@dwk/oauth 0.1.0-beta.0

package/src/registration.ts

@@ -0,0 +1,336 @@
+/**
+ * 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, type OAuthErrorCode } from "./errors";
+import { json, methodNotAllowed, readJson } from "./http";
+import { OAuthLogEvent } from "./log";
+import {
+  emit,
+  resolveObservability,
+  type ObservabilityConfig,
+} from "./observability";
+import type { EndpointAuthenticator } from "./introspection";
+import type { ClientRecord } from "./store";
+
+const DEFAULT_GRANT_TYPES = ["authorization_code", "refresh_token"] as const;
+const DEFAULT_RESPONSE_TYPES = ["code"] as const;
+const DEFAULT_AUTH_METHODS = [
+  "none",
+  "client_secret_basic",
+  "client_secret_post",
+] as const;
+
+/** 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;
+}
+
+/** 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",
+] as const;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  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: string): boolean {
+  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: unknown,
+  config: ClientRegistrationConfig,
+): { readonly metadata: Record<string, unknown> } | MetadataError {
+  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: Record<string, unknown> = {
+    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: ClientRegistrationConfig,
+): (request: Request) => Promise<Response> {
+  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: ClientRecord = {
+      clientId,
+      clientIdIssuedAt: issuedAt,
+      ...(clientSecret ? { clientSecret } : {}),
+      metadata,
+    };
+    await config.saveClient(record);
+
+    emit(obs, "info", OAuthLogEvent.ClientRegistered, {
+      clientHost: hostFromUrl(clientId),
+    });
+    const response: Record<string, unknown> = {
+      client_id: clientId,
+      client_id_issued_at: issuedAt,
+      ...(clientSecret
+        ? { client_secret: clientSecret, client_secret_expires_at: 0 }
+        : {}),
+      ...metadata,
+    };
+    return json(response, 201);
+  };
+}

package/src/revocation.ts

@@ -0,0 +1,92 @@
+/**
+ * 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,
+  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 function createRevocationHandler(
+  config: RevocationConfig,
+): (request: Request) => Promise<Response> {
+  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 });
+  };
+}

package/src/store.ts

@@ -0,0 +1,93 @@
+/**
+ * Plain-data storage seams for the stateful endpoints.
+ *
+ * Per the design constraint, this lib does **not** own a database: token, client,
+ * and pushed-request records are passed in and out through these interfaces, and
+ * the consuming endpoint package backs them with a strongly-consistent store
+ * (D1 with session consistency, or a Durable Object) via `@dwk/store` —
+ * **never KV**, since a stale token/authz record is a security bug. Implementing
+ * these against an in-memory `Map` is all a unit test needs, which is why the
+ * core runs under plain Node.
+ */
+
+/**
+ * The data an introspection lookup returns for a token (RFC 7662 §2.2). All
+ * members are optional except what the caller chooses to expose; the handler
+ * maps these camelCase fields to the snake_case response members and decides
+ * `active` from `revoked`/`expiresAt` unless {@link active} is set explicitly.
+ */
+export interface IntrospectionTokenRecord {
+  /**
+   * Explicit active flag. When omitted, the handler derives liveness from
+   * {@link revoked} and {@link expiresAt}; set `false` to force inactive.
+   */
+  readonly active?: boolean;
+  /** Whether the token has been revoked — forces `active: false`. */
+  readonly revoked?: boolean;
+  /** Space-separated granted scopes (`scope`). */
+  readonly scope?: string;
+  /** The client the token was issued to (`client_id`). */
+  readonly clientId?: string;
+  /** Human-readable resource-owner identifier (`username`). */
+  readonly username?: string;
+  /** Token type, e.g. `"Bearer"` or `"DPoP"` (`token_type`). */
+  readonly tokenType?: string;
+  /** Expiry, seconds since the epoch (`exp`). */
+  readonly expiresAt?: number;
+  /** Issued-at, seconds since the epoch (`iat`). */
+  readonly issuedAt?: number;
+  /** Not-before, seconds since the epoch (`nbf`). */
+  readonly notBefore?: number;
+  /** Subject identifier (`sub`). */
+  readonly subject?: string;
+  /** Intended audience (`aud`). */
+  readonly audience?: string | readonly string[];
+  /** Issuer identifier (`iss`). */
+  readonly issuer?: string;
+  /** Unique token identifier (`jti`). */
+  readonly tokenId?: string;
+  /**
+   * RFC 9449 DPoP confirmation: the proof-key thumbprint bound to the token.
+   * Surfaced as `cnf: { jkt }` so a Resource Server can complete the binding.
+   */
+  readonly jkt?: string;
+}
+
+/** A pushed authorization request awaiting redemption (RFC 9126). */
+export interface PushedRequestRecord {
+  /** The opaque `request_uri` reference (without the URN prefix). */
+  readonly reference: string;
+  /** The client that pushed the request. */
+  readonly clientId: string;
+  /** The pushed authorization parameters (form fields), as key→value. */
+  readonly params: Readonly<Record<string, string>>;
+  /** Expiry, seconds since the epoch. */
+  readonly expiresAt: number;
+  /** DPoP key thumbprint, when the PAR was DPoP-bound (RFC 9449 §10). */
+  readonly jkt?: string;
+}
+
+/** Storage for pushed authorization requests (RFC 9126). */
+export interface PushedAuthorizationStore {
+  /** Persist a freshly pushed request, keyed by its `reference`. */
+  save(record: PushedRequestRecord): Promise<void>;
+  /**
+   * Atomically fetch and invalidate a pushed request by `reference`, returning
+   * it only if it was still present and unexpired at `now`. Returns `null`
+   * otherwise, so a `request_uri` is single-use even under concurrent
+   * authorization requests (enforce this with a conditional delete/`RETURNING`).
+   */
+  consume(reference: string, now: number): Promise<PushedRequestRecord | null>;
+}
+
+/** A registered OAuth client record (RFC 7591). */
+export interface ClientRecord {
+  /** The issued client identifier. */
+  readonly clientId: string;
+  /** Issued-at, seconds since the epoch (`client_id_issued_at`). */
+  readonly clientIdIssuedAt: number;
+  /** Hashed/opaque client secret for confidential clients, if any. */
+  readonly clientSecret?: string;
+  /** The validated, normalized client metadata that was registered. */
+  readonly metadata: Readonly<Record<string, unknown>>;
+}