@dwk/host-meta 0.1.0-beta.0

package/dist/log.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@dwk/host-meta` — structured observability event taxonomy.
+ *
+ * host-meta is public, request-invariant discovery data, so the stakes are low
+ * — but which representation clients actually negotiate (XRD vs JRD) is useful
+ * signal, and a flood of rejected non-`GET` probes is worth a counter. Logging
+ * and metrics are opt-in via an injected {@link Logger}/{@link Metrics} (see
+ * `@dwk/log`) and **share this one vocabulary**: the same dotted event name is
+ * passed to the logger and the metrics sink so a log line and its counter line
+ * up. No request carries user data — the document is host-wide — so fields are
+ * limited to the chosen `format` and a machine-readable `reason`.
+ *
+ * @packageDocumentation
+ */
+/** Stable event names emitted by `@dwk/host-meta`. */
+export declare const HostMetaLogEvent: {
+    /**
+     * The host-meta document was served. Field: `format` (`"xrd"` or `"jrd"`),
+     * the negotiated representation.
+     */
+    readonly Served: "host-meta.served";
+    /**
+     * A request was rejected before the document could be served. Field: `reason`
+     * (`method_not_allowed`).
+     */
+    readonly Rejected: "host-meta.rejected";
+};
+/** Union of the event-name string literals in {@link HostMetaLogEvent}. */
+export type HostMetaLogEvent = (typeof HostMetaLogEvent)[keyof typeof HostMetaLogEvent];
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,sDAAsD;AACtD,eAAO,MAAM,gBAAgB;IAC3B;;;OAGG;;IAEH;;;OAGG;;CAEK,CAAC;AAEX,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAC1B,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/log.js

@@ -0,0 +1,28 @@
+/**
+ * `@dwk/host-meta` — structured observability event taxonomy.
+ *
+ * host-meta is public, request-invariant discovery data, so the stakes are low
+ * — but which representation clients actually negotiate (XRD vs JRD) is useful
+ * signal, and a flood of rejected non-`GET` probes is worth a counter. Logging
+ * and metrics are opt-in via an injected {@link Logger}/{@link Metrics} (see
+ * `@dwk/log`) and **share this one vocabulary**: the same dotted event name is
+ * passed to the logger and the metrics sink so a log line and its counter line
+ * up. No request carries user data — the document is host-wide — so fields are
+ * limited to the chosen `format` and a machine-readable `reason`.
+ *
+ * @packageDocumentation
+ */
+/** Stable event names emitted by `@dwk/host-meta`. */
+export const HostMetaLogEvent = {
+    /**
+     * The host-meta document was served. Field: `format` (`"xrd"` or `"jrd"`),
+     * the negotiated representation.
+     */
+    Served: "host-meta.served",
+    /**
+     * A request was rejected before the document could be served. Field: `reason`
+     * (`method_not_allowed`).
+     */
+    Rejected: "host-meta.rejected",
+};
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,sDAAsD;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B;;;OAGG;IACH,MAAM,EAAE,kBAAkB;IAC1B;;;OAGG;IACH,QAAQ,EAAE,oBAAoB;CACtB,CAAC"}

package/dist/negotiation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Representation selection for the one `/.well-known/host-meta` URL (RFC 6415
+ * §3). The document is served as XRD (`application/xrd+xml`) **by default** and
+ * as JRD (`application/jrd+json`) only when the client specifically prefers it,
+ * via — in priority order — an explicit `?format=` override, the
+ * `host-meta.json` path (RFC 7033 §10.1, always JRD), or a higher-q Accept
+ * preference for JRD over XRD.
+ */
+/** The chosen representation. */
+export type Format = "xrd" | "jrd";
+/**
+ * Decide which representation to serve.
+ *
+ * 1. `?format=json`/`jrd` → JRD; `?format=xml`/`xrd` → XRD (explicit override
+ *    wins over everything, per RFC 6415 §3's `?format=` mechanism).
+ * 2. A request to the `host-meta.json` path → JRD (RFC 7033 §10.1).
+ * 3. Otherwise compare Accept q-values: JRD only when it is *strictly*
+ *    preferred over XRD; XRD is the default for ties, wildcards, and no header.
+ */
+export declare function negotiateFormat(url: URL, accept: string | null, isJsonPath: boolean): Format;
+//# sourceMappingURL=negotiation.d.ts.map

package/dist/negotiation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiation.d.ts","sourceRoot":"","sources":["../src/negotiation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,iCAAiC;AACjC,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;AA2BnC;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,UAAU,EAAE,OAAO,GAClB,MAAM,CAcR"}

package/dist/negotiation.js

@@ -0,0 +1,62 @@
+/**
+ * Representation selection for the one `/.well-known/host-meta` URL (RFC 6415
+ * §3). The document is served as XRD (`application/xrd+xml`) **by default** and
+ * as JRD (`application/jrd+json`) only when the client specifically prefers it,
+ * via — in priority order — an explicit `?format=` override, the
+ * `host-meta.json` path (RFC 7033 §10.1, always JRD), or a higher-q Accept
+ * preference for JRD over XRD.
+ */
+/**
+ * The best (highest) q-value among the given exact media types in an `Accept`
+ * header, or `0` if none of them appear. Wildcards (`* /*`) are deliberately
+ * ignored: they express no preference between XRD and JRD, so a bare `Accept:
+ * * /*` (or a missing header) must fall through to the XRD default.
+ */
+function acceptQuality(accept, mediaTypes) {
+    let best = 0;
+    for (const part of accept.split(",")) {
+        const segments = part.trim().split(";");
+        const type = segments[0]?.trim().toLowerCase();
+        if (type === undefined || !mediaTypes.includes(type))
+            continue;
+        let q = 1;
+        for (const segment of segments.slice(1)) {
+            const match = /^\s*q=(.*)$/i.exec(segment);
+            if (match && match[1] !== undefined) {
+                const parsed = Number.parseFloat(match[1]);
+                if (!Number.isNaN(parsed))
+                    q = parsed;
+            }
+        }
+        if (q > best)
+            best = q;
+    }
+    return best;
+}
+/**
+ * Decide which representation to serve.
+ *
+ * 1. `?format=json`/`jrd` → JRD; `?format=xml`/`xrd` → XRD (explicit override
+ *    wins over everything, per RFC 6415 §3's `?format=` mechanism).
+ * 2. A request to the `host-meta.json` path → JRD (RFC 7033 §10.1).
+ * 3. Otherwise compare Accept q-values: JRD only when it is *strictly*
+ *    preferred over XRD; XRD is the default for ties, wildcards, and no header.
+ */
+export function negotiateFormat(url, accept, isJsonPath) {
+    const format = url.searchParams.get("format")?.toLowerCase();
+    if (format === "json" || format === "jrd")
+        return "jrd";
+    if (format === "xml" || format === "xrd")
+        return "xrd";
+    if (isJsonPath)
+        return "jrd";
+    if (accept === null || accept.length === 0)
+        return "xrd";
+    const jrdQuality = acceptQuality(accept, [
+        "application/jrd+json",
+        "application/json",
+    ]);
+    const xrdQuality = acceptQuality(accept, ["application/xrd+xml"]);
+    return jrdQuality > xrdQuality ? "jrd" : "xrd";
+}
+//# sourceMappingURL=negotiation.js.map

package/dist/negotiation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiation.js","sourceRoot":"","sources":["../src/negotiation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;GAKG;AACH,SAAS,aAAa,CAAC,MAAc,EAAE,UAA6B;IAClE,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC/C,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,SAAS;QAC/D,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3C,IAAI,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;gBACpC,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC3C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;oBAAE,CAAC,GAAG,MAAM,CAAC;YACxC,CAAC;QACH,CAAC;QACD,IAAI,CAAC,GAAG,IAAI;YAAE,IAAI,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAQ,EACR,MAAqB,EACrB,UAAmB;IAEnB,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IAC7D,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACxD,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAEvD,IAAI,UAAU;QAAE,OAAO,KAAK,CAAC;IAE7B,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACzD,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,EAAE;QACvC,sBAAsB;QACtB,kBAAkB;KACnB,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC;IAClE,OAAO,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;AACjD,CAAC"}

package/dist/xrd.d.ts

@@ -0,0 +1,24 @@
+/**
+ * XRD (Extensible Resource Descriptor) rendering of a host-meta document — the
+ * default `application/xrd+xml` representation of RFC 6415 §2. This is the only
+ * serializer new to `@dwk/host-meta`: the JRD side reuses `@dwk/webfinger`'s
+ * link shape. It renders the *same* {@link HostMetaDocument} the JRD serializer
+ * does, so the two stay information-equivalent (RFC 6415 §3).
+ *
+ * Output maps the model onto the XRD 1.0 schema: `Subject`, `Property`
+ * (`xsi:nil="true"` for an absent/`null` value), and `Link` elements with
+ * `rel`/`type`/`href`/`template` attributes and nested `Title`/`Property`
+ * children. All text and attribute values are XML-escaped.
+ */
+import type { HostMetaDocument } from "./document";
+/** The XRD 1.0 default namespace (OASIS). */
+export declare const XRD_NAMESPACE = "http://docs.oasis-open.org/ns/xri/xrd-1.0";
+/**
+ * Escape a string for inclusion in XML text or a double-quoted attribute value:
+ * the five predefined entities. Applied to every dynamic value so operator- or
+ * resource-supplied content can never break out of the document structure.
+ */
+export declare function escapeXml(value: string): string;
+/** Serialize a host-meta document to an XRD (`application/xrd+xml`) body. */
+export declare function serializeXrd(document: HostMetaDocument): string;
+//# sourceMappingURL=xrd.d.ts.map

package/dist/xrd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xrd.d.ts","sourceRoot":"","sources":["../src/xrd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAQ,MAAM,YAAY,CAAC;AAEzD,6CAA6C;AAC7C,eAAO,MAAM,aAAa,8CAA8C,CAAC;AAIzE;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO/C;AA0DD,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAsB/D"}

package/dist/xrd.js

@@ -0,0 +1,100 @@
+/**
+ * XRD (Extensible Resource Descriptor) rendering of a host-meta document — the
+ * default `application/xrd+xml` representation of RFC 6415 §2. This is the only
+ * serializer new to `@dwk/host-meta`: the JRD side reuses `@dwk/webfinger`'s
+ * link shape. It renders the *same* {@link HostMetaDocument} the JRD serializer
+ * does, so the two stay information-equivalent (RFC 6415 §3).
+ *
+ * Output maps the model onto the XRD 1.0 schema: `Subject`, `Property`
+ * (`xsi:nil="true"` for an absent/`null` value), and `Link` elements with
+ * `rel`/`type`/`href`/`template` attributes and nested `Title`/`Property`
+ * children. All text and attribute values are XML-escaped.
+ */
+/** The XRD 1.0 default namespace (OASIS). */
+export const XRD_NAMESPACE = "http://docs.oasis-open.org/ns/xri/xrd-1.0";
+/** The XML Schema instance namespace, used for `xsi:nil` on absent properties. */
+const XSI_NAMESPACE = "http://www.w3.org/2001/XMLSchema-instance";
+/**
+ * Escape a string for inclusion in XML text or a double-quoted attribute value:
+ * the five predefined entities. Applied to every dynamic value so operator- or
+ * resource-supplied content can never break out of the document structure.
+ */
+export function escapeXml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/** Whether any property (top-level or per-link) is `null`, requiring the `xsi` namespace. */
+function needsXsi(document) {
+    // Mirror linkXml's null-safety: a missing properties bag (`undefined` or a
+    // runtime `null` from untyped callers) carries no nil values to declare.
+    const hasNil = (props) => props !== undefined &&
+        props !== null &&
+        Object.values(props).some((v) => v === null);
+    if (hasNil(document.properties))
+        return true;
+    return document.links.some((link) => hasNil(link.properties));
+}
+/** Render a single `<Property>` element at the given indent. */
+function propertyXml(type, value, indent) {
+    if (value === null) {
+        return `${indent}<Property type="${escapeXml(type)}" xsi:nil="true"/>`;
+    }
+    return `${indent}<Property type="${escapeXml(type)}">${escapeXml(value)}</Property>`;
+}
+/** Render a single `<Link>` element, expanding to a child block only when it has titles/properties. */
+function linkXml(link) {
+    const attrs = [`rel="${escapeXml(link.rel)}"`];
+    if (link.type !== undefined)
+        attrs.push(`type="${escapeXml(link.type)}"`);
+    if (link.href !== undefined)
+        attrs.push(`href="${escapeXml(link.href)}"`);
+    if (link.template !== undefined) {
+        attrs.push(`template="${escapeXml(link.template)}"`);
+    }
+    const open = `  <Link ${attrs.join(" ")}`;
+    const titles = link.titles ? Object.entries(link.titles) : [];
+    const properties = link.properties ? Object.entries(link.properties) : [];
+    if (titles.length === 0 && properties.length === 0) {
+        return [`${open}/>`];
+    }
+    const lines = [`${open}>`];
+    for (const [lang, title] of titles) {
+        // RFC 7033 §4.4.4.3 uses "und" for an undetermined language; XRD omits the
+        // attribute in that case rather than emitting `xml:lang="und"`.
+        const langAttr = lang === "und" ? "" : ` xml:lang="${escapeXml(lang)}"`;
+        lines.push(`    <Title${langAttr}>${escapeXml(title)}</Title>`);
+    }
+    for (const [type, value] of properties) {
+        lines.push(propertyXml(type, value, "    "));
+    }
+    lines.push("  </Link>");
+    return lines;
+}
+/** Serialize a host-meta document to an XRD (`application/xrd+xml`) body. */
+export function serializeXrd(document) {
+    const rootAttrs = needsXsi(document)
+        ? `xmlns="${XRD_NAMESPACE}" xmlns:xsi="${XSI_NAMESPACE}"`
+        : `xmlns="${XRD_NAMESPACE}"`;
+    const lines = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<XRD ${rootAttrs}>`,
+    ];
+    if (document.subject !== undefined) {
+        lines.push(`  <Subject>${escapeXml(document.subject)}</Subject>`);
+    }
+    if (document.properties) {
+        for (const [type, value] of Object.entries(document.properties)) {
+            lines.push(propertyXml(type, value, "  "));
+        }
+    }
+    for (const link of document.links) {
+        lines.push(...linkXml(link));
+    }
+    lines.push("</XRD>");
+    return lines.join("\n") + "\n";
+}
+//# sourceMappingURL=xrd.js.map

package/dist/xrd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xrd.js","sourceRoot":"","sources":["../src/xrd.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@dwk/host-meta",
+  "version": "0.1.0-beta.0",
+  "description": "Web Host Metadata (RFC 6415) host-meta discovery at /.well-known/host-meta with XRD/JRD content negotiation.",
+  "keywords": [
+    "host-meta",
+    "rfc6415",
+    "well-known",
+    "discovery",
+    "xrd",
+    "jrd",
+    "cloudflare-workers"
+  ],
+  "type": "module",
+  "license": "ISC",
+  "author": "David W. Keith <me@dwk.io>",
+  "homepage": "https://github.com/davidwkeith/workers/tree/main/packages/host-meta#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwkeith/workers.git",
+    "directory": "packages/host-meta"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dwk/log": "0.1.0-beta.0",
+    "@dwk/webfinger": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}

package/src/config.ts

@@ -0,0 +1,96 @@
+/**
+ * Configuration for {@link createHostMeta}: the WebFinger endpoint URL that
+ * seeds the `lrdd` template and/or a set of static top-level links, plus the
+ * optional logging/metrics seams. Per the composition contract the package
+ * never reads the global environment — every link arrives here, so a handler
+ * can be instantiated multiple times and tested in isolation.
+ */
+
+import { noopLogger, noopMetrics, type Logger, type Metrics } from "@dwk/log";
+import type { Link } from "@dwk/webfinger";
+
+import { buildDocument, type HostMetaDocument } from "./document";
+import { serializeJrd } from "./jrd";
+import { serializeXrd } from "./xrd";
+
+/** Configuration passed to {@link createHostMeta}. */
+export interface HostMetaConfig {
+  /**
+   * The site's WebFinger endpoint URL (e.g.
+   * `https://example.com/.well-known/webfinger`). When supplied, an `lrdd` link
+   * templated to it (`…?resource={uri}`) is emitted first — the relation
+   * fediverse/OpenID software fetches host-meta to find before falling back to
+   * WebFinger. A URL already containing `{uri}` is used verbatim.
+   */
+  readonly webfingerUrl?: string;
+  /**
+   * Additional static top-level `Link` entries to advertise (e.g. `author`,
+   * `license`). Appended after the auto-generated `lrdd` link. At least one of
+   * {@link webfingerUrl} or `links` MUST be supplied, or {@link createHostMeta}
+   * throws at construction time.
+   */
+  readonly links?: readonly Link[];
+  /** Optional subject the metadata describes — the host itself (XRD `Subject`). */
+  readonly subject?: string;
+  /** Optional host-level properties; a `null` value means "present but absent". */
+  readonly properties?: Readonly<Record<string, string | null>>;
+  /**
+   * Logger for discovery events; defaults to a no-op. Wire a real logger (see
+   * `@dwk/log`) to surface which representation was served and why a request was
+   * rejected instead of swallowing them.
+   */
+  readonly logger?: Logger;
+  /**
+   * Metrics sink for discovery counters; defaults to a no-op. Wire an adapter
+   * (e.g. `analyticsEngineMetrics` from `@dwk/log`) to chart the same events the
+   * logger names — "served/min" by format, "rejection rate".
+   */
+  readonly metrics?: Metrics;
+}
+
+/** Configuration after defaults are filled and the document is pre-computed. */
+export interface ResolvedConfig {
+  /** The host-meta document, built once at construction (it never varies per request). */
+  readonly document: HostMetaDocument;
+  /** The XRD representation, serialized once at construction. */
+  readonly xrdBody: string;
+  /** The JRD representation, serialized once at construction. */
+  readonly jrdBody: string;
+  readonly logger: Logger;
+  readonly metrics: Metrics;
+}
+
+/**
+ * Validate and normalise a {@link HostMetaConfig}. Fails loudly when neither a
+ * WebFinger URL nor any static link is configured — a host-meta document that
+ * advertises nothing is always a misconfiguration, not a silently empty `XRD`.
+ * The document is computed once here (it is request-invariant) and reused for
+ * every response.
+ */
+export function resolveConfig(config: HostMetaConfig): ResolvedConfig {
+  const hasLinks = (config.links?.length ?? 0) > 0;
+  if (config.webfingerUrl === undefined && !hasLinks) {
+    throw new Error(
+      "@dwk/host-meta: configure `webfingerUrl` and/or `links` — a host-meta " +
+        "document must advertise at least one link.",
+    );
+  }
+
+  // The document is request-invariant, so both representations are serialized
+  // once here and reused verbatim for every response — no per-request XML
+  // serialization or JSON.stringify.
+  const document = buildDocument({
+    webfingerUrl: config.webfingerUrl,
+    links: config.links,
+    subject: config.subject,
+    properties: config.properties,
+  });
+
+  return {
+    document,
+    xrdBody: serializeXrd(document),
+    jrdBody: serializeJrd(document),
+    logger: config.logger ?? noopLogger,
+    metrics: config.metrics ?? noopMetrics,
+  };
+}

package/src/document.ts

@@ -0,0 +1,82 @@
+/**
+ * The host-meta document model (RFC 6415 §2): a host-wide set of top-level
+ * `Link`s plus optional `Subject`/`Property` metadata. The model is a single
+ * plain-data shape that **both** representations render from — the XRD
+ * (`application/xrd+xml`) serializer in `xrd.ts` and the JRD
+ * (`application/jrd+json`) serializer in `jrd.ts` — so the two are guaranteed
+ * information-equivalent (RFC 6415 §3).
+ *
+ * The `Link` type is reused verbatim from `@dwk/webfinger`: host-meta links are
+ * the same `rel`/`href`/`template`/`type`/`titles`/`properties` shape WebFinger
+ * already defines, so the JRD link-shaping is shared and only the XRD serializer
+ * is new (see the package spec).
+ */
+
+import type { Link } from "@dwk/webfinger";
+
+export type { Link };
+
+/**
+ * A resolved host-meta document. `links` is always present (it is the point of
+ * the document); `subject` and `properties` appear only when the operator
+ * configured them. This is what both serializers consume.
+ */
+export interface HostMetaDocument {
+  /** Optional subject the metadata describes — the host itself (XRD `Subject`). */
+  readonly subject?: string;
+  /** Optional host-level properties; a `null` value means "present but absent". */
+  readonly properties?: Readonly<Record<string, string | null>>;
+  /** The top-level link relations advertised for the host. */
+  readonly links: readonly Link[];
+}
+
+/**
+ * Build the `lrdd` `template` from a WebFinger endpoint URL. The Link-based
+ * Resource Descriptor Document template is the URL clients expand with the
+ * queried resource (`{uri}`) to reach per-account discovery (RFC 6415 §3,
+ * RFC 7033 §10.1). If the supplied URL already contains a `{uri}` placeholder it
+ * is used as-is; otherwise a `resource={uri}` query parameter is appended.
+ */
+export function lrddTemplate(webfingerUrl: string): string {
+  if (webfingerUrl.includes("{uri}")) return webfingerUrl;
+  const separator = webfingerUrl.includes("?") ? "&" : "?";
+  return `${webfingerUrl}${separator}resource={uri}`;
+}
+
+/**
+ * Assemble the host-meta {@link HostMetaDocument} from the operator's inputs.
+ * When a WebFinger endpoint URL is supplied, an `lrdd` link templated to it is
+ * emitted **first** (the relation fediverse/OpenID software probes for before
+ * falling back to WebFinger), followed by any static operator-configured links.
+ */
+export function buildDocument(opts: {
+  readonly webfingerUrl?: string;
+  readonly links?: readonly Link[];
+  readonly subject?: string;
+  readonly properties?: Readonly<Record<string, string | null>>;
+}): HostMetaDocument {
+  const links: Link[] = [];
+  if (opts.webfingerUrl !== undefined) {
+    links.push({
+      rel: "lrdd",
+      type: "application/jrd+json",
+      template: lrddTemplate(opts.webfingerUrl),
+    });
+  }
+  if (opts.links) {
+    links.push(...opts.links);
+  }
+
+  const document: {
+    subject?: string;
+    properties?: Readonly<Record<string, string | null>>;
+    links: readonly Link[];
+  } = { links };
+  if (opts.subject !== undefined) {
+    document.subject = opts.subject;
+  }
+  if (opts.properties && Object.keys(opts.properties).length > 0) {
+    document.properties = opts.properties;
+  }
+  return document;
+}