@julr/sesame 0.5.1 → 0.6.0

package/build/src/types.d.ts

@@ -1,4 +1,6 @@
 import type { HttpContext } from '@adonisjs/core/http';
+import type { JWK } from 'jose';
+import type { OAuthUserProviderContract } from './guard/types.ts';
 /**
  * Augment this interface via module augmentation to enable
  * type-safe scope names across the application.
@@ -47,6 +49,46 @@ export type InferScopes<T extends {
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.1
  */
 export declare const BUILTIN_SCOPES: Set<string>;
+/**
+ * OIDC-recognized scopes that are accepted by server-level validation
+ * without needing to be declared in the config `scopes` map.
+ *
+ * Unlike `BUILTIN_SCOPES`, these still require explicit client authorization
+ * via `ClientService.validateClientScopes()`.
+ */
+export declare const OIDC_SCOPES: Set<string>;
+/**
+ * Protocol-managed claims that must never be overridden by `getOidcClaims()`.
+ */
+export declare const RESERVED_OIDC_CLAIMS: Set<string>;
+/**
+ * Interface for User models that provide OIDC claims.
+ * Implement this on your User model to include custom claims
+ * in id_tokens and /userinfo responses.
+ *
+ * If not implemented, only protocol-level claims (sub, iss, aud, exp, iat)
+ * are included.
+ */
+export interface OidcSubject {
+    getOidcClaims(scopes: Scope[]): Record<string, unknown> | Promise<Record<string, unknown>>;
+}
+/**
+ * Collect OIDC claims based on the granted scopes.
+ *
+ * Maps each scope to its corresponding claims object and merges
+ * only the claims for scopes present in the granted set.
+ *
+ * @example
+ * ```ts
+ * getOidcClaims(scopes: Scope[]) {
+ *   return collectOidcClaims(scopes, {
+ *     profile: { name: this.fullName },
+ *     email: { email: this.email },
+ *   })
+ * }
+ * ```
+ */
+export declare function collectOidcClaims(scopes: Scope[], claimsMap: Partial<Record<Scope, Record<string, unknown>>>): Record<string, unknown>;
 /**
  * Supported OAuth 2.1 grant types.
  *
@@ -59,6 +101,39 @@ export declare const BUILTIN_SCOPES: Set<string>;
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-6
  */
 export type GrantType = 'authorization_code' | 'refresh_token' | 'client_credentials';
+/**
+ * Options for creating an OAuth client programmatically.
+ */
+export interface CreateClientOptions {
+    name: string;
+    redirectUris: string[];
+    scopes?: string[];
+    grantTypes?: GrantType[];
+    isPublic?: boolean;
+    requirePkce?: boolean;
+    userId?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for updating an existing OAuth client.
+ */
+export interface UpdateClientOptions {
+    name?: string;
+    redirectUris?: string[];
+    scopes?: string[];
+    grantTypes?: GrantType[];
+    isDisabled?: boolean;
+    requirePkce?: boolean;
+    metadata?: Record<string, any>;
+}
+/**
+ * Result returned when creating a client.
+ * Includes the raw secret (only available at creation time).
+ */
+export interface CreateClientResult {
+    client: import('./models/oauth_client.ts').OAuthClient;
+    clientSecret: string | null;
+}
 /**
  * User-facing configuration interface for Sésame.
  *
@@ -100,6 +175,18 @@ export interface SesameConfig {
      * Defaults to '30d'.
      */
     refreshTokenTtl?: string;
+    /**
+     * Grace period (in seconds) during which a recently-rotated
+     * refresh token is still accepted instead of triggering
+     * replay-attack detection. Handles race conditions in
+     * multi-process clients (e.g. MCP SDK).
+     *
+     * Set to `0` to disable (strict rotation, no grace period).
+     * Defaults to `120` (2 minutes).
+     *
+     * @see https://auth0.com/docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation
+     */
+    refreshTokenRotationGracePeriod?: number;
     /**
      * Access token TTL for the client_credentials grant (M2M).
      * Defaults to `accessTokenTtl`.
@@ -142,6 +229,27 @@ export interface SesameConfig {
      * Defaults to `false`.
      */
     allowPublicRegistration?: boolean;
+    /**
+     * JWK (JSON Web Key) for signing ID tokens.
+     * Must be an RSA private key in JWK format.
+     * Required together with `oidcProvider` when OIDC scopes (openid) are used.
+     * Passed via env var, parsed at boot, lives in memory.
+     */
+    jwk?: JWK;
+    /**
+     * User provider used by OIDC flows to resolve the subject for
+     * `id_token` emission and `/userinfo`.
+     *
+     * This is independent from `@adonisjs/auth` guards. The provider is
+     * configured once for the authorization server and must be stable for
+     * the issuer. Required together with `jwk` to enable OIDC.
+     */
+    oidcProvider?: OAuthUserProviderContract<unknown>;
+    /**
+     * ID token TTL as a string duration (e.g. '1h', '10m').
+     * Defaults to '1h'.
+     */
+    idTokenTtl?: string;
 }
 /**
  * Fully resolved configuration with defaults applied.
@@ -155,12 +263,16 @@ export interface ResolvedSesameConfig {
     accessTokenTtl: string;
     clientCredentialsAccessTokenTtl: string;
     refreshTokenTtl: string;
+    refreshTokenRotationGracePeriod: number;
     authorizationCodeTtl: string;
     authorizationRequestTtl: string;
     loginPage: string | ((ctx: HttpContext, params: URLSearchParams) => string);
     consentPage: string | ((ctx: HttpContext, params: URLSearchParams) => string);
     allowDynamicRegistration: boolean;
     allowPublicRegistration: boolean;
+    jwk?: JWK;
+    oidcProvider?: OAuthUserProviderContract<unknown>;
+    idTokenTtl: string;
 }
 /**
  * OAuth 2.0 Authorization Server Metadata as defined by RFC 8414.

package/build/stubs/main.ts

@@ -0,0 +1,5 @@
+/**
+ * Path to the root directory where the stubs are stored. We use
+ * this path within commands and the configure hook
+ */
+export const stubsRoot = import.meta.dirname

package/build/stubs/migrations/create_oauth_authorization_codes_table.stub

@@ -15,6 +15,7 @@ export default class extends BaseSchema {
       table.text('redirect_uri').notNullable()
       table.string('code_challenge').nullable()
       table.string('code_challenge_method').nullable()
+      table.string('nonce').nullable()
       table.timestamp('expires_at').notNullable()
       table.timestamp('created_at').notNullable()
       table.timestamp('updated_at').notNullable()

package/build/stubs/migrations/create_oauth_pending_authorization_requests_table.stub

@@ -21,6 +21,7 @@ export default class extends BaseSchema {
       table.string('state').nullable()
       table.string('code_challenge').nullable()
       table.string('code_challenge_method').nullable()
+      table.string('nonce').nullable()
       table.timestamp('expires_at').notNullable()
       table.timestamp('created_at').notNullable()
     })

package/build/stubs/migrations/create_oauth_refresh_tokens_table.stub

@@ -9,7 +9,7 @@ export default class extends BaseSchema {
     this.schema.createTable(this.tableName, (table) => {
       table.uuid('id').primary()
       table.string('token').notNullable().index()
-      table.string('access_token_id').notNullable()
+      table.uuid('access_token_id').notNullable()
       table.string('client_id').notNullable().references('client_id').inTable('oauth_clients').onDelete('CASCADE')
       table.string('user_id').notNullable()
       table.json('scopes').notNullable()

package/build/token_controller-DyI7oy-U.js

@@ -0,0 +1,481 @@
+import "./chunk-DF48asd8.js";
+import { a as OAuthRefreshToken, c as OIDC_SCOPES, i as OAuthAuthorizationCode, o as ClientService, s as BUILTIN_SCOPES, t as SesameManager } from "./sesame_manager-DYUSZ0NC.js";
+import "./oauth_client-BSanvSql.js";
+import { a as E_INVALID_GRANT, o as E_INVALID_REQUEST, r as E_INVALID_CLIENT, s as E_INVALID_SCOPE, u as E_UNSUPPORTED_GRANT_TYPE } from "./oauth_error-C7UhDb2q.js";
+import { t as OAuthAccessToken } from "./oauth_access_token-Cz_5gNBx.js";
+import { t as TokenService } from "./token_service-DwnfAR9F.js";
+import { t as IdTokenService } from "./id_token_service-CpTzOUDe.js";
+import { DateTime } from "luxon";
+import { createHash } from "node:crypto";
+import string from "@adonisjs/core/helpers/string";
+import vine from "@vinejs/vine";
+//#region src/actions/exchange_authorization_code.ts
+/**
+* Validates the code_verifier format per RFC 7636 §4.1.
+* 43-128 characters from the unreserved character set [A-Za-z0-9-._~].
+*/
+const codeVerifierValidator = vine.create({ code_verifier: vine.string().minLength(43).maxLength(128).regex(/^[A-Za-z0-9\-._~]+$/) });
+/**
+* Handle the Authorization Code Grant (RFC 6749 §4.1.3).
+*
+* Exchanges an authorization code for an access token and
+* optionally a refresh token and id_token. Verifies PKCE,
+* validates scopes, and atomically consumes the code to
+* prevent replay.
+*
+* @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3
+* @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.6
+*/
+var ExchangeAuthorizationCodeAction = class {
+	/**
+	* Exchange an authorization code for tokens. The code is
+	* consumed atomically inside a transaction.
+	*/
+	async execute(manager, input) {
+		const tokenService = new TokenService(manager);
+		const clientService = new ClientService();
+		if (!input.client.grantTypes.includes("authorization_code")) throw new E_INVALID_CLIENT("Client is not allowed to use the authorization_code grant");
+		const authCode = await this.#validateAuthorizationCode(tokenService, input);
+		await this.#verifyPkce(input.codeVerifier, authCode);
+		clientService.validateClientScopes(authCode.scopes, input.client.scopes);
+		const accessToken = tokenService.createAccessToken();
+		const refreshToken = this.#prepareRefreshToken(manager, tokenService);
+		const idToken = await this.#prepareIdToken(manager, authCode, input.client, accessToken.raw);
+		await this.#atomicExchange(input, authCode, accessToken, refreshToken);
+		const ttlSeconds = string.seconds.parse(manager.config.accessTokenTtl);
+		return {
+			access_token: accessToken.raw,
+			token_type: "Bearer",
+			expires_in: ttlSeconds,
+			scope: authCode.scopes.join(" "),
+			...refreshToken ? { refresh_token: refreshToken.raw } : {},
+			...idToken ? { id_token: idToken } : {}
+		};
+	}
+	/**
+	* Lookup the authorization code by hash and validate
+	* it has not expired and matches the redirect_uri.
+	*/
+	async #validateAuthorizationCode(tokenService, input) {
+		if (!input.code) throw new E_INVALID_REQUEST("Missing required parameter: code");
+		if (!input.redirectUri) throw new E_INVALID_REQUEST("Missing required parameter: redirect_uri");
+		const hashedCode = tokenService.hashToken(input.code);
+		const authCode = await OAuthAuthorizationCode.query().where("code", hashedCode).where("clientId", input.client.clientId).first();
+		if (!authCode) throw new E_INVALID_GRANT("Authorization code not found");
+		if (authCode.expiresAt < DateTime.now()) {
+			await OAuthAuthorizationCode.query().where("id", authCode.id).delete();
+			throw new E_INVALID_GRANT("Authorization code has expired");
+		}
+		if (authCode.redirectUri !== input.redirectUri) throw new E_INVALID_GRANT("Redirect URI mismatch");
+		return authCode;
+	}
+	/**
+	* Verify the PKCE code_verifier against the stored
+	* code_challenge using S256 (mandatory per OAuth 2.1).
+	*/
+	async #verifyPkce(codeVerifier, authCode) {
+		const [verifierError] = await codeVerifierValidator.tryValidate({ code_verifier: codeVerifier });
+		if (verifierError) {
+			await OAuthAuthorizationCode.query().where("id", authCode.id).delete();
+			throw new E_INVALID_REQUEST("code_verifier must be 43-128 characters using only [A-Za-z0-9-._~] (RFC 7636 §4.1)");
+		}
+		if (!authCode.codeChallenge) {
+			await OAuthAuthorizationCode.query().where("id", authCode.id).delete();
+			throw new E_INVALID_GRANT("Authorization code is missing PKCE challenge");
+		}
+		if (createHash("sha256").update(codeVerifier).digest("base64url") !== authCode.codeChallenge) {
+			await OAuthAuthorizationCode.query().where("id", authCode.id).delete();
+			throw new E_INVALID_GRANT("PKCE verification failed");
+		}
+	}
+	/**
+	* Precompute refresh token values if the refresh_token
+	* grant type is enabled on the server.
+	*/
+	#prepareRefreshToken(manager, tokenService) {
+		if (!manager.isGrantTypeEnabled("refresh_token")) return null;
+		const { raw, hash } = tokenService.createRefreshToken();
+		const refreshTtl = string.seconds.parse(manager.config.refreshTokenTtl);
+		return {
+			raw,
+			hash,
+			expiresAt: DateTime.now().plus({ seconds: refreshTtl })
+		};
+	}
+	/**
+	* Build an id_token JWT if the authorization code was
+	* granted the openid scope.
+	*/
+	async #prepareIdToken(manager, authCode, client, accessTokenRaw) {
+		if (!authCode.scopes.includes("openid")) return null;
+		const idTokenService = new IdTokenService(manager);
+		const user = await manager.findUserById(authCode.userId);
+		if (!user) throw new E_INVALID_GRANT("OIDC user not found");
+		return idTokenService.sign({
+			sub: authCode.userId,
+			clientId: client.clientId,
+			scopes: authCode.scopes,
+			accessToken: accessTokenRaw,
+			user,
+			nonce: authCode.nonce ?? void 0
+		});
+	}
+	/**
+	* Atomically consume the authorization code and persist
+	* the new access token (and optionally refresh token)
+	* inside a single transaction.
+	*/
+	async #atomicExchange(input, authCode, accessToken, refreshToken) {
+		await OAuthAuthorizationCode.transaction(async (trx) => {
+			const deleteResult = await OAuthAuthorizationCode.query({ client: trx }).where("id", authCode.id).delete();
+			if ((Array.isArray(deleteResult) ? Number(deleteResult[0] ?? 0) : Number(deleteResult)) !== 1) throw new E_INVALID_GRANT("Authorization code has already been consumed");
+			const accessTokenId = crypto.randomUUID();
+			await OAuthAccessToken.create({
+				id: accessTokenId,
+				tokenHash: accessToken.hash,
+				clientId: input.client.clientId,
+				userId: authCode.userId,
+				scopes: authCode.scopes,
+				expiresAt: DateTime.fromJSDate(accessToken.expiresAt)
+			}, { client: trx });
+			if (refreshToken) await OAuthRefreshToken.create({
+				id: crypto.randomUUID(),
+				token: refreshToken.hash,
+				accessTokenId,
+				clientId: input.client.clientId,
+				userId: authCode.userId,
+				scopes: authCode.scopes,
+				expiresAt: refreshToken.expiresAt
+			}, { client: trx });
+		});
+	}
+};
+//#endregion
+//#region src/actions/exchange_refresh_token.ts
+/**
+* Handle the Refresh Token Grant (RFC 6749 §6).
+*
+* Exchanges a refresh token for a new access token and a new
+* refresh token (rotation). The old refresh token is revoked
+* immediately after use.
+*
+* ## Replay detection
+*
+* If a revoked refresh token is presented **outside** the grace
+* period, all tokens for that client+user pair are nuked to
+* mitigate stolen-token reuse (RFC 6819 §5.2.2.3, RFC 9700 §4.14.2).
+*
+* ## Grace period (rotation reuse window)
+*
+* OAuth 2.1 requires that rotated refresh tokens be single-use.
+* However, that requirement conflicts with the realities of
+* distributed systems: if the server rotates the token but the
+* client never receives (or persists) the new token — due to a
+* network failure, a concurrent refresh from another process, or
+* a retry after timeout — the client loses its grant permanently.
+*
+* To handle this, we allow a recently-rotated refresh token to be
+* reused within a short configurable window (`refreshTokenRotationGracePeriod`,
+* defaults to 120 s). During that window the old token issues fresh
+* tokens without triggering replay-attack revocation.
+*
+* This is the same approach used by Auth0 ("reuse interval") and
+* Cloudflare workers-oauth-provider ("previous token"). It provides
+* most of the security benefits of strict rotation while remaining
+* reliable for real-world clients (MCP SDK, multi-process CLIs, etc.).
+*
+* @see https://datatracker.ietf.org/doc/html/rfc6749#section-6
+* @see https://datatracker.ietf.org/doc/html/rfc6819#section-5.2.2.3
+* @see https://datatracker.ietf.org/doc/html/rfc9700#section-4.14.2
+*/
+var ExchangeRefreshTokenAction = class {
+	/**
+	* Rotate the refresh token, issue a new access token,
+	* and optionally reissue an id_token if openid scope
+	* is present.
+	*/
+	async execute(manager, input) {
+		const tokenService = new TokenService(manager);
+		const clientService = new ClientService();
+		if (!input.refreshToken) throw new E_INVALID_REQUEST("Missing required parameter: refresh_token");
+		if (!input.client.grantTypes.includes("refresh_token")) throw new E_INVALID_CLIENT("Client is not allowed to use the refresh_token grant");
+		const hashedToken = tokenService.hashToken(input.refreshToken);
+		const refreshToken = await OAuthRefreshToken.query().where("token", hashedToken).where("clientId", input.client.clientId).first();
+		if (!refreshToken) throw new E_INVALID_GRANT("Refresh token not found");
+		if (refreshToken.revokedAt) {
+			const gracePeriodSeconds = manager.config.refreshTokenRotationGracePeriod;
+			const revokedSecondsAgo = DateTime.now().diff(refreshToken.revokedAt, "seconds").seconds;
+			if (gracePeriodSeconds <= 0 || revokedSecondsAgo > gracePeriodSeconds) {
+				await this.#nukeTokensForReplay(input.client.clientId, refreshToken.userId);
+				throw new E_INVALID_GRANT("Refresh token has been revoked (possible replay attack)");
+			}
+			/**
+			* Within grace period — the old refresh token was recently
+			* rotated and a concurrent client is reusing it. Issue new
+			* tokens without nuking the family. This matches Auth0 / Okta
+			* behavior for handling race conditions in multi-process
+			* clients (e.g. MCP SDK proactive refresh + SDK 401 retry).
+			*/
+			return this.#issueFreshTokens(manager, input, refreshToken);
+		}
+		if (refreshToken.expiresAt < DateTime.now()) throw new E_INVALID_GRANT("Refresh token has expired");
+		const scopes = this.#resolveScopes(manager, input, refreshToken, clientService);
+		const accessToken = tokenService.createAccessToken();
+		const newRefreshToken = this.#prepareRefreshToken(manager, tokenService);
+		const idToken = await this.#prepareIdToken(manager, scopes, refreshToken, input.client, accessToken.raw);
+		await this.#atomicRotation(input, refreshToken, accessToken, newRefreshToken, scopes);
+		const ttlSeconds = string.seconds.parse(manager.config.accessTokenTtl);
+		return {
+			access_token: accessToken.raw,
+			token_type: "Bearer",
+			expires_in: ttlSeconds,
+			scope: scopes.join(" "),
+			refresh_token: newRefreshToken.raw,
+			...idToken ? { id_token: idToken } : {}
+		};
+	}
+	/**
+	* Grace-period reuse: the old refresh token was rotated
+	* recently and a concurrent client replayed it. Issue a
+	* brand-new AT + RT pair directly (the old pair is already
+	* revoked from the first rotation).
+	*/
+	async #issueFreshTokens(manager, input, revokedRefreshToken) {
+		const tokenService = new TokenService(manager);
+		const clientService = new ClientService();
+		const scopes = this.#resolveScopes(manager, input, revokedRefreshToken, clientService);
+		const accessToken = tokenService.createAccessToken();
+		const newRefreshToken = this.#prepareRefreshToken(manager, tokenService);
+		const idToken = await this.#prepareIdToken(manager, scopes, revokedRefreshToken, input.client, accessToken.raw);
+		const accessTokenId = crypto.randomUUID();
+		await OAuthAccessToken.create({
+			id: accessTokenId,
+			tokenHash: accessToken.hash,
+			clientId: input.client.clientId,
+			userId: revokedRefreshToken.userId,
+			scopes,
+			expiresAt: DateTime.fromJSDate(accessToken.expiresAt)
+		});
+		await OAuthRefreshToken.create({
+			id: crypto.randomUUID(),
+			token: newRefreshToken.hash,
+			accessTokenId,
+			clientId: input.client.clientId,
+			userId: revokedRefreshToken.userId,
+			scopes,
+			expiresAt: newRefreshToken.expiresAt
+		});
+		const ttlSeconds = string.seconds.parse(manager.config.accessTokenTtl);
+		return {
+			access_token: accessToken.raw,
+			token_type: "Bearer",
+			expires_in: ttlSeconds,
+			scope: scopes.join(" "),
+			refresh_token: newRefreshToken.raw,
+			...idToken ? { id_token: idToken } : {}
+		};
+	}
+	/**
+	* Replay detection: nuke all tokens for this client+user
+	* pair when a revoked token is reused.
+	*/
+	async #nukeTokensForReplay(clientId, userId) {
+		await OAuthRefreshToken.query().where("clientId", clientId).where("userId", userId).delete();
+		await OAuthAccessToken.query().where("clientId", clientId).where("userId", userId).whereNull("revokedAt").update({ revokedAt: DateTime.now().toSQL() });
+	}
+	/**
+	* Resolve the effective scopes for the new token. Supports
+	* scope narrowing but rejects scope escalation.
+	*/
+	#resolveScopes(manager, input, refreshToken, clientService) {
+		if (!input.scope) {
+			clientService.validateClientScopes(refreshToken.scopes, input.client.scopes);
+			return refreshToken.scopes;
+		}
+		const requested = input.scope.split(" ");
+		const originalSet = new Set(refreshToken.scopes);
+		const invalid = requested.filter((s) => !originalSet.has(s));
+		if (invalid.length > 0) throw new E_INVALID_SCOPE(`Scope not in original grant: ${invalid.join(", ")}`);
+		const invalidScopes = manager.validateScopes(requested);
+		if (invalidScopes.length > 0) throw new E_INVALID_SCOPE(`Invalid scopes: ${invalidScopes.join(", ")}`);
+		if (manager.usesOidcScopes(requested) && !manager.isOidcEnabled) throw new E_INVALID_SCOPE("OIDC scopes require OIDC to be configured (set jwk and oidcProvider in config)");
+		clientService.validateClientScopes(requested, input.client.scopes);
+		return requested;
+	}
+	/**
+	* Precompute the new refresh token values for rotation.
+	*/
+	#prepareRefreshToken(manager, tokenService) {
+		const { raw, hash } = tokenService.createRefreshToken();
+		const refreshTtl = string.seconds.parse(manager.config.refreshTokenTtl);
+		return {
+			raw,
+			hash,
+			expiresAt: DateTime.now().plus({ seconds: refreshTtl })
+		};
+	}
+	/**
+	* Reissue an id_token if openid scope is present.
+	* No nonce on refresh per OIDC Core §12.2.
+	*/
+	async #prepareIdToken(manager, scopes, refreshToken, client, accessTokenRaw) {
+		if (!scopes.includes("openid")) return null;
+		const idTokenService = new IdTokenService(manager);
+		const user = await manager.findUserById(refreshToken.userId);
+		if (!user) throw new E_INVALID_GRANT("OIDC user not found");
+		return idTokenService.sign({
+			sub: refreshToken.userId,
+			clientId: client.clientId,
+			scopes,
+			accessToken: accessTokenRaw,
+			user
+		});
+	}
+	/**
+	* Atomically revoke the old token pair and persist the
+	* new access + refresh tokens inside a single transaction.
+	*/
+	async #atomicRotation(input, oldRefreshToken, accessToken, newRefreshToken, scopes) {
+		await OAuthRefreshToken.transaction(async (trx) => {
+			const revokedAt = DateTime.now();
+			const updateResult = await OAuthRefreshToken.query({ client: trx }).where("id", oldRefreshToken.id).whereNull("revokedAt").update({ revokedAt: revokedAt.toSQL() });
+			if ((Array.isArray(updateResult) ? Number(updateResult[0] ?? 0) : Number(updateResult)) !== 1) throw new E_INVALID_GRANT("Refresh token has already been consumed");
+			await OAuthAccessToken.query({ client: trx }).where("id", oldRefreshToken.accessTokenId).whereNull("revokedAt").update({ revokedAt: revokedAt.toSQL() });
+			const accessTokenId = crypto.randomUUID();
+			await OAuthAccessToken.create({
+				id: accessTokenId,
+				tokenHash: accessToken.hash,
+				clientId: input.client.clientId,
+				userId: oldRefreshToken.userId,
+				scopes,
+				expiresAt: DateTime.fromJSDate(accessToken.expiresAt)
+			}, { client: trx });
+			await OAuthRefreshToken.create({
+				id: crypto.randomUUID(),
+				token: newRefreshToken.hash,
+				accessTokenId,
+				clientId: input.client.clientId,
+				userId: oldRefreshToken.userId,
+				scopes,
+				expiresAt: newRefreshToken.expiresAt
+			}, { client: trx });
+		});
+	}
+};
+//#endregion
+//#region src/actions/exchange_client_credentials.ts
+/**
+* Handle the Client Credentials Grant (RFC 6749 §4.4).
+*
+* Issues an access token directly to a confidential client
+* for machine-to-machine communication. No refresh token
+* is issued. User-centric OIDC scopes are rejected.
+*
+* @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.4
+*/
+var ExchangeClientCredentialsAction = class {
+	/**
+	* Validate the client, resolve scopes, and issue an
+	* access token for M2M usage.
+	*/
+	async execute(manager, input) {
+		const clientService = new ClientService();
+		if (input.client.isPublic) throw new E_INVALID_CLIENT("Public clients cannot use the client_credentials grant");
+		if (!input.client.grantTypes.includes("client_credentials")) throw new E_INVALID_CLIENT("Client is not allowed to use the client_credentials grant");
+		const scopes = this.#resolveScopes(manager, input, clientService);
+		if (!input.client.userId) throw new E_INVALID_CLIENT("Client must be associated with a user to use the client_credentials grant");
+		const tokenService = new TokenService(manager);
+		const ttlSeconds = string.seconds.parse(manager.config.clientCredentialsAccessTokenTtl);
+		const { raw: accessTokenRaw, hash: tokenHash } = tokenService.createAccessToken();
+		const expiresAt = new Date(Date.now() + ttlSeconds * 1e3);
+		await OAuthAccessToken.create({
+			id: crypto.randomUUID(),
+			tokenHash,
+			clientId: input.client.clientId,
+			userId: input.client.userId,
+			scopes,
+			expiresAt: DateTime.fromJSDate(expiresAt)
+		});
+		return {
+			access_token: accessTokenRaw,
+			token_type: "Bearer",
+			expires_in: ttlSeconds,
+			scope: scopes.join(" ")
+		};
+	}
+	/**
+	* Resolve and validate scopes. Falls back to the client's
+	* non-OIDC scopes when none are requested. Rejects any
+	* user-centric OIDC scopes.
+	*/
+	#resolveScopes(manager, input, clientService) {
+		const requestedScopes = input.scope ? input.scope.split(" ") : input.client.scopes.filter((scope) => !BUILTIN_SCOPES.has(scope) && !OIDC_SCOPES.has(scope));
+		const forbiddenRequested = requestedScopes.filter((scope) => BUILTIN_SCOPES.has(scope) || OIDC_SCOPES.has(scope));
+		if (forbiddenRequested.length > 0) throw new E_INVALID_SCOPE(`Scopes not allowed for client_credentials: ${forbiddenRequested.join(", ")}`);
+		const invalidScopes = manager.validateScopes(requestedScopes);
+		if (invalidScopes.length > 0) throw new E_INVALID_SCOPE(`Invalid scopes: ${invalidScopes.join(", ")}`);
+		clientService.validateClientScopes(requestedScopes, input.client.scopes);
+		return requestedScopes;
+	}
+};
+//#endregion
+//#region src/controllers/token_controller.ts
+/**
+* Handles the OAuth 2.0 Token Endpoint (RFC 6749 §3.2).
+*
+* Authenticates the client, extracts grant-specific params,
+* and dispatches to the appropriate action. Sets required
+* cache headers on all token responses.
+*
+* @see https://datatracker.ietf.org/doc/html/rfc6749#section-3.2
+*/
+var TokenController = class TokenController {
+	static validator = vine.create({ grant_type: vine.string() });
+	/**
+	* Validate the grant type, authenticate the client,
+	* and dispatch to the appropriate grant action.
+	*/
+	async handle(ctx) {
+		const manager = await ctx.containerResolver.make(SesameManager);
+		const body = ctx.request.body();
+		const [error, validated] = await TokenController.validator.tryValidate(body);
+		if (error) throw new E_UNSUPPORTED_GRANT_TYPE("Missing required parameter: grant_type");
+		if (!manager.isGrantTypeEnabled(validated.grant_type)) throw new E_UNSUPPORTED_GRANT_TYPE(`Grant type "${validated.grant_type}" is not enabled`);
+		const client = await new ClientService().authenticateClient({
+			authorizationHeader: ctx.request.header("authorization"),
+			bodyClientId: body.client_id,
+			bodyClientSecret: body.client_secret
+		});
+		const result = await this.#dispatchGrant(validated.grant_type, manager, client, body);
+		ctx.response.header("Cache-Control", "no-store");
+		ctx.response.header("Pragma", "no-cache");
+		return result;
+	}
+	/**
+	* Map each grant type to its action, extracting the
+	* relevant params from the request body.
+	*/
+	#dispatchGrant(grantType, manager, client, body) {
+		const handler = {
+			authorization_code: () => new ExchangeAuthorizationCodeAction().execute(manager, {
+				client,
+				code: body.code,
+				redirectUri: body.redirect_uri,
+				codeVerifier: body.code_verifier
+			}),
+			refresh_token: () => new ExchangeRefreshTokenAction().execute(manager, {
+				client,
+				refreshToken: body.refresh_token,
+				scope: body.scope
+			}),
+			client_credentials: () => new ExchangeClientCredentialsAction().execute(manager, {
+				client,
+				scope: body.scope
+			})
+		}[grantType];
+		if (!handler) throw new E_UNSUPPORTED_GRANT_TYPE(`Unsupported grant type: ${grantType}`);
+		return handler();
+	}
+};
+//#endregion
+export { TokenController as default };