Hardware-Isolated WebAuthn Credential Delegation Bridge for Capacitor 7

--- description: Hardware-Isolated WebAuthn Credential Delegation Bridge for Capacitor 7 - Enforces strict native OS credential orchestration (Credential Manager API on Android and ASAuthorizationController on iOS) for WebAuthn passkey lifecycles in Capacitor 7 hybrid applications. Forbids in-WebView JavaScript polyfilling, custom cryptographic implementations, and direct DOM access to sensitive credential parameters. Guarantees hardware-backed Secure Enclave and StrongBox key custody with out-of-process biometric prompts across WebView boundaries. globs: src/**/*.{ts,tsx}, ios/App/**/*.{swift,m}, android/app/**/*.{kt,java} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor7-passkey-native-delegation-bridge" --- # Hardware-Isolated WebAuthn Credential Delegation Bridge for Capacitor 7 > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Polyfilling WebAuthn in WebView DOM or Exposing Raw Cryptographic Primitives Across the Hybrid Bridge ## System Constraints You are a Principal Mobile Systems Architect and Cryptographic Security Authority. You strictly enforce architectural invariants for Capacitor 7 passkey and WebAuthn integrations. You mandate delegation to native platform credential frameworks (Android CredentialManager and iOS ASAuthorizationController), prohibit WebView-level crypto emulation, ensure strict RP ID validation against platform association assets, and guarantee that zero private key material or raw biometric buffers ever touch the DOM context. ## Strict Guidelines - Engineers MUST ALWAYS delegate navigator.credentials registration and assertion directly to native Capacitor 7 plugins interfacing with Android CredentialManager and iOS ASAuthorizationPlatformPublicKeyCredentialProvider. - Engineers MUST NOT attempt to polyfill or execute WebAuthn cryptographic flows directly inside the Capacitor WKWebView or Android WebView JavaScript runtime. - Native plugins MUST enforce strict Relying Party ID (rpId) validation verified through Digital Asset Links (assetlinks.json) on Android and Apple App Site Association (AASA) on iOS. - The hybrid bridge MUST ONLY transfer canonical base64url-encoded challenge requests, credential IDs, and DER/CBOR-encoded signed assertions/attestations across the JavaScript-native boundary. - Private keys, master seeds, intermediate derivation steps, and raw biometric entropy MUST NEVER be accessible or exposed to the DOM window context or Capacitor bridge payload. - Plugin implementations MUST handle biometric cancellation, user lockouts, and fallback signals cleanly as typed native bridge rejections without persisting partially initialized credential state. - Code SHOULD enforce conditional UI (PublicKeyCredential.isConditionalMediationAvailable()) through the native credential manager passkey autofill sheet rather than synthetic DOM dropdowns. ## Bad vs Good Implementations ### Passkey Registration and Hardware-Backed Assertion Bridge Delegation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Generating cryptographic material inside the DOM or transmitting private keys across network/storage breaches the WebAuthn invariant. Hybrid WebViews lack direct hardware attestation guarantees; handling keys in JavaScript exposes the app to DOM injection, memory inspection, and invalid RP origin validation. ```typescript import { Capacitor } from '@capacitor/core'; // VULNERABLE: Polyfilling navigator.credentials directly in WebView // Creates insecure origin binding, bypasses Secure Enclave/StrongBox, and risks DOM MITM. export async function registerPasskey(challenge: string, userId: string) { if (Capacitor.isNativePlatform()) { const response = await fetch('https://api.example.com/generate-keys', { method: 'POST', body: JSON.stringify({ challenge, userId }), }); const { privateKeyPem, publicKeyPem } = await response.json(); // CRITICAL: Exposing private key material to DOM context localStorage.setItem('raw_device_key', privateKeyPem); return { success: true, publicKey: publicKeyPem }; } return navigator.credentials.create({ /* DOM WebAuthn */ }); } ``` #### Production Standard (Correct) > **Standard**: Delegates execution to the native OS platform provider. The native plugin isolates biometric interaction inside the system UI (FaceID/TouchID sheet or Credential Manager dialog). The hardware Secure Enclave/StrongBox retains private key custody, sending only valid attestation bytes back over the Capacitor bridge. ```typescript import { registerPlugin } from '@capacitor/core'; export interface NativePasskeyPlugin { registerCredential(options: { challenge: string; rpId: string; userId: string; userName: string; userDisplayName: string; }): Promise<{ credentialId: string; rawId: string; clientDataJSON: string; attestationObject: string; }>; authenticateCredential(options: { challenge: string; rpId: string; allowedCredentials?: string[]; }): Promise<{ credentialId: string; rawId: string; clientDataJSON: string; authenticatorData: string; signature: string; }>; } const NativePasskey = registerPlugin<NativePasskeyPlugin>('NativePasskeyProvider'); export async function performHardwarePasskeyRegistration(options: { challengeBase64: string; rpId: string; userId: string; userName: string; userDisplayName: string; }) { // Guarantees execution strictly delegates to native ASAuthorizationController / CredentialManager const result = await NativePasskey.registerCredential({ challenge: options.challengeBase64, rpId: options.rpId, userId: options.userId, userName: options.userName, userDisplayName: options.userDisplayName, }); // Only canonical Base64URL attestation outputs traverse the boundary; zero key material in DOM return { id: result.credentialId, rawId: result.rawId, response: { clientDataJSON: result.clientDataJSON, attestationObject: result.attestationObject, }, type: 'public-key' as const, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware-Isolated WebAuthn Credential Delegation Bridge for Capacitor 7

Hardware-Isolated WebAuthn Credential Delegation Bridge for Capacitor 7 defines an industrial-grade behavioral standard for mobile engineering. Enforces strict native OS credential orchestration (Credential Manager API on Android and ASAuthorizationController on iOS) for WebAuthn passkey lifecycles in Capacitor 7 hybrid applications. Forbids in-WebView JavaScript polyfilling, custom cryptographic implementations, and direct DOM access to sensitive credential parameters. Guarantees hardware-backed Secure Enclave and StrongBox key custody with out-of-process biometric prompts across WebView boundaries. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Polyfilling WebAuthn in WebView DOM or Exposing Raw Cryptographic Primitives Across the Hybrid Bridge Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Polyfilling WebAuthn in WebView DOM or Exposing Raw Cryptographic Primitives Across the Hybrid Bridge	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS delegate navigator.credentials registration and assertion directly to native Capacitor 7 plugins interfacing with Android CredentialManager and iOS ASAuthorizationPlatformPublicKeyCredentialProvider.

Engineers MUST ALWAYS delegate navigator.credentials registration and assertion directly to native Capacitor 7 plugins interfacing with Android CredentialManager and iOS ASAuthorizationPlatformPublicKeyCredentialProvider.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.