@udibo/oauth2 0.1.0

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

@@ -0,0 +1,242 @@
+import type { ClientInterface } from "../../models/client.js";
+import type { AuthenticationContext } from "../../models/authentication.js";
+import type { RefreshToken, Token } from "../../models/token.js";
+import type { AbstractScope, BasicScope } from "../../models/scope.js";
+import type { ClientServiceInterface } from "./client.js";
+import type { UserServiceInterface } from "./user.js";
+/**
+ * Minimal interface for reading/validating tokens.
+ *
+ * This is all a resource server needs to authenticate requests.
+ * Implement this when your resource server validates tokens against
+ * an external authorization server (e.g., via introspection) or
+ * a shared token store.
+ */
+export interface TokenReaderInterface<Client extends ClientInterface, User, Scope extends AbstractScope = BasicScope> {
+    /** Retrieves an existing token by access token string. */
+    getToken(accessToken: string): Promise<Token<Client, User, Scope> | undefined>;
+}
+/**
+ * Full service interface for token lifecycle management.
+ *
+ * Extends {@linkcode TokenReaderInterface} with methods for generating,
+ * saving, and revoking tokens. Used by the authorization server and
+ * 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
+ * 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.
+ * `generateRefreshToken` and `refreshTokenExpiresAt` always receive a user:
+ * a token with no resource owner is never issued a refresh token.
+ */
+export interface TokenServiceInterface<Client extends ClientInterface, User, Scope extends AbstractScope = BasicScope> extends TokenReaderInterface<Client, User, Scope> {
+    /** Lifetime of access tokens in seconds. */
+    accessTokenLifetime: number;
+    /** Lifetime of refresh tokens in seconds. */
+    refreshTokenLifetime: number;
+    /**
+     * Validates and returns the accepted scope for a client and user. Return a
+     * scope to grant it (it may narrow the requested scope, RFC 6749 §3.3),
+     * `null`/`undefined` to accept the requested scope as-is, or `false` to
+     * reject with `invalid_scope`. `user` is `undefined` for a client acting as
+     * its own resource owner (client credentials).
+     * @returns The accepted scope, null/undefined to accept as-is, or false to reject.
+     */
+    acceptedScope(client: Client, user: User | undefined, scope?: Scope | null): Promise<Scope | null | undefined | false>;
+    /**
+     * Generates an access token string. `user` is `undefined` for a client
+     * acting as its own resource owner (client credentials) — a signed-token
+     * 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.
+     */
+    generateAccessToken(client: Client, user: User | undefined, scope?: Scope | null, authenticationContext?: AuthenticationContext): Promise<string>;
+    /** Generates a refresh token string. */
+    generateRefreshToken(client: Client, user: User, scope?: Scope | null): Promise<string | undefined>;
+    /**
+     * Gets the date that a new access token would expire at. `user` is
+     * `undefined` for a client acting as its own resource owner (client
+     * credentials).
+     */
+    accessTokenExpiresAt(client: Client, user: User | undefined, scope?: Scope | null): Promise<Date | undefined>;
+    /** Gets the date that a new refresh token would expire at. */
+    refreshTokenExpiresAt(client: Client, user: User, scope?: Scope | null): Promise<Date | undefined>;
+    /**
+     * Gets the absolute date a rotation family stops being refreshable, from the
+     * family's anchor ({@linkcode RefreshToken.familyCreatedAt}).
+     *
+     * **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
+     * 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
+     * service-wide version, which is what the abstract implementation reads).
+     *
+     * `user` is the refreshed token's own — `undefined` when the store returns a
+     * token that has none, so cap from the client alone in that case.
+     */
+    refreshTokenFamilyExpiresAt?(client: Client, user: User | undefined, familyCreatedAt: Date, scope?: Scope | null): Promise<Date | undefined>;
+    /** Retrieves an existing token by refresh token. */
+    getRefreshToken(refreshToken: string): Promise<RefreshToken<Client, User, Scope> | undefined>;
+    /** Persists a refresh token and returns the saved record. */
+    save(token: RefreshToken<Client, User, Scope>): Promise<RefreshToken<Client, User, Scope>>;
+    /** Persists an access token and returns the saved record. */
+    save(token: Token<Client, User, Scope>): Promise<Token<Client, User, Scope>>;
+    /**
+     * Persists either token kind and returns the saved record. Preserve
+     * `authenticationContext` on save and every read, including refresh and
+     * revoked records; never reconstruct it from a user's current session.
+     */
+    save(token: Token<Client, User, Scope> | RefreshToken<Client, User, Scope>): Promise<Token<Client, User, Scope> | RefreshToken<Client, User, Scope>>;
+    /** Revokes a token record. Resolves true if a token was revoked. */
+    revoke(token: Token<Client, User, Scope> | RefreshToken<Client, User, Scope>): Promise<boolean>;
+    /**
+     * Revokes a token by string, using `hint` (`access_token`/`refresh_token`,
+     * RFC 7009 §2.1) to disambiguate which kind to look up first.
+     */
+    revoke(token: string, hint?: string | null): Promise<boolean>;
+    /** Revokes a token given as a record or string. Resolves true if revoked. */
+    revoke(token: Token<Client, User, Scope> | RefreshToken<Client, User, Scope> | string, hint?: string | null): Promise<boolean>;
+    /**
+     * Revokes a refresh token that has just been superseded by rotation.
+     * Atomically claims the active token: resolves `true` once, and `false` for
+     * concurrent or repeated claims. The grant saves a successor only after a
+     * successful claim. Apply the same guarantee to `revoke` when it is the fallback.
+     *
+     * Rotation is bookkeeping inside a **continuing** grant: the person stays
+     * signed in and the successor token takes over. Implement this when
+     * {@linkcode revoke} carries end-of-grant side effects — ending the session
+     * the token belongs to, cascading to sibling records — so a routine refresh
+     * cannot terminate the very session it renews. When absent, the refresh
+     * grant falls back to {@linkcode revoke}.
+     */
+    revokeRotated?(token: RefreshToken<Client, User, Scope>): Promise<boolean>;
+    /**
+     * Revokes all tokens issued with the given authorization code.
+     * Returns true if any tokens were revoked (indicating code replay).
+     *
+     * Per RFC 6819 Section 4.4.1.1, if an authorization code is used more
+     * than once, the authorization server MUST revoke all tokens previously
+     * issued based on that authorization code.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc6819#section-4.4.1.1
+     */
+    revokeCode(code: string): Promise<boolean>;
+    /**
+     * Looks up a refresh token that has already been revoked/rotated out —
+     * the signal the refresh grant's reuse detection needs. Implement this
+     * (with {@linkcode revokeFamily}) by keeping revoked refresh-token records
+     * findable instead of deleting them; when absent, reuse detection is
+     * silently disabled.
+     */
+    getRevokedRefreshToken?(refreshToken: string): Promise<RefreshToken<Client, User, Scope> | undefined>;
+    /**
+     * Revokes every token belonging to a rotation family — called by the
+     * refresh grant when a rotated-out member is replayed, so a stolen token
+     * can't keep a session alive. Returns true if anything was revoked.
+     */
+    revokeFamily?(familyId: string): Promise<boolean>;
+}
+/** Options for configuring an abstract token service. */
+export interface AbstractTokenServiceOptions<Client extends ClientInterface, User> {
+    /** Lifetime of access tokens in seconds. Defaults to 3600 (1 hour). */
+    accessTokenLifetime?: number;
+    /** Lifetime of refresh tokens in seconds. Defaults to 1209600 (14 days). */
+    refreshTokenLifetime?: number;
+    /**
+     * 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`.
+     */
+    refreshTokenMaxLifetime?: number;
+    /** Client service for hydrating tokens. */
+    clientService?: ClientServiceInterface<Client, User>;
+    /** User service for hydrating tokens. */
+    userService?: UserServiceInterface<User>;
+}
+/**
+ * Abstract token service with sensible defaults for token generation.
+ *
+ * Provides default implementations for:
+ * - `acceptedScope` — accepts scope as-is
+ * - `generateAccessToken` / `generateRefreshToken` — crypto.randomUUID()
+ * - `accessTokenExpiresAt` / `refreshTokenExpiresAt` — based on lifetime settings
+ *
+ * Subclasses must implement the storage methods:
+ * `getToken`, `getRefreshToken`, `save`, `revoke`, `revokeCode`
+ */
+export declare abstract class AbstractTokenService<Client extends ClientInterface, User, Scope extends AbstractScope = BasicScope> implements TokenServiceInterface<Client, User, Scope> {
+    /** Lifetime of access tokens in seconds. */
+    accessTokenLifetime: number;
+    /** Lifetime of refresh tokens in seconds. */
+    refreshTokenLifetime: number;
+    /**
+     * Absolute lifetime of a refresh-token family in seconds, or `undefined` for
+     * an uncapped family. Enforced only through this class's
+     * {@linkcode refreshTokenFamilyExpiresAt}: an override that ignores it
+     * ignores the cap.
+     */
+    refreshTokenMaxLifetime?: number;
+    /** Client service used by subclasses to hydrate tokens. */
+    protected clientService?: ClientServiceInterface<Client, User>;
+    /** User service used by subclasses to hydrate tokens. */
+    protected userService?: UserServiceInterface<User>;
+    /**
+     * Lifetimes default to 3600 seconds (access) and 1209600 seconds / 14 days
+     * (refresh) when not supplied. `refreshTokenMaxLifetime` has no default —
+     * refresh-token families are uncapped unless one is configured.
+     *
+     * @throws {TypeError} If `refreshTokenLifetime` exceeds
+     * `refreshTokenMaxLifetime`, which would truncate every issued refresh token.
+     */
+    constructor(options?: AbstractTokenServiceOptions<Client, User>);
+    /**
+     * Accepts the requested scope unchanged. Override to narrow or reject scope
+     * (return `false` to reject with `invalid_scope`).
+     */
+    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>;
+    /** 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}. */
+    accessTokenExpiresAt(_client: Client, _user: User | undefined, _scope?: Scope | null): Promise<Date | undefined>;
+    /** Computes the refresh token expiry as now plus {@linkcode refreshTokenLifetime}. */
+    refreshTokenExpiresAt(_client: Client, _user: User, _scope?: Scope | null): Promise<Date | undefined>;
+    /**
+     * Computes the family's absolute expiry as its anchor plus
+     * {@linkcode refreshTokenMaxLifetime}, or `undefined` when no cap is
+     * configured. Override to cap per client instead of service-wide.
+     */
+    refreshTokenFamilyExpiresAt(_client: Client, _user: User | undefined, familyCreatedAt: Date, _scope?: Scope | null): Promise<Date | undefined>;
+    /** Retrieves a persisted token by its access token string. */
+    abstract getToken(accessToken: string): Promise<Token<Client, User, Scope> | undefined>;
+    /** Retrieves a persisted token by its refresh token string. */
+    abstract getRefreshToken(refreshToken: string): Promise<RefreshToken<Client, User, Scope> | undefined>;
+    /** Persists a refresh token and returns the saved record. */
+    abstract save(token: RefreshToken<Client, User, Scope>): Promise<RefreshToken<Client, User, Scope>>;
+    /** Persists an access token and returns the saved record. */
+    abstract save(token: Token<Client, User, Scope>): Promise<Token<Client, User, Scope>>;
+    /** Persists either token kind and returns the saved record. */
+    abstract save(token: Token<Client, User, Scope> | RefreshToken<Client, User, Scope>): Promise<Token<Client, User, Scope> | RefreshToken<Client, User, Scope>>;
+    /** Revokes a token record. Resolves true if a token was revoked. */
+    abstract revoke(token: Token<Client, User, Scope> | RefreshToken<Client, User, Scope>): Promise<boolean>;
+    /**
+     * Revokes a token by string, using `hint` (`access_token`/`refresh_token`,
+     * RFC 7009 §2.1) to disambiguate which kind to look up first.
+     */
+    abstract revoke(token: string, hint?: string | null): Promise<boolean>;
+    /** Revokes a token given as a record or string. Resolves true if revoked. */
+    abstract revoke(token: Token<Client, User, Scope> | RefreshToken<Client, User, Scope> | string, hint?: string | null): Promise<boolean>;
+    /**
+     * Revokes every token issued from the given authorization code, returning
+     * true if any were revoked (signaling code replay per RFC 6819 §4.4.1.1).
+     */
+    abstract revokeCode(code: string): Promise<boolean>;
+}

package/esm/server/services/token.js

@@ -0,0 +1,78 @@
+/**
+ * Abstract token service with sensible defaults for token generation.
+ *
+ * Provides default implementations for:
+ * - `acceptedScope` — accepts scope as-is
+ * - `generateAccessToken` / `generateRefreshToken` — crypto.randomUUID()
+ * - `accessTokenExpiresAt` / `refreshTokenExpiresAt` — based on lifetime settings
+ *
+ * Subclasses must implement the storage methods:
+ * `getToken`, `getRefreshToken`, `save`, `revoke`, `revokeCode`
+ */
+export class AbstractTokenService {
+    /** Lifetime of access tokens in seconds. */
+    accessTokenLifetime;
+    /** Lifetime of refresh tokens in seconds. */
+    refreshTokenLifetime;
+    /**
+     * Absolute lifetime of a refresh-token family in seconds, or `undefined` for
+     * an uncapped family. Enforced only through this class's
+     * {@linkcode refreshTokenFamilyExpiresAt}: an override that ignores it
+     * ignores the cap.
+     */
+    refreshTokenMaxLifetime;
+    /** Client service used by subclasses to hydrate tokens. */
+    clientService;
+    /** User service used by subclasses to hydrate tokens. */
+    userService;
+    /**
+     * Lifetimes default to 3600 seconds (access) and 1209600 seconds / 14 days
+     * (refresh) when not supplied. `refreshTokenMaxLifetime` has no default —
+     * refresh-token families are uncapped unless one is configured.
+     *
+     * @throws {TypeError} If `refreshTokenLifetime` exceeds
+     * `refreshTokenMaxLifetime`, which would truncate every issued refresh token.
+     */
+    constructor(options) {
+        this.accessTokenLifetime = options?.accessTokenLifetime ?? 3600;
+        this.refreshTokenLifetime = options?.refreshTokenLifetime ?? 1209600;
+        this.refreshTokenMaxLifetime = options?.refreshTokenMaxLifetime;
+        if (this.refreshTokenMaxLifetime !== undefined &&
+            this.refreshTokenLifetime > this.refreshTokenMaxLifetime) {
+            throw new TypeError("refreshTokenLifetime must not exceed refreshTokenMaxLifetime");
+        }
+        this.clientService = options?.clientService;
+        this.userService = options?.userService;
+    }
+    /**
+     * Accepts the requested scope unchanged. Override to narrow or reject scope
+     * (return `false` to reject with `invalid_scope`).
+     */
+    acceptedScope(_client, _user, scope) {
+        return Promise.resolve(scope);
+    }
+    /** Generates an opaque access token string. Override to issue a different format. */
+    generateAccessToken(_client, _user, _scope, _authenticationContext) {
+        return Promise.resolve(crypto.randomUUID());
+    }
+    /** Generates an opaque refresh token string. Override to issue a different format. */
+    generateRefreshToken(_client, _user, _scope) {
+        return Promise.resolve(crypto.randomUUID());
+    }
+    /** Computes the access token expiry as now plus {@linkcode accessTokenLifetime}. */
+    accessTokenExpiresAt(_client, _user, _scope) {
+        return Promise.resolve(new Date(Date.now() + this.accessTokenLifetime * 1000));
+    }
+    /** Computes the refresh token expiry as now plus {@linkcode refreshTokenLifetime}. */
+    refreshTokenExpiresAt(_client, _user, _scope) {
+        return Promise.resolve(new Date(Date.now() + this.refreshTokenLifetime * 1000));
+    }
+    /**
+     * Computes the family's absolute expiry as its anchor plus
+     * {@linkcode refreshTokenMaxLifetime}, or `undefined` when no cap is
+     * configured. Override to cap per client instead of service-wide.
+     */
+    refreshTokenFamilyExpiresAt(_client, _user, familyCreatedAt, _scope) {
+        return Promise.resolve(this.refreshTokenMaxLifetime == null ? undefined : new Date(familyCreatedAt.getTime() + this.refreshTokenMaxLifetime * 1000));
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Service interface for user management.
+ * Provides user lookup and authentication.
+ */
+export interface UserServiceInterface<User> {
+    /** Retrieves a user by their unique identifier. */
+    get(id: string): Promise<User | undefined>;
+    /**
+     * Retrieves an authenticated user if the username/password combination is
+     * correct.
+     *
+     * Only the password grant calls this, and the grant issues tokens for
+     * whatever user this returns — it applies **no second-factor check of its
+     * own**. This method is therefore the only place an MFA policy can be
+     * enforced on that flow: return `undefined` or throw for a user who owes a
+     * second factor, or accept that their password alone mints tokens.
+     *
+     * Throwing an OAuth2 error (e.g. `InvalidGrantError`) surfaces it on the
+     * token response as that error; anything else becomes a `server_error`.
+     */
+    getAuthenticated(username: string, password: string): Promise<User | undefined>;
+}
+/**
+ * The password hashing primitives, re-exported from the identity layer so a
+ * credential minted through one entrypoint verifies through the other. See
+ * `@udibo/oauth2/identity` for the work-factor constants and the
+ * `PasswordIdentityService` that records them on the credential.
+ */
+export { generateSalt, hashPassword, verifyPassword, } from "../../identity/password.js";

package/esm/server/services/user.js

@@ -0,0 +1,7 @@
+/**
+ * The password hashing primitives, re-exported from the identity layer so a
+ * credential minted through one entrypoint verifies through the other. See
+ * `@udibo/oauth2/identity` for the work-factor constants and the
+ * `PasswordIdentityService` that records them on the credential.
+ */
+export { generateSalt, hashPassword, verifyPassword, } from "../../identity/password.js";

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

@@ -0,0 +1,201 @@
+/**
+ * OIDC signing keys and compact JWS signing — Web Crypto only, no
+ * dependencies. Backs id_token issuance, the JWKS endpoint, and the optional
+ * signed (JWT) access-token generator.
+ *
+ * Keys are ES256 (the OIDC-recommended default with broad library support).
+ * Generate once with {@link generateSigningKey}, persist via
+ * {@link exportSigningKeyJwk}, and load on boot with {@link importSigningKeyJwk}
+ * so every instance of a multi-instance deploy signs with the same key (an
+ * ephemeral per-instance key would fail verification across instances).
+ *
+ * @module
+ */
+import type { AuthenticationContext } from "../models/authentication.js";
+/** A ready-to-use signing key: private half signs, public JWK is published. */
+export interface SigningKey {
+    /** Key id, stamped into JWS headers and the JWKS entry. */
+    kid: string;
+    /** JWS algorithm. Always `ES256` today. */
+    alg: "ES256";
+    /** The private key used to sign. */
+    privateKey: CryptoKey;
+    /** The public JWK (no private material) served from the JWKS endpoint. */
+    publicJwk: JsonWebKey & {
+        kid: string;
+        alg: string;
+        use: string;
+    };
+}
+/**
+ * Provides the server's current signing key. A provider seam so key storage
+ * and rotation stay app-owned; {@link StaticSigningKeyProvider} covers the
+ * single-key case.
+ */
+export interface SigningKeyProvider {
+    /** The key new tokens are signed with. */
+    getSigningKey(): Promise<SigningKey>;
+    /** Every public key a verifier may need (current + not-yet-expired old). */
+    getPublicJwks(): Promise<{
+        keys: JsonWebKey[];
+    }>;
+}
+/** A {@link SigningKeyProvider} over one fixed key. */
+export declare class StaticSigningKeyProvider implements SigningKeyProvider {
+    #private;
+    /** Fixes the single key this provider signs with and publishes. */
+    constructor(key: SigningKey);
+    /** The fixed key passed at construction. */
+    getSigningKey(): Promise<SigningKey>;
+    /** A JWKS containing only the fixed key's public JWK. */
+    getPublicJwks(): Promise<{
+        keys: JsonWebKey[];
+    }>;
+}
+/** Options for {@link RotatingSigningKeyProvider}. */
+export interface RotatingSigningKeyProviderOptions {
+    /** The key new tokens are signed with. Its `kid` is stamped into every JWS. */
+    current: SigningKey;
+    /**
+     * Keys retired from signing but still published in JWKS so tokens minted
+     * before the rotation keep verifying. Omit (or pass `[]`) for the single-key
+     * steady state, where this provider behaves exactly like
+     * {@link StaticSigningKeyProvider}.
+     */
+    previous?: SigningKey[];
+}
+/**
+ * A {@link SigningKeyProvider} for rotating the signing key through a JWKS
+ * grace window: sign with {@link RotatingSigningKeyProviderOptions.current}
+ * only, while {@link RotatingSigningKeyProviderOptions.previous} keys stay
+ * published so outstanding tokens keep validating until they expire and every
+ * consumer has refetched JWKS.
+ *
+ * Rotation is: promote the new key to `current`, move the old one into
+ * `previous`, and hold that grace window for at least the longest token
+ * lifetime before dropping the old key from `previous`. Because
+ * {@link signJwt} stamps the current key's `kid` into every JWS header and each
+ * published JWK carries its own `kid`, verifiers select the right key by `kid`
+ * across the window. Keys are published current-first and de-duplicated by
+ * `kid`.
+ *
+ * A single-key configuration (`previous` empty or omitted) publishes exactly
+ * the one key and is behaviourally identical to
+ * {@link StaticSigningKeyProvider} — adopting this provider does not change a
+ * deployment that has not started a rotation.
+ *
+ * @example
+ * ```ts
+ * const provider = new RotatingSigningKeyProvider({
+ *   current: await importSigningKeyJwk(JSON.parse(currentJwk)),
+ *   previous: [await importSigningKeyJwk(JSON.parse(oldJwk))],
+ * });
+ * ```
+ */
+export declare class RotatingSigningKeyProvider implements SigningKeyProvider {
+    #private;
+    /** Fixes the current signing key and the published set (current + previous). */
+    constructor(options: RotatingSigningKeyProviderOptions);
+    /** The current key — the only key new tokens are ever signed with. */
+    getSigningKey(): Promise<SigningKey>;
+    /** Public JWKs for the current key and every still-published previous key. */
+    getPublicJwks(): Promise<{
+        keys: JsonWebKey[];
+    }>;
+}
+/** Maps a user to a JWT `sub` claim: the user's `id` property, else the user itself. */
+export declare function defaultSubjectOf(user: unknown): string;
+/** Generate a fresh ES256 signing key with a random `kid`. */
+export declare function generateSigningKey(): Promise<SigningKey>;
+/**
+ * Export a signing key (including private material) as a JWK for persistence
+ * — e.g. into a secret-manager entry the app loads on boot. Guard it like any
+ * credential.
+ */
+export declare function exportSigningKeyJwk(key: SigningKey): Promise<JsonWebKey & {
+    kid: string;
+}>;
+/** Import a signing key previously exported with {@link exportSigningKeyJwk}. */
+export declare function importSigningKeyJwk(jwk: JsonWebKey & {
+    kid?: string;
+}): Promise<SigningKey>;
+/**
+ * Sign a compact JWS (`header.payload.signature`) with the given key —
+ * the primitive behind id_tokens and JWT access tokens.
+ */
+export declare function signJwt(key: SigningKey, payload: Record<string, unknown>, header?: Record<string, unknown>): Promise<string>;
+/** Options for {@link verifyJwt}. */
+export interface VerifyJwtOptions {
+    /**
+     * Accept a payload whose `exp` has passed. Only for a token used as a
+     * **hint** rather than as authority — OIDC RP-Initiated Logout's
+     * `id_token_hint` is the case this exists for, since the id_token naming the
+     * session to end has usually outlived its own lifetime by the time anyone
+     * logs out. Never set it for a token that authorizes something.
+     *
+     * @default false
+     */
+    ignoreExpiration?: boolean;
+}
+/**
+ * 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.
+ */
+export declare function verifyJwt(jwt: string, publicJwk: JsonWebKey, options?: VerifyJwtOptions): Promise<Record<string, unknown> | undefined>;
+/**
+ * Build a `generateAccessToken` implementation that issues **signed JWT
+ * access tokens** (RFC 9068 `at+jwt`) instead of opaque strings — the
+ * "verifiable signed-token option": resource servers can validate offline
+ * against the JWKS endpoint. Wire it into your token service:
+ *
+ * ```ts
+ * class JwtTokenService extends MyTokenService {
+ *   override generateAccessToken = createJwtAccessTokenGenerator({
+ *     signingKeys, issuer: "https://auth.example.com",
+ *   });
+ * }
+ * ```
+ *
+ * The token store still persists the (hashed) JWT string, so revocation and
+ * introspection keep working exactly as with opaque tokens.
+ */
+export declare function createJwtAccessTokenGenerator(options: {
+    /** Keys the tokens are signed with (also served from JWKS). */
+    signingKeys: SigningKeyProvider;
+    /** The `iss` claim — must match the advertised issuer. */
+    issuer: string;
+    /**
+     * The `aud` claim — per RFC 9068 an identifier of the resource server(s)
+     * the token is intended for (e.g. `https://api.example.com`). Defaults to
+     * the client id, which single-resource validators must then accept.
+     */
+    audience?: string;
+    /** Token lifetime in seconds for the `exp` claim. Defaults to 3600. */
+    lifetimeSeconds?: number;
+    /** Maps a user to the `sub` claim. Defaults to the user's `id` property. */
+    subjectOf?: (user: unknown) => string;
+    /**
+     * Extra claims for the resource owner's tokens — the same seam
+     * `AuthorizationServer`'s `userClaims` option gives the id_token, so one
+     * claims computation can feed both. Called only when a user is present: a
+     * client-credentials token has no resource owner, so it never carries user
+     * claims. The protocol claims (`iss`, `sub`, `aud`, `client_id`, `iat`,
+     * `exp`, `jti`, `scope`) always win — a returned claim under one of those
+     * names is discarded, never merged.
+     * The fourth argument is the token's recorded authentication event. Return
+     * its fields to emit them, without consulting a newer session. Custom token
+     * service wrappers must forward the fourth `generateAccessToken` argument.
+     */
+    userClaims?: (user: unknown, scope?: {
+        toString(): string;
+    } | null, client?: {
+        id: string;
+    }, authenticationContext?: AuthenticationContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
+}): (client: {
+    id: string;
+}, user: unknown, scope?: {
+    toString(): string;
+} | null, authenticationContext?: AuthenticationContext) => Promise<string>;