Security Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The SweepBot security architecture is designed to protect user sweepstakes portfolio data and automation credentials through a multi-layered approach encompassing authentication, data isolation, and client-side encryption. As a platform that interacts with third-party casino interfaces, SweepBot prioritizes zero-knowledge principles for sensitive credentials and strict row-level security for cloud-stored data.
The scope of this architecture covers the Web Dashboard, REST/WebSocket API, Browser Extension, and Desktop Automation application. It specifically addresses risks such as unauthorized data exposure, privilege escalation, and injection vulnerabilities while enforcing mandatory safety guardrails for automated play.
Authentication and Authorization
SweepBot utilizes Supabase Auth for identity management, employing JSON Web Tokens (JWT) to secure API interactions. The system distinguishes between short-lived access tokens and longer-lived refresh tokens to balance security with user experience.
Token Management
- Access Tokens: 15-minute lifespan, stored in memory only (never in
localStorage) to mitigate XSS risks. - Refresh Tokens: 7-day lifespan, stored in
httpOnly,Secure,SameSite=Strictcookies to prevent client-side script access. - Validation: Every protected API route enforces JWT validation and extracts the
user_idfor request scoping.
Sources: SECURITY.md:66-72, CLAUDE.md:104-106
Tier-Based Access Control
User capabilities and API rate limits are gated based on subscription tiers (e.g., Free, Starter, Pro, Elite). Tier information is stored within the JWT user_metadata for immediate enforcement by the requireAuth middleware.
| Tier | Rate Limit | Platform Connection Limit |
|---|---|---|
| Free | 100 req/min | 2 Platforms |
| Starter | N/A | 8 Platforms |
| Pro+ | 1000 req/min | Unlimited |
Sources: SECURITY.md:83, SWEEPBOT_DASHBOARD.html:1015-1018, SWEEPBOT_DASHBOARD.html:1212-1215
Data Security and Isolation
The project implements "Security by Design" at the database and application layers to ensure that users can only access their own data.
Row Level Security (RLS)
PostgreSQL 16 (via Supabase) enforces RLS on all user-scoped tables. This ensures that even if an application-level bug occurs, the database engine itself rejects queries attempting to access rows belonging to another user_id.
Sources: SECURITY.md:76-78, AGENTS.md:121-124
Request Lifecycle Security
The following diagram illustrates the flow of an authenticated request through the security layers.
The API ensures data isolation by always including the authenticated user's ID in database queries.
Sources: SWEEPBOT_DASHBOARD.html:1124-1135, CLAUDE.md:104-106
Cryptographic Credential Vault
For the Desktop Automation app, SweepBot employs a zero-knowledge design to protect casino credentials. These credentials are never transmitted to SweepBot servers.
- Encryption: AES-256-GCM is used for client-side encryption.
- Key Derivation: Keys are derived from a user-defined master password using the Argon2id Key Derivation Function (KDF).
- Storage: Encrypted blobs are stored locally on the user's device.
Sources: SECURITY.md:86-89
API and Extension Protection
Specific security headers and validation techniques are applied to the public-facing components of the monorepo.
API Hardening
- Input Validation: All endpoints use Zod schemas to validate request bodies and parameters, preventing malformed data from reaching the logic layer.
- Query Safety: The system utilizes Drizzle ORM for parameterized queries, effectively eliminating SQL injection risks by avoiding raw string interpolation.
- Transport: Mandatory HTTPS with HSTS (HTTP Strict Transport Security) headers.
- CORS: Restricted to known SweepBot origins to prevent cross-site request forgery.
Sources: SECURITY.md:81-85, CLAUDE.md:104-106
Extension Security
The browser extension (MV3) operates under a strict Content Security Policy (CSP).
- Communication: Message passing between background workers and content scripts is validated via Zod.
- Restrictions: Use of
eval()and inline scripts is strictly prohibited. - Permissions: Host permissions are limited strictly to known sweepstakes casino domains.
Sources: SECURITY.md:92-96, AGENTS.md:58-60
Responsible Play Guardrails
Security in SweepBot extends to operational safety. The automation engine (packages/flows) includes non-negotiable guardrails to prevent harmful automation behavior.
| Guardrail | Enforcement | Override Allowed? |
|---|---|---|
max_duration | Caps sessions (default 2 hours) | No |
cool_down_check | Blocks execution during configured periods | No |
| Loop Caps | maxIterations ≤ 100, maxDuration ≤ 30 min | No |
These guardrails are baked into the ResponsiblePlayValidator and cannot be circumvented by users.
Sources: AGENTS.md:183-191, CLAUDE.md:144-150
Summary of Security Features
The following table summarizes the key security components across the architecture.
| Component | Logic | File Reference |
|---|---|---|
| Audit Logging | Captures client IP and request timing (currently being hardened) | PR_CODE_REVIEW_FIXES.md:113 |
| XSS Prevention | Sanitization of user-generated content (big wins, flow names) | SWEEPBOT_DASHBOARD.html:1571-1575 |
| Error Handling | Custom ApiError and UnauthorizedError classes | CODEBASE_IMPROVEMENTS.md:46-55 |
| Webhook Security | Stripe signature verification using STRIPE_WEBHOOK_SECRET | SWEEPBOT_DASHBOARD.html:1483-1492 |
Sources: PR_CODE_REVIEW_FIXES.md, CODEBASE_IMPROVEMENTS.md, SWEEPBOT_DASHBOARD.html
Conclusion
SweepBot's security architecture focuses on protecting user identity and financial privacy through modern standards like JWT, Argon2id, and RLS. By implementing a zero-knowledge vault for automation credentials and strictly validating all incoming data, the system minimizes the impact of potential platform-wide vulnerabilities while ensuring a secure environment for automated sweepstakes management.