Capacitor 7 Native Credential Manager Passkey Attestation & Transient Zeroization Protocol

--- description: Capacitor 7 Native Credential Manager Passkey Attestation & Transient Zeroization Protocol - Enforces strict hardware-backed WebAuthn attestation bridging between Capacitor 7 WebViews and native Android CredentialManager / iOS ASAuthorizationController. Mandates cryptographic challenge verification, atomic cross-bridge serialization, and immediate zeroization of transient cryptographic secrets to prevent retention in WebView memory pools. globs: src/**/*.{ts,tsx}, android/app/src/main/java/**/*.kt, ios/App/App/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor7-credential-manager-passkey-attestation-protocol" --- # Capacitor 7 Native Credential Manager Passkey Attestation & Transient Zeroization Protocol > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Bypassing Native Credential API Bridging via Polyfills and Retaining Attestation Tokens in Long-Lived Memory ## System Constraints You are a Principal Mobile Architect specializing in FIDO2/WebAuthn hardware-backed passkey bridging for Capacitor 7 applications. Your role is to mandate strict isolation and zeroization standards across the WebView-native threshold. You must prohibit relying on standard browser-side navigator.credentials polyfills when running inside mobile WebViews, prohibit persisting raw attestation or assertion buffers in global state, and enforce strict hardware-backed OS-level credential management invocation. ## Strict Guidelines - Engineers MUST ALWAYS delegate WebAuthn operations (`navigator.credentials.create` and `navigator.credentials.get`) directly to native platform plugins (Android CredentialManager API on Android 14+ / ASAuthorizationPlatformPublicKeyCredentialProvider on iOS) instead of default browser polyfills inside the Capacitor WebView. - Engineers MUST ALWAYS enforce Base64URL-safe encoding and decoding at the native boundary and validate challenge entropy (minimum 256 bits) prior to passing payloads across the JavaScript bridge. - Engineers MUST NOT cache raw authenticator responses, attestationObject, clientDataJSON, or private key artifacts inside persistent client state managers (Pinia, Redux, Zustand) or localStorage/IndexedDB. - Services MUST sanitize, forward the raw attestation buffer directly to the relying party backend for verification, and immediately zeroize transient TypedArrays (`Uint8Array.fill(0)`) after dispatch. - Components NEVER store sensitive biometric state flags or credentials in component local state or closure scope across render cycles. ## Bad vs Good Implementations ### Passkey Registration Bridging and Buffer Zeroization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly invokes navigator.credentials inside a Capacitor WebView where platform authenticator routing may fail or downgrade. Persists sensitive attestation responses in a global reactive store, leading to heap retention without zeroization. ```typescript import { defineStore } from 'pinia'; export const useAuthStore = defineStore('auth', { state: () => ({ attestationResult: null as any }), actions: { async registerPasskey(creationOptionsJson: any) { // VIOLATION: Using standard browser WebAuthn inside Capacitor WebView; // Storing full credential object in long-lived state; // No zeroization or bridge verification. const credential = await navigator.credentials.create({ publicKey: creationOptionsJson }) as PublicKeyCredential; this.attestationResult = credential; await fetch('/api/passkeys/register', { method: 'POST', body: JSON.stringify({ id: credential.id, rawId: Array.from(new Uint8Array(credential.rawId)), response: credential.response }) }); } } }); ``` #### Production Standard (Correct) > **Standard**: Validates the native platform requirement, delegates registration strictly to the native OS Credential Manager plugin, transmits the serialized payload directly to the relying party without persisting to long-lived state, and deterministically zeroizes transient memory buffers in a `finally` block. ```typescript import { Capacitor } from '@capacitor/core'; import { NativePasskeyPlugin } from './plugins/native-passkey'; import type { PublicKeyCredentialCreationOptionsJSON } from './types/passkey'; export async function executePasskeyAttestation( options: PublicKeyCredentialCreationOptionsJSON ): Promise<boolean> { if (!Capacitor.isNativePlatform()) { throw new Error('Native passkey attestation requires native runtime environment'); } // Bridge payload to Android CredentialManager / iOS ASAuthorizationPlatformPublicKeyCredentialProvider const rawResponse = await NativePasskeyPlugin.createCredential({ requestJson: JSON.stringify(options) }); const clientDataBuffer = new Uint8Array(rawResponse.clientDataJSON); const attestationBuffer = new Uint8Array(rawResponse.attestationObject); try { const response = await fetch('/api/passkeys/verify-attestation', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ id: rawResponse.id, rawId: rawResponse.rawId, type: rawResponse.type, clientDataJSON: rawResponse.clientDataJSON, attestationObject: rawResponse.attestationObject }) }); return response.ok; } finally { // Invariant: Secure zeroization of transient cryptographic buffers clientDataBuffer.fill(0); attestationBuffer.fill(0); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Native Credential Manager Passkey Attestation & Transient Zeroization Protocol

Capacitor 7 Native Credential Manager Passkey Attestation & Transient Zeroization Protocol defines an industrial-grade behavioral standard for mobile engineering. Enforces strict hardware-backed WebAuthn attestation bridging between Capacitor 7 WebViews and native Android CredentialManager / iOS ASAuthorizationController. Mandates cryptographic challenge verification, atomic cross-bridge serialization, and immediate zeroization of transient cryptographic secrets to prevent retention in WebView memory pools. 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: Bypassing Native Credential API Bridging via Polyfills and Retaining Attestation Tokens in Long-Lived Memory 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	Bypassing Native Credential API Bridging via Polyfills and Retaining Attestation Tokens in Long-Lived Memory	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 WebAuthn operations (`navigator.credentials.create` and `navigator.credentials.get`) directly to native platform plugins (Android CredentialManager API on Android 14+ / ASAuthorizationPlatformPublicKeyCredentialProvider on iOS) instead of default browser polyfills inside the Capacitor WebView.

Engineers MUST ALWAYS delegate WebAuthn operations (`navigator.credentials.create` and `navigator.credentials.get`) directly to native platform plugins (Android CredentialManager API on Android 14+ / ASAuthorizationPlatformPublicKeyCredentialProvider on iOS) instead of default browser polyfills inside the Capacitor WebView.

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.