@dereekb/firebase-server 13.11.18 → 13.12.1

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

@@ -1,14 +1,16 @@
 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.
+ * Controller for OIDC discovery and JWKS endpoints under `/.well-known`.
+ *
+ * The protected-resource discovery doc (`/.well-known/oauth-protected-resource`)
+ * is owned by the protected resource itself (the MCP module's
+ * `McpWellKnownController`), not the authorization server, per RFC 9728.
  */
 export declare class OidcWellKnownController {
-    private readonly config;
     private readonly providerConfigService;
     private readonly jwksService;
-    constructor(config: OidcModuleConfig, providerConfigService: OidcProviderConfigService, jwksService: JwksService);
+    constructor(providerConfigService: OidcProviderConfigService, jwksService: JwksService);
     /**
      * OpenID Connect Discovery endpoint (RFC 8414 / OpenID Connect Discovery 1.0).
      *
@@ -28,15 +30,4 @@ export declare class OidcWellKnownController {
     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.
-     *
-     * @returns The protected resource metadata with authorization server URLs.
-     */
-    getProtectedResource(): {
-        authorization_servers: string[];
-    };
 }

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

@@ -2,6 +2,7 @@ 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';
+import { OidcAuthMiddlewareConfig } from './oauth-auth.module';
 /**
  * NestJS middleware that verifies OAuth bearer tokens issued by our OIDC provider.
  *
@@ -9,13 +10,32 @@ import { type OidcAuthenticatedRequest } from '../service/oidc.auth';
  * verifies it via the provider's AccessToken model, and attaches the
  * auth context to the request as {@link OidcAuthData}.
  *
+ * On 401, emits an RFC 9728 `WWW-Authenticate: Bearer ...` header — including
+ * the `resource_metadata` discovery URL when `OidcAuthMiddlewareConfig.resourceMetadataUrl`
+ * is configured — so OAuth-aware clients (Claude, mcp-inspector, etc.) can
+ * locate the discovery doc explicitly.
+ *
  * Applied to routes via {@link ConfigureOidcAuthMiddlewareModule}.
  *
+ * @example
+ * Wired automatically when `protectedPaths` is set on `oidcModuleMetadata`:
+ * ```ts
+ * oidcModuleMetadata({
+ *   dependencyModule: MyOidcDependencyModule,
+ *   config: {
+ *     protectedPaths: ['/api/model', '/mcp'],
+ *     resourceMetadataUrl: 'https://api.example.com/.well-known/oauth-protected-resource'
+ *   }
+ * })
+ * ```
+ *
  * @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 config;
     private readonly logger;
-    constructor(oidcService: OidcService);
-    use(req: OidcAuthenticatedRequest, _res: Response, next: NextFunction): Promise<void>;
+    constructor(oidcService: OidcService, config: OidcAuthMiddlewareConfig);
+    use(req: OidcAuthenticatedRequest, res: Response, next: NextFunction): Promise<void>;
+    private _setWwwAuthenticate;
 }

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

@@ -6,6 +6,23 @@ import { type SlashPath } from '@dereekb/util';
  * 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
+ * Manual configuration without going through `oidcModuleMetadata`:
+ * ```ts
+ * @Module({
+ *   providers: [
+ *     {
+ *       provide: OidcAuthMiddlewareConfig,
+ *       useValue: {
+ *         protectedPaths: ['/api/model', '/mcp'],
+ *         resourceMetadataUrl: 'https://api.example.com/.well-known/oauth-protected-resource'
+ *       } satisfies OidcAuthMiddlewareConfig
+ *     }
+ *   ]
+ * })
+ * export class MyApiModule {}
+ * ```
  */
 export declare abstract class OidcAuthMiddlewareConfig {
     /**
@@ -16,7 +33,30 @@ export declare abstract class OidcAuthMiddlewareConfig {
      * since those are protected by AppCheck.
      */
     readonly protectedPaths: SlashPath[];
+    /**
+     * Absolute URL of the OAuth 2.0 Protected Resource Metadata document
+     * (RFC 9728). When set, included as the `resource_metadata` parameter
+     * of the `WWW-Authenticate: Bearer` header on 401 responses so OAuth
+     * clients can locate the discovery doc explicitly rather than relying on
+     * origin-rooted path-walkback (which fails when the function isn't
+     * mounted at `/` — e.g. behind the Firebase Functions emulator URL prefix).
+     */
+    readonly resourceMetadataUrl?: string;
 }
+/**
+ * Builds the `WWW-Authenticate: Bearer ...` challenge string emitted on 401
+ * responses to OAuth-protected routes.
+ *
+ * Per RFC 6750 §3 / RFC 7235, auth-params are comma-separated (optionally
+ * with surrounding whitespace). When `resourceMetadataUrl` is provided, it's
+ * included as the RFC 9728 `resource_metadata` hint so clients can locate the
+ * discovery doc directly instead of relying on origin-rooted path-walkback.
+ *
+ * @param error - The RFC 6750 `error` token (e.g. `invalid_token`, `invalid_request`).
+ * @param resourceMetadataUrl - Optional protected-resource metadata URL.
+ * @returns Header value, e.g. `Bearer resource_metadata="…", error="invalid_token"`.
+ */
+export declare function buildBearerChallenge(error: string, resourceMetadataUrl?: string): string;
 /**
  * Applies OAuth bearer token verification as global Express middleware on
  * the given NestJS application.
@@ -39,5 +79,22 @@ export declare abstract class OidcAuthMiddlewareConfig {
  *   }
  * };
  * ```
+ *
+ * Pair with `oidcModuleMetadata` (passing `resourceMetadataUrl` on `config`) so
+ * the 401 emits an RFC 9728 `WWW-Authenticate: Bearer resource_metadata="..."`
+ * header — required when the resource server isn't mounted at the origin root
+ * (e.g. behind the Firebase Functions emulator URL prefix), since RFC 9728's
+ * default path-walkback lands at a 404 in that case.
+ *
+ * @example
+ * ```ts
+ * oidcModuleMetadata({
+ *   dependencyModule: MyOidcDependencyModule,
+ *   config: {
+ *     protectedPaths: ['/api/model', '/mcp'],
+ *     resourceMetadataUrl: 'http://localhost:9902/dereekb-components/us-central1/api/.well-known/oauth-protected-resource'
+ *   }
+ * })
+ * ```
  */
 export declare function applyOidcAuthMiddleware(nestApp: INestApplication): void;

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

@@ -9,6 +9,37 @@ import { type JwksKeyConverterConfig } from './model';
  * Matches the `renderError` option from the oidc-provider `Configuration` type.
  */
 export type OidcRenderErrorFunction = Configuration['renderError'];
+/**
+ * Per-resource configuration returned by `features.resourceIndicators.getResourceServerInfo`
+ * to oidc-provider when a client requests an access token bound to a specific resource
+ * (RFC 8707).
+ *
+ * Shape mirrors oidc-provider's `ResourceServer` documented at
+ * `features.resourceIndicators.getResourceServerInfo` in
+ * `node_modules/oidc-provider/lib/helpers/defaults.js`.
+ */
+export interface OidcResourceServerInfo {
+    /**
+     * Space-delimited scopes valid on this resource server. Issued access tokens
+     * are filtered to the intersection of the client-requested scopes and this
+     * allow-list.
+     */
+    readonly scope: string;
+    /**
+     * `aud` claim placed on tokens bound to this resource. Defaults to the
+     * resource indicator URL when omitted.
+     */
+    readonly audience?: string;
+    /**
+     * Access-token TTL override for this resource (seconds). Falls back to the
+     * provider's `ttl.AccessToken` when omitted.
+     */
+    readonly accessTokenTTL?: number;
+    /**
+     * Access-token format. Defaults to `'opaque'`.
+     */
+    readonly accessTokenFormat?: 'opaque' | 'jwt';
+}
 /**
  * OIDC provider-level configuration for scopes, grant types, response types,
  * and claim mappings. These values drive both the oidc-provider instance and the
@@ -193,6 +224,48 @@ export declare abstract class OidcModuleConfig {
      * since those are typically protected by AppCheck.
      */
     readonly protectedPaths?: SlashPath[];
+    /**
+     * Map of recognized OAuth resource indicator URLs (RFC 8707) to their
+     * {@link OidcResourceServerInfo}. When non-empty, oidc-provider's
+     * `features.resourceIndicators.getResourceServerInfo` is wired to look up
+     * each requested `resource` parameter against this map and reject unknown
+     * resources with `invalid_target`.
+     *
+     * Required for OAuth-aware MCP clients (Claude, mcp-inspector) — they pass
+     * the MCP URL from the protected-resource discovery doc as the `resource`
+     * parameter on `/authorize` and `/token`, and oidc-provider rejects every
+     * such request with `invalid_target` unless that URL is recognized here.
+     *
+     * @example
+     * ```ts
+     * resourceServers: {
+     *   'http://localhost:9902/dereekb-components/us-central1/api/mcp': {
+     *     scope: 'openid profile email offline_access demo model.create model.read model.update model.delete model.query model.invoke',
+     *     audience: 'http://localhost:9902/dereekb-components/us-central1/api/mcp'
+     *   }
+     * }
+     * ```
+     */
+    readonly resourceServers?: Readonly<Record<string, OidcResourceServerInfo>>;
+    /**
+     * Absolute URL of the OAuth 2.0 Protected Resource Metadata document
+     * (RFC 9728) for the resources guarded by {@link protectedPaths}.
+     *
+     * When set, the OIDC bearer middleware emits
+     * `WWW-Authenticate: Bearer resource_metadata="<url>", error="invalid_token"`
+     * on 401 responses, so OAuth-aware clients (Claude, mcp-inspector) can
+     * locate the discovery doc without relying on RFC 9728's origin-rooted
+     * path-walkback rule — which only works when the resource server is
+     * actually mounted at the origin root.
+     *
+     * Typically derived from `appMcpUrl` (or the equivalent protected-resource
+     * URL) — e.g. for `appMcpUrl = https://api.example.com/mcp`, the value is
+     * `https://api.example.com/.well-known/oauth-protected-resource`.
+     *
+     * @example
+     * resourceMetadataUrl: 'http://localhost:9902/dereekb-components/us-central1/api/.well-known/oauth-protected-resource'
+     */
+    readonly resourceMetadataUrl?: string;
     /**
      * Supported token endpoint authentication methods.
      *

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

@@ -74,6 +74,20 @@ export declare const FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE: strin
  * @throws {Error} When `appUrl` is missing, the resolved issuer lacks an HTTP prefix, or the encryption secret is invalid.
  */
 export declare function oidcModuleConfigFactory(configService: ConfigService, envService: FirebaseServerEnvService): OidcModuleConfig;
+/**
+ * Derives the RFC 9728 protected-resource metadata URL from `envService.appMcpUrl`.
+ *
+ * For `appMcpUrl = http://localhost:9902/dereekb-components/us-central1/api/mcp`, this
+ * returns `http://localhost:9902/dereekb-components/us-central1/api/.well-known/oauth-protected-resource` —
+ * i.e. the discovery doc colocated with the MCP endpoint, regardless of any URL prefix
+ * imposed by the runtime (Firebase Functions emulator, Cloud Run path, etc.).
+ *
+ * Returns `undefined` when no `appMcpUrl` is configured.
+ *
+ * @param envService - The Firebase server environment service.
+ * @returns The discovery URL, or `undefined` if `appMcpUrl` is not set.
+ */
+export declare function deriveResourceMetadataUrlFromEnv(envService: FirebaseServerEnvService): string | undefined;
 /**
  * Factory that creates {@link OidcServerFirestoreCollections} using the provided Firestore context
  * and JWKS encryption config from {@link OidcModuleConfig}.
@@ -83,6 +97,11 @@ export declare function oidcModuleConfigFactory(configService: ConfigService, en
  * @returns The configured OidcServerFirestoreCollections.
  */
 export declare function oidcFirestoreCollectionsFactory(firestoreContext: FirestoreContext, oidcModuleConfig: OidcModuleConfig): OidcServerFirestoreCollections;
+/**
+ * Subset of {@link OidcModuleConfig} that consumers may override via
+ * `oidcModuleMetadata`'s `config` or `configFactory`.
+ */
+export type OidcModuleMetadataOverrides = Partial<Pick<OidcModuleConfig, 'issuer' | 'suppressBodyParserWarning' | 'renderError' | 'protectedPaths' | 'appOAuthInteractionPath' | 'appOAuthLoginUrlPart' | 'appOAuthConsentUrlPart' | 'tokenEndpointAuthMethods' | 'registrationEnabled' | 'trustProxy' | 'trustProxyInNonProduction' | 'tokenLifetimes' | 'maxRequestedLoginDuration' | 'minRequestedLoginDuration' | 'defaultRequestedLoginDuration' | 'resourceServers' | 'resourceMetadataUrl'>>;
 export interface ProvideAppOidcModuleMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
     /**
      * Module that exports the required dependencies for this module.
@@ -90,14 +109,37 @@ export interface ProvideAppOidcModuleMetadataConfig extends Pick<ModuleMetadata,
      */
     readonly dependencyModule: Required<ModuleMetadata>['imports']['0'];
     /**
-     * Optional overrides to merge into the {@link OidcModuleConfig} produced by the factory.
+     * Optional static overrides to merge into the {@link OidcModuleConfig} produced by the factory.
      *
      * The `issuer` override is honored verbatim and takes precedence over the factory-derived issuer
      * (which is normally built from `envService.appApiUrl` origin ?? `envService.appUrl`). Pass an
      * explicit `issuer` when the consumer wants a canonical issuer URL that does not match either
      * environment URL — e.g., when serving OIDC behind a non-`/oidc` path or under a vanity host.
+     *
+     * For values that must be derived from runtime services (e.g. `resourceServers` keyed on
+     * `envService.appMcpUrl`), use {@link configFactory} instead. When both are supplied,
+     * `configFactory`'s result is merged on top of `config`.
+     */
+    readonly config?: OidcModuleMetadataOverrides;
+    /**
+     * Optional dynamic overrides that depend on runtime services. Called inside the
+     * `OidcModuleConfig` factory with the resolved {@link FirebaseServerEnvService} and
+     * {@link ConfigService}. Merged on top of {@link config} (so `configFactory` values win).
+     *
+     * Use this when an override field (typically `resourceServers` or `resourceMetadataUrl`)
+     * must be derived from `envService.appMcpUrl` rather than from a value that's stable
+     * at module-import time.
+     *
+     * @example
+     * ```ts
+     * configFactory: (envService) => ({
+     *   resourceServers: envService.appMcpUrl
+     *     ? { [envService.appMcpUrl]: { scope: ALL_SCOPES, audience: envService.appMcpUrl } }
+     *     : undefined
+     * })
+     * ```
      */
-    readonly config?: Partial<Pick<OidcModuleConfig, 'issuer' | 'suppressBodyParserWarning' | 'renderError' | 'protectedPaths' | 'appOAuthInteractionPath' | 'appOAuthLoginUrlPart' | 'appOAuthConsentUrlPart' | 'tokenEndpointAuthMethods' | 'registrationEnabled' | 'trustProxy' | 'trustProxyInNonProduction' | 'tokenLifetimes' | 'maxRequestedLoginDuration' | 'minRequestedLoginDuration' | 'defaultRequestedLoginDuration'>>;
+    readonly configFactory?: (envService: FirebaseServerEnvService, configService: ConfigService) => OidcModuleMetadataOverrides;
 }
 /**
  * Convenience function used to generate ModuleMetadata for an app's OidcModule.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.11.18",
+  "version": "13.12.1",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -15,6 +15,12 @@
       "import": "./mailgun/index.cjs.mjs",
       "default": "./mailgun/index.cjs.js"
     },
+    "./twilio": {
+      "module": "./twilio/index.esm.js",
+      "types": "./twilio/index.d.ts",
+      "import": "./twilio/index.cjs.mjs",
+      "default": "./twilio/index.cjs.js"
+    },
     "./zoho": {
       "module": "./zoho/index.esm.js",
       "types": "./zoho/index.d.ts",
@@ -33,6 +39,12 @@
       "import": "./oidc/index.cjs.mjs",
       "default": "./oidc/index.cjs.js"
     },
+    "./mcp": {
+      "module": "./mcp/index.esm.js",
+      "types": "./mcp/index.d.ts",
+      "import": "./mcp/index.cjs.mjs",
+      "default": "./mcp/index.cjs.js"
+    },
     "./package.json": "./package.json",
     ".": {
       "module": "./index.esm.js",
@@ -44,15 +56,15 @@
   "main": "./index.cjs.js",
   "types": "./src/index.d.ts",
   "peerDependencies": {
-    "@dereekb/analytics": "13.11.18",
-    "@dereekb/date": "13.11.18",
-    "@dereekb/dbx-core": "13.11.18",
-    "@dereekb/firebase": "13.11.18",
-    "@dereekb/model": "13.11.18",
-    "@dereekb/nestjs": "13.11.18",
-    "@dereekb/rxjs": "13.11.18",
-    "@dereekb/util": "13.11.18",
-    "@dereekb/zoho": "13.11.18",
+    "@dereekb/analytics": "13.12.1",
+    "@dereekb/date": "13.12.1",
+    "@dereekb/dbx-core": "13.12.1",
+    "@dereekb/firebase": "13.12.1",
+    "@dereekb/model": "13.12.1",
+    "@dereekb/nestjs": "13.12.1",
+    "@dereekb/rxjs": "13.12.1",
+    "@dereekb/util": "13.12.1",
+    "@dereekb/zoho": "13.12.1",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.19",

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

@@ -180,6 +180,13 @@ export declare abstract class AbstractFirebaseServerAuthUserContext<S extends Fi
      */
     protected _generateResetPasswordKey(): string;
     beginResetPassword(): Promise<FirebaseServerAuthResetUserPasswordClaims>;
+    /**
+     * Returns the TTL (in milliseconds) for newly-generated reset codes. Subclasses may override
+     * to customize expiry.
+     *
+     * @returns The TTL in milliseconds for newly-generated reset codes.
+     */
+    protected _resetCodeExpiresInMs(): Milliseconds;
     loadResetPasswordClaims<T extends FirebaseServerAuthResetUserPasswordClaims = FirebaseServerAuthResetUserPasswordClaims>(): Promise<Maybe<T>>;
     setPassword(password: PasswordString): Promise<admin.auth.UserRecord>;
     updateUser(template: admin.auth.UpdateRequest): Promise<admin.auth.UserRecord>;
@@ -753,11 +760,19 @@ export interface FirebaseServerUserPasswordResetService<D = unknown, U extends F
     completePasswordReset(uid: FirebaseAuthUserId, input: FirebaseServerAuthCompletePasswordResetInput): Promise<admin.auth.UserRecord>;
 }
 /**
- * Default throttle duration (1 hour) between reset content sends to prevent spam.
+ * Default throttle duration (60 seconds) between reset content re-sends to prevent spam while
+ * remaining responsive for legitimate users who didn't receive the first email.
  *
  * Used by {@link AbstractFirebaseServerUserPasswordResetService.sendResetContent} to rate-limit delivery.
  */
 export declare const DEFAULT_RESET_COM_THROTTLE_TIME: number;
+/**
+ * Default lifetime (15 minutes) of a reset code before it expires.
+ *
+ * Used by {@link AbstractFirebaseServerAuthUserContext.beginResetPassword} to set
+ * `resetExpiresAt` in the user's claims.
+ */
+export declare const DEFAULT_RESET_CODE_EXPIRES_IN: number;
 /**
  * Base implementation of {@link FirebaseServerUserPasswordResetService} that handles reset initiation,
  * claims management, throttled reset content delivery, and reset completion.

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

@@ -1,18 +1,32 @@
+import { type Maybe } from '@dereekb/util';
 /**
  * Wraps an async function that uses {@link FirebaseServerUserPasswordResetService} methods,
  * catching password-reset-specific errors and re-throwing them as appropriate {@link HttpsError} instances
  * suitable for returning to clients.
  *
- * Error mapping:
+ * Default mapping (security-hardened — enumeration-safe, for end-user callers):
  * - {@link FirebaseServerAuthPasswordResetInvalidCodeError} → permission-denied (403)
- * - {@link FirebaseServerAuthPasswordResetNoResetConfigError} → bad-request (400)
- * - {@link FirebaseServerAuthPasswordResetThrottleError} → unavailable (503)
- * - {@link FirebaseServerAuthPasswordResetSendOnceError} → bad-request (400)
+ * - {@link FirebaseServerAuthPasswordResetNoResetConfigError} → permission-denied (403), same opaque
+ *   response as InvalidCode so callers cannot distinguish "wrong code" from "no reset active".
+ * - {@link FirebaseServerAuthPasswordResetSendOnceError} → permission-denied (403), same opaque
+ *   response so callers cannot probe whether a reset was already initiated.
+ * - {@link FirebaseServerAuthPasswordResetThrottleError} → unavailable (503) with a generic message
+ *   (no `lastSentAt` is leaked).
+ *
+ * Admin mapping (`isAdmin: true`) — preserves distinct error codes and statuses so an admin
+ * resetting on behalf of another user can see the actual reason. Used when the call originates
+ * from an authenticated admin, where enumeration is not a concern:
+ * - {@link FirebaseServerAuthPasswordResetInvalidCodeError} → permission-denied (403)
+ * - {@link FirebaseServerAuthPasswordResetNoResetConfigError} → bad-request (400), distinct message
+ * - {@link FirebaseServerAuthPasswordResetSendOnceError} → bad-request (400), distinct message
+ * - {@link FirebaseServerAuthPasswordResetThrottleError} → unavailable (503), same as default
  *
  * @param fn - The async function to execute.
+ * @param isAdmin - When `true`, returns distinct error codes/messages instead of the
+ *   enumeration-safe opaque response. Pass the caller's admin status here.
  * @returns The result of the function.
  */
-export declare function catchAndThrowPasswordResetServerErrors<T>(fn: () => Promise<T>): Promise<T>;
+export declare function catchAndThrowPasswordResetServerErrors<T>(fn: () => Promise<T>, isAdmin?: Maybe<boolean>): Promise<T>;
 /**
  * Creates a permission-denied (403) server error for an invalid or expired password reset code.
  *
@@ -22,6 +36,11 @@ export declare function authServicePasswordResetInvalidCodeError(): import("fire
 /**
  * Creates a bad-request (400) server error when no active password reset exists for the user.
  *
+ * Distinct from {@link authServicePasswordResetInvalidCodeError}. Use only when the caller is
+ * trusted (e.g., an admin) and revealing "no reset active" is not an enumeration risk; for
+ * end-user callers, {@link catchAndThrowPasswordResetServerErrors} maps this case to the same
+ * opaque response as `InvalidCodeError`.
+ *
  * @returns An {@link HttpsError} with code `invalid-argument`.
  */
 export declare function authServicePasswordResetNoConfigError(): import("firebase-functions/https").HttpsError;

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

@@ -13,6 +13,22 @@ export interface FirebaseServerEnvironmentConfig extends ServerEnvironmentConfig
      * it from `appUrl + globalApiRoutePrefix`.
      */
     readonly appApiUrl?: Maybe<WebsiteUrlWithPrefix>;
+    /**
+     * The MCP endpoint URL (e.g., 'https://api.example.com/mcp').
+     *
+     * When set, the firebase-server MCP module advertises this URL as the protected
+     * resource in `/.well-known/oauth-protected-resource`, and the OIDC bearer
+     * middleware uses its origin to construct the `WWW-Authenticate`
+     * `resource_metadata` hint on 401 responses.
+     *
+     * Set explicitly when the MCP endpoint lives on a different origin than the
+     * frontend `appUrl` (e.g., dev: behind a different port than the SPA proxy;
+     * prod: a dedicated `api.*` subdomain that bypasses Firebase Hosting).
+     *
+     * When omitted, the MCP module falls back to deriving the URL from
+     * `appApiUrl` (or `appUrl`).
+     */
+    readonly appMcpUrl?: Maybe<WebsiteUrlWithPrefix>;
     /**
      * The webhook URL. When not set explicitly, `buildNestServerRootModule()` computes
      * it from `appUrl + /webhook`.

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

@@ -45,6 +45,15 @@ export declare abstract class FirebaseServerEnvService {
      * The full API URL (e.g., 'https://app.example.com/api').
      */
     abstract readonly appApiUrl: Maybe<WebsiteUrl>;
+    /**
+     * The full MCP endpoint URL (e.g., 'https://api.example.com/mcp').
+     *
+     * When set, advertised verbatim in `/.well-known/oauth-protected-resource` and
+     * used to derive the OIDC bearer middleware's `WWW-Authenticate`
+     * `resource_metadata` hint. When omitted, modules fall back to deriving the
+     * URL from `appApiUrl` / `appUrl`.
+     */
+    abstract readonly appMcpUrl: Maybe<WebsiteUrl>;
     /**
      * The full webhook URL (e.g., 'https://app.example.com/webhook').
      */

package/src/lib/nest/controller/model/model.api.get.service.d.ts

@@ -1,5 +1,5 @@
 import { type Maybe } from '@dereekb/util';
-import { type FirestoreModelKey, type FirestoreModelType } from '@dereekb/firebase';
+import { type FirestoreModelIdentity, type FirestoreModelKey, type FirestoreModelType } from '@dereekb/firebase';
 import { type INestApplicationContext } from '@nestjs/common';
 import { ModelApiDispatchConfig } from './model.api.dispatch';
 import { type FirebaseServerAuthData } from '../auth.context.server';
@@ -29,6 +29,24 @@ export interface ModelAccessReadError {
     readonly message: string;
     readonly code?: string;
 }
+/**
+ * Shape of a single failed-key entry from `useMultipleModels({ throwOnFirstError: false })`.
+ * Exposed so the mapper below stays testable without a live nest context.
+ */
+export interface ModelAccessUseMultipleModelsFailureEntry {
+    readonly key: FirestoreModelKey;
+    readonly error: unknown;
+}
+/**
+ * Maps a single `useMultipleModels` failure entry into the public {@link ModelAccessReadError}
+ * shape. Unwraps the typical Firebase error shapes via {@link firebaseServerErrorInfo} so
+ * permission-denied / not-found errors surface a real message + code instead of the generic
+ * `"Unknown error"` fallback the inline mapping used previously.
+ *
+ * @param entry - A failed-key entry from the underlying multi-read.
+ * @returns A `{ key, message, code? }` triple safe to return to API/MCP callers.
+ */
+export declare function modelAccessReadErrorFromUseMultipleModelsFailure(entry: ModelAccessUseMultipleModelsFailureEntry): ModelAccessReadError;
 /**
  * Service for direct document reads using the `useModel()` permission-checking pattern.
  *
@@ -38,7 +56,23 @@ export interface ModelAccessReadError {
  */
 export declare class ModelApiGetService {
     private readonly _nestContext;
+    private _identityByModelType;
     constructor(config: ModelApiDispatchConfig, nestApplication: INestApplicationContext);
+    /**
+     * Returns the registered {@link FirestoreModelIdentity} for the given `modelType` string, or
+     * `undefined` when no model of that type is registered.
+     *
+     * Identities are read from `firebaseModelsService` and cached on first successful call. The
+     * lookup uses the provided `auth` to build a real model context — `getFirestoreCollection(ctx)`
+     * is context-dependent (calls `ctx.collection(...)` or similar), so a synthetic empty context
+     * is not sufficient.
+     *
+     * @param modelType - The Firestore model type string (e.g., 'guestbook', 'profile').
+     * @param auth - The request's auth data; used to build a context for the (one-time) lookup.
+     * @returns The matching identity or `undefined`.
+     */
+    getModelIdentity(modelType: FirestoreModelType, auth: Maybe<FirebaseServerAuthData>): Maybe<FirestoreModelIdentity>;
+    private _buildIdentityMap;
     /**
      * Reads a single document by model type and key with permission checking.
      *

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

@@ -16,6 +16,7 @@ export declare class DefaultFirebaseServerEnvService extends ServerEnvironmentSe
      */
     get developmentSchedulerEnabled(): boolean;
     get appUrlDetails(): Maybe<WebsiteUrlDetails>;
+    get appMcpUrl(): Maybe<WebsiteUrl>;
     get appWebhookUrl(): Maybe<WebsiteUrl>;
     get isApiEnabled(): boolean;
     get isWebhooksEnabled(): boolean;