@tinycloud/share-sdk 1.2.0-beta.1 → 1.2.0-beta.3

package/dist/share-root.d.ts

@@ -1,5 +1,39 @@
-import { CompactUcanAuthorization } from '@tinycloud/share-envelope';
-import { C as CreateOwnerDelegationParams, r as OwnerDelegationReceipt, D as DelegatedShareKey, A as AddressedOwnerRootInput, i as AddressedOwnerRootReceipt } from './addressed-publish-CsUS7-SI.js';
+import { CompactUcanAuthorization, UnifiedContentSource } from '@tinycloud/share-envelope';
+import { C as CreateOwnerDelegationParams, r as OwnerDelegationReceipt, A as AddressedOwnerRootInput, i as AddressedOwnerRootReceipt, D as DelegatedShareKey, l as AddressedPublishAuthority } from './addressed-publish-CsUS7-SI.js';
+
+/**
+ * The fields of an owner-signed SIWE CACAO that bound its authority. Read
+ * from the exact bytes the Node imported; nothing here is taken from the
+ * SDK's own echo of the request.
+ */
+interface DecodedOwnerRootCacao {
+    /** CIDv1 (raw, BLAKE3) of the exact CACAO bytes, as the Node computes it. */
+    readonly cid: string;
+    readonly issuer: string;
+    readonly audience: string;
+    readonly issuedAt: string;
+    readonly expiresAt?: string;
+    readonly notBefore?: string;
+    /** Every SIWE resource, in signed order. */
+    readonly resources: readonly string[];
+    /** The ReCap `att` of the last resource; null-prototype maps. */
+    readonly attenuation: Readonly<Record<string, Readonly<Record<string, readonly unknown[]>>>>;
+    /** The ReCap `prf` list (parent capabilities); a root has none. */
+    readonly reCapProofs: readonly unknown[];
+}
+/** CIDv1 (raw, BLAKE3) of exact CACAO bytes, as the Node computes a delegation CID. */
+declare function ownerRootCacaoCid(bytes: Uint8Array): string;
+/**
+ * Decode the exact bytes of an owner-signed SIWE CACAO. Checks size, CBOR
+ * strictness, the envelope shape (eip4361 payload, 65-byte eip191 signature)
+ * and, when given, that the bytes hash to `expectedCid`.
+ *
+ * It does not verify the wallet signature: the Node verifies it when it
+ * imports the delegation and is the authority on it. This decoder exists so
+ * a caller can check what was signed (scope, audience, lifetime) instead of
+ * trusting the request it made.
+ */
+declare function decodeOwnerRootCacao(bytes: Uint8Array, expectedCid?: string): DecodedOwnerRootCacao;
 
 /** KV prefix every share lives under; the root never reaches outside it. */
 declare const SHARE_ROOT_PREFIX = "xyz.tinycloud.share/shares/";
@@ -7,47 +41,28 @@ declare const SHARE_ROOT_PREFIX = "xyz.tinycloud.share/shares/";
 declare const SHARE_ROOT_MAX_LIFETIME_MS: number;
 /** Longest lifetime of an agent root (the OpenKey device-grant cap). */
 declare const AGENT_SHARE_ROOT_MAX_LIFETIME_MS: number;
-/** Product cap on a bearer link or policy root signed under a root. */
+/** Product cap on a bearer link, a per-share grant, or a policy root. */
 declare const SHARE_ROOT_LINK_MAX_LIFETIME_MS: number;
 /**
- * Signer clock skew tolerated on a signed root's `exp - iat` (only there:
- * `exp - now` stays strict), so an approval is not wasted when the signer
- * sets its own issue time.
+ * Signer clock skew tolerated on a signed delegation's `exp - iat` (only
+ * there: `exp - now` stays strict), so an approval is not wasted when the
+ * signer sets its own issue time.
  */
 declare const SHARE_ROOT_CLOCK_SKEW_MS: number;
 /** `ensureShareRoot` asks for the cap minus this margin, so a clamping or slow signer stays inside the cap. */
 declare const SHARE_ROOT_REQUEST_MARGIN_MS: number;
-/**
- * NODE-B2 (§9 "Advertised mode"): a Node lists these in the `features` of
- * its public `GET /info` (sdk-core `checkNodeInfo` → `NodeInfo.features`):
- * the capability marker plus exactly one active mode. Read in one place,
- * {@link readPolicyOwnerAuthorityMode}; the Node version is never consulted.
- */
-declare const POLICY_OWNER_AUTHORITY_FEATURES: {
-    readonly marker: "policy-owner-authority-v1";
-    readonly record: "policy-owner-authority-record";
-    readonly enforce: "policy-owner-authority-enforce";
-};
-/** How long a known mode is trusted before the Node is asked again (NODE-B2: at most 5 minutes). */
-declare const POLICY_OWNER_AUTHORITY_PROBE_TTL_MS: number;
-/** `share`: Share/CLI root in `applications`. `agent`: `default` space, bearer only. */
+/** `share`: Share/CLI root in `applications`. `agent`: `default` space. Both are kv/bearer only. */
 type ShareRootKind = "share" | "agent";
-/**
- * What the owner signed. `kv`: get + metadata on the share prefix only.
- * `kv+share-decrypt`: also decrypt on the owner's `:share` network, which a
- * policy owner needs; minted only while the Node advertises `enforce` and
- * `shareRootPolicyRoots` is on.
- */
-type ShareRootScope = "kv" | "kv+share-decrypt";
-type ShareRootErrorCode = "invalid-request" | "invalid-key" | "key-cleared" | "lifetime-exceeds-cap" | "expired" | "malformed-root" | "issuer-mismatch" | "audience-mismatch" | "resource-mismatch" | "ability-mismatch" | "expiry-mismatch" | "reroot-same-key" | "link-out-of-scope" | "policy-roots-disabled" | "policy-roots-not-enforced-by-node" | "root-not-policy-capable";
+type ShareRootErrorCode = "invalid-request" | "invalid-key" | "key-cleared" | "lifetime-exceeds-cap" | "expired" | "malformed-root" | "issuer-mismatch" | "audience-mismatch" | "resource-mismatch" | "ability-mismatch" | "expiry-mismatch" | "reroot-same-key" | "link-out-of-scope" | "share-id-not-network-safe" | "network-not-active" | "node-refused" | "grant-revoke-incomplete" | "share-id-in-use" | "control-target-invalid";
 interface ShareRootErrorDetails {
     /** The delegation CID the Node imported (the receipt's), when the owner already signed. */
     readonly rootCid?: string;
     /** CID of the signed bytes, when it differs from `rootCid`. */
     readonly signedCid?: string;
-    /** The imported root may grant more, or longer, than requested: the owner must revoke `rootCid`. */
+    /** The imported delegation may grant more, or longer, than requested: the owner must revoke `rootCid`. */
     readonly mustRevoke?: boolean;
 }
+/** The error every share-root, per-share grant and owner-control operation throws. */
 declare class ShareRootError extends Error {
     readonly code: ShareRootErrorCode;
     readonly rootCid?: string;
@@ -64,26 +79,16 @@ interface ShareRootOwnerAuthority {
 }
 interface ShareRootOptions {
     readonly kind?: ShareRootKind;
-    /**
-     * Feature flag `shareRootPolicyRoots`, off by default. A root gains `:share`
-     * decrypt, and can sign policy roots through {@link ShareRoot.policyRootSigner},
-     * only while this is on and the root's Node advertises owner-authority
-     * mode `enforce`.
-     */
-    readonly shareRootPolicyRoots?: boolean;
-    /** Defaults to {@link defaultPolicyOwnerModeProbe}. */
-    readonly policyOwnerModeProbe?: PolicyOwnerModeProbe;
     readonly now?: () => number;
 }
 /** Persistable root metadata. Holds no key material: the key lives in its own store. */
 interface ShareRootRecord {
     readonly version: 1;
     readonly kind: ShareRootKind;
-    readonly scope: ShareRootScope;
-    /** The Node the root was created against; its advertised mode gates policy signing. */
+    /** The Node the root was created against. */
     readonly nodeOrigin: string;
     readonly cid: string;
-    /** Base64url of the exact owner-signed CACAO bytes. */
+    /** Base64url (unpadded) of the exact owner-signed CACAO bytes. */
     readonly authorization: string;
     readonly spaceId: string;
     readonly ownerDid: string;
@@ -99,67 +104,33 @@ interface ShareRootLink {
     readonly delegation: CompactUcanAuthorization;
 }
 /**
- * Policy/v3 owner signing for a `kv+share-decrypt` root. Shaped like
- * `AddressedPublishAuthority` without `registerPolicy`. Every call re-checks
- * the whole gate (flag, the Node's advertised mode within the probe TTL, root
- * live, key present), so a signer kept past a mode change stops working.
+ * Policy/v3 owner signing for one per-share grant. Shaped like
+ * `AddressedPublishAuthority` without `registerPolicy`. Every call checks the
+ * key is held and the grant is live.
  */
-interface ShareRootPolicySigner {
-    /** The share key DID: the `ownerDid` of the policy roots. */
+interface SharePolicySigner {
+    /** The per-share key DID: the `ownerDid` of the policy roots. */
     readonly ownerDid: string;
+    /** The owner delegation (grant) CID that authorizes the key. */
     readonly rootCid: string;
-    /** Interim rule: no policy root may outlive the share root. */
+    /** No policy root may outlive the grant. */
     readonly notAfter: Date;
     /** Build and sign one proofless policy root; its expiry must be within `notAfter` and 31 days. */
     createOwnerRoot(input: AddressedOwnerRootInput): Promise<AddressedOwnerRootReceipt>;
     /** Sign a 32-byte digest (policy or envelope); nothing else. */
     sign(digest: Uint8Array): Promise<Uint8Array>;
 }
-/**
- * The single adapter over the Node's advertisement. Takes the `features`
- * list of `GET /info` and returns `"enforce"` only for the marker plus the
- * `-enforce` mode and no `-record`; `"record"` for the marker plus
- * `-record` only; `undefined` for anything else (no marker, as on every
- * Node up to 1.21.0, both modes, or a malformed list). Only `"enforce"`
- * enables policy-capable roots.
- */
-declare function readPolicyOwnerAuthorityMode(features: unknown): "enforce" | "record" | undefined;
-/** Per-Node cache of "does this Node enforce owner-authority expiry". */
-interface PolicyOwnerModeProbe {
-    /** True only when the Node currently advertises `enforce`. Never throws. */
-    isEnforced(nodeOrigin: string): Promise<boolean>;
-    /**
-     * Record the `features` a sign-in just read from `GET /info`
-     * (`NodeInfo.features`), so each sign-in refreshes the answer without a
-     * second fetch.
-     */
-    observe(nodeOrigin: string, features: readonly string[]): void;
-}
-/**
- * Keep each Node's answer in memory for `ttlMs` (default and ceiling 5
- * minutes), then read `GET /info` again, so a Node that stops advertising
- * `enforce` turns the gate off within one TTL. Only `https:` origins (and
- * `http:` on loopback) are probed. A failure, a non-JSON or oversized
- * (64 KiB) answer, or a malformed list counts as not enforcing and is cached
- * for the same TTL.
- */
-declare function createPolicyOwnerModeProbe(options?: {
-    readonly fetch?: (input: URL, init: RequestInit) => Promise<Response>;
-    readonly ttlMs?: number;
-    readonly now?: () => number;
-}): PolicyOwnerModeProbe;
-/** Process-wide default; sign-in code should feed it `NodeInfo.features` through `observe`. */
-declare const defaultPolicyOwnerModeProbe: PolicyOwnerModeProbe;
 /**
  * A wallet-signed, read-only root delegated to one non-extractable share key,
- * so shares outlive the owner's login session (TC-1423 D3, option B').
+ * so bearer links outlive the owner's login session (TC-1423 D3, option B').
  *
- * - Scope: `kv/get` + `kv/metadata` on the share prefix. `:share` decrypt is
- *   added (scope `kv+share-decrypt`) only when the root is created while
- *   `shareRootPolicyRoots` is on and its Node advertises owner-authority mode
- *   `enforce`; a `kv` root holds no decrypt, so the Node refuses any Policy/v3
- *   registration it signs. Never put, del, list, `capabilities/read`,
- *   `network.create` or `:default`.
+ * - Scope: `kv/get` + `kv/metadata` on the share prefix, and nothing else.
+ *   The root never decrypts, before or after the Node enforces owner-authority
+ *   binding: every addressed (email/domain) or edit share uses its own
+ *   per-share grant and network (`ShareGrant`). Without decrypt, the key
+ *   cannot own a policy over encrypted content (the Node answers
+ *   `policy-owner-not-authorized`). Never put, del, list,
+ *   `capabilities/read`, `network.create` or any encryption network.
  * - Created only through `createOwnerDelegation({ permissions })`; the signed
  *   bytes are decoded and checked here.
  * - Lifetime: at most 37 days (`agent`: 30). One key per root.
@@ -168,14 +139,10 @@ declare const defaultPolicyOwnerModeProbe: PolicyOwnerModeProbe;
  *   share key requires the composer to be on its own origin first (REVIEW-D3
  *   V2-2); this package provides none. CLI profiles may keep a key in a 0600
  *   file and rebuild with `restore`.
- * - The client flag and `policyRootSigner` gate only this API: whoever holds
- *   the key can sign through other APIs. What bounds that is the scope of the
- *   root (no decrypt before `enforce`) and the Node.
  */
 declare class ShareRoot {
     #private;
     readonly kind: ShareRootKind;
-    readonly scope: ShareRootScope;
     readonly nodeOrigin: string;
     readonly cid: string;
     readonly ownerDid: string;
@@ -185,12 +152,10 @@ declare class ShareRoot {
     readonly expiresAt: Date;
     private constructor();
     /**
-     * Ask the owner for a new root (one approval) for a fresh share key. The
-     * scope is chosen now: `kv+share-decrypt` only for a `share` root with the
-     * flag on and `nodeOrigin` advertising `enforce`, otherwise `kv`. All request
-     * checks run before anything is signed. If the signed result is rejected,
-     * the key is cleared and the error carries the imported `rootCid` (and
-     * `mustRevoke` when the root may be wider than requested).
+     * Ask the owner for a new root (one approval) for a fresh share key. All
+     * request checks run before anything is signed. If the signed result is
+     * rejected, the key is cleared and the error carries the imported `rootCid`
+     * (and `mustRevoke` when the root may be wider than requested).
      *
      * `keyFactory` defaults to a fresh non-extractable WebCrypto key that only
      * this root holds. A custom factory must not persist the key before
@@ -210,10 +175,12 @@ declare class ShareRoot {
         readonly key: DelegatedShareKey;
         readonly options?: ShareRootOptions;
     }): Promise<ShareRoot>;
-    /** The `Authorization` value the Node knows this root by (base64url CACAO). */
+    /**
+     * This root's CACAO as base64url, UNPADDED (the record form). As a Node
+     * `Authorization` header it must be padded to a multiple of 4 characters:
+     * the Node refuses an unpadded value otherwise.
+     */
     get authorization(): string;
-    /** True when the root holds `:share` decrypt and may act as a policy owner (still gated per call). */
-    get policyCapable(): boolean;
     toRecord(): ShareRootRecord;
     /** True while the root is live, its key is held, and it lasts at least until `expiresAt`. Revocation is not visible here. */
     covers(expiresAt: Date, now?: number): boolean;
@@ -227,27 +194,17 @@ declare class ShareRoot {
         readonly path: string;
         readonly expiresAt: Date;
     }): Promise<ShareRootLink>;
-    /**
-     * The only ShareRoot API that signs Policy/v3 (email/domain) owner material.
-     * Needs a `kv+share-decrypt` root, the `shareRootPolicyRoots` flag, a live
-     * root and key, and the root's Node advertising `enforce`; the returned
-     * signer re-checks all of it on every call. Until then addressed shares use
-     * per-share owner grants. Agent roots are bearer-only.
-     */
-    policyRootSigner(): Promise<ShareRootPolicySigner>;
     /** Drop this root's key handle. It does not revoke the root: only the owner does that. */
     clear(): void;
 }
 /**
- * Re-root only when needed. `purpose: "bearer"` (default) keeps any live root
- * of the same kind, space and Node that covers `expiresAt`. `purpose:
- * "policy"` additionally needs a `kv+share-decrypt` root: it throws unless the
- * flag is on and the Node enforces, and re-roots when the current root is
- * `kv`; it never hands back a `kv` root. A re-root costs one approval, uses a
- * new key and requests the kind's cap minus {@link SHARE_ROOT_REQUEST_MARGIN_MS}.
+ * Re-root only when needed: keep a live root of the same kind, space and
+ * Node that covers `expiresAt`; otherwise mint one new root (one approval)
+ * with a new key, requesting the kind's cap minus
+ * {@link SHARE_ROOT_REQUEST_MARGIN_MS}.
  *
- * - Links and policies signed under the old root stay valid until their own
- *   expiry; keep the old root (and its key) to revoke them (REVIEW-D3 V2-5).
+ * - Links signed under the old root stay valid until their own expiry; keep
+ *   the old root (and its key) to revoke them (REVIEW-D3 V2-5).
  * - Concurrent calls each re-root (two approvals, and one orphaned root if
  *   both write the same store slot): callers serialize, e.g. with a lock.
  * - A revoked root still "covers" here: re-root when `/delegate` answers
@@ -256,7 +213,6 @@ declare class ShareRoot {
 declare function ensureShareRoot(input: {
     readonly current?: ShareRoot;
     readonly expiresAt: Date;
-    readonly purpose?: "bearer" | "policy";
     readonly owner: ShareRootOwnerAuthority;
     readonly spaceId: string;
     readonly nodeOrigin: string;
@@ -305,38 +261,364 @@ interface ShareKeyDelegationInput {
  */
 declare function signShareKeyDelegation(input: ShareKeyDelegationInput): Promise<CompactUcanAuthorization>;
 
+/** `view`: kv get + metadata. `edit`: also kv put. Both on one exact key. */
+type ShareGrantAccess = "view" | "edit";
+/** P2(a): a read-back key lives at most one hour. */
+declare const EDIT_SHARE_READER_MAX_LIFETIME_MS: number;
+type FetchFn$1 = (input: URL, init?: RequestInit) => Promise<Response>;
 /**
- * The fields of an owner-signed SIWE CACAO that bound its authority. Read
- * from the exact bytes the Node imported; nothing here is taken from the
- * SDK's own echo of the request.
+ * The share's one content key (I1): `xyz.tinycloud.share/shares/<shareId>/<file>`,
+ * or, for `view` only, a TC-1428 version file
+ * `xyz.tinycloud.share/artifacts/<aid>/versions/<n>/<file>` (versions are
+ * immutable, and that path is not bound to the shareId, so `edit` is refused).
  */
-interface DecodedOwnerRootCacao {
-    /** CIDv1 (raw, BLAKE3) of the exact CACAO bytes, as the Node computes it. */
+declare function assertShareGrantPath(path: string, shareId: string, access: ShareGrantAccess): void;
+/** Progress of one addressed share, for the consumer's history/index row (the SDK does not store rows). */
+type ShareGrantRowState = "pending" | "granted" | "network" | "active" | "abandoned" | "retired";
+/** The history/index row to persist at each step. Write `pending` BEFORE the approval prompt. */
+interface ShareGrantRow {
+    readonly shareId: string;
+    /** Network name, `share-<shareId>`. */
+    readonly nw: string;
+    readonly networkId: string;
+    readonly keyDid: string;
+    readonly access: ShareGrantAccess;
+    readonly path: string;
+    readonly state: ShareGrantRowState;
+    readonly grantCid?: string;
+}
+/** Persistable grant metadata (record v2). Holds no key material. */
+interface ShareGrantRecord {
+    readonly version: 2;
     readonly cid: string;
-    readonly issuer: string;
-    readonly audience: string;
-    readonly issuedAt: string;
-    readonly expiresAt?: string;
-    readonly notBefore?: string;
-    /** Every SIWE resource, in signed order. */
-    readonly resources: readonly string[];
-    /** The ReCap `att` of the last resource; null-prototype maps. */
-    readonly attenuation: Readonly<Record<string, Readonly<Record<string, readonly unknown[]>>>>;
-    /** The ReCap `prf` list (parent capabilities); a root has none. */
-    readonly reCapProofs: readonly unknown[];
+    /** Base64url of the exact owner-signed CACAO bytes. */
+    readonly authorization: string;
+    readonly spaceId: string;
+    readonly ownerDid: string;
+    readonly keyDid: string;
+    readonly nodeOrigin: string;
+    readonly shareId: string;
+    readonly networkId: string;
+    readonly path: string;
+    readonly access: ShareGrantAccess;
+    readonly expiresAt: string;
+}
+/** What one addressed or edit share asks the owner for. */
+interface ShareGrantRequest {
+    readonly owner: ShareRootOwnerAuthority;
+    /** The owner's `applications` space. */
+    readonly spaceId: string;
+    readonly nodeOrigin: string;
+    /** Names the network `share-<shareId>`: must match `^[a-z0-9][a-z0-9-]{15,35}$`. */
+    readonly shareId: string;
+    /** The share's one content key (see `assertShareGrantPath`). */
+    readonly path: string;
+    readonly access: ShareGrantAccess;
+    /** At most 30 days ahead. */
+    readonly expiresAt: Date;
+    /**
+     * Key-gone recovery only: accept the share's network when it already
+     * exists and is `active` (a half-published share whose key was lost), and
+     * grant a new key on it. Without it, `prepare` refuses an existing network
+     * (`share-id-in-use`) before the prompt. A retired network is always
+     * refused.
+     */
+    readonly resumeExistingNetwork?: boolean;
+    readonly keyFactory?: () => Promise<DelegatedShareKey>;
+    readonly fetch?: FetchFn$1;
+    readonly now?: () => number;
+}
+/** A per-share grant whose key exists but which the owner has not approved yet. Persist `row` first, then `approve()`. */
+interface PendingShareGrant {
+    readonly shareId: string;
+    readonly networkId: string;
+    readonly keyDid: string;
+    /** The `pending` row: write it before calling `approve()`. */
+    readonly row: ShareGrantRow;
+    /** Ask the owner for the grant: exactly one approval. */
+    approve(): Promise<ShareGrant>;
+    /** Drop the key without asking (e.g. the row write failed). */
+    discard(): void;
 }
-/** CIDv1 (raw, BLAKE3) of exact CACAO bytes, as the Node computes a delegation CID. */
-declare function ownerRootCacaoCid(bytes: Uint8Array): string;
 /**
- * Decode the exact bytes of an owner-signed SIWE CACAO. Checks size, CBOR
- * strictness, the envelope shape (eip4361 payload, 65-byte eip191 signature)
- * and, when given, that the bytes hash to `expectedCid`.
+ * A per-share owner grant on the share's own encryption network (TC-1423,
+ * PERSHARE-NETWORK design v2). Every addressed (email/domain) or edit share
+ * gets one, before and after the Node enforces owner-authority binding; the
+ * share root never decrypts.
  *
- * It does not verify the wallet signature: the Node verifies it when it
- * imports the delegation and is the authority on it. This decoder exists so
- * a caller can check what was signed (scope, audience, lifetime) instead of
- * trusting the request it made.
+ * One owner approval signs one CACAO to a FRESH non-extractable per-share key:
+ * - kv `get` + `metadata` (+ `put` for `edit`) on the share's one content key;
+ * - `network.create`, `network.revoke` and `decrypt` on exactly
+ *   `urn:tinycloud:encryption:<owner did:pkh>:share-<shareId>`, and nothing
+ *   else (the Node matches network resources by exact parsed id, so these
+ *   reach no other network).
+ * The key creates that network (owned by the owner) and owns the share's
+ * policy. Decrypt therefore covers this one share's ciphertext only, for the
+ * key and for the share's recipients.
+ *
+ * Publish order (the consumer stores the rows; see `ShareGrantRow`):
+ * 0. `ShareGrant.prepare`: shareId rule, path, access, expiry, space and
+ *    origin are checked, and the network is looked up (an existing or
+ *    retired one is refused); a typed error costs no approval.
+ * 1. Persist `pending.row` (state `pending`), and a CLI persists the key file.
+ * 2. `pending.approve()`: one approval; row `granted` with `grantCid`.
+ * 3. `grant.ensureNetwork()`: creates the network if absent, re-reads it after
+ *    any answer (racing creates can answer 500), accepts only `active`; row
+ *    `network`. Retry at no approval while the key is held.
+ * 4. The owner session encrypts to `grant.networkId` and stores the object
+ *    (`grant.assertContentSource`); on failure `grant.retireNetwork()`, row
+ *    `abandoned`.
+ * 5. `publishAddressedShare({ authority: grant.publishAuthority(registerPolicy) })`:
+ *    the network is re-read as `active` right before registration.
+ * 6. Row `active`.
+ *
+ * Revoke: `revokeShareGrant` retires the network first (permanent; every
+ * recipient loses decrypt at the next request; no approval while the key is
+ * held), then revokes the grant (one owner approval). Revoking the grant
+ * first would strand an active network the dead key can no longer retire.
+ *
+ * Key custody: no browser persistence (needs the composer on its own origin
+ * first, REVIEW-D3 V2-2); keep the grant in memory, or in a CLI 0600 key file
+ * via `restore`, until the share is retired or expired.
  */
-declare function decodeOwnerRootCacao(bytes: Uint8Array, expectedCid?: string): DecodedOwnerRootCacao;
+declare class ShareGrant {
+    #private;
+    readonly cid: string;
+    readonly ownerDid: string;
+    readonly spaceId: string;
+    readonly keyDid: string;
+    readonly nodeOrigin: string;
+    readonly shareId: string;
+    readonly networkId: string;
+    readonly path: string;
+    readonly access: ShareGrantAccess;
+    readonly issuedAt: Date;
+    readonly expiresAt: Date;
+    private constructor();
+    /**
+     * Step 0: check everything that does not need the owner, and make the key.
+     * Also looks the share's network up (no approval): a shareId whose network
+     * is retired (burned), or already exists from an earlier grant, is refused
+     * with `share-id-in-use` before the prompt (see `resumeExistingNetwork`).
+     * Throws `share-id-not-network-safe`, `invalid-request`, `lifetime-exceeds-cap`,
+     * `share-id-in-use`, `node-refused` or `invalid-key` with no approval spent.
+     */
+    static prepare(input: ShareGrantRequest): Promise<PendingShareGrant>;
+    /** `prepare` then `approve`, for callers that keep no `pending` row (tests, one-shot tools). */
+    static create(input: ShareGrantRequest): Promise<ShareGrant>;
+    /** Rebuild a stored grant with its key (e.g. a CLI 0600 key file); the signed bytes are checked again. Only record v2. */
+    static restore(input: {
+        readonly record: ShareGrantRecord;
+        readonly key: DelegatedShareKey;
+        readonly now?: () => number;
+        readonly fetch?: FetchFn$1;
+    }): Promise<ShareGrant>;
+    /**
+     * This grant's CACAO as base64url, UNPADDED (the record form). As a Node
+     * `Authorization` header it must be padded to a multiple of 4 characters:
+     * the Node refuses an unpadded value otherwise.
+     */
+    get authorization(): string;
+    /** The exact KV resource this grant covers. */
+    get resource(): string;
+    toRecord(): ShareGrantRecord;
+    /** The history/index row for `state`. */
+    row(state: ShareGrantRowState): ShareGrantRow;
+    /**
+     * Step 3: make sure the share's network exists and is usable. Creates it
+     * when absent (key-signed, no approval), then decides on a fresh lookup
+     * after any answer. Returns `networkId` (the grant's lowercase spelling;
+     * the Node echoes the owner in EIP-55 case). A retired network is never
+     * re-created (the Node answers 409): `network-not-active`.
+     */
+    ensureNetwork(): Promise<string>;
+    /** Throw `network-not-active` unless the share's network is `active` now (fresh lookup). */
+    assertNetworkActive(): Promise<string>;
+    /**
+     * Retire the share's network with the per-share key (no approval):
+     * PERMANENT, and every holder of decrypt on it (recipients included) is
+     * refused at their next request. Idempotent: a repeat or a never-created
+     * network counts as done.
+     */
+    retireNetwork(): Promise<"retired" | "absent">;
+    /** Step 4 check (I1): the stored object belongs to this share, on its exact key and network. */
+    assertContentSource(contentSource: UnifiedContentSource): void;
+    /**
+     * Policy/v3 owner signing for this one share. Every call checks the key is
+     * held and the grant is live. Policy roots must be owned by the per-share
+     * key, expire no later than the grant, and name only this grant's exact
+     * KV resource (no action the grant lacks) and decrypt on this share's
+     * network (parsed equality).
+     */
+    policySigner(): SharePolicySigner;
+    /**
+     * Step 5: `publishAddressedShare`'s `authority` for this share. Its
+     * `registerPolicy` first re-reads the network and refuses unless it is
+     * `active` (released Nodes accept registrations on missing or retired
+     * networks).
+     */
+    publishAuthority(registerPolicy: AddressedPublishAuthority["registerPolicy"]): AddressedPublishAuthority;
+    /** Drop the per-share key. It does not retire the network or revoke the grant. */
+    clear(): void;
+}
+/**
+ * Revoke one addressed share: retire its network with the per-share key
+ * (permanent, no approval), THEN revoke the grant with an owner SIWE (one
+ * approval). Only a `{ revoked: true, cid }` receipt counts. If the owner
+ * step fails, decrypt is already cut: the error `grant-revoke-incomplete`
+ * says so, and the caller can retry the grant revoke. Without the key, use
+ * the owner control batch (`runShareControlBatch`).
+ */
+declare function revokeShareGrant(input: {
+    readonly grant: ShareGrant;
+    readonly owner: {
+        signOwnerRevocation(cid: string): Promise<string>;
+    };
+    readonly fetch?: FetchFn$1;
+}): Promise<{
+    readonly network: "retired" | "absent";
+    readonly grant: "revoked";
+}>;
+/** A short-lived key that lets the owner read back one share's content (P2(a)). */
+interface EditShareReader {
+    readonly cid: string;
+    readonly keyDid: string;
+    readonly networkId: string;
+    readonly path: string;
+    readonly expiresAt: Date;
+    /** Signs this reader's kv/get and decrypt invocations; refuses after expiry or `clear()`. */
+    readonly signer: ShareKeySigner;
+    clear(): void;
+}
+/**
+ * Let the owner read back an edit share (P2(a)): one approval for kv `get`
+ * on the share's key and `decrypt` on its network, to a throwaway in-memory
+ * key that lives at most one hour. Nothing is stored.
+ */
+declare function openEditShare(input: {
+    readonly owner: ShareRootOwnerAuthority;
+    readonly record: Pick<ShareGrantRecord, "spaceId" | "ownerDid" | "shareId" | "networkId" | "path">;
+    readonly lifetimeMs?: number;
+    readonly now?: () => number;
+}): Promise<EditShareReader>;
+
+/**
+ * One encryption network per addressed share (TC-1423, PERSHARE-NETWORK
+ * design): `urn:tinycloud:encryption:<owner did:pkh, lowercase>:share-<shareId>`.
+ * A stored ciphertext is wrapped to exactly one share's network, so a key or
+ * recipient session holding decrypt on it reaches that one share only.
+ */
+declare const SHARE_NETWORK_NAME_PREFIX = "share-";
+/** Throws `share-id-not-network-safe` unless `shareId` matches `^[a-z0-9][a-z0-9-]{15,35}$` (UUIDs and 32-hex ids do). */
+declare function assertNetworkSafeShareId(shareId: string): void;
+/** The share's own network: `urn:tinycloud:encryption:<owner did:pkh, lowercase>:share-<shareId>`. */
+declare function perShareNetworkIdFor(ownerDid: string, shareId: string): string;
+
+/**
+ * Largest `Authorization` value an owner control may carry. Measured on the
+ * production ingress (nginx 1.27.4, `large_client_header_buffers 4 32k`,
+ * HTTP/1.1): 32,751 bytes pass, 32,752 bytes get `400 Request Header Or
+ * Cookie Too Large`. A direct Node accepts ~483 KB and Cloudflare 128 KB.
+ * 30,000 bytes leave 8.4% for header-name and proxy overhead. Each share
+ * (network URN with `delegation/revoke` + `network.revoke`) costs ~845
+ * bytes: 34 shares per control with the space rows (29,800 bytes measured
+ * with the `applications` row, imported by the Node), 35 without.
+ */
+declare const SHARE_CONTROL_HEADER_BUDGET_BYTES = 30000;
+/** A control lives ten minutes: long enough to retire and revoke one batch. */
+declare const SHARE_CONTROL_LIFETIME_MS: number;
+type FetchFn = (input: URL, init?: RequestInit) => Promise<Response>;
+/** The owner wallet, as a SIWE signer: one call = one approval. */
+interface ShareControlOwner {
+    /** `did:pkh:eip155:<chain>:<address>`. */
+    readonly ownerDid: string;
+    /** The SIWE `domain` the wallet shows (the composer's host). */
+    readonly domain: string;
+    /** EIP-191 `personal_sign` of exactly `message`; returns the 65-byte signature as 0x hex. */
+    signMessage(message: string): Promise<string>;
+}
+/** One share to cut: its network, and its grant when known. */
+interface ShareControlTarget {
+    readonly networkId: string;
+    readonly grantCid?: string;
+}
+/** One owner control: one approval, sized to the header budget before signing. */
+interface ShareControlBatch {
+    readonly targets: readonly ShareControlTarget[];
+    /** `<space>/delegation` rows (first batch only): revoke any delegation in those spaces (share roots, links). */
+    readonly spaceDelegationResources: readonly string[];
+    /** Exact `Authorization` value length of the signed control, in bytes. */
+    readonly headerBytes: number;
+}
+/**
+ * Split a kill-all into owner controls (one approval each), sized by the
+ * exact `Authorization` bytes of each signed control, never above
+ * `budgetBytes` (default {@link SHARE_CONTROL_HEADER_BUDGET_BYTES}).
+ *
+ * EVERY control carries the same `<space>/delegation` row for each of
+ * `spaceIds`: a grant's kv row is revoked through the `applications` row,
+ * and Nodes that accept control revokes (v1.20.6, NODE-B2 N4') need it in
+ * the control that revokes that grant. The `default` row covers agent roots
+ * and their links. `createOwnerDelegation` cannot express these rows (and
+ * caps a delegation at 16 permissions), so controls are built here.
+ *
+ * Targets are restricted to this owner's per-share networks
+ * (`control-target-invalid` otherwise), checked before anything is signed.
+ */
+declare function planShareControlBatches(input: {
+    readonly owner: Pick<ShareControlOwner, "ownerDid" | "domain">;
+    readonly targets: readonly ShareControlTarget[];
+    /** Spaces whose delegations every control may revoke (e.g. the owner's `applications` and `default`). */
+    readonly spaceIds?: readonly string[];
+    readonly budgetBytes?: number;
+}): ShareControlBatch[];
+interface ShareControlResult {
+    readonly controlCid: string;
+    readonly networks: readonly {
+        readonly networkId: string;
+        readonly result: "retired" | "absent" | "failed";
+        readonly error?: string;
+    }[];
+    /**
+     * `revoked`: by the control. `revoked-by-owner`: the Node refused the
+     * control (released Nodes refuse it for grants that carry decrypt) and
+     * the per-grant owner fallback (one approval each) revoked it. `refused`:
+     * still live.
+     */
+    readonly grants: readonly {
+        readonly grantCid: string;
+        readonly result: "revoked" | "revoked-by-owner" | "refused";
+        readonly status: number;
+    }[];
+}
+/**
+ * Run one control (one approval): sign it to a fresh throwaway key, import
+ * it (`POST /delegate`), retire EVERY target network first (decrypt is cut
+ * for everyone at the next request), then revoke each known grant through
+ * the control. A revoke counts only with a `{ revoked: true, cid }` receipt
+ * for that grant. With `revokeFallback`, a grant the Node refuses to revoke
+ * through the control (1.21.0 refuses it for decrypt-bearing grants) is
+ * revoked by the owner directly (one approval each). The throwaway key is
+ * cleared before returning.
+ *
+ * The batch is checked again here (targets, space rows, domain, and the
+ * byte budget on the real values) before the owner is asked, so a stored or
+ * hand-built batch gets the same checks as a planned one.
+ *
+ * A grant is revoked even if its network's retire failed: re-run (the same
+ * batch, or a new plan for the leftovers) until every network is `retired`
+ * or `absent`. Re-runs are idempotent.
+ */
+declare function runShareControlBatch(input: {
+    readonly owner: ShareControlOwner;
+    readonly nodeOrigin: string;
+    readonly batch: ShareControlBatch;
+    readonly revokeFallback?: {
+        signOwnerRevocation(cid: string): Promise<string>;
+    };
+    readonly fetch?: FetchFn;
+    readonly now?: () => number;
+    readonly keyFactory?: () => Promise<DelegatedShareKey>;
+}): Promise<ShareControlResult>;
 
-export { AGENT_SHARE_ROOT_MAX_LIFETIME_MS, type DecodedOwnerRootCacao, POLICY_OWNER_AUTHORITY_FEATURES, POLICY_OWNER_AUTHORITY_PROBE_TTL_MS, type PolicyOwnerModeProbe, SHARE_ROOT_CLOCK_SKEW_MS, SHARE_ROOT_LINK_MAX_LIFETIME_MS, SHARE_ROOT_MAX_LIFETIME_MS, SHARE_ROOT_PREFIX, SHARE_ROOT_REQUEST_MARGIN_MS, type ShareKeyDelegationInput, type ShareKeySigner, ShareRoot, ShareRootError, type ShareRootErrorCode, type ShareRootErrorDetails, type ShareRootKind, type ShareRootLink, type ShareRootOptions, type ShareRootOwnerAuthority, type ShareRootPolicySigner, type ShareRootRecord, type ShareRootScope, assertNonExtractableShareKey, createPolicyOwnerModeProbe, decodeOwnerRootCacao, defaultPolicyOwnerModeProbe, ensureShareRoot, ownerRootCacaoCid, readPolicyOwnerAuthorityMode, signShareKeyDelegation };
+export { AGENT_SHARE_ROOT_MAX_LIFETIME_MS, type DecodedOwnerRootCacao, EDIT_SHARE_READER_MAX_LIFETIME_MS, type EditShareReader, type PendingShareGrant, SHARE_CONTROL_HEADER_BUDGET_BYTES, SHARE_CONTROL_LIFETIME_MS, SHARE_NETWORK_NAME_PREFIX, SHARE_ROOT_CLOCK_SKEW_MS, SHARE_ROOT_LINK_MAX_LIFETIME_MS, SHARE_ROOT_MAX_LIFETIME_MS, SHARE_ROOT_PREFIX, SHARE_ROOT_REQUEST_MARGIN_MS, type ShareControlBatch, type ShareControlOwner, type ShareControlResult, type ShareControlTarget, ShareGrant, type ShareGrantAccess, type ShareGrantRecord, type ShareGrantRequest, type ShareGrantRow, type ShareGrantRowState, type ShareKeyDelegationInput, type ShareKeySigner, type SharePolicySigner, ShareRoot, ShareRootError, type ShareRootErrorCode, type ShareRootErrorDetails, type ShareRootKind, type ShareRootLink, type ShareRootOptions, type ShareRootOwnerAuthority, type ShareRootRecord, assertNetworkSafeShareId, assertNonExtractableShareKey, assertShareGrantPath, decodeOwnerRootCacao, ensureShareRoot, openEditShare, ownerRootCacaoCid, perShareNetworkIdFor, planShareControlBatches, revokeShareGrant, runShareControlBatch, signShareKeyDelegation };