@julr/sesame 0.5.1 → 0.7.0

package/build/sesame_manager-CeEmlzba.js

@@ -0,0 +1,515 @@
+import { n as OIDC_SCOPES, t as BUILTIN_SCOPES } from "./types-DEtn2Zdb.js";
+import { o as E_INVALID_REQUEST, r as E_INVALID_CLIENT, s as E_INVALID_SCOPE } from "./oauth_error-CvxtZvjp.js";
+import { DateTime } from "luxon";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { SignJWT, importJWK } from "jose";
+//#region src/services/client_service.ts
+/**
+* Handles OAuth client authentication and credential management.
+*
+* Supports the client authentication methods defined in RFC 6749 §2.3:
+* - `client_secret_basic`: HTTP Basic auth with client_id:client_secret
+* - `client_secret_post`: credentials in the request body
+* - `none`: public clients (no secret)
+*
+* Client secrets are stored as SHA-256 hashes and compared using
+* timing-safe equality to prevent timing attacks.
+*
+* @see https://datatracker.ietf.org/doc/html/rfc6749#section-2.3
+*/
+var ClientService = class {
+	#manager;
+	constructor(manager) {
+		this.#manager = manager;
+	}
+	/**
+	* Parse an HTTP Basic Authorization header into client credentials.
+	* Follows RFC 6749 §2.3.1 — the client_id and client_secret are
+	* URL-decoded after base64 decoding.
+	*
+	* @see https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
+	*/
+	parseBasicAuth(header) {
+		if (!header.startsWith("Basic ")) return null;
+		try {
+			const decoded = Buffer.from(header.slice(6), "base64").toString("utf-8");
+			const colonIndex = decoded.indexOf(":");
+			if (colonIndex === -1) return null;
+			return {
+				clientId: decodeURIComponent(decoded.slice(0, colonIndex)),
+				clientSecret: decodeURIComponent(decoded.slice(colonIndex + 1))
+			};
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Extract client credentials from a request. Checks the
+	* Authorization header first (Basic auth), then falls back
+	* to POST body parameters (`client_id` / `client_secret`).
+	*/
+	extractCredentials(options) {
+		const basic = options.authorizationHeader ? this.parseBasicAuth(options.authorizationHeader) : null;
+		if (basic && options.bodyClientId) throw new E_INVALID_REQUEST("Multiple client authentication methods are not allowed");
+		if (basic) return basic;
+		if (options.bodyClientId) return {
+			clientId: options.bodyClientId,
+			clientSecret: options.bodyClientSecret
+		};
+		return null;
+	}
+	/**
+	* Authenticate a client from request credentials.
+	* Extracts credentials, looks up the client in DB, and verifies the secret
+	* for confidential clients.
+	*/
+	async authenticateClient(options) {
+		const credentials = this.extractCredentials(options);
+		if (!credentials) throw new E_INVALID_CLIENT("Client authentication failed");
+		if (!this.#manager) throw new Error("ClientService requires SesameManager for authentication");
+		const client = await this.#manager.store.findClient(credentials.clientId);
+		if (!client || client.isDisabled) throw new E_INVALID_CLIENT("Client authentication failed");
+		if (!client.isPublic) {
+			if (!credentials.clientSecret || !this.verifySecret(credentials.clientSecret, client.clientSecret)) throw new E_INVALID_CLIENT("Client authentication failed");
+		}
+		return client;
+	}
+	/**
+	* Validate that requested scopes are within the client's
+	* allowed scopes. Throws `E_INVALID_SCOPE` if any scope
+	* is not permitted. An empty `clientScopes` array means the
+	* client has no scope permissions (RFC 6749 §2, §3.3).
+	*
+	* @see https://datatracker.ietf.org/doc/html/rfc6749#section-3.3
+	*/
+	validateClientScopes(requestedScopes, clientScopes) {
+		const nonBuiltinScopes = requestedScopes.filter((s) => !BUILTIN_SCOPES.has(s));
+		if (clientScopes.length === 0 && nonBuiltinScopes.length > 0) throw new E_INVALID_SCOPE(`Scope not allowed: ${nonBuiltinScopes.join(", ")}`);
+		const allowedSet = new Set(clientScopes);
+		const invalid = nonBuiltinScopes.filter((s) => !allowedSet.has(s));
+		if (invalid.length > 0) throw new E_INVALID_SCOPE(`Scope not allowed: ${invalid.join(", ")}`);
+	}
+	/**
+	* Hash a client secret for storage using SHA-256
+	* (base64url-encoded).
+	*/
+	hashSecret(secret) {
+		return createHash("sha256").update(secret).digest("base64url");
+	}
+	/**
+	* Verify a client secret against its stored hash using
+	* timing-safe comparison to prevent timing attacks.
+	*/
+	verifySecret(secret, storedHash) {
+		const hash = this.hashSecret(secret);
+		try {
+			return timingSafeEqual(Buffer.from(hash), Buffer.from(storedHash));
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Generate a random client ID (16 bytes, hex-encoded).
+	*/
+	generateClientId() {
+		return randomBytes(16).toString("hex");
+	}
+	/**
+	* Generate a random client secret (32 bytes, base64url-encoded).
+	*/
+	generateClientSecret() {
+		return randomBytes(32).toString("base64url");
+	}
+};
+//#endregion
+//#region src/services/key_service.ts
+/**
+* Manages the RSA key pair used to sign ID tokens.
+* Accepts a JWK from config, caches the imported private key
+* and public JWK for JWKS export.
+*/
+var KeyService = class KeyService {
+	#privateKey = null;
+	#publicJwk;
+	#kid;
+	#jwk;
+	constructor(jwk) {
+		this.#jwk = jwk;
+		this.#kid = jwk.kid ?? KeyService.computeKid(jwk);
+		this.#publicJwk = {
+			kty: jwk.kty,
+			n: jwk.n,
+			e: jwk.e,
+			kid: this.#kid,
+			use: "sig",
+			alg: "RS256"
+		};
+	}
+	/**
+	* Compute a `kid` from public key components (SHA-256, base64url).
+	* Same approach as node-oidc-provider.
+	*/
+	static computeKid(jwk) {
+		const components = JSON.stringify({
+			e: jwk.e,
+			kty: jwk.kty,
+			n: jwk.n
+		});
+		return createHash("sha256").update(components).digest("base64url");
+	}
+	async #getPrivateKey() {
+		if (this.#privateKey) return this.#privateKey;
+		this.#privateKey = await importJWK(this.#jwk, "RS256");
+		return this.#privateKey;
+	}
+	async sign(payload) {
+		const key = await this.#getPrivateKey();
+		return new SignJWT(payload).setProtectedHeader({
+			alg: "RS256",
+			kid: this.#kid,
+			typ: "JWT"
+		}).sign(key);
+	}
+	getPublicJwks() {
+		return { keys: [this.#publicJwk] };
+	}
+	get kid() {
+		return this.#kid;
+	}
+};
+//#endregion
+//#region src/routes.ts
+/**
+* Lazy-loaded controller imports for all OAuth 2.1 endpoints.
+* Using lazy imports ensures controllers are only loaded when
+* their routes are hit.
+*/
+const controllers = {
+	token: () => import("./token_controller-DRatCQNT.js"),
+	authorize: () => import("./authorize_controller-sCZIjnc-.js"),
+	consent: () => import("./consent_controller-ChBboaSd.js"),
+	introspect: () => import("./introspect_controller-LVYGWhMj.js"),
+	revoke: () => import("./revoke_controller-Daz4Yqfs.js"),
+	register: () => import("./register_controller-Cdk3c32j.js"),
+	metadata: () => import("./metadata_controller-hwfmxlF7.js"),
+	clientInfo: () => import("./client_info_controller-B5A3tpbk.js"),
+	jwks: () => import("./jwks_controller-4HUVS_HC.js"),
+	userinfo: () => import("./userinfo_controller-YwN26wK-.js")
+};
+/**
+* Register OAuth 2.1 endpoint routes on the given router.
+*
+* Paths are relative (no prefix) — the user wraps the call
+* in a `router.group().prefix('/oauth')` to control the mount point.
+*
+* Endpoints registered:
+* - `POST /token` — Token endpoint (RFC 6749 §3.2)
+* - `GET /authorize` — Authorization endpoint (RFC 6749 §3.1)
+* - `POST /consent` — User consent submission
+* - `POST /introspect` — Token introspection (RFC 7662)
+* - `POST /revoke` — Token revocation (RFC 7009)
+* - `POST /register` — Dynamic client registration (RFC 7591)
+* - `GET /client-info` — Public client information (RFC 6819 §4.4.1.4)
+*/
+function registerOAuthRoutes(router) {
+	router.post("/token", [controllers.token]).as("sesame.token");
+	router.get("/authorize", [controllers.authorize]).as("sesame.authorize");
+	router.post("/consent", [controllers.consent]).as("sesame.consent");
+	router.get("/client-info", [controllers.clientInfo]).as("sesame.clientInfo");
+	router.post("/introspect", [controllers.introspect]).as("sesame.introspect");
+	router.post("/revoke", [controllers.revoke]).as("sesame.revoke");
+	router.post("/register", [controllers.register]).as("sesame.register");
+	router.get("/userinfo", [controllers.userinfo]).as("sesame.userinfo");
+	router.post("/userinfo", [controllers.userinfo]).as("sesame.userinfo.post");
+}
+/**
+* Register well-known discovery routes at the root level.
+*
+* These must be registered outside any prefix group so they
+* remain at `/.well-known/...`.
+*
+* Endpoints registered:
+* - `GET /.well-known/oauth-authorization-server` — Server metadata (RFC 8414)
+* - `GET /.well-known/openid-configuration` — OpenID Connect discovery
+* - `GET /.well-known/oauth-protected-resource` — Protected resource metadata (RFC 9728)
+*/
+function registerWellKnownRoutes(router, options) {
+	const jwksPath = options?.jwksPath ?? "/jwks";
+	router.get("/.well-known/oauth-authorization-server", [controllers.metadata, "authServer"]).as("sesame.metadata.authServer");
+	router.get("/.well-known/openid-configuration", [controllers.metadata, "oidc"]).as("sesame.metadata.oidc");
+	router.get("/.well-known/oauth-protected-resource", [controllers.metadata, "protectedResource"]).as("sesame.metadata.protectedResource");
+	router.get(jwksPath, [controllers.jwks]).as("sesame.jwks");
+}
+//#endregion
+//#region src/sesame_manager.ts
+/**
+* Central manager for the Sésame OAuth 2.1 server.
+*
+* Holds the resolved configuration. Registered as a singleton
+* in the AdonisJS IoC container by `SesameProvider`.
+*/
+var SesameManager = class {
+	#config;
+	#router;
+	#keyService;
+	#store;
+	constructor(config, router, store) {
+		this.#config = config;
+		this.#router = router;
+		this.#store = store;
+		this.#keyService = config.jwk ? new KeyService(config.jwk) : null;
+	}
+	#publicClient(client) {
+		const publicClient = { ...client };
+		Object.defineProperty(publicClient, "clientSecret", {
+			value: client.clientSecret,
+			enumerable: false,
+			writable: false
+		});
+		return publicClient;
+	}
+	get config() {
+		return this.#config;
+	}
+	get store() {
+		return this.#store;
+	}
+	get keyService() {
+		if (!this.#keyService) throw new Error("OIDC requires a JWK. Set the `jwk` option in defineConfig().");
+		return this.#keyService;
+	}
+	get isOidcEnabled() {
+		return this.#keyService !== null && this.#config.oidcProvider !== void 0;
+	}
+	/**
+	* Load a user by ID using the configured user provider.
+	* Returns the original user model instance, or null if not found.
+	*/
+	async findUserById(userId) {
+		if (!this.#config.oidcProvider) return null;
+		return (await this.#config.oidcProvider.findById(userId))?.getOriginal() ?? null;
+	}
+	/**
+	* Check if a scope is registered in the server configuration.
+	*
+	* @see https://datatracker.ietf.org/doc/html/rfc6749#section-3.3
+	*/
+	hasScope(scope) {
+		return scope in this.#config.scopes;
+	}
+	/**
+	* Check if the requested scope list uses any OIDC-specific scopes.
+	*/
+	usesOidcScopes(scopes) {
+		return scopes.some((scope) => OIDC_SCOPES.has(scope));
+	}
+	/**
+	* Return the list of scopes that are not registered in the
+	* server configuration. When no scopes are configured, all
+	* requested scopes are considered unknown per RFC 6749 §3.3
+	* (`invalid_scope` — "The requested scope is invalid, unknown,
+	* or malformed").
+	*
+	* @see https://datatracker.ietf.org/doc/html/rfc6749#section-3.3
+	* @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+	*/
+	validateScopes(scopes) {
+		const invalidScopes = /* @__PURE__ */ new Set();
+		if (!scopes.includes("openid")) scopes.filter((scope) => scope !== "openid" && OIDC_SCOPES.has(scope)).forEach((scope) => invalidScopes.add(scope));
+		if (Object.keys(this.#config.scopes).length === 0) {
+			scopes.filter((scope) => !BUILTIN_SCOPES.has(scope) && !OIDC_SCOPES.has(scope)).forEach((scope) => invalidScopes.add(scope));
+			return [...invalidScopes];
+		}
+		scopes.filter((scope) => !BUILTIN_SCOPES.has(scope) && !OIDC_SCOPES.has(scope) && !this.hasScope(scope)).forEach((scope) => invalidScopes.add(scope));
+		return [...invalidScopes];
+	}
+	/**
+	* Check if a grant type is enabled in the server configuration.
+	*/
+	isGrantTypeEnabled(grantType) {
+		return this.#config.grantTypes.includes(grantType);
+	}
+	/**
+	* Revoke all OAuth artifacts for a given user.
+	*
+	* Call this when a user is deleted or deactivated to ensure
+	* none of their tokens remain usable. Revokes access tokens
+	* and refresh tokens, and deletes authorization codes and
+	* consent records.
+	*/
+	async revokeAllForUser(userId) {
+		const now = DateTime.now();
+		await this.#store.revokeAllForUser({
+			userId,
+			now
+		});
+	}
+	/**
+	* Purge revoked and/or expired tokens and authorization codes.
+	*
+	* Returns the total number of deleted records. Expired tokens are
+	* retained for `retentionHours` (default 168 = 7 days) to allow
+	* for debugging and audit trails.
+	*/
+	async purgeTokens(options) {
+		const revokedOnly = options?.revokedOnly ?? false;
+		const expiredOnly = options?.expiredOnly ?? false;
+		const retentionHours = options?.retentionHours ?? 168;
+		const purgeRevoked = revokedOnly || !expiredOnly;
+		const purgeExpired = expiredOnly || !revokedOnly;
+		const cutoff = DateTime.now().minus({ hours: retentionHours });
+		return this.#store.purgeTokens({
+			purgeRevoked,
+			purgeExpired,
+			cutoff,
+			now: DateTime.now()
+		});
+	}
+	/**
+	* Create a new OAuth client programmatically.
+	* Returns the client and the raw secret (only available at creation time).
+	*/
+	async createClient(options) {
+		const clientService = new ClientService();
+		const isPublic = options.isPublic ?? false;
+		const grantTypes = options.grantTypes ?? ["authorization_code"];
+		const scopes = options.scopes ?? this.#config.defaultScopes;
+		const clientId = clientService.generateClientId();
+		const clientSecret = isPublic ? null : clientService.generateClientSecret();
+		const hashedSecret = clientSecret ? clientService.hashSecret(clientSecret) : null;
+		const client = await this.#store.createClient({
+			id: crypto.randomUUID(),
+			clientId,
+			clientSecret: hashedSecret,
+			name: options.name,
+			redirectUris: options.redirectUris,
+			scopes,
+			grantTypes,
+			isPublic,
+			isDisabled: false,
+			requirePkce: options.requirePkce ?? true,
+			type: isPublic ? "public" : "confidential",
+			metadata: options.metadata ?? null,
+			userId: options.userId ?? null
+		});
+		return {
+			client: this.#publicClient(client),
+			clientSecret
+		};
+	}
+	/**
+	* Find a client by its public client_id.
+	*/
+	async findClient(clientId) {
+		const client = await this.#store.findClient(clientId);
+		return client ? this.#publicClient(client) : null;
+	}
+	/**
+	* List all clients, optionally filtered by userId.
+	*/
+	async listClients(options) {
+		return (await this.#store.listClients(options)).map((client) => this.#publicClient(client));
+	}
+	/**
+	* Update an existing client by its public client_id.
+	* Returns the updated client, or null if not found.
+	*/
+	async updateClient(clientId, options) {
+		const store = this.#store;
+		const client = await store.findClient(clientId);
+		if (!client) return null;
+		if (options.name !== void 0) client.name = options.name;
+		if (options.redirectUris !== void 0) client.redirectUris = options.redirectUris;
+		if (options.scopes !== void 0) client.scopes = options.scopes;
+		if (options.grantTypes !== void 0) client.grantTypes = options.grantTypes;
+		if (options.isDisabled !== void 0) client.isDisabled = options.isDisabled;
+		if (options.requirePkce !== void 0) client.requirePkce = options.requirePkce;
+		if (options.metadata !== void 0) client.metadata = options.metadata;
+		await store.updateClient({
+			id: client.id,
+			data: options
+		});
+		const updated = await store.findClient(clientId);
+		return updated ? this.#publicClient(updated) : null;
+	}
+	/**
+	* Delete a client and all its associated tokens, codes, and consents.
+	* Returns true if the client was found and deleted.
+	*/
+	async deleteClient(clientId) {
+		return this.#store.deleteClient(clientId);
+	}
+	/**
+	* Rotate the secret of a confidential client.
+	* Returns the new raw secret, or null if the client is public or not found.
+	*/
+	async rotateClientSecret(clientId) {
+		const store = this.#store;
+		const client = await store.findClient(clientId);
+		if (!client || client.isPublic) return null;
+		const clientService = new ClientService();
+		const newSecret = clientService.generateClientSecret();
+		client.clientSecret = clientService.hashSecret(newSecret);
+		await store.updateClientSecret({
+			id: client.id,
+			secret: client.clientSecret
+		});
+		return newSecret;
+	}
+	/**
+	* Register OAuth 2.1 endpoint routes (token, authorize, consent, etc.).
+	*
+	* Paths are relative — wrap the call in a `router.group().prefix()`
+	* to control the mount point.
+	*
+	* Do not apply session-auth middleware to the entire OAuth group.
+	* Endpoints like `/token`, `/introspect`, `/revoke`, and `/register`
+	* must stay callable without a browser session.
+	*
+	* @example
+	* ```ts
+	* router.group(() => {
+	*   sesame.registerRoutes()
+	* }).prefix('/oauth')
+	* ```
+	*/
+	registerRoutes() {
+		registerOAuthRoutes(this.#router);
+	}
+	/**
+	* Register discovery routes at the root level.
+	*
+	* Must be called outside any prefix group so endpoints
+	* remain at `/.well-known/...`.
+	*/
+	registerDiscoveryRoutes(options) {
+		registerWellKnownRoutes(this.#router, options);
+	}
+	/**
+	* @deprecated Use `registerDiscoveryRoutes()` instead.
+	*/
+	registerWellKnownRoutes(options) {
+		this.registerDiscoveryRoutes(options);
+	}
+	/**
+	* Register a `/.well-known/oauth-protected-resource` endpoint
+	* for a specific resource path (RFC 9728). Useful for MCP
+	* servers that need per-resource discovery.
+	*
+	* @see https://datatracker.ietf.org/doc/html/rfc9728
+	*/
+	registerProtectedResource(options) {
+		const wellKnownPath = `/.well-known/oauth-protected-resource${options.resource}`;
+		this.#router.get(wellKnownPath, async (ctx) => {
+			ctx.response.header("Cache-Control", "public, max-age=15, stale-while-revalidate=15, stale-if-error=86400");
+			return {
+				resource: `${this.#config.issuer}${options.resource}`,
+				authorization_servers: [this.#config.issuer],
+				scopes_supported: [...options.scopes ?? Object.keys(this.#config.scopes), ...BUILTIN_SCOPES],
+				bearer_methods_supported: ["header"]
+			};
+		});
+	}
+};
+//#endregion
+export { ClientService as n, SesameManager as t };

package/build/sesame_manager-DQxvsTEq.js

@@ -0,0 +1,2 @@
+import { t as SesameManager } from "./sesame_manager-CeEmlzba.js";
+export { SesameManager };

package/build/src/actions/authorize.d.ts

@@ -0,0 +1,46 @@
+import type { SesameManager } from '../sesame_manager.ts';
+export interface AuthorizeInput {
+    clientId: string;
+    responseType: string;
+    redirectUri: string;
+    scope?: string;
+    state?: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: string;
+    nonce?: string;
+    userId?: string;
+}
+export type AuthorizeResult = {
+    type: 'redirect_error';
+    error: string;
+    description: string;
+} | {
+    type: 'login_required';
+} | {
+    type: 'consent_required';
+    authToken: string;
+    scopes: string[];
+} | {
+    type: 'authorized';
+    code: string;
+};
+/**
+ * Handles the OAuth 2.0 authorization request business logic.
+ *
+ * Validates the client, scopes, and PKCE parameters, checks
+ * existing consent, and either issues an authorization code
+ * or signals that login/consent is required.
+ *
+ * Errors before redirect_uri validation are thrown as exceptions.
+ * Errors after are returned as `redirect_error` results so the
+ * controller can redirect back to the client per spec.
+ */
+export declare class AuthorizeAction {
+    #private;
+    /**
+     * Process an authorization request. Returns a discriminated
+     * union that the controller interprets as the appropriate
+     * HTTP redirect.
+     */
+    execute(manager: SesameManager, input: AuthorizeInput): Promise<AuthorizeResult>;
+}

package/build/src/actions/exchange_authorization_code.d.ts

@@ -0,0 +1,34 @@
+import type { SesameManager } from '../sesame_manager.ts';
+import type { OAuthClientRecord } from '../storage/types.ts';
+export interface ExchangeAuthorizationCodeInput {
+    client: OAuthClientRecord;
+    code: string;
+    redirectUri: string;
+    codeVerifier: string;
+}
+/**
+ * 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
+ */
+export declare class ExchangeAuthorizationCodeAction {
+    #private;
+    /**
+     * Exchange an authorization code for tokens. The code is
+     * consumed atomically inside a transaction.
+     */
+    execute(manager: SesameManager, input: ExchangeAuthorizationCodeInput): Promise<{
+        access_token: string;
+        token_type: 'Bearer';
+        expires_in: number;
+        scope: string;
+        refresh_token?: string | undefined;
+        id_token?: string | undefined;
+    }>;
+}

package/build/src/actions/exchange_client_credentials.d.ts

@@ -0,0 +1,28 @@
+import type { SesameManager } from '../sesame_manager.ts';
+import type { OAuthClientRecord } from '../storage/types.ts';
+export interface ExchangeClientCredentialsInput {
+    client: OAuthClientRecord;
+    scope?: string;
+}
+/**
+ * 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
+ */
+export declare class ExchangeClientCredentialsAction {
+    #private;
+    /**
+     * Validate the client, resolve scopes, and issue an
+     * access token for M2M usage.
+     */
+    execute(manager: SesameManager, input: ExchangeClientCredentialsInput): Promise<{
+        access_token: string;
+        token_type: 'Bearer';
+        expires_in: number;
+        scope: string;
+    }>;
+}

package/build/src/actions/exchange_refresh_token.d.ts

@@ -0,0 +1,59 @@
+import type { SesameManager } from '../sesame_manager.ts';
+import type { OAuthClientRecord } from '../storage/types.ts';
+export interface ExchangeRefreshTokenInput {
+    client: OAuthClientRecord;
+    refreshToken: string;
+    scope?: string;
+}
+/**
+ * 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
+ */
+export declare class ExchangeRefreshTokenAction {
+    #private;
+    /**
+     * Rotate the refresh token, issue a new access token,
+     * and optionally reissue an id_token if openid scope
+     * is present.
+     */
+    execute(manager: SesameManager, input: ExchangeRefreshTokenInput): Promise<{
+        access_token: string;
+        token_type: 'Bearer';
+        expires_in: number;
+        scope: string;
+        refresh_token: string;
+        id_token?: string | undefined;
+    }>;
+}