feat(security): production hardening for external deployment

Container (Dockerfile): - Multi-stage build (deps + runtime) for minimal attack surface - Upgrade base image from node:18-alpine to node:22-alpine - Run as non-root 'node' user (UID 1000); source files owned by root - /app/data directory owned by node for SQLite + logs - Docker HEALTHCHECK: wget /health every 30s docker-compose.yaml: - Port bound to 127.0.0.1 only (expose via reverse proxy) - read_only: true filesystem; /tmp tmpfs for Node.js - no-new-privileges:true, cap_drop: ALL - Named volume sofarr-data for persistent data - TRUST_PROXY, COOKIE_SECRET, NODE_ENV added Helmet v7 + CSP nonce: - Upgrade helmet@4 → helmet@7, express-rate-limit@6 → @7 - CSP with per-request nonce injected into index.html script/link tags (replaces blanket unsafe-inline; nonce changes every request) - HSTS: max-age=1yr, includeSubDomains, preload - Referrer-Policy: strict-origin-when-cross-origin - Permissions-Policy: camera/mic/geolocation/payment/usb all off - index.html served dynamically with nonce injection; static assets served normally via express.static({index:false}) Trust proxy: - TRUST_PROXY env var configures app.set('trust proxy') so rate limiting and secure cookies work correctly behind Nginx/Caddy Session & auth: - Token store migrated from in-memory Map to SQLite via better-sqlite3 (server/utils/tokenStore.js): survives restarts, WAL mode, 31-day TTL - CSRF double-submit cookie pattern (server/middleware/verifyCsrf.js): POST/PUT/PATCH/DELETE on /api/* require X-CSRF-Token header matching the csrf_token cookie; timing-safe comparison - CSRF token issued on login + GET /api/auth/csrf; cleared on logout - Login input validation: username/password length + type checked before hitting Emby - skipSuccessfulRequests:true on login rate limiter (only count failures) - express.json({ limit: '64kb' }) to reject oversized payloads Rate limiting: - General API limiter: 300 req/15min per IP on all /api/* routes - Login limiter unchanged (10 failures/15min) but now only counts fails Logging: - Log file moved from /app/server.log to DATA_DIR/server.log (writable by non-root node user in container) - Size-based rotation: rotate at 10 MB, keep 3 files (server.log.1-3) - DATA_DIR defaults to ./data locally, /app/data in container Error handling: - Global Express error handler: catches unhandled errors, logs message, returns generic 500 (no stack traces to clients) Health/readiness: - GET /health: returns {status:'ok', uptime:N} — used by HEALTHCHECK - GET /ready: returns 503 if EMBY_URL not configured Error sanitization (sanitizeError.js): - Added patterns for password= params, bearer tokens, Basic auth in URLs Supply chain: - Remove unused cors dependency - add better-sqlite3@^9 - CI: upgrade to Node 22, raise audit level to --audit-level=high - .gitignore: add data/, *.db, *.db-wal, *.db-shm Docs: - SECURITY.md: threat model, hardening checklist, proxy examples, header table, rate limit table, Docker secrets guidance - .env.example + .env.sample: TRUST_PROXY, DATA_DIR documented
2026-05-17 06:47:25 +01:00
parent 6b8c215497
commit bdbbcabfbc
15 changed files with 1300 additions and 134 deletions
--- a/server/index.js
+++ b/server/index.js
@@ -2,6 +2,8 @@ const express = require('express');
 const path = require('path');
 const cookieParser = require('cookie-parser');
 const helmet = require('helmet');
+const rateLimit = require('express-rate-limit');
+const crypto = require('crypto');
 const fs = require('fs');
 require('dotenv').config();

@@ -10,7 +12,29 @@ require('dotenv').config();
 const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
 const currentLevel = LOG_LEVELS[(process.env.LOG_LEVEL || 'info').toLowerCase()] || 1;

-const logFile = fs.createWriteStream(path.join(__dirname, '../server.log'), { flags: 'a' });
+// Log file lives in DATA_DIR so the non-root container user can write to it
+const DATA_DIR = process.env.DATA_DIR || path.join(__dirname, '../data');
+if (!fs.existsSync(DATA_DIR)) fs.mkdirSync(DATA_DIR, { recursive: true });
+
+const LOG_PATH = path.join(DATA_DIR, 'server.log');
+const LOG_MAX_BYTES = 10 * 1024 * 1024; // 10 MB per file
+const LOG_KEEP = 3;                      // keep 3 rotated files
+
+function rotateLogIfNeeded() {
+  try {
+    const stat = fs.statSync(LOG_PATH);
+    if (stat.size < LOG_MAX_BYTES) return;
+    for (let i = LOG_KEEP - 1; i >= 1; i--) {
+      const src = `${LOG_PATH}.${i}`;
+      const dst = `${LOG_PATH}.${i + 1}`;
+      if (fs.existsSync(src)) fs.renameSync(src, dst);
+    }
+    fs.renameSync(LOG_PATH, `${LOG_PATH}.1`);
+  } catch { /* ignore rotation errors — don't crash the server */ }
+}
+
+rotateLogIfNeeded();
+const logFile = fs.createWriteStream(LOG_PATH, { flags: 'a' });
 const originalConsoleLog = console.log;
 const originalConsoleError = console.error;
 const originalConsoleWarn = console.warn;
@@ -54,35 +78,173 @@ const radarrRoutes = require('./routes/radarr');
 const embyRoutes = require('./routes/emby');
 const dashboardRoutes = require('./routes/dashboard');
 const authRoutes = require('./routes/auth');
+const verifyCsrf = require('./middleware/verifyCsrf');
 const { startPoller, POLL_INTERVAL, POLLING_ENABLED } = require('./utils/poller');

+// ---------------------------------------------------------------------------
+// Startup environment validation
+// ---------------------------------------------------------------------------
+const cookieSecret = process.env.COOKIE_SECRET;
+if (!cookieSecret && process.env.NODE_ENV === 'production') {
+  console.error('[Security] COOKIE_SECRET is not set in production — aborting.');
+  process.exit(1);
+} else if (!cookieSecret) {
+  console.warn('[Security] COOKIE_SECRET not set — unsigned cookies (dev only)');
+}
+if (!process.env.EMBY_URL && process.env.NODE_ENV === 'production') {
+  console.error('[Config] EMBY_URL is required');
+  process.exit(1);
+}
+
 const app = express();
 const PORT = process.env.PORT || 3001;

-app.use(helmet({
-  contentSecurityPolicy: false // SPA uses inline scripts; CSP requires a nonce/hash strategy
-}));
-
-const cookieSecret = process.env.COOKIE_SECRET;
-if (!cookieSecret && process.env.NODE_ENV === 'production') {
-  console.error('[Security] COOKIE_SECRET is not set in production — cookies are unsigned and can be tampered with!');
-  process.exit(1);
-} else if (!cookieSecret) {
-  console.warn('[Security] COOKIE_SECRET is not set — using unsigned cookies (acceptable for development only)');
+// ---------------------------------------------------------------------------
+// Trust proxy — required when behind Nginx/Caddy/Traefik so that
+// req.ip reflects the real client IP (not 127.0.0.1) and
+// req.secure is true when the upstream TLS is terminated by the proxy.
+// Set TRUST_PROXY=1 (or a specific IP/CIDR) via env.
+// ---------------------------------------------------------------------------
+if (process.env.TRUST_PROXY) {
+  const trustValue = /^\d+$/.test(process.env.TRUST_PROXY)
+    ? parseInt(process.env.TRUST_PROXY, 10)
+    : process.env.TRUST_PROXY;
+  app.set('trust proxy', trustValue);
 }
-app.use(cookieParser(cookieSecret || undefined));
-app.use(express.json());
-app.use(express.static(path.join(__dirname, '../public')));

+// ---------------------------------------------------------------------------
+// Helmet v7 — security response headers
+// CSP uses a per-request nonce injected into index.html so inline scripts
+// and styles are allowed only with a valid nonce, not blanket unsafe-inline.
+// ---------------------------------------------------------------------------
+app.use((req, res, next) => {
+  // Generate a fresh nonce for every request
+  res.locals.cspNonce = crypto.randomBytes(16).toString('base64');
+  next();
+});
+
+app.use((req, res, next) => {
+  helmet({
+    contentSecurityPolicy: {
+      directives: {
+        defaultSrc: ["'self'"],
+        scriptSrc: ["'self'", (req, res) => `'nonce-${res.locals.cspNonce}'`],
+        styleSrc: ["'self'", (req, res) => `'nonce-${res.locals.cspNonce}'`],
+        imgSrc: ["'self'", 'data:', 'blob:'],
+        fontSrc: ["'self'", 'data:'],
+        connectSrc: ["'self'"],
+        objectSrc: ["'none'"],
+        baseUri: ["'self'"],
+        frameAncestors: ["'none'"],
+        formAction: ["'self'"],
+        upgradeInsecureRequests: process.env.NODE_ENV === 'production' ? [] : null
+      }
+    },
+    hsts: {
+      maxAge: 31536000,       // 1 year
+      includeSubDomains: true,
+      preload: true
+    },
+    referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
+    crossOriginEmbedderPolicy: false // not needed for this SPA
+  })(req, res, next);
+});
+
+// Permissions-Policy — disable powerful browser features not needed by the app
+app.use((req, res, next) => {
+  res.setHeader(
+    'Permissions-Policy',
+    'camera=(), microphone=(), geolocation=(), payment=(), usb=()'
+  );
+  next();
+});
+
+// ---------------------------------------------------------------------------
+// General API rate limiter — applies to all /api/* routes
+// More specific limiters (e.g. login) apply on top of this.
+// ---------------------------------------------------------------------------
+const apiLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,   // 15 minutes
+  max: 300,                    // 300 requests per IP per window (generous for polling)
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: 'Too many requests, please try again later' }
+});
+
+// ---------------------------------------------------------------------------
+// Body parsing & cookies
+// ---------------------------------------------------------------------------
+app.use(cookieParser(cookieSecret || undefined));
+app.use(express.json({ limit: '64kb' })); // prevent oversized JSON payloads
+
+// ---------------------------------------------------------------------------
+// Health / readiness endpoints (no auth, no rate-limit)
+// Used by Docker HEALTHCHECK and orchestrators.
+// ---------------------------------------------------------------------------
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok', uptime: process.uptime() });
+});
+
+app.get('/ready', (req, res) => {
+  // Confirm critical config is present
+  const ready = !!(process.env.EMBY_URL);
+  if (ready) {
+    res.json({ status: 'ready' });
+  } else {
+    res.status(503).json({ status: 'not ready', reason: 'EMBY_URL not configured' });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Static files — served before API routes
+// index.html is served manually so we can inject the CSP nonce
+// ---------------------------------------------------------------------------
+const PUBLIC_DIR = path.join(__dirname, '../public');
+const INDEX_HTML = path.join(PUBLIC_DIR, 'index.html');
+
+// Serve all static assets (js, css, images, icons) except index.html
+app.use(express.static(PUBLIC_DIR, { index: false }));
+
+// Serve index.html with nonce injected into the <script> and <link> tags
+function serveIndex(req, res) {
+  fs.readFile(INDEX_HTML, 'utf8', (err, html) => {
+    if (err) return res.status(500).send('Internal Server Error');
+    const nonce = res.locals.cspNonce;
+    // Inject nonce into <script> and <link rel="stylesheet"> tags
+    const patched = html
+      .replace(/<script([^>]*)>/gi, `<script nonce="${nonce}"$1>`)
+      .replace(/<link([^>]*rel=["']stylesheet["'][^>]*)>/gi, `<link nonce="${nonce}"$1>`);
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.send(patched);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// API routes (rate-limited; auth routes exempt CSRF for login/csrf endpoints)
+// CSRF protection applies to all state-changing /api/* requests except
+// /api/auth/login (pre-auth) and /api/auth/csrf (issues the token).
+// ---------------------------------------------------------------------------
+app.use('/api', apiLimiter);
+app.use('/api/auth', authRoutes);
+
+// All routes below this point require CSRF validation on mutating methods
+app.use('/api', verifyCsrf);
 app.use('/api/sabnzbd', sabnzbdRoutes);
 app.use('/api/sonarr', sonarrRoutes);
 app.use('/api/radarr', radarrRoutes);
 app.use('/api/emby', embyRoutes);
 app.use('/api/dashboard', dashboardRoutes);
-app.use('/api/auth', authRoutes);

-app.get('/', (req, res) => {
-  res.sendFile(path.join(__dirname, '../public/index.html'));
+// SPA catch-all — serve index.html for any unmatched path
+app.get('*', serveIndex);
+
+// ---------------------------------------------------------------------------
+// Global error handler — never leak stack traces to clients
+// ---------------------------------------------------------------------------
+// eslint-disable-next-line no-unused-vars
+app.use((err, req, res, next) => {
+  console.error('[Server] Unhandled error:', err.message);
+  res.status(500).json({ error: 'Internal server error' });
 });

 app.listen(PORT, () => {
@@ -91,6 +253,7 @@ app.listen(PORT, () => {
  console.log(`  Server running on port ${PORT}`);
  console.log(`  Log level: ${process.env.LOG_LEVEL || 'info'}`);
  console.log(`  Polling: ${POLLING_ENABLED ? POLL_INTERVAL + 'ms' : 'disabled (on-demand)'}`);
+  console.log(`  Trust proxy: ${process.env.TRUST_PROXY || 'disabled'}`);
  console.log(`=================================`);
  startPoller();
 });
--- a/server/middleware/verifyCsrf.js
+++ b/server/middleware/verifyCsrf.js
@@ -0,0 +1,42 @@
+/**
+ * CSRF protection using the double-submit cookie pattern.
+ *
+ * On login the server issues a random `csrf_token` cookie (httpOnly:false
+ * so JS can read it). The SPA must send the same value in the
+ * `X-CSRF-Token` request header for every state-changing request (POST,
+ * PUT, PATCH, DELETE).
+ *
+ * Because the `sameSite: strict` session cookie already provides strong
+ * protection in modern browsers, this acts as defence-in-depth for
+ * older browsers and any edge cases.
+ *
+ * Safe methods (GET, HEAD, OPTIONS) are exempted.
+ */
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+function verifyCsrf(req, res, next) {
+  if (SAFE_METHODS.has(req.method)) return next();
+
+  const cookieToken = req.cookies.csrf_token;
+  const headerToken = req.headers['x-csrf-token'];
+
+  if (!cookieToken || !headerToken) {
+    return res.status(403).json({ error: 'CSRF token missing' });
+  }
+
+  // Constant-time comparison to prevent timing attacks
+  if (cookieToken.length !== headerToken.length) {
+    return res.status(403).json({ error: 'CSRF token invalid' });
+  }
+
+  const a = Buffer.from(cookieToken);
+  const b = Buffer.from(headerToken);
+  if (!require('crypto').timingSafeEqual(a, b)) {
+    return res.status(403).json({ error: 'CSRF token invalid' });
+  }
+
+  next();
+}
+
+module.exports = verifyCsrf;
--- a/server/routes/auth.js
+++ b/server/routes/auth.js
@@ -4,30 +4,19 @@ const crypto = require('crypto');
 const rateLimit = require('express-rate-limit');
 const router = express.Router();

+// Persistent SQLite-backed token store — survives restarts
+const { storeToken, getToken, clearToken } = require('../utils/tokenStore');
+
 const EMBY_URL = process.env.EMBY_URL;

-// Server-side token store: userId -> { accessToken }
-// Keeps AccessToken off the client; required for logout revocation.
-const tokenStore = new Map();
-
-function storeToken(userId, accessToken) {
-  tokenStore.set(userId, { accessToken });
-}
-
-function getToken(userId) {
-  return tokenStore.get(userId) || null;
-}
-
-function clearToken(userId) {
-  tokenStore.delete(userId);
-}
-

+// Strict login limiter: 10 attempts per 15 min, then locked for the window
 const loginLimiter = rateLimit({
-  windowMs: 15 * 60 * 1000, // 15 minutes
+  windowMs: 15 * 60 * 1000,
  max: 10,
  standardHeaders: true,
  legacyHeaders: false,
+  skipSuccessfulRequests: true, // only count failures toward the limit
  message: { success: false, error: 'Too many login attempts, please try again later' }
 });

@@ -35,15 +24,23 @@ const loginLimiter = rateLimit({
 router.post('/login', loginLimiter, async (req, res) => {
  try {
    const { username, password, rememberMe } = req.body;
+
+    // Input validation — reject obviously invalid inputs before hitting Emby
+    if (typeof username !== 'string' || username.trim().length === 0 || username.length > 128) {
+      return res.status(400).json({ success: false, error: 'Invalid username' });
+    }
+    if (typeof password !== 'string' || password.length === 0 || password.length > 256) {
+      return res.status(400).json({ success: false, error: 'Invalid password' });
+    }
    
-    console.log(`[Auth] Attempting login for user: ${username}`);
+    console.log(`[Auth] Attempting login for user: ${username.trim()}`);
    
    // Authenticate with Emby using a stable DeviceId derived from the username.
    // Using a deterministic DeviceId causes Emby to reuse the existing session
    // for this device rather than creating a new one on each login.
-    const stableDeviceId = 'sofarr-' + crypto.createHash('sha256').update(username.toLowerCase()).digest('hex').slice(0, 16);
+    const stableDeviceId = 'sofarr-' + crypto.createHash('sha256').update(username.trim().toLowerCase()).digest('hex').slice(0, 16);
    const authResponse = await axios.post(`${EMBY_URL}/Users/authenticatebyname`, {
-      Username: username,
+      Username: username.trim(),
      Pw: password
    }, {
      headers: {
@@ -70,22 +67,36 @@ router.post('/login', loginLimiter, async (req, res) => {
    // Set authentication cookie (signed when COOKIE_SECRET is set).
    // rememberMe=true  → persistent cookie, expires in 30 days
    // rememberMe=false → session cookie, expires when browser closes
+    // secure is always true — the app should sit behind HTTPS in production;
+    // behind a reverse proxy set TRUST_PROXY=1 so req.secure works correctly.
    const cookiePayload = JSON.stringify({ id: user.Id, name: user.Name, isAdmin });
    const signed = !!process.env.COOKIE_SECRET;
    const cookieOptions = {
      httpOnly: true,
      secure: process.env.NODE_ENV === 'production',
      sameSite: 'strict',
-      signed
+      signed,
+      path: '/'
    };
    if (rememberMe) {
      cookieOptions.maxAge = 30 * 24 * 60 * 60 * 1000; // 30 days
    }
    res.cookie('emby_user', cookiePayload, cookieOptions);
+
+    // Issue a CSRF token tied to this session so state-changing endpoints
+    // can validate the double-submit cookie pattern
+    const csrfToken = crypto.randomBytes(32).toString('hex');
+    res.cookie('csrf_token', csrfToken, {
+      httpOnly: false, // intentionally readable by JS for the double-submit pattern
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'strict',
+      path: '/'
+    });
    
    res.json({
      success: true,
-      user: { id: user.Id, name: user.Name, isAdmin }
+      user: { id: user.Id, name: user.Name, isAdmin },
+      csrfToken
    });
  } catch (error) {
    console.error(`[Auth] Login failed:`, error.message);
@@ -122,6 +133,19 @@ router.get('/me', (req, res) => {
  });
 });

+// CSRF token refresh — lets the SPA get a new token without re-logging-in
+// (e.g. after a page reload where the JS variable was lost)
+router.get('/csrf', (req, res) => {
+  const csrfToken = crypto.randomBytes(32).toString('hex');
+  res.cookie('csrf_token', csrfToken, {
+    httpOnly: false,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'strict',
+    path: '/'
+  });
+  res.json({ csrfToken });
+});
+
 // Logout
 router.post('/logout', async (req, res) => {
  const user = parseSessionCookie(req);
@@ -143,7 +167,14 @@ router.post('/logout', async (req, res) => {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict',
-    signed: !!process.env.COOKIE_SECRET
+    signed: !!process.env.COOKIE_SECRET,
+    path: '/'
+  });
+  res.clearCookie('csrf_token', {
+    httpOnly: false,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'strict',
+    path: '/'
  });
  res.json({ success: true });
 });
--- a/server/utils/sanitizeError.js
+++ b/server/utils/sanitizeError.js
@@ -1,14 +1,19 @@
-const API_KEY_PATTERN = /([?&]apikey=)[^&\s]*/gi;
-const TOKEN_PATTERN = /([?&]token=)[^&\s]*/gi;
-const HEADER_PATTERN = /x-(?:api-key|mediabrowser-token|emby-authorization):[^\s,]*/gi;
+// Query-param secrets (SABnzbd apikey, generic token/password params)
+const QUERY_SECRET_PATTERN = /([?&](?:apikey|token|password|api_key|key|secret)=)[^&\s#]*/gi;
+// HTTP auth header values (X-Api-Key, X-MediaBrowser-Token, Authorization, X-Emby-Authorization)
+const HEADER_PATTERN = /(?:x-api-key|x-mediabrowser-token|x-emby-authorization|authorization)\s*:\s*\S+/gi;
+// Bearer tokens
+const BEARER_PATTERN = /bearer\s+[A-Za-z0-9\-._~+/]+=*/gi;
+// Basic auth credentials in URLs (http://user:pass@host)
+const BASIC_AUTH_URL_PATTERN = /\/\/[^:@/\s]+:[^@/\s]+@/gi;

 function sanitizeError(err) {
-  let msg = err.message || String(err);
-  // Redact API keys in URLs (SABnzbd passes apikey as query param)
-  msg = msg.replace(API_KEY_PATTERN, '$1[REDACTED]');
-  msg = msg.replace(TOKEN_PATTERN, '$1[REDACTED]');
-  // Redact auth header values if they appear in the message
-  msg = msg.replace(HEADER_PATTERN, (m) => m.split(':')[0] + ':[REDACTED]');
+  let msg = (err && err.message) ? err.message : String(err);
+  msg = msg.replace(QUERY_SECRET_PATTERN, '$1[REDACTED]');
+  msg = msg.replace(HEADER_PATTERN, (m) => m.split(/[\s:]/)[0] + ':[REDACTED]');
+  msg = msg.replace(BEARER_PATTERN, 'bearer [REDACTED]');
+  msg = msg.replace(BASIC_AUTH_URL_PATTERN, '//[REDACTED]@');
+  // Never leak stack traces to API responses
  return msg;
 }

--- a/server/utils/tokenStore.js
+++ b/server/utils/tokenStore.js
@@ -0,0 +1,83 @@
+/**
+ * Persistent token store backed by SQLite (better-sqlite3).
+ *
+ * Survives process restarts — Emby tokens remain valid across deploys
+ * and container restarts, so users do not need to re-login after an
+ * update. Tokens are stored in DATA_DIR/tokens.db (default: /app/data
+ * inside the container, or ./data locally).
+ *
+ * Schema: tokens(userId TEXT PK, accessToken TEXT, createdAt INTEGER)
+ *
+ * Expired rows (older than TOKEN_TTL_DAYS) are pruned on startup and
+ * once per hour, preventing unbounded growth.
+ */
+
+const Database = require('better-sqlite3');
+const path = require('path');
+const fs = require('fs');
+
+const TOKEN_TTL_DAYS = 31; // slightly longer than max cookie lifetime
+const DATA_DIR = process.env.DATA_DIR || path.join(__dirname, '../../data');
+
+// Ensure data directory exists (non-root writable in container)
+if (!fs.existsSync(DATA_DIR)) {
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+}
+
+const DB_PATH = path.join(DATA_DIR, 'tokens.db');
+const db = new Database(DB_PATH);
+
+// WAL mode for better concurrent read performance
+db.pragma('journal_mode = WAL');
+db.pragma('foreign_keys = ON');
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS tokens (
+    userId      TEXT PRIMARY KEY,
+    accessToken TEXT NOT NULL,
+    createdAt   INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+  )
+`);
+
+const storeToken = db.prepare(
+  `INSERT OR REPLACE INTO tokens (userId, accessToken, createdAt)
+   VALUES (?, ?, strftime('%s','now'))`
+);
+
+const getTokenStmt = db.prepare(
+  `SELECT accessToken FROM tokens WHERE userId = ?`
+);
+
+const clearTokenStmt = db.prepare(
+  `DELETE FROM tokens WHERE userId = ?`
+);
+
+const pruneStmt = db.prepare(
+  `DELETE FROM tokens WHERE createdAt < strftime('%s','now') - ?`
+);
+
+const TTL_SECONDS = TOKEN_TTL_DAYS * 24 * 60 * 60;
+
+function prune() {
+  const result = pruneStmt.run(TTL_SECONDS);
+  if (result.changes > 0) {
+    console.log(`[TokenStore] Pruned ${result.changes} expired token(s)`);
+  }
+}
+
+// Prune on startup and every hour
+prune();
+setInterval(prune, 60 * 60 * 1000).unref();
+
+module.exports = {
+  storeToken(userId, accessToken) {
+    storeToken.run(userId, accessToken);
+  },
+  getToken(userId) {
+    const row = getTokenStmt.get(userId);
+    return row ? { accessToken: row.accessToken } : null;
+  },
+  clearToken(userId) {
+    clearTokenStmt.run(userId);
+  }
+};