@vellumai/vellum-gateway 0.10.3 → 0.10.4-staging.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.10.3",
+  "version": "0.10.4-staging.1",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/assistant-acl-write-drain.test.ts

@@ -0,0 +1,217 @@
+import { describe, test, expect } from "bun:test";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * DROP-safety guard: the gateway no longer WRITES the 8 ACL columns into the
+ * assistant DB (the gateway DB is the source of truth). This source scan fails
+ * if any assistantDbRun(/assistantDbExec( call site writes one of those columns,
+ * so the assistant-side DROP-COLUMN migration (302) stays safe.
+ *
+ * 8 ACL columns (gateway-owned, assistant-mirror dropped):
+ *   contacts.role, contacts.principal_id
+ *   contact_channels.{status, policy, verified_at, verified_via,
+ *                     revoked_reason, blocked_reason}
+ *
+ * RESIDUAL ASSISTANT-DB ACL READS still pending before the DROP:
+ *   - gateway/src/db/data-migrations/m0006-*: one-time reconcile reads assistant
+ *     ACL columns to seed the gateway DB.
+ *   - gateway/src/db/data-migrations/m0008-*: one-time backfill reads assistant
+ *     ACL columns.
+ *   These append-only one-time migrations are the ONLY remaining assistant-DB
+ *   ACL reads; they are retired at the assistant DROP-COLUMN migration (302).
+ *   The heal/seed reads (the channel-mirror heal and the inbound contact-seed
+ *   blocked-check) are drained — they read identity/info only and resolve ACL
+ *   from the gateway DB. The WRITE side is clean — this guard asserts that.
+ */
+
+// Deliberate, greppable exceptions. Must stay empty: every entry is an
+// assistant-DB ACL write that the DROP migration would break.
+const ACL_WRITE_ALLOWLIST: string[] = [];
+
+const ACL_COLUMNS = [
+  "role",
+  "principal_id",
+  "status",
+  "policy",
+  "verified_at",
+  "verified_via",
+  "revoked_reason",
+  "blocked_reason",
+] as const;
+
+// Info columns are assistant-owned and intentionally NOT flagged.
+const INFO_COLUMNS = ["last_seen_at", "interaction_count", "last_interaction"];
+
+const GATEWAY_SRC = join(import.meta.dirname!, "..");
+
+const EXCLUDED_DIRS = new Set(["__tests__", "data-migrations"]);
+const EXCLUDED_FILES = new Set(["assistant-db-proxy.ts"]);
+
+function collectSourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      if (EXCLUDED_DIRS.has(entry)) continue;
+      out.push(...collectSourceFiles(full));
+      continue;
+    }
+    if (!entry.endsWith(".ts")) continue;
+    if (entry.endsWith(".test.ts")) continue;
+    if (EXCLUDED_FILES.has(entry)) continue;
+    out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Extract the SQL string literal argument of an assistantDbRun/assistantDbExec
+ * call starting at `callStart`. Handles template literals and quoted strings
+ * spanning multiple lines. Returns the literal text (without delimiters) and
+ * the index just past it, or null if no string literal follows the open paren.
+ */
+function extractSqlArg(
+  src: string,
+  callStart: number,
+): { sql: string; end: number } | null {
+  const open = src.indexOf("(", callStart);
+  if (open === -1) return null;
+  let i = open + 1;
+  // Skip whitespace to the first argument.
+  while (i < src.length && /\s/.test(src[i])) i++;
+  const quote = src[i];
+  if (quote !== "`" && quote !== '"' && quote !== "'") return null;
+  const start = i + 1;
+  i = start;
+  while (i < src.length) {
+    if (src[i] === "\\") {
+      i += 2;
+      continue;
+    }
+    if (src[i] === quote) {
+      return { sql: src.slice(start, i), end: i + 1 };
+    }
+    i++;
+  }
+  return null;
+}
+
+// Only writes to these tables carry the dropped ACL columns. status/policy
+// etc. on other tables (channel_verification_sessions, *_ingress_invites) are
+// unrelated and must not be flagged.
+const ACL_TABLES = ["contacts", "contact_channels"];
+
+/** True if `sql` writes one of the 8 ACL columns into contacts/contact_channels. */
+function sqlWritesAclColumn(sql: string): boolean {
+  const normalized = sql.replace(/\s+/g, " ").toLowerCase();
+
+  // INSERT INTO <table> (col, col, ...) — an ACL column named for an ACL table.
+  const insertMatch = normalized.match(
+    /insert(?:\s+or\s+\w+)?\s+into\s+([a-z_]+)\s*\(([^)]*)\)/,
+  );
+  if (insertMatch && ACL_TABLES.includes(insertMatch[1])) {
+    const cols = insertMatch[2].split(",").map((c) => c.trim());
+    if (cols.some((c) => (ACL_COLUMNS as readonly string[]).includes(c))) {
+      return true;
+    }
+  }
+
+  // UPDATE <table> SET <acl_col> = — an ACL column assigned on an ACL table.
+  // Scope to the SET clause (up to WHERE) so a WHERE-clause ACL column isn't
+  // mistaken for an assignment.
+  const updateMatch = normalized.match(
+    /update\s+([a-z_]+)\s+set\s+(.*?)(?:\swhere\s|$)/,
+  );
+  if (updateMatch && ACL_TABLES.includes(updateMatch[1])) {
+    const setClause = updateMatch[2];
+    for (const col of ACL_COLUMNS) {
+      // Require an assignment to avoid flagging references, and word-boundary
+      // so principal_id doesn't match as a substring.
+      const re = new RegExp(`\\b${col}\\s*=`, "i");
+      if (re.test(setClause)) return true;
+    }
+  }
+
+  return false;
+}
+
+describe("assistant-DB ACL write drain guard", () => {
+  test("no assistantDbRun/assistantDbExec call writes a dropped ACL column", () => {
+    const files = collectSourceFiles(GATEWAY_SRC);
+    const violations: string[] = [];
+
+    const callRe = /assistantDb(?:Run|Exec)\s*\(/g;
+
+    for (const file of files) {
+      const src = readFileSync(file, "utf-8");
+      let m: RegExpExecArray | null;
+      callRe.lastIndex = 0;
+      while ((m = callRe.exec(src)) !== null) {
+        const arg = extractSqlArg(src, m.index);
+        if (!arg) continue;
+        if (sqlWritesAclColumn(arg.sql)) {
+          const rel = file.slice(GATEWAY_SRC.length + 1);
+          if (ACL_WRITE_ALLOWLIST.includes(rel)) continue;
+          violations.push(`${rel}: ${arg.sql.replace(/\s+/g, " ").trim()}`);
+        }
+      }
+    }
+
+    expect(violations).toEqual([]);
+  });
+
+  test("matcher flags ACL writes but not info-column or read SQL", () => {
+    // ACL writes (must be flagged)
+    expect(
+      sqlWritesAclColumn("UPDATE contacts SET role = ? WHERE id = ?"),
+    ).toBe(true);
+    expect(
+      sqlWritesAclColumn(
+        "UPDATE contact_channels SET status = ?, policy = ? WHERE id = ?",
+      ),
+    ).toBe(true);
+    expect(
+      sqlWritesAclColumn(
+        "INSERT INTO contacts (id, role, principal_id) VALUES (?, ?, ?)",
+      ),
+    ).toBe(true);
+
+    // Info-column writes (must NOT be flagged)
+    expect(
+      sqlWritesAclColumn(
+        "UPDATE contact_channels SET last_seen_at = ?, interaction_count = ? WHERE id = ?",
+      ),
+    ).toBe(false);
+    expect(
+      sqlWritesAclColumn(
+        "INSERT INTO contact_channels (id, last_seen_at, interaction_count, last_interaction) VALUES (?, ?, ?, ?)",
+      ),
+    ).toBe(false);
+
+    // Identity/info-only writes (must NOT be flagged)
+    expect(
+      sqlWritesAclColumn(
+        "UPDATE contacts SET display_name = ?, updated_at = ? WHERE id = ?",
+      ),
+    ).toBe(false);
+
+    // Reads referencing ACL columns (must NOT be flagged)
+    expect(
+      sqlWritesAclColumn(
+        "SELECT cc.status FROM contact_channels cc WHERE cc.status = 'active'",
+      ),
+    ).toBe(false);
+  });
+
+  test("allowlist is empty (no sanctioned ACL writes remain)", () => {
+    expect(ACL_WRITE_ALLOWLIST).toEqual([]);
+    // Guard that INFO_COLUMNS and ACL_COLUMNS stay disjoint.
+    expect(
+      INFO_COLUMNS.filter((c) =>
+        (ACL_COLUMNS as readonly string[]).includes(c),
+      ),
+    ).toEqual([]);
+  });
+});

package/src/__tests__/binding-helpers.test.ts

@@ -1,9 +1,8 @@
 /**
- * Tests for the guardian binding-helper lookups, which read the gateway DB
+ * Tests for the guardian binding helpers, which read and write the gateway DB
  * (source of truth for ACL). The gateway DB is a real (file-backed) DB seeded
- * per test; the assistant DB proxy is mocked and throws on read so the tests
- * prove the lookups never touch the assistant mirror. revokeExistingChannel
- * Guardian still writes both the assistant UPDATE and the gateway dual-write.
+ * per test; the assistant DB proxy is mocked and throws on every call so the
+ * tests prove the helpers never touch the assistant mirror.
  */
 
 import {
@@ -18,59 +17,14 @@ import {
 
 import "./test-preload.js";
 
-// Assistant DB proxy: reads throw (lookups must not touch it); the revoke
-// UPDATE is captured so we can assert the assistant mirror write still fires.
-// A simple in-memory `contact_channels` model lets us prove the id-keyed
-// update vs. the (type,address) logical-key fallback under id-divergence.
-const assistantRunCalls: { sql: string; bind?: unknown[] }[] = [];
-
-type AsstChannel = {
-  id: string;
-  type: string;
-  address: string;
-  status: string;
-  policy: string;
-};
-const asstChannels: AsstChannel[] = [];
-
-function seedAsstChannel(c: AsstChannel): void {
-  asstChannels.push(c);
-}
-
-let throwOnAsstRun = false;
-
+// Assistant DB proxy: every call throws so the tests prove the helpers read
+// and write only the gateway DB.
 mock.module("../db/assistant-db-proxy.js", () => ({
   assistantDbQuery: mock(async () => {
-    throw new Error("assistant DB read not expected in binding lookups");
+    throw new Error("assistant DB read not expected in binding helpers");
   }),
-  assistantDbRun: mock(async (sql: string, bind?: unknown[]) => {
-    assistantRunCalls.push({ sql, bind });
-    if (throwOnAsstRun) throw new Error("assistant DB proxy unavailable");
-    let changes = 0;
-    if (/WHERE id = \?/.test(sql)) {
-      const id = bind?.[1];
-      for (const ch of asstChannels) {
-        if (ch.id === id) {
-          ch.status = "revoked";
-          ch.policy = "deny";
-          changes++;
-        }
-      }
-    } else if (/WHERE type = \? AND address = \?/.test(sql)) {
-      const type = bind?.[1];
-      const address = bind?.[2];
-      for (const ch of asstChannels) {
-        if (
-          ch.type === type &&
-          ch.address.toLowerCase() === String(address).toLowerCase()
-        ) {
-          ch.status = "revoked";
-          ch.policy = "deny";
-          changes++;
-        }
-      }
-    }
-    return { changes, lastInsertRowid: 0 };
+  assistantDbRun: mock(async () => {
+    throw new Error("assistant DB write not expected in binding helpers");
   }),
   assistantDbExec: mock(async () => undefined),
 }));
@@ -96,8 +50,6 @@ beforeEach(() => {
   const db = getGatewayDb();
   db.delete(contactChannels).run();
   db.delete(contacts).run();
-  assistantRunCalls.length = 0;
-  asstChannels.length = 0;
 });
 
 afterAll(() => {
@@ -248,7 +200,7 @@ describe("resolveCanonicalPrincipal", () => {
 });
 
 describe("revokeExistingChannelGuardian", () => {
-  test("revokes the gateway channel and mirrors the write to the assistant DB", async () => {
+  test("revokes the active guardian channel in the gateway DB only", async () => {
     seedContact({ id: "g1", role: "guardian" });
     const chId = seedChannel({
       contactId: "g1",
@@ -256,18 +208,9 @@ describe("revokeExistingChannelGuardian", () => {
       address: "U_OWNER",
       status: "active",
     });
-    // Assistant row shares the same id — the id-keyed update matches.
-    seedAsstChannel({
-      id: chId,
-      type: "slack",
-      address: "U_OWNER",
-      status: "active",
-      policy: "allow",
-    });
 
     await revokeExistingChannelGuardian("slack");
 
-    // Gateway DB status flipped to revoked.
     const after = getGatewayDb()
       .select()
       .from(contactChannels)
@@ -275,79 +218,48 @@ describe("revokeExistingChannelGuardian", () => {
       .find((r) => r.id === chId);
     expect(after?.status).toBe("revoked");
     expect(after?.policy).toBe("deny");
-
-    // Assistant mirror revoked via the id-keyed update (no fallback needed).
-    expect(assistantRunCalls.length).toBe(1);
-    expect(assistantRunCalls[0]!.sql).toContain("WHERE id = ?");
-    expect(assistantRunCalls[0]!.bind).toContain(chId);
-    expect(asstChannels[0]!.status).toBe("revoked");
-    expect(asstChannels[0]!.policy).toBe("deny");
   });
 
-  test("revokes the assistant mirror by (type,address) when ids diverge", async () => {
+  test("revokes every active guardian channel for the type", async () => {
     seedContact({ id: "g1", role: "guardian" });
-    // Gateway guardian channel under id G.
-    seedChannel({
-      id: "G",
+    const a = seedChannel({
       contactId: "g1",
       type: "slack",
-      address: "U_OWNER",
+      address: "U_A",
       status: "active",
     });
-    // Assistant row shares (type,address) but sits under a DIFFERENT id A.
-    seedAsstChannel({
-      id: "A",
+    const b = seedChannel({
+      contactId: "g1",
       type: "slack",
-      address: "U_OWNER",
+      address: "U_B",
       status: "active",
-      policy: "allow",
     });
 
     await revokeExistingChannelGuardian("slack");
 
-    // id-keyed update missed; logical-key fallback revoked row A.
-    expect(asstChannels[0]!.status).toBe("revoked");
-    expect(asstChannels[0]!.policy).toBe("deny");
-    expect(assistantRunCalls.length).toBe(2);
-    expect(assistantRunCalls[0]!.sql).toContain("WHERE id = ?");
-    expect(assistantRunCalls[1]!.sql).toContain(
-      "WHERE type = ? AND address = ? COLLATE NOCASE",
-    );
-  });
-
-  test("no-ops (no writes) when no active guardian binding exists", async () => {
-    seedContact({ id: "g1", role: "guardian" });
-    seedChannel({ contactId: "g1", type: "slack", status: "revoked" });
-
-    await revokeExistingChannelGuardian("slack");
-
-    expect(assistantRunCalls.length).toBe(0);
+    const rows = getGatewayDb().select().from(contactChannels).all();
+    for (const id of [a, b]) {
+      const row = rows.find((r) => r.id === id);
+      expect(row?.status).toBe("revoked");
+      expect(row?.policy).toBe("deny");
+    }
   });
 
-  test("revokes the gateway row even when the assistant mirror fails", async () => {
+  test("no-ops when no active guardian binding exists", async () => {
     seedContact({ id: "g1", role: "guardian" });
     const chId = seedChannel({
       contactId: "g1",
       type: "slack",
-      address: "U_OWNER",
-      status: "active",
+      status: "revoked",
     });
 
-    throwOnAsstRun = true;
-    try {
-      // Must not throw — the best-effort mirror failure is swallowed.
-      await revokeExistingChannelGuardian("slack");
-    } finally {
-      throwOnAsstRun = false;
-    }
+    await revokeExistingChannelGuardian("slack");
 
-    // Gateway (source of truth) is revoked despite the mirror failure.
     const after = getGatewayDb()
       .select()
       .from(contactChannels)
       .all()
       .find((r) => r.id === chId);
     expect(after?.status).toBe("revoked");
-    expect(after?.policy).toBe("deny");
   });
 });

package/src/__tests__/contact-handlers.test.ts

@@ -233,26 +233,23 @@ describe("mark_channel_verified IPC handler", () => {
     ).rejects.toThrow(/not found/);
   });
 
-  test("inherits assistant-mirror behavior: a gateway-absent channel is mirrored then verified", async () => {
+  test("does not verify a channel absent from the gateway DB", async () => {
     seedAssistantContact("c1");
     seedAssistantChannel({ id: "ch1", contactId: "c1", status: "unverified" });
 
-    const res = (await markChannelVerifiedHandler({
-      contactChannelId: "ch1",
-    })) as { ok: boolean; didWrite: boolean; channel: { status: string } };
-
-    expect(res.ok).toBe(true);
-    expect(res.didWrite).toBe(true);
-    expect(res.channel.status).toBe("active");
+    // The channel lives only in the assistant DB. The gateway DB is the source
+    // of truth and does not heal from the assistant, so verification reports
+    // not found and nothing lands in the gateway DB.
+    await expect(
+      markChannelVerifiedHandler({ contactChannelId: "ch1" }),
+    ).rejects.toThrow(/not found/);
 
-    // Channel + parent contact were materialized into the gateway DB.
     const channelInGateway = getGatewayDb()
       .select()
       .from(contactChannels)
       .where(eq(contactChannels.id, "ch1"))
       .get();
-    expect(channelInGateway).toBeTruthy();
-    expect(channelInGateway!.contactId).toBe("c1");
+    expect(channelInGateway).toBeUndefined();
   });
 });
 

package/src/__tests__/contact-prompt-submit.test.ts

@@ -704,65 +704,7 @@ describe("handleContactPromptSubmit", () => {
     expect(ipcCall.body.error).toBeUndefined();
   });
 
-  test("guardian bootstrap-create — assistant mirror keeps role='guardian' even if create-mirror INSERT fails", async () => {
-    // No guardian seeded: handler mints one gateway-first. Make the
-    // bootstrap-create assistant mirror INSERT (role='guardian') fail, so the
-    // assistant DB has no guardian row when Phase-2 upsertContact runs. Without
-    // the role re-assert, that upsert would INSERT the id with role='contact',
-    // downgrading the guardian in the mirror.
-    const realDb = testAssistantDb!;
-    let failNextGuardianInsert = true;
-    testAssistantDb = {
-      prepare(sql: string) {
-        if (
-          failNextGuardianInsert &&
-          /INSERT INTO contacts/i.test(sql) &&
-          /'guardian'/.test(sql)
-        ) {
-          failNextGuardianInsert = false;
-          throw new Error("assistant DB guardian INSERT unavailable");
-        }
-        return realDb.prepare(sql);
-      },
-    } as unknown as Database;
-
-    let res: Response;
-    try {
-      res = await handleContactPromptSubmit(
-        makeRequest({
-          requestId: "req-boot-downgrade",
-          address: "+15552223333",
-          channelType: "phone",
-          role: "guardian",
-          displayName: "Mirror Guardian",
-        }),
-      );
-    } finally {
-      testAssistantDb = realDb;
-    }
-
-    expect(res.status).toBe(200);
-    const body = (await res.json()) as Record<string, unknown>;
-    expect(body.accepted).toBe(true);
-
-    // Gateway DB: guardian minted with role=guardian (authoritative).
-    const gwGuardians = getGatewayDb()
-      .select()
-      .from(gwContacts)
-      .where(eq(gwContacts.role, "guardian"))
-      .all();
-    expect(gwGuardians).toHaveLength(1);
-
-    // Assistant mirror: the role re-assert healed any Phase-2 downgrade — the
-    // row exists and is role='guardian', NOT 'contact'.
-    const asContacts = testAssistantDb!
-      .prepare(`SELECT role FROM contacts WHERE id = ?`)
-      .all(gwGuardians[0].id) as { role: string }[];
-    expect(asContacts).toHaveLength(1);
-    expect(asContacts[0].role).toBe("guardian");
-  });
-
-  test("guardian bootstrap-create — assistant mirror row is role='guardian'", async () => {
+  test("guardian bootstrap-create — gateway is authoritative; assistant mirror row exists without ACL role", async () => {
     const res = await handleContactPromptSubmit(
       makeRequest({
         requestId: "req-boot-role",
@@ -776,6 +718,7 @@ describe("handleContactPromptSubmit", () => {
     expect(res.status).toBe(200);
     expect(((await res.json()) as Record<string, unknown>).accepted).toBe(true);
 
+    // Gateway DB is the source of truth for the guardian ACL role.
     const gwGuardians = getGatewayDb()
       .select()
       .from(gwContacts)
@@ -783,11 +726,13 @@ describe("handleContactPromptSubmit", () => {
       .all();
     expect(gwGuardians).toHaveLength(1);
 
+    // Assistant mirror is an identity mirror only — the row exists but no ACL
+    // role is written through, so it falls back to the schema default 'contact'.
     const asContacts = testAssistantDb!
       .prepare(`SELECT role FROM contacts WHERE id = ?`)
       .all(gwGuardians[0].id) as { role: string }[];
     expect(asContacts).toHaveLength(1);
-    expect(asContacts[0].role).toBe("guardian");
+    expect(asContacts[0].role).toBe("contact");
   });
 
   test("non-guardian prompt — 500 + daemon error when channel can't be resolved (no empty channelId)", async () => {