@tinycloud/node-sdk 2.1.0-beta.0 → 2.1.0-beta.1

package/dist/core.d.cts

@@ -1,5 +1,5 @@
-import { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, IWasmBindings, SiweConfig, ClientSession, TinyCloudSession, Extension, Delegation, IKVService, ISQLService, IDuckDbService, IHooksService, 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 { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, IWasmBindings, SiweConfig, ClientSession, TinyCloudSession, Extension, Delegation, IKVService, ISQLService, IDuckDbService, IHooksService, INotificationHandler, IENSResolver, IDataVaultService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISharingService, CreateDelegationParams, DelegationResult, PermissionEntry, 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, Manifest, ManifestDefaults, ManifestDelegation, ManifestValidationError, PermissionEntry, PermissionNotInManifestError, PersistedSessionData, PrefixedKVService, ProtocolMismatchError, QueryOptions, QueryResponse, ReceiveOptions, ResolvedCapabilities, ResolvedDelegate, ResourceCapability, SQLAction, SQLActionType, SQLService, SQLServiceConfig, SchemaInfo, ServiceContext, ServiceContextConfig, ServiceSession, SessionExpiredError, 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, expandActionShortNames, isCapabilitySubset, loadManifest, makePublicSpaceId, parseExpiry, parseSpaceUri, resolveManifest, validateManifest } from '@tinycloud/sdk-core';
 import { EventEmitter } from 'events';
 import { InvokeFunction } from '@tinycloud/sdk-services';
 
@@ -550,6 +550,35 @@ interface TinyCloudNodeConfig {
     /** Optional SIWE configuration overrides (e.g., nonce for server-provided nonces) */
     siweConfig?: SiweConfig;
 }
+/**
+ * Options for {@link TinyCloudNode.delegateTo}.
+ *
+ * `expiry` accepts either an ms-format duration string (e.g. `"7d"`, `"1h"`)
+ * or a raw number of milliseconds. When omitted, the default is 1 hour.
+ *
+ * `forceWalletSign` bypasses the derivability check and sends the
+ * delegation through the legacy wallet-signed SIWE path, which always
+ * triggers a wallet prompt. Used for testing, for explicit wallet
+ * confirmation flows, and by the legacy `createDelegation` fallback.
+ */
+interface DelegateToOptions {
+    /** Override expiry. ms-format string ("7d", "1h") or raw milliseconds. */
+    expiry?: string | number;
+    /** Force the wallet-signed SIWE path even if the caps are derivable. Default false. */
+    forceWalletSign?: boolean;
+}
+/**
+ * Result of {@link TinyCloudNode.delegateTo}.
+ *
+ * `prompted` indicates whether a wallet prompt was shown — `true` for the
+ * legacy wallet path (always), `false` for the session-key UCAN path (never).
+ * Callers wiring single-prompt sign-in flows use this to assert that their
+ * capability chain was derivable.
+ */
+interface DelegateToResult {
+    delegation: PortableDelegation;
+    prompted: boolean;
+}
 /**
  * High-level TinyCloud API for Node.js environments.
  *
@@ -977,6 +1006,58 @@ declare class TinyCloudNode {
      * @returns Result containing boolean permission status
      */
     checkPermission(path: string, action: string): Promise<DelegationResult<boolean>>;
+    /**
+     * Safety margin before the session's own expiry at which {@link delegateTo}
+     * will refuse to issue a derived delegation. Prevents issuing sub-delegations
+     * that would be invalid by the time the recipient used them. Spec: 60 seconds.
+     *
+     * @internal
+     */
+    private static readonly SESSION_EXPIRY_SAFETY_MARGIN_MS;
+    /**
+     * Issue a delegation using the capability-chain flow.
+     *
+     * When the requested permissions are a subset of the current session's
+     * recap, the delegation is signed by the session key via WASM — no wallet
+     * prompt. When they are not, a {@link PermissionNotInManifestError} is
+     * raised so the caller can trigger an escalation flow (e.g.
+     * `TinyCloudWeb.requestPermissions`). Passing `forceWalletSign: true`
+     * bypasses the derivability check and always uses the wallet-signed SIWE
+     * path — used by the legacy `createDelegation` fallback and by callers
+     * that want explicit wallet confirmation.
+     *
+     * Current limitation: exactly one {@link PermissionEntry} per call. For
+     * multi-resource delegation, call `delegateTo` multiple times. This keeps
+     * each delegation a single `(spaceId, path)` grant, which matches the
+     * underlying `PortableDelegation` shape.
+     *
+     * @throws {@link SessionExpiredError} when there is no session or the
+     *   current session has expired (or will within the 60s safety margin).
+     * @throws {@link PermissionNotInManifestError} when the requested entries
+     *   are not a subset of the granted session capabilities and
+     *   `forceWalletSign` is not set.
+     */
+    delegateTo(did: string, permissions: PermissionEntry[], options?: DelegateToOptions): Promise<DelegateToResult>;
+    /**
+     * Issue a delegation via the session-key UCAN WASM path.
+     *
+     * The caller has already verified the request is derivable from the
+     * current session; we just need to shape the inputs for
+     * {@link createDelegationWrapper}.
+     *
+     * @internal
+     */
+    private createDelegationViaWasmPath;
+    /**
+     * Issue a delegation via the legacy wallet-signed SIWE path for a single
+     * {@link PermissionEntry}. Shares the implementation with the public
+     * `createDelegation` method via {@link createDelegationWalletPath} so
+     * both entry points hit exactly the same SIWE / signer / public-space
+     * logic without mutual recursion.
+     *
+     * @internal
+     */
+    private createDelegationLegacyWalletPath;
     /**
      * Create a delegation from this user to another user.
      *
@@ -1002,6 +1083,14 @@ declare class TinyCloudNode {
         /** Include a companion delegation for the user's public space (default: true) */
         includePublicSpace?: boolean;
     }): Promise<PortableDelegation>;
+    /**
+     * Legacy wallet-signed SIWE delegation path. Lifted from the original
+     * `createDelegation` body verbatim so both the legacy public method and
+     * `delegateTo({ forceWalletSign: true })` hit the same code.
+     *
+     * @internal
+     */
+    private createDelegationWalletPath;
     /**
      * Use a delegation received from another user.
      *
@@ -1148,4 +1237,4 @@ declare class WasmKeyProvider implements KeyProvider {
  */
 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 };
+export { type DelegateToOptions, type DelegateToResult, DelegatedAccess, FileSessionStorage, MemorySessionStorage, type NodeEventEmitterStrategy, NodeUserAuthorization, type NodeUserAuthorizationConfig, type PortableDelegation, type SignStrategy, TinyCloudNode, type TinyCloudNodeConfig, WasmKeyProvider, type WasmKeyProviderConfig, createWasmKeyProvider, defaultSignStrategy, deserializeDelegation, serializeDelegation };

package/dist/core.d.ts

@@ -1,5 +1,5 @@
-import { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, IWasmBindings, SiweConfig, ClientSession, TinyCloudSession, Extension, Delegation, IKVService, ISQLService, IDuckDbService, IHooksService, 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 { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, IWasmBindings, SiweConfig, ClientSession, TinyCloudSession, Extension, Delegation, IKVService, ISQLService, IDuckDbService, IHooksService, INotificationHandler, IENSResolver, IDataVaultService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISharingService, CreateDelegationParams, DelegationResult, PermissionEntry, 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, Manifest, ManifestDefaults, ManifestDelegation, ManifestValidationError, PermissionEntry, PermissionNotInManifestError, PersistedSessionData, PrefixedKVService, ProtocolMismatchError, QueryOptions, QueryResponse, ReceiveOptions, ResolvedCapabilities, ResolvedDelegate, ResourceCapability, SQLAction, SQLActionType, SQLService, SQLServiceConfig, SchemaInfo, ServiceContext, ServiceContextConfig, ServiceSession, SessionExpiredError, 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, expandActionShortNames, isCapabilitySubset, loadManifest, makePublicSpaceId, parseExpiry, parseSpaceUri, resolveManifest, validateManifest } from '@tinycloud/sdk-core';
 import { EventEmitter } from 'events';
 import { InvokeFunction } from '@tinycloud/sdk-services';
 
@@ -550,6 +550,35 @@ interface TinyCloudNodeConfig {
     /** Optional SIWE configuration overrides (e.g., nonce for server-provided nonces) */
     siweConfig?: SiweConfig;
 }
+/**
+ * Options for {@link TinyCloudNode.delegateTo}.
+ *
+ * `expiry` accepts either an ms-format duration string (e.g. `"7d"`, `"1h"`)
+ * or a raw number of milliseconds. When omitted, the default is 1 hour.
+ *
+ * `forceWalletSign` bypasses the derivability check and sends the
+ * delegation through the legacy wallet-signed SIWE path, which always
+ * triggers a wallet prompt. Used for testing, for explicit wallet
+ * confirmation flows, and by the legacy `createDelegation` fallback.
+ */
+interface DelegateToOptions {
+    /** Override expiry. ms-format string ("7d", "1h") or raw milliseconds. */
+    expiry?: string | number;
+    /** Force the wallet-signed SIWE path even if the caps are derivable. Default false. */
+    forceWalletSign?: boolean;
+}
+/**
+ * Result of {@link TinyCloudNode.delegateTo}.
+ *
+ * `prompted` indicates whether a wallet prompt was shown — `true` for the
+ * legacy wallet path (always), `false` for the session-key UCAN path (never).
+ * Callers wiring single-prompt sign-in flows use this to assert that their
+ * capability chain was derivable.
+ */
+interface DelegateToResult {
+    delegation: PortableDelegation;
+    prompted: boolean;
+}
 /**
  * High-level TinyCloud API for Node.js environments.
  *
@@ -977,6 +1006,58 @@ declare class TinyCloudNode {
      * @returns Result containing boolean permission status
      */
     checkPermission(path: string, action: string): Promise<DelegationResult<boolean>>;
+    /**
+     * Safety margin before the session's own expiry at which {@link delegateTo}
+     * will refuse to issue a derived delegation. Prevents issuing sub-delegations
+     * that would be invalid by the time the recipient used them. Spec: 60 seconds.
+     *
+     * @internal
+     */
+    private static readonly SESSION_EXPIRY_SAFETY_MARGIN_MS;
+    /**
+     * Issue a delegation using the capability-chain flow.
+     *
+     * When the requested permissions are a subset of the current session's
+     * recap, the delegation is signed by the session key via WASM — no wallet
+     * prompt. When they are not, a {@link PermissionNotInManifestError} is
+     * raised so the caller can trigger an escalation flow (e.g.
+     * `TinyCloudWeb.requestPermissions`). Passing `forceWalletSign: true`
+     * bypasses the derivability check and always uses the wallet-signed SIWE
+     * path — used by the legacy `createDelegation` fallback and by callers
+     * that want explicit wallet confirmation.
+     *
+     * Current limitation: exactly one {@link PermissionEntry} per call. For
+     * multi-resource delegation, call `delegateTo` multiple times. This keeps
+     * each delegation a single `(spaceId, path)` grant, which matches the
+     * underlying `PortableDelegation` shape.
+     *
+     * @throws {@link SessionExpiredError} when there is no session or the
+     *   current session has expired (or will within the 60s safety margin).
+     * @throws {@link PermissionNotInManifestError} when the requested entries
+     *   are not a subset of the granted session capabilities and
+     *   `forceWalletSign` is not set.
+     */
+    delegateTo(did: string, permissions: PermissionEntry[], options?: DelegateToOptions): Promise<DelegateToResult>;
+    /**
+     * Issue a delegation via the session-key UCAN WASM path.
+     *
+     * The caller has already verified the request is derivable from the
+     * current session; we just need to shape the inputs for
+     * {@link createDelegationWrapper}.
+     *
+     * @internal
+     */
+    private createDelegationViaWasmPath;
+    /**
+     * Issue a delegation via the legacy wallet-signed SIWE path for a single
+     * {@link PermissionEntry}. Shares the implementation with the public
+     * `createDelegation` method via {@link createDelegationWalletPath} so
+     * both entry points hit exactly the same SIWE / signer / public-space
+     * logic without mutual recursion.
+     *
+     * @internal
+     */
+    private createDelegationLegacyWalletPath;
     /**
      * Create a delegation from this user to another user.
      *
@@ -1002,6 +1083,14 @@ declare class TinyCloudNode {
         /** Include a companion delegation for the user's public space (default: true) */
         includePublicSpace?: boolean;
     }): Promise<PortableDelegation>;
+    /**
+     * Legacy wallet-signed SIWE delegation path. Lifted from the original
+     * `createDelegation` body verbatim so both the legacy public method and
+     * `delegateTo({ forceWalletSign: true })` hit the same code.
+     *
+     * @internal
+     */
+    private createDelegationWalletPath;
     /**
      * Use a delegation received from another user.
      *
@@ -1148,4 +1237,4 @@ declare class WasmKeyProvider implements KeyProvider {
  */
 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 };
+export { type DelegateToOptions, type DelegateToResult, DelegatedAccess, FileSessionStorage, MemorySessionStorage, type NodeEventEmitterStrategy, NodeUserAuthorization, type NodeUserAuthorizationConfig, type PortableDelegation, type SignStrategy, TinyCloudNode, type TinyCloudNodeConfig, WasmKeyProvider, type WasmKeyProviderConfig, createWasmKeyProvider, defaultSignStrategy, deserializeDelegation, serializeDelegation };

package/dist/core.js

@@ -820,7 +820,12 @@ import {
   CapabilityKeyRegistry,
   SharingService,
   UnsupportedFeatureError,
-  makePublicSpaceId
+  makePublicSpaceId,
+  PermissionNotInManifestError,
+  SessionExpiredError,
+  expandActionShortNames,
+  isCapabilitySubset,
+  parseRecapCapabilities
 } from "@tinycloud/sdk-core";
 
 // src/DelegatedAccess.ts
@@ -982,9 +987,72 @@ function createWasmKeyProvider(sessionManager) {
   return new WasmKeyProvider({ sessionManager });
 }
 
+// src/delegateToHelpers.ts
+import {
+  parseExpiry,
+  SiweMessage
+} from "@tinycloud/sdk-core";
+function legacyParamsToPermissionEntries(actions, path, spaceIdOverride) {
+  const byService = /* @__PURE__ */ new Map();
+  for (const a of actions) {
+    const slashIdx = a.indexOf("/");
+    if (slashIdx === -1) {
+      continue;
+    }
+    const service = a.slice(0, slashIdx);
+    if (!service.startsWith("tinycloud.")) {
+      continue;
+    }
+    const list = byService.get(service);
+    if (list === void 0) {
+      byService.set(service, [a]);
+    } else {
+      list.push(a);
+    }
+  }
+  const space = spaceIdOverride ?? "default";
+  const entries = [];
+  for (const [service, actionList] of byService) {
+    entries.push({
+      service,
+      space,
+      path,
+      actions: actionList
+    });
+  }
+  return entries;
+}
+function resolveExpiryMs(expiry) {
+  if (expiry === void 0) {
+    return 60 * 60 * 1e3;
+  }
+  if (typeof expiry === "number") {
+    if (!Number.isFinite(expiry) || expiry <= 0) {
+      throw new Error(
+        `delegateTo expiry must be a positive finite number (got ${expiry})`
+      );
+    }
+    return expiry;
+  }
+  return parseExpiry(expiry);
+}
+function extractSiweExpiration(siwe) {
+  const parsed = new SiweMessage(siwe);
+  if (parsed.expirationTime === void 0 || parsed.expirationTime === null) {
+    return void 0;
+  }
+  const d = new Date(parsed.expirationTime);
+  if (Number.isNaN(d.getTime())) {
+    throw new Error(
+      `Session SIWE has unparseable expirationTime: ${parsed.expirationTime}`
+    );
+  }
+  return d;
+}
+
 // src/TinyCloudNode.ts
 var DEFAULT_HOST = "https://node.tinycloud.xyz";
-var TinyCloudNode = class _TinyCloudNode {
+var _TinyCloudNode = class _TinyCloudNode {
   /**
    * Create a new TinyCloudNode instance.
    *
@@ -2118,6 +2186,150 @@ var TinyCloudNode = class _TinyCloudNode {
   async checkPermission(path, action) {
     return this.delegationManager.checkPermission(path, action);
   }
+  /**
+   * Issue a delegation using the capability-chain flow.
+   *
+   * When the requested permissions are a subset of the current session's
+   * recap, the delegation is signed by the session key via WASM — no wallet
+   * prompt. When they are not, a {@link PermissionNotInManifestError} is
+   * raised so the caller can trigger an escalation flow (e.g.
+   * `TinyCloudWeb.requestPermissions`). Passing `forceWalletSign: true`
+   * bypasses the derivability check and always uses the wallet-signed SIWE
+   * path — used by the legacy `createDelegation` fallback and by callers
+   * that want explicit wallet confirmation.
+   *
+   * Current limitation: exactly one {@link PermissionEntry} per call. For
+   * multi-resource delegation, call `delegateTo` multiple times. This keeps
+   * each delegation a single `(spaceId, path)` grant, which matches the
+   * underlying `PortableDelegation` shape.
+   *
+   * @throws {@link SessionExpiredError} when there is no session or the
+   *   current session has expired (or will within the 60s safety margin).
+   * @throws {@link PermissionNotInManifestError} when the requested entries
+   *   are not a subset of the granted session capabilities and
+   *   `forceWalletSign` is not set.
+   */
+  async delegateTo(did, permissions, options) {
+    const session = this.auth?.tinyCloudSession;
+    if (!session) {
+      throw new SessionExpiredError(/* @__PURE__ */ new Date(0));
+    }
+    const sessionExpiry = extractSiweExpiration(session.siwe);
+    if (sessionExpiry !== void 0) {
+      const now2 = Date.now();
+      const marginMs = _TinyCloudNode.SESSION_EXPIRY_SAFETY_MARGIN_MS;
+      if (sessionExpiry.getTime() <= now2 + marginMs) {
+        throw new SessionExpiredError(sessionExpiry);
+      }
+    }
+    if (!Array.isArray(permissions) || permissions.length === 0) {
+      throw new Error(
+        "delegateTo requires a non-empty permissions array"
+      );
+    }
+    if (permissions.length > 1) {
+      throw new Error(
+        "delegateTo currently supports one permission entry per call. Call delegateTo multiple times for multi-resource delegation."
+      );
+    }
+    const entry = permissions[0];
+    const expandedEntry = {
+      ...entry,
+      actions: expandActionShortNames(entry.service, entry.actions)
+    };
+    const now = /* @__PURE__ */ new Date();
+    const expiryMs = resolveExpiryMs(options?.expiry);
+    const expirationTime = new Date(now.getTime() + expiryMs);
+    let effectiveExpiration = expirationTime;
+    if (sessionExpiry !== void 0 && sessionExpiry < expirationTime) {
+      effectiveExpiration = sessionExpiry;
+    }
+    if (options?.forceWalletSign) {
+      const delegation2 = await this.createDelegationLegacyWalletPath(
+        did,
+        expandedEntry,
+        effectiveExpiration
+      );
+      return { delegation: delegation2, prompted: true };
+    }
+    const granted = parseRecapCapabilities(
+      (siwe) => this.wasmBindings.parseRecapFromSiwe(siwe),
+      session.siwe
+    );
+    const requested = [expandedEntry];
+    const { subset, missing } = isCapabilitySubset(requested, granted);
+    if (!subset) {
+      throw new PermissionNotInManifestError(missing, granted);
+    }
+    const delegation = await this.createDelegationViaWasmPath(
+      did,
+      expandedEntry,
+      effectiveExpiration,
+      session
+    );
+    return { delegation, prompted: false };
+  }
+  /**
+   * Issue a delegation via the session-key UCAN WASM path.
+   *
+   * The caller has already verified the request is derivable from the
+   * current session; we just need to shape the inputs for
+   * {@link createDelegationWrapper}.
+   *
+   * @internal
+   */
+  async createDelegationViaWasmPath(did, entry, expirationTime, session) {
+    const spaceId = entry.space === "default" ? session.spaceId : entry.space;
+    const serviceSession = {
+      delegationHeader: session.delegationHeader,
+      delegationCid: session.delegationCid,
+      jwk: session.jwk,
+      spaceId,
+      verificationMethod: session.verificationMethod
+    };
+    const expirationSecs = Math.floor(expirationTime.getTime() / 1e3);
+    const result = this.createDelegationWrapper({
+      session: serviceSession,
+      delegateDID: did,
+      spaceId,
+      path: entry.path,
+      actions: entry.actions,
+      expirationSecs
+    });
+    return {
+      cid: result.cid,
+      delegationHeader: { Authorization: `Bearer ${result.delegation}` },
+      spaceId,
+      path: entry.path,
+      actions: entry.actions,
+      disableSubDelegation: false,
+      expiry: result.expiry,
+      delegateDID: did,
+      ownerAddress: session.address,
+      chainId: session.chainId,
+      host: this.config.host
+    };
+  }
+  /**
+   * Issue a delegation via the legacy wallet-signed SIWE path for a single
+   * {@link PermissionEntry}. Shares the implementation with the public
+   * `createDelegation` method via {@link createDelegationWalletPath} so
+   * both entry points hit exactly the same SIWE / signer / public-space
+   * logic without mutual recursion.
+   *
+   * @internal
+   */
+  async createDelegationLegacyWalletPath(delegateDID, entry, expirationTime) {
+    const spaceIdOverride = entry.space === "default" ? void 0 : entry.space;
+    return this.createDelegationWalletPath({
+      path: entry.path,
+      actions: entry.actions,
+      delegateDID,
+      includePublicSpace: true,
+      expiryMs: Math.max(0, expirationTime.getTime() - Date.now()),
+      spaceIdOverride
+    });
+  }
   /**
    * Create a delegation from this user to another user.
    *
@@ -2128,6 +2340,51 @@ var TinyCloudNode = class _TinyCloudNode {
    * @returns A portable delegation that can be sent to the recipient
    */
   async createDelegation(params) {
+    if (!this.signer) {
+      throw new Error("Cannot createDelegation() in session-only mode. Requires wallet mode.");
+    }
+    if (!this.auth?.tinyCloudSession) {
+      throw new Error("Not signed in. Call signIn() first.");
+    }
+    let resolvedDelegateDID = params.delegateDID;
+    if (resolvedDelegateDID.endsWith(".eth") && this.config.ensResolver) {
+      const address = await this.config.ensResolver.resolveAddress(resolvedDelegateDID);
+      if (!address) throw new Error(`Could not resolve ENS name: ${resolvedDelegateDID}`);
+      resolvedDelegateDID = `did:pkh:eip155:1:${address}`;
+    }
+    const entries = legacyParamsToPermissionEntries(
+      params.actions,
+      params.path,
+      params.spaceIdOverride
+    );
+    if (entries.length === 1) {
+      try {
+        const result = await this.delegateTo(
+          resolvedDelegateDID,
+          [entries[0]],
+          params.expiryMs !== void 0 ? { expiry: params.expiryMs } : void 0
+        );
+        return result.delegation;
+      } catch (err) {
+        if (err instanceof PermissionNotInManifestError) {
+        } else {
+          throw err;
+        }
+      }
+    }
+    return this.createDelegationWalletPath({
+      ...params,
+      delegateDID: resolvedDelegateDID
+    });
+  }
+  /**
+   * Legacy wallet-signed SIWE delegation path. Lifted from the original
+   * `createDelegation` body verbatim so both the legacy public method and
+   * `delegateTo({ forceWalletSign: true })` hit the same code.
+   *
+   * @internal
+   */
+  async createDelegationWalletPath(params) {
     if (!this.signer) {
       throw new Error("Cannot createDelegation() in session-only mode. Requires wallet mode.");
     }
@@ -2135,11 +2392,6 @@ var TinyCloudNode = class _TinyCloudNode {
     if (!session) {
       throw new Error("Not signed in. Call signIn() first.");
     }
-    if (params.delegateDID.endsWith(".eth") && this.config.ensResolver) {
-      const address = await this.config.ensResolver.resolveAddress(params.delegateDID);
-      if (!address) throw new Error(`Could not resolve ENS name: ${params.delegateDID}`);
-      params = { ...params, delegateDID: `did:pkh:eip155:1:${address}` };
-    }
     const abilities = {};
     const kvActions = params.actions.filter((a) => a.startsWith("tinycloud.kv/"));
     const sqlActions = params.actions.filter((a) => a.startsWith("tinycloud.sql/"));
@@ -2427,6 +2679,31 @@ var TinyCloudNode = class _TinyCloudNode {
     };
   }
 };
+// ===========================================================================
+// Capability-chain delegation (spec: .claude/specs/capability-chain.md)
+// ===========================================================================
+/**
+ * Safety margin before the session's own expiry at which {@link delegateTo}
+ * will refuse to issue a derived delegation. Prevents issuing sub-delegations
+ * that would be invalid by the time the recipient used them. Spec: 60 seconds.
+ *
+ * @internal
+ */
+_TinyCloudNode.SESSION_EXPIRY_SAFETY_MARGIN_MS = 6e4;
+var TinyCloudNode = _TinyCloudNode;
+
+// src/core.ts
+import {
+  PermissionNotInManifestError as PermissionNotInManifestError2,
+  SessionExpiredError as SessionExpiredError2,
+  ManifestValidationError,
+  resolveManifest,
+  validateManifest,
+  loadManifest,
+  isCapabilitySubset as isCapabilitySubset2,
+  expandActionShortNames as expandActionShortNames2,
+  parseExpiry as parseExpiry2
+} from "@tinycloud/sdk-core";
 
 // src/delegation.ts
 function serializeDelegation(delegation) {
@@ -2490,13 +2767,16 @@ export {
   DuckDbService3 as DuckDbService,
   FileSessionStorage,
   KVService3 as KVService,
+  ManifestValidationError,
   MemorySessionStorage,
   NodeUserAuthorization,
+  PermissionNotInManifestError2 as PermissionNotInManifestError,
   PrefixedKVService,
   ProtocolMismatchError,
   SQLAction,
   SQLService3 as SQLService,
   ServiceContext3 as ServiceContext,
+  SessionExpiredError2 as SessionExpiredError,
   SharingService2 as SharingService,
   SilentNotificationHandler2 as SilentNotificationHandler,
   Space,
@@ -2519,8 +2799,14 @@ export {
   defaultSignStrategy,
   defaultSpaceCreationHandler,
   deserializeDelegation,
+  expandActionShortNames2 as expandActionShortNames,
+  isCapabilitySubset2 as isCapabilitySubset,
+  loadManifest,
   makePublicSpaceId2 as makePublicSpaceId,
+  parseExpiry2 as parseExpiry,
   parseSpaceUri,
-  serializeDelegation
+  resolveManifest,
+  serializeDelegation,
+  validateManifest
 };
 //# sourceMappingURL=core.js.map