@bookedsolid/rea 0.2.1 → 0.4.0

package/dist/registry/interpolate.js

@@ -0,0 +1,121 @@
+/**
+ * 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 const SECRET_NAME_HEURISTIC = /(TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL)/i;
+/** POSIX identifier — matches legal env var names. */
+const VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Matches `${...}` with ANY inner content (including empty / illegal). The
+ * inner content is re-validated against VAR_NAME_RE so we can emit a clear
+ * error message per-occurrence.
+ *
+ * Note: the regex is non-greedy and bounded by `}`, so an unterminated
+ * `${foo` will NOT match here — callers detect unterminated braces by
+ * scanning for a literal `${` with no matching `}` after replacement.
+ */
+const PLACEHOLDER_RE = /\$\{([^}]*)\}/g;
+/**
+ * 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 function interpolateEnv(rawEnv, processEnv) {
+    const resolved = {};
+    const missingSet = new Set();
+    const missing = [];
+    const secretKeys = [];
+    for (const [key, template] of Object.entries(rawEnv)) {
+        validateNoUnterminatedBrace(key, template);
+        const referencedSecretName = { seen: false };
+        let anyMissing = false;
+        const replaced = template.replace(PLACEHOLDER_RE, (_match, inner) => {
+            if (inner.length === 0) {
+                throw new Error(`registry env value for "${key}" contains empty \${} placeholder — expected \${VAR}`);
+            }
+            if (!VAR_NAME_RE.test(inner)) {
+                throw new Error(`registry env value for "${key}" references invalid var name "${inner}" — ` +
+                    'expected POSIX identifier matching /^[A-Za-z_][A-Za-z0-9_]*$/');
+            }
+            if (SECRET_NAME_HEURISTIC.test(inner)) {
+                referencedSecretName.seen = true;
+            }
+            const v = processEnv[inner];
+            if (typeof v !== 'string') {
+                if (!missingSet.has(inner)) {
+                    missingSet.add(inner);
+                    missing.push(inner);
+                }
+                anyMissing = true;
+                // Return the original placeholder so tests can see the unresolved
+                // template if they inspect resolved[key]. Callers MUST consult
+                // `missing` and refuse to start the server — they should not ship
+                // this value to a child process.
+                return `\${${inner}}`;
+            }
+            return v;
+        });
+        // A key is secret-bearing when either (a) its name matches the heuristic
+        // or (b) any `${VAR}` it references does. This matches the redact-by-default
+        // contract documented in the PR body: the template is auditable, the
+        // runtime value is not.
+        if (SECRET_NAME_HEURISTIC.test(key) || referencedSecretName.seen) {
+            secretKeys.push(key);
+        }
+        // Record resolved value regardless of missing — downstream caller uses
+        // `missing` as the sole signal for "refuse to start". If the caller
+        // chooses to proceed, the unresolved placeholder is a loud canary.
+        void anyMissing;
+        resolved[key] = replaced;
+    }
+    return { resolved, missing, secretKeys };
+}
+/**
+ * Scan for a literal `${` that has no matching `}` after it. The main
+ * replace pass uses a regex that REQUIRES `}`, so unterminated opens
+ * would be silently kept as literals without this pre-check — which
+ * would ship a raw `${...` string to the child, nearly always a bug.
+ */
+function validateNoUnterminatedBrace(key, template) {
+    let i = 0;
+    while (i < template.length) {
+        const open = template.indexOf('${', i);
+        if (open === -1)
+            return;
+        const close = template.indexOf('}', open + 2);
+        if (close === -1) {
+            throw new Error(`registry env value for "${key}" contains unterminated \${ — add a closing } or escape the literal`);
+        }
+        i = close + 1;
+    }
+}

package/dist/registry/loader.d.ts

@@ -12,7 +12,7 @@ declare const RegistryServerSchema: z.ZodObject<{
     name: z.ZodString;
     command: z.ZodString;
     args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    env: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>, Record<string, string>, Record<string, string> | undefined>;
     env_passthrough: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     tier_overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNativeEnum<typeof Tier>>>;
     enabled: z.ZodDefault<z.ZodBoolean>;
@@ -39,7 +39,7 @@ declare const RegistrySchema: z.ZodObject<{
         name: z.ZodString;
         command: z.ZodString;
         args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-        env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        env: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>, Record<string, string>, Record<string, string> | undefined>;
         env_passthrough: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
         tier_overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNativeEnum<typeof Tier>>>;
         enabled: z.ZodDefault<z.ZodBoolean>;

package/dist/registry/loader.js

@@ -11,6 +11,7 @@ import path from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { z } from 'zod';
 import { Tier } from '../policy/types.js';
+import { interpolateEnv } from './interpolate.js';
 /**
  * Regex used to refuse passthrough of var names that look like secrets.
  * Explicit `env:` mapping is the escape hatch — if a user types the value into
@@ -25,7 +26,27 @@ const RegistryServerSchema = z
         .regex(/^[a-z0-9][a-z0-9-]*$/, 'server name must be lowercase-kebab and cannot start with a dash'),
     command: z.string().min(1),
     args: z.array(z.string()).default([]),
-    env: z.record(z.string()).default({}),
+    // Values may contain `${VAR}` placeholders (see `registry/interpolate.ts`)
+    // which resolve at server-spawn time against rea-serve's own process.env.
+    // We validate SYNTAX at load time by running a dry-run pass with an empty
+    // host env — interpolateEnv throws on malformed syntax but treats missing
+    // vars as runtime signal, not a load-time error. The runtime check lives
+    // in `downstream.ts` where it can mark the affected server unhealthy
+    // without taking down the gateway.
+    env: z
+        .record(z.string())
+        .default({})
+        .superRefine((raw, ctx) => {
+        try {
+            interpolateEnv(raw, {});
+        }
+        catch (err) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }),
     env_passthrough: z
         .array(z
         .string()

package/dist/registry/tofu-gate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * TOFU gate — the startup-time bridge between `classifyServers` and the
+ * gateway's downstream pool.
+ *
+ * Responsibilities:
+ *
+ *  1. Load the current fingerprint store (or treat missing as first-run).
+ *  2. Classify every server in the registry.
+ *  3. Emit the side effects a classification implies:
+ *       - `first-seen` → audit allowed, LOUD stderr block, log info.
+ *       - `unchanged` → silent.
+ *       - `drifted` (no bypass) → audit denied, stderr warn, log warn,
+ *         and the server is FILTERED OUT of the returned set.
+ *       - `drifted` (bypass via REA_ACCEPT_DRIFT) → log info, audit allowed
+ *         with `bypassed: true` in metadata; server remains in the set.
+ *  4. Persist the updated store.
+ *
+ * Returns the filtered `RegistryServer[]` the gateway should actually wire
+ * into its `DownstreamPool`. Drifted-without-bypass servers are DROPPED here
+ * so the pool never has a chance to spawn them — the gateway stays up,
+ * other servers remain available, the upstream client just sees a smaller
+ * tool catalog.
+ */
+import type { RegistryServer } from './types.js';
+import { type TofuClassification } from './tofu.js';
+import { type Logger } from '../gateway/log.js';
+export interface TofuGateResult {
+    accepted: RegistryServer[];
+    classifications: TofuClassification[];
+}
+/**
+ * Apply the TOFU gate and return the filtered server set for the pool.
+ *
+ * Audit, stderr, and structured-log side effects all fire here. The caller
+ * (gateway startup) does not need to repeat them.
+ *
+ * The optional `logger` is the G5 gateway logger threaded from `rea serve`.
+ * When omitted (tests, doctor callers without a serve session), a default
+ * logger is created so TOFU records always participate in structured output.
+ */
+export declare function applyTofuGate(baseDir: string, servers: RegistryServer[], logger?: Logger): Promise<TofuGateResult>;

package/dist/registry/tofu-gate.js

@@ -0,0 +1,189 @@
+/**
+ * TOFU gate — the startup-time bridge between `classifyServers` and the
+ * gateway's downstream pool.
+ *
+ * Responsibilities:
+ *
+ *  1. Load the current fingerprint store (or treat missing as first-run).
+ *  2. Classify every server in the registry.
+ *  3. Emit the side effects a classification implies:
+ *       - `first-seen` → audit allowed, LOUD stderr block, log info.
+ *       - `unchanged` → silent.
+ *       - `drifted` (no bypass) → audit denied, stderr warn, log warn,
+ *         and the server is FILTERED OUT of the returned set.
+ *       - `drifted` (bypass via REA_ACCEPT_DRIFT) → log info, audit allowed
+ *         with `bypassed: true` in metadata; server remains in the set.
+ *  4. Persist the updated store.
+ *
+ * Returns the filtered `RegistryServer[]` the gateway should actually wire
+ * into its `DownstreamPool`. Drifted-without-bypass servers are DROPPED here
+ * so the pool never has a chance to spawn them — the gateway stays up,
+ * other servers remain available, the upstream client just sees a smaller
+ * tool catalog.
+ */
+import { Tier, InvocationStatus } from '../policy/types.js';
+import { appendAuditRecord } from '../audit/append.js';
+import { loadFingerprintStore, saveFingerprintStore, } from './fingerprints-store.js';
+import { classifyServers, updateStore, } from './tofu.js';
+import { createLogger } from '../gateway/log.js';
+const TOFU_TOOL_NAME = 'rea.tofu';
+const TOFU_SERVER_NAME = 'rea';
+/** Inner box width (characters between the vertical borders). */
+const BOX_INNER_WIDTH = 64;
+/**
+ * Render a line inside the TOFU banner box. Truncates overlong content with
+ * an ellipsis so the right border stays aligned even if a server name or
+ * label is unusually long. Pure string formatting — no side effects.
+ */
+function boxLine(content) {
+    const padded = ` ${content}`;
+    const truncated = padded.length > BOX_INNER_WIDTH ? padded.slice(0, BOX_INNER_WIDTH - 1) + '…' : padded;
+    return `  ║${truncated.padEnd(BOX_INNER_WIDTH, ' ')}║`;
+}
+/**
+ * Apply the TOFU gate and return the filtered server set for the pool.
+ *
+ * Audit, stderr, and structured-log side effects all fire here. The caller
+ * (gateway startup) does not need to repeat them.
+ *
+ * The optional `logger` is the G5 gateway logger threaded from `rea serve`.
+ * When omitted (tests, doctor callers without a serve session), a default
+ * logger is created so TOFU records always participate in structured output.
+ */
+export async function applyTofuGate(baseDir, servers, logger) {
+    const log = logger ?? createLogger();
+    const store = await loadFingerprintStore(baseDir);
+    const acceptDrift = process.env.REA_ACCEPT_DRIFT;
+    const classifications = classifyServers(servers, store, acceptDrift !== undefined ? { acceptDrift } : {});
+    const byName = new Map(servers.map((s) => [s.name, s]));
+    const accepted = [];
+    for (const c of classifications) {
+        const server = byName.get(c.server);
+        if (server === undefined)
+            continue; // defensive — classifyServers preserves order
+        await emitSideEffects(baseDir, c, log);
+        if (c.verdict === 'drifted' && !c.bypassed)
+            continue;
+        accepted.push(server);
+    }
+    const nextStore = updateStore(store, classifications);
+    await saveFingerprintStore(baseDir, nextStore);
+    return { accepted, classifications };
+}
+async function emitSideEffects(baseDir, c, log) {
+    if (c.verdict === 'unchanged')
+        return;
+    if (c.verdict === 'first-seen') {
+        // LOUD stderr — deliberately eye-catching. An attacker landing a poisoned
+        // registry at first install is the exact case this surface defends.
+        process.stderr.write([
+            '',
+            `  ╔${'═'.repeat(BOX_INNER_WIDTH)}╗`,
+            boxLine(' rea TOFU: NEW DOWNSTREAM SERVER RECORDED'),
+            `  ╠${'═'.repeat(BOX_INNER_WIDTH)}╣`,
+            boxLine(` name:        ${c.server}`),
+            boxLine(` fingerprint: ${c.current.slice(0, 16)}…`),
+            boxLine(''),
+            boxLine(' If you did not add this server, STOP and inspect'),
+            boxLine(' .rea/registry.yaml before any tool call executes.'),
+            `  ╚${'═'.repeat(BOX_INNER_WIDTH)}╝`,
+            '',
+        ].join('\n'));
+        log.info({
+            event: 'registry.tofu.first_seen',
+            message: `TOFU: new downstream server "${c.server}" recorded on first start`,
+            server_name: c.server,
+            fingerprint: c.current,
+        });
+        await safeAudit(baseDir, log, {
+            status: InvocationStatus.Allowed,
+            metadata: {
+                event: 'tofu.first_seen',
+                server: c.server,
+                fingerprint: c.current,
+            },
+        });
+        return;
+    }
+    // verdict === 'drifted'
+    if (c.bypassed) {
+        // Intentionally quieter than the unbypassed block: the operator set
+        // REA_ACCEPT_DRIFT, so this is authorized rotation and does not need
+        // the blocking banner. A single stderr line + warn-level log + audit
+        // entry is the documented UI for accepted drift.
+        process.stderr.write(`[rea] TOFU: accepting drift for "${c.server}" (REA_ACCEPT_DRIFT set) — fingerprint rotated.\n`);
+        log.warn({
+            event: 'registry.tofu.drift_accepted',
+            message: `TOFU: accepted fingerprint drift for "${c.server}" (REA_ACCEPT_DRIFT bypass)`,
+            server_name: c.server,
+            stored: c.stored,
+            current: c.current,
+        });
+        await safeAudit(baseDir, log, {
+            status: InvocationStatus.Allowed,
+            metadata: {
+                event: 'tofu.drift_accepted',
+                server: c.server,
+                stored_fingerprint: c.stored,
+                current_fingerprint: c.current,
+                bypassed: true,
+            },
+        });
+        return;
+    }
+    process.stderr.write([
+        '',
+        `  ╔${'═'.repeat(BOX_INNER_WIDTH)}╗`,
+        boxLine(' rea TOFU: FINGERPRINT DRIFT — SERVER BLOCKED'),
+        `  ╠${'═'.repeat(BOX_INNER_WIDTH)}╣`,
+        boxLine(` name:    ${c.server}`),
+        boxLine(` stored:  ${(c.stored ?? '').slice(0, 16)}…`),
+        boxLine(` current: ${c.current.slice(0, 16)}…`),
+        boxLine(''),
+        boxLine(' The server will NOT connect. Other servers remain up.'),
+        boxLine(' To accept (once):  REA_ACCEPT_DRIFT=<name> rea serve'),
+        `  ╚${'═'.repeat(BOX_INNER_WIDTH)}╝`,
+        '',
+    ].join('\n'));
+    log.warn({
+        event: 'registry.tofu.drift_blocked',
+        message: `TOFU: server fingerprint changed for "${c.server}" — possible proxy poisoning, server blocked`,
+        server_name: c.server,
+        stored: c.stored,
+        current: c.current,
+    });
+    await safeAudit(baseDir, log, {
+        status: InvocationStatus.Denied,
+        error: `fingerprint drift for "${c.server}" — server blocked (set REA_ACCEPT_DRIFT to accept)`,
+        metadata: {
+            event: 'tofu.drift_blocked',
+            server: c.server,
+            stored_fingerprint: c.stored,
+            current_fingerprint: c.current,
+        },
+    });
+}
+/**
+ * Append a TOFU audit record. Errors in the audit path are logged but
+ * never propagated — an audit-log outage must not take down the gateway.
+ */
+async function safeAudit(baseDir, log, entry) {
+    try {
+        const input = {
+            tool_name: TOFU_TOOL_NAME,
+            server_name: TOFU_SERVER_NAME,
+            status: entry.status,
+            tier: Tier.Read,
+            metadata: entry.metadata,
+            ...(entry.error !== undefined ? { error: entry.error } : {}),
+        };
+        await appendAuditRecord(baseDir, input);
+    }
+    catch (err) {
+        log.error({
+            event: 'registry.tofu.audit_failed',
+            message: 'TOFU: audit append failed — gateway continues, record lost',
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}

package/dist/registry/tofu.d.ts

@@ -0,0 +1,111 @@
+/**
+ * TOFU classifier — the G7 gate between `.rea/registry.yaml` and the
+ * downstream pool.
+ *
+ * For each server declared in the registry, classify as:
+ *
+ *   - `first-seen` — no entry in `.rea/fingerprints.json`. Record the
+ *     fingerprint, surface a LOUD block to the operator, allow the server
+ *     to connect. This is the TOFU trust-on-first-use decision; the
+ *     loudness is deliberate so a silent poisoning at first install is
+ *     still visible in stderr / audit / logs.
+ *
+ *   - `unchanged` — fingerprint matches the stored value. Proceed normally.
+ *
+ *   - `drifted` — fingerprint differs from the stored value. Refuse to
+ *     connect the server unless `REA_ACCEPT_DRIFT` names it for a single
+ *     boot. The rest of the gateway stays up — other servers remain
+ *     available, the upstream client just sees a smaller catalog.
+ *
+ * The audit entry, log line, and stderr block are emitted by the caller
+ * (the gateway startup sequence). This module is pure classification plus
+ * store updates; keeping it side-effect-free makes it unit-testable
+ * without stubbing the filesystem or the audit chain.
+ */
+import type { RegistryServer } from './types.js';
+import type { FingerprintStore } from './fingerprints-store.js';
+export type TofuVerdict = 'first-seen' | 'unchanged' | 'drifted';
+export interface TofuClassification {
+    server: string;
+    verdict: TofuVerdict;
+    /** Current fingerprint (always present — we always compute it). */
+    current: string;
+    /** Stored fingerprint, when one existed. Absent for `first-seen`. */
+    stored?: string;
+    /** Whether `REA_ACCEPT_DRIFT` bypass was honored for this server. */
+    bypassed: boolean;
+}
+export interface ClassifyOptions {
+    /**
+     * Raw value of `REA_ACCEPT_DRIFT`. Accepts a single server name or a
+     * comma-separated list. Whitespace is trimmed. Empty or undefined means
+     * no bypass.
+     */
+    acceptDrift?: string;
+}
+/**
+ * Classify every server in `servers` against the loaded `store`. Pure:
+ * does not read or write the filesystem. Returns one classification per
+ * server in the same order.
+ *
+ * ## Rename-with-removal defense (scope: narrow)
+ *
+ * A name-only lookup is not enough when an attacker rewrites a
+ * previously trusted entry AND changes its `name` at the same time: the
+ * stored lookup would miss and the tampered entry would land as benign
+ * `first-seen`. To close THAT specific shape we compute a rename signal
+ * at boot time:
+ *
+ *   - `disappeared = stored_names - registry_names`
+ *   - `appeared    = registry_names - stored_names`
+ *
+ * If BOTH sets are non-empty in the same boot, at least one declared
+ * entry has been renamed-with-removal (stored entry vanished, a new name
+ * showed up). In that case every entry in `appeared` is promoted from
+ * `first-seen` to `drifted`: the operator MUST explicitly accept it via
+ * `REA_ACCEPT_DRIFT=<new-name>` before it connects.
+ *
+ * ### What this defense does NOT catch
+ *
+ * If the attacker leaves the old trusted entry in the registry (e.g.
+ * flipped `enabled: false`, or left untouched as a decoy) and ADDS a
+ * tampered entry under a new name, `disappeared` stays empty, the
+ * set-difference heuristic does not fire, and the new entry lands as
+ * `first-seen`. That is **not a bypass** of the TOFU contract — it is
+ * structurally identical to `operator added a new MCP server`, which
+ * TOFU intentionally allows with a LOUD stderr banner demanding the
+ * operator's attention. The first-seen banner is the enforcement
+ * mechanism for that shape; the rename-with-removal heuristic above is
+ * strictly additional coverage for the harder-to-notice shape where the
+ * old entry disappears at the same moment the new one arrives.
+ *
+ * Genuinely additive installs (new entry appended with no concurrent
+ * removal) also remain `first-seen` and get the usual LOUD banner.
+ *
+ * This is strictly additive over the name-based lookup — a name-matched
+ * drift (same name, changed config) still classifies as `drifted` via
+ * the primary path.
+ *
+ * The fingerprint itself already includes `server.name` (see
+ * `fingerprint.ts` canonicalization), so an attacker cannot make a
+ * renamed entry's fingerprint coincide with a stored one under a
+ * different name. That means a cross-name fingerprint match would never
+ * happen in practice — the set-difference heuristic above is what
+ * actually defends the rename-with-removal shape.
+ */
+export declare function classifyServers(servers: RegistryServer[], store: FingerprintStore, opts?: ClassifyOptions): TofuClassification[];
+/**
+ * Merge classifications into an updated store. Applies the TOFU rule:
+ *
+ *   - `first-seen`  → add the current fingerprint.
+ *   - `unchanged`   → keep the existing value (no-op).
+ *   - `drifted`     → if bypassed, overwrite with the current fingerprint
+ *                     (operator has authorized the update); otherwise keep
+ *                     the stored value (drift persists across restart until
+ *                     explicitly accepted).
+ *
+ * Does not prune entries for servers that were removed from the registry —
+ * that decision is the operator's, and silently dropping fingerprints
+ * would let an attacker rename-then-reinstall a server to reset TOFU state.
+ */
+export declare function updateStore(store: FingerprintStore, classifications: TofuClassification[]): FingerprintStore;