@dereekb/oauth-resource 14.4.0

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

@@ -0,0 +1,168 @@
+import { type FirebaseAuthUserId } 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 FirestoreSessionErrorFactory } from './firestore-session.client';
+import { type FirestoreSessionCredentialsCache } from './firestore-session.cache';
+import { type FirebaseUserSession, type FirebaseUserSessionOpener } from './firebase-user-session';
+/**
+ * Default {@link FirebaseUserSessionPoolConfig.maxSessions}.
+ *
+ * Bounds *concurrently distinct users*, not total users. Each entry is a full Firebase app: one
+ * `Firestore` with its network stack and one `Auth` with a refresh timer. 32 is deliberate — high
+ * enough that a normal request mix never evicts, low enough that an unbounded-uid caller cannot
+ * exhaust the process.
+ */
+export declare const DEFAULT_FIREBASE_USER_SESSION_POOL_SIZE = 32;
+export interface FirebaseUserSessionPoolConfig {
+    /**
+     * The teardown-sweep key shared by every app this pool registers. Required — a silent default lets
+     * two pools in one process collide.
+     */
+    readonly namespace: string;
+    readonly firebase: FirebaseClientConfig;
+    readonly apiBaseUrl: WebsiteUrl;
+    /**
+     * Discriminates sessions that share a uid but not a target. Defaults to `firebase.projectId`.
+     */
+    readonly scope?: Maybe<string>;
+    /**
+     * Target number of concurrently-held sessions. Defaults to
+     * {@link DEFAULT_FIREBASE_USER_SESSION_POOL_SIZE}.
+     */
+    readonly maxSessions?: Maybe<number>;
+    /**
+     * Hard ceiling on a session's usable age. Defaults to {@link FIRESTORE_SESSION_MAX_CACHE_MS}.
+     */
+    readonly maxSessionAgeMs?: Maybe<Milliseconds>;
+    /**
+     * How far ahead of a session's expiry it stops being handed out. Defaults to
+     * {@link FIRESTORE_SESSION_EXPIRY_BUFFER_MS}.
+     */
+    readonly refreshSkewMs?: Maybe<Milliseconds>;
+    readonly fetcher?: Maybe<typeof fetch>;
+    readonly errorFactory?: Maybe<FirestoreSessionErrorFactory>;
+    /**
+     * Optional credentials cache shared across opens.
+     *
+     * SECURITY: a {@link FirestoreSessionCredentials} is a bearer credential for its user. The pool's
+     * own state is in-memory and dies with the process; supply a cache only if you can protect it at
+     * least as well as a 0600 file store.
+     */
+    readonly credentialsCache?: Maybe<FirestoreSessionCredentialsCache>;
+    /**
+     * Test seam. Defaults to {@link openFirebaseUserSession}.
+     */
+    readonly openSession?: Maybe<FirebaseUserSessionOpener>;
+    /**
+     * Clock seam, so TTL/LRU behavior is deterministic in specs.
+     */
+    readonly now?: Maybe<Getter<UnixDateTimeMillisecondsNumber>>;
+    readonly onEvent?: Maybe<FirebaseUserSessionPoolEventHandler>;
+}
+/**
+ * What happened to a pooled session.
+ *
+ * `evicted` / `expired` / `over-capacity` are DECISIONS; `closed` is the app actually going away,
+ * which for an entry marked over-capacity happens later, on its last `release()`.
+ */
+export type FirebaseUserSessionPoolEventType = 'opened' | 'reused' | 'expired' | 'evicted' | 'over-capacity' | 'closed' | 'teardown-failed';
+export interface FirebaseUserSessionPoolEvent {
+    readonly type: FirebaseUserSessionPoolEventType;
+    readonly uid: FirebaseAuthUserId;
+    readonly appName: string;
+    /**
+     * The pool's entry count after the event.
+     */
+    readonly size: number;
+    readonly error?: unknown;
+}
+export type FirebaseUserSessionPoolEventHandler = (event: FirebaseUserSessionPoolEvent) => void;
+export interface AcquireFirebaseUserSessionInput {
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * The verified bearer access token belonging to {@link uid}.
+     */
+    readonly accessToken: string;
+    /**
+     * Skips any credentials-cache read for this acquisition.
+     */
+    readonly refreshCredentials?: boolean;
+}
+/**
+ * A borrowed session. The pool will not tear its app down while the lease is held.
+ */
+export interface FirebaseUserSessionLease {
+    readonly session: FirebaseUserSession;
+    /**
+     * Returns the session to the pool. Idempotent.
+     */
+    release(): void;
+}
+export interface FirebaseUserSessionPoolStats {
+    /**
+     * Number of pooled entries.
+     */
+    readonly size: number;
+    /**
+     * Number of OUTSTANDING leases across all entries — not the number of leased entries.
+     */
+    readonly leased: number;
+    readonly maxSessions: number;
+}
+export interface FirebaseUserSessionPool {
+    /**
+     * Borrows a session for the uid, opening one if needed.
+     *
+     * @param input - The uid and its access token.
+     * @returns The lease. The caller MUST `release()` it.
+     */
+    openSession(input: AcquireFirebaseUserSessionInput): Promise<FirebaseUserSessionLease>;
+    /**
+     * Borrows a session for the duration of `fn` and releases it afterwards, however `fn` settles.
+     *
+     * The request boundary IS the lifetime, so this is what a resource server calls.
+     *
+     * @param input - The uid and its access token.
+     * @param fn - The work to run with the session.
+     * @returns Whatever `fn` resolves to.
+     */
+    useSession<T>(input: AcquireFirebaseUserSessionInput, fn: (session: FirebaseUserSession) => Promise<T>): Promise<T>;
+    /**
+     * Detaches and tears down the uid's session — immediately when idle, on its last `release()`
+     * otherwise.
+     *
+     * @param uid - The user whose session should be closed.
+     */
+    closeSession(uid: FirebaseAuthUserId): Promise<void>;
+    /**
+     * Tears down every session and latches the pool closed. A later `openSession` throws `unavailable`.
+     */
+    close(): Promise<void>;
+    stats(): FirebaseUserSessionPoolStats;
+}
+/**
+ * Creates a per-`(scope, uid)` Firebase session pool with an explicit cap and TTL/LRU eviction.
+ *
+ * Exists because {@link openFirebaseUserSession} alone does not generalize past one user per process:
+ * a signed-in `Auth` runs a token-refresh timer and a live `Firestore` holds handles, so a server
+ * holding N concurrent user sessions leaks both per user without an owner. The pool is that owner.
+ *
+ * ### Why the TTL is driven by App Check, not Auth
+ *
+ * A signed-in `Auth` refreshes its ID token indefinitely — a Firebase refresh token does not expire
+ * on an hourly clock. The App Check token does not refresh: it is minted once by the API and
+ * `isTokenAutoRefreshEnabled` is `false`, because there is no local attestation to refresh against.
+ * So the session's real ceiling is the envelope's `expiresAt` (documented by the endpoint as "the
+ * earliest expiry among its credentials"), floored by {@link FirebaseUserSessionPoolConfig.maxSessionAgeMs}.
+ * Tearing the whole app down on expiry and re-minting costs one round trip; keeping it alive costs a
+ * silently unattested connection.
+ *
+ * ### Why a lease rather than a bare getter
+ *
+ * Reference counting is what makes eviction safe. Evicting an entry someone is mid-query on turns a
+ * capacity event into a user-visible failure, so the pool never tears down a leased session.
+ *
+ * @param config - The pool configuration.
+ * @returns The pool.
+ */
+export declare function firebaseUserSessionPool(config: FirebaseUserSessionPoolConfig): FirebaseUserSessionPool;

package/firebase/src/lib/session/firestore-session.cache.d.ts

@@ -0,0 +1,79 @@
+import { type AsyncKeyedValueCache, type Maybe, type Milliseconds, type UnixDateTimeMillisecondsNumber } from '@dereekb/util';
+import { type FirebaseAuthUserId } from '@dereekb/firebase';
+import { type FirestoreSessionCredentials } from './firestore-session.client';
+/**
+ * Hard ceiling on how long a minted user-scoped Firestore session may be reused, regardless of what
+ * the API reported in `expiresAt`.
+ *
+ * One hour, because that is the Firebase ceiling the credentials themselves sit under: a custom
+ * token is exchangeable for one hour, and the ID token it mints lives one hour. Holding a session
+ * past that buys nothing — the sign-in would fail — and re-minting is one HTTP round-trip.
+ */
+export declare const FIRESTORE_SESSION_MAX_CACHE_MS: Milliseconds;
+/**
+ * Default skew/latency buffer applied when deciding whether a cached session is still usable.
+ */
+export declare const FIRESTORE_SESSION_EXPIRY_BUFFER_MS: Milliseconds;
+/**
+ * A cached user-scoped Firestore session.
+ *
+ * Stores the credential envelope the API minted, not the live Firebase objects — those are
+ * per-process and cannot be serialized. A cache hit still signs in; it just skips the
+ * `GET /session/firestore` round-trip.
+ *
+ * SECURITY: every entry holds a Firebase custom token, which is a bearer credential for the user it
+ * was minted for. A persistent store MUST protect them at least as well as a 0600 file — this
+ * package deliberately ships no persistent implementation, only the {@link FirestoreSessionCredentialsCache}
+ * port and the expiry policy; `firebaseUserSessionPool`'s own state is in-memory and dies with the
+ * process.
+ */
+export interface FirestoreSessionCacheEntry {
+    /**
+     * The credential bundle returned by `GET /session/firestore`.
+     *
+     * Named `session` rather than `credentials` deliberately: it is the on-disk JSON schema of every
+     * existing `@dereekb/dbx-cli` `~/.<cli>/.firestore-sessions.json`, and renaming it would silently
+     * invalidate every user's cache on upgrade.
+     */
+    readonly session: FirestoreSessionCredentials;
+    /**
+     * Unix epoch milliseconds at which the entry was written.
+     */
+    readonly cachedAt: UnixDateTimeMillisecondsNumber;
+    /**
+     * The uid the entry was minted for, denormalized so a stale entry belonging to a different user
+     * can be detected without parsing the custom token.
+     */
+    readonly uid: FirebaseAuthUserId;
+}
+/**
+ * A credentials cache keyed by whatever the consumer keys sessions on (an env name for a CLI, a uid
+ * for a server).
+ *
+ * A PORT, not an implementation. This package ships no persistent store — see the security note on
+ * {@link FirestoreSessionCacheEntry}.
+ */
+export type FirestoreSessionCredentialsCache = AsyncKeyedValueCache<FirestoreSessionCacheEntry>;
+/**
+ * Resolves the epoch-millis instant at which a cached session stops being usable.
+ *
+ * The effective expiry is the EARLIER of the API-reported `expiresAt` and
+ * {@link FIRESTORE_SESSION_MAX_CACHE_MS} past the write. Taking the earlier of the two means a
+ * server that reports an over-long (or unparsable) window still cannot push a session past the
+ * Firebase credential ceiling.
+ *
+ * @param entry - The cached entry.
+ * @returns The effective expiry in unix epoch milliseconds.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function firestoreSessionEntryExpiresAt(entry: FirestoreSessionCacheEntry): UnixDateTimeMillisecondsNumber;
+/**
+ * Returns true when the cached session is at or near its effective expiry.
+ *
+ * @param entry - The cached entry (`null`/`undefined` is treated as expired).
+ * @param nowMs - The current time in unix epoch milliseconds. Defaults to `Date.now()`.
+ * @param bufferMs - Skew/latency buffer; the entry is treated as expired this far ahead of its effective expiry.
+ * @returns `true` when the entry is unusable, otherwise `false`.
+ */
+export declare function isFirestoreSessionExpired(entry: Maybe<FirestoreSessionCacheEntry>, nowMs?: UnixDateTimeMillisecondsNumber, bufferMs?: Milliseconds): boolean;

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

@@ -0,0 +1,149 @@
+import { type CodedError, type ISO8601DateString, type Maybe, type WebsiteUrl } from '@dereekb/util';
+import { type FirebaseAuthUserId } from '@dereekb/firebase';
+import { type OAuthResourceErrorCode } from '@dereekb/oauth-resource';
+import { BaseError } from 'make-error';
+/**
+ * Path (relative to the API base URL) of the user-scoped Firestore session endpoint served by
+ * `@dereekb/firebase-server`'s `SessionApiController`.
+ *
+ * Duplicated here rather than imported because importing it from `@dereekb/firebase-server` would be
+ * a dependency CYCLE: `firebase-server` already depends on `@dereekb/oauth-resource`
+ * (`packages/firebase-server/oidc/src/lib/service/oidc.service.ts`). The source of truth is
+ * `packages/firebase-server/src/lib/nest/controller/session/session.api.config.ts`.
+ */
+export declare const FIRESTORE_SESSION_API_PATH = "/session/firestore";
+/**
+ * The credential bundle `GET <apiBaseUrl>/session/firestore` returns.
+ *
+ * Mirrors `FirestoreSessionResult` in `@dereekb/firebase-server`'s `session.api.service.ts`.
+ *
+ * SECURITY: this is a bearer credential for the user it names. The custom token is exchangeable for
+ * a signed-in Firebase session as that uid by anyone holding it.
+ */
+export interface FirestoreSessionCredentials {
+    /**
+     * The uid the session was minted for.
+     */
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * A Firebase Auth custom token to exchange via `signInWithCustomToken`.
+     */
+    readonly customToken: string;
+    /**
+     * An App Check attestation minted server-side for the project's registered web app. Absent when
+     * the API has no `appCheckAppId` configured (a project that does not enforce App Check).
+     */
+    readonly appCheckToken?: string;
+    /**
+     * ISO timestamp at which the session's shortest-lived credential expires.
+     */
+    readonly expiresAt: ISO8601DateString;
+}
+/**
+ * Stable error code raised while obtaining a user-scoped Firestore session.
+ *
+ * Widens {@link OAuthResourceErrorCode} rather than forking a parallel union (DG-2). The 401/403
+ * members mean exactly what they mean there; the rest describe a failure of the OUTBOUND mint call,
+ * which is a different domain from an inbound token check — which is why they are NOT pushed back
+ * into `OAuthResourceErrorCode`: `bearerChallengeErrorForCode` would silently map them to
+ * `invalid_token`, and `OAUTH_RESOURCE_ERROR_STATUS_CODES` is a total `Record`.
+ */
+export type FirestoreSessionErrorCode = OAuthResourceErrorCode | 'not_found' | 'unavailable' | 'invalid_response' | 'invalid_config';
+export interface FirestoreSessionErrorInput {
+    readonly code: FirestoreSessionErrorCode;
+    readonly message: string;
+    /**
+     * HTTP status of the failed mint call, when the failure came from one.
+     */
+    readonly status?: Maybe<number>;
+    /**
+     * The actionable next step for an operator.
+     */
+    readonly suggestion?: Maybe<string>;
+    /**
+     * Extra machine-readable context carried onto the error.
+     */
+    readonly details?: Maybe<Record<string, unknown>>;
+}
+/**
+ * Error raised when a user-scoped Firestore session cannot be obtained.
+ *
+ * Consumers that already have their own error type do not have to catch and re-wrap this one: pass a
+ * {@link FirestoreSessionErrorFactory} and the session functions throw that type instead — the same
+ * seam `OAuthResourceErrorFactory` provides for verification.
+ */
+export declare class FirestoreSessionError extends BaseError implements CodedError {
+    readonly code: FirestoreSessionErrorCode;
+    readonly status?: number;
+    readonly suggestion?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(input: FirestoreSessionErrorInput);
+}
+/**
+ * Creates the error thrown when a session cannot be obtained.
+ *
+ * The seam that keeps this package error-type agnostic.
+ */
+export type FirestoreSessionErrorFactory = (input: FirestoreSessionErrorInput) => Error;
+/**
+ * Default {@link FirestoreSessionErrorFactory}, producing a {@link FirestoreSessionError}.
+ *
+ * @param input - The code, message, status, suggestion, and details of the failure.
+ * @returns The error to throw.
+ */
+export declare const defaultFirestoreSessionErrorFactory: FirestoreSessionErrorFactory;
+/**
+ * Returns true when the input is a {@link FirestoreSessionError}.
+ *
+ * @param error - The value to test.
+ * @returns Whether the value is a {@link FirestoreSessionError}.
+ */
+export declare function isFirestoreSessionError(error: unknown): error is FirestoreSessionError;
+/**
+ * Maps an HTTP status from the mint endpoint onto a {@link FirestoreSessionErrorCode}.
+ *
+ * @param status - The response status.
+ * @returns The matching error code.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function firestoreSessionErrorCodeForStatus(status: number): FirestoreSessionErrorCode;
+/**
+ * Composes the session endpoint's absolute URL from an API base URL.
+ *
+ * @param apiBaseUrl - The API base URL, with or without a trailing slash.
+ * @returns The absolute `/session/firestore` URL.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function firestoreSessionUrl(apiBaseUrl: WebsiteUrl): WebsiteUrl;
+export interface FetchFirestoreSessionInput {
+    /**
+     * The API base URL — typically `<host>/<project>/us-central1/api` or `https://<domain>/api`.
+     *
+     * The `/session/firestore` path is appended automatically.
+     */
+    readonly apiBaseUrl: WebsiteUrl;
+    /**
+     * The verified bearer access token to present. Must carry the `session.firestore` scope.
+     */
+    readonly accessToken: string;
+    /**
+     * Custom fetch implementation, for tracing or for tests.
+     */
+    readonly fetcher?: Maybe<typeof fetch>;
+    /**
+     * Maps a failure onto the consumer's own error type. Defaults to
+     * {@link defaultFirestoreSessionErrorFactory}.
+     */
+    readonly errorFactory?: Maybe<FirestoreSessionErrorFactory>;
+}
+/**
+ * Fetches a user-scoped Firestore session from the API with a Bearer access token.
+ *
+ * The endpoint is admin-only and additionally gated on the `session.firestore` OIDC scope, so a 403
+ * here usually means the token's user is not an admin or the token was issued without that scope.
+ *
+ * @param input - The API target, access token, and optional fetch/error overrides.
+ * @returns The parsed {@link FirestoreSessionCredentials}.
+ * @throws {FirestoreSessionError} (or the `errorFactory`'s type) When the endpoint answers non-2xx or returns an unusable body.
+ */
+export declare function fetchFirestoreSession(input: FetchFirestoreSessionInput): Promise<FirestoreSessionCredentials>;

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

@@ -0,0 +1,5 @@
+export * from './firebase-client.config';
+export * from './firebase-user-session';
+export * from './firebase-user-session.pool';
+export * from './firestore-session.cache';
+export * from './firestore-session.client';

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";