@basein/runner 0.2.11 → 0.3.0

package/dist/record/redact.d.ts

@@ -4,28 +4,122 @@
  * The proxy sits on the credential path for every wrapped server (§9), and every
  * argument and result it sees crosses a process boundary and then the network.
  * So redaction runs on the recording copy of both arguments *and* results,
- * before the step report is even queued.
+ * before the step report is even queued — and once more, as the last line of
+ * defence, on every free-text field `RemoteRecorder` sends (the prompt, the
+ * answer, the reasoning, error messages), because those never pass through a
+ * structured payload at all.
  *
  * Three rules, in the order they fire:
- *   1. **By key.** A value under a key matching {@link SECRET_KEY} is replaced
- *      wholesale, whatever its type. `authorization: { scheme, token }` loses
- *      both halves, because the object as a whole is the secret.
+ *   1. **By key.** A value under a key that names a secret ({@link isSecretKey})
+ *      is replaced wholesale, whatever its type. `authorization: { scheme, token }`
+ *      loses both halves, because the object as a whole is the secret.
  *   2. **`env` blocks.** An object under an `env` key has *every* value replaced.
  *      MCP server configs put credentials there under arbitrary names, so no key
  *      pattern would catch them.
- *   3. **By shape.** A string that looks like a bearer token, a JWT, an
- *      `sk-`/`ghp_`-style key or an AWS access key id is replaced wherever it
- *      appears — including inside free text, where key-matching cannot reach.
+ *   3. **By shape.** A string that looks like a credential — a bearer token, a
+ *      JWT, a provider key, a PEM private key, a password in a URL, a
+ *      `DB_PASSWORD=…` line of a `.env` file, an `X-Api-Key:` header — is
+ *      replaced wherever it appears, including inside free text, where key
+ *      matching cannot reach. Reading `.env` or `~/.aws/credentials` is a routine
+ *      thing for an agent to do; its result is recorded like any other.
+ *
+ * KEYS ARE MATCHED ON WHOLE NAME SEGMENTS, not substrings. The old rule was one
+ * unanchored alternation, so `author`, `max_tokens`, `nextPageToken` and
+ * `tokenizer` were all "secrets" — the recording lost real arguments (numbers
+ * became the string "[redacted]") and a scenario built from it had nothing to
+ * replay. Names are split on camelCase, snake_case, kebab-case and dots, and a
+ * segment has to *be* the secret word (`token`, `accessToken`, `x-api-key`), not
+ * merely contain it. The names 0.2.12's substring rule caught that do hold
+ * credentials are still caught: plurals (`tokens`, `api_keys`), an `auth` that
+ * ends the name (`basic_auth`, `X-Upstream-Auth`), `oauth`, `authentication`,
+ * `auth_code` — and a number under the secret itself (`token: 482913`, an OTP).
+ *
+ * TEXT RULES ARE ANCHORED TO WHERE SECRETS ARE WRITTEN, not to every
+ * `name = value` in sight. A recorded Read of source code must survive: its
+ * bytes are what a scenario's output logic is authored against, and
+ * `const token = await getToken()` is not a secret. So assignments are only
+ * redacted in env/ini/YAML line form, shell `NAME=value` form, header form and
+ * JSON `"key": "value"` form, and never when the value is visibly code (a call,
+ * a member access, a `${reference}`, a type in a declaration such as
+ * `password: string`, or a variable named for the same thing such as
+ * `token: newToken`). A separator never spans a line break: an empty
+ * `DB_PASSWORD=` must not take the next line with it.
+ *
+ * JSON TEXT IS REDACTED AS JSON. A serialized tool payload goes through
+ * {@link redactJsonText}, which parses it and runs the rules on each string
+ * leaf — the same pass its producer's {@link redact} made — so the result is
+ * always valid JSON and, when nothing new was found, the producer's bytes
+ * exactly (live replay serializes a result the same way and compares). The
+ * rules still tolerate JSON-escaped text (a string leaf that holds a JSON
+ * document, a preview of one): they never start a match inside an escape
+ * sequence and never replace a quote or a backslash, so an escaped document
+ * stays parseable.
  *
  * Redaction never throws and never mutates its input: a cycle, a `BigInt`, a
  * getter that explodes — each degrades to a placeholder rather than losing the
  * step or, worse, taking the session down.
  */
 export declare const REDACTED = "[redacted]";
-/** Keys whose values are secret regardless of shape. */
+/**
+ * The substring rule this module used before key segments. Kept exported for
+ * anything that imported it, and applied again under `BIR_REDACT_LEGACY_KEYS=1`.
+ *
+ * @deprecated over-matches ordinary names (`author`, `max_tokens`); use {@link isSecretKey}.
+ */
 export declare const SECRET_KEY: RegExp;
-/** Replace every secret-shaped run inside a string. */
+/**
+ * A string leaf longer than this is cut before its shapes are scanned. Every
+ * consumer caps a recorded payload far below it (64 KiB), so the cut is never
+ * visible in what is sent — it only stops a 20 MB tool result from costing a
+ * few hundred milliseconds of regex work on a hook's path.
+ */
+export declare const REDACT_SCAN_MAX_CHARS: number;
+/**
+ * How strongly a key names a secret. `strong` redacts any value but a boolean
+ * — the secret itself (`password`, `token`, `api_key`, `mfa_token`) may well
+ * be a number: a one-time code, a PIN, a numeric key. `weak` (a session id,
+ * something *about* a token such as `token_id`, a list such as `tokens`)
+ * keeps numbers and booleans too, which are ids, counters and flags there far
+ * more often than they are credentials.
+ */
+export type SecretKeyStrength = "strong" | "weak";
+export declare function secretKeyStrength(name: string): SecretKeyStrength | undefined;
+/** True when a value under `name` is a secret (see {@link secretKeyStrength}). */
+export declare function isSecretKey(name: string): boolean;
+/**
+ * The same question for an UPPER_SNAKE environment variable name, where the
+ * words run together (`PGPASSWORD`, `GITHUB_TOKEN`, `AWS_SECRET_ACCESS_KEY`)
+ * and substring matching is the convention rather than the mistake — minus
+ * the counters (`MAX_TOKENS`, `TOKENIZERS_PARALLELISM`) and file pointers
+ * (`PASSWORD_FILE`, the Docker secrets convention).
+ */
+export declare function isSecretEnvName(name: string): boolean;
+/**
+ * Replace every secret-shaped run inside a string.
+ *
+ * Idempotent: redacting the result again changes nothing. That is what lets a
+ * payload be redacted by its producer and again at the recorder without its
+ * bytes moving (live replay compares against them). One pass is not always a
+ * fixed point — a match one rule declined (`Authorization: Authorization: …`)
+ * can hide a secret that only shows once a later rule has run — so a pass that
+ * changed something is followed by another, until one changes nothing.
+ */
 export declare function redactText(text: string): string;
+/**
+ * Redact a string that holds JSON — a serialized tool input, result or error —
+ * and return JSON, always.
+ *
+ * Running {@link redactText} over the serialized text could not promise that:
+ * a rule that met `\n` after an empty `KEY=` wrote `KEY=\[redacted]`, and the
+ * service stored a payload no parser accepts. So the text is parsed and every
+ * string leaf gets the rules as plain text, exactly as its producer's
+ * {@link redact} did. When that finds nothing new — the normal case, since
+ * producers redact first — the original bytes come back untouched: live replay
+ * serializes a result the same way and compares against what was recorded.
+ * Text that is not JSON (a truncated preview, a producer's plain error) gets
+ * {@link redactText}: there is no structure to keep.
+ */
+export declare function redactJsonText(text: string): string;
 /**
  * Deep-clone `value` with secrets removed. The result is always JSON-safe, so
  * the caller can serialise it without a second failure mode.