turva-llms-txt-validator 0.3.1 → 0.3.3

package/README.md

@@ -1,72 +1,159 @@
 # turva-llms-txt-validator
 
-Validate a site's llms.txt structure from the command line, from Node or in CI. Eight structure checks, each reported as pass, warn or fail with a one-line detail, and two v2 discovery checks reported as information. No score on purpose: a structure check can say what is there and what is missing, and a number on top of ten checks would look like an agent-readiness score without measuring one.
+Check a website's `llms.txt` from the command line, Node or CI. Get a clear result for each check, with readable output or JSON.
 
-This is the open-source form of the hosted validator at [turva.dev/llms-txt-validator](https://turva.dev/llms-txt-validator), which runs the same logic inside the open [turva.dev Cloudflare Worker](https://github.com/erekola/turva-worker). The hosted validator stays canonical: if the two ever disagree, the hosted one wins and this package gets the fix.
+**Eight structure checks and two informational discovery checks.** The result describes the file's structure and the home page's discovery links. It does not measure overall agent readiness or predict AI-search citations.
 
-## Install
+[npm package](https://www.npmjs.com/package/turva-llms-txt-validator) · [Try it in your browser](https://turva.dev/llms-txt-validator) · [llms.txt guide](https://turva.dev/guides/llms-txt) · [All turva.dev tools](https://turva.dev/tools)
 
-    npm install -g turva-llms-txt-validator
+## Quick start
 
-Or run it without installing:
+Requires **Node.js 18.17 or newer**. Run it without a global install:
 
-    npx turva-llms-txt-validator example.com
+```sh
+npx --yes turva-llms-txt-validator example.com
+```
 
-## CLI
+Replace `example.com` with the domain you want to check. A domain, HTTP URL or HTTPS URL is accepted. Validation uses the host's `/llms.txt` and home page over HTTPS, regardless of the supplied path.
 
-    llms-txt-validate example.com
-    llms-txt-validate example.com --json
-    llms-txt-validate example.com --strict
+For repeated use, install the CLI globally:
 
-Exit codes: 0 valid (warnings allowed), 1 not valid (with --strict, warnings also exit 1), 2 fetch or input error. The two v2 checks are reported as information and move no exit code. Two documents are fetched from the target site over https, its /llms.txt and its home page, each following a redirect only to the same host or its www/apex twin (an off-site or unsafe redirect fails the first check), each fetch times out after 8 seconds and each read is capped at 256 KB. Nothing else is requested, the site is never crawled and nothing is stored.
+```sh
+npm install -g turva-llms-txt-validator
+llms-txt-validate example.com
+```
 
-The target has to be a public domain name: an IP literal, a bracketed IPv6 address, localhost and the internal-use TLDs local, internal, home, lan, corp, test and invalid are all refused before any request goes out, and every redirect hop is checked by the same rule. Names are not resolved here, so a public name that points at a private address is stopped by the network the fetch runs on rather than by this code. On the hosted validator that network is the Cloudflare edge, which does not route to private address space.
+## Read the result
 
-## The checks
+The summary comes last. Each preceding line reports one check. This shortened example uses the hosted validator's turva.dev result observed on 2026-09-09, formatted as the CLI prints it. The remaining passing checks are omitted here:
 
-| # | Check | fail | warn |
-|---|-------|------|------|
-| 1 | File exists at /llms.txt, HTTP 200 (a same-site www/apex redirect is followed) | non-200, or an off-site or unsafe redirect | |
-| 2 | Response is plain text | body looks like HTML | content-type is not text/plain or text/markdown |
-| 3 | Starts with an H1 title | first non-empty line is not a markdown H1, indentation included, since four spaces make it a code block | |
-| 4 | Blockquote summary after the title | | missing one-line summary |
-| 5 | H2 sections group the content | | no H2 sections, or no section carrying a markdown file list |
-| 6 | Markdown links an agent can follow | | no links, an empty link name, a scheme without a host, or relative links |
-| 7 | Small enough to be cheap to read | | over 50 KB, or read truncated at 256 KB |
-| 8 | No HTML markup in the file | | HTML tags found |
+```text
+https://turva.dev/llms.txt
+  ok    File exists at /llms.txt (HTTP 200)
+  ok    Response is plain text (text/plain)
+  ok    Starts with an H1 title ("# turva.dev")
+result: valid
+```
 
-Two more checks read the site's home page for the link relations v2 of the format recommends. They describe the site rather than the file, so they carry the status `pass` when the relation is there and `info` when it is not, never `warn` and never `fail`, and they leave both the summary line and the `--strict` exit code alone. v2 is two weeks old at the time of writing, so warning about these would turn valid files into files with warnings for following the version of the format they were written against.
+A `warn` identifies something to review, such as a missing blockquote summary. It does not fail the command unless you add `--strict`. A `FAIL` means a structural requirement failed. Each line includes the observed detail.
 
-| # | Check | pass | info |
-|---|-------|------|------|
-| 9 | Home page points to its llms.txt (v2) | `rel="describedby"` with a target, found in the head or the Link header | not found, no target on the relation, or the home page could not be read |
-| 10 | Home page points to a markdown version (v2) | `rel="alternate"` with the media type `text/markdown` and a target, found in the head or the Link header | not found, no target on the relation, a different media type, or the home page could not be read |
+The eight structure checks determine the summary:
 
-## Node API
+| Summary | Meaning | Default exit code | With `--strict` |
+| --- | --- | --- | --- |
+| `valid` | No structure warnings or failures | `0` | `0` |
+| `valid with warnings` | At least one warning, no failures | `0` | `1` |
+| `not valid` | At least one failure | `1` | `1` |
+| Input or fetch error | Validation could not complete | `2` | `2` |
 
-    import { validateHost } from "turva-llms-txt-validator";
+The two discovery checks return `pass` or `info`. They never change the summary or exit code, including in strict mode. If the home page cannot be read, those checks report `info`. The file's structure result still stands.
 
-    const result = await validateHost("example.com");
-    console.log(result.summary);
-    for (const c of result.checks) console.log(c.status, c.label, c.detail);
+Use JSON for automation and strict mode when warnings should fail a CI step:
 
-The summary is one of valid, valid with warnings, or not valid, and the two v2 checks never change it. The result object is { target, summary, checks }, the same shape the hosted validator returns as JSON:
+```sh
+npx --yes turva-llms-txt-validator example.com --json --strict
+```
 
-    curl -H "Accept: application/json" "https://turva.dev/llms-txt-validator?url=example.com"
+Completed validation returns `{ target, summary, checks }`. Each check contains `{ id, status, label, detail }`. With `--json`, input and fetch errors return `{ "error": "..." }` and exit with code `2`.
 
-## CI
+## What it checks
 
-GitHub Actions:
+### File structure
 
-    - name: Validate llms.txt
-      run: npx turva-llms-txt-validator your-domain.com --strict
+| # | Check | Failure | Warning |
+| --- | --- | --- | --- |
+| 1 | `/llms.txt` returns HTTP 200 | Non-200 response, rejected or excessive redirects | none |
+| 2 | Response is plain text | Body looks like an HTML page | Content type is neither `text/plain` nor `text/markdown` |
+| 3 | First non-empty line is a Markdown H1 | Missing H1, including a title indented as a code block | none |
+| 4 | Blockquote summary follows the title | none | Missing summary |
+| 5 | H2 sections group the content | none | No H2 sections, or no section contains a Markdown link list |
+| 6 | Markdown links have names and absolute HTTP or HTTPS targets | none | Missing links, empty names, relative targets or unsupported targets |
+| 7 | File is small enough to read cheaply | none | Over 50 KB, or truncated at the 256 KB read limit |
+| 8 | File contains no HTML markup | none | HTML tags found |
 
-Woodpecker or any other runner: the same npx line works anywhere Node 18.17 or newer is present.
+Some failures stop the file checks early. For example, an HTML response is reported as a failed plain-text check rather than parsed as Markdown.
 
-## Why these checks
+### Home-page discovery
 
-The llms.txt format is a plain text map of a site for AI agents: an H1 title, a one-line blockquote summary and H2 sections of markdown links. v2 of the proposal, published in August 2026, left that format alone and added two link relations so an agent can find a page's markdown version and its llms.txt without guessing. The first eight checks test the structure and nothing else, and the last two report those two relations. What the format is and why it matters is written out at [llms.txt explained](https://turva.dev/guides/llms-txt), and the free tools this package belongs to are collected at [turva.dev/tools](https://turva.dev/tools).
+These checks are labelled **v2** in the output. They look for link relations in the home page's HTML head or HTTP `Link` header.
+
+| # | Check | Pass condition | Otherwise |
+| --- | --- | --- | --- |
+| 9 | Home page points to its llms.txt | `rel="describedby"` has a non-empty target | `info` |
+| 10 | Home page points to a Markdown version | `rel="alternate"` has media type `text/markdown` and a non-empty target | `info` |
+
+The validator detects these declarations without fetching their targets. It also does not follow the links inside `llms.txt`, crawl the site or test whether an AI agent can complete a task there.
+
+## Use from Node
+
+Install the package in your project:
+
+```sh
+npm install turva-llms-txt-validator
+```
+
+Use an ES module, for example `validate.mjs`:
+
+```js
+import { validateHost } from "turva-llms-txt-validator";
+
+const result = await validateHost("example.com");
+console.log(result.summary);
+for (const check of result.checks) {
+  console.log(check.status, check.label, check.detail);
+}
+```
+
+`validateHost` rejects on invalid input or a failed `/llms.txt` fetch. Structural failures are returned in `checks` with the summary `not valid`.
+
+## Use in CI
+
+Add this step to a GitHub Actions job that already has Node.js 18.17 or newer available. Replace `your-domain.com` with your domain:
+
+```yaml
+- name: Validate llms.txt
+  run: npx --yes turva-llms-txt-validator your-domain.com --strict
+```
+
+The same command works in Woodpecker and other runners with Node installed. Omit `--strict` if warnings should remain advisory.
+
+## Fetch limits and security
+
+The default validation requests two documents: `https://<host>/llms.txt` and `https://<host>/`. Redirects may add requests, but linked pages and discovery targets are never fetched. The validator stores no results.
+
+- Timeout: eight seconds per document, shared across its redirect chain.
+- Read limit: 256 KB per response.
+- Redirects: up to four hops, over HTTPS, to the same host or its `www`/apex equivalent. Off-site redirects, embedded credentials and unsupported ports are rejected.
+- Host checks: IP literals, bracketed IPv6 addresses, localhost and the internal-use TLDs `local`, `internal`, `home`, `lan`, `corp`, `test` and `invalid` are rejected before a request is sent. Redirect targets are checked too.
+
+**DNS resolution is not checked for private addresses.** A syntactically public domain can resolve to a private IP, so if you expose this package through a service that accepts untrusted domains, enforce private-address restrictions at the network layer. Local and CI runs use their own network policy. The hosted validator runs on the Cloudflare edge.
+
+For vulnerability reporting and supported versions, see [SECURITY.md](SECURITY.md).
+
+## Hosted version and source
+
+The [hosted validator](https://turva.dev/llms-txt-validator) accepts any public domain in the browser. It requests the same two documents, `/llms.txt` and the home page, and runs the same checks. Its source is in the [turva.dev Cloudflare Worker](https://github.com/erekola/turva-worker). The hosted validator is the canonical implementation: if results diverge, this package is updated to match it.
+
+The hosted version also returns JSON with the same result shape:
+
+```sh
+curl -H "Accept: application/json" "https://turva.dev/llms-txt-validator?url=example.com"
+```
+
+In Windows PowerShell, use `curl.exe` if `curl` resolves to `Invoke-WebRequest`.
+
+The package has no runtime dependencies. The repository's release workflow uses npm trusted publishing with provenance. See [SECURITY.md](SECURITY.md) for details and [CHANGELOG.md](CHANGELOG.md) for releases.
+
+## Check HTML and Markdown content
+
+[markdown-parity-check](https://github.com/erekola/markdown-parity-check) is a separate tool for a different question. This validator reads the structure of `llms.txt` and the home page's discovery links. The parity check compares the main content of one page's HTML and Markdown versions and reports changed text, numbers, links or blocks. It requires Node.js 22 or newer:
+
+```sh
+npx --yes markdown-parity-check --url https://example.com/page --format json
+```
+
+Replace the URL with your page. If Markdown is served at another address, add `--markdown-url https://example.com/page.md`. Its [browser version](https://turva.dev/markdown-parity-check) on turva.dev checks turva.dev's own pages only. See the [comparison README](https://github.com/erekola/markdown-parity-check) for local-file mode, exit codes and limits.
 
 ## License
 
-MIT. Source at [github.com/erekola/llms-txt-validator](https://github.com/erekola/llms-txt-validator). Published to npm from GitHub Actions with provenance, a signed attestation of where and how the package was built, verifiable on the npm package page.
+[MIT](LICENSE). Built by [Erik Rekola](https://github.com/erekola) at [turva.dev](https://turva.dev).

package/bin/cli.mjs

@@ -31,6 +31,11 @@ try {
   if (result.summary === "valid with warnings" && flags.has("--strict")) process.exit(1);
   process.exit(0);
 } catch (err) {
-  console.error("error: " + (err && err.message ? err.message : String(err)));
+  const message = err && err.message ? err.message : String(err);
+  // The hosted validator answers every failure as JSON when JSON was asked for, so a CI
+  // step that parses --json output gets {"error": ...} here too instead of an empty stdout
+  // and a plain-text stderr (round 16 S3-3). The exit code is unchanged.
+  if (flags.has("--json")) console.log(JSON.stringify({ error: message }, null, 2));
+  else console.error("error: " + message);
   process.exit(2);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "turva-llms-txt-validator",
-  "version": "0.3.1",
-  "description": "Validate a site's llms.txt structure: eight checks as pass/warn/fail plus two llms.txt v2 discovery checks as information, JSON output. Same checks as the hosted validator at turva.dev/llms-txt-validator.",
+  "version": "0.3.3",
+  "description": "Validate a site's llms.txt structure: eight checks as pass/warn/fail plus two llms.txt v2 discovery checks that read pass or info and never move the summary, JSON output. Same checks as the hosted validator at turva.dev/llms-txt-validator.",
   "type": "module",
   "main": "./src/index.mjs",
   "exports": "./src/index.mjs",

package/src/index.mjs

@@ -12,8 +12,20 @@ import { readFileSync } from "node:fs";
 export const VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8")
 ).version;
+// The hosted validator identifies itself without a version, because its version is the
+// site's and moves with every release; this package carries its own. The two strings
+// differ on purpose and nothing compares them (round 16 S3-6).
 const UA = "turva-llms-txt-validator/" + VERSION + " (+https://turva.dev/llms-txt-validator)";
 
+// Cut a string to at most n UTF-16 code units without leaving a lone high surrogate at the
+// end. String.prototype.slice counts code units, so a cut that lands inside a surrogate
+// pair leaves half of it, and that half serialises as bytes that are not valid UTF-8
+// (round 16 S3-1 and S3-2, measured on the hosted validator). Mirrors worker.js cut().
+export function cut(s, n) {
+  s = String(s).slice(0, n);
+  return /[\uD800-\uDBFF]$/.test(s) ? s.slice(0, -1) : s;
+}
+
 export function normalizeHostInput(raw) {
   let s = String(raw || "").trim().toLowerCase();
   if (!s) return null;
@@ -56,15 +68,20 @@ export async function fetchLlmsTxt(host, opts = {}) {
       headers: { "user-agent": opts.userAgent ?? UA, "accept": opts.accept ?? "text/plain, text/markdown;q=0.9, */*;q=0.1" }
     });
     if (res.status >= 300 && res.status < 400) {
+      // Six paths leave this branch, five returns and one continue, and not one of them
+      // ever reads the redirect body. undici holds the connection until a body is read or
+      // cancelled, so it is released here, once, before the location is even parsed. A
+      // failed cancel must not turn a redirect verdict into a throw (2026-09-10).
+      try { await res.body?.cancel(); } catch { /* the verdict below is the answer */ }
       const loc = res.headers.get("location") || "";
       if (!loc) return { redirect: true, reason: "no-location", status: res.status, location: "" };
-      if (hop >= 4) return { redirect: true, reason: "too-many", status: res.status, location: loc.slice(0, 120) };
+      if (hop >= 4) return { redirect: true, reason: "too-many", status: res.status, location: cut(loc, 120) };
       let next;
-      try { next = new URL(loc, url); } catch { return { redirect: true, reason: "bad-location", status: res.status, location: loc.slice(0, 120) }; }
+      try { next = new URL(loc, url); } catch { return { redirect: true, reason: "bad-location", status: res.status, location: cut(loc, 120) }; }
       const safeTarget = next.protocol === "https:" && !next.port && !next.username && !next.password && isValidPublicHost(next.hostname);
       const twin = (next.hostname.startsWith("www.") ? next.hostname.slice(4) : next.hostname) === reqApex;
-      if (!safeTarget) return { redirect: true, reason: "unsafe-target", status: res.status, location: next.href.slice(0, 120) };
-      if (!twin) return { redirect: true, reason: "off-host", status: res.status, location: next.href.slice(0, 120) };
+      if (!safeTarget) return { redirect: true, reason: "unsafe-target", status: res.status, location: cut(next.href, 120) };
+      if (!twin) return { redirect: true, reason: "off-host", status: res.status, location: cut(next.href, 120) };
       if (!redirectedFrom) redirectedFrom = url;
       url = next.href;
       continue;
@@ -137,6 +154,41 @@ function collectLinks(text) {
 // 2026-08-29). Bounding the quantifier would trade the speed bug for a silent accuracy bug,
 // so the scan is by index: every character is read once and the furthest failed target scan
 // is remembered.
+// CommonMark fenced code blocks, marked line by line. A "## " or a link inside a fence is
+// example text and not the file's own structure, but until 2026-09-10 both counted, so a
+// file whose only section and only link lived inside ``` or ~~~ was reported valid. The
+// scan is one pass over the lines with no backtracking pattern, because the ReDoS repair
+// of 2026-08-24 bought a worse accuracy defect with a bounded quantifier and the rule out
+// of it was to scan by index instead (mds/gotchas.md 2026-08-24 (jatko 12)).
+// Returns one boolean per line: true for a fence line and for everything inside it.
+function fenceMask(lines) {
+  const mask = new Array(lines.length).fill(false);
+  let fenceChar = "", fenceLen = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    let p = 0;
+    while (p < 4 && l[p] === " ") p++;
+    if (p > 3) { mask[i] = fenceChar !== ""; continue; }
+    const c = l[p];
+    let run = 0;
+    if (c === "`" || c === "~") { while (l[p + run] === c) run++; }
+    if (fenceChar === "") {
+      // An opening backtick fence may not carry a backtick in its info string; a tilde
+      // fence may. Anything shorter than three markers is not a fence at all. A later
+      // round will read the consequence as a bug and it is not: in ```js `x` the info
+      // string holds a backtick, so that line is prose, and a bare ``` after it OPENS a
+      // block instead of closing one. CommonMark reads the same input the same way,
+      // measured against the spec 2026-09-10. Leave it.
+      if (run >= 3 && (c !== "`" || l.indexOf("`", p + run) === -1)) {
+        fenceChar = c; fenceLen = run; mask[i] = true;
+      }
+      continue;
+    }
+    mask[i] = true;
+    if (c === fenceChar && run >= fenceLen && l.slice(p + run).trim() === "") { fenceChar = ""; fenceLen = 0; }
+  }
+  return mask;
+}
 function listItemHasLink(l) {
   const m = /^ {0,3}[-*+] /.exec(l);
   if (!m) return false;
@@ -203,25 +255,32 @@ export function validateLlmsTxt(f) {
   // indented code block rather than a heading, and trimming erased that difference, so
   // "    # Site" passed as the H1 until 2026-08-29. CommonMark allows three spaces.
   if (/^ {0,3}# \S/.test(firstRaw)) {
-    add("h1-title", "pass", "Starts with an H1 title", JSON.stringify(first.slice(0, 80)));
+    add("h1-title", "pass", "Starts with an H1 title", JSON.stringify(cut(first, 80)));
   } else {
     add("h1-title", "fail", "Starts with an H1 title", "the first non-empty line should be a markdown H1 (# Site name)");
   }
   const afterH1 = lines.slice(firstIdx + 1).find((l) => l.trim() !== "") || "";
   if (afterH1.trim().startsWith("> ")) {
-    add("summary", "pass", "Blockquote summary after the title", JSON.stringify(afterH1.trim().slice(0, 80)));
+    add("summary", "pass", "Blockquote summary after the title", JSON.stringify(cut(afterH1.trim(), 80)));
   } else {
     add("summary", "warn", "Blockquote summary after the title", "recommended by the format (> one-line summary), not required");
   }
-  const h2Count = (f.text.match(/^## /gm) || []).length;
+  // Headings are read outside fences only, and with the same indentation the H1 check and
+  // listItemHasLink have allowed since 2026-08-29. Until 2026-09-10 this one line still
+  // demanded column zero, so a correct file indented by one to three spaces was reported as
+  // having no sections at all while its list under the same indentation counted fine.
+  const fenced = fenceMask(lines);
+  const h2Count = lines.filter((l, i) => !fenced[i] && /^ {0,3}## /.test(l)).length;
   // A section counts when it carries a file list. An H2 followed by a paragraph satisfied
   // this check until 2026-08-29, and the format puts each section's links in a list.
   let sectionsWithList = 0;
   {
     let inSection = false, counted = false;
-    for (const l of lines) {
-      if (/^## /.test(l)) { inSection = true; counted = false; continue; }
-      if (/^# /.test(l)) { inSection = false; continue; }
+    for (let i = 0; i < lines.length; i++) {
+      const l = lines[i];
+      if (fenced[i]) continue;
+      if (/^ {0,3}## /.test(l)) { inSection = true; counted = false; continue; }
+      if (/^ {0,3}# /.test(l)) { inSection = false; continue; }
       if (inSection && !counted && listItemHasLink(l)) { sectionsWithList++; counted = true; }
     }
   }
@@ -232,7 +291,9 @@ export function validateLlmsTxt(f) {
   } else {
     add("sections", "warn", "H2 sections group the content", "no H2 sections found; sections are the convention for grouping links");
   }
-  const links = collectLinks(f.text);
+  // Links are collected from the prose only, for the same reason the headings are: a link
+  // shown inside a code fence is an example of a link, not one an agent can follow.
+  const links = collectLinks(lines.filter((l, i) => !fenced[i]).join("\n"));
   // An entry an agent can use has a name and a target with a host. An empty name and a
   // bare "https://" both counted as valid absolute links until 2026-08-29.
   const named = links.filter((m) => m.name.trim() !== "");
@@ -482,6 +543,122 @@ function* htmlTags(text) {
   }
 }
 
+// One forward scan over a tag's attributes, quote aware, first declaration wins, which is
+// what the HTML tokenizer does. A quoted value is opaque: nothing inside it is an
+// attribute name, which is the whole point of reading the tag this way. The quote opens
+// only directly after "=", the same rule tagEnd uses to find the end of the tag, so the
+// two agree on where a value starts and ends.
+function tagAttributes(tag) {
+  const out = {};
+  const space = " \t\n\r\f";
+  const n = tag.length;
+  const open = /^<[a-z0-9]*/i.exec(tag);
+  let i = open ? open[0].length : 0;
+  while (i < n) {
+    const c = tag[i];
+    if (c === ">") break;
+    if (space.includes(c) || c === "/") { i++; continue; }
+    const nameStart = i;
+    while (i < n && !space.includes(tag[i]) && tag[i] !== "/" && tag[i] !== "=" && tag[i] !== ">") i++;
+    const name = tag.slice(nameStart, i).toLowerCase();
+    while (i < n && space.includes(tag[i])) i++;
+    let value = "";
+    if (tag[i] === "=") {
+      i++;
+      while (i < n && space.includes(tag[i])) i++;
+      const q = tag[i];
+      if (q === '"' || q === "'") {
+        i++;
+        const valueStart = i;
+        while (i < n && tag[i] !== q) i++;
+        value = tag.slice(valueStart, i);
+        if (i < n) i++;
+      } else {
+        const valueStart = i;
+        while (i < n && !space.includes(tag[i]) && tag[i] !== ">") i++;
+        value = tag.slice(valueStart, i);
+      }
+    }
+    if (name && !(name in out)) out[name] = value;
+  }
+  return out;
+}
+
+// RFC 8288 section 3: a Link header is a comma separated list, each value an angle
+// bracketed URI reference followed by semicolon separated parameters, and a parameter
+// value may be a quoted string that contains commas, semicolons and backslash escapes.
+// Reading rel and type with one regex over the whole value read the CONTENT of
+// title="note; rel=alternate; type=text/markdown" as parameters of the link.
+function parseLinkHeader(header) {
+  const s = String(header || "");
+  const space = " \t";
+  const n = s.length;
+  const out = [];
+  let i = 0;
+  while (i < n) {
+    while (i < n && (s[i] === "," || space.includes(s[i]))) i++;
+    if (i >= n) break;
+    if (s[i] !== "<") { i = nextLinkValue(s, i); continue; }
+    const gt = s.indexOf(">", i + 1);
+    if (gt === -1) break;
+    const href = s.slice(i + 1, gt).trim();
+    i = gt + 1;
+    const params = {};
+    while (i < n) {
+      while (i < n && space.includes(s[i])) i++;
+      if (i >= n) break;
+      if (s[i] === ",") { i++; break; }
+      if (s[i] !== ";") { i = nextLinkValue(s, i); break; }
+      i++;
+      while (i < n && space.includes(s[i])) i++;
+      const nameStart = i;
+      while (i < n && s[i] !== "=" && s[i] !== ";" && s[i] !== "," && !space.includes(s[i])) i++;
+      const name = s.slice(nameStart, i).toLowerCase();
+      while (i < n && space.includes(s[i])) i++;
+      let value = "";
+      if (s[i] === "=") {
+        i++;
+        while (i < n && space.includes(s[i])) i++;
+        if (s[i] === '"') {
+          i++;
+          let buf = "";
+          while (i < n && s[i] !== '"') {
+            if (s[i] === "\\" && i + 1 < n) { buf += s[i + 1]; i += 2; continue; }
+            buf += s[i];
+            i++;
+          }
+          if (i < n) i++;
+          value = buf;
+        } else {
+          const valueStart = i;
+          while (i < n && s[i] !== ";" && s[i] !== "," && !space.includes(s[i])) i++;
+          value = s.slice(valueStart, i);
+        }
+      }
+      if (name && !(name in params)) params[name] = value;
+    }
+    out.push({ href: href, params: params });
+  }
+  return out;
+}
+
+// Move to the start of the next comma separated value without stopping inside a quoted
+// string, so a comma in title="a, b" does not split one value into two.
+function nextLinkValue(s, from) {
+  let quote = "";
+  for (let j = from; j < s.length; j++) {
+    const c = s[j];
+    if (quote) {
+      if (c === "\\") { j++; continue; }
+      if (c === quote) quote = "";
+      continue;
+    }
+    if (c === '"') { quote = c; continue; }
+    if (c === ",") return j + 1;
+  }
+  return s.length;
+}
+
 // v2 of the llms.txt proposal (August 2026) left the file format alone and added one
 // thing: a page should say where its markdown version and its llms.txt are, using
 // rel="alternate" type="text/markdown" and rel="describedby", as HTML link elements or
@@ -501,24 +678,26 @@ export function findLinkRelations(html, linkHeader) {
     // NAME is "link<link", not as a link element, so \b would count a relation the site
     // does not publish. Measured against parse5, 2026-08-24.
     if (!/^<link(?=[\s/>])/i.test(tag)) continue;
-    // The attribute name has to start the token. \b sits between the hyphen and the name,
-    // so data-rel, data-type and data-href were read as the real attributes until
-    // 2026-08-29, and a page could claim a relation it does not publish.
-    const rel = ((tag.match(/(?:^|[\s/])rel\s*=\s*["']?([^"'>]+)/i) || [])[1] || "").toLowerCase().trim().split(/\s+/);
-    const type = ((tag.match(/(?:^|[\s/])type\s*=\s*["']?([^"'>\s]+)/i) || [])[1] || "").toLowerCase();
-    const href = ((tag.match(/(?:^|[\s/])href\s*=\s*"([^"]*)"|(?:^|[\s/])href\s*=\s*'([^']*)'|(?:^|[\s/])href\s*=\s*([^\s"'>]+)/i) || []).slice(1).find((x) => x !== undefined) || "").trim();
+    // Attributes come from ONE quote aware scan, not from three independent regex matches
+    // over the whole tag. Those three could not tell an attribute from the quoted CONTENT
+    // of another attribute, so data-note=" rel='alternate' type='text/markdown'
+    // href='/fake.md'" reported a relation the page does not publish. The earlier
+    // data-rel fix, 2026-08-29, moved the START of the name and does not reach this.
+    // Measured and fixed 2026-09-09.
+    const attrs = tagAttributes(tag);
+    const rel = (attrs.rel || "").toLowerCase().trim().split(/\s+/);
+    const type = (attrs.type || "").toLowerCase().trim();
+    const href = (attrs.href || "").trim();
     // text/markdown, not anything that starts with it, and a relation without a target is
     // not a relation: both passed until 2026-08-29.
     const isMarkdown = type.split(";")[0].trim() === "text/markdown";
     if (!found.describedby && href && rel.includes("describedby")) found.describedby = href;
     if (!found.markdown && href && rel.includes("alternate") && isMarkdown) found.markdown = href;
   }
-  for (const part of String(linkHeader || "").split(/,(?=\s*<)/)) {
-    const lt = part.indexOf("<");
-    const gt = lt === -1 ? -1 : part.indexOf(">", lt + 1);
-    const href = (gt === -1 ? "" : part.slice(lt + 1, gt)).trim();
-    const rel = ((part.match(/(?:^|[;\s])rel\s*=\s*"?([^";,]+)"?/i) || [])[1] || "").toLowerCase().trim().split(/\s+/);
-    const type = ((part.match(/(?:^|[;\s])type\s*=\s*"?([^";,]+)"?/i) || [])[1] || "").toLowerCase().trim();
+  for (const link of parseLinkHeader(linkHeader)) {
+    const href = link.href;
+    const rel = (link.params.rel || "").toLowerCase().trim().split(/\s+/);
+    const type = (link.params.type || "").toLowerCase().trim();
     const isMarkdownHeader = type.split(";")[0].trim() === "text/markdown";
     if (!found.describedby && href && rel.includes("describedby")) found.describedby = href;
     if (!found.markdown && href && rel.includes("alternate") && isMarkdownHeader) found.markdown = href;
@@ -535,9 +714,9 @@ export function validateV2Discovery(found, unreadReason) {
     return checks;
   }
   add("v2-describedby", found.describedby ? "pass" : "info", "Home page points to its llms.txt (v2)",
-    found.describedby ? 'rel="describedby" to ' + found.describedby.slice(0, 120) : 'no rel="describedby" in the head or the Link header; v2 recommends it so an agent finds the file without guessing');
+    found.describedby ? 'rel="describedby" to ' + cut(found.describedby, 120) : 'no rel="describedby" in the head or the Link header; v2 recommends it so an agent finds the file without guessing');
   add("v2-markdown-alternate", found.markdown ? "pass" : "info", "Home page points to a markdown version (v2)",
-    found.markdown ? 'rel="alternate" type="text/markdown" to ' + found.markdown.slice(0, 120) : 'no rel="alternate" type="text/markdown" in the head or the Link header; v2 recommends it so an agent finds the markdown form without guessing');
+    found.markdown ? 'rel="alternate" type="text/markdown" to ' + cut(found.markdown, 120) : 'no rel="alternate" type="text/markdown" in the head or the Link header; v2 recommends it so an agent finds the markdown form without guessing');
   return checks;
 }
 
@@ -550,7 +729,7 @@ export function summarizeChecks(checks) {
 export async function validateHost(input, opts = {}) {
   const host = normalizeHostInput(input);
   if (!host || !isValidPublicHost(host)) {
-    throw new Error("not a public domain name: " + String(input).slice(0, 120));
+    throw new Error("not a public domain name: " + cut(input, 120));
   }
   // opts comes from the caller, and path and accept exist for this function's own
   // second read. Forwarding them to the first read would let a caller point the