@julr/sesame 0.5.1 → 0.7.0

package/build/token_controller-DRatCQNT.js

@@ -0,0 +1,492 @@
+import { n as OIDC_SCOPES, t as BUILTIN_SCOPES } from "./types-DEtn2Zdb.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-CvxtZvjp.js";
+import { n as ClientService, t as SesameManager } from "./sesame_manager-CeEmlzba.js";
+import { t as TokenService } from "./token_service-DDQ3Dxaj.js";
+import { t as IdTokenService } from "./id_token_service-BtBUiL_n.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(manager, tokenService, input);
+		await this.#verifyPkce(manager, 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(manager, 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(manager, 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 store = manager.store;
+		const authCode = await store.findAuthorizationCode({
+			code: hashedCode,
+			clientId: input.client.clientId
+		});
+		if (!authCode) throw new E_INVALID_GRANT("Authorization code not found");
+		if (authCode.expiresAt < DateTime.now()) {
+			await store.deleteAuthorizationCode(authCode.id);
+			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(manager, codeVerifier, authCode) {
+		const store = manager.store;
+		const [verifierError] = await codeVerifierValidator.tryValidate({ code_verifier: codeVerifier });
+		if (verifierError) {
+			await store.deleteAuthorizationCode(authCode.id);
+			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 store.deleteAuthorizationCode(authCode.id);
+			throw new E_INVALID_GRANT("Authorization code is missing PKCE challenge");
+		}
+		if (createHash("sha256").update(codeVerifier).digest("base64url") !== authCode.codeChallenge) {
+			await store.deleteAuthorizationCode(authCode.id);
+			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(manager, input, authCode, accessToken, refreshToken) {
+		const store = manager.store;
+		const accessTokenId = crypto.randomUUID();
+		if (!await store.exchangeAuthorizationCode({
+			codeId: authCode.id,
+			accessToken: {
+				id: accessTokenId,
+				tokenHash: accessToken.hash,
+				clientId: input.client.clientId,
+				userId: authCode.userId,
+				scopes: authCode.scopes,
+				expiresAt: DateTime.fromJSDate(accessToken.expiresAt)
+			},
+			refreshToken: refreshToken ? {
+				id: crypto.randomUUID(),
+				token: refreshToken.hash,
+				accessTokenId,
+				clientId: input.client.clientId,
+				userId: authCode.userId,
+				scopes: authCode.scopes,
+				expiresAt: refreshToken.expiresAt
+			} : null
+		})) throw new E_INVALID_GRANT("Authorization code has already been consumed");
+	}
+};
+//#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 manager.store.findRefreshToken({
+			hash: hashedToken,
+			clientId: input.client.clientId
+		});
+		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(manager, 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(manager, 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 manager.store.issueTokenPair({
+			accessToken: {
+				id: accessTokenId,
+				tokenHash: accessToken.hash,
+				clientId: input.client.clientId,
+				userId: revokedRefreshToken.userId,
+				scopes,
+				expiresAt: DateTime.fromJSDate(accessToken.expiresAt)
+			},
+			refreshToken: {
+				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(manager, clientId, userId) {
+		await manager.store.revokeTokenFamily({
+			clientId,
+			userId,
+			now: DateTime.now()
+		});
+	}
+	/**
+	* 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(manager, input, oldRefreshToken, accessToken, newRefreshToken, scopes) {
+		const store = manager.store;
+		const accessTokenId = crypto.randomUUID();
+		if (!await store.rotateRefreshToken({
+			oldRefreshTokenId: oldRefreshToken.id,
+			oldAccessTokenId: oldRefreshToken.accessTokenId,
+			revokedAt: DateTime.now(),
+			accessToken: {
+				id: accessTokenId,
+				tokenHash: accessToken.hash,
+				clientId: input.client.clientId,
+				userId: oldRefreshToken.userId,
+				scopes,
+				expiresAt: DateTime.fromJSDate(accessToken.expiresAt)
+			},
+			refreshToken: {
+				id: crypto.randomUUID(),
+				token: newRefreshToken.hash,
+				accessTokenId,
+				clientId: input.client.clientId,
+				userId: oldRefreshToken.userId,
+				scopes,
+				expiresAt: newRefreshToken.expiresAt
+			}
+		})) throw new E_INVALID_GRANT("Refresh token has already been consumed");
+	}
+};
+//#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 manager.store.createAccessToken({
+			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(manager).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 };

package/build/token_service-DDQ3Dxaj.js

@@ -0,0 +1,59 @@
+import { createHash, randomBytes } from "node:crypto";
+import string from "@adonisjs/core/helpers/string";
+//#region src/services/token_service.ts
+/**
+* Handles opaque token generation for access tokens, refresh tokens,
+* and authorization codes.
+*
+* All tokens are random opaque values. Only their SHA-256 hashes
+* are stored in the database, so the raw tokens cannot be
+* reconstructed from a database leak.
+*/
+var TokenService = class {
+	#manager;
+	constructor(manager) {
+		this.#manager = manager;
+	}
+	/**
+	* Create an opaque access token. Returns the raw token
+	* (sent to the client), its SHA-256 hash (stored in DB),
+	* and the computed expiration date.
+	*/
+	createAccessToken() {
+		const raw = this.generateOpaqueToken();
+		const ttlSeconds = string.seconds.parse(this.#manager.config.accessTokenTtl);
+		return {
+			raw,
+			hash: this.hashToken(raw),
+			expiresAt: new Date(Date.now() + ttlSeconds * 1e3)
+		};
+	}
+	/**
+	* Create an opaque refresh token. Returns the raw token
+	* (sent to the client) and its SHA-256 hash (stored in DB).
+	*/
+	createRefreshToken() {
+		const raw = this.generateOpaqueToken();
+		return {
+			raw,
+			hash: this.hashToken(raw)
+		};
+	}
+	/**
+	* Generate a cryptographically random opaque token
+	* (32 bytes, base64url-encoded).
+	*/
+	generateOpaqueToken() {
+		return randomBytes(32).toString("base64url");
+	}
+	/**
+	* SHA-256 hash a token value for secure storage.
+	* All tokens (codes, access tokens, refresh tokens) are stored
+	* as hashes so raw values cannot be reconstructed from a DB leak.
+	*/
+	hashToken(token) {
+		return createHash("sha256").update(token).digest("base64url");
+	}
+};
+//#endregion
+export { TokenService as t };

package/build/types-DEtn2Zdb.js

@@ -0,0 +1,75 @@
+//#region src/types.ts
+/**
+* Standard OAuth/OIDC scopes that are always valid regardless
+* of server or client scope configuration.
+*
+* These scopes are:
+* - Accepted during scope validation (client and server level)
+* - Advertised in `scopes_supported` of all metadata endpoints
+*   (protected resource, OIDC discovery) so MCP clients know
+*   they can request them
+*
+* - `offline_access`: signals that the client needs a refresh token
+*   (OIDC Core §11). Note: Sesame issues refresh tokens by default
+*   when the `refresh_token` grant is enabled, regardless of whether
+*   the client requests this scope (per RFC 6749 §5.1). This scope
+*   is still advertised for clients that check metadata before
+*   building their authorization request.
+*
+* @see https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess
+* @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.1
+*/
+const BUILTIN_SCOPES = /* @__PURE__ */ new Set(["offline_access"]);
+/**
+* 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()`.
+*/
+const OIDC_SCOPES = /* @__PURE__ */ new Set([
+	"openid",
+	"profile",
+	"email"
+]);
+/**
+* Protocol-managed claims that must never be overridden by `getOidcClaims()`.
+*/
+const RESERVED_OIDC_CLAIMS = /* @__PURE__ */ new Set([
+	"sub",
+	"iss",
+	"aud",
+	"exp",
+	"iat",
+	"nbf",
+	"jti",
+	"nonce",
+	"at_hash",
+	"auth_time",
+	"acr",
+	"azp",
+	"sid"
+]);
+/**
+* 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 },
+*   })
+* }
+* ```
+*/
+function collectOidcClaims(scopes, claimsMap) {
+	const result = {};
+	for (const [scope, claims] of Object.entries(claimsMap)) if (scopes.includes(scope) && claims) Object.assign(result, claims);
+	return result;
+}
+//#endregion
+export { collectOidcClaims as i, OIDC_SCOPES as n, RESERVED_OIDC_CLAIMS as r, BUILTIN_SCOPES as t };

package/build/userinfo_controller-YwN26wK-.js

@@ -0,0 +1,37 @@
+import { c as E_INVALID_TOKEN, n as E_INSUFFICIENT_SCOPE, o as E_INVALID_REQUEST } from "./oauth_error-CvxtZvjp.js";
+import { t as SesameManager } from "./sesame_manager-CeEmlzba.js";
+import { t as TokenService } from "./token_service-DDQ3Dxaj.js";
+import { t as IdTokenService } from "./id_token_service-BtBUiL_n.js";
+//#region src/controllers/userinfo_controller.ts
+/**
+* OpenID Connect UserInfo endpoint (OIDC Core §5.3).
+*
+* Returns claims about the authenticated user based on the
+* access token's scopes. Supports both GET and POST.
+*
+* @see https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
+*/
+var UserinfoController = class {
+	async handle(ctx) {
+		const manager = await ctx.containerResolver.make(SesameManager);
+		const authHeader = ctx.request.header("authorization");
+		const rawToken = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : ctx.request.body().access_token;
+		if (!rawToken) throw new E_INVALID_REQUEST("Missing Bearer token");
+		const hashed = new TokenService(manager).hashToken(rawToken);
+		const token = await manager.store.findAccessToken({ hash: hashed });
+		if (!token) throw new E_INVALID_TOKEN("Invalid access token");
+		if (token.revokedAt) throw new E_INVALID_TOKEN("Access token has been revoked");
+		if (token.expiresAt.toJSDate() < /* @__PURE__ */ new Date()) throw new E_INVALID_TOKEN("Access token has expired");
+		if (!token.scopes.includes("openid")) throw new E_INSUFFICIENT_SCOPE(["openid"], "Token does not have openid scope");
+		const user = await manager.findUserById(token.userId);
+		if (!user) throw new E_INVALID_TOKEN("Invalid access token");
+		const userClaims = await IdTokenService.resolveUserClaims(user, token.scopes);
+		ctx.response.header("Content-Type", "application/json");
+		return {
+			sub: token.userId,
+			...userClaims
+		};
+	}
+};
+//#endregion
+export { UserinfoController as default };

package/build/vite.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;