@dwk/oauth 0.1.0-beta.0

package/dist/store.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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>>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC/C,iCAAiC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,4DAA4D;AAC5D,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,IAAI,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;CAC9E;AAED,mDAAmD;AACnD,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,oEAAoE;IACpE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtD"}

package/dist/store.js

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@dwk/oauth",
+  "version": "0.1.0-beta.0",
+  "description": "OAuth 2.0 server building blocks: RFC 8414 metadata, RFC 7662 introspection, RFC 7009 revocation, RFC 9126 PAR, RFC 7591 dynamic client registration. Cross-standard reusable; no Workers runtime dependency.",
+  "keywords": [
+    "oauth2",
+    "rfc8414",
+    "rfc7662",
+    "rfc7009",
+    "rfc9126",
+    "rfc7591",
+    "introspection",
+    "revocation",
+    "par",
+    "dynamic-client-registration",
+    "dpop"
+  ],
+  "type": "module",
+  "license": "ISC",
+  "author": "David W. Keith <me@dwk.io>",
+  "homepage": "https://github.com/davidwkeith/workers/tree/main/packages/oauth#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwkeith/workers.git",
+    "directory": "packages/oauth"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dwk/dpop": "0.1.0-beta.0",
+    "@dwk/log": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}

package/src/encoding.ts

@@ -0,0 +1,26 @@
+/**
+ * base64url + random-identifier helpers.
+ *
+ * Kept dependency-free and runtime-agnostic (Web Crypto / `btoa` only) so the
+ * surrounding modules unit-test without a Workers runtime.
+ */
+
+/** Encode bytes as unpadded base64url (RFC 4648 §5). */
+export function bytesToBase64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+/**
+ * A cryptographically-random unpadded-base64url identifier of `bytes` entropy
+ * (default 32 bytes = 256 bits). Used for `request_uri` references, generated
+ * `client_id`s, and client secrets, where unguessability is the security
+ * property.
+ */
+export function randomIdentifier(bytes = 32): string {
+  return bytesToBase64url(crypto.getRandomValues(new Uint8Array(bytes)));
+}

package/src/errors.ts

@@ -0,0 +1,80 @@
+/**
+ * The shared OAuth 2.0 error registry.
+ *
+ * OAuth defines a fixed vocabulary of `error` codes across its specs; emitting a
+ * non-registered code (the finding in [#39]) makes a server fail conformance and
+ * confuses standards-compliant clients, which switch on these exact strings.
+ * Centralizing them here lets `@dwk/indieauth` and the eventual Solid-OIDC OP
+ * share one audited registry rather than re-spelling literals per call site.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6749#section-5.2 (token endpoint)
+ * @see https://www.rfc-editor.org/rfc/rfc7591#section-3.2.2 (registration)
+ * @see https://www.rfc-editor.org/rfc/rfc9449#section-12 (DPoP)
+ */
+
+/** The registered OAuth 2.0 `error` codes this lib emits. */
+export const OAuthError = {
+  // RFC 6749 §5.2 — token endpoint / general protocol errors.
+  /** The request is missing a parameter, malformed, or otherwise invalid. */
+  InvalidRequest: "invalid_request",
+  /** Client authentication failed or the client is unknown. */
+  InvalidClient: "invalid_client",
+  /** The grant (code, refresh token, …) is invalid, expired, or revoked. */
+  InvalidGrant: "invalid_grant",
+  /** The authenticated client is not authorized to use this grant type. */
+  UnauthorizedClient: "unauthorized_client",
+  /** The grant type is not supported by the authorization server. */
+  UnsupportedGrantType: "unsupported_grant_type",
+  /** The requested scope is invalid, unknown, or exceeds what was granted. */
+  InvalidScope: "invalid_scope",
+  /** An unexpected server-side condition prevented fulfilling the request. */
+  ServerError: "server_error",
+  /** The server is temporarily overloaded or under maintenance. */
+  TemporarilyUnavailable: "temporarily_unavailable",
+
+  // RFC 7591 §3.2.2 — dynamic client registration.
+  /** One or more submitted client metadata fields are invalid. */
+  InvalidClientMetadata: "invalid_client_metadata",
+  /** One or more `redirect_uris` are invalid. */
+  InvalidRedirectUri: "invalid_redirect_uri",
+
+  // RFC 7009 §2.2.1 — revocation.
+  /** The server does not support revoking the presented token type. */
+  UnsupportedTokenType: "unsupported_token_type",
+
+  // RFC 9126 §2.3 — pushed authorization requests.
+  /** The `request_uri` is unknown, expired, or already consumed. */
+  InvalidRequestUri: "invalid_request_uri",
+
+  // RFC 9449 §5 / §12 — DPoP.
+  /** The DPoP proof is missing or fails verification. */
+  InvalidDpopProof: "invalid_dpop_proof",
+} as const;
+
+/** Union of the registered error-code string literals in {@link OAuthError}. */
+export type OAuthErrorCode = (typeof OAuthError)[keyof typeof OAuthError];
+
+const JSON_HEADERS = { "content-type": "application/json" } as const;
+
+/**
+ * Build an OAuth 2.0 error response (RFC 6749 §5.2): a JSON body with `error`
+ * and optional `error_description`. `error` is typed to the registry so a
+ * non-registered code cannot be emitted by accident.
+ *
+ * Extra headers (e.g. `WWW-Authenticate` for a `401`) are merged in; callers
+ * MUST keep `error_description` free of secrets and untrusted echoes.
+ */
+export function oauthErrorResponse(
+  error: OAuthErrorCode,
+  description?: string,
+  status = 400,
+  headers?: Record<string, string>,
+): Response {
+  const body = description
+    ? { error, error_description: description }
+    : { error };
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { ...JSON_HEADERS, ...headers },
+  });
+}

package/src/http.ts

@@ -0,0 +1,51 @@
+/**
+ * Small request/response helpers shared by the four endpoint handlers. Web
+ * Fetch types only (`Request`/`Response`/`URLSearchParams`) so the handlers run
+ * and test under plain Node.
+ */
+
+const JSON_HEADERS = { "content-type": "application/json" } as const;
+
+/** Serialize `body` as a JSON response with the given status. */
+export function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: JSON_HEADERS,
+  });
+}
+
+/** A `405 Method Not Allowed` carrying the permitted methods in `Allow`. */
+export function methodNotAllowed(allow: string): Response {
+  return new Response("Method Not Allowed", {
+    status: 405,
+    headers: { allow },
+  });
+}
+
+/**
+ * Read an `application/x-www-form-urlencoded` body into `URLSearchParams`. A
+ * malformed/empty body or wrong content-type yields empty params (never throws),
+ * so the caller's own field validation reports the problem as a `400` rather
+ * than the handler crashing.
+ */
+export async function readForm(request: Request): Promise<URLSearchParams> {
+  const params = new URLSearchParams();
+  try {
+    const form = await request.formData();
+    for (const [key, value] of form) {
+      if (typeof value === "string") params.set(key, value);
+    }
+  } catch {
+    // Intentionally swallowed — see the doc comment.
+  }
+  return params;
+}
+
+/** Parse a JSON request body, returning `undefined` if it is absent/malformed. */
+export async function readJson(request: Request): Promise<unknown> {
+  try {
+    return (await request.json()) as unknown;
+  } catch {
+    return undefined;
+  }
+}

package/src/index.ts

@@ -0,0 +1,75 @@
+/**
+ * `@dwk/oauth` — OAuth 2.0 authorization-server building blocks.
+ *
+ * A cross-standard reusable lib (like `@dwk/dpop`, `@dwk/log`): it provides the
+ * shared OAuth 2.0 *server* primitives that `@dwk/indieauth` already partly
+ * implements and that the eventual Solid-OIDC OP will need, so they share one
+ * audited implementation rather than diverging. It owns the protocol mechanics
+ * of four stateful endpoints plus the metadata document and the error registry;
+ * it stays **protocol-agnostic** (no IndieWeb/Solid claim handling) and
+ * **runtime-agnostic** (plain-data storage seams, Web Fetch + Web Crypto only),
+ * so it unit-tests under plain Node without a Workers runtime.
+ *
+ * What it provides:
+ * - **RFC 8414** authorization-server metadata document (config → JSON), the
+ *   single source of truth shared with the static document Anglesite publishes.
+ * - **RFC 7662** token introspection (protected; derives `active`, maps claims,
+ *   surfaces DPoP `cnf.jkt`).
+ * - **RFC 7009** token revocation (idempotent, always `200`).
+ * - **RFC 9126** pushed authorization requests (single-use `request_uri`,
+ *   optional DPoP binding via `@dwk/dpop`).
+ * - **RFC 7591** dynamic client registration (strict metadata validation).
+ * - A shared, registered **OAuth error registry**.
+ *
+ * Storage is never owned here: token/client/pushed-request records flow through
+ * the plain-data seams in {@link module:store}, which the consuming endpoint
+ * package backs with a strongly-consistent store (D1/DO via `@dwk/store`) —
+ * never KV.
+ *
+ * @see spec/packages/oauth.md
+ * @packageDocumentation
+ */
+
+export { OAuthError, oauthErrorResponse, type OAuthErrorCode } from "./errors";
+
+export {
+  buildAuthorizationServerMetadata,
+  type AuthorizationServerMetadata,
+  type AuthorizationServerMetadataConfig,
+} from "./metadata";
+
+export {
+  createIntrospectionHandler,
+  isTokenActive,
+  buildIntrospectionResponse,
+  type IntrospectionConfig,
+  type IntrospectionResponse,
+  type EndpointAuthenticator,
+} from "./introspection";
+
+export { createRevocationHandler, type RevocationConfig } from "./revocation";
+
+export {
+  createPushedAuthorizationRequestHandler,
+  parseRequestUri,
+  requestUriFor,
+  PUSHED_REQUEST_URI_PREFIX,
+  type PushedAuthorizationRequestConfig,
+} from "./par";
+
+export {
+  createClientRegistrationHandler,
+  validateClientMetadata,
+  type ClientRegistrationConfig,
+} from "./registration";
+
+export type {
+  IntrospectionTokenRecord,
+  PushedRequestRecord,
+  PushedAuthorizationStore,
+  ClientRecord,
+} from "./store";
+
+export { OAuthLogEvent } from "./log";
+export type { ObservabilityConfig } from "./observability";
+export type { Logger, Metrics } from "@dwk/log";

package/src/introspection.ts

@@ -0,0 +1,185 @@
+/**
+ * OAuth 2.0 Token Introspection (RFC 7662).
+ *
+ * A protected POST endpoint a Resource Server queries to learn whether a token
+ * is currently active and, if so, its metadata. The endpoint **MUST** be
+ * protected (RFC 7662 §2.1) so it cannot be used as a token-scanning oracle —
+ * hence {@link IntrospectionConfig.authenticate} is required, not optional.
+ *
+ * The lib owns only the protocol mechanics: it asks the caller to look the token
+ * up (storage stays in the consuming package, see `./store`), derives the
+ * `active` flag, and maps the record to the snake_case response. A DPoP-bound
+ * token surfaces its key thumbprint as `cnf: { jkt }` so the RS can complete the
+ * proof-of-possession binding via `@dwk/dpop`.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc7662
+ */
+
+import { hostFromUrl } from "@dwk/log";
+
+import { OAuthError, oauthErrorResponse } from "./errors";
+import { json, methodNotAllowed, readForm } from "./http";
+import { OAuthLogEvent } from "./log";
+import {
+  emit,
+  resolveObservability,
+  type ObservabilityConfig,
+} from "./observability";
+import type { IntrospectionTokenRecord } from "./store";
+
+/**
+ * Authenticates the calling Resource Server / client at a protected endpoint.
+ *
+ * Receives the request and, when the handler could extract one from the body,
+ * the requested `client_id`. The handler passes a **pre-parse clone** of the
+ * request, so an authenticator that itself reads the body (e.g. a
+ * `client_secret_post` credential, or matching the authenticated client against
+ * `clientId` per RFC 9126 §2.1) does not disturb the handler's own parse.
+ */
+export type EndpointAuthenticator = (
+  request: Request,
+  clientId?: string,
+) => boolean | Promise<boolean>;
+
+/** Configuration for {@link createIntrospectionHandler}. */
+export interface IntrospectionConfig extends ObservabilityConfig {
+  /**
+   * Look up the presented token, returning the record to introspect or `null`
+   * if it is unknown. The optional `tokenTypeHint` is the client's
+   * `token_type_hint` (RFC 7662 §2.1) — a non-binding optimization the store may
+   * ignore. Storage is the consuming package's concern; this stays plain-data.
+   */
+  readonly lookupToken: (
+    token: string,
+    tokenTypeHint?: string,
+  ) => Promise<IntrospectionTokenRecord | null>;
+  /**
+   * Authenticate the caller. **Required** — an unprotected introspection
+   * endpoint is a token-scanning oracle (RFC 7662 §2.1). Return `false` to
+   * reject with `401 invalid_client`.
+   */
+  readonly authenticate: EndpointAuthenticator;
+  /** Current time (seconds since the epoch). Defaults to `Date.now()`. */
+  readonly now?: () => number;
+}
+
+/** The JSON shape of an introspection response (RFC 7662 §2.2). */
+export interface IntrospectionResponse {
+  readonly active: boolean;
+  readonly scope?: string;
+  readonly client_id?: string;
+  readonly username?: string;
+  readonly token_type?: string;
+  readonly exp?: number;
+  readonly iat?: number;
+  readonly nbf?: number;
+  readonly sub?: string;
+  readonly aud?: string | readonly string[];
+  readonly iss?: string;
+  readonly jti?: string;
+  readonly cnf?: { readonly jkt: string };
+}
+
+/** The single inactive response RFC 7662 §2.2 mandates for any non-active token. */
+const INACTIVE: IntrospectionResponse = { active: false };
+
+/**
+ * Whether `record` represents a currently-active token at `now`. A record is
+ * active unless it is `null`, explicitly `active: false`, revoked, past its
+ * `expiresAt`, or before its `notBefore`. Pure and side-effect-free.
+ */
+export function isTokenActive(
+  record: IntrospectionTokenRecord | null,
+  now: number,
+): boolean {
+  if (record === null) return false;
+  if (record.active === false) return false;
+  if (record.revoked === true) return false;
+  if (record.expiresAt !== undefined && now >= record.expiresAt) return false;
+  if (record.notBefore !== undefined && now < record.notBefore) return false;
+  return true;
+}
+
+/**
+ * Map an active token record to its RFC 7662 response, emitting only members the
+ * record actually carries (so the response never advertises empty claims). The
+ * caller MUST have already established the token is active.
+ */
+export function buildIntrospectionResponse(
+  record: IntrospectionTokenRecord,
+): IntrospectionResponse {
+  const response: Record<string, unknown> = { active: true };
+  if (record.scope !== undefined) response.scope = record.scope;
+  if (record.clientId !== undefined) response.client_id = record.clientId;
+  if (record.username !== undefined) response.username = record.username;
+  if (record.tokenType !== undefined) response.token_type = record.tokenType;
+  if (record.expiresAt !== undefined) response.exp = record.expiresAt;
+  if (record.issuedAt !== undefined) response.iat = record.issuedAt;
+  if (record.notBefore !== undefined) response.nbf = record.notBefore;
+  if (record.subject !== undefined) response.sub = record.subject;
+  if (record.audience !== undefined) response.aud = record.audience;
+  if (record.issuer !== undefined) response.iss = record.issuer;
+  if (record.tokenId !== undefined) response.jti = record.tokenId;
+  if (record.jkt !== undefined) response.cnf = { jkt: record.jkt };
+  return response as unknown as IntrospectionResponse;
+}
+
+/**
+ * Create the introspection endpoint handler. The returned handler accepts a
+ * `POST` request and returns the introspection JSON; route it at whatever path
+ * the deployer mounts (it is path-agnostic).
+ */
+export function createIntrospectionHandler(
+  config: IntrospectionConfig,
+): (request: Request) => Promise<Response> {
+  const obs = resolveObservability(config);
+  const clock = config.now ?? (() => Math.floor(Date.now() / 1000));
+
+  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);
+
+    // Protect the endpoint first, so an unauthenticated caller learns nothing
+    // about any token (not even "unknown" vs "known") — the token lookup stays
+    // after this gate. Reading the (small) form body up front is not sensitive.
+    const clientId = form.get("client_id") ?? undefined;
+    if (!(await config.authenticate(authRequest, clientId))) {
+      emit(obs, "warn", OAuthLogEvent.IntrospectionRejected, {
+        reason: "unauthenticated",
+      });
+      return oauthErrorResponse(
+        OAuthError.InvalidClient,
+        "introspection requires client authentication",
+        401,
+        { "WWW-Authenticate": "Bearer" },
+      );
+    }
+
+    const token = form.get("token") ?? "";
+    if (!token) {
+      return oauthErrorResponse(
+        OAuthError.InvalidRequest,
+        "`token` is required",
+      );
+    }
+    const hint = form.get("token_type_hint") ?? undefined;
+
+    const record = await config.lookupToken(token, hint);
+    if (!isTokenActive(record, clock())) {
+      emit(obs, "info", OAuthLogEvent.IntrospectionInactive);
+      return json(INACTIVE);
+    }
+
+    // `record` is non-null here: isTokenActive(null) is false.
+    const active = record as IntrospectionTokenRecord;
+    emit(obs, "info", OAuthLogEvent.IntrospectionActive, {
+      clientHost: active.clientId ? hostFromUrl(active.clientId) : undefined,
+    });
+    return json(buildIntrospectionResponse(active));
+  };
+}

package/src/log.ts

@@ -0,0 +1,43 @@
+/**
+ * `@dwk/oauth` — structured observability event taxonomy.
+ *
+ * These endpoints sit on the security-sensitive edge of an authorization server:
+ * a refused introspection (token scanning), a rejected registration, or a
+ * consumed/forged `request_uri` is exactly the kind of event an operator needs a
+ * signal for. Logging and metrics are opt-in via an injected {@link Logger} and
+ * {@link Metrics} (see `@dwk/log`) and **share this one vocabulary** — the same
+ * dotted event name is passed to the logger and the metrics sink so a log line
+ * and its counter line up.
+ *
+ * Fields follow the redaction policy: a `client_id` URL is reduced to its host
+ * via `hostFromUrl`, and tokens, secrets, codes, and `request_uri` reference
+ * values are **never** logged — only machine-readable reason codes, hosts, and
+ * scopes.
+ *
+ * @packageDocumentation
+ */
+
+/** Stable event names emitted by `@dwk/oauth`. */
+export const OAuthLogEvent = {
+  /** A token was introspected and reported active. */
+  IntrospectionActive: "oauth.introspection.active",
+  /** A token was introspected and reported inactive (unknown/expired/revoked). */
+  IntrospectionInactive: "oauth.introspection.inactive",
+  /** An introspection request was refused (failed endpoint authentication). */
+  IntrospectionRejected: "oauth.introspection.rejected",
+  /** A token was revoked (or the no-op revocation of an unknown token). */
+  TokenRevoked: "oauth.revocation.revoked",
+  /** A revocation request was refused (failed endpoint authentication). */
+  RevocationRejected: "oauth.revocation.rejected",
+  /** A pushed authorization request was stored and a `request_uri` issued. */
+  PushedRequestStored: "oauth.par.stored",
+  /** A pushed authorization request was rejected before storage. Field: `reason`. */
+  PushedRequestRejected: "oauth.par.rejected",
+  /** A dynamic client registration succeeded. Field: `clientHost`. */
+  ClientRegistered: "oauth.registration.registered",
+  /** A dynamic client registration was rejected. Field: `reason`. */
+  ClientRegistrationRejected: "oauth.registration.rejected",
+} as const;
+
+/** Union of the event-name string literals in {@link OAuthLogEvent}. */
+export type OAuthLogEvent = (typeof OAuthLogEvent)[keyof typeof OAuthLogEvent];