@tinycloud/node-sdk 2.7.0-beta.3 → 2.7.0-beta.5

package/dist/index.js

@@ -17034,10 +17034,12 @@ import {
   computeCid,
   prepareSession,
   completeSessionSetup,
+  validatePersistedSession,
   ensureEip55,
   makeSpaceId,
   createDelegation,
   parseRecapFromSiwe,
+  parseVerifiedRecapFromSiwe,
   generateHostSIWEMessage,
   siweToDelegationHeaders,
   protocolVersion,
@@ -17062,6 +17064,7 @@ var _NodeWasmBindings = class _NodeWasmBindings {
     this.makeSpaceId = makeSpaceId;
     this.createDelegation = createDelegation;
     this.parseRecapFromSiwe = parseRecapFromSiwe;
+    this.parseVerifiedRecapFromSiwe = parseVerifiedRecapFromSiwe;
     this.generateHostSIWEMessage = generateHostSIWEMessage;
     this.siweToDelegationHeaders = siweToDelegationHeaders;
     this.protocolVersion = protocolVersion;
@@ -17078,6 +17081,9 @@ var _NodeWasmBindings = class _NodeWasmBindings {
       _NodeWasmBindings.panicHookInitialized = true;
     }
   }
+  validatePersistedSession(proof) {
+    return validatePersistedSession(proof);
+  }
   createSessionManager() {
     return new TCWSessionManager();
   }
@@ -17162,6 +17168,7 @@ import {
   HooksService as HooksService2,
   DataVaultService,
   EncryptionService,
+  DecryptTransportResponseError,
   SecretsService,
   createVaultCrypto,
   ServiceContext as ServiceContext2,
@@ -17179,12 +17186,16 @@ import {
   TINYCLOUD_SECRETS_BOOTSTRAP_MANIFEST,
   bootstrapSteps,
   ENCRYPTION_PERMISSION_SERVICE as ENCRYPTION_PERMISSION_SERVICE2,
+  CaveatedDelegationUnsupportedError,
   PermissionNotInManifestError,
   SessionExpiredError,
+  canonicalizeRecapCaveats,
+  recapCaveatsEqual,
   expandPermissionEntries as expandPermissionEntriesCore,
   isCapabilitySubset,
   parseRecapCapabilities,
   SERVICE_LONG_TO_SHORT,
+  SERVICE_SHORT_TO_LONG,
   KV as KV2,
   SQL as SQL2,
   DUCKDB as DUCKDB2,
@@ -17197,8 +17208,12 @@ import {
   pkhDid as pkhDid2,
   resolveTinyCloudHosts as resolveTinyCloudHosts2,
   principalDidEquals as principalDidEquals2,
-  parseNetworkId as parseNetworkId2
+  parseNetworkId as parseNetworkId2,
+  resolveSecretPath as resolveSecretPath2
 } from "@tinycloud/sdk-core";
+import {
+  parsePermissionHint
+} from "@tinycloud/sdk-services";
 
 // src/authorization/NodeUserAuthorization.ts
 import {
@@ -17443,6 +17458,30 @@ var NodeUserAuthorization = class {
       this.tinycloudHosts = [...hosts];
     }
   }
+  /** @internal Atomically adopt the state staged by TinyCloudNode.restoreSession. */
+  installRestoredSession(sessionManager, session, hosts) {
+    this.sessionManager = sessionManager;
+    this.tinycloudHosts = hosts && hosts.length > 0 ? [...hosts] : void 0;
+    this._lastActivationSkippedSpaceIds = [];
+    if (!session) {
+      this._session = void 0;
+      this._tinyCloudSession = void 0;
+      this._address = void 0;
+      this._chainId = void 0;
+      return;
+    }
+    this._tinyCloudSession = { ...session };
+    this._address = session.address;
+    this._chainId = session.chainId;
+    this._session = {
+      address: session.address,
+      walletAddress: session.address,
+      chainId: session.chainId,
+      sessionKey: session.sessionKey,
+      siwe: session.siwe,
+      signature: session.signature
+    };
+  }
   /**
    * Ensure `tinycloudHosts` are resolved before a host-needing call.
    *
@@ -18650,6 +18689,9 @@ var DEFAULT_ENCRYPTION_NETWORK_NAME = "default";
 var NETWORK_CREATE_ACTION2 = ENCRYPTION2.NETWORK_CREATE;
 var DECRYPT_ACTION2 = ENCRYPTION2.DECRYPT;
 var NETWORK_ADMIN_TYPE = "tinycloud.encryption.network-admin/v1";
+function isSecretPayload(value) {
+  return typeof value === "object" && value !== null && "value" in value && typeof value.value === "string" && "createdAt" in value && typeof value.createdAt === "string" && "updatedAt" in value && typeof value.updatedAt === "string";
+}
 var ROOT_DELEGATION_ACTIONS = [
   KV2.PUT,
   KV2.GET,
@@ -18704,6 +18746,141 @@ function didPrincipalMatches2(actual, expected) {
     return actual === expected;
   }
 }
+function clonePersistedSessionJwk(jwk) {
+  if (jwk === null || typeof jwk !== "object" || Array.isArray(jwk)) {
+    throw new Error("Persisted session has an invalid private Ed25519 session key.");
+  }
+  try {
+    const serialized = JSON.stringify(jwk);
+    const cloned = serialized === void 0 ? void 0 : JSON.parse(serialized);
+    if (cloned === null || typeof cloned !== "object" || Array.isArray(cloned)) {
+      throw new Error("invalid JWK object");
+    }
+    return cloned;
+  } catch {
+    throw new Error("Persisted session has an invalid private Ed25519 session key.");
+  }
+}
+function cloneRecapCaveats(caveats) {
+  if (!caveats) return [];
+  const cloneJson = (value) => {
+    if (value === null || typeof value === "boolean" || typeof value === "string") {
+      return value;
+    }
+    if (typeof value === "number") {
+      if (Number.isFinite(value)) return value;
+      throw new Error("ReCap caveats must contain only JSON values.");
+    }
+    if (Array.isArray(value)) return value.map(cloneJson);
+    if (typeof value === "object") {
+      const prototype = Object.getPrototypeOf(value);
+      if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error("ReCap caveats must contain only JSON values.");
+      }
+      const copy = /* @__PURE__ */ Object.create(null);
+      for (const [key2, nested] of Object.entries(value)) {
+        copy[key2] = cloneJson(nested);
+      }
+      return copy;
+    }
+    throw new Error("ReCap caveats must contain only JSON values.");
+  };
+  try {
+    return JSON.parse(JSON.stringify(caveats.map(cloneJson)));
+  } catch {
+    throw new Error("Verified persisted session ReCap contains invalid caveats.");
+  }
+}
+var ServiceGraphLifetime = class {
+  constructor(invokeFn, invokeAnyFn, fetchFn) {
+    this.invokeFn = invokeFn;
+    this.invokeAnyFn = invokeAnyFn;
+    this.fetchFn = fetchFn;
+    this.abortController = new AbortController();
+    this.contexts = /* @__PURE__ */ new Set();
+    this.retired = false;
+    this.invoke = (session, service, path, action, facts) => {
+      this.assertActive();
+      return this.invokeFn(session, service, path, action, facts);
+    };
+    this.invokeAny = (session, entries, facts) => {
+      this.assertActive();
+      return this.invokeAnyFn(session, entries, facts);
+    };
+    this.fetch = (url, init2) => {
+      this.assertActive();
+      return this.fetchFn(url, {
+        ...init2,
+        signal: this.combineSignals(init2?.signal)
+      });
+    };
+  }
+  track(context) {
+    this.assertActive();
+    this.contexts.add(context);
+    return context;
+  }
+  retire() {
+    if (this.retired) return;
+    this.retired = true;
+    this.abortController.abort();
+    try {
+      for (const context of this.contexts) {
+        try {
+          const retire = context.retire;
+          if (retire) retire.call(context);
+          else context.abort();
+        } catch (error) {
+          console.error("Error retiring service graph context:", error);
+        }
+      }
+    } finally {
+      this.contexts.clear();
+    }
+  }
+  assertActive() {
+    if (this.retired) {
+      throw new Error("Service graph has been retired by session replacement.");
+    }
+  }
+  combineSignals(signal) {
+    if (!signal) return this.abortController.signal;
+    const combined = new AbortController();
+    const abort = () => combined.abort();
+    if (signal.aborted || this.abortController.signal.aborted) {
+      abort();
+    } else {
+      signal.addEventListener("abort", abort, { once: true });
+      this.abortController.signal.addEventListener("abort", abort, { once: true });
+    }
+    return combined.signal;
+  }
+};
+var UnsupportedSessionRestoreError = class extends Error {
+  constructor(reason = "it cannot replace and enumerate every live session signer") {
+    super(`Persisted session restore is unsupported by this WASM binding because ${reason}.`);
+    this.code = "RESTORE_SESSION_KEY_REPLACEMENT_UNSUPPORTED";
+    this.name = "UnsupportedSessionRestoreError";
+  }
+};
+function canonicalRestoredVerificationMethod(canonicalVerificationMethod, persistedVerificationMethod) {
+  if (typeof persistedVerificationMethod !== "string") return void 0;
+  const principal = canonicalVerificationMethod.split("#", 1)[0];
+  return persistedVerificationMethod === principal || persistedVerificationMethod === canonicalVerificationMethod ? canonicalVerificationMethod : void 0;
+}
+function persistedExpiry(value) {
+  if (typeof value !== "string") {
+    throw new Error("Persisted session without a SIWE expiration must include expiresAt.");
+  }
+  const expiry = new Date(value);
+  if (!Number.isFinite(expiry.getTime()) || expiry.getTime() <= Date.now()) {
+    throw new Error("Persisted session expiry is invalid or expired.");
+  }
+  return expiry;
+}
+function sameInstant(left, right) {
+  return left.getTime() === right.getTime();
+}
 function sharingActionsToAbilities(path, actions) {
   var _a;
   const abilities = {};
@@ -18830,6 +19007,7 @@ var _TinyCloudNode = class _TinyCloudNode {
     this.auth = null;
     this.tc = null;
     this._chainId = 1;
+    this._baseVaults = /* @__PURE__ */ new Map();
     this._baseSecrets = /* @__PURE__ */ new Map();
     this._secrets = /* @__PURE__ */ new Map();
     this.runtimePermissionGrants = [];
@@ -18849,26 +19027,55 @@ var _TinyCloudNode = class _TinyCloudNode {
       skipped: false
     };
     this.invokeWithRuntimePermissions = (session, service, path, action, facts) => {
-      return this.wasmBindings.invoke(
-        this.selectInvocationSession(session, service, path, action),
-        service,
+      const operation = {
+        spaceId: session.spaceId,
+        service: this.invocationServiceName(service),
         path,
-        action,
-        facts
+        action
+      };
+      const grant = this.findGrantForOperation(operation);
+      const grantedOperation = grant?.operations.find(
+        (candidate) => this.operationCovers(candidate, operation)
       );
+      const invocationSession = !grant || grant.provenance === "primary" ? session : grant.session;
+      if ((grantedOperation?.caveats?.length ?? 0) > 0) {
+        if (!this.wasmBindings.invokeAny) {
+          throw new Error("WASM binding does not support caveat-preserving invocation");
+        }
+        return this.wasmBindings.invokeAny(invocationSession, [{
+          spaceId: invocationSession.spaceId,
+          service,
+          path,
+          action,
+          caveats: cloneRecapCaveats(grantedOperation.caveats)
+        }], facts);
+      }
+      return this.wasmBindings.invoke(invocationSession, service, path, action, facts);
     };
     this.invokeAnyWithRuntimePermissions = (session, entries, facts) => {
       if (!this.wasmBindings.invokeAny) {
         throw new Error("WASM binding does not support invokeAny");
       }
-      const grant = this.findGrantForOperations(
-        entries.flatMap((entry) => {
-          const operation = this.operationFromInvokeAnyEntry(entry);
-          return operation ? [operation] : [];
-        })
-      );
+      const operations = entries.flatMap((entry) => {
+        const operation = this.operationFromInvokeAnyEntry(entry);
+        return operation ? [operation] : [];
+      });
+      const grant = this.findGrantForOperations(operations);
       const invocationSession = !grant || grant.provenance === "primary" ? session : grant.session;
-      return this.wasmBindings.invokeAny(invocationSession, entries, facts);
+      const caveatPreservingEntries = grant ? entries.map((entry) => {
+        const requested = this.operationFromInvokeAnyEntry(entry);
+        const granted = requested && grant.operations.find(
+          (candidate) => this.operationCovers(candidate, requested)
+        );
+        if (!granted?.caveats?.length) {
+          return entry;
+        }
+        if (entry.caveats !== void 0 && !recapCaveatsEqual(entry.caveats, granted.caveats)) {
+          throw new Error("Invocation caveats do not match signed ReCap authority.");
+        }
+        return { ...entry, caveats: cloneRecapCaveats(granted.caveats) };
+      }) : entries;
+      return this.wasmBindings.invokeAny(invocationSession, caveatPreservingEntries, facts);
     };
     this.explicitHost = config.host;
     this.config = {
@@ -18897,16 +19104,19 @@ var _TinyCloudNode = class _TinyCloudNode {
       throw new Error("Failed to get session key JWK");
     }
     this.sessionKeyJwk = JSON.parse(jwkStr);
+    this._serviceGraph = this.createServiceGraphLifetime();
     this._capabilityRegistry = new CapabilityKeyRegistry();
     this._keyProvider = new WasmKeyProvider({
       sessionManager: this.sessionManager
     });
     this.notificationHandler = config.notificationHandler ?? new SilentNotificationHandler();
+    const receiveOnlyGraph = this._serviceGraph;
     this._sharingService = new SharingService({
       hosts: [this.config.host],
       // session: undefined - not needed for receive()
-      invoke: this.invokeWithRuntimePermissions,
-      fetch: globalThis.fetch.bind(globalThis),
+      invoke: receiveOnlyGraph.invoke,
+      fetch: receiveOnlyGraph.fetch,
+      assertActive: () => receiveOnlyGraph.assertActive(),
       keyProvider: this._keyProvider,
       registry: this._capabilityRegistry,
       createDelegationWasm: (params) => this.createDelegationWrapper(params),
@@ -18918,12 +19128,12 @@ var _TinyCloudNode = class _TinyCloudNode {
       createKVService: (config2) => {
         const prefix = config2.pathPrefix?.replace(/\/$/, "");
         const kvService = new KVService2({ prefix });
-        const kvContext = new ServiceContext2({
+        const kvContext = receiveOnlyGraph.track(new ServiceContext2({
           invoke: config2.invoke,
           fetch: config2.fetch ?? globalThis.fetch.bind(globalThis),
           hosts: config2.hosts,
           telemetry: this.config.telemetry
-        });
+        }));
         kvContext.setSession(config2.session);
         kvService.initialize(kvContext);
         return kvService;
@@ -18997,6 +19207,16 @@ var _TinyCloudNode = class _TinyCloudNode {
   shouldUseBootstrapSignInRequest(config) {
     return config.autoBootstrapAccount !== false && config.manifest === void 0 && config.capabilityRequest === void 0 && (config.prefix ?? "default") === "default" && isOpenKeyAutoSignStrategy(config.signStrategy);
   }
+  createServiceGraphLifetime() {
+    return new ServiceGraphLifetime(
+      this.invokeWithRuntimePermissions,
+      this.invokeAnyWithRuntimePermissions,
+      // Resolve fetch at request time. This keeps the graph-owned lifetime
+      // signal while preserving the SDK's existing injectable global fetch
+      // behavior (including adapters that install it after construction).
+      (url, init2) => globalThis.fetch(url, init2)
+    );
+  }
   syncResolvedHostFromAuth() {
     const host = this.auth?.hosts[0];
     if (host) {
@@ -19066,6 +19286,27 @@ var _TinyCloudNode = class _TinyCloudNode {
   get sessionDid() {
     return this.sessionManager.getDID(this.sessionKeyId);
   }
+  /**
+   * Return the current session's signed ReCap capabilities after the session
+   * has been authenticated or restored. This is intentionally distinct from
+   * installed runtime delegations: it reports base-session authority only.
+   *
+   * Invalid or unparseable signed ReCap material throws so callers fail closed
+   * rather than treating a malformed session as unrestricted authority.
+   */
+  getVerifiedSessionCapabilities() {
+    const session = this.currentTinyCloudSession();
+    if (!session || !session.siwe) return [];
+    return parseRecapCapabilities(
+      (siwe) => this.parseRecapWithCaveats(siwe),
+      session.siwe
+    ).map((entry) => entry.service === "tinycloud.encryption" ? {
+      service: entry.service,
+      path: entry.path,
+      actions: [...entry.actions],
+      ...entry.caveats === void 0 ? {} : { caveats: entry.caveats }
+    } : entry);
+  }
   /**
    * Get the Ethereum address for this user.
    */
@@ -19155,6 +19396,7 @@ var _TinyCloudNode = class _TinyCloudNode {
     this._hooks = void 0;
     this._vault = void 0;
     this._encryption = void 0;
+    this._baseVaults.clear();
     this._baseSecrets.clear();
     this._secrets.clear();
     this._spaceService = void 0;
@@ -19162,6 +19404,10 @@ var _TinyCloudNode = class _TinyCloudNode {
     this.runtimePermissionGrants = [];
     await this.tc.signIn(options);
     this.syncResolvedHostFromAuth();
+    const oldGraph = this._serviceGraph;
+    this._serviceGraph = this.createServiceGraphLifetime();
+    oldGraph.retire();
+    this.tc.retireServices();
     const signedInSession = this.currentTinyCloudSession();
     if (signedInSession) {
       this.sessionKeyId = signedInSession.sessionKey;
@@ -19446,7 +19692,7 @@ var _TinyCloudNode = class _TinyCloudNode {
     }
     let operations = [];
     try {
-      const entries = this.wasmBindings.parseRecapFromSiwe(siwe);
+      const entries = this.parseRecapWithCaveats(siwe);
       if (Array.isArray(entries)) {
         operations = entries.flatMap((entry) => {
           const service = this.invocationServiceName(entry.service);
@@ -19454,7 +19700,8 @@ var _TinyCloudNode = class _TinyCloudNode {
             ...this.isEncryptionNetworkOperation(service, entry.path) ? { resource: entry.path } : { spaceId: entry.space },
             service,
             path: entry.path,
-            action
+            action,
+            caveats: cloneRecapCaveats(entry.caveats)
           }));
         });
       }
@@ -19807,86 +20054,441 @@ var _TinyCloudNode = class _TinyCloudNode {
    */
   async restoreSession(sessionData) {
     await this.wasmBindings.ensureInitialized?.();
-    this._kv = void 0;
-    this._sql = void 0;
-    this._duckdb = void 0;
-    this._hooks = void 0;
-    this._vault = void 0;
-    this._encryption = void 0;
-    this._baseSecrets.clear();
-    this._secrets.clear();
-    this._spaceService = void 0;
-    this._serviceContext = void 0;
-    this.runtimePermissionGrants = [];
-    const restoredAddress = sessionData.address ? canonicalizeAddress2(sessionData.address) : void 0;
-    if (restoredAddress) {
-      this._address = restoredAddress;
+    const restoredJwk = clonePersistedSessionJwk(sessionData.jwk);
+    if (sessionData.chainId !== void 0 && (!Number.isSafeInteger(sessionData.chainId) || sessionData.chainId <= 0)) {
+      throw new Error("Persisted session chain ID must be a positive safe integer.");
+    }
+    const stagedManager = this.wasmBindings.createSessionManager();
+    const stagedReplace = stagedManager.replaceSessionKey;
+    const liveKeys = this.sessionManager.listSessionKeys;
+    const stagedKeys = stagedManager.listSessionKeys;
+    if (typeof stagedReplace !== "function" || typeof liveKeys !== "function" || typeof stagedKeys !== "function") {
+      throw new UnsupportedSessionRestoreError();
+    }
+    let stagedKeyId;
+    let stagedJwk;
+    let canonicalVerificationMethod;
+    try {
+      const keyIds = liveKeys.call(this.sessionManager);
+      if (!Array.isArray(keyIds) || !keyIds.every((keyId) => typeof keyId === "string")) {
+        throw new UnsupportedSessionRestoreError("it cannot reliably enumerate every live session signer");
+      }
+      for (const keyId of keyIds) {
+        if (keyId === this.sessionKeyId) continue;
+        const jwk = this.sessionManager.jwk(keyId);
+        if (!jwk) throw new Error("missing live session key");
+        stagedReplace.call(stagedManager, clonePersistedSessionJwk(JSON.parse(jwk)), keyId);
+      }
+      stagedKeyId = stagedReplace.call(stagedManager, restoredJwk, this.sessionKeyId);
+      const stagedJwkJson = stagedManager.jwk(stagedKeyId);
+      if (!stagedJwkJson) throw new Error("missing restored session key");
+      stagedJwk = clonePersistedSessionJwk(JSON.parse(stagedJwkJson));
+      canonicalVerificationMethod = stagedManager.getDID(stagedKeyId);
+    } catch (error) {
+      if (error instanceof UnsupportedSessionRestoreError) throw error;
+      throw new Error("Persisted session has an invalid private Ed25519 session key.");
     }
-    if (sessionData.chainId) {
-      this._chainId = sessionData.chainId;
+    const restoredVerificationMethod = canonicalRestoredVerificationMethod(
+      canonicalVerificationMethod,
+      sessionData.verificationMethod
+    );
+    if (!restoredVerificationMethod) {
+      throw new Error(
+        "Persisted session verification method does not match its private Ed25519 session key."
+      );
+    }
+    const proofValues = [
+      sessionData.siwe,
+      sessionData.signature,
+      sessionData.address,
+      sessionData.chainId
+    ];
+    const hasPersistedProof = proofValues.every((value) => value !== void 0);
+    if (!hasPersistedProof && (proofValues.some((value) => value !== void 0) || sessionData.expiresAt !== void 0)) {
+      throw new Error("Persisted session authority metadata is incomplete.");
+    }
+    const restoredAddress = hasPersistedProof ? canonicalizeAddress2(sessionData.address) : void 0;
+    let stagedSessionExpiry = /* @__PURE__ */ new Date(0);
+    let stagedRecap = [];
+    if (hasPersistedProof) {
+      if (typeof this.wasmBindings.validatePersistedSession !== "function") {
+        throw new UnsupportedSessionRestoreError("it cannot verify persisted SIWE authority");
+      }
+      const verified = this.wasmBindings.validatePersistedSession({
+        delegationHeader: sessionData.delegationHeader,
+        delegationCid: sessionData.delegationCid,
+        spaceId: sessionData.spaceId,
+        jwk: stagedJwk,
+        address: restoredAddress,
+        chainId: sessionData.chainId,
+        siwe: sessionData.siwe,
+        signature: sessionData.signature
+      });
+      const exactRecap = 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)
+      }));
+      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)) {
+        throw new Error("Persisted session expiry does not match its signed SIWE authority.");
+      }
+      stagedSessionExpiry = signedExpiry ?? persistedPolicyExpiry ?? persistedExpiry(void 0);
     }
     const resolvedHost = await this.resolveRestoredHost(
       sessionData.tinycloudHosts,
       restoredAddress,
       sessionData.chainId
     );
-    if (resolvedHost) {
-      this.config.host = resolvedHost;
-    }
-    this._serviceContext = new ServiceContext2({
-      invoke: this.invokeWithRuntimePermissions,
-      invokeAny: this.invokeAnyWithRuntimePermissions,
-      fetch: globalThis.fetch.bind(globalThis),
-      hosts: [this.config.host],
-      telemetry: this.config.telemetry
-    });
-    this._kv = new KVService2({});
-    this._kv.initialize(this._serviceContext);
-    this._serviceContext.registerService("kv", this._kv);
-    this._sql = new SQLService2({});
-    this._sql.initialize(this._serviceContext);
-    this._serviceContext.registerService("sql", this._sql);
-    this._duckdb = new DuckDbService2({});
-    this._duckdb.initialize(this._serviceContext);
-    this._serviceContext.registerService("duckdb", this._duckdb);
-    this._hooks = new HooksService2({});
-    this._hooks.initialize(this._serviceContext);
-    this._serviceContext.registerService("hooks", this._hooks);
+    const stagedHost = resolvedHost ?? this.config.host;
+    const stagedAddress = restoredAddress;
+    const stagedChainId = sessionData.chainId ?? 1;
+    const stagedNodeDid = stagedAddress ? pkhDid2(stagedAddress, stagedChainId) : canonicalVerificationMethod;
     const serviceSession = {
       delegationHeader: sessionData.delegationHeader,
       delegationCid: sessionData.delegationCid,
       spaceId: sessionData.spaceId,
-      verificationMethod: sessionData.verificationMethod,
-      jwk: sessionData.jwk
+      verificationMethod: restoredVerificationMethod,
+      jwk: stagedJwk
     };
-    this._serviceContext.setSession(serviceSession);
-    this._vault = this.createVaultService(sessionData.spaceId, this._kv);
-    this._vault.initialize(this._serviceContext);
-    this._serviceContext.registerService("vault", this._vault);
-    this.initializeV2Services(serviceSession);
-    if (sessionData.siwe && restoredAddress && sessionData.chainId) {
-      const tcSession = {
-        address: restoredAddress,
-        chainId: sessionData.chainId,
-        sessionKey: JSON.stringify(sessionData.jwk),
-        spaceId: sessionData.spaceId,
-        delegationCid: sessionData.delegationCid,
-        delegationHeader: sessionData.delegationHeader,
-        verificationMethod: sessionData.verificationMethod,
-        jwk: sessionData.jwk,
-        siwe: sessionData.siwe,
-        signature: sessionData.signature ?? ""
-      };
-      if (this.auth) {
-        this.auth.setRestoredTinyCloudSession(
-          tcSession,
-          this.config.host ? [this.config.host] : void 0
+    const stagedTcSession = hasPersistedProof ? {
+      address: restoredAddress,
+      chainId: sessionData.chainId,
+      sessionKey: JSON.stringify(stagedJwk),
+      spaceId: sessionData.spaceId,
+      spaces: sessionData.spaces,
+      delegationCid: sessionData.delegationCid,
+      delegationHeader: sessionData.delegationHeader,
+      verificationMethod: restoredVerificationMethod,
+      jwk: stagedJwk,
+      siwe: sessionData.siwe,
+      signature: sessionData.signature
+    } : void 0;
+    const stagedPrimary = this.stagePrimarySessionState(
+      stagedTcSession,
+      stagedNodeDid,
+      stagedHost,
+      stagedSessionExpiry,
+      stagedRecap
+    );
+    const stagedGraph = this.stageRestoredServiceGraph({
+      host: stagedHost,
+      manager: stagedManager,
+      serviceSession,
+      verificationMethod: canonicalVerificationMethod,
+      nodeDid: stagedNodeDid,
+      address: stagedAddress,
+      chainId: stagedChainId,
+      tinyCloudSession: stagedTcSession,
+      sessionExpiry: stagedSessionExpiry,
+      recap: stagedRecap
+    });
+    const oldGraph = this._serviceGraph;
+    const oldCore = this.tc;
+    this.sessionManager = stagedManager;
+    this.sessionKeyId = stagedKeyId;
+    this.sessionKeyJwk = stagedJwk;
+    if (resolvedHost) this.config.host = resolvedHost;
+    this._address = stagedAddress;
+    this._chainId = stagedChainId;
+    this._serviceContext = stagedGraph.serviceContext;
+    this._kv = stagedGraph.kv;
+    this._sql = stagedGraph.sql;
+    this._duckdb = stagedGraph.duckdb;
+    this._hooks = stagedGraph.hooks;
+    this._vault = stagedGraph.vault;
+    this._encryption = stagedGraph.encryption;
+    this._capabilityRegistry = stagedGraph.capabilityRegistry;
+    this._keyProvider = stagedGraph.keyProvider;
+    this._sharingService = stagedGraph.sharingService;
+    this._delegationManager = stagedGraph.delegationManager;
+    this._spaceService = stagedGraph.spaceService;
+    this._serviceGraph = stagedGraph.graph;
+    this._baseSecrets = /* @__PURE__ */ new Map();
+    this._secrets = /* @__PURE__ */ new Map();
+    this._publicKV = void 0;
+    this._account = void 0;
+    this.tc = stagedGraph.core;
+    this._recapOperationsCache = stagedPrimary.cache;
+    this.runtimePermissionGrants = stagedPrimary.grants;
+    if (this.auth) {
+      this.auth.installRestoredSession(stagedManager, stagedTcSession, [stagedHost]);
+      this._restoredTcSession = void 0;
+    } else {
+      this._restoredTcSession = stagedTcSession;
+    }
+    oldGraph.retire();
+    oldCore?.retireServices?.();
+  }
+  stagePrimarySessionState(session, verificationMethod, host, sessionExpiry, recap) {
+    if (!session?.siwe) return { cache: void 0, grants: [] };
+    let operations = [];
+    operations = recap.flatMap((entry) => {
+      const service = this.invocationServiceName(entry.service);
+      return entry.actions.map((action) => ({
+        ...this.isEncryptionNetworkOperation(service, entry.path) ? { resource: entry.path } : { spaceId: entry.space },
+        service,
+        path: entry.path,
+        action,
+        caveats: cloneRecapCaveats(entry.caveats)
+      }));
+    });
+    const cache = { siwe: session.siwe, operations };
+    if (operations.length === 0) return { cache, grants: [] };
+    const expiresAt = sessionExpiry;
+    return {
+      cache,
+      grants: [{
+        session: {
+          delegationHeader: session.delegationHeader,
+          delegationCid: session.delegationCid,
+          spaceId: session.spaceId,
+          verificationMethod: session.verificationMethod,
+          jwk: session.jwk
+        },
+        delegation: {
+          cid: session.delegationCid,
+          delegationHeader: session.delegationHeader,
+          delegateDID: session.verificationMethod,
+          delegatorDID: verificationMethod,
+          spaceId: session.spaceId,
+          path: "",
+          actions: [...new Set(operations.map((operation) => operation.action))],
+          expiry: expiresAt,
+          allowSubDelegation: true,
+          ownerAddress: session.address,
+          chainId: session.chainId,
+          host
+        },
+        operations,
+        expiresAt,
+        provenance: "primary"
+      }]
+    };
+  }
+  stageRestoredServiceGraph(input) {
+    const graph = this.createServiceGraphLifetime();
+    const core = this.auth ? new TinyCloud(this.auth, {
+      invokeAny: graph.invokeAny,
+      telemetry: this.config.telemetry
+    }) : null;
+    if (core) {
+      core.initializeServices(graph.invoke, [input.host], graph.fetch);
+      const coreContext = graph.track(core.serviceContext);
+      coreContext.setSession(input.serviceSession);
+    }
+    const serviceContext = graph.track(new ServiceContext2({
+      invoke: graph.invoke,
+      invokeAny: graph.invokeAny,
+      fetch: graph.fetch,
+      hosts: [input.host],
+      telemetry: this.config.telemetry
+    }));
+    const kv = new KVService2({});
+    kv.initialize(serviceContext);
+    serviceContext.registerService("kv", kv);
+    const sql = new SQLService2({});
+    sql.initialize(serviceContext);
+    serviceContext.registerService("sql", sql);
+    const duckdb = new DuckDbService2({});
+    duckdb.initialize(serviceContext);
+    serviceContext.registerService("duckdb", duckdb);
+    const hooks = new HooksService2({});
+    hooks.initialize(serviceContext);
+    serviceContext.registerService("hooks", hooks);
+    serviceContext.setSession(input.serviceSession);
+    const encryption = this.createEncryptionService({
+      graph,
+      host: input.host,
+      session: input.serviceSession,
+      did: input.nodeDid,
+      address: input.address,
+      chainId: input.chainId
+    });
+    encryption.initialize(serviceContext);
+    serviceContext.registerService("encryption", encryption);
+    const vault = this.createVaultService(input.serviceSession.spaceId, kv, encryption, {
+      host: input.host,
+      did: input.nodeDid,
+      address: input.address,
+      chainId: input.chainId,
+      serviceGraph: graph
+    });
+    vault.initialize(serviceContext);
+    serviceContext.registerService("vault", vault);
+    const capabilityRegistry = new CapabilityKeyRegistry();
+    if (input.tinyCloudSession) {
+      const session = input.tinyCloudSession;
+      const delegations = input.recap.map((entry) => ({
+        cid: session.delegationCid,
+        delegateDID: session.verificationMethod,
+        spaceId: entry.space,
+        path: entry.path,
+        actions: [...entry.actions],
+        caveats: cloneRecapCaveats(entry.caveats),
+        expiry: input.sessionExpiry,
+        isRevoked: false,
+        allowSubDelegation: true
+      }));
+      if (delegations.length > 0) {
+        capabilityRegistry.registerKey({
+          id: session.sessionKey,
+          did: session.verificationMethod,
+          type: "session",
+          jwk: session.jwk,
+          priority: 0
+        }, delegations);
+      }
+    }
+    const delegationManager = new DelegationManager({
+      hosts: [input.host],
+      session: input.serviceSession,
+      invoke: graph.invoke,
+      invokeAny: graph.invokeAny,
+      fetch: graph.fetch
+    });
+    const keyProvider = new WasmKeyProvider({ sessionManager: input.manager });
+    const sharingService = new SharingService({
+      hosts: [input.host],
+      invoke: graph.invoke,
+      fetch: graph.fetch,
+      assertActive: () => graph.assertActive(),
+      keyProvider,
+      registry: capabilityRegistry,
+      createDelegationWasm: (params) => this.createDelegationWrapper(params),
+      computeCid: (data, codec) => {
+        if (!this.wasmBindings.computeCid) throw new Error("computeCid is unavailable");
+        return this.wasmBindings.computeCid(data, codec);
+      },
+      createKVService: (config) => {
+        const service = new KVService2({ prefix: config.pathPrefix?.replace(/\/$/, "") });
+        const context = graph.track(new ServiceContext2({
+          invoke: config.invoke,
+          fetch: config.fetch ?? globalThis.fetch.bind(globalThis),
+          hosts: config.hosts,
+          telemetry: this.config.telemetry
+        }));
+        context.setSession(config.session);
+        service.initialize(context);
+        return service;
+      }
+    });
+    sharingService.updateConfig({
+      session: input.serviceSession,
+      delegationManager,
+      sessionExpiry: input.sessionExpiry,
+      createDelegationWasm: (params) => {
+        graph.assertActive();
+        return this.createDelegationWrapper(params);
+      },
+      onRootDelegationNeeded: this.signer ? async (params) => {
+        graph.assertActive();
+        const delegation = await this.createRootDelegationForSharing(
+          params,
+          () => graph.assertActive()
         );
-      } else {
-        this._restoredTcSession = tcSession;
+        graph.assertActive();
+        return delegation;
+      } : void 0
+    });
+    const spaceService = new SpaceService({
+      hosts: [input.host],
+      session: input.serviceSession,
+      invoke: graph.invoke,
+      fetch: graph.fetch,
+      capabilityRegistry,
+      userDid: input.nodeDid,
+      createKVService: (spaceId) => {
+        graph.assertActive();
+        const scopedKv = new KVService2({});
+        const context = graph.track(new ServiceContext2({
+          invoke: graph.invoke,
+          invokeAny: graph.invokeAny,
+          fetch: graph.fetch,
+          hosts: [input.host],
+          telemetry: this.config.telemetry
+        }));
+        context.setSession({ ...input.serviceSession, spaceId });
+        scopedKv.initialize(context);
+        return scopedKv;
+      },
+      createVaultService: (spaceId) => {
+        graph.assertActive();
+        const scopedKv = new KVService2({});
+        const context = graph.track(new ServiceContext2({
+          invoke: graph.invoke,
+          invokeAny: graph.invokeAny,
+          fetch: graph.fetch,
+          hosts: [input.host],
+          telemetry: this.config.telemetry
+        }));
+        context.setSession({ ...input.serviceSession, spaceId });
+        scopedKv.initialize(context);
+        const scopedVault = this.createVaultService(spaceId, scopedKv, encryption, {
+          host: input.host,
+          did: input.nodeDid,
+          address: input.address,
+          chainId: input.chainId,
+          serviceGraph: graph
+        });
+        scopedVault.initialize(context);
+        return scopedVault;
+      },
+      createSecretsService: (spaceId) => {
+        graph.assertActive();
+        return this.secretsForSpace(spaceId);
+      },
+      createDelegation: async (params) => {
+        graph.assertActive();
+        try {
+          const portableDelegation = await this.createDelegation({
+            delegateDID: params.delegateDID,
+            path: params.path,
+            actions: params.actions,
+            disableSubDelegation: params.disableSubDelegation,
+            expiryMs: params.expiry ? params.expiry.getTime() - Date.now() : void 0
+          });
+          return { ok: true, data: {
+            cid: portableDelegation.cid,
+            delegateDID: portableDelegation.delegateDID,
+            delegatorDID: this.did,
+            spaceId: portableDelegation.spaceId,
+            path: portableDelegation.path,
+            actions: portableDelegation.actions,
+            expiry: portableDelegation.expiry,
+            isRevoked: false,
+            allowSubDelegation: !portableDelegation.disableSubDelegation,
+            createdAt: /* @__PURE__ */ new Date(),
+            authHeader: portableDelegation.delegationHeader.Authorization
+          } };
+        } catch (error) {
+          return { ok: false, error: {
+            code: "CREATION_FAILED",
+            message: error instanceof Error ? error.message : String(error),
+            service: "delegation"
+          } };
+        }
+      },
+      onSpaceRegistered: async (space) => {
+        graph.assertActive();
+        await this.account.spaces.register(space);
       }
-      this.registerPrimarySessionGrant(tcSession);
-    }
+    });
+    spaceService.updateConfig({ sharingService });
+    return { core, graph, serviceContext, kv, sql, duckdb, hooks, vault, encryption, capabilityRegistry, keyProvider, sharingService, delegationManager, spaceService };
   }
   /**
    * Resolve the host a restored session should target.
@@ -20048,14 +20650,19 @@ var _TinyCloudNode = class _TinyCloudNode {
     if (!session) {
       return;
     }
-    this.tc.initializeServices(this.invokeWithRuntimePermissions, [this.config.host]);
-    this._serviceContext = new ServiceContext2({
-      invoke: this.invokeWithRuntimePermissions,
-      invokeAny: this.invokeAnyWithRuntimePermissions,
-      fetch: globalThis.fetch.bind(globalThis),
+    this.tc.initializeServices(
+      this._serviceGraph.invoke,
+      [this.config.host],
+      this._serviceGraph.fetch
+    );
+    this._serviceGraph.track(this.tc.serviceContext);
+    this._serviceContext = this._serviceGraph.track(new ServiceContext2({
+      invoke: this._serviceGraph.invoke,
+      invokeAny: this._serviceGraph.invokeAny,
+      fetch: this._serviceGraph.fetch,
       hosts: [this.config.host],
       telemetry: this.config.telemetry
-    });
+    }));
     this._kv = new KVService2({});
     this._kv.initialize(this._serviceContext);
     this._serviceContext.registerService("kv", this._kv);
@@ -20090,12 +20697,12 @@ var _TinyCloudNode = class _TinyCloudNode {
   createSpaceScopedKVService(spaceId) {
     const kvService = new KVService2({});
     if (this._serviceContext) {
-      const spaceScopedContext = new ServiceContext2({
+      const spaceScopedContext = this._serviceGraph.track(new ServiceContext2({
         invoke: this._serviceContext.invoke,
         fetch: this._serviceContext.fetch,
         hosts: this._serviceContext.hosts,
         telemetry: this.config.telemetry
-      });
+      }));
       const session = this._serviceContext.session;
       if (session) {
         spaceScopedContext.setSession({ ...session, spaceId });
@@ -20128,6 +20735,18 @@ var _TinyCloudNode = class _TinyCloudNode {
     }
     return session;
   }
+  /**
+   * Runtime-permission helpers can be used from an authenticated Node session
+   * before its public ServiceContext is initialized. They still need the
+   * current signed session, never an optional or stale authority object.
+   */
+  requireEncryptionSession() {
+    const session = this._serviceContext?.session ?? this.auth?.tinyCloudSession;
+    if (!session) {
+      throw new Error("Not signed in. Call signIn() first.");
+    }
+    return session;
+  }
   createEncryptionCrypto() {
     const wasm = this.wasmBindings;
     const columnEncrypt = (key2, plaintext) => {
@@ -20183,14 +20802,15 @@ var _TinyCloudNode = class _TinyCloudNode {
     }
     return info.nodeId;
   }
-  async signRawNetworkAuthorization(input) {
+  async signRawNetworkAuthorization(input, binding) {
+    binding?.graph.assertActive();
     if (!this.wasmBindings.invokeAny) {
       throw new Error("WASM binding does not support raw-resource invokeAny");
     }
     if (!this.wasmBindings.computeCid) {
       throw new Error("WASM binding does not support invocation CID computation");
     }
-    const session = this.requireServiceSession();
+    const session = binding?.session ?? this.requireEncryptionSession();
     const headers = this.invokeAnyWithRuntimePermissions(
       session,
       [
@@ -20209,6 +20829,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       input.targetNode,
       session.jwk
     );
+    binding?.graph.assertActive();
     return {
       authorization: audienceBound,
       invocationCid: this.wasmBindings.computeCid(
@@ -20217,25 +20838,55 @@ var _TinyCloudNode = class _TinyCloudNode {
       )
     };
   }
-  createEncryptionService() {
+  async fetchEncryptionNetworkAt(host, networkId, fetchFn) {
+    const response = await fetchFn(
+      `${host}/encryption/networks/${encodeURIComponent(networkId)}`
+    );
+    if (response.status === 404) return null;
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch encryption network ${networkId}: HTTP ${response.status} ${await response.text()}`
+      );
+    }
+    const body = await response.json();
+    return "descriptor" in body && body.descriptor ? body.descriptor : body;
+  }
+  createEncryptionService(binding) {
+    const graph = binding?.graph ?? this._serviceGraph;
+    const host = binding?.host ?? this.config.host;
+    const session = binding?.session ?? this.requireEncryptionSession();
+    const did = binding?.did ?? this.did;
+    const address = binding?.address ?? this._address;
+    const chainId = binding?.chainId ?? this._chainId;
     const crypto2 = this.createEncryptionCrypto();
     const transport = {
-      postDecrypt: async ({ networkId, authorization, canonicalBody }) => {
-        const response = await fetch(
-          `${this.config.host}/encryption/networks/${encodeURIComponent(networkId)}/decrypt`,
+      postDecrypt: async ({ networkId, authorization, canonicalBody, signal }) => {
+        graph.assertActive();
+        const response = await graph.fetch(
+          `${host}/encryption/networks/${encodeURIComponent(networkId)}/decrypt`,
           {
             method: "POST",
             headers: {
               Authorization: authorization,
               "Content-Type": "application/json"
             },
-            body: canonicalBody
+            body: canonicalBody,
+            signal
           }
         );
+        graph.assertActive();
         if (!response.ok) {
-          throw new Error(
-            `decrypt failed ${response.status}: ${await response.text()}`
-          );
+          let permissionHint;
+          if (response.status === 401 || response.status === 403) {
+            try {
+              const body = await response.json();
+              const record = typeof body === "object" && body !== null ? body : void 0;
+              const nested = typeof record?.error === "object" && record.error !== null ? record.error : void 0;
+              permissionHint = parsePermissionHint(record?.permissionHint) ?? parsePermissionHint(nested?.permissionHint);
+            } catch {
+            }
+          }
+          throw new DecryptTransportResponseError(response.status, permissionHint);
         }
         return await response.json();
       }
@@ -20244,12 +20895,14 @@ var _TinyCloudNode = class _TinyCloudNode {
       crypto: crypto2,
       signer: {
         signDecryptInvocation: async (input) => {
+          graph.assertActive();
           const signed2 = await this.signRawNetworkAuthorization({
             targetNode: input.targetNode,
             networkId: input.networkId,
             action: DECRYPT_ACTION2,
             facts: input.facts
-          });
+          }, { graph, session });
+          graph.assertActive();
           return {
             ...signed2,
             canonicalBody: canonicalizeEncryptionJson(
@@ -20260,25 +20913,35 @@ var _TinyCloudNode = class _TinyCloudNode {
       },
       transport,
       node: {
-        fetchByNetworkId: (networkId) => this.getEncryptionNetwork(networkId)
+        fetchByNetworkId: async (networkId) => {
+          graph.assertActive();
+          const descriptor = await this.fetchEncryptionNetworkAt(host, networkId, graph.fetch);
+          graph.assertActive();
+          return descriptor;
+        }
       },
       wellKnown: {
         fetchWellKnown: async (principal, discoveryKey) => {
-          if (!this._address || !didPrincipalMatches2(principal, this.did)) {
-            return null;
-          }
-          if (!this.config.host) {
+          graph.assertActive();
+          if (!address || !didPrincipalMatches2(principal, did)) {
             return null;
           }
-          const publicSpaceId = makePublicSpaceId(this._address, this._chainId);
-          const result = await TinyCloud.readPublicSpace(this.config.host, publicSpaceId, discoveryKey);
-          if (!result.ok) {
+          const publicSpaceId = makePublicSpaceId(address, chainId);
+          const encodedKey = discoveryKey.split("/").map(encodeURIComponent).join("/");
+          const response = await graph.fetch(
+            `${host}/public/${encodeURIComponent(publicSpaceId)}/kv/${encodedKey}`,
+            { method: "GET" }
+          );
+          graph.assertActive();
+          if (!response.ok) {
             return null;
           }
-          const body = result.data;
+          const body = await response.json();
+          graph.assertActive();
           return "descriptor" in body && body.descriptor ? body.descriptor : body;
         }
-      }
+      },
+      assertActive: () => graph.assertActive()
     });
   }
   getEncryptionService() {
@@ -20292,8 +20955,9 @@ var _TinyCloudNode = class _TinyCloudNode {
     }
     return this._encryption;
   }
-  createVaultService(spaceId, kv) {
+  createVaultService(spaceId, kv, encryptionService = this.getEncryptionService(), nodeContext) {
     const wasm = this.wasmBindings;
+    const serviceGraph = nodeContext?.serviceGraph ?? this._serviceGraph;
     const vaultCrypto = createVaultCrypto({
       vault_encrypt: wasm.vault_encrypt,
       vault_decrypt: wasm.vault_decrypt,
@@ -20304,12 +20968,17 @@ var _TinyCloudNode = class _TinyCloudNode {
       vault_sha256: wasm.vault_sha256
     });
     const self2 = this;
+    const did = nodeContext?.did ?? this.did;
+    const address = nodeContext?.address ?? this._address;
+    const chainId = nodeContext?.chainId ?? this._chainId;
+    const host = nodeContext?.host ?? this.config.host;
+    const ownerDid = this.ownerDidFromSpaceId(spaceId) ?? did;
     return new DataVaultService({
       spaceId,
       crypto: vaultCrypto,
       encryption: {
-        networkId: this.getEncryptionNetworkIdForSpace(spaceId),
-        service: this.getEncryptionService(),
+        networkId: `urn:tinycloud:encryption:${ownerDid}:${DEFAULT_ENCRYPTION_NETWORK_NAME}`,
+        service: encryptionService,
         decryptCapabilityProof: () => ({
           proofs: [this.requireServiceSession().delegationCid]
         })
@@ -20318,6 +20987,7 @@ var _TinyCloudNode = class _TinyCloudNode {
         kv,
         ensurePublicSpace: async () => {
           try {
+            serviceGraph.assertActive();
             await self2.ensurePublicSpace();
             return { ok: true, data: void 0 };
           } catch (error) {
@@ -20325,14 +20995,15 @@ var _TinyCloudNode = class _TinyCloudNode {
           }
         },
         get publicKV() {
+          serviceGraph.assertActive();
           return self2._publicKV ?? self2.tc.publicKV;
         },
-        readPublicSpace: (host, targetSpaceId, key2) => TinyCloud.readPublicSpace(host, targetSpaceId, key2),
+        readPublicSpace: (host2, targetSpaceId, key2) => TinyCloud.readPublicSpace(host2, targetSpaceId, key2),
         makePublicSpaceId: TinyCloud.makePublicSpaceId,
-        did: this.did,
-        address: this._address ?? "",
-        chainId: this._chainId,
-        hosts: [this.config.host]
+        did,
+        address: address ?? "",
+        chainId,
+        hosts: [host]
       }
     });
   }
@@ -20341,6 +21012,7 @@ var _TinyCloudNode = class _TinyCloudNode {
    * @internal
    */
   initializeV2Services(serviceSession) {
+    const graph = this._serviceGraph;
     this._capabilityRegistry = new CapabilityKeyRegistry();
     const tcSession = this.auth?.tinyCloudSession;
     if (tcSession && this._address) {
@@ -20385,21 +21057,23 @@ var _TinyCloudNode = class _TinyCloudNode {
       hosts: [this.config.host],
       accountSpaceId: this.accountSpaceId,
       session: serviceSession,
-      invoke: this.invokeWithRuntimePermissions,
-      invokeAny: this.invokeAnyWithRuntimePermissions,
-      fetch: globalThis.fetch.bind(globalThis)
+      invoke: graph.invoke,
+      invokeAny: graph.invokeAny,
+      fetch: graph.fetch
     });
     this._spaceService = new SpaceService({
       hosts: [this.config.host],
       session: serviceSession,
-      invoke: this.wasmBindings.invoke,
-      fetch: globalThis.fetch.bind(globalThis),
+      invoke: graph.invoke,
+      fetch: graph.fetch,
       capabilityRegistry: this._capabilityRegistry,
       userDid: this.did,
       createKVService: (spaceId) => {
+        graph.assertActive();
         return this.createSpaceScopedKVService(spaceId);
       },
       createVaultService: (spaceId) => {
+        graph.assertActive();
         const kvService = this.createSpaceScopedKVService(spaceId);
         const vaultService = this.createVaultService(spaceId, kvService);
         if (this._serviceContext) {
@@ -20408,11 +21082,13 @@ var _TinyCloudNode = class _TinyCloudNode {
         return vaultService;
       },
       createSecretsService: (spaceId) => {
+        graph.assertActive();
         return this.secretsForSpace(spaceId);
       },
       // Enable space.delegations.create() via SIWE-based delegation
       createDelegation: async (params) => {
         try {
+          graph.assertActive();
           const portableDelegation = await this.createDelegation({
             delegateDID: params.delegateDID,
             path: params.path,
@@ -20446,18 +21122,50 @@ var _TinyCloudNode = class _TinyCloudNode {
         }
       },
       onSpaceRegistered: async (space) => {
+        graph.assertActive();
         await this.account.spaces.register(space);
       }
     });
-    this._sharingService.updateConfig({
+    this._sharingService = new SharingService({
+      hosts: [this.config.host],
       session: serviceSession,
+      invoke: graph.invoke,
+      fetch: graph.fetch,
+      assertActive: () => graph.assertActive(),
+      keyProvider: this._keyProvider,
+      registry: this._capabilityRegistry,
       delegationManager: this._delegationManager,
       sessionExpiry: this.getSessionExpiry(),
-      // WASM-based delegation creation (preferred - no server roundtrip)
-      createDelegationWasm: (params) => this.createDelegationWrapper(params),
-      // Root delegation for long-lived share links (bypasses session expiry)
-      // In node-sdk we have direct signer access, so no popup needed
-      onRootDelegationNeeded: this.signer ? async (params) => this.createRootDelegationForSharing(params) : void 0
+      createDelegationWasm: (params) => {
+        graph.assertActive();
+        return this.createDelegationWrapper(params);
+      },
+      computeCid: (data, codec) => {
+        if (!this.wasmBindings.computeCid) throw new Error("computeCid is unavailable");
+        return this.wasmBindings.computeCid(data, codec);
+      },
+      createKVService: (config) => {
+        graph.assertActive();
+        const service = new KVService2({ prefix: config.pathPrefix?.replace(/\/$/, "") });
+        const context = graph.track(new ServiceContext2({
+          invoke: config.invoke,
+          fetch: config.fetch ?? graph.fetch,
+          hosts: config.hosts,
+          telemetry: this.config.telemetry
+        }));
+        context.setSession(config.session);
+        service.initialize(context);
+        return service;
+      },
+      onRootDelegationNeeded: this.signer ? async (params) => {
+        graph.assertActive();
+        const delegation = await this.createRootDelegationForSharing(
+          params,
+          () => graph.assertActive()
+        );
+        graph.assertActive();
+        return delegation;
+      } : void 0
     });
     this._spaceService.updateConfig({
       sharingService: this._sharingService
@@ -20524,7 +21232,9 @@ var _TinyCloudNode = class _TinyCloudNode {
    * with expiry longer than the current session.
    * @internal
    */
-  async createOwnerDelegation(params) {
+  async createOwnerDelegation(params, assertActive) {
+    const assertOwnerGraphActive = assertActive ?? this._serviceGraph.assertActive.bind(this._serviceGraph);
+    assertOwnerGraphActive();
     if (!params.delegateDid.startsWith("did:key:") || params.actions.length === 0 || params.path.length === 0) {
       throw new Error("Owner delegation requires an external did:key audience and bounded capabilities");
     }
@@ -20549,8 +21259,10 @@ var _TinyCloudNode = class _TinyCloudNode {
       delegateUri: params.delegateDid
     });
     const signature2 = await this.signer.signMessage(prepared.siwe);
+    assertOwnerGraphActive();
     const delegationSession = this.wasmBindings.completeSessionSetup({ ...prepared, signature: signature2 });
     const activation = await activateSessionWithHost2(host, delegationSession.delegationHeader);
+    assertOwnerGraphActive();
     if (!activation.success) {
       throw new Error(`Owner delegation import failed: ${activation.status} ${activation.error ?? ""}`.trim());
     }
@@ -20578,7 +21290,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       }
     };
   }
-  async createRootDelegationForSharing(params) {
+  async createRootDelegationForSharing(params, assertActive) {
     try {
       return (await this.createOwnerDelegation({
         delegateDid: params.shareKeyDID,
@@ -20586,8 +21298,9 @@ var _TinyCloudNode = class _TinyCloudNode {
         path: params.path,
         actions: params.actions,
         expiresAt: params.requestedExpiry
-      })).delegation;
+      }, assertActive)).delegation;
     } catch {
+      assertActive?.();
       return void 0;
     }
   }
@@ -20659,13 +21372,13 @@ var _TinyCloudNode = class _TinyCloudNode {
       throw new Error("Not signed in. Call signIn() first.");
     }
     const sql = new SQLService2({});
-    const spaceScopedContext = new ServiceContext2({
+    const spaceScopedContext = this._serviceGraph.track(new ServiceContext2({
       invoke: this._serviceContext.invoke,
       invokeAny: this._serviceContext.invokeAny,
       fetch: this._serviceContext.fetch,
       hosts: this._serviceContext.hosts,
       telemetry: this.config.telemetry
-    });
+    }));
     spaceScopedContext.setSession({ ...this._serviceContext.session, spaceId });
     sql.initialize(spaceScopedContext);
     return sql;
@@ -20689,12 +21402,12 @@ var _TinyCloudNode = class _TinyCloudNode {
       throw new Error("Not signed in. Call signIn() first.");
     }
     const kv = new KVService2({});
-    const spaceScopedContext = new ServiceContext2({
+    const spaceScopedContext = this._serviceGraph.track(new ServiceContext2({
       invoke: this._serviceContext.invoke,
       invokeAny: this._serviceContext.invokeAny,
       fetch: this._serviceContext.fetch,
       hosts: this._serviceContext.hosts
-    });
+    }));
     spaceScopedContext.setSession({ ...this._serviceContext.session, spaceId });
     kv.initialize(spaceScopedContext);
     return kv;
@@ -20730,19 +21443,11 @@ var _TinyCloudNode = class _TinyCloudNode {
   }
   async getEncryptionNetwork(nameOrNetworkId = this.getDefaultEncryptionNetworkId()) {
     const networkId = nameOrNetworkId.startsWith("urn:tinycloud:encryption:") ? nameOrNetworkId : this.getDefaultEncryptionNetworkId(nameOrNetworkId);
-    const response = await fetch(
-      `${this.config.host}/encryption/networks/${encodeURIComponent(networkId)}`
+    return this.fetchEncryptionNetworkAt(
+      this.config.host,
+      networkId,
+      globalThis.fetch.bind(globalThis)
     );
-    if (response.status === 404) {
-      return null;
-    }
-    if (!response.ok) {
-      throw new Error(
-        `Failed to fetch encryption network ${networkId}: HTTP ${response.status} ${await response.text()}`
-      );
-    }
-    const body = await response.json();
-    return "descriptor" in body && body.descriptor ? body.descriptor : body;
   }
   async createEncryptionNetwork(name = DEFAULT_ENCRYPTION_NETWORK_NAME) {
     const targetNode = await this.fetchNodeId();
@@ -20836,6 +21541,38 @@ var _TinyCloudNode = class _TinyCloudNode {
     }
     return secrets;
   }
+  /**
+   * Read a secret from an explicit target space without requesting or
+   * auto-signing authority. Active runtime delegations are selected by the
+   * normal KV and encryption invocation paths.
+   */
+  async readSecret(input) {
+    const resolved = resolveSecretPath2(input.name, { scope: input.scope });
+    const targetSpace = input.space.startsWith("tinycloud:") ? input.space : this.ownedSpaceId(input.space);
+    const result = await this.getBaseVault(targetSpace).readNetworkEncrypted(
+      resolved.vaultKey
+    );
+    if (result.status !== "ok") {
+      if (result.status === "permission_required") {
+        const hint = parsePermissionHint(result.hint);
+        if (hint === void 0) return { status: "read_failed" };
+        return {
+          status: "permission_required",
+          hint: {
+            service: hint.service,
+            ...hint.space === void 0 ? {} : { space: hint.space },
+            path: hint.path,
+            actions: [...hint.actions]
+          }
+        };
+      }
+      return { status: result.status };
+    }
+    if (!isSecretPayload(result.entry.value)) {
+      return { status: "invalid_payload" };
+    }
+    return { status: "ok", value: result.entry.value.value };
+  }
   getBaseSecrets(spaceId) {
     if (!this._spaceService) {
       throw new Error("Not signed in. Call signIn() first.");
@@ -20843,16 +21580,29 @@ var _TinyCloudNode = class _TinyCloudNode {
     const resolvedSpace = spaceId.startsWith("tinycloud:") ? spaceId : this.ownedSpaceId(spaceId);
     let secrets = this._baseSecrets.get(resolvedSpace);
     if (!secrets) {
-      const kvService = this.createSpaceScopedKVService(resolvedSpace);
-      const vaultService = this.createVaultService(resolvedSpace, kvService);
-      if (this._serviceContext) {
-        vaultService.initialize(this._serviceContext);
-      }
-      secrets = new SecretsService(() => vaultService);
+      secrets = new SecretsService(() => this.getBaseVault(resolvedSpace));
       this._baseSecrets.set(resolvedSpace, secrets);
     }
     return secrets;
   }
+  getBaseVault(spaceId) {
+    if (!this._spaceService) {
+      throw new Error("Not signed in. Call signIn() first.");
+    }
+    const resolvedSpace = spaceId.startsWith("tinycloud:") ? spaceId : this.ownedSpaceId(spaceId);
+    let vault = this._baseVaults.get(resolvedSpace);
+    if (!vault) {
+      vault = this.createVaultService(
+        resolvedSpace,
+        this.createSpaceScopedKVService(resolvedSpace)
+      );
+      if (this._serviceContext) {
+        vault.initialize(this._serviceContext);
+      }
+      this._baseVaults.set(resolvedSpace, vault);
+    }
+    return vault;
+  }
   /**
    * Hooks write stream subscription API.
    */
@@ -20957,6 +21707,63 @@ var _TinyCloudNode = class _TinyCloudNode {
       (grant) => grant.delegation
     );
   }
+  /**
+   * Return the effective capabilities of installed runtime grants.
+   *
+   * The result is projected from the SDK's activated, expiry-pruned grant
+   * operations rather than from PortableDelegation transport metadata. Base
+   * session authority is intentionally omitted; callers that need the full
+   * live authority must combine this with {@link getVerifiedSessionCapabilities}.
+   */
+  getEffectiveRuntimePermissionEntries() {
+    const session = this.currentTinyCloudSession();
+    if (!session) return [];
+    this.pruneExpiredRuntimePermissionGrants();
+    const grouped = /* @__PURE__ */ new Map();
+    for (const grant of this.runtimePermissionGrants) {
+      if (grant.provenance === "primary") continue;
+      for (const operation of grant.operations) {
+        const service = SERVICE_SHORT_TO_LONG[operation.service];
+        if (service === void 0 || typeof operation.path !== "string" || typeof operation.action !== "string") {
+          continue;
+        }
+        let space;
+        if (service !== "tinycloud.encryption") {
+          if (typeof operation.spaceId !== "string") continue;
+          try {
+            space = this.resolvePermissionSpace(operation.spaceId, session);
+          } catch {
+            continue;
+          }
+        }
+        const caveats = operation.caveats === void 0 || operation.caveats.length === 0 ? void 0 : cloneRecapCaveats(operation.caveats);
+        const identity = JSON.stringify({
+          service,
+          ...space === void 0 ? {} : { space },
+          path: operation.path,
+          caveats: canonicalizeRecapCaveats(caveats)
+        });
+        const existing = grouped.get(identity);
+        if (existing === void 0) {
+          grouped.set(identity, {
+            service,
+            ...space === void 0 ? {} : { space },
+            path: operation.path,
+            actions: [operation.action],
+            ...caveats === void 0 ? {} : { caveats }
+          });
+          continue;
+        }
+        if (!existing.actions.includes(operation.action)) {
+          existing.actions.push(operation.action);
+          existing.actions.sort();
+        }
+      }
+    }
+    return [...grouped.values()].sort(
+      (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"))
+    );
+  }
   /**
    * Install a portable runtime permission delegation into this SDK instance so
    * matching service calls and downstream `delegateTo()` calls can use it.
@@ -21025,6 +21832,7 @@ var _TinyCloudNode = class _TinyCloudNode {
         "grantRuntimePermissions requires wallet mode with a signer or privateKey."
       );
     }
+    this.assertDelegationCaveatsPreservable(expanded);
     const rawEntries = expanded.filter(
       (entry) => this.isEncryptionPermissionEntry(entry)
     );
@@ -21286,12 +22094,12 @@ var _TinyCloudNode = class _TinyCloudNode {
     }
     if (this._serviceContext) {
       const publicKV = new KVService2({ prefix: "" });
-      const publicContext = new ServiceContext2({
-        invoke: this.invokeWithRuntimePermissions,
-        fetch: this._serviceContext.fetch,
+      const publicContext = this._serviceGraph.track(new ServiceContext2({
+        invoke: this._serviceGraph.invoke,
+        fetch: this._serviceGraph.fetch,
         hosts: this._serviceContext.hosts,
         telemetry: this.config.telemetry
-      });
+      }));
       publicContext.setSession({
         delegationHeader: delegationSession.delegationHeader,
         delegationCid: delegationSession.delegationCid,
@@ -21358,13 +22166,14 @@ var _TinyCloudNode = class _TinyCloudNode {
   async getDelegationStatus(cid) {
     return this.delegationManager.status(cid);
   }
-  /** Compute the canonical CID of a compact delegation authorization. */
+  /** Compute the canonical CID of a compact UCAN or DAG-CBOR delegation authorization. */
   computeDelegationCid(authorization) {
     if (!authorization || !this.wasmBindings.computeCid) {
       throw new Error("Delegation CID computation is unavailable");
     }
+    const compact = authorization.replace(/^Bearer /i, "");
     return this.wasmBindings.computeCid(
-      new TextEncoder().encode(authorization),
+      compact.includes(".") ? new TextEncoder().encode(compact) : decodeAuthorizationBytes(authorization),
       0x55n
     );
   }
@@ -21456,6 +22265,7 @@ var _TinyCloudNode = class _TinyCloudNode {
           "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."
         );
       }
+      this.assertDelegationCaveatsPreservable(expandedEntries);
       const delegation2 = await this.createDelegationLegacyWalletPath(
         did,
         expandedEntries[0],
@@ -21464,13 +22274,14 @@ var _TinyCloudNode = class _TinyCloudNode {
       return { delegation: delegation2, prompted: true };
     }
     const granted = parseRecapCapabilities(
-      (siwe) => this.wasmBindings.parseRecapFromSiwe(siwe),
+      (siwe) => this.parseRecapWithCaveats(siwe),
       session.siwe
     );
     const { subset, missing } = isCapabilitySubset(expandedEntries, granted);
     if (!subset) {
+      const runtimeOperations = this.permissionEntriesToOperations(expandedEntries, session);
       const runtimeGrant = this.findGrantForOperations(
-        this.permissionEntriesToOperations(expandedEntries, session),
+        runtimeOperations,
         { excludePrimary: true }
       );
       if (runtimeGrant) {
@@ -21483,7 +22294,8 @@ var _TinyCloudNode = class _TinyCloudNode {
           did,
           expandedEntries,
           runtimeExpiration,
-          runtimeGrant
+          runtimeGrant,
+          runtimeOperations
         );
         return { delegation: delegation2, prompted: false };
       }
@@ -21553,6 +22365,7 @@ var _TinyCloudNode = class _TinyCloudNode {
         "createDelegationViaWasmPath requires a non-empty entries array"
       );
     }
+    this.assertDelegationCaveatsPreservable(entries);
     const resolvedSpaces = /* @__PURE__ */ new Set();
     for (const entry of entries) {
       if (this.isEncryptionPermissionEntry(entry)) {
@@ -21633,7 +22446,9 @@ var _TinyCloudNode = class _TinyCloudNode {
       host: this.config.host
     };
   }
-  async createDelegationViaRuntimeGrant(did, entries, expirationTime, grant) {
+  async createDelegationViaRuntimeGrant(did, entries, expirationTime, grant, requestedOperations) {
+    this.assertRuntimeGrantCaveatsPreservable(entries, requestedOperations, grant);
+    this.assertDelegationCaveatsPreservable(entries);
     const result = this.createDelegationWrapper({
       session: grant.session,
       delegateDID: did,
@@ -21687,6 +22502,74 @@ var _TinyCloudNode = class _TinyCloudNode {
   expandPermissionEntries(permissions) {
     return expandPermissionEntriesCore(permissions);
   }
+  /**
+   * The current WASM child-delegation APIs accept action-only maps. Refuse any
+   * constrained branch rather than signing a broader action-only child UCAN.
+   */
+  assertDelegationCaveatsPreservable(entries) {
+    const caveated = entries.filter(
+      (entry) => !recapCaveatsEqual(entry.caveats, void 0)
+    );
+    if (caveated.length > 0) {
+      throw new CaveatedDelegationUnsupportedError(caveated);
+    }
+  }
+  /**
+   * Runtime grant selection intentionally allows an uncaveated operation to
+   * select a caveated grant so invocation can restore the signed caveat before
+   * crossing the caveat-aware WASM boundary. Child delegation cannot do that:
+   * it only accepts action maps, so reject the selected constrained branch.
+   */
+  assertRuntimeGrantCaveatsPreservable(entries, requestedOperations, grant) {
+    let operationIndex = 0;
+    const caveated = [];
+    for (const entry of entries) {
+      for (const action of entry.actions) {
+        const requested = requestedOperations[operationIndex++];
+        if (!requested) continue;
+        const constrained = grant.operations.find(
+          (granted) => this.operationCovers(granted, requested) && !recapCaveatsEqual(granted.caveats, void 0)
+        );
+        if (constrained) {
+          caveated.push({
+            ...entry,
+            actions: [action],
+            caveats: cloneRecapCaveats(constrained.caveats)
+          });
+        }
+      }
+    }
+    if (caveated.length > 0) {
+      throw new CaveatedDelegationUnsupportedError(caveated);
+    }
+  }
+  /** Reject caveated parent branches before action-only child signing. */
+  assertPortableDelegationCaveatsPreservable(delegation) {
+    const entries = [];
+    const add3 = (service, space, path, actions, caveats) => {
+      if (recapCaveatsEqual(caveats, void 0)) return;
+      entries.push({
+        service: service.startsWith("tinycloud.") ? service : `tinycloud.${service}`,
+        space,
+        path,
+        actions: [...actions],
+        caveats: cloneRecapCaveats(caveats)
+      });
+    };
+    add3(
+      delegation.actions[0]?.split("/", 1)[0] ?? "tinycloud.unknown",
+      delegation.spaceId,
+      delegation.path,
+      delegation.actions,
+      delegation.caveats
+    );
+    for (const resource of delegation.resources ?? []) {
+      add3(resource.service, resource.space, resource.path, resource.actions, resource.caveats);
+    }
+    if (entries.length > 0) {
+      throw new CaveatedDelegationUnsupportedError(entries);
+    }
+  }
   shortServiceName(service) {
     const short = SERVICE_LONG_TO_SHORT[service];
     if (short === void 0) {
@@ -21741,14 +22624,15 @@ var _TinyCloudNode = class _TinyCloudNode {
         ...this.isEncryptionNetworkOperation(service, entry.path) ? { resource: entry.path } : { spaceId },
         service,
         path: entry.path,
-        action
+        action,
+        ...entry.caveats === void 0 ? {} : { caveats: cloneRecapCaveats(entry.caveats) }
       }));
     });
   }
   sessionCoversPermissionEntries(session, entries) {
     try {
       const granted = parseRecapCapabilities(
-        (siwe) => this.wasmBindings.parseRecapFromSiwe(siwe),
+        (siwe) => this.parseRecapWithCaveats(siwe),
         session.siwe
       );
       return isCapabilitySubset(entries, granted).subset;
@@ -21764,7 +22648,8 @@ var _TinyCloudNode = class _TinyCloudNode {
         ...this.isEncryptionNetworkOperation(service, entry.path) ? { resource: entry.path } : { spaceId },
         service,
         path: entry.path,
-        action
+        action,
+        ...entry.caveats === void 0 ? {} : { caveats: cloneRecapCaveats(entry.caveats) }
       }));
     });
   }
@@ -21840,7 +22725,8 @@ var _TinyCloudNode = class _TinyCloudNode {
       service: this.shortServiceName(entry.service),
       space: this.isEncryptionPermissionEntry(entry) ? "encryption" : spaceId,
       path: entry.path,
-      actions: [...entry.actions]
+      actions: [...entry.actions],
+      ...entry.caveats === void 0 ? {} : { caveats: cloneRecapCaveats(entry.caveats) }
     }));
   }
   operationsFromDelegation(delegation) {
@@ -21851,7 +22737,8 @@ var _TinyCloudNode = class _TinyCloudNode {
         ...this.isEncryptionNetworkOperation(service, resource.path) ? { resource: resource.path } : { spaceId: resource.space },
         service,
         path: resource.path,
-        action
+        action,
+        caveats: cloneRecapCaveats(resource.caveats)
       }));
     });
   }
@@ -21867,7 +22754,8 @@ var _TinyCloudNode = class _TinyCloudNode {
       service,
       space: delegation.spaceId,
       path: delegation.path,
-      actions
+      actions,
+      ...delegation.caveats === void 0 ? {} : { caveats: cloneRecapCaveats(delegation.caveats) }
     }));
   }
   /**
@@ -21968,6 +22856,9 @@ var _TinyCloudNode = class _TinyCloudNode {
     if (granted.service !== requested.service || !this.actionContains(granted.action, requested.action)) {
       return false;
     }
+    if (requested.caveats !== void 0 && !recapCaveatsEqual(granted.caveats, requested.caveats)) {
+      return false;
+    }
     if (granted.resource !== void 0 || requested.resource !== void 0) {
       return granted.resource !== void 0 && requested.resource !== void 0 && granted.resource === requested.resource && this.pathContains(granted.path, requested.path);
     }
@@ -22002,6 +22893,10 @@ var _TinyCloudNode = class _TinyCloudNode {
   invocationServiceName(service) {
     return service.startsWith("tinycloud.") ? this.shortServiceName(service) : service;
   }
+  /** Prefer the v2 caveat-preserving parser while retaining old custom WASM. */
+  parseRecapWithCaveats(siwe) {
+    return this.wasmBindings.parseVerifiedRecapFromSiwe?.(siwe) ?? this.wasmBindings.parseRecapFromSiwe(siwe);
+  }
   isEncryptionNetworkOperation(service, path) {
     return service === "encryption" && path.startsWith("urn:tinycloud:encryption:");
   }
@@ -22012,7 +22907,8 @@ var _TinyCloudNode = class _TinyCloudNode {
         resource: entry.resource,
         service,
         path: entry.path,
-        action: entry.action
+        action: entry.action,
+        ...entry.caveats === void 0 ? {} : { caveats: cloneRecapCaveats(entry.caveats) }
       };
     }
     if (this.isEncryptionNetworkOperation(service, entry.path)) {
@@ -22020,7 +22916,8 @@ var _TinyCloudNode = class _TinyCloudNode {
         resource: entry.path,
         service,
         path: entry.path,
-        action: entry.action
+        action: entry.action,
+        ...entry.caveats === void 0 ? {} : { caveats: cloneRecapCaveats(entry.caveats) }
       };
     }
     if (typeof entry.spaceId === "string") {
@@ -22028,7 +22925,8 @@ var _TinyCloudNode = class _TinyCloudNode {
         spaceId: entry.spaceId,
         service,
         path: entry.path,
-        action: entry.action
+        action: entry.action,
+        ...entry.caveats === void 0 ? {} : { caveats: cloneRecapCaveats(entry.caveats) }
       };
     }
     return void 0;
@@ -22368,6 +23266,7 @@ var _TinyCloudNode = class _TinyCloudNode {
    * @returns A portable delegation for the sub-delegate
    */
   async createSubDelegation(parentDelegation, params) {
+    this.assertPortableDelegationCaveatsPreservable(parentDelegation);
     if (!this.signer) {
       throw new Error("Cannot createSubDelegation() in session-only mode. Requires wallet mode.");
     }
@@ -22484,7 +23383,7 @@ import {
   parsePkhDid,
   pkhDid as pkhDid3,
   principalDid,
-  principalDidEquals as principalDidEquals3,
+  principalDidEquals as principalDidEquals4,
   parseCanonicalNetworkId,
   TinyCloudDebugLogger,
   tinyCloudDebugLogger,
@@ -22622,6 +23521,7 @@ import {
   DEFAULT_MANIFEST_SPACE as DEFAULT_MANIFEST_SPACE2,
   DEFAULT_MANIFEST_VERSION,
   VAULT_PERMISSION_SERVICE,
+  CaveatedDelegationUnsupportedError as CaveatedDelegationUnsupportedError2,
   PermissionNotInManifestError as PermissionNotInManifestError2,
   SessionExpiredError as SessionExpiredError2,
   ManifestValidationError,
@@ -22638,6 +23538,283 @@ import {
 } from "@tinycloud/sdk-core";
 
 // src/delegation.ts
+import {
+  canonicalizeRecapCaveats as canonicalizeRecapCaveats2,
+  principalDidEquals as principalDidEquals3
+} from "@tinycloud/sdk-core";
+var SERVICE_BY_SHORT_NAME = {
+  kv: "tinycloud.kv",
+  sql: "tinycloud.sql",
+  duckdb: "tinycloud.duckdb",
+  hooks: "tinycloud.hooks"
+};
+function authorizationWithoutBearer(authorization) {
+  return authorization.replace(/^Bearer /i, "");
+}
+function normalizedHost(host) {
+  if (typeof host !== "string" || host.length === 0) {
+    throw new Error("Validated runtime delegation requires a non-empty host.");
+  }
+  return host.replace(/\/+$/, "");
+}
+function didPrincipalsMatch(left, right) {
+  try {
+    return principalDidEquals3(left, right);
+  } catch {
+    return left === right;
+  }
+}
+function compactUcanPayload(authorization) {
+  const compact = authorizationWithoutBearer(authorization);
+  const parts = compact.split(".");
+  if (parts.length !== 3 || parts.some((part) => part.length === 0)) {
+    throw new Error(
+      "Validated runtime delegation requires a compact UCAN authorization so its signed authority can be derived."
+    );
+  }
+  try {
+    const payload = JSON.parse(
+      Buffer.from(parts[1], "base64url").toString("utf8")
+    );
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+      throw new Error("payload is not an object");
+    }
+    return payload;
+  } catch {
+    throw new Error(
+      "Validated runtime delegation authorization has an invalid compact UCAN payload."
+    );
+  }
+}
+function canonicalPermissionEntries(permissions) {
+  return permissions.map((permission) => ({
+    ...permission,
+    actions: [...permission.actions].sort()
+  })).sort(
+    (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")) || canonicalizeRecapCaveats2(left.caveats).localeCompare(canonicalizeRecapCaveats2(right.caveats))
+  );
+}
+function signedCaveats(value) {
+  if (!Array.isArray(value) || value.some(
+    (caveat) => caveat === null || typeof caveat !== "object" || Array.isArray(caveat)
+  )) {
+    throw new Error("Validated runtime delegation has malformed signed ReCap caveats.");
+  }
+  const cloned = JSON.parse(JSON.stringify(value));
+  return canonicalizeRecapCaveats2(cloned) === canonicalizeRecapCaveats2(void 0) ? void 0 : cloned;
+}
+function groupedSignedEntries(service, space, path, abilities) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const [action, rawCaveats] of Object.entries(abilities)) {
+    const caveats = signedCaveats(rawCaveats);
+    const identity = canonicalizeRecapCaveats2(caveats);
+    const group = groups.get(identity) ?? { actions: [], caveats };
+    group.actions.push(action);
+    groups.set(identity, group);
+  }
+  return [...groups.values()].map((group) => ({
+    service,
+    ...space === void 0 ? {} : { space },
+    path,
+    actions: group.actions.sort(),
+    ...group.caveats === void 0 ? {} : { caveats: group.caveats }
+  }));
+}
+function signedAuthorityFromCompactUcan(authorization) {
+  const payload = compactUcanPayload(authorization);
+  if (typeof payload.aud !== "string" || payload.aud.length === 0) {
+    throw new Error("Validated runtime delegation is missing a signed audience.");
+  }
+  if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
+    throw new Error("Validated runtime delegation is missing a signed expiry.");
+  }
+  const expiry = new Date(payload.exp * 1e3);
+  if (Number.isNaN(expiry.getTime())) {
+    throw new Error("Validated runtime delegation has an invalid signed expiry.");
+  }
+  if (payload.att === null || typeof payload.att !== "object" || Array.isArray(payload.att)) {
+    throw new Error("Validated runtime delegation is missing a signed attenuation.");
+  }
+  const permissions = [];
+  for (const [resource, abilities] of Object.entries(payload.att)) {
+    if (abilities === null || typeof abilities !== "object" || Array.isArray(abilities)) {
+      throw new Error("Validated runtime delegation has an invalid signed attenuation.");
+    }
+    const abilityEntries = Object.entries(abilities);
+    if (abilityEntries.length === 0) {
+      throw new Error("Validated runtime delegation has an empty signed capability.");
+    }
+    if (resource.startsWith("urn:tinycloud:encryption:")) {
+      permissions.push(...groupedSignedEntries(
+        "tinycloud.encryption",
+        void 0,
+        resource,
+        abilities
+      ));
+      continue;
+    }
+    const match = /^(tinycloud:[^/]+)\/(kv|sql|duckdb|hooks)\/(.*)$/.exec(resource);
+    if (!match) {
+      throw new Error(
+        `Validated runtime delegation has an unsupported signed resource '${resource}'.`
+      );
+    }
+    const [, space, shortService, path] = match;
+    const service = SERVICE_BY_SHORT_NAME[shortService];
+    if (service === void 0) {
+      throw new Error(
+        `Validated runtime delegation has an unsupported signed service '${shortService}'.`
+      );
+    }
+    permissions.push(...groupedSignedEntries(
+      service,
+      space,
+      path,
+      abilities
+    ));
+  }
+  if (permissions.length === 0) {
+    throw new Error("Validated runtime delegation has no signed capabilities.");
+  }
+  const canonicalPermissions = canonicalPermissionEntries(permissions);
+  const canonicalResources = canonicalPermissions.map((permission) => ({
+    service: permission.service === "tinycloud.encryption" ? "encryption" : permission.service.slice("tinycloud.".length),
+    space: permission.service === "tinycloud.encryption" ? "encryption" : permission.space,
+    path: permission.path,
+    actions: [...permission.actions],
+    ...permission.caveats === void 0 ? {} : { caveats: permission.caveats }
+  }));
+  return {
+    audience: payload.aud,
+    expiry,
+    permissions: canonicalPermissions,
+    resources: canonicalResources
+  };
+}
+function canonicalResourcesFromPortableDelegation(delegation) {
+  if (delegation.resources !== void 0 && delegation.resources.length > 0) {
+    return delegation.resources.map((resource) => ({ ...resource, actions: [...resource.actions].sort() })).sort(
+      (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")) || canonicalizeRecapCaveats2(left.caveats).localeCompare(canonicalizeRecapCaveats2(right.caveats))
+    );
+  }
+  const byService = /* @__PURE__ */ new Map();
+  for (const action of delegation.actions) {
+    const [service] = action.split("/", 1);
+    const shortService = service.replace(/^tinycloud\./, "");
+    const values = byService.get(shortService) ?? [];
+    values.push(action);
+    byService.set(shortService, values);
+  }
+  return [...byService.entries()].map(([service, actions]) => ({
+    service,
+    space: service === "encryption" ? "encryption" : delegation.spaceId,
+    path: delegation.path,
+    actions: [...new Set(actions)].sort(),
+    ...delegation.caveats === void 0 ? {} : { caveats: delegation.caveats }
+  })).sort(
+    (left, right) => left.service.localeCompare(right.service) || left.space.localeCompare(right.space) || left.path.localeCompare(right.path)
+  );
+}
+function resourcesMatch(actual, expected) {
+  const comparable = (resource) => ({
+    ...resource,
+    caveats: canonicalizeRecapCaveats2(resource.caveats)
+  });
+  return JSON.stringify(actual.map(comparable)) === JSON.stringify(expected.map(comparable));
+}
+async function activateValidatedRuntimeDelegation(node, delegation, options) {
+  const host = normalizedHost(options.host);
+  if (delegation.host !== void 0 && normalizedHost(delegation.host) !== host) {
+    throw new Error(
+      `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.");
+  }
+  if (delegation.expiry.getTime() <= Date.now()) {
+    throw new Error("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.");
+  }
+  const cid = node.computeDelegationCid(authorization);
+  if (cid !== delegation.cid) {
+    throw new Error("Runtime delegation CID does not match authorization bytes.");
+  }
+  const signed2 = signedAuthorityFromCompactUcan(authorization);
+  if (signed2.expiry.getTime() <= Date.now()) {
+    throw new Error("Runtime delegation is expired.");
+  }
+  if (delegation.expiry.getTime() !== signed2.expiry.getTime()) {
+    throw new Error("Runtime delegation expiry does not match signed authority.");
+  }
+  if (!didPrincipalsMatch(signed2.audience, node.sessionDid)) {
+    throw new Error(
+      `Runtime delegation targets ${signed2.audience} but this session is ${node.sessionDid}.`
+    );
+  }
+  if (!didPrincipalsMatch(delegation.delegateDID, signed2.audience)) {
+    throw new Error("Runtime delegation audience does not match signed authority.");
+  }
+  const declaredResources = canonicalResourcesFromPortableDelegation(delegation);
+  if (!resourcesMatch(declaredResources, signed2.resources)) {
+    throw new Error("Runtime delegation resources do not match signed authority.");
+  }
+  const previouslyInstalled = node.getRuntimePermissionDelegations().find((candidate) => candidate.cid === cid);
+  if (previouslyInstalled !== void 0 && previouslyInstalled.delegationHeader.Authorization !== authorization) {
+    throw new Error(
+      "A different authorization is already installed for this runtime delegation CID."
+    );
+  }
+  const primary = signed2.resources[0];
+  const signedSpace = signed2.permissions.find(
+    (permission) => permission.service !== "tinycloud.encryption"
+  )?.space;
+  const installedCandidate = {
+    cid,
+    delegationHeader: { Authorization: authorization },
+    ownerAddress: delegation.ownerAddress,
+    chainId: delegation.chainId,
+    spaceId: signedSpace ?? delegation.spaceId,
+    path: primary.path,
+    actions: [...primary.actions],
+    ...primary.caveats === void 0 ? {} : { caveats: primary.caveats },
+    resources: signed2.resources.map((resource) => ({
+      ...resource,
+      actions: [...resource.actions]
+    })),
+    expiry: new Date(signed2.expiry),
+    delegateDID: signed2.audience,
+    host
+  };
+  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);
+  }
+  const installed = node.getRuntimePermissionDelegations().find((candidate) => candidate.cid === cid);
+  if (!installed) {
+    throw new Error("Runtime delegation activation did not install the validated authority.");
+  }
+  if (installed.delegationHeader.Authorization !== authorization || !didPrincipalsMatch(installed.delegateDID, signed2.audience) || installed.expiry.getTime() !== signed2.expiry.getTime() || !resourcesMatch(
+    canonicalResourcesFromPortableDelegation(installed),
+    signed2.resources
+  ) || normalizedHost(installed.host ?? "") !== host) {
+    throw new Error(
+      "Runtime delegation activation installed authority that differs from the validated authority."
+    );
+  }
+  return {
+    cid,
+    delegation: installed,
+    effectivePermissions: signed2.permissions,
+    expiry: new Date(signed2.expiry),
+    audience: signed2.audience,
+    host: normalizedHost(installed.host ?? host)
+  };
+}
 async function grantAuthRequest(authority, request, options) {
   if (request.kind !== "tinycloud.auth.request") {
     throw new Error(
@@ -22700,10 +23877,11 @@ import {
   SECRET_NAME_RE,
   canonicalizeSecretScope,
   resolveSecretListPrefix as resolveSecretListPrefix2,
-  resolveSecretPath as resolveSecretPath2
+  resolveSecretPath as resolveSecretPath3
 } from "@tinycloud/sdk-core";
 import {
   EncryptionService as EncryptionService2,
+  DecryptTransportResponseError as DecryptTransportResponseError2,
   parseNetworkId as parseNetworkId3,
   buildNetworkId,
   isNetworkId,
@@ -22779,6 +23957,7 @@ export {
   AutoApproveSpaceCreationHandler2 as AutoApproveSpaceCreationHandler,
   CapabilityKeyRegistry2 as CapabilityKeyRegistry,
   CapabilityKeyRegistryErrorCodes,
+  CaveatedDelegationUnsupportedError2 as CaveatedDelegationUnsupportedError,
   DECRYPT_ACTION3 as DECRYPT_ACTION,
   DECRYPT_FACT_TYPE,
   DECRYPT_RESULT_TYPE,
@@ -22789,6 +23968,7 @@ export {
   DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
   DataVaultService2 as DataVaultService,
   DatabaseHandle,
+  DecryptTransportResponseError2 as DecryptTransportResponseError,
   DelegatedAccess,
   DelegationErrorCodes,
   DelegationManager2 as DelegationManager,
@@ -22829,11 +24009,13 @@ export {
   TinyCloudDebugLogger,
   TinyCloudNode,
   UnsupportedFeatureError2 as UnsupportedFeatureError,
+  UnsupportedSessionRestoreError,
   VAULT_PERMISSION_SERVICE,
   VaultHeaders,
   VaultPublicSpaceKVActions,
   VersionCheckError,
   WasmKeyProvider,
+  activateValidatedRuntimeDelegation,
   addressStorageKey,
   buildCanonicalDecryptRequest,
   buildDecryptAttenuation,
@@ -22900,10 +24082,10 @@ export {
   parseSpaceUri,
   pkhDid3 as pkhDid,
   principalDid,
-  principalDidEquals3 as principalDidEquals,
+  principalDidEquals4 as principalDidEquals,
   resolveManifest2 as resolveManifest,
   resolveSecretListPrefix2 as resolveSecretListPrefix,
-  resolveSecretPath2 as resolveSecretPath,
+  resolveSecretPath3 as resolveSecretPath,
   resourceCapabilitiesToSpaceAbilitiesMap2 as resourceCapabilitiesToSpaceAbilitiesMap,
   serializeDelegation,
   tinyCloudDebugLogger,