@monster-orange/den 0.2.8 → 0.4.0

package/src/shared/secrets/index.ts

@@ -2,30 +2,40 @@
  * Secrets strategy selection.
  *
  * Resolution order for the backend:
- *   1. DEN_SECRETS_PROVIDER env var (doppler | 1password | env)
+ *   1. DEN_SECRETS_PROVIDER env var (none | doppler | 1password | env)
  *   2. `secrets.provider` in config/local/user.yml (per-engineer)
- *   3. `secrets.provider` in config/den.yml (team default)
- *   4. "doppler"
+ *   3. `secrets.provider` in the org config (team default)
+ *   4. "doppler" — implicit and deprecated: a warning says to set it.
  *
- * Adding a backend = implement SecretsProvider and register it in FACTORIES.
+ * Every backend is a strategy registered in the strategy registry
+ * (./strategies.ts); a new one registers there, like a plugin.
+ *
+ * Den assumes nothing about where a distribution keeps its secrets: no
+ * vault, item, field or account is built in. The engine's own named secrets
+ * (`sudo`, `journeys_agent_key`) exist only when `secrets.refs.<name>` says
+ * where they are; otherwise the feature reports "not configured".
  */
-import { OP_ACCOUNT_DEFAULT, OP_CLI_TIMEOUT_MS } from "../constants.js";
 import { readDenConfig, readUserConfig } from "../den-config.js";
-import { DopplerProvider } from "./doppler.js";
-import { EnvProvider } from "./env.js";
-import { OnePasswordProvider } from "./onepassword.js";
+import type { DetectResult } from "../strategies/registry.js";
+import { notConfiguredMessage, SecretsNotConfiguredError } from "./none.js";
+import { secretsStrategy, type SecretsStrategy } from "./strategies.js";
 import type {
+  PreflightResult,
   SecretRef,
   SecretsProvider,
   SecretsProviderName,
 } from "./types.js";
 
-import { envKey } from "../product.js";
+import { envKey, product } from "../product.js";
 export * from "./types.js";
 export { flatKeyFor, toEnvName, refPath } from "./keys.js";
 export { DopplerProvider } from "./doppler.js";
 export { EnvProvider } from "./env.js";
+export { NoneProvider } from "./none.js";
 export { OnePasswordProvider } from "./onepassword.js";
+export { notConfiguredMessage, SecretsNotConfiguredError } from "./none.js";
+export { secretsStrategy, secretsStrategyIds } from "./strategies.js";
+export type { SecretsStrategy, SecretsSetupContext } from "./strategies.js";
 export * from "./secret-env.js";
 
 export interface SecretsConfig {
@@ -42,17 +52,19 @@ export interface SecretsConfig {
   /** `"vault/item/field": FLAT_KEY` overrides for doppler/env. */
   keys?: Record<string, string>;
   /**
-   * Where the engine's own named secrets live, overriding the built-in
-   * defaults field by field (see {@link namedSecretRef}). Names in use:
-   * `sudo` (the saved local-dev sudo password) and `journeys_agent_key`
-   * (the journeys pillar's agent API key).
+   * Where the engine's own named secrets live (see {@link namedSecretRef}).
+   * There are no built-in defaults: a name with no entry here is "not
+   * configured" and its feature stays off. Names in use: `sudo` (the saved
+   * local-dev sudo password) and `journeys_agent_key` (the journeys
+   * pillar's agent API key).
    *
    *   refs:
-   *     journeys_agent_key: { vault: Shared, item: CI Keys }
+   *     sudo: { vault: Private, item: Dev Keys, field: ACME_LOCAL_ADMIN_PWD }
+   *     journeys_agent_key: { key: CURSOR_API_KEY }   # doppler / env
    */
   refs?: Record<string, Partial<SecretRef>>;
   /**
-   * The per-engineer developer keys `make den-setup-1password` collects
+   * The per-engineer developer keys `make <cli>-setup-1password` collects
    * into the developer-keys item (see scripts/setup-1password.ts). Default:
    * only the keys the engine itself uses.
    */
@@ -70,6 +82,10 @@ export interface DeveloperKeyDef {
 }
 
 export interface DeveloperKeysConfig {
+  /** The 1Password vault holding the developer-keys item (no default). */
+  vault?: string;
+  /** The developer-keys item (no default). */
+  item?: string;
   /**
    * A dotenv file (relative to the den root, e.g. an app checkout's
    * `.env`) whose values are offered as defaults.
@@ -79,26 +95,21 @@ export interface DeveloperKeysConfig {
 }
 
 export const SECRETS_PROVIDERS: readonly SecretsProviderName[] = [
+  "none",
   "doppler",
   "1password",
   "env",
 ];
 
-const FACTORIES: Record<
-  SecretsProviderName,
-  (c: SecretsConfig) => SecretsProvider
-> = {
-  doppler: (c) => new DopplerProvider({ ...c.doppler, keys: c.keys }),
-  "1password": (c) =>
-    new OnePasswordProvider({
-      account: c.onepassword?.account ?? OP_ACCOUNT_DEFAULT,
-      timeoutMs: OP_CLI_TIMEOUT_MS,
-    }),
-  env: (c) => new EnvProvider(c.keys),
-};
+/** The backend an unset `secrets.provider` falls back to (deprecated). */
+export const IMPLICIT_SECRETS_PROVIDER: SecretsProviderName = "doppler";
 
 function isProviderName(v: unknown): v is SecretsProviderName {
-  return typeof v === "string" && (SECRETS_PROVIDERS as string[]).includes(v);
+  return (
+    typeof v === "string" &&
+    (SECRETS_PROVIDERS as string[]).includes(v) &&
+    secretsStrategy(v) !== undefined
+  );
 }
 
 /** Effective secrets config (team file, then per-engineer override). */
@@ -125,33 +136,48 @@ export function readSecretsConfig(): SecretsConfig {
   };
 }
 
+/** Whether `ref` gives backend `name` enough to address a secret. */
+export function refIsComplete(
+  name: SecretsProviderName,
+  ref: Partial<SecretRef> | undefined,
+): boolean {
+  if (!ref || typeof ref !== "object") return false;
+  return secretsStrategy(name)?.capabilities.refComplete(ref) ?? false;
+}
+
 /**
- * The engine-named secret `name`: `defaults` with any configured
- * `secrets.refs.<name>` fields laid over them. The engine never hard-wires
- * an org's vault or item names; the defaults are neutral placeholders.
+ * The engine-named secret `name`, exactly as `secrets.refs.<name>` gives it,
+ * or null when the distribution has not configured it (or configured too
+ * little for the selected backend). There are no built-in defaults: Den
+ * never assumes a vault, item, field or key of its own.
  */
 export function namedSecretRef(
   name: string,
-  defaults: SecretRef,
   cfg: SecretsConfig = readSecretsConfig(),
-): SecretRef {
-  const override = cfg.refs?.[name] ?? {};
-  const pick = (v: unknown, d: string): string =>
-    typeof v === "string" && v.trim() ? v.trim() : d;
+  provider: SecretsProviderName = resolveProviderName(cfg),
+): SecretRef | null {
+  const raw = cfg.refs?.[name];
+  if (!refIsComplete(provider, raw)) return null;
+  const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
   const ref: SecretRef = {
-    vault: pick(override.vault, defaults.vault),
-    item: pick(override.item, defaults.item),
-    field: pick(override.field, defaults.field),
+    vault: str(raw!.vault),
+    item: str(raw!.item),
+    field: str(raw!.field) || str(raw!.key),
   };
-  const key = override.key ?? defaults.key;
-  if (key) ref.key = key;
+  if (str(raw!.key)) ref.key = str(raw!.key);
   return ref;
 }
 
-export function resolveProviderName(
+export interface ResolvedProvider {
+  name: SecretsProviderName;
+  /** True when nothing chose it: the deprecated implicit doppler default. */
+  implicit: boolean;
+}
+
+export function resolveProvider(
   cfg: SecretsConfig,
   env: NodeJS.ProcessEnv = process.env,
-): SecretsProviderName {
+): ResolvedProvider {
   const fromEnv = env.DEN_SECRETS_PROVIDER;
   if (fromEnv) {
     if (!isProviderName(fromEnv)) {
@@ -159,40 +185,243 @@ export function resolveProviderName(
         `${envKey("SECRETS_PROVIDER")}="${fromEnv}" is not one of ${SECRETS_PROVIDERS.join(", ")}`,
       );
     }
-    return fromEnv;
+    return { name: fromEnv, implicit: false };
   }
   if (cfg.provider !== undefined && !isProviderName(cfg.provider)) {
     throw new Error(
       `secrets.provider "${String(cfg.provider)}" is not one of ${SECRETS_PROVIDERS.join(", ")}`,
     );
   }
-  return cfg.provider ?? "doppler";
+  return cfg.provider
+    ? { name: cfg.provider, implicit: false }
+    : { name: IMPLICIT_SECRETS_PROVIDER, implicit: true };
+}
+
+export function resolveProviderName(
+  cfg: SecretsConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): SecretsProviderName {
+  return resolveProvider(cfg, env).name;
+}
+
+/** The registered strategy for `name` (always registered for a valid name). */
+export function strategyFor(name: SecretsProviderName): SecretsStrategy {
+  const s = secretsStrategy(name);
+  if (!s) throw new Error(`secrets strategy "${name}" is not registered`);
+  return s;
 }
 
 export function createSecretsProvider(
   name: SecretsProviderName,
   cfg: SecretsConfig = {},
 ): SecretsProvider {
-  return FACTORIES[name](cfg);
+  return strategyFor(name).capabilities.create(cfg);
+}
+
+/**
+ * The provider behind detect(): while the strategy reports its backend
+ * unavailable (its CLI is not on PATH), nothing is spawned. Reads report
+ * null / not ready, and get, set and preflight give detect()'s reason
+ * instead of a spawn error.
+ */
+class DetectedProvider implements SecretsProvider {
+  constructor(
+    private readonly inner: SecretsProvider,
+    private readonly strategy: SecretsStrategy,
+    private readonly implicit = false,
+  ) {}
+  get name(): SecretsProviderName {
+    return this.inner.name;
+  }
+  private unavailable(): string | null {
+    // The implicit default is resolved lazily: only a secret actually being
+    // read or written gets here, and only then does it warn (once).
+    if (this.implicit) warnImplicitOnce();
+    const d = this.strategy.detect();
+    return d.available ? null : `not available: ${d.reason ?? "unavailable"}`;
+  }
+  async isReady(): Promise<boolean> {
+    return this.unavailable() ? false : this.inner.isReady();
+  }
+  async get(ref: SecretRef): Promise<string> {
+    const why = this.unavailable();
+    if (why) throw new Error(`${this.name} secrets backend ${why}`);
+    return this.inner.get(ref);
+  }
+  async tryGet(ref: SecretRef): Promise<string | null> {
+    return this.unavailable() ? null : this.inner.tryGet(ref);
+  }
+  async set(ref: SecretRef, value: string): Promise<void> {
+    const why = this.unavailable();
+    if (why) throw new Error(`${this.name} secrets backend ${why}`);
+    return this.inner.set(ref, value);
+  }
+  async preflight(): Promise<PreflightResult> {
+    // Nothing chose a backend, so nothing requires one to be ready.
+    if (this.implicit) return { ok: true };
+    const why = this.unavailable();
+    if (why)
+      return {
+        ok: false,
+        message:
+          `${this.strategy.capabilities.label} ${why}.\n` +
+          `Install it, or set secrets.provider in ${product().configFile} (none | doppler | 1password | env).`,
+      };
+    return this.inner.preflight();
+  }
+  runPrefix(): string[] {
+    // Never wrap a command in an implicit backend.
+    if (this.implicit) return [];
+    return this.unavailable() ? [] : this.inner.runPrefix();
+  }
+}
+
+let warnedImplicit = false;
+function warnImplicitOnce(): void {
+  if (warnedImplicit) return;
+  warnedImplicit = true;
+  console.warn(`⚠️  ${IMPLICIT_PROVIDER_WARNING}`);
 }
 
 let cached: SecretsProvider | null = null;
 let cachedKey = "";
 
-/** The configured backend. Re-resolves when DEN_SECRETS_PROVIDER changes. */
+/**
+ * The configured backend, behind its strategy's detect(). Re-resolves when
+ * DEN_SECRETS_PROVIDER or the config changes.
+ */
 export function getSecretsProvider(): SecretsProvider {
   const cfg = readSecretsConfig();
-  const name = resolveProviderName(cfg);
-  const key = `${name}|${JSON.stringify(cfg)}`;
+  const { name, implicit } = resolveProvider(cfg);
+  const key = `${name}|${implicit}|${JSON.stringify(cfg)}`;
   if (!cached || key !== cachedKey) {
-    cached = createSecretsProvider(name, cfg);
+    cached = new DetectedProvider(
+      createSecretsProvider(name, cfg),
+      strategyFor(name),
+      implicit,
+    );
     cachedKey = key;
   }
   return cached;
 }
 
+export interface SecretsStatus {
+  /** The selected strategy id. */
+  backend: SecretsProviderName;
+  /** Name people see ("1Password"). */
+  label: string;
+  /** True when secrets.provider is unset (the deprecated doppler default). */
+  implicit: boolean;
+  /** detect() of the selected strategy. */
+  detect: DetectResult;
+}
+
+/** The selected strategy and its detect() result. Never spawns, never throws. */
+export function secretsStatus(
+  cfg: SecretsConfig = readSecretsConfig(),
+  env: NodeJS.ProcessEnv = process.env,
+  opts: { detect?: boolean } = {},
+): SecretsStatus {
+  let r: ResolvedProvider;
+  try {
+    r = resolveProvider(cfg, env);
+  } catch (err) {
+    return {
+      backend: "none",
+      label: "none",
+      implicit: false,
+      detect: { available: false, reason: (err as Error).message },
+    };
+  }
+  const s = strategyFor(r.name);
+  return {
+    backend: r.name,
+    label: s.capabilities.label,
+    implicit: r.implicit,
+    // detect:false: report the choice without probing (nothing needs it).
+    detect:
+      opts.detect === false
+        ? { available: false, reason: "not checked: nothing needs it" }
+        : s.detect(env),
+  };
+}
+
+/**
+ * Env vars the selected strategy gives the processes Den starts (the web
+ * server). Only 1password gives any (OP_ACCOUNT, from the distribution's
+ * config or the engineer's shell); every other backend gives none.
+ */
+export function secretsProcessEnv(
+  cfg: SecretsConfig = readSecretsConfig(),
+  env: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  let name: SecretsProviderName;
+  try {
+    name = resolveProviderName(cfg, env);
+  } catch {
+    return {};
+  }
+  return strategyFor(name).capabilities.env?.(cfg, env) ?? {};
+}
+
+/** The engine's own named refs, for the legacy warning. */
+export const ENGINE_SECRET_REFS = ["sudo", "journeys_agent_key"] as const;
+
+export const IMPLICIT_PROVIDER_WARNING =
+  "secrets.provider is not set; the implicit doppler default is deprecated and will be removed in a later minor. " +
+  "Set it explicitly: doppler, 1password, env or none.";
+
+/**
+ * Config warnings about secrets, for the server's startup log and
+ * `validate`: a 1password distribution with no refs (the old built-in
+ * vault/item/field are gone). The implicit doppler default warns lazily,
+ * the first time it resolves a secret (see getSecretsProvider), so a
+ * distribution that needs no secrets never hears about it.
+ */
+export function secretsConfigWarnings(
+  cfg: SecretsConfig = readSecretsConfig(),
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  let r: ResolvedProvider;
+  try {
+    r = resolveProvider(cfg, env);
+  } catch (err) {
+    return [(err as Error).message];
+  }
+  const out: string[] = [];
+  if (
+    r.name === "1password" &&
+    !ENGINE_SECRET_REFS.some((n) => refIsComplete(r.name, cfg.refs?.[n]))
+  ) {
+    out.push(
+      "secrets.provider is 1password but secrets.refs is empty: Den no longer assumes a default vault, item or field. " +
+        `Add the refs to ${product().configFile}, e.g.\n` +
+        "  secrets:\n" +
+        "    refs:\n" +
+        "      sudo: { vault: <vault>, item: <item>, field: <field> }\n" +
+        "      journeys_agent_key: { vault: <vault>, item: <item>, field: CURSOR_API_KEY }\n" +
+        "The vault-backed features (saved sudo password, journeys agent key) stay off until then.",
+    );
+  }
+  return out;
+}
+
+/**
+ * Throw "not configured" for engine ref `name`, or return it. For features
+ * that cannot run without it.
+ */
+export function requireNamedSecretRef(
+  name: string,
+  cfg: SecretsConfig = readSecretsConfig(),
+): SecretRef {
+  const ref = namedSecretRef(name, cfg);
+  if (!ref) throw new SecretsNotConfiguredError(notConfiguredMessage(name));
+  return ref;
+}
+
 /** Test hook. */
 export function resetSecretsProviderCache(): void {
   cached = null;
   cachedKey = "";
+  warnedImplicit = false;
 }

package/src/shared/secrets/none.ts

@@ -0,0 +1,56 @@
+/**
+ * The `none` strategy: no secrets backend. What a distribution gets when it
+ * sets no `secrets.provider`. It resolves nothing, never spawns a CLI, and
+ * every secret-backed feature reports "not configured" instead of failing.
+ */
+import { product } from "../product.js";
+import type { PreflightResult, SecretRef, SecretsProvider } from "./types.js";
+
+/**
+ * "not configured: set secrets.provider and secrets.refs.<name> in
+ * config/<cli>.yml" — the one message every surface shows for a secret Den
+ * has no configured place for.
+ */
+export function notConfiguredMessage(refName = "<name>"): string {
+  return `not configured: set secrets.provider and secrets.refs.${refName} in ${product().configFile}`;
+}
+
+/** Thrown when a secret is asked of a backend or ref that is not configured. */
+export class SecretsNotConfiguredError extends Error {
+  readonly code = "not-configured";
+  constructor(message = notConfiguredMessage()) {
+    super(message);
+    this.name = "SecretsNotConfiguredError";
+  }
+}
+
+export class NoneProvider implements SecretsProvider {
+  readonly name = "none" as const;
+
+  async isReady(): Promise<boolean> {
+    return false;
+  }
+
+  async get(ref: SecretRef): Promise<string> {
+    throw new SecretsNotConfiguredError(
+      `${ref.field || "secret"}: no secrets backend is configured (${notConfiguredMessage()})`,
+    );
+  }
+
+  async tryGet(): Promise<string | null> {
+    return null;
+  }
+
+  async set(): Promise<void> {
+    throw new SecretsNotConfiguredError();
+  }
+
+  async preflight(): Promise<PreflightResult> {
+    // Nothing to sign in to: `up` and `web` run as they are.
+    return { ok: true, message: "no secrets backend configured" };
+  }
+
+  runPrefix(): string[] {
+    return [];
+  }
+}

package/src/shared/secrets/strategies.ts

@@ -0,0 +1,202 @@
+/**
+ * The built-in secrets strategies, registered through the generic strategy
+ * registry (src/shared/strategies/registry.ts) exactly as a plugin would
+ * register one. Each entry is `{ id, kind: "secrets", detect(), capabilities }`.
+ *
+ * Capabilities:
+ *  - `create(cfg)`: the SecretsProvider for this backend;
+ *  - `label`: the name people see ("Save to 1Password");
+ *  - `cli`: the CLI it needs, for `make setup`'s install step;
+ *  - `refComplete(ref)`: whether a configured `secrets.refs.<name>` gives
+ *    this backend enough to address a secret;
+ *  - `env(cfg, env)`: optional vars this backend gives the processes Den
+ *    starts (only 1password: OP_ACCOUNT, from the distribution's config);
+ *  - `setup(ctx)`: optional interactive setup (`make <cli>-setup-secrets`).
+ */
+import * as path from "path";
+import { OP_CLI_TIMEOUT_MS } from "../constants.js";
+import {
+  getStrategy,
+  onPath,
+  registerStrategy,
+  strategyIds,
+  type DetectResult,
+  type StrategyEntry,
+} from "../strategies/registry.js";
+import { DopplerProvider } from "./doppler.js";
+import { EnvProvider } from "./env.js";
+import { NoneProvider } from "./none.js";
+import { OnePasswordProvider } from "./onepassword.js";
+import type { SecretsConfig } from "./index.js";
+import type { SecretRef, SecretsProvider } from "./types.js";
+
+export const SECRETS_KIND = "secrets";
+
+export interface SecretsSetupContext {
+  cfg: SecretsConfig;
+  provider: SecretsProvider;
+  /** Den's package root (its scripts live there). */
+  engineRoot: string;
+  /** The distribution's CLI name, for remediation lines. */
+  cli: string;
+  /** Run a command with inherited stdio; its exit code. */
+  run(cmd: string, args: string[]): number;
+  log(line: string): void;
+  error(line: string): void;
+}
+
+export interface SecretsCapabilities {
+  label: string;
+  create(cfg: SecretsConfig): SecretsProvider;
+  cli?: { bin: string; formula: string };
+  refComplete(ref: Partial<SecretRef>): boolean;
+  env?(cfg: SecretsConfig, env: NodeJS.ProcessEnv): Record<string, string>;
+  setup?(ctx: SecretsSetupContext): Promise<number>;
+}
+
+export type SecretsStrategy = StrategyEntry<
+  typeof SECRETS_KIND,
+  SecretsCapabilities
+>;
+
+const nonEmpty = (v: unknown): boolean =>
+  typeof v === "string" && v.trim().length > 0;
+
+/** Flat-key backends address a secret by its key, or an env-shaped field. */
+const flatRefComplete = (ref: Partial<SecretRef>): boolean =>
+  nonEmpty(ref.key) || nonEmpty(ref.field);
+
+function cliDetect(bin: string, label: string) {
+  return (env: NodeJS.ProcessEnv = process.env): DetectResult =>
+    onPath(bin, env)
+      ? { available: true }
+      : { available: false, reason: `${label} CLI (${bin}) is not on PATH` };
+}
+
+function otherBackends(): string {
+  return (
+    "Or pick another backend in the org config (secrets.provider: env | doppler | 1password),\n" +
+    "  or for just you in config/local/user.yml."
+  );
+}
+
+const none: SecretsStrategy = {
+  id: "none",
+  kind: SECRETS_KIND,
+  detect: () => ({
+    available: true,
+    reason: "no secrets backend configured",
+  }),
+  capabilities: {
+    label: "none",
+    create: () => new NoneProvider(),
+    refComplete: () => false,
+  },
+};
+
+const env: SecretsStrategy = {
+  id: "env",
+  kind: SECRETS_KIND,
+  detect: () => ({ available: true }),
+  capabilities: {
+    label: "environment",
+    create: (c) => new EnvProvider(c.keys),
+    refComplete: flatRefComplete,
+    async setup(ctx) {
+      ctx.log(
+        "The env backend reads secrets from the process environment.\n" +
+          `Export them yourself (direnv, CI secrets, \`doppler run -- ${ctx.cli} up\`).`,
+      );
+      return 0;
+    },
+  },
+};
+
+const doppler: SecretsStrategy = {
+  id: "doppler",
+  kind: SECRETS_KIND,
+  detect: cliDetect("doppler", "The Doppler"),
+  capabilities: {
+    label: "Doppler",
+    create: (c) => new DopplerProvider({ ...c.doppler, keys: c.keys }),
+    cli: { bin: "doppler", formula: "dopplerhq/cli/doppler" },
+    refComplete: flatRefComplete,
+    async setup(ctx) {
+      if (!doppler.detect().available) {
+        ctx.error(
+          "✗ The Doppler CLI is not installed.\n" +
+            `  Install it:  brew install dopplerhq/cli/doppler\n  then re-run: make ${ctx.cli}-setup-secrets\n\n  ` +
+            otherBackends(),
+        );
+        return 1;
+      }
+      if (!(await ctx.provider.isReady())) {
+        ctx.log("→ doppler login");
+        if (ctx.run("doppler", ["login"]) !== 0) return 1;
+      }
+      const scope: string[] = [];
+      if (ctx.cfg.doppler?.project)
+        scope.push("--project", ctx.cfg.doppler.project);
+      if (ctx.cfg.doppler?.config)
+        scope.push("--config", ctx.cfg.doppler.config);
+      ctx.log(`→ doppler setup ${scope.join(" ")}`.trim());
+      if (
+        ctx.run("doppler", ["setup", "--no-interactive", ...scope]) !== 0 &&
+        scope.length === 0
+      ) {
+        ctx.run("doppler", ["setup"]);
+      }
+      return 0;
+    },
+  },
+};
+
+const onepassword: SecretsStrategy = {
+  id: "1password",
+  kind: SECRETS_KIND,
+  detect: cliDetect("op", "The 1Password"),
+  capabilities: {
+    label: "1Password",
+    create: (c) =>
+      new OnePasswordProvider({
+        // From the distribution's config or the engineer's shell; never a
+        // built-in account.
+        account: c.onepassword?.account,
+        timeoutMs: OP_CLI_TIMEOUT_MS,
+      }),
+    cli: { bin: "op", formula: "1password-cli" },
+    refComplete: (ref) => nonEmpty(ref.item) && nonEmpty(ref.field),
+    env(c, e): Record<string, string> {
+      const account = c.onepassword?.account?.trim() || e.OP_ACCOUNT?.trim();
+      return account ? { OP_ACCOUNT: account } : {};
+    },
+    async setup(ctx) {
+      if (!onepassword.detect().available) {
+        ctx.error(
+          "✗ The 1Password CLI (op) is not installed.\n" +
+            `  Install it:  brew install 1password-cli\n\n  ` +
+            otherBackends(),
+        );
+        return 1;
+      }
+      return ctx.run(path.join(ctx.engineRoot, "node_modules", ".bin", "tsx"), [
+        path.join(ctx.engineRoot, "scripts", "setup-1password.ts"),
+      ]);
+    },
+  },
+};
+
+for (const s of [none, env, doppler, onepassword]) registerStrategy(s);
+
+/** The registered secrets strategy `id`, or undefined. */
+export function secretsStrategy(id: string): SecretsStrategy | undefined {
+  return getStrategy<typeof SECRETS_KIND, SecretsCapabilities>(
+    SECRETS_KIND,
+    id,
+  );
+}
+
+/** Every registered secrets strategy id. */
+export function secretsStrategyIds(): string[] {
+  return strategyIds(SECRETS_KIND);
+}