@udibo/oauth2 0.4.1 → 0.5.1

package/esm/server/grants/refresh-token.js

@@ -40,8 +40,9 @@ export class RefreshTokenGrant extends AbstractGrant {
      * authorization.
      *
      * @throws {InvalidRequestError} If `refresh_token` is missing.
-     * @throws {InvalidGrantError} If the refresh token is unknown or expired, or
-     * its family has outlived the absolute cap.
+     * @throws {InvalidGrantError} If the refresh token is unknown or expired, its
+     * family has outlived the absolute cap, or a concurrent exchange already
+     * claimed it.
      * @throws {InvalidClientError} If the token was issued to another client.
      * @throws {InvalidScopeError} If the requested scope exceeds the original grant.
      */
@@ -98,7 +99,7 @@ export class RefreshTokenGrant extends AbstractGrant {
         if (familyExpiresAt && familyExpiresAt.getTime() <= Date.now()) {
             throw new InvalidGrantError("refresh_token family expired");
         }
-        const nextToken = await this.generateToken(client, user, nextScope, tokenService, currentToken.authenticationContext);
+        const nextToken = await this.generateToken(client, user, nextScope, tokenService, currentToken.authenticationContext, familyExpiresAt);
         const nextRefreshToken = "refreshToken" in nextToken
             ? nextToken
             : {

package/esm/server/introspection-token-reader.d.ts

@@ -46,10 +46,13 @@ export interface IntrospectionTokenReaderOptions<Client extends ClientInterface,
      * `undefined` when the token doesn't represent a user. Omit entirely if
      * your app never reads user info off the token.
      *
-     * A machine token (client credentials) carries no `sub`, so `data.sub` is
-     * present only when there is a resource owner — `data.sub ? {…} : undefined`
-     * is the whole discriminator, and a client-credentials caller resolves to no
-     * user.
+     * This package's authorization server sets `sub` from its `subjectOf`
+     * option (the user's `id` by default — the same value its id_token and
+     * UserInfo carry) and omits it for a token with no user, whatever its
+     * `introspectionClaims` hook returns, so `data.sub` is present only when
+     * there is a resource owner and `data.sub ? {…} : undefined` is the whole
+     * discriminator. Another authorization server may set `sub` to the client
+     * id for a machine token; check how yours answers.
      *
      * May be async — return a promise to enrich from a DB lookup or the
      * authorization server's OIDC UserInfo endpoint, using `data.sub` as
@@ -81,6 +84,11 @@ export interface IntrospectionTokenReaderOptions<Client extends ClientInterface,
  * types via the {@linkcode IntrospectionTokenReaderOptions.getClient} and
  * {@linkcode IntrospectionTokenReaderOptions.getUser} mappers.
  *
+ * The reader does not check `aud` or `iss`: any token the endpoint reports
+ * active with a bearer `token_type` is accepted. When one authorization server
+ * issues tokens for several APIs, check the audience yourself (it is on
+ * {@linkcode Token.claims}) or have the endpoint scope its answers.
+ *
  * @example
  * ```ts
  * import {
@@ -137,9 +145,10 @@ export declare class IntrospectionTokenReader<Client extends ClientInterface, Us
      *   returns a 5xx — a down authorization server must be distinguishable from
      *   a genuinely invalid token (which is `undefined` → `invalid_token`), not
      *   collapsed into it.
-     * @throws {ServerError} If the endpoint returns a 4xx (e.g. the reader's own
-     *   introspection credentials are rejected) — a misconfiguration, not a
-     *   verdict on the caller's token.
+     * @throws {ServerError} If the endpoint returns any other non-2xx status
+     *   (e.g. the reader's own introspection credentials are rejected) or a body
+     *   that is not JSON — a misconfiguration, not a verdict on the caller's
+     *   token.
      *
      * An active response is only accepted when its `token_type` names a bearer
      * token. RFC 7662 answers for refresh tokens too, and a refresh token's

package/esm/server/introspection-token-reader.js

@@ -22,6 +22,11 @@ import { encodeBasicAuth } from "../utils/basic-auth.js";
  * types via the {@linkcode IntrospectionTokenReaderOptions.getClient} and
  * {@linkcode IntrospectionTokenReaderOptions.getUser} mappers.
  *
+ * The reader does not check `aud` or `iss`: any token the endpoint reports
+ * active with a bearer `token_type` is accepted. When one authorization server
+ * issues tokens for several APIs, check the audience yourself (it is on
+ * {@linkcode Token.claims}) or have the endpoint scope its answers.
+ *
  * @example
  * ```ts
  * import {
@@ -87,9 +92,10 @@ export class IntrospectionTokenReader {
      *   returns a 5xx — a down authorization server must be distinguishable from
      *   a genuinely invalid token (which is `undefined` → `invalid_token`), not
      *   collapsed into it.
-     * @throws {ServerError} If the endpoint returns a 4xx (e.g. the reader's own
-     *   introspection credentials are rejected) — a misconfiguration, not a
-     *   verdict on the caller's token.
+     * @throws {ServerError} If the endpoint returns any other non-2xx status
+     *   (e.g. the reader's own introspection credentials are rejected) or a body
+     *   that is not JSON — a misconfiguration, not a verdict on the caller's
+     *   token.
      *
      * An active response is only accepted when its `token_type` names a bearer
      * token. RFC 7662 answers for refresh tokens too, and a refresh token's

package/esm/server/jwks-token-reader.d.ts

@@ -255,9 +255,9 @@ export declare class JwksTokenReader<Client extends ClientInterface, User, S ext
      *   available — a down issuer must be distinguishable from a genuinely
      *   invalid token, not collapsed into it. Once keys are cached, a failed
      *   refresh is absorbed and the cached keys keep serving.
-     * @throws {ServerError} If the JWKS endpoint returns a 4xx or a body that
-     *   is not a JWKS, or discovery reports no `jwks_uri` — a
-     *   misconfiguration, not a verdict on the caller's token.
+     * @throws {ServerError} If, with no keys cached, the JWKS endpoint returns
+     *   a 4xx or a body that is not a JWKS, or discovery reports no `jwks_uri`
+     *   — a misconfiguration, not a verdict on the caller's token.
      */
     getToken(accessToken: string): Promise<Token<Client, User, S> | undefined>;
 }

package/esm/server/jwks-token-reader.js

@@ -276,9 +276,9 @@ export class JwksTokenReader {
      *   available — a down issuer must be distinguishable from a genuinely
      *   invalid token, not collapsed into it. Once keys are cached, a failed
      *   refresh is absorbed and the cached keys keep serving.
-     * @throws {ServerError} If the JWKS endpoint returns a 4xx or a body that
-     *   is not a JWKS, or discovery reports no `jwks_uri` — a
-     *   misconfiguration, not a verdict on the caller's token.
+     * @throws {ServerError} If, with no keys cached, the JWKS endpoint returns
+     *   a 4xx or a body that is not a JWKS, or discovery reports no `jwks_uri`
+     *   — a misconfiguration, not a verdict on the caller's token.
      */
     async getToken(accessToken) {
         const parsed = parseJws(accessToken);

package/esm/server/redirect-uri.d.ts

@@ -149,15 +149,12 @@ export declare function checkRedirectUriPattern(pattern: string, isPublicSuffix?
  * - A host label may never be empty, and a single trailing dot is treated as
  *   the same host, so `example.com.` cannot smuggle an extra label past the
  *   parent-domain rule.
- * - A requested URI containing `*` never matches anything, checked both on the
- *   raw string and on the percent-decoded host, so a pattern can never be
- *   replayed back as a literal redirect target.
- *
- * That last rule is a deliberate tightening: `*` is a legal host character, so
- * a registration containing one that was previously matched by exact string
- * comparison no longer matches at all. Such a registration cannot be created
- * any more — a `*` now makes the value a pattern, which must satisfy the rules
- * above — so this only affects rows written before patterns existed.
+ * - A requested URI containing a literal `*` never matches any registration,
+ *   so a pattern can never be replayed back as a redirect target. A requested
+ *   host that percent-decodes to one containing `*` never matches a pattern.
+ *
+ * Any registration containing `*` is a pattern, so a stored literal URI with a
+ * `*` in its host matches only if it also satisfies the pattern rules.
  *
  * @param registered The client's registered redirect URIs.
  * @param redirectUri The `redirect_uri` from the authorization request.

package/esm/server/redirect-uri.js

@@ -38,27 +38,8 @@
  *
  * @module
  */
-/**
- * A label used to ask whether the *children* of a parent domain are public
- * suffixes, which is a different question from whether the parent is one.
- *
- * `r.appspot.com` is a registrable domain by the list's reckoning, but the rule
- * `*.r.appspot.com` makes every one of its subdomains a public suffix belonging
- * to a different registrant — so a wildcard over it hands codes to strangers
- * even though the parent itself passes. Probing with a label no registry has
- * ever issued answers that in one lookup.
- */
+// A label no registry issues; a PSL hit on it catches `*.r.appspot.com` rules.
 const CHILD_PROBE_LABEL = "udibo-public-suffix-probe";
-/**
- * Split a hostname into labels, or `null` when it is not usable for matching.
- *
- * A single trailing dot is the DNS root and is dropped, so `example.com.` and
- * `example.com` are the same host — without this, the extra empty label would
- * shift every label the public-suffix check looks at and let `*.deno.net.`
- * through. Any *other* empty label (`a..b`, a leading `.`) is refused outright
- * rather than normalized: it cannot resolve, and an empty leftmost label would
- * otherwise satisfy any prefix/suffix test.
- */
 function hostLabels(hostname) {
     const normalized = hostname.endsWith(".") ? hostname.slice(0, -1) : hostname;
     if (normalized.length === 0)
@@ -175,12 +156,7 @@ export function checkRedirectUriPattern(pattern, isPublicSuffix) {
     }
     return null;
 }
-/**
- * The loopback IP literals RFC 8252 §7.3 covers, in the form
- * `URL.hostname` normalizes them to. `localhost` is deliberately absent: RFC
- * 8252 §8.3 advises against it because its resolution depends on a host file
- * the authorization server does not control.
- */
+// RFC 8252 §7.3 IP literals only; `localhost` is excluded per RFC 8252 §8.3.
 const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "[::1]"]);
 function matchesLoopback(registration, redirectUri) {
     if (isRedirectUriPattern(registration))
@@ -275,15 +251,12 @@ function matchesPattern(pattern, redirectUri, isPublicSuffix) {
  * - A host label may never be empty, and a single trailing dot is treated as
  *   the same host, so `example.com.` cannot smuggle an extra label past the
  *   parent-domain rule.
- * - A requested URI containing `*` never matches anything, checked both on the
- *   raw string and on the percent-decoded host, so a pattern can never be
- *   replayed back as a literal redirect target.
+ * - A requested URI containing a literal `*` never matches any registration,
+ *   so a pattern can never be replayed back as a redirect target. A requested
+ *   host that percent-decodes to one containing `*` never matches a pattern.
  *
- * That last rule is a deliberate tightening: `*` is a legal host character, so
- * a registration containing one that was previously matched by exact string
- * comparison no longer matches at all. Such a registration cannot be created
- * any more — a `*` now makes the value a pattern, which must satisfy the rules
- * above — so this only affects rows written before patterns existed.
+ * Any registration containing `*` is a pattern, so a stored literal URI with a
+ * `*` in its host matches only if it also satisfies the pattern rules.
  *
  * @param registered The client's registered redirect URIs.
  * @param redirectUri The `redirect_uri` from the authorization request.

package/esm/server/resource-server.d.ts

@@ -231,10 +231,12 @@ export declare class ResourceServer<Client extends ClientInterface, User, S exte
      *
      * The token's expiry is compared against now with {@linkcode
      * clockSkewSeconds} of leeway, so the same tolerance applies whichever
-     * token reader produced the token.
+     * token reader produced the token. A token without `accessTokenExpiresAt`
+     * is never refused as expired here. Revocation is the reader's to report,
+     * by resolving no token.
      *
-     * @throws {InvalidTokenError} If the token is invalid, expired beyond the
-     *   configured leeway, or revoked
+     * @throws {InvalidTokenError} If the reader resolves no token, or the token
+     *   has expired beyond the configured leeway
      * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
      */
     getToken(accessToken: string, services: ResourceServerServices<Client, User, S>): Promise<Token<Client, User, S>>;

package/esm/server/resource-server.js

@@ -258,10 +258,12 @@ export class ResourceServer {
      *
      * The token's expiry is compared against now with {@linkcode
      * clockSkewSeconds} of leeway, so the same tolerance applies whichever
-     * token reader produced the token.
+     * token reader produced the token. A token without `accessTokenExpiresAt`
+     * is never refused as expired here. Revocation is the reader's to report,
+     * by resolving no token.
      *
-     * @throws {InvalidTokenError} If the token is invalid, expired beyond the
-     *   configured leeway, or revoked
+     * @throws {InvalidTokenError} If the reader resolves no token, or the token
+     *   has expired beyond the configured leeway
      * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
      */
     async getToken(accessToken, services) {

package/esm/server/services/client.d.ts

@@ -30,6 +30,10 @@ export interface ClientServiceInterface<Client extends ClientInterface, User> {
      * carried none.
      */
     getAuthenticated(id: string, secret?: string): Promise<Client | undefined>;
-    /** Retrieves a user associated with a client (for client-credentials grant). */
+    /**
+     * Resolves the user a client-credentials token acts for. Resolving
+     * `undefined` is the conformant case and yields a user-less machine token;
+     * see `ClientCredentialsGrant` before mapping a client to a human user.
+     */
     getUser(client: Client | string): Promise<User | undefined>;
 }

package/esm/server/services/device-authorization.d.ts

@@ -34,15 +34,15 @@ import type { AbstractScope } from "../../models/scope.js";
  */
 export interface DeviceAuthorizationServiceInterface<Client extends ClientInterface, User, Scope extends AbstractScope> {
     /**
-     * Lifetime of device codes in seconds.
-     * RFC 8628 does not specify a default, but 15-30 minutes is common.
-     * @default 1800 (30 minutes)
+     * Lifetime of device codes in seconds. RFC 8628 sets no default; 15–30
+     * minutes is common.
      */
     lifetime: number;
     /**
-     * Minimum polling interval in seconds.
-     * Clients should not poll more frequently than this.
-     * @default 5
+     * Minimum polling interval in seconds, copied onto each new authorization
+     * and returned to the device as `interval`. The grant answers a faster poll
+     * with `slow_down` and adds 5 seconds to that authorization's interval
+     * (RFC 8628 §3.5).
      */
     interval: number;
     /**

package/esm/server/services/token.d.ts

@@ -24,9 +24,10 @@ export interface TokenReaderInterface<Client extends ClientInterface, User, Scop
  * its grant types.
  *
  * **A token need not have a user.** The client credentials grant (RFC 6749
- * §4.4) has no resource owner, so it calls `acceptedScope`,
- * `generateAccessToken`, and `accessTokenExpiresAt` with `user: undefined` and
- * saves a {@linkcode Token} whose `user` is unset. An implementation that
+ * §4.4) has no resource owner, so when `ClientServiceInterface.getUser`
+ * resolves none it calls `acceptedScope`, `generateAccessToken`, and
+ * `accessTokenExpiresAt` with `user: undefined` and saves a {@linkcode Token}
+ * whose `user` is unset. An implementation that
  * dereferences `user` without checking will throw on those requests, and a
  * store with a non-nullable user column cannot persist the result — decide
  * scope and lifetime from the client alone when it is absent.
@@ -53,8 +54,13 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * generator names the client as the subject then, per RFC 9068 §2.2.
      * Forward `authenticationContext` to a signed-token generator so it uses
      * the credential's event, including the original event on refresh.
+     * `expiresAt` is the expiry the grant will store for this token — already
+     * clamped to the refresh family's cap when one applies. Forward it too, so
+     * a signed token's `exp` never outlives what the server itself honors; the
+     * grants always pass it, and a wrapper that drops it leaves offline
+     * verifiers accepting the token past its stored expiry.
      */
-    generateAccessToken(client: Client, user: User | undefined, scope?: Scope | null, authenticationContext?: AuthenticationContext): Promise<string>;
+    generateAccessToken(client: Client, user: User | undefined, scope?: Scope | null, authenticationContext?: AuthenticationContext, expiresAt?: Date): Promise<string>;
     /** Generates a refresh token string. */
     generateRefreshToken(client: Client, user: User, scope?: Scope | null): Promise<string | undefined>;
     /**
@@ -71,7 +77,8 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      *
      * **This method is the whole cap.** The grants clamp a rotation's access and
      * refresh expiries to the date it returns and answer `invalid_grant` once
-     * that date has passed. Return `undefined` — or leave the method off
+     * that date has passed; a refresh-token record without `familyCreatedAt` is
+     * never capped. Return `undefined` — or leave the method off
      * entirely, which is the default — and the family is never capped, however
      * the service is otherwise configured. Implement it to cap per client (see
      * {@linkcode AbstractTokenService.refreshTokenMaxLifetime} for the
@@ -151,8 +158,8 @@ export interface AbstractTokenServiceOptions<Client extends ClientInterface, Use
     /**
      * Absolute lifetime of a refresh-token family in seconds, read by this
      * class's {@linkcode AbstractTokenService.refreshTokenFamilyExpiresAt}. Omit
-     * for the historical behavior, an uncapped sliding window. Must be at least
-     * `refreshTokenLifetime`.
+     * to leave families uncapped, so rotation extends a family indefinitely.
+     * Must be at least `refreshTokenLifetime`.
      */
     refreshTokenMaxLifetime?: number;
     /** Client service for hydrating tokens. */
@@ -202,7 +209,7 @@ export declare abstract class AbstractTokenService<Client extends ClientInterfac
      */
     acceptedScope(_client: Client, _user: User | undefined, scope?: Scope | null): Promise<Scope | null | undefined | false>;
     /** Generates an opaque access token string. Override to issue a different format. */
-    generateAccessToken(_client: Client, _user: User | undefined, _scope?: Scope | null, _authenticationContext?: AuthenticationContext): Promise<string>;
+    generateAccessToken(_client: Client, _user: User | undefined, _scope?: Scope | null, _authenticationContext?: AuthenticationContext, _expiresAt?: Date): Promise<string>;
     /** Generates an opaque refresh token string. Override to issue a different format. */
     generateRefreshToken(_client: Client, _user: User, _scope?: Scope | null): Promise<string | undefined>;
     /** Computes the access token expiry as now plus {@linkcode accessTokenLifetime}. */

package/esm/server/services/token.js

@@ -52,7 +52,7 @@ export class AbstractTokenService {
         return Promise.resolve(scope);
     }
     /** Generates an opaque access token string. Override to issue a different format. */
-    generateAccessToken(_client, _user, _scope, _authenticationContext) {
+    generateAccessToken(_client, _user, _scope, _authenticationContext, _expiresAt) {
         return Promise.resolve(crypto.randomUUID());
     }
     /** Generates an opaque refresh token string. Override to issue a different format. */

package/esm/server/signing-keys.d.ts

@@ -115,7 +115,11 @@ export declare function generateSigningKey(): Promise<SigningKey>;
 export declare function exportSigningKeyJwk(key: SigningKey): Promise<JsonWebKey & {
     kid: string;
 }>;
-/** Import a signing key previously exported with {@link exportSigningKeyJwk}. */
+/**
+ * Import a signing key previously exported with {@link exportSigningKeyJwk}.
+ * A JWK without a `kid` is given a random one, so every instance importing it
+ * would publish and stamp a different `kid` — persist the exported `kid`.
+ */
 export declare function importSigningKeyJwk(jwk: JsonWebKey & {
     kid?: string;
 }): Promise<SigningKey>;
@@ -139,10 +143,12 @@ export interface VerifyJwtOptions {
 }
 /**
  * Verify a compact JWS against a public JWK and return its payload, or
- * `undefined` when the signature (or shape) is invalid or the payload's `exp`
- * is in the past. Exported for tests and lightweight in-process verification;
- * production resource servers should verify against the JWKS endpoint with
- * their JOSE library of choice.
+ * `undefined` when the signature (or shape) is invalid or a numeric `exp` is
+ * not in the future. It verifies ES256 regardless of the header's `alg` and
+ * checks nothing else: a payload with no `exp` passes, and `iss`, `aud`, and
+ * `nbf` are the caller's to check. Exported for tests and lightweight
+ * in-process verification; production resource servers should verify against
+ * the JWKS endpoint with their JOSE library of choice.
  */
 export declare function verifyJwt(jwt: string, publicJwk: JsonWebKey, options?: VerifyJwtOptions): Promise<Record<string, unknown> | undefined>;
 /**
@@ -159,8 +165,10 @@ export declare function verifyJwt(jwt: string, publicJwk: JsonWebKey, options?:
  * }
  * ```
  *
- * The token store still persists the (hashed) JWT string, so revocation and
- * introspection keep working exactly as with opaque tokens.
+ * Your token store persists the JWT string like any access token, so
+ * revocation and introspection work as with opaque tokens for readers that
+ * consult the store. A resource server that verifies the JWT offline against
+ * JWKS does not see a revocation and accepts the token until its `exp`.
  */
 export declare function createJwtAccessTokenGenerator(options: {
     /** Keys the tokens are signed with (also served from JWKS). */
@@ -173,7 +181,14 @@ export declare function createJwtAccessTokenGenerator(options: {
      * the client id, which single-resource validators must then accept.
      */
     audience?: string;
-    /** Token lifetime in seconds for the `exp` claim. Defaults to 3600. */
+    /**
+     * Upper bound in seconds on the `exp` claim. Defaults to 3600. The claim
+     * is the earlier of this and the expiry the grant passes as the fifth
+     * argument — the token service's `accessTokenExpiresAt`, already clamped to
+     * any refresh-family cap — so an offline verifier never accepts the token
+     * past the server's own expiry. A wrapper that drops that argument falls
+     * back to this lifetime alone.
+     */
     lifetimeSeconds?: number;
     /** Maps a user to the `sub` claim. Defaults to the user's `id` property. */
     subjectOf?: (user: unknown) => string;
@@ -198,4 +213,4 @@ export declare function createJwtAccessTokenGenerator(options: {
     id: string;
 }, user: unknown, scope?: {
     toString(): string;
-} | null, authenticationContext?: AuthenticationContext) => Promise<string>;
+} | null, authenticationContext?: AuthenticationContext, expiresAt?: Date) => Promise<string>;

package/esm/server/signing-keys.js

@@ -128,7 +128,11 @@ export async function exportSigningKeyJwk(key) {
     const jwk = await crypto.subtle.exportKey("jwk", key.privateKey);
     return { ...jwk, kid: key.kid, alg: key.alg };
 }
-/** Import a signing key previously exported with {@link exportSigningKeyJwk}. */
+/**
+ * Import a signing key previously exported with {@link exportSigningKeyJwk}.
+ * A JWK without a `kid` is given a random one, so every instance importing it
+ * would publish and stamp a different `kid` — persist the exported `kid`.
+ */
 export async function importSigningKeyJwk(jwk) {
     const privateKey = await crypto.subtle.importKey("jwk", jwk, ES256_PARAMS, true, ["sign"]);
     const kid = jwk.kid ?? crypto.randomUUID();
@@ -150,10 +154,12 @@ export async function signJwt(key, payload, header = {}) {
 }
 /**
  * Verify a compact JWS against a public JWK and return its payload, or
- * `undefined` when the signature (or shape) is invalid or the payload's `exp`
- * is in the past. Exported for tests and lightweight in-process verification;
- * production resource servers should verify against the JWKS endpoint with
- * their JOSE library of choice.
+ * `undefined` when the signature (or shape) is invalid or a numeric `exp` is
+ * not in the future. It verifies ES256 regardless of the header's `alg` and
+ * checks nothing else: a payload with no `exp` passes, and `iss`, `aud`, and
+ * `nbf` are the caller's to check. Exported for tests and lightweight
+ * in-process verification; production resource servers should verify against
+ * the JWKS endpoint with their JOSE library of choice.
  */
 export async function verifyJwt(jwt, publicJwk, options = {}) {
     const parts = jwt.split(".");
@@ -190,13 +196,15 @@ export async function verifyJwt(jwt, publicJwk, options = {}) {
  * }
  * ```
  *
- * The token store still persists the (hashed) JWT string, so revocation and
- * introspection keep working exactly as with opaque tokens.
+ * Your token store persists the JWT string like any access token, so
+ * revocation and introspection work as with opaque tokens for readers that
+ * consult the store. A resource server that verifies the JWT offline against
+ * JWKS does not see a revocation and accepts the token until its `exp`.
  */
 export function createJwtAccessTokenGenerator(options) {
     const lifetime = options.lifetimeSeconds ?? 3600;
     const subjectOf = options.subjectOf ?? defaultSubjectOf;
-    return async (client, user, scope, authenticationContext) => {
+    return async (client, user, scope, authenticationContext, expiresAt) => {
         const event = user
             ? snapshotAuthenticationContext(authenticationContext)
             : undefined;
@@ -205,6 +213,9 @@ export function createJwtAccessTokenGenerator(options) {
         const extraClaims = user && options.userClaims
             ? await options.userClaims(user, scope, client, event)
             : undefined;
+        const storedExp = expiresAt
+            ? Math.floor(expiresAt.getTime() / 1000)
+            : now + lifetime;
         const payload = {
             ...extraClaims,
             iss: options.issuer,
@@ -212,7 +223,7 @@ export function createJwtAccessTokenGenerator(options) {
             client_id: client.id,
             aud: options.audience ?? client.id,
             iat: now,
-            exp: now + lifetime,
+            exp: Math.min(now + lifetime, storedExp),
             jti: crypto.randomUUID(),
         };
         const scopeText = scope?.toString();

package/esm/testing/contract/mod.d.ts

@@ -19,9 +19,9 @@
  * sequential case and fails the concurrent one, which is the whole
  * reason the suites exist.
  *
- * Each runner takes a factory + seed-helpers because `add` / `register`
- * methods aren't part of the public service interface — the consumer
- * tells the runner how to populate test data.
+ * The service runners take a factory plus seed helpers because `add` /
+ * `register` methods aren't part of the public service interfaces — the
+ * consumer tells the runner how to populate test data.
  *
  * @module
  */

package/esm/testing/contract/mod.js

@@ -19,9 +19,9 @@
  * sequential case and fails the concurrent one, which is the whole
  * reason the suites exist.
  *
- * Each runner takes a factory + seed-helpers because `add` / `register`
- * methods aren't part of the public service interface — the consumer
- * tells the runner how to populate test data.
+ * The service runners take a factory plus seed helpers because `add` /
+ * `register` methods aren't part of the public service interfaces — the
+ * consumer tells the runner how to populate test data.
  *
  * @module
  */

package/esm/testing/contract/tenant.d.ts

@@ -1,5 +1,5 @@
 /**
- * Contract test suite for a Udibo tenant's authorization answers: what
+ * Contract test suite for a Udibo Identity tenant's authorization answers: what
  * introspection reports about a signed-in person, what `GET /api/memberships`
  * lists for them, and what `POST /api/check` and `POST /api/check/batch`
  * answer.

package/esm/testing/contract/tenant.js

@@ -1,5 +1,5 @@
 /**
- * Contract test suite for a Udibo tenant's authorization answers: what
+ * Contract test suite for a Udibo Identity tenant's authorization answers: what
  * introspection reports about a signed-in person, what `GET /api/memberships`
  * lists for them, and what `POST /api/check` and `POST /api/check/batch`
  * answer.
@@ -32,7 +32,7 @@ import { encodeBasicAuth } from "../../utils/basic-auth.js";
  * safe as long as nothing else uses that namespace.
  */
 export function runTenantContractTests(options) {
-    describe(options.describeName ?? "Udibo tenant contract", () => {
+    describe(options.describeName ?? "Udibo Identity tenant contract", () => {
         let tenant;
         let metadata;
         let send;

package/esm/testing/mod.d.ts

@@ -1,7 +1,7 @@
 /**
  * Testing helpers for apps that use `@udibo/oauth2`.
  *
- * Two layers ship:
+ * Three layers ship:
  *
  * - **Testing surface for the OAuth2 protocol.** The recommended pattern
  *   for testing apps that use the resource server is to expose your
@@ -20,14 +20,16 @@
  * - **In-memory service implementations.** `MemoryUserService`,
  *   `MemoryClientService`, `MemoryTokenService`,
  *   `MemoryAuthorizationCodeService`, and `MemoryDeviceAuthorizationService`
- *   satisfy every server-side service contract, generic over the consumer's
+ *   implement the authorization server's user, client, token,
+ *   authorization-code and device-authorization service interfaces, generic
+ *   over the consumer's
  *   user / client / scope types. Suitable for tests, examples, and
  *   prototypes — never for production.
  *
- * - **A fake Udibo tenant.** {@link createFakeTenant} answers a tenant's
+ * - **A fake Udibo Identity tenant.** {@link createFakeTenant} answers a tenant's
  *   protocol surface and its `/api/check` questions over `fetch`, with the
  *   claims a real tenant issues — permissions, the organization picked at
- *   sign-in, and resource grants — so an app built on a Udibo tenant can test
+ *   sign-in, and resource grants — so an app built on a Udibo Identity tenant can test
  *   its own routes without running the identity service.
  *
  * Nothing in this module is an OAuth2 primitive — only testing support.

package/esm/testing/mod.js

@@ -1,7 +1,7 @@
 /**
  * Testing helpers for apps that use `@udibo/oauth2`.
  *
- * Two layers ship:
+ * Three layers ship:
  *
  * - **Testing surface for the OAuth2 protocol.** The recommended pattern
  *   for testing apps that use the resource server is to expose your
@@ -20,14 +20,16 @@
  * - **In-memory service implementations.** `MemoryUserService`,
  *   `MemoryClientService`, `MemoryTokenService`,
  *   `MemoryAuthorizationCodeService`, and `MemoryDeviceAuthorizationService`
- *   satisfy every server-side service contract, generic over the consumer's
+ *   implement the authorization server's user, client, token,
+ *   authorization-code and device-authorization service interfaces, generic
+ *   over the consumer's
  *   user / client / scope types. Suitable for tests, examples, and
  *   prototypes — never for production.
  *
- * - **A fake Udibo tenant.** {@link createFakeTenant} answers a tenant's
+ * - **A fake Udibo Identity tenant.** {@link createFakeTenant} answers a tenant's
  *   protocol surface and its `/api/check` questions over `fetch`, with the
  *   claims a real tenant issues — permissions, the organization picked at
- *   sign-in, and resource grants — so an app built on a Udibo tenant can test
+ *   sign-in, and resource grants — so an app built on a Udibo Identity tenant can test
  *   its own routes without running the identity service.
  *
  * Nothing in this module is an OAuth2 primitive — only testing support.

package/esm/testing/services.d.ts

@@ -1,5 +1,5 @@
 /**
- * In-memory implementations of every OAuth2 service interface.
+ * In-memory implementations of the authorization server's service interfaces.
  *
  * The `Memory*Service` family is the public, generic version of the fixtures
  * the library uses for its own tests. They satisfy the

package/esm/testing/services.js

@@ -1,5 +1,5 @@
 /**
- * In-memory implementations of every OAuth2 service interface.
+ * In-memory implementations of the authorization server's service interfaces.
  *
  * The `Memory*Service` family is the public, generic version of the fixtures
  * the library uses for its own tests. They satisfy the