sos-sdk-node-ts 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+## Unreleased
+
+- Add the shared trusted-BFF authorized-subject directory client with canonical
+  SOS GW Organization/License routes, real submit/poll HTTP coverage,
+  independent `sameAs` alias matching and fail-closed animal-card DID
+  validation.
+- Document multiple-controller ownership and future explicit principal
+  controller promotion without changing the child or animal subject identity.
+- Add the 2026 development-owner notice and re-establish the public repository
+  from a clean source snapshot while
+  retaining this changelog as the package release record.
+
+## 0.1.7 - 2026-10-05
+
+- Add a short-lived HMAC-protected email assertion for exact BFF-to-BFF
+  audiences and purposes. It normalizes the authenticated email and fails
+  closed for weak secrets, altered payloads, expiry and cross-audience reuse;
+  it is not a browser-selected mode or an authorization capability.
+
+## 0.1.6 - 2026-10-04
+
+- Add one atomic accepted-handover persistence boundary for the
+  Encounter/EncounterHistory projection, future professional Group audience
+  revision and family-safe journey event.
+
+## 0.1.5 - 2026-10-04
+
+- Add the product-neutral confidential channel cache shared by SOSChain,
+  VetChain and UHC Next.js BFFs. One profile-and-channel document stores
+  materialized FHIR Communication messages behind the unlocked profile's
+  confidential-storage adapter, skips already opened source JWEs and keeps
+  subject, channel, recipients and payload out of cleartext persistence.
+
+## 0.1.4 - 2026-10-04
+
+- Add the injectable protected Bundle-sync service used by trusted runtimes for
+  clinical documents, Consent, emergency contacts and Encounter transfers.
+  It persists the exact retryable draft, enforces idempotency and confirms a
+  mutation only after authoritative provider readback.
+- Pin `sos-sdk-core-ts@0.5.1`, which owns the portable synchronization state
+  and response reconciliation contract.
+
+- Link the coordinated clinical accessor adoption boundary and keep optional
+  portal/assistant editor work out of the Node adapter until runtime behavior
+  is actually required.
+
+## 0.1.3 - 2026-09-27
+
+- Serialize Node test files so package and publication gates cannot exhaust a
+  shared developer workstation with parallel workers.
+- Require one version change only after grouped changes are merged and tested,
+  and preserve every exact published version on an immutable stable branch.
+
+- Add the product-neutral immutable prompt-audio Node runtime with stable
+  SHA-256 object keys, durable filesystem storage, concurrent-miss coalescing,
+  sequential prewarming and an ElevenLabs multilingual-v2 adapter.
+- Correct the package boundary: SOSChain, Vet and UHC may reuse this Node
+  runtime while keeping their sector policy in their own SDKs.
+- Add a product-neutral, create-only GCS prompt store so identical reviewed
+  assets can be reused across Vet, UHC and Connect ICA without sharing live
+  OTPs, personalized speech or clinical data.
+
+## 0.1.2
+
+- Add the Node CSPRNG adapter and factory for the shared multi-recipient ML-KEM
+  secure-message core used by written and binary-audio payloads.
+- Keep Node limited to validated `node:crypto.randomBytes` output; ML-KEM, KDF,
+  CEK wrapping and AES content protection remain in runtime-neutral core.
+
+## 0.1.1
+
+- Apply the blocking main-before-publish release contract to the SOSChain Node SDK documentation and repository skills.
+
+## 0.1.0
+
+- Initialize the SOSChain-specific Node SDK above `sos-sdk-core-ts@0.2.0`.
+- Add fail-closed authenticated emergency dispatch with HTTPS enforcement,
+  idempotency and acknowledgement validation.

package/NOTICE

@@ -0,0 +1,2 @@
+sos-sdk-node-ts
+Copyright 2026 Connecting Solution & Applications Ltd.

package/README.md

@@ -1,5 +1,14 @@
 # sos-sdk-node-ts
 
+Copyright 2026 Connecting Solution & Applications Ltd.
+Licensed under the Apache License, Version 2.0; see [`NOTICE`](NOTICE).
+
+## Public source history
+
+The public repository begins from a clean 2026 source snapshot. The retained
+[`CHANGELOG.md`](CHANGELOG.md) records package releases without republishing
+the former Git push history.
+
 Accepted Encounter handover persistence and future channel-audience
 reconciliation are documented in
 [`docs/ENCOUNTER_TRANSFER_AUDIENCE_PERSISTENCE.md`](docs/ENCOUNTER_TRANSFER_AUDIENCE_PERSISTENCE.md).
@@ -13,7 +22,7 @@ deterministic failures and never commit a local package reference. Staging
 begins only after exact registry packages are installed and verified.
 
 
-Product-neutral Node adapters shared by SOSChain, Vet and UHC trusted runtimes.
+Product-neutral Node adapters for trusted SOSCHAIN runtimes.
 
 ```text
 gdc-* frozen
@@ -27,8 +36,8 @@ sos-sdk-node-ts
 
 This package owns reusable server-side Node transport, credentials,
 persistence, jobs and prompt-audio runtime behavior. It does not own
-deterministic data contracts, common authorization or sector policy. Vet, UHC
-and SOSChain may consume it without depending on one another.
+deterministic data contracts, common authorization or sector policy. Downstream
+applications consume it without creating dependencies between one another.
 
 `BundleSyncDraftService` is the trusted-runtime adapter for the shared durable
 editor outbox. The application injects protected storage, payload protection
@@ -40,7 +49,7 @@ readback.
 It also does not duplicate the typed clinical Bundle editors exposed by the
 GDC Node SDK. Add a SOS Node adapter only when a real shared channel workflow
 requires runtime behavior, following the
-[SOS/Vet/UHC clinical accessor adoption matrix](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/CLINICAL_TYPED_ACCESSOR_ADOPTION.md).
+[clinical accessor adoption matrix](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/CLINICAL_TYPED_ACCESSOR_ADOPTION.md).
 Portals and assistants without that editor remain on their verified versions.
 
 The first adapter, `SosEmergencyDispatchClient`, sends an already-authorized
@@ -48,6 +57,18 @@ 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.
+
+`sos-sdk-node-ts/subject-card-directory-client` owns the complete asynchronous
+SOS GW Organization/License search and polling protocol used by every portal
+BFF. It matches exact aliases inside `Organization.sameAs` CSV values and
+rejects removed animal-card DID layouts before UI mapping. See
+[the authorized subject directory contract](docs/AUTHORIZED_SUBJECT_DIRECTORY.md).
+
 ## 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,5 @@ 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';
+export * from './subject-card-directory-client.js';

package/dist/index.js

@@ -5,3 +5,5 @@ 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';
+export * from './subject-card-directory-client.js';

package/dist/subject-card-directory-client.d.ts

@@ -0,0 +1,51 @@
+export type SosGatewayRouteContext = Readonly<{
+    tenantId: string;
+    jurisdiction: string;
+    sector: string;
+}>;
+export type AuthorizedSubjectVerifiedContact = Readonly<{
+    email?: string;
+    telephone?: string;
+}>;
+export type AuthorizedIndividualSubjectDirectoryInput = Readonly<{
+    verifiedContact: AuthorizedSubjectVerifiedContact;
+    requestThid?: string;
+    pollOptions?: Readonly<{
+        timeoutMs?: number;
+        intervalMs?: number;
+    }>;
+}>;
+export type AuthorizedIndividualSubject = Readonly<{
+    subjectDid: string;
+    organizationId?: string;
+    role?: string;
+    grantClaims: Readonly<Record<string, unknown>>;
+    authorizationEvidenceId?: string;
+    relatedPersonId?: string;
+    issuerDid?: string;
+    subjectClaims: Readonly<Record<string, unknown>>;
+}>;
+export type SosGatewaySubjectDirectoryClientOptions = Readonly<{
+    baseUrl: string;
+    bearerToken?: string;
+    appId?: string;
+    appVersion?: string;
+    defaultHeaders?: Readonly<Record<string, string>>;
+    requestTimeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}>;
+/**
+ * Shared trusted-BFF client for the canonical asynchronous SOS GW subject
+ * directory. The verified contact is discovery evidence only; results never
+ * grant a protected clinical or emergency action.
+ */
+export declare class SosGatewaySubjectDirectoryClient {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly requestTimeoutMs;
+    private readonly fetchImpl;
+    constructor(options: SosGatewaySubjectDirectoryClientOptions);
+    listAuthorizedIndividualSubjects(routeContext: SosGatewayRouteContext, input: AuthorizedIndividualSubjectDirectoryInput): Promise<AuthorizedIndividualSubject[]>;
+    private submitAndPoll;
+    private post;
+}

package/dist/subject-card-directory-client.js

@@ -0,0 +1,288 @@
+import { randomUUID } from 'node:crypto';
+import { parseAnimalCardDidWeb } from 'sos-data-utils-ts/animal-card-interoperability';
+import { buildGatewayApplicationHeaders } from 'sos-data-utils-ts/gateway-application-identity';
+const CLAIM_AUDIENCE_TYPE = 'org.schema.IndividualProduct.audience.audienceType';
+const CLAIM_ITEM_CONDITION = 'org.schema.IndividualProduct.itemCondition';
+const CLAIM_PERSON_EMAIL = 'org.schema.Person.email';
+const CLAIM_PERSON_TELEPHONE = 'org.schema.Person.telephone';
+const CLAIM_ORGANIZATION_SAME_AS = 'org.schema.Organization.sameAs';
+const CLAIM_ORGANIZATION_OWNER_EMAIL = 'org.schema.Organization.owner.email';
+const CLAIM_ORGANIZATION_OWNER_TELEPHONE = 'org.schema.Organization.owner.telephone';
+const CLAIM_ORGANIZATION_OWNER_IDENTIFIER = 'org.schema.Organization.owner.identifier.value';
+const CLAIM_ORGANIZATION_MEMBER_ROLE = 'org.schema.Organization.member.role';
+const CLAIM_RELATED_PERSON_ROLE = 'RelatedPerson.role';
+const CLAIM_OCCUPATION_IDENTIFIER = 'org.schema.Person.hasOccupation.identifier.value';
+/**
+ * Shared trusted-BFF client for the canonical asynchronous SOS GW subject
+ * directory. The verified contact is discovery evidence only; results never
+ * grant a protected clinical or emergency action.
+ */
+export class SosGatewaySubjectDirectoryClient {
+    baseUrl;
+    headers;
+    requestTimeoutMs;
+    fetchImpl;
+    constructor(options) {
+        this.baseUrl = normalizeBaseUrl(options.baseUrl);
+        this.requestTimeoutMs = positiveInteger(options.requestTimeoutMs ?? 15_000, 'request_timeout_invalid');
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.headers = Object.freeze({
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            ...(requiredOptional(options.bearerToken) ? { Authorization: `Bearer ${requiredOptional(options.bearerToken)}` } : {}),
+            ...(requiredOptional(options.appId)
+                ? buildGatewayApplicationHeaders({
+                    appId: requiredOptional(options.appId),
+                    appVersion: options.appVersion,
+                })
+                : {}),
+            ...(options.defaultHeaders ?? {}),
+        });
+    }
+    async listAuthorizedIndividualSubjects(routeContext, input) {
+        const context = normalizeRouteContext(routeContext);
+        const email = String(input.verifiedContact?.email || '').trim().toLowerCase();
+        const telephone = String(input.verifiedContact?.telephone || '').trim();
+        if (!email && !telephone)
+            throw new Error('verified_contact_required');
+        const organizationPath = gatewayPath(context, 'Organization', '_search');
+        const organizationPollPath = gatewayPath(context, 'Organization', '_search-response');
+        const ownerResult = await this.submitAndPoll(organizationPath, organizationPollPath, {
+            thid: input.requestThid || threadId('authorized-subject-owner'),
+            body: searchBundle('Family-search-v1.0', {
+                '@context': 'org.schema',
+                ...(email ? { [CLAIM_ORGANIZATION_OWNER_EMAIL]: email } : {}),
+                ...(telephone ? { [CLAIM_ORGANIZATION_OWNER_TELEPHONE]: telephone } : {}),
+            }),
+        }, input.pollOptions);
+        const ownedSubjects = readOwnedSubjects(ownerResult.body, context, { email, telephone });
+        const subjectsByDid = new Map(ownedSubjects.map((subject) => [subject.subjectDid, subject]));
+        const licensePath = gatewayPath(context, 'License', '_search');
+        const licensePollPath = gatewayPath(context, 'License', '_search-response');
+        const licenseResult = await this.submitAndPoll(licensePath, licensePollPath, {
+            thid: input.requestThid || threadId('authorized-subject-license'),
+            body: {
+                resourceType: 'Bundle',
+                type: 'batch',
+                data: [{
+                        request: { method: 'POST' },
+                        resource: { meta: { status: 'active', claims: {
+                                    '@context': 'org.schema',
+                                    [CLAIM_AUDIENCE_TYPE]: 'Individual',
+                                    [CLAIM_ITEM_CONDITION]: 'https://schema.org/UsedCondition',
+                                    ...(email ? { [CLAIM_PERSON_EMAIL]: email } : {}),
+                                    ...(telephone ? { [CLAIM_PERSON_TELEPHONE]: telephone } : {}),
+                                } } },
+                    }],
+            },
+        }, input.pollOptions);
+        const licenses = readAcceptedLicenses(licenseResult.body, context);
+        for (const license of licenses) {
+            if (subjectsByDid.has(license.subjectDid))
+                continue;
+            const organizationResult = await this.submitAndPoll(organizationPath, organizationPollPath, {
+                thid: threadId('authorized-subject-record'),
+                body: searchBundle('Family-search-v1.0', {
+                    '@context': 'org.schema',
+                    [CLAIM_ORGANIZATION_SAME_AS]: license.subjectDid,
+                }),
+            }, input.pollOptions);
+            const organization = readFirstOrganization(organizationResult.body);
+            if (!publicAliases(organization.claims[CLAIM_ORGANIZATION_SAME_AS]).includes(license.subjectDid))
+                continue;
+            subjectsByDid.set(license.subjectDid, Object.freeze({
+                subjectDid: license.subjectDid,
+                ...(organization.organizationId ? { organizationId: organization.organizationId } : {}),
+                ...(license.role ? { role: license.role } : {}),
+                grantClaims: license.grantClaims,
+                ...(license.authorizationEvidenceId ? { authorizationEvidenceId: license.authorizationEvidenceId } : {}),
+                ...(license.relatedPersonId ? { relatedPersonId: license.relatedPersonId } : {}),
+                ...(license.issuerDid ? { issuerDid: license.issuerDid } : {}),
+                subjectClaims: organization.claims,
+            }));
+        }
+        return [...subjectsByDid.values()];
+    }
+    async submitAndPoll(submitPath, pollPath, payload, options) {
+        const submit = await this.post(submitPath, payload);
+        requireSuccessfulResponse(submit, 'gateway_submit_failed');
+        const timeoutMs = positiveInteger(options?.timeoutMs ?? 30_000, 'poll_timeout_invalid');
+        const intervalMs = positiveInteger(options?.intervalMs ?? 250, 'poll_interval_invalid');
+        const started = Date.now();
+        for (;;) {
+            const poll = await this.post(pollPath, { thid: payload.thid });
+            if (poll.status !== 202) {
+                requireSuccessfulResponse(poll, 'gateway_poll_failed');
+                return poll;
+            }
+            if (Date.now() - started >= timeoutMs)
+                throw new Error('gateway_poll_timeout');
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    }
+    async post(path, payload) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+        try {
+            const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method: 'POST',
+                headers: this.headers,
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            const raw = await response.text();
+            let body = {};
+            if (raw) {
+                try {
+                    body = JSON.parse(raw);
+                }
+                catch {
+                    body = raw;
+                }
+            }
+            return { status: response.status, body };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+function searchBundle(type, claims) {
+    return {
+        resourceType: 'Bundle',
+        type: 'batch',
+        data: [{ type, request: { method: 'POST' }, resource: { meta: { claims } } }],
+    };
+}
+function readOwnedSubjects(body, context, verified) {
+    const resources = readData(body).flatMap((entry) => entry?.resource?.resourceType === 'Bundle' && Array.isArray(entry.resource.entry)
+        ? entry.resource.entry.map((item) => item?.resource).filter(Boolean)
+        : []);
+    return resources.flatMap((resource) => {
+        const claims = objectRecord(resource?.meta?.claims);
+        const ownerEmail = String(claims[CLAIM_ORGANIZATION_OWNER_EMAIL] || '').trim().toLowerCase();
+        const ownerTelephone = String(claims[CLAIM_ORGANIZATION_OWNER_TELEPHONE] || '').trim();
+        if (!((verified.email && ownerEmail === verified.email) || (verified.telephone && ownerTelephone === verified.telephone)))
+            return [];
+        const subjectDid = selectSubjectCardAlias(claims[CLAIM_ORGANIZATION_SAME_AS], context);
+        if (!subjectDid)
+            return [];
+        const role = context.sector === 'animal-care'
+            ? 'RESPRSN'
+            : String(claims[CLAIM_ORGANIZATION_MEMBER_ROLE] || '').trim();
+        const relatedPersonId = String(claims[CLAIM_ORGANIZATION_OWNER_IDENTIFIER] || '').trim();
+        return [Object.freeze({
+                subjectDid,
+                ...(String(resource?.id || '').trim() ? { organizationId: String(resource.id).trim() } : {}),
+                ...(role ? { role } : {}),
+                ...(relatedPersonId ? { relatedPersonId } : {}),
+                grantClaims: Object.freeze({}),
+                subjectClaims: claims,
+            })];
+    });
+}
+function readAcceptedLicenses(body, context) {
+    const rows = readData(body)[0]?.resource?.data;
+    if (!Array.isArray(rows))
+        return [];
+    return rows.flatMap((row) => {
+        const meta = objectRecord(row?.meta || row?.resource?.meta);
+        const subjectDid = String(meta.authorizedSubjectDid || '').trim();
+        if (!subjectDid)
+            return [];
+        requireCanonicalSubjectDid(subjectDid, context);
+        const claims = objectRecord(meta.claims);
+        const relatedRoles = String(claims[CLAIM_RELATED_PERSON_ROLE] || '')
+            .split(',').map((value) => value.trim().toUpperCase()).filter(Boolean);
+        const occupation = String(claims[CLAIM_OCCUPATION_IDENTIFIER] || '').trim();
+        const role = relatedRoles.includes('CAREGIVER') ? 'CAREGIVER' : relatedRoles[0] || occupation;
+        return [Object.freeze({
+                subjectDid,
+                ...(role ? { role } : {}),
+                grantClaims: claims,
+                ...(requiredOptional(meta.identifier) ? { authorizationEvidenceId: requiredOptional(meta.identifier) } : {}),
+                ...(requiredOptional(meta.relatedPersonId) ? { relatedPersonId: requiredOptional(meta.relatedPersonId) } : {}),
+                ...(requiredOptional(meta.issuerDid) ? { issuerDid: requiredOptional(meta.issuerDid) } : {}),
+            })];
+    });
+}
+function readFirstOrganization(body) {
+    const entry = readData(body)[0];
+    const claims = objectRecord(entry?.resource?.meta?.claims || entry?.meta?.claims);
+    const organizationId = String(entry?.resource?.id || entry?.id || '').trim();
+    return { claims, ...(organizationId ? { organizationId } : {}) };
+}
+function readData(body) {
+    const root = objectRecord(body);
+    const payload = objectRecord(root.body || root);
+    return Array.isArray(payload.data) ? payload.data : [];
+}
+function selectSubjectCardAlias(value, context) {
+    const aliases = publicAliases(value);
+    const candidate = aliases.find((alias) => context.sector === 'animal-care'
+        ? alias.includes(':card:vetchain:')
+        : alias.includes(':card:uhc:'));
+    if (!candidate)
+        return undefined;
+    requireCanonicalSubjectDid(candidate, context);
+    return candidate;
+}
+function requireCanonicalSubjectDid(subjectDid, context) {
+    if (context.sector === 'animal-care' && !parseAnimalCardDidWeb(subjectDid)) {
+        throw new Error('animal_card_did_invalid');
+    }
+    if (context.sector !== 'animal-care' && !/^did:web:[^\s]+:card:uhc:(?:personal|professional):[^\s]+$/i.test(subjectDid)) {
+        throw new Error('human_card_did_invalid');
+    }
+}
+function publicAliases(value) {
+    const values = Array.isArray(value) ? value : String(value ?? '').split(',');
+    return [...new Set(values.map((alias) => String(alias).trim()).filter(Boolean))];
+}
+function gatewayPath(context, resource, action) {
+    return `/${context.tenantId}/cds-${context.jurisdiction}/v1/${context.sector}/individual/org.schema/${resource}/${action}`;
+}
+function normalizeRouteContext(value) {
+    const segment = (input) => {
+        const normalized = String(input ?? '').trim();
+        if (!normalized || normalized.includes('/') || normalized === '.' || normalized === '..')
+            throw new Error('gateway_route_context_invalid');
+        return normalized;
+    };
+    return Object.freeze({
+        tenantId: segment(value.tenantId),
+        jurisdiction: segment(value.jurisdiction),
+        sector: segment(value.sector),
+    });
+}
+function normalizeBaseUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {
+        throw new Error('gateway_base_url_insecure');
+    }
+    return url.href.replace(/\/$/, '');
+}
+function requireSuccessfulResponse(response, code) {
+    if (response.status >= 200 && response.status < 300)
+        return;
+    const issue = objectRecord(response.body);
+    const diagnostics = Array.isArray(issue.issue)
+        ? issue.issue.map((entry) => String(objectRecord(entry).diagnostics || '').trim()).find(Boolean)
+        : undefined;
+    throw new Error(`${code}:${response.status}${diagnostics ? `:${diagnostics}` : ''}`);
+}
+function objectRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function requiredOptional(value) {
+    const normalized = String(value ?? '').trim();
+    return normalized || undefined;
+}
+function positiveInteger(value, code) {
+    if (!Number.isInteger(value) || value < 1)
+        throw new Error(code);
+    return value;
+}
+function threadId(prefix) {
+    return `${prefix}-${randomUUID()}`;
+}

package/docs/AUTHORIZED_SUBJECT_DIRECTORY.md

@@ -0,0 +1,48 @@
+# Authorized subject directory
+
+`SosGatewaySubjectDirectoryClient` is the single Node/BFF adapter for listing
+human and animal cards already associated with a verified contact. Portals do
+not build gateway paths, search Bundles or polling loops themselves.
+
+The client submits and polls these SOS GW routes:
+
+- `individual/org.schema/Organization/_search` and `_search-response` for
+  owner/contact lookup and exact `sameAs` resolution;
+- `individual/org.schema/License/_search` and `_search-response` for active,
+  accepted relationship evidence.
+
+`Organization.sameAs` remains the comma-separated flat claim used by the
+confidential resource. SOS GW indexes every normalized non-empty alias as its
+own protected indexed attribute. Exact resolution therefore searches one
+alias; a returned CSV is accepted only when it contains that exact alias.
+Animal entries accept only the current species-bound card profile, in which a
+seven-digit taxonomy context precedes the complete 21-digit card number. The
+removed split `jurisdiction5:animalId16` form fails closed. The exact profile
+literal remains owned and documented by the gateway that issues the card.
+
+Discovery is not authorization. A signed OpenID token is verified by the BFF;
+the SDK receives only the verified contact and uses the token as server-side
+transport evidence. Selecting a returned card creates no relationship and
+grants no clinical, communication or emergency access.
+
+## Multiple controllers and future rotation
+
+One child or animal may have multiple active controllers, such as two parents,
+two legal guardians or two responsible keepers. Each controller must have a
+separate governed `RelatedPerson` relationship and accepted licence/evidence.
+The subject card remains in the subject organization's
+`org.schema.Organization.sameAs`; it must not become
+`org.schema.Person.sameAs` of either controller.
+
+A later lifecycle contract may designate one active relationship as the
+principal administrative controller. Revoking that controller must revoke only
+that person's relationship, licence and controller keys, then explicitly
+promote another eligible active relationship. It must not rotate the child or
+animal card DID, replace the subject organization, or infer succession from
+CSV ordering. This principal-controller promotion flow is documented here but
+is not implemented by the directory client.
+
+Employees are a different subject. Their own professional aliases belong in
+`org.schema.Person.sameAs`; SOS GW normalizes that CSV, indexes every alias
+independently and projects the same aliases into the employee DID Document's
+`alsoKnownAs` alongside its organization-employee authorization URN.

package/docs/PROMPT_AUDIO_RUNTIME.md

@@ -23,10 +23,10 @@ developer machine.
 `FileSystemPromptAudioStore` supports local and demo execution. Production
 applications use `GcsPromptAudioStore` or implement `PromptAudioObjectStore`
 over another approved object store without changing the cache lifecycle.
-One GCS bucket may be shared by Vet, UHC and Connect ICA: the default object
-name has no product prefix and reuse occurs only when the complete canonical
-descriptor matches. Deployments may configure an isolation prefix when policy
-requires separate storage. `ElevenLabsPromptAudioSynthesizer`
+One object bucket may be shared by compatible trusted runtimes: the default
+object name has no product prefix and reuse occurs only when the complete
+canonical descriptor matches. Deployments may configure an isolation prefix
+when policy requires separate storage. `ElevenLabsPromptAudioSynthesizer`
 defaults to `eleven_multilingual_v2`; API keys stay in the trusted runtime and
 are neither logged nor included in an error.
 

package/docs/SDK_LAYERING.md

@@ -6,17 +6,13 @@ flowchart TB
   DATA --> CORE["sos-sdk-core-ts<br/>runtime-neutral authorization"]
   DATA --> NODE["sos-sdk-node-ts<br/>product-neutral Node adapters"]
   CORE --> NODE
-  NODE --> RUNTIME["SOSChain · Vet · UHC trusted Node runtimes"]
-  CORE --> VET["vet-sdk-core-ts"]
-  CORE --> UHC["uhc-sdk-core-ts"]
-  DATA --> VET
-  DATA --> UHC
+  NODE --> RUNTIME["SOSCHAIN trusted Node runtimes"]
 ```
 
 `sos-sdk-node-ts` is the common Node-runtime layer; it is not the SOSChain
 product SDK. Product-neutral storage, transport, credential, job and audio
-adapters belong here. Sector policy remains in the corresponding Vet, UHC or
-SOSChain package, and no shared package may depend back on a product SDK.
+adapters belong here. Sector policy remains in downstream applications, and no
+shared package may depend back on a product SDK.
 
 For immutable prompt audio, `sos-data-utils-ts/prompt-audio` produces the
 canonical descriptor and localized numeric-code fragments. This package

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-node-ts",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Product-neutral Node adapters shared by SOSChain, Vet and UHC runtimes",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -39,11 +39,21 @@
     "./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"
+    },
+    "./subject-card-directory-client": {
+      "types": "./dist/subject-card-directory-client.d.ts",
+      "default": "./dist/subject-card-directory-client.js"
     }
   },
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
+    "NOTICE",
     "docs"
   ],
   "scripts": {
@@ -55,6 +65,7 @@
     "prepack": "npm run check"
   },
   "dependencies": {
+    "sos-data-utils-ts": "0.6.13",
     "sos-sdk-core-ts": "0.5.2"
   },
   "devDependencies": {