@tinycloud/node-sdk 3.0.1-beta.0 → 3.1.0-beta.10

package/dist/core.js

@@ -262,6 +262,10 @@ var defaultSignStrategy = { type: "auto-sign" };
 // src/authorization/NodeUserAuthorization.ts
 var DECRYPT_ACTION = ENCRYPTION.DECRYPT;
 var NETWORK_CREATE_ACTION = ENCRYPTION.NETWORK_CREATE;
+function describeHostFailure(result) {
+  const text = result.error?.trim();
+  return text ? `${result.status} - ${text}` : `${result.status}`;
+}
 function canonicalizeOpenKeyManifestJson(value) {
   const json = JSON.stringify(value);
   if (json === void 0) {
@@ -726,21 +730,28 @@ var NodeUserAuthorization = class {
     });
     const signature = await this.signMessage(siwe, purpose);
     const headers = this.wasm.siweToDelegationHeaders({ siwe, signature });
-    const result = await submitHostDelegation(host, headers);
-    return result.success;
+    return submitHostDelegation(host, headers);
   }
   /**
    * Create a specific space on the server via host delegation.
    * Used for lazy creation of additional spaces (e.g., public).
    */
   async hostPublicSpace(spaceId) {
-    return this.hostSpace(spaceId);
+    return (await this.hostSpace(spaceId)).success;
   }
   /**
    * Create a specific owned space on the server via host delegation.
    * Used by manifest registry setup for the account space.
    */
   async hostOwnedSpace(spaceId, purpose) {
+    return (await this.hostOwnedSpaceResult(spaceId, purpose)).success;
+  }
+  /**
+   * {@link hostOwnedSpace} with the full host-delegation result, so a failure
+   * keeps its HTTP status (e.g. a typed 401/403) instead of collapsing to
+   * `false`.
+   */
+  async hostOwnedSpaceResult(spaceId, purpose) {
     return this.hostSpace(spaceId, purpose);
   }
   /**
@@ -784,9 +795,11 @@ var NodeUserAuthorization = class {
       }
       try {
         const created = await this.hostSpace();
-        if (!created) {
-          const err = new Error(`Failed to create space: ${primarySpaceId}`);
-          handler.onSpaceCreationFailed?.(creationContext, err);
+        if (!created.success) {
+          const err = Object.assign(
+            new Error(`Failed to create space ${primarySpaceId}: ${describeHostFailure(created)}`),
+            { cause: created }
+          );
           throw err;
         }
       } catch (error) {
@@ -802,8 +815,9 @@ var NodeUserAuthorization = class {
         this._tinyCloudSession.delegationHeader
       );
       if (!retryResult.success) {
-        const err = new Error(
-          `Failed to activate session after creating space: ${retryResult.error}`
+        const err = Object.assign(
+          new Error(`Failed to activate session after creating space: ${describeHostFailure(retryResult)}`),
+          { cause: retryResult }
         );
         handler.onSpaceCreationFailed?.(creationContext, err);
         throw err;
@@ -821,9 +835,11 @@ var NodeUserAuthorization = class {
       }
       try {
         const created = await this.hostSpace();
-        if (!created) {
-          const err = new Error(`Failed to create space: ${primarySpaceId}`);
-          handler.onSpaceCreationFailed?.(creationContext, err);
+        if (!created.success) {
+          const err = Object.assign(
+            new Error(`Failed to create space ${primarySpaceId}: ${describeHostFailure(created)}`),
+            { cause: created }
+          );
           throw err;
         }
       } catch (error) {
@@ -839,8 +855,9 @@ var NodeUserAuthorization = class {
         this._tinyCloudSession.delegationHeader
       );
       if (!retryResult.success) {
-        const err = new Error(
-          `Failed to activate session after creating space: ${retryResult.error}`
+        const err = Object.assign(
+          new Error(`Failed to activate session after creating space: ${describeHostFailure(retryResult)}`),
+          { cause: retryResult }
         );
         handler.onSpaceCreationFailed?.(creationContext, err);
         throw err;
@@ -848,7 +865,10 @@ var NodeUserAuthorization = class {
       handler.onSpaceCreated?.(creationContext);
       return;
     }
-    throw new Error(`Failed to activate session: ${result.error}`);
+    throw Object.assign(
+      new Error(`Failed to activate session: ${describeHostFailure(result)}`),
+      { cause: result }
+    );
   }
   recordActivationSkippedSpaces(result, primarySpaceId) {
     if (result.success) {
@@ -1638,14 +1658,14 @@ var NodeUserAuthorization = class {
    * Request signature via event emitter with timeout.
    */
   requestSignatureViaEmitter(request, emitter, timeout) {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve, reject2) => {
       const timeoutId = setTimeout(() => {
-        reject(new Error("Sign request timed out"));
+        reject2(new Error("Sign request timed out"));
       }, timeout);
       const respond = async (response) => {
         clearTimeout(timeoutId);
         if (!response.approved) {
-          reject(
+          reject2(
             new Error(response.reason ?? "Sign request rejected via emitter")
           );
         } else {
@@ -1662,6 +1682,8 @@ var NodeUserAuthorization = class {
 import {
   TinyCloud,
   activateSessionWithHost as activateSessionWithHost2,
+  authorizationVerdictOf,
+  httpResponseError,
   KVService as KVService2,
   SQLService as SQLService2,
   DuckDbService as DuckDbService2,
@@ -1695,6 +1717,7 @@ import {
   recapCaveatsEqual,
   expandPermissionEntries as expandPermissionEntriesCore,
   isCapabilitySubset,
+  isExplicitOnlyAction,
   parseRecapCapabilities,
   SERVICE_LONG_TO_SHORT,
   SERVICE_SHORT_TO_LONG,
@@ -1717,7 +1740,10 @@ import {
   CREDENTIAL_INVITATION_REQUEST_DOMAIN,
   validateShareDeliveryAuthorizationV3Bytes,
   verifyEip191MessageSignature,
-  signCompactUcanRootAuthorization
+  signCompactUcanRootAuthorization,
+  isStorageFullError,
+  STORAGE_FULL_MESSAGE,
+  STORAGE_WRITE_TOO_LARGE_MESSAGE
 } from "@tinycloud/sdk-core";
 import {
   parsePermissionHint
@@ -2305,6 +2331,25 @@ function jsonFromVerifier(value) {
 function verifierRecapEntries(entries) {
   return entries.map((entry) => Array.isArray(entry.caveats) ? { ...entry, caveats: entry.caveats.map((caveat) => jsonFromVerifier(caveat)) } : entry);
 }
+function exactVerifiedRecap(verified) {
+  const exactRecap = Array.isArray(verified.verifiedRecap) ? verifierRecapEntries(verified.verifiedRecap) : verified.verifiedRecap;
+  if (!Array.isArray(exactRecap) || !exactRecap.every(
+    (entry) => entry !== null && typeof entry === "object" && typeof entry.service === "string" && typeof entry.space === "string" && typeof entry.path === "string" && Array.isArray(entry.actions) && entry.actions.every((action) => typeof action === "string") && Array.isArray(entry.caveats) && entry.caveats.every(
+      (caveat) => caveat !== null && typeof caveat === "object" && !Array.isArray(caveat)
+    )
+  )) {
+    throw new UnsupportedSessionRestoreError(
+      "it cannot reconstruct caveat-preserving persisted ReCap authority"
+    );
+  }
+  return exactRecap.map((entry) => ({
+    service: entry.service,
+    space: entry.space,
+    path: entry.path,
+    actions: [...entry.actions],
+    caveats: cloneRecapCaveats(entry.caveats)
+  }));
+}
 var ServiceGraphLifetime = class {
   constructor(invokeFn, invokeAnyFn, fetchFn) {
     this.invokeFn = invokeFn;
@@ -2400,6 +2445,10 @@ function persistedExpiry(value) {
 function sameInstant(left, right) {
   return left.getTime() === right.getTime();
 }
+function describeHostFailure2(result) {
+  const text = result.error?.trim();
+  return text ? `${result.status} - ${text}` : `${result.status}`;
+}
 function ownerDelegationPermissions(params) {
   const hasPermissions = Object.prototype.hasOwnProperty.call(params, "permissions");
   const hasLegacy = Object.prototype.hasOwnProperty.call(params, "path") || Object.prototype.hasOwnProperty.call(params, "actions");
@@ -3203,7 +3252,10 @@ var _TinyCloudNode = class _TinyCloudNode {
       marker
     );
     if (!written.ok) {
-      throw new Error(`Failed to write bootstrap completion marker: ${written.error.message}`);
+      throw Object.assign(
+        new Error(`Failed to write bootstrap completion marker: ${written.error.message}`),
+        { cause: written.error }
+      );
     }
   }
   isAcceptedBootstrapCompletionMarker(value) {
@@ -3249,17 +3301,23 @@ var _TinyCloudNode = class _TinyCloudNode {
           rawAbilities
         });
       } catch (err) {
-        throw new Error(
-          `Account bootstrap aborted: signature rejected for space "${step.space}". Cause: ${err instanceof Error ? err.message : String(err)}`
+        throw Object.assign(
+          new Error(
+            `Account bootstrap aborted: signature rejected for space "${step.space}". Cause: ${err instanceof Error ? err.message : String(err)}`
+          ),
+          { cause: err }
         );
       }
       sessions.set(step.space, session);
     }
     for (const step of steps) {
       if (step.kind !== "host") continue;
-      const hosted = await auth.hostOwnedSpace(step.spaceId, "bootstrap-host");
-      if (!hosted) {
-        throw new Error(`Failed to host bootstrap space: ${step.spaceId}`);
+      const hosted = await auth.hostOwnedSpaceResult(step.spaceId, "bootstrap-host");
+      if (!hosted.success) {
+        throw Object.assign(
+          new Error(`Failed to host bootstrap space ${step.spaceId}: ${describeHostFailure2(hosted)}`),
+          { cause: hosted }
+        );
       }
     }
     await new Promise((resolve) => setTimeout(resolve, 100));
@@ -3271,8 +3329,11 @@ var _TinyCloudNode = class _TinyCloudNode {
       }
       const activated = await activateSessionWithHost2(host, session.delegationHeader);
       if (!activated.success || activated.skipped?.includes(step.spaceId)) {
-        throw new Error(
-          `Failed to activate bootstrap session for ${step.spaceId}: ${activated.error ?? "space was skipped"}`
+        throw Object.assign(
+          new Error(
+            `Failed to activate bootstrap session for ${step.spaceId}: ${activated.success ? "space was skipped" : describeHostFailure2(activated)}`
+          ),
+          { cause: activated }
         );
       }
       this.registerBootstrapRuntimeGrant(
@@ -3285,7 +3346,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       if (step.kind === "account-index-schema") {
         const ensured = await this.account.index.ensure();
         if (!ensured.ok) {
-          throw new Error(`Failed to create account index schema: ${ensured.error.message}`);
+          throw Object.assign(new Error(`Failed to create account index schema: ${ensured.error.message}`), { cause: ensured.error });
         }
       }
       if (step.kind === "seed-spaces") {
@@ -3300,8 +3361,9 @@ var _TinyCloudNode = class _TinyCloudNode {
           }))
         );
         if (!registered.ok) {
-          throw new Error(
-            `Failed to seed account spaces: ${registered.error.message}`
+          throw Object.assign(
+            new Error(`Failed to seed account spaces: ${registered.error.message}`),
+            { cause: registered.error }
           );
         }
         const batchError = registered.data.recoveredFromBatchError;
@@ -3322,7 +3384,7 @@ var _TinyCloudNode = class _TinyCloudNode {
           { assumeUnregistered: true }
         );
         if (!registered.ok) {
-          throw new Error(`Failed to seed bootstrap applications: ${registered.error.message}`);
+          throw Object.assign(new Error(`Failed to seed bootstrap applications: ${registered.error.message}`), { cause: registered.error });
         }
       }
       if (step.kind === "encryption-network-create") {
@@ -3340,8 +3402,9 @@ var _TinyCloudNode = class _TinyCloudNode {
           ]
         });
         if (!migrated.ok) {
-          throw new Error(
-            `Failed to create secret_records schema: ${migrated.error.message}`
+          throw Object.assign(
+            new Error(`Failed to create secret_records schema: ${migrated.error.message}`),
+            { cause: migrated.error }
           );
         }
       }
@@ -3513,8 +3576,9 @@ var _TinyCloudNode = class _TinyCloudNode {
     await this.ensureOwnedSpaceHostedById(accountSpaceId);
     const result = await this.account.applications.register(request.manifests);
     if (!result.ok) {
-      throw new Error(
-        `Failed to write manifest registry records: ${result.error.message}`
+      throw Object.assign(
+        new Error(`Failed to write manifest registry records: ${result.error.message}`),
+        { cause: result.error }
       );
     }
   }
@@ -3539,7 +3603,10 @@ var _TinyCloudNode = class _TinyCloudNode {
         if (this.currentSessionCanListSpaces()) {
           const spaces = await this.account.spaces.syncAccessible();
           if (!spaces.ok) {
-            throw new Error(`Failed to sync account spaces: ${spaces.error.message}`);
+            throw Object.assign(
+              new Error(`Failed to sync account spaces: ${spaces.error.message}`),
+              { cause: spaces.error }
+            );
           }
         }
       });
@@ -3594,14 +3661,20 @@ var _TinyCloudNode = class _TinyCloudNode {
         await task();
         return;
       } catch (error) {
+        const verdict = authorizationVerdictOf(error);
         const message = error instanceof Error ? error.message : String(error);
-        if (/Unauthorized Action|\b(?:401|403)\b/.test(message)) {
+        const isAuthorizationVerdict = verdict === void 0 ? /Unauthorized Action|\b(?:401|403)\b/.test(message) : verdict !== "other";
+        if (isAuthorizationVerdict) {
           console.warn(
             "TinyCloud account registry sync stopped: authorization verdict is not retryable",
             error
           );
           return;
         }
+        if (isStorageFullError(error) || isStorageFullError(error?.cause) || message.includes(STORAGE_FULL_MESSAGE) || message.includes(STORAGE_WRITE_TOO_LARGE_MESSAGE)) {
+          console.warn("TinyCloud account registry sync stopped: storage is full", error);
+          return;
+        }
         lastError = error;
         if (attempt < delays.length - 1) {
           await new Promise((resolve) => setTimeout(resolve, delays[attempt]));
@@ -3675,19 +3748,26 @@ var _TinyCloudNode = class _TinyCloudNode {
       return;
     }
     if (!activation.success && activation.status !== 404) {
-      throw new Error(
-        `Failed to check owned space ${spaceId}: ${activation.error ?? activation.status}`
+      throw Object.assign(
+        new Error(`Failed to check owned space ${spaceId}: ${describeHostFailure2(activation)}`),
+        { cause: activation }
       );
     }
-    const created = await this.auth.hostOwnedSpace(spaceId);
-    if (!created) {
-      throw new Error(`Failed to create owned space: ${spaceId}`);
+    const created = await this.auth.hostOwnedSpaceResult(spaceId);
+    if (!created.success) {
+      throw Object.assign(
+        new Error(`Failed to create owned space ${spaceId}: ${describeHostFailure2(created)}`),
+        { cause: created }
+      );
     }
     await new Promise((resolve) => setTimeout(resolve, 100));
     const retry = await activateSessionWithHost2(host, session.delegationHeader);
     if (!retry.success || retry.skipped?.includes(spaceId)) {
-      throw new Error(
-        `Failed to activate session after creating owned space ${spaceId}: ${retry.error ?? "space was skipped"}`
+      throw Object.assign(
+        new Error(
+          `Failed to activate session after creating owned space ${spaceId}: ${retry.success ? "space was skipped" : describeHostFailure2(retry)}`
+        ),
+        { cause: retry }
       );
     }
     this.confirmedHostedSpaceIds.add(spaceId);
@@ -3722,19 +3802,23 @@ var _TinyCloudNode = class _TinyCloudNode {
     if (!host) {
       throw new Error("Owned space hosting requires a TinyCloud host");
     }
-    const hosted = await this.auth.hostOwnedSpace(
-      spaceId
-    );
-    if (!hosted) {
-      throw new Error(`Failed to host owned space: ${spaceId}`);
+    const hosted = await this.auth.hostOwnedSpaceResult(spaceId);
+    if (!hosted.success) {
+      throw Object.assign(
+        new Error(`Failed to host owned space ${spaceId}: ${describeHostFailure2(hosted)}`),
+        { cause: hosted }
+      );
     }
     const activation = await activateSessionWithHost2(
       host,
       session.delegationHeader
     );
     if (!activation.success || activation.skipped?.includes(spaceId)) {
-      throw new Error(
-        `Failed to activate session for owned space ${spaceId}: ${activation.error ?? "space was skipped"}`
+      throw Object.assign(
+        new Error(
+          `Failed to activate session for owned space ${spaceId}: ${activation.success ? "space was skipped" : describeHostFailure2(activation)}`
+        ),
+        { cause: activation }
       );
     }
     try {
@@ -3930,23 +4014,7 @@ var _TinyCloudNode = class _TinyCloudNode {
           throw new InvalidRestoredSessionError(error instanceof Error ? error.message : String(error));
         }
       })();
-      const exactRecap = Array.isArray(verified.verifiedRecap) ? verifierRecapEntries(verified.verifiedRecap) : verified.verifiedRecap;
-      if (!Array.isArray(exactRecap) || !exactRecap.every(
-        (entry) => entry !== null && typeof entry === "object" && typeof entry.service === "string" && typeof entry.space === "string" && typeof entry.path === "string" && Array.isArray(entry.actions) && entry.actions.every((action) => typeof action === "string") && Array.isArray(entry.caveats) && entry.caveats.every(
-          (caveat) => caveat !== null && typeof caveat === "object" && !Array.isArray(caveat)
-        )
-      )) {
-        throw new UnsupportedSessionRestoreError(
-          "it cannot reconstruct caveat-preserving persisted ReCap authority"
-        );
-      }
-      stagedRecap = exactRecap.map((entry) => ({
-        service: entry.service,
-        space: entry.space,
-        path: entry.path,
-        actions: [...entry.actions],
-        caveats: cloneRecapCaveats(entry.caveats)
-      }));
+      stagedRecap = exactVerifiedRecap(verified);
       const signedExpiry = verified.expiresAt === void 0 ? void 0 : persistedExpiry(verified.expiresAt);
       const persistedPolicyExpiry = sessionData.expiresAt === void 0 ? void 0 : persistedExpiry(sessionData.expiresAt);
       if (signedExpiry && persistedPolicyExpiry && !sameInstant(signedExpiry, persistedPolicyExpiry)) {
@@ -4750,7 +4818,7 @@ var _TinyCloudNode = class _TinyCloudNode {
     if (cached) return cached;
     const response = await fetch(`${this.config.host}/info`);
     if (!response.ok) {
-      throw new Error(`Failed to fetch node info: HTTP ${response.status}`);
+      throw await httpResponseError(response, "Failed to fetch node info");
     }
     const info = await response.json();
     if (typeof info.nodeId !== "string" || info.nodeId.length === 0) {
@@ -4800,9 +4868,7 @@ var _TinyCloudNode = class _TinyCloudNode {
     );
     if (response.status === 404) return null;
     if (!response.ok) {
-      throw new Error(
-        `Failed to fetch encryption network ${networkId}: HTTP ${response.status} ${await response.text()}`
-      );
+      throw await httpResponseError(response, `Failed to fetch encryption network ${networkId}`);
     }
     const body = await response.json();
     return "descriptor" in body && body.descriptor ? body.descriptor : body;
@@ -5235,7 +5301,10 @@ var _TinyCloudNode = class _TinyCloudNode {
     const activation = await activateSessionWithHost2(host, delegationSession.delegationHeader);
     assertOwnerGraphActive();
     if (!activation.success) {
-      throw new Error(`Owner delegation import failed: ${activation.status} ${activation.error ?? ""}`.trim());
+      throw Object.assign(
+        new Error(`Owner delegation import failed: ${activation.status} ${activation.error ?? ""}`.trim()),
+        { cause: activation }
+      );
     }
     const delegation = {
       cid: delegationSession.delegationCid,
@@ -5300,7 +5369,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       headers: { accept: "application/json", "content-type": "application/json", authorization },
       body: canonicalizeEncryptionJson(request)
     });
-    if (!response.ok) throw new Error(`V3 share delivery authorization failed: ${response.status}`);
+    if (!response.ok) throw await httpResponseError(response, "V3 share delivery authorization failed");
     const verified = validateShareDeliveryAuthorizationV3Bytes(new Uint8Array(await response.arrayBuffer()), {
       request,
       senderKeyDid: this.credentialHolderDid,
@@ -5522,9 +5591,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       );
     }
     if (!response.ok) {
-      throw new Error(
-        `Failed to create encryption network ${networkId}: HTTP ${response.status} ${await response.text()}`
-      );
+      throw await httpResponseError(response, `Failed to create encryption network ${networkId}`);
     }
     const created = await response.json();
     return created.descriptor;
@@ -5808,6 +5875,42 @@ var _TinyCloudNode = class _TinyCloudNode {
       (left, right) => left.service.localeCompare(right.service) || (left.space ?? "").localeCompare(right.space ?? "") || left.path.localeCompare(right.path) || left.actions.join("\0").localeCompare(right.actions.join("\0"))
     );
   }
+  /**
+   * Verify a wallet-signed session grant (a CACAO built from a SIWE and its
+   * EIP-191 signature) issued to this instance's live session key. The
+   * verifier rebuilds the CACAO from `siwe` and `signature`, so the grant is
+   * accepted only when its authorization bytes and CID are exactly that CACAO,
+   * its signer is `address`, its audience is this session key, it is valid
+   * now, and its ReCap covers `spaceId` or names only raw encryption networks
+   * (a decrypt-only grant has no space). Returns the signed ReCap and expiry.
+   * Bindings without `validateSessionGrant` fall back to the session verifier,
+   * which also refuses decrypt-only grants.
+   */
+  verifySessionGrant(grant) {
+    const bindings = this.wasmBindings;
+    const validate = typeof bindings.validateSessionGrant === "function" ? bindings.validateSessionGrant.bind(bindings) : bindings.validatePersistedSession?.bind(bindings);
+    if (validate === void 0) {
+      throw new UnsupportedSessionRestoreError("it cannot verify persisted SIWE authority");
+    }
+    const verified = validate({
+      delegationHeader: { Authorization: grant.delegationHeader.Authorization },
+      delegationCid: grant.delegationCid,
+      spaceId: grant.spaceId,
+      jwk: this.sessionKeyJwk,
+      address: canonicalizeAddress2(grant.address),
+      chainId: grant.chainId,
+      siwe: grant.siwe,
+      signature: grant.signature
+    });
+    if (typeof verified.expiresAt !== "string") {
+      throw new Error("Session grant has no signed expiry.");
+    }
+    const expiresAt = new Date(verified.expiresAt);
+    if (!Number.isFinite(expiresAt.getTime())) {
+      throw new Error("Session grant has an invalid signed expiry.");
+    }
+    return { recap: exactVerifiedRecap(verified), expiresAt };
+  }
   /**
    * Install a portable runtime permission delegation into this SDK instance so
    * matching service calls and downstream `delegateTo()` calls can use it.
@@ -5832,8 +5935,9 @@ var _TinyCloudNode = class _TinyCloudNode {
       delegation.delegationHeader
     );
     if (!activateResult.success) {
-      throw new Error(
-        `Failed to activate runtime permission delegation: ${activateResult.error}`
+      throw Object.assign(
+        new Error(`Failed to activate runtime permission delegation: ${describeHostFailure2(activateResult)}`),
+        { cause: activateResult }
       );
     }
     this.runtimePermissionGrants = this.runtimePermissionGrants.filter(
@@ -5929,8 +6033,9 @@ var _TinyCloudNode = class _TinyCloudNode {
         delegatedSession.delegationHeader
       );
       if (!activateResult.success) {
-        throw new Error(
-          `Failed to activate runtime permission delegation: ${activateResult.error}`
+        throw Object.assign(
+          new Error(`Failed to activate runtime permission delegation: ${describeHostFailure2(activateResult)}`),
+          { cause: activateResult }
         );
       }
       const delegation = this.runtimeDelegationFromSession(
@@ -5938,7 +6043,8 @@ var _TinyCloudNode = class _TinyCloudNode {
         delegatedEntries,
         spaceId,
         session,
-        expiresAt
+        expiresAt,
+        { siwe: prepared.siwe, signature }
       );
       this.runtimePermissionGrants.push({
         session: {
@@ -6115,7 +6221,10 @@ var _TinyCloudNode = class _TinyCloudNode {
       delegationSession.delegationHeader
     );
     if (!activateResult.success) {
-      throw new Error(`Failed to activate public space delegation: ${activateResult.error}`);
+      throw Object.assign(
+        new Error(`Failed to activate public space delegation: ${describeHostFailure2(activateResult)}`),
+        { cause: activateResult }
+      );
     }
     if (this._capabilityRegistry && this.session) {
       const sessionKey = {
@@ -6468,8 +6577,9 @@ var _TinyCloudNode = class _TinyCloudNode {
       delegationHeader
     );
     if (!activateResult.success) {
-      throw new Error(
-        `Failed to activate delegation with host: ${activateResult.error}`
+      throw Object.assign(
+        new Error(`Failed to activate delegation with host: ${describeHostFailure2(activateResult)}`),
+        { cause: activateResult }
       );
     }
     return {
@@ -6505,8 +6615,9 @@ var _TinyCloudNode = class _TinyCloudNode {
       delegationHeader
     );
     if (!activateResult.success) {
-      throw new Error(
-        `Failed to activate delegation with host: ${activateResult.error}`
+      throw Object.assign(
+        new Error(`Failed to activate delegation with host: ${describeHostFailure2(activateResult)}`),
+        { cause: activateResult }
       );
     }
     return {
@@ -6719,7 +6830,7 @@ var _TinyCloudNode = class _TinyCloudNode {
     }
     return grants;
   }
-  runtimeDelegationFromSession(delegatedSession, entries, spaceId, session, expiresAt) {
+  runtimeDelegationFromSession(delegatedSession, entries, spaceId, session, expiresAt, siweProof) {
     const resources = this.delegatedResourcesForEntries(entries, spaceId);
     const primary = resources[0];
     return {
@@ -6734,7 +6845,8 @@ var _TinyCloudNode = class _TinyCloudNode {
       delegateDID: session.verificationMethod,
       ownerAddress: session.address,
       chainId: session.chainId,
-      host: this.config.host
+      host: this.config.host,
+      siweProof
     };
   }
   runtimeGrantFromDelegation(delegation, session) {
@@ -6927,6 +7039,9 @@ var _TinyCloudNode = class _TinyCloudNode {
     if (grantedAction === requestedAction) {
       return true;
     }
+    if (isExplicitOnlyAction(requestedAction)) {
+      return false;
+    }
     if (grantedAction.endsWith("/*")) {
       const prefix = grantedAction.slice(0, -2);
       return requestedAction.startsWith(`${prefix}/`);
@@ -7113,7 +7228,10 @@ var _TinyCloudNode = class _TinyCloudNode {
       delegationSession.delegationHeader
     );
     if (!activateResult.success) {
-      throw new Error(`Failed to activate delegation: ${activateResult.error}`);
+      throw Object.assign(
+        new Error(`Failed to activate delegation: ${describeHostFailure2(activateResult)}`),
+        { cause: activateResult }
+      );
     }
     const result = {
       cid: delegationSession.delegationCid,
@@ -7263,7 +7381,10 @@ var _TinyCloudNode = class _TinyCloudNode {
       invokerSession.delegationHeader
     );
     if (!activateResult.success) {
-      throw new Error(`Failed to activate delegated session: ${activateResult.error}`);
+      throw Object.assign(
+        new Error(`Failed to activate delegated session: ${describeHostFailure2(activateResult)}`),
+        { cause: activateResult }
+      );
     }
     const session = {
       address: mySession.address,
@@ -7380,7 +7501,10 @@ var _TinyCloudNode = class _TinyCloudNode {
       subDelegationSession.delegationHeader
     );
     if (!activateResult.success) {
-      throw new Error(`Failed to activate sub-delegation: ${activateResult.error}`);
+      throw Object.assign(
+        new Error(`Failed to activate sub-delegation: ${describeHostFailure2(activateResult)}`),
+        { cause: activateResult }
+      );
     }
     return {
       cid: subDelegationSession.delegationCid,
@@ -7445,6 +7569,16 @@ import {
   decodeBase64Url,
   principalDidEquals as principalDidEquals3
 } from "@tinycloud/sdk-core";
+var RuntimeDelegationRejectedError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.name = "RuntimeDelegationRejectedError";
+    this.reason = reason;
+  }
+};
+function reject(reason, message) {
+  throw new RuntimeDelegationRejectedError(reason, message);
+}
 var SERVICE_BY_SHORT_NAME = {
   kv: "tinycloud.kv",
   sql: "tinycloud.sql",
@@ -7591,6 +7725,15 @@ function signedAuthorityFromCompactUcan(authorization) {
       abilities
     ));
   }
+  return canonicalSignedAuthority({
+    issuer: payload.iss,
+    audience: payload.aud,
+    expiry,
+    proofs: [...payload.prf],
+    ...remainingRedelegationDepth === void 0 ? {} : { remainingRedelegationDepth }
+  }, permissions);
+}
+function canonicalSignedAuthority(signed, permissions) {
   if (permissions.length === 0) {
     throw new Error("Validated runtime delegation has no signed capabilities.");
   }
@@ -7602,15 +7745,84 @@ function signedAuthorityFromCompactUcan(authorization) {
     actions: [...permission.actions],
     ...permission.caveats === void 0 ? {} : { caveats: permission.caveats }
   }));
-  return {
-    issuer: payload.iss,
-    audience: payload.aud,
-    expiry,
-    proofs: [...payload.prf],
-    ...remainingRedelegationDepth === void 0 ? {} : { remainingRedelegationDepth },
-    permissions: canonicalPermissions,
-    resources: canonicalResources
-  };
+  return { ...signed, permissions: canonicalPermissions, resources: canonicalResources };
+}
+var RAW_ENCRYPTION_PREFIX = "urn:tinycloud:encryption:";
+var PKH_SPACE = /^tinycloud:pkh:eip155:(\d+):(0x[0-9a-fA-F]{40}):(.+)$/;
+function comparableSpace(space) {
+  const match = PKH_SPACE.exec(space);
+  return match ? `tinycloud:pkh:eip155:${match[1]}:${match[2].toLowerCase()}:${match[3]}` : space;
+}
+function signedAuthorityFromSessionGrant(node, delegation, authorization, cid) {
+  const proof = delegation.siweProof;
+  if (proof === void 0 || proof === null || typeof proof !== "object" || typeof proof.siwe !== "string" || typeof proof.signature !== "string") {
+    reject(
+      "proof_missing",
+      "Runtime delegation is a wallet-signed session grant stored without its signed SIWE proof, so its authority cannot be verified."
+    );
+  }
+  if (typeof node.verifySessionGrant !== "function") {
+    reject("unsupported", "This runtime cannot verify wallet-signed session grants.");
+  }
+  const owner = `did:pkh:eip155:${delegation.chainId}:${delegation.ownerAddress}`;
+  if (typeof node.did !== "string" || !didPrincipalsMatch(owner, node.did)) {
+    reject("owner_mismatch", "Runtime delegation is not signed by this session's owner.");
+  }
+  let verified;
+  try {
+    verified = node.verifySessionGrant({
+      delegationHeader: { Authorization: authorization },
+      delegationCid: cid,
+      spaceId: delegation.spaceId,
+      address: delegation.ownerAddress,
+      chainId: delegation.chainId,
+      siwe: proof.siwe,
+      signature: proof.signature
+    });
+  } catch (error) {
+    reject("proof_invalid", error instanceof Error ? error.message : String(error));
+  }
+  const space = comparableSpace(delegation.spaceId);
+  const spaceOwner = PKH_SPACE.exec(delegation.spaceId);
+  if (!spaceOwner || !didPrincipalsMatch(`did:pkh:eip155:${spaceOwner[1]}:${spaceOwner[2]}`, owner)) {
+    reject("authority_invalid", "Runtime delegation space is not owned by its signer.");
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const entry of verified.recap) {
+    const service = entry.service.startsWith("tinycloud.") ? entry.service : `tinycloud.${entry.service}`;
+    const raw = entry.space === "encryption";
+    if (raw) {
+      if (service !== "tinycloud.encryption" || !entry.path.startsWith(RAW_ENCRYPTION_PREFIX)) {
+        reject("authority_invalid", "Runtime delegation has an unsupported signed raw resource.");
+      }
+      const networkOwner = entry.path.slice(RAW_ENCRYPTION_PREFIX.length, entry.path.lastIndexOf(":"));
+      if (!didPrincipalsMatch(networkOwner, owner)) {
+        reject("authority_invalid", "Runtime delegation names an encryption network its signer does not own.");
+      }
+    } else if (service === "tinycloud.encryption" || comparableSpace(entry.space) !== space) {
+      reject("authority_invalid", "Runtime delegation has signed authority outside its space.");
+    }
+    const caveats = signedCaveats(entry.caveats ?? []);
+    const key = JSON.stringify([service, raw ? "" : entry.space, entry.path, canonicalizeRecapCaveats2(caveats)]);
+    const group = groups.get(key) ?? {
+      service,
+      ...raw ? {} : { space: entry.space },
+      path: entry.path,
+      actions: [],
+      ...caveats === void 0 ? {} : { caveats }
+    };
+    for (const action of entry.actions) {
+      if (!group.actions.includes(action)) group.actions.push(action);
+    }
+    groups.set(key, group);
+  }
+  return canonicalSignedAuthority({
+    issuer: owner,
+    // The verifier bound the SIWE audience to this runtime's own session key.
+    audience: node.sessionDid,
+    expiry: verified.expiresAt,
+    proofs: []
+  }, [...groups.values()]);
 }
 function canonicalResourcesFromPortableDelegation(delegation) {
   if (delegation.resources !== void 0 && delegation.resources.length > 0) {
@@ -7646,46 +7858,58 @@ function resourcesMatch(actual, expected) {
 async function activateValidatedRuntimeDelegation(node, delegation, options) {
   const host = normalizedHost(options.host);
   if (delegation.host !== void 0 && normalizedHost(delegation.host) !== host) {
-    throw new Error(
+    reject(
+      "host_mismatch",
       `Runtime delegation host '${delegation.host}' does not match expected host '${options.host}'.`
     );
   }
   if (!(delegation.expiry instanceof Date) || Number.isNaN(delegation.expiry.getTime())) {
-    throw new Error("Runtime delegation has an invalid expiry.");
+    reject("authority_invalid", "Runtime delegation has an invalid expiry.");
   }
   if (delegation.expiry.getTime() <= Date.now()) {
-    throw new Error("Runtime delegation is expired.");
+    reject("expired", "Runtime delegation is expired.");
   }
   const authorization = delegation.delegationHeader?.Authorization;
   if (typeof authorization !== "string" || authorization.length === 0) {
-    throw new Error("Runtime delegation is missing authorization bytes.");
+    reject("authority_invalid", "Runtime delegation is missing authorization bytes.");
   }
   const cid = node.computeDelegationCid(authorization);
   if (cid !== delegation.cid) {
-    throw new Error("Runtime delegation CID does not match authorization bytes.");
+    reject("cid_mismatch", "Runtime delegation CID does not match authorization bytes.");
+  }
+  const compact = authorizationWithoutBearer(authorization).split(".").length === 3;
+  let signed;
+  try {
+    signed = compact ? signedAuthorityFromCompactUcan(authorization) : signedAuthorityFromSessionGrant(node, delegation, authorization, cid);
+  } catch (error) {
+    if (error instanceof RuntimeDelegationRejectedError) throw error;
+    reject("authority_invalid", error instanceof Error ? error.message : String(error));
   }
-  const signed = signedAuthorityFromCompactUcan(authorization);
   if (signed.expiry.getTime() <= Date.now()) {
-    throw new Error("Runtime delegation is expired.");
+    reject("expired", "Runtime delegation is expired.");
   }
   if (delegation.expiry.getTime() !== signed.expiry.getTime()) {
-    throw new Error("Runtime delegation expiry does not match signed authority.");
+    reject("authority_invalid", "Runtime delegation expiry does not match signed authority.");
   }
   if (!didPrincipalsMatch(signed.audience, node.sessionDid)) {
-    throw new Error(
+    reject(
+      "audience_mismatch",
       `Runtime delegation targets ${signed.audience} but this session is ${node.sessionDid}.`
     );
   }
   if (!didPrincipalsMatch(delegation.delegateDID, signed.audience)) {
-    throw new Error("Runtime delegation audience does not match signed authority.");
+    reject("audience_mismatch", "Runtime delegation audience does not match signed authority.");
+  }
+  if (compact && !resourcesMatch(canonicalResourcesFromPortableDelegation(delegation), signed.resources)) {
+    reject("resources_mismatch", "Runtime delegation resources do not match signed authority.");
   }
-  const declaredResources = canonicalResourcesFromPortableDelegation(delegation);
-  if (!resourcesMatch(declaredResources, signed.resources)) {
-    throw new Error("Runtime delegation resources do not match signed authority.");
+  if (options.authorize !== void 0 && !options.authorize(signed.permissions)) {
+    throw new Error("Runtime delegation is not authorized for this runtime.");
   }
   const previouslyInstalled = node.getRuntimePermissionDelegations().find((candidate) => candidate.cid === cid);
   if (previouslyInstalled !== void 0 && previouslyInstalled.delegationHeader.Authorization !== authorization) {
-    throw new Error(
+    reject(
+      "cid_mismatch",
       "A different authorization is already installed for this runtime delegation CID."
     );
   }
@@ -7715,22 +7939,28 @@ async function activateValidatedRuntimeDelegation(node, delegation, options) {
     })),
     expiry: new Date(signed.expiry),
     delegateDID: signed.audience,
-    host
+    host,
+    ...compact ? {} : { siweProof: delegation.siweProof }
   };
-  if (node.isSessionOnly === true && typeof node.did === "string" && principalDidEquals3(node.did, node.sessionDid) && typeof node.useDelegation === "function") {
-    await node.useDelegation(installedCandidate);
-  } else {
-    await node.useRuntimeDelegation(installedCandidate);
+  try {
+    if (node.isSessionOnly === true && typeof node.did === "string" && principalDidEquals3(node.did, node.sessionDid) && typeof node.useDelegation === "function") {
+      await node.useDelegation(installedCandidate);
+    } else {
+      await node.useRuntimeDelegation(installedCandidate);
+    }
+  } catch (error) {
+    reject("activation_rejected", error instanceof Error ? error.message : String(error));
   }
   const installed = node.getRuntimePermissionDelegations().find((candidate) => candidate.cid === cid);
   if (!installed) {
-    throw new Error("Runtime delegation activation did not install the validated authority.");
+    reject("activation_rejected", "Runtime delegation activation did not install the validated authority.");
   }
   if (installed.delegationHeader.Authorization !== authorization || !didPrincipalsMatch(installed.delegateDID, signed.audience) || installed.expiry.getTime() !== signed.expiry.getTime() || !resourcesMatch(
     canonicalResourcesFromPortableDelegation(installed),
     signed.resources
   ) || normalizedHost(installed.host ?? "") !== host) {
-    throw new Error(
+    reject(
+      "activation_rejected",
       "Runtime delegation activation installed authority that differs from the validated authority."
     );
   }