@tinycloud/node-sdk 3.1.0-beta.1 → 3.1.0-beta.11

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) {
@@ -790,10 +794,12 @@ var NodeUserAuthorization = class {
         return;
       }
       try {
-        const created = (await this.hostSpace()).success;
-        if (!created) {
-          const err = new Error(`Failed to create space: ${primarySpaceId}`);
-          handler.onSpaceCreationFailed?.(creationContext, err);
+        const created = await this.hostSpace();
+        if (!created.success) {
+          const err = Object.assign(
+            new Error(`Failed to create space ${primarySpaceId}: ${describeHostFailure(created)}`),
+            { cause: created }
+          );
           throw err;
         }
       } catch (error) {
@@ -809,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;
@@ -827,10 +834,12 @@ var NodeUserAuthorization = class {
         return;
       }
       try {
-        const created = (await this.hostSpace()).success;
-        if (!created) {
-          const err = new Error(`Failed to create space: ${primarySpaceId}`);
-          handler.onSpaceCreationFailed?.(creationContext, err);
+        const created = await this.hostSpace();
+        if (!created.success) {
+          const err = Object.assign(
+            new Error(`Failed to create space ${primarySpaceId}: ${describeHostFailure(created)}`),
+            { cause: created }
+          );
           throw err;
         }
       } catch (error) {
@@ -846,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;
@@ -855,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) {
@@ -1645,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 {
@@ -1670,6 +1683,7 @@ import {
   TinyCloud,
   activateSessionWithHost as activateSessionWithHost2,
   authorizationVerdictOf,
+  httpResponseError,
   KVService as KVService2,
   SQLService as SQLService2,
   DuckDbService as DuckDbService2,
@@ -1703,6 +1717,7 @@ import {
   recapCaveatsEqual,
   expandPermissionEntries as expandPermissionEntriesCore,
   isCapabilitySubset,
+  isExplicitOnlyAction,
   parseRecapCapabilities,
   SERVICE_LONG_TO_SHORT,
   SERVICE_SHORT_TO_LONG,
@@ -1725,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
@@ -2313,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;
@@ -2408,7 +2445,7 @@ function persistedExpiry(value) {
 function sameInstant(left, right) {
   return left.getTime() === right.getTime();
 }
-function describeHostFailure(result) {
+function describeHostFailure2(result) {
   const text = result.error?.trim();
   return text ? `${result.status} - ${text}` : `${result.status}`;
 }
@@ -3154,12 +3191,13 @@ var _TinyCloudNode = class _TinyCloudNode {
     if (!auth) {
       throw new Error("Account bootstrap requires an active wallet session");
     }
+    const accountSpaceId = this.ownedSpaceId(ACCOUNT_REGISTRY_SPACE2);
     const skipped = auth.lastActivationSkippedSpaceIds;
+    if (skipped.includes(accountSpaceId)) return { action: "run", mode: "fresh" };
     if (skipped.some((spaceId) => enshrinedSpaceIds.has(spaceId))) {
-      return { action: "run", mode: "fresh" };
+      return { action: "run", mode: "repair" };
     }
     try {
-      const accountSpaceId = this.ownedSpaceId(ACCOUNT_REGISTRY_SPACE2);
       const markerPermission = {
         service: "tinycloud.kv",
         space: accountSpaceId,
@@ -3171,7 +3209,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       }
       const marker = await this.readBootstrapCompletionMarker();
       if (marker.ok) {
-        if (this.isAcceptedBootstrapCompletionMarker(marker.data.data)) {
+        if (this.isAcceptedBootstrapCompletionMarker(marker.data.data, steps.map((step) => step.id))) {
           return { action: "skip" };
         }
         return { action: "run", mode: "repair" };
@@ -3215,15 +3253,22 @@ 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) {
+  /**
+   * A marker written before a canonical space was added triggers one bounded repair.
+   */
+  isAcceptedBootstrapCompletionMarker(value, canonicalStepIds) {
     if (typeof value !== "object" || value === null) return false;
     const entries = Object.entries(value);
     const markerValue = (name) => entries.find(([key]) => key === name)?.[1];
     const version = markerValue("v");
-    return typeof version === "number" && Number.isInteger(version) && ACCEPTED_MARKER_VERSIONS.some((acceptedVersion) => acceptedVersion === version);
+    const stepIds = markerValue("stepIds");
+    return typeof version === "number" && Number.isInteger(version) && ACCEPTED_MARKER_VERSIONS.some((acceptedVersion) => acceptedVersion === version) && Array.isArray(stepIds) && canonicalStepIds.every((stepId) => stepIds.includes(stepId));
   }
   markerReadIsUnhostedSpace(meta) {
     return meta?.status === 404;
@@ -3261,17 +3306,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));
@@ -3283,8 +3334,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(
@@ -3297,33 +3351,43 @@ 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") {
-        const registered = await this.account.spaces.registerBatch(
-          step.spaces.map((space) => ({
-            spaceId: space.spaceId,
-            name: space.name,
-            ownerDid: this.did,
-            type: "owned",
-            permissions: ["*"],
-            status: "active"
-          }))
-        );
-        if (!registered.ok) {
-          throw new Error(
-            `Failed to seed account spaces: ${registered.error.message}`
-          );
-        }
-        const batchError = registered.data.recoveredFromBatchError;
-        if (batchError) {
-          warnings.push({
-            stepId: step.id,
-            kind: "batch-write-reconciled",
-            code: batchError.code,
-            message: batchError.message
-          });
+        const inputs = step.spaces.map((space) => ({
+          spaceId: space.spaceId,
+          name: space.name,
+          ownerDid: this.did,
+          type: "owned",
+          permissions: ["*"],
+          status: "active"
+        }));
+        if (mode === "fresh") {
+          const registered = await this.account.spaces.registerBatch(inputs);
+          if (!registered.ok) {
+            throw Object.assign(
+              new Error(`Failed to seed account spaces: ${registered.error.message}`),
+              { cause: registered.error }
+            );
+          }
+          const batchError = registered.data.recoveredFromBatchError;
+          if (batchError) {
+            warnings.push({
+              stepId: step.id,
+              kind: "batch-write-reconciled",
+              code: batchError.code,
+              message: batchError.message
+            });
+          }
+        } else {
+          const ensured = await this.account.spaces.registerMissing(inputs);
+          if (!ensured.ok) {
+            throw Object.assign(
+              new Error(`Failed to seed account spaces: ${ensured.error.message}`),
+              { cause: ensured.error }
+            );
+          }
         }
       }
       if (step.kind === "seed-applications") {
@@ -3334,7 +3398,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") {
@@ -3352,8 +3416,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 }
           );
         }
       }
@@ -3620,6 +3685,10 @@ var _TinyCloudNode = class _TinyCloudNode {
           );
           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]));
@@ -3694,14 +3763,14 @@ var _TinyCloudNode = class _TinyCloudNode {
     }
     if (!activation.success && activation.status !== 404) {
       throw Object.assign(
-        new Error(`Failed to check owned space ${spaceId}: ${describeHostFailure(activation)}`),
+        new Error(`Failed to check owned space ${spaceId}: ${describeHostFailure2(activation)}`),
         { cause: activation }
       );
     }
     const created = await this.auth.hostOwnedSpaceResult(spaceId);
     if (!created.success) {
       throw Object.assign(
-        new Error(`Failed to create owned space ${spaceId}: ${describeHostFailure(created)}`),
+        new Error(`Failed to create owned space ${spaceId}: ${describeHostFailure2(created)}`),
         { cause: created }
       );
     }
@@ -3710,7 +3779,7 @@ var _TinyCloudNode = class _TinyCloudNode {
     if (!retry.success || retry.skipped?.includes(spaceId)) {
       throw Object.assign(
         new Error(
-          `Failed to activate session after creating owned space ${spaceId}: ${retry.success ? "space was skipped" : describeHostFailure(retry)}`
+          `Failed to activate session after creating owned space ${spaceId}: ${retry.success ? "space was skipped" : describeHostFailure2(retry)}`
         ),
         { cause: retry }
       );
@@ -3747,19 +3816,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 {
@@ -3955,23 +4028,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)) {
@@ -4775,7 +4832,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) {
@@ -4825,9 +4882,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;
@@ -5328,7 +5383,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,
@@ -5550,9 +5605,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;
@@ -5836,6 +5889,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.
@@ -5860,8 +5949,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(
@@ -5957,8 +6047,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(
@@ -5966,7 +6057,8 @@ var _TinyCloudNode = class _TinyCloudNode {
         delegatedEntries,
         spaceId,
         session,
-        expiresAt
+        expiresAt,
+        { siwe: prepared.siwe, signature }
       );
       this.runtimePermissionGrants.push({
         session: {
@@ -6143,7 +6235,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 = {
@@ -6496,8 +6591,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 {
@@ -6533,8 +6629,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 {
@@ -6747,7 +6844,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 {
@@ -6762,7 +6859,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) {
@@ -6955,6 +7053,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}/`);
@@ -7141,7 +7242,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,
@@ -7291,7 +7395,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,
@@ -7408,7 +7515,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,
@@ -7473,6 +7583,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",
@@ -7619,6 +7739,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.");
   }
@@ -7630,15 +7759,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) {
@@ -7674,46 +7872,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."
     );
   }
@@ -7743,22 +7953,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."
     );
   }