Solid-Node-Client

-- a nodejs client for Solid --

This library uses solid-auth-fetcher to provide session management and fetching for https: URLs and uses solid-rest to provide solid-like fetches on file: and other non-http URLs. It supports login and authenticated fetches to NSS servers. Support for login to other servers will be added in the future.

As of version 1.2.0, solid node client now supports multiple logins from the same script. See below for details

Synopsis

Stand alone usage :

import { SolidNodeClient } from 'solid-node-client';
const client = new SolidNodeClient();

async function main(){
    let response = await client.fetch('https://example.com/publicResource');
    console.log(await response.text())
    let session = await client.login();
    if( session ) {
        console.log (`logged in as <${session.webId}>`);
        response = await client.fetch('https://example.com/privateResource');
        console.log(await response.text())
        logout();
    }    
}

Usage with rdflib :

import {SolidNodeClient} from 'solid-node-client';
import * as $rdf from 'rdflib';
global.$rdf = $rdf;
const client = new SolidNodeClient();
const store   = $rdf.graph();
const fetcher = $rdf.fetcher(store,{fetch:client.fetch.bind(client)});  
    // now all rdflib methods support file:// requests in nodejs

async function main(){
    let session = await login();  // may be omitted if you don't need authentication
    // now all rdflib methods support authenticated http: requests in nodejs
}

Installation

1. install the app

  npm install

2. give the app permission

Skip this step if you don't need authenticated access to a pod. To get authenticated access to a pod, you will need to add "https://solid-node-client" as a trusted app on that pod or the portion of it you want to access. See how to make an app trusted for how to do this.

Methods

login(options)

Logs the user in to a Solid pod and returns an authenticated session. Credentials for the login may be set as environment variables in your operating system or passed in the options.

If these variables are part of your environment, you can use the login() method without arguments.

• SOLID_IDP // the server root e.g. https://solidcoummunity.net (no trailing slash)
• SOLID_USERNAME // your username on the server
• SOLID_PASSWORD // your password on the server
• SOLID_DEBUG // set this if you want to output extended login and session debugging

If you don't have those environment variables set or if you wish to override them, you can set them in the arguments to login().

   let session = await client.login({
       idp : "https://yourIdentityProvider",
       username : "yourUsername",
       password : "yourPassword",
       debug : true // or false
   });

The session object returned will be a solid-auth-fetcher Session object which has properties loggedIn and webId. See the solid-auth-fetcher docs for further details if you need them.

logout()

Logs the user out. This means that authenticated fetches are no longer possible but you can still use unauthenticated fetches.

fetch()

This method performs CRUD operations as specified in the Solid REST spec. When used with file: URLs, most of the REST spec is followed and, as with http: URLs, the return value is a Response object containing fields such status and statusText and methods such as text(), json(), and headers.get(). See the solid-rest docs for details of how file: URLs are handled.

Here's an example :

// write a resource
let writeResponse = await client.fetch( 'https://example.com/file.text', {
  method : "PUT",
  body : "some content to go in the resource",
  headers : { "Content-type" : 'text/plain' }
}
console.log( writeResponse.status  );  // 201
// now read it
let readResponse = await client.fetch( 'https://example.com/file.text' );
// display its contents
console.log( await response.text()  );

Note about Patch

PATCH is supported by solid-node-client, but only if your script imports rdflib and set the global.$rdf variable. The syntax for PATCH is the same as in rdflib.

import {SolidNodeClient} from 'solid-node-client';
import * as $rdf from 'rdflib';
global.$rdf = $rdf;
const client = new SolidNodeClient();
// client.fetch() now supports PATCH on file: URLs and all solid-rest backends

Multiple Identities

It is now possible to login multiple times from the same script. You can create clients authorized for several different identities.

  const client_1 = new SolidNodeClient();
  const client_2 = new SolidNodeClient();
  const client_3 = new SolidNodeClient();
  await client_1.login( siteA_credentials);
  await client_2.login( siteB_credentials);
  // now client_1 is authenticated at siteA;
  //     client_2 is authenticated at siteB;
  //     client_3 is unauthenticated
}

Acknowledgements

All of the session management is from Jackson Creed's solid-auth-fetcher. The login is from Michiel de Jong's solid-crud-tests.

Copyright and License

copyright © 2020, Jeff Zucker, may be freely distributed with the MIT license