@gotgenes/pi-permission-system 32.0.2 → 32.0.3

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [32.0.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.2...pi-permission-system-v32.0.3) (2026-09-15)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** mask a value bound to a bare or suffixed key name ([f23b8b9](https://github.com/gotgenes/pi-packages/commit/f23b8b93ceafa732ffe9d5484e4a935094d06754)), closes [#920](https://github.com/gotgenes/pi-packages/issues/920)
+* **pi-permission-system:** stop writing a named secret into the permission logs ([cf4f370](https://github.com/gotgenes/pi-packages/commit/cf4f370d192d778e600a253331bbf6e42b3cd758)), closes [#920](https://github.com/gotgenes/pi-packages/issues/920)
+
+### Documentation
+
+* **pi-permission-system:** restate the log-redaction boundary as name-structural ([958cba1](https://github.com/gotgenes/pi-packages/commit/958cba124a1b799a7e6af959440a26d7cf722934)), closes [#920](https://github.com/gotgenes/pi-packages/issues/920)
+* **pi-permission-system:** correct the review-log knob's unredacted claim ([0664a6c](https://github.com/gotgenes/pi-packages/commit/0664a6cf6fbf3e75c4a6864cc582716dd6d15a26)), closes [#920](https://github.com/gotgenes/pi-packages/issues/920)
+
 ## [32.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.1...pi-permission-system-v32.0.2) (2026-09-11)
 
 

package/README.md

@@ -177,7 +177,8 @@ Hardening the gates against bypass, fail-closed corrections (breaking ones inclu
 - _Permissive defaults, trust profiles, or workflow presets._
   Your risk profile is not knowable from here, so defaults are least-privilege and common policies ship as documented recipes rather than preset keywords.
 - _Guessing what is sensitive._
-  No built-in secret denylist, and log redaction is key-name-structural rather than predictive — a redactor that silently misses a key invites treating the log as safe to share.
+  No built-in secret denylist, and log redaction is name-structural rather than predictive: a value is masked because of the name that binds it — a log key, a shell variable, a request header field — never because of what it looks like.
+  A redactor that guesses invites treating the log as safe to share.
 - _Model judgment in the core._
   This package makes no LLM call and holds no model config; model-assisted judging attaches as a chain link over the authorizer seam instead.
   A link decides nothing until you name it in `authorizerChain`, and its `allow` on an excluded surface is downgraded to `defer`.

package/docs/configuration.md

@@ -100,7 +100,7 @@ This clamp is deny-preserving and, like `yoloMode`, applied at composition; when
 | Key                         | Default  | Description                                                                                                                                                                                                                                  |
 | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `debugLog`                  | `false`  | Enables verbose diagnostic logging to `logs/pi-permission-system-debug.jsonl`                                                                                                                                                                |
-| `permissionReviewLog`       | `true`   | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl`. Records bash command strings unredacted — see [Log file sensitivity](#log-file-sensitivity)                                         |
+| `permissionReviewLog`       | `true`   | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl`. Records bash command strings, masked only where a name binds the secret — see [Log file sensitivity](#log-file-sensitivity)         |
 | `yoloMode`                  | `false`  | Auto-approves `ask` results instead of prompting when yolo mode is enabled                                                                                                                                                                   |
 | `doublePressToConfirm`      | `true`   | Requires a confirming second press of a decision hotkey in the inline TUI dialog (see below). TUI sessions only; set to `false` for single-press.                                                                                            |
 | `forwardingTimeoutMs`       | `600000` | How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. A child whose parent is not draining its inbox gives up in ~2 s regardless, whether that parent runs in this process or its own. |
@@ -1197,19 +1197,30 @@ Both logs are created **owner-only** (`0600`, in a `0700` directory), and a log
 The permission-forwarding request and response files are written the same way.
 This closes the shared-host case: another user on the same machine cannot read them.
 
-Values bound to a **sensitive key name** — `authorization`, `token`, `secret`, `password`, `credential`, `cookie`, `api_key`, `private_key`, matched case-insensitively — are masked as `[redacted]` before anything is written.
+Values bound to a **sensitive name** — `authorization`, `token`, `secret`, `password`, `credential`, `cookie`, and a bare or suffixed `key` (`api_key`, `private_key`, `OPENROUTER_KEY`, `apiKey`), matched case-insensitively — are masked as `[redacted]` before anything is written.
 So a tool called with `{"authorization": "Bearer …"}` records `{"authorization": "[redacted]"}`.
 
+A bash command binds values to names too, and the same predicate answers for those.
+The command is parsed, and a value is masked when it is bound to a sensitive name by a shell assignment or a request header field:
+
+```text
+KEY="sk-or-v1-…" curl https://x        →  KEY=[redacted] curl https://x
+env MY_KEY=… deploy                    →  env MY_KEY=[redacted] deploy
+curl -H "Authorization: Bearer sk-…"   →  curl -H "Authorization:[redacted]"
+```
+
 The boundary is worth stating exactly, because it is easy to over-read:
 
-> A value bound to a sensitive key name is masked; a secret embedded in a bash command string is not.
+> A value bound to a sensitive name is masked — whether the name is a log key, a shell variable, or a request header field.
+> A secret with no name bound to it, such as one typed as a `grep` pattern, is not.
 
-A command string has no keys, so `deploy --token abc123` is logged unredacted.
+So `grep -r "sk-ant-…" .` and `deploy --token abc123` are both logged unredacted: the first binds the secret to nothing, and the second binds it to a flag rather than a name.
 The extension deliberately does not try to guess which parts of a command look secret-shaped — see [ADR 0010] for the measured reasoning.
+A command the parser could not fully resolve, and a secret inside an inline-shell payload (`bash -c '…'`) or a heredoc body, are masked only as far as the parse reached.
 
 Every value the **review** log writes is narrowed to `reviewLogFieldMaxWidth` (1000 characters by default) and marked with an ellipsis, so a single pathological command cannot put tens of kilobytes in one entry.
 This is a length bound, not redaction: it never inspects a value to decide what to hide, and it applies to every field alike.
-The two compose — a sensitive-keyed value is masked whole however long it was.
+The two compose, and masking runs first — a sensitively-named value is masked whole however long it was, and the cap never shortens one.
 The debug log is left unbounded, since it is opt-in and exists to be read in full.
 
 Practical guidance:

package/docs/troubleshooting.md

@@ -54,8 +54,9 @@ This makes it easy to verify which files the extension actually loaded:
 - This is a permission decision layer, not a sandbox — for true isolation see [Agent Sandboxes](https://engine.build/lab/agent-sandboxes).
   The two are complementary rather than alternatives: a sandbox enforces which paths are in scope and in which direction, while this package decides whether a particular action on an in-scope path may proceed.
   [ADR 0013] §8 records that division and the seam that exports this package's scope decisions to a sandbox launcher.
-- The review log records bash command strings unredacted.
-  Log files are created owner-only (`0600`), and values bound to a sensitive key name (`authorization`, `token`, `password`, …) are masked — but a secret embedded in a command string is not.
+- The review log records bash command strings, masked only where a name binds the secret.
+  Log files are created owner-only (`0600`), and a value bound to a sensitive name (`authorization`, `token`, `password`, a bare or suffixed `key`, …) is masked — whether the name is a log key, a shell variable, or a request header field.
+  A secret with no name bound to it, such as one typed as a `grep` pattern, is not.
   Review-log values are shortened at `reviewLogFieldMaxWidth` (1000 characters by default), which bounds the file's growth but is a length cap, not redaction.
   See [Log file sensitivity](configuration.md#log-file-sensitivity) and [ADR 0010].
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "32.0.2",
+  "version": "32.0.3",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/access-intent/bash/parser.ts

@@ -15,6 +15,8 @@ export interface TSNode {
   readonly text: string;
   /** Absolute byte offset of this node's start in the parsed source. */
   readonly startIndex: number;
+  /** Absolute byte offset one past this node's end in the parsed source. */
+  readonly endIndex: number;
   readonly childCount: number;
   /** False for anonymous tokens (operators, delimiters); true for named nodes. */
   readonly isNamed: boolean;

package/src/logging/command-redaction.ts

@@ -0,0 +1,241 @@
+import {
+  ARG_NODE_TYPES,
+  resolveNodeText,
+} from "#src/access-intent/bash/node-text";
+import { getWarmBashParser, type TSNode } from "#src/access-intent/bash/parser";
+import { isPlainRecord } from "#src/value-guards";
+import { isSensitiveName, REDACTED_PLACEHOLDER } from "./log-redaction";
+
+/**
+ * Grammar-anchored masking of a secret bound to a sensitive name *inside* a
+ * bash command string.
+ *
+ * Key-name redaction (`log-redaction.ts`) masks a value because of the key it
+ * is bound to, and a command string is one opaque value under the key
+ * `command`. This module asks the same question of the names a command binds
+ * values to — a shell variable and an HTTP header field — so one predicate
+ * answers for all three binding forms.
+ *
+ * Every rule matches a **parse node**, never a substring of the command text.
+ * That is what keeps it usable: measured against a 12 MB review log (7146
+ * unique commands), a raw-string scan for a sensitively-named assignment
+ * matched ten commands and every one was embedded Python (`key=lambda x: x[1]`)
+ * or a `sed` pattern; the same rule anchored to a `variable_assignment` node
+ * matched none. See `docs/decisions/0010-permission-log-secret-exposure.md`.
+ *
+ * A value with no name bound to it — a secret typed as a `grep` pattern — is
+ * out of reach of a structural rule and stays unmasked.
+ */
+
+/** The log keys whose value is a bash command string. */
+export const COMMAND_BEARING_LOG_KEYS: ReadonlySet<string> = new Set([
+  "command",
+  "executedUnit",
+]);
+
+/** A range of the command to replace, and what to put in its place. */
+interface MaskSpan {
+  readonly start: number;
+  readonly end: number;
+  readonly replacement: string;
+}
+
+/**
+ * Mask every sensitively-named value in a bash command string.
+ *
+ * Best-effort by design: a cold parser, a parse that throws, and a parse that
+ * recovered from a syntax error all yield whatever the walk did resolve rather
+ * than blanking the field, because the command text is the main reason the
+ * review log is read. It never throws — the writer sits under the fail-closed
+ * `tool_call` boundary, where a raised mask would cost the whole log line.
+ */
+export function redactCommandSecrets(command: string): string {
+  if (!command) return command;
+
+  try {
+    const parser = getWarmBashParser();
+    if (!parser) return command;
+    const tree = parser.parse(command);
+    if (!tree) return command;
+    try {
+      const spans: MaskSpan[] = [];
+      collectMaskSpans(tree.rootNode, spans);
+      return applyMaskSpans(command, spans);
+    } finally {
+      tree.delete();
+    }
+  } catch {
+    return command;
+  }
+}
+
+/**
+ * Apply {@link redactCommandSecrets} to every command-bearing key in a log
+ * record.
+ *
+ * Recurses through plain objects and arrays, like the width cap beside it: all
+ * of today's producers write `command` and `executedUnit` at the top level, but
+ * a writer stage that only looks at the top level is one a later nested
+ * producer escapes without anyone noticing.
+ */
+export function maskCommandFields<T>(details: T): T {
+  return maskValue(details, false) as T;
+}
+
+function maskValue(value: unknown, bindsCommand: boolean): unknown {
+  if (typeof value === "string") {
+    return bindsCommand ? redactCommandSecrets(value) : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => maskValue(entry, bindsCommand));
+  }
+  if (isPlainRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        maskValue(entry, COMMAND_BEARING_LOG_KEYS.has(key)),
+      ]),
+    );
+  }
+  return value;
+}
+
+function collectMaskSpans(node: TSNode, spans: MaskSpan[]): void {
+  const span = maskSpanOf(node);
+  if (span) spans.push(span);
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) collectMaskSpans(child, spans);
+  }
+}
+
+function maskSpanOf(node: TSNode): MaskSpan | null {
+  return (
+    assignmentValueSpan(node) ??
+    wordAssignmentSpan(node) ??
+    headerValueSpan(node)
+  );
+}
+
+/**
+ * `KEY="sk-…" curl …`, `KEY=sk-…`, `export OPENROUTER_KEY="sk-…"`.
+ *
+ * The span runs to the assignment node's own end rather than the value node's,
+ * so a value the grammar splits across several children is covered whole.
+ */
+function assignmentValueSpan(node: TSNode): MaskSpan | null {
+  if (node.type !== "variable_assignment") return null;
+  const name = node.child(0);
+  if (!name || !isSensitiveName(name.text)) return null;
+  const value = node.child(2);
+  if (!value) return null;
+  return maskSpan(value.startIndex, node.endIndex, REDACTED_PLACEHOLDER);
+}
+
+/**
+ * `env MY_KEY=abc deploy`, which tree-sitter classifies as a plain `word`
+ * rather than an assignment because it follows a command name.
+ *
+ * The name must open with a letter or underscore, so a long option
+ * (`--my-key=abc`) cannot match: an option binds its value to a flag, and the
+ * flag forms are deliberately out of scope.
+ */
+const WORD_ASSIGNMENT = /^([A-Za-z_][A-Za-z0-9_]*)=/;
+
+function wordAssignmentSpan(node: TSNode): MaskSpan | null {
+  if (node.type !== "word") return null;
+  const match = WORD_ASSIGNMENT.exec(node.text);
+  if (!match || !isSensitiveName(match[1])) return null;
+  return maskSpan(
+    node.startIndex + match[0].length,
+    node.endIndex,
+    REDACTED_PLACEHOLDER,
+  );
+}
+
+/** `curl -H "Authorization: Bearer sk-…"`, in any of its quoting forms. */
+const HEADER_FIELD = /^([A-Za-z][A-Za-z0-9_-]*)[ \t]*:[ \t]*\S/;
+
+function headerValueSpan(node: TSNode): MaskSpan | null {
+  if (!ARG_NODE_TYPES.has(node.type)) return null;
+  const match = HEADER_FIELD.exec(resolveNodeText(node));
+  const field = match?.[1];
+  if (!field || !isSensitiveName(field) || isCamelCased(field)) return null;
+  const colon = node.text.indexOf(":");
+  if (colon < 0) return null;
+  // The span swallows a closing quote, so the replacement puts one back and
+  // the masked argument stays quoted the way it was written.
+  return maskSpan(
+    node.startIndex + colon + 1,
+    node.endIndex,
+    REDACTED_PLACEHOLDER + openQuoteAt(node.text, colon),
+  );
+}
+
+/**
+ * An HTTP field name is hyphenated (`X-Api-Key`), never camel-cased.
+ *
+ * Without this the only false positives in the measured corpus were two
+ * records of `grep "legalDirectionalKeys: readonly"` — a search pattern over
+ * TypeScript source, which names a field of nothing.
+ */
+function isCamelCased(field: string): boolean {
+  return /[a-z][A-Z]/.test(field);
+}
+
+/**
+ * The quote character still open at `index`, or the empty string.
+ *
+ * Read at the mask's own position rather than off the argument's first
+ * character: a field name can straddle a quote boundary (`Auth"orization: "$T`),
+ * and the quote the mask swallowed is the one open where it begins.
+ */
+function openQuoteAt(text: string, index: number): string {
+  let quote = "";
+  for (let i = 0; i < index; i++) {
+    const char = text[i];
+    if (quote === "") {
+      if (char === '"' || char === "'") quote = char;
+    } else if (quote === '"' && char === "\\") {
+      i += 1;
+    } else if (char === quote) {
+      quote = "";
+    }
+  }
+  return quote;
+}
+
+function maskSpan(
+  start: number,
+  end: number,
+  replacement: string,
+): MaskSpan | null {
+  return start < end ? { start, end, replacement } : null;
+}
+
+/**
+ * Replace each span, outermost-wins and right to left.
+ *
+ * A sensitive assignment whose value is itself a header argument yields two
+ * spans, one inside the other; masking both would nest a placeholder inside a
+ * region already replaced. Working right to left keeps the earlier offsets
+ * valid as the string shortens.
+ */
+function applyMaskSpans(command: string, spans: MaskSpan[]): string {
+  if (spans.length === 0) return command;
+
+  const ordered = [...spans].sort((a, b) => a.start - b.start || b.end - a.end);
+  const disjoint: MaskSpan[] = [];
+  for (const span of ordered) {
+    const previous = disjoint.at(-1);
+    if (previous && span.start < previous.end) continue;
+    disjoint.push(span);
+  }
+
+  let masked = command;
+  for (const span of disjoint.toReversed()) {
+    masked =
+      masked.slice(0, span.start) + span.replacement + masked.slice(span.end);
+  }
+  return masked;
+}

package/src/logging/log-field-cap.ts

@@ -1,3 +1,5 @@
+import { isPlainRecord } from "#src/value-guards";
+
 /**
  * The permission review log's width bound (ADR 0011 §6).
  *
@@ -57,7 +59,7 @@ function capValue(value: unknown, maxWidth: number): unknown {
   if (Array.isArray(value)) {
     return value.map((entry) => capValue(entry, maxWidth));
   }
-  if (isPlainObject(value)) {
+  if (isPlainRecord(value)) {
     return Object.fromEntries(
       Object.entries(value).map(([key, entry]) => [
         key,
@@ -67,16 +69,3 @@ function capValue(value: unknown, maxWidth: number): unknown {
   }
   return value;
 }
-
-/**
- * Whether a value is a record this cap should descend into.
- *
- * A class instance (a `Date`, an `Error`) is left alone: rebuilding it as a
- * plain object would change what the writer serializes, and the cap's job is
- * to shorten strings, not to reshape a value.
- */
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  if (typeof value !== "object" || value === null) return false;
-  const prototype: unknown = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}

package/src/logging/log-redaction.ts

@@ -1,7 +1,7 @@
 import { createJsonSafeReplacer } from "./json-safe-stringify";
 
 /**
- * Key-name redaction for the permission logs.
+ * Name-based redaction for the permission logs.
  *
  * The technique is deliberately structural rather than predictive: a value is
  * masked because of the *name* it is bound to, never because of what it looks
@@ -9,19 +9,41 @@ import { createJsonSafeReplacer } from "./json-safe-stringify";
  * was measured against a real 6.7 MB review log and declined — see
  * `docs/decisions/0010-permission-log-secret-exposure.md`.
  *
- * The boundary that follows from this, stated once: a value bound to a
- * sensitive key name is masked; a secret embedded in a bash command string is
- * not, because a command string has no keys.
+ * This module owns the predicate and the log-key binding form.
+ * `command-redaction.ts` asks the same predicate about the names a bash
+ * command binds values to.
+ *
+ * The boundary that follows, stated once: a value bound to a sensitive name is
+ * masked — whether the name is a log key, a shell variable, or a request
+ * header field. A secret with no name bound to it, such as one typed as a
+ * `grep` pattern, is not.
  */
 
 export const REDACTED_PLACEHOLDER = "[redacted]";
 
-const SENSITIVE_KEY_PATTERN =
-  /authorization|api[-_]?key|secret|token|password|passwd|credential|cookie|private[-_]?key/i;
+/**
+ * Names that bind a credential, matched case-insensitively.
+ *
+ * `api[-_]?keys?` and `private[-_]?keys?` are kept alongside the general
+ * name-boundary `key` rule rather than subsumed by it, so the whole predicate
+ * is a union with the pattern it replaced and can add a name but never drop
+ * one — the separator-less `apikey` matches only via the specific alternative.
+ */
+const SENSITIVE_NAME_PATTERN =
+  /authorization|api[-_]?keys?|private[-_]?keys?|secret|token|password|passwd|credential|cookie|(?:^|[-_])keys?(?:$|[-_])/i;
+
+/**
+ * A `key` bound as the tail of a camel-cased name (`apiKey`, `sortKeys`).
+ *
+ * Deliberately case-sensitive and separate from the pattern above: under `/i`
+ * the leading `[a-z0-9]` would match an uppercase letter and `Key` would match
+ * `key`, so `monkey` would read as sensitive.
+ */
+const CAMEL_KEY_PATTERN = /[a-z0-9](?:Key|Keys)(?:$|[A-Z_-])/;
 
-/** True when a log key names a credential-bearing value. */
-export function isSensitiveLogKey(key: string): boolean {
-  return SENSITIVE_KEY_PATTERN.test(key);
+/** True when a name binds a credential-bearing value. */
+export function isSensitiveName(name: string): boolean {
+  return SENSITIVE_NAME_PATTERN.test(name) || CAMEL_KEY_PATTERN.test(name);
 }
 
 /**
@@ -36,7 +58,7 @@ export function redactedJsonStringify(value: unknown): string | undefined {
   return JSON.stringify(
     value,
     createJsonSafeReplacer((key, currentValue) =>
-      currentValue != null && isSensitiveLogKey(key)
+      currentValue != null && isSensitiveName(key)
         ? REDACTED_PLACEHOLDER
         : currentValue,
     ),

package/src/logging/logging.ts

@@ -4,6 +4,7 @@ import {
   EXTENSION_ID,
   type PermissionSystemExtensionConfig,
 } from "#src/config/extension-config";
+import { maskCommandFields } from "./command-redaction";
 import { capLogFieldWidths, resolveReviewLogFieldWidth } from "./log-field-cap";
 import {
   OWNER_ONLY_FILE_MODE,
@@ -39,13 +40,41 @@ export function createPermissionSystemLogger(
   const hardened = new Set<string>();
 
   /**
-   * The only place a log line is produced.
+   * The transform stages every log line passes through, in the order they must
+   * run.
+   *
+   * Command masking runs first, and it runs for both streams. Capping a command
+   * before masking it would hand the masker a truncated command — a parse of
+   * something the agent never ran — and the debug stream carries the same
+   * payload as the review stream, so a mask that skipped it would only move the
+   * exposure rather than close it.
    *
    * `maxFieldWidth` bounds every string the line carries; it is supplied for
    * the review stream and withheld for the debug stream, which is opt-in and
-   * exists to be read in full. Capping happens before redaction, which masks
-   * by key name and so still masks a sensitive value whole.
+   * exists to be read in full. Capping happens before key-name redaction, which
+   * masks by name and so still masks a sensitive value whole.
    */
+  const prepareLogLine = (
+    stream: "debug" | "review",
+    event: string,
+    details: Record<string, unknown>,
+    maxFieldWidth?: number,
+  ): string | undefined => {
+    const masked = maskCommandFields(details);
+    const bounded =
+      maxFieldWidth === undefined
+        ? masked
+        : capLogFieldWidths(masked, maxFieldWidth);
+    return redactedJsonStringify({
+      timestamp: new Date().toISOString(),
+      extension: EXTENSION_ID,
+      stream,
+      event,
+      ...bounded,
+    });
+  };
+
+  /** The only place a log line is produced. */
   const writeLine = (
     stream: "debug" | "review",
     path: string,
@@ -59,17 +88,7 @@ export function createPermissionSystemLogger(
     }
 
     try {
-      const bounded =
-        maxFieldWidth === undefined
-          ? details
-          : capLogFieldWidths(details, maxFieldWidth);
-      const line = redactedJsonStringify({
-        timestamp: new Date().toISOString(),
-        extension: EXTENSION_ID,
-        stream,
-        event,
-        ...bounded,
-      });
+      const line = prepareLogLine(stream, event, details, maxFieldWidth);
       if (!line) {
         return `Failed to write permission-system ${stream} log '${path}': event could not be serialized.`;
       }

package/src/value-guards.ts

@@ -6,6 +6,22 @@ export function toRecord(value: unknown): Record<string, unknown> {
   return value as Record<string, unknown>;
 }
 
+/**
+ * Whether a value is a record a structural walk should descend into.
+ *
+ * A class instance (a `Date`, an `Error`) is not: rebuilding one as a plain
+ * object would change what a serializer downstream writes. Distinct from
+ * {@link toRecord}, which reads a value as a record without asking how it was
+ * built.
+ */
+export function isPlainRecord(
+  value: unknown,
+): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
 export function getNonEmptyString(value: unknown): string | null {
   if (typeof value !== "string") {
     return null;