@octane-xplat/biometrics 0.0.0-nightly.g2e22171

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# `@octane-xplat/biometrics`
+
+```sh
+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`; 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'
+
+if ((await biometrics.ensure()) === 'granted') {
+	const ok = await biometrics.impl!.verify('Unlock your saved trips')
+}
+```
+
+The shared capability contract: `supported` reports whether an
+implementation exists on this target — branch on it rather than catching —
+`ensure()` resolves `'granted' | 'denied' | 'unsupported'`, and `impl` is
+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](../../.agents/docs/notes/platform-notes.md).
+Exercised by the harness `Services` screen
+([`packages/app/src/Services.tsrx`](../app/src/Services.tsrx)).

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@octane-xplat/biometrics",
+  "version": "0.0.0-nightly.g2e22171",
+  "description": "Biometric verification (FaceID/TouchID/fingerprint) for Octane xplat — matching web + NativeScript implementations",
+  "keywords": [
+    "android",
+    "biometrics",
+    "cross-platform",
+    "faceid",
+    "fingerprint",
+    "ios",
+    "nativescript",
+    "octane",
+    "touchid",
+    "web",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/biometrics",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
+    "directory": "packages/biometrics"
+  },
+  "files": [
+    "src",
+    "types",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": {
+        "types": "./types/generated/index.macos.d.ts",
+        "default": "./src/index.macos.ts"
+      },
+      "types": "./types/generated/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": {
+      "types": "./types/generated/*.d.ts",
+      "default": "./src/*"
+    },
+    "./*.ts": {
+      "types": "./types/generated/*.d.ts",
+      "default": "./src/*.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nativescript/biometrics": "1.3.1"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.5",
+    "@nativescript/core": "9.1.3",
+    "@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",
+    "@nativescript/core": ">=9.1.0 <10",
+    "octane": ">=0.6.3 <1"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    }
+  },
+  "nativescript": {
+    "platforms": {
+      "android": "9.1.0",
+      "ios": "9.1.0"
+    }
+  },
+  "scripts": {
+    "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

@@ -0,0 +1,140 @@
+// 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> = {
+	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

@@ -0,0 +1,54 @@
+// 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() {
+		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 {
+				// 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/src/biometrics.web.ts

@@ -0,0 +1,13 @@
+// Biometrics — web leaf. WebAuthn is an authentication ceremony, not a
+// standalone local-presence API: it requires an RP challenge and a registered
+// credential, and may require a user gesture. Do not claim it implements the
+// native verify(reason) contract by creating an ephemeral passkey.
+import type { BiometricsImpl, Capability } from './types'
+
+export const biometrics: Capability<BiometricsImpl> = {
+	supported: false,
+	async ensure() {
+		return 'unsupported'
+	},
+	impl: null,
+}

package/src/index.macos.ts

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

package/src/index.ts

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

package/src/types.ts

@@ -0,0 +1,11 @@
+/** 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>
+}

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>;
+}