Security Architecture

1. Overview

This page provides a transparent look at how Assistant Hub secures your data. We believe in security through transparency — understanding our architecture helps you make informed decisions about trusting us with your API keys and data.

All cryptographic operations use the Web Crypto API (not Node.js crypto), which provides hardware-backed implementations on supported platforms.

2. API Key Encryption

When you store API keys (Gemini, Grok, CoinGecko, BANKR), they are encrypted before being written to the database using AES-256-GCM — the same authenticated encryption standard used by banks and government agencies.

Encryption Flow

Technical Details

The encryption key is stored as a Railway environment variable and never committed to source code. Each value is encrypted with a unique random IV, ensuring that even identical keys produce different ciphertexts.

3. Password Security

User passwords are hashed using PBKDF2 (Password-Based Key Derivation Function 2) before storage. Plaintext passwords are never stored, logged, or transmitted after initial receipt.

Hashing Flow

The 200,000 iteration count follows current OWASP recommendations and makes brute-force attacks computationally expensive. Each user has a unique random salt, preventing rainbow table attacks.

4. Authentication

After login, you receive a signed JSON Web Token (JWT) that authenticates all subsequent API requests.

Tokens contain only non-sensitive identifiers. Passwords, API keys, and personal data are never included in the JWT payload.

5. Data in Transit

All communication between your browser and our servers is encrypted using TLS 1.2+ via Cloudflare and Railway's infrastructure.

• HTTPS everywhere — All HTTP requests are automatically upgraded to HTTPS.
• Cloudflare CDN — Provides additional DDoS protection and TLS termination.
• No URL parameters — API keys and sensitive data are never passed in URL query strings, preventing exposure in server logs and browser history.
• Secure headers — API keys are transmitted via request body or secure headers only.

6. Wallet Connectivity

Assistant Hub detects wallets using the EIP-6963 multi-wallet detection standard. Our wallet integration is strictly read-only and non-custodial.

• No private key access — We never request, receive, or store your private keys or seed phrases.
• Public address only — We only request your wallet's public address for display and portfolio tracking.
• User-signed transactions — All blockchain transactions (via BANKR) require explicit user signing in their wallet. We prepare transactions; you authorize them.
• Multi-wallet support — MetaMask, Coinbase Wallet, OKX, Phantom, Rabby, and other EIP-6963 compatible wallets with a 4-layer detection fallback.

7. Agent Isolation & Bun Worker Sandboxing

Autonomous trading agents operate within strict security boundaries, with optional V8 isolate sandboxing for condition evaluation:

• User scope — Each agent is bound to its creator's user_id. Agents cannot access other users' data, positions, or wallets.
• Paper trading only — Agents execute trades within the virtual paper trading system. No real funds are at risk unless you explicitly prepare and sign a BANKR transaction.
• Cooldown enforcement — Minimum 60-second cooldown between agent actions prevents runaway trading loops.
• Position limits — Maximum position size is capped at $100,000 (virtual) and maximum 5 agents per user.
• Premium gating — Agent deployment requires Premium tier, adding an additional access control layer.
• V8 Worker isolation — When AGENT_ISOLATION=true, each agent evaluation runs in a separate Bun Worker (isolated V8 isolate) with no shared memory, no DB access, and no network. A 5-second hard timeout prevents runaway evaluations. DB operations (trades, notifications) always run in the main thread.

8. Agent Capability Attestations (ACA)

Every autonomous trading agent operates under a formal, default-deny permission system. Rather than trusting agents by default, each must be explicitly granted specific capabilities before it can act.

Standard Capabilities

Key design decisions:

• Only READ_MARKET_DATA is granted by default — all other capabilities start denied
• WITHDRAW_FUNDS cannot be enabled at agent creation — requires a separate update with critical-severity audit logging
• Capabilities are stored as structured JSONB in PostgreSQL with GIN indexes for fast querying
• Every permission change is logged to the immutable NIST audit trail

9. Defense-in-Depth Enforcement

ACA permission checks are enforced at three independent layers. Even if one layer is bypassed, the next catches unauthorized actions.

Each gate calls enforceAcaCapability() which checks the agent's stored capabilities, logs the result to the audit trail, and hard-blocks the action if not granted — no fallback, no override.

10. NIST Framework Alignment & Audit Logging

We voluntarily align our security program with the NIST Cybersecurity Framework (CSF 2.0) and key NIST Special Publications:

• NIST SP 800-53 Rev. 5 — Security and Privacy Controls (AU-2 Audit Events)
• NIST SP 800-92 — Guide to Computer Security Log Management
• NIST SP 800-63B — Digital Identity Guidelines (password hashing, authentication)

All security-relevant events are recorded in an immutable, append-only audit log with cryptographic hash chain linking. Each entry includes a pseudonymized actor ID (never raw usernames in logs), structured event type, outcome metadata, and a SHA-256 hash that chains it to the previous entry — making any tampering detectable.

Audit Event Categories

Audit Record Structure

Every audit record contains:

• Timestamp: ISO 8601 with millisecond precision
• Event type: Structured category (e.g., agent.permission_change)
• Severity: Low, Medium, High, or Critical
• Actor: User ID or agent ID that triggered the event
• Outcome: Success or failure with reason
• Correlation ID: Links the event to the originating request trace
• Previous hash: SHA-256 hash of the previous entry's HMAC signature, creating a tamper-evident chain
• HMAC signature: Enhanced payload includes action, actor, target, detail JSON, timestamp, and previous hash

Immutability guarantee: Audit records are insert-only with cryptographic chaining. There is no UPDATE or DELETE path for audit data. The SHA-256 hash chain ensures any modification or deletion of entries is detectable via the /api/observability/audit/verify admin endpoint.

Retention & Access Policy

• Standard retention: 90 days for routine audit events
• High-severity retention: Up to 365 days for critical events (e.g., WITHDRAW_FUNDS permission changes, integrity violations)
• Access control: Audit log access is restricted to admin roles and is itself logged, preventing silent inspection

11. Distributed Request Tracing & OTLP Export

Every inbound request is assigned a unique correlation ID that propagates through the entire request lifecycle, with W3C Trace Context compatibility and configurable sampling:

• HTTP layer: Correlation ID generated in middleware, attached to every response header
• W3C Trace Context: Full traceparent header support for distributed propagation across services
• Service calls: Forwarded to all downstream providers (Gemini, Grok, BANKR, CoinGecko)
• Audit logs: Every audit event includes the correlation ID for full request reconstruction
• Error responses: Error payloads include the correlation ID so users can reference specific failures

This enables end-to-end incident investigation: from the initial HTTP request through AI provider calls, database operations, and audit events — all linked by a single ID.

Configurable Trace Sampling

Sampling is fully configurable via the TRACE_SAMPLE_RATE environment variable (default: 1.0 = 100%):

• Always sampled: Auth, payments, agent actions, comms, paper trading, settings — security-critical paths are never skipped
• Never sampled: Health checks and low-risk monitoring endpoints
• Rate-based: All other paths use the configured sample rate for cost-efficient observability
• Upstream respect: If an incoming traceparent header indicates unsampled, the decision is honored

OTLP Export (OpenTelemetry)

A native OTLP HTTP JSON exporter sends completed traces to any OpenTelemetry-compatible backend (Jaeger, Grafana Tempo, Datadog, etc.) — zero npm dependencies, pure fetch(). Configured via OTLP_ENDPOINT (disabled when empty). Batch size and flush interval are configurable; a final flush runs on SIGTERM for graceful shutdown.

Tracing Privacy & Retention

• Traces contain only operational metadata — raw prompts, API keys, and sensitive user data are never captured in trace spans
• Retention: Maximum 30 days, stored encrypted
• Access: Restricted to security and engineering investigation; trace access is itself audited

12. Supervised Message Bus & Content Guard

All inter-agent and swarm room communication passes through a dedicated content inspection layer before broadcast:

• PII blocking: Social Security Numbers, credit card numbers (Visa, Mastercard, Amex, Discover patterns) are automatically detected and blocked
• Secret detection: API keys, Bearer tokens, PEM private keys, and hex-encoded secrets are caught before they can leak into shared rooms
• Exploit prevention: Script injection (<script>), SQL injection (UNION SELECT), path traversal (../../), and command injection patterns are blocked
• Content length limits: Messages exceeding the configured maximum are rejected
• Audit trail: Every blocked message is logged to the signed NIST audit trail with the matched rule and reason

The content guard runs synchronously before message dispatch — blocked content never reaches other participants. Each pattern category can be independently enabled or disabled via configuration.

13. Behavioral Monitor & Auto-Isolation

A rolling-window anomaly detection system tracks per-agent behavior patterns and auto-escalates when thresholds are exceeded:

Escalation Path

• Paused agents are skipped by the evaluation engine until manually resumed
• Each escalation is logged to the NIST audit trail (warn for first anomaly, critical for auto-pause)
• Admin dashboard: /api/observability/monitor/agents shows tracked, warned, and paused agent counts
• resumeAgent() clears all anomaly state and resets counters for a fresh start

14. Security Architecture Overview

15. What We Don't Store

• ❌ Private keys or seed phrases
• ❌ Credit card or bank account numbers
• ❌ Social security or government ID numbers
• ❌ Browsing history or third-party tracking data
• ❌ Plaintext passwords (only PBKDF2 hashes)
• ❌ Unencrypted API keys (only AES-256-GCM ciphertext)
• ❌ IP addresses or precise geolocation
• ❌ Third-party analytics cookies

16. Safe Usage Guide

• Stealth Mode (zero data leaves your machine): Use the Free tier with Ollama (local LLM). No API keys needed, no wallet connected. All AI inference runs locally on your hardware.
• Standard Mode (encrypted keys): Connect Gemini, Grok, or Groq Cloud. Your API keys are encrypted with AES-256-GCM at rest. Chat messages are sent to the provider you select.
• Agent Mode (formal permissions): Deploy autonomous agents. All actions are gated by ACA capabilities with full NIST audit logging. Wallet is read-only — your keys, your custody.

Tip: For maximum privacy, use a VPN, an incognito browser session, and connect only throwaway test API keys until you're comfortable.

17. Vulnerability Reporting

If you discover a security vulnerability, please report it responsibly:

• Email: [email protected]
• security.txt: /.well-known/security.txt (RFC 9116)
• Include a description and steps to reproduce
• Allow reasonable time for us to investigate and patch before public disclosure
• We aim to respond within 7 days