@dereekb/dbx-cli 14.2.0 → 14.4.0

package/lint-cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-lint-cache",
-  "version": "14.2.0",
+  "version": "14.4.0",
   "sideEffects": false,
   "private": true,
   "type": "module",
@@ -9,7 +9,7 @@
     "eslint": "10.9.1"
   },
   "peerDependencies": {
-    "@dereekb/util": "14.2.0",
+    "@dereekb/util": "14.4.0",
     "yargs": "^18.0.0"
   }
 }

package/manifest-extract/package.json

@@ -1,18 +1,22 @@
 {
   "name": "@dereekb/dbx-cli/manifest-extract",
-  "version": "14.2.0",
+  "version": "14.4.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.2.0",
-    "@dereekb/dbx-cli": "14.2.0",
-    "@dereekb/firebase": "14.2.0",
-    "@dereekb/model": "14.2.0",
-    "@dereekb/nestjs": "14.2.0",
-    "@dereekb/rxjs": "14.2.0",
-    "@dereekb/util": "14.2.0",
+    "@dereekb/date": "14.4.0",
+    "@dereekb/dbx-cli": "14.4.0",
+    "@dereekb/firebase": "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",
     "ts-morph": "^28.0.0"
   },
+  "devDependencies": {
+    "@dereekb/firebase": "14.4.0"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {

package/model-test/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/dbx-cli/model-test",
-  "version": "14.2.0",
+  "version": "14.4.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/util": "14.2.0",
+    "@dereekb/util": "14.4.0",
     "ts-morph": "^28.0.0"
   },
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "14.2.0",
+  "version": "14.4.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -66,11 +66,12 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "14.2.0",
-    "@dereekb/firebase": "14.2.0",
-    "@dereekb/model": "14.2.0",
-    "@dereekb/nestjs": "14.2.0",
-    "@dereekb/util": "14.2.0",
+    "@dereekb/date": "14.4.0",
+    "@dereekb/firebase": "14.4.0",
+    "@dereekb/model": "14.4.0",
+    "@dereekb/nestjs": "14.4.0",
+    "@dereekb/oauth-resource": "14.4.0",
+    "@dereekb/util": "14.4.0",
     "@nestjs/common": "^12.0.1",
     "arktype": "^2.2.0",
     "firebase": "^12.18.0",
@@ -83,7 +84,9 @@
   "devDependencies": {
     "@angular/core": "22.1.4",
     "@types/yargs": "^17.0.35",
-    "eslint": "10.9.1"
+    "@typescript-eslint/parser": "8.69.0",
+    "eslint": "10.9.1",
+    "firebase": "^12.18.0"
   },
   "module": "./index.esm.js",
   "main": "./index.esm.js",

package/route/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@dereekb/dbx-cli/route",
-  "version": "14.2.0",
+  "version": "14.4.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.2.0",
-    "@dereekb/dbx-cli": "14.2.0",
-    "@dereekb/firebase": "14.2.0",
-    "@dereekb/model": "14.2.0",
-    "@dereekb/nestjs": "14.2.0",
-    "@dereekb/util": "14.2.0"
+    "@dereekb/date": "14.4.0",
+    "@dereekb/dbx-cli": "14.4.0",
+    "@dereekb/firebase": "14.4.0",
+    "@dereekb/model": "14.4.0",
+    "@dereekb/nestjs": "14.4.0",
+    "@dereekb/oauth-resource": "14.4.0",
+    "@dereekb/util": "14.4.0"
   },
   "exports": {
     "./package.json": "./package.json",

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

@@ -1,33 +1,20 @@
+import { type FirestoreSessionCredentials, type FirestoreSessionErrorFactory } from '@dereekb/oauth-resource/firebase';
+export { FIRESTORE_SESSION_API_PATH } from '@dereekb/oauth-resource/firebase';
 /**
- * Path (relative to the API base URL) of the direct-Firestore session endpoint served by
- * `@dereekb/firebase-server`'s `SessionApiController`.
+ * The credential bundle `GET <apiBaseUrl>/session/firestore` returns.
  *
- * Duplicated here rather than imported so `dbx-cli` keeps no dependency on the server package —
- * the same arrangement `CALL_MODEL_API_PATH` uses.
+ * The CLI's name for {@link FirestoreSessionCredentials}, which is the shared implementation in
+ * `@dereekb/oauth-resource/firebase`.
  */
-export declare const FIRESTORE_SESSION_API_PATH = "/session/firestore";
+export type CliFirestoreSession = FirestoreSessionCredentials;
 /**
- * The credential bundle `GET <apiBaseUrl>/session/firestore` returns.
+ * Maps a generic session failure onto a {@link CliError}, re-attaching the CLI-flavored remediation
+ * an operator can act on (`<cli> auth login --env <env>` and friends).
+ *
+ * @param input - The generic failure.
+ * @returns The `CliError` to throw.
  */
-export interface CliFirestoreSession {
-    /**
-     * The uid the session was minted for.
-     */
-    readonly uid: string;
-    /**
-     * 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: string;
-}
+export declare const cliFirestoreSessionErrorFactory: FirestoreSessionErrorFactory;
 export interface FetchFirestoreSessionInput {
     /**
      * The API base URL — typically `<host>/<project>/us-central1/api` or `https://<domain>/api`.
@@ -44,11 +31,18 @@ export interface FetchFirestoreSessionInput {
 /**
  * Fetches a direct-Firestore session from the API with the cached Bearer access token.
  *
- * The endpoint is admin-only and additionally gated on the `session.firestore` OIDC scope, so a 403
- * here usually means the logged-in user is not an admin or logged in without that scope.
+ * The thin CLI wrapper over `@dereekb/oauth-resource/firebase`'s `fetchFirestoreSession`: it binds
+ * the CLI's `tracedFetch` (so `--verbose` and `--timeout` apply) and the `CliError` factory.
  *
  * @param input - The API target, access token, and optional fetch override.
  * @returns The parsed {@link CliFirestoreSession}.
  * @throws {CliError} When the endpoint answers non-2xx or returns an unusable body.
  */
 export declare function fetchFirestoreSession(input: FetchFirestoreSessionInput): Promise<CliFirestoreSession>;
+/**
+ * Binds the CLI's verbose-trace + `--timeout` fetch behavior onto the supplied (or global) fetch.
+ *
+ * @param fetcher - The underlying fetch impl, when one was injected.
+ * @returns A `fetch`-shaped function carrying the CLI's tracing.
+ */
+export declare function cliFirestoreSessionFetcher(fetcher?: typeof fetch): typeof fetch;

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

@@ -1,3 +1,4 @@
 export * from './auth.command.factory';
 export * from './oidc.client';
 export * from './oidc.flow';
+export * from './oidc.loopback';

package/src/lib/auth/oidc.loopback.d.ts

@@ -0,0 +1,127 @@
+import { type Maybe, type PortNumber, type WebsiteUrl } from '@dereekb/util';
+/**
+ * Hostnames RFC 8252 §7.3 treats as the loopback interface, and the exact set `oidc-provider`
+ * recognizes as a loopback redirect host.
+ *
+ * `[::1]` carries its brackets because that is what `URL.hostname` returns for an IPv6 literal —
+ * the brackets are stripped again before the address is handed to `server.listen`.
+ */
+export declare const LOOPBACK_REDIRECT_HOSTNAMES: readonly string[];
+/**
+ * The loopback port the CLI suggests when the configured redirect URI has no bindable port.
+ *
+ * Deliberately outside the 9900-9910 block the Firebase emulators occupy, so a suggested redirect
+ * URI never collides with a running emulator.
+ */
+export declare const SUGGESTED_CLI_LOOPBACK_REDIRECT_PORT: PortNumber;
+/**
+ * Error code raised when the loopback listener cannot bind the redirect URI's port (e.g. the port
+ * is already in use, or is privileged).
+ */
+export declare const LOOPBACK_REDIRECT_LISTEN_FAILED_ERROR_CODE = "AUTH_REDIRECT_LISTEN_FAILED";
+/**
+ * Error code raised when no redirect reached the loopback listener within the allotted time.
+ */
+export declare const LOOPBACK_REDIRECT_TIMEOUT_ERROR_CODE = "AUTH_REDIRECT_TIMEOUT";
+/**
+ * A redirect URI the CLI can bind a local HTTP listener to, decomposed into its parts.
+ */
+export interface LoopbackRedirectTarget {
+    /**
+     * The normalized redirect URI to send as `redirect_uri`. Identical to the configured URI unless a
+     * port override was applied.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * The loopback hostname, as `URL.hostname` reports it (so `[::1]` keeps its brackets).
+     */
+    readonly hostname: string;
+    /**
+     * The port to bind. Always a positive integer — a `0`/absent port is not a capturable target.
+     */
+    readonly port: PortNumber;
+    /**
+     * The path the provider redirects to. Requests to any other path are answered `404` so a stray
+     * `/favicon.ico` cannot be mistaken for the authorization redirect.
+     */
+    readonly pathname: string;
+}
+export interface ParseLoopbackRedirectUriInput {
+    /**
+     * The configured redirect URI.
+     */
+    readonly redirectUri: Maybe<string>;
+    /**
+     * Optional port override, replacing whatever port the redirect URI carries.
+     *
+     * The resulting URI is what gets sent as `redirect_uri`, so it must be registered with the OAuth
+     * client just like the configured one.
+     */
+    readonly port?: Maybe<PortNumber>;
+}
+/**
+ * Decomposes a redirect URI into a {@link LoopbackRedirectTarget} when the CLI can bind a local
+ * listener for it.
+ *
+ * A target is only produced for an `http:` loopback URI carrying a concrete, non-zero port. The
+ * conventional `http://127.0.0.1:0/callback` placeholder is deliberately NOT capturable: binding an
+ * ephemeral port would mean sending a `redirect_uri` that differs from the registered one, which
+ * every OAuth provider rejects unless the client is registered as a native app (where loopback
+ * ports are compared port-insensitively).
+ *
+ * @param input - The parse inputs.
+ * @param input.redirectUri - The configured redirect URI.
+ * @param input.port - Optional port override applied to the parsed URI.
+ * @returns The bindable target, or `undefined` when the URI cannot be captured locally.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function parseLoopbackRedirectUri(input: ParseLoopbackRedirectUriInput): Maybe<LoopbackRedirectTarget>;
+export interface StartLoopbackRedirectCaptureInput {
+    /**
+     * The bindable target, from {@link parseLoopbackRedirectUri}.
+     */
+    readonly target: LoopbackRedirectTarget;
+    /**
+     * Text shown in the browser tab once the redirect is captured.
+     */
+    readonly successMessage?: Maybe<string>;
+}
+export interface LoopbackRedirectCapture {
+    /**
+     * The `redirect_uri` the listener is bound to. Send this value in the authorization request.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * The bound port.
+     */
+    readonly port: PortNumber;
+    /**
+     * Resolves with the full redirect URL (query string included) the browser was sent to.
+     *
+     * A provider error redirect resolves rather than rejects — the returned URL carries the `error`
+     * params, which the shared redirect parser already turns into an `AUTH_PROVIDER_ERROR`.
+     *
+     * @param timeoutMs - Optional milliseconds to wait before rejecting with
+     *   {@link LOOPBACK_REDIRECT_TIMEOUT_ERROR_CODE}. Waits indefinitely when omitted.
+     */
+    readonly waitForRedirect: (timeoutMs?: Maybe<number>) => Promise<WebsiteUrl>;
+    /**
+     * Closes the listener and destroys any open sockets, so the CLI's event loop can drain.
+     */
+    readonly close: () => Promise<void>;
+}
+/**
+ * Binds a local HTTP listener to a loopback redirect URI so the authorization code can be read
+ * straight out of the browser redirect instead of being pasted back by hand.
+ *
+ * The listener answers exactly one path — the redirect URI's own — and serves a short "you can close
+ * this tab" page. Everything else is answered `404`, which is what keeps the browser's automatic
+ * `/favicon.ico` request from being mistaken for the redirect.
+ *
+ * @param input - The capture inputs.
+ * @param input.target - The bindable target, from {@link parseLoopbackRedirectUri}.
+ * @param input.successMessage - Optional override for the browser success page's body line.
+ * @returns The started {@link LoopbackRedirectCapture}.
+ * @throws {CliError} `AUTH_REDIRECT_LISTEN_FAILED` when the port cannot be bound.
+ */
+export declare function startLoopbackRedirectCapture(input: StartLoopbackRedirectCaptureInput): Promise<LoopbackRedirectCapture>;

package/src/lib/config/env.d.ts

@@ -1,4 +1,5 @@
-import { type Maybe } from '@dereekb/util';
+import { type Maybe, type OidcClientAuthMethod } from '@dereekb/util';
+import { type FirebaseClientConfig, type FirebaseClientEmulatorsConfig, firebaseClientEmulatorsInUse, isFirebaseClientConfigComplete } from '@dereekb/oauth-resource/firebase';
 import { type CliTokenEntry } from './token.cache';
 /**
  * The default OAuth/OIDC scopes requested by the CLI when none are configured.
@@ -15,7 +16,12 @@ export declare const MODEL_WRITE_OIDC_SCOPES: readonly ["model.create", "model.u
 /**
  * The default redirect URI used by the CLI.
  *
- * Opens up to nothing in the browser so the user can copy/paste the resulting token url back into the CLI.
+ * The `0` port is a placeholder, not a bindable port: the redirect resolves to nothing in the
+ * browser and the user copy/pastes the resulting URL back into the CLI.
+ *
+ * To have `auth login` capture the redirect automatically instead, configure a redirect URI with a
+ * concrete loopback port (e.g. `http://127.0.0.1:8976/callback`) and register that exact URI with
+ * the OAuth client — `auth login` binds it and reads the code straight out of the browser redirect.
  */
 export declare const DEFAULT_CLI_REDIRECT_URI = "http://127.0.0.1:0/callback";
 /**
@@ -112,67 +118,22 @@ export declare function mergeCliEnvWithDefault(input: MergeCliEnvWithDefaultInpu
  */
 export declare function mergeCliFirebaseConfig(env: Maybe<CliFirebaseConfig>, defaultEnv: Maybe<CliFirebaseConfig>): CliFirebaseConfig | undefined;
 /**
- * Local Firebase emulator targets for a CLI env.
- *
- * 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.
+ * Local Firebase emulator targets for a CLI env. The CLI's name for
+ * {@link FirebaseClientEmulatorsConfig}.
  */
-export interface CliFirebaseEmulatorsConfig {
-    /**
-     * 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_CLI_FIREBASE_EMULATOR_HOST}.
-     */
-    readonly host?: string;
-    /**
-     * Port of the Auth emulator. When unset, Auth is not redirected to an emulator.
-     */
-    readonly authPort?: number;
-    /**
-     * Port of the Firestore emulator. When unset, Firestore is not redirected to an emulator.
-     */
-    readonly firestorePort?: number;
-}
+export type CliFirebaseEmulatorsConfig = FirebaseClientEmulatorsConfig;
 /**
  * Firebase client-SDK configuration for a CLI env, used only by the direct-Firestore session
  * (`CliContext.getFirestoreContext`). Everything else the CLI does goes over the model HTTP API and
  * needs none of this.
  *
- * 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.
+ * The CLI's name for {@link FirebaseClientConfig}: the same shape any resource server opening a
+ * user-scoped Firestore session supplies.
  */
-export interface CliFirebaseConfig {
-    /**
-     * 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?: CliFirebaseEmulatorsConfig;
-}
+export type CliFirebaseConfig = FirebaseClientConfig;
 /**
  * Default host used for Firebase emulator connections when a {@link CliFirebaseEmulatorsConfig}
- * omits one.
+ * omits one. See {@link DEFAULT_FIREBASE_CLIENT_EMULATOR_HOST}.
  */
 export declare const DEFAULT_CLI_FIREBASE_EMULATOR_HOST = "localhost";
 /**
@@ -182,17 +143,22 @@ export declare const DEFAULT_CLI_FIREBASE_EMULATOR_HOST = "localhost";
  * Deliberately separate from {@link isCliEnvConfigComplete}: the Firebase config is optional, and
  * folding it into the general completeness check would break every CLI that only uses the model API.
  *
- * @param firebase - The env's Firebase client config, if any.
- * @returns `true` when `apiKey`, `projectId`, and `appId` are all present and non-empty.
+ * See {@link isFirebaseClientConfigComplete}.
+ */
+export declare const isCliFirebaseConfigComplete: typeof isFirebaseClientConfigComplete;
+/**
+ * Returns true when the env's emulator config is present and active. See
+ * {@link firebaseClientEmulatorsInUse}.
  */
-export declare function isCliFirebaseConfigComplete(firebase: Maybe<CliFirebaseConfig>): firebase is Required<Pick<CliFirebaseConfig, 'apiKey' | 'projectId' | 'appId'>> & CliFirebaseConfig;
+export declare const cliFirebaseEmulatorsInUse: typeof firebaseClientEmulatorsInUse;
 /**
- * Returns true when the env's emulator config is present and active.
+ * The OAuth client's registered `token_endpoint_auth_method`, as far as the CLI needs to model it.
  *
- * @param firebase - The env's Firebase client config, if any.
- * @returns `true` when emulators are configured and not explicitly disabled.
+ * Wider than {@link OidcClientAuthMethod} by exactly one member: `'none'`, the public-client case.
+ * That value is meaningless to the protocol layer — a public client sends no credential, so there is
+ * no presentation to choose — but it is precisely what the CLI needs in order to stop asking for one.
  */
-export declare function cliFirebaseEmulatorsInUse(firebase: Maybe<CliFirebaseConfig>): boolean;
+export type OidcCliTokenEndpointAuthMethod = OidcClientAuthMethod | 'none';
 /**
  * Environment-targeting config for a CLI invocation.
  *
@@ -231,12 +197,30 @@ export interface CliEnvConfig {
     readonly clientId?: string;
     /**
      * The OAuth client secret registered with the target app.
+     *
+     * Absent for a public client — see {@link tokenEndpointAuthMethod}.
      */
     readonly clientSecret?: string;
     /**
-     * The redirect URI registered with the OAuth client. The CLI does not bind a server — it parses
-     * the URL the user pastes back, so this can be any value the OIDC provider accepts as a
-     * registered redirect URI (e.g. `http://127.0.0.1:0/callback` or another loopback/placeholder URL).
+     * How the client authenticates at the token endpoint, mirroring the OAuth client's registered
+     * `token_endpoint_auth_method`.
+     *
+     * `'none'` marks a PUBLIC client: it holds no secret and proves itself with PKCE instead. Recording
+     * it lets `auth setup` skip the client-secret prompt outright rather than asking for a credential
+     * that must not exist — the prompt cannot infer this, since "no secret yet" and "never a secret"
+     * look identical from an empty config.
+     *
+     * Omit to leave it unknown, which keeps the existing prompt-and-accept-empty behaviour.
+     */
+    readonly tokenEndpointAuthMethod?: OidcCliTokenEndpointAuthMethod;
+    /**
+     * The redirect URI registered with the OAuth client.
+     *
+     * When this is an `http:` loopback URI with a concrete, non-zero port (e.g.
+     * `http://127.0.0.1:8976/callback`), `auth login` binds that port and reads the authorization code
+     * straight out of the browser redirect. Any other value — including the
+     * {@link DEFAULT_CLI_REDIRECT_URI} `:0` placeholder and out-of-band URNs — falls back to the user
+     * pasting the redirect URL back into the CLI.
      *
      * Defaults to {@link DEFAULT_CLI_REDIRECT_URI}.
      */
@@ -312,10 +296,15 @@ export declare function applyEnvVarOverrides(input: EnvVarOverrideInput): Maybe<
 /**
  * Returns true when the env has the minimum fields needed to attempt an OAuth login or token refresh.
  *
+ * `clientSecret` is NOT among them. A CLI is a public client in the usual case
+ * (`token_endpoint_auth_method: 'none'`), authenticating with PKCE rather than a secret, so requiring
+ * one here would report a correctly-configured public env as incomplete — and send the caller back to
+ * `auth setup` to supply a credential the provider would then reject.
+ *
  * @param env - The env config to check.
- * @returns `true` when `apiBaseUrl`, `oidcIssuer`, `clientId`, `clientSecret`, and `redirectUri` are all present and non-empty.
+ * @returns `true` when `apiBaseUrl`, `oidcIssuer`, `clientId`, and `redirectUri` are all present and non-empty.
  */
-export declare function isCliEnvConfigComplete(env: Maybe<CliEnvConfig>): env is Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'clientSecret' | 'redirectUri'>> & CliEnvConfig;
+export declare function isCliEnvConfigComplete(env: Maybe<CliEnvConfig>): env is Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'redirectUri'>> & CliEnvConfig;
 /**
  * Inputs to {@link readEnvTokenEntry}.
  */

package/src/lib/config/env.resolve.d.ts

@@ -8,7 +8,7 @@ import { type CliPaths } from './paths';
  * Guarantees that the OIDC client fields are present so callers can pass them through to the
  * OIDC client/token helpers without a non-null assertion or extra runtime check.
  */
-export type CliEnvConfigComplete = Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'clientSecret' | 'redirectUri'>> & CliEnvConfig;
+export type CliEnvConfigComplete = Required<Pick<CliEnvConfig, 'apiBaseUrl' | 'oidcIssuer' | 'clientId' | 'redirectUri'>> & CliEnvConfig;
 /**
  * Builds the conventional `<CLINAME>_ENV` env var name from the CLI binary name.
  *
@@ -71,8 +71,9 @@ export declare function resolveCliEnv(input: ResolveCliEnvInput): Promise<Resolv
 export interface ResolveCliEnvOrThrowInput extends ResolveCliEnvInput {
     /**
      * When `true`, throws `AUTH_ENV_INCOMPLETE` if the resolved env is missing OIDC fields
-     * (apiBaseUrl, oidcIssuer, clientId, clientSecret, redirectUri). The returned env is narrowed
-     * to {@link CliEnvConfigComplete}. Defaults to `false`.
+     * (apiBaseUrl, oidcIssuer, clientId, redirectUri). `clientSecret` is not required — see
+     * {@link isCliEnvConfigComplete}. The returned env is narrowed to {@link CliEnvConfigComplete}.
+     * Defaults to `false`.
      */
     readonly requireComplete?: boolean;
 }

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

@@ -1,40 +1,19 @@
-import { type AsyncKeyedValueCache, type Maybe } from '@dereekb/util';
-import { type CliFirestoreSession } from '../api/firestore-session.client';
+import { type FirestoreSessionCacheEntry, type FirestoreSessionCredentialsCache, firestoreSessionEntryExpiresAt, isFirestoreSessionExpired } from '@dereekb/oauth-resource/firebase';
 /**
  * Hard ceiling on how long a minted direct-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.
+ * API reported in `expiresAt`. See {@link FIRESTORE_SESSION_MAX_CACHE_MS}.
  */
 export declare const CLI_FIRESTORE_SESSION_MAX_CACHE_MS: number;
 /**
- * Default skew/latency buffer applied when deciding whether a cached session is still usable.
+ * Default skew/latency buffer applied when deciding whether a cached session is still usable. See
+ * {@link FIRESTORE_SESSION_EXPIRY_BUFFER_MS}.
  */
-export declare const CLI_FIRESTORE_SESSION_EXPIRY_BUFFER_MS = 60000;
+export declare const CLI_FIRESTORE_SESSION_EXPIRY_BUFFER_MS: number;
 /**
- * A cached direct-Firestore session for a single env.
- *
- * 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.
+ * A cached direct-Firestore session for a single env. The CLI's name for
+ * {@link FirestoreSessionCacheEntry}.
  */
-export interface CliFirestoreSessionEntry {
-    /**
-     * The credential bundle returned by `GET /session/firestore`.
-     */
-    readonly session: CliFirestoreSession;
-    /**
-     * Unix epoch milliseconds at which the entry was written.
-     */
-    readonly cachedAt: number;
-    /**
-     * 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: string;
-}
+export type CliFirestoreSessionEntry = FirestoreSessionCacheEntry;
 /**
  * Firestore session cache shape on disk — keyed by env name.
  */
@@ -45,13 +24,18 @@ export type CliFirestoreSessionCache = Record<string, CliFirestoreSessionEntry>;
  * Backed by a single JSON file with per-process in-memory memoization, exactly like the token
  * cache — see {@link createMemoizedJsonFileAsyncKeyedValueCache}.
  */
-export type CliFirestoreSessionCacheStore = AsyncKeyedValueCache<CliFirestoreSessionEntry>;
+export type CliFirestoreSessionCacheStore = FirestoreSessionCredentialsCache;
 export interface CreateCliFirestoreSessionCacheStoreInput {
     readonly firestoreSessionCachePath: string;
 }
 /**
  * Creates a per-env direct-Firestore session cache store backed by a single JSON file.
  *
+ * The file-backed half of the session cache stays HERE rather than moving to
+ * `@dereekb/oauth-resource/firebase`: it depends on `@dereekb/nestjs`, and a Nest peer has no business
+ * in a package whose whole point is a clean install graph. Only the expiry policy and the
+ * {@link FirestoreSessionCredentialsCache} port are shared.
+ *
  * Entries are written with mode 0o600 — they hold a Firebase custom token, which is a bearer
  * credential for the user it was minted for.
  *
@@ -62,25 +46,12 @@ export interface CreateCliFirestoreSessionCacheStoreInput {
  */
 export declare function createCliFirestoreSessionCacheStore(input: CreateCliFirestoreSessionCacheStoreInput): CliFirestoreSessionCacheStore;
 /**
- * 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 CLI_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__
+ * Resolves the epoch-millis instant at which a cached session stops being usable. See
+ * {@link firestoreSessionEntryExpiresAt}.
  */
-export declare function cliFirestoreSessionEntryExpiresAt(entry: CliFirestoreSessionEntry): number;
+export declare const cliFirestoreSessionEntryExpiresAt: typeof firestoreSessionEntryExpiresAt;
 /**
- * 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`.
+ * Returns true when the cached session is at or near its effective expiry. See
+ * {@link isFirestoreSessionExpired}.
  */
-export declare function isCliFirestoreSessionExpired(entry: Maybe<CliFirestoreSessionEntry>, nowMs?: number, bufferMs?: number): boolean;
+export declare const isCliFirestoreSessionExpired: typeof isFirestoreSessionExpired;