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

package/dist/share-root.d.cts

@@ -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.cjs';
+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';
+
+/**
+ * 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/";
@@ -157,8 +191,9 @@ declare const defaultPolicyOwnerModeProbe: PolicyOwnerModeProbe;
  * - 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`,
+ *   `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`.
  * - Created only through `createOwnerDelegation({ permissions })`; the signed
  *   bytes are decoded and checked here.
@@ -305,38 +340,139 @@ 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";
+/** Persistable grant metadata. Holds no key material. */
+interface ShareGrantRecord {
+    readonly version: 1;
+    readonly cid: string;
+    /** Base64url of the exact owner-signed CACAO bytes. */
+    readonly authorization: string;
+    readonly spaceId: string;
+    readonly ownerDid: string;
+    readonly keyDid: string;
+    readonly nodeOrigin: string;
+    /** The one exact KV key under `xyz.tinycloud.share/shares/`. */
+    readonly path: string;
+    readonly access: ShareGrantAccess;
+    readonly expiresAt: string;
+}
 /**
- * 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.
+ * A per-share owner grant (TC-1423 D3, the interim path for addressed shares
+ * while the Node does not enforce owner-authority binding).
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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).
  */
-interface DecodedOwnerRootCacao {
-    /** CIDv1 (raw, BLAKE3) of the exact CACAO bytes, as the Node computes it. */
+declare class ShareGrant {
+    #private;
     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[];
+    readonly ownerDid: string;
+    readonly spaceId: string;
+    readonly keyDid: string;
+    readonly nodeOrigin: 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).
+     */
+    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 restore(input: {
+        readonly record: ShareGrantRecord;
+        readonly key: DelegatedShareKey;
+        readonly now?: () => number;
+    }): Promise<ShareGrant>;
+    /** The `Authorization` value the Node knows this grant by (base64url CACAO). */
+    get authorization(): string;
+    /** The exact KV resource this grant covers. */
+    get resource(): string;
+    toRecord(): ShareGrantRecord;
+    /**
+     * 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`.
+     */
+    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. */
+    clear(): void;
+}
+
+interface ShareNetworkResult {
+    /** `urn:tinycloud:encryption:<owner did:pkh>:share`. */
+    readonly networkId: string;
+    /** Owner wallet approvals this call used: 0 when the network already existed, else 1. */
+    readonly approvals: 0 | 1;
 }
-/** 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`.
+ * 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.
+ */
+declare function shareNetworkIdFor(ownerDid: string): string;
+type FetchFn = (input: URL, init?: RequestInit) => Promise<Response>;
+/**
+ * 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.
  *
- * 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.
+ * 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`.
  */
-declare function decodeOwnerRootCacao(bytes: Uint8Array, expectedCid?: string): DecodedOwnerRootCacao;
+declare function ensureShareNetwork(input: {
+    readonly owner: ShareRootOwnerAuthority;
+    readonly spaceId: string;
+    readonly nodeOrigin: string;
+    readonly fetch?: FetchFn;
+    readonly keyFactory?: () => Promise<DelegatedShareKey>;
+    readonly now?: () => number;
+}): Promise<ShareNetworkResult>;
 
-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, 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 };

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 { 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/";
@@ -157,8 +191,9 @@ declare const defaultPolicyOwnerModeProbe: PolicyOwnerModeProbe;
  * - 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`,
+ *   `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`.
  * - Created only through `createOwnerDelegation({ permissions })`; the signed
  *   bytes are decoded and checked here.
@@ -305,38 +340,139 @@ 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";
+/** Persistable grant metadata. Holds no key material. */
+interface ShareGrantRecord {
+    readonly version: 1;
+    readonly cid: string;
+    /** Base64url of the exact owner-signed CACAO bytes. */
+    readonly authorization: string;
+    readonly spaceId: string;
+    readonly ownerDid: string;
+    readonly keyDid: string;
+    readonly nodeOrigin: string;
+    /** The one exact KV key under `xyz.tinycloud.share/shares/`. */
+    readonly path: string;
+    readonly access: ShareGrantAccess;
+    readonly expiresAt: string;
+}
 /**
- * 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.
+ * A per-share owner grant (TC-1423 D3, the interim path for addressed shares
+ * while the Node does not enforce owner-authority binding).
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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).
  */
-interface DecodedOwnerRootCacao {
-    /** CIDv1 (raw, BLAKE3) of the exact CACAO bytes, as the Node computes it. */
+declare class ShareGrant {
+    #private;
     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[];
+    readonly ownerDid: string;
+    readonly spaceId: string;
+    readonly keyDid: string;
+    readonly nodeOrigin: 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).
+     */
+    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 restore(input: {
+        readonly record: ShareGrantRecord;
+        readonly key: DelegatedShareKey;
+        readonly now?: () => number;
+    }): Promise<ShareGrant>;
+    /** The `Authorization` value the Node knows this grant by (base64url CACAO). */
+    get authorization(): string;
+    /** The exact KV resource this grant covers. */
+    get resource(): string;
+    toRecord(): ShareGrantRecord;
+    /**
+     * 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`.
+     */
+    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. */
+    clear(): void;
+}
+
+interface ShareNetworkResult {
+    /** `urn:tinycloud:encryption:<owner did:pkh>:share`. */
+    readonly networkId: string;
+    /** Owner wallet approvals this call used: 0 when the network already existed, else 1. */
+    readonly approvals: 0 | 1;
 }
-/** 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`.
+ * 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.
+ */
+declare function shareNetworkIdFor(ownerDid: string): string;
+type FetchFn = (input: URL, init?: RequestInit) => Promise<Response>;
+/**
+ * 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.
  *
- * 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.
+ * 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`.
  */
-declare function decodeOwnerRootCacao(bytes: Uint8Array, expectedCid?: string): DecodedOwnerRootCacao;
+declare function ensureShareNetwork(input: {
+    readonly owner: ShareRootOwnerAuthority;
+    readonly spaceId: string;
+    readonly nodeOrigin: string;
+    readonly fetch?: FetchFn;
+    readonly keyFactory?: () => Promise<DelegatedShareKey>;
+    readonly now?: () => number;
+}): Promise<ShareNetworkResult>;
 
-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, 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 };