@monster-orange/den 0.2.8 → 0.3.0

package/scripts/setup-1password.ts

@@ -1,9 +1,12 @@
 /**
  * 1Password Developer API Keys setup.
  *
- * Creates and populates the developer-keys item (OP_DEV_KEYS_ITEM) inside the
- * personal vault (OP_API_KEYS_VAULT), which services can use to inject
- * secrets at `make up` time via `op run --env-file=.env.op`.
+ * Creates and populates the developer-keys item inside a vault, which
+ * services can use to inject secrets at `make up` time via
+ * `op run --env-file=.env.op`. Where it lives is the distribution's choice:
+ * `secrets.developer_keys.{vault,item}` in the org config, else the vault
+ * and item of `secrets.refs.sudo`. Den has no default; with neither set the
+ * script says "not configured" and exits 0 (1 with --check).
  *
  * Which keys to collect is org data: `secrets.developer_keys.fields` in the
  * org config (default: only the keys the engine itself uses), and
@@ -11,7 +14,8 @@
  * offered as defaults.
  *
  * Usage:
- *   make den-setup-1password          — full interactive setup
+ *   make <cli>-setup-1password        — full interactive setup (only when
+ *                                       secrets.provider is 1password)
  *   npx tsx scripts/setup-1password.ts --check   — non-interactive vault check
  *                                                   exits 0 if ready, 1 if not
  */
@@ -20,22 +24,23 @@ import { execFile, spawnSync } from "child_process";
 import { promisify } from "util";
 import * as fs from "fs";
 import * as path from "path";
-import { fileURLToPath } from "url";
 import chalk from "chalk";
 import {
-  OP_ACCOUNT_DEFAULT,
-  OP_API_KEYS_VAULT,
-  OP_DEV_KEYS_ITEM,
-} from "../src/shared/constants.js";
-import {
+  notConfiguredMessage,
   readSecretsConfig,
+  secretsStrategy,
   type DeveloperKeyDef,
 } from "../src/shared/secrets/index.js";
 
 import { product } from "../src/shared/product.js";
-// Ensure op invocations hit the den-owned account even when this script is
-// run directly via `npx tsx` (not through make, which already exports OP_ACCOUNT).
-process.env.OP_ACCOUNT ||= OP_ACCOUNT_DEFAULT;
+import { getDistRoot } from "../src/shared/paths.js";
+const SECRETS_CFG = readSecretsConfig();
+// op uses the distribution's account (secrets.onepassword.account) or the
+// engineer's own OP_ACCOUNT; Den has none of its own.
+Object.assign(
+  process.env,
+  secretsStrategy("1password")?.capabilities.env?.(SECRETS_CFG, process.env),
+);
 
 const execFileAsync = promisify(execFile);
 
@@ -46,11 +51,19 @@ async function opJson<T>(args: string[]): Promise<T> {
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const DEN_ROOT = path.resolve(__dirname, "..");
+// dotenv paths are relative to the distribution root, never the engine.
+const DEN_ROOT = getDistRoot();
 
-const VAULT_NAME = OP_API_KEYS_VAULT;
-const ITEM_NAME = OP_DEV_KEYS_ITEM;
+const pick = (...v: Array<string | undefined>): string =>
+  v.map((x) => (typeof x === "string" ? x.trim() : "")).find(Boolean) ?? "";
+const VAULT_NAME = pick(
+  SECRETS_CFG.developer_keys?.vault,
+  SECRETS_CFG.refs?.sudo?.vault,
+);
+const ITEM_NAME = pick(
+  SECRETS_CFG.developer_keys?.item,
+  SECRETS_CFG.refs?.sudo?.item,
+);
 
 // ─── .env reader ─────────────────────────────────────────────────────────────
 
@@ -89,7 +102,7 @@ function parseEnvFile(filePath: string): Record<string, string> {
   return result;
 }
 
-const DEVELOPER_KEYS = readSecretsConfig().developer_keys ?? {};
+const DEVELOPER_KEYS = SECRETS_CFG.developer_keys ?? {};
 
 /**
  * The dotenv file `secrets.developer_keys.env_file` names (relative to the
@@ -560,7 +573,16 @@ async function setupMode(): Promise<void> {
 
 const isCheck = process.argv.includes("--check");
 
-if (isCheck) {
+if (!VAULT_NAME || !ITEM_NAME) {
+  // No place for the developer keys: nothing to set up, and no op call.
+  console.log(
+    `Developer keys item ${notConfiguredMessage("sudo").replace(
+      /secrets\.refs\.sudo/,
+      "secrets.developer_keys.vault + .item (or secrets.refs.sudo)",
+    )}`,
+  );
+  process.exit(isCheck ? 1 : 0);
+} else if (isCheck) {
   checkMode().catch(() => process.exit(1));
 } else {
   setupMode().catch((err: Error) => {

package/scripts/setup-secrets.ts

@@ -1,17 +1,21 @@
 /**
  * Backend-agnostic developer-secrets setup.
  *
- * Dispatches to the strategy selected by `secrets.provider` in
- * config/den.yml (override: DEN_SECRETS_PROVIDER or
- * config/local/user.yml). See src/shared/secrets.
+ * Dispatches to the `setup` capability of the strategy selected by
+ * `secrets.provider` in the org config (override: DEN_SECRETS_PROVIDER or
+ * config/local/user.yml). See src/shared/secrets/strategies.ts.
  *
  * Usage:
  *   make den-setup-secrets                 — interactive setup
  *   npx tsx scripts/setup-secrets.ts --check    — non-interactive; exit 0 when ready
  *   npx tsx scripts/setup-secrets.ts --cli      — print "<provider> <binary> <formula>"
- *   npx tsx scripts/setup-secrets.ts --gate     — like --check, but a backend that
- *                                                 is not ready only warns unless
- *                                                 secrets.required is true
+ *   npx tsx scripts/setup-secrets.ts --provider — print the selected strategy id
+ *   npx tsx scripts/setup-secrets.ts --gate     — the up / web gate: passes
+ *                                                 silently unless secrets.required
+ *                                                 is true, then like --check
+ *
+ * With `secrets.provider: none` there is nothing to set up: it says so and
+ * exits 0.
  */
 import { spawnSync } from "child_process";
 import * as path from "path";
@@ -20,6 +24,8 @@ import chalk from "chalk";
 import {
   getSecretsProvider,
   readSecretsConfig,
+  resolveProvider,
+  strategyFor,
 } from "../src/shared/secrets/index.js";
 
 import { envKey, product } from "../src/shared/product.js";
@@ -31,126 +37,86 @@ function run(cmd: string, args: string[]): number {
   return spawnSync(cmd, args, { stdio: "inherit", cwd: ROOT }).status ?? 1;
 }
 
-function installed(cmd: string): boolean {
-  return !spawnSync(cmd, ["--version"], { stdio: "ignore" }).error;
-}
-
-const INSTALL: Record<string, string> = {
-  doppler: "brew install dopplerhq/cli/doppler",
-  op: "brew install 1password-cli",
-};
-
-function otherBackends(current: string): string {
-  return (
-    "Or pick another backend for just you (config/local/user.yml):\n" +
-    "    secrets:\n" +
-    `      provider: env        # or 1password / doppler (team default: ${current})\n` +
-    `  or for one shell: ${envKey("SECRETS_PROVIDER")}=env make web`
-  );
-}
+const NONE_MESSAGE =
+  "No secrets backend is configured (secrets.provider: none), so there is nothing to set up.\n" +
+  `To use one, set secrets.provider (doppler | 1password | env) and secrets.refs.<name> in ${product().configFile}.`;
 
 async function main(): Promise<number> {
-  const provider = getSecretsProvider();
   const cfg = readSecretsConfig();
-  const label = `secrets backend: ${provider.name}`;
+  const resolved = resolveProvider(cfg);
+  const strategy = strategyFor(resolved.name);
+  const label = `secrets backend: ${resolved.name}`;
+
+  // `--provider`: print the selected strategy id (make reads it to offer
+  // backend-specific targets). Never probes the backend.
+  if (process.argv.includes("--provider")) {
+    console.log(resolved.name);
+    return 0;
+  }
 
   // `--cli`: print "<provider> <binary> <brew formula>" for make setup's
-  // install step ("env -" when the backend needs no CLI).
+  // install step ("<provider> - -" when the backend needs no CLI). An unset
+  // provider needs nothing installed until something asks for a secret.
   if (process.argv.includes("--cli")) {
-    const bin =
-      provider.name === "doppler"
-        ? "doppler"
-        : provider.name === "1password"
-          ? "op"
-          : "";
-    const formula = bin ? INSTALL[bin].replace(/^brew install /, "") : "";
-    console.log(`${provider.name} ${bin || "-"} ${formula || "-"}`);
+    const cli = resolved.implicit ? undefined : strategy.capabilities.cli;
+    console.log(`${resolved.name} ${cli?.bin ?? "-"} ${cli?.formula ?? "-"}`);
     return 0;
   }
 
+  // The up / web gate: only a distribution that requires its backend
+  // (secrets.required) is checked. Nothing required: pass, silently, whatever
+  // the provider; a feature that needs a secret reports it when it asks.
+  if (gate && !cfg.required) return 0;
+
   if (check || gate) {
-    const r = await provider.preflight();
-    if (r.ok) return 0;
-    if (gate && !cfg.required) {
-      // Signed in but no default scope: secret_env refs name their own
-      // (<project>/<config>/<key>), so only the engine's own secrets lack one.
-      if (await provider.isReady()) {
-        console.error(
-          chalk.gray(
-            `   ${label}: signed in, no default scope set (secret_env refs still resolve;` +
-              ` test logins and the saved sudo password need one: \`make ${product().cli}-setup-secrets\`).`,
-          ),
-        );
-        return 0;
-      }
-      console.error(
-        chalk.yellow(
-          `⚠️  ${label} is not ready — continuing.\n` +
-            "   Test logins and the saved sudo password need it; run " +
-            `\`make ${product().cli}-setup-secrets\` when you want them.`,
-        ),
-      );
+    if (resolved.name === "none" || (resolved.implicit && !cfg.required)) {
+      if (resolved.name === "none")
+        console.log(`  ✓ ${NONE_MESSAGE.split("\n")[0]}`);
       return 0;
     }
+    const r = await getSecretsProvider().preflight();
+    if (r.ok) return 0;
     console.error(chalk.red(`✗ ${label}\n${r.message ?? ""}`));
     return 1;
   }
 
+  const setup = strategy.capabilities.setup;
+  if (resolved.name === "none" || !setup) {
+    console.log(NONE_MESSAGE);
+    return 0;
+  }
+  if (resolved.implicit && !cfg.required) {
+    // Nothing chose a backend and nothing requires one: no store to set up.
+    console.log(
+      "secrets.provider is not set, so there is nothing to set up.\n" +
+        `To use a backend, set secrets.provider (doppler | 1password | env | none) in ${product().configFile}.`,
+    );
+    return 0;
+  }
   console.log(
     chalk.bold(`\n${product().title} developer secrets (${label})\n`),
   );
-  switch (provider.name) {
-    case "doppler": {
-      if (!installed("doppler")) {
-        console.error(
-          chalk.red("✗ The Doppler CLI is not installed.\n") +
-            `  Install it:  ${INSTALL.doppler}\n  then re-run: make ${product().cli}-setup-secrets\n\n  ` +
-            otherBackends(provider.name),
-        );
-        return 1;
-      }
-      if (!(await provider.isReady())) {
-        console.log("→ doppler login");
-        if (run("doppler", ["login"]) !== 0) return 1;
-      }
-      const scope: string[] = [];
-      if (cfg.doppler?.project) scope.push("--project", cfg.doppler.project);
-      if (cfg.doppler?.config) scope.push("--config", cfg.doppler.config);
-      console.log(`→ doppler setup ${scope.join(" ")}`.trim());
-      if (
-        run("doppler", ["setup", "--no-interactive", ...scope]) !== 0 &&
-        scope.length === 0
-      ) {
-        run("doppler", ["setup"]);
-      }
-      break;
-    }
-    case "1password":
-      if (!installed("op")) {
-        console.error(
-          chalk.red("✗ The 1Password CLI (op) is not installed.\n") +
-            `  Install it:  ${INSTALL.op}\n\n  ` +
-            otherBackends(provider.name),
-        );
-        return 1;
-      }
-      return run(path.join(ROOT, "node_modules", ".bin", "tsx"), [
-        path.join(ROOT, "scripts", "setup-1password.ts"),
-      ]);
-    case "env":
-      console.log(
-        "The env backend reads secrets from the process environment.\n" +
-          `Export them yourself (direnv, CI secrets, \`doppler run -- ${product().cli} up\`).`,
-      );
-      break;
-  }
+  const provider = getSecretsProvider();
+  const code = await setup({
+    cfg,
+    provider,
+    engineRoot: ROOT,
+    cli: product().cli,
+    run,
+    log: (l) => console.log(l),
+    error: (l) => console.error(chalk.red(l)),
+  });
+  if (code !== 0) return code;
   const r = await provider.preflight();
   console.log(
     r.ok ? chalk.green(`✓ ${label} ready`) : chalk.red(`✗ ${r.message}`),
   );
+  if (!r.ok)
+    console.log(
+      `  Or for one shell: ${envKey("SECRETS_PROVIDER")}=none make web`,
+    );
   return r.ok ? 0 : 1;
 }
-
 main().then(
   (code) => process.exit(code),
   (err: unknown) => {

package/src/pillars/api/global-setup.ts

@@ -86,7 +86,7 @@ async function globalSetup(_config: FullConfig) {
           `  ⚠  No credentials for ${role} — authenticated ${role} tests will fail`,
         );
         console.warn(
-          `     eval $(op signin) && make auth-configure (admin) or verify 1Password vault`,
+          `     set E2E_${role.toUpperCase()}_EMAIL / _PASSWORD, or set up the secrets backend (secrets.provider)`,
         );
       } else {
         // Token mint failure, IdP misconfiguration, etc. — fail fast

package/src/pillars/journeys/sandbox.ts

@@ -36,10 +36,10 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import { OP_API_KEYS_VAULT, OP_DEV_KEYS_ITEM } from "../../shared/constants.js";
 import {
   getSecretsProvider,
   namedSecretRef,
+  notConfiguredMessage,
   type SecretRef,
 } from "../../shared/secrets/index.js";
 import type { Environment } from "../../shared/types/index.js";
@@ -51,22 +51,12 @@ import { getDistRoot } from "../../shared/paths.js";
 import { containsValue } from "../../shared/redact.js";
 // ── Layer 1: captureSecrets ──────────────────────────────────────────────────
 
-/** 1Password field label holding the Cursor API key (= env var name). */
+/** The Cursor API key's env var name (and the usual field label). */
 export const CURSOR_API_KEY_FIELD = "CURSOR_API_KEY";
 
 /** Name of the agent-key ref under `secrets.refs` in the org config. */
 export const JOURNEYS_AGENT_KEY_REF = "journeys_agent_key";
 
-/**
- * Where the agent key lives when `secrets.refs.journeys_agent_key` is not
- * configured: the engineer's own developer-keys item (neutral default).
- */
-export const JOURNEYS_AGENT_KEY_DEFAULT: SecretRef = {
-  vault: OP_API_KEYS_VAULT,
-  item: OP_DEV_KEYS_ITEM,
-  field: CURSOR_API_KEY_FIELD,
-};
-
 /**
  * Secrets captured into memory before environment sanitization.
  *
@@ -84,6 +74,7 @@ export interface OpFieldRequest {
   item: string;
   vault: string;
   field: string;
+  key?: string;
 }
 
 export interface CaptureSecretsDeps {
@@ -91,8 +82,11 @@ export interface CaptureSecretsDeps {
   opReadField?: (request: OpFieldRequest) => Promise<string>;
   /** Env-var source; defaults to process.env. */
   env?: NodeJS.ProcessEnv;
-  /** Where the key lives; defaults to the configured `journeys_agent_key` ref. */
-  agentKeyRef?: SecretRef;
+  /**
+   * Where the key lives; defaults to the configured `journeys_agent_key`
+   * ref. null: not configured (there is no built-in location).
+   */
+  agentKeyRef?: SecretRef | null;
 }
 
 /** Default reader: the configured secrets strategy. */
@@ -118,14 +112,25 @@ export async function captureSecrets(
   if (cursorApiKey.length === 0) {
     let opError = "";
     const ref =
-      deps.agentKeyRef ??
-      namedSecretRef(JOURNEYS_AGENT_KEY_REF, JOURNEYS_AGENT_KEY_DEFAULT);
+      deps.agentKeyRef !== undefined
+        ? deps.agentKeyRef
+        : namedSecretRef(JOURNEYS_AGENT_KEY_REF);
+    if (!ref) {
+      // No configured place for the key: say so, without asking a backend.
+      throw new Error(
+        `No Cursor API key available for journey agents.\n` +
+          `  Options:\n` +
+          `    • set the ${CURSOR_API_KEY_FIELD} env var\n` +
+          `    • secrets backend: ${notConfiguredMessage(JOURNEYS_AGENT_KEY_REF)}\n`,
+      );
+    }
     try {
       cursorApiKey = (
         await opReadField({
           item: ref.item,
           vault: ref.vault,
           field: ref.field,
+          ...(ref.key ? { key: ref.key } : {}),
         })
       ).trim();
     } catch (error) {
@@ -137,8 +142,8 @@ export async function captureSecrets(
           `  Options:\n` +
           `    • CI: set the ${CURSOR_API_KEY_FIELD} env var\n` +
           `    • Local: sign in to the secrets backend (make ${product().cli}-setup-secrets) and\n` +
-          `      make sure the "${ref.item}" item in the "${ref.vault}" vault has a\n` +
-          `      ${ref.field} field (move it with secrets.refs.${JOURNEYS_AGENT_KEY_REF})\n` +
+          `      make sure secrets.refs.${JOURNEYS_AGENT_KEY_REF} (item "${ref.item}", vault "${ref.vault}",\n` +
+          `      field ${ref.field}) holds the key\n` +
           (opError ? `  Secrets backend error: ${opError}\n` : ""),
       );
     }

package/src/pillars/journeys/tools/browser-session.ts

@@ -32,7 +32,7 @@ import { product } from "../../../shared/product.js";
  * Mint a fresh authenticated browser session for `role` against `env`'s
  * web surface and return the storageState auth-file path (and nothing
  * else). Throws a loud, actionable error when credentials cannot be
- * sourced — naming both the 1Password path (local) and the E2E_* env-var
+ * sourced — naming both the secrets-backend path (local) and the E2E_* env-var
  * path (CI), mirroring browser/global-setup.ts.
  */
 export async function provisionBrowserSession(
@@ -47,7 +47,7 @@ export async function provisionBrowserSession(
   if (!credentials) {
     const localHint =
       role === "admin"
-        ? `  Local: make auth-configure env=${env}  (handles 1Password sign-in automatically)\n`
+        ? `  Local: with secrets.provider: 1password, make auth-configure env=${env}\n`
         : `  Local: sign in to the secrets backend (make ${product().cli}-setup-secrets); the ${role} account comes from test_accounts in the org config\n`;
     throw new Error(
       `No credentials for ${role}.\n` +

package/src/scripts/setup-default-workspace.ts

@@ -145,7 +145,7 @@ async function main() {
     '  This builds the "default" workspace — every standard system repo,\n' +
       `  all managed: ${product().cli} clones and keeps each one up to date for\n` +
       "  you, no checkouts or decisions required. For anything you actively\n" +
-      "  develop, flip that repo to dev-managed in the web UX (Local Dev)\n" +
+      "  develop, flip that repo to dev-managed in the web UX (Workspaces)\n" +
       "  and point it at your own checkout.\n",
   );
 
@@ -183,7 +183,7 @@ async function main() {
     `\n  ✓ Default workspace configured with ${seed.length} service(s), all managed.`,
   );
   console.log(
-    "  Change any repo to dev-managed in the web UX: make web → Local Dev.",
+    "  Change any repo to dev-managed in the web UX: make web → Workspaces.",
   );
   console.log(`  Run 'make ${product().cli}-up' to start your services.\n`);
 }

package/src/shared/auth/headless-login.ts

@@ -34,7 +34,7 @@ const PROJECT_ROOT = getDistRoot();
 const AUTH_DIR = path.resolve(PROJECT_ROOT, "playwright/.auth");
 
 // Per-engineer admin config — stores email + secret reference (no password)
-// Created by: make auth-configure [env=<env>]
+// Created by: make auth-configure [env=<env>] (secrets.provider: 1password)
 // Lookup order: config/local/admin-auth-{env}.json → config/local/admin-auth.json
 const LOCAL_CONFIG_DIR = path.resolve(PROJECT_ROOT, "config/local");
 

package/src/shared/auth/sudo-vault.ts

@@ -1,51 +1,56 @@
 /**
  * Secrets-backed persistence for the local-dev sudo password.
  *
- * Goes through the configured secrets strategy (Doppler, 1Password or env —
- * see src/shared/secrets), addressing the named ref `sudo` (default
- * OP_API_KEYS_VAULT / OP_DEV_KEYS_ITEM / OP_DEN_SUDO_FIELD; an org
- * moves it with `secrets.refs.sudo` in its config) — flat key
- * DEN_LOCAL_ADMIN_PWD for key/value backends.
+ * Goes through the configured secrets strategy (see src/shared/secrets),
+ * addressing the named ref `sudo`. There is no built-in location: a
+ * distribution that wants the saved password sets `secrets.refs.sudo` in its
+ * config. Without it, the vault path is "not configured" and only the
+ * interactive unlock is offered; nothing is spawned.
  *
  * All read helpers fail *soft*: if the backend isn't installed, the user isn't
- * signed in, or the value is missing, they return null/false so the server can
- * fall back to the manual unlock banner without surfacing CLI noise.
+ * signed in, the ref is not configured or the value is missing, they return
+ * null/false so the server can fall back to the manual unlock without
+ * surfacing CLI noise.
  */
 
-import {
-  OP_API_KEYS_VAULT,
-  OP_DEV_KEYS_ITEM,
-  OP_DEN_SUDO_FIELD,
-} from "../constants.js";
 import {
   getSecretsProvider,
   namedSecretRef,
+  notConfiguredMessage,
+  readSecretsConfig,
+  secretsStatus,
+  SecretsNotConfiguredError,
   type SecretRef,
+  type SecretsProviderName,
 } from "../secrets/index.js";
+import { product } from "../product.js";
 
-/** The built-in default for the `sudo` named ref. */
-export const SUDO_SECRET_REF: SecretRef = {
-  vault: OP_API_KEYS_VAULT,
-  item: OP_DEV_KEYS_ITEM,
-  field: OP_DEN_SUDO_FIELD,
-};
+/** Name of the sudo ref under `secrets.refs`. */
+export const SUDO_REF_NAME = "sudo";
 
-/** The effective sudo ref (`secrets.refs.sudo` over the default). */
-function sudoRef(): SecretRef {
-  return namedSecretRef("sudo", SUDO_SECRET_REF);
+/** The configured sudo ref, or null when `secrets.refs.sudo` is not set. */
+export function sudoRef(): SecretRef | null {
+  try {
+    return namedSecretRef(SUDO_REF_NAME, readSecretsConfig());
+  } catch {
+    return null;
+  }
 }
 
-/** True when the secrets backend is installed AND authenticated. */
+/** True when the sudo ref is configured AND its backend is ready. */
 export async function isSecretsBackendReady(): Promise<boolean> {
+  if (!sudoRef()) return false;
   return getSecretsProvider().isReady();
 }
 
 /** @deprecated use isSecretsBackendReady */
 export const isOpSignedIn = isSecretsBackendReady;
 
-/** Read the stored sudo password. Null when unavailable or empty. */
+/** Read the stored sudo password. Null when unavailable, unconfigured or empty. */
 export async function readSudoFromVault(): Promise<string | null> {
-  return getSecretsProvider().tryGet(sudoRef());
+  const ref = sudoRef();
+  if (!ref) return null;
+  return getSecretsProvider().tryGet(ref);
 }
 
 /** Whether a non-empty sudo password is stored (without returning it). */
@@ -55,15 +60,72 @@ export async function hasSudoInVault(): Promise<boolean> {
 
 /** Save (or overwrite) the sudo password. Throws on backend errors. */
 export async function saveSudoToVault(password: string): Promise<void> {
-  await getSecretsProvider().set(sudoRef(), password);
+  const ref = sudoRef();
+  if (!ref)
+    throw new SecretsNotConfiguredError(notConfiguredMessage(SUDO_REF_NAME));
+  await getSecretsProvider().set(ref, password);
+}
+
+/** What the UI's unlock form may offer: `/api/sudo-password/vault-status`. */
+export interface SudoVaultStatus {
+  /** The selected strategy id. */
+  backend: SecretsProviderName;
+  /** Name people see ("1Password"), for "Save to <label>". */
+  label: string;
+  /** `secrets.refs.sudo` is set for this backend. */
+  configured: boolean;
+  /**
+   * The backend can work here, whether or not a sudo ref is configured
+   * (`configured` says that). With no ref: detect() only (a PATH check,
+   * nothing spawned), and only for an explicitly chosen provider; an unset
+   * provider is never probed (it is not needed). With a ref: detect() and
+   * signed in.
+   */
+  backendAvailable: boolean;
+  /** Why it is not available (not configured, CLI not on PATH, signed out). */
+  reason?: string;
+  /** The distribution's org config file (e.g. config/acme.yml), for UI copy. */
+  configFile: string;
+  hasStored: boolean;
+  /** @deprecated alias of backendAvailable; removed in a later minor. */
+  opAvailable: boolean;
+}
+
+export async function sudoVaultStatus(): Promise<SudoVaultStatus> {
+  const cfg = readSecretsConfig();
+  const ref = sudoRef();
+  const pre = secretsStatus(cfg, process.env, { detect: false });
+  // Probe only what is needed or was chosen: a ref, or an explicit backend.
+  const probe = !!ref || (!pre.implicit && pre.backend !== "none");
+  const st = probe ? secretsStatus(cfg, process.env) : pre;
+  const out = (
+    backendAvailable: boolean,
+    hasStored: boolean,
+    reason?: string,
+  ): SudoVaultStatus => ({
+    backend: st.backend,
+    label: st.label,
+    configured: !!ref,
+    backendAvailable,
+    ...(reason ? { reason } : {}),
+    configFile: product().configFile,
+    hasStored,
+    opAvailable: backendAvailable,
+  });
+  if (!ref)
+    return out(
+      probe && st.detect.available,
+      false,
+      notConfiguredMessage(SUDO_REF_NAME),
+    );
+  if (!st.detect.available)
+    return out(false, false, `not available: ${st.detect.reason ?? ""}`.trim());
+  if (!(await getSecretsProvider().isReady()))
+    return out(false, false, `${st.label} is not signed in`);
+  return out(true, await hasSudoInVault());
 }
 
 /** Name of the active backend, for UI copy ("Save to Doppler"). */
 export function secretsBackendLabel(): string {
-  const n = getSecretsProvider().name;
-  return n === "1password"
-    ? "1Password"
-    : n === "doppler"
-      ? "Doppler"
-      : "environment";
+  return secretsStatus().label;
 }

package/src/shared/auth/token-providers/index.ts

@@ -115,9 +115,13 @@ const localJwtProvider: TokenProvider = {
     const l = cfg.auth?.localJwt;
     if (!l) throw new Error(`auth.localJwt is not set for ${cfg.name}`);
     const env = o.env ?? process.env;
+    // An explicit key the environment file names: not a default ref, so it
+    // resolves as it always has (env first, then the selected backend).
+    const fromEnv = env[l.secretKey];
+    const backend = fromEnv ? null : getSecretsProvider();
     const secret =
-      env[l.secretKey] ??
-      (await getSecretsProvider().tryGet({
+      fromEnv ??
+      (await backend!.tryGet({
         vault: "",
         item: "",
         field: l.secretKey,
@@ -125,7 +129,7 @@ const localJwtProvider: TokenProvider = {
       }));
     if (!secret) {
       throw new Error(
-        `local-jwt signing secret ${l.secretKey} not found in env or the secrets backend`,
+        `local-jwt signing secret ${l.secretKey} not found in env or the ${backend?.name ?? "configured"} secrets backend (secrets.provider)`,
       );
     }
     const ttl = l.ttlSeconds ?? 3600;