Plan: issuing signed level credentials
Implementation plan for Bob Rapp and Ken Johnston. This builds on CREDENTIALS.md. Bob accepted all five recommendations on 19 Nov 2026. Phase 1 uses public TEST keys only; Bob and Ken have agreed on the certificate titles; the signature images have not arrived.
The problem
Every learner who completes a level gets a certificate signed by Bob and Ken. Anyone, such as an employer, must be able to check that it is real in seconds, without contacting us and without seeing the learner's private work. Today:
- Beacon (
aigovops/packages/beacon) signs Ed25519 receipts. Its receipt has no learner, credential or revocation fields, and no permanent issuer key is configured; it falls back to a demo key. - There is no public page anywhere for checking a receipt.
- The course is hosted on GitHub Pages at
aigovops-foundation.github.io/how-ai-works/.
Proposed solution
1. One credential record per learner per level, in an open standard. A JSON record in the Open Badges 3.0 format (W3C Verifiable Credential). Open Badges 3.0 is the free open standard for digital badges, so learners can carry the credential into wallets and onto LinkedIn, and no vendor holds it. It contains only the fields in CREDENTIALS.md: the name the learner chooses, the credential name, the level, the date, the public project title, the reviewing host, the receipt ID and the status URL. No email, quiz answers or project text. It is signed with Ed25519 over RFC 8785 (JCS) canonical JSON. apps/sandbox400 already has JCS and Ed25519 code to reuse. Beacon's sorted-key form is not full JCS, as its own docs say.
2. Two signatures that mean different things.
- Visible: Bob's and Ken's handwritten signature images are printed on the certificate (PDF and PNG, generated from the approved mockup).
- Cryptographic: one Foundation issuer key signs every record. Once per level, Bob and Ken each sign a short, public "signatory authorization" saying the Foundation key issues that level's credential in their names. The verify page shows both. This keeps signing automatic while every certificate still traces back to Bob's and Ken's own approval.
3. A free verify page that works offline. A static page at verify.aigovops.org (the Foundation owns aigovops.org). The page reads the receipt ID from the QR code and checks the signature in the browser. It also checks a signed public status list that holds only receipt IDs and their status (valid, revoked or reissued), in the W3C Bitstring Status List format. It needs no server and no database, and keeps no learner data. It can launch on GitHub Pages at /how-ai-works/verify/ until the domain is pointed.
4. Issuance flow, human-gated.
- The host marks the level project as approved.
- The credential agent builds unsigned records for the cohort and opens a batch for review.
- Bob gives one "issue" yes per batch, the one irreversible click.
- A GitHub Action signs the records with the issuer key, held in 1Password and the Actions secret, and never in the repo. It then renders the certificates and updates the status list.
- Fo emails each learner their certificate PDF and JSON file.
5. Keys and failure handling. The issuer key is created once, in a short key ceremony with Bob present. Its public key is published at verify.aigovops.org/.well-known/ and in the repo. Rotating the key uses Beacon's keys.mjs current/retired model. If the key leaks, we rotate it, mark the affected records reissued and re-sign them. An errata or a credential found to be wrong is handled by revoking or reissuing it, never by silently editing it.
Phases
| Phase | What | Who signs off | Rough time |
|---|---|---|---|
| 0 | Settle the decisions below and obtain signature images | Bob, Ken | Days, on your schedule |
| 1 | Record schema, signer, verify page, status list and tests, all with test keys | Devin builds; Devin Review; Bob merges | 1–2 days |
| 2 | Certificate PDF/PNG renderer from the mockup, with signature images | Bob, Ken approve a proof | 1 day |
| 3 | Key ceremony; publish the public key and the per-level authorizations | Bob present; Bob and Ken sign | 1 hour |
| 4 | Pilot: first Level 100 cohort, end to end | Host marks projects; Bob issues | After the first Thursday cohort |
| 5 | Open Badges wallet export and LinkedIn "Add to profile" link | Bob | 1 day |
Risks
- Degree confusion: names keep to "Certificate" and "Mastery" (see the naming rule in CREDENTIALS.md); every certificate says "Free and open. Every source cited. Human-reviewed."
- Forged images: a picture of a certificate proves nothing. The verify page is the authority, and the certificate says so.
- Privacy: the public status list holds only receipt IDs and status. The learner holds the full record.
- Key loss or leak: a 1Password backup, the rotation and reissue path, and a public key history.
Recorded decisions
| # | Decision | Chosen approach | Recorded state |
|---|---|---|---|
| 1 | Record format | Open Badges 3.0 | Decided by Bob, 19 Nov 2026 |
| 2 | Signing model | Foundation key plus a one-time Bob/Ken authorization per level | Decided by Bob, 19 Nov 2026 |
| 3 | Verify address | verify.aigovops.org; GitHub Pages until the domain is set | Decided by Bob, 19 Nov 2026 |
| 4 | Signature images | One from each, on white (PNG or phone photo) | Awaiting images from Bob and Ken |
| 5 | Signatory titles on certificates | Both “Founder and Co-chair, Review Board” | Bob set the titles and relayed Ken's agreement, 20 Nov 2026 |
| 6 | Verifier address for real records | https://verify.aigovops.org/ itself, served from its own Pages repository (not /verify/ on this site). Real keys and real records are refused for any other base | Decided by Bob, 20 Nov 2026 |
| 7 | Proof suite | eddsa-rdfc-2022, the suite 1EdTech's certification guide lists, replacing eddsa-jcs-2022 before any real issuance | Decided by Bob, 20 Nov 2026 |
| 8 | Learner identifier | Keep the per-record anonymous subject ID; no identifier field. Add a hashed identifier only if the official suite fails without one | Decided by Bob, 20 Nov 2026 |
Phase 1 implementation: apps/credentials/README.md. The QR carries the compressed credential in a URL fragment, not an ID lookup. Public bitstring status lists contain bits, not learner records or receipt IDs. These refine the proposal above.