failproofai 1.0.7-beta.2 → 1.0.8-beta.0

package/src/hooks/semantic/jev-config.ts

@@ -49,17 +49,64 @@
  * microseconds, and it means `failproofai jev setup` / `remove` take effect on
  * the very next tool call — including inside the long-lived daemon worker —
  * with no restart and no stale state to reason about.
+ *
+ * # FailproofAI Cloud (`provider: "failproofai"`)
+ *
+ * The one provider whose key is NOT in this file. `failproofai config --token`
+ * with a key carrying `jev:evaluate` stores that key in the `jev` slot of
+ * `credentials.json` and, when there is no `jev.json` yet, writes one naming
+ * this provider, the Cloud origin + `/enforcement/v1/jev` and `mode: "shadow"`.
+ * So for this provider:
+ *
+ * - the key comes from `credentials.json` (`readJevCloudCredential`), read with
+ *   the same owner-only file, directory and size checks this file gets — a
+ *   loose credentials file is refused, not read, and Jev is off;
+ * - an `apiKey` in `jev.json` makes the file invalid, and
+ *   `FAILPROOFAI_JEV_API_KEY` is ignored: the Cloud key has exactly one home,
+ *   so disconnecting or rotating it can never leave a second copy steering Jev;
+ * - `baseUrl` is required, and its ORIGIN must equal the origin the credential
+ *   was verified against (`jev.url`). The key is only ever sent where it was
+ *   issued, and both halves of that decision live in global files.
+ * - the credential counts only while the connection it came with is still on
+ *   this machine: a policy or reporting credential on the SAME origin holding
+ *   the SAME key, in the same file (`readJevCloudCredential`). A slot an older
+ *   build's disconnect left behind is not a connection, and neither is one an
+ *   older build's reconnect with another key (on hosted FailproofAI Cloud,
+ *   possibly another org's, on the same origin) left beside it.
+ * - no usable credential is `not-connected` when the machine has no FailproofAI
+ *   Cloud connection at all, and `key-lacks-jev` when it has one whose key does
+ *   not carry `jev:evaluate` (connected with such a key, or the slot was
+ *   cleared on a reconnect). Jev is off either way; the two remedies differ.
+ *
+ * # `mode: "off"`
+ *
+ * Every provider accepts `off | shadow | enforce`. `off` keeps the file — the
+ * endpoint, and for BYOK the key — while Jev does not run at all:
+ * `loadJevConfig` returns null exactly as for an absent file. It exists so the
+ * dashboard can switch the Cloud route off without deleting the file that
+ * `config --token` will never rewrite. An older build reads `off` as an
+ * invalid mode, which is also off.
  */
 import { closeSync, constants as fsConstants, fstatSync, openSync, readSync, statSync } from "node:fs";
 import { dirname } from "node:path";
+import { readJevCloudCredential, type JevCloudCredential } from "../fp-config";
 import { jevConfigFile } from "../fp-home";
 
-export type JevProviderKind = "typesafe" | "openrouter" | "vercel" | "cloudflare" | "custom";
+export type { JevCloudCredential } from "../fp-config";
+
+export type JevProviderKind = "typesafe" | "openrouter" | "vercel" | "cloudflare" | "custom" | "failproofai";
+
+/** `off` does not run Jev at all; `shadow` logs Jev and enforces regex; `enforce` applies the combine rules. */
+export type JevConfigMode = "off" | "shadow" | "enforce";
 
 export interface JevConfig {
   provider: JevProviderKind;
+  /**
+   * The bearer key. For `failproofai` it is never in the FILE: the loader fills
+   * it from the `jev` slot of `credentials.json` (see the header).
+   */
   apiKey: string;
-  /** Required for `custom`; an optional override otherwise. */
+  /** Required for `custom` and `failproofai`; an optional override otherwise. */
   baseUrl?: string;
   /** `cloudflare` only. */
   accountId?: string;
@@ -67,13 +114,49 @@ export interface JevConfig {
   model?: string;
   /** Default 3000; the reasoning is on `DEFAULT_JEV_TIMEOUT_MS` in `evaluator.ts`. */
   timeoutMs?: number;
-  /** `shadow` logs Jev and enforces regex; `enforce` applies the combine rules. Default `enforce`. */
-  mode?: "shadow" | "enforce";
+  /**
+   * Default `enforce`. `off` is accepted in a file but never reaches the hook
+   * path: `loadJevConfig` returns null for it.
+   */
+  mode?: JevConfigMode;
+  /**
+   * `failproofai` only: the origin of the Cloud credential this config was
+   * validated against — the one place its key may be sent. Set by
+   * `validateJevConfig` from the credential it was handed, never read from a
+   * file (a `credentialOrigin` in `jev.json` is an unknown key, ignored), and
+   * checked again by `validateLoadedJevConfig` before any route or transport
+   * is built. A Cloud config assembled by hand without it is refused there.
+   */
+  credentialOrigin?: string;
 }
 
-export const DEFAULT_JEV_MODE: NonNullable<JevConfig["mode"]> = "enforce";
+export const DEFAULT_JEV_MODE: "shadow" | "enforce" = "enforce";
+
+export const JEV_PROVIDER_KINDS: readonly JevProviderKind[] = ["typesafe", "openrouter", "vercel", "cloudflare", "custom", "failproofai"];
+
+/** The provider whose key comes from this machine's FailproofAI Cloud connection. */
+export const JEV_CLOUD_PROVIDER = "failproofai" as const satisfies JevProviderKind;
+
+/**
+ * Where FailproofAI Cloud serves Jev, under the Cloud origin. The transport
+ * appends `/systemone` (`nativeEndpoint`), so the route is
+ * `POST <origin>/enforcement/v1/jev/systemone`.
+ */
+export const JEV_CLOUD_BASE_PATH = "/enforcement/v1/jev";
 
-export const JEV_PROVIDER_KINDS: readonly JevProviderKind[] = ["typesafe", "openrouter", "vercel", "cloudflare", "custom"];
+/**
+ * The `baseUrl` `config --token` writes for the Cloud base it connected to.
+ *
+ * Built the way every other Cloud route is — `<base>/enforcement/v1/…`, as the
+ * desired-state pull does (`cloud-enrollment.ts`) — so a self-hosted Cloud
+ * served under a path prefix gets its Jev route under the same prefix. For the
+ * hosted product the base IS the origin. Query and fragment are dropped: a base
+ * never carries either (`validateCloudUrl`).
+ */
+export function jevCloudBaseUrl(cloudBase: string): string {
+  const url = new URL(cloudBase);
+  return `${url.origin}${url.pathname.replace(/\/+$/, "")}${JEV_CLOUD_BASE_PATH}`;
+}
 
 /** The env var that may supply the key (and nothing else) when the file carries none. */
 export const JEV_API_KEY_ENV = "FAILPROOFAI_JEV_API_KEY";
@@ -160,8 +243,11 @@ export type ValidationResult<T> =
    * carries no `apiKey` and `FAILPROOFAI_JEV_API_KEY` is unset here. Callers
    * that can tell those apart (`inspectJevConfig`, and `jev status` through it)
    * use the flag rather than matching on `problem`.
+   *
+   * `notConnected` is its FailproofAI Cloud twin: the file names the Cloud
+   * provider and this machine holds no Jev credential for it.
    */
-  | { ok: false; problem: string; missingKey?: true };
+  | { ok: false; problem: string; missingKey?: true; notConnected?: true };
 
 /** A key is visible ASCII, one line, at most 4 KiB. The message never includes the key. */
 export function validateApiKey(key: unknown): string | null {
@@ -170,11 +256,62 @@ export function validateApiKey(key: unknown): string | null {
   return null;
 }
 
+/**
+ * Query parameter names that carry a CREDENTIAL rather than a routing choice.
+ *
+ * Matched on the parameter's name with everything but letters and digits
+ * removed, so `api_key`, `api-key`, `X-Api-Key` and `apiKey` are one rule
+ * rather than four — and `?api-version=`, the parameter the query string is
+ * permitted for in the first place, matches none of them.
+ *
+ * Substrings, because the real names are compounds: `access_token`,
+ * `subscription-key`, `authToken`, `x-functions-key`. The short ones that have
+ * no word to be a substring of are matched whole instead.
+ */
+const CREDENTIAL_PARAM_PARTS = ["key", "token", "secret", "password", "passwd", "credential", "auth", "signature"] as const;
+const CREDENTIAL_PARAM_NAMES = new Set(["pw", "pass", "sig", "sid", "jwt", "bearer", "session", "code", "access"]);
+
+/** A parameter name safe to quote back: it goes into a message the CLI prints. */
+const QUOTABLE_PARAM_RE = /^[A-Za-z0-9._-]{1,40}$/;
+
+/**
+ * Why a base URL's query string may not be stored, or null when it may.
+ *
+ * A credential in a base URL is a mistake wherever it ends up, because the
+ * config file already has an `apiKey` field that is sent as a bearer and never
+ * printed — while the endpoint DERIVED from the base URL is logged, printed by
+ * `jev status`, put in error messages and returned to the dashboard. So this
+ * refuses the credential at the door rather than eliding it on the way out:
+ * eliding leaves the secret in the file and in everything the file feeds.
+ *
+ * It refuses on the parameter NAME, not on the presence of a query, because
+ * some proxies genuinely route on one (`?api-version=`) — see the comment on
+ * the normalization below. The VALUE is checked too, through the same
+ * `looksLikeCredential` that refuses a key pasted into `--model`: a parameter
+ * called `t` whose value is `sk-…` is the same mistake under a name no list
+ * can carry. A false refusal there turns Jev off and leaves the regex tier
+ * enforcing, which is the direction this whole module errs in.
+ */
+function credentialQueryProblem(url: URL): string | null {
+  for (const [name, value] of url.searchParams) {
+    const shown = QUOTABLE_PARAM_RE.test(name) ? `?${name}=` : "one of its query parameters";
+    const flat = name.toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (CREDENTIAL_PARAM_PARTS.some((part) => flat.includes(part)) || CREDENTIAL_PARAM_NAMES.has(flat)) {
+      return `baseUrl must not carry a credential in its query string, and ${shown} is one; put the key in the key field`;
+    }
+    if (looksLikeCredential(value)) {
+      return `baseUrl's ${shown} value is shaped like a credential (not repeated here); put the key in the key field`;
+    }
+  }
+  return null;
+}
+
 /**
  * An endpoint base URL: https, or http to a loopback host only (a local proxy).
- * No credentials in the URL and no fragment — a key belongs in the key field,
- * where it is sent as a bearer and never printed. `validateJevConfig` further
- * accepts the loopback http form only in shadow mode.
+ * No credentials in the URL — not as userinfo, not as a query parameter — and no
+ * fragment, because a key belongs in the key field, where it is sent as a bearer
+ * and never printed. `validateJevConfig` further accepts the loopback http form
+ * only in shadow mode.
  */
 export function validateBaseUrl(raw: unknown): ValidationResult<string> {
   if (typeof raw !== "string" || raw.trim() === "") return { ok: false, problem: "baseUrl must be a non-empty string" };
@@ -189,6 +326,8 @@ export function validateBaseUrl(raw: unknown): ValidationResult<string> {
   }
   if (url.username || url.password) return { ok: false, problem: "baseUrl must not carry credentials; put the key in the key field" };
   if (url.hash) return { ok: false, problem: "baseUrl must not have a #fragment" };
+  const credentialQuery = credentialQueryProblem(url);
+  if (credentialQuery) return { ok: false, problem: credentialQuery };
   // Trailing slashes come off the PATH, never the string: a query string is legal
   // (some proxies want `?api-version=`), and the endpoint path is appended to
   // the pathname, so it must never end up inside the query.
@@ -196,6 +335,137 @@ export function validateBaseUrl(raw: unknown): ValidationResult<string> {
   return { ok: true, value: url.toString() };
 }
 
+export interface BaseUrlWithoutQuery {
+  /** The URL with any `?query` taken off. */
+  url: string;
+  /** Whether there was one to take off. */
+  hadQuery: boolean;
+}
+
+/**
+ * A stored base URL with its query string (and any userinfo) removed, and
+ * whether it had a query.
+ *
+ * The refusal above is the source fix, and this is what makes the way OUT safe
+ * regardless: a file written by an older build can already carry `?token=`, and
+ * that file is exactly the one whose owner is being shown the URL so they can
+ * repair it. So nothing that crosses the wire to the dashboard, and nothing the
+ * CLI prints, carries a query string off a base URL — `displayEndpoint` does it
+ * for the derived endpoint, and this does it for the base URL itself.
+ *
+ * Takes a string rather than a `URL` because the callers that need it most are
+ * reading a REFUSED file, where the value may not parse at all. An unparseable
+ * one is cut at the first `?`, which is strictly more aggressive than parsing.
+ */
+export function baseUrlWithoutQuery(raw: string): BaseUrlWithoutQuery {
+  // Userinfo (`https://svc:<key>@host`) comes off as well: it is the other place
+  // a URL carries a credential, and `validateBaseUrl` refuses it for that reason.
+  try {
+    const url = new URL(raw);
+    if (!url.search && !url.username && !url.password) return { url: raw, hadQuery: false };
+    const hadQuery = url.search !== "";
+    url.search = "";
+    url.username = "";
+    url.password = "";
+    return { url: url.toString(), hadQuery };
+  } catch {
+    const cut = raw.indexOf("?");
+    const head = (cut < 0 ? raw : raw.slice(0, cut)).replace(/^([^:/?#]+:\/\/)[^/?#]*@/, "$1");
+    return { url: head, hadQuery: cut >= 0 };
+  }
+}
+
+/**
+ * Path suffixes that are an ENDPOINT, never a base. Longest first, so
+ * `/v1/chat/completions` strips back to `/v1` rather than to `/v1/chat`.
+ *
+ * `/systemone` is this product's own suffix; the other four are what an OpenAI-
+ * compatible base serves. Every one of them is the LAST segment of a request URL
+ * whose base is its parent, which is what makes the repair unambiguous.
+ */
+const ENDPOINT_SUFFIXES = ["/chat/completions", "/systemone", "/completions", "/embeddings", "/models"] as const;
+
+export interface EndpointGivenAsBase {
+  /** The suffix that gave it away, e.g. `/models`. */
+  suffix: string;
+  /** The base that was probably meant: the same URL with the suffix taken off. */
+  base: string;
+}
+
+/**
+ * Whether a URL is obviously an endpoint rather than an API base, and the base it
+ * implies.
+ *
+ * This is checked where a URL is being saved (`jev setup`, the dashboard's save),
+ * and deliberately not in `validateBaseUrl`: a config already on disk that names
+ * an endpoint as its base keeps working
+ * (`nativeEndpoint` does not append a second `/systemone`), and turning Jev off on
+ * an upgrade for a file that was routing correctly would be a worse failure than
+ * the one this prevents.
+ *
+ * What it prevents: `--url https://…/typesafe/v1/models` was saved without
+ * complaint, requests then went to `…/v1/models/systemone`, and the only signal
+ * was `http-404: Not Found` from `jev test`. The CLI knows `/systemone` is its own
+ * suffix and that a provider's base ends at a version root, so it can say so
+ * before anything is written.
+ */
+export function endpointGivenAsBase(url: string): EndpointGivenAsBase | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  const path = parsed.pathname.replace(/\/+$/, "");
+  const suffix = ENDPOINT_SUFFIXES.find((s) => path.toLowerCase().endsWith(s));
+  if (suffix === undefined) return null;
+  parsed.pathname = path.slice(0, path.length - suffix.length) || "/";
+  return { suffix, base: parsed.toString() };
+}
+
+/**
+ * The provider each known host IS, so `failproofai jev --url <url>` needs no
+ * `--provider`. Exact hosts only: a neighbouring name (`eu.api.typesafe.ai`, a
+ * corporate proxy) is `custom`, which reaches the same TypeSafe-compatible API
+ * at the URL given, and `--provider` is there to say otherwise.
+ */
+const PROVIDER_BY_HOST: Readonly<Record<string, JevProviderKind>> = {
+  "api.typesafe.ai": "typesafe",
+  "openrouter.ai": "openrouter",
+  "ai-gateway.vercel.sh": "vercel",
+  "api.cloudflare.com": "cloudflare",
+};
+
+/** The provider a validated URL names, or `custom` for a host that is nobody's. */
+export function providerForUrl(url: string): JevProviderKind {
+  try {
+    return PROVIDER_BY_HOST[new URL(url).hostname.toLowerCase()] ?? "custom";
+  } catch {
+    return "custom";
+  }
+}
+
+/**
+ * Why `provider` cannot be saved with a base on `url`'s host, or null.
+ *
+ * Two pairs: a provider the host says it is not (`openrouter` on Vercel's
+ * gateway — the two disagree about where the key is sent), and `custom` on
+ * Cloudflare, whose per-account, wrapped endpoint a custom route cannot speak.
+ * `custom` on any other known host is "treat this URL as itself", not a
+ * disagreement. Checked where a URL is saved (`jev --url`, `jev setup
+ * --base-url`, the dashboard's save) and, like `endpointGivenAsBase`, not by
+ * the loader: a file already on disk keeps working.
+ */
+export function providerHostConflict(provider: string, url: string): string | null {
+  const known = providerForUrl(url);
+  if (known === "custom" || known === provider) return null;
+  const host = new URL(url).host;
+  if (provider !== "custom") return `${host} is ${known}'s endpoint, not ${provider}'s`;
+  return known === "cloudflare"
+    ? `${host} is Cloudflare Workers AI, which provider custom cannot reach — its endpoint is per-account and its answers are wrapped, and a custom endpoint is asked in TypeSafe's own shape at <url>/systemone`
+    : null;
+}
+
 function isPlainHttp(url: string): boolean {
   try {
     return new URL(url).protocol === "http:";
@@ -204,6 +474,21 @@ function isPlainHttp(url: string): boolean {
   }
 }
 
+/**
+ * The origin a bearer token would be sent to: https, or http to a loopback host
+ * — the same schemes `validateBaseUrl` admits. Null for anything else, so a
+ * credential naming some other scheme matches no base URL at all.
+ */
+function originOf(raw: string): string | null {
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname))) return null;
+    return url.origin;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Prefixes real credentials carry: OpenAI / OpenRouter / Anthropic / Stripe
  * (`sk-`, `sk_`, `rk_`), GitHub, GitLab, Slack, AWS, Google, Hugging Face and
@@ -223,6 +508,16 @@ export function looksLikeCredential(s: string): boolean {
   return s.length >= 32 && !s.includes("/") && !/jev/i.test(s) && /[A-Za-z]/.test(s) && /[0-9]/.test(s);
 }
 
+/**
+ * Whether a string is shaped like a model id. Used on names that came back from
+ * a provider's `/models` endpoint and are about to be printed: those are remote
+ * strings, so anything carrying a control character, an ANSI escape or a
+ * kilobyte of padding is dropped rather than rendered.
+ */
+export function isModelIdShaped(s: string): boolean {
+  return MODEL_RE.test(s);
+}
+
 function validateModel(raw: unknown): ValidationResult<string> {
   if (typeof raw !== "string" || !MODEL_RE.test(raw)) {
     return { ok: false, problem: "model must be 1–200 characters of letters, digits and . _ : / @ ~ + -" };
@@ -254,8 +549,17 @@ function validateModel(raw: unknown): ValidationResult<string> {
  * `envKey` is the value of `FAILPROOFAI_JEV_API_KEY`, used only when the object
  * has no `apiKey`. Unknown top-level keys are ignored so a newer failproofai's
  * file does not switch Jev off on an older one. Problems never quote the key.
+ *
+ * `cloud` is the `jev` slot of `credentials.json`, and is read ONLY for the
+ * FailproofAI Cloud provider, which takes its key from nowhere else: not the
+ * file (an `apiKey` there is refused) and not `envKey` (ignored). The file's
+ * `baseUrl` must sit on the origin the credential was verified against.
  */
-export function validateJevConfig(raw: unknown, envKey?: string | null): ValidationResult<JevConfig> {
+export function validateJevConfig(
+  raw: unknown,
+  envKey?: string | null,
+  cloud?: JevCloudCredential | null,
+): ValidationResult<JevConfig> {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { ok: false, problem: "the file must hold a JSON object" };
   const o = raw as Record<string, unknown>;
 
@@ -266,7 +570,31 @@ export function validateJevConfig(raw: unknown, envKey?: string | null): Validat
   const kind = provider as JevProviderKind;
 
   let apiKey: string;
-  if (o.apiKey !== undefined) {
+  if (kind === JEV_CLOUD_PROVIDER) {
+    // One home for the Cloud key, so revoking it at disconnect cannot leave a
+    // copy behind that keeps Jev spending — and so nothing a session can set
+    // (the environment) or a second file can hold decides which key is sent.
+    if (o.apiKey !== undefined) {
+      return {
+        ok: false,
+        problem:
+          "provider failproofai takes its key from this machine's FailproofAI Cloud connection (credentials.json), " +
+          "never from jev.json — remove apiKey from the file (not repeated here)",
+      };
+    }
+    if (!cloud) {
+      return {
+        ok: false,
+        problem:
+          "this machine is not connected to FailproofAI Cloud with a key that carries jev:evaluate — " +
+          "connect it with: failproofai config --token <key>",
+        notConnected: true,
+      };
+    }
+    const bad = validateApiKey(cloud.key);
+    if (bad) return { ok: false, problem: `the FailproofAI Cloud key in credentials.json is unusable: ${bad}` };
+    apiKey = cloud.key;
+  } else if (o.apiKey !== undefined) {
     const bad = validateApiKey(o.apiKey);
     if (bad) return { ok: false, problem: bad };
     apiKey = o.apiKey as string;
@@ -288,8 +616,30 @@ export function validateJevConfig(raw: unknown, envKey?: string | null): Validat
     const r = validateBaseUrl(o.baseUrl);
     if (!r.ok) return r;
     cfg.baseUrl = r.value;
-  } else if (kind === "custom") {
-    return { ok: false, problem: "provider custom needs a baseUrl" };
+  } else if (kind === "custom" || kind === JEV_CLOUD_PROVIDER) {
+    return { ok: false, problem: `provider ${kind} needs a baseUrl` };
+  }
+
+  if (kind === JEV_CLOUD_PROVIDER && cloud) {
+    // The key goes only to the origin it was issued for. Compared as origins
+    // (scheme + host + port), which is what decides where a bearer token lands;
+    // the path under it is the Cloud's own routing.
+    const credentialOrigin = originOf(cloud.url);
+    const baseOrigin = originOf(cfg.baseUrl as string);
+    if (credentialOrigin === null) {
+      return { ok: false, problem: "the FailproofAI Cloud credential in credentials.json names no usable origin — reconnect: failproofai config --token <key>" };
+    }
+    if (baseOrigin !== credentialOrigin) {
+      return {
+        ok: false,
+        problem:
+          `baseUrl is on ${baseOrigin ?? "an unusable origin"}, but this machine's FailproofAI Cloud key was issued for ${credentialOrigin} — ` +
+          "the key is only ever sent to the origin it was issued for. Point jev.json back at it: failproofai jev setup --provider failproofai",
+      };
+    }
+    // Carried with the config, so the check can be made again — for real —
+    // wherever the config is used (`validateLoadedJevConfig`).
+    cfg.credentialOrigin = credentialOrigin;
   }
 
   if (kind === "cloudflare") {
@@ -317,7 +667,7 @@ export function validateJevConfig(raw: unknown, envKey?: string | null): Validat
   }
 
   if (o.mode !== undefined) {
-    if (o.mode !== "shadow" && o.mode !== "enforce") return { ok: false, problem: 'mode must be "shadow" or "enforce"' };
+    if (o.mode !== "off" && o.mode !== "shadow" && o.mode !== "enforce") return { ok: false, problem: 'mode must be "off", "shadow" or "enforce"' };
     cfg.mode = o.mode;
   }
 
@@ -325,25 +675,107 @@ export function validateJevConfig(raw: unknown, envKey?: string | null): Validat
   // authenticates the server there: while the local proxy is down, any process
   // of this user — the agent being judged included — can bind its port and
   // answer "none" to every question. In enforce mode that answer clears
-  // reviewable denies; in shadow mode it changes nothing, so that is the only
-  // mode it is accepted in.
-  if (cfg.baseUrl !== undefined && isPlainHttp(cfg.baseUrl) && cfg.mode !== "shadow") {
+  // reviewable denies; in shadow mode it changes nothing, and `off` sends
+  // nothing at all, so enforce is the one mode it is refused in.
+  if (cfg.baseUrl !== undefined && isPlainHttp(cfg.baseUrl) && cfg.mode === "enforce") {
     return {
       ok: false,
       problem:
         "plain http (to localhost) is accepted only with mode shadow: in enforce mode Jev's answers can clear a deny, " +
-        "and while the local proxy is down any process on this machine could take its port and answer. Use https, or mode shadow",
+        "and while the local proxy is down any process on this machine could take its port and answer. " +
+        (cfg.provider === JEV_CLOUD_PROVIDER
+          ? "Reconnect to an https FailproofAI Cloud URL (failproofai config --token <key> --url https://…), or keep mode shadow"
+          : "Use https, or mode shadow"),
     };
   }
 
   return { ok: true, value: cfg };
 }
 
+/**
+ * Re-validate a config that was already LOADED — by `loadJevConfig` or
+ * `inspectJevConfig` — before a route or a transport is built from it.
+ *
+ * For every BYOK provider that is `validateJevConfig` as it always was. The
+ * FailproofAI Cloud provider is the one whose in-memory `apiKey` is not a file
+ * field: the loader filled it from `credentials.json`, and `validateJevConfig`
+ * would refuse the very key it put there as a file's `apiKey`. So the key goes
+ * back in the credential slot — under `credentialOrigin`, the origin of the
+ * credential the loader validated against, which the loader recorded on the
+ * config. The origin check therefore runs again, for real: a config whose
+ * `baseUrl` has since moved to another origin is refused, and so is a Cloud
+ * config assembled by hand with no `credentialOrigin` at all, so a future
+ * caller cannot build one and skip the check. (Display-only callers that build
+ * a stand-in on purpose name the origin they mean explicitly.)
+ */
+export function validateLoadedJevConfig(cfg: JevConfig): ValidationResult<JevConfig> {
+  if (cfg.provider !== JEV_CLOUD_PROVIDER) return validateJevConfig(cfg);
+  const { apiKey, credentialOrigin, ...rest } = cfg;
+  if (typeof credentialOrigin !== "string" || credentialOrigin === "") {
+    return {
+      ok: false,
+      problem: "this FailproofAI Cloud config names no credential origin — it did not come from the loader, so its key is not sent anywhere",
+    };
+  }
+  return validateJevConfig(rest, null, { url: credentialOrigin, key: apiKey });
+}
+
 // ── Loading ──────────────────────────────────────────────────────────────────
 
 export type JevConfigInspection =
   | { status: "absent"; path: string }
-  | { status: "ok"; path: string; mode: number | null; keySource: "file" | "env"; config: JevConfig }
+  | {
+      status: "ok";
+      path: string;
+      mode: number | null;
+      /** `cloud`: the `jev` slot of `credentials.json` (the FailproofAI Cloud provider). */
+      keySource: "file" | "env" | "cloud";
+      config: JevConfig;
+    }
+  | {
+      /**
+       * A sound file that says `mode: "off"`. Jev does not run — `loadJevConfig`
+       * returns null — and nothing is wrong: the owner switched it off and kept
+       * the endpoint (and, for BYOK, the key) for later. Reported apart from
+       * `absent` so `jev status` and the dashboard can say "switched off"
+       * rather than "not configured", and apart from `ok` so no reader that
+       * takes `ok` to mean "on" can be wrong about it.
+       */
+      status: "off";
+      path: string;
+      mode: number | null;
+      /** Everything the file says except the key. */
+      routing: Omit<JevConfig, "apiKey">;
+    }
+  | {
+      /**
+       * The file names the FailproofAI Cloud provider and is sound, but this
+       * machine holds no Jev credential (never connected with a `jev:evaluate`
+       * key, or disconnected since). Jev is off. The FailproofAI Cloud twin of
+       * `key-missing`: nothing is wrong with the FILE, so no reader should tell
+       * its owner to rewrite it.
+       */
+      status: "not-connected";
+      path: string;
+      mode: number | null;
+      routing: Omit<JevConfig, "apiKey">;
+      problem: string;
+    }
+  | {
+      /**
+       * The file names the FailproofAI Cloud provider and is sound, and this
+       * machine IS connected to FailproofAI Cloud — but with a key that does not
+       * carry `jev:evaluate` (connected with one, or reconnected with one since,
+       * which clears the slot). Jev is off. Apart from `not-connected` because
+       * telling a connected machine it is "not connected" sends its owner to
+       * reconnect with the same key, when the remedy is a key with Jev.
+       */
+      status: "key-lacks-jev";
+      path: string;
+      mode: number | null;
+      routing: Omit<JevConfig, "apiKey">;
+      problem: string;
+    }
   | {
       /**
        * The file is sound and names `FAILPROOFAI_JEV_API_KEY` as the key's
@@ -371,8 +803,22 @@ export type JevConfigInspection =
       problem: string;
       /** The command that fixes it, when one does. */
       fix?: string;
+      /** When the refusal is about credentials.json: that file's permission bits (`mode` stays jev.json's). */
+      credentialsMode?: number | null;
+      /** A too-open file with no key in it: refused as firmly, but no key was exposed. */
+      keyless?: true;
     };
 
+/** Whether config text is an object with no `apiKey`; anything else may hold one. */
+function namesNoKey(text: string): boolean {
+  try {
+    const o: unknown = JSON.parse(text);
+    return o !== null && typeof o === "object" && !Array.isArray(o) && (o as Record<string, unknown>).apiKey === undefined;
+  } catch {
+    return false;
+  }
+}
+
 function readEnvKey(): string | null {
   const v = process.env[JEV_API_KEY_ENV];
   return v === undefined || v === "" ? null : v;
@@ -442,14 +888,40 @@ export function inspectJevConfig(): JevConfigInspection {
     const st = fstatSync(fd);
     if (!st.isFile()) return { status: "refused", path, mode: null, reason: "unreadable", problem: "it is not a regular file" };
     mode = st.mode & 0o777;
+    const readText = (): string => {
+      const buf = Buffer.alloc(st.size);
+      let off = 0;
+      while (off < buf.length) {
+        const n = readSync(fd, buf, off, buf.length - off, off);
+        if (n === 0) break;
+        off += n;
+      }
+      return buf.subarray(0, off).toString("utf8");
+    };
     if (modesAreMeaningful() && (mode & 0o077) !== 0) {
+      // Read only to word the refusal: a file with no key in it (the Cloud's,
+      // whose key is in credentials.json, or a key-from-env one) is refused as
+      // firmly, but telling its owner a key leaked sends them to rotate one
+      // that never did.
+      let keyless = false;
+      try {
+        keyless = st.size <= MAX_CONFIG_BYTES && namesNoKey(readText());
+      } catch {
+        // Unreadable: it may hold one.
+      }
+      const perms = mode.toString(8).padStart(4, "0");
       return {
         status: "refused",
         path,
         mode,
         reason: "too-open",
-        problem: `its permissions are ${mode.toString(8).padStart(4, "0")}; it holds a key, so it must be owner-only (chmod 600 ${path})`,
+        problem: !keyless
+          ? `its permissions are ${perms}; it holds a key, so it must be owner-only (chmod 600 ${path})`
+          : (mode & 0o022) !== 0
+            ? `its permissions are ${perms}; other users could change it, and with it where Jev sends tool calls and prompts, so it must be owner-only (chmod 600 ${path})`
+            : `its permissions are ${perms}; it must be owner-only (chmod 600 ${path})`,
         fix: `chmod 600 ${path}`,
+        ...(keyless ? { keyless: true as const } : {}),
       };
     }
     const dirMode = looseConfigDirMode(path);
@@ -467,14 +939,7 @@ export function inspectJevConfig(): JevConfigInspection {
       };
     }
     if (st.size > MAX_CONFIG_BYTES) return { status: "refused", path, mode, reason: "too-large", problem: `it is larger than ${MAX_CONFIG_BYTES} bytes` };
-    const buf = Buffer.alloc(st.size);
-    let off = 0;
-    while (off < buf.length) {
-      const n = readSync(fd, buf, off, buf.length - off, off);
-      if (n === 0) break;
-      off += n;
-    }
-    text = buf.subarray(0, off).toString("utf8");
+    text = readText();
   } catch (err) {
     return { status: "refused", path, mode, reason: "unreadable", problem: `cannot read it (${(err as NodeJS.ErrnoException).code ?? "error"})` };
   } finally {
@@ -491,6 +956,50 @@ export function inspectJevConfig(): JevConfigInspection {
   } catch {
     return { status: "refused", path, mode, reason: "not-json", problem: "it is not valid JSON" };
   }
+  const isObject = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed);
+  const fields = isObject ? (parsed as Record<string, unknown>) : null;
+
+  // Switched off. Checked before any key is looked for, because nothing will be
+  // sent: a BYOK file whose key lives in the environment, and a Cloud file on a
+  // machine that has since disconnected, are both simply "off". The rest of the
+  // file is still validated — with stand-ins in the key slots, which are never
+  // sent anywhere — so a file that is off AND broken is reported as broken.
+  if (fields?.mode === "off") {
+    const r = validateJevConfig(parsed, KEY_STAND_IN, standInCloudCredential(fields));
+    if (!r.ok) return { status: "refused", path, mode, reason: "invalid", problem: r.problem };
+    return { status: "off", path, mode, routing: routingOf(r.value) };
+  }
+
+  if (fields?.provider === JEV_CLOUD_PROVIDER) {
+    // The key lives in credentials.json, which is read with the same owner-only
+    // checks as this file: a credentials file someone else could have written
+    // is refused, not read, and Jev is off.
+    const credential = readJevCloudCredential();
+    if (credential.status === "refused") {
+      return {
+        status: "refused",
+        path,
+        mode,
+        reason: credential.reason === "too-open" ? "too-open" : "unreadable",
+        problem: `the FailproofAI Cloud credential was refused: ${credential.problem}`,
+        ...(credential.fix ? { fix: credential.fix } : {}),
+        credentialsMode: credential.mode,
+      };
+    }
+    // `FAILPROOFAI_JEV_API_KEY` is deliberately not passed: see the header.
+    const r = validateJevConfig(parsed, null, credential.status === "ok" ? credential.credential : null);
+    if (r.ok) return { status: "ok", path, mode, keySource: "cloud", config: r.value };
+    if (r.notConnected === true) {
+      const rest = validateJevConfig(parsed, null, standInCloudCredential(fields));
+      if (!rest.ok) return { status: "refused", path, mode, reason: "invalid", problem: rest.problem };
+      if (credential.status === "absent" && credential.connected) {
+        return { status: "key-lacks-jev", path, mode, routing: routingOf(rest.value), problem: KEY_LACKS_JEV_PROBLEM };
+      }
+      return { status: "not-connected", path, mode, routing: routingOf(rest.value), problem: r.problem };
+    }
+    return { status: "refused", path, mode, reason: "invalid", problem: r.problem };
+  }
+
   const envKey = readEnvKey();
   const r = validateJevConfig(parsed, envKey);
   if (!r.ok) {
@@ -499,15 +1008,11 @@ export function inspectJevConfig(): JevConfigInspection {
       // validation never got that far, so ask again with a stand-in key.
       const rest = validateJevConfig(parsed, KEY_STAND_IN);
       if (rest.ok) {
-        const routing: Omit<JevConfig, "apiKey"> = { provider: rest.value.provider, mode: rest.value.mode, timeoutMs: rest.value.timeoutMs };
-        if (rest.value.baseUrl !== undefined) routing.baseUrl = rest.value.baseUrl;
-        if (rest.value.accountId !== undefined) routing.accountId = rest.value.accountId;
-        if (rest.value.model !== undefined) routing.model = rest.value.model;
         return {
           status: "key-missing",
           path,
           mode,
-          routing,
+          routing: routingOf(rest.value),
           problem: `it carries no apiKey, so the key comes from ${JEV_API_KEY_ENV} — which is not set in this environment`,
         };
       }
@@ -520,14 +1025,57 @@ export function inspectJevConfig(): JevConfigInspection {
 }
 
 /**
- * The validated global config, or null — absent, refused, invalid, or a
- * key-from-the-environment file in an environment that does not set it all
- * mean Jev is off and the regex path runs unchanged. Never throws.
+ * Why a Cloud file on a connected machine is off when no Jev key is stored for
+ * the connection (`key-lacks-jev`). Hedged: a connect whose introspect went
+ * unanswered clears the slot too, so nothing on disk says what the key carries.
+ */
+export const KEY_LACKS_JEV_PROBLEM =
+  "this machine is connected to FailproofAI Cloud, but no Jev key is stored for that connection (its key lacks jev:evaluate, or the connect could not confirm it)";
+
+/** Everything a validated config says except its key — copied field by field, so the key cannot ride along. */
+function routingOf(cfg: JevConfig): Omit<JevConfig, "apiKey"> {
+  const routing: Omit<JevConfig, "apiKey"> = { provider: cfg.provider, mode: cfg.mode, timeoutMs: cfg.timeoutMs };
+  if (cfg.baseUrl !== undefined) routing.baseUrl = cfg.baseUrl;
+  if (cfg.accountId !== undefined) routing.accountId = cfg.accountId;
+  if (cfg.model !== undefined) routing.model = cfg.model;
+  // Never `credentialOrigin`: every status that reports routing is one with no
+  // usable credential behind it, so there is no origin to report — only the
+  // stand-in it was validated with.
+  return routing;
+}
+
+/**
+ * A Cloud credential that stands in for a missing one, on the file's own origin,
+ * so the rest of a Cloud file can be validated when there is no key to check it
+ * with. Like `KEY_STAND_IN` it is never written and never sent; an unparseable
+ * `baseUrl` gets a placeholder origin and is refused by `validateBaseUrl` first.
+ */
+function standInCloudCredential(fields: Record<string, unknown>): JevCloudCredential {
+  let url = "https://stand-in.invalid";
+  if (typeof fields.baseUrl === "string") {
+    try {
+      url = new URL(fields.baseUrl.trim()).origin;
+    } catch {
+      // Keep the placeholder.
+    }
+  }
+  return { url, key: KEY_STAND_IN };
+}
+
+/**
+ * The validated global config, or null — absent, refused, invalid, switched
+ * off, a key-from-the-environment file in an environment that does not set it,
+ * or a FailproofAI Cloud file on a machine with no Cloud credential all mean
+ * Jev is off and the regex path runs unchanged. Never throws.
+ *
+ * `mode: "off"` never comes out of here: `inspectJevConfig` reports it as its
+ * own status, and the check below is the belt to that brace — an off config
+ * reaching the hook path would be read as the default mode, `enforce`.
  */
 export function loadJevConfig(): JevConfig | null {
   try {
     const r = inspectJevConfig();
-    return r.status === "ok" ? r.config : null;
+    return r.status === "ok" && r.config.mode !== "off" ? r.config : null;
   } catch {
     return null;
   }