A-2 — trust envelope synthesizer formalized: mtls_fingerprint, call counters, boot wiring

2026-05-09

securitytrust-envelopegateway

LOCKSTEP TRACEABILITY MATRIX --- api_endpoints: ["none — internal synthesis, no new routes"] sdk_methods_updated: ["none"] mcp_tools_updated: ["none"] ---

What We Built

Three concrete gaps between A-1 (schema + signing infra) and a production-useful audit-only envelope.

Gap 1 — _mtlsFingerprint never set: synth.ts reads c.get("_mtlsFingerprint") to populate br_trust.mtls_fingerprint, but mtls-auth.ts never called c.set("_mtlsFingerprint", ...). Every mTLS-authenticated request produced an envelope with mtls_fingerprint: null. Fixed: added c.set("_mtlsFingerprint", fingerprint ?? null) immediately after cert validation passes and the principal is built.

Gap 2 — Call counters hardcoded to 0: br_trust.reputation.{successful_calls,failed_calls} were always 0 because synth.ts had no mechanism to query historical usage. Added getCallCounts?: (tenantId, agentId) => Promise<{successful, failed}> to SynthesizeEnvelopeDeps. In production (wired in boot-api.ts), this queries usage_events GROUP BY status for the agent. Fails-open to {0, 0} if DB is unavailable or the dep is unwired (e.g. local dev).

Gap 3 — Envelope synthesis mode was never activated in production: boot-api.ts called createApiApp() without envelopeSynthMode, envelopeKeys, or envelopeSynthDeps. The gateway always ran with mode="off" regardless of the gateway.envelope.synth.mode config key. Fixed: boot-api.ts now reads cfgAtStart.gateway?.envelope?.synth?.mode and, when non-off, loads the Ed25519 signing key from Secrets Manager (at ${AWS_SECRETS_PREFIX}/envelope-signing-key) and wires reputationEngine + getCallCounts as synth deps. Key load failure is non-fatal at boot — mode falls back to "off" so the gateway boots rather than crashing on a missing SM secret.

Config type gap: GatewayConfig in types.gateway.ts was missing the envelope field even though the Zod schema declared it. Added the field so cfgAtStart.gateway?.envelope?.synth?.mode type-checks without casting.

Lockstep Checklist

[x] TypeScript SDK: no change
[x] Python SDK: no change
[x] MCP tools: no change
[x] OpenAPI: no change
[x] Config type: GatewayConfig.envelope added to types.gateway.ts
[x] Ship log: this entry

How to activate in production

Set gateway.envelope.synth.mode = "audit-only" in the gateway config (or via the config DB). The ECS task reads this at boot, loads the Ed25519 key from Secrets Manager, and begins synthesizing + signing a trust envelope on every /v1/* request. The envelope is attached to the context but not yet consumed by routing/budget/guardrails — that's A-3/A-4/A-5.