sos-sdk-node-ts 0.1.6 → 0.1.7

package/README.md

@@ -48,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/index.d.ts

@@ -5,3 +5,4 @@ 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

@@ -5,3 +5,4 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-node-ts",
-  "version": "0.1.6",
+  "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",
@@ -39,6 +39,10 @@
     "./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": [