vet-sdk-core-ts 0.4.7 → 0.4.9

package/README.md

@@ -46,6 +46,10 @@ 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).
 
+The personal controller identity flow uses only the high-level reusable BFF
+methods documented in
+[`docs/101-PERSONAL-IDENTITY-EVIDENCE.md`](docs/101-PERSONAL-IDENTITY-EVIDENCE.md).
+
 ## Animal species
 
 `VetChainDomesticAnimalSpecies` provides stable application keys, official

package/dist/reusable-bff.d.ts

@@ -20,8 +20,53 @@ export type ReusableProfessionalBffRoutes = Readonly<{
     subject: string;
     digitalTwinSearch: string;
     breakGlass: string;
+    identityEvidence: string;
 }>;
 export declare const DefaultReusableProfessionalBffRoutes: ReusableProfessionalBffRoutes;
+/** Business actions understood by every reusable identity-evidence BFF. */
+export declare const IdentityEvidenceActions: Readonly<{
+    PrepareDeclaration: "prepare-declaration";
+    Upload: "upload";
+    VerifySignaturePdf: "verify-signature-pdf";
+}>;
+/** Controller relationships supported by the first animal declaration. */
+export declare const IdentityEvidenceControllerCapacities: Readonly<{
+    Owner: "owner";
+    ResponsiblePerson: "responsible-person";
+    Keeper: "keeper";
+}>;
+export type IdentityEvidenceDeclarationInput = Readonly<{
+    subjectId: string;
+    locale?: 'en' | 'es';
+    fullLegalName: string;
+    countryCode: string;
+    regional: boolean;
+    subdivisionCode?: string;
+    identifierKind: string;
+    identifierValue: string;
+    controllerCapacity: typeof IdentityEvidenceControllerCapacities[keyof typeof IdentityEvidenceControllerCapacities];
+}>;
+export type IdentityEvidenceUploadInput = Readonly<{
+    subjectId: string;
+    controllerIdentifierId: string;
+    pdf: Blob;
+}>;
+export type IdentityEvidenceIdentifierSummary = Readonly<{
+    id: string;
+    typeLabel: string;
+    jurisdictionLabel: string;
+    displayValue: string;
+    status: 'pending' | 'verified' | 'rejected';
+}>;
+export type IdentityEvidenceDocumentSummary = Readonly<{
+    id: string;
+    fileName: string;
+    status: 'pending' | 'verified' | 'rejected';
+}>;
+export type IdentityEvidenceListResult = Readonly<{
+    identifiers: readonly IdentityEvidenceIdentifierSummary[];
+    documents: readonly IdentityEvidenceDocumentSummary[];
+}>;
 type BusinessPayload = Readonly<Record<string, unknown>>;
 /**
  * Business-level client for the reusable professional BFF shared by UHC UNID,
@@ -82,13 +127,33 @@ export declare class ReusableProfessionalBffClient {
     readonly breakGlass: Readonly<{
         request: (input: BusinessPayload) => Promise<unknown>;
     }>;
+    /**
+     * Personal identity evidence without transport or certificate plumbing.
+     *
+     * `upload()` stores one signed PDF as pending evidence. Only
+     * `verifySignaturePdf()` may ask the trusted provider adapter to change its
+     * status. Neither a browser digest nor a successful upload means verified.
+     */
+    readonly identityEvidence: Readonly<{
+        list: (input: Readonly<{
+            subjectId: string;
+        }>) => Promise<IdentityEvidenceListResult>;
+        prepareDeclaration: (input: IdentityEvidenceDeclarationInput) => Promise<Blob>;
+        upload: (input: IdentityEvidenceUploadInput) => Promise<unknown>;
+        verifySignaturePdf: (input: Readonly<{
+            evidenceId: string;
+        }>) => Promise<unknown>;
+    }>;
     private readonly routes;
     private readonly fetcher;
     private readonly baseUrl;
     constructor(extension: ReusableBffProductExtension);
+    private uploadIdentityEvidence;
     private subjectAction;
     private applicationRoute;
     private request;
+    private requestForm;
+    private requestBlob;
 }
 export declare class ReusableBffError extends Error {
     readonly status: number;

package/dist/reusable-bff.js

@@ -12,6 +12,19 @@ export const DefaultReusableProfessionalBffRoutes = Object.freeze({
     subject: '/api/subject',
     digitalTwinSearch: '/api/test-twins/search',
     breakGlass: '/api/professional/break-glass',
+    identityEvidence: '/api/identity-evidence',
+});
+/** Business actions understood by every reusable identity-evidence BFF. */
+export const IdentityEvidenceActions = Object.freeze({
+    PrepareDeclaration: 'prepare-declaration',
+    Upload: 'upload',
+    VerifySignaturePdf: 'verify-signature-pdf',
+});
+/** Controller relationships supported by the first animal declaration. */
+export const IdentityEvidenceControllerCapacities = Object.freeze({
+    Owner: 'owner',
+    ResponsiblePerson: 'responsible-person',
+    Keeper: 'keeper',
 });
 /**
  * Business-level client for the reusable professional BFF shared by UHC UNID,
@@ -73,6 +86,29 @@ export class ReusableProfessionalBffClient {
         });
         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) });
+        this.identityEvidence = Object.freeze({
+            list: ({ subjectId }) => this.request(`${this.routes.identityEvidence}?subjectId=${encodeURIComponent(required(subjectId, 'bff_subject_id_required'))}`, 'GET'),
+            prepareDeclaration: input => this.requestBlob(this.routes.identityEvidence, {
+                action: IdentityEvidenceActions.PrepareDeclaration,
+                ...input,
+            }),
+            upload: input => this.uploadIdentityEvidence(input),
+            verifySignaturePdf: ({ evidenceId }) => this.request(this.routes.identityEvidence, 'POST', {
+                action: IdentityEvidenceActions.VerifySignaturePdf,
+                evidenceId: required(evidenceId, 'bff_identity_evidence_id_required'),
+            }),
+        });
+    }
+    uploadIdentityEvidence(input) {
+        if (!(input.pdf instanceof Blob) || input.pdf.type !== 'application/pdf') {
+            return Promise.reject(new TypeError('bff_identity_evidence_pdf_required'));
+        }
+        const form = new FormData();
+        form.set('action', IdentityEvidenceActions.Upload);
+        form.set('subjectId', required(input.subjectId, 'bff_subject_id_required'));
+        form.set('controllerIdentifierId', required(input.controllerIdentifierId, 'bff_controller_identifier_id_required'));
+        form.set('pdf', input.pdf);
+        return this.requestForm(this.routes.identityEvidence, form);
     }
     subjectAction(action, input) {
         return this.request(this.routes.subject, 'POST', { ...input, action });
@@ -100,6 +136,42 @@ export class ReusableProfessionalBffClient {
         }
         return payload;
     }
+    async requestForm(path, body) {
+        const response = await this.fetcher(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            credentials: 'include',
+            headers: {
+                accept: 'application/json',
+                'x-product-extension': this.extension.productId,
+            },
+            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;
+    }
+    async requestBlob(path, body) {
+        assertBusinessPayload(body, false);
+        const response = await this.fetcher(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            credentials: 'include',
+            headers: {
+                accept: 'application/pdf',
+                'content-type': 'application/json',
+                'x-product-extension': this.extension.productId,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const payload = await response.json().catch(() => undefined);
+            const error = asRecord(payload).error;
+            throw new ReusableBffError(response.status, typeof error === 'string' ? error : 'bff_operation_failed');
+        }
+        return response.blob();
+    }
 }
 export class ReusableBffError extends Error {
     constructor(status, message) {

package/docs/101-PERSONAL-IDENTITY-EVIDENCE.md

@@ -0,0 +1,49 @@
+# Personal identity evidence: beginner guide
+
+This flow starts in PetChain and is reusable from SOSChain and UHC UNID. A
+person may have several identities: for example a Spanish national identity,
+a Canadian driving licence and a passport. Each is independent and may have
+different evidence and verification dates.
+
+## What the app does
+
+1. Show only a person or animal the signed-in account may already manage.
+2. Let the person prepare a declaration for one of their identities.
+3. Download the declaration, sign it outside the portal and upload the signed
+   PDF.
+4. Ask the trusted provider to verify the PDF signature.
+5. Refresh the provider result. Only that result may say `verified`.
+
+For an animal, the declaration also states the person's relationship to that
+animal. A successful PDF upload does not prove that relationship by itself.
+An authorized veterinarian or registry may provide separate evidence.
+
+## The four UI methods
+
+```ts
+const evidence = client.identityEvidence
+
+const current = await evidence.list({ subjectId })
+const unsignedPdf = await evidence.prepareDeclaration(declaration)
+await evidence.upload({ subjectId, controllerIdentifierId, pdf: signedPdf })
+await evidence.verifySignaturePdf({ evidenceId })
+```
+
+Those are application methods, not transport helpers. The browser does not
+parse certificates, choose trust roots, perform revocation checks, write a
+ledger record, build DIDComm or construct gateway claims.
+
+## What is stored
+
+- Each civil identity is its own `schema.org/Person` resource.
+- Application fields use flat `resource.meta.claims`.
+- The provider stores the signed PDF privately and keeps uploader, signers and
+  verifier separate.
+- SOSChain embeds the same flow but does not copy the identity into its own
+  subject index.
+
+Emergency calls require a current provider-returned verified identity. Login,
+email, telephone, a selected card, a PDF upload or a browser hash never grants
+that permission.
+
+See [`snippets/personal-identity-evidence.ts`](snippets/personal-identity-evidence.ts).

package/docs/snippets/personal-identity-evidence.ts

@@ -0,0 +1,23 @@
+import { ReusableProfessionalBffClient } from 'vet-sdk-core-ts/reusable-bff'
+
+// The product adapter supplies the BFF route and authenticated session.
+const client = new ReusableProfessionalBffClient({
+  productId: 'vetchain',
+  allowedSectors: ['animal-care'],
+})
+
+// Step 1. Read provider-authorized identities and evidence for the selected card.
+const current = await client.identityEvidence.list({ subjectId })
+
+// Step 2. Prepare the human-readable declaration; signing happens outside the portal.
+const declarationPdf = await client.identityEvidence.prepareDeclaration(declaration)
+
+// Step 3. Upload stays pending. A local digest is not verification.
+await client.identityEvidence.upload({ subjectId, controllerIdentifierId, pdf: signedPdf })
+
+// Step 4. Only the trusted server adapter checks the PDF signature and updates status.
+await client.identityEvidence.verifySignaturePdf({ evidenceId })
+
+// Step 5. Render only refreshed provider readback.
+void current
+void declarationPdf

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-sdk-core-ts",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Browser-safe VetChain core contracts and governed animal species identifiers",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -59,6 +59,6 @@
   },
   "dependencies": {
     "@noble/hashes": "^2.2.0",
-    "vet-data-utils-ts": "0.4.2"
+    "vet-data-utils-ts": "0.4.7"
   }
 }