@monster-orange/den 0.4.18 → 0.4.20

package/src/shared/secrets/index.ts

@@ -17,6 +17,12 @@
  */
 import { readDenConfig, readUserConfig } from "../den-config.js";
 import type { DetectResult } from "../strategies/registry.js";
+import { ConfigError } from "../config-error.js";
+import {
+  describeOpTokenSource,
+  opTokenSourceError,
+  parseOpTokenSource,
+} from "./op-token.js";
 import { notConfiguredMessage, SecretsNotConfiguredError } from "./none.js";
 import { secretsStrategy, type SecretsStrategy } from "./strategies.js";
 import type {
@@ -37,6 +43,7 @@ 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 * from "./op-token.js";
 
 export interface SecretsConfig {
   provider?: SecretsProviderName;
@@ -48,7 +55,16 @@ export interface SecretsConfig {
    */
   required?: boolean;
   doppler?: { project?: string; config?: string };
-  onepassword?: { account?: string };
+  onepassword?: {
+    account?: string;
+    /**
+     * Where the service-account token comes from: `keychain:<service>`,
+     * `file:<path>` (mode 600) or `env:<VAR>` (the default,
+     * `env:OP_SERVICE_ACCOUNT_TOKEN`). Per machine: read from
+     * config/local/user.yml only, never from the distribution's config.
+     */
+    token?: string;
+  };
   /** `"vault/item/field": FLAT_KEY` overrides for doppler/env. */
   keys?: Record<string, string>;
   /**
@@ -126,11 +142,32 @@ export function readSecretsConfig(): SecretsConfig {
   } catch {
     /* no user config */
   }
+  // The token source is this machine's: the distribution's config never
+  // names one, and a bad one is refused here, naming the key.
+  const tokenErr =
+    user.onepassword?.token === undefined || user.onepassword.token === null
+      ? null
+      : opTokenSourceError(user.onepassword.token);
+  if (tokenErr) {
+    const key = "secrets.onepassword.token";
+    throw new ConfigError([
+      {
+        file: "config/local/user.yml",
+        key,
+        message: tokenErr,
+        text: `${key} ${tokenErr}`,
+      },
+    ]);
+  }
   return {
     ...team,
     ...user,
     doppler: { ...team.doppler, ...user.doppler },
-    onepassword: { ...team.onepassword, ...user.onepassword },
+    onepassword: {
+      ...team.onepassword,
+      ...user.onepassword,
+      token: user.onepassword?.token ?? undefined,
+    },
     keys: { ...team.keys, ...user.keys },
     refs: { ...team.refs, ...user.refs },
   };
@@ -251,6 +288,14 @@ class DetectedProvider implements SecretsProvider {
   async tryGet(ref: SecretRef): Promise<string | null> {
     return this.unavailable() ? null : this.inner.tryGet(ref);
   }
+  async tryGetWithReason(
+    ref: SecretRef,
+  ): Promise<{ value: string | null; reason?: string }> {
+    const why = this.unavailable();
+    if (why) return { value: null, reason: why };
+    if (this.inner.tryGetWithReason) return this.inner.tryGetWithReason(ref);
+    return { value: await 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}`);
@@ -364,6 +409,24 @@ export function secretsProcessEnv(
   return strategyFor(name).capabilities.env?.(cfg, env) ?? {};
 }
 
+/**
+ * Settings › Secrets: where the 1Password token comes from, as text
+ * ("keychain: <service>", "file: <path>", "env: <VAR>") or "not set". The
+ * source only, never the token; reads nothing from the keychain or the file.
+ */
+export function opTokenSourceSetting(
+  cfg: SecretsConfig | (() => SecretsConfig) = readSecretsConfig,
+): string {
+  try {
+    const raw = (typeof cfg === "function" ? cfg() : cfg).onepassword?.token;
+    return raw === undefined || raw === null
+      ? "not set"
+      : describeOpTokenSource(parseOpTokenSource(raw));
+  } catch {
+    return "invalid: see secrets.onepassword.token";
+  }
+}
+
 /** The engine's own named refs, for the legacy warning. */
 export const ENGINE_SECRET_REFS = ["sudo", "journeys_agent_key"] as const;
 
@@ -379,9 +442,14 @@ export const IMPLICIT_PROVIDER_WARNING =
  * distribution that needs no secrets never hears about it.
  */
 export function secretsConfigWarnings(
-  cfg: SecretsConfig = readSecretsConfig(),
+  cfg?: SecretsConfig,
   env: NodeJS.ProcessEnv = process.env,
 ): string[] {
+  try {
+    cfg ??= readSecretsConfig();
+  } catch (err) {
+    return [(err as Error).message];
+  }
   let r: ResolvedProvider;
   try {
     r = resolveProvider(cfg, env);

package/src/shared/secrets/onepassword.ts

@@ -5,27 +5,95 @@
 import { execFile } from "child_process";
 import { promisify } from "util";
 import type { PreflightResult, SecretRef, SecretsProvider } from "./types.js";
+import {
+  DEFAULT_OP_TOKEN_SOURCE,
+  OP_TOKEN_ENV,
+  OpFailure,
+  mapOpFailure,
+  readOpToken,
+  type OpTokenDeps,
+  type OpTokenSource,
+} from "./op-token.js";
 
 import { product } from "../product.js";
 const execFileAsync = promisify(execFile);
 
 export interface OnePasswordOptions {
   account?: string;
+  /**
+   * Where the service-account token comes from (`secrets.onepassword.token`).
+   * Unset: the default `env:OP_SERVICE_ACCOUNT_TOKEN`, and `op` is run with
+   * this process's own env even when that has none (a signed-in desktop app
+   * still works).
+   */
+  tokenSource?: OpTokenSource;
+  /** Test seam: the env, platform and home the token source is read with. */
+  tokenDeps?: OpTokenDeps;
   timeoutMs?: number;
 }
 
 export class OnePasswordProvider implements SecretsProvider {
   readonly name = "1password" as const;
   private readonly timeout: number;
+  private readonly tokenSource: OpTokenSource | undefined;
+  private readonly tokenDeps: OpTokenDeps | undefined;
 
   constructor(opts: OnePasswordOptions = {}) {
     this.timeout = opts.timeoutMs ?? 60_000;
+    this.tokenSource = opts.tokenSource;
+    this.tokenDeps = opts.tokenDeps;
     if (opts.account) process.env.OP_ACCOUNT ||= opts.account;
   }
 
+  /**
+   * The options for one `op` call. The token is read now (never cached) and
+   * goes only into the child's env. A configured source that yields none
+   * fails with its reason; the default source with no token runs `op` as
+   * before.
+   */
+  private async opOptions(): Promise<{
+    timeout: number;
+    env?: NodeJS.ProcessEnv;
+    token?: string;
+  }> {
+    const explicit = this.tokenSource !== undefined;
+    const t = await readOpToken(
+      this.tokenSource ?? DEFAULT_OP_TOKEN_SOURCE,
+      this.tokenDeps,
+    );
+    if (!t.ok) {
+      if (explicit) throw new OpFailure("token_source", t.reason);
+      return { timeout: this.timeout, env: process.env };
+    }
+    return {
+      timeout: this.timeout,
+      env: { ...process.env, [OP_TOKEN_ENV]: t.token },
+      token: t.token,
+    };
+  }
+
+  /** Run `op`; a failure carries op's reason in plain words, never the token. */
+  private async run(args: string[], rawErrors = false): Promise<string> {
+    const { token, ...opts } = await this.opOptions();
+    try {
+      const { stdout } = await execFileAsync("op", args, opts);
+      return String(stdout);
+    } catch (err) {
+      // `set` keeps op's own error: its caller strips the value it wrote.
+      if (rawErrors) throw err;
+      const e = err as { stderr?: unknown; killed?: boolean; code?: unknown };
+      if (e.killed)
+        throw new OpFailure("unknown", "1Password failed: op timed out");
+      if (e.code === "ENOENT")
+        throw new OpFailure("unknown", "1Password failed: op is not installed");
+      const m = mapOpFailure(String(e.stderr ?? ""), token ? [token] : []);
+      throw new OpFailure(m.code, m.text);
+    }
+  }
+
   async isReady(): Promise<boolean> {
     try {
-      await execFileAsync("op", ["whoami"], { timeout: this.timeout });
+      await this.run(["whoami"]);
       return true;
     } catch {
       return false;
@@ -37,18 +105,26 @@ export class OnePasswordProvider implements SecretsProvider {
     const args = ["item", "get", ref.item];
     if (ref.vault) args.push("--vault", ref.vault);
     args.push("--fields", `label=${ref.field}`, "--reveal");
-    const { stdout } = await execFileAsync("op", args, {
-      timeout: this.timeout,
-    });
-    return String(stdout).trim();
+    return (await this.run(args)).trim();
   }
 
   async tryGet(ref: SecretRef): Promise<string | null> {
+    return (await this.tryGetWithReason(ref)).value;
+  }
+
+  async tryGetWithReason(
+    ref: SecretRef,
+  ): Promise<{ value: string | null; reason?: string }> {
     try {
       const v = await this.get(ref);
-      return v.length > 0 ? v : null;
-    } catch {
-      return null;
+      return v.length > 0
+        ? { value: v }
+        : { value: null, reason: "the field is empty" };
+    } catch (err) {
+      return {
+        value: null,
+        reason: err instanceof OpFailure ? err.message : undefined,
+      };
     }
   }
 
@@ -57,13 +133,10 @@ export class OnePasswordProvider implements SecretsProvider {
     const vault = ref.vault ? ["--vault", ref.vault] : [];
     const field = `${ref.field}[password]=${value}`;
     try {
-      await execFileAsync("op", ["item", "edit", ref.item, ...vault, field], {
-        timeout: this.timeout,
-      });
+      await this.run(["item", "edit", ref.item, ...vault, field], true);
     } catch (err) {
       try {
-        await execFileAsync(
-          "op",
+        await this.run(
           [
             "item",
             "create",
@@ -74,7 +147,7 @@ export class OnePasswordProvider implements SecretsProvider {
             ...vault,
             field,
           ],
-          { timeout: this.timeout },
+          true,
         );
       } catch {
         throw err;

package/src/shared/secrets/op-token.ts

@@ -0,0 +1,270 @@
+/**
+ * Where the 1Password service-account token comes from, and why `op` failed.
+ *
+ * A Den running as a service (launchd, systemd) does not read a login shell,
+ * so `op` has no OP_SERVICE_ACCOUNT_TOKEN of its own. `secrets.onepassword.token`
+ * in config/local/user.yml (per machine, never the distribution's) says
+ * where to read one:
+ *
+ *   keychain:<service>   macOS: `security find-generic-password -s <service> -w`
+ *   file:<path>          a file whose mode is exactly 600; `~` expands
+ *   env:<VAR>            an env var of this process (the default is
+ *                        env:OP_SERVICE_ACCOUNT_TOKEN)
+ *
+ * The token is read when a ref is resolved, never cached, and goes only into
+ * the `op` child's env. Nothing here returns it in text: every message names
+ * the source, never the token.
+ */
+import { execFile, execFileSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { promisify } from "util";
+
+const execFileAsync = promisify(execFile);
+
+export const OP_TOKEN_ENV = "OP_SERVICE_ACCOUNT_TOKEN";
+const SECURITY_TIMEOUT_MS = 10_000;
+
+export type OpTokenSource =
+  | { kind: "keychain"; service: string }
+  | { kind: "file"; path: string }
+  | { kind: "env"; name: string };
+
+export const DEFAULT_OP_TOKEN_SOURCE: OpTokenSource = {
+  kind: "env",
+  name: OP_TOKEN_ENV,
+};
+
+const SHAPE =
+  "must be keychain:<service>, file:<path> or env:<VAR> (for example env:OP_SERVICE_ACCOUNT_TOKEN)";
+
+/** Why `raw` is not a valid token source, or null. Never echoes `raw`. */
+export function opTokenSourceError(raw: unknown): string | null {
+  if (typeof raw !== "string") return SHAPE;
+  const m = /^(keychain|file|env):(.*)$/s.exec(raw);
+  if (!m) return SHAPE;
+  const [, kind, rest] = m;
+  // eslint-disable-next-line no-control-regex
+  if (rest.trim() === "" || /[\u0000-\u001f]/.test(rest))
+    return `${kind}: needs a value on one line; ${SHAPE}`;
+  if (kind === "env" && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(rest))
+    return `env: needs an env var name; ${SHAPE}`;
+  if (kind === "keychain" && rest.startsWith("-"))
+    return `keychain: service name must not start with "-"; ${SHAPE}`;
+  return null;
+}
+
+/** The source `raw` names (unset: the default). Throws, naming `where`. */
+export function parseOpTokenSource(
+  raw: unknown,
+  where = "secrets.onepassword.token",
+): OpTokenSource {
+  if (raw === undefined || raw === null) return DEFAULT_OP_TOKEN_SOURCE;
+  const err = opTokenSourceError(raw);
+  if (err) throw new Error(`${where} ${err}`);
+  const s = raw as string;
+  const i = s.indexOf(":");
+  const kind = s.slice(0, i);
+  const rest = s.slice(i + 1);
+  if (kind === "keychain") return { kind, service: rest };
+  if (kind === "file") return { kind, path: rest };
+  return { kind: "env", name: rest };
+}
+
+/** "keychain: <service>", "file: <path>" or "env: <VAR>": what people see. */
+export function describeOpTokenSource(src: OpTokenSource): string {
+  if (src.kind === "keychain") return `keychain: ${src.service}`;
+  if (src.kind === "file") return `file: ${src.path}`;
+  return `env: ${src.name}`;
+}
+
+export type OpTokenResult =
+  | { ok: true; token: string }
+  | { ok: false; reason: string };
+
+export interface OpTokenDeps {
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  home?: string;
+}
+
+function expandHome(p: string, home: string): string {
+  if (p === "~") return home;
+  if (p.startsWith("~/")) return path.join(home, p.slice(2));
+  return p;
+}
+
+function fail(src: OpTokenSource, why: string): OpTokenResult {
+  return {
+    ok: false,
+    reason: `token source ${describeOpTokenSource(src)}: ${why}`,
+  };
+}
+
+function readTokenFile(src: { kind: "file"; path: string }, home: string) {
+  const file = expandHome(src.path, home);
+  let st: fs.Stats;
+  try {
+    st = fs.statSync(file);
+  } catch {
+    return fail(src, "file not found or not readable");
+  }
+  if (!st.isFile()) return fail(src, "not a regular file");
+  const mode = st.mode & 0o777;
+  if (mode !== 0o600)
+    return fail(
+      src,
+      `file mode is ${mode.toString(8).padStart(3, "0")}; it must be 600 (chmod 600 the file)`,
+    );
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf-8");
+  } catch {
+    return fail(src, "file not readable");
+  }
+  const token = text.replace(/[\r\n]+$/, "");
+  return token ? ({ ok: true, token } as const) : fail(src, "file is empty");
+}
+
+function fromEnv(src: { kind: "env"; name: string }, env: NodeJS.ProcessEnv) {
+  const v = env[src.name];
+  return v
+    ? ({ ok: true, token: v } as const)
+    : fail(src, "env var is not set");
+}
+
+const NOT_MAC = "the macOS keychain is not available on this system";
+
+/**
+ * Read the token now. Never cached. The failure reason names the source,
+ * never the token.
+ */
+export async function readOpToken(
+  src: OpTokenSource,
+  deps: OpTokenDeps = {},
+): Promise<OpTokenResult> {
+  const env = deps.env ?? process.env;
+  const home = deps.home ?? os.homedir();
+  if (src.kind === "env") return fromEnv(src, env);
+  if (src.kind === "file") return readTokenFile(src, home);
+  if ((deps.platform ?? process.platform) !== "darwin")
+    return fail(src, NOT_MAC);
+  try {
+    const { stdout } = await execFileAsync(
+      "security",
+      ["find-generic-password", "-s", src.service, "-w"],
+      { timeout: SECURITY_TIMEOUT_MS, env },
+    );
+    const token = String(stdout).replace(/[\r\n]+$/, "");
+    return token ? { ok: true, token } : fail(src, "keychain item is empty");
+  } catch {
+    return fail(src, "keychain item not found or not readable");
+  }
+}
+
+/**
+ * Whether the source yields a token, for `doctor`: the same checks, but a
+ * keychain item is only looked up (no `-w`), so nothing is read and no
+ * keychain prompt can appear. Returns the reason, or null when it works.
+ */
+export function opTokenSourceProblem(
+  src: OpTokenSource,
+  deps: OpTokenDeps = {},
+): string | null {
+  const env = deps.env ?? process.env;
+  const home = deps.home ?? os.homedir();
+  if (src.kind === "env") {
+    const r = fromEnv(src, env);
+    return r.ok ? null : r.reason;
+  }
+  if (src.kind === "file") {
+    const r = readTokenFile(src, home);
+    return r.ok ? null : r.reason;
+  }
+  if ((deps.platform ?? process.platform) !== "darwin")
+    return `token source ${describeOpTokenSource(src)}: ${NOT_MAC}`;
+  try {
+    execFileSync("security", ["find-generic-password", "-s", src.service], {
+      timeout: SECURITY_TIMEOUT_MS,
+      env,
+      stdio: "ignore",
+    });
+    return null;
+  } catch {
+    return `token source ${describeOpTokenSource(src)}: keychain item not found`;
+  }
+}
+
+export type OpFailureCode =
+  | "no_token"
+  | "no_access"
+  | "not_found"
+  | "rate_limited"
+  | "token_source"
+  | "unknown";
+
+export interface OpFailureInfo {
+  code: OpFailureCode;
+  /** Plain words, safe to show. */
+  text: string;
+}
+
+/**
+ * Map `op`'s stderr to one plain reason. Pure. `redact` lists strings (the
+ * token) to blank out of the unknown case's summary.
+ */
+export function mapOpFailure(
+  stderr: string,
+  redact: readonly string[] = [],
+): OpFailureInfo {
+  const s = stderr ?? "";
+  if (
+    /not signed in|no active session|service account token|sign ?in|session (has )?expired|authenticat|no accounts? (configured|found)/i.test(
+      s,
+    )
+  )
+    return {
+      code: "no_token",
+      text: "1Password has no service-account token or session for this process",
+    };
+  if (/rate.?limit|too many requests|\b429\b/i.test(s))
+    return { code: "rate_limited", text: "1Password rate limited the request" };
+  if (
+    /isn't a vault|is not a vault|don't have access|do not have access|doesn't have access|not authorized|forbidden|permission|\b403\b|access denied/i.test(
+      s,
+    )
+  )
+    return { code: "no_access", text: "no access to the vault" };
+  if (
+    /isn't an item|isn't a field|is not an item|not found|no such|could not find|couldn't find|doesn't exist|does not exist|no (item|field)|more than one item/i.test(
+      s,
+    )
+  )
+    return { code: "not_found", text: "item or field not found" };
+  let line =
+    s
+      .split(/\r?\n/)
+      .map((l) =>
+        l.replace(/^\[\w+\]\s*\d{4}\/\d\d\/\d\d \d\d:\d\d:\d\d\s*/, "").trim(),
+      )
+      .find((l) => l) ?? "";
+  for (const r of redact) if (r) line = line.split(r).join("[hidden]");
+  line = line.replace(/op:\/\/\S+/g, "[ref]");
+  if (line.length > 100) line = `${line.slice(0, 100)}...`;
+  return {
+    code: "unknown",
+    text: line ? `1Password failed: ${line}` : "1Password failed (no detail)",
+  };
+}
+
+/** A failed 1Password read, with a reason that is safe to show. */
+export class OpFailure extends Error {
+  constructor(
+    readonly code: OpFailureCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "OpFailure";
+  }
+}

package/src/shared/secrets/secret-env.ts

@@ -80,6 +80,8 @@ export function assertSecretEnvSpec(
 export interface SecretEnvMissing {
   key: string;
   ref: string;
+  /** Why, in plain words, when the provider said (never a value). */
+  reason?: string;
 }
 
 export type SecretEnvResolution =
@@ -87,8 +89,10 @@ export type SecretEnvResolution =
   | { ok: false; missing: SecretEnvMissing[]; message: string };
 
 /**
- * The failure text for unresolved keys: key, ref and provider, never a value
- * and never the provider's own error output (which could echo one).
+ * The failure text for unresolved keys: key, ref and provider, and the
+ * provider's reason when it gave one (a mapped phrase such as "no access to
+ * the vault"), never a value and never its raw error output (which could
+ * echo one).
  */
 export function describeSecretEnvMissing(
   target: string,
@@ -96,7 +100,8 @@ export function describeSecretEnvMissing(
   provider: string,
 ): string {
   const lines = missing.map(
-    (m) => `  ${m.key} (ref ${m.ref}, provider ${provider}): not resolved`,
+    (m) =>
+      `  ${m.key} (ref ${m.ref}, provider ${provider}): not resolved${m.reason ? `: ${m.reason}` : ""}`,
   );
   return (
     `${target}: ${missing.length} secret_env key(s) could not be resolved; not starting it:\n` +
@@ -120,17 +125,25 @@ export async function resolveSecretEnv(
     entries.map(async ([key, raw]) => {
       if (secretEnvRefError(raw)) return { key, raw, value: null };
       let value: string | null = null;
+      let reason: string | undefined;
       try {
-        value = await provider.tryGet(parseSecretEnvRef(raw));
+        const ref = parseSecretEnvRef(raw);
+        if (provider.tryGetWithReason) {
+          ({ value, reason } = await provider.tryGetWithReason(ref));
+        } else value = await provider.tryGet(ref);
       } catch {
         value = null;
       }
-      return { key, raw, value };
+      return { key, raw, value, reason };
     }),
   );
   const missing = results
     .filter((r) => !r.value)
-    .map((r) => ({ key: r.key, ref: String(r.raw) }));
+    .map((r) => ({
+      key: r.key,
+      ref: String(r.raw),
+      ...(r.reason ? { reason: r.reason } : {}),
+    }));
   if (missing.length)
     return {
       ok: false,

package/src/shared/secrets/strategies.ts

@@ -27,6 +27,7 @@ import { DopplerProvider } from "./doppler.js";
 import { EnvProvider } from "./env.js";
 import { NoneProvider } from "./none.js";
 import { OnePasswordProvider } from "./onepassword.js";
+import { parseOpTokenSource } from "./op-token.js";
 import type { SecretsConfig } from "./index.js";
 import type { SecretRef, SecretsProvider } from "./types.js";
 
@@ -162,6 +163,11 @@ const onepassword: SecretsStrategy = {
         // From the distribution's config or the engineer's shell; never a
         // built-in account.
         account: c.onepassword?.account,
+        // Per machine (user.yml); validated when the config is read.
+        tokenSource:
+          c.onepassword?.token === undefined
+            ? undefined
+            : parseOpTokenSource(c.onepassword.token),
         timeoutMs: OP_CLI_TIMEOUT_MS,
       }),
     cli: { bin: "op", formula: "1password-cli" },

package/src/shared/secrets/types.ts

@@ -50,6 +50,14 @@ export interface SecretsProvider {
   get(ref: SecretRef): Promise<string>;
   /** Read a secret, returning null instead of throwing. */
   tryGet(ref: SecretRef): Promise<string | null>;
+  /**
+   * Like tryGet, plus a plain-words reason when it is null (op's own: no
+   * token, no access to the vault, not found, rate limited). Optional. The
+   * reason never carries a secret value or a token.
+   */
+  tryGetWithReason?(
+    ref: SecretRef,
+  ): Promise<{ value: string | null; reason?: string }>;
   /** Write (create or overwrite) a secret. Throws on failure. */
   set(ref: SecretRef, value: string): Promise<void>;
   /** Check the backend is usable before `den up`/`restart`. */