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

package/dist/share-root.d.cts

@@ -0,0 +1,342 @@
+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';
+
+/** KV prefix every share lives under; the root never reaches outside it. */
+declare const SHARE_ROOT_PREFIX = "xyz.tinycloud.share/shares/";
+/** Longest lifetime of a Share (browser device or CLI profile) root. */
+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. */
+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.
+ */
+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. */
+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";
+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`. */
+    readonly mustRevoke?: boolean;
+}
+declare class ShareRootError extends Error {
+    readonly code: ShareRootErrorCode;
+    readonly rootCid?: string;
+    readonly signedCid?: string;
+    readonly mustRevoke: boolean;
+    constructor(code: ShareRootErrorCode, message: string, details?: ShareRootErrorDetails);
+}
+/** What a signed-in owner session provides: TinyCloudNode / web-sdk `createOwnerDelegation`. */
+interface ShareRootOwnerAuthority {
+    /** `did:pkh:eip155:<chain>:<address>` of the owner wallet. */
+    readonly ownerDid: string;
+    /** Sign one CACAO with exactly `permissions` (one wallet approval) and import it into the Node. */
+    createOwnerDelegation(params: CreateOwnerDelegationParams): Promise<OwnerDelegationReceipt>;
+}
+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. */
+    readonly nodeOrigin: string;
+    readonly cid: string;
+    /** Base64url of the exact owner-signed CACAO bytes. */
+    readonly authorization: string;
+    readonly spaceId: string;
+    readonly ownerDid: string;
+    readonly keyDid: string;
+    readonly expiresAt: string;
+}
+interface ShareRootLink {
+    readonly rootCid: string;
+    readonly linkDid: string;
+    readonly path: string;
+    readonly expiresAt: Date;
+    /** Compact UCAN for `POST /delegate`, then the link's bearer token. */
+    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.
+ */
+interface ShareRootPolicySigner {
+    /** The share key DID: the `ownerDid` of the policy roots. */
+    readonly ownerDid: string;
+    readonly rootCid: string;
+    /** Interim rule: no policy root may outlive the share root. */
+    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').
+ *
+ * - 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`.
+ * - Created only through `createOwnerDelegation({ permissions })`; the signed
+ *   bytes are decoded and checked here.
+ * - Lifetime: at most 37 days (`agent`: 30). One key per root.
+ * - Key custody: `create` generates the non-extractable key itself and never
+ *   exposes it; `clear()` drops the only handle. Browser persistence of a
+ *   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;
+    readonly spaceId: string;
+    readonly keyDid: string;
+    readonly issuedAt: Date;
+    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).
+     *
+     * `keyFactory` defaults to a fresh non-extractable WebCrypto key that only
+     * this root holds. A custom factory must not persist the key before
+     * `create` resolves.
+     */
+    static create(input: {
+        readonly owner: ShareRootOwnerAuthority;
+        readonly spaceId: string;
+        readonly nodeOrigin: string;
+        readonly expiresAt: Date;
+        readonly keyFactory?: () => Promise<DelegatedShareKey>;
+        readonly options?: ShareRootOptions;
+    }): Promise<ShareRoot>;
+    /** Rebuild a stored root with its key (e.g. a CLI 0600 key file); the signed bytes are checked again. */
+    static restore(input: {
+        readonly record: ShareRootRecord;
+        readonly key: DelegatedShareKey;
+        readonly options?: ShareRootOptions;
+    }): Promise<ShareRoot>;
+    /** The `Authorization` value the Node knows this root by (base64url CACAO). */
+    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;
+    /**
+     * Sign a bearer link: `kv/get` on one exact key under the prefix, to the
+     * link's own key, with this root as its only proof. It never outlives the
+     * root (the Node refuses that too) or 30 days. Zero approvals.
+     */
+    signBearerLink(input: {
+        readonly linkDid: string;
+        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}.
+ *
+ * - 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).
+ * - 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
+ *   `delegation-revoked`.
+ */
+declare function ensureShareRoot(input: {
+    readonly current?: ShareRoot;
+    readonly expiresAt: Date;
+    readonly purpose?: "bearer" | "policy";
+    readonly owner: ShareRootOwnerAuthority;
+    readonly spaceId: string;
+    readonly nodeOrigin: string;
+    readonly keyFactory?: () => Promise<DelegatedShareKey>;
+    readonly options?: ShareRootOptions;
+}): Promise<{
+    readonly root: ShareRoot;
+    readonly rerooted: boolean;
+}>;
+
+/**
+ * Link signing outside WASM. The SDK's WASM delegation builder signs with a
+ * raw session JWK; a share key must never exist as raw bytes in a browser.
+ * These helpers build the same compact UCAN the Node accepts and hand only
+ * the exact signing input to the key's `sign`, so the key can be a
+ * non-extractable WebCrypto Ed25519 handle (browser: kept in IndexedDB;
+ * Node/CLI: imported non-extractable from its own 0600 key file).
+ */
+type ShareKeySigner = Pick<DelegatedShareKey, "did" | "sign">;
+/**
+ * Throw unless `key` is a non-extractable Ed25519 WebCrypto private key whose
+ * public half is `key.did`. The binding is checked by signing a fixed probe
+ * and verifying it against the DID, so a root is never requested for a key
+ * this process cannot actually use.
+ */
+declare function assertNonExtractableShareKey(key: DelegatedShareKey): Promise<void>;
+interface ShareKeyDelegationInput {
+    readonly key: ShareKeySigner;
+    readonly audienceDid: string;
+    /** Resource -> ability -> caveats; the caller bounds it (see `ShareRoot.signBearerLink`). */
+    readonly attenuation: Readonly<Record<string, Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>>>;
+    readonly proofs: readonly string[];
+    /** Exactly one fact object, as the Node's compact UCAN requires; defaults to `{}`. */
+    readonly facts?: readonly [Readonly<Record<string, unknown>>];
+    /** Unix seconds. */
+    readonly notBefore: number;
+    /** Unix seconds. */
+    readonly expiresAt: number;
+    readonly nonce?: string;
+}
+/**
+ * Sign a compact UCAN delegation (JCS header and payload, EdDSA) with a share
+ * key. Unlike share-envelope's invocation signer it is not limited to 60 s:
+ * lifetime limits belong to the caller. The result is re-verified (signature,
+ * issuer binding, canonical JSON) before it is returned.
+ */
+declare function signShareKeyDelegation(input: ShareKeyDelegationInput): Promise<CompactUcanAuthorization>;
+
+/**
+ * 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;
+
+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 };