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-biometric-enclave-attestation-partitioning

Capacitor 7 Hardware Enclave Attestation & Key Partitioning Invariant

Mandates that hybrid mobile applications using Capacitor 7 isolate all biometric authorization proofs within hardware-backed security modules (Apple Secure Enclave and Android KeyStore StrongBox) via cryptographic challenge-response signing. Prohibits trusting client-side boolean biometric verification flags across the bridge, preventing OS-level runtime hook attacks (e.g., Frida, Objection).

Prohibited Anti-Pattern: Boolean Biometric Evaluation and Unattested Software-Tier Credential Storage

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Capacitor 7 Hardware Enclave Attestation & Key Partitioning Invariant - Mandates that hybrid mobile applications using Capacitor 7 isolate all biometric authorization proofs within hardware-backed security modules (Apple Secure Enclave and Android KeyStore StrongBox) via cryptographic challenge-response signing. Prohibits trusting client-side boolean biometric verification flags across the bridge, preventing OS-level runtime hook attacks (e.g., Frida, Objection).
globs: src/**/*.{ts,tsx}, ios/App/App/**/*.{swift,m}, android/app/src/**/*.{java,kt}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/capacitor-7-biometric-enclave-attestation-partitioning"
---

# Capacitor 7 Hardware Enclave Attestation & Key Partitioning Invariant

> **Severity**: CRITICAL | **Category**: mobile
> **Anti-Pattern Warning**: Boolean Biometric Evaluation and Unattested Software-Tier Credential Storage

## System Constraints
You are a Principal Mobile Security Architect enforcing zero-trust hardware enclave attestation and key partitioning for Capacitor 7 hybrid applications. You must ensure that biometric authentication is never treated as a binary UI event, but as an atomic hardware-enclave cryptographic operation signing a server-issued challenge with hardware-partitioned private keys.

## Strict Guidelines
- Engineers MUST ALWAYS require a server-generated, single-use, time-bounded cryptographic nonce (minimum 256 bits of entropy) before invoking native biometric operations.
- Engineers MUST NOT authorize sensitive actions or state changes based on a boolean success flag returned across the Capacitor JavaScript bridge.
- Native plugins MUST configure private keys with UserPresence/Biometry flags strictly bound to hardware-backed key generation (kSecAccessControlBiometryAny on iOS; KeyProperties.AUTH_BIOMETRIC_STRONG with setIsStrongBoxBacked(true) on Android).
- Services MUST enforce strict key partitioning by generating domain-isolated key pairs per operation type (e.g., Authentication vs. Transaction Signing vs. Secure Storage Decryption) to prevent key-reuse vulnerabilities.
- The native layer MUST return an asymmetric signature (e.g., ECDSA over P-256) and hardware attestation cert chain to the WebView to forward directly to the backend for cryptographic validation.
- Components NEVER store sensitive raw secrets or tokens in standard WebView storage (localStorage, IndexedDB) or generic unencrypted Capacitor Preferences.

## Bad vs Good Implementations
### Biometric Authentication with Hardware Enclave Signing vs Boolean Bridge Check

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Trusts a boolean flag passed across the Capacitor bridge. An attacker with a rooted device or Frida/Objection can easily bypass the UI prompt by hooking the bridge method or the native LocalAuthentication / BiometricPrompt callback to return true without touching the hardware.
```typescript
import { BiometricAuth } from '@aparajita/capacitor-biometric-auth';
import { apiClient } from '@/services/api';

export async function authorizeTransfer(amount: number, recipientId: string): Promise<void> {
  // VULNERABLE: Relies on client-side boolean check.
  // An attacker with Frida can hook `verify()` to unconditionally return `{ hasCredentials: true, verified: true }`.
  const result = await BiometricAuth.verify({
    reason: 'Confirm funds transfer',
    title: 'Biometric Approval'
  });

  if (result.verified) {
    await apiClient.post('/transfers', { amount, recipientId });
  } else {
    throw new Error('Biometric verification failed');
  }
}
```

#### Production Standard (Correct)
> **Standard**: Shifts trust completely off the client-side execution context. The native plugin invokes the hardware enclave (Secure Enclave / Android StrongBox) to sign the server nonce. Because the private key cannot be exported or used without physical biometric confirmation at the hardware layer, tampering with runtime boolean values in the WebView or OS will fail backend verification.
```typescript
import { HardwareEnclaveAuth } from '@/plugins/hardware-enclave';
import { apiClient } from '@/services/api';

export interface TransferRequest {
  amount: number;
  recipientId: string;
}

export async function authorizeTransfer(payload: TransferRequest): Promise<void> {
  // 1. Fetch single-use cryptographic challenge from the server
  const { challengeId, nonce } = await apiClient.post<{ challengeId: string; nonce: string }>(
    '/transfers/initiate-challenge',
    payload
  );

  // 2. Request hardware enclave signing with partitioned key
  // Private key usage requires hardware-level biometric gating (Secure Enclave / Android StrongBox)
  const { signature, keyAlias } = await HardwareEnclaveAuth.signChallenge({
    keyPartition: 'TRANSACTION_SIGNING',
    challenge: nonce,
    promptTitle: 'Authorize Transaction',
    promptSubtitle: `Transferring $${payload.amount}`
  });

  // 3. Send signature and challenge back to the server for verification against registered public key
  // Runtime hooks cannot produce a valid cryptographic signature without Enclave authorization
  await apiClient.post('/transfers/finalize', {
    challengeId,
    signature,
    keyAlias
  });
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

Mobile Security Framework MCP
Performs static and dynamic security analysis of Capacitor Android and iOS application binaries for cryptographic and enclave implementation flaws.
Recommended Agent Skills (askills.dev)

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

Mobile Key Attestation Validator CLI
CLI utility to inspect native iOS/Android bridge implementations to ensure StrongBox and Secure Enclave hardware flags are properly configured.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Hardware Enclave Attestation & Key Partitioning Invariant

Capacitor 7 Hardware Enclave Attestation & Key Partitioning Invariant defines an industrial-grade behavioral standard for mobile engineering. Mandates that hybrid mobile applications using Capacitor 7 isolate all biometric authorization proofs within hardware-backed security modules (Apple Secure Enclave and Android KeyStore StrongBox) via cryptographic challenge-response signing. Prohibits trusting client-side boolean biometric verification flags across the bridge, preventing OS-level runtime hook attacks (e.g., Frida, Objection). 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: Boolean Biometric Evaluation and Unattested Software-Tier Credential Storage 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 DriftBoolean Biometric Evaluation and Unattested Software-Tier Credential StorageCritical
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 require a server-generated, single-use, time-bounded cryptographic nonce (minimum 256 bits of entropy) before invoking native biometric operations.

Engineers MUST ALWAYS require a server-generated, single-use, time-bounded cryptographic nonce (minimum 256 bits of entropy) before invoking native biometric operations.

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 authorize sensitive actions or state changes based on a boolean success flag returned across the Capacitor JavaScript bridge.

Engineers MUST NOT authorize sensitive actions or state changes based on a boolean success flag returned across the Capacitor JavaScript bridge.

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 configure private keys with UserPresence/Biometry flags strictly bound to hardware-backed key generation (kSecAccessControlBiometryAny on iOS

Native plugins MUST configure private keys with UserPresence/Biometry flags strictly bound to hardware-backed key generation (kSecAccessControlBiometryAny on iOS; KeyProperties.AUTH_BIOMETRIC_STRONG with setIsStrongBoxBacked(true) on Android).

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

Services MUST enforce strict key partitioning by generating domain-isolated key pairs per operation type (e.g., Authentication vs. Transaction Signing vs. Secure Storage Decryption) to prevent key-reuse vulnerabilities.

Services MUST enforce strict key partitioning by generating domain-isolated key pairs per operation type (e.g., Authentication vs. Transaction Signing vs. Secure Storage Decryption) to prevent key-reuse vulnerabilities.

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

The native layer MUST return an asymmetric signature (e.g., ECDSA over P-256) and hardware attestation cert chain to the WebView to forward directly to the backend for cryptographic validation.

The native layer MUST return an asymmetric signature (e.g., ECDSA over P-256) and hardware attestation cert chain to the WebView to forward directly to the backend for cryptographic validation.

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.
6

Components NEVER store sensitive raw secrets or tokens in standard WebView storage (localStorage, IndexedDB) or generic unencrypted Capacitor Preferences.

Components NEVER store sensitive raw secrets or tokens in standard WebView storage (localStorage, IndexedDB) or generic unencrypted Capacitor Preferences.

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 Enclave Attestation & Key Partitioning Invariant critical for AI coding assistants?

Mandates that hybrid mobile applications using Capacitor 7 isolate all biometric authorization proofs within hardware-backed security modules (Apple Secure Enclave and Android KeyStore StrongBox) via cryptographic challenge-response signing. Prohibits trusting client-side boolean biometric verification flags across the bridge, preventing OS-level runtime hook attacks (e.g., Frida, Objection). 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 (Boolean Biometric Evaluation and Unattested Software-Tier Credential Storage) 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