@arkyc/face-match 1.0.0

package/dist/drivers/external.d.mts

@@ -0,0 +1,17 @@
+import { FaceMatchConfig, FaceMatchDriver, FaceMatchRequest } from "../types.mjs";
+import { FaceMatchResultData } from "@arkyc/types";
+
+//#region src/drivers/external.d.ts
+/**
+ * Generic HTTP face-match driver: POSTs both base64 images to a configured
+ * endpoint and expects a {@link FaceMatchResultData}-shaped JSON response.
+ */
+declare class ExternalFaceMatchDriver implements FaceMatchDriver {
+  private readonly config;
+  readonly name = "external";
+  constructor(config: FaceMatchConfig);
+  compare(request: FaceMatchRequest): Promise<FaceMatchResultData>;
+}
+//#endregion
+export { ExternalFaceMatchDriver };
+//# sourceMappingURL=external.d.mts.map

package/dist/drivers/external.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.d.mts","names":[],"sources":["../../src/drivers/external.ts"],"mappings":";;;;;;AAOA;;cAAa,uBAAA,YAAmC,eAAA;EAAA,iBAGjB,MAAA;EAAA,SAFpB,IAAA;cAEoB,MAAA,EAAQ,eAAA;EAI/B,OAAA,CAAQ,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,mBAAA;AAAA"}

package/dist/drivers/external.mjs

@@ -0,0 +1,32 @@
+//#region src/drivers/external.ts
+/**
+* Generic HTTP face-match driver: POSTs both base64 images to a configured
+* endpoint and expects a {@link FaceMatchResultData}-shaped JSON response.
+*/
+var ExternalFaceMatchDriver = class {
+	config;
+	name = "external";
+	constructor(config) {
+		this.config = config;
+		if (!config.endpoint) throw new Error("ExternalFaceMatchDriver requires config.endpoint");
+	}
+	async compare(request) {
+		const res = await fetch(this.config.endpoint, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				...this.config.apiKey ? { authorization: `Bearer ${this.config.apiKey}` } : {}
+			},
+			body: JSON.stringify({
+				documentPortrait: Buffer.from(request.documentPortrait).toString("base64"),
+				selfie: Buffer.from(request.selfie).toString("base64")
+			})
+		});
+		if (!res.ok) throw new Error(`ExternalFaceMatchDriver request failed with status ${res.status}`);
+		return await res.json();
+	}
+};
+//#endregion
+export { ExternalFaceMatchDriver };
+
+//# sourceMappingURL=external.mjs.map

package/dist/drivers/external.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.mjs","names":[],"sources":["../../src/drivers/external.ts"],"sourcesContent":["import type { FaceMatchResultData } from '@arkyc/types'\nimport type { FaceMatchConfig, FaceMatchDriver, FaceMatchRequest } from '../types'\n\n/**\n * Generic HTTP face-match driver: POSTs both base64 images to a configured\n * endpoint and expects a {@link FaceMatchResultData}-shaped JSON response.\n */\nexport class ExternalFaceMatchDriver implements FaceMatchDriver {\n  readonly name = 'external'\n\n  constructor(private readonly config: FaceMatchConfig) {\n    if (!config.endpoint) throw new Error('ExternalFaceMatchDriver requires config.endpoint')\n  }\n\n  async compare(request: FaceMatchRequest): Promise<FaceMatchResultData> {\n    const res = await fetch(this.config.endpoint as string, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        ...(this.config.apiKey ? { authorization: `Bearer ${this.config.apiKey}` } : {}),\n      },\n      body: JSON.stringify({\n        documentPortrait: Buffer.from(request.documentPortrait).toString('base64'),\n        selfie: Buffer.from(request.selfie).toString('base64'),\n      }),\n    })\n\n    if (!res.ok) {\n      throw new Error(`ExternalFaceMatchDriver request failed with status ${res.status}`)\n    }\n\n    return (await res.json()) as FaceMatchResultData\n  }\n}\n"],"mappings":";;;;;AAOA,IAAa,0BAAb,MAAgE;CAGjC;CAF7B,OAAgB;CAEhB,YAAY,QAA0C;EAAzB,KAAA,SAAA;EAC3B,IAAI,CAAC,OAAO,UAAU,MAAM,IAAI,MAAM,kDAAkD;CAC1F;CAEA,MAAM,QAAQ,SAAyD;EACrE,MAAM,MAAM,MAAM,MAAM,KAAK,OAAO,UAAoB;GACtD,QAAQ;GACR,SAAS;IACP,gBAAgB;IAChB,GAAI,KAAK,OAAO,SAAS,EAAE,eAAe,UAAU,KAAK,OAAO,SAAS,IAAI,CAAC;GAChF;GACA,MAAM,KAAK,UAAU;IACnB,kBAAkB,OAAO,KAAK,QAAQ,gBAAgB,CAAC,CAAC,SAAS,QAAQ;IACzE,QAAQ,OAAO,KAAK,QAAQ,MAAM,CAAC,CAAC,SAAS,QAAQ;GACvD,CAAC;EACH,CAAC;EAED,IAAI,CAAC,IAAI,IACP,MAAM,IAAI,MAAM,sDAAsD,IAAI,QAAQ;EAGpF,OAAQ,MAAM,IAAI,KAAK;CACzB;AACF"}

package/dist/drivers/mock.d.mts

@@ -0,0 +1,15 @@
+import { FaceMatchDriver, FaceMatchRequest } from "../types.mjs";
+import { FaceMatchResultData } from "@arkyc/types";
+
+//#region src/drivers/mock.d.ts
+/**
+ * Deterministic face-match driver for development + tests. Passes by default;
+ * `hints` steer the similarity score and verdict.
+ */
+declare class MockFaceMatchDriver implements FaceMatchDriver {
+  readonly name = "mock";
+  compare(request: FaceMatchRequest): Promise<FaceMatchResultData>;
+}
+//#endregion
+export { MockFaceMatchDriver };
+//# sourceMappingURL=mock.d.mts.map

package/dist/drivers/mock.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock.d.mts","names":[],"sources":["../../src/drivers/mock.ts"],"mappings":";;;;;;AASA;;cAAa,mBAAA,YAA+B,eAAA;EAAA,SACjC,IAAA;EAEH,OAAA,CAAQ,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,mBAAA;AAAA"}

package/dist/drivers/mock.mjs

@@ -0,0 +1,25 @@
+//#region src/drivers/mock.ts
+const clamp01 = (n) => Math.min(1, Math.max(0, n));
+/**
+* Deterministic face-match driver for development + tests. Passes by default;
+* `hints` steer the similarity score and verdict.
+*/
+var MockFaceMatchDriver = class {
+	name = "mock";
+	async compare(request) {
+		const similarityScore = clamp01(request.hints?.similarityScore ?? .9);
+		return {
+			passed: request.hints?.passed ?? similarityScore >= .5,
+			similarityScore,
+			confidence: .93,
+			raw: {
+				provider: "mock",
+				similarityScore
+			}
+		};
+	}
+};
+//#endregion
+export { MockFaceMatchDriver };
+
+//# sourceMappingURL=mock.mjs.map

package/dist/drivers/mock.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock.mjs","names":[],"sources":["../../src/drivers/mock.ts"],"sourcesContent":["import type { FaceMatchResultData } from '@arkyc/types'\nimport type { FaceMatchDriver, FaceMatchRequest } from '../types'\n\nconst clamp01 = (n: number): number => Math.min(1, Math.max(0, n))\n\n/**\n * Deterministic face-match driver for development + tests. Passes by default;\n * `hints` steer the similarity score and verdict.\n */\nexport class MockFaceMatchDriver implements FaceMatchDriver {\n  readonly name = 'mock'\n\n  async compare(request: FaceMatchRequest): Promise<FaceMatchResultData> {\n    const similarityScore = clamp01(request.hints?.similarityScore ?? 0.9)\n    const passed = request.hints?.passed ?? similarityScore >= 0.5\n\n    return {\n      passed,\n      similarityScore,\n      confidence: 0.93,\n      raw: { provider: 'mock', similarityScore },\n    }\n  }\n}\n"],"mappings":";AAGA,MAAM,WAAW,MAAsB,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC;;;;;AAMjE,IAAa,sBAAb,MAA4D;CAC1D,OAAgB;CAEhB,MAAM,QAAQ,SAAyD;EACrE,MAAM,kBAAkB,QAAQ,QAAQ,OAAO,mBAAmB,EAAG;EAGrE,OAAO;GACL,QAHa,QAAQ,OAAO,UAAU,mBAAmB;GAIzD;GACA,YAAY;GACZ,KAAK;IAAE,UAAU;IAAQ;GAAgB;EAC3C;CACF;AACF"}

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+import { FaceMatchConfig, FaceMatchDriver, FaceMatchDriverName, FaceMatchRequest } from "./types.mjs";
+import { FaceMatchDriverFactory } from "./registry.mjs";
+import { MockFaceMatchDriver } from "./drivers/mock.mjs";
+import { ExternalFaceMatchDriver } from "./drivers/external.mjs";
+export { ExternalFaceMatchDriver, FaceMatchConfig, FaceMatchDriver, FaceMatchDriverFactory, FaceMatchDriverName, FaceMatchRequest, MockFaceMatchDriver };

package/dist/index.mjs

@@ -0,0 +1,4 @@
+import { ExternalFaceMatchDriver } from "./drivers/external.mjs";
+import { MockFaceMatchDriver } from "./drivers/mock.mjs";
+import { FaceMatchDriverFactory } from "./registry.mjs";
+export { ExternalFaceMatchDriver, FaceMatchDriverFactory, MockFaceMatchDriver };

package/dist/registry.d.mts

@@ -0,0 +1,16 @@
+import { FaceMatchConfig, FaceMatchDriver } from "./types.mjs";
+
+//#region src/registry.d.ts
+/** Selects a face-match driver from config. */
+declare class FaceMatchDriverFactory {
+  /**'
+   * Resolve the face-match driver named by `config`.
+   *
+   * @param config
+   * @returns
+   */
+  static create(config: FaceMatchConfig): FaceMatchDriver;
+}
+//#endregion
+export { FaceMatchDriverFactory };
+//# sourceMappingURL=registry.d.mts.map

package/dist/registry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.mts","names":[],"sources":["../src/registry.ts"],"mappings":";;;;cAMa,sBAAA;EAAA;;;;;;EAAA,OAOJ,MAAA,CAAO,MAAA,EAAQ,eAAA,GAAkB,eAAe;AAAA"}

package/dist/registry.mjs

@@ -0,0 +1,23 @@
+import { ExternalFaceMatchDriver } from "./drivers/external.mjs";
+import { MockFaceMatchDriver } from "./drivers/mock.mjs";
+//#region src/registry.ts
+/** Selects a face-match driver from config. */
+var FaceMatchDriverFactory = class {
+	/**'
+	* Resolve the face-match driver named by `config`.
+	*
+	* @param config
+	* @returns
+	*/
+	static create(config) {
+		switch (config.driver) {
+			case "mock": return new MockFaceMatchDriver();
+			case "external": return new ExternalFaceMatchDriver(config);
+			default: throw new Error(`Unknown face-match driver: ${config.driver}`);
+		}
+	}
+};
+//#endregion
+export { FaceMatchDriverFactory };
+
+//# sourceMappingURL=registry.mjs.map

package/dist/registry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.mjs","names":[],"sources":["../src/registry.ts"],"sourcesContent":["import type { FaceMatchConfig, FaceMatchDriver } from './types'\n\nimport { ExternalFaceMatchDriver } from './drivers/external'\nimport { MockFaceMatchDriver } from './drivers/mock'\n\n/** Selects a face-match driver from config. */\nexport class FaceMatchDriverFactory {\n  /**'\n   * Resolve the face-match driver named by `config`.\n   *\n   * @param config\n   * @returns\n   */\n  static create(config: FaceMatchConfig): FaceMatchDriver {\n    switch (config.driver) {\n      case 'mock':\n        return new MockFaceMatchDriver()\n      case 'external':\n        return new ExternalFaceMatchDriver(config)\n      default:\n        throw new Error(`Unknown face-match driver: ${(config as FaceMatchConfig).driver}`)\n    }\n  }\n}\n"],"mappings":";;;;AAMA,IAAa,yBAAb,MAAoC;;;;;;;CAOlC,OAAO,OAAO,QAA0C;EACtD,QAAQ,OAAO,QAAf;GACE,KAAK,QACH,OAAO,IAAI,oBAAoB;GACjC,KAAK,YACH,OAAO,IAAI,wBAAwB,MAAM;GAC3C,SACE,MAAM,IAAI,MAAM,8BAA+B,OAA2B,QAAQ;EACtF;CACF;AACF"}

package/dist/types.d.mts

@@ -0,0 +1,34 @@
+import { FaceMatchResultData } from "@arkyc/types";
+
+//#region src/types.d.ts
+/** The two images compared by a face-match driver. */
+interface FaceMatchRequest {
+  /** Portrait extracted from the identity document. */
+  documentPortrait: Uint8Array;
+  /** Selfie captured during liveness. */
+  selfie: Uint8Array;
+  /**
+   * Optional deterministic signals (used by the `mock` driver and tests to
+   * steer the similarity / verdict). Ignored by real drivers.
+   */
+  hints?: {
+    similarityScore?: number;
+    passed?: boolean;
+  };
+}
+/** A pluggable face-match provider. */
+interface FaceMatchDriver {
+  readonly name: string;
+  compare(request: FaceMatchRequest): Promise<FaceMatchResultData>;
+}
+/** Identifier for a registered face-match driver. */
+type FaceMatchDriverName = 'mock' | 'external';
+/** Configuration selecting + parameterising the active face-match driver. */
+interface FaceMatchConfig {
+  driver: FaceMatchDriverName;
+  endpoint?: string;
+  apiKey?: string;
+}
+//#endregion
+export { FaceMatchConfig, FaceMatchDriver, FaceMatchDriverName, FaceMatchRequest };
+//# sourceMappingURL=types.d.mts.map

package/dist/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;;UAGiB,gBAAA;EAAA;EAEf,gBAAA,EAAkB,UAAA;;EAElB,MAAA,EAAQ,UAAU;EAFlB;;;;EAOA,KAAA;IAAU,eAAA;IAA0B,MAAA;EAAA;AAAA;AAItC;AAAA,UAAiB,eAAA;EAAA,SACN,IAAA;EACT,OAAA,CAAQ,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,mBAAA;AAAA;;KAIlC,mBAAA;;UAGK,eAAA;EACf,MAAA,EAAQ,mBAAmB;EAC3B,QAAA;EACA,MAAA;AAAA"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@arkyc/face-match",
+  "version": "1.0.0",
+  "description": "Driver-based face matching",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@arkyc/types": "^1.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "clean": "rm -rf dist"
+  }
+}