@tinycloud/node-sdk 1.2.0 → 1.4.0

package/dist/index.d.cts

@@ -1,6 +1,5 @@
-import * as _tinycloud_sdk_core from '@tinycloud/sdk-core';
-import { ISigner, Bytes, ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ClientSession, TinyCloudSession, Extension, Delegation, IKVService, ISQLService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISharingService, CreateDelegationParams, DelegationResult, KeyProvider, JWK } from '@tinycloud/sdk-core';
-export { AutoRejectStrategy, AutoSignStrategy, BatchOptions, BatchResponse, CallbackStrategy, CapabilityEntry, CapabilityKeyRegistry, CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, ClientSession, CreateDelegationParams, DatabaseHandle, Delegation, DelegationChain, DelegationChainV2, DelegationDirection, DelegationError, DelegationErrorCode, DelegationErrorCodes, DelegationFilters, DelegationManager, DelegationManagerConfig, DelegationRecord, DelegationResult, EncodedShareData, ExecuteOptions, ExecuteResponse, Extension, FetchFunction, GenerateShareParams, ICapabilityKeyRegistry, IDatabaseHandle, IKVService, IPrefixedKVService, ISQLService, ISessionStorage, ISharingService, ISigner, ISpace, ISpaceScopedDelegations, ISpaceScopedSharing, ISpaceService, IUserAuthorization, IngestOptions, InvokeFunction, JWK, KVResponse, KVService, KVServiceConfig, KeyInfo, KeyProvider, KeyType, PersistedSessionData, PrefixedKVService, ProtocolMismatchError, QueryOptions, QueryResponse, ReceiveOptions, SQLAction, SQLActionType, SQLService, SQLServiceConfig, ServiceContext, ServiceContextConfig, ServiceSession, ShareAccess, ShareLink, ShareLinkData, ShareSchema, SharingService, SharingServiceConfig, SignCallback, SignRequest, SignResponse, Space, SpaceConfig, SpaceErrorCode, SpaceErrorCodes, SpaceInfo, SpaceOwnership, SpaceService, SpaceServiceConfig, SqlStatement, SqlValue, StoredDelegationChain, TinyCloud, TinyCloudConfig, TinyCloudSession, VersionCheckError, buildSpaceUri, checkNodeVersion, createCapabilityKeyRegistry, createSharingService, createSpaceService, makePublicSpaceId, parseSpaceUri } from '@tinycloud/sdk-core';
+import { ISigner, Bytes, ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ClientSession, TinyCloudSession, Extension, Delegation, IKVService, ISQLService, IDataVaultService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISharingService, CreateDelegationParams, DelegationResult, KeyProvider, JWK } from '@tinycloud/sdk-core';
+export { AutoRejectStrategy, AutoSignStrategy, BatchOptions, BatchResponse, CallbackStrategy, CapabilityEntry, CapabilityKeyRegistry, CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, ClientSession, CreateDelegationParams, DataVaultConfig, DataVaultService, DatabaseHandle, Delegation, DelegationChain, DelegationChainV2, DelegationDirection, DelegationError, DelegationErrorCode, DelegationErrorCodes, DelegationFilters, DelegationManager, DelegationManagerConfig, DelegationRecord, DelegationResult, EncodedShareData, ExecuteOptions, ExecuteResponse, Extension, FetchFunction, GenerateShareParams, ICapabilityKeyRegistry, IDataVaultService, IDatabaseHandle, IKVService, IPrefixedKVService, ISQLService, ISessionStorage, ISharingService, ISigner, ISpace, ISpaceScopedDelegations, ISpaceScopedSharing, ISpaceService, IUserAuthorization, IngestOptions, InvokeFunction, JWK, KVResponse, KVService, KVServiceConfig, KeyInfo, KeyProvider, KeyType, PersistedSessionData, PrefixedKVService, ProtocolMismatchError, QueryOptions, QueryResponse, ReceiveOptions, SQLAction, SQLActionType, SQLService, SQLServiceConfig, ServiceContext, ServiceContextConfig, ServiceSession, ShareAccess, ShareLink, ShareLinkData, ShareSchema, SharingService, SharingServiceConfig, SignCallback, SignRequest, SignResponse, Space, SpaceConfig, SpaceErrorCode, SpaceErrorCodes, SpaceInfo, SpaceOwnership, SpaceService, SpaceServiceConfig, SqlStatement, SqlValue, StoredDelegationChain, TinyCloud, TinyCloudConfig, TinyCloudSession, VaultAction, VaultCrypto, VaultEntry, VaultError, VaultGetOptions, VaultGrantOptions, VaultHeaders, VaultListOptions, VaultPutOptions, VersionCheckError, WasmVaultFunctions, buildSpaceUri, checkNodeVersion, createCapabilityKeyRegistry, createSharingService, createSpaceService, createVaultCrypto, makePublicSpaceId, parseSpaceUri } from '@tinycloud/sdk-core';
 import { EventEmitter } from 'events';
 import { TCWSessionManager } from '@tinycloud/node-sdk-wasm';
 
@@ -237,6 +236,8 @@ interface NodeUserAuthorizationConfig {
     autoCreateSpace?: boolean;
     /** TinyCloud server endpoints (default: ["https://node.tinycloud.xyz"]) */
     tinycloudHosts?: string[];
+    /** Whether to include public space capabilities in the session (default: true) */
+    enablePublicSpace?: boolean;
 }
 /**
  * Node.js implementation of IUserAuthorization.
@@ -284,6 +285,7 @@ declare class NodeUserAuthorization implements IUserAuthorization {
     private readonly sessionExpirationMs;
     private readonly autoCreateSpace;
     private readonly tinycloudHosts;
+    private readonly enablePublicSpace;
     private sessionManager;
     private extensions;
     private _session?;
@@ -313,6 +315,11 @@ declare class NodeUserAuthorization implements IUserAuthorization {
      * 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.
@@ -479,6 +486,39 @@ declare class DelegatedAccess {
     get sql(): ISQLService;
 }
 
+/**
+ * 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.
@@ -498,6 +538,10 @@ interface TinyCloudNodeConfig {
     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;
 }
 /**
  * High-level TinyCloud API for Node.js environments.
@@ -518,6 +562,9 @@ declare class TinyCloudNode {
     private _serviceContext?;
     private _kv?;
     private _sql?;
+    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 */
@@ -592,6 +639,26 @@ declare class TinyCloudNode {
      * 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.
      *
@@ -655,6 +722,11 @@ declare class TinyCloudNode {
      * SQL database operations on this user's space.
      */
     get sql(): ISQLService;
+    /**
+     * 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.
      *
@@ -790,11 +862,12 @@ declare class TinyCloudNode {
      */
     get sharingService(): ISharingService;
     /**
-     * Ensure the user's public space exists.
-     * Creates it via spaces.create('public') if it doesn't.
-     * Requires the user to be signed in.
+     * 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<_tinycloud_sdk_core.Result<void, _tinycloud_sdk_core.ServiceError>>;
+    ensurePublicSpace(): Promise<void>;
     /**
      * Get a KVService scoped to the user's own public space.
      * Writes require authentication (owner/delegate).
@@ -865,6 +938,8 @@ declare class TinyCloudNode {
         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;
     }): Promise<PortableDelegation>;
     /**
      * Use a delegation received from another user.

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-import * as _tinycloud_sdk_core from '@tinycloud/sdk-core';
-import { ISigner, Bytes, ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ClientSession, TinyCloudSession, Extension, Delegation, IKVService, ISQLService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISharingService, CreateDelegationParams, DelegationResult, KeyProvider, JWK } from '@tinycloud/sdk-core';
-export { AutoRejectStrategy, AutoSignStrategy, BatchOptions, BatchResponse, CallbackStrategy, CapabilityEntry, CapabilityKeyRegistry, CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, ClientSession, CreateDelegationParams, DatabaseHandle, Delegation, DelegationChain, DelegationChainV2, DelegationDirection, DelegationError, DelegationErrorCode, DelegationErrorCodes, DelegationFilters, DelegationManager, DelegationManagerConfig, DelegationRecord, DelegationResult, EncodedShareData, ExecuteOptions, ExecuteResponse, Extension, FetchFunction, GenerateShareParams, ICapabilityKeyRegistry, IDatabaseHandle, IKVService, IPrefixedKVService, ISQLService, ISessionStorage, ISharingService, ISigner, ISpace, ISpaceScopedDelegations, ISpaceScopedSharing, ISpaceService, IUserAuthorization, IngestOptions, InvokeFunction, JWK, KVResponse, KVService, KVServiceConfig, KeyInfo, KeyProvider, KeyType, PersistedSessionData, PrefixedKVService, ProtocolMismatchError, QueryOptions, QueryResponse, ReceiveOptions, SQLAction, SQLActionType, SQLService, SQLServiceConfig, ServiceContext, ServiceContextConfig, ServiceSession, ShareAccess, ShareLink, ShareLinkData, ShareSchema, SharingService, SharingServiceConfig, SignCallback, SignRequest, SignResponse, Space, SpaceConfig, SpaceErrorCode, SpaceErrorCodes, SpaceInfo, SpaceOwnership, SpaceService, SpaceServiceConfig, SqlStatement, SqlValue, StoredDelegationChain, TinyCloud, TinyCloudConfig, TinyCloudSession, VersionCheckError, buildSpaceUri, checkNodeVersion, createCapabilityKeyRegistry, createSharingService, createSpaceService, makePublicSpaceId, parseSpaceUri } from '@tinycloud/sdk-core';
+import { ISigner, Bytes, ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ClientSession, TinyCloudSession, Extension, Delegation, IKVService, ISQLService, IDataVaultService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISharingService, CreateDelegationParams, DelegationResult, KeyProvider, JWK } from '@tinycloud/sdk-core';
+export { AutoRejectStrategy, AutoSignStrategy, BatchOptions, BatchResponse, CallbackStrategy, CapabilityEntry, CapabilityKeyRegistry, CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, ClientSession, CreateDelegationParams, DataVaultConfig, DataVaultService, DatabaseHandle, Delegation, DelegationChain, DelegationChainV2, DelegationDirection, DelegationError, DelegationErrorCode, DelegationErrorCodes, DelegationFilters, DelegationManager, DelegationManagerConfig, DelegationRecord, DelegationResult, EncodedShareData, ExecuteOptions, ExecuteResponse, Extension, FetchFunction, GenerateShareParams, ICapabilityKeyRegistry, IDataVaultService, IDatabaseHandle, IKVService, IPrefixedKVService, ISQLService, ISessionStorage, ISharingService, ISigner, ISpace, ISpaceScopedDelegations, ISpaceScopedSharing, ISpaceService, IUserAuthorization, IngestOptions, InvokeFunction, JWK, KVResponse, KVService, KVServiceConfig, KeyInfo, KeyProvider, KeyType, PersistedSessionData, PrefixedKVService, ProtocolMismatchError, QueryOptions, QueryResponse, ReceiveOptions, SQLAction, SQLActionType, SQLService, SQLServiceConfig, ServiceContext, ServiceContextConfig, ServiceSession, ShareAccess, ShareLink, ShareLinkData, ShareSchema, SharingService, SharingServiceConfig, SignCallback, SignRequest, SignResponse, Space, SpaceConfig, SpaceErrorCode, SpaceErrorCodes, SpaceInfo, SpaceOwnership, SpaceService, SpaceServiceConfig, SqlStatement, SqlValue, StoredDelegationChain, TinyCloud, TinyCloudConfig, TinyCloudSession, VaultAction, VaultCrypto, VaultEntry, VaultError, VaultGetOptions, VaultGrantOptions, VaultHeaders, VaultListOptions, VaultPutOptions, VersionCheckError, WasmVaultFunctions, buildSpaceUri, checkNodeVersion, createCapabilityKeyRegistry, createSharingService, createSpaceService, createVaultCrypto, makePublicSpaceId, parseSpaceUri } from '@tinycloud/sdk-core';
 import { EventEmitter } from 'events';
 import { TCWSessionManager } from '@tinycloud/node-sdk-wasm';
 
@@ -237,6 +236,8 @@ interface NodeUserAuthorizationConfig {
     autoCreateSpace?: boolean;
     /** TinyCloud server endpoints (default: ["https://node.tinycloud.xyz"]) */
     tinycloudHosts?: string[];
+    /** Whether to include public space capabilities in the session (default: true) */
+    enablePublicSpace?: boolean;
 }
 /**
  * Node.js implementation of IUserAuthorization.
@@ -284,6 +285,7 @@ declare class NodeUserAuthorization implements IUserAuthorization {
     private readonly sessionExpirationMs;
     private readonly autoCreateSpace;
     private readonly tinycloudHosts;
+    private readonly enablePublicSpace;
     private sessionManager;
     private extensions;
     private _session?;
@@ -313,6 +315,11 @@ declare class NodeUserAuthorization implements IUserAuthorization {
      * 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.
@@ -479,6 +486,39 @@ declare class DelegatedAccess {
     get sql(): ISQLService;
 }
 
+/**
+ * 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.
@@ -498,6 +538,10 @@ interface TinyCloudNodeConfig {
     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;
 }
 /**
  * High-level TinyCloud API for Node.js environments.
@@ -518,6 +562,9 @@ declare class TinyCloudNode {
     private _serviceContext?;
     private _kv?;
     private _sql?;
+    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 */
@@ -592,6 +639,26 @@ declare class TinyCloudNode {
      * 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.
      *
@@ -655,6 +722,11 @@ declare class TinyCloudNode {
      * SQL database operations on this user's space.
      */
     get sql(): ISQLService;
+    /**
+     * 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.
      *
@@ -790,11 +862,12 @@ declare class TinyCloudNode {
      */
     get sharingService(): ISharingService;
     /**
-     * Ensure the user's public space exists.
-     * Creates it via spaces.create('public') if it doesn't.
-     * Requires the user to be signed in.
+     * 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<_tinycloud_sdk_core.Result<void, _tinycloud_sdk_core.ServiceError>>;
+    ensurePublicSpace(): Promise<void>;
     /**
      * Get a KVService scoped to the user's own public space.
      * Writes require authentication (owner/delegate).
@@ -865,6 +938,8 @@ declare class TinyCloudNode {
         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;
     }): Promise<PortableDelegation>;
     /**
      * Use a delegation received from another user.