@dereekb/firebase-server 13.4.0 → 13.4.2

package/oidc/src/lib/controller/oidc.interaction.controller.d.ts

@@ -23,6 +23,10 @@ export declare class OidcInteractionController {
      *
      * Detects the interaction type and redirects to the appropriate frontend page.
      *
+     * @param uid - the interaction UID from the URL path
+     * @param req - the incoming Express request
+     * @param res - the Express response used for redirecting
+     * @returns a redirect response to the appropriate frontend page
      * @throws {HttpException} 404 when the interaction UID is not found or has expired.
      */
     getInteraction(uid: OidcInteractionUid, req: Request, res: Response): Promise<void>;
@@ -32,6 +36,9 @@ export declare class OidcInteractionController {
      * Verifies the Firebase Auth ID token sent by the frontend, extracts the
      * user's UID, and completes the oidc-provider login interaction.
      *
+     * @param uid - the interaction UID from the URL path
+     * @param body - the login request containing the Firebase ID token
+     * @param res - the Express response used for sending JSON
      * @throws {HttpException} 401 when the Firebase ID token is invalid.
      * @throws {HttpException} 400 when the login interaction cannot be completed.
      */
@@ -42,12 +49,17 @@ export declare class OidcInteractionController {
      * Receives consent decision from frontend. Grants missing OIDC scopes and claims
      * when approved, or returns `access_denied` when rejected.
      *
+     * @param uid - the interaction UID from the URL path
+     * @param body - the consent request containing approval decision and Firebase ID token
+     * @param res - the Express response used for sending JSON
      * @throws {HttpException} 400 when the consent interaction cannot be completed.
      */
     postConsent(uid: OidcInteractionUid, body: OAuthInteractionConsentRequest, res: Response): Promise<void>;
     /**
      * Verifies a Firebase Auth ID token and returns the user's UID.
      *
+     * @param idToken - the Firebase Auth ID token to verify
+     * @returns the user's UID extracted from the decoded token
      * @throws {HttpException} 401 when the token is invalid or expired.
      */
     private _verifyIdToken;

package/oidc/src/lib/controller/oidc.wellknown.controller.d.ts

@@ -14,12 +14,16 @@ export declare class OidcWellKnownController {
      *
      * Returns the provider metadata so clients can auto-discover endpoints,
      * supported scopes, signing algorithms, etc.
+     *
+     * @returns the OIDC discovery metadata document
      */
     getOpenIdConfiguration(): Promise<OidcDiscoveryMetadata>;
     /**
      * JWKS endpoint. Returns the public JSON Web Key Set for token verification.
      *
      * This endpoint is typically skipped if the JwksServiceStorageConfig is provided.
+     *
+     * @returns the public JWKS containing all non-retired signing keys
      */
     getJwks(): Promise<{
         keys: import("..").JsonWebKeyWithKid[];
@@ -29,6 +33,8 @@ export declare class OidcWellKnownController {
      *
      * Returns the authorization server(s) that protect this resource,
      * allowing clients to discover which authorization server to use.
+     *
+     * @returns the protected resource metadata with authorization server URLs
      */
     getProtectedResource(): {
         authorization_servers: string[];

package/oidc/src/lib/model/jwks/jwks.d.ts

@@ -85,10 +85,16 @@ export interface JwksKeyConverterConfig {
  * Creates a snapshot converter for {@link JwksKey} documents.
  *
  * Requires runtime encryption config since the private key field is encrypted at rest.
+ *
+ * @param config - encryption configuration for the private key field
+ * @returns snapshot converter functions for JwksKey documents
  */
 export declare function jwksKeyConverter(config: JwksKeyConverterConfig): import("@dereekb/firebase").SnapshotConverterFunctions<JwksKey, Partial<import("@dereekb/util").ReplaceType<JwksKey, import("@dereekb/util").MaybeMap<object>, any>>>;
 /**
  * Returns the Firestore {@link CollectionReference} for {@link JwksKey} documents.
+ *
+ * @param context - the Firestore context to create the collection reference from
+ * @returns the typed collection reference for JwksKey documents
  */
 export declare function jwksKeyCollectionReference(context: FirestoreContext): CollectionReference<JwksKey>;
 /**
@@ -103,5 +109,8 @@ export interface JwksKeyFirestoreCollectionConfig extends JwksKeyConverterConfig
 }
 /**
  * Creates a {@link JwksKeyFirestoreCollection} with encrypted private key field support.
+ *
+ * @param config - configuration including the Firestore context and encryption settings
+ * @returns the configured JwksKey Firestore collection
  */
 export declare function jwksKeyFirestoreCollection(config: JwksKeyFirestoreCollectionConfig): JwksKeyFirestoreCollection;

package/oidc/src/lib/model/jwks/jwks.query.d.ts

@@ -2,17 +2,26 @@ import { type FirestoreQueryConstraint } from '@dereekb/firebase';
 import { type JwksKeyStatus } from './jwks';
 /**
  * Query for JwksKey documents with a specific status.
+ *
+ * @param status - the lifecycle status to filter by
+ * @returns Firestore query constraints filtering by the given status
  */
 export declare function jwksKeysWithStatusQuery(status: JwksKeyStatus): FirestoreQueryConstraint[];
 /**
  * Query for active JwksKey documents.
+ *
+ * @returns Firestore query constraints filtering for active keys
  */
 export declare function activeJwksKeysQuery(): FirestoreQueryConstraint[];
 /**
  * Query for non-retired JwksKey documents (active + rotated).
+ *
+ * @returns Firestore query constraints filtering for non-retired keys
  */
 export declare function nonRetiredJwksKeysQuery(): FirestoreQueryConstraint[];
 /**
  * Query for rotated JwksKey documents.
+ *
+ * @returns Firestore query constraints filtering for rotated keys
  */
 export declare function rotatedJwksKeysQuery(): FirestoreQueryConstraint[];

package/oidc/src/lib/model/oidc/oidcmodel.action.server.d.ts

@@ -25,6 +25,7 @@ export declare abstract class OidcModelServerActions {
  * Creates a concrete {@link OidcModelServerActions} implementation wired to the provided context.
  *
  * @param context - the fully assembled OIDC model server actions context
+ * @returns the concrete OidcModelServerActions instance
  *
  * @example
  * ```ts
@@ -39,12 +40,18 @@ export declare function oidcModelServerActions(context: OidcModelServerActionsCo
  *
  * Delegates to {@link OidcClientService.createClient} to generate a `client_id` and `client_secret`,
  * create the adapter entry, and return the secret in plaintext (only returned once).
+ *
+ * @param context - the OIDC model server actions context
+ * @returns a transform function factory for creating OIDC clients
  */
 export declare function createOidcClientFactory(context: OidcModelServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<CreateOidcClientParams, () => Promise<CreateOidcClientResult>, object, unknown>;
 /**
  * Factory for the `updateOidcClient` action.
  *
  * Delegates to {@link OidcClientService.updateClient} to apply plaintext field updates.
+ *
+ * @param context - the OIDC model server actions context
+ * @returns a transform function factory for updating OIDC clients
  */
 export declare function updateOidcClientFactory(context: OidcModelServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<UpdateOidcClientParams, (document: OidcEntryDocument) => Promise<OidcEntryDocument>, object, unknown>;
 /**
@@ -52,11 +59,17 @@ export declare function updateOidcClientFactory(context: OidcModelServerActionsC
  *
  * Delegates to {@link OidcClientService.rotateClientSecret} to generate a new secret
  * and return it in plaintext (only returned once).
+ *
+ * @param context - the OIDC model server actions context
+ * @returns a transform function factory for rotating OIDC client secrets
  */
 export declare function rotateOidcClientSecretFactory(context: OidcModelServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<import("@dereekb/firebase").TargetModelParams, (document: OidcEntryDocument) => Promise<RotateOidcClientSecretResult>, object, unknown>;
 /**
  * Factory for the `deleteOidcClient` action.
  *
  * Delegates to {@link OidcClientService.deleteClient}.
+ *
+ * @param context - the OIDC model server actions context
+ * @returns a transform function factory for deleting OIDC clients
  */
 export declare function deleteOidcClientFactory(context: OidcModelServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<import("@dereekb/firebase").TargetModelParams, (document: OidcEntryDocument) => Promise<void>, object, unknown>;

package/oidc/src/lib/model/oidc/oidcmodel.module.d.ts

@@ -3,6 +3,9 @@ import { OidcModelServerActions } from './oidcmodel.action.server';
 import { OidcClientService } from '../../service/oidc.client.service';
 /**
  * Factory that creates an {@link OidcModelServerActions} instance from the injected {@link OidcClientService}.
+ *
+ * @param oidcClientService - the OIDC client service to wire into the server actions
+ * @returns the configured OidcModelServerActions instance
  */
 export declare function oidcModelServerActionsFactory(oidcClientService: OidcClientService): OidcModelServerActions;
 export interface ProvideAppOidcModelMetadataConfig {
@@ -18,6 +21,7 @@ export interface ProvideAppOidcModelMetadataConfig {
  * By default this module exports:
  * - OidcModelServerActions
  *
- * @param config
+ * @param config - the configuration specifying the OIDC module dependency
+ * @returns the NestJS module metadata for the OidcModel module
  */
 export declare function appOidcModelModuleMetadata(config: ProvideAppOidcModelMetadataConfig): ModuleMetadata;

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

@@ -169,7 +169,8 @@ export declare abstract class OidcModuleConfig {
      *
      * Called by {@link oidcModuleConfigFactory} after building the config from environment variables.
      *
+     * @param config - the config object to validate
      * @throws {Error} When any required field (`issuer`, `appInteractionPath`, `appLoginUrlPart`, `appConsentUrlPart`, `jwksServiceConfig`, `jwksKeyConverterConfig`) is missing.
      */
-    static assertValidConfig(config: OidcModuleConfig): void;
+    static assertValidConfig(config: Partial<OidcModuleConfig>): void;
 }

package/oidc/src/lib/oidc.module.d.ts

@@ -65,12 +65,19 @@ export declare const FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE: strin
  * Reads the JWKS encryption secret from `OIDC_JWKS_ENCRYPTION_SECRET`; in test environments,
  * a deterministic fallback is used.
  *
+ * @param configService - the NestJS ConfigService for reading environment variables
+ * @param envService - the Firebase server environment service for app URL and env detection
+ * @returns the constructed OidcModuleConfig
  * @throws {Error} When `appUrl` is missing, lacks an HTTP prefix, or the encryption secret is invalid.
  */
 export declare function oidcModuleConfigFactory(configService: ConfigService, envService: FirebaseServerEnvService): OidcModuleConfig;
 /**
  * Factory that creates {@link OidcServerFirestoreCollections} using the provided Firestore context
  * and JWKS encryption config from {@link OidcModuleConfig}.
+ *
+ * @param firestoreContext - the Firestore context for collection creation
+ * @param oidcModuleConfig - the OIDC module config containing JWKS encryption settings
+ * @returns the configured OidcServerFirestoreCollections
  */
 export declare function oidcFirestoreCollectionsFactory(firestoreContext: FirestoreContext, oidcModuleConfig: OidcModuleConfig): OidcServerFirestoreCollections;
 export interface ProvideAppOidcModuleMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
@@ -94,7 +101,7 @@ export interface ProvideAppOidcModuleMetadataConfig extends Pick<ModuleMetadata,
  * Additionally, the following may be optionally provided:
  * - JwksServiceStorageConfig
  *
- * @param metadataConfig
- * @returns
+ * @param metadataConfig - the configuration for generating the OIDC module metadata
+ * @returns the NestJS module metadata for the OIDC module
  */
 export declare function oidcModuleMetadata(metadataConfig: ProvideAppOidcModuleMetadataConfig): ModuleMetadata;

package/oidc/src/lib/service/oidc.account.service.d.ts

@@ -78,6 +78,8 @@ export declare class OidcAccountServiceUserContext<S extends OidcScope = OidcSco
      *
      * Returns an {@link OidcAccount} compatible with oidc-provider's `findAccount` interface,
      * or `undefined` if the user does not exist in Firebase Auth.
+     *
+     * @returns the OIDC account for this user, or undefined if the user does not exist
      */
     findAccount(): Promise<OidcAccount | undefined>;
 }
@@ -95,10 +97,15 @@ export declare class OidcAccountService<S extends OidcScope = OidcScope, U exten
     constructor(authService: FirebaseServerAuthService<U>, delegate: OidcAccountServiceDelegate<S, U>);
     /**
      * The provider config from the delegate.
+     *
+     * @returns the OIDC provider configuration from the delegate
      */
     get providerConfig(): OidcProviderConfig<S>;
     /**
      * Creates a user context for the given user ID.
+     *
+     * @param uid - the Firebase Auth user ID
+     * @returns a new user context bound to the given user
      */
     userContext(uid: string): OidcAccountServiceUserContext<S, U>;
 }

package/oidc/src/lib/service/oidc.adapter.service.d.ts

@@ -16,5 +16,6 @@ import { type OidcEncryptionService } from './oidc.encryption.service';
  *
  * @param collections - Firestore collection access for adapter entries.
  * @param encryptionService - Encryption service for sensitive payload fields.
+ * @returns an oidc-provider adapter constructor backed by Firestore
  */
 export declare function createAdapterFactory(collections: OidcServerFirestoreCollections, encryptionService: OidcEncryptionService): AdapterConstructor;

package/oidc/src/lib/service/oidc.config.service.d.ts

@@ -95,6 +95,7 @@ export declare class OidcProviderConfigService {
      *
      * @param jwksUri - Optional override for the JWKS URI (e.g., from cloud storage).
      *   Falls back to `{issuer}{routes.jwks}`.
+     * @returns the fully constructed OIDC discovery metadata
      */
     buildDiscoveryMetadata(jwksUri?: string): OidcDiscoveryMetadata;
 }

package/oidc/src/lib/service/oidc.encryption.service.d.ts

@@ -44,10 +44,16 @@ export declare class OidcEncryptionService {
     /**
      * Encrypts sensitive fields in an adapter payload and returns it as a {@link JsonSerializableObject}
      * suitable for storing directly in Firestore.
+     *
+     * @param payload - the adapter payload to encrypt
+     * @returns the encrypted payload as a JSON-serializable object
      */
     encryptAdapterPayload(payload: AdapterPayload): JsonSerializableObject;
     /**
      * Decrypts sensitive fields in a Firestore-stored payload object back to an {@link AdapterPayload}.
+     *
+     * @param payload - the encrypted Firestore-stored payload
+     * @returns the decrypted adapter payload
      */
     decryptAdapterPayload(payload: JsonSerializableObject): AdapterPayload;
 }

package/oidc/src/lib/service/oidc.interaction.service.d.ts

@@ -14,6 +14,10 @@ export declare class OidcInteractionService {
      * Loads the interaction details for a given request/response pair.
      *
      * Requires the oidc-provider interaction cookie to be present on the request.
+     *
+     * @param req - the Express request containing the interaction cookie
+     * @param res - the Express response
+     * @returns the oidc-provider interaction details
      */
     getInteractionDetails(req: Request, res: Response): Promise<Interaction>;
     /**
@@ -23,6 +27,8 @@ export declare class OidcInteractionService {
      * This is necessary when the interaction cookie is scoped to a different path
      * (e.g., the frontend) and is not sent with backend API requests.
      *
+     * @param uid - the interaction UID to look up
+     * @returns the interaction details for the given UID
      * @throws {Error} When the interaction is not found or has expired.
      */
     findInteractionByUid(uid: OidcInteractionUid): Promise<Interaction>;
@@ -32,6 +38,10 @@ export declare class OidcInteractionService {
      * Looks up the interaction directly by UID, applies the result, saves it,
      * and returns the `returnTo` URL for the client to redirect to.
      *
+     * @param uid - the interaction UID to complete
+     * @param result - the interaction results to apply
+     * @param options - optional settings for merging with the last submission
+     * @param options.mergeWithLastSubmission - whether to merge with the last submission (defaults to true)
      * @returns The `returnTo` URL that the client should redirect to.
      */
     finishInteractionByUid(uid: OidcInteractionUid, result: InteractionResults, options?: {
@@ -39,6 +49,11 @@ export declare class OidcInteractionService {
     }): Promise<string>;
     /**
      * Finds an existing grant by ID, or creates a new one.
+     *
+     * @param grantId - the existing grant ID to look up, or undefined to create a new grant
+     * @param accountId - the account ID for creating a new grant
+     * @param clientId - the client ID for creating a new grant
+     * @returns the found or newly created grant
      */
     findOrCreateGrant(grantId: string | undefined, accountId: string, clientId: string): Promise<Grant>;
 }

package/oidc/src/lib/service/oidc.jwks.service.d.ts

@@ -7,9 +7,13 @@ import { OidcServerFirestoreCollections } from '../model/model';
  * Result of {@link JwksService.generateKeyPair}.
  */
 export interface GenerateKeyPairResult {
-    /** The stored Firestore document data (private key is encrypted). */
+    /**
+     * The stored Firestore document data (private key is encrypted).
+     */
     readonly jwksKey: JwksKey;
-    /** The unencrypted private JWK, ready for use as a signing key. */
+    /**
+     * The unencrypted private JWK, ready for use as a signing key.
+     */
     readonly signingKey: JsonWebKeyWithKid;
 }
 export declare abstract class JwksServiceConfig {
@@ -70,10 +74,14 @@ export declare class JwksService {
      *
      * Returns both the stored {@link JwksKey} and the unencrypted private JWK
      * so callers can use the signing key immediately without a decryption round-trip.
+     *
+     * @returns the generated key pair result containing the stored JwksKey and signing key
      */
     generateKeyPair(): Promise<GenerateKeyPairResult>;
     /**
      * Returns the currently active signing key's private JWK.
+     *
+     * @returns the active signing key's private JWK, or undefined if no active key exists
      */
     getActiveSigningKey(): Promise<JsonWebKeyWithKid | undefined>;
     /**
@@ -84,22 +92,30 @@ export declare class JwksService {
      *
      * Returns undefined if storage is not configured or `serveJwksFromStorage` is false.
      * Returns null if an error occured while trying to setup.
+     *
+     * @returns the public URL, or null/undefined if unavailable
      */
     getJwksStoragePublicUrl(): Promise<Maybe<WebsiteUrlWithPrefix>>;
     /**
      * Returns the public JWKS (all non-retired keys) by querying Firestore.
+     *
+     * @returns the public JWKS containing all non-retired signing keys
      */
     getLatestPublicJwks(): Promise<{
         keys: JsonWebKeyWithKid[];
     }>;
     /**
      * Rotates keys: marks the current active key as rotated and generates a new active key.
+     *
+     * @returns the newly generated active JwksKey
      */
     rotateKeys(): Promise<JwksKey>;
     private _initializeKeysAndCloud;
     private _syncKeysToCloud;
     /**
      * Retires rotated keys whose expiresAt has passed.
+     *
+     * @returns the number of keys retired
      */
     retireExpiredKeys(): Promise<number>;
 }

package/oidc/src/lib/service/oidc.service.d.ts

@@ -1,5 +1,4 @@
-import type Provider from 'oidc-provider';
-import { type Configuration } from 'oidc-provider';
+import type { default as Provider, Configuration } from 'oidc-provider';
 import { OidcModuleConfig } from '../oidc.config';
 import { JwksService } from './oidc.jwks.service';
 import { OidcAccountService } from './oidc.account.service';
@@ -24,6 +23,8 @@ export declare class OidcService {
     constructor(config: OidcModuleConfig, providerConfigService: OidcProviderConfigService, jwksService: JwksService, accountService: OidcAccountService, collections: OidcServerFirestoreCollections, encryptionService: OidcEncryptionService);
     /**
      * Returns the oidc-provider instance, initializing it on first access.
+     *
+     * @returns the lazily-initialized oidc-provider instance
      */
     getProvider(): Promise<Provider>;
     /**
@@ -32,7 +33,7 @@ export declare class OidcService {
      * Uses the provider's `AccessToken` model to look up the token and extract
      * the account ID, scope, and client ID.
      *
-     * @param token - The opaque access token string.
+     * @param rawToken - The opaque access token string.
      * @returns The auth context, or `undefined` if the token is invalid or expired.
      */
     verifyAccessToken(rawToken: string): Promise<OidcAuthData | undefined>;
@@ -49,6 +50,9 @@ export declare class OidcService {
      *
      * Does NOT include `adapter`, `findAccount`, or `jwks` — those require async
      * setup and are handled by {@link OidcService}.
+     *
+     * @param cookieKeys - the signing keys for oidc-provider session cookies
+     * @returns the oidc-provider configuration options
      */
     buildProviderConfiguration(cookieKeys: string[]): Configuration;
     private _buildProvider;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.4.0",
+  "version": "13.4.2",
   "exports": {
     "./test": {
       "module": "./test/index.esm.js",
@@ -43,15 +43,15 @@
   "main": "./index.cjs.js",
   "types": "./src/index.d.ts",
   "peerDependencies": {
-    "@dereekb/analytics": "13.4.0",
-    "@dereekb/date": "13.4.0",
-    "@dereekb/dbx-core": "13.4.0",
-    "@dereekb/firebase": "13.4.0",
-    "@dereekb/model": "13.4.0",
-    "@dereekb/nestjs": "13.4.0",
-    "@dereekb/rxjs": "13.4.0",
-    "@dereekb/util": "13.4.0",
-    "@dereekb/zoho": "13.4.0",
+    "@dereekb/analytics": "13.4.2",
+    "@dereekb/date": "13.4.2",
+    "@dereekb/dbx-core": "13.4.2",
+    "@dereekb/firebase": "13.4.2",
+    "@dereekb/model": "13.4.2",
+    "@dereekb/nestjs": "13.4.2",
+    "@dereekb/rxjs": "13.4.2",
+    "@dereekb/util": "13.4.2",
+    "@dereekb/zoho": "13.4.2",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.16",

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

@@ -17,6 +17,7 @@ export interface AuthDataRef<T extends AuthData = AuthData> {
  * including email, phone, and sign-in timestamps.
  *
  * @param token - The decoded ID token from Firebase Admin Auth.
+ * @returns A normalized {@link FirebaseAuthToken} with camelCase fields.
  *
  * @example
  * ```typescript

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

@@ -175,6 +175,8 @@ export declare abstract class AbstractFirebaseServerAuthUserContext<S extends Fi
     loadDetails(): Promise<FirebaseAuthDetails>;
     /**
      * Generates a random numeric string for use as a temporary reset password.
+     *
+     * @returns A random numeric string suitable as a temporary password.
      */
     protected _generateResetPasswordKey(): string;
     beginResetPassword(): Promise<FirebaseServerAuthResetUserPasswordClaims>;
@@ -192,6 +194,7 @@ export declare abstract class AbstractFirebaseServerAuthUserContext<S extends Fi
      *
      * @param roles - The complete set of roles to assign.
      * @param claimsToRetain - Additional claims to merge in alongside the role-derived claims.
+     * @returns Resolves when the claims have been replaced.
      *
      * @example
      * ```typescript
@@ -203,6 +206,9 @@ export declare abstract class AbstractFirebaseServerAuthUserContext<S extends Fi
     /**
      * Converts roles to their corresponding claim keys, filtering out null/undefined entries
      * that represent unrelated claims in the service's {@link FirebaseServerAuthService.claimsForRoles} output.
+     *
+     * @param roles - The roles to convert to claims.
+     * @returns Filtered claims object with only the relevant role-based entries.
      */
     protected _claimsForRolesChange(roles: ArrayOrValue<AuthRole>): Partial<{
         [x: string]: import("@dereekb/util").AuthClaimValue | null;
@@ -322,7 +328,10 @@ export interface FirebaseServerAuthInitializeNewUser<D = unknown> {
      */
     readonly email?: EmailAddress;
     /**
-     * Phone for the new user, if applicable.
+     * Phone for the new user, if applicable. Must be a valid {@link E164PhoneNumber} (e.g. `'+17206620850'`).
+     *
+     * Firebase Auth requires E.164 format. If the value is not valid, {@link FirebaseServerAuthUserBadInputError}
+     * is thrown with code `auth/invalid-phone-number`.
      */
     readonly phone?: E164PhoneNumber;
     /**
@@ -494,6 +503,7 @@ export type UserContextOrUid<U extends FirebaseServerAuthUserContext = FirebaseS
  *
  * @param authService - The auth service to create a context from if needed.
  * @param userContextOrUid - A user context or UID string.
+ * @returns The resolved user context instance.
  *
  * @example
  * ```typescript
@@ -534,6 +544,8 @@ export declare abstract class AbstractFirebaseServerNewUserService<U extends Fir
     loadSetupDetailsForUserContext(userContext: U, config?: FirebaseServerAuthNewUserSendSetupDetailsConfig<D>): Promise<Maybe<FirebaseServerAuthNewUserSetupDetails<U, D>>>;
     /**
      * Records the current timestamp as the last setup content communication date in the user's claims.
+     *
+     * @param details - The user's setup details containing the user context.
      */
     protected updateSetupContentSentTime(details: FirebaseServerAuthNewUserSetupDetails<U, D>): Promise<void>;
     markUserSetupAsComplete(uid: FirebaseAuthUserId): Promise<boolean>;
@@ -542,6 +554,8 @@ export declare abstract class AbstractFirebaseServerNewUserService<U extends Fir
      *
      * Generates a random setup password if none is provided. Override to customize user creation behavior.
      *
+     * @param input - The initialization configuration for the new user.
+     * @returns The created user record and the setup password used.
      * @throws Throws if the Firebase Admin SDK rejects the user creation.
      */
     protected createNewUser(input: FirebaseServerAuthInitializeNewUser<D>): Promise<FirebaseServerAuthCreateNewUserResult>;
@@ -556,6 +570,8 @@ export declare abstract class AbstractFirebaseServerNewUserService<U extends Fir
     protected abstract sendSetupContentToUser(details: FirebaseServerAuthNewUserSetupDetails<U, D>): Promise<void>;
     /**
      * Clears setup-related claims (setup password and last communication date) from the user.
+     *
+     * @param userContext - The user context to clear setup claims from.
      */
     protected updateClaimsToClearUser(userContext: U): Promise<void>;
 }

package/src/lib/auth/auth.service.error.d.ts

@@ -1,4 +1,50 @@
+import { type FirebaseErrorCode } from '@dereekb/firebase';
 import { BaseError } from 'make-error';
+/**
+ * The type of identifier that caused the user-already-exists conflict.
+ */
+export type FirebaseServerAuthUserExistsErrorIdentifierType = 'phone' | 'email';
+/**
+ * Thrown by {@link AbstractFirebaseServerNewUserService.createNewUser} when Firebase Auth rejects
+ * user creation because the provided phone number or email is already associated with another account.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await newUserService.initializeNewUser({ email, phone });
+ * } catch (e) {
+ *   if (e instanceof FirebaseServerAuthUserExistsError && e.identifierType === 'phone') {
+ *     const existingUser = await auth.getUserByPhoneNumber(e.identifierValue);
+ *   }
+ * }
+ * ```
+ */
+export declare class FirebaseServerAuthUserExistsError extends BaseError {
+    readonly code: FirebaseErrorCode;
+    readonly identifierType: FirebaseServerAuthUserExistsErrorIdentifierType;
+    readonly identifierValue: string;
+    constructor(code: FirebaseErrorCode, identifierType: FirebaseServerAuthUserExistsErrorIdentifierType, identifierValue: string);
+}
+/**
+ * Thrown by {@link AbstractFirebaseServerNewUserService.createNewUser} when Firebase Auth rejects
+ * user creation due to invalid input (e.g., a malformed phone number).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await newUserService.initializeNewUser({ email, phone: 'not-e164' });
+ * } catch (e) {
+ *   if (e instanceof FirebaseServerAuthUserBadInputError) {
+ *     console.log(`Bad input (${e.code}): ${e.inputValue}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class FirebaseServerAuthUserBadInputError extends BaseError {
+    readonly code: FirebaseErrorCode;
+    readonly inputValue: string;
+    constructor(code: FirebaseErrorCode, inputValue: string, message?: string);
+}
 /**
  * Thrown by sendSetupDetails() if the user has no setup configuration available, meaning they probably already have accepted their invite or is in an invalid state.
  */

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

@@ -17,6 +17,7 @@ export declare const FIREBASE_SERVER_ENV_TOKEN: InjectionToken;
  * Creates a NestJS provider that binds the given config to the {@link FIREBASE_SERVER_ENV_TOKEN} injection token.
  *
  * @param env - The Firebase server environment configuration.
+ * @returns A NestJS provider binding the config to the {@link FIREBASE_SERVER_ENV_TOKEN} token.
  *
  * @example
  * ```typescript
@@ -31,6 +32,7 @@ export declare function firebaseServerEnvTokenProvider<T extends FirebaseServerE
  * Use this when the NestJS app needs the config accessible via either token.
  *
  * @param env - The Firebase server environment configuration.
+ * @returns An array of providers binding the config to both Firebase and base server env tokens.
  *
  * @example
  * ```typescript

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

@@ -13,18 +13,32 @@ export interface FirebaseServerEnvServiceRef<S extends FirebaseServerEnvService
  * backed by a {@link FirebaseServerEnvironmentConfig}.
  */
 export declare abstract class FirebaseServerEnvService {
-    /** Whether the server is running in a test/CI environment. */
+    /**
+     * Whether the server is running in a test/CI environment.
+     */
     abstract readonly isTestingEnv: boolean;
-    /** Whether the server is running in production. */
+    /**
+     * Whether the server is running in production.
+     */
     abstract readonly isProduction: boolean;
-    /** Whether the server is running in a staging environment. */
+    /**
+     * Whether the server is running in a staging environment.
+     */
     abstract readonly isStaging: boolean;
-    /** Whether developer/debug tools are enabled for this environment. */
+    /**
+     * Whether developer/debug tools are enabled for this environment.
+     */
     abstract readonly developerToolsEnabled: boolean;
-    /** Whether the development scheduler (for cron-like tasks) is enabled. */
+    /**
+     * Whether the development scheduler (for cron-like tasks) is enabled.
+     */
     abstract readonly developmentSchedulerEnabled: boolean;
-    /** The application's public URL, if configured. */
+    /**
+     * The application's public URL, if configured.
+     */
     abstract readonly appUrl: Maybe<string>;
-    /** Parsed URL details for the application URL. */
+    /**
+     * Parsed URL details for the application URL.
+     */
     abstract readonly appUrlDetails: Maybe<WebsiteUrlDetails>;
 }