@sdxc/well-known 2026.10.23 → 2026.10.25

package/README.md

@@ -120,7 +120,7 @@ The failure every reader returns, with `format` (the registered name) and `issue
 #### `WellKnownFormat<Document>`
 
 The descriptor each document subpath exports: `name`, `mediaType`, `placement`, `cors`,
-`stringify` and `parse`. `respond` and `serve` take one; its `parse` reads structure only, so a
+optional fixed `headers`, `stringify` and `parse`. `respond` and `serve` take one; its `parse` reads structure only, so a
 client checking a fetched document's issuer or resource calls the subpath's own `parse`.
 
 ### Every document subpath
@@ -136,6 +136,11 @@ Each exports `NAME`, `MEDIA_TYPE`, `parse(text)`, `stringify(document)` and a de
 - `stringify(document, options?: StringifyOptions): string` writes unsigned text with LF endings,
   with `options.comments` at the top.
 - `isExpired(document, now?: Date): boolean` answers whether `expires` has passed.
+- `cleartextSigner({ key, passphrase?, onError? })` is a `transform` for `serve`/`respond` that
+  wraps the file in an OpenPGP cleartext signature through
+  [`@sdxc/openpgp`](https://www.npmjs.com/package/@sdxc/openpgp). `key` reads an armored private
+  key per call; with none, or one that fails (reported to `onError`), the file is served unsigned.
+  Each body is signed once, so the `ETag` stays stable.
 - `securityTxt` is the descriptor.
 
 ### `@sdxc/well-known/webfinger` (RFC 7033)
@@ -153,7 +158,11 @@ Each exports `NAME`, `MEDIA_TYPE`, `parse(text)`, `stringify(document)` and a de
   specification land in `extensions` under their serialized names, validated by
   `options.extensions`, any synchronous [Standard Schema](https://standardschema.dev/).
 - `define(document)` takes `issuer` and `responseTypesSupported` and defaults lists to `[]`, URLs
-  to `null` and flags to `false`.
+  to `null` and flags to `false`, except `requestUriParameterSupported`, which is `true` as the
+  registry defines it. The PAR (RFC 9126) and request object (RFC 9101) members are typed fields:
+  `pushedAuthorizationRequestEndpoint`, `requirePushedAuthorizationRequests`,
+  `requestParameterSupported`, `requestUriParameterSupported`,
+  `requestObjectSigningAlgValuesSupported` and `requireSignedRequestObject`.
 - `stringify(document): string` writes extensions beside the standard members, which win a name
   clash.
 - `authorizationServerMetadata` is the descriptor.
@@ -162,7 +171,7 @@ Each exports `NAME`, `MEDIA_TYPE`, `parse(text)`, `stringify(document)` and a de
 
 `OpenIdProviderMetadata` adds the Discovery members to the RFC 8414 document. `define` also
 requires `authorizationEndpoint`, `jwksUri`, `subjectTypesSupported` and
-`idTokenSigningAlgValuesSupported`, and defaults `requestUriParameterSupported` to `true`. `parse`,
+`idTokenSigningAlgValuesSupported`. `parse`,
 `stringify` and `ParseOptions` work as above; `openIdConfiguration` is the descriptor, with
 `placement: "append"`.
 
@@ -184,6 +193,50 @@ requires `authorizationEndpoint`, `jwksUri`, `subjectTypesSupported` and
 - `jwks` is the descriptor. Serving through it publishes each key's public half and leaves
   symmetric keys out, so private keys can go in directly.
 
+### `@sdxc/well-known/client-id-metadata-document` (OAuth Client ID Metadata Document, draft 02)
+
+The RFC 7591 metadata a client serves at the `https` URL it uses as `client_id`: `parse(text, { clientId })`
+applies the draft's `client_id`, credential and redirect URI rules, `define` and `stringify` write
+one, and `respond(clientIdMetadataDocument, document)` serves it.
+
+### `@sdxc/well-known/http-message-signatures-directory` (Web Bot Auth)
+
+The key directory a signing bot publishes, served as `MEDIA_TYPE`
+(`application/http-message-signatures-directory+json`) with CORS.
+
+- `parse(text)` keeps public, asymmetric keys with a registered HTTP signature `alg` (or none) and
+  numeric `nbf`/`exp`, counting the rest in `skipped`.
+- `build(keys)` publishes each key's public half with `use: "sig"`, failing for a symmetric key or
+  one without `kid`; set `kid` to the key's RFC 7638 thumbprint (`JWK.thumbprint` in `@sdxc/jwt`).
+- `httpMessageSignaturesDirectory` is the descriptor. `@sdxc/http-signatures/web-bot-auth` signs
+  the response through `respond`'s `sign` option.
+
+### `@sdxc/well-known/api-catalog` (RFC 9727)
+
+The link set listing the APIs a host publishes, served as `MEDIA_TYPE`
+(`application/linkset+json` with the RFC 9727 `profile`) with CORS, and with
+`Link: </.well-known/api-catalog>; rel="api-catalog"` on every answer, `HEAD` included.
+
+- `build({ url, apis, catalogs? })` writes an `item` link from the catalog to each API, then each
+  API's `serviceDesc`, `serviceDoc`, `serviceMeta` and `status` targets anchored at its endpoint,
+  every path resolved against `url`. `catalogs` nests other catalogs.
+- `parse(text)` reads any RFC 9264 JSON link set with at least one link, as `{ links }` in the
+  shape `@sdxc/link-header/linkset` reads.
+- `apiCatalog` is the descriptor:
+
+```typescript
+wellKnown({
+	"api-catalog": serve(apiCatalog, (ctx) =>
+		build({
+			url: new URL("/.well-known/api-catalog", ctx.url),
+			apis: [
+				{ url: "/v1", serviceDesc: [{ href: "/v1/openapi.json" }], status: [{ href: "/health" }] },
+			],
+		}),
+	),
+});
+```
+
 ### `@sdxc/well-known/change-password` (W3C)
 
 `redirect(target: URL | string): Response` is a 302 to the page where a signed-in person changes
@@ -213,13 +266,16 @@ object is a valid document. `passkeyEndpoints` is the descriptor.
 The document with its media type, a `Cache-Control` (`options.cache`, default public for one hour),
 an `ETag` over the body and CORS for a CORS format. With `options.request` it answers 304 when
 `If-None-Match` still matches and an empty body for `HEAD`. `options.headers` apply last.
+`options.transform(body)` rewrites the serialized body before the `ETag` is computed, such as
+`cleartextSigner`. `options.sign(response, request)` runs over the full 200 response first, for a
+signature over the body.
 
 ### `@sdxc/well-known/middleware`
 
 #### `serve(format, produce: (ctx) => Document | null, options?): WellKnownEntry`
 
 Answers with `produce(ctx)`'s document through `respond`, built per request; `null` falls through
-to the next middleware. `produce` may be async, and `options` takes `cache` and `headers`.
+to the next middleware. `produce` may be async, and `options` takes `cache`, `headers`, `transform` and `sign`.
 
 #### `wellKnown(entries: Record<string, WellKnownEntry>): Middleware`
 
@@ -232,7 +288,7 @@ answers `OPTIONS`; any other method gets a 405 with `Allow`. Every other path go
 `WellKnownPlacement` is `"insert" | "append"`. `WellKnownEntry` is any
 `(ctx) => Response | null`, sync or async. Each document subpath exports its document type
 (`SecurityTxt`, `Jrd`, `AuthorizationServerMetadata<Extensions>`, `OpenIdProviderMetadata<Extensions>`,
-`ProtectedResourceMetadata<Extensions>`, `JwkSet`, `PasskeyEndpoints`, `NodeInfo`,
+`ProtectedResourceMetadata<Extensions>`, `JwkSet`, `ApiCatalog`, `PasskeyEndpoints`, `NodeInfo`,
 `NodeInfoLinks`) and the types of its members (`ParsedSecurityTxt`, `JrdLink`, `WebFingerQuery`,
 `LocalizedString`, `BearerMethod`, `Jwk`, `ParsedJwkSet`, `NodeInfoSoftware`, `NodeInfoUsage` and
 the rest).
@@ -243,7 +299,8 @@ the rest).
 import { isFailure } from "@sdxc/result";
 import { redirect } from "@sdxc/well-known/change-password";
 import { serve, wellKnown } from "@sdxc/well-known/middleware";
-import { isExpired, securityTxt } from "@sdxc/well-known/security-txt";
+import { cleartextSigner, isExpired, securityTxt } from "@sdxc/well-known/security-txt";
+import { env } from "cloudflare:workers";
 import type { SecurityTxt } from "@sdxc/well-known/security-txt";
 import { readQuery, select, webFinger } from "@sdxc/well-known/webfinger";
 import type { Jrd } from "@sdxc/well-known/webfinger";
@@ -266,7 +323,9 @@ declare function findProfile(resource: string): Promise<Jrd | null>;
 let router = createRouter({
 	middleware: [
 		wellKnown({
-			"security.txt": serve(securityTxt, () => SECURITY_TXT),
+			"security.txt": serve(securityTxt, () => SECURITY_TXT, {
+				transform: cleartextSigner({ key: () => env.SECURITY_TXT_SIGNING_KEY }),
+			}),
 			webfinger: async (ctx) => {
 				let query = readQuery(ctx.url);
 				if (isFailure(query)) return new Response(query.error.message, { status: 400 });

package/dist/api-catalog.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The RFC 9727 API catalog served at `/.well-known/api-catalog`: an RFC 9264 link set
+ * naming every API a host publishes, each with its machine-readable description, human
+ * documentation, policies and health endpoint, so a client discovers them from the origin.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { LinksetLink } from "@sdxc/link-header/linkset";
+import type { Result } from "@sdxc/result";
+import type { WellKnownFormat } from "./format.js";
+import { WellKnownParseError } from "./parse-error.js";
+export declare const NAME = "api-catalog";
+/** The profile URI RFC 9727 §7.3 registers, marking a link set as an API catalog. */
+export declare const PROFILE = "https://www.rfc-editor.org/info/rfc9727";
+export declare const MEDIA_TYPE = "application/linkset+json; profile=\"https://www.rfc-editor.org/info/rfc9727\"";
+/** The relation type that points at an API catalog, from a page or from another catalog. */
+export declare const LINK_RELATION = "api-catalog";
+/** A catalog: the links of its link set, read and written through `@sdxc/link-header/linkset`. */
+export interface ApiCatalog {
+    links: LinksetLink[];
+}
+/** One resource an API's metadata link points at. */
+export interface ApiCatalogTarget {
+    /** Resolved against the catalog's URL, so a path names a resource on the catalog's host. */
+    href: URL | string;
+    /** The media type a client gets, such as `application/json` for an OpenAPI document. */
+    type?: string;
+    title?: string;
+}
+/** One API, with the RFC 8631 relations RFC 9727 Appendix A.1 describes it through. */
+export interface ApiDescription {
+    /** The API's endpoint: the catalog's `item` link points here, and its metadata hangs off it. */
+    url: URL | string;
+    /** A name for the API, carried on its `item` link. */
+    title?: string;
+    /** Machine-readable descriptions, such as an OpenAPI document (`service-desc`). */
+    serviceDesc?: ApiCatalogTarget[];
+    /** Documentation for people (`service-doc`). */
+    serviceDoc?: ApiCatalogTarget[];
+    /** Other machine-readable metadata, such as usage policies (`service-meta`). */
+    serviceMeta?: ApiCatalogTarget[];
+    /** The API's health or status endpoint (`status`). */
+    status?: ApiCatalogTarget[];
+}
+/** What a catalog lists. */
+export interface ApiCatalogInput {
+    /** The catalog's own URL: the anchor of its `item` links and the base for every relative href. */
+    url: URL | string;
+    apis: ApiDescription[];
+    /** Other catalogs this one nests, for APIs grouped by domain or product (RFC 9727 §4.3). */
+    catalogs?: Array<URL | string>;
+}
+/**
+ * Builds a catalog combining both shapes RFC 9727 Appendix A shows: an `item` link from the
+ * catalog to each API, then each API's own metadata links anchored at its endpoint. Every
+ * reference is made absolute against `url`.
+ *
+ * @param input - The catalog's URL, its APIs and any nested catalogs.
+ * @returns The catalog, ready for `stringify` or `serve`.
+ * @example
+ * build({
+ *   url: new URL("/.well-known/api-catalog", ctx.url),
+ *   apis: [{ url: "/api/v1", serviceDesc: [{ href: "/api/v1/openapi.json", type: "application/json" }], status: [{ href: "/health" }] }],
+ * });
+ */
+export declare function build(input: ApiCatalogInput): ApiCatalog;
+/**
+ * Reads a catalog. The link set must follow RFC 9264's JSON form and hold at least one
+ * link, since RFC 9727 §4.1 requires a catalog to link to its APIs.
+ *
+ * @param text - The served JSON.
+ * @returns The catalog, or every place it breaks either RFC.
+ * @example let catalog = parse(await (await fetch(wellKnownUrl(origin, NAME, "append"))).text());
+ */
+export declare function parse(text: string): Result<ApiCatalog, WellKnownParseError>;
+/**
+ * Writes a catalog as its `application/linkset+json` document.
+ *
+ * @param document - The catalog.
+ */
+export declare function stringify(document: ApiCatalog): string;
+/**
+ * A catalog as a servable format: the link set media type with the RFC 9727 profile, CORS so
+ * a browser-based API explorer can read it, and on every answer, `HEAD` included, the
+ * `Link: <…>; rel="api-catalog"` that RFC 9727 §2 requires.
+ */
+export declare const apiCatalog: WellKnownFormat<ApiCatalog>;

package/dist/api-catalog.js

@@ -0,0 +1,106 @@
+import { serializeLink } from "@sdxc/link-header";
+import { JSON_MEDIA_TYPE, parseJson, stringifyJson } from "@sdxc/link-header/linkset";
+import { failure, isFailure, success } from "@sdxc/result";
+import { WellKnownParseError } from "./parse-error.js";
+export const NAME = "api-catalog";
+/** The profile URI RFC 9727 §7.3 registers, marking a link set as an API catalog. */
+export const PROFILE = "https://www.rfc-editor.org/info/rfc9727";
+export const MEDIA_TYPE = `${JSON_MEDIA_TYPE}; profile="${PROFILE}"`;
+/** The relation type that points at an API catalog, from a page or from another catalog. */
+export const LINK_RELATION = "api-catalog";
+/** The metadata relations an {@link ApiDescription} carries, in the order the catalog lists them. */
+const METADATA_RELATIONS = [
+    ["serviceDesc", "service-desc"],
+    ["serviceDoc", "service-doc"],
+    ["serviceMeta", "service-meta"],
+    ["status", "status"],
+];
+/**
+ * A reference as an absolute URL against the catalog's, since RFC 9264 asks a link set to
+ * carry no relative references; one that cannot be resolved stays as written.
+ *
+ * @param reference - A URL or a path.
+ * @param base - The catalog's URL.
+ */
+function absolute(reference, base) {
+    return URL.parse(String(reference), base)?.href ?? String(reference);
+}
+/**
+ * Builds a catalog combining both shapes RFC 9727 Appendix A shows: an `item` link from the
+ * catalog to each API, then each API's own metadata links anchored at its endpoint. Every
+ * reference is made absolute against `url`.
+ *
+ * @param input - The catalog's URL, its APIs and any nested catalogs.
+ * @returns The catalog, ready for `stringify` or `serve`.
+ * @example
+ * build({
+ *   url: new URL("/.well-known/api-catalog", ctx.url),
+ *   apis: [{ url: "/api/v1", serviceDesc: [{ href: "/api/v1/openapi.json", type: "application/json" }], status: [{ href: "/health" }] }],
+ * });
+ */
+export function build(input) {
+    let anchor = String(input.url);
+    let links = [];
+    for (let api of input.apis) {
+        let link = { anchor, rel: "item", href: absolute(api.url, anchor) };
+        if (api.title !== undefined)
+            link.title = api.title;
+        links.push(link);
+    }
+    for (let catalog of input.catalogs ?? []) {
+        links.push({ anchor, rel: LINK_RELATION, href: absolute(catalog, anchor) });
+    }
+    for (let api of input.apis) {
+        let endpoint = absolute(api.url, anchor);
+        for (let [member, rel] of METADATA_RELATIONS) {
+            for (let target of api[member] ?? []) {
+                let link = { anchor: endpoint, rel, href: absolute(target.href, anchor) };
+                if (target.type !== undefined)
+                    link.type = target.type;
+                if (target.title !== undefined)
+                    link.title = target.title;
+                links.push(link);
+            }
+        }
+    }
+    return { links };
+}
+/**
+ * Reads a catalog. The link set must follow RFC 9264's JSON form and hold at least one
+ * link, since RFC 9727 §4.1 requires a catalog to link to its APIs.
+ *
+ * @param text - The served JSON.
+ * @returns The catalog, or every place it breaks either RFC.
+ * @example let catalog = parse(await (await fetch(wellKnownUrl(origin, NAME, "append"))).text());
+ */
+export function parse(text) {
+    let links = parseJson(text);
+    if (isFailure(links))
+        return failure(new WellKnownParseError(NAME, links.error.issues));
+    if (links.data.length === 0) {
+        return failure(new WellKnownParseError(NAME, [{ at: "/linkset", message: "The catalog links to no API." }]));
+    }
+    return success({ links: links.data });
+}
+/**
+ * Writes a catalog as its `application/linkset+json` document.
+ *
+ * @param document - The catalog.
+ */
+export function stringify(document) {
+    return stringifyJson(document.links);
+}
+/**
+ * A catalog as a servable format: the link set media type with the RFC 9727 profile, CORS so
+ * a browser-based API explorer can read it, and on every answer, `HEAD` included, the
+ * `Link: <…>; rel="api-catalog"` that RFC 9727 §2 requires.
+ */
+export const apiCatalog = {
+    name: NAME,
+    mediaType: MEDIA_TYPE,
+    placement: "append",
+    cors: true,
+    headers: { Link: serializeLink(`/.well-known/${NAME}`, LINK_RELATION) },
+    stringify,
+    parse,
+};

package/dist/client-id-metadata-document.d.ts

@@ -0,0 +1,115 @@
+/**
+ * OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document-02):
+ * the RFC 7591 client metadata a client publishes at the `https` URL it uses as its
+ * `client_id`, with the reader an authorization server checks a fetched copy through.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { WellKnownFormat } from "./format.js";
+import type { JwkSet } from "./jwks.js";
+import type { LocalizedString } from "./oauth-protected-resource.js";
+import type { WellKnownParseError } from "./parse-error.js";
+export declare const NAME = "client-id-metadata-document";
+export declare const MEDIA_TYPE = "application/json";
+/**
+ * The client authentication methods a document may declare (§4.1): `none` and the
+ * methods proven with a key pair, since a published document can establish no shared
+ * secret.
+ */
+export declare const TOKEN_ENDPOINT_AUTH_METHODS: readonly ["none", "private_key_jwt", "tls_client_auth", "self_signed_tls_client_auth"];
+export type TokenEndpointAuthMethod = (typeof TOKEN_ENDPOINT_AUTH_METHODS)[number];
+/**
+ * A client's published metadata. `clientId` and every redirect URI stay strings because
+ * both are matched by simple string comparison (§3, §4.2); `scope` is the space-delimited
+ * member read as a list.
+ *
+ * @template Extensions - The RFC 7591 members outside this list, validated by a schema on parse.
+ */
+export interface ClientIdMetadataDocument<Extensions extends object = {}> {
+    /** The Client Identifier URL, exactly the URL the document is served at. */
+    clientId: string;
+    redirectUris: string[];
+    /** An absent member reads as `none`: with no secret to present, the client is public. */
+    tokenEndpointAuthMethod: TokenEndpointAuthMethod;
+    /** @default ["authorization_code"] */
+    grantTypes: string[];
+    /** @default ["code"] */
+    responseTypes: string[];
+    clientName: LocalizedString | null;
+    clientUri: URL | null;
+    logoUri: URL | null;
+    scope: string[];
+    contacts: string[];
+    tosUri: URL | null;
+    policyUri: URL | null;
+    jwksUri: URL | null;
+    /** Public keys only; serving the document publishes each key's public half. */
+    jwks: JwkSet | null;
+    softwareId: string | null;
+    softwareVersion: string | null;
+    /** A JWT asserting the client's provenance (§4.3), kept opaque. */
+    softwareStatement: string | null;
+    extensions: Extensions;
+}
+/**
+ * How a fetched document is read.
+ *
+ * @template Extensions - The members the schema produces.
+ */
+export interface ParseOptions<Extensions extends object> {
+    /** The URL the document was fetched from; its `client_id` must equal it, byte for byte (§4). */
+    clientId: string;
+    /** Validates the members outside the typed list; without one they stay unchecked. */
+    extensions?: StandardSchemaV1<unknown, Extensions>;
+}
+/**
+ * Whether a string is a valid Client Identifier URL (§3): `https`, a path, and no
+ * userinfo, dot segments or fragment. It reads the raw string, so a dot segment the URL
+ * parser would resolve away still fails; a query is allowed, though discouraged.
+ *
+ * @param value - A `client_id` as presented.
+ * @example
+ * isClientIdentifierUrl("https://app.example.com/client.json"); // true
+ */
+export declare function isClientIdentifierUrl(value: string): boolean;
+/**
+ * Reads a fetched document. It fails on a `client_id` other than `options.clientId`, a
+ * `client_secret*` member, a secret-based or unknown `token_endpoint_auth_method`, a
+ * keyed method without exactly one key source, private key material, or a redirect URI
+ * the client could not register; every RFC 7591 member outside the list lands in `extensions`.
+ *
+ * @param text - The served JSON.
+ * @param options - The fetched URL and an extension schema.
+ * @template Extensions - The extension members the schema produces.
+ * @example
+ * let client = parse(await response.text(), { clientId: url });
+ */
+export declare function parse<Extensions extends object = Record<string, unknown>>(text: string, options: ParseOptions<Extensions>): Result<ClientIdMetadataDocument<Extensions>, WellKnownParseError>;
+/**
+ * Writes the document as its registered member names, leaving out `null` members, empty
+ * optional lists and default grant and response types. `token_endpoint_auth_method` is
+ * always written, since RFC 7591 reads an absent one as `client_secret_basic`, and
+ * `jwks` carries each key's public half only.
+ *
+ * @param document - The metadata to publish.
+ */
+export declare function stringify(document: ClientIdMetadataDocument<object>): string;
+/**
+ * Builds a document from the members a client sets: `none` authentication, the RFC 7591
+ * default grant and response types, empty lists, `null` single values and no extensions.
+ *
+ * @param document - The members the client publishes.
+ * @template Extensions - Members outside the typed list the client also publishes.
+ * @example
+ * define({ clientId: "https://app.example.com/client.json", redirectUris: ["https://app.example.com/callback"] });
+ */
+export declare function define<Extensions extends object = {}>(document: Pick<ClientIdMetadataDocument<Extensions>, "clientId"> & Partial<ClientIdMetadataDocument<Extensions>>): ClientIdMetadataDocument<Extensions>;
+/**
+ * The document as a servable format, for `respond` from `./response` at the route behind
+ * the client's own URL. Its `parse` applies every rule but the URL match, which a
+ * fetching authorization server checks by calling `parse` with `clientId`.
+ */
+export declare const clientIdMetadataDocument: WellKnownFormat<ClientIdMetadataDocument<object>>;