fireemu 0.17.0 → 0.18.0

package/README.md

@@ -14,7 +14,7 @@ Fireemu is being developed to close these gaps. For example, it provides:
 
 Fireemu is still in development and does not yet reproduce every feature and behavior of production Firebase. Before relying on Fireemu’s test results in CI or other automated workflows, we recommend differential testing against production Firebase services for the features and critical workflows your application uses. Run the same tests against Fireemu and a dedicated Firebase test project, and check for differences in results and behavior that could affect your application. Use a dedicated test project, not your live production project.
 
-See the [capability manifest](https://github.com/t-k/fireemu/blob/v0.17.0/crates/fireemu/src/capabilities.json) and [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.17.0/docs/compatibility-contract.md) for supported features, known differences, and the status of compatibility verification.
+See the [capability manifest](https://github.com/t-k/fireemu/blob/v0.18.0/crates/fireemu/src/capabilities.json) and [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.18.0/docs/compatibility-contract.md) for supported features, known differences, and the status of compatibility verification.
 
 ## Quick start
 
@@ -70,13 +70,13 @@ Fireemu supports Cloud Firestore, Firebase Authentication (Identity Platform), C
 | Cloud Pub/Sub | Schemas, BigQuery and Cloud Storage subscription delivery, and some APIs such as `UpdateTopic` are not supported.  |
 | Firebase App Check | Local testing with debug tokens is supported. Real attestation through Play Integrity, App Attest, DeviceCheck, or reCAPTCHA, and replay protection using limited-use tokens, are not supported.  |
 
-This table highlights key limitations; it is not exhaustive. Check individual API support and conditions with the following command or the [capability manifest](https://github.com/t-k/fireemu/blob/v0.17.0/crates/fireemu/src/capabilities.json).
+This table highlights key limitations; it is not exhaustive. Check individual API support and conditions with the following command or the [capability manifest](https://github.com/t-k/fireemu/blob/v0.18.0/crates/fireemu/src/capabilities.json).
 
 ```sh
 npx fireemu capabilities
 ```
 
-See the [Functions support inventory](https://github.com/t-k/fireemu/blob/v0.17.0/docs/functions-export-inventory.md) for support by trigger type.
+See the [Functions support inventory](https://github.com/t-k/fireemu/blob/v0.18.0/docs/functions-export-inventory.md) for support by trigger type.
 
 ### Unsupported products
 
@@ -135,7 +135,7 @@ Use `--ui-port 0` to disable the UI. When automatic UI startup cannot bind the d
 
 When a Functions codebase is loaded, the Functions page shows registered functions, triggers, invocation results, and logs. You can run scheduled functions immediately or advance the virtual clock to their next scheduled execution. 
 
-For clock-sensitive and parallel integration tests, [test clocks and independent worlds](https://github.com/t-k/fireemu/blob/v0.17.0/docs/test-worlds.md) describes explicit Node Date/timer/Cloud Tasks policies and the `fireemu/testing` helper. Separate worlds isolate their clocks, Rules, Functions and service state, including when they use the same project ID.
+For clock-sensitive and parallel integration tests, [test clocks and independent worlds](https://github.com/t-k/fireemu/blob/v0.18.0/docs/test-worlds.md) describes explicit Node Date/timer/Cloud Tasks policies and the `fireemu/testing` helper. Separate worlds isolate their clocks, Rules, Functions and service state, including when they use the same project ID.
 
 ### Export data
 
@@ -151,6 +151,18 @@ On Unix-like systems, the destination and its ancestor directories are subject t
 
 On macOS, an ancestor directory with an ACL is refused when the ACL has an `allow` entry for anyone but the owner, root or the user running the export, whatever permissions the entry shows (the kernel grants rights that `ls -le` does not list). `deny` entries are accepted, so a standard home directory (which carries `group:everyone deny delete`) and the folders below it work. When an export is refused for an ACL, the message names the entry; remove it (`chmod -a`) or export to another directory, for example one under `$TMPDIR`. Check an ancestor with `/bin/ls -led <directory>`. A destination on a volume that ignores ownership (exFAT and FAT sticks and cards, or an external APFS volume with "Ignore ownership on this volume" turned on) is refused, because the owner and the mode of its directories do not show who can change them; export to a volume that enforces ownership. A volume without atomic directory rename (exFAT, FAT, some network filesystems) cannot publish an export either: use a directory on an APFS volume.
 
+### Keep data between runs
+
+`--import <dir>` loads an export at startup, and `--export-on-exit` (without a directory of its own) writes the state back to the same directory when the run ends:
+
+```sh
+npx fireemu exec --import ./emulator-data --export-on-exit -- npm test
+```
+
+- An empty `--import` directory starts with no data, so the first run of a new volume needs no separate command. A missing directory is refused (a mistyped path must not start an empty suite), unless it is also where `--export-on-exit` writes. A directory that holds anything but no `firebase-export-metadata.json` is refused.
+- A failed `--export-on-exit` is printed as an `error:` line, and the run exits 1 when the command succeeded (a failing command keeps its own exit code). The official CLI only warns and exits 0; Fireemu differs so that a CI job that depends on the saved data cannot pass without it.
+- The export directory may be a volume mount point, for example a container volume mounted at `/data`. A mount point cannot be replaced by an atomic rename, so the export is staged inside it and moved into place, the old `firebase-export-metadata.json` leaving first and the new one arriving last. That replacement is not atomic: an interrupted export leaves a directory without the manifest, which `--import` refuses instead of loading part of it. Any other directory is still replaced atomically.
+
 ### Troubleshooting
 
 For startup or installation problems, inspect the environment and bundled files with:
@@ -214,6 +226,17 @@ Under the `strict` profile, a project without Security Rules behaves as a produc
 
 The answers keep production's wording, which does not mention Fireemu. The startup output therefore has a `firestore rules:` and a `storage rules:` line that say when no rules are loaded and how to load them, and the first refused request for each database and bucket (up to 32 of each) prints a warning to standard error. Name the rules files in `firebase.json` (`firestore.rules`, `storage.rules`) or in `fireemu.json` (`rules.source`, `storage.rules`).
 
+### Why a request was denied
+
+A Security Rules denial is answered with production's wording (Firestore's `PERMISSION_DENIED` "Missing or insufficient permissions.", Storage's 403), which does not say which rule refused. Fireemu therefore prints each denial of an end-user request to standard error, with every `allow` condition the request evaluated and what it evaluated to:
+
+```text
+note: firestore: Security Rules denied get on "notes/n1" in "database (default)" (request.auth.uid "bob"): no allow statement evaluated to true; line 5:22 `request.auth.uid == resource.data.owner` was false
+```
+
+- Set `rules.denialLog` to `"off"` in `fireemu.json` to silence these lines (for example in a suite that asserts many denials). The answer to the client is the same either way.
+- When the UI is running, its Rules page lists the decided requests from the start of the run, with what every expression evaluated to. The same trace is served by `GET /v1/sessions/default/rules/requests` on the control API.
+
 ### Compatibility profiles
 
 | Profile | Behavior |
@@ -241,8 +264,10 @@ Fireemu is mostly run by tests, in CI and on a developer's machine. Where produc
 | Unsigned emulator custom tokens are accepted | `auth.allowUnsignedCustomTokens` | refused |
 | Firestore and Storage Security Rules accept `@firebase/rules-unit-testing`'s unsigned mock ID token (`authenticatedContext()`, the client SDK's `mockUserToken`) | `auth.allowUnsignedIdTokens` | refused, as production refuses an unsigned token |
 | Identity-provider sign-in accepts the fixture assertions and the sign-in widget (`/emulator/auth/handler`), for built-in, `oidc.*` and `saml.*` providers | `auth.idpAssertions` (`"fixture"`) | `"signed"`: OIDC ID tokens must verify with an `auth.idpSigners` key, SAML responses with the provider's certificates, and the fixture and built-in providers are refused |
-| The strict Eventarc listener admits any credential or none, so the Admin SDK publishes with a fake credential (see [Eventarc authentication](https://github.com/t-k/fireemu/blob/v0.17.0/docs/eventarc-authentication.md)) | `eventarc.authentication` (`"permissive"`) | `"production"`: a missing, malformed or JWT-shaped bearer is refused with production's 401 |
+| The strict Eventarc listener admits any credential or none, so the Admin SDK publishes with a fake credential (see [Eventarc authentication](https://github.com/t-k/fireemu/blob/v0.18.0/docs/eventarc-authentication.md)) | `eventarc.authentication` (`"permissive"`) | `"production"`: a missing, malformed or JWT-shaped bearer is refused with production's 401 |
 | A query whose composite index is not defined (or is still building, or was deleted) runs, and each missing index is reported once per database on stderr with production's refusal text and the `firestore.indexes.json` entry | `firestore.missingIndexes` (`"report"`) | refused with `FAILED_PRECONDITION` and the console link (`"refuse"`) |
+| A tenant of `auth.tenants` can have any readable id, such as `tenant-a` | `auth.tenantIdFormat` (`"readable"`) | the id must have production's generated form, the display name, a hyphen and five characters of `a-z0-9` (`"generated"`) |
+| An end user's native gRPC `Listen` stream stays open however long it is held. `POST /v1/firestore/listen:expire` on the control API ends every held end-user stream at once, with production's status, to test a client's reconnect | `firestore.listenStreamLifetime` (`"unlimited"`) | ended with `INTERNAL` an hour after it opened, as production ends it (`"oneHour"`) |
 
 The start banner and `fireemu capabilities` report whether `productionExact` is set.
 
@@ -286,7 +311,7 @@ You can also name the configuration file with `--config`.
 npx fireemu up --config ./fireemu.json
 ```
 
-Keep Fireemu-specific settings in a Fireemu configuration file containing `"schemaVersion": 1`, rather than in `firebase.json`. See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.17.0/spec/config/fireemu.schema.json) for all available settings. 
+Keep Fireemu-specific settings in a Fireemu configuration file containing `"schemaVersion": 1`, rather than in `firebase.json`. See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.18.0/spec/config/fireemu.schema.json) for all available settings. 
 
 ### Firebase Authentication (Identity Platform) configuration
 
@@ -317,9 +342,9 @@ Unsigned custom tokens minted by the Firebase Admin SDK in emulator mode are acc
 
 The unsigned mock ID token of `@firebase/rules-unit-testing` is accepted by default when Firestore and Storage Security Rules are evaluated, including with the `strict` profile. This is the token `authenticatedContext()` and the client SDKs' `mockUserToken` option send (`createMockUserToken` in `@firebase/util`). Under `strict` only that exact shape is accepted: a JWT whose header is exactly `{"alg":"none","type":"JWT"}` and whose signature is empty. `request.auth` is built from the token's claims, as the official emulator builds it, when the token names a subject (`sub`) and its audience (`aud`) is the project the request goes to. Its `exp` is not checked, because the SDK sets `iat: 0` and `exp: 3600` by default. Every other token is verified as before, expiry included. That covers the unsigned ID tokens fireemu itself issues (their header carries `typ`, not `type`), and a token that claims a signature that does not verify is still refused. The `emulator` profile accepts any unsigned token, as the official emulator does, and its Storage also accepts another project's token. To refuse the mock token as production does, set `auth.allowUnsignedIdTokens` to `false` (in either profile) or set `productionExact`. A session with `auth.idTokenSigning: "session-rsa"` accepts no unsigned token. The setting does not affect callable Functions, Identity Toolkit or App Check.
 
-See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.17.0/spec/config/fireemu.schema.json) for the format and accepted values of each setting.  
+See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.18.0/spec/config/fireemu.schema.json) for the format and accepted values of each setting.  
 
-Declare `auth.authorizedDomains`, for example `["localhost", "app.test"]`, to set the initial project-wide list in either profile. The list replaces the defaults, so include `localhost` if your tests use it. An empty list authorizes no host under `strict`; an absent or `null` setting keeps the existing defaults (`localhost` and the project's `firebaseapp.com` and `web.app` domains). Validation uses the Admin API's rules for the selected profile, including its conversion of numeric and boolean entries to strings and omission of `null` entries; use strings when writing the list. Fireemu intentionally keeps `localhost` in its defaults for development. The [recorded production sandbox baseline](https://github.com/t-k/fireemu/blob/v0.17.0/conformance/auth-action-production.json) does not include it; new production projects may also omit it. This default is a Fireemu-only convenience, and declaring the list replaces it. Tenant-scoped strict action links currently check the tenant's default domains rather than this project declaration; support for the parent project's live list is pending.
+Declare `auth.authorizedDomains`, for example `["localhost", "app.test"]`, to set the initial project-wide list in either profile. The list replaces the defaults, so include `localhost` if your tests use it. An empty list authorizes no host under `strict`; an absent or `null` setting keeps the existing defaults (`localhost` and the project's `firebaseapp.com` and `web.app` domains). Validation uses the Admin API's rules for the selected profile, including its conversion of numeric and boolean entries to strings and omission of `null` entries; use strings when writing the list. Fireemu intentionally keeps `localhost` in its defaults for development. The [recorded production sandbox baseline](https://github.com/t-k/fireemu/blob/v0.18.0/conformance/auth-action-production.json) does not include it; new production projects may also omit it. This default is a Fireemu-only convenience, and declaring the list replaces it. Tenant-scoped strict action links currently check the tenant's default domains rather than this project declaration; support for the parent project's live list is pending.
 
 An Admin update changes the live list. A session reset restores the declared list, when present, and preserves an Admin-written list when no initial list was declared. Projects created later receive the declaration word for word, independently of the default project's live list; listing a particular project's `firebaseapp.com` or `web.app` domain therefore gives later projects that same domain. Clearing accounts leaves the live list alone. Auth export/import carries accounts without the domain list or its declaration. The `emulator` profile accepts the setting and exposes the list, while continuing to allow action-link continue URLs outside it.
 
@@ -413,11 +438,11 @@ Under the `strict` profile, TOTP is enabled only through the project's MFA confi
 
 #### Enable multi-tenancy
 
-Under the `strict` profile, enable `multiTenant.allowTenants` before using multi-tenancy: through the Admin API, or with `auth.multiTenant` in the file (see "Start with tenants" below). See the [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.17.0/docs/compatibility-contract.md) for the supported Admin API scope. 
+Under the `strict` profile, enable `multiTenant.allowTenants` before using multi-tenancy: through the Admin API, or with `auth.multiTenant` in the file (see "Start with tenants" below). See the [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.18.0/docs/compatibility-contract.md) for the supported Admin API scope. 
 
 #### Start with tenants
 
-Instead of creating tenants through the Admin API in every session, declare the default project's tenants and the multi-tenancy switch in the file. Each entry of `auth.tenants` is an Admin v2 `Tenant` document plus its `tenantId`, which has the form production generates, the display name, a hyphen, and five characters of `a-z0-9`:
+Instead of creating tenants through the Admin API in every session, declare the default project's tenants and the multi-tenancy switch in the file. Each entry of `auth.tenants` is an Admin v2 `Tenant` document plus its `tenantId`. By default the id can be any readable name that starts with a letter and holds letters, digits and hyphens (up to 63 characters), such as `tenant-a`. With `productionExact` or `auth.tenantIdFormat: "generated"` it must have the form production generates, the display name, a hyphen, and five characters of `a-z0-9`, such as `acme-x7k2q`:
 
 ```json
 {
@@ -427,7 +452,7 @@ Instead of creating tenants through the Admin API in every session, declare the
     "multiTenant": { "allowTenants": true },
     "tenants": [
       {
-        "tenantId": "acme-x7k2q",
+        "tenantId": "tenant-a",
         "displayName": "acme",
         "allowPasswordSignup": true,
         "mfaConfig": { "state": "ENABLED", "enabledProviders": ["PHONE_SMS"] }
@@ -464,7 +489,7 @@ A schedule is driven by the virtual clock alone: real time passing runs nothing.
 
 A manual run (`POST /v1/sessions/{session}/functions/{name}:run`) enqueues one run of a scheduled function stamped with the current virtual time. It does not consume the next occurrence, which still comes due and is subject to `scheduler.overlap` like any run. It answers `400 INVALID_ARGUMENT` for an unknown function, a function that is not scheduled, an overlap policy refusal, or a runtime that is shutting down, and `429 RESOURCE_EXHAUSTED` when the event queue is full. This is fireemu's own control, not a claim about production's run-now.
 
-See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.17.0/spec/config/fireemu.schema.json) for available settings and values. 
+See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.18.0/spec/config/fireemu.schema.json) for available settings and values. 
 
 ### Firestore history limits
 
@@ -542,15 +567,34 @@ Fireemu is compatible with the listed Local Emulator Suite products as shipped b
 
 The `strict` and `emulator` profiles differ in some behaviors to serve their respective purposes. Where the official emulator and production Firebase disagree, Fireemu also adopts production behavior in some cases and records the difference.
 
-Check support for the specific APIs and conditions your application uses, rather than relying on product names alone. The [compatibility contract](https://github.com/t-k/fireemu/blob/v0.17.0/spec/compatibility/contract.json) records scope and known differences. The [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.17.0/docs/compatibility-contract.md) explains the verification process and how to interpret its records. 
+Check support for the specific APIs and conditions your application uses, rather than relying on product names alone. The [compatibility contract](https://github.com/t-k/fireemu/blob/v0.18.0/spec/compatibility/contract.json) records scope and known differences. The [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.18.0/docs/compatibility-contract.md) explains the verification process and how to interpret its records. 
 
 ### Network exposure of the Storage port
 
 Like the official emulator, the Storage port reflects the requested object name in the HTML body of its 404 for a missing media read (`text/html`, as production answers). A web page opened on the developer's machine could therefore run script on that origin. Keep the emulator bound to localhost, which is the default, and do not expose the Storage port to other hosts or networks. The strict profile sends no `X-Content-Type-Options: nosniff` on the JSON API answers where production sends none, so it does not add that defence in depth; the emulator profile keeps the official emulator's header.
 
+### Run in a container
+
+By default every listener is on loopback, which a published container port cannot reach. To serve the emulators to the host or to other containers, opt in with `network.allowNonLoopbackHosts` in `fireemu.json` and give the product emulators a host in `firebase.json`:
+
+```json
+{ "schemaVersion": 1, "firebaseJson": "firebase.json", "network": { "allowNonLoopbackHosts": true } }
+```
+
+```json
+{ "emulators": { "firestore": { "host": "0.0.0.0", "port": 8080 }, "auth": { "host": "0.0.0.0", "port": 9099 } } }
+```
+
+- Only Firestore, Auth, Storage, Functions, Eventarc, Cloud Tasks and Pub/Sub may listen off loopback. The Hub, the UI and the Logging emulator stay on loopback. Auth, whose port also serves the control API, listens on loopback or on every interface (`0.0.0.0` or `::`), not on one other address.
+- The emulators serve without a credential, so the start prints a `warning:` line for each listener off loopback. Any client that reaches a published port can do what a local client can on the product APIs, including the Admin SDK's `Bearer owner` credential and the Auth emulator's own routes. Publish the ports only to a network you trust.
+- Fireemu's own controls answer loopback peers only and return 403 to any other peer: the control API (`/v1/` and `/health/` on the Auth port), App Check debug-token management, and the routes that load Security Rules or clear Firestore data (what `@firebase/rules-unit-testing`'s `loadFirestoreRules`, `loadStorageRules` and `clearFirestore` call). Run the code that uses them in the emulator's network namespace: inside the container, or in a container that shares it (a Podman pod, `--network container:<name>`).
+- Because a forwarder inside that namespace (`kubectl port-forward`, a sidecar proxy) connects from loopback, every control API request also needs `Authorization: Bearer <control token>` once the option is on, from a process as from a page; only `/health/` is exempt. The routes that load Security Rules or clear Firestore data are not held to the token, so `@firebase/rules-unit-testing` keeps working; a client that reaches the emulator through such a forwarder can call them, as it could on the official emulator. `fireemu exec` gives its command the token in `FIREEMU_CONTROL_TOKEN`, and `fireemu/testing` and the UI send it.
+- Browser pages must still come from a loopback origin (`http://localhost:...`), so a page served from another host cannot use the exposed ports.
+- A listener on `0.0.0.0` or `::` is advertised as `127.0.0.1` or `::1` in the environment and the Hub, as the official CLI does.
+
 ### Changes between versions
 
-Configuration and behavior may change between releases. See the [CHANGELOG](https://github.com/t-k/fireemu/blob/v0.17.0/CHANGELOG.md) for release changes.
+Configuration and behavior may change between releases. See the [CHANGELOG](https://github.com/t-k/fireemu/blob/v0.18.0/CHANGELOG.md) for release changes.
 
 ## Performance
 
@@ -567,7 +611,7 @@ The following results come from one `standard` run at commit `f3b942c`. Ratios a
 
 The 95% confidence interval for the startup-time ratio is `[21.4, 21.8]`. For the peak-memory ratio, calculated as official emulator divided by Fireemu, it is `[10.2, 11.1]`.
 
-See [benchmark.yml](https://github.com/t-k/fireemu/blob/v0.17.0/.github/workflows/benchmark.yml) for the workflow and [`tools/bench/`](https://github.com/t-k/fireemu/tree/v0.17.0/tools/bench/) for the benchmark implementation. 
+See [benchmark.yml](https://github.com/t-k/fireemu/blob/v0.18.0/.github/workflows/benchmark.yml) for the workflow and [`tools/bench/`](https://github.com/t-k/fireemu/tree/v0.18.0/tools/bench/) for the benchmark implementation. 
 
 ## Reporting issues and contributing
 
@@ -575,8 +619,8 @@ When reporting an issue, include the Fireemu and Firebase SDK versions, the prof
 
 For compatibility issues, also state whether you are comparing against the actual Firebase service or the official emulator, along with the expected and actual results. Remove credentials and personal information before sharing configuration files or logs.
 
-See the [development guide](https://github.com/t-k/fireemu/blob/v0.17.0/docs/development.md) for build and test instructions.
+See the [development guide](https://github.com/t-k/fireemu/blob/v0.18.0/docs/development.md) for build and test instructions.
 
 ## License
 
-Fireemu is licensed under the [Apache License 2.0](https://github.com/t-k/fireemu/blob/v0.17.0/LICENSE). Third-party notices are listed in [THIRD_PARTY_LICENSES.txt](https://github.com/t-k/fireemu/blob/v0.17.0/THIRD_PARTY_LICENSES.txt).
+Fireemu is licensed under the [Apache License 2.0](https://github.com/t-k/fireemu/blob/v0.18.0/LICENSE). Third-party notices are listed in [THIRD_PARTY_LICENSES.txt](https://github.com/t-k/fireemu/blob/v0.18.0/THIRD_PARTY_LICENSES.txt).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fireemu",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "A local runtime for testing Firebase SDK and Functions code, checked against production Firebase behavior",
   "keywords": [
     "emulator",
@@ -31,11 +31,11 @@
   ],
   "type": "module",
   "optionalDependencies": {
-    "@fireemu/darwin-arm64": "0.17.0",
-    "@fireemu/darwin-x64": "0.17.0",
-    "@fireemu/linux-x64": "0.17.0",
-    "@fireemu/linux-arm64": "0.17.0",
-    "@fireemu/win32-x64": "0.17.0"
+    "@fireemu/darwin-arm64": "0.18.0",
+    "@fireemu/darwin-x64": "0.18.0",
+    "@fireemu/linux-x64": "0.18.0",
+    "@fireemu/linux-arm64": "0.18.0",
+    "@fireemu/win32-x64": "0.18.0"
   },
   "engines": {
     "node": ">=20"