Skip to content

feat(broker): An Integrator can read when a grant ends and which certificate was approved - #39

Merged
sodre merged 10 commits into
mainfrom
t3/implement-foresight-12
Nov 21, 2026
Merged

sodre merged 10 commits into
mainfrom
t3/implement-foresight-12

Conversation

@sodre

@sodre sodre commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

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: its sha256, the fingerprint the Companion shows, plus its subject, issuer and expiry). A new approvals/current call 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 creates
status(approval)
  LEFT JOIN approved_grant            # the row outlives the approval's end
  grant row present  -> expires_at_ms, certificate {sha256[, subject, issuer, not_after_ms]}
  no grant row       -> both omitted  # pending, denied, expired/cancelled before approval,
                                      # or the grant record removed by audit retention

demo Integrator
  job.json changes (watchFile, 1 s)  -> pin approvals/current's id for that result
  GET /api/job                       -> { result, approval: status(pinned id) }
  Job page                           -> match if approval.certificate.sha256 == result.fingerprint

Choices the ticket left open, decided here:

  • Which states carry the fields. Approved and replaced approvals carry them, as the ticket asks. So do expired and cancelled ones that had a grant, because the same grant row describes them.
  • expires_at_ms is the approved deadline, not the effective lease deadline. docs/reference/api.md says that a revocation, a renewal or a Gateway lease can end access sooner, and that state says whether the grant is still in force.
  • The leaf's names are kept with the grant. approved_grant gains subject, issuer and not_after, added in place on open without bumping user_version, so an older Broker can still open the store. A grant recorded before this change reports {sha256} only.
  • The names are in encoding order (C=US, O=…, CN=…), as x509-parser prints them, joined with ", ". api.md says so.
  • approvals/current answers 404 for an unknown host or another Integrator's binding. It matches the authenticated Integrator, and returns the same view status does.
  • CI installs Playwright's Chromium before pnpm test, for the demo's new page tests.

Extras for the owner

Evidence

Criterion Ticked Shown by
The Broker returns expires_at_ms and certificate.sha256 for approvals that have a grant, and omits them for approvals that don't yes status_reports_grant_expiry_and_certificate_once_a_grant_exists; authenticated_consent_signing_reconnect_and_revocation (cancelled)
Broker tests cover approved, expired, replaced and pending approvals yes status_reports_grant_expiry_and_certificate_once_a_grant_exists
docs/reference/api.md documents the fields yes docs/reference/api.md, "Read approval status", read by the Spec reviewer in rounds 1, 3 and 4
certificate also carries subject, issuer and not_after_ms, kept with the grant yes status_reports_grant_expiry_and_certificate_once_a_grant_exists; opening_an_older_store_adds_the_leaf_columns_to_existing_grants
The backend can read the current approval without creating one, so the Job page compares against the approval the job ran under yes examples/demo-integrator/compose_demo.py --verify (the wiring, live); the four job-approval.test.js tests (the pinning); status_reports_grant_expiry_and_certificate_once_a_grant_exists (the lookup)
Follow-up in the demo Integrator: countdown, automatic compare without the paste box, screenshot fixtures yes 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.mjs

All six boxes are ticked with tick-criteria.py, after the ticket's section heading was renamed from ## Acceptance to ## Acceptance criteria.

Test Red Green
status_reports_grant_expiry_and_certificate_once_a_grant_exists: pending omits the fields; approved carries them With the handler change reverted: service.rs:707 left: Null right: Object {"sha256": …} ok
Same test: a denied renewal carries no grant fields Handler forced to add certificate for denied: panicked at service.rs:786 ok
Same test: an approval that expired before anyone approved it carries no grant fields Handler forced to add certificate for a grant-less expired: panicked at service.rs:814 ok
Same test: approved deadline equals the Companion's activation deadline, in whole seconds Handler adding 1000 ms: panicked at service.rs:723 ok
Same test: certificate names the leaf's subject, issuer and expiry Before the leaf was persisted: service.rs:732 left: {"sha256": …} right: {"issuer": "CN=Broker integration test CA", "not_after_ms": 4070908800000, "sha256": …, "subject": "CN=Broker integration test user"} ok
Same test: a grant recorded before the change reports {sha256} only Handler adding subject for it: service.rs:850 left: {"sha256": …, "subject": Null} ok
Same test: approvals/current finds the approval, and 404s without creating one With the route removed: panicked at service.rs:654 ok
Same test: approvals/current refuses another Integrator's binding With the guard removed, the query on the authenticated Integrator alone: service.rs:803 left: 200 right: 404 ok
authenticated_consent_signing_reconnect_and_revocation: a cancelled approval keeps its grant's values With the handler change reverted: panicked at service.rs:467 ok
opening_an_older_store_adds_the_leaf_columns_to_existing_grants Before the in-place ALTER: panicked at approvals.rs:489 ok
the Access approved page counts down to the grant deadline Before the countdown: waiting for locator('#access-ends').getByText('14:30 left'), timeout ok
the Job result page compares the fingerprints without a paste box Before the automatic compare: waiting for locator('#match') to be visible, timeout ok
the Job result page says when the job has no approved certificate to compare Before #no-compare existed: failed with a timeout ok
a job keeps the approval that was current when its result landed; a job read before anything noticed it pins the approval current at that read With pinning disabled (every read looks up the current approval): actual: 'B' ok
no job, or a Broker that could not answer, leaves nothing pinned for good Red only as ERR_MODULE_NOT_FOUND before job-approval.js existed ok
a rerun that writes the same result again pins the approval current then With the pin keyed on the text alone: actual: 'A', expected: 'B' ok
the image copies every local module the servers import Against the Dockerfile before 17a55a6: + actual: ['job-approval.js']; the live run had exited with the integrator container exited (1), and node -e "import('./job-approval.js')" in that image printed ERR_MODULE_NOT_FOUND ok

On 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 warnings and cargo fmt --all --check are clean. pnpm test in examples/demo-integrator on 17a55a6: 8 passed, 0 skipped, 0 failed; pnpm lint is clean. node scripts/capture_screenshots.mjs re-rendered access-active (light and dark) and job-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 --verify on 17a55a6, with a Companion built from this branch: exit 0, printing Compose mTLS accepted selected SHA-256 99f4b3e3…5c09 and Job page matched the fingerprint the site received with the approval. It paired, approved, ran the job's curl through the Gateway (the job's own request started the approval), and opened /job, which showed #job-approved with 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/current route and the demo changes. The three approved_grant columns 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_version bump). 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

  1. The retention purge deletes approved_grant while the approval row can survive, so the fields vanish against the docs' promise. Fixed: docs/reference/api.md says the fields are absent once audit retention removes an ended approval's grant record.
  2. The docs said every expired or cancelled approval keeps the fields, but one that ended before a grant has none. Fixed: the docs list those cases as absent.
  3. "Access ends then unless a renewal replaces the grant first" was wrong for revocation and certificate revocation. Fixed: the docs say a revocation, a renewal or a Gateway lease can end access sooner, and state says whether the grant is still in force.
  4. expires_at_ms is 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.
  5. The test tolerated 999 ms between the status deadline and the activation deadline. Fixed: it asserts exact equality.
  6. No test covered an approval that expired with no grant. Fixed: the test lets a renewal's offer lapse and checks that both fields are absent.
  7. The new approve/status helpers 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

  1. The test repeats the post-and-decode chain and the renew call. Pushed back: it matches the inline style of every other test in service.rs.
  2. The query row is a positional 7-tuple. Pushed back: it extends the handler's existing tuple; a struct for one call site adds nothing.
  3. The certificate binding holds a digest. Fixed: renamed to certificate_sha256.
  4. The approve helper takes a bare renewal: bool. Pushed back: two call sites, and the doc comment says what it does.
  5. The local ended holds seconds, while another test's ended holds a state. Fixed: renamed to expired_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)

  1. The Job page compares against the approval the tab remembers, which the job's own request never gives it, so it shows nothing to compare, or the wrong approval after a renewal. Fixed: widened Return grant expiry and approved certificate in the approval status response #12 on the owner's choice; approvals/current finds the job's approval (criterion 5), reviewed in round 4. The same round found compose_demo.py --verify still filling the removed paste box; fixed to expect #job-approved and #match.
  2. The wording when no approval is tracked. Fixed: #no-compare says to approve the request in the Companion and run the job again.
  3. The countdown trusts the browser's clock. Pushed back: it is advisory, and the page re-reads the Broker's state every 5 s.
  4. A local variable shadows show. Fixed: renamed.
  5. The page test duplicates the screenshot script's page server. Pushed back: sharing it would tie the test to a docs script CI does not run.
  6. Two copies of one fingerprint comparison. Fixed: one same computed once.
  7. The docs implied RFC 4514 order for subject and issuer. Fixed: api.md says encoding order, joined with ", ".

Standards, Spec and Security, round 3: no findings; Spec judged both added criteria met.

Correctness, round 4 (9eb4f81..d515e6c)

  1. The page looks up the current approval when it opens, not when the job ran, so a renewal in between changes what it compares. Fixed: widened Return grant expiry and approved certificate in the approval status response #12 on the owner's choice; the Integrator pins the approval when the job's result lands (job-approval.js), reviewed in round 5.
  2. approvals/current checks no permit, and answers 404 where status might answer 403. Pushed back: the endpoint takes the backend bearer token like status, and 404 for "no current approval" is what the demo and docs rely on.
  3. /api/job fails outright when the Broker errors. Fixed: a failed lookup gives approval: null.
  4. An unknown host answers 404 rather than an error naming the host. Pushed back: the host comes from the Integrator's own configuration, and 404 tells the caller no approval exists, which is true.
  5. The lookup repeats the approval view's query. Pushed back: both call one view; the lookup's own query selects only the ID.
  6. The lookup filtered on the caller's Integrator rather than the authenticated one. Fixed: it binds a.integrator and refuses a binding for another Integrator (red: service.rs:803 left: 200 right: 404).
  7. /api/job awaits 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.
  8. The interval's updater is named tick like the field that holds it. Pushed back: page.tick holds the handle of tick, 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)

  1. A job result whose text equals the last one is never pinned again, so a rerun under a renewal keeps the earlier approval. Fixed: widened Return grant expiry and approved certificate in the approval status response #12 on the owner's tick; the pin is keyed on the text and the file's mtime, reviewed in round 6.
  2. A failed or absent pin falls back to the approval current at the next read, and a restart loses every pin. Pushed back: the fallback is the documented, tested behaviour (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.
  3. The file watcher polls every second, so a read can race the pin. Pushed back: it takes a renewal approved within a second of the job's result landing; forJob pins at that read in any case.
  4. Two concurrent 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.
  5. No negative caching while the pinned ID is null. Pushed back: retrying the lookup on the next read is the intended behaviour, and its test asserts it.
  6. No test for the Integrator-mismatch guard. Pushed back: the stranger binding in status_reports_grant_expiry_and_certificate_once_a_grant_exists (service.rs:801) covers it, and it was red with the guard removed.
  7. The Integrator is enforced twice, by the guard and the query. Pushed back: the query alone answered 200 for a stranger binding (finding 25's red); the guard is what refuses it.
  8. No test for an identical rerun after a renewal. Fixed: a rerun that writes the same result again pins the approval current then.
  9. No tests for a lookup failure followed by a renewal, or for a restart. Pushed back: both are finding 29's documented fallback.

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

sodre and others added 10 commits November 20, 2026 03:09
…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>
@sodre
sodre marked this pull request as ready for review November 21, 2026 01:34
@sodre
sodre merged commit 9b06f11 into main Nov 21, 2026
38 checks passed
@sodre sodre mentioned this pull request Nov 21, 2026
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.

Return grant expiry and approved certificate in the approval status response

1 participant