docs: define TLS contract-pack profile#585
Conversation
Design-only doc establishing the TLS contract-pack scope: 6 cert fixtures (4 negative classes), 2 receipts, 1 evidence doc; expected verifier behavior per fixture; rustls/tonic adapter contracts; scanner-safety boundary; explicit out-of-scope list. Implementation lands in subsequent v0.8.0 PRs (CLI dispatch + proof artifact).
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
* feat(cli): add tls bundle profile Implements the v0.8.0 TLS contract-pack profile defined by docs/release/v0.8.0-tls-profile-design.md (PR-A, #585). This is PR-B of the v0.8.0 lane: CLI wiring only, no adapter helpers. What landed: - BundleProfile::Tls variant on the clap-derived profile enum, the manifest_name() arm, and the parse_manifest_profile() round-trip so `verify-bundle` reads the same profile string back. - New BundleEntry variants (TlsValidLeaf, TlsValidChain, TlsNegativeChain, TlsEvidenceDoc) feeding the existing bundle generation + receipt pipeline. The receipts/materialization.json and receipts/audit-surface.json shape is shared with scanner-safe and oidc, so existing tooling (`verify-bundle`, `inspect-bundle`) works unchanged. - Four negative chains generated via the existing uselesskey-x509::srp::chain_negative variants: ExpiredLeaf, NotYetValidLeaf, HostnameMismatch { wrong_hostname }, UnknownCa. - evidence/tls-profile.md emitted alongside the cert bundle with the per-fixture rejection-class table from the design doc. - Documented expected hostname and wrong hostname constants (TLS_EXPECTED_HOSTNAME, TLS_WRONG_HOSTNAME) baked into the bundle so downstream callers can assert against fixed strings. Tests: crates/uselesskey-cli/tests/tls_profile.rs covers layout, single-cert vs full-chain PEM block counts, byte-identical determinism across two invocations, and a `verify-bundle` round-trip with drift detection. Out of scope for this PR (tracked separately): - adapter helpers in uselesskey-rustls / uselesskey-tonic - bundle-proof --profile tls runner (PR-C) - committed expected/ artifacts under examples/ - how-to guide under docs/how-to/ Cross-refs: - design: docs/release/v0.8.0-tls-profile-design.md - negative variants: crates/uselesskey-x509/src/srp/chain_negative.rs * test(cli): assert tls evidence markdown content Close the mutation gap exposed by `cargo mutants` on render_tls_evidence_markdown - the function could be replaced with `"xyzzy".into()` and all tests still passed. Add a content assertion that names each of the 6 fixture filenames and each failure class.
Completes the v0.8.0 TLS lane started by the design doc in #585 and the CLI implementation in #587. Extends `cargo xtask bundle-proof` with a new `--profile tls` arm that produces the release-evidence proof artifact for the TLS contract pack, mirroring the OIDC precedent shipped in v0.7.0. What this PR does: - Adds `tls` to `BUNDLE_PROOF_SUPPORTED_PROFILES` and wires the per-profile default-out-dir / json-filename / markdown-filename / markdown-title / claim-boundary / expected-artifacts helpers. - Adds `TLS_CONTRACT_PACK_PROOF_CLAIM_BOUNDARY` (matches the design-doc scope: pack shape, not downstream verifier correctness; no revocation, no mTLS, no production CA custody). - Drives `bundle`, `verify-bundle`, `inspect-bundle`, the CLI tls contract-pack tests, x509 owner tests, and `no-blob` against the generated TLS bundle, and validates the 7 expected artifacts: 4 cert PEMs (valid leaf, valid chain, 4 negative classes) plus the per-fixture rejection evidence markdown. - Adds `tls-contract-pack-proof` to `release_evidence_steps_minor()` after `oidc-contract-pack-proof`. Patch lane stays unchanged: full contract-pack proofs are minor-only by design. - Adds the "TLS contract-pack proof" row to the minor release-summary table next to the scanner-safe and OIDC rows. Tests: - `bundle_proof_tls_profile_constant_includes_tls` covers the supported profile list, helper outputs, default out dir, and the 7 expected artifact paths. - `bundle_proof_receipt_enforces_tls_contract_pack_contents` and `bundle_proof_receipt_rejects_incomplete_tls_contract_pack` mirror the OIDC receipt tests against a `tls_bundle_proof_manifest()` helper. - `bundle_proof_markdown_summarizes_tls_contract_checks` covers the rendered markdown. - `release_evidence_minor_step_list_includes_tls_contract_pack_proof` and `release_evidence_patch_step_list_excludes_tls_contract_pack_proof` pin the step-list wiring on both lanes. - Updates the existing minor-lane dry-run / summary tests to also assert the new TLS step and artifacts. Validation: - `cargo xtask bundle-proof --profile tls --out target/release-evidence/tls` succeeds end-to-end. Generated bundle has the 6 PEMs + evidence/tls-profile.md + 2 receipts; `tls-contract-pack-proof.{json,md}` are written with all 7 contract-pack checks present. - `cargo xtask bundle-proof --profile scanner-safe` and `--profile oidc` still succeed (regression-clean). - `cargo xtask release-evidence --version 0.8.0-dev --dry-run --summary` plans 16 commands including the new tls step; the `--patch --dry-run` variant plans 10 commands with tls excluded. - `cargo fmt --check -p xtask` and `cargo clippy -p xtask --all-targets -- -D warnings` clean. Out of scope: - `crates/uselesskey-cli/` — the TLS profile already exists post-#587; this PR is xtask-only. - Task-first TLS how-to docs (planned for PR-D). - rustls/tonic adapter helpers (future release). Cross-refs: - Design: `docs/release/v0.8.0-tls-profile-design.md` (PR #585). - CLI impl: PR #587. - OIDC proof precedent (template followed here): `oidc-contract-pack-proof.{json,md}` and the `OIDC_CONTRACT_PACK_PROOF_CLAIM_BOUNDARY` constant.
Task-first user-facing how-to for the `uselesskey bundle --profile tls` contract pack. Walks readers through generating the bundle, the six certificate fixtures (valid leaf, valid chain, four negatives), the expected verifier outcomes per fixture, the documented hostname constants, and the release-grade evidence command. Mirrors the OIDC how-to pattern: terse, task-first prose, explicit "what this proves / does not prove" claim boundaries, and a scanner-safety note that points back to publish-recovery and the design doc for out-of-scope coverage. Completes the v0.8.0 TLS contract-pack lane: design (#585) + CLI profile (#587) + xtask bundle-proof (#588) + this user-facing piece. Pure docs PR; no source changes.
Pure design doc for the v0.8.0 TLS contract-pack profile. No code.
Summary
Establishes the contract for
uselesskey bundle --profile tlsbefore anyimplementation lands. Models the v0.7.0 OIDC contract pack — a
deterministic bundle of valid plus protocol-shaped negative fixtures that
downstream TLS verifiers can run against — for cert-chain validation
tests.
Bundle shape:
certs/valid-leaf.pem,certs/valid-chain.pem(happy path)certs/negative-expired-leaf.pem(expired)certs/negative-not-yet-valid.pem(not yet valid)certs/negative-wrong-hostname.pem(hostname mismatch)certs/negative-untrusted-root.pem(unknown CA)receipts/materialization.json,receipts/audit-surface.jsonevidence/tls-profile.mdThe doc records per-fixture expected verifier behavior, rustls / tonic
adapter contracts (behavior only — no typed API claims yet), the
scanner-safety boundary, PR-time and release-time evidence routing, and
an explicit out-of-scope list.
v0.8.0 PR sequence
docs: define TLS contract-pack profile—pure design.
feat(cli): add tls bundle profile—BundleProfile::Tlsdispatch, six cert fixtures, receipts, evidence markdown, rustls/tonic
adapter helpers.
xtask: add tls contract-pack proof—bundle-proof --profile tlsrunner, fold into v0.8.0 release-evidencematrix.
Precedent
The OIDC contract pack (v0.7.0,
bundle --profile oidc) proved thecontract-pack model and is referenced throughout this doc:
docs/how-to/test-oidc-jwks-validation.mdtarget/release-evidence/oidc/oidc-contract-pack-proof.mdThe TLS pack reuses the same dispatch shape, scanner-safe stance, and
receipt schema.
Claim boundary
uselesskeyis a test-fixture layer. The TLS pack proves verifierrejection paths for five failure classes; it does NOT prove revocation
handling, CT log behavior, mTLS, browser-trust-store simulation, or
production CA custody.
Test plan
cargo xtask docs-sync --checkpassescargo xtask typospassesgit diff --checkcleandocs/release/(release-scope design), notdocs/how-to/crates/,xtask/,examples/, or other code-path edits)not-proven boundaries