batman

docs/security.md

@@ -0,0 +1,52 @@
+# Security
+
+## Authentication
+
+### Device Tokens
+- Format: `dev_` + 48 random bytes, base64url-encoded
+- Stored as SHA-256 hash in database
+- Raw token returned only once during registration
+- Expire after 90 days
+- Revocation immediately invalidates token
+
+### Client Authentication
+- Passwords hashed with bcrypt (10 rounds)
+- JWT access tokens (24h expiration)
+- Refresh tokens with rotation and revocation
+- Tokens stored in HttpOnly cookies on dashboard
+
+## Authorization
+
+### Role-Based Access
+- `admin`: Full access including device management and revocation
+- `viewer`: Read-only access to tabs, devices, and commands
+
+### Venue Isolation
+- Every user and device is scoped to exactly one venue
+- All service methods validate venue context from authentication
+- Cross-venue access is blocked at the service layer
+
+## API Security
+
+### Headers
+- Helmet for security headers
+- Strict CORS (dashboard origin only)
+- Body size limits enforced
+
+### Rate Limiting
+- Device sync: 1 request per 30 seconds per device
+- Command creation: 10 requests per minute per user
+- General: 100 requests per minute per client
+
+### Error Handling
+- Consistent error format never exposes internals
+- No secrets in error messages
+- No stack traces in production
+
+## Audit Trail
+
+All sensitive operations are logged:
+- Command creation, acknowledgement, expiration
+- Device registration and revocation
+- Snapshot conflicts
+- No sensitive data (passwords, tokens) in audit logs