> ## Documentation Index
> Fetch the complete documentation index at: https://haptix-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Architecture

> In-depth cryptographic security specifications, key hierarchy, WYSIWYS inspection, and cluster replay prevention.

# Security Architecture & Threat Model

Haptix replaces single private key storage with an **on-chain Anchor smart account architecture** where signing rights are bound directly to hardware security enclaves using NIST P-256 (secp256r1) WebAuthn credentials.

This eliminates the two primary vulnerabilities in crypto:

1. **Seed Phrase Leakage / Phishing**: Private keys never leave the phone's hardware enclave (Android Keystore / StrongBox and Apple Secure Enclave).
2. **Single-Signature Catastrophic Drain**: Transfers exceeding user-defined spend limits mathematically require a 2-of-2 hardware quorum across independent devices.

***

## 1. Key Hierarchy & Authority Separation

To prevent backdoor vulnerabilities and enforce defense-in-depth, Haptix enforces strict operational separation:

| Role | Key Type | Privileges & Constraints |
| :- | :- | :- |
| **Primary Passkey** | NIST P-256 (WebAuthn) | Routine transfers (\le Spend Threshold), 1-tap biometrics. |
| **Secondary Passkey (Vault Key)** | NIST P-256 (WebAuthn) | Co-signs transfers (> Spend Threshold) and on-chain policy updates. |
| **Recovery Guardian** | Independent Solana Keypair | Freeze wallet, initiate 24-hour timelocked key rotation. **Cannot spend funds.** |
| **Relayer (Fee Payer)** | Ed25519 System Keypair | Pays network transaction & rent fees ONLY. **Cannot sign for wallet PDA.** |
| **Program Upgrade Authority** | BPF Upgradeable Loader | Upgradable on Devnet; timelocked Squads v4 multisig on Mainnet. |

***

## 2. What-You-See-Is-What-You-Sign (WYSIWYS)

Both the mobile client and passkey engine enforce strict payload inspection before user verification or invoking the device enclave:

### A. Pre-Signature Binary Validation

Arbitrary binary payloads and blind hashes are rejected immediately with a security exception. Every authorized instruction requires an exact byte length:

| Instruction | Exact Payload Length | Validated Elements |
| :- | :- | :- |
| `TRANSFER` | **97 Bytes** | Cluster tag, recipient (bytes 57..89), amount (bytes 89..97) |
| `SET_GUARDIAN` | **93 Bytes** | Cluster tag, proposed guardian pubkey, auth nonce |
| `SET_THRESHOLD` | **70 Bytes** | Cluster tag, new threshold lamports (u64 LE), auth nonce |
| `GRANT_AGENT` | **140 Bytes** | Cluster tag, agent pubkey, spend allowance, expiry timestamp |
| `REVOKE_AGENT` | **93 Bytes** | Cluster tag, revoked agent pubkey, auth nonce |
| `UNFREEZE_WALLET` | **64 Bytes** | Cluster tag, wallet PDA, auth nonce |
| `CANCEL_RECOVERY` | **64 Bytes** | Cluster tag, wallet PDA, auth nonce |

### B. Display Consistency Verification

The recipient address and amount displayed on screen are cross-verified against the recipient (bytes 57..89) and amount (bytes 89..97) decoded from the 97-byte message buffer. If the on-screen recipient or amount differs from the byte payload, signing is immediately aborted.

***

## 3. Autonomous Agent Hot-Key Budgets

Haptix provides native session key grants for AI agents (e.g., Jupiter Auto-DCA, trading algorithms):

* **Autonomous Allowance**: Once granted via a 2-of-2 hardware passkey quorum, an agent key can sign transactions without prompting for biometrics, up to its explicit budget cap.
* **Budget Isolation**: The agent's allowance is an independent budget that does **not** count against or consume the human owner's daily spend threshold.
* **Time-Bounded Expiry**: Agent sessions enforce short expiration timestamps (e.g., 1h to 24h).
* **Instant Revocation**: Owners can revoke an agent session at any time. Revocation remains fully operational even if the wallet is locked/frozen.

***

## 4. Cluster Binding & Replay Prevention

1. **8-Byte Cluster Tag**: Every signed message includes an 8-byte ASCII cluster identifier (`devnet\0\0` or `mainnet\0`). On-chain programs reject authorization messages where the embedded cluster tag does not match the account's bound cluster.
2. **Domain Separation**: Devnet currently operates under Program ID `9wC1ok8d4PrBDG3TS7iyEu9QxMCYv6BKrdLb3q4yZbke`. Mainnet production deployment will mint an independent Program ID to guarantee physical instruction domain separation.
3. **Sequential Auth Nonces**: Every state-changing owner authorization increments an on-chain `auth_nonce`, preventing replay of previously captured WebAuthn assertions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.