Skip to content

v1.0 tag-cut: refresh internal docs against ADR-034 (PR 2/4) #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
tachyon-beep wants to merge 1 commit into from
Closed

v1.0 tag-cut: refresh internal docs against ADR-034 (PR 2/4) #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
61 changes: 41 additions & 20 deletions docs/clarion/1.0/requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines +567 to +568

@chatgpt-codex-connector chatgpt-codex-connector Bot May 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Remove claim of loopback unauthenticated startup warning

This requirement now states that loopback-without-token mode emits a startup warning, but the startup warning in crates/clarion-cli/src/http_read.rs is only guarded by warn_unauthenticated_non_loopback (non-loopback bind with no auth) and there is no analogous loopback warning path. Since ADR-034 validation rejects unauthenticated non-loopback startup, this documented loopback warning behavior is not backed by implementation and can mislead operators about what signal they will actually see.

Useful? React with 👍 / 👎.

Comment on lines +567 to +568

**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
Comment on lines +577 to +580

@chatgpt-codex-connector chatgpt-codex-connector Bot May 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Point verification at actual HTTP-auth tests

The verification references here cite crates/clarion-cli/tests/serve.rs lines 1457/1495/1547/1579/1614, but those lines are in summary-provider tests (and shell fixture text), not the non-loopback/authentication guard behavior this requirement describes. This makes the requirement’s evidence trail incorrect and can hide regressions because readers will validate the wrong tests; the relevant HTTP auth coverage is around the non-loopback/identity tests near serve_http_refuses_startup_on_non_loopback_without_token and related cases in the 1250–1345 range.

Useful? React with 👍 / 👎.

by config-layer tests.
Comment on lines +577 to +581
**See**: System Design §9 (Integrations, HTTP Read API), ADR-014, ADR-034.

#### REQ-HTTP-04 — ETag-style response caching

Expand Down Expand Up @@ -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
Comment on lines +799 to +802

@chatgpt-codex-connector chatgpt-codex-connector Bot May 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Fix NFR-SEC-03 verification test citations

This verification block repeats the same incorrect serve.rs line citations (1457/1495/1547/1579/1614), which point to summary-routing tests rather than the HTTP bind/auth guard tests described by NFR-SEC-03. Keeping these references as-is weakens the requirement traceability and can misdirect audits to unrelated coverage instead of the actual non-loopback and identity-token enforcement tests around lines 1250–1345.

Useful? React with 👍 / 👎.

surface.
**See**: System Design §9 (HTTP Read API), §10 (Security), ADR-014, ADR-034.

#### NFR-SEC-04 — Audit surface — security events as findings

Expand Down
6 changes: 3 additions & 3 deletions docs/suite/loom.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading