@dwk/oauth 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 David W. Keith
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# `@dwk/oauth`
+
+> OAuth 2.0 authorization-server building blocks: RFC 8414 metadata, RFC 7662
+> introspection, RFC 7009 revocation, RFC 9126 PAR, RFC 7591 dynamic client
+> registration. Cross-standard reusable.
+
+Part of the [`@dwk` IndieWeb + Solid cohort](../../README.md). See the
+[package specification](../../spec/packages/oauth.md) for the full requirements.
+
+This package is **cross-standard reusable**: it takes plain-data inputs only, has
+no Workers-runtime dependency (only Web Fetch + Web Crypto), and unit-tests in
+isolation (Node, no `workerd`). It is **protocol-agnostic** — no IndieWeb/Solid
+claim handling is baked in; the caller supplies issuer/audience policy and the
+storage seams. It exists so [`@dwk/indieauth`](../indieauth) and the eventual
+Solid-OIDC OP share one audited implementation of these primitives rather than
+diverging.
+
+## What it provides
+
+| Endpoint / artifact | RFC | Factory |
+| --- | --- | --- |
+| Authorization-server metadata | [8414](https://www.rfc-editor.org/rfc/rfc8414) | `buildAuthorizationServerMetadata` |
+| Token introspection | [7662](https://www.rfc-editor.org/rfc/rfc7662) | `createIntrospectionHandler` |
+| Token revocation | [7009](https://www.rfc-editor.org/rfc/rfc7009) | `createRevocationHandler` |
+| Pushed authorization requests | [9126](https://www.rfc-editor.org/rfc/rfc9126) | `createPushedAuthorizationRequestHandler` |
+| Dynamic client registration | [7591](https://www.rfc-editor.org/rfc/rfc7591) | `createClientRegistrationHandler` |
+| OAuth error registry | [6749 §5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2) | `OAuthError`, `oauthErrorResponse` |
+
+## The static / dynamic split
+
+The **metadata document** (`/.well-known/oauth-authorization-server`) is static
+JSON derived from config known at build time, so **Anglesite serves it** — no
+Worker route is needed merely to publish it. `buildAuthorizationServerMetadata`
+is the single source of truth that drives both that static document and any
+runtime behaviour that must agree with what was advertised.
+
+The **four POST endpoints** are stateful, so they are the handlers this lib
+provides. Each is a path-agnostic `(request) => Promise<Response>` you mount
+wherever you like and back with your own strongly-consistent storage.
+
+## Storage is yours (never KV)
+
+This lib owns no database. Token, client, and pushed-request records flow through
+the plain-data seams in `./store`, which you back with a strongly-consistent
+store (D1 with session consistency, or a Durable Object) via
+[`@dwk/store`](../store). Authoritative token/authz state **MUST NOT** live in
+KV: a stale introspection or revocation result is a security bug.
+
+## Usage
+
+### Metadata (RFC 8414)
+
+```ts
+import { buildAuthorizationServerMetadata } from "@dwk/oauth";
+
+const metadata = buildAuthorizationServerMetadata({
+  issuer: "https://example.com",
+  authorizationEndpoint: "https://example.com/authorize",
+  tokenEndpoint: "https://example.com/token",
+  introspectionEndpoint: "https://example.com/introspect",
+  revocationEndpoint: "https://example.com/revoke",
+  pushedAuthorizationRequestEndpoint: "https://example.com/par",
+  registrationEndpoint: "https://example.com/register",
+  scopesSupported: ["read", "write"],
+  dpopSigningAlgValuesSupported: ["ES256"],
+});
+```
+
+Endpoint URLs and optional value lists are emitted only when supplied, so the
+document never advertises an endpoint you did not mount.
+
+### Introspection (RFC 7662)
+
+```ts
+import { createIntrospectionHandler } from "@dwk/oauth";
+
+const introspect = createIntrospectionHandler({
+  // Required: the endpoint MUST be protected against token scanning.
+  authenticate: (request) => verifyResourceServer(request),
+  // Look the token up in your strongly-consistent store.
+  lookupToken: async (token) => store.findToken(token),
+});
+
+// active → mapped RFC 7662 claims (snake_case), inactive → { active: false }.
+const response = await introspect(request);
+```
+
+A DPoP-bound token surfaces its key thumbprint as `cnf: { jkt }`. The `active`
+flag is derived from the record's `revoked`/`expiresAt`/`notBefore` (or an
+explicit `active` field). `isTokenActive` and `buildIntrospectionResponse` are
+exported as pure helpers.
+
+### Revocation (RFC 7009)
+
+```ts
+import { createRevocationHandler } from "@dwk/oauth";
+
+const revoke = createRevocationHandler({
+  revokeToken: async (token) => store.revoke(token), // MUST be idempotent
+  // authenticate is optional — omit for public clients using `none`.
+});
+```
+
+Revocation always returns `200` (even for an unknown token), so a client can
+retry safely and cannot probe token existence by status code.
+
+### Pushed authorization requests (RFC 9126)
+
+```ts
+import {
+  createPushedAuthorizationRequestHandler,
+  parseRequestUri,
+} from "@dwk/oauth";
+
+const par = createPushedAuthorizationRequestHandler({
+  saveRequest: async (record) => store.savePushedRequest(record),
+  validate: (params) => (params.code_challenge ? null : "PKCE required"),
+  lifetimeSeconds: 60,
+  dpopBinding: true, // verify a DPoP proof at PAR and record its jkt
+  endpoint: "https://example.com/par",
+});
+// → 201 { request_uri, expires_in }
+```
+
+At the **authorization endpoint** (in your package), recover and single-use the
+reference:
+
+```ts
+const reference = parseRequestUri(url.searchParams.get("request_uri")!);
+const pushed = reference ? await store.consumePushedRequest(reference, now) : null;
+```
+
+The `authenticate` hook is `(request, clientId?) => boolean | Promise<boolean>`:
+the handler parses the body, hands the extracted `client_id` to the hook, and
+passes a **pre-parse clone** of the request, so an authenticator can read the
+body itself (e.g. a `client_secret_post` credential) without disturbing the
+handler's own parse. This is what lets a PAR authenticator enforce the RFC 9126
+§2.1 requirement that the authenticated client match the request's `client_id`.
+
+### Dynamic client registration (RFC 7591)
+
+```ts
+import { createClientRegistrationHandler } from "@dwk/oauth";
+
+const register = createClientRegistrationHandler({
+  saveClient: async (record) => store.saveClient(record),
+  // authenticate is optional (gate open registration with an initial token).
+  redirectUriPolicy: (uri) => uri.startsWith("https://"),
+});
+// → 201 client information response with the issued client_id (+ secret).
+```
+
+Validation is strict on the security-relevant fields (`redirect_uris`,
+`token_endpoint_auth_method`, the `authorization_code` ⇔ `code` pairing) and
+ignores unrecognized members rather than echoing arbitrary client-supplied data
+back. `validateClientMetadata` is exported as a pure helper.
+
+## Errors
+
+`OAuthError` is the registered error-code registry; `oauthErrorResponse(code,
+description?, status?, headers?)` builds the RFC 6749 §5.2 JSON body. `code` is
+typed to the registry, so a non-registered code (the kind that breaks
+standards-compliant clients) cannot be emitted by accident.
+
+## Out of scope
+
+- The authorization and token endpoints themselves (those are
+  [`@dwk/indieauth`](../indieauth) / the future OP, which compose this lib).
+- Storage (you supply it; see above).
+- `DPoP-Nonce` issuance and the `use_dpop_nonce` flow.
+- JWK Set hosting and access-token signing/verification.
+
+## License
+
+[ISC](../../LICENSE)

package/dist/encoding.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function bytesToBase64url(bytes: Uint8Array): string;
+/**
+ * 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 declare function randomIdentifier(bytes?: number): string;
+//# sourceMappingURL=encoding.d.ts.map

package/dist/encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../src/encoding.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAO1D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAK,GAAG,MAAM,CAEnD"}

package/dist/encoding.js

@@ -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) {
+    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) {
+    return bytesToBase64url(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+//# sourceMappingURL=encoding.js.map

package/dist/encoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../src/encoding.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wDAAwD;AACxD,MAAM,UAAU,gBAAgB,CAAC,KAAiB;IAChD,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,MAAM,CAAC;SAChB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACxB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAK,GAAG,EAAE;IACzC,OAAO,gBAAgB,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 declare const OAuthError: {
+    /** The request is missing a parameter, malformed, or otherwise invalid. */
+    readonly InvalidRequest: "invalid_request";
+    /** Client authentication failed or the client is unknown. */
+    readonly InvalidClient: "invalid_client";
+    /** The grant (code, refresh token, …) is invalid, expired, or revoked. */
+    readonly InvalidGrant: "invalid_grant";
+    /** The authenticated client is not authorized to use this grant type. */
+    readonly UnauthorizedClient: "unauthorized_client";
+    /** The grant type is not supported by the authorization server. */
+    readonly UnsupportedGrantType: "unsupported_grant_type";
+    /** The requested scope is invalid, unknown, or exceeds what was granted. */
+    readonly InvalidScope: "invalid_scope";
+    /** An unexpected server-side condition prevented fulfilling the request. */
+    readonly ServerError: "server_error";
+    /** The server is temporarily overloaded or under maintenance. */
+    readonly TemporarilyUnavailable: "temporarily_unavailable";
+    /** One or more submitted client metadata fields are invalid. */
+    readonly InvalidClientMetadata: "invalid_client_metadata";
+    /** One or more `redirect_uris` are invalid. */
+    readonly InvalidRedirectUri: "invalid_redirect_uri";
+    /** The server does not support revoking the presented token type. */
+    readonly UnsupportedTokenType: "unsupported_token_type";
+    /** The `request_uri` is unknown, expired, or already consumed. */
+    readonly InvalidRequestUri: "invalid_request_uri";
+    /** The DPoP proof is missing or fails verification. */
+    readonly InvalidDpopProof: "invalid_dpop_proof";
+};
+/** Union of the registered error-code string literals in {@link OAuthError}. */
+export type OAuthErrorCode = (typeof OAuthError)[keyof typeof OAuthError];
+/**
+ * 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 declare function oauthErrorResponse(error: OAuthErrorCode, description?: string, status?: number, headers?: Record<string, string>): Response;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,6DAA6D;AAC7D,eAAO,MAAM,UAAU;IAErB,2EAA2E;;IAE3E,6DAA6D;;IAE7D,0EAA0E;;IAE1E,yEAAyE;;IAEzE,mEAAmE;;IAEnE,4EAA4E;;IAE5E,4EAA4E;;IAE5E,iEAAiE;;IAIjE,gEAAgE;;IAEhE,+CAA+C;;IAI/C,qEAAqE;;IAIrE,kEAAkE;;IAIlE,uDAAuD;;CAE/C,CAAC;AAEX,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAI1E;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,SAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,QAAQ,CAQV"}

package/dist/errors.js

@@ -0,0 +1,66 @@
+/**
+ * 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",
+};
+const JSON_HEADERS = { "content-type": "application/json" };
+/**
+ * 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, description, status = 400, headers) {
+    const body = description
+        ? { error, error_description: description }
+        : { error };
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { ...JSON_HEADERS, ...headers },
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,6DAA6D;AAC7D,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,4DAA4D;IAC5D,2EAA2E;IAC3E,cAAc,EAAE,iBAAiB;IACjC,6DAA6D;IAC7D,aAAa,EAAE,gBAAgB;IAC/B,0EAA0E;IAC1E,YAAY,EAAE,eAAe;IAC7B,yEAAyE;IACzE,kBAAkB,EAAE,qBAAqB;IACzC,mEAAmE;IACnE,oBAAoB,EAAE,wBAAwB;IAC9C,4EAA4E;IAC5E,YAAY,EAAE,eAAe;IAC7B,4EAA4E;IAC5E,WAAW,EAAE,cAAc;IAC3B,iEAAiE;IACjE,sBAAsB,EAAE,yBAAyB;IAEjD,iDAAiD;IACjD,gEAAgE;IAChE,qBAAqB,EAAE,yBAAyB;IAChD,+CAA+C;IAC/C,kBAAkB,EAAE,sBAAsB;IAE1C,gCAAgC;IAChC,qEAAqE;IACrE,oBAAoB,EAAE,wBAAwB;IAE9C,iDAAiD;IACjD,kEAAkE;IAClE,iBAAiB,EAAE,qBAAqB;IAExC,4BAA4B;IAC5B,uDAAuD;IACvD,gBAAgB,EAAE,oBAAoB;CAC9B,CAAC;AAKX,MAAM,YAAY,GAAG,EAAE,cAAc,EAAE,kBAAkB,EAAW,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAqB,EACrB,WAAoB,EACpB,MAAM,GAAG,GAAG,EACZ,OAAgC;IAEhC,MAAM,IAAI,GAAG,WAAW;QACtB,CAAC,CAAC,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE;QAC3C,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;IACd,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE;QACxC,MAAM;QACN,OAAO,EAAE,EAAE,GAAG,YAAY,EAAE,GAAG,OAAO,EAAE;KACzC,CAAC,CAAC;AACL,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+/** Serialize `body` as a JSON response with the given status. */
+export declare function json(body: unknown, status?: number): Response;
+/** A `405 Method Not Allowed` carrying the permitted methods in `Allow`. */
+export declare function methodNotAllowed(allow: string): Response;
+/**
+ * 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 declare function readForm(request: Request): Promise<URLSearchParams>;
+/** Parse a JSON request body, returning `undefined` if it is absent/malformed. */
+export declare function readJson(request: Request): Promise<unknown>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,iEAAiE;AACjE,wBAAgB,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,SAAM,GAAG,QAAQ,CAK1D;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAKxD;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC,CAWzE;AAED,kFAAkF;AAClF,wBAAsB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAMjE"}

package/dist/http.js

@@ -0,0 +1,50 @@
+/**
+ * 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" };
+/** Serialize `body` as a JSON response with the given status. */
+export function json(body, status = 200) {
+    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) {
+    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) {
+    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) {
+    try {
+        return (await request.json());
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,YAAY,GAAG,EAAE,cAAc,EAAE,kBAAkB,EAAW,CAAC;AAErE,iEAAiE;AACjE,MAAM,UAAU,IAAI,CAAC,IAAa,EAAE,MAAM,GAAG,GAAG;IAC9C,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE;QACxC,MAAM;QACN,OAAO,EAAE,YAAY;KACtB,CAAC,CAAC;AACL,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,IAAI,QAAQ,CAAC,oBAAoB,EAAE;QACxC,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,EAAE,KAAK,EAAE;KACnB,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAgB;IAC7C,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;YAChC,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAAE,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,iDAAiD;IACnD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAgB;IAC7C,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAY,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `@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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/E,OAAO,EACL,gCAAgC,EAChC,KAAK,2BAA2B,EAChC,KAAK,iCAAiC,GACvC,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,0BAA0B,EAC1B,aAAa,EACb,0BAA0B,EAC1B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,uBAAuB,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAE9E,OAAO,EACL,uCAAuC,EACvC,eAAe,EACf,aAAa,EACb,yBAAyB,EACzB,KAAK,gCAAgC,GACtC,MAAM,OAAO,CAAC;AAEf,OAAO,EACL,+BAA+B,EAC/B,sBAAsB,EACtB,KAAK,wBAAwB,GAC9B,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,GACb,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,39 @@
+/**
+ * `@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 } from "./errors";
+export { buildAuthorizationServerMetadata, } from "./metadata";
+export { createIntrospectionHandler, isTokenActive, buildIntrospectionResponse, } from "./introspection";
+export { createRevocationHandler } from "./revocation";
+export { createPushedAuthorizationRequestHandler, parseRequestUri, requestUriFor, PUSHED_REQUEST_URI_PREFIX, } from "./par";
+export { createClientRegistrationHandler, validateClientMetadata, } from "./registration";
+export { OAuthLogEvent } from "./log";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAuB,MAAM,UAAU,CAAC;AAE/E,OAAO,EACL,gCAAgC,GAGjC,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,0BAA0B,EAC1B,aAAa,EACb,0BAA0B,GAI3B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,uBAAuB,EAAyB,MAAM,cAAc,CAAC;AAE9E,OAAO,EACL,uCAAuC,EACvC,eAAe,EACf,aAAa,EACb,yBAAyB,GAE1B,MAAM,OAAO,CAAC;AAEf,OAAO,EACL,+BAA+B,EAC/B,sBAAsB,GAEvB,MAAM,gBAAgB,CAAC;AASxB,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC"}

package/dist/introspection.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 { 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;
+    };
+}
+/**
+ * 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 declare function isTokenActive(record: IntrospectionTokenRecord | null, now: number): boolean;
+/**
+ * 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 declare function buildIntrospectionResponse(record: IntrospectionTokenRecord): 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 declare function createIntrospectionHandler(config: IntrospectionConfig): (request: Request) => Promise<Response>;
+//# sourceMappingURL=introspection.d.ts.map

package/dist/introspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../src/introspection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,OAAO,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,MAAM,KACd,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,4DAA4D;AAC5D,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,CACpB,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,MAAM,KACnB,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;IAC7C,wEAAwE;IACxE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,mEAAmE;AACnE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AAKD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,wBAAwB,GAAG,IAAI,EACvC,GAAG,EAAE,MAAM,GACV,OAAO,CAOT;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,wBAAwB,GAC/B,qBAAqB,CAevB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,mBAAmB,GAC1B,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAmDzC"}