@sdxc/well-known 0.0.0-pre.1

package/dist/oauth-protected-resource.d.ts

@@ -0,0 +1,110 @@
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728): the typed document, its reader
+ * with the §3.3 resource check a caller cannot skip, its writer, `define` and the
+ * metadata URL, so a client learns which authorization server protects an API.
+ *
+ * @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-protected-resource";
+export declare const MEDIA_TYPE = "application/json";
+/** How a resource accepts a bearer token (RFC 6750 §2). */
+export type BearerMethod = "header" | "body" | "query";
+/**
+ * RFC 9728 §2, in the order the RFC lists its members.
+ *
+ * @template Extensions - The members outside this list, validated by a schema on parse.
+ */
+export interface ProtectedResourceMetadata<Extensions extends object = {}> {
+    resource: URL;
+    /** Issuer identifiers of the authorization servers whose tokens the resource accepts. */
+    authorizationServers: URL[];
+    jwksUri: URL | null;
+    scopesSupported: string[];
+    bearerMethodsSupported: BearerMethod[];
+    resourceSigningAlgValuesSupported: string[];
+    resourceName: LocalizedString | null;
+    resourceDocumentation: URL | null;
+    resourcePolicyUri: URL | null;
+    resourceTosUri: URL | null;
+    tlsClientCertificateBoundAccessTokens: boolean;
+    authorizationDetailsTypesSupported: string[];
+    dpopSigningAlgValuesSupported: string[];
+    dpopBoundAccessTokensRequired: boolean;
+    /** A JWT carrying the metadata, kept opaque. */
+    signedMetadata: string | null;
+    extensions: Extensions;
+}
+/** A value with its untagged form and its `#`-tagged variants (§2.1), keyed by language tag. */
+export interface LocalizedString {
+    value: string;
+    translations: Record<string, string>;
+}
+/**
+ * How a fetched metadata document is read.
+ *
+ * @template Extensions - The members the schema produces.
+ */
+export interface ParseOptions<Extensions extends object> {
+    /** The identifier the metadata URL was built from, or the requested URL (§3.3). */
+    resource: URL | string;
+    /**
+     * Accept a `resource` that is a same-origin, segment-aligned prefix of `resource`,
+     * for metadata found through a challenge on a URL below the resource.
+     * @default "exact"
+     */
+    match?: "exact" | "prefix";
+    /** Validates the members outside the standard list; without one they stay unchecked. */
+    extensions?: StandardSchemaV1<unknown, Extensions>;
+}
+/**
+ * Reads protected resource metadata fetched for a resource. The published `resource`
+ * must equal the expected one (or, with `match: "prefix"`, cover it); a mismatch, a
+ * missing `resource`, or a malformed member fails. Members outside §2 land in
+ * `extensions`.
+ *
+ * @param text - The served JSON.
+ * @param options - The expected resource, how to match it, and an extension schema.
+ * @template Extensions - The extension members the schema produces.
+ * @example
+ * let metadata = parse(body, { resource: "https://api.example/v1" });
+ */
+export declare function parse<Extensions extends object = Record<string, unknown>>(text: string, options: ParseOptions<Extensions>): Result<ProtectedResourceMetadata<Extensions>, WellKnownParseError>;
+/**
+ * Writes the document as its registered member names, leaving out `null` members,
+ * empty lists and `false` flags; a localized name writes its tagged variants beside it.
+ *
+ * @param document - The metadata to publish.
+ */
+export declare function stringify(document: ProtectedResourceMetadata<object>): string;
+/**
+ * Builds a document from the members an app sets. Lists default to empty, URLs to
+ * `null`, booleans to `false`; `bearerMethodsSupported` to `["header"]`, the one method
+ * OAuth 2.1 and MCP both allow.
+ *
+ * @param document - The members the resource publishes.
+ * @template Extensions - Members outside §2 the resource also publishes.
+ * @example
+ * define({ resource: new URL("https://api.example/v1"), scopesSupported: ["read"] });
+ */
+export declare function define<Extensions extends object = {}>(document: Pick<ProtectedResourceMetadata<Extensions>, "resource"> & Partial<ProtectedResourceMetadata<Extensions>>): ProtectedResourceMetadata<Extensions>;
+/**
+ * Where a resource's metadata is served, with the suffix inserted before its path
+ * (§3.1).
+ *
+ * @param resource - The resource identifier.
+ * @example
+ * metadataUrl("https://api.example.com/v1");
+ * // https://api.example.com/.well-known/oauth-protected-resource/v1
+ */
+export declare function metadataUrl(resource: URL | string): URL;
+/**
+ * Protected resource metadata as a servable format. Its `parse` reads the structure
+ * alone; a client reading a fetched document calls `parse` with the resource it
+ * expected.
+ */
+export declare const protectedResourceMetadata: WellKnownFormat<ProtectedResourceMetadata<object>>;

package/dist/oauth-protected-resource.js

@@ -0,0 +1,136 @@
+import { sameIdentifier } from "./lib/identifier.js";
+import { defaults, readMetadata, writeMetadata } from "./lib/metadata.js";
+import { wellKnownUrl } from "./well-known-url.js";
+export const NAME = "oauth-protected-resource";
+export const MEDIA_TYPE = "application/json";
+/** Every RFC 9728 member, by camelCase field. */
+const FIELDS = {
+    resource: { wire: "resource", kind: "url", required: true },
+    authorizationServers: { wire: "authorization_servers", kind: "urls" },
+    jwksUri: { wire: "jwks_uri", kind: "url" },
+    scopesSupported: { wire: "scopes_supported", kind: "strings" },
+    bearerMethodsSupported: {
+        wire: "bearer_methods_supported",
+        kind: "strings",
+        values: ["header", "body", "query"],
+    },
+    resourceSigningAlgValuesSupported: {
+        wire: "resource_signing_alg_values_supported",
+        kind: "strings",
+    },
+    resourceName: { wire: "resource_name", kind: "localized" },
+    resourceDocumentation: { wire: "resource_documentation", kind: "url" },
+    resourcePolicyUri: { wire: "resource_policy_uri", kind: "url" },
+    resourceTosUri: { wire: "resource_tos_uri", kind: "url" },
+    tlsClientCertificateBoundAccessTokens: {
+        wire: "tls_client_certificate_bound_access_tokens",
+        kind: "boolean",
+    },
+    authorizationDetailsTypesSupported: {
+        wire: "authorization_details_types_supported",
+        kind: "strings",
+    },
+    dpopSigningAlgValuesSupported: { wire: "dpop_signing_alg_values_supported", kind: "strings" },
+    dpopBoundAccessTokensRequired: { wire: "dpop_bound_access_tokens_required", kind: "boolean" },
+    signedMetadata: { wire: "signed_metadata", kind: "text" },
+};
+/**
+ * Whether a published resource is a same-origin, segment-aligned prefix of the one
+ * requested: `https://api.example/v1` covers `https://api.example/v1/items`, never
+ * `https://api.example/v10`.
+ *
+ * @param published - The document's `resource`.
+ * @param requested - The URL the client asked about.
+ */
+function coversResource(published, requested) {
+    if (published.origin !== requested.origin)
+        return false;
+    if (sameIdentifier(published, requested))
+        return true;
+    let base = published.pathname.endsWith("/") ? published.pathname : `${published.pathname}/`;
+    return requested.pathname.startsWith(base);
+}
+/**
+ * Reads protected resource metadata fetched for a resource. The published `resource`
+ * must equal the expected one (or, with `match: "prefix"`, cover it); a mismatch, a
+ * missing `resource`, or a malformed member fails. Members outside §2 land in
+ * `extensions`.
+ *
+ * @param text - The served JSON.
+ * @param options - The expected resource, how to match it, and an extension schema.
+ * @template Extensions - The extension members the schema produces.
+ * @example
+ * let metadata = parse(body, { resource: "https://api.example/v1" });
+ */
+export function parse(text, options) {
+    let expected = new URL(options.resource);
+    return readMetadata(text, {
+        format: NAME,
+        table: FIELDS,
+        extensions: options.extensions,
+        check(fields, issues) {
+            let published = fields.resource;
+            let matches = options.match === "prefix"
+                ? coversResource(published, expected)
+                : sameIdentifier(published, expected);
+            if (matches)
+                return;
+            issues.push({
+                at: "/resource",
+                message: `The document names resource "${published.href}", not "${expected.href}".`,
+            });
+        },
+    });
+}
+/**
+ * Writes the document as its registered member names, leaving out `null` members,
+ * empty lists and `false` flags; a localized name writes its tagged variants beside it.
+ *
+ * @param document - The metadata to publish.
+ */
+export function stringify(document) {
+    return writeMetadata(document, FIELDS);
+}
+/**
+ * Builds a document from the members an app sets. Lists default to empty, URLs to
+ * `null`, booleans to `false`; `bearerMethodsSupported` to `["header"]`, the one method
+ * OAuth 2.1 and MCP both allow.
+ *
+ * @param document - The members the resource publishes.
+ * @template Extensions - Members outside §2 the resource also publishes.
+ * @example
+ * define({ resource: new URL("https://api.example/v1"), scopesSupported: ["read"] });
+ */
+export function define(document) {
+    return {
+        ...defaults(FIELDS),
+        bearerMethodsSupported: ["header"],
+        extensions: {},
+        ...document,
+    };
+}
+/**
+ * Where a resource's metadata is served, with the suffix inserted before its path
+ * (§3.1).
+ *
+ * @param resource - The resource identifier.
+ * @example
+ * metadataUrl("https://api.example.com/v1");
+ * // https://api.example.com/.well-known/oauth-protected-resource/v1
+ */
+export function metadataUrl(resource) {
+    return wellKnownUrl(resource, NAME, "insert");
+}
+/**
+ * Protected resource metadata as a servable format. Its `parse` reads the structure
+ * alone; a client reading a fetched document calls `parse` with the resource it
+ * expected.
+ */
+export const protectedResourceMetadata = {
+    name: NAME,
+    mediaType: MEDIA_TYPE,
+    placement: "insert",
+    cors: false,
+    stringify,
+    parse: (text) => readMetadata(text, { format: NAME, table: FIELDS }),
+};

package/dist/openid-configuration.d.ts

@@ -0,0 +1,75 @@
+/**
+ * OpenID Connect Discovery 1.0 provider metadata: the RFC 8414 document plus the
+ * members §3 adds, read with the §4.3 issuer check and served at the appended path
+ * §4 fixes, so a provider and its relying parties share one mapping.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { WellKnownFormat } from "./format.js";
+import type { AuthorizationServerMetadata, ParseOptions } from "./oauth-authorization-server.js";
+import type { WellKnownParseError } from "./parse-error.js";
+export type { ParseOptions } from "./oauth-authorization-server.js";
+export declare const NAME = "openid-configuration";
+export declare const MEDIA_TYPE = "application/json";
+/**
+ * OpenID Connect Discovery 1.0 §3, which extends the RFC 8414 members. OIDC Discovery
+ * requires `RS256` among `idTokenSigningAlgValuesSupported`; the reader accepts a
+ * provider publishing without it.
+ *
+ * @template Extensions - The members outside this list, validated by a schema on parse.
+ */
+export interface OpenIdProviderMetadata<Extensions extends object = {}> extends AuthorizationServerMetadata<Extensions> {
+    authorizationEndpoint: URL;
+    jwksUri: URL;
+    userinfoEndpoint: URL | null;
+    endSessionEndpoint: URL | null;
+    checkSessionIframe: URL | null;
+    subjectTypesSupported: string[];
+    idTokenSigningAlgValuesSupported: string[];
+    claimsSupported: string[];
+    promptValuesSupported: string[];
+    acrValuesSupported: string[];
+    requestParameterSupported: boolean;
+    /** Absent in the document means `true` (§3). */
+    requestUriParameterSupported: boolean;
+    frontchannelLogoutSupported: boolean;
+    frontchannelLogoutSessionSupported: boolean;
+    backchannelLogoutSupported: boolean;
+    backchannelLogoutSessionSupported: boolean;
+}
+/**
+ * Reads provider metadata. A missing required member (`issuer`,
+ * `authorization_endpoint`, `jwks_uri`, `response_types_supported`,
+ * `subject_types_supported`, `id_token_signing_alg_values_supported`) or a different
+ * issuer fails; members outside §3 land in `extensions`.
+ *
+ * @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(body, { issuer: "https://op.example" });
+ */
+export declare function parse<Extensions extends object = Record<string, unknown>>(text: string, options?: ParseOptions<Extensions>): Result<OpenIdProviderMetadata<Extensions>, WellKnownParseError>;
+/**
+ * Writes the document as its registered member names, leaving out `null` members,
+ * optional empty lists and flags at their §3 default. The REQUIRED lists are written
+ * even when empty, so the output always passes {@link parse}.
+ *
+ * @param document - The metadata to publish.
+ */
+export declare function stringify(document: OpenIdProviderMetadata<object>): string;
+/**
+ * Builds a document from the members an app sets; lists default to empty, URLs to
+ * `null` and flags to their §3 default.
+ *
+ * @param document - The members the provider publishes.
+ * @template Extensions - Members outside §3 the provider also publishes.
+ */
+export declare function define<Extensions extends object = {}>(document: Pick<OpenIdProviderMetadata<Extensions>, "issuer" | "authorizationEndpoint" | "jwksUri" | "responseTypesSupported" | "subjectTypesSupported" | "idTokenSigningAlgValuesSupported"> & Partial<OpenIdProviderMetadata<Extensions>>): OpenIdProviderMetadata<Extensions>;
+/**
+ * Provider metadata as a servable format, appended to the issuer (§4). Its `parse`
+ * checks no issuer; a relying party reading a fetched document calls `parse` with one.
+ */
+export declare const openIdConfiguration: WellKnownFormat<OpenIdProviderMetadata<object>>;

package/dist/openid-configuration.js

@@ -0,0 +1,60 @@
+import { defaults, readMetadata, writeMetadata } from "./lib/metadata.js";
+import { issuerCheck, OPENID_PROVIDER_FIELDS } from "./lib/oauth-fields.js";
+export const NAME = "openid-configuration";
+export const MEDIA_TYPE = "application/json";
+/**
+ * Reads provider metadata. A missing required member (`issuer`,
+ * `authorization_endpoint`, `jwks_uri`, `response_types_supported`,
+ * `subject_types_supported`, `id_token_signing_alg_values_supported`) or a different
+ * issuer fails; members outside §3 land in `extensions`.
+ *
+ * @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(body, { issuer: "https://op.example" });
+ */
+export function parse(text, options = {}) {
+    return readMetadata(text, {
+        format: NAME,
+        table: OPENID_PROVIDER_FIELDS,
+        extensions: options.extensions,
+        check: issuerCheck(options.issuer),
+    });
+}
+/**
+ * Writes the document as its registered member names, leaving out `null` members,
+ * optional empty lists and flags at their §3 default. The REQUIRED lists are written
+ * even when empty, so the output always passes {@link parse}.
+ *
+ * @param document - The metadata to publish.
+ */
+export function stringify(document) {
+    return writeMetadata(document, OPENID_PROVIDER_FIELDS);
+}
+/**
+ * Builds a document from the members an app sets; lists default to empty, URLs to
+ * `null` and flags to their §3 default.
+ *
+ * @param document - The members the provider publishes.
+ * @template Extensions - Members outside §3 the provider also publishes.
+ */
+export function define(document) {
+    return {
+        ...defaults(OPENID_PROVIDER_FIELDS),
+        extensions: {},
+        ...document,
+    };
+}
+/**
+ * Provider metadata as a servable format, appended to the issuer (§4). Its `parse`
+ * checks no issuer; a relying party reading a fetched document calls `parse` with one.
+ */
+export const openIdConfiguration = {
+    name: NAME,
+    mediaType: MEDIA_TYPE,
+    placement: "append",
+    cors: false,
+    stringify,
+    parse: (text) => parse(text),
+};

package/dist/parse-error.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The one failure every well-known reader returns, naming the format and each place
+ * the text broke its specification, so a caller can report all of them at once
+ * instead of fixing a document one error per fetch.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Why a well-known document could not be read (or, for a JWKS, written). Every issue
+ * found is listed, and `message` summarizes the first.
+ */
+export declare class WellKnownParseError extends Error {
+    name: string;
+    /** The registered name of the document that failed, such as `security.txt`. */
+    readonly format: string;
+    readonly issues: WellKnownParseError.Issue[];
+    /**
+     * @param format - The registered name of the document.
+     * @param issues - Every problem found, at least one.
+     */
+    constructor(format: string, issues: WellKnownParseError.Issue[]);
+}
+export declare namespace WellKnownParseError {
+    /** One place a document breaks its specification. */
+    interface Issue {
+        /**
+         * A JSON Pointer for a JSON document (`""` for the whole document), a 1-based line
+         * number for a text one (`0` for the file as a whole).
+         */
+        at: string | number;
+        message: string;
+    }
+}

package/dist/parse-error.js

@@ -0,0 +1,29 @@
+/**
+ * The one failure every well-known reader returns, naming the format and each place
+ * the text broke its specification, so a caller can report all of them at once
+ * instead of fixing a document one error per fetch.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Why a well-known document could not be read (or, for a JWKS, written). Every issue
+ * found is listed, and `message` summarizes the first.
+ */
+export class WellKnownParseError extends Error {
+    name = "WellKnownParseError";
+    /** The registered name of the document that failed, such as `security.txt`. */
+    format;
+    issues;
+    /**
+     * @param format - The registered name of the document.
+     * @param issues - Every problem found, at least one.
+     */
+    constructor(format, issues) {
+        let first = issues[0]?.message ?? "The document is invalid.";
+        let more = issues.length > 1 ? ` (and ${issues.length - 1} more)` : "";
+        super(`${format}: ${first}${more}`);
+        this.format = format;
+        this.issues = issues;
+    }
+}

package/dist/passkey-endpoints.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The W3C Passkey Endpoints document: where a password manager sends a person to
+ * create a passkey or manage existing ones. Every member is optional, so an empty
+ * object is a valid document.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { WellKnownFormat } from "./format.js";
+import type { WellKnownParseError } from "./parse-error.js";
+export declare const NAME = "passkey-endpoints";
+export declare const MEDIA_TYPE = "application/json";
+export interface PasskeyEndpoints {
+    /** The page where a signed-in person creates a passkey. */
+    enroll: URL | null;
+    /** The page where a signed-in person lists and removes their passkeys. */
+    manage: URL | null;
+    /** The page explaining how the site uses the WebAuthn PRF extension. */
+    prfUsageDetails: URL | null;
+}
+/**
+ * Reads the document; absent members are `null`, a member that is not an absolute URL
+ * fails, and unknown members are ignored.
+ *
+ * @param text - The served JSON.
+ */
+export declare function parse(text: string): Result<PasskeyEndpoints, WellKnownParseError>;
+/**
+ * Writes the document, leaving out `null` members.
+ *
+ * @param document - The endpoints to publish.
+ */
+export declare function stringify(document: PasskeyEndpoints): string;
+/** The passkey endpoints as a servable format, always answered with the document itself. */
+export declare const passkeyEndpoints: WellKnownFormat<PasskeyEndpoints>;

package/dist/passkey-endpoints.js

@@ -0,0 +1,40 @@
+import { success } from "@sdxc/result";
+import { readMetadata, writeMetadata } from "./lib/metadata.js";
+export const NAME = "passkey-endpoints";
+export const MEDIA_TYPE = "application/json";
+/** Every member the specification defines, by camelCase field. */
+const FIELDS = {
+    enroll: { wire: "enroll", kind: "url" },
+    manage: { wire: "manage", kind: "url" },
+    prfUsageDetails: { wire: "prf_usage_details", kind: "url" },
+};
+/**
+ * Reads the document; absent members are `null`, a member that is not an absolute URL
+ * fails, and unknown members are ignored.
+ *
+ * @param text - The served JSON.
+ */
+export function parse(text) {
+    let read = readMetadata(text, { format: NAME, table: FIELDS });
+    if (read.status === "failure")
+        return read;
+    let { enroll, manage, prfUsageDetails } = read.data;
+    return success({ enroll, manage, prfUsageDetails });
+}
+/**
+ * Writes the document, leaving out `null` members.
+ *
+ * @param document - The endpoints to publish.
+ */
+export function stringify(document) {
+    return writeMetadata(document, FIELDS);
+}
+/** The passkey endpoints as a servable format, always answered with the document itself. */
+export const passkeyEndpoints = {
+    name: NAME,
+    mediaType: MEDIA_TYPE,
+    placement: "insert",
+    cors: false,
+    stringify,
+    parse,
+};

package/dist/response.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Turns a well-known document into a `Response` with the headers every such answer
+ * shares: its media type, a cache policy, an `ETag`, CORS where the format requires
+ * it, and a 304 for a client whose copy is current.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { PolicyOptions } from "@sdxc/http/cache";
+import type { WellKnownFormat } from "./format.js";
+/** How a document is answered. */
+export interface RespondOptions {
+    /** Enables a 304 when the request's `If-None-Match` still matches, and an empty body for `HEAD`. */
+    request?: Request;
+    /** @default { visibility: "public", maxAge: "1 hour" } */
+    cache?: PolicyOptions;
+    /** Extra headers, applied last so they override the defaults. */
+    headers?: HeadersInit;
+}
+/**
+ * The document as a `Response`: its media type, a `Cache-Control` from `policy()`, an
+ * `ETag` from `etag()` over the serialized body, CORS where the format requires it, and a
+ * 304 through `conditional()` when `request` is given.
+ *
+ * @param format - The document's format.
+ * @param document - The document to serve.
+ * @param options - The request, the cache policy and extra headers.
+ * @template Document - The format's document type.
+ * @example
+ * return respond(openIdConfiguration, WELL_KNOWN, { request: ctx.request });
+ */
+export declare function respond<Document>(format: WellKnownFormat<Document>, document: Document, options?: RespondOptions): Promise<Response>;

package/dist/response.js

@@ -0,0 +1,35 @@
+import { conditional, etag, policy } from "@sdxc/http/cache";
+/** The cache policy a well-known document gets unless the caller states one. */
+const DEFAULT_CACHE = { visibility: "public", maxAge: "1 hour" };
+/**
+ * The document as a `Response`: its media type, a `Cache-Control` from `policy()`, an
+ * `ETag` from `etag()` over the serialized body, CORS where the format requires it, and a
+ * 304 through `conditional()` when `request` is given.
+ *
+ * @param format - The document's format.
+ * @param document - The document to serve.
+ * @param options - The request, the cache policy and extra headers.
+ * @template Document - The format's document type.
+ * @example
+ * return respond(openIdConfiguration, WELL_KNOWN, { request: ctx.request });
+ */
+export async function respond(format, document, options = {}) {
+    let body = format.stringify(document);
+    let headers = new Headers({
+        "Content-Type": format.mediaType,
+        "Cache-Control": policy(options.cache ?? DEFAULT_CACHE).toString(),
+    });
+    let tag = await etag(body);
+    if (tag.status === "success")
+        headers.set("ETag", tag.data);
+    if (format.cors)
+        headers.set("Access-Control-Allow-Origin", "*");
+    for (let [name, value] of new Headers(options.headers))
+        headers.set(name, value);
+    let request = options.request;
+    let isHead = request?.method.toUpperCase() === "HEAD";
+    let response = new Response(isHead ? null : body, { status: 200, headers });
+    if (request === undefined)
+        return response;
+    return await conditional(request, response);
+}

package/dist/security-txt.d.ts

@@ -0,0 +1,64 @@
+/**
+ * security.txt (RFC 9116): a line-based reader enforcing the §2.5 cardinalities and
+ * `https` rules, reading a cleartext-signed file from its signed body, and a writer,
+ * so every app publishes where a researcher reports a vulnerability.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { WellKnownFormat } from "./format.js";
+import { WellKnownParseError } from "./parse-error.js";
+export declare const NAME = "security.txt";
+export declare const MEDIA_TYPE = "text/plain; charset=utf-8";
+/** The fields RFC 9116 §2.5 defines, with unknown ones kept under `extensions`. */
+export interface SecurityTxt {
+    /** `mailto:`, `tel:` or `https:` URIs, in the order a researcher should try them. */
+    contact: [URL, ...URL[]];
+    expires: Date;
+    encryption: URL[];
+    acknowledgments: URL[];
+    /** Language tags, written as one comma-separated field. */
+    preferredLanguages: string[];
+    canonical: URL[];
+    policy: URL[];
+    hiring: URL[];
+    /** Fields outside RFC 9116 §2.5, keyed by lowercased name, kept in order. */
+    extensions: Record<string, string[]>;
+}
+export interface ParsedSecurityTxt extends SecurityTxt {
+    /** Whether the text arrived inside an OpenPGP cleartext signature (RFC 9116 §2). */
+    signed: boolean;
+}
+export interface StringifyOptions {
+    /** `#` comment lines written before the first field. */
+    comments?: string[];
+}
+/**
+ * Reads a security.txt file. It fails on a missing `Contact`, a missing or repeated
+ * `Expires`, a repeated `Preferred-Languages`, an `http` URI (or a non-`https` one where
+ * §2.5 asks for a web URI), and a line that is neither a field, a comment nor blank.
+ * An expired file parses; `isExpired` answers staleness.
+ *
+ * @param text - The served text, signed or not; the signature is left unverified.
+ */
+export declare function parse(text: string): Result<ParsedSecurityTxt, WellKnownParseError>;
+/**
+ * Writes unsigned security.txt text: comments first, then the §2.5 fields, then the
+ * extensions, one per line with LF endings. `Expires` is written in UTC to the second.
+ *
+ * @param document - The fields to publish.
+ * @param options - Comment lines to write before the fields.
+ * @example
+ * stringify({ ...fields, expires: new Date("2027-01-01T00:00:00Z") }, { comments: ["Report issues here"] });
+ */
+export declare function stringify(document: SecurityTxt, options?: StringifyOptions): string;
+/**
+ * RFC 9116 §2.5.5: a file past its `Expires` is stale and SHOULD be ignored.
+ *
+ * @param document - The file's fields.
+ * @param now - The moment to judge against.
+ */
+export declare function isExpired(document: SecurityTxt, now?: Date): boolean;
+/** security.txt as a servable format. */
+export declare const securityTxt: WellKnownFormat<SecurityTxt>;