feat(phase7): implement Phase 7 PRE-7 + 7.A — security foundation, break-glass, data incidents, provincial resources

apps/admin-desktop/src/pages/TotpEnrollmentPage.tsx

@@ -0,0 +1,75 @@
+import { useState } from 'react'
+import { getAuth, multiFactor, TotpMultiFactorGenerator } from 'firebase/auth'
+import type { TotpSecret } from 'firebase/auth'
+
+export function TotpEnrollmentPage() {
+  const auth = getAuth()
+  const [totpSecret, setTotpSecret] = useState<TotpSecret | null>(null)
+  const [verificationCode, setVerificationCode] = useState('')
+  const [enrolled, setEnrolled] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  async function handleGenerate() {
+    setError(null)
+    const user = auth.currentUser
+    if (!user) {
+      setError('You must be logged in to enroll TOTP.')
+      return
+    }
+    try {
+      const session = await multiFactor(user).getSession()
+      const secret = await TotpMultiFactorGenerator.generateSecret(session)
+      setTotpSecret(secret)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to generate secret')
+    }
+  }
+
+  async function handleEnroll() {
+    setError(null)
+    const user = auth.currentUser
+    if (!user || !totpSecret) return
+    try {
+      const assertion = TotpMultiFactorGenerator.assertionForEnrollment(
+        totpSecret,
+        verificationCode,
+      )
+      await multiFactor(user).enroll(assertion, 'Authenticator')
+      setEnrolled(true)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Enrollment failed')
+    }
+  }
+
+  if (enrolled) return <p>TOTP enrolled successfully.</p>
+
+  return (
+    <div>
+      <h1>Enroll TOTP Authenticator</h1>
+      {!totpSecret ? (
+        <button onClick={() => void handleGenerate()}>Generate Secret</button>
+      ) : (
+        <>
+          <p>
+            Secret key: <code>{totpSecret.secretKey}</code>
+          </p>
+          <p>
+            QR URI:{' '}
+            <code>
+              {totpSecret.generateQrCodeUrl('Bantayog Alert', auth.currentUser?.email ?? 'admin')}
+            </code>
+          </p>
+          <input
+            placeholder="6-digit code"
+            value={verificationCode}
+            onChange={(e) => {
+              setVerificationCode(e.target.value)
+            }}
+          />
+          <button onClick={() => void handleEnroll()}>Verify and Enroll</button>
+        </>
+      )}
+      {error && <p role="alert">{error}</p>}
+    </div>
+  )
+}

apps/admin-desktop/src/routes.tsx

@@ -1,13 +1,15 @@
 import { createBrowserRouter } from 'react-router-dom'
 import { ProtectedRoute } from '@bantayog/shared-ui'
 import { LoginPage } from './pages/LoginPage'
+import { TotpEnrollmentPage } from './pages/TotpEnrollmentPage'
 import { TriageQueuePage } from './pages/TriageQueuePage'
 import { AgencyAssistanceQueuePage } from './pages/AgencyAssistanceQueuePage'
 import { AnalyticsDashboardPage } from './pages/AnalyticsDashboardPage'
 import { RosterPage } from './pages/RosterPage'
 
 export const router = createBrowserRouter([
   { path: '/login', element: <LoginPage /> },
+  { path: '/totp-enroll', element: <TotpEnrollmentPage /> },
   {
     path: '/',
     element: (

apps/admin-desktop/src/services/callables.ts

@@ -143,4 +143,72 @@ export const callables = {
       functions,
       'bulkAvailabilityOverride',
     )(payload).then((r) => r.data),
+  initiateBreakGlass: (payload: { codeA: string; codeB: string; reason: string }) =>
+    httpsCallable<typeof payload, { sessionId: string }>(
+      functions,
+      'initiateBreakGlass',
+    )(payload).then((r) => r.data),
+  deactivateBreakGlass: () =>
+    httpsCallable<Record<string, never>>(functions, 'deactivateBreakGlass')({}).then((r) => r.data),
+  declareEmergency: (payload: {
+    hazardType: string
+    affectedMunicipalityIds: string[]
+    message: string
+  }) =>
+    httpsCallable<typeof payload, { alertId: string }>(
+      functions,
+      'declareEmergency',
+    )(payload).then((r) => r.data),
+  declareDataIncident: (payload: {
+    incidentType: string
+    severity: string
+    affectedCollections: string[]
+    affectedDataClasses: string[]
+    estimatedAffectedSubjects?: number
+    summary: string
+  }) =>
+    httpsCallable<typeof payload, { incidentId: string }>(
+      functions,
+      'declareDataIncident',
+    )(payload).then((r) => r.data),
+  recordIncidentResponseEvent: (payload: { incidentId: string; phase: string; notes?: string }) =>
+    httpsCallable<typeof payload, { eventId: string }>(
+      functions,
+      'recordIncidentResponseEvent',
+    )(payload).then((r) => r.data),
+  setRetentionExempt: (payload: {
+    collection: string
+    documentId: string
+    exempt: boolean
+    reason: string
+  }) => httpsCallable<typeof payload>(functions, 'setRetentionExempt')(payload).then((r) => r.data),
+  approveErasureRequest: (payload: {
+    erasureRequestId: string
+    approved: boolean
+    reason?: string
+  }) =>
+    httpsCallable<typeof payload>(functions, 'approveErasureRequest')(payload).then((r) => r.data),
+  toggleMutualAidVisibility: (payload: { agencyId: string; visible: boolean }) =>
+    httpsCallable<typeof payload>(
+      functions,
+      'toggleMutualAidVisibility',
+    )(payload).then((r) => r.data),
+  upsertProvincialResource: (payload: {
+    id?: string
+    name: string
+    type: string
+    quantity: number
+    unit: string
+    location: string
+    available: boolean
+  }) =>
+    httpsCallable<typeof payload, { id: string }>(
+      functions,
+      'upsertProvincialResource',
+    )(payload).then((r) => r.data),
+  archiveProvincialResource: (payload: { id: string }) =>
+    httpsCallable<typeof payload>(
+      functions,
+      'archiveProvincialResource',
+    )(payload).then((r) => r.data),
 }

docs/learnings.md

@@ -96,6 +96,16 @@
 - Capacitor void-return callbacks need braces: `return () => { clearInterval(id) }`.
 - When refactoring from `refCount` to `Set<subscribers>`, remove ALL stale `refCount` references.
 
+## Phase 7 — Provincial Superadmin
+
+- `@google-cloud/bigquery` `.table.query()` doesn't exist; use `bq.query()` directly for SQL queries.
+- BigQuery query results are untyped; extract into typed helpers with `as unknown as RowType[]` to satisfy strict ESLint rules (`no-unsafe-member-access`, `no-unsafe-argument`).
+- `@typescript-eslint/no-unnecessary-condition` flags `?.` on non-optional fields in function parameter types — use `.` when the type declares the field as required.
+- Firestore path template literals (`db.doc(\`...\`)`) trigger `no-restricted-syntax`lint; use chained`.collection().doc()` instead.
+- `@typescript-eslint/no-misused-promises` flags async onClick handlers; wrap with `() => void asyncFn()`.
+- `bcryptjs` preferred over `bcrypt` in this repo — pure JS, no native compilation.
+- `@google-cloud/logging` must be added as explicit dependency when using Cloud Logging API in triggers.
+
 ## Misc
 
 - `navigator.clipboard` in happy-dom often needs to be defined as an own property before spying.

docs/progress.md

@@ -1,6 +1,30 @@
 # Progress
 
-## Current — Phase 6 Responder App (branch: `phase6/responder-app`)
+## Current — Phase 7 Provincial Superadmin + NDRRMC + Break-Glass
+
+### PRE-7 — Audit & Auth Foundation (branch: `feature/phase7-pre`)
+
+| Task                                    | Status  | Notes                                                                                             |
+| --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
+| 1. Schema additions (shared-validators) | ✅ DONE | `dataIncidentDocSchema`, extended `breakglassEventDocSchema` + `agencyDocSchema`. 229 tests pass. |
+| 2. `requireMfaAuth()` + tests           | ✅ DONE | 6 test cases including edge cases (null auth, missing firebase, non-string factor). 14/14 pass.   |
+| 3. `audit-stream.ts` service            | ✅ DONE | Fire-and-forget BigQuery streaming. `@google-cloud/bigquery@^7.9.2` added.                        |
+| 4. Audit export batch + health check    | ✅ DONE | 5min batch, 10min health check with FCM alert. `@google-cloud/logging` added.                     |
+| 5. Analytics snapshot extension         | ✅ DONE | `resolvedToday` + `avgResponseTimeMinutes` on province summary. 7/7 tests.                        |
+| 6. Bare-bones TOTP enrollment page      | ✅ DONE | `/totp-enroll` route, unprotected. Firebase v12 TOTP MFA.                                         |
+| 7. Seed break-glass config script       | ✅ DONE | `bcryptjs`, idempotent, `system_config/break_glass_config`.                                       |
+
+**Staging gate:** Pending — needs 24h soak before 7.A can deploy.
+
+### 7.A — Security Callables (branch: `feature/phase7-a`) — IN PROGRESS
+
+### 7.B — Superadmin UI (branch: `feature/phase7-b`) — BLOCKED by 7.A
+
+### 7.C — Drill & Verification — BLOCKED by 7.B
+
+---
+
+## Phase 6 — Responder App (branch: `phase6/responder-app`) — COMPLETE
 
 | Task                                             | Status  | Notes                                                                                                                                                                          |
 | ------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

functions/package.json

@@ -29,6 +29,8 @@
   },
   "dependencies": {
     "@bantayog/shared-data": "workspace:*",
+    "@google-cloud/bigquery": "^7.9.2",
+    "@google-cloud/logging": "^7.0.0",
     "@bantayog/shared-sms-parser": "workspace:*",
     "@bantayog/shared-types": "workspace:*",
     "@bantayog/shared-validators": "workspace:*",
@@ -41,10 +43,12 @@
     "geojson": "^0.5.0",
     "ngeohash": "^0.6.3",
     "sharp": "^0.34.5",
+    "bcryptjs": "^2.4.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@firebase/rules-unit-testing": "^5.0.0",
+    "@types/bcryptjs": "^2.4.6",
     "@types/ngeohash": "^0.6.8",
     "@types/node": "^20.12.0",
     "firebase": "^12.0.0",