pyric 0.1.0-alpha.21 → 0.1.0-alpha.24

package/src/storage/sandbox/rules-evaluator.ts

@@ -1,3 +1,4 @@
+import { FirestoreSet } from '../../rules/simulator/firestore-set.js';
 import { RulesFloat } from '../../rules/simulator/wrappers/float.js';
 import {
   expandVerb,
@@ -10,7 +11,16 @@ import {
   type StorageResource,
   type StorageRules,
 } from './rules.js';
+import { buildRequestObject, buildResourceObject } from './rules-bindings.js';
 import { evalMethodCall } from './rules-methods.js';
+import {
+  cmp,
+  evalValueOperator,
+  isFloatNum,
+  isValueTypeOperand,
+  numOp,
+  typeMatches,
+} from './rules-operators.js';
 import { formatPath, matchSegments, splitPath } from './rules-path-match.js';
 import {
   RuleEvalError,
@@ -33,10 +43,10 @@ export function evaluateStorageRules(
   now: Date = new Date(),
   firestoreLookup?: FirestoreLookup,
 ): EvaluationResult {
-  // `request.time` is the request's evaluation moment, modeled internally
-  // as epoch milliseconds so it compares numerically against the
-  // `timestamp.date(...)` / `timestamp.value(...)` constructors. The caller
-  // injects it (deterministic in tests); it defaults to now.
+  // `request.time` is the request's evaluation moment. The caller injects it
+  // (deterministic in tests); it defaults to now. The request binding turns
+  // it into the Timestamp value `timestamp.date(...)` and
+  // `timestamp.value(...)` also build.
   const nowMillis = now.getTime();
   const pathSegments = splitPath(input.request.path);
   const reasons: string[] = [];
@@ -76,32 +86,43 @@ export function evaluateStorageRules(
         if (!applies) continue;
         let result: boolean;
         try {
-          const value = rule.condition
-            ? evalExpr(rule.condition, {
-                input,
-                now: nowMillis,
-                params: newParams,
-                locals: {},
-                funcs: block.visibleFuncs ?? new Map(),
-                depth: 0,
-                firestoreLookup,
-                firestoreAccesses,
-              })
-            : true;
-          // An error value reaching the allow boundary DENIES, carrying
-          // production's own message (e.g. "Property name is undefined on
-          // object.") into the reason trace.
-          if (isErr(value)) {
+          let value: unknown = true;
+          if (rule.condition) {
+            value = evalExpr(rule.condition, {
+              input,
+              now: nowMillis,
+              params: newParams,
+              locals: {},
+              funcs: block.visibleFuncs ?? new Map(),
+              depth: 0,
+              firestoreLookup,
+              firestoreAccesses,
+            });
+          }
+          if (typeof value === 'boolean') {
+            result = value;
+          } else {
+            // Not a bool. Either the expression already produced an evaluation
+            // error, or CEL's boolean typing of the allow boundary makes one
+            // here: the same `RuleError` the ternary condition raises, rather
+            // than a truthiness coercion. Both DENY this rule with production's
+            // own message in the reason trace and continue to the next rule.
+            // Registry rows
+            // `storage-rules#storage.semantic.strict-boolean-allow-boundary`
+            // and `storage-rules#storage.semantic.strict-boolean-ternary-condition`
+            // carry the claim; corpus scenario
+            // `strict-boolean-allow-and-ternary` is the capture that verifies it.
+            let failure: RuleError;
+            if (isErr(value)) {
+              failure = value;
+            } else {
+              failure = new RuleError(`Allow condition expected bool, got ${describeType(value)}.`);
+            }
             reasons.push(
-              `match ${formatPath(block.segments)} ${input.request.method}: ${value.message}`,
+              `match ${formatPath(block.segments)} ${input.request.method}: ${failure.message}`,
             );
             continue;
           }
-          // Unverified: production's behavior for a non-boolean allow
-          // condition (a CEL type error there, rather than this truthiness
-          // coercion) has not been captured. The coercion stays as written
-          // until a production capture settles it.
-          result = truthy(value);
         } catch (err) {
           // Any function-evaluation failure (undefined function, wrong
           // arity, depth exceeded, error inside a body) denies this rule
@@ -149,13 +170,6 @@ function readProperty(obj: unknown, name: string): unknown {
   return v;
 }
 
-function truthy(v: unknown): boolean {
-  // An error value is never truthy: it denies. (Without this, a `RuleError`
-  // object would be truthy and every absent-property read would FALSE-ALLOW.)
-  if (isErr(v)) return false;
-  return v !== false && v !== null && v !== undefined && !(typeof v === 'number' && Number.isNaN(v));
-}
-
 /**
  * Raised when a user-defined function cannot be evaluated (undefined,
  * wrong arity, call depth exceeded, or an error surfacing from within a
@@ -173,8 +187,8 @@ const MAX_CALL_DEPTH = 20;
 /** Everything an expression needs to evaluate. */
 export interface EvalCtx {
   input: EvaluationInput;
-  /** `request.time` as epoch milliseconds (injected by the caller,
-   *  defaulting to evaluation-time now). */
+  /** The evaluation instant in epoch milliseconds (injected by the caller,
+   *  defaulting to evaluation-time now); `request.time` is its Timestamp. */
   now: number;
   /** Path wildcards from the enclosing match. Empty inside a function
    *  body: caller wildcards do not leak in except via arguments. */
@@ -277,11 +291,15 @@ export function evalExpr(expr: Expr, ctx: EvalCtx): unknown {
       // An error condition denies the whole conditional; it must not fall
       // through to the alternate branch and potentially allow.
       if (isErr(c)) return c;
-      // Unverified: production's behavior for a non-boolean ternary
-      // condition (a CEL type error there, rather than this truthiness
-      // coercion) has not been captured. The coercion stays as written
-      // until a production capture settles it.
-      return truthy(c) ? evalExpr(expr.then, ctx) : evalExpr(expr.else, ctx);
+      // CEL types the condition as bool. A non-boolean condition is an
+      // evaluation error, which `&&` and `||` absorb like any other. Registry
+      // row `storage-rules#storage.semantic.strict-boolean-ternary-condition`
+      // carries the claim; corpus scenario `strict-boolean-allow-and-ternary`
+      // is the capture that would verify it.
+      if (typeof c !== 'boolean') {
+        return new RuleError(`Ternary condition expected bool, got ${describeType(c)}.`);
+      }
+      return c ? evalExpr(expr.then, ctx) : evalExpr(expr.else, ctx);
     }
     case 'in': {
       const el = evalExpr(expr.element, ctx);
@@ -293,8 +311,9 @@ export function evalExpr(expr: Expr, ctx: EvalCtx): unknown {
       // live-pinned by rules-firestore-prototype-chain-keys), so JS `in`
       // (which walks the prototype chain) would false-ALLOW here.
       if (Array.isArray(coll)) return coll.some((v) => rulesEquals(v, el));
+      if (coll instanceof FirestoreSet) return coll.hasAll([el]);
       if (isRulesMap(coll)) return typeof el === 'string' && Object.prototype.hasOwnProperty.call(coll, el);
-      return new RuleError(`'in' applied to ${describeType(coll)} (expected a list or map).`);
+      return new RuleError(`'in' applied to ${describeType(coll)} (expected a list, set, or map).`);
     }
     case 'is': {
       const v = evalExpr(expr.value, ctx);
@@ -354,6 +373,11 @@ export function evalExpr(expr: Expr, ctx: EvalCtx): unknown {
       if (isErr(l)) return l;
       const r = evalExpr(expr.right, ctx);
       if (isErr(r)) return r;
+      // Timestamp, Duration, and Bytes operands own their comparison and
+      // arithmetic operators; equality stays with rulesEquals below.
+      if (expr.op !== '==' && expr.op !== '!=' && (isValueTypeOperand(l) || isValueTypeOperand(r))) {
+        return evalValueOperator(expr.op, l, r);
+      }
       switch (expr.op) {
         // Lists and maps compare STRUCTURALLY (production `[a] == [a]` is true;
         // JS reference identity would make every literal comparison
@@ -501,104 +525,3 @@ function evalCall(expr: Extract<Expr, { kind: 'call' }>, ctx: EvalCtx): unknown
   }
   return evalExpr(fn.body, bodyCtx);
 }
-
-/**
- * `value is <type>` check. Numbers use the RULES-B5 model: a `RulesFloat`
- * wrapper is a FLOAT, a bare number is an INT — so `1.0 is float` and
- * `!(1.0 is int)` type by literal form exactly as production does. A bare
- * NON-integral number (a fractional value that arrived from data rather than
- * a literal, e.g. a Firestore-lookup double) still reads as float. `number`
- * accepts either.
- */
-function typeMatches(v: unknown, typeName: string): boolean | RuleError {
-  switch (typeName) {
-    case 'string': return typeof v === 'string';
-    case 'bool': return typeof v === 'boolean';
-    case 'int': return typeof v === 'number' && Number.isInteger(v);
-    case 'float': return v instanceof RulesFloat || (typeof v === 'number' && !Number.isInteger(v));
-    case 'number': return v instanceof RulesFloat || typeof v === 'number';
-    case 'list': return Array.isArray(v);
-    case 'map': return isRulesMap(v);
-    default:
-      // timestamp/duration/path/latlng are modeled as plain millis/strings
-      // here — a type test against them cannot answer honestly, so deny
-      // with a reason rather than false-allow.
-      return new RuleError(`'is ${typeName}' is not supported by the storage evaluator.`);
-  }
-}
-
-/** Raw numeric value of an int (bare number) or float (RulesFloat); undefined
- *  for anything else. */
-function isFloatNum(v: unknown): boolean {
-  return v instanceof RulesFloat;
-}
-
-function cmp(a: unknown, b: unknown): number {
-  const an = numVal(a);
-  const bn = numVal(b);
-  // CEL compares int and float by numeric value (`1 < 1.5` is well-typed).
-  if (an !== undefined && bn !== undefined) return an - bn;
-  if (typeof a === 'string' && typeof b === 'string') return a < b ? -1 : a > b ? 1 : 0;
-  return Number.NaN; // mismatched types → NaN → all comparisons return false
-}
-
-/** Arithmetic over ints and floats: unwraps, computes, and RE-TAGS the result
- *  as a float when either operand was one (int op float promotes to float). */
-function numOp(a: unknown, b: unknown, fn: (x: number, y: number) => number): unknown {
-  const an = numVal(a);
-  const bn = numVal(b);
-  if (an === undefined || bn === undefined) return undefined;
-  const result = fn(an, bn);
-  return isFloatNum(a) || isFloatNum(b) ? new RulesFloat(result) : result;
-}
-
-/**
- * Build the `resource.*` binding from the existing-object record, converting
- * the ISO-8601 time fields to epoch millis so they compare numerically against
- * `request.time` (which {@link buildRequestObject} models the same way) and
- * against each other (`resource.timeCreated == resource.updated`).
- *
- * A field the record does not carry is left `undefined`, which
- * {@link readProperty} reports as production's absent-property ERROR.
- */
-function buildResourceObject(resource: StorageResource): Record<string, unknown> {
-  return {
-    size: resource.size,
-    contentType: resource.contentType,
-    metadata: resource.metadata,
-    name: resource.name,
-    bucket: resource.bucket,
-    generation: resource.generation,
-    metageneration: resource.metageneration,
-    timeCreated: isoToMillis(resource.timeCreated),
-    updated: isoToMillis(resource.updated),
-  };
-}
-
-/** ISO-8601 → epoch millis. An unparseable or absent value stays `undefined`
- *  (→ absent-property error → deny) rather than becoming `NaN`. */
-function isoToMillis(iso: string | undefined): number | undefined {
-  if (iso === undefined) return undefined;
-  const ms = Date.parse(iso);
-  return Number.isNaN(ms) ? undefined : ms;
-}
-
-function buildRequestObject(input: EvaluationInput, now: number): Record<string, unknown> {
-  return {
-    // The production Storage engine represents anonymous auth as an absent
-    // property, not a usable null value. Ordinary `request.auth != null`
-    // gates still deny, while conditionals cannot incorrectly select a
-    // fallback branch from the synthetic null.
-    auth: input.request.auth ?? new RuleError('Property auth is undefined on object.'),
-    // Production treats an operation without an incoming object (notably
-    // delete/read) as an absent binding. A direct null comparison errors just
-    // like a property read; neither may turn the missing value into an allow.
-    resource: input.request.resource ?? new RuleError('Property resource is undefined on object.'),
-    method: input.request.method,
-    path: input.request.path,
-    // `request.time` as epoch millis — see the timestamp constructors in
-    // `evalMethodCall`, which produce the same representation so comparisons
-    // like `request.time < timestamp.date(2030, 1, 1)` are plain numerics.
-    time: now,
-  };
-}

package/src/storage/sandbox/rules-firestore-lookup.ts

@@ -0,0 +1,112 @@
+import type { Expr } from './rules.js';
+import { evalExpr, type EvalCtx } from './rules-evaluator.js';
+import {
+  RuleEvalError,
+  RuleResourceLimitError,
+  RuleUnsupportedError,
+} from './rules-evaluation-error.js';
+import { RuleError, describeRulesType as describeType } from './rules-values.js';
+
+type MethodCall = Extract<Expr, { kind: 'methodcall' }>;
+
+/**
+ * Evaluate `firestore.get(path)` / `firestore.exists(path)`.
+ *
+ * Requires an injected {@link FirestoreLookup} (the enforcement layer
+ * supplies one from the sandbox's Firestore data). With NO capability —
+ * pure/test usage without a sandbox — this denies with an "unsupported"
+ * reason rather than ever a false allow, preserving the pre-lookup posture.
+ *
+ * Semantics (production-honest, deny-on-error):
+ *   - `firestore.get(path)` → a resource `{ data: <fields> }`. Member access
+ *     `.data.<field>` then reads the doc's fields. On a NONEXISTENT doc,
+ *     production `get()` is itself an error, so this denies with a reason.
+ *   - `firestore.exists(path)` → boolean.
+ *   - Malformed path (missing `/databases/<db>/documents/` prefix, odd
+ *     segment count), a non-string interpolation, wrong arg count, or a
+ *     non-path argument → deny with a reason.
+ */
+export function evalFirestoreBuiltin(expr: MethodCall, ctx: EvalCtx): unknown {
+  if (expr.method !== 'get' && expr.method !== 'exists') {
+    // Unknown namespace method, compile-reject class, never absorbed.
+    throw new RuleUnsupportedError(`unsupported method firestore.${expr.method}()`);
+  }
+  if (!ctx.firestoreLookup) {
+    // No sandbox-backed capability injected — keep the deny-with-reason
+    // "unsupported" behavior; never a false allow.
+    throw new RuleEvalError(
+      `firestore.${expr.method}() is unsupported here — no Firestore lookup capability is configured`,
+    );
+  }
+  if (expr.args.length !== 1) {
+    // Wrong call shape: production rejects at compile; never absorbed.
+    throw new RuleUnsupportedError(`firestore.${expr.method}() expects a single path argument`);
+  }
+  const arg = expr.args[0];
+  if (arg.kind !== 'path') {
+    throw new RuleUnsupportedError(`firestore.${expr.method}() requires a /databases/.../documents/... path literal`);
+  }
+  const docPath = buildFirestoreDocPath(arg, ctx);
+  if (!ctx.firestoreAccesses.has(docPath)) {
+    if (ctx.firestoreAccesses.size >= 2) {
+      // Resource-limit class, the same posture as the Firestore lookup
+      // budget: production fails the whole evaluation closed, so a
+      // determining &&/|| operand must NOT absorb this into an allow.
+      throw new RuleResourceLimitError('firestore access limit exceeded: at most two distinct documents');
+    }
+    ctx.firestoreAccesses.add(docPath);
+  }
+  if (expr.method === 'exists') {
+    return ctx.firestoreLookup.exists(docPath);
+  }
+  const fields = ctx.firestoreLookup.get(docPath);
+  if (fields === null) {
+    // A missing get is a Rules error VALUE: it denies at the allow boundary,
+    // but participates in COMMUTATIVE CEL error absorption in `&&`/`||`
+    // (`error || true` allows, and `error && false` evaluates to false,
+    // see the tri-state operand handling in rules-evaluator.ts).
+    return new RuleError(`firestore.get() targeted a nonexistent document: ${docPath}`);
+  }
+  return { data: fields };
+}
+
+/**
+ * Assemble a {@link PathArgSegment} list into the document path the
+ * {@link FirestoreLookup} expects, then validate + strip the required
+ * `/databases/<db>/documents/` prefix. Interpolations must resolve to a
+ * string or number; anything else (e.g. `request.auth.uid` when auth is
+ * null → undefined) throws → deny.
+ */
+function buildFirestoreDocPath(
+  pathExpr: Extract<Expr, { kind: 'path' }>,
+  ctx: EvalCtx,
+): string {
+  const parts = pathExpr.segments.map((seg) => {
+    if (seg.kind === 'literal') return seg.value;
+    const v = evalExpr(seg.expr, ctx);
+    if (typeof v === 'string') return v;
+    if (typeof v === 'number') return String(v);
+    throw new RuleEvalError(
+      `Firestore path interpolation resolved to ${describeType(v)} (expected a string)`,
+    );
+  });
+  // Required production shape: databases / <db> / documents / <doc path…>.
+  if (parts.length < 4 || parts[0] !== 'databases' || parts[2] !== 'documents') {
+    throw new RuleEvalError(
+      `malformed Firestore path — expected /databases/<db>/documents/... , got /${parts.join('/')}`,
+    );
+  }
+  if (parts[1] !== '(default)') {
+    throw new RuleEvalError(
+      `Storage rules may access only the default Firestore database, got ${parts[1]}`,
+    );
+  }
+  const docSegments = parts.slice(3);
+  // A document path is collection/doc pairs — an even, non-zero segment count.
+  if (docSegments.length === 0 || docSegments.length % 2 !== 0) {
+    throw new RuleEvalError(
+      `Firestore path does not point at a document (needs an even segment count): ${docSegments.join('/')}`,
+    );
+  }
+  return docSegments.join('/');
+}

package/src/storage/sandbox/rules-hashing-methods.ts

@@ -0,0 +1,50 @@
+import { evaluateHashingMethod } from '../../rules/simulator/hashing-builtins.js';
+import { Bytes } from '../../rules/simulator/wrappers/bytes.js';
+import type { EvalCtx } from './rules-evaluator.js';
+import { RuleEvalError, RuleUnsupportedError } from './rules-evaluation-error.js';
+import {
+  evalArguments,
+  evalValueMethod,
+  type MethodCall,
+  type ReceiverMethods,
+} from './rules-method-calls.js';
+import { describeRulesType as describeType, isRuleError as isErr } from './rules-values.js';
+
+/** The digests the `hashing` namespace defines. */
+const HASHING_FUNCTIONS = new Set(['crc32', 'crc32c', 'md5', 'sha256']);
+
+/**
+ * `hashing.md5(value)`, `hashing.sha256(value)`, `hashing.crc32(value)`, and
+ * `hashing.crc32c(value)` over a string (hashed as its UTF-8 bytes) or Bytes,
+ * returning Bytes. Another argument type is production's "Unsupported
+ * operation error", captured for `hashing.md5(int)`.
+ */
+export function evalHashingNamespace(expr: MethodCall, ctx: EvalCtx): unknown {
+  if (!HASHING_FUNCTIONS.has(expr.method)) {
+    // A name outside the namespace is a compile-reject class: never absorbed.
+    throw new RuleUnsupportedError(`unsupported method hashing.${expr.method}()`);
+  }
+  const args = evalArguments(expr, ctx);
+  if (isErr(args)) return args;
+  if (args.length !== 1) {
+    throw new RuleEvalError(`hashing.${expr.method}() expects a single string or bytes argument`);
+  }
+  const [input] = args;
+  if (typeof input !== 'string' && !(input instanceof Bytes)) {
+    throw new RuleEvalError(
+      `Unsupported operation error. Received: hashing.${expr.method}(${describeType(input)}). `
+        + `Expected: hashing.${expr.method}(bytes), hashing.${expr.method}(string).`,
+    );
+  }
+  return evaluateHashingMethod(expr.method, [input]);
+}
+
+/**
+ * The Bytes encodings, answered by the value itself: `toBase64()` is padded
+ * base64url and `toHexString()` is uppercase hexadecimal. `size()` lives with
+ * the other sized types.
+ */
+export const bytesMethods: ReceiverMethods = {
+  toBase64: evalValueMethod,
+  toHexString: evalValueMethod,
+};

package/src/storage/sandbox/rules-method-calls.ts

@@ -0,0 +1,67 @@
+import { NO_OP, RulesValue } from '../../rules/simulator/wrappers/base.js';
+import type { Expr } from './rules.js';
+import { evalExpr, type EvalCtx } from './rules-evaluator.js';
+import { RuleEvalError } from './rules-evaluation-error.js';
+import { isRuleError as isErr, type RuleError } from './rules-values.js';
+
+export type MethodCall = Extract<Expr, { kind: 'methodcall' }>;
+
+/**
+ * Evaluates `<receiver>.<method>(args)` for one method name. The dispatcher
+ * evaluates the receiver first and passes its value; an error receiver never
+ * reaches a method.
+ */
+export type ReceiverMethod = (receiver: unknown, expr: MethodCall, ctx: EvalCtx) => unknown;
+
+/** Method name to evaluator, one record per concern file. */
+export type ReceiverMethods = Readonly<Record<string, ReceiverMethod>>;
+
+/**
+ * Evaluates `<namespace>.<method>(args)` for a builtin namespace such as
+ * `timestamp` or `hashing`.
+ */
+export type NamespaceMethod = (expr: MethodCall, ctx: EvalCtx) => unknown;
+
+/**
+ * Production's error for a method its receiver type does not define, such as
+ * `resource.size.hours()`. It is an evaluation error, so a determining
+ * `&&`/`||` operand absorbs it (rules-storage-stdlib-timestamp-duration
+ * captures `resource.size.year() == 1970 || true` allowing).
+ */
+export function functionNotFound(method: string): RuleEvalError {
+  return new RuleEvalError(`Function not found error: Name: [${method}].`);
+}
+
+/** Deny a call that passes arguments to a method that takes none. */
+export function expectNoArguments(expr: MethodCall): void {
+  if (expr.args.length !== 0) {
+    throw new RuleEvalError(`${expr.method}() expects no arguments`);
+  }
+}
+
+/** Evaluate every argument in order; the first error value wins. */
+export function evalArguments(expr: MethodCall, ctx: EvalCtx): unknown[] | RuleError {
+  const values: unknown[] = [];
+  for (const arg of expr.args) {
+    const value = evalExpr(arg, ctx);
+    if (isErr(value)) return value;
+    values.push(value);
+  }
+  return values;
+}
+
+/**
+ * A no-argument method a Timestamp, Duration, or Bytes value answers for
+ * itself through `callMethod`: the timestamp accessors, `seconds()` and
+ * `nanos()` on a duration, and the Bytes encodings. Any other receiver, or a
+ * value that does not define the method, is production's function-not-found
+ * error.
+ */
+export function evalValueMethod(receiver: unknown, expr: MethodCall): unknown {
+  expectNoArguments(expr);
+  if (receiver instanceof RulesValue) {
+    const result = receiver.callMethod(expr.method, []);
+    if (result !== NO_OP) return result;
+  }
+  throw functionNotFound(expr.method);
+}