docs: correct the redirect-matching and IdP-support claims #8

Merged

jlxq0 merged 1 commit from docs/correct-redirect-and-idp-claims into main

2026-08-26 05:08:26 +00:00

jlxq0 commented

2026-08-26 04:57:45 +00:00

Owner

Three prose claims that are false, in one PR because none of them is testable
and all three were found by reading rather than by a failure.

`README.md` — "Redirect URIs are exact matches"

False since v0.1.3. matches_loopback_entry (src/oauth_redirect.rs:43)
relaxes the port for cleartext loopback entries, as RFC 8252 §7.3 requires.
This is the public-facing one and it is actively harmful: it tells an operator
to allowlist every ephemeral port a native client might bind, which is the
conclusion that produced #5 and locked the Claude Code CLI out with
unregistered redirect_uri. Replaced with the actual rule, including what is
still exact (scheme, host, path, query, and the full string for https and
private-use entries).

`AGENTS.md` — "Logto or another OIDC provider"

Contradicted by README.md:44 ("Logto-compatible, not arbitrary-OIDC
compatible") and by AGENTS.md's own Known Pitfalls forty lines below it. Two
correct statements and one stale one in a single file is worse than being
wrong throughout, because a reader who finds an accurate one first has no
reason to keep looking.

No `CLAUDE.md`

Codex reads AGENTS.md and gets the whole pitfall list; Claude got nothing.
One line, @AGENTS.md, per the repo convention.

Verification

Five gates green at 12395a1 on rustc 1.98.0, which is what CI's
toolchain: stable resolves to today: cargo fmt --all --check,
cargo clippy --all-targets --all-features --locked -- -D warnings,
cargo test --all-features --locked (92 passed), cargo audit against the
finished lockfile, cargo deny check bans licenses sources.

This change is not test-covered and cannot be. No assertion can catch
prose that contradicts a passing test, which is precisely how the README line
survived #6. Rather than add a token assertion that pretends otherwise, the
behaviour the new wording describes was verified by removal: replacing the
body of matches_loopback_entry with return false, which is exactly the
behaviour the old README described, turns loopback_entry_matches_any_port
and loopback_port_relaxation_does_not_relax_host_or_path red and leaves the
other 90 tests green. The suite rejects the state the README documented.

Deployment unaffected: docs only, no Cargo.toml, Dockerfile or workflow
change. v0.1.3 stays the released version.

Three prose claims that are false, in one PR because none of them is testable and all three were found by reading rather than by a failure. ### `README.md` — "Redirect URIs are exact matches" False since v0.1.3. `matches_loopback_entry` (`src/oauth_redirect.rs:43`) relaxes the port for cleartext loopback entries, as RFC 8252 §7.3 requires. This is the public-facing one and it is actively harmful: it tells an operator to allowlist every ephemeral port a native client might bind, which is the conclusion that produced #5 and locked the Claude Code CLI out with `unregistered redirect_uri`. Replaced with the actual rule, including what is still exact (scheme, host, path, query, and the full string for `https` and private-use entries). ### `AGENTS.md` — "Logto or another OIDC provider" Contradicted by `README.md:44` ("**Logto-compatible**, not arbitrary-OIDC compatible") and by AGENTS.md's own Known Pitfalls forty lines below it. Two correct statements and one stale one in a single file is worse than being wrong throughout, because a reader who finds an accurate one first has no reason to keep looking. ### No `CLAUDE.md` Codex reads `AGENTS.md` and gets the whole pitfall list; Claude got nothing. One line, `@AGENTS.md`, per the repo convention. ## Verification Five gates green at `12395a1` on rustc 1.98.0, which is what CI's `toolchain: stable` resolves to today: `cargo fmt --all --check`, `cargo clippy --all-targets --all-features --locked -- -D warnings`, `cargo test --all-features --locked` (92 passed), `cargo audit` against the finished lockfile, `cargo deny check bans licenses sources`. **This change is not test-covered and cannot be.** No assertion can catch prose that contradicts a passing test, which is precisely how the README line survived #6. Rather than add a token assertion that pretends otherwise, the behaviour the new wording describes was verified by removal: replacing the body of `matches_loopback_entry` with `return false`, which is exactly the behaviour the old README described, turns `loopback_entry_matches_any_port` and `loopback_port_relaxation_does_not_relax_host_or_path` red and leaves the other 90 tests green. The suite rejects the state the README documented. Deployment unaffected: docs only, no `Cargo.toml`, `Dockerfile` or workflow change. `v0.1.3` stays the released version.

jlxq0 added 1 commit

2026-08-26 04:57:45 +00:00

docs: correct the redirect-matching and IdP-support claims

CI / cargo (pull_request) Successful in 53s

Details

CI / docker (pull_request) Successful in 20s

Details

12395a1816

README said "Redirect URIs are exact matches". That stopped being true in
v0.1.3, which relaxed the port for cleartext loopback entries per RFC 8252
§7.3. A reader following the old line concludes they must allowlist every
ephemeral port a native client might bind, which is the same wrong conclusion
that produced #5.

AGENTS.md's public auth contract offered "Logto or another OIDC provider",
contradicting both README and its own Known Pitfalls forty lines further down.
Two accurate statements and one stale one in the same file is worse than being
wrong throughout: a reader who hits the accurate one first never looks further.

Add the one-line CLAUDE.md pointer so Claude reads AGENTS.md, which Codex
already does.

No test covers any of this and none can: the behaviour is already pinned by
loopback_entry_matches_any_port and loopback_port_relaxation_does_not_relax_
host_or_path, and the prose contradicted a passing test. Verified by removal
instead: replacing the body of matches_loopback_entry with `return false`,
which is exactly the behaviour the old README described, turns both of those
tests red and leaves the other 90 green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4zPxBoAdNv8QfBDdfGHJ6

jlxq0 referenced this pull request

2026-08-26 04:58:33 +00:00

deployed_allowlist_parses cannot observe the deployment it is named after #11

jlxq0 merged commit 8cb3a1ea42 into main

2026-08-26 05:08:26 +00:00

jlxq0 deleted branch docs/correct-redirect-and-idp-claims

2026-08-26 05:08:27 +00:00

jlxq0 referenced this pull request from a commit

2026-08-26 05:08:27 +00:00

Merge pull request 'docs: correct the redirect-matching and IdP-support claims' (#8) from docs/correct-redirect-and-idp-claims into main

jlxq0 referenced this pull request

2026-08-27 02:37:06 +00:00