@octane-xplat/biometrics 0.14.0 → 0.15.0

package/README.md

@@ -6,9 +6,9 @@ pnpm add @octane-xplat/biometrics
 
 Local biometric verification — Face ID / Touch ID / fingerprint or device
 credential — behind one capability object. iOS and Android run
-`@nativescript/biometrics`; web and the macOS AppKit host report
-`supported: false` (WebAuthn is an authentication ceremony, not a
-local-presence check, and the dev host has no LocalAuthentication bridge).
+`@nativescript/biometrics`; macOS AppKit uses Apple LocalAuthentication
+for Touch ID. Web reports `supported: false` because WebAuthn requires
+a registered credential and an authentication ceremony.
 
 ```ts
 import { biometrics } from '@octane-xplat/biometrics'
@@ -24,7 +24,24 @@ implementation exists on this target — branch on it rather than catching —
 the service once usable. `verify(reason)` resolves `false` for a declined
 or failed prompt rather than throwing.
 
+On macOS, availability checks do not open a prompt. Missing hardware,
+enrollment, pairing, or a connected sensor returns `unsupported`; lockout
+or an interaction restriction returns `denied`. A host without the Objective-C
+LocalAuthentication bridge reports `supported: false` and `impl: null`.
+Verification uses biometrics only, hides password fallback, and returns
+`false` on cancellation, failure, or an overlapping prompt.
+
+```ts
+import { biometrics } from '@octane-xplat/biometrics'
+
+const availability = await biometrics.ensure()
+if (availability === 'granted') {
+	const verified = await biometrics.impl!.verify('Unlock your saved trips')
+	console.log(verified ? 'Unlocked' : 'Still locked')
+}
+```
+
 Guide: [Using device features](../../docs/platform/platform-services.md);
-per-target availability: [platform notes](../../docs/notes/platform-notes.md).
+per-target availability: [platform notes](../../.agents/docs/notes/platform-notes.md).
 Exercised by the harness `Services` screen
 ([`packages/app/src/Services.tsrx`](../app/src/Services.tsrx)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/biometrics",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Biometric verification (FaceID/TouchID/fingerprint) for Octane xplat — matching web + NativeScript implementations",
   "keywords": [
     "android",
@@ -23,15 +23,29 @@
     "directory": "packages/biometrics"
   },
   "files": [
-    "src"
+    "src",
+    "types",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
   ],
   "type": "module",
   "exports": {
     ".": {
-      "macos": "./src/index.macos.ts",
+      "macos": {
+        "types": "./types/generated/index.macos.d.ts",
+        "default": "./src/index.macos.ts"
+      },
+      "types": "./types/generated/index.d.ts",
       "default": "./src/index.ts"
     },
-    "./*": "./src/*"
+    "./*": {
+      "types": "./types/generated/*.d.ts",
+      "default": "./src/*"
+    },
+    "./*.ts": {
+      "types": "./types/generated/*.d.ts",
+      "default": "./src/*.ts"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -40,9 +54,13 @@
     "@nativescript/biometrics": "1.3.1"
   },
   "devDependencies": {
-    "@nativescript-community/octane": "0.2.4",
+    "@nativescript-community/octane": "0.2.5",
     "@nativescript/core": "9.1.3",
-    "octane": "0.11.0"
+    "@nativescript/types": "9.1.4",
+    "@tsrx/typescript-plugin": "0.4.11",
+    "octane": "0.11.0",
+    "tsrx-typegen": "0.3.0",
+    "typescript": "5.9.3"
   },
   "peerDependencies": {
     "@nativescript-community/octane": ">=0.2.1 <1",
@@ -64,6 +82,10 @@
     }
   },
   "scripts": {
-    "test:packed": "node tests/packed-consumer.mjs"
+    "test:packed": "node tests/packed-consumer.mjs",
+    "test": "node --test tests/*.test.mjs",
+    "test:macos-runtime": "node ../../apps/macos/test/verify-biometrics.mjs",
+    "typegen": "tsrx-typegen --project tsconfig.types.json",
+    "pack:check": "tsrx-typegen --pack-check"
   }
 }

package/src/biometrics.macos.ts

@@ -1,9 +1,140 @@
-// Biometrics — AppKit host leaf. No LocalAuthentication bridge exists on the
-// dev host.
-import type { Capability, BiometricsImpl } from './types'
+// LocalAuthentication through the AppKit host's existing Objective-C bridge.
+import type { BiometricsImpl, Capability } from './types'
+
+declare const objc: { import(name: string): void }
+declare const interop: { Reference: new () => { value?: { domain: string; code: number } } }
+declare const LAContext: { new: () => AuthenticationContext }
+
+interface AuthenticationContext {
+	localizedFallbackTitle: string
+	canEvaluatePolicyError(policy: number, error: InstanceType<typeof interop.Reference>): boolean
+	evaluatePolicyLocalizedReasonReply(
+		policy: number,
+		reason: string,
+		reply: (success: boolean, error: unknown) => void,
+	): void
+	invalidate(): void
+}
+
+// LAPolicyDeviceOwnerAuthenticationWithBiometrics: do not silently substitute
+// password/Apple Watch authentication on a machine without biometric hardware.
+const biometricPolicy = 1
+
+function frameworkAvailable(): boolean {
+	try {
+		objc.import('LocalAuthentication')
+	} catch {
+		// Some hosts have already bound the symbols; others cannot provide them.
+	}
+
+	return (
+		typeof LAContext !== 'undefined' &&
+		typeof interop !== 'undefined' &&
+		typeof interop.Reference !== 'undefined'
+	)
+}
+
+function availability(context: AuthenticationContext): 'granted' | 'denied' | 'unsupported' {
+	const error = new interop.Reference()
+	if (context.canEvaluatePolicyError(biometricPolicy, error)) {
+		return 'granted'
+	}
+
+	// Missing hardware (-6), enrollment (-7), pairing (-12) or a connected
+	// sensor (-13) is absence, not a permission denial.
+	// Lockout (-8), interaction restrictions and other failures remain denied.
+	return error.value?.domain === 'com.apple.LocalAuthentication' &&
+		[-6, -7, -12, -13].includes(Number(error.value.code))
+		? 'unsupported'
+		: 'denied'
+}
+
+function invalidate(context: AuthenticationContext | null): void {
+	try {
+		context?.invalidate()
+	} catch {
+		// Cleanup must not turn a failed authentication into a rejected promise.
+	}
+}
+
+// Root both the context and callback until completion; native callbacks may
+// outlive the JS call. Refuse concurrent prompts rather than canceling one.
+let active: {
+	context: AuthenticationContext | null
+	reply: ((success: boolean, error: unknown) => void) | null
+} | null = null
+
+const implementation: BiometricsImpl = {
+	verify(reason) {
+		if (active || !frameworkAvailable() || typeof reason !== 'string' || !reason.trim()) {
+			return Promise.resolve(false)
+		}
+
+		const operation = {
+			context: null as AuthenticationContext | null,
+			reply: null as ((success: boolean, error: unknown) => void) | null,
+		}
+
+		active = operation
+		return new Promise<boolean>((resolve) => {
+			let settled = false
+			const finish = (success: boolean) => {
+				if (settled) {
+					return
+				}
+
+				settled = true
+				if (active === operation) {
+					active = null
+				}
+
+				invalidate(operation.context)
+				operation.context = null
+				operation.reply = null
+				resolve(success)
+			}
+
+			try {
+				operation.context = LAContext.new()
+				if (availability(operation.context) !== 'granted') {
+					finish(false)
+					return
+				}
+
+				operation.context.localizedFallbackTitle = ''
+				operation.reply = (success, error) => finish(Boolean(success) && !error)
+				operation.context.evaluatePolicyLocalizedReasonReply(
+					biometricPolicy,
+					reason,
+					operation.reply,
+				)
+			} catch {
+				finish(false)
+			}
+		})
+	},
+}
 
 export const biometrics: Capability<BiometricsImpl> = {
-	supported: false,
-	ensure: async () => 'unsupported',
-	impl: null,
+	get supported() {
+		return frameworkAvailable()
+	},
+	async ensure() {
+		if (!frameworkAvailable()) {
+			return 'unsupported'
+		}
+
+		let context: AuthenticationContext | null = null
+		try {
+			context = LAContext.new()
+			return availability(context)
+		} catch {
+			return 'denied'
+		} finally {
+			invalidate(context)
+		}
+	},
+	get impl() {
+		return frameworkAvailable() ? implementation : null
+	},
 }

package/src/biometrics.ts

@@ -1,23 +1,53 @@
 // Biometrics — FaceID/TouchID/fingerprint via @nativescript/biometrics.
 import { BiometricAuth } from '@nativescript/biometrics'
+import type { VerifyBiometricOptions } from '@nativescript/biometrics'
+import { isIOS } from '@nativescript/core'
 import type { Capability } from './types'
 import type { BiometricsImpl } from './types'
 
 const bio = new BiometricAuth()
 
+// One prompt at a time — matching the macOS leaf, an overlapping call
+// resolves false rather than stacking prompts or racing the shared
+// keychain entry on iOS.
+let verifying = false
+
 export const biometrics: Capability<BiometricsImpl> = {
 	supported: true,
 	async ensure() {
-		const r = await bio.available()
-		return r.any ? 'granted' : 'unsupported'
+		try {
+			const r = await bio.available()
+			// Android reports `any` for a secure lockscreen without biometrics —
+			// verify() requires BIOMETRIC_STRONG, so that state is not usable.
+			return r.any && (isIOS || r.biometrics) ? 'granted' : 'unsupported'
+		} catch {
+			// Android rejects when the device lacks biometric hardware,
+			// enrollment, or a secure lockscreen — absence, not an error.
+			return 'unsupported'
+		}
 	},
 	impl: {
 		async verify(reason) {
+			if (verifying) {
+				return false
+			}
+
+			verifying = true
 			try {
-				const r = await bio.verifyBiometric({ title: reason })
+				// iOS ignores `title` on its default keychain path — route
+				// through LAContext (pinFallback selects that path; customFallback
+				// keeps the biometrics-only policy) so `message` surfaces the
+				// caller's reason, matching Android's dialog title.
+				const options: VerifyBiometricOptions = isIOS
+					? { title: reason, message: reason, pinFallback: true, ios: { customFallback: true } }
+					: { title: reason }
+
+				const r = await bio.verifyBiometric(options)
 				return r.code === 0
 			} catch {
 				return false
+			} finally {
+				verifying = false
 			}
 		},
 	},

package/types/generated/.tsrx-typegen-manifest.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "files": [
+    "biometrics.d.ts",
+    "biometrics.macos.d.ts",
+    "biometrics.web.d.ts",
+    "index.d.ts",
+    "index.macos.d.ts",
+    "types.d.ts"
+  ]
+}

package/types/generated/biometrics.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from './types.js';
+import type { BiometricsImpl } from './types.js';
+export declare const biometrics: Capability<BiometricsImpl>;

package/types/generated/biometrics.macos.d.ts

@@ -0,0 +1,2 @@
+import type { BiometricsImpl, Capability } from './types.js';
+export declare const biometrics: Capability<BiometricsImpl>;

package/types/generated/biometrics.web.d.ts

@@ -0,0 +1,2 @@
+import type { BiometricsImpl, Capability } from './types.js';
+export declare const biometrics: Capability<BiometricsImpl>;

package/types/generated/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export { biometrics } from './biometrics.js';

package/types/generated/index.macos.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export { biometrics } from './biometrics.macos.js';

package/types/generated/types.d.ts

@@ -0,0 +1,10 @@
+/** Optional capability — never throws for absence (docs/platform/platform-services.md). */
+export interface Capability<T> {
+    supported: boolean;
+    ensure(): Promise<'granted' | 'denied' | 'unsupported'>;
+    /** usable iff supported && ensured */
+    impl: T | null;
+}
+export interface BiometricsImpl {
+    verify(reason: string): Promise<boolean>;
+}