@tinycloud/node-sdk 3.2.6-beta.6 → 3.3.0-beta.8

package/dist/core.cjs

@@ -106,6 +106,7 @@ __export(core_exports, {
   expandActionShortNames: () => import_sdk_core13.expandActionShortNames,
   expandPermissionEntries: () => import_sdk_core13.expandPermissionEntries,
   expandPermissionEntry: () => import_sdk_core13.expandPermissionEntry,
+  getNodeReplicationLoaders: () => getNodeReplicationLoaders,
   getTinyCloudDebugLogs: () => import_sdk_core12.getTinyCloudDebugLogs,
   installTinyCloudDebugGlobals: () => import_sdk_core12.installTinyCloudDebugGlobals,
   isCapabilitySubset: () => import_sdk_core13.isCapabilitySubset,
@@ -526,6 +527,7 @@ var NodeUserAuthorization = class {
     this.siweConfig = config.siweConfig;
     this.includeAccountRegistryPermissions = config.includeAccountRegistryPermissions ?? true;
     this.replication = config.replication?.enabled === true ? config.replication : void 0;
+    this.establishReplicaStamp = config.establishReplicaStamp;
     this._manifest = config.manifest;
     this._capabilityRequest = config.capabilityRequest;
     this.sessionManager = config.sessionManager ?? this.wasm.createSessionManager();
@@ -1295,6 +1297,27 @@ var NodeUserAuthorization = class {
       signature
     };
   }
+  persistedData(session, expiresAt, createdAt, replicaStamp) {
+    return {
+      address: session.address,
+      chainId: session.chainId,
+      sessionKey: JSON.stringify(session.jwk),
+      siwe: session.siwe,
+      signature: session.signature,
+      tinycloudSession: {
+        delegationHeader: session.delegationHeader,
+        delegationCid: session.delegationCid,
+        spaceId: session.spaceId,
+        spaces: session.spaces,
+        verificationMethod: session.verificationMethod
+      },
+      expiresAt,
+      createdAt,
+      version: "1.0",
+      tinycloudHosts: this.tinycloudHosts,
+      ...replicaStamp ? { replicaStamp } : {}
+    };
+  }
   /**
    * Sign in and create a new session.
    *
@@ -1374,24 +1397,13 @@ var NodeUserAuthorization = class {
       siwe: prepared.siwe,
       signature
     };
-    const persistedData = {
-      address,
-      chainId,
-      sessionKey: JSON.stringify(jwk),
-      siwe: prepared.siwe,
-      signature,
-      tinycloudSession: {
-        delegationHeader: session.delegationHeader,
-        delegationCid: session.delegationCid,
-        spaceId,
-        spaces: spacesMetadata,
-        verificationMethod: this.sessionManager.getDID(keyId)
-      },
-      expiresAt: expirationTime.toISOString(),
-      createdAt: now.toISOString(),
-      version: "1.0",
-      tinycloudHosts: this.tinycloudHosts
-    };
+    const replicaStamp = await this.establishReplicaStamp?.(tinyCloudSession);
+    const persistedData = this.persistedData(
+      tinyCloudSession,
+      expirationTime.toISOString(),
+      now.toISOString(),
+      replicaStamp
+    );
     await this.enqueuePersistence(async () => {
       await this.sessionStorage.save(address, persistedData);
       if (generation !== this.sessionGeneration) {
@@ -1545,28 +1557,12 @@ var NodeUserAuthorization = class {
       siwe: prepared.siwe,
       signature
     };
-    const expirationMatch = prepared.siwe.match(/Expiration Time: (.+)/);
-    const issuedAtMatch = prepared.siwe.match(/Issued At: (.+)/);
+    const expirationMatch = prepared.siwe?.match(/Expiration Time: (.+)/);
+    const issuedAtMatch = prepared.siwe?.match(/Issued At: (.+)/);
     const expiresAt = expirationMatch?.[1] ?? new Date(Date.now() + this.sessionExpirationMs).toISOString();
     const createdAt = issuedAtMatch?.[1] ?? (/* @__PURE__ */ new Date()).toISOString();
-    const persistedData = {
-      address,
-      chainId,
-      sessionKey: JSON.stringify(jwk),
-      siwe: prepared.siwe,
-      signature,
-      tinycloudSession: {
-        delegationHeader: session.delegationHeader,
-        delegationCid: session.delegationCid,
-        spaceId: prepared.spaceId,
-        spaces: spacesMetadata,
-        verificationMethod: this.sessionManager.getDID(keyId)
-      },
-      expiresAt,
-      createdAt,
-      version: "1.0",
-      tinycloudHosts: this.tinycloudHosts
-    };
+    const replicaStamp = await this.establishReplicaStamp?.(tinyCloudSession);
+    const persistedData = this.persistedData(tinyCloudSession, expiresAt, createdAt, replicaStamp);
     await this.sessionStorage.save(address, persistedData);
     this._session = clientSession;
     this._tinyCloudSession = tinyCloudSession;
@@ -1629,15 +1625,36 @@ var NodeUserAuthorization = class {
     const { prepared, keyId, jwk } = await this.prepareSessionForSigning();
     const presentation = this.buildPresentationEnvelope(options?.reason);
     const hostHint = this.primaryTinyCloudHost;
-    const result = await authorizeFn({
+    const originalRequest = {
       protocolVersion: 1,
       siwe: prepared.siwe,
       jwk,
+      verificationMethod: prepared.verificationMethod,
       host: hostHint,
       keyId: options?.openkeyKeyId,
       presentation
-    });
-    return this.signInWithOpenKeyResult(result, prepared, keyId, jwk);
+    };
+    let result;
+    let signed;
+    let signature;
+    for (let attempt = 0; ; ) {
+      try {
+        result ?? (result = await authorizeFn(originalRequest));
+        signed = await this.verifyOpenKeyResult(result, prepared);
+        signature = result.signature;
+        break;
+      } catch (error) {
+        if (!options?.retryResult) throw error;
+        const next = await options.retryResult(
+          error instanceof Error ? error : new Error(String(error)),
+          originalRequest,
+          ++attempt
+        );
+        if (next === null) throw error;
+        result = next;
+      }
+    }
+    return this.signInWithPreparedSession(signed, signature, keyId, jwk);
   }
   /**
    * Build a `CapabilityPresentationEnvelopeV1` from `this._manifest`. The
@@ -1717,6 +1734,11 @@ var NodeUserAuthorization = class {
    *    (resource, action) pair in the returned SIWE.
    */
   async signInWithOpenKeyResult(result, prepared, keyId, jwk) {
+    const signed = await this.verifyOpenKeyResult(result, prepared);
+    return this.signInWithPreparedSession(signed, result.signature, keyId, jwk);
+  }
+  /** Validate a candidate without activating a network session, so paste retries reuse one preparation. */
+  async verifyOpenKeyResult(result, prepared) {
     if (result.protocolVersion !== 1) {
       throw new Error(`Unsupported OpenKey protocol version ${result.protocolVersion}`);
     }
@@ -1961,17 +1983,12 @@ var NodeUserAuthorization = class {
       }
     }
     void nonRequiredGrantedPairs;
-    return this.signInWithPreparedSession(
-      {
-        siwe: result.signedMessage,
-        jwk: prepared.jwk,
-        spaceId: prepared.spaceId,
-        verificationMethod: prepared.verificationMethod
-      },
-      result.signature,
-      keyId,
-      jwk
-    );
+    return {
+      siwe: result.signedMessage,
+      jwk: prepared.jwk,
+      spaceId: prepared.spaceId,
+      verificationMethod: prepared.verificationMethod
+    };
   }
   /**
    * Clear persisted session data.
@@ -2530,41 +2547,6 @@ function deserializeDelegation(data) {
 
 // src/TinyCloudNode.ts
 var import_siwe2 = require("siwe");
-
-// src/replication/config.ts
-var import_prefix2 = require("@tinycloud/sdk-services/kv/replication/prefix");
-function assertValidReplicationConfig(replication) {
-  if (replication === void 0 || replication.enabled !== true) return;
-  if (replication.storage === void 0 || replication.storage === null) {
-    throw new TypeError("replication.enabled requires replication.storage");
-  }
-  if (!Array.isArray(replication.prefixes) || replication.prefixes.length === 0) {
-    throw new TypeError("replication.prefixes must be a non-empty array");
-  }
-  for (const prefix of replication.prefixes) {
-    try {
-      (0, import_prefix2.assertFolderPrefix)(prefix);
-    } catch (error) {
-      throw new TypeError(error instanceof Error ? error.message : String(error));
-    }
-  }
-  for (const [index, prefix] of replication.prefixes.entries()) {
-    for (const other of replication.prefixes.slice(index + 1)) {
-      if ((0, import_prefix2.kvPrefixCovers)(prefix, other) || (0, import_prefix2.kvPrefixCovers)(other, prefix)) {
-        throw new TypeError(
-          `replication.prefixes must not overlap: ${JSON.stringify(prefix)} and ${JSON.stringify(other)}`
-        );
-      }
-    }
-    if ((prefix === "/" || prefix.split("/", 1)[0] === "vault") && replication.allowSecrets !== true) {
-      throw new TypeError(
-        `replication prefix ${JSON.stringify(prefix)} overlaps the vault namespace; pass allowSecrets to opt in`
-      );
-    }
-  }
-}
-
-// src/TinyCloudNode.ts
 var import_sdk_core10 = require("@tinycloud/sdk-core");
 var import_sdk_services2 = require("@tinycloud/sdk-services");
 
@@ -3365,6 +3347,7 @@ function ownerPermissionsToAbilities(permissions) {
   }
   return { abilities, rawAbilities };
 }
+var TERMINAL_DELEGATION_REQUIRES_SESSION_KEY = "disableSubDelegation requires a session-key delegation";
 function base64UrlEncode(bytes) {
   const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
   let output = "";
@@ -3476,6 +3459,20 @@ function accountIndexWarningDiagnostic(error) {
   }
   return diagnostic;
 }
+function replicaRestoreRefusal(error) {
+  if (error !== null && typeof error === "object" && "code" in error && error.code === "REPLICA_GATED" && "gate" in error) {
+    switch (error.gate) {
+      case "not_established":
+      case "stamp_stale":
+      case "principal_mismatch":
+      case "purge_pending":
+      case "logout_pending":
+      case "gate_unavailable":
+        return error.gate;
+    }
+  }
+  return "gate_unavailable";
+}
 var _TinyCloudNode = class _TinyCloudNode {
   /**
    * Create a new TinyCloudNode instance.
@@ -3505,6 +3502,37 @@ var _TinyCloudNode = class _TinyCloudNode {
     this.auth = null;
     this.tc = null;
     this._chainId = 1;
+    /** Mints the replica session stamp on each fresh sign-in (TC-858 §4.1). Undefined when replication is off. */
+    this.establishReplicaStamp = async (session) => {
+      const replication = this.config.replication;
+      if (!replication?.enabled) return void 0;
+      const epoch = this.sessionEpoch;
+      const attempt = this.latestSessionAttempt;
+      try {
+        const { verifiedOwnerConsentAnchor, establishReplicaSessionStamp } = await getNodeReplicationLoaders().authority();
+        if (epoch !== this.sessionEpoch || attempt !== this.latestSessionAttempt) return void 0;
+        const anchor = verifiedOwnerConsentAnchor(session, this.wasmBindings, exactVerifiedRecap);
+        if (anchor === null) {
+          throw Object.assign(new Error("Replica sign-in requires a verified finite owner SIWE and exact-space KV get+sync."), {
+            code: "REPLICA_GATED",
+            gate: "not_established"
+          });
+        }
+        const stamp = await establishReplicaSessionStamp(
+          replication.storage,
+          (0, import_sdk_core10.pkhDid)(session.address, session.chainId),
+          anchor
+        );
+        if (epoch !== this.sessionEpoch || attempt !== this.latestSessionAttempt) return void 0;
+        this.replicaSessionStamp = stamp;
+        return stamp;
+      } catch (error) {
+        if (epoch === this.sessionEpoch && attempt === this.latestSessionAttempt) {
+          this.replicaRestoreGate = replicaRestoreRefusal(error);
+        }
+        return void 0;
+      }
+    };
     this._baseVaults = /* @__PURE__ */ new Map();
     this._baseSecrets = /* @__PURE__ */ new Map();
     this._secrets = /* @__PURE__ */ new Map();
@@ -3629,7 +3657,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       });
       return this.wasmBindings.invokeAny(invocationSession, caveatPreservingEntries, facts);
     };
-    assertValidReplicationConfig(config.replication);
+    if (config.replication?.enabled) getNodeReplicationLoaders().validateConfig(config.replication);
     this.explicitHost = config.host;
     this.config = {
       ...config,
@@ -3644,6 +3672,16 @@ var _TinyCloudNode = class _TinyCloudNode {
       this.replicationRuntime = runtime;
       this.replicationControl = {
         status: async () => {
+          const gate = this.replicaRestoreGate;
+          if (gate) return this.config.replication.prefixes.map((prefix) => ({
+            prefix,
+            state: "gated",
+            gate,
+            errorCode: "REPLICA_GATED",
+            pending: { inFlight: 0, committed: 0, ambiguous: 0 },
+            pinned: [],
+            lagMs: null
+          }));
           const status = await runtime.then((ready) => ready.control.status());
           const scopeError = this.replicationScopeError;
           if (!scopeError) return status;
@@ -3660,7 +3698,15 @@ var _TinyCloudNode = class _TinyCloudNode {
             lagMs: null
           }));
         },
-        sync: async (input) => (await runtime).control.sync(input),
+        sync: async (input) => {
+          if (this.replicaRestoreGate) {
+            throw Object.assign(new Error("Replica restore is gated."), {
+              code: "REPLICA_GATED",
+              gate: this.replicaRestoreGate
+            });
+          }
+          return (await runtime).control.sync(input);
+        },
         purge: (input) => {
           const instance = this.replicationRuntimeInstance;
           return instance ? instance.control.purge(input) : runtime.then((ready) => ready.control.purge(input));
@@ -3876,6 +3922,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       signer: this.signer,
       signStrategy: config.signStrategy ?? { type: "auto-sign" },
       wasmBindings: this.wasmBindings,
+      ...config.replication?.enabled === true ? { establishReplicaStamp: this.establishReplicaStamp } : {},
       sessionManager: this.sessionManager,
       sessionStorage: config.sessionStorage ?? new MemorySessionStorage(),
       domain: this.siweDomain,
@@ -4073,11 +4120,10 @@ var _TinyCloudNode = class _TinyCloudNode {
     return this.signer === null;
   }
   /**
-   * Get the space ID for this user.
-   * Available after signIn().
+   * Primary space of the signed-in or restored network session, including compact sessions.
    */
   get spaceId() {
-    return this.auth?.tinyCloudSession?.spaceId;
+    return this.auth?.tinyCloudSession?.spaceId ?? this._activeServiceSession?.spaceId;
   }
   /**
    * Get the account space ID for this wallet identity.
@@ -4125,6 +4171,12 @@ var _TinyCloudNode = class _TinyCloudNode {
   get restorableSession() {
     return this.currentTinyCloudSession();
   }
+  /** The active, verified replica stamp. Undefined when the replica is refused or the session has ended. */
+  get replicaStamp() {
+    const stamp = this.replicaSessionStamp;
+    if (!stamp || this.replicaRestoreGate !== void 0 || !this.currentTinyCloudSession()) return void 0;
+    return { incarnation: stamp.incarnation, lifecycleEpoch: stamp.lifecycleEpoch };
+  }
   /**
    * Sign out and end the session on this instance.
    *
@@ -4145,19 +4197,61 @@ var _TinyCloudNode = class _TinyCloudNode {
   }
   async endSession() {
     const leavingAddress = this.address ?? this._restoredTcSession?.address;
+    const leavingChainId = this._chainId;
+    const leavingPrincipal = this.replicaSessionPrincipal ?? (leavingAddress ? (0, import_sdk_core10.pkhDid)(leavingAddress, leavingChainId) : void 0);
     const leavingAuth = this.auth;
+    const leavingContext = this._serviceContext;
+    let denied;
     try {
       this.teardownSession();
     } finally {
+      const denial = leavingPrincipal ? this.denyReplicaGate({ reason: "sign_out", principal: leavingPrincipal }, leavingContext) : Promise.resolve(void 0);
       try {
-        await this.accountRegistryTail;
-        if (this.replicationRuntime) await (await this.replicationRuntime).unbind();
+        denied = await denial;
       } finally {
-        if (leavingAddress) {
-          await (leavingAuth ? leavingAuth.clearPersistedSession(leavingAddress) : this.config.sessionStorage?.clear(leavingAddress));
+        try {
+          await this.accountRegistryTail;
+          await this.quiesceReplicaRuntime();
+        } finally {
+          if (leavingAddress) {
+            await (leavingAuth ? leavingAuth.clearPersistedSession(leavingAddress) : this.config.sessionStorage?.clear(leavingAddress));
+          }
         }
       }
     }
+    if (denied?.status === "unguarded") {
+      throw new Error(`Replica gate was not denied (${denied.code ?? "unknown"}); the replica may still be restorable.`);
+    }
+  }
+  /**
+   * Step 1 of replica sign-out. Never rejects: failures come back as `unguarded` so the session
+   * is still cleared. Returns `undefined` when replication is off.
+   */
+  async denyReplicaGate(input, context = this._serviceContext) {
+    const replication = this.config.replication;
+    if (!replication?.enabled) return void 0;
+    try {
+      const lifecycle = replication.storage.lifecycle;
+      if (lifecycle?.kind !== (replication.storage.kind === "indexeddb" ? "indexeddb" : "file")) {
+        return { status: "unguarded", code: "gate_unavailable" };
+      }
+      const result = await lifecycle.deny(input);
+      if (result.status === "denied" || result.status === "deleted" || result.status === "marker") {
+        try {
+          (await getNodeReplicationLoaders().authority()).reportReplicaDenial(
+            result,
+            input.reason,
+            replication.onEvent,
+            context
+          );
+        } catch {
+        }
+      }
+      return result;
+    } catch (error) {
+      const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : "gate_unavailable";
+      return { status: "unguarded", code };
+    }
   }
   /**
    * Synchronously drop every piece of in-memory session authority and
@@ -4176,15 +4270,9 @@ var _TinyCloudNode = class _TinyCloudNode {
     this._activeServiceSession = void 0;
     oldGraph.retire();
     oldCore?.retireServices();
-    oldAuth?.resetSession(
-      this.sessionManager,
-      this.sessionKeyId,
-      this.explicitHost ? [this.explicitHost] : void 0
-    );
     this.config.host = this.explicitHost ?? DEFAULT_HOST;
     this._chainId = 1;
     this._restoredNodeFeatures = void 0;
-    this._activeServiceSession = void 0;
     this._serviceContext = void 0;
     this._kv = void 0;
     this._sql = void 0;
@@ -4209,6 +4297,9 @@ var _TinyCloudNode = class _TinyCloudNode {
     this._bootstrapStatus = { skipped: false };
     this.replicationDelegateSession = void 0;
     this.replicationScopeError = void 0;
+    this.replicaSessionPrincipal = void 0;
+    this.replicaSessionStamp = void 0;
+    this.replicaRestoreGate = void 0;
     const sessionKey = createDefaultSessionKey(this.wasmBindings);
     this.sessionManager = sessionKey.manager;
     this.sessionKeyId = sessionKey.keyId;
@@ -4218,6 +4309,9 @@ var _TinyCloudNode = class _TinyCloudNode {
       sessionKey.keyId,
       this.explicitHost ? [this.explicitHost] : void 0
     );
+    this.replicaSessionPrincipal = void 0;
+    this.replicaSessionStamp = void 0;
+    this.replicaRestoreGate = void 0;
     this._serviceGraph = this.createServiceGraphLifetime();
     this.auth = oldAuth;
     this.tc = this.auth ? new import_sdk_core10.TinyCloud(this.auth, {
@@ -4247,11 +4341,25 @@ var _TinyCloudNode = class _TinyCloudNode {
         "Cannot signIn() in session-only mode. Provide a privateKey in config to create your own space."
       );
     }
+    await this.signInWith(() => this.tc.signIn(options));
+  }
+  /**
+   * Fresh OpenKey sign-in. The callback receives the SDK's original SIWE and
+   * session JWK before approval; the signed result is verified against those
+   * bytes before the network session or replica stamp is committed.
+   */
+  async signInWithOpenKey(authorizeFn, options) {
+    if (!this.signer || !this.tc || !this.auth) {
+      throw new Error("Cannot signInWithOpenKey() in session-only mode. Provide a signer in config.");
+    }
+    await this.signInWith(() => this.auth.signInWithOpenKey(authorizeFn, options));
+  }
+  async signInWith(performSignIn) {
     const epoch = this.sessionEpoch;
     const attempt = ++this.latestSessionAttempt;
     await this.signOutInFlight;
     try {
-      await this.establishSignIn(epoch, options);
+      await this.establishSignIn(epoch, performSignIn);
     } catch (error) {
       if (epoch !== this.sessionEpoch && attempt === this.latestSessionAttempt) {
         await this.endSession();
@@ -4259,7 +4367,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       throw error;
     }
   }
-  async establishSignIn(epoch, options) {
+  async establishSignIn(epoch, performSignIn) {
     if (!this.signer || !this.tc) {
       throw new Error("Not signed in. Call signIn() first.");
     }
@@ -4269,6 +4377,12 @@ var _TinyCloudNode = class _TinyCloudNode {
     const address = (0, import_sdk_core10.canonicalizeAddress)(await this.signer.getAddress());
     const chainId = await this.signer.getChainId();
     this.assertSessionEpoch(epoch, "Sign-in");
+    const nextPrincipal = (0, import_sdk_core10.pkhDid)(address, chainId);
+    const priorPrincipal = this.replicaSessionPrincipal ?? (this.address ? (0, import_sdk_core10.pkhDid)(this.address, this._chainId) : void 0);
+    if (this.config.replication?.enabled && priorPrincipal && priorPrincipal !== nextPrincipal) {
+      const denial = await this.denyReplicaGate({ reason: "account_switch", principal: priorPrincipal, next: nextPrincipal });
+      this.replicaRestoreGate = denial?.status === "unguarded" ? "gate_unavailable" : "stamp_stale";
+    }
     if (address !== this._address || chainId !== this._chainId) this.storageFull.clear();
     this._address = address;
     this._chainId = chainId;
@@ -4286,7 +4400,20 @@ var _TinyCloudNode = class _TinyCloudNode {
     this.runtimePermissionGrants = [];
     this.confirmedHostedSpaceIds.clear();
     this.hostedOwnedSpaceIds.clear();
-    await this.tc.signIn(options);
+    const signInAttempt = this.latestSessionAttempt;
+    const previousReplicaGate = this.replicaRestoreGate;
+    const previousReplicaStamp = this.replicaSessionStamp;
+    this.replicaRestoreGate = void 0;
+    this.replicaSessionStamp = void 0;
+    try {
+      await performSignIn();
+    } catch (error) {
+      if (epoch === this.sessionEpoch && signInAttempt === this.latestSessionAttempt) {
+        this.replicaRestoreGate = previousReplicaGate;
+        this.replicaSessionStamp = previousReplicaStamp;
+      }
+      throw error;
+    }
     this.assertSessionEpoch(epoch, "Sign-in");
     this.cancelOwnedSpaceHosts();
     this.syncResolvedHostFromAuth();
@@ -4294,8 +4421,9 @@ var _TinyCloudNode = class _TinyCloudNode {
       this.hostedOwnedSpaceIds.add(spaceId);
     }
     this.replicationDelegateSession = void 0;
+    this.replicaSessionPrincipal = (0, import_sdk_core10.pkhDid)(address, chainId);
     this.replicationScopeError = void 0;
-    if (this.replicationRuntime) await (await this.replicationRuntime).unbind();
+    await this.quiesceReplicaRuntime();
     this.assertSessionEpoch(epoch, "Sign-in");
     const oldGraph = this._serviceGraph;
     this._serviceGraph = this.createServiceGraphLifetime();
@@ -4882,6 +5010,9 @@ var _TinyCloudNode = class _TinyCloudNode {
     if (this.ownStorageFull) {
       return;
     }
+    if (!this.currentSessionCoversAccountRegistry()) {
+      return;
+    }
     const controller = new AbortController();
     const deadline = setTimeout(
       () => controller.abort(new DOMException("Account registry deadline exceeded", "TimeoutError")),
@@ -4996,6 +5127,27 @@ var _TinyCloudNode = class _TinyCloudNode {
       (operation) => operation.service === "space" && this.actionContains(operation.action, "tinycloud.space/list")
     );
   }
+  /**
+   * Whether the current primary session's recap covers the account index read
+   * (`tinycloud.sql/read` on the owned account space's `account` database),
+   * the first call of every registry sync. As in
+   * {@link currentSessionCanListSpaces}, a session with no parseable recap
+   * keeps today's behavior.
+   */
+  currentSessionCoversAccountRegistry() {
+    const session = this.currentTinyCloudSession();
+    const operations = session ? this.recapOperationsFromSession(session) : [];
+    if (operations.length === 0) {
+      return true;
+    }
+    const indexRead = {
+      spaceId: this.ownedSpaceId(import_sdk_core10.ACCOUNT_REGISTRY_SPACE),
+      service: "sql",
+      path: "account",
+      action: "tinycloud.sql/read"
+    };
+    return operations.some((granted) => this.operationCovers(granted, indexRead));
+  }
   async withAccountRegistryRetry(task, signal) {
     const delays = [250, 1e3, 3e3];
     const stopped = (detail) => {
@@ -5462,11 +5614,12 @@ var _TinyCloudNode = class _TinyCloudNode {
     );
     const stagedHost = resolvedHost ?? this.config.host;
     let restoredNodeFeatures;
+    let replicaProtocolMismatch = false;
     if (this.config.replication?.enabled) {
       try {
         restoredNodeFeatures = (await (0, import_sdk_core10.checkNodeInfo)(stagedHost, this.wasmBindings.protocolVersion())).features;
       } catch (error) {
-        if (!(error instanceof import_sdk_core10.VersionCheckError)) throw error;
+        replicaProtocolMismatch = error instanceof import_sdk_core10.ProtocolMismatchError;
       }
     }
     const stagedAddress = restoredAddress;
@@ -5474,28 +5627,55 @@ var _TinyCloudNode = class _TinyCloudNode {
     let replicationPrincipal;
     let compactReplicationSession;
     let replicationScopeError;
+    let replicationScopeUnavailable = false;
     if (this.config.replication?.enabled) {
       if (stagedAddress !== void 0) {
         replicationPrincipal = (0, import_sdk_core10.pkhDid)(stagedAddress, stagedChainId);
       } else {
-        const { replicationScopeFromSignedSession } = await getNodeReplicationLoaders().authority();
-        const signedScope = replicationScopeFromSignedSession({
-          delegationHeader: sessionData.delegationHeader,
-          delegationCid: sessionData.delegationCid,
-          verificationMethod: restoredVerificationMethod,
-          persistedSpace: sessionData.spaceId
-        });
-        if (!signedScope) {
-          replicationScopeError = "Persisted space does not match the locally verified delegation scope.";
-        } else {
-          replicationPrincipal = signedScope.principal;
-          compactReplicationSession = {
+        try {
+          const { replicationScopeFromSignedSession } = await getNodeReplicationLoaders().authority();
+          const signedScope = replicationScopeFromSignedSession({
             delegationHeader: sessionData.delegationHeader,
             delegationCid: sessionData.delegationCid,
-            spaceId: signedScope.space,
             verificationMethod: restoredVerificationMethod,
-            jwk: stagedJwk
-          };
+            persistedSpace: sessionData.spaceId
+          });
+          if (!signedScope) {
+            replicationScopeError = "Persisted space does not match the locally verified delegation scope.";
+          } else {
+            replicationPrincipal = signedScope.principal;
+            compactReplicationSession = {
+              delegationHeader: sessionData.delegationHeader,
+              delegationCid: sessionData.delegationCid,
+              spaceId: signedScope.space,
+              verificationMethod: restoredVerificationMethod,
+              jwk: stagedJwk
+            };
+          }
+        } catch {
+          replicationScopeUnavailable = true;
+          replicationScopeError = "Replica scope could not be verified for this network session.";
+        }
+      }
+    }
+    let replicaRestoreGate;
+    let restoredReplicaStamp;
+    const replication = this.config.replication;
+    if (replication?.enabled) {
+      if (replicaProtocolMismatch) {
+        replicaRestoreGate = "gate_unavailable";
+      } else if (replicationPrincipal === void 0) {
+        replicaRestoreGate = replicationScopeUnavailable ? "gate_unavailable" : "principal_mismatch";
+      } else {
+        try {
+          const { restoreReplicaSessionStamp } = await getNodeReplicationLoaders().authority();
+          restoredReplicaStamp = await restoreReplicaSessionStamp(
+            replication.storage,
+            replicationPrincipal,
+            sessionData.replicaStamp ?? void 0
+          );
+        } catch (error) {
+          replicaRestoreGate = replicaRestoreRefusal(error);
         }
       }
     }
@@ -5588,7 +5768,10 @@ var _TinyCloudNode = class _TinyCloudNode {
     }
     this.replicationDelegateSession = compactReplicationSession;
     this.replicationScopeError = replicationScopeError;
-    if (this.replicationRuntime) await (await this.replicationRuntime).unbind();
+    this.replicaRestoreGate = replicaRestoreGate;
+    this.replicaSessionPrincipal = replicationPrincipal;
+    this.replicaSessionStamp = restoredReplicaStamp;
+    await this.quiesceReplicaRuntime();
     if (epoch !== this.sessionEpoch) {
       oldGraph.retire();
       oldCore?.retireServices?.();
@@ -5603,7 +5786,7 @@ var _TinyCloudNode = class _TinyCloudNode {
         detail: replicationScopeError
       });
     }
-    await this.bindReplicationRuntime(stagedGraph.serviceContext, serviceSession, stagedGraph.kv, replicationPrincipal);
+    await this.bindReplicaOrGate(stagedGraph.serviceContext, serviceSession, stagedGraph.kv, replicationPrincipal);
     oldCore?.retireServices?.();
     if (epoch !== this.sessionEpoch) {
       if (attempt === this.latestSessionAttempt) await this.endSession();
@@ -5736,6 +5919,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       session: input.serviceSession,
       invoke: graph.invoke,
       invokeAny: graph.invokeAny,
+      signOwnerRevocation: this.signer ? (cid) => this.signOwnerRevocation(cid) : void 0,
       fetch: graph.fetch
     });
     const keyProvider = new WasmKeyProvider({ sessionManager: input.manager });
@@ -6079,6 +6263,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       signer: this.signer,
       signStrategy: this.config.signStrategy ?? { type: "auto-sign" },
       wasmBindings: this.wasmBindings,
+      ...this.config.replication?.enabled === true ? { establishReplicaStamp: this.establishReplicaStamp } : {},
       sessionManager: this.sessionManager,
       sessionStorage: options?.sessionStorage ?? this.config.sessionStorage ?? new MemorySessionStorage(),
       domain: this.siweDomain,
@@ -6137,6 +6322,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       signer: this.signer,
       signStrategy: this.config.signStrategy ?? { type: "auto-sign" },
       wasmBindings: this.wasmBindings,
+      ...this.config.replication?.enabled === true ? { establishReplicaStamp: this.establishReplicaStamp } : {},
       sessionManager: this.sessionManager,
       sessionStorage: options?.sessionStorage ?? this.config.sessionStorage ?? new MemorySessionStorage(),
       domain: this.siweDomain,
@@ -6217,7 +6403,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       jwk: session.jwk
     };
     this._serviceContext.setSession(serviceSession);
-    await this.bindReplicationRuntime(this._serviceContext, serviceSession, this._kv);
+    await this.bindReplicaOrGate(this._serviceContext, serviceSession, this._kv);
     this.tc.serviceContext.setSession(serviceSession);
     this._vault = this.createVaultService(session.spaceId, this._kv);
     this._vault.initialize(this._serviceContext);
@@ -6611,6 +6797,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       session: serviceSession,
       invoke: graph.invoke,
       invokeAny: graph.invokeAny,
+      signOwnerRevocation: this.signer ? (cid) => this.signOwnerRevocation(cid) : void 0,
       fetch: graph.fetch
     });
     this._spaceService = new import_sdk_core10.SpaceService({
@@ -6746,11 +6933,12 @@ var _TinyCloudNode = class _TinyCloudNode {
    * Both SharingService (single-entry) and
    * {@link TinyCloudNode.delegateTo} (multi-entry) drive this through
    * the same code path so there's exactly one place that touches the
-   * WASM boundary.
+   * WASM boundary. `terminal` adds the node's terminal marker, which the
+   * WASM builder cannot emit.
    *
    * @internal
    */
-  createDelegationWrapper(params) {
+  createDelegationWrapper(params, terminal = false) {
     const wasmSession = {
       delegationHeader: params.session.delegationHeader,
       delegationCid: params.session.delegationCid,
@@ -6770,8 +6958,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       params.notBeforeSecs
     );
     return {
-      delegation: result.delegation,
-      cid: result.cid,
+      ...terminal ? (0, import_sdk_core10.markDelegationTerminal)(result.delegation, params.session.jwk) : { delegation: result.delegation, cid: result.cid },
       // Rust serde `rename_all = "camelCase"` emits `delegateDid`
       // (lowercase d); the TypeScript interface uses `delegateDID`
       // (historical, matches Delegation.delegateDID). Normalize here.
@@ -7903,7 +8090,8 @@ var _TinyCloudNode = class _TinyCloudNode {
     return this.delegationManager.create(params);
   }
   /**
-   * Revoke a delegation using the v2 DelegationManager.
+   * Revoke a delegation with the owner wallet when available. Session-only
+   * clients continue to use their delegated revocation authority.
    *
    * @param cid - The CID of the delegation to revoke
    * @returns Result indicating success or failure
@@ -8019,6 +8207,9 @@ var _TinyCloudNode = class _TinyCloudNode {
       effectiveExpiration = sessionExpiry;
     }
     if (options?.forceWalletSign) {
+      if (options.disableSubDelegation) {
+        throw new Error(TERMINAL_DELEGATION_REQUIRES_SESSION_KEY);
+      }
       if (expandedEntries.length > 1) {
         throw new Error(
           "delegateTo with forceWalletSign=true supports at most one PermissionEntry. Multi-entry requests must go through the session-key UCAN path (drop forceWalletSign) or the legacy createDelegation method."
@@ -8054,7 +8245,8 @@ var _TinyCloudNode = class _TinyCloudNode {
         plan.effectiveExpiration,
         plan.grant,
         plan.operations,
-        onPrepared
+        onPrepared,
+        options?.disableSubDelegation === true
       );
       return { delegation: delegation2, prompted: false };
     }
@@ -8063,7 +8255,8 @@ var _TinyCloudNode = class _TinyCloudNode {
       expandedEntries,
       effectiveExpiration,
       session,
-      onPrepared
+      onPrepared,
+      options?.disableSubDelegation === true
     );
     return { delegation, prompted: false };
   }
@@ -8178,34 +8371,67 @@ var _TinyCloudNode = class _TinyCloudNode {
     return auth.replicationSignInEntries();
   }
   async replicationAuthority() {
-    const { createReplicationAuthority } = await getNodeReplicationLoaders().authority();
+    const { createReplicationAuthority, mintNodeReplicationGrant, verifiedOwnerConsentAnchor } = await getNodeReplicationLoaders().authority();
     return createReplicationAuthority({
       replicationSession: () => this.currentTinyCloudSession() ?? this.replicationDelegateSession,
+      verifiedConsentAnchor: (session) => {
+        const current = this.currentTinyCloudSession();
+        return session === current && current !== void 0 ? verifiedOwnerConsentAnchor(current, this.wasmBindings, exactVerifiedRecap) : null;
+      },
       siweExpiration: (siwe) => extractSiweExpiration(siwe),
       planDelegation: (entries, options) => this.planDelegation(entries, options),
-      mintDelegation: async (deviceDid, entries) => {
-        const result = await this.delegateTo((0, import_sdk_core10.principalDid)(deviceDid), entries);
-        return {
-          ucan: result.delegation.delegationHeader.Authorization,
-          expiresAt: result.delegation.expiry.getTime()
-        };
-      }
+      mintDelegation: (deviceDid, entries, options) => mintNodeReplicationGrant(
+        deviceDid,
+        entries,
+        options,
+        options?.renewalOnly ? this.currentTinyCloudSession() : void 0,
+        this
+      )
     });
   }
-  async bindReplicationRuntime(context, session, kv, principal) {
+  async quiesceReplicaRuntime() {
     if (!this.replicationRuntime) return;
-    const identityPrincipal = principal ?? (this._address === void 0 ? void 0 : (0, import_sdk_core10.pkhDid)(this._address, this._chainId));
-    if (identityPrincipal === void 0) return;
-    const runtime = await this.replicationRuntime;
-    const authority = await this.replicationAuthority();
-    await runtime.bind({
-      context,
-      session,
-      principal: identityPrincipal,
-      authority,
-      nodeFeatures: this.replicationNodeFeatures,
-      primaryKV: [{ space: session.spaceId, kv }]
-    });
+    try {
+      await (await this.replicationRuntime).unbind();
+    } catch {
+      this.replicaRestoreGate = "gate_unavailable";
+    }
+  }
+  async bindReplicaOrGate(context, session, kv, principal) {
+    if (!this.replicationRuntime) return;
+    const gate = this.replicaRestoreGate;
+    const epoch = this.sessionEpoch;
+    const attempt = this.latestSessionAttempt;
+    try {
+      const runtime = await this.replicationRuntime;
+      if (epoch !== this.sessionEpoch || attempt !== this.latestSessionAttempt || this._kv !== kv || this._serviceContext !== context || gate !== this.replicaRestoreGate) return;
+      if (gate) {
+        await runtime.bindGatedNetworkOnly({
+          context,
+          session,
+          gate,
+          primaryKV: [{ space: session.spaceId, kv }]
+        }, getNodeReplicationLoaders().gatedNetwork);
+        return;
+      }
+      const identityPrincipal = principal ?? (this._address === void 0 ? void 0 : (0, import_sdk_core10.pkhDid)(this._address, this._chainId));
+      if (identityPrincipal === void 0) return;
+      const authority = await this.replicationAuthority();
+      if (epoch !== this.sessionEpoch || attempt !== this.latestSessionAttempt || this._kv !== kv || this._serviceContext !== context) return;
+      await runtime.bind({
+        context,
+        session,
+        principal: identityPrincipal,
+        stamp: this.replicaSessionStamp,
+        authority,
+        nodeFeatures: this.replicationNodeFeatures,
+        primaryKV: [{ space: session.spaceId, kv }]
+      });
+    } catch {
+      if (epoch !== this.sessionEpoch || attempt !== this.latestSessionAttempt || this._kv !== kv || this._serviceContext !== context) return;
+      this.replicaRestoreGate = "gate_unavailable";
+      await this.quiesceReplicaRuntime();
+    }
   }
   /** Stable control facade for this node's optional replication runtime. */
   get replication() {
@@ -8261,7 +8487,7 @@ var _TinyCloudNode = class _TinyCloudNode {
    *
    * @internal
    */
-  async createDelegationViaWasmPath(did, entries, expirationTime, session, onPrepared) {
+  async createDelegationViaWasmPath(did, entries, expirationTime, session, onPrepared, disableSubDelegation = false) {
     if (entries.length === 0) {
       throw new Error(
         "createDelegationViaWasmPath requires a non-empty entries array"
@@ -8321,7 +8547,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       spaceId,
       abilities,
       expirationSecs
-    });
+    }, disableSubDelegation);
     const primary = result.resources[0];
     const delegationHeader = { Authorization: result.delegation };
     const delegation = {
@@ -8331,7 +8557,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       path: primary.path,
       actions: primary.actions,
       resources: result.resources,
-      disableSubDelegation: false,
+      disableSubDelegation,
       expiry: result.expiry,
       delegateDID: did,
       ownerAddress: session.address,
@@ -8353,7 +8579,7 @@ var _TinyCloudNode = class _TinyCloudNode {
     }
     return delegation;
   }
-  async createDelegationViaRuntimeGrant(did, entries, expirationTime, grant, requestedOperations, onPrepared) {
+  async createDelegationViaRuntimeGrant(did, entries, expirationTime, grant, requestedOperations, onPrepared, disableSubDelegation = false) {
     this.assertRuntimeGrantCaveatsPreservable(entries, requestedOperations, grant);
     this.assertDelegationCaveatsPreservable(entries);
     const result = this.createDelegationWrapper({
@@ -8362,7 +8588,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       spaceId: grant.session.spaceId,
       abilities: this.permissionsToAbilities(entries),
       expirationSecs: Math.floor(expirationTime.getTime() / 1e3)
-    });
+    }, disableSubDelegation);
     const primary = result.resources[0];
     const delegationHeader = { Authorization: result.delegation };
     const targetHost = grant.delegation.host ?? this.config.host;
@@ -8373,7 +8599,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       path: primary.path,
       actions: primary.actions,
       resources: result.resources,
-      disableSubDelegation: false,
+      disableSubDelegation,
       expiry: result.expiry,
       delegateDID: did,
       ownerAddress: grant.delegation.ownerAddress,
@@ -8957,11 +9183,10 @@ var _TinyCloudNode = class _TinyCloudNode {
       params.spaceIdOverride
     );
     try {
-      const result = await this.delegateTo(
-        resolvedDelegateDID,
-        entries,
-        params.expiryMs !== void 0 ? { expiry: params.expiryMs } : void 0
-      );
+      const result = await this.delegateTo(resolvedDelegateDID, entries, {
+        ...params.expiryMs !== void 0 ? { expiry: params.expiryMs } : {},
+        disableSubDelegation: params.disableSubDelegation
+      });
       return result.delegation;
     } catch (err2) {
       if (err2 instanceof import_sdk_core10.PermissionNotInManifestError) {
@@ -8982,6 +9207,9 @@ var _TinyCloudNode = class _TinyCloudNode {
    * @internal
    */
   async createDelegationWalletPath(params) {
+    if (params.disableSubDelegation) {
+      throw new Error(TERMINAL_DELEGATION_REQUIRES_SESSION_KEY);
+    }
     if (!this.signer) {
       throw new Error("Cannot createDelegation() in session-only mode. Requires wallet mode.");
     }
@@ -9037,7 +9265,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       spaceId: params.spaceIdOverride ?? session.spaceId,
       path: params.path,
       actions: params.actions,
-      disableSubDelegation: params.disableSubDelegation ?? false,
+      disableSubDelegation: false,
       expiry: expirationTime,
       delegateDID: params.delegateDID,
       ownerAddress: session.address,
@@ -9080,7 +9308,7 @@ var _TinyCloudNode = class _TinyCloudNode {
           spaceId: publicSpaceId,
           path: "",
           actions: [import_sdk_core10.KV.GET, import_sdk_core10.KV.PUT, import_sdk_core10.KV.METADATA],
-          disableSubDelegation: params.disableSubDelegation ?? false,
+          disableSubDelegation: false,
           expiry: expirationTime,
           delegateDID: params.delegateDID,
           ownerAddress: session.address,
@@ -9247,6 +9475,9 @@ var _TinyCloudNode = class _TinyCloudNode {
     if (parentDelegation.disableSubDelegation) {
       throw new Error("Parent delegation does not allow sub-delegation");
     }
+    if (params.disableSubDelegation) {
+      throw new Error(TERMINAL_DELEGATION_REQUIRES_SESSION_KEY);
+    }
     const parentResources = parentDelegation.resources ?? [{
       service: parentDelegation.actions[0]?.split("/", 1)[0]?.replace(/^tinycloud\./, "") ?? "kv",
       space: parentDelegation.spaceId,
@@ -9319,7 +9550,7 @@ var _TinyCloudNode = class _TinyCloudNode {
       spaceId: parentDelegation.spaceId,
       path: requestedResources[0].path,
       actions: requestedResources[0].actions,
-      disableSubDelegation: params.disableSubDelegation ?? false,
+      disableSubDelegation: false,
       expiry: actualExpiry,
       delegateDID: params.delegateDID,
       ownerAddress: parentDelegation.ownerAddress,
@@ -9436,6 +9667,7 @@ var import_sdk_core22 = require("@tinycloud/sdk-core");
   expandActionShortNames,
   expandPermissionEntries,
   expandPermissionEntry,
+  getNodeReplicationLoaders,
   getTinyCloudDebugLogs,
   installTinyCloudDebugGlobals,
   isCapabilitySubset,