💽Storage Module

The Storage module, accessible via ssx.storage, provides functionality to store and retrieve data in Kepler. Kepler is architected as a decentralized storage system that uses DIDs and Authorization Capabilities to define where your data lives, and who has access. Any DID controller (e.g. people, applications, DAOs) can administer their own Kepler Orbit.

Background

Some of the functions for the KeplerStorage Module are written in Rust and made available to the SDK through WebAssembly. This allows for a more secure and performant implementation of these functions using SpruceID's audited Rust libraries.

Getting Started

By using Kepler via the storage module within SSX, you hereby agree to the Kepler Developer Terms found here.

To use the storage module within SSX, you will need to configure the modules parameter in the SSX configuration object.

modules: {
    settings?: boolean | SSXStorageModuleConfig;
};

SSXStorageModuleConfig: {
    prefix?: string;
    hosts?: Array<string>;
    autoCreateNewOrbit?: boolean;
};

Below is an example of initializing a SSX instance with the storage enabled:

boolean

import { SSX } from '@spruceid/ssx';

const ssx = new SSX({
  modules: {
    storage: true
  },
});

object

import { SSX } from '@spruceid/ssx';

const ssx = new SSX({
  modules: {
    storage: {
      prefix: 'app-prefix',
      hosts: ['https://kepler.spruceid.xyz'],
      autoCreateNewOrbit: true,
    },
  },
});

Below are descriptions of the configuration parameters for the storage module:

Parameter	Type	Description	default
prefix	string	A prefix to be used for all keys stored in the storage service.	''
hosts	string[]	A list of Kepler hosts to use for the storage service.	['https://kepler.spruceid.xyz']
autoCreateNewOrbit	boolean	A flag to indicate whether to create a new orbit if one does not exist. If this is off, a createOrbit call must happen for the user to have an orbtit created.	true

Orbit Creation (Optional)

Orbits are the namespace that is created by a user to store data. They are the source of authority in their orbit — they authorize other dids and keys to read and write data to their orbit.

You'll need to create an orbit to store data for your user. If you've configured the autoCreateNewOrbit parameter to true, then an orbit will be created automatically when you sign in, if a user does not have one. If you've configured it to false, then you'll need to manually create an orbit (see activateSession and hostOrbit methods).

Methods

activateSession

Checks if an orbit exists for the user.

activateSession = (
    session?: SSXClientSession, 
    onError?: () => void
) => Promise<boolean>;

Here is an example of how to use it:

const orbitExists = await ssx.storage.activateSession();

delegate

Delegates the stored data.

delegate = (
  /** The target file or folder you are sharing */
  target: string;
  /** The DID of the key you are delegating to. */
  delegateDID: string;
  /** The actions you are authorizing the delegate to do. */
  actions: Array<string>;
  /** The statement in the SIWE message */
  statement?: string;
) => Promise<DelegateResponse>;

type DelegateResponse = {
  /** The contents of the SIWE message */
  siwe: string;
  /** The signature of the SIWE message */
  signature: string;
  /** The version of the delegation issued */
  version: number;
};

Here is an example of how to use it:

const delegateResponse = await ssx.storage.delegate({
    target: 'myOrbitId/kv/path',
    delegateDID: 'delegateDID',
    actions: ['get', 'metadata'],
    statement: 'I am giving permission to read this data.',
});

delete

Deletes the stored value associated with a specific key.

delete = (
  key: string,
  options?: {
    prefix?: string, // Default to the prefix informed in the constructor
    request?: Request
  }
) => Promise<Response>;

Here is an example of how to use it:

await ssx.storage.delete('your_key_here');

deleteAll

Deletes all stored key-value pairs in the storage.

The prefix parameter is optional. If given, it will delete all data in that prefix. Default to empty string.

deleteAll = (prefix?: string) => Promise<Response>;

Here is an example of how to use it:

await ssx.storage.delete('your_key_here');

get

Gets the stored value associated with a specific key.

get = (
  key: string,
  options?: {
    prefix?: string, // Default to the prefix informed in the constructor
    request?: Request
  }
) => Promise<Response>;

Here is an example of how to use it:

const { data } = await ssx.storage.get('your_key_here');

generateSharingLink

Generates a link pointing to stored content.

generateSharingLink = (
  path: string
) => Promise<string>;

Here is an example of how to use it:

const shareBase64 = await ssx.storage.generateSharingLink('your_key_here');

hostOrbit

Creates an orbit for the user manually.

hostOrbit = (session?: SSXClientSession) => Promise<void>;

Here is an example of how to use it:

const orbit = await ssx.storage.hostOrbit();

list

Lists all the keys currently stored.

list = (
  options?: {
    prefix?: string, // Default to the prefix informed in the constructor
    path?: string, // Identifies the path to be combined with the prefix
    removePrefix?: boolean, // Removes or not the prefix from the file names
    request?: Request
  }
) => Promise<Response>;

Here is an example of how to use it:

const { data } = ssx.storage.list();

put

Stores a value with a specific key.

put = (
  key: string,
  value: any,
  options?: {
    prefix?: string, // Default to the prefix informed in the constructor
    request?: Request
  }
) => Promise<Response>;

Here is an example of how to use it:

await ssx.storage.put('your_key_here', 'data_here');

retrieveSharingLink

Retrieves content given a shareBase64 string.

retrieveSharingLink = (
  encodedShare: string
) => Promise<Response>;

Here is an example of how to use it:

const data = await ssx.storage.retrieveSharingLink('shareBase64');