sos-sdk-node-ts 0.1.17 → 0.1.19

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 0.1.19 - 2026-11-04
+
+- Discover existing professional employee DID documents from an exact
+  configured provider using country, optional regional jurisdiction,
+  organization legal identifier, sector and verified email. Return only roles
+  whose authoritative DID document binds the expected employee authorization.
+
+## 0.1.18 - 2026-11-03
+
+- Add a trusted Node client for subject-card provider advertisements and
+  federated authorized-subject reads. Provider failures remain visible while
+  successful directories continue to return their cards.
+- Consume `sos-data-utils-ts@0.6.21` and `sos-sdk-core-ts@0.5.4`, the exact
+  published provider-discovery contracts validated by this release.
+
 ## 0.1.17 - 2026-10-22
 
 - Consume the shared historical NCBI OBO taxonomy read compatibility used by

package/README.md

@@ -78,6 +78,14 @@ 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).
 
+`sos-sdk-node-ts/portable-professional-evidence` lets a trusted BFF discover
+existing professional roles from an exact configured provider using country,
+optional ISO 3166-2 region, organization legal identifier, sector and verified
+email. It derives candidate employee DIDs only from the governed role catalog
+and returns a role only when the authoritative employee DID document binds the
+expected authorization URN. These routing inputs and a later browser role
+choice grant no authority by themselves.
+
 `sos-sdk-node-ts/host-organization-directory-client` is the separate trusted-
 BFF client for a host operator's organization directory. It sends the
 canonical `org.schema/Organization/_search` request, polls the matching

package/dist/index.d.ts

@@ -11,3 +11,4 @@ export * from './server-passkey-profile.js';
 export * from './host-organization-directory-client.js';
 export * from './secure-organization-registration.js';
 export * from './portable-professional-evidence.js';
+export * from './subject-card-provider-catalog-client.js';

package/dist/index.js

@@ -11,3 +11,4 @@ export * from './server-passkey-profile.js';
 export * from './host-organization-directory-client.js';
 export * from './secure-organization-registration.js';
 export * from './portable-professional-evidence.js';
+export * from './subject-card-provider-catalog-client.js';

package/dist/portable-professional-evidence.d.ts

@@ -14,6 +14,21 @@ export type PortableProfessionalEnrollment = Readonly<{
     jurisdiction: string;
     role: string;
 }>;
+/**
+ * Finds the signed professional DID documents already published beneath one
+ * exact organization. Country, optional region, legal identifier and sector
+ * only reconstruct routing; the authoritative employee DID and authorization
+ * URN still determine every returned role.
+ */
+export declare function resolvePortableProfessionalOrganizationEnrollments(input: Readonly<{
+    country: unknown;
+    region?: unknown;
+    organizationIdentifier: unknown;
+    sector: unknown;
+    verifiedEmail: unknown;
+    providers: readonly PortableProfessionalProvider[];
+    fetchImpl?: typeof fetch;
+}>): Promise<readonly PortableProfessionalEnrollment[]>;
 /**
  * Derives routing candidates only from evidence shape plus a server-owned host
  * and sector allowlist. The returned candidate grants no authority: the signed

package/dist/portable-professional-evidence.js

@@ -1,6 +1,7 @@
 import { createPublicKey, verify } from 'node:crypto';
 import { inflateRawSync } from 'node:zlib';
 import { buildProfessionalDidWeb } from 'gdc-common-utils-ts/utils/did';
+import { getHealthcareProfessionalRolesBySector } from 'gdc-common-utils-ts/constants/healthcare';
 const EMPLOYEE_AUTHORIZATION_URN_PATTERN = /^urn:cds-([a-z]{2}(?:-[a-z0-9]{2,3})?):v[1-9][0-9]*:organization:([a-z][a-z0-9-]*):([^:]+):member:(z[1-9A-HJ-NP-Za-km-z]+):([0-9]+)$/i;
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
@@ -16,6 +17,102 @@ function identifiers(resource) {
 function providerIssuer(provider) {
     return `${new URL(provider.baseUrl).origin}/${encodeURIComponent(provider.tenantId)}/cds-${encodeURIComponent(provider.jurisdiction)}/v1/${encodeURIComponent(provider.sector)}`;
 }
+async function resolveProviderDid(provider, fetchImpl) {
+    const response = await fetchImpl(`${providerIssuer(provider)}/.well-known/did.json`, {
+        headers: { accept: 'application/did+json, application/json' },
+    });
+    if (!response.ok)
+        throw new TypeError('professional_tenant_did_unavailable');
+    const document = record(await response.json());
+    const providerDid = text(document.id);
+    const expectedContext = `:${provider.tenantId}:cds-${provider.jurisdiction}:v1:${provider.sector}`;
+    const services = Array.isArray(document.service) ? document.service : [];
+    const hasJwks = services.some(service => text(record(service).type) === 'JsonWebKeyService2020'
+        && /^https:\/\//i.test(text(record(service).serviceEndpoint)));
+    if (!providerDid.startsWith('did:web:') || !providerDid.endsWith(expectedContext) || !hasJwks) {
+        throw new TypeError('professional_tenant_did_invalid');
+    }
+    return providerDid;
+}
+/**
+ * Finds the signed professional DID documents already published beneath one
+ * exact organization. Country, optional region, legal identifier and sector
+ * only reconstruct routing; the authoritative employee DID and authorization
+ * URN still determine every returned role.
+ */
+export async function resolvePortableProfessionalOrganizationEnrollments(input) {
+    const country = text(input.country).toUpperCase();
+    const region = text(input.region).toUpperCase();
+    const jurisdiction = region || country;
+    const organizationIdentifier = text(input.organizationIdentifier);
+    const sector = text(input.sector).toLowerCase();
+    const verifiedEmail = text(input.verifiedEmail).toLowerCase();
+    if (!/^[A-Z]{2}$/.test(country))
+        throw new TypeError('professional_country_invalid');
+    if (region && (!new RegExp(`^${country}-[A-Z0-9]{1,3}$`).test(region))) {
+        throw new TypeError('professional_region_country_mismatch');
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{1,127}$/.test(organizationIdentifier)) {
+        throw new TypeError('professional_organization_identifier_invalid');
+    }
+    if (!verifiedEmail)
+        throw new TypeError('verified_email_required');
+    const roleCatalog = getHealthcareProfessionalRolesBySector(sector);
+    const roles = Object.values(roleCatalog).filter(role => role.claim.startsWith('ISCO-08|'));
+    if (!roles.length)
+        throw new TypeError('professional_sector_not_allowed');
+    const providers = input.providers.filter(provider => provider.tenantId === organizationIdentifier
+        && provider.jurisdiction.toUpperCase() === jurisdiction
+        && provider.sector.toLowerCase() === sector);
+    if (providers.length === 0)
+        throw new TypeError('professional_provider_not_found');
+    if (providers.length > 1)
+        throw new TypeError('multiple_professional_providers_found');
+    const provider = providers[0];
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const providerDid = await resolveProviderDid(provider, fetchImpl);
+    const results = [];
+    for (const role of roles) {
+        const professionalDid = buildProfessionalDidWeb({
+            organizationDidWeb: providerDid,
+            email: verifiedEmail,
+            role: role.claim,
+        });
+        const memberPath = professionalDid.slice(`${providerDid}:employee:`.length);
+        const memberId = memberPath.slice(0, memberPath.indexOf(':'));
+        const didUrl = `${providerIssuer(provider)}/employee/${encodeURIComponent(memberId)}/${encodeURIComponent(role.claim)}/did.json`;
+        const response = await fetchImpl(didUrl, { headers: { accept: 'application/did+json, application/json' } });
+        if (response.status === 404)
+            continue;
+        if (!response.ok)
+            throw new TypeError('professional_directory_unavailable');
+        const document = record(await response.json());
+        if (text(document.id) !== professionalDid)
+            throw new TypeError('professional_did_invalid');
+        const employeeAuthorizationUrn = (Array.isArray(document.alsoKnownAs) ? document.alsoKnownAs : [])
+            .map(String).find(value => EMPLOYEE_AUTHORIZATION_URN_PATTERN.test(value)) || '';
+        const authorization = EMPLOYEE_AUTHORIZATION_URN_PATTERN.exec(employeeAuthorizationUrn);
+        if (!authorization
+            || authorization[1].toUpperCase() !== jurisdiction
+            || authorization[3] !== organizationIdentifier
+            || authorization[5] !== role.code) {
+            throw new TypeError('professional_credential_binding_invalid');
+        }
+        results.push(Object.freeze({
+            sector: provider.sector,
+            employeeAuthorizationUrn,
+            professionalDid,
+            providerDid,
+            gatewayBaseUrl: new URL(provider.baseUrl).origin,
+            tenantId: provider.tenantId,
+            jurisdiction,
+            role: role.claim,
+        }));
+    }
+    if (!results.length)
+        throw new TypeError('professional_profile_not_found');
+    return Object.freeze(results);
+}
 function decodeShcQr(value) {
     const normalized = text(value);
     if (!/^shc:\/\d+$/.test(normalized))
@@ -231,20 +328,7 @@ export async function resolvePortableProfessionalEnrollment(input) {
         throw new TypeError('multiple_professional_providers_found');
     const provider = matches[0];
     const gatewayBaseUrl = new URL(provider.baseUrl).origin;
-    const response = await fetchImpl(`${providerIssuer(provider)}/.well-known/did.json`, {
-        headers: { accept: 'application/did+json, application/json' },
-    });
-    if (!response.ok)
-        throw new TypeError('professional_tenant_did_unavailable');
-    const document = record(await response.json());
-    const providerDid = text(document.id);
-    const expectedContext = `:${provider.tenantId}:cds-${provider.jurisdiction}:v1:${provider.sector}`;
-    const services = Array.isArray(document.service) ? document.service : [];
-    const hasJwks = services.some(service => text(record(service).type) === 'JsonWebKeyService2020'
-        && /^https:\/\//i.test(text(record(service).serviceEndpoint)));
-    if (!providerDid.startsWith('did:web:') || !providerDid.endsWith(expectedContext) || !hasJwks) {
-        throw new TypeError('professional_tenant_did_invalid');
-    }
+    const providerDid = await resolveProviderDid(provider, fetchImpl);
     const role = `ISCO-08|${authorizationRoleCode}`;
     const professionalDid = buildProfessionalDidWeb({ organizationDidWeb: providerDid, email: verifiedEmail, role });
     return Object.freeze({

package/dist/subject-card-provider-catalog-client.d.ts

@@ -0,0 +1,32 @@
+import type { SubjectCardProviderDescriptor } from 'sos-data-utils-ts/subject-card-directory';
+import { type SubjectCardProviderDiscoveryFilter } from 'sos-sdk-core-ts/subject-card-provider-discovery';
+import { type AuthorizedIndividualSubject, type AuthorizedSubjectVerifiedContact } from './subject-card-directory-client.js';
+export type SosSubjectCardProviderCatalogClientOptions = Readonly<{
+    catalogUrl: string;
+    bearerToken?: string;
+    fetchImpl?: typeof fetch;
+}>;
+/** Reads public provider advertisements from a data-space JSON:API catalog. */
+export declare class SosSubjectCardProviderCatalogClient {
+    private readonly catalogUrl;
+    private readonly bearerToken?;
+    private readonly fetchImpl;
+    constructor(options: SosSubjectCardProviderCatalogClientOptions);
+    discover(filter: SubjectCardProviderDiscoveryFilter): Promise<readonly SubjectCardProviderDescriptor[]>;
+}
+export type FederatedProviderSubject = Readonly<{
+    providerId: string;
+    subject: AuthorizedIndividualSubject;
+}>;
+export type FederatedProviderSubjectResult = Readonly<{
+    subjects: readonly FederatedProviderSubject[];
+    unavailableProviderIds: readonly string[];
+}>;
+/** Queries every advertised directory independently and keeps partial success. */
+export declare function readFederatedProviderSubjects(input: Readonly<{
+    providers: readonly SubjectCardProviderDescriptor[];
+    subjectKind?: 'human' | 'animal';
+    verifiedContact: AuthorizedSubjectVerifiedContact;
+    bearerToken?: string;
+    readProvider?: (provider: SubjectCardProviderDescriptor, verifiedContact: AuthorizedSubjectVerifiedContact) => Promise<readonly AuthorizedIndividualSubject[]>;
+}>): Promise<FederatedProviderSubjectResult>;

package/dist/subject-card-provider-catalog-client.js

@@ -0,0 +1,100 @@
+import { discoverSubjectCardProviders, } from 'sos-sdk-core-ts/subject-card-provider-discovery';
+import { SosGatewaySubjectDirectoryClient, } from './subject-card-directory-client.js';
+/** Reads public provider advertisements from a data-space JSON:API catalog. */
+export class SosSubjectCardProviderCatalogClient {
+    catalogUrl;
+    bearerToken;
+    fetchImpl;
+    constructor(options) {
+        this.catalogUrl = secureUrl(options.catalogUrl);
+        this.bearerToken = optional(options.bearerToken);
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async discover(filter) {
+        const url = new URL(this.catalogUrl);
+        url.searchParams.set('subjectKind', filter.subjectKind);
+        url.searchParams.set('operation', filter.operation);
+        const response = await this.fetchImpl(url, {
+            headers: {
+                Accept: 'application/vnd.api+json',
+                ...(this.bearerToken ? { Authorization: `Bearer ${this.bearerToken}` } : {}),
+            },
+        });
+        if (!response.ok)
+            throw new Error(`provider_catalog_failed:${response.status}`);
+        const body = await response.json();
+        if (!Array.isArray(body.data))
+            throw new Error('provider_catalog_response_invalid');
+        const catalog = body.data.map(entry => {
+            const row = record(entry);
+            if (row.type !== 'subject-card-provider')
+                throw new Error('provider_catalog_entry_invalid');
+            return record(row.attributes);
+        });
+        return discoverSubjectCardProviders(catalog, filter);
+    }
+}
+/** Queries every advertised directory independently and keeps partial success. */
+export async function readFederatedProviderSubjects(input) {
+    const providers = discoverSubjectCardProviders(input.providers, {
+        subjectKind: input.subjectKind ?? commonSubjectKind(input.providers),
+        operation: 'directory',
+    });
+    const readProvider = input.readProvider ?? (async (provider) => {
+        const route = parseDirectoryRoute(provider.directoryRoute);
+        const client = new SosGatewaySubjectDirectoryClient({
+            baseUrl: route.baseUrl,
+            bearerToken: input.bearerToken,
+        });
+        return client.listAuthorizedIndividualSubjects(route.context, {
+            verifiedContact: input.verifiedContact,
+        });
+    });
+    const settled = await Promise.allSettled(providers.map(provider => readProvider(provider, input.verifiedContact)));
+    const subjects = [];
+    const unavailableProviderIds = [];
+    for (const [index, result] of settled.entries()) {
+        const provider = providers[index];
+        if (result.status === 'rejected') {
+            unavailableProviderIds.push(provider.providerId);
+            continue;
+        }
+        for (const subject of result.value)
+            subjects.push(Object.freeze({ providerId: provider.providerId, subject }));
+    }
+    return Object.freeze({
+        subjects: Object.freeze(subjects),
+        unavailableProviderIds: Object.freeze(unavailableProviderIds),
+    });
+}
+function commonSubjectKind(providers) {
+    const kinds = new Set(providers.flatMap(provider => provider.subjectKinds));
+    if (kinds.size !== 1)
+        throw new Error('provider_subject_kind_filter_required');
+    return [...kinds][0];
+}
+function parseDirectoryRoute(value) {
+    const url = secureUrl(value);
+    const segments = url.pathname.split('/').filter(Boolean);
+    if (segments.length !== 4 || !segments[1]?.startsWith('cds-') || segments[2] !== 'v1') {
+        throw new Error('provider_directory_route_invalid');
+    }
+    return Object.freeze({
+        baseUrl: url.origin,
+        context: Object.freeze({ tenantId: segments[0], jurisdiction: segments[1].slice(4), sector: segments[3] }),
+    });
+}
+function secureUrl(value) {
+    const url = new URL(value);
+    const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local))
+        throw new Error('provider_url_insecure');
+    return url;
+}
+function optional(value) {
+    const normalized = String(value ?? '').trim();
+    return normalized || undefined;
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-node-ts",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Product-neutral Node adapters shared by SOSChain, Vet and UHC runtimes",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -59,6 +59,10 @@
     "./portable-professional-evidence": {
       "types": "./dist/portable-professional-evidence.d.ts",
       "default": "./dist/portable-professional-evidence.js"
+    },
+    "./subject-card-provider-catalog-client": {
+      "types": "./dist/subject-card-provider-catalog-client.d.ts",
+      "default": "./dist/subject-card-provider-catalog-client.js"
     }
   },
   "files": [
@@ -80,8 +84,8 @@
     "@simplewebauthn/server": "13.3.2",
     "gdc-common-utils-ts": "2.9.30",
     "gdc-sdk-node-ts": "2.9.32",
-    "sos-data-utils-ts": "0.6.17",
-    "sos-sdk-core-ts": "0.5.2"
+    "sos-data-utils-ts": "0.6.21",
+    "sos-sdk-core-ts": "0.5.4"
   },
   "devDependencies": {
     "@types/node": "^24.10.0",