@tinycloud/node-sdk 1.6.0 → 2.0.0

package/dist/core.d.ts

@@ -0,0 +1,1114 @@
+import { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, IWasmBindings, ClientSession, TinyCloudSession, Extension, Delegation, IKVService, ISQLService, IDuckDbService, INotificationHandler, IENSResolver, IDataVaultService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISharingService, CreateDelegationParams, DelegationResult, KeyProvider, ISessionManager, JWK } from '@tinycloud/sdk-core';
+export { AutoApproveSpaceCreationHandler, AutoRejectStrategy, AutoSignStrategy, BatchOptions, BatchResponse, CallbackStrategy, CapabilityEntry, CapabilityKeyRegistry, CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, ClientSession, ColumnInfo, CreateDelegationParams, DataVaultConfig, DataVaultService, DatabaseHandle, Delegation, DelegationChain, DelegationChainV2, DelegationDirection, DelegationError, DelegationErrorCode, DelegationErrorCodes, DelegationFilters, DelegationManager, DelegationManagerConfig, DelegationRecord, DelegationResult, DuckDbAction, DuckDbActionType, DuckDbBatchOptions, DuckDbBatchResponse, DuckDbDatabaseHandle, DuckDbExecuteOptions, DuckDbExecuteResponse, DuckDbOptions, DuckDbQueryOptions, DuckDbQueryResponse, DuckDbService, DuckDbServiceConfig, DuckDbStatement, DuckDbValue, EncodedShareData, ExecuteOptions, ExecuteResponse, Extension, FetchFunction, GenerateShareParams, ICapabilityKeyRegistry, IDataVaultService, IDatabaseHandle, IDuckDbDatabaseHandle, IDuckDbService, IENSResolver, IKVService, INotificationHandler, IPrefixedKVService, ISQLService, ISessionManager, ISessionStorage, ISharingService, ISigner, ISpace, ISpaceCreationHandler, ISpaceScopedDelegations, ISpaceScopedSharing, ISpaceService, IUserAuthorization, IWasmBindings, IngestOptions, InvokeFunction, JWK, KVResponse, KVService, KVServiceConfig, KeyInfo, KeyProvider, KeyType, PersistedSessionData, PrefixedKVService, ProtocolMismatchError, QueryOptions, QueryResponse, ReceiveOptions, SQLAction, SQLActionType, SQLService, SQLServiceConfig, SchemaInfo, ServiceContext, ServiceContextConfig, ServiceSession, ShareAccess, ShareLink, ShareLinkData, ShareSchema, SharingService, SharingServiceConfig, SignCallback, SignRequest, SignResponse, SilentNotificationHandler, Space, SpaceConfig, SpaceCreationContext, SpaceErrorCode, SpaceErrorCodes, SpaceInfo, SpaceOwnership, SpaceService, SpaceServiceConfig, SqlStatement, SqlValue, StoredDelegationChain, TableInfo, TinyCloud, TinyCloudConfig, TinyCloudSession, UnsupportedFeatureError, VaultCrypto, VaultEntry, VaultError, VaultGetOptions, VaultGrantOptions, VaultHeaders, VaultListOptions, VaultPublicSpaceKVActions, VaultPutOptions, VersionCheckError, ViewInfo, WasmVaultFunctions, buildSpaceUri, checkNodeInfo, createCapabilityKeyRegistry, createSharingService, createSpaceService, createVaultCrypto, defaultSpaceCreationHandler, makePublicSpaceId, parseSpaceUri } from '@tinycloud/sdk-core';
+import { EventEmitter } from 'events';
+import { InvokeFunction } from '@tinycloud/sdk-services';
+
+/**
+ * In-memory session storage for Node.js.
+ *
+ * Sessions are stored in memory and lost when the process exits.
+ * Suitable for:
+ * - Development and testing
+ * - Stateless server deployments
+ * - Short-lived processes
+ *
+ * @example
+ * ```typescript
+ * const storage = new MemorySessionStorage();
+ * await storage.save("0x123...", sessionData);
+ * const session = await storage.load("0x123...");
+ * ```
+ */
+declare class MemorySessionStorage implements ISessionStorage {
+    private sessions;
+    /**
+     * Save a session for an address.
+     */
+    save(address: string, session: PersistedSessionData): Promise<void>;
+    /**
+     * Load a session for an address.
+     */
+    load(address: string): Promise<PersistedSessionData | null>;
+    /**
+     * Clear a session for an address.
+     */
+    clear(address: string): Promise<void>;
+    /**
+     * Check if a session exists for an address.
+     */
+    exists(address: string): boolean;
+    /**
+     * Memory storage is always available.
+     */
+    isAvailable(): boolean;
+    /**
+     * Clear all sessions.
+     */
+    clearAll(): void;
+    /**
+     * Get the number of stored sessions.
+     */
+    size(): number;
+}
+
+/**
+ * File-based session storage for Node.js.
+ *
+ * Sessions are persisted to the file system and survive process restarts.
+ * Suitable for:
+ * - CLI applications
+ * - Long-running server processes
+ * - Development environments
+ *
+ * @example
+ * ```typescript
+ * const storage = new FileSessionStorage("/tmp/tinycloud-sessions");
+ * await storage.save("0x123...", sessionData);
+ * // Session persists across process restarts
+ * ```
+ */
+declare class FileSessionStorage implements ISessionStorage {
+    private readonly baseDir;
+    /**
+     * Create a new FileSessionStorage.
+     *
+     * @param baseDir - Directory to store session files (default: ~/.tinycloud/sessions)
+     */
+    constructor(baseDir?: string);
+    /**
+     * Get the default session storage directory.
+     */
+    private getDefaultDir;
+    /**
+     * Ensure the storage directory exists.
+     */
+    private ensureDirectoryExists;
+    /**
+     * Get the file path for an address.
+     */
+    private getFilePath;
+    /**
+     * Save a session for an address.
+     */
+    save(address: string, session: PersistedSessionData): Promise<void>;
+    /**
+     * Load a session for an address.
+     */
+    load(address: string): Promise<PersistedSessionData | null>;
+    /**
+     * Clear a session for an address.
+     */
+    clear(address: string): Promise<void>;
+    /**
+     * Check if a session exists for an address.
+     */
+    exists(address: string): boolean;
+    /**
+     * Check if file system storage is available.
+     */
+    isAvailable(): boolean;
+}
+
+/**
+ * Node.js-specific SignStrategy types for TinyCloud authorization.
+ *
+ * This module re-exports common types from sdk-core and provides
+ * Node.js-specific implementations (e.g., NodeEventEmitterStrategy
+ * using Node's EventEmitter instead of browser EventTarget).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Node.js event emitter strategy: emits sign requests as events.
+ *
+ * Uses Node.js EventEmitter for compatibility with Node.js applications.
+ * For browser environments, use the EventEmitterStrategy from sdk-core
+ * which uses EventTarget.
+ *
+ * Events emitted:
+ * - 'sign-request': When a sign request is received
+ *
+ * Use cases:
+ * - Async approval workflows in Node.js
+ * - External signing services
+ * - Multi-step authorization flows
+ *
+ * @example
+ * ```typescript
+ * const emitter = new EventEmitter();
+ * const strategy: NodeEventEmitterStrategy = { type: 'event-emitter', emitter };
+ *
+ * emitter.on('sign-request', async (req, respond) => {
+ *   const approved = await externalApprovalService.check(req);
+ *   respond({ approved, signature: approved ? await sign(req.message) : undefined });
+ * });
+ * ```
+ */
+interface NodeEventEmitterStrategy {
+    type: "event-emitter";
+    emitter: EventEmitter;
+    /** Timeout in milliseconds for waiting on event response (default: 60000) */
+    timeout?: number;
+}
+/**
+ * Node.js sign strategy union type.
+ *
+ * Determines how sign requests are handled in NodeUserAuthorization.
+ * Uses Node.js EventEmitter for the event-emitter strategy.
+ */
+type SignStrategy = AutoSignStrategy | AutoRejectStrategy | CallbackStrategy | NodeEventEmitterStrategy;
+/**
+ * Default sign strategy is auto-sign for convenience.
+ * This is the Node.js-specific version typed with SignStrategy.
+ */
+declare const defaultSignStrategy: SignStrategy;
+
+/**
+ * Configuration for NodeUserAuthorization.
+ */
+interface NodeUserAuthorizationConfig {
+    /** The signer used for signing messages */
+    signer: ISigner;
+    /** Sign strategy for handling sign requests */
+    signStrategy?: SignStrategy;
+    /** Session storage implementation */
+    sessionStorage?: ISessionStorage;
+    /** Domain for SIWE messages */
+    domain: string;
+    /** URI for SIWE messages (default: domain) */
+    uri?: string;
+    /** Statement included in SIWE messages */
+    statement?: string;
+    /** Space prefix for new sessions */
+    spacePrefix?: string;
+    /** Default actions for sessions */
+    defaultActions?: Record<string, Record<string, string[]>>;
+    /** Session expiration time in milliseconds (default: 1 hour) */
+    sessionExpirationMs?: number;
+    /** Automatically create space if it doesn't exist (default: false) */
+    autoCreateSpace?: boolean;
+    /** Custom space creation handler. If provided, takes precedence over autoCreateSpace. */
+    spaceCreationHandler?: ISpaceCreationHandler;
+    /** TinyCloud server endpoints (default: ["https://node.tinycloud.xyz"]) */
+    tinycloudHosts?: string[];
+    /** Whether to include public space capabilities in the session (default: true) */
+    enablePublicSpace?: boolean;
+    /** WASM bindings for cryptographic operations. Required. */
+    wasmBindings: IWasmBindings;
+}
+/**
+ * Node.js implementation of IUserAuthorization.
+ *
+ * Supports multiple sign strategies for different use cases:
+ * - auto-sign: Automatically approve all sign requests (trusted backends)
+ * - auto-reject: Reject all sign requests (read-only mode)
+ * - callback: Delegate to a custom callback function (CLI prompts)
+ * - event-emitter: Emit sign requests as events (async workflows)
+ *
+ * @example
+ * ```typescript
+ * // Auto-sign for backend services
+ * const auth = new NodeUserAuthorization({
+ *   signer: new PrivateKeySigner(process.env.PRIVATE_KEY),
+ *   signStrategy: { type: 'auto-sign' },
+ *   domain: 'api.myapp.com',
+ * });
+ *
+ * // Callback for CLI prompts
+ * const auth = new NodeUserAuthorization({
+ *   signer,
+ *   signStrategy: {
+ *     type: 'callback',
+ *     handler: async (req) => {
+ *       const approved = await promptUser(`Sign for ${req.address}?`);
+ *       return { approved };
+ *     }
+ *   },
+ *   domain: 'cli.myapp.com',
+ * });
+ * ```
+ */
+declare class NodeUserAuthorization implements IUserAuthorization {
+    private readonly signer;
+    private readonly signStrategy;
+    private readonly sessionStorage;
+    private readonly domain;
+    private readonly uri;
+    private readonly statement?;
+    private readonly spacePrefix;
+    private readonly defaultActions;
+    private readonly sessionExpirationMs;
+    private readonly autoCreateSpace;
+    private readonly spaceCreationHandler?;
+    private readonly tinycloudHosts;
+    private readonly enablePublicSpace;
+    private readonly wasm;
+    private sessionManager;
+    private extensions;
+    private _session?;
+    private _tinyCloudSession?;
+    private _address?;
+    private _chainId?;
+    private _nodeFeatures;
+    constructor(config: NodeUserAuthorizationConfig);
+    /**
+     * The current active session (web-core compatible).
+     */
+    get session(): ClientSession | undefined;
+    /**
+     * The current TinyCloud session with full delegation data.
+     * Includes spaceId, delegationHeader, and delegationCid.
+     */
+    get tinyCloudSession(): TinyCloudSession | undefined;
+    get nodeFeatures(): string[];
+    /**
+     * Add an extension to the authorization flow.
+     */
+    extend(extension: Extension): void;
+    /**
+     * Get the space ID for the current session.
+     */
+    getSpaceId(): string | undefined;
+    /**
+     * Create the space on the TinyCloud server (host delegation).
+     * This registers the user as the owner of the space.
+     */
+    private hostSpace;
+    /**
+     * Create a specific space on the server via host delegation.
+     * Used for lazy creation of additional spaces (e.g., public).
+     */
+    hostPublicSpace(spaceId: string): Promise<boolean>;
+    /**
+     * Ensure the user's space exists on the TinyCloud server.
+     * Creates the space if it doesn't exist and autoCreateSpace is enabled.
+     * If autoCreateSpace is false and space doesn't exist, silently returns
+     * (user may be using delegations to access other spaces).
+     *
+     * @throws Error if space creation fails
+     */
+    ensureSpaceExists(): Promise<void>;
+    /**
+     * Sign in and create a new session.
+     *
+     * This follows the correct SIWE-ReCap flow:
+     * 1. Create session key and get JWK
+     * 2. Call prepareSession() which generates the SIWE with ReCap capabilities
+     * 3. Sign the SIWE string from prepareSession
+     * 4. Call completeSessionSetup() with the prepared session + signature
+     */
+    signIn(): Promise<ClientSession>;
+    /**
+     * Sign out and clear the current session.
+     */
+    signOut(): Promise<void>;
+    /**
+     * Get the current wallet/signer address.
+     */
+    address(): string | undefined;
+    /**
+     * Get the current chain ID.
+     */
+    chainId(): number | undefined;
+    /**
+     * Sign a message with the connected signer.
+     */
+    signMessage(message: string): Promise<string>;
+    /**
+     * Prepare a session for external signing.
+     *
+     * Use this method when you need to sign the SIWE message externally (e.g., via
+     * a hardware wallet, multi-sig, or external service). After obtaining the signature,
+     * call `signInWithPreparedSession()` to complete the sign-in.
+     *
+     * @example
+     * ```typescript
+     * const { prepared, keyId, jwk } = await auth.prepareSessionForSigning();
+     * const signature = await externalSigner.signMessage(prepared.siwe);
+     * const session = await auth.signInWithPreparedSession(prepared, signature, keyId, jwk);
+     * ```
+     */
+    prepareSessionForSigning(): Promise<{
+        prepared: {
+            siwe: string;
+            jwk: Record<string, unknown>;
+            spaceId: string;
+            verificationMethod: string;
+        };
+        keyId: string;
+        jwk: Record<string, unknown>;
+        address: string;
+        chainId: number;
+    }>;
+    /**
+     * Complete sign-in with a prepared session and signature.
+     *
+     * Use this method after obtaining a signature for the SIWE message from
+     * `prepareSessionForSigning()`. The signature MUST be over `prepared.siwe`.
+     *
+     * @param prepared - The prepared session from `prepareSessionForSigning()`
+     * @param signature - The signature over `prepared.siwe`
+     * @param keyId - The session key ID from `prepareSessionForSigning()`
+     * @param jwk - The JWK from `prepareSessionForSigning()`
+     */
+    signInWithPreparedSession(prepared: {
+        siwe: string;
+        jwk: Record<string, unknown>;
+        spaceId: string;
+        verificationMethod: string;
+    }, signature: string, keyId: string, jwk: Record<string, unknown>): Promise<ClientSession>;
+    /**
+     * Clear persisted session data.
+     */
+    clearPersistedSession(address?: string): Promise<void>;
+    /**
+     * Check if a session is persisted for an address.
+     */
+    isSessionPersisted(address: string): boolean;
+    /**
+     * Request a signature based on the configured strategy.
+     */
+    private requestSignature;
+    /**
+     * Request signature via event emitter with timeout.
+     */
+    private requestSignatureViaEmitter;
+}
+
+/**
+ * A portable delegation that can be transported between users.
+ * Extends the base Delegation type with fields required for transport.
+ *
+ * @remarks
+ * PortableDelegation adds transport fields to Delegation:
+ * - `delegationHeader`: Structured authorization header for API calls
+ * - `ownerAddress`: Space owner's address for session creation
+ * - `chainId`: Chain ID for session creation
+ * - `host`: Optional server URL
+ */
+interface PortableDelegation extends Omit<Delegation, "isRevoked"> {
+    /** The authorization header for this delegation (structured format) */
+    delegationHeader: {
+        Authorization: string;
+    };
+    /** The address of the space owner */
+    ownerAddress: string;
+    /** The chain ID */
+    chainId: number;
+    /** TinyCloud server URL where this delegation was created */
+    host?: string;
+    /** Whether the recipient is prevented from creating sub-delegations */
+    disableSubDelegation?: boolean;
+    /** Companion delegation for the user's public space (auto-created when includePublicSpace is true) */
+    publicDelegation?: PortableDelegation;
+}
+/**
+ * Serialize a PortableDelegation for transport (e.g., over network).
+ */
+declare function serializeDelegation(delegation: PortableDelegation): string;
+/**
+ * Deserialize a PortableDelegation from transport.
+ */
+declare function deserializeDelegation(data: string): PortableDelegation;
+
+/**
+ * Provides access to a space via a received delegation.
+ *
+ * This is returned by TinyCloudNode.useDelegation() and provides
+ * KV operations on the delegated space.
+ */
+declare class DelegatedAccess {
+    private session;
+    private _delegation;
+    private host;
+    private _serviceContext;
+    private _kv;
+    private _sql;
+    private _duckdb;
+    constructor(session: TinyCloudSession, delegation: PortableDelegation, host: string, invoke: InvokeFunction);
+    /**
+     * Get the delegation this access was created from.
+     */
+    get delegation(): PortableDelegation;
+    /**
+     * The space ID this access is for.
+     */
+    get spaceId(): string;
+    /**
+     * The path this access is scoped to.
+     */
+    get path(): string;
+    /**
+     * KV operations on the delegated space.
+     */
+    get kv(): IKVService;
+    /**
+     * SQL operations on the delegated space.
+     */
+    get sql(): ISQLService;
+    /**
+     * DuckDB operations on the delegated space.
+     */
+    get duckdb(): IDuckDbService;
+}
+
+/**
+ * TinyCloudNode - High-level API for Node.js users.
+ *
+ * Each user has their own TinyCloudNode instance with their own key.
+ * This class provides a simplified interface for:
+ * - Signing in and managing sessions
+ * - Key-value storage operations on own space
+ * - Creating and using delegations
+ *
+ * @example
+ * ```typescript
+ * const alice = new TinyCloudNode({
+ *   privateKey: process.env.ALICE_PRIVATE_KEY,
+ *   host: "https://node.tinycloud.xyz",
+ *   prefix: "myapp",
+ * });
+ *
+ * await alice.signIn();
+ * await alice.kv.put("greeting", "Hello, world!");
+ *
+ * // Delegate access to Bob
+ * const delegation = await alice.createDelegation({
+ *   path: "shared/",
+ *   actions: ["tinycloud.kv/get", "tinycloud.kv/put"],
+ *   delegateDID: bob.did,
+ * });
+ *
+ * // Bob uses the delegation
+ * const access = await bob.useDelegation(delegation);
+ * const data = await access.kv.get("shared/data");
+ * ```
+ */
+
+/**
+ * Configuration for TinyCloudNode.
+ * All fields are optional - TinyCloudNode can work with zero configuration.
+ */
+interface TinyCloudNodeConfig {
+    /** Hex-encoded private key (with or without 0x prefix). Optional - only needed for wallet mode and signIn() */
+    privateKey?: string;
+    /** Custom signer implementation. If provided, takes precedence over privateKey. */
+    signer?: ISigner;
+    /** TinyCloud server URL (default: "https://node.tinycloud.xyz") */
+    host?: string;
+    /** Space prefix for this user's space. Optional - only needed for signIn() */
+    prefix?: string;
+    /** Domain for SIWE messages (default: derived from host) */
+    domain?: string;
+    /** Session expiration time in milliseconds (default: 1 hour) */
+    sessionExpirationMs?: number;
+    /** Whether to automatically create space if it doesn't exist (default: false) */
+    autoCreateSpace?: boolean;
+    /** Custom session storage implementation (default: MemorySessionStorage) */
+    sessionStorage?: ISessionStorage;
+    /** Whether to include public space capabilities in the session (default: true).
+     * When true, signIn() automatically includes capabilities for the user's public space,
+     * accessible via spaces.get('public').kv */
+    enablePublicSpace?: boolean;
+    /** Custom WASM bindings (default: @tinycloud/node-sdk-wasm). Used by browser wrapper. */
+    wasmBindings?: IWasmBindings;
+    /** Notification handler for sign-in/sign-out/error events (default: SilentNotificationHandler) */
+    notificationHandler?: INotificationHandler;
+    /** ENS resolver for resolving .eth names in delegation methods */
+    ensResolver?: IENSResolver;
+    /** Custom space creation handler (default: auto-approve when autoCreateSpace is true) */
+    spaceCreationHandler?: ISpaceCreationHandler;
+}
+/**
+ * High-level TinyCloud API for Node.js environments.
+ *
+ * Each user creates their own TinyCloudNode instance with their private key.
+ * The instance manages the user's session and provides access to their space.
+ */
+/** @internal */
+interface NodeDefaults {
+    createWasmBindings: () => IWasmBindings;
+    createSigner: (privateKey: string, chainId?: number) => ISigner;
+}
+declare class TinyCloudNode {
+    /** @internal Registered by importing @tinycloud/node-sdk (not /core) */
+    private static nodeDefaults?;
+    /** @internal Register Node.js-specific defaults (NodeWasmBindings, PrivateKeySigner) */
+    static registerNodeDefaults(defaults: NodeDefaults): void;
+    private config;
+    private signer;
+    private auth;
+    private tc;
+    private _address?;
+    private _chainId;
+    private wasmBindings;
+    private sessionManager;
+    private _serviceContext?;
+    private _kv?;
+    private _sql?;
+    private _duckdb?;
+    private _vault?;
+    /** Cached public KV with proper delegation (set by ensurePublicSpace) */
+    private _publicKV?;
+    /** Session key ID - always available */
+    private sessionKeyId;
+    /** Session key JWK as object - always available */
+    private sessionKeyJwk;
+    /** Notification handler for user-facing events */
+    private notificationHandler;
+    private _capabilityRegistry;
+    private _keyProvider;
+    private _sharingService;
+    private _delegationManager?;
+    private _spaceService?;
+    private get nodeFeatures();
+    /**
+     * Create a new TinyCloudNode instance.
+     *
+     * All configuration is optional. Without a privateKey, the instance operates
+     * in "session-only" mode where it can receive delegations but cannot create
+     * its own space via signIn().
+     *
+     * @param config - Configuration options (all optional)
+     *
+     * @example
+     * ```typescript
+     * // Session-only mode - can receive delegations
+     * const bob = new TinyCloudNode();
+     * console.log(bob.did); // did:key:z6Mk... - available immediately
+     *
+     * // Wallet mode - can create own space
+     * const alice = new TinyCloudNode({
+     *   privateKey: process.env.ALICE_PRIVATE_KEY,
+     *   prefix: "myapp",
+     * });
+     * await alice.signIn();
+     * ```
+     */
+    constructor(config?: TinyCloudNodeConfig);
+    /**
+     * Set up authorization handler and TinyCloud instance.
+     * @internal
+     */
+    private setupAuth;
+    /**
+     * Get the primary identity DID for this user.
+     * - If wallet connected and signed in: returns PKH DID (did:pkh:eip155:{chainId}:{address})
+     * - If session-only mode: returns session key DID (did:key:z6Mk...)
+     *
+     * Use this for delegations - it always returns the appropriate identity.
+     */
+    get did(): string;
+    /**
+     * Get the session key DID. Always available.
+     * Format: did:key:z6Mk...#z6Mk...
+     *
+     * Use this when you specifically need the session key, not the user identity.
+     */
+    get sessionDid(): string;
+    /**
+     * Get the Ethereum address for this user.
+     */
+    get address(): string | undefined;
+    /**
+     * Check if this instance is in session-only mode (no wallet).
+     * In session-only mode, the instance can receive delegations but cannot
+     * create its own space via signIn().
+     */
+    get isSessionOnly(): boolean;
+    /**
+     * Get the space ID for this user.
+     * Available after signIn().
+     */
+    get spaceId(): string | undefined;
+    /**
+     * Get the current TinyCloud session.
+     * Available after signIn().
+     */
+    get session(): TinyCloudSession | undefined;
+    /**
+     * Sign in and create a new session.
+     * This creates the user's space if it doesn't exist.
+     * Requires wallet mode (privateKey in config).
+     */
+    signIn(): Promise<void>;
+    /**
+     * Restore a previously established session from stored delegation data.
+     *
+     * This is used by the CLI to restore a session that was created via the
+     * browser-based delegation flow (OpenKey `/delegate` page). Instead of
+     * signing in with a private key, it injects the delegation data directly.
+     *
+     * @param sessionData - The stored delegation data from the browser flow
+     */
+    restoreSession(sessionData: {
+        delegationHeader: {
+            Authorization: string;
+        };
+        delegationCid: string;
+        spaceId: string;
+        jwk: object;
+        verificationMethod: string;
+        address?: string;
+        chainId?: number;
+    }): Promise<void>;
+    /**
+     * Connect a wallet to upgrade from session-only mode to wallet mode.
+     *
+     * This allows a user who started in session-only mode to later connect
+     * a wallet and gain the ability to create their own space.
+     *
+     * Note: This does NOT automatically sign in. Call signIn() after connecting
+     * the wallet to create your space.
+     *
+     * @param privateKey - The Ethereum private key (hex string, no 0x prefix)
+     * @param options - Optional configuration
+     * @param options.prefix - Space name prefix (defaults to "default")
+     *
+     * @example
+     * ```typescript
+     * // Start in session-only mode
+     * const node = new TinyCloudNode({ host: "https://node.tinycloud.xyz" });
+     * console.log(node.did); // did:key:z6Mk... (session key)
+     *
+     * // Later, connect a wallet
+     * node.connectWallet(privateKey);
+     * await node.signIn();
+     * console.log(node.did); // did:pkh:eip155:1:0x... (PKH)
+     * ```
+     */
+    connectWallet(privateKey: string, options?: {
+        prefix?: string;
+        sessionStorage?: ISessionStorage;
+    }): void;
+    /**
+     * Connect any ISigner to upgrade from session-only mode to wallet mode.
+     *
+     * Same as connectWallet() but accepts any ISigner implementation instead
+     * of a raw private key string. Use this for browser wallets, hardware wallets,
+     * or custom signing backends.
+     *
+     * Note: This does NOT automatically sign in. Call signIn() after connecting.
+     *
+     * @param signer - Any ISigner implementation
+     * @param options - Optional configuration
+     * @param options.prefix - Space name prefix (defaults to "default")
+     */
+    connectSigner(signer: ISigner, options?: {
+        prefix?: string;
+        sessionStorage?: ISessionStorage;
+    }): void;
+    /**
+     * Initialize the service context and KV service after sign-in.
+     * @internal
+     */
+    private initializeServices;
+    /**
+     * Initialize the v2 delegation system services.
+     * @internal
+     */
+    private initializeV2Services;
+    /**
+     * Get the session expiry time.
+     * @internal
+     */
+    private getSessionExpiry;
+    /**
+     * Wrapper for the WASM createDelegation function.
+     * Adapts the WASM interface to what SharingService expects.
+     * @internal
+     */
+    private createDelegationWrapper;
+    /**
+     * Create a direct root delegation from the wallet to a share key.
+     * This bypasses the session delegation chain, allowing share links
+     * with expiry longer than the current session.
+     * @internal
+     */
+    private createRootDelegationForSharing;
+    /**
+     * Track a received delegation in the capability registry.
+     * @internal
+     */
+    private trackReceivedDelegation;
+    /**
+     * Key-value storage operations on this user's space.
+     */
+    get kv(): IKVService;
+    /**
+     * SQL database operations on this user's space.
+     */
+    get sql(): ISQLService;
+    /**
+     * DuckDB database operations on this user's space.
+     */
+    get duckdb(): IDuckDbService;
+    /**
+     * Data Vault operations - client-side encrypted KV storage.
+     * Call `vault.unlock(signer)` after signIn() to derive encryption keys.
+     */
+    get vault(): IDataVaultService;
+    /**
+     * Get the CapabilityKeyRegistry for managing keys and their capabilities.
+     *
+     * The registry tracks keys (session, main, ingested) and their associated
+     * delegations, enabling automatic key selection for operations.
+     *
+     * @example
+     * ```typescript
+     * const registry = alice.capabilityRegistry;
+     *
+     * // Get the best key for an operation
+     * const key = registry.getKeyForCapability(
+     *   "tinycloud://my-space/kv/data",
+     *   "tinycloud.kv/get"
+     * );
+     *
+     * // List all capabilities
+     * const capabilities = registry.getAllCapabilities();
+     * ```
+     */
+    get capabilityRegistry(): ICapabilityKeyRegistry;
+    /**
+     * Access received delegations (recipient view).
+     *
+     * Use this to see what delegations have been received via useDelegation().
+     *
+     * @example
+     * ```typescript
+     * // List all received delegations
+     * const received = bob.delegations.list();
+     * console.log("I have access to:", received.length, "spaces");
+     *
+     * // Get a specific delegation by CID
+     * const delegation = bob.delegations.get(cid);
+     * ```
+     */
+    get delegations(): {
+        /** List all received delegations */
+        list: () => Delegation[];
+        /** Get a delegation by CID */
+        get: (cid: string) => Delegation | undefined;
+    };
+    /**
+     * Get the DelegationManager for delegation CRUD operations.
+     *
+     * This is the v2 delegation service providing a cleaner API than
+     * the legacy createDelegation/useDelegation methods.
+     *
+     * @example
+     * ```typescript
+     * const delegations = alice.delegationManager;
+     *
+     * // Create a delegation
+     * const result = await delegations.create({
+     *   delegateDID: bob.did,
+     *   path: "shared/",
+     *   actions: ["tinycloud.kv/get", "tinycloud.kv/put"],
+     *   expiry: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
+     * });
+     *
+     * // List delegations
+     * const listResult = await delegations.list();
+     *
+     * // Revoke a delegation
+     * await delegations.revoke(delegationCid);
+     * ```
+     */
+    get delegationManager(): DelegationManager;
+    /**
+     * Get the SpaceService for managing spaces.
+     *
+     * The SpaceService provides access to owned and delegated spaces,
+     * including space creation, listing, and scoped operations.
+     *
+     * @example
+     * ```typescript
+     * const spaces = alice.spaces;
+     *
+     * // List all accessible spaces
+     * const result = await spaces.list();
+     *
+     * // Create a new space
+     * const createResult = await spaces.create('photos');
+     *
+     * // Get a space object for operations
+     * const mySpace = spaces.get('default');
+     * await mySpace.kv.put('key', 'value');
+     *
+     * // Check if a space exists
+     * const exists = await spaces.exists('photos');
+     * ```
+     */
+    get spaces(): ISpaceService;
+    /**
+     * Alias for `spaces` - get the SpaceService.
+     * @see spaces
+     */
+    get spaceService(): ISpaceService;
+    /**
+     * Get the SharingService for creating and receiving v2 sharing links.
+     *
+     * The SharingService creates sharing links with embedded private keys,
+     * allowing recipients to exercise delegations without prior session setup.
+     *
+     * @example
+     * ```typescript
+     * const sharing = alice.sharing;
+     *
+     * // Generate a sharing link
+     * const result = await sharing.generate({
+     *   path: "/kv/documents/report.pdf",
+     *   actions: ["tinycloud.kv/get"],
+     *   expiry: new Date(Date.now() + 24 * 60 * 60 * 1000),
+     * });
+     *
+     * if (result.ok) {
+     *   console.log("Share URL:", result.data.url);
+     *   // Send the URL to the recipient
+     * }
+     *
+     * // Receive a sharing link
+     * const receiveResult = await sharing.receive(shareUrl);
+     * if (receiveResult.ok) {
+     *   // Use the pre-configured KV service
+     *   const data = await receiveResult.data.kv.get("report.pdf");
+     * }
+     * ```
+     */
+    get sharing(): ISharingService;
+    /**
+     * Alias for `sharing` - get the SharingService.
+     * @see sharing
+     */
+    get sharingService(): ISharingService;
+    /**
+     * Ensure the user's public space exists and is accessible.
+     * Creates the space and activates a session delegation for it.
+     * This is the trigger for lazy public space creation — call it
+     * before writing to spaces.get('public').kv.
+     */
+    ensurePublicSpace(): Promise<void>;
+    /**
+     * Get a KVService scoped to the user's own public space.
+     * Writes require authentication (owner/delegate).
+     */
+    get publicKV(): IKVService;
+    /**
+     * Create a delegation using the v2 DelegationManager.
+     *
+     * This is a convenience method that wraps DelegationManager.create().
+     * For more control, use `this.delegationManager` directly.
+     *
+     * @param params - Delegation parameters
+     * @returns Result containing the created Delegation
+     *
+     * @example
+     * ```typescript
+     * const result = await alice.delegate({
+     *   delegateDID: bob.did,
+     *   path: "shared/",
+     *   actions: ["tinycloud.kv/get", "tinycloud.kv/put"],
+     *   expiry: new Date(Date.now() + 24 * 60 * 60 * 1000),
+     * });
+     *
+     * if (result.ok) {
+     *   console.log("Delegation created:", result.data.cid);
+     * }
+     * ```
+     */
+    delegate(params: CreateDelegationParams): Promise<DelegationResult<Delegation>>;
+    /**
+     * Revoke a delegation using the v2 DelegationManager.
+     *
+     * @param cid - The CID of the delegation to revoke
+     * @returns Result indicating success or failure
+     */
+    revokeDelegation(cid: string): Promise<DelegationResult<void>>;
+    /**
+     * List all delegations for the current session's space.
+     *
+     * @returns Result containing an array of Delegations
+     */
+    listDelegations(): Promise<DelegationResult<Delegation[]>>;
+    /**
+     * Check if the current session has permission for a path and action.
+     *
+     * @param path - The resource path to check
+     * @param action - The action to check (e.g., "tinycloud.kv/get")
+     * @returns Result containing boolean permission status
+     */
+    checkPermission(path: string, action: string): Promise<DelegationResult<boolean>>;
+    /**
+     * Create a delegation from this user to another user.
+     *
+     * The delegation grants the recipient access to a specific path and actions
+     * within this user's space.
+     *
+     * @param params - Delegation parameters
+     * @returns A portable delegation that can be sent to the recipient
+     */
+    createDelegation(params: {
+        /** Path within the space to delegate access to */
+        path: string;
+        /** Actions to allow (e.g., ["tinycloud.kv/get", "tinycloud.kv/put"]) */
+        actions: string[];
+        /** DID of the recipient (from their TinyCloudNode.did) */
+        delegateDID: string;
+        /** Whether to prevent the recipient from creating sub-delegations (default: false) */
+        disableSubDelegation?: boolean;
+        /** Expiration time in milliseconds from now (default: 1 hour) */
+        expiryMs?: number;
+        /** Override space ID (for creating delegations to non-primary spaces like public) */
+        spaceIdOverride?: string;
+        /** Include a companion delegation for the user's public space (default: true) */
+        includePublicSpace?: boolean;
+    }): Promise<PortableDelegation>;
+    /**
+     * Use a delegation received from another user.
+     *
+     * This creates a new session key for this user that chains from the
+     * received delegation, allowing operations on the delegator's space.
+     *
+     * Works in both modes:
+     * - **Wallet mode**: Creates a SIWE sub-delegation from PKH to session key
+     * - **Session-only mode**: Uses the delegation directly (must target session key DID)
+     *
+     * @param delegation - The PortableDelegation to use (from createDelegation or transport)
+     * @returns A DelegatedAccess instance for performing operations
+     */
+    useDelegation(delegation: PortableDelegation): Promise<DelegatedAccess>;
+    /**
+     * Create a sub-delegation from a received delegation.
+     *
+     * This allows further delegating access that was received from another user,
+     * if the original delegation allows sub-delegation.
+     *
+     * @param parentDelegation - The delegation received from another user
+     * @param params - Sub-delegation parameters (must be within parent's scope)
+     * @returns A portable delegation for the sub-delegate
+     */
+    createSubDelegation(parentDelegation: PortableDelegation, params: {
+        /** Path within the delegated path to sub-delegate */
+        path: string;
+        /** Actions to allow (must be subset of parent's actions) */
+        actions: string[];
+        /** DID of the recipient */
+        delegateDID: string;
+        /** Whether to prevent the recipient from creating further sub-delegations */
+        disableSubDelegation?: boolean;
+        /** Expiration time in milliseconds from now (must be before parent's expiry) */
+        expiryMs?: number;
+    }): Promise<PortableDelegation>;
+}
+
+/**
+ * WasmKeyProvider - KeyProvider implementation using WASM session manager.
+ *
+ * This provider wraps the SessionManager from node-sdk-wasm to provide
+ * cryptographic key operations required by the SharingService.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extended session manager with optional key listing support.
+ * The base ISessionManager doesn't include listSessionKeys(),
+ * but concrete implementations (e.g., TCWSessionManager) may provide it.
+ */
+interface SessionManagerWithListing extends ISessionManager {
+    listSessionKeys?(): string[];
+}
+/**
+ * Configuration for WasmKeyProvider.
+ */
+interface WasmKeyProviderConfig {
+    /**
+     * The WASM session manager instance.
+     * Must be created before constructing the KeyProvider.
+     */
+    sessionManager: SessionManagerWithListing;
+}
+/**
+ * KeyProvider implementation that wraps the WASM session manager.
+ *
+ * This allows the SharingService to create new session keys for sharing links
+ * using the same cryptographic operations as the main session management.
+ *
+ * @example
+ * ```typescript
+ * // sessionManager from wasmBindings.createSessionManager()
+ * import { WasmKeyProvider } from "@tinycloud/node-sdk";
+ *
+ * const sessionManager = new SessionManager();
+ * const keyProvider = new WasmKeyProvider({ sessionManager });
+ *
+ * // Create a session key for a sharing link
+ * const keyId = await keyProvider.createSessionKey("share:abc123");
+ * const jwk = keyProvider.getJWK(keyId);
+ * const did = await keyProvider.getDID(keyId);
+ * ```
+ */
+declare class WasmKeyProvider implements KeyProvider {
+    private sessionManager;
+    /**
+     * Create a new WasmKeyProvider.
+     *
+     * @param config - Configuration with the WASM session manager
+     */
+    constructor(config: WasmKeyProviderConfig);
+    /**
+     * Generate a new session key with the given name.
+     *
+     * This creates a new Ed25519 key pair in the WASM session manager.
+     * The key can then be used for signing delegations in sharing links.
+     *
+     * @param name - A unique name/ID for the key (e.g., "share:timestamp:random")
+     * @returns The key ID (same as the name provided)
+     */
+    createSessionKey(name: string): Promise<string>;
+    /**
+     * Get the JWK (JSON Web Key) for a key.
+     *
+     * Returns the full JWK including the private key (d parameter),
+     * which is required for signing and for embedding in sharing links.
+     *
+     * @param keyId - The key ID to retrieve
+     * @returns The JWK object with public and private key components
+     * @throws Error if the key is not found
+     */
+    getJWK(keyId: string): JWK;
+    /**
+     * Get the DID (Decentralized Identifier) for a key.
+     *
+     * Returns the did:key format DID derived from the key's public key.
+     * This DID can be used as the delegatee in delegations.
+     *
+     * @param keyId - The key ID to retrieve
+     * @returns The DID in did:key format (e.g., "did:key:z6Mk...")
+     */
+    getDID(keyId: string): Promise<string>;
+    /**
+     * List all session keys currently held by the provider.
+     *
+     * @returns Array of key IDs
+     */
+    listKeys(): string[];
+    /**
+     * Check if a key exists in the provider.
+     *
+     * @param keyId - The key ID to check
+     * @returns True if the key exists
+     */
+    hasKey(keyId: string): boolean;
+}
+/**
+ * Create a new WasmKeyProvider instance.
+ *
+ * @param sessionManager - The WASM session manager
+ * @returns A new WasmKeyProvider instance
+ */
+declare function createWasmKeyProvider(sessionManager: SessionManagerWithListing): WasmKeyProvider;
+
+export { DelegatedAccess, FileSessionStorage, MemorySessionStorage, type NodeEventEmitterStrategy, NodeUserAuthorization, type NodeUserAuthorizationConfig, type PortableDelegation, type SignStrategy, TinyCloudNode, type TinyCloudNodeConfig, WasmKeyProvider, type WasmKeyProviderConfig, createWasmKeyProvider, defaultSignStrategy, deserializeDelegation, serializeDelegation };