[codex] phase5 pre-b schema and rules

docs/learnings.md

@@ -13,6 +13,12 @@ Durable rules worth keeping across sessions.
 - Idempotency hashing that runs in callable code must be async and Web Crypto-safe; a `require('node:crypto')` fallback can fail under ESM/browser bundling even when the code works in unit tests.
 - When a callable looks like an auth or App Check problem, verify the initialized functions region before chasing browser state; a region mismatch can produce misleading unauthenticated failures.
 - **Stale compiled functions binary is the first thing to check when `FirebaseError: internal` appears in E2E but unit tests pass.** The emulator runs `functions/lib/`, not `functions/src/`. If source was changed (e.g. `enforceAppCheck`) but `pnpm --filter @bantayog/functions build` was not re-run, the emulator silently enforces the old setting. Fix: rebuild before running `firebase emulators:exec`.
+- `createTestEnv()` in this repo expects Firestore, Database, and Storage emulators. If you only boot Firestore, rules tests that initialize the shared harness fail before they reach assertions.
+- When a payload schema is `strict()` and a field is truly transitional, strip that field before validation instead of widening the schema and accidentally allowing unrelated junk.
+- If a transitional field is part of the contract, model it explicitly in the schema instead of stripping it in the trigger. Stripping is only the fallback when the field is truly out-of-band.
+- Ops-facing document schemas should use ops-specific enums, not the broader public report enum, or the rules/tests will drift silently.
+- `z.string().uuid()` trips `@typescript-eslint/no-deprecated` under the current lint config. Use `z.uuid()` in shared validators.
+- Collection query tests can fail on a rule that is really written for per-document access. If the rule uses `resource.data` in a way that doesn’t support `list`, switch the test to `getDoc` or rewrite the rule intentionally.
 
 ## Firestore
 

docs/progress.md

@@ -2,6 +2,19 @@
 
 ## Current
 
+### Phase 5 PRE-B - Schema + Rules Foundation (2026-04-24)
+
+- Status: DONE locally - schema amendments, rules additions, and inbox materialization updates landed
+- Scope:
+  - shared validators: coordination, responders, users, reports, and export updates
+  - Firestore rules: field mode sessions, report notes, report messages, command channel map-key lookup, report sharing events, and shared report reads
+  - inbox trigger: `report_ops.reportType`, optional `locationGeohash`, and explicit `exactLocation` payload support derived from the inbox item
+- Verification:
+  - `pnpm --filter @bantayog/shared-validators exec vitest run src/coordination.test.ts src/responders.test.ts src/users.test.ts src/reports.test.ts` - PASS
+  - `firebase emulators:exec --only firestore,database,storage "pnpm --filter @bantayog/functions exec vitest run src/__tests__/rules/field-mode-sessions.rules.test.ts src/__tests__/rules/report-notes.rules.test.ts src/__tests__/rules/report-messages.rules.test.ts src/__tests__/rules/coordination.rules.test.ts src/__tests__/rules/report-sharing.rules.test.ts"` - PASS
+  - `firebase emulators:exec --only firestore "pnpm --filter @bantayog/functions exec vitest run src/__tests__/triggers/process-inbox-item.test.ts"` - PASS
+  - `npx turbo run lint typecheck` - PASS
+
 ### Refactor Audit 2026-04-23 — Implementation Continuation
 
 **Branch:** `refactor/audit-2026-04-23-continuation`

functions/package.json

@@ -35,11 +35,13 @@
     "file-type": "^22.0.1",
     "firebase-admin": "^13.8.0",
     "firebase-functions": "^7.2.5",
+    "ngeohash": "^0.6.3",
     "sharp": "^0.34.5",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@firebase/rules-unit-testing": "^5.0.0",
+    "@types/ngeohash": "^0.6.8",
     "@types/node": "^20.12.0",
     "firebase": "^12.0.0",
     "firebase-functions-test": "^3.3.0",

functions/src/__tests__/rules/coordination.rules.test.ts

@@ -1,5 +1,5 @@
 import { assertFails, assertSucceeds } from '@firebase/rules-unit-testing'
-import { collection, doc, getDocs, setDoc, addDoc } from 'firebase/firestore'
+import { collection, doc, getDoc, getDocs, setDoc, addDoc } from 'firebase/firestore'
 import { afterAll, beforeAll, describe, it } from 'vitest'
 import { authed, createTestEnv } from '../helpers/rules-harness.js'
 import { seedActiveAccount, staffClaims, ts } from '../helpers/seed-factories.js'
@@ -13,6 +13,11 @@ beforeAll(async () => {
     role: 'municipal_admin',
     municipalityId: 'daet',
   })
+  await seedActiveAccount(env, {
+    uid: 'other-admin',
+    role: 'municipal_admin',
+    municipalityId: 'mercedes',
+  })
 })
 
 afterAll(async () => {
@@ -134,20 +139,146 @@ describe('coordination collections rules', () => {
     })
 
     it('muni admin can read own municipality requests', async () => {
-      const unauthed = env.unauthenticatedContext().firestore()
-      await setDoc(doc(unauthed, 'agency_assistance_requests/req-1'), {
-        requestedByMunicipality: 'daet',
-        targetAgencyId: 'bfp-daet',
-        dispatchId: 'd-1',
-        requestType: 'BFP',
-        requestedAt: ts,
+      await env.withSecurityRulesDisabled(async (ctx) => {
+        await setDoc(doc(ctx.firestore(), 'agency_assistance_requests', 'req-1'), {
+          requestedByMunicipality: 'daet',
+          targetAgencyId: 'bfp-daet',
+          dispatchId: 'd-1',
+          requestType: 'BFP',
+          requestedAt: ts,
+        })
+      })
+      const db = authed(
+        env,
+        'daet-admin',
+        staffClaims({ role: 'municipal_admin', municipalityId: 'daet' }),
+      )
+      await assertSucceeds(getDoc(doc(db, 'agency_assistance_requests', 'req-1')))
+    })
+  })
+
+  describe('command_channel_threads/messages participant lookup', () => {
+    beforeAll(async () => {
+      await env.withSecurityRulesDisabled(async (ctx) => {
+        await setDoc(doc(ctx.firestore(), 'command_channel_threads', 'thread-1'), {
+          threadId: 'thread-1',
+          reportId: 'report-1',
+          threadType: 'agency_assistance',
+          subject: 'Need help',
+          participantUids: { 'daet-admin': true },
+          createdBy: 'daet-admin',
+          createdAt: ts,
+          updatedAt: ts,
+          schemaVersion: 1,
+        })
+
+        await setDoc(doc(ctx.firestore(), 'command_channel_messages', 'msg-1'), {
+          threadId: 'thread-1',
+          authorUid: 'daet-admin',
+          authorRole: 'municipal_admin',
+          body: 'hello',
+          createdAt: ts,
+          schemaVersion: 1,
+        })
       })
+    })
+
+    it('allows participant to read thread', async () => {
       const db = authed(
         env,
         'daet-admin',
         staffClaims({ role: 'municipal_admin', municipalityId: 'daet' }),
       )
-      await assertSucceeds(getDocs(collection(db, 'agency_assistance_requests')))
+      await assertSucceeds(getDoc(doc(db, 'command_channel_threads', 'thread-1')))
+    })
+
+    it('denies non-participant from reading thread', async () => {
+      const db = authed(
+        env,
+        'other-admin',
+        staffClaims({ role: 'municipal_admin', municipalityId: 'mercedes' }),
+      )
+      await assertFails(getDoc(doc(db, 'command_channel_threads', 'thread-1')))
     })
+
+    it('allows participant to read message through parent thread lookup', async () => {
+      const db = authed(
+        env,
+        'daet-admin',
+        staffClaims({ role: 'municipal_admin', municipalityId: 'daet' }),
+      )
+      await assertSucceeds(getDoc(doc(db, 'command_channel_messages', 'msg-1')))
+    })
+
+    it('denies non-participant from reading message', async () => {
+      const db = authed(
+        env,
+        'other-admin',
+        staffClaims({ role: 'municipal_admin', municipalityId: 'mercedes' }),
+      )
+      await assertFails(getDoc(doc(db, 'command_channel_messages', 'msg-1')))
+    })
+  })
+})
+
+describe('command_channel_threads/messages — participant map key lookup', () => {
+  beforeAll(async () => {
+    await env.withSecurityRulesDisabled(async (ctx) => {
+      await setDoc(doc(ctx.firestore(), 'command_channel_threads', 'thread-1'), {
+        threadId: 'thread-1',
+        reportId: 'report-1',
+        threadType: 'agency_assistance',
+        subject: 'Need help',
+        participantUids: { 'daet-admin': true },
+        createdBy: 'daet-admin',
+        createdAt: ts,
+        updatedAt: ts,
+        schemaVersion: 1,
+      })
+
+      await setDoc(doc(ctx.firestore(), 'command_channel_messages', 'msg-1'), {
+        threadId: 'thread-1',
+        message: 'hello',
+        sentBy: 'daet-admin',
+        sentAt: ts,
+        schemaVersion: 1,
+      })
+    })
+  })
+
+  it('allows participant to read thread', async () => {
+    const db = authed(
+      env,
+      'daet-admin',
+      staffClaims({ role: 'municipal_admin', municipalityId: 'daet' }),
+    )
+    await assertSucceeds(getDoc(doc(db, 'command_channel_threads', 'thread-1')))
+  })
+
+  it('denies non-participant from reading thread', async () => {
+    const db = authed(
+      env,
+      'other-admin',
+      staffClaims({ role: 'municipal_admin', municipalityId: 'mercedes' }),
+    )
+    await assertFails(getDoc(doc(db, 'command_channel_threads', 'thread-1')))
+  })
+
+  it('allows participant to read a message when parent thread participantUids contains uid', async () => {
+    const db = authed(
+      env,
+      'daet-admin',
+      staffClaims({ role: 'municipal_admin', municipalityId: 'daet' }),
+    )
+    await assertSucceeds(getDoc(doc(db, 'command_channel_messages', 'msg-1')))
+  })
+
+  it('denies non-participant from reading a message', async () => {
+    const db = authed(
+      env,
+      'other-admin',
+      staffClaims({ role: 'municipal_admin', municipalityId: 'mercedes' }),
+    )
+    await assertFails(getDoc(doc(db, 'command_channel_messages', 'msg-1')))
   })
 })

functions/src/__tests__/rules/field-mode-sessions.rules.test.ts

@@ -0,0 +1,83 @@
+import { assertFails, assertSucceeds } from '@firebase/rules-unit-testing'
+import { doc, getDoc, setDoc } from 'firebase/firestore'
+import { afterAll, beforeAll, describe, it } from 'vitest'
+import { authed, createTestEnv, unauthed } from '../helpers/rules-harness.js'
+import { seedActiveAccount, staffClaims, ts } from '../helpers/seed-factories.js'
+
+let env: Awaited<ReturnType<typeof createTestEnv>>
+
+const sessionData = {
+  uid: 'daet-admin',
+  municipalityId: 'daet',
+  enteredAt: ts,
+  expiresAt: ts + 43200000,
+  isActive: true,
+  schemaVersion: 1,
+}
+
+beforeAll(async () => {
+  env = await createTestEnv('field-mode-sessions-rules-test')
+  await seedActiveAccount(env, {
+    uid: 'daet-admin',
+    role: 'municipal_admin',
+    municipalityId: 'daet',
+  })
+  await seedActiveAccount(env, {
+    uid: 'other-admin',
+    role: 'municipal_admin',
+    municipalityId: 'mercedes',
+  })
+  await seedActiveAccount(env, { uid: 'superadmin', role: 'provincial_superadmin' })
+
+  await env.withSecurityRulesDisabled(async (ctx) => {
+    await setDoc(doc(ctx.firestore(), 'field_mode_sessions', 'daet-admin'), sessionData)
+  })
+})
+
+afterAll(async () => {
+  await env.cleanup()
+})
+
+describe('field_mode_sessions rules', () => {
+  it('allows owner to read their own session', async () => {
+    const db = authed(
+      env,
+      'daet-admin',
+      staffClaims({ role: 'municipal_admin', municipalityId: 'daet' }),
+    )
+    await assertSucceeds(getDoc(doc(db, 'field_mode_sessions', 'daet-admin')))
+  })
+
+  it('allows owner to write their own session', async () => {
+    const db = authed(
+      env,
+      'daet-admin',
+      staffClaims({ role: 'municipal_admin', municipalityId: 'daet' }),
+    )
+    await assertSucceeds(setDoc(doc(db, 'field_mode_sessions', 'daet-admin'), sessionData))
+  })
+
+  it('denies other user reading another user session', async () => {
+    const db = authed(
+      env,
+      'other-admin',
+      staffClaims({ role: 'municipal_admin', municipalityId: 'mercedes' }),
+    )
+    await assertFails(getDoc(doc(db, 'field_mode_sessions', 'daet-admin')))
+  })
+
+  it('denies unauthenticated reads', async () => {
+    const db = unauthed(env)
+    await assertFails(getDoc(doc(db, 'field_mode_sessions', 'daet-admin')))
+  })
+
+  it('denies superadmin writes to field_mode_sessions', async () => {
+    const db = authed(env, 'superadmin', staffClaims({ role: 'provincial_superadmin' }))
+    await assertFails(setDoc(doc(db, 'field_mode_sessions', 'daet-admin'), sessionData))
+  })
+
+  it('allows superadmin reads', async () => {
+    const db = authed(env, 'superadmin', staffClaims({ role: 'provincial_superadmin' }))
+    await assertSucceeds(getDoc(doc(db, 'field_mode_sessions', 'daet-admin')))
+  })
+})

functions/src/__tests__/rules/report-messages.rules.test.ts

@@ -0,0 +1,86 @@
+import { assertFails, assertSucceeds } from '@firebase/rules-unit-testing'
+import { addDoc, collection, doc, getDoc, setDoc } from 'firebase/firestore'
+import { afterAll, beforeAll, describe, it } from 'vitest'
+import { authed, createTestEnv } from '../helpers/rules-harness.js'
+import { seedActiveAccount, seedReport, staffClaims, ts } from '../helpers/seed-factories.js'
+
+let env: Awaited<ReturnType<typeof createTestEnv>>
+
+beforeAll(async () => {
+  env = await createTestEnv('report-messages-rules-test')
+  await seedActiveAccount(env, {
+    uid: 'daet-admin',
+    role: 'municipal_admin',
+    municipalityId: 'daet',
+  })
+  await seedActiveAccount(env, {
+    uid: 'bfp-admin',
+    role: 'agency_admin',
+    municipalityId: 'daet',
+    agencyId: 'bfp-daet',
+  })
+  await seedReport(env, 'report-1', {
+    municipalityId: 'daet',
+    opsOverrides: { municipalityId: 'daet', agencyIds: ['bfp-daet'] },
+  })
+  await env.withSecurityRulesDisabled(async (ctx) => {
+    await setDoc(doc(ctx.firestore(), 'reports', 'report-1', 'messages', 'msg-1'), {
+      authorUid: 'daet-admin',
+      body: 'Seed message',
+      createdAt: ts,
+      schemaVersion: 1,
+    })
+  })
+})
+
+afterAll(async () => {
+  await env.cleanup()
+})
+
+describe('reports/messages rules', () => {
+  it('allows muni admin to read a message', async () => {
+    const db = authed(
+      env,
+      'daet-admin',
+      staffClaims({ role: 'municipal_admin', municipalityId: 'daet' }),
+    )
+    await assertSucceeds(getDoc(doc(db, 'reports', 'report-1', 'messages', 'msg-1')))
+  })
+
+  it('allows agency admin to read a message when report_ops agencyIds includes their agency', async () => {
+    const db = authed(
+      env,
+      'bfp-admin',
+      staffClaims({ role: 'agency_admin', municipalityId: 'daet', agencyId: 'bfp-daet' }),
+    )
+    await assertSucceeds(getDoc(doc(db, 'reports', 'report-1', 'messages', 'msg-1')))
+  })
+
+  it('allows muni admin to write a message', async () => {
+    const db = authed(
+      env,
+      'daet-admin',
+      staffClaims({ role: 'municipal_admin', municipalityId: 'daet' }),
+    )
+    await assertSucceeds(
+      addDoc(collection(db, 'reports', 'report-1', 'messages'), {
+        authorUid: 'daet-admin',
+        body: 'En route.',
+        createdAt: ts,
+        schemaVersion: 1,
+      }),
+    )
+  })
+
+  it('denies citizen writes to messages', async () => {
+    const db = authed(env, 'citizen-1', staffClaims({ role: 'citizen' }))
+    await assertFails(
+      addDoc(collection(db, 'reports', 'report-1', 'messages'), {
+        authorUid: 'citizen-1',
+        body: 'hi',
+        createdAt: ts,
+        schemaVersion: 1,
+      }),
+    )
+  })
+})