@bookedsolid/rea 0.3.0 → 0.5.0

package/dist/policy/loader.d.ts

@@ -13,6 +13,13 @@ declare const PolicySchema: z.ZodObject<{
     blocked_paths: z.ZodArray<z.ZodString, "many">;
     notification_channel: z.ZodDefault<z.ZodString>;
     injection_detection: z.ZodOptional<z.ZodEnum<["block", "warn"]>>;
+    injection: z.ZodOptional<z.ZodObject<{
+        suspicious_blocks_writes: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        suspicious_blocks_writes?: boolean | undefined;
+    }, {
+        suspicious_blocks_writes?: boolean | undefined;
+    }>>;
     context_protection: z.ZodOptional<z.ZodObject<{
         delegate_to_subagent: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         max_bash_output_lines: z.ZodOptional<z.ZodNumber>;
@@ -25,10 +32,16 @@ declare const PolicySchema: z.ZodObject<{
     }>>;
     review: z.ZodOptional<z.ZodObject<{
         codex_required: z.ZodOptional<z.ZodBoolean>;
+        cache_max_age_seconds: z.ZodOptional<z.ZodNumber>;
+        allow_skip_in_ci: z.ZodOptional<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         codex_required?: boolean | undefined;
+        cache_max_age_seconds?: number | undefined;
+        allow_skip_in_ci?: boolean | undefined;
     }, {
         codex_required?: boolean | undefined;
+        cache_max_age_seconds?: number | undefined;
+        allow_skip_in_ci?: boolean | undefined;
     }>>;
     redact: z.ZodOptional<z.ZodObject<{
         match_timeout_ms: z.ZodOptional<z.ZodNumber>;
@@ -94,12 +107,17 @@ declare const PolicySchema: z.ZodObject<{
     blocked_paths: string[];
     notification_channel: string;
     injection_detection?: "block" | "warn" | undefined;
+    injection?: {
+        suspicious_blocks_writes?: boolean | undefined;
+    } | undefined;
     context_protection?: {
         delegate_to_subagent: string[];
         max_bash_output_lines?: number | undefined;
     } | undefined;
     review?: {
         codex_required?: boolean | undefined;
+        cache_max_age_seconds?: number | undefined;
+        allow_skip_in_ci?: boolean | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;
@@ -127,12 +145,17 @@ declare const PolicySchema: z.ZodObject<{
     block_ai_attribution?: boolean | undefined;
     notification_channel?: string | undefined;
     injection_detection?: "block" | "warn" | undefined;
+    injection?: {
+        suspicious_blocks_writes?: boolean | undefined;
+    } | undefined;
     context_protection?: {
         delegate_to_subagent?: string[] | undefined;
         max_bash_output_lines?: number | undefined;
     } | undefined;
     review?: {
         codex_required?: boolean | undefined;
+        cache_max_age_seconds?: number | undefined;
+        allow_skip_in_ci?: boolean | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;

package/dist/policy/loader.js

@@ -24,6 +24,8 @@ const ContextProtectionSchema = z.object({
 const ReviewPolicySchema = z
     .object({
     codex_required: z.boolean().optional(),
+    cache_max_age_seconds: z.number().int().positive().optional(),
+    allow_skip_in_ci: z.boolean().optional(),
 })
     .strict();
 /**
@@ -64,6 +66,33 @@ const AuditPolicySchema = z
     rotation: AuditRotationPolicySchema.optional(),
 })
     .strict();
+/**
+ * G9: injection tier escalation. `suspicious_blocks_writes` is fully
+ * optional at the schema layer — absence is distinguishable from an
+ * explicit `false`. The middleware (`createInjectionMiddleware`) then
+ * applies the action-aware default:
+ *
+ *   - `injection_detection: block` (default) + flag unset  → `true`
+ *     (0.2.x parity — a single literal match at write/destructive tier
+ *     still denies for upgraded consumers who omit the `injection:` block)
+ *   - `injection_detection: block` + flag explicit `false` → `false`
+ *     (explicit opt-out)
+ *   - `injection_detection: warn`  + flag unset or `false` → `false`
+ *     (warn mode preserves 0.2.x warn-only semantics)
+ *   - flag explicit `true` (pinned in `bst-internal*`)      → `true`
+ *
+ * This avoids the Codex-reported regression in PR #25 where the schema
+ * default of `false` silently loosened `injection_detection: block`
+ * behavior on upgrade for non-bst consumers.
+ *
+ * `likely_injection` verdicts (multi-literal matches, base64-decoded matches,
+ * or any read-tier match) are ALWAYS deny regardless of this flag.
+ */
+const InjectionPolicySchema = z
+    .object({
+    suspicious_blocks_writes: z.boolean().optional(),
+})
+    .strict();
 const PolicySchema = z
     .object({
     version: z.string(),
@@ -77,6 +106,7 @@ const PolicySchema = z
     blocked_paths: z.array(z.string()),
     notification_channel: z.string().default(''),
     injection_detection: z.enum(['block', 'warn']).optional(),
+    injection: InjectionPolicySchema.optional(),
     context_protection: ContextProtectionSchema.optional(),
     review: ReviewPolicySchema.optional(),
     redact: RedactPolicySchema.optional(),

package/dist/policy/profiles.d.ts

@@ -28,6 +28,13 @@ export declare const ProfileSchema: z.ZodObject<{
     blocked_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     notification_channel: z.ZodOptional<z.ZodString>;
     injection_detection: z.ZodOptional<z.ZodEnum<["block", "warn"]>>;
+    injection: z.ZodOptional<z.ZodObject<{
+        suspicious_blocks_writes: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        suspicious_blocks_writes?: boolean | undefined;
+    }, {
+        suspicious_blocks_writes?: boolean | undefined;
+    }>>;
     context_protection: z.ZodOptional<z.ZodObject<{
         delegate_to_subagent: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         max_bash_output_lines: z.ZodOptional<z.ZodNumber>;
@@ -46,6 +53,9 @@ export declare const ProfileSchema: z.ZodObject<{
     blocked_paths?: string[] | undefined;
     notification_channel?: string | undefined;
     injection_detection?: "block" | "warn" | undefined;
+    injection?: {
+        suspicious_blocks_writes?: boolean | undefined;
+    } | undefined;
     context_protection?: {
         delegate_to_subagent?: string[] | undefined;
         max_bash_output_lines?: number | undefined;
@@ -58,6 +68,9 @@ export declare const ProfileSchema: z.ZodObject<{
     blocked_paths?: string[] | undefined;
     notification_channel?: string | undefined;
     injection_detection?: "block" | "warn" | undefined;
+    injection?: {
+        suspicious_blocks_writes?: boolean | undefined;
+    } | undefined;
     context_protection?: {
         delegate_to_subagent?: string[] | undefined;
         max_bash_output_lines?: number | undefined;

package/dist/policy/profiles.js

@@ -25,6 +25,17 @@ const ContextProtectionProfileSchema = z
     max_bash_output_lines: z.number().int().positive().optional(),
 })
     .strict();
+/**
+ * G9: injection tier-escalation knobs. Profile-layer schema mirrors the policy
+ * loader's `InjectionPolicySchema` but leaves the flag fully optional so the
+ * profile-default lives at the policy-loader layer (ships `false` by default).
+ * Strict mode still rejects typos so a misspelled key fails loudly at init.
+ */
+const InjectionProfileSchema = z
+    .object({
+    suspicious_blocks_writes: z.boolean().optional(),
+})
+    .strict();
 /**
  * Profile is PolicySchema with every field optional. Strict mode still rejects
  * unknown keys so a typo in a profile YAML fails loudly at init time rather
@@ -39,6 +50,7 @@ export const ProfileSchema = z
     blocked_paths: z.array(z.string()).optional(),
     notification_channel: z.string().optional(),
     injection_detection: z.enum(['block', 'warn']).optional(),
+    injection: InjectionProfileSchema.optional(),
     context_protection: ContextProtectionProfileSchema.optional(),
 })
     .strict();

package/dist/policy/types.d.ts

@@ -31,6 +31,26 @@ export interface ReviewPolicy {
      * log. Default when unset is `true` (Codex required).
      */
     codex_required?: boolean;
+    /**
+     * Review-cache TTL used by `rea cache check` (BUG-009). Entries older
+     * than this window are treated as a miss, forcing re-review. Default
+     * when unset is 3600 seconds (1 hour) — matches the windows the
+     * push-review-gate hook already assumes. Express in seconds, positive
+     * integer.
+     */
+    cache_max_age_seconds?: number;
+    /**
+     * Authorization for `REA_SKIP_PUSH_REVIEW` / `REA_SKIP_CODEX_REVIEW` when
+     * the `CI` environment variable is set. The skip hatches are ambient and
+     * unauthenticated — a leaked env file or a malicious parent process can
+     * bypass the gate and record a forged actor (git config is mutable repo
+     * config). Refusing these hatches in CI contexts by default removes that
+     * bypass surface. Set `true` ONLY on build agents where the operator has
+     * an independent reason to trust the environment. Default `false`.
+     *
+     * Added in 0.5.0 as Codex F2 on the PR1 adversarial review.
+     */
+    allow_skip_in_ci?: boolean;
 }
 /**
  * User-supplied redaction pattern entry. Each pattern has a stable `name` used
@@ -77,6 +97,33 @@ export interface AuditRotationPolicy {
 export interface AuditPolicy {
     rotation?: AuditRotationPolicy;
 }
+/**
+ * G9 — injection tier escalation knobs. The classifier bucketed matches into
+ * `clean` / `suspicious` / `likely_injection`; this block governs what happens
+ * to the `suspicious` bucket (a single literal match at write/destructive tier,
+ * no base64 escalation). `likely_injection` is ALWAYS a deny regardless of
+ * these knobs.
+ *
+ * `suspicious_blocks_writes` —
+ *   `undefined` (omitted): middleware defaults based on `injection_detection`:
+ *     block mode defaults to `true` (0.2.x parity — single literal at
+ *     write/destructive tier still denies); warn mode defaults to `false`
+ *     (preserves 0.2.x warn-only semantics).
+ *   `false` (explicit opt-out): suspicious matches warn-only (log + audit
+ *     metadata, `status: allowed`), regardless of `injection_detection`.
+ *   `true` (pinned in `bst-internal*` and this repo's own policy): suspicious
+ *     matches at write/destructive tier deny with verdict `suspicious` in the
+ *     audit record.
+ *
+ * G9 follow-up (post-merge Codex finding #1): the pre-patch schema default
+ * of `false` silently loosened 0.2.x `injection_detection: block` behavior
+ * for any consumer who upgraded without adding the `injection:` block.
+ * Making this field optional and defaulting it at the middleware restores
+ * 0.2.x parity.
+ */
+export interface InjectionPolicy {
+    suspicious_blocks_writes?: boolean;
+}
 export interface Policy {
     version: string;
     profile: string;
@@ -89,6 +136,7 @@ export interface Policy {
     blocked_paths: string[];
     notification_channel: string;
     injection_detection?: 'block' | 'warn';
+    injection?: InjectionPolicy;
     context_protection?: ContextProtection;
     review?: ReviewPolicy;
     redact?: RedactPolicy;

package/dist/registry/fingerprint.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Registry server fingerprinting — G7 proxy-poisoning defense.
+ *
+ * ## Threat model
+ *
+ * The registry file (`.rea/registry.yaml`) is plain YAML on the operator's
+ * disk. An attacker who lands a malicious template via `rea init`, or who
+ * patches the file out-of-band (compromised dependency postinstall, CI-bot
+ * misconfig, editor plugin writing through stale buffers), can silently swap
+ * a downstream server's `command`, `args`, or `env` keys. The gateway would
+ * spawn the new child at next startup and proxy it without challenge.
+ *
+ * Fingerprinting defends the **catalog-tampering** vector: we hash the
+ * canonicalized server config on first sight (TOFU — trust on first use),
+ * persist it to `.rea/fingerprints.json`, and on every subsequent boot refuse
+ * to connect servers whose fingerprint has drifted without an explicit
+ * one-shot acknowledgement (`REA_ACCEPT_DRIFT=<name>`).
+ *
+ * ## Scope: path-only, not binary
+ *
+ * We fingerprint the **config path** (name, command, args, env KEY SET,
+ * env_passthrough, tier_overrides). We do NOT hash the binary contents at
+ * `config.command`. Three reasons:
+ *
+ *   1. Binary hashing turns TOFU into a slow-boot tax — cold spawns already
+ *      dominate first-run latency; adding N sha256-of-binary operations makes
+ *      this worse on every restart.
+ *   2. Legitimate MCP server upgrades (e.g. `@modelcontextprotocol/server-git`
+ *      patch version bump) would legitimately change the binary content and
+ *      would trip false-positive drift on every upgrade.
+ *   3. The G7 threat model is **registry tampering** (YAML rewrite), which the
+ *      canonicalized config hash covers cleanly. Host compromise — where an
+ *      attacker swaps the on-disk binary at `config.command` — is a different
+ *      G-number (supply-chain / host-integrity), not G7.
+ *
+ * ## Env values vs env keys
+ *
+ * We fingerprint the SORTED KEY SET of `config.env`, not the values. Values
+ * frequently contain secrets (`GITHUB_TOKEN: ghp_...`) that the operator may
+ * legitimately rotate; rotating a secret must not trip drift. Adding or
+ * removing a key IS semantic change (new permission scope, new passthrough
+ * surface) — that trips drift and is caught.
+ */
+import type { RegistryServer } from './types.js';
+/**
+ * Canonical representation of a server for fingerprinting. Field order is
+ * fixed so JSON.stringify output is deterministic; arrays/keys are sorted.
+ */
+interface CanonicalServer {
+    name: string;
+    command: string;
+    args: string[];
+    env_keys: string[];
+    env_passthrough: string[];
+    tier_overrides: Array<[string, string]>;
+}
+/**
+ * Compute a stable sha256 fingerprint of a registry server's config path.
+ * Pure function — same input produces the same output forever.
+ *
+ * Two callers with the same server entry in different registries must get
+ * the same fingerprint; two servers that differ in any material way (command,
+ * args, env KEY presence, passthrough surface, tier override for any tool)
+ * must get different fingerprints.
+ */
+export declare function fingerprintServer(server: RegistryServer): string;
+/**
+ * Test hook: expose the canonical form so tests can assert what is and is
+ * not included in the fingerprint input. Not part of the public API — no
+ * consumer should depend on this shape remaining stable.
+ */
+export declare function __canonicalizeForTests(server: RegistryServer): CanonicalServer;
+export {};

package/dist/registry/fingerprint.js

@@ -0,0 +1,81 @@
+/**
+ * Registry server fingerprinting — G7 proxy-poisoning defense.
+ *
+ * ## Threat model
+ *
+ * The registry file (`.rea/registry.yaml`) is plain YAML on the operator's
+ * disk. An attacker who lands a malicious template via `rea init`, or who
+ * patches the file out-of-band (compromised dependency postinstall, CI-bot
+ * misconfig, editor plugin writing through stale buffers), can silently swap
+ * a downstream server's `command`, `args`, or `env` keys. The gateway would
+ * spawn the new child at next startup and proxy it without challenge.
+ *
+ * Fingerprinting defends the **catalog-tampering** vector: we hash the
+ * canonicalized server config on first sight (TOFU — trust on first use),
+ * persist it to `.rea/fingerprints.json`, and on every subsequent boot refuse
+ * to connect servers whose fingerprint has drifted without an explicit
+ * one-shot acknowledgement (`REA_ACCEPT_DRIFT=<name>`).
+ *
+ * ## Scope: path-only, not binary
+ *
+ * We fingerprint the **config path** (name, command, args, env KEY SET,
+ * env_passthrough, tier_overrides). We do NOT hash the binary contents at
+ * `config.command`. Three reasons:
+ *
+ *   1. Binary hashing turns TOFU into a slow-boot tax — cold spawns already
+ *      dominate first-run latency; adding N sha256-of-binary operations makes
+ *      this worse on every restart.
+ *   2. Legitimate MCP server upgrades (e.g. `@modelcontextprotocol/server-git`
+ *      patch version bump) would legitimately change the binary content and
+ *      would trip false-positive drift on every upgrade.
+ *   3. The G7 threat model is **registry tampering** (YAML rewrite), which the
+ *      canonicalized config hash covers cleanly. Host compromise — where an
+ *      attacker swaps the on-disk binary at `config.command` — is a different
+ *      G-number (supply-chain / host-integrity), not G7.
+ *
+ * ## Env values vs env keys
+ *
+ * We fingerprint the SORTED KEY SET of `config.env`, not the values. Values
+ * frequently contain secrets (`GITHUB_TOKEN: ghp_...`) that the operator may
+ * legitimately rotate; rotating a secret must not trip drift. Adding or
+ * removing a key IS semantic change (new permission scope, new passthrough
+ * surface) — that trips drift and is caught.
+ */
+import { createHash } from 'node:crypto';
+function canonicalize(server) {
+    const envKeys = Object.keys(server.env).sort();
+    const passthrough = [...(server.env_passthrough ?? [])].sort();
+    const overrides = Object.entries(server.tier_overrides ?? {})
+        .map(([k, v]) => [k, String(v)])
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    return {
+        name: server.name,
+        command: server.command,
+        args: [...server.args],
+        env_keys: envKeys,
+        env_passthrough: passthrough,
+        tier_overrides: overrides,
+    };
+}
+/**
+ * Compute a stable sha256 fingerprint of a registry server's config path.
+ * Pure function — same input produces the same output forever.
+ *
+ * Two callers with the same server entry in different registries must get
+ * the same fingerprint; two servers that differ in any material way (command,
+ * args, env KEY presence, passthrough surface, tier override for any tool)
+ * must get different fingerprints.
+ */
+export function fingerprintServer(server) {
+    const canonical = canonicalize(server);
+    const json = JSON.stringify(canonical);
+    return createHash('sha256').update(json).digest('hex');
+}
+/**
+ * Test hook: expose the canonical form so tests can assert what is and is
+ * not included in the fingerprint input. Not part of the public API — no
+ * consumer should depend on this shape remaining stable.
+ */
+export function __canonicalizeForTests(server) {
+    return canonicalize(server);
+}

package/dist/registry/fingerprints-store.d.ts

@@ -0,0 +1,62 @@
+/**
+ * TOFU fingerprint store — persisted trust anchors for each downstream
+ * server declared in `.rea/registry.yaml`.
+ *
+ * Stored at `.rea/fingerprints.json`. Versioned schema (currently `"1"`)
+ * so we can migrate shape without a surprise parse failure on upgrade.
+ *
+ * ## Format
+ *
+ * ```json
+ * {
+ *   "version": "1",
+ *   "servers": {
+ *     "discord-ops": "a3f4...",
+ *     "obsidian":    "b1c2..."
+ *   }
+ * }
+ * ```
+ *
+ * ## Corruption policy
+ *
+ * A missing file is the **first-run** state. An unparseable or
+ * schema-invalid file is NOT silently ignored: the loader throws. The
+ * gateway treats that as a fail-closed signal — refuse to start rather than
+ * reset TOFU state, which would downgrade a real attack to a first-seen
+ * acceptance. The operator can delete the file deliberately to re-bootstrap.
+ *
+ * ## Concurrency
+ *
+ * Writes use an atomic `write → rename` pattern to avoid torn reads. The
+ * gateway is the only writer in normal operation (startup TOFU check),
+ * so we do not take a file lock — two concurrent `rea serve` processes
+ * in the same repo is not a supported state.
+ */
+import { z } from 'zod';
+export declare const FINGERPRINT_STORE_VERSION = "1";
+declare const FingerprintStoreSchema: z.ZodObject<{
+    version: z.ZodLiteral<"1">;
+    servers: z.ZodRecord<z.ZodString, z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    version: "1";
+    servers: Record<string, string>;
+}, {
+    version: "1";
+    servers: Record<string, string>;
+}>;
+export type FingerprintStore = z.infer<typeof FingerprintStoreSchema>;
+declare function storePathFor(baseDir: string): string;
+/**
+ * Load the fingerprint store. Returns an empty store if the file does not
+ * exist (first-run). Throws on unreadable or schema-invalid files — do NOT
+ * catch and treat as first-run, that would let an attacker who corrupts the
+ * file downgrade a drift event to first-seen acceptance.
+ */
+export declare function loadFingerprintStore(baseDir: string): Promise<FingerprintStore>;
+/**
+ * Persist the fingerprint store. Writes to a sibling `.new` file then
+ * renames into place so a crashed process never leaves a half-written store
+ * that would fail to parse on next boot.
+ */
+export declare function saveFingerprintStore(baseDir: string, store: FingerprintStore): Promise<void>;
+export { FingerprintStoreSchema, storePathFor as __fingerprintStorePathForTests };

package/dist/registry/fingerprints-store.js

@@ -0,0 +1,111 @@
+/**
+ * TOFU fingerprint store — persisted trust anchors for each downstream
+ * server declared in `.rea/registry.yaml`.
+ *
+ * Stored at `.rea/fingerprints.json`. Versioned schema (currently `"1"`)
+ * so we can migrate shape without a surprise parse failure on upgrade.
+ *
+ * ## Format
+ *
+ * ```json
+ * {
+ *   "version": "1",
+ *   "servers": {
+ *     "discord-ops": "a3f4...",
+ *     "obsidian":    "b1c2..."
+ *   }
+ * }
+ * ```
+ *
+ * ## Corruption policy
+ *
+ * A missing file is the **first-run** state. An unparseable or
+ * schema-invalid file is NOT silently ignored: the loader throws. The
+ * gateway treats that as a fail-closed signal — refuse to start rather than
+ * reset TOFU state, which would downgrade a real attack to a first-seen
+ * acceptance. The operator can delete the file deliberately to re-bootstrap.
+ *
+ * ## Concurrency
+ *
+ * Writes use an atomic `write → rename` pattern to avoid torn reads. The
+ * gateway is the only writer in normal operation (startup TOFU check),
+ * so we do not take a file lock — two concurrent `rea serve` processes
+ * in the same repo is not a supported state.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+const FINGERPRINTS_FILE = 'fingerprints.json';
+const REA_DIR = '.rea';
+export const FINGERPRINT_STORE_VERSION = '1';
+const FingerprintStoreSchema = z
+    .object({
+    version: z.literal(FINGERPRINT_STORE_VERSION),
+    servers: z.record(z.string().regex(/^[a-f0-9]{64}$/, 'fingerprint must be lowercase hex sha256')),
+})
+    .strict();
+function storePathFor(baseDir) {
+    return path.join(baseDir, REA_DIR, FINGERPRINTS_FILE);
+}
+/**
+ * Load the fingerprint store. Returns an empty store if the file does not
+ * exist (first-run). Throws on unreadable or schema-invalid files — do NOT
+ * catch and treat as first-run, that would let an attacker who corrupts the
+ * file downgrade a drift event to first-seen acceptance.
+ */
+export async function loadFingerprintStore(baseDir) {
+    const filePath = storePathFor(baseDir);
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return { version: FINGERPRINT_STORE_VERSION, servers: {} };
+        }
+        throw new Error(`failed to read fingerprint store at ${filePath}: ${err instanceof Error ? err.message : err}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`fingerprint store at ${filePath} is not valid JSON — delete the file to re-bootstrap TOFU if this is intentional: ${err instanceof Error ? err.message : err}`);
+    }
+    const result = FingerprintStoreSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`fingerprint store at ${filePath} failed schema validation: ${result.error.message}`);
+    }
+    return result.data;
+}
+/**
+ * Persist the fingerprint store. Writes to a sibling `.new` file then
+ * renames into place so a crashed process never leaves a half-written store
+ * that would fail to parse on next boot.
+ */
+export async function saveFingerprintStore(baseDir, store) {
+    const filePath = storePathFor(baseDir);
+    const tmpPath = `${filePath}.new`;
+    await fs.mkdir(path.join(baseDir, REA_DIR), { recursive: true });
+    // Validate before write — a malformed in-memory store should never be
+    // persisted. The parse is cheap and catches bugs in the classify layer.
+    FingerprintStoreSchema.parse(store);
+    const serialized = JSON.stringify(store, null, 2) + '\n';
+    await fs.writeFile(tmpPath, serialized, 'utf8');
+    try {
+        await fs.rename(tmpPath, filePath);
+    }
+    catch (err) {
+        // Best-effort cleanup of the orphaned .new file so a retry doesn't
+        // accumulate cruft. If the unlink itself fails, swallow — the original
+        // rename error is the one the caller needs to see.
+        try {
+            await fs.unlink(tmpPath);
+        }
+        catch {
+            /* ignore cleanup failure */
+        }
+        throw err;
+    }
+}
+export { FingerprintStoreSchema, storePathFor as __fingerprintStorePathForTests };

package/dist/registry/interpolate.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Environment-variable interpolation for the registry's explicit `env:` map.
+ *
+ * Supports a deliberately minimal syntax — ONLY `${VAR}` (curly-brace form)
+ * in env VALUES (keys are never interpolated). This keeps the surface area
+ * small enough to reason about:
+ *
+ *   - No bare `$VAR` form (ambiguous with shell semantics).
+ *   - No default syntax (`${VAR:-fallback}`) — 0.3.0 ships without it.
+ *   - No command substitution (`$(cmd)`) — never.
+ *   - No recursive expansion. If `${FOO}` resolves to a string that itself
+ *     contains `${BAR}`, the inner text is treated as a literal. This is
+ *     intentional to prevent a malicious env var contents from triggering
+ *     a second round of lookups.
+ *
+ * Var names follow POSIX identifier rules: `^[A-Za-z_][A-Za-z0-9_]*$`.
+ * Anything else inside `${...}` is a syntax error.
+ *
+ * Secret tagging: if either the env KEY OR any referenced `${VAR}` NAME
+ * matches the secret-name heuristic (TOKEN/KEY/SECRET/PASSWORD/CREDENTIAL),
+ * the resolved entry's key is added to `secretKeys`. Callers use this to
+ * gate logging / redaction decisions. The resolved VALUE never flows into
+ * audit records on its own — downstream.ts passes it straight to the child
+ * transport — but `secretKeys` is exported so a future telemetry path can
+ * make the right call without re-deriving the heuristic.
+ */
+/**
+ * Regex used to flag env keys and interpolated var names that look like
+ * secrets. Kept in sync with the same pattern in `registry/loader.ts`.
+ */
+export declare const SECRET_NAME_HEURISTIC: RegExp;
+export interface InterpolateResult {
+    /** Env map with every `${VAR}` resolved against `processEnv`. */
+    resolved: Record<string, string>;
+    /**
+     * Names of env vars referenced by the template but absent from
+     * `processEnv` (or present but not a string). Empty when every
+     * reference was satisfied. Deduplicated, in first-seen order.
+     */
+    missing: string[];
+    /**
+     * Env KEYS in `resolved` that should be treated as secret-bearing —
+     * either because the key name itself matches the heuristic, or
+     * because one of the `${VAR}` names referenced in its value did.
+     * Callers MUST NOT log the resolved value of these keys.
+     */
+    secretKeys: string[];
+}
+/**
+ * Interpolate `${VAR}` placeholders in every value of `rawEnv` against
+ * `processEnv`. Pure function — no I/O, no mutation of inputs.
+ *
+ * Throws on malformed syntax (unterminated brace, empty name, illegal
+ * identifier chars). Malformed templates are a LOAD-TIME problem, not a
+ * runtime one, so the throw bubbles up to the registry loader / server
+ * spawn path where it can be reported with file + key context.
+ */
+export declare function interpolateEnv(rawEnv: Record<string, string>, processEnv: NodeJS.ProcessEnv): InterpolateResult;