fission-sdk

Fission SDK

Fission provides app hosting with user controlled data. We’re building a web native file system that combines files, encryption, and identity, like an open source iCloud.

Get started making fission-enabled apps with the Fission SDK!

What you'll find here

The Fission SDK offers tools for:

• managing a user's web native file system
• managing a user's private keys
• authenticating & authorizing user actions

You'll also find some helper functions for interacting with some of the building blocks:

• js-ipfs for distributed file storage
• keystore-idb for key management, encryption & digital signatures

File System

The Web Native File System (WNFS) is built on top of IPFS. It's structured and functions similarly to a Unix-style file system, with one notable exception: it's a Directed Acyclic Graph (DAG), meaning that a given child can have more than one parent (think symlinks but without the "sym").

Each file system has a public tree and a private tree. All information (links, data, metadata, etc) in the private tree is encrypted. Decryption keys are stored in such a manner that access to a given folder grants access to all of its subfolders.

Basics

WNFS exposes a familiar POSIX-style interface:

• ls: list a directory
• mkdir: create a directory
• add: add a file
• cat: retrieve a file

Versions

Since the file system may evolve over time, a "version" is associated with each node in the file system (tracked with semver)

Currently two versions exist:

• 1.0.0: file tree with metadata. Nodes in the file tree are structured as 2 layers where one layer contains "header" information (metadata, cache, etc), and the second layer contains data or links. This is the default version, use this unless you have a good reason not to
• 0.0.0: bare file tree. The public tree is ipfs dag-pg nodes. The private tree is encrypted links with no associated metadata. These shuld really only be used for vanity links to be rendered by a gateway.

API

Config

Each instantiation method takes an optional config. Below is the default config and descriptions of each value.

const defaultConfig = {
  keyName: 'filesystem-root', // the name of the key for the filesystem root as stored in IndexedDB
  version: '1.0.0' // the version of the filesystem as discussed above
}

---

Instantiation

empty

Creates a file system with an empty public tree & an empty private tree at the root

Params:

• cfg: FileSystemConfig optional

Returns: FileSystem instance

Example:

import FileSystem from 'fission-sdk/fs'
const wnfs = await FileSystem.empty()

---

fromCID

Loads an existing file system from a CID

Params:

• cid: CID (string) required
• cfg: FileSystemConfig optional

Returns: FileSystem instance

Example:

import FileSystem from 'fission-sdk/fs'
const cid = "QmWKst5WVNTPfMsSFCQEJYBJLEsUZfghqrKXJBVU4EuA76"
const wnfs = await FileSystem.empty(cid)

---

forUser

Loads an existing file system from a username

Params:

• username: string required
• cfg: FileSystemConfig optional

Returns: FileSystem instance

Example:

import FileSystem from 'fission-sdk/fs'
const wnfs = await FileSystem.foruser("boris")

---

Methods

Methods for interacting with the filesystem all use absolute paths. We're planning on adding a stateful session but for now, filesystem state will need to be tracked in your application.

ls

Returns a list of links at a given directory path

Params:

• path: string required

Returns: Links[] list of links

Example:

// public
const links = await wnfs.ls("public/some/directory/path")
// private
const links = await wnfs.ls("private/some/directory/path")

---

mkdir

Creates a directory at the given path

Params:

• path: string required

Returns: CID the updated root CID for the file system

Example:

const updatedCID = await wnfs.mkdir("public/some/directory/path")
// creates a directory called "path" at "public/some/directory"

---

add

Adds some file content at a given path

Params:

• path: string required
• content: FileContent (object | string | Blob | Buffer) required

Returns: CID the updated root CID for the file system

Example:

const content = "hello world"
const updatedCID = await wnfs.add("public/some/path/to/a/file", content)
// creates a file called "file" at "public/some/path/to/a"

---

cat

Retrieves some file content at a given path

Params:

• path: string required

Returns: FileContent (object | string | Blob | Buffer)

Example:

const content = await wnfs.cat("public/some/path/to/a/file")

---

get

Retrieves the node at the given path, either a File or Tree object

Params:

• path: string required

Returns: Tree | File | null

Example:

const node = await wnfs.get("public/some/path")

---

sync

Ensures the latest version of the file system is added to IPFS and returns the root CID

Params: none

Returns: CID the updated root CID for the file system

Example:

const rootCID = await wnfs.sync()

---

pinList

Retrieves an array of all CIDs that need to be pinned in order to backup the FS.

Params: none

Returns: CID[]

Example:

const allCIDs = await wnfs.pinList()

Users & Key

🚧 Under Construction 🚧

Building Blocks

Warning: Here be 🐉! Only use lower level utilities if you know what you're doing.

This library is built on top of js-ipfs and keystore-idb. If you have already integrated an ipfs daemon or keystore-idb into your web application, you probably don't want to have two instances floating around.

You can use one instance for your whole application by doing the following:

import ipfs from 'fission-sdk/ipfs'

// get the ipfs instance that the Fission SDK is using
const ipfs = await ipfs.getIpfs()

// OR set the ipfs to an instance that you already have
await ipfs.setipfs(ipfsInstance)

import keystore from 'fission-sdk/keystore'

// get the keystore instance that the Fission SDK is using
const ks = await keystore.getKeystore()

// OR set the keystore to an instance that you already have
await keystore.setKeystore(keystoreInstance)

Development

# install dependencies 
yarn
 
# run development server 
yarn start
 
# build 
yarn build
 
# test 
yarn test
 
# test w/ reloading 
yarn test:watch
 
# publish (run this script instead of npm publish!) 
./publish.sh