@dereekb/dbx-cli 14.3.0 → 14.4.0

package/src/lib/firestore/firestore.session.d.ts

@@ -1,7 +1,4 @@
-import { type FirebaseApp } from 'firebase/app';
-import { type Auth } from 'firebase/auth';
-import { type Firestore } from 'firebase/firestore';
-import { type FirestoreContext } from '@dereekb/firebase';
+import { type FirebaseUserSession } from '@dereekb/oauth-resource/firebase';
 import { type CliFirestoreSession } from '../api/firestore-session.client';
 import { type CliEnvConfig } from '../config/env';
 import { type CliFirestoreSessionCacheStore } from '../config/firestore-session.cache';
@@ -9,25 +6,23 @@ import { type CliFirestoreSessionCacheStore } from '../config/firestore-session.
  * A live direct-Firestore session: the Firebase client objects the CLI signed in with, plus the
  * `FirestoreContext` an app's collections factory consumes.
  *
+ * The CLI's view of {@link FirebaseUserSession}, whose implementation lives in
+ * `@dereekb/oauth-resource/firebase` so any resource server that verified a bearer token carrying the
+ * `session.firestore` scope gets the same bridge.
+ *
  * The `firestoreContext` is built by `clientFirebaseFirestoreContextFactory`, the exact analogue of
  * the server's `googleCloudFirestoreContextFactory` — both satisfy `FirestoreContextFactory` — so an
  * app's `make<App>FirestoreCollections(context)` accepts it unchanged, and the CLI runs the SAME
  * queries the Angular app runs, through the SAME security rules.
  */
-export interface CliFirestoreSessionContext {
+export interface CliFirestoreSessionContext extends FirebaseUserSession {
     /**
      * The credential bundle the API minted for this session.
+     *
+     * The CLI's long-standing name for {@link FirebaseUserSession.credentials}; both name the same
+     * object.
      */
     readonly session: CliFirestoreSession;
-    /**
-     * True when {@link session} came from the on-disk session cache rather than a fresh
-     * `GET /session/firestore`. Surfaced for `doctor` and `--verbose`, not for control flow.
-     */
-    readonly fromCache: boolean;
-    readonly app: FirebaseApp;
-    readonly auth: Auth;
-    readonly firestore: Firestore;
-    readonly firestoreContext: FirestoreContext;
 }
 export interface CreateCliFirestoreSessionContextInput {
     readonly cliName: string;
@@ -49,39 +44,15 @@ export interface CreateCliFirestoreSessionContextInput {
      */
     readonly refreshSession?: boolean;
 }
-/**
- * The Firebase app name a direct-Firestore session registers for a CLI + env pair.
- *
- * Deriving the name rather than tracking apps in a side registry is what makes ONE app per CLI + env
- * per process a property of the code instead of a convention: {@link createCliFirestoreSessionContext}
- * looks this name up in `getApps()` before initializing, so repeated session opens in one process —
- * a doctor probe alongside a command's own session, an action that re-resolves the accessor — all
- * share a single app, and {@link closeAllCliFirebaseApps} finds it again from the name alone.
- *
- * @param input - The CLI name and env name the session targets.
- * @returns The Firebase app name for that pair.
- * @__NO_SIDE_EFFECTS__
- */
-export declare function cliFirebaseAppName(input: Pick<CreateCliFirestoreSessionContextInput, 'cliName' | 'envName'>): string;
 /**
  * Opens a direct Firestore connection as the authenticated CLI user.
  *
- * Steps, in a strict order:
+ * A thin wrapper over `openFirebaseUserSession`: it validates the env's Firebase client config with
+ * the CLI's own env-var-naming remediation, then delegates. The strict step ORDER (mint → fresh app →
+ * App Check FIRST → emulator wiring → sign-in) and its reasoning live with the implementation.
  *
- * 0. When a `sessionCache` is supplied, reuse the env's cached credential envelope if it is still
- *    live. Sessions are cached for up to an hour (see `CLI_FIRESTORE_SESSION_MAX_CACHE_MS`), which is
- *    the ceiling the Firebase credentials themselves sit under. A hit skips step 1 only — the
- *    Firebase app is per-process, so the sign-in in step 5 always runs.
- * 1. `GET <apiBaseUrl>/session/firestore` for a custom token + App Check attestation.
- * 2. `initializeApp` with the env's Firebase client config.
- * 3. `initializeAppCheck` with a `CustomProvider` handing back the server-minted token. **This must
- *    happen before any other Firebase call** — `dbx-firebase`'s provider documents the same
- *    constraint: "App Check must be initialized before any Firebase request goes out, otherwise
- *    requests are sent without an App Check token and are rejected in production." Skipped when the
- *    env targets emulators (which do not verify attestations) or when the API minted no token.
- * 4. `getAuth` / `getFirestore`, connecting each to its emulator when configured.
- * 5. `signInWithCustomToken`. The user's stored custom claims land at the top level of the exchanged
- *    ID token, so `request.auth.token.<claim>` reads in security rules behave exactly as in the app.
+ * The session's Firebase app is named `<cliName>::<envName>::<uid>`, so
+ * {@link closeAllCliFirebaseApps} finds every app this CLI opened from the name alone.
  *
  * There is deliberately NO fallback to the HTTP model API — a failure here throws so the operator
  * sees it. `createFirestoreSessionDoctorCheck` is the diagnostic surface for why.
@@ -96,15 +67,7 @@ export declare function createCliFirestoreSessionContext(input: CreateCliFiresto
  *
  * Required for the CLI to EXIT. A signed-in `Auth` and a live `Firestore` both hold open handles
  * that keep the Node event loop alive indefinitely, so without this a command prints its result and
- * then hangs forever — the process never returns to the shell. Nothing in the CLI is long-lived
- * enough to want that: a session is opened for one invocation and is dead weight afterwards.
- *
- * `deleteApp` is the single call that covers it — it disposes every registered component, which for
- * Firestore runs the same shutdown `terminate()` does, and for Auth stops the token-refresh timer.
- *
- * Deliberately tolerant: teardown runs in a `finally` after the command has already produced its
- * output, so a failure here must not change the exit code or mask the real result. A session that
- * was never opened is a no-op.
+ * then hangs forever — the process never returns to the shell.
  *
  * @param session - The session context to close.
  */
@@ -112,23 +75,15 @@ export declare function closeCliFirestoreSessionContext(session: CliFirestoreSes
 /**
  * Deletes every still-live Firebase app this CLI opened, whether or not a session was handed back.
  *
- * The CLI's last line of defence against a hang. `closeCliFirestoreSessionContext` covers the normal
- * path, but it needs a session to be handed to it, and three cases never produce one:
+ * The CLI's last line of defence against a hang. {@link closeCliFirestoreSessionContext} covers the
+ * normal path, but it needs a session to be handed to it, and three cases never produce one:
  *
- * - a handshake that fails AFTER `initializeApp` — a rejected custom token, a failed App Check
- *   registration — throws, so the caller that catches it has an initialized app and no session;
+ * - a handshake that fails AFTER `initializeApp` — a failed App Check registration, a broken emulator
+ *   connection — throws, so the caller that catches it has an initialized app and no session;
  * - a caller that opens its own session outside the context memo (the doctor probe) owns its own
  *   teardown, and forgetting it hangs the process;
  * - a {@link CliContext} orphaned mid-invocation carries the only reference to its session memo.
  *
- * Each leaves an app whose `Firestore` and signed-in `Auth` hold the Node event loop open forever.
- * `getApps()` already tracks every live app and `deleteApp` removes it from that list, so the app
- * names {@link cliFirebaseAppName} derives are enough to find them again — no side registry to keep
- * in sync, and idempotent by construction.
- *
- * Tolerant of failures for the same reason {@link closeCliFirestoreSessionContext} is: it runs after
- * the result is already on stdout.
- *
  * @param input - The function inputs.
  * @param input.cliName - The CLI whose apps should be closed. Apps belonging to other Firebase
  *   consumers in the same process are left alone.

package/test/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@dereekb/dbx-cli/test",
-  "version": "14.3.0",
+  "version": "14.4.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.3.0",
-    "@dereekb/dbx-cli": "14.3.0",
-    "@dereekb/firebase": "14.3.0",
-    "@dereekb/firebase-server/test": "14.3.0",
-    "@dereekb/model": "14.3.0",
-    "@dereekb/nestjs": "14.3.0",
-    "@dereekb/rxjs": "14.3.0",
-    "@dereekb/util": "14.3.0",
+    "@dereekb/date": "14.4.0",
+    "@dereekb/dbx-cli": "14.4.0",
+    "@dereekb/firebase": "14.4.0",
+    "@dereekb/firebase-server/test": "14.4.0",
+    "@dereekb/model": "14.4.0",
+    "@dereekb/nestjs": "14.4.0",
+    "@dereekb/oauth-resource": "14.4.0",
+    "@dereekb/rxjs": "14.4.0",
+    "@dereekb/util": "14.4.0",
     "@nestjs/common": "^12.0.1",
     "arktype": "^2.2.0",
     "vitest": "4.1.11",

package/validate/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/dbx-cli/validate",
-  "version": "14.3.0",
+  "version": "14.4.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/dbx-cli": "14.3.0",
-    "@dereekb/util": "14.3.0",
+    "@dereekb/dbx-cli": "14.4.0",
+    "@dereekb/util": "14.4.0",
     "ts-morph": "^28.0.0"
   }
 }