@sdxc/well-known 0.0.0-pre.1

package/dist/security-txt.js

@@ -0,0 +1,228 @@
+import { failure, success } from "@sdxc/result";
+import { WellKnownParseError } from "./parse-error.js";
+export const NAME = "security.txt";
+export const MEDIA_TYPE = "text/plain; charset=utf-8";
+/** The URI-valued fields, by lowercased field name, and whether a web URI is all they take. */
+const URI_FIELDS = {
+    contact: { key: "contact", httpsOnly: false },
+    encryption: { key: "encryption", httpsOnly: false },
+    acknowledgments: { key: "acknowledgments", httpsOnly: true },
+    canonical: { key: "canonical", httpsOnly: true },
+    policy: { key: "policy", httpsOnly: true },
+    hiring: { key: "hiring", httpsOnly: true },
+};
+/** A field line: a name of visible characters other than `:`, then its value (§3). */
+const FIELD_LINE = /^([!-9;-~]+):[ \t]*(.*?)[ \t]*$/;
+/** An RFC 3339 `date-time`, which §2.5.5 requires of `Expires`. */
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+/** The armor line opening an OpenPGP cleartext signature (RFC 4880 §7). */
+const SIGNED_HEADER = "-----BEGIN PGP SIGNED MESSAGE-----";
+/** The armor line closing the signed body. */
+const SIGNATURE_HEADER = "-----BEGIN PGP SIGNATURE-----";
+/**
+ * The lines to read: every line of an unsigned file, or the dash-unescaped signed body
+ * of a cleartext-signed one, each keeping its number in the original text.
+ *
+ * @param text - The served text.
+ * @param issues - Where a signature with no body end is reported.
+ */
+function bodyLines(text, issues) {
+    let all = text
+        .replace(/^/, "")
+        .split(/\r?\n/)
+        .map((line, index) => ({ number: index + 1, text: line }));
+    let start = all.findIndex((line) => line.text.trim() !== "");
+    if (all[start]?.text.trim() !== SIGNED_HEADER)
+        return { lines: all, signed: false };
+    let headersEnd = all.findIndex((line, index) => index > start && line.text.trim() === "");
+    let end = all.findIndex((line, index) => index > headersEnd && line.text.trim() === SIGNATURE_HEADER);
+    if (headersEnd === -1 || end === -1) {
+        issues.push({
+            at: all[start]?.number ?? 0,
+            message: "The signed message has no signature block.",
+        });
+        return { lines: [], signed: true };
+    }
+    let lines = all.slice(headersEnd + 1, end).map((line) => ({
+        ...line,
+        text: line.text.startsWith("- ") ? line.text.slice(2) : line.text,
+    }));
+    return { lines, signed: true };
+}
+/**
+ * Reads a URI field's value, enforcing §2.5's rule that a web URI uses `https` and, for
+ * the fields that take only a web URI, that it is one.
+ *
+ * @param value - The field value.
+ * @param field - The field name as written.
+ * @param httpsOnly - Whether the field takes nothing but an `https` URI.
+ * @param line - The line number, for the issue.
+ * @param issues - Where problems are collected.
+ */
+function readUri(value, field, httpsOnly, line, issues) {
+    if (!URL.canParse(value)) {
+        issues.push({ at: line, message: `${field} is not a URI.` });
+        return null;
+    }
+    let url = new URL(value);
+    if (url.protocol === "http:" || (httpsOnly && url.protocol !== "https:")) {
+        issues.push({ at: line, message: `${field} must use https.` });
+        return null;
+    }
+    return url;
+}
+/**
+ * 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 function parse(text) {
+    let issues = [];
+    let { lines, signed } = bodyLines(text, issues);
+    let uris = {
+        contact: [],
+        encryption: [],
+        acknowledgments: [],
+        canonical: [],
+        policy: [],
+        hiring: [],
+    };
+    let expires = [];
+    let expiresFields = 0;
+    let languages = [];
+    let extensions = {};
+    for (let line of lines) {
+        let trimmed = line.text.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        let match = FIELD_LINE.exec(line.text);
+        if (!match) {
+            issues.push({ at: line.number, message: "The line is not a field, a comment or blank." });
+            continue;
+        }
+        let field = match[1] ?? "";
+        let value = match[2] ?? "";
+        let key = field.toLowerCase();
+        if (key in URI_FIELDS) {
+            let spec = URI_FIELDS[key];
+            let url = readUri(value, field, spec.httpsOnly, line.number, issues);
+            if (url)
+                uris[spec.key].push(url);
+        }
+        else if (key === "expires") {
+            expiresFields += 1;
+            let date = new Date(value);
+            if (DATE_TIME.test(value) && !Number.isNaN(date.getTime()))
+                expires.push(date);
+            else
+                issues.push({ at: line.number, message: "Expires is not an RFC 3339 date-time." });
+            if (expiresFields > 1)
+                issues.push({ at: line.number, message: "Expires appears more than once." });
+        }
+        else if (key === "preferred-languages") {
+            languages.push(value
+                .split(",")
+                .map((tag) => tag.trim())
+                .filter((tag) => tag !== ""));
+            if (languages.length > 1) {
+                issues.push({ at: line.number, message: "Preferred-Languages appears more than once." });
+            }
+        }
+        else {
+            (extensions[key] ??= []).push(value);
+        }
+    }
+    let [firstContact, ...otherContacts] = uris.contact;
+    let [expiry] = expires;
+    if (firstContact === undefined)
+        issues.push({ at: 0, message: "The file has no Contact field." });
+    if (expiresFields === 0)
+        issues.push({ at: 0, message: "The file has no Expires field." });
+    if (issues.length > 0 || firstContact === undefined || expiry === undefined) {
+        return failure(new WellKnownParseError(NAME, issues));
+    }
+    return success({
+        contact: [firstContact, ...otherContacts],
+        expires: expiry,
+        encryption: uris.encryption,
+        acknowledgments: uris.acknowledgments,
+        preferredLanguages: languages[0] ?? [],
+        canonical: uris.canonical,
+        policy: uris.policy,
+        hiring: uris.hiring,
+        extensions,
+        signed,
+    });
+}
+/**
+ * A field value safe to write on one line, so a value carrying a line break can never
+ * start a field of its own.
+ *
+ * @param value - The value to write.
+ */
+function oneLine(value) {
+    return value.replace(/[\r\n]+/g, " ").trim();
+}
+/**
+ * The canonical form of a field name for writing: each hyphenated word capitalized, as
+ * RFC 9116 writes its own fields.
+ *
+ * @param key - A lowercased field name.
+ */
+function fieldName(key) {
+    return key.replace(/(^|-)([a-z])/g, (_, dash, letter) => `${dash}${letter.toUpperCase()}`);
+}
+/**
+ * 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 function stringify(document, options = {}) {
+    let lines = [];
+    for (let comment of options.comments ?? []) {
+        for (let part of comment.split(/\r?\n/))
+            lines.push(part === "" ? "#" : `# ${part}`);
+    }
+    let write = (field, values) => {
+        for (let value of values)
+            lines.push(`${field}: ${oneLine(String(value))}`);
+    };
+    write("Contact", document.contact);
+    lines.push(`Expires: ${document.expires.toISOString().replace(/\.\d{3}Z$/, "Z")}`);
+    write("Encryption", document.encryption);
+    write("Acknowledgments", document.acknowledgments);
+    if (document.preferredLanguages.length > 0) {
+        write("Preferred-Languages", [document.preferredLanguages.join(", ")]);
+    }
+    write("Canonical", document.canonical);
+    write("Policy", document.policy);
+    write("Hiring", document.hiring);
+    for (let [key, values] of Object.entries(document.extensions))
+        write(fieldName(key), values);
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * 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 function isExpired(document, now = new Date()) {
+    return document.expires.getTime() <= now.getTime();
+}
+/** security.txt as a servable format. */
+export const securityTxt = {
+    name: NAME,
+    mediaType: MEDIA_TYPE,
+    placement: "insert",
+    cors: false,
+    stringify: (document) => stringify(document),
+    parse,
+};

package/dist/webfinger.d.ts

@@ -0,0 +1,75 @@
+/**
+ * WebFinger (RFC 7033): the JRD document, reading the `resource` and `rel` query
+ * parameters, and selecting only the links asked for, so a server answers the way
+ * §4 requires and a client reads what any server returns.
+ *
+ * @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 = "webfinger";
+export declare const MEDIA_TYPE = "application/jrd+json";
+/** The JSON Resource Descriptor (RFC 7033 §4.4). */
+export interface Jrd {
+    subject: string | null;
+    aliases: string[];
+    /** Property URIs to values; RFC 7033 §4.4.3 allows `null`. */
+    properties: Record<string, string | null>;
+    links: JrdLink[];
+}
+/** One link of a JRD (RFC 7033 §4.4.4). */
+export interface JrdLink {
+    rel: string;
+    type: string | null;
+    href: string | null;
+    /** Language tag, or `und`, to title. */
+    titles: Record<string, string>;
+    properties: Record<string, string | null>;
+}
+/** What a WebFinger request asks for. */
+export interface WebFingerQuery {
+    resource: string;
+    /** Every `rel` parameter, in order; empty selects all links. */
+    rels: string[];
+}
+/** A WebFinger request without a `resource`, which §4.2 answers with a 400. */
+export declare class MissingResourceError extends Error {
+    name: string;
+    constructor();
+}
+/**
+ * Reads `resource` and every `rel` from a request URL, per RFC 7033 §4.1. A missing or
+ * empty `resource` fails, so the caller answers 400 as §4.2 requires.
+ *
+ * @param url - The request URL.
+ * @example
+ * let query = readQuery(ctx.url);
+ * if (isFailure(query)) return new Response(query.error.message, { status: 400 });
+ */
+export declare function readQuery(url: URL): Result<WebFingerQuery, MissingResourceError>;
+/**
+ * The document with only the links whose `rel` was asked for, per §4.3; an empty list
+ * keeps every link, and every other member is kept either way.
+ *
+ * @param document - The full document.
+ * @param rels - The requested relation types.
+ */
+export declare function select(document: Jrd, rels: string[]): Jrd;
+/**
+ * Reads a JRD. Absent members read as empty; a member of the wrong type or a link
+ * without `rel` fails, with every issue reported.
+ *
+ * @param text - The served JSON.
+ */
+export declare function parse(text: string): Result<Jrd, WellKnownParseError>;
+/**
+ * Writes a JRD, leaving out a `null` subject, empty lists and empty maps, and a link's
+ * `null` members.
+ *
+ * @param document - The descriptor to publish.
+ */
+export declare function stringify(document: Jrd): string;
+/** WebFinger as a servable format; every answer carries CORS `*`, as §5 requires. */
+export declare const webFinger: WellKnownFormat<Jrd>;

package/dist/webfinger.js

@@ -0,0 +1,205 @@
+import { failure, success } from "@sdxc/result";
+import { isObject, pointer, readJsonObject } from "./lib/json.js";
+import { WellKnownParseError } from "./parse-error.js";
+export const NAME = "webfinger";
+export const MEDIA_TYPE = "application/jrd+json";
+/** A WebFinger request without a `resource`, which §4.2 answers with a 400. */
+export class MissingResourceError extends Error {
+    name = "MissingResourceError";
+    constructor() {
+        super('The WebFinger request has no "resource" parameter.');
+    }
+}
+/**
+ * Reads `resource` and every `rel` from a request URL, per RFC 7033 §4.1. A missing or
+ * empty `resource` fails, so the caller answers 400 as §4.2 requires.
+ *
+ * @param url - The request URL.
+ * @example
+ * let query = readQuery(ctx.url);
+ * if (isFailure(query)) return new Response(query.error.message, { status: 400 });
+ */
+export function readQuery(url) {
+    let resource = url.searchParams.get("resource");
+    if (resource === null || resource === "")
+        return failure(new MissingResourceError());
+    return success({ resource, rels: url.searchParams.getAll("rel") });
+}
+/**
+ * The document with only the links whose `rel` was asked for, per §4.3; an empty list
+ * keeps every link, and every other member is kept either way.
+ *
+ * @param document - The full document.
+ * @param rels - The requested relation types.
+ */
+export function select(document, rels) {
+    if (rels.length === 0)
+        return document;
+    return { ...document, links: document.links.filter((link) => rels.includes(link.rel)) };
+}
+/**
+ * Reads a property map, whose values §4.4.3 allows to be strings or `null`.
+ *
+ * @param value - The decoded member.
+ * @param at - The member's pointer.
+ * @param issues - Where problems are collected.
+ */
+function readProperties(value, at, issues) {
+    if (value === undefined)
+        return {};
+    if (!isObject(value)) {
+        issues.push({ at, message: "Properties are not an object." });
+        return {};
+    }
+    let result = {};
+    for (let [key, entry] of Object.entries(value)) {
+        if (typeof entry === "string" || entry === null)
+            result[key] = entry;
+        else
+            issues.push({
+                at: `${at}${pointer(key)}`,
+                message: "A property value is not a string or null.",
+            });
+    }
+    return result;
+}
+/**
+ * Reads a member that must be a string when present.
+ *
+ * @param body - The object holding it.
+ * @param member - The member name.
+ * @param at - The object's pointer.
+ * @param issues - Where problems are collected.
+ */
+function readOptionalString(body, member, at, issues) {
+    let value = body[member];
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "string")
+        return value;
+    issues.push({ at: `${at}${pointer(member)}`, message: `"${member}" is not a string.` });
+    return null;
+}
+/**
+ * Reads one link, which must name its `rel`.
+ *
+ * @param value - The decoded array element.
+ * @param at - The element's pointer.
+ * @param issues - Where problems are collected.
+ */
+function readLink(value, at, issues) {
+    if (!isObject(value)) {
+        issues.push({ at, message: "A link is not an object." });
+        return null;
+    }
+    if (typeof value.rel !== "string") {
+        issues.push({ at: `${at}/rel`, message: 'A link has no string "rel".' });
+        return null;
+    }
+    let titles = {};
+    if (value.titles !== undefined) {
+        if (isObject(value.titles)) {
+            for (let [tag, title] of Object.entries(value.titles)) {
+                if (typeof title === "string")
+                    titles[tag] = title;
+                else
+                    issues.push({ at: `${at}/titles${pointer(tag)}`, message: "A title is not a string." });
+            }
+        }
+        else
+            issues.push({ at: `${at}/titles`, message: "Titles are not an object." });
+    }
+    return {
+        rel: value.rel,
+        type: readOptionalString(value, "type", at, issues),
+        href: readOptionalString(value, "href", at, issues),
+        titles,
+        properties: readProperties(value.properties, `${at}/properties`, issues),
+    };
+}
+/**
+ * Reads a JRD. Absent members read as empty; a member of the wrong type or a link
+ * without `rel` fails, with every issue reported.
+ *
+ * @param text - The served JSON.
+ */
+export function parse(text) {
+    let decoded = readJsonObject(text, NAME);
+    if (decoded.status === "failure")
+        return decoded;
+    let body = decoded.data;
+    let issues = [];
+    let aliases = [];
+    if (body.aliases !== undefined) {
+        if (Array.isArray(body.aliases)) {
+            for (let [index, alias] of body.aliases.entries()) {
+                if (typeof alias === "string")
+                    aliases.push(alias);
+                else
+                    issues.push({ at: pointer("aliases", index), message: "An alias is not a string." });
+            }
+        }
+        else
+            issues.push({ at: "/aliases", message: '"aliases" is not an array.' });
+    }
+    let links = [];
+    if (body.links !== undefined) {
+        if (Array.isArray(body.links)) {
+            for (let [index, entry] of body.links.entries()) {
+                let link = readLink(entry, pointer("links", index), issues);
+                if (link)
+                    links.push(link);
+            }
+        }
+        else
+            issues.push({ at: "/links", message: '"links" is not an array.' });
+    }
+    let document = {
+        subject: readOptionalString(body, "subject", "", issues),
+        aliases,
+        properties: readProperties(body.properties, "/properties", issues),
+        links,
+    };
+    if (issues.length > 0)
+        return failure(new WellKnownParseError(NAME, issues));
+    return success(document);
+}
+/**
+ * Writes a JRD, leaving out a `null` subject, empty lists and empty maps, and a link's
+ * `null` members.
+ *
+ * @param document - The descriptor to publish.
+ */
+export function stringify(document) {
+    let output = {};
+    if (document.subject !== null)
+        output.subject = document.subject;
+    if (document.aliases.length > 0)
+        output.aliases = document.aliases;
+    if (Object.keys(document.properties).length > 0)
+        output.properties = document.properties;
+    if (document.links.length > 0) {
+        output.links = document.links.map((link) => {
+            let written = { rel: link.rel };
+            if (link.type !== null)
+                written.type = link.type;
+            if (link.href !== null)
+                written.href = link.href;
+            if (Object.keys(link.titles).length > 0)
+                written.titles = link.titles;
+            if (Object.keys(link.properties).length > 0)
+                written.properties = link.properties;
+            return written;
+        });
+    }
+    return JSON.stringify(output);
+}
+/** WebFinger as a servable format; every answer carries CORS `*`, as §5 requires. */
+export const webFinger = {
+    name: NAME,
+    mediaType: MEDIA_TYPE,
+    placement: "insert",
+    cors: true,
+    stringify,
+    parse,
+};

package/dist/well-known-url.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Builds the URL a well-known document lives at for an identifier, applying the
+ * placement rule its specification fixes, so an identifier carrying a path finds its
+ * document where the server actually serves it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { WellKnownPlacement } from "./format.js";
+/**
+ * The URL a well-known document is served at for an identifier. Inserting keeps the
+ * identifier's path and query after the suffix and drops a terminating slash after the
+ * host (RFC 9728 §3.1); appending drops the query, fragment and trailing slashes.
+ *
+ * @param identifier - An absolute URL: an issuer, a resource, or an origin.
+ * @param name - The registered suffix, such as `oauth-authorization-server`.
+ * @param placement - Where the suffix goes; RFC 8414 and RFC 9728 insert, OIDC appends.
+ * @returns The document's URL.
+ * @example
+ * wellKnownUrl("https://as.example/tenant", "oauth-authorization-server");
+ * // https://as.example/.well-known/oauth-authorization-server/tenant
+ * @example
+ * wellKnownUrl("https://op.example/tenant", "openid-configuration", "append");
+ * // https://op.example/tenant/.well-known/openid-configuration
+ */
+export declare function wellKnownUrl(identifier: URL | string, name: string, placement?: WellKnownPlacement): URL;

package/dist/well-known-url.js

@@ -0,0 +1,29 @@
+/** Matches the slashes an identifier ends with before a suffix is appended. */
+const TRAILING_SLASHES = /\/+$/;
+/**
+ * The URL a well-known document is served at for an identifier. Inserting keeps the
+ * identifier's path and query after the suffix and drops a terminating slash after the
+ * host (RFC 9728 §3.1); appending drops the query, fragment and trailing slashes.
+ *
+ * @param identifier - An absolute URL: an issuer, a resource, or an origin.
+ * @param name - The registered suffix, such as `oauth-authorization-server`.
+ * @param placement - Where the suffix goes; RFC 8414 and RFC 9728 insert, OIDC appends.
+ * @returns The document's URL.
+ * @example
+ * wellKnownUrl("https://as.example/tenant", "oauth-authorization-server");
+ * // https://as.example/.well-known/oauth-authorization-server/tenant
+ * @example
+ * wellKnownUrl("https://op.example/tenant", "openid-configuration", "append");
+ * // https://op.example/tenant/.well-known/openid-configuration
+ */
+export function wellKnownUrl(identifier, name, placement = "insert") {
+    let source = new URL(identifier);
+    if (placement === "append") {
+        let path = source.pathname.replace(TRAILING_SLASHES, "");
+        return new URL(`${path}/.well-known/${name}`, source.origin);
+    }
+    let path = source.pathname === "/" ? "" : source.pathname;
+    let url = new URL(`/.well-known/${name}${path}`, source.origin);
+    url.search = source.search;
+    return url;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@sdxc/well-known",
+	"version": "0.0.0-pre.1",
+	"description": "Typed documents for well-known URIs: security.txt, WebFinger, OAuth and OIDC metadata, JWKS and more",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js",
+		"./security-txt": "./dist/security-txt.js",
+		"./webfinger": "./dist/webfinger.js",
+		"./oauth-authorization-server": "./dist/oauth-authorization-server.js",
+		"./openid-configuration": "./dist/openid-configuration.js",
+		"./oauth-protected-resource": "./dist/oauth-protected-resource.js",
+		"./jwks": "./dist/jwks.js",
+		"./change-password": "./dist/change-password.js",
+		"./passkey-endpoints": "./dist/passkey-endpoints.js",
+		"./response": "./dist/response.js",
+		"./middleware": "./dist/middleware.js"
+	},
+	"dependencies": {
+		"@remix-run/data-schema": "^0.3.0",
+		"@sdxc/result": "2026.9.15",
+		"@standard-schema/spec": "^1.1.0"
+	},
+	"peerDependencies": {
+		"@sdxc/http": "2026.9.23",
+		"remix": "3.0.0-rc.2"
+	},
+	"peerDependenciesMeta": {
+		"@sdxc/http": {
+			"optional": true
+		},
+		"remix": {
+			"optional": true
+		}
+	},
+	"gitHead": "f0a77f407e4c30389df65cd8138b150e367da94f",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/well-known"
+	}
+}