sos-sdk-node-ts 0.1.15 → 0.1.16

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.1.16 - 2026-10-22
+
+- Recover checksum-valid historical animal cards through the provider's exact
+  stored alias and explicit taxonomy claim, while returning only the current
+  species-bound card identity to portals. New writes still reject the retired
+  identifier form.
+
 ## 0.1.15 - 2026-10-22
 
 - Add product-neutral verification and resolution for an existing professional

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

@@ -17,6 +17,8 @@ export type AuthorizedIndividualSubjectDirectoryInput = Readonly<{
 }>;
 export type AuthorizedIndividualSubject = Readonly<{
     subjectDid: string;
+    /** Historical provider lookup alias retained only while its record is migrated. */
+    sourceSubjectDid?: string;
     organizationId?: string;
     role?: string;
     grantClaims: Readonly<Record<string, unknown>>;

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

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { parseAnimalCardDidWeb } from 'sos-data-utils-ts/animal-card-interoperability';
+import { migrateHistoricalAnimalCardDidWeb, parseAnimalCardDidWeb, parseNcbiTaxonomyUri, } 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';
@@ -10,6 +10,7 @@ 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_ORGANIZATION_MEMBER_ADDITIONAL_TYPE = 'org.schema.Organization.member.additionalType';
 const CLAIM_RELATED_PERSON_ROLE = 'RelatedPerson.role';
 const CLAIM_OCCUPATION_IDENTIFIER = 'org.schema.Person.hasOccupation.identifier.value';
 /**
@@ -93,8 +94,10 @@ export class SosGatewaySubjectDirectoryClient {
             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,
+            const resolvedDid = resolveSubjectCardDid(license.subjectDid, context, organization.claims);
+            subjectsByDid.set(resolvedDid.subjectDid, Object.freeze({
+                subjectDid: resolvedDid.subjectDid,
+                ...(resolvedDid.sourceSubjectDid ? { sourceSubjectDid: resolvedDid.sourceSubjectDid } : {}),
                 ...(organization.organizationId ? { organizationId: organization.organizationId } : {}),
                 ...(license.role ? { role: license.role } : {}),
                 grantClaims: license.grantClaims,
@@ -167,15 +170,17 @@ function readOwnedSubjects(body, context, verified) {
         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)
+        const sourceSubjectDid = selectSubjectCardAlias(claims[CLAIM_ORGANIZATION_SAME_AS], context);
+        if (!sourceSubjectDid)
             return [];
+        const resolvedDid = resolveSubjectCardDid(sourceSubjectDid, context, claims);
         const role = isAnimalSector(context.sector)
             ? 'RESPRSN'
             : String(claims[CLAIM_ORGANIZATION_MEMBER_ROLE] || '').trim();
         const relatedPersonId = String(claims[CLAIM_ORGANIZATION_OWNER_IDENTIFIER] || '').trim();
         return [Object.freeze({
-                subjectDid,
+                subjectDid: resolvedDid.subjectDid,
+                ...(resolvedDid.sourceSubjectDid ? { sourceSubjectDid: resolvedDid.sourceSubjectDid } : {}),
                 ...(String(resource?.id || '').trim() ? { organizationId: String(resource.id).trim() } : {}),
                 ...(role ? { role } : {}),
                 ...(relatedPersonId ? { relatedPersonId } : {}),
@@ -195,7 +200,6 @@ function readAcceptedLicenses(body, context) {
             return [];
         if (!isSubjectCardCandidate(subjectDid, context))
             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);
@@ -229,9 +233,29 @@ function selectSubjectCardAlias(value, context) {
         : alias.includes(':card:uhc:'));
     if (!candidate)
         return undefined;
-    requireCanonicalSubjectDid(candidate, context);
+    if (!isAnimalSector(context.sector))
+        requireCanonicalSubjectDid(candidate, context);
     return candidate;
 }
+function resolveSubjectCardDid(sourceSubjectDid, context, claims) {
+    if (!isAnimalSector(context.sector)) {
+        requireCanonicalSubjectDid(sourceSubjectDid, context);
+        return Object.freeze({ subjectDid: sourceSubjectDid });
+    }
+    if (parseAnimalCardDidWeb(sourceSubjectDid)) {
+        return Object.freeze({ subjectDid: sourceSubjectDid });
+    }
+    const taxonomyId = parseNcbiTaxonomyUri(claims[CLAIM_ORGANIZATION_MEMBER_ADDITIONAL_TYPE]);
+    const migrated = taxonomyId
+        ? migrateHistoricalAnimalCardDidWeb(sourceSubjectDid, taxonomyId)
+        : undefined;
+    if (!migrated)
+        throw new Error('animal_card_did_invalid');
+    return Object.freeze({
+        subjectDid: migrated.cardDid,
+        sourceSubjectDid: migrated.sourceCardDid,
+    });
+}
 function requireCanonicalSubjectDid(subjectDid, context) {
     if (isAnimalSector(context.sector) && !parseAnimalCardDidWeb(subjectDid)) {
         throw new Error('animal_card_did_invalid');

package/docs/AUTHORIZED_SUBJECT_DIRECTORY.md

@@ -15,10 +15,14 @@ The client submits and polls these SOS GW routes:
 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.
+Animal entries returned to consumers use only the current species-bound card
+profile, in which a seven-digit taxonomy context precedes the complete
+21-digit card number. A retired split `jurisdiction5:animalId16` alias can be
+used only to find an existing provider record: its historical checksum and the
+record's explicit animal taxonomy claim must validate before the client derives
+the current identifier. The client retains the old alias separately for exact
+provider lookup and never accepts it for a new write. 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-node-ts",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Product-neutral Node adapters shared by SOSChain, Vet and UHC runtimes",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -80,7 +80,7 @@
     "@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.13",
+    "sos-data-utils-ts": "0.6.16",
     "sos-sdk-core-ts": "0.5.2"
   },
   "devDependencies": {