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

package/src/rules/rtdb/simulation/handler.ts

@@ -1,7 +1,8 @@
 import { DataSnapshot, evaluateRtdbExpression } from '../grammar/simulator.js';
-import type { EvalContext } from '../grammar/simulator.js';
+import type { EvalContext, SimulatedAuth } from '../grammar/simulator.js';
 import type { RtdbNode, RtdbRuleExpression } from '../types.js';
-import { SimulationInputSchema } from './spec.js';
+import { SimulationInputSchema, type SimulationInput } from './spec.js';
+import { normalizeAuthState } from '../../../sandbox/sandbox-context.js';
 import type { SimulateResult } from './spec.js';
 
 interface AncestorMatch {
@@ -40,6 +41,23 @@ function snapshotChildKeys(snap: DataSnapshot): string[] {
   return Object.keys(value as object);
 }
 
+/**
+ * The rules `auth` variable for a signed-in request: the uid, the ID token
+ * claims with the tenant folded in by the shared normalizer, and `provider`,
+ * which production reads as the token's `firebase.sign_in_provider`. There is
+ * no top-level `auth.tenant`; production reads it as null.
+ */
+function simulatedAuthOf(auth: NonNullable<SimulationInput['auth']>): SimulatedAuth {
+  const normalized = normalizeAuthState(auth);
+  const token = normalized?.token ?? {};
+  const simulated: SimulatedAuth = { uid: auth.uid, token };
+  const firebase = token.firebase;
+  const claims = typeof firebase === 'object' && firebase !== null ? (firebase as Record<string, unknown>) : {};
+  const signInProvider = claims.sign_in_provider;
+  if (typeof signInProvider === 'string') simulated.provider = signInProvider;
+  return simulated;
+}
+
 /**
  * `.validate` enforcement for a write. RTDB evaluates every rule on the path
  * from the root to the write location, then every descendant rule present in
@@ -122,6 +140,7 @@ function findFailingValidate(
     );
 
     const hasLocalDeletion = snapshotChildKeys(data).some((k) => !newData.child(k).exists());
+    const literalKeys = literalChildKeys(node);
 
     for (const child of node.children) {
       const childSegments = child.path.split('/').filter(Boolean);
@@ -133,6 +152,7 @@ function findFailingValidate(
       if (isAtOrBelowWriteTarget || isUnderModifiedSubtree) {
         if (isPathVar) {
           for (const key of snapshotChildKeys(newData)) {
+            if (literalKeys.has(key)) continue;
             const failure = walk(
               child,
               data.child(key),
@@ -169,6 +189,7 @@ function findFailingValidate(
             }
           }
           for (const key of writeKeys) {
+            if (literalKeys.has(key)) continue;
             const failure = walk(
               child,
               data.child(key),
@@ -185,7 +206,7 @@ function findFailingValidate(
             shouldValidateSiblingSubtree(currentSegments, hasLocalDeletion, allWritePaths)
           ) {
             for (const key of snapshotChildKeys(newData)) {
-              if (writeKeys.has(key)) continue;
+              if (writeKeys.has(key) || literalKeys.has(key)) continue;
               const failure = walk(
                 child,
                 data.child(key),
@@ -260,24 +281,65 @@ function collectAncestors(
 
   if (pathSegments.length === 0) return ancestors;
 
+  const matched = childFor(node, pathSegments[0]);
+  if (matched === undefined) return ancestors;
+  const newBindings = matched.variable === undefined
+    ? { ...bindings }
+    : { ...bindings, [matched.variable]: pathSegments[0] };
+  ancestors.push(...collectAncestors(matched.child, pathSegments.slice(1), newBindings, depth + 1));
+  return ancestors;
+}
+
+/** The last segment of a rule node's path: its key, or `$name` for a wildcard. */
+function keyOf(node: RtdbNode): string | undefined {
+  const segments = node.path.split('/').filter(Boolean);
+  return segments[segments.length - 1];
+}
+
+/** The keys a node's literal children name. A `$wildcard` sibling never matches them. */
+function literalChildKeys(node: RtdbNode): Set<string> {
+  const keys = new Set<string>();
   for (const child of node.children) {
-    const childSegments = child.path.split('/').filter(Boolean);
-    if (childSegments.length === 0) continue;
-
-    const lastSegment = childSegments[childSegments.length - 1];
-    const isPathVar = lastSegment.startsWith('$');
-
-    if (isPathVar || pathSegments[0] === lastSegment) {
-      const newBindings = isPathVar
-        ? { ...bindings, [lastSegment]: pathSegments[0] }
-        : { ...bindings };
-      const deeper = collectAncestors(child, pathSegments.slice(1), newBindings, depth + 1);
-      ancestors.push(...deeper);
-      return ancestors;
-    }
+    const key = keyOf(child);
+    const isLiteral = key !== undefined && !key.startsWith('$');
+    if (isLiteral) keys.add(key);
   }
+  return keys;
+}
 
-  return ancestors;
+/**
+ * The child rule node that applies to `key`: the literal child that names it,
+ * else the `$wildcard` child, bound to it. Production applies a wildcard only
+ * to keys no literal sibling names, whichever is declared first.
+ */
+function childFor(node: RtdbNode, key: string): { child: RtdbNode; variable?: string } | undefined {
+  let wildcard: { child: RtdbNode; variable: string } | undefined;
+  for (const child of node.children) {
+    const childKey = keyOf(child);
+    if (childKey === undefined) continue;
+    if (childKey === key) return { child };
+    const isWildcard = childKey.startsWith('$');
+    if (isWildcard && wildcard === undefined) wildcard = { child, variable: childKey };
+  }
+  return wildcard;
+}
+
+/** The denial result for a failing `.validate` rule. */
+function toValidateFailureResult(failure: ValidateFailure): SimulateResult {
+  const reason = failure.unsupported
+    ? `Validation rule at '${failure.node.path}' contains an expression the simulator cannot evaluate: ${failure.rule.raw} — not evaluated; production may reject this write.`
+    : 'Validation rule evaluated to false';
+  return {
+    success: true,
+    data: {
+      allowed: false,
+      unsupported: failure.unsupported === true,
+      matchedPath: failure.node.path,
+      matchedRule: failure.rule.raw,
+      reason,
+      pathVariableBindings: failure.bindings,
+    },
+  };
 }
 
 /**
@@ -344,6 +406,25 @@ function projectPostWriteTree(
   return root;
 }
 
+function buildSimulatedQueryContext(
+  operation: string,
+  query: SimulationInput['query'],
+): EvalContext['query'] {
+  if (operation !== 'read' || !query) {
+    return null;
+  }
+  return {
+    orderByChild: query.orderByChild ?? null,
+    orderByKey: query.orderByKey ?? null,
+    orderByValue: query.orderByValue ?? null,
+    equalTo: query.equalTo ?? null,
+    limitToFirst: query.limitToFirst ?? null,
+    limitToLast: query.limitToLast ?? null,
+    startAt: query.startAt ?? null,
+    endAt: query.endAt ?? null,
+  };
+}
+
 export class SimulateHandler {
   execute(compiled: RtdbNode, rawInput: unknown): SimulateResult {
     const parsed = SimulationInputSchema.safeParse(rawInput);
@@ -358,7 +439,11 @@ export class SimulateHandler {
       };
     }
 
-    const { operation, path, auth, mockData, newData, updates } = parsed.data;
+    const { operation, path, auth, mockData, newData, updates, query } = parsed.data;
+    // `now` in an RTDB rule is the instant the request is evaluated. A caller
+    // hosting a sandbox names it so a `now`-gated rule moves with the sandbox
+    // clock; a standalone caller leaves it out and gets the wall clock.
+    const evaluationNow = parsed.data.now ?? Date.now();
 
     try {
       const pathSegments = path.split('/').filter(Boolean);
@@ -388,6 +473,11 @@ export class SimulateHandler {
           : projectPostWriteTree(mockData, pathSegments, newData, updates);
       const mergedRootData = new DataSnapshot(mergedRoot, '/');
 
+      let contextAuth: SimulatedAuth | null = null;
+      if (auth) contextAuth = simulatedAuthOf(auth);
+
+      const contextQuery = buildSimulatedQueryContext(operation, query);
+
       const buildContext: ContextBuilder = (data, newDataArg, bindings) => {
         const pvBindings: Record<string, string> = {};
         for (const [k, v] of Object.entries(bindings)) {
@@ -395,15 +485,42 @@ export class SimulateHandler {
           pvBindings[k.slice(1)] = v;
         }
         return {
-          auth: auth ? { uid: auth.uid, token: auth.token } : null,
+          auth: contextAuth,
           data,
           newData: newDataArg,
           root: rootData,
-          now: Date.now(),
+          now: evaluationNow,
           pathVariableBindings: pvBindings,
+          query: contextQuery,
         };
       };
 
+      // The validate operation runs only the `.validate` phase: every
+      // `.validate` rule from the root through the write location and its
+      // written descendants must pass, whatever `.write` grants.
+      if (operation === 'validate') {
+        const deepestValidate = [...ancestors].reverse().find((a) => a.node.validate !== undefined)
+          ?? ancestors.find((a) => hasValidateRule(a.node));
+        if (deepestValidate === undefined) {
+          return {
+            success: false,
+            error: { code: 'NO_MATCHING_RULE', message: `No 'validate' rule found for path '${path}'`, recoverable: true },
+          };
+        }
+        const failure = findFailingValidate(rootNode, rootData, mergedRootData, {}, buildContext, pathSegments, updates);
+        if (failure) return toValidateFailureResult(failure);
+        return {
+          success: true,
+          data: {
+            allowed: true,
+            matchedPath: deepestValidate.node.path,
+            matchedRule: deepestValidate.node.validate?.raw ?? 'true',
+            reason: 'Validation rules evaluated to true',
+            pathVariableBindings: deepestValidate.pathVariableBindings,
+          },
+        };
+      }
+
       // Tracks the first ancestor whose `.write`/`.read` rule the grammar
       // couldn't parse. Unlike `.validate`, `.write`/`.read` rules cascade
       // (any ancestor granting `true` wins), so an unparseable rule is not
@@ -447,21 +564,7 @@ export class SimulateHandler {
               pathSegments,
               updates,
             );
-            if (failure) {
-              return {
-                success: true,
-                data: {
-                  allowed: false,
-                  unsupported: failure.unsupported === true,
-                  matchedPath: failure.node.path,
-                  matchedRule: failure.rule.raw,
-                  reason: failure.unsupported
-                    ? `Validation rule at '${failure.node.path}' contains an expression the simulator cannot evaluate: ${failure.rule.raw} — not evaluated; production may reject this write.`
-                    : 'Validation rule evaluated to false',
-                  pathVariableBindings: failure.bindings,
-                },
-              };
-            }
+            if (failure) return toValidateFailureResult(failure);
           }
           return {
             success: true,

package/src/rules/rtdb/simulation/spec.ts

@@ -1,10 +1,26 @@
 import { z } from 'zod';
 
+export const SimulationQuerySchema = z.object({
+  orderByChild: z.string().nullable().optional(),
+  orderByKey: z.boolean().nullable().optional(),
+  orderByValue: z.boolean().nullable().optional(),
+  equalTo: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
+  limitToFirst: z.number().nullable().optional(),
+  limitToLast: z.number().nullable().optional(),
+  startAt: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
+  endAt: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
+});
+export type SimulationQuery = z.infer<typeof SimulationQuerySchema>;
+
 export const SimulationInputSchema = z.object({
   operation: z.enum(['read', 'write', 'validate']),
   path: z.string().min(1).startsWith('/'),
   auth: z.union([
-    z.object({ uid: z.string(), token: z.record(z.unknown()) }),
+    z.object({
+      uid: z.string(),
+      tenant: z.string().optional(),
+      token: z.record(z.unknown()).optional(),
+    }),
     z.null(),
   ]),
   mockData: z.record(z.unknown()),
@@ -21,6 +37,13 @@ export const SimulationInputSchema = z.object({
   updates: z
     .array(z.object({ path: z.string().min(1).startsWith('/'), value: z.unknown() }))
     .optional(),
+  query: SimulationQuerySchema.optional(),
+  /**
+   * The instant the rules engine reports as `now`, in epoch milliseconds.
+   * Callers hosting a sandbox pass their sandbox clock so a `now`-gated rule
+   * moves with it. Omitted, the engine reads the wall clock.
+   */
+  now: z.number().optional(),
 });
 export type SimulationInput = z.infer<typeof SimulationInputSchema>;
 

package/src/rules/simulator/evaluator.ts

@@ -345,6 +345,38 @@ export function isKnownGlobal(name: string): boolean {
 
 // ═══ Binary operations with short-circuit ═══
 
+function evaluateShortCircuitOp(
+  determiningValue: boolean,
+  left: Expression,
+  right: Expression,
+  ctx: SimulationContext,
+  scope: Record<string, unknown>,
+): unknown {
+  let lv: unknown, lErr: unknown;
+  try {
+    lv = requireBoolean(evaluate(left, ctx, scope), left);
+  } catch (e) {
+    lErr = e;
+  }
+  if (lErr instanceof ResourceLimitError) throw lErr;
+  if (lErr === undefined && lv === determiningValue) {
+    ctx.trace?.skip(right);
+    return determiningValue;
+  }
+
+  let rv: unknown, rErr: unknown;
+  try {
+    rv = requireBoolean(evaluate(right, ctx, scope), right);
+  } catch (e) {
+    rErr = e;
+  }
+  if (rErr instanceof ResourceLimitError) throw rErr;
+  if (rErr === undefined && rv === determiningValue) return determiningValue;
+  if (lErr !== undefined) throw lErr;
+  if (rErr !== undefined) throw rErr;
+  return rv;
+}
+
 function evaluateBinaryOp(
   op: string, left: Expression, right: Expression,
   ctx: SimulationContext, scope: Record<string, unknown>,
@@ -362,47 +394,8 @@ function evaluateBinaryOp(
   // either errored or did not determine the result. If neither operand
   // determines the result and one errored, the error propagates (re-thrown)
   // so the handler DENYs.
-  if (op === '&&') {
-    let lv: unknown, lErr: unknown;
-    try { lv = requireBoolean(evaluate(left, ctx, scope), left); } catch (e) { lErr = e; }
-    // A resource-limit failure (the document access budget) fails the WHOLE
-    // request, it is not a CEL error value: a determining RHS must not
-    // absorb it into an ALLOW. Fail closed immediately.
-    // TODO(unverified): confirm against a live production capture that the
-    // 11th-access error is not absorbable. The Rules Test API does not
-    // enforce the budget, so the capture has to be a deployed ruleset.
-    if (lErr instanceof ResourceLimitError) throw lErr;
-    if (lErr === undefined && lv === false) {
-      // LHS is false → determines the result; RHS need not be evaluated.
-      ctx.trace?.skip(right);
-      return false;
-    }
-    // LHS errored or was true — RHS may absorb the error (if RHS is false)
-    // or determine the truthy result.
-    let rv: unknown, rErr: unknown;
-    try { rv = requireBoolean(evaluate(right, ctx, scope), right); } catch (e) { rErr = e; }
-    if (rErr === undefined && rv === false) return false; // RHS false absorbs any LHS error
-    if (lErr !== undefined) throw lErr;           // LHS error not absorbed
-    if (rErr !== undefined) throw rErr;           // RHS error, LHS was true
-    return rv;
-  }
-  if (op === '||') {
-    let lv: unknown, lErr: unknown;
-    try { lv = requireBoolean(evaluate(left, ctx, scope), left); } catch (e) { lErr = e; }
-    // See the `&&` branch: a resource-limit failure is not absorbable.
-    if (lErr instanceof ResourceLimitError) throw lErr;
-    if (lErr === undefined && lv === true) {
-      // LHS is true → determines the result; RHS need not be evaluated.
-      ctx.trace?.skip(right);
-      return true;
-    }
-    let rv: unknown, rErr: unknown;
-    try { rv = requireBoolean(evaluate(right, ctx, scope), right); } catch (e) { rErr = e; }
-    if (rErr === undefined && rv === true) return true; // RHS true absorbs any LHS error
-    if (lErr !== undefined) throw lErr;          // LHS error not absorbed
-    if (rErr !== undefined) throw rErr;          // RHS error, LHS was false
-    return rv;
-  }
+  if (op === '&&') return evaluateShortCircuitOp(false, left, right, ctx, scope);
+  if (op === '||') return evaluateShortCircuitOp(true, left, right, ctx, scope);
 
   const lv = evaluate(left, ctx, scope);
   const rv = evaluate(right, ctx, scope);

package/src/rules/simulator/handler.ts

@@ -27,6 +27,7 @@ import { Path } from './wrappers/path.js';
 import { LookupBudget } from './lookup-budget.js';
 import { ResourceLimitError } from './eval-error.js';
 import { projectAfterState } from './project-after-state.js';
+import { DOCUMENT_PATH_FORM, documentRelativePath } from './request-path.js';
 import {
   requestQuery,
   resolveServerTimestamps,
@@ -493,7 +494,12 @@ export class SimulateFirestoreRulesHandler {
       // Resolve the match block for this path.
       // The root match is /databases/{database}/documents — skip it,
       // start matching from its children directly.
-      const pathSegments = tc.path.split('/').filter(Boolean);
+      // Both the document-relative form and the full resource name the
+      // console shows mean the same request, so the full form is reduced
+      // before a block is resolved against it and every message about this
+      // case names the reduced form.
+      const requestPath = documentRelativePath(tc.path);
+      const pathSegments = requestPath.split('/').filter(Boolean);
       // Functions declared at GLOBAL scope (above `service`) and SERVICE
       // scope (inside `service`, outside the documents match) seed the walk
       // alongside the documents-match's own (#346). Declaration order
@@ -539,7 +545,7 @@ export class SimulateFirestoreRulesHandler {
         }
       }
       const pathResolution: PathResolutionTrace = {
-        requestPath: tc.path,
+        requestPath,
         attempts: pathRecorder.attempts,
       };
 
@@ -555,7 +561,10 @@ export class SimulateFirestoreRulesHandler {
           state,
           decision: 'DENY',
           trace: [],
-          notes: [`No match block found for path '${tc.path}'`],
+          notes: [
+            `No match block found for path '${requestPath}', so the request is denied by default.`,
+            DOCUMENT_PATH_FORM,
+          ],
           pathResolution,
         });
         continue;

package/src/rules/simulator/mapdiff.ts

@@ -7,6 +7,8 @@
  * Semantics derived from production Firestore behavior:
  * - Only compares top-level keys (nested map diff is unreliable in production)
  * - Values are compared with Firestore Rules value equality
+ * - Keys are own keys only, so a key named `constructor` or `toString` is
+ *   added or removed like any other (production maps expose no prototype)
  * - Returns Set-like objects with hasOnly(), hasAll(), hasAny(), size()
  */
 
@@ -28,7 +30,7 @@ export class MapDiff {
   addedKeys(): FirestoreSet {
     const added: string[] = [];
     for (const key of Object.keys(this.after)) {
-      if (!(key in this.before)) added.push(key);
+      if (!Object.hasOwn(this.before, key)) added.push(key);
     }
     return new FirestoreSet(added);
   }
@@ -37,7 +39,7 @@ export class MapDiff {
   removedKeys(): FirestoreSet {
     const removed: string[] = [];
     for (const key of Object.keys(this.before)) {
-      if (!(key in this.after)) removed.push(key);
+      if (!Object.hasOwn(this.after, key)) removed.push(key);
     }
     return new FirestoreSet(removed);
   }
@@ -46,7 +48,7 @@ export class MapDiff {
   changedKeys(): FirestoreSet {
     const changed: string[] = [];
     for (const key of Object.keys(this.after)) {
-      if (key in this.before && !rulesValuesEqual(this.before[key], this.after[key])) {
+      if (Object.hasOwn(this.before, key) && !rulesValuesEqual(this.before[key], this.after[key])) {
         changed.push(key);
       }
     }
@@ -58,7 +60,7 @@ export class MapDiff {
     const affected: string[] = [];
     const allKeys = new Set([...Object.keys(this.before), ...Object.keys(this.after)]);
     for (const key of allKeys) {
-      if (!(key in this.before) || !(key in this.after) || !rulesValuesEqual(this.before[key], this.after[key])) {
+      if (!Object.hasOwn(this.before, key) || !Object.hasOwn(this.after, key) || !rulesValuesEqual(this.before[key], this.after[key])) {
         affected.push(key);
       }
     }
@@ -69,7 +71,7 @@ export class MapDiff {
   unchangedKeys(): FirestoreSet {
     const unchanged: string[] = [];
     for (const key of Object.keys(this.before)) {
-      if (key in this.after && rulesValuesEqual(this.before[key], this.after[key])) {
+      if (Object.hasOwn(this.after, key) && rulesValuesEqual(this.before[key], this.after[key])) {
         unchanged.push(key);
       }
     }