@dereekb/firebase-server 13.2.2 → 13.3.1

package/oidc/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@dereekb/firebase-server/oidc",
+  "version": "13.3.1",
+  "peerDependencies": {
+    "@dereekb/date": "13.3.1",
+    "@dereekb/model": "13.3.1",
+    "@dereekb/nestjs": "13.3.1",
+    "@dereekb/rxjs": "13.3.1",
+    "@dereekb/firebase": "13.3.1",
+    "@dereekb/util": "13.3.1",
+    "@dereekb/zoho": "13.3.1",
+    "oidc-provider": "^9.7.0"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/oidc/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

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

@@ -0,0 +1,3 @@
+export * from './oidc.interaction.controller';
+export * from './oidc.provider.controller';
+export * from './oidc.wellknown.controller';

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

@@ -0,0 +1,54 @@
+import { type Request, type Response } from 'express';
+import { OidcProviderConfigService } from '../service';
+import { type OAuthInteractionConsentRequest, type OAuthInteractionLoginRequest, type OidcInteractionUid } from '@dereekb/firebase';
+import { OidcAccountService } from '../service/oidc.account.service';
+import { OidcInteractionService } from '../service/oidc.interaction.service';
+/**
+ * Controller for OIDC interaction endpoints (login/consent).
+ *
+ * The GET endpoint is accessed via browser redirect from the oidc-provider
+ * and must be excluded from AppCheck middleware.
+ *
+ * The POST endpoints are called by the frontend app. They verify the user's
+ * Firebase Auth ID token and bypass the oidc-provider interaction cookie
+ * (which is scoped to the frontend path set by `interactions.url`).
+ */
+export declare class OidcInteractionController {
+    private readonly oidcInteractionService;
+    private readonly oidcProviderConfigService;
+    private readonly accountService;
+    constructor(oidcInteractionService: OidcInteractionService, oidcProviderConfigService: OidcProviderConfigService, accountService: OidcAccountService);
+    /**
+     * GET /interaction/:uid
+     *
+     * Detects the interaction type and redirects 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>;
+    /**
+     * POST /interaction/:uid/login
+     *
+     * Verifies the Firebase Auth ID token sent by the frontend, extracts the
+     * user's UID, and completes the oidc-provider login interaction.
+     *
+     * @throws {HttpException} 401 when the Firebase ID token is invalid.
+     * @throws {HttpException} 400 when the login interaction cannot be completed.
+     */
+    postLogin(uid: OidcInteractionUid, body: OAuthInteractionLoginRequest, res: Response): Promise<void>;
+    /**
+     * POST /interaction/:uid/consent
+     *
+     * Receives consent decision from frontend. Grants missing OIDC scopes and claims
+     * when approved, or returns `access_denied` when rejected.
+     *
+     * @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.
+     *
+     * @throws {HttpException} 401 when the token is invalid or expired.
+     */
+    private _verifyIdToken;
+}

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

@@ -0,0 +1,18 @@
+import { type Request, type Response } from 'express';
+import { OidcService } from '../service/oidc.service';
+/**
+ * Catch-all controller that proxies requests to the oidc-provider callback.
+ *
+ * Mounted at the issuer path (`/oidc` by default). The oidc-provider instance
+ * handles all core OAuth/OIDC endpoints internally (authorization, token,
+ * userinfo, registration, JWKS, etc.).
+ *
+ * The provider's callback strips the controller prefix from the URL so that
+ * the provider sees paths relative to its issuer (e.g., `/auth` instead of `/oidc/auth`).
+ */
+export declare class OidcProviderController {
+    private readonly oidcService;
+    private _callback;
+    constructor(oidcService: OidcService);
+    handleOidcRequest(req: Request, res: Response): Promise<void>;
+}

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

@@ -0,0 +1,36 @@
+import { JwksService } from '../service/oidc.jwks.service';
+import { OidcModuleConfig } from '../oidc.config';
+import { OidcProviderConfigService, type OidcDiscoveryMetadata } from '../service/oidc.config.service';
+/**
+ * Controller for OAuth/OIDC discovery and metadata endpoints.
+ */
+export declare class OidcWellKnownController {
+    private readonly config;
+    private readonly providerConfigService;
+    private readonly jwksService;
+    constructor(config: OidcModuleConfig, providerConfigService: OidcProviderConfigService, jwksService: JwksService);
+    /**
+     * OpenID Connect Discovery endpoint (RFC 8414 / OpenID Connect Discovery 1.0).
+     *
+     * Returns the provider metadata so clients can auto-discover endpoints,
+     * supported scopes, signing algorithms, etc.
+     */
+    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.
+     */
+    getJwks(): Promise<{
+        keys: import("..").JsonWebKeyWithKid[];
+    }>;
+    /**
+     * OAuth Protected Resource discovery endpoint (RFC 8707).
+     *
+     * Returns the authorization server(s) that protect this resource,
+     * allowing clients to discover which authorization server to use.
+     */
+    getProtectedResource(): {
+        authorization_servers: string[];
+    };
+}

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

@@ -0,0 +1,6 @@
+export * from './middleware';
+export * from './model';
+export * from './oidc.config';
+export * from './controller';
+export * from './oidc.module';
+export * from './service';

package/oidc/src/lib/middleware/index.d.ts

@@ -0,0 +1,3 @@
+export * from './oauth-auth.decorator';
+export * from './oauth-auth.middleware';
+export * from './oauth-auth.module';

package/oidc/src/lib/middleware/oauth-auth.decorator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * NestJS parameter decorator that extracts the {@link OidcAuthData} from the request.
+ *
+ * Returns `undefined` if the middleware has not run or the request is unauthenticated.
+ *
+ * @example
+ * ```ts
+ * @Get('me')
+ * getMe(@OidcAuth() auth: OidcAuthData) {
+ *   return { uid: auth.uid };
+ * }
+ * ```
+ */
+export declare const OidcAuth: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/oidc/src/lib/middleware/oauth-auth.middleware.d.ts

@@ -0,0 +1,21 @@
+import { type NestMiddleware } from '@nestjs/common';
+import { type Response, type NextFunction } from 'express';
+import { OidcService } from '../service/oidc.service';
+import { type OidcAuthenticatedRequest } from '../service/oidc.auth';
+/**
+ * NestJS middleware that verifies OAuth bearer tokens issued by our OIDC provider.
+ *
+ * Extracts `Authorization: Bearer <token>` from the request header,
+ * verifies it via the provider's AccessToken model, and attaches the
+ * auth context to the request as {@link OidcAuthData}.
+ *
+ * Applied to routes via {@link ConfigureOidcAuthMiddlewareModule}.
+ *
+ * @throws {UnauthorizedException} When the Authorization header is missing, malformed, or the token is invalid/expired.
+ */
+export declare class OidcAuthBearerTokenMiddleware implements NestMiddleware {
+    private readonly oidcService;
+    private readonly logger;
+    constructor(oidcService: OidcService);
+    use(req: OidcAuthenticatedRequest, _res: Response, next: NextFunction): Promise<void>;
+}

package/oidc/src/lib/middleware/oauth-auth.module.d.ts

@@ -0,0 +1,50 @@
+import { type MiddlewareConsumer } from '@nestjs/common';
+import { type SlashPath } from '@dereekb/util';
+/**
+ * Configuration for `OidcAuthBearerTokenMiddleware` route protection.
+ *
+ * Works in reverse of `FirebaseAppCheckMiddlewareConfig`: instead of protecting
+ * all routes and ignoring some, this only protects explicitly specified paths.
+ * Routes under the global API prefix (protected by AppCheck) are excluded.
+ *
+ * @example
+ * ```ts
+ * // Provide in your module:
+ * { provide: OidcAuthMiddlewareConfig, useValue: { protectedPaths: ['/mcp'] } }
+ * ```
+ */
+export declare abstract class OidcAuthMiddlewareConfig {
+    /**
+     * Path prefixes that require OAuth bearer token verification.
+     *
+     * Only requests matching one of these prefixes will be checked.
+     * Paths under the global API route prefix should not be included
+     * since those are protected by AppCheck.
+     */
+    readonly protectedPaths: SlashPath[];
+}
+/**
+ * Middleware module that applies OAuth bearer token verification
+ * to paths specified in `OidcAuthMiddlewareConfig`.
+ *
+ * Only protects explicitly listed paths — all other routes pass through.
+ * This is the inverse of `ConfigureFirebaseAppCheckMiddlewareModule`, which
+ * protects everything and ignores specific paths.
+ *
+ * @example
+ * ```ts
+ * @Module({
+ *   imports: [ConfigureOidcAuthMiddlewareModule],
+ *   providers: [
+ *     { provide: OidcAuthMiddlewareConfig, useValue: { protectedPaths: ['/mcp'] } }
+ *   ]
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export declare class ConfigureOidcAuthMiddlewareModule {
+    private readonly config?;
+    private readonly logger;
+    constructor(config?: OidcAuthMiddlewareConfig | undefined);
+    configure(consumer: MiddlewareConsumer): void;
+}

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

@@ -0,0 +1,3 @@
+export * from './jwks';
+export * from './oidc';
+export * from './model';

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

@@ -0,0 +1,3 @@
+export * from './jwks';
+export * from './jwks.id';
+export * from './jwks.query';

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

@@ -0,0 +1,107 @@
+import { type Maybe } from '@dereekb/util';
+import { type GrantedReadRole } from '@dereekb/model';
+import { AbstractFirestoreDocument, type FirestoreCollection, type FirestoreContext, type CollectionReference } from '@dereekb/firebase';
+import { type AES256GCMEncryptionSecretSource } from '@dereekb/nestjs';
+/**
+ * Abstract class providing access to all JWKS-related Firestore collections.
+ *
+ * Implementations provide concrete collection instances wired to a specific {@link FirestoreContext}.
+ */
+export declare abstract class JwksFirestoreCollections {
+    abstract readonly jwksKeyCollection: JwksKeyFirestoreCollection;
+}
+/**
+ * Firestore model identity for {@link JwksKey} documents.
+ *
+ * This is a server-side only model. It has no provisions for client-side access.
+ */
+export declare const jwksKeyIdentity: import("@dereekb/firebase").RootFirestoreModelIdentity<"oidcJwksKey", "oidc_jwks">;
+/**
+ * Lifecycle status of a JWKS signing key.
+ *
+ * - `active` — currently used for signing new tokens
+ * - `rotated` — replaced by a newer key but still valid for verification until expiry
+ * - `retired` — fully expired and excluded from the public JWKS
+ */
+export type JwksKeyStatus = 'active' | 'rotated' | 'retired';
+/**
+ * JWK with a required kid field.
+ */
+export interface JsonWebKeyWithKid extends JsonWebKey {
+    readonly kid: string;
+    readonly kty: string;
+    readonly alg?: string;
+    readonly use?: string;
+}
+/**
+ * Firestore document representing a JWKS signing key.
+ */
+export interface JwksKey {
+    /**
+     * Private key in JWK format, encrypted at rest.
+     */
+    privateKey: string;
+    /**
+     * Public key in JWK format (plain text for JWKS endpoint).
+     */
+    publicKey: JsonWebKeyWithKid;
+    /**
+     * Current lifecycle status.
+     */
+    status: JwksKeyStatus;
+    /**
+     * When this key was created.
+     */
+    createdAt: Date;
+    /**
+     * When this key was rotated (status changed from active to rotated).
+     */
+    rotatedAt?: Maybe<Date>;
+    /**
+     * When tokens signed with this key will all have expired.
+     */
+    expiresAt?: Maybe<Date>;
+}
+/**
+ * Role type for JWKS key documents. Read-only since keys are managed by the {@link JwksService}.
+ */
+export type JwksKeyRoles = GrantedReadRole;
+/**
+ * Firestore document wrapper for {@link JwksKey}.
+ */
+export declare class JwksKeyDocument extends AbstractFirestoreDocument<JwksKey, JwksKeyDocument, typeof jwksKeyIdentity> {
+    get modelIdentity(): import("@dereekb/firebase").RootFirestoreModelIdentity<"oidcJwksKey", "oidc_jwks">;
+}
+/**
+ * Configuration for creating a {@link JwksKey} snapshot converter.
+ */
+export interface JwksKeyConverterConfig {
+    /**
+     * Encryption secret source for the private key field.
+     */
+    readonly encryptionSecret: AES256GCMEncryptionSecretSource;
+}
+/**
+ * Creates a snapshot converter for {@link JwksKey} documents.
+ *
+ * Requires runtime encryption config since the private key field is encrypted at rest.
+ */
+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.
+ */
+export declare function jwksKeyCollectionReference(context: FirestoreContext): CollectionReference<JwksKey>;
+/**
+ * Typed Firestore collection for {@link JwksKey} documents.
+ */
+export type JwksKeyFirestoreCollection = FirestoreCollection<JwksKey, JwksKeyDocument>;
+/**
+ * Configuration for creating a {@link JwksKeyFirestoreCollection}.
+ */
+export interface JwksKeyFirestoreCollectionConfig extends JwksKeyConverterConfig {
+    readonly firestoreContext: FirestoreContext;
+}
+/**
+ * Creates a {@link JwksKeyFirestoreCollection} with encrypted private key field support.
+ */
+export declare function jwksKeyFirestoreCollection(config: JwksKeyFirestoreCollectionConfig): JwksKeyFirestoreCollection;

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

@@ -0,0 +1,9 @@
+import { type FirestoreModelId, type FirestoreModelKey } from '@dereekb/firebase';
+/**
+ * Document ID for a JwksKey. The kid (key identifier) string.
+ */
+export type JwksKeyId = FirestoreModelId;
+/**
+ * Full Firestore model key path for a JwksKey document.
+ */
+export type JwksKeyKey = FirestoreModelKey;

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

@@ -0,0 +1,18 @@
+import { type FirestoreQueryConstraint } from '@dereekb/firebase';
+import { type JwksKeyStatus } from './jwks';
+/**
+ * Query for JwksKey documents with a specific status.
+ */
+export declare function jwksKeysWithStatusQuery(status: JwksKeyStatus): FirestoreQueryConstraint[];
+/**
+ * Query for active JwksKey documents.
+ */
+export declare function activeJwksKeysQuery(): FirestoreQueryConstraint[];
+/**
+ * Query for non-retired JwksKey documents (active + rotated).
+ */
+export declare function nonRetiredJwksKeysQuery(): FirestoreQueryConstraint[];
+/**
+ * Query for rotated JwksKey documents.
+ */
+export declare function rotatedJwksKeysQuery(): FirestoreQueryConstraint[];

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

@@ -0,0 +1,12 @@
+import { type JwksFirestoreCollections, type JwksKeyFirestoreCollection } from './jwks';
+import { type OidcModelFirestoreCollections, type OidcEntryFirestoreCollection } from '@dereekb/firebase';
+/**
+ * Abstract class providing access to all OIDC-related Firestore collections.
+ *
+ * Extends both {@link JwksFirestoreCollections} (server-only JWKS keys) and
+ * {@link OidcModelFirestoreCollections} (shared adapter entries).
+ */
+export declare abstract class OidcServerFirestoreCollections implements JwksFirestoreCollections, OidcModelFirestoreCollections {
+    abstract readonly jwksKeyCollection: JwksKeyFirestoreCollection;
+    abstract readonly oidcEntryCollection: OidcEntryFirestoreCollection;
+}

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

@@ -0,0 +1,2 @@
+export * from './oidcmodel.action.server';
+export * from './oidcmodel.module';

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

@@ -0,0 +1,62 @@
+import { type AsyncFirebaseFunctionCreateAction, type AsyncOidcEntryUpdateAction, type AsyncOidcEntryDeleteAction, type CreateOidcClientParams, type CreateOidcClientResult, type UpdateOidcClientParams, type DeleteOidcClientParams, type RotateOidcClientSecretParams, type RotateOidcClientSecretResult, type OidcEntryDocument } from '@dereekb/firebase';
+import { type FirebaseServerActionsContext } from '@dereekb/firebase-server';
+import { type OidcClientService } from '../../service/oidc.client.service';
+/**
+ * Context providing the OIDC client service and server action utilities needed by OIDC model server actions.
+ */
+export interface OidcModelServerActionsContext extends FirebaseServerActionsContext {
+    /**
+     * Service for managing OIDC client adapter entries.
+     */
+    readonly oidcClientService: OidcClientService;
+}
+/**
+ * Abstract service class defining all server-side OIDC client CRUD actions.
+ *
+ * @see {@link oidcModelServerActions} for the concrete implementation factory.
+ */
+export declare abstract class OidcModelServerActions {
+    abstract createOidcClient(params: CreateOidcClientParams): AsyncFirebaseFunctionCreateAction<CreateOidcClientParams, CreateOidcClientResult>;
+    abstract updateOidcClient(params: UpdateOidcClientParams): AsyncOidcEntryUpdateAction<UpdateOidcClientParams>;
+    abstract rotateOidcClientSecret(params: RotateOidcClientSecretParams): AsyncFirebaseFunctionCreateAction<RotateOidcClientSecretParams, RotateOidcClientSecretResult, OidcEntryDocument>;
+    abstract deleteOidcClient(params: DeleteOidcClientParams): AsyncOidcEntryDeleteAction<DeleteOidcClientParams>;
+}
+/**
+ * Creates a concrete {@link OidcModelServerActions} implementation wired to the provided context.
+ *
+ * @param context - the fully assembled OIDC model server actions context
+ *
+ * @example
+ * ```ts
+ * const actions = oidcModelServerActions(context);
+ * const createFn = await actions.createOidcClient({ client_name: 'My App', redirect_uris: ['...'] });
+ * const result = await createFn();
+ * ```
+ */
+export declare function oidcModelServerActions(context: OidcModelServerActionsContext): OidcModelServerActions;
+/**
+ * Factory for the `createOidcClient` action.
+ *
+ * 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).
+ */
+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.
+ */
+export declare function updateOidcClientFactory(context: OidcModelServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<UpdateOidcClientParams, (document: OidcEntryDocument) => Promise<OidcEntryDocument>, object, unknown>;
+/**
+ * Factory for the `rotateOidcClientSecret` action.
+ *
+ * Delegates to {@link OidcClientService.rotateClientSecret} to generate a new secret
+ * and return it in plaintext (only returned once).
+ */
+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}.
+ */
+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

@@ -0,0 +1,23 @@
+import { type ModuleMetadata } from '@nestjs/common';
+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}.
+ */
+export declare function oidcModelServerActionsFactory(oidcClientService: OidcClientService): OidcModelServerActions;
+export interface ProvideAppOidcModelMetadataConfig {
+    /**
+     * The OidcModule that exports the required OIDC dependencies:
+     * - {@link OidcClientService}
+     */
+    readonly oidcModule: Required<ModuleMetadata>['imports']['0'];
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's OidcModelModule.
+ *
+ * By default this module exports:
+ * - OidcModelServerActions
+ *
+ * @param config
+ */
+export declare function appOidcModelModuleMetadata(config: ProvideAppOidcModelMetadataConfig): ModuleMetadata;