vet-sdk-core-ts 0.4.25 → 0.4.27

package/README.md

@@ -32,6 +32,22 @@ The result contains printable vaccination data plus both
 the validity interval explicitly; FHIR `Immunization.expirationDate` remains
 the vaccine-batch expiry.
 
+`pqcProofLookupReference` is separate: it hashes the exact compact SHC JWS so
+`publishVeterinaryHealthCardPqcProofs(...)` and
+`resolveVeterinaryHealthCardPqcProofs(...)` can use a product ledger/resolver
+to retrieve the unchanged detached `pqc:/` proofs from a single printed SHC
+QR when online. It does not replace the offline companion QR labels.
+
+## Private clinic documents and index projection
+
+`sealVeterinarySecureClinicMessage(...)` signs the complete FHIR Bundle
+document with ML-DSA-44 and encrypts it to the clinic/controller endpoint with
+ML-KEM-768 plus AES-256-GCM. Its separate index projection contains only each
+source `fullUrl` and the server-policy allowlisted `resource.meta.tag[]`
+codings. Every coding system must be the concrete
+`<ResourceType>.<search-parameter-or-custom>` key; repeated values become one
+CSV flat claim. The GW never receives the encrypted message or private Bundle.
+
 ## USDC payment quotes
 
 `vet-sdk-core-ts/payment` separates the payment provider, asset and EVM network

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

@@ -13,8 +13,26 @@ export type IssuedVeterinaryHealthCardCredential = Readonly<{
     pqcQr: readonly (readonly string[])[];
     payloadBytes: Uint8Array;
     payloadReferences: SmartHealthCardPayloadReferences;
+    /** Optional online lookup; separate from payload hashes and the `pqc:/` format. */
+    pqcProofLookupReference: string;
     printData: InternationalHealthCardPrintData;
 }>;
+export type VeterinaryHealthCardPqcProofRecord = Readonly<{
+    lookupReference: string;
+    pqcCompanionProofs: readonly string[];
+}>;
+export type VeterinaryHealthCardPqcProofLedger<Receipt = unknown> = Readonly<{
+    publish(record: VeterinaryHealthCardPqcProofRecord): Promise<Receipt>;
+    resolve(lookupReference: string): Promise<VeterinaryHealthCardPqcProofRecord | undefined>;
+}>;
+/** Browser/server adapter for the Vet product BFF; ledger custody remains behind that boundary. */
+export declare function createVeterinaryHealthCardPqcProofHttpLedger(input: Readonly<{
+    baseUrl: string;
+    bearerToken?: () => Promise<string | undefined>;
+    fetchImpl?: typeof fetch;
+}>): VeterinaryHealthCardPqcProofLedger<Readonly<{
+    transactionId: string;
+}>>;
 /**
  * Issues transport values only after the caller supplies GW's authoritative
  * readback Bundle. The tenant issuer owns the standard ES256 signature. Every
@@ -35,6 +53,19 @@ export declare function issueVeterinaryHealthCardCredential(input: Readonly<{
     }>;
     pqcQr?: PostQuantumCompanionProofQrOptions;
 }>): Promise<IssuedVeterinaryHealthCardCredential>;
+/** Publishes only detached proofs under the exact compact-SHC lookup key. */
+export declare function publishVeterinaryHealthCardPqcProofs<Receipt>(input: Readonly<{
+    issued: IssuedVeterinaryHealthCardCredential;
+    ledger: VeterinaryHealthCardPqcProofLedger<Receipt>;
+}>): Promise<Readonly<{
+    lookupReference: string;
+    receipt: Receipt;
+}>>;
+/** Resolves companion proofs online from one scanned SHC QR set. */
+export declare function resolveVeterinaryHealthCardPqcProofs(input: Readonly<{
+    shcQr: readonly string[];
+    ledger: Pick<VeterinaryHealthCardPqcProofLedger, 'resolve'>;
+}>): Promise<readonly string[]>;
 /** Verifies the standard credential and all scanned companion proofs offline through caller-owned trust resolvers. */
 export declare function verifyVeterinaryHealthCardCredential(input: Readonly<{
     shcQr: readonly string[];

package/dist/health-card-issuance.js

@@ -1,6 +1,38 @@
-import { assembleSmartHealthCardJws, buildSmartHealthCardPayloadReferences, decodePostQuantumCompanionProofQr, decodeSmartHealthCardPayloadBytes, decodeSmartHealthCardQr, encodePostQuantumCompanionProofUri, encodePostQuantumCompanionProofQr, encodeSmartHealthCardQr, prepareSmartHealthCard, } from 'vet-data-utils-ts/shc';
+import { assembleSmartHealthCardJws, buildSmartHealthCardJwsProofReference, buildSmartHealthCardPayloadReferences, decodePostQuantumCompanionProofQr, decodePostQuantumCompanionProofUri, decodeSmartHealthCardPayloadBytes, decodeSmartHealthCardQr, encodePostQuantumCompanionProofUri, encodePostQuantumCompanionProofQr, encodeSmartHealthCardQr, prepareSmartHealthCard, } from 'vet-data-utils-ts/shc';
 import { buildInternationalHealthCardPrintData, } from 'vet-data-utils-ts/international-health-card';
 import { projectClinicalBundleForReading, } from 'vet-data-utils-ts/clinical-bundle-reader';
+/** Browser/server adapter for the Vet product BFF; ledger custody remains behind that boundary. */
+export function createVeterinaryHealthCardPqcProofHttpLedger(input) {
+    const baseUrl = input.baseUrl.replace(/\/$/, '');
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const headers = async () => {
+        const token = await input.bearerToken?.();
+        return {
+            'Content-Type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        };
+    };
+    return {
+        async publish(record) {
+            const response = await fetchImpl(baseUrl, {
+                method: 'POST', headers: await headers(), body: JSON.stringify(record),
+            });
+            if (!response.ok)
+                throw new Error(`veterinary_health_card_pqc_publish_failed:${response.status}`);
+            return await response.json();
+        },
+        async resolve(lookupReference) {
+            const response = await fetchImpl(`${baseUrl}/${encodeURIComponent(lookupReference)}`, {
+                method: 'GET', headers: await headers(),
+            });
+            if (response.status === 404)
+                return undefined;
+            if (!response.ok)
+                throw new Error(`veterinary_health_card_pqc_resolve_failed:${response.status}`);
+            return await response.json();
+        },
+    };
+}
 /**
  * Issues transport values only after the caller supplies GW's authoritative
  * readback Bundle. The tenant issuer owns the standard ES256 signature. Every
@@ -34,6 +66,7 @@ export async function issueVeterinaryHealthCardCredential(input) {
         pqcQr: detached.map(proof => encodePostQuantumCompanionProofQr(proof, input.pqcQr)),
         payloadBytes: prepared.payloadBytes,
         payloadReferences,
+        pqcProofLookupReference: buildSmartHealthCardJwsProofReference(compactJws),
         printData: buildInternationalHealthCardPrintData({
             authoritativeBundle: input.authoritativeBundle,
             validFrom: input.print.validFrom,
@@ -43,6 +76,29 @@ export async function issueVeterinaryHealthCardCredential(input) {
         }),
     };
 }
+/** Publishes only detached proofs under the exact compact-SHC lookup key. */
+export async function publishVeterinaryHealthCardPqcProofs(input) {
+    input.issued.pqcCompanionProofs.forEach(decodePostQuantumCompanionProofUri);
+    const record = {
+        lookupReference: input.issued.pqcProofLookupReference,
+        pqcCompanionProofs: [...input.issued.pqcCompanionProofs],
+    };
+    const receipt = await input.ledger.publish(record);
+    return { lookupReference: record.lookupReference, receipt };
+}
+/** Resolves companion proofs online from one scanned SHC QR set. */
+export async function resolveVeterinaryHealthCardPqcProofs(input) {
+    const compactJws = decodeSmartHealthCardQr(input.shcQr);
+    const lookupReference = buildSmartHealthCardJwsProofReference(compactJws);
+    const record = await input.ledger.resolve(lookupReference);
+    if (!record)
+        throw new TypeError('veterinary_health_card_pqc_proof_not_found');
+    if (record.lookupReference !== lookupReference) {
+        throw new TypeError('veterinary_health_card_pqc_lookup_mismatch');
+    }
+    record.pqcCompanionProofs.forEach(decodePostQuantumCompanionProofUri);
+    return [...record.pqcCompanionProofs];
+}
 /** Verifies the standard credential and all scanned companion proofs offline through caller-owned trust resolvers. */
 export async function verifyVeterinaryHealthCardCredential(input) {
     const compactJws = decodeSmartHealthCardQr(input.shcQr);

package/dist/index.d.ts

@@ -7,5 +7,6 @@ export * from "./reusable-bff.js";
 export * from "./research-study.js";
 export * from "./payment.js";
 export * from "./health-card-issuance.js";
+export * from "./secure-clinic-channel.js";
 export * from "./scheduling.js";
 export * from "vet-data-utils-ts";

package/dist/index.js

@@ -7,5 +7,6 @@ export * from "./reusable-bff.js";
 export * from "./research-study.js";
 export * from "./payment.js";
 export * from "./health-card-issuance.js";
+export * from "./secure-clinic-channel.js";
 export * from "./scheduling.js";
 export * from "vet-data-utils-ts";

package/dist/secure-clinic-channel.d.ts

@@ -0,0 +1,50 @@
+type JsonObject = Record<string, unknown>;
+export interface VeterinarySecureEndpointPublicKeys {
+    endpointId: string;
+    signingKeyId: string;
+    encryptionKeyId: string;
+    signingPublicKey: Uint8Array;
+    encryptionPublicKey: Uint8Array;
+}
+export interface VeterinarySecureEndpointKeys {
+    publicKeys: VeterinarySecureEndpointPublicKeys;
+    signingSecretKey: Uint8Array;
+    encryptionSecretKey: Uint8Array;
+}
+export interface VeterinaryEncryptedEnvelope {
+    mediaType: 'application/didcomm-encrypted+json';
+    compactJwe: string;
+}
+export interface VeterinaryIndexProjection {
+    entries: Array<{
+        fullUrl: string;
+        claims: Record<string, string>;
+    }>;
+}
+export interface VeterinaryIndexProjectionPolicy {
+    allowedResourceTypes: ReadonlySet<string>;
+    allowedTagSystems: ReadonlySet<string>;
+}
+export declare function createVeterinarySecureEndpointKeys(endpointId: string): Promise<VeterinarySecureEndpointKeys>;
+export declare function sealVeterinarySecureClinicMessage(input: Readonly<{
+    sender: VeterinarySecureEndpointKeys;
+    recipient: VeterinarySecureEndpointPublicKeys;
+    from: string;
+    to: string;
+    messageId: string;
+    threadId: string;
+    bundle: JsonObject;
+    indexPolicy: VeterinaryIndexProjectionPolicy;
+}>): Promise<Readonly<{
+    envelope: VeterinaryEncryptedEnvelope;
+    indexProjection: VeterinaryIndexProjection;
+}>>;
+export declare function openVeterinarySecureClinicMessage(input: Readonly<{
+    recipient: VeterinarySecureEndpointKeys;
+    senderSigningPublicKey: Uint8Array;
+    envelope: VeterinaryEncryptedEnvelope;
+}>): Promise<Readonly<{
+    bundle: unknown;
+    signatureVerified: true;
+}>>;
+export {};

package/dist/secure-clinic-channel.js

@@ -0,0 +1,173 @@
+import { ml_dsa44 } from '@noble/post-quantum/ml-dsa.js';
+import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function base64Url(value) {
+    const bytes = typeof value === 'string' ? encoder.encode(value) : value;
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+function fromBase64Url(value) {
+    const padded = value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - value.length % 4) % 4);
+    const binary = atob(padded);
+    return Uint8Array.from(binary, character => character.charCodeAt(0));
+}
+function canonicalize(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalize).join(',')}]`;
+    return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, child]) => `${JSON.stringify(key)}:${canonicalize(child)}`).join(',')}}`;
+}
+async function keyId(prefix, publicKey) {
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', publicKey));
+    return `${prefix}:${base64Url(digest)}`;
+}
+export async function createVeterinarySecureEndpointKeys(endpointId) {
+    const signing = ml_dsa44.keygen();
+    const encryption = ml_kem768.keygen();
+    return {
+        publicKeys: {
+            endpointId,
+            signingKeyId: await keyId('urn:vetchain:key:ml-dsa-44', signing.publicKey),
+            encryptionKeyId: await keyId('urn:vetchain:key:ml-kem-768', encryption.publicKey),
+            signingPublicKey: signing.publicKey,
+            encryptionPublicKey: encryption.publicKey,
+        },
+        signingSecretKey: signing.secretKey,
+        encryptionSecretKey: encryption.secretKey,
+    };
+}
+async function encryptAesGcm(keyBytes, plaintext, aad) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const key = await crypto.subtle.importKey('raw', keyBytes, 'AES-GCM', false, ['encrypt']);
+    const combined = new Uint8Array(await crypto.subtle.encrypt({
+        name: 'AES-GCM', iv: iv, ...(aad ? { additionalData: aad } : {}), tagLength: 128,
+    }, key, plaintext));
+    return { iv, ciphertext: combined.slice(0, -16), tag: combined.slice(-16) };
+}
+async function decryptAesGcm(keyBytes, iv, ciphertext, tag, aad) {
+    const key = await crypto.subtle.importKey('raw', keyBytes, 'AES-GCM', false, ['decrypt']);
+    const combined = new Uint8Array(ciphertext.length + tag.length);
+    combined.set(ciphertext);
+    combined.set(tag, ciphertext.length);
+    return new Uint8Array(await crypto.subtle.decrypt({
+        name: 'AES-GCM', iv: iv, ...(aad ? { additionalData: aad } : {}), tagLength: 128,
+    }, key, combined));
+}
+async function deriveWrapKey(sharedSecret, encryptionKeyId) {
+    const source = await crypto.subtle.importKey('raw', sharedSecret, 'HKDF', false, ['deriveBits']);
+    return new Uint8Array(await crypto.subtle.deriveBits({
+        name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(0),
+        info: encoder.encode(`VetChain clinic CEK wrap v1\0${encryptionKeyId}`),
+    }, source, 256));
+}
+function extractIndexProjection(bundle, policy) {
+    var _a;
+    if (bundle.resourceType !== 'Bundle' || bundle.type !== 'document' || !Array.isArray(bundle.entry)) {
+        throw new Error('The private payload must be a FHIR Bundle document');
+    }
+    if (bundle.entry[0]?.resource?.resourceType !== 'Composition') {
+        throw new Error('A FHIR Bundle document must have Composition as its first entry');
+    }
+    const entries = [];
+    for (const rawEntry of bundle.entry) {
+        const entry = rawEntry;
+        const resource = entry.resource;
+        if (!resource || typeof resource.resourceType !== 'string' || typeof resource.id !== 'string')
+            continue;
+        if (typeof entry.fullUrl !== 'string')
+            throw new Error('Each indexed resource requires an absolute HTTPS fullUrl');
+        let parsed;
+        try {
+            parsed = new URL(entry.fullUrl);
+        }
+        catch {
+            throw new Error('Each indexed resource requires an absolute HTTPS fullUrl');
+        }
+        const segments = parsed.pathname.split('/').filter(Boolean);
+        if (parsed.protocol !== 'https:' || segments.at(-2) !== resource.resourceType
+            || segments.at(-1) !== resource.id || !UUID_PATTERN.test(resource.id)) {
+            throw new Error('The fullUrl must end in /<ResourceType>/<UUID> matching the resource');
+        }
+        if (resource.resourceType === 'Binary' && resource.contentType === 'application/pdf') {
+            throw new Error('PDF content must be an Attachment inside DocumentReference');
+        }
+        if (!policy.allowedResourceTypes.has(resource.resourceType))
+            continue;
+        const tags = resource.meta?.tag;
+        if (!Array.isArray(tags))
+            continue;
+        const grouped = {};
+        for (const rawTag of tags) {
+            const tag = rawTag;
+            if (typeof tag.system !== 'string' || typeof tag.code !== 'string' || !policy.allowedTagSystems.has(tag.system))
+                continue;
+            if (!tag.system.startsWith(`${resource.resourceType}.`)) {
+                throw new Error(`Index claim ${tag.system} must start with ${resource.resourceType}.`);
+            }
+            ;
+            (grouped[_a = tag.system] ?? (grouped[_a] = [])).push(tag.code);
+        }
+        const claims = Object.fromEntries(Object.entries(grouped).map(([key, values]) => [key, values.join(',')]));
+        if (Object.keys(claims).length)
+            entries.push({ fullUrl: entry.fullUrl, claims });
+    }
+    return { entries };
+}
+function sign(sender, plaintext) {
+    const header = base64Url(canonicalize({ alg: 'ML-DSA-44', kid: sender.publicKeys.signingKeyId, typ: 'application/didcomm-signed+json' }));
+    const payload = base64Url(canonicalize(plaintext));
+    return `${header}.${payload}.${base64Url(ml_dsa44.sign(encoder.encode(`${header}.${payload}`), sender.signingSecretKey))}`;
+}
+export async function sealVeterinarySecureClinicMessage(input) {
+    const indexProjection = extractIndexProjection(input.bundle, input.indexPolicy);
+    const signed = sign(input.sender, {
+        id: input.messageId, thid: input.threadId,
+        type: 'https://vetchain.app/protocols/private-fhir-document/1.0/ips',
+        from: input.from, to: [input.to], created_time: Math.floor(Date.now() / 1000),
+        body: { mediaType: 'application/fhir+json', bundle: input.bundle },
+    });
+    const cek = crypto.getRandomValues(new Uint8Array(32));
+    const header = base64Url(canonicalize({
+        alg: 'ML-KEM-768+A256GCMKW', enc: 'A256GCM', kid: input.recipient.encryptionKeyId,
+        typ: 'application/didcomm-encrypted+json', cty: 'application/didcomm-signed+json',
+    }));
+    const encrypted = await encryptAesGcm(cek, encoder.encode(signed), encoder.encode(header));
+    const encapsulated = ml_kem768.encapsulate(input.recipient.encryptionPublicKey);
+    const wrapped = await encryptAesGcm(await deriveWrapKey(encapsulated.sharedSecret, input.recipient.encryptionKeyId), cek);
+    const encryptedKey = base64Url(canonicalize({
+        kem: base64Url(encapsulated.cipherText), iv: base64Url(wrapped.iv),
+        ciphertext: base64Url(wrapped.ciphertext), tag: base64Url(wrapped.tag),
+    }));
+    return { envelope: { mediaType: 'application/didcomm-encrypted+json', compactJwe: [
+                header, encryptedKey, base64Url(encrypted.iv), base64Url(encrypted.ciphertext), base64Url(encrypted.tag),
+            ].join('.') }, indexProjection };
+}
+export async function openVeterinarySecureClinicMessage(input) {
+    const parts = input.envelope.compactJwe.split('.');
+    if (parts.length !== 5)
+        throw new Error('Invalid encrypted DIDComm envelope');
+    const [headerPart, encryptedKeyPart, iv, ciphertext, tag] = parts;
+    const header = JSON.parse(decoder.decode(fromBase64Url(headerPart)));
+    if (header.kid !== input.recipient.publicKeys.encryptionKeyId)
+        throw new Error('Envelope recipient key does not match');
+    const encryptedKey = JSON.parse(decoder.decode(fromBase64Url(encryptedKeyPart)));
+    const shared = ml_kem768.decapsulate(fromBase64Url(encryptedKey.kem), input.recipient.encryptionSecretKey);
+    const cek = await decryptAesGcm(await deriveWrapKey(shared, input.recipient.publicKeys.encryptionKeyId), fromBase64Url(encryptedKey.iv), fromBase64Url(encryptedKey.ciphertext), fromBase64Url(encryptedKey.tag));
+    const signed = decoder.decode(await decryptAesGcm(cek, fromBase64Url(iv), fromBase64Url(ciphertext), fromBase64Url(tag), encoder.encode(headerPart)));
+    const [signedHeader, payload, signature, extra] = signed.split('.');
+    if (extra !== undefined || !signature)
+        throw new Error('Invalid signed DIDComm payload');
+    const protectedHeader = JSON.parse(decoder.decode(fromBase64Url(signedHeader)));
+    if (protectedHeader.alg !== 'ML-DSA-44' || protectedHeader.typ !== 'application/didcomm-signed+json'
+        || !ml_dsa44.verify(fromBase64Url(signature), encoder.encode(`${signedHeader}.${payload}`), input.senderSigningPublicKey)) {
+        throw new Error('Invalid ML-DSA signature');
+    }
+    const plaintext = JSON.parse(decoder.decode(fromBase64Url(payload)));
+    return { bundle: (plaintext.body.bundle), signatureVerified: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-sdk-core-ts",
-  "version": "0.4.25",
+  "version": "0.4.27",
   "description": "Browser-safe VetChain core contracts and governed animal species identifiers",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -48,6 +48,10 @@
       "types": "./dist/health-card-issuance.d.ts",
       "default": "./dist/health-card-issuance.js"
     },
+    "./secure-clinic-channel": {
+      "types": "./dist/secure-clinic-channel.d.ts",
+      "default": "./dist/secure-clinic-channel.js"
+    },
     "./scheduling": {
       "types": "./dist/scheduling.d.ts",
       "default": "./dist/scheduling.js"
@@ -75,7 +79,8 @@
   },
   "dependencies": {
     "@noble/hashes": "^2.2.0",
+    "@noble/post-quantum": "0.5.4",
     "gdc-common-utils-ts": "2.9.10",
-    "vet-data-utils-ts": "0.5.15"
+    "vet-data-utils-ts": "0.5.17"
   }
 }