sos-sdk-node-ts 0.1.18 → 0.1.19

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## 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

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-node-ts",
-  "version": "0.1.18",
+  "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",