@julr/sesame 0.5.0 → 0.6.0

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 { OAuthClient } from '../models/oauth_client.ts';
+export interface ExchangeAuthorizationCodeInput {
+    client: OAuthClient;
+    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<{
+        id_token?: string | undefined;
+        refresh_token?: string | undefined;
+        access_token: string;
+        token_type: "Bearer";
+        expires_in: number;
+        scope: string;
+    }>;
+}

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

@@ -0,0 +1,28 @@
+import type { SesameManager } from '../sesame_manager.ts';
+import type { OAuthClient } from '../models/oauth_client.ts';
+export interface ExchangeClientCredentialsInput {
+    client: OAuthClient;
+    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 { OAuthClient } from '../models/oauth_client.ts';
+export interface ExchangeRefreshTokenInput {
+    client: OAuthClient;
+    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<{
+        id_token?: string | undefined;
+        access_token: string;
+        token_type: "Bearer";
+        expires_in: number;
+        scope: string;
+        refresh_token: string;
+    }>;
+}

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

@@ -0,0 +1,26 @@
+import type { SesameManager } from '../sesame_manager.ts';
+import type { OAuthClient } from '../models/oauth_client.ts';
+export interface AuthorizationCodeInput {
+    client: OAuthClient;
+    userId: string;
+    scopes: string[];
+    redirectUri: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: string;
+    nonce?: string;
+}
+/**
+ * Create and persist an authorization code in the database.
+ * Returns the raw (unhashed) code to be sent to the client.
+ *
+ * Shared between the authorize and consent flows to avoid
+ * duplicating the code-issuance logic.
+ */
+export declare class IssueAuthorizationCodeAction {
+    /**
+     * Generate an opaque authorization code, store its SHA-256
+     * hash in the database, and return the raw value for the
+     * client redirect.
+     */
+    execute(manager: SesameManager, input: AuthorizationCodeInput): Promise<string>;
+}

package/build/src/controllers/authorize_controller.d.ts

@@ -2,17 +2,10 @@ import type { HttpContext } from '@adonisjs/core/http';
 /**
  * Handles the OAuth 2.0 Authorization Endpoint (RFC 6749 §3.1).
  *
- * Implements the authorization code flow with PKCE support (RFC 7636).
- * Validates the client, requested scopes, and PKCE parameters, then
- * either redirects the user to the login/consent page or directly
- * issues an authorization code if consent was already granted.
- *
- * The `iss` response parameter is included per RFC 9207 to prevent
- * mix-up attacks.
+ * Validates HTTP parameters, delegates business logic to
+ * AuthorizeAction, and interprets the result as redirects.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-3.1
- * @see https://datatracker.ietf.org/doc/html/rfc7636
- * @see https://datatracker.ietf.org/doc/html/rfc9207
  */
 export default class AuthorizeController {
     #private;
@@ -24,30 +17,38 @@ export default class AuthorizeController {
         state: import("@vinejs/vine/schema/base/literal").OptionalModifier<import("@vinejs/vine").VineString>;
         code_challenge: import("@vinejs/vine/schema/base/literal").OptionalModifier<import("@vinejs/vine").VineString>;
         code_challenge_method: import("@vinejs/vine/schema/base/literal").OptionalModifier<import("@vinejs/vine").VineString>;
+        nonce: import("@vinejs/vine/schema/base/literal").OptionalModifier<import("@vinejs/vine").VineString>;
     }, {
+        nonce?: string | null | undefined;
         scope?: string | null | undefined;
         state?: string | null | undefined;
         code_challenge?: string | null | undefined;
         code_challenge_method?: string | null | undefined;
-        redirect_uri: string;
         client_id: string;
+        redirect_uri: string;
         response_type: string;
     }, {
+        nonce?: string | undefined;
         scope?: string | undefined;
         state?: string | undefined;
         code_challenge?: string | undefined;
         code_challenge_method?: string | undefined;
-        redirect_uri: string;
         client_id: string;
+        redirect_uri: string;
         response_type: string;
     }, {
+        nonce?: string | undefined;
         scope?: string | undefined;
         state?: string | undefined;
         code_challenge?: string | undefined;
         code_challenge_method?: string | undefined;
-        redirect_uri: string;
         client_id: string;
+        redirect_uri: string;
         response_type: string;
     }>, Record<string, any> | undefined>;
+    /**
+     * Validate the authorization request query params, run the
+     * authorize action, and redirect based on the result.
+     */
     handle(ctx: HttpContext): Promise<void>;
 }

package/build/src/controllers/consent_controller.d.ts

@@ -23,5 +23,10 @@ export default class ConsentController {
     }, {
         auth_token: string;
     }>, Record<string, any> | undefined>;
+    /**
+     * Validate the consent submission, consume the pending
+     * request, and redirect back to the client with either
+     * an authorization code or an access_denied error.
+     */
     handle(ctx: HttpContext): Promise<void>;
 }

package/build/src/controllers/jwks_controller.d.ts

@@ -0,0 +1,14 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Serves the JSON Web Key Set (JWKS) containing public keys
+ * used to verify ID token signatures.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7517
+ */
+export default class JwksController {
+    handle(ctx: HttpContext): Promise<{
+        keys: import("jose").JWK[];
+    } | {
+        error: string;
+    }>;
+}

package/build/src/controllers/metadata_controller.d.ts

@@ -1,5 +1,5 @@
 import type { HttpContext } from '@adonisjs/core/http';
-import type { AuthServerMetadata, ResourceServerMetadata } from '../types.ts';
+import { type AuthServerMetadata, type ResourceServerMetadata } from '../types.ts';
 /**
  * Serves OAuth 2.0 discovery metadata documents.
  *
@@ -34,15 +34,21 @@ export default class MetadataController {
      * @see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
      */
     oidc(ctx: HttpContext): Promise<{
+        error: string;
+    } | {
+        userinfo_endpoint: string;
+        jwks_uri: string;
         subject_types_supported: string[];
+        id_token_signing_alg_values_supported: string[];
         scopes_supported: string[];
+        claims_supported: string[];
+        response_types_supported: string[];
         issuer: string;
         authorization_endpoint: string;
         token_endpoint: string;
         registration_endpoint?: string;
         introspection_endpoint?: string;
         revocation_endpoint?: string;
-        response_types_supported: string[];
         response_modes_supported: string[];
         grant_types_supported: string[];
         token_endpoint_auth_methods_supported: string[];
@@ -50,6 +56,7 @@ export default class MetadataController {
         revocation_endpoint_auth_methods_supported?: string[];
         code_challenge_methods_supported: string[];
         authorization_response_iss_parameter_supported: boolean;
+        error?: undefined;
     }>;
     /**
      * OAuth 2.0 Protected Resource Metadata (RFC 9728).

package/build/src/controllers/token_controller.d.ts

@@ -2,15 +2,14 @@ import type { HttpContext } from '@adonisjs/core/http';
 /**
  * Handles the OAuth 2.0 Token Endpoint (RFC 6749 §3.2).
  *
- * Dispatches to the appropriate grant handler based on the
- * `grant_type` parameter. Sets `Cache-Control: no-store` and
- * `Pragma: no-cache` headers on all token responses as required
- * by the spec.
+ * 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
- * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.1
  */
 export default class TokenController {
+    #private;
     static validator: import("@vinejs/vine").VineValidator<import("@vinejs/vine").VineObject<{
         grant_type: import("@vinejs/vine").VineString;
     }, {
@@ -20,5 +19,9 @@ export default class TokenController {
     }, {
         grant_type: string;
     }>, Record<string, any> | undefined>;
+    /**
+     * Validate the grant type, authenticate the client,
+     * and dispatch to the appropriate grant action.
+     */
     handle(ctx: HttpContext): Promise<any>;
 }

package/build/src/controllers/userinfo_controller.d.ts

@@ -0,0 +1,14 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * 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
+ */
+export default class UserinfoController {
+    handle(ctx: HttpContext): Promise<{
+        sub: string | null;
+    }>;
+}

package/build/src/guard/main.js

@@ -1,6 +1,6 @@
-import "../../decorate-BKZEjPRg.js";
-import "../../oauth_access_token-bsoM5KeU.js";
-import "../../oauth_client-BIoY5jBR.js";
-import "../../token_service-fhoA4slP.js";
-import { i as OAuthGuard, n as oauthUserProvider, r as OAuthLucidUserProvider, t as oauthGuard } from "../../main-B3M6ihoS.js";
+import "../../chunk-DF48asd8.js";
+import "../../oauth_client-BSanvSql.js";
+import "../../oauth_access_token-Cz_5gNBx.js";
+import "../../token_service-DwnfAR9F.js";
+import { i as OAuthGuard, n as oauthUserProvider, r as OAuthLucidUserProvider, t as oauthGuard } from "../../main-DGBJhq3E.js";
 export { OAuthGuard, OAuthLucidUserProvider, oauthGuard, oauthUserProvider };

package/build/src/middleware/any_scope_middleware.js

@@ -1,4 +1,13 @@
-import { n as E_INSUFFICIENT_SCOPE } from "../../oauth_error-CnJ3L8tf.js";
+import "../../chunk-DF48asd8.js";
+import { n as E_INSUFFICIENT_SCOPE } from "../../oauth_error-C7UhDb2q.js";
+//#region src/middleware/any_scope_middleware.ts
+/**
+* Any-scope middleware requires ANY of the listed scopes on the
+* authenticated OAuth token. Throws 403 if none match.
+*
+* @example
+* router.get('/data', [DataController]).use(middleware.anyScope({ scopes: ['read', 'read-all'] }))
+*/
 var AnyScopeMiddleware = class {
 	async handle(ctx, next, options) {
 		const guard = ctx.auth.use("oauth");
@@ -15,4 +24,5 @@ var AnyScopeMiddleware = class {
 		await guard.authenticate();
 	}
 };
+//#endregion
 export { AnyScopeMiddleware as default };

package/build/src/middleware/scope_middleware.js

@@ -1,4 +1,13 @@
-import { n as E_INSUFFICIENT_SCOPE } from "../../oauth_error-CnJ3L8tf.js";
+import "../../chunk-DF48asd8.js";
+import { n as E_INSUFFICIENT_SCOPE } from "../../oauth_error-C7UhDb2q.js";
+//#region src/middleware/scope_middleware.ts
+/**
+* Scope middleware requires ALL listed scopes on the authenticated
+* OAuth token. Throws 403 if any scope is missing.
+*
+* @example
+* router.get('/admin', [AdminController]).use(middleware.scopes({ scopes: ['admin', 'manage'] }))
+*/
 var ScopeMiddleware = class {
 	async handle(ctx, next, options) {
 		const guard = ctx.auth.use("oauth");
@@ -15,4 +24,5 @@ var ScopeMiddleware = class {
 		await guard.authenticate();
 	}
 };
+//#endregion
 export { ScopeMiddleware as default };

package/build/src/models/oauth_authorization_code.d.ts

@@ -24,6 +24,7 @@ export declare class OAuthAuthorizationCode extends BaseModel {
     redirectUri: string;
     codeChallenge: string | null;
     codeChallengeMethod: string | null;
+    nonce: string | null;
     expiresAt: DateTime;
     createdAt: DateTime;
     updatedAt: DateTime;

package/build/src/models/oauth_pending_authorization_request.d.ts

@@ -24,6 +24,7 @@ export declare class OAuthPendingAuthorizationRequest extends BaseModel {
     state: string | null;
     codeChallenge: string | null;
     codeChallengeMethod: string | null;
+    nonce: string | null;
     expiresAt: DateTime;
     createdAt: DateTime;
 }

package/build/src/oauth_error.d.ts

@@ -171,8 +171,8 @@ export declare const E_INVALID_TOKEN: {
         code?: string;
         status?: number;
     }): {
-        get oauthCode(): string;
         handle(error: /*elided*/ any, ctx: HttpContext): void;
+        get oauthCode(): string;
         name: string;
         help?: string;
         code?: string;

package/build/src/routes.d.ts

@@ -26,4 +26,6 @@ export declare function registerOAuthRoutes(router: Router): void;
  * - `GET /.well-known/openid-configuration` — OpenID Connect discovery
  * - `GET /.well-known/oauth-protected-resource` — Protected resource metadata (RFC 9728)
  */
-export declare function registerWellKnownRoutes(router: Router): void;
+export declare function registerWellKnownRoutes(router: Router, options?: {
+    jwksPath?: string;
+}): void;

package/build/src/services/id_token_service.d.ts

@@ -0,0 +1,30 @@
+import type { SesameManager } from '../sesame_manager.ts';
+/**
+ * Builds and signs OIDC `id_token` JWTs.
+ */
+export declare class IdTokenService {
+    #private;
+    constructor(manager: SesameManager);
+    /**
+     * Compute `at_hash` — left half of SHA-256 hash of the access token, base64url-encoded.
+     * @see OIDC Core §3.1.3.6
+     */
+    static computeAtHash(accessToken: string): string;
+    /**
+     * Filter out reserved claims that the server owns.
+     */
+    static filterReservedClaims(claims: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Resolve user OIDC claims by calling `getOidcClaims` if present,
+     * then filtering out reserved protocol claims.
+     */
+    static resolveUserClaims(user: unknown, scopes: string[]): Promise<Record<string, unknown>>;
+    sign(options: {
+        sub: string;
+        clientId: string;
+        scopes: string[];
+        accessToken: string;
+        user: unknown;
+        nonce?: string;
+    }): Promise<string>;
+}

package/build/src/services/key_service.d.ts

@@ -0,0 +1,20 @@
+import { type JWK } from 'jose';
+/**
+ * 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.
+ */
+export declare class KeyService {
+    #private;
+    constructor(jwk: JWK);
+    /**
+     * Compute a `kid` from public key components (SHA-256, base64url).
+     * Same approach as node-oidc-provider.
+     */
+    static computeKid(jwk: JWK): string;
+    sign(payload: Record<string, unknown>): Promise<string>;
+    getPublicJwks(): {
+        keys: JWK[];
+    };
+    get kid(): string;
+}

package/build/src/sesame_manager.d.ts

@@ -1,5 +1,7 @@
 import type { Router } from '@adonisjs/core/http';
-import { type ResolvedSesameConfig, type Scope } from './types.ts';
+import { type CreateClientOptions, type CreateClientResult, type ResolvedSesameConfig, type Scope, type UpdateClientOptions } from './types.ts';
+import { KeyService } from './services/key_service.ts';
+import { OAuthClient } from './models/oauth_client.ts';
 export interface PurgeResult {
     accessTokens: number;
     refreshTokens: number;
@@ -16,12 +18,23 @@ export declare class SesameManager {
     #private;
     constructor(config: ResolvedSesameConfig, router: Router);
     get config(): ResolvedSesameConfig;
+    get keyService(): KeyService;
+    get isOidcEnabled(): boolean;
+    /**
+     * Load a user by ID using the configured user provider.
+     * Returns the original user model instance, or null if not found.
+     */
+    findUserById(userId: string): Promise<unknown | null>;
     /**
      * Check if a scope is registered in the server configuration.
      *
      * @see https://datatracker.ietf.org/doc/html/rfc6749#section-3.3
      */
     hasScope(scope: Scope): boolean;
+    /**
+     * Check if the requested scope list uses any OIDC-specific scopes.
+     */
+    usesOidcScopes(scopes: Scope[]): boolean;
     /**
      * Return the list of scopes that are not registered in the
      * server configuration. When no scopes are configured, all
@@ -58,6 +71,36 @@ export declare class SesameManager {
         expiredOnly?: boolean;
         retentionHours?: number;
     }): Promise<PurgeResult>;
+    /**
+     * Create a new OAuth client programmatically.
+     * Returns the client and the raw secret (only available at creation time).
+     */
+    createClient(options: CreateClientOptions): Promise<CreateClientResult>;
+    /**
+     * Find a client by its public client_id.
+     */
+    findClient(clientId: string): Promise<OAuthClient | null>;
+    /**
+     * List all clients, optionally filtered by userId.
+     */
+    listClients(options?: {
+        userId?: string;
+    }): Promise<OAuthClient[]>;
+    /**
+     * Update an existing client by its public client_id.
+     * Returns the updated client, or null if not found.
+     */
+    updateClient(clientId: string, options: UpdateClientOptions): Promise<OAuthClient | null>;
+    /**
+     * Delete a client and all its associated tokens, codes, and consents.
+     * Returns true if the client was found and deleted.
+     */
+    deleteClient(clientId: string): Promise<boolean>;
+    /**
+     * Rotate the secret of a confidential client.
+     * Returns the new raw secret, or null if the client is public or not found.
+     */
+    rotateClientSecret(clientId: string): Promise<string | null>;
     /**
      * Register OAuth 2.1 endpoint routes (token, authorize, consent, etc.).
      *
@@ -77,12 +120,20 @@ export declare class SesameManager {
      */
     registerRoutes(): void;
     /**
-     * Register well-known discovery routes at the root level.
+     * Register discovery routes at the root level.
      *
      * Must be called outside any prefix group so endpoints
      * remain at `/.well-known/...`.
      */
-    registerWellKnownRoutes(): void;
+    registerDiscoveryRoutes(options?: {
+        jwksPath?: string;
+    }): void;
+    /**
+     * @deprecated Use `registerDiscoveryRoutes()` instead.
+     */
+    registerWellKnownRoutes(options?: {
+        jwksPath?: string;
+    }): void;
     /**
      * Register a `/.well-known/oauth-protected-resource` endpoint
      * for a specific resource path (RFC 9728). Useful for MCP