@vellumai/vellum-gateway 0.7.0 → 0.7.2

package/src/verification/binding-helpers.ts

@@ -0,0 +1,107 @@
+/**
+ * Guardian binding helpers for gateway-owned verification.
+ *
+ * Provides lookup, conflict detection, and revocation of existing bindings.
+ * Binding creation uses the existing createGuardianBinding from
+ * gateway/src/auth/guardian-bootstrap.ts which already dual-writes.
+ *
+ * All assistant DB access is via raw SQL (assistantDbQuery/assistantDbRun).
+ */
+
+import { eq } from "drizzle-orm";
+
+import {
+  assistantDbQuery,
+  assistantDbRun,
+} from "../db/assistant-db-proxy.js";
+import { getGatewayDb } from "../db/connection.js";
+import { contactChannels as gwContactChannels } from "../db/schema.js";
+import { getLogger } from "../logger.js";
+
+const log = getLogger("verification-bindings");
+
+// ---------------------------------------------------------------------------
+// Lookup
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the existing active guardian binding for a channel.
+ */
+export async function getExistingGuardianBinding(
+  channel: string,
+): Promise<{ externalUserId: string | null } | null> {
+  const rows = await assistantDbQuery<{ externalUserId: string | null }>(
+    `SELECT cc.external_user_id AS externalUserId
+     FROM contacts c
+     JOIN contact_channels cc ON cc.contact_id = c.id
+     WHERE c.role = 'guardian' AND cc.type = ? AND cc.status = 'active'
+     LIMIT 1`,
+    [channel],
+  );
+  return rows[0] ?? null;
+}
+
+/**
+ * Resolve the canonical principal ID for the guardian.
+ * Looks up the vellum channel binding's principal; falls back to the provided ID.
+ */
+export async function resolveCanonicalPrincipal(
+  fallback: string,
+): Promise<string> {
+  const rows = await assistantDbQuery<{ principalId: string | null }>(
+    `SELECT c.principal_id AS principalId
+     FROM contacts c
+     JOIN contact_channels cc ON cc.contact_id = c.id
+     WHERE c.role = 'guardian' AND cc.type = 'vellum' AND cc.status = 'active'
+     LIMIT 1`,
+    [],
+  );
+  return rows[0]?.principalId ?? fallback;
+}
+
+// ---------------------------------------------------------------------------
+// Revocation (dual-write)
+// ---------------------------------------------------------------------------
+
+/**
+ * Revoke all existing active guardian bindings for a channel.
+ * Uses fetched IDs for the UPDATE to avoid TOCTOU races.
+ */
+export async function revokeExistingChannelGuardian(
+  channel: string,
+): Promise<void> {
+  const now = Date.now();
+
+  const revokedRows = await assistantDbQuery<{ id: string }>(
+    `SELECT cc.id
+     FROM contacts c
+     JOIN contact_channels cc ON cc.contact_id = c.id
+     WHERE c.role = 'guardian' AND cc.type = ? AND cc.status = 'active'`,
+    [channel],
+  );
+
+  if (revokedRows.length === 0) return;
+
+  const ids = revokedRows.map((r) => r.id);
+  const placeholders = ids.map(() => "?").join(", ");
+
+  await assistantDbRun(
+    `UPDATE contact_channels
+     SET status = 'revoked', policy = 'deny', updated_at = ?
+     WHERE id IN (${placeholders})`,
+    [now, ...ids],
+  );
+
+  // Gateway DB dual-write
+  try {
+    const gwDb = getGatewayDb();
+    for (const id of ids) {
+      gwDb.update(gwContactChannels)
+        .set({ status: "revoked", policy: "deny", updatedAt: now })
+        .where(eq(gwContactChannels.id, id))
+        .run();
+    }
+  } catch (gwErr) {
+    log.warn({ err: gwErr }, "Gateway DB revoke dual-write failed (best-effort)");
+  }
+}

package/src/verification/code-parsing.ts

@@ -0,0 +1,44 @@
+/**
+ * Verification code parsing for gateway-owned text-channel verification.
+ *
+ * Mirrors the assistant's parseGuardianVerifyCode from acl-enforcement.ts.
+ * Accepts a bare code as the entire message: 6-digit numeric OR 64-char hex.
+ * Strips surrounding mrkdwn formatting characters first so that codes
+ * pasted with bold/italic/code formatting are still recognized.
+ */
+
+import { createHash } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip Slack/Telegram mrkdwn formatting wrappers from raw message text.
+ */
+function stripMrkdwnFormatting(text: string): string {
+  return text.replace(/^[*_~`]+/, "").replace(/[*_~`]+$/, "");
+}
+
+/**
+ * Parse a verification code from message content.
+ *
+ * Returns the code string if the message is a bare 6-digit numeric or
+ * 64-char hex code, or undefined if the message is not a verification code.
+ */
+export function parseVerificationCode(content: string): string | undefined {
+  const stripped = stripMrkdwnFormatting(content.trim());
+  const match = stripped.match(/^([0-9a-fA-F]{64}|\d{6})$/);
+  return match?.[1];
+}
+
+// ---------------------------------------------------------------------------
+// Hashing
+// ---------------------------------------------------------------------------
+
+/**
+ * Hash a verification secret using SHA-256 (matches the assistant's scheme).
+ */
+export function hashVerificationSecret(secret: string): string {
+  return createHash("sha256").update(secret).digest("hex");
+}

package/src/verification/contact-helpers.ts

@@ -0,0 +1,342 @@
+/**
+ * Contact upsert/lookup helpers for gateway-owned verification.
+ *
+ * All operations go through assistantDbQuery/assistantDbRun (raw SQL via
+ * IPC proxy). No IPC routes are used — only the direct SQL executor.
+ *
+ * These helpers cover the subset of contact operations needed by the
+ * verification intercept flow. They are intentionally simpler than the
+ * assistant's full upsertContact/syncChannels — we only need to upsert
+ * a single contact+channel for the verifying user.
+ */
+
+import { existsSync } from "node:fs";
+
+import { eq } from "drizzle-orm";
+
+import {
+  assistantDbQuery,
+  assistantDbRun,
+} from "../db/assistant-db-proxy.js";
+import { getGatewayDb } from "../db/connection.js";
+import { contactChannels as gwContactChannels, contacts as gwContacts } from "../db/schema.js";
+import { getLogger } from "../logger.js";
+import { resolveIpcSocketPath } from "../ipc/socket-path.js";
+import { canonicalizeInboundIdentity } from "./identity.js";
+
+const log = getLogger("verification-contacts");
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ContactChannelRow {
+  channelId: string;
+  contactId: string;
+  externalUserId: string | null;
+  externalChatId: string | null;
+  displayName: string | null;
+  status: string;
+}
+
+// ---------------------------------------------------------------------------
+// Lookup
+// ---------------------------------------------------------------------------
+
+/**
+ * Find an existing contact channel for a given channel type + external user ID.
+ */
+export async function findContactChannelByExternalUserId(
+  channelType: string,
+  externalUserId: string,
+): Promise<ContactChannelRow | null> {
+  const rows = await assistantDbQuery<ContactChannelRow>(
+    `SELECT cc.id AS channelId, cc.contact_id AS contactId,
+            cc.external_user_id AS externalUserId,
+            cc.external_chat_id AS externalChatId,
+            c.display_name AS displayName,
+            cc.status
+     FROM contact_channels cc
+     JOIN contacts c ON c.id = cc.contact_id
+     WHERE cc.type = ? AND cc.external_user_id = ?
+     LIMIT 1`,
+    [channelType, externalUserId],
+  );
+  return rows[0] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Upsert
+// ---------------------------------------------------------------------------
+
+/**
+ * Upsert a contact + channel for a verified user.
+ *
+ * If a contact channel with the same (type, address) exists, updates it.
+ * Otherwise creates a new contact + channel.
+ *
+ * This is intentionally simpler than the assistant's full upsertContact —
+ * it handles the verification-specific case only (single channel, no
+ * reassignment, no invite binding).
+ */
+export async function upsertVerifiedContactChannel(params: {
+  sourceChannel: string;
+  externalUserId: string;
+  externalChatId: string;
+  displayName?: string;
+  username?: string;
+}): Promise<void> {
+  const now = Date.now();
+  const { sourceChannel, externalChatId, displayName, username } = params;
+
+  const canonicalUserId =
+    canonicalizeInboundIdentity(sourceChannel, params.externalUserId) ??
+    params.externalUserId;
+  const address = canonicalUserId.toLowerCase();
+  const contactDisplayName = displayName ?? username ?? canonicalUserId;
+
+  // Check if a channel with this (type, address) already exists
+  const existing = await assistantDbQuery<{
+    channelId: string;
+    contactId: string;
+    channelStatus: string;
+  }>(
+    `SELECT cc.id AS channelId, cc.contact_id AS contactId, cc.status AS channelStatus
+     FROM contact_channels cc
+     WHERE cc.type = ? AND cc.address = ?
+     LIMIT 1`,
+    [sourceChannel, address],
+  );
+
+  if (existing.length > 0) {
+    const row = existing[0];
+
+    // Don't overwrite blocked channels
+    if (row.channelStatus === "blocked") {
+      log.warn({ sourceChannel, address }, "Skipping upsert: channel is blocked");
+      return;
+    }
+
+    // Update existing channel
+    await assistantDbRun(
+      `UPDATE contact_channels
+       SET status = 'active', policy = 'allow',
+           external_user_id = ?, external_chat_id = ?,
+           revoked_reason = NULL, blocked_reason = NULL,
+           updated_at = ?
+       WHERE id = ?`,
+      [canonicalUserId, externalChatId, now, row.channelId],
+    );
+
+    // Dual-write to gateway DB
+    try {
+      const gwDb = getGatewayDb();
+      gwDb.update(gwContactChannels)
+        .set({
+          status: "active",
+          policy: "allow",
+          externalUserId: canonicalUserId,
+          externalChatId,
+          revokedReason: null,
+          blockedReason: null,
+          updatedAt: now,
+        })
+        .where(eq(gwContactChannels.id, row.channelId))
+        .run();
+    } catch (gwErr) {
+      log.warn({ err: gwErr }, "Gateway DB contact channel update dual-write failed");
+    }
+
+    return;
+  }
+
+  // Create new contact + channel. Both use OR IGNORE for idempotency under
+  // retries. If the channel insert fails mid-flight, the orphan contact row
+  // is harmless (no channels → invisible in UI, cleaned up by next upsert
+  // for the same identity which will find-by-address and reuse it).
+  const contactId = crypto.randomUUID();
+  const channelId = crypto.randomUUID();
+
+  await assistantDbRun(
+    `INSERT OR IGNORE INTO contacts (id, display_name, role, created_at, updated_at)
+     VALUES (?, ?, 'contact', ?, ?)`,
+    [contactId, contactDisplayName, now, now],
+  );
+
+  await assistantDbRun(
+    `INSERT OR IGNORE INTO contact_channels
+       (id, contact_id, type, address, is_primary, external_user_id, external_chat_id,
+        status, policy, interaction_count, created_at, updated_at)
+     VALUES (?, ?, ?, ?, 0, ?, ?, 'active', 'allow', 0, ?, ?)`,
+    [channelId, contactId, sourceChannel, address, canonicalUserId, externalChatId, now, now],
+  );
+
+  // Dual-write to gateway DB
+  try {
+    const gwDb = getGatewayDb();
+    gwDb.insert(gwContacts)
+      .values({
+        id: contactId,
+        displayName: contactDisplayName,
+        role: "contact",
+        createdAt: now,
+        updatedAt: now,
+      })
+      .onConflictDoNothing()
+      .run();
+
+    gwDb.insert(gwContactChannels)
+      .values({
+        id: channelId,
+        contactId,
+        type: sourceChannel,
+        address,
+        isPrimary: false,
+        externalUserId: canonicalUserId,
+        externalChatId,
+        status: "active",
+        policy: "allow",
+        interactionCount: 0,
+        createdAt: now,
+        updatedAt: now,
+      })
+      .onConflictDoNothing()
+      .run();
+  } catch (gwErr) {
+    log.warn({ err: gwErr }, "Gateway DB contact create dual-write failed");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Inbound contact seeding (dual-write)
+// ---------------------------------------------------------------------------
+
+/**
+ * Create or update a contact channel for an inbound actor, preserving any
+ * existing status/policy. Used to seed contact records when new users are
+ * first seen on a channel.
+ *
+ * - Existing channel: updates display name, external_user_id, external_chat_id.
+ *   Status and policy are left unchanged so blocked/revoked channels stay that way.
+ * - New channel: inserts contact + channel with status='unverified', policy='allow'.
+ *
+ * Dual-writes to both the assistant DB (source of truth) and the gateway DB.
+ * Skips silently when the assistant IPC socket is unavailable (test environments).
+ */
+export async function upsertContactChannel(params: {
+  sourceChannel: string;
+  externalUserId: string;
+  externalChatId?: string;
+  displayName?: string;
+  username?: string;
+}): Promise<void> {
+  const { path: socketPath } = resolveIpcSocketPath("assistant");
+  if (!existsSync(socketPath)) return;
+
+  const { sourceChannel, externalChatId, displayName, username } = params;
+  const now = Date.now();
+  const canonicalUserId =
+    canonicalizeInboundIdentity(sourceChannel, params.externalUserId) ??
+    params.externalUserId;
+  const address = canonicalUserId.toLowerCase();
+  const contactDisplayName = displayName ?? username ?? canonicalUserId;
+
+  const existing = await assistantDbQuery<{
+    channelId: string;
+    contactId: string;
+    channelStatus: string;
+  }>(
+    `SELECT cc.id AS channelId, cc.contact_id AS contactId, cc.status AS channelStatus
+     FROM contact_channels cc
+     WHERE cc.type = ? AND cc.address = ?
+     LIMIT 1`,
+    [sourceChannel, address],
+  );
+
+  if (existing.length > 0) {
+    const row = existing[0];
+    if (row.channelStatus === "blocked") return;
+
+    // Update identity/display fields; preserve status and policy.
+    await assistantDbRun(
+      `UPDATE contacts SET display_name = ?, updated_at = ? WHERE id = ?`,
+      [contactDisplayName, now, row.contactId],
+    );
+    await assistantDbRun(
+      `UPDATE contact_channels
+       SET external_user_id = ?,
+           external_chat_id = COALESCE(?, external_chat_id),
+           updated_at = ?
+       WHERE id = ?`,
+      [canonicalUserId, externalChatId ?? null, now, row.channelId],
+    );
+
+    try {
+      const gwDb = getGatewayDb();
+      gwDb
+        .update(gwContactChannels)
+        .set({
+          externalUserId: canonicalUserId,
+          ...(externalChatId ? { externalChatId } : {}),
+          updatedAt: now,
+        })
+        .where(eq(gwContactChannels.id, row.channelId))
+        .run();
+    } catch (gwErr) {
+      log.warn({ err: gwErr }, "Gateway DB contact channel update dual-write failed");
+    }
+    return;
+  }
+
+  // New contact + channel.
+  const contactId = crypto.randomUUID();
+  const channelId = crypto.randomUUID();
+
+  await assistantDbRun(
+    `INSERT OR IGNORE INTO contacts (id, display_name, role, created_at, updated_at)
+     VALUES (?, ?, 'contact', ?, ?)`,
+    [contactId, contactDisplayName, now, now],
+  );
+  await assistantDbRun(
+    `INSERT OR IGNORE INTO contact_channels
+       (id, contact_id, type, address, is_primary, external_user_id, external_chat_id,
+        status, policy, interaction_count, created_at, updated_at)
+     VALUES (?, ?, ?, ?, 0, ?, ?, 'unverified', 'allow', 0, ?, ?)`,
+    [channelId, contactId, sourceChannel, address, canonicalUserId, externalChatId ?? null, now, now],
+  );
+
+  try {
+    const gwDb = getGatewayDb();
+    gwDb
+      .insert(gwContacts)
+      .values({
+        id: contactId,
+        displayName: contactDisplayName,
+        role: "contact",
+        createdAt: now,
+        updatedAt: now,
+      })
+      .onConflictDoNothing()
+      .run();
+    gwDb
+      .insert(gwContactChannels)
+      .values({
+        id: channelId,
+        contactId,
+        type: sourceChannel,
+        address,
+        isPrimary: false,
+        externalUserId: canonicalUserId,
+        externalChatId: externalChatId ?? null,
+        status: "unverified",
+        policy: "allow",
+        interactionCount: 0,
+        createdAt: now,
+        updatedAt: now,
+      })
+      .onConflictDoNothing()
+      .run();
+  } catch (gwErr) {
+    log.warn({ err: gwErr }, "Gateway DB contact channel create dual-write failed");
+  }
+}

package/src/verification/identity-match.ts

@@ -0,0 +1,68 @@
+/**
+ * Identity matching for verification sessions.
+ *
+ * Mirrors the assistant's channel-verification-service.ts identity check.
+ * Determines whether the actor submitting a verification code matches the
+ * expected identity on an outbound session.
+ */
+
+import type { VerificationSession } from "./session-helpers.js";
+
+/**
+ * Check whether the actor matches the session's expected identity.
+ *
+ * Returns true if:
+ * - The session has no expected identity (inbound sessions)
+ * - The session's identity binding status is not 'bound' (pending_bootstrap)
+ * - The actor matches the expected identity
+ */
+export function checkIdentityMatch(
+  session: VerificationSession,
+  actorExternalUserId: string,
+  actorChatId: string,
+): boolean {
+  const hasExpectedIdentity =
+    session.expectedExternalUserId != null ||
+    session.expectedChatId != null ||
+    session.expectedPhoneE164 != null;
+
+  if (!hasExpectedIdentity || session.identityBindingStatus !== "bound") {
+    return true;
+  }
+
+  // Phone match
+  if (session.expectedPhoneE164 != null) {
+    if (
+      actorExternalUserId === session.expectedPhoneE164 ||
+      actorExternalUserId === session.expectedExternalUserId
+    ) {
+      return true;
+    }
+  }
+
+  // Chat ID match (Telegram, Slack, etc.)
+  if (session.expectedChatId != null) {
+    if (session.expectedExternalUserId != null) {
+      // When both are set, require the externalUserId match — chatId alone
+      // is insufficient (shared group chats).
+      if (actorExternalUserId === session.expectedExternalUserId) {
+        return true;
+      }
+    } else if (actorChatId === session.expectedChatId) {
+      return true;
+    }
+  }
+
+  // Fallback: only expectedExternalUserId set (no phone, no chat)
+  if (
+    session.expectedPhoneE164 == null &&
+    session.expectedChatId == null &&
+    session.expectedExternalUserId != null
+  ) {
+    if (actorExternalUserId === session.expectedExternalUserId) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/verification/identity.ts

@@ -0,0 +1,61 @@
+/**
+ * Channel-agnostic inbound identity canonicalization for the gateway.
+ *
+ * Mirrors assistant/src/util/canonicalize-identity.ts so the gateway
+ * can canonicalize sender IDs independently.
+ */
+
+/** Channels whose raw sender IDs are phone numbers. */
+const PHONE_CHANNELS = new Set(["phone", "whatsapp"]);
+
+/**
+ * Normalize a phone number string to E.164 format.
+ */
+function normalizePhoneNumber(input: string): string | null {
+  const withoutTrunkZero = input.replace(/\(0\)/g, "");
+  const stripped = withoutTrunkZero.replace(/[\s\-().]/g, "");
+
+  if (stripped.length === 0) return null;
+
+  if (stripped.startsWith("+")) {
+    const digits = stripped.slice(1);
+    if (/^\d{10,15}$/.test(digits)) {
+      return stripped;
+    }
+    return null;
+  }
+
+  if (!/^\d+$/.test(stripped)) return null;
+
+  if (stripped.length === 10) {
+    return `+1${stripped}`;
+  }
+
+  if (stripped.length === 11 && stripped.startsWith("1")) {
+    return `+${stripped}`;
+  }
+
+  return null;
+}
+
+/**
+ * Canonicalize a raw inbound sender identity for the given channel.
+ *
+ * For phone-like channels: attempts E.164 normalization.
+ * For non-phone channels: returns trimmed raw ID unchanged.
+ * Returns null only when rawId is empty/whitespace-only.
+ */
+export function canonicalizeInboundIdentity(
+  channel: string,
+  rawId: string,
+): string | null {
+  const trimmed = rawId.trim();
+  if (trimmed.length === 0) return null;
+
+  if (PHONE_CHANNELS.has(channel)) {
+    const e164 = normalizePhoneNumber(trimmed);
+    return e164 ?? trimmed;
+  }
+
+  return trimmed;
+}