Sharing Links - TinyCloud

Sharing links provide read-only access to one KV key without requiring the recipient to have a TinyCloud account. The SDK packages a scoped delegation and an ephemeral private key into a tc1: bearer token.

Store data and generate a link

The generating SDK instance must be signed in and have delegation capability.

const stored = await tc.kv.put("my-document", {
  title: "Project notes",
  body: "Next review is Friday.",
});
if (!stored.ok) throw new Error(stored.error.message);

const shared = await tc.sharing.generate({
  path: "my-document",
  expiry: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
});
if (!shared.ok) throw new Error(shared.error.message);

const shareUrl = shared.data.url;
console.log(shareUrl);

sharing.generate() is available from both the Node and Web SDKs. By default, the generated delegation grants tinycloud.kv/get and tinycloud.kv/metadata for the selected key.

Receive the same key

Browser recipients can retrieve the shared value with the static helper. They do not create an SDK instance or call signIn().

import { TinyCloudWeb } from "@tinycloud/web-sdk";

const received = await TinyCloudWeb.receiveShare<{
  title: string;
  body: string;
}>(shareUrl);

if (!received.ok) throw new Error(received.error.message);
console.log(received.data.path);       // "my-document" (with any app prefix)
console.log(received.data.data.title); // "Project notes"

The helper reads the path embedded in the link unless the caller explicitly passes a different key. For a single-key sharing flow, do not substitute an unrelated key at receive time.

What the link contains

schema version 1
the full shared KV path
the TinyCloud host and owner space ID
a signed read delegation
a private JWK for the generated share principal

Anyone who has the URL can exercise the embedded authority until it expires or the delegation is revoked. Do not log sharing links or put them in analytics, referrer URLs, or public issue trackers.

End access early

Keep the generated delegation CID if the owner may need to revoke the link:

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

Use short expiries as a second limit. A new link creates a new share principal and delegation; it does not extend the old link.

When to use a delegation instead

Use a sharing link for a one-click, read-only handoff of a single value. Use a normal delegation when the recipient has a persistent identity, needs several paths or actions, or may sub-delegate.

​Store data and generate a link

​Receive the same key

​What the link contains

​End access early

​When to use a delegation instead

Store data and generate a link

Receive the same key

What the link contains

End access early

When to use a delegation instead