fireemu 0.9.0 → 0.11.0

package/README.md

@@ -1,122 +1,493 @@
+<!-- Generated from README.md by npm/scripts/prepare-launcher.mjs at pack time. Edit README.md in the repository, not this file. -->
+
 # Fireemu
 
-A local runtime for testing Firebase SDK and Functions code, checked against production Firebase behavior.
+Fireemu is a local emulator for testing applications built with Firebase. It aims to match production Firebase behavior as closely as possible, so you can test locally and in CI without using a real Firebase project.
+
+Passing tests against the official emulator does not always mean your application will behave the same way in production. Some features are not supported by the official emulator, and some execution conditions are difficult to reproduce locally. These gaps can leave you relying on a real Firebase project for part of your testing.
 
-Some Firebase failures are easy to miss locally. A query may need a composite index in production even though it passes against the official emulator. Production limits may reject a request that looked fine during development. Finding those problems only after running against a real Firebase project makes the feedback loop slow and can leave test data behind.
+Fireemu is being developed to close these gaps. For example, it provides:
 
-Fireemu was built for two jobs:
+- **Validation of configuration required in production:** Fireemu detects issues that the official emulator misses, such as missing Firestore index definitions.
+- **Support for features not available in the official emulator:** Fireemu also supports features such as TOTP-based multi-factor authentication.
+- **Control over test execution conditions:** You can set an arbitrary time and run scheduled functions to verify their behavior without waiting for the actual scheduled time.
 
-- catch selected production-facing problems earlier, including missing Firestore indexes and production limit violations;
-- keep local test runs fast, with no JVM emulator to start and a single command that starts the services, runs the test command, and shuts everything down.
+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.
 
-Fireemu is pre-1.0. It is not a replacement for the official Firebase Emulator Suite or for testing against a real Firebase project. Use it as an additional test target, keep the official emulator in your test matrix, and verify important flows against production before shipping.
+See the [capability manifest](https://github.com/t-k/fireemu/blob/v0.11.0/crates/fireemu/src/capabilities.json) and [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.11.0/docs/compatibility-contract.md) for supported features, known differences, and the status of compatibility verification.
 
-The real `firebase-admin`, `firebase` (Node and browser) and `firebase/firestore/lite` SDKs run against it unchanged. Run `npx fireemu capabilities` before depending on a specific API: each capability records whether it is implemented, partial, validation-only, or unsupported. The full feature summary, the known gaps from production Firebase and from the official Emulator Suite, and the project status are in the repository README linked below.
+## Quick start
 
-## Install
+Node.js 20 or newer is required.
 
 ```sh
-npm install -D fireemu
+npm install --save-dev fireemu
 npx fireemu init
-npx fireemu doctor
+
+# Start the emulator
+# UI (default): http://127.0.0.1:4000
+npx fireemu up
 ```
 
+Open the UI in your browser to inspect and manage data. Press `Ctrl+C` to stop the emulator.
+
+To run the emulator only for the duration of a command, use `exec` instead of `up`.
+
 ```sh
-pnpm add -D fireemu        # or: pnpm dlx fireemu doctor
-yarn add -D fireemu
+# Start the emulator, run a command, and stop when the command exits
+npx fireemu exec -- <command>
+
+# Example: run tests
+npx fireemu exec -- npm test
 ```
 
-Nothing is downloaded at install time and there is no install script. `fireemu` is a small Node
-launcher; the daemon for your platform arrives as an optional dependency
-(`@fireemu/darwin-arm64` and friends), so npm installs exactly one binary and skips the rest.
-An install that resolved from a cache or a private registry is a complete, offline installation.
+### Supported platforms
+
+| OS | Architecture |
+|---|---|
+| macOS 13 or newer | Apple silicon, Intel |
+| Linux | x86-64, arm64 |
+| Windows 10 or newer | x86-64 |
 
-## Initialize
+Running Functions requires `firebase-functions` v6 or v7 in the codebase. 
 
-`npx fireemu init` creates `fireemu.json` with the recommended `strict` profile. In a terminal, its wizard explains the production behavior supplied by `strict`, the pinned official emulator behavior selected by `emulator`, and how a referenced Firebase project configuration stays live. In CI or with redirected input it uses the strict defaults without prompting; use `--interactive` to force the wizard or `--yes`/`--no-interactive` to suppress it.
+## Supported scope
 
-If the project already has `firebase.json`, init records it as a live `firebaseJson` reference so rules, indexes, Functions codebases and emulator ports are loaded again on every start. `--profile emulator` and `--firebase-json <file>` choose alternatives explicitly. Existing `fireemu.json` files are preserved unless `--force` is supplied, and a symbolic link is never overwritten.
+Fireemu supports Cloud Firestore, Firebase Authentication (Identity Platform), Cloud Storage for Firebase, Cloud Functions for Firebase, Cloud Pub/Sub, and Eventarc. It also provides a local Firebase App Check implementation and a UI for managing data and viewing logs. 
+
+### Key unsupported features and limitations
+
+| Product | Key unsupported features and limitations |
+|---|---|
+| Cloud Firestore | The Enterprise Pipeline API supports a limited subset of read operations. Full-text search supports index definition validation, but local search execution is not supported.   |
+| Firebase Authentication (Identity Platform) | Authentication flows that communicate with external identity providers, authorization-code exchange, and SAML XML signature verification are outside the supported scope. These are separate from local authentication behavior and provider configuration.  |
+| Cloud Storage for Firebase | Object versioning, signed URLs, ACL-based access control, object composition (`compose`), and notification configuration are not supported.  |
+| Cloud Functions for Firebase | Triggers that depend on unsupported products, such as Realtime Database (deferred), Remote Config, and Data Connect (deferred), cannot run. Storage archive events do not occur because object versioning is not supported.  |
+| 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.11.0/crates/fireemu/src/capabilities.json).
 
 ```sh
-npx fireemu init --yes
-npx fireemu up --config fireemu.json
+npx fireemu capabilities
+```
+
+See the [Functions support inventory](https://github.com/t-k/fireemu/blob/v0.11.0/docs/functions-export-inventory.md) for support by trigger type.
+
+### Unsupported products
+
+Realtime Database, Firebase Hosting, App Hosting, and Data Connect are not currently supported. Firebase Extensions support is not planned. 
+
+## Usage
+
+### Select services
+
+Use `--only` to select the services to start.
+
+```sh
+# Start only Firebase Authentication (Identity Platform), Firestore, and Storage
+npx fireemu up --only auth,firestore,storage
+```
+
+You can also select an individual Functions codebase.
+
+```sh
+npx fireemu up --only functions:<codebase>
+```
+
+### Run a command
+
+Service selection also works with `exec`.
+
+```sh
+npx fireemu exec --only auth,firestore,storage -- npm test
+```
+
+`exec` sets the Firebase SDK emulator host environment variables for the child command and returns its exit status. SIGINT and SIGTERM are forwarded to the child command.
+
+The official CLI command names are also available as aliases. 
+
+```sh
+npx fireemu emulators:start
+npx fireemu emulators:exec -- npm test
 ```
 
-## Use
+### UI
+
+The default UI address is `http://127.0.0.1:4000`. Use `--ui-port` to specify a port.
 
 ```sh
-npx fireemu up --config fireemu.json
+# Start the UI on port 4001
+npx fireemu up --ui-port 4001
 ```
 
-`exec` is the `firebase emulators:exec` equivalent: it serves the same, runs a command with the
-emulator host variables once every listener is bound, stops everything when the command exits and
-exits with its status.
+`exec` does not start the UI by default. Add `--ui` to use it while the command runs.
 
 ```sh
-npx fireemu exec --firebase-json firebase.json --project my-app --only auth,firestore,storage -- vitest run
+npx fireemu exec --ui -- npm test
 ```
 
-The command receives `FIRESTORE_EMULATOR_HOST`, `FIREBASE_AUTH_EMULATOR_HOST`,
-`FIREBASE_STORAGE_EMULATOR_HOST` / `STORAGE_EMULATOR_HOST`, `GOOGLE_CLOUD_PROJECT` /
-`GCLOUD_PROJECT`, and `FIREEMU_CONTROL_TOKEN` / `FIREEMU_CONTROL_URL` for the control API.
+Use `--ui-port 0` to disable the UI. When automatic UI startup cannot bind the default port, the emulator starts without the UI. Check the startup output if the UI is unavailable.  
+
+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. 
 
-An Emulator UI is compiled into the binary and served at `http://127.0.0.1:4000/ui`
-(`--ui-port 0` turns it off).
+### Export data
 
-## Supported platforms
+To save data from a running emulator, run the following command in another terminal.
+
+```sh
+npx fireemu emulators:export ./emulator-data
+```
 
-| Package | OS | Arch | Built for |
-| --- | --- | --- | --- |
-| `@fireemu/darwin-arm64` | macOS 13+ | Apple silicon | `aarch64-apple-darwin` |
-| `@fireemu/darwin-x64` | macOS 13+ | Intel | `x86_64-apple-darwin` |
-| `@fireemu/linux-x64` | Linux (any libc) | x86-64 | `x86_64-unknown-linux-musl`, static |
-| `@fireemu/linux-arm64` | Linux (any libc) | arm64 | `aarch64-unknown-linux-musl`, static |
-| `@fireemu/win32-x64` | Windows 10+ | x86-64 | `x86_64-pc-windows-msvc` |
+On Windows, `emulators:export` and `--export-on-exit` are not currently available. Import and other emulator functionality remain available.
 
-The Linux builds are statically linked against musl, so they run on any distribution and inside
-distroless and Alpine containers.
+On Unix-like systems, the destination and its ancestor directories are subject to ownership and permission restrictions. Use a dedicated, non-shared directory rather than `/tmp` or a shared directory. 
 
-## Prerequisites
+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.
 
-- **Node 20 or newer** to run the launcher, and to run a Functions codebase. Nothing else needs
-  Node; Firestore, Auth, Storage and the UI are served by the binary itself.
-- **No Java.** Unlike the Firebase Emulator Suite, `fireemu` runs no JVM emulator.
-- For `--functions <dir>`: the codebase's own `node_modules`, with `firebase-functions` v6 or v7
-  and `firebase-admin`. `npx fireemu doctor` prints the range the bundled runner supports.
+### Troubleshooting
 
-## Check an installation
+For startup or installation problems, inspect the environment and bundled files with:
 
 ```sh
 npx fireemu doctor
 ```
 
-It reports the version and platform of the installed binary, whether the Emulator UI is compiled
-in, where the Node runner was found and which `firebase-functions` majors it instruments, the Node
-version, and that no JVM is required. Anything missing comes with a remediation line, and a broken
-installation exits non-zero so a setup script can gate on it. The report carries versions and paths
-only -- never tokens, keys, or the contents of a configuration file.
+The command reports information about the Fireemu binary, UI, Functions runner, and Node.js, and suggests remedies when it finds missing components or problems. 
+
+## Configuration
+
+### Initial setup and reusing `firebase.json`
+
+`fireemu init` creates `fireemu.json` in the current directory. The interactive setup lets you choose a compatibility profile and whether to reuse an existing `firebase.json`.
+
+When reusing `firebase.json`, Fireemu references the file rather than copying its settings. Rules, indexes, Functions codebases, and emulator ports are read from it each time Fireemu starts.
+
+Use the non-interactive form for CI or scripted setup.
+
+```sh
+npx fireemu init --yes
+```
+
+An existing `fireemu.json` is not overwritten unless `--force` is supplied.
+
+### Compatibility profiles
+
+| Profile | Behavior |
+|---|---|
+| `strict` | Matches production Firebase behavior and constraints as closely as possible within the supported scope. This is the default profile |
+| `emulator` | Targets the behavior of a pinned version of the official emulator. Known differences are documented in the compatibility documentation |
+
+Use `strict` when testing against production Firebase behavior. Add `emulator` to your test targets when you also need to check alignment with the official emulator.
+
+Under the `emulator` profile, a request that names a tenant the project does not have creates that tenant, and the number of tenants is not limited, as in the official emulator. The `strict` profile refuses such a request, as production does. A request that Fireemu refuses (a wrong credential, a browser page without the control token on the emulator routes, App Check, an unknown API key) creates nothing. As in the official emulator, a plain `GET` without an `Origin` header to a tenant route of `127.0.0.1` creates the tenant, so any web page you visit while the emulator runs can add tenants to it (not read them); use the `strict` profile where that matters.
+
+### Basic configuration
+
+The initial configuration selects Standard edition Firestore with the Native API.
+
+```json
+{
+  "$schema": "https://fireemu.dev/spec/config/fireemu.schema.json",
+  "schemaVersion": 1,
+  "profile": "strict",
+  "firestore": {
+    "edition": "standard",
+    "apiMode": "native"
+  }
+}
+```
+
+You can specify the configuration file with `--config`.
+
+```sh
+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.11.0/spec/config/fireemu.schema.json) for all available settings. 
+
+### Firebase Authentication (Identity Platform) configuration
+
+The `auth` section of `fireemu.json` lets you configure sign-in methods, password policies, account permissions, and other authentication settings. Match your application’s configuration to test registration, sign-in, and account management behavior.
+
+| What you can configure | Main settings |
+|---|---|
+| Enable or disable email/password, anonymous, and phone sign-in | `auth.signIn` |
+| Test phone numbers and verification codes | `auth.signIn.phoneNumber.testPhoneNumbers` |
+| Initial authorized domains for action-link continue URLs | `auth.authorizedDomains` |
+| Handling of accounts that share an email address | `auth.signIn.allowDuplicateEmails` |
+| Password length and character requirements, and policy enforcement at sign-in | `auth.passwordPolicy` |
+| TOTP-based multi-factor authentication | `auth.totp` |
+| Initial multi-factor authentication (MFA) configuration of a project, such as enabling TOTP under the `strict` profile | `auth.mfa` |
+| Tenants that exist when the daemon starts, and the multi-tenancy switch | `auth.tenants`, `auth.multiTenant` |
+| Restrictions on end-user account creation and deletion | `auth.client.permissions` |
+| Email enumeration protection | `auth.improvedEmailPrivacy` |
+| Project- and tenant-specific password policies and account permissions | `auth.passwordPolicyOverrides`, `auth.configOverrides` |
+| Blocking functions before account creation or sign-in, and credential forwarding to those functions | `auth.blockingFunctions` |
+| Initial custom OIDC and SAML provider resources | `auth.providers.oidc`, `auth.providers.saml` |
+| Public keys for verifying custom tokens and OIDC ID tokens | `auth.customTokenSigners`, `auth.idpSigners` |
+| Sign-up quota configuration and local quota-exceeded simulation | `auth.quota`, `auth.quotaSimulation` |
+
+See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.11.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.11.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.
+
+Declare project OIDC and SAML resources with `auth.providers.oidc` and `auth.providers.saml`, using the Admin v2 resource fields and an ID-only `name` such as `oidc.fixture` or `saml.fixture`. Full resource names are refused. For example, `"providers": {"oidc": [{"name": "oidc.fixture", "enabled": true, "clientId": "local-client", "issuer": "https://issuer.test", "responseType": {"idToken": true}}]}` initializes that provider in both profiles. Strict OIDC sign-in also needs matching public issuer keys in `auth.idpSigners`; no key is fetched. Strict SAML uses the declared provider certificates and retains its existing assertion checks.
+
+Each declared array replaces that provider kind; `[]` explicitly starts it empty, while an absent or `null` kind declares no initial resources. Admin operations change live resources until a session reset restores the declared kinds. Later session and routed projects inherit the declaration independently of the default project's live changes. Tenant resources and built-in providers remain separate. Clearing accounts preserves live resources; snapshots and Auth export/import transfer no provider resources or declarations. The emulator profile continues to accept its unsigned fixture credentials without requiring configured or enabled provider resources. These declarations require a canonical document with `"schemaVersion": 1`; a Firebase deployment `auth.providers` section without that version remains deployment data and installs no provider seeds.
+
+#### Example configuration
+
+This example enables email/password and phone sign-in while disabling anonymous sign-in. It requires passwords of at least 12 characters containing uppercase letters, lowercase letters, and numbers, and prevents users from deleting their own accounts. Phone sign-in uses a configured test phone number and verification code.
+
+```json
+{
+  "$schema": "https://fireemu.dev/spec/config/fireemu.schema.json",
+  "schemaVersion": 1,
+  "profile": "strict",
+  "firestore": {
+    "edition": "standard",
+    "apiMode": "native"
+  },
+  "auth": {
+    "signIn": {
+      "allowDuplicateEmails": false,
+      "email": {
+        "enabled": true,
+        "passwordRequired": true
+      },
+      "anonymous": {
+        "enabled": false
+      },
+      "phoneNumber": {
+        "enabled": true,
+        "testPhoneNumbers": {
+          "+16505550101": "123456"
+        }
+      }
+    },
+    "passwordPolicy": {
+      "enforcementState": "ENFORCE",
+      "forceUpgradeOnSignin": true,
+      "constraints": {
+        "minLength": 12,
+        "requireUppercase": true,
+        "requireLowercase": true,
+        "requireNumeric": true
+      }
+    },
+    "client": {
+      "permissions": {
+        "disabledUserSignup": false,
+        "disabledUserDeletion": true
+      }
+    },
+    "improvedEmailPrivacy": true
+  }
+}
+```
+
+For an existing `fireemu.json`, add the settings you need to its `auth` section. Adjust the values to match your application’s requirements.   
+
+#### Project- and tenant-specific settings
+
+Use `auth.passwordPolicyOverrides` to specify different password policies for individual projects or tenants. Use `auth.configOverrides` to customize account creation and deletion permissions and email enumeration protection.
+
+These settings are separate from creating the project or tenant. Naming a tenant in `auth.configOverrides` or `auth.passwordPolicyOverrides` does not create it (declare it in `auth.tenants` to have it created).  
+
+#### Enable multi-factor authentication at start
+
+Under the `strict` profile, TOTP is enabled only through the project's MFA configuration, as in production, so `auth.totp` alone enables nothing there. Use `auth.mfa` to declare that configuration in the file instead of calling the Admin API in every session. It has the shape Identity Platform uses (`state`, `enabledProviders`, and `providerConfigs` with `totpProviderConfig.adjacentIntervals`):
+
+```json
+{
+  "schemaVersion": 1,
+  "profile": "strict",
+  "auth": {
+    "mfa": {
+      "state": "ENABLED",
+      "providerConfigs": [
+        { "state": "ENABLED", "totpProviderConfig": { "adjacentIntervals": 1 } }
+      ]
+    }
+  }
+}
+```
+
+- The configuration applies when the daemon starts, in both profiles, and to every project created afterward (not the default project's current value). It is validated as the Admin API validates an update of `mfa`, and a value production would refuse stops the daemon at startup.
+- Nothing else changes. An Admin API update replaces the current configuration, and disabling MFA refuses TOTP as production does. A tenant follows its own `mfaConfig`, not this setting.
+- `POST /v1/sessions/{session}/reset` returns the project to the declared configuration. Without `auth.mfa`, a reset leaves a configuration set through the Admin API alone, as it does the rest of the project configuration. `DELETE /emulator/v1/projects/{project}/accounts` clears accounts only.
+- An export does not carry the project's `mfa` configuration, so an imported project keeps its own `auth.mfa` or Admin-set configuration.
+- The `emulator` profile keeps `auth.totp` working. Under `strict`, `auth.totp` without an `auth.mfa` that enables TOTP prints a startup warning naming `auth.mfa`.
+
+#### 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.11.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`:
+
+```json
+{
+  "schemaVersion": 1,
+  "profile": "strict",
+  "auth": {
+    "multiTenant": { "allowTenants": true },
+    "tenants": [
+      {
+        "tenantId": "acme-x7k2q",
+        "displayName": "acme",
+        "allowPasswordSignup": true,
+        "mfaConfig": { "state": "ENABLED", "enabledProviders": ["PHONE_SMS"] }
+      }
+    ]
+  }
+}
+```
+
+- A document is read by the code the Admin tenant create route reads one with, so a value production refuses stops the daemon at startup. The tenants are created empty, in file order, and settings such as `mfaConfig` and `passwordPolicyConfig` come from the document. The file is stricter than the route in the `emulator` profile: it also refuses an unknown member and a missing or invalid `displayName`, as production does.
+- A declared tenant has what an Admin create with that document gives: an omitted `allowPasswordSignup`, `enableEmailLinkSignin` or `enableAnonymousUser` is off and multi-factor is off. A tenant the `emulator` profile creates on the way for a request that names an unknown id gets the official emulator's defaults instead (all three on, `PHONE_SMS` multi-factor), so declare what your test needs.
+- Under the `strict` profile tenants are created only in a project that allows them, as in production, so `auth.tenants` needs `auth.multiTenant.allowTenants: true` (the daemon refuses to start otherwise). The `emulator` profile takes tenants without the switch.
+- The default project and every session project (`POST /v1/sessions`) start with the declared switch and tenants. `POST /v1/sessions/{session}/reset` (the default session's included) creates them again, empty, and returns the switch to the declared value; without these keys a reset leaves an Admin-set switch alone. A namespace the `emulator` profile creates for an unknown project id (as the official emulator does) starts with the declared switch and tenants too: it is created by the requests that already created one (a user, a provider or a project setting written there) and by a request that writes a tenant there (creating one, or naming one that does not exist yet), not by a read alone. A session created for that project id (`POST /v1/sessions`) replaces the namespace, tenants included, and starts with the declared ones.
+- With `--import`, an imported tenant is authoritative for its id, and a declared tenant the import did not carry is still created. If you keep re-importing your own export (`--import dir --export-on-exit dir`), an edit to a declared tenant is therefore ignored once its exported copy exists: the daemon prints a warning naming the tenant when the imported tenant's document differs from the declared one (every setting the file can declare is compared). The switch is the other way round: a declared `allowTenants` wins over the import. After a reset the declared version of a tenant comes back, not the imported one.
+
+#### Test quota-exceeded behavior
+
+Use `auth.quotaSimulation` to test sign-up quota-exceeded behavior locally. For example, set `auth.quotaSimulation` to:
+
+```json
+{
+  "mode": "enforce",
+  "defaultQuotaPerHour": 5
+}
+```
+
+This is a local fixed-window simulation. It does not reproduce Firebase’s full quota accounting or abuse-prevention systems.  
+
+### Configure execution time
+
+Set the emulator’s starting time with `daemon.clockStart`. Configure the clock, time zone, and other scheduling behavior in the `scheduler` section. This lets you test scheduled functions independently of the actual time. If the Functions event queue is full (4,096 active events or 64 MiB), a scheduled run that comes due stays due and runs once room frees, and a manual run answers `429 RESOURCE_EXHAUSTED` without being queued. The clock can also move backwards (`clock:set` with `"allowBackwards": true`, or **Allow moving backwards** on the Runtime page). In the `emulator` profile, ID tokens stay usable after a rewind, as with the official emulator, which does not check their issue time. In the `strict` profile, Authentication (`INVALID_ID_TOKEN`), Cloud Firestore and Cloud Storage refuse an ID token issued after the new time until the clock reaches its issue time again. In both profiles an expired token is still refused. A rewind to before an account was created, or before its tokens were revoked, makes even a new sign-in's token count as revoked; move the clock forward again or reset the session instead. Conversely, a revocation or password change made after a rewind does not revoke tokens issued at later times on the timeline: the `emulator` profile accepts them at once, and `strict` accepts them once the clock reaches their issue time. Move the clock forward past their issue time before revoking, or reset the session.
+
+A schedule is driven by the virtual clock alone: real time passing runs nothing. Each clock move (`clock:advance`, `clock:advanceTo`, `clock:set` or the Runtime page) makes every occurrence in `(previous time, new time]` due, so an occurrence exactly at the new time is included and one exactly at the previous time is not. `scheduler.catchUp` decides what runs: `all` runs each one (at most `scheduler.maxCatchUpRuns` per job and clock move, the rest stays due and runs as room frees), `latest` runs the newest and `none` runs none, and both record one `skipped: catch-up` summary per job and clock move that drops runs. A rewind never replays: occurrences the schedule already passed are not run again when the clock moves forward over them, and the schedule resumes once the clock passes the last occurrence it ran or still owes (its cursor). After a rewind below that point, runs still owed from a backlog or held for room stay owed but do not come due again until the clock passes it. A session reset or a snapshot restore starts every schedule from the clock's current time instead, so after a rewind the occurrences between that time and a later one are due again. `scheduler.overlap` (`allow`, `skip`, `queue`, `reject`) applies to scheduler runs and manual runs alike. A function counts as busy while any of its runs is queued or running, including a run that is waiting to be retried, so under `skip` and `reject` a retry still pending can suppress the next occurrence; fireemu does not distinguish a retry attempt from an overlapping run here. With `catchUp: all`, one clock move over several occurrences of the same function overlaps itself, so `skip` keeps the oldest of them and `reject` counts the rest as rejections.
+
+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.11.0/spec/config/fireemu.schema.json) for available settings and values. 
+
+### Firestore history limits
+
+Like production, Fireemu keeps every version of a document written in the last hour, so a `read_time` read, a read-only transaction or a resumed listener can see it. A test that updates the same documents many times therefore holds many versions in memory. These limits are local; production has none of them:
+
+- Each database retains at most 1 GiB of logical history bytes and 1,000,000 versions, each session 1 GiB and 1,000,000 versions, and the daemon 4 GiB and 4,000,000 versions. Logical bytes follow Firestore's storage size model and are not the process's memory, which can be several times larger.
+- On a pinned clock (`daemon.clockStart`), time does not pass on its own, so a database keeps at most 1,024 versions of any one document. This limit works like `maxVersionsPerPath` below: once a document goes past it, older snapshots are released for the whole database.
+- A commit that would cross a limit is refused whole with `RESOURCE_EXHAUSTED` and the message `Firestore retained history capacity is exhausted`.
+
+Versions older than an hour are released by the next commit after the clock passes them. To use less memory, lower the limits in the `firestore.history` section:
+
+```json
+{
+  "schemaVersion": 1,
+  "firestore": {
+    "edition": "standard",
+    "apiMode": "native",
+    "history": {
+      "maxVersionsPerPath": 16,
+      "maxBytes": 268435456
+    }
+  }
+}
+```
+
+- `maxVersionsPerPath` (1 to 1,000,000) sets the most versions of one document a database keeps, on either clock, in place of the defaults above.
+- `maxBytes` (1 MiB to 1 GiB) lowers the logical history bytes one database retains. An import (`--import`) is not checked against it: a larger import starts with a `warning:` line naming the database, its bytes and the limit (a snapshot restore above it logs the same line), and every later write that would grow the history is refused with `RESOURCE_EXHAUSTED`.
+
+Without these keys the defaults apply.
+
+The version cap applies to each document separately, but its effect reaches the whole database. Snapshots stay exact for every document, so once any document has more versions than the cap, the database keeps no snapshot older than that document's oldest kept version. After that:
+
+- A `read_time` read older than that point is refused with `FAILED_PRECONDITION` (`The requested 'read_time' is no longer retained by this database.`). So is a new read-only transaction at such a `read_time` (`read_time is no longer retained by this database`).
+- A transaction already open on an older snapshot fails its next read or commit with `ABORTED` (`The referenced transaction has expired or is no longer valid.`), even if it only touches other documents.
+- A listener resuming from an older point is reset and sent the full result again.
+
+Client SDKs retry `ABORTED` transactions. One frequently updated document under a small cap can therefore keep aborting unrelated transactions. Avoid very small caps: choose a cap above the number of times any document is updated while your longest transaction is open.
+
+To see how much history a running daemon holds, run `fireemu doctor --connect <control URL>`. Its `history.*` lines report the retained versions and logical bytes against the session and daemon limits, and how many bytes the next compaction would release.
+
+### Storage stored-byte limit
+
+The Storage emulator keeps every object in memory, and by default nothing bounds how much. To cap it, set `storage.maxStoredBytes` (bytes, at least 1). Production has no such limit; it is local to Fireemu:
+
+```json
+{
+  "schemaVersion": 1,
+  "storage": { "maxStoredBytes": 1073741824 }
+}
+```
+
+- Each object counts its bytes once, and a copy counts again. Replacing an object counts only the difference in size.
+- An upload, a resumable upload's final request or a copy that would grow the total past the limit is refused with HTTP 402 and the message `storage.maxStoredBytes limit exceeded` (in the JSON API, with the reason `storageCapacityExceeded`). There is no `Retry-After`. Delete objects to make room. The Firebase client SDKs report a 402 at once as `storage/quota-exceeded` without retrying; the Cloud Storage client libraries do not retry it either.
+- A write that does not grow the total, such as an equal or smaller replacement, always passes, even while the store holds more than the limit (after an import, a restore or a lowered limit).
+- A refused write changes nothing. A resumable upload stays open: its offset does not advance, so you can send the same final chunk again after making room, or cancel the upload.
+- An import (`--import`) and a snapshot restore are not checked against the limit. An import above it starts with a `warning:` line naming the stored bytes and the limit, and a snapshot restore above it logs the same line.
+
+`fireemu doctor --connect <control URL>` reports the stored bytes as `objects.bytes` against this limit.
+
+## Compatibility and limitations
+
+### Differences from production Firebase
+
+Fireemu aims to match production Firebase behavior, but a successful local operation does not guarantee the same result in production.
+
+The local runtime does not reproduce real quota accounting, billing, IAM, organization policies, regional or network differences, or service rollouts. Local performance measurements also do not predict production latency or throughput.
+
+Security Rules and API behavior are implemented using documentation and observations of Firebase’s actual behavior. Changes in Firebase or untested conditions may introduce differences that have not yet been recorded.
+
+### Comparison with the official emulator
+
+The official emulator comparison baseline is `firebase-tools 15.28.2`.
+
+Fireemu is compatible with the listed Local Emulator Suite products as shipped by firebase-tools 15.28.2 -- Cloud Firestore, Firebase Authentication, Cloud Storage for Firebase, Cloud Functions, Cloud Pub/Sub and Eventarc, with Security Rules on the Firestore and Storage surfaces -- under the `emulator` compatibility profile and the evidence recorded in `spec/compatibility/contract.json`; it makes no complete-suite and no unqualified superset claim while Realtime Database, Firebase Hosting, App Hosting and Data Connect are deferred and Firebase Extensions is not planned.
+
+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.11.0/spec/compatibility/contract.json) records scope and known differences. The [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.11.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.
+
+### Changes between versions
+
+Configuration and behavior may change between releases. See the [CHANGELOG](https://github.com/t-k/fireemu/blob/v0.11.0/CHANGELOG.md) for release changes.
+
+## Performance
+
+Fireemu is compared with the official Firestore emulator using the same SDK workloads. Both run sequentially on the same GitHub Actions Linux runner, with Fireemu using the `emulator` profile. The benchmark also validates operation results.
+
+The following results come from one `standard` run at commit `f3b942c`. Ratios are calculated from five measured pairs; absolute values depend on the execution environment.
+
+| Metric | Official emulator | Fireemu | Comparison |
+|---|---:|---:|---:|
+| Startup until the SDK can use Firestore | 3,043 ms | 140 ms | 21.6× faster |
+| Idle memory with an empty database (PSS) | 390 MiB | 11 MiB | About 1/34 the memory |
+| Peak memory during a trial (cgroup) | 849 MiB | 79 MiB | About 1/10.7 the memory |
+| Firestore throughput across 22 workloads | — | — | 1.1× to 5.2× higher |
+
+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.11.0/.github/workflows/benchmark.yml) for the workflow and [`tools/bench/`](https://github.com/t-k/fireemu/tree/v0.11.0/tools/bench/) for the benchmark implementation. 
 
-## Upgrade, uninstall, offline
+## Reporting issues and contributing
 
-- **Upgrade**: `npm install -D fireemu@<version>`. The launcher pins its platform packages to its
-  own exact version, so `fireemu@1.2.3` can only resolve `@fireemu/linux-x64@1.2.3` -- an upgrade
-  moves the binary and the launcher together, never one without the other.
-- **Uninstall**: `npm uninstall fireemu`. Nothing is installed outside `node_modules`: no cache
-  directory, no global binary, no downloaded component.
-- **Offline**: `npm install --offline` works once the tarballs are in the npm cache, and so does
-  installing from a private registry that mirrors the `fireemu` and `@fireemu` packages. Warm a
-  cache with `npm install` on a machine of the same platform, or vendor the tarballs with
-  `npm pack`.
-- **A vendored or self-built binary**: set `FIREEMU_BINARY_PATH` to it and the launcher runs that
-  instead of resolving a platform package.
-- **If the binary is missing**: the launcher says which package it looked for and what is
-  published. The usual cause is an install that skipped optional dependencies
-  (`--omit=optional`, `--no-optional`, or a lockfile built on another platform).
+When reporting an issue, include the Fireemu and Firebase SDK versions, the profile used, the Firebase product involved, and a minimal reproduction.
 
-## Documentation and source
+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.
 
-<https://github.com/t-k/fireemu>
+See the [development guide](https://github.com/t-k/fireemu/blob/v0.11.0/docs/development.md) for build and test instructions.
 
 ## License
 
-Apache-2.0
+Fireemu is licensed under the [Apache License 2.0](https://github.com/t-k/fireemu/blob/v0.11.0/LICENSE). Third-party notices are listed in [THIRD_PARTY_LICENSES.txt](https://github.com/t-k/fireemu/blob/v0.11.0/THIRD_PARTY_LICENSES.txt).

package/bin/fireemu.mjs

@@ -116,10 +116,11 @@ function main() {
   ensureExecutable(binary.path);
   // Keep terminal I/O and the foreground process group intact. PID-directed signals only
   // reach this launcher, so forward them and wait for the daemon's own shutdown to finish.
-  const child = spawn(binary.path, process.argv.slice(2), {
-    stdio: "inherit",
-    windowsHide: false,
-  });
+  //
+  // The handlers are registered before the daemon is spawned: a signal that reached the launcher
+  // between spawn() and process.on() would kill it with the default action and orphan the daemon.
+  // Node runs a handler on the event loop, after main() has returned, so `child` exists by then.
+  let child;
   for (const signal of ["SIGTERM", "SIGINT"]) {
     process.on(signal, () => {
       // Windows delivers console Ctrl-C to the child directly; child.kill would forcefully
@@ -129,6 +130,10 @@ function main() {
       if (child.exitCode === null && child.signalCode === null) child.kill(signal);
     });
   }
+  child = spawn(binary.path, process.argv.slice(2), {
+    stdio: "inherit",
+    windowsHide: false,
+  });
   child.on("error", (error) => {
     if (child.pid) {
       // A failed signal delivery must not orphan a daemon that is still running.

package/package.json

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