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

package/dist/core.js

@@ -253,12 +253,22 @@ var NodeUserAuthorization = class {
       },
       capabilities: {
         "": ["tinycloud.capabilities/read"]
+      },
+      hooks: {
+        "": [
+          "tinycloud.hooks/subscribe",
+          "tinycloud.hooks/register",
+          "tinycloud.hooks/list",
+          "tinycloud.hooks/unregister"
+        ]
       }
     };
     this.sessionExpirationMs = config.sessionExpirationMs ?? 60 * 60 * 1e3;
     this.autoCreateSpace = config.autoCreateSpace ?? false;
     this.spaceCreationHandler = config.spaceCreationHandler;
-    this.tinycloudHosts = config.tinycloudHosts ?? ["https://node.tinycloud.xyz"];
+    this.tinycloudHosts = config.tinycloudHosts ?? [
+      "https://node.tinycloud.xyz"
+    ];
     this.enablePublicSpace = config.enablePublicSpace ?? true;
     this.nonce = config.nonce;
     this.siweConfig = config.siweConfig;
@@ -398,7 +408,10 @@ var NodeUserAuthorization = class {
           throw err;
         }
       } catch (error) {
-        handler.onSpaceCreationFailed?.(creationContext, error instanceof Error ? error : new Error(String(error)));
+        handler.onSpaceCreationFailed?.(
+          creationContext,
+          error instanceof Error ? error : new Error(String(error))
+        );
         throw error;
       }
       await new Promise((resolve) => setTimeout(resolve, 100));
@@ -432,7 +445,10 @@ var NodeUserAuthorization = class {
           throw err;
         }
       } catch (error) {
-        handler.onSpaceCreationFailed?.(creationContext, error instanceof Error ? error : new Error(String(error)));
+        handler.onSpaceCreationFailed?.(
+          creationContext,
+          error instanceof Error ? error : new Error(String(error))
+        );
         throw error;
       }
       await new Promise((resolve) => setTimeout(resolve, 100));
@@ -541,7 +557,10 @@ var NodeUserAuthorization = class {
     this._tinyCloudSession = tinyCloudSession;
     this._address = address;
     this._chainId = chainId;
-    const nodeInfo = await checkNodeInfo(this.tinycloudHosts[0], this.wasm.protocolVersion());
+    const nodeInfo = await checkNodeInfo(
+      this.tinycloudHosts[0],
+      this.wasm.protocolVersion()
+    );
     this._nodeFeatures = nodeInfo.features;
     for (const ext of this.extensions) {
       if (ext.afterSignIn) {
@@ -701,7 +720,10 @@ var NodeUserAuthorization = class {
     this._tinyCloudSession = tinyCloudSession;
     this._address = address;
     this._chainId = chainId;
-    const nodeInfo = await checkNodeInfo(this.tinycloudHosts[0], this.wasm.protocolVersion());
+    const nodeInfo = await checkNodeInfo(
+      this.tinycloudHosts[0],
+      this.wasm.protocolVersion()
+    );
     this._nodeFeatures = nodeInfo.features;
     for (const ext of this.extensions) {
       if (ext.afterSignIn) {
@@ -752,7 +774,9 @@ var NodeUserAuthorization = class {
         );
       }
       default:
-        throw new Error(`Unknown sign strategy: ${this.signStrategy.type}`);
+        throw new Error(
+          `Unknown sign strategy: ${this.signStrategy.type}`
+        );
     }
   }
   /**
@@ -786,6 +810,7 @@ import {
   KVService as KVService2,
   SQLService as SQLService2,
   DuckDbService as DuckDbService2,
+  HooksService as HooksService2,
   DataVaultService,
   createVaultCrypto,
   ServiceContext as ServiceContext2,
@@ -795,12 +820,18 @@ import {
   CapabilityKeyRegistry,
   SharingService,
   UnsupportedFeatureError,
-  makePublicSpaceId
+  makePublicSpaceId,
+  PermissionNotInManifestError,
+  SessionExpiredError,
+  expandActionShortNames,
+  isCapabilitySubset,
+  parseRecapCapabilities
 } from "@tinycloud/sdk-core";
 
 // src/DelegatedAccess.ts
 import {
   KVService,
+  HooksService,
   SQLService,
   DuckDbService,
   ServiceContext
@@ -825,6 +856,9 @@ var DelegatedAccess = class {
     this._duckdb = new DuckDbService({});
     this._duckdb.initialize(this._serviceContext);
     this._serviceContext.registerService("duckdb", this._duckdb);
+    this._hooks = new HooksService({});
+    this._hooks.initialize(this._serviceContext);
+    this._serviceContext.registerService("hooks", this._hooks);
     const serviceSession = {
       delegationHeader: session.delegationHeader,
       delegationCid: session.delegationCid,
@@ -870,6 +904,12 @@ var DelegatedAccess = class {
   get duckdb() {
     return this._duckdb;
   }
+  /**
+   * Hooks write-stream subscriptions on the delegated space.
+   */
+  get hooks() {
+    return this._hooks;
+  }
 };
 
 // src/keys/WasmKeyProvider.ts
@@ -947,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.
    *
@@ -1075,7 +1178,9 @@ var TinyCloudNode = class _TinyCloudNode {
       nonce: config.nonce,
       siweConfig: config.siweConfig
     });
-    this.tc = new TinyCloud(this.auth);
+    this.tc = new TinyCloud(this.auth, {
+      invokeAny: this.wasmBindings.invokeAny
+    });
   }
   /**
    * Get the primary identity DID for this user.
@@ -1144,6 +1249,7 @@ var TinyCloudNode = class _TinyCloudNode {
     this._kv = void 0;
     this._sql = void 0;
     this._duckdb = void 0;
+    this._hooks = void 0;
     this._serviceContext = void 0;
     await this.tc.signIn();
     this.initializeServices();
@@ -1163,6 +1269,7 @@ var TinyCloudNode = class _TinyCloudNode {
     this._kv = void 0;
     this._sql = void 0;
     this._duckdb = void 0;
+    this._hooks = void 0;
     this._serviceContext = void 0;
     if (sessionData.address) {
       this._address = sessionData.address;
@@ -1172,6 +1279,7 @@ var TinyCloudNode = class _TinyCloudNode {
     }
     this._serviceContext = new ServiceContext2({
       invoke: this.wasmBindings.invoke,
+      invokeAny: this.wasmBindings.invokeAny,
       fetch: globalThis.fetch.bind(globalThis),
       hosts: [this.config.host]
     });
@@ -1184,6 +1292,9 @@ var TinyCloudNode = class _TinyCloudNode {
     this._duckdb = new DuckDbService2({});
     this._duckdb.initialize(this._serviceContext);
     this._serviceContext.registerService("duckdb", this._duckdb);
+    this._hooks = new HooksService2({});
+    this._hooks.initialize(this._serviceContext);
+    this._serviceContext.registerService("hooks", this._hooks);
     const serviceSession = {
       delegationHeader: sessionData.delegationHeader,
       delegationCid: sessionData.delegationCid,
@@ -1283,7 +1394,9 @@ var TinyCloudNode = class _TinyCloudNode {
       nonce: this.config.nonce,
       siweConfig: this.config.siweConfig
     });
-    this.tc = new TinyCloud(this.auth);
+    this.tc = new TinyCloud(this.auth, {
+      invokeAny: this.wasmBindings.invokeAny
+    });
     this.config.prefix = prefix;
   }
   /**
@@ -1321,7 +1434,9 @@ var TinyCloudNode = class _TinyCloudNode {
       nonce: this.config.nonce,
       siweConfig: this.config.siweConfig
     });
-    this.tc = new TinyCloud(this.auth);
+    this.tc = new TinyCloud(this.auth, {
+      invokeAny: this.wasmBindings.invokeAny
+    });
     this.config.prefix = prefix;
   }
   /**
@@ -1336,6 +1451,7 @@ var TinyCloudNode = class _TinyCloudNode {
     this.tc.initializeServices(this.wasmBindings.invoke, [this.config.host]);
     this._serviceContext = new ServiceContext2({
       invoke: this.wasmBindings.invoke,
+      invokeAny: this.wasmBindings.invokeAny,
       fetch: globalThis.fetch.bind(globalThis),
       hosts: [this.config.host]
     });
@@ -1353,6 +1469,9 @@ var TinyCloudNode = class _TinyCloudNode {
       this._duckdb.initialize(this._serviceContext);
       this._serviceContext.registerService("duckdb", this._duckdb);
     }
+    this._hooks = new HooksService2({});
+    this._hooks.initialize(this._serviceContext);
+    this._serviceContext.registerService("hooks", this._hooks);
     const serviceSession = {
       delegationHeader: session.delegationHeader,
       delegationCid: session.delegationCid,
@@ -1731,6 +1850,15 @@ var TinyCloudNode = class _TinyCloudNode {
     }
     return this._vault;
   }
+  /**
+   * Hooks write stream subscription API.
+   */
+  get hooks() {
+    if (!this._hooks) {
+      throw new Error("Not signed in. Call signIn() first.");
+    }
+    return this._hooks;
+  }
   // ===========================================================================
   // v2 Service Accessors
   // ===========================================================================
@@ -2058,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.
    *
@@ -2068,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.");
     }
@@ -2075,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/"));
@@ -2367,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) {
@@ -2430,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,
@@ -2459,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