@udibo/oauth2 0.1.0

package/esm/server/introspection-token-reader.js

@@ -0,0 +1,164 @@
+/**
+ * Token reader that validates tokens via an OAuth2 introspection endpoint.
+ *
+ * This is the standard way for resource servers to validate tokens when
+ * they are separate from the authorization server. The reader calls the
+ * authorization server's introspection endpoint (RFC 7662) to check
+ * whether a token is active and retrieve its metadata.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7662
+ * @module
+ */
+import { ServerError, TemporarilyUnavailableError } from "../errors.js";
+import { BasicScope } from "../models/scope.js";
+import { encodeBasicAuth } from "../utils/basic-auth.js";
+/**
+ * Validates tokens by calling an OAuth2 introspection endpoint (RFC 7662).
+ *
+ * Use this with {@linkcode ResourceServer} when your resource server is
+ * separate from the authorization server. The reader authenticates with
+ * the introspection endpoint using client credentials (HTTP Basic Auth)
+ * and projects the response into the resource server's `Client` / `User`
+ * types via the {@linkcode IntrospectionTokenReaderOptions.getClient} and
+ * {@linkcode IntrospectionTokenReaderOptions.getUser} mappers.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   IntrospectionTokenReader,
+ *   ResourceServer,
+ * } from "@udibo/oauth2/server/resource";
+ *
+ * interface MyClient { id: string }
+ * interface MyUser { id: string; email?: string }
+ *
+ * const tokenReader = new IntrospectionTokenReader<MyClient, MyUser>({
+ *   introspectionEndpoint: "https://auth.example.com/introspect",
+ *   clientId: "my-api",
+ *   clientSecret: "my-secret",
+ *   getClient: (data) => ({ id: data.client_id! }),
+ *   getUser: (data) =>
+ *     data.sub
+ *       ? { id: data.sub, email: data.email as string | undefined }
+ *       : undefined,
+ * });
+ *
+ * const resourceServer = new ResourceServer<MyClient, MyUser>({
+ *   resolve: () => ({ services: { tokenService: tokenReader } }),
+ * });
+ * ```
+ */
+export class IntrospectionTokenReader {
+    introspectionEndpoint;
+    clientId;
+    clientSecret;
+    Scope;
+    getClient;
+    getUser;
+    fetchTimeoutMs;
+    customFetch;
+    /**
+     * `Scope` defaults to {@linkcode BasicScope}, `fetchTimeoutMs` to 5000, and
+     * `fetch` to the global `fetch` when omitted from `options`.
+     */
+    constructor(options) {
+        this.introspectionEndpoint = options.introspectionEndpoint;
+        this.clientId = options.clientId;
+        this.clientSecret = options.clientSecret;
+        this.Scope = options.Scope ??
+            BasicScope;
+        this.getClient = options.getClient;
+        this.getUser = options.getUser;
+        this.fetchTimeoutMs = options.fetchTimeoutMs ?? 5_000;
+        this.customFetch = options.fetch;
+    }
+    /**
+     * Validates an access token by calling the introspection endpoint.
+     *
+     * Sends a POST request with the token to the configured introspection
+     * endpoint, authenticated with client credentials via HTTP Basic Auth.
+     *
+     * @returns The token with client/user/scope info, or `undefined` when the
+     *   endpoint reports the token inactive (RFC 7662 `{ active: false }`) or
+     *   does not identify it as a bearer access token.
+     * @throws {TemporarilyUnavailableError} If the introspection endpoint is
+     *   unreachable, takes longer than
+     *   {@linkcode IntrospectionTokenReaderOptions.fetchTimeoutMs} to answer, or
+     *   returns a 5xx — a down authorization server must be distinguishable from
+     *   a genuinely invalid token (which is `undefined` → `invalid_token`), not
+     *   collapsed into it.
+     * @throws {ServerError} If the endpoint returns a 4xx (e.g. the reader's own
+     *   introspection credentials are rejected) — a misconfiguration, not a
+     *   verdict on the caller's token.
+     *
+     * An active response is only accepted when its `token_type` names a bearer
+     * token. RFC 7662 answers for refresh tokens too, and a refresh token's
+     * response is otherwise indistinguishable from an access token's — without
+     * this check a refresh token presented as `Authorization: Bearer …` would
+     * authenticate at the resource server, bypassing rotation and reuse
+     * detection. An authorization server that omits `token_type` from an active
+     * response cannot be read by this reader.
+     */
+    async getToken(accessToken) {
+        const data = await this.#introspect(accessToken);
+        if (!data.active)
+            return undefined;
+        if (data.token_type?.toLowerCase() !== "bearer")
+            return undefined;
+        const [client, user] = await Promise.all([
+            this.getClient(data),
+            this.getUser?.(data),
+        ]);
+        return {
+            accessToken,
+            accessTokenExpiresAt: data.exp ? new Date(data.exp * 1000) : undefined,
+            client,
+            user,
+            scope: data.scope
+                ? new this.Scope(data.scope)
+                : undefined,
+            claims: data,
+        };
+    }
+    async #introspect(accessToken) {
+        const fetchImpl = this.customFetch ?? globalThis.fetch;
+        const controller = new AbortController();
+        const deadline = setTimeout(() => controller.abort(), this.fetchTimeoutMs);
+        try {
+            let response;
+            try {
+                response = await fetchImpl(this.introspectionEndpoint, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/x-www-form-urlencoded",
+                        "Authorization": encodeBasicAuth(this.clientId, this.clientSecret),
+                    },
+                    body: new URLSearchParams({ token: accessToken }),
+                    signal: controller.signal,
+                });
+            }
+            catch (cause) {
+                throw new TemporarilyUnavailableError("token introspection request failed", { cause });
+            }
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw response.status >= 500
+                    ? new TemporarilyUnavailableError(`token introspection failed (HTTP ${response.status})`)
+                    : new ServerError(`token introspection failed (HTTP ${response.status})`);
+            }
+            try {
+                return await response.json();
+            }
+            catch (cause) {
+                throw controller.signal.aborted
+                    ? new TemporarilyUnavailableError("token introspection request failed", { cause })
+                    : new ServerError("token introspection response was not JSON", {
+                        cause,
+                    });
+            }
+        }
+        finally {
+            clearTimeout(deadline);
+        }
+    }
+}

package/esm/server/jwks-token-reader.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Token reader that validates JWT access tokens locally against the
+ * issuer's published JWKS, with no per-request network hop.
+ *
+ * This is the validating half of RFC 9068 (`at+jwt`): the authorization
+ * server signs access tokens and publishes its public keys at a `jwks_uri`;
+ * the resource server fetches those keys once, caches them, and verifies
+ * every subsequent token in-process. Signature verification uses Web Crypto
+ * only — the package takes no JOSE dependency.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc9068
+ * @see https://datatracker.ietf.org/doc/html/rfc7517
+ * @module
+ */
+import type { ClientInterface } from "../models/client.js";
+import type { AbstractScope, ScopeConstructor } from "../models/scope.js";
+import { BasicScope } from "../models/scope.js";
+import type { Token } from "../models/token.js";
+import type { TokenReaderInterface } from "./services/token.js";
+/**
+ * Claims of a validated JWT access token, as defined by RFC 9068 §2.2.
+ *
+ * Passed to the {@linkcode JwksTokenReaderOptions.getClient} and
+ * {@linkcode JwksTokenReaderOptions.getUser} mappers. Issuers routinely add
+ * their own claims (roles, tenant, email); the index signature exposes them.
+ */
+export interface JwtAccessTokenClaims {
+    /** Issuer that signed the token. Verified against the configured issuer. */
+    iss: string;
+    /** Subject — the end user, or the client itself for client-credentials tokens. */
+    sub?: string;
+    /** Audience(s) the token is intended for. Verified against the configured audience. */
+    aud: string | string[];
+    /** Expiration time, seconds since the epoch. */
+    exp: number;
+    /** Issued-at time, seconds since the epoch. */
+    iat?: number;
+    /** Not-before time, seconds since the epoch. */
+    nbf?: number;
+    /** Unique token identifier. */
+    jti?: string;
+    /** Client the token was issued to. */
+    client_id?: string;
+    /** Space-delimited granted scopes. */
+    scope?: string;
+    /** Granted scopes as an array or string — the variant some issuers emit instead of `scope`. */
+    scp?: string | string[];
+    /** Extension claims. Issuers may add anything. */
+    [claim: string]: unknown;
+}
+/**
+ * Options for configuring the JWKS token reader.
+ *
+ * {@linkcode issuer} and {@linkcode audience} are required because RFC 9068
+ * §4 requires a resource server to reject tokens minted for a different
+ * issuer or a different audience — with local validation there is no
+ * authorization server in the request path to do it for you.
+ */
+export interface JwksTokenReaderOptions<Client extends ClientInterface, User, S extends AbstractScope = BasicScope> {
+    /**
+     * Expected `iss` claim. Also the discovery base when
+     * {@linkcode jwksUri} is omitted.
+     */
+    issuer: string;
+    /**
+     * Accepted `aud` claim value(s) — this resource server's identifier. A
+     * token passes when its `aud` (string or array) includes at least one of
+     * these. Authorization servers that default `aud` to the client id
+     * require listing the client ids you accept.
+     */
+    audience: string | string[];
+    /**
+     * URL of the issuer's JWKS. Omit to discover it from `issuer`, trying
+     * `/.well-known/oauth-authorization-server` then
+     * `/.well-known/openid-configuration` inserted before the issuer's path
+     * component (RFC 8414 §3.1), then the OIDC Core form with
+     * `/.well-known/openid-configuration` appended. For a path-less issuer the
+     * last two are the same URL and only one request is made.
+     */
+    jwksUri?: string;
+    /**
+     * JWS algorithms accepted from the token header, intersected with what the
+     * matched key supports. Defaults to every asymmetric algorithm Web Crypto
+     * covers: `ES256`/`ES384`/`ES512`, `RS256`/`RS384`/`RS512`, and
+     * `PS256`/`PS384`/`PS512`. Pin it to what your issuer actually signs with
+     * when you can. Symmetric (`HS*`) and `none` are never accepted.
+     */
+    algorithms?: string[];
+    /**
+     * Accepted `typ` header values, compared case-insensitively with an
+     * optional `application/` prefix. Defaults to `["at+jwt"]` per RFC 9068 §4.
+     *
+     * This is the first line of defense against another JWT the same issuer
+     * signs — an OIDC `id_token` above all — being replayed as an access
+     * token. Prefer configuring your issuer to stamp `at+jwt` over widening
+     * this. If you must widen it (`["at+jwt", "jwt"]`) or disable it (`[]`),
+     * give this API an {@linkcode audience} that is **not** one of your client
+     * ids, since an `id_token`'s `aud` is a client id. The
+     * {@linkcode clientIdClaim} requirement and the rejection of
+     * `id_token`-only claims still apply either way.
+     */
+    types?: string[];
+    /**
+     * Claim carrying the client id, required on every accepted token (RFC 9068
+     * §2.2 makes `client_id` REQUIRED, and its absence is what tells an
+     * `id_token` apart from an access token). Defaults to `"client_id"`; point
+     * it at the vendor claim for issuers that deviate — Okta's `cid`, Azure
+     * AD v1's `appid`. There is deliberately no way to drop the requirement.
+     */
+    clientIdClaim?: string;
+    /**
+     * Leeway in seconds applied to `exp` and `nbf` to absorb clock drift
+     * between the issuer and this server. Defaults to 30.
+     *
+     * This governs this reader's own claim checks. The token it returns carries
+     * the issuer's `exp` verbatim, and {@linkcode ResourceServer} re-checks that
+     * against its own {@linkcode ResourceServerOptions.clockSkewSeconds}, which
+     * defaults to no leeway — so set that one too for a resource server that
+     * must tolerate an about-to-expire token.
+     */
+    clockSkewSeconds?: number;
+    /**
+     * How long a fetched JWKS is served before the next validation refreshes
+     * it. Defaults to 600000 (10 minutes). A refresh that fails keeps serving
+     * the cached keys. Zero or negative makes every read refresh — supported,
+     * and the deterministic setting for tests, but it leans on
+     * {@link JwksTokenReaderOptions.minFetchIntervalMs} alone for rate limiting.
+     */
+    cacheMaxAgeMs?: number;
+    /**
+     * Minimum interval between JWKS fetches. Defaults to 30000 (30 seconds).
+     * This is the guard that stops a flood of tokens bearing unknown `kid`s
+     * from turning this reader into a JWKS-endpoint DoS amplifier; the cost is
+     * that a key rotation is picked up at most one interval late. Zero or
+     * negative removes the throttle entirely — a test-only setting, never
+     * appropriate against a real endpoint.
+     */
+    minFetchIntervalMs?: number;
+    /**
+     * Deadline in milliseconds for a JWKS or discovery request. Defaults to
+     * 5000. Without it a blackholed endpoint (dropped packets rather than a
+     * refused connection) would hang the refresh — and with it every request
+     * that joins the shared in-flight fetch. Ignored by an injected
+     * {@linkcode fetch} that doesn't honour `AbortSignal`.
+     */
+    fetchTimeoutMs?: number;
+    /** Optional scope constructor for parsing scope strings. Defaults to BasicScope. */
+    Scope?: ScopeConstructor<S>;
+    /**
+     * Projects a validated token's claims into a typed `Client`. Required
+     * because the client shape is app-specific; `client_id` (RFC 9068) is the
+     * usual key.
+     *
+     * May be async — return a promise to enrich from a DB lookup.
+     */
+    getClient: (claims: JwtAccessTokenClaims) => Client | Promise<Client>;
+    /**
+     * Projects a validated token's claims into a typed `User`. Return
+     * `undefined` when the token doesn't represent a user (e.g.
+     * client-credentials tokens). Omit entirely if your app never reads user
+     * info off the token.
+     *
+     * May be async — return a promise to enrich from a DB lookup or the
+     * issuer's UserInfo endpoint, using `claims.sub` as the lookup key.
+     */
+    getUser?: (claims: JwtAccessTokenClaims) => User | undefined | Promise<User | undefined>;
+    /**
+     * `fetch` implementation used for JWKS and discovery requests. Defaults to
+     * the global `fetch`. Inject it to route through a custom client (mTLS,
+     * timeouts, retries) or to stub the network in tests.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Validates JWT access tokens (RFC 9068) against the issuer's remote JWKS.
+ *
+ * Use this with {@linkcode ResourceServer} when the authorization server
+ * issues **signed** access tokens: keys are fetched once and cached on the
+ * instance, so validation costs no network round-trip per request — the
+ * trade-off against {@linkcode IntrospectionTokenReader}, which sees
+ * revocation immediately but calls the authorization server every time. A
+ * revoked JWT stays valid here until it expires, so keep access-token
+ * lifetimes short, or introspect on the endpoints where revocation latency
+ * matters.
+ *
+ * A token is accepted only when its signature verifies against a published
+ * key whose algorithm the header matches, and its `typ`, `iss`, `aud`, `exp`
+ * and `nbf` all satisfy the configuration. Anything else is `undefined` —
+ * the same `invalid_token` surface as an unknown opaque token. Unreachable
+ * key material throws instead, so a down issuer is never reported as a bad
+ * token.
+ *
+ * **Token substitution.** An access token must never be confused with
+ * another JWT the same issuer signs. Three checks enforce that
+ * independently: `typ` must be `at+jwt`
+ * ({@linkcode JwksTokenReaderOptions.types}), the client-id claim must be
+ * present ({@linkcode JwksTokenReaderOptions.clientIdClaim}, REQUIRED by
+ * RFC 9068 §2.2 and absent from an `id_token`), and `id_token`-only claims
+ * (`nonce`, `at_hash`, `c_hash`, `s_hash`) are rejected outright.
+ * `auth_time`, `acr` and `amr` are **not** in that list — RFC 9068 §2.2.1
+ * permits them on an access token. A `crit` header is rejected per RFC 7515
+ * §4.1.11, since this reader understands no JWS extensions.
+ *
+ * The cache lives on the instance: construct one reader and reuse it.
+ *
+ * @example
+ * ```ts
+ * import { JwksTokenReader, ResourceServer } from "@udibo/oauth2/server/resource";
+ *
+ * interface MyClient { id: string }
+ * interface MyUser { id: string }
+ *
+ * const tokenReader = new JwksTokenReader<MyClient, MyUser>({
+ *   issuer: "https://auth.example.com",
+ *   audience: "https://api.example.com",
+ *   getClient: (claims) => ({ id: String(claims.client_id) }),
+ *   getUser: (claims) => claims.sub ? { id: claims.sub } : undefined,
+ * });
+ *
+ * const resourceServer = new ResourceServer<MyClient, MyUser>({
+ *   resolve: () => ({ services: { tokenService: tokenReader } }),
+ * });
+ * ```
+ */
+export declare class JwksTokenReader<Client extends ClientInterface, User, S extends AbstractScope = BasicScope> implements TokenReaderInterface<Client, User, S> {
+    #private;
+    /**
+     * Defaults: every Web Crypto asymmetric algorithm accepted, `at+jwt`
+     * required as `typ`, `client_id` as the required client-id claim, 30
+     * seconds of clock skew, a 10-minute cache with a 30-second minimum
+     * between fetches, a 5-second request deadline, {@linkcode BasicScope},
+     * and the global `fetch`.
+     *
+     * @throws {TypeError} If `issuer` is not an absolute URL, `audience` is
+     *   empty, or `algorithms` names an algorithm this package cannot verify
+     *   (a silently ignored entry would read as a policy that isn't enforced).
+     */
+    constructor(options: JwksTokenReaderOptions<Client, User, S>);
+    /**
+     * Validates a JWT access token against the cached JWKS.
+     *
+     * Refreshes the keys when no published key verifies the signature — at
+     * most one fetch per {@linkcode
+     * JwksTokenReaderOptions.minFetchIntervalMs}, shared by concurrent
+     * callers. A token whose `kid` matched a cached key and still failed
+     * verification is a forgery, not a rotation, and provokes no fetch. A
+     * stale cache refreshes in the background: requests are served from the
+     * cached keys rather than blocked on the issuer.
+     *
+     * @returns The token with client/user/scope info, or `undefined` when the
+     *   token is malformed, signed by an unknown or unaccepted key, or fails
+     *   any claim check.
+     * @throws {TemporarilyUnavailableError} If the JWKS (or discovery
+     *   document) is unreachable or returns a 5xx **and** no cached keys are
+     *   available — a down issuer must be distinguishable from a genuinely
+     *   invalid token, not collapsed into it. Once keys are cached, a failed
+     *   refresh is absorbed and the cached keys keep serving.
+     * @throws {ServerError} If the JWKS endpoint returns a 4xx or a body that
+     *   is not a JWKS, or discovery reports no `jwks_uri` — a
+     *   misconfiguration, not a verdict on the caller's token.
+     */
+    getToken(accessToken: string): Promise<Token<Client, User, S> | undefined>;
+}