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

package/dist/share-root.d.cts

@@ -1,4 +1,4 @@
-import { CompactUcanAuthorization } from '@tinycloud/share-envelope';
+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.cjs';
 
 /**
@@ -41,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;
@@ -98,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;
@@ -133,68 +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 `:share` decrypt, so its key cannot own a
- *   policy over `:share`-encrypted content (the Node answers
- *   `policy-owner-not-authorized`). 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.
@@ -203,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;
@@ -220,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
@@ -245,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;
@@ -262,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
@@ -291,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;
@@ -342,9 +263,33 @@ declare function signShareKeyDelegation(input: ShareKeyDelegationInput): Promise
 
 /** `view`: kv get + metadata. `edit`: also kv put. Both on one exact key. */
 type ShareGrantAccess = "view" | "edit";
-/** Persistable grant metadata. Holds no key material. */
+/** 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 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).
+ */
+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: 1;
+    readonly version: 2;
     readonly cid: string;
     /** Base64url of the exact owner-signed CACAO bytes. */
     readonly authorization: string;
@@ -352,38 +297,89 @@ interface ShareGrantRecord {
     readonly ownerDid: string;
     readonly keyDid: string;
     readonly nodeOrigin: string;
-    /** The one exact KV key under `xyz.tinycloud.share/shares/`. */
+    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;
+}
 /**
- * A per-share owner grant (TC-1423 D3, the interim path for addressed shares
- * while the Node does not enforce owner-authority binding).
+ * 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.
  *
- * The owner signs one CACAO (one approval per share) to a FRESH per-share
- * key, never the share-root key:
- * - kv `get` + `metadata` (+ `put` for `edit`) on exactly one KV key under
- *   the share prefix, in the `applications` space;
- * - `decrypt` on the owner's `:share` network, which a Policy/v3 owner must
- *   hold (every v3 policy's capability ceiling includes decrypt on the
- *   source's network; without it the Node answers
- *   `policy-owner-not-authorized`);
- * - at most 30 days, and exactly the requested expiry.
- * The per-share key then owns that one share's policy: `publishAuthority`
- * signs its two policy roots (bounded by the grant's expiry and exact path)
- * and its 32-byte policy and envelope digests.
+ * 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.
  *
- * Revoking the grant (one owner SIWE `POST /revoke` on `cid`) cuts the
- * per-share key's own reads and its decrypt, for this share only. Until the
- * Node binds policy registrations to the owner delegation (NODE-B2), an
- * already-registered policy keeps admitting recipients until its own expiry,
- * which never exceeds the grant's.
+ * 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`.
  *
- * Key custody: `create` generates a non-extractable key and never exposes
- * it. Keep the grant (in memory, or a CLI 0600 key file via `restore`) until
- * the share expires, to sign `RootRevocation` later. No browser persistence:
- * that needs the composer on its own origin first (REVIEW-D3 V2-2).
+ * 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 class ShareGrant {
     #private;
@@ -392,87 +388,237 @@ declare class ShareGrant {
     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();
     /**
-     * Ask the owner for one per-share grant (one approval). Path, access,
-     * expiry, space and Node origin are checked before the wallet is asked; the
-     * signed CACAO is decoded and must match exactly, or the key is cleared and
-     * the error carries the imported CID (`mustRevoke` when it may be wider).
+     * 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 create(input: {
-        readonly owner: ShareRootOwnerAuthority;
-        readonly spaceId: string;
-        readonly nodeOrigin: string;
-        readonly path: string;
-        readonly access: ShareGrantAccess;
-        readonly expiresAt: Date;
-        readonly keyFactory?: () => Promise<DelegatedShareKey>;
-        readonly now?: () => number;
-    }): Promise<ShareGrant>;
-    /** Rebuild a stored grant with its key (e.g. a CLI 0600 key file); the signed bytes are checked again. */
+    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>;
-    /** The `Authorization` value the Node knows this grant by (base64url CACAO). */
+    /**
+     * 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 (with no action the grant lacks) and decrypt on `:share`.
+     * 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).
      */
-    policySigner(): ShareRootPolicySigner;
-    /** `publishAddressedShare`'s `authority` for this share: the policy signer plus the caller's `registerPolicy`. */
     publishAuthority(registerPolicy: AddressedPublishAuthority["registerPolicy"]): AddressedPublishAuthority;
-    /** Drop the per-share key. It does not revoke the grant: only the owner does that. */
+    /** Drop the per-share key. It does not retire the network or revoke the grant. */
     clear(): void;
 }
-
-interface ShareNetworkResult {
-    /** `urn:tinycloud:encryption:<owner did:pkh>:share`. */
+/**
+ * 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;
-    /** Owner wallet approvals this call used: 0 when the network already existed, else 1. */
-    readonly approvals: 0 | 1;
+    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;
 }
 /**
- * The owner's `:share` network URN, `urn:tinycloud:encryption:<owner
- * did:pkh>:share`: where Share sources are encrypted, and the network a
- * per-share grant or a `kv+share-decrypt` root may decrypt. The Node compares
- * the did:pkh address case-insensitively.
+ * 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 function shareNetworkIdFor(ownerDid: string): string;
+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;
+}
 /**
- * Make sure the owner's dedicated `:share` encryption network exists (D3
- * addendum §1, review B1). Per owner: `urn:tinycloud:encryption:<owner
- * did:pkh>:share`. The owner owns it, never a share key or per-share key: a
- * network whose owner is the key would be root authority for that key
- * (tinycloud-node `delegation.rs:792-809`), so revoking its grant would not
- * cut decrypt.
+ * 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}).
  *
- * Idempotent: when the Node already has it, nothing is signed (0 approvals).
- * Otherwise the owner signs one short-lived CACAO (one approval, once per
- * owner) granting only `network.create` on that URN to a throwaway
- * non-extractable key, which creates the network with the owner as
- * `ownerDid` and is then cleared. A 409 from a concurrent creator counts as
- * created. Share sources encrypt to it; vault and secrets stay on `:default`.
+ * 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 ensureShareNetwork(input: {
-    readonly owner: ShareRootOwnerAuthority;
-    readonly spaceId: string;
+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 keyFactory?: () => Promise<DelegatedShareKey>;
     readonly now?: () => number;
-}): Promise<ShareNetworkResult>;
+    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, ShareGrant, type ShareGrantAccess, type ShareGrantRecord, type ShareKeyDelegationInput, type ShareKeySigner, type ShareNetworkResult, ShareRoot, ShareRootError, type ShareRootErrorCode, type ShareRootErrorDetails, type ShareRootKind, type ShareRootLink, type ShareRootOptions, type ShareRootOwnerAuthority, type ShareRootPolicySigner, type ShareRootRecord, type ShareRootScope, assertNonExtractableShareKey, createPolicyOwnerModeProbe, decodeOwnerRootCacao, defaultPolicyOwnerModeProbe, ensureShareNetwork, ensureShareRoot, ownerRootCacaoCid, readPolicyOwnerAuthorityMode, shareNetworkIdFor, 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 };