@securecoms/agent-bridge 0.25.4 → 0.26.0

package/README.md

@@ -589,6 +589,21 @@ the agent **plaintext** — message text and, for attachments, a **local file pa
 This is why Python agents (which have no native MLS library) fully support
 attachments: the cryptography lives in the daemon, not the agent.
 
+**Files links (`vault_ref`).** A message can instead point at an item already in
+the enclave's Files (FileSafe). The daemon does **not** fetch it on receipt: the
+delivered message carries the caption as `text` (`"[Files link]"` when there is
+none) and a reference,
+`vault_refs: [{ enclave_id, node_id, content_hash, dek_commit, name_hint?, mime_hint?, size_hint? }]`.
+The `*_hint` fields are the sender's unverified claims; treat them as data, never
+as a path or an instruction. A link whose enclave is not the channel's, or whose
+fields are malformed, is dropped (counted as `refused_vault_refs` on `/healthz`).
+To open one, call `POST /v1/vault-read` with
+`{ enclave_id, node_id, expected_content_hash: content_hash, expected_dek_commit: dek_commit }`.
+The two pins go together: sending only one is a 400.
+If the item changed in Files after it was shared, the daemon refuses with
+`422 {"error":"vault_ref_changed","detail":{"pin":"..."}}` and returns no bytes.
+`/healthz` advertises support as `capabilities.vault_ref: 1`.
+
 ---
 
 ## Voice fast path

package/dist/attachments.d.ts

@@ -10,6 +10,61 @@ export type ArtifactShareBody = {
     digest: string;
     text?: string;
 };
+/**
+ * A Files link: a reference to a FileSafe item, opened only through the
+ * recipient's own vault access. Carries NO key material and NO download
+ * handle. Wire keys are camelCase, the same as `artifact_share`. Schema and
+ * rules: docs/architecture/2026-10-01-files-link-message-review.md section 3.
+ */
+export type VaultRefBody = {
+    v: 1;
+    type: "vault_ref";
+    /** Canonical lowercase UUID. MUST equal the channel's enclave (rule R2). */
+    enclaveId: string;
+    /** Canonical lowercase UUID. */
+    nodeId: string;
+    /** Version pin 1: "blake2b:" + 64 hex over the stored CIPHERTEXT. */
+    contentHash: string;
+    /** Version pin 2: "blake2b:" + 64 hex commitment to the DEK material (connect-clients-core computeDekCommit). */
+    dekCommit: string;
+    /** Untrusted sender hints. Never used for authorization or save paths. */
+    name?: string;
+    mime?: string;
+    size?: number;
+    /** Optional caption, same meaning as artifact_share.text. */
+    text?: string;
+};
+/**
+ * What the runtime receives in `BridgeMessage.vault_refs`. The `_hint` fields
+ * are UNTRUSTED claims by the sender, data only: the vault's own sealed name
+ * and size are the truth, read through `/v1/vault-read` / `/v1/vault-list`.
+ * Open it with `/v1/vault-read` passing `expected_content_hash` and
+ * `expected_dek_commit` from this entry; the daemon never fetches it on
+ * receipt.
+ */
+export type VaultRefEntry = {
+    enclave_id: string;
+    node_id: string;
+    content_hash: string;
+    dek_commit: string;
+    name_hint?: string;
+    mime_hint?: string;
+    size_hint?: number;
+};
+/** Plaintext ceiling for the size hint. PARITY: connect-web useVault.ts
+ *  VAULT_MAX_FILE_BYTES (100 MiB object limit minus the 16-byte AEAD tag). */
+export declare const VAULT_REF_MAX_SIZE_HINT: number;
+/** The vault pin format. Exported for the /v1/vault-read expected_* params. */
+export declare const VAULT_PIN: RegExp;
+/**
+ * Rule R1: strict parse. Any required field failing returns null (the caller
+ * refuses the link). Each hint is dropped on its own when it fails its type or
+ * length check; nothing is coerced. Unknown keys are never copied, so smuggled
+ * key material or download handles cannot reach the runtime.
+ */
+export declare function parseVaultRefBody(raw: unknown): VaultRefBody | null;
+/** The runtime-facing reference for a parsed body (hints renamed `_hint`). */
+export declare function toVaultRefEntry(body: VaultRefBody): VaultRefEntry;
 export type AttachmentMeta = {
     filename: string;
     mime: string;

package/dist/bin.js

@@ -8930,6 +8930,31 @@ function unpackDekMaterial(buf) {
   return { fileKey: buf.subarray(0, 32), fileNonce: buf.subarray(32) };
 }
 
+// ../connect-clients-core/dist/filesafe/dek-commit.js
+import { blake2b as blake2b2 } from "@noble/hashes/blake2b";
+var DEK_COMMIT_LABEL = "securecoms/vault_ref/dek/v1";
+function computeDekCommit(enclaveId, nodeId, fileKey, fileNonce) {
+  const enc3 = new TextEncoder();
+  const sep = new Uint8Array([0]);
+  const parts = [
+    enc3.encode(DEK_COMMIT_LABEL),
+    sep,
+    enc3.encode(enclaveId),
+    sep,
+    enc3.encode(nodeId),
+    sep,
+    packDekMaterial(fileKey, fileNonce)
+  ];
+  const preimage = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) {
+    preimage.set(p, at);
+    at += p.length;
+  }
+  const digest = blake2b2(preimage, { dkLen: 32 });
+  return `blake2b:${Array.from(digest, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
 // ../../node_modules/@agentvault/crypto/dist/index.js
 init_sha2();
 init_hmac();
@@ -25828,7 +25853,7 @@ var FakeConnectBackend = class _FakeConnectBackend {
       message_id: messageId,
       channel_id: p.channelId,
       enclave_id: p.enclaveId,
-      message_type: "text",
+      message_type: p.messageType ?? "text",
       sender_id: p.senderId,
       sender_type: "agent",
       identity_proof: { signature: "", algo: "ed25519", attested: false, canonicalization: "RFC8785" },
@@ -27726,6 +27751,47 @@ var DecryptErrorLogLimiter = class {
 
 // src/attachments.ts
 import { basename } from "node:path";
+var VAULT_REF_MAX_SIZE_HINT = 100 * 1024 * 1024 - 16;
+var VAULT_REF_MAX_NAME = 255;
+var VAULT_REF_MAX_MIME = 127;
+var CANONICAL_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+var VAULT_PIN = /^blake2b:[0-9a-f]{64}$/;
+var HINT_FORBIDDEN = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
+var MIME_TYPE = /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$/;
+function parseVaultRefBody(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const r = raw;
+  if (r.type !== "vault_ref" || r.v !== 1) return null;
+  const { enclaveId, nodeId, contentHash, dekCommit } = r;
+  if (typeof enclaveId !== "string" || !CANONICAL_UUID.test(enclaveId)) return null;
+  if (typeof nodeId !== "string" || !CANONICAL_UUID.test(nodeId)) return null;
+  if (typeof contentHash !== "string" || !VAULT_PIN.test(contentHash)) return null;
+  if (typeof dekCommit !== "string" || !VAULT_PIN.test(dekCommit)) return null;
+  const body = { v: 1, type: "vault_ref", enclaveId, nodeId, contentHash, dekCommit };
+  if (typeof r.name === "string" && r.name.length <= VAULT_REF_MAX_NAME && !HINT_FORBIDDEN.test(r.name)) {
+    body.name = r.name;
+  }
+  if (typeof r.mime === "string" && r.mime.length <= VAULT_REF_MAX_MIME && !HINT_FORBIDDEN.test(r.mime) && MIME_TYPE.test(r.mime)) {
+    body.mime = r.mime;
+  }
+  if (typeof r.size === "number" && Number.isInteger(r.size) && r.size >= 0 && r.size <= VAULT_REF_MAX_SIZE_HINT) {
+    body.size = r.size;
+  }
+  if (typeof r.text === "string") body.text = r.text;
+  return body;
+}
+function toVaultRefEntry(body) {
+  const entry = {
+    enclave_id: body.enclaveId,
+    node_id: body.nodeId,
+    content_hash: body.contentHash,
+    dek_commit: body.dekCommit
+  };
+  if (body.name !== void 0) entry.name_hint = body.name;
+  if (body.mime !== void 0) entry.mime_hint = body.mime;
+  if (body.size !== void 0) entry.size_hint = body.size;
+  return entry;
+}
 function sanitizeFilename(name, fallback) {
   const base = basename(name ?? "");
   const cleaned = base.replace(/[/\\]/g, "").replace(/^\.+$/, "");
@@ -28408,6 +28474,15 @@ var VaultIntegrityError = class extends Error {
     if (cause !== void 0) this.cause = cause;
   }
 };
+var VaultPinMismatchError = class extends VaultIntegrityError {
+  pin;
+  constructor(pin) {
+    super(`vault: pinned ${pin} does not match; the file changed after it was shared, not opened`);
+    this.name = "VaultPinMismatchError";
+    this.pin = pin;
+  }
+};
+var VAULT_PINS_TOGETHER = "expected_content_hash and expected_dek_commit go together";
 async function vaultWriteImpl(args2) {
   const gen = args2.deps.currentGeneration;
   const kek = args2.deps.exporterKekForGeneration(gen);
@@ -28431,10 +28506,20 @@ async function vaultWriteImpl(args2) {
   return { node_id: created.node_id };
 }
 async function vaultReadImpl(args2) {
+  const pinnedHash = args2.expected?.contentHash;
+  const pinnedCommit = args2.expected?.dekCommit;
+  if (args2.expected !== void 0 && (typeof pinnedHash !== "string" || typeof pinnedCommit !== "string")) {
+    throw new VaultIntegrityError(`vault: ${VAULT_PINS_TOGETHER}`);
+  }
   const meta = await args2.deps.getNodeForDownload(args2.nodeId);
+  if (pinnedHash !== void 0 && meta.content_hash !== pinnedHash) {
+    throw new VaultPinMismatchError("content_hash_server");
+  }
   const ct = await args2.deps.getBlob(meta.download_url);
-  const expected = (meta.content_hash ?? "").replace(/^blake2b:/, "");
-  if (await computeFileDigest(ct) !== expected) {
+  const digestHex = await computeFileDigest(ct);
+  if (pinnedHash !== void 0) {
+    if (`blake2b:${digestHex}` !== pinnedHash) throw new VaultPinMismatchError("ciphertext_digest");
+  } else if (digestHex !== (meta.content_hash ?? "").replace(/^blake2b:/, "")) {
     throw new VaultIntegrityError("vault: ciphertext failed integrity/digest check");
   }
   const wrap = [...meta.wraps].sort((a, b) => b.kek_generation - a.kek_generation)[0];
@@ -28448,6 +28533,9 @@ async function vaultReadImpl(args2) {
   } catch (e) {
     throw new VaultIntegrityError("vault: DEK unwrap failed (bad KEK, AAD mismatch, or tampered wrap)", e);
   }
+  if (pinnedCommit !== void 0 && computeDekCommit(args2.enclaveId, args2.nodeId, fileKey, fileNonce) !== pinnedCommit) {
+    throw new VaultPinMismatchError("dek_commit");
+  }
   try {
     return await decryptFile(ct, fileKey, fileNonce);
   } catch (e) {
@@ -28945,6 +29033,7 @@ function logPendingCommitResolved(outcome) {
       writeServiceLog("info", "mls.pending_commit.resolved.unknown");
   }
 }
+var VAULT_REF_BARE_TEXT = "[Files link]";
 var VOICE_MODE_GUIDANCE = "Reply immediately and conversationally, one short sentence per message; never bundle multiple points into one message.";
 var FAST_PATH_SPOKEN_GUIDANCE = "A one-sentence spoken acknowledgement has already been sent for this turn. Reply only with information it did not contain, in one or two short sentences; if there is nothing to add, send nothing.";
 var ROOM_VOICE_GUIDANCE_MENTION_ONLY = "You are in a group voice room. Reply ONLY when a message @mentions your display name. Keep replies to one short sentence. When you should not reply, send nothing.";
@@ -29439,6 +29528,8 @@ var BridgeAgent = class _BridgeAgent {
    * counter is incremented. Surfaced on health()/metrics().
    */
   failedAttachments = 0;
+  /** Files link: vault_ref bodies refused by R1 (strict parse) or R2 (enclave binding). */
+  refusedVaultRefs = 0;
   /**
    * Task 4 (self-hosted fast voice): test/deploy seam for the fast-path LLM
    * client. Undefined whenever `cfg.voice?.fastPath.enabled` is not true —
@@ -31500,11 +31591,12 @@ var BridgeAgent = class _BridgeAgent {
    *  useVault.downloadFile returns `{name, bytes}` in-memory — here the
    *  caller already supplies nodeId so we return bytes, not a re-resolved
    *  name the bridge has no cached listing to look up). */
-  async vaultRead(enclaveId, vaultChannelId, nodeId) {
+  async vaultRead(enclaveId, vaultChannelId, nodeId, expected) {
     const session = await this.getVaultSession(enclaveId, await this.resolveVaultChannelId(enclaveId, vaultChannelId));
     const bytes = await vaultReadImpl({
       enclaveId,
       nodeId,
+      expected,
       deps: {
         exporterKekForGeneration: session.kekForGeneration,
         getNodeForDownload: (id) => this.vaultGetNodeForDownload(enclaveId, id),
@@ -32494,7 +32586,12 @@ var BridgeAgent = class _BridgeAgent {
         const encId = m.envelope.enclave_id;
         if (encId && !this.channelEnclaveRecorded.has(m.channelId)) {
           this.channelEnclaveRecorded.add(m.channelId);
-          this.store.recordChannelEnclave(m.channelId, encId);
+          const priorEnclave = this.store.getChannelMeta(m.channelId)?.enclaveId;
+          if (priorEnclave === void 0) {
+            this.store.recordChannelEnclave(m.channelId, encId);
+          } else if (priorEnclave !== encId) {
+            writeServiceLog("warn", "channel_enclave.envelope_mismatch");
+          }
         }
         const parsed = JSON.parse(
           new TextDecoder().decode(m.plaintext)
@@ -32508,6 +32605,75 @@ var BridgeAgent = class _BridgeAgent {
             acked.push(m.queueId);
             continue;
           }
+          if (parsed.type === "vault_ref") {
+            const senderType = m.envelope.sender_type;
+            const senderIsAgent = senderType === "agent" ? true : senderType === "human" ? false : void 0;
+            const chanMeta = this.freshMeta(m.channelId);
+            const loopSenderIsAgent = this.loopSenderIsAgent(
+              m.channelId,
+              m.envelope.sender_id,
+              senderIsAgent,
+              false
+            );
+            const agentHops = this.agentHops.noteInbound(m.channelId, loopSenderIsAgent, m.messageId);
+            const caption = typeof parsed.text === "string" ? parsed.text : "";
+            let answerable = true;
+            if (chanMeta && chanMeta.is_dm === false) {
+              answerable = shouldProcessRoomMessage(
+                caption,
+                this.cfg.agentName ?? this.cfg.identityId,
+                this.cfg.identityId,
+                {
+                  senderIsAgent: loopSenderIsAgent,
+                  roomDisplayName: this.ownRoomDisplayName(),
+                  agentHops,
+                  maxAgentHops: this.maxAgentHops
+                }
+              );
+              if (!answerable) this.filteredRoomMessages++;
+            } else if (loopSenderIsAgent === true && !agentHopAllowed(agentHops, this.maxAgentHops)) {
+              answerable = false;
+            }
+            if (!answerable) {
+              if (loopSenderIsAgent === true) this.noteAgentTurnSuppressed(agentHops);
+              acked.push(m.queueId);
+              continue;
+            }
+            const ref = parseVaultRefBody(parsed);
+            if (ref === null) {
+              this.refusedVaultRefs++;
+              writeServiceLog("warn", "vault_ref.invalid");
+              acked.push(m.queueId);
+              continue;
+            }
+            const recordedEnclave = this.store.getChannelMeta(m.channelId)?.enclaveId;
+            if (!encId || ref.enclaveId !== encId || recordedEnclave !== ref.enclaveId) {
+              this.refusedVaultRefs++;
+              writeServiceLog("warn", "vault_ref.enclave_mismatch");
+              acked.push(m.queueId);
+              continue;
+            }
+            const vaultRefMessage = {
+              channel_id: m.channelId,
+              message_id: m.messageId,
+              sender_id: m.envelope.sender_id,
+              // A bare link still reads as something to a runtime that
+              // ignores vault_refs.
+              text: ref.text ? ref.text : VAULT_REF_BARE_TEXT,
+              ts: m.receivedAt,
+              authorization: this.authorizationFor(m.channelId, m.envelope.sender_id),
+              sender_name: this.freshRoster(m.channelId)?.get(m.envelope.sender_id)?.name,
+              sender_is_agent: senderIsAgent,
+              vault_refs: [toVaultRefEntry(ref)],
+              ...m.voiceMode ? {
+                voice: true,
+                guidance: selectVoiceGuidance(chanMeta?.is_dm, m.voiceDefaultResponder)
+              } : {}
+            };
+            if (!await this.stageRuntimeMessage(vaultRefMessage)) continue;
+            acked.push(m.queueId);
+            continue;
+          }
           if (parsed.type === "artifact_share") {
             try {
               const senderName = this.freshRoster(m.channelId)?.get(m.envelope.sender_id)?.name;
@@ -33234,6 +33400,7 @@ var BridgeAgent = class _BridgeAgent {
       custody_read_failing: this.provider.custodyHealth().readFailing,
       custody_store_unavailable: this.provider.custodyHealth().storeUnavailable,
       failed_attachments: this.failedAttachments,
+      refused_vault_refs: this.refusedVaultRefs,
       fast_path_sent: this.fastPathSent,
       fast_path_failed: this.fastPathFailed,
       fast_path_skipped: this.fastPathSkipped,
@@ -33294,6 +33461,7 @@ var BridgeAgent = class _BridgeAgent {
       custody: this.provider.custodyHealth(),
       welcomeRequestsSent: this.welcomeRequestsSent,
       failedAttachments: this.failedAttachments,
+      refusedVaultRefs: this.refusedVaultRefs,
       build: BRIDGE_VERSION
     };
   }
@@ -33398,6 +33566,10 @@ var BRIDGE_ERRORS = {
   // tell "server/network hiccup, retry" apart from "this ciphertext or key
   // material is not trustworthy, do not retry blindly".
   vault_integrity_failed: { http: 422, message: "vault content or key material failed integrity/signature verification" },
+  // Files link (review 2026-10-01 R4): a pinned /v1/vault-read whose node no
+  // longer holds the shared bytes or key. Terminal for that link: never fall
+  // back to the current version. `detail.pin` names the refused pin.
+  vault_ref_changed: { http: 422, message: "this file changed in Files after it was shared; not opened" },
   internal: { http: 500, message: "internal error" }
 };
 function errorBody(code, detail) {
@@ -33444,8 +33616,13 @@ function capabilities(opts) {
     api_version: "1",
     receive_modes: ["longpoll", "sse", ...opts.websocket ? ["websocket"] : []],
     send_types: ["text", "agent_status", "a2a"],
-    webhook_push: false
+    webhook_push: false,
     // B3: A2A-style push-notification config (ciphertext/wake-only)
+    // Files link (review 2026-10-01 section 6): the highest `vault_ref` body
+    // version this daemon parses into BridgeMessage.vault_refs (never fetched
+    // on receipt) and opens with the R4 pins on /v1/vault-read. A daemon
+    // without this field skips and acks a link, so the agent never sees it.
+    vault_ref: 1
   };
 }
 var SEND_CAP = 64 * 1024;
@@ -33487,8 +33664,17 @@ var vaultWriteSchema = z3.object({
 var vaultReadSchema = z3.object({
   enclave_id: z3.string().min(1),
   vault_channel_id: z3.string().min(1).optional(),
-  node_id: z3.string().min(1)
-});
+  node_id: z3.string().min(1),
+  // Files link pins (review 2026-10-01 R4), copied by the runtime from a
+  // BridgeMessage.vault_refs entry. Each is enforced when present; omitted,
+  // the read is unchanged.
+  expected_content_hash: z3.string().regex(VAULT_PIN).optional(),
+  expected_dek_commit: z3.string().regex(VAULT_PIN).optional()
+}).refine(
+  // Audit H1: both pins or neither. A single pin is never a weaker pinned read.
+  (d) => d.expected_content_hash === void 0 === (d.expected_dek_commit === void 0),
+  { message: VAULT_PINS_TOGETHER }
+);
 var vaultListSchema = z3.object({
   enclave_id: z3.string().min(1),
   vault_channel_id: z3.string().min(1).optional(),
@@ -33628,7 +33814,11 @@ function createHttpServer(agent, opts) {
       if (method === "POST" && path === "/v1/vault-read") {
         const parsed = vaultReadSchema.safeParse(JSON.parse(await readBody(req, OTHER_CAP)));
         if (!parsed.success) return jsonError(res, "invalid_request", parsed.error.issues);
-        const r = await agent.vaultRead(parsed.data.enclave_id, parsed.data.vault_channel_id, parsed.data.node_id);
+        const { expected_content_hash: pinHash, expected_dek_commit: pinCommit } = parsed.data;
+        const r = pinHash !== void 0 && pinCommit !== void 0 ? await agent.vaultRead(parsed.data.enclave_id, parsed.data.vault_channel_id, parsed.data.node_id, {
+          contentHash: pinHash,
+          dekCommit: pinCommit
+        }) : await agent.vaultRead(parsed.data.enclave_id, parsed.data.vault_channel_id, parsed.data.node_id);
         return json(res, 200, r);
       }
       if (method === "POST" && path === "/v1/vault-list") {
@@ -33721,6 +33911,7 @@ function createHttpServer(agent, opts) {
       if (e instanceof GroupSupersededSendError) return jsonError(res, "group_superseded");
       if (e instanceof IdempotencyConflictError) return jsonError(res, "invalid_request", e.message);
       if (e instanceof InvalidPathError) return jsonError(res, "invalid_request", e.message);
+      if (e instanceof VaultPinMismatchError) return jsonError(res, "vault_ref_changed", { pin: e.pin });
       if (e instanceof VaultIntegrityError) return jsonError(res, "vault_integrity_failed", e.message);
       if (e instanceof SyntaxError) return jsonError(res, "invalid_json");
       writeServiceLog("error", "http.request_failed", {}, e);

package/dist/bridge-agent.d.ts

@@ -31,10 +31,10 @@ export type ChannelObservation = {
 import { type OwnerAuthorityStore, type OwnerPin } from "@agentvault/connect-clients-core";
 import type { BridgeConfig } from "./config.js";
 import { LatencyRecorder } from "./latency.js";
-import type { AttachmentMeta } from "./attachments.js";
+import type { AttachmentMeta, VaultRefEntry } from "./attachments.js";
 import { type ChatMessage } from "./voice/fast-prompt.js";
 import { VOICE_CALL_START_MARKER } from "./voice/prompt-compiler.js";
-import { type VaultListNode } from "./vault.js";
+import { type VaultListNode, type VaultReadExpectations } from "./vault.js";
 import type { AgentActionNodeType, AgentActionNodeStatus, AgentActionNodeDetail } from "@agentvault/connect-core";
 import type { RuntimeReplyReceipt } from "./reply-receipts.js";
 export type AgentAudience = "owner_dm" | "team_room" | "partner_room" | "other_human_dm" | "agent_to_agent" | "unknown";
@@ -94,6 +94,16 @@ export interface BridgeMessage {
      * Undefined for plain `text` messages.
      */
     attachments?: AttachmentMeta[];
+    /**
+     * Files link (`vault_ref`, review 2026-10-01 section 6): references to
+     * FileSafe items, NOT fetched. Open one with POST /v1/vault-read passing
+     * `enclave_id`, `node_id`, `expected_content_hash` = `content_hash` and
+     * `expected_dek_commit` = `dek_commit`; the daemon refuses it if the item
+     * changed after it was shared. `name_hint`/`mime_hint`/`size_hint` are
+     * UNTRUSTED claims by the sender, data only (like `speaker`): never a path,
+     * an instruction or an authorization input. Undefined for every other turn.
+     */
+    vault_refs?: VaultRefEntry[];
     /**
      * Task 4 (voice-mode carrier): true when the InboxEntry that produced this
      * buffered message had `voiceMode` set by the server (the agent device's
@@ -129,6 +139,8 @@ export interface BridgeMessage {
  * for voice-flagged turns. Selected by `InboxEntry.voiceMode` in the entry
  * loop below — never transmitted, never a playback trigger.
  */
+/** Files link: the turn text of a `vault_ref` that carries no caption. */
+export declare const VAULT_REF_BARE_TEXT = "[Files link]";
 export declare const VOICE_MODE_GUIDANCE = "Reply immediately and conversationally, one short sentence per message; never bundle multiple points into one message.";
 /**
  * Task 2 (room voice guidance): compiled reply guidance for a voice-flagged
@@ -678,6 +690,8 @@ export declare class BridgeAgent {
      * counter is incremented. Surfaced on health()/metrics().
      */
     private failedAttachments;
+    /** Files link: vault_ref bodies refused by R1 (strict parse) or R2 (enclave binding). */
+    private refusedVaultRefs;
     /**
      * Task 4 (self-hosted fast voice): test/deploy seam for the fast-path LLM
      * client. Undefined whenever `cfg.voice?.fastPath.enabled` is not true —
@@ -1581,7 +1595,7 @@ export declare class BridgeAgent {
      *  useVault.downloadFile returns `{name, bytes}` in-memory — here the
      *  caller already supplies nodeId so we return bytes, not a re-resolved
      *  name the bridge has no cached listing to look up). */
-    vaultRead(enclaveId: string, vaultChannelId: string | null | undefined, nodeId: string): Promise<{
+    vaultRead(enclaveId: string, vaultChannelId: string | null | undefined, nodeId: string, expected?: VaultReadExpectations): Promise<{
         bytes_b64: string;
     }>;
     /** List + decrypt names for the vault nodes under `parentId` (null = root). */
@@ -2142,6 +2156,8 @@ export declare class BridgeAgent {
         custody_store_unavailable: boolean;
         /** Track 5: cumulative artifact_share messages where download/decrypt/digest failed (fail-soft — acked, no redeliver). */
         failed_attachments: number;
+        /** Files link: vault_ref bodies refused by R1 (strict parse) or R2 (enclave binding), acked. */
+        refused_vault_refs: number;
         /** Task 4 (self-hosted fast voice): cumulative fast-path replies actually sent. */
         fast_path_sent: number;
         /** Task 4 (self-hosted fast voice): cumulative fast-path attempts that errored (LLM call, normalization, or send) — fail-soft, never blocks the buffered turn. */
@@ -2292,6 +2308,8 @@ export declare class BridgeAgent {
         welcomeRequestsSent: number;
         /** Track 5: cumulative artifact_share failures (download/decrypt/digest). */
         failedAttachments: number;
+        /** Files link: vault_ref bodies refused by R1 (strict parse) or R2 (enclave binding), acked. */
+        refusedVaultRefs: number;
         /** SDK-6: bridge build id, so a /v1/metrics reading captured across a daemon
          * restart can be attributed to a version — counters are process-lifetime
          * and zero on restart (spec §5.5). */

package/dist/errors.d.ts

@@ -6,7 +6,7 @@
  * WebSocket returns `{type:"error", error, message, detail?}`. A client gets the
  * same `error` code regardless of which transport it used. (A2A §9.5/§10.6 pattern.)
  */
-export type BridgeErrorCode = "unauthorized" | "forbidden_origin" | "not_found" | "invalid_request" | "invalid_json" | "body_too_large" | "channel_pending" | "rate_limited" | "agent_paused" | "send_forbidden" | "group_superseded" | "unknown_action_run" | "vault_integrity_failed" | "internal";
+export type BridgeErrorCode = "unauthorized" | "forbidden_origin" | "not_found" | "invalid_request" | "invalid_json" | "body_too_large" | "channel_pending" | "rate_limited" | "agent_paused" | "send_forbidden" | "group_superseded" | "unknown_action_run" | "vault_integrity_failed" | "vault_ref_changed" | "internal";
 export interface BridgeErrorSpec {
     /** HTTP status this code maps to (the WS binding ignores it). */
     http: number;

package/dist/http-server.d.ts

@@ -43,6 +43,7 @@ export declare function capabilities(opts: {
     receive_modes: string[];
     send_types: string[];
     webhook_push: boolean;
+    vault_ref: number;
 };
 export declare const memoryRecordSchema: z.ZodEffects<z.ZodObject<{
     conversation_id: z.ZodString;
@@ -56,7 +57,7 @@ export declare const memoryRecordSchema: z.ZodEffects<z.ZodObject<{
     text: string;
     role: "agent" | "peer";
     conversation_id: string;
-    modality: "voice" | "text";
+    modality: "text" | "voice";
     message_id?: string | undefined;
     idempotency_key?: string | undefined;
     peer_id?: string | undefined;
@@ -64,7 +65,7 @@ export declare const memoryRecordSchema: z.ZodEffects<z.ZodObject<{
     text: string;
     role: "agent" | "peer";
     conversation_id: string;
-    modality: "voice" | "text";
+    modality: "text" | "voice";
     message_id?: string | undefined;
     idempotency_key?: string | undefined;
     peer_id?: string | undefined;
@@ -72,7 +73,7 @@ export declare const memoryRecordSchema: z.ZodEffects<z.ZodObject<{
     text: string;
     role: "agent" | "peer";
     conversation_id: string;
-    modality: "voice" | "text";
+    modality: "text" | "voice";
     message_id?: string | undefined;
     idempotency_key?: string | undefined;
     peer_id?: string | undefined;
@@ -80,7 +81,7 @@ export declare const memoryRecordSchema: z.ZodEffects<z.ZodObject<{
     text: string;
     role: "agent" | "peer";
     conversation_id: string;
-    modality: "voice" | "text";
+    modality: "text" | "voice";
     message_id?: string | undefined;
     idempotency_key?: string | undefined;
     peer_id?: string | undefined;

package/dist/index.js

@@ -8593,6 +8593,31 @@ function unpackDekMaterial(buf) {
   return { fileKey: buf.subarray(0, 32), fileNonce: buf.subarray(32) };
 }
 
+// ../connect-clients-core/dist/filesafe/dek-commit.js
+import { blake2b as blake2b2 } from "@noble/hashes/blake2b";
+var DEK_COMMIT_LABEL = "securecoms/vault_ref/dek/v1";
+function computeDekCommit(enclaveId, nodeId, fileKey, fileNonce) {
+  const enc3 = new TextEncoder();
+  const sep = new Uint8Array([0]);
+  const parts = [
+    enc3.encode(DEK_COMMIT_LABEL),
+    sep,
+    enc3.encode(enclaveId),
+    sep,
+    enc3.encode(nodeId),
+    sep,
+    packDekMaterial(fileKey, fileNonce)
+  ];
+  const preimage = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) {
+    preimage.set(p, at);
+    at += p.length;
+  }
+  const digest = blake2b2(preimage, { dkLen: 32 });
+  return `blake2b:${Array.from(digest, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
 // ../../node_modules/@agentvault/crypto/dist/index.js
 init_sha2();
 init_hmac();
@@ -25491,7 +25516,7 @@ var FakeConnectBackend = class _FakeConnectBackend {
       message_id: messageId,
       channel_id: p.channelId,
       enclave_id: p.enclaveId,
-      message_type: "text",
+      message_type: p.messageType ?? "text",
       sender_id: p.senderId,
       sender_type: "agent",
       identity_proof: { signature: "", algo: "ed25519", attested: false, canonicalization: "RFC8785" },
@@ -27388,6 +27413,47 @@ var DecryptErrorLogLimiter = class {
 
 // src/attachments.ts
 import { basename } from "node:path";
+var VAULT_REF_MAX_SIZE_HINT = 100 * 1024 * 1024 - 16;
+var VAULT_REF_MAX_NAME = 255;
+var VAULT_REF_MAX_MIME = 127;
+var CANONICAL_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+var VAULT_PIN = /^blake2b:[0-9a-f]{64}$/;
+var HINT_FORBIDDEN = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
+var MIME_TYPE = /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$/;
+function parseVaultRefBody(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const r = raw;
+  if (r.type !== "vault_ref" || r.v !== 1) return null;
+  const { enclaveId, nodeId, contentHash, dekCommit } = r;
+  if (typeof enclaveId !== "string" || !CANONICAL_UUID.test(enclaveId)) return null;
+  if (typeof nodeId !== "string" || !CANONICAL_UUID.test(nodeId)) return null;
+  if (typeof contentHash !== "string" || !VAULT_PIN.test(contentHash)) return null;
+  if (typeof dekCommit !== "string" || !VAULT_PIN.test(dekCommit)) return null;
+  const body = { v: 1, type: "vault_ref", enclaveId, nodeId, contentHash, dekCommit };
+  if (typeof r.name === "string" && r.name.length <= VAULT_REF_MAX_NAME && !HINT_FORBIDDEN.test(r.name)) {
+    body.name = r.name;
+  }
+  if (typeof r.mime === "string" && r.mime.length <= VAULT_REF_MAX_MIME && !HINT_FORBIDDEN.test(r.mime) && MIME_TYPE.test(r.mime)) {
+    body.mime = r.mime;
+  }
+  if (typeof r.size === "number" && Number.isInteger(r.size) && r.size >= 0 && r.size <= VAULT_REF_MAX_SIZE_HINT) {
+    body.size = r.size;
+  }
+  if (typeof r.text === "string") body.text = r.text;
+  return body;
+}
+function toVaultRefEntry(body) {
+  const entry = {
+    enclave_id: body.enclaveId,
+    node_id: body.nodeId,
+    content_hash: body.contentHash,
+    dek_commit: body.dekCommit
+  };
+  if (body.name !== void 0) entry.name_hint = body.name;
+  if (body.mime !== void 0) entry.mime_hint = body.mime;
+  if (body.size !== void 0) entry.size_hint = body.size;
+  return entry;
+}
 function sanitizeFilename(name, fallback) {
   const base = basename(name ?? "");
   const cleaned = base.replace(/[/\\]/g, "").replace(/^\.+$/, "");
@@ -28257,6 +28323,15 @@ var VaultIntegrityError = class extends Error {
     if (cause !== void 0) this.cause = cause;
   }
 };
+var VaultPinMismatchError = class extends VaultIntegrityError {
+  pin;
+  constructor(pin) {
+    super(`vault: pinned ${pin} does not match; the file changed after it was shared, not opened`);
+    this.name = "VaultPinMismatchError";
+    this.pin = pin;
+  }
+};
+var VAULT_PINS_TOGETHER = "expected_content_hash and expected_dek_commit go together";
 async function vaultWriteImpl(args2) {
   const gen = args2.deps.currentGeneration;
   const kek = args2.deps.exporterKekForGeneration(gen);
@@ -28280,10 +28355,20 @@ async function vaultWriteImpl(args2) {
   return { node_id: created.node_id };
 }
 async function vaultReadImpl(args2) {
+  const pinnedHash = args2.expected?.contentHash;
+  const pinnedCommit = args2.expected?.dekCommit;
+  if (args2.expected !== void 0 && (typeof pinnedHash !== "string" || typeof pinnedCommit !== "string")) {
+    throw new VaultIntegrityError(`vault: ${VAULT_PINS_TOGETHER}`);
+  }
   const meta = await args2.deps.getNodeForDownload(args2.nodeId);
+  if (pinnedHash !== void 0 && meta.content_hash !== pinnedHash) {
+    throw new VaultPinMismatchError("content_hash_server");
+  }
   const ct = await args2.deps.getBlob(meta.download_url);
-  const expected = (meta.content_hash ?? "").replace(/^blake2b:/, "");
-  if (await computeFileDigest(ct) !== expected) {
+  const digestHex = await computeFileDigest(ct);
+  if (pinnedHash !== void 0) {
+    if (`blake2b:${digestHex}` !== pinnedHash) throw new VaultPinMismatchError("ciphertext_digest");
+  } else if (digestHex !== (meta.content_hash ?? "").replace(/^blake2b:/, "")) {
     throw new VaultIntegrityError("vault: ciphertext failed integrity/digest check");
   }
   const wrap = [...meta.wraps].sort((a, b) => b.kek_generation - a.kek_generation)[0];
@@ -28297,6 +28382,9 @@ async function vaultReadImpl(args2) {
   } catch (e) {
     throw new VaultIntegrityError("vault: DEK unwrap failed (bad KEK, AAD mismatch, or tampered wrap)", e);
   }
+  if (pinnedCommit !== void 0 && computeDekCommit(args2.enclaveId, args2.nodeId, fileKey, fileNonce) !== pinnedCommit) {
+    throw new VaultPinMismatchError("dek_commit");
+  }
   try {
     return await decryptFile(ct, fileKey, fileNonce);
   } catch (e) {
@@ -28794,6 +28882,7 @@ function logPendingCommitResolved(outcome) {
       writeServiceLog2("info", "mls.pending_commit.resolved.unknown");
   }
 }
+var VAULT_REF_BARE_TEXT = "[Files link]";
 var VOICE_MODE_GUIDANCE = "Reply immediately and conversationally, one short sentence per message; never bundle multiple points into one message.";
 var FAST_PATH_SPOKEN_GUIDANCE = "A one-sentence spoken acknowledgement has already been sent for this turn. Reply only with information it did not contain, in one or two short sentences; if there is nothing to add, send nothing.";
 var ROOM_VOICE_GUIDANCE_MENTION_ONLY = "You are in a group voice room. Reply ONLY when a message @mentions your display name. Keep replies to one short sentence. When you should not reply, send nothing.";
@@ -29288,6 +29377,8 @@ var BridgeAgent = class _BridgeAgent {
    * counter is incremented. Surfaced on health()/metrics().
    */
   failedAttachments = 0;
+  /** Files link: vault_ref bodies refused by R1 (strict parse) or R2 (enclave binding). */
+  refusedVaultRefs = 0;
   /**
    * Task 4 (self-hosted fast voice): test/deploy seam for the fast-path LLM
    * client. Undefined whenever `cfg.voice?.fastPath.enabled` is not true —
@@ -31349,11 +31440,12 @@ var BridgeAgent = class _BridgeAgent {
    *  useVault.downloadFile returns `{name, bytes}` in-memory — here the
    *  caller already supplies nodeId so we return bytes, not a re-resolved
    *  name the bridge has no cached listing to look up). */
-  async vaultRead(enclaveId, vaultChannelId, nodeId) {
+  async vaultRead(enclaveId, vaultChannelId, nodeId, expected) {
     const session = await this.getVaultSession(enclaveId, await this.resolveVaultChannelId(enclaveId, vaultChannelId));
     const bytes = await vaultReadImpl({
       enclaveId,
       nodeId,
+      expected,
       deps: {
         exporterKekForGeneration: session.kekForGeneration,
         getNodeForDownload: (id) => this.vaultGetNodeForDownload(enclaveId, id),
@@ -32343,7 +32435,12 @@ var BridgeAgent = class _BridgeAgent {
         const encId = m.envelope.enclave_id;
         if (encId && !this.channelEnclaveRecorded.has(m.channelId)) {
           this.channelEnclaveRecorded.add(m.channelId);
-          this.store.recordChannelEnclave(m.channelId, encId);
+          const priorEnclave = this.store.getChannelMeta(m.channelId)?.enclaveId;
+          if (priorEnclave === void 0) {
+            this.store.recordChannelEnclave(m.channelId, encId);
+          } else if (priorEnclave !== encId) {
+            writeServiceLog2("warn", "channel_enclave.envelope_mismatch");
+          }
         }
         const parsed = JSON.parse(
           new TextDecoder().decode(m.plaintext)
@@ -32357,6 +32454,75 @@ var BridgeAgent = class _BridgeAgent {
             acked.push(m.queueId);
             continue;
           }
+          if (parsed.type === "vault_ref") {
+            const senderType = m.envelope.sender_type;
+            const senderIsAgent = senderType === "agent" ? true : senderType === "human" ? false : void 0;
+            const chanMeta = this.freshMeta(m.channelId);
+            const loopSenderIsAgent = this.loopSenderIsAgent(
+              m.channelId,
+              m.envelope.sender_id,
+              senderIsAgent,
+              false
+            );
+            const agentHops = this.agentHops.noteInbound(m.channelId, loopSenderIsAgent, m.messageId);
+            const caption = typeof parsed.text === "string" ? parsed.text : "";
+            let answerable = true;
+            if (chanMeta && chanMeta.is_dm === false) {
+              answerable = shouldProcessRoomMessage(
+                caption,
+                this.cfg.agentName ?? this.cfg.identityId,
+                this.cfg.identityId,
+                {
+                  senderIsAgent: loopSenderIsAgent,
+                  roomDisplayName: this.ownRoomDisplayName(),
+                  agentHops,
+                  maxAgentHops: this.maxAgentHops
+                }
+              );
+              if (!answerable) this.filteredRoomMessages++;
+            } else if (loopSenderIsAgent === true && !agentHopAllowed(agentHops, this.maxAgentHops)) {
+              answerable = false;
+            }
+            if (!answerable) {
+              if (loopSenderIsAgent === true) this.noteAgentTurnSuppressed(agentHops);
+              acked.push(m.queueId);
+              continue;
+            }
+            const ref = parseVaultRefBody(parsed);
+            if (ref === null) {
+              this.refusedVaultRefs++;
+              writeServiceLog2("warn", "vault_ref.invalid");
+              acked.push(m.queueId);
+              continue;
+            }
+            const recordedEnclave = this.store.getChannelMeta(m.channelId)?.enclaveId;
+            if (!encId || ref.enclaveId !== encId || recordedEnclave !== ref.enclaveId) {
+              this.refusedVaultRefs++;
+              writeServiceLog2("warn", "vault_ref.enclave_mismatch");
+              acked.push(m.queueId);
+              continue;
+            }
+            const vaultRefMessage = {
+              channel_id: m.channelId,
+              message_id: m.messageId,
+              sender_id: m.envelope.sender_id,
+              // A bare link still reads as something to a runtime that
+              // ignores vault_refs.
+              text: ref.text ? ref.text : VAULT_REF_BARE_TEXT,
+              ts: m.receivedAt,
+              authorization: this.authorizationFor(m.channelId, m.envelope.sender_id),
+              sender_name: this.freshRoster(m.channelId)?.get(m.envelope.sender_id)?.name,
+              sender_is_agent: senderIsAgent,
+              vault_refs: [toVaultRefEntry(ref)],
+              ...m.voiceMode ? {
+                voice: true,
+                guidance: selectVoiceGuidance(chanMeta?.is_dm, m.voiceDefaultResponder)
+              } : {}
+            };
+            if (!await this.stageRuntimeMessage(vaultRefMessage)) continue;
+            acked.push(m.queueId);
+            continue;
+          }
           if (parsed.type === "artifact_share") {
             try {
               const senderName = this.freshRoster(m.channelId)?.get(m.envelope.sender_id)?.name;
@@ -33083,6 +33249,7 @@ var BridgeAgent = class _BridgeAgent {
       custody_read_failing: this.provider.custodyHealth().readFailing,
       custody_store_unavailable: this.provider.custodyHealth().storeUnavailable,
       failed_attachments: this.failedAttachments,
+      refused_vault_refs: this.refusedVaultRefs,
       fast_path_sent: this.fastPathSent,
       fast_path_failed: this.fastPathFailed,
       fast_path_skipped: this.fastPathSkipped,
@@ -33143,6 +33310,7 @@ var BridgeAgent = class _BridgeAgent {
       custody: this.provider.custodyHealth(),
       welcomeRequestsSent: this.welcomeRequestsSent,
       failedAttachments: this.failedAttachments,
+      refusedVaultRefs: this.refusedVaultRefs,
       build: BRIDGE_VERSION
     };
   }
@@ -33354,6 +33522,10 @@ var BRIDGE_ERRORS = {
   // tell "server/network hiccup, retry" apart from "this ciphertext or key
   // material is not trustworthy, do not retry blindly".
   vault_integrity_failed: { http: 422, message: "vault content or key material failed integrity/signature verification" },
+  // Files link (review 2026-10-01 R4): a pinned /v1/vault-read whose node no
+  // longer holds the shared bytes or key. Terminal for that link: never fall
+  // back to the current version. `detail.pin` names the refused pin.
+  vault_ref_changed: { http: 422, message: "this file changed in Files after it was shared; not opened" },
   internal: { http: 500, message: "internal error" }
 };
 function errorBody(code, detail) {
@@ -33400,8 +33572,13 @@ function capabilities(opts) {
     api_version: "1",
     receive_modes: ["longpoll", "sse", ...opts.websocket ? ["websocket"] : []],
     send_types: ["text", "agent_status", "a2a"],
-    webhook_push: false
+    webhook_push: false,
     // B3: A2A-style push-notification config (ciphertext/wake-only)
+    // Files link (review 2026-10-01 section 6): the highest `vault_ref` body
+    // version this daemon parses into BridgeMessage.vault_refs (never fetched
+    // on receipt) and opens with the R4 pins on /v1/vault-read. A daemon
+    // without this field skips and acks a link, so the agent never sees it.
+    vault_ref: 1
   };
 }
 var SEND_CAP = 64 * 1024;
@@ -33443,8 +33620,17 @@ var vaultWriteSchema = z3.object({
 var vaultReadSchema = z3.object({
   enclave_id: z3.string().min(1),
   vault_channel_id: z3.string().min(1).optional(),
-  node_id: z3.string().min(1)
-});
+  node_id: z3.string().min(1),
+  // Files link pins (review 2026-10-01 R4), copied by the runtime from a
+  // BridgeMessage.vault_refs entry. Each is enforced when present; omitted,
+  // the read is unchanged.
+  expected_content_hash: z3.string().regex(VAULT_PIN).optional(),
+  expected_dek_commit: z3.string().regex(VAULT_PIN).optional()
+}).refine(
+  // Audit H1: both pins or neither. A single pin is never a weaker pinned read.
+  (d) => d.expected_content_hash === void 0 === (d.expected_dek_commit === void 0),
+  { message: VAULT_PINS_TOGETHER }
+);
 var vaultListSchema = z3.object({
   enclave_id: z3.string().min(1),
   vault_channel_id: z3.string().min(1).optional(),
@@ -33584,7 +33770,11 @@ function createHttpServer(agent, opts) {
       if (method === "POST" && path === "/v1/vault-read") {
         const parsed = vaultReadSchema.safeParse(JSON.parse(await readBody(req, OTHER_CAP)));
         if (!parsed.success) return jsonError(res, "invalid_request", parsed.error.issues);
-        const r = await agent.vaultRead(parsed.data.enclave_id, parsed.data.vault_channel_id, parsed.data.node_id);
+        const { expected_content_hash: pinHash, expected_dek_commit: pinCommit } = parsed.data;
+        const r = pinHash !== void 0 && pinCommit !== void 0 ? await agent.vaultRead(parsed.data.enclave_id, parsed.data.vault_channel_id, parsed.data.node_id, {
+          contentHash: pinHash,
+          dekCommit: pinCommit
+        }) : await agent.vaultRead(parsed.data.enclave_id, parsed.data.vault_channel_id, parsed.data.node_id);
         return json(res, 200, r);
       }
       if (method === "POST" && path === "/v1/vault-list") {
@@ -33677,6 +33867,7 @@ function createHttpServer(agent, opts) {
       if (e instanceof GroupSupersededSendError) return jsonError(res, "group_superseded");
       if (e instanceof IdempotencyConflictError) return jsonError(res, "invalid_request", e.message);
       if (e instanceof InvalidPathError) return jsonError(res, "invalid_request", e.message);
+      if (e instanceof VaultPinMismatchError) return jsonError(res, "vault_ref_changed", { pin: e.pin });
       if (e instanceof VaultIntegrityError) return jsonError(res, "vault_integrity_failed", e.message);
       if (e instanceof SyntaxError) return jsonError(res, "invalid_json");
       writeServiceLog2("error", "http.request_failed", {}, e);

package/dist/vault.d.ts

@@ -6,6 +6,18 @@
 export declare class VaultIntegrityError extends Error {
     constructor(message: string, cause?: unknown);
 }
+/** Which Files-link pin a pinned read refused on (review 2026-10-01 R4). */
+export type VaultPin = "content_hash_server" | "ciphertext_digest" | "dek_commit";
+/** A pinned read (`/v1/vault-read` with expected_*) refused because the node no
+ *  longer holds the bytes or key that were shared: "This file changed in Files
+ *  after it was shared. Not opened." A VaultIntegrityError, so every existing
+ *  integrity handler still fails closed on it. */
+export declare class VaultPinMismatchError extends VaultIntegrityError {
+    readonly pin: VaultPin;
+    constructor(pin: VaultPin);
+}
+/** The pin pair error text, shared with the HTTP boundary's refine (H1). */
+export declare const VAULT_PINS_TOGETHER = "expected_content_hash and expected_dek_commit go together";
 export interface VaultWriteDeps {
     exporterKekForGeneration: (gen: number) => Uint8Array;
     currentGeneration: number;
@@ -45,10 +57,21 @@ export interface VaultReadDeps {
     }>;
     getBlob: (url: string) => Promise<Uint8Array>;
 }
+/** Files-link pins for a read (review 2026-10-01 R4). Both are
+ *  "blake2b:" + 64 hex, validated at the HTTP boundary. BOTH OR NEITHER
+ *  (audit H1): a lone dekCommit fell back to the server's content_hash, so a
+ *  member holding the KEK could re-encrypt new plaintext under the same DEK,
+ *  recreate the node with the same wrap and a new hash, and be served it; a
+ *  lone contentHash leaves the two-key swap open. */
+export interface VaultReadExpectations {
+    contentHash: string;
+    dekCommit: string;
+}
 export declare function vaultReadImpl(args: {
     enclaveId: string;
     nodeId: string;
     deps: VaultReadDeps;
+    expected?: VaultReadExpectations;
 }): Promise<Uint8Array>;
 export interface VaultListRawNode {
     node_id: string;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const BRIDGE_VERSION = "0.25.4";
+export declare const BRIDGE_VERSION = "0.26.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-bridge",
-  "version": "0.25.4",
+  "version": "0.26.0",
   "type": "module",
   "engines": {
     "node": ">=22.5.0"