Apexone11
diff --git a/‎backend/.env.example‎
Lines changed: 24 additions & 0 deletions b/‎backend/.env.example‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎backend/prisma/migrations/20260527000001_webauthn_last_used_at/migration.sql‎
Lines changed: 16 additions & 0 deletions b/‎backend/prisma/migrations/20260527000001_webauthn_last_used_at/migration.sql‎
Lines changed: 16 additions & 0 deletions
diff --git a/‎backend/prisma/migrations/20260527000002_session_mfa_verified_at/migration.sql‎
Lines changed: 18 additions & 0 deletions b/‎backend/prisma/migrations/20260527000002_session_mfa_verified_at/migration.sql‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎backend/prisma/migrations/20260527000003_data_battery_saver_modes/migration.sql‎
Lines changed: 15 additions & 0 deletions b/‎backend/prisma/migrations/20260527000003_data_battery_saver_modes/migration.sql‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎backend/prisma/schema.prisma‎
Lines changed: 19 additions & 7 deletions b/‎backend/prisma/schema.prisma‎
Lines changed: 19 additions & 7 deletions
diff --git a/‎backend/scripts/restoreVolumeFromR2.js‎
Lines changed: 150 additions & 0 deletions b/‎backend/scripts/restoreVolumeFromR2.js‎
Lines changed: 150 additions & 0 deletions
diff --git a/‎backend/src/index.js‎
Lines changed: 9 additions & 0 deletions b/‎backend/src/index.js‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎backend/src/lib/dataSaverNegotiation.js‎
Lines changed: 78 additions & 0 deletions b/‎backend/src/lib/dataSaverNegotiation.js‎
Lines changed: 78 additions & 0 deletions
@@ -365,3 +365,27 @@ ENABLE_QUERY_LOGGING=
 # Older code paths read EMAIL_PROVIDER; new code reads EMAIL_TRANSPORT.
 # Set whichever your deployment scripts use; the other is ignored.
 EMAIL_PROVIDER=
+
+# ── ADMIN MFA SEALED-GLASS-BREAK (do NOT enable in normal operations) ──
+# When set to the literal string "true", disables admin MFA enforcement
+# at login regardless of the flag_admin_mfa_required feature flag.
+# Intended ONLY for incident response when the founder is locked out
+# (e.g. lost 2FA device). Every login that bypasses MFA via this
+# override emits the structured log event
+# `auth.admin_mfa_emergency_disabled` which is captured by Sentry.
+# Unset as soon as the incident is resolved.
+EMERGENCY_DISABLE_ADMIN_MFA=
+
+# ── UPLOAD VOLUME BACKUP (R2 mirror, wave-12.11) ──────────────────
+# Daily job that mirrors /data/uploads (avatars, covers, attachments,
+# group-media, etc.) to a dedicated R2 bucket. REQUIRED IN PRODUCTION —
+# without it the Railway volume is a single point of failure and the
+# backup job silently no-ops, meaning every user-uploaded photo is
+# permanently lost if the disk corrupts or the instance is rebuilt.
+# Boot fails fast in NODE_ENV=production if this is unset.
+# Recovery procedure: scripts/restoreVolumeFromR2.js. Documented in
+# docs/internal/security/RUNBOOK_DB_RESTORE.md "Upload Volume Recovery".
+R2_BUCKET_UPLOAD_BACKUP=
+# Optional overrides — defaults to 24h cadence + 10 uploads/sec.
+UPLOAD_BACKUP_INTERVAL_MS=
+UPLOAD_BACKUP_RATE_LIMIT_PER_SEC=
@@ -0,0 +1,16 @@
+-- Wave-12.11 — WebAuthnCredential.lastUsedAt
+--
+-- Adds a nullable timestamp column to WebAuthnCredential so the admin
+-- portal can show "last used" per passkey, and so we have an audit
+-- signal for unused passkeys that should be retired. Written every
+-- time the credential verifies successfully in webauthn.routes.js.
+--
+-- Originally part of the L2.14 deferred plan for admin MFA. Implemented
+-- standalone in wave-12.11 because the column is useful on its own (no
+-- behavioural change to the verify path beyond the additional write).
+--
+-- Idempotency: ADD COLUMN IF NOT EXISTS so re-running the migration
+-- after a partial deploy is safe (CLAUDE.md A5).
+
+ALTER TABLE "WebAuthnCredential"
+  ADD COLUMN IF NOT EXISTS "lastUsedAt" TIMESTAMP(3);
@@ -0,0 +1,18 @@
+-- Wave-12.11 — Session.mfaVerifiedAt
+--
+-- Adds a nullable timestamp column to Session. Set when the user
+-- completes the email-OTP challenge (loginChallenge.consume) OR
+-- redeems a recovery code OR hits POST /api/auth/mfa/step-up.
+-- requireRecentMfa middleware compares this to NOW() and 403s if the
+-- gap exceeds the per-route window (default 15 min).
+--
+-- Closes the L2.14 deferred admin-MFA step-up plan. The column is
+-- nullable so existing sessions don't need to be re-issued — the
+-- middleware treats NULL as "never verified" which 403s on the
+-- protected route, sending the admin through the step-up flow.
+--
+-- Idempotency: ADD COLUMN IF NOT EXISTS so re-running the migration
+-- after a partial deploy is safe (CLAUDE.md A5).
+
+ALTER TABLE "Session"
+  ADD COLUMN IF NOT EXISTS "mfaVerifiedAt" TIMESTAMP(3);
@@ -0,0 +1,15 @@
+-- Wave-12.11 — UserPreferences.dataSaverMode + batterySaverMode
+--
+-- One combined migration covering both founder-priority modes from
+-- docs/internal/plans/data-saver-mode.md and battery-saver-mode.md.
+-- Both use the same "on" | "off" | "auto" tri-state. `auto` means
+-- honor the platform signal:
+--   - data-saver:    Save-Data header + navigator.connection.saveData
+--   - battery-saver: prefers-reduced-motion: reduce
+--
+-- Idempotent guards per CLAUDE.md A5 — safe to re-run if a prior
+-- partial deploy already applied one of the columns.
+
+ALTER TABLE "UserPreferences"
+  ADD COLUMN IF NOT EXISTS "dataSaverMode" TEXT NOT NULL DEFAULT 'auto',
+  ADD COLUMN IF NOT EXISTS "batterySaverMode" TEXT NOT NULL DEFAULT 'auto';
@@ -967,6 +967,12 @@ model UserPreferences {
   // "All schools" inline per-picker. Default true matches the founder's
   // intent that most users see their own school first.
   scopeBySchool          Boolean @default(true)
+  // Wave-12.11 — Data Saver + Battery Saver. Both follow the same
+  // "on" / "off" / "auto" pattern. `auto` means honor the platform
+  // signal: Save-Data request header / navigator.connection.saveData
+  // for data-saver; prefers-reduced-motion: reduce for battery-saver.
+  dataSaverMode          String  @default("auto")
+  batterySaverMode       String  @default("auto")
   user                   User    @relation(fields: [userId], references: [id], onDelete: Cascade)
 }
 
@@ -1303,17 +1309,18 @@ model UserSensitive {
 
 // ── WebAuthn passkey credentials ────────────────────────────
 model WebAuthnCredential {
-  id           Int      @id @default(autoincrement())
+  id           Int       @id @default(autoincrement())
   userId       Int
-  credentialId String   @unique
+  credentialId String    @unique
   publicKey    Bytes
-  counter      Int      @default(0)
+  counter      Int       @default(0)
   deviceType   String?
-  backedUp     Boolean  @default(false)
+  backedUp     Boolean   @default(false)
   transports   String?
-  name         String   @default("Passkey")
-  createdAt    DateTime @default(now())
-  user         User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  name         String    @default("Passkey")
+  createdAt    DateTime  @default(now())
+  lastUsedAt   DateTime?
+  user         User      @relation(fields: [userId], references: [id], onDelete: Cascade)
 
@@index([userId])
 }
@@ -2671,6 +2678,11 @@ model Session {
   riskScore       Int?
   trustedDeviceId String?
   lastActiveAt    DateTime  @default(now())
+  // Timestamp of the last MFA verification on this session. Set when
+  // the user completes the email-OTP challenge, redeems a recovery
+  // code, or hits POST /api/auth/mfa/step-up. requireRecentMfa
+  // middleware enforces a max-age window against this column.
+  mfaVerifiedAt   DateTime?
   expiresAt       DateTime
   revokedAt       DateTime?
   createdAt       DateTime  @default(now())
 
@@ -0,0 +1,150 @@
+/**
+ * restoreVolumeFromR2.js — disaster-recovery for /data/uploads.
+ *
+ * Wave-12.11. Pairs with backend/src/lib/jobs/uploadVolumeBackup.js.
+ *
+ * When to run: the Railway volume is gone, corrupted, or replaced. The
+ * DB rows still point at /uploads/... paths; without restoring the
+ * files every <img> 404s. Run this on the new instance BEFORE flipping
+ * traffic back on.
+ *
+ * What it does:
+ *   1. Lists every object under the `upload-volume-backup/` prefix in
+ *      R2_BUCKET_UPLOAD_BACKUP.
+ *   2. For each one, writes the file back into UPLOADS_DIR preserving
+ *      the original relative path (`avatars/123.jpg` etc.).
+ *   3. Refuses to overwrite existing files by default. Pass --force
+ *      to overwrite (use ONLY when the volume is intentionally being
+ *      wiped + repopulated; otherwise you risk replacing live newer
+ *      content with stale backups).
+ *   4. Skips R2 listing pagination boundaries cleanly — handles the
+ *      ContinuationToken pattern S3 returns for buckets > 1000 keys.
+ *
+ * Usage:
+ *   # Inspect what would happen (no writes):
+ *   node backend/scripts/restoreVolumeFromR2.js --dry-run
+ *
+ *   # Actual restore (writes new files only, skip-if-exists):
+ *   node backend/scripts/restoreVolumeFromR2.js
+ *
+ *   # Wipe + repopulate (use after volume reformat):
+ *   node backend/scripts/restoreVolumeFromR2.js --force
+ *
+ * Required env: R2_BUCKET_UPLOAD_BACKUP + R2_ACCOUNT_ID +
+ *               R2_ACCESS_KEY_ID + R2_SECRET_ACCESS_KEY.
+ *
+ * Exit codes: 0 success, 1 missing config / R2 unavailable, 2 partial
+ * failure (some objects could not be restored — report shows which).
+ */
+const fs = require('node:fs')
+const path = require('node:path')
+const { ListObjectsV2Command, GetObjectCommand } = require('@aws-sdk/client-s3')
+
+require('dotenv').config({ path: path.resolve(__dirname, '../.env') })
+
+const { KEY_PREFIX } = require('../src/lib/jobs/uploadVolumeBackup')
+
+async function main() {
+  const args = process.argv.slice(2)
+  const dryRun = args.includes('--dry-run')
+  const force = args.includes('--force')
+
+  const bucket = process.env.R2_BUCKET_UPLOAD_BACKUP
+  if (!bucket) {
+    console.error('FATAL: R2_BUCKET_UPLOAD_BACKUP is not set.')
+    process.exit(1)
+  }
+
+  // Lazy-require the R2 client so we share the same singleton + config
+  // checks as the runtime app.
+  const { isR2Configured } = require('../src/lib/r2Storage')
+  if (!isR2Configured()) {
+    console.error('FATAL: R2 credentials are not configured.')
+    process.exit(1)
+  }
+
+  // Build a dedicated S3 client for this script rather than reaching
+  // into r2Storage internals. Same credentials, same endpoint — keeps
+  // r2Storage's getClient() private and avoids tying script lifetimes
+  // to the runtime singleton's connection pool.
+  const { S3Client } = require('@aws-sdk/client-s3')
+  const client = new S3Client({
+    region: 'auto',
+    endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
+    credentials: {
+      accessKeyId: process.env.R2_ACCESS_KEY_ID,
+      secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+    },
+  })
+
+  const { UPLOADS_DIR } = require('../src/lib/storage')
+  console.log(`Restoring from R2 bucket "${bucket}" → ${UPLOADS_DIR}`)
+  console.log(
+    `Mode: ${dryRun ? 'DRY RUN' : force ? 'FORCE (overwrite existing)' : 'SAFE (skip-if-exists)'}`,
+  )
+
+  let restored = 0
+  let skipped = 0
+  let failed = 0
+  let scanned = 0
+  let continuationToken
+
+  do {
+    const list = await client.send(
+      new ListObjectsV2Command({
+        Bucket: bucket,
+        Prefix: KEY_PREFIX,
+        ContinuationToken: continuationToken,
+      }),
+    )
+
+    for (const obj of list.Contents || []) {
+      scanned += 1
+      const relativePath = obj.Key.slice(KEY_PREFIX.length)
+      const destination = path.join(UPLOADS_DIR, relativePath)
+
+      if (fs.existsSync(destination) && !force) {
+        skipped += 1
+        continue
+      }
+      if (dryRun) {
+        console.log(`[dry-run] would restore ${obj.Key} → ${destination}`)
+        restored += 1
+        continue
+      }
+
+      try {
+        fs.mkdirSync(path.dirname(destination), { recursive: true })
+        const get = await client.send(new GetObjectCommand({ Bucket: bucket, Key: obj.Key }))
+        // The Body is a stream — collect to a buffer for the write.
+        // For multi-GB videos a streaming pipe would be better; we
+        // don't expect that volume here (avatars + small attachments).
+        const chunks = []
+        for await (const chunk of get.Body) chunks.push(chunk)
+        fs.writeFileSync(destination, Buffer.concat(chunks))
+        restored += 1
+        if (restored % 100 === 0) {
+          console.log(`Restored ${restored} files (skipped ${skipped}, failed ${failed})...`)
+        }
+      } catch (err) {
+        console.error(`FAILED ${obj.Key}: ${err?.message || err}`)
+        failed += 1
+      }
+    }
+
+    continuationToken = list.IsTruncated ? list.NextContinuationToken : undefined
+  } while (continuationToken)
+
+  console.log('')
+  console.log('=== Restore summary ===')
+  console.log(`Scanned:  ${scanned}`)
+  console.log(`Restored: ${restored}`)
+  console.log(`Skipped:  ${skipped} (already on disk; use --force to overwrite)`)
+  console.log(`Failed:   ${failed}`)
+  process.exit(failed > 0 ? 2 : 0)
+}
+
+main().catch((err) => {
+  console.error('FATAL:', err)
+  process.exit(1)
+})
@@ -894,6 +894,15 @@ async function startServer() {
       ).unref()
     }, msUntilNextFour).unref()
 
+    // Wave-12.11 — daily mirror of /data/uploads to R2 so user-
+    // uploaded photos survive a Railway volume crash. No-ops
+    // gracefully when R2_BUCKET_UPLOAD_BACKUP is unset. Recovery
+    // procedure documented in docs/internal/security/
+    // RUNBOOK_DB_RESTORE.md "Upload Volume Recovery" section.
+    const { startUploadVolumeBackup } = require('./lib/jobs/uploadVolumeBackup')
+    const { UPLOADS_DIR } = require('./lib/storage')
+    startUploadVolumeBackup({ uploadsDir: UPLOADS_DIR })
+
     log.info({ port: PORT }, `Server running on http://localhost:${PORT}`)
   })
 
 
@@ -0,0 +1,78 @@
+/**
+ * dataSaverNegotiation.js — server-side data-saver detection.
+ *
+ * Wave-12.11. Pairs with the frontend `useDataSaver` hook.
+ *
+ * Returns true when the current request should receive a lighter
+ * response (smaller image variants, no thumbnail array, no SSE
+ * streaming, etc.). Three signals, OR'd:
+ *
+ *   1. `Save-Data: on` request header (RFC 8478). Sent by Chrome on
+ *      cellular when the user has Data Saver enabled, and by some
+ *      mobile browsers on metered connections.
+ *   2. `req.user.dataSaverMode === 'on'` — the user explicitly turned
+ *      Data Saver on in Settings. Honored even if no header is set.
+ *   3. `req.user.dataSaverMode === 'auto'` AND the header is on. The
+ *      `auto` default means we follow the platform signal when the
+ *      user hasn't expressed a preference either way.
+ *
+ * Explicit `dataSaverMode === 'off'` ALWAYS wins — the user said no.
+ * This is the "I have wifi, give me the full experience" override even
+ * if their browser is sending Save-Data for unrelated reasons.
+ *
+ * The helper is a synchronous read; no DB roundtrip. Routes that want
+ * to honor data-saver should pull the user pref into req.user (or a
+ * scoped lookup) BEFORE calling this — the existing requireAuth
+ * middleware does not currently load dataSaverMode, so callers either:
+ *   a) accept "header-only" detection (anonymous requests, public
+ *      endpoints), or
+ *   b) hydrate req.user.dataSaverMode themselves.
+ *
+ * Why no middleware sets it globally yet: the per-request Prisma read
+ * cost adds up across every endpoint. Routes that benefit from
+ * data-saver opt in explicitly. Settings tab is the canonical write.
+ */
+
+/**
+ * @param {import('express').Request} req
+ * @returns {boolean}
+ */
+function isDataSaverRequest(req) {
+  const userPref = req?.user?.dataSaverMode
+
+  // Explicit "off" wins — never down-rev the response when the user
+  // said they want the full version.
+  if (userPref === 'off') return false
+
+  // Explicit "on" wins — return the lighter response regardless of
+  // header presence.
+  if (userPref === 'on') return true
+
+  // `auto` (or anonymous / unloaded pref) → honor the request header.
+  const header = String(req?.headers?.['save-data'] || '')
+    .trim()
+    .toLowerCase()
+  return header === 'on'
+}
+
+/**
+ * Frontend may also pass an explicit `?lite=1` query param when its
+ * hook detected client-side that data-saver is on (covers Safari,
+ * which doesn't send Save-Data). Honored as a third signal.
+ */
+function isLiteQueryRequest(req) {
+  return req?.query?.lite === '1' || req?.query?.lite === 'true'
+}
+
+/**
+ * Convenience: returns true if ANY of the three signals fire.
+ */
+function shouldReturnLite(req) {
+  return isDataSaverRequest(req) || isLiteQueryRequest(req)
+}
+
+module.exports = {
+  isDataSaverRequest,
+  isLiteQueryRequest,
+  shouldReturnLite,
+}