@tinycloud/node-sdk 2.11.0-beta.0 → 2.11.0-beta.10

package/dist/{core-B_i2KfID.d.cts → core-BypriIWK.d.cts}

@@ -1,4 +1,4 @@
-import { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, LocalNodeIdentityStore, IWasmBindings, ISessionManager, SiweConfig, Manifest, ComposedManifestRequest, ClientSession, TinyCloudSession, Extension, SignRequest, SignInOptions, Delegation, DelegatedResource, PermissionEntry, TelemetryConfig, IKVService, ISQLService, IDuckDbService, IHooksService, INotificationHandler, IENSResolver, AccountService, RegisterOwnerSharePolicyParams, OwnerSharePolicyRegistrationReceipt, ShareDeliveryAuthorizationReceipt, IDataVaultService, IEncryptionService, NetworkDescriptor, ISecretsService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISpace, ISharingService, CreateDelegationParams, DelegationResult, DelegationRevocationReceipt, DelegationStatus, ResolvedDelegate, KeyProvider, JWK } from '@tinycloud/sdk-core';
+import { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, LocalNodeIdentityStore, IWasmBindings, ISessionManager, SiweConfig, Manifest, ComposedManifestRequest, ClientSession, TinyCloudSession, Extension, SignRequest, SignInOptions, CapabilityPresentationEnvelopeV1, Delegation, DelegatedResource, PermissionEntry, TelemetryConfig, IKVService, ISQLService, IDuckDbService, IHooksService, CreateOwnerDelegationParams as CreateOwnerDelegationParams$1, OwnerDelegationReceipt as OwnerDelegationReceipt$1, INotificationHandler, IENSResolver, AccountService, InvokeAnyFunction as InvokeAnyFunction$1, RegisterOwnerSharePolicyParams, OwnerSharePolicyRegistrationReceipt, ShareDeliveryAuthorizationReceipt, IDataVaultService, IEncryptionService, NetworkDescriptor, ISecretsService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISpace, ISharingService, CreateDelegationParams, DelegationResult, DelegationRevocationReceipt, DelegationStatus, ResolvedDelegate, KeyProvider, JWK } from '@tinycloud/sdk-core';
 import { EventEmitter } from 'events';
 import { InvokeFunction, InvokeAnyFunction } from '@tinycloud/sdk-services';
 
@@ -195,9 +195,9 @@ interface NodeUserAuthorizationConfig {
     tinycloudRegistryUrl?: string | null;
     /** Fallback TinyCloud hosts. Default: hosted TinyCloud node. */
     tinycloudFallbackHosts?: string[] | null;
-    /** Probe for a locally-running TinyCloud node before registry/fallback resolution. Default: true. */
+    /** Probe configured/registered local nodes before registry/fallback resolution. Default: true. */
     autoDiscoverLocalNode?: boolean;
-    /** Local loopback node URL to probe. Default: http://127.0.0.1:8000. */
+    /** Local loopback node URL to probe. Omit to avoid probing loopback. */
     localNodeUrl?: string;
     /** Known `*.local.tinycloud.link` subdomain name, probed directly. */
     localLinkName?: string;
@@ -319,6 +319,12 @@ declare class NodeUserAuthorization implements IUserAuthorization {
     private _address?;
     private _chainId?;
     private _nodeFeatures;
+    /**
+     * `nodeId` from the `GET /info` performed during sign-in/restore, tagged with
+     * the host it came from. Callers that need the node DID (encryption-network
+     * admin invocations) reuse this instead of re-fetching `/info`.
+     */
+    private _nodeInfoIdentity?;
     private _lastActivationSkippedSpaceIds;
     constructor(config: NodeUserAuthorizationConfig);
     /**
@@ -387,6 +393,13 @@ declare class NodeUserAuthorization implements IUserAuthorization {
     private requireTinyCloudHosts;
     private get primaryTinyCloudHost();
     get nodeFeatures(): string[];
+    /**
+     * The node DID reported by `GET /info` for `host`, if the sign-in (or
+     * restore) that populated it targeted that same host. Returns `undefined`
+     * for any other host, and for nodes whose `/info` omits `nodeId`, so callers
+     * fall back to fetching it themselves rather than using a foreign node's DID.
+     */
+    nodeIdForHost(host: string): string | undefined;
     get lastActivationSkippedSpaceIds(): string[];
     /**
      * Compute the `abilities` map the WASM `prepareSession` call should
@@ -533,6 +546,153 @@ declare class NodeUserAuthorization implements IUserAuthorization {
         spaceId: string;
         verificationMethod: string;
     }, signature: string, keyId: string, jwk: Record<string, unknown>): Promise<ClientSession>;
+    /**
+     * End-to-end sign-in via OpenKey `authorizeTinyCloud()` (Sol CRITICAL-4).
+     *
+     * This is the production entry point that wires
+     * {@link prepareSessionForSigning} → OpenKey `authorizeTinyCloud()` →
+     * {@link signInWithOpenKeyResult} into one call. Consumers pass in a
+     * caller-provided `authorizeFn` (typically a thin wrapper around
+     * `openkey.authorizeTinyCloud()`) so this method has no direct
+     * dependency on the OpenKey SDK — it works with any transport that
+     * conforms to the versioned protocol.
+     *
+     * The `authorizeFn` MUST:
+     *   1. Send the prepared SIWE bytes to OpenKey.
+     *   2. Return the exact `TinyCloudAuthorizationResultV1` shape (with
+     *      `signedMessage` — the bytes the signature actually verifies
+     *      against — plus `selectedActionKeys` and `permissions`).
+     *
+     * NodeUserAuthorization then completes the session with `signedMessage`
+     * (never the prepared bytes), verifying the signature, the immutable
+     * SIWE fields, and every subset invariant enforced by
+     * {@link signInWithOpenKeyResult}. This preserves the exact-byte
+     * guarantee: if the user did NOT narrow, the returned `signedMessage`
+     * equals the prepared SIWE byte-for-byte; if the user narrowed, only
+     * the ReCap block differs and every immutable header field survives.
+     *
+     * Legacy exact-byte {@link signIn} callers are unaffected — this method
+     * is opt-in.
+     *
+     * @param authorizeFn Callback that invokes the versioned OpenKey
+     *   `authorizeTinyCloud()` protocol and returns the result. Receives
+     *   the prepared SIWE bytes plus a `host` hint the widget should bind
+     *   into its /authorize-sign-prepare context.
+     * @param options Optional overrides for the OpenKey request.
+     */
+    signInWithOpenKey(authorizeFn: (input: {
+        protocolVersion: 1;
+        siwe: string;
+        jwk: Record<string, unknown>;
+        host?: string;
+        /**
+         * Sol MAJOR-3: OpenKey key ID (managed or external key) to sign
+         * with. When omitted, the OpenKey SDK falls back to the last
+         * connected key. Callers who want to bind the flow to a specific
+         * OpenKey key can override via options.openkeyKeyId; otherwise the
+         * bridge relies on the SDK's connected-key state.
+         */
+        keyId?: string;
+        /**
+         * Optional presentation envelope forwarded to the OpenKey widget.
+         * Built from this instance's `_manifest` when set. Display-only —
+         * the widget/server MUST NOT let it expand authority. The envelope
+         * carries `manifests` payloads plus a stable SHA-256 digest so the
+         * OpenKey server can origin-bind the browser origin against the
+         * app's well-known manifest.
+         */
+        presentation?: CapabilityPresentationEnvelopeV1;
+    }) => Promise<{
+        protocolVersion: 1;
+        address: string;
+        signature: string;
+        signedMessage: string;
+        selectedActionKeys: string[];
+        permissions: Array<{
+            service: string;
+            space: string;
+            path: string;
+            actions: string[];
+        }>;
+    }>, options?: {
+        host?: string;
+        openkeyKeyId?: string;
+        /**
+         * Optional caller-supplied reason string forwarded in the
+         * presentation envelope. Rendered as caller-supplied (never
+         * verified) in the widget.
+         */
+        reason?: string;
+    }): Promise<ClientSession>;
+    /**
+     * Build a `CapabilityPresentationEnvelopeV1` from `this._manifest`. The
+     * envelope is display-only — the OpenKey widget renders it under an
+     * honest trust label, and the server /authorize-sign-prepare route
+     * decides whether to upgrade the label to `origin-bound` by fetching
+     * the well-known manifest and comparing its digest to
+     * `manifestDigest`.
+     *
+     * Returns `undefined` when no manifest is set — the widget renders as
+     * "no manifest supplied" (unsigned).
+     *
+     * The digest is a deterministic SHA-256 over canonical JSON of the
+     * first manifest payload; OpenKey parses the fetched well-known manifest
+     * and applies the same canonicalization before comparing digests.
+     */
+    private buildPresentationEnvelope;
+    /**
+     * Complete sign-in with a versioned OpenKey authorization result.
+     *
+     * Where `signInWithPreparedSession` completes with a signature over the
+     * ORIGINAL prepared SIWE, this method completes with the SIWE bytes the
+     * OpenKey widget actually presented and signed (`signedMessage`). It
+     * exists because the versioned authorizeTinyCloud protocol lets the user
+     * narrow capabilities; the returned bytes may differ from the original
+     * request and are the only ones the signature actually verifies against.
+     *
+     * The `result` parameter is validated at the trust boundary via
+     * `validateAuthorizationResultV1` (in sdk-core). Callers should validate
+     * BEFORE calling this method so unknown/missing fields are rejected
+     * before any session state is created.
+     *
+     * Validation performed here (defence-in-depth: even a "valid" v1 payload
+     * must clear these checks before any session state is created):
+     * 1. `result.address` matches the local signer's address.
+     * 2. `result.signature` recovers to `result.address` when verified against
+     *    `result.signedMessage`.
+     * 3. Every immutable SIWE header field (domain, address, URI, version,
+     *    chainId, nonce, issuedAt) in the original prepared SIWE is preserved
+     *    byte-for-byte in `result.signedMessage`. `statement` is NOT in this
+     *    list because the WASM renders it from the ReCap contents; it MUST
+     *    change when the ReCap is narrowed.
+     * 4. Every capability in `result.signedMessage`'s ReCap block was present
+     *    in the original prepared SIWE — narrowing OK, broadening rejected.
+     * 5. Every `result.selectedActionKeys` entry corresponds to a
+     *    (resource, action) pair in the returned SIWE.
+     */
+    signInWithOpenKeyResult(result: {
+        protocolVersion: 1;
+        address: string;
+        signature: string;
+        signedMessage: string;
+        selectedActionKeys: string[];
+        permissions: Array<{
+            service: string;
+            space: string;
+            path: string;
+            actions: string[];
+        }>;
+    }, prepared: {
+        /**
+         * The ORIGINAL SIWE the SDK produced via {@link prepareSessionForSigning}.
+         * Used as the source-of-truth reference for immutable-header and
+         * capability-subset comparison against `result.signedMessage`.
+         */
+        siwe: string;
+        jwk: Record<string, unknown>;
+        spaceId: string;
+        verificationMethod: string;
+    }, keyId: string, jwk: Record<string, unknown>): Promise<ClientSession>;
     /**
      * Clear persisted session data.
      */
@@ -856,19 +1016,9 @@ type SecretReadResult = {
 } | {
     status: "invalid_payload";
 };
-interface CreateOwnerDelegationParams {
-    readonly delegateDid: string;
-    readonly spaceId: string;
-    readonly path: string;
-    readonly actions: readonly string[];
-    readonly expiresAt: Date;
-}
-interface OwnerDelegationReceipt {
+type CreateOwnerDelegationParams = CreateOwnerDelegationParams$1;
+interface OwnerDelegationReceipt extends OwnerDelegationReceipt$1 {
     readonly delegation: Delegation;
-    /** Exact signed DAG-CBOR bytes submitted in the Authorization header. */
-    readonly signedDagCbor: Uint8Array;
-    /** Locally derived by the node WASM implementation; this is delegation identity. */
-    readonly delegationCid: string;
     readonly nodeReceipt: {
         /** Raw /delegate response CID: a commit-event id, not delegation identity. */
         readonly commitEventCid?: string;
@@ -897,9 +1047,9 @@ interface TinyCloudNodeConfig {
     tinycloudRegistryUrl?: string | null;
     /** Fallback TinyCloud hosts. Default: hosted TinyCloud node. */
     tinycloudFallbackHosts?: string[] | null;
-    /** Probe for a locally-running TinyCloud node before registry/fallback resolution. Default: true. */
+    /** Probe configured/registered local nodes before registry/fallback resolution. Default: true. */
     autoDiscoverLocalNode?: boolean;
-    /** Local loopback node URL to probe. Default: http://127.0.0.1:8000. */
+    /** Local loopback node URL to probe. Omit to avoid probing loopback. */
     localNodeUrl?: string;
     /** Known `*.local.tinycloud.link` subdomain name, probed directly. */
     localLinkName?: string;
@@ -997,6 +1147,21 @@ interface RuntimePermissionGrantOptions {
     /** Override expiry. ms-format string ("7d", "1h") or raw milliseconds. */
     expiry?: string | number;
 }
+interface EnsureEncryptionNetworkOptions {
+    /**
+     * Skip the `GET /encryption/networks/{id}` existence probe and go straight
+     * to the create.
+     *
+     * The probe pays for itself only when the network already exists. On a
+     * freshly bootstrapped account it is a guaranteed 404, so it costs a round
+     * trip on the cold sign-in path and saves nothing. Creating without it is
+     * safe: the server answers `409 Conflict` if the network is already there,
+     * which {@link TinyCloudNode.createEncryptionNetwork} resolves by reading the
+     * existing descriptor. Set this only when the caller knows the account was
+     * just provisioned.
+     */
+    assumeMissing?: boolean;
+}
 /**
  * High-level TinyCloud API for Node.js environments.
  *
@@ -1008,6 +1173,23 @@ interface NodeDefaults {
     createWasmBindings: () => IWasmBindings;
     createSigner: (privateKey: string, chainId?: number) => ISigner;
 }
+/**
+ * A bootstrap step that COMPLETED but did so in a degraded way — e.g. a KV
+ * batch write that failed ambiguously and was recovered by per-space
+ * reconciliation. Structured (not prose) so callers can branch on `kind` and
+ * `code` without parsing messages (TC-361).
+ */
+interface BootstrapWarning {
+    /** The BootstrapStep.id that degraded, e.g. "account:seed-spaces"
+     *  (BootstrapStepBase.id — packages/bootstrap/src/index.ts:642-645). */
+    stepId: string;
+    /** What kind of degradation. Additive union; one member today. */
+    kind: "batch-write-reconciled";
+    /** ServiceError.code of the underlying failure that was recovered from. */
+    code: string;
+    /** Human-readable detail. Diagnostics only — never parse this. */
+    message: string;
+}
 declare class TinyCloudNode {
     /** @internal Registered by importing @tinycloud/node-sdk (not /core) */
     private static nodeDefaults?;
@@ -1054,6 +1236,12 @@ declare class TinyCloudNode {
      * so this avoids re-parsing the recap on every registration.
      */
     private _recapOperationsCache?;
+    /**
+     * Owned space ids this sign-in has already confirmed are hosted. Consulted by
+     * {@link ensureOwnedSpaceHostedById}; cleared on every {@link signIn} because
+     * hosting is confirmed against the session that was active at the time.
+     */
+    private readonly confirmedHostedSpaceIds;
     /**
      * TinyCloudSession captured by {@link restoreSession} when there's no
      * auth-layer signer available (session-only mode used by OpenKey-backed
@@ -1061,6 +1249,7 @@ declare class TinyCloudNode {
      * {@link currentTinyCloudSession} as a fallback for `auth.tinyCloudSession`.
      */
     private _restoredTcSession?;
+    private _activeServiceSession?;
     /**
      * True when the last signIn() detected an interactive signer and skipped
      * client-side bootstrap. Apps can read this to know whether bootstrap was
@@ -1071,7 +1260,10 @@ declare class TinyCloudNode {
      * Outcome of the last signIn()'s account-bootstrap attempt. `skipped` is
      * true when bootstrap did not complete (interactive signer, auto-sign
      * denied, or a bootstrap step failed); `reason` carries the cause so apps
-     * can surface a "finish account setup" call-to-action.
+     * can surface a "finish account setup" call-to-action. `warnings` is
+     * present when bootstrap completed, but one or more steps recovered from
+     * an ambiguous failure (e.g. a KV batch write reconciled via per-space
+     * fallback) — clean vs. recovered runs are otherwise byte-identical.
      */
     private _bootstrapStatus;
     /** Whether the last signIn() skipped client-side bootstrap because the
@@ -1081,6 +1273,7 @@ declare class TinyCloudNode {
     get bootstrapStatus(): {
         skipped: boolean;
         reason?: string;
+        warnings?: BootstrapWarning[];
     };
     private get nodeFeatures();
     /** SIWE domain — uses config override or defaults to app.tinycloud.xyz */
@@ -1262,6 +1455,22 @@ declare class TinyCloudNode {
     private withAccountRegistryRetry;
     private requestedEncryptionNetworkIds;
     private ensureRequestedEncryptionNetworks;
+    /**
+     * Ensure one of this user's owned spaces is hosted, at most once per space
+     * per sign-in.
+     *
+     * Account bootstrap funnels six calls through here (via
+     * `AccountService.ensureAccountSpaceHosted`), and each one re-submits
+     * `activateSessionWithHost` with the *primary* session. That session's recap
+     * covers only `default` and `secrets`, so the account space appears in
+     * neither `activated` nor `skipped` and the guard below returns immediately
+     * — the repeat calls cannot change the outcome, they only cost round trips.
+     *
+     * The memo is per sign-in ({@link confirmedHostedSpaceIds} is cleared in
+     * `signIn`) and only records confirmed successes. A wrong skip is
+     * self-revealing: the next write to the space fails immediately and loudly
+     * with `404 Space not found`.
+     */
     private ensureOwnedSpaceHostedById;
     /**
      * Host one of this user's owned spaces by name (e.g. `"applications"`).
@@ -1409,6 +1618,16 @@ declare class TinyCloudNode {
      * rehydration set by {@link restoreSession} (session-only mode).
      */
     private currentTinyCloudSession;
+    /**
+     * Mint a multi-capability invocation through the established session key.
+     * Callers receive only the signed headers; session key material remains
+     * owned by the session manager and is never part of the caller contract.
+     */
+    invokeAny(entries: Parameters<InvokeAnyFunction$1>[1], facts?: Parameters<InvokeAnyFunction$1>[2]): ReturnType<InvokeAnyFunction$1>;
+    /** Sign protocol bytes with the established in-memory session key. */
+    signSessionBytes(bytes: Uint8Array): Promise<Uint8Array>;
+    /** Bind a session-signed invocation to the canonical service audience. */
+    bindInvocationAudience(authorization: string, audience: string): Promise<string>;
     /**
      * Connect a wallet to upgrade from session-only mode to wallet mode.
      *
@@ -1472,6 +1691,14 @@ declare class TinyCloudNode {
      */
     private requireEncryptionSession;
     private createEncryptionCrypto;
+    /**
+     * The node DID for {@link config.host}.
+     *
+     * Sign-in already performs `GET /info` for the protocol-version check, and
+     * that response carries `nodeId`, so reuse it rather than fetching `/info` a
+     * second time. Only a value recorded for this exact host qualifies; older
+     * nodes that omit `nodeId` fall through to the fetch.
+     */
     private fetchNodeId;
     private signRawNetworkAuthorization;
     private fetchEncryptionNetworkAt;
@@ -1528,6 +1755,7 @@ declare class TinyCloudNode {
         readonly recipientEmail: string;
         readonly shareUrl: string;
         readonly documentName: string;
+        readonly idempotencyKey: string;
         readonly expiresAt: string;
         /** The enrolled receipt key from the node trust bundle. */
         readonly nodeProof: {
@@ -1596,7 +1824,13 @@ declare class TinyCloudNode {
     get encryption(): IEncryptionService;
     getEncryptionNetwork(nameOrNetworkId?: string): Promise<NetworkDescriptor | null>;
     createEncryptionNetwork(name?: string): Promise<NetworkDescriptor>;
-    ensureEncryptionNetwork(nameOrNetworkId?: string): Promise<NetworkDescriptor>;
+    /**
+     * Ensure an encryption network exists, creating it if necessary.
+     *
+     * @param nameOrNetworkId - Network name or full `urn:tinycloud:encryption:` id.
+     * @param options - See {@link EnsureEncryptionNetworkOptions}.
+     */
+    ensureEncryptionNetwork(nameOrNetworkId?: string, options?: EnsureEncryptionNetworkOptions): Promise<NetworkDescriptor>;
     /**
      * App-facing secrets API backed by the `secrets` space vault.
      */
@@ -2178,4 +2412,4 @@ declare class WasmKeyProvider implements KeyProvider {
  */
 declare function createWasmKeyProvider(sessionManager: SessionManagerWithListing): WasmKeyProvider;
 
-export { type AuthDelegationArtifact as A, type CreateOwnerDelegationParams as C, type DelegateToOptions as D, FileSessionStorage as F, MemorySessionStorage as M, type NodeEventEmitterStrategy as N, type OwnerDelegationReceipt as O, type PortableDelegation as P, type RestorableSession as R, type SecretPermissionHint as S, TinyCloudNode as T, UnsupportedSessionRestoreError as U, type ValidatedRuntimeDelegation as V, WasmKeyProvider as W, type AuthRequestArtifact as a, type DelegateToResult as b, DelegatedAccess as c, type DelegationAuthority as d, NodeUserAuthorization as e, type NodeUserAuthorizationConfig as f, type RuntimeDelegationActivator as g, type RuntimePermissionGrantOptions as h, type SecretReadInput as i, type SecretReadResult as j, type SignStrategy as k, type TinyCloudNodeConfig as l, type WasmKeyProviderConfig as m, activateValidatedRuntimeDelegation as n, createWasmKeyProvider as o, defaultSignStrategy as p, deserializeDelegation as q, grantAuthRequest as r, serializeDelegation as s };
+export { type AuthDelegationArtifact as A, type BootstrapWarning as B, type CreateOwnerDelegationParams as C, type DelegateToOptions as D, type EnsureEncryptionNetworkOptions as E, FileSessionStorage as F, MemorySessionStorage as M, type NodeEventEmitterStrategy as N, type OwnerDelegationReceipt as O, type PortableDelegation as P, type RestorableSession as R, type SecretPermissionHint as S, TinyCloudNode as T, UnsupportedSessionRestoreError as U, type ValidatedRuntimeDelegation as V, WasmKeyProvider as W, type AuthRequestArtifact as a, type DelegateToResult as b, DelegatedAccess as c, type DelegationAuthority as d, NodeUserAuthorization as e, type NodeUserAuthorizationConfig as f, type RuntimeDelegationActivator as g, type RuntimePermissionGrantOptions as h, type SecretReadInput as i, type SecretReadResult as j, type SignStrategy as k, type TinyCloudNodeConfig as l, type WasmKeyProviderConfig as m, activateValidatedRuntimeDelegation as n, createWasmKeyProvider as o, defaultSignStrategy as p, deserializeDelegation as q, grantAuthRequest as r, serializeDelegation as s };