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-biometric-secure-keystore-isolation

Capacitor 7 Biometric-Bound Secure KeyStore Cryptographic Isolation

Enforces hardware-backed cryptographic key isolation in Capacitor 7 hybrid applications via iOS Secure Enclave and Android Hardware KeyStore. Mandates that authentication tokens, refresh credentials, and cryptographic signing keys remain inaccessible to the inspectable WebKit web view sandbox, unencrypted SQLite, and local web storage. Restricts secret persistence strictly to biometrically gated native keychain primitives with zero-persistence memory buffers.

Prohibited Anti-Pattern: Leaking Long-Lived Credentials into Inspectable WebKit Web Storage or Unencrypted Capacitor Preferences

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Capacitor 7 Biometric-Bound Secure KeyStore Cryptographic Isolation - Enforces hardware-backed cryptographic key isolation in Capacitor 7 hybrid applications via iOS Secure Enclave and Android Hardware KeyStore. Mandates that authentication tokens, refresh credentials, and cryptographic signing keys remain inaccessible to the inspectable WebKit web view sandbox, unencrypted SQLite, and local web storage. Restricts secret persistence strictly to biometrically gated native keychain primitives with zero-persistence memory buffers.
globs: src/**/*.{ts,tsx,js,jsx}, ios/App/**/*.{swift,h,m}, android/app/**/*.{kt,java}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/capacitor-biometric-secure-keystore-isolation"
---

# Capacitor 7 Biometric-Bound Secure KeyStore Cryptographic Isolation

> **Severity**: CRITICAL | **Category**: mobile
> **Anti-Pattern Warning**: Leaking Long-Lived Credentials into Inspectable WebKit Web Storage or Unencrypted Capacitor Preferences

## System Constraints
You are a Principal Mobile Security Architect enforcing strict hardware-backed cryptographic isolation for Capacitor 7. You must prevent any storage of authentication artifacts in standard WebKit containers (localStorage, sessionStorage, IndexedDB, or standard unencrypted Capacitor Preferences). Every secret must be managed through biometrically gated native keychain/keystore plugins utilizing iOS Secure Enclave (kSecAccessControlBiometryCurrentSet) or Android KeyStore with setUserAuthenticationRequired(true). Sensitive values in JavaScript must be transient, scoped to runtime memory closures, and never leaked to persistent inspectable layers or console streams.

## Strict Guidelines
- Engineers MUST ALWAYS store long-lived tokens, refresh tokens, and private keys within hardware-backed native vaults (iOS Keychain with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly/Biometry, Android KeyStore with KeyGenParameterSpec.Builder).
- Engineers MUST NOT persist raw access tokens, refresh tokens, or session identifiers in WebKit `window.localStorage`, `window.sessionStorage`, unencrypted IndexedDB, document cookies, or the baseline `@capacitor/preferences` plugin.
- Services MUST instantiate transient memory handles for active API tokens that are wiped immediately on application pause, background transition, or user logout.
- Components NEVER render or log cryptographic tokens, private keys, or raw biometrically decrypted values into WebKit DevTools console logs, diagnostics events, or analytics telemetry.
- Native plugins MUST enforce biometric re-authentication (Face ID, Touch ID, Android BiometricPrompt) before releasing or operating on hardware-sealed cryptographic keys.
- Code SHOULD prefer public-key request signing within the native Secure Enclave/KeyStore over exposing private keys or long-lived symmetric secrets to the JavaScript bridge.

## Bad vs Good Implementations
### Biometric Native Vault vs Web Storage Leak

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Writing tokens to localStorage or unencrypted Capacitor Preferences exposes secrets directly to Safari/Chrome remote WebKit inspection, XSS exploits, and plain-text file extraction from device backups.
```typescript
import { Preferences } from '@capacitor/preferences';

interface AuthResponse {
  accessToken: string;
  refreshToken: string;
}

export async function handleLoginSuccess(response: AuthResponse): Promise<void> {
  // CRITICAL SECURITY FLAW: Stored in WebKit inspectable storage / unencrypted XML/plist
  localStorage.setItem('access_token', response.accessToken);
  await Preferences.set({
    key: 'refresh_token',
    value: response.refreshToken,
  });
  console.log('Stored session tokens:', response);
}
```

#### Production Standard (Correct)
> **Standard**: Enforces verified production invariants and compliant error handling.
```typescript
import { NativeBiometricVault } from '@/plugins/native-biometric-vault';

interface AuthResponse {
  accessToken: string;
  refreshToken: string;
}

// Ephemeral in-memory store; never written to persistent WebKit storage
let ephemeralAccessToken: string | null = null;

export async function handleLoginSuccess(response: AuthResponse): Promise<void> {
  // Retain access token purely in memory closure for active HTTP session
  ephemeralAccessToken = response.accessToken;

  // Hardware-isolate refresh token into Secure Enclave / Android KeyStore
  await NativeBiometricVault.setBiometricSecret({
    key: 'auth_refresh_token',
    value: response.refreshToken,
    accessControl: 'BIOMETRY_CURRENT_SET_OR_DEVICE_PASSCODE',
    requireBiometricPrompt: true,
    promptTitle: 'Authenticate to protect your session',
  });
}

export function getEphemeralAccessToken(): string | null {
  return ephemeralAccessToken;
}

export function clearSessionMemory(): void {
  ephemeralAccessToken = null;
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

Mobile Security Analysis MCP
Scans Capacitor/Cordova artifacts for local storage leaks and unencrypted preferences.
Recommended Agent Skills (askills.dev)

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

Capacitor Security Auditor CLI
Verifies native bridge configurations, permissions, and plugin storage mechanisms.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Biometric-Bound Secure KeyStore Cryptographic Isolation

Capacitor 7 Biometric-Bound Secure KeyStore Cryptographic Isolation defines an industrial-grade behavioral standard for mobile engineering. Enforces hardware-backed cryptographic key isolation in Capacitor 7 hybrid applications via iOS Secure Enclave and Android Hardware KeyStore. Mandates that authentication tokens, refresh credentials, and cryptographic signing keys remain inaccessible to the inspectable WebKit web view sandbox, unencrypted SQLite, and local web storage. Restricts secret persistence strictly to biometrically gated native keychain primitives with zero-persistence memory buffers. 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: Leaking Long-Lived Credentials into Inspectable WebKit Web Storage or Unencrypted Capacitor Preferences 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 DriftLeaking Long-Lived Credentials into Inspectable WebKit Web Storage or Unencrypted Capacitor PreferencesCritical
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 store long-lived tokens, refresh tokens, and private keys within hardware-backed native vaults (iOS Keychain with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly/Biometry, Android KeyStore with KeyGenParameterSpec.Builder).

Engineers MUST ALWAYS store long-lived tokens, refresh tokens, and private keys within hardware-backed native vaults (iOS Keychain with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly/Biometry, Android KeyStore with KeyGenParameterSpec.Builder).

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 persist raw access tokens, refresh tokens, or session identifiers in WebKit `window.localStorage`, `window.sessionStorage`, unencrypted IndexedDB, document cookies, or the baseline `@capacitor/preferences` plugin.

Engineers MUST NOT persist raw access tokens, refresh tokens, or session identifiers in WebKit `window.localStorage`, `window.sessionStorage`, unencrypted IndexedDB, document cookies, or the baseline `@capacitor/preferences` plugin.

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

Services MUST instantiate transient memory handles for active API tokens that are wiped immediately on application pause, background transition, or user logout.

Services MUST instantiate transient memory handles for active API tokens that are wiped immediately on application pause, background transition, or user logout.

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

Components NEVER render or log cryptographic tokens, private keys, or raw biometrically decrypted values into WebKit DevTools console logs, diagnostics events, or analytics telemetry.

Components NEVER render or log cryptographic tokens, private keys, or raw biometrically decrypted values into WebKit DevTools console logs, diagnostics events, or analytics telemetry.

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 plugins MUST enforce biometric re-authentication (Face ID, Touch ID, Android BiometricPrompt) before releasing or operating on hardware-sealed cryptographic keys.

Native plugins MUST enforce biometric re-authentication (Face ID, Touch ID, Android BiometricPrompt) before releasing or operating on hardware-sealed cryptographic keys.

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

Code SHOULD prefer public-key request signing within the native Secure Enclave/KeyStore over exposing private keys or long-lived symmetric secrets to the JavaScript bridge.

Code SHOULD prefer public-key request signing within the native Secure Enclave/KeyStore over exposing private keys or long-lived symmetric secrets to the 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.
Technical Questions & Answers

Frequently Asked Technical Questions

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

Q:Why is Capacitor 7 Biometric-Bound Secure KeyStore Cryptographic Isolation critical for AI coding assistants?

Enforces hardware-backed cryptographic key isolation in Capacitor 7 hybrid applications via iOS Secure Enclave and Android Hardware KeyStore. Mandates that authentication tokens, refresh credentials, and cryptographic signing keys remain inaccessible to the inspectable WebKit web view sandbox, unencrypted SQLite, and local web storage. Restricts secret persistence strictly to biometrically gated native keychain primitives with zero-persistence memory buffers. 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 (Leaking Long-Lived Credentials into Inspectable WebKit Web Storage or Unencrypted Capacitor Preferences) 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