sos-data-utils-ts 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.2
+
+- Add the product-neutral `speciesId7 + cardNumber20` preimage and lowercase
+  SHA3-256 asset-id builder shared by human and animal subject cards.
+- Bind human cards implicitly to NCBI Taxonomy `9606` as `0009606`, without
+  displaying species or asking a person for it.
+- Keep species outside every printed 21-digit card and exclude its final Damm
+  check digit from blockchain identity material.
+
 ## 0.2.1
 
 - Add the shared product-neutral Task artifact schema backed by canonical flat

package/README.md

@@ -22,6 +22,19 @@ The shared Task authoring schema uses canonical flat FHIR-like claims from
 correlation and output claims remain optional so the same contract supports
 human work items and machine-created asynchronous jobs.
 
+Subject-card index resolution uses one product-neutral 27-digit preimage:
+
+```text
+speciesId7 + first20DigitsOfValidatedCardNumber21
+```
+
+The final printed Damm digit is validation only and is excluded. Animal
+products provide the animal's NCBI Taxonomy identifier separately from the
+printed card. Human-health products use Homo sapiens (`9606`, projected as
+`0009606`) implicitly and never display or request species. Only the lowercase
+SHA3-256 digest of the 27 ASCII digits may cross the blockchain boundary; it
+locates the active index provider and grants no data access.
+
 The organization-verification contract resolves policy by business sector and
 ISO country. The governed CA/US profiles are:
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './bff-api.js';
 export * from './organization-verification-policy.js';
 export * from './task-artifact-schema.js';
+export * from './subject-card-index.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from './bff-api.js';
 export * from './organization-verification-policy.js';
 export * from './task-artifact-schema.js';
+export * from './subject-card-index.js';

package/dist/subject-card-index.d.ts

@@ -0,0 +1,41 @@
+export type SubjectSpeciesId7 = string;
+export type SubjectCardNumber21 = string;
+export type SubjectCardIndexCanonicalNumericId27 = string;
+export type SubjectCardIndexAssetId = string;
+/** Canonical NCBI Taxonomy identifier for Homo sapiens. */
+export declare const HUMAN_NCBI_TAXONOMY_ID: "9606";
+/** Seven-digit taxonomy projection used implicitly for human-card ledger keys. */
+export declare const HUMAN_SPECIES_ID7: "0009606";
+/**
+ * Projects a positive NCBI Taxonomy identifier to exactly seven decimal digits.
+ *
+ * This helper is product-neutral and therefore accepts Homo sapiens. A
+ * veterinary caller remains responsible for rejecting `9606` as an animal.
+ */
+export declare function normalizeSubjectSpeciesId7(ncbiTaxonomyId: string): SubjectSpeciesId7;
+/**
+ * Builds the common 27-digit lookup preimage for a validated 21-digit card.
+ *
+ * The visible Damm digit is excluded because it detects transcription errors
+ * rather than contributing identity material. Species remains outside the
+ * printed number but prevents equal card payloads for different species from
+ * sharing one ledger key. Human callers pass `9606` (normally via the fixed
+ * `HUMAN_NCBI_TAXONOMY_ID` constant); they never ask a person for a species.
+ */
+export declare function buildSubjectCardIndexCanonicalNumericId27(input: Readonly<{
+    ncbiTaxonomyId: string;
+    cardNumber21: string;
+}>): SubjectCardIndexCanonicalNumericId27;
+/**
+ * Returns lowercase hexadecimal SHA3-256 of the ASCII 27-digit preimage.
+ *
+ * Only this opaque digest crosses the blockchain boundary. The card number,
+ * taxonomy identifier and canonical preimage must not be written to the
+ * ledger. Resolving the digest locates an index provider; it grants no access.
+ */
+export declare function buildSubjectCardIndexAssetId(input: Readonly<{
+    ncbiTaxonomyId: string;
+    cardNumber21: string;
+}>): Promise<SubjectCardIndexAssetId>;
+/** Validates the exact lowercase SHA3-256 hexadecimal ledger-key profile. */
+export declare function isSubjectCardIndexAssetId(value: string): value is SubjectCardIndexAssetId;

package/dist/subject-card-index.js

@@ -0,0 +1,69 @@
+// Copyright 2026 Connecting Solution & Applications Ltd under the Apache License, Version 2.0.
+import { bytesToHexString } from 'gdc-common-utils-ts/utils/base-convert';
+import { SHA3_256_MULTIHASH_PROFILE } from 'gdc-common-utils-ts/utils/multiformat-profile';
+import { computeDammCheckDigit } from 'gdc-common-utils-ts/utils/unified-health-id';
+/** Canonical NCBI Taxonomy identifier for Homo sapiens. */
+export const HUMAN_NCBI_TAXONOMY_ID = '9606';
+/** Seven-digit taxonomy projection used implicitly for human-card ledger keys. */
+export const HUMAN_SPECIES_ID7 = '0009606';
+/**
+ * Projects a positive NCBI Taxonomy identifier to exactly seven decimal digits.
+ *
+ * This helper is product-neutral and therefore accepts Homo sapiens. A
+ * veterinary caller remains responsible for rejecting `9606` as an animal.
+ */
+export function normalizeSubjectSpeciesId7(ncbiTaxonomyId) {
+    const source = String(ncbiTaxonomyId || '').trim();
+    if (!/^\d{1,7}$/.test(source)) {
+        throw new TypeError('NCBI Taxonomy identifier must contain at most seven digits.');
+    }
+    const normalized = source.replace(/^0+/, '') || '0';
+    if (normalized === '0') {
+        throw new TypeError('NCBI Taxonomy identifier must be positive.');
+    }
+    return normalized.padStart(7, '0');
+}
+/**
+ * Builds the common 27-digit lookup preimage for a validated 21-digit card.
+ *
+ * The visible Damm digit is excluded because it detects transcription errors
+ * rather than contributing identity material. Species remains outside the
+ * printed number but prevents equal card payloads for different species from
+ * sharing one ledger key. Human callers pass `9606` (normally via the fixed
+ * `HUMAN_NCBI_TAXONOMY_ID` constant); they never ask a person for a species.
+ */
+export function buildSubjectCardIndexCanonicalNumericId27(input) {
+    const speciesId7 = normalizeSubjectSpeciesId7(input.ncbiTaxonomyId);
+    const cardNumber21 = normalizeCardNumber21(input.cardNumber21);
+    return `${speciesId7}${cardNumber21.slice(0, 20)}`;
+}
+/**
+ * Returns lowercase hexadecimal SHA3-256 of the ASCII 27-digit preimage.
+ *
+ * Only this opaque digest crosses the blockchain boundary. The card number,
+ * taxonomy identifier and canonical preimage must not be written to the
+ * ledger. Resolving the digest locates an index provider; it grants no access.
+ */
+export async function buildSubjectCardIndexAssetId(input) {
+    const canonicalNumericId27 = buildSubjectCardIndexCanonicalNumericId27(input);
+    const digest = SHA3_256_MULTIHASH_PROFILE.digest(new TextEncoder().encode(canonicalNumericId27));
+    return bytesToHexString(digest);
+}
+/** Validates the exact lowercase SHA3-256 hexadecimal ledger-key profile. */
+export function isSubjectCardIndexAssetId(value) {
+    return /^[a-f0-9]{64}$/.test(String(value || ''));
+}
+function normalizeCardNumber21(value) {
+    const source = String(value || '').trim();
+    if (!source || !/^[0-9 -]+$/.test(source)) {
+        throw new TypeError('cardNumber21 must contain only decimal digits, spaces or hyphens.');
+    }
+    const digits = source.replace(/[ -]/g, '');
+    if (!/^\d{21}$/.test(digits)) {
+        throw new TypeError('cardNumber21 must contain exactly 21 digits.');
+    }
+    if (computeDammCheckDigit(digits.slice(0, 20)) !== digits.slice(20)) {
+        throw new TypeError('cardNumber21 has an invalid Damm check digit.');
+    }
+    return digits;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-data-utils-ts",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Product-neutral SOS channel and BFF contract utilities",
   "license": "Apache-2.0",
   "type": "module",
@@ -22,6 +22,10 @@
     "./task-artifact-schema": {
       "types": "./dist/task-artifact-schema.d.ts",
       "default": "./dist/task-artifact-schema.js"
+    },
+    "./subject-card-index": {
+      "types": "./dist/subject-card-index.d.ts",
+      "default": "./dist/subject-card-index.js"
     }
   },
   "files": [