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

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

@@ -1,4 +1,4 @@
-import { useRef, useState } from 'react'
+import { useState } from 'react'
 import { detectEncoding } from '@bantayog/shared-validators'
 import { callables } from '../services/callables'
 
@@ -16,33 +16,21 @@ interface Props {
 }
 
 export function MassAlertModal({ municipalityId, onClose }: Props) {
-  const sendKeyRef = useRef<string>(crypto.randomUUID())
-  const escalateKeyRef = useRef<string>(crypto.randomUUID())
   const [message, setMessage] = useState('')
   const [reachPlan, setReachPlan] = useState<ReachPlan | null>(null)
   const [loading, setLoading] = useState(false)
   const [error, setError] = useState<string | null>(null)
-  const [pagasaSignalRef, setPagasaSignalRef] = useState('')
-  const [notes, setNotes] = useState('')
-
-  const normalizedMessage = message.trim()
-  const normalizedPagasaSignalRef = pagasaSignalRef.trim()
-  const normalizedNotes = notes.trim()
 
   const encoding = message ? detectEncoding(message).encoding : 'GSM-7'
 
   const handlePreview = () => {
-    if (!normalizedMessage) {
-      setError('Message cannot be empty')
-      return
-    }
-    setError(null)
     setLoading(true)
+    setError(null)
     void (async () => {
       try {
         const plan = await callables.massAlertReachPlanPreview({
           targetScope: { municipalityIds: [municipalityId] },
-          message: normalizedMessage,
+          message,
         })
         setReachPlan(plan)
       } catch (err: unknown) {
@@ -58,15 +46,14 @@ export function MassAlertModal({ municipalityId, onClose }: Props) {
       setError('Direct send is not available for this alert scope')
       return
     }
-    setError(null)
     setLoading(true)
     void (async () => {
       try {
         await callables.sendMassAlert({
           reachPlan,
-          message: normalizedMessage,
+          message,
           targetScope: { municipalityIds: [municipalityId] },
-          idempotencyKey: sendKeyRef.current,
+          idempotencyKey: crypto.randomUUID(),
         })
         onClose()
       } catch (err: unknown) {
@@ -78,23 +65,14 @@ export function MassAlertModal({ municipalityId, onClose }: Props) {
   }
 
   const handleEscalate = () => {
-    if (normalizedNotes.length > 2000) {
-      setError('Notes must be 2000 characters or fewer')
-      return
-    }
-    setError(null)
     setLoading(true)
     void (async () => {
       try {
         await callables.requestMassAlertEscalation({
-          message: normalizedMessage,
+          message,
           targetScope: { municipalityIds: [municipalityId] },
-          evidencePack: {
-            linkedReportIds: [],
-            ...(normalizedPagasaSignalRef ? { pagasaSignalRef: normalizedPagasaSignalRef } : {}),
-            ...(normalizedNotes ? { notes: normalizedNotes } : {}),
-          },
-          idempotencyKey: escalateKeyRef.current,
+          evidencePack: { linkedReportIds: [] },
+          idempotencyKey: crypto.randomUUID(),
         })
         onClose()
       } catch (err: unknown) {
@@ -120,8 +98,6 @@ export function MassAlertModal({ municipalityId, onClose }: Props) {
         onChange={(e) => {
           setMessage(e.target.value)
           setReachPlan(null)
-          sendKeyRef.current = crypto.randomUUID()
-          escalateKeyRef.current = crypto.randomUUID()
         }}
         rows={4}
       />
@@ -130,7 +106,7 @@ export function MassAlertModal({ municipalityId, onClose }: Props) {
         {reachPlan?.unicodeWarning && <span> ⚠ UCS-2 (multi-byte)</span>}
         {reachPlan && <> · Segments: {reachPlan.segmentCount}</>}
       </p>
-      <button onClick={handlePreview} disabled={!normalizedMessage || loading}>
+      <button onClick={handlePreview} disabled={!message || loading}>
         Preview Reach
       </button>
       {reachPlan && (
@@ -153,32 +129,9 @@ export function MassAlertModal({ municipalityId, onClose }: Props) {
         Send Alert
       </button>
       {reachPlan?.route === 'ndrrmc_escalation' && (
-        <>
-          <label htmlFor="pagasa-signal-ref">PAGASA Signal Ref (optional)</label>
-          <input
-            id="pagasa-signal-ref"
-            type="text"
-            value={pagasaSignalRef}
-            onChange={(e) => {
-              setPagasaSignalRef(e.target.value)
-              escalateKeyRef.current = crypto.randomUUID()
-            }}
-          />
-          <label htmlFor="escalation-notes">Notes (optional)</label>
-          <textarea
-            id="escalation-notes"
-            value={notes}
-            maxLength={2000}
-            onChange={(e) => {
-              setNotes(e.target.value)
-              escalateKeyRef.current = crypto.randomUUID()
-            }}
-            rows={2}
-          />
-          <button onClick={handleEscalate} disabled={loading}>
-            Request NDRRMC Escalation
-          </button>
-        </>
+        <button onClick={handleEscalate} disabled={loading}>
+          Request NDRRMC Escalation
+        </button>
       )}
       <button onClick={onClose}>Cancel</button>
     </dialog>

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                                                                                                                                                                          |
 | ------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

docs/superpowers/plans/2026-04-27-phase7.md

@@ -1116,7 +1116,6 @@ import { UserManagementPage } from './pages/UserManagementPage'
 import { ProvincialResourcesPage } from './pages/ProvincialResourcesPage'
 import { SystemHealthPage } from './pages/SystemHealthPage'
 import { BreakGlassPage } from './pages/BreakGlassPage'
-
 ;<Route path="/province" element={<ProtectedRoute allowedRoles={['provincial_superadmin']} />}>
   <Route index element={<Navigate to="/province/dashboard" replace />} />
   <Route path="dashboard" element={<ProvinceDashboardPage />} />

functions/lib/__tests__/callables/mark-dispatch-unable-to-complete.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mark-dispatch-unable-to-complete.test.d.ts.map