Skip to content

docs: define TLS contract-pack profile#585

Merged
EffortlessSteven merged 1 commit into
mainfrom
docs/tls-contract-pack-design
May 11, 2026
Merged

docs: define TLS contract-pack profile#585
EffortlessSteven merged 1 commit into
mainfrom
docs/tls-contract-pack-design

Conversation

@EffortlessSteven

Copy link
Copy Markdown
Member

Pure design doc for the v0.8.0 TLS contract-pack profile. No code.

Summary

Establishes the contract for uselesskey bundle --profile tls before any
implementation 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.json
  • evidence/tls-profile.md

The 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

  • PR-A (this PR): docs: define TLS contract-pack profile
    pure design.
  • PR-B: feat(cli): add tls bundle profileBundleProfile::Tls
    dispatch, six cert fixtures, receipts, evidence markdown, rustls/tonic
    adapter helpers.
  • PR-C: xtask: add tls contract-pack proof
    bundle-proof --profile tls runner, fold into v0.8.0 release-evidence
    matrix.

Precedent

The OIDC contract pack (v0.7.0, bundle --profile oidc) proved the
contract-pack model and is referenced throughout this doc:

  • How-to: docs/how-to/test-oidc-jwks-validation.md
  • Release-evidence proof: target/release-evidence/oidc/oidc-contract-pack-proof.md

The TLS pack reuses the same dispatch shape, scanner-safe stance, and
receipt schema.

Claim boundary

uselesskey is a test-fixture layer. The TLS pack proves verifier
rejection 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 --check passes
  • cargo xtask typos passes
  • git diff --check clean
  • Doc placed under docs/release/ (release-scope design), not
    docs/how-to/
  • No changes outside the new doc file (no crates/, xtask/,
    examples/, or other code-path edits)
  • All six certificate fixtures specified with expected-behavior /
    not-proven boundaries
  • Claim boundary explicit in Scope section

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).
@gemini-code-assist

Copy link
Copy Markdown

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@coderabbitai

coderabbitai Bot commented May 11, 2026

Copy link
Copy Markdown

Warning

Rate limit exceeded

@EffortlessSteven has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 38 minutes and 16 seconds before requesting another review.

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 @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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 configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: ed241cad-540e-4031-9a63-60cc50476573

📥 Commits

Reviewing files that changed from the base of the PR and between 4a758a3 and bc53f8b.

📒 Files selected for processing (1)
  • docs/release/v0.8.0-tls-profile-design.md
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/tls-contract-pack-design

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@EffortlessSteven EffortlessSteven merged commit b13296b into main May 11, 2026
5 checks passed
EffortlessSteven added a commit that referenced this pull request May 12, 2026
* 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.
EffortlessSteven added a commit that referenced this pull request May 12, 2026
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.
EffortlessSteven added a commit that referenced this pull request May 12, 2026
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.
@EffortlessSteven EffortlessSteven mentioned this pull request May 12, 2026
4 tasks
EffortlessSteven added a commit that referenced this pull request May 12, 2026
TLS contract-pack and public crate-surface cleanup release. Bumps
workspace to 0.8.0. CHANGELOG entry curated from merged PRs:
#485-#605 (TLS lane #585/#587/#588/#589, task-first how-tos
#590-#594, SRP collapse #595/#598/#599/#602, migration guide #603,
Clippy ratchets #505, dep bumps #484-#491).
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.

1 participant