firestore.rules

rules_version = '2';

service cloud.firestore {
  match /databases/{database}/documents {
    // The caller's own /users doc, as a DocumentReference. Signals and comments
    // store their owner as a reference to this doc, so every ownership check
    // below compares against it.
    function userDoc() {
      return /databases/$(database)/documents/users/$(request.auth.uid);
    }

    // A durably authenticated caller: email/password once verified, or Google,
    // which the provider verifies for us. NOT the anonymous sessions the app
    // opens at startup for every visitor. This is the second half of M-1
    // (HelpAPaw/Flutter#67) — the half that had to wait for an app release.
    //
    // WHY `email_verified` AND NOT `sign_in_provider`
    // The app upgrades an anonymous account IN PLACE (`linkWithCredential`,
    // same uid). That links a provider without re-authenticating, so the
    // session token's `sign_in_provider` stays 'anonymous' for the rest of that
    // session — for a real, upgraded user. Gating on it would lock out exactly
    // the people this is meant to admit. `email_verified` is derived from
    // account state when the token is minted, so it follows the upgrade, and it
    // mirrors the router gate that already keeps unverified users out of the
    // create UI.
    //
    // WHY THIS COULD NOT SHIP WITH THE REST OF M-1
    // `email_verified` is baked in at MINT time, and neither `User.reload()`
    // nor an app restart within the token's ~1h life re-mints it. A user who
    // verified (or upgraded) mid-session therefore carried a stale `false` and
    // had their first writes denied — which is what forced the 2026-07-23
    // rollback. The client now force-refreshes the token at both points that
    // flip the claim (`633da3b`: email_verification_page, sign_in_page), and
    // that shipped in 6.0.2+126.
    //
    // Anything server-side (the fan-out, moderation, ownership) uses the Admin
    // SDK and bypasses rules entirely, so nothing legitimate is caught here.
    function isVerifiedCaller() {
      return request.auth != null
             && request.auth.token.email_verified == true;
    }

    // The signal's reporter (owner), compared by DocumentReference path.
    // Used by both the prod and test signal update/delete rules so the
    // security-critical ownership check lives in exactly one place.
    function isSignalReporter() {
      return resource.data.reporter == userDoc();
    }

    // The caller holds the moderator role (master spec 3.6.1).
    //
    // A server-only DOCUMENT, deliberately not a custom auth claim. Moderator
    // *actions* all run through callable Cloud Functions, which re-check this
    // same document with the Admin SDK — so the claim would only ever decide
    // whether the client draws a button, at the cost of a second copy of the
    // value that can drift. It would also inherit the ID token's refresh
    // window: a revoked moderator would keep their powers until the token
    // expired, up to an hour. Reading the document instead makes both grant
    // and revoke take effect on the very next request.
    //
    // Costs one document read per evaluation, which is why every call site
    // below places it LAST in an `||` chain — the owner check short-circuits
    // first, so the ordinary path never pays for it.
    function isModerator() {
      return request.auth != null
             && exists(/databases/$(database)/documents/moderators/$(request.auth.uid));
    }

    // Comments are locked on the parent signal at {coll}/{signalId} (master
    // spec 18.3, "Lock comments").
    //
    // Nested `get()` with defaults so a signal with no `moderation` map at all
    // — which is every signal written before this feature — reads as unlocked
    // rather than erroring the whole rule and denying every comment.
    function isCommentsLocked(coll, signalId) {
      return get(/databases/$(database)/documents/$(coll)/$(signalId))
               .data.get('moderation', {}).get('commentsLocked', false) == true;
    }

    // The `moderation` map is written ONLY by the Cloud Functions (Admin SDK,
    // bypasses rules). No client may touch it — least of all the reporter.
    //
    // This is load-bearing, not defensive: the reporter's own update branch
    // (isSignalReporter) accepts *any* field at any value, so without this a
    // reporter could clear `moderation.commentsLocked` or delete the warning
    // label a moderator put on their signal, straight from a patched client.
    // The lock would be decoration.
    function isNotTouchingModeration() {
      return !request.resource.data.diff(resource.data)
                .affectedKeys().hasAny(['moderation']);
    }

    // The caller currently holds this signal (master spec 4.5).
    //
    // The DEFAULT ARGUMENT is the "absent means the reporter" derivation, and it
    // is permanent rather than a migration step: builds released before signal
    // ownership keep creating signals with no `signalOwner`, so no ruleset can
    // assume the field is there, and nothing is backfilled.
    //
    // A RELEASED signal stores an explicit null, which equals no userDoc() — so a
    // released signal correctly has no owner rather than falling back to the
    // reporter, who is the one person who may have just stepped away from it.
    // That distinction is the whole point of storing null rather than deleting
    // the field, and collapsing the two is the mistake this comment exists to
    // prevent.
    function isSignalOwner() {
      return resource.data.get('signalOwner', resource.data.reporter) == userDoc();
    }

    // `signalOwner` is written ONLY by the signalOwnership Cloud Function (Admin
    // SDK, bypasses rules), plus once at creation via isSignalCreate().
    //
    // Load-bearing for exactly the reason isNotTouchingModeration() is, and
    // applied to BOTH update branches for the same reason: the reporter's branch
    // accepts any field at any value, so without this a reporter could never be
    // handed off from — they would simply write themselves back in — and any
    // signed-in user on a patched client could seize a stranger's signal by
    // writing one field. The timeline would show no transfer, because no event
    // was written.
    function isNotTouchingOwnership() {
      return !request.resource.data.diff(resource.data)
                .affectedKeys().hasAny(['signalOwner']);
    }

    // `ownerActiveAt` is a CLOCK, so it is pinned to the server's.
    //
    // The staleness rule that stops a signal deadlocking behind a silent owner
    // reads this field, which means an owner free to choose its value could keep
    // a signal they have abandoned forever. Allowed on either branch — the owner
    // stamps it as part of an ordinary status change — but never at a value the
    // caller picked.
    function isValidOwnerStamp() {
      return !request.resource.data.diff(resource.data)
                .affectedKeys().hasAny(['ownerActiveAt'])
             || request.resource.data.ownerActiveAt == request.time;
    }

    // The caller holds the signal on the parent signal at {coll}/{signalId}.
    // Same shape and same reasoning as isParentSignalReporter, including the
    // absent-means-reporter default; backs the takeoverRequests rules, where a
    // owner must not be able to file a request against themselves.
    function isParentSignalOwner(coll, signalId) {
      // `let` so the document is fetched ONCE. Spelling the get() out twice —
      // for the value and for the default — is two billed document reads on
      // every takeover-request write, for one answer.
      let parent = get(/databases/$(database)/documents/$(coll)/$(signalId)).data;
      return parent.get('signalOwner', parent.reporter) == userDoc();
    }

    // The caller is the reporter of the parent signal at {coll}/{signalId}.
    // Backs the comment-delete cascade for both the prod and test collections,
    // so that ownership check lives in one place instead of being inlined twice.
    function isParentSignalReporter(coll, signalId) {
      return get(/databases/$(database)/documents/$(coll)/$(signalId)).data.reporter
             == userDoc();
    }

    // Shared title/description bounds for both create and update. Applying it
    // to update too closes a gap where only create was checked: the edit
    // screen writes both fields on every save, so an update with no
    // client-side cap could otherwise persist an unbounded title or
    // description.
    function isValidSignalContentBounds() {
      return request.resource.data.title is string
             && request.resource.data.title.size() > 0
             && request.resource.data.title.size() <= 300
             && request.resource.data.description is string
             && request.resource.data.description.size() <= 10000;
    }

    // Validates a signal create (M-1): a verified, non-anonymous caller, with
    // `reporter` pinned to them (no impersonation), plus basic type/size bounds
    // on the content fields to curb content abuse and read/storage-cost
    // inflation.
    function isSignalCreate() {
      return isVerifiedCaller()
             && request.resource.data.reporter == userDoc()
             && isValidSignalContentBounds()
             // `signalType` is deliberately NOT required, and not bounded
             // either. Signal types were folded into the help-tag vocabulary
             // and nothing writes the field any more, but builds released
             // before that still send it — mandating or range-checking a
             // retired field would only ever break an old client.
             && isValidUrgency()
             && isValidHelpNeededTags()
             && isValidAnimalType()
             && isValidInitialSignalOwner();
    }

    // The reporter is the initial signal owner (master spec 4.5).
    //
    // Optional-if-absent for the same reason as isValidUrgency: builds released
    // before signal ownership create signals with no `signalOwner`, and readers
    // derive one. Present-and-wrong is what this rejects — a signal cannot be
    // created already assigned to somebody else, which would be a way to write
    // the field without going through the callable or leaving a timeline entry.
    //
    // `ownerActiveAt` is REJECTED outright on create, and that is a security
    // check rather than tidiness: isValidOwnerStamp() is wired into the two
    // update rules only, so without this clause a patched client could create a
    // signal stamped with a far-future `ownerActiveAt`. `isOwnerStale` then
    // computes a negative age forever, and the staleness escape hatch — the
    // thing that stops a signal deadlocking behind an owner who stops answering —
    // is permanently disabled for that signal, silently.
    //
    // The server falls back to `createdAt` until the owner first acts, so
    // omitting it costs nothing.
    function isValidInitialSignalOwner() {
      return !('ownerActiveAt' in request.resource.data)
             && (!('signalOwner' in request.resource.data)
                 || request.resource.data.signalOwner == userDoc());
    }

    // Bounds the help tags, but does NOT require the field — same reasoning as
    // isValidUrgency. Builds released before the tag system are still in the
    // wild and create signals with none; the fan-out defaults those to the
    // fallback tag, so they still reach people. Requiring it here would break
    // signal creation for everyone who has not updated.
    //
    // Tighten to mandatory only once adoption of the tagged build is high
    // enough — that is step 3 of the rollout, and it is a production deploy.
    // This did NOT change when signal types were retired: tags are now the only
    // thing describing what a signal needs, which makes requiring them more
    // tempting and no less breaking. An old build that cannot create a signal
    // at all is a worse outcome than one whose signals default to `rescue`.
    //
    // The size cap is a reach limit as much as a priority limit: tagging a
    // signal with the whole vocabulary would make it match every user. The
    // codes themselves are NOT validated against an allow-list, deliberately —
    // a newer client may introduce a code this deployed ruleset has never heard
    // of, and rejecting it would break the new build instead of the old one.
    function isValidHelpNeededTags() {
      return !('helpNeededTags' in request.resource.data)
             || (request.resource.data.helpNeededTags is list
                 && request.resource.data.helpNeededTags.size() > 0
                 && request.resource.data.helpNeededTags.size() <= 3);
    }

    // Optional for the same reason, and left unconstrained beyond being a
    // string so a future species cannot be rejected by an old ruleset.
    function isValidAnimalType() {
      return !('animalType' in request.resource.data)
             || (request.resource.data.animalType is string
                 && request.resource.data.animalType.size() > 0
                 && request.resource.data.animalType.size() <= 32);
    }

    // Bounds the urgency level, but does NOT require the field.
    //
    // Optional on purpose: builds released before the urgency system are still
    // in the wild and create signals with no `urgency` at all. Making it
    // mandatory would break signal creation for every user who has not
    // updated, which is not a trade worth making for a field the client
    // back-fills on read anyway.
    function isValidUrgency() {
      return !('urgency' in request.resource.data)
             || (request.resource.data.urgency is int
                 && request.resource.data.urgency >= 0
                 && request.resource.data.urgency <= 2);
    }

    // Validates a comment create (M-1): author pinned to the caller. Covers all
    // three comment shapes — user text comments, and the `status_change` /
    // `urgency_change` system comments (which carry no `text`) — so the text
    // bounds only apply when a `text` field is present.
    //
    // Takes the collection so the lock check can name the parent signal, the
    // same way isParentSignalReporter does. That `get()` is one extra read per
    // comment write; comments are low-volume, and it is the difference between
    // a real lock and a hidden text field. It also denies comments on a
    // QUARANTINED signal for free: the parent document no longer exists, so
    // the get() fails and the write is refused.
    function isCommentCreate(coll, signalId) {
      return isVerifiedCaller()
             && request.resource.data.author == userDoc()
             && (
               !('text' in request.resource.data)
               || (request.resource.data.text is string
                   && request.resource.data.text.size() > 0
                   && request.resource.data.text.size() <= 2000)
             )
             && isValidMentions()
             && !isCommentsLocked(coll, signalId);
    }

    // Bounds the @-mention array on a comment (spec 7.5).
    //
    // The COUNT is all this can say. Rules have no way to iterate a list, so
    // there is no expressing "every entry is a {uid, start, end}" here, and
    // pretending otherwise with a `size()` check on entry 0 would be worse than
    // saying nothing. The array is therefore untrusted input on the server too,
    // and `functions/src/mentions.ts` decodes it defensively — which costs
    // nothing, because a forged mention cannot reach anybody: it only re-words a
    // notification a subscriber was already being sent.
    //
    // The cap is duplicated from `maxMentionsPerComment`
    // (lib/src/models/comment_mention.dart) and guarded by
    // test/models/comment_mention_test.dart. Drifting BELOW the client's cap is the
    // silent direction: a shipped build's write starts failing and the author is
    // told only that the comment could not be added.
    function isValidMentions() {
      return !('mentions' in request.resource.data)
             || (request.resource.data.mentions is list
                 && request.resource.data.mentions.size() <= 10);
    }

    // Validates a signal-timeline event create (master spec 4.6).
    //
    // Events live in their own subcollection rather than in `comments` because
    // they answer to different rules: a comment is user-authored and its text is
    // the payload, while an event is a record of something that happened to the
    // signal and its shape is fixed per `type`. Keeping them apart is what lets
    // this function validate a CLOSED vocabulary instead of accumulating another
    // "only when present" clause per event type, the way isCommentCreate() had
    // to for the two system shapes it still has to tolerate.
    //
    // The type list is duplicated from SignalEventType (lib/src/models/signal_event.dart)
    // and guarded by test/signal_event_vocabulary_guard_test.dart. A type the app
    // can write but the rules reject fails loudly (the write is denied); a type
    // the rules accept but the app cannot read fails SILENTLY — the row just
    // never appears in anyone's history.
    //
    // A `status_change` event does not by itself authorise the status change:
    // the signal write travels through isSignalOwnerUpdate() separately.
    function isSignalEventCreate() {
      return request.auth != null
             && request.resource.data.actor == userDoc()
             && request.resource.data.createdAt is timestamp
             && isValidEventNote()
             && (
               (request.resource.data.type == 'status_change'
                && isValidLevel('oldStatus') && isValidLevel('newStatus'))
               || (request.resource.data.type == 'urgency_change'
                   && isValidLevel('oldUrgency') && isValidLevel('newUrgency'))
               || (request.resource.data.type == 'tags_change'
                   && isValidTagList('oldTags', 0)
                   && isValidTagList('newTags', 1))
             );
    }

    // NOTE the type NOT in that list: `ownership_transfer`. It is SERVER-ONLY
    // (SignalEventType.serverOnly) — the signalOwnership callable writes it through
    // the Admin SDK, which bypasses rules entirely, so omitting it here costs
    // nothing and buys a real property: nobody can forge a timeline entry saying
    // they took responsibility for a signal. The drift guard therefore compares
    // this list against SignalEventType.clientCodes, not allCodes. Do NOT add it
    // here to make a failing guard pass.

    // The update note is MANDATORY on an event (spec 4.6: "Every status change
    // requires an update note"), unlike `text` on a comment, which is optional
    // because the legacy system shapes carry none.
    //
    // 500 is mirrored by the input formatter on the note dialog — see the
    // field-length invariant in docs/SPECIFICATION.md 12.
    function isValidEventNote() {
      return request.resource.data.note is string
             && request.resource.data.note.size() > 0
             && request.resource.data.note.size() <= 500;
    }

    // A status or urgency code. Same 0..2 bound as the signal fields they
    // describe, so an event can never claim a transition the signal itself
    // could not hold.
    // `get` with an out-of-range default so an absent field fails the bound
    // rather than needing a separate `in` check.
    function isValidLevel(field) {
      let value = request.resource.data.get(field, -1);
      return value is int && value >= 0 && value <= 2;
    }

    // The before/after tag lists on a `tags_change` event (#80), bounded by the
    // same 1..3 the signal's own `helpNeededTags` is (isValidHelpTags) — an
    // event must not be able to claim a transition the signal could not hold.
    //
    // [minSize] differs by side and both values are deliberate. `newTags` is the
    // state the signal is moving to, and the picker refuses to confirm an empty
    // selection, so 1. `oldTags` is 0 because a signal created before the tag
    // vocabulary genuinely has none, and requiring one there would make the very
    // first tag change on a legacy signal the one thing nobody can record.
    //
    // The CODES are not enumerated here on purpose. `HelpTag` is the vocabulary,
    // mirrored once in `functions/src/tags.ts` and guarded; a third copy in the
    // rules would be one no test parses, and its drift would deny writes from a
    // client that had added a tag. isValidHelpTags takes the same position on
    // the signal document itself.
    function isValidTagList(field, minSize) {
      let value = request.resource.data.get(field, null);
      return value is list && value.size() >= minSize && value.size() <= 3;
    }

    // Validates the display name on a publicProfiles write (L-2). Bounds the
    // length and rejects control characters — a newline or a NUL in a name that
    // is rendered next to every signal and comment is only ever abuse.
    //
    // `matches()` is a whole-string RE2 match. The pattern reads as "any run of
    // non-control characters containing at least one that isn't a space", so it
    // also rejects "" and whitespace-only names, which would render as a blank
    // author and read as a deleted/unknown user.
    //
    // **Absent passes.** The document carries two independently written client
    // fields now, and `PublicProfileService.setPhotoUrl` merge-writes only the
    // avatar — on an account whose profile does not exist yet, that is a
    // *create* holding no name at all. Requiring one here would make the order
    // of two unrelated mirror-writes decide whether either succeeds. The write
    // still has to carry something: see `hasAny` at the create/update rules.
    function isValidProfileName() {
      return !('name' in request.resource.data)
             || (request.resource.data.name is string
                 && request.resource.data.name.size() <= 100
                 && request.resource.data.name
                      .matches('[^\\x00-\\x1f]*[^\\x00-\\x20][^\\x00-\\x1f]*'));
    }

    // Validates the avatar URL on a publicProfiles write.
    //
    // **Host-restricted, not "any https URL", and that is the whole point of
    // the function.** This value is handed to an image loader on every other
    // user's device wherever the profile is shown, so an unrestricted field
    // would let one user aim every viewer's phone at a URL of their choosing —
    // an IP/user-agent log at minimum, an arbitrarily large download at worst.
    //
    // The two branches are the only two places an avatar can actually come
    // from: the app's own Storage bucket (`profile_page.dart` uploads to
    // `profile_photos/{uid}.jpg` and mirrors the download URL) and a Google
    // account photo adopted at sign-in. The Storage branch is pinned to the
    // caller's OWN uid, so it cannot be used to point at someone else's avatar
    // and pass it off as theirs. The Google branch cannot be pinned to anything
    // — the path carries an opaque account id — and does not need to be: every
    // URL on that host is a Google-hosted image, which is the property being
    // bought here.
    //
    // `lh[0-9]+`, not `lh3` alone: Google has served account photos from lh3
    // through lh6 over the years and older accounts still carry the earlier
    // hosts. Pinning the digit would deny those avatars forever, and the denial
    // is invisible — the mirror is best-effort and only `debugPrint`s.
    //
    // Absent passes, for the same reason as the name: a name-only write must
    // not have to restate the avatar.
    function isValidProfilePhotoUrl(userId) {
      return !('photoUrl' in request.resource.data)
             || (request.resource.data.photoUrl is string
                 && request.resource.data.photoUrl.size() <= 500
                 && request.resource.data.photoUrl.matches(
                      'https://firebasestorage\\.googleapis\\.com/v0/b/[a-zA-Z0-9._-]+/o/profile_photos%2F'
                      + userId + '\\.jpg\\?.*'
                      + '|https://lh[0-9]+\\.googleusercontent\\.com/[^ ]*'));
    }

    // The SIGNAL OWNER's coordination powers (master spec 4.5, 4.2, 5.2): the
    // status, the urgency and the help-needed tags, plus the two stamps that
    // travel with them. Everything else about the signal stays the reporter's.
    //
    // This REPLACED isStatusOnlyUpdate(), which let ANY signed-in user change
    // ANY signal's status. That is why `urgency` used to be excluded from this
    // allow-list, and why that exclusion was described — here, and in
    // SPECIFICATION 4.6 and 5.1 — as the entire enforcement of "only the signal
    // owner may mark a signal Red": with no ownership concept, the reporter was
    // the only stand-in for a signal owner the app had.
    //
    // Now there is one. The gate moved from the FIELD LIST to isSignalOwner(), so
    // `urgency` and `helpNeededTags` being here is the spec being implemented
    // rather than the old rule being weakened — master spec 5.2 names the case
    // holder explicitly, and 4.2 gives them the tags. **The load-bearing clause
    // is now isSignalOwner(); do not drop it to "simplify" this function.**
    //
    // lastUpdatedBy is still self-stamped so it can't be pointed at someone else
    // (handleSignalUpdated uses it to decide whom NOT to notify), and
    // ownerActiveAt is pinned to the server clock by isValidOwnerStamp on the
    // rule itself.
    // **THIS BREAKS ALREADY-RELEASED BUILDS, DELIBERATELY.** Every shipped
    // client writes `{status, lastUpdatedBy}` for any signed-in user, which the
    // old rule allowed; here it is denied on any signal the caller did not
    // report and does not hold. Those builds have no ownership UI, so there is
    // no claim path and the user just gets "Failed to update status".
    //
    // Called out explicitly, the way the M-1 / #67 comments above are, because
    // the mitigation is a DEPLOY ORDER and not a code change: functions first,
    // then the app release that offers claim-to-act, then this ruleset — never
    // this ruleset first. Tracking: HelpAPaw/Flutter#71, and SPECIFICATION 4.8.
    function isSignalOwnerUpdate() {
      return isSignalOwner()
             && request.resource.data.diff(resource.data).affectedKeys()
                  .hasOnly(['status', 'urgency', 'helpNeededTags',
                            'lastUpdatedBy', 'ownerActiveAt'])
             && request.resource.data.lastUpdatedBy == userDoc()
             && request.resource.data.status is int
             && request.resource.data.status >= 0
             && request.resource.data.status <= 2;
    }

    // Whether an ANSWERED takeover request may be filed again.
    //
    // A decline should not be permanent — a signal looks very different two weeks
    // later, and a volunteer told "no, I have this" in the first hour may be the
    // right person once the owner has moved on. But re-asking has to cost
    // something, because every request notifies the owner, and a decline is
    // exactly the moment somebody might start nagging.
    //
    // One day. Long enough that it cannot be used to pester, short enough that
    // it never blocks a genuine change of circumstances.
    //
    // The value is mirrored by `SignalOwnershipService.reaskCooldown`, which the
    // UI needs to say *when* the offer can be made again, and guarded by
    // `test/takeover_cooldown_guard_test.dart` — see the field-length invariant
    // in docs/SPECIFICATION.md 12 for why that pairing is always guarded.
    function isAfterReaskCooldown() {
      return resource.data.status != 'pending'
             && resource.data.resolvedAt is timestamp
             && request.time > resource.data.resolvedAt + duration.value(1, 'd');
    }

    // Withdrawing your own offer, which is an UPDATE and not a delete.
    //
    // It has to be, or the cooldown above is decoration: if withdrawing removed
    // the document, `create` would be unconstrained again and
    // withdraw → re-file → withdraw → re-file is an unlimited loop, notifying
    // the owner every time. Marking it `withdrawn` leaves the slot occupied, so
    // asking again costs the same cooldown as being declined does.
    //
    // `resolvedAt` is pinned to `request.time` for the same reason it is on the
    // owner's stamp — a value the requester could choose is a cooldown they
    // could skip. `handleTakeoverResolved` ignores this status, so nobody is
    // notified that somebody changed their mind.
    function isTakeoverWithdraw(requesterId) {
      return request.auth != null
             && request.auth.uid == requesterId
             && resource.data.status == 'pending'
             && request.resource.data.status == 'withdrawn'
             && request.resource.data.resolvedAt == request.time
             && request.resource.data.diff(resource.data).affectedKeys()
                  .hasOnly(['status', 'resolvedAt']);
    }

    // Validates a takeover request (master spec 4.5, "case ownership can be
    // transferred if someone else takes responsibility").
    //
    // The DOCUMENT ID IS THE RATE LIMIT — it is the requester's uid, create is
    // allowed and update is not, so one person can have at most one live request
    // per signal. Same trick as isReportCreate below.
    //
    // Blocks anonymous callers, as signal and comment creation now also do
    // (isVerifiedCaller). This one uses `sign_in_provider` rather than
    // `email_verified` and can keep doing so: nothing has ever written this
    // collection from an in-place-upgraded session, which is the case that
    // makes `sign_in_provider` unsafe for the older surfaces.
    function isTakeoverRequestCreate(coll, signalId, requesterId) {
      return request.auth != null
             && request.auth.uid == requesterId
             && request.auth.token.firebase.sign_in_provider != 'anonymous'
             && request.resource.data.requester == userDoc()
             && request.resource.data.status == 'pending'
             && isValidEventNote()
             && request.resource.data.createdAt is timestamp
             && request.resource.data.keys()
                  .hasOnly(['requester', 'status', 'note', 'createdAt'])
             && !isParentSignalOwner(coll, signalId);
    }

    // Users collection - private profile (tokens, location, prefs, phone).
    // Owner-only: never expose to other users.
    //
    // NOTE: rules do NOT cascade into subcollections. This block covers the user
    // document only — `users/{uid}/notifications/{id}` needs its own match below,
    // and so would any future subcollection.
    match /users/{userId} {
      allow read: if request.auth != null && request.auth.uid == userId;

      // create/update and delete are split on purpose. `isValidHelperPrefs`
      // dereferences `request.resource.data`, which is **null on a delete** — a
      // combined `allow write` therefore errors and denies every delete,
      // including the owner's own. That breaks `detachAnonymousData`, which
      // deletes this doc and `userLocations/{uid}` in one try block: the first
      // delete throws, the second never runs, and the abandoned uid keeps a live
      // location doc that the fan-out still treats as a candidate.
      allow create, update: if request.auth != null
                            && request.auth.uid == userId
                            && isValidHelperPrefs();
      allow delete: if request.auth != null && request.auth.uid == userId;
    }

    // Size caps on the tag/species preference lists.
    //
    // Only the owner can write here, so this is not an authorization boundary —
    // it is a bound on how far one account can inflate the fan-out's work.
    // Those lists are read for every candidate on every signal, and nothing
    // else stops a client writing ten thousand entries into one.
    //
    // Codes are not checked against an allow-list, for the same reason as
    // isValidHelpNeededTags: a newer app build must not be rejected by an older
    // deployed ruleset. An unrecognised code simply never matches.
    function isValidHelperPrefs() {
      return isBoundedCodeList('helperTags', 32)
             && isBoundedCodeList('animalTypes', 32);
    }

    // `field` under notificationPreferences is absent, or a list of at most
    // `max` entries. Absent is always allowed: every writer of this document
    // uses a merged partial write, so most updates touch none of these.
    function isBoundedCodeList(field, max) {
      return !('notificationPreferences' in request.resource.data)
             || !(field in request.resource.data.notificationPreferences)
             || (request.resource.data.notificationPreferences[field] is list
                 && request.resource.data.notificationPreferences[field].size() <= max);
    }

    // In-app notification inbox, one document per notification per recipient.
    // Written server-side by the fan-out (Admin SDK, bypasses rules) and
    // client-side by the arrival catch-up (NearbySignalChecker), which runs in a
    // headless isolate.
    match /users/{userId}/notifications/{notificationId} {
      allow read: if request.auth != null && request.auth.uid == userId;

      // The only client-side writer is the catch-up, and it only ever produces
      // `nearby_signal`. Pinning the type stops a client fabricating a
      // `status_change` entry it was never sent. The size caps are the real
      // security value: without them an owner-only collection is a free-storage
      // vector. `expiresAt` is required or the document would outlive the TTL
      // policy forever.
      allow create: if request.auth != null
                    && request.auth.uid == userId
                    // Both field shapes are allowed, and neither is required.
                    // Builds released before the tag vocabulary write
                    // `signalType`; newer ones write `helpNeededTags`. A phased
                    // release means both are in the wild for months, and this
                    // rule is the *client* write path for the arrival catch-up
                    // — rejecting the old shape makes that inbox entry vanish
                    // silently, because NearbySignalChecker swallows the error.
                    // Tighten to helpNeededTags-only once old builds are gone.
                    // Tracking: HelpAPaw/Flutter#70.
                    && request.resource.data.keys().hasOnly([
                         'type', 'title', 'body', 'read', 'signalId',
                         'signalTitle', 'helpNeededTags', 'signalType',
                         'testMode', 'createdAt', 'expiresAt'
                       ])
                    && request.resource.data.type == 'nearby_signal'
                    && request.resource.data.read == false
                    && request.resource.data.signalId is string
                    && request.resource.data.signalId.size() <= 200
                    && request.resource.data.title is string
                    && request.resource.data.title.size() <= 300
                    && request.resource.data.body is string
                    && request.resource.data.body.size() <= 1000
                    && request.resource.data.signalTitle is string
                    && request.resource.data.signalTitle.size() <= 300
                    // Bounded if present, never required — see the allow-list
                    // above. Codes are not checked against a list: a newer
                    // client may know one this deployed ruleset does not, and
                    // rejecting it would break the new build rather than the
                    // old one. Same reasoning as isValidHelpNeededTags.
                    && (!('helpNeededTags' in request.resource.data)
                        || (request.resource.data.helpNeededTags is list
                            && request.resource.data.helpNeededTags.size() <= 3))
                    && (!('signalType' in request.resource.data)
                        || request.resource.data.signalType is int)
                    && request.resource.data.testMode is bool
                    && request.resource.data.createdAt is timestamp
                    && request.resource.data.expiresAt is timestamp;

      // Diff-based: the page only ever flips `read`, so a client can't rewrite
      // the title/body/signalId of a notification after the fact.
      allow update: if request.auth != null
                    && request.auth.uid == userId
                    && request.resource.data.diff(resource.data)
                         .affectedKeys().hasOnly(['read'])
                    && request.resource.data.read is bool;

      allow delete: if request.auth != null && request.auth.uid == userId;
    }

    // User live location - kept separate from the user doc so high-frequency
    // location writes don't trigger the token-dedupe Cloud Function. Owner-only;
    // the notification fan-out reads it via the Admin SDK (bypasses rules).
    match /userLocations/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }

    // Unread-notification counter, source of the iOS app badge. Top-level for
    // the same reason as userLocations: `onUserTokensWritten` fires on every
    // `users/{uid}` write, so a counter on the user doc would cost one function
    // invocation per recipient per notification.
    //
    // The value is advisory — it drifts on Cloud Function retries and TTL
    // deletions — and the client repairs it with a count() aggregation on
    // resume. That is why the owner may write it directly.
    match /userCounters/{userId} {
      allow read: if request.auth != null && request.auth.uid == userId;
      allow write: if request.auth != null
                   && request.auth.uid == userId
                   && request.resource.data.keys().hasOnly(['unread', 'updatedAt'])
                   && request.resource.data.unread is int
                   && request.resource.data.unread >= 0;
    }

    // Public profiles - the display name and avatar, readable by any signed-in
    // user (incl. anonymous) so reporter/comment-author names and pictures
    // resolve for everyone. Writable only by the owner. On account deletion
    // this is overwritten with "Deleted user" so erasure propagates to all
    // signals/comments dynamically.
    match /publicProfiles/{userId} {
      // Single-document reads only (L-2). The app resolves names one uid at a
      // time (PublicProfileService.getName), so denying `list` costs it nothing
      // and stops the entire user base being enumerated from one query. Do NOT
      // widen this back to `read` — that grants `list` again.
      allow get: if request.auth != null;
      allow list: if false;
      // The only fields the app ever writes here are `name` and `photoUrl`.
      // `deleted`/`deletedAt` are tombstone fields, and `signalsPosted` a
      // server-owned counter, both written through the Admin SDK, which
      // bypasses rules — so restricting the caller to these two costs nothing,
      // stops a user clearing their own "Deleted user" tombstone, and is the
      // entire security of `signalsPosted`: a stat its subject cannot set.
      // **Do not add a field to this allow-list without checking whether some
      // server-written value beside it was relying on being excluded.**
      //
      // `hasAny` because each field is optional and validated only when present
      // (the two mirror-writes are independent), which would otherwise let an
      // empty document be created.
      allow create: if request.auth != null
                    && request.auth.uid == userId
                    && request.resource.data.keys().hasOnly(['name', 'photoUrl'])
                    && request.resource.data.keys().hasAny(['name', 'photoUrl'])
                    && isValidProfileName()
                    && isValidProfilePhotoUrl(userId);
      // Diff-based (not `keys()`) so a name edit on a doc that already carries
      // the tombstone fields isn't rejected for merely containing them.
      allow update: if request.auth != null
                    && request.auth.uid == userId
                    && request.resource.data.diff(resource.data)
                         .affectedKeys().hasOnly(['name', 'photoUrl'])
                    && isValidProfileName()
                    && isValidProfilePhotoUrl(userId);
      allow delete: if request.auth != null && request.auth.uid == userId;
    }

    // Signals collection - public read, authenticated write
    match /signals/{signalId} {
      allow read: if true;  // Public read - signals are public data
      // M-1, complete: a verified non-anonymous caller (isVerifiedCaller),
      // `reporter` bound to them, and the content fields bounded.
      allow create: if isSignalCreate();
      // Reporter may edit any field; the SIGNAL OWNER may change the coordination
      // fields (status, urgency, tags). Nobody else may write the signal at all
      // — a volunteer who wants to move a signal claims it first, through the
      // signalOwnership callable (master spec 4.5, "the current case holder can
      // update status").
      //
      // `isValidUrgency()` applies to BOTH branches. The reporter branch
      // otherwise accepts any field at any value, and an out-of-range urgency
      // is not a client-side cosmetic problem: the server reads it raw, so
      // `urgency: 42` makes every write look like an escalation
      // (`42 > 2`) and wakes every subscriber with a "Updated" push.
      //
      // The tag/species validators apply to both branches for the same reason,
      // and the cap especially: `helpNeededTags` is a *reach* limit, so leaving
      // update unvalidated means a reporter can create a compliant signal and
      // then widen it to the whole vocabulary, matching every user in the
      // fan-out's set intersection. The edit screen writes both fields on
      // update, so this is the path that field actually travels.
      //
      // `isNotTouchingModeration()` applies to BOTH branches — see its doc
      // comment. The reporter branch is the one that matters.
      allow update: if request.auth != null
                    && isValidUrgency()
                    && isValidHelpNeededTags()
                    && isValidAnimalType()
                    && isValidSignalContentBounds()
                    && isNotTouchingModeration()
                    && isNotTouchingOwnership()
                    && isValidOwnerStamp()
                    && (isSignalReporter() || isSignalOwnerUpdate());
      // Only the signal's reporter may delete it
      allow delete: if request.auth != null && isSignalReporter();

      // Comments subcollection
      match /comments/{commentId} {
        allow read: if true;  // Public read
        allow create: if isCommentCreate('signals', signalId);
        // The signal's reporter may delete comments (enables delete-signal cascade).
        //
        // **The worse half of the #68 gap, and not an audit problem.** There is
        // no author-delete rule anywhere on this collection, so the standing
        // effect is that a comment's own author cannot delete their comment but
        // the signal's reporter can delete ANYONE's — quietly, one at a time,
        // with no audit row. Removing every critical comment on your own signal
        // is the power master spec §18.3 deliberately routes through
        // `moderateAction.deleteComment`, which demands a note, writes an audit
        // entry and refuses your own content.
        //
        // Retired together with the two rules below — see the events block for
        // why the flip is a separate deploy. Tracking: HelpAPaw/Flutter#68.
        allow delete: if request.auth != null
                      && isParentSignalReporter('signals', signalId);
      }

      // Signal timeline (master spec 4.6). See isSignalEventCreate() for why
      // this is not in `comments`.
      match /events/{eventId} {
        allow read: if true;  // Public read, like the signal it describes
        allow create: if isSignalEventCreate();
        // An event is a record of what happened; nobody edits history.
        allow update: if false;
        // KNOWN GAP, now with a fix built and waiting on a deploy order.
        //
        // The reporter can delete individual events, so the history is
        // tamper-evident at best. This only ever existed because the
        // delete-signal cascade ran on the CLIENT and had to be able to empty
        // the subcollection, or deleting a signal orphaned it forever.
        //
        // **That cascade is gone.** `signalRemoval` (functions/src/removeSignal.ts)
        // moves the document server-side and `purgeRemoval` erases the
        // descendants with an Admin SDK `recursiveDelete`, which bypasses these
        // rules entirely. Nothing in the new client deletes an event.
        //
        // So this becomes `allow delete: if false` — but NOT in the same deploy
        // as the rest of #68, and this is a DEPLOY ORDER, not a code change.
        // Every already-released build still runs the old cascade, whose one
        // batch covers all three subcollections; denying it makes that batch
        // fail atomically, so nothing is deleted and the user gets that
        // build's own `failedToDeleteSignal` (a string this branch has since
        // renamed) on any signal that has history. Clean — no half-deleted
        // signal — but still a broken Delete button until they update. Flip this, and the
        // two rules below it, and `isParentSignalReporter`, only once the
        // release carrying `signalRemoval` is on the installed base — the same
        // sequencing #71 is waiting on. Tracking: HelpAPaw/Flutter#68.
        allow delete: if request.auth != null
                      && isParentSignalReporter('signals', signalId);
      }

      // Takeover requests (master spec 4.5). Doc id IS the requester's uid.
      //
      // Client-written, unlike the transfer itself, because a request is an
      // ordinary user-authored document with no privilege attached — routing it
      // through a function would buy nothing, exactly as with `reports`. The
      // owner is told about it by the onTakeoverRequested trigger, and
      // APPROVING it is the privileged half, which is the callable's job.
      match /takeoverRequests/{requesterId} {
        // Signed-in rather than public: unlike a comment, this names someone who
        // volunteered but has not been accepted, and every reader of this app
        // holds at least an anonymous session anyway.
        allow read: if request.auth != null;
        allow create: if isTakeoverRequestCreate('signals', signalId, requesterId);
        // The ONLY client update is re-filing an answered request after the
        // cooldown, and it has to satisfy the create validator too — so a
        // re-filed request cannot have a different shape from a fresh one, and
        // in particular cannot arrive already `approved`. Approving and
        // declining stay the signalOwnership callable's job: a client that could
        // flip `status` here would claim to have been accepted.
        // Ordered cheapest-first, the same convention isModerator() documents:
        // withdrawing needs no get() at all, and the cooldown check is free,
        // while isTakeoverRequestCreate ends in a billed read of the parent
        // signal. Written the other way round, every withdrawal and every
        // in-cooldown retry — exactly the traffic the cooldown exists to make
        // cheap — pays for that read before being answered.
        allow update: if isTakeoverWithdraw(requesterId)
                      || (isAfterReaskCooldown()
                          && isTakeoverRequestCreate('signals', signalId, requesterId));
        // Reporter only, for the delete-signal cascade — a subcollection left
        // behind when the parent goes is orphaned forever. The REQUESTER has no
        // delete: withdrawing is isTakeoverWithdraw() above, because a delete
        // would free the uid slot and walk straight past the cooldown.
        //
        // The third of the three cascade-only deletes #68 retires; see the
        // events block above for why the flip waits on an app release. The
        // requester's own side of this rule is unaffected and stays as it is.
        allow delete: if request.auth != null
                      && isParentSignalReporter('signals', signalId);
      }
    }

    // Test signals collection - same rules as signals
    match /signals_test/{signalId} {
      allow read: if true;
      allow create: if isSignalCreate();
      // Same rules as prod signals (see helpers above).
      allow update: if request.auth != null
                    && isValidUrgency()
                    && isValidHelpNeededTags()
                    && isValidAnimalType()
                    && isValidSignalContentBounds()
                    && isNotTouchingModeration()
                    && isNotTouchingOwnership()
                    && isValidOwnerStamp()
                    && (isSignalReporter() || isSignalOwnerUpdate());
      allow delete: if request.auth != null && isSignalReporter();

      match /comments/{commentId} {
        allow read: if true;
        allow create: if isCommentCreate('signals_test', signalId);
        allow delete: if request.auth != null
                      && isParentSignalReporter('signals_test', signalId);
      }

      match /events/{eventId} {
        allow read: if true;
        allow create: if isSignalEventCreate();
        allow update: if false;
        // Retired with its production twin — see the #68 deploy-order note there.
        allow delete: if request.auth != null
                      && isParentSignalReporter('signals_test', signalId);
      }

      match /takeoverRequests/{requesterId} {
        allow read: if request.auth != null;
        allow create: if isTakeoverRequestCreate('signals_test', signalId, requesterId);
        // Ordered cheapest-first, the same convention isModerator() documents:
        // withdrawing needs no get() at all, and the cooldown check is free,
        // while isTakeoverRequestCreate ends in a billed read of the parent
        // signal. Written the other way round, every withdrawal and every
        // in-cooldown retry — exactly the traffic the cooldown exists to make
        // cheap — pays for that read before being answered.
        allow update: if isTakeoverWithdraw(requesterId)
                      || (isAfterReaskCooldown()
                          && isTakeoverRequestCreate('signals_test', signalId, requesterId));
        allow delete: if request.auth != null
                      && isParentSignalReporter('signals_test', signalId);
      }
    }

    // Allow collection group queries for comments
    match /{path=**}/comments/{commentId} {
      allow read: if request.auth != null;
    }

    // Feedback collection - only admins can read (via Admin SDK/Console).
    // Any signed-in caller (incl. the automatic anonymous app sessions) may
    // submit, but (M-2):
    //   - auth is required — no unauthenticated writes; combined with App Check
    //     enforcement this closes the open email/cost-abuse vector.
    //   - userId is pinned to the caller so it can't be spoofed to frame another
    //     user (the email/rate-limit both key off it).
    //   - email, when present, must be a syntactically valid address (also
    //     re-validated in the function before it's used as replyTo).
    // Each accepted write triggers onFeedbackCreated, which sends an email and
    // enforces a per-user rate limit.
    match /feedback/{feedbackId} {
      allow create: if request.auth != null
                    && request.resource.data.userId == request.auth.uid
                    && request.resource.data.message is string
                    && request.resource.data.message.size() > 0
                    && request.resource.data.message.size() <= 1000
                    && request.resource.data.type in ['general', 'bug', 'feature', 'other']
                    && (
                      !('email' in request.resource.data)
                      || request.resource.data.email == null
                      || (request.resource.data.email is string
                          && request.resource.data.email.size() <= 254
                          && request.resource.data.email.matches('^[^@ ]+@[^@ ]+[.][^@ ]+$'))
                    );
      allow read, update, delete: if false;  // Only accessible via Admin SDK/Console
    }

    // ---------------------------------------------------------------------
    // Moderation (master spec 3.6.1, 18)
    // ---------------------------------------------------------------------

    // The moderator roster. `{ grantedAt, grantedBy, note? }`.
    //
    // Granted and revoked ONLY by `functions/scripts/grant_moderator.js` via
    // the Admin SDK. No client write path exists — not even a moderator's, and
    // least of all the subject's own, which is what stops self-promotion.
    //
    // `get` on your own document is allowed so the app can decide whether to
    // draw the moderation entry point. `list` is denied for the same reason as
    // publicProfiles: the roster is exactly the list an attacker would want, to
    // know whom to target.
    match /moderators/{userId} {
      allow get: if request.auth != null && request.auth.uid == userId;
      allow list: if false;
      allow create, update, delete: if false;
    }

    // User-submitted reports (master spec 18.1).
    //
    // The document id is `{reporterUid}_{targetType}_{targetId}` and THAT is
    // the rate limit: `create` is allowed, `update` is not, so a second report
    // of the same target by the same user collides with the existing document
    // and is denied. One report per user per target, with no throttle
    // collection to maintain (contrast feedbackThrottle, which throttles an
    // email rather than a write).
    //
    // Reads are moderator-only. A reporter cannot read their own report back —
    // deliberate, per spec 18.7: internal moderation records are not visible to
    // users, and a report carries an accusation about someone else.
    match /reports/{reportId} {
      allow get, list: if isModerator();
      allow create: if isReportCreate(reportId);
      // Status transitions run through the moderation callables so that every
      // one leaves an audit entry. A direct client write would not.
      allow update, delete: if false;
    }

    // Pins the reporter to the caller (no framing someone else), pins the
    // opening status, and bounds every field.
    //
    // `reason` is bounded but NOT checked against an allow-list, for the same
    // reason as isValidHelpNeededTags: a newer client may know a code this
    // deployed ruleset has never heard of, and rejecting it would break the new
    // build rather than the old one. An unrecognised reason still reaches a
    // moderator, who can read `details`.
    //
    // The id check is what makes the one-per-target limit real — without it a
    // client could write the same report under a fresh random id forever.
    function isReportCreate(reportId) {
      return request.auth != null
             && request.resource.data.keys().hasOnly([
                  'targetType', 'targetId', 'signalId', 'collection',
                  'reason', 'details', 'reporterId', 'reportedUserId',
                  'status', 'testMode', 'createdAt'
                ])
             && request.resource.data.targetType in ['signal', 'comment', 'user']
             && request.resource.data.targetId is string
             && request.resource.data.targetId.size() > 0
             && request.resource.data.targetId.size() <= 200
             && request.resource.data.reporterId == request.auth.uid
             // Ordered AFTER the type checks above: this concatenates the two
             // fields, and doing that to a non-string errors the whole rule.
             && reportId == request.auth.uid + '_'
                            + request.resource.data.targetType + '_'
                            + request.resource.data.targetId
             && request.resource.data.collection in ['signals', 'signals_test']
             && request.resource.data.reason is string
             && request.resource.data.reason.size() > 0
             && request.resource.data.reason.size() <= 64
             && request.resource.data.details is string
             && request.resource.data.details.size() <= 1000
             && request.resource.data.status == 'open'
             // `testMode` is derived from `collection`, not independent of it.
             // Validated separately, a patched client could file
             // `{collection: 'signals', testMode: true}` — a report against a
             // PRODUCTION signal that lands in the test queue, where no
             // production moderator is looking. Tying them together is what
             // makes the queue's testMode filter mean what it says.
             && request.resource.data.testMode
                == (request.resource.data.collection == 'signals_test')
             && request.resource.data.createdAt is timestamp
             && (!('signalId' in request.resource.data)
                 || (request.resource.data.signalId is string
                     && request.resource.data.signalId.size() <= 200))
             && (!('reportedUserId' in request.resource.data)
                 || (request.resource.data.reportedUserId is string
                     && request.resource.data.reportedUserId.size() <= 200));
    }

    // Audit trail of every moderator action (master spec 18.7).
    //
    // Written exclusively by the moderation callables through the Admin SDK,
    // which is the entire point of routing actions through functions instead of
    // widening these rules: a client-written audit log is a forgeable one.
    // Readable by moderators so the queue can show what has already been done
    // to a signal.
    match /moderationActions/{actionId} {
      allow get, list: if isModerator();
      allow create, update, delete: if false;
    }

    // Quarantined signals — where a hidden signal's document goes.
    //
    // NO client match on purpose: denied by default, to every caller,
    // moderators included. Hiding therefore makes a signal genuinely
    // unreadable rather than merely filtered out of the map, which a plain
    // `hidden: true` field could never do while `signals` stays publicly
    // readable.
    //
    //     match /moderationQuarantine/{id}   <- intentionally absent
    //
    // Note that only the signal DOCUMENT moves. Its `comments` and `events`
    // subcollections stay where they are (Firestore keeps subcollections when a
    // document is deleted), which is what makes a restore lossless — and also
    // means those remain publicly readable to anyone holding the signal id.
    // Recorded in docs/SPECIFICATION.md §14.

    // Removed signals — where a signal its own REPORTER took down goes (#68).
    //
    // The same move-not-a-flag shape as quarantine above, and a separate
    // collection for three reasons: these expire after
    // REMOVED_RETENTION_DAYS and quarantine does not, the reporter restores
    // these where only a moderator restores quarantine, and `listQuarantined`
    // is a 50-item moderator worklist that ordinary removals would swamp.
    //
    // Unlike quarantine, this one IS readable — but only by the person whose
    // signal it is. Quarantine is denied to everyone because its whole purpose
    // is withholding content from readers; a removal is the opposite, content
    // its own author put in the bin, and they have to be able to see what is in
    // there to get it back out. Everyone else, moderators included, is denied
    // here and reads the projected summary through `listQuarantined` instead.
    //
    // `list` works because My Signals queries this filtered by
    // `data.reporter`, so every document the query can return already
    // satisfies the rule. A query without that filter is denied outright,
    // which is the point.
    //
    // Writes are server-only. `signalRemoval` moves documents in and out
    // through the Admin SDK, exactly like the moderation callables — a client
    // that could write here could restore a signal without the fan-out guard,
    // or forge one that was never theirs.
    match /removedSignals/{removalId} {
      allow get, list: if request.auth != null
                       && resource.data.data.reporter == userDoc();
      allow create, update, delete: if false;
    }
  }
}