Issue and verify SMART Health Cards and SMART Health Links for patient credential sharing

In-depth guide

Steps

1. To issue a SMART Health Card: package the patient's FHIR data (e.g., immunization Bundle) as a minimized FHIR Bundle (no server URLs, no narrative), compress it with DEFLATE, then sign it as a JWS compact serialization using an ES256 (ECDSA P-256) private key; the resulting JWS string is the SMART Health Card
2. Publish the issuer's public key at a JWKS endpoint at <issuer>/.well-known/jwks.json; the kid in the JWS header must match a key in the JWKS; verifiers will fetch this endpoint to validate signatures
3. To distribute as a file, wrap the JWS string(s) in a JSON object with a 'verifiableCredential' array and save as a .smart-health-card file (MIME type: application/smart-health-card); for QR distribution, split the JWS into chunks and encode each as a numeric QR code
4. To issue a SMART Health Link (SHL): generate a random encryption key, encrypt the payload (FHIR Bundle or .smart-health-card file) with AES-256-GCM, store it at a manifest URL, then encode the SHL URL as shlink:/<base64url-payload> for sharing via QR or hyperlink
5. To verify a SMART Health Card: decode the JWS, fetch the issuer's JWKS, validate the ES256 signature, check the 'exp' claim if present, and parse the vc.credentialSubject.fhirBundle to extract the clinical data
6. For SMART Health Links verification: parse the SHL URL to extract the manifest URL and decryption key, GET the manifest with the SHL-recipient header, then decrypt and decompress each payload file to obtain the FHIR data