OpenSpec Change: biometrics

Package: @suaveplan/biometrics Status: PROPOSED Type: new-package

Why

Vaulted needs biometric authentication across desktop (Windows Hello, Touch ID via Electrobun), mobile (Face ID, Android BiometricPrompt via Capacitor), and macOS (Touch ID via @suaveplan/macos-keychain). Platform APIs are fragmented and inconsistent; a thin universal facade ensures the Vaulted app and extensions use a single interface regardless of runtime.

What changes

ADDED: BiometricAuth class — universal facade with auto-detected or injected delegate
ADDED: authenticate(reason) — returns Promise<boolean> (never biometric data)
ADDED: getAvailability() — returns BiometricAvailability
ADDED: BiometricDelegate interface — platform implementers implement this
ADDED: CapacitorBiometricDelegate — delegates to Capacitor Local Authentication plugin
ADDED: ElectrobunBiometricDelegate — delegates to Electrobun native bridge
ADDED: MacosKeychainBiometricDelegate — delegates to @suaveplan/macos-keychain biometric APIs
ADDED: NoOpBiometricDelegate — always returns false; used on unsupported platforms
ADDED: BiometricAvailability — { available: boolean; type?: BiometricType; reason?: UnavailabilityReason }
ADDED: BiometricType — 'touchId' | 'faceId' | 'fingerprint' | 'iris' | 'unknown'
ADDED: UnavailabilityReason — 'noHardware' | 'notEnrolled' | 'notSupported' | 'permissionDenied' | 'unknown'
ADDED: BiometricError extends SuaveplanError
ADDED: BiometricNotAvailableError extends BiometricError (code BIOMETRIC.NOT_AVAILABLE)
ADDED: BiometricHardwareError extends BiometricError (code BIOMETRIC.HARDWARE_ERROR)
ADDED: Injectable clock?: Clock in BiometricAuth options for deterministic timeout testing
ADDED: Zod schemas for availability and options
ADDED: OTel counter biometric.authenticate.total (by outcome) and histogram biometric.authenticate.duration_ms

Out of scope

Biometric enrollment — OS-level concern, not a library responsibility
Secure enclave key generation or keypair creation — defer to @suaveplan/crypto-browser and platform plugins
Fallback to device PIN / password — platform-specific behavior, deferred to consumer
WebAuthn / passkey biometric flows — handled by @suaveplan/webauthn

Gap analysis: sub-standard → enterprise

Consumer-grade biometric libraries often capture, buffer, or even persist raw biometric data (fingerprints, face geometry) in application memory, violating platform security guidelines and creating catastrophic privacy risk if the device is compromised. They also fail to provide a structured fallback when hardware is unavailable or not enrolled, leaving apps to crash or hang. Enterprise-grade code must never touch raw biometric templates; it must delegate entirely to OS secure enclaves, surface clear availability signals, and offer a deterministic NoOp fallback for unsupported platforms.

Security model

Threat model: Compromised host attempting to replay biometric authentication signals; malicious delegates intercepting or spoofing platform responses; side-channel leakage via timing of availability checks.
Privacy guarantees: Raw biometric data is never read, stored, or transmitted by this library. All biometric matching occurs inside the platform secure enclave / TEE. Only a boolean result is returned to the application.
Input validation: reason string length bounded and sanitized; delegate implementations validated at injection time against the BiometricDelegate interface contract.
Side-channel resistance: Availability checks and authentication calls use constant-time paths where feasible; no correlation between vault item access and biometric prompt timing.
Key material handling: No cryptographic keys are derived from biometric data in this package. Key generation is explicitly out of scope and deferred to @suaveplan/crypto-browser and platform plugins.

Performance SLOs

Latency: P95 authenticate prompt-to-result < 2s on supported hardware; P95 getAvailability < 50ms.
Throughput: Serial by design — biometric prompts are user-interactive and never batched.
Memory bounds: Peak memory < 256 KB per authentication attempt; no image or template buffering.
Bundle size budget: Core facade + delegates < 10 kB gzipped; platform-specific delegates tree-shakeable.

Observability plan

OTel spans/metrics: Counter biometric.authenticate.total by outcome; histogram biometric.authenticate.duration_ms; gauge for availability state transitions.
Structured logging: JSON logs at info for authentication attempts, warn for unavailability, error for delegate failures; never logs biometric type as a personal identifier.
Error telemetry: Distinct codes (NOT_AVAILABLE) with platform context and delegate name (anonymized where required).
Health checks: Expose BiometricAuth.isHealthy() returning false if the active delegate throws repeatedly.

Dependency audit

Runtime deps: @suaveplan/errors, @suaveplan/otel, and platform-specific peer dependencies (Capacitor, Electrobun, macOS keychain) that are injected, not bundled.
Supply-chain risk: No biometric SDKs from unvetted vendors; all delegates are first-party wrappers around platform APIs.
Tree-shakeability: BiometricAuth, each delegate, and availability utilities are individually tree-shakeable.
License: All first-party code MIT-licensed; platform plugins retain their original licenses and are peer dependencies.

Operational readiness

Graceful degradation: NoOpBiometricDelegate ensures unsupported platforms receive false rather than exceptions; consumers can cascade to PIN/password.
Resource limits: Authentication timeout enforced by platform delegate; internal timeout as a failsafe.
Error recovery: Delegate exceptions are caught and mapped to BiometricError; repeated failures trigger health-check degradation.
Backpressure: Not applicable — biometric operations are user-serialized; concurrent calls are queued and deduplicated.
Version compatibility: Public API frozen after v1; additive-only changes; deprecated delegates supported for two major versions.
Platform safety: Runtime platform detection uses typeof process !== 'undefined' && process.platform === 'darwin' with safe fallback to NoOpBiometricDelegate to avoid crashes in browser environments without process.

Verification approach

100% coverage target: All exported functions, branches, and error paths instrumented in test.
Property-based tests: Availability state machine transitions, delegate injection contracts, and error code coverage tested with fast-check invariants.
Load/stress criteria: 100 sequential authenticate calls without memory growth > 5%; no handle leaks in test doubles implementing the BiometricDelegate interface with deterministic responses.
Security audit checklist: Verify no raw biometric data in logs or memory; confirm delegate sandboxing; validate timeout and cancellation paths.
src/auth/auth.test.ts — covers authenticate success, failure, cancellation, delegate injection
src/platform/platform.test.ts — covers platform auto-detection, unsupported platform fallback
src/delegate/delegate.test.ts — covers every delegate implementation contract
src/availability/availability.test.ts — covers getAvailability mapping
src/errors/errors.spec-conformance.test.ts — pins error hierarchies and strict-mode behaviors
tests/dep-graph.test.ts — pins dependency invariants

Migration impact

None — additive only.

Impact

Downstream consumers

No dependents (verified by bunx turbo ls --filter=...@suaveplan/biometrics).

Breaking changes