zach/Onsol-GO
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
St. Nebula
2026-04-23 23:58:59 -05:00
commit 47b9e3c159
257 changed files with 18913 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/firebase-firestore-enterprise-native-mode/references/data_model.md
+54
View File
@@ -0,0 +1,54 @@
# Firestore Data Model Reference
Firestore is a NoSQL, document-oriented database. Unlike a SQL database, there are no tables or rows. Instead, you store data in **documents**, which are organized into **collections**.
## Document Data Model
Data in Firestore is organized into documents, collections, and subcollections.
### Documents
A **document** is a lightweight record that contains fields, which map to values. Each document is identified by a name. A document can contain complex nested objects in addition to basic data types like strings, numbers, and booleans. Documents are limited to a maximum size of 1 MiB.
Example document (e.g., in a `users` collection):
```json
{
"first": "Ada",
"last": "Lovelace",
"born": 1815
}
```
### Collections
Documents live in **collections**, which are containers for your documents. For example, you could have a `users` collection to contain your various users, each represented by a document.
* Collections can only contain documents. They cannot directly contain raw fields with values, and they cannot contain other collections.
* Documents within a collection can contain different fields.
* You don't need to "create" or "delete" collections explicitly. After you create the first document in a collection, the collection exists. If you delete all of the documents in a collection, the collection no longer exists.
### Subcollections
Documents can contain subcollections natively. A subcollection is a collection associated with a specific document.
For example, a user document in the `users` collection could have a `messages` subcollection containing message documents exclusively for that user. This creates a powerful hierarchical data structure.
Data path example: `users/user1/messages/message1`
## Collection Group Support
A **collection group** consists of all collections with the same ID. By default, queries retrieve results from a single collection in your database. Use a collection group query to retrieve documents from a collection group instead of from a single collection.
### Use Cases
Collection group queries are useful when you want to query across multiple subcollections that share the same organizational structure.
For example, imagine an app with a `landmarks` collection where each landmark has a `reviews` subcollection. If you want to find all 5-star reviews across *all* landmarks, it would involve checking many separate `reviews` subcollections. With a collection group, you can perform a single query against the `reviews` collection group.
### Examples
**Standard Query** (Single Collection):
Find all 5-star reviews for a specific landmark.
```javascript
db.collection('landmarks/golden_gate_bridge/reviews').where('rating', '==', 5)
```
**Collection Group Query**:
Find all 5-star reviews across *all* landmarks.
```javascript
db.collectionGroup('reviews').where('rating', '==', 5)
```
.agents/skills/firebase-firestore-enterprise-native-mode/references/indexes.md
+111
View File
@@ -0,0 +1,111 @@
# Firestore Indexes Reference
Indexes helps to improve query performance. Firestore Enterprise edition does not create any indexes by default. By default, Firestore Enterprise performs a full collection scan to find documents that match a query, which can be slow and expensive for large collections. To avoid this, you can create indexes to optimize your queries.
## Index Structure
An index consists of the following:
* a collection ID.
* a list of fields in the given collection.
* an order, either ascending or descending, for each field.
### Index Ordering
The order and sort direction of each field uniquely defines the index. For example, the following indexes are two distinct indexes and not interchangeable:
* Field name `name` (ascending) and `population` (descending)
* Field name `name` (descending) and `population` (ascending)
### Index Density
Dense indexes: By default, Firestore indexes store data from all documents in a collection. An index entry will be added for a document regardless of whether the document contains any of the fields specified in the index. Non-existent fields are treated as having a NULL value when generating index entries.
Sparse indexes: To change this behavior, you can define the index as a sparse index. A sparse index indexes only the documents in the collection that contain a value (including null) for at least one of the indexed fields. A sparse index reduces storage costs and can improve performance.
### Unique Indexes
You can use unique index option to enforce unique values for the indexed fields. For indexes on multiple fields, each combination of values must be unique across the index. The database rejects any update and insert operations that attempt to create index entries with duplicate values.
## Query Support Examples
| Query Type | Index Required |
| :--- | :--- |
| **Simple Equality**<br>`where("a", "==", 1)` | Single-Field Index on field `a` |
| **Simple Range/Sort**<br>`where("a", ">", 1).orderBy("a")` | Single-Field Index on field `a` |
| **Multiple Equality**<br>`where("a", "==", 1).where("b", "==", 2)` | Single-Field Index on field `a` and `b` |
| **Equality + Range/Sort**<br>`where("a", "==", 1).where("b", ">", 2)` | **Composite Index** on field `a` and `b` |
| **Multiple Ranges**<br>`where("a", ">", 1).where("b", ">", 2)` | **Composite Index** on field `a` and `b` |
| **Array Contains + Equality**<br>`where("tags", "array-contains", "news").where("active", "==", true)` | **Composite Index** on field `tags` and `active` |
If no indexes is present, Firestore Enterprise will perform a full collection scan to find documents that match a query.
## Management
### Config files
Your indexes should be defined in `firestore.indexes.json` (pointed to by `firebase.json`).
Define a dense index:
```json
{
"indexes": [
{
"collectionGroup": "cities",
"queryScope": "COLLECTION",
"density": "DENSE",
"fields": [
{ "fieldPath": "country", "order": "ASCENDING" },
{ "fieldPath": "population", "order": "DESCENDING" }
]
}
],
"fieldOverrides": []
}
```
Define a sparse-any index:
```json
{
"indexes": [
{
"collectionGroup": "cities",
"queryScope": "COLLECTION",
"density": "SPARSE_ANY",
"fields": [
{ "fieldPath": "country", "order": "ASCENDING" },
{ "fieldPath": "population", "order": "DESCENDING" }
]
}
],
"fieldOverrides": []
}
```
Define a unique index:
```json
{
"indexes": [
{
"collectionGroup": "cities",
"queryScope": "COLLECTION",
"density": "SPARSE_ANY",
"unique": true,
"fields": [
{ "fieldPath": "country", "order": "ASCENDING" },
{ "fieldPath": "population", "order": "DESCENDING" }
]
}
],
"fieldOverrides": []
}
```
### CLI Commands
Deploy indexes only:
```bash
npx firebase-tools@latest -y deploy --only firestore:indexes
```
.agents/skills/firebase-firestore-enterprise-native-mode/references/provisioning.md
+101
View File
@@ -0,0 +1,101 @@
# Provisioning Firestore Enterprise Native Mode
## Manual Initialization
Initialize the following firebase configuration files manually. Do not use `npx -y firebase-tools@latest init`, as it expects interactive inputs.
1. **Create a Firestore Enterprise Database**: Create a Firestore Enterprise database using the Firebase CLI.
2. **Create `firebase.json`**: This file contains database configuration for the Firebase CLI.
3. **Create `firestore.rules`**: This file contains your security rules.
4. **Create `firestore.indexes.json`**: This file contains your index definitions.
### 1. Create a Firestore Enterprise Database
Use the following command to create a Firestore Enterprise database:
```bash
firebase firestore:databases:create my-database-id \
--location="nam5" \
--edition="enterprise" \
--firestore-data-access="ENABLED" \
--mongodb-compatible-data-access="DISABLED"
```
This will create an enterprise database in `nam5` with native mode enabled. A database id is required to create an enterprise database and the database id must not be `(default)`. To enable realtime-updates feature, use `--realtime-updates` flag.
```bash
firebase firestore:databases:create my-database-id \
--location="nam5" \
--edition="enterprise" \
--firestore-data-access="ENABLED" \
--mongodb-compatible-data-access="DISABLED" \
--realtime-updates="ENABLED"
```
### 2. Create `firebase.json`
Create a file named `firebase.json` in your project root with the following content. If this file already exists, instead append to the existing JSON:
```json
{
"firestore": {
"rules": "firestore.rules",
"indexes": "firestore.indexes.json",
"edition": "enterprise",
"database": "my-database-id",
"location": "nam5"
}
}
```
### 2. Create `firestore.rules`
Create a file named `firestore.rules`. A good starting point (locking down the database) is:
```
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
allow read, write: if false;
}
}
}
```
*See [security_rules.md](security_rules.md) for how to write actual rules.*
### 3. Create `firestore.indexes.json`
Create a file named `firestore.indexes.json` with an empty configuration to start:
```json
{
"indexes": [],
"fieldOverrides": []
}
```
*See [indexes.md](indexes.md) for how to configure indexes.*
## Deploy rules and indexes
```bash
# To deploy all rules and indexes
firebase deploy --only firestore
# To deploy just rules
firebase deploy --only firestore:rules
# To deploy just indexes
firebase deploy --only firestore:indexes
```
## Local Emulation
To run Firestore locally for development and testing:
```bash
firebase emulators:start --only firestore
```
This starts the Firestore emulator, typically on port 8080. You can interact with it using the Emulator UI (usually at http://localhost:4000/firestore).
.agents/skills/firebase-firestore-enterprise-native-mode/references/python_sdk_usage.md
+126
View File
@@ -0,0 +1,126 @@
# Python SDK Usage
The Python Server SDK is used for backend/server environments and utilizes Google Application Default Credentials in most Google Cloud environments.
### Writing Data
#### Set a Document
Creates a document if it does not exist or overwrites it if it does. You can also specify a merge option to only update provided fields.
```python
city_ref = db.collection("cities").document("LA")
# Create/Overwrite
city_ref.set({
"name": "Los Angeles",
"state": "CA",
"country": "USA"
})
# Merge
city_ref.set({"population": 3900000}, merge=True)
```
#### Add a Document with Auto-ID
Use when you don't care about the document ID and want Firestore to automatically generate one.
```python
update_time, city_ref = db.collection("cities").add({
"name": "Tokyo",
"country": "Japan"
})
print("Document written with ID: ", city_ref.id)
```
#### Update a Document
Update some fields of an existing document without overwriting the entire document. Fails if the document doesn't exist.
```python
city_ref = db.collection("cities").document("LA")
city_ref.update({
"capital": True
})
```
#### Transactions
Perform an atomic read-modify-write operation.
```python
from google.cloud.firestore import Transaction
transaction = db.transaction()
city_ref = db.collection("cities").document("SF")
@firestore.transactional
def update_in_transaction(transaction, city_ref):
snapshot = city_ref.get(transaction=transaction)
if not snapshot.exists:
raise Exception("Document does not exist!")
new_population = snapshot.get("population") + 1
transaction.update(city_ref, {"population": new_population})
update_in_transaction(transaction, city_ref)
```
### Reading Data
#### Get a Single Document
```python
doc_ref = db.collection("cities").document("SF")
doc = doc_ref.get()
if doc.exists:
print(f"Document data: {doc.to_dict()}")
else:
print("No such document!")
```
#### Get Multiple Documents
Fetches all documents in a query or collection once.
```python
docs = db.collection("cities").stream()
for doc in docs:
print(f"{doc.id} => {doc.to_dict()}")
```
### Queries
#### Simple and Compound Queries
Use `.where()` to combine filters safely. Stack `.where()` calls for compound queries.
```python
from google.cloud.firestore import FieldFilter
cities_ref = db.collection("cities")
# Simple equality
query_1 = cities_ref.where(filter=FieldFilter("state", "==", "CA"))
# Compound (AND)
query_2 = cities_ref.where(
filter=FieldFilter("state", "==", "CA")
).where(
filter=FieldFilter("population", ">", 1000000)
)
```
#### Order and Limit
Sort and limit results cleanly.
```python
query = cities_ref.order_by("name").limit(3)
```
#### Pipeline Queries
You can use pipeline queries to perform complex queries.
```python
pipeline = client.pipeline().collection("users")
for result in pipeline.execute():
print(f"{result.id} => {result.data()}")
```
.agents/skills/firebase-firestore-enterprise-native-mode/references/security_rules.md
+414
View File
@@ -0,0 +1,414 @@
## 1. Generate Firestore Rules
You are an expert Firebase Security Rules engineer with deep knowledge of Firestore security best practices. Your task is to generate comprehensive, secure Firebase Security rules for the user's project. To minimize the risk of security incidents and avoid misleading the user about the security of their application, you must be extremely humble about the rules you generate. Always present the rules you've written as a prototype that needs review.
After generating the rules, you MUST explicitly communicate to the user exactly like this:
"I've set up prototype Security Rules to keep the data in Firestore safe. They are designed to be secure for <explain reasons here>. However, you should review and verify them before broadly sharing your app. If you'd like, I can help you harden these rules."
### Workflow
Follow this structured workflow strictly:
#### Phase-1: Codebase Analysis
1. **Scan the entire codebase** to identify:
- Programming language(s) used (for understanding context only)
- All Firestore collection and document paths
- **All Firestore Queries:** Identify every `where()`, `orderBy()`, and `limit()` clause. The security rules **MUST** allow these specific queries.
- Data models and schemas (interfaces, classes, types)
- Data types for each field (strings, numbers, booleans, timestamps, URLs, emails, etc.)
- Required vs. optional fields
- Field constraints (min/max length, format patterns, allowed values)
- CRUD operations (create, read, update, delete)
- Authentication patterns (Firebase Auth, custom tokens, anonymous)
- Access patterns and business logic rules
2. **Document your findings** in a untracked file. Refer to this file when generating the security rules.
#### Phase-2: Security Rules Generation
**CRITICAL**: Follow the following principles **every time you modify the security rules file**
Generate Firebase Security Rules following these principles:
- **Default deny:** Start with denying all access, then explicitly allow only what's needed
- **Least privilege:** Grant minimum permissions required
- **Validate data:** Check data types, allowed fields, and constraints on both creates and updates.
- **MANDATORY:** You **MUST** use the **Validator Function Pattern** described in the "Critical Directives" section below. This involves defining a specific validation function (e.g., `isValidUser`) and calling it in **BOTH** `create` and `update` rules.
- **MANDATORY:** For **ALL** creates **AND ALL** updates, ensure that after the operation, the required fields are still available and that the data is valid.
- **Authentication checks:** Verify user identity before granting access
- **Authorization logic:** Implement role-based or ownership-based access control
- **UID Protection:** Prevent users from changing ownership of data
- **Initially restricted:** Never make any collection or data publicly readable, always require authentication for any access to data unless
the user makes an *explicit* request for unauthenticated data.
This means the first firestore.rules file you generate must never have any "allow read: true" statements.
**Structure Requirements:**
1. **Document assumed data models at the beginning of the rules file:**
```javascript
// ===============================================================
// Assumed Data Model
// ===============================================================
//
// This security rules file assumes the following data structures:
//
// Collection: [name]
// Document ID: [pattern]
// Fields:
// - field1: type (required/optional, constraints) - description
// - field2: type (required/optional, constraints) - description
// [List all fields with types, constraints, and whether immutable]
//
// [Repeat for all collections]
//
// ===============================================================
```
2. **Include comprehensive helper functions to avoid repetition:**
```javascript
// ===============================================================
// Helper Functions
// ===============================================================
//
// Check if the user is authenticated
function isAuthenticated() {
return request.auth != null;
}
//
// Check if user owns the resource (for user-owned documents)
function isOwner(userId) {
return isAuthenticated() && request.auth.uid == userId;
}
//
// Check if user is owner based on document's uid field
function isDocOwner() {
return isAuthenticated() && request.auth.uid == resource.data.uid;
}
//
// Verify UID hasn't been tampered with on create
function uidUnchanged() {
return !('uid' in request.resource.data) ||
request.resource.data.uid == request.auth.uid;
}
//
// Ensure uid field is not modified on update
function uidNotModified() {
return !('uid' in request.resource.data) ||
request.resource.data.uid == resource.data.uid;
}
//
// Validate required fields exist
function hasRequiredFields(fields) {
return request.resource.data.keys().hasAll(fields);
}
//
// Validate string length
function validStringLength(field, minLen, maxLen) {
return request.resource.data[field] is string &&
request.resource.data[field].size() >= minLen &&
request.resource.data[field].size() <= maxLen;
}
//
// Validate URL format (must start with https:// or http://)
function isValidUrl(url) {
return url is string &&
(url.matches("^https://.*") || url.matches("^http://.*"));
}
//
// Validate email format
function isValidEmail(email) {
return email is string &&
email.matches("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$");
}
//
// Validate ISO 8601 date string format (YYYY-MM-DDTHH:MM:SS)
// CRITICAL: This validates format ONLY, not logical date values (e.g., month 13).
// Use the 'timestamp' type for documents where logical date validation is required.
function isValidDateString(dateStr) {
return dateStr is string &&
dateStr.matches("^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.*Z?$");
}
//
// Validate that a string path is correctly scoped to the user's ID
function isScopedPath(path) {
return path is string && path.matches("^users/" + request.auth.uid + "/.*");
}
//
// Validate that a value is positive
function isPositive(field) {
return request.resource.data[field] is number && request.resource.data[field] > 0;
}
//
// Validate that a list is a list and enforces size limits
function isValidList(list, maxSize) {
return list is list && list.size() <= maxSize;
}
//
// Validate optional string (if present, must be string and within length)
function isValidOptionalString(field, minLen, maxLen) {
return !('field' in request.resource.data) ||
(request.resource.data[field] is string &&
request.resource.data[field].size() >= minLen &&
request.resource.data[field].size() <= maxLen);
}
//
// Validate that a map contains only allowed keys
function isValidMap(mapData, allowedKeys) {
return mapData is map && mapData.keys().hasOnly(allowedKeys);
}
//
// Validate that the document contains only the allowed fields
function hasOnlyAllowedFields(fields) {
return request.resource.data.keys().hasOnly(fields);
}
//
// Validate that the document hasn't changed in the fields that are not allowed to be changed
function areImmutableFieldsUnchanged(fields) {
return !request.resource.data.diff(resource.data).affectedKeys().hasAny(fields);
}
//
// Validate that a timestamp is recent (within the last 5 minutes)
function isRecent(time) {
return time is timestamp &&
time > request.time - duration.value(5, 'm') &&
time <= request.time;
}
//
// [Add more helper functions as needed for the data validation like the example below]
//
// ===============================================================
//
// Domain Validators (CRITICAL: Use these in both create and update)
//
// function isValidUser(data) {
// // Only allow admin to create admin roles
// return hasOnlyAllowedFields(['name', 'email', 'age', 'role']) &&
// data.name is string && data.name.size() > 0 && data.name.size() < 50 &&
// data.email is string && isValidEmail(data.email) &&
// data.age is number && data.age >= 18 &&
// data.role in ['admin', 'user', 'guest'];
// }
```
#### Mandatory: User Data Separation (The "No Mixed Content" Rule)
- Firestore security rules apply to the entire document. You cannot allow users to read the displayName
field while hiding the email field in the same document.
- If a collection (e.g., users) contains ANY PII (email, phone, address, private settings), you MUST
strictly limit read access to the document owner only (allow read: if isOwner(userId);).
- If the application requires public profiles (e.g., showing user names/avatars on posts):
- 1. Denormalization (Preferred): Copy the user's public info (name, photoURL) directly onto the resources
they create (e.g., store authorName and authorPhoto inside the posts document).
- 2. Split Collections: Create a separate users_public collection that contains only non-sensitive data,
and keep the sensitive data in a locked-down users_private collection.
- NEVER write a rule that allows read access to a document containing PII for anyone other than the owner.
#### **CRITICAL** RBAC Guidelines
This is one of the most important set of instructions to follow. Failing to follow these rules will result in catastrophic security vulnerabilities.
- **NEVER** allow users to create their own privileged roles. That means that no user should be able to create an item in a database with their role set to
a role similar to "admin" unless they are already a bootstrapped admin.
- **NEVER** allow users to update their own roles or permissions.
- **NEVER** allow users to grant themselves access to other users' data.
- **NEVER** allow users to bypass the role hierarchy.
- **ALWAYS** validate that the user is authorized to perform the requested action.
- **ALWAYS** validate that the user is not attempting to escalate their privileges.
- **ALWAYS** validate that the user is not attempting to access data they do not have permission to access.
Here's a **bad** example of what **NOT** to do:
```javascript
match /users/{userId} {
// BAD: Allows users to create their own roles because a user can create a new user document with a role of 'admin' and the isAdmin() function will return true
allow create: if (isOwner(userId) && isValidUser(request.resource.data)) || isAdmin();
// BAD: Allows users to update their own roles because a user can update their own user document with a role of 'admin' and the isAdmin() function will return true
allow update: if (isOwner(userId) && isValidUser(request.resource.data)) || isAdmin();
}
```
Here's a **good** example of what **TO** do:
```javascript
match /users/{userId} {
// GOOD: Does NOT allow users to create their own roles unless they are an admin or the user is updating their own role to a less privileged role
allow create: if isAuthenticated() && isValidUser(request.resource.data) && ((isOwner(userId) && request.resource.data.role == 'client') || isAdmin());
// GOOD: Does NOT allow users to update their own roles unless they are an admin
allow update: if isAuthenticated() && isValidUser(request.resource.data) && ((isOwner(userId) && request.resource.data.role == resource.data.role) || isAdmin());
}
```
#### Critical Directives for Secure Generation
- **PREFER USING READ OVER LIST OR GET** `list` and `get` can add complexity to security rules. Prefer using `read` over them.
- **Date and Timestamp Validation:**
- **Prefer Timestamps:** ALWAYS prefer the `timestamp` type for date fields. Firestore automatically ensures they are logically valid dates.
- **String Date Risks:** If using strings for dates (e.g., ISO 8601), a regex check like `isValidDateString` only validates **format**, not **logic** (it would accept Feb 31st).
- **Regex Escaping:** When using regex for digits, you **MUST** use double backslashes (e.g., `\\\\d`) in the rules string. Using a single backslash (`\\d`) is a common bug that causes validation to fail.
- **Immutable Fields:** Fields like `createdAt`, `authorUID`, or any other field that should not change after creation must be explicitly protected in `update` rules. (e.g., `request.resource.data.createdAt == resource.data.createdAt`). **CRITICAL**: When allowing non-owners to update specific fields (like incrementing a counter), you **MUST** explicitly verify that all other fields (e.g., `authorName`, `tags`, `body`) remain unchanged to prevent unauthorized metadata modification. For sensitive fields, ensure that the logged in user is also the owner of the document.
- **Identity Integrity:** When storing denormalized user identity (e.g. `authorName`, `authorPhoto`), you **MUST** validate this data.
- **Prefer Auth Token:** If possible, check if `request.resource.data.authorName == request.auth.token.name`.
- **Strict Validation:** If the auth token is unavailable, you **MUST** strictly validate the type (string) and length (e.g. < 50 chars) to prevent spoofing with massive or malicious payloads.
- **Client-Side Fetching:** The most secure pattern is to store ONLY `authorUid` and fetch the profile client-side. If you denormalize, you accept the risk of stale or spoofed data unless you validate it.
- **Enforce Strict Schema (No Extraneous Fields):** Documents must not contain any fields other than those explicitly defined in the data model. This prevents users from adding arbitrary data.
- **NEVER allow PII EXPOSURE LEAKS:** Never allow PII (Personally Identifiable Information) to be exposed in the data model. This includes email addresses, phone numbers, and any other information that could be used to identify a user. For example, even if a user is logged-in, they should not have access to read another user's information.
- **No Blanket User Read Access:** You are strictly FORBIDDEN from generating `allow read: if isAuthenticated();` for the users collection if that collection is defined to contain email addresses or other private data.
- **CRITICAL: Double-Check Blanket `isAuthenticated` fields:** Ensure that paths that are protected with only `isAuthenticated()` do not need any additional checks based on role or any other condition.
- **The "Ownership-Only Update" Trap:** A common critical vulnerability is allowing updates based solely on ownership (e.g., `allow update: if isOwner(resource.data.uid);`). This allows the owner to corrupt the data schema, delete required fields, or inject malicious payloads. You **MUST** always combine ownership checks with data validation (e.g., `allow update: if isOwner(...) && isValidEntity(...);`) **AND** validate that self-escalation is not possible.
- **Deep Array Inspection:** It is insufficient to check if a field `is list`. You **MUST** validate the contents of the array (e.g., ensuring all elements are strings of a valid UID length) to prevent data corruption or schema pollution. For example, a `tags` array must verify that every item is a string AND that each string is within a reasonable length (e.g., < 20 chars).
- **Permission-Field Lockdown:** Fields that control access (e.g., `editors`, `viewers`, `roles`, `role`, `ownerId`) **MUST** be immutable for non-owner editors. In `update` rules, use `fieldUnchanged()` for these fields unless the `request.auth.uid` matches the document's original owner/creator. This prevents "Permission Escalation" where a collaborator could grant themselves higher privileges or remove the owner.
### Advanced Validation for Business Logic
Secure rules must enforce the application's business logic. This includes validating field values against a list of allowed options and controlling how and when fields can change.
#### 1. Enforce Enum Values
If a field should only contain specific values (e.g., a status), validate against a list.
**Example:**
```javascript
// A 'task' document's status can only be one of three values
function isValidStatus() {
let validStatuses = ['pending', 'in-progress', 'completed'];
return request.resource.data.status in validStatuses;
}
allow create: if isValidStatus() && ...
```
#### 2. Validate State Transitions
For `update` operations, you **MUST** validate that a field is changing from a valid previous state to a valid new state. This prevents users from bypassing workflows (e.g., marking a task as 'completed' from 'archived').
**Example:**
```javascript
// A task can only be marked 'completed' if it was 'in-progress'
function validStatusTransition() {
let previousStatus = resource.data.status;
let newStatus = request.resource.data.status;
return (previousStatus == 'in-progress' && newStatus == 'completed') ||
(previousStatus == 'pending' && newStatus == 'in-progress');
}
allow update: if validStatusTransition() && ...
```
#### 3. Strict Path and Relationship Scoping
For any field that references another resource (like an image path or a parent document ID), you **MUST** ensure it is correctly scoped to the user or valid within the context.
**Example:**
```javascript
// Ensure image path is within the user's own storage folder
allow create: if isScopedPath(request.resource.data.imageBucket) && ...
```
#### 4. Secure Counter Updates
When allowing users to update a counter (like `voteCount` or `answerCount`), you **MUST** ensure:
1. **Atomic Increments:** The field is only changing by exactly +1 or -1.
2. **Isolation:** **NO OTHER FIELDS** are being modified. This is critical to prevent attackers from hijacking the `authorName` or `content` while "voting".
3. **Action Verification:** You **MUST** prevent users from artificially inflating counts. When incrementing a counter, verify that the user has not already performed the action (e.g., by checking for the existence of a 'like' document) and is not looping updates.
* **CRITICAL:** Relying solely on `!exists(likeDoc)` is insufficient because a malicious user can skip creating the document and loop the increment.
* **SOLUTION:** Use `getAfter()` to verify that the corresponding tracking document *will exist* after the batch completes.
**Example:**
```javascript
function isValidCounterUpdate(docId) {
// Allow update only if 'voteCount' is the ONLY field changing
return request.resource.data.diff(resource.data).affectedKeys().hasOnly(['voteCount']) &&
// And the change is exactly +1 or -1
math.abs(request.resource.data.voteCount - resource.data.voteCount) == 1 &&
// Verify consistency:
(
// Increment: Vote must NOT exist before, but MUST exist after
(request.resource.data.voteCount > resource.data.voteCount &&
!exists(/databases/$(database)/documents/votes/$(request.auth.uid + '_' + docId)) &&
getAfter(/databases/$(database)/documents/votes/$(request.auth.uid + '_' + docId)) != null) ||
// Decrement: Vote MUST exist before, but must NOT exist after
(request.resource.data.voteCount < resource.data.voteCount &&
exists(/databases/$(database)/documents/votes/$(request.auth.uid + '_' + docId)) &&
getAfter(/databases/$(database)/documents/votes/$(request.auth.uid + '_' + docId)) == null)
);
}
allow update: if isValidCounterUpdate(docId) && ...
```
#### 5. **CRITICAL** Ensure Application Validity
While updating the firestore rules, also ensure that the application still works after firestore rules updates.
3. **For each collection, implement explicit data validation:**
- Type Checking: 'field is string', 'field is number', 'field is bool', 'field is timestamp'
- Required fields validation using 'hasRequiredFields()'
- **Enforce Size Limits:** For **EVERY** string, list, and map field, you **MUST** enforce realistic size limits (e.g., `text.size() < 1000`, `tags.size() < 20`). **Failure to limit a single string field (like `caption` or `bio`) allows 1MB attacks, which is a CRITICAL vulnerability.**
- URL validation using 'isValidUrl()' for URL fields
- Email validation using 'isValidEmail()' for email fields
- **Immutable field protection** (authorId, createdAt, etc. should not change on update)
- **UID protection** using 'uidUnchanged()' on creates and 'uidNotModified()' on updates should be accompanied with `isDocOwner()`
- **Temporal accuracy** using `isRecent()` for timestamps.
- **Range validation** using `isPositive()` or similar for numbers.
- **Path scoping** using `isScopedPath()` for storage paths.
Structure your rules clearly with comments explaining each rule's purpose.
#### Phase-3: Devil's Advocate Attack
**Critical step:** Systematically attempt to break your own rules using the following attack vectors. You MUST document the outcome of each attempt.
1. **Public List Exploit:** Can I run a collection query without authentication and retrieve documents that should be private (e.g., where `visible == false`)?
2. **Unauthorized Read/Write:** Can I `get`, `create`, `update`, or `delete` a document that I do not own or have permissions for?
3. **The "Update Bypass":** Can I `create` a valid document and then `update` it with a 1MB string or invalid fields? (Tests if validation logic is missing from `update`).
4. **Ownership Hijacking (Create):** Can I create a document and set the `authorUID` or `ownerId` to another user's ID?
5. **Ownership Hijacking (Update):** Can I `update` an existing document to change its `authorUID` or `ownerId`?
6. **Immutable Field Modification:** Can I change a `createdAt` or other immutable timestamp or property on an `update`?
7. **Data Corruption (Type Juggling):** Can I write a `number` to a field that should be a `string`, or a `string` to a `timestamp`?
8. **Validation Bypass (Create vs. Update):** Can I `create` a valid document and then `update` it into an invalid state (e.g., remove a required field, write a string that's too long)?
9. **Resource Exhaustion / DoS:** Can I write an enormous string (e.g., 1MB) to any field that accepts a string or a massive array to a list field? Every string field (e.g., `bio`, `url`, `name`) MUST have a `.size()` check. If any are missing, it's a "Resource Exhaustion/DoS" risk.
10. **Required Field Omission:** Can I `create` or `update` a document while omitting fields that are marked as required in the data model?
11. **Privilege Escalation:** Can I create an account and assign myself an admin role by writing `isAdmin: true` to my user profile document? (Tests reliance on document data vs. custom claims).
12. **Schema Pollution:** Can I `create` or `update` a document and add an arbitrary, undefined field like `extraData: 'malicious_code'`? (Tests for strict schema enforcement).
13. **Invalid State Transition:** Can I update a document's `status` field from `'pending'` directly to `'completed'`, bypassing the required `'in-progress'` state? (Tests business logic enforcement).
14. **Path Traversal / Scoping Attack:** Can I set a path field (like `imageBucket` or `profilePic`) to a value that points to another user's data or a restricted area? (Tests for regex path scoping).
15. **Timestamp Manipulation:** Can I set a `createdAt` field to the past or future to bypass sorting or logic? (Tests for `request.time` validation).
16. **Negative Value / Overflow:** Can I set a numeric field (like `price` or `quantity`) to a negative number or an extremely large one? (Tests for range validation).
17. **The "Mixed Content" Leak:** Create a second user. Can User B read User A's users document? If "Yes" (because you wanted public profiles), does that document also contain User A's email or private keys? If both are true, the rules are insecure.
18. **Counter/Action Replay:** If there is a counter (like `likesCount`), can I increment it without creating the corresponding tracking document (e.g., inside `likes/{userId}`)? Can I increment it twice? (Tests for `getAfter()` consistency checks).
19. **Orphaned Subcollection Access:** Can I read/write to a subcollection (e.g., `users/123/posts/456`) if the parent document (`users/123`) does not exist? (Tests for parent existence checks).
20. **Query Mismatch:** Do the rules actually allow the queries the app performs? (e.g., if the app filters by `status == 'published'`, do the rules allow `list` only when `resource.data.status == 'published'`?)
21. **Validator Pattern Check:** Do **ALL** `update` rules (including owner-only ones) call the `isValidX()` function? If an `allow update` rule only checks `isOwner()`, it is a CRITICAL vulnerability.
Document each attack attempt and whether it succeeded. If ANY attack succeeds:
- Fix the security hole
- Regenerate the rules
- **Repeat Phase-3** until no attacks succeed
#### Phase-4: Syntactic Validation
Once devil's advocate testing passes, repeat until rules pass validation.
**After all phases are complete, create or update the `firestore.rules` file.**
### Critical Constraints
1. **Never skip the devil's advocate phase** - this is your primary security validation
2. **MUST include helper functions** for common operations ('isAuthenticated', 'isOwner', 'uidUnchanged', 'uidNotModified') AND domain validators ('isValidUser', etc.)
3. **MUST document assumed data models** at the beginning of the rules file
4. **Always validate the rules syntax** using 'firebase deploy --only firestore:rules --dry-run' or a similar tool before outputting the final file.
5. **Provide complete, runnable code** - no placeholders or TODOs
6. **Document all assumptions** about data structure or access patterns
7. **Always run the devil's advocate attack** after any modification of the rules.
8. **Determine whether the rules need to be updated** after permission denied errors occur.
9. **Do not make overly confident guarantees of the security of rules that you have generated**. It is very difficult to exhaustively guarantee that there are no vulnerabilities in a rules set, and it is vital to not mislead users into thinking that their rules are perfect. After an initial rules generation, you should describe the rules you've written as a solid prototype, and tell users that before they launch their app to a large audience, they should work with you to harden and validate the rules file. Be clear that users should carefully review rules to ensure security.
.agents/skills/firebase-firestore-enterprise-native-mode/references/web_sdk_usage.md
+201
View File
@@ -0,0 +1,201 @@
# Web SDK Usage
This guide focuses on the **Modular Web SDK** (v9+), which is tree-shakeable and efficient.
### Initialization
```javascript
import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";
// If running in Firebase App Hosting, you can skip Firebase Config and instead use:
// const app = initializeApp();
const firebaseConfig = {
// Your config options. Get the values by running 'firebase apps:sdkconfig <platform> <app-id>'
};
const app = initializeApp(firebaseConfig);
const db = getFirestore(app);
```
### Writing Data
#### Set a Document
Creates a document if it doesn't exist, or overwrites it if it does. You can also specify a merge option to only update provided fields.
```javascript
import { doc, setDoc } from "firebase/firestore";
// Create/Overwrite document with ID "LA"
await setDoc(doc(db, "cities", "LA"), {
name: "Los Angeles",
state: "CA",
country: "USA"
});
// To merge with existing data instead of overwriting:
await setDoc(doc(db, "cities", "LA"), { population: 3900000 }, { merge: true });
```
#### Add a Document with Auto-ID
Use when you don't care about the document ID and want Firestore to automatically generate one.
```javascript
import { collection, addDoc } from "firebase/firestore";
const docRef = await addDoc(collection(db, "cities"), {
name: "Tokyo",
country: "Japan"
});
console.log("Document written with ID: ", docRef.id);
```
#### Update a Document
Update some fields of an existing document without overwriting the entire document. Fails if the document doesn't exist.
```javascript
import { doc, updateDoc } from "firebase/firestore";
const laRef = doc(db, "cities", "LA");
await updateDoc(laRef, {
capital: true
});
```
#### Transactions
Perform an atomic read-modify-write operation.
```javascript
import { runTransaction, doc } from "firebase/firestore";
const sfDocRef = doc(db, "cities", "SF");
try {
await runTransaction(db, async (transaction) => {
const sfDoc = await transaction.get(sfDocRef);
if (!sfDoc.exists()) {
throw "Document does not exist!";
}
const newPopulation = sfDoc.data().population + 1;
transaction.update(sfDocRef, { population: newPopulation });
});
console.log("Transaction successfully committed!");
} catch (e) {
console.log("Transaction failed: ", e);
}
```
### Reading Data
#### Get a Single Document
```javascript
import { doc, getDoc } from "firebase/firestore";
const docRef = doc(db, "cities", "SF");
const docSnap = await getDoc(docRef);
if (docSnap.exists()) {
console.log("Document data:", docSnap.data());
} else {
console.log("No such document!");
}
```
#### Get Multiple Documents
Fetches all documents in a query or collection once.
```javascript
import { collection, getDocs } from "firebase/firestore";
const querySnapshot = await getDocs(collection(db, "cities"));
querySnapshot.forEach((doc) => {
console.log(doc.id, " => ", doc.data());
});
```
### Realtime Updates
#### Listen to a Document or Query
```javascript
import { doc, onSnapshot } from "firebase/firestore";
const unsub = onSnapshot(doc(db, "cities", "SF"), (doc) => {
console.log("Current data: ", doc.data());
});
// To stop listening:
// unsub();
```
### Handle Changes
```javascript
import { collection, query, where, onSnapshot } from "firebase/firestore";
const q = query(collection(db, "cities"), where("state", "==", "CA"));
const unsubscribe = onSnapshot(q, (snapshot) => {
snapshot.docChanges().forEach((change) => {
if (change.type === "added") {
console.log("New city: ", change.doc.data());
}
if (change.type === "modified") {
console.log("Modified city: ", change.doc.data());
}
if (change.type === "removed") {
console.log("Removed city: ", change.doc.data());
}
});
});
```
### Queries
#### Simple and Compound Queries
Use `query()` and `where()` to combine filters safely.
```javascript
import { collection, query, where, getDocs } from "firebase/firestore";
const citiesRef = collection(db, "cities");
// Simple equality
const q1 = query(citiesRef, where("state", "==", "CA"));
// Compound (AND)
// Note: Requires a composite index if filtering on different fields
const q2 = query(citiesRef, where("state", "==", "CA"), where("population", ">", 1000000));
```
#### Order and Limit
Sort and limit results cleanly.
```javascript
import { orderBy, limit } from "firebase/firestore";
const q = query(citiesRef, orderBy("name"), limit(3));
```
#### Pipeline Queries
You can use pipeline queries to perform complex queries.
```javascript
const readDataPipeline = db.pipeline()
.collection("users");
// Execute the pipeline and handle the result
try {
const querySnapshot = await execute(readDataPipeline);
querySnapshot.results.forEach((result) => {
console.log(`${result.id} => ${result.data()}`);
});
} catch (error) {
console.error("Error getting documents: ", error);
}
```