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

package/dist/core.js

@@ -203,7 +203,9 @@ import {
   submitHostDelegation,
   activateSessionWithHost,
   checkNodeInfo,
-  AutoApproveSpaceCreationHandler
+  AutoApproveSpaceCreationHandler,
+  manifestAbilitiesUnion,
+  resolveManifest
 } from "@tinycloud/sdk-core";
 
 // src/authorization/strategies.ts
@@ -272,8 +274,25 @@ var NodeUserAuthorization = class {
     this.enablePublicSpace = config.enablePublicSpace ?? true;
     this.nonce = config.nonce;
     this.siweConfig = config.siweConfig;
+    this._manifest = config.manifest;
     this.sessionManager = this.wasm.createSessionManager();
   }
+  /**
+   * Return the manifest currently driving sign-in behavior, or
+   * `undefined` if none is set. Used by TinyCloudWeb/TinyCloudNode
+   * internals to surface the manifest for requestPermissions flows
+   * without forcing the caller to track it separately.
+   */
+  get manifest() {
+    return this._manifest;
+  }
+  /**
+   * Install or replace the stored manifest. Takes effect on the next
+   * `signIn()` call — the current session (if any) is not touched.
+   */
+  setManifest(manifest) {
+    this._manifest = manifest;
+  }
   /**
    * The current active session (web-core compatible).
    */
@@ -290,6 +309,39 @@ var NodeUserAuthorization = class {
   get nodeFeatures() {
     return this._nodeFeatures;
   }
+  /**
+   * Compute the `abilities` map the WASM `prepareSession` call should
+   * see at sign-in time.
+   *
+   * When a manifest is installed, we resolve it and union together:
+   * - the app's own `resources` (what it needs at runtime)
+   * - every `additionalDelegates[*].permissions` list (what it will
+   *   re-delegate to other DIDs post sign-in)
+   *
+   * into the short-service / path / full-URN-actions shape the WASM
+   * layer expects. This is the key invariant that lets
+   * {@link TinyCloudNode.delegateTo} issue manifest-declared
+   * delegations via the session key (no wallet prompt): the session's
+   * own recap already covers every action those delegations need.
+   *
+   * When no manifest is installed, we fall back to the
+   * {@link defaultActions} table so existing callers see no change.
+   *
+   * This is a pure function of `this._manifest` + `this.defaultActions`
+   * — the manifest resolution performs no I/O and throws a
+   * {@link ManifestValidationError} on structural problems (missing
+   * id/name, unparseable expiry, etc), which will surface at sign-in
+   * rather than being silently swallowed.
+   *
+   * @internal
+   */
+  resolveSignInAbilities() {
+    if (this._manifest === void 0) {
+      return this.defaultActions;
+    }
+    const resolved = resolveManifest(this._manifest);
+    return manifestAbilitiesUnion(resolved);
+  }
   /**
    * Build SIWE overrides from the top-level nonce and siweConfig.
    * - Top-level `nonce` is seeded first so `siweConfig.nonce` wins if both are set.
@@ -493,7 +545,7 @@ var NodeUserAuthorization = class {
     const now = /* @__PURE__ */ new Date();
     const expirationTime = new Date(now.getTime() + this.sessionExpirationMs);
     const prepared = this.wasm.prepareSession({
-      abilities: this.defaultActions,
+      abilities: this.resolveSignInAbilities(),
       address,
       chainId,
       domain: this.domain,
@@ -636,7 +688,7 @@ var NodeUserAuthorization = class {
     const now = /* @__PURE__ */ new Date();
     const expirationTime = new Date(now.getTime() + this.sessionExpirationMs);
     const prepared = this.wasm.prepareSession({
-      abilities: this.defaultActions,
+      abilities: this.resolveSignInAbilities(),
       address,
       chainId,
       domain: this.domain,
@@ -820,7 +872,13 @@ import {
   CapabilityKeyRegistry,
   SharingService,
   UnsupportedFeatureError,
-  makePublicSpaceId
+  makePublicSpaceId,
+  PermissionNotInManifestError,
+  SessionExpiredError,
+  expandActionShortNames,
+  isCapabilitySubset,
+  parseRecapCapabilities,
+  SERVICE_LONG_TO_SHORT
 } from "@tinycloud/sdk-core";
 
 // src/DelegatedAccess.ts
@@ -982,9 +1040,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.
    *
@@ -1108,12 +1229,35 @@ var TinyCloudNode = class _TinyCloudNode {
       enablePublicSpace: config.enablePublicSpace ?? true,
       spaceCreationHandler: config.spaceCreationHandler,
       nonce: config.nonce,
-      siweConfig: config.siweConfig
+      siweConfig: config.siweConfig,
+      manifest: config.manifest
     });
     this.tc = new TinyCloud(this.auth, {
       invokeAny: this.wasmBindings.invokeAny
     });
   }
+  /**
+   * Install or replace the manifest that drives the SIWE recap at
+   * sign-in. Takes effect on the next `signIn()` call — the current
+   * session (if any) is not touched. Wire this up from a higher
+   * layer (e.g. TinyCloudWeb.setManifest) so the manifest is kept
+   * in sync across the stack.
+   */
+  setManifest(manifest) {
+    if (!this.auth) {
+      throw new Error(
+        "setManifest requires wallet mode. Provide a signer or privateKey in the TinyCloudNode config."
+      );
+    }
+    this.auth.setManifest(manifest);
+  }
+  /**
+   * Return the manifest currently installed on the auth handler,
+   * or `undefined` if none is set.
+   */
+  get manifest() {
+    return this.auth?.manifest;
+  }
   /**
    * Get the primary identity DID for this user.
    * - If wallet connected and signed in: returns PKH DID (did:pkh:eip155:{chainId}:{address})
@@ -1620,7 +1764,19 @@ var TinyCloudNode = class _TinyCloudNode {
   }
   /**
    * Wrapper for the WASM createDelegation function.
-   * Adapts the WASM interface to what SharingService expects.
+   *
+   * The WASM call now takes a multi-resource `abilities` map
+   * (matching `prepareSession`'s shape) and emits ONE UCAN that
+   * covers every `(service, path, actions)` entry. We mirror the raw
+   * result back through `CreateDelegationWasmResult`, converting the
+   * seconds-since-epoch `expiry` to a Date and normalizing the
+   * `delegateDid` → `delegateDID` case.
+   *
+   * Both SharingService (single-entry) and
+   * {@link TinyCloudNode.delegateTo} (multi-entry) drive this through
+   * the same code path so there's exactly one place that touches the
+   * WASM boundary.
+   *
    * @internal
    */
   createDelegationWrapper(params) {
@@ -1635,18 +1791,19 @@ var TinyCloudNode = class _TinyCloudNode {
       wasmSession,
       params.delegateDID,
       params.spaceId,
-      params.path,
-      params.actions,
+      params.abilities,
       params.expirationSecs,
       params.notBeforeSecs
     );
     return {
       delegation: result.delegation,
       cid: result.cid,
-      delegateDID: result.delegateDid,
-      path: result.path,
-      actions: result.actions,
-      expiry: new Date(result.expiry * 1e3)
+      // Rust serde `rename_all = "camelCase"` emits `delegateDid`
+      // (lowercase d); the TypeScript interface uses `delegateDID`
+      // (historical, matches Delegation.delegateDID). Normalize here.
+      delegateDID: result.delegateDid ?? result.delegateDID,
+      expiry: new Date(result.expiry * 1e3),
+      resources: result.resources
     };
   }
   /**
@@ -2118,6 +2275,209 @@ var TinyCloudNode = class _TinyCloudNode {
   async checkPermission(path, action) {
     return this.delegationManager.checkPermission(path, action);
   }
+  /**
+   * Issue a delegation using the capability-chain flow.
+   *
+   * When every requested permission is a subset of the current
+   * session's recap, the delegation is signed by the session key via
+   * WASM — no wallet prompt. When at least one is NOT derivable, a
+   * {@link PermissionNotInManifestError} is raised (carrying the
+   * missing entries) 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.
+   *
+   * Multi-entry delegations are now emitted as **one** signed UCAN:
+   * the underlying WASM `createDelegation` takes a full
+   * `HashMap<Service, HashMap<Path, Vec<Ability>>>` abilities map
+   * and produces a single attenuation carrying every
+   * `(service, path, actions)` entry. The returned
+   * {@link DelegateToResult.delegation} is that single blob, and
+   * apps can POST it to their backend exactly like a single-entry
+   * delegation (the server verifies all granted resources from one
+   * UCAN).
+   *
+   * For single-entry requests the `PortableDelegation.path` and
+   * `.actions` fields mirror the one granted entry. For
+   * multi-entry requests they mirror the **first** entry (stable
+   * lexicographic order from the Rust side); consumers that need
+   * the full picture read `PortableDelegation.resources`.
+   *
+   * @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 any requested
+   *   entry is 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"
+      );
+    }
+    const expandedEntries = permissions.map((entry) => ({
+      ...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) {
+      if (expandedEntries.length > 1) {
+        throw new Error(
+          "delegateTo with forceWalletSign=true supports at most one PermissionEntry. Multi-entry requests must go through the session-key UCAN path (drop forceWalletSign) or the legacy createDelegation method."
+        );
+      }
+      const delegation2 = await this.createDelegationLegacyWalletPath(
+        did,
+        expandedEntries[0],
+        effectiveExpiration
+      );
+      return { delegation: delegation2, prompted: true };
+    }
+    const granted = parseRecapCapabilities(
+      (siwe) => this.wasmBindings.parseRecapFromSiwe(siwe),
+      session.siwe
+    );
+    const { subset, missing } = isCapabilitySubset(expandedEntries, granted);
+    if (!subset) {
+      throw new PermissionNotInManifestError(missing, granted);
+    }
+    const delegation = await this.createDelegationViaWasmPath(
+      did,
+      expandedEntries,
+      effectiveExpiration,
+      session
+    );
+    return { delegation, prompted: false };
+  }
+  /**
+   * Issue a delegation via the session-key UCAN WASM path.
+   *
+   * The caller has already verified every entry is derivable from
+   * the current session; we build one multi-resource abilities map
+   * and emit one signed UCAN covering them all.
+   *
+   * All entries must share the same target space (the UCAN is
+   * scoped to a single space). If they don't, this throws — mixing
+   * spaces in a single delegation is not supported by the underlying
+   * Rust create_delegation call and the resulting UCAN would be
+   * under-specified.
+   *
+   * @internal
+   */
+  async createDelegationViaWasmPath(did, entries, expirationTime, session) {
+    if (entries.length === 0) {
+      throw new Error(
+        "createDelegationViaWasmPath requires a non-empty entries array"
+      );
+    }
+    const resolvedSpaces = /* @__PURE__ */ new Set();
+    for (const entry of entries) {
+      const spaceId2 = entry.space === "default" ? session.spaceId : entry.space;
+      resolvedSpaces.add(spaceId2);
+    }
+    if (resolvedSpaces.size !== 1) {
+      throw new Error(
+        `delegateTo: all permission entries must target the same space, got ${resolvedSpaces.size}: ${JSON.stringify([...resolvedSpaces])}`
+      );
+    }
+    const spaceId = [...resolvedSpaces][0];
+    const abilities = {};
+    for (const entry of entries) {
+      const shortService = SERVICE_LONG_TO_SHORT[entry.service];
+      if (shortService === void 0) {
+        throw new Error(
+          `delegateTo: unknown service '${entry.service}' \u2014 no short-form mapping`
+        );
+      }
+      if (abilities[shortService] === void 0) {
+        abilities[shortService] = {};
+      }
+      const pathsMap = abilities[shortService];
+      const existing = pathsMap[entry.path];
+      if (existing === void 0) {
+        pathsMap[entry.path] = [...entry.actions];
+      } else {
+        const seen = new Set(existing);
+        for (const action of entry.actions) {
+          if (!seen.has(action)) {
+            existing.push(action);
+            seen.add(action);
+          }
+        }
+      }
+    }
+    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,
+      abilities,
+      expirationSecs
+    });
+    const primary = result.resources[0];
+    return {
+      cid: result.cid,
+      delegationHeader: { Authorization: `Bearer ${result.delegation}` },
+      spaceId,
+      path: primary.path,
+      actions: primary.actions,
+      resources: result.resources,
+      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 +2488,49 @@ 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
+    );
+    try {
+      const result = await this.delegateTo(
+        resolvedDelegateDID,
+        entries,
+        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 +2538,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 +2825,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 as resolveManifest2,
+  validateManifest,
+  loadManifest,
+  isCapabilitySubset as isCapabilitySubset2,
+  expandActionShortNames as expandActionShortNames2,
+  parseExpiry as parseExpiry2
+} from "@tinycloud/sdk-core";
 
 // src/delegation.ts
 function serializeDelegation(delegation) {
@@ -2490,13 +2913,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 +2945,14 @@ export {
   defaultSignStrategy,
   defaultSpaceCreationHandler,
   deserializeDelegation,
+  expandActionShortNames2 as expandActionShortNames,
+  isCapabilitySubset2 as isCapabilitySubset,
+  loadManifest,
   makePublicSpaceId2 as makePublicSpaceId,
+  parseExpiry2 as parseExpiry,
   parseSpaceUri,
-  serializeDelegation
+  resolveManifest2 as resolveManifest,
+  serializeDelegation,
+  validateManifest
 };
 //# sourceMappingURL=core.js.map