From 064d37aa35fa419b7dac274745353f6490665454 Mon Sep 17 00:00:00 2001
From: John Morrissey <544926+tachyon-beep@users.noreply.github.com>
Date: Fri, 22 May 2026 19:54:47 +1000
Subject: [PATCH] docs(v1.0): refresh internal design docs against ADR-034
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ADR-034 retroactively made non-loopback HTTP binds REQUIRE authentication
(HMAC identity or legacy bearer). The internal design docs still
described the pre-ADR-034 trust model. Refresh:

- requirements.md NFR-SEC-03: rewrite the statement and verification
  clause for the authenticated-non-loopback rule. Verification now cites
  the five serve.rs tests that enforce it. See line adds ADR-034.
- requirements.md REQ-HTTP-03: same scope as NFR-SEC-03; the See line
  adds ADR-034 and the verification points at the same test surface.
- CLAUDE.md HMAC paragraph: HMAC is the preferred non-loopback
  mechanism in v1.0 per ADR-034, not "post-1.0 hardening." Replay
  protection (timestamp + nonce window) remains the only ADR-034
  forward-work item.
- loom.md: §5 "v0.1 asterisks" → "v1.0 asterisks"; retirement wording
  retargeted to release:v1.1.

Closes gap-register items DOC-03, DOC-04, DOC-05 (folded into the
REQ-HTTP-03 rewrite), DOC-06, DOC-07.
---
 CLAUDE.md                        |  7 +++-
 docs/clarion/1.0/requirements.md | 61 +++++++++++++++++++++-----------
 docs/suite/loom.md               |  6 ++--
 3 files changed, 50 insertions(+), 24 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1fb4ffe1..c872e760 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -141,7 +141,12 @@ Open issues for the v1.0 known limitations and any post-release follow-ups live
 
 - **WP9-B (Filigree finding emission)** — deferred from 1.0 per the [Sprint 2 scope amendment](docs/implementation/sprint-2/scope-amendment-2026-05.md#4-v01-planmd-resequencing).
 - **HTTP file language manifest registry** — narrow core-extension fallback at 1.0; persistent registry is a post-1.0 task.
-- **HMAC inbound auth (C-4)** — bearer is the 1.0 wire surface; HMAC is forward-compatible and tracked for post-1.0 hardening.
+- **HMAC inbound auth (C-4)** — HMAC (`X-Loom-Component: clarion:<hmac>`) is the
+  preferred non-loopback authentication mechanism in v1.0 per ADR-034,
+  configured via `serve.http.identity_token_env`. The legacy bearer-token path
+  (`serve.http.token_env`) remains supported for compatibility. Replay
+  protection (timestamp + nonce window) is ADR-034 forward-work tracked for
+  post-1.0 hardening.
 
 <!-- filigree:instructions:v2.0.3:d454f2c2 -->
 ## Filigree Issue Tracker
diff --git a/docs/clarion/1.0/requirements.md b/docs/clarion/1.0/requirements.md
index eb688b5d..36b50d51 100644
--- a/docs/clarion/1.0/requirements.md
+++ b/docs/clarion/1.0/requirements.md
@@ -558,19 +558,28 @@ Clarion exposes read-only HTTP endpoints: `GET /api/v1/entities`, `GET /api/v1/e
 #### REQ-HTTP-03 — Registry-backend HTTP trust model
 
 For Filigree `registry_backend: clarion`, Clarion's HTTP read API is
-unauthenticated and loopback-only by default. Non-loopback binds are refused
-unless `serve.http.allow_non_loopback: true` is set; that opt-in requires an
-authenticated reverse proxy or equivalent operator-managed access-control layer
-outside Clarion.
+loopback-only by default. Non-loopback binds require **both**
+`serve.http.allow_non_loopback: true` **and** a resolved authentication secret
+— either HMAC identity via `serve.http.identity_token_env` (preferred per
+ADR-034) or a legacy bearer token via `serve.http.token_env`. A non-loopback
+bind with the opt-in but no resolved secret is refused at startup with
+`CLA-CONFIG-HTTP-NO-AUTH`. The loopback-without-token mode remains
+unauthenticated and emits a startup warning that any local process can read the
+catalogue; non-loopback no longer has an unauthenticated mode.
 
 **Rationale**: the ADR-014 read surface is a bounded local federation contract,
-not the earlier broad HTTP API. The implementation prevents accidental network
-exposure mechanically and leaves intentional non-loopback exposure to deployment
-controls.
-**Verification**: loopback bind starts without extra flags; non-loopback bind is
-rejected without `allow_non_loopback`; non-loopback opt-in logs an
-unauthenticated-surface warning.
-**See**: System Design §9 (Integrations, HTTP Read API), ADR-014.
+not the earlier broad HTTP API. ADR-034 closes the original gap that permitted
+unauthenticated non-loopback binds behind the `allow_non_loopback` opt-in
+alone. The implementation prevents accidental network exposure mechanically and
+makes intentional non-loopback exposure fail closed without an authentication
+secret rather than silently warn-and-bind.
+**Verification**: `crates/clarion-cli/tests/serve.rs` covers the loopback
+default (line 1457), the loopback `identity_token_env`-resolution-failure
+refusal (line 1495), the non-loopback-without-auth startup refusal (line 1547),
+the non-loopback HMAC-required path (line 1579), and the non-loopback
+legacy-bearer path (line 1614). The loopback startup-warning surface is covered
+by config-layer tests.
+**See**: System Design §9 (Integrations, HTTP Read API), ADR-014, ADR-034.
 
 #### REQ-HTTP-04 — ETag-style response caching
 
@@ -770,17 +779,29 @@ Clarion structures prompts with explicit `<file_content trusted="false">...</fil
 
 #### NFR-SEC-03 — Non-loopback HTTP read API guard
 
-Clarion refuses to start the ADR-014 HTTP read API on a non-loopback bind unless
-`serve.http.allow_non_loopback: true` is set. When enabled, startup logs a
-warning that the endpoint is unauthenticated and must be protected outside
-Clarion.
+Clarion refuses to start the HTTP read API on a non-loopback bind unless **both**
+`serve.http.allow_non_loopback: true` is set **and** an authentication secret is
+resolved at startup — either an HMAC identity secret via
+`serve.http.identity_token_env` (preferred, per ADR-034) or a legacy bearer
+token via `serve.http.token_env`. A non-loopback bind with neither secret
+resolved fails closed at startup with `CLA-CONFIG-HTTP-NO-AUTH`. The
+startup-warning surface (endpoint unauthenticated; protect outside Clarion)
+applies only to the loopback-without-token mode, which remains the ADR-014
+default for the local sidecar case.
 
 **Rationale**: loopback is not a complete security boundary, but accidental
-network exposure is the highest-risk failure mode for the registry-backend
-surface. The guard makes that exposure explicit.
-**Verification**: config tests cover the default, refusal, and opt-in warning
-paths.
-**See**: System Design §9 (HTTP Read API), §10 (Security), ADR-014.
+network *exposure* without authentication is the highest-risk failure mode for
+the registry-backend surface. ADR-034 closes the original ADR-014 gap that
+permitted unauthenticated non-loopback binds behind the `allow_non_loopback`
+opt-in alone; the opt-in remains the gate that admits non-loopback binds at all
+but no longer admits them unauthenticated.
+**Verification**: `crates/clarion-cli/tests/serve.rs` covers the loopback
+default (line 1457), the loopback `identity_token_env`-set-but-env-missing
+refusal (line 1495), the non-loopback-without-auth refusal (line 1547), the
+non-loopback HMAC-required path (line 1579), and the non-loopback legacy-bearer
+path (line 1614). Config-layer tests cover the loopback startup-warning
+surface.
+**See**: System Design §9 (HTTP Read API), §10 (Security), ADR-014, ADR-034.
 
 #### NFR-SEC-04 — Audit surface — security events as findings
 
diff --git a/docs/suite/loom.md b/docs/suite/loom.md
index baaaf92a..4f81a659 100644
--- a/docs/suite/loom.md
+++ b/docs/suite/loom.md
@@ -62,11 +62,11 @@ A "standalone mode" that works only because an invisible sibling is still import
 - **Clarion** builds its catalog whether Wardline is present or not. Wardline's annotations *enrich* Clarion's entity metadata with trust-tier and policy-semantic information, but Clarion's structural truth is independent of Wardline's policy truth.
 - **Shuttle**, if built, would execute changes whether any sibling is present. Sibling tools enrich its telemetry (which Filigree ticket? which Clarion entity? which Wardline policy?) but are never required for a change to apply or roll back.
 
-### v0.1 asterisks
+### v1.0 asterisks
 
-The v0.1 suite does not pass the expanded failure test cleanly. Two specific couplings are named here so they cannot drift unnoticed:
+The v1.0 suite does not pass the expanded failure test cleanly. Two specific couplings are named here so they cannot drift unnoticed:
 
-- **Wardline→Filigree findings are pipeline-coupled through Clarion in v0.1.** Wardline's SARIF output reaches Filigree only via Clarion's `clarion sarif import` translator. This violates pipeline composability for the (Wardline, Filigree) pair. *Retirement condition*: Wardline gains a native Filigree emitter (see Clarion's ADR-015), at which point Clarion's SARIF translator retires and the pair composes directly. The asterisk ships with v0.1 and retires in v0.2.
+- **Wardline→Filigree findings are pipeline-coupled through Clarion in v1.0.** Wardline's SARIF output reaches Filigree only via Clarion's `clarion sarif import` translator. This violates pipeline composability for the (Wardline, Filigree) pair. *Retirement condition*: Wardline gains a native Filigree emitter (see Clarion's ADR-015), at which point Clarion's SARIF translator retires and the pair composes directly. The asterisk ships with v1.0 and is tracked for retirement under `release:v1.1`.
 - **Clarion's Python plugin imports `wardline.core.registry.REGISTRY` at startup.** This is initialization coupling scoped to the Wardline-aware plugin specifically, not to Clarion as a product — Clarion's core and any non-Wardline-aware plugins do not depend on Wardline being importable. The coupling is named so it does not slip unexamined into a future general-purpose plugin. If a future plugin introduces similar initialization coupling without a clear "this plugin is specifically about Wardline" justification, it violates this rule.
 
 Asterisks are acceptable only with a written retirement condition and an honest statement of which failure-test mode is being temporarily violated. A "we'll fix it later" without a test-mode citation is not an asterisk; it is the stealth-monolith failure mode wearing different clothes.