@securecoms/agent-bridge 0.1.0 → 0.2.0

package/README.md

@@ -363,6 +363,25 @@ The loopback hop carries plaintext by design — the agent is the endpoint and t
 
 ---
 
+## Attachments and any-language agents
+
+The daemon is the universal substrate: an agent in any language (Python, Go,
+TypeScript, ...) connects over the local loopback WS/HTTP and never speaks MLS
+itself. The daemon performs all MLS encryption/decryption in TypeScript and hands
+the agent **plaintext** — message text and, for attachments, a **local file path**.
+
+- **Receiving an attachment:** the delivered message includes
+  `attachments: [{ filename, mime, size, path, sha256 }]`. Read the file at `path`
+  (saved under `<store-dir>/attachments/<channel>/`). No MLS, no key handling.
+- **Sending an attachment:** `POST /v1/send-attachment` with
+  `{ "channel_id": "...", "path": "/local/file.png", "caption": "optional" }`.
+  The daemon reads, encrypts, uploads, and dispatches it.
+
+This is why Python agents (which have no native MLS library) fully support
+attachments: the cryptography lives in the daemon, not the agent.
+
+---
+
 ## Flags and environment
 
 | Flag | Env var | Default | Description |

package/dist/bin.js

@@ -2439,6 +2439,11 @@ var SqliteMlsStateStore = class {
   }
 };
 
+// src/bridge-agent.ts
+import { decryptFile, encryptFile, computeFileDigest, base64ToBytes as base64ToBytes2, bytesToBase64 as bytesToBase642 } from "@agentvault/crypto";
+import { promises as fsp } from "node:fs";
+import { join as join2, dirname as dirname2 } from "node:path";
+
 // src/latency.ts
 var DEFAULT_CAPACITY = 1024;
 function round(n) {
@@ -2586,6 +2591,74 @@ var TokenBucketFloor = class {
   }
 };
 
+// src/attachments.ts
+import { basename } from "node:path";
+function sanitizeFilename(name, fallback) {
+  const base = basename(name ?? "");
+  const cleaned = base.replace(/[/\\]/g, "").replace(/^\.+$/, "");
+  return cleaned.length > 0 ? cleaned : fallback;
+}
+var MIME_BY_EXT = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  pdf: "application/pdf",
+  txt: "text/plain",
+  md: "text/markdown",
+  json: "application/json",
+  csv: "text/csv",
+  html: "text/html",
+  mp4: "video/mp4",
+  mp3: "audio/mpeg",
+  zip: "application/zip",
+  wav: "audio/wav"
+};
+function mimeForName(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot < 0 || dot === name.length - 1) return "application/octet-stream";
+  return MIME_BY_EXT[name.slice(dot + 1).toLowerCase()] ?? "application/octet-stream";
+}
+async function prepareAttachment(filePath, caption, channelId, deps) {
+  const bytes = await deps.readFile(filePath);
+  const name = basename(filePath);
+  const { encryptedData, fileKey, fileNonce, digest } = deps.encryptFile(bytes);
+  const blobId = await deps.uploadBlob(encryptedData, channelId);
+  const body = {
+    v: 1,
+    type: "artifact_share",
+    name,
+    mime: mimeForName(name),
+    size: bytes.length,
+    blobId,
+    fileKey: deps.bytesToBase64(fileKey),
+    fileNonce: deps.bytesToBase64(fileNonce),
+    digest
+  };
+  if (caption) body.text = caption;
+  return body;
+}
+async function materializeAttachment(body, ctx, deps) {
+  const ciphertext = await deps.downloadBlob(body.blobId);
+  const sha2565 = deps.computeFileDigest(ciphertext);
+  if (sha2565 !== body.digest) {
+    throw new Error(`attachment digest mismatch for blob ${body.blobId}`);
+  }
+  const plain = deps.decryptFile(
+    ciphertext,
+    deps.base64ToBytes(body.fileKey),
+    deps.base64ToBytes(body.fileNonce)
+  );
+  const safeName = sanitizeFilename(body.name, ctx.messageId);
+  const dir = `${ctx.attachmentsDir}/${ctx.channelId}`;
+  const path = `${dir}/${ctx.messageId}-${safeName}`;
+  await deps.mkdirp(dir);
+  await deps.writeFile(path, plain);
+  return { filename: safeName, mime: body.mime, size: plain.length, path, sha256: sha2565 };
+}
+
 // src/bridge-agent.ts
 var DEFAULT_MAX_BUFFER = 1e3;
 var CHANNEL_META_TTL_MS = 5 * 6e4;
@@ -2606,6 +2679,14 @@ var RateLimitedError = class extends Error {
     this.name = "RateLimitedError";
   }
 };
+var InvalidPathError = class extends Error {
+  constructor(filePath, cause) {
+    super(`cannot read attachment file: ${filePath}`);
+    this.filePath = filePath;
+    this.name = "InvalidPathError";
+    if (cause !== void 0) this.cause = cause;
+  }
+};
 var BRIDGE_VERSION = "0.0.0";
 function hexToBytes2(h) {
   return new Uint8Array(Buffer.from(h, "hex"));
@@ -2644,6 +2725,25 @@ var BridgeAgent = class _BridgeAgent {
       capacity: cfg.rateLimitCapacity ?? 20,
       refillPerMinute: cfg.rateLimitRefillPerMinute ?? 20
     });
+    const self = this;
+    this.downloadBlobImpl = deps.downloadBlob ?? async function(blobId) {
+      const url = `${cfg.apiBase}/api/v1/attachments/${encodeURIComponent(blobId)}?caller_identity_id=${encodeURIComponent(cfg.identityId)}`;
+      const res = await self.fetchImpl(url, { headers: { authorization: `Bearer ${cfg.apiKey}` } });
+      if (!res.ok) throw new Error(`download blob failed: ${res.status}`);
+      return new Uint8Array(await res.arrayBuffer());
+    };
+    this.uploadBlobImpl = deps.uploadBlob ?? async function(ciphertext, channelId) {
+      const url = `${cfg.apiBase}/api/v1/attachments?channel_id=${encodeURIComponent(channelId)}&caller_identity_id=${encodeURIComponent(cfg.identityId)}`;
+      const res = await self.fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/octet-stream", authorization: `Bearer ${cfg.apiKey}` },
+        body: ciphertext
+      });
+      if (!res.ok) throw new Error(`upload blob failed: ${res.status}`);
+      const j = await res.json();
+      return String(j.attachment_id);
+    };
+    this.attachmentsDirImpl = deps.attachmentsDir ?? join2(dirname2(cfg.storePath), "attachments");
   }
   transport;
   provider;
@@ -2687,6 +2787,12 @@ var BridgeAgent = class _BridgeAgent {
   rateLimitedSends = 0;
   /** Cumulative count of requestWelcome calls fired for no-local-state deliveries (self-heal signal). */
   welcomeRequestsSent = 0;
+  /**
+   * Track 5: cumulative count of artifact_share messages where download/decrypt/digest
+   * failed. Fail-soft — failures are acked (no redelivery), logged to stderr, and this
+   * counter is incremented. Surfaced on health()/metrics().
+   */
+  failedAttachments = 0;
   /** Per-channel timestamp of last requestWelcome call, for cooldown enforcement. */
   lastWelcomeRequest = /* @__PURE__ */ new Map();
   /** Minimum gap between requestWelcome calls for the same channel (2 minutes). */
@@ -2699,6 +2805,12 @@ var BridgeAgent = class _BridgeAgent {
   startedAt = 0;
   store;
   latency;
+  /** Track 5: injectable blob download fn (default: fetch-based). */
+  downloadBlobImpl;
+  /** Track 5: injectable blob upload fn (default: fetch-based). */
+  uploadBlobImpl;
+  /** Track 5: directory where received attachments are saved. */
+  attachmentsDirImpl;
   /**
    * Enforce the inbound-buffer cap with a DROP-OLDEST policy.
    *
@@ -2819,6 +2931,59 @@ var BridgeAgent = class _BridgeAgent {
     this.latency.record("send.total", performance.now() - sendStart);
     return { message_id: id, status: "sent" };
   }
+  sendDeps() {
+    return {
+      uploadBlob: (ciphertext, channelId) => this.uploadBlobImpl(ciphertext, channelId),
+      encryptFile,
+      bytesToBase64: bytesToBase642,
+      readFile: (p) => fsp.readFile(p).then((b) => new Uint8Array(b))
+    };
+  }
+  async sendAttachment(channelId, filePath, caption) {
+    this.enforceRateFloor("attachment", channelId);
+    const joined = await this.reconcileJoin(channelId);
+    if (!joined) throw new ChannelPendingError(channelId);
+    let body;
+    try {
+      body = await prepareAttachment(filePath, caption, channelId, this.sendDeps());
+    } catch (e) {
+      if (e.code === "ENOENT" || e.code === "EACCES" || e.code === "ENOTDIR" || e.code === "EISDIR") {
+        throw new InvalidPathError(filePath, e);
+      }
+      throw e;
+    }
+    const id = crypto.randomUUID();
+    const sendStart = performance.now();
+    await sendWithSelfHeal(
+      this.provider,
+      channelId,
+      (epoch) => this.latency.time(
+        "send.encrypt",
+        () => buildOutboundEnvelope({
+          custody: this.custody,
+          groupKey: this.provider,
+          messageId: id,
+          channelId,
+          enclaveId: this.cfg.enclaveId,
+          senderId: this.cfg.identityId,
+          senderType: "agent",
+          type: "artifact_share",
+          bodyPlaintext: JSON.stringify(body),
+          bindingId: "",
+          bindingVersion: "0.0.0",
+          agentSkillId: null,
+          epoch,
+          traceparent: ZERO_TRACEPARENT,
+          references: [],
+          stage5Outcome: "allow",
+          stage5Evaluators: []
+        })
+      ),
+      (envelope) => this.latency.time("send.publish", () => this.transport.publish(envelope))
+    );
+    this.latency.record("send.total", performance.now() - sendStart);
+    return { message_id: id, status: "sent" };
+  }
   async listChannels() {
     const url = `${this.cfg.apiBase}/api/v1/enclaves/${this.cfg.enclaveId}/channels?caller_identity_id=${encodeURIComponent(this.cfg.identityId)}`;
     const res = await this.fetchImpl(url, {
@@ -2995,6 +3160,42 @@ var BridgeAgent = class _BridgeAgent {
           new TextDecoder().decode(m.plaintext)
         );
         if (parsed.type && parsed.type !== "text") {
+          if (parsed.type === "artifact_share") {
+            try {
+              const senderName = this.freshRoster(m.channelId)?.get(m.envelope.sender_id)?.name;
+              const senderType = m.envelope.sender_type;
+              const senderIsAgent = senderType === "agent" ? true : senderType === "human" ? false : void 0;
+              const meta = await materializeAttachment(
+                parsed,
+                { attachmentsDir: this.attachmentsDirImpl, channelId: m.channelId, messageId: m.messageId },
+                {
+                  downloadBlob: this.downloadBlobImpl,
+                  decryptFile,
+                  computeFileDigest,
+                  base64ToBytes: base64ToBytes2,
+                  mkdirp: (d) => fsp.mkdir(d, { recursive: true }).then(() => void 0),
+                  writeFile: (p, data) => fsp.writeFile(p, data)
+                }
+              );
+              this.buffer.push({
+                channel_id: m.channelId,
+                message_id: m.messageId,
+                sender_id: m.envelope.sender_id,
+                text: typeof parsed.text === "string" ? parsed.text : "",
+                ts: m.receivedAt,
+                sender_name: senderName,
+                sender_is_agent: senderIsAgent,
+                attachments: [meta]
+              });
+              this.capBuffer();
+            } catch (e) {
+              this.failedAttachments++;
+              process.stderr.write(
+                `[bridge] attachment failed on ${m.messageId}: ${e.message}
+`
+              );
+            }
+          }
           acked.push(m.queueId);
           continue;
         }
@@ -3119,6 +3320,7 @@ var BridgeAgent = class _BridgeAgent {
       filtered_room: this.filteredRoomMessages,
       rate_limited: this.rateLimitedSends,
       permanently_skipped: this.provider.permanentlySkippedCount(),
+      failed_attachments: this.failedAttachments,
       uptime_s: this.startedAt ? Math.floor((Date.now() - this.startedAt) / 1e3) : 0,
       version: BRIDGE_VERSION
     };
@@ -3159,7 +3361,8 @@ var BridgeAgent = class _BridgeAgent {
       filteredRoomMessages: this.filteredRoomMessages,
       rateLimitedSends: this.rateLimitedSends,
       permanentlySkipped: this.provider.permanentlySkippedCount(),
-      welcomeRequestsSent: this.welcomeRequestsSent
+      welcomeRequestsSent: this.welcomeRequestsSent,
+      failedAttachments: this.failedAttachments
     };
   }
   async close() {
@@ -3271,6 +3474,11 @@ var a2aSchema = z.object({
   kind: z.enum(["message", "task", "artifact"]),
   object: z.record(z.unknown())
 });
+var sendAttachmentSchema = z.object({
+  channel_id: z.string().min(1),
+  path: z.string().min(1),
+  caption: z.string().optional()
+});
 var sendSchema = z.object({
   channel_id: z.string().min(1),
   text: z.string().optional(),
@@ -3365,6 +3573,12 @@ function createHttpServer(agent, opts) {
         const r = parsed.data.a2a ? await agent.sendA2A(parsed.data.channel_id, parsed.data.a2a, parsed.data.idempotency_key) : await agent.send(parsed.data.channel_id, parsed.data.text, parsed.data.idempotency_key);
         return json(res, 200, r);
       }
+      if (method === "POST" && path === "/v1/send-attachment") {
+        const parsed = sendAttachmentSchema.safeParse(JSON.parse(await readBody(req, OTHER_CAP)));
+        if (!parsed.success) return jsonError(res, "invalid_request", parsed.error.issues);
+        const r = await agent.sendAttachment(parsed.data.channel_id, parsed.data.path, parsed.data.caption);
+        return json(res, 200, r);
+      }
       if (method === "POST" && path === "/v1/status") {
         const parsed = statusSchema.safeParse(JSON.parse(await readBody(req, OTHER_CAP)));
         if (!parsed.success) return jsonError(res, "invalid_request", parsed.error.issues);
@@ -3414,6 +3628,7 @@ function createHttpServer(agent, opts) {
       }
       if (e instanceof ChannelPendingError) return jsonError(res, "channel_pending");
       if (e instanceof RateLimitedError) return jsonError(res, "rate_limited");
+      if (e instanceof InvalidPathError) return jsonError(res, "invalid_request", e.message);
       if (e instanceof SyntaxError) return jsonError(res, "invalid_json");
       process.stderr.write(`[bridge] request error: ${e?.message ?? e}
 `);
@@ -3628,21 +3843,21 @@ async function handleInbound(sock, agent, data, inflight) {
 
 // src/bin.ts
 import { readFileSync as readFileSync3, mkdirSync, writeFileSync as writeFileSync2, rmSync, existsSync as existsSync2, realpathSync } from "node:fs";
-import { join as join3, dirname as dirname4 } from "node:path";
+import { join as join4, dirname as dirname5 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir, userInfo } from "node:os";
 import { spawnSync } from "node:child_process";
 
 // src/service/install.ts
-import { dirname as dirname2 } from "node:path";
+import { dirname as dirname3 } from "node:path";
 
 // src/service/config.ts
-import { basename, extname, isAbsolute, resolve } from "node:path";
+import { basename as basename2, extname, isAbsolute, resolve } from "node:path";
 function slugify(s) {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
 }
 function deriveServiceConfig(input) {
-  const stem = input.label ?? basename(input.credentialPath, extname(input.credentialPath));
+  const stem = input.label ?? basename2(input.credentialPath, extname(input.credentialPath));
   const slug = slugify(stem);
   const cred = isAbsolute(input.credentialPath) ? input.credentialPath : resolve(input.credentialPath);
   const args2 = ["--credential", cred];
@@ -3718,7 +3933,7 @@ WantedBy=default.target
 var ServiceUnsupportedError = class extends Error {
 };
 function tokenHint(input) {
-  return `${dirname2(input.credentialPath)}/bridge-token`;
+  return `${dirname3(input.credentialPath)}/bridge-token`;
 }
 function requireOk(r, what) {
   if (r.status !== 0) throw new Error(`${what} failed (exit ${r.status})${r.stderr ? `: ${r.stderr.trim()}` : ""}`);
@@ -3726,8 +3941,8 @@ function requireOk(r, what) {
 function installService(input, deps) {
   const cfg = deriveServiceConfig(input);
   if (deps.platform === "darwin") {
-    deps.mkdirp(dirname2(cfg.plistPath));
-    deps.mkdirp(dirname2(cfg.logPath));
+    deps.mkdirp(dirname3(cfg.plistPath));
+    deps.mkdirp(dirname3(cfg.logPath));
     deps.writeFile(cfg.plistPath, renderLaunchdPlist(cfg));
     deps.run("launchctl", ["bootout", `gui/${cfg.uid}/${cfg.label}`]);
     requireOk(deps.run("launchctl", ["bootstrap", `gui/${cfg.uid}`, cfg.plistPath]), "launchctl bootstrap");
@@ -3736,7 +3951,7 @@ function installService(input, deps) {
     return { label: cfg.label, filePath: cfg.plistPath, logHint: cfg.logPath, tokenHint: tokenHint(input) };
   }
   if (deps.platform === "linux") {
-    deps.mkdirp(dirname2(cfg.unitPath));
+    deps.mkdirp(dirname3(cfg.unitPath));
     deps.writeFile(cfg.unitPath, renderSystemdUnit(cfg));
     deps.run("systemctl", ["--user", "daemon-reload"]);
     deps.run("loginctl", ["enable-linger", deps.user]);
@@ -3764,7 +3979,7 @@ function uninstallService(input, deps) {
 }
 
 // src/service/resolve-bin.ts
-import { join as join2, dirname as dirname3 } from "node:path";
+import { join as join3, dirname as dirname4 } from "node:path";
 import { createRequire } from "node:module";
 var GlobalInstallPermissionError = class extends Error {
   constructor(message) {
@@ -3789,7 +4004,7 @@ function resolveStableBinScript(input, deps) {
     if (deps.fileExists(input.binScript)) return input.binScript;
     throw new Error(`bin path does not exist and is not an npx cache path: ${input.binScript}`);
   }
-  const pkgRoot = dirname3(dirname3(input.binScript));
+  const pkgRoot = dirname4(dirname4(input.binScript));
   const inst = deps.run("npm", ["i", "-g", pkgRoot, "--install-links"]);
   if (inst.status !== 0) {
     if (/EACCES|permission denied/i.test(inst.stderr)) {
@@ -3802,7 +4017,7 @@ function resolveStableBinScript(input, deps) {
   }
   const root = deps.run("npm", ["root", "-g"]);
   if (root.status !== 0) throw new Error(`npm root -g failed (exit ${root.status})`);
-  const stable = join2(root.stdout.trim(), input.packageName, "dist", "bin.js");
+  const stable = join3(root.stdout.trim(), input.packageName, "dist", "bin.js");
   if (!deps.fileExists(stable)) throw new Error(`global install did not produce ${stable}`);
   return stable;
 }
@@ -3921,7 +4136,7 @@ async function main() {
 `);
     process.exit(1);
   }
-  const tokenFile = daemon.tokenFile ?? join3(dirname4(credentialPath), "bridge-token");
+  const tokenFile = daemon.tokenFile ?? join4(dirname5(credentialPath), "bridge-token");
   const token = resolveToken({ tokenFile, token: daemon.token });
   const agent = new BridgeAgent(cfg);
   await agent.start();

package/dist/bridge-agent.d.ts

@@ -1,6 +1,7 @@
 import { MlsGroupKeyProvider } from "@agentvault/connect-sdk-ts";
 import type { BridgeConfig } from "./config.js";
 import { LatencyRecorder } from "./latency.js";
+import type { AttachmentMeta } from "./attachments.js";
 export interface BridgeMessage {
     channel_id: string;
     message_id: string;
@@ -20,6 +21,12 @@ export interface BridgeMessage {
      * @mention filter reads (not recomputed differently).
      */
     sender_is_agent?: boolean;
+    /**
+     * Track 5: materialized attachment metadata for `artifact_share` messages.
+     * Each entry corresponds to one downloaded+decrypted file saved to disk.
+     * Undefined for plain `text` messages.
+     */
+    attachments?: AttachmentMeta[];
 }
 export interface BridgeAgentDeps {
     transport?: any;
@@ -27,6 +34,24 @@ export interface BridgeAgentDeps {
     fetchImpl?: typeof fetch;
     /** Injectable so tests can assert recorded stages; defaults to a fresh one. */
     latency?: LatencyRecorder;
+    /**
+     * Track 5: injectable blob downloader. Defaults to the fetch-based impl that
+     * GETs `${apiBase}/api/v1/attachments/<blobId>?caller_identity_id=<identityId>`
+     * with Bearer auth. Override in tests to avoid real HTTP.
+     */
+    downloadBlob?: (blobId: string) => Promise<Uint8Array>;
+    /**
+     * Track 5: injectable blob uploader. Defaults to the fetch-based impl that
+     * POSTs ciphertext to `${apiBase}/api/v1/attachments?channel_id=<id>&caller_identity_id=<id>`
+     * with Bearer auth and returns the server-assigned blobId. Override in tests to avoid real HTTP.
+     */
+    uploadBlob?: (ciphertext: Uint8Array, channelId: string) => Promise<string>;
+    /**
+     * Track 5: override the directory where received attachments are saved.
+     * Defaults to `join(dirname(cfg.storePath), "attachments")`. Override in
+     * tests that use `:memory:` as the store path.
+     */
+    attachmentsDir?: string;
     /**
      * Phase 1 item 4 (ADR-0002): hard cap on the in-memory inbound buffer. A
      * consumer that never drains (agent offline, no /v1/events poller) must not
@@ -62,6 +87,10 @@ export declare class RateLimitedError extends Error {
     readonly retryAfterMs: number;
     constructor(channelId: string, retryAfterMs: number);
 }
+export declare class InvalidPathError extends Error {
+    readonly filePath: string;
+    constructor(filePath: string, cause?: unknown);
+}
 export declare const BRIDGE_VERSION = "0.0.0";
 export declare class BridgeAgent {
     private readonly cfg;
@@ -106,6 +135,12 @@ export declare class BridgeAgent {
     private rateLimitedSends;
     /** Cumulative count of requestWelcome calls fired for no-local-state deliveries (self-heal signal). */
     private welcomeRequestsSent;
+    /**
+     * Track 5: cumulative count of artifact_share messages where download/decrypt/digest
+     * failed. Fail-soft — failures are acked (no redelivery), logged to stderr, and this
+     * counter is incremented. Surfaced on health()/metrics().
+     */
+    private failedAttachments;
     /** Per-channel timestamp of last requestWelcome call, for cooldown enforcement. */
     private readonly lastWelcomeRequest;
     /** Minimum gap between requestWelcome calls for the same channel (2 minutes). */
@@ -118,6 +153,12 @@ export declare class BridgeAgent {
     private startedAt;
     private readonly store;
     private readonly latency;
+    /** Track 5: injectable blob download fn (default: fetch-based). */
+    private readonly downloadBlobImpl;
+    /** Track 5: injectable blob upload fn (default: fetch-based). */
+    private readonly uploadBlobImpl;
+    /** Track 5: directory where received attachments are saved. */
+    private readonly attachmentsDirImpl;
     constructor(cfg: BridgeConfig, deps?: BridgeAgentDeps);
     /**
      * Enforce the inbound-buffer cap with a DROP-OLDEST policy.
@@ -151,6 +192,11 @@ export declare class BridgeAgent {
         message_id: string;
         status: "sent";
     }>;
+    private sendDeps;
+    sendAttachment(channelId: string, filePath: string, caption?: string): Promise<{
+        message_id: string;
+        status: "sent";
+    }>;
     listChannels(): Promise<Array<{
         channel_id: string;
         name: string | null;
@@ -215,6 +261,8 @@ export declare class BridgeAgent {
         rate_limited: number;
         /** Cumulative inbound rows acked-and-dropped because they were provably past-epoch undecryptable (forward-secrecy secret gone). */
         permanently_skipped: number;
+        /** Track 5: cumulative artifact_share messages where download/decrypt/digest failed (fail-soft — acked, no redeliver). */
+        failed_attachments: number;
         uptime_s: number;
         version: string;
     };
@@ -254,6 +302,8 @@ export declare class BridgeAgent {
         rateLimitedSends: number;
         permanentlySkipped: number;
         welcomeRequestsSent: number;
+        /** Track 5: cumulative artifact_share failures (download/decrypt/digest). */
+        failedAttachments: number;
     };
     close(): Promise<void>;
 }

package/dist/index.js

@@ -2367,6 +2367,11 @@ var SqliteMlsStateStore = class {
   }
 };
 
+// src/bridge-agent.ts
+import { decryptFile, encryptFile, computeFileDigest, base64ToBytes as base64ToBytes2, bytesToBase64 as bytesToBase642 } from "@agentvault/crypto";
+import { promises as fsp } from "node:fs";
+import { join, dirname } from "node:path";
+
 // src/latency.ts
 var DEFAULT_CAPACITY = 1024;
 function round(n) {
@@ -2514,6 +2519,74 @@ var TokenBucketFloor = class {
   }
 };
 
+// src/attachments.ts
+import { basename } from "node:path";
+function sanitizeFilename(name, fallback) {
+  const base = basename(name ?? "");
+  const cleaned = base.replace(/[/\\]/g, "").replace(/^\.+$/, "");
+  return cleaned.length > 0 ? cleaned : fallback;
+}
+var MIME_BY_EXT = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  pdf: "application/pdf",
+  txt: "text/plain",
+  md: "text/markdown",
+  json: "application/json",
+  csv: "text/csv",
+  html: "text/html",
+  mp4: "video/mp4",
+  mp3: "audio/mpeg",
+  zip: "application/zip",
+  wav: "audio/wav"
+};
+function mimeForName(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot < 0 || dot === name.length - 1) return "application/octet-stream";
+  return MIME_BY_EXT[name.slice(dot + 1).toLowerCase()] ?? "application/octet-stream";
+}
+async function prepareAttachment(filePath, caption, channelId, deps) {
+  const bytes = await deps.readFile(filePath);
+  const name = basename(filePath);
+  const { encryptedData, fileKey, fileNonce, digest } = deps.encryptFile(bytes);
+  const blobId = await deps.uploadBlob(encryptedData, channelId);
+  const body = {
+    v: 1,
+    type: "artifact_share",
+    name,
+    mime: mimeForName(name),
+    size: bytes.length,
+    blobId,
+    fileKey: deps.bytesToBase64(fileKey),
+    fileNonce: deps.bytesToBase64(fileNonce),
+    digest
+  };
+  if (caption) body.text = caption;
+  return body;
+}
+async function materializeAttachment(body, ctx, deps) {
+  const ciphertext = await deps.downloadBlob(body.blobId);
+  const sha2565 = deps.computeFileDigest(ciphertext);
+  if (sha2565 !== body.digest) {
+    throw new Error(`attachment digest mismatch for blob ${body.blobId}`);
+  }
+  const plain = deps.decryptFile(
+    ciphertext,
+    deps.base64ToBytes(body.fileKey),
+    deps.base64ToBytes(body.fileNonce)
+  );
+  const safeName = sanitizeFilename(body.name, ctx.messageId);
+  const dir = `${ctx.attachmentsDir}/${ctx.channelId}`;
+  const path = `${dir}/${ctx.messageId}-${safeName}`;
+  await deps.mkdirp(dir);
+  await deps.writeFile(path, plain);
+  return { filename: safeName, mime: body.mime, size: plain.length, path, sha256: sha2565 };
+}
+
 // src/bridge-agent.ts
 var DEFAULT_MAX_BUFFER = 1e3;
 var CHANNEL_META_TTL_MS = 5 * 6e4;
@@ -2534,6 +2607,14 @@ var RateLimitedError = class extends Error {
     this.name = "RateLimitedError";
   }
 };
+var InvalidPathError = class extends Error {
+  constructor(filePath, cause) {
+    super(`cannot read attachment file: ${filePath}`);
+    this.filePath = filePath;
+    this.name = "InvalidPathError";
+    if (cause !== void 0) this.cause = cause;
+  }
+};
 var BRIDGE_VERSION = "0.0.0";
 function hexToBytes2(h) {
   return new Uint8Array(Buffer.from(h, "hex"));
@@ -2572,6 +2653,25 @@ var BridgeAgent = class _BridgeAgent {
       capacity: cfg.rateLimitCapacity ?? 20,
       refillPerMinute: cfg.rateLimitRefillPerMinute ?? 20
     });
+    const self = this;
+    this.downloadBlobImpl = deps.downloadBlob ?? async function(blobId) {
+      const url = `${cfg.apiBase}/api/v1/attachments/${encodeURIComponent(blobId)}?caller_identity_id=${encodeURIComponent(cfg.identityId)}`;
+      const res = await self.fetchImpl(url, { headers: { authorization: `Bearer ${cfg.apiKey}` } });
+      if (!res.ok) throw new Error(`download blob failed: ${res.status}`);
+      return new Uint8Array(await res.arrayBuffer());
+    };
+    this.uploadBlobImpl = deps.uploadBlob ?? async function(ciphertext, channelId) {
+      const url = `${cfg.apiBase}/api/v1/attachments?channel_id=${encodeURIComponent(channelId)}&caller_identity_id=${encodeURIComponent(cfg.identityId)}`;
+      const res = await self.fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/octet-stream", authorization: `Bearer ${cfg.apiKey}` },
+        body: ciphertext
+      });
+      if (!res.ok) throw new Error(`upload blob failed: ${res.status}`);
+      const j = await res.json();
+      return String(j.attachment_id);
+    };
+    this.attachmentsDirImpl = deps.attachmentsDir ?? join(dirname(cfg.storePath), "attachments");
   }
   transport;
   provider;
@@ -2615,6 +2715,12 @@ var BridgeAgent = class _BridgeAgent {
   rateLimitedSends = 0;
   /** Cumulative count of requestWelcome calls fired for no-local-state deliveries (self-heal signal). */
   welcomeRequestsSent = 0;
+  /**
+   * Track 5: cumulative count of artifact_share messages where download/decrypt/digest
+   * failed. Fail-soft — failures are acked (no redelivery), logged to stderr, and this
+   * counter is incremented. Surfaced on health()/metrics().
+   */
+  failedAttachments = 0;
   /** Per-channel timestamp of last requestWelcome call, for cooldown enforcement. */
   lastWelcomeRequest = /* @__PURE__ */ new Map();
   /** Minimum gap between requestWelcome calls for the same channel (2 minutes). */
@@ -2627,6 +2733,12 @@ var BridgeAgent = class _BridgeAgent {
   startedAt = 0;
   store;
   latency;
+  /** Track 5: injectable blob download fn (default: fetch-based). */
+  downloadBlobImpl;
+  /** Track 5: injectable blob upload fn (default: fetch-based). */
+  uploadBlobImpl;
+  /** Track 5: directory where received attachments are saved. */
+  attachmentsDirImpl;
   /**
    * Enforce the inbound-buffer cap with a DROP-OLDEST policy.
    *
@@ -2747,6 +2859,59 @@ var BridgeAgent = class _BridgeAgent {
     this.latency.record("send.total", performance.now() - sendStart);
     return { message_id: id, status: "sent" };
   }
+  sendDeps() {
+    return {
+      uploadBlob: (ciphertext, channelId) => this.uploadBlobImpl(ciphertext, channelId),
+      encryptFile,
+      bytesToBase64: bytesToBase642,
+      readFile: (p) => fsp.readFile(p).then((b) => new Uint8Array(b))
+    };
+  }
+  async sendAttachment(channelId, filePath, caption) {
+    this.enforceRateFloor("attachment", channelId);
+    const joined = await this.reconcileJoin(channelId);
+    if (!joined) throw new ChannelPendingError(channelId);
+    let body;
+    try {
+      body = await prepareAttachment(filePath, caption, channelId, this.sendDeps());
+    } catch (e) {
+      if (e.code === "ENOENT" || e.code === "EACCES" || e.code === "ENOTDIR" || e.code === "EISDIR") {
+        throw new InvalidPathError(filePath, e);
+      }
+      throw e;
+    }
+    const id = crypto.randomUUID();
+    const sendStart = performance.now();
+    await sendWithSelfHeal(
+      this.provider,
+      channelId,
+      (epoch) => this.latency.time(
+        "send.encrypt",
+        () => buildOutboundEnvelope({
+          custody: this.custody,
+          groupKey: this.provider,
+          messageId: id,
+          channelId,
+          enclaveId: this.cfg.enclaveId,
+          senderId: this.cfg.identityId,
+          senderType: "agent",
+          type: "artifact_share",
+          bodyPlaintext: JSON.stringify(body),
+          bindingId: "",
+          bindingVersion: "0.0.0",
+          agentSkillId: null,
+          epoch,
+          traceparent: ZERO_TRACEPARENT,
+          references: [],
+          stage5Outcome: "allow",
+          stage5Evaluators: []
+        })
+      ),
+      (envelope) => this.latency.time("send.publish", () => this.transport.publish(envelope))
+    );
+    this.latency.record("send.total", performance.now() - sendStart);
+    return { message_id: id, status: "sent" };
+  }
   async listChannels() {
     const url = `${this.cfg.apiBase}/api/v1/enclaves/${this.cfg.enclaveId}/channels?caller_identity_id=${encodeURIComponent(this.cfg.identityId)}`;
     const res = await this.fetchImpl(url, {
@@ -2923,6 +3088,42 @@ var BridgeAgent = class _BridgeAgent {
           new TextDecoder().decode(m.plaintext)
         );
         if (parsed.type && parsed.type !== "text") {
+          if (parsed.type === "artifact_share") {
+            try {
+              const senderName = this.freshRoster(m.channelId)?.get(m.envelope.sender_id)?.name;
+              const senderType = m.envelope.sender_type;
+              const senderIsAgent = senderType === "agent" ? true : senderType === "human" ? false : void 0;
+              const meta = await materializeAttachment(
+                parsed,
+                { attachmentsDir: this.attachmentsDirImpl, channelId: m.channelId, messageId: m.messageId },
+                {
+                  downloadBlob: this.downloadBlobImpl,
+                  decryptFile,
+                  computeFileDigest,
+                  base64ToBytes: base64ToBytes2,
+                  mkdirp: (d) => fsp.mkdir(d, { recursive: true }).then(() => void 0),
+                  writeFile: (p, data) => fsp.writeFile(p, data)
+                }
+              );
+              this.buffer.push({
+                channel_id: m.channelId,
+                message_id: m.messageId,
+                sender_id: m.envelope.sender_id,
+                text: typeof parsed.text === "string" ? parsed.text : "",
+                ts: m.receivedAt,
+                sender_name: senderName,
+                sender_is_agent: senderIsAgent,
+                attachments: [meta]
+              });
+              this.capBuffer();
+            } catch (e) {
+              this.failedAttachments++;
+              process.stderr.write(
+                `[bridge] attachment failed on ${m.messageId}: ${e.message}
+`
+              );
+            }
+          }
           acked.push(m.queueId);
           continue;
         }
@@ -3047,6 +3248,7 @@ var BridgeAgent = class _BridgeAgent {
       filtered_room: this.filteredRoomMessages,
       rate_limited: this.rateLimitedSends,
       permanently_skipped: this.provider.permanentlySkippedCount(),
+      failed_attachments: this.failedAttachments,
       uptime_s: this.startedAt ? Math.floor((Date.now() - this.startedAt) / 1e3) : 0,
       version: BRIDGE_VERSION
     };
@@ -3087,7 +3289,8 @@ var BridgeAgent = class _BridgeAgent {
       filteredRoomMessages: this.filteredRoomMessages,
       rateLimitedSends: this.rateLimitedSends,
       permanentlySkipped: this.provider.permanentlySkippedCount(),
-      welcomeRequestsSent: this.welcomeRequestsSent
+      welcomeRequestsSent: this.welcomeRequestsSent,
+      failedAttachments: this.failedAttachments
     };
   }
   async close() {
@@ -3099,7 +3302,7 @@ var BridgeAgent = class _BridgeAgent {
 
 // src/config.ts
 import { readFileSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname as dirname2, join as join2 } from "node:path";
 var REQUIRED = ["api_key", "identity_id", "device_id", "signing_private_key", "enclave_id", "api_base"];
 function loadConfig(opts) {
   const raw = readFileSync(opts.credentialPath, "utf8");
@@ -3116,7 +3319,7 @@ function loadConfig(opts) {
     throw new Error("credential file is not valid JSON");
   }
   for (const k of REQUIRED) if (typeof json2[k] !== "string" || !json2[k]) throw new Error(`credential file missing required field: ${k}`);
-  const storePath = opts.storePath ?? join(dirname(opts.credentialPath), "bridge-state.db");
+  const storePath = opts.storePath ?? join2(dirname2(opts.credentialPath), "bridge-state.db");
   const agentName = typeof json2.agent_name === "string" && json2.agent_name ? json2.agent_name : typeof json2.display_name === "string" && json2.display_name ? json2.display_name : void 0;
   const rateLimitCapacity = typeof json2.rate_limit_capacity === "number" ? json2.rate_limit_capacity : 20;
   const rateLimitRefillPerMinute = typeof json2.rate_limit_refill_per_minute === "number" ? json2.rate_limit_refill_per_minute : 20;
@@ -3269,6 +3472,11 @@ var a2aSchema = z.object({
   kind: z.enum(["message", "task", "artifact"]),
   object: z.record(z.unknown())
 });
+var sendAttachmentSchema = z.object({
+  channel_id: z.string().min(1),
+  path: z.string().min(1),
+  caption: z.string().optional()
+});
 var sendSchema = z.object({
   channel_id: z.string().min(1),
   text: z.string().optional(),
@@ -3363,6 +3571,12 @@ function createHttpServer(agent, opts) {
         const r = parsed.data.a2a ? await agent.sendA2A(parsed.data.channel_id, parsed.data.a2a, parsed.data.idempotency_key) : await agent.send(parsed.data.channel_id, parsed.data.text, parsed.data.idempotency_key);
         return json(res, 200, r);
       }
+      if (method === "POST" && path === "/v1/send-attachment") {
+        const parsed = sendAttachmentSchema.safeParse(JSON.parse(await readBody(req, OTHER_CAP)));
+        if (!parsed.success) return jsonError(res, "invalid_request", parsed.error.issues);
+        const r = await agent.sendAttachment(parsed.data.channel_id, parsed.data.path, parsed.data.caption);
+        return json(res, 200, r);
+      }
       if (method === "POST" && path === "/v1/status") {
         const parsed = statusSchema.safeParse(JSON.parse(await readBody(req, OTHER_CAP)));
         if (!parsed.success) return jsonError(res, "invalid_request", parsed.error.issues);
@@ -3412,6 +3626,7 @@ function createHttpServer(agent, opts) {
       }
       if (e instanceof ChannelPendingError) return jsonError(res, "channel_pending");
       if (e instanceof RateLimitedError) return jsonError(res, "rate_limited");
+      if (e instanceof InvalidPathError) return jsonError(res, "invalid_request", e.message);
       if (e instanceof SyntaxError) return jsonError(res, "invalid_json");
       process.stderr.write(`[bridge] request error: ${e?.message ?? e}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-bridge",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",