@dwk/oauth 0.1.0-beta.0

package/dist/par.js

@@ -0,0 +1,132 @@
+/**
+ * Pushed Authorization Requests (RFC 9126).
+ *
+ * The client POSTs its authorization-request parameters directly to this
+ * endpoint; the server validates and stores them and hands back a short-lived,
+ * single-use `request_uri`. The client then starts the normal authorization
+ * flow with just `client_id` + `request_uri`, so the request parameters never
+ * travel through the browser/redirect and cannot be tampered with.
+ *
+ * This lib owns the *push* side (validate → store → mint `request_uri`). The
+ * *consume* side lives at the authorization endpoint in the consuming package:
+ * use {@link parseRequestUri} to recover the reference and the store's
+ * single-use `consume` ({@link PushedAuthorizationStore}). When DPoP binding is
+ * enabled and the push carries a `DPoP` header, the proof is verified via
+ * `@dwk/dpop` and its `jkt` recorded so the eventual token is key-bound
+ * (RFC 9449 §10).
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9126
+ */
+import { verifyDpopProof } from "@dwk/dpop";
+import { hostFromUrl } from "@dwk/log";
+import { randomIdentifier } from "./encoding";
+import { OAuthError, oauthErrorResponse } from "./errors";
+import { json, methodNotAllowed, readForm } from "./http";
+import { OAuthLogEvent } from "./log";
+import { emit, resolveObservability, } from "./observability";
+/** The URN prefix RFC 9126 §2.2 mandates for a PAR `request_uri`. */
+export const PUSHED_REQUEST_URI_PREFIX = "urn:ietf:params:oauth:request_uri:";
+const DEFAULT_LIFETIME_SECONDS = 60;
+/** Reference entropy in bytes: 256 bits of unguessable `request_uri`. */
+const REFERENCE_BYTES = 32;
+/** Build the `request_uri` URN for a stored reference. */
+export function requestUriFor(reference) {
+    return `${PUSHED_REQUEST_URI_PREFIX}${reference}`;
+}
+/**
+ * Recover the opaque reference from a PAR `request_uri`, or `null` if `uri` is
+ * not a `urn:ietf:params:oauth:request_uri:` value. Use this at the
+ * authorization endpoint before calling the store's single-use `consume`.
+ */
+export function parseRequestUri(uri) {
+    if (!uri.startsWith(PUSHED_REQUEST_URI_PREFIX))
+        return null;
+    const reference = uri.slice(PUSHED_REQUEST_URI_PREFIX.length);
+    return reference.length > 0 ? reference : null;
+}
+/**
+ * Create the pushed-authorization-request endpoint handler. On success it
+ * returns `201` with `{ request_uri, expires_in }` (RFC 9126 §2.2).
+ */
+export function createPushedAuthorizationRequestHandler(config) {
+    const obs = resolveObservability(config);
+    const clock = config.now ?? (() => Math.floor(Date.now() / 1000));
+    const lifetime = config.lifetimeSeconds ?? DEFAULT_LIFETIME_SECONDS;
+    return async (request) => {
+        if (request.method.toUpperCase() !== "POST") {
+            return methodNotAllowed("POST");
+        }
+        // Clone before consuming the body so the authenticator can read it too.
+        const authRequest = request.clone();
+        const form = await readForm(request);
+        // RFC 9126 §2.1: the PAR body MUST NOT itself contain a `request_uri`.
+        if (form.has("request_uri")) {
+            emit(obs, "warn", OAuthLogEvent.PushedRequestRejected, {
+                reason: "request_uri_present",
+            });
+            return oauthErrorResponse(OAuthError.InvalidRequest, "`request_uri` is not allowed in a pushed authorization request");
+        }
+        const clientId = form.get("client_id") ?? "";
+        if (!clientId) {
+            emit(obs, "warn", OAuthLogEvent.PushedRequestRejected, {
+                reason: "client_id_missing",
+            });
+            return oauthErrorResponse(OAuthError.InvalidRequest, "`client_id` is required");
+        }
+        // Authenticate with the extracted `client_id` in hand, so the authenticator
+        // can enforce the RFC 9126 §2.1 match (authenticated client == client_id).
+        if (config.authenticate &&
+            !(await config.authenticate(authRequest, clientId))) {
+            emit(obs, "warn", OAuthLogEvent.PushedRequestRejected, {
+                reason: "unauthenticated",
+            });
+            return oauthErrorResponse(OAuthError.InvalidClient, "pushed authorization requests require client authentication", 401, { "WWW-Authenticate": "Bearer" });
+        }
+        const params = {};
+        for (const [key, value] of form)
+            params[key] = value;
+        if (config.validate) {
+            const problem = await config.validate(params);
+            if (problem !== null && problem !== undefined) {
+                emit(obs, "warn", OAuthLogEvent.PushedRequestRejected, {
+                    reason: "validation_failed",
+                    clientHost: hostFromUrl(clientId),
+                });
+                return oauthErrorResponse(OAuthError.InvalidRequest, problem);
+            }
+        }
+        let jkt;
+        if (config.dpopBinding) {
+            const proof = request.headers.get("DPoP");
+            if (proof) {
+                const dpop = await verifyDpopProof({
+                    proof,
+                    htm: "POST",
+                    htu: config.endpoint ?? request.url,
+                });
+                if (!dpop.valid || !dpop.jkt) {
+                    emit(obs, "warn", OAuthLogEvent.PushedRequestRejected, {
+                        reason: "dpop_invalid",
+                        clientHost: hostFromUrl(clientId),
+                    });
+                    return oauthErrorResponse(OAuthError.InvalidDpopProof, `DPoP proof verification failed: ${dpop.reason ?? "unknown"}`);
+                }
+                jkt = dpop.jkt;
+            }
+        }
+        const reference = randomIdentifier(REFERENCE_BYTES);
+        const record = {
+            reference,
+            clientId,
+            params,
+            expiresAt: clock() + lifetime,
+            ...(jkt ? { jkt } : {}),
+        };
+        await config.saveRequest(record);
+        emit(obs, "info", OAuthLogEvent.PushedRequestStored, {
+            clientHost: hostFromUrl(clientId),
+        });
+        return json({ request_uri: requestUriFor(reference), expires_in: lifetime }, 201);
+    };
+}
+//# sourceMappingURL=par.js.map

package/dist/par.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"par.js","sourceRoot":"","sources":["../src/par.ts"],"names":[],"mappings":"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"}

package/dist/registration.d.ts

@@ -0,0 +1,71 @@
+/**
+ * OAuth 2.0 Dynamic Client Registration (RFC 7591).
+ *
+ * A POST endpoint where a client submits its metadata and receives an issued
+ * `client_id` (and, for confidential clients, a `client_secret`). The lib
+ * validates the metadata against the registered standard fields and the
+ * server's supported value lists, normalizes defaults, mints the identifier(s),
+ * and delegates persistence to {@link ClientRegistrationConfig.saveClient}.
+ *
+ * Validation is deliberately strict on the security-relevant fields
+ * (`redirect_uris`, `token_endpoint_auth_method`, and the
+ * grant/response-type pairing) and ignores unrecognized members rather than
+ * echoing arbitrary client-supplied data back as registered metadata.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc7591
+ */
+import { type OAuthErrorCode } from "./errors";
+import { type ObservabilityConfig } from "./observability";
+import type { EndpointAuthenticator } from "./introspection";
+import type { ClientRecord } from "./store";
+/** Configuration for {@link createClientRegistrationHandler}. */
+export interface ClientRegistrationConfig extends ObservabilityConfig {
+    /** Persist a newly registered client record. */
+    readonly saveClient: (record: ClientRecord) => Promise<void>;
+    /**
+     * Optionally authenticate the caller (RFC 7591 §3: an "initial access token"
+     * may gate open registration). Omit to allow open registration. Return
+     * `false` to reject with `401 invalid_client`.
+     */
+    readonly authenticate?: EndpointAuthenticator;
+    /** Mint the `client_id`. Defaults to a 256-bit random base64url string. */
+    readonly generateClientId?: () => string;
+    /** Mint the `client_secret`. Defaults to a 256-bit random base64url string. */
+    readonly generateClientSecret?: () => string;
+    /**
+     * Extra redirect-URI policy applied after structural validation (e.g. an
+     * allowlist of hosts). Return `false` to reject with `invalid_redirect_uri`.
+     */
+    readonly redirectUriPolicy?: (uri: string) => boolean;
+    /** Grant types the server allows. Defaults to authorization_code + refresh_token. */
+    readonly grantTypesSupported?: readonly string[];
+    /** Response types the server allows. Defaults to `["code"]`. */
+    readonly responseTypesSupported?: readonly string[];
+    /** Token-endpoint auth methods the server allows. Defaults to none/basic/post. */
+    readonly tokenEndpointAuthMethodsSupported?: readonly string[];
+    /** Current time (seconds since the epoch). Defaults to `Date.now()`. */
+    readonly now?: () => number;
+}
+/** A validation failure: the error code and a human-readable description. */
+interface MetadataError {
+    readonly error: OAuthErrorCode;
+    readonly description: string;
+}
+/**
+ * Validate and normalize submitted client metadata. Returns the normalized
+ * metadata (defaults applied, only recognized members retained) or a
+ * {@link MetadataError}. Pure and side-effect-free, so it unit-tests directly.
+ */
+export declare function validateClientMetadata(input: unknown, config: ClientRegistrationConfig): {
+    readonly metadata: Record<string, unknown>;
+} | MetadataError;
+/**
+ * Create the dynamic-client-registration endpoint handler. On success it returns
+ * `201` with the client information response (RFC 7591 §3.2.1): the issued
+ * `client_id`/`client_id_issued_at`, an optional `client_secret`
+ * (+`client_secret_expires_at: 0`, meaning non-expiring) for confidential
+ * clients, and the registered metadata.
+ */
+export declare function createClientRegistrationHandler(config: ClientRegistrationConfig): (request: Request) => Promise<Response>;
+export {};
+//# sourceMappingURL=registration.d.ts.map

package/dist/registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAkC,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAG/E,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAU5C,iEAAiE;AACjE,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAC9C,2EAA2E;IAC3E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,MAAM,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACtD,qFAAqF;IACrF,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,gEAAgE;IAChE,QAAQ,CAAC,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpD,kFAAkF;IAClF,QAAQ,CAAC,iCAAiC,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/D,wEAAwE;IACxE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,6EAA6E;AAC7E,UAAU,aAAa;IACrB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAoCD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,wBAAwB,GAC/B;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,aAAa,CAiJhE;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,wBAAwB,GAC/B,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA+DzC"}

package/dist/registration.js

@@ -0,0 +1,258 @@
+/**
+ * OAuth 2.0 Dynamic Client Registration (RFC 7591).
+ *
+ * A POST endpoint where a client submits its metadata and receives an issued
+ * `client_id` (and, for confidential clients, a `client_secret`). The lib
+ * validates the metadata against the registered standard fields and the
+ * server's supported value lists, normalizes defaults, mints the identifier(s),
+ * and delegates persistence to {@link ClientRegistrationConfig.saveClient}.
+ *
+ * Validation is deliberately strict on the security-relevant fields
+ * (`redirect_uris`, `token_endpoint_auth_method`, and the
+ * grant/response-type pairing) and ignores unrecognized members rather than
+ * echoing arbitrary client-supplied data back as registered metadata.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc7591
+ */
+import { hostFromUrl } from "@dwk/log";
+import { randomIdentifier } from "./encoding";
+import { OAuthError, oauthErrorResponse } from "./errors";
+import { json, methodNotAllowed, readJson } from "./http";
+import { OAuthLogEvent } from "./log";
+import { emit, resolveObservability, } from "./observability";
+const DEFAULT_GRANT_TYPES = ["authorization_code", "refresh_token"];
+const DEFAULT_RESPONSE_TYPES = ["code"];
+const DEFAULT_AUTH_METHODS = [
+    "none",
+    "client_secret_basic",
+    "client_secret_post",
+];
+/** Recognized RFC 7591 string-valued metadata members echoed back on success. */
+const STRING_FIELDS = [
+    "client_name",
+    "client_uri",
+    "logo_uri",
+    "scope",
+    "tos_uri",
+    "policy_uri",
+    "jwks_uri",
+    "software_id",
+    "software_version",
+];
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+/**
+ * Whether `uri` is an acceptable redirect URI: a parseable absolute URL with no
+ * fragment component (RFC 7591 §2 / RFC 6749 §3.1.2 — the fragment is reserved
+ * for the response and must not be pre-registered).
+ */
+function isValidRedirectUri(uri) {
+    try {
+        return new URL(uri).hash === "";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate and normalize submitted client metadata. Returns the normalized
+ * metadata (defaults applied, only recognized members retained) or a
+ * {@link MetadataError}. Pure and side-effect-free, so it unit-tests directly.
+ */
+export function validateClientMetadata(input, config) {
+    if (!isObject(input)) {
+        return {
+            error: OAuthError.InvalidClientMetadata,
+            description: "request body must be a JSON object",
+        };
+    }
+    const authMethods = config.tokenEndpointAuthMethodsSupported ?? DEFAULT_AUTH_METHODS;
+    const grantTypesSupported = config.grantTypesSupported ?? DEFAULT_GRANT_TYPES;
+    const responseTypesSupported = config.responseTypesSupported ?? DEFAULT_RESPONSE_TYPES;
+    // token_endpoint_auth_method (default per RFC 7591 §2).
+    const authMethod = input.token_endpoint_auth_method ?? "client_secret_basic";
+    if (typeof authMethod !== "string" || !authMethods.includes(authMethod)) {
+        return {
+            error: OAuthError.InvalidClientMetadata,
+            description: `unsupported token_endpoint_auth_method: ${String(authMethod)}`,
+        };
+    }
+    // grant_types / response_types (defaults per RFC 7591 §2).
+    const requestedGrants = input.grant_types ?? ["authorization_code"];
+    if (!isStringArray(requestedGrants)) {
+        return {
+            error: OAuthError.InvalidClientMetadata,
+            description: "grant_types must be an array of strings",
+        };
+    }
+    for (const grant of requestedGrants) {
+        if (!grantTypesSupported.includes(grant)) {
+            return {
+                error: OAuthError.InvalidClientMetadata,
+                description: `unsupported grant_type: ${grant}`,
+            };
+        }
+    }
+    const requestedResponses = input.response_types ?? ["code"];
+    if (!isStringArray(requestedResponses)) {
+        return {
+            error: OAuthError.InvalidClientMetadata,
+            description: "response_types must be an array of strings",
+        };
+    }
+    for (const responseType of requestedResponses) {
+        if (!responseTypesSupported.includes(responseType)) {
+            return {
+                error: OAuthError.InvalidClientMetadata,
+                description: `unsupported response_type: ${responseType}`,
+            };
+        }
+    }
+    // Grant/response-type consistency (RFC 7591 §2): authorization_code ⇔ code.
+    const usesCode = requestedGrants.includes("authorization_code");
+    const wantsCode = requestedResponses.includes("code");
+    if (usesCode !== wantsCode) {
+        return {
+            error: OAuthError.InvalidClientMetadata,
+            description: "grant_types and response_types are inconsistent: " +
+                "`authorization_code` requires `code` and vice versa",
+        };
+    }
+    // redirect_uris: required for redirect-based flows.
+    const needsRedirect = requestedGrants.includes("authorization_code") ||
+        requestedGrants.includes("implicit");
+    const redirectUris = input.redirect_uris;
+    if (redirectUris !== undefined) {
+        if (!isStringArray(redirectUris)) {
+            return {
+                error: OAuthError.InvalidRedirectUri,
+                description: "redirect_uris must be an array of strings",
+            };
+        }
+        for (const uri of redirectUris) {
+            if (!isValidRedirectUri(uri)) {
+                return {
+                    error: OAuthError.InvalidRedirectUri,
+                    description: `invalid redirect_uri: ${uri}`,
+                };
+            }
+            if (config.redirectUriPolicy && !config.redirectUriPolicy(uri)) {
+                return {
+                    error: OAuthError.InvalidRedirectUri,
+                    description: `redirect_uri not permitted: ${uri}`,
+                };
+            }
+        }
+    }
+    if (needsRedirect &&
+        (!isStringArray(redirectUris) || redirectUris.length === 0)) {
+        return {
+            error: OAuthError.InvalidRedirectUri,
+            description: "redirect_uris is required for the requested grant_types",
+        };
+    }
+    // contacts: optional array of strings.
+    if (input.contacts !== undefined && !isStringArray(input.contacts)) {
+        return {
+            error: OAuthError.InvalidClientMetadata,
+            description: "contacts must be an array of strings",
+        };
+    }
+    // jwks: optional object.
+    if (input.jwks !== undefined && !isObject(input.jwks)) {
+        return {
+            error: OAuthError.InvalidClientMetadata,
+            description: "jwks must be a JSON object",
+        };
+    }
+    // Recognized string fields must be strings when present.
+    for (const field of STRING_FIELDS) {
+        if (input[field] !== undefined && typeof input[field] !== "string") {
+            return {
+                error: OAuthError.InvalidClientMetadata,
+                description: `${field} must be a string`,
+            };
+        }
+    }
+    // Assemble normalized metadata: defaults applied, only recognized members.
+    const metadata = {
+        token_endpoint_auth_method: authMethod,
+        grant_types: requestedGrants,
+        response_types: requestedResponses,
+    };
+    if (redirectUris !== undefined)
+        metadata.redirect_uris = redirectUris;
+    if (input.contacts !== undefined)
+        metadata.contacts = input.contacts;
+    if (input.jwks !== undefined)
+        metadata.jwks = input.jwks;
+    for (const field of STRING_FIELDS) {
+        if (input[field] !== undefined)
+            metadata[field] = input[field];
+    }
+    return { metadata };
+}
+/**
+ * Create the dynamic-client-registration endpoint handler. On success it returns
+ * `201` with the client information response (RFC 7591 §3.2.1): the issued
+ * `client_id`/`client_id_issued_at`, an optional `client_secret`
+ * (+`client_secret_expires_at: 0`, meaning non-expiring) for confidential
+ * clients, and the registered metadata.
+ */
+export function createClientRegistrationHandler(config) {
+    const obs = resolveObservability(config);
+    const clock = config.now ?? (() => Math.floor(Date.now() / 1000));
+    const newClientId = config.generateClientId ?? (() => randomIdentifier());
+    const newClientSecret = config.generateClientSecret ?? (() => randomIdentifier());
+    return async (request) => {
+        if (request.method.toUpperCase() !== "POST") {
+            return methodNotAllowed("POST");
+        }
+        // Clone so an authenticator that reads the body (e.g. an initial access
+        // token in the body) does not disturb the handler's own JSON parse. A
+        // registration request carries no `client_id` (one is being issued).
+        if (config.authenticate && !(await config.authenticate(request.clone()))) {
+            emit(obs, "warn", OAuthLogEvent.ClientRegistrationRejected, {
+                reason: "unauthenticated",
+            });
+            return oauthErrorResponse(OAuthError.InvalidClient, "client registration requires authorization", 401, { "WWW-Authenticate": "Bearer" });
+        }
+        const body = await readJson(request);
+        const result = validateClientMetadata(body, config);
+        if ("error" in result) {
+            emit(obs, "warn", OAuthLogEvent.ClientRegistrationRejected, {
+                reason: result.error,
+            });
+            return oauthErrorResponse(result.error, result.description);
+        }
+        const { metadata } = result;
+        const issuedAt = clock();
+        const clientId = newClientId();
+        const confidential = metadata.token_endpoint_auth_method !== "none";
+        const clientSecret = confidential ? newClientSecret() : undefined;
+        const record = {
+            clientId,
+            clientIdIssuedAt: issuedAt,
+            ...(clientSecret ? { clientSecret } : {}),
+            metadata,
+        };
+        await config.saveClient(record);
+        emit(obs, "info", OAuthLogEvent.ClientRegistered, {
+            clientHost: hostFromUrl(clientId),
+        });
+        const response = {
+            client_id: clientId,
+            client_id_issued_at: issuedAt,
+            ...(clientSecret
+                ? { client_secret: clientSecret, client_secret_expires_at: 0 }
+                : {}),
+            ...metadata,
+        };
+        return json(response, 201);
+    };
+}
+//# sourceMappingURL=registration.js.map

package/dist/registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.js","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAuB,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EACL,IAAI,EACJ,oBAAoB,GAErB,MAAM,iBAAiB,CAAC;AAIzB,MAAM,mBAAmB,GAAG,CAAC,oBAAoB,EAAE,eAAe,CAAU,CAAC;AAC7E,MAAM,sBAAsB,GAAG,CAAC,MAAM,CAAU,CAAC;AACjD,MAAM,oBAAoB,GAAG;IAC3B,MAAM;IACN,qBAAqB;IACrB,oBAAoB;CACZ,CAAC;AAqCX,iFAAiF;AACjF,MAAM,aAAa,GAAG;IACpB,aAAa;IACb,YAAY;IACZ,UAAU;IACV,OAAO;IACP,SAAS;IACT,YAAY;IACZ,UAAU;IACV,aAAa;IACb,kBAAkB;CACV,CAAC;AAEX,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;AAC3E,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,GAAW;IACrC,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAc,EACd,MAAgC;IAEhC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO;YACL,KAAK,EAAE,UAAU,CAAC,qBAAqB;YACvC,WAAW,EAAE,oCAAoC;SAClD,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GACf,MAAM,CAAC,iCAAiC,IAAI,oBAAoB,CAAC;IACnE,MAAM,mBAAmB,GAAG,MAAM,CAAC,mBAAmB,IAAI,mBAAmB,CAAC;IAC9E,MAAM,sBAAsB,GAC1B,MAAM,CAAC,sBAAsB,IAAI,sBAAsB,CAAC;IAE1D,wDAAwD;IACxD,MAAM,UAAU,GAAG,KAAK,CAAC,0BAA0B,IAAI,qBAAqB,CAAC;IAC7E,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACxE,OAAO;YACL,KAAK,EAAE,UAAU,CAAC,qBAAqB;YACvC,WAAW,EAAE,2CAA2C,MAAM,CAAC,UAAU,CAAC,EAAE;SAC7E,CAAC;IACJ,CAAC;IAED,2DAA2D;IAC3D,MAAM,eAAe,GAAG,KAAK,CAAC,WAAW,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACpE,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,EAAE,CAAC;QACpC,OAAO;YACL,KAAK,EAAE,UAAU,CAAC,qBAAqB;YACvC,WAAW,EAAE,yCAAyC;SACvD,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,eAAe,EAAE,CAAC;QACpC,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,OAAO;gBACL,KAAK,EAAE,UAAU,CAAC,qBAAqB;gBACvC,WAAW,EAAE,2BAA2B,KAAK,EAAE;aAChD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,kBAAkB,GAAG,KAAK,CAAC,cAAc,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5D,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACvC,OAAO;YACL,KAAK,EAAE,UAAU,CAAC,qBAAqB;YACvC,WAAW,EAAE,4CAA4C;SAC1D,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,YAAY,IAAI,kBAAkB,EAAE,CAAC;QAC9C,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YACnD,OAAO;gBACL,KAAK,EAAE,UAAU,CAAC,qBAAqB;gBACvC,WAAW,EAAE,8BAA8B,YAAY,EAAE;aAC1D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,kBAAkB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO;YACL,KAAK,EAAE,UAAU,CAAC,qBAAqB;YACvC,WAAW,EACT,mDAAmD;gBACnD,qDAAqD;SACxD,CAAC;IACJ,CAAC;IAED,oDAAoD;IACpD,MAAM,aAAa,GACjB,eAAe,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QAC9C,eAAe,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACvC,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,CAAC;IACzC,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,CAAC;YACjC,OAAO;gBACL,KAAK,EAAE,UAAU,CAAC,kBAAkB;gBACpC,WAAW,EAAE,2CAA2C;aACzD,CAAC;QACJ,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC/B,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7B,OAAO;oBACL,KAAK,EAAE,UAAU,CAAC,kBAAkB;oBACpC,WAAW,EAAE,yBAAyB,GAAG,EAAE;iBAC5C,CAAC;YACJ,CAAC;YACD,IAAI,MAAM,CAAC,iBAAiB,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/D,OAAO;oBACL,KAAK,EAAE,UAAU,CAAC,kBAAkB;oBACpC,WAAW,EAAE,+BAA+B,GAAG,EAAE;iBAClD,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IACD,IACE,aAAa;QACb,CAAC,CAAC,aAAa,CAAC,YAAY,CAAC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC,EAC3D,CAAC;QACD,OAAO;YACL,KAAK,EAAE,UAAU,CAAC,kBAAkB;YACpC,WAAW,EAAE,yDAAyD;SACvE,CAAC;IACJ,CAAC;IAED,uCAAuC;IACvC,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnE,OAAO;YACL,KAAK,EAAE,UAAU,CAAC,qBAAqB;YACvC,WAAW,EAAE,sCAAsC;SACpD,CAAC;IACJ,CAAC;IAED,yBAAyB;IACzB,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACtD,OAAO;YACL,KAAK,EAAE,UAAU,CAAC,qBAAqB;YACvC,WAAW,EAAE,4BAA4B;SAC1C,CAAC;IACJ,CAAC;IAED,yDAAyD;IACzD,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,QAAQ,EAAE,CAAC;YACnE,OAAO;gBACL,KAAK,EAAE,UAAU,CAAC,qBAAqB;gBACvC,WAAW,EAAE,GAAG,KAAK,mBAAmB;aACzC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,MAAM,QAAQ,GAA4B;QACxC,0BAA0B,EAAE,UAAU;QACtC,WAAW,EAAE,eAAe;QAC5B,cAAc,EAAE,kBAAkB;KACnC,CAAC;IACF,IAAI,YAAY,KAAK,SAAS;QAAE,QAAQ,CAAC,aAAa,GAAG,YAAY,CAAC;IACtE,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,QAAQ,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IACrE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,QAAQ,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACzD,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,SAAS;YAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B,CAC7C,MAAgC;IAEhC,MAAM,GAAG,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IAClE,MAAM,WAAW,GAAG,MAAM,CAAC,gBAAgB,IAAI,CAAC,GAAG,EAAE,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC1E,MAAM,eAAe,GACnB,MAAM,CAAC,oBAAoB,IAAI,CAAC,GAAG,EAAE,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAE5D,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;QACvB,IAAI,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;YAC5C,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QAED,wEAAwE;QACxE,sEAAsE;QACtE,qEAAqE;QACrE,IAAI,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC;YACzE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,0BAA0B,EAAE;gBAC1D,MAAM,EAAE,iBAAiB;aAC1B,CAAC,CAAC;YACH,OAAO,kBAAkB,CACvB,UAAU,CAAC,aAAa,EACxB,4CAA4C,EAC5C,GAAG,EACH,EAAE,kBAAkB,EAAE,QAAQ,EAAE,CACjC,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;QACrC,MAAM,MAAM,GAAG,sBAAsB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACpD,IAAI,OAAO,IAAI,MAAM,EAAE,CAAC;YACtB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,0BAA0B,EAAE;gBAC1D,MAAM,EAAE,MAAM,CAAC,KAAK;aACrB,CAAC,CAAC;YACH,OAAO,kBAAkB,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;QAC9D,CAAC;QAED,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;QAC5B,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;QAC/B,MAAM,YAAY,GAAG,QAAQ,CAAC,0BAA0B,KAAK,MAAM,CAAC;QACpE,MAAM,YAAY,GAAG,YAAY,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAElE,MAAM,MAAM,GAAiB;YAC3B,QAAQ;YACR,gBAAgB,EAAE,QAAQ;YAC1B,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,QAAQ;SACT,CAAC;QACF,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAEhC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,gBAAgB,EAAE;YAChD,UAAU,EAAE,WAAW,CAAC,QAAQ,CAAC;SAClC,CAAC,CAAC;QACH,MAAM,QAAQ,GAA4B;YACxC,SAAS,EAAE,QAAQ;YACnB,mBAAmB,EAAE,QAAQ;YAC7B,GAAG,CAAC,YAAY;gBACd,CAAC,CAAC,EAAE,aAAa,EAAE,YAAY,EAAE,wBAAwB,EAAE,CAAC,EAAE;gBAC9D,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,QAAQ;SACZ,CAAC;QACF,OAAO,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC7B,CAAC,CAAC;AACJ,CAAC"}

package/dist/revocation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OAuth 2.0 Token Revocation (RFC 7009).
+ *
+ * A POST endpoint where a client asks the authorization server to invalidate a
+ * token. Revocation is **idempotent and forgiving**: an unknown, malformed, or
+ * already-revoked token still yields `200` (RFC 7009 §2.2), so a client can
+ * retry safely and cannot probe token existence by status code. The lib owns the
+ * protocol; the actual invalidation is delegated to
+ * {@link RevocationConfig.revokeToken}, backed by the consuming package's store.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc7009
+ */
+import { type ObservabilityConfig } from "./observability";
+import type { EndpointAuthenticator } from "./introspection";
+/** Configuration for {@link createRevocationHandler}. */
+export interface RevocationConfig extends ObservabilityConfig {
+    /**
+     * Revoke the presented token. MUST be idempotent and MUST NOT throw for an
+     * unknown token — RFC 7009 §2.2 requires `200` regardless. The optional
+     * `tokenTypeHint` is the client's non-binding `token_type_hint`.
+     */
+    readonly revokeToken: (token: string, tokenTypeHint?: string) => Promise<void>;
+    /**
+     * Optionally authenticate the caller (RFC 7009 §2.1: confidential clients
+     * MUST be authenticated). Omit for public clients using the `none` method.
+     * Return `false` to reject with `401 invalid_client`.
+     */
+    readonly authenticate?: EndpointAuthenticator;
+}
+/**
+ * Create the revocation endpoint handler. The returned handler accepts a `POST`
+ * request and returns `200` with an empty body on success.
+ */
+export declare function createRevocationHandler(config: RevocationConfig): (request: Request) => Promise<Response>;
+//# sourceMappingURL=revocation.d.ts.map

package/dist/revocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revocation.d.ts","sourceRoot":"","sources":["../src/revocation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE7D,yDAAyD;AACzD,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,CACpB,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,MAAM,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC;CAC/C;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,gBAAgB,GACvB,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA2CzC"}

package/dist/revocation.js

@@ -0,0 +1,50 @@
+/**
+ * OAuth 2.0 Token Revocation (RFC 7009).
+ *
+ * A POST endpoint where a client asks the authorization server to invalidate a
+ * token. Revocation is **idempotent and forgiving**: an unknown, malformed, or
+ * already-revoked token still yields `200` (RFC 7009 §2.2), so a client can
+ * retry safely and cannot probe token existence by status code. The lib owns the
+ * protocol; the actual invalidation is delegated to
+ * {@link RevocationConfig.revokeToken}, backed by the consuming package's store.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc7009
+ */
+import { OAuthError, oauthErrorResponse } from "./errors";
+import { methodNotAllowed, readForm } from "./http";
+import { OAuthLogEvent } from "./log";
+import { emit, resolveObservability, } from "./observability";
+/**
+ * Create the revocation endpoint handler. The returned handler accepts a `POST`
+ * request and returns `200` with an empty body on success.
+ */
+export function createRevocationHandler(config) {
+    const obs = resolveObservability(config);
+    return async (request) => {
+        if (request.method.toUpperCase() !== "POST") {
+            return methodNotAllowed("POST");
+        }
+        // Clone before consuming the body so the authenticator can read it too.
+        const authRequest = request.clone();
+        const form = await readForm(request);
+        const clientId = form.get("client_id") ?? undefined;
+        if (config.authenticate &&
+            !(await config.authenticate(authRequest, clientId))) {
+            emit(obs, "warn", OAuthLogEvent.RevocationRejected, {
+                reason: "unauthenticated",
+            });
+            return oauthErrorResponse(OAuthError.InvalidClient, "revocation requires client authentication", 401, { "WWW-Authenticate": "Bearer" });
+        }
+        const token = form.get("token") ?? "";
+        // A missing `token` is the one malformed-request case RFC 7009 §2.1 lets us
+        // reject; a present-but-unknown token is still a success.
+        if (!token) {
+            return oauthErrorResponse(OAuthError.InvalidRequest, "`token` is required");
+        }
+        const hint = form.get("token_type_hint") ?? undefined;
+        await config.revokeToken(token, hint);
+        emit(obs, "info", OAuthLogEvent.TokenRevoked);
+        return new Response(null, { status: 200 });
+    };
+}
+//# sourceMappingURL=revocation.js.map

package/dist/revocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revocation.js","sourceRoot":"","sources":["../src/revocation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EACL,IAAI,EACJ,oBAAoB,GAErB,MAAM,iBAAiB,CAAC;AAsBzB;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAwB;IAExB,MAAM,GAAG,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;QACvB,IAAI,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;YAC5C,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QAED,wEAAwE;QACxE,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;QAErC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,SAAS,CAAC;QACpD,IACE,MAAM,CAAC,YAAY;YACnB,CAAC,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,EACnD,CAAC;YACD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,kBAAkB,EAAE;gBAClD,MAAM,EAAE,iBAAiB;aAC1B,CAAC,CAAC;YACH,OAAO,kBAAkB,CACvB,UAAU,CAAC,aAAa,EACxB,2CAA2C,EAC3C,GAAG,EACH,EAAE,kBAAkB,EAAE,QAAQ,EAAE,CACjC,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QACtC,4EAA4E;QAC5E,0DAA0D;QAC1D,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,kBAAkB,CACvB,UAAU,CAAC,cAAc,EACzB,qBAAqB,CACtB,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,SAAS,CAAC;QAEtD,MAAM,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;QAC9C,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IAC7C,CAAC,CAAC;AACJ,CAAC"}