vet-data-utils-ts 0.5.6 → 0.5.8

package/README.md

@@ -1,5 +1,35 @@
 # vet-data-utils-ts
 
+## Veterinary immunization credentials
+
+`buildVeterinaryImmunization(...)` creates a FHIR R4 `Immunization` with the
+animal in `patient` and the veterinarian's real `PractitionerRole` in
+`performer.actor`. The caller must supply a governed vaccine coding selected
+for the animal species, jurisdiction and current terminology release; this
+package does not guess a rabies or medicinal-product code.
+
+`prepareSmartHealthCard(...)` minimizes a FHIR Bundle, serializes it
+deterministically and returns the exact raw-DEFLATE ES256 signing input. The
+tenant issuer signs that input with its dedicated P-256 credential key and
+publishes the matching public JWK at `iss + /.well-known/jwks.json`.
+`encodeSmartHealthCardQr(...)` then produces standard `shc:/` numeric QR data.
+
+`encodePostQuantumCompanionProofUri(...)` carries an RFC 7797 detached ML-DSA
+JWS as `pqc:/...`. This is a VetChain transition transport, not part of the
+SMART Health Cards standard. `encodePostQuantumCompanionProofQr(...)` applies
+the same two-decimal-digits-per-JWS-character encoding used by SHC, defaults to
+two numbered large QR labels, and never repeats the external payload. Each
+attester signs the exact uncompressed SHC payload bytes; verification therefore
+requires both QR sets.
+
+`buildSmartHealthCardPayloadReferences(...)` returns two deliberately distinct
+SHA3-384 identifiers over those exact canonical bytes: a
+`urn:multibase:z...` multihash for exact ledger lookup and a base58btc CIDv1
+with the `raw` codec for content-addressed retrieval. The IHC print projection
+shows FHIR `Immunization.occurrenceDateTime`, `vaccineCode` and
+`protocolApplied.targetDisease`. Its issuer-supplied validity interval is not
+FHIR `Immunization.expirationDate`, which means vaccine-batch expiry.
+
 Development and releases follow the mandatory
 [`local-first TDD and release contract`](docs/LOCAL_FIRST_RELEASE_CONTRACT.md).
 

package/THIRD_PARTY_NOTICES.md

@@ -11,3 +11,9 @@ The generated ISO jurisdiction catalogue is derived from Debian `iso-codes`
 
 The generated catalogue may be replaced or updated independently by running
 `npm run update:iso-jurisdictions` against the version pinned in that script.
+
+SMART Health Card payloads use `pako` for browser-safe RFC 1951 raw DEFLATE:
+
+- Source: https://github.com/nodeca/pako
+- Copyright: Vitaly Puzrin and Andrey Tupitsin
+- License: MIT

package/dist/immunization.d.ts

@@ -0,0 +1,50 @@
+export type FhirCoding = Readonly<{
+    system: string;
+    code: string;
+    version?: string;
+    display?: string;
+}>;
+export type FhirCodeableConcept = Readonly<{
+    coding: readonly FhirCoding[];
+    text?: string;
+}>;
+export type VeterinaryImmunizationInput = Readonly<{
+    identifier?: Readonly<{
+        system?: string;
+        value: string;
+    }>;
+    animalReference: string;
+    occurrenceDateTime: string;
+    vaccineCode: FhirCodeableConcept;
+    performerPractitionerRoleReference: string;
+    primarySource?: boolean;
+    lotNumber?: string;
+    expirationDate?: string;
+    manufacturerReference?: string;
+    site?: FhirCodeableConcept;
+    route?: FhirCodeableConcept;
+    doseQuantity?: Readonly<{
+        value: number;
+        unit?: string;
+        system?: string;
+        code?: string;
+    }>;
+    protocolApplied?: readonly Readonly<{
+        series?: string;
+        doseNumberPositiveInt?: number;
+        seriesDosesPositiveInt?: number;
+        targetDisease?: readonly FhirCodeableConcept[];
+    }>[];
+}>;
+export type VeterinaryImmunizationR4 = Readonly<Record<string, unknown> & {
+    resourceType: 'Immunization';
+    status: 'completed';
+}>;
+/**
+ * Builds the FHIR R4 Immunization recorded by a veterinary professional.
+ *
+ * Vaccine coding is deliberately supplied by the caller: the applicable code
+ * system and allowed vaccines depend on species, jurisdiction and the active
+ * terminology release. This helper never guesses a rabies or product code.
+ */
+export declare function buildVeterinaryImmunization(input: Partial<VeterinaryImmunizationInput>): VeterinaryImmunizationR4;

package/dist/immunization.js

@@ -0,0 +1,48 @@
+function required(value, errorCode) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(errorCode);
+    return value.trim();
+}
+function validateCodeableConcept(value) {
+    if (!value || typeof value !== 'object')
+        throw new TypeError('veterinary_immunization_vaccine_coding_required');
+    const coding = value.coding;
+    if (!Array.isArray(coding) || coding.length === 0 || coding.some(item => {
+        if (!item || typeof item !== 'object')
+            return true;
+        const candidate = item;
+        return typeof candidate.system !== 'string' || !candidate.system.trim()
+            || typeof candidate.code !== 'string' || !candidate.code.trim();
+    }))
+        throw new TypeError('veterinary_immunization_vaccine_coding_required');
+}
+/**
+ * Builds the FHIR R4 Immunization recorded by a veterinary professional.
+ *
+ * Vaccine coding is deliberately supplied by the caller: the applicable code
+ * system and allowed vaccines depend on species, jurisdiction and the active
+ * terminology release. This helper never guesses a rabies or product code.
+ */
+export function buildVeterinaryImmunization(input) {
+    const animalReference = required(input.animalReference, 'veterinary_immunization_animal_reference_required');
+    const performerReference = required(input.performerPractitionerRoleReference, 'veterinary_immunization_performer_practitioner_role_required');
+    const occurrenceDateTime = required(input.occurrenceDateTime, 'veterinary_immunization_occurrence_required');
+    validateCodeableConcept(input.vaccineCode);
+    return {
+        resourceType: 'Immunization',
+        ...(input.identifier ? { identifier: [{ ...input.identifier }] } : {}),
+        status: 'completed',
+        vaccineCode: input.vaccineCode,
+        patient: { reference: animalReference },
+        occurrenceDateTime,
+        primarySource: input.primarySource ?? true,
+        performer: [{ actor: { reference: performerReference } }],
+        ...(input.lotNumber ? { lotNumber: input.lotNumber } : {}),
+        ...(input.expirationDate ? { expirationDate: input.expirationDate } : {}),
+        ...(input.manufacturerReference ? { manufacturer: { reference: input.manufacturerReference } } : {}),
+        ...(input.site ? { site: input.site } : {}),
+        ...(input.route ? { route: input.route } : {}),
+        ...(input.doseQuantity ? { doseQuantity: input.doseQuantity } : {}),
+        ...(input.protocolApplied ? { protocolApplied: input.protocolApplied } : {}),
+    };
+}

package/dist/index.d.ts

@@ -6,9 +6,12 @@ export * from './digital-twin.js';
 export * from './emergency.js';
 export * from './financial.js';
 export * from './group.js';
+export * from './immunization.js';
+export * from './international-health-card.js';
 export * from './iso-jurisdictions.js';
 export * from './organization-application.js';
 export * from './payment.js';
 export * from './research-study.js';
 export * from './sectors.js';
+export * from './shc.js';
 export * from './veterinary-sections.js';

package/dist/index.js

@@ -6,9 +6,12 @@ export * from './digital-twin.js';
 export * from './emergency.js';
 export * from './financial.js';
 export * from './group.js';
+export * from './immunization.js';
+export * from './international-health-card.js';
 export * from './iso-jurisdictions.js';
 export * from './organization-application.js';
 export * from './payment.js';
 export * from './research-study.js';
 export * from './sectors.js';
+export * from './shc.js';
 export * from './veterinary-sections.js';

package/dist/international-health-card.d.ts

@@ -0,0 +1,34 @@
+import { type SmartHealthCardPayloadReferences } from './shc.js';
+export type InternationalHealthCardCodedValue = Readonly<{
+    system: string;
+    code: string;
+    display?: string;
+}>;
+export type InternationalHealthCardVaccination = Readonly<{
+    resourceType: 'Immunization';
+    administeredAt: string;
+    validFrom: string;
+    validUntil: string;
+    product: InternationalHealthCardCodedValue;
+    targetDiseases: readonly InternationalHealthCardCodedValue[];
+    authorOrganizationUrn: string;
+    /** FHIR Immunization.expirationDate: expiry of the vaccine batch, not credential validity. */
+    vaccineBatchExpiresOn?: string;
+}>;
+export type InternationalHealthCardPrintData = Readonly<{
+    vaccination: InternationalHealthCardVaccination;
+    payloadReferences: SmartHealthCardPayloadReferences;
+}>;
+/**
+ * Projects human-readable IHC data from the authoritative FHIR R4 resource.
+ * `validFrom` and `validUntil` are credential/travel-policy dates supplied by
+ * the issuer; FHIR `Immunization.expirationDate` remains the vaccine batch
+ * expiry and is never reused as the validity end.
+ */
+export declare function buildInternationalHealthCardPrintData(input: Readonly<{
+    authoritativeBundle: Record<string, unknown>;
+    validFrom: string;
+    validUntil: string;
+    authorOrganizationUrn: string;
+    payloadBytes: Uint8Array;
+}>): InternationalHealthCardPrintData;

package/dist/international-health-card.js

@@ -0,0 +1,68 @@
+import { buildSmartHealthCardPayloadReferences } from './shc.js';
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function requiredText(value, error) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(error);
+    return value.trim();
+}
+function firstCoding(value, error) {
+    const concept = record(value);
+    const coding = Array.isArray(concept?.coding) ? concept.coding.map(record).find(Boolean) : undefined;
+    if (!coding)
+        throw new TypeError(error);
+    const system = requiredText(coding.system, error);
+    const code = requiredText(coding.code, error);
+    const display = typeof coding.display === 'string' && coding.display.trim()
+        ? coding.display.trim()
+        : typeof concept?.text === 'string' && concept.text.trim() ? concept.text.trim() : undefined;
+    return { system, code, ...(display ? { display } : {}) };
+}
+function targetDiseases(immunization) {
+    const protocols = Array.isArray(immunization.protocolApplied) ? immunization.protocolApplied : [];
+    return protocols.flatMap(protocolValue => {
+        const protocol = record(protocolValue);
+        const diseases = Array.isArray(protocol?.targetDisease) ? protocol.targetDisease : [];
+        return diseases.map(disease => firstCoding(disease, 'international_health_card_target_disease_coding_required'));
+    });
+}
+/**
+ * Projects human-readable IHC data from the authoritative FHIR R4 resource.
+ * `validFrom` and `validUntil` are credential/travel-policy dates supplied by
+ * the issuer; FHIR `Immunization.expirationDate` remains the vaccine batch
+ * expiry and is never reused as the validity end.
+ */
+export function buildInternationalHealthCardPrintData(input) {
+    const entries = Array.isArray(input.authoritativeBundle?.entry) ? input.authoritativeBundle.entry : [];
+    const immunization = entries
+        .map(entry => record(record(entry)?.resource))
+        .find(resource => resource?.resourceType === 'Immunization' && resource.status === 'completed');
+    if (!immunization)
+        throw new TypeError('international_health_card_completed_immunization_required');
+    const validFrom = requiredText(input.validFrom, 'international_health_card_valid_from_required');
+    const validUntil = requiredText(input.validUntil, 'international_health_card_valid_until_required');
+    if (Number.isNaN(Date.parse(validFrom)) || Number.isNaN(Date.parse(validUntil))
+        || Date.parse(validFrom) > Date.parse(validUntil)) {
+        throw new TypeError('international_health_card_validity_invalid');
+    }
+    const authorOrganizationUrn = requiredText(input.authorOrganizationUrn, 'international_health_card_author_organization_urn_required');
+    if (!/^urn:cds-[a-z]{2}(?:-[a-z0-9]{2,3})?:v[1-9][0-9]*:organization:[a-z][a-z0-9-]*:[^:]+$/i.test(authorOrganizationUrn)) {
+        throw new TypeError('international_health_card_author_organization_urn_invalid');
+    }
+    return {
+        vaccination: {
+            resourceType: 'Immunization',
+            administeredAt: requiredText(immunization.occurrenceDateTime, 'international_health_card_occurrence_required'),
+            validFrom,
+            validUntil,
+            product: firstCoding(immunization.vaccineCode, 'international_health_card_vaccine_coding_required'),
+            targetDiseases: targetDiseases(immunization),
+            authorOrganizationUrn,
+            ...(typeof immunization.expirationDate === 'string' && immunization.expirationDate.trim()
+                ? { vaccineBatchExpiresOn: immunization.expirationDate.trim() }
+                : {}),
+        },
+        payloadReferences: buildSmartHealthCardPayloadReferences(input.payloadBytes),
+    };
+}

package/dist/shc.d.ts

@@ -0,0 +1,73 @@
+export declare const SmartHealthCardQrPrefix: "shc:/";
+export declare const PostQuantumCompanionProofPrefix: "pqc:/";
+export declare const SmartHealthCardMaxSingleQrLength = 1195;
+export declare const SmartHealthCardMaxQrChunkBodyLength = 1191;
+export declare const PostQuantumCompanionProofDefaultQrCount = 2;
+export type PostQuantumCompanionProofQrOptions = Readonly<{
+    /** Exact number of companion QR labels produced per detached proof. Defaults to two. */
+    qrCount?: number;
+}>;
+export type SmartHealthCardPayloadReferences = Readonly<{
+    /** Exact SHA3-384 multihash encoded as base58btc and wrapped for ledger lookup. */
+    multihashUrn: string;
+    /** CIDv1(raw, SHA3-384) encoded as base58btc for content-addressed retrieval. */
+    cidV1: string;
+}>;
+export type SmartHealthCardPayload = Readonly<{
+    iss: string;
+    nbf: number;
+    vc: Readonly<{
+        type: readonly string[];
+        credentialSubject: Readonly<{
+            fhirVersion: string;
+            fhirBundle: Record<string, unknown>;
+        }>;
+    }>;
+}>;
+export type PreparedSmartHealthCard = Readonly<{
+    protectedHeader: Readonly<{
+        alg: 'ES256';
+        zip: 'DEF';
+        kid: string;
+    }>;
+    payload: SmartHealthCardPayload;
+    payloadBytes: Uint8Array;
+    encodedHeader: string;
+    encodedPayload: string;
+    signingInput: string;
+    signingBytes: Uint8Array;
+}>;
+/** Applies the payload-size rules required by the SMART Health Cards framework. */
+export declare function minimizeFhirBundleForSmartHealthCard(input: Record<string, unknown>): Record<string, unknown>;
+/** Prepares the exact raw-DEFLATE compact-JWS input to be signed by an external ES256 issuer key. */
+export declare function prepareSmartHealthCard(input: Readonly<{
+    issuer: string;
+    notBefore: number;
+    kid: string;
+    fhirVersion: string;
+    fhirBundle: Record<string, unknown>;
+    additionalTypes?: readonly string[];
+}>): PreparedSmartHealthCard;
+export declare function assembleSmartHealthCardJws(prepared: Pick<PreparedSmartHealthCard, 'encodedHeader' | 'encodedPayload'>, signatureBase64Url: string): string;
+/**
+ * Builds both project-supported base58btc references over the exact canonical
+ * SHC payload bytes. The multihash URN is a ledger lookup key; the CID is a
+ * content identifier. They are deliberately not aliases.
+ */
+export declare function buildSmartHealthCardPayloadReferences(payloadBytes: Uint8Array): SmartHealthCardPayloadReferences;
+/** Encodes one compact SHC JWS into one or more standard numeric QR payloads. */
+export declare function encodeSmartHealthCardQr(compactJws: string): readonly string[];
+/** Reassembles standard SHC QR payloads regardless of scan order. */
+export declare function decodeSmartHealthCardQr(qrValues: readonly string[]): string;
+/** Encodes an RFC 7797 ML-DSA detached JWS as the version-one `pqc:/` companion transport. */
+export declare function encodePostQuantumCompanionProofUri(detachedJws: string): string;
+export declare function decodePostQuantumCompanionProofUri(uri: string): string;
+/**
+ * Encodes an ML-DSA detached JWS using the same two-decimal-digits-per-JWS-
+ * character technique as SHC. The external SHC payload is never repeated.
+ */
+export declare function encodePostQuantumCompanionProofQr(detachedJws: string, options?: PostQuantumCompanionProofQrOptions): readonly string[];
+/** Reassembles one complete detached proof regardless of companion QR scan order. */
+export declare function decodePostQuantumCompanionProofQr(qrValues: readonly string[]): string;
+/** Returns the exact uncompressed payload bytes that every detached companion proof verifies. */
+export declare function decodeSmartHealthCardPayloadBytes(compactJws: string): Uint8Array;

package/dist/shc.js

@@ -0,0 +1,268 @@
+import { canonicalizeFhirResource } from 'gdc-common-utils-ts/utils/fhir-cid';
+import { Content } from 'gdc-common-utils-ts/utils/content';
+import { buildRawCidV1FromUtf8String } from 'gdc-common-utils-ts/utils/multiformat-profile';
+import { encodeMultibaseSha3 } from 'gdc-common-utils-ts/utils/multibasehash';
+import { deflateRaw, inflateRaw } from 'pako';
+export const SmartHealthCardQrPrefix = 'shc:/';
+export const PostQuantumCompanionProofPrefix = 'pqc:/';
+export const SmartHealthCardMaxSingleQrLength = 1195;
+export const SmartHealthCardMaxQrChunkBodyLength = 1191;
+export const PostQuantumCompanionProofDefaultQrCount = 2;
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function nonEmptyString(value, errorCode) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(errorCode);
+    return value.trim();
+}
+function collectBundleReferences(bundle) {
+    const references = new Map();
+    const entries = Array.isArray(bundle.entry) ? bundle.entry : [];
+    entries.forEach((entry, index) => {
+        if (!isRecord(entry) || !isRecord(entry.resource))
+            return;
+        const shortReference = `resource:${index}`;
+        if (typeof entry.fullUrl === 'string')
+            references.set(entry.fullUrl, shortReference);
+        if (typeof entry.resource.resourceType === 'string' && typeof entry.resource.id === 'string') {
+            references.set(`${entry.resource.resourceType}/${entry.resource.id}`, shortReference);
+        }
+    });
+    return references;
+}
+function minimizeValue(value, references, resourceRoot = false) {
+    if (Array.isArray(value))
+        return value.map(item => minimizeValue(item, references));
+    if (!isRecord(value))
+        return value;
+    const output = {};
+    const isResource = resourceRoot || typeof value.resourceType === 'string';
+    const isCoding = typeof value.system === 'string' && typeof value.code === 'string';
+    const isCodeableConcept = Array.isArray(value.coding);
+    for (const [key, child] of Object.entries(value)) {
+        if (isResource && (key === 'id' || key === 'text'))
+            continue;
+        if (isResource && key === 'meta') {
+            if (isRecord(child) && Array.isArray(child.security)) {
+                output.meta = { security: minimizeValue(child.security, references) };
+            }
+            continue;
+        }
+        if (isCoding && key === 'display')
+            continue;
+        if (isCodeableConcept && key === 'text')
+            continue;
+        if (key === 'reference' && typeof child === 'string' && references.has(child)) {
+            output.reference = references.get(child);
+            continue;
+        }
+        output[key] = minimizeValue(child, references);
+    }
+    return output;
+}
+/** Applies the payload-size rules required by the SMART Health Cards framework. */
+export function minimizeFhirBundleForSmartHealthCard(input) {
+    if (input.resourceType !== 'Bundle')
+        throw new TypeError('shc_fhir_bundle_required');
+    const references = collectBundleReferences(input);
+    const minimized = minimizeValue(input, references, true);
+    const entries = Array.isArray(minimized.entry) ? minimized.entry : [];
+    minimized.entry = entries.map((entry, index) => isRecord(entry)
+        ? { ...entry, fullUrl: `resource:${index}` }
+        : entry);
+    return JSON.parse(canonicalizeFhirResource(minimized, {
+        stripMetaVersionId: true,
+        stripNarrativeText: true,
+        stripNestedElementIds: true,
+    }));
+}
+/** Prepares the exact raw-DEFLATE compact-JWS input to be signed by an external ES256 issuer key. */
+export function prepareSmartHealthCard(input) {
+    const issuer = nonEmptyString(input.issuer, 'shc_issuer_required');
+    if (!issuer.startsWith('https://') || issuer.endsWith('/'))
+        throw new TypeError('shc_issuer_https_without_trailing_slash_required');
+    if (!Number.isInteger(input.notBefore) || input.notBefore < 0)
+        throw new TypeError('shc_not_before_seconds_required');
+    const kid = nonEmptyString(input.kid, 'shc_kid_required');
+    const fhirVersion = nonEmptyString(input.fhirVersion, 'shc_fhir_version_required');
+    const payload = {
+        iss: issuer,
+        nbf: input.notBefore,
+        vc: {
+            type: ['https://smarthealth.cards#health-card', ...(input.additionalTypes ?? [])],
+            credentialSubject: {
+                fhirVersion,
+                fhirBundle: minimizeFhirBundleForSmartHealthCard(input.fhirBundle),
+            },
+        },
+    };
+    const protectedHeader = { alg: 'ES256', zip: 'DEF', kid };
+    const encodedHeader = Content.objectToRawBase64UrlSafe(protectedHeader);
+    const canonicalPayload = canonicalizeFhirResource(payload, {
+        stripMetaVersionId: false,
+    });
+    const payloadBytes = Content.stringToBytesUTF8(canonicalPayload);
+    const encodedPayload = Content.bytesToRawBase64UrlSafe(deflateRaw(payloadBytes));
+    const signingInput = `${encodedHeader}.${encodedPayload}`;
+    return {
+        protectedHeader,
+        payload: JSON.parse(canonicalPayload),
+        payloadBytes,
+        encodedHeader,
+        encodedPayload,
+        signingInput,
+        signingBytes: Content.stringToBytesUTF8(signingInput),
+    };
+}
+export function assembleSmartHealthCardJws(prepared, signatureBase64Url) {
+    const signature = nonEmptyString(signatureBase64Url, 'shc_signature_required');
+    if (!/^[A-Za-z0-9_-]+$/.test(signature))
+        throw new TypeError('shc_signature_base64url_required');
+    return `${prepared.encodedHeader}.${prepared.encodedPayload}.${signature}`;
+}
+function encodeNumericBody(value) {
+    return [...value].map(character => {
+        const encoded = character.charCodeAt(0) - 45;
+        if (encoded < 0 || encoded > 99)
+            throw new TypeError('shc_jws_character_invalid');
+        return encoded.toString().padStart(2, '0');
+    }).join('');
+}
+function decodeNumericBody(value) {
+    if (!value || value.length % 2 !== 0 || !/^\d+$/.test(value))
+        throw new TypeError('shc_qr_numeric_body_invalid');
+    let decoded = '';
+    for (let index = 0; index < value.length; index += 2) {
+        const pair = Number(value.slice(index, index + 2));
+        if (pair > 77)
+            throw new TypeError('shc_qr_numeric_pair_invalid');
+        decoded += String.fromCharCode(pair + 45);
+    }
+    return decoded;
+}
+/**
+ * Builds both project-supported base58btc references over the exact canonical
+ * SHC payload bytes. The multihash URN is a ledger lookup key; the CID is a
+ * content identifier. They are deliberately not aliases.
+ */
+export function buildSmartHealthCardPayloadReferences(payloadBytes) {
+    if (!(payloadBytes instanceof Uint8Array) || payloadBytes.length === 0) {
+        throw new TypeError('shc_payload_bytes_required');
+    }
+    const payloadText = Content.bytesToStringUTF8(payloadBytes);
+    return {
+        multihashUrn: `urn:multibase:${encodeMultibaseSha3(payloadBytes, 384)}`,
+        cidV1: buildRawCidV1FromUtf8String(payloadText),
+    };
+}
+/** Encodes one compact SHC JWS into one or more standard numeric QR payloads. */
+export function encodeSmartHealthCardQr(compactJws) {
+    const jws = nonEmptyString(compactJws, 'shc_compact_jws_required');
+    if (jws.length <= SmartHealthCardMaxSingleQrLength)
+        return [`${SmartHealthCardQrPrefix}${encodeNumericBody(jws)}`];
+    const chunkCount = Math.ceil(jws.length / SmartHealthCardMaxQrChunkBodyLength);
+    const chunkLength = Math.ceil(jws.length / chunkCount);
+    return Array.from({ length: chunkCount }, (_, index) => {
+        const chunk = jws.slice(index * chunkLength, (index + 1) * chunkLength);
+        return `${SmartHealthCardQrPrefix}${index + 1}/${chunkCount}/${encodeNumericBody(chunk)}`;
+    });
+}
+/** Reassembles standard SHC QR payloads regardless of scan order. */
+export function decodeSmartHealthCardQr(qrValues) {
+    if (!Array.isArray(qrValues) || qrValues.length === 0)
+        throw new TypeError('shc_qr_required');
+    if (qrValues.length === 1 && /^shc:\/\d+$/.test(qrValues[0])) {
+        return decodeNumericBody(qrValues[0].slice(SmartHealthCardQrPrefix.length));
+    }
+    const chunks = qrValues.map(value => {
+        const match = /^shc:\/(\d+)\/(\d+)\/(\d+)$/.exec(value);
+        if (!match)
+            throw new TypeError('shc_qr_chunk_invalid');
+        return { index: Number(match[1]), count: Number(match[2]), value: decodeNumericBody(match[3]) };
+    });
+    const expectedCount = chunks[0].count;
+    if (expectedCount !== chunks.length
+        || chunks.some(chunk => chunk.count !== expectedCount || chunk.index < 1 || chunk.index > expectedCount)
+        || new Set(chunks.map(chunk => chunk.index)).size !== expectedCount) {
+        throw new TypeError('shc_qr_chunk_set_invalid');
+    }
+    return chunks.sort((left, right) => left.index - right.index).map(chunk => chunk.value).join('');
+}
+function validatePostQuantumDetachedJws(detachedJws) {
+    const match = /^([A-Za-z0-9_-]+)\.\.([A-Za-z0-9_-]+)$/.exec(detachedJws);
+    if (!match)
+        throw new TypeError('pqc_detached_jws_invalid');
+    let header;
+    try {
+        header = Content.base64UrlSafeToJSON(match[1]);
+    }
+    catch {
+        throw new TypeError('pqc_detached_jws_invalid');
+    }
+    if (!isRecord(header)
+        || !['ML-DSA-44', 'ML-DSA-65', 'ML-DSA-87'].includes(String(header.alg))
+        || typeof header.kid !== 'string' || !header.kid
+        || header.b64 !== false
+        || !Array.isArray(header.crit) || !header.crit.includes('b64')) {
+        throw new TypeError('pqc_detached_jws_invalid');
+    }
+    return detachedJws;
+}
+/** Encodes an RFC 7797 ML-DSA detached JWS as the version-one `pqc:/` companion transport. */
+export function encodePostQuantumCompanionProofUri(detachedJws) {
+    const validated = validatePostQuantumDetachedJws(detachedJws);
+    return `${PostQuantumCompanionProofPrefix}${validated}`;
+}
+export function decodePostQuantumCompanionProofUri(uri) {
+    if (typeof uri !== 'string' || !uri.startsWith(PostQuantumCompanionProofPrefix)) {
+        throw new TypeError('pqc_companion_proof_uri_invalid');
+    }
+    return validatePostQuantumDetachedJws(uri.slice(PostQuantumCompanionProofPrefix.length));
+}
+/**
+ * Encodes an ML-DSA detached JWS using the same two-decimal-digits-per-JWS-
+ * character technique as SHC. The external SHC payload is never repeated.
+ */
+export function encodePostQuantumCompanionProofQr(detachedJws, options = {}) {
+    const validated = validatePostQuantumDetachedJws(detachedJws);
+    const qrCount = options.qrCount ?? PostQuantumCompanionProofDefaultQrCount;
+    if (!Number.isInteger(qrCount) || qrCount < 1 || qrCount > 99 || qrCount > validated.length) {
+        throw new TypeError('pqc_companion_proof_qr_count_invalid');
+    }
+    const chunkLength = Math.ceil(validated.length / qrCount);
+    if (qrCount === 1)
+        return [`${PostQuantumCompanionProofPrefix}${encodeNumericBody(validated)}`];
+    return Array.from({ length: qrCount }, (_, index) => {
+        const chunk = validated.slice(index * chunkLength, (index + 1) * chunkLength);
+        return `${PostQuantumCompanionProofPrefix}${index + 1}/${qrCount}/${encodeNumericBody(chunk)}`;
+    });
+}
+/** Reassembles one complete detached proof regardless of companion QR scan order. */
+export function decodePostQuantumCompanionProofQr(qrValues) {
+    if (!Array.isArray(qrValues) || qrValues.length === 0)
+        throw new TypeError('pqc_companion_proof_qr_required');
+    if (qrValues.length === 1 && /^pqc:\/\d+$/.test(qrValues[0])) {
+        return validatePostQuantumDetachedJws(decodeNumericBody(qrValues[0].slice(PostQuantumCompanionProofPrefix.length)));
+    }
+    const chunks = qrValues.map(value => {
+        const match = /^pqc:\/(\d+)\/(\d+)\/(\d+)$/.exec(value);
+        if (!match)
+            throw new TypeError('pqc_companion_proof_qr_chunk_invalid');
+        return { index: Number(match[1]), count: Number(match[2]), value: decodeNumericBody(match[3]) };
+    });
+    const expectedCount = chunks[0].count;
+    if (expectedCount !== chunks.length
+        || chunks.some(chunk => chunk.count !== expectedCount || chunk.index < 1 || chunk.index > expectedCount)
+        || new Set(chunks.map(chunk => chunk.index)).size !== expectedCount) {
+        throw new TypeError('pqc_companion_proof_qr_chunk_set_invalid');
+    }
+    return validatePostQuantumDetachedJws(chunks.sort((left, right) => left.index - right.index).map(chunk => chunk.value).join(''));
+}
+/** Returns the exact uncompressed payload bytes that every detached companion proof verifies. */
+export function decodeSmartHealthCardPayloadBytes(compactJws) {
+    const parts = compactJws.split('.');
+    if (parts.length !== 3)
+        throw new TypeError('shc_compact_jws_invalid');
+    return inflateRaw(Content.base64ToBytes(parts[1]));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-data-utils-ts",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -40,6 +40,14 @@
       "types": "./dist/group.d.ts",
       "default": "./dist/group.js"
     },
+    "./immunization": {
+      "types": "./dist/immunization.d.ts",
+      "default": "./dist/immunization.js"
+    },
+    "./international-health-card": {
+      "types": "./dist/international-health-card.d.ts",
+      "default": "./dist/international-health-card.js"
+    },
     "./iso-jurisdictions": {
       "types": "./dist/iso-jurisdictions.d.ts",
       "default": "./dist/iso-jurisdictions.js"
@@ -60,6 +68,10 @@
       "types": "./dist/sectors.d.ts",
       "default": "./dist/sectors.js"
     },
+    "./shc": {
+      "types": "./dist/shc.d.ts",
+      "default": "./dist/shc.js"
+    },
     "./veterinary-sections": {
       "types": "./dist/veterinary-sections.d.ts",
       "default": "./dist/veterinary-sections.js"
@@ -85,10 +97,12 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/pako": "^2.0.4",
     "typescript": "^5.5.4"
   },
   "dependencies": {
-    "gdc-common-utils-ts": "2.9.10"
+    "gdc-common-utils-ts": "2.9.10",
+    "pako": "^2.2.0"
   },
   "engines": {
     "node": ">=20"