Comment on page
💽
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.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.
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
object
import { SSX } from '@spruceid/ssx';
const ssx = new SSX({
modules: {
storage: true
},
});
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 |
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).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();
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.',
});
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');
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');
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');
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');
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();
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();
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');
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');
Last modified 4mo ago