Set security rules and indexes

Your app's data shares the Firestore database and Storage bucket with Arc CMS, and Firebase takes one rules file for each. So you keep your rules and indexes in files of your own, and every deploy combines them with the core files.

The files

scripts/arc-rules-build.mjs writes the combined files, and firebase.json deploys those. It runs by itself before every Firestore and Storage deploy (a Firebase predeploy), so a plain deploy always ships your rules. .arc-build/ is ignored by git. To build the files by hand and look at them:

npm run rules:build

Write Firestore rules

Create firestore.app.rules at the root of the repository. It holds match blocks, and functions of your own if you need them, with no rules_version line and no service or match /databases/... wrapper:

match /users/{userDocId}/children/{childId} {
  allow read, write: if ownsUserRecord(userDocId);
  allow read: if isAdmin();

  match /progress/{lessonId} {
    allow read, write: if ownsUserRecord(userDocId);
  }
}

match /Lessons/{lessonId} {
  allow read: if isSignedIn();
  allow write: if isAdmin();
}

The build puts your file where the core file has the line // @arc-app-rules, inside match /databases/{database}/documents, so your rules can call the core helpers.

Write Storage rules

Create storage.app.rules the same way. It goes inside match /b/{bucket}/o. The core rules let the owner and admins read the per-user folder, users/{userDocId}/, but grant no writes there; your app grants them with its own limits:

match /users/{userDocId}/recordings/{fileName} {
  allow write: if ownsUserRecord(userDocId)
    && (request.resource == null
        || (request.resource.size < 10 * 1024 * 1024
            && request.resource.contentType.matches('audio/.*')));
}

Every other path in the bucket is public for reading, except folders named users in the first two levels. Put private files under users/{userDocId}/.

The helpers you can call

Both core files define these for app rules, with the same names and meaning:

The claims are explained in Roles and claims, and where per-person data belongs in Follow the account contract.

What an app rule can and cannot do

• It can only add access. Firebase allows a request when any matching rule allows it. Your rule can grant more; it can never take away what a core rule grants.
• Keep it to your own paths. A rule on a core collection can only widen access to it. If core's access is wrong for your app, that is a change to Arc CMS.
• Name your functions differently from core's. Besides the helpers above, the core Firestore file defines functions such as isAuthenticated, isOwnUserDoc, hasNoPassword and arcRole. Prefix your own, for example appIsTeacher().
• Choose collection names core does not use. Core's rules make every collection named arc_... or Tags_... readable by anyone and writable by editors, so a collection of yours with such a name is public whatever your rule says. app_pins and app_phone_pin_tries are core's too, closed to every browser: they hold your app's PINs and its gates' counts of wrong phone PINs (see PINs for your app).
• No wrapper. A rules_version line or a service block in your file breaks the combined file.

Firestore denies every path no rule matches, so a collection of yours without a rule is closed to the browser. Cloud Functions are not bound by rules.

Add indexes

Create firestore.app.indexes.json with the same shape as firestore.indexes.json:

{
  "indexes": [
    {
      "collectionGroup": "progress",
      "queryScope": "COLLECTION",
      "fields": [
        { "fieldPath": "done", "order": "ASCENDING" },
        { "fieldPath": "updatedAt", "order": "DESCENDING" }
      ]
    }
  ],
  "fieldOverrides": []
}

The build merges it with the core indexes and drops duplicates. A field override that both files define differently stops the build with a message: keep it in one file.

Deploy

Deploy rules and indexes like any other part; the combined files are built first. See Deploy and Security rules.

Test your rules

1. Create a spec in tests/rules/custom/, such as tests/rules/custom/children.spec.ts. Load the combined rules, as the core specs in tests/rules/ do, so your rules are tested together with the core ones:

   import { readFileSync } from 'node:fs';
   import { resolve } from 'node:path';
   import { afterAll, beforeAll, it } from 'vitest';
   import { assertFails, assertSucceeds, initializeTestEnvironment, RulesTestEnvironment } from '@firebase/rules-unit-testing';
   import { doc, getDoc } from 'firebase/firestore';
   
   let env: RulesTestEnvironment;
   
   beforeAll(async () => {
     env = await initializeTestEnvironment({
       projectId: 'demo-arccms-rules',
       firestore: { rules: readFileSync(resolve(__dirname, '../../../.arc-build/firestore.rules'), 'utf8') },
     });
   });
   afterAll(async () => { await env?.cleanup(); });
   
   it('lets a parent read their own child', async () => {
     const parent = env.authenticatedContext('parent-uid', { arccms_uid: 'parent-doc' }).firestore();
     await assertSucceeds(getDoc(doc(parent, 'users/parent-doc/children/c1')));
   });
   
   it('refuses another parent', async () => {
     const other = env.authenticatedContext('other-uid', { arccms_uid: 'other-doc' }).firestore();
     await assertFails(getDoc(doc(other, 'users/parent-doc/children/c1')));
   });

2. Run every rules spec, core and yours, against the Firestore and Storage emulators:

   npm run test:rules

   It builds the combined files first. It needs Java and the Firebase CLI, and it is not part of npm run test.

Run it whenever you change a rules file. See Testing.