@vellumai/cli 0.10.11-dev.202607242127.a6bf2b2 → 0.10.11-staging.2

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

@@ -1,260 +0,0 @@
-/**
- * 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

@@ -1,234 +0,0 @@
-/**
- * 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;