@sdxc/well-known 0.0.0-pre.1

package/dist/lib/oauth-fields.d.ts

@@ -0,0 +1,291 @@
+/**
+ * The mapping tables and identity check the OAuth and OpenID Connect metadata
+ * documents share, so OpenID Connect Discovery extends the RFC 8414 members by
+ * spreading one table instead of repeating it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { WellKnownParseError } from "../parse-error.js";
+/** Every RFC 8414 member, by camelCase field. */
+export declare const AUTHORIZATION_SERVER_FIELDS: {
+    issuer: {
+        wire: string;
+        kind: "text";
+        required: true;
+    };
+    authorizationEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    tokenEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    jwksUri: {
+        wire: string;
+        kind: "url";
+    };
+    registrationEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    revocationEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    introspectionEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    deviceAuthorizationEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    pushedAuthorizationRequestEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    scopesSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    responseTypesSupported: {
+        wire: string;
+        kind: "strings";
+        required: true;
+    };
+    responseModesSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    grantTypesSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    tokenEndpointAuthMethodsSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    tokenEndpointAuthSigningAlgValuesSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    revocationEndpointAuthMethodsSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    introspectionEndpointAuthMethodsSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    codeChallengeMethodsSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    uiLocalesSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    serviceDocumentation: {
+        wire: string;
+        kind: "url";
+    };
+    opPolicyUri: {
+        wire: string;
+        kind: "url";
+    };
+    opTosUri: {
+        wire: string;
+        kind: "url";
+    };
+    authorizationResponseIssParameterSupported: {
+        wire: string;
+        kind: "boolean";
+    };
+    protectedResources: {
+        wire: string;
+        kind: "urls";
+    };
+    signedMetadata: {
+        wire: string;
+        kind: "text";
+    };
+};
+/**
+ * Adds the §3.3 check to a read: the published `issuer` must name the issuer the
+ * document was fetched for.
+ *
+ * @param expected - The issuer asked for, if the caller named one.
+ */
+export declare function issuerCheck(expected: URL | string | undefined): (fields: Record<string, unknown>, issues: WellKnownParseError.Issue[]) => void;
+/**
+ * OpenID Connect Discovery §3 members over the RFC 8414 ones. `authorization_endpoint`
+ * and `jwks_uri` become required, and `request_uri_parameter_supported` defaults to
+ * `true`, as §3 states for an absent member.
+ */
+export declare const OPENID_PROVIDER_FIELDS: {
+    authorizationEndpoint: {
+        wire: string;
+        kind: "url";
+        required: true;
+    };
+    jwksUri: {
+        wire: string;
+        kind: "url";
+        required: true;
+    };
+    userinfoEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    endSessionEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    checkSessionIframe: {
+        wire: string;
+        kind: "url";
+    };
+    subjectTypesSupported: {
+        wire: string;
+        kind: "strings";
+        required: true;
+    };
+    idTokenSigningAlgValuesSupported: {
+        wire: string;
+        kind: "strings";
+        required: true;
+    };
+    claimsSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    promptValuesSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    acrValuesSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    requestParameterSupported: {
+        wire: string;
+        kind: "boolean";
+    };
+    requestUriParameterSupported: {
+        wire: string;
+        kind: "boolean";
+        default: true;
+    };
+    frontchannelLogoutSupported: {
+        wire: string;
+        kind: "boolean";
+    };
+    frontchannelLogoutSessionSupported: {
+        wire: string;
+        kind: "boolean";
+    };
+    backchannelLogoutSupported: {
+        wire: string;
+        kind: "boolean";
+    };
+    backchannelLogoutSessionSupported: {
+        wire: string;
+        kind: "boolean";
+    };
+    issuer: {
+        wire: string;
+        kind: "text";
+        required: true;
+    };
+    tokenEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    registrationEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    revocationEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    introspectionEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    deviceAuthorizationEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    pushedAuthorizationRequestEndpoint: {
+        wire: string;
+        kind: "url";
+    };
+    scopesSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    responseTypesSupported: {
+        wire: string;
+        kind: "strings";
+        required: true;
+    };
+    responseModesSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    grantTypesSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    tokenEndpointAuthMethodsSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    tokenEndpointAuthSigningAlgValuesSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    revocationEndpointAuthMethodsSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    introspectionEndpointAuthMethodsSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    codeChallengeMethodsSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    uiLocalesSupported: {
+        wire: string;
+        kind: "strings";
+    };
+    serviceDocumentation: {
+        wire: string;
+        kind: "url";
+    };
+    opPolicyUri: {
+        wire: string;
+        kind: "url";
+    };
+    opTosUri: {
+        wire: string;
+        kind: "url";
+    };
+    authorizationResponseIssParameterSupported: {
+        wire: string;
+        kind: "boolean";
+    };
+    protectedResources: {
+        wire: string;
+        kind: "urls";
+    };
+    signedMetadata: {
+        wire: string;
+        kind: "text";
+    };
+};

package/dist/lib/oauth-fields.js

@@ -0,0 +1,103 @@
+import { sameIdentifier } from "./identifier.js";
+/** Every RFC 8414 member, by camelCase field. */
+export const AUTHORIZATION_SERVER_FIELDS = {
+    issuer: { wire: "issuer", kind: "text", required: true },
+    authorizationEndpoint: { wire: "authorization_endpoint", kind: "url" },
+    tokenEndpoint: { wire: "token_endpoint", kind: "url" },
+    jwksUri: { wire: "jwks_uri", kind: "url" },
+    registrationEndpoint: { wire: "registration_endpoint", kind: "url" },
+    revocationEndpoint: { wire: "revocation_endpoint", kind: "url" },
+    introspectionEndpoint: { wire: "introspection_endpoint", kind: "url" },
+    deviceAuthorizationEndpoint: { wire: "device_authorization_endpoint", kind: "url" },
+    pushedAuthorizationRequestEndpoint: {
+        wire: "pushed_authorization_request_endpoint",
+        kind: "url",
+    },
+    scopesSupported: { wire: "scopes_supported", kind: "strings" },
+    responseTypesSupported: { wire: "response_types_supported", kind: "strings", required: true },
+    responseModesSupported: { wire: "response_modes_supported", kind: "strings" },
+    grantTypesSupported: { wire: "grant_types_supported", kind: "strings" },
+    tokenEndpointAuthMethodsSupported: {
+        wire: "token_endpoint_auth_methods_supported",
+        kind: "strings",
+    },
+    tokenEndpointAuthSigningAlgValuesSupported: {
+        wire: "token_endpoint_auth_signing_alg_values_supported",
+        kind: "strings",
+    },
+    revocationEndpointAuthMethodsSupported: {
+        wire: "revocation_endpoint_auth_methods_supported",
+        kind: "strings",
+    },
+    introspectionEndpointAuthMethodsSupported: {
+        wire: "introspection_endpoint_auth_methods_supported",
+        kind: "strings",
+    },
+    codeChallengeMethodsSupported: { wire: "code_challenge_methods_supported", kind: "strings" },
+    uiLocalesSupported: { wire: "ui_locales_supported", kind: "strings" },
+    serviceDocumentation: { wire: "service_documentation", kind: "url" },
+    opPolicyUri: { wire: "op_policy_uri", kind: "url" },
+    opTosUri: { wire: "op_tos_uri", kind: "url" },
+    authorizationResponseIssParameterSupported: {
+        wire: "authorization_response_iss_parameter_supported",
+        kind: "boolean",
+    },
+    protectedResources: { wire: "protected_resources", kind: "urls" },
+    signedMetadata: { wire: "signed_metadata", kind: "text" },
+};
+/**
+ * Adds the §3.3 check to a read: the published `issuer` must name the issuer the
+ * document was fetched for.
+ *
+ * @param expected - The issuer asked for, if the caller named one.
+ */
+export function issuerCheck(expected) {
+    return (fields, issues) => {
+        if (expected === undefined)
+            return;
+        if (sameIdentifier(String(fields.issuer), expected))
+            return;
+        issues.push({
+            at: "/issuer",
+            message: `The document names issuer "${String(fields.issuer)}", not "${String(expected)}".`,
+        });
+    };
+}
+/**
+ * OpenID Connect Discovery §3 members over the RFC 8414 ones. `authorization_endpoint`
+ * and `jwks_uri` become required, and `request_uri_parameter_supported` defaults to
+ * `true`, as §3 states for an absent member.
+ */
+export const OPENID_PROVIDER_FIELDS = {
+    ...AUTHORIZATION_SERVER_FIELDS,
+    authorizationEndpoint: { wire: "authorization_endpoint", kind: "url", required: true },
+    jwksUri: { wire: "jwks_uri", kind: "url", required: true },
+    userinfoEndpoint: { wire: "userinfo_endpoint", kind: "url" },
+    endSessionEndpoint: { wire: "end_session_endpoint", kind: "url" },
+    checkSessionIframe: { wire: "check_session_iframe", kind: "url" },
+    subjectTypesSupported: { wire: "subject_types_supported", kind: "strings", required: true },
+    idTokenSigningAlgValuesSupported: {
+        wire: "id_token_signing_alg_values_supported",
+        kind: "strings",
+        required: true,
+    },
+    claimsSupported: { wire: "claims_supported", kind: "strings" },
+    promptValuesSupported: { wire: "prompt_values_supported", kind: "strings" },
+    acrValuesSupported: { wire: "acr_values_supported", kind: "strings" },
+    requestParameterSupported: { wire: "request_parameter_supported", kind: "boolean" },
+    requestUriParameterSupported: {
+        wire: "request_uri_parameter_supported",
+        kind: "boolean",
+        default: true,
+    },
+    frontchannelLogoutSupported: { wire: "frontchannel_logout_supported", kind: "boolean" },
+    frontchannelLogoutSessionSupported: {
+        wire: "frontchannel_logout_session_supported",
+        kind: "boolean",
+    },
+    backchannelLogoutSupported: { wire: "backchannel_logout_supported", kind: "boolean" },
+    backchannelLogoutSessionSupported: {
+        wire: "backchannel_logout_session_supported",
+        kind: "boolean",
+    },
+};

package/dist/middleware.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A fetch-router middleware that answers the well-known names an app lists and passes
+ * every other path on, so the registry composes with the app's own routes, including
+ * app-specific names under `/.well-known/`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Middleware, RequestContext } from "remix/router";
+import type { WellKnownFormat } from "./format.js";
+import type { RespondOptions } from "./response.js";
+/** What one name answers with; `null` falls through to the next middleware, usually a 404. */
+export type WellKnownEntry = (ctx: RequestContext) => Response | null | Promise<Response | null>;
+/**
+ * Serves a format's document, produced per request so tenant or clock data can vary.
+ * A `null` document falls through to the next middleware.
+ *
+ * @param format - The document's format.
+ * @param produce - Builds the document for the request.
+ * @param options - The cache policy and extra headers.
+ * @template Document - The format's document type.
+ * @example
+ * serve(securityTxt, () => SECURITY_TXT);
+ */
+export declare function serve<Document>(format: WellKnownFormat<Document>, produce: (ctx: RequestContext) => Document | null | Promise<Document | null>, options?: Omit<RespondOptions, "request">): WellKnownEntry;
+/**
+ * Answers `GET` and `HEAD` on `/.well-known/<name>` (and `/.well-known/<name>/<path>` for an
+ * inserted name) for the names given, `OPTIONS` for a CORS format, and a 405 with `Allow`
+ * for any other method. Every other path goes to `next()`.
+ *
+ * @param entries - Each name the app serves, mapped to what answers it.
+ * @example
+ * wellKnown({ "security.txt": serve(securityTxt, () => SECURITY_TXT) });
+ */
+export declare function wellKnown(entries: Record<string, WellKnownEntry>): Middleware;

package/dist/middleware.js

@@ -0,0 +1,88 @@
+import { respond } from "./response.js";
+/** The path prefix RFC 8615 reserves. */
+const PREFIX = "/.well-known/";
+/** The methods every name answers. */
+const READ_METHODS = ["GET", "HEAD"];
+/**
+ * What the middleware knows about an entry `serve` built: whether its format inserts
+ * the suffix (so a path may follow the name) and whether it answers CORS preflights.
+ */
+const ENTRY_FORMATS = new WeakMap();
+/**
+ * Serves a format's document, produced per request so tenant or clock data can vary.
+ * A `null` document falls through to the next middleware.
+ *
+ * @param format - The document's format.
+ * @param produce - Builds the document for the request.
+ * @param options - The cache policy and extra headers.
+ * @template Document - The format's document type.
+ * @example
+ * serve(securityTxt, () => SECURITY_TXT);
+ */
+export function serve(format, produce, options = {}) {
+    let entry = async (ctx) => {
+        let document = await produce(ctx);
+        if (document === null)
+            return null;
+        return await respond(format, document, { ...options, request: ctx.request });
+    };
+    ENTRY_FORMATS.set(entry, { placement: format.placement, cors: format.cors });
+    return entry;
+}
+/**
+ * The entry a path names: the exact name, or, for a format that inserts its suffix
+ * before an identifier's path, the name followed by that path.
+ *
+ * @param entries - The names the app serves.
+ * @param suffix - The path after `/.well-known/`.
+ */
+function findEntry(entries, suffix) {
+    for (let [name, entry] of Object.entries(entries)) {
+        if (suffix === name)
+            return entry;
+        if (suffix.startsWith(`${name}/`) && ENTRY_FORMATS.get(entry)?.placement === "insert")
+            return entry;
+    }
+    return null;
+}
+/**
+ * Answers `GET` and `HEAD` on `/.well-known/<name>` (and `/.well-known/<name>/<path>` for an
+ * inserted name) for the names given, `OPTIONS` for a CORS format, and a 405 with `Allow`
+ * for any other method. Every other path goes to `next()`.
+ *
+ * @param entries - Each name the app serves, mapped to what answers it.
+ * @example
+ * wellKnown({ "security.txt": serve(securityTxt, () => SECURITY_TXT) });
+ */
+export function wellKnown(entries) {
+    return async (ctx, next) => {
+        let path = ctx.url.pathname;
+        if (!path.startsWith(PREFIX))
+            return next();
+        let entry = findEntry(entries, path.slice(PREFIX.length));
+        if (entry === null)
+            return next();
+        let cors = ENTRY_FORMATS.get(entry)?.cors ?? false;
+        let allow = cors ? [...READ_METHODS, "OPTIONS"] : READ_METHODS;
+        let method = ctx.method.toUpperCase();
+        if (method === "OPTIONS" && cors) {
+            return new Response(null, {
+                status: 204,
+                headers: {
+                    Allow: allow.join(", "),
+                    "Access-Control-Allow-Origin": "*",
+                    "Access-Control-Allow-Methods": allow.join(", "),
+                },
+            });
+        }
+        if (!READ_METHODS.includes(method)) {
+            return new Response(null, { status: 405, headers: { Allow: allow.join(", ") } });
+        }
+        let response = await entry(ctx);
+        if (response === null)
+            return next();
+        if (method === "HEAD" && response.body !== null)
+            return new Response(null, response);
+        return response;
+    };
+}

package/dist/oauth-authorization-server.d.ts

@@ -0,0 +1,99 @@
+/**
+ * OAuth 2.0 Authorization Server Metadata (RFC 8414): the typed document, its reader
+ * with the §3.3 issuer check, its writer and `define`, so a server publishes and a
+ * client reads the same member names from one mapping table.
+ *
+ * @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 { WellKnownParseError } from "./parse-error.js";
+export declare const NAME = "oauth-authorization-server";
+export declare const MEDIA_TYPE = "application/json";
+/**
+ * RFC 8414 §2 plus the registry members an app in this repo publishes. `issuer` is a
+ * string because it is compared as published and carried verbatim in tokens' `iss`.
+ *
+ * @template Extensions - The members outside this list, validated by a schema on parse.
+ */
+export interface AuthorizationServerMetadata<Extensions extends object = {}> {
+    issuer: string;
+    authorizationEndpoint: URL | null;
+    tokenEndpoint: URL | null;
+    jwksUri: URL | null;
+    registrationEndpoint: URL | null;
+    revocationEndpoint: URL | null;
+    introspectionEndpoint: URL | null;
+    /** RFC 8628. */
+    deviceAuthorizationEndpoint: URL | null;
+    /** RFC 9126. */
+    pushedAuthorizationRequestEndpoint: URL | null;
+    scopesSupported: string[];
+    responseTypesSupported: string[];
+    responseModesSupported: string[];
+    grantTypesSupported: string[];
+    tokenEndpointAuthMethodsSupported: string[];
+    tokenEndpointAuthSigningAlgValuesSupported: string[];
+    revocationEndpointAuthMethodsSupported: string[];
+    introspectionEndpointAuthMethodsSupported: string[];
+    codeChallengeMethodsSupported: string[];
+    uiLocalesSupported: string[];
+    serviceDocumentation: URL | null;
+    opPolicyUri: URL | null;
+    opTosUri: URL | null;
+    /** RFC 9207. */
+    authorizationResponseIssParameterSupported: boolean;
+    /** RFC 9728 §4. */
+    protectedResources: URL[];
+    /** A JWT carrying the metadata, kept opaque. */
+    signedMetadata: string | null;
+    extensions: Extensions;
+}
+/**
+ * How a metadata document is read.
+ *
+ * @template Extensions - The members the schema produces.
+ */
+export interface ParseOptions<Extensions extends object> {
+    /** The issuer the document was fetched for; a different `issuer` fails (§3.3). */
+    issuer?: URL | string;
+    /** Validates the members outside the standard list; without one they stay unchecked. */
+    extensions?: StandardSchemaV1<unknown, Extensions>;
+}
+/**
+ * Reads authorization server metadata. Absent lists read as empty and absent URLs as
+ * `null`; members outside RFC 8414 land in `extensions`. A missing `issuer` or
+ * `response_types_supported`, a malformed member, or a different issuer fails.
+ *
+ * @param text - The served JSON.
+ * @param options - The expected issuer and an extension schema.
+ * @template Extensions - The extension members the schema produces.
+ * @example
+ * let metadata = parse(await response.text(), { issuer: "https://as.example" });
+ */
+export declare function parse<Extensions extends object = Record<string, unknown>>(text: string, options?: ParseOptions<Extensions>): Result<AuthorizationServerMetadata<Extensions>, WellKnownParseError>;
+/**
+ * Writes the document as its registered member names, leaving out `null` members,
+ * optional empty lists and `false` flags. `response_types_supported` is REQUIRED, so
+ * it is written even when empty and the output always passes {@link parse}.
+ *
+ * @param document - The metadata to publish.
+ */
+export declare function stringify(document: AuthorizationServerMetadata<object>): string;
+/**
+ * Builds a document from the members an app sets; lists default to empty, URLs to
+ * `null`, flags to `false` and extensions to none.
+ *
+ * @param document - The members the app publishes.
+ * @template Extensions - Members outside RFC 8414 the app also publishes.
+ * @example
+ * define({ issuer: "https://as.example", responseTypesSupported: ["code"] });
+ */
+export declare function define<Extensions extends object = {}>(document: Pick<AuthorizationServerMetadata<Extensions>, "issuer" | "responseTypesSupported"> & Partial<AuthorizationServerMetadata<Extensions>>): AuthorizationServerMetadata<Extensions>;
+/**
+ * RFC 8414 metadata as a servable format. Its `parse` checks no issuer; a client
+ * reading a fetched document calls `parse` with `issuer`.
+ */
+export declare const authorizationServerMetadata: WellKnownFormat<AuthorizationServerMetadata<object>>;

package/dist/oauth-authorization-server.js

@@ -0,0 +1,61 @@
+import { defaults, readMetadata, writeMetadata } from "./lib/metadata.js";
+import { AUTHORIZATION_SERVER_FIELDS, issuerCheck } from "./lib/oauth-fields.js";
+export const NAME = "oauth-authorization-server";
+export const MEDIA_TYPE = "application/json";
+/**
+ * Reads authorization server metadata. Absent lists read as empty and absent URLs as
+ * `null`; members outside RFC 8414 land in `extensions`. A missing `issuer` or
+ * `response_types_supported`, a malformed member, or a different issuer fails.
+ *
+ * @param text - The served JSON.
+ * @param options - The expected issuer and an extension schema.
+ * @template Extensions - The extension members the schema produces.
+ * @example
+ * let metadata = parse(await response.text(), { issuer: "https://as.example" });
+ */
+export function parse(text, options = {}) {
+    return readMetadata(text, {
+        format: NAME,
+        table: AUTHORIZATION_SERVER_FIELDS,
+        extensions: options.extensions,
+        check: issuerCheck(options.issuer),
+    });
+}
+/**
+ * Writes the document as its registered member names, leaving out `null` members,
+ * optional empty lists and `false` flags. `response_types_supported` is REQUIRED, so
+ * it is written even when empty and the output always passes {@link parse}.
+ *
+ * @param document - The metadata to publish.
+ */
+export function stringify(document) {
+    return writeMetadata(document, AUTHORIZATION_SERVER_FIELDS);
+}
+/**
+ * Builds a document from the members an app sets; lists default to empty, URLs to
+ * `null`, flags to `false` and extensions to none.
+ *
+ * @param document - The members the app publishes.
+ * @template Extensions - Members outside RFC 8414 the app also publishes.
+ * @example
+ * define({ issuer: "https://as.example", responseTypesSupported: ["code"] });
+ */
+export function define(document) {
+    return {
+        ...defaults(AUTHORIZATION_SERVER_FIELDS),
+        extensions: {},
+        ...document,
+    };
+}
+/**
+ * RFC 8414 metadata as a servable format. Its `parse` checks no issuer; a client
+ * reading a fetched document calls `parse` with `issuer`.
+ */
+export const authorizationServerMetadata = {
+    name: NAME,
+    mediaType: MEDIA_TYPE,
+    placement: "insert",
+    cors: false,
+    stringify,
+    parse: (text) => parse(text),
+};