@monster-orange/den 0.4.19 → 0.4.20

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.4.20] - 2026-11-09
+
+### Added
+
+- **1Password works for a Den running as a service.** A Den under launchd
+  does not read your login shell, so `op` had no
+  `OP_SERVICE_ACCOUNT_TOKEN` and every 1Password `secret_env` ref failed
+  with a bare "not resolved". `secrets.onepassword.token` in
+  `config/local/user.yml` (per machine) now says where the token comes
+  from: `keychain:<service>` (macOS), `file:<path>` (mode 600 only) or
+  `env:<VAR>` (the default is `env:OP_SERVICE_ACCOUNT_TOKEN`, as before).
+  A bad value is refused at config load, naming the key. The token is read
+  when a ref is resolved, never cached, and goes only into the `op` child's
+  env; it is never logged, stored, put in an error, the activity records
+  or an API response.
+- **"Not resolved" now says why.** A 1Password ref that fails reports one
+  of: no service-account token or session, no access to the vault, item or
+  field not found, rate limited, or a short safe summary. A token source
+  that fails (keychain item missing, file mode wrong, env var unset) is
+  named, never the token.
+- **doctor** adds a `1password` row, "this process has no service-account
+  token. Set secrets.onepassword.token.", when 1Password is the provider
+  and the source yields none (a warning).
+- **Settings › Secrets** shows the token's source, never the token
+  (`GET /api/settings` gains `op_token_source`, a string).
+
 ## [0.4.19] - 2026-11-08
 
 ### Added

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.19/hero-dark.png">
-  <img src="docs/images/0.4.19/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.20/hero-dark.png">
+  <img src="docs/images/0.4.20/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
 </picture>
 
 ## Set up by your agent
@@ -39,7 +39,7 @@ It doesn't replace your tools. Your repos, Docker, your test runners, your secre
 yours. Den connects them and turns on good practice from the start.
 
 <p align="center">
-  <img src="docs/images/0.4.19/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
+  <img src="docs/images/0.4.20/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
 </p>
 
 ## How it helps
@@ -69,10 +69,10 @@ yours. Den connects them and turns on good practice from the start.
   lives in your own repo.
 
 <p align="center">
-  <img src="docs/images/0.4.19/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
-  <img src="docs/images/0.4.19/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
-  <img src="docs/images/0.4.19/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
-  <img src="docs/images/0.4.19/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
+  <img src="docs/images/0.4.20/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
+  <img src="docs/images/0.4.20/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
+  <img src="docs/images/0.4.20/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
+  <img src="docs/images/0.4.20/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
 </p>
 
 ## Get started

package/docs/distributions.md

@@ -619,12 +619,12 @@ The backend is a strategy, chosen with `secrets.provider` in the org config
 (per engineer in `config/local/user.yml`, per shell with
 `<PREFIX>_SECRETS_PROVIDER`):
 
-| `secrets.provider` | What it is                                                                               |
-| ------------------ | ---------------------------------------------------------------------------------------- |
-| `none`             | No store. Nothing is resolved, no CLI is run; `den create` scaffolds this                |
-| `env`              | Plain environment variables of the process running Den                                   |
-| `doppler`          | The `doppler` CLI (`secrets.doppler: { project, config }` for a default scope)           |
-| `1password`        | The `op` CLI (`secrets.onepassword.account` for the account, else your own `OP_ACCOUNT`) |
+| `secrets.provider` | What it is                                                                                                                                                                   |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `none`             | No store. Nothing is resolved, no CLI is run; `den create` scaffolds this                                                                                                    |
+| `env`              | Plain environment variables of the process running Den                                                                                                                       |
+| `doppler`          | The `doppler` CLI (`secrets.doppler: { project, config }` for a default scope)                                                                                               |
+| `1password`        | The `op` CLI (`secrets.onepassword.account` for the account, else your own `OP_ACCOUNT`; [a service-account token for a service](#1password-for-a-den-running-as-a-service)) |
 
 ```yaml
 # config/acme.yml
@@ -799,6 +799,49 @@ OPENAI_API_KEY (names only; not resolved in a dry run)`.
   (`[A-Za-z_][A-Za-z0-9_]*`). A `stacks:` entry in the org config takes
   `secret_env` too.
 
+## 1Password for a Den running as a service
+
+A Den started by launchd or systemd does not read your login shell, so
+`op` has no `OP_SERVICE_ACCOUNT_TOKEN` and every 1Password ref fails.
+`secrets.onepassword.token` says where this machine keeps the
+service-account token. It is per machine: Den reads it from
+`config/local/user.yml` only, and a value in the distribution's config is
+ignored.
+
+```yaml
+# config/local/user.yml
+secrets:
+  onepassword:
+    token: keychain:op-service-account # or file:~/.config/op/token | env:OP_SERVICE_ACCOUNT_TOKEN
+```
+
+| Value                | Where the token comes from                                                                                               |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `keychain:<service>` | macOS: `security find-generic-password -s <service> -w`, run with no shell. Refused on other systems                     |
+| `file:<path>`        | A file whose mode is exactly 600 (a group or other bit refuses it). `~` expands; a trailing newline is dropped           |
+| `env:<VAR>`          | The env var `<VAR>` of the process running Den. With no key set the default is `env:OP_SERVICE_ACCOUNT_TOKEN`, as before |
+
+- **Checked at config load.** A value that is none of these shapes is
+  refused, naming `secrets.onepassword.token`. The message never repeats
+  the value.
+- **Read each time.** The token is read when a ref is resolved, never
+  cached or written anywhere, and passed only in the `op` child's env as
+  `OP_SERVICE_ACCOUNT_TOKEN`. It is never in a log, an error, the activity
+  records or an API response.
+- **Why a ref failed.** A `secret_env` key that does not resolve says why,
+  in plain words: no service-account token or session; no access to the
+  vault; item or field not found; rate limited; or a short summary of
+  what `op` said. When the token source itself fails (the keychain item is
+  missing, the file's mode is wrong, the env var is unset) the message
+  names the source, never the token.
+- **doctor.** With `secrets.provider: 1password` and a source that yields
+  no token, `doctor` adds a `1password` row: "this process has no
+  service-account token. Set secrets.onepassword.token." It is a warning,
+  not a failure (a signed-in `op` app needs no token). `doctor` only looks
+  a keychain item up; it never reads the token.
+- **Settings.** Settings › Secrets shows the source (`keychain: <service>`,
+  `file: <path>`, `env: <VAR>` or "not set"), never the token.
+
 ## The edge and TLS
 
 The edge is one Traefik per org that routes `<name>.<edge.domain>` (and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.19",
+  "version": "0.4.20",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

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`. */

package/src/ui/cli/doctor-command.ts

@@ -37,8 +37,13 @@ import { readBrand } from "../../shared/brand.js";
 import { hasEdgeBlock, readEdgeConfig } from "../../shared/edge/config.js";
 import { edgeTlsWarnings, tlsStrategyFor } from "../../shared/edge/tls.js";
 import {
+  describeOpTokenSource,
+  opTokenSourceProblem,
+  parseOpTokenSource,
   readSecretsConfig,
+  resolveProviderName,
   secretsStatus,
+  type SecretsConfig,
 } from "../../shared/secrets/index.js";
 import {
   DEN_PTY_ID,
@@ -77,7 +82,22 @@ type Selector = (env: NodeJS.ProcessEnv) => DoctorRow;
 
 const SELECTORS: Record<string, Selector> = {
   secrets(env) {
-    const st = secretsStatus(readSecretsConfig(), env);
+    let cfg: SecretsConfig;
+    try {
+      cfg = readSecretsConfig();
+    } catch (err) {
+      // A bad secrets.* key (naming the key): a problem, not a crash.
+      return {
+        kind: "secrets",
+        selected: "",
+        implicit: false,
+        available: false,
+        reason: (err as Error).message,
+        problem: true,
+        warnings: [],
+      };
+    }
+    const st = secretsStatus(cfg, env);
     return {
       kind: "secrets",
       selected: st.backend,
@@ -172,7 +192,7 @@ export function doctorRows(env: NodeJS.ProcessEnv = process.env): DoctorRow[] {
     ...Object.keys(SELECTORS).filter((k) => kinds.includes(k)),
     ...kinds.filter((k) => !(k in SELECTORS)),
   ];
-  return ordered.map(
+  const rows = ordered.map(
     (kind) =>
       SELECTORS[kind]?.(env) ?? {
         kind,
@@ -184,6 +204,38 @@ export function doctorRows(env: NodeJS.ProcessEnv = process.env): DoctorRow[] {
         warnings: [],
       },
   );
+  const op = onePasswordTokenRow(env);
+  if (op) rows.splice(rows.findIndex((r) => r.kind === "secrets") + 1, 0, op);
+  return rows;
+}
+
+/**
+ * The 1password row: shown only when 1Password is the configured provider
+ * (secret_env refs and the engine's own secrets resolve through it) and the
+ * configured token source yields no token. A warning, not a failure: a
+ * signed-in desktop app needs none. Checks the source without reading a
+ * keychain secret, so nothing prompts.
+ */
+function onePasswordTokenRow(env: NodeJS.ProcessEnv): DoctorRow | null {
+  try {
+    const cfg = readSecretsConfig();
+    if (resolveProviderName(cfg, env) !== "1password") return null;
+    const src = parseOpTokenSource(cfg.onepassword?.token);
+    const why = opTokenSourceProblem(src, { env });
+    if (!why) return null;
+    return {
+      kind: "1password",
+      selected: describeOpTokenSource(src),
+      implicit: false,
+      available: false,
+      reason:
+        "this process has no service-account token. Set secrets.onepassword.token.",
+      problem: false,
+      warnings: [why],
+    };
+  } catch {
+    return null;
+  }
 }
 
 export function formatDoctor(rows: DoctorRow[], title: string): string[] {

package/src/ui/server/index.ts

@@ -173,6 +173,7 @@ import {
 } from "../../shared/auth/sudo-vault.js";
 import {
   notConfiguredMessage,
+  opTokenSourceSetting,
   secretsConfigWarnings,
 } from "../../shared/secrets/index.js";
 import { DEN_BANNER_LINES, DEN_SUBTITLE } from "../../shared/banner.js";
@@ -4860,7 +4861,8 @@ async function handleRequest(
   // ── API: user settings ────────────────────────────────────────────────────
   // GET  /api/settings  → { editor, editors, terminal, terminals, editor_overrides, languages,
   //                         log_window_lines, graph, appearance, shell, distribution,
-  //                         user_web_port, local_dev, cli_tabs, language, ui_languages }
+  //                         user_web_port, local_dev, cli_tabs, language, ui_languages,
+  //                         op_token_source }
   // POST /api/settings  body: { editor?, terminal?, editor_overrides?, graph?, appearance?, shell?,
   //                             language? }
   //   graph: { direction, group, density, panelWidth } (see graph-prefs.ts)
@@ -4929,6 +4931,8 @@ async function handleRequest(
         // what it is when unset (the short hostname).
         machine_name: machineNameSetting(user),
         machine_name_default: machineLabel(null, os.hostname()),
+        // Where the 1Password token comes from (the source, never the token).
+        op_token_source: opTokenSourceSetting(),
       });
     }
     if (req.method === "POST") {

package/src/ui/server/public/i18n/es.js

@@ -402,6 +402,7 @@
     "set.cli.web_port": "Tu puerto web",
     "set.cli.signin": "Inicio de sesión del navegador",
     "set.cli.sudo": "Contraseña de administrador",
+    "set.cli.op_token": "Origen del token de 1Password",
     "set.access.owner": "Propietario",
     "set.access.devices": "Dispositivos vinculados",
     "set.access.waiting": "Dispositivos en espera",

package/src/ui/server/public/i18n/ja.js

@@ -391,6 +391,7 @@
     "set.cli.web_port": "あなたの web ポート",
     "set.cli.signin": "ブラウザのサインイン",
     "set.cli.sudo": "管理者パスワード",
+    "set.cli.op_token": "1Password トークンの取得元",
     "set.access.owner": "オーナー",
     "set.access.devices": "リンク済みデバイス",
     "set.access.waiting": "承認待ちのデバイス",

package/src/ui/server/public/settings-registry.js

@@ -81,6 +81,13 @@ export const DEN_SETTING_CATEGORIES = [
     description:
       "Reach this Den from your other devices: sign in with GitHub as its owner, or pair a device with a one-time link. On localhost nothing asks.",
   },
+  {
+    id: "secrets",
+    label: "Secrets",
+    order: 58,
+    description:
+      "Where this machine gets the credentials Den resolves secrets with. Per machine (config/local/user.yml); only the source is shown, never a secret.",
+  },
   {
     id: "cli",
     label: "Command line",
@@ -1033,6 +1040,21 @@ export const DEN_SETTINGS = [
     read: () => null,
   },
 
+  {
+    // 1Password for a Den running as a service: where its service-account
+    // token comes from (secrets.onepassword.token in user.yml). The source
+    // only, never the token.
+    id: "cli.op_token",
+    category: "secrets",
+    label: "1Password token source",
+    description:
+      "Where this machine's 1Password service-account token comes from, for a Den running as a service. Set secrets.onepassword.token in config/local/user.yml: keychain:<service>, file:<path> or env:<VAR>. The token itself is never shown.",
+    keywords: ["secrets", "1password", "op", "service account", "token"],
+    scope: "user",
+    control: { type: "readonly" },
+    read: (ctx) => ctx.data.op_token_source ?? "not set",
+  },
+
   ...ACCESS_ROWS,
 
   // ── Distribution (read-only) ───────────────────────────────────────────

package/src/ui/server/public/shell.js

@@ -516,6 +516,7 @@
     "set.cli.web_port": "Your web port",
     "set.cli.signin": "Browser sign-in",
     "set.cli.sudo": "Admin password",
+    "set.cli.op_token": "1Password token source",
     "set.access.owner": "Owner",
     "set.access.devices": "Linked devices",
     "ident.local": "Local",