Design Separate Browser / Mobile and Backend Access Paths with Explicit Trust, Audit, and Failure Boundaries

[Browser / Mobile]   | Firebase Auth ID token + optional App Check   |---- direct Firestore read/write ----> [Security Rules] ---> [Firestore]   |   | HTTPS Bearer ID token   v[AtlasMart Orders API]   1. verify user token   2. application authorization (tenant/role/resource/invariant)   3. idempotency / transaction policy where needed   | ADC / attached or federated workload identity   v[IAM] ---> [Firestore][Background Worker]   | workload identity only   v[IAM] ---> [Firestore]Never: Browser ---> service-account key ---> Firestore

rules_version = '2';service cloud.firestore {  match /databases/{database}/documents {    function signedIn() { return request.auth != null; }    function tenant() { return signedIn() ? request.auth.token.tenantId : null; }    match /profiles/{uid} {      allow get: if signedIn() && request.auth.uid == uid;      allow list: if false;      allow update: if signedIn()        && request.auth.uid == uid        && request.resource.data.uid == resource.data.uid        && request.resource.data.tenantId == resource.data.tenantId        && request.resource.data.diff(resource.data).affectedKeys()             .hasOnly(["displayName", "locale"]);      allow create, delete: if false;    }    match /orders/{orderId} {      allow get: if signedIn()        && resource.data.tenantId == tenant()        && resource.data.customerId == request.auth.uid;      allow list: if signedIn()        && resource.data.tenantId == tenant()        && resource.data.customerId == request.auth.uid        && request.query.limit <= 25;      allow create: if signedIn()        && request.resource.data.tenantId == tenant()        && request.resource.data.customerId == request.auth.uid        && request.resource.data.status == "DRAFT";      allow update, delete: if false;    }    match /refundRequests/{requestId} {      // Clients can create a request; only trusted backend code changes status.      allow create: if signedIn()        && request.resource.data.requestedBy == request.auth.uid        && request.resource.data.status == "REQUESTED";      allow get: if signedIn()        && resource.data.requestedBy == request.auth.uid;      allow list, update, delete: if false;    }    match /{document=**} {      allow read, write: if false;    }  }}

import fs from "node:fs";import test, { before, after, beforeEach } from "node:test";import {  initializeTestEnvironment,  assertSucceeds,  assertFails} from "@firebase/rules-unit-testing";import { doc, getDoc, setDoc, updateDoc } from "firebase/firestore";let env;before(async () => {  env = await initializeTestEnvironment({    projectId: "demo-atlasmart-firestore",    firestore: {      host: "127.0.0.1", port: 8080,      rules: fs.readFileSync("firestore.rules", "utf8")    }  });});beforeEach(async () => {  await env.clearFirestore();  await env.withSecurityRulesDisabled(async ctx => {    const db = ctx.firestore();    await setDoc(doc(db, "profiles/u-1001"), {      uid: "u-1001", tenantId: "t-atlas", displayName: "Ava", locale: "en"    });    await setDoc(doc(db, "orders/o-9001"), {      tenantId: "t-atlas", customerId: "u-1001", status: "PAID", totalCents: 12990    });  });});after(async () => env.cleanup());test("client path is constrained by Rules", async () => {  const ava = env.authenticatedContext("u-1001", { tenantId: "t-atlas", role: "customer" }).firestore();  const other = env.authenticatedContext("u-2002", { tenantId: "t-atlas", role: "customer" }).firestore();  await assertSucceeds(getDoc(doc(ava, "orders/o-9001")));  await assertFails(getDoc(doc(other, "orders/o-9001")));  await assertFails(updateDoc(doc(ava, "orders/o-9001"), { status: "REFUNDED" }));});

// Never ship this module to a browser bundle.process.env.FIRESTORE_EMULATOR_HOST = "127.0.0.1:8080";process.env.FIREBASE_AUTH_EMULATOR_HOST = "127.0.0.1:9099";process.env.GCLOUD_PROJECT = "demo-atlasmart-firestore";import { initializeApp } from "firebase-admin/app";import { getAuth } from "firebase-admin/auth";import { getFirestore } from "firebase-admin/firestore";initializeApp({ projectId: "demo-atlasmart-firestore" });export const adminAuth = getAuth();export const adminDb = getFirestore();

export async function verifiedActor(adminAuth, authorizationHeader) {  const prefix = "Bearer ";  if (!authorizationHeader?.startsWith(prefix)) {    throw Object.assign(new Error("UNAUTHENTICATED"), { status: 401 });  }  const idToken = authorizationHeader.slice(prefix.length);  const decoded = await adminAuth.verifyIdToken(idToken);  return {    uid: decoded.uid,    tenantId: decoded.tenantId,    role: decoded.role,    authTime: decoded.auth_time  };}export function authorizeRefund(actor, order) {  if (actor.tenantId !== order.tenantId) {    throw Object.assign(new Error("CROSS_TENANT"), { status: 403 });  }  if (!["support", "admin"].includes(actor.role)) {    throw Object.assign(new Error("ROLE_REQUIRED"), { status: 403 });  }  if (order.status !== "PAID") {    throw Object.assign(new Error("ORDER_NOT_REFUNDABLE"), { status: 409 });  }}

export async function handleRefundRequest(req) {  const correlationId = req.headers['x-correlation-id'] ?? crypto.randomUUID();  const actor = await verifiedActor(adminAuth, req.headers.authorization);  const orderRef = adminDb.doc(`orders/${req.body.orderId}`);  const orderSnap = await orderRef.get();  if (!orderSnap.exists) return { status: 404 };  authorizeRefund(actor, orderSnap.data());  // Chapter 10 principle: external payment action needs durable idempotency/workflow state.  // Chapter 9 principle: state-dependent Firestore changes use transaction/precondition as needed.  await orderRef.update({ status: 'REFUND_PENDING' });  auditAuthorization({    correlationId, actor, action: 'order.refund', resource: orderRef.path,    outcome: 'allow', reason: 'policy_passed'  });  return { status: 202, correlationId };}

{  "event": "projection_repair",  "correlationId": "job-2026-09-16T18:00Z-17",  "workload": "atlasmart-projection-repair",  "actorUid": null,  "source": "scheduled-reconciliation",  "resource": "users/u-1001/feed/e-order-o-9003",  "outcome": "repaired"}

export function auditAuthorization({ correlationId, actor, action, resource, outcome, reason }) {  console.log(JSON.stringify({    event: "authorization_decision",    correlationId,    actorUid: actor?.uid ?? null,    actorTenantId: actor?.tenantId ?? null,    actorRole: actor?.role ?? null,    action,    resource,    outcome,    reason,    // Deliberately omitted: ID token, refresh token, Authorization header,    // service-account private keys, ADC credential material.    at: new Date().toISOString()  }));}

const cases = [  { name: 'owner-direct-read', path: 'client', expect: 'ALLOW' },  { name: 'other-user-direct-read', path: 'client', expect: 'RULES_DENY' },  { name: 'client-refund-write', path: 'client', expect: 'RULES_DENY' },  { name: 'customer-refund-api', path: 'backend', expect: 'APP_DENY_ROLE' },  { name: 'support-cross-tenant-refund', path: 'backend', expect: 'APP_DENY_TENANT' },  { name: 'support-same-tenant-refund', path: 'backend', expect: 'APP_ALLOW_LOCAL' },  { name: 'backend-without-cloud-role', path: 'production-only', expect: 'IAM_DENY' }];for (const c of cases) console.log(JSON.stringify(c));// Local suite proves client Rules + backend app authorization + Admin bypass.// IAM_DENY requires an isolated real Google Cloud project and is never faked.