@dereekb/firebase-server 14.3.0 → 14.5.0

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

@@ -1,6 +1,6 @@
 import { type ModuleMetadata } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
-import { OidcModuleConfig, type OidcProviderConfig, type OidcResourceServerInfo } from './oidc.config';
+import { OidcModuleConfig } from './oidc.config';
 import { type FirestoreContext } from '@dereekb/firebase';
 import { FirebaseServerEnvService } from '@dereekb/firebase-server';
 import { OidcServerFirestoreCollections } from './model/model';
@@ -88,43 +88,6 @@ export declare function oidcModuleConfigFactory(configService: ConfigService, en
  * @returns The discovery URL, or `undefined` if `appMcpUrl` is not set.
  */
 export declare function deriveResourceMetadataUrlFromEnv(envService: FirebaseServerEnvService): string | undefined;
-/**
- * Input for {@link buildFirebaseServerMcpResourceServer}.
- */
-export interface BuildFirebaseServerMcpResourceServerInput {
-    /**
-     * The Firebase server environment service. The MCP URL is read from `envService.appMcpUrl`.
-     */
-    readonly envService: FirebaseServerEnvService;
-    /**
-     * The OIDC provider config whose scopes back the resource server's `scope` value.
-     */
-    readonly providerConfig: OidcProviderConfig;
-}
-/**
- * Builds a single-entry {@link OidcResourceServerInfo} map for the MCP endpoint
- * declared on `envService.appMcpUrl`, with `scope` set to every scope declared
- * on `providerConfig.claims` (so any scope the provider issues is valid on the
- * resource server) and `audience` set to the MCP URL.
- *
- * Returns `undefined` when no `appMcpUrl` is configured.
- *
- * Used internally by {@link oidcModuleMetadata} when {@link OidcModuleConfig.configureMcpResourceServer}
- * is enabled, and exported for apps that need to combine the MCP resource server
- * with additional app-specific entries:
- *
- * @example
- * ```ts
- * resourceServers: {
- *   ...(buildFirebaseServerMcpResourceServer({ envService, providerConfig: APP_PROVIDER_CONFIG }) ?? {}),
- *   'https://api.example.com/extras': {
- *     scope: 'openid profile',
- *     audience: 'https://api.example.com/extras'
- *   }
- * }
- * ```
- */
-export declare function buildFirebaseServerMcpResourceServer(input: BuildFirebaseServerMcpResourceServerInput): Record<string, OidcResourceServerInfo> | undefined;
 /**
  * Factory that creates {@link OidcServerFirestoreCollections} using the provided Firestore context
  * and JWKS encryption config from {@link OidcModuleConfig}.
@@ -138,7 +101,7 @@ export declare function oidcFirestoreCollectionsFactory(firestoreContext: Firest
  * 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' | 'configureMcpResourceServer' | 'cors'>>;
+export type OidcModuleMetadataOverrides = Partial<Pick<OidcModuleConfig, 'issuer' | 'suppressBodyParserWarning' | 'renderError' | 'protectedPaths' | 'unprotectedPaths' | 'appOAuthInteractionPath' | 'appOAuthLoginUrlPart' | 'appOAuthConsentUrlPart' | 'tokenEndpointAuthMethods' | 'registrationEnabled' | 'trustProxy' | 'trustProxyInNonProduction' | 'tokenLifetimes' | 'maxRequestedLoginDuration' | 'minRequestedLoginDuration' | 'defaultRequestedLoginDuration' | 'resourceServers' | 'resourceMetadataUrl' | 'configureMcpResourceServer' | 'cors'>>;
 export interface ProvideAppOidcModuleMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
     /**
      * Module that exports the required dependencies for this module.

package/oidc/src/lib/oidc.resource-server.d.ts

@@ -0,0 +1,170 @@
+import { type BuildIssuerProfilesConfig, type BuildIssuerProfilesOidcIssuerInput } from '@dereekb/oauth-resource';
+import { type FirebaseServerEnvService } from '@dereekb/firebase-server';
+import { type Maybe, type Seconds, type WebsiteUrlWithPrefix } from '@dereekb/util';
+import { type OidcModuleConfig, type OidcProviderConfig, type OidcResourceServerInfo } from './oidc.config';
+export interface BuildOidcResourceServerConfig {
+    /**
+     * The RFC 8707 resource indicator — the value a client sends as `resource=` on `/authorize` and
+     * `/token`, and the key this entry is registered under. Usually the resource's full URL, e.g.
+     * `https://db.example.com/mcp`.
+     */
+    readonly url: WebsiteUrlWithPrefix;
+    /**
+     * 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, so keep it to what the
+     * resource actually understands rather than every scope the provider issues.
+     */
+    readonly scope: string;
+    /**
+     * `aud` claim placed on tokens bound to this resource. Defaults to {@link url}.
+     *
+     * An OFF-BOX resource server usually wants its ORIGIN here (`https://db.example.com`) rather
+     * than the `/mcp` resource-indicator URL, so one audience covers every route it serves.
+     */
+    readonly audience?: Maybe<string>;
+    /**
+     * Access-token format. Defaults to oidc-provider's `'opaque'`.
+     *
+     * **Set `'jwt'` for any resource server that is not this API process.** An opaque access token is
+     * a database key: it can only be validated by the issuer's own adapter store, so a remote service
+     * fundamentally cannot verify it. A `'jwt'` token is an RS256 JWT signed with the provider's
+     * active JWKS key (no extra provider config needed — `getResourceServerConfig` falls back to
+     * `clientDefaults.id_token_signed_response_alg`, i.e. `RS256`), which any service can verify via
+     * `@dereekb/oauth-resource` against the published `/.well-known/jwks.json`.
+     *
+     * The trade-off: a JWT access token is NOT persisted by oidc-provider, so it has no adapter
+     * record and **cannot be revoked before `exp`**. Revoking the Grant stops refresh and future
+     * issuance but leaves outstanding JWTs valid — keep {@link accessTokenTTL} short.
+     */
+    readonly accessTokenFormat?: Maybe<'opaque' | 'jwt'>;
+    /**
+     * Access-token TTL for this resource, in seconds. Falls back to the provider's `ttl.AccessToken`.
+     */
+    readonly accessTokenTTL?: Maybe<Seconds>;
+}
+/**
+ * Builds a single-entry {@link OidcResourceServerInfo} map for an RFC 8707 resource indicator.
+ *
+ * This is the supported way to declare a resource server the provider issues tokens for —
+ * including one that runs OFF-BOX (a Docker'd sidecar, a worker, a standalone MCP host), which is
+ * what {@link BuildOidcResourceServerConfig.accessTokenFormat} `'jwt'` exists for.
+ *
+ * @param config - The resource indicator, its scopes, and the token shape to issue for it.
+ * @returns A single-entry map keyed by the resource indicator.
+ *
+ * @example
+ * ```ts
+ * const DB_ORIGIN = 'https://db.example.com';
+ *
+ * oidcModuleMetadata({
+ *   dependencyModule: MyOidcDependencyModule,
+ *   config: {
+ *     resourceServers: buildOidcResourceServer({
+ *       url: `${DB_ORIGIN}/mcp`,
+ *       scope: 'openid profile email offline_access',
+ *       audience: DB_ORIGIN,
+ *       accessTokenFormat: 'jwt',
+ *       accessTokenTTL: 3600
+ *     })
+ *   }
+ * })
+ * ```
+ */
+export declare function buildOidcResourceServer(config: BuildOidcResourceServerConfig): Record<string, OidcResourceServerInfo>;
+/**
+ * Input for {@link buildFirebaseServerMcpResourceServer}.
+ */
+export interface BuildFirebaseServerMcpResourceServerInput {
+    /**
+     * The Firebase server environment service. The MCP URL is read from `envService.appMcpUrl`.
+     */
+    readonly envService: FirebaseServerEnvService;
+    /**
+     * The OIDC provider config whose scopes back the resource server's `scope` value.
+     */
+    readonly providerConfig: OidcProviderConfig;
+    /**
+     * Access-token format. Defaults to oidc-provider's `'opaque'`.
+     *
+     * See {@link BuildOidcResourceServerConfig.accessTokenFormat}.
+     */
+    readonly accessTokenFormat?: Maybe<'opaque' | 'jwt'>;
+    /**
+     * Access-token TTL for the MCP resource, in seconds.
+     */
+    readonly accessTokenTTL?: Maybe<Seconds>;
+}
+/**
+ * Builds a single-entry {@link OidcResourceServerInfo} map for the MCP endpoint
+ * declared on `envService.appMcpUrl`, with `scope` set to every scope declared
+ * on `providerConfig.claims` (so any scope the provider issues is valid on the
+ * resource server) and `audience` set to the MCP URL.
+ *
+ * Returns `undefined` when no `appMcpUrl` is configured.
+ *
+ * Used internally by `oidcModuleMetadata` when `OidcModuleConfig.configureMcpResourceServer`
+ * is enabled.
+ *
+ * @param input - The environment service and provider config backing the entry.
+ * @returns The single-entry map, or `undefined` when no MCP URL is configured.
+ *
+ * @deprecated Prefer {@link buildOidcResourceServer}, which takes the URL, scope, audience, and
+ * token format explicitly instead of deriving a fixed shape from the environment.
+ */
+export declare function buildFirebaseServerMcpResourceServer(input: BuildFirebaseServerMcpResourceServerInput): Record<string, OidcResourceServerInfo> | undefined;
+export interface FirebaseServerIssuerProfilesConfig {
+    /**
+     * The provider's own module config. Its `issuer` becomes the trusted OIDC issuer, and every
+     * registered `resourceServers` entry contributes its key and `audience` to the accepted
+     * audience list.
+     */
+    readonly oidcModuleConfig: Pick<OidcModuleConfig, 'issuer' | 'resourceServers'>;
+    /**
+     * Firebase project ids whose ID tokens the resource server also trusts.
+     */
+    readonly firebaseProjectIds?: Maybe<readonly string[]>;
+    /**
+     * Extra audiences to accept beyond the ones derived from `resourceServers` — typically the
+     * resource server's own origin when it is not itself a registered resource indicator.
+     */
+    readonly audiences?: Maybe<readonly string[]>;
+    /**
+     * Overrides how the provider's verification keys are resolved, bypassing discovery. The API
+     * verifying its OWN tokens in-process passes a local key set here rather than making an HTTP
+     * call back to itself.
+     */
+    readonly getKey?: Maybe<Required<Exclude<BuildIssuerProfilesOidcIssuerInput, string>>['getKey']>;
+    /**
+     * `fetch` used for OIDC discovery; injected in specs.
+     */
+    readonly fetch?: Maybe<typeof fetch>;
+}
+/**
+ * Emits the `@dereekb/oauth-resource` {@link BuildIssuerProfilesConfig} for THIS provider, so an
+ * API and the satellite services it issues tokens for cannot drift on issuer / audience strings —
+ * both sides read the same `OidcModuleConfig`.
+ *
+ * The type dependency points `firebase-server → oauth-resource` and never the reverse: the light
+ * verify package must stay installable in a plain Express service with no Firebase, Nest, or
+ * oidc-provider in its install graph.
+ *
+ * @param config - The provider's module config plus any extra trusted projects / audiences.
+ * @returns The issuer-profile config to hand to `buildIssuerProfiles()`.
+ *
+ * @example
+ * ```ts
+ * // inside the API, to hand its satellites a config they cannot get wrong
+ * const profilesConfig = firebaseServerIssuerProfiles({ oidcModuleConfig, firebaseProjectIds: [projectId] });
+ * const profiles = buildIssuerProfiles(profilesConfig);
+ * ```
+ */
+export declare function firebaseServerIssuerProfiles(config: FirebaseServerIssuerProfilesConfig): BuildIssuerProfilesConfig;
+/**
+ * Reads every audience a registered resource-server map can put on an access token: each entry's
+ * key (the resource indicator, which oidc-provider uses as the audience by default) plus its
+ * explicit `audience` when one is configured.
+ *
+ * @param resourceServers - The provider's registered resource servers, if any.
+ * @returns The unique audience values.
+ */
+export declare function oidcResourceServerAudiences(resourceServers: Maybe<Record<string, OidcResourceServerInfo>>): string[];

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

@@ -11,3 +11,5 @@ export * from './oidc.client.service';
 export * from './oidc.interaction.service';
 export * from './oidc.grant';
 export * from './oidc.interaction-policy';
+export * from './oidc.jwt-signing.service';
+export * from './oidc.download-signer';

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

@@ -90,9 +90,14 @@ export declare class OidcProviderConfigService {
      * provider does support those scopes, for the clients holding the profile. This narrower list is
      * for metadata a client treats as a request template — notably an MCP protected-resource
      * document's `scopes_supported`, which dynamic-registration clients (the Claude Code CLI) copy
-     * verbatim onto `/authorize`. An assignment-only scope advertised there ends the flow in
-     * `access_denied`: the consent unlock gate judges the REQUEST, so unlike an admin-only scope
-     * there is no deselect-at-consent way through.
+     * verbatim onto `/authorize`. Defaulting such a document to this narrower list keeps an
+     * unassigned client from requesting a scope it can never be granted.
+     *
+     * A resource MAY still advertise an assignment-only scope deliberately (demo-api does for
+     * `token.cli`, so an MCP connector can ask for it at all). That is not fatal for the clients
+     * lacking the profile: the consent URL builder withholds the scope from them, so it lands in the
+     * submit's `rejected` set and the flow completes without it — the same treatment an admin-only
+     * scope gets for a non-admin.
      */
     readonly clientRequestableScopesSupported: string[];
     /**

package/oidc/src/lib/service/oidc.download-signer.d.ts

@@ -0,0 +1,17 @@
+import { type DownloadTokenSigner } from '@dereekb/firebase-server';
+import { type OidcJwtSigningService } from './oidc.jwt-signing.service';
+/**
+ * Adapts {@link OidcJwtSigningService} to the `@dereekb/firebase-server` {@link DownloadTokenSigner}
+ * interface, so the signed asset-download endpoint can use the OIDC provider's own JWKS without
+ * `@dereekb/firebase-server` taking a dependency on this package.
+ *
+ * Using the provider's JWKS is the point: it is already shared across function instances and already
+ * rotates, so a download capability token needs no new secret to distribute. The `typ` + `aud`
+ * discriminators the download module passes in are what keep such a token from ever being accepted
+ * as an OAuth access token (and vice versa) even though both are signed by the same keys.
+ *
+ * @param signingService - The provider's JWT signing service.
+ * @returns A signer to register under the `DOWNLOAD_TOKEN_SIGNER` injection token.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function oidcDownloadTokenSigner(signingService: OidcJwtSigningService): DownloadTokenSigner;

package/oidc/src/lib/service/oidc.jwt-signing.service.d.ts

@@ -0,0 +1,112 @@
+import { type Maybe, type Milliseconds, type Seconds } from '@dereekb/util';
+import { type JWTPayload } from 'jose';
+import { OidcModuleConfig } from '../oidc.config';
+import { JwksService } from './oidc.jwks.service';
+/**
+ * Default lifetime of a minted JWT, in seconds.
+ */
+export declare const DEFAULT_OIDC_SIGNED_JWT_EXPIRES_IN_SECONDS: Seconds;
+/**
+ * How long the active signing key is cached before it is re-read from the JWKS store.
+ *
+ * A rotation is picked up within this window; rotated keys stay in the public JWKS for 30 days, so
+ * tokens signed with the previous key keep verifying in the meantime.
+ */
+export declare const DEFAULT_OIDC_JWT_SIGNING_KEY_CACHE_MS: Milliseconds;
+/**
+ * Header `typ` for a minted JWT: an RFC 9068 JWT access token, matching the format oidc-provider
+ * uses for the `accessTokenFormat: 'jwt'` resource-server tokens.
+ */
+export declare const DEFAULT_OIDC_SIGNED_JWT_TYP = "at+jwt";
+export interface OidcSignJwtInput {
+    /**
+     * `aud` claim(s) — the resource the token is for, e.g. an off-box service's origin.
+     */
+    readonly audience: string | readonly string[];
+    /**
+     * `sub` claim — the first-party identity of the caller, e.g. `demo-api`.
+     */
+    readonly subject: string;
+    /**
+     * Lifetime in seconds. Defaults to {@link DEFAULT_OIDC_SIGNED_JWT_EXPIRES_IN_SECONDS}.
+     */
+    readonly expiresIn?: Maybe<Seconds>;
+    /**
+     * Extra claims merged onto the payload, e.g. `{ client_id, scope }`.
+     */
+    readonly claims?: Maybe<Record<string, unknown>>;
+    /**
+     * Header `typ`. Defaults to {@link DEFAULT_OIDC_SIGNED_JWT_TYP}.
+     */
+    readonly typ?: Maybe<string>;
+}
+export interface OidcVerifyJwtInput {
+    /**
+     * The compact JWT to verify.
+     */
+    readonly token: string;
+    /**
+     * Required `aud` claim value.
+     */
+    readonly audience: string | readonly string[];
+    /**
+     * Required header `typ`. Pass the SAME discriminator the token was minted with — a first-party JWT
+     * minted for a non-OAuth purpose (e.g. an asset-download capability) is signed by the same JWKS as
+     * the provider's `at+jwt` access tokens, so `typ` + `aud` are what keep the two from being
+     * interchangeable.
+     */
+    readonly typ?: Maybe<string>;
+}
+export interface OidcSignedJwt {
+    readonly token: string;
+    readonly expiresAt: Date;
+    /**
+     * `kid` of the JWKS key that signed the token.
+     */
+    readonly kid: string;
+}
+/**
+ * Signs first-party JWTs with the OIDC provider's active JWKS signing key.
+ *
+ * The result is an RS256 token with `iss` = this provider's issuer, so any resource server that
+ * already trusts the provider's JWKS for OAuth access tokens verifies it with no new secret or
+ * trust anchor: "the API mints a token for the satellite service" is literally "sign with the
+ * active key, `aud` = the satellite's origin". The counterpart on the resource server is
+ * `verifyBearerJwt` from `@dereekb/oauth-resource`, whose `oidc` issuer profile discovers this
+ * provider's `jwks_uri` from its own discovery document.
+ *
+ * Registered and exported by `oidcModuleMetadata`, so a downstream app injects it with no extra
+ * wiring. Pair it with `createCachedTokenProvider` from `@dereekb/util/oidc` to hold a minted
+ * token until it nears expiry instead of re-signing per call.
+ */
+export declare class OidcJwtSigningService {
+    private readonly _jwks;
+    private readonly _config;
+    private _cached;
+    private _verifyKey;
+    constructor(_jwks: JwksService, _config: OidcModuleConfig);
+    /**
+     * Mints a signed JWT.
+     *
+     * @param input - Audience, subject, lifetime, and extra claims.
+     * @returns The compact token, its expiry, and the signing key id.
+     */
+    signJwt(input: OidcSignJwtInput): Promise<OidcSignedJwt>;
+    /**
+     * Verifies a JWT that THIS provider signed, against its own JWKS.
+     *
+     * Enforces `iss` (this provider), `aud`, and — when supplied — the header `typ`. Returns
+     * `undefined` rather than throwing when the token does not verify, so a caller serving an
+     * unauthenticated route can answer with one generic error for every failure mode.
+     *
+     * The counterpart to {@link signJwt}: `verifyAccessToken` deliberately does NOT accept a token
+     * minted with a non-`at+jwt` `typ` and a non-OAuth audience, and this method is how a purpose-built
+     * token proves it is the RIGHT kind.
+     *
+     * @param input - The token, its required audience, and its required `typ`.
+     * @returns The verified payload, or `undefined` when verification fails.
+     */
+    verifyJwt(input: OidcVerifyJwtInput): Promise<Maybe<JWTPayload>>;
+    private _getVerifyKey;
+    private _loadSigningKey;
+}

package/oidc/src/lib/service/oidc.jwt-verify.d.ts

@@ -0,0 +1,37 @@
+import { type IssuerProfiles } from '@dereekb/oauth-resource';
+import { type JWTVerifyGetKey } from 'jose';
+import { type OidcModuleConfig } from '../oidc.config';
+import { type JwksService } from './oidc.jwks.service';
+/**
+ * Builds a jose {@link JWTVerifyGetKey} backed by the provider's OWN published JWKS, read directly
+ * from {@link JwksService} rather than over HTTP.
+ *
+ * An in-process verifier must not `createRemoteJWKSet` against its own `/.well-known/jwks.json`:
+ * that would make every bearer-authenticated request depend on the process being able to reach
+ * itself over the network (which it may not be, behind a load balancer, in a Functions emulator,
+ * or under supertest).
+ *
+ * The key set is cached and re-read only when a token presents a `kid` the cache does not hold —
+ * so a freshly rotated key is picked up on its first use instead of after a fixed TTL.
+ *
+ * @param jwksService - The provider's JWKS service.
+ * @returns The key resolver.
+ */
+export declare function jwksServiceVerifyGetKey(jwksService: JwksService): JWTVerifyGetKey;
+/**
+ * Builds the {@link IssuerProfiles} the provider uses to verify its OWN JWT-format access tokens
+ * in-process.
+ *
+ * A JWT access token is issued for a specific `resource=`, so it carries THAT resource server's
+ * audience — not the API's own identity. The accepted audiences are therefore every registered
+ * `resourceServers` key and audience, plus the issuer itself. The trust decision that implies is
+ * deliberate and narrow: a resource server the user consented to may present the token it was
+ * given back to the API that issued it. Scope enforcement is unchanged and still does the real
+ * authorization work (e.g. the admin-only `session.firestore` consent gate and the endpoint's own
+ * admin predicate).
+ *
+ * @param config - The provider's module config.
+ * @param jwksService - The provider's JWKS service, used for local key resolution.
+ * @returns The issuer profiles, holding exactly this provider.
+ */
+export declare function oidcProviderIssuerProfiles(config: OidcModuleConfig, jwksService: JwksService): IssuerProfiles;

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

@@ -23,6 +23,11 @@ export interface ResolveLoginDurationTier {
      */
     readonly hasServiceScope: boolean;
 }
+/**
+ * Claims a JWT access token carries that the {@link OidcAuthData} shape sets explicitly, and that
+ * are therefore NOT app account claims.
+ */
+export declare const OIDC_JWT_ACCESS_TOKEN_RESERVED_CLAIMS: readonly string[];
 /**
  * Core OIDC service that wraps the oidc-provider instance and exposes
  * typed methods for interaction handling, provider initialization, and JWKS management.
@@ -36,6 +41,7 @@ export declare class OidcService {
     private readonly encryptionService;
     private readonly _logger;
     private readonly _getProvider;
+    private readonly _getIssuerProfiles;
     constructor(config: OidcModuleConfig, providerConfigService: OidcProviderConfigService, jwksService: JwksService, accountService: OidcAccountService, collections: OidcServerFirestoreCollections, encryptionService: OidcEncryptionService);
     /**
      * Returns the oidc-provider instance, initializing it on first access.
@@ -67,15 +73,40 @@ export declare class OidcService {
         dbx_max_session_ttl?: number;
     } | undefined, tier: ResolveLoginDurationTier): number;
     /**
-     * Verifies an opaque access token and returns the {@link OidcAuthData}.
+     * Verifies an access token and returns the {@link OidcAuthData}.
+     *
+     * Two formats are accepted, because oidc-provider issues two:
+     *
+     * - **opaque** (the default) — a database key. Looked up through the provider's `AccessToken`
+     *   model, which reads the Firestore adapter record written at issuance.
+     * - **JWT** (a resource server registered with `accessTokenFormat: 'jwt'`) — verified by
+     *   signature against this provider's own JWKS via `@dereekb/oauth-resource`. A JWT access token
+     *   is deliberately NOT persisted by oidc-provider (`lib/models/formats/jwt.js` returns no
+     *   payload, so `base_model.js` skips the `adapter.upsert`), which means `AccessToken.find()`
+     *   always misses for one and the store lookup alone would 401 every token the provider just
+     *   issued.
      *
-     * Uses the provider's `AccessToken` model to look up the token and extract
-     * the account ID, scope, and client ID.
+     * The same absence of an adapter record is why a JWT access token **cannot be revoked before
+     * `exp`**: {@link revokeGrant} deletes the Grant and every persisted token referencing it, which
+     * stops refresh and future issuance, but an outstanding JWT stays verifiable until it expires.
+     * Keep `accessTokenTTL` short on any resource server that opts into the JWT format.
      *
-     * @param rawToken - The opaque access token string.
+     * @param rawToken - The access token string, opaque or JWT.
      * @returns The auth context, or `undefined` if the token is invalid or expired.
      */
     verifyAccessToken(rawToken: string): Promise<OidcAuthData | undefined>;
+    /**
+     * Verifies a JWT-format access token issued by THIS provider for one of its registered resource
+     * servers, and builds the same {@link OidcAuthData} shape the opaque path produces.
+     *
+     * `sub` is the `accountId` oidc-provider stamped at issuance, which IS the Firebase uid (the
+     * opaque path reads the identical value off `accessToken.accountId`), so no mapping table is
+     * involved.
+     *
+     * @param rawToken - The raw token, which may not be a JWT at all.
+     * @returns The auth context, or `undefined` when the token is not a verifiable JWT from this provider.
+     */
+    private _verifyJwtAccessToken;
     /**
      * Revokes a Grant entry and every grantable token entry that references it.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "14.3.0",
+  "version": "14.5.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -58,17 +58,18 @@
   },
   "peerDependencies": {
     "@cantoo/pdf-lib": ">=2.6.5 <2.11.0",
-    "@dereekb/analytics": "14.3.0",
-    "@dereekb/calcom": "14.3.0",
-    "@dereekb/date": "14.3.0",
-    "@dereekb/dbx-core": "14.3.0",
-    "@dereekb/discord": "14.3.0",
-    "@dereekb/firebase": "14.3.0",
-    "@dereekb/model": "14.3.0",
-    "@dereekb/nestjs": "14.3.0",
-    "@dereekb/rxjs": "14.3.0",
-    "@dereekb/util": "14.3.0",
-    "@dereekb/zoho": "14.3.0",
+    "@dereekb/analytics": "14.5.0",
+    "@dereekb/calcom": "14.5.0",
+    "@dereekb/date": "14.5.0",
+    "@dereekb/dbx-core": "14.5.0",
+    "@dereekb/discord": "14.5.0",
+    "@dereekb/firebase": "14.5.0",
+    "@dereekb/model": "14.5.0",
+    "@dereekb/nestjs": "14.5.0",
+    "@dereekb/oauth-resource": "14.5.0",
+    "@dereekb/rxjs": "14.5.0",
+    "@dereekb/util": "14.5.0",
+    "@dereekb/zoho": "14.5.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.22.0",
     "@modelcontextprotocol/node": "2.0.0",
@@ -85,6 +86,7 @@
     "firebase-admin": "^13.10.0",
     "firebase-functions": "^7.3.2",
     "firebase-functions-test": "3.5.0",
+    "jose": "^6.2.12",
     "jsonwebtoken": "^9.0.3",
     "make-error": "^1.3.6",
     "nanoid": "^6.0.1",