sos-sdk-core-ts 0.1.6 → 0.2.2

package/CHANGELOG.md

@@ -2,13 +2,31 @@
 
 ## Unreleased
 
+## 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
+  by SOSChain, Vet and UHC, above `sos-data-utils-ts` and below product SDKs.
+- Remove the accidental dependency on and root reexport of `uhc-sdk-core-ts`.
+- Add neutral `authorizeEmergencyAction` and `EmergencyDeliveryTarget` APIs;
+  retain the older `Soschain*` names as deprecated compatibility aliases.
 - Consume emergency evidence, Group/ServiceRequest and card-target contracts
   from `sos-data-utils-ts@0.3.0` instead of maintaining SDK-local copies.
 - Preserve the existing SDK root and subpath exports as compatibility aliases.
-- Pin `uhc-sdk-core-ts@0.6.1` so the complete tree deduplicates to one
-  `sos-data-utils-ts@0.3.0` installation.
-- Pin the first registry release to `uhc-sdk-core-ts@0.6.0` so SOSChain
-  consumers can remove the historical vendored package from staging builds.
 
 ## 0.1.5
 

package/README.md

@@ -1,12 +1,39 @@
-# SOSChain SDK Core
+# Shared SOS SDK Core
+## Blocking local-first SDK release
 
-Runtime-neutral SOSChain extension of `uhc-sdk-core-ts`. Deterministic record
-types and builders come from `sos-data-utils-ts`; this SDK owns authorization
-and orchestration.
+The canonical contract is [`SDK_LAYERING.md`](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/SDK_LAYERING.md). Its
+indivisible order is **local packages -> full local test matrix -> merge every
+validated branch to `main` -> publish bottom-up -> install exact registry
+versions and commit lockfiles on `main` -> staging**. Never publish to discover
+deterministic failures and never commit a local package reference. Staging
+begins only after exact registry packages are installed and verified.
 
-It consumes the exact published `uhc-sdk-core-ts` contract. Git, workspace,
-vendored and `file:` dependencies are forbidden in committed or deployed
-dependency state.
+
+Runtime-neutral shared SDK for SOSChain, VetChain and UHC. Deterministic
+cross-product record types and builders come from `sos-data-utils-ts`; this SDK
+owns reusable authorization and orchestration without Node, browser, gateway or
+product-specific behavior.
+
+The canonical architecture keeps both shared layers visible:
+
+```text
+gdc-* frozen
+    ↓
+sos-data-utils-ts
+    ↓
+sos-sdk-core-ts
+    ├──→ vet-sdk-core-ts
+    ├──→ uhc-sdk-core-ts
+    └──→ sos-sdk-node-ts
+```
+
+Vet and UHC may also depend directly on `sos-data-utils-ts` when they import or
+expose its types. `sos-sdk-core-ts` never depends on or reexports either product
+SDK. `sos-sdk-node-ts` owns SOSChain-specific Node transport, persistence and
+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
@@ -16,17 +43,36 @@ 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.
 
-`authorizeSoschainEmergencyAction` separately checks trusted evidence for every
+`authorizeEmergencyAction` separately checks trusted evidence for every
 member and for `sos:call` or `sos:request`. Identity verification alone never
 grants an emergency capability. Regional/local delivery is represented by
-`SoschainEmergencyDeliveryTarget`; transport and tenant routing stay outside FHIR.
+`EmergencyDeliveryTarget`; transport and tenant routing stay outside FHIR.
 The `incident-reporter` relationship represents a short-lived grant issued by
 a trusted scan resolver to an already verified person at the scene; it does
 not imply guardianship, control or professional status.
 
+The older `SoschainEmergency*` names remain deprecated compatibility aliases
+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.
 
+## 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/emergency-authorization.d.ts

@@ -1,6 +1,7 @@
-import type { SoschainEmergencyAuthorizationEvidence, SoschainEmergencyCapability } from 'sos-data-utils-ts/emergency-evidence';
-export type { SoschainEmergencyAuthorizationEvidence, SoschainEmergencyCapability, SoschainEvidenceDomain, } from 'sos-data-utils-ts/emergency-evidence';
-export type SoschainEmergencyDeliveryTarget = Readonly<{
+import type { EmergencyAuthorizationEvidence, EmergencyCapability, EvidenceDomain } from 'sos-data-utils-ts/emergency-evidence';
+export type { EmergencyAuthorizationEvidence, EmergencyCapability, EvidenceDomain, } from 'sos-data-utils-ts/emergency-evidence';
+/** Runtime-neutral endpoint selected after authorization succeeds. */
+export type EmergencyDeliveryTarget = Readonly<{
     tenantId: string;
     jurisdiction: string;
     locality?: string;
@@ -10,10 +11,20 @@ export type SoschainEmergencyDeliveryTarget = Readonly<{
  * Requires current trusted evidence for every affected subject and capability.
  * Identifier syntax and the legal meaning of each issuer remain policy concerns.
  */
-export declare function authorizeSoschainEmergencyAction(input: Readonly<{
+export declare function authorizeEmergencyAction(input: Readonly<{
     callerId: string;
     memberSubjectIds: readonly string[];
-    capability: SoschainEmergencyCapability;
-    evidence: readonly SoschainEmergencyAuthorizationEvidence[];
+    capability: EmergencyCapability;
+    evidence: readonly EmergencyAuthorizationEvidence[];
     now?: string;
 }>): readonly string[];
+/** @deprecated Use `EmergencyDeliveryTarget`. */
+export type SoschainEmergencyDeliveryTarget = EmergencyDeliveryTarget;
+/** @deprecated Import `EmergencyAuthorizationEvidence` from this module. */
+export type SoschainEmergencyAuthorizationEvidence = EmergencyAuthorizationEvidence;
+/** @deprecated Import `EmergencyCapability` from this module. */
+export type SoschainEmergencyCapability = EmergencyCapability;
+/** @deprecated Import `EvidenceDomain` from this module. */
+export type SoschainEvidenceDomain = EvidenceDomain;
+/** @deprecated Use `authorizeEmergencyAction`. */
+export declare const authorizeSoschainEmergencyAction: typeof authorizeEmergencyAction;

package/dist/emergency-authorization.js

@@ -2,7 +2,7 @@
  * Requires current trusted evidence for every affected subject and capability.
  * Identifier syntax and the legal meaning of each issuer remain policy concerns.
  */
-export function authorizeSoschainEmergencyAction(input) {
+export function authorizeEmergencyAction(input) {
     const at = Date.parse(input.now ?? new Date().toISOString());
     const evidenceIds = new Set();
     for (const subjectId of input.memberSubjectIds) {
@@ -17,3 +17,5 @@ export function authorizeSoschainEmergencyAction(input) {
     }
     return [...evidenceIds];
 }
+/** @deprecated Use `authorizeEmergencyAction`. */
+export const authorizeSoschainEmergencyAction = authorizeEmergencyAction;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-/** SOSChain extends UHC without moving product-specific contracts into UHC. */
-export * from 'uhc-sdk-core-ts';
-export * from 'sos-data-utils-ts/emergency-evidence';
+/** Shared runtime-neutral orchestration remains independent from product SDKs. */
+export { EmergencyCapabilities, EvidenceDomains, EvidenceRelationships, SoschainEmergencyCapabilities, SoschainEvidenceDomains, SoschainEvidenceRelationships, } from 'sos-data-utils-ts/emergency-evidence';
+export type { EvidenceRelationship, SoschainEvidenceRelationship, } from 'sos-data-utils-ts/emergency-evidence';
 export * from './emergency-group.js';
 export * from './emergency-authorization.js';
 export * from './place-card-association.js';
+export * from './secure-message-crypto.js';

package/dist/index.js

@@ -1,6 +1,6 @@
-/** SOSChain extends UHC without moving product-specific contracts into UHC. */
-export * from 'uhc-sdk-core-ts';
-export * from 'sos-data-utils-ts/emergency-evidence';
+/** Shared runtime-neutral orchestration remains independent from product SDKs. */
+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 './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/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,7 +1,7 @@
 {
   "name": "sos-sdk-core-ts",
-  "version": "0.1.6",
-  "description": "Runtime-neutral SOSChain contracts extending uhc-sdk-core-ts",
+  "version": "0.2.2",
+  "description": "Runtime-neutral shared orchestration for SOS, Vet and UHC products",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
   "repository": {
@@ -27,9 +27,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,8 +48,10 @@
     "prepack": "npm run check"
   },
   "dependencies": {
-    "sos-data-utils-ts": "0.3.0",
-    "uhc-sdk-core-ts": "0.6.1"
+    "@noble/ciphers": "2.4.0",
+    "@noble/hashes": "2.4.0",
+    "@noble/post-quantum": "0.7.1",
+    "sos-data-utils-ts": "0.3.9"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",