Security Model

Design Principles

HARP’s security model is built on three principles:

1. Zero-knowledge relay — The relay is a dumb pipe. It routes encrypted blobs and never sees plaintext. Compromising the relay reveals nothing about authorization content.
2. End-to-end encryption — Only the agent platform and the HARP app can read request/response content. The encryption key is derived via X25519 key exchange and never transmitted.
3. Biometric non-repudiation — Authorizations are signed with Ed25519 keys that require biometric authentication (Face ID / fingerprint) to use. Signatures prove a specific device authorized a specific action.

Cryptographic Primitives

Key Exchange: X25519

Used during pairing to establish a shared secret between the agent platform and the HARP app. Each side generates an ephemeral X25519 keypair. The shared secret is derived independently by both parties.

Key Derivation: HKDF-SHA256

The shared secret is passed through HKDF with salt "harp-v1-enc" to derive a 32-byte symmetric encryption key. This key is used for all subsequent request/response encryption.

Encryption: XChaCha20-Poly1305

All request and response payloads are encrypted with XChaCha20-Poly1305 (authenticated encryption with associated data). Each message uses a fresh random 24-byte nonce. The Poly1305 MAC ensures integrity and authenticity.

Signing: Ed25519

The HARP app generates an Ed25519 keypair during pairing. The private key is stored in the device’s Secure Enclave (iOS) or TEE (Android) and requires biometric authentication to use. Authorization responses are signed, providing cryptographic proof of who authorized what.

Hashing: SHA-256

Used to hash the pairing secret before storing it on the relay. The relay verifies the hash during device registration without ever seeing the raw secret.

Threat Model

What HARP Defends Against

Threat	Defense
Relay compromise	E2E encryption. Attacker sees only encrypted blobs, pair_ids, and timing metadata.
Network eavesdropping	XChaCha20-Poly1305 encryption. Even without TLS, payload content is protected.
Replay attacks	Each request has a unique request_id (UUID v7) and nonce. The relay rejects duplicate submissions.
Forged authorizations	Ed25519 signatures. The platform verifies responses against the app’s public key established during pairing.
Unauthorized authorizations	Biometric gating. The Ed25519 signing key requires Face ID or fingerprint to use.
Pairing interception	QR codes expire in 5 minutes, use ephemeral X25519 keys, and are invalidated after single use. The pairing secret is hashed for relay verification.
Rogue agent platform	Each pairing has independent keys. Compromising one platform does not affect other pairings on the same device.

What HARP Does Not Defend Against

Threat	Why	Mitigation
Compromised device	If the user’s phone is fully compromised (root/jailbreak + keylogger), the attacker can approve requests.	Device security hygiene. HARP assumes the device’s Secure Enclave/TEE is intact.
Social engineering	A user can be tricked into approving a malicious request by a convincing description.	Clear action descriptions and parameter display. User education.
Compromised agent platform	If the platform’s private key and encryption key are stolen, an attacker can send fake requests.	Secure key storage on the platform side. The app still shows the full context for human review.
Metadata analysis	The relay sees pair_id, request_id, timestamps, and payload sizes. Timing analysis can reveal usage patterns.	TLS for transport. The relay does not log requests by default.
Denial of service	An attacker can flood the relay with requests, preventing legitimate authorizations.	Rate limiting (per pair_id and per IP). Cloudflare DDoS protection for the managed relay.

Security Boundaries

┌─────────────────────────────────────────────────────┐
│ TRUSTED                                             │
│                                                     │
│  Agent Platform          HARP App                   │
│  - Encryption key        - Encryption key           │
│  - Platform keypair      - Ed25519 signing key      │
│  - Plaintext context     - Plaintext context        │
│  - Audit logs            - Decision history         │
│                                                     │
├─────────────────────────────────────────────────────┤
│ UNTRUSTED                                           │
│                                                     │
│  Relay Service                                      │
│  - Encrypted blobs only                             │
│  - Routing table (pair_id -> device)                │
│  - No plaintext, no keys, no audit data             │
│                                                     │
└─────────────────────────────────────────────────────┘

Pairing Security

The pairing flow is the most security-critical phase because it establishes the encryption keys used for all future communication.

Protections:

• QR code contains an ephemeral X25519 public key. An attacker who sees the QR but not the private key cannot derive the shared secret.
• QR code expires in 5 minutes and is single-use.
• The pairing secret is a random 32-byte value included in the QR. It is hashed (SHA-256) before being stored on the relay. The app proves possession of the secret during registration.
• The relay’s temporary pairing mailbox is deleted after completion.

Attack surface: An attacker with physical access to the QR code during the 5-minute window could scan it before the legitimate user. Mitigation: the QR is typically displayed on a trusted screen (user’s own terminal) and requires physical proximity.

Key Storage

Agent Platform

Pairing data (including the encryption key) is stored at ~/.harp/pairings/<name>.json. File permissions should be 600 (owner read/write only). In CI/CD environments, store pairing data as encrypted secrets.

HARP App

• Encryption key: Stored in expo-secure-store (Keychain on iOS, EncryptedSharedPreferences on Android).
• Ed25519 signing key: Stored in the Secure Enclave (iOS) or TEE (Android). Requires biometric authentication for each use.
• Decision history: Stored in on-device SQLite. Not synced to any cloud service.

Audit Trail

Both endpoints maintain independent audit trails:

• Platform: ~/.harp/audit/YYYY-MM-DD.jsonl — every request and response with full plaintext.
• App: On-device SQLite — every decision with full decrypted context.
• Relay: Nothing. The relay does not log request content by design.

Ed25519 signatures on authorization responses provide cryptographic non-repudiation. A signature can be verified at any time using the app’s public key (established during pairing) without contacting the relay.