@bookedsolid/rea 0.6.1 → 0.7.0

package/dist/gateway/server.js

@@ -35,7 +35,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { DownstreamPool, splitPrefixed } from './downstream-pool.js';
-import { META_HEALTH_TOOL_NAME, META_SERVER_NAME, META_TOOL_NAME, buildHealthSnapshot, metaHealthToolDescriptor, } from './meta/health.js';
+import { boundedDiagnosticString, META_HEALTH_TOOL_NAME, META_SERVER_NAME, META_TOOL_NAME, buildHealthSnapshot, metaHealthToolDescriptor, sanitizeHealthSnapshot, } from './meta/health.js';
 import { appendAuditRecord } from '../audit/append.js';
 import { getPkgVersion } from '../cli/utils.js';
 import { createAuditMiddleware } from './middleware/audit.js';
@@ -127,6 +127,11 @@ export function createGateway(opts) {
     const pool = new DownstreamPool(registry, logger);
     const gatewayVersion = getPkgVersion();
     const startedAtMs = Date.now();
+    // BUG-011 (0.6.2) — process-lifetime counter of failed audit appends from
+    // the `__rea__health` short-circuit. Exposed on the health snapshot as
+    // `summary.audit_fail_count` so operators can detect the silent-audit-gap
+    // condition without parsing stderr.
+    let healthAuditFailCount = 0;
     const server = new Server({ name: 'rea', version: gatewayVersion }, { capabilities: { tools: {} } });
     // Build the circuit breaker with observability hooks wired in — state
     // transitions log a structured record AND update the Prometheus gauge.
@@ -161,7 +166,13 @@ export function createGateway(opts) {
         try {
             const contents = await fs.readFile(path.join(baseDir, '.rea', 'HALT'), 'utf8');
             const trimmed = contents.trim();
-            return { halt: true, reason: trimmed.length > 0 ? trimmed : null };
+            // Hard-cap the raw read at the diagnostic string budget before it
+            // enters the snapshot. An oversize HALT file (operator accident or
+            // local attacker) must not cause an O(size) allocation on every
+            // `__rea__health` call. `sanitizeHealthSnapshot` also truncates,
+            // but capping at ingestion keeps the snapshot itself bounded.
+            const bounded = boundedDiagnosticString(trimmed);
+            return { halt: true, reason: bounded.length > 0 ? bounded : null };
         }
         catch {
             return { halt: false, reason: null };
@@ -220,14 +231,23 @@ export function createGateway(opts) {
         if (prefixed === META_HEALTH_TOOL_NAME) {
             const startMs = Date.now();
             const haltState = await readHalt();
-            const snapshot = buildHealthSnapshot({
+            // Internal snapshot carries the raw diagnostic strings — used by the
+            // audit record below so operators have the full text in the log even
+            // when the MCP response has them stripped/redacted.
+            const internalSnapshot = buildHealthSnapshot({
                 gatewayVersion,
                 startedAtMs,
                 policy,
                 downstreams: pool.healthSnapshot(),
                 halt: haltState.halt,
                 haltReason: haltState.reason,
+                auditFailCount: healthAuditFailCount,
             });
+            // BUG-011 (0.6.2) — sanitize BEFORE serializing to the wire. Strips
+            // `halt_reason` + per-downstream `last_error` by default; when
+            // `gateway.health.expose_diagnostics: true` applies redactSecrets +
+            // injection-scan and replaces any non-clean string with the sentinel.
+            const wireSnapshot = sanitizeHealthSnapshot(internalSnapshot, policy);
             // Best-effort audit append. Failures here must never prevent the
             // caller from getting the health response — that would defeat the
             // whole point of a "works when everything else is broken" tool.
@@ -241,24 +261,45 @@ export function createGateway(opts) {
                     session_id: currentSessionId(),
                     duration_ms: Date.now() - startMs,
                     metadata: {
-                        halt: snapshot.gateway.halt,
-                        downstreams_registered: snapshot.summary.registered,
-                        downstreams_healthy: snapshot.summary.healthy,
+                        halt: internalSnapshot.gateway.halt,
+                        // BUG-011 (0.6.2) — N-3: the audit log is the authoritative
+                        // trusted-operator sink for full diagnostic text. Strings are
+                        // already bounded at ingestion (halt-file read + downstream
+                        // lastError getter) via `boundedDiagnosticString`, and the
+                        // audit file is on local disk with hash-chained append-only
+                        // semantics — not LLM-reachable. Log the pre-sanitize strings
+                        // here so the `rea doctor` / audit-tail path preserves the
+                        // text the MCP wire strips under the default policy.
+                        halt_reason: internalSnapshot.gateway.halt_reason,
+                        downstreams_registered: internalSnapshot.summary.registered,
+                        downstreams_healthy: internalSnapshot.summary.healthy,
+                        downstream_errors: internalSnapshot.downstreams
+                            .filter((d) => d.last_error !== null)
+                            .map((d) => ({ name: d.name, last_error: d.last_error })),
                     },
                 });
             }
             catch (err) {
-                logger.warn({
+                // BUG-011 (0.6.2) — elevated from `warn` to `error`. A dropped
+                // meta.health audit entry is an observability gap: the response
+                // still goes out but the record of it is missing, which defeats
+                // the forensic value of the hash chain for that call. Also bump a
+                // process-lifetime counter surfaced on the next snapshot's
+                // `summary.audit_fail_count` so operators can detect the condition
+                // without parsing stderr.
+                healthAuditFailCount += 1;
+                logger.error({
                     event: 'meta.health.audit_failed',
                     message: 'failed to append audit record for __rea__health; serving response anyway',
                     error: err instanceof Error ? err.message : String(err),
+                    audit_fail_count: healthAuditFailCount,
                 });
             }
             return {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify(snapshot, null, 2),
+                        text: JSON.stringify(wireSnapshot, null, 2),
                     },
                 ],
             };

package/dist/policy/loader.d.ts

@@ -95,6 +95,23 @@ declare const PolicySchema: z.ZodObject<{
             max_age_days?: number | undefined;
         } | undefined;
     }>>;
+    gateway: z.ZodOptional<z.ZodObject<{
+        health: z.ZodOptional<z.ZodObject<{
+            expose_diagnostics: z.ZodOptional<z.ZodBoolean>;
+        }, "strict", z.ZodTypeAny, {
+            expose_diagnostics?: boolean | undefined;
+        }, {
+            expose_diagnostics?: boolean | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        health?: {
+            expose_diagnostics?: boolean | undefined;
+        } | undefined;
+    }, {
+        health?: {
+            expose_diagnostics?: boolean | undefined;
+        } | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     version: string;
     profile: string;
@@ -133,6 +150,11 @@ declare const PolicySchema: z.ZodObject<{
             max_age_days?: number | undefined;
         } | undefined;
     } | undefined;
+    gateway?: {
+        health?: {
+            expose_diagnostics?: boolean | undefined;
+        } | undefined;
+    } | undefined;
 }, {
     version: string;
     profile: string;
@@ -171,6 +193,11 @@ declare const PolicySchema: z.ZodObject<{
             max_age_days?: number | undefined;
         } | undefined;
     } | undefined;
+    gateway?: {
+        health?: {
+            expose_diagnostics?: boolean | undefined;
+        } | undefined;
+    } | undefined;
 }>;
 /**
  * Async policy loader with TTL cache and mtime-based invalidation.

package/dist/policy/loader.js

@@ -93,6 +93,20 @@ const InjectionPolicySchema = z
     suspicious_blocks_writes: z.boolean().optional(),
 })
     .strict();
+/**
+ * BUG-011 (0.6.2) — gateway-level policy. Currently only the `health`
+ * sub-block is defined; kept strict so typos (`gateway.heath`) fail loudly.
+ */
+const GatewayHealthPolicySchema = z
+    .object({
+    expose_diagnostics: z.boolean().optional(),
+})
+    .strict();
+const GatewayPolicySchema = z
+    .object({
+    health: GatewayHealthPolicySchema.optional(),
+})
+    .strict();
 const PolicySchema = z
     .object({
     version: z.string(),
@@ -111,6 +125,7 @@ const PolicySchema = z
     review: ReviewPolicySchema.optional(),
     redact: RedactPolicySchema.optional(),
     audit: AuditPolicySchema.optional(),
+    gateway: GatewayPolicySchema.optional(),
 })
     .strict();
 const DEFAULT_CACHE_TTL_MS = 30_000;

package/dist/policy/types.d.ts

@@ -124,6 +124,33 @@ export interface AuditPolicy {
 export interface InjectionPolicy {
     suspicious_blocks_writes?: boolean;
 }
+/**
+ * BUG-011 (0.6.2) — gateway-level policy knobs.
+ *
+ * `health.expose_diagnostics` governs whether `__rea__health` emits
+ * `halt_reason` and per-downstream `last_error` strings in its MCP response
+ * (vs. dropping them to `null`). The short-circuit responds BEFORE the
+ * middleware chain — so it bypasses `redact` and `injection` middleware by
+ * design (the tool must stay callable under HALT). That means downstream
+ * error strings, which are populated verbatim from `err.message`, can carry
+ * secrets or injection payloads all the way to the caller unless we
+ * sanitize in the short-circuit path itself.
+ *
+ * Default `false` (fields emitted as `null`). The Helix team's explicit
+ * preference was "strip, don't redact" — a smaller trust ask than trusting
+ * our secret/injection pattern coverage. Operators who accept that trade-off
+ * (e.g. single-tenant dev boxes) can flip `expose_diagnostics: true`, at
+ * which point the short-circuit applies the same `redactSecrets` +
+ * `classifyInjection` pass the middleware chain would. The full untouched
+ * values always flow into the audit log regardless — diagnostics remain
+ * available via `rea doctor`, just not over the MCP wire.
+ */
+export interface GatewayHealthPolicy {
+    expose_diagnostics?: boolean;
+}
+export interface GatewayPolicy {
+    health?: GatewayHealthPolicy;
+}
 export interface Policy {
     version: string;
     profile: string;
@@ -141,4 +168,5 @@ export interface Policy {
     review?: ReviewPolicy;
     redact?: RedactPolicy;
     audit?: AuditPolicy;
+    gateway?: GatewayPolicy;
 }