Skip to content

docs: make the docs and site say what the code does (#73) - #76

Merged
DavidGodefroid merged 1 commit into
mainfrom
docs/fact-check-73
Nov 14, 2026
Merged

DavidGodefroid merged 1 commit into
mainfrom
docs/fact-check-73

Conversation

@DavidGodefroid

Copy link
Copy Markdown
Owner

Summary

This PR fixes the documentation items of the fact-check in #73: the README, docs/, SECURITY.md, CONTRIBUTING.md and site/. It changes no code. I re-verified each item against origin/main at a3761ad, and against lea origin/main where the two integrate.

  • Security model (items 1 to 13):
  • Approvals are on lockhub (14 to 18): the console reviews policy loosenings only and approves no request. The docs now use lox run's service and volume names, and keep the standalone launcher's names for the standalone case. D7, hub step 19, and the SECURITY.md scope are rewritten for the hub.
  • Policy semantics (19 to 29):
    • The managed deny and managed ask steps are in the evaluation order, and shadow mode keeps managed rules.
    • Step 8 still applies when the gate has no policy.
    • The Anthropic exceptions are described: OAuth, body-less reads, trusted docs.anthropic.com, and container.
    • The ClientHello check applies to non-internal hosts.
    • The canonical-path check applies only when paths is set.
    • The upload class no longer mentions bodies of unknown length.
    • The auto checks are split into parse-time and per-request checks.
    • The policy-decode fallback is described: asks get E_NO_CONSOLE, FREE continues.
    • Internal hosts are reachable on ports 80 and 443 plus the declared ports.
    • D-optin, D8 and D6 match the code.
    • "v0.1.0" is replaced by "the current release".
  • Commands and lea (30 to 58):
    • Flags, defaults and exceptions are corrected, including --hub-net and positional arguments, and the managed-dir mount is documented.
    • The audit decision values are listed.
    • The supported-versions table now runs from v0.9.0 to v0.12.0.
    • The cosign behaviour of update is described exactly, including LOCKHTTP_SKIP_COSIGN and pre-releases.
    • The launcher's exact identity is distinguished from the regexp in SECURITY.md.
    • lea: the CA path is ~/.local/share/lea/..., lea runs ca init itself, and the trust store is /etc/pki/ca-trust/....
    • lea: the audit is a named volume, the gate takes the profile from up.json, the proxy address is $LEA_PROXY_IP, a root-owned /usr/local/bin/lockhttp is trusted without checks, and the deck plays no sound.
    • lea: the doctor list now separates lea doctor's checks from the manual ones.
    • CONTRIBUTING: macOS is not run on PRs, and the exact integration command is given.
  • Reference pages and site (59 to 67):
    • E_METHOD and E_UNCONFINED are listed.
    • The inject example now has its internal_hosts entry.
    • The replay fingerprint covers every end-to-end header.
    • ca init is shown with --dir.
    • Versions updated: lockkit v0.20.0, site v0.12.x.
    • The signer is drawn outside the proxy's network namespace.
    • site/install no longer mentions lockhttp's own "signed install script".
  • Unverifiable items: I checked them in lockkit, lockhub, homebrew-tap, lockfamily and lea.
    • brew trust exists: the tap's CI runs it.
    • The brew formula does not run cosign at install. It writes a digest the tap verified when it was bumped, and the docs now say so.
    • All the other unverifiable items are accurate.

Closes #73

Test plan

  • scripts/hygiene.sh passes.
  • go test ./cmd/lockhttp/ -run 'Release|Launcher|Workflow|Pin|Doc' passes.
  • Every markdown table row has the same number of columns as its header.
  • CI is green.
  • The pages deploy succeeds after the merge.

🤖 Generated with Claude Code

Fix the FALSE, MISLEADING and OUTDATED items of the fact-check in
README.md, docs/, SECURITY.md, CONTRIBUTING.md and site/, each
re-verified against origin/main (and lea origin/main where they meet):

- security model: DNS resolved before the decision with --hub-net (T2
  residual), Claude allowlist vs user rules and shadow mode, Cookie
  scanned, decryption covers CONNECT :443 only, internal_hosts lift the
  floor, CA key on the host under lea, WebSocket frames scanned for
  injected secrets, warnings in the audit;
- approvals are hub tickets; the console only reviews loosenings; lox
  run's service and volume names, the standalone launcher's kept;
- policy: managed deny/ask steps, step 8 with no policy, ClientHello
  check for non-internal hosts, inject paths, upload class, hub step 19;
- decisions D7, D8, D-optin, D-ih, D6, fail-closed fallback, auto checks
  split between parse time and per request;
- usage, configuration, docker, install, lea: flags, defaults, audit
  decisions, versions table to v0.12.0, cosign behaviour, CA paths,
  trust store, audit volume, proxy IP, manual checks;
- site: version v0.12.x, comparison rows, audit, inject example with
  internal_hosts, E_UNCONFINED and E_METHOD, signer out of the proxy
  namespace.

pages.yml now pins its actions by full commit SHA, as SECURITY.md says.

Closes #73

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@DavidGodefroid
DavidGodefroid merged commit e000add into main Nov 14, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs fact-check: wrong or misleading claims

1 participant