Delegations & Sharing

Use this guide to grant another signed-in TinyCloud principal access to a path in your space. In the examples, alice and bob are SDK instances that have already completed signIn().

Create and use a delegation

Use the recipient’s owner DID. After wallet sign-in, bob.did is that owner DID; bob.sessionDid identifies the ephemeral session key instead.

const delegation = await alice.createDelegation({
  delegateDID: bob.did,
  path: "shared/",
  actions: ["tinycloud.kv/get", "tinycloud.kv/put"],
  expiryMs: 7 * 24 * 60 * 60 * 1000,
});

// Deliver `delegation` to Bob through your authenticated application channel.
const access = await bob.useDelegation(delegation);
const value = await access.kv.get("document.json");

if (!value.ok) throw new Error(value.error.message);
console.log(value.data.data);

useDelegation() returns a DelegatedAccess handle for the delegator’s space. Its KV service is already rooted at shared/, so its keys are relative to that delegated path. It does not copy the data into the recipient’s space.

Serialize for transport

createDelegation() returns a PortableDelegation object. To send it as text, use the SDK helpers instead of manually converting its Date fields:

import {
  serializeDelegation,
  deserializeDelegation,
} from "@tinycloud/node-sdk";

const payload = serializeDelegation(delegation);
// Send `payload` through an authenticated channel.

const received = deserializeDelegation(payload);
const receivedAccess = await bob.useDelegation(received);

The same helpers are exported by @tinycloud/web-sdk for browser applications. The serialized delegation is a bearer credential; do not log it or send it through an untrusted channel.

Narrow access further

If the parent permits sub-delegation, Bob can grant Carol a narrower subset:

const child = await bob.createSubDelegation(delegation, {
  delegateDID: carol.did,
  path: "shared/public/",
  actions: ["tinycloud.kv/get"],
  expiryMs: 24 * 60 * 60 * 1000,
});

The child must stay within the parent’s resources and action set, cannot outlive the parent, and cannot bypass a parent’s sub-delegation restriction. Without expiryMs, createSubDelegation defaults to the longest lifetime the parent allows. Sessions activated from a received delegation default the same way.

Block further delegation

createSubDelegation() signs with the wallet, so it cannot set disableSubDelegation; passing true throws. To issue a grant the recipient cannot pass on, use createDelegation() with disableSubDelegation: true and address it to the recipient’s session-key did:key, not its did:pkh owner DID. Here carolSession is a client without a wallet signer. Its credentialHolderDid is the bare did:key session-key DID; use it rather than carolSession.did, which carries a #fragment that createDelegation rejects as an invalid audience DID:

const terminal = await alice.createDelegation({
  delegateDID: carolSession.credentialHolderDid,
  path: "shared/public/",
  actions: ["tinycloud.kv/get"],
  disableSubDelegation: true,
});

const access = await carolSession.useDelegation(terminal);

The delegation carries the node’s terminal marker, so the node refuses any delegation that cites it as a parent. A recipient in wallet mode chains a new session from the grant, which the node refuses for a terminal parent, so createDelegation() throws if disableSubDelegation is combined with a did:pkh recipient. Drop the flag for a wallet recipient.

Revoke access

Both the Node and Web SDKs expose revokeDelegation():

const revoked = await alice.revokeDelegation(delegation.cid);
if (!revoked.ok) throw new Error(revoked.error.message);

Revocation is node-confirmed and invalidates use of that delegation. Revoking an ancestor also prevents its descendants from being used. The Node SDK can query the node-confirmed lifecycle state:

const status = await alice.getDelegationStatus(delegation.cid);
if (status.ok) console.log(status.data.status); // "revoked"

Delegations also stop working at their signed expiry. Expiry limits exposure, but it is not a substitute for revokeDelegation() when access must end now.

Inspect received grants

The Node SDK records delegations installed by useDelegation():

const receivedDelegations = bob.delegations.list();
const oneDelegation = bob.delegations.get(delegation.cid);

For the SDK transport fields and the node’s validation model, see Delegations.

Quickstarts

Authentication and data

Collaboration and extensions

Delegations & Sharing

Create and use a delegation

Serialize for transport

Narrow access further

Block further delegation

Revoke access

Inspect received grants

​Create and use a delegation

​Serialize for transport

​Narrow access further

​Block further delegation

​Revoke access

​Inspect received grants

Create and use a delegation

Serialize for transport

Narrow access further

Block further delegation

Revoke access

Inspect received grants