@dereekb/firebase-server 14.2.0 → 14.4.0

package/test/src/lib/oidc/oidc.test.flow.d.ts

@@ -1,8 +1,18 @@
+import request from 'supertest';
 import { type INestApplication } from '@nestjs/common';
+import { type Maybe } from '@dereekb/util';
 import { type OidcProviderProfileKey, type OidcTokenEndpointAuthMethod } from '@dereekb/firebase';
 import { OidcClientService } from '@dereekb/firebase-server/oidc';
 /**
- * Configuration for {@link performFullOAuthFlow}.
+ * A stage of the OAuth authorization code flow that {@link performOAuthFlow} can stop at.
+ *
+ * - `'auth'` — stop on the `/oidc/auth` response, before the login interaction.
+ * - `'callback'` — stop on the client callback redirect, before the token exchange.
+ * - `'token'` — run the whole flow, through the token exchange.
+ */
+export type OAuthTestFlowStage = 'auth' | 'callback' | 'token';
+/**
+ * Configuration for {@link performOAuthFlow} / {@link performFullOAuthFlow}.
  */
 export interface OAuthTestFlowConfig {
     /**
@@ -33,36 +43,226 @@ export interface OAuthTestFlowConfig {
      * "all registered scopes" resolution deliberately drops assignment-only scopes.
      */
     readonly providerProfiles?: readonly OidcProviderProfileKey[];
+    /**
+     * OAuth `prompt` parameter for the authorization request (e.g. `'consent'` to force the consent screen
+     * on a session that has already authorized the client). Omitted by default.
+     */
+    readonly prompt?: string;
+    /**
+     * Explicit subset of the requested OIDC scopes to grant at consent (the consent request's
+     * `grantedOIDCScopes`). Omitted by default, which grants every requested scope.
+     */
+    readonly grantedOIDCScopes?: readonly string[];
+    /**
+     * A prior flow's client and cookies to run this flow against — the same OAuth client, the same
+     * provider session, and therefore the same Grant. Omitted by default, which creates a fresh client
+     * and starts a fresh session.
+     *
+     * When the session is still logged in, the provider skips the login prompt and the flow goes straight
+     * to consent (or straight to the callback when nothing new needs consenting and `prompt` is unset).
+     */
+    readonly session?: OAuthTestFlowSession;
+    /**
+     * RFC 8707 `resource` indicator, sent on both `/oidc/auth` and `/oidc/token`.
+     *
+     * Must match a key registered on the provider's `resourceServers` config. The issued access
+     * token then carries that entry's `audience` and — when the entry sets
+     * `accessTokenFormat: 'jwt'` — is an RS256 JWT a remote resource server can verify against the
+     * provider's JWKS, rather than the default opaque token only the provider itself can validate.
+     */
+    readonly resource?: string;
+    /**
+     * Extra query parameters merged onto the `/oidc/auth` request, for parameters this config does
+     * not model explicitly.
+     */
+    readonly extraAuthParams?: Record<string, string | number>;
+    /**
+     * The stage to stop the flow at. Defaults to `'token'`, the full flow.
+     *
+     * - `'auth'` — issue the `/oidc/auth` request and stop, exposing the raw redirect response on
+     *   {@link OAuthTestFlowResult.authResponse}. Nothing logs in, so no `uid` is needed.
+     * - `'callback'` — drive auth → login → consent → the callback redirect and stop before the token
+     *   exchange, exposing {@link OAuthTestFlowResult.callbackUrl} and
+     *   {@link OAuthTestFlowResult.consentRedirectUrl}. A callback carrying an `error` instead of a
+     *   `code` (e.g. `access_denied`) is not treated as a failure at this stage, so a caller can assert
+     *   on it.
+     * - `'token'` — the full flow, exchanging the authorization code for tokens.
+     *
+     * Ignored by {@link performFullOAuthFlow} / {@link setupAndPerformFullOAuthFlow}, whose result type
+     * guarantees tokens; stop early with {@link performOAuthFlow} / {@link setupAndPerformOAuthFlow}.
+     */
+    readonly stopAtStage?: OAuthTestFlowStage;
+}
+/**
+ * The client and cookies a flow ran with, for chaining a second flow onto the same provider session.
+ */
+export interface OAuthTestFlowSession {
+    readonly client: OAuthTestFlowClient;
+    readonly cookieJar: OAuthTestFlowCookieJar;
+}
+/**
+ * The OAuth client a flow created (or reused).
+ */
+export interface OAuthTestFlowClient {
+    readonly client_id: string;
+    readonly client_secret?: string;
+    readonly redirectUri: string;
+}
+/**
+ * Cookie jar helpers for the OAuth flow. See {@link createCookieJar}.
+ */
+export interface OAuthTestFlowCookieJar {
+    readonly collectCookies: (res: request.Response) => void;
+    readonly cookieHeader: () => string;
+}
+/**
+ * Result of {@link performOAuthFlow}, covering every {@link OAuthTestFlowStage} it can stop at.
+ *
+ * Every field a stage produced is populated; the fields belonging to later stages are undefined.
+ */
+export interface OAuthTestFlowResult {
+    /**
+     * The stage the flow stopped at.
+     */
+    readonly stage: OAuthTestFlowStage;
+    /**
+     * The raw `/oidc/auth` response, before any redirect was followed.
+     *
+     * Always populated. This is what a flow stopped at the `'auth'` stage asserts on — it may be a
+     * redirect to the login interaction, or an error callback (e.g. `error=invalid_target`).
+     */
+    readonly authResponse: request.Response;
+    /**
+     * The PKCE `code_verifier` the flow's `code_challenge` was derived from.
+     *
+     * Always populated, for a caller that performs its own `/oidc/token` request after stopping at the
+     * `'callback'` stage.
+     */
+    readonly codeVerifier: string;
+    /**
+     * The URL of the consent SCREEN the provider redirected to, when the flow reached it.
+     *
+     * Its `scopes` query parameter is the checkbox list the consent UI renders, so it is what scope
+     * withholding (e.g. an admin-only scope kept off a non-admin's screen) acts on.
+     *
+     * Undefined when the flow stopped at the `'auth'` stage, or when nothing needed consenting.
+     */
+    readonly consentRedirectUrl?: Maybe<URL>;
+    /**
+     * The client callback URL the flow ended on, carrying either a `code` or an `error`.
+     *
+     * Undefined when the flow stopped at the `'auth'` stage.
+     */
+    readonly callbackUrl?: Maybe<URL>;
+    /**
+     * The access token the token endpoint issued. Undefined unless the flow ran to the `'token'` stage.
+     */
+    readonly accessToken?: string;
+    /**
+     * The ID token the token endpoint issued. Undefined unless the flow ran to the `'token'` stage.
+     */
+    readonly idToken?: string;
+    /**
+     * The `token_type` the token endpoint reported for the access token.
+     */
+    readonly tokenType?: string;
+    /**
+     * The space-separated scope the token endpoint reported for the access token. Undefined unless the
+     * flow ran to the `'token'` stage.
+     */
+    readonly scope?: string;
+    /**
+     * The client and cookies this flow ran with, for chaining another flow onto the same session via
+     * {@link OAuthTestFlowConfig.session} — and for the cookie header a caller's own `/oidc/token`
+     * request needs, via `session.cookieJar.cookieHeader()`.
+     */
+    readonly session: OAuthTestFlowSession;
 }
-export interface PerformFullOAuthFlowResult {
+/**
+ * Result of {@link performFullOAuthFlow} — an {@link OAuthTestFlowResult} that ran to the `'token'`
+ * stage, so the callback and the tokens are guaranteed.
+ */
+export interface PerformFullOAuthFlowResult extends OAuthTestFlowResult {
+    readonly callbackUrl: URL;
     readonly accessToken: string;
     readonly idToken: string;
+    readonly scope: string;
 }
 /**
- * Input for {@link performFullOAuthFlow}.
+ * Input for {@link performOAuthFlow}.
  */
-export interface PerformFullOAuthFlowInput {
+export interface PerformOAuthFlowInput {
     readonly server: ReturnType<INestApplication['getHttpServer']>;
     readonly oidcClientService: OidcClientService;
     readonly nestApp: INestApplication;
-    readonly uid: string;
+    /**
+     * Firebase user ID for whom the test ID token is minted and the flow is authorized.
+     *
+     * Only optional for a flow that stops at the `'auth'` stage, which never reaches the login
+     * interaction. Any later stage throws when it is missing.
+     */
+    readonly uid?: Maybe<string>;
     readonly config?: OAuthTestFlowConfig;
 }
+/**
+ * Input for {@link performFullOAuthFlow}.
+ */
+export interface PerformFullOAuthFlowInput extends PerformOAuthFlowInput {
+    readonly uid: string;
+}
+/**
+ * Performs the OAuth authorization code flow with PKCE, up to the configured
+ * {@link OAuthTestFlowConfig.stopAtStage}.
+ *
+ * Steps: create client → PKCE → auth redirect → login → consent → code exchange → token
+ *
+ * Stopping early is how a test asserts on an intermediate the completed flow discards — the raw
+ * `/oidc/auth` response, the consent screen's offered `scopes`, or a callback that came back carrying
+ * an `error` instead of a `code`. A stage before `'token'` never exchanges the code, so it never
+ * throws on such a callback; the caller asserts on {@link OAuthTestFlowResult.callbackUrl} instead,
+ * and can run its own `/oidc/token` request with {@link OAuthTestFlowResult.codeVerifier} and the
+ * session's cookie header.
+ *
+ * @param input - Bag of services and overrides needed to drive the flow.
+ * @param input.server - HTTP server returned by `nestApp.getHttpServer()` against which all supertest requests are issued.
+ * @param input.oidcClientService - Service used to create the OAuth client whose credentials drive the flow.
+ * @param input.nestApp - Initialized NestJS application; used to resolve {@link OidcAccountService} for project-id-derived ID tokens and default scopes.
+ * @param input.uid - Firebase user ID for whom the test ID token is minted; required for any stage past `'auth'`.
+ * @param input.config - Optional flow overrides (scopes, redirect URI, client name, token endpoint auth method, provider profiles, stop stage).
+ * @returns The intermediates the flow produced, plus the tokens when it ran to the `'token'` stage.
+ * @throws {Error} When a stage past `'auth'` is requested without a `uid`, or when the token exchange step fails (the response body and status are included in the message).
+ */
+export declare function performOAuthFlow(input: PerformOAuthFlowInput): Promise<OAuthTestFlowResult>;
 /**
  * Performs the full OAuth authorization code flow with PKCE and returns tokens.
  *
  * Steps: create client → PKCE → auth redirect → login → consent → code exchange → token
  *
+ * Always runs to the `'token'` stage — {@link OAuthTestFlowConfig.stopAtStage} is ignored here, since
+ * this function's result guarantees tokens. Use {@link performOAuthFlow} to stop earlier.
+ *
  * @param input - Bag of services and overrides needed to drive the flow end-to-end.
  * @param input.server - HTTP server returned by `nestApp.getHttpServer()` against which all supertest requests are issued.
  * @param input.oidcClientService - Service used to create the OAuth client whose credentials drive the flow.
  * @param input.nestApp - Initialized NestJS application; used to resolve {@link OidcAccountService} for project-id-derived ID tokens and default scopes.
  * @param input.uid - Firebase user ID for whom the test ID token is minted and the OAuth flow is authorized.
  * @param input.config - Optional flow overrides (scopes, redirect URI, client name, token endpoint auth method, provider profiles).
- * @returns The exchanged access token and ID token from the OIDC `/token` endpoint.
+ * @returns The exchanged access token and ID token from the OIDC `/token` endpoint, plus the flow's intermediates.
  * @throws {Error} When the token exchange step fails (the response body and status are included in the message).
  */
 export declare function performFullOAuthFlow(input: PerformFullOAuthFlowInput): Promise<PerformFullOAuthFlowResult>;
+/**
+ * Higher-level helper that resolves OIDC services from the NestJS DI container,
+ * rotates JWKS keys, and then performs the OAuth flow up to {@link OAuthTestFlowConfig.stopAtStage}.
+ *
+ * This avoids callers needing to import from `@dereekb/firebase-server/oidc` directly.
+ *
+ * @param nestApp - Initialized NestJS application from which {@link JwksService} and {@link OidcClientService} are resolved.
+ * @param uid - Firebase user ID for whom the OAuth flow is authorized; only omittable for the `'auth'` stage.
+ * @param config - Optional flow overrides (scopes, redirect URI, client name, token endpoint auth method, provider profiles, stop stage).
+ * @returns The result of {@link performOAuthFlow}.
+ */
+export declare function setupAndPerformOAuthFlow(nestApp: INestApplication, uid: Maybe<string>, config?: OAuthTestFlowConfig): Promise<OAuthTestFlowResult>;
 /**
  * Higher-level helper that resolves OIDC services from the NestJS DI container,
  * rotates JWKS keys, and then performs the full OAuth flow.

package/twilio/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/twilio",
-  "version": "14.2.0",
+  "version": "14.4.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.2.0",
-    "@dereekb/firebase": "14.2.0",
-    "@dereekb/firebase-server": "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/firebase": "14.4.0",
+    "@dereekb/firebase-server": "14.4.0",
+    "@dereekb/model": "14.4.0",
+    "@dereekb/nestjs": "14.4.0",
+    "@dereekb/rxjs": "14.4.0",
+    "@dereekb/util": "14.4.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "14.2.0",
+  "version": "14.4.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.2.0",
-    "@dereekb/date": "14.2.0",
-    "@dereekb/model": "14.2.0",
-    "@dereekb/nestjs": "14.2.0",
-    "@dereekb/rxjs": "14.2.0",
-    "@dereekb/firebase": "14.2.0",
-    "@dereekb/firebase-server": "14.2.0",
-    "@dereekb/util": "14.2.0",
-    "@dereekb/zoho": "14.2.0",
+    "@dereekb/analytics": "14.4.0",
+    "@dereekb/date": "14.4.0",
+    "@dereekb/model": "14.4.0",
+    "@dereekb/nestjs": "14.4.0",
+    "@dereekb/rxjs": "14.4.0",
+    "@dereekb/firebase": "14.4.0",
+    "@dereekb/firebase-server": "14.4.0",
+    "@dereekb/util": "14.4.0",
+    "@dereekb/zoho": "14.4.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "express": "^5.2.1"