@dereekb/firebase-server 14.2.0 → 14.4.0

package/oidc/package.json

@@ -1,22 +1,24 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "14.2.0",
+  "version": "14.4.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.2.0",
-    "@dereekb/date": "14.2.0",
-    "@dereekb/firebase": "14.2.0",
-    "@dereekb/firebase-server": "14.2.0",
-    "@dereekb/model": "14.2.0",
-    "@dereekb/nestjs": "14.2.0",
-    "@dereekb/rxjs": "14.2.0",
-    "@dereekb/util": "14.2.0",
-    "@dereekb/zoho": "14.2.0",
+    "@dereekb/analytics": "14.4.0",
+    "@dereekb/date": "14.4.0",
+    "@dereekb/firebase": "14.4.0",
+    "@dereekb/firebase-server": "14.4.0",
+    "@dereekb/model": "14.4.0",
+    "@dereekb/nestjs": "14.4.0",
+    "@dereekb/oauth-resource": "14.4.0",
+    "@dereekb/rxjs": "14.4.0",
+    "@dereekb/util": "14.4.0",
+    "@dereekb/zoho": "14.4.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "express": "^5.2.1",
     "firebase-admin": "^13.10.0",
+    "jose": "^6.2.12",
     "nanoid": "^6.0.1",
     "oidc-provider": "^9.8.2"
   },

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

@@ -86,7 +86,9 @@ export interface ResolveEffectiveSubsetInput {
      */
     readonly alwaysGranted?: readonly string[];
     /**
-     * Entries the existing Grant has previously granted or rejected. Tolerated as no-ops on re-consent.
+     * Entries the existing Grant has already decided and this consent leaves as-is. Tolerated as no-ops on
+     * re-consent. A previously-rejected entry the request names again belongs in `missing` instead — see
+     * `reconsiderRejectedValues` — or it can never be granted on that Grant.
      */
     readonly alreadyEncountered?: readonly string[];
 }

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

@@ -3,5 +3,6 @@ export * from './model';
 export * from './oidc.config';
 export * from './controller';
 export * from './oidc.module';
+export * from './oidc.resource-server';
 export * from './profile';
 export * from './service';

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

@@ -52,6 +52,9 @@ export declare abstract class OidcAuthMiddlewareConfig {
  * included as the RFC 9728 `resource_metadata` hint so clients can locate the
  * discovery doc directly instead of relying on origin-rooted path-walkback.
  *
+ * Delegates to `@dereekb/oauth-resource`'s builder so the challenge an off-box resource server
+ * emits and the one this API emits are produced by the same code.
+ *
  * @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"`.

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}.

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

@@ -9,4 +9,6 @@ export * from './oidc.jwks.service';
 export * from './oidc.config.service';
 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';

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

@@ -0,0 +1,103 @@
+import { type Grant } from 'oidc-provider';
+/**
+ * Removes previously-rejected OIDC scopes from a Grant's rejected set.
+ *
+ * oidc-provider exposes `rejectOIDCScope()` but no inverse, and a rejected scope is subtracted from
+ * `getOIDCScope()` on every read — so `addOIDCScope()` alone cannot put a once-rejected scope back in
+ * force. `rejected` is plain persisted data (`Pick<Grant, 'openid' | 'resources'>`), which is what
+ * makes editing it directly the supported shape of an un-reject.
+ *
+ * @param grant - The grant to edit in place.
+ * @param scopes - The scopes to un-reject. Scopes not currently rejected are ignored.
+ */
+export declare function unrejectOIDCScopes(grant: Grant, scopes: Iterable<string>): void;
+/**
+ * Removes previously-rejected OIDC claims from a Grant's rejected set.
+ *
+ * @param grant - The grant to edit in place.
+ * @param claims - The claims to un-reject. Claims not currently rejected are ignored.
+ * @see unrejectOIDCScopes
+ */
+export declare function unrejectOIDCClaims(grant: Grant, claims: Iterable<string>): void;
+/**
+ * Removes previously-rejected resource scopes for one resource indicator from a Grant's rejected set.
+ *
+ * @param grant - The grant to edit in place.
+ * @param resource - The resource indicator.
+ * @param scopes - The scopes to un-reject. Scopes not currently rejected for the resource are ignored.
+ * @see unrejectOIDCScopes
+ */
+export declare function unrejectResourceScopes(grant: Grant, resource: string, scopes: Iterable<string>): void;
+/**
+ * Input for {@link reconsiderRejectedValues}.
+ */
+export interface ReconsiderRejectedValuesInput {
+    /**
+     * Values oidc-provider reports as still undecided for this consent (e.g. `prompt.details.missingOIDCScope`).
+     */
+    readonly missing: readonly string[];
+    /**
+     * Values the existing Grant has already decided — granted or rejected.
+     */
+    readonly encountered: readonly string[];
+    /**
+     * The subset of `encountered` the existing Grant has REJECTED.
+     */
+    readonly rejected: readonly string[];
+    /**
+     * Values the current authorization request asks for. Only a rejected value the request names again is
+     * reconsidered; a rejection from an earlier, wider request stays in force.
+     */
+    readonly requested: ReadonlySet<string>;
+}
+/**
+ * Output of {@link reconsiderRejectedValues}.
+ */
+export interface ReconsiderRejectedValuesResult {
+    /**
+     * `missing` plus the reconsidered values, so a consent decides them again.
+     */
+    readonly missing: string[];
+    /**
+     * `encountered` minus the reconsidered values, so they are no longer treated as settled no-ops.
+     */
+    readonly encountered: string[];
+    /**
+     * The values moved from `encountered` back into `missing`: rejected on the Grant and named by the
+     * current request. A consent that grants one of these must un-reject it on the Grant as well.
+     */
+    readonly reconsidered: string[];
+}
+/**
+ * Moves previously-rejected values the current request asks for again from the "encountered" set back into
+ * the "missing" set, so a re-consent decides them afresh.
+ *
+ * oidc-provider counts a rejected value as encountered: it never reappears in the prompt's `missing*`
+ * details, so without this a consent that names it again is a silent no-op and the value can never be
+ * granted on that Grant — even when the user explicitly ticks it. Values the Grant has GRANTED are left in
+ * `encountered`: they are already in force and need no re-application.
+ *
+ * @param input - The missing, encountered, rejected, and requested sets.
+ * @returns The adjusted missing/encountered sets plus the reconsidered values.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function reconsiderRejectedValues(input: ReconsiderRejectedValuesInput): ReconsiderRejectedValuesResult;
+/**
+ * Names every claim an authorization request's `claims` parameter asks for, across `id_token` and `userinfo`.
+ *
+ * @param claimsParam - The raw `claims` request parameter (a JSON string), or undefined.
+ * @returns The requested claim names; empty when the parameter is absent or malformed.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function requestedOIDCClaimNames(claimsParam: unknown): Set<string>;
+/**
+ * Normalizes an authorization request's `resource` parameter to its list of resource indicators.
+ *
+ * @param resourceParam - The raw `resource` request parameter (a string, an array of strings, or undefined).
+ * @returns The resource indicators; empty when the parameter is absent.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function requestedResourceIndicators(resourceParam: unknown): string[];

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

@@ -0,0 +1,77 @@
+import { type Maybe, type Milliseconds, type Seconds } from '@dereekb/util';
+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 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;
+    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>;
+    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.2.0",
+  "version": "14.4.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -57,18 +57,19 @@
     }
   },
   "peerDependencies": {
-    "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/analytics": "14.2.0",
-    "@dereekb/calcom": "14.2.0",
-    "@dereekb/date": "14.2.0",
-    "@dereekb/dbx-core": "14.2.0",
-    "@dereekb/discord": "14.2.0",
-    "@dereekb/firebase": "14.2.0",
-    "@dereekb/model": "14.2.0",
-    "@dereekb/nestjs": "14.2.0",
-    "@dereekb/rxjs": "14.2.0",
-    "@dereekb/util": "14.2.0",
-    "@dereekb/zoho": "14.2.0",
+    "@cantoo/pdf-lib": ">=2.6.5 <2.11.0",
+    "@dereekb/analytics": "14.4.0",
+    "@dereekb/calcom": "14.4.0",
+    "@dereekb/date": "14.4.0",
+    "@dereekb/dbx-core": "14.4.0",
+    "@dereekb/discord": "14.4.0",
+    "@dereekb/firebase": "14.4.0",
+    "@dereekb/model": "14.4.0",
+    "@dereekb/nestjs": "14.4.0",
+    "@dereekb/oauth-resource": "14.4.0",
+    "@dereekb/rxjs": "14.4.0",
+    "@dereekb/util": "14.4.0",
+    "@dereekb/zoho": "14.4.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",