@julr/sesame 0.0.0

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

@@ -0,0 +1,22 @@
+import { DateTime } from 'luxon';
+import { BaseModel } from '@adonisjs/lucid/orm';
+/**
+ * Tracks which scopes a user has approved for a given client.
+ *
+ * When a user grants consent during the authorization flow,
+ * the approved scopes are persisted here. On subsequent
+ * authorization requests, if the requested scopes are a subset
+ * of previously approved scopes, the user is not prompted again.
+ *
+ * New scopes are merged into the existing record when the user
+ * approves additional permissions.
+ */
+export declare class OAuthConsent extends BaseModel {
+    static table: string;
+    id: string;
+    clientId: string;
+    userId: string;
+    scopes: string[];
+    createdAt: DateTime;
+    updatedAt: DateTime;
+}

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

@@ -0,0 +1,29 @@
+import { DateTime } from 'luxon';
+import { BaseModel } from '@adonisjs/lucid/orm';
+/**
+ * Database record for an OAuth 2.0 refresh token (RFC 6749 §6).
+ *
+ * The `token` column stores the SHA-256 hash of the raw refresh
+ * token value. Refresh token rotation is enforced: each use
+ * produces a new token and revokes the old one.
+ *
+ * Replay detection is implemented by checking `revokedAt` —
+ * if a revoked token is presented, all tokens for that
+ * client+user pair are deleted as a security measure.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-6
+ * @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-4.14.2
+ */
+export declare class OAuthRefreshToken extends BaseModel {
+    static table: string;
+    id: string;
+    token: string;
+    accessTokenId: string;
+    clientId: string;
+    userId: string;
+    scopes: string[];
+    expiresAt: DateTime;
+    revokedAt: DateTime | null;
+    createdAt: DateTime;
+    updatedAt: DateTime;
+}

package/build/src/oauth_error.d.ts

@@ -0,0 +1,359 @@
+/**
+ * OAuth 2.0 error classes following the error codes defined in
+ * RFC 6749 §5.2 (https://datatracker.ietf.org/doc/html/rfc6749#section-5.2)
+ * and RFC 7591 §3.2.2 (https://datatracker.ietf.org/doc/html/rfc7591#section-3.2.2).
+ *
+ * Each error class extends AdonisJS Exception and self-renders via
+ * the `handle()` method, producing a standard OAuth JSON error response.
+ */
+import { Exception } from '@adonisjs/core/exceptions';
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Base class for all OAuth errors. Extends AdonisJS Exception
+ * and renders the standard OAuth error response format:
+ * `{ error: "<oauth_code>", error_description: "<message>" }`.
+ *
+ * Subclasses declare a static `oauthCode` matching the `error` field
+ * defined by the OAuth 2.0 spec (e.g. `invalid_request`, `invalid_client`).
+ */
+export declare class OAuthError extends Exception {
+    static oauthCode: string;
+    get oauthCode(): string;
+    handle(error: this, ctx: HttpContext): void;
+}
+/**
+ * The request is missing a required parameter, includes an unsupported
+ * parameter value, repeats a parameter, or is otherwise malformed.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export declare const E_INVALID_REQUEST: {
+    new (message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    }): {
+        get oauthCode(): string;
+        handle(error: /*elided*/ any, ctx: HttpContext): void;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly oauthCode: string;
+    help?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+/**
+ * Client authentication failed (e.g. unknown client, no client
+ * authentication included, or unsupported authentication method).
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export declare const E_INVALID_CLIENT: {
+    new (message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    }): {
+        /**
+         * If the client attempted to authenticate via the Authorization header
+         * (Basic auth), the server MUST include WWW-Authenticate: Basic.
+         *
+         * @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-3.2.4
+         */
+        handle(error: /*elided*/ any, ctx: HttpContext): void;
+        get oauthCode(): string;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly oauthCode: string;
+    help?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+/**
+ * The provided authorization grant (authorization code, refresh token,
+ * resource owner credentials) is invalid, expired, revoked, or does
+ * not match the redirection URI used in the authorization request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export declare const E_INVALID_GRANT: {
+    new (message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    }): {
+        get oauthCode(): string;
+        handle(error: /*elided*/ any, ctx: HttpContext): void;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly oauthCode: string;
+    help?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+/**
+ * The requested scope is invalid, unknown, malformed, or exceeds
+ * the scope granted by the resource owner.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export declare const E_INVALID_SCOPE: {
+    new (message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    }): {
+        get oauthCode(): string;
+        handle(error: /*elided*/ any, ctx: HttpContext): void;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly oauthCode: string;
+    help?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+/**
+ * The access token provided is expired, revoked, malformed,
+ * or invalid for other reasons.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+ */
+export declare const E_INVALID_TOKEN: {
+    new (message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    }): {
+        get oauthCode(): string;
+        handle(error: /*elided*/ any, ctx: HttpContext): void;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly oauthCode: string;
+    help?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+/**
+ * The authorization grant type is not supported by the
+ * authorization server.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+ */
+export declare const E_UNSUPPORTED_GRANT_TYPE: {
+    new (message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    }): {
+        get oauthCode(): string;
+        handle(error: /*elided*/ any, ctx: HttpContext): void;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly oauthCode: string;
+    help?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+/**
+ * The authorization server does not support obtaining an
+ * authorization code using this response type.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+export declare const E_UNSUPPORTED_RESPONSE_TYPE: {
+    new (message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    }): {
+        get oauthCode(): string;
+        handle(error: /*elided*/ any, ctx: HttpContext): void;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly oauthCode: string;
+    help?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+/**
+ * The resource owner or authorization server denied the request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+export declare const E_ACCESS_DENIED: {
+    new (message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    }): {
+        get oauthCode(): string;
+        handle(error: /*elided*/ any, ctx: HttpContext): void;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly oauthCode: string;
+    help?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+/**
+ * The client metadata value is invalid, as defined in the dynamic
+ * client registration protocol.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7591#section-3.2.2
+ */
+export declare const E_INVALID_CLIENT_METADATA: {
+    new (message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    }): {
+        get oauthCode(): string;
+        handle(error: /*elided*/ any, ctx: HttpContext): void;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly oauthCode: string;
+    help?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+/**
+ * The authorization server encountered an unexpected condition
+ * that prevented it from fulfilling the request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
+ */
+export declare const E_SERVER_ERROR: {
+    new (message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    }): {
+        get oauthCode(): string;
+        handle(error: /*elided*/ any, ctx: HttpContext): void;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly oauthCode: string;
+    help?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};

package/build/src/routes.d.ts

@@ -0,0 +1,28 @@
+import { Router } from '@adonisjs/core/http';
+/**
+ * Register all OAuth 2.1 routes on the given AdonisJS router.
+ *
+ * Endpoints registered:
+ * - `POST /oauth/token` — Token endpoint (RFC 6749 §3.2)
+ * - `GET /oauth/authorize` — Authorization endpoint (RFC 6749 §3.1)
+ * - `POST /oauth/consent` — User consent submission
+ * - `POST /oauth/introspect` — Token introspection (RFC 7662)
+ * - `POST /oauth/revoke` — Token revocation (RFC 7009)
+ * - `POST /oauth/register` — Dynamic client registration (RFC 7591)
+ * - `GET /oauth/client-info` — Public client information (RFC 6819 §4.4.1.4)
+ * - `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)
+ */
+export declare function registerRoutes(router: Router): void;
+/**
+ * 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
+ */
+export declare function registerProtectedResource(router: Router, options: {
+    resource: string;
+    scopes?: string[];
+}): void;

package/build/src/rules.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Validates a redirect URI per OAuth 2.1 / RFC 8252 rules.
+ * Blocks fragments, dangerous schemes, and requires HTTPS for non-localhost hosts.
+ */
+export declare const redirectUriRule: (options?: undefined) => import("@vinejs/vine/types").Validation<undefined>;
+/**
+ * Blocks dangerous URI schemes and enforces same host+scheme
+ * matching with redirect_uris (RFC 7591 §5).
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7591#section-5
+ */
+export declare const metadataUriRule: (options?: undefined) => import("@vinejs/vine/types").Validation<undefined>;

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

@@ -0,0 +1,67 @@
+/**
+ * Extracted client credentials from a request.
+ */
+export interface ClientCredentials {
+    clientId: string;
+    clientSecret?: string;
+}
+/**
+ * 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
+ */
+export declare class ClientService {
+    /**
+     * 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: string): ClientCredentials | 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: {
+        authorizationHeader?: string;
+        bodyClientId?: string;
+        bodyClientSecret?: string;
+    }): ClientCredentials | null;
+    /**
+     * 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: string[], clientScopes: string[]): void;
+    /**
+     * Hash a client secret for storage using SHA-256
+     * (base64url-encoded).
+     */
+    hashSecret(secret: string): string;
+    /**
+     * Verify a client secret against its stored hash using
+     * timing-safe comparison to prevent timing attacks.
+     */
+    verifySecret(secret: string, storedHash: string): boolean;
+    /**
+     * Generate a random client ID (16 bytes, hex-encoded).
+     */
+    generateClientId(): string;
+    /**
+     * Generate a random client secret (32 bytes, base64url-encoded).
+     */
+    generateClientSecret(): string;
+}

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

@@ -0,0 +1,42 @@
+import type { SesameManager } from '../sesame_manager.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.
+ */
+export declare class TokenService {
+    #private;
+    constructor(manager: SesameManager);
+    /**
+     * 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(): {
+        raw: string;
+        hash: string;
+        expiresAt: Date;
+    };
+    /**
+     * Create an opaque refresh token. Returns the raw token
+     * (sent to the client) and its SHA-256 hash (stored in DB).
+     */
+    createRefreshToken(): {
+        raw: string;
+        hash: string;
+    };
+    /**
+     * Generate a cryptographically random opaque token
+     * (32 bytes, base64url-encoded).
+     */
+    generateOpaqueToken(): string;
+    /**
+     * 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: string): string;
+}

package/build/src/sesame_manager.d.ts

@@ -0,0 +1,66 @@
+import type { ResolvedSesameConfig } from './types.ts';
+export interface PurgeResult {
+    accessTokens: number;
+    refreshTokens: number;
+    authorizationCodes: number;
+}
+/**
+ * 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`.
+ */
+export declare class SesameManager {
+    #private;
+    constructor(config: ResolvedSesameConfig);
+    get config(): ResolvedSesameConfig;
+    /**
+     * Check if a scope is registered in the server configuration.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc6749#section-3.3
+     */
+    hasScope(scope: string): boolean;
+    /**
+     * 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: string[]): string[];
+    /**
+     * Check if a grant type is enabled in the server configuration.
+     */
+    isGrantTypeEnabled(grantType: string): boolean;
+    /**
+     * 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.
+     */
+    revokeAllForUser(userId: string): Promise<void>;
+    /**
+     * 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.
+     *
+     * Inspired by Laravel Passport's `passport:purge` command.
+     */
+    purgeTokens(options?: {
+        revokedOnly?: boolean;
+        expiredOnly?: boolean;
+        retentionHours?: number;
+    }): Promise<PurgeResult>;
+    /**
+     * Parse a duration string like '1h', '30m', '10d' into seconds.
+     * Supported units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days).
+     */
+    parseTtl(ttl: string): number;
+}