@dwk/oauth 0.1.0-beta.0

package/src/metadata.ts

@@ -0,0 +1,133 @@
+/**
+ * OAuth 2.0 Authorization Server Metadata (RFC 8414).
+ *
+ * One source of truth drives two consumers: the **static** metadata document
+ * Anglesite publishes at `/.well-known/oauth-authorization-server` (derived from
+ * config at build time), and any **runtime** behaviour that must agree with what
+ * was advertised. The builder is pure config→JSON; it is protocol-agnostic, so
+ * IndieAuth, a Solid-OIDC OP, or a bare OAuth AS all feed it their own endpoints
+ * and supported-value lists.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc8414
+ */
+
+/** Configuration for {@link buildAuthorizationServerMetadata}. */
+export interface AuthorizationServerMetadataConfig {
+  /** The authorization-server issuer identifier (a URL, no query/fragment). */
+  readonly issuer: string;
+  /** Absolute authorization endpoint URL. */
+  readonly authorizationEndpoint?: string;
+  /** Absolute token endpoint URL. */
+  readonly tokenEndpoint?: string;
+  /** Absolute token-introspection endpoint URL (RFC 7662). */
+  readonly introspectionEndpoint?: string;
+  /** Absolute token-revocation endpoint URL (RFC 7009). */
+  readonly revocationEndpoint?: string;
+  /** Absolute pushed-authorization-request endpoint URL (RFC 9126). */
+  readonly pushedAuthorizationRequestEndpoint?: string;
+  /** Absolute dynamic-client-registration endpoint URL (RFC 7591). */
+  readonly registrationEndpoint?: string;
+  /** Absolute JWK Set document URL. */
+  readonly jwksUri?: string;
+  /** OAuth scopes the server supports. Omitted from the document when empty. */
+  readonly scopesSupported?: readonly string[];
+  /** Supported `response_type` values. Defaults to `["code"]`. */
+  readonly responseTypesSupported?: readonly string[];
+  /** Supported `grant_type` values. Defaults to `["authorization_code"]`. */
+  readonly grantTypesSupported?: readonly string[];
+  /** Supported token-endpoint client authentication methods. Defaults to `["none"]`. */
+  readonly tokenEndpointAuthMethodsSupported?: readonly string[];
+  /** Supported PKCE `code_challenge` methods. Defaults to `["S256"]`. */
+  readonly codeChallengeMethodsSupported?: readonly string[];
+  /** Supported DPoP proof signing algorithms (RFC 9449), if DPoP is offered. */
+  readonly dpopSigningAlgValuesSupported?: readonly string[];
+  /**
+   * Whether the AS *requires* PAR for every authorization request (RFC 9126
+   * §4). Only emitted (as `true`) when a PAR endpoint is configured.
+   */
+  readonly requirePushedAuthorizationRequests?: boolean;
+}
+
+/**
+ * The JSON shape of the authorization-server metadata document. Snake-cased per
+ * RFC 8414; optional members are omitted (not `null`) when not configured.
+ */
+export interface AuthorizationServerMetadata {
+  readonly issuer: string;
+  readonly authorization_endpoint?: string;
+  readonly token_endpoint?: string;
+  readonly introspection_endpoint?: string;
+  readonly revocation_endpoint?: string;
+  readonly pushed_authorization_request_endpoint?: string;
+  readonly require_pushed_authorization_requests?: boolean;
+  readonly registration_endpoint?: string;
+  readonly jwks_uri?: string;
+  readonly scopes_supported?: readonly string[];
+  readonly response_types_supported: readonly string[];
+  readonly grant_types_supported: readonly string[];
+  readonly token_endpoint_auth_methods_supported: readonly string[];
+  readonly code_challenge_methods_supported: readonly string[];
+  readonly dpop_signing_alg_values_supported?: readonly string[];
+}
+
+/**
+ * Build the RFC 8414 metadata document from config. `issuer`,
+ * `response_types_supported`, `grant_types_supported`,
+ * `token_endpoint_auth_methods_supported`, and `code_challenge_methods_supported`
+ * are always present (with defaults); every endpoint URL and the optional value
+ * lists are emitted only when supplied, so the document never advertises an
+ * endpoint the deployer did not mount.
+ */
+export function buildAuthorizationServerMetadata(
+  config: AuthorizationServerMetadataConfig,
+): AuthorizationServerMetadata {
+  const metadata: Record<string, unknown> = {
+    issuer: config.issuer,
+    response_types_supported: config.responseTypesSupported ?? ["code"],
+    grant_types_supported: config.grantTypesSupported ?? ["authorization_code"],
+    token_endpoint_auth_methods_supported:
+      config.tokenEndpointAuthMethodsSupported ?? ["none"],
+    code_challenge_methods_supported: config.codeChallengeMethodsSupported ?? [
+      "S256",
+    ],
+  };
+
+  if (config.authorizationEndpoint !== undefined) {
+    metadata.authorization_endpoint = config.authorizationEndpoint;
+  }
+  if (config.tokenEndpoint !== undefined) {
+    metadata.token_endpoint = config.tokenEndpoint;
+  }
+  if (config.introspectionEndpoint !== undefined) {
+    metadata.introspection_endpoint = config.introspectionEndpoint;
+  }
+  if (config.revocationEndpoint !== undefined) {
+    metadata.revocation_endpoint = config.revocationEndpoint;
+  }
+  if (config.pushedAuthorizationRequestEndpoint !== undefined) {
+    metadata.pushed_authorization_request_endpoint =
+      config.pushedAuthorizationRequestEndpoint;
+    // `require_*` is only meaningful alongside the endpoint that satisfies it.
+    if (config.requirePushedAuthorizationRequests) {
+      metadata.require_pushed_authorization_requests = true;
+    }
+  }
+  if (config.registrationEndpoint !== undefined) {
+    metadata.registration_endpoint = config.registrationEndpoint;
+  }
+  if (config.jwksUri !== undefined) {
+    metadata.jwks_uri = config.jwksUri;
+  }
+  if (config.scopesSupported && config.scopesSupported.length > 0) {
+    metadata.scopes_supported = config.scopesSupported;
+  }
+  if (
+    config.dpopSigningAlgValuesSupported &&
+    config.dpopSigningAlgValuesSupported.length > 0
+  ) {
+    metadata.dpop_signing_alg_values_supported =
+      config.dpopSigningAlgValuesSupported;
+  }
+
+  return metadata as unknown as AuthorizationServerMetadata;
+}

package/src/observability.ts

@@ -0,0 +1,56 @@
+/**
+ * The shared logging/metrics seam used by every endpoint. Logging and metrics
+ * are opt-in (default no-op) and share one event vocabulary (see `./log` and
+ * `@dwk/log`): the same dotted event name flows to both the logger and the
+ * metrics sink so a log line and its counter line up.
+ */
+
+import { noopLogger, noopMetrics, type Logger, type Metrics } from "@dwk/log";
+import type { LogFields } from "@dwk/log";
+
+/** Observability config fragment mixed into each handler's config. */
+export interface ObservabilityConfig {
+  /**
+   * Logger for endpoint events; defaults to a no-op. Wire a real logger (see
+   * `@dwk/log`) to surface introspection refusals, registration rejections, and
+   * the like instead of swallowing them.
+   */
+  readonly logger?: Logger;
+  /**
+   * Metrics sink for the same events; defaults to a no-op. Wire an adapter (e.g.
+   * `analyticsEngineMetrics` from `@dwk/log`) to chart what the logger names.
+   */
+  readonly metrics?: Metrics;
+}
+
+/** A resolved logger/metrics pair, defaults applied. */
+export interface Observability {
+  readonly logger: Logger;
+  readonly metrics: Metrics;
+}
+
+/** Resolve the optional observability config to concrete (no-op) sinks. */
+export function resolveObservability(
+  config: ObservabilityConfig,
+): Observability {
+  return {
+    logger: config.logger ?? noopLogger,
+    metrics: config.metrics ?? noopMetrics,
+  };
+}
+
+/**
+ * Emit a structured event on both the logger and the metrics sink. `warn` for
+ * handled-but-notable rejections, `info` for normal outcomes. Honors the
+ * redaction policy — callers pass only reason codes, sanitized hosts, and
+ * scopes, never tokens, secrets, or `request_uri` references.
+ */
+export function emit(
+  obs: Observability,
+  level: "info" | "warn",
+  event: string,
+  fields?: LogFields,
+): void {
+  obs.logger[level](event, fields);
+  obs.metrics.count(event, fields);
+}

package/src/par.ts

@@ -0,0 +1,205 @@
+/**
+ * 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,
+  type ObservabilityConfig,
+} from "./observability";
+import type { EndpointAuthenticator } from "./introspection";
+import type { PushedRequestRecord } from "./store";
+
+/** 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: string): string {
+  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: string): string | null {
+  if (!uri.startsWith(PUSHED_REQUEST_URI_PREFIX)) return null;
+  const reference = uri.slice(PUSHED_REQUEST_URI_PREFIX.length);
+  return reference.length > 0 ? reference : null;
+}
+
+/** Configuration for {@link createPushedAuthorizationRequestHandler}. */
+export interface PushedAuthorizationRequestConfig extends ObservabilityConfig {
+  /** Persist a freshly pushed request (keyed by its `reference`). */
+  readonly saveRequest: (record: PushedRequestRecord) => Promise<void>;
+  /**
+   * Optionally authenticate the caller (RFC 9126 §2: clients authenticate as at
+   * the token endpoint). Omit for public clients. Return `false` to reject with
+   * `401 invalid_client`.
+   */
+  readonly authenticate?: EndpointAuthenticator;
+  /**
+   * Optional extra validation of the pushed parameters (e.g. requiring PKCE or a
+   * known `response_type`). Return an error description string to reject with
+   * `400 invalid_request`, or `null` to accept.
+   */
+  readonly validate?: (
+    params: Readonly<Record<string, string>>,
+  ) => string | null | Promise<string | null>;
+  /** `request_uri` lifetime in seconds. Defaults to 60 (RFC 9126 favors short). */
+  readonly lifetimeSeconds?: number;
+  /**
+   * Enable RFC 9449 DPoP binding: when `true` and the push carries a `DPoP`
+   * header, the proof is verified and its `jkt` recorded on the request. The
+   * `htu` is bound to {@link endpoint} (falling back to the request URL).
+   */
+  readonly dpopBinding?: boolean;
+  /** Absolute PAR endpoint URL, used as the DPoP `htu`. */
+  readonly endpoint?: string;
+  /** Current time (seconds since the epoch). Defaults to `Date.now()`. */
+  readonly now?: () => number;
+}
+
+/**
+ * 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: PushedAuthorizationRequestConfig,
+): (request: Request) => Promise<Response> {
+  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: Record<string, string> = {};
+    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: string | undefined;
+    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: PushedRequestRecord = {
+      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,
+    );
+  };
+}