@tinycloud/node-sdk 2.4.0-beta.8 → 2.4.0

package/dist/{core-iwTdsebf.d.cts → core-DfE4s_Rg.d.cts}

@@ -1,6 +1,6 @@
 import { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, IWasmBindings, SiweConfig, Manifest, ComposedManifestRequest, ClientSession, TinyCloudSession, Extension, SignInOptions, Delegation, DelegatedResource, PermissionEntry, TelemetryConfig, IKVService, ISQLService, IDuckDbService, IHooksService, INotificationHandler, IENSResolver, AccountService, IDataVaultService, IEncryptionService, NetworkDescriptor, ISecretsService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISpace, ISharingService, CreateDelegationParams, DelegationResult, ResolvedDelegate, KeyProvider, ISessionManager, JWK } from '@tinycloud/sdk-core';
 import { EventEmitter } from 'events';
-import { InvokeFunction } from '@tinycloud/sdk-services';
+import { InvokeFunction, InvokeAnyFunction } from '@tinycloud/sdk-services';
 
 /**
  * In-memory session storage for Node.js.
@@ -230,6 +230,11 @@ interface NodeUserAuthorizationConfig {
     /** Include implicit account registry permissions when composing `manifest`. Default true. */
     includeAccountRegistryPermissions?: boolean;
 }
+interface CreateBootstrapSessionOptions {
+    spaceId: string;
+    capabilityRequest: ComposedManifestRequest;
+    rawAbilities?: Record<string, string[]>;
+}
 /**
  * Node.js implementation of IUserAuthorization.
  *
@@ -296,6 +301,7 @@ declare class NodeUserAuthorization implements IUserAuthorization {
     private _address?;
     private _chainId?;
     private _nodeFeatures;
+    private _lastActivationSkippedSpaceIds;
     constructor(config: NodeUserAuthorizationConfig);
     /**
      * Return the manifest currently driving sign-in behavior, or
@@ -332,12 +338,36 @@ declare class NodeUserAuthorization implements IUserAuthorization {
      * `siwe` is the load-bearing one because `extractSiweExpiration` returns
      * undefined for missing SIWEs and the SDK then treats the session as
      * expired-at-epoch-zero.
+     *
+     * @param hosts - The TinyCloud hosts this session was created against,
+     *   as persisted in {@link PersistedSessionData.tinycloudHosts}. When
+     *   present (and non-empty) they are adopted directly so the restored
+     *   session resolves to the same node as the original sign-in without
+     *   re-running registry/fallback resolution. When absent (old session)
+     *   hosts are resolved lazily on the first host-needing call via
+     *   {@link ensureTinyCloudHosts}.
+     */
+    setRestoredTinyCloudSession(session: TinyCloudSession, hosts?: string[]): void;
+    /**
+     * Ensure `tinycloudHosts` are resolved before a host-needing call.
+     *
+     * Fresh sign-in resolves hosts up front; a restored session may not have
+     * (old persisted sessions predate {@link PersistedSessionData.tinycloudHosts}).
+     * This guard makes a restored session resolve the node exactly like a fresh
+     * sign-in — persisted hosts are preferred (already set by
+     * {@link setRestoredTinyCloudSession}), otherwise the registry/fallback
+     * resolution runs lazily here. Idempotent: {@link resolveTinyCloudHostsForSignIn}
+     * early-returns when hosts are already set.
+     *
+     * Throws if hosts are unset and the restored session has no address/chainId
+     * to resolve from — a real failure that must surface, not be masked.
      */
-    setRestoredTinyCloudSession(session: TinyCloudSession): void;
+    ensureTinyCloudHosts(): Promise<void>;
     private resolveTinyCloudHostsForSignIn;
     private requireTinyCloudHosts;
     private get primaryTinyCloudHost();
     get nodeFeatures(): string[];
+    get lastActivationSkippedSpaceIds(): string[];
     /**
      * Compute the `abilities` map the WASM `prepareSession` call should
      * see at sign-in time.
@@ -410,6 +440,8 @@ declare class NodeUserAuthorization implements IUserAuthorization {
      * @throws Error if space creation fails
      */
     ensureSpaceExists(): Promise<void>;
+    private recordActivationSkippedSpaces;
+    createBootstrapSession(options: CreateBootstrapSessionOptions): Promise<TinyCloudSession>;
     /**
      * Sign in and create a new session.
      *
@@ -650,7 +682,7 @@ declare class DelegatedAccess {
     private _sql;
     private _duckdb;
     private _hooks;
-    constructor(session: TinyCloudSession, delegation: PortableDelegation, host: string, invoke: InvokeFunction, telemetry?: TelemetryConfig);
+    constructor(session: TinyCloudSession, delegation: PortableDelegation, host: string, invoke: InvokeFunction, invokeAny?: InvokeAnyFunction, telemetry?: TelemetryConfig);
     /**
      * Get the delegation this access was created from.
      */
@@ -731,6 +763,8 @@ interface TinyCloudNodeConfig {
     privateKey?: string;
     /** Custom signer implementation. If provided, takes precedence over privateKey. */
     signer?: ISigner;
+    /** Strategy for root signature requests. Defaults to auto-sign for local keys. */
+    signStrategy?: SignStrategy;
     /** Explicit TinyCloud server URL. When omitted, signIn resolves the user's host. */
     host?: string;
     /** TinyCloud location registry URL. Default: https://registry.tinycloud.xyz. */
@@ -786,6 +820,8 @@ interface TinyCloudNodeConfig {
     capabilityRequest?: ComposedManifestRequest;
     /** Include implicit account registry permissions when composing `manifest`. Default true. */
     includeAccountRegistryPermissions?: boolean;
+    /** Run canonical first-account bootstrap when fresh account state is detected. Default true. */
+    autoBootstrapAccount?: boolean;
     /** Default-off service telemetry. */
     telemetry?: TelemetryConfig;
 }
@@ -915,6 +951,7 @@ declare class TinyCloudNode {
      * @internal
      */
     private setupAuth;
+    private shouldUseBootstrapSignInRequest;
     private syncResolvedHostFromAuth;
     /**
      * Install or replace the manifest that drives the SIWE recap at
@@ -985,12 +1022,16 @@ declare class TinyCloudNode {
      */
     signIn(options?: SignInOptions): Promise<void>;
     private ownedSpaceId;
+    private bootstrapAccountIfNeeded;
+    private isFreshBootstrapAccount;
+    private runAccountBootstrap;
+    private registerBootstrapRuntimeGrant;
     private writeManifestRegistryRecords;
     private scheduleAccountRegistrySync;
     private withAccountRegistryRetry;
     private requestedEncryptionNetworkIds;
     private ensureRequestedEncryptionNetworks;
-    private ensureOwnedSpaceHosted;
+    private ensureOwnedSpaceHostedById;
     /**
      * Host one of this user's owned spaces by name (e.g. `"applications"`).
      *
@@ -1001,7 +1042,7 @@ declare class TinyCloudNode {
      * caller is the root authority of their own owned spaces, so no additional
      * delegation is required.
      *
-     * Unlike {@link ensureOwnedSpaceHosted}, this always submits the host
+     * Unlike {@link ensureOwnedSpaceHostedById}, this always submits the host
      * delegation rather than inferring hosting from session activation: a space
      * the current session has never referenced is reported neither as
      * `activated` nor `skipped`, so activation-based detection would wrongly
@@ -1012,6 +1053,56 @@ declare class TinyCloudNode {
      * @returns The hosted space URI.
      */
     hostOwnedSpace(name: string): Promise<string>;
+    /**
+     * Ensure one of this user's owned spaces (e.g. `"secrets"`) is hosted on the
+     * server.
+     *
+     * At sign-in, a full-authority session auto-hosts the owner's `secrets`
+     * space, but a session created with a manifest / capabilityRequest does not.
+     * Such a session can therefore hold valid `tinycloud.kv/*` capabilities for
+     * the owned `secrets` space yet still fail its first scoped
+     * `secrets.put(...)` with `404 Space not found`, because the space was never
+     * registered on the node.
+     *
+     * Calling this resolves `name` to the owner's owned-space URI
+     * (`tinycloud:pkh:eip155:<chain>:<addr>:<name>`). It first consults the
+     * account-space spaces registry (`account/spaces/{space_id}`, the canonical
+     * KV source of truth, fronted by a best-effort SQLite index): if the space is
+     * already registered/hosted it returns the URI WITHOUT submitting a host
+     * delegation, avoiding a redundant host-SIWE signature prompt for owners who
+     * already use the space. Only when the space is absent — or the registry
+     * check fails for any reason (e.g. a cold SQLite index reporting
+     * `no such table: spaces`) — does it fall through to {@link hostOwnedSpace}.
+     *
+     * The registry check is purely an optimization: any failure falls back to
+     * hosting, and the host SIWE is idempotent server-side, so re-hosting an
+     * existing space remains a safe no-op. Must be called after {@link signIn}.
+     *
+     * @param name - The owned space name (e.g. `"secrets"`).
+     * @returns The hosted owned-space URI.
+     */
+    ensureOwnedSpaceHosted(name: string): Promise<string>;
+    /**
+     * Check whether an owned space is already registered/hosted by consulting the
+     * account spaces registry.
+     *
+     * Source of truth is the canonical KV registry record
+     * `account/spaces/{space_id}`, read here via `account.spaces.get(spaceId)`.
+     * The KV path is used (rather than `syncAccessible()`) because it works under
+     * a manifest/recap session with NO extra prompt: the composed manifest recap
+     * already grants `tinycloud.kv get/list` on the account space `spaces/`
+     * prefix, whereas `syncAccessible()` depends on `tinycloud.space/list`, which
+     * a recap session does not hold. Before reading, it consults the fast SQLite
+     * index (`account.index.spaces.list()`) as a best-effort short-circuit; on a
+     * cold index (`no such table: spaces`) or any other index failure it falls
+     * back to the canonical KV read.
+     *
+     * This is a best-effort optimization. ANY failure of the check path (missing
+     * table, KV error, missing record, thrown exception) resolves to `false` so
+     * the caller falls through to hosting — per the directive, "if it fails in any
+     * way then create the space".
+     */
+    private isOwnedSpaceRegistered;
     /**
      * Restore a previously established session from stored delegation data.
      *
@@ -1046,7 +1137,32 @@ declare class TinyCloudNode {
          * for callers that need to round-trip the full session shape.
          */
         signature?: string;
+        /**
+         * The TinyCloud hosts this session was created against (from
+         * {@link PersistedSessionData.tinycloudHosts}). When present they are
+         * adopted so the restored session targets the same node as the
+         * original sign-in — without this, service calls fall back to the
+         * default host and the auth layer throws "TinyCloud hosts have not
+         * been resolved". When absent (old persisted session) hosts resolve
+         * lazily via the registry/fallback on the first host-needing call.
+         */
+        tinycloudHosts?: string[];
     }): Promise<void>;
+    /**
+     * Resolve the host a restored session should target.
+     *
+     * Mirrors fresh sign-in host resolution but for the restore path:
+     * an explicit/pinned host always wins, then the hosts the session was
+     * persisted with, then a lazy registry/fallback resolution for sessions
+     * that predate the persisted `tinycloudHosts` field. Returns `undefined`
+     * only when there's nothing to resolve from (no explicit host, no
+     * persisted hosts, and no address/chainId) — in which case the existing
+     * `config.host` (default) is left in place.
+     *
+     * Resolution failures are surfaced, not swallowed: a genuinely broken
+     * registry lookup throws rather than silently falling back to a wrong host.
+     */
+    private resolveRestoredHost;
     /**
      * Resolve the currently-active TinyCloudSession, preferring the auth
      * layer's value (wallet mode) and falling back to the node-level

package/dist/{core-iwTdsebf.d.ts → core-DfE4s_Rg.d.ts}

@@ -1,6 +1,6 @@
 import { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, IWasmBindings, SiweConfig, Manifest, ComposedManifestRequest, ClientSession, TinyCloudSession, Extension, SignInOptions, Delegation, DelegatedResource, PermissionEntry, TelemetryConfig, IKVService, ISQLService, IDuckDbService, IHooksService, INotificationHandler, IENSResolver, AccountService, IDataVaultService, IEncryptionService, NetworkDescriptor, ISecretsService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISpace, ISharingService, CreateDelegationParams, DelegationResult, ResolvedDelegate, KeyProvider, ISessionManager, JWK } from '@tinycloud/sdk-core';
 import { EventEmitter } from 'events';
-import { InvokeFunction } from '@tinycloud/sdk-services';
+import { InvokeFunction, InvokeAnyFunction } from '@tinycloud/sdk-services';
 
 /**
  * In-memory session storage for Node.js.
@@ -230,6 +230,11 @@ interface NodeUserAuthorizationConfig {
     /** Include implicit account registry permissions when composing `manifest`. Default true. */
     includeAccountRegistryPermissions?: boolean;
 }
+interface CreateBootstrapSessionOptions {
+    spaceId: string;
+    capabilityRequest: ComposedManifestRequest;
+    rawAbilities?: Record<string, string[]>;
+}
 /**
  * Node.js implementation of IUserAuthorization.
  *
@@ -296,6 +301,7 @@ declare class NodeUserAuthorization implements IUserAuthorization {
     private _address?;
     private _chainId?;
     private _nodeFeatures;
+    private _lastActivationSkippedSpaceIds;
     constructor(config: NodeUserAuthorizationConfig);
     /**
      * Return the manifest currently driving sign-in behavior, or
@@ -332,12 +338,36 @@ declare class NodeUserAuthorization implements IUserAuthorization {
      * `siwe` is the load-bearing one because `extractSiweExpiration` returns
      * undefined for missing SIWEs and the SDK then treats the session as
      * expired-at-epoch-zero.
+     *
+     * @param hosts - The TinyCloud hosts this session was created against,
+     *   as persisted in {@link PersistedSessionData.tinycloudHosts}. When
+     *   present (and non-empty) they are adopted directly so the restored
+     *   session resolves to the same node as the original sign-in without
+     *   re-running registry/fallback resolution. When absent (old session)
+     *   hosts are resolved lazily on the first host-needing call via
+     *   {@link ensureTinyCloudHosts}.
+     */
+    setRestoredTinyCloudSession(session: TinyCloudSession, hosts?: string[]): void;
+    /**
+     * Ensure `tinycloudHosts` are resolved before a host-needing call.
+     *
+     * Fresh sign-in resolves hosts up front; a restored session may not have
+     * (old persisted sessions predate {@link PersistedSessionData.tinycloudHosts}).
+     * This guard makes a restored session resolve the node exactly like a fresh
+     * sign-in — persisted hosts are preferred (already set by
+     * {@link setRestoredTinyCloudSession}), otherwise the registry/fallback
+     * resolution runs lazily here. Idempotent: {@link resolveTinyCloudHostsForSignIn}
+     * early-returns when hosts are already set.
+     *
+     * Throws if hosts are unset and the restored session has no address/chainId
+     * to resolve from — a real failure that must surface, not be masked.
      */
-    setRestoredTinyCloudSession(session: TinyCloudSession): void;
+    ensureTinyCloudHosts(): Promise<void>;
     private resolveTinyCloudHostsForSignIn;
     private requireTinyCloudHosts;
     private get primaryTinyCloudHost();
     get nodeFeatures(): string[];
+    get lastActivationSkippedSpaceIds(): string[];
     /**
      * Compute the `abilities` map the WASM `prepareSession` call should
      * see at sign-in time.
@@ -410,6 +440,8 @@ declare class NodeUserAuthorization implements IUserAuthorization {
      * @throws Error if space creation fails
      */
     ensureSpaceExists(): Promise<void>;
+    private recordActivationSkippedSpaces;
+    createBootstrapSession(options: CreateBootstrapSessionOptions): Promise<TinyCloudSession>;
     /**
      * Sign in and create a new session.
      *
@@ -650,7 +682,7 @@ declare class DelegatedAccess {
     private _sql;
     private _duckdb;
     private _hooks;
-    constructor(session: TinyCloudSession, delegation: PortableDelegation, host: string, invoke: InvokeFunction, telemetry?: TelemetryConfig);
+    constructor(session: TinyCloudSession, delegation: PortableDelegation, host: string, invoke: InvokeFunction, invokeAny?: InvokeAnyFunction, telemetry?: TelemetryConfig);
     /**
      * Get the delegation this access was created from.
      */
@@ -731,6 +763,8 @@ interface TinyCloudNodeConfig {
     privateKey?: string;
     /** Custom signer implementation. If provided, takes precedence over privateKey. */
     signer?: ISigner;
+    /** Strategy for root signature requests. Defaults to auto-sign for local keys. */
+    signStrategy?: SignStrategy;
     /** Explicit TinyCloud server URL. When omitted, signIn resolves the user's host. */
     host?: string;
     /** TinyCloud location registry URL. Default: https://registry.tinycloud.xyz. */
@@ -786,6 +820,8 @@ interface TinyCloudNodeConfig {
     capabilityRequest?: ComposedManifestRequest;
     /** Include implicit account registry permissions when composing `manifest`. Default true. */
     includeAccountRegistryPermissions?: boolean;
+    /** Run canonical first-account bootstrap when fresh account state is detected. Default true. */
+    autoBootstrapAccount?: boolean;
     /** Default-off service telemetry. */
     telemetry?: TelemetryConfig;
 }
@@ -915,6 +951,7 @@ declare class TinyCloudNode {
      * @internal
      */
     private setupAuth;
+    private shouldUseBootstrapSignInRequest;
     private syncResolvedHostFromAuth;
     /**
      * Install or replace the manifest that drives the SIWE recap at
@@ -985,12 +1022,16 @@ declare class TinyCloudNode {
      */
     signIn(options?: SignInOptions): Promise<void>;
     private ownedSpaceId;
+    private bootstrapAccountIfNeeded;
+    private isFreshBootstrapAccount;
+    private runAccountBootstrap;
+    private registerBootstrapRuntimeGrant;
     private writeManifestRegistryRecords;
     private scheduleAccountRegistrySync;
     private withAccountRegistryRetry;
     private requestedEncryptionNetworkIds;
     private ensureRequestedEncryptionNetworks;
-    private ensureOwnedSpaceHosted;
+    private ensureOwnedSpaceHostedById;
     /**
      * Host one of this user's owned spaces by name (e.g. `"applications"`).
      *
@@ -1001,7 +1042,7 @@ declare class TinyCloudNode {
      * caller is the root authority of their own owned spaces, so no additional
      * delegation is required.
      *
-     * Unlike {@link ensureOwnedSpaceHosted}, this always submits the host
+     * Unlike {@link ensureOwnedSpaceHostedById}, this always submits the host
      * delegation rather than inferring hosting from session activation: a space
      * the current session has never referenced is reported neither as
      * `activated` nor `skipped`, so activation-based detection would wrongly
@@ -1012,6 +1053,56 @@ declare class TinyCloudNode {
      * @returns The hosted space URI.
      */
     hostOwnedSpace(name: string): Promise<string>;
+    /**
+     * Ensure one of this user's owned spaces (e.g. `"secrets"`) is hosted on the
+     * server.
+     *
+     * At sign-in, a full-authority session auto-hosts the owner's `secrets`
+     * space, but a session created with a manifest / capabilityRequest does not.
+     * Such a session can therefore hold valid `tinycloud.kv/*` capabilities for
+     * the owned `secrets` space yet still fail its first scoped
+     * `secrets.put(...)` with `404 Space not found`, because the space was never
+     * registered on the node.
+     *
+     * Calling this resolves `name` to the owner's owned-space URI
+     * (`tinycloud:pkh:eip155:<chain>:<addr>:<name>`). It first consults the
+     * account-space spaces registry (`account/spaces/{space_id}`, the canonical
+     * KV source of truth, fronted by a best-effort SQLite index): if the space is
+     * already registered/hosted it returns the URI WITHOUT submitting a host
+     * delegation, avoiding a redundant host-SIWE signature prompt for owners who
+     * already use the space. Only when the space is absent — or the registry
+     * check fails for any reason (e.g. a cold SQLite index reporting
+     * `no such table: spaces`) — does it fall through to {@link hostOwnedSpace}.
+     *
+     * The registry check is purely an optimization: any failure falls back to
+     * hosting, and the host SIWE is idempotent server-side, so re-hosting an
+     * existing space remains a safe no-op. Must be called after {@link signIn}.
+     *
+     * @param name - The owned space name (e.g. `"secrets"`).
+     * @returns The hosted owned-space URI.
+     */
+    ensureOwnedSpaceHosted(name: string): Promise<string>;
+    /**
+     * Check whether an owned space is already registered/hosted by consulting the
+     * account spaces registry.
+     *
+     * Source of truth is the canonical KV registry record
+     * `account/spaces/{space_id}`, read here via `account.spaces.get(spaceId)`.
+     * The KV path is used (rather than `syncAccessible()`) because it works under
+     * a manifest/recap session with NO extra prompt: the composed manifest recap
+     * already grants `tinycloud.kv get/list` on the account space `spaces/`
+     * prefix, whereas `syncAccessible()` depends on `tinycloud.space/list`, which
+     * a recap session does not hold. Before reading, it consults the fast SQLite
+     * index (`account.index.spaces.list()`) as a best-effort short-circuit; on a
+     * cold index (`no such table: spaces`) or any other index failure it falls
+     * back to the canonical KV read.
+     *
+     * This is a best-effort optimization. ANY failure of the check path (missing
+     * table, KV error, missing record, thrown exception) resolves to `false` so
+     * the caller falls through to hosting — per the directive, "if it fails in any
+     * way then create the space".
+     */
+    private isOwnedSpaceRegistered;
     /**
      * Restore a previously established session from stored delegation data.
      *
@@ -1046,7 +1137,32 @@ declare class TinyCloudNode {
          * for callers that need to round-trip the full session shape.
          */
         signature?: string;
+        /**
+         * The TinyCloud hosts this session was created against (from
+         * {@link PersistedSessionData.tinycloudHosts}). When present they are
+         * adopted so the restored session targets the same node as the
+         * original sign-in — without this, service calls fall back to the
+         * default host and the auth layer throws "TinyCloud hosts have not
+         * been resolved". When absent (old persisted session) hosts resolve
+         * lazily via the registry/fallback on the first host-needing call.
+         */
+        tinycloudHosts?: string[];
     }): Promise<void>;
+    /**
+     * Resolve the host a restored session should target.
+     *
+     * Mirrors fresh sign-in host resolution but for the restore path:
+     * an explicit/pinned host always wins, then the hosts the session was
+     * persisted with, then a lazy registry/fallback resolution for sessions
+     * that predate the persisted `tinycloudHosts` field. Returns `undefined`
+     * only when there's nothing to resolve from (no explicit host, no
+     * persisted hosts, and no address/chainId) — in which case the existing
+     * `config.host` (default) is left in place.
+     *
+     * Resolution failures are surfaced, not swallowed: a genuinely broken
+     * registry lookup throws rather than silently falling back to a wrong host.
+     */
+    private resolveRestoredHost;
     /**
      * Resolve the currently-active TinyCloudSession, preferring the auth
      * layer's value (wallet mode) and falling back to the node-level