css

BashLib CSS tooling

This is a set of tools specifically for facilitating interactions with the Community Solid Server API.

It provides a core set of functionality for creating data pods on a css instance and creating a client credentials token on a Community Solid Server instance, as well as a set of authentication options for Node.JS.

Installing

npm run build;

Functionality

Pod creation

compatibility: CSSv2.0.0 - current

This tool automatically creates a new Solid account and accompanying data pod on a Community Solid Server (CSS) instance. The CSS instance must be configured to allow multiple users to register (editable in the startup options of the server).

CLI

The create-pod command creates a new Solid account and data pod on a given CSS instance. The command triggers an interactive prompt if not all option values are passed.

node bin/css.js create-pod [options]

options

  -b, --base-url <string>      Base URL of the pod server.
  -n, --name                   Name for the newly created Solid account.
  -e, --email <string>         Email adres for the user. Default to <name>@test.edu
  -p, --password <string>      User password. Default to <name>

Node.JS usage

The Node.JS interface provides the createPods function that initializes a Solid account on the given CSS instance for each account .

include { createPods } from '/install/location'

// An array containing the information of the accounts to be create on the CSS instance
let accounts = [
  { // Account 1
    "name": "Bob",
    "email": "Bob@test.edu",
    "password": "BobsVerySecurePassword",
  }, 
  { // Acount 2
    "name": "Carol",
  }
]

// CSS instance base URL
let baseUrl = "https://localhost:3000/"

// Create the requested accounts on the CSS instance
await createPods(baseUrl, accounts)

Client Credentials Token generation

compatibility: CSSv4.0.0 - current

As of version 4 of the Community Solid Server, support was added for authentication using Client Credentials tokens. Such a token can be generated by the user for their Solid account on their CSS pod provider. A generated token can be permanently used to create new access tokens, without requiring the user credentials or an interactive browser session again to authenticate the user. This module handles the creation and storage of this token, as well as some additional useful information for building an authenticated fetch function using this token.

CLI

The create-token command creates a new Client Credentials token for your data pod on your local filesystem. This command provides an interactive prompt if not all option values are given.

node bin/css.js create-token [options]

options

  -i, --idp <string>       URL of your identity provider (= baseURI of your CSS server)
  -n, --name <string>      Token name
  -e, --email <string>     User email
  -p, --password <string>  User password
  -w, --webId <string>     User webId (optional)
  -o, --out <string>       Token file location (defaults to ~/.solid/.css-auth-token)
  -v, --verbose            Log actions

Node.JS

The Node.JS interface provides identical functionality to the CLI interface.

  import { generateClientCredentialsToken } from "/install/location"
  
  let options = {
    name: string,                                  // The name of the token, used for matching and removing auth tokens.
    email: string,                                 // The user email
    password: string,                              // The user password
    idp: string,                                   // URL of your identity provider (= baseURI of your CSS server)
    clientCredentialsTokenStorageLocation?: string // (optional) Storage location of the stored client credentials token (defaults to ~/.solid/.css-auth-token).
  }
  
  // Returns the location of the newly generated Client Credentials token.
  let storageLocation = await generateClientCredentialsToken(options);

Creating an authenticated fetch

These modules provides a set of functions to create an authenticated fetch function to interact with resources on a Solid data pod. This functionality is developed for testing purposes in the Community Solid Server ecosystem. We advise against using these in production environments, and refer to the Inrupt developer tools for authentication.

Interactive

compatbility: universal

This module provides an interactive authentication flow using the browser according to the Inrupt Node.JS authentication flow. This implementation stores the session info on disk (default location: ~/.solid/.session-info-interactive), to reuse the existing session in subsequent application calls, to support usecases where the application is run multiple times per minute without requiring the user to redo the browser authentication step every time.

import SolidFetchBuilder from "/install/location"

const builder = new SolidFetchBuilder();
let options = {
  idp: string,                          // Solid identity provider
  sessionInfoStorageLocation?: string,  // (optional) Session info storage (default: ~/.solid/.session-info-interactive).
  port?: number,                        // (optional) Port used for redirect url of OIDC login flow
  verbose?: boolean,                    // (optional) Log authentication errors
}
builder.buildInteractive(options);
let fetch = builder.getFetch()
// OR let {fetch, webId} = builder.getSessionInfo();

From Client Credentials token

compatibility: CSSv4.0.0 - current

This module builds an authenticated Fetch function given a client credentials token, that can be generated using the client credentials token generation module module. Client Credentials tokens are only available for the Community Solid Server from v4.x.x and onwards. This module also stores the session information on disk, so subsequent runs of the application do not have to redo the authentication flow on every run (per default this information is stored in: ~/.solid/.session-info-interactive)

import SolidFetchBuilder from "/install/location"

const builder = new SolidFetchBuilder();
let options = {
  idp?: string,                                    // (optional) Solid identity provider - this value is stored in the generated token
  clientCredentialsTokenStorageLocation?: string,  // (optional) Storage location of the stored client credentials token (defaults to ~/.solid/.css-auth-token).
  sessionInfoStorageLocation?: string,             // (optional) Storage location of session information to reuse in subsequent runs of the application (defaults to ~/.solid/.session-info-token).
  verbose?: boolean,                               // (optional) Log authentication errors
}
builder.buildFromClientCredentialsToken(options);
let fetch = builder.getFetch()
// OR let {fetch, webId} = builder.getSessionInfo();

From User Credentials

compatibility: CSSv2.x.x

deprecated - Older version of CSS and requires user credentials, please use token based authentication flow instead.

This module builds an authenticated fetch function given user credentials. This auth module hijacks the browser authentication flow for the Community Solid Server, and only works with v2.x.x of the CSS! (This module does not store session information, and re-authenticates on every subsequent run of the application using it)

import SolidFetchBuilder from "/install/location"

const builder = new SolidFetchBuilder();
let options = {
  idp: string,       // Solid identity provider
  email: string,     // User email
  password: string,  // User password
  port?: number,     // (optional) Port used for redirect url of OIDC login flow
  verbose?: boolean, // (optional) Log authentication errors
}
builder.buildFromUserCredentials(options);
let fetch = builder.getFetch()
// OR let {fetch, webId} = builder.getSessionInfo();