Lobby

Authorization

The auth lobby grants apps authorization to access WNFS. Apps request permission to use App Storage and additional public and private directories. The auth lobby creates a User Controlled Authorization Networks (UCAN) token that reflects the requested permissions.

Webnative checks the UCAN at initialization and returns an auth scenario.

• AuthSucceded. The user has just returned from the auth lobby, and they granted the requested permissions.

• Continuation. The user has already granted permission, and the UCAN has not expired.

• AuthCancelled. The user denied the requested permissions.

• NotAuthorised. The user has not granted permission yet or the UCAN has expired.

UCANs expire and users must periodically re-authorize apps through the auth lobby. All user data is preserved in WNFS across authorizations, including the data stored in App Storage.

Shared devices

In most cases, users will not need to log out of an app or a device. Read more about this part of our vision for Fission-enabled apps in the What does “log in” or “log out” mean for the Fission SDK and apps? blog post.

One case where logging out is desirable is on a shared device. Logging out on a shared device can be accomplished in two steps:

• Remove the UCAN token from apps that were granted permissions with the webnativewn.leave function

• Log out from the auth lobby on the reset page (https://auth.fission.codes/reset/)

File System

Permissions

Every file system action checks if an app has received sufficient permissions from the user. Apps request permissions when they initialize webnative, and the auth lobby grants authorization.

Apps request permission for App Storage, additional private and public directories, and user apps published with the Platform APIs. For example, and notes app might request these permissions.

permissions: {
  app: {
    name: "Notes",
    creator: "Fission"
  },
  fs: {
    privatePaths: [ "Notes" ],
    publicPaths: [ "Notes" ]
  },
  platform: {
    apps: []
  }
}

The app would have access to its App Storage and shared public and private Notes directories.

The initialize function will return a NotAuthorised scenario if one of the UCAN will expire in one day to minimize the likelihood of receiving an expired permissions error. But to be safe, apps should also account for this error.

Web Worker

Can I use my file system in a web worker? Yes, this only requires a slightly different setup.

// UI thread
// `state.fs` will now be `null`
const { permissions } = wn.initialise({ loadFileSystem: false })
worker.postMessage({ tag: "LOAD_FS", permissions })
​
// Web Worker
let fs
​
self.onMessage = async event => {
  switch (event.data.tag) {
    case "LOAD_FS":
      fs = await wn.loadFileSystem(event.data.permissions)
      break;
  }
}

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 consists of ipfs dag-pg nodes. The private tree is encrypted links with no associated metadata. These should really only be used for vanity links to be rendered by a gateway.