Security

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 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:

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 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 [email protected]. We take all reports seriously and will respond within 24 hours.