@codedology/code-forge 0.9.0 → 0.10.0

package/src/engines/sandbox-dirs.mjs

@@ -0,0 +1,257 @@
+/**
+ * The Codex coder sandbox profile (block B93): `coder.sandbox.{profile, add_dirs}`.
+ *
+ * Facts (Codex 0.155.1, `test/fixtures/help/codex-0.155.1.txt`): `--add-dir <DIR>` = "Additional
+ * directories that should be writable alongside the primary workspace"; `-s` takes `read-only`,
+ * `workspace-write` or `danger-full-access`.
+ *
+ * Profiles:
+ *  - `workspace` (the default, and what no `coder` key means): today's argv, `-s workspace-write`
+ *    with the project `-C <cwd>` as the only writable root.
+ *  - `toolchain`: the same, plus one `--add-dir <abs>` per `add_dirs` entry (a build cache, a
+ *    package store), right after `-s workspace-write`.
+ *  - `full`: `-s danger-full-access`. Codex writes anywhere the user can; like the Claude coder
+ *    (bypassPermissions), the forbidden list, the transcript grep and the gates are the limits.
+ *
+ * Every `add_dirs` entry is absolute or starts with `~/` (expanded against the process HOME). It is
+ * resolved component by component: each symlink is replaced by its target (bounded; a loop is
+ * refused), `..` steps up from the resolved dir, a missing tail is kept as written, and the
+ * existing part is the native realpath (true case). So a symlink, even a dangling one, is judged
+ * by its target. Matching folds case on macOS and Windows. An entry is REFUSED (`sandbox-dir-refused`) when it is `/`, the home dir itself, or is,
+ * contains or sits inside: `~/.code-forge`, `~/.codex` (and `$CODEX_HOME`), `~/.ssh`, `~/.gnupg`,
+ * `~/.aws`, `~/.config`, `~/Library/Keychains`, the run temp base / run temp root, or the session
+ * CODEX_HOME. A refusal names the key path (`coder.sandbox.add_dirs[<i>]`), never the value.
+ *
+ * Pure apart from `lstat`/`readlink`/`realpath`; it never creates, lists or writes a directory.
+ */
+
+import { lstatSync, readlinkSync, realpathSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** The profiles, in the order the docs list them. */
+export const SANDBOX_PROFILES = Object.freeze(['workspace', 'toolchain', 'full']);
+
+/** The default profile: today's argv. */
+export const DEFAULT_SANDBOX_PROFILE = 'workspace';
+
+/** The error code a refused `add_dirs` entry carries (validation rule and builder). */
+export const SANDBOX_DIR_REFUSED = 'sandbox-dir-refused';
+
+/** Home-relative directories no coder sandbox may open (nor any dir that holds or sits in one). */
+export const PROTECTED_HOME_DIRS = Object.freeze(['.code-forge', '.codex', '.ssh', '.gnupg', '.aws', '.config', path.join('Library', 'Keychains')]);
+
+/** An `Error` with a `code` of {@link SANDBOX_DIR_REFUSED}. */
+export class SandboxDirError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'SandboxDirError';
+    this.code = SANDBOX_DIR_REFUSED;
+  }
+}
+
+/** The most symlinks one entry may pass through before it is refused (as the kernel's ELOOP). */
+const MAX_LINK_HOPS = 40;
+
+/** A path whose symlinks cannot be followed (a loop, too many hops, an unreadable link). */
+class Unresolvable extends Error {}
+
+/** @param {string} p @returns {string} the native realpath (true case), or `p` when it fails. */
+function native(p) {
+  try {
+    return realpathSync.native(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Resolve `p` the way the kernel would: walk it one component at a time with `lstat`; a symlink is
+ * replaced by its target (read with `readlink`, followed again, bounded); `..` steps up from the
+ * resolved dir, never lexically. A missing component ends the walk: the existing part is the
+ * native realpath, the rest is kept as written. So a dangling symlink is judged by its target.
+ * @param {string} p - absolute.
+ * @param {{n: number}} [hops]
+ * @returns {string}
+ * @throws {Unresolvable} on a loop, too many hops, or a component that cannot be read.
+ */
+function resolvePath(p, hops = { n: 0 }) {
+  const { root } = path.parse(p);
+  const parts = p.slice(root.length).split(path.sep).filter((c) => c.length > 0 && c !== '.');
+  let cur = root;
+  for (let i = 0; i < parts.length; i += 1) {
+    if (parts[i] === '..') {
+      cur = path.dirname(cur);
+      continue;
+    }
+    const next = path.join(cur, parts[i]);
+    let st;
+    try {
+      st = lstatSync(next);
+    } catch (err) {
+      const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+      if (code === 'ENOENT' || code === 'ENOTDIR') return path.join(native(cur), ...parts.slice(i));
+      throw new Unresolvable();
+    }
+    if (!st.isSymbolicLink()) {
+      cur = next;
+      continue;
+    }
+    hops.n += 1;
+    if (hops.n > MAX_LINK_HOPS) throw new Unresolvable();
+    let target;
+    try {
+      target = readlinkSync(next);
+    } catch {
+      throw new Unresolvable();
+    }
+    cur = resolvePath(path.isAbsolute(target) ? target : `${cur}${path.sep}${target}`, hops);
+  }
+  return native(cur);
+}
+
+/** @param {string} p @returns {string} a refused tree, resolved; a tree that cannot be is kept as written. */
+function resolveTree(p) {
+  try {
+    return resolvePath(path.resolve(p));
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/** Case-insensitive by default on macOS and Windows: compare folded there, so a missing tree is matched too. */
+const FOLD_CASE = process.platform === 'darwin' || process.platform === 'win32';
+
+/** @param {string} p @returns {string} */
+function fold(p) {
+  return FOLD_CASE ? p.toLowerCase() : p;
+}
+
+/** @param {string} a @param {string} b @returns {boolean} `a` is `b` (both resolved; case folded where the FS is). */
+function same(a, b) {
+  return fold(a) === fold(b);
+}
+
+/** @param {string} a @param {string} b @returns {boolean} `a` is `b` or inside it (both resolved). */
+function within(a, b) {
+  const rel = path.relative(fold(b), fold(a));
+  if (rel === '') return true;
+  return !(rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel));
+}
+
+/** @param {NodeJS.ProcessEnv} env @returns {string} */
+function homeOf(env) {
+  return typeof env.HOME === 'string' && env.HOME.length > 0 ? env.HOME : os.homedir();
+}
+
+/**
+ * Expand one entry: absolute, or `~/…` against `home`. Anything else is `null`. `.` and `..` are
+ * kept as written: the resolver steps through them after following symlinks.
+ * @param {unknown} entry @param {string} home @returns {string | null}
+ */
+export function expandSandboxDir(entry, home) {
+  if (typeof entry !== 'string' || entry.length === 0 || entry.includes('\0')) return null;
+  if (entry.startsWith('~/')) return `${path.resolve(home)}${path.sep}${entry.slice(2)}`;
+  if (path.isAbsolute(entry)) return entry;
+  return null;
+}
+
+/**
+ * @typedef {object} SandboxGuards
+ * @property {NodeJS.ProcessEnv} [env] - the env whose HOME / CODEX_HOME count (default `process.env`).
+ * @property {ReadonlyArray<string | null | undefined>} [extra] - more refused trees: the run temp
+ *   base or root, the session CODEX_HOME (absolute paths; `null`/`undefined` are skipped).
+ */
+
+/**
+ * The refused trees for `guards`, each resolved once.
+ * @param {SandboxGuards} guards
+ * @returns {{home: string, realHome: string, protectedTrees: string[], runTrees: string[]}}
+ */
+function refusedTrees(guards) {
+  const env = guards.env ?? process.env;
+  const home = homeOf(env);
+  const protectedTrees = PROTECTED_HOME_DIRS.map((d) => resolveTree(path.join(home, d)));
+  if (typeof env.CODEX_HOME === 'string' && path.isAbsolute(env.CODEX_HOME)) protectedTrees.push(resolveTree(env.CODEX_HOME));
+  /** @type {string[]} */
+  const runTrees = [];
+  for (const p of guards.extra ?? []) {
+    if (typeof p === 'string' && path.isAbsolute(p)) runTrees.push(resolveTree(p));
+  }
+  return { home, realHome: resolveTree(home), protectedTrees, runTrees };
+}
+
+/**
+ * Check one `add_dirs` entry against resolved trees.
+ * @param {unknown} entry @param {number} index @param {ReturnType<typeof refusedTrees>} trees
+ * @returns {{ok: true, dir: string} | {ok: false, keyPath: string, why: string}}
+ */
+function checkOne(entry, index, trees) {
+  const keyPath = `coder.sandbox.add_dirs[${index}]`;
+  const expanded = expandSandboxDir(entry, trees.home);
+  if (expanded === null) return { ok: false, keyPath, why: 'it must be an absolute path or start with ~/' };
+  let real;
+  try {
+    real = resolvePath(expanded);
+  } catch {
+    return { ok: false, keyPath, why: 'its symlinks cannot be resolved' };
+  }
+  if (real === path.parse(real).root) return { ok: false, keyPath, why: 'it is the filesystem root' };
+  if (same(real, trees.realHome)) return { ok: false, keyPath, why: 'it is the home directory' };
+  if (within(trees.realHome, real)) return { ok: false, keyPath, why: 'it holds the home directory' };
+  if (trees.protectedTrees.some((t) => within(real, t) || within(t, real))) {
+    return { ok: false, keyPath, why: 'it is, holds or sits inside a protected directory (~/.code-forge, ~/.codex, ~/.ssh, ~/.gnupg, ~/.aws, ~/.config, ~/Library/Keychains)' };
+  }
+  if (trees.runTrees.some((t) => within(real, t) || within(t, real))) {
+    return { ok: false, keyPath, why: 'it is, holds or sits inside the run temp root or the session CODEX_HOME' };
+  }
+  return { ok: true, dir: real };
+}
+
+/**
+ * Every refused `add_dirs` entry (validation reports each one).
+ * @param {unknown} dirs @param {SandboxGuards} [guards]
+ * @returns {Array<{keyPath: string, why: string}>}
+ */
+export function sandboxDirRefusals(dirs, guards = {}) {
+  if (dirs === undefined) return [];
+  if (!Array.isArray(dirs)) return [{ keyPath: 'coder.sandbox.add_dirs', why: 'it must be a list of directories' }];
+  const trees = refusedTrees(guards);
+  /** @type {Array<{keyPath: string, why: string}>} */
+  const out = [];
+  dirs.forEach((entry, i) => {
+    const one = checkOne(entry, i, trees);
+    if ('keyPath' in one) out.push({ keyPath: one.keyPath, why: one.why });
+  });
+  return out;
+}
+
+/**
+ * Check `add_dirs` and resolve each entry; the first refusal wins (the builder fails closed).
+ * @param {unknown} dirs - the `coder.sandbox.add_dirs` value.
+ * @param {SandboxGuards} [guards]
+ * @returns {{ok: true, dirs: string[]} | {ok: false, keyPath: string, why: string}} `why` names a
+ *   category, never the value.
+ */
+export function checkSandboxDirs(dirs, guards = {}) {
+  if (dirs === undefined) return { ok: true, dirs: [] };
+  if (!Array.isArray(dirs)) return { ok: false, keyPath: 'coder.sandbox.add_dirs', why: 'it must be a list of directories' };
+  const trees = refusedTrees(guards);
+  /** @type {string[]} */
+  const out = [];
+  for (let i = 0; i < dirs.length; i += 1) {
+    const one = checkOne(dirs[i], i, trees);
+    if ('keyPath' in one) return { ok: false, keyPath: one.keyPath, why: one.why };
+    out.push(one.dir);
+  }
+  return { ok: true, dirs: out };
+}
+
+/**
+ * The message of a refusal: the key path and the category, never the value.
+ * @param {{keyPath: string, why: string}} refusal @returns {string}
+ */
+export function sandboxRefusalMessage(refusal) {
+  return `${SANDBOX_DIR_REFUSED}: ${refusal.keyPath} is refused — ${refusal.why}`;
+}

package/src/keys/store.mjs

@@ -5,11 +5,15 @@
  *   1. env var       — `env:NAME` from the reference, else `CODE_FORGE_KEY_<NAME>`
  *   2. OS keychain   — this store (`@napi-rs/keyring` → macOS `security` CLI → 0600 file)
  *   3. 1Password     — `op read <op://…>` (retry once on a first-call timeout); a hit is cached
- *                      into the store as `{"v", "exp"}` for `cacheHours` (default 8)
+ *                      into the store as `{"v", "exp"}` for `cacheHours` (whole hours 1–24,
+ *                      default 8; `keys.cache_hours` / `keys set --cache-hours`, B84)
  *   4. ask           — hidden input, only when the caller passes `ask` (setup only)
  * An entry whose `exp` has passed is deleted on that first read and treated as absent, so the
- * chain moves on to 1Password and refreshes it. A backend that fails to read is skipped with a
- * non-secret reason (backend name + error code) in `errors`; the chain never aborts on it.
+ * chain moves on to 1Password and refreshes it. A cached entry is never trusted for longer than
+ * the reader's hours (B84, D2): a read whose entry has `exp > now + hours` moves the expiry
+ * earlier to `now + hours` (entry and index row rewritten, value kept, 1Password not asked); an
+ * expiry is never moved later, and a read with no hours caps at `MAX_CACHE_HOURS`. A backend that
+ * fails to read is skipped with a non-secret reason (backend name + error code) in `errors`; the chain never aborts on it.
  *
  * `source` names where the value came from: `env`, the store backend that held it (`keychain`,
  * `security-cli`, `file`), `op`, or `ask`.
@@ -18,7 +22,11 @@
  * redacted output path (`util/log`, `util/redact`) masks it from then on. Nothing here prints.
  *
  * Alongside the secrets the store keeps `index.json` (0600, no values): name → source, backend,
- * exp — what `keys list` shows.
+ * exp, and (B85) the `op://` reference a 1Password read came from — what `keys list` shows and
+ * what its re-link hint names. A row written before B85 has no `ref` and still lists.
+ *
+ * An entry dropped as expired is reported to the reader (B85): `resolveKey` returns its old `exp`
+ * as `expired` when nothing else resolved, so `jev ask` can print the exact re-link command.
  *
  * @typedef {object} Backend
  * @property {string} name
@@ -28,8 +36,8 @@
  * @property {(name: string, value: string) => Promise<void>} set
  * @property {(name: string) => Promise<boolean>} delete
  *
- * @typedef {{name: string, source: string, backend: string, exp: number|null}} IndexRow
- * @typedef {{value: string|null, source: string|null, exp: number|null, errors: string[]}} Resolution
+ * @typedef {{name: string, source: string, backend: string, exp: number|null, ref?: string}} IndexRow
+ * @typedef {{value: string|null, source: string|null, exp: number|null, errors: string[], expired?: number|null}} Resolution
  */
 
 import { readFile } from 'node:fs/promises';
@@ -42,6 +50,11 @@ import { createSecurityCliBackend } from './backends/security-cli.mjs';
 import { isOpRef, opRead as realOpRead } from './onepassword.mjs';
 
 export const DEFAULT_CACHE_HOURS = 8;
+/** The bounds of `keys.cache_hours` / `--cache-hours`; the schema carries the same numbers. */
+export const MIN_CACHE_HOURS = 1;
+export const MAX_CACHE_HOURS = 24;
+/** The one text for an out-of-range cache time; it never carries the value. */
+export const CACHE_HOURS_RULE = `a whole number of hours from ${MIN_CACHE_HOURS} to ${MAX_CACHE_HOURS}`;
 const HOUR_MS = 3_600_000;
 const NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
 
@@ -74,6 +87,62 @@ export function parseRef(name, ref) {
   return { envName, storeName, opRef: ref?.startsWith('op://') ? ref : null };
 }
 
+/**
+ * @param {unknown} exp
+ * @returns {exp is number} a time in ms that `new Date(exp)` can print: finite, |exp| <= 8.64e15.
+ */
+export function isTime(exp) {
+  return typeof exp === 'number' && Number.isFinite(exp) && Math.abs(exp) <= 8.64e15;
+}
+
+/**
+ * A reference as one POSIX shell word for a re-link command a human copies (B85): unchanged when
+ * every character is in `[A-Za-z0-9_./:@%+=-]`, else wrapped in single quotes with each `'` written
+ * as `'\''`.
+ * @param {string} ref
+ * @returns {string}
+ */
+export function shellWord(ref) {
+  return /^[A-Za-z0-9_./:@%+=-]+$/.test(ref) ? ref : `'${ref.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * @param {unknown} hours
+ * @returns {hours is number} a whole number of hours within the bounds.
+ */
+export function isCacheHours(hours) {
+  return Number.isInteger(hours) && /** @type {number} */ (hours) >= MIN_CACHE_HOURS && /** @type {number} */ (hours) <= MAX_CACHE_HOURS;
+}
+
+/**
+ * @param {unknown} hours
+ * @returns {number} the hours, when they are within the bounds.
+ * @throws {RangeError} otherwise — no path may cache for longer than the maximum.
+ */
+function assertCacheHours(hours) {
+  if (!isCacheHours(hours)) {
+    throw new RangeError(`cache hours must be ${CACHE_HOURS_RULE}`);
+  }
+  return hours;
+}
+
+/**
+ * The cache time a project asks for (`keys.cache_hours`). Absent ⇒ the default; present and valid
+ * ⇒ that value; anything else ⇒ the default with a problem text (never the value itself).
+ * @param {Record<string, any> | null | undefined} cfg
+ * @returns {{hours: number, source: 'config'|'default', problem: string|null}}
+ */
+export function cacheHoursFrom(cfg) {
+  const keys = cfg?.keys;
+  if (keys === null || typeof keys !== 'object' || !Object.hasOwn(keys, 'cache_hours')) {
+    return { hours: DEFAULT_CACHE_HOURS, source: 'default', problem: null };
+  }
+  if (isCacheHours(keys.cache_hours)) {
+    return { hours: keys.cache_hours, source: 'config', problem: null };
+  }
+  return { hours: DEFAULT_CACHE_HOURS, source: 'default', problem: `keys.cache_hours must be ${CACHE_HOURS_RULE}` };
+}
+
 /**
  * @param {string} value
  * @param {number|null} exp
@@ -122,8 +191,9 @@ export function codeForgeHome(env = process.env) {
  * @param {object} opts
  * @param {Backend[]} opts.backends - candidates, most preferred first; unavailable ones are dropped.
  * @param {string} opts.dir - where `index.json` lives.
+ * @param {typeof writePrivateFile} [opts.writeIndexFile] - writes `index.json` (tests inject a failure).
  */
-export async function createKeyStore({ backends, dir }) {
+export async function createKeyStore({ backends, dir, writeIndexFile = writePrivateFile }) {
   /** @type {Backend[]} */
   const live = [];
   for (const backend of backends) {
@@ -153,7 +223,7 @@ export async function createKeyStore({ backends, dir }) {
   const updateIndex = async (change) => {
     const index = await readIndex();
     change(index);
-    await writePrivateFile(indexFile, JSON.stringify(index, null, 2));
+    await writeIndexFile(indexFile, JSON.stringify(index, null, 2));
   };
 
   return {
@@ -165,10 +235,14 @@ export async function createKeyStore({ backends, dir }) {
      * @param {string} name
      * @param {number} now
      * @param {string[]} [errors] - receives one non-secret reason per backend that failed.
+     * @param {{maxHours?: number, onExpired?: (exp: number) => void}} [opts] - the reader's cache
+     *   time; a longer `exp` is cut to `now + maxHours` (default `MAX_CACHE_HOURS`). `onExpired`
+     *   gets the old `exp` of an entry this read dropped as expired (B85).
      * @returns {Promise<{value: string, exp: number|null, backend: string}|null>}
      */
-    async read(name, now, errors = []) {
+    async read(name, now, errors = [], { maxHours = MAX_CACHE_HOURS, onExpired } = {}) {
       assertKeyName(name);
+      const latest = now + assertCacheHours(maxHours) * HOUR_MS;
       for (const backend of readOrder) {
         let raw;
         try {
@@ -186,11 +260,36 @@ export async function createKeyStore({ backends, dir }) {
           await backend.delete(name).catch((err) => {
             errors.push(`${backend.name}: delete of expired entry failed (${reasonOf(err)})`);
           });
+          // reported first, and a failed index update is a reason, never a reject: the reader still
+          // learns the key expired
+          onExpired?.(entry.exp);
           await updateIndex((index) => {
             delete index[name];
+          }).catch((err) => {
+            errors.push(`index: removal of the expired entry failed (${reasonOf(err)})`);
           });
           return null;
         }
+        if (entry.exp !== null && entry.exp > latest) {
+          // D2: the shorter expiry applies now; the value stays and 1Password is not asked
+          // a failed rewrite leaves the index alone (it still matches the stored entry);
+          // the index row is only adjusted when one exists, never invented
+          const rewritten = await backend.set(name, encodeEntry(entry.value, latest)).then(
+            () => true,
+            (err) => {
+              errors.push(`${backend.name}: rewrite of the shortened expiry failed (${reasonOf(err)})`);
+              return false;
+            },
+          );
+          if (rewritten) {
+            await updateIndex((index) => {
+              if (index[name]) index[name] = { ...index[name], backend: backend.name, exp: latest };
+            }).catch((err) => {
+              errors.push(`index: rewrite of the shortened expiry failed (${reasonOf(err)})`);
+            });
+          }
+          return { value: entry.value, exp: latest, backend: backend.name };
+        }
         return { ...entry, backend: backend.name };
       }
       return null;
@@ -199,9 +298,10 @@ export async function createKeyStore({ backends, dir }) {
     /**
      * @param {string} name
      * @param {string} value
-     * @param {{source: string, exp: number|null}} meta
+     * @param {{source: string, exp: number|null, ref?: string}} meta - `ref` (B85): the `op://`
+     *   reference the value was read from; it goes to the index, never a value.
      */
-    async put(name, value, { source, exp }) {
+    async put(name, value, { source, exp, ref }) {
       assertKeyName(name);
       if (!writer) {
         throw new Error('keys: no writable backend');
@@ -209,7 +309,7 @@ export async function createKeyStore({ backends, dir }) {
       registerSecret(value);
       await writer.set(name, encodeEntry(value, exp));
       await updateIndex((index) => {
-        index[name] = { source, backend: writer.name, exp };
+        index[name] = { source, backend: writer.name, exp, ...(typeof ref === 'string' ? { ref } : {}) };
       });
     },
 
@@ -238,6 +338,7 @@ export async function createKeyStore({ backends, dir }) {
           source: String(index[name].source),
           backend: String(index[name].backend),
           exp: index[name].exp ?? null,
+          ...(typeof index[name].ref === 'string' ? { ref: index[name].ref } : {}),
         }));
     },
   };
@@ -267,8 +368,8 @@ export function createDefaultKeyStore(
 }
 
 /**
- * Read a key from 1Password and cache it into the store as `{v, exp}` for `cacheHours`. A cache
- * write failure is reported in `errors` but does not lose the value just read.
+ * Read a key from 1Password and cache it into the store as `{v, exp}` for `cacheHours`; the index
+ * row records `opRef` (B85). A cache write failure is reported in `errors` but does not lose the value just read.
  *
  * @param {string} storeName
  * @param {string} opRef
@@ -280,6 +381,7 @@ export function createDefaultKeyStore(
  * @returns {Promise<Resolution>}
  */
 export async function readOpAndCache(storeName, opRef, { store, opRead = realOpRead, now = Date.now(), cacheHours = DEFAULT_CACHE_HOURS }) {
+  assertCacheHours(cacheHours);
   const res = await opRead(opRef);
   if (res.value === null) {
     return { value: null, source: null, exp: null, errors: [res.error ?? 'op read failed'] };
@@ -288,7 +390,7 @@ export async function readOpAndCache(storeName, opRef, { store, opRead = realOpR
   const exp = now + cacheHours * HOUR_MS;
   /** @type {string[]} */
   const errors = [];
-  await store.put(storeName, res.value, { source: 'op', exp }).catch((err) => {
+  await store.put(storeName, res.value, { source: 'op', exp, ref: opRef }).catch((err) => {
     errors.push(`cache write failed (${reasonOf(err)})`);
   });
   return { value: res.value, source: 'op', exp, errors };
@@ -305,11 +407,14 @@ export async function readOpAndCache(storeName, opRef, { store, opRead = realOpR
  * @param {typeof realOpRead} [deps.opRead]
  * @param {(name: string) => Promise<string|null>} [deps.ask] - setup only; omitted everywhere else.
  * @param {number} [deps.now]
- * @param {number} [deps.cacheHours]
- * @returns {Promise<Resolution>}
+ * @param {number} [deps.cacheHours] - how long a 1Password read is cached, and the longest a cached
+ *   entry is trusted. Omitted: cached for `DEFAULT_CACHE_HOURS`, trusted up to `MAX_CACHE_HOURS`.
+ * @returns {Promise<Resolution>} when nothing resolved, `expired` is the old `exp` of a cached
+ *   entry this call dropped as expired, else null (B85).
  */
-export async function resolveKey(name, { store, ref, env = process.env, opRead = realOpRead, ask, now = Date.now(), cacheHours = DEFAULT_CACHE_HOURS }) {
+export async function resolveKey(name, { store, ref, env = process.env, opRead = realOpRead, ask, now = Date.now(), cacheHours }) {
   const { envName, storeName, opRef } = parseRef(name, ref);
+  const maxHours = cacheHours === undefined ? MAX_CACHE_HOURS : assertCacheHours(cacheHours);
   /** @type {string[]} */
   const errors = [];
 
@@ -319,13 +424,15 @@ export async function resolveKey(name, { store, ref, env = process.env, opRead =
     return { value: fromEnv, source: 'env', exp: null, errors };
   }
 
-  const cached = await store.read(storeName, now, errors);
+  /** @type {number|null} */
+  let expired = null;
+  const cached = await store.read(storeName, now, errors, { maxHours, onExpired: (exp) => { expired = exp; } });
   if (cached) {
     return { value: cached.value, source: cached.backend, exp: cached.exp, errors };
   }
 
   if (opRef) {
-    const fromOp = await readOpAndCache(storeName, opRef, { store, opRead, now, cacheHours });
+    const fromOp = await readOpAndCache(storeName, opRef, { store, opRead, now, cacheHours: cacheHours ?? DEFAULT_CACHE_HOURS });
     errors.push(...fromOp.errors);
     if (fromOp.value !== null) {
       return { ...fromOp, errors };
@@ -343,5 +450,5 @@ export async function resolveKey(name, { store, ref, env = process.env, opRead =
     }
   }
 
-  return { value: null, source: null, exp: null, errors };
+  return { value: null, source: null, exp: null, errors, expired };
 }