Security Model

This document describes the threat model, security boundaries, encryption mechanisms, and compliance direction for the Hippocortex platform.

Security Principles

1. Deny by default: All access requires explicit authentication and authorization
2. Least privilege: Users and agents receive the minimum permissions necessary
3. Defense in depth: Multiple security layers (network, auth, RBAC, encryption)
4. Auditability: Security-relevant actions are logged with actor identity and timestamp
5. Data isolation: Tenant data is strictly isolated at the query layer
6. No trust in input: All API input is validated and sanitized

Threat Model

Threat Actors

Actor	Capability	Motivation
External attacker	Network access, public API endpoints	Data theft, service disruption
Compromised agent	Valid API key, scoped access	Data exfiltration beyond allowed scope
Malicious insider	Valid user credentials, org membership	Unauthorized data access
Compromised dependency	Code execution in build/runtime	Supply chain attack
Cloud provider	Infrastructure access	Data access (mitigated by encryption)

Attack Surface

+----------------------------------------------------------+
|  EXTERNAL ATTACK SURFACE                                  |
|                                                          |
|  [HTTPS endpoints]                                       |
|    api.hippocortex.dev                                   |
|    dashboard.hippocortex.dev                             |
|    docs.hippocortex.dev                                  |
|                                                          |
|  [Authentication]                                        |
|    Clerk (OAuth/SSO), JWT, API Keys                      |
|                                                          |
|  [API Input]                                             |
|    JSON request bodies, query parameters, headers        |
+----------------------------------------------------------+

+----------------------------------------------------------+
|  INTERNAL ATTACK SURFACE                                  |
|                                                          |
|  [Container-to-container]                                |
|    Docker bridge network (no public exposure)            |
|                                                          |
|  [Data stores]                                           |
|    PostgreSQL (encrypted at rest via disk encryption)    |
|    Redis (in-memory, persistence to disk)                |
|                                                          |
|  [Environment variables]                                 |
|    VAULT_MASTER_KEY, API keys, database credentials      |
+----------------------------------------------------------+

Threat Scenarios and Mitigations

#	Threat	Impact	Likelihood	Mitigation
T1	Stolen API key	Unauthorized memory access	Medium	Key rotation, scope restrictions, rate limiting
T2	JWT forgery	Identity spoofing	Low	RSA/EC signature verification, short expiry
T3	SQL injection	Data breach	Low	Parameterized queries only, no raw SQL
T4	XSS in dashboard	Session hijack	Low	CSP headers, input sanitization, HttpOnly cookies
T5	SSRF via capture	Internal network scan	Medium	Input URL validation, no server-side fetching of user URLs
T6	Credential leak in memory	Secret exposure	High	Automatic secret detection and vault redaction
T7	Cross-tenant data access	Data breach	Low	Row-level tenant filtering, no cross-tenant queries
T8	Brute force auth	Account takeover	Medium	Rate limiting, Clerk lockout policies
T9	Database backup theft	Data breach	Low	Encrypted backups, restricted backup access
T10	DDoS	Service unavailability	Medium	Rate limiting, Traefik configuration, Hetzner DDoS protection

Security Boundaries

Network Boundaries

Public Internet
       |
       | TLS 1.2+ only
       v
+------------------+
|     Traefik      |  <-- Boundary 1: TLS termination
|  (reverse proxy) |      HTTP to HTTPS redirect
+--------+---------+      CORS enforcement
         |
         | HTTP (internal)
         v
+------------------+
|   API Server     |  <-- Boundary 2: Authentication
|   (Hono)         |      RBAC enforcement
+--------+---------+      Input validation
         |
         | Authenticated queries
         v
+------------------+
|   Data Layer     |  <-- Boundary 3: Data isolation
|  (PostgreSQL)    |      Row-level tenant filtering
|  (Redis)         |      Encrypted vault items
+------------------+

Authentication Boundary

All API endpoints (except health checks) require authentication:

Endpoint Category	Auth Required	Method
Health checks (/health, /ready)	No	None
Public API (/v1/*)	Yes	JWT, API Key, or Clerk token
Admin API (/admin/*)	Yes	X-Admin-Key header
Dashboard API	Yes	Clerk session token
Metrics (/metrics)	No	Internal network only

Authorization Boundary

After authentication, the RBAC layer enforces permissions:

1. Organization membership: User must be a member of the organization
2. Role-based permissions: User's org role must include the required permission
3. Namespace scoping: Memory operations are restricted to accessible namespaces
4. Agent scoping: Agent access is restricted to configured allowedScopes
5. Vault permissions: Vault access requires explicit permission grants

Encryption

In Transit

Connection	Encryption
Client to Traefik	TLS 1.2+ (Let's Encrypt certificates)
Traefik to API	HTTP (internal Docker network, no public exposure)
API to PostgreSQL	Optional TLS (configured via POSTGRES_SSL)
API to Redis	Optional TLS (configured via REDIS_TLS)

At Rest

Data	Encryption
Vault items	AES-256-GCM with per-item random IV
Vault notes	AES-256-GCM (same key, separate IV)
Database	Disk-level encryption (Hetzner server encryption)
Backups	pgdump with server-side encryption
Redis persistence	Disk-level encryption

Key Management

Key	Storage	Rotation
VAULT_MASTER_KEY	Environment variable	Manual (re-encrypt all items)
API keys (hx_live_*)	Hashed in PostgreSQL	User-initiated
JWT signing key	Clerk-managed	Clerk rotation policy
TLS certificates	Let's Encrypt (auto-renewed)	90-day auto-rotation

Input Validation

API Input

All API input is validated using Zod schemas:

• Request body JSON is parsed and validated against typed schemas
• Query parameters are type-checked and range-validated
• Path parameters are validated (UUID format, slug format)
• Headers are validated (Authorization format, content types)

Content Limits

Limit	Value	Purpose
Request body size	1 MB	Prevent memory exhaustion
Capture text length	100,000 chars	Reasonable memory size
Query string length	10,000 chars	Prevent oversized queries
Tags per item	50	Prevent tag abuse
Tag length	100 chars	Reasonable tag size

Secret Detection in Input

The secret detection engine scans all captured text for credentials before storage. Detected secrets are:

1. Extracted and stored in the vault
2. Replaced with vault references in the stored memory
3. Never stored in plaintext in the memory tables

Rate Limiting

Tier	Rate Limit	Scope
Free	100 req/min	Per API key
Pro	1,000 req/min	Per API key
Enterprise	Custom	Per API key or per organization

Rate limiting is enforced at the API middleware layer using Redis-backed sliding window counters.

Responses include rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1710460800

Audit Logging

What Is Logged

Category	Events
Authentication	Login, logout, failed login, token refresh
Authorization	Permission granted, permission denied
Data access	Memory read, memory write, memory delete
Vault	Secret created, revealed, updated, deleted
Admin	Tenant management, user management, queue operations
Configuration	Policy changes, namespace changes, role changes

Audit Log Properties

• Immutable: Audit entries cannot be modified or deleted through the API
• Timestamped: UTC timestamps with millisecond precision
• Actor-attributed: Every entry includes the authenticated actor's identity
• Retention: Enterprise plan audit logs are retained indefinitely

Compliance Direction

Hippocortex is designed with compliance frameworks in mind, though formal certifications are not yet obtained:

Framework	Status	Relevant Controls
SOC 2 Type II	Planned	Access controls, encryption, audit logging
GDPR	Partial	Data isolation, retention policies, deletion support
HIPAA	Planned	Encryption at rest, audit trail, access controls
ISO 27001	Planned	Security boundaries, risk assessment, incident response

Data Residency

Current deployment: Single-region (Hetzner, Germany/EU). All data resides in the EU.

Future: Multi-region deployment with data residency controls per tenant.

Data Deletion

Hippocortex supports data deletion for compliance:

• Memory deletion: Individual memories can be deleted via API
• Namespace deletion: All memories in a namespace can be deleted
• Tenant deletion: All tenant data can be purged (admin action)
• Retention policies: Automatic deletion after configurable retention periods

Incident Response

The incident response procedure covers:

• Security incident classification
• Escalation procedures
• Communication templates
• Post-incident review process