pyric 0.0.1 → 0.1.0-alpha.8

package/dist/rules/modules/stdlib/membership.rules

@@ -0,0 +1,40 @@
+// Membership module for role-based and claims-based access control.
+//
+// Two access patterns:
+//   1. Custom claims on auth token (0 get() calls, set server-side)
+//   2. Member maps on documents (0 get() calls on the doc itself)
+//
+// Usage:
+//   import { hasClaim, hasClaimRole, isMemberOf, hasRole } from 'membership';
+//
+//   // Workspace access via custom claims
+//   allow read: if hasClaim('workspace_id');
+//   allow write: if hasClaimRole('workspace_role', 'admin');
+//
+//   // Project access via member map on document
+//   allow read: if isMemberOf(resource.data.members);
+//   allow update: if hasRole(resource.data.members, 'admin');
+
+// Check if the auth token has a non-null value for a claim key.
+export function hasClaim(claim) {
+  return request.auth != null
+    && request.auth.token[claim] != null;
+}
+
+// Check if the auth token has a specific value for a claim key.
+export function hasClaimRole(claim, role) {
+  return request.auth != null
+    && request.auth.token[claim] == role;
+}
+
+// Check if the caller's UID exists as a key in a members map.
+export function isMemberOf(membersMap) {
+  return request.auth != null
+    && request.auth.uid in membersMap;
+}
+
+// Check if the caller has a specific role in a members map.
+export function hasRole(membersMap, role) {
+  return request.auth != null
+    && membersMap[request.auth.uid] == role;
+}

package/dist/rules/modules/stdlib/membership.test.json

@@ -0,0 +1,107 @@
+[
+  {
+    "description": "hasClaim allows when token has the claim",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": { "uid": "user1", "token": { "workspace": true } },
+    "wrapFunction": "hasClaim",
+    "wrapOperation": "read",
+    "wrapCallExpr": "hasClaim('workspace')"
+  },
+  {
+    "description": "hasClaim denies when token lacks the claim",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": { "uid": "user1", "token": {} },
+    "wrapFunction": "hasClaim",
+    "wrapOperation": "read",
+    "wrapCallExpr": "hasClaim('workspace')"
+  },
+  {
+    "description": "hasClaim denies unauthenticated",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": null,
+    "wrapFunction": "hasClaim",
+    "wrapOperation": "read",
+    "wrapCallExpr": "hasClaim('workspace')"
+  },
+  {
+    "description": "hasClaimRole allows when claim matches role",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": { "uid": "user1", "token": { "role": "admin" } },
+    "wrapFunction": "hasClaimRole",
+    "wrapOperation": "read",
+    "wrapCallExpr": "hasClaimRole('role', 'admin')"
+  },
+  {
+    "description": "hasClaimRole denies when claim has wrong role",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": { "uid": "user1", "token": { "role": "member" } },
+    "wrapFunction": "hasClaimRole",
+    "wrapOperation": "read",
+    "wrapCallExpr": "hasClaimRole('role', 'admin')"
+  },
+  {
+    "description": "isMemberOf allows when uid is in members map",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": { "uid": "alice" },
+    "resource": { "members": { "alice": "editor", "bob": "viewer" } },
+    "wrapFunction": "isMemberOf",
+    "wrapOperation": "read",
+    "wrapCallExpr": "isMemberOf(resource.data.members)"
+  },
+  {
+    "description": "isMemberOf denies when uid is not in members map",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": { "uid": "carol" },
+    "resource": { "members": { "alice": "editor", "bob": "viewer" } },
+    "wrapFunction": "isMemberOf",
+    "wrapOperation": "read",
+    "wrapCallExpr": "isMemberOf(resource.data.members)"
+  },
+  {
+    "description": "hasRole allows when uid has matching role",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": { "uid": "alice" },
+    "resource": { "members": { "alice": "admin", "bob": "viewer" } },
+    "wrapFunction": "hasRole",
+    "wrapOperation": "read",
+    "wrapCallExpr": "hasRole(resource.data.members, 'admin')"
+  },
+  {
+    "description": "hasRole denies when uid has different role",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": { "uid": "bob" },
+    "resource": { "members": { "alice": "admin", "bob": "viewer" } },
+    "wrapFunction": "hasRole",
+    "wrapOperation": "read",
+    "wrapCallExpr": "hasRole(resource.data.members, 'admin')"
+  },
+  {
+    "description": "hasRole denies unauthenticated",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": null,
+    "resource": { "members": { "alice": "admin" } },
+    "wrapFunction": "hasRole",
+    "wrapOperation": "read",
+    "wrapCallExpr": "hasRole(resource.data.members, 'admin')"
+  }
+]

package/dist/rules/modules/stdlib/spaces.rules

@@ -0,0 +1,46 @@
+// Spaces module — cross-document membership gating for shared spaces
+// (teams, rooms, groups, projects, parties). The second-most-common
+// app shape after author-owned content: a PARENT document defines who
+// may touch its children.
+//
+// Explicit-param design (like geometry): the caller reads the parent
+// doc ONCE via a helper and passes its data in. Define the helper in
+// your rules — get() is cached per request, so every function below
+// can share one read (of the 10-get budget):
+//
+//   import { isSpaceMember, hasSpaceRole, validMemberCreate } from 'spaces';
+//
+//   match /spaces/{spaceId}/tasks/{taskId} {
+//     function space() {
+//       return get(/databases/$(database)/documents/spaces/$(spaceId)).data;
+//     }
+//     allow read: if isSpaceMember(space());
+//     allow create: if validMemberCreate(space(), 'author');
+//     allow delete: if hasSpaceRole(space(), 'admin');
+//   }
+//
+// Members field shapes verified against the production engine:
+//   list: members: ['uidA', 'uidB']            → isSpaceMember only
+//   map:  members: { uidA: 'admin', ... }      → isSpaceMember + hasSpaceRole
+// A missing members field, a non-member uid, or a missing parent doc
+// (get() of a missing doc errors) all fail CLOSED.
+
+// The caller is in the space's members field. `in` covers both
+// shapes: list membership and map keys.
+export function isSpaceMember(spaceData) {
+  return request.auth != null && request.auth.uid in spaceData.members;
+}
+
+// The caller's role in a MAP-shaped members field equals `role`.
+// List-shaped members carry no roles — this denies on them.
+export function hasSpaceRole(spaceData, role) {
+  return request.auth != null && spaceData.members[request.auth.uid] == role;
+}
+
+// Member-gated authored create: the caller is a member AND the
+// incoming child doc's author field is the caller. The "post a
+// message / add a task" guard.
+export function validMemberCreate(spaceData, authorField) {
+  return isSpaceMember(spaceData)
+    && request.resource.data[authorField] == request.auth.uid;
+}

package/dist/rules/modules/stdlib/spaces.test.json

@@ -0,0 +1,392 @@
+[
+  {
+    "description": "isSpaceMember allows a list-shaped member",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "alice"
+    },
+    "wrapFunction": "isSpaceMember",
+    "wrapOperation": "get",
+    "wrapCallExpr": "isSpaceMember(get(/databases/$(database)/documents/spaces/s1).data)",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": [
+            "alice",
+            "bob"
+          ]
+        }
+      }
+    ],
+    "resource": {
+      "title": "x"
+    }
+  },
+  {
+    "description": "isSpaceMember denies a non-member (list shape)",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "mallory"
+    },
+    "wrapFunction": "isSpaceMember",
+    "wrapOperation": "get",
+    "wrapCallExpr": "isSpaceMember(get(/databases/$(database)/documents/spaces/s1).data)",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": [
+            "alice",
+            "bob"
+          ]
+        }
+      }
+    ],
+    "resource": {
+      "title": "x"
+    }
+  },
+  {
+    "description": "isSpaceMember allows a map-shaped member",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "alice"
+    },
+    "wrapFunction": "isSpaceMember",
+    "wrapOperation": "get",
+    "wrapCallExpr": "isSpaceMember(get(/databases/$(database)/documents/spaces/s1).data)",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": {
+            "alice": "admin",
+            "bob": "viewer"
+          }
+        }
+      }
+    ],
+    "resource": {
+      "title": "x"
+    }
+  },
+  {
+    "description": "isSpaceMember denies a non-member (map shape)",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "mallory"
+    },
+    "wrapFunction": "isSpaceMember",
+    "wrapOperation": "get",
+    "wrapCallExpr": "isSpaceMember(get(/databases/$(database)/documents/spaces/s1).data)",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": {
+            "alice": "admin",
+            "bob": "viewer"
+          }
+        }
+      }
+    ],
+    "resource": {
+      "title": "x"
+    }
+  },
+  {
+    "description": "isSpaceMember denies unauthenticated",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "spaces/s1/tasks/t1",
+    "auth": null,
+    "wrapFunction": "isSpaceMember",
+    "wrapOperation": "get",
+    "wrapCallExpr": "isSpaceMember(get(/databases/$(database)/documents/spaces/s1).data)",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": [
+            "alice",
+            "bob"
+          ]
+        }
+      }
+    ],
+    "resource": {
+      "title": "x"
+    }
+  },
+  {
+    "description": "isSpaceMember denies when the members field is missing (fail-closed)",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "alice"
+    },
+    "wrapFunction": "isSpaceMember",
+    "wrapOperation": "get",
+    "wrapCallExpr": "isSpaceMember(get(/databases/$(database)/documents/spaces/s1).data)",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "name": "no-members"
+        }
+      }
+    ],
+    "resource": {
+      "title": "x"
+    }
+  },
+  {
+    "description": "hasSpaceRole allows the matching role",
+    "expectation": "ALLOW",
+    "method": "create",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "alice"
+    },
+    "wrapFunction": "hasSpaceRole",
+    "wrapOperation": "create",
+    "wrapCallExpr": "hasSpaceRole(get(/databases/$(database)/documents/spaces/s1).data, 'admin')",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": {
+            "alice": "admin",
+            "bob": "viewer"
+          }
+        }
+      }
+    ],
+    "data": {
+      "title": "x"
+    }
+  },
+  {
+    "description": "hasSpaceRole denies a different role",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "bob"
+    },
+    "wrapFunction": "hasSpaceRole",
+    "wrapOperation": "create",
+    "wrapCallExpr": "hasSpaceRole(get(/databases/$(database)/documents/spaces/s1).data, 'admin')",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": {
+            "alice": "admin",
+            "bob": "viewer"
+          }
+        }
+      }
+    ],
+    "data": {
+      "title": "x"
+    }
+  },
+  {
+    "description": "hasSpaceRole denies a non-member",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "mallory"
+    },
+    "wrapFunction": "hasSpaceRole",
+    "wrapOperation": "create",
+    "wrapCallExpr": "hasSpaceRole(get(/databases/$(database)/documents/spaces/s1).data, 'admin')",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": {
+            "alice": "admin",
+            "bob": "viewer"
+          }
+        }
+      }
+    ],
+    "data": {
+      "title": "x"
+    }
+  },
+  {
+    "description": "hasSpaceRole denies on a list-shaped members field (no roles)",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "alice"
+    },
+    "wrapFunction": "hasSpaceRole",
+    "wrapOperation": "create",
+    "wrapCallExpr": "hasSpaceRole(get(/databases/$(database)/documents/spaces/s1).data, 'admin')",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": [
+            "alice",
+            "bob"
+          ]
+        }
+      }
+    ],
+    "data": {
+      "title": "x"
+    }
+  },
+  {
+    "description": "validMemberCreate allows a member creating an author-stamped doc",
+    "expectation": "ALLOW",
+    "method": "create",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "alice"
+    },
+    "wrapFunction": "validMemberCreate",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validMemberCreate(get(/databases/$(database)/documents/spaces/s1).data, 'author')",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": [
+            "alice",
+            "bob"
+          ]
+        }
+      }
+    ],
+    "data": {
+      "title": "x",
+      "author": "alice"
+    }
+  },
+  {
+    "description": "validMemberCreate denies a member stamping someone else as author",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "alice"
+    },
+    "wrapFunction": "validMemberCreate",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validMemberCreate(get(/databases/$(database)/documents/spaces/s1).data, 'author')",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": [
+            "alice",
+            "bob"
+          ]
+        }
+      }
+    ],
+    "data": {
+      "title": "x",
+      "author": "bob"
+    }
+  },
+  {
+    "description": "validMemberCreate denies a non-member",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "mallory"
+    },
+    "wrapFunction": "validMemberCreate",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validMemberCreate(get(/databases/$(database)/documents/spaces/s1).data, 'author')",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": [
+            "alice",
+            "bob"
+          ]
+        }
+      }
+    ],
+    "data": {
+      "title": "x",
+      "author": "mallory"
+    }
+  },
+  {
+    "description": "validMemberCreate denies a missing author field",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "spaces/s1/tasks/t1",
+    "auth": {
+      "uid": "alice"
+    },
+    "wrapFunction": "validMemberCreate",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validMemberCreate(get(/databases/$(database)/documents/spaces/s1).data, 'author')",
+    "wrapMatch": "/spaces/{spaceId}/tasks/{taskId}",
+    "functionMocks": [
+      {
+        "function": "get",
+        "path": "spaces/s1",
+        "result": {
+          "members": [
+            "alice",
+            "bob"
+          ]
+        }
+      }
+    ],
+    "data": {
+      "title": "x"
+    }
+  }
+]

package/dist/rules/modules/stdlib/state.rules

@@ -0,0 +1,28 @@
+// Game state machine helpers.
+//
+// Convention: documents must have these fields:
+//   status: 'waiting' | 'playing' | 'won' | 'draw'
+//   moveCount: number
+//   host: string (UID)
+//   guest: string (UID)
+//
+// Usage:
+//   import { isPlaying, moveIncremented, participantsUnchanged } from 'state';
+//
+//   allow update: if isPlaying() && moveIncremented() && participantsUnchanged();
+
+// Is the game actively in play?
+export function isPlaying() {
+  return resource.data.status == 'playing';
+}
+
+// Did moveCount increment by exactly 1?
+export function moveIncremented() {
+  return request.resource.data.moveCount == resource.data.moveCount + 1;
+}
+
+// Are host and guest unchanged? (prevents mid-game identity swap)
+export function participantsUnchanged() {
+  return request.resource.data.host == resource.data.host
+      && request.resource.data.guest == resource.data.guest;
+}

package/dist/rules/modules/stdlib/state.test.json

@@ -0,0 +1,55 @@
+[
+  {
+    "description": "isPlaying allows when status is playing",
+    "expectation": "ALLOW",
+    "method": "update",
+    "path": "test/game1",
+    "auth": { "uid": "user1" },
+    "resource": { "status": "playing" },
+    "wrapFunction": "isPlaying",
+    "wrapOperation": "update"
+  },
+  {
+    "description": "isPlaying denies when status is waiting",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/game1",
+    "auth": { "uid": "user1" },
+    "resource": { "status": "waiting" },
+    "wrapFunction": "isPlaying",
+    "wrapOperation": "update"
+  },
+  {
+    "description": "moveIncremented allows 0 to 1",
+    "expectation": "ALLOW",
+    "method": "update",
+    "path": "test/game1",
+    "auth": { "uid": "user1" },
+    "data": { "moveCount": 1 },
+    "resource": { "moveCount": 0 },
+    "wrapFunction": "moveIncremented",
+    "wrapOperation": "update"
+  },
+  {
+    "description": "moveIncremented denies skip from 0 to 5",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/game1",
+    "auth": { "uid": "user1" },
+    "data": { "moveCount": 5 },
+    "resource": { "moveCount": 0 },
+    "wrapFunction": "moveIncremented",
+    "wrapOperation": "update"
+  },
+  {
+    "description": "participantsUnchanged denies when host changes",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/game1",
+    "auth": { "uid": "user1" },
+    "data": { "host": "hijacked", "guest": "guest1" },
+    "resource": { "host": "host1", "guest": "guest1" },
+    "wrapFunction": "participantsUnchanged",
+    "wrapOperation": "update"
+  }
+]