@vellumai/cli 0.10.11 → 0.10.12-dev.202607242326.75b9ec6

package/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -0,0 +1,260 @@
+/**
+ * Wire contracts for the remote-web pairing flow — the RFC 8628-style
+ * device-code exchange that connects a browser (or the iOS app) to a
+ * self-hosted assistant over its public ingress URL.
+ *
+ * The gateway routes are the authoritative serving side:
+ *   - `POST /v1/remote-web/pairing-challenge`     mint a challenge
+ *       (`gateway/src/http/routes/remote-web-pairing-challenge.ts`,
+ *        `gateway/src/remote-web/pairing-challenge-store.ts`)
+ *   - `POST /v1/remote-web/pairing-verification`  approve by user code
+ *       (`gateway/src/http/routes/remote-web-pairing-verification.ts`)
+ *   - `POST /v1/remote-web/pairing-token`         poll + exchange device code
+ *       (`gateway/src/http/routes/remote-web-pairing-token.ts`)
+ *
+ * These shapes mirror those handlers' request/response bodies exactly so the
+ * gateway, the `vellum pair` CLI (`cli/src/commands/pair.ts`), and the web SPA
+ * (`clients/web/src/lib/auth/remote-gateway-session.ts`) share one definition
+ * and cannot silently drift.
+ *
+ * Timestamps are ISO-8601 strings — every gateway response serializes them via
+ * `Date#toISOString()`.
+ */
+
+/** `POST /v1/remote-web/pairing-challenge` request body. */
+export interface RemoteWebPairingChallengeRequest {
+  /** Public https base URL the scanning device can reach the assistant at. */
+  publicBaseUrl: string;
+}
+
+/** `POST /v1/remote-web/pairing-challenge` success response body (200). */
+export interface RemoteWebPairingChallengeResponse {
+  /** Opaque secret the paired device exchanges for a token. */
+  deviceCode: string;
+  /** Short human-readable code the host approves out of band. */
+  userCode: string;
+  /** URL the device opens to complete pairing. */
+  verificationUri: string;
+  /** ISO-8601 instant the challenge expires. */
+  expiresAt: string;
+  /** Seconds until the challenge expires. */
+  expiresInSeconds: number;
+  /** Recommended poll interval (seconds) for the token-exchange endpoint. */
+  intervalSeconds: number;
+}
+
+/** `POST /v1/remote-web/pairing-verification` request body. */
+export interface RemoteWebPairingVerificationRequest {
+  /** The `userCode` from the challenge, entered/scanned on the host. */
+  userCode: string;
+}
+
+/**
+ * `POST /v1/remote-web/pairing-verification` success response body (200).
+ *
+ * The gateway maps the `expired` / `invalid` outcomes to error responses, so
+ * the only success shape on the wire is the approved variant.
+ */
+export interface RemoteWebPairingVerificationResponse {
+  status: "approved";
+  verificationUri: string;
+  /** ISO-8601 instant the approved challenge expires. */
+  expiresAt: string;
+}
+
+/** `POST /v1/remote-web/pairing-token` request body. */
+export interface RemoteWebPairingTokenRequest {
+  /** The `deviceCode` from the challenge. */
+  deviceCode: string;
+}
+
+/**
+ * `POST /v1/remote-web/pairing-token` still-pending response body (202) — the
+ * challenge exists but has not been approved yet, so the client keeps polling.
+ */
+export interface RemoteWebPairingTokenPendingResponse {
+  status: "pending";
+  /** ISO-8601 instant the challenge expires. */
+  expiresAt: string;
+  /** Recommended poll interval (seconds) before the next exchange attempt. */
+  intervalSeconds: number;
+}
+
+/**
+ * `POST /v1/remote-web/pairing-token` approved response body (200) — carries
+ * the minted browser session credentials. The refresh token is delivered out
+ * of band as an `HttpOnly` cookie, not in this body.
+ */
+export interface RemoteWebPairingTokenApprovedResponse {
+  status: "approved";
+  accessToken: string;
+  /** ISO-8601 instant the access token expires. */
+  accessTokenExpiresAt: string;
+  /** ISO-8601 instant after which the client should refresh the session. */
+  refreshAfter: string;
+  guardianId: string;
+  assistantId: string;
+}
+
+/** Union of the two terminal `pairing-token` response bodies. */
+export type RemoteWebPairingTokenResponse =
+  | RemoteWebPairingTokenPendingResponse
+  | RemoteWebPairingTokenApprovedResponse;
+
+// ── Shared pairing URL helpers ──────────────────────────────────────────────
+//
+// Every surface that mints a pairing (the `vellum pair --qr` CLI, the web
+// settings "Pair a device" card) must accept the same public URLs and build
+// the same scannable links. The helpers are environment-neutral (WHATWG URL
+// only) so both Node and browser callers share one implementation.
+
+/** Why a public base URL can't be advertised in a pairing challenge. */
+export type PublicBaseUrlRejection =
+  | "unparseable"
+  | "loopback"
+  | "non-https"
+  | "service-website";
+
+export type PublicBaseUrlResult =
+  | { ok: true; url: string }
+  | { ok: false; reason: PublicBaseUrlRejection };
+
+/**
+ * Hosts that are a tunnel/ingress vendor's own website, not a user's assistant
+ * endpoint. These are the tunnel vendors our docs mention, and their sites are
+ * exactly where a lost user grabs a URL from — e.g. a Tailscale admin invite
+ * link (`login.tailscale.com/admin/invite/…`), which is https and non-loopback
+ * and so clears every other check. Pairing refuses them with a targeted message
+ * rather than minting a challenge the scanning device can never reach.
+ */
+export const TUNNEL_PROVIDER_WEBSITE_HOSTS = [
+  "login.tailscale.com",
+  "tailscale.com",
+  "www.tailscale.com",
+  "ngrok.com",
+  "dashboard.ngrok.com",
+  "dash.cloudflare.com",
+  "cloudflare.com",
+  "www.cloudflare.com",
+] as const;
+
+/**
+ * A URL whose exact host is a tunnel/ingress vendor's own website (see
+ * {@link TUNNEL_PROVIDER_WEBSITE_HOSTS}). Exact-host only: a user's real
+ * Tailscale endpoint (`*.ts.net`) or Cloudflare-fronted domain is never a
+ * listed host, so a legitimate address is never mistaken for a vendor site.
+ */
+export function isTunnelProviderWebsiteUrl(url: string): boolean {
+  let hostname: string;
+  try {
+    // WHATWG URL lowercases the hostname during parsing.
+    hostname = new URL(url).hostname;
+  } catch {
+    return false;
+  }
+  return (TUNNEL_PROVIDER_WEBSITE_HOSTS as readonly string[]).includes(
+    hostname,
+  );
+}
+
+/**
+ * The display name of the tunnel/ingress vendor a service-website URL points
+ * at (`"Tailscale"` / `"ngrok"` / `"Cloudflare"`), or null when the host is not
+ * a known vendor site. Drives the "This is <Name>'s website" pairing guidance.
+ */
+export function tunnelProviderWebsiteName(url: string): string | null {
+  let hostname: string;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return null;
+  }
+  if (
+    !(TUNNEL_PROVIDER_WEBSITE_HOSTS as readonly string[]).includes(hostname)
+  ) {
+    return null;
+  }
+  if (hostname.includes("tailscale")) return "Tailscale";
+  if (hostname.includes("ngrok")) return "ngrok";
+  if (hostname.includes("cloudflare")) return "Cloudflare";
+  return null;
+}
+
+/**
+ * A loopback URL — `localhost`, `[::1]`, or `127.x.x.x`. A pairing link that
+ * encodes a loopback address is unreachable from the scanning device.
+ */
+export function isLoopbackPublicUrl(url: string): boolean {
+  try {
+    // WHATWG URL canonicalizes hostnames, so IPv6 loopback is always "[::1]".
+    const hostname = new URL(url).hostname;
+    return (
+      hostname === "localhost" ||
+      hostname === "[::1]" ||
+      /^127(?:\.\d{1,3}){3}$/.test(hostname)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Normalize an address to the public base a scanning device opens:
+ * query/hash stripped, the `assistant` path segment (and everything after it)
+ * removed so a pasted pair-page URL collapses to its base, and trailing
+ * slashes trimmed. Throws if the value is not a parseable URL.
+ */
+export function normalizePublicBaseUrl(value: string): string {
+  const url = new URL(value);
+  url.search = "";
+  url.hash = "";
+  const parts = url.pathname.split("/").filter(Boolean);
+  const assistantIndex = parts.indexOf("assistant");
+  if (assistantIndex >= 0) {
+    parts.splice(assistantIndex);
+  }
+  url.pathname = parts.length ? `/${parts.join("/")}` : "/";
+  return url.toString().replace(/\/+$/, "");
+}
+
+/**
+ * Resolve an address to the public https base URL to advertise in a pairing
+ * challenge, or report why it can't be used. Loopback and non-https links are
+ * refused with a specific reason callers turn into their own guidance.
+ */
+export function resolvePublicBaseUrl(raw: string): PublicBaseUrlResult {
+  let normalized: string;
+  try {
+    normalized = normalizePublicBaseUrl(raw);
+  } catch {
+    return { ok: false, reason: "unparseable" };
+  }
+  if (isLoopbackPublicUrl(normalized)) {
+    return { ok: false, reason: "loopback" };
+  }
+  if (isTunnelProviderWebsiteUrl(normalized)) {
+    return { ok: false, reason: "service-website" };
+  }
+  if (new URL(normalized).protocol !== "https:") {
+    return { ok: false, reason: "non-https" };
+  }
+  return { ok: true, url: normalized };
+}
+
+/**
+ * The scannable pair URL: the challenge's verification URI with the device
+ * code carried in the fragment (`#device_code=…`), matching what the pair
+ * page reads on load. Fragments never reach the wire.
+ */
+export function buildRemoteWebPairingUrl(
+  challenge: Pick<
+    RemoteWebPairingChallengeResponse,
+    "verificationUri" | "deviceCode"
+  >,
+): string {
+  const url = new URL(challenge.verificationUri);
+  url.hash = new URLSearchParams({
+    device_code: challenge.deviceCode,
+  }).toString();
+  return url.toString();
+}

package/node_modules/@vellumai/service-contracts/src/rpc.ts

@@ -0,0 +1,234 @@
+/**
+ * CES RPC method contracts.
+ *
+ * Defines the request and response schemas for every RPC method in the
+ * assistant-to-CES wire protocol. Each method has a canonical string
+ * name, a request schema, and a response schema.
+ *
+ * Methods:
+ *
+ * **Lifecycle**
+ * - `update_managed_credential` — Push an updated API key to CES after hatch
+ *
+ * **Credential CRUD**
+ * - `get_credential` — Retrieve a credential by account name
+ * - `set_credential` — Store or update a credential
+ * - `delete_credential` — Delete a credential by account name
+ * - `list_credentials` — List all credential account names
+ * - `bulk_set_credentials` — Store multiple credentials at once
+ */
+
+import { z } from "zod";
+import { RpcErrorSchema } from "./error.js";
+
+// ---------------------------------------------------------------------------
+// Method name constants
+// ---------------------------------------------------------------------------
+
+export const CesRpcMethod = {
+  /** Push an updated assistant credential to CES after post-hatch provisioning. */
+  UpdateManagedCredential: "update_managed_credential",
+  /** Retrieve a single credential by account name. */
+  GetCredential: "get_credential",
+  /** Store or update a credential by account name. */
+  SetCredential: "set_credential",
+  /** Delete a credential by account name. */
+  DeleteCredential: "delete_credential",
+  /** List all credential account names. */
+  ListCredentials: "list_credentials",
+  /** Bulk-import credentials (set multiple at once). */
+  BulkSetCredentials: "bulk_set_credentials",
+} as const;
+
+export type CesRpcMethod = (typeof CesRpcMethod)[keyof typeof CesRpcMethod];
+
+// ---------------------------------------------------------------------------
+// update_managed_credential
+// ---------------------------------------------------------------------------
+
+export const UpdateManagedCredentialSchema = z.object({
+  /** The assistant API key to push to CES for platform credential materialization. */
+  assistantApiKey: z.string(), // nosemgrep: not-a-secret
+  /**
+   * Optional platform assistant ID. In warm-pool mode the ID may not be
+   * available at CES startup; the assistant pushes it here once provisioned.
+   */
+  assistantId: z.string().optional(),
+});
+export type UpdateManagedCredential = z.infer<
+  typeof UpdateManagedCredentialSchema
+>;
+
+export const UpdateManagedCredentialResponseSchema = z.object({
+  /** Whether the managed credential was successfully updated. */
+  updated: z.boolean(),
+});
+export type UpdateManagedCredentialResponse = z.infer<
+  typeof UpdateManagedCredentialResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// get_credential
+// ---------------------------------------------------------------------------
+
+export const GetCredentialSchema = z.object({
+  /** The account name to look up. */
+  account: z.string(),
+});
+export type GetCredential = z.infer<typeof GetCredentialSchema>;
+
+export const GetCredentialResponseSchema = z.object({
+  /** Whether the credential was found. */
+  found: z.boolean(),
+  /** The credential value (present only when found). */
+  value: z.string().optional(),
+});
+export type GetCredentialResponse = z.infer<typeof GetCredentialResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// set_credential
+// ---------------------------------------------------------------------------
+
+export const SetCredentialSchema = z.object({
+  /** The account name to store the credential under. */
+  account: z.string(),
+  /** The credential value to store. */
+  value: z.string(),
+});
+export type SetCredential = z.infer<typeof SetCredentialSchema>;
+
+export const SetCredentialResponseSchema = z.object({
+  /** Whether the credential was successfully stored. */
+  ok: z.boolean(),
+});
+export type SetCredentialResponse = z.infer<typeof SetCredentialResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// delete_credential
+// ---------------------------------------------------------------------------
+
+export const DeleteCredentialSchema = z.object({
+  /** The account name to delete. */
+  account: z.string(),
+});
+export type DeleteCredential = z.infer<typeof DeleteCredentialSchema>;
+
+export const DeleteCredentialResponseSchema = z.object({
+  /** The result of the delete operation. */
+  result: z.enum(["deleted", "not-found", "error"]),
+});
+export type DeleteCredentialResponse = z.infer<
+  typeof DeleteCredentialResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// list_credentials
+// ---------------------------------------------------------------------------
+
+export const ListCredentialsSchema = z.object({});
+export type ListCredentials = z.infer<typeof ListCredentialsSchema>;
+
+export const ListCredentialsResponseSchema = z.object({
+  /** The account names of all stored credentials. */
+  accounts: z.array(z.string()),
+});
+export type ListCredentialsResponse = z.infer<
+  typeof ListCredentialsResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// bulk_set_credentials
+// ---------------------------------------------------------------------------
+
+export const BulkSetCredentialsSchema = z.object({
+  /** Array of credentials to set in bulk. */
+  credentials: z.array(
+    z.object({
+      /** The account name to store the credential under. */
+      account: z.string(),
+      /** The credential value to store. */
+      value: z.string(),
+    }),
+  ),
+});
+export type BulkSetCredentials = z.infer<typeof BulkSetCredentialsSchema>;
+
+export const BulkSetCredentialsResponseSchema = z.object({
+  /** Per-credential results indicating success or failure. */
+  results: z.array(
+    z.object({
+      /** The account name that was set. */
+      account: z.string(),
+      /** Whether the credential was successfully stored. */
+      ok: z.boolean(),
+    }),
+  ),
+});
+export type BulkSetCredentialsResponse = z.infer<
+  typeof BulkSetCredentialsResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Full RPC contract type map
+// ---------------------------------------------------------------------------
+
+/**
+ * Type-level mapping from RPC method names to their request and response
+ * schemas. Useful for building type-safe RPC dispatch layers.
+ */
+export interface CesRpcContract {
+  [CesRpcMethod.UpdateManagedCredential]: {
+    request: UpdateManagedCredential;
+    response: UpdateManagedCredentialResponse;
+  };
+  [CesRpcMethod.GetCredential]: {
+    request: GetCredential;
+    response: GetCredentialResponse;
+  };
+  [CesRpcMethod.SetCredential]: {
+    request: SetCredential;
+    response: SetCredentialResponse;
+  };
+  [CesRpcMethod.DeleteCredential]: {
+    request: DeleteCredential;
+    response: DeleteCredentialResponse;
+  };
+  [CesRpcMethod.ListCredentials]: {
+    request: ListCredentials;
+    response: ListCredentialsResponse;
+  };
+  [CesRpcMethod.BulkSetCredentials]: {
+    request: BulkSetCredentials;
+    response: BulkSetCredentialsResponse;
+  };
+}
+
+/**
+ * Schema lookup map for runtime validation of RPC payloads.
+ */
+export const CesRpcSchemas = {
+  [CesRpcMethod.UpdateManagedCredential]: {
+    request: UpdateManagedCredentialSchema,
+    response: UpdateManagedCredentialResponseSchema,
+  },
+  [CesRpcMethod.GetCredential]: {
+    request: GetCredentialSchema,
+    response: GetCredentialResponseSchema,
+  },
+  [CesRpcMethod.SetCredential]: {
+    request: SetCredentialSchema,
+    response: SetCredentialResponseSchema,
+  },
+  [CesRpcMethod.DeleteCredential]: {
+    request: DeleteCredentialSchema,
+    response: DeleteCredentialResponseSchema,
+  },
+  [CesRpcMethod.ListCredentials]: {
+    request: ListCredentialsSchema,
+    response: ListCredentialsResponseSchema,
+  },
+  [CesRpcMethod.BulkSetCredentials]: {
+    request: BulkSetCredentialsSchema,
+    response: BulkSetCredentialsResponseSchema,
+  },
+} as const;