@sdxc/well-known 2026.10.25 → 2026.11.3

package/README.md

@@ -102,6 +102,36 @@ let router = createRouter({
 `wellKnown` answers the names it lists with the media type, a cache policy, an `ETag`, CORS where
 the specification requires it and a 304 for a current copy; every other path reaches your routes.
 
+## Command line
+
+```sh
+bunx @sdxc/well-known --help
+```
+
+With [`@sdxc/kit`](https://www.npmjs.com/package/@sdxc/kit) installed, `sdxc pkg well-known …` runs the same command line, using the version your project installs.
+
+Check a site's security.txt, or a file before you deploy it; it exits 1 when a required field is
+missing, a line is malformed or `Expires` has passed:
+
+```sh
+bunx @sdxc/well-known security-txt check https://example.com
+bunx @sdxc/well-known security-txt check public/.well-known/security.txt --json
+```
+
+Fetch, validate and print a document; OAuth and OpenID Connect metadata must name the URL you
+pass as their issuer, and NodeInfo follows its links to the newest schema:
+
+```sh
+bunx @sdxc/well-known fetch https://auth.example.com openid-configuration
+bunx @sdxc/well-known fetch https://example.com webfinger --resource acct:me@example.com
+bunx @sdxc/well-known fetch https://example.com jwks.json --json
+```
+
+`fetch` reads `webfinger`, `nodeinfo`, `oauth-authorization-server`, `openid-configuration`,
+`oauth-protected-resource`, `jwks.json`, `passkey-endpoints`, `api-catalog` and
+`http-message-signatures-directory`. Exit codes are 0 valid, 1 problems found, 2 usage or an
+unreadable file or origin.
+
 ## API
 
 ### `@sdxc/well-known`

package/dist/cli-contract.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The `sdxc-well-known` command line as a contract: `security-txt check` for a site's or a
+ * file's security.txt, and `fetch` for any JSON document the package reads. Help, usage
+ * errors and each handler's typed `ctx.flags` all come from this one declaration.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** The documents `fetch` reads, by the registered name they are served under. */
+export declare const DOCUMENTS: readonly ["webfinger", "nodeinfo", "oauth-authorization-server", "openid-configuration", "oauth-protected-resource", "jwks.json", "passkey-endpoints", "api-catalog", "http-message-signatures-directory"];
+/** A document name `fetch` accepts. */
+export type DocumentName = (typeof DOCUMENTS)[number];
+/** Every command `sdxc-well-known` takes. */
+export declare const WELL_KNOWN_COMMANDS: import("@sdxc/cli").Group<Omit<{
+    readonly description: "sdxc-well-known — read and check /.well-known/ documents";
+    readonly "security-txt": import("@sdxc/cli").Group<Omit<{
+        readonly description: "security.txt (RFC 9116)";
+        readonly check: import("@sdxc/cli").Command<{
+            readonly target: import("@sdxc/cli").Argument<string>;
+        }, {
+            readonly json: import("@sdxc/cli").Flag<boolean>;
+        }>;
+    }, "description" | "hidden" | "arguments" | "flags" | "tasks">, Record<never, never>, Record<never, never>>;
+    readonly fetch: import("@sdxc/cli").Command<{
+        readonly identifier: import("@sdxc/cli").Argument<string>;
+        readonly document: import("@sdxc/cli").Argument<"api-catalog" | "webfinger" | "nodeinfo" | "oauth-authorization-server" | "openid-configuration" | "oauth-protected-resource" | "jwks.json" | "passkey-endpoints" | "http-message-signatures-directory">;
+    }, {
+        readonly resource: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        readonly rel: import("@sdxc/cli").ValueFlag<string, false, true, false>;
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+}, "description" | "hidden" | "arguments" | "flags" | "tasks">, Record<never, never>, Record<never, never>>;

package/dist/cli-contract.js

@@ -0,0 +1,70 @@
+/**
+ * The `sdxc-well-known` command line as a contract: `security-txt check` for a site's or a
+ * file's security.txt, and `fetch` for any JSON document the package reads. Help, usage
+ * errors and each handler's typed `ctx.flags` all come from this one declaration.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import * as s from "@remix-run/data-schema";
+import { argument, command, commands, flag } from "@sdxc/cli";
+/** The documents `fetch` reads, by the registered name they are served under. */
+export const DOCUMENTS = [
+    "webfinger",
+    "nodeinfo",
+    "oauth-authorization-server",
+    "openid-configuration",
+    "oauth-protected-resource",
+    "jwks.json",
+    "passkey-endpoints",
+    "api-catalog",
+    "http-message-signatures-directory",
+];
+/** Every command `sdxc-well-known` takes. */
+export const WELL_KNOWN_COMMANDS = commands({
+    description: "sdxc-well-known — read and check /.well-known/ documents",
+    "security-txt": commands({
+        description: "security.txt (RFC 9116)",
+        check: command({
+            description: "Check a security.txt: required fields, field syntax and expiry. An http(s) origin fetches its /.well-known/security.txt; anything else is a file, - or nothing reads stdin. Exits 1 and lists every problem.",
+            arguments: {
+                target: argument(s.string(), {
+                    default: "-",
+                    description: "An origin (https://example.com), a file, or - for stdin",
+                }),
+            },
+            flags: {
+                json: flag.boolean("json", { description: "Print the report as JSON" }),
+            },
+            examples: [
+                "security-txt check https://example.com",
+                "security-txt check public/.well-known/security.txt --json",
+            ],
+        }),
+    }),
+    fetch: command({
+        description: "Fetch one well-known document from an origin, validate it and print it. OAuth and OpenID Connect metadata must name the identifier as their issuer, and protected resource metadata as its resource. Exits 1 and lists every problem on stderr.",
+        arguments: {
+            identifier: argument(s.string(), {
+                description: "The origin, issuer or resource URL (https://example.com)",
+            }),
+            document: argument(s.enum_(DOCUMENTS), {
+                description: `The document to read: ${DOCUMENTS.join(", ")}`,
+            }),
+        },
+        flags: {
+            resource: flag.string("resource", {
+                description: "The WebFinger resource to look up (acct:user@example.com)",
+            }),
+            rel: flag.string("rel", { description: "A WebFinger link relation to ask for" }).multiple(),
+            json: flag.boolean("json", {
+                description: "Print { document, url, valid, issues, data } with the parsed document",
+            }),
+        },
+        examples: [
+            "fetch https://auth.example.com openid-configuration",
+            "fetch https://mastodon.social webfinger --resource acct:Gargron@mastodon.social",
+            "fetch https://example.com jwks.json --json",
+        ],
+    }),
+});

package/dist/cli-fetch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The `sdxc-well-known fetch` handler: builds the URL a document lives at for an identifier,
+ * fetches it, validates it with the document's own reader and prints it. NodeInfo follows its
+ * links document to the newest schema it names, so the printed document is the server's own.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Prints the validated body on stdout, or each problem as `<pointer>: message` on stderr;
+ * `--json` prints `{ document, url, valid, issues, data }` with the parsed, camelCase document.
+ * NodeInfo answers 2.1 when its links name it, else 2.0.
+ */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<{
+    readonly identifier: import("@sdxc/cli").Argument<string>;
+    readonly document: import("@sdxc/cli").Argument<"api-catalog" | "webfinger" | "nodeinfo" | "oauth-authorization-server" | "openid-configuration" | "oauth-protected-resource" | "jwks.json" | "passkey-endpoints" | "http-message-signatures-directory">;
+}, {
+    readonly resource: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+    readonly rel: import("@sdxc/cli").ValueFlag<string, false, true, false>;
+    readonly json: import("@sdxc/cli").Flag<boolean>;
+}>, []>;
+export default _default;

package/dist/cli-fetch.js

@@ -0,0 +1,174 @@
+/**
+ * The `sdxc-well-known fetch` handler: builds the URL a document lives at for an identifier,
+ * fetches it, validates it with the document's own reader and prints it. NodeInfo follows its
+ * links document to the newest schema it names, so the printed document is the server's own.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, exit, success, usage } from "@sdxc/cli";
+import { isFailure } from "@sdxc/result";
+import * as apiCatalog from "./api-catalog.js";
+import { WELL_KNOWN_COMMANDS } from "./cli-contract.js";
+import { fetchDocument, readWebUrl, statusIssue } from "./cli-input.js";
+import * as signaturesDirectory from "./http-message-signatures-directory.js";
+import * as jwks from "./jwks.js";
+import * as nodeinfo from "./nodeinfo.js";
+import * as authorizationServer from "./oauth-authorization-server.js";
+import * as protectedResource from "./oauth-protected-resource.js";
+import * as openIdConfiguration from "./openid-configuration.js";
+import * as passkeyEndpoints from "./passkey-endpoints.js";
+import * as webfinger from "./webfinger.js";
+import { wellKnownUrl } from "./well-known-url.js";
+/**
+ * The document `name` serves at the root of the identifier's origin.
+ *
+ * @param name - The registered name
+ */
+function atOrigin(name) {
+    return (identifier) => success(wellKnownUrl(new URL(identifier).origin, name));
+}
+/** Every document `fetch` reads; NodeInfo's entry reads the links document it starts from. */
+const READERS = {
+    webfinger: {
+        accept: webfinger.MEDIA_TYPE,
+        url(identifier, flags) {
+            if (flags.resource === undefined) {
+                return usage("webfinger needs --resource, such as --resource acct:user@example.com");
+            }
+            let url = wellKnownUrl(new URL(identifier).origin, webfinger.NAME);
+            url.searchParams.set("resource", flags.resource);
+            for (let rel of flags.rel)
+                url.searchParams.append("rel", rel);
+            return success(url);
+        },
+        parse: (text) => webfinger.parse(text),
+    },
+    nodeinfo: {
+        accept: nodeinfo.MEDIA_TYPE,
+        url: atOrigin(nodeinfo.NAME),
+        parse: (text) => nodeinfo.parseLinks(text),
+    },
+    "oauth-authorization-server": {
+        accept: authorizationServer.MEDIA_TYPE,
+        url: (identifier) => success(wellKnownUrl(identifier, authorizationServer.NAME)),
+        parse: (text, issuer) => authorizationServer.parse(text, { issuer }),
+    },
+    "openid-configuration": {
+        accept: openIdConfiguration.MEDIA_TYPE,
+        url: (identifier) => success(wellKnownUrl(identifier, openIdConfiguration.NAME, "append")),
+        parse: (text, issuer) => openIdConfiguration.parse(text, { issuer }),
+    },
+    "oauth-protected-resource": {
+        accept: protectedResource.MEDIA_TYPE,
+        url: (identifier) => success(protectedResource.metadataUrl(identifier)),
+        parse: (text, resource) => protectedResource.parse(text, { resource }),
+    },
+    "jwks.json": {
+        accept: jwks.MEDIA_TYPE,
+        url: atOrigin(jwks.NAME),
+        parse: (text) => jwks.parse(text),
+    },
+    "passkey-endpoints": {
+        accept: passkeyEndpoints.MEDIA_TYPE,
+        url: atOrigin(passkeyEndpoints.NAME),
+        parse: (text) => passkeyEndpoints.parse(text),
+    },
+    "api-catalog": {
+        accept: apiCatalog.MEDIA_TYPE,
+        url: atOrigin(apiCatalog.NAME),
+        parse: (text) => apiCatalog.parse(text),
+    },
+    "http-message-signatures-directory": {
+        accept: signaturesDirectory.MEDIA_TYPE,
+        url: atOrigin(signaturesDirectory.NAME),
+        parse: (text) => signaturesDirectory.parse(text),
+    },
+};
+/**
+ * Reads a fetched body, turning a non-2xx status into the outcome's only issue.
+ *
+ * @param retrieved - The fetched document
+ * @param parse - The document's reader
+ */
+function read(retrieved, parse) {
+    let unavailable = statusIssue(retrieved);
+    if (unavailable !== null)
+        return { retrieved, data: null, issues: [unavailable] };
+    let parsed = parse(retrieved.text);
+    if (isFailure(parsed))
+        return { retrieved, data: null, issues: parsed.error.issues };
+    return { retrieved, data: parsed.data, issues: [] };
+}
+/**
+ * The served body for people: indented when it is JSON, verbatim otherwise.
+ *
+ * @param text - The body as served
+ */
+function pretty(text) {
+    try {
+        return `${JSON.stringify(JSON.parse(text), null, 2)}\n`;
+    }
+    catch {
+        return text.endsWith("\n") ? text : `${text}\n`;
+    }
+}
+/**
+ * Prints the validated body on stdout, or each problem as `<pointer>: message` on stderr;
+ * `--json` prints `{ document, url, valid, issues, data }` with the parsed, camelCase document.
+ * NodeInfo answers 2.1 when its links name it, else 2.0.
+ */
+export default createCommand(WELL_KNOWN_COMMANDS.fetch, async (ctx) => {
+    let { identifier, document } = ctx.arguments;
+    let checked = readWebUrl(identifier);
+    if (isFailure(checked))
+        return checked;
+    let reader = READERS[document];
+    let url = reader.url(identifier, ctx.flags);
+    if (isFailure(url))
+        return url;
+    let retrieved = await fetchDocument(url.data, reader.accept, ctx);
+    if (isFailure(retrieved))
+        return retrieved;
+    let outcome = read(retrieved.data, (text) => reader.parse(text, identifier));
+    if (document === "nodeinfo" && outcome.issues.length === 0) {
+        let { links } = outcome.data;
+        let link = links.find((entry) => entry.rel === nodeinfo.NODEINFO_2_1) ??
+            links.find((entry) => entry.rel === nodeinfo.NODEINFO_2_0);
+        if (link === undefined) {
+            outcome = {
+                ...outcome,
+                data: null,
+                issues: [{ at: "/links", message: "No link names a NodeInfo 2.0 or 2.1 schema." }],
+            };
+        }
+        else {
+            let linked = await fetchDocument(new URL(link.href), nodeinfo.DOCUMENT_MEDIA_TYPE, ctx);
+            if (isFailure(linked))
+                return linked;
+            outcome = read(linked.data, nodeinfo.parse);
+        }
+    }
+    let valid = outcome.issues.length === 0;
+    if (ctx.flags.json) {
+        let report = {
+            document,
+            url: outcome.retrieved.from,
+            valid,
+            issues: outcome.issues,
+            data: outcome.data,
+        };
+        ctx.stdout(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else if (valid) {
+        ctx.stdout(pretty(outcome.retrieved.text));
+    }
+    else {
+        ctx.stderr(`${outcome.retrieved.from}\n`);
+        for (let issue of outcome.issues) {
+            let at = issue.at === "" || issue.at === 0 ? "(document)" : String(issue.at);
+            ctx.stderr(`  ${at}: ${issue.message}\n`);
+        }
+    }
+    return valid ? success() : exit(1);
+});

package/dist/cli-input.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Where `sdxc-well-known` reads a document from: a file, stdin, or an origin over HTTP. Every
+ * command shares it, so an unreadable file and an unreachable origin both exit 2 with the same
+ * kind of message, while a server's error status stays a finding the command reports.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { ChainContext, ExitError, UsageError } from "@sdxc/cli";
+import type { Result } from "@sdxc/result";
+import { WellKnownParseError } from "./parse-error.js";
+/** A document as read, with `from` naming it in reports and `status` set when it was fetched. */
+export interface Retrieved {
+    from: string;
+    text: string;
+    /** The HTTP status for a fetched document, `null` for a file or stdin. */
+    status: number | null;
+}
+/** The run's directory, stdin and abort signal, which every read needs. */
+export type InputContext = Pick<ChainContext, "cwd" | "stdin" | "signal">;
+/**
+ * Whether text names a web origin rather than a file.
+ *
+ * @param text - An argument as typed
+ */
+export declare function isWebUrl(text: string): boolean;
+/**
+ * An `http(s)` URL from an argument, or a usage error naming what was expected.
+ *
+ * @param text - The argument as typed
+ */
+export declare function readWebUrl(text: string): Result<URL, UsageError>;
+/**
+ * Reads `file` against the run's directory, or stdin for `-`. A terminal on stdin is a usage
+ * error, so a command run with no input answers at once with its help.
+ *
+ * @param file - The path as typed, or `-`
+ * @param ctx - The running command
+ */
+export declare function readLocal(file: string, ctx: InputContext): Promise<Result<Retrieved, ExitError | UsageError>>;
+/**
+ * GETs `url`, following redirects, within a fixed deadline. Any answer the server gives is a
+ * success carrying its status; only a request that gets no answer exits 2.
+ *
+ * @param url - The document's URL
+ * @param accept - The media types the request asks for
+ * @param ctx - The running command, whose signal cancels the request
+ */
+export declare function fetchDocument(url: URL, accept: string, ctx: InputContext): Promise<Result<Retrieved, ExitError>>;
+/**
+ * The issue a non-2xx answer becomes, so a missing document is reported like a malformed one.
+ *
+ * @param retrieved - A document as read
+ * @returns The issue, or `null` for a file, stdin or a 2xx answer
+ */
+export declare function statusIssue(retrieved: Retrieved): WellKnownParseError.Issue | null;

package/dist/cli-input.js

@@ -0,0 +1,89 @@
+/**
+ * Where `sdxc-well-known` reads a document from: a file, stdin, or an origin over HTTP. Every
+ * command shares it, so an unreadable file and an unreachable origin both exit 2 with the same
+ * kind of message, while a server's error status stays a finding the command reports.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { exit, usage } from "@sdxc/cli";
+import { success } from "@sdxc/result";
+import { WellKnownParseError } from "./parse-error.js";
+/** How long one request may take before the command gives up on the origin. */
+const FETCH_TIMEOUT_MS = 10_000;
+/**
+ * Whether text names a web origin rather than a file.
+ *
+ * @param text - An argument as typed
+ */
+export function isWebUrl(text) {
+    return /^https?:\/\//i.test(text);
+}
+/**
+ * An `http(s)` URL from an argument, or a usage error naming what was expected.
+ *
+ * @param text - The argument as typed
+ */
+export function readWebUrl(text) {
+    if (isWebUrl(text) && URL.canParse(text))
+        return success(new URL(text));
+    return usage(`Expected an http(s) URL such as https://example.com; got ${JSON.stringify(text)}`);
+}
+/**
+ * Reads `file` against the run's directory, or stdin for `-`. A terminal on stdin is a usage
+ * error, so a command run with no input answers at once with its help.
+ *
+ * @param file - The path as typed, or `-`
+ * @param ctx - The running command
+ */
+export async function readLocal(file, ctx) {
+    if (file === "-") {
+        if (ctx.stdin.isTTY)
+            return usage("Pass an origin or a file, or pipe one on stdin");
+        return success({ from: "<stdin>", text: await ctx.stdin.text(), status: null });
+    }
+    try {
+        let text = await readFile(resolve(ctx.cwd, file), "utf8");
+        return success({ from: file, text, status: null });
+    }
+    catch (error) {
+        let reason = error instanceof Error ? error.message : String(error);
+        return exit(2, `Cannot read ${file}: ${reason}`);
+    }
+}
+/**
+ * GETs `url`, following redirects, within a fixed deadline. Any answer the server gives is a
+ * success carrying its status; only a request that gets no answer exits 2.
+ *
+ * @param url - The document's URL
+ * @param accept - The media types the request asks for
+ * @param ctx - The running command, whose signal cancels the request
+ */
+export async function fetchDocument(url, accept, ctx) {
+    try {
+        let response = await fetch(url, {
+            headers: { Accept: accept },
+            redirect: "follow",
+            signal: AbortSignal.any([ctx.signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)]),
+        });
+        return success({ from: url.href, text: await response.text(), status: response.status });
+    }
+    catch (error) {
+        let reason = error instanceof Error ? error.message : String(error);
+        return exit(2, `Cannot fetch ${url.href}: ${reason}`);
+    }
+}
+/**
+ * The issue a non-2xx answer becomes, so a missing document is reported like a malformed one.
+ *
+ * @param retrieved - A document as read
+ * @returns The issue, or `null` for a file, stdin or a 2xx answer
+ */
+export function statusIssue(retrieved) {
+    if (retrieved.status === null || (retrieved.status >= 200 && retrieved.status < 300)) {
+        return null;
+    }
+    return { at: 0, message: `The server answered HTTP ${retrieved.status}.` };
+}

package/dist/cli-security-txt-check.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The `sdxc-well-known security-txt check` handler: reads a security.txt from an origin, a
+ * file or stdin, applies the RFC 9116 reader and the expiry rule, and reports every problem
+ * with its line. Exits 1 when the file is missing, malformed or expired.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Prints `<source>: valid, expires <date>` or one `<source>:<line>: message` per problem, a
+ * line of `0` meaning the file as a whole; `--json` prints `{ source, valid, signed, expires,
+ * issues }`, with `signed` and `expires` `null` when the file could not be read.
+ */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<{
+    readonly target: import("@sdxc/cli").Argument<string>;
+}, {
+    readonly json: import("@sdxc/cli").Flag<boolean>;
+}>, []>;
+export default _default;

package/dist/cli-security-txt-check.js

@@ -0,0 +1,66 @@
+/**
+ * The `sdxc-well-known security-txt check` handler: reads a security.txt from an origin, a
+ * file or stdin, applies the RFC 9116 reader and the expiry rule, and reports every problem
+ * with its line. Exits 1 when the file is missing, malformed or expired.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, exit, success } from "@sdxc/cli";
+import { isFailure } from "@sdxc/result";
+import { WELL_KNOWN_COMMANDS } from "./cli-contract.js";
+import { fetchDocument, isWebUrl, readLocal, statusIssue } from "./cli-input.js";
+import { isExpired, MEDIA_TYPE, NAME, parse } from "./security-txt.js";
+import { wellKnownUrl } from "./well-known-url.js";
+/**
+ * Prints `<source>: valid, expires <date>` or one `<source>:<line>: message` per problem, a
+ * line of `0` meaning the file as a whole; `--json` prints `{ source, valid, signed, expires,
+ * issues }`, with `signed` and `expires` `null` when the file could not be read.
+ */
+export default createCommand(WELL_KNOWN_COMMANDS["security-txt"].check, async (ctx) => {
+    let target = ctx.arguments.target;
+    let retrieved = isWebUrl(target)
+        ? await fetchDocument(wellKnownUrl(new URL(target).origin, NAME), MEDIA_TYPE, ctx)
+        : await readLocal(target, ctx);
+    if (isFailure(retrieved))
+        return retrieved;
+    let from = retrieved.data.from;
+    let issues = [];
+    let document = null;
+    let unavailable = statusIssue(retrieved.data);
+    if (unavailable !== null) {
+        issues.push(unavailable);
+    }
+    else {
+        let parsed = parse(retrieved.data.text);
+        if (isFailure(parsed)) {
+            issues.push(...parsed.error.issues);
+        }
+        else {
+            document = parsed.data;
+            if (isExpired(document)) {
+                issues.push({ at: 0, message: `Expires ${document.expires.toISOString()} has passed.` });
+            }
+        }
+    }
+    if (ctx.flags.json) {
+        let report = {
+            source: from,
+            valid: issues.length === 0,
+            signed: document?.signed ?? null,
+            expires: document?.expires ?? null,
+            issues,
+        };
+        ctx.stdout(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else if (issues.length === 0 && document !== null) {
+        let signed = document.signed ? ", signed" : "";
+        ctx.stdout(`${from}: valid, expires ${document.expires.toISOString()}${signed}\n`);
+    }
+    else {
+        for (let issue of issues) {
+            ctx.stdout(issue.at === 0 ? `${from}: ${issue.message}\n` : `${from}:${issue.at}: ${issue.message}\n`);
+        }
+    }
+    return issues.length === 0 ? success() : exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * The `sdxc-well-known` command-line program: the contract in `cli-contract.ts` with each
+ * command mapped onto its handler, which loads only when that command runs. Exit codes: 0
+ * done, 1 a document with problems, 2 usage, unreadable input or an unreachable origin.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** The `sdxc-well-known` program, run by the bin entry below and by tests through `invoke()`. */
+export declare const cli: import("@sdxc/cli").CLI<import("@sdxc/cli").Group<Omit<{
+    readonly description: "sdxc-well-known — read and check /.well-known/ documents";
+    readonly "security-txt": import("@sdxc/cli").Group<Omit<{
+        readonly description: "security.txt (RFC 9116)";
+        readonly check: import("@sdxc/cli").Command<{
+            readonly target: import("@sdxc/cli").Argument<string>;
+        }, {
+            readonly json: import("@sdxc/cli").Flag<boolean>;
+        }>;
+    }, "description" | "hidden" | "arguments" | "flags" | "tasks">, Record<never, never>, Record<never, never>>;
+    readonly fetch: import("@sdxc/cli").Command<{
+        readonly identifier: import("@sdxc/cli").Argument<string>;
+        readonly document: import("@sdxc/cli").Argument<"api-catalog" | "webfinger" | "nodeinfo" | "oauth-authorization-server" | "openid-configuration" | "oauth-protected-resource" | "jwks.json" | "passkey-endpoints" | "http-message-signatures-directory">;
+    }, {
+        readonly resource: import("@sdxc/cli").ValueFlag<string, false, false, false>;
+        readonly rel: import("@sdxc/cli").ValueFlag<string, false, true, false>;
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+}, "description" | "hidden" | "arguments" | "flags" | "tasks">, Record<never, never>, Record<never, never>>, []>;

package/dist/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * The `sdxc-well-known` command-line program: the contract in `cli-contract.ts` with each
+ * command mapped onto its handler, which loads only when that command runs. Exit codes: 0
+ * done, 1 a document with problems, 2 usage, unreadable input or an unreachable origin.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCLI, lazy } from "@sdxc/cli";
+import { WELL_KNOWN_COMMANDS } from "./cli-contract.js";
+/** The `sdxc-well-known` program, run by the bin entry below and by tests through `invoke()`. */
+export const cli = createCLI({ name: "sdxc-well-known", commands: WELL_KNOWN_COMMANDS });
+cli.map(WELL_KNOWN_COMMANDS["security-txt"].check, lazy(() => import("./cli-security-txt-check.js")));
+cli.map(WELL_KNOWN_COMMANDS.fetch, lazy(() => import("./cli-fetch.js")));
+if (import.meta.main) {
+    process.exit(await cli.run(process.argv.slice(2)));
+}

package/package.json

@@ -1,8 +1,11 @@
 {
 	"name": "@sdxc/well-known",
-	"version": "2026.10.25",
+	"version": "2026.11.3",
 	"description": "Typed documents for well-known URIs: security.txt, WebFinger, NodeInfo, OAuth and OIDC metadata, JWKS and more",
 	"license": "MIT",
+	"bin": {
+		"sdxc-well-known": "dist/cli.js"
+	},
 	"type": "module",
 	"exports": {
 		".": "./dist/index.js",
@@ -23,14 +26,15 @@
 	},
 	"dependencies": {
 		"@remix-run/data-schema": "^1.0.0",
+		"@sdxc/cli": "2026.11.3",
 		"@sdxc/json-pointer": "2026.10.14",
 		"@sdxc/link-header": "2026.10.25",
-		"@sdxc/openpgp": "2026.10.25",
+		"@sdxc/openpgp": "2026.11.3",
 		"@sdxc/result": "2026.10.13",
 		"@standard-schema/spec": "^1.1.0"
 	},
 	"peerDependencies": {
-		"@sdxc/http": "2026.10.25",
+		"@sdxc/http": "2026.11.3",
 		"remix": "3.1.0"
 	},
 	"peerDependenciesMeta": {
@@ -41,7 +45,7 @@
 			"optional": true
 		}
 	},
-	"gitHead": "1440b969c0a3e3808dfcee3f17d2ef43915f32a8",
+	"gitHead": "d1dd4030f8df68b8a170940a3f790ea8654d3676",
 	"publishConfig": {
 		"access": "public"
 	},