@securecoms/agent-bridge 0.11.0 → 0.11.2

package/dist/latency.js

@@ -0,0 +1,87 @@
+// latency.ts — lightweight per-stage latency recorder for the agent-bridge.
+//
+// Captures the SecureComs MESSAGE-ENVELOPE cost (MLS encrypt, relay publish,
+// decrypt, receive cycle) so we can report real p50/p95/p99 SEPARATE from the
+// agent's LLM time. Deliberately dependency-free and bounded: each stage keeps
+// a fixed-size ring buffer of recent samples and percentiles are computed on
+// demand from a sorted copy. Off the hot path beyond a single array write.
+//
+// This is NOT a metrics-pipeline replacement; it is a self-contained, loopback
+// -exposed snapshot (`/v1/metrics`) for profiling + load tests. Per-stage
+// timings are monotonic (performance.now) and local — true cross-process
+// end-to-end (sender-publish → recipient-decrypt) needs clock-synced
+// correlation by message id and is a follow-up.
+const DEFAULT_CAPACITY = 1024;
+function round(n) {
+    // Two-decimal ms is plenty; avoids float noise in the JSON snapshot.
+    return Math.round(n * 100) / 100;
+}
+/** Nearest-rank percentile (1-indexed ceil) over an ascending-sorted array. */
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const rank = Math.ceil((p / 100) * sorted.length);
+    const idx = Math.min(Math.max(rank, 1), sorted.length) - 1;
+    return sorted[idx];
+}
+export class LatencyRecorder {
+    capacity;
+    // Per-stage ring buffer of recent samples (ms).
+    buffers = new Map();
+    // Write cursor per stage (for the ring buffer wrap).
+    cursors = new Map();
+    constructor(opts = {}) {
+        this.capacity = opts.capacity ?? DEFAULT_CAPACITY;
+    }
+    /** Record a single sample (ms) for a stage. O(1). */
+    record(stage, ms) {
+        let buf = this.buffers.get(stage);
+        if (!buf) {
+            buf = [];
+            this.buffers.set(stage, buf);
+            this.cursors.set(stage, 0);
+        }
+        if (buf.length < this.capacity) {
+            buf.push(ms);
+        }
+        else {
+            // Ring-buffer overwrite of the oldest slot.
+            const cur = this.cursors.get(stage) ?? 0;
+            buf[cur] = ms;
+            this.cursors.set(stage, (cur + 1) % this.capacity);
+        }
+    }
+    /**
+     * Time an async fn, record its elapsed wall time under `stage`, return its
+     * value. Records even when the fn throws (the failure still consumed time),
+     * then re-throws — so a thrown error never loses the timing sample.
+     */
+    async time(stage, fn) {
+        const start = performance.now();
+        try {
+            return await fn();
+        }
+        finally {
+            this.record(stage, performance.now() - start);
+        }
+    }
+    /** Percentile snapshot per stage. Rounded to 2 decimals (ms). */
+    snapshot() {
+        const out = {};
+        for (const [stage, buf] of this.buffers) {
+            if (buf.length === 0)
+                continue;
+            const sorted = [...buf].sort((a, b) => a - b);
+            const sum = sorted.reduce((acc, n) => acc + n, 0);
+            out[stage] = {
+                count: sorted.length,
+                p50: round(percentile(sorted, 50)),
+                p95: round(percentile(sorted, 95)),
+                p99: round(percentile(sorted, 99)),
+                max: round(sorted[sorted.length - 1]),
+                mean: round(sum / sorted.length),
+            };
+        }
+        return out;
+    }
+}

package/dist/rate-limit.js

@@ -0,0 +1,56 @@
+// Per-channel token-bucket safety floor for the SecureComs agent bridge.
+//
+// A lazy-refill token bucket: tokens regenerate based on elapsed wall-clock time
+// at each read, so there is no timer/interval. The clock is injectable for
+// deterministic tests. State is per-key; an unseen key starts full.
+//
+// `capacity <= 0` disables the floor entirely (tryConsume always allows),
+// mirroring how `maxBuffer <= 0` disables the bridge's buffer cap.
+export class TokenBucketFloor {
+    capacity;
+    refillPerMs;
+    now;
+    buckets = new Map();
+    constructor(opts) {
+        this.capacity = opts.capacity;
+        this.refillPerMs = opts.refillPerMinute / 60_000;
+        this.now = opts.now ?? Date.now;
+    }
+    refill(key) {
+        const t = this.now();
+        let b = this.buckets.get(key);
+        if (!b) {
+            b = { tokens: this.capacity, lastRefill: t };
+            this.buckets.set(key, b);
+            return b;
+        }
+        const elapsed = t - b.lastRefill;
+        if (elapsed > 0) {
+            b.tokens = Math.min(this.capacity, b.tokens + elapsed * this.refillPerMs);
+            b.lastRefill = t;
+        }
+        return b;
+    }
+    /** Consume one token. Returns true if allowed, false if the bucket is empty. */
+    tryConsume(key) {
+        if (this.capacity <= 0)
+            return true; // disabled
+        const b = this.refill(key);
+        if (b.tokens >= 1) {
+            b.tokens -= 1;
+            return true;
+        }
+        return false;
+    }
+    /** Milliseconds until one token is available (0 if already available). */
+    msUntilNextToken(key) {
+        if (this.capacity <= 0)
+            return 0;
+        const b = this.refill(key);
+        if (b.tokens >= 1)
+            return 0;
+        if (this.refillPerMs <= 0)
+            return Infinity;
+        return Math.ceil((1 - b.tokens) / this.refillPerMs);
+    }
+}

package/dist/service/config.js

@@ -0,0 +1,26 @@
+import { basename, extname, isAbsolute, resolve } from "node:path";
+function slugify(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
+}
+export function deriveServiceConfig(input) {
+    const stem = input.label ?? basename(input.credentialPath, extname(input.credentialPath));
+    const slug = slugify(stem);
+    const cred = isAbsolute(input.credentialPath) ? input.credentialPath : resolve(input.credentialPath);
+    const args = ["--credential", cred];
+    if (input.storePath)
+        args.push("--store", isAbsolute(input.storePath) ? input.storePath : resolve(input.storePath));
+    if (input.port != null)
+        args.push("--port", String(input.port));
+    return {
+        slug,
+        label: `com.securecoms.bridge.${slug}`,
+        unitName: `securecoms-bridge-${slug}`,
+        args,
+        execPath: input.execPath,
+        binScript: input.binScript,
+        uid: input.uid,
+        plistPath: `${input.home}/Library/LaunchAgents/com.securecoms.bridge.${slug}.plist`,
+        unitPath: `${input.home}/.config/systemd/user/securecoms-bridge-${slug}.service`,
+        logPath: `${input.home}/Library/Logs/securecoms-bridge-${slug}.log`,
+    };
+}

package/dist/service/install.js

@@ -0,0 +1,60 @@
+import { dirname } from "node:path";
+import { deriveServiceConfig } from "./config.js";
+import { renderLaunchdPlist } from "./launchd.js";
+import { renderSystemdUnit } from "./systemd.js";
+export class ServiceUnsupportedError extends Error {
+}
+function tokenHint(input) {
+    return `${dirname(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()}` : ""}`);
+}
+export function installService(input, deps) {
+    const cfg = deriveServiceConfig(input);
+    if (deps.platform === "darwin") {
+        deps.mkdirp(dirname(cfg.plistPath));
+        deps.mkdirp(dirname(cfg.logPath));
+        deps.writeFile(cfg.plistPath, renderLaunchdPlist(cfg));
+        // Reload-safe: boot out any prior instance (ignore failure), then bootstrap + enable.
+        deps.run("launchctl", ["bootout", `gui/${cfg.uid}/${cfg.label}`]);
+        // bootstrap actually loads the service — its failure is the real install failure,
+        // so surface it (don't let a broken install look silently successful).
+        requireOk(deps.run("launchctl", ["bootstrap", `gui/${cfg.uid}`, cfg.plistPath]), "launchctl bootstrap");
+        deps.run("launchctl", ["enable", `gui/${cfg.uid}/${cfg.label}`]);
+        // Start (or restart) the service now so install doesn't wait for the next login.
+        // Mirrors the linux `enable --now`; kickstart -k re-launches if an old instance lingers.
+        requireOk(deps.run("launchctl", ["kickstart", "-k", `gui/${cfg.uid}/${cfg.label}`]), "launchctl kickstart");
+        return { label: cfg.label, filePath: cfg.plistPath, logHint: cfg.logPath, tokenHint: tokenHint(input) };
+    }
+    if (deps.platform === "linux") {
+        deps.mkdirp(dirname(cfg.unitPath));
+        deps.writeFile(cfg.unitPath, renderSystemdUnit(cfg));
+        deps.run("systemctl", ["--user", "daemon-reload"]);
+        deps.run("loginctl", ["enable-linger", deps.user]);
+        // enable --now is the load-bearing command (enable at login + start now); surface failure.
+        requireOk(deps.run("systemctl", ["--user", "enable", "--now", cfg.unitName]), "systemctl --user enable --now");
+        return { label: cfg.unitName, filePath: cfg.unitPath, logHint: `journalctl --user -u ${cfg.unitName} -f`, tokenHint: tokenHint(input) };
+    }
+    throw new ServiceUnsupportedError(`Service install isn't supported on ${deps.platform} yet. Run the agent in a terminal, or use a process manager.`);
+}
+export function uninstallService(input, deps) {
+    const cfg = deriveServiceConfig(input);
+    if (deps.platform === "darwin") {
+        const existed = deps.fileExists(cfg.plistPath);
+        deps.run("launchctl", ["bootout", `gui/${cfg.uid}/${cfg.label}`]);
+        if (existed)
+            deps.removeFile(cfg.plistPath);
+        return { removed: existed, filePath: cfg.plistPath };
+    }
+    if (deps.platform === "linux") {
+        const existed = deps.fileExists(cfg.unitPath);
+        deps.run("systemctl", ["--user", "disable", "--now", cfg.unitName]);
+        if (existed)
+            deps.removeFile(cfg.unitPath);
+        deps.run("systemctl", ["--user", "daemon-reload"]);
+        return { removed: existed, filePath: cfg.unitPath };
+    }
+    throw new ServiceUnsupportedError(`Service uninstall isn't supported on ${deps.platform} yet.`);
+}

package/dist/service/launchd.js

@@ -0,0 +1,30 @@
+/** A deterministic launchd LaunchAgent plist. ProgramArguments re-invoke the
+ *  running bin in run mode; KeepAlive restarts on crash, RunAtLoad starts at login. */
+export function renderLaunchdPlist(cfg) {
+    const argv = [cfg.execPath, cfg.binScript, ...cfg.args];
+    const programArgs = argv.map((a) => `    <string>${escapeXml(a)}</string>`).join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${cfg.label}</string>
+  <key>ProgramArguments</key>
+  <array>
+${programArgs}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(cfg.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(cfg.logPath)}</string>
+</dict>
+</plist>
+`;
+}
+function escapeXml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/dist/service/systemd.js

@@ -0,0 +1,25 @@
+/** Quotes a single systemd ExecStart token if it contains whitespace or a
+ *  double-quote character.  Tokens that are already safe pass through unchanged
+ *  so the common no-space case stays readable in the unit file. */
+function sdQuote(s) {
+    return s.includes(" ") || s.includes('"') ? `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"` : s;
+}
+/** A systemd --user unit. ExecStart re-invokes the running bin in run mode;
+ *  Restart=always supervises crashes. WantedBy=default.target enables at login. */
+export function renderSystemdUnit(cfg) {
+    const execStart = [cfg.execPath, cfg.binScript, ...cfg.args].map(sdQuote).join(" ");
+    return `[Unit]
+Description=SecureComs agent bridge (${cfg.slug})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${execStart}
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`;
+}

package/dist/sodium-ready.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Warm libsodium once per process, before any file-crypto call.
+ *
+ * ⛔⛔ THIS IS A DELEGATE, AND THE DELEGATION IS THE POINT. #331 moved the
+ * warm-up body and its memo to `packages/connect-sdk-ts/src/sodium-ready.ts`.
+ * A process that holds TWO independent readiness memos warms libsodium twice,
+ * and this bridge process holds one instance of the SDK module already. Keeping
+ * a second memo here would have made the two barriers count separately.
+ * ⛔ DO NOT restore a local memo, a local `generateEphemeralKeypair()` call, or
+ * a local `warming` variable. `src/sodium-ready.delegation.gate.test.ts` (G-E)
+ * counts the underlying warm-ups across BOTH barriers and reads 2 the moment
+ * one comes back.
+ *
+ * ⛔ THE NAME AND THE EXPORT STAY. `bridge-agent.ts:64` imports this symbol and
+ * `index.ts:7` re-exports it. Callers keep calling `ensureSodiumReady()` from
+ * this package; only where the body lives changed.
+ *
+ * The four findings this file carried before #331, and where each one now
+ * lives. None is deleted, because each still binds on something.
+ *
+ * ⛔ 1. THE DISCARDED KEYPAIR IS THE READINESS GATE, NOT DEAD CODE. ⇒ ITS
+ * SUBJECT MOVED. The `generateEphemeralKeypair()` await now sits in the SDK
+ * module named above, and the finding travels with it. It still says what it
+ * always said: `@agentvault/crypto` has no readiness contract on its entire
+ * synchronous surface, sixteen exported synchronous functions throw when
+ * libsodium's WASM heap is not yet initialised (`<member> is not a function`
+ * or `Cannot read properties of undefined (reading '_malloc')`), and
+ * `generateEphemeralKeypair` is the ASYNC export that awaits `sodium.ready`
+ * internally on the SAME module instance those synchronous exports use. ⛔ Do
+ * not "simplify" the delegate by inlining a keypair mint back here: that is a
+ * second warm-up, not a shortcut.
+ *
+ * ⛔ 2. DO NOT IMPORT `libsodium-wrappers-sumo` DIRECTLY HERE. ⇒ THIS ONE STILL
+ * BINDS ON THIS FILE, UNCHANGED. `esbuild.config.mjs:15` inlines every
+ * `@agentvault/connect-*` workspace package into the bridge bundle and that
+ * specifier is absent from the EXTERNAL list at `:3-8`, so esbuild would bundle
+ * a SECOND libsodium instance out of this file. The await would then warm a
+ * heap that nothing reads, and this fix would look correct and do nothing.
+ * ⚠️ The same inlining is why the delegate below is not a no-op in the shipped
+ * bundle: the SDK barrier is inlined into `dist/bin.js` exactly once, and this
+ * delegate points at that one copy.
+ *
+ * ⛔ 3. MEMOIZE THE PROMISE, NOT A BOOLEAN. ⇒ ITS SUBJECT MOVED. The memo is the
+ * SDK module's `warming`. Measured: under `if (warmed) return; await ...;
+ * warmed = true;` two CONCURRENT callers both run the body. The bridge has two
+ * independent entry points (send and receive), so that concurrency is real
+ * here, which is why the finding was written here first. It is pinned now by
+ * `packages/connect-sdk-ts/src/sodium-ready.memo.gate.test.ts` (G-C1) and by
+ * `src/sodium-ready.retry.test.ts:52-69` in this package, which reaches the SDK
+ * memo THROUGH this delegate.
+ *
+ * ⛔⛔ 4. THE `catch` THAT CLEARS THE MEMO IS NOT REDUNDANT. DO NOT DELETE IT.
+ * ⇒ ITS SUBJECT MOVED, AND THE CONSEQUENCE STILL LANDS IN THIS PACKAGE. A bare
+ * `warming ??= ...` in the SDK module would hold a REJECTED promise for the
+ * life of the process if the FIRST warm-up rejects (WASM instantiation failure,
+ * OOM, a corrupt binary), and every later prepareAttachment AND
+ * materializeAttachment IN THIS PACKAGE would then reject at its first
+ * statement, forever. ⛔ ON THE RECEIVE SIDE THAT IS SILENT: the ingest pump's
+ * fail-soft catch acks the message, increments the failed-attachment counter
+ * and logs, so one transient failure becomes a PERMANENT, PROCESS-WIDE
+ * attachment outage that never surfaces as a crash. The SDK module clears the
+ * memo on rejection and RETHROWS, so the first caller still sees the real
+ * failure. Pinned by `src/sodium-ready.retry.test.ts`, both halves.
+ */
+export declare function ensureSodiumReady(): Promise<void>;

package/dist/vault.d.ts

@@ -0,0 +1,96 @@
+/** Vault-crypto integrity failures: digest mismatch, DEK-wrap AEAD failure
+ *  (bad/dropped nonce, wrong KEK, spliced ciphertext), or "no wrap for any
+ *  generation we hold". Distinguished from generic REST/plumbing errors so
+ *  the HTTP boundary can map it to a dedicated error code (errors.ts
+ *  `vault_integrity_failed`) instead of a bare 500. */
+export declare class VaultIntegrityError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+export interface VaultWriteDeps {
+    exporterKekForGeneration: (gen: number) => Uint8Array;
+    currentGeneration: number;
+    createNode: (body: any) => Promise<{
+        node_id: string;
+        presign_post: {
+            url: string;
+            fields: Record<string, string>;
+        } | null;
+    }>;
+    putBlob: (presign: {
+        url: string;
+        fields: Record<string, string>;
+    }, ciphertext: Uint8Array) => Promise<void>;
+    commitNode: (nodeId: string) => Promise<{
+        status: string;
+    }>;
+}
+export declare function vaultWriteImpl(args: {
+    enclaveId: string;
+    nodeId: string;
+    name: string;
+    bytes: Uint8Array;
+    deps: VaultWriteDeps;
+}): Promise<{
+    node_id: string;
+}>;
+export interface VaultReadDeps {
+    exporterKekForGeneration: (gen: number) => Uint8Array;
+    getNodeForDownload: (nodeId: string) => Promise<{
+        download_url: string;
+        wraps: {
+            kek_generation: number;
+            wrapped_dek_b64: string;
+        }[];
+        content_hash: string | null;
+    }>;
+    getBlob: (url: string) => Promise<Uint8Array>;
+}
+export declare function vaultReadImpl(args: {
+    enclaveId: string;
+    nodeId: string;
+    deps: VaultReadDeps;
+}): Promise<Uint8Array>;
+export interface VaultListRawNode {
+    node_id: string;
+    kind: "folder" | "file";
+    parent_id: string | null;
+    enc_name_b64: string;
+    name_kek_generation: number;
+    ciphertext_len: number | null;
+    content_hash: string | null;
+}
+export interface VaultListNode {
+    node_id: string;
+    kind: "folder" | "file";
+    parent_id: string | null;
+    name: string;
+    size_bytes: number | null;
+    content_hash: string | null;
+}
+export interface VaultListDeps {
+    exporterKekForGeneration: (gen: number) => Uint8Array;
+    listNodes: (parentId: string | null) => Promise<{
+        nodes: VaultListRawNode[];
+    }>;
+}
+export declare function vaultListImpl(args: {
+    enclaveId: string;
+    parentId: string | null;
+    deps: VaultListDeps;
+}): Promise<VaultListNode[]>;
+export interface VaultDeleteDeps {
+    deleteNode: (nodeId: string) => Promise<{
+        deleted: string;
+        bytes_freed: number;
+    }>;
+}
+/** No crypto on delete (the server drops an opaque row) — kept as a thin
+ *  pass-through so BridgeAgent.vaultDelete has the same deps-injection shape
+ *  as write/read/list for testability and symmetry. */
+export declare function vaultDeleteImpl(args: {
+    nodeId: string;
+    deps: VaultDeleteDeps;
+}): Promise<{
+    deleted: string;
+    bytes_freed: number;
+}>;