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:
- 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).
- It prepares the CWT and the bytes to sign: STT-CWT-001…005, STT-ISS-004.
- 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.
- Pain point: The baby has no Taifafeki ID number, so his records would normally stay locked inside the Taifafeki hospital’s system.
- Enabler: A digitally signed QR card travels with the family — no ID number or database lookup needed.
- Policy: Babies born abroad can get a verifiable vaccine record before they have the host country’s civil registration or a national ID — and registering the birth at home still matters.
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.
- Pain point (J2a): Without a check, a forged or mistyped card could quietly become an official record.
- Pain point (J2b): Babies born abroad are invisible to the home health system until civil registration catches up — sometimes months later.
- Enabler (J2a): The phone reads the card offline, and keeps “what the family told us” clearly separate from “what we have verified”.
- Enabler (J2b): An offline form links the baby to his household immediately; it syncs once the phone finds a signal.
- Policy (J2a): Keep a clear line between what families report and what has been verified, and don’t grant trust too early.
- Policy (J2b): Newborns can be registered at home, offline, before civil registration or a national ID exists.
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.
- Pain point (J3a): Clinicians either distrust foreign paper and re-vaccinate, or trust it blindly.
- Pain point (J3b): Countries name and package vaccines differently, so doses get missed or repeated.
- Enabler (J3a): The signing key of Taifafeki is on the shared WHO trust list, so any clinic can check it locally.
- Enabler (J3b): The original code from Taifafeki is kept and the Onesa code is added alongside; the schedule engine calculates what’s due.
- Policy (J3a): Trust is decentralized: a clinic in Onesa verifies a signature from Taifafeki itself, without contacting Taifafeki.
- Policy (J3b): Never overwrite another country’s record: keep the original coding alongside the national one.
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:
- It assembles the IPS and Somsak’s DVCs.
- It encrypts them (STT-VHL-004, STT-VHL-007) behind a passcode-protected manifest with an expiry (STT-VHL-009).
- 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.
- Pain point (J4.0a): Many families share one smartphone; one-app-per-person designs leave them out.
- Pain point (J4.0b): Sending photos or PDFs of records leaks data and can’t be verified by the receiver.
- Enabler (J4.0a): A household wallet on one phone, with a separate health summary for each person.
- Enabler (J4.0b): A Verifiable Health Link: the QR holds only a locked pointer; the data stays home until the passcode is given.
- Policy (J4.0a): Design for shared devices (“One Family, One Phone”) so families with only one phone aren’t left out.
- Policy (J4.0b): Data sovereignty: the record stays in Onesa until the family authorizes someone to open it.
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:
- The viewer verifies the HCERT against Country B’s DSC in its copy of the trust list.
- It requests the manifest by ITI-YY5, signed with HTTP Message Signatures (STT-VHL-005, STT-VHL-006, STT-VHL-008).
- The Onesa gateway checks the passcode, the expiry and the consent, returns the manifest, and logs the access at home (
TrustDemoJ41Access). - The viewer decrypts the IPS and DVCs (STT-VHL-007) (
TrustDemoJ41Received). - 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.
- Pain point: Without the history, the doctor would repeat vaccines or have to guess.
- Enabler: The record is fetched live from Onesa, viewed without being copied, and an access log is sent home.
- Policy: Continuity of care across borders: each country keeps its own records, with no international patient registry and no vendor lock-in. What is agreed regionally is the data model and the trust list, not a shared copy of the data.