sos-sdk-core-ts 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## Unreleased
+
+## 0.3.0 - 2026-09-26
+
+- Pin `sos-data-utils-ts@0.4.1`, which owns the Organization fallback target
+  and governed public-risk campaign criteria used by this release.
+- Add idempotent fulfilled-Appointment to Encounter orchestration with
+  Appointment, subject, service provider and current Location continuity.
+- Add fail-closed authorization for encounter-related voice, video and secure
+  messages. Calls never carry clinical Bundles, and preliminary Bundles may be
+  delivered only without updating the subject index.
+- Create independent compact-coded emergency ServiceRequest and triage Task
+  entries targeting a HealthcareService or its owning Organization.
+- Add frozen-cohort CommunicationRequest orchestration and per-recipient
+  delivery checks for blood-donation and governed FHIR SearchParameter
+  public-risk campaigns.
+- Replace copied emergency Group members and split coding claims with the
+  canonical Group-reference and compact-code contract.
+- Document the immutable main-tarball local Vet proof required before npm
+  publication and staging.
+
+## 0.2.2 - 2026-09-25
+
+- Add runtime-neutral ML-KEM-768 multi-recipient encryption for written and
+  binary-audio messages with one SHA3-256-derived AES-256-GCM content key and
+  one independently protected CEK entry per recipient.
+- Preserve the historical deterministic 32-byte message-seed derivation
+  contract and add recipient updates that rewrap the CEK without changing the
+  stored ciphertext, IV or authentication tag.
+- Fail closed for duplicate or unknown recipients, malformed envelopes,
+  invalid random-source output and authenticated-ciphertext tampering.
+
+## 0.2.1
+
+- Link the shared runtime layer to the blocking local-first release order: complete local proof, merge validated branches to main, publish bottom-up, pin exact registry artifacts, then stage.
+
 ## 0.2.0
 
 - Redefine `sos-sdk-core-ts` as the runtime-neutral orchestration layer consumed

package/README.md

@@ -1,4 +1,16 @@
 # Shared SOS SDK Core
+## Blocking local-first SDK release
+
+The canonical contract is [`SDK_LAYERING.md`](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/SDK_LAYERING.md).
+Merge and push validated shared dependency sources to `main`, create immutable
+unpublished tarballs from those main commits with `npm pack`, and install them
+temporarily with `--no-save`. Prove the real local Vet channel (portal, phone
+service, chatbot or other supported channel) -> BFF or channel service ->
+high-level SDK -> GW VET journey without skips. Then merge the consumer source
+to `main`, publish the exact commits bottom-up, pin exact registry versions and
+lockfiles, repeat affected local gates, and only then promote to staging.
+Never commit a tarball or `file:`, Git or workspace dependency.
+
 
 Runtime-neutral shared SDK for SOSChain, VetChain and UHC. Deterministic
 cross-product record types and builders come from `sos-data-utils-ts`; this SDK
@@ -26,13 +38,11 @@ jobs; those adapters do not belong here.
 Git, workspace, vendored and `file:` dependencies are forbidden in committed
 or deployed dependency state.
 
-The emergency-group contract treats `emergencyGroupId`, `subjectId` and
-`callerId` as opaque business identifiers. A group assistance request is one
-flat `ServiceRequest.*` claims under `resource.meta.claims`. A FHIR R5, R6 or
-other resource is projected only at an integration boundary.
-
-Groups are named collections. A scanned card is attached to one selected group
-before that group's identifiers are projected into a single service request.
+The emergency-group contract stores subject references only on an enumerated
+FHIR Group. A group assistance request references that Group from one standard,
+compact-coded ServiceRequest; it never copies members or persists split coding
+claims. Flat claims remain the canonical storage representation and native
+FHIR is projected only at an explicit boundary.
 
 `authorizeEmergencyAction` separately checks trusted evidence for every
 member and for `sos:call` or `sos:request`. Identity verification alone never
@@ -48,6 +58,34 @@ to the same types and implementation; they are not a second contract.
 `buildSoschainPlaceCardAssociationClaims` records a UHC/VetChain card link to
 a canonical SOSChain Place or vehicle without merging either identity.
 
+## Care, emergency and alert orchestration
+
+`sos-sdk-core-ts/care-emergency-alert-orchestration` supplies the shared,
+runtime-neutral plans for Appointment-to-Encounter continuity, protected
+pre-publication calls/messages, resilient emergency ServiceRequest plus triage
+Task creation, and governed donation/public-risk campaigns. Transport,
+persistence, authorization evidence acquisition and product policy remain in
+the channel service, Node adapter and Vet/UHC/SOSChain layers.
+
+See [docs/CARE_EMERGENCY_AND_ALERT_ORCHESTRATION.md](docs/CARE_EMERGENCY_AND_ALERT_ORCHESTRATION.md)
+for lifecycle, authorization and persistence invariants.
+
+## Multi-recipient secure messages
+
+`sos-sdk-core-ts/secure-message-crypto` protects written and binary-audio
+messages with the same runtime-neutral byte API. It derives one AES-256 content
+key from one random 32-byte message seed, encrypts the content once, and wraps
+that CEK independently for each ML-KEM-768 recipient. The ML-KEM shared secret
+is recipient-specific; the resulting content key and ciphertext are common to
+all authorized recipients.
+
+`updateRecipients(...)` rewraps the existing CEK for added device/channel keys
+and can remove obsolete or temporary service entries without changing the
+stored ciphertext, IV or authentication tag. The caller remains responsible
+for proving authorization to change recipients. Runtime packages inject only
+`SecureRandomSource`; Node, Expo and browser crypto adapters must not duplicate
+ML-KEM, HKDF or AES logic. See [docs/SECURE_MESSAGES.md](docs/SECURE_MESSAGES.md).
+
 ```bash
 npm install
 npm run check

package/dist/care-emergency-alert-orchestration.d.ts

@@ -0,0 +1,84 @@
+import { type CareJourneyTransition, type EmergencyIntake, type GovernedAlertCampaign, type GovernedAlertCohortSnapshot, type GovernedAlertDeliveryAudit } from 'sos-data-utils-ts/care-emergency-alert-records';
+import { type ClinicalCoding } from 'fhir-data-utils-ts/care-emergency-alert';
+import type { FlatClaimResourceEntry } from 'fhir-data-utils-ts/flat-claim-resource-graph';
+export type FulfilledAppointmentEncounterPlan = Readonly<{
+    created: false;
+    encounterReference: string;
+}> | Readonly<{
+    created: true;
+    encounterReference: string;
+    encounterEntry: FlatClaimResourceEntry;
+}>;
+/**
+ * Plans one idempotent Appointment-to-Encounter transition. Persistence must
+ * enforce `idempotencyKey`; an existing reference suppresses duplicate writes.
+ */
+export declare function orchestrateFulfilledAppointment(input: Readonly<{
+    transition: CareJourneyTransition;
+    encounterIdentifier: string;
+    existingEncounterReference?: string;
+}>): FulfilledAppointmentEncounterPlan;
+export type EncounterCommunicationAuthorization = Readonly<{
+    encounterReference: string;
+    actorReference: string;
+    recipientReferences: readonly string[];
+    channel: 'voice' | 'video' | 'encrypted-message';
+    includesClinicalBundle: boolean;
+    clinicalStatus?: 'preliminary' | 'final';
+    updateIndex: boolean;
+}>;
+/**
+ * Authorizes only the channel boundary. It never attests clinical data.
+ * Preliminary encrypted Bundles may be delivered directly but cannot update
+ * the subject index; voice/video signaling cannot carry a clinical Bundle.
+ */
+export declare function authorizeEncounterCommunication(input: Readonly<{
+    encounterReference: string;
+    actorReference: string;
+    recipientReferences: readonly string[];
+    actorCanCommunicate: boolean;
+    encounterActive: boolean;
+    channel: EncounterCommunicationAuthorization['channel'];
+    includesClinicalBundle: boolean;
+    clinicalStatus?: 'preliminary' | 'final';
+    updateIndex: boolean;
+}>): EncounterCommunicationAuthorization;
+/** Creates independent standard ServiceRequest and durable triage Task entries. */
+export declare function orchestrateEmergencyRequest(input: Readonly<{
+    intake: EmergencyIntake;
+    serviceRequestIdentifier: string;
+    triageTaskIdentifier: string;
+    assistanceCode: ClinicalCoding;
+}>): Readonly<{
+    intake: EmergencyIntake;
+    serviceRequestEntry: FlatClaimResourceEntry;
+    triageTaskEntry: FlatClaimResourceEntry;
+}>;
+export type GovernedAlertCampaignPlan = Readonly<{
+    campaign: GovernedAlertCampaign;
+    cohortSnapshot: GovernedAlertCohortSnapshot;
+    communicationRequestEntry: FlatClaimResourceEntry;
+}>;
+/** Builds one campaign request bound to the frozen evaluated Group snapshot. */
+export declare function prepareGovernedAlertCampaign(input: Readonly<{
+    campaign: GovernedAlertCampaign;
+    snapshotGroupReference: string;
+    evaluatedAt: string;
+    evaluationFingerprint: string;
+    eligibleSubjectReferences: readonly string[];
+    communicationRequestEntryId: string;
+    communicationRequestIdentifier: string;
+    category: ClinicalCoding;
+}>): GovernedAlertCampaignPlan;
+/** Rechecks frozen membership before recording the data-layer delivery audit. */
+export declare function prepareGovernedAlertDelivery(input: Readonly<{
+    campaignPlan: GovernedAlertCampaignPlan;
+    recipientReference: string;
+    communicationReference: string;
+    evaluatedAt: string;
+    eligibilityCurrent: boolean;
+    exclusionCurrent: boolean;
+    consentReference?: string;
+    channelAuthorizationReference?: string;
+    outcome: 'sent' | 'suppressed';
+}>): GovernedAlertDeliveryAudit;

package/dist/care-emergency-alert-orchestration.js

@@ -0,0 +1,139 @@
+import { freezeGovernedAlertCohort, normalizeCareJourneyTransition, normalizeEmergencyIntake, normalizeGovernedAlertCampaign, recordGovernedAlertDelivery, } from 'sos-data-utils-ts/care-emergency-alert-records';
+import { buildCohortCommunicationRequestFlatEntry, buildEncounterCareJourneyFlatGraph, buildServiceRequestFlatEntry, buildServiceRequestTriageTaskFlatEntry, } from 'fhir-data-utils-ts/care-emergency-alert';
+/**
+ * Plans one idempotent Appointment-to-Encounter transition. Persistence must
+ * enforce `idempotencyKey`; an existing reference suppresses duplicate writes.
+ */
+export function orchestrateFulfilledAppointment(input) {
+    const transition = normalizeCareJourneyTransition(input.transition);
+    if (input.existingEncounterReference) {
+        return Object.freeze({
+            created: false,
+            encounterReference: reference(input.existingEncounterReference, 'Encounter', 'existing_encounter_reference_invalid'),
+        });
+    }
+    const encounterEntry = buildEncounterCareJourneyFlatGraph({
+        parent: {
+            entryId: transition.encounterEntryId,
+            identifier: input.encounterIdentifier,
+            status: 'in-progress',
+            subjectReference: transition.subjectReference,
+            appointmentReference: transition.appointmentReference,
+            serviceProviderReference: transition.serviceProviderReference,
+            periodStart: transition.occurredAt,
+            locationReference: transition.locationReference,
+        },
+    })[0];
+    return Object.freeze({ created: true, encounterReference: encounterEntry.reference, encounterEntry });
+}
+/**
+ * Authorizes only the channel boundary. It never attests clinical data.
+ * Preliminary encrypted Bundles may be delivered directly but cannot update
+ * the subject index; voice/video signaling cannot carry a clinical Bundle.
+ */
+export function authorizeEncounterCommunication(input) {
+    if (!input.actorCanCommunicate)
+        throw new Error('encounter_communication_actor_forbidden');
+    if (!input.encounterActive)
+        throw new Error('encounter_communication_inactive_encounter');
+    if ((input.channel === 'voice' || input.channel === 'video') && input.includesClinicalBundle) {
+        throw new Error('encounter_call_clinical_bundle_forbidden');
+    }
+    if (input.includesClinicalBundle && !input.clinicalStatus)
+        throw new Error('encounter_communication_clinical_status_required');
+    if (input.clinicalStatus === 'preliminary' && input.updateIndex)
+        throw new Error('preliminary_clinical_index_update_forbidden');
+    const recipientReferences = uniqueReferences(input.recipientReferences, 'encounter_communication_recipient_required');
+    return Object.freeze({
+        encounterReference: reference(input.encounterReference, 'Encounter', 'encounter_communication_encounter_reference_invalid'),
+        actorReference: reference(input.actorReference, undefined, 'encounter_communication_actor_reference_invalid'),
+        recipientReferences,
+        channel: input.channel,
+        includesClinicalBundle: input.includesClinicalBundle,
+        ...(input.clinicalStatus ? { clinicalStatus: input.clinicalStatus } : {}),
+        updateIndex: input.updateIndex,
+    });
+}
+/** Creates independent standard ServiceRequest and durable triage Task entries. */
+export function orchestrateEmergencyRequest(input) {
+    const intake = normalizeEmergencyIntake(input.intake);
+    const serviceRequestEntry = buildServiceRequestFlatEntry({
+        entryId: intake.serviceRequestEntryId,
+        identifier: input.serviceRequestIdentifier,
+        status: 'active',
+        intent: 'order',
+        priority: 'stat',
+        code: input.assistanceCode,
+        subjectReference: intake.subjectReference,
+        requesterReference: intake.requesterReference,
+        performerReferences: [intake.targetServiceReference],
+        authoredAt: intake.receivedAt,
+    });
+    const triageTaskEntry = buildServiceRequestTriageTaskFlatEntry({
+        entryId: intake.triageTaskEntryId,
+        identifier: input.triageTaskIdentifier,
+        serviceRequestReference: serviceRequestEntry.reference,
+        subjectReference: intake.subjectReference,
+        requesterReference: intake.requesterReference,
+        ownerReference: intake.triageOwnerReference,
+        authoredAt: intake.receivedAt,
+    });
+    return Object.freeze({ intake, serviceRequestEntry, triageTaskEntry });
+}
+/** Builds one campaign request bound to the frozen evaluated Group snapshot. */
+export function prepareGovernedAlertCampaign(input) {
+    const campaign = normalizeGovernedAlertCampaign(input.campaign);
+    const cohortSnapshot = freezeGovernedAlertCohort({
+        campaign,
+        snapshotGroupReference: input.snapshotGroupReference,
+        evaluatedAt: input.evaluatedAt,
+        evaluationFingerprint: input.evaluationFingerprint,
+        eligibleSubjectReferences: input.eligibleSubjectReferences,
+    });
+    const communicationRequestEntry = buildCohortCommunicationRequestFlatEntry({
+        entryId: input.communicationRequestEntryId,
+        identifier: input.communicationRequestIdentifier,
+        status: 'active',
+        priority: 'routine',
+        category: input.category,
+        subjectReference: cohortSnapshot.snapshotGroupReference,
+        requesterReference: campaign.requesterReference,
+        authoredAt: cohortSnapshot.evaluatedAt,
+        reasonReferences: [campaign.groupDefinitionReference],
+    });
+    return Object.freeze({ campaign, cohortSnapshot, communicationRequestEntry });
+}
+/** Rechecks frozen membership before recording the data-layer delivery audit. */
+export function prepareGovernedAlertDelivery(input) {
+    const recipientReference = reference(input.recipientReference, undefined, 'alert_delivery_recipient_reference_invalid');
+    if (!input.campaignPlan.cohortSnapshot.eligibleSubjectReferences.includes(recipientReference)) {
+        throw new Error('alert_delivery_recipient_not_in_snapshot');
+    }
+    return recordGovernedAlertDelivery({
+        campaignId: input.campaignPlan.campaign.campaignId,
+        snapshotGroupReference: input.campaignPlan.cohortSnapshot.snapshotGroupReference,
+        recipientReference,
+        communicationReference: input.communicationReference,
+        evaluatedAt: input.evaluatedAt,
+        eligibilityCurrent: input.eligibilityCurrent,
+        exclusionCurrent: input.exclusionCurrent,
+        consentReference: input.consentReference,
+        channelAuthorizationReference: input.channelAuthorizationReference,
+        outcome: input.outcome,
+    });
+}
+function uniqueReferences(values, error) {
+    const references = [...new Set(values.map(value => reference(value, undefined, error)))];
+    if (!references.length)
+        throw new TypeError(error);
+    return Object.freeze(references);
+}
+function reference(value, expectedType, error) {
+    if (typeof value !== 'string')
+        throw new TypeError(error);
+    const normalized = value.trim();
+    const match = /^([A-Z][A-Za-z0-9]+)\/([A-Za-z0-9.-]{1,128})$/.exec(normalized);
+    if (!match || (expectedType && match[1] !== expectedType))
+        throw new TypeError(error);
+    return normalized;
+}

package/dist/index.d.ts

@@ -3,4 +3,6 @@ export { EmergencyCapabilities, EvidenceDomains, EvidenceRelationships, Soschain
 export type { EvidenceRelationship, SoschainEvidenceRelationship, } from 'sos-data-utils-ts/emergency-evidence';
 export * from './emergency-group.js';
 export * from './emergency-authorization.js';
+export * from './care-emergency-alert-orchestration.js';
 export * from './place-card-association.js';
+export * from './secure-message-crypto.js';

package/dist/index.js

@@ -2,4 +2,6 @@
 export { EmergencyCapabilities, EvidenceDomains, EvidenceRelationships, SoschainEmergencyCapabilities, SoschainEvidenceDomains, SoschainEvidenceRelationships, } from 'sos-data-utils-ts/emergency-evidence';
 export * from './emergency-group.js';
 export * from './emergency-authorization.js';
+export * from './care-emergency-alert-orchestration.js';
 export * from './place-card-association.js';
+export * from './secure-message-crypto.js';

package/dist/secure-message-crypto.d.ts

@@ -0,0 +1,49 @@
+import { type SecureMessageEnvelope } from 'sos-data-utils-ts/secure-message-envelope';
+export interface SecureRandomSource {
+    getRandomBytes(length: number): Promise<Uint8Array>;
+}
+export interface SecureMessageRecipientPublicKey {
+    readonly keyId: string;
+    readonly publicKey: Uint8Array;
+}
+export interface SecureMessageRecipientKeyPair extends SecureMessageRecipientPublicKey {
+    readonly secretKey: Uint8Array;
+}
+export interface OpenedSecureMessage {
+    readonly contentType: string;
+    readonly plaintext: Uint8Array;
+}
+/**
+ * Preserve the historical secure-message contract: one random 32-byte message
+ * seed deterministically derives the AES-256 content-encryption key. The CEK is
+ * then wrapped independently for every current ML-KEM recipient.
+ */
+export declare const deriveSecureMessageContentEncryptionKey: (messageSeed: Uint8Array) => Uint8Array;
+/** Runtime-neutral ML-KEM multi-recipient encryption for text or binary audio messages. */
+export declare class MultiRecipientSecureMessageCrypto {
+    private readonly randomSource;
+    constructor(randomSource: SecureRandomSource);
+    generateRecipientKeyPair(keyId: string): Promise<SecureMessageRecipientKeyPair>;
+    seal(input: Readonly<{
+        plaintext: Uint8Array;
+        contentType: string;
+        recipients: readonly SecureMessageRecipientPublicKey[];
+    }>): Promise<SecureMessageEnvelope>;
+    open(input: Readonly<{
+        envelope: SecureMessageEnvelope;
+        recipient: SecureMessageRecipientKeyPair;
+    }>): Promise<OpenedSecureMessage>;
+    /**
+     * Rewrap the existing CEK without opening or re-encrypting message content.
+     * Business authorization for adding or removing a DCR remains with the caller.
+     */
+    updateRecipients(input: Readonly<{
+        envelope: SecureMessageEnvelope;
+        authorizingRecipient: SecureMessageRecipientKeyPair;
+        addRecipients?: readonly SecureMessageRecipientPublicKey[];
+        removeRecipientKeyIds?: readonly string[];
+    }>): Promise<SecureMessageEnvelope>;
+    private assertUniqueRecipientKeys;
+    private wrapContentEncryptionKey;
+    private unwrapContentEncryptionKey;
+}

package/dist/secure-message-crypto.js

@@ -0,0 +1,306 @@
+import { gcm } from '@noble/ciphers/aes.js';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { sha3_256 } from '@noble/hashes/sha3.js';
+import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
+import { SecureMessageContentEncryptionAlgorithm, SecureMessageEnvelopeProfile, SecureMessageKeyManagementAlgorithm, assertSecureMessageEnvelope, } from 'sos-data-utils-ts/secure-message-envelope';
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder(undefined, { fatal: true });
+const AES_KEY_BYTES = 32;
+const AES_GCM_NONCE_BYTES = 12;
+const AES_GCM_TAG_BYTES = 16;
+const ML_KEM_KEYGEN_SEED_BYTES = 64;
+const ML_KEM_ENCAPSULATION_SEED_BYTES = 32;
+const BASE64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const WRAP_VERSION = 'mlkem-cek-wrap-v1';
+const assertRandomBytes = (bytes, expectedLength) => {
+    if (!(bytes instanceof Uint8Array) || bytes.length !== expectedLength) {
+        throw new Error('secure_random_source_invalid');
+    }
+    return bytes;
+};
+const assertKeyId = (keyId) => {
+    const normalized = String(keyId).trim();
+    if (!normalized)
+        throw new Error('secure_message_recipient_key_id_required');
+    return normalized;
+};
+const encodeBase64Url = (bytes) => {
+    let output = '';
+    for (let offset = 0; offset < bytes.length; offset += 3) {
+        const first = bytes[offset];
+        const second = bytes[offset + 1];
+        const third = bytes[offset + 2];
+        const combined = (first << 16) | ((second ?? 0) << 8) | (third ?? 0);
+        output += BASE64URL_ALPHABET[(combined >>> 18) & 63];
+        output += BASE64URL_ALPHABET[(combined >>> 12) & 63];
+        if (second !== undefined)
+            output += BASE64URL_ALPHABET[(combined >>> 6) & 63];
+        if (third !== undefined)
+            output += BASE64URL_ALPHABET[combined & 63];
+    }
+    return output;
+};
+const decodeBase64Url = (value) => {
+    if (!/^[A-Za-z0-9_-]+$/u.test(value))
+        throw new Error('secure_message_base64url_invalid');
+    const output = new Uint8Array(Math.floor((value.length * 6) / 8));
+    let accumulator = 0;
+    let bits = 0;
+    let outputOffset = 0;
+    for (const character of value) {
+        const alphabetIndex = BASE64URL_ALPHABET.indexOf(character);
+        if (alphabetIndex < 0)
+            throw new Error('secure_message_base64url_invalid');
+        accumulator = (accumulator << 6) | alphabetIndex;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            output[outputOffset] = (accumulator >>> bits) & 0xff;
+            outputOffset += 1;
+        }
+    }
+    return output;
+};
+const encodeJson = (value) => encodeBase64Url(textEncoder.encode(JSON.stringify(value)));
+const decodeJson = (value) => {
+    try {
+        return JSON.parse(textDecoder.decode(decodeBase64Url(value)));
+    }
+    catch {
+        throw new Error('secure_message_json_invalid');
+    }
+};
+const splitCiphertextAndTag = (sealed) => {
+    if (sealed.length < AES_GCM_TAG_BYTES)
+        throw new Error('secure_message_ciphertext_invalid');
+    return {
+        ciphertext: sealed.slice(0, -AES_GCM_TAG_BYTES),
+        tag: sealed.slice(-AES_GCM_TAG_BYTES),
+    };
+};
+const joinCiphertextAndTag = (ciphertext, tag) => {
+    if (tag.length !== AES_GCM_TAG_BYTES)
+        throw new Error('secure_message_tag_invalid');
+    const sealed = new Uint8Array(ciphertext.length + tag.length);
+    sealed.set(ciphertext);
+    sealed.set(tag, ciphertext.length);
+    return sealed;
+};
+const protectedHeader = (contentType) => {
+    const normalizedContentType = String(contentType).trim();
+    if (!normalizedContentType || normalizedContentType.length > 255 || /[\u0000-\u001f\u007f]/u.test(normalizedContentType)) {
+        throw new Error('secure_message_content_type_invalid');
+    }
+    return {
+        typ: 'application/jose+json',
+        cty: normalizedContentType,
+        enc: SecureMessageContentEncryptionAlgorithm.A256GCM,
+        profile: SecureMessageEnvelopeProfile.MultirecipientMlKemV1,
+    };
+};
+const parseProtectedHeader = (encoded) => {
+    const header = decodeJson(encoded);
+    if (header.typ !== 'application/jose+json'
+        || typeof header.cty !== 'string'
+        || header.enc !== SecureMessageContentEncryptionAlgorithm.A256GCM
+        || header.profile !== SecureMessageEnvelopeProfile.MultirecipientMlKemV1) {
+        throw new Error('secure_message_protected_header_invalid');
+    }
+    return protectedHeader(header.cty);
+};
+const deriveRecipientWrappingKey = (sharedSecret, encodedProtectedHeader, recipientKeyId) => hkdf(sha256, sharedSecret, textEncoder.encode('multi-recipient-ml-kem-v1'), textEncoder.encode(`${encodedProtectedHeader}.${recipientKeyId}.cek`), AES_KEY_BYTES);
+/**
+ * Preserve the historical secure-message contract: one random 32-byte message
+ * seed deterministically derives the AES-256 content-encryption key. The CEK is
+ * then wrapped independently for every current ML-KEM recipient.
+ */
+export const deriveSecureMessageContentEncryptionKey = (messageSeed) => {
+    if (!(messageSeed instanceof Uint8Array) || messageSeed.length !== AES_KEY_BYTES) {
+        throw new Error('secure_message_seed_invalid');
+    }
+    return sha3_256(messageSeed);
+};
+/** Runtime-neutral ML-KEM multi-recipient encryption for text or binary audio messages. */
+export class MultiRecipientSecureMessageCrypto {
+    constructor(randomSource) {
+        this.randomSource = randomSource;
+    }
+    async generateRecipientKeyPair(keyId) {
+        const seed = assertRandomBytes(await this.randomSource.getRandomBytes(ML_KEM_KEYGEN_SEED_BYTES), ML_KEM_KEYGEN_SEED_BYTES);
+        try {
+            const { publicKey, secretKey } = ml_kem768.keygen(seed);
+            return { keyId: assertKeyId(keyId), publicKey, secretKey };
+        }
+        finally {
+            seed.fill(0);
+        }
+    }
+    async seal(input) {
+        if (!(input.plaintext instanceof Uint8Array) || input.plaintext.length === 0) {
+            throw new Error('secure_message_plaintext_required');
+        }
+        this.assertUniqueRecipientKeys(input.recipients);
+        const messageSeed = assertRandomBytes(await this.randomSource.getRandomBytes(AES_KEY_BYTES), AES_KEY_BYTES);
+        const cek = deriveSecureMessageContentEncryptionKey(messageSeed);
+        const iv = assertRandomBytes(await this.randomSource.getRandomBytes(AES_GCM_NONCE_BYTES), AES_GCM_NONCE_BYTES);
+        const encodedProtectedHeader = encodeJson(protectedHeader(input.contentType));
+        try {
+            const sealed = gcm(cek, iv, textEncoder.encode(encodedProtectedHeader)).encrypt(input.plaintext);
+            const { ciphertext, tag } = splitCiphertextAndTag(sealed);
+            const recipients = [];
+            for (const recipient of input.recipients) {
+                recipients.push(await this.wrapContentEncryptionKey(cek, encodedProtectedHeader, recipient));
+            }
+            const envelope = {
+                profile: SecureMessageEnvelopeProfile.MultirecipientMlKemV1,
+                protected: encodedProtectedHeader,
+                recipients,
+                iv: encodeBase64Url(iv),
+                ciphertext: encodeBase64Url(ciphertext),
+                tag: encodeBase64Url(tag),
+            };
+            assertSecureMessageEnvelope(envelope);
+            return envelope;
+        }
+        finally {
+            messageSeed.fill(0);
+            cek.fill(0);
+            iv.fill(0);
+        }
+    }
+    async open(input) {
+        assertSecureMessageEnvelope(input.envelope);
+        const header = parseProtectedHeader(input.envelope.protected);
+        const cek = await this.unwrapContentEncryptionKey(input.envelope, input.recipient);
+        try {
+            const plaintext = gcm(cek, decodeBase64Url(input.envelope.iv), textEncoder.encode(input.envelope.protected)).decrypt(joinCiphertextAndTag(decodeBase64Url(input.envelope.ciphertext), decodeBase64Url(input.envelope.tag)));
+            return { contentType: header.cty, plaintext };
+        }
+        finally {
+            cek.fill(0);
+        }
+    }
+    /**
+     * Rewrap the existing CEK without opening or re-encrypting message content.
+     * Business authorization for adding or removing a DCR remains with the caller.
+     */
+    async updateRecipients(input) {
+        assertSecureMessageEnvelope(input.envelope);
+        parseProtectedHeader(input.envelope.protected);
+        const addRecipients = input.addRecipients ?? [];
+        this.assertUniqueRecipientKeys(addRecipients, false);
+        const removedKeyIds = new Set((input.removeRecipientKeyIds ?? []).map(assertKeyId));
+        const existingKeyIds = new Set(input.envelope.recipients.map(({ header }) => header.kid));
+        for (const removedKeyId of removedKeyIds) {
+            if (!existingKeyIds.has(removedKeyId)) {
+                throw new Error('secure_message_recipient_remove_not_found');
+            }
+        }
+        const retainedRecipients = input.envelope.recipients.filter(({ header }) => !removedKeyIds.has(header.kid));
+        const retainedKeyIds = new Set(retainedRecipients.map(({ header }) => header.kid));
+        for (const recipient of addRecipients) {
+            const keyId = assertKeyId(recipient.keyId);
+            if (retainedKeyIds.has(keyId))
+                throw new Error('secure_message_recipient_duplicate');
+            retainedKeyIds.add(keyId);
+        }
+        if (retainedRecipients.length + addRecipients.length === 0) {
+            throw new Error('secure_message_recipients_required');
+        }
+        const cek = await this.unwrapContentEncryptionKey(input.envelope, input.authorizingRecipient);
+        try {
+            const addedRecipients = [];
+            for (const recipient of addRecipients) {
+                addedRecipients.push(await this.wrapContentEncryptionKey(cek, input.envelope.protected, recipient));
+            }
+            const updatedEnvelope = {
+                ...input.envelope,
+                recipients: [...retainedRecipients, ...addedRecipients],
+            };
+            assertSecureMessageEnvelope(updatedEnvelope);
+            return updatedEnvelope;
+        }
+        finally {
+            cek.fill(0);
+        }
+    }
+    assertUniqueRecipientKeys(recipients, requireAtLeastOne = true) {
+        if (!Array.isArray(recipients) || (requireAtLeastOne && recipients.length === 0)) {
+            throw new Error('secure_message_recipients_required');
+        }
+        const keyIds = new Set();
+        for (const recipient of recipients) {
+            const keyId = assertKeyId(recipient.keyId);
+            if (!(recipient.publicKey instanceof Uint8Array))
+                throw new Error('secure_message_recipient_public_key_invalid');
+            if (keyIds.has(keyId))
+                throw new Error('secure_message_recipient_duplicate');
+            keyIds.add(keyId);
+        }
+    }
+    async wrapContentEncryptionKey(cek, encodedProtectedHeader, recipient) {
+        const recipientKeyId = assertKeyId(recipient.keyId);
+        const encapsulationSeed = assertRandomBytes(await this.randomSource.getRandomBytes(ML_KEM_ENCAPSULATION_SEED_BYTES), ML_KEM_ENCAPSULATION_SEED_BYTES);
+        let sharedSecret;
+        let wrappingKey;
+        const wrappingIv = assertRandomBytes(await this.randomSource.getRandomBytes(AES_GCM_NONCE_BYTES), AES_GCM_NONCE_BYTES);
+        try {
+            const encapsulated = ml_kem768.encapsulate(recipient.publicKey, encapsulationSeed);
+            sharedSecret = encapsulated.sharedSecret;
+            wrappingKey = deriveRecipientWrappingKey(sharedSecret, encodedProtectedHeader, recipientKeyId);
+            const wrapAad = textEncoder.encode(`${encodedProtectedHeader}.${recipientKeyId}.cek`);
+            const sealedCek = gcm(wrappingKey, wrappingIv, wrapAad).encrypt(cek);
+            const { ciphertext, tag } = splitCiphertextAndTag(sealedCek);
+            const wrappedCek = {
+                v: WRAP_VERSION,
+                kem: 'ML-KEM-768',
+                kdf: 'HKDF-SHA-256',
+                wrap: 'A256GCM',
+                kemCiphertext: encodeBase64Url(encapsulated.cipherText),
+                iv: encodeBase64Url(wrappingIv),
+                ciphertext: encodeBase64Url(ciphertext),
+                tag: encodeBase64Url(tag),
+            };
+            return {
+                header: {
+                    alg: SecureMessageKeyManagementAlgorithm.MlKem768HkdfSha256A256GcmKw,
+                    kid: recipientKeyId,
+                },
+                encrypted_key: encodeJson(wrappedCek),
+            };
+        }
+        finally {
+            encapsulationSeed.fill(0);
+            wrappingIv.fill(0);
+            sharedSecret?.fill(0);
+            wrappingKey?.fill(0);
+        }
+    }
+    async unwrapContentEncryptionKey(envelope, recipientKeyPair) {
+        const recipientKeyId = assertKeyId(recipientKeyPair.keyId);
+        const recipient = envelope.recipients.find(({ header }) => header.kid === recipientKeyId);
+        if (!recipient)
+            throw new Error('secure_message_recipient_not_found');
+        const wrappedCek = decodeJson(recipient.encrypted_key);
+        if (wrappedCek.v !== WRAP_VERSION
+            || wrappedCek.kem !== 'ML-KEM-768'
+            || wrappedCek.kdf !== 'HKDF-SHA-256'
+            || wrappedCek.wrap !== 'A256GCM'
+            || typeof wrappedCek.kemCiphertext !== 'string'
+            || typeof wrappedCek.iv !== 'string'
+            || typeof wrappedCek.ciphertext !== 'string'
+            || typeof wrappedCek.tag !== 'string') {
+            throw new Error('secure_message_recipient_wrap_invalid');
+        }
+        const sharedSecret = ml_kem768.decapsulate(decodeBase64Url(wrappedCek.kemCiphertext), recipientKeyPair.secretKey);
+        const wrappingKey = deriveRecipientWrappingKey(sharedSecret, envelope.protected, recipientKeyId);
+        try {
+            return gcm(wrappingKey, decodeBase64Url(wrappedCek.iv), textEncoder.encode(`${envelope.protected}.${recipientKeyId}.cek`)).decrypt(joinCiphertextAndTag(decodeBase64Url(wrappedCek.ciphertext), decodeBase64Url(wrappedCek.tag)));
+        }
+        finally {
+            sharedSecret.fill(0);
+            wrappingKey.fill(0);
+        }
+    }
+}

package/docs/CARE_EMERGENCY_AND_ALERT_ORCHESTRATION.md

@@ -0,0 +1,74 @@
+# Care, Emergency and Alert Orchestration
+
+This package owns runtime-neutral authorization and orchestration shared by
+VetChain, UHC and SOSChain. FHIR flat-claim builders belong to
+`fhir-data-utils-ts`; deterministic records belong to `sos-data-utils-ts`;
+transport and persistence belong to BFF/channel and Node services; animal and
+human policy stays in Vet and UHC.
+
+## 1. Care continuity and protected contact
+
+1. Appointment `fulfilled` -> Encounter is an idempotent transition.
+2. The Encounter preserves the selected subject, Appointment, service-provider
+   Organization, start time and current Location.
+3. Admission, diagnostics, intensive care, ward and discharge are represented
+   by Encounter/location continuity. Controllers see only what current Consent
+   and actor/subject authorization permit.
+4. An authorized practitioner may start voice/video contact or send an
+   encrypted message to the controller or permitted related recipients before
+   publishing stressful results.
+5. Voice/video signaling carries no clinical Bundle. A preliminary clinical
+   Bundle may be delivered by encrypted message only with `updateIndex=false`.
+   A call or preliminary message must not publish, attest or update the subject
+   index. Final clinical publication is a separate workflow.
+6. A missed call may create an encrypted text/audio message in the same thread;
+   its recipients and thread authorization are revalidated by the service.
+
+The orchestrator returns a plan. The persistence owner must enforce the
+idempotency key and must not treat a returned plan as authorization evidence.
+
+## 2. Resilient emergency assistance
+
+When normal telephone service is unavailable, an authenticated controller or
+authorized requester submits an emergency request to a HealthcareService or
+its owning Organization. The BFF resolves the official target and creates two
+independent resources:
+
+- a compact-coded ServiceRequest containing the care request, requester,
+  subject and performer target;
+- a Task containing durable intake/triage ownership and linking back through
+  `Task.focus`.
+
+The emergency console can claim and update the Task, then open an authorized
+voice/video callback or encrypted thread. Raw phone/email destinations,
+WebRTC SDP/ICE/TURN state and encryption keys never enter either FHIR resource.
+The request grants no read access by itself; subject access still requires the
+current emergency or ordinary authorization contract.
+
+## 3. Governed alerts
+
+The common flow supports both `blood-donation` and `public-risk` campaigns.
+The server evaluates a governed definitional Group, freezes an enumerated Group
+snapshot and binds a CommunicationRequest to that snapshot. Subscription wakes
+evaluation; it is not Consent, cohort-query authority or send authority.
+
+Blood-donation campaigns require compact `system|code` blood-group filters and
+the minimum elapsed days since the last donation. Public-risk campaigns require
+server-authorized FHIR `resourceType`, `searchParameter` and `value` criteria;
+clients cannot submit executable queries.
+
+Immediately before each delivery, the service must verify snapshot membership,
+current eligibility, current exclusions, Consent and channel authorization.
+Only then may it create/send the Communication and record the audit. Group and
+CommunicationRequest resources never replace those per-recipient checks.
+
+## Release proof
+
+Merge validated shared dependency sources to `main`, create immutable
+unpublished tarballs from those commits, and install them temporarily with
+`--no-save`. Prove the affected real local Vet channel (portal, phone service,
+chatbot or another supported channel) -> BFF/channel service -> high-level SDK
+-> GW VET journey without skips. Merge the validated consumer source to
+`main`, publish exact packages bottom-up, pin registry versions, repeat affected
+local gates, and only then promote to staging. Never commit local tarballs or
+local dependency references.

package/docs/SECURE_MESSAGES.md

@@ -0,0 +1,59 @@
+# Multi-recipient secure messages
+
+## Public API
+
+Create `MultiRecipientSecureMessageCrypto` with a runtime-provided
+`SecureRandomSource`. The runtime supplies cryptographically secure random
+bytes only. The shared SDK owns ML-KEM-768, HKDF-SHA-256, SHA3-256 content-key
+derivation and AES-256-GCM.
+
+The byte-oriented methods are:
+
+- `generateRecipientKeyPair(keyId)` creates an ML-KEM recipient key pair.
+- `seal({ plaintext, contentType, recipients })` encrypts content once and
+  protects the CEK independently for every recipient public key.
+- `open({ envelope, recipient })` authenticates and returns the original bytes
+  plus protected content type.
+- `updateRecipients(...)` adds and removes recipient wraps without changing
+  the content ciphertext.
+
+Text callers encode/decode UTF-8 at their UI boundary. Audio callers pass the
+recorded binary bytes directly. The cryptographic layer never transcribes,
+converts or interprets either payload.
+
+## Key model
+
+One random 32-byte message seed deterministically derives one AES-256 CEK using
+SHA3-256. Content is encrypted once with AES-256-GCM. For each recipient:
+
+1. ML-KEM-768 independently produces a recipient-specific shared secret and
+   KEM ciphertext.
+2. HKDF-SHA-256 binds a wrapping key to the protected header and recipient
+   `kid`.
+3. AES-256-GCM protects the common CEK with that recipient wrapping key.
+
+The common CEK is not the ML-KEM shared secret. This distinction permits every
+authorized recipient to open the same content ciphertext while preserving an
+independent post-quantum encapsulation for each recipient key.
+
+## Recipient changes
+
+`updateRecipients(...)` proves possession of one current recipient secret key,
+unwraps the CEK in memory, adds independently wrapped CEKs for new public keys,
+and removes selected old entries. It does not decrypt or re-encrypt message
+content. Temporary buffers holding seeds, shared secrets, CEKs and wrapping
+keys are cleared after use where the JavaScript runtime permits it.
+
+This method is a cryptographic mechanism, not an authorization decision. A BFF
+or product service must first enforce the current subject, device/channel,
+Consent and recovery policy. It must reject an empty final recipient list.
+
+## Storage and channels
+
+Storage persists the opaque envelope from `sos-data-utils-ts`. It need not
+retain a service recipient once the current user devices have received their
+wraps. Web, telephone, WhatsApp or future channel DCRs use distinct `kid` and
+ML-KEM keys, but the message remains one ciphertext.
+
+Audio duration, file size, retention, notification email and voicemail access
+are product-level policies. They do not change this envelope or core API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-core-ts",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Runtime-neutral shared orchestration for SOS, Vet and UHC products",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -20,6 +20,10 @@
       "types": "./dist/emergency-group.d.ts",
       "default": "./dist/emergency-group.js"
     },
+    "./care-emergency-alert-orchestration": {
+      "types": "./dist/care-emergency-alert-orchestration.d.ts",
+      "default": "./dist/care-emergency-alert-orchestration.js"
+    },
     "./emergency-authorization": {
       "types": "./dist/emergency-authorization.d.ts",
       "default": "./dist/emergency-authorization.js"
@@ -27,9 +31,18 @@
     "./place-card-association": {
       "types": "./dist/place-card-association.d.ts",
       "default": "./dist/place-card-association.js"
+    },
+    "./secure-message-crypto": {
+      "types": "./dist/secure-message-crypto.d.ts",
+      "default": "./dist/secure-message-crypto.js"
     }
   },
-  "files": ["dist", "README.md", "CHANGELOG.md"],
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "docs"
+  ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "npm run clean && tsc -p tsconfig.json",
@@ -39,7 +52,11 @@
     "prepack": "npm run check"
   },
   "dependencies": {
-    "sos-data-utils-ts": "0.3.2"
+    "@noble/ciphers": "2.4.0",
+    "@noble/hashes": "2.4.0",
+    "@noble/post-quantum": "0.7.1",
+    "fhir-data-utils-ts": "0.3.7",
+    "sos-data-utils-ts": "0.4.1"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",