@dereekb/firebase-server 13.4.0 → 13.4.2

package/oidc/index.cjs.js

@@ -177,6 +177,7 @@ function _define_property$f(obj, key, value) {
      *
      * 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.
      */ function assertValidConfig(config) {
                 if (!config.issuer) {
@@ -206,6 +207,9 @@ function _define_property$f(obj, key, value) {
 
 /**
  * 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
  */ function jwksKeysWithStatusQuery(status) {
     return [
         firebase.where('status', '==', status)
@@ -213,11 +217,15 @@ function _define_property$f(obj, key, value) {
 }
 /**
  * Query for active JwksKey documents.
+ *
+ * @returns Firestore query constraints filtering for active keys
  */ function activeJwksKeysQuery() {
     return jwksKeysWithStatusQuery('active');
 }
 /**
  * Query for non-retired JwksKey documents (active + rotated).
+ *
+ * @returns Firestore query constraints filtering for non-retired keys
  */ function nonRetiredJwksKeysQuery() {
     return [
         firebase.where('status', 'in', [
@@ -228,6 +236,8 @@ function _define_property$f(obj, key, value) {
 }
 /**
  * Query for rotated JwksKey documents.
+ *
+ * @returns Firestore query constraints filtering for rotated keys
  */ function rotatedJwksKeysQuery() {
     return jwksKeysWithStatusQuery('rotated');
 }
@@ -539,13 +549,15 @@ exports.JwksService = /*#__PURE__*/ function() {
      *
      * 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
      */ function generateKeyPair() {
                 return _async_to_generator$a(function() {
                     var _generateKeyPairSync, publicKey, privateKey, kid, publicJwk, privateJwk, getKey, encryptedPrivateKey, data, doc;
                     return _ts_generator$a(this, function(_state) {
                         switch(_state.label){
                             case 0:
-                                _generateKeyPairSync = crypto.generateKeyPairSync('rsa', {
+                                /* eslint-disable @typescript-eslint/no-explicit-any -- Node.js crypto types do not include JWK format overloads */ _generateKeyPairSync = crypto.generateKeyPairSync('rsa', {
                                     modulusLength: 2048,
                                     publicKeyEncoding: {
                                         type: 'spki',
@@ -556,7 +568,7 @@ exports.JwksService = /*#__PURE__*/ function() {
                                         format: 'jwk'
                                     }
                                 }), publicKey = _generateKeyPairSync.publicKey, privateKey = _generateKeyPairSync.privateKey;
-                                kid = crypto.randomBytes(16).toString('hex');
+                                /* eslint-enable @typescript-eslint/no-explicit-any */ kid = crypto.randomBytes(16).toString('hex');
                                 publicJwk = _object_spread_props$3(_object_spread$6({}, publicKey), {
                                     kid: kid,
                                     kty: 'RSA',
@@ -600,6 +612,8 @@ exports.JwksService = /*#__PURE__*/ function() {
             key: "getActiveSigningKey",
             value: /**
      * Returns the currently active signing key's private JWK.
+     *
+     * @returns the active signing key's private JWK, or undefined if no active key exists
      */ function getActiveSigningKey() {
                 return _async_to_generator$a(function() {
                     var results, result, data, getKey;
@@ -636,6 +650,8 @@ exports.JwksService = /*#__PURE__*/ function() {
      *
      * 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
      */ function getJwksStoragePublicUrl() {
                 return _async_to_generator$a(function() {
                     return _ts_generator$a(this, function(_state) {
@@ -651,6 +667,8 @@ exports.JwksService = /*#__PURE__*/ function() {
             key: "getLatestPublicJwks",
             value: /**
      * Returns the public JWKS (all non-retired keys) by querying Firestore.
+     *
+     * @returns the public JWKS containing all non-retired signing keys
      */ function getLatestPublicJwks() {
                 return _async_to_generator$a(function() {
                     var keys;
@@ -695,6 +713,8 @@ exports.JwksService = /*#__PURE__*/ function() {
             key: "rotateKeys",
             value: /**
      * Rotates keys: marks the current active key as rotated and generates a new active key.
+     *
+     * @returns the newly generated active JwksKey
      */ function rotateKeys() {
                 return _async_to_generator$a(function() {
                     var now, expiresAt, _ref, newKey;
@@ -873,6 +893,8 @@ exports.JwksService = /*#__PURE__*/ function() {
             key: "retireExpiredKeys",
             value: /**
      * Retires rotated keys whose expiresAt has passed.
+     *
+     * @returns the number of keys retired
      */ function retireExpiredKeys() {
                 return _async_to_generator$a(function() {
                     var now, count;
@@ -1181,6 +1203,8 @@ function _ts_generator$9(thisArg, body) {
      *
      * 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
      */ function findAccount() {
                 return _async_to_generator$9(function() {
                     var authUserContext, exists, delegate;
@@ -1248,6 +1272,8 @@ function _ts_generator$9(thisArg, body) {
             key: "providerConfig",
             get: /**
      * The provider config from the delegate.
+     *
+     * @returns the OIDC provider configuration from the delegate
      */ function get() {
                 return this.delegate.providerConfig;
             }
@@ -1255,6 +1281,9 @@ function _ts_generator$9(thisArg, body) {
         {
             /**
      * 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
      */ key: "userContext",
             value: function userContext(uid) {
                 return new OidcAccountServiceUserContext(this, uid);
@@ -1373,6 +1402,9 @@ function _is_native_reflect_construct() {
  * 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
  */ function jwksKeyConverter(config) {
     return firebase.snapshotConverterFunctions({
         fields: {
@@ -1395,11 +1427,17 @@ function _is_native_reflect_construct() {
 // MARK: Collection
 /**
  * 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
  */ function jwksKeyCollectionReference(context) {
     return context.collection(jwksKeyIdentity.collectionName);
 }
 /**
  * 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
  */ function jwksKeyFirestoreCollection(config) {
     var firestoreContext = config.firestoreContext;
     return firestoreContext.firestoreCollection({
@@ -1558,6 +1596,7 @@ function _ts_generator$8(thisArg, body) {
  * 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
@@ -1579,6 +1618,9 @@ function _ts_generator$8(thisArg, body) {
  *
  * 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
  */ function createOidcClientFactory(context) {
     var oidcClientService = context.oidcClientService, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     return firebaseServerActionTransformFunctionFactory(firebase.createOidcClientParamsType, function(params) {
@@ -1605,6 +1647,9 @@ function _ts_generator$8(thisArg, body) {
  * 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
  */ function updateOidcClientFactory(context) {
     var oidcClientService = context.oidcClientService, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     return firebaseServerActionTransformFunctionFactory(firebase.updateOidcClientParamsType, function(params) {
@@ -1641,6 +1686,9 @@ function _ts_generator$8(thisArg, body) {
  *
  * 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
  */ function rotateOidcClientSecretFactory(context) {
     var oidcClientService = context.oidcClientService, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     return firebaseServerActionTransformFunctionFactory(firebase.rotateOidcClientSecretParamsType, function(_params) {
@@ -1667,9 +1715,12 @@ function _ts_generator$8(thisArg, body) {
  * 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
  */ function deleteOidcClientFactory(context) {
     var oidcClientService = context.oidcClientService, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
-    return firebaseServerActionTransformFunctionFactory(firebase.deleteOidcClientParamsType, function(params) {
+    return firebaseServerActionTransformFunctionFactory(firebase.deleteOidcClientParamsType, function(_params) {
         return _async_to_generator$8(function() {
             return _ts_generator$8(this, function(_state) {
                 return [
@@ -1929,6 +1980,7 @@ function _ts_generator$7(thisArg, body) {
                                 ];
                             case 1:
                                 provider = _state.sent();
+                                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- oidc-provider Client has static methods not exposed in types
                                 ProviderClient = provider.Client;
                                 // Mirrors oidc-provider's default idFactory from lib/helpers/defaults.js
                                 clientId = nanoid.nanoid();
@@ -1990,7 +2042,7 @@ function _ts_generator$7(thisArg, body) {
                                     {
                                         modelKeys: firebase.firestoreModelKey(firebase.oidcEntryIdentity, clientId),
                                         client_id: clientId,
-                                        client_secret: clientSecret
+                                        client_secret: clientSecret !== null && clientSecret !== void 0 ? clientSecret : ''
                                     }
                                 ];
                         }
@@ -2013,7 +2065,7 @@ function _ts_generator$7(thisArg, body) {
      * @throws When the client is not found.
      */ function updateClient(clientId, params) {
                 return _async_to_generator$7(function() {
-                    var provider, ProviderClient, existing, updatedMetadata, client;
+                    var provider, ProviderClient, existing, updatedMetadata, _params_logo_uri, _params_client_uri, client;
                     return _ts_generator$7(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -2023,6 +2075,7 @@ function _ts_generator$7(thisArg, body) {
                                 ];
                             case 1:
                                 provider = _state.sent();
+                                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- oidc-provider Client has static methods not exposed in types
                                 ProviderClient = provider.Client;
                                 return [
                                     4,
@@ -2034,17 +2087,13 @@ function _ts_generator$7(thisArg, body) {
                                     throw new Error('Client not found.');
                                 }
                                 updatedMetadata = _object_spread$5({}, existing);
-                                if (params.client_name !== undefined && params.client_name !== null) {
-                                    updatedMetadata.client_name = params.client_name;
-                                }
-                                if (params.redirect_uris !== undefined && params.redirect_uris !== null) {
-                                    updatedMetadata.redirect_uris = params.redirect_uris;
-                                }
+                                updatedMetadata.client_name = params.client_name;
+                                updatedMetadata.redirect_uris = params.redirect_uris;
                                 if (params.logo_uri !== undefined) {
-                                    updatedMetadata.logo_uri = params.logo_uri || undefined;
+                                    updatedMetadata.logo_uri = (_params_logo_uri = params.logo_uri) !== null && _params_logo_uri !== void 0 ? _params_logo_uri : undefined;
                                 }
                                 if (params.client_uri !== undefined) {
-                                    updatedMetadata.client_uri = params.client_uri || undefined;
+                                    updatedMetadata.client_uri = (_params_client_uri = params.client_uri) !== null && _params_client_uri !== void 0 ? _params_client_uri : undefined;
                                 }
                                 // Mirrors oidc-provider's lib/helpers/add_client.js: re-validates and persists.
                                 return [
@@ -2091,6 +2140,7 @@ function _ts_generator$7(thisArg, body) {
                                 ];
                             case 1:
                                 provider = _state.sent();
+                                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- oidc-provider Client has static methods not exposed in types
                                 ProviderClient = provider.Client;
                                 return [
                                     4,
@@ -2150,6 +2200,7 @@ function _ts_generator$7(thisArg, body) {
                                 ];
                             case 1:
                                 provider = _state.sent();
+                                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- oidc-provider Client has static methods not exposed in types
                                 ProviderClient = provider.Client;
                                 return [
                                     4,
@@ -2229,6 +2280,9 @@ function _object_spread_props$1(target, source) {
 // MARK: Provider Factories
 /**
  * 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
  */ function oidcModelServerActionsFactory(oidcClientService) {
     var context = _object_spread_props$1(_object_spread$4({}, firebaseServer.firebaseServerActionsContext()), {
         oidcClientService: oidcClientService
@@ -2241,7 +2295,8 @@ function _object_spread_props$1(target, source) {
  * 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
  */ function appOidcModelModuleMetadata(config) {
     var oidcModule = config.oidcModule;
     return {
@@ -2469,6 +2524,7 @@ function _ts_generator$6(thisArg, body) {
  *
  * @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
  */ function createAdapterFactory(collections, encryptionService) {
     var FirestoreAdapter = /*#__PURE__*/ function() {
         function FirestoreAdapter(name) {
@@ -2536,7 +2592,7 @@ function _ts_generator$6(thisArg, body) {
                                     data = snapshot.data();
                                     return [
                                         2,
-                                        data && data.type === this.name ? this._toPayload(data) : undefined
+                                        (data === null || data === void 0 ? void 0 : data.type) === this.name ? this._toPayload(data) : undefined
                                     ];
                             }
                         });
@@ -2702,6 +2758,9 @@ function _ts_generator$6(thisArg, body) {
                 /**
          * Converts a Firestore document into an oidc-provider payload,
          * returning `undefined` if the entry has expired.
+         *
+         * @param data - the Firestore document data to convert
+         * @returns the decrypted adapter payload, or undefined if the entry has expired
          */ key: "_toPayload",
                 value: function _toPayload(data) {
                     var expiresDate = data.expiresAt ? _instanceof$1(data.expiresAt, Date) ? data.expiresAt : data.expiresAt.toDate() : undefined;
@@ -2805,6 +2864,9 @@ function _unsupported_iterable_to_array$5(o, minLen) {
             /**
      * 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
      */ key: "encryptAdapterPayload",
             value: function encryptAdapterPayload(payload) {
                 var filtered = util.filterUndefinedValues(payload);
@@ -2814,8 +2876,12 @@ function _unsupported_iterable_to_array$5(o, minLen) {
         {
             /**
      * 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
      */ key: "decryptAdapterPayload",
             value: function decryptAdapterPayload(payload) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 return this.adapterPayloadEncryptor.decrypt(payload);
             }
         }
@@ -2977,6 +3043,7 @@ var DEFAULT_OIDC_CODE_CHALLENGE_METHODS = [
      *
      * @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
      */ key: "buildDiscoveryMetadata",
             value: function buildDiscoveryMetadata(jwksUri) {
                 var issuer = this.config.issuer;
@@ -3259,6 +3326,8 @@ function _ts_generator$5(thisArg, body) {
         {
             /**
      * Returns the oidc-provider instance, initializing it on first access.
+     *
+     * @returns the lazily-initialized oidc-provider instance
      */ key: "getProvider",
             value: function getProvider() {
                 return this._getProvider();
@@ -3273,11 +3342,11 @@ function _ts_generator$5(thisArg, body) {
      * 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.
      */ function verifyAccessToken(rawToken) {
                 return _async_to_generator$5(function() {
-                    var _firstValue, _accessToken_exp, provider, accessToken, token;
+                    var _accessToken_exp, provider, accessToken, token;
                     return _ts_generator$5(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -3301,7 +3370,7 @@ function _ts_generator$5(thisArg, body) {
                                 }
                                 token = {
                                     // Standard JWT claims — sourced from the access token
-                                    aud: (_firstValue = util.firstValue(accessToken.aud)) !== null && _firstValue !== void 0 ? _firstValue : accessToken.clientId,
+                                    aud: util.firstValue(accessToken.aud),
                                     iss: this.config.issuer,
                                     sub: accessToken.accountId,
                                     iat: accessToken.iat,
@@ -3355,6 +3424,7 @@ function _ts_generator$5(thisArg, body) {
                                 ];
                             case 1:
                                 provider = _state.sent();
+                                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- oidc-provider Client has static methods not exposed in types
                                 ProviderClient = provider.Client;
                                 return [
                                     4,
@@ -3391,6 +3461,9 @@ function _ts_generator$5(thisArg, body) {
      *
      * 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
      */ key: "buildProviderConfiguration",
             value: function buildProviderConfiguration(cookieKeys) {
                 var _this = this;
@@ -3429,7 +3502,7 @@ function _ts_generator$5(thisArg, body) {
                     interactions: {
                         url: function url(_ctx, interaction) {
                             return _async_to_generator$5(function() {
-                                var baseUrl, client_id, paramsToEncode, client, scopes, interactionLoginDetails, paramsString, redirectUrl;
+                                var baseUrl, client_id, paramsToEncode, client, scopes, interactionLoginDetails, paramsString;
                                 return _ts_generator$5(this, function(_state) {
                                     switch(_state.label){
                                         case 0:
@@ -3471,10 +3544,9 @@ function _ts_generator$5(thisArg, body) {
                                             paramsString = fetch.makeUrlSearchParamsString(paramsToEncode, {
                                                 useUrlSearchSpaceHandling: true
                                             });
-                                            redirectUrl = "".concat(baseUrl, "?").concat(paramsString);
                                             return [
                                                 2,
-                                                redirectUrl
+                                                "".concat(baseUrl, "?").concat(paramsString)
                                             ];
                                     }
                                 });
@@ -3538,7 +3610,9 @@ function _ts_generator$5(thisArg, body) {
                                 _ref = _state.sent(), ProviderClass = _ref.default;
                                 provider = new ProviderClass(config.issuer, _object_spread_props(_object_spread$2({}, providerConfiguration), {
                                     adapter: adapterFactory,
+                                    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- oidc-provider findAccount signature is more specific than our wrapper
                                     findAccount: findAccount,
+                                    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- oidc-provider expects JOSE JWK type which differs from Node.js JsonWebKey
                                     jwks: {
                                         keys: [
                                             signingKey
@@ -3762,7 +3836,7 @@ function _ts_generator$4(thisArg, body) {
                         switch(_state.label){
                             case 0:
                                 authHeader = req.headers.authorization;
-                                if (!authHeader || !authHeader.startsWith('Bearer ')) {
+                                if (!(authHeader === null || authHeader === void 0 ? void 0 : authHeader.startsWith('Bearer '))) {
                                     throw new common.UnauthorizedException('Missing or invalid Authorization header');
                                 }
                                 token = authHeader.slice(7);
@@ -4136,6 +4210,10 @@ function _ts_generator$3(thisArg, body) {
      * 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
      */ function getInteractionDetails(req, res) {
                 return _async_to_generator$3(function() {
                     var provider;
@@ -4166,6 +4244,8 @@ function _ts_generator$3(thisArg, body) {
      * 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.
      */ function findInteractionByUid(uid) {
                 return _async_to_generator$3(function() {
@@ -4205,6 +4285,10 @@ function _ts_generator$3(thisArg, body) {
      * 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.
      */ function finishInteractionByUid(uid, result, options) {
                 return _async_to_generator$3(function() {
@@ -4243,9 +4327,14 @@ function _ts_generator$3(thisArg, body) {
             key: "findOrCreateGrant",
             value: /**
      * 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
      */ function findOrCreateGrant(grantId, accountId, clientId) {
                 return _async_to_generator$3(function() {
-                    var provider, grant;
+                    var provider, grant, found;
                     return _ts_generator$3(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -4264,7 +4353,11 @@ function _ts_generator$3(thisArg, body) {
                                     provider.Grant.find(grantId)
                                 ];
                             case 2:
-                                grant = _state.sent();
+                                found = _state.sent();
+                                if (!found) {
+                                    throw new Error("Grant not found for grantId: ".concat(grantId));
+                                }
+                                grant = found;
                                 return [
                                     3,
                                     4
@@ -4527,6 +4620,10 @@ function _ts_generator$2(thisArg, body) {
      *
      * 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.
      */ function getInteraction(uid, req, res) {
                 return _async_to_generator$2(function() {
@@ -4577,6 +4674,9 @@ function _ts_generator$2(thisArg, body) {
      * 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.
      */ function postLogin(uid, body, res) {
@@ -4638,10 +4738,13 @@ function _ts_generator$2(thisArg, body) {
      * 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.
      */ function postConsent(uid, body, res) {
                 return _async_to_generator$2(function() {
-                    var _ref, _prompt_details, _prompt_details1, _prompt_details2, redirectTo, interaction, prompt, params, session, grant, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, _step_value, indicator, scopes, grantId, redirectTo1;
+                    var _ref, redirectTo, interaction, prompt, params, session, grant, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, _step_value, indicator, scopes, grantId, redirectTo1;
                     return _ts_generator$2(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -4694,13 +4797,13 @@ function _ts_generator$2(thisArg, body) {
                                 ];
                             case 6:
                                 grant = _state.sent();
-                                if ((_prompt_details = prompt.details) === null || _prompt_details === void 0 ? void 0 : _prompt_details.missingOIDCScope) {
+                                if (prompt.details.missingOIDCScope) {
                                     grant.addOIDCScope(prompt.details.missingOIDCScope.join(' '));
                                 }
-                                if ((_prompt_details1 = prompt.details) === null || _prompt_details1 === void 0 ? void 0 : _prompt_details1.missingOIDCClaims) {
+                                if (prompt.details.missingOIDCClaims) {
                                     grant.addOIDCClaims(prompt.details.missingOIDCClaims);
                                 }
-                                if ((_prompt_details2 = prompt.details) === null || _prompt_details2 === void 0 ? void 0 : _prompt_details2.missingResourceScopes) {
+                                if (prompt.details.missingResourceScopes) {
                                     _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
                                     try {
                                         for(_iterator = Object.entries(prompt.details.missingResourceScopes)[Symbol.iterator](); !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
@@ -4765,6 +4868,8 @@ function _ts_generator$2(thisArg, body) {
             /**
      * 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.
      */ function _verifyIdToken(idToken) {
                 return _async_to_generator$2(function() {
@@ -5228,6 +5333,8 @@ function _ts_generator(thisArg, body) {
      *
      * Returns the provider metadata so clients can auto-discover endpoints,
      * supported scopes, signing algorithms, etc.
+     *
+     * @returns the OIDC discovery metadata document
      */ function getOpenIdConfiguration() {
                 return _async_to_generator(function() {
                     var _ref, jwksUri;
@@ -5255,6 +5362,8 @@ function _ts_generator(thisArg, body) {
      * 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
      */ function getJwks() {
                 return _async_to_generator(function() {
                     return _ts_generator(this, function(_state) {
@@ -5272,6 +5381,8 @@ function _ts_generator(thisArg, body) {
      *
      * 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
      */ key: "getProtectedResource",
             value: function getProtectedResource() {
                 return {
@@ -5414,6 +5525,9 @@ function _unsupported_iterable_to_array(o, minLen) {
  * 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.
  */ function oidcModuleConfigFactory(configService, envService) {
     var _configService_get;
@@ -5453,6 +5567,10 @@ function _unsupported_iterable_to_array(o, minLen) {
 /**
  * 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
  */ function oidcFirestoreCollectionsFactory(firestoreContext, oidcModuleConfig) {
     return {
         jwksKeyCollection: jwksKeyFirestoreCollection(_object_spread({
@@ -5473,13 +5591,13 @@ function _unsupported_iterable_to_array(o, minLen) {
  * 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
  */ function oidcModuleMetadata(metadataConfig) {
     var dependencyModule = metadataConfig.dependencyModule, config$1 = metadataConfig.config, imports = metadataConfig.imports, exports$1 = metadataConfig.exports, providers = metadataConfig.providers;
-    var dependencyModuleImport = dependencyModule ? [
+    var dependencyModuleImport = [
         dependencyModule
-    ] : [];
+    ];
     return {
         imports: [
             config.ConfigModule,