@dereekb/firebase-server 13.12.9 → 13.13.0

package/oidc/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.12.9",
+  "version": "13.13.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.9",
-    "@dereekb/date": "13.12.9",
-    "@dereekb/firebase": "13.12.9",
-    "@dereekb/firebase-server": "13.12.9",
-    "@dereekb/model": "13.12.9",
-    "@dereekb/nestjs": "13.12.9",
-    "@dereekb/rxjs": "13.12.9",
-    "@dereekb/util": "13.12.9",
-    "@dereekb/zoho": "13.12.9",
+    "@dereekb/analytics": "13.13.0",
+    "@dereekb/date": "13.13.0",
+    "@dereekb/firebase": "13.13.0",
+    "@dereekb/firebase-server": "13.13.0",
+    "@dereekb/model": "13.13.0",
+    "@dereekb/nestjs": "13.13.0",
+    "@dereekb/rxjs": "13.13.0",
+    "@dereekb/util": "13.13.0",
+    "@dereekb/zoho": "13.13.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

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

@@ -4,6 +4,7 @@ import { type OAuthInteractionConsentRequest, type OAuthInteractionLoginRequest,
 import { OidcAccountService } from '../service/oidc.account.service';
 import { OidcInteractionService } from '../service/oidc.interaction.service';
 import { OidcService } from '../service/oidc.service';
+import { type OidcAnalyticsService } from '../service/analytics';
 /**
  * Controller for OIDC interaction endpoints (login/consent).
  *
@@ -19,7 +20,9 @@ export declare class OidcInteractionController {
     private readonly oidcProviderConfigService;
     private readonly accountService;
     private readonly oidcService;
-    constructor(oidcInteractionService: OidcInteractionService, oidcProviderConfigService: OidcProviderConfigService, accountService: OidcAccountService, oidcService: OidcService);
+    private readonly _logger;
+    private readonly _analytics;
+    constructor(oidcInteractionService: OidcInteractionService, oidcProviderConfigService: OidcProviderConfigService, accountService: OidcAccountService, oidcService: OidcService, analytics?: OidcAnalyticsService);
     /**
      * GET /interaction/:uid.
      *

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

@@ -29,5 +29,22 @@ export declare class OidcProviderController {
      * @param res - Express response used to issue the 302 redirect to the configured `appLoginUrl`.
      */
     redirectToClientLogin(req: Request, res: Response): void;
+    /**
+     * GET /oidc/session.
+     *
+     * Read route that verifies the presented bearer access token and returns its resolved session
+     * lifetime metadata: `{ sub, scope, expiresAt, rotationDisabled }`. `expiresAt` is the grant's
+     * expiry (unix seconds) and `rotationDisabled` flags a non-rotating (service) token. The values
+     * are sourced from the access token's baked-in `extra` claims (see `extraTokenClaims`), so this
+     * does not require decoding the opaque token client-side — cleaner than userinfo, which does not
+     * echo access-token `extra`.
+     *
+     * Declared ahead of the `@All('{*path}')` catch-all so it is matched here rather than proxied to
+     * the oidc-provider callback (mirrors `GET /oidc/login/client`).
+     *
+     * @param req - Inbound request; the `Authorization: Bearer <token>` header is read for the access token.
+     * @param res - Express response used to send the session JSON (401 when the token is missing/invalid).
+     */
+    getSession(req: Request, res: Response): Promise<void>;
     handleOidcRequest(req: Request, res: Response): Promise<void>;
 }

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

@@ -86,6 +86,24 @@ export interface OidcProviderConfig<S extends OidcScope = OidcScope> {
      * Supported OAuth 2.0 grant types (e.g., `['authorization_code', 'refresh_token']`).
      */
     readonly grantTypes: string[];
+    /**
+     * Scopes that may only be granted to admin users. When a consent request includes any of these
+     * scopes and the resolving user is not an admin (per
+     * {@link OidcAccountServiceDelegate.isAdminUser}), the interaction is hard-rejected with
+     * `access_denied` rather than silently dropping the scope.
+     *
+     * Keeps the generic package app-agnostic: apps opt a scope (e.g. `token.service`) into admin-only
+     * behavior by listing it here, rather than the package hard-coding any scope name.
+     */
+    readonly adminOnlyScopes?: readonly string[];
+    /**
+     * Scopes whose grants must never rotate their refresh token. When a grant's scope set intersects
+     * this list, {@link buildProviderConfiguration}'s `rotateRefreshToken` hook returns `false`,
+     * yielding a stable refresh token suitable for storing in a server environment variable.
+     *
+     * All other grants keep oidc-provider's default rotation behavior.
+     */
+    readonly nonRotatingScopes?: readonly string[];
 }
 /**
  * Returns the space-delimited list of every scope declared on `providerConfig.claims`.
@@ -142,6 +160,26 @@ export declare const DEFAULT_MAX_REQUESTED_LOGIN_DURATION_SECONDS: number;
  * Default global floor for a client-requested login duration, in seconds. 1 hour.
  */
 export declare const DEFAULT_MIN_REQUESTED_LOGIN_DURATION_SECONDS: number;
+/**
+ * Default ceiling (seconds) on a login duration for a non-admin user. 45 days.
+ *
+ * Tier 1 of the tiered ceiling resolved by `resolveTieredServerMaxSeconds`.
+ */
+export declare const DEFAULT_MAX_NONADMIN_LOGIN_DURATION_SECONDS: number;
+/**
+ * Default ceiling (seconds) on a normal (non-service-token) login duration for an admin user. 90 days.
+ *
+ * Tier 2 of the tiered ceiling resolved by `resolveTieredServerMaxSeconds`.
+ */
+export declare const DEFAULT_MAX_ADMIN_LOGIN_DURATION_SECONDS: number;
+/**
+ * Default ceiling (seconds) on a login duration carrying an admin-only service-token scope. 365 days.
+ *
+ * Tier 3 of the tiered ceiling resolved by `resolveTieredServerMaxSeconds`. Also matches
+ * node-oidc-provider's absolute refresh-token rotation cap (`totalLifetime >= 365.25d`), so a
+ * service token issued at this ceiling never rotates.
+ */
+export declare const DEFAULT_MAX_SERVICE_TOKEN_LOGIN_DURATION_SECONDS: number;
 /**
  * Default token lifetimes: 15 min access tokens, 30-day refresh tokens, 30-day sessions/grants, 60 s auth codes.
  */
@@ -205,6 +243,28 @@ export declare abstract class OidcModuleConfig {
      * auth-URL param. When undefined, falls back to {@link OidcTokenLifetimes.refreshToken}.
      */
     readonly defaultRequestedLoginDuration?: number;
+    /**
+     * Tiered ceiling (seconds) on the requested login duration for a non-admin user.
+     *
+     * Used by `resolveTieredServerMaxSeconds` when the resolving user is not an admin; the resolved
+     * tier value is used as the `serverMaxSeconds` ceiling (it replaces the flat
+     * {@link maxRequestedLoginDuration}, since service-token tokens intentionally exceed it).
+     *
+     * Defaults to {@link DEFAULT_MAX_NONADMIN_LOGIN_DURATION_SECONDS} (45 days).
+     */
+    readonly maxRequestedLoginDurationNonAdmin?: number;
+    /**
+     * Tiered ceiling (seconds) on a normal (non-service-token) requested login duration for an admin user.
+     *
+     * Defaults to {@link DEFAULT_MAX_ADMIN_LOGIN_DURATION_SECONDS} (90 days).
+     */
+    readonly maxRequestedLoginDurationAdmin?: number;
+    /**
+     * Tiered ceiling (seconds) on a requested login duration carrying an admin-only service-token scope.
+     *
+     * Defaults to {@link DEFAULT_MAX_SERVICE_TOKEN_LOGIN_DURATION_SECONDS} (365 days).
+     */
+    readonly maxRequestedLoginDurationServiceToken?: number;
     /**
      * JWKS service configuration (encryption secret, rotated key max age).
      */

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

@@ -0,0 +1,4 @@
+export * from './oidc.analytics.config';
+export * from './oidc.analytics.handler';
+export * from './oidc.analytics.module';
+export * from './oidc.analytics.service';

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

@@ -0,0 +1,46 @@
+import { type InjectionToken } from '@nestjs/common';
+import { type OidcAnalyticsEventType } from './oidc.analytics.handler';
+/**
+ * Default prefix prepended to every resolved OIDC analytics event name forwarded
+ * to the downstream analytics pipeline (e.g. `'OIDC ' + 'Login'` → `'OIDC Login'`).
+ */
+export declare const DEFAULT_OIDC_ANALYTICS_EVENT_NAME_PREFIX = "OIDC ";
+/**
+ * Default per-type downstream event name parts (the {@link DEFAULT_OIDC_ANALYTICS_EVENT_NAME_PREFIX}
+ * is prepended at send time).
+ */
+export declare const DEFAULT_OIDC_ANALYTICS_EVENT_NAMES: Record<OidcAnalyticsEventType, string>;
+/**
+ * Configuration for {@link FirebaseServerOidcAnalyticsService}.
+ *
+ * Apps provide this via {@link FIREBASE_SERVER_OIDC_ANALYTICS_CONFIG} (typically through
+ * {@link appOidcAnalyticsModuleMetadata}) to tune how OIDC events are named, logged, and forwarded.
+ */
+export interface FirebaseServerOidcAnalyticsConfig {
+    /**
+     * The prefix prepended to every resolved event name.
+     * Defaults to {@link DEFAULT_OIDC_ANALYTICS_EVENT_NAME_PREFIX}.
+     */
+    readonly eventNamePrefix?: string;
+    /**
+     * Per-type overrides for the (unprefixed) event name part. Merged over
+     * {@link DEFAULT_OIDC_ANALYTICS_EVENT_NAMES}.
+     */
+    readonly eventNames?: Partial<Record<OidcAnalyticsEventType, string>>;
+    /**
+     * Whether to emit a per-event `Logger` line for each OIDC event.
+     *
+     * Defaults to `true` on non-production environments.
+     */
+    readonly logEvents?: boolean;
+}
+/**
+ * NestJS injection token for the optional {@link FirebaseServerOidcAnalyticsConfig} provider.
+ *
+ * @example
+ * ```typescript
+ * @Module(appOidcAnalyticsModuleMetadata({ oidcAnalyticsConfig: { eventNamePrefix: 'OIDC ', logEvents: true } }))
+ * export class AppOidcAnalyticsModule {}
+ * ```
+ */
+export declare const FIREBASE_SERVER_OIDC_ANALYTICS_CONFIG: InjectionToken<FirebaseServerOidcAnalyticsConfig>;

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

@@ -0,0 +1,116 @@
+import { type InjectionToken, type Logger } from '@nestjs/common';
+import { type FirebaseAuthUserId } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+/**
+ * The high-level OIDC/OAuth interaction-flow event types captured as analytics.
+ *
+ * Each value maps to a distinct downstream analytics event name (see
+ * {@link DEFAULT_OIDC_ANALYTICS_EVENT_NAMES}). Scoped to the OIDC interaction flow
+ * (`POST /interaction/:uid/login` and `/consent`) — the events that have no callModel
+ * representation. Client/grant lifecycle operations run through callModel functions and
+ * are captured by the callModel analytics layer (`OnCallModelAnalyticsService`) instead.
+ */
+export type OidcAnalyticsEventType = 'login' | 'consent';
+/**
+ * Structured analytics event emitted once per high-level OIDC/OAuth moment.
+ *
+ * A single flat shape (mirroring the MCP `McpAnalyticsEvent`) keyed by {@link type};
+ * only the fields relevant to a given event type are populated. The {@link FirebaseServerOidcAnalyticsService}
+ * resolves a distinct downstream event name from {@link type} and forwards the populated
+ * fields as properties.
+ *
+ * Consumed by {@link OidcAnalyticsService} implementations registered under {@link OIDC_ANALYTICS_SERVICE}.
+ */
+export interface OidcAnalyticsEvent {
+    /**
+     * The high-level event identity.
+     */
+    readonly type: OidcAnalyticsEventType;
+    /**
+     * Whether the underlying operation completed successfully. `false` for failed logins,
+     * the admin-only service-token rejection, and any other denied/errored outcome.
+     */
+    readonly isSuccessful: boolean;
+    /**
+     * The Firebase Auth UID of the acting/owning user, when known. Always present for
+     * login/consent (the verified account id); best-effort for grant revocation (the grant
+     * owner) and typically absent for clientId-keyed client lifecycle events.
+     */
+    readonly uid?: Maybe<FirebaseAuthUserId>;
+    /**
+     * The OAuth client id the user is authenticating against / consenting to, when known.
+     */
+    readonly clientId?: Maybe<string>;
+    /**
+     * The OIDC scopes granted on a successful consent.
+     */
+    readonly scopes?: Maybe<string[]>;
+    /**
+     * Whether the event involved an admin-only service-token scope.
+     */
+    readonly serviceToken?: Maybe<boolean>;
+    /**
+     * Whether the acting user is an admin, when resolved (consent flow).
+     */
+    readonly isAdmin?: Maybe<boolean>;
+    /**
+     * Whether the user denied the consent prompt.
+     */
+    readonly denied?: Maybe<boolean>;
+    /**
+     * A short machine-readable reason for a failed/denied outcome (e.g. `'service_token_non_admin'`,
+     * `'invalid_id_token'`).
+     */
+    readonly reason?: Maybe<string>;
+    /**
+     * The thrown error, when the operation failed ({@link isSuccessful} is `false`).
+     */
+    readonly error?: Maybe<unknown>;
+    /**
+     * Wall-clock duration in milliseconds, when a handler boundary is available (controller handlers).
+     */
+    readonly durationMs?: Maybe<number>;
+    /**
+     * Custom key-value properties. Reserved for future use.
+     */
+    readonly properties?: Maybe<Record<string, any>>;
+}
+/**
+ * Abstract analytics service that apps implement to process OIDC analytics events.
+ *
+ * Analogous to the MCP `McpAnalyticsService` but scoped to the OIDC/OAuth transport.
+ * Apps extend this class and provide it via {@link OIDC_ANALYTICS_SERVICE}.
+ */
+export declare abstract class OidcAnalyticsService {
+    abstract handleOidcAnalyticsEvent(event: OidcAnalyticsEvent): void;
+}
+/**
+ * Injection token for the OIDC analytics service.
+ *
+ * Apps provide this (typically via {@link appOidcAnalyticsModuleMetadata} on a `@Global()`
+ * module) to enable analytics in the OIDC dispatch chain. When absent, the OIDC emitters
+ * fall back to {@link noopOidcAnalyticsService}.
+ */
+export declare const OIDC_ANALYTICS_SERVICE: InjectionToken<OidcAnalyticsService>;
+/**
+ * Creates a no-op {@link OidcAnalyticsService} that silently discards all events.
+ *
+ * Used as the default fallback by the OIDC emitters when no analytics service is registered.
+ *
+ * @returns An {@link OidcAnalyticsService} that discards all analytics events.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function noopOidcAnalyticsService(): OidcAnalyticsService;
+/**
+ * Forwards an {@link OidcAnalyticsEvent} to the given service, fail-soft.
+ *
+ * A throwing analytics handler must never break the underlying OIDC operation, so the
+ * handler invocation is wrapped — on error a warning is logged and the error is swallowed.
+ * Mirrors the MCP `_emitMcpAnalytics` discipline, factored to a free function because the
+ * OIDC events fire from several emitters.
+ *
+ * @param service - The analytics service to forward to.
+ * @param event - The event to emit.
+ * @param logger - The emitter's logger, used to warn when the handler throws.
+ */
+export declare function emitOidcAnalyticsEvent(service: OidcAnalyticsService, event: OidcAnalyticsEvent, logger: Logger): void;

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

@@ -0,0 +1,35 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { type Maybe } from '@dereekb/util';
+import { type FirebaseServerOidcAnalyticsConfig } from './oidc.analytics.config';
+/**
+ * Configuration for {@link appOidcAnalyticsModuleMetadata}.
+ */
+export interface AppOidcAnalyticsMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Optional {@link FirebaseServerOidcAnalyticsConfig} provided under
+     * {@link FIREBASE_SERVER_OIDC_ANALYTICS_CONFIG}. When omitted, the service uses its defaults.
+     */
+    readonly oidcAnalyticsConfig?: Maybe<FirebaseServerOidcAnalyticsConfig>;
+}
+/**
+ * Generates NestJS module metadata that registers {@link FirebaseServerOidcAnalyticsService} as the
+ * OIDC analytics consumer, aliased to {@link OIDC_ANALYTICS_SERVICE}.
+ *
+ * Mirrors the convention used by `appMcpAnalyticsModuleMetadata`. Requires no dependency module —
+ * `FirebaseServerAnalyticsService` is resolved optionally and is expected to be supplied globally by
+ * the app's analytics module.
+ *
+ * Decorate a `@Global()` module with the result so the `OIDC_ANALYTICS_SERVICE` token is visible to
+ * the OIDC controllers and services provided by the app's OIDC module.
+ *
+ * @param config - Optional metadata + analytics config to merge in.
+ * @returns NestJS module metadata providing + exporting the OIDC analytics service and token.
+ *
+ * @example
+ * ```typescript
+ * @Global()
+ * @Module(appOidcAnalyticsModuleMetadata())
+ * export class AppOidcAnalyticsModule {}
+ * ```
+ */
+export declare function appOidcAnalyticsModuleMetadata(config?: AppOidcAnalyticsMetadataConfig): ModuleMetadata;

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

@@ -0,0 +1,23 @@
+import { FirebaseServerAnalyticsService, FirebaseServerEnvService } from '@dereekb/firebase-server';
+import { OidcAnalyticsService, type OidcAnalyticsEvent } from './oidc.analytics.handler';
+import { type FirebaseServerOidcAnalyticsConfig } from './oidc.analytics.config';
+/**
+ * Reusable {@link OidcAnalyticsService} that forwards each high-level OIDC event to the app's
+ * {@link FirebaseServerAnalyticsService}, so OIDC-transport analytics feed the same downstream
+ * pipeline (e.g. Segment) as model and MCP analytics.
+ *
+ * Each {@link OidcAnalyticsEvent.type} resolves to a distinct downstream event name
+ * (`eventNamePrefix` + per-type name, e.g. `'OIDC Login'`). Registered globally via
+ * {@link appOidcAnalyticsModuleMetadata}; tuned via {@link FirebaseServerOidcAnalyticsConfig}.
+ * When no analytics service is available the call is a no-op aside from the optional log line.
+ */
+export declare class FirebaseServerOidcAnalyticsService extends OidcAnalyticsService {
+    private readonly firebaseServerEnvService;
+    private readonly analyticsService?;
+    private readonly _logger;
+    private readonly _eventNamePrefix;
+    private readonly _eventNames;
+    private readonly _logEvents;
+    constructor(firebaseServerEnvService: FirebaseServerEnvService, analyticsService?: FirebaseServerAnalyticsService | undefined, config?: FirebaseServerOidcAnalyticsConfig);
+    handleOidcAnalyticsEvent(event: OidcAnalyticsEvent): void;
+}

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

@@ -1,3 +1,4 @@
+export * from './analytics';
 export * from './oidc.account';
 export * from './oidc.account.service';
 export * from './oidc.auth';

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

@@ -60,6 +60,21 @@ export declare abstract class OidcAccountServiceDelegate<S extends OidcScope = O
      * @returns The claims to return for this user.
      */
     abstract buildClaimsForUser(userContext: U, scopes: Set<S>): Promise<OidcAccountClaims> | OidcAccountClaims;
+    /**
+     * Resolves whether the given user is an admin, used to gate
+     * {@link OidcProviderConfig.adminOnlyScopes} at consent time.
+     *
+     * Implementations should resolve admin status from the user's raw auth claims/roles
+     * independently of the requested OIDC scopes (do not rely on a scope-gated claim builder),
+     * so the check is authoritative regardless of which scopes the client requested.
+     *
+     * Optional: when omitted, the consent flow treats the user as a non-admin, hard-rejecting any
+     * request for an admin-only scope.
+     *
+     * @param userContext - The Firebase Auth user context.
+     * @returns Whether the user is an admin.
+     */
+    isAdminUser?(userContext: U): Promise<boolean>;
 }
 /**
  * Per-user context for OIDC account operations.

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

@@ -6,6 +6,10 @@ import { type OidcService } from './oidc.service';
  *
  * Mirrors the oidc-provider `registration.js` flow to ensure all provider
  * validation and lifecycle hooks run.
+ *
+ * Client create/update/rotate/delete are driven by callModel functions, so their
+ * analytics are captured by the callModel analytics layer (`OnCallModelAnalyticsService`)
+ * with the acting user — not by the OIDC analytics service.
  */
 export declare class OidcClientService {
     private readonly oidcService;

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

@@ -42,11 +42,11 @@ export declare class OidcInteractionService {
      * @param result - The interaction results to apply.
      * @param options - Optional settings for merging with the last submission.
      * @param options.mergeWithLastSubmission - Whether to merge with the last submission (defaults to true)
-     * @returns The `returnTo` URL that the client should redirect to.
+     * @returns The interaction that was completed. It includes the returnTo property for the next step of the interaction.
      */
     finishInteractionByUid(uid: OidcInteractionUid, result: InteractionResults, options?: {
         mergeWithLastSubmission?: boolean;
-    }): Promise<string>;
+    }): Promise<Interaction>;
     /**
      * Finds an existing grant by ID, or creates a new one.
      *

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

@@ -8,6 +8,21 @@ import { OidcProviderConfigService } from './oidc.config.service';
 import { type OidcEntryClientId, type OidcEntryOAuthClientPayloadData } from '@dereekb/firebase';
 import { type Maybe } from '@dereekb/util';
 import { type OidcAuthData } from './oidc.auth';
+/**
+ * Tier flags that select the server-max login-duration ceiling for a grant.
+ *
+ * @see OidcService.resolveLoginDurationForGrant
+ */
+export interface ResolveLoginDurationTier {
+    /**
+     * Whether the resolving user is an admin.
+     */
+    readonly isAdmin: boolean;
+    /**
+     * Whether the grant being created carries an admin-only service-token scope.
+     */
+    readonly hasServiceScope: boolean;
+}
 /**
  * Core OIDC service that wraps the oidc-provider instance and exposes
  * typed methods for interaction handling, provider initialization, and JWKS management.
@@ -36,13 +51,20 @@ export declare class OidcService {
      *
      * Mirrors the resolution used by the `Grant`/`Session` TTL functions in {@link buildProviderConfiguration}.
      *
+     * The `serverMaxSeconds` ceiling is tiered by {@link resolveTieredServerMaxSeconds}: a non-admin
+     * caps at the non-admin tier, an admin at the admin tier, and an admin whose grant carries a
+     * service-token scope at the (highest) service-token tier. This tiered value replaces the flat
+     * {@link OidcModuleConfig.maxRequestedLoginDuration} ceiling so a service token can intentionally
+     * exceed it.
+     *
      * @param requestedRawTtl - The raw `dbx_session_ttl` value from `interaction.params`, if any.
      * @param clientPayload - The persisted client metadata, used to read the per-client `dbx_max_session_ttl` cap.
+     * @param tier - Whether the resolving user is an admin and whether the grant carries a service-token scope.
      * @returns The resolved Grant TTL in seconds.
      */
     resolveLoginDurationForGrant(requestedRawTtl: unknown, clientPayload: {
         dbx_max_session_ttl?: number;
-    } | undefined): number;
+    } | undefined, tier: ResolveLoginDurationTier): number;
     /**
      * Verifies an opaque access token and returns the {@link OidcAuthData}.
      *

package/oidc/src/lib/service/oidc.session-ttl.d.ts

@@ -9,6 +9,19 @@ export declare const DBX_FIREBASE_SERVER_OIDC_SESSION_TTL_PARAM = "dbx_session_t
  * Custom oidc-provider client metadata field for a client's maximum requestable login duration (seconds).
  */
 export declare const DBX_FIREBASE_SERVER_OIDC_MAX_SESSION_TTL_CLIENT_METADATA = "dbx_max_session_ttl";
+/**
+ * Access-token `extra` claim carrying the grant's resolved expiry as unix seconds.
+ *
+ * Baked on at issuance (`extraTokenClaims`) and read back by `verifyAccessToken` and the
+ * `GET /oidc/session` route so clients can surface the session lifetime without decoding the token.
+ */
+export declare const DBX_FIREBASE_SERVER_OIDC_SESSION_EXPIRES_AT_CLAIM = "dbx_session_expires_at";
+/**
+ * Access-token `extra` claim flagging whether the grant's refresh token rotation is disabled.
+ *
+ * `true` when the token's scope set intersects {@link OidcProviderConfig.nonRotatingScopes}.
+ */
+export declare const DBX_FIREBASE_SERVER_OIDC_ROTATION_DISABLED_CLAIM = "dbx_rotation_disabled";
 /**
  * Inputs to {@link resolveLoginDurationSeconds}.
  */
@@ -57,6 +70,107 @@ export interface ResolveLoginDurationInput {
  * ```
  */
 export declare function resolveLoginDurationSeconds(input: ResolveLoginDurationInput): number;
+/**
+ * Inputs to {@link resolveTieredServerMaxSeconds}.
+ */
+export interface ResolveTieredServerMaxInput {
+    /**
+     * Whether the resolving user is an admin.
+     */
+    readonly isAdmin: boolean;
+    /**
+     * Whether the grant carries an admin-only service-token scope.
+     */
+    readonly hasServiceScope: boolean;
+    /**
+     * Ceiling (seconds) for a non-admin user.
+     */
+    readonly nonAdminMax: number;
+    /**
+     * Ceiling (seconds) for a normal (non-service-token) admin login.
+     */
+    readonly adminMax: number;
+    /**
+     * Ceiling (seconds) for an admin login carrying a service-token scope.
+     */
+    readonly serviceTokenMax: number;
+}
+/**
+ * Resolves the tiered server-max ceiling (seconds) used as `serverMaxSeconds` for a login duration.
+ *
+ * Tiers, highest to lowest priority:
+ * 1. Admin + service-token scope → `serviceTokenMax`.
+ * 2. Admin (normal) → `adminMax`.
+ * 3. Non-admin → `nonAdminMax`.
+ *
+ * A non-admin should never reach the service-token branch — the consent flow hard-rejects a
+ * non-admin requesting a service-token scope before this resolves — but the tiering is defensive:
+ * a non-admin always resolves to `nonAdminMax` regardless of `hasServiceScope`.
+ *
+ * @param input - The tier inputs (admin flag, service-scope flag, and the three tier ceilings).
+ * @returns The resolved ceiling in seconds.
+ */
+export declare function resolveTieredServerMaxSeconds(input: ResolveTieredServerMaxInput): number;
+/**
+ * Absolute cap (seconds) on how long a refresh token may be rotated, after which its TTL is final.
+ *
+ * Mirrors node-oidc-provider's default `rotateRefreshToken` cap of `365.25 * 24 * 60 * 60`.
+ */
+export declare const REFRESH_TOKEN_ROTATION_MAX_LIFETIME_SECONDS: number;
+/**
+ * Percentage of a refresh token's lifetime that must elapse before the library-default branch rotates it.
+ *
+ * Mirrors node-oidc-provider's default `rotateRefreshToken` threshold of `70`.
+ */
+export declare const REFRESH_TOKEN_ROTATION_TTL_PERCENTAGE_THRESHOLD = 70;
+/**
+ * Inputs to {@link shouldRotateRefreshToken}.
+ */
+export interface ShouldRotateRefreshTokenInput {
+    /**
+     * Space-delimited scope string of the refresh token being exchanged, if any.
+     */
+    readonly scope: string | undefined;
+    /**
+     * Scopes whose grants must never rotate (from {@link OidcProviderConfig.nonRotatingScopes}).
+     */
+    readonly nonRotatingScopes: readonly string[];
+    /**
+     * The refresh token's total lifetime in seconds (`refreshToken.totalLifetime()`).
+     */
+    readonly totalLifetimeSeconds: number;
+    /**
+     * The client's auth method (`client.clientAuthMethod`); `'none'` indicates a public client.
+     */
+    readonly clientAuthMethod: string | undefined;
+    /**
+     * Whether the refresh token is sender-constrained (`refreshToken.isSenderConstrained()`).
+     */
+    readonly isSenderConstrained: boolean;
+    /**
+     * Percentage of the refresh token's lifetime already elapsed (`refreshToken.ttlPercentagePassed()`).
+     */
+    readonly ttlPercentagePassed: number;
+}
+/**
+ * Decides whether a refresh token should rotate on exchange.
+ *
+ * Returns `false` (no rotation) whenever the token's scope set intersects `nonRotatingScopes` — the
+ * dbx-components extension point that makes service tokens stable for server env consumption.
+ *
+ * For every other token this **replicates node-oidc-provider's default `rotateRefreshToken`**
+ * (because setting the option disables the library's built-in default, we must reproduce it):
+ * 1. `totalLifetime >= 365.25d` → `false` (rotation cap reached; TTL is final).
+ * 2. public client (`clientAuthMethod === 'none'`) and not sender-constrained → `true`.
+ * 3. otherwise → `ttlPercentagePassed >= 70`.
+ *
+ * Keep this in sync with `node_modules/oidc-provider/lib/helpers/defaults.js` (`rotateRefreshToken`)
+ * across oidc-provider upgrades.
+ *
+ * @param input - The rotation inputs.
+ * @returns Whether the refresh token should rotate.
+ */
+export declare function shouldRotateRefreshToken(input: ShouldRotateRefreshTokenInput): boolean;
 /**
  * Parses a raw `dbx_session_ttl` value (string or number, from URL query / form / persisted interaction params)
  * into a positive integer number of seconds. Returns `undefined` when missing or invalid so the caller falls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.12.9",
+  "version": "13.13.0",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -57,15 +57,15 @@
   "types": "./src/index.d.ts",
   "peerDependencies": {
     "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/analytics": "13.12.9",
-    "@dereekb/date": "13.12.9",
-    "@dereekb/dbx-core": "13.12.9",
-    "@dereekb/firebase": "13.12.9",
-    "@dereekb/model": "13.12.9",
-    "@dereekb/nestjs": "13.12.9",
-    "@dereekb/rxjs": "13.12.9",
-    "@dereekb/util": "13.12.9",
-    "@dereekb/zoho": "13.12.9",
+    "@dereekb/analytics": "13.13.0",
+    "@dereekb/date": "13.13.0",
+    "@dereekb/dbx-core": "13.13.0",
+    "@dereekb/firebase": "13.13.0",
+    "@dereekb/model": "13.13.0",
+    "@dereekb/nestjs": "13.13.0",
+    "@dereekb/rxjs": "13.13.0",
+    "@dereekb/util": "13.13.0",
+    "@dereekb/zoho": "13.13.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@modelcontextprotocol/sdk": "1.29.0",