pyric-admin 0.1.0-alpha.30.2 → 0.1.0-alpha.32

package/src/auth/oracle-admin-answers.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Replays the Admin SDK answers in the production capture
+ * `auth-request-auth-per-sign-in` (`behavior.admin`) through pyric-admin's
+ * in-process arm (`initializeApp({ sandbox })`).
+ *
+ * Each call's outcome is compared as `resolved`, or the error code with
+ * whether it threw synchronously. Every difference must be pinned with both
+ * answers and the finding; fixing a finding turns its pin red, and the fix
+ * deletes the pin.
+ */
+import { afterEach, describe, expect, it } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { initializeSandbox } from 'pyric/sandbox';
+import { createUserWithEmailAndPassword, getAuth as getClientAuth, sandbox as clientSandbox } from 'pyric/auth';
+import { deleteApp, getApps, initializeApp } from '../app/index.js';
+import { getAuth } from './index.js';
+
+afterEach(async () => {
+  await Promise.all(getApps().map((app) => deleteApp(app)));
+});
+
+type Recorded = { resolved?: true; code?: string | null; threw?: string; rejected?: true };
+const OBSERVATION = JSON.parse(readFileSync(new URL('../../../conformance/observations/auth/auth-request-auth-per-sign-in.json', import.meta.url), 'utf8')) as {
+  behavior: { admin: Record<string, Recorded> };
+};
+
+function summary(r: Recorded): string {
+  if (r.resolved) return 'resolved';
+  return `${r.threw === 'synchronously' ? 'throws' : 'rejects'} ${r.code ?? '(no code)'}`;
+}
+async function outcome(run: () => unknown): Promise<string> {
+  let promise: unknown;
+  try {
+    promise = run();
+  } catch (e) {
+    return `throws ${(e as { code?: string }).code ?? '(no code)'}`;
+  }
+  try {
+    await promise;
+    return 'resolved';
+  } catch (e) {
+    return `rejects ${(e as { code?: string }).code ?? '(no code)'}`;
+  }
+}
+
+/** Known differences, keyed by the observation's call name. */
+const PINS: Record<string, { pyric: string; production: string; finding: string }> = {
+  createUserTakenEmail: { pyric: 'resolved', production: 'rejects auth/email-already-exists', finding: 'auth-claims AU-6: admin user-management errors are missing or use client codes' },
+  createUserTakenUid: { pyric: 'rejects (no code)', production: 'rejects auth/uid-already-exists', finding: 'auth-claims AU-6' },
+  createUserShortPassword: { pyric: 'resolved', production: 'rejects auth/invalid-password', finding: 'auth-claims AU-6' },
+  createUserInvalidEmail: { pyric: 'resolved', production: 'rejects auth/invalid-email', finding: 'auth-claims AU-6' },
+  getUserMissing: { pyric: 'rejects (no code)', production: 'rejects auth/user-not-found', finding: 'auth-claims AU-6' },
+  getUserByEmailMissing: { pyric: 'rejects (no code)', production: 'rejects auth/user-not-found', finding: 'auth-claims AU-6' },
+  getUserByEmailOtherCase: { pyric: 'rejects (no code)', production: 'resolved', finding: 'auth-claims CO-4: getUserByEmail matches the stored email case-sensitively' },
+  deleteUserMissing: { pyric: 'rejects (no code)', production: 'rejects auth/user-not-found', finding: 'auth-claims AU-6' },
+  setCustomUserClaimsMissing: { pyric: 'rejects (no code)', production: 'rejects auth/user-not-found', finding: 'auth-claims AU-6' },
+  setCustomUserClaims1100: { pyric: 'resolved', production: 'rejects auth/claims-too-large', finding: 'auth-claims AU-5: no 1000-character custom-claims limit' },
+  createCustomTokenEmptyUid: { pyric: 'resolved', production: 'throws auth/argument-error', finding: 'auth-claims AU-4: createCustomToken validates neither uid nor claims' },
+  createCustomToken129Uid: { pyric: 'resolved', production: 'throws auth/argument-error', finding: 'auth-claims AU-4' },
+  createCustomTokenReservedAud: { pyric: 'resolved', production: 'throws auth/argument-error', finding: 'auth-claims AU-4' },
+  createCustomTokenNullClaims: { pyric: 'resolved', production: 'throws auth/argument-error', finding: 'auth-claims AU-4' },
+  verifyIdTokenOfCustomToken: { pyric: 'resolved', production: 'rejects auth/argument-error', finding: 'auth-claims AU-9: verifyIdToken accepts a custom token' },
+  verifyIdTokenCheckRevokedDisabled: { pyric: 'resolved', production: 'rejects auth/user-disabled', finding: 'auth-claims AU-10: checkRevoked ignores disabled and deleted users' },
+  verifyIdTokenCheckRevokedDeleted: { pyric: 'resolved', production: 'rejects auth/user-not-found', finding: 'auth-claims AU-10' },
+};
+
+describe('pyric-admin auth answers as the production Admin SDK does', () => {
+  it('user management, custom tokens, custom claims and verifyIdToken', async () => {
+    const sandbox = initializeSandbox();
+    const admin = getAuth(initializeApp({ sandbox }, 'oracle-admin-answers'));
+    const email = 'ad@example.com';
+    const uid = 'oracle-ad';
+    await admin.createUser({ uid, email, password: 'secret-pw' });
+
+    // A client session on the same sandbox, for verifyIdToken.
+    const client = getClientAuth(sandbox);
+    const { user } = await createUserWithEmailAndPassword(client, 'verify@example.com', 'secret-pw');
+    const idToken = await user.getIdToken();
+
+    const observed: Record<string, string> = {
+      createUserTakenEmail: await outcome(() => admin.createUser({ email, password: 'secret-pw' })),
+      createUserTakenUid: await outcome(() => admin.createUser({ uid, password: 'secret-pw' })),
+      createUserShortPassword: await outcome(() => admin.createUser({ uid: 'oracle-short', password: '12345' })),
+      createUserInvalidEmail: await outcome(() => admin.createUser({ uid: 'oracle-bad', email: 'nope' })),
+      getUserMissing: await outcome(() => admin.getUser('oracle-missing')),
+      getUserByEmailMissing: await outcome(() => admin.getUserByEmail('oracle-missing@example.com')),
+      getUserByEmailOtherCase: await outcome(() => admin.getUserByEmail(email.toUpperCase())),
+      deleteUserMissing: await outcome(() => admin.deleteUser('oracle-missing')),
+      setCustomUserClaimsMissing: await outcome(() => admin.setCustomUserClaims('oracle-missing', { a: 1 })),
+      setCustomUserClaims1100: await outcome(() => admin.setCustomUserClaims(uid, { blob: 'x'.repeat(1100) })),
+      setCustomUserClaimsReserved: await outcome(() => admin.setCustomUserClaims(uid, { sub: 'x' })),
+      createCustomTokenEmptyUid: await outcome(() => admin.createCustomToken('')),
+      createCustomToken129Uid: await outcome(() => admin.createCustomToken('x'.repeat(129))),
+      createCustomToken128Uid: await outcome(() => admin.createCustomToken('x'.repeat(128))),
+      createCustomTokenReservedAud: await outcome(() => admin.createCustomToken('u', { aud: 'x' })),
+      createCustomTokenReservedFirebase: await outcome(() => admin.createCustomToken('u', { firebase: {} })),
+      createCustomTokenNullClaims: await outcome(() => admin.createCustomToken('u', null as never)),
+      verifyIdTokenOfCustomToken: await outcome(async () => admin.verifyIdToken(await admin.createCustomToken('u'))),
+    };
+    clientSandbox.updateUser(client, user.uid, { disabled: true });
+    observed.verifyIdTokenNoCheckDisabled = await outcome(() => admin.verifyIdToken(idToken));
+    observed.verifyIdTokenCheckRevokedDisabled = await outcome(() => admin.verifyIdToken(idToken, true));
+    clientSandbox.deleteUser(client, user.uid);
+    observed.verifyIdTokenCheckRevokedDeleted = await outcome(() => admin.verifyIdToken(idToken, true));
+
+    const found: Record<string, { pyric: string; production: string }> = {};
+    for (const [call, pyric] of Object.entries(observed)) {
+      const production = summary(OBSERVATION.behavior.admin[call]);
+      if (pyric !== production) found[call] = { pyric, production };
+    }
+    const pinned = Object.fromEntries(Object.entries(PINS).map(([call, pin]) => [call, { pyric: pin.pyric, production: pin.production }]));
+    expect(found).toEqual(pinned);
+  });
+});

package/src/auth/verify-id-token-claims.test.ts

@@ -0,0 +1,42 @@
+/**
+ * `verifyIdToken` on a client ID token returns the token's own `sub`, `aud`,
+ * `iss`, `iat`, `exp` and `auth_time`, not values made up at verify time
+ * (auth-claims AU-7). A server's recent-sign-in check reads `auth_time`
+ * (firebase.google.com/docs/auth/admin/manage-cookies: "the auth_time should
+ * be checked"), and production keeps it at the sign-in across refreshes
+ * (firebase-admin `token-verifier.d.ts`: "the same auth_time value"; capture
+ * `admin.verifyIdTokenDecoded.authTimeEqualsToken: true`).
+ */
+import { afterEach, describe, expect, it } from 'bun:test';
+import { initializeSandbox } from 'pyric/sandbox';
+import { getClock } from 'pyric/sandbox/internal';
+import { createUserWithEmailAndPassword, getAuth as getClientAuth } from 'pyric/auth';
+import { deleteApp, getApps, initializeApp } from '../app/index.js';
+import { getAuth } from './index.js';
+
+afterEach(async () => {
+  await Promise.all(getApps().map((app) => deleteApp(app)));
+});
+
+describe('verifyIdToken returns the client token claims', () => {
+  it('keeps auth_time at the sign-in and iat at the refresh', async () => {
+    const sandbox = initializeSandbox();
+    const admin = getAuth(initializeApp({ sandbox }, 'verify-id-token-claims'));
+    const client = getClientAuth(sandbox);
+    // Move the sandbox clock away from the wall clock, so a value made up at
+    // verify time cannot match by accident.
+    getClock(sandbox).advance(60 * 60 * 1000);
+    const { user } = await createUserWithEmailAndPassword(client, 'ada@example.com', 'secret-pw');
+    getClock(sandbox).advance(10 * 60 * 1000);
+    const idToken = await user.getIdToken(true);
+    const { claims } = await user.getIdTokenResult();
+
+    const decoded = await admin.verifyIdToken(idToken);
+
+    for (const key of ['sub', 'aud', 'iss', 'iat', 'exp', 'auth_time'] as const) {
+      expect(decoded[key]).toEqual(claims[key]);
+    }
+    expect(decoded.uid).toBe(user.uid);
+    expect(decoded.iat - decoded.auth_time).toBe(600);
+  });
+});

package/src/database/index.ts

@@ -6,7 +6,12 @@
  * an in-memory RTDB implementing this load-bearing data-plane subset:
  *
  *       - `Database.ref(path?)` returns a {@link Reference}.
- *       - `Reference#set(value)` writes into the in-memory tree.
+ *       - `Reference#set(value)` writes into the in-memory tree, normalized
+ *         as the host normalizes it: arrays become integer-keyed children,
+ *         null children and empty objects are dropped, and `val()` renders
+ *         integer keys back as an array (`ChildrenNode.val`, #1121).
+ *         Inline `.priority` keys are dropped, since priorities are not
+ *         modeled here.
  *       - `Reference#get()` reads; returns a `DataSnapshot`-shaped
  *         `{ exists(), val(), key, child(), forEach(), … }`.
  *       - `Reference#update(values)` merges children (a `null` value
@@ -98,7 +103,17 @@ import {
 } from '../app/index.js';
 import { assertAdminAppActive } from '../app/lifecycle.js';
 import { increment, serverTimestamp } from 'pyric/database';
-import { assertGettablePath, valueAtChildPath, valueChildren } from 'pyric/database/internal';
+import {
+  assertGettablePath,
+  coerceArrays,
+  errorPrefix,
+  inlinePriorities,
+  normalizeNode,
+  validateUpdate,
+  validateWrite,
+  valueAtChildPath,
+  valueChildren,
+} from 'pyric/database/internal';
 import { deferredExport } from 'pyric/app/internal';
 
 /** `firebase-admin/database`'s `enableLogging`. The sandbox does not model
@@ -422,19 +437,9 @@ function joinPath(segments: string[]): string {
   return '/' + segments.join('/');
 }
 
-/** Deep-clone a JSON value so stored state doesn't share identity with
- *  caller-held references. */
-function cloneJson<T extends JsonValue>(v: T): T {
-  if (v === null || typeof v !== 'object') return v;
-  if (Array.isArray(v)) return v.map((x) => cloneJson(x as JsonValue)) as T;
-  const out: Record<string, JsonValue> = {};
-  for (const [k, val] of Object.entries(v as Record<string, JsonValue>)) {
-    out[k] = cloneJson(val);
-  }
-  return out as T;
-}
-
-/** Read the value at `path` in `root`. `null` for absent paths. */
+/** Read the stored value at `path` in `root`: integer-keyed children stay
+ *  object keys. `null` for absent paths. The result is a fresh copy, sharing
+ *  nothing with the stored tree. */
 function readPath(root: Record<string, JsonValue>, path: string): JsonValue {
   const segs = pathSegments(path);
   let node: JsonValue = root;
@@ -448,10 +453,11 @@ function readPath(root: Record<string, JsonValue>, path: string): JsonValue {
     if (!Object.hasOwn(obj, seg)) return null;
     node = obj[seg]!;
   }
-  return cloneJson(node);
+  return structuredClone(node);
 }
 
-/** Write `value` at `path`. `null` deletes. Trims empty ancestor objects. */
+/** Write a value {@link normalizeNode} built at `path`. `null` deletes.
+ *  Trims empty ancestor objects. */
 function writePath(
   root: Record<string, JsonValue>,
   path: string,
@@ -467,7 +473,7 @@ function writePath(
         'pyric-admin/database sandbox: root write must be an object (or null to clear).',
       );
     }
-    Object.assign(root, cloneJson(value) as Record<string, JsonValue>);
+    Object.assign(root, value);
     return;
   }
   // Walk to parent, creating intermediate objects as needed.
@@ -495,7 +501,7 @@ function writePath(
     delete cursor[lastKey];
     trimEmptyAncestors(root, segs);
   } else {
-    cursor[lastKey] = cloneJson(value);
+    cursor[lastKey] = value;
   }
 }
 
@@ -538,6 +544,52 @@ function trimEmptyAncestors(
   }
 }
 
+// ─── Write validation (both arms) ────────────────────────────────────
+//
+// firebase-admin validates a write before it is sent and throws the error
+// synchronously, so both arms do the same here, with the SDK's text
+// (`validateFirebaseDataArg`, `validateFirebaseMergeDataArg`). Both arms
+// then write the value as RTDB stores it (`normalizeNode`): the remote arm
+// relays that, not the raw value, so a value JSON would carry differently
+// (a `Date` becomes a string) is written as firebase-admin writes it.
+//
+// Priorities are not modeled on either arm: a valid priority, inline or
+// under an `update()` key ending in `.priority`, is accepted and dropped.
+
+/** The value a `set` or `push` writes, as RTDB stores it, after throwing the
+ *  SDK's error for a value it refuses. `segs` is the reference's path: for
+ *  `push`, the parent's. */
+function validateValueArg(fnName: 'set' | 'push', segs: string[], value: unknown): JsonValue {
+  validateWrite(value, joinPath(segs), errorPrefix(fnName, 'value'));
+  inlinePriorities(value);
+  return normalizeNode(value);
+}
+
+/** Whether an `update()` key addresses a priority, as `a/.priority` does. */
+function isPriorityKey(key: string): boolean {
+  const segments = pathSegments(key);
+  return segments[segments.length - 1] === '.priority';
+}
+
+/** The patch an `update` writes, each value as RTDB stores it and priority
+ *  keys dropped, after throwing the SDK's error for values it refuses. */
+function validateValuesArg(segs: string[], values: unknown): Record<string, JsonValue> {
+  const entries = Object.entries(validateUpdate(values, joinPath(segs)));
+  for (const [, value] of entries) inlinePriorities(value);
+  const dataEntries = entries.filter(([key]) => !isPriorityKey(key));
+  return Object.fromEntries(dataEntries.map(([key, value]) => [key, normalizeNode(value)]));
+}
+
+/** Run a synchronous in-memory write as a promise that settles with it. */
+function settled(write: () => void): Promise<void> {
+  try {
+    write();
+    return Promise.resolve();
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+
 // ─── Push-id generator ────────────────────────────────────────────────
 //
 // Lifted from `pyric/database/sandbox/push-id.ts` — the algorithm
@@ -633,9 +685,11 @@ function buildSandboxRef(
 
     // ─── Data-plane methods (implemented) ────────────────────────────
 
-    /** Set `value` at this path. `null` deletes. */
-    async set(value: unknown): Promise<void> {
-      writePath(state.root, canonical, value as JsonValue);
+    /** Set `value` at this path. `null` deletes. A value the SDK refuses
+     *  throws synchronously, as firebase-admin does. */
+    set(value: unknown): Promise<void> {
+      const stored = validateValueArg('set', segs, value);
+      return settled(() => writePath(state.root, canonical, stored));
     },
 
     /** Read this path. Resolves to a {@link DataSnapshot}-shaped value. */
@@ -663,22 +717,20 @@ function buildSandboxRef(
     },
 
     /** Shallow merge: each key in `values` replaces the corresponding
-     *  child at this path. `null` values delete. */
-    async update(values: object): Promise<void> {
-      if (values === null || typeof values !== 'object') {
-        throw new TypeError(
-          'pyric-admin/database sandbox: update expected an object.',
-        );
-      }
-      for (const [k, v] of Object.entries(values as Record<string, unknown>)) {
-        const subSegs = [...segs, ...pathSegments(k)];
-        writePath(state.root, joinPath(subSegs), v as JsonValue);
-      }
+     *  child at this path. `null` values delete. Values the SDK refuses
+     *  throw synchronously, as firebase-admin does. */
+    update(values: object): Promise<void> {
+      const patch = validateValuesArg(segs, values);
+      return settled(() => {
+        for (const [k, v] of Object.entries(patch)) {
+          writePath(state.root, joinPath([...segs, ...pathSegments(k)]), v);
+        }
+      });
     },
 
     /** Delete the subtree at this path. Equivalent to `set(null)`. */
-    async remove(): Promise<void> {
-      writePath(state.root, canonical, null);
+    remove(): Promise<void> {
+      return settled(() => writePath(state.root, canonical, null));
     },
 
     /** Mint a 20-char push id, optionally writing `value` at the new
@@ -687,11 +739,12 @@ function buildSandboxRef(
      *  once the (synchronous) write completes; the underlying ref is
      *  available synchronously via the returned object's own methods. */
     push(value?: unknown, onComplete?: (err: Error | null) => void): AdminThenableReference {
+      const stored = value === undefined ? undefined : validateValueArg('push', segs, value);
       const id = generatePushId();
       const childPath = joinPath([...segs, id]);
-      if (value !== undefined) {
+      if (stored !== undefined) {
         try {
-          writePath(state.root, childPath, value as JsonValue);
+          writePath(state.root, childPath, stored);
         } catch (err) {
           if (onComplete) onComplete(err as Error);
           throw err;
@@ -813,18 +866,28 @@ function buildSandboxRef(
  *  the load-bearing subset of firebase-admin's `DataSnapshot` shape.
  *  Backend-agnostic: the snapshot is a pure (path, value) view; `refAt`
  *  supplies backend-appropriate `Reference`s (local tree or remote), so
- *  the local and remote arms share one snapshot implementation. */
+ *  the local and remote arms share one snapshot implementation.
+ *
+ *  `stored` is the value as RTDB stores it, children by key, with no
+ *  arrays. `val()` renders integer keys as an array when they are dense
+ *  enough; `exportVal()` and `toJSON()` never do (`ChildrenNode.val`
+ *  builds an array only when not exporting). `exported`, when given, is the
+ *  host's export of the same node, priorities included. */
 function buildSandboxSnap(
   refAt: (path: string) => AdminReference,
   path: string,
-  val: JsonValue,
+  stored: JsonValue,
+  exported?: unknown,
 ): AdminDataSnapshot {
   const segs = pathSegments(path);
   const key = segs.length === 0 ? null : segs[segs.length - 1]!;
-  const exists = val !== null;
-  // An array value still has children: `val()` renders integer keys as an
-  // array, and the SDK iterates them as '0', '1', ... (#1110).
-  const children = valueChildren(val);
+  const exists = stored !== null;
+  // A node `val()` renders as an array still has its children, keyed
+  // '0', '1', ... in index order (#1110).
+  const children = valueChildren(stored);
+  const val = coerceArrays(stored);
+  const exportedChild = (childSegs: readonly string[]): unknown =>
+    exported === undefined ? undefined : valueAtChildPath(exported, childSegs);
   const snap = {
     key,
     get ref(): AdminReference {
@@ -838,8 +901,8 @@ function buildSandboxSnap(
     },
     child(p: string): AdminDataSnapshot {
       const childSegs = pathSegments(p);
-      const childVal = valueAtChildPath(val, childSegs) as JsonValue;
-      return buildSandboxSnap(refAt, joinPath([...segs, ...childSegs]), childVal);
+      const childVal = valueAtChildPath(stored, childSegs) as JsonValue;
+      return buildSandboxSnap(refAt, joinPath([...segs, ...childSegs]), childVal, exportedChild(childSegs));
     },
     hasChild(p: string): boolean {
       return snap.child(p).exists();
@@ -852,13 +915,13 @@ function buildSandboxSnap(
     },
     forEach(cb: (child: AdminDataSnapshot) => boolean | void): boolean {
       for (const { key: childKey, value } of children) {
-        const childSnap = buildSandboxSnap(refAt, joinPath([...segs, childKey]), value as JsonValue);
+        const childSnap = buildSandboxSnap(refAt, joinPath([...segs, childKey]), value as JsonValue, exportedChild([childKey]));
         if (cb(childSnap) === true) return true;
       }
       return false;
     },
     toJSON(): unknown {
-      return val;
+      return snap.exportVal();
     },
     // RTDB priority isn't modeled — return `null`, matching the SDK
     // default for a node without an explicit priority.
@@ -866,9 +929,9 @@ function buildSandboxSnap(
       return null;
     },
     exportVal(): unknown {
-      // No priorities → `exportVal()` matches `val()`. The SDK's
-      // exportVal includes `.priority` when set; we have none.
-      return val;
+      // The SDK's export format adds `.priority` where one is set. The
+      // in-process arm models no priorities, so it is the stored value.
+      return structuredClone(exported === undefined ? stored : exported);
     },
   };
   return snap as unknown as AdminDataSnapshot;
@@ -895,6 +958,8 @@ interface RemoteWireSnapshot {
   key: string | null;
   exists: boolean;
   value: unknown;
+  /** `exportVal()` on the host, priorities included. */
+  exportValue?: unknown;
   size: number;
 }
 
@@ -971,8 +1036,12 @@ function buildRemoteRef(
   const segs = pathSegments(canonical);
   const key = segs.length === 0 ? null : segs[segs.length - 1]!;
   const refAt = (p: string): AdminReference => buildRemoteRef(state, db, p);
+  // The host sends `val()`, arrays included; storing it again by key
+  // recovers the stored value (an array's nulls are holes, not children).
+  // `exportValue` carries the priorities another plane set; this arm writes
+  // none, but reads them back as the host has them.
   const snapFromWire = (wire: RemoteWireSnapshot): AdminDataSnapshot =>
-    buildSandboxSnap(refAt, canonical, (wire.value ?? null) as JsonValue);
+    buildSandboxSnap(refAt, canonical, normalizeNode(wire.value ?? null), wire.exportValue);
 
   const ref = {
     key,
@@ -992,13 +1061,14 @@ function buildRemoteRef(
 
     // ─── Data-plane methods (relayed worker ops) ─────────────────────
 
-    /** Set `value` at this path. `null` deletes. Relays `rtdb.set`. */
-    async set(value: unknown): Promise<void> {
-      await relayRtdbOp(state, {
+    /** Set `value` at this path. `null` deletes. Relays `rtdb.set`. A
+     *  value the SDK refuses throws synchronously and is not relayed. */
+    set(value: unknown): Promise<void> {
+      return relayRtdbOp(state, {
         method: 'rtdb.set',
         path: canonical,
-        value: value ?? null,
-      });
+        value: validateValueArg('set', segs, value),
+      }).then(() => undefined);
     },
 
     /** Read this path (`rtdb.get`). Resolves to a `DataSnapshot`. */
@@ -1047,18 +1117,15 @@ function buildRemoteRef(
 
     /** Relays `rtdb.update` — the worker applies the FULL multi-path
      *  update semantics (`pyric/database`), an upgrade over the
-     *  local arm's shallow per-key merge. `null` values delete. */
-    async update(values: object): Promise<void> {
-      if (values === null || typeof values !== 'object') {
-        throw new TypeError(
-          'pyric-admin/database sandbox: update expected an object.',
-        );
-      }
-      await relayRtdbOp(state, {
+     *  local arm's shallow per-key merge. `null` values delete. Values the
+     *  SDK refuses throw synchronously and are not relayed. */
+    update(values: object): Promise<void> {
+      const patch = validateValuesArg(segs, values);
+      return relayRtdbOp(state, {
         method: 'rtdb.update',
         path: canonical,
-        values: values as Record<string, unknown>,
-      });
+        values: patch,
+      }).then(() => undefined);
     },
 
     /** Delete the subtree at this path (`rtdb.remove`). */
@@ -1079,12 +1146,13 @@ function buildRemoteRef(
      * rejects the thenable and reaches `onComplete`.
      */
     push(value?: unknown, onComplete?: (err: Error | null) => void): AdminThenableReference {
+      const stored = value === undefined ? undefined : validateValueArg('push', segs, value);
       const id = generatePushId();
       const childPath = joinPath([...segs, id]);
       const write: Promise<void> =
-        value === undefined
+        stored === undefined
           ? Promise.resolve()
-          : relayRtdbOp(state, { method: 'rtdb.push', path: canonical, key: id, value })
+          : relayRtdbOp(state, { method: 'rtdb.push', path: canonical, key: id, value: stored })
               .then(() => undefined);
       // Surface completion without forcing the caller to await: `.then`'s
       // rejection handler also keeps a fire-and-forget push from becoming

package/src/storage/delete-files.ts

@@ -7,7 +7,7 @@
  * started. With `force`, every file is tried, and the call rejects with the
  * array of errors when any failed, as the library's callback receives them.
  */
-import { everyListedName, type DeleteFilesOptions } from './file-query.js';
+import { entryOf, everyListedName, resumesAfter, type DeleteFilesOptions } from './file-query.js';
 
 /** How many deletes `@google-cloud/storage` runs at once. */
 const PARALLEL_DELETES = 10;
@@ -38,3 +38,22 @@ export async function deleteListedFiles(
   if (!force) throw errors[0];
   throw errors;
 }
+
+/**
+ * A stop rule for names arriving in name order: true once they hold the
+ * `maxResults` files `deleteFiles(query)` deletes. Without `maxResults` it
+ * deletes every listed file, so it needs every name.
+ */
+export function deletedNamesFound(query: DeleteFilesOptions): (name: string) => boolean {
+  const maxResults = query.maxResults ?? 0;
+  const limited = maxResults > 0;
+  if (!limited) return () => false;
+  const after = resumesAfter(query);
+  let found = 0;
+  return (name) => {
+    const entry = entryOf(name, query);
+    const listedFile = entry !== undefined && !entry.rolledUp && (after === undefined || entry.key > after);
+    if (listedFile) found += 1;
+    return found >= maxResults;
+  };
+}

package/src/storage/file-query.ts

@@ -64,7 +64,7 @@ export function readsEveryPage(query: GetFilesOptions): boolean {
 /** The page of `names` that `query` asks for, `pageSize` entries at most. */
 export function listingPage(names: readonly string[], query: GetFilesOptions, pageSize = pageSizeOf(query)): ListingPage {
   const entries = entriesOf(names, query);
-  const after = query.pageToken === undefined ? undefined : decodeToken(query.pageToken);
+  const after = resumesAfter(query);
   const remaining = after === undefined ? entries : entries.filter(entry => entry.key > after);
   const page = remaining.slice(0, pageSize);
   const more = remaining.length > page.length;
@@ -93,34 +93,46 @@ export function apiResponseOf(page: ListingPage): GetFilesApiResponse {
   };
 }
 
-function pageSizeOf(query: GetFilesOptions): number {
+/** The entry key a query's `pageToken` resumes after, if it has one. */
+export function resumesAfter(query: GetFilesOptions): string | undefined {
+  return query.pageToken === undefined ? undefined : decodeToken(query.pageToken);
+}
+
+export function pageSizeOf(query: GetFilesOptions): number {
   const limited = typeof query.maxResults === 'number' && query.maxResults > 0;
   return limited ? Math.min(query.maxResults!, DEFAULT_PAGE_SIZE) : DEFAULT_PAGE_SIZE;
 }
 
-interface Entry {
+/** A listed entry: a file name, or a prefix that names roll up to at the delimiter. */
+export interface Entry {
   key: string;
   rolledUp: boolean;
 }
 
-/** The names under the prefix, with the delimiter's roll-up applied, in name order. */
-function entriesOf(names: readonly string[], query: GetFilesOptions): Entry[] {
+/** The entry `name` lists as under `query`'s prefix and delimiter, or `undefined` outside the prefix. */
+export function entryOf(name: string, query: GetFilesOptions): Entry | undefined {
   const prefix = query.prefix ?? '';
   const delimiter = query.delimiter ?? '';
+  if (!name.startsWith(prefix)) return undefined;
+  const rest = name.slice(prefix.length);
+  const cut = delimiter === '' ? -1 : rest.indexOf(delimiter);
+  const rolledUp = cut !== -1;
+  const key = rolledUp ? prefix + rest.slice(0, cut + delimiter.length) : name;
+  return { key, rolledUp };
+}
+
+/** The names under the prefix, with the delimiter's roll-up applied, in name order. */
+function entriesOf(names: readonly string[], query: GetFilesOptions): Entry[] {
   const byKey = new Map<string, Entry>();
   for (const name of names) {
-    if (!name.startsWith(prefix)) continue;
-    const rest = name.slice(prefix.length);
-    const cut = delimiter === '' ? -1 : rest.indexOf(delimiter);
-    const rolledUp = cut !== -1;
-    const key = rolledUp ? prefix + rest.slice(0, cut + delimiter.length) : name;
-    byKey.set(key, { key, rolledUp });
+    const entry = entryOf(name, query);
+    if (entry !== undefined) byKey.set(entry.key, entry);
   }
   return [...byKey.values()].sort((a, b) => compareKeys(a.key, b.key));
 }
 
 /** Name order, as the JSON API lists objects. */
-function compareKeys(a: string, b: string): number {
+export function compareKeys(a: string, b: string): number {
   if (a < b) return -1;
   if (a > b) return 1;
   return 0;

package/src/storage/get-files.ts

@@ -10,8 +10,11 @@
  */
 import {
   apiResponseOf,
+  entryOf,
   listingPage,
+  pageSizeOf,
   readsEveryPage,
+  resumesAfter,
   type GetFilesApiResponse,
   type GetFilesOptions,
 } from './file-query.js';
@@ -38,3 +41,25 @@ function onePage<F>(names: readonly string[], query: GetFilesOptions, fileOf: (n
   const nextQuery = token === undefined ? null : { ...query, pageToken: token };
   return [page.names.map(fileOf), nextQuery, apiResponseOf(page)];
 }
+
+/**
+ * A stop rule for names arriving in name order: true once they hold every
+ * entry the result for `query` needs. A single page needs one entry past its
+ * size, to know there is a next page; reading every page needs every name.
+ */
+export function pageNamesFound(query: GetFilesOptions): (name: string) => boolean {
+  if (readsEveryPage(query)) return () => false;
+  const after = resumesAfter(query);
+  const wanted = pageSizeOf(query) + 1;
+  let found = 0;
+  let lastKey: string | undefined;
+  return (name) => {
+    const key = entryOf(name, query)?.key;
+    const listed = key !== undefined && (after === undefined || key > after);
+    const isNewEntry = listed && key !== lastKey;
+    if (!isNewEntry) return false;
+    lastKey = key;
+    found += 1;
+    return found >= wanted;
+  };
+}