rsc-universal 0.1.1

package/skills/firebase/references/data-modeling.md

@@ -0,0 +1,108 @@
+# Data modeling — denormalization, sharding, pagination, indexes
+
+Firestore is a NoSQL document store. You pay for and wait on reads, so the unit of design is the read
+path, not the normalized entity. No joins exist; you either denormalize or you fan out.
+
+## Denormalization and fan-out
+
+Copy the few fields a screen needs onto the document that screen reads, and update the copies on
+write. Example: a feed shows `authorName` next to each post.
+
+```ts
+// Write path keeps the copy in sync (a small batch, or a Cloud Function on the user doc).
+const batch = writeBatch(db);
+batch.set(doc(db, "posts", postId), { authorId, authorName: user.displayName, body });
+await batch.commit();
+```
+
+Fan-out write: when one event must appear in many places (a message into every member's inbox), write
+N documents in a batch (max 500 ops) or trigger a Cloud Function to do the fan-out asynchronously.
+
+## Sharded counters
+
+A single document tolerates ~1 sustained write/sec. A "likes" counter on a viral post will exceed
+that. Spread writes across N shard docs and sum on read.
+
+```ts
+const N = 10;
+// increment a random shard
+await updateDoc(doc(db, "posts", postId, "shards", String(Math.floor(Math.random() * N))), {
+  count: increment(1),
+});
+// read = sum of shards
+const shards = await getDocs(collection(db, "posts", postId, "shards"));
+const total = shards.docs.reduce((s, d) => s + d.data().count, 0);
+```
+
+Pick N to cover peak writes/sec (each shard absorbs ~1/sec).
+
+## Avoiding hotspots
+
+Sequential IDs and monotonically increasing indexed fields (auto-increment, `Date.now()` written to an
+indexed field at high rate) concentrate writes on one index range. Use Firestore's scattered auto-IDs
+(`addDoc` / `doc(collection(db,'x'))`), and if you must index a timestamp at high write rate, add a
+sharding prefix to spread the index.
+
+## Pagination with cursors
+
+Don't use numeric offsets (Firestore still reads the skipped docs). Use cursors.
+
+```ts
+const first = query(collection(db, "posts"), orderBy("createdAt", "desc"), limit(20));
+const snap = await getDocs(first);
+const last = snap.docs[snap.docs.length - 1];
+const next = query(collection(db, "posts"), orderBy("createdAt", "desc"), startAfter(last), limit(20));
+```
+
+## Aggregation
+
+For counts/sums without reading every doc, use server-side aggregation:
+
+```ts
+import { getCountFromServer } from "firebase/firestore";
+const c = await getCountFromServer(query(collection(db, "posts"), where("ownerId", "==", uid)));
+c.data().count; // billed as a small number of reads, not one-per-doc
+```
+
+## Collection-group queries
+
+To query the same-named subcollection across all parents (every `messages` subcollection at once):
+
+```ts
+import { collectionGroup } from "firebase/firestore";
+const recent = query(collectionGroup(db, "messages"), orderBy("createdAt", "desc"), limit(50));
+```
+
+This needs a collection-group composite index (declared in `firestore.indexes.json`) and Rules that
+match the subcollection path with a wildcard.
+
+## Composite index design
+
+A query that filters/ranges on one field and orders by another needs a composite index. Firestore's
+error in production gives you a one-click link to create it, but you should commit it to source.
+
+```json
+{
+  "indexes": [
+    {
+      "collectionGroup": "posts",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "ownerId", "order": "ASCENDING" },
+        { "fieldPath": "createdAt", "order": "DESCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": []
+}
+```
+
+Deploy with `firebase deploy --only firestore:indexes`. The emulator runs queries without these
+indexes, so "works locally, fails in prod with *requires an index*" is the expected gap — keep this
+file in sync and deploy it before shipping new queries.
+
+## Query constraint caps
+
+- `in`, `not-in`, `array-contains-any`: up to ~30 values per query.
+- A single range/inequality filter applies to one field; combine with other filters via composite
+  indexes. There is no `OR` across different fields without `or()` + the matching indexes.

package/skills/firebase/references/security-rules.md

@@ -0,0 +1,137 @@
+# Security Rules — CEL patterns and testing
+
+Firestore/Storage Security Rules are written in CEL. They are evaluated server-side on every direct
+client request, and they are the access-control layer — there is no app server in the trust path by
+default. Rules are **not** query filters: a query is rejected entirely unless the rules can prove
+every matched document is allowed.
+
+## Structure and granular methods
+
+```javascript
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /posts/{postId} {
+      // read  = get + list ; write = create + update + delete
+      allow get:    if isOwner();
+      allow list:   if request.auth != null;   // pair with a constrained query
+      allow create: if isValidNewPost();
+      allow update: if isOwner() && ownerUnchanged();
+      allow delete: if isOwner();
+    }
+  }
+}
+```
+
+Split `get` from `list` and `create` from `update` so a permissive query path can't leak documents a
+single-doc read would block, and so create-time validation differs from edit-time validation.
+
+## Reusable functions
+
+```javascript
+function signedIn()  { return request.auth != null; }
+function isOwner()   { return signedIn() && resource.data.ownerId == request.auth.uid; }
+function isAdmin()   { return signedIn() && request.auth.token.admin == true; } // custom claim
+function ownerUnchanged() {
+  return request.resource.data.ownerId == resource.data.ownerId; // immutable field
+}
+```
+
+- `resource.data` = the existing stored document.
+- `request.resource.data` = the incoming write (what the doc will become).
+- `request.auth.uid` = authenticated user id; `request.auth.token.<claim>` = custom claims.
+
+## RBAC via custom claims
+
+Custom claims are the cheapest role check — they live in the token, so no extra read.
+
+```javascript
+match /admin/{doc=**} {
+  allow read, write: if isAdmin();
+}
+```
+
+Set them server-side only:
+
+```ts
+import { getAuth } from "firebase-admin/auth";
+await getAuth().setCustomUserClaims(uid, { admin: true, plan: "pro" });
+// Claims refresh on the client's next ID-token refresh, not instantly.
+```
+
+## Cross-document checks with get() / exists()
+
+When the role lives in another document rather than a claim:
+
+```javascript
+function memberRole(orgId) {
+  return get(/databases/$(database)/documents/orgs/$(orgId)/members/$(request.auth.uid)).data.role;
+}
+match /orgs/{orgId}/projects/{projectId} {
+  allow write: if memberRole(orgId) in ['owner', 'editor'];
+}
+```
+
+Each `get()`/`exists()` is a billed read and counts against the rule-evaluation lookup limit per
+request — keep them shallow and prefer custom claims for hot paths.
+
+## Write validation
+
+```javascript
+allow create: if signedIn()
+  && request.resource.data.ownerId == request.auth.uid          // can't forge ownership
+  && request.resource.data.keys().hasOnly(['title','body','ownerId','createdAt'])
+  && request.resource.data.title is string
+  && request.resource.data.title.size() < 200
+  && request.resource.data.createdAt == request.time;           // server-stamped
+```
+
+`hasOnly` blocks privilege-escalation fields a client might smuggle in.
+
+## Time-based throttling
+
+```javascript
+// Allow a write only if the last one on this doc was > 60s ago.
+allow update: if request.time > resource.data.lastWrite + duration.value(60, 's');
+```
+
+## Testing with @firebase/rules-unit-testing
+
+This is the only library that can mock `request.auth` against the emulator. Run it under the emulator.
+
+```ts
+import { initializeTestEnvironment, assertFails, assertSucceeds } from "@firebase/rules-unit-testing";
+import { setDoc, getDoc, doc } from "firebase/firestore";
+import { readFileSync } from "node:fs";
+
+const env = await initializeTestEnvironment({
+  projectId: "demo-test",
+  firestore: { rules: readFileSync("firestore.rules", "utf8") },
+});
+
+const alice = env.authenticatedContext("alice").firestore();
+const bob   = env.authenticatedContext("bob").firestore();
+
+// owner can write their own post
+await assertSucceeds(setDoc(doc(alice, "posts/p1"), { ownerId: "alice", title: "hi" }));
+// someone else cannot read it
+await assertFails(getDoc(doc(bob, "posts/p1")));
+// unauthenticated is denied
+await assertFails(getDoc(doc(env.unauthenticatedContext().firestore(), "posts/p1")));
+
+await env.cleanup();
+```
+
+Run it: `firebase emulators:exec --only firestore "npm test"`.
+
+## Reading firestore-debug.log
+
+When a rule denies a request you didn't expect, the Firestore emulator writes the evaluated
+expression and the deny reason to `firestore-debug.log` in the project root. Grep it for the
+collection path to see which `allow` failed and which variable was null.
+
+## App Check
+
+App Check attests that a request originated from your genuine app (reCAPTCHA Enterprise on web, Play
+Integrity on Android, App Attest on iOS) **before** Rules even evaluate. Enforce it in production so
+Rules only ever run for legitimate clients, not scrapers or scripts hitting the REST API directly.

package/skills/firebase/scripts/verify.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — firebase skill gate. Run from your PROJECT root.
+#
+# What it does (read-only, idempotent, never writes):
+#   1. Locates firestore.rules / storage.rules. FAILS if a rules file exists but is empty, or if it
+#      carries an open catch-all (`allow read, write: if true;` — any whitespace, with read/write in
+#      either order, or a bare `allow read: if true;` / `allow write: if true;`).
+#   2. Validates firestore.indexes.json parses as JSON when present (uses node, python3, or jq —
+#      whichever exists; skips the parse if none do).
+#   3. If the Firebase CLI is present, prints the advisory rules-test path (firebase emulators:exec).
+#
+# Exit code: non-zero ONLY on a hard failure (open/empty rules, malformed indexes JSON). Missing
+# tools and missing Firebase artifacts are skips, never failures. An empty/clean repo exits 0.
+#
+# Portability: stock macOS bash 3.2 — no mapfile, no associative arrays; arrays are initialised so
+# they expand safely under `set -u`.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+ROOT="$(pwd)"
+
+# ---- 1. Discover rules files ----
+RULES_FILES=()
+while IFS= read -r -d '' f; do
+  RULES_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' -o -path '*/dist/*' \) -prune -o \
+    -type f \( -name 'firestore.rules' -o -name 'storage.rules' -o -name '*.rules' \) -print0 2>/dev/null
+)
+
+if [ "${#RULES_FILES[@]}" -eq 0 ]; then
+  skip "no *.rules files found — not a Firebase project (or rules not in this tree). Nothing to lint."
+else
+  for f in "${RULES_FILES[@]}"; do
+    # strip comments so an example/comment doesn't trip the catch-all check
+    body="$(sed -E 's://.*$::' "$f" 2>/dev/null | tr -d '\r' || true)"
+    if [ -z "$(printf '%s' "$body" | tr -d '[:space:]')" ]; then
+      err "$f: rules file is empty — that is fail-open at deploy time"
+      continue
+    fi
+    # open catch-all: allow [read|write|read, write|write, read] : if true ;
+    if printf '%s' "$body" | grep -Eiq 'allow[[:space:]]+(read|write)([[:space:]]*,[[:space:]]*(read|write))?[[:space:]]*:[[:space:]]*if[[:space:]]+true[[:space:]]*;'; then
+      err "$f: contains an open rule (allow ...: if true;) — the database is open to the internet. Scope it to request.auth + ownership."
+    else
+      ok "$f: no open 'if true' catch-all"
+    fi
+  done
+fi
+
+# ---- 2. Validate firestore.indexes.json ----
+INDEX_FILES=()
+while IFS= read -r -d '' f; do
+  INDEX_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' \) -prune -o \
+    -type f -name 'firestore.indexes.json' -print0 2>/dev/null
+)
+
+if [ "${#INDEX_FILES[@]}" -eq 0 ]; then
+  skip "no firestore.indexes.json found — skipping index JSON validation."
+else
+  parse_json() {
+    if command -v jq >/dev/null 2>&1; then jq -e . "$1" >/dev/null 2>&1; return $?; fi
+    if command -v node >/dev/null 2>&1; then node -e 'JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"))' "$1" >/dev/null 2>&1; return $?; fi
+    if command -v python3 >/dev/null 2>&1; then python3 -c 'import json,sys; json.load(open(sys.argv[1]))' "$1" >/dev/null 2>&1; return $?; fi
+    return 2
+  }
+  for f in "${INDEX_FILES[@]}"; do
+    if parse_json "$f"; then
+      ok "$f: valid JSON"
+    elif [ $? -eq 2 ]; then
+      skip "$f: no JSON parser (jq/node/python3) available — skipping validation"
+    else
+      err "$f: malformed JSON — firebase deploy --only firestore:indexes will reject it"
+    fi
+  done
+fi
+
+# ---- 3. Advisory: rules unit testing ----
+if command -v firebase >/dev/null 2>&1; then
+  note "Firebase CLI found. Run rules tests with: firebase emulators:exec --only firestore \"npm test\""
+  note "Reminder: the emulator does NOT enforce composite indexes — keep firestore.indexes.json in sync and deploy it."
+else
+  skip "firebase CLI not installed — skipping the emulator rules-test hint."
+fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found failures"; fi
+exit "$EXIT"