@vellumai/vellum-gateway 0.7.0 → 0.7.2

package/src/pairing/pairing-routes.ts

@@ -1,379 +0,0 @@
-/**
- * Gateway-native pairing route handlers.
- *
- * Handles the full iOS pairing flow directly in the gateway:
- *   - POST /pairing/register  — macOS pre-registers a pairing request (QR displayed)
- *   - POST /pairing/request   — iOS initiates a pairing handshake
- *   - GET  /pairing/status    — iOS polls for approval status
- *
- * Credentials (JWT access token + opaque refresh token) are minted via
- * guardian-bootstrap, which writes directly to the assistant's SQLite
- * database with dual-writes to the gateway DB.
- */
-
-import { bootstrapGuardian } from "../auth/guardian-bootstrap.js";
-import { mintServiceToken } from "../auth/token-exchange.js";
-import { getLogger } from "../logger.js";
-
-import {
-  hashDeviceId,
-  isDeviceApproved,
-  refreshDevice,
-} from "./approved-devices-store.js";
-import { PairingStore } from "./pairing-store.js";
-
-const log = getLogger("pairing-routes");
-
-// ---------------------------------------------------------------------------
-// Credential types
-// ---------------------------------------------------------------------------
-
-interface PairingCredentials {
-  accessToken: string;
-  accessTokenExpiresAt: number;
-  refreshToken: string;
-  refreshTokenExpiresAt: number;
-  refreshAfter: number;
-}
-
-// ---------------------------------------------------------------------------
-// Credential minting (delegates to gateway's guardian-bootstrap)
-// ---------------------------------------------------------------------------
-
-async function mintPairingCredentials(
-  deviceId: string,
-  platform: string,
-): Promise<PairingCredentials | null> {
-  try {
-    const result = await bootstrapGuardian({ platform, deviceId });
-    log.info({ platform }, "Minted credentials during pairing");
-    return {
-      accessToken: result.accessToken,
-      accessTokenExpiresAt: result.accessTokenExpiresAt,
-      refreshToken: result.refreshToken,
-      refreshTokenExpiresAt: result.refreshTokenExpiresAt,
-      refreshAfter: result.refreshAfter,
-    };
-  } catch (err) {
-    log.warn(
-      { err },
-      "Failed to mint credentials during pairing — continuing without them",
-    );
-    return null;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Transient in-memory state
-// ---------------------------------------------------------------------------
-
-const PAIRING_PENDING_DEVICE_ID_TTL_MS = 10 * 60 * 1000; // 10 minutes
-const pendingDeviceIds = new Map<
-  string,
-  { deviceId: string; createdAt: number }
->();
-
-const PAIRING_CREDENTIAL_RETRIEVAL_TTL_MS = 5 * 60 * 1000; // 5 minutes
-const approvedCredentials = new Map<
-  string,
-  { credentials: PairingCredentials; approvedAt: number }
->();
-
-function sweepApprovedCredentials(): void {
-  const now = Date.now();
-  for (const [id, entry] of approvedCredentials) {
-    if (now - entry.approvedAt > PAIRING_CREDENTIAL_RETRIEVAL_TTL_MS) {
-      approvedCredentials.delete(id);
-    }
-  }
-}
-
-function sweepPendingDeviceIds(): void {
-  const now = Date.now();
-  for (const [id, entry] of pendingDeviceIds) {
-    if (now - entry.createdAt > PAIRING_PENDING_DEVICE_ID_TTL_MS) {
-      pendingDeviceIds.delete(id);
-    }
-  }
-}
-
-const mintingInFlight = new Set<string>();
-
-function cleanupPairingState(pairingRequestId: string): void {
-  pendingDeviceIds.delete(pairingRequestId);
-  approvedCredentials.delete(pairingRequestId);
-  mintingInFlight.delete(pairingRequestId);
-}
-
-// ---------------------------------------------------------------------------
-// HTTP helpers
-// ---------------------------------------------------------------------------
-
-const MAX_PAIRING_BODY_BYTES = 4096;
-
-function jsonError(code: string, message: string, status: number): Response {
-  return Response.json({ error: { code, message } }, { status });
-}
-
-// ---------------------------------------------------------------------------
-// Route handler factory
-// ---------------------------------------------------------------------------
-
-export function createPairingHandler(deps: {
-  pairingStore: PairingStore;
-  getBearerToken?: () => string | undefined;
-}) {
-  const { pairingStore } = deps;
-
-  function getOrMintBearerToken(): string | undefined {
-    if (deps.getBearerToken) {
-      const token = deps.getBearerToken();
-      if (token) return token;
-    }
-    try {
-      return mintServiceToken();
-    } catch {
-      return undefined;
-    }
-  }
-
-  return {
-    /**
-     * POST /pairing/register — Bearer-authenticated.
-     * macOS pre-registers a pairing request when the QR is displayed.
-     */
-    async handlePairingRegister(req: Request): Promise<Response> {
-      try {
-        const body = (await req.json()) as Record<string, unknown>;
-        const pairingRequestId =
-          typeof body.pairingRequestId === "string"
-            ? body.pairingRequestId
-            : "";
-        const pairingSecret =
-          typeof body.pairingSecret === "string" ? body.pairingSecret : "";
-        const gatewayUrl =
-          typeof body.gatewayUrl === "string" ? body.gatewayUrl : "";
-        const localLanUrl =
-          typeof body.localLanUrl === "string" ? body.localLanUrl : null;
-
-        if (!pairingRequestId || !pairingSecret || !gatewayUrl) {
-          return jsonError(
-            "BAD_REQUEST",
-            "Missing required fields: pairingRequestId, pairingSecret, gatewayUrl",
-            400,
-          );
-        }
-
-        const result = pairingStore.register({
-          pairingRequestId,
-          pairingSecret,
-          gatewayUrl,
-          localLanUrl,
-        });
-        if (!result.ok) {
-          const message =
-            result.reason === "active_pairing"
-              ? "A pairing request is already in progress"
-              : "Conflict: pairingRequestId exists with different secret";
-          return jsonError("CONFLICT", message, 409);
-        }
-
-        return Response.json({ ok: true });
-      } catch (err) {
-        log.error({ err }, "Failed to register pairing request");
-        return jsonError("INTERNAL_ERROR", "Internal server error", 500);
-      }
-    },
-
-    /**
-     * POST /pairing/request — Unauthenticated (secret-gated).
-     * iOS initiates a pairing handshake.
-     */
-    async handlePairingRequest(req: Request): Promise<Response> {
-      try {
-        const contentLength = req.headers.get("content-length");
-        if (contentLength && Number(contentLength) > MAX_PAIRING_BODY_BYTES) {
-          return jsonError("BAD_REQUEST", "Payload too large", 413);
-        }
-        const body = (await req.json()) as Record<string, unknown>;
-        const pairingRequestId =
-          typeof body.pairingRequestId === "string"
-            ? body.pairingRequestId
-            : "";
-        const pairingSecret =
-          typeof body.pairingSecret === "string" ? body.pairingSecret : "";
-        const deviceId =
-          typeof body.deviceId === "string" ? body.deviceId.trim() : "";
-        const deviceName =
-          typeof body.deviceName === "string" ? body.deviceName.trim() : "";
-
-        log.info(
-          { pairingRequestId, deviceName, hasDeviceId: !!deviceId },
-          "Pairing request received",
-        );
-
-        if (!deviceId || !deviceName) {
-          return jsonError(
-            "BAD_REQUEST",
-            "Missing required fields: deviceId, deviceName",
-            400,
-          );
-        }
-
-        if (!pairingRequestId || !pairingSecret) {
-          return jsonError(
-            "BAD_REQUEST",
-            "Missing required fields: pairingRequestId, pairingSecret",
-            400,
-          );
-        }
-
-        const result = pairingStore.beginRequest({
-          pairingRequestId,
-          pairingSecret,
-          deviceId,
-          deviceName,
-        });
-        if (!result.ok) {
-          if (result.reason === "already_paired") {
-            return jsonError(
-              "CONFLICT",
-              "This pairing request is already bound to another device",
-              409,
-            );
-          }
-          const statusCode =
-            result.reason === "invalid_secret"
-              ? 403
-              : result.reason === "not_found"
-                ? 403
-                : 410;
-          return jsonError("FORBIDDEN", "Forbidden", statusCode);
-        }
-
-        const entry = result.entry;
-        const hashedDeviceId = hashDeviceId(deviceId);
-        const bearerToken = getOrMintBearerToken();
-
-        // Auto-approve if device is in the allowlist
-        if (isDeviceApproved(hashedDeviceId) && bearerToken) {
-          refreshDevice(hashedDeviceId, deviceName);
-          pairingStore.approve(pairingRequestId, bearerToken);
-          log.info(
-            { pairingRequestId, hashedDeviceId },
-            "Auto-approved allowlisted device",
-          );
-          const credentials = await mintPairingCredentials(deviceId, "ios");
-          return Response.json({
-            status: "approved",
-            bearerToken,
-            gatewayUrl: entry.gatewayUrl,
-            localLanUrl: entry.localLanUrl,
-            ...(credentials
-              ? {
-                  accessToken: credentials.accessToken,
-                  accessTokenExpiresAt: credentials.accessTokenExpiresAt,
-                  refreshToken: credentials.refreshToken,
-                  refreshTokenExpiresAt: credentials.refreshTokenExpiresAt,
-                  refreshAfter: credentials.refreshAfter,
-                }
-              : {}),
-          });
-        }
-
-        // Store the raw deviceId transiently so we can mint the actor token
-        // later when the pairing is actually approved.
-        pendingDeviceIds.set(pairingRequestId, {
-          deviceId,
-          createdAt: Date.now(),
-        });
-
-        return Response.json({ status: "pending" });
-      } catch (err) {
-        log.error({ err }, "Failed to process pairing request");
-        return jsonError("INTERNAL_ERROR", "Internal server error", 500);
-      }
-    },
-
-    /**
-     * GET /pairing/status — Unauthenticated (secret-gated).
-     * iOS polls for approval status.
-     */
-    async handlePairingStatus(req: Request): Promise<Response> {
-      const url = new URL(req.url);
-      const id = url.searchParams.get("id") ?? "";
-      const secret = url.searchParams.get("secret") ?? "";
-      const deviceId = (url.searchParams.get("deviceId") ?? "").trim();
-
-      if (!id || !secret) {
-        return jsonError(
-          "BAD_REQUEST",
-          "Missing required params: id, secret",
-          400,
-        );
-      }
-
-      if (!pairingStore.validateSecret(id, secret)) {
-        return jsonError("FORBIDDEN", "Forbidden", 403);
-      }
-
-      sweepApprovedCredentials();
-      sweepPendingDeviceIds();
-
-      const entry = pairingStore.get(id);
-      if (!entry) {
-        pendingDeviceIds.delete(id);
-        return jsonError("NOT_FOUND", "Not found", 404);
-      }
-
-      if (entry.status === "approved") {
-        let credentialEntry = approvedCredentials.get(id);
-        if (!credentialEntry && !mintingInFlight.has(id)) {
-          const pending = pendingDeviceIds.get(id);
-          const deviceIdMatchesEntry = Boolean(
-            deviceId &&
-            entry.hashedDeviceId &&
-            hashDeviceId(deviceId) === entry.hashedDeviceId,
-          );
-          const mintDeviceId =
-            pending?.deviceId ?? (deviceIdMatchesEntry ? deviceId : undefined);
-          if (mintDeviceId) {
-            mintingInFlight.add(id);
-            try {
-              const credentials = await mintPairingCredentials(mintDeviceId, "ios");
-              if (credentials) {
-                pendingDeviceIds.delete(id);
-                credentialEntry = { credentials, approvedAt: Date.now() };
-                approvedCredentials.set(id, credentialEntry);
-              }
-            } finally {
-              mintingInFlight.delete(id);
-            }
-          }
-        }
-
-        return Response.json({
-          status: "approved",
-          bearerToken: entry.bearerToken,
-          gatewayUrl: entry.gatewayUrl,
-          localLanUrl: entry.localLanUrl,
-          ...(credentialEntry
-            ? {
-                accessToken: credentialEntry.credentials.accessToken,
-                accessTokenExpiresAt:
-                  credentialEntry.credentials.accessTokenExpiresAt,
-                refreshToken: credentialEntry.credentials.refreshToken,
-                refreshTokenExpiresAt:
-                  credentialEntry.credentials.refreshTokenExpiresAt,
-                refreshAfter: credentialEntry.credentials.refreshAfter,
-              }
-            : {}),
-        });
-      }
-
-      return Response.json({ status: entry.status });
-    },
-
-    cleanupPairingState,
-  };
-}

package/src/pairing/pairing-store.ts

@@ -1,218 +0,0 @@
-/**
- * In-memory pairing request store with TTL.
- *
- * Each pairing request lives for at most TTL_MS (5 minutes) before
- * being swept as expired. Status transitions:
- *   registered → pending → approved | denied | expired
- */
-
-import { createHash, timingSafeEqual } from "node:crypto";
-
-import { getLogger } from "../logger.js";
-
-const log = getLogger("pairing-store");
-
-const PAIRING_TTL_MS = 5 * 60 * 1000; // 5 minutes
-const PAIRING_SWEEP_INTERVAL_MS = 30_000; // 30 seconds
-
-export type PairingStatus =
-  | "registered"
-  | "pending"
-  | "approved"
-  | "denied"
-  | "expired";
-
-export interface PairingRequest {
-  pairingRequestId: string;
-  hashedPairingSecret: string;
-  hashedDeviceId?: string;
-  deviceName?: string;
-  status: PairingStatus;
-  gatewayUrl: string;
-  localLanUrl: string | null;
-  bearerToken?: string;
-  createdAt: number;
-}
-
-function hashValue(value: string): string {
-  return createHash("sha256").update(value).digest("hex");
-}
-
-function timingSafeCompare(a: string, b: string): boolean {
-  const bufA = Buffer.from(a);
-  const bufB = Buffer.from(b);
-  if (bufA.length !== bufB.length) return false;
-  return timingSafeEqual(bufA, bufB);
-}
-
-export class PairingStore {
-  private requests = new Map<string, PairingRequest>();
-  private sweepTimer: ReturnType<typeof setInterval> | null = null;
-
-  start(): void {
-    this.sweepTimer = setInterval(
-      () => this.sweep(),
-      PAIRING_SWEEP_INTERVAL_MS,
-    );
-  }
-
-  stop(): void {
-    if (this.sweepTimer) {
-      clearInterval(this.sweepTimer);
-      this.sweepTimer = null;
-    }
-    this.requests.clear();
-  }
-
-  /**
-   * Pre-register a pairing request (called when QR is displayed).
-   * Idempotent: if the same ID exists and secret matches, overwrite.
-   * Returns false with 'conflict' if ID exists but secret doesn't match,
-   * or 'active_pairing' if another pairing request is already in progress.
-   */
-  register(params: {
-    pairingRequestId: string;
-    pairingSecret: string;
-    gatewayUrl: string;
-    localLanUrl?: string | null;
-  }): { ok: true } | { ok: false; reason: "conflict" | "active_pairing" } {
-    const hashedSecret = hashValue(params.pairingSecret);
-    const existing = this.requests.get(params.pairingRequestId);
-
-    if (existing) {
-      if (!timingSafeCompare(existing.hashedPairingSecret, hashedSecret)) {
-        return { ok: false, reason: "conflict" };
-      }
-    }
-
-    // Reject if another pairing request is already active (registered or pending).
-    for (const entry of this.requests.values()) {
-      if (entry.pairingRequestId === params.pairingRequestId) continue;
-      if (entry.status === "registered" || entry.status === "pending") {
-        log.warn(
-          {
-            existingPairingRequestId: entry.pairingRequestId,
-            newPairingRequestId: params.pairingRequestId,
-          },
-          "Rejected pairing registration — another pairing is already in progress",
-        );
-        return { ok: false, reason: "active_pairing" };
-      }
-    }
-
-    this.requests.set(params.pairingRequestId, {
-      pairingRequestId: params.pairingRequestId,
-      hashedPairingSecret: hashedSecret,
-      status: "registered",
-      gatewayUrl: params.gatewayUrl,
-      localLanUrl: params.localLanUrl ?? null,
-      createdAt: Date.now(),
-    });
-    log.info(
-      { pairingRequestId: params.pairingRequestId },
-      "Pairing request registered",
-    );
-    return { ok: true };
-  }
-
-  /**
-   * iOS initiates a pairing request. Validates the secret and transitions
-   * the entry to "pending" (or "approved" if auto-approved).
-   */
-  beginRequest(params: {
-    pairingRequestId: string;
-    pairingSecret: string;
-    deviceId: string;
-    deviceName: string;
-  }):
-    | { ok: true; entry: PairingRequest }
-    | {
-        ok: false;
-        reason: "not_found" | "invalid_secret" | "expired" | "already_paired";
-      } {
-    const entry = this.requests.get(params.pairingRequestId);
-    if (!entry) {
-      return { ok: false, reason: "not_found" };
-    }
-
-    if (entry.status === "expired" || entry.status === "denied") {
-      return { ok: false, reason: "expired" };
-    }
-
-    const hashedSecret = hashValue(params.pairingSecret);
-    if (!timingSafeCompare(entry.hashedPairingSecret, hashedSecret)) {
-      return { ok: false, reason: "invalid_secret" };
-    }
-
-    const hashedDeviceId = hashValue(params.deviceId);
-
-    if (
-      entry.hashedDeviceId &&
-      !timingSafeCompare(entry.hashedDeviceId, hashedDeviceId)
-    ) {
-      log.warn(
-        { pairingRequestId: params.pairingRequestId },
-        "Pairing request already bound to a different device",
-      );
-      return { ok: false, reason: "already_paired" };
-    }
-
-    entry.hashedDeviceId = hashedDeviceId;
-    entry.deviceName = params.deviceName;
-    if (entry.status === "registered") {
-      entry.status = "pending";
-    }
-    return { ok: true, entry };
-  }
-
-  approve(
-    pairingRequestId: string,
-    bearerToken: string,
-  ): PairingRequest | null {
-    const entry = this.requests.get(pairingRequestId);
-    if (!entry) return null;
-    entry.status = "approved";
-    entry.bearerToken = bearerToken;
-    return entry;
-  }
-
-  deny(pairingRequestId: string): PairingRequest | null {
-    const entry = this.requests.get(pairingRequestId);
-    if (!entry) return null;
-    entry.status = "denied";
-    return entry;
-  }
-
-  get(pairingRequestId: string): PairingRequest | null {
-    return this.requests.get(pairingRequestId) ?? null;
-  }
-
-  validateSecret(pairingRequestId: string, secret: string): boolean {
-    const entry = this.requests.get(pairingRequestId);
-    if (!entry) return false;
-    const hashedSecret = hashValue(secret);
-    return timingSafeCompare(entry.hashedPairingSecret, hashedSecret);
-  }
-
-  private sweep(): void {
-    const now = Date.now();
-    let changed = false;
-    for (const [id, entry] of this.requests) {
-      if (now - entry.createdAt > PAIRING_TTL_MS) {
-        if (entry.status !== "approved") {
-          entry.status = "expired";
-          changed = true;
-        }
-        // Remove entries older than 2x TTL regardless of status
-        if (now - entry.createdAt > PAIRING_TTL_MS * 2) {
-          this.requests.delete(id);
-          changed = true;
-          log.debug({ pairingRequestId: id }, "Pairing request swept");
-        }
-      }
-    }
-    if (changed) {
-      log.debug("Sweep completed with changes");
-    }
-  }
-}