06. Verification

Draft 0.1. Reference implementation: api/verify-receipt.js, api/receipt-proof.js, scripts/verify-receipt-offline.js (copied as spec/verifier/verify-offline.js), frontend/src/utils/receiptSignature.js, frontend/src/pages/VerifyReceiptPage.jsx. Vectors v18, v19.

6.1 Two paths, one algorithm

A receiver holds an artifact (a printed transcript, a PDF, a work sample, a course row) and a receipt id. Verification answers, in order: is this id a real receipt; do the bytes I hold match what was sealed; who signed; was it publicly logged; what tier of claim is this; has it been withdrawn.

The proof file is what the Download proof (JSON) link under the verdict on /verify/<id> saves, and what GET /api/receipt-proof?id=<id> returns. The reference verifier and the conformance vectors are published at /spec/verifier under Apache-2.0, so obtaining the offline path takes no account, no clone, and no permission.

A receiver who does not trust the online answer MUST be able to reproduce it offline from public inputs. That is the design test for every field on the verify payload.

6.2 The algorithm, step by step

Step 0. Classify the id. Match ^(tr|cr|ws|wn|wl|att|kb)_[a-f0-9]{12}$ (case-insensitive). An id with no known prefix falls through to the legacy lookups (event receipts by uuid, consent receipts, plan receipts) and otherwise 404s. ecr_ and tl_ never resolve here (chapter 02).

Step 1. Hash integrity (the receiver's own step). Compute SHA-256 over the artifact you hold, exactly as the issuing surface computed it (the whole transcript issuance payload for tr_; the canonical hash-domain object per chapter 02 for the others). Compare with the receipt's hash. A mismatch means the bytes you hold are not the bytes that were sealed. No server can do this step for you; the verifier's --sha256 flag performs the comparison against the logged leaf.

Step 2. Existence and state. Online: GET /api/verify-receipt?id=. verified: true means the id resolves in the operator's ledger; it does not mean the claims are true. If the payload carries revoked: true, the family withdrew it: stop, and treat the artifact as withdrawn (the id, kind, dates, and hash remain so a receiver holding the link learns the truth rather than hitting a memory hole).

Step 3. Identity of content. The receipt id MUST equal the prefix plus the first 12 hex of the receipt's sha256. A receiver holding the artifact MAY re-derive both from the canonical hash domain (vectors v04 to v08) and MUST treat a mismatch as a forged or corrupted receipt.

Step 4. Signatures.

• Family signature (if issuer_signature is present): verify 'eformogi-receipt-sig-v1:' + leaf_payload against issuer_signature.public_jwk, in the receiver's own runtime; render the verdict honestly (chapter 04, section 4.5). A receiver SHOULD additionally check that public_jwk matches the kb_ binding at issuer_signature.kb_receipt_id (resolvable at /verify/kb_<id> and provable in the log), and that key_established_at precedes issued_at. The reference verifier does the signature check and derives did:key from public_jwk, requiring it to equal key_id; resolving the kb_ receipt itself needs a second proof file and is still planned.

A verifier MUST NOT fail a receipt because key_established_at is later than issued_at. issued_at is the moment the family sealed the record, and it legitimately precedes the key in at least two ordinary cases: a guest issues a record before having an account and republishes it later with the original issued_at, and a family's first signed receipt is stamped before its signing key is minted. The ordering is worth showing a receiver and worth nothing as a verdict, so an implementation SHOULD report it as an advisory note. A tolerance window is the wrong fix; the gap is weeks. The reference client (frontend/src/utils/receiptSignature.js) verifies against the served public_jwk only; the kb_ join is done server-side when the payload is built.

• Organization countersignature on attestations (if org_countersig is present): verify 'eformogi-witness-countersig-v1:' + <att_ leaf> against the DID document key.
• Absence of a signature is not a failure; it means "verifies by integrity alone".

Step 5. Log inclusion. Fetch GET /api/receipt-proof?id= (or use the proof file you hold), then run the four checks the reference verifier runs, in order, all of which MUST pass:

1. (optional, with --sha256) the artifact hash you computed equals sha256 inside leaf_payload;
2. leaf_hash == SHA256(0x00 || leaf_payload);
3. the audit path folds from leaf_hash at leaf_index in a tree of sth.tree_size leaves to sth.root_hash (chapter 05, section 5.4);
4. sth.signature verifies under 'eformogi-sth-v1:' against the organization key.

Two further checks run when the proof carries issuer_signature: the family signature of step 4 over the same leaf bytes, and the did:key derivation of key_id from public_jwk. Both are skipped, not failed, when the receipt was not signed with a family key. The key-establishment ordering prints as an advisory note and never changes the verdict. Vectors v21 (a real proof with a valid family signature: all five checks pass) and v22 (the same proof with one character of that signature flipped: refused) pin this.

status: "pending" means no head covers the leaf yet: the verifier exits 1 and says so; try again after the next daily head. Vector v18 passes all four; v19 (one flipped path element) fails at check 3.

Step 6. Tier display. Render the family's tier_counts chips with the labels of chapter 03, section 3.6, muting any mentor or receiver chip the ledger does not corroborate and suffixing it "issuer-declared". Render every attestation with its self-declared fields, its ceremony observations, and its dispute door. Where a witness's signed_grade differs from family_stated_grade, render both.

Step 7. Say what was proved. The tr_, cr_, and ws_ verify surfaces MUST carry a "what this verification means" paragraph and a "what this verification does NOT mean" paragraph (section 6.6). Gaps recorded against the reference implementation: the kb_, wn_, and wl_ pages do not carry the paired paragraphs, and a witnessed ws_ page replaces the "does NOT mean" heading with "Trust ladder: rung 2 reached." followed by the caveat text; extending the pair to every surface and keeping the heading stable when witnessed is planned.

6.3 Verify payloads by kind

Common to every found receipt: verified: true, kind, id, issued_by: "Eformogi". Never returned: student or family identity beyond what the family printed, org or counselor names or emails, narrative text, file paths, or raw metadata blobs.

Attestation entries inside attestations[] carry the same signer and ceremony fields as the attestation kind, minus the target context.

6.4 Exact error semantics

GET /api/verify-receipt:

Headers on keyed calls: X-Verify-Quota-Plan, X-Verify-Quota-Limit, X-Verify-Quota-Used. A present-but-invalid organization key is never an error: it falls back to public attribution so a bad key can never break a free verify. self=1 marks the issuing device viewing its own receipt and suppresses view counting and notification; it can only undercount.

GET /api/receipt-proof:

Reference verifier exit codes: 0 verified or verdict matched; 1 a step failed, the proof is pending, or a vector's verdict mismatched; 2 usage error or unreadable input.

6.4.1 The proof file

This is the whole offline input. It contains no personal data by construction: the leaf grammar is four fields (chapter 02), and the signature block is the public half of a key whose establishment is already a public kb_ receipt.

A pending response carries status: "pending", leaf_index, next_sth, leaf_payload, leaf_hash, and issuer_signature when present. It is enough to check a family signature immediately; it is not enough to prove inclusion, and the verifier refuses rather than implying otherwise.

The sth object MUST be the bytes that were signed, with the signature appended. An implementation that rebuilds it from typed database columns will re-serialize timestamps and break every offline check, which is why the reference implementation stores and returns the signed body verbatim.

6.5 Online versus offline capabilities

6.6 What this does not prove (the verify page's own words)

The transcript page: "The family issued this transcript through Eformogi. The SHA-256 above was computed at issuance over the entire transcript content. If the printed document you are reading matches the hash, no field has been altered since the family sealed it. The family, not the school, is the records office of record." And: "This is a self-issued, family-attested transcript. The hash proves the bytes haven't changed since issuance; it does not, by itself, prove the underlying claims were evaluated by a third party. Receivers who need third-party-evaluated or issuer-of-record records should ask the family for the linked evidence. The per-course signature chips show who put their name on each row rather than promoting any row to a rank Eformogi cannot award."

The work-sample page, unwitnessed: "This is a self-attested work sample. The hash proves the entry hasn't changed since sealing; it does not, by itself, prove the work was evaluated by a third party." Witnessed: "Each signature is hashed against this same receipt id; signatures cannot be silently altered. Receivers should verify each signer's identity independently; Eformogi does not gatekeep evaluator legitimacy."

The course page: "The grade above is what the family wrote down. Each co-signature below is a separate signed claim from a third party who reviewed the course; where their attested grade differs, both are rendered openly."

An implementation of this specification MUST carry equivalent text on every verify surface and MUST NOT describe a Record as "verified" without the qualifier of what was verified.