Merge pull request #43 from MaazAhmed47/codex/pre-hn-public-truth

fix: align public proof with enforced MCP behavior

Author: MaazAhmed47

.mcp.json

@@ -8,7 +8,7 @@
 
 **MCP runtime trust layer for AI agents.**
 
-Interlock detects material MCP tool drift after approval, including effective-permission expansion that static manifest comparison can miss, quarantines changed gateway-mediated calls before continued use, and emits hash-chained evidence.
+Interlock detects material MCP tool drift after approval, including effective-permission expansion that static manifest comparison can miss, quarantines the affected tool so that later gateway-mediated calls to that tool are held before upstream forwarding, and emits hash-chained evidence.
 
 Current source metadata is `0.2.0-alpha.1`. This identifies the source tree; it is not a published GitHub release. See [GitHub Releases](https://github.com/MaazAhmed47/Interlock/releases) for published artifacts.
 
@@ -36,7 +36,7 @@ docker compose run --rm demo-runner scenario-a
 docker compose run --rm demo-runner scenario-b
 ```
 
-This runs the real proof sequence: approved tool → material capability drift → quarantine before a changed gateway-mediated call continues → Security Receipt → hash-chain verification. `scenario-b` adds the behavioral case that static manifest comparison misses: the same tool and schema move from expected `403 denied` to observed `200 allowed`.
+This runs the real proof sequence: an approved `read_file` boundary undergoes a material capability change, Interlock quarantines that tool, the next gateway-mediated call to `read_file` is held before any upstream `tools/call` is forwarded, and the decision produces a Security Receipt that passes hash-chain verification. `scenario-b` adds the behavioral case that static manifest comparison misses: the same tool and schema move from expected `403 denied` to observed `200 allowed`.
 
 See the [offline demo instructions](demo/offline/README.md#quickstart) for the command reference, fixed ports, reset procedure, and exact proof limits.
 
@@ -103,7 +103,7 @@ Scope note: this is behavioral verification, not provider-wide OAuth introspecti
 
 Use Interlock when an AI agent can call MCP tools that touch real systems: files, internal documents, databases, Slack, GitHub, customer records, or deployment workflows — especially when those tools are vendor, community, forked, or separately operated surfaces your team does not fully control.
 
-Example: you approved a read-only MCP tool for internal documents. Later, the same tool name gains external export behavior or starts exposing sensitive data fields. Interlock detects the drift, blocks or quarantines the tool before execution, and records a Security Receipt for review.
+Example: you approved a read-only MCP tool for internal documents. Later, the same tool name gains external export behavior or starts exposing sensitive data fields. Interlock can detect that material surface drift during gateway re-discovery, quarantine that tool, hold subsequent gateway-mediated calls to it before forwarding, and record a Security Receipt for review. Unrelated approved tools keep working. Undeclared behavioral drift may require a controlled probe or an observed response first.
 
 ---
 
@@ -133,7 +133,7 @@ configuration is default-deny: the variable name must also appear in
 }
 ```
 
-Use a non-production workflow only. Baseline a safe read-only tool, then make or simulate one safe surface change and verify that Interlock detects the changed tool boundary before execution.
+Use a non-production workflow only. Baseline a safe read-only tool, then make or simulate one safe surface change and verify that Interlock detects the changed boundary at re-discovery and holds the subsequent gateway-mediated call to that tool before forwarding upstream.
 
 ---
 
@@ -163,7 +163,7 @@ Interlock is built around that runtime control gap for MCP agents:
 
 * baseline approved MCP tools
 * detect post-approval tool/schema drift
-* enforce quarantine before execution
+* enforce quarantine on the affected tool, holding subsequent gateway-mediated calls to it before upstream forwarding
 * produce audit evidence for runtime decisions
 
 Interlock is not affiliated with or endorsed by OWASP. The mapping above describes alignment with public agentic security guidance.
@@ -293,7 +293,7 @@ Beyond pattern matching, Interlock enforces business-logic constraints on tool a
 }
 ```
 
-Now an agent calling `refund_user(amount=99999)` is denied before execution — even if the tool exists and the agent has permission. Regex can't catch business-logic violations like this; deterministic bounds can.
+Now an agent calling `refund_user(amount=99999)` through `/mcp/call` is denied at the gateway before Interlock forwards the upstream `tools/call` — even if the tool exists and the agent has permission. Regex can't catch business-logic violations like this; deterministic bounds can.
 
 ---
 
@@ -516,7 +516,7 @@ Open an issue, start a discussion, or reach out from the links above.
 Interlock is strongest when agents are close to real systems: databases, Slack, files, ticketing, deployment tools, finance data, or internal APIs. A buyer should be able to prove value quickly by seeing:
 
 - a clean MCP tool baseline recorded at discovery
-- a risky tool schema or capability drift quarantined before execution
+- a risky tool schema or capability drift detected at re-discovery, followed by a gateway-mediated call to that tool held before upstream forwarding
 - role-based policy blocking a dangerous call from the wrong agent
 - response scanning catching prompt injection, secrets, PII, or oversized output
 - audit evidence for every allow, deny, monitor, and quarantine decision
@@ -578,7 +578,7 @@ What to verify before production:
 
 ## What Interlock is
 
-Interlock detects material MCP tool drift after approval, including effective-permission expansion that static manifest comparison can miss, quarantines changed gateway-mediated calls before continued use, and emits hash-chained evidence.
+Interlock detects material MCP tool drift after approval, including effective-permission expansion that static manifest comparison can miss, quarantines the affected tool so that later gateway-mediated calls to that tool are held before upstream forwarding, and emits hash-chained evidence.
 
 It is built for the agent path, not just prompt filtering. The main security surface is `POST /mcp/call`, where Interlock checks server trust, tool whitelist rules, tool metadata, schema drift, provenance, RBAC, tool-call arguments, and MCP responses before returning anything to the agent.
 
@@ -725,7 +725,7 @@ Readback effect evidence schema: [`readback-effect-drift-record.v1.json`](interl
 
 `core/chain_drift.py` adds pre-execution analysis for planned MCP tool chains. This catches risks that no single tool call reveals alone: sensitive read -> external send, secret read -> shell execution, Terraform plan -> apply/destroy, or preview -> deploy/charge later in the same workflow. The analyzer does not call providers or execute tools. It hashes every step's arguments, builds an evidence-safe chain profile, and logs a chain-drift Security Receipt when the planned sequence crosses a material boundary.
 
-Critical chain findings are denied before execution with types such as `chain_sensitive_read_to_external_effect`, `chain_secret_to_execution`, `chain_preview_to_deploy`, `chain_preview_to_destructive`, and `chain_preview_to_money_movement`. Read-only chains remain allowed. This is a prevention point for orchestrators that can submit a planned sequence before running it; it is not a claim that Interlock can infer every future agent step without seeing the plan.
+Critical chain findings are denied before the orchestrator forwards provider calls when it submits the planned sequence to Interlock, with types such as `chain_sensitive_read_to_external_effect`, `chain_secret_to_execution`, `chain_preview_to_deploy`, `chain_preview_to_destructive`, and `chain_preview_to_money_movement`. Read-only chains remain allowed. This is a prevention point for orchestrators that expose a plan before running it; it is not a claim that Interlock can infer every future agent step without seeing the plan.
 
 Chain drift evidence schema: [`chain-drift-record.v1.json`](interlock-web/public/schemas/chain-drift-record.v1.json).
 

README.md

@@ -1,15 +1,20 @@
-# Interlock v0.1.0 — First Pilot-Ready Release
+# Interlock v0.1.0 — First Tagged Release
 
-First tagged release of Interlock for serious design-partner evaluation.
+Historical notes for the first published tag. The current source metadata and
+compatibility boundary are documented in `README.md`; this file does not
+describe the current tree.
 
-Interlock is a self-hosted runtime security gateway for AI agents and MCP servers. It sits between agents and tools, scans prompts and responses, enforces tool policy, detects MCP drift, and records audit evidence for allow, deny, monitor, and quarantine decisions.
+Interlock is an MCP runtime trust layer for AI agents. In this tag it sat between
+agents and tools, scanned prompts and responses, enforced tool policy, detected
+MCP drift, and recorded audit evidence for allow, deny, monitor, and quarantine
+decisions.
 
 ## What's included
 
 ### Runtime Security Controls
 
 * OpenAI-compatible `/v1/chat/completions` gateway with prompt scanning before provider forwarding
-* MCP tool-call proxy with policy enforcement before execution
+* MCP tool-call proxy with policy enforcement at the gateway before upstream forwarding
 * Response scanning for prompt injection, PII, secrets, and oversized outputs
 * LLM judge path with configurable fail modes
 

RELEASE_NOTES.md

@@ -9,8 +9,8 @@ they are actually done.
 
 ## What's proven today
 
-These paths are implemented, covered by the test suite (500+ tests run as a
-whole directory in CI), and reproducible end-to-end in the offline demo:
+These paths are implemented, covered by the full Python suite in CI, and the
+scoped default surface-drift path is reproducible end-to-end in the offline demo:
 
 - **Capability drift detection.** A registered MCP tool's surface
   (description, input schema, annotations, derived effect metadata) is
@@ -21,8 +21,9 @@ whole directory in CI), and reproducible end-to-end in the offline demo:
   canary probes record what a tool's backing API actually permits. When a
   previously denied action starts succeeding (403 → 200) with the same
   identity and tool surface, the tool is quarantined with receipt evidence.
-- **Quarantine before execution.** Calls to a quarantined or drifted tool
-  are blocked at the gateway before the upstream call is made, and the
+- **Gateway hold after detected material drift.** Subsequent calls to a
+  quarantined or materially drifted tool are blocked at the gateway before an
+  upstream `tools/call` is forwarded, and the
   denial is recorded with binding fields (call id, argument hash, surface
   hashes).
 - **Hash-chained Security Receipts.** Every allow/deny/quarantine decision
@@ -46,8 +47,8 @@ than find them in a pilot.
 - **Effect drift is detected post-execution for the first call.** Outcome
   drift (a "dry-run" tool that suddenly applies changes) is judged from the
   upstream response, so the first drifting call has already executed by the
-  time it is caught. Subsequent calls are blocked by the resulting
-  quarantine. Only surface drift and quarantine state block pre-execution.
+  time it is caught. Subsequent calls to that tool are blocked by the
+  resulting quarantine. Only surface drift and quarantine state block pre-execution.
 - **The audit chain is tamper-evident, not externally anchored.** The hash
   chain uses unkeyed SHA-256 and lives in the same database as the data it
   protects. It detects casual tampering; it does not resist an attacker
@@ -60,11 +61,12 @@ than find them in a pilot.
   `xfail` tests in `tests/test_drift_adversarial.py` (e.g. exfiltration
   verbs outside the heuristic keyword set, indirect auth-scope widening via
   an innocuous-looking parameter).
-- **Not yet protocol-complete against the official MCP SDK.** The gateway
-  speaks the JSON-RPC tool-call subset it needs and is tested against mocks
-  and mock servers, not certified against the official MCP SDK's transports
-  and session semantics (Streamable HTTP, stdio, session lifecycle,
-  notifications).
+- **Tested, pinned official-SDK interoperability; not full MCP conformance.**
+  Official Python `mcp==2.0.0` and TypeScript client `2.0.0` probes cover the
+  scoped stateless `2026-07-28` gateway path, and an official TypeScript server
+  `2.0.0` probe covers pinned JSON/SSE upstream calls. These pins do not prove
+  other SDK versions, stdio, subscriptions, sessionful transports, or full MCP
+  conformance; see `docs/mcp-2026-compatibility.md`.
 - **Single-tenant assumptions.** Per-key data separation exists, but there
   is no hard tenant isolation story (separate schemas/databases,
   per-tenant encryption) for hosting mutually distrusting customers.
@@ -76,10 +78,10 @@ than find them in a pilot.
 
 In rough priority order; each item closes a limitation above.
 
-- **Official MCP SDK adoption and transport completeness.** Build the
-  gateway's MCP surface on the official SDK; support Streamable HTTP and
-  stdio transports and correct session lifecycle handling, verified against
-  SDK-based reference servers.
+- **Broader transport and session interoperability.** Preserve the pinned
+  official-SDK probes while adding explicitly scoped coverage for stdio,
+  subscriptions, and session lifecycle behavior. This remains compatibility
+  work, not a promise of full MCP conformance.
 - **Signed and externally anchored receipts.** Key-based signatures over
   receipt content and periodic anchoring of the chain head outside the
   primary database, so verification does not depend on trusting the

ROADMAP.md

@@ -40,7 +40,8 @@ For enterprise pilots:
 
 - Use Postgres through `DATABASE_URL`; do not rely on local SQLite for multi-instance deployments.
 - Use Redis through `REDIS_URL` before running multiple workers or pods.
-- Put the admin surface behind SSO, VPN, identity-aware proxy, or a private network until native OIDC/SAML is implemented.
+- OIDC admin authentication is implemented for issuer/audience/JWKS-validated JWTs and dashboard Authorization Code + PKCE. Configure and test it for the selected IdP, or keep the admin surface behind a VPN, identity-aware proxy, or private network.
+- SAML is not implemented. A SAML-only deployment needs an identity-aware proxy or another external bridge; do not describe Interlock as having native SAML support.
 - Configure retention with `/admin/retention`.
 - Connect logs, metrics, and audit events to the buyer's monitoring/SIEM.
 - Test backup restore before routing production agent traffic.

SECURITY.md

@@ -16,16 +16,22 @@ caller-selected roles in `/mcp/call` request bodies.
 This happens automatically during gateway startup, before the one-shot seeder
 runs. A first-time user does not mint a key or grant scopes manually.
 
-What it proves (and nothing more): the two **live-proven** drift classes.
-
-1. **Capability / surface drift** (default path): a tool a team approved as
-   read-only changes under the same name into an external-export/PII tool.
-   Interlock detects the drift at re-discovery, quarantines the tool **before
-   any call executes**, and issues a tamper-evident Security Receipt.
-2. **Behavioral / effective-permission drift** (advanced path): same tool,
+The default evaluator proves one drift class. A separate maintainer command
+proves the advanced behavioral class; the two paths are not one combined claim.
+
+1. **Capability / surface drift (default evaluator proof):** `read_file`, a tool a
+   team approved as read-only, changes under the same name into an
+   external-export/PII tool. Interlock detects the drift at re-discovery and
+   quarantines that one tool. A subsequent gateway-mediated call **to
+   `read_file`** is held before Interlock forwards an upstream `tools/call`, and
+   Interlock issues a tamper-evident Security Receipt. The unchanged
+   `list_documents` control tool keeps working — quarantine is per tool, not a
+   server-wide pause.
+2. **Behavioral / effective-permission drift (separate advanced proof):** same tool,
    same schema — a call the upstream denied (403) later becomes allowed
-   (200). An operator probe catches the effective-permission expansion and
-   quarantines the tool.
+   (200). The controlled probe is forwarded so Interlock can observe that
+   response and quarantine that tool. A later gateway-mediated call **to that
+   same tool** is not forwarded while that quarantine remains in force.
 
 ## Quickstart
 
@@ -63,6 +69,10 @@ Dashboard: <http://localhost:8080/dashboard> → Settings → API URL
 The demo binds fixed localhost ports `8001`, `8080`, and `9100`; stop or
 reconfigure anything already using them.
 
+Compose generates project-scoped container names (for example,
+`<project>-gateway-1`); use `docker compose ps` to inspect the current project
+instead of depending on fixed global container names.
+
 In **Audit Log → Runtime Decisions**, every event has a **Receipt** button
 (the tamper-evident record) and a **Verify** button (the four-claim evidence
 view with live verification and a replay check).

demo/offline/README.md

@@ -26,7 +26,6 @@ services:
     image: interlock:demo
     build:
       context: ../..
-    container_name: interlock-demo-gateway
     restart: unless-stopped
     environment:
       # Local demo posture: non-production, no external judge required.
@@ -60,7 +59,6 @@ services:
     image: interlock-demo-mock:local
     build:
       context: ./mock_server
-    container_name: interlock-demo-mock
     restart: unless-stopped
     networks:
       - demo-net
@@ -72,7 +70,6 @@ services:
       args:
         # Baked into the SPA — this is the gateway URL as seen by the BROWSER.
         VITE_INTERLOCK_API_URL: http://localhost:8001
-    container_name: interlock-demo-dashboard
     restart: unless-stopped
     networks:
       - demo-net
@@ -82,7 +79,6 @@ services:
   # three documented loopback ports.
   host-proxy:
     image: nginx:alpine
-    container_name: interlock-demo-host-proxy
     restart: unless-stopped
     ports:
       - "127.0.0.1:8001:8001"
@@ -111,7 +107,6 @@ services:
   # One-shot: registers, verifies, and approves the demo baseline on `up`.
   seeder:
     image: python:3.12-slim
-    container_name: interlock-demo-seeder
     volumes:
       - .:/demo:ro
     environment:

demo/offline/docker-compose.yml

@@ -112,7 +112,9 @@ def call_counts() -> dict:
 }
 
 # Same tool NAME, broader surface: external export + PII. Interlock's drift
-# classifier rates this critical and quarantines it before any call runs.
+# classifier rates this critical at re-discovery and quarantines this one tool,
+# so the next gateway-mediated call to read_file is held before upstream
+# forwarding. Other approved tools on the server are unaffected.
 READ_FILE_MUTATED = {
     "name": "read_file",
     "description": (