@vellumai/vellum-gateway 0.7.0 → 0.7.2

package/src/verification/rate-limit-helpers.ts

@@ -0,0 +1,205 @@
+/**
+ * Rate limiting helpers for gateway-owned verification.
+ *
+ * Gateway DB is the primary store; assistant DB gets best-effort dual-writes.
+ * Uses atomic upserts (ON CONFLICT) to handle concurrent webhook deliveries.
+ */
+
+import { and, eq, sql } from "drizzle-orm";
+
+import { assistantDbRun } from "../db/assistant-db-proxy.js";
+import { getGatewayDb } from "../db/connection.js";
+import { channelGuardianRateLimits as gwRateLimits } from "../db/schema.js";
+import { getLogger } from "../logger.js";
+
+const log = getLogger("verification-rate-limits");
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const RATE_LIMIT_MAX_ATTEMPTS = 5;
+const RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000;
+const RATE_LIMIT_LOCKOUT_MS = 30 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface RateLimitRecord {
+  attemptTimestampsJson: string;
+  lockedUntil: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+
+export function getRateLimit(
+  channel: string,
+  actorExternalUserId: string,
+  actorChatId: string,
+): RateLimitRecord | null {
+  const gwDb = getGatewayDb();
+  const row = gwDb
+    .select()
+    .from(gwRateLimits)
+    .where(
+      and(
+        eq(gwRateLimits.channel, channel),
+        eq(gwRateLimits.actorExternalUserId, actorExternalUserId),
+        eq(gwRateLimits.actorChatId, actorChatId),
+      ),
+    )
+    .get();
+
+  return row
+    ? { attemptTimestampsJson: row.attemptTimestampsJson, lockedUntil: row.lockedUntil }
+    : null;
+}
+
+/**
+ * Returns true if the actor is currently locked out.
+ */
+export function isRateLimited(
+  channel: string,
+  actorExternalUserId: string,
+  actorChatId: string,
+): boolean {
+  const record = getRateLimit(channel, actorExternalUserId, actorChatId);
+  return record?.lockedUntil != null && Date.now() < record.lockedUntil;
+}
+
+// ---------------------------------------------------------------------------
+// Write
+// ---------------------------------------------------------------------------
+
+/**
+ * Record an invalid verification attempt. Uses a single atomic SQL UPDATE
+ * with json_array + json_each to prune old timestamps and append the new
+ * one in one statement, avoiding the read-modify-write race where
+ * concurrent calls could overwrite each other's timestamps.
+ *
+ * For new records (no existing row), falls back to INSERT with a single
+ * timestamp.
+ */
+export async function recordInvalidAttempt(
+  channel: string,
+  actorExternalUserId: string,
+  actorChatId: string,
+): Promise<void> {
+  const now = Date.now();
+  const cutoff = now - RATE_LIMIT_WINDOW_MS;
+
+  // Gateway DB — atomic upsert with in-SQL JSON manipulation.
+  // The ON CONFLICT UPDATE prunes expired timestamps and appends the new
+  // one in a single statement, so concurrent upserts serialize at the
+  // row level (SQLite's write lock) without stale reads.
+  const gwDb = getGatewayDb();
+  const newId = crypto.randomUUID();
+  const singleTimestampJson = JSON.stringify([now]);
+
+  gwDb.run(sql`
+    INSERT INTO ${gwRateLimits} (
+      id, channel, actor_external_user_id, actor_chat_id,
+      attempt_timestamps_json, locked_until, created_at, updated_at
+    ) VALUES (
+      ${newId}, ${channel}, ${actorExternalUserId}, ${actorChatId},
+      ${singleTimestampJson}, NULL, ${now}, ${now}
+    )
+    ON CONFLICT (channel, actor_external_user_id, actor_chat_id) DO UPDATE SET
+      attempt_timestamps_json = (
+        SELECT json_group_array(value) FROM (
+          SELECT value FROM json_each(${gwRateLimits.attemptTimestampsJson})
+          WHERE CAST(value AS INTEGER) > ${cutoff}
+          UNION ALL
+          SELECT ${now}
+        )
+      ),
+      locked_until = CASE
+        WHEN (
+          SELECT COUNT(*) FROM (
+            SELECT value FROM json_each(${gwRateLimits.attemptTimestampsJson})
+            WHERE CAST(value AS INTEGER) > ${cutoff}
+            UNION ALL
+            SELECT ${now}
+          )
+        ) >= ${RATE_LIMIT_MAX_ATTEMPTS}
+        THEN ${now + RATE_LIMIT_LOCKOUT_MS}
+        ELSE ${gwRateLimits.lockedUntil}
+      END,
+      updated_at = ${now}
+  `);
+
+  // Read back for assistant DB dual-write
+  const updated = getRateLimit(channel, actorExternalUserId, actorChatId);
+  const timestampsJson = updated?.attemptTimestampsJson ?? singleTimestampJson;
+  const lockedUntil = updated?.lockedUntil ?? null;
+
+  // Assistant DB dual-write
+  try {
+    await assistantDbRun(
+      `INSERT INTO channel_guardian_rate_limits
+         (id, channel, actor_external_user_id, actor_chat_id,
+          attempt_timestamps_json, locked_until, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT (channel, actor_external_user_id, actor_chat_id) DO UPDATE SET
+         attempt_timestamps_json = excluded.attempt_timestamps_json,
+         locked_until = excluded.locked_until,
+         updated_at = excluded.updated_at`,
+      [
+        crypto.randomUUID(),
+        channel,
+        actorExternalUserId,
+        actorChatId,
+        timestampsJson,
+        lockedUntil,
+        now,
+        now,
+      ],
+    );
+  } catch (err) {
+    log.warn({ err }, "Assistant DB rate limit dual-write failed (best-effort)");
+  }
+}
+
+export async function resetRateLimit(
+  channel: string,
+  actorExternalUserId: string,
+  actorChatId: string,
+): Promise<void> {
+  const now = Date.now();
+
+  const gwDb = getGatewayDb();
+  gwDb.update(gwRateLimits)
+    .set({
+      attemptTimestampsJson: "[]",
+      lockedUntil: null,
+      updatedAt: now,
+    })
+    .where(
+      and(
+        eq(gwRateLimits.channel, channel),
+        eq(gwRateLimits.actorExternalUserId, actorExternalUserId),
+        eq(gwRateLimits.actorChatId, actorChatId),
+      ),
+    )
+    .run();
+
+  try {
+    await assistantDbRun(
+      `UPDATE channel_guardian_rate_limits
+       SET attempt_timestamps_json = '[]', locked_until = NULL, updated_at = ?
+       WHERE channel = ?
+         AND actor_external_user_id = ?
+         AND actor_chat_id = ?`,
+      [now, channel, actorExternalUserId, actorChatId],
+    );
+  } catch (err) {
+    log.warn({ err }, "Assistant DB rate limit reset dual-write failed (best-effort)");
+  }
+}

package/src/verification/reply-delivery.ts

@@ -0,0 +1,109 @@
+/**
+ * Verification reply delivery for gateway-owned text-channel verification.
+ *
+ * Delivers deterministic template-driven replies to the originating channel
+ * via the replyCallbackUrl (the gateway's own /deliver/* endpoint). This
+ * keeps verification replies entirely within the gateway — the assistant
+ * never sees verification code messages.
+ */
+
+import { fetchImpl } from "../fetch.js";
+import { getLogger } from "../logger.js";
+
+const log = getLogger("verification-reply");
+
+const DELIVERY_TIMEOUT_MS = 10_000;
+
+// ---------------------------------------------------------------------------
+// Reply templates (mirrors assistant's verification-templates.ts)
+// ---------------------------------------------------------------------------
+
+export function composeVerificationSuccessReply(
+  verificationType?: "guardian" | "trusted_contact",
+): string {
+  if (verificationType === "trusted_contact") {
+    return "Verification successful! You can now message the assistant.";
+  }
+  return "Verification successful. You are now set as the guardian for this channel.";
+}
+
+export function composeVerificationFailureReply(
+  reason?: string,
+): string {
+  return reason ?? "The verification code is invalid or has expired.";
+}
+
+// ---------------------------------------------------------------------------
+// Delivery
+// ---------------------------------------------------------------------------
+
+export interface VerificationReplyParams {
+  replyCallbackUrl: string;
+  chatId: string;
+  text: string;
+  assistantId?: string;
+}
+
+/**
+ * Deliver a verification reply via the channel's callback URL.
+ *
+ * Uses fetchImpl (the gateway's fetch wrapper) to call the gateway's own
+ * /deliver/* endpoint. Retries once after a short delay on failure.
+ */
+export async function deliverVerificationReply(
+  params: VerificationReplyParams,
+): Promise<void> {
+  const { replyCallbackUrl, chatId, text, assistantId } = params;
+
+  const body = JSON.stringify({
+    chatId,
+    text,
+    ...(assistantId ? { assistantId } : {}),
+  });
+
+  const headers = { "Content-Type": "application/json" };
+
+  try {
+    const res = await fetchImpl(replyCallbackUrl, {
+      method: "POST",
+      headers,
+      body,
+      signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+    });
+
+    if (!res.ok) {
+      const resBody = await res.text().catch(() => "<unreadable>");
+      log.error(
+        { status: res.status, body: resBody, chatId },
+        "Verification reply delivery returned non-OK status",
+      );
+    }
+  } catch (err) {
+    log.error(
+      { err, chatId },
+      "Verification reply delivery failed — retrying once",
+    );
+
+    // Single retry after 2s
+    await new Promise((r) => setTimeout(r, 2000));
+    try {
+      const retryRes = await fetchImpl(replyCallbackUrl, {
+        method: "POST",
+        headers,
+        body,
+        signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+      });
+      if (!retryRes.ok) {
+        log.error(
+          { status: retryRes.status, chatId },
+          "Verification reply retry also failed",
+        );
+      }
+    } catch (retryErr) {
+      log.error(
+        { err: retryErr, chatId },
+        "Verification reply retry threw",
+      );
+    }
+  }
+}

package/src/verification/session-helpers.ts

@@ -0,0 +1,164 @@
+/**
+ * Verification session helpers for gateway-owned verification.
+ *
+ * Session lookup, consumption, and status checks — all via raw SQL
+ * through the assistant DB IPC proxy. Dual-writes to gateway DB on
+ * session consumption.
+ */
+
+import { eq } from "drizzle-orm";
+
+import {
+  assistantDbQuery,
+  assistantDbRun,
+} from "../db/assistant-db-proxy.js";
+import { getGatewayDb } from "../db/connection.js";
+import { channelVerificationSessions as gwSessions } from "../db/schema.js";
+import { getLogger } from "../logger.js";
+
+const log = getLogger("verification-sessions");
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface VerificationSession {
+  id: string;
+  challengeHash: string;
+  expiresAt: number;
+  status: string;
+  verificationPurpose: string;
+  expectedExternalUserId: string | null;
+  expectedChatId: string | null;
+  expectedPhoneE164: string | null;
+  identityBindingStatus: string | null;
+  codeDigits: number | null;
+  maxAttempts: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const SESSION_COLUMNS = `
+  id, challenge_hash AS challengeHash, expires_at AS expiresAt,
+  status, verification_purpose AS verificationPurpose,
+  expected_external_user_id AS expectedExternalUserId,
+  expected_chat_id AS expectedChatId,
+  expected_phone_e164 AS expectedPhoneE164,
+  identity_binding_status AS identityBindingStatus,
+  code_digits AS codeDigits, max_attempts AS maxAttempts
+`;
+
+/**
+ * All session statuses that represent an interceptable verification session.
+ *
+ * Includes 'awaiting_response' — outbound text verification sessions are
+ * created with this status (see assistant createOutboundSession).
+ */
+const INTERCEPTABLE_STATUSES = `('pending', 'pending_bootstrap', 'awaiting_response')`;
+
+// ---------------------------------------------------------------------------
+// Session lookup
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether there is any pending/active verification session for this
+ * channel. Used as a fast guard before attempting code parsing + validation.
+ */
+export async function hasPendingOrActiveSession(
+  channel: string,
+): Promise<boolean> {
+  const now = Date.now();
+  const rows = await assistantDbQuery<{ id: string }>(
+    `SELECT id FROM channel_verification_sessions
+     WHERE channel = ?
+       AND status IN ${INTERCEPTABLE_STATUSES}
+       AND expires_at > ?
+     LIMIT 1`,
+    [channel, now],
+  );
+  return rows.length > 0;
+}
+
+/**
+ * Find a session matching a specific challenge hash.
+ */
+export async function findSessionByHash(
+  channel: string,
+  challengeHash: string,
+): Promise<VerificationSession | null> {
+  const now = Date.now();
+  const rows = await assistantDbQuery<VerificationSession>(
+    `SELECT ${SESSION_COLUMNS}
+     FROM channel_verification_sessions
+     WHERE channel = ?
+       AND challenge_hash = ?
+       AND status IN ${INTERCEPTABLE_STATUSES}
+       AND expires_at > ?
+     LIMIT 1`,
+    [channel, challengeHash, now],
+  );
+  return rows[0] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Session consumption (dual-write)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mark a verification session as consumed. Dual-writes to both assistant
+ * and gateway DBs.
+ *
+ * The UPDATE includes a status predicate so only the first concurrent
+ * consumer wins — subsequent attempts see zero changes and return false,
+ * preserving one-time-code semantics under race conditions.
+ */
+export async function consumeSession(
+  sessionId: string,
+  actorExternalUserId: string,
+  actorChatId: string,
+): Promise<boolean> {
+  const now = Date.now();
+
+  // Assistant DB (source of truth) — status guard ensures atomicity
+  const result = await assistantDbRun(
+    `UPDATE channel_verification_sessions
+     SET status = 'consumed',
+         consumed_by_external_user_id = ?,
+         consumed_by_chat_id = ?,
+         updated_at = ?
+     WHERE id = ?
+       AND status IN ${INTERCEPTABLE_STATUSES}`,
+    [actorExternalUserId, actorChatId, now, sessionId],
+  );
+
+  if (result.changes === 0) {
+    log.warn(
+      { sessionId },
+      "Session consume returned 0 changes — already consumed or status changed",
+    );
+    return false;
+  }
+
+  // Gateway DB dual-write
+  try {
+    const gwDb = getGatewayDb();
+    gwDb.update(gwSessions)
+      .set({
+        status: "consumed",
+        consumedByExternalUserId: actorExternalUserId,
+        consumedByChatId: actorChatId,
+        updatedAt: now,
+      })
+      .where(eq(gwSessions.id, sessionId))
+      .run();
+  } catch (gwErr) {
+    log.warn(
+      { err: gwErr, sessionId },
+      "Gateway DB session consume dual-write failed (best-effort)",
+    );
+  }
+
+  return true;
+}