User stories

Each story traces to the smart-trust-tools requirements that serve it (scenarios/story-requirements.json); where the HCERT library does not serve a story, the note says what does.

Role I want to So that Requirements
Caregiver Have my son’s birth doses from abroad recognised at home his care does not start over and nothing is repeated STT-VER-001, STT-VER-009, STT-TRU-002
Caregiver Show each family member’s records abroad from our one shared phone, with a passcode I can say aloud a doctor abroad can treat us without paper or an app STD-ACC-001, STT-VHL-001, STT-VHL-002, STT-VHL-004, STT-VHL-007
Caregiver Decide who sees my child’s record, and for how long the record stays at home and I know who has looked STD-ACC-001, STT-VHL-009, STT-VHL-008
Birth clinic vaccinator Print a signed record of each birth dose the family can carry anywhere   STT-PAY-001, STT-PAY-003, STT-ISS-004, STT-COS-001, STT-HC1-001, STT-QR-001
Community health worker Read a foreign vaccination QR offline and register the child with it the clinic sees what was given before the family arrives STT-VER-011, STT-B45-002, STT-CBR-003
Community health worker Refer a child whose foreign record needs checking verification is done by someone who can STT-VER-011
Community health worker Register a newborn into the household offline, before civil registration no newborn in my village is missed, even with no signal STT-PAY-005
Home clinic provider Know whether a foreign certificate is genuine, and why not when it is not   STT-VER-001, STT-VER-002, STT-VER-008, STT-TRU-001
Home clinic provider See which doses are due once the foreign doses are imported I give only what is missing STD-SCH-001
Home clinic provider Keep the foreign vaccine code and add our schedule code beside it, deciding myself when there is no match the other country’s record is never overwritten and the next nurse need not decide again STD-SEM-001
Point-of-care provider Read a visiting child’s summary and vaccinations from a QR the parent shows without installing anything or calling another country STT-VHL-005, STT-VHL-006, STT-VHL-007, STT-VHL-008
Point-of-care provider Know the record I read abroad came from the child’s home country and was not altered I can rely on it as I would on my own clinic’s record STT-VER-001, STT-TRU-002, STT-KID-002

User scenarios

Each step names the requirements of smart-trust-tools it exercises, and the FHIR examples of this guide it produces. The stories are in scenarios/stories.json. Each moment ends with its pain point, what enables it, and the policy point it makes, as the journeys walkthrough presents them.

J1 — Vaccinated and recorded (Taifafeki, birth day)

Precondition: the issuer’s DSC is on the trust list. XXR’s document signer certificate (DSC), issued under XXR’s Country Signing CA (CSCA), was shared with the GDHCN, the Trust Anchor, before any DVC is signed; the GDHCN publishes it as a DID document. Sharing it is not a step of issuing. A DVC signed with a key whose DSC was never shared fails every receiver’s trust-list check (STT-VER-006).

Khamla, a woman from Onesa who works in Taifafeki, gives birth to Somsak on 2025-10-28 at Kesaro Provincial Hospital. He has no Taifafeki identity number. Dr Anan gives the Hep B and BCG birth doses and records them with their WHO PreQual product codes. For each dose, the hospital system does three things:

  1. It builds a DVCMinPreQual payload: STT-PAY-001…005 and STT-PAY-007, with subclaim −6 (STT-SEL-003). No identity document is needed (STT-PAY-005).
  2. It prepares the CWT and the bytes to sign: STT-CWT-001…005, STT-ISS-004.
  3. It has XXR’s key sign them (STT-COS-002, STT-COS-006), then finishes the HC1 text: STT-COS-001, STT-ZIP-001, STT-B45-001, STT-HC1-001, STT-QR-001.

Khamla leaves with two paper DVCs. In the demo: the library tests use the WHO guide’s own two signed HC1 strings (QR Code Generation §12), which verify against the live DEV trust list under the same XXR key. Somsak’s DVC payloads are illustrative. Live issuance in the app uses a TEST-ONLY key (STT-ISS-003), whose DSC is not on the GDHCN list, so its DVCs do not verify in J3.

J2 — Found and registered (Onesa, Somsak is 7 weeks old)

J2a. Khamla has brought Somsak home to Onesa. On a routine visit to Village 04, Khamla’s village, Vilay finds a newborn the Onesa system does not know exists. Her phone has had no signal for weeks. Khamla shows the two cards. The CHW app reads them with read-unverified (STT-VER-011; STT-B45-002, STT-ZIP-002, STT-CBR-003), which needs no trust list. It shows the doses, but checks no signature and saves nothing yet.

J2b. On the CHW app’s newborn form (structured data capture, TrustDemoHouseholdRegistration) she adds Somsak to the Sengmany household (TrustDemoHousehold), with a temporary id. Bounmy confirms the details as head of household. The app saves the doses read from the cards as reported by the family, not verified (TrustDemoJ2HepBReported, TrustDemoJ2BcgReported: primarySource false). Vilay refers Somsak to the district health center (TrustDemoJ2Referral). Everything stays queued on the phone, for 28 days if need be, and syncs when it next reaches a signal.

J3 — A foreign record used for the next vaccine (Lomaru District Health Center, Somsak is 10 weeks old)

Precondition: the DID documents are already loaded. Loading them is not a step of this visit. The clinic may be offline all day, so the EHR fetches nothing during it: its trust store holds the GDHCN DEV trust list as it was last refreshed, including XXR’s DSC DID document (STT-TRU-001, STT-TRU-002, STT-TRU-005). A clinic with no connection of its own refreshes it about weekly, when the CHW visits the base clinic or district health office, where Country B retrieves the list the GDHCN trust anchor distributes. A DSC published after that refresh is not in the clinic’s copy, so its DVC fails the trust-list check (STT-VER-006) until the next refresh.

J3a. Nurse Chanthason opens the referral and scans the QRs. The EHR verifies each DVC offline against that copy (STT-VER-001…009, STT-KID-002), without contacting Taifafeki. Both verify, so it imports them as FHIR Immunizations (TrustDemoJ3HepB, TrustDemoJ3Bcg) with provenance (TrustDemoJ3Verification; STT-VER-007, STT-VER-008), replacing the reported doses of J2. If a DVC fails (a tampered card, say), the EHR names the step and the reason, the doses stay unverified, and the nurse decides by national catch-up policy.

J3b. The Taifafeki Hep B product matches nothing on the national schedule. The EHR keeps the product coding of Taifafeki and adds the schedule coding beside it, from the national map (TrustDemoProductToOnesaEpi). For the Hep B product the map has no entry, so Nurse Chanthason makes the clinical call that it is the schedule’s birth dose (TrustDemoJ3Adjudication), and her decision is added to the map for the next clinic. The schedule (TrustDemoOnesaInfantSchedule) then runs: the birth doses count, and pentavalent 1, bOPV 1 and PCV 1, due at 6 weeks, are overdue at 10 weeks (TrustDemoJ3Recommendation), so Nurse Chanthason gives them that day. Khamla leaves with the date of the next doses (TrustDemoJ3Reminder). Over the year Somsak gets the rest of his doses and measles-rubella at 9 months, in Onesa.

J4.0 — Continuity across a border: one family, one phone (Onesa, 12 months later)

J4.0a. The family plans a trip to Taifafeki. Bounmy’s phone holds the family wallet, with a profile for each of them. Somsak’s summary (TrustDemoJ4Ips) shows six doses: two from Taifafeki, four from Onesa.

Precondition, as in J1: Country B’s DSC, under Country B’s CSCA, is already shared with the GDHCN, the Trust Anchor. That is what lets the clinic in Taifafeki verify the link in J4.1.

J4.0b. For Somsak, Bounmy shares his record with a 4-digit passcode he can say aloud, valid for 14 days. The portal records his consent (TrustDemoJ4Consent), then does three things:

  1. It assembles the IPS and Somsak’s DVCs.
  2. It encrypts them (STT-VHL-004, STT-VHL-007) behind a passcode-protected manifest with an expiry (STT-VHL-009).
  3. It issues the link as an HCERT, with the VHL at key 5 (STT-VHL-001, STT-VHL-002), signed with Country B’s DSC.

The QR holds only a pointer and a key: the record stays in Onesa.

J4.1 — Continuity across a border: a paediatrician in Taifafeki sees the full history (Kesaro, 12 months later)

Precondition, as in J3: the DID documents are already loaded. The clinic viewer’s trust store is a cached copy of the GDHCN trust list, including Country B’s DSC DID document (STT-TRU-001, STT-TRU-002, STT-TRU-005). The clinic refreshes it nightly or hourly, against about weekly at the offline J3 clinic. It does not need to be online to verify: verifying reads the cache and never fetches the list. A DSC published after the last refresh fails the trust-list check (STT-VER-006), naming that reason.

Back where it began, Dr Anan, a paediatrician, sees Somsak at a paediatric clinic in Kesaro. Bounmy shows the QR on his phone and says the passcode. The clinic viewer and the Onesa gateway take five steps:

  1. The viewer verifies the HCERT against Country B’s DSC in its copy of the trust list.
  2. It requests the manifest by ITI-YY5, signed with HTTP Message Signatures (STT-VHL-005, STT-VHL-006, STT-VHL-008).
  3. The Onesa gateway checks the passcode, the expiry and the consent, returns the manifest, and logs the access at home (TrustDemoJ41Access).
  4. The viewer decrypts the IPS and DVCs (STT-VHL-007) (TrustDemoJ41Received).
  5. It shows them to Dr Anan: every dose since the birth, viewed, never copied.

A wrong passcode is refused, and the attempt is still logged in Onesa (TrustDemoJ41WrongPasscode). If the HCERT does not verify (for example, Country B’s DSC is missing from the cached list), there is no digital verification. The clinic names the step and the reason (STT-VER-008), does not follow the VHL, and Dr Anan treats whatever the family can show as he would a paper record.

Edit this page on GitHub