AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
mobilecritical PriorityID: capacitor-7-passkey-hardware-enclave-bridge-standard

Capacitor 7 Hardware-Backed WebAuthn Enclave Synchronization Guardrail

Bridges hybrid WebView navigator.credentials invocations directly into hardware-backed Secure Enclave (iOS ASAuthorizationPlatformPublicKeyCredentialProvider) and Android KeyStore/FIDO2 Credential Manager APIs. Prohibits polyfill execution inside software-only contexts and prevents state desynchronization between native async lifecycle hooks and the hybrid bridge thread.

Prohibited Anti-Pattern: Interception-Bypass and Bridge Execution Desynchronization in Hybrid WebAuthn Flows

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Capacitor 7 Hardware-Backed WebAuthn Enclave Synchronization Guardrail - Bridges hybrid WebView navigator.credentials invocations directly into hardware-backed Secure Enclave (iOS ASAuthorizationPlatformPublicKeyCredentialProvider) and Android KeyStore/FIDO2 Credential Manager APIs. Prohibits polyfill execution inside software-only contexts and prevents state desynchronization between native async lifecycle hooks and the hybrid bridge thread.
globs: ios/App/App/**/*.swift, android/app/src/**/*.kt, src/**/*.{ts,tsx}, capacitor.config.ts
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/capacitor-7-passkey-hardware-enclave-bridge-standard"
---

# Capacitor 7 Hardware-Backed WebAuthn Enclave Synchronization Guardrail

> **Severity**: CRITICAL | **Category**: mobile
> **Anti-Pattern Warning**: Interception-Bypass and Bridge Execution Desynchronization in Hybrid WebAuthn Flows

## System Constraints
You are a Principal Mobile Systems Architect and Security Engineer enforcing Capacitor 7 Passkey Hardware Enclave Bridge standards. Enforce strict isolation between hybrid WebView WebAuthn bindings and hardware cryptoprocessors (Apple Secure Enclave, Android StrongBox/TEE). Prevent race conditions, thread deadlock, and broken cryptographic validation in native-to-web IPC bridges.

## Strict Guidelines
- Engineers MUST ALWAYS intercept `navigator.credentials.create` and `navigator.credentials.get` at the native WebView layer, routing calls directly to native platform credential authenticators (ASAuthorizationController or Android CredentialManager).
- Engineers MUST NOT handle WebAuthn challenge signing or private key generation inside JavaScript runtimes or software-fallback crypto libraries.
- Native plugins MUST enforce UI-thread dispatching for modal OS authenticators while offloading cryptographic payload processing to background dispatch queues to prevent UI thread lock.
- The bridge MUST maintain atomic session locks during native biometric prompts, preventing duplicate credential requests or premature cancellation timeouts emitted by the hybrid client runtime.
- Native bridge implementations MUST strictly reject clientDataJSON and authenticatorData payloads that lack verification of the native App ID binding / Digital Asset Links.

## Bad vs Good Implementations
### Capacitor 7 Native Bridge Client Invocation

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Directly calling navigator.credentials inside a Capacitor WebView fails platform-origin checks (capacitor://localhost or https://localhost), bypasses native Credential Manager/ASAuthorizationController integration, and fails to engage hardware-backed security modules reliably across iOS and Android.
```typescript
import { Capacitor } from '@capacitor/core';

export async function authenticatePasskey(challengeBase64: string): Promise<Credential | null> {
  // Anti-pattern: Relying on WebView's native navigator.credentials directly without
  // native bridge synchronization causes origin mismatch and bypasses StrongBox/Enclave.
  const credential = await navigator.credentials.get({
    publicKey: {
      challenge: Uint8Array.from(atob(challengeBase64), c => c.charCodeAt(0)),
      rpId: 'example.com',
      userVerification: 'required',
      timeout: 60000,
    }
  });
  return credential;
}
```

#### Production Standard (Correct)
> **Standard**: Forces execution through a registered Capacitor native bridge, ensuring invocations leverage ASAuthorizationPlatformPublicKeyCredentialProvider (iOS) and CredentialManager with BiometricPrompt (Android), preserving hardware enclave isolation.
```typescript
import { registerPlugin } from '@capacitor/core';

interface NativePasskeyPlugin {
  getAssertion(options: { challenge: string; rpId: string; timeoutMs: number }): Promise<{
    credentialId: string;
    rawId: string;
    authenticatorData: string;
    clientDataJSON: string;
    signature: string;
    userHandle?: string;
  }>;
}

const NativePasskey = registerPlugin<NativePasskeyPlugin>('NativePasskey');

export async function authenticatePasskey(challengeBase64: string): Promise<{
  credentialId: string;
  authenticatorData: string;
  clientDataJSON: string;
  signature: string;
}> {
  // Invariant: Native plugin coordinates with iOS Secure Enclave / Android StrongBox
  // and resolves through atomic native async task handles to eliminate thread race conditions.
  const result = await NativePasskey.getAssertion({
    challenge: challengeBase64,
    rpId: 'example.com',
    timeoutMs: 60000,
  });

  return {
    credentialId: result.credentialId,
    authenticatorData: result.authenticatorData,
    clientDataJSON: result.clientDataJSON,
    signature: result.signature,
  };
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

GitHub Context Server
Reads repository state, tracking native Capacitor bridge definitions and Gradle/CocoaPods native dependencies.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Capacitor CLI Runner
Executes 'cap sync', 'cap run android', and 'cap run ios' to validate native hardware bridge builds.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware-Backed WebAuthn Enclave Synchronization Guardrail

Capacitor 7 Hardware-Backed WebAuthn Enclave Synchronization Guardrail defines an industrial-grade behavioral standard for mobile engineering. Bridges hybrid WebView navigator.credentials invocations directly into hardware-backed Secure Enclave (iOS ASAuthorizationPlatformPublicKeyCredentialProvider) and Android KeyStore/FIDO2 Credential Manager APIs. Prohibits polyfill execution inside software-only contexts and prevents state desynchronization between native async lifecycle hooks and the hybrid bridge thread. 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: Interception-Bypass and Bridge Execution Desynchronization in Hybrid WebAuthn Flows 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftInterception-Bypass and Bridge Execution Desynchronization in Hybrid WebAuthn FlowsCritical
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 InconsistencyAI 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:

1

Engineers MUST ALWAYS intercept `navigator.credentials.create` and `navigator.credentials.get` at the native WebView layer, routing calls directly to native platform credential authenticators (ASAuthorizationController or Android CredentialManager).

Engineers MUST ALWAYS intercept `navigator.credentials.create` and `navigator.credentials.get` at the native WebView layer, routing calls directly to native platform credential authenticators (ASAuthorizationController or Android CredentialManager).

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST NOT handle WebAuthn challenge signing or private key generation inside JavaScript runtimes or software-fallback crypto libraries.

Engineers MUST NOT handle WebAuthn challenge signing or private key generation inside JavaScript runtimes or software-fallback crypto libraries.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Native plugins MUST enforce UI-thread dispatching for modal OS authenticators while offloading cryptographic payload processing to background dispatch queues to prevent UI thread lock.

Native plugins MUST enforce UI-thread dispatching for modal OS authenticators while offloading cryptographic payload processing to background dispatch queues to prevent UI thread lock.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

The bridge MUST maintain atomic session locks during native biometric prompts, preventing duplicate credential requests or premature cancellation timeouts emitted by the hybrid client runtime.

The bridge MUST maintain atomic session locks during native biometric prompts, preventing duplicate credential requests or premature cancellation timeouts emitted by the hybrid client runtime.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Native bridge implementations MUST strictly reject clientDataJSON and authenticatorData payloads that lack verification of the native App ID binding / Digital Asset Links.

Native bridge implementations MUST strictly reject clientDataJSON and authenticatorData payloads that lack verification of the native App ID binding / Digital Asset Links.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Capacitor 7 Hardware-Backed WebAuthn Enclave Synchronization Guardrail critical for AI coding assistants?

Bridges hybrid WebView navigator.credentials invocations directly into hardware-backed Secure Enclave (iOS ASAuthorizationPlatformPublicKeyCredentialProvider) and Android KeyStore/FIDO2 Credential Manager APIs. Prohibits polyfill execution inside software-only contexts and prevents state desynchronization between native async lifecycle hooks and the hybrid bridge thread. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Interception-Bypass and Bridge Execution Desynchronization in Hybrid WebAuthn Flows) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related MOBILE Rules

View all rules →
mobile
106

Tauri 2.0 Mobile IPC & Capabilities Permissions Matrix Standard

Tauri v2 introduces a capability-driven permissions system replacing legacy v1 allowlists across iOS and Android runtimes. Failure to constrain IPC command handlers with typed schemas and explicit mobile capability definitions exposes native mobile OS surfaces to arbitrary code execution, permission leakage, and silent serialization failures. Production mobile deployments require strictly typed IPC boundary validation, granular capability scopes, and graceful permission degradation.

mobile
70

Capacitor 7 Native Bridge, Biometric Auth & Android 15 Lifecycle Production Standard

Capacitor 7 enforces strict bridge lifecycle contracts, asynchronous native plugin interop, and mandatory Android 15 edge-to-edge window inset handling. Storing sensitive authentication tokens in unencrypted web storage or failing to bind biometric authentication directly to hardware-backed Keystore or Secure Enclave mechanisms compromises app integrity and causes fatal crash or viewport occlusion issues on modern mobile operating systems.

mobile
58

Tauri 2.0 Mobile IPC Isolation and Capabilities Permission Scoping

Enforces strict capability permission boundaries, payload validation, and secure IPC invoke scoping for Tauri v2 Android and iOS environments. Prevents arbitrary IPC command execution, excessive native privilege granting, and deserialization vulnerabilities across the mobile webview-native boundary.

1 Rule in Stack

Capacitor