@dereekb/oauth-resource 14.4.0

package/firebase/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@dereekb/oauth-resource/firebase",
+  "version": "14.4.0",
+  "sideEffects": false,
+  "type": "module",
+  "peerDependencies": {
+    "@dereekb/date": "14.4.0",
+    "@dereekb/firebase": "14.4.0",
+    "@dereekb/model": "14.4.0",
+    "@dereekb/oauth-resource": "14.4.0",
+    "@dereekb/rxjs": "14.4.0",
+    "@dereekb/util": "14.4.0",
+    "firebase": "^12.18.0",
+    "make-error": "^1.3.6"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.esm.js",
+      "default": "./index.esm.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.esm.js",
+  "types": "./index.d.ts"
+}

package/firebase/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/firebase/src/lib/firestore/firestore.sdk-identity.d.ts

@@ -0,0 +1,165 @@
+import { type Maybe } from '@dereekb/util';
+/**
+ * The `drivers.firestoreDriverIdentifier` a client-SDK `FirestoreContext` reports.
+ *
+ * `clientFirebaseFirestoreContextFactory` stamps this; the server's
+ * `googleCloudFirestoreContextFactory` stamps `@google-cloud/firestore` instead. Comparing against
+ * it is how {@link inspectFirebaseClientFirestoreIdentity} tells an admin-SDK context that reached
+ * the client-SDK read path apart from a genuinely broken client one.
+ */
+export declare const CLIENT_FIRESTORE_DRIVER_IDENTIFIER = "@firebase/firestore";
+/**
+ * The distinct ways a session's Firestore handle can be unusable, in the order
+ * {@link inspectFirebaseClientFirestoreIdentity} tests them — most specific diagnosis first.
+ */
+export type FirebaseClientFirestoreIdentityProblem = 
+/**
+ * `firestoreContext` is absent, or its `firestore` is null/undefined. Every `collection()` call
+ * built off it throws `Expected first argument to collection() to be a CollectionReference, a
+ * DocumentReference or FirebaseFirestore` — the SDK's message for ANY non-Firestore first
+ * argument, which is why it never named this.
+ */
+'no-firestore-handle'
+/**
+ * The context reports a driver other than {@link CLIENT_FIRESTORE_DRIVER_IDENTIFIER} — an
+ * admin/`@google-cloud/firestore` context reached the client-SDK read path.
+ *
+ * This is the guard for the security property the whole user-scoped session path rests on: the
+ * client SDK is the only Firestore transport that carries a user ID token and is therefore
+ * rules-evaluated. An Admin-SDK context reaching here is a bug, not a fallback.
+ */
+ | 'unexpected-driver'
+/**
+ * Two copies of `@firebase/firestore` are loaded, so the handle minted by one fails the other's
+ * brand check.
+ */
+ | 'duplicated-firestore-sdk'
+/**
+ * The handle is present and the driver looks right, but it is not an instance of THIS copy of the
+ * SDK's `Firestore` class and no duplicate install explains it.
+ */
+ | 'foreign-firestore-instance';
+/**
+ * Where one consumer resolved `@firebase/firestore` to, and at which version.
+ *
+ * Reported for both the calling consumer and `@dereekb/firebase` because the whole point of the
+ * duplicated-SDK hypothesis is that those two answers can differ.
+ */
+export interface FirebaseClientFirestoreSdkModuleIdentity {
+    /**
+     * The resolved package directory, or `undefined` when resolution failed.
+     */
+    readonly packageDir?: Maybe<string>;
+    readonly version?: Maybe<string>;
+    /**
+     * Why resolution failed, when it did.
+     */
+    readonly error?: Maybe<string>;
+}
+/**
+ * The provenance + brand-check report {@link inspectFirebaseClientFirestoreIdentity} produces.
+ *
+ * Everything here is reported whether or not the check passed: a `sdkDuplicated: true` alongside
+ * `ok: true` is a latent hazard worth seeing before it becomes an outage.
+ */
+export interface FirebaseClientFirestoreIdentityReport {
+    readonly ok: boolean;
+    readonly problem?: FirebaseClientFirestoreIdentityProblem;
+    readonly firestorePresent: boolean;
+    /**
+     * Whether the handle passes `instanceof Firestore` against the copy of `@firebase/firestore` THIS
+     * package loaded.
+     */
+    readonly firestoreIsSdkInstance: boolean;
+    /**
+     * The handle's constructor name, which distinguishes a duplicate `Firestore` (same name, different
+     * class) from a genuinely foreign object.
+     */
+    readonly firestoreConstructor?: Maybe<string>;
+    readonly firestoreDriverIdentifier?: Maybe<string>;
+    /**
+     * The version of the `firebase` umbrella package resolved at runtime.
+     */
+    readonly firebaseVersion?: Maybe<string>;
+    /**
+     * Where the CONSUMER (this package, or whoever supplied a `consumerRequire`) resolves the SDK.
+     */
+    readonly sdkFromConsumer: FirebaseClientFirestoreSdkModuleIdentity;
+    readonly sdkFromDbxFirebase: FirebaseClientFirestoreSdkModuleIdentity;
+    /**
+     * True when the two resolutions above name DIFFERENT package directories.
+     */
+    readonly sdkDuplicated: boolean;
+}
+/**
+ * The slice of a session context {@link inspectFirebaseClientFirestoreIdentity} reads.
+ *
+ * Deliberately looser than `FirestoreContext`: this check exists precisely for the case where the
+ * object is not the shape its declared type claims, so narrowing it here would assume away the
+ * failure. A real `FirebaseUserSession['firestoreContext']` is structurally assignable.
+ */
+export interface FirebaseClientFirestoreIdentityContext {
+    readonly firestore?: unknown;
+    readonly drivers?: {
+        readonly firestoreDriverIdentifier?: unknown;
+    };
+}
+/**
+ * Input for {@link inspectFirebaseClientFirestoreIdentity}.
+ */
+export interface InspectFirebaseClientFirestoreIdentityInput {
+    readonly firestoreContext?: Maybe<FirebaseClientFirestoreIdentityContext>;
+    /**
+     * `createRequire(import.meta.url)` from the CONSUMER package. The duplicated-SDK hypothesis is
+     * exactly "do these two consumers see the same copy", so the resolution root must be the
+     * caller's. Defaults to this package's own.
+     */
+    readonly consumerRequire?: Maybe<NodeJS.Require>;
+    /**
+     * Names the consumer in the suggestion text. Defaults to `'@dereekb/oauth-resource/firebase'`.
+     */
+    readonly consumerName?: Maybe<string>;
+}
+/**
+ * Default {@link InspectFirebaseClientFirestoreIdentityInput.consumerName}.
+ */
+export declare const DEFAULT_FIRESTORE_IDENTITY_CONSUMER_NAME = "@dereekb/oauth-resource/firebase";
+/**
+ * Checks that a session's Firestore handle is one THIS copy of the client SDK will accept, and
+ * reports where every consumer resolved the SDK from.
+ *
+ * Exists because `collection()` refuses any non-`Firestore` first argument with one message —
+ * `Expected first argument to collection() to be a CollectionReference, a DocumentReference or
+ * FirebaseFirestore` — that names neither the model, nor the collection, nor which of the four
+ * distinct causes ({@link FirebaseClientFirestoreIdentityProblem}) produced it.
+ *
+ * Lives in this package rather than in a consumer because the `instanceof Firestore` brand check
+ * must be performed by the module that CONSTRUCTS the handle, and that module is
+ * `openFirebaseUserSession`.
+ *
+ * The `instanceof` test is the load-bearing one and it is deliberately NOT structural: an identity
+ * check across the package boundary is the only thing that can detect a duplicated
+ * `@firebase/firestore`, which is exactly what a structural check would hide.
+ *
+ * @param input - The session's `firestoreContext`, when one was built, plus the consumer's
+ *   resolution root.
+ * @returns The provenance + brand-check report.
+ */
+export declare function inspectFirebaseClientFirestoreIdentity(input: InspectFirebaseClientFirestoreIdentityInput): FirebaseClientFirestoreIdentityReport;
+/**
+ * The actionable next step for a failed {@link inspectFirebaseClientFirestoreIdentity}, keyed on
+ * which problem was found.
+ *
+ * Each branch names the fix rather than the symptom — a raw SDK sentence sends an operator looking at
+ * security rules and App Check, neither of which is ever the cause here.
+ *
+ * @param report - The report to describe.
+ * @param overrides - Per-problem replacement text, for a consumer whose operator-facing wording
+ *   names its own remediation (`re-run with --verbose`, `rebuild the CLI`, …).
+ * @param consumerName - Names the consumer in the duplicated-SDK text. Defaults to
+ *   {@link DEFAULT_FIRESTORE_IDENTITY_CONSUMER_NAME}.
+ * @returns The suggestion, or `undefined` when the report passed.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function firebaseClientFirestoreIdentitySuggestion(report: FirebaseClientFirestoreIdentityReport, overrides?: Maybe<Partial<Record<FirebaseClientFirestoreIdentityProblem, string>>>, consumerName?: Maybe<string>): Maybe<string>;

package/firebase/src/lib/firestore/index.d.ts

@@ -0,0 +1 @@
+export * from './firestore.sdk-identity';

package/firebase/src/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './firestore';
+export * from './session';

package/firebase/src/lib/session/firebase-client.config.d.ts

@@ -0,0 +1,86 @@
+import { type Maybe, type PortNumber } from '@dereekb/util';
+/**
+ * Local Firebase emulator targets for a Firebase client config.
+ *
+ * Mirrors the semantics of `DbxFirebaseEmulatorsConfig` in `@dereekb/dbx-firebase` (whose parse
+ * helper is Angular-bound and not reusable here): the presence of this object means "use emulators"
+ * unless {@link useEmulators} is explicitly `false`.
+ *
+ * App Check is auto-disabled whenever emulators are in use — the emulators do not verify
+ * attestations, and `initializeAppCheck` against a fake project only gets in the way.
+ */
+export interface FirebaseClientEmulatorsConfig {
+    /**
+     * Set `false` to keep the emulator targets configured but inactive. Defaults to `true`.
+     */
+    readonly useEmulators?: boolean;
+    /**
+     * Host the emulators are reachable at. Defaults to {@link DEFAULT_FIREBASE_CLIENT_EMULATOR_HOST}.
+     */
+    readonly host?: string;
+    /**
+     * Port of the Auth emulator. When unset, Auth is not redirected to an emulator.
+     */
+    readonly authPort?: PortNumber;
+    /**
+     * Port of the Firestore emulator. When unset, Firestore is not redirected to an emulator.
+     */
+    readonly firestorePort?: PortNumber;
+}
+/**
+ * Firebase client-SDK configuration used to open a user-scoped Firestore session.
+ *
+ * These are the same public values the app's browser client initializes with — copy them from the
+ * target app's environment file. `appId` in particular must be the registered **web** app, since the
+ * server mints its App Check attestation for that app.
+ */
+export interface FirebaseClientConfig {
+    /**
+     * The Firebase web API key.
+     */
+    readonly apiKey?: string;
+    /**
+     * The project's auth domain (e.g. `my-project.firebaseapp.com`).
+     */
+    readonly authDomain?: string;
+    /**
+     * The Firebase project id.
+     */
+    readonly projectId?: string;
+    /**
+     * The registered **web** app id (e.g. `1:1234567890:web:abcdef`).
+     */
+    readonly appId?: string;
+    /**
+     * Optional emulator targets for local development.
+     */
+    readonly emulators?: FirebaseClientEmulatorsConfig;
+}
+/**
+ * A {@link FirebaseClientConfig} carrying everything a session needs to initialize an app.
+ */
+export type CompleteFirebaseClientConfig = Required<Pick<FirebaseClientConfig, 'apiKey' | 'projectId' | 'appId'>> & FirebaseClientConfig;
+/**
+ * Default host used for Firebase emulator connections when a {@link FirebaseClientEmulatorsConfig}
+ * omits one.
+ */
+export declare const DEFAULT_FIREBASE_CLIENT_EMULATOR_HOST = "localhost";
+/**
+ * Returns true when the config carries the minimum Firebase client values needed to open a
+ * user-scoped Firestore session.
+ *
+ * Deliberately a standalone predicate rather than a field of a wider "config is complete" check: a
+ * host's Firebase config is optional, and folding it into a general completeness check would break
+ * every consumer that only talks to the HTTP API.
+ *
+ * @param firebase - The Firebase client config, if any.
+ * @returns `true` when `apiKey`, `projectId`, and `appId` are all present and non-empty.
+ */
+export declare function isFirebaseClientConfigComplete(firebase: Maybe<FirebaseClientConfig>): firebase is CompleteFirebaseClientConfig;
+/**
+ * Returns true when the config's emulator targets are present and active.
+ *
+ * @param firebase - The Firebase client config, if any.
+ * @returns `true` when emulators are configured and not explicitly disabled.
+ */
+export declare function firebaseClientEmulatorsInUse(firebase: Maybe<FirebaseClientConfig>): boolean;

package/firebase/src/lib/session/firebase-user-session.d.ts

@@ -0,0 +1,223 @@
+import { type FirebaseApp } from 'firebase/app';
+import { type Auth } from 'firebase/auth';
+import { type Firestore } from 'firebase/firestore';
+import { type FirebaseAuthUserId, type FirestoreContext } from '@dereekb/firebase';
+import { type Getter, type Maybe, type Milliseconds, type UnixDateTimeMillisecondsNumber, type WebsiteUrl } from '@dereekb/util';
+import { type FirebaseClientConfig } from './firebase-client.config';
+import { type FirestoreSessionCredentials, type FirestoreSessionErrorFactory } from './firestore-session.client';
+import { type FirestoreSessionCredentialsCache } from './firestore-session.cache';
+/**
+ * Separator between the segments of a {@link firebaseUserSessionAppName}.
+ *
+ * `::` rather than `-` because a Firebase project id is `[a-z0-9-]+`, so a single `-` makes
+ * `(ns='srv', scope='a-b', uid='c')` and `(ns='srv', scope='a', uid='b-c')` collide on `srv-a-b-c`.
+ * `:` cannot appear in a project id, so `::` is collision-free for any namespace that does not itself
+ * contain `::`.
+ */
+export declare const FIREBASE_USER_SESSION_KEY_SEPARATOR = "::";
+export interface FirebaseUserSessionKeyInput {
+    /**
+     * The teardown-sweep key — every app this owner registered shares it as a prefix.
+     *
+     * Required rather than defaulted: a silent default lets two independently-configured pools in one
+     * process sweep each other's apps.
+     */
+    readonly namespace: string;
+    /**
+     * Discriminates sessions that share a uid but not a target. Normally the Firebase project id.
+     */
+    readonly scope: string;
+    readonly uid: FirebaseAuthUserId;
+}
+/**
+ * The base Firebase app name a user-scoped session registers.
+ *
+ * A DERIVED name rather than a side registry is what lets {@link closeFirebaseUserSessionApps} find
+ * every app this owner opened from `getApps()` alone — no registry to keep in sync, and idempotent by
+ * construction.
+ *
+ * Note this is the BASE name: {@link openFirebaseUserSession} appends `#2`, `#3`, … when the base is
+ * already taken, because a session that mints its own credentials must never reuse an existing app
+ * registration (see the note on {@link openFirebaseUserSession}).
+ *
+ * @param input - The namespace, scope, and uid the session targets.
+ * @returns The base Firebase app name.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function firebaseUserSessionAppName(input: FirebaseUserSessionKeyInput): string;
+/**
+ * The `getApps()` name prefix every session opened under a namespace shares.
+ *
+ * @param namespace - The namespace to sweep.
+ * @returns The app-name prefix.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function firebaseUserSessionNamespacePrefix(namespace: string): string;
+/**
+ * A live user-scoped Firestore session: the Firebase client objects signed in as the user, plus the
+ * `FirestoreContext` an app's collections factory consumes.
+ *
+ * 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 holder runs the SAME
+ * queries the Angular app runs, through the SAME security rules.
+ *
+ * This is deliberately NOT an Admin-SDK "act as user" path: the client SDK is the only Firestore
+ * transport that carries a user ID token and is therefore rules-evaluated.
+ */
+export interface FirebaseUserSession {
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * The credential bundle the API minted for this session.
+     */
+    readonly credentials: FirestoreSessionCredentials;
+    /**
+     * True when {@link credentials} came from a supplied cache rather than a fresh mint. Diagnostic
+     * only — never control flow.
+     */
+    readonly fromCache: boolean;
+    readonly appName: string;
+    readonly app: FirebaseApp;
+    readonly auth: Auth;
+    readonly firestore: Firestore;
+    readonly firestoreContext: FirestoreContext;
+    readonly createdAt: UnixDateTimeMillisecondsNumber;
+    /**
+     * `min(credentials.expiresAt, createdAt + maxSessionAgeMs)`, falling back to the ceiling when the
+     * API returned an unparsable timestamp.
+     */
+    readonly expiresAt: UnixDateTimeMillisecondsNumber;
+}
+export interface OpenFirebaseUserSessionInput {
+    /**
+     * The teardown-sweep key. See {@link FirebaseUserSessionKeyInput.namespace}.
+     */
+    readonly namespace: string;
+    /**
+     * Discriminates sessions sharing a uid. Defaults to `firebase.projectId`.
+     */
+    readonly scope?: Maybe<string>;
+    readonly firebase: Maybe<FirebaseClientConfig>;
+    readonly apiBaseUrl: WebsiteUrl;
+    readonly accessToken: string;
+    /**
+     * When set, asserted against the minted credentials' uid.
+     *
+     * This makes the mint endpoint's central security property — "the custom token is always minted
+     * for `auth.uid`, with no way to name another user" — locally checkable at the CONSUME side, which
+     * matters far more for a server holding N users than for a one-user CLI.
+     */
+    readonly uid?: Maybe<FirebaseAuthUserId>;
+    readonly fetcher?: Maybe<typeof fetch>;
+    readonly errorFactory?: Maybe<FirestoreSessionErrorFactory>;
+    /**
+     * Optional credentials cache. When supplied, a live cached envelope for {@link cacheKey} is reused
+     * instead of re-minting one, and a freshly minted envelope is written back.
+     */
+    readonly credentialsCache?: Maybe<FirestoreSessionCredentialsCache>;
+    /**
+     * Key to read/write in {@link credentialsCache}. Defaults to the session's uid.
+     */
+    readonly cacheKey?: Maybe<string>;
+    /**
+     * Skips the cache read for this call and re-mints, still writing the result back. Used by
+     * diagnostics and by the retry after a sign-in failure.
+     */
+    readonly refreshCredentials?: boolean;
+    /**
+     * Hard ceiling on the session's usable age. Defaults to {@link FIRESTORE_SESSION_MAX_CACHE_MS}.
+     */
+    readonly maxSessionAgeMs?: Maybe<Milliseconds>;
+    /**
+     * Clock seam, for deterministic tests.
+     */
+    readonly now?: Maybe<Getter<UnixDateTimeMillisecondsNumber>>;
+}
+/**
+ * Opens a user-scoped Firestore session. The seam a pool (or a test) substitutes.
+ */
+export type FirebaseUserSessionOpener = (input: OpenFirebaseUserSessionInput) => Promise<FirebaseUserSession>;
+/**
+ * Opens a direct Firestore connection as the user the presented access token belongs to.
+ *
+ * Steps, in a strict order:
+ *
+ * 0. When a `credentialsCache` is supplied, reuse the cached credential envelope if it is still live.
+ *    Sessions are cached for up to an hour (see {@link 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-session, so the sign-in in step 5 always runs.
+ * 1. `GET <apiBaseUrl>/session/firestore` for a custom token + App Check attestation.
+ * 2. `initializeApp` under the first FREE name derived from {@link firebaseUserSessionAppName}.
+ *
+ *    **Never reuse an existing registration.** `initializeAppCheck` on an app whose App Check
+ *    provider is already initialized silently returns the EXISTING instance when
+ *    `CustomProvider.isEqual` matches — and `isEqual` compares `getToken.toString()`, the source text
+ *    of the arrow function, which is byte-identical across two closures built at this call site over
+ *    different tokens. Reusing an app therefore keeps the FIRST attestation and drops the freshly
+ *    minted one on the floor, so requests go out under a stale (eventually expired) App Check token.
+ *    App reuse is the POOL's responsibility, at the session-object level, never at the app-registry
+ *    level.
+ * 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
+ *    config 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.
+ *
+ * There is deliberately NO fallback to an Admin-SDK context — the whole point is that rules stay in
+ * force, so a failure here throws.
+ *
+ * @param input - The namespace, Firebase client config, API target, and access token.
+ * @returns The live {@link FirebaseUserSession}.
+ * @throws {FirestoreSessionError} (or the `errorFactory`'s type) When the config is incomplete, or any step of the handshake fails.
+ */
+export declare function openFirebaseUserSession(input: OpenFirebaseUserSessionInput): Promise<FirebaseUserSession>;
+/**
+ * Tears down a session opened by {@link openFirebaseUserSession}.
+ *
+ * Required, not optional hygiene. A signed-in `Auth` runs a token-refresh timer and a live
+ * `Firestore` holds open handles, so both leak per user without teardown — and in a CLI-shaped
+ * process they keep the Node event loop alive indefinitely, so the process never exits.
+ *
+ * `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 normally runs after the caller's result is already produced, so a
+ * failure here must not change the outcome.
+ *
+ * @param session - The session to close.
+ */
+export declare function closeFirebaseUserSession(session: Pick<FirebaseUserSession, 'app'>): Promise<void>;
+/**
+ * Deletes one Firebase app, swallowing any failure.
+ *
+ * @param app - The app to delete.
+ */
+export declare function closeFirebaseUserSessionApp(app: FirebaseApp): Promise<void>;
+/**
+ * Deletes every still-live Firebase app opened under a namespace, whether or not a session was
+ * handed back.
+ *
+ * The last line of defence against a leak. {@link closeFirebaseUserSession} 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 caller that opens its own session outside a pool owns its own teardown, and forgetting it
+ *   leaks;
+ * - an owner orphaned mid-invocation carries the only reference to its session.
+ *
+ * `getApps()` already tracks every live app and `deleteApp` removes it from that list, so the app
+ * names {@link firebaseUserSessionAppName} derives are enough to find them again — no side registry
+ * to keep in sync, and idempotent by construction.
+ *
+ * @param input - The function inputs.
+ * @param input.namespace - The namespace whose apps should be closed. Apps belonging to other
+ *   Firebase consumers in the same process are left alone.
+ * @returns Resolves once every matching app has been deleted.
+ */
+export declare function closeFirebaseUserSessionApps(input: {
+    readonly namespace: string;
+}): Promise<void>;