v1.0 tag-cut: refresh internal docs against ADR-034 (PR 2/4)#14
v1.0 tag-cut: refresh internal docs against ADR-034 (PR 2/4)#14tachyon-beep wants to merge 1 commit into
Conversation
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.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 064d37aa35
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 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 |
There was a problem hiding this comment.
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 👍 / 👎.
| 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 |
There was a problem hiding this comment.
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 👍 / 👎.
| unauthenticated and emits a startup warning that any local process can read the | ||
| catalogue; non-loopback no longer has an unauthenticated mode. |
There was a problem hiding this comment.
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 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Updates the v1.0 internal documentation to align with ADR-034’s hardened HTTP read API trust model (non-loopback binds must be authenticated) and refreshes a couple of v1.0-era “asterisks”/follow-up tracking notes.
Changes:
- Rewrite
REQ-HTTP-03andNFR-SEC-03in the v1.0 requirements to reflect “authenticated non-loopback” (HMAC preferred; legacy bearer supported) and add ADR-034 to references. - Update
CLAUDE.mdto state HMAC is the preferred non-loopback mechanism in v1.0 (not post-1.0 hardening). - Rename
loom.md“v0.1 asterisks” → “v1.0 asterisks” and retarget retirement tracking torelease:v1.1.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/suite/loom.md | Renames the “asterisks” section to v1.0 and updates the retirement-tracking wording. |
| docs/clarion/1.0/requirements.md | Updates HTTP trust/security requirements to match ADR-034’s authenticated non-loopback rule and expands verification/See references. |
| CLAUDE.md | Corrects the v1.0 positioning of HMAC inbound auth per ADR-034 and notes remaining forward-work. |
Comments suppressed due to low confidence (2)
docs/clarion/1.0/requirements.md:790
- This requirement references a “startup-warning surface (endpoint unauthenticated; protect outside Clarion)” for loopback-without-token mode. In the current implementation, there is no loopback-specific warning; the only WARN log is for unauthenticated non-loopback binds (which are refused at startup), while loopback unauthenticated binds log INFO with
auth=none. Please align the requirement text with the actual logging semantics (or implement the documented warning).
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.
docs/clarion/1.0/requirements.md:803
- The verification clause again cites
crates/clarion-cli/tests/serve.rsline numbers (1457/1495/1547/1579/1614) that no longer match the described HTTP auth/non-loopback guard tests. Please update to stable references (prefer test names) and ensure the cited tests actually cover the non-loopback HMAC/bearer paths being claimed.
**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.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| unauthenticated and emits a startup warning that any local process can read the | ||
| catalogue; non-loopback no longer has an unauthenticated mode. |
| 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. |
|
Superseded — the v1.0 tag-cut work in this stacked chain has all landed on |
Summary
ADR-034 retroactively made non-loopback HTTP binds require authentication (HMAC identity preferred, legacy bearer supported). The internal design docs were still describing the pre-ADR-034 trust model. This PR refreshes them.
Changes (single commit, 3 files, 50/24 line delta):
docs/clarion/1.0/requirements.mdNFR-SEC-03 — rewrite statement + verification clause for the authenticated-non-loopback rule. Verification cites the fivecrates/clarion-cli/tests/serve.rstests that enforce it.docs/clarion/1.0/requirements.mdREQ-HTTP-03 — same scope; See line addsADR-034.CLAUDE.mdHMAC paragraph — HMAC is the preferred non-loopback mechanism in v1.0 per ADR-034, not "post-1.0 hardening". Only replay protection (timestamp + nonce window) remains as ADR-034 forward-work.docs/suite/loom.md— §5 "v0.1 asterisks" → "v1.0 asterisks"; retirement wording retargeted torelease:v1.1.Closes (filigree)
clarion-7913f950d7— DOC-03 NFR-SEC-03 stale post-ADR-034clarion-272b5bc1ec— DOC-04 REQ-HTTP-03 stale post-ADR-034clarion-461e78616f— DOC-05 REQ-HTTP-03 See line (folded into DOC-04 rewrite)clarion-8367414ab5— DOC-06 loom.md "v0.1 asterisks" labelsclarion-84a1fbaba1— DOC-07 CLAUDE.md HMAC misrepresentationTest plan
Doc-only change. Verified ADR-034 §3 wording matches the refreshed requirements; verified See lines cite ADR-034.
🤖 Generated with Claude Code