sos-sdk-node-ts 0.1.5 → 0.1.7

package/README.md

@@ -1,4 +1,8 @@
 # sos-sdk-node-ts
+
+Accepted Encounter handover persistence and future channel-audience
+reconciliation are documented in
+[`docs/ENCOUNTER_TRANSFER_AUDIENCE_PERSISTENCE.md`](docs/ENCOUNTER_TRANSFER_AUDIENCE_PERSISTENCE.md).
 ## 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). Its
@@ -44,6 +48,12 @@ emergency request over HTTPS with a stable idempotency key and validates the
 provider acknowledgement. The bearer credential remains only in the trusted
 Node runtime.
 
+`sos-sdk-node-ts/bff-email-assertion` lets one authenticated BFF present a
+normalized email to one exact receiving BFF for a short-lived, named purpose.
+The receiving application still authorizes the operation and should reject
+replay where it matters. Never expose the shared secret or let a browser set
+the trusted issuer, audience, purpose or identity claims.
+
 ## Secure-message CSPRNG adapter
 
 `sos-sdk-node-ts/secure-message-crypto` exports `NodeSecureRandomSource` and

package/dist/bff-email-assertion.d.ts

@@ -0,0 +1,33 @@
+export type BffEmailAssertion = Readonly<{
+    issuer: string;
+    audience: string;
+    purpose: string;
+    email: string;
+    assertionId: string;
+    issuedAt: number;
+    expiresAt: number;
+}>;
+type CreateInput = Readonly<{
+    issuer: string;
+    audience: string;
+    purpose: string;
+    email: string;
+    secret: string;
+    now?: Date;
+    lifetimeSeconds?: number;
+}>;
+type VerifyInput = Readonly<{
+    issuer: string;
+    audience: string;
+    purpose: string;
+    secret: string;
+    now?: Date;
+}>;
+/**
+ * Issues a minimal, short-lived identity assertion from one trusted BFF to an
+ * exact receiving BFF. It is not a browser mode switch or an authorization
+ * capability; the receiver must still enforce the requested operation.
+ */
+export declare function createBffEmailAssertion(input: CreateInput): string;
+export declare function verifyBffEmailAssertion(assertion: string, input: VerifyInput): BffEmailAssertion;
+export {};

package/dist/bff-email-assertion.js

@@ -0,0 +1,113 @@
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+const MAXIMUM_LIFETIME_SECONDS = 5 * 60;
+/**
+ * Issues a minimal, short-lived identity assertion from one trusted BFF to an
+ * exact receiving BFF. It is not a browser mode switch or an authorization
+ * capability; the receiver must still enforce the requested operation.
+ */
+export function createBffEmailAssertion(input) {
+    const secret = validatedSecret(input.secret);
+    const issuedAt = epochSeconds(input.now ?? new Date());
+    const lifetimeSeconds = input.lifetimeSeconds ?? 120;
+    if (!Number.isInteger(lifetimeSeconds) || lifetimeSeconds < 1 || lifetimeSeconds > MAXIMUM_LIFETIME_SECONDS) {
+        throw new Error('bff_assertion_lifetime_invalid');
+    }
+    const payload = Object.freeze({
+        issuer: absoluteUrl(input.issuer, 'bff_assertion_issuer_invalid'),
+        audience: absoluteUrl(input.audience, 'bff_assertion_audience_invalid'),
+        purpose: required(input.purpose, 'bff_assertion_purpose_invalid'),
+        email: normalizedEmail(input.email),
+        assertionId: randomUUID(),
+        issuedAt,
+        expiresAt: issuedAt + lifetimeSeconds,
+    });
+    const encoded = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+    return `${encoded}.${signature(encoded, secret)}`;
+}
+export function verifyBffEmailAssertion(assertion, input) {
+    const secret = validatedSecret(input.secret);
+    const [encoded, receivedSignature, extra] = assertion.split('.');
+    if (!encoded || !receivedSignature || extra)
+        throw new Error('bff_assertion_format_invalid');
+    const expectedSignature = signature(encoded, secret);
+    const received = Buffer.from(receivedSignature, 'base64url');
+    const expected = Buffer.from(expectedSignature, 'base64url');
+    if (received.length !== expected.length || !timingSafeEqual(received, expected))
+        throw new Error('bff_assertion_signature_invalid');
+    const payload = parsePayload(encoded);
+    if (payload.issuer !== absoluteUrl(input.issuer, 'bff_assertion_issuer_invalid'))
+        throw new Error('bff_assertion_issuer_mismatch');
+    if (payload.audience !== absoluteUrl(input.audience, 'bff_assertion_audience_invalid'))
+        throw new Error('bff_assertion_audience_mismatch');
+    if (payload.purpose !== required(input.purpose, 'bff_assertion_purpose_invalid'))
+        throw new Error('bff_assertion_purpose_mismatch');
+    const now = epochSeconds(input.now ?? new Date());
+    if (payload.expiresAt <= now)
+        throw new Error('bff_assertion_expired');
+    if (payload.issuedAt > now || payload.expiresAt - payload.issuedAt > MAXIMUM_LIFETIME_SECONDS)
+        throw new Error('bff_assertion_time_invalid');
+    return payload;
+}
+function parsePayload(encoded) {
+    try {
+        const value = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
+        if (!value || typeof value !== 'object'
+            || typeof value.issuer !== 'string' || typeof value.audience !== 'string'
+            || typeof value.purpose !== 'string' || typeof value.email !== 'string'
+            || typeof value.assertionId !== 'string' || typeof value.issuedAt !== 'number'
+            || typeof value.expiresAt !== 'number')
+            throw new Error('invalid');
+        return Object.freeze({
+            issuer: absoluteUrl(value.issuer, 'bff_assertion_payload_invalid'),
+            audience: absoluteUrl(value.audience, 'bff_assertion_payload_invalid'),
+            purpose: required(value.purpose, 'bff_assertion_payload_invalid'),
+            email: normalizedEmail(value.email),
+            assertionId: required(value.assertionId, 'bff_assertion_payload_invalid'),
+            issuedAt: value.issuedAt,
+            expiresAt: value.expiresAt,
+        });
+    }
+    catch (reason) {
+        if (reason instanceof Error && reason.message.startsWith('bff_assertion_'))
+            throw reason;
+        throw new Error('bff_assertion_payload_invalid');
+    }
+}
+function signature(encoded, secret) {
+    return createHmac('sha256', secret).update(encoded).digest('base64url');
+}
+function validatedSecret(value) {
+    const secret = Buffer.from(value, 'utf8');
+    if (secret.length < 32)
+        throw new Error('bff_assertion_secret_invalid');
+    return secret;
+}
+function normalizedEmail(value) {
+    const email = value.trim().toLowerCase();
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
+        throw new Error('bff_assertion_email_invalid');
+    return email;
+}
+function required(value, issue) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new Error(issue);
+    return normalized;
+}
+function absoluteUrl(value, issue) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' && url.hostname !== 'localhost')
+            throw new Error(issue);
+        return url.href.replace(/\/$/, '');
+    }
+    catch {
+        throw new Error(issue);
+    }
+}
+function epochSeconds(value) {
+    const milliseconds = value.getTime();
+    if (!Number.isFinite(milliseconds))
+        throw new Error('bff_assertion_time_invalid');
+    return Math.floor(milliseconds / 1_000);
+}

package/dist/encounter-transfer-audience-service.d.ts

@@ -0,0 +1,34 @@
+import { type EncounterTransferOrchestrationInput } from 'sos-sdk-core-ts/encounter-transfer-communication';
+export type AcceptedEncounterHandoverCommit = Readonly<{
+    idempotencyKey: string;
+    communicationThreadId: string;
+    projectionCommunication: Readonly<Record<string, unknown>>;
+    expectedProfessionalGroupReferences: readonly string[];
+    retainedProfessionalGroupReferences: readonly string[];
+    addedProfessionalGroupReferences: readonly string[];
+    removedProfessionalGroupReferences: readonly string[];
+    nextProfessionalGroupReferences: readonly string[];
+    familyJourneyEvent: Readonly<Record<string, unknown>>;
+}>;
+export type AcceptedEncounterHandoverReceipt = Readonly<{
+    idempotencyKey: string;
+    outcome: 'committed' | 'already-committed';
+    revision: string;
+}>;
+export type AcceptedEncounterHandoverPersistence = Readonly<{
+    /** Atomically persists every field or none; partial commits are forbidden. */
+    commitAcceptedHandover(commit: AcceptedEncounterHandoverCommit): Promise<AcceptedEncounterHandoverReceipt>;
+}>;
+/**
+ * Prepare and atomically persist one accepted Encounter handover.
+ *
+ * The injected adapter owns compare-and-swap/idempotency and must commit the
+ * provider projection, future professional audience and family-safe journey
+ * event as one unit. This service deliberately exposes no sequence of partial
+ * persistence callbacks. Authorization and service Group resolution occur in
+ * the product BFF before this call; historical Communications are untouched.
+ */
+export declare function persistAcceptedEncounterHandover(input: EncounterTransferOrchestrationInput, persistence: AcceptedEncounterHandoverPersistence): Promise<Readonly<{
+    commit: AcceptedEncounterHandoverCommit;
+    receipt: AcceptedEncounterHandoverReceipt;
+}>>;

package/dist/encounter-transfer-audience-service.js

@@ -0,0 +1,35 @@
+import { prepareEncounterTransferOrchestration, } from 'sos-sdk-core-ts/encounter-transfer-communication';
+/**
+ * Prepare and atomically persist one accepted Encounter handover.
+ *
+ * The injected adapter owns compare-and-swap/idempotency and must commit the
+ * provider projection, future professional audience and family-safe journey
+ * event as one unit. This service deliberately exposes no sequence of partial
+ * persistence callbacks. Authorization and service Group resolution occur in
+ * the product BFF before this call; historical Communications are untouched.
+ */
+export async function persistAcceptedEncounterHandover(input, persistence) {
+    const plan = prepareEncounterTransferOrchestration(input);
+    const reconciliation = plan.audienceReconciliation;
+    const commit = Object.freeze({
+        idempotencyKey: reconciliation.idempotencyKey,
+        communicationThreadId: reconciliation.communicationThreadId,
+        projectionCommunication: Object.freeze(plan.projectionCommunication),
+        expectedProfessionalGroupReferences: Object.freeze([...input.currentProfessionalGroupReferences]),
+        retainedProfessionalGroupReferences: reconciliation.retainedProfessionalGroupReferences,
+        addedProfessionalGroupReferences: reconciliation.addedProfessionalGroupReferences,
+        removedProfessionalGroupReferences: reconciliation.removedProfessionalGroupReferences,
+        nextProfessionalGroupReferences: reconciliation.nextProfessionalGroupReferences,
+        familyJourneyEvent: reconciliation.familyJourneyEvent,
+    });
+    const receipt = await persistence.commitAcceptedHandover(commit);
+    if (receipt.idempotencyKey !== commit.idempotencyKey) {
+        throw new TypeError('encounter_handover_receipt_idempotency_mismatch');
+    }
+    if (receipt.outcome !== 'committed' && receipt.outcome !== 'already-committed') {
+        throw new TypeError('encounter_handover_receipt_outcome_invalid');
+    }
+    if (!String(receipt.revision || '').trim())
+        throw new TypeError('encounter_handover_receipt_revision_required');
+    return Object.freeze({ commit, receipt: Object.freeze({ ...receipt }) });
+}

package/dist/index.d.ts

@@ -4,3 +4,5 @@ export * from './prompt-audio-runtime.js';
 export * from './secure-message-crypto.js';
 export * from './confidential-channel-cache.js';
 export * from './bundle-sync-service.js';
+export * from './encounter-transfer-audience-service.js';
+export * from './bff-email-assertion.js';

package/dist/index.js

@@ -4,3 +4,5 @@ export * from './prompt-audio-runtime.js';
 export * from './secure-message-crypto.js';
 export * from './confidential-channel-cache.js';
 export * from './bundle-sync-service.js';
+export * from './encounter-transfer-audience-service.js';
+export * from './bff-email-assertion.js';

package/docs/ENCOUNTER_TRANSFER_AUDIENCE_PERSISTENCE.md

@@ -0,0 +1,38 @@
+# Accepted Encounter handover persistence
+
+`persistAcceptedEncounterHandover(...)` is the product-neutral Node boundary
+for one accepted patient movement. The product BFF authenticates the actor,
+authorizes the transition and resolves exact source/destination
+`HealthcareService` Group assignments before calling it.
+
+The injected persistence adapter receives one indivisible commit containing:
+
+- the completed Communication Bundle that projects both Encounter updates and
+  both EncounterHistory milestones;
+- the expected current professional Groups and retained/added/removed/next
+  future audience;
+- the family-safe journey event;
+- one idempotency key and communication-thread identifier.
+
+The adapter must compare-and-swap the expected audience and commit every field
+or none. Retrying the same idempotency key returns `already-committed`. It must
+not expose separate public callbacks that could persist the Encounter while
+failing to update the channel, or vice versa.
+
+```ts
+const persisted = await persistAcceptedEncounterHandover(
+  authorizedEncounterTransfer,
+  {
+    commitAcceptedHandover: commit => handoverRepository.commitAtomically(commit),
+  },
+)
+
+if (persisted.receipt.outcome === 'already-committed') {
+  return persisted.receipt
+}
+```
+
+Historical Communications and their recipient snapshots are never modified.
+Subsequent Communications use `nextProfessionalGroupReferences`. The
+family-facing channel receives only `familyJourneyEvent` after its independent
+recipient and purpose checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-node-ts",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Product-neutral Node adapters shared by SOSChain, Vet and UHC runtimes",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -32,9 +32,17 @@
       "types": "./dist/bundle-sync-service.d.ts",
       "default": "./dist/bundle-sync-service.js"
     },
+    "./encounter-transfer-audience-service": {
+      "types": "./dist/encounter-transfer-audience-service.d.ts",
+      "default": "./dist/encounter-transfer-audience-service.js"
+    },
     "./confidential-channel-cache": {
       "types": "./dist/confidential-channel-cache.d.ts",
       "default": "./dist/confidential-channel-cache.js"
+    },
+    "./bff-email-assertion": {
+      "types": "./dist/bff-email-assertion.d.ts",
+      "default": "./dist/bff-email-assertion.js"
     }
   },
   "files": [
@@ -51,7 +59,7 @@
     "prepack": "npm run check"
   },
   "dependencies": {
-    "sos-sdk-core-ts": "0.5.1"
+    "sos-sdk-core-ts": "0.5.2"
   },
   "devDependencies": {
     "@types/node": "^24.10.0",