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

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/index.cjs

@@ -6633,7 +6633,7 @@ function canonicalKeyHashHex(encryptedSymmetricKey) {
 }
 function pathBoundSessionPermissions(input) {
   const encryptionNetwork = assertNetwork(input.encryptionNetwork);
-  return [{ service: "tinycloud.encryption", path: `${encryptionNetwork}/share/`, actions: ["tinycloud.encryption/decrypt", "tinycloud.encryption/key.create"] }];
+  return [{ service: "tinycloud.encryption", path: `${encryptionNetwork}/share/`, actions: ["tinycloud.encryption/decrypt"] }];
 }
 function planPathBoundShare(input) {
   const keyPath = pathBoundKeyPath(input.shareId);
@@ -6644,9 +6644,7 @@ function planPathBoundShare(input) {
     encryptionNetwork,
     keyPath,
     keyResource,
-    requiredPermissions: [{ service: "tinycloud.encryption", path: keyResource, actions: ["tinycloud.encryption/key.create"] }],
-    sessionPermissions: pathBoundSessionPermissions({ encryptionNetwork }),
-    registrationPermissions: [{ service: "tinycloud.encryption", path: `${encryptionNetwork}/share/`, actions: ["tinycloud.encryption/decrypt"] }],
+    registrationPermissions: pathBoundSessionPermissions({ encryptionNetwork }),
     encryptOptions: (extra) => ({ networkId: encryptionNetwork, ...extra?.metadata === void 0 ? {} : { metadata: { ...extra.metadata } } })
   };
 }
@@ -6700,34 +6698,11 @@ function bindPathBoundContentSource(input) {
     initialCiphertextDigestHex: hex2((0, import_sha2562.sha256)(expected))
   };
 }
-function isUnauthorized(error) {
-  const value = error;
-  return value !== null && typeof value === "object" && (value.status === 401 || value.status === 403 || value.code === "PERMISSION_DENIED" || value.code === "AUTH_UNAUTHORIZED");
-}
 async function encryptAddressedShareContent(input) {
   const { plan, keys } = input;
   const byteLength = input.plaintext.byteLength;
-  let receipt;
-  try {
-    receipt = await keys.createKey(plan.keyPath, { networkId: plan.encryptionNetwork });
-  } catch (error) {
-    if (isUnauthorized(error)) {
-      const status = error.status;
-      throw new AddressedContentSourceError(
-        "key-not-authorized",
-        `the owner session does not hold tinycloud.encryption/key.create on ${plan.keyResource} (the node answers "Unauthorized Action: ${plan.keyResource} / tinycloud.encryption/key.create"); hold it either at sign-in (put plan.sessionPermissions in the manifest: key.create on ${plan.encryptionNetwork}/share/) or per share (requestPermissions(plan.requiredPermissions)) before creating the key` + (status === 403 ? "; if the owner signs in through OpenKey, the request must come from a first-party TinyCloud origin" : "")
-      );
-    }
-    throw error;
-  }
-  if (receipt.networkId !== plan.encryptionNetwork || receipt.keyPath !== plan.keyPath || receipt.state !== void 0 && receipt.state !== "active") {
-    throw new AddressedContentSourceError("key-receipt-mismatch", "the created key does not match this share");
-  }
   const envelope = await keys.encrypt(plan.keyPath, input.plaintext, plan.encryptOptions(input.metadata === void 0 ? void 0 : { metadata: input.metadata }));
   assertEnvelope(plan, envelope);
-  if (receipt.keyVersion !== void 0 && envelope.keyVersion !== receipt.keyVersion) {
-    throw new AddressedContentSourceError("key-receipt-mismatch", "the envelope key version does not match the created key");
-  }
   const storedBytes = pathBoundStoredBytes(envelope);
   return { envelope, storedBytes, byteLength };
 }