pyric-admin 0.1.0-alpha.10 → 0.1.0-alpha.12

package/README.md.orig

@@ -21,6 +21,7 @@ loads `firebase-admin` directly.
 | `pyric-admin/auth` | Admin Auth shape |
 | `pyric-admin/database` | Admin Realtime Database shape |
 | `pyric-admin/storage` | Admin Storage shape |
+| `pyric-admin/messaging` | Admin Cloud Messaging send plane |
 
 ## Explicit sandbox setup
 
@@ -46,3 +47,4 @@ without sandbox activation and therefore resolves Firebase Admin directly.
 - [Auth API](https://pyric.dev/docs/pyric-admin-auth-reference-api/)
 - [Realtime Database API](https://pyric.dev/docs/pyric-admin-database-reference-api/)
 - [Storage API](https://pyric.dev/docs/pyric-admin-storage-reference-api/)
+- [Messaging API](https://pyric.dev/docs/pyric-admin-messaging-reference-api/)

package/dist/firestore/index.d.ts

@@ -14,6 +14,24 @@
  * default-app resolution and throw the captured `app/no-app` error when
  * nothing is initialized. The original `getFirestore(ctx)` context form
  * (the load-bearing shape the existing suite uses) is preserved verbatim.
+ *
+ * RULES-BYPASS PARITY (#394): the two APP-resolution forms — `getFirestore(app)`
+ * and no-arg `getFirestore()` — mirror `firebase-admin/firestore`'s
+ * `getFirestore(app?)`, and REAL firebase-admin bypasses security rules. So both
+ * app forms resolve to the rules-BYPASS admin lens (`getAdminFirestore` →
+ * `{ mode: 'admin' }`), exactly as `pyric-admin/database`'s `getDatabase(app)`
+ * and `pyric-admin/storage`'s `getStorage(app)` already do. Previously the app
+ * forms routed through the anon-lens `getFirestore(sandbox.withAuth(null))`,
+ * which evaluates `request.auth == null` and is DENIED by any real ruleset — a
+ * deny-direction divergence from production that blocked the RTDB-trigger →
+ * Firestore-stamp pattern (a Cloud Function's admin write).
+ *
+ * The `getFirestore(ctx)` CONTEXT form is UNCHANGED and stays rules-ENFORCED
+ * (its captured identity is load-bearing for the rules-simulation suite). No
+ * page ever reaches this module: a page's `firebase/firestore` resolves to
+ * `pyric/firestore` (the rules-enforced client), not `pyric-admin`; only the
+ * `firebase-admin/*` → `pyric-admin/*` swap in the trusted functions child
+ * imports this. See {@link getFirestore}.
  */
 export * from 'pyric/sandbox/admin-firestore';
 import { type SandboxFirestore } from 'pyric/sandbox/admin-firestore';
@@ -22,11 +40,19 @@ import { type PyricAdminApp } from '../app/index.js';
 /**
  * Return the admin Firestore handle.
  *
- *   - `getFirestore(ctx)` — the original context form (rules-applied for the
+ *   - `getFirestore(ctx)` — the original context form (rules-APPLIED for the
  *     ctx's captured identity). Unchanged; idempotent per `SandboxContext`.
- *   - `getFirestore(app)` — resolves a {@link PyricAdminApp}'s sandbox.
- *   - `getFirestore()` — resolves the default app; throws `app/no-app` when
- *     nothing is initialized.
+ *     This is the pyric-internal rules-simulation shape, not a firebase-admin
+ *     shape, so it keeps rule evaluation.
+ *   - `getFirestore(app)` — resolves a {@link PyricAdminApp}'s sandbox to the
+ *     rules-BYPASS admin lens (firebase-admin parity, #394).
+ *   - `getFirestore()` — resolves the default app to the rules-BYPASS admin
+ *     lens; throws `app/no-app` when nothing is initialized.
+ *
+ * The app forms mirror `firebase-admin/firestore`'s `getFirestore(app?)`,
+ * which bypasses security rules — so a Cloud Function's admin write lands the
+ * same way it does in production, instead of being denied as `request.auth ==
+ * null` by the sandbox's anon lens (the #394 deny-direction divergence).
  */
 export declare function getFirestore(target?: SandboxContext | PyricAdminApp): SandboxFirestore;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/firestore/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,cAAc,+BAA+B,CAAC;AAE9C,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAoBzB;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,MAAM,CAAC,EAAE,cAAc,GAAG,aAAa,GACtC,gBAAgB,CAUlB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/firestore/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,cAAc,+BAA+B,CAAC;AAE9C,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAsBzB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,CAAC,EAAE,cAAc,GAAG,aAAa,GACtC,gBAAgB,CAUlB"}

package/dist/firestore/index.js

@@ -14,18 +14,38 @@
  * default-app resolution and throw the captured `app/no-app` error when
  * nothing is initialized. The original `getFirestore(ctx)` context form
  * (the load-bearing shape the existing suite uses) is preserved verbatim.
+ *
+ * RULES-BYPASS PARITY (#394): the two APP-resolution forms — `getFirestore(app)`
+ * and no-arg `getFirestore()` — mirror `firebase-admin/firestore`'s
+ * `getFirestore(app?)`, and REAL firebase-admin bypasses security rules. So both
+ * app forms resolve to the rules-BYPASS admin lens (`getAdminFirestore` →
+ * `{ mode: 'admin' }`), exactly as `pyric-admin/database`'s `getDatabase(app)`
+ * and `pyric-admin/storage`'s `getStorage(app)` already do. Previously the app
+ * forms routed through the anon-lens `getFirestore(sandbox.withAuth(null))`,
+ * which evaluates `request.auth == null` and is DENIED by any real ruleset — a
+ * deny-direction divergence from production that blocked the RTDB-trigger →
+ * Firestore-stamp pattern (a Cloud Function's admin write).
+ *
+ * The `getFirestore(ctx)` CONTEXT form is UNCHANGED and stays rules-ENFORCED
+ * (its captured identity is load-bearing for the rules-simulation suite). No
+ * page ever reaches this module: a page's `firebase/firestore` resolves to
+ * `pyric/firestore` (the rules-enforced client), not `pyric-admin`; only the
+ * `firebase-admin/*` → `pyric-admin/*` swap in the trusted functions child
+ * imports this. See {@link getFirestore}.
  */
 export * from 'pyric/sandbox/admin-firestore';
-import { getFirestore as baseGetFirestore, } from 'pyric/sandbox/admin-firestore';
+import { getFirestore as baseGetFirestore, getAdminFirestore as baseGetAdminFirestore, } from 'pyric/sandbox/admin-firestore';
 import { ADMIN_APP_TARGET, getApp, isSandboxAdminApp, } from '../app/index.js';
 import { assertAdminAppActive } from '../app/lifecycle.js';
-/** Narrow a `PyricAdminApp` to the anonymous {@link SandboxContext} the
- *  admin firestore backend runs against. Sandbox apps expose their
- *  `Sandbox` — LOCAL and REMOTE alike: the base `getFirestore` is
- *  remote-aware (it dispatches a remote-branded sandbox to the
- *  channel-backed arm), so no guard is needed here. Prod apps require
- *  firebase-admin's real Firestore, which the in-process backend does
- *  not model. */
+/** Narrow a `PyricAdminApp` to the {@link SandboxContext} the admin
+ *  firestore backend runs against. Sandbox apps expose their `Sandbox` —
+ *  LOCAL and REMOTE alike: the base resolvers are remote-aware (they
+ *  dispatch a remote-branded sandbox to the channel-backed arm), so no
+ *  guard is needed here. The context's captured auth is IRRELEVANT on the
+ *  admin path (rules are bypassed, so no rule reads `request.auth`); it is
+ *  normalised to `withAuth(null)` only to obtain a context. Prod apps
+ *  require firebase-admin's real Firestore, which the in-process backend
+ *  does not model. */
 function adminAppToContext(app) {
     if (isSandboxAdminApp(app)) {
         return app.sandbox.withAuth(null);
@@ -36,20 +56,28 @@ function adminAppToContext(app) {
 /**
  * Return the admin Firestore handle.
  *
- *   - `getFirestore(ctx)` — the original context form (rules-applied for the
+ *   - `getFirestore(ctx)` — the original context form (rules-APPLIED for the
  *     ctx's captured identity). Unchanged; idempotent per `SandboxContext`.
- *   - `getFirestore(app)` — resolves a {@link PyricAdminApp}'s sandbox.
- *   - `getFirestore()` — resolves the default app; throws `app/no-app` when
- *     nothing is initialized.
+ *     This is the pyric-internal rules-simulation shape, not a firebase-admin
+ *     shape, so it keeps rule evaluation.
+ *   - `getFirestore(app)` — resolves a {@link PyricAdminApp}'s sandbox to the
+ *     rules-BYPASS admin lens (firebase-admin parity, #394).
+ *   - `getFirestore()` — resolves the default app to the rules-BYPASS admin
+ *     lens; throws `app/no-app` when nothing is initialized.
+ *
+ * The app forms mirror `firebase-admin/firestore`'s `getFirestore(app?)`,
+ * which bypasses security rules — so a Cloud Function's admin write lands the
+ * same way it does in production, instead of being denied as `request.auth ==
+ * null` by the sandbox's anon lens (the #394 deny-direction divergence).
  */
 export function getFirestore(target) {
     if (target === undefined) {
-        return baseGetFirestore(adminAppToContext(getApp()));
+        return baseGetAdminFirestore(adminAppToContext(getApp()));
     }
     if (typeof target === 'object' && target !== null && ADMIN_APP_TARGET in target) {
         const app = target;
         assertAdminAppActive(app);
-        return baseGetFirestore(adminAppToContext(app));
+        return baseGetAdminFirestore(adminAppToContext(app));
     }
     return baseGetFirestore(target);
 }

package/dist/firestore/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/firestore/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,cAAc,+BAA+B,CAAC;AAE9C,OAAO,EACL,YAAY,IAAI,gBAAgB,GAEjC,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,gBAAgB,EAChB,MAAM,EACN,iBAAiB,GAElB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;;;;iBAMiB;AACjB,SAAS,iBAAiB,CAAC,GAAkB;IAC3C,IAAI,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IACD,MAAM,IAAI,KAAK,CACb,wEAAwE;QACtE,sEAAsE,CACzE,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAuC;IAEvC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,gBAAgB,CAAC,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,gBAAgB,IAAI,MAAM,EAAE,CAAC;QAChF,MAAM,GAAG,GAAG,MAAuB,CAAC;QACpC,oBAAoB,CAAC,GAAG,CAAC,CAAC;QAC1B,OAAO,gBAAgB,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,gBAAgB,CAAC,MAAwB,CAAC,CAAC;AACpD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/firestore/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,cAAc,+BAA+B,CAAC;AAE9C,OAAO,EACL,YAAY,IAAI,gBAAgB,EAChC,iBAAiB,IAAI,qBAAqB,GAE3C,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,gBAAgB,EAChB,MAAM,EACN,iBAAiB,GAElB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;;;;;;sBAQsB;AACtB,SAAS,iBAAiB,CAAC,GAAkB;IAC3C,IAAI,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IACD,MAAM,IAAI,KAAK,CACb,wEAAwE;QACtE,sEAAsE,CACzE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAuC;IAEvC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,qBAAqB,CAAC,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,gBAAgB,IAAI,MAAM,EAAE,CAAC;QAChF,MAAM,GAAG,GAAG,MAAuB,CAAC;QACpC,oBAAoB,CAAC,GAAG,CAAC,CAAC;QAC1B,OAAO,qBAAqB,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,gBAAgB,CAAC,MAAwB,CAAC,CAAC;AACpD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyric-admin",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.12",
   "license": "Apache-2.0",
   "homepage": "https://pyric.dev",
   "repository": {
@@ -33,10 +33,15 @@
     "./storage": {
       "types": "./dist/storage/index.d.ts",
       "import": "./dist/storage/index.js"
+    },
+    "./messaging": {
+      "types": "./dist/messaging/index.d.ts",
+      "import": "./dist/messaging/index.js"
     }
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],
@@ -46,7 +51,7 @@
     "typecheck": "bun x tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "pyric": "^0.1.0-alpha.10"
+    "pyric": "^0.1.0-alpha.12"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/app/index.ts

@@ -0,0 +1,235 @@
+/**
+ * `pyric-admin/app` — sandbox-only admin app registry.
+ *
+ * Production selection happens before this module loads: activated Node
+ * processes resolve `firebase-admin/app` here, while inactive applications
+ * continue resolving their own `firebase-admin/app` package unchanged.
+ */
+import {
+  REMOTE_SANDBOX_FACTORY,
+  type RemoteSandboxFactory,
+  type RemoteSandboxFactoryOptions,
+  type Sandbox,
+} from 'pyric/sandbox';
+import { assertAdminAppActive, markAdminAppDeleted } from './lifecycle.js';
+
+/** Brand carried by every sandbox admin app. */
+export const ADMIN_APP_TARGET = Symbol.for('pyric.admin.app.target');
+export type PyricAdminAppTarget = 'sandbox';
+
+/** firebase-admin's default app name. */
+export const DEFAULT_APP_NAME = '[DEFAULT]';
+
+export interface SandboxAdminApp {
+  readonly [ADMIN_APP_TARGET]: 'sandbox';
+  readonly sandbox: Sandbox;
+  readonly name: string;
+}
+
+export type PyricAdminApp = SandboxAdminApp;
+export type InitializeAdminAppConfig = { sandbox: Sandbox };
+
+/**
+ * Firebase Functions' ESM runtime statically imports this credential factory
+ * while linking its database provider. Pyric initializes the sandbox app
+ * before that provider executes, so the factory is not used by supported
+ * Functions flows. Keep the named export link-compatible, but fail clearly if
+ * application code asks the development sandbox for production credentials.
+ */
+export function applicationDefault(): never {
+  throw new Error(
+    'pyric-admin/app: applicationDefault() is unavailable in the sandbox. ' +
+      'Pyric development does not use production credentials.',
+  );
+}
+
+/** Local error with the observable firebase-admin app-error shape. */
+class FirebaseAppError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'FirebaseAppError';
+    this.code = `app/${code}`;
+  }
+}
+
+// Node may evaluate this ESM-only mirror through distinct require(esm) and
+// import module records when the register hook rewrites both CJS and ESM
+// Firebase consumers. Firebase Admin's app registry is process-wide, so keep
+// the mirror registry behind Symbol.for as well: both module records must see
+// the same default app and sandbox handle.
+const APP_REGISTRY = Symbol.for('pyric.admin.app.registry');
+const AMBIENT_APPS = Symbol.for('pyric.admin.app.ambientApps');
+interface GlobalAppRegistry {
+  [APP_REGISTRY]?: Map<string, PyricAdminApp>;
+  [AMBIENT_APPS]?: WeakSet<PyricAdminApp>;
+}
+const globalRegistry = globalThis as GlobalAppRegistry;
+const appRegistry = globalRegistry[APP_REGISTRY] ??= new Map<string, PyricAdminApp>();
+const ambientApps = globalRegistry[AMBIENT_APPS] ??= new WeakSet<PyricAdminApp>();
+
+function validateAppName(name: unknown): asserts name is string {
+  if (typeof name !== 'string' || name === '') {
+    throw new FirebaseAppError(
+      'invalid-app-name',
+      `Invalid Firebase app name "${String(name)}" provided. App name must be a non-empty string.`,
+    );
+  }
+}
+
+function alreadyExists(name: string, code: 'duplicate-app' | 'invalid-app-options'): FirebaseAppError {
+  return new FirebaseAppError(
+    code,
+    `A Firebase app named "${name}" already exists with a different configuration.`,
+  );
+}
+
+/**
+ * Initialize a sandbox admin app.
+ *
+ * An explicit `{ sandbox }` config binds an in-process or remote sandbox.
+ * A bare call resolves the remote sandbox factory installed by
+ * `@pyric/cli/register`. Production callers must import `firebase-admin/app`
+ * without Pyric activation instead of passing production options here.
+ */
+export function initializeApp(
+  config?: InitializeAdminAppConfig,
+  name: string = DEFAULT_APP_NAME,
+): PyricAdminApp {
+  validateAppName(name);
+  const existing = appRegistry.get(name);
+
+  if (config === undefined) {
+    if (existing !== undefined) {
+      if (ambientApps.has(existing)) return existing;
+      throw alreadyExists(name, 'invalid-app-options');
+    }
+    const app = initializeAmbientApp(name);
+    appRegistry.set(name, app);
+    ambientApps.add(app);
+    return app;
+  }
+
+  if (!isSandboxConfig(config)) {
+    throw new TypeError(
+      'pyric-admin/app is a sandbox-only mirror. Production applications must ' +
+        'load firebase-admin/app without Pyric activation.',
+    );
+  }
+
+  if (existing !== undefined) {
+    if (!ambientApps.has(existing) && existing.sandbox === config.sandbox) return existing;
+    throw alreadyExists(
+      name,
+      ambientApps.has(existing) ? 'invalid-app-options' : 'duplicate-app',
+    );
+  }
+
+  const app: SandboxAdminApp = {
+    [ADMIN_APP_TARGET]: 'sandbox',
+    sandbox: config.sandbox,
+    name,
+  };
+  appRegistry.set(name, app);
+  return app;
+}
+
+/** Return the registered app for `name`. */
+export function getApp(name: string = DEFAULT_APP_NAME): PyricAdminApp {
+  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 FirebaseAppError(
+      'no-app',
+      lead + 'Make sure you call initializeApp() before using any of the Firebase services.',
+    );
+  }
+  return app;
+}
+
+/** Return a copy of the app registry. */
+export function getApps(): PyricAdminApp[] {
+  return Array.from(appRegistry.values());
+}
+
+/** Remove a sandbox app from the registry. */
+export function deleteApp(app: PyricAdminApp): Promise<void> {
+  if (typeof app !== 'object' || app === null || !(ADMIN_APP_TARGET in app)) {
+    throw new FirebaseAppError('invalid-argument', 'Invalid app argument.');
+  }
+  assertAdminAppActive(app);
+  const existing = getApp(app.name);
+  appRegistry.delete(existing.name);
+  markAdminAppDeleted(existing);
+  return Promise.resolve();
+}
+
+function initializeAmbientApp(name: string): PyricAdminApp {
+  const env = process.env.PYRIC_SANDBOX;
+  if (env === undefined || env.trim() === '') {
+    throw new Error(
+      'pyric-admin/app is a sandbox-only mirror and no sandbox is active. ' +
+        'Run under `pyric dev`, set PYRIC_SANDBOX with @pyric/cli/register, ' +
+        'or load firebase-admin/app without Pyric activation for production.',
+    );
+  }
+
+  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 as { [REMOTE_SANDBOX_FACTORY]?: RemoteSandboxFactory })[
+    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/cli/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 };
+}
+
+function parsePyricSandboxEnv(env: string): RemoteSandboxFactoryOptions {
+  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>".',
+  );
+}
+
+function isSandboxConfig(config: InitializeAdminAppConfig): config is { sandbox: Sandbox } {
+  return typeof config === 'object' && config !== null && 'sandbox' in config;
+}
+
+export function isSandboxAdminApp(app: PyricAdminApp): app is SandboxAdminApp {
+  return app[ADMIN_APP_TARGET] === 'sandbox';
+}

package/src/app/lifecycle.ts

@@ -0,0 +1,17 @@
+const deletedApps = new WeakSet<object>();
+
+/** Internal lifecycle guard shared by every pyric-admin service factory. */
+export function assertAdminAppActive(app: object & { readonly name: string }): void {
+  if (!deletedApps.has(app)) return;
+  const error = new Error(
+    `Firebase app named "${app.name}" has already been deleted.`,
+  ) as Error & { code: string };
+  error.name = 'FirebaseAppError';
+  error.code = 'app/app-deleted';
+  throw error;
+}
+
+/** Tombstone a wrapper while leaving the caller-owned Sandbox alive. */
+export function markAdminAppDeleted(app: object): void {
+  deletedApps.add(app);
+}