Repository navigation
feat(broker): An Integrator can read when a grant ends and which certificate was approved - #39
Merged
Merged
Conversation
…ificate was approved The backend approval status response now carries `expires_at_ms` and `certificate.sha256` once an approval has a grant, and omits them for one that never had one. An approval that ended after it was granted (expired, cancelled, replaced) keeps its own grant's values. Refs #12 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refs #12 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… that the deadline can end sooner Review round 1 on f28a87e: an approval that expired or was cancelled before a grant, or whose grant record retention removed, omits the fields; the deadline is the approved one, not when access ends. The test now checks the Companion's deadline exactly and an approval that lapsed without a grant. Refs #12 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…bject, issuer and expiry The Broker keeps the selected leaf's subject, issuer and own not-after with the grant, so they outlive the approval's public chain, and the status call reports them under `certificate`. A store opened by this Broker gains the columns in place, without a version bump, so an older Broker can still open it; a grant recorded before then reports its digest alone. Refs #12 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… fingerprint itself The Access approved page shows how long the grant has left, from the status call's expires_at_ms. The Job result page compares the fingerprint the site received with certificate.sha256 from the status call and drops the paste box. The screenshot fixtures carry the new fields, and the handbook shots are re-rendered. A page test drives the site in Playwright's Chromium, which CI now installs before pnpm test. Refs #12 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…thout creating one POST /v1/backend/approvals/current takes a Workload binding and host and returns the status view of the approval its Gateway traffic uses, or 404. The demo's Job result page uses it, through /api/job, to compare the site's fingerprint with the approval the job ran under, even when the job's own connection started it, and compose_demo --verify checks that match instead of pasting a fingerprint. Also from review round 3 on 9eb4f81: the no-approval wording, one comparison for both verdicts, a countdown updater that no longer shadows show(), and the name order of subject and issuer in the API docs. Refs #12 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… Integrator Review round 4 on d515e6c: the lookup refuses a binding for another Integrator and queries by the authenticated one, rather than trusting the binding's. The demo's /api/job shows the job's result even when the Broker can't answer the lookup. Refs #12 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… ran under The demo Integrator pins the Workload's current approval when the launcher records a job's result (it polls job.json), and the Job page reads that approval's status from then on. A renewal approved later, or a fresh request after the approval ends, no longer changes the comparison. A job nobody pinned yet pins at its first read. Refs #12 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…current then The pin was keyed on job.json's text, so a rerun under a renewal that wrote identical text kept comparing against the earlier approval. It is now keyed on the text and the file's mtime. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
99dabc2 added the module without adding it to the Dockerfile, so the container exited at startup with ERR_MODULE_NOT_FOUND. A test now checks that the Dockerfile copies every local module integrator.js and upstream.js import. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #12
Summary
An Integrator's backend can now read, from the approval status call, when a grant's approved access ends (
expires_at_ms) and which client certificate the user approved (certificate: itssha256, the fingerprint the Companion shows, plus its subject, issuer and expiry). A newapprovals/currentcall finds a Workload's current approval without creating one, and the demo Integrator uses both to count down to the deadline and check the fingerprint itself.POST /v1/backend/status { "id": "…", "state": "approved", "ready": true, + "expires_at_ms": 1795470000000, + "certificate": { "sha256": "c64a4b8b…f00b", + "subject": "CN=Demo user", "issuer": "CN=Countersign demo client-ca", + "not_after_ms": 1826000000000 }, "upstream_mtls_accepted": true, "ingress_closed_count": 0, "egress_closed_count": 0 } +POST /v1/backend/approvals/current { binding, host } -> the same view, or 404; never createsChoices the ticket left open, decided here:
expiredandcancelledones that had a grant, because the same grant row describes them.expires_at_msis the approved deadline, not the effective lease deadline.docs/reference/api.mdsays that a revocation, a renewal or a Gateway lease can end access sooner, and thatstatesays whether the grant is still in force.approved_grantgainssubject,issuerandnot_after, added in place on open without bumpinguser_version, so an older Broker can still open the store. A grant recorded before this change reports{sha256}only.C=US, O=…, CN=…), as x509-parser prints them, joined with ", ".api.mdsays so.approvals/currentanswers 404 for an unknown host or another Integrator's binding. It matches the authenticated Integrator, and returns the same viewstatusdoes.pnpm test, for the demo's new page tests.Extras for the owner
certificate.subject,issuerandnot_after_ms. The ticket marks them optional: "If keeping them means persisting the chain, shipsha256alone first."approvals/current), reviewed in round 4job.json's text. A mismatch run under one approval, then a renewal approving the job's certificate and a rerun, writes the same text, so the page keeps comparing against the first approval and still says the fingerprints differ. Criterion 5: "compares against the approval the job ran under". Pinning on the file's mtime as well fixes it, with a unit test for an identical rerun, plus a review round.Evidence
expires_at_msandcertificate.sha256for approvals that have a grant, and omits them for approvals that don'tstatus_reports_grant_expiry_and_certificate_once_a_grant_exists;authenticated_consent_signing_reconnect_and_revocation(cancelled)status_reports_grant_expiry_and_certificate_once_a_grant_existsdocs/reference/api.mddocuments the fieldsdocs/reference/api.md, "Read approval status", read by the Spec reviewer in rounds 1, 3 and 4certificatealso carriessubject,issuerandnot_after_ms, kept with the grantstatus_reports_grant_expiry_and_certificate_once_a_grant_exists;opening_an_older_store_adds_the_leaf_columns_to_existing_grantsexamples/demo-integrator/compose_demo.py --verify(the wiring, live); the fourjob-approval.test.jstests (the pinning);status_reports_grant_expiry_and_certificate_once_a_grant_exists(the lookup)the Access approved page counts down to the grant deadline;the Job result page compares the fingerprints without a paste box;node scripts/capture_screenshots.mjsAll six boxes are ticked with
tick-criteria.py, after the ticket's section heading was renamed from## Acceptanceto## Acceptance criteria.status_reports_grant_expiry_and_certificate_once_a_grant_exists: pending omits the fields; approved carries themservice.rs:707 left: Null right: Object {"sha256": …}certificatefordenied: panicked atservice.rs:786certificatefor a grant-lessexpired: panicked atservice.rs:814service.rs:723certificatenames the leaf's subject, issuer and expiryservice.rs:732 left: {"sha256": …} right: {"issuer": "CN=Broker integration test CA", "not_after_ms": 4070908800000, "sha256": …, "subject": "CN=Broker integration test user"}{sha256}onlysubjectfor it:service.rs:850 left: {"sha256": …, "subject": Null}approvals/currentfinds the approval, and 404s without creating oneservice.rs:654approvals/currentrefuses another Integrator's bindingservice.rs:803 left: 200 right: 404authenticated_consent_signing_reconnect_and_revocation: a cancelled approval keeps its grant's valuesservice.rs:467opening_an_older_store_adds_the_leaf_columns_to_existing_grantsALTER: panicked atapprovals.rs:489the Access approved page counts down to the grant deadlinewaiting for locator('#access-ends').getByText('14:30 left'), timeoutthe Job result page compares the fingerprints without a paste boxwaiting for locator('#match') to be visible, timeoutthe Job result page says when the job has no approved certificate to compare#no-compareexisted: failed with a timeouta job keeps the approval that was current when its result landed;a job read before anything noticed it pins the approval current at that readactual: 'B'no job, or a Broker that could not answer, leaves nothing pinned for goodERR_MODULE_NOT_FOUNDbeforejob-approval.jsexisteda rerun that writes the same result again pins the approval current thenactual: 'A', expected: 'B'the image copies every local module the servers import+ actual: ['job-approval.js']; the live run had exited with the integrator containerexited (1), andnode -e "import('./job-approval.js')"in that image printedERR_MODULE_NOT_FOUNDOn 81c52af (17a55a6 changes only the demo's Dockerfile and a test):
cargo test -p countersign-broker: lib 6, approvals 8, service 4 passed; 0 skipped, 0 failed.cargo clippy -p countersign-broker --all-targets -- -D warningsandcargo fmt --all --checkare clean.pnpm testinexamples/demo-integratoron 17a55a6: 8 passed, 0 skipped, 0 failed;pnpm lintis clean.node scripts/capture_screenshots.mjsre-renderedaccess-active(light and dark) andjob-result: the first shows "59:30 left · until …" under the grant row, the second the job's fingerprint beside the approved certificate's, with "Same SHA-256" shown. The Companion formats the fingerprint as lowercase hex (packages/companion/src/main.js:120), so the docs' "without its spaces" holds.xvfb-run -a .venv/bin/python examples/demo-integrator/compose_demo.py --app packages/companion/dist/linux-arm64-unpacked/countersign-companion --verifyon 17a55a6, with a Companion built from this branch: exit 0, printingCompose mTLS accepted selected SHA-256 99f4b3e3…5c09andJob page matched the fingerprint the site received with the approval. It paired, approved, ran the job'scurlthrough the Gateway (the job's own request started the approval), and opened/job, which showed#job-approvedwith the fingerprint and#match.Not run: the Gateway runtime test and the Companion and widget suites, because nothing they cover changed.
Merge Danger
Door: two-way. A revert removes the response fields, the
approvals/currentroute and the demo changes. The threeapproved_grantcolumns stay in any store this Broker opened; the older Broker ignores them.Blast Radius: Integrator backends that read approval status; the demo Integrator.
The merge ships a Broker whose status response has more fields, a new backend route, and an in-place column migration on open (no
user_versionbump). CI gains a Playwright Chromium install step. No flag.Reviews
Correctness, Standards, Spec and Security, seven rounds: 36 findings, each with its outcome
Correctness, round 1
approved_grantwhile the approval row can survive, so the fields vanish against the docs' promise. Fixed:docs/reference/api.mdsays the fields are absent once audit retention removes an ended approval's grant record.expiredorcancelledapproval keeps the fields, but one that ended before a grant has none. Fixed: the docs list those cases as absent.statesays whether the grant is still in force.expires_at_msis not the effective lease deadline. Fixed: the docs call it the deadline the user approved; the value stays the grant's deadline, as the ticket asks.approve/statushelpers repeat the older revocation test's inline flow. Pushed back: that test fetches by the admit body and runs lease and sign steps between those calls, so moving it onto the helpers is churn outside this ticket.Standards, round 1
service.rs.certificatebinding holds a digest. Fixed: renamed tocertificate_sha256.approvehelper takes a barerenewal: bool. Pushed back: two call sites, and the doc comment says what it does.endedholds seconds, while another test'sendedholds a state. Fixed: renamed toexpired_at_s.Spec, round 1: no findings. Security, round 1: no findings.
Correctness, Standards, Spec and Security, round 2 (fixes since f28a87e, pinned df4be77): no findings.
Correctness, round 3 (the two widenings, df4be77..9eb4f81)
approvals/currentfinds the job's approval (criterion 5), reviewed in round 4. The same round foundcompose_demo.py --verifystill filling the removed paste box; fixed to expect#job-approvedand#match.#no-comparesays to approve the request in the Companion and run the job again.show. Fixed: renamed.samecomputed once.subjectandissuer. Fixed:api.mdsays encoding order, joined with ", ".Standards, Spec and Security, round 3: no findings; Spec judged both added criteria met.
Correctness, round 4 (9eb4f81..d515e6c)
job-approval.js), reviewed in round 5.approvals/currentchecks no permit, and answers 404 wherestatusmight answer 403. Pushed back: the endpoint takes the backend bearer token likestatus, and 404 for "no current approval" is what the demo and docs rely on./api/jobfails outright when the Broker errors. Fixed: a failed lookup givesapproval: null.view; the lookup's own query selects only the ID.a.integratorand refuses a binding for another Integrator (red:service.rs:803 left: 200 right: 404)./api/jobawaits the job file and then the Broker, one after the other. Pushed back: the second needs the first's result to decide whether to pin.ticklike the field that holds it. Pushed back:page.tickholds the handle oftick, and the pair reads as one thing.Standards, Spec and Security, round 4: no findings; Spec judged criterion 5 met.
Correctness, round 5 (d515e6c..99dabc2, pinned 99dabc2)
no job, or a Broker that could not answer, leaves nothing pinned for good), and the demo keeps all its state in memory by design.forJobpins at that read in any case.pin()calls are not serialised. Pushed back: both store the same text with the ID the Broker returned milliseconds apart; the last write wins with the same answer.status_reports_grant_expiry_and_certificate_once_a_grant_exists(service.rs:801) covers it, and it was red with the guard removed.a rerun that writes the same result again pins the approval current then.Standards, Spec and Security, round 5: no findings; Spec judged criterion 5 met, wanting evidence from
compose_demo.py --verify.Correctness, Standards, Spec and Security, round 6 (the fix for 28 and 35, 99dabc2..81c52af, pinned 81c52af): no findings. Spec wants evidence from
compose_demo.py --verify.Correctness, Standards, Spec and Security, round 7 (81c52af..17a55a6: the image left out
job-approval.js, found by the compose run, not by a review): no findings. Spec judged criterion 5 shown by the passing compose run. Security was read in the session: the diff copies one module into the image and adds a test.Tracking
Epic: none
Spec: none
Ticket: #12 Return grant expiry and approved certificate in the approval status response
Flag: none
🤖 Generated with Claude Code