@moxxy/sdk 0.32.0 → 0.34.0

package/src/fs-utils.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdirSync, promises as fsp, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { chmod, mkdir, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -11,6 +11,19 @@ export interface WriteFileAtomicOptions {
   readonly encoding?: BufferEncoding;
 }
 
+/**
+ * The private-path helpers below dispatch through `fs.promises` rather than
+ * destructured `node:fs/promises` bindings so the framework keeps ONE mockable
+ * filesystem boundary: a destructured binding is captured at import time and no
+ * longer observable, which silently blinds the regression guards that count
+ * `fs.open` / `fs.mkdir` calls (persistence.ready.test.ts).
+ */
+
+/** Owner-only directory: no group/other bits, so nobody else can even traverse in. */
+export const PRIVATE_DIR_MODE = 0o700;
+/** Owner-only file. */
+export const PRIVATE_FILE_MODE = 0o600;
+
 /**
  * Crash-atomic file write: write a unique sibling temp file, then `rename` it
  * over the target. POSIX `rename` is atomic on the same filesystem, so a crash
@@ -84,3 +97,109 @@ export function moxxyHome(): string {
 export function moxxyPath(...segments: string[]): string {
   return join(moxxyHome(), ...segments);
 }
+
+/**
+ * POSIX permission bits are meaningless on Windows (`chmod` only toggles the
+ * read-only flag; access is governed by ACLs), so the tightening helpers below
+ * are no-ops there rather than pretending to enforce something they cannot.
+ */
+const POSIX_PERMS = process.platform !== 'win32';
+
+/** Group/other bits. Their presence is what makes a path readable by another
+ *  local account, and is the only condition worth a `chmod` syscall. */
+const GROUP_OTHER = 0o077;
+
+/**
+ * `mkdir -p` a directory that must stay owner-only, tightening it when it
+ * already exists with looser bits.
+ *
+ * The tightening pass is what makes this safe to adopt mid-life: installs
+ * created before this was enforced have a `0755` directory on disk, and
+ * `mkdir` is a no-op on an existing path, so mode alone would never fix them.
+ *
+ * Best-effort by design: a permission error (a directory owned by another user,
+ * an exotic filesystem, a network mount) must never take down a boot whose only
+ * problem is that a chmod did not stick. Directory CREATION still throws, since
+ * failing to create the state directory is a real failure.
+ */
+export async function ensurePrivateDir(dir: string): Promise<void> {
+  await fsp.mkdir(dir, { recursive: true, mode: PRIVATE_DIR_MODE });
+  await tightenIfLoose(dir, PRIVATE_DIR_MODE);
+}
+
+/**
+ * Create-if-absent a file that must stay owner-only, tightening it when it
+ * already exists with looser bits. `open(path, 'a')` creates with
+ * `0o666 & ~umask` (typically `0644`), so an append-only log needs the mode
+ * applied explicitly and retroactively.
+ */
+export async function ensurePrivateFile(file: string): Promise<void> {
+  const handle = await fsp.open(file, 'a', PRIVATE_FILE_MODE);
+  await handle.close();
+  await tightenIfLoose(file, PRIVATE_FILE_MODE);
+}
+
+async function tightenIfLoose(target: string, mode: number): Promise<void> {
+  if (!POSIX_PERMS) return;
+  try {
+    const st = await fsp.stat(target);
+    if ((st.mode & GROUP_OTHER) === 0) return;
+    await fsp.chmod(target, mode);
+  } catch {
+    /* best-effort: never fail a boot over a chmod */
+  }
+}
+
+/**
+ * The temp-file shape {@link writeFileAtomic} renames from:
+ * `<target>.<pid>.<uuid>.tmp`. Anchored, and specific enough that a user file
+ * that merely ends in `.tmp` can never match.
+ */
+const ATOMIC_TMP = /\.\d+\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/i;
+
+/** Age past which an atomic-write temp file is certainly abandoned. A live
+ *  write is sub-second; anything a day old outlived the process that made it. */
+const STALE_TMP_AGE_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Delete abandoned {@link writeFileAtomic} temp files in `dirs`.
+ *
+ * `writeFileAtomic` unlinks its temp file when the write throws, but it cannot
+ * when the process is `SIGKILL`ed mid-write, so residue accumulates for the
+ * life of the install (six such files, the oldest a month old, prompted this).
+ *
+ * Two properties keep this safe against a CONCURRENT moxxy process writing to
+ * the same directory: only the exact `.<pid>.<uuid>.tmp` shape is considered,
+ * and only entries older than {@link STALE_TMP_AGE_MS}. A temp file that is
+ * still live is milliseconds old and can never be selected.
+ *
+ * Non-recursive and fully best-effort: it returns the number removed and never
+ * throws, so callers can fire it detached at boot without guarding it.
+ */
+export async function pruneStaleTempFiles(
+  dirs: ReadonlyArray<string>,
+  now = Date.now(),
+): Promise<number> {
+  let removed = 0;
+  for (const dir of dirs) {
+    let names: string[];
+    try {
+      names = await fsp.readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      if (!ATOMIC_TMP.test(name)) continue;
+      const full = join(dir, name);
+      try {
+        const st = await fsp.stat(full);
+        if (now - st.mtimeMs < STALE_TMP_AGE_MS) continue;
+        await fsp.rm(full, { force: true });
+        removed++;
+      } catch {
+        /* raced with another pruner, or not ours to delete */
+      }
+    }
+  }
+  return removed;
+}

package/src/hooks.ts

@@ -3,6 +3,7 @@ import type { EventLogReader } from './log.js';
 import type { PendingToolCall } from './permission.js';
 import type { ProviderRequest } from './provider.js';
 import type { SessionId, TurnId } from './ids.js';
+import type { Principal } from './principal.js';
 import type { ServiceRegistry } from './services.js';
 
 export interface AppContext {
@@ -10,6 +11,13 @@ export interface AppContext {
   readonly cwd: string;
   readonly log: EventLogReader;
   readonly env: Readonly<Record<string, string | undefined>>;
+  /**
+   * Who the session is attributed to, when the surface could establish it.
+   * This is what lets a policy or audit hook answer "who is asking" instead of
+   * only "what is being asked". Absent means unattributed: a hook that gates on
+   * identity must fail closed on `undefined` rather than assuming an admin.
+   */
+  readonly actor?: Principal;
   /**
    * Inter-plugin service registry — publish a service in `onInit` for sibling
    * plugins to consume in theirs. See {@link ServiceRegistry}.

package/src/host-credential.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { hostCredentialName } from './secret-provider.js';
+
+describe('hostCredentialName', () => {
+  it('upper-snakes a host, mirroring the provider-key convention', () => {
+    expect(hostCredentialName('github.example.com')).toBe('MOXXY_CREDENTIAL_GITHUB_EXAMPLE_COM');
+  });
+
+  it('accepts a full URL and uses only its host', () => {
+    expect(hostCredentialName('https://registry.example.internal/moxxy/index.json')).toBe(
+      'MOXXY_CREDENTIAL_REGISTRY_EXAMPLE_INTERNAL',
+    );
+  });
+
+  // A credential belongs to the host, not to a socket, so the same secret
+  // serves the mirror whether or not the URL happens to name a port.
+  it('ignores the port', () => {
+    expect(hostCredentialName('registry.internal:8443')).toBe(hostCredentialName('registry.internal'));
+    expect(hostCredentialName('https://registry.internal:8443/x')).toBe(
+      hostCredentialName('registry.internal'),
+    );
+  });
+
+  it('collapses runs of non-alphanumerics and trims the edges', () => {
+    expect(hostCredentialName('my--host..internal')).toBe('MOXXY_CREDENTIAL_MY_HOST_INTERNAL');
+  });
+
+  it('handles an IPv6 literal', () => {
+    expect(hostCredentialName('https://[::1]:9000/x')).toBe('MOXXY_CREDENTIAL_1');
+  });
+
+  // Deriving a name from garbage would silently look up the wrong secret, which
+  // reads as "no credential configured" rather than as the typo it is.
+  it('returns null rather than a name derived from nonsense', () => {
+    for (const bad of ['', '   ', 'not a host', 'https://', '://x']) {
+      expect(hostCredentialName(bad)).toBeNull();
+    }
+  });
+});

package/src/index.ts

@@ -42,6 +42,50 @@ export type {
 
 export type { EventLogReader } from './log.js';
 
+// Identity. The type + pure helpers ride the main barrel; the OS resolver needs
+// `node:os` and is exported from `@moxxy/sdk/server`.
+export type { Principal } from './principal.js';
+export { samePrincipal, formatPrincipal } from './principal.js';
+
+export { verifyEd25519 } from './signature.js';
+
+export { TOOL_ICONS, isToolIcon, type ToolIcon } from './tool-icon.js';
+
+export type {
+  AuditExporterDef,
+  AuditExportBatch,
+  AuditExportContext,
+  AuditExportResource,
+} from './audit-export.js';
+export { defineAuditExporter } from './audit-export.js';
+
+// Audit trail: the tamper-evident receipt, distinct from the event log.
+export type {
+  AuditAction,
+  AuditRecord,
+  AuditSinkDef,
+  AuditSinkScope,
+  AuditSinkSession,
+  UnchainedAuditRecord,
+} from './audit.js';
+export { defineAuditSink, auditActionOf } from './audit.js';
+
+// Where a named secret comes from (external store instead of the local vault).
+export type {
+  SecretProviderDef,
+  SecretProviderScope,
+  SecretProviderSession,
+} from './secret-provider.js';
+export { defineSecretProvider, hostCredentialName } from './secret-provider.js';
+
+// Secret redaction for anything leaving the process.
+export {
+  isSecretKey,
+  redactSecrets,
+  redactSecretText,
+  REDACTED_PLACEHOLDER,
+} from './redact.js';
+
 export type {
   RunTurnOptions,
   SessionLogReader,
@@ -217,6 +261,11 @@ export {
   type ResolvedProviderTools,
 } from './provider-tool-utils.js';
 export type { WriteFileAtomicOptions } from './fs-utils.js';
+export type {
+  EgressProxySettings,
+  EgressStatus,
+  InstallEgressProxyOptions,
+} from './egress.js';
 export type { ChannelRunStatus } from './channel-status.js';
 export type { CrossProcessFireLock, CrossProcessFireLockOptions } from './cross-process-lock.js';
 export { createMutex, type Mutex } from './mutex.js';

package/src/mode/react-loop.ts

@@ -260,7 +260,16 @@ export async function* runReactLoop(
       return;
     }
 
-    const systemPrompt = buildSystemPromptWithSkills(ctx.systemPrompt, ctx.skills.list());
+    // A text-only provider cannot call `load_skill`. Advertising the lazy skill
+    // index anyway makes agent-shaped transports (notably Claude Code CLI)
+    // imitate the unavailable call as plain assistant text and then end the
+    // turn. Keep the base prompt, but only advertise lazy skills when the
+    // selected model can actually execute the loader. Unknown/dynamic model ids
+    // retain the historical tool-capable behavior, matching collect-stream's
+    // conservative capability fallback.
+    const descriptor = ctx.provider.models.find((candidate) => candidate.id === ctx.model);
+    const availableSkills = descriptor?.supportsTools === false ? [] : ctx.skills.list();
+    const systemPrompt = buildSystemPromptWithSkills(ctx.systemPrompt, availableSkills);
     const { messages, stablePrefixIndex } = projectMessages(ctx, {
       ...(systemPrompt ? { systemPrompt } : {}),
       ...(volatileText ? { trailingUserText: volatileText } : {}),

package/src/plugin.ts

@@ -17,6 +17,9 @@ import type { ViewRendererDef } from './view-renderer.js';
 import type { TunnelProviderDef } from './tunnel.js';
 import type { WorkflowExecutorDef } from './workflow.js';
 import type { EventStoreDef } from './event-store.js';
+import type { AuditSinkDef } from './audit.js';
+import type { AuditExporterDef } from './audit-export.js';
+import type { SecretProviderDef } from './secret-provider.js';
 import type { ReflectorDef } from './reflector.js';
 
 export type PluginKind = 'tools' | 'provider' | 'mode' | 'compactor' | 'cache-strategy' | 'view-renderer' | 'tunnel-provider' | 'mcp' | 'cli' | 'channel' | 'surface' | 'hooks' | 'agent' | 'command' | 'transcriber' | 'synthesizer' | 'embedder' | 'isolator' | 'workflow-executor' | 'event-store' | 'reflector';
@@ -54,6 +57,13 @@ export interface PluginSpec {
    * boundary, since the store sees every event). See {@link EventStoreDef}.
    */
   readonly eventStores?: ReadonlyArray<EventStoreDef>;
+  /** Audit-trail sinks (syslog, OTel, S3, webhook). Registered alongside the
+   *  protected local floor; never auto-activated, see registry-kinds. */
+  readonly auditSinks?: ReadonlyArray<AuditSinkDef>;
+  readonly auditExporters?: ReadonlyArray<AuditExporterDef>;
+  /** External secret stores (Vault, AWS/Azure, 1Password). Registered
+   *  alongside the vault floor; never auto-activated. */
+  readonly secretProviders?: ReadonlyArray<SecretProviderDef>;
   /**
    * Reflector backends — the learning-loop block that watches a finished turn
    * and *proposes* memory/skill improvements without silently writing. One

package/src/principal-os.ts

@@ -0,0 +1,48 @@
+import { hostname, userInfo } from 'node:os';
+import type { Principal } from './principal.js';
+
+/**
+ * The local OS account, as a {@link Principal}.
+ *
+ * This is the FLOOR identity: it is what the TUI and other local surfaces
+ * attribute to when no stronger issuer (a channel token, an OIDC assertion) is
+ * available. Its trust is exactly the trust of local account separation, which
+ * is why {@link Principal.issuer} says `os` rather than pretending to more.
+ *
+ * The id is `user@host` because a bare username is ambiguous the moment
+ * transcripts from several machines reach one audit sink.
+ */
+export function resolveOsPrincipal(): Principal {
+  const user = safeUsername();
+  const host = safeHostname();
+  return {
+    id: host ? `${user}@${host}` : user,
+    kind: 'human',
+    issuer: 'os',
+    displayName: user,
+  };
+}
+
+/**
+ * `userInfo()` throws when the uid has no passwd entry, which happens in
+ * distroless containers and some CI images. An unattributed session is worse
+ * than a coarse one, so fall back rather than fail.
+ */
+function safeUsername(): string {
+  try {
+    const name = userInfo().username.trim();
+    if (name.length > 0) return name;
+  } catch {
+    /* fall through */
+  }
+  const fromEnv = (process.env.USER ?? process.env.USERNAME ?? '').trim();
+  return fromEnv.length > 0 ? fromEnv : 'unknown';
+}
+
+function safeHostname(): string {
+  try {
+    return hostname().trim();
+  } catch {
+    return '';
+  }
+}

package/src/principal.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { formatPrincipal, samePrincipal, type Principal } from './principal.js';
+import { resolveOsPrincipal } from './principal-os.js';
+
+const alice: Principal = { id: 'alice', kind: 'human', issuer: 'os' };
+
+describe('samePrincipal', () => {
+  // An id is only unique inside its issuer's namespace. Collapsing that would
+  // let a weakly-issued identity impersonate a strongly-issued one of the same
+  // name, which is the whole reason `issuer` exists.
+  it('requires the issuer to match, not just the id', () => {
+    expect(samePrincipal(alice, { ...alice, issuer: 'oidc' })).toBe(false);
+    expect(samePrincipal(alice, { ...alice, displayName: 'Alice A.' })).toBe(true);
+  });
+
+  it('treats undefined as unattributed, not as a wildcard', () => {
+    expect(samePrincipal(undefined, alice)).toBe(false);
+    expect(samePrincipal(alice, undefined)).toBe(false);
+    expect(samePrincipal(undefined, undefined)).toBe(true);
+  });
+});
+
+describe('formatPrincipal', () => {
+  it('renders issuer:id, never the display name', () => {
+    expect(formatPrincipal({ ...alice, displayName: 'Alice A.' })).toBe('os:alice');
+  });
+
+  it('names the absent case explicitly', () => {
+    expect(formatPrincipal(undefined)).toBe('unattributed');
+  });
+});
+
+describe('resolveOsPrincipal', () => {
+  it('issues a human principal scoped to the host', () => {
+    const p = resolveOsPrincipal();
+    expect(p.kind).toBe('human');
+    expect(p.issuer).toBe('os');
+    expect(p.id.length).toBeGreaterThan(0);
+    expect(p.displayName).toBeTruthy();
+  });
+
+  // A bare username collides the moment transcripts from several machines land
+  // in one audit sink.
+  it('qualifies the id with the hostname', () => {
+    expect(resolveOsPrincipal().id).toContain('@');
+  });
+});

package/src/principal.ts

@@ -0,0 +1,60 @@
+/**
+ * Who an action was taken on behalf of.
+ *
+ * Until this existed the event log recorded `source` (a CATEGORY: user, model,
+ * tool, plugin, system, compactor) but never a subject, so a transcript proved
+ * that a machine did something, not that a person did. That makes audit,
+ * role-based policy, and cost attribution impossible to build on top, and all
+ * three are table stakes for a shared or managed deployment.
+ *
+ * A `Principal` is deliberately small and provider-neutral: the identity blocks
+ * that will issue it (OS user, channel bearer token, OAuth/OIDC subject, a
+ * GitHub App installation) agree on this shape and nothing more.
+ */
+export interface Principal {
+  /**
+   * Stable identifier within {@link issuer}'s namespace. Only meaningful when
+   * paired with the issuer: `alice` from `os` and `alice` from `oidc` are not
+   * the same subject, so consumers comparing identities must compare both.
+   */
+  readonly id: string;
+  /**
+   * `human` when a person is behind the action, `service` for an unattended
+   * runner (a schedule, a webhook, a CI job). The distinction matters to policy:
+   * "a human approved this" is a different claim from "a daemon did it".
+   */
+  readonly kind: 'human' | 'service';
+  /**
+   * What vouched for the identity: `os`, `channel-token`, `oauth`, or the name
+   * of the plugin that resolved it. Records HOW MUCH the identity is worth. An
+   * `os` principal is only as trustworthy as local account separation; an
+   * `oidc` one carries a verified assertion.
+   */
+  readonly issuer: string;
+  /** Human-readable label for surfaces. Never used for comparison. */
+  readonly displayName?: string;
+  /**
+   * Additional verified attributes (email, groups, tenant). Kept flat and
+   * stringly-typed so it survives JSON round-trips through the event log and
+   * the runner wire protocol without a schema per issuer.
+   */
+  readonly claims?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Whether two principals denote the same subject. Compares issuer AND id: an id
+ * is only unique inside its issuer's namespace (see {@link Principal.id}).
+ */
+export function samePrincipal(a: Principal | undefined, b: Principal | undefined): boolean {
+  if (!a || !b) return a === b;
+  return a.issuer === b.issuer && a.id === b.id;
+}
+
+/**
+ * Compact `issuer:id` label for logs and status lines. Deliberately NOT the
+ * display name: an audit line has to be unambiguous, and display names are
+ * neither unique nor stable.
+ */
+export function formatPrincipal(principal: Principal | undefined): string {
+  return principal ? `${principal.issuer}:${principal.id}` : 'unattributed';
+}

package/src/redact.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import { isSecretKey, redactSecretText, redactSecrets } from './redact.js';
+
+describe('isSecretKey', () => {
+  it('recognises the common secret-bearing field names', () => {
+    for (const key of ['apiKey', 'api_key', 'SECRET', 'authToken', 'privateKey', 'Authorization']) {
+      expect(isSecretKey(key)).toBe(true);
+    }
+  });
+
+  it('does not flag ordinary fields', () => {
+    for (const key of ['command', 'path', 'name', 'monkey']) expect(isSecretKey(key)).toBe(false);
+  });
+});
+
+describe('redactSecretText', () => {
+  // The motivating case: the carrier field is `command`, so key-name redaction
+  // alone prints the token verbatim.
+  it('masks a bearer token inside a shell command', () => {
+    const out = redactSecretText('curl -H "Authorization: Bearer sk-ant-api03-XYZ123456789" https://api');
+    expect(out).not.toContain('XYZ123456789');
+    expect(out).toContain('[redacted]');
+    // The attempt itself must stay visible: an auditor needs to see a header
+    // was sent, not just that something was hidden.
+    expect(out).toContain('curl');
+    expect(out.toLowerCase()).toContain('authorization');
+  });
+
+  it('masks vendor key formats wherever they appear', () => {
+    const cases: ReadonlyArray<[string, string]> = [
+      ['sk-ant-api03-ABCDEFGHIJKLMNOP', 'ABCDEFGHIJKLMNOP'],
+      ['ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ012345', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'],
+      ['xoxb-1234567890-ABCDEFGH', 'ABCDEFGH'],
+      ['AKIAIOSFODNN7EXAMPLE', 'IOSFODNN7EXAMPLE'],
+      ['AIzaSyA1234567890abcdefghijklmnop', 'SyA1234567890abcdefghijklmnop'],
+    ];
+    for (const [input, secret] of cases) {
+      expect(redactSecretText(`value=${input}`)).not.toContain(secret);
+    }
+  });
+
+  it('masks a JWT', () => {
+    const jwt = 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NX0.SflKxwRJSMeKKF2QT4fwpMeJf36P';
+    expect(redactSecretText(`token ${jwt}`)).toContain('[redacted-jwt]');
+  });
+
+  it('masks credentials embedded in a URL', () => {
+    const out = redactSecretText('https://alice:hunter2@proxy.corp:3128/path');
+    expect(out).not.toContain('hunter2');
+    expect(out).toContain('proxy.corp');
+  });
+
+  it('masks KEY=value style assignments', () => {
+    const out = redactSecretText('export GITHUB_TOKEN=abcdef123456 && run');
+    expect(out).not.toContain('abcdef123456');
+    expect(out).toContain('GITHUB_TOKEN');
+  });
+
+  it('leaves ordinary text alone', () => {
+    const text = 'ls -la /home/alice && grep -r "monkey" src/';
+    expect(redactSecretText(text)).toBe(text);
+  });
+});
+
+describe('redactSecrets', () => {
+  it('drops the value of a secret-named field entirely', () => {
+    expect(redactSecrets({ apiKey: 'sk-whatever' })).toEqual({ apiKey: '[redacted]' });
+  });
+
+  it('scans ordinary string fields for secret shapes', () => {
+    const out = redactSecrets({ command: 'curl -H "Authorization: Bearer sk-ant-ABCDEFGH12345678"' });
+    expect(JSON.stringify(out)).not.toContain('ABCDEFGH12345678');
+  });
+
+  it('walks arrays and nested objects', () => {
+    const out = redactSecrets({ steps: [{ env: { TOKEN: 'ghp_ABCDEFGHIJKLMNOPQRSTUV' } }] });
+    expect(JSON.stringify(out)).not.toContain('ABCDEFGHIJKLMNOPQRSTUV');
+  });
+
+  it('bounds the walk so a pathological input cannot blow the stack', () => {
+    let deep: Record<string, unknown> = { apiKey: 'sk-deep' };
+    for (let i = 0; i < 500; i++) deep = { nested: deep };
+    expect(() => redactSecrets(deep)).not.toThrow();
+  });
+
+  it('passes non-objects through unchanged', () => {
+    expect(redactSecrets(42)).toBe(42);
+    expect(redactSecrets(null)).toBe(null);
+    expect(redactSecrets(undefined)).toBe(undefined);
+  });
+});

package/src/redact.ts

@@ -0,0 +1,91 @@
+/**
+ * Secret redaction for anything that leaves the process: an audit record, a
+ * terminal prompt, a support paste.
+ *
+ * Two independent passes, because they catch different things and either alone
+ * leaves a real hole:
+ *
+ *   - by KEY NAME, for `{ apiKey: 'sk-…' }`, where the value is opaque.
+ *   - by VALUE SHAPE, for a secret embedded in an ordinary-looking field. The
+ *     motivating case is a Bash tool call: its `command` is not a secret-named
+ *     key, so a key-name pass alone prints
+ *     `curl -H "Authorization: Bearer sk-ant-…"` verbatim.
+ *
+ * Deliberately NOT a guarantee. A redactor that claims completeness invites
+ * treating redacted output as safe to publish; treat it as reducing accidental
+ * exposure, not as sanitisation.
+ */
+
+/** Field names whose VALUES are secret material regardless of shape. */
+const SECRET_KEY =
+  /(?:api[_-]?key|secret|token|password|passwd|passphrase|authorization|auth[_-]?token|bearer|credential|private[_-]?key|access[_-]?key)/i;
+
+/**
+ * Value shapes that are secrets wherever they appear. Ordered vendor prefixes
+ * first (precise, no false positives) then generic bearer/assignment forms.
+ *
+ * Each pattern keeps any leading context in a capture group so the replacement
+ * can preserve it: masking `Authorization: Bearer X` down to just `[redacted]`
+ * would lose the fact that a header was there at all, which matters when the
+ * point is auditing what was attempted.
+ */
+const SECRET_VALUE_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
+  // Vendor-issued key formats.
+  [/\b(sk-ant-)[A-Za-z0-9_-]{8,}/g, '$1[redacted]'],
+  [/\b(sk-)[A-Za-z0-9_-]{16,}/g, '$1[redacted]'],
+  [/\b(gh[pousr]_)[A-Za-z0-9]{16,}/g, '$1[redacted]'],
+  [/\b(xox[baprs]-)[A-Za-z0-9-]{8,}/g, '$1[redacted]'],
+  [/\b(AKIA)[0-9A-Z]{12,}/g, '$1[redacted]'],
+  [/\b(AIza)[A-Za-z0-9_-]{20,}/g, '$1[redacted]'],
+  // JWTs: three base64url segments.
+  [/\b(ey[A-Za-z0-9_-]{8,})\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, 'eyJ[redacted-jwt]'],
+  // `Authorization: Bearer <anything>` in a header or a shell command.
+  [/\b(authorization\s*[:=]\s*(?:bearer|basic|token)\s+)\S+/gi, '$1[redacted]'],
+  [/\b(bearer\s+)[A-Za-z0-9._~+/=-]{12,}/gi, '$1[redacted]'],
+  // `FOO_TOKEN=value` / `--api-key value` style assignments.
+  [
+    /\b([A-Za-z0-9_-]*(?:key|token|secret|password|passwd)[A-Za-z0-9_-]*\s*[:=]\s*)(?!\s)["']?[^\s"'&;|]{6,}["']?/gi,
+    '$1[redacted]',
+  ],
+  // Credentials embedded in a URL.
+  [/\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)[^\s@]+(@)/gi, '$1[redacted]$2'],
+];
+
+export const REDACTED_PLACEHOLDER = '[redacted]';
+
+/** True when a field name reads as secret-bearing. */
+export function isSecretKey(key: string): boolean {
+  return SECRET_KEY.test(key);
+}
+
+/**
+ * Mask secret-shaped substrings inside a free-text value. This is the pass that
+ * covers shell commands, URLs, and headers, where the carrier field has an
+ * innocuous name.
+ */
+export function redactSecretText(text: string): string {
+  let out = text;
+  for (const [pattern, replacement] of SECRET_VALUE_PATTERNS) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}
+
+/**
+ * Redact a structured value: secret-named fields lose their value entirely,
+ * every other string is scanned for secret-shaped content.
+ *
+ * `maxDepth` bounds the walk so a pathologically nested input cannot blow the
+ * stack; anything deeper is returned unredacted, which is why callers that
+ * accept untrusted shapes should also cap size before display.
+ */
+export function redactSecrets(value: unknown, maxDepth = 6, depth = 0): unknown {
+  if (typeof value === 'string') return redactSecretText(value);
+  if (depth >= maxDepth || value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map((v) => redactSecrets(v, maxDepth, depth + 1));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    out[k] = SECRET_KEY.test(k) ? REDACTED_PLACEHOLDER : redactSecrets(v, maxDepth, depth + 1);
+  }
+  return out;
+}