AuthBox documentation — User guide

Documentation embedded in this build.

The walkthrough, unattended

make walkthrough — no PACE, no MODE — from the run that closed docs/plans/152. This is what the last phase of the composed smoke printed, trimmed to the walkthrough's own lines: the six act headers, the diagnostics an act prints on its way to a fact, and each act's closing line. Every OK line below is a registered claim; a test fails the build if the script that produced it stops saying so.

=== docs/plans/152 — a day in the harbour watch, in six acts over the composition that is already up ===

=== Act 1 — Arrival ===
OK   Act 1: a new joiner enrolled from an invitation with the key born on their own machine,
     and the self page behind the door names the certificate they now hold

=== Act 2 — Need to know ===
     receipt: {"iss":"authboxproxy","sub":"cn=analyst,o=authbox,c=us",
     "issuer_dn":"cn=authbox fixture ca","attributes":["clearance:CONFIDENTIAL"],
     "aud":"records.authbox", ...}
OK   Act 2: one record and two analysts — the cleared one reads it with its marking, the
     other is refused with a receipt, and the sealed copy on both disks opens for the
     cleared one alone

=== Act 3 — Standing agreements ===
     --- the WRITER's own decisions for this ticket ---
     {"seq":380, ...,"outcome":"permit","subject_dn":"cn=operator,o=authbox,c=us",
      "resource":"/admin/v1/requests/req-.../assign","action":"POST", ...}
     {"seq":381, ...,"action":"brokerage:assigned",
      "detail":"assigned request \"req-...\": grant \"grant-...\" gives
      \"cn=liaison,o=authbox,c=us\" mission \"us.authbox.operators.harbour-watch/harbour-drill\"
      until 2026-09-19T04:59:24Z, inert until accepted", ...}
     {"seq":383, ...,"outcome":"deny","subject_dn":"cn=liaison,o=authbox,c=us",
      "action":"POST","detail":"actor signature required: no X-AuthBox-Signature header
      presented", ...}
     {"seq":385, ...,"outcome":"permit","subject_dn":"cn=liaison,o=authbox,c=us",
      "signature_kind":"certificate","signature_verified":true, ...}
     {"seq":386, ...,"action":"brokerage:accept",
      "detail":"accepted request \"req-...\" for mission
      \"us.authbox.operators.harbour-watch/harbour-drill\"; grant \"grant-...\" is live
      until 2026-09-19T04:59:24Z", ...}
OK   Act 3: the analyst asked, the project's admin assigned from the workspace, the analyst
     signed with their own key, the attribute appeared and the project's door admitted them

=== Act 4 — The project ships a service ===
OK   Act 4: the project minted a service identity whose name it never typed, the key was
     born at the delivery and handed over once, it renewed itself with nobody awake, and
     the project took it back

=== Act 5 — Federation ===
OK   Act 5: headquarters answered through the chain from an enclave that cannot dial it,
     and a suspension at the authority refused the analyst at the edge within one poll and
     was lifted again

=== Act 6 — The accreditor ===
     audit export verifies across 1 segment(s), 38 records

     UNBACKED      <runtime>/walkthrough/act6-receipt.jws
                   correlation b5d647bbec679a5d9bd47622a3522f60

     0 matched, 0 contradicted, 1 unbacked, 0 invalid

     an unbacked receipt is not by itself an accusation: this export may simply not
     carry the segment its decision was logged in. Nothing offline can tell that apart
     from a decision that was never logged — see docs/standards/receipt-profile.md.

     these receipts account for 0 of the 22 decision(s) this export records; 22 UNACCOUNTED FOR
OK   Act 6: the accreditor read a history computed from the records, reconciled a receipt
     against the signed export, and opened the evidence register and the OSCAL component
     definition

Two things worth reading in that transcript rather than past it.

Act 3's fourth line is a denial — cn=liaison was refused for want of a signature before the fifth line permits the same operation, signed. That is not a flake: the acceptance endpoint refuses an unsigned attempt first and a signed one second, by design, and the walkthrough's own retry is what produces both lines. A chain reading this export for the first time sees the refusal and the permit both, in order, which is the honest record of what happened rather than a summary of it.

Act 6's verdict is unbacked, not clean, and that is correct. The receipt this act mints describes a decision made an instant after the audit export it reconciles against was sealed. authboxctl receipt reconcile says so in as many words rather than reporting a false match or a false failure — the distinction this whole product exists to keep apart: believing a claim, and checking it.

Back to the tutorial.