@tinycloud/share-sdk 1.4.4 → 1.5.0-beta.1

package/README.md

@@ -23,25 +23,22 @@ import {
 // 1. Plan, before anything is written. The network must be the owner's default network with the EIP-55 checksummed address.
 const plan = planPathBoundShare({ shareId, encryptionNetwork: defaultEncryptionNetworkForOwner(ownerDid) });
 
-// 2. Hold two capabilities. (a) decrypt under `<network>/share/` (`plan.registrationPermissions`): the node refuses to register the share
-//    unless the owner holds it; a bare-network decrypt never covers a share key. (b) `key.create` for the share's key, by ONE of:
-//      - `plan.sessionPermissions` in the manifest the owner signs in with (decrypt + key.create on `<network>/share/`, no prompt per
-//        share; needs a sign-in route that signs these, for example `signMessage` from a first-party origin), or
-//      - `await tcw.requestPermissions(plan.requiredPermissions)` per share (one consent per share).
-//    Without it, `encryptAddressedShareContent` throws `key-not-authorized`. Every created key permanently uses one of the node's 1000 key slots per
-//    network (deleted keys count, and the count is shared with `apps/` keys): each shared file uses one slot, so validate everything first
-//    (`planPathBoundShare` refuses a bad share id or network before any key exists). A failure after the key exists still costs the slot and there
-//    is no key delete: retry with a NEW shareId.
+// 2. Hold decrypt under `<network>/share/` (`plan.registrationPermissions`, or `pathBoundSessionPermissions({ encryptionNetwork })` in the
+//    sign-in manifest, before any share exists): the node refuses to register the share unless the owner
+//    holds it; a bare-network decrypt never covers a share key. No capability is needed to encrypt: the share's key is deterministic and
+//    `keys.encrypt` wraps to its public key, which the node serves without authentication. The node records the key when the share policy
+//    is registered (step 5), in the same transaction. Each published share adds one key record, which counts toward the network's key limit
+//    (shared with `apps/` keys); `planPathBoundShare` refuses a bad share id or network before anything is encrypted.
 //    The share id is ONE grammar everywhere (plan, size bound, publisher): `[a-z0-9][a-z0-9_-]{15,63}` (16 to 64 characters; a lowercase `randomUUID()`,
 //    with or without its hyphens, is valid). Uppercase, `.`, a leading `_` or `-`, and anything longer than 64 characters are refused.
 
-// 3. Create the key and encrypt under it (`keys` is a named-key client: `tcw.keys`, `node.keys` or `NamedKeyClient`).
+// 3. Encrypt under the share's key (`keys` is a named-key client: `tcw.keys`, `node.keys` or `NamedKeyClient`).
 const encrypted = await encryptAddressedShareContent({ plan, keys, plaintext, metadata: { contentType } });
 
 // 4. Store EXACTLY encrypted.storedBytes (the canonical v2 envelope) at the share's path.
 await put(path, encrypted.storedBytes);
 
-// 5. Bind and publish.
+// 5. Bind and publish. Registering the policy records the share's key.
 const contentSource = bindPathBoundContentSource({
   plan, envelope: encrypted.envelope, storedBytes: encrypted.storedBytes, kvResource: `${spaceId}/kv/${path}`, selector: "exact",
 });
@@ -50,4 +47,4 @@ await publishAddressedShare({ /* shareId, target, resource, actions, ... */ cont
 
 `publishAddressedShare` refuses a content source that is not bound to its own share's key (`AddressedContentSourceError`, match on `code`: `key-path-required`, `key-path-mismatch`, `digest-invalid`, `network-invalid`) before it signs, registers or writes anything; there is no network-wide fallback. Do not call `encryptToNetwork` with a `keyPath` for a share: it returns a v1 envelope wrapped to the network key, which neither the node nor the recipient opens. `assertAddressedShareFits` and `addressedShareBodyUpperBound` derive the key path from `shareId`. Opening an older share that has no key path is unchanged.
 
-`pathBoundSessionPermissions({ encryptionNetwork })` returns the one manifest entry for the sign-in route (`decrypt` + `key.create` on `<network>/share/`) without needing a share id; build both your manifest and any scope guard of your own from it. Hand-written content sources are not supported: the publisher checks the path, the digest's format and the network, but only `bindPathBoundContentSource` derives the raw-byte digest the recipient and the node compare.
+Hand-written content sources are not supported: the publisher checks the path, the digest's format and the network, but only `bindPathBoundContentSource` derives the raw-byte digest the recipient and the node compare.

package/dist/{addressed-publish-DorqWQJ8.d.ts → addressed-publish-D4IWNXuw.d.ts}

@@ -9,11 +9,11 @@ import { S as ShareAuthorizationRequired, a as ShareAuthorizationMethod } from '
  * opens only that one key, never the network. This module is the single place that derives the path, validates the
  * network, serializes the stored envelope and computes the digests, so no consumer hand-writes any of them.
  *
- * Call sequence: `planPathBoundShare` (before anything is written) -> the caller holds the plan's `requiredPermissions`
- * -> `encryptAddressedShareContent` (or the caller's own `keys.createKey` + `keys.encrypt`) -> upload `storedBytes` ->
- * `bindPathBoundContentSource` -> `publishAddressedShare`.
+ * Call sequence: `planPathBoundShare` (before anything is written) -> `encryptAddressedShareContent` (or the caller's own
+ * `keys.encrypt`, which encrypts to the key's public key) -> upload `storedBytes` -> `bindPathBoundContentSource` ->
+ * `publishAddressedShare`. The node records the share's key when the policy is registered; nothing creates it beforehand.
  */
-type AddressedContentSourceErrorCode = "share-id-invalid" | "network-invalid" | "network-not-checksummed" | "key-path-required" | "key-path-mismatch" | "digest-invalid" | "key-not-authorized" | "key-receipt-mismatch" | "envelope-invalid" | "stored-bytes-mismatch";
+type AddressedContentSourceErrorCode = "share-id-invalid" | "network-invalid" | "network-not-checksummed" | "key-path-required" | "key-path-mismatch" | "digest-invalid" | "envelope-invalid" | "stored-bytes-mismatch";
 /** A path-bound source could not be planned, built or accepted. Match on `code`, not the message or `instanceof`. */
 declare class AddressedContentSourceError extends TypeError {
     readonly code: AddressedContentSourceErrorCode;
@@ -56,18 +56,7 @@ interface PathBoundSharePlan {
     readonly keyPath: string;
     /** `<network>/share/<shareId>`: the one decrypt resource the share grants. */
     readonly keyResource: string;
-    /**
-     * ROUTE A, per share at runtime: `key.create` on exactly this share's key, requested with `requestPermissions` before the key is created
-     * (one extra consent per share). For apps that cannot use the sign-in route (for example apps whose sign-in goes through the OpenKey widget
-     * `authorizeTinyCloud` route, which refuses decrypt and key.create outside `apps/`).
-     */
-    readonly requiredPermissions: PathBoundPermissionEntry[];
-    /**
-     * ROUTE B, once at sign-in (manifest entries): `key.create` and `decrypt` on the default network's `<network>/share/` prefix, so every share's
-     * key can be created without a further prompt. Put these in the `permissions` of the manifest the owner signs in with.
-     */
-    readonly sessionPermissions: PathBoundPermissionEntry[];
-    /** The owner session must hold these for the node to register the policy: decrypt under `<network>/share/` (also part of `sessionPermissions`). */
+    /** The owner session must hold these for the node to register the policy: decrypt under `<network>/share/`. */
     readonly registrationPermissions: PathBoundPermissionEntry[];
     /** Options for `keys.encrypt(plan.keyPath, plaintext, plan.encryptOptions({ metadata }))`. */
     encryptOptions(extra?: {
@@ -78,8 +67,8 @@ interface PathBoundSharePlan {
     };
 }
 /**
- * The manifest entries (route B, sign-in) that let one session create every share's key: `decrypt` and `key.create` on the default network's
- * `<network>/share/` prefix. Needs no share id, so an app builds its manifest before any share exists. Put the result in `manifest.permissions`.
+ * The manifest entries that let one session register every share's policy: `decrypt` on the default network's `<network>/share/` prefix.
+ * Needs no share id, so an app builds its sign-in manifest before any share exists. Put the result in `manifest.permissions`.
  */
 declare function pathBoundSessionPermissions(input: {
     readonly encryptionNetwork: string;
@@ -114,14 +103,6 @@ declare function bindPathBoundContentSource(input: {
 }): PathBoundContentSource;
 /** The part of a named-key client (`NamedKeyClient`, web `tcw.keys`, node `node.keys`) this module calls. */
 interface AddressedShareKeyClient {
-    createKey(path: string, options: {
-        networkId: string;
-    }): Promise<{
-        readonly networkId: string;
-        readonly keyPath: string;
-        readonly state?: string;
-        readonly keyVersion?: number;
-    }>;
     encrypt(path: string, plaintext: Uint8Array, options: {
         networkId: string;
         metadata?: Record<string, string>;
@@ -134,9 +115,8 @@ interface EncryptedAddressedContent {
     readonly byteLength: number;
 }
 /**
- * Create the share's named key and encrypt the content under it. Built from the same steps a consumer may run itself
- * (`keys.createKey`, `keys.encrypt`, then `bindPathBoundContentSource`). The key-create capability in
- * `plan.requiredPermissions` must already be held; an unauthorized answer is reported as `key-not-authorized` naming it.
+ * Encrypt the content under the share's named key. `keys.encrypt` wraps to the key's public key, which the node serves without
+ * authentication; the key needs no record yet (the node records it when the share policy is registered).
  */
 declare function encryptAddressedShareContent(input: {
     readonly plan: PathBoundSharePlan;

package/dist/{addressed-publish-BPFFqD5s.d.cts → addressed-publish-qp_bEVYu.d.cts}

@@ -9,11 +9,11 @@ import { S as ShareAuthorizationRequired, a as ShareAuthorizationMethod } from '
  * opens only that one key, never the network. This module is the single place that derives the path, validates the
  * network, serializes the stored envelope and computes the digests, so no consumer hand-writes any of them.
  *
- * Call sequence: `planPathBoundShare` (before anything is written) -> the caller holds the plan's `requiredPermissions`
- * -> `encryptAddressedShareContent` (or the caller's own `keys.createKey` + `keys.encrypt`) -> upload `storedBytes` ->
- * `bindPathBoundContentSource` -> `publishAddressedShare`.
+ * Call sequence: `planPathBoundShare` (before anything is written) -> `encryptAddressedShareContent` (or the caller's own
+ * `keys.encrypt`, which encrypts to the key's public key) -> upload `storedBytes` -> `bindPathBoundContentSource` ->
+ * `publishAddressedShare`. The node records the share's key when the policy is registered; nothing creates it beforehand.
  */
-type AddressedContentSourceErrorCode = "share-id-invalid" | "network-invalid" | "network-not-checksummed" | "key-path-required" | "key-path-mismatch" | "digest-invalid" | "key-not-authorized" | "key-receipt-mismatch" | "envelope-invalid" | "stored-bytes-mismatch";
+type AddressedContentSourceErrorCode = "share-id-invalid" | "network-invalid" | "network-not-checksummed" | "key-path-required" | "key-path-mismatch" | "digest-invalid" | "envelope-invalid" | "stored-bytes-mismatch";
 /** A path-bound source could not be planned, built or accepted. Match on `code`, not the message or `instanceof`. */
 declare class AddressedContentSourceError extends TypeError {
     readonly code: AddressedContentSourceErrorCode;
@@ -56,18 +56,7 @@ interface PathBoundSharePlan {
     readonly keyPath: string;
     /** `<network>/share/<shareId>`: the one decrypt resource the share grants. */
     readonly keyResource: string;
-    /**
-     * ROUTE A, per share at runtime: `key.create` on exactly this share's key, requested with `requestPermissions` before the key is created
-     * (one extra consent per share). For apps that cannot use the sign-in route (for example apps whose sign-in goes through the OpenKey widget
-     * `authorizeTinyCloud` route, which refuses decrypt and key.create outside `apps/`).
-     */
-    readonly requiredPermissions: PathBoundPermissionEntry[];
-    /**
-     * ROUTE B, once at sign-in (manifest entries): `key.create` and `decrypt` on the default network's `<network>/share/` prefix, so every share's
-     * key can be created without a further prompt. Put these in the `permissions` of the manifest the owner signs in with.
-     */
-    readonly sessionPermissions: PathBoundPermissionEntry[];
-    /** The owner session must hold these for the node to register the policy: decrypt under `<network>/share/` (also part of `sessionPermissions`). */
+    /** The owner session must hold these for the node to register the policy: decrypt under `<network>/share/`. */
     readonly registrationPermissions: PathBoundPermissionEntry[];
     /** Options for `keys.encrypt(plan.keyPath, plaintext, plan.encryptOptions({ metadata }))`. */
     encryptOptions(extra?: {
@@ -78,8 +67,8 @@ interface PathBoundSharePlan {
     };
 }
 /**
- * The manifest entries (route B, sign-in) that let one session create every share's key: `decrypt` and `key.create` on the default network's
- * `<network>/share/` prefix. Needs no share id, so an app builds its manifest before any share exists. Put the result in `manifest.permissions`.
+ * The manifest entries that let one session register every share's policy: `decrypt` on the default network's `<network>/share/` prefix.
+ * Needs no share id, so an app builds its sign-in manifest before any share exists. Put the result in `manifest.permissions`.
  */
 declare function pathBoundSessionPermissions(input: {
     readonly encryptionNetwork: string;
@@ -114,14 +103,6 @@ declare function bindPathBoundContentSource(input: {
 }): PathBoundContentSource;
 /** The part of a named-key client (`NamedKeyClient`, web `tcw.keys`, node `node.keys`) this module calls. */
 interface AddressedShareKeyClient {
-    createKey(path: string, options: {
-        networkId: string;
-    }): Promise<{
-        readonly networkId: string;
-        readonly keyPath: string;
-        readonly state?: string;
-        readonly keyVersion?: number;
-    }>;
     encrypt(path: string, plaintext: Uint8Array, options: {
         networkId: string;
         metadata?: Record<string, string>;
@@ -134,9 +115,8 @@ interface EncryptedAddressedContent {
     readonly byteLength: number;
 }
 /**
- * Create the share's named key and encrypt the content under it. Built from the same steps a consumer may run itself
- * (`keys.createKey`, `keys.encrypt`, then `bindPathBoundContentSource`). The key-create capability in
- * `plan.requiredPermissions` must already be held; an unauthorized answer is reported as `key-not-authorized` naming it.
+ * Encrypt the content under the share's named key. `keys.encrypt` wraps to the key's public key, which the node serves without
+ * authentication; the key needs no record yet (the node records it when the share policy is registered).
  */
 declare function encryptAddressedShareContent(input: {
     readonly plan: PathBoundSharePlan;

package/dist/artifact.cjs

@@ -5484,6 +5484,7 @@ function serialize(value) {
 function canonicalize(value) {
   return serialize(value);
 }
+var POLICY_ROOT_MAX_LIFETIME_SECONDS = 31 * 24 * 60 * 60;
 
 // src/artifact.ts
 var import_sha2562 = require("@noble/hashes/sha256");