pyric-admin 0.1.0-alpha.7

package/README.md

@@ -0,0 +1,49 @@
+# pyric-admin
+
+Firebase Admin-shaped adapters that can run against either a Pyric sandbox or
+real Firebase Admin SDK backends.
+
+Use `pyric-admin` when you want server/admin ergonomics while keeping the same
+backend-selection model as the client package.
+
+> **Alpha.** This package is an early alpha. The admin-shaped subpaths are
+> best-effort mirror contracts of `firebase-admin` — not guaranteed parity.
+> Any exported surface beyond the mirrored shapes is experimental public-alpha
+> and may change without notice.
+
+## Subpaths
+
+| Subpath | Surface |
+|---|---|
+| `pyric-admin/app` | Admin app initialization for sandbox or production |
+| `pyric-admin/firestore` | Admin Firestore shape over sandbox or `firebase-admin/firestore` |
+| `pyric-admin/auth` | Admin Auth shape over sandbox or `firebase-admin/auth` |
+| `pyric-admin/database` | Admin Realtime Database shape over sandbox or `firebase-admin/database` |
+| `pyric-admin/storage` | Admin Storage shape over sandbox or `firebase-admin/storage` |
+
+## Example
+
+```ts
+import { initializeApp } from 'pyric-admin/app';
+import { initializeSandbox } from 'pyric/sandbox';
+import { getFirestore } from 'pyric-admin/firestore';
+
+const app = initializeApp({ sandbox: initializeSandbox() });
+const db = getFirestore(app);
+
+await db.collection('posts').doc('hello').set({ title: 'Hello' });
+```
+
+Production apps pass normal Firebase Admin credentials:
+
+```ts
+import { initializeApp, cert } from 'pyric-admin/app';
+
+const app = initializeApp({
+  credential: cert(serviceAccount),
+});
+```
+
+## Docs
+
+- [Firestore docs](docs/firestore/)

package/dist/app/index.d.ts

@@ -0,0 +1,158 @@
+/**
+ * `pyric-admin/app` — Phase 3 initializeApp surface (ADR-001 D6) plus the
+ * default-app registry and AMBIENT INIT (adoption experience, layer 3).
+ *
+ * Mirror shape: at cutover this becomes `pyric-admin/app` and is the
+ * single entry point where the sandbox-vs-prod choice is made for the
+ * admin surface. Every `pyric-admin/*` subpath inspects the handle's
+ * brand for backend dispatch.
+ *
+ * Current shadow scope:
+ *   - `initializeApp({ credential, ... })` — prod-backed (live;
+ *     delegates to `firebase-admin/app.initializeApp`).
+ *   - `initializeApp({ sandbox })` — sandbox-backed (live).
+ *   - `initializeApp()` — BARE, zero pyric identifiers in app code. The
+ *     environment decides the backend (see "Ambient init" below).
+ *   - Per-subpath adapter dispatch via the brand: implemented in
+ *     `pyric-admin/{auth,database,storage}` via structural
+ *     checks on the `app` argument. Phase 4 commits use property
+ *     probing today; cutover swaps to brand-symbol reads.
+ *
+ * ── Default-app registry ──────────────────────────────────────────────
+ *
+ * Mirrors `firebase-admin/app`'s lifecycle exactly (oracle:
+ * `firebase-admin/lib/app/lifecycle.js`):
+ *
+ *   - `initializeApp(config?, name?)` registers under `'[DEFAULT]'` when
+ *     unnamed; `getApp(name?)` / `getApps()` / `deleteApp(app)` read it.
+ *   - Duplicate-name errors carry firebase-admin's codes and message
+ *     text: `app/duplicate-app` for a config'd re-init with a different
+ *     configuration, `app/invalid-app-options` for a bare-vs-config'd
+ *     mismatch (firebase-admin's autoInit mismatch), `app/no-app` from
+ *     `getApp` on a missing name, `app/invalid-app-name` for a
+ *     non-string/empty name. Errors reuse firebase-admin's own
+ *     `FirebaseAppError` class, so `instanceof`, `constructor.name`,
+ *     `.code`, and message text match production byte-for-byte
+ *     (oracle: `admin-app-*` observations).
+ *   - Idempotency mirror: a bare `initializeApp()` repeated for the same
+ *     name returns the existing auto-initialized app (firebase-admin's
+ *     autoInit path); `initializeApp({ sandbox })` repeated with the
+ *     SAME `Sandbox` reference returns the existing app (the reference
+ *     is our deep-equal analog — sandboxes have identity, not value
+ *     equality); prod re-inits delegate the equality decision to
+ *     firebase-admin itself (deep-equal options → same app; credential /
+ *     httpAgent present → `app/invalid-app-options`, exactly upstream).
+ *
+ * ── Ambient init (bare `initializeApp()`) ─────────────────────────────
+ *
+ * The user's server code contains ZERO pyric identifiers — bare
+ * `initializeApp()` + no-arg `getDatabase()` / `getAuth()`. The
+ * environment picks the backend:
+ *
+ *   - `PYRIC_SANDBOX` unset → exactly firebase-admin's behavior:
+ *     delegate to `firebase-admin/app.initializeApp()` (FIREBASE_CONFIG
+ *     env + application-default credentials), register the prod arm.
+ *   - `PYRIC_SANDBOX=remote` or `remote:<url>` → obtain a remote sandbox
+ *     handle from the factory installed by `pyric-tools/register` at
+ *     `globalThis[REMOTE_SANDBOX_FACTORY]`
+ *     (`Symbol.for('pyric.remote.sandboxFactory')`) and register the
+ *     sandbox arm. One activation line is logged to stderr. If the env
+ *     is set but no factory is installed, throw with remediation (run
+ *     under `pyric dev`, or add `--import pyric-tools/register` to
+ *     NODE_OPTIONS).
+ *   - Production guard: refuses to route to a sandbox when
+ *     `NODE_ENV === 'production'`, unless `PYRIC_SANDBOX_FORCE=1`.
+ *
+ * Ambient resolution happens ONLY on the bare call — any explicit
+ * config (`{ sandbox }` or prod `AppOptions`, even `{}`) bypasses the
+ * env entirely, so pyric-aware code keeps full control.
+ */
+import { type Sandbox } from 'pyric/sandbox';
+import { type App as AdminApp, type AppOptions } from 'firebase-admin/app';
+/**
+ * Brand on every PyricAdminApp. Matches the symbol used in
+ * `pyric/app` so a future shared `pyric/runtime` package can
+ * unify dispatch helpers across both packages.
+ */
+export declare const ADMIN_APP_TARGET: unique symbol;
+export type PyricAdminAppTarget = 'sandbox' | 'prod';
+/** firebase-admin's default app name — `'[DEFAULT]'`. */
+export declare const DEFAULT_APP_NAME = "[DEFAULT]";
+export interface SandboxAdminApp {
+    readonly [ADMIN_APP_TARGET]: 'sandbox';
+    readonly sandbox: Sandbox;
+    /** Registry name (mirrors firebase-admin `App.name`). */
+    readonly name: string;
+}
+export interface ProdAdminApp {
+    readonly [ADMIN_APP_TARGET]: 'prod';
+    readonly adminApp: AdminApp;
+    /** Registry name (mirrors firebase-admin `App.name`). */
+    readonly name: string;
+}
+export type PyricAdminApp = SandboxAdminApp | ProdAdminApp;
+export type InitializeAdminAppConfig = {
+    sandbox: Sandbox;
+} | AppOptions;
+/**
+ * App-lifecycle errors reuse `firebase-admin`'s own exported
+ * `FirebaseAppError` so the thrown error's class, `constructor.name`,
+ * `.code` (`app/no-app`, `app/duplicate-app`, `app/invalid-app-options`,
+ * `app/invalid-app-name`, `app/invalid-argument`), and message text match
+ * production byte-for-byte (oracle: `admin-app-*` observations assert
+ * `errorName: "FirebaseAppError"`). The published typings declare only the
+ * base `Error` constructor, but the real runtime class is
+ * `new FirebaseAppError(code, message)` where `code` becomes `app/<code>` —
+ * the typed cast recovers it.
+ */
+declare const AdminAppError: new (code: string, message: string) => Error & {
+    readonly code: string;
+};
+/** @deprecated Alias kept for pre-merge call sites; errors ARE `FirebaseAppError`. */
+export declare const PyricAdminAppError: new (code: string, message: string) => Error & {
+    readonly code: string;
+};
+export type PyricAdminAppError = InstanceType<typeof AdminAppError>;
+/**
+ * Initialize a Pyric admin app and register it under `name`
+ * (default `'[DEFAULT]'`), mirroring `firebase-admin/app.initializeApp`.
+ *
+ * @example
+ * ```ts
+ * // Ambient (zero pyric identifiers — environment decides)
+ * import { initializeApp } from 'pyric-admin/app';
+ * const app = initializeApp();
+ *
+ * // Prod-backed
+ * import { applicationDefault } from 'firebase-admin/app';
+ * const app = initializeApp({ credential: applicationDefault() });
+ *
+ * // Sandbox-backed
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * const app = initializeApp({ sandbox: initializeSandbox() });
+ * ```
+ */
+export declare function initializeApp(config?: InitializeAdminAppConfig, name?: string): PyricAdminApp;
+/**
+ * Return the registered app for `name` (default `'[DEFAULT]'`).
+ * Mirrors `firebase-admin/app.getApp` — including the exact `app/no-app`
+ * error text on a miss.
+ */
+export declare function getApp(name?: string): PyricAdminApp;
+/**
+ * A copy of the list of all registered apps.
+ * Mirrors `firebase-admin/app.getApps`.
+ */
+export declare function getApps(): PyricAdminApp[];
+/**
+ * Remove `app` from the registry, mirroring `firebase-admin/app.deleteApp`.
+ * Prod-backed apps also delete the underlying firebase-admin app (freeing
+ * its resources and its slot in firebase-admin's own registry, so the
+ * name can be re-initialized). Sandbox-backed apps only deregister — the
+ * `Sandbox` handle's lifetime belongs to its creator.
+ */
+export declare function deleteApp(app: PyricAdminApp): Promise<void>;
+export declare function isSandboxAdminApp(app: PyricAdminApp): app is SandboxAdminApp;
+export declare function isProdAdminApp(app: PyricAdminApp): app is ProdAdminApp;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/app/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAEH,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,GAAG,IAAI,QAAQ,EACpB,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,eAAuC,CAAC;AAErE,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,MAAM,CAAC;AAErD,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,YAAY,CAAC;AAE3D,MAAM,MAAM,wBAAwB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,UAAU,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,QAAA,MAAM,aAAa,EAAkC,KACnD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,KACZ,KAAK,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,sFAAsF;AACtF,eAAO,MAAM,kBAAkB,aALvB,MAAM,WACH,MAAM,KACZ,KAAK,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAGW,CAAC;AAChD,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,OAAO,aAAa,CAAC,CAAC;AA8BpE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,CAAC,EAAE,wBAAwB,EACjC,IAAI,GAAE,MAAyB,GAC9B,aAAa,CA8Df;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,GAAE,MAAyB,GAAG,aAAa,CAcrE;AAED;;;GAGG;AACH,wBAAgB,OAAO,IAAI,aAAa,EAAE,CAEzC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAW3D;AA0FD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,GAAG,IAAI,eAAe,CAE5E;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,GAAG,IAAI,YAAY,CAEtE"}

package/dist/app/index.js

@@ -0,0 +1,297 @@
+/**
+ * `pyric-admin/app` — Phase 3 initializeApp surface (ADR-001 D6) plus the
+ * default-app registry and AMBIENT INIT (adoption experience, layer 3).
+ *
+ * Mirror shape: at cutover this becomes `pyric-admin/app` and is the
+ * single entry point where the sandbox-vs-prod choice is made for the
+ * admin surface. Every `pyric-admin/*` subpath inspects the handle's
+ * brand for backend dispatch.
+ *
+ * Current shadow scope:
+ *   - `initializeApp({ credential, ... })` — prod-backed (live;
+ *     delegates to `firebase-admin/app.initializeApp`).
+ *   - `initializeApp({ sandbox })` — sandbox-backed (live).
+ *   - `initializeApp()` — BARE, zero pyric identifiers in app code. The
+ *     environment decides the backend (see "Ambient init" below).
+ *   - Per-subpath adapter dispatch via the brand: implemented in
+ *     `pyric-admin/{auth,database,storage}` via structural
+ *     checks on the `app` argument. Phase 4 commits use property
+ *     probing today; cutover swaps to brand-symbol reads.
+ *
+ * ── Default-app registry ──────────────────────────────────────────────
+ *
+ * Mirrors `firebase-admin/app`'s lifecycle exactly (oracle:
+ * `firebase-admin/lib/app/lifecycle.js`):
+ *
+ *   - `initializeApp(config?, name?)` registers under `'[DEFAULT]'` when
+ *     unnamed; `getApp(name?)` / `getApps()` / `deleteApp(app)` read it.
+ *   - Duplicate-name errors carry firebase-admin's codes and message
+ *     text: `app/duplicate-app` for a config'd re-init with a different
+ *     configuration, `app/invalid-app-options` for a bare-vs-config'd
+ *     mismatch (firebase-admin's autoInit mismatch), `app/no-app` from
+ *     `getApp` on a missing name, `app/invalid-app-name` for a
+ *     non-string/empty name. Errors reuse firebase-admin's own
+ *     `FirebaseAppError` class, so `instanceof`, `constructor.name`,
+ *     `.code`, and message text match production byte-for-byte
+ *     (oracle: `admin-app-*` observations).
+ *   - Idempotency mirror: a bare `initializeApp()` repeated for the same
+ *     name returns the existing auto-initialized app (firebase-admin's
+ *     autoInit path); `initializeApp({ sandbox })` repeated with the
+ *     SAME `Sandbox` reference returns the existing app (the reference
+ *     is our deep-equal analog — sandboxes have identity, not value
+ *     equality); prod re-inits delegate the equality decision to
+ *     firebase-admin itself (deep-equal options → same app; credential /
+ *     httpAgent present → `app/invalid-app-options`, exactly upstream).
+ *
+ * ── Ambient init (bare `initializeApp()`) ─────────────────────────────
+ *
+ * The user's server code contains ZERO pyric identifiers — bare
+ * `initializeApp()` + no-arg `getDatabase()` / `getAuth()`. The
+ * environment picks the backend:
+ *
+ *   - `PYRIC_SANDBOX` unset → exactly firebase-admin's behavior:
+ *     delegate to `firebase-admin/app.initializeApp()` (FIREBASE_CONFIG
+ *     env + application-default credentials), register the prod arm.
+ *   - `PYRIC_SANDBOX=remote` or `remote:<url>` → obtain a remote sandbox
+ *     handle from the factory installed by `pyric-tools/register` at
+ *     `globalThis[REMOTE_SANDBOX_FACTORY]`
+ *     (`Symbol.for('pyric.remote.sandboxFactory')`) and register the
+ *     sandbox arm. One activation line is logged to stderr. If the env
+ *     is set but no factory is installed, throw with remediation (run
+ *     under `pyric dev`, or add `--import pyric-tools/register` to
+ *     NODE_OPTIONS).
+ *   - Production guard: refuses to route to a sandbox when
+ *     `NODE_ENV === 'production'`, unless `PYRIC_SANDBOX_FORCE=1`.
+ *
+ * Ambient resolution happens ONLY on the bare call — any explicit
+ * config (`{ sandbox }` or prod `AppOptions`, even `{}`) bypasses the
+ * env entirely, so pyric-aware code keeps full control.
+ */
+import { REMOTE_SANDBOX_FACTORY, } from 'pyric/sandbox';
+import { initializeApp as initializeFirebaseAdminApp, deleteApp as deleteFirebaseAdminApp, FirebaseAppError, } from 'firebase-admin/app';
+/**
+ * Brand on every PyricAdminApp. Matches the symbol used in
+ * `pyric/app` so a future shared `pyric/runtime` package can
+ * unify dispatch helpers across both packages.
+ */
+export const ADMIN_APP_TARGET = Symbol.for('pyric.admin.app.target');
+/** firebase-admin's default app name — `'[DEFAULT]'`. */
+export const DEFAULT_APP_NAME = '[DEFAULT]';
+/**
+ * App-lifecycle errors reuse `firebase-admin`'s own exported
+ * `FirebaseAppError` so the thrown error's class, `constructor.name`,
+ * `.code` (`app/no-app`, `app/duplicate-app`, `app/invalid-app-options`,
+ * `app/invalid-app-name`, `app/invalid-argument`), and message text match
+ * production byte-for-byte (oracle: `admin-app-*` observations assert
+ * `errorName: "FirebaseAppError"`). The published typings declare only the
+ * base `Error` constructor, but the real runtime class is
+ * `new FirebaseAppError(code, message)` where `code` becomes `app/<code>` —
+ * the typed cast recovers it.
+ */
+const AdminAppError = FirebaseAppError;
+/** @deprecated Alias kept for pre-merge call sites; errors ARE `FirebaseAppError`. */
+export const PyricAdminAppError = AdminAppError;
+// ─── Registry ───────────────────────────────────────────────────────────
+//
+// Module-level, matching firebase-admin's `defaultAppStore` (one store per
+// module instance). `autoInitApps` tracks which registered apps came from a
+// BARE `initializeApp()` — firebase-admin's `autoInit` flag — so the
+// bare-vs-config'd mismatch throws exactly like upstream.
+const appRegistry = new Map();
+const autoInitApps = new WeakSet();
+/** firebase-admin's app-name validation, verbatim message. */
+function validateAppName(name) {
+    if (typeof name !== 'string' || name === '') {
+        throw new AdminAppError('invalid-app-name', `Invalid Firebase app name "${String(name)}" provided. App name must be a non-empty string.`);
+    }
+}
+/** firebase-admin's message for every same-name/different-config case. */
+function alreadyExists(name, code) {
+    return new AdminAppError(code, `A Firebase app named "${name}" already exists with a different configuration.`);
+}
+/**
+ * Initialize a Pyric admin app and register it under `name`
+ * (default `'[DEFAULT]'`), mirroring `firebase-admin/app.initializeApp`.
+ *
+ * @example
+ * ```ts
+ * // Ambient (zero pyric identifiers — environment decides)
+ * import { initializeApp } from 'pyric-admin/app';
+ * const app = initializeApp();
+ *
+ * // Prod-backed
+ * import { applicationDefault } from 'firebase-admin/app';
+ * const app = initializeApp({ credential: applicationDefault() });
+ *
+ * // Sandbox-backed
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * const app = initializeApp({ sandbox: initializeSandbox() });
+ * ```
+ */
+export function initializeApp(config, name = DEFAULT_APP_NAME) {
+    validateAppName(name);
+    const existing = appRegistry.get(name);
+    // ── Bare call: ambient resolution ────────────────────────────────────
+    if (config === undefined) {
+        if (existing !== undefined) {
+            // firebase-admin: two autoInit calls return the same app; an
+            // autoInit call against a config'd app is an options mismatch.
+            if (autoInitApps.has(existing))
+                return existing;
+            throw alreadyExists(name, 'invalid-app-options');
+        }
+        const app = initializeAmbientApp(name);
+        appRegistry.set(name, app);
+        autoInitApps.add(app);
+        return app;
+    }
+    // ── Explicit sandbox config ──────────────────────────────────────────
+    if (isSandboxConfig(config)) {
+        if (existing !== undefined) {
+            // Reference identity is the deep-equal analog for sandboxes.
+            if (!autoInitApps.has(existing) &&
+                existing[ADMIN_APP_TARGET] === 'sandbox' &&
+                existing.sandbox === config.sandbox) {
+                return existing;
+            }
+            throw alreadyExists(name, autoInitApps.has(existing) ? 'invalid-app-options' : 'duplicate-app');
+        }
+        const app = {
+            [ADMIN_APP_TARGET]: 'sandbox',
+            sandbox: config.sandbox,
+            name,
+        };
+        appRegistry.set(name, app);
+        return app;
+    }
+    // ── Explicit prod options ────────────────────────────────────────────
+    if (existing !== undefined) {
+        if (existing[ADMIN_APP_TARGET] === 'prod' && !autoInitApps.has(existing)) {
+            // Delegate the equality decision to firebase-admin itself: deep-
+            // equal options return the same AdminApp; credential / httpAgent
+            // re-inits throw app/invalid-app-options; different options throw
+            // app/duplicate-app — all with upstream's exact messages.
+            const adminApp = initializeFirebaseAdminApp(config, name);
+            if (adminApp === existing.adminApp)
+                return existing;
+        }
+        throw alreadyExists(name, autoInitApps.has(existing) ? 'invalid-app-options' : 'duplicate-app');
+    }
+    const adminApp = initializeFirebaseAdminApp(config, name);
+    const app = { [ADMIN_APP_TARGET]: 'prod', adminApp, name };
+    appRegistry.set(name, app);
+    return app;
+}
+/**
+ * Return the registered app for `name` (default `'[DEFAULT]'`).
+ * Mirrors `firebase-admin/app.getApp` — including the exact `app/no-app`
+ * error text on a miss.
+ */
+export function getApp(name = DEFAULT_APP_NAME) {
+    validateAppName(name);
+    const app = appRegistry.get(name);
+    if (app === undefined) {
+        const lead = name === DEFAULT_APP_NAME
+            ? 'The default Firebase app does not exist. '
+            : `Firebase app named "${name}" does not exist. `;
+        throw new AdminAppError('no-app', lead + 'Make sure you call initializeApp() before using any of the Firebase services.');
+    }
+    return app;
+}
+/**
+ * A copy of the list of all registered apps.
+ * Mirrors `firebase-admin/app.getApps`.
+ */
+export function getApps() {
+    return Array.from(appRegistry.values());
+}
+/**
+ * Remove `app` from the registry, mirroring `firebase-admin/app.deleteApp`.
+ * Prod-backed apps also delete the underlying firebase-admin app (freeing
+ * its resources and its slot in firebase-admin's own registry, so the
+ * name can be re-initialized). Sandbox-backed apps only deregister — the
+ * `Sandbox` handle's lifetime belongs to its creator.
+ */
+export function deleteApp(app) {
+    if (typeof app !== 'object' || app === null || !(ADMIN_APP_TARGET in app)) {
+        throw new AdminAppError('invalid-argument', 'Invalid app argument.');
+    }
+    // Make sure the given app is actually registered (throws app/no-app).
+    const existing = getApp(app.name);
+    appRegistry.delete(existing.name);
+    if (existing[ADMIN_APP_TARGET] === 'prod') {
+        return deleteFirebaseAdminApp(existing.adminApp);
+    }
+    return Promise.resolve();
+}
+// ─── Ambient init ───────────────────────────────────────────────────────
+/**
+ * Resolve a bare `initializeApp()` from the environment. See the
+ * module-level "Ambient init" docs for the full contract.
+ */
+function initializeAmbientApp(name) {
+    const env = process.env.PYRIC_SANDBOX;
+    if (env === undefined || env.trim() === '') {
+        // Unset → exactly today's prod behavior: firebase-admin's autoInit
+        // (FIREBASE_CONFIG env options + application-default credentials).
+        const adminApp = initializeFirebaseAdminApp(undefined, name);
+        return { [ADMIN_APP_TARGET]: 'prod', adminApp, name };
+    }
+    const opts = parsePyricSandboxEnv(env);
+    if (process.env.NODE_ENV === 'production' &&
+        process.env.PYRIC_SANDBOX_FORCE !== '1') {
+        throw new Error('pyric-admin: PYRIC_SANDBOX is set but NODE_ENV is "production" — ' +
+            'refusing to route firebase-admin to a development sandbox. ' +
+            'Unset PYRIC_SANDBOX in production, or set PYRIC_SANDBOX_FORCE=1 ' +
+            'if this routing is intentional.');
+    }
+    const factory = globalThis[REMOTE_SANDBOX_FACTORY];
+    if (typeof factory !== 'function') {
+        throw new Error(`pyric-admin: PYRIC_SANDBOX=${env} is set but no remote sandbox ` +
+            'factory is installed (globalThis[Symbol.for(' +
+            "'pyric.remote.sandboxFactory')] is absent). Run your server " +
+            'under `pyric dev`, or add `--import pyric-tools/register` to ' +
+            'NODE_OPTIONS.');
+    }
+    const sandbox = factory(opts);
+    process.stderr.write(`pyric: firebase-admin routed to sandbox${opts.url !== undefined ? ` at ${opts.url}` : ''}\n`);
+    return { [ADMIN_APP_TARGET]: 'sandbox', sandbox, name };
+}
+/**
+ * Parse the `PYRIC_SANDBOX` activator value.
+ *
+ *   - `remote`        → `{}` (factory discovers the running `pyric dev`)
+ *   - `remote:<url>`  → `{ url }` (everything after the FIRST colon —
+ *     URLs contain colons, so only the mode prefix is split off)
+ *
+ * Anything else throws: an unrecognized activator must never silently
+ * fall through to prod (mode-by-side-effect in the failure direction).
+ */
+function parsePyricSandboxEnv(env) {
+    const value = env.trim();
+    if (value === 'remote')
+        return {};
+    if (value.startsWith('remote:')) {
+        const url = value.slice('remote:'.length).trim();
+        if (url === '') {
+            throw new Error('pyric-admin: PYRIC_SANDBOX=remote: has an empty url. Use ' +
+                'PYRIC_SANDBOX=remote to auto-discover the running `pyric dev`, ' +
+                'or PYRIC_SANDBOX=remote:<url> with the host url.');
+        }
+        return { url };
+    }
+    throw new Error(`pyric-admin: unrecognized PYRIC_SANDBOX value "${env}". Supported ` +
+        'values: "remote" (auto-discover the running `pyric dev`) or ' +
+        '"remote:<url>".');
+}
+// ─── Guards ─────────────────────────────────────────────────────────────
+function isSandboxConfig(config) {
+    return typeof config === 'object' && config !== null && 'sandbox' in config;
+}
+export function isSandboxAdminApp(app) {
+    return app[ADMIN_APP_TARGET] === 'sandbox';
+}
+export function isProdAdminApp(app) {
+    return app[ADMIN_APP_TARGET] === 'prod';
+}
+//# sourceMappingURL=index.js.map

package/dist/app/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/app/index.ts"],"names":[],"mappings":"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"}

package/dist/auth/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * `pyric-admin/auth` — Phase 3 (branded-app dispatch) + Phase 4b
+ * (minimal in-memory sandbox backend).
+ *
+ * Mirrors `firebase-admin/auth` for a useful subset of methods. The
+ * `app` argument is the branded handle from `pyric-admin/app`
+ * ({@link PyricAdminApp}); the brand symbol picks the backend:
+ *
+ *   - **Prod path** (`app[ADMIN_APP_TARGET] === 'prod'`) — delegates to
+ *     `firebase-admin/auth`'s `getAuth(app.adminApp)` and returns the
+ *     production `Auth` instance unchanged. Drop-in replacement for
+ *     `firebase-admin/auth` so agents already calling it keep their
+ *     exact behavior (tenants, providers, MFA, session cookies, action
+ *     codes, all present on the returned handle).
+ *
+ *   - **Sandbox path** (`app[ADMIN_APP_TARGET] === 'sandbox'`) — backed
+ *     by an in-memory store keyed off `app.sandbox`. Implements the
+ *     core user-management subset listed below. Tokens are NOT real
+ *     JWTs — they're deterministic strings the same sandbox backend
+ *     parses on `verifyIdToken`. The sandbox backend is intentionally
+ *     minimal: enough to exercise agent code paths that use
+ *     `createUser` / `getUser` / `setCustomUserClaims` /
+ *     `createCustomToken` / `verifyIdToken`, not enough to model a
+ *     real identity platform.
+ *
+ *   - **Remote sandbox arm** — when the sandbox carries `pyric/sandbox`'s
+ *     remote brand (a Node-side handle onto the browser-hosted
+ *     SharedWorker sandbox from `pyric-tools`' `connectRemoteSandbox()`),
+ *     user CRUD relays over the handle's worker channel instead of the
+ *     in-memory store, so server-created users land in the ONE user pool
+ *     the browser app + Studio share. See the "Remote sandbox arm"
+ *     section below for the details (including the extra methods it
+ *     supports: `updateUser`, `listUsers`).
+ *
+ * Surface scope on the sandbox backend (what works):
+ *
+ *   - {@link getAuth}
+ *   - `Auth.createCustomToken(uid, claims?)` — returns a deterministic
+ *     `pyric-sandbox-custom:${uid}:${json}` string; no signing.
+ *   - `Auth.verifyIdToken(token)` — parses tokens minted by
+ *     `createCustomToken`; returns a {@link DecodedIdToken}-shaped
+ *     object.
+ *   - `Auth.createUser(properties)` — stores a {@link UserRecord}
+ *     in an in-memory `Map<uid, UserRecord>`. Auto-generates a `uid`
+ *     when one is not supplied.
+ *   - `Auth.getUser(uid)` — Map lookup.
+ *   - `Auth.getUserByEmail(email)` — linear scan.
+ *   - `Auth.deleteUser(uid)` — Map delete.
+ *   - `Auth.setCustomUserClaims(uid, claims)` — updates the stored
+ *     `UserRecord.customClaims`.
+ *
+ * Sandbox backend — explicitly NOT implemented (throws
+ * `'not implemented in pyric-admin/auth sandbox backend'` so callers
+ * get a clear remediation message):
+ *
+ *   - Tenancy: `tenantManager` and any per-tenant call.
+ *   - Identity providers: `createProviderConfig`, `getProviderConfig`,
+ *     `listProviderConfigs`, `updateProviderConfig`,
+ *     `deleteProviderConfig`.
+ *   - Multi-factor: `MultiFactorSettings` on UserRecord is always
+ *     `undefined`; MFA enrollment is unsupported.
+ *   - Session cookies: `createSessionCookie`, `verifySessionCookie`.
+ *   - Action codes / password reset / email link sign-in:
+ *     `generatePasswordResetLink`, `generateEmailVerificationLink`,
+ *     `generateSignInWithEmailLink`, `generateVerifyAndChangeEmailLink`.
+ *   - Bulk operations: `listUsers`, `getUsers`, `deleteUsers`,
+ *     `importUsers`.
+ *   - Revocation: `revokeRefreshTokens`.
+ *   - `getUserByPhoneNumber`, `getUserByProviderUid`.
+ *   - `updateUser` — not required by the brief.
+ *
+ * Real `firebase-admin` types are imported with `import type` so
+ * signatures stay identical to upstream — there's no shape drift to
+ * keep in sync.
+ */
+import type { Auth as AdminAuth, CreateRequest, DecodedIdToken, UserRecord } from 'firebase-admin/auth';
+import { type PyricAdminApp } from '../app/index.js';
+/**
+ * The handle returned by {@link getAuth}. On the prod path this is
+ * literally `firebase-admin/auth`'s `Auth` — every method, every
+ * tenant/project manager, every shape detail. On the sandbox path it is
+ * a structurally-compatible `Auth` whose method set is the explicit
+ * subset documented above; non-implemented methods throw a clear
+ * remediation error rather than silently returning bad data.
+ */
+export type Auth = AdminAuth;
+export type { CreateRequest, DecodedIdToken, UserRecord };
+/**
+ * Token format minted by `createCustomToken` and parsed by
+ * `verifyIdToken`. Exported as a constant so tests can lock the shape.
+ *
+ * Layout: `pyric-sandbox-custom:${uid}:${jsonClaims}`
+ *
+ * - The prefix lets `verifyIdToken` reject foreign tokens with a clear
+ *   "not a sandbox token" error rather than NaN'ing out.
+ * - `uid` is colon-free per the auto-uid format above.
+ * - `jsonClaims` is the JSON-stringified developer claims (or `{}` when
+ *   none were provided). Round-trips losslessly through `JSON.parse`.
+ *
+ * NOT a JWT. NOT signed. Do not use this token format to talk to any
+ * real Firebase service — it only round-trips through this same
+ * sandbox backend.
+ */
+export declare const SANDBOX_TOKEN_PREFIX = "pyric-sandbox-custom";
+/**
+ * Return an `Auth` handle for the given app — or for the DEFAULT app when
+ * called with no argument (mirrors firebase-admin's no-arg `getAuth()`:
+ * resolves `'[DEFAULT]'` through `pyric-admin/app`'s registry and throws
+ * `app/no-app` when nothing has been initialized). Works on all three
+ * arms — local sandbox, remote sandbox, prod — since dispatch happens on
+ * whatever brand the resolved app carries.
+ *
+ * Dispatches on the brand symbol set by `pyric-admin/app`'s
+ * `initializeApp`:
+ *   - `'prod'` → delegates to `firebase-admin/auth`'s `getAuth` against
+ *     `app.adminApp`. The returned `Auth` is the production object,
+ *     unmodified.
+ *   - `'sandbox'` → returns an in-memory `Auth` handle backed by an
+ *     {@link AuthStore} keyed off `app.sandbox`. Repeat calls for the
+ *     same sandbox share the store, so writes are visible across
+ *     handles (matches upstream `getAuth(app)` idempotency).
+ *
+ * The firebase-admin import is dynamic (`require` at call time) so the
+ * module's top-level evaluation stays cheap and so sandbox-only
+ * consumers do not pay the firebase-admin initialization cost. Mirrors
+ * how `pyric/firestore` defers its firebase init: backends are
+ * pay-for-what-you-use.
+ *
+ * @example
+ * ```ts
+ * import { initializeApp } from 'pyric-admin/app';
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * import { getAuth } from 'pyric-admin/auth';
+ *
+ * const sandbox = initializeSandbox();
+ * const app = initializeApp({ sandbox });
+ * const auth = getAuth(app);
+ *
+ * const user = await auth.createUser({ uid: 'alice', email: 'a@e.com' });
+ * const token = await auth.createCustomToken(user.uid, { role: 'admin' });
+ * const decoded = await auth.verifyIdToken(token);
+ * console.log(decoded.uid, decoded.role); // 'alice' 'admin'
+ * ```
+ */
+export declare function getAuth(app?: PyricAdminApp): Auth;
+//# sourceMappingURL=index.d.ts.map