@bajustone/fortress 1.0.0-rc.1

package/dist/plugins/oauth.d.ts

@@ -0,0 +1,406 @@
+import { F as FortressPlugin } from '../config-B2366s_G.js';
+import { F as FortressUser } from '../types-et0R8tsC.js';
+import '../index-CxEkfCA0.js';
+import '../jwt.js';
+import '../auth-service-BkzZkWfH.js';
+
+/**
+ * PKCE (Proof Key for Code Exchange) S256 implementation.
+ * Used by the OAuth plugin to secure authorization code flows.
+ */
+/** Generate a cryptographically random code verifier (43-128 chars, URL-safe) */
+declare function generateCodeVerifier(): string;
+/** Generate S256 code challenge from a code verifier */
+declare function generateCodeChallenge(verifier: string): Promise<string>;
+/**
+ * Verify a code verifier against a stored S256 challenge.
+ *
+ * Validates the verifier against RFC 7636 §4.1 (43-128 chars, unreserved
+ * URL-safe character set) before computing the challenge — a verifier that
+ * fails this check is invalid by definition and must not unlock a code.
+ *
+ * Uses {@link timingSafeEqualHex} for the final comparison so a remote
+ * attacker can't differentiate "wrong verifier" from "wrong verifier with
+ * matching prefix" via response timing.
+ */
+declare function verifyCodeChallenge(verifier: string, challenge: string, method: string): Promise<boolean>;
+
+/**
+ * OAuth 2.0 authorization server plugin for fortress.
+ *
+ * Implements the authorization-code grant (with PKCE) and client-credentials
+ * grant for confidential and public clients. Persists clients, authorization
+ * codes, access tokens, and pending flows via the fortress database adapter,
+ * and exposes the standard `/authorize` and `/token` endpoints when mounted.
+ *
+ * @module
+ */
+
+interface OAuthConfig {
+    /** Authorization code expiry in seconds (default: 600 = 10 min) */
+    authCodeExpirySeconds?: number;
+    /** Pending flow expiry in seconds (default: 600 = 10 min) */
+    pendingFlowExpirySeconds?: number;
+    /** Access token expiry in seconds (default: 3600 = 1 hour) */
+    accessTokenExpirySeconds?: number;
+    /**
+     * Refresh token expiry in seconds (default: 30 days). Refresh tokens are
+     * sliding — each rotation issues a fresh token with a new expiry. Set to
+     * 0 to disable refresh-token issuance entirely.
+     *
+     * @see RFC 6749 §6 · RFC 9700 §2.2.2
+     */
+    refreshTokenExpirySeconds?: number;
+    /**
+     * id_token expiry in seconds (default: 3600 = 1 hour). Only relevant
+     * when the request includes `scope=openid`.
+     *
+     * @see OIDC Core 1.0 §2
+     */
+    idTokenExpirySeconds?: number;
+    /** Seconds rotated signing keys remain published in JWKS. Default: idTokenExpirySeconds. */
+    signingKeyGraceSeconds?: number;
+    /** Map OAuth scopes to IAM permissions. Example: `{ 'read:posts': { resource: 'post', action: 'read' } }` */
+    scopePermissionMap?: Record<string, {
+        resource: string;
+        action: string;
+    }>;
+    /** Base URL for the OAuth server (used in OIDC discovery document) */
+    issuerUrl?: string;
+    /**
+     * RFC 9700 §2.1.1 escape hatch: when `true`, `/oauth/authorize` will accept
+     * requests without a `code_challenge` from confidential clients. Defaults
+     * to `false`. Strongly discouraged — PKCE is mandatory in current OAuth
+     * BCP. Provided only so legacy server-side RPs can be migrated
+     * incrementally.
+     */
+    allowNonPkceConfidentialClients?: boolean;
+    /**
+     * Static list of OIDC/OAuth scope names the AS knows about, surfaced in
+     * discovery's `scopes_supported`. Merged with the keys of
+     * {@link OAuthConfig.scopePermissionMap} and the default OIDC scopes
+     * (`openid`, `email`, `profile`). Optional — informational metadata only;
+     * does not enforce per-client allow-listing on its own.
+     */
+    scopesSupported?: string[];
+    /**
+     * Per-deployment extension hook for `/oauth/userinfo`. Receives the
+     * {@link FortressUser} resolved from the access token plus the token's
+     * scope (or `null` if no scope was issued), and returns a claims record
+     * that is merged into the OIDC-shaped response on top of the standard
+     * claims fortress emits.
+     *
+     * Use this to attach app-specific claims (tenant, roles, custom
+     * profile fields). Returning `{}` is the no-op; returning a key already
+     * emitted by fortress overwrites it (you'd typically only do that for
+     * `preferred_username` or `name` when the host app stores its own).
+     *
+     * @example
+     * ```ts
+     * userinfoClaims: (user, scope) => ({
+     *   tenant_id: user.tenantId,
+     *   ...(scope?.includes('profile') ? { picture: user.avatarUrl } : {}),
+     * })
+     * ```
+     */
+    userinfoClaims?: (user: FortressUser, scope: string | null) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Mount the front-door `GET /oauth/authorize` endpoint. Off by default —
+     * opt in once your host app has wired up `loginUrl` and `consentUrl`.
+     * Plugin methods (`createPendingFlow`, `handleAuthorizeRequest`) stay
+     * available regardless.
+     */
+    enableAuthorizeEndpoint?: boolean;
+    /**
+     * Mount the consent-API endpoints (`GET /oauth/flows/:flowId`,
+     * `POST /oauth/flows/:flowId/approve`, `POST /oauth/flows/:flowId/deny`).
+     * Off by default — opt in for the SPA-friendly consent flow (Pattern B).
+     * The corresponding methods stay available regardless.
+     */
+    enableConsentApi?: boolean;
+    /**
+     * Where the host app's sign-in page lives, e.g.
+     * `'https://app.example.com/signin'`. The authorize endpoint redirects
+     * unauthenticated users to `${loginUrl}?flow=<id>`.
+     */
+    loginUrl?: string;
+    /**
+     * Where the host app's consent page lives, e.g.
+     * `'https://app.example.com/oauth/consent'`. The authorize endpoint
+     * redirects authenticated users to `${consentUrl}?flow=<id>`.
+     */
+    consentUrl?: string;
+}
+/** RFC 6749 §2.1 / OIDC Discovery `token_endpoint_auth_methods_supported` aliases. */
+type TokenEndpointAuthMethod = 'client_secret_basic' | 'client_secret_post' | 'none';
+/** Persisted state for an in-flight OAuth authorization-code flow. */
+interface PendingFlowRecord {
+    /** Internal DB primary key — never exposed to clients. */
+    id: string;
+    /** Public opaque handle used in URLs; replaces enumerable serial ids (H6). */
+    flowId: string;
+    clientId: string;
+    redirectUri: string;
+    scope: string | null;
+    state: string;
+    codeChallenge: string | null;
+    codeChallengeMethod: string | null;
+    /** OIDC Core §3.1.2.1 nonce — mirrored from the authorize query if present. */
+    nonce: string | null;
+    /**
+     * Subject the flow is bound to. Null until the first authenticated
+     * read/approve, then trust-on-first-use claims it for that user. Every
+     * subsequent read/approve/deny MUST match.
+     *
+     * Closes H6 (IDOR on `/oauth/flows/:flowId`): without this column, any
+     * authenticated user could fetch another user's RP state token or
+     * approve their flow.
+     */
+    userId: string | null;
+    /** Set during atomic approve/deny claim; prevents concurrent double-submit. */
+    usedAt: Date | null;
+    expiresAt: Date;
+}
+/** Client authentication extracted from HTTP request (Basic auth or body params) */
+/** Resolved client credentials parsed from a token-endpoint request. */
+interface ClientAuth {
+    clientId: string;
+    clientSecret: string;
+}
+/** Token endpoint request body (application/x-www-form-urlencoded) */
+/** Body shape accepted by the OAuth `/token` endpoint. */
+interface TokenRequestBody {
+    grant_type: string;
+    code?: string;
+    redirect_uri?: string;
+    client_id?: string;
+    client_secret?: string;
+    code_verifier?: string;
+    scope?: string;
+    /** RFC 6749 §6 refresh-token grant payload. */
+    refresh_token?: string;
+}
+/** Authorization endpoint query params */
+/** Query parameters accepted by the OAuth `/authorize` endpoint. */
+interface AuthorizeRequestParams {
+    client_id: string;
+    redirect_uri: string;
+    response_type: string;
+    scope?: string;
+    state?: string;
+    code_challenge?: string;
+    code_challenge_method?: string;
+}
+interface OAuthMethods {
+    createClient: (data: {
+        name: string;
+        redirectUris: string[];
+        grantTypes: string[];
+        allowedScopes?: string[];
+        tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
+    }) => Promise<{
+        clientId: string;
+        clientSecret: string | null;
+    }>;
+    createAuthorizationCode: (params: {
+        clientId: string;
+        userId: string;
+        redirectUri: string;
+        scope?: string;
+        codeChallenge?: string;
+        codeChallengeMethod?: string;
+        nonce?: string;
+        authTime?: number;
+    }) => Promise<{
+        code: string;
+    }>;
+    exchangeCode: (params: {
+        code: string;
+        clientId: string;
+        clientSecret?: string;
+        redirectUri: string;
+        codeVerifier?: string;
+    }) => Promise<{
+        accessToken: string;
+        tokenType: string;
+        expiresIn: number;
+        scope?: string;
+        refreshToken?: string;
+        idToken?: string;
+    }>;
+    refreshTokenGrant: (params: {
+        clientId: string;
+        clientSecret?: string;
+        refreshToken: string;
+        scope?: string;
+    }) => Promise<{
+        accessToken: string;
+        tokenType: string;
+        expiresIn: number;
+        refreshToken: string;
+        scope?: string;
+        idToken?: string;
+    }>;
+    clientCredentialsGrant: (params: {
+        clientId: string;
+        clientSecret: string;
+        scope?: string;
+    }) => Promise<{
+        accessToken: string;
+        tokenType: string;
+        expiresIn: number;
+    }>;
+    revokeToken: (token: string) => Promise<void>;
+    introspectToken: (token: string) => Promise<{
+        active: boolean;
+        clientId?: string;
+        userId?: string;
+        scope?: string;
+    }>;
+    createPendingFlow: (params: {
+        clientId: string;
+        redirectUri: string;
+        scope?: string;
+        state: string;
+        codeChallenge?: string;
+        codeChallengeMethod?: string;
+        userId?: string;
+    }) => Promise<{
+        flowId: string;
+    }>;
+    /**
+     * Read a pending flow without consuming it. Throws if not found, expired,
+     * or (when `userId` is supplied) owned by a different user — in the
+     * "different user" case the error is `not_found` rather than `forbidden`
+     * to avoid confirming the flow's existence.
+     */
+    getPendingFlow: (flowId: string | number, context?: {
+        userId?: string;
+    }) => Promise<PendingFlowRecord>;
+    /** Read and delete a pending flow (single-use). Throws if not found or expired. */
+    resumePendingFlow: (flowId: string | number, context?: {
+        userId?: string;
+    }) => Promise<PendingFlowRecord>;
+    getUserInfo: (token: string) => Promise<FortressUser | null>;
+    /** Rotate the RS256 id-token signing key and prune expired retired keys. */
+    rotateSigningKey: () => Promise<{
+        kid: string;
+    }>;
+    handleTokenRequest: (body: TokenRequestBody, clientAuth?: ClientAuth) => Promise<Record<string, unknown>>;
+    handleIntrospectRequest: (body: {
+        token: string;
+    }, clientAuth: ClientAuth) => Promise<Record<string, unknown>>;
+    handleRevokeRequest: (body: {
+        token: string;
+    }, clientAuth: ClientAuth) => Promise<void>;
+    /**
+     * OIDC Core 1.0 §5.3 userinfo endpoint. Returns the standard claims set
+     * (`sub`, `email`, `email_verified`, `name`, `preferred_username`,
+     * `updated_at`) gated by the access token's scope (§5.4), plus anything
+     * the {@link OAuthConfig.userinfoClaims} hook contributes. Throws 401
+     * for invalid / expired tokens (RFC 6750).
+     */
+    handleUserInfoRequest: (bearerToken: string) => Promise<Record<string, unknown>>;
+    /**
+     * RFC 7517 / OIDC Discovery JWKS endpoint. Returns the AS's public
+     * verification keys (`{ keys: [...] }`). The first call materialises the
+     * active signing key if none has been generated yet; subsequent calls
+     * are cheap reads.
+     */
+    handleJwksRequest: () => Promise<Record<string, unknown>>;
+    handleDiscovery: () => Record<string, unknown>;
+    /**
+     * Handle GET /oauth/authorize. Validates the query, creates a pending
+     * flow, and returns the URL to redirect the browser to (login if no
+     * user, consent if authenticated).
+     */
+    handleAuthorizeRequest: (query: Record<string, string | undefined>, context: {
+        userId?: string;
+    }) => Promise<{
+        redirectUrl: string;
+        flowId: string;
+    }>;
+    /**
+     * Handle GET /oauth/flows/:flowId. Returns the consent metadata the host
+     * app's consent page renders. Throws if the flow is unknown or expired.
+     *
+     * Requires the request principal to own the flow — the first authenticated
+     * read claims the flow for `context.userId` (trust-on-first-use); every
+     * subsequent read MUST come from the same user or the response is 404.
+     */
+    handleGetFlow: (flowId: string | number, context: {
+        userId: string;
+    }) => Promise<{
+        flowId: string;
+        client: {
+            clientId: string;
+            name: string;
+        };
+        redirectUri: string;
+        scopes: string[];
+        state: string;
+    }>;
+    /**
+     * Handle POST /oauth/flows/:flowId/approve. Issues an authorization code
+     * for the authenticated user, deletes the pending flow, and returns the
+     * URL the browser should be sent back to (the OAuth client's redirect_uri
+     * with `?code=...&state=...`).
+     */
+    handleApproveFlow: (flowId: string | number, context: {
+        userId: string;
+        authTimeSeconds?: number;
+    }) => Promise<{
+        redirectUrl: string;
+    }>;
+    /**
+     * Handle POST /oauth/flows/:flowId/deny. Deletes the pending flow and
+     * returns the URL the browser should be sent back to (redirect_uri with
+     * `?error=access_denied&state=...`).
+     *
+     * Requires the request principal to own the flow.
+     */
+    handleDenyFlow: (flowId: string | number, context: {
+        userId: string;
+    }) => Promise<{
+        redirectUrl: string;
+    }>;
+    resolveTokenPermissions: (token: string) => Promise<{
+        resource: string;
+        action: string;
+    }[]>;
+}
+/**
+ * OAuth 2.0 server plugin factory. Returns a {@link FortressPlugin} that
+ * implements the authorization-code grant (with PKCE) and client-credentials
+ * grant, persists clients and tokens, and exposes `/authorize` and `/token`
+ * endpoints when mounted on a framework adapter.
+ */
+declare function oauth(config?: OAuthConfig): FortressPlugin & {
+    readonly name: 'oauth';
+};
+/**
+ * RFC 8252 §8.4 redirect-URI matcher with the loopback exception.
+ *
+ * Confidential clients still get exact-match (the registered URI must equal
+ * the inbound URI byte-for-byte). Native / public clients that registered an
+ * `http://127.0.0.1/<path>` or `http://[::1]/<path>` redirect MUST be allowed
+ * to vary the port at runtime, because the loopback HTTP server picks one
+ * dynamically. Path, query, and fragment still have to match.
+ *
+ * This is intentionally narrow: only `127.0.0.1` and `[::1]` get the
+ * any-port leniency. `localhost` (DNS-resolved) is NOT widened — RFC 8252
+ * §8.3 actively recommends against it for security reasons (DNS rebinding).
+ */
+declare function matchRedirectUri(registered: string, inbound: string): boolean;
+
+/**
+ * Map a fortress user record to an OIDC-Core-§5.1 claims object, gated by
+ * the access token's scope per §5.4.
+ *
+ * Exported so host apps with a custom `handleUserInfoRequest` (e.g. one
+ * that adds tenant claims) can compose on top of the same baseline rather
+ * than re-implementing the OIDC shape from scratch.
+ */
+declare function toOidcUserinfo(user: FortressUser, scope: string | null | undefined): Record<string, unknown>;
+
+export { type AuthorizeRequestParams, type ClientAuth, type OAuthConfig, type OAuthMethods, type PendingFlowRecord, type TokenEndpointAuthMethod, type TokenRequestBody, generateCodeChallenge, generateCodeVerifier, matchRedirectUri, oauth, toOidcUserinfo, verifyCodeChallenge };