@dereekb/firebase-server 14.3.0 → 14.5.0

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

@@ -1,9 +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 {
     /**
@@ -53,6 +62,36 @@ export interface OAuthTestFlowConfig {
      * 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.
@@ -76,44 +115,164 @@ export interface OAuthTestFlowCookieJar {
     readonly collectCookies: (res: request.Response) => void;
     readonly cookieHeader: () => string;
 }
-export interface PerformFullOAuthFlowResult {
-    readonly accessToken: string;
-    readonly idToken: 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 space-separated scope the token endpoint reported for the access token.
+     * The stage the flow stopped at.
      */
-    readonly scope: string;
+    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 refresh token the token endpoint issued.
+     *
+     * Only present when the flow requested `offline_access` — the provider issues a refresh token for
+     * no other reason. Undefined unless the flow ran to the `'token'` stage.
+     *
+     * This is what a revocation test spends: a refresh exchange is the one operation that keeps working
+     * against a still-live Grant and fails with `invalid_grant` the instant the Grant is destroyed.
+     */
+    readonly refreshToken?: 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}.
+     * {@link OAuthTestFlowConfig.session} — and for the cookie header a caller's own `/oidc/token`
+     * request needs, via `session.cookieJar.cookieHeader()`.
      */
     readonly session: OAuthTestFlowSession;
 }
 /**
- * Input for {@link performFullOAuthFlow}.
+ * Result of {@link performFullOAuthFlow} — an {@link OAuthTestFlowResult} that ran to the `'token'`
+ * stage, so the callback and the tokens are guaranteed.
  */
-export interface PerformFullOAuthFlowInput {
+export interface PerformFullOAuthFlowResult extends OAuthTestFlowResult {
+    readonly callbackUrl: URL;
+    readonly accessToken: string;
+    readonly idToken: string;
+    readonly scope: string;
+}
+/**
+ * Input for {@link performOAuthFlow}.
+ */
+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.3.0",
+  "version": "14.5.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.3.0",
-    "@dereekb/firebase": "14.3.0",
-    "@dereekb/firebase-server": "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.5.0",
+    "@dereekb/firebase": "14.5.0",
+    "@dereekb/firebase-server": "14.5.0",
+    "@dereekb/model": "14.5.0",
+    "@dereekb/nestjs": "14.5.0",
+    "@dereekb/rxjs": "14.5.0",
+    "@dereekb/util": "14.5.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/package.json

@@ -1,22 +1,26 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "14.3.0",
+  "version": "14.5.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.3.0",
-    "@dereekb/date": "14.3.0",
-    "@dereekb/model": "14.3.0",
-    "@dereekb/nestjs": "14.3.0",
-    "@dereekb/rxjs": "14.3.0",
-    "@dereekb/firebase": "14.3.0",
-    "@dereekb/firebase-server": "14.3.0",
-    "@dereekb/util": "14.3.0",
-    "@dereekb/zoho": "14.3.0",
+    "@dereekb/analytics": "14.5.0",
+    "@dereekb/date": "14.5.0",
+    "@dereekb/firebase": "14.5.0",
+    "@dereekb/firebase-server": "14.5.0",
+    "@dereekb/model": "14.5.0",
+    "@dereekb/nestjs": "14.5.0",
+    "@dereekb/rxjs": "14.5.0",
+    "@dereekb/util": "14.5.0",
+    "@dereekb/zoho": "14.5.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "express": "^5.2.1"
   },
+  "devDependencies": {
+    "@nestjs/testing": "^12.0.1",
+    "date-fns": "^4.1.0"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {