vet-sdk-core-ts 0.4.3 → 0.4.5

package/README.md

@@ -6,6 +6,31 @@ 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.
 
+## Professional break-glass authorization
+
+Node BFFs call `buildVeterinaryBreakGlassSmartAuthorization` with only the
+animal DID, governed sections, incident id and clinical justification. The
+result can be passed directly to
+`ServerProfileSessionManager.openProfessional().requestSmartToken(...)`.
+It contains the veterinary purpose, scope, 15-minute cap and audited emergency
+claims, but never a `client_id`, SMART audience, private-key assertion or VP.
+Those OpenID proofs are reconstructed and signed by the registered server
+wallet in `gdc-sdk-node-ts`.
+
+```ts
+const authorization = buildVeterinaryBreakGlassSmartAuthorization({
+  subjectDid,
+  requestedSections,
+  incidentId,
+  justification,
+})
+
+await openedProfessional.requestSmartToken(authorization)
+```
+
+`buildVeterinaryBreakGlassSmartRequest` remains only as a low-level
+compatibility envelope for integrations that already own the OpenID fields.
+
 The numeric animal identity and external evidence contract is documented in
 [`docs/ANIMAL_IDENTITY.md`](docs/ANIMAL_IDENTITY.md).
 
@@ -41,7 +66,10 @@ findVetChainSpeciesByTaxonomyId("9685")?.key; // "Cat"
 `buildVeterinaryDigitalTwinSearchRequest` accepts only one governed section,
 selected resource families, display text and dates. It returns both the FHIR
 `Parameters` body and the `filters` map for `DigitalTwinSdk.search`; callers do
-not author `Composition.section` or resource claim names.
+not author `Composition.section` or resource claim names. The returned public
+resource is `ResearchSubject`, so the Node SDK sends
+`POST digitaltwin/.../ResearchSubject/_search`; the `Composition.*` fields
+filter the canonical Composition embedded in that ResearchSubject.
 
 ```ts
 const request = buildVeterinaryDigitalTwinSearchRequest({

package/dist/gateway-contract.d.ts

@@ -26,9 +26,29 @@ export type VeterinaryBreakGlassSmartRequest = Readonly<{
         }>;
     }>;
 }>;
+/**
+ * Business-only SMART authorization consumed by a high-level professional
+ * runtime. Wallet keys, client identifiers, audiences, JWT assertions and VPs
+ * deliberately do not belong to this browser-safe contract.
+ */
+export type VeterinaryBreakGlassSmartAuthorization = Readonly<{
+    subjectDid: string;
+    purpose: 'EMERGENCY';
+    scopes: readonly [string];
+    acrValues: 'urn:antifraud:acr:openid4vp:employee';
+    requestBodyClaims: Readonly<{
+        expires_in: number;
+        break_glass: Readonly<{
+            incidentId: string;
+            subjectKind: 'animal';
+            reasonCode: 'animal-emergency';
+            justification: string;
+        }>;
+    }>;
+}>;
 export type VeterinaryDigitalTwinSearchRequest = Readonly<{
     format: VeterinaryDigitalTwinFormat;
-    resourceType: 'Composition';
+    resourceType: 'ResearchSubject';
     filters: Readonly<Record<string, string | readonly string[]>>;
     payload: Readonly<{
         thid: string;
@@ -36,6 +56,23 @@ export type VeterinaryDigitalTwinSearchRequest = Readonly<{
     }>;
 }>;
 export declare function buildVetGatewayRoutePrefix(context: VetGatewayRouteContext): string;
+/**
+ * Converts the portal's governed emergency form into the business fields for
+ * `ServerProfileSessionManager.openProfessional().requestSmartToken(...)`.
+ * The Node SDK derives and signs every OpenID/VP field from the registered
+ * wallet; the portal never supplies or persists that plumbing.
+ */
+export declare function buildVeterinaryBreakGlassSmartAuthorization(input: Readonly<{
+    subjectDid: string;
+    requestedSections: readonly string[];
+    incidentId: string;
+    justification: string;
+}>): VeterinaryBreakGlassSmartAuthorization;
+/**
+ * Low-level compatibility envelope for callers that already own OpenID
+ * plumbing. New Node BFFs should use
+ * `buildVeterinaryBreakGlassSmartAuthorization` with `openProfessional`.
+ */
 export declare function buildVeterinaryBreakGlassSmartRequest(input: Readonly<{
     thid: string;
     actorDid: string;
@@ -50,8 +87,9 @@ export declare function buildVeterinaryBreakGlassSmartRequest(input: Readonly<{
 }>): VeterinaryBreakGlassSmartRequest;
 /**
  * Converts browser-safe search values into both FHIR Parameters and the exact
- * filter map accepted by the Node DigitalTwin SDK. Callers never choose flat
- * claim names.
+ * filter map accepted by the Node DigitalTwin SDK. The public twin resource is
+ * ResearchSubject; Composition.* filters address its embedded canonical
+ * Composition index. Callers never choose flat claim names.
  */
 export declare function buildVeterinaryDigitalTwinSearchRequest(input: Readonly<{
     thid: string;

package/dist/gateway-contract.js

@@ -6,11 +6,41 @@ export function buildVetGatewayRoutePrefix(context) {
         throw new TypeError('vet_gateway_jurisdiction_invalid');
     return `/${tenantId}/cds-${jurisdiction}/v1/${context.sector}`;
 }
-export function buildVeterinaryBreakGlassSmartRequest(input) {
+/**
+ * Converts the portal's governed emergency form into the business fields for
+ * `ServerProfileSessionManager.openProfessional().requestSmartToken(...)`.
+ * The Node SDK derives and signs every OpenID/VP field from the registered
+ * wallet; the portal never supplies or persists that plumbing.
+ */
+export function buildVeterinaryBreakGlassSmartAuthorization(input) {
     const emergency = parseVeterinaryBreakGlassRequestData(input);
-    const actorDid = did(input.actorDid, 'vet_break_glass_actor_invalid');
     const section = emergency.requestedSections.join(',');
     const scope = `organization/Composition.rs?subject=${encodeURIComponent(emergency.subjectDid)}&section=${encodeURIComponent(section)}`;
+    return Object.freeze({
+        subjectDid: emergency.subjectDid,
+        purpose: 'EMERGENCY',
+        scopes: Object.freeze([scope]),
+        acrValues: 'urn:antifraud:acr:openid4vp:employee',
+        requestBodyClaims: Object.freeze({
+            expires_in: VeterinaryBreakGlassMaxLifetimeSeconds,
+            break_glass: Object.freeze({
+                incidentId: emergency.incidentId,
+                subjectKind: emergency.subjectKind,
+                reasonCode: emergency.reasonCode,
+                justification: emergency.justification,
+            }),
+        }),
+    });
+}
+/**
+ * Low-level compatibility envelope for callers that already own OpenID
+ * plumbing. New Node BFFs should use
+ * `buildVeterinaryBreakGlassSmartAuthorization` with `openProfessional`.
+ */
+export function buildVeterinaryBreakGlassSmartRequest(input) {
+    const emergency = parseVeterinaryBreakGlassRequestData(input);
+    const actorDid = did(input.actorDid, 'vet_break_glass_actor_invalid');
+    const authorization = buildVeterinaryBreakGlassSmartAuthorization(emergency);
     return Object.freeze({
         thid: bounded(input.thid, 'thid'),
         iss: actorDid,
@@ -21,23 +51,19 @@ export function buildVeterinaryBreakGlassSmartRequest(input) {
             client_assertion: bounded(input.clientAssertion, 'clientAssertion'),
             client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
             vp_token: bounded(input.vpToken, 'vpToken'),
-            acr_values: 'urn:antifraud:acr:openid4vp:employee',
-            purpose: 'EMERGENCY',
-            scope,
-            expires_in: VeterinaryBreakGlassMaxLifetimeSeconds,
-            break_glass: {
-                incidentId: emergency.incidentId,
-                subjectKind: emergency.subjectKind,
-                reasonCode: emergency.reasonCode,
-                justification: emergency.justification,
-            },
+            acr_values: authorization.acrValues,
+            purpose: authorization.purpose,
+            scope: authorization.scopes[0],
+            expires_in: authorization.requestBodyClaims.expires_in,
+            break_glass: authorization.requestBodyClaims.break_glass,
         },
     });
 }
 /**
  * Converts browser-safe search values into both FHIR Parameters and the exact
- * filter map accepted by the Node DigitalTwin SDK. Callers never choose flat
- * claim names.
+ * filter map accepted by the Node DigitalTwin SDK. The public twin resource is
+ * ResearchSubject; Composition.* filters address its embedded canonical
+ * Composition index. Callers never choose flat claim names.
  */
 export function buildVeterinaryDigitalTwinSearchRequest(input) {
     const search = parseVeterinaryDigitalTwinSearch(input.search);
@@ -67,14 +93,14 @@ export function buildVeterinaryDigitalTwinSearchRequest(input) {
     return Object.freeze({
         format,
         filters: Object.freeze(filters),
-        // GW stores the pseudonymous twin as a Composition. The selected nested
-        // resource families become repeated Parameters entries; they never change
-        // the asynchronous route resource type.
-        resourceType: 'Composition',
+        // ResearchSubject is the public twin. Its embedded canonical Composition
+        // indexes the selected nested resource families as repeated Parameters;
+        // those filters never change the asynchronous route resource type.
+        resourceType: 'ResearchSubject',
         payload: {
             thid: bounded(input.thid, 'thid'),
             body: format === VeterinaryDigitalTwinFormats.Api
-                ? { data: [{ type: 'Composition-search-request-v1.0', resource: { resourceType: 'Parameters', parameter } }] }
+                ? { data: [{ type: 'ResearchSubject-search-request-v1.0', resource: { resourceType: 'Parameters', parameter } }] }
                 : { resourceType: 'Parameters', parameter },
         },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-sdk-core-ts",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Browser-safe VetChain core contracts and governed animal species identifiers",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",