vet-sdk-core-ts 0.4.6 → 0.4.7

package/README.md

@@ -6,6 +6,18 @@ UHC SDK packages and must not import them.
 The SDK consumes governed browser-safe values from `vet-data-utils-ts` and
 owns gateway request construction. GW VET remains the policy authority.
 
+## Reusable professional BFF
+
+`ReusableProfessionalBffClient` exposes the complete business-level portal
+journey for UHC UNID, VetChain and SOSChain adapters: post-login profile gate,
+organization admission and review, activation, licences, employees, individual
+creation, clinical data, secondary-use consent, Digital Twin search and
+break-glass. Product adapters inject sectors, translations, routes and policy.
+The client rejects GW, wallet, DCR, SMART and VP plumbing from browser payloads.
+
+Start with [`docs/101-REUSABLE_PROFESSIONAL_BFF.md`](docs/101-REUSABLE_PROFESSIONAL_BFF.md)
+and its commented snippet.
+
 ## Professional break-glass authorization
 
 Node BFFs call `buildVeterinaryBreakGlassSmartAuthorization` with only the

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export * from "./animal-identity.js";
 export * from "./gateway-contract.js";
 export * from "./card-issuance.js";
 export * from "./animal-onboarding.js";
+export * from "./reusable-bff.js";
 export * from "vet-data-utils-ts";

package/dist/index.js

@@ -3,4 +3,5 @@ export * from "./animal-identity.js";
 export * from "./gateway-contract.js";
 export * from "./card-issuance.js";
 export * from "./animal-onboarding.js";
+export * from "./reusable-bff.js";
 export * from "vet-data-utils-ts";

package/dist/reusable-bff.d.ts

@@ -0,0 +1,97 @@
+export type ReusableBffProductExtension = Readonly<{
+    /** Stable adapter id used for diagnostics; never an authorization claim. */
+    productId: string;
+    /** Exact governed sectors rendered by this product. Empty means render none. */
+    allowedSectors: readonly string[];
+    baseUrl?: string;
+    routes?: Partial<ReusableProfessionalBffRoutes>;
+    fetch?: typeof globalThis.fetch;
+}>;
+export type ReusableProfessionalBffRoutes = Readonly<{
+    initialPin: string;
+    initialPinUnlock: string;
+    profileActivation: string;
+    employeeActivation: string;
+    applications: string;
+    applicationReview: string;
+    licenses: string;
+    employeeInvitations: string;
+    employeeLifecycle: string;
+    subject: string;
+    digitalTwinSearch: string;
+    breakGlass: string;
+}>;
+export declare const DefaultReusableProfessionalBffRoutes: ReusableProfessionalBffRoutes;
+type BusinessPayload = Readonly<Record<string, unknown>>;
+/**
+ * Business-level client for the reusable professional BFF shared by UHC UNID,
+ * VetChain and SOSChain product adapters.
+ *
+ * Callers choose business actions only. Firebase/GW tokens, wallet seeds,
+ * activation credentials, DIDComm/JWE, DCR, SMART audiences, client assertions
+ * and VPs stay inside the BFF and its high-level Node runtime. Product-specific
+ * sectors, labels, evidence and policy are injected through the adapter.
+ */
+export declare class ReusableProfessionalBffClient {
+    private readonly extension;
+    readonly profileGate: Readonly<{
+        status: () => Promise<unknown>;
+        create: (input: Readonly<{
+            pin: string;
+            repeatPin: string;
+        }>) => Promise<unknown>;
+        unlock: (input: Readonly<{
+            pin: string;
+        }>) => Promise<unknown>;
+    }>;
+    readonly profiles: Readonly<{
+        activate: (input: BusinessPayload) => Promise<unknown>;
+        activateEmployee: (input: BusinessPayload) => Promise<unknown>;
+    }>;
+    readonly applications: Readonly<{
+        submit: (input: unknown) => Promise<unknown>;
+        review: (input: BusinessPayload & Readonly<{
+            applicationId: string;
+        }>) => Promise<unknown>;
+        complete: (input: Readonly<{
+            applicationId: string;
+        }>) => Promise<unknown>;
+        pdf: (input: Readonly<{
+            applicationId: string;
+        }>) => Promise<unknown>;
+        credential: (input: Readonly<{
+            applicationId: string;
+        }>) => Promise<unknown>;
+    }>;
+    readonly licenses: Readonly<{
+        purchase: (input: BusinessPayload) => Promise<unknown>;
+    }>;
+    readonly employees: Readonly<{
+        invite: (input: BusinessPayload) => Promise<unknown>;
+        lifecycle: (input: BusinessPayload) => Promise<unknown>;
+    }>;
+    readonly subjects: Readonly<{
+        create: (input: BusinessPayload) => Promise<unknown>;
+        addClinicalData: (input: BusinessPayload) => Promise<unknown>;
+        deleteClinicalData: (input: BusinessPayload) => Promise<unknown>;
+        permitDigitalTwin: (input: BusinessPayload) => Promise<unknown>;
+    }>;
+    readonly digitalTwins: Readonly<{
+        search: (input: BusinessPayload) => Promise<unknown>;
+    }>;
+    readonly breakGlass: Readonly<{
+        request: (input: BusinessPayload) => Promise<unknown>;
+    }>;
+    private readonly routes;
+    private readonly fetcher;
+    private readonly baseUrl;
+    constructor(extension: ReusableBffProductExtension);
+    private subjectAction;
+    private applicationRoute;
+    private request;
+}
+export declare class ReusableBffError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export {};

package/dist/reusable-bff.js

@@ -0,0 +1,138 @@
+import { parseReusableOrganizationApplication } from 'vet-data-utils-ts';
+export const DefaultReusableProfessionalBffRoutes = Object.freeze({
+    initialPin: '/api/profiles/initial-pin',
+    initialPinUnlock: '/api/profiles/initial-pin/unlock',
+    profileActivation: '/api/profiles/activation',
+    employeeActivation: '/api/employees/activation',
+    applications: '/api/test-network/applications',
+    applicationReview: '/api/test-network/applications/review',
+    licenses: '/api/licenses',
+    employeeInvitations: '/api/employees/invitations',
+    employeeLifecycle: '/api/employees/lifecycle',
+    subject: '/api/subject',
+    digitalTwinSearch: '/api/test-twins/search',
+    breakGlass: '/api/professional/break-glass',
+});
+/**
+ * Business-level client for the reusable professional BFF shared by UHC UNID,
+ * VetChain and SOSChain product adapters.
+ *
+ * Callers choose business actions only. Firebase/GW tokens, wallet seeds,
+ * activation credentials, DIDComm/JWE, DCR, SMART audiences, client assertions
+ * and VPs stay inside the BFF and its high-level Node runtime. Product-specific
+ * sectors, labels, evidence and policy are injected through the adapter.
+ */
+export class ReusableProfessionalBffClient {
+    constructor(extension) {
+        this.extension = extension;
+        this.routes = Object.freeze({ ...DefaultReusableProfessionalBffRoutes, ...extension.routes });
+        this.fetcher = extension.fetch ?? globalThis.fetch;
+        if (typeof this.fetcher !== 'function')
+            throw new TypeError('bff_fetch_not_available');
+        this.baseUrl = String(extension.baseUrl || '').replace(/\/$/, '');
+        required(extension.productId, 'bff_product_id_required');
+        this.profileGate = Object.freeze({
+            status: () => this.request(this.routes.initialPin, 'GET'),
+            create: input => {
+                if (input.pin !== input.repeatPin)
+                    return Promise.reject(new TypeError('profile_pin_confirmation_mismatch'));
+                return this.request(this.routes.initialPin, 'POST', input, true);
+            },
+            unlock: input => this.request(this.routes.initialPinUnlock, 'POST', input, true),
+        });
+        this.profiles = Object.freeze({
+            activate: input => this.request(this.routes.profileActivation, 'POST', input),
+            activateEmployee: input => this.request(this.routes.employeeActivation, 'POST', input),
+        });
+        this.applications = Object.freeze({
+            submit: async (input) => {
+                const normalized = parseReusableOrganizationApplication({
+                    ...asRecord(input),
+                    allowedSectors: this.extension.allowedSectors,
+                });
+                return this.request(this.routes.applications, 'POST', normalized);
+            },
+            review: ({ applicationId, ...input }) => this.request(this.routes.applicationReview, 'POST', {
+                ...input,
+                applicationId: required(applicationId, 'bff_application_id_required'),
+            }),
+            complete: ({ applicationId }) => this.request(this.applicationRoute(applicationId, 'complete'), 'POST', {}),
+            pdf: ({ applicationId }) => this.request(this.applicationRoute(applicationId, 'pdf'), 'GET'),
+            credential: ({ applicationId }) => this.request(this.applicationRoute(applicationId, 'credential'), 'GET'),
+        });
+        this.licenses = Object.freeze({ purchase: input => this.request(this.routes.licenses, 'POST', input) });
+        this.employees = Object.freeze({
+            invite: input => this.request(this.routes.employeeInvitations, 'POST', input),
+            lifecycle: input => this.request(this.routes.employeeLifecycle, 'POST', input),
+        });
+        this.subjects = Object.freeze({
+            create: input => this.subjectAction('create', input),
+            addClinicalData: input => this.subjectAction('add-clinical-data', input),
+            deleteClinicalData: input => this.subjectAction('delete-clinical-data', input),
+            permitDigitalTwin: input => this.subjectAction('permit-digital-twin', input),
+        });
+        this.digitalTwins = Object.freeze({ search: input => this.request(this.routes.digitalTwinSearch, 'POST', input) });
+        this.breakGlass = Object.freeze({ request: input => this.request(this.routes.breakGlass, 'POST', input) });
+    }
+    subjectAction(action, input) {
+        return this.request(this.routes.subject, 'POST', { ...input, action });
+    }
+    applicationRoute(applicationId, suffix) {
+        return `${this.routes.applications}/${encodeURIComponent(required(applicationId, 'bff_application_id_required'))}/${suffix}`;
+    }
+    async request(path, method, body, allowPin = false) {
+        if (body !== undefined)
+            assertBusinessPayload(body, allowPin);
+        const response = await this.fetcher(`${this.baseUrl}${path}`, {
+            method,
+            credentials: 'include',
+            headers: {
+                accept: 'application/json',
+                'x-product-extension': this.extension.productId,
+                ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const payload = response.status === 204 ? undefined : await response.json().catch(() => undefined);
+        if (!response.ok) {
+            const error = asRecord(payload).error;
+            throw new ReusableBffError(response.status, typeof error === 'string' ? error : 'bff_operation_failed');
+        }
+        return payload;
+    }
+}
+export class ReusableBffError extends Error {
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'ReusableBffError';
+    }
+}
+const forbiddenPlumbing = new Set([
+    'access_token', 'activation_code', 'client_assertion', 'client_id', 'id_token',
+    'private_key', 'privatekey', 'seed', 'vp_token', 'wallet_seed', 'walletseed',
+]);
+function assertBusinessPayload(value, allowPin) {
+    if (!value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        value.forEach(item => assertBusinessPayload(item, allowPin));
+        return;
+    }
+    for (const [key, nested] of Object.entries(value)) {
+        const normalized = key.toLowerCase();
+        if (forbiddenPlumbing.has(normalized) || (!allowPin && normalized.includes('pin'))) {
+            throw new TypeError('bff_internal_plumbing_forbidden');
+        }
+        assertBusinessPayload(nested, allowPin);
+    }
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function required(value, error) {
+    const normalized = String(value ?? '').trim();
+    if (!normalized)
+        throw new TypeError(error);
+    return normalized;
+}

package/docs/101-REUSABLE_PROFESSIONAL_BFF.md

@@ -0,0 +1,89 @@
+# Reusable professional BFF: beginner guide
+
+This is the stable business API shared by the UHC UNID, VetChain and SOSChain
+professional portals. The common client lives in `vet-sdk-core-ts`; each portal
+adds an adapter with its sectors, translations, routes and policy. No `gdc-*`
+repository needs to change when a product adds or documents an extension.
+
+## The three layers
+
+1. The browser calls `ReusableProfessionalBffClient` with business data.
+2. The product BFF verifies login, profile ownership, PIN/passkey grants and
+   policy, then uses its server-only high-level runtime.
+3. GW validates signed identity, consent and authorization and persists the
+   authoritative result.
+
+The browser never builds GW paths, DCR requests, DIDComm/JWE envelopes, SMART
+audiences, `client_assertion`, `vp_token`, activation credentials or wallet
+keys. The reusable client rejects those fields.
+
+## Complete common journey
+
+| Stage | SDK operation | Product extension |
+|---|---|---|
+| Verified login | portal identity provider | issuer, translations and mail |
+| Profile gate before navigation | `profileGate.status/create/unlock` | PIN/passkey UI |
+| Organization application | `applications.submit` | allowed sectors and localized labels |
+| Human review | `applications.review` | reviewer policy and optional evidence |
+| Evidence document | `applications.pdf/credential` | PDF template and signing policy |
+| Controller activation | `applications.complete`, `profiles.activate` | delivery channel and host route |
+| Seats and employees | `licenses.purchase`, `employees.invite/lifecycle` | roles and payment adapter |
+| Employee activation | `profiles.activateEmployee` | selected approved role |
+| Individual | `subjects.create` | person demographics in UHC/SOSChain; animal demographics in VetChain |
+| Clinical data | `subjects.addClinicalData/deleteClinicalData` | permitted FHIR resources |
+| Secondary use | `subjects.permitDigitalTwin` | purpose/consent policy |
+| Digital Twin | `digitalTwins.search` | governed search profile |
+| Emergency access | `breakGlass.request` | disabled by default; human/animal policy differs |
+
+## Organization application contract
+
+- The product supplies the sector allowlist. The form does not hardcode
+  “animal”, “healthcare” or any other product label. An empty allowlist renders
+  no sector choice and fails closed.
+- Country starts unselected and uses ISO 3166-1 alpha-2. A regional identifier
+  uses an ISO 3166-2 subdivision belonging to that country, for example
+  `CA-BC` or `ES-MD`. Postal region is separate.
+- There is one official identifier with type `TAX`, `EIN` or `BN`. A second
+  `taxId` is forbidden. A later VAT/tax identifier is additional evidence only
+  when the official identifier is not already `TAX`.
+- Official licence is separate and optional on Test Network. A later production
+  policy may require it for authorized clinical/index writers.
+- Legal representative and technical controller are separate. If they are the
+  same person, the product checkbox reuses the verified email and disables the
+  duplicate input.
+- The six independent roles are service provider, data provider and data
+  consumer for both the individual index and the Digital Twin index.
+- No application contains a PIN. After verified login, the global profile gate
+  creates a PIN once for a new account or unlocks the existing profile after a
+  reload, before any redirect or application screen.
+
+## PDF and activation licence
+
+The PDF `docVersion` is the lowercase SHA-256 of the immutable template bytes.
+Its portal field is the deployed web origin, not the GW hostname. Authorized
+staff review the application, not merely the PDF.
+
+Submission goes directly to human review. There is no generic ten-minute PDF
+or legal-representative email OTP. A product extension may verify an official
+registry telephone when that evidence source requires it.
+
+After approval, GW `Order` issues the controller activation licence used once
+by exchange and DCR. Test Network delivery may be email; production delivery is
+planned postal verification. The production licence target is one year with a
+renewal warning one month before expiry. Delivery and renewal remain explicit
+TODOs until their live boundary tests exist.
+
+## Product extensions
+
+- **VetChain:** animal sectors, animal individual, veterinary clinical data,
+  animal Digital Twin and veterinarian-only animal break-glass.
+- **UHC UNID:** health/other governed sectors, human individual and its own
+  consent/emergency policy.
+- **SOSChain:** emergency-response sectors and associations; capabilities come
+  from its BFF/GW and fail closed when not enabled.
+
+Extensions may narrow or disable a common capability. They must never obtain
+authority from a browser-selected role, product id, sector or checkbox.
+
+See [`snippets/reusable-professional-bff.ts`](snippets/reusable-professional-bff.ts)
+for a commented integration example.

package/docs/ANIMAL_IDENTITY.md

@@ -0,0 +1,76 @@
+# VetChain animal identity and evidence
+
+## Canonical numeric contract
+
+The personal portal, professional portal, PETD and telephone assistant use the
+same ordered identity tuple:
+
+```text
+speciesId7 + jurisdictionCode5 + animalNumericId15
+```
+
+The check digit follows that same passport and voice order:
+
+```text
+checkDigit1 = Damm(speciesId7 + jurisdictionCode5 + animalNumericId15)
+animalIdentifier16 = animalNumericId15 + checkDigit1
+cardNumber21 = jurisdictionCode5 + animalIdentifier16
+```
+
+`speciesId7` is the zero-padded seven-digit projection of the canonical
+`ncbiTaxonomyId`. `jurisdictionCode5` is country3 plus the immutable region2 of
+birth or initial registration. It is not current residence, current location
+or provider. The animal number contains exactly 15 decimal digits for cards,
+DTMF and voice readback.
+
+Species is shown separately in PETD/card/QR and is required to validate the
+check digit. The digit detects transcription or inconsistent context; with
+only ten possible results it cannot create uniqueness. An authoritative
+registry must reject two different animals using the same 15-digit number in
+the same jurisdiction and evidence-system namespace.
+
+## Animal Index blockchain asset
+
+The permissioned Animal Index uses the exact fixed-width decimal string, not a
+BigInt, hexadecimal conversion or packed representation:
+
+```text
+canonicalNumericId27 = speciesId7 + jurisdictionCode5 + animalNumericId15
+assetId = lowercaseHex(SHA3-256(ASCII(canonicalNumericId27)))
+```
+
+ASCII and UTF-8 produce the same 27 bytes for decimal digits. Keeping the
+fixed-width string preserves leading zeroes and avoids byte-order/length rules;
+converting to a shorter integer byte array provides no meaningful hash-cost
+benefit. SHA-256 is not part of this Animal Index contract; SHA3-256 is the
+minimum accepted algorithm. `checkDigit1` is excluded because it detects capture errors and is not
+identity material.
+
+The asset resolves only the currently active index provider, if one exists. It
+contains no animal data and grants no authorization. Provider replacement or
+revocation remains ledger history while current resolution returns only the
+active provider. The deterministic digest is pseudonymous, not encryption, so
+the 27-digit preimage must not be published or logged.
+
+## Evidence systems
+
+| System | Individual 15-digit source | Rule |
+| --- | --- | --- |
+| USDA AIN | yes | Exactly 15 digits beginning `840`; `840` tags apply to animals born in the United States. |
+| CFIA ISO 11784 | yes | Exactly 15 digits beginning `124`; Canadian livestock ranges are allocated by CFIA and responsible administrators. |
+| ISO 11784/11785 animal microchip | yes | Global technical system: preserve all 15 digits and retain issuer/registry evidence separately, regardless of location. |
+| Herd mark | no | May identify a group/herd; issuing authority and jurisdiction are separate metadata. |
+| Slap tattoo | no | May identify a herd or location; issuing authority and jurisdiction are separate metadata. |
+| Other tattoo | no | Retain as evidence; never pad, hash or reinterpret it as the numeric animal number. |
+
+Sources:
+
+- USDA APHIS animal identification: <https://www.aphis.usda.gov/nvap/reference-guide/animal-identification>
+- CFIA approved animal indicators: <https://inspection.canada.ca/en/animal-health/terrestrial-animals/traceability/indicators>
+- ICAR global ISO 11784/11785 device registry: <https://www.icar.org/icar-registry-of-rfid-devices-in-conformance-with-iso-11784-11785/>
+- EU pet passport use of the global standard: <https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32026R0132>
+
+Evidence capture never means verification. Portal and telephone clients create
+an unverified draft, preserve the evidence system and exact normalized value,
+and wait for an authoritative registry/issuer check before presenting it as
+verified or using it for signed PETD issuance.

package/docs/snippets/reusable-professional-bff.ts

@@ -0,0 +1,42 @@
+import { ReusableProfessionalBffClient } from 'vet-sdk-core-ts/reusable-bff'
+
+// The product adapter owns sectors and translations. The browser cannot ask
+// for a sector that the deployed product did not explicitly enable.
+const bff = new ReusableProfessionalBffClient({
+  productId: 'vetchain',
+  allowedSectors: ['animal-care', 'animal-insurance', 'animal-research', 'animal-tech'],
+})
+
+// Run this immediately after verified login and before redirecting anywhere.
+// New accounts call create once; returning/reloaded accounts call unlock.
+const gate = await bff.profileGate.status()
+void gate
+
+// The application contains business evidence only: no taxId duplicate, PIN,
+// activation code, wallet seed, client assertion, VP or SMART token.
+await bff.applications.submit({
+  sector: 'animal-care',
+  officialId: { type: 'BN', value: '704457076' },
+  countryCode: 'CA',
+  regionalId: true,
+  subdivisionCode: 'CA-BC',
+  officialLicense: 'CVBC-12345',
+  legalRepresentative: { name: 'Legal Representative', email: 'legal@example.test' },
+  technicalController: { sameAsLegalRepresentative: true },
+  participationRoles: [
+    'individual-index-data-provider',
+    'digital-twin-data-consumer',
+  ],
+})
+
+// High-level subject, clinical, Digital Twin and break-glass operations use the
+// current authenticated BFF session. Internal GW security plumbing stays on the
+// server and is rejected if a browser tries to include it.
+await bff.subjects.addClinicalData({ resource: { resourceType: 'Observation' } })
+await bff.digitalTwins.search({ section: 'results', text: 'blood', dateFrom: '2026-01-01' })
+await bff.breakGlass.request({
+  subjectDid: 'did:web:example:card:vetchain:12409:1234567890123456',
+  requestedSections: ['results'],
+  incidentId: 'incident-1',
+  justification: 'Immediate emergency veterinary treatment is required.',
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-sdk-core-ts",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Browser-safe VetChain core contracts and governed animal species identifiers",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -31,11 +31,16 @@
     "./animal-onboarding": {
       "types": "./dist/animal-onboarding.d.ts",
       "default": "./dist/animal-onboarding.js"
+    },
+    "./reusable-bff": {
+      "types": "./dist/reusable-bff.d.ts",
+      "default": "./dist/reusable-bff.js"
     }
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "docs"
   ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
@@ -54,6 +59,6 @@
   },
   "dependencies": {
     "@noble/hashes": "^2.2.0",
-    "vet-data-utils-ts": "0.3.1"
+    "vet-data-utils-ts": "0.4.2"
   }
 }