pyric 0.0.1 → 0.1.0-alpha.8

package/dist/rules/modules/resolver.js

@@ -0,0 +1,49 @@
+/**
+ * Node-side `2+modules` resolver — the disk-reading public API. All the
+ * resolution logic lives in `./resolver-core.js` (pure, no node imports);
+ * this wrapper supplies the {@link ModuleFileReader} that reads relative
+ * imports from `basePath` and stdlib modules from the package's on-disk
+ * `stdlib/` directory.
+ *
+ * NODE-ONLY by construction (static `fs`/`path`/`url` imports). Browser
+ * consumers use `./resolver-browser.js`, which binds the core to the
+ * inlined stdlib and never touches this file — that separation is the
+ * point: these node imports used to leak into browser bundles through
+ * `resolver-browser`'s import chain (caught by the pyric-serve P0 validation).
+ */
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { loadModuleWith, resolveModulesWith, } from './resolver-core.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const STDLIB_DIR = join(__dirname, 'stdlib');
+const diskReader = {
+    readRelative(basePath, moduleName) {
+        try {
+            return readFileSync(join(basePath, `${moduleName}.rules`), 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    },
+    readStdlib(moduleName) {
+        try {
+            return readFileSync(join(STDLIB_DIR, `${moduleName}.rules`), 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/** Resolve a `2+modules` source, reading relative + stdlib modules from disk. */
+export function resolveModules(source, options) {
+    return resolveModulesWith(diskReader, source, options);
+}
+/** Load one module with the disk reader (exposed for `rules/node` consumers). */
+export function loadModule(moduleName, options) {
+    return loadModuleWith(diskReader, moduleName, options);
+}
+// Pure helpers + types re-exported so existing `./resolver.js` importers
+// (`rules/node.js`, `rules/tools.js`) keep their import sites unchanged.
+export { sanitizeModuleName, prefixPrivateFunctions, rewriteCalls, } from './resolver-core.js';
+//# sourceMappingURL=resolver.js.map

package/dist/rules/modules/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../src/rules/modules/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EACL,cAAc,EACd,kBAAkB,GAInB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAE7C,MAAM,UAAU,GAAqB;IACnC,YAAY,CAAC,QAAQ,EAAE,UAAU;QAC/B,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,UAAU,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,UAAU,CAAC,UAAU;QACnB,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,UAAU,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC;QACxE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF,CAAC;AAEF,iFAAiF;AACjF,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,OAAwB;IACrE,OAAO,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACzD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,UAAkB,EAAE,OAAwB;IACrE,OAAO,cAAc,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;AACzD,CAAC;AAED,yEAAyE;AACzE,yEAAyE;AACzE,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,GACb,MAAM,oBAAoB,CAAC"}

package/dist/rules/modules/stdlib/atomic.rules

@@ -0,0 +1,52 @@
+// Atomic module — cross-document integrity for BATCH writes, via the
+// get()/getAfter() pair. Firestore evaluates every write in a batch
+// against rules, and getAfter() returns another document's POST-BATCH
+// state — so a rule can require "this write is only valid if a
+// companion write happened in the same atomic batch".
+//
+// All semantics live-verified against a production database: companion
+// visibility, solo-write denial, wrong-delta denial, single-use consumption
+// incl. replay denial, and out-of-batch getAfter() falling back to current
+// state.
+//
+// Explicit-param design: pass BOTH states of the companion doc —
+// `get(path).data` (pre-batch) and `getAfter(path).data` (post-batch).
+//
+//   import { companionChangedBy, consumedFlag } from 'atomic';
+//
+//   // Denormalized counter: creating a task REQUIRES the team's
+//   // taskCount to have been incremented in the same batch:
+//   match /teams/{teamId}/tasks/{taskId} {
+//     function teamBefore() {
+//       return get(/databases/$(database)/documents/teams/$(teamId)).data;
+//     }
+//     function teamAfter() {
+//       return getAfter(/databases/$(database)/documents/teams/$(teamId)).data;
+//     }
+//     allow create: if companionChangedBy(teamBefore(), teamAfter(), 'taskCount', 1);
+//   }
+//
+//   // Single-use invite: the join is valid only when the invite was
+//   // consumed (false -> true) IN THIS BATCH — replays deny because
+//   // the pre-batch state is already true:
+//   allow update: if consumedFlag(inviteBefore(), inviteAfter(), 'used');
+//
+// NOTE (simulator): in-batch companion semantics cannot be expressed
+// in the simulator or the Rules Test API mock surface — the simulator
+// treats cross-doc getAfter() as get(). These function BODIES are
+// simulator-tested with explicit values; the getAfter() WIRING is the
+// live v1 scope's job. Companion writes need their own allow rules too —
+// every write in a batch is evaluated.
+
+// The companion doc's field changed by EXACTLY n in this batch.
+// before/after are the SAME doc's get()/getAfter() data.
+export function companionChangedBy(before, after, field, n) {
+  return after[field] == before[field] + n;
+}
+
+// A single-use flag was consumed IN THIS BATCH: pre-batch false,
+// post-batch true. Replays deny (pre-batch is already true), and a
+// solo write denies (getAfter == get, so false != true).
+export function consumedFlag(before, after, flagField) {
+  return before[flagField] == false && after[flagField] == true;
+}

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

@@ -0,0 +1,152 @@
+[
+  {
+    "description": "companionChangedBy allows an exact +1 delta",
+    "expectation": "ALLOW",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "alice"
+    },
+    "data": {
+      "x": 1
+    },
+    "wrapFunction": "companionChangedBy",
+    "wrapOperation": "create",
+    "wrapCallExpr": "companionChangedBy({'taskCount': 3}, {'taskCount': 4}, 'taskCount', 1)"
+  },
+  {
+    "description": "companionChangedBy allows an exact negative delta",
+    "expectation": "ALLOW",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "alice"
+    },
+    "data": {
+      "x": 1
+    },
+    "wrapFunction": "companionChangedBy",
+    "wrapOperation": "create",
+    "wrapCallExpr": "companionChangedBy({'n': 2}, {'n': 1}, 'n', -1)"
+  },
+  {
+    "description": "companionChangedBy denies a wrong delta",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "alice"
+    },
+    "data": {
+      "x": 1
+    },
+    "wrapFunction": "companionChangedBy",
+    "wrapOperation": "create",
+    "wrapCallExpr": "companionChangedBy({'taskCount': 3}, {'taskCount': 5}, 'taskCount', 1)"
+  },
+  {
+    "description": "companionChangedBy denies an unchanged companion (solo write: after == before)",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "alice"
+    },
+    "data": {
+      "x": 1
+    },
+    "wrapFunction": "companionChangedBy",
+    "wrapOperation": "create",
+    "wrapCallExpr": "companionChangedBy({'taskCount': 3}, {'taskCount': 3}, 'taskCount', 1)"
+  },
+  {
+    "description": "companionChangedBy denies a missing companion field (null-on-miss)",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "alice"
+    },
+    "data": {
+      "x": 1
+    },
+    "wrapFunction": "companionChangedBy",
+    "wrapOperation": "create",
+    "wrapCallExpr": "companionChangedBy({'other': 1}, {'other': 1}, 'taskCount', 1)"
+  },
+  {
+    "description": "consumedFlag allows false -> true consumption",
+    "expectation": "ALLOW",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "alice"
+    },
+    "data": {
+      "x": 1
+    },
+    "wrapFunction": "consumedFlag",
+    "wrapOperation": "create",
+    "wrapCallExpr": "consumedFlag({'used': false}, {'used': true}, 'used')"
+  },
+  {
+    "description": "consumedFlag denies a replay (already consumed before the batch)",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "alice"
+    },
+    "data": {
+      "x": 1
+    },
+    "wrapFunction": "consumedFlag",
+    "wrapOperation": "create",
+    "wrapCallExpr": "consumedFlag({'used': true}, {'used': true}, 'used')"
+  },
+  {
+    "description": "consumedFlag denies a solo write (after == before == false)",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "alice"
+    },
+    "data": {
+      "x": 1
+    },
+    "wrapFunction": "consumedFlag",
+    "wrapOperation": "create",
+    "wrapCallExpr": "consumedFlag({'used': false}, {'used': false}, 'used')"
+  },
+  {
+    "description": "consumedFlag denies un-consuming (true -> false)",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "alice"
+    },
+    "data": {
+      "x": 1
+    },
+    "wrapFunction": "consumedFlag",
+    "wrapOperation": "create",
+    "wrapCallExpr": "consumedFlag({'used': true}, {'used': false}, 'used')"
+  },
+  {
+    "description": "consumedFlag denies a missing flag field",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "alice"
+    },
+    "data": {
+      "x": 1
+    },
+    "wrapFunction": "consumedFlag",
+    "wrapOperation": "create",
+    "wrapCallExpr": "consumedFlag({}, {}, 'used')"
+  }
+]

package/dist/rules/modules/stdlib/auth.rules

@@ -0,0 +1,7 @@
+export function isAuthenticated() {
+  return request.auth != null;
+}
+
+export function isOwner(userId) {
+  return isAuthenticated() && request.auth.uid == userId;
+}

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

@@ -0,0 +1,53 @@
+[
+  {
+    "description": "isAuthenticated allows authenticated user",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": { "uid": "user1" },
+    "wrapFunction": "isAuthenticated",
+    "wrapOperation": "read"
+  },
+  {
+    "description": "isAuthenticated denies unauthenticated user",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": null,
+    "wrapFunction": "isAuthenticated",
+    "wrapOperation": "read"
+  },
+  {
+    "description": "isOwner allows when uid matches",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "test/user1",
+    "auth": { "uid": "user1" },
+    "wrapFunction": "isOwner",
+    "wrapArgs": ["userId"],
+    "wrapOperation": "read",
+    "wrapMatch": "/test/{userId}"
+  },
+  {
+    "description": "isOwner denies when uid does not match",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "test/user2",
+    "auth": { "uid": "user1" },
+    "wrapFunction": "isOwner",
+    "wrapArgs": ["userId"],
+    "wrapOperation": "read",
+    "wrapMatch": "/test/{userId}"
+  },
+  {
+    "description": "isOwner denies unauthenticated user",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "test/user1",
+    "auth": null,
+    "wrapFunction": "isOwner",
+    "wrapArgs": ["userId"],
+    "wrapOperation": "read",
+    "wrapMatch": "/test/{userId}"
+  }
+]

package/dist/rules/modules/stdlib/content.rules

@@ -0,0 +1,50 @@
+// Content module for author-owned documents — the most common
+// Firebase app shape (posts, notes, docs, comments, tasks).
+//
+// Convention: documents carry an author field (a UID string) and
+// usually a status field ('draft' | 'published' | ...). Field names
+// are parameters, not conventions — pass yours.
+//
+// Usage:
+//   import { validAuthorCreate, isAuthor, canReadContent, notDeleted } from 'content';
+//   import { onlyFieldsChanged } from 'lifecycle';
+//
+//   match /posts/{postId} {
+//     // Create: author is the signed-in user.
+//     allow create: if validAuthorCreate('author');
+//     // Read: published to everyone, drafts to the author only.
+//     allow read: if canReadContent('status', 'author') && notDeleted();
+//     // Update: author edits content fields; authorship immutable.
+//     allow update: if isAuthor('author') && onlyFieldsChanged(['title', 'body', 'status']);
+//     allow delete: if isAuthor('author');
+//   }
+
+// Create guard: signed in, and the incoming doc's author field is the
+// caller. Use on `create` (reads request.resource).
+export function validAuthorCreate(authorField) {
+  return request.auth != null
+    && request.resource.data[authorField] == request.auth.uid;
+}
+
+// The caller is the EXISTING document's author. Use on update/delete
+// (reads resource).
+export function isAuthor(authorField) {
+  return request.auth != null
+    && resource.data[authorField] == request.auth.uid;
+}
+
+// Read visibility: published content is public; anything else is
+// visible to its author only. Works for get; for list queries the
+// client must filter (rules are not filters — a bare collection query
+// will be denied unless it proves status == 'published').
+export function canReadContent(statusField, authorField) {
+  return resource.data[statusField] == 'published'
+    || (request.auth != null && resource.data[authorField] == request.auth.uid);
+}
+
+// Soft-delete guard: the document is not marked deleted. Reads the
+// EXISTING doc; a doc without the field passes — bracket access is
+// the null-on-miss idiom (dotted access of a missing key ERRORS).
+export function notDeleted() {
+  return resource.data['deleted'] != true;
+}

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

@@ -0,0 +1,238 @@
+[
+  {
+    "description": "validAuthorCreate allows when author is the caller",
+    "expectation": "ALLOW",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "validAuthorCreate",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validAuthorCreate('author')",
+    "data": {
+      "author": "user1",
+      "title": "hi"
+    }
+  },
+  {
+    "description": "validAuthorCreate denies when author is someone else",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "validAuthorCreate",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validAuthorCreate('author')",
+    "data": {
+      "author": "user2",
+      "title": "hi"
+    }
+  },
+  {
+    "description": "validAuthorCreate denies unauthenticated",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": null,
+    "wrapFunction": "validAuthorCreate",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validAuthorCreate('author')",
+    "data": {
+      "author": "user1"
+    }
+  },
+  {
+    "description": "validAuthorCreate denies missing author field",
+    "expectation": "DENY",
+    "method": "create",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "validAuthorCreate",
+    "wrapOperation": "create",
+    "wrapCallExpr": "validAuthorCreate('author')",
+    "data": {
+      "title": "hi"
+    }
+  },
+  {
+    "description": "isAuthor allows the existing doc's author",
+    "expectation": "ALLOW",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "isAuthor",
+    "wrapOperation": "update",
+    "wrapCallExpr": "isAuthor('author')",
+    "resource": {
+      "author": "user1",
+      "title": "old"
+    },
+    "data": {
+      "author": "user1",
+      "title": "new"
+    }
+  },
+  {
+    "description": "isAuthor denies a non-author",
+    "expectation": "DENY",
+    "method": "update",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "isAuthor",
+    "wrapOperation": "update",
+    "wrapCallExpr": "isAuthor('author')",
+    "resource": {
+      "author": "user2",
+      "title": "old"
+    },
+    "data": {
+      "author": "user2",
+      "title": "new"
+    }
+  },
+  {
+    "description": "isAuthor denies unauthenticated",
+    "expectation": "DENY",
+    "method": "delete",
+    "path": "test/doc1",
+    "auth": null,
+    "wrapFunction": "isAuthor",
+    "wrapOperation": "delete",
+    "wrapCallExpr": "isAuthor('author')",
+    "resource": {
+      "author": "user1"
+    }
+  },
+  {
+    "description": "canReadContent allows anyone to read published",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "stranger"
+    },
+    "wrapFunction": "canReadContent",
+    "wrapOperation": "get",
+    "wrapCallExpr": "canReadContent('status', 'author')",
+    "resource": {
+      "status": "published",
+      "author": "user2"
+    }
+  },
+  {
+    "description": "canReadContent allows unauthenticated read of published",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": null,
+    "wrapFunction": "canReadContent",
+    "wrapOperation": "get",
+    "wrapCallExpr": "canReadContent('status', 'author')",
+    "resource": {
+      "status": "published",
+      "author": "user2"
+    }
+  },
+  {
+    "description": "canReadContent allows the author to read a draft",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "canReadContent",
+    "wrapOperation": "get",
+    "wrapCallExpr": "canReadContent('status', 'author')",
+    "resource": {
+      "status": "draft",
+      "author": "user1"
+    }
+  },
+  {
+    "description": "canReadContent denies a stranger reading a draft",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "canReadContent",
+    "wrapOperation": "get",
+    "wrapCallExpr": "canReadContent('status', 'author')",
+    "resource": {
+      "status": "draft",
+      "author": "user2"
+    }
+  },
+  {
+    "description": "canReadContent denies unauthenticated read of a draft",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": null,
+    "wrapFunction": "canReadContent",
+    "wrapOperation": "get",
+    "wrapCallExpr": "canReadContent('status', 'author')",
+    "resource": {
+      "status": "draft",
+      "author": "user2"
+    }
+  },
+  {
+    "description": "notDeleted allows when deleted flag is false",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "notDeleted",
+    "wrapOperation": "get",
+    "wrapCallExpr": "notDeleted()",
+    "resource": {
+      "deleted": false,
+      "title": "x"
+    }
+  },
+  {
+    "description": "notDeleted allows when the field is absent (null-on-miss)",
+    "expectation": "ALLOW",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "notDeleted",
+    "wrapOperation": "get",
+    "wrapCallExpr": "notDeleted()",
+    "resource": {
+      "title": "x"
+    }
+  },
+  {
+    "description": "notDeleted denies a soft-deleted doc",
+    "expectation": "DENY",
+    "method": "get",
+    "path": "test/doc1",
+    "auth": {
+      "uid": "user1"
+    },
+    "wrapFunction": "notDeleted",
+    "wrapOperation": "get",
+    "wrapCallExpr": "notDeleted()",
+    "resource": {
+      "deleted": true,
+      "title": "x"
+    }
+  }
+]

package/dist/rules/modules/stdlib/counters.rules

@@ -0,0 +1,41 @@
+// Counters module for denormalized numeric integrity.
+//
+// The recurring shape: a client-maintained count (likes, votes, moves,
+// quantities) that rules must keep honest — it may only change by a
+// known step, or stay within known bounds. Generalizes the
+// state-module's moveIncremented() (hardcoded to moveCount) to any
+// field.
+//
+// Usage:
+//   import { incrementedBy, changedBy, boundedNumber } from 'counters';
+//
+//   // A like toggle: likeCount moves by exactly ±1:
+//   allow update: if changedBy('likeCount', -1, 1);
+//
+//   // A move counter: strictly +1 per move:
+//   allow update: if incrementedBy('moveCount', 1);
+//
+//   // A rating: any write keeps it in [1, 5]:
+//   allow write: if boundedNumber('rating', 1, 5);
+
+// The field changed by EXACTLY n relative to the existing document.
+// n may be negative (decrement). Update rules only (needs resource).
+export function incrementedBy(field, n) {
+  return request.resource.data[field] == resource.data[field] + n;
+}
+
+// The field's delta is within [min, max] (inclusive) — and it is NOT
+// required to change (delta 0 passes when min <= 0 <= max).
+export function changedBy(field, min, max) {
+  return request.resource.data[field] - resource.data[field] >= min
+    && request.resource.data[field] - resource.data[field] <= max;
+}
+
+// The incoming value is a number within [min, max] (inclusive).
+// Works on create and update. Missing field reads null (dynamic
+// access) and fails the type check rather than erroring.
+export function boundedNumber(field, min, max) {
+  return (request.resource.data[field] is int || request.resource.data[field] is float)
+    && request.resource.data[field] >= min
+    && request.resource.data[field] <= max;
+}