pyric 0.0.1 → 0.1.0-alpha.8

package/dist/rules/modules/stdlib/timing.rules

@@ -0,0 +1,20 @@
+// Timing module for cooldown / rate-limit enforcement.
+//
+// Rules CAN rate-limit (contrary to a common assumption — jrpg
+// FINDINGS F-004): compare request.time against a stored server
+// timestamp. Pair with lifecycle's isServerTimestamp on the SAME
+// write so the stored timestamp cannot be forged by the client:
+//
+//   import { cooldownElapsed } from 'timing';
+//   import { isServerTimestamp } from 'lifecycle';
+//
+//   // At most one move every 2 seconds:
+//   allow update: if cooldownElapsed('lastMoveAt', 2)
+//     && isServerTimestamp('lastMoveAt');
+
+// The stored timestamp is more than `seconds` old (strict). Update
+// rules only — needs `resource`. The field must be a Timestamp; a
+// missing field errors, which denies (fail-closed).
+export function cooldownElapsed(field, seconds) {
+  return request.time > resource.data[field] + duration.value(seconds, 's');
+}

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

@@ -0,0 +1,106 @@
+[
+  {
+    "description": "cooldownElapsed allows when the stored timestamp is older than the window",
+    "expectation": "ALLOW",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "resource": {
+      "lastMoveAt": {
+        "__type": "timestamp",
+        "iso": "2026-01-01T00:00:00Z"
+      }
+    },
+    "data": {
+      "lastMoveAt": "REQUEST_TIME"
+    },
+    "requestTime": "2026-01-01T00:02:00Z",
+    "wrapFunction": "cooldownElapsed",
+    "wrapOperation": "update",
+    "wrapCallExpr": "cooldownElapsed('lastMoveAt', 60)"
+  },
+  {
+    "description": "cooldownElapsed denies inside the window",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "resource": {
+      "lastMoveAt": {
+        "__type": "timestamp",
+        "iso": "2026-01-01T00:00:00Z"
+      }
+    },
+    "data": {
+      "lastMoveAt": "REQUEST_TIME"
+    },
+    "requestTime": "2026-01-01T00:00:30Z",
+    "wrapFunction": "cooldownElapsed",
+    "wrapOperation": "update",
+    "wrapCallExpr": "cooldownElapsed('lastMoveAt', 60)"
+  },
+  {
+    "description": "cooldownElapsed denies at the exact boundary (strict comparison)",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "resource": {
+      "lastMoveAt": {
+        "__type": "timestamp",
+        "iso": "2026-01-01T00:00:00Z"
+      }
+    },
+    "data": {
+      "lastMoveAt": "REQUEST_TIME"
+    },
+    "requestTime": "2026-01-01T00:01:00Z",
+    "wrapFunction": "cooldownElapsed",
+    "wrapOperation": "update",
+    "wrapCallExpr": "cooldownElapsed('lastMoveAt', 60)"
+  },
+  {
+    "description": "cooldownElapsed denies (fail-closed) when the field is missing",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "resource": {
+      "other": 1
+    },
+    "data": {
+      "lastMoveAt": "REQUEST_TIME"
+    },
+    "requestTime": "2026-01-01T00:02:00Z",
+    "wrapFunction": "cooldownElapsed",
+    "wrapOperation": "update",
+    "wrapCallExpr": "cooldownElapsed('lastMoveAt', 60)"
+  },
+  {
+    "description": "cooldownElapsed denies (fail-closed) when the field is not a timestamp",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "resource": {
+      "lastMoveAt": "yesterday"
+    },
+    "data": {
+      "lastMoveAt": "REQUEST_TIME"
+    },
+    "requestTime": "2026-01-01T00:02:00Z",
+    "wrapFunction": "cooldownElapsed",
+    "wrapOperation": "update",
+    "wrapCallExpr": "cooldownElapsed('lastMoveAt', 60)"
+  }
+]

package/dist/rules/modules/stdlib/transitions.rules

@@ -0,0 +1,34 @@
+// Transitions module for state machine enforcement.
+//
+// Validates that a field transitions from one known value to another.
+// Use to enforce valid status flows (e.g., open -> in_progress -> completed).
+//
+// Usage:
+//   import { validTransition, statusIs, newStatusIs } from 'transitions';
+//
+//   // Only allow open -> in_progress
+//   allow update: if validTransition('status', 'open', 'in_progress');
+//
+//   // Allow update only when currently active
+//   allow update: if statusIs('status', 'active');
+//
+//   // Compound: multiple valid transitions via OR
+//   allow update: if validTransition('status', 'open', 'in_progress')
+//     || validTransition('status', 'in_progress', 'completed')
+//     || validTransition('status', 'completed', 'archived');
+
+// Check that a field transitions from one value to another.
+export function validTransition(field, from, to) {
+  return resource.data[field] == from
+    && request.resource.data[field] == to;
+}
+
+// Check the current (existing) value of a field.
+export function statusIs(field, value) {
+  return resource.data[field] == value;
+}
+
+// Check the incoming (new) value of a field.
+export function newStatusIs(field, value) {
+  return request.resource.data[field] == value;
+}

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

@@ -0,0 +1,86 @@
+[
+  {
+    "description": "validTransition allows correct from->to",
+    "expectation": "ALLOW",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": { "uid": "user1" },
+    "resource": { "status": "open" },
+    "data": { "status": "in_progress" },
+    "wrapFunction": "validTransition",
+    "wrapOperation": "update",
+    "wrapCallExpr": "validTransition('status', 'open', 'in_progress')"
+  },
+  {
+    "description": "validTransition denies wrong from value",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": { "uid": "user1" },
+    "resource": { "status": "completed" },
+    "data": { "status": "in_progress" },
+    "wrapFunction": "validTransition",
+    "wrapOperation": "update",
+    "wrapCallExpr": "validTransition('status', 'open', 'in_progress')"
+  },
+  {
+    "description": "validTransition denies wrong to value",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": { "uid": "user1" },
+    "resource": { "status": "open" },
+    "data": { "status": "archived" },
+    "wrapFunction": "validTransition",
+    "wrapOperation": "update",
+    "wrapCallExpr": "validTransition('status', 'open', 'in_progress')"
+  },
+  {
+    "description": "statusIs allows when current value matches",
+    "expectation": "ALLOW",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": { "uid": "user1" },
+    "resource": { "status": "active" },
+    "data": { "status": "active" },
+    "wrapFunction": "statusIs",
+    "wrapOperation": "update",
+    "wrapCallExpr": "statusIs('status', 'active')"
+  },
+  {
+    "description": "statusIs denies when current value differs",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": { "uid": "user1" },
+    "resource": { "status": "archived" },
+    "data": { "status": "archived" },
+    "wrapFunction": "statusIs",
+    "wrapOperation": "update",
+    "wrapCallExpr": "statusIs('status', 'active')"
+  },
+  {
+    "description": "newStatusIs allows when incoming value matches",
+    "expectation": "ALLOW",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": { "uid": "user1" },
+    "resource": { "status": "open" },
+    "data": { "status": "completed" },
+    "wrapFunction": "newStatusIs",
+    "wrapOperation": "update",
+    "wrapCallExpr": "newStatusIs('status', 'completed')"
+  },
+  {
+    "description": "newStatusIs denies when incoming value differs",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": { "uid": "user1" },
+    "resource": { "status": "open" },
+    "data": { "status": "in_progress" },
+    "wrapFunction": "newStatusIs",
+    "wrapOperation": "update",
+    "wrapCallExpr": "newStatusIs('status', 'completed')"
+  }
+]

package/dist/rules/modules/stdlib/turns.rules

@@ -0,0 +1,27 @@
+// Turn enforcement for 2-participant games/sessions.
+//
+// Convention: documents must have these fields:
+//   host: string (UID)
+//   guest: string (UID)
+//   currentTurn: 'host' | 'guest'
+//
+// Usage:
+//   import { isMyTurn, turnFlipped } from 'turns';
+//
+//   allow update: if isMyTurn() && turnFlipped();
+
+// Is the caller the participant whose turn it is?
+export function isMyTurn() {
+  return (resource.data.currentTurn == 'host'
+            && request.auth.uid == resource.data.host)
+      || (resource.data.currentTurn == 'guest'
+            && request.auth.uid == resource.data.guest);
+}
+
+// Did the turn alternate?
+export function turnFlipped() {
+  return (resource.data.currentTurn == 'host'
+            && request.resource.data.currentTurn == 'guest')
+      || (resource.data.currentTurn == 'guest'
+            && request.resource.data.currentTurn == 'host');
+}

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

@@ -0,0 +1,64 @@
+[
+  {
+    "description": "isMyTurn allows host when currentTurn is host",
+    "expectation": "ALLOW",
+    "method": "update",
+    "path": "test/game1",
+    "auth": { "uid": "host1" },
+    "resource": { "host": "host1", "guest": "guest1", "currentTurn": "host" },
+    "wrapFunction": "isMyTurn",
+    "wrapOperation": "update"
+  },
+  {
+    "description": "isMyTurn denies guest when currentTurn is host",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/game1",
+    "auth": { "uid": "guest1" },
+    "resource": { "host": "host1", "guest": "guest1", "currentTurn": "host" },
+    "wrapFunction": "isMyTurn",
+    "wrapOperation": "update"
+  },
+  {
+    "description": "isMyTurn allows guest when currentTurn is guest",
+    "expectation": "ALLOW",
+    "method": "update",
+    "path": "test/game1",
+    "auth": { "uid": "guest1" },
+    "resource": { "host": "host1", "guest": "guest1", "currentTurn": "guest" },
+    "wrapFunction": "isMyTurn",
+    "wrapOperation": "update"
+  },
+  {
+    "description": "isMyTurn denies unauthenticated",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/game1",
+    "auth": null,
+    "resource": { "host": "host1", "guest": "guest1", "currentTurn": "host" },
+    "wrapFunction": "isMyTurn",
+    "wrapOperation": "update"
+  },
+  {
+    "description": "turnFlipped allows host to guest transition",
+    "expectation": "ALLOW",
+    "method": "update",
+    "path": "test/game1",
+    "auth": { "uid": "host1" },
+    "data": { "currentTurn": "guest" },
+    "resource": { "currentTurn": "host" },
+    "wrapFunction": "turnFlipped",
+    "wrapOperation": "update"
+  },
+  {
+    "description": "turnFlipped denies same turn value",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/game1",
+    "auth": { "uid": "host1" },
+    "data": { "currentTurn": "host" },
+    "resource": { "currentTurn": "host" },
+    "wrapFunction": "turnFlipped",
+    "wrapOperation": "update"
+  }
+]

package/dist/rules/modules/stdlib/validation.rules

@@ -0,0 +1,31 @@
+// Validation module for document field shape and value checks.
+//
+// Usage:
+//   import { hasRequired, hasOnly, validString, isOneOf } from 'validation';
+//
+//   allow create: if hasRequired(['title', 'status'])
+//     && validString('title', 1, 100)
+//     && isOneOf('status', ['draft', 'published']);
+
+export function hasRequired(fields) {
+  return request.resource.data.keys().hasAll(fields);
+}
+
+export function hasOnly(fields) {
+  return request.resource.data.keys().hasOnly(fields);
+}
+
+// Incoming field is a string with size in [min, max] (inclusive).
+// Uses dynamic access, so a MISSING field reads as null (not an
+// error) and fails the `is string` check — safe on optional fields.
+export function validString(field, min, max) {
+  return request.resource.data[field] is string
+    && request.resource.data[field].size() >= min
+    && request.resource.data[field].size() <= max;
+}
+
+// Enum check: the incoming field value is one of the allowed values.
+// (`in` on a list — NOT `.includes()`, which does not exist in rules.)
+export function isOneOf(field, values) {
+  return request.resource.data[field] in values;
+}

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

@@ -0,0 +1,184 @@
+[
+  {
+    "description": "hasRequired allows when field present",
+    "expectation": "ALLOW",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "data": {
+      "name": "Alice"
+    },
+    "wrapFunction": "hasRequired",
+    "wrapCallExpr": "hasRequired(['name'])",
+    "wrapOperation": "create"
+  },
+  {
+    "description": "hasRequired denies when field missing",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "data": {
+      "email": "alice@example.com"
+    },
+    "wrapFunction": "hasRequired",
+    "wrapCallExpr": "hasRequired(['name'])",
+    "wrapOperation": "create"
+  },
+  {
+    "description": "hasOnly denies when extra field present",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "data": {
+      "name": "Alice",
+      "email": "a@b.com",
+      "secret": "x"
+    },
+    "wrapFunction": "hasOnly",
+    "wrapCallExpr": "hasOnly(['name', 'email'])",
+    "wrapOperation": "create"
+  },
+  {
+    "description": "validString allows string within bounds",
+    "expectation": "ALLOW",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "validString",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validString('title', 1, 10)",
+    "data": {
+      "title": "hello"
+    }
+  },
+  {
+    "description": "validString allows at exact min and max boundary",
+    "expectation": "ALLOW",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "validString",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validString('title', 5, 5)",
+    "data": {
+      "title": "hello"
+    }
+  },
+  {
+    "description": "validString denies empty string below min",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "validString",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validString('title', 1, 10)",
+    "data": {
+      "title": ""
+    }
+  },
+  {
+    "description": "validString denies string over max",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "validString",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validString('title', 1, 4)",
+    "data": {
+      "title": "hello"
+    }
+  },
+  {
+    "description": "validString denies non-string value",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "validString",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validString('title', 1, 10)",
+    "data": {
+      "title": 42
+    }
+  },
+  {
+    "description": "validString denies MISSING field (null-on-miss, not error)",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "validString",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validString('title', 1, 10)",
+    "data": {
+      "other": "x"
+    }
+  },
+  {
+    "description": "isOneOf allows a listed value",
+    "expectation": "ALLOW",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "isOneOf",
+    "wrapOperation": "create",
+    "wrapCallExpr": "isOneOf('status', ['draft', 'published'])",
+    "data": {
+      "status": "draft"
+    }
+  },
+  {
+    "description": "isOneOf denies an unlisted value",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "isOneOf",
+    "wrapOperation": "create",
+    "wrapCallExpr": "isOneOf('status', ['draft', 'published'])",
+    "data": {
+      "status": "nuked"
+    }
+  },
+  {
+    "description": "isOneOf denies a missing field",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "isOneOf",
+    "wrapOperation": "create",
+    "wrapCallExpr": "isOneOf('status', ['draft', 'published'])",
+    "data": {
+      "other": "x"
+    }
+  }
+]

package/dist/rules/modules/stdlib-content.d.ts

@@ -0,0 +1,11 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ * Regenerate via `bun run inline-stdlib` (or `bun run build`, which
+ * runs the generator as part of `prebuild`).
+ *
+ * Mirror of every `.rules` file under `src/modules/stdlib/`,
+ * inlined as TypeScript string literals so the resolver can run
+ * in the browser. See `scripts/inline-stdlib.ts`.
+ */
+export declare const STDLIB_INLINE: Record<string, string>;
+//# sourceMappingURL=stdlib-content.d.ts.map

package/dist/rules/modules/stdlib-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdlib-content.d.ts","sourceRoot":"","sources":["../../../src/rules/modules/stdlib-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAmkBhD,CAAC"}