File uploads, better UI, UA restrictions

Restrict use to "Cloud Phone" user agent
Allow QR uploads file image files
Better UI (colors, sizing, blink animation, etc)
Soft keys and keyboard navigation

Author: Tombarr

CLAUDE.md

@@ -0,0 +1,166 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+MFA Sync Service - A secure, ephemeral MFA secret key sharing service designed for devices without cameras. Allows secure transfer of TOTP secrets via short-lived, encrypted, PIN-based exchanges.
+
+## Essential Commands
+
+### Development
+```bash
+# Install dependencies
+npm install
+
+# Start development server (auto-restarts Redis daemon + Node with --watch)
+npm run dev
+
+# Start production server
+npm start
+```
+
+### Docker Operations
+```bash
+# Build Docker image
+npm run docker:build
+
+# Start services (app + Redis + nginx)
+npm run docker:run
+
+# Stop services
+npm run docker:stop
+
+# View logs
+npm run docker:logs
+```
+
+### Code Quality
+```bash
+# Format code
+npx prettier --write .
+```
+
+## Architecture
+
+### Core Technology Stack
+- **Runtime**: Node.js 24+ with ES modules (`"type": "module"`)
+- **Framework**: Express 5.x
+- **Storage**: Redis (in-memory ephemeral storage with TTL)
+- **Security**: Helmet, CORS, express-rate-limit, AES-256-GCM encryption
+
+### Key Architectural Patterns
+
+**Ephemeral Secret Exchange Flow**:
+1. Admin device scans QR code → extracts TOTP secret
+2. POST `/api/store` → encrypts secret with random key, generates random 6-digit PIN, stores in Redis with TTL
+3. Feature phone retrieves via POST `/api/retrieve` with PIN
+4. Secret auto-deletes after retrieval (one-time use) or on TTL expiration
+
+**Security Layers**:
+- **Encryption at Rest**: Secrets encrypted with AES-256-GCM before Redis storage, unique key per secret
+- **Ephemeral Storage**: Redis TTL (default 120s) + immediate deletion after retrieval
+- **Rate Limiting**: 10 secrets per 15min (store), 20 attempts per 5min (retrieve)
+- **CSP + SRI**: Nonce-based Content Security Policy with Subresource Integrity hashes
+
+### Critical Files
+
+**`server.js`** (main application):
+- Express server setup with security middleware
+- Four main endpoints: `/api/store`, `/api/retrieve`, `/api/health`, `/api/check/:pin`
+- Encryption/decryption functions using `crypto.createCipheriv/createDecipheriv`
+- PIN generation: `generatePIN()` - creates 6-digit random PIN
+- Note: Uses custom middleware for SRI injection and CSP nonces
+
+**`middleware/sri-injector.js`**:
+- Injects Subresource Integrity (SRI) hashes into HTML responses
+- Automatically adds `integrity="sha384-..."` to `<script>` and `<link>` tags
+- Uses Cheerio for HTML parsing and manipulation
+- Manages file hash cache via `HashCache`
+
+**`middleware/csp-nonce.js`**:
+- Generates unique nonce per request for Content Security Policy
+- Implements strict CSP: blocks inline scripts/styles without nonce, blocks all frames, enforces HTTPS
+- Stores nonce in `res.locals.nonce` for use by SRI injector
+
+**`middleware/static-html.js`**:
+- Custom static file middleware for serving HTML with security attributes
+- Coordinates CSP nonce injection with SRI hash injection
+
+**`public/` directory**:
+- `index.html`: Feature phone interface (PIN entry + TOTP display)
+- `sync.html`: Admin interface (QR scanner + secret submission)
+- All use inline JavaScript with Web Crypto API for client-side TOTP generation
+
+### Redis Data Structure
+
+```
+Key: mfa:{pin}
+Value: JSON {
+  encrypted: string,      // AES-256-GCM encrypted secret
+  iv: string,            // Initialization vector (hex)
+  authTag: string,       // GCM auth tag (hex)
+  encryptionKey: string, // 32-byte key (hex)
+  label: string,         // Account label
+  issuer: string,        // Service issuer
+  createdAt: number      // Timestamp
+}
+TTL: 120 seconds (configurable via PIN_TTL)
+
+Key: mfa:{pin}:retrieved
+Value: "true" | "false"
+TTL: Matches main key TTL
+```
+
+### Environment Variables
+
+Required/important configuration:
+- `PORT` (default: 3000) - Server port
+- `REDIS_URL` (default: `redis://localhost:6379`) - Redis connection string
+- `ALLOWED_ORIGINS` (default: `*`) - CORS origins (comma-separated for multiple)
+- `PIN_TTL` (default: 120) - PIN expiration time in seconds
+- `NODE_ENV` (default: development) - Environment mode
+
+## Important Implementation Details
+
+### Encryption Implementation
+- Algorithm: AES-256-GCM (authenticated encryption)
+- Each secret gets a unique random 32-byte encryption key
+- Key is stored alongside encrypted data in Redis (not separately)
+- IV (Initialization Vector) is 16 bytes random per encryption
+- Auth tag ensures integrity and authenticity
+
+### Rate Limiting Strategy
+- Store endpoint: 10 requests per 15 minutes (prevents spam)
+- Retrieve endpoint: 20 requests per 5 minutes (allows reasonable retry attempts but prevents brute force)
+- Rate limits are IP-based via express-rate-limit
+
+### Secret Validation
+- TOTP secrets must match regex: `/^[A-Z2-7]+=*$/` (Base32 alphabet)
+- PINs must match: `/^\d{6,8}$/` (6-8 digits numeric only)
+
+### One-Time Retrieval Mechanism
+1. Check `mfa:{pin}:retrieved` flag before allowing retrieval
+2. If "true", return 410 Gone status
+3. On successful retrieval: set flag to "true" with KEEPTTL, delete main key
+4. This ensures secrets can only be retrieved once even within TTL window
+
+## Working with This Codebase
+
+### Adding New API Endpoints
+Follow the existing pattern in `server.js`:
+- Apply appropriate rate limiters
+- Validate input with regex before processing
+- Use try-catch with proper error logging
+- Return consistent JSON error format: `{ error: "message" }`
+
+### Modifying Security Policies
+- CSP directives: Edit `middleware/csp-nonce.js`
+- SRI behavior: Edit `middleware/sri-injector.js`
+- Rate limits: Edit limiters in `server.js` (lines 49-59)
+
+### Deployment Considerations
+- Always use HTTPS in production (nginx reverse proxy included in docker-compose)
+- Set restrictive `ALLOWED_ORIGINS` (never use `*` in production)
+- Monitor Redis memory usage (configured with 256MB max + LRU eviction)
+- Keep `PIN_TTL` short (5-10 minutes recommended for security)