# Security

> Aerostack security model — JWT access tokens, scoped API keys, webhook secret verification, and HTTPS-only edge deployment.

Aerostack is built with security-first principles. This page documents the security model, key types, and best practices.

## Authentication Model

### JWT Tokens (Dashboard / Admin API)

Admin API routes (`/api/*`) use JWT access tokens:

- **Algorithm:** HS256 (HMAC-SHA256)
- **Access token lifetime:** 24 hours
- **Refresh token lifetime:** 30 days
- **Revocation:** JTI (JWT ID) tracked in KV — tokens can be revoked instantly

Tokens are issued on login and refreshed via the refresh endpoint. Both access and refresh tokens can be revoked (logout invalidates both).

### API Keys (Project / Public API)

Project API routes (`/v1/*`) use API keys:

| Key Type | Prefix | Access Level | Use Case |
|----------|--------|-------------|----------|
| Public key | — | Read-only (auth, realtime subscribe, storage upload, AI chat) | Browser / mobile apps |
| Secret key | — | Full access (database, cache, queue, gateway, admin) | Server-side only |
| Account key | `ak_` | Full account access across all projects | CLI / automation |
| Consumer key | `ask_live_` | Gateway API access for a specific consumer | API consumers |

**Key storage:** All keys are SHA-256 hashed before storage. The raw key is shown once at creation and never stored.

**Key caching:** API keys are cached in KV with a 5-minute TTL for sub-10ms validation latency.

### Workspace Tokens

Workspace tokens (`mwt_...`) authenticate access to MCP workspace tools:

- Generated per-workspace with configurable permissions
- Can be revoked instantly without affecting other workspace members
- Used by SDK integrations (OpenAI, LangChain, Vercel AI) and MCP clients

## Client vs Server Keys

**Client-side SDKs** (browser, mobile) use **public keys** with limited permissions:

- Authentication (login, register, OTP)
- Realtime (subscribe only, no publish)
- Storage (upload only)
- AI (chat, search)

**Server-side SDKs** (Node.js, Python, Go) use **secret keys** with full permissions:

- All client-side operations, plus:
- Database (read, write, delete)
- Cache (get, set, delete)
- Queue (publish, consume)
- Gateway (manage consumers, billing)
- Realtime (publish, kick users)

**Never expose secret keys in client-side code.** Use public keys for browsers and mobile apps.

## Data Security

### Encryption

- **Secrets (MCP/workspace):** AES-GCM encrypted at rest. Team members never see raw API keys.
- **Passwords:** PBKDF2-SHA256 with 100,000 iterations and 16-byte random salt.
- **OTP codes:** HMAC-hashed in KV storage.
- **All traffic:** TLS 1.3 enforced via Cloudflare edge.

### Tenant Isolation

- Every database query is automatically scoped to the authenticated project via `WHERE project_id = ?`
- SQL injection is prevented by a denylist (blocks DDL: DROP, ALTER, TRUNCATE, etc.) and allowlist (only SELECT, INSERT, UPDATE, DELETE, WITH)
- Multi-statement queries are blocked
- Core platform tables (`users`, `projects`, `api_keys`) are inaccessible from user functions

### CORS Policy

- **Public API endpoints:** Allow all origins (`*`)
- **Admin dashboard API:** Whitelist-based (only `*.aerostack.dev` and configured domains)
- **Credentials:** Supported on admin routes with origin validation

## Security Headers

All responses include:

| Header | Value |
|--------|-------|
| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` |
| `X-Content-Type-Options` | `nosniff` |
| `X-Frame-Options` | `DENY` |
| `Content-Security-Policy` | `default-src 'none'; frame-ancestors 'none'` |
| `Referrer-Policy` | `strict-origin-when-cross-origin` |
| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` |

## Best Practices

### Key Management

1. **Rotate keys regularly** — generate new keys and revoke old ones from the dashboard
2. **Use scoped keys** — create keys with minimal required permissions
3. **Never commit keys** — use environment variables or secret management tools
4. **Use separate keys per environment** — different keys for development and production

### Application Security

1. **Validate on the server** — never trust client-side validation alone
2. **Use HTTPS everywhere** — Aerostack enforces TLS but ensure your own endpoints do too
3. **Implement rate limiting** — see [Rate Limiting](/features/rate-limiting) for built-in limits
4. **Monitor with observability** — check error logs and anomaly detection in the dashboard

## Reporting Security Issues

If you discover a security vulnerability, please email **security@aerostack.dev**. We take all reports seriously and will respond within 24 hours.