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

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

@@ -0,0 +1,214 @@
+import { Bytes } from '../../rules/simulator/wrappers/bytes.js';
+import type { EvalCtx } from './rules-evaluator.js';
+import { RuleEvalError } from './rules-evaluation-error.js';
+import {
+  evalArguments,
+  expectNoArguments,
+  functionNotFound,
+  type MethodCall,
+  type ReceiverMethods,
+} from './rules-method-calls.js';
+import { isRuleError as isErr, type RuleError } from './rules-values.js';
+
+/** The receiver as a string, or production's function-not-found error. */
+function stringReceiver(receiver: unknown, expr: MethodCall): string {
+  if (typeof receiver !== 'string') throw functionNotFound(expr.method);
+  return receiver;
+}
+
+/** The single string argument of `matches()` and `split()`. */
+function patternArgument(expr: MethodCall, ctx: EvalCtx): string | RuleError {
+  if (expr.args.length !== 1) {
+    throw new RuleEvalError(`${expr.method}() expects a single pattern argument`);
+  }
+  const args = evalArguments(expr, ctx);
+  if (isErr(args)) return args;
+  const [pattern] = args;
+  if (typeof pattern !== 'string') {
+    throw new RuleEvalError(`${expr.method}() pattern must be a string`);
+  }
+  return pattern;
+}
+
+/**
+ * `string.matches(re)`: regex match anchored to the WHOLE string, mirroring
+ * production Storage (which anchors implicitly, so `'abc'.matches('a')` is
+ * FALSE).
+ *
+ * RE2-vs-JS divergence (honest note): production runs RE2, we compile the
+ * pattern with JavaScript's `RegExp`. JS RegExp is a superset of RE2:
+ * backreferences (`\1`) and lookaround (`(?=`, `(?!`, `(?<=`, `(?<!`) work in
+ * JS but are UNSUPPORTED in RE2 and would fail in production. To avoid ever
+ * false-allowing on a pattern production would reject, those constructs are
+ * detected up front and denied. Invalid patterns (that even JS won't compile)
+ * also deny. A non-string receiver denies too: production would error, and
+ * an error denies.
+ */
+function evalMatches(receiver: unknown, expr: MethodCall, ctx: EvalCtx): unknown {
+  const subject = stringReceiver(receiver, expr);
+  const pattern = patternArgument(expr, ctx);
+  if (typeof pattern !== 'string') return pattern;
+  // Anchor to the whole string. `(?:...)` keeps the caller's alternations
+  // from binding past the anchors.
+  return compileRe2Pattern('matches', pattern, `^(?:${pattern})$`).test(subject);
+}
+
+/**
+ * Evaluate `string.split(re)`: RE2 regex split, the storage-rules idiom for
+ * segmenting object names (`fileId.split('-')[0:2]`). Shares matches()'s
+ * RE2-vs-JS guard: constructs RE2 rejects (backreferences, lookaround) deny
+ * with a reason rather than silently (mis)compiling under JS semantics.
+ */
+function evalSplit(receiver: unknown, expr: MethodCall, ctx: EvalCtx): unknown {
+  const subject = stringReceiver(receiver, expr);
+  const pattern = patternArgument(expr, ctx);
+  if (typeof pattern !== 'string') return pattern;
+  return subject.split(compileRe2Pattern('split', pattern, pattern));
+}
+
+/**
+ * `string.replace(pattern, replacement)`: replaces every match of the RE2
+ * pattern. The replacement follows Java `Matcher` template rules, which
+ * rules-storage-stdlib-string-bytes-hashing captures: `$n` inserts group n,
+ * `${name}` a named group, and `\c` the character c. Any other `$` is an
+ * illegal group reference and an error; production's Rules Test API answers
+ * one with HTTP 500, so the error here denies rather than guessing a value.
+ */
+function evalReplace(receiver: unknown, expr: MethodCall, ctx: EvalCtx): unknown {
+  const subject = stringReceiver(receiver, expr);
+  const args = evalArguments(expr, ctx);
+  if (isErr(args)) return args;
+  const [pattern, replacement] = args;
+  if (args.length !== 2 || typeof pattern !== 'string' || typeof replacement !== 'string') {
+    throw new RuleEvalError(`replace() expects (pattern: string, replacement: string)`);
+  }
+  const regex = compileRe2Pattern('replace', pattern, pattern, 'g');
+  const groupCount = captureGroupCount(regex);
+  return subject.replace(regex, (...match: unknown[]) => {
+    const groups = match.slice(0, groupCount + 1) as Array<string | undefined>;
+    return expandReplacement(replacement, groups, namedGroupsOf(match[match.length - 1]));
+  });
+}
+
+/** The named-groups object JavaScript passes last to a replacer, when the pattern has one. */
+function namedGroupsOf(lastReplacerArgument: unknown): Readonly<Record<string, string | undefined>> {
+  if (typeof lastReplacerArgument === 'object' && lastReplacerArgument !== null) {
+    return lastReplacerArgument as Record<string, string | undefined>;
+  }
+  return {};
+}
+
+/** Number of capture groups in `regex`, read from a match of the empty alternative. */
+function captureGroupCount(regex: RegExp): number {
+  const probe = new RegExp(`${regex.source}|`).exec('');
+  return probe === null ? 0 : probe.length - 1;
+}
+
+/**
+ * Expand a Java `Matcher` replacement template. `groups[0]` is the whole
+ * match; a group that did not participate inserts nothing.
+ */
+function expandReplacement(
+  template: string,
+  groups: ReadonlyArray<string | undefined>,
+  namedGroups: Readonly<Record<string, string | undefined>>,
+): string {
+  const groupCount = groups.length - 1;
+  let out = '';
+  let i = 0;
+  while (i < template.length) {
+    const char = template[i];
+    if (char === '\\') {
+      if (i + 1 >= template.length) {
+        throw new RuleEvalError('replace() replacement ends with an escape character');
+      }
+      out += template[i + 1];
+      i += 2;
+      continue;
+    }
+    if (char !== '$') {
+      out += char;
+      i += 1;
+      continue;
+    }
+    const next = template[i + 1];
+    if (next === '{') {
+      const close = template.indexOf('}', i + 2);
+      if (close === -1) {
+        throw new RuleEvalError(`replace() replacement has an unclosed group name: ${template.slice(i)}`);
+      }
+      const name = template.slice(i + 2, close);
+      if (!Object.hasOwn(namedGroups, name)) {
+        throw new RuleEvalError(`replace() replacement names no group: ${template.slice(i, close + 1)}`);
+      }
+      out += namedGroups[name] ?? '';
+      i = close + 1;
+      continue;
+    }
+    if (next === undefined || next < '0' || next > '9') {
+      throw new RuleEvalError(`replace() replacement has an illegal group reference: ${template.slice(i)}`);
+    }
+    // Java reads the longest digit run that still names an existing group.
+    let group = Number(next);
+    let end = i + 2;
+    while (end < template.length && template[end] >= '0' && template[end] <= '9') {
+      const longer = group * 10 + Number(template[end]);
+      if (longer > groupCount) break;
+      group = longer;
+      end += 1;
+    }
+    if (group > groupCount) {
+      throw new RuleEvalError(`replace() replacement names group ${group}, but the pattern has ${groupCount}`);
+    }
+    out += groups[group] ?? '';
+    i = end;
+  }
+  return out;
+}
+
+/** `string.lower()`, `upper()`, and `trim()`. */
+function evalCaseAndTrim(receiver: unknown, expr: MethodCall): unknown {
+  const subject = stringReceiver(receiver, expr);
+  expectNoArguments(expr);
+  if (expr.method === 'lower') return subject.toLowerCase();
+  if (expr.method === 'upper') return subject.toUpperCase();
+  return subject.trim();
+}
+
+/** `string.toUtf8()`: the string's UTF-8 encoding as Bytes. */
+function evalToUtf8(receiver: unknown, expr: MethodCall): unknown {
+  const subject = stringReceiver(receiver, expr);
+  expectNoArguments(expr);
+  return Bytes.fromUtf8(subject);
+}
+
+/**
+ * Compile a rules regular expression with JavaScript's `RegExp`. `pattern`
+ * is the caller's RE2 pattern, checked for the constructs JS accepts and RE2
+ * rejects (backreferences, lookaround); `source` is what compiles, which is
+ * `pattern` itself or an anchored wrapper around it.
+ */
+function compileRe2Pattern(method: string, pattern: string, source: string, flags?: string): RegExp {
+  const backref = /\\[1-9]/.test(pattern);
+  const lookaround = /\(\?<?[=!]/.test(pattern);
+  if (backref || lookaround) {
+    throw new RuleEvalError(
+      `${method}() pattern uses an RE2-unsupported construct (${backref ? 'backreference' : 'lookaround'}) that production would reject`,
+    );
+  }
+  try {
+    return new RegExp(source, flags);
+  } catch (err) {
+    throw new RuleEvalError(`${method}() invalid regex pattern: ${(err as Error).message}`);
+  }
+}
+
+export const stringMethods: ReceiverMethods = {
+  lower: evalCaseAndTrim,
+  matches: evalMatches,
+  replace: evalReplace,
+  split: evalSplit,
+  toUtf8: evalToUtf8,
+  trim: evalCaseAndTrim,
+  upper: evalCaseAndTrim,
+};

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

@@ -0,0 +1,98 @@
+import { Duration } from '../../rules/simulator/wrappers/duration.js';
+import { Timestamp } from '../../rules/simulator/wrappers/timestamp.js';
+import type { EvalCtx } from './rules-evaluator.js';
+import { RuleEvalError } from './rules-evaluation-error.js';
+import {
+  evalArguments,
+  evalValueMethod,
+  type MethodCall,
+  type ReceiverMethods,
+} from './rules-method-calls.js';
+import { isRuleError as isErr } from './rules-values.js';
+
+/** The units `duration.value(magnitude, unit)` accepts, per the rules language. */
+const DURATION_UNITS = ['w', 'd', 'h', 'm', 's', 'ms', 'ns'];
+
+/**
+ * `timestamp.date(year, month, day)` (UTC midnight, 1-based month) and
+ * `timestamp.value(epochMillis)`, both returning a Timestamp that compares
+ * with `request.time` and the resource time fields.
+ */
+export function evalTimestampNamespace(expr: MethodCall, ctx: EvalCtx): unknown {
+  const args = evalArguments(expr, ctx);
+  if (isErr(args)) return args;
+  if (expr.method === 'value') {
+    if (args.length !== 1 || typeof args[0] !== 'number') {
+      throw new RuleEvalError(`timestamp.value() expects (epochMillis: number)`);
+    }
+    return Timestamp.fromMillis(args[0]);
+  }
+  if (expr.method === 'date') {
+    if (args.length !== 3 || !args.every((a) => typeof a === 'number')) {
+      throw new RuleEvalError(`timestamp.date() expects (year, month, day) numbers`);
+    }
+    const [year, month, day] = args as [number, number, number];
+    return Timestamp.fromYMD(year, month, day);
+  }
+  throw new RuleEvalError(`unsupported timestamp.${expr.method}()`);
+}
+
+/**
+ * `duration.value(magnitude, unit)`, `duration.time(hours, minutes, seconds,
+ * nanos)`, and `duration.abs(duration)`, each returning a Duration. A
+ * timestamp plus a duration is a timestamp, which is the freshness idiom
+ * production accepts:
+ *
+ *   request.time < resource.timeCreated + duration.value(1, 'h')
+ */
+export function evalDurationNamespace(expr: MethodCall, ctx: EvalCtx): unknown {
+  const args = evalArguments(expr, ctx);
+  if (isErr(args)) return args;
+  if (expr.method === 'value') {
+    if (args.length !== 2 || typeof args[0] !== 'number' || typeof args[1] !== 'string') {
+      throw new RuleEvalError(`duration.value() expects (magnitude: number, unit: string)`);
+    }
+    const [magnitude, unit] = args as [number, string];
+    if (!DURATION_UNITS.includes(unit)) {
+      throw new RuleEvalError(
+        `duration.value() got unknown unit "${unit}", expected one of ${DURATION_UNITS.join(', ')}`,
+      );
+    }
+    return Duration.fromValue(magnitude, unit);
+  }
+  if (expr.method === 'time') {
+    if (args.length !== 4 || !args.every((a) => typeof a === 'number')) {
+      throw new RuleEvalError(`duration.time() expects (hours, minutes, seconds, nanos) numbers`);
+    }
+    const [hours, minutes, seconds, nanos] = args as [number, number, number, number];
+    return Duration.fromTime(hours, minutes, seconds, nanos);
+  }
+  if (expr.method === 'abs') {
+    if (args.length !== 1 || !(args[0] instanceof Duration)) {
+      throw new RuleEvalError(`duration.abs() expects a single duration`);
+    }
+    return Duration.abs(args[0]);
+  }
+  throw new RuleEvalError(`unsupported duration.${expr.method}()`);
+}
+
+/**
+ * The Timestamp accessors and the Duration `seconds()`/`nanos()`, answered
+ * by the value itself. On a timestamp, `seconds()` and `nanos()` are the
+ * seconds of the minute and the nanoseconds of the second; `toMillis()` is
+ * the epoch value.
+ */
+export const timeMethods: ReceiverMethods = {
+  date: evalValueMethod,
+  day: evalValueMethod,
+  dayOfWeek: evalValueMethod,
+  dayOfYear: evalValueMethod,
+  hours: evalValueMethod,
+  minutes: evalValueMethod,
+  month: evalValueMethod,
+  nanos: evalValueMethod,
+  seconds: evalValueMethod,
+  time: evalValueMethod,
+  toMillis: evalValueMethod,
+  year: evalValueMethod,
+};

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

@@ -1,3 +1,6 @@
+import { FirestoreSet } from '../../rules/simulator/firestore-set.js';
+import { MapDiff } from '../../rules/simulator/mapdiff.js';
+import { RulesValue } from '../../rules/simulator/wrappers/base.js';
 import { RulesFloat } from '../../rules/simulator/wrappers/float.js';
 
 /** Error value that propagates through an expression and denies at the allow boundary. */
@@ -22,12 +25,21 @@ export function isRulesMap(value: unknown): value is Record<string, unknown> {
   return prototype === Object.prototype || prototype === null;
 }
 
+/**
+ * Rules value equality. Numbers compare int-to-float by value, lists and maps
+ * compare structurally over own keys, and Timestamp, Duration, Bytes, and Set
+ * values own their equality.
+ */
 export function rulesEquals(left: unknown, right: unknown): boolean {
   if (left === right) return true;
   if (left == null || right == null) return left == null && right == null;
   const leftNumber = numericValue(left);
   const rightNumber = numericValue(right);
   if (leftNumber !== undefined && rightNumber !== undefined) return leftNumber === rightNumber;
+  // A wrapper equals only a value of its own type. With a wrapper on the
+  // right alone, no branch below matches and the result is false.
+  if (left instanceof RulesValue) return left.equals(right);
+  if (left instanceof FirestoreSet) return left.equals(right);
   if (Array.isArray(left) && Array.isArray(right)) {
     return left.length === right.length && left.every((value, index) => rulesEquals(value, right[index]));
   }
@@ -43,9 +55,16 @@ export function rulesEquals(left: unknown, right: unknown): boolean {
   return false;
 }
 
+/** The Rules type name of a value, as production's error messages spell it. */
 export function describeRulesType(value: unknown): string {
   if (value === null) return 'null';
   if (value === undefined) return 'undefined';
-  if (value instanceof RulesFloat) return 'float';
+  if (value instanceof RulesValue) return value.typeName;
+  if (value instanceof FirestoreSet) return 'set';
+  if (value instanceof MapDiff) return 'map_diff';
+  if (typeof value === 'number') return Number.isInteger(value) ? 'int' : 'float';
+  if (typeof value === 'boolean') return 'bool';
+  if (Array.isArray(value)) return 'list';
+  if (isRulesMap(value)) return 'map';
   return typeof value;
 }

package/src/storage/sandbox/rules.ts

@@ -30,18 +30,26 @@
  *       member access (`a.b`), index access (`a['b']`), slice (`a[x:y]`)
  *       unary: `!`, `-`
  *       binary: `&& || == != < > <= >= + - * / %`
- *       ternary `?:`, `in` (list membership / map keys), `is` (type test)
+ *       ternary `?:`, `in` (list and set membership, map keys), `is` (type test)
  *       parens
  *       user-defined function calls (`isOwner(uid)`)
- *       `request.time` compared against the timestamp constructors
- *         `timestamp.date(y, m, d)` (UTC midnight) and
- *         `timestamp.value(epochMillis)`. The caller injects the time
- *         (3rd arg to `evaluateStorageRules`), defaulting to now.
- *       `duration.value(n, unit)` — a duration in millis, so the freshness
- *         idiom `request.time < resource.timeCreated + duration.value(1, 'h')`
+ *       `request.time` and the resource time fields as Timestamp values,
+ *         built also by `timestamp.date(y, m, d)` (UTC midnight) and
+ *         `timestamp.value(epochMillis)`, with the timestamp accessors. The
+ *         caller injects the time (3rd arg to `evaluateStorageRules`),
+ *         defaulting to now.
+ *       `duration.value(n, unit)`, `duration.time(h, m, s, ns)`, and
+ *         `duration.abs(d)` as Duration values, so the freshness idiom
+ *         `request.time < resource.timeCreated + duration.value(1, 'h')`
  *         evaluates.
- *       `string.matches(re)` — whole-string RE2-style regex match
- *         (see `evalMatches` for the RE2-vs-JS divergence handling)
+ *       string methods: `matches(re)` (whole-string RE2-style match),
+ *         `split(re)`, `lower()`, `upper()`, `trim()`, `replace(re, sub)`,
+ *         and `toUtf8()` (see rules-string-methods.ts for the RE2-vs-JS
+ *         handling)
+ *       `hashing.md5/sha256/crc32/crc32c` and Bytes values
+ *       List and Set methods (`toSet()`, `hasAll/hasAny/hasOnly`,
+ *         `difference/union/intersection`) and `Map.diff()` with the
+ *         MapDiff key sets
  *       custom-metadata access in both dotted (`resource.metadata.owner`)
  *         and bracket (`resource.metadata['owner']`) form — the metadata
  *         map is a plain string→string object, so both resolve identically
@@ -73,6 +81,7 @@
  */
 
 import { parseToASTOrError } from '../../rules/grammar/FirestoreParser.js';
+import { parseErrorWording } from '../../rules/grammar/parse-error-wording.js';
 // RULES-B5 float model, shared with the Firestore simulator: a FLOAT value is
 // tagged with this wrapper while a bare JS `number` means INT (see the
 // wrapper's header for why floats are the wrapped case). The storage evaluator
@@ -132,6 +141,10 @@ export function expandVerb(verb: StorageGrantVerb | StorageRequestMethod): Stora
 export interface StorageAuth {
   uid: string;
   token?: Record<string, unknown>;
+  /** Multi-tenant identity. The evaluator projects it into
+   *  `request.auth.token.firebase.tenant` through the sandbox context's
+   *  shared normalization, preserving any explicit nested value. */
+  tenant?: string;
 }
 
 /** Inbound request bindings the rules see. */
@@ -159,10 +172,10 @@ export interface StorageRequest {
  *     (`resourceFromStored`) therefore sources `name` from the persisted
  *     record's `fullPath`, NOT its `name`.
  *   - `timeCreated` / `updated` are ISO-8601 strings here (the persisted
- *     shape); the evaluator converts them to epoch millis when it builds the
- *     binding, so they compare numerically against `request.time` and against
- *     each other. Production types them as `timestamp` and rejects an int in
- *     their place ("Received: int < timestamp").
+ *     shape); the evaluator converts them to Timestamp values when it builds
+ *     the binding, so they compare against `request.time` and against each
+ *     other. Production types them as `timestamp` and rejects an int in their
+ *     place ("Received: int < timestamp").
  *   - The update-time field is `updated`. There is NO `resource.timeUpdated`
  *     in the Storage rules language.
  *
@@ -440,7 +453,7 @@ export function parseStorageRules(source: string): StorageRules {
   const parsed = parseToASTOrError(source);
   if (!parsed.ok) {
     throw new SyntaxError(
-      `Storage rules parse error at line ${parsed.error.line}, column ${parsed.error.column}: expected ${parsed.error.expected}.`,
+      `Storage rules parse error at line ${parsed.error.line}, column ${parsed.error.column}: ${parseErrorWording(parsed.error, source)}.`,
     );
   }
   const ast: SharedRules = parsed.ast;

package/src/storage/sandbox/running-service.ts

@@ -0,0 +1,52 @@
+/**
+ * The storage service a sandbox is running: its store, the ruleset it
+ * enforces, and the cross-service IAM posture it evaluates Firestore lookups
+ * under.
+ *
+ * This is the mutable half of the surface. The factory in `storage/service.ts`
+ * decides when one of these is created and which sandbox it belongs to; what
+ * one holds while it is running is here, because that is what enforcement,
+ * rule replacement, and posture replacement all reach for and none of them
+ * needs the factory's caching to say it.
+ */
+import type { StorageBackend } from '../persistence.js';
+import type { StorageRules } from './rules.js';
+
+/**
+ * Cross-service IAM posture for `firestore.get()/exists()` in Storage rules.
+ *
+ * Production Storage rules can read Firestore ONLY when the project's
+ * Storage service agent holds `roles/firebaserules.firestoreServiceAgent`.
+ * `'granted'` (the default, the common configured-project state) serves
+ * lookups from the same-sandbox Firestore store; `'denied'` makes every
+ * EXECUTED lookup fail exactly like production without the role (error to
+ * rule denies), while short-circuited lookups are never executed and stay
+ * unaffected. Captured boundary: conformance observation
+ * `stdlib-realstorage-p3-lookup-budget` (registry row storage-rules#134).
+ */
+export type CrossServiceIam = 'granted' | 'denied';
+
+/**
+ * Internal sandbox service: owns the IDB connection and the parsed rules.
+ * Only constructed inside the sandbox `getStorageSandbox` path.
+ */
+export class StorageService {
+  constructor(
+    readonly backend: StorageBackend,
+    /**
+     * The ruleset every operation on this service evaluates against.
+     * Assigned at construction and reassigned only by `replaceStorageRules`,
+     * which is the one deliberate way to install a new ruleset into a sandbox
+     * whose storage is already open.
+     */
+    public rules: StorageRules | null = null,
+    /**
+     * The cross-service IAM posture every operation on this service evaluates
+     * `firestore.get()/exists()` under. Assigned at construction and
+     * reassigned only by `replaceCrossServiceIam`, which is the one deliberate
+     * way to move a sandbox whose storage is already open between the granted
+     * and denied project states.
+     */
+    public crossServiceIam: CrossServiceIam = 'granted',
+  ) {}
+}