@vibe-agent-toolkit/resources 0.1.39-rc.8 → 0.1.39

package/src/link-auth-content-fetch.ts

@@ -0,0 +1,146 @@
+/**
+ * Public content-fetch primitive for the linkAuth feature (design issue #113 §6.2).
+ *
+ * Ships as a standalone primitive — no consumer wiring (asset-references,
+ * bundling) lands in this slice. The shape and security disciplines are
+ * designed so future callers can adopt it without reworking the contract.
+ *
+ * Responsibility split:
+ *   - `resolveAuthenticatedUrl` (engine): pick provider, rewrite URL, resolve
+ *     token, expand auth.headers AND fetch.headers against the same context.
+ *   - `ContentCache`: persist `(bytes, metadata)` keyed by rewritten URL with
+ *     30-min default TTL; whitelists fields so tokens cannot be persisted.
+ *   - `authTransport`: cross-origin auth strip, 429/Retry-After handling.
+ *   - **This primitive**: wire them together, decide cache vs fetch, build
+ *     metadata, return a typed result.
+ *
+ * Behavior matrix:
+ *   - Engine returns `unsupported` → return as-is, no fetch, no cache touch.
+ *   - Engine returns `unverified` → return as-is, no fetch, **no cache touch**
+ *     even if a cache was supplied (§6.3: result flips when a token appears,
+ *     so caching the no-token answer would poison future runs).
+ *   - Engine returns success + cache present + not forceRefresh + cache hit →
+ *     return `{ bytes, metadata, cached: true }`, no fetch.
+ *   - Engine returns success otherwise → fetch via `authTransport` (using
+ *     `fetch.headers` merged over `auth.headers` when present), write to
+ *     cache if supplied, return `{ bytes, metadata, cached: false }`.
+ *
+ * **Throws** on network-level failures from the transport: DNS resolution
+ * failure, TLS handshake failure, connection refused, `AbortError` from the
+ * caller's `signal`, or any underlying `fetchImpl` rejection. The cache is
+ * only touched after the response body is fully read, so a transport failure
+ * cannot land a partial entry on disk. Consumers that need degradation
+ * semantics (validators, batch tools) should wrap calls in a try/catch.
+ *
+ * **Token never persisted.** Tokens are interpolated into headers in-memory;
+ * the metadata interface excludes header fields. The cache additionally
+ * whitelists the metadata fields it accepts. See cycle-6 token-persistence
+ * test for the on-disk assertion.
+ *
+ * **High-volume callers**: token resolution can be expensive (`gh auth token`
+ * spawns a subprocess). Callers iterating many URLs should wrap their `deps`
+ * once with `wrapLinkAuthDepsWithMemo` from `./link-auth-deps-memo.js` and
+ * pass the wrapped object to every invocation, so the same argv resolves at
+ * most once across the iteration.
+ */
+
+import { resolveAuthenticatedUrl, type LinkAuthConfig } from '@vibe-agent-toolkit/utils';
+
+import { type ContentCache, type ContentMetadata } from './content-cache.js';
+import { type LinkAuthDeps } from './link-auth-deps-memo.js';
+import { authTransport, type AuthTransportOptions } from './link-auth-transport.js';
+
+export interface FetchAuthenticatedOptions {
+  /** Content cache to read from and write to. Omit to skip caching entirely. */
+  readonly cache?: ContentCache;
+  /** Bypass cache reads (still writes through on success). Default: false. */
+  readonly forceRefresh?: boolean;
+  /** Test/DI hook. Default: `globalThis.fetch`. */
+  readonly fetchImpl?: typeof fetch;
+  /** Token-resolution dependencies (env map, runCommand). Default: engine defaults. */
+  readonly deps?: LinkAuthDeps;
+  /** Propagated to the transport — caller's per-request timeout budget. */
+  readonly signal?: AbortSignal;
+  /** Per-call overrides for the transport's redirect / retry caps. */
+  readonly transportOptions?: AuthTransportOptions;
+}
+
+export type ContentFetchResult =
+  | {
+      readonly bytes: Uint8Array;
+      readonly metadata: ContentMetadata;
+      readonly cached: boolean;
+    }
+  | { readonly outcome: 'unsupported' }
+  | { readonly outcome: 'unverified'; readonly reason: string };
+
+export async function fetchAuthenticated(
+  url: string,
+  config: LinkAuthConfig,
+  options: FetchAuthenticatedOptions = {},
+): Promise<ContentFetchResult> {
+  const plan = resolveAuthenticatedUrl(url, config, options.deps);
+  // Discriminate via Object.hasOwn (not `'fetchUrl' in plan`) so a prototype-
+  // injected `fetchUrl` field cannot reroute a non-success outcome onto the
+  // cache/fetch path. The engine controls plan shape — defending in depth.
+  if (!Object.hasOwn(plan, 'fetchUrl')) {
+    // unsupported / unverified — both short-circuit without fetch or cache.
+    const failure = plan as Exclude<typeof plan, { fetchUrl: string }>;
+    return failure.outcome === 'unverified'
+      ? { outcome: 'unverified', reason: failure.reason }
+      : { outcome: 'unsupported' };
+  }
+  const success = plan as Extract<typeof plan, { fetchUrl: string }>;
+
+  const cache = options.cache;
+  if (cache !== undefined && options.forceRefresh !== true) {
+    const hit = await cache.get(success.fetchUrl);
+    if (hit !== null) {
+      return { bytes: hit.bytes, metadata: hit.metadata, cached: true };
+    }
+  }
+
+  // Merge headers: start from auth (covers Authorization + check-mode Accept),
+  // layer fetch.headers on top (overrides on conflict — e.g. swap the GitHub
+  // Accept from +json to .raw). Both header objects come from the engine, so
+  // both have the resolved token baked in (§6.2 dual-expand).
+  const requestHeaders: Record<string, string> = {
+    ...success.headers,
+    ...(success.fetchHeaders ?? {}),
+  };
+
+  const transportOptions: AuthTransportOptions = {
+    ...(options.transportOptions ?? {}),
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+  };
+
+  const response = await authTransport(
+    success.fetchUrl,
+    requestHeaders,
+    options.fetchImpl ?? globalThis.fetch,
+    transportOptions,
+  );
+
+  // Read full body as bytes. We use arrayBuffer (binary-clean) and wrap into a
+  // fresh Uint8Array so the caller doesn't hold a view onto fetch's internal
+  // buffer.
+  const arrayBuffer = await response.arrayBuffer();
+  const bytes = new Uint8Array(arrayBuffer);
+
+  const metadata: ContentMetadata = {
+    status: response.status,
+    contentType: response.headers.get('content-type'),
+    etag: response.headers.get('etag'),
+    lastModified: response.headers.get('last-modified'),
+    fetchedAt: Date.now(),
+    rewrittenUrl: success.fetchUrl,
+  };
+
+  // Write-through. The ContentCache whitelists fields and fails soft on IO,
+  // so a write failure does not propagate.
+  if (cache !== undefined) {
+    await cache.set(success.fetchUrl, bytes, metadata);
+  }
+
+  return { bytes, metadata, cached: false };
+}

package/src/link-auth-deps-memo.ts

@@ -0,0 +1,56 @@
+/**
+ * Memoization wrapper for linkAuth `runCommand`-shaped token resolvers.
+ *
+ * Token resolution can be expensive — `gh auth token` spawns a subprocess on
+ * every call, env-source reads are cheap but consistent treatment is simpler
+ * to reason about — so the validator and the content-fetch primitive both
+ * wrap their `runCommand` once per session. Identical argv tuples return the
+ * cached result; distinct argv tuples are run independently.
+ *
+ * Lifetime of the memo is the lifetime of the returned `LinkAuthDeps` —
+ * one-per-session, never module-global. Callers that want a fresh resolve
+ * (e.g. token rotation between runs) construct a fresh validator / primitive
+ * call and get a fresh memo.
+ *
+ * Lifted out of `external-link-validator.ts` (where it shipped first in #125)
+ * so the slice-3 content-fetch primitive shares the same implementation —
+ * see CLAUDE.md "code duplication policy" (jscpd would flag a clone).
+ *
+ * Per design issue #113 review on PR #125 (memoize all token sources, not
+ * just `command` sources).
+ */
+
+import { defaultRunCommand, type resolveAuthenticatedUrl } from '@vibe-agent-toolkit/utils';
+
+/**
+ * Re-exposed deps type — the third argument to `resolveAuthenticatedUrl`.
+ * Mirrors the engine's `Partial<TokenResolutionDeps>` without importing the
+ * private type name.
+ */
+export type LinkAuthDeps = Parameters<typeof resolveAuthenticatedUrl>[2];
+
+/**
+ * Wrap a `LinkAuthDeps` so its `runCommand` (used by the engine's
+ * `resolveToken`) caches results per unique argv. Without this, validating N
+ * URLs from the same host re-runs the token command N times.
+ *
+ * Caches by JSON-stringified argv so semantically-identical invocations
+ * share. The cache is per-call-site (one Map per wrapper); callers that share
+ * across multiple `resolveAuthenticatedUrl` invocations should call this
+ * once and reuse the wrapped object.
+ */
+export function wrapLinkAuthDepsWithMemo(deps: LinkAuthDeps): NonNullable<LinkAuthDeps> {
+  type RunCommandFn = NonNullable<NonNullable<LinkAuthDeps>['runCommand']>;
+  type RunCommandResult = ReturnType<RunCommandFn>;
+  const memo = new Map<string, RunCommandResult>();
+  const baseRunCommand: RunCommandFn = deps?.runCommand ?? defaultRunCommand;
+  const runCommand: RunCommandFn = (argv) => {
+    const key = JSON.stringify(argv);
+    const cached = memo.get(key);
+    if (cached !== undefined) return cached;
+    const fresh = baseRunCommand(argv);
+    memo.set(key, fresh);
+    return fresh;
+  };
+  return { ...(deps ?? {}), runCommand };
+}

package/src/link-auth-transport.ts

@@ -0,0 +1,179 @@
+/**
+ * Auth-safe HTTP transport for the linkAuth feature (design issue #113 §5.2, §8).
+ *
+ * Lower-level than the public `fetchAuthenticated` primitive — this transport
+ * does not know about providers, token resolution, or caching. It takes a URL
+ * + already-built headers and adds two behaviors required by the design:
+ *
+ *   §8 (cross-origin token leak defense) — `redirect: 'manual'`, then a
+ *   bounded loop that follows Location headers. On any redirect to a
+ *   different origin the `Authorization` header is stripped and stays
+ *   stripped for subsequent hops (defeats token-laundering via a cross-origin
+ *   bounce back to the original host).
+ *
+ *   §5.2 (rate-limit handling) — on HTTP 429, parse `Retry-After` (seconds or
+ *   HTTP-date), wait, retry. Bounded by `maxRetries` so a stuck host cannot
+ *   hang validation; bounded by `maxRetryAfterMs` so a hostile or buggy host
+ *   cannot pin a validation run for an hour with `Retry-After: 86400`.
+ *
+ * Pure-ish: `fetchImpl` and `sleep` are dependency-injected so tests do not
+ * touch the network or wall-clock. Production callers pass `globalThis.fetch`.
+ */
+
+export interface AuthTransportOptions {
+  /** Maximum redirect hops to follow before returning the last 3xx response (default: 5). */
+  readonly maxRedirects?: number;
+  /** Maximum 429 retries before returning the final 429 response (default: 2). */
+  readonly maxRetries?: number;
+  /** Cap on Retry-After in ms; defends against hostile/buggy long values (default: 60_000). */
+  readonly maxRetryAfterMs?: number;
+  /** Abort signal propagated to every fetchImpl call (validator's per-request timeout budget). */
+  readonly signal?: AbortSignal;
+  /** Test-only sleep injection. Production callers omit. */
+  readonly sleep?: (ms: number) => Promise<void>;
+}
+
+const DEFAULT_MAX_REDIRECTS = 5;
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_MAX_RETRY_AFTER_MS = 60_000;
+/**
+ * Minimum delay between 429 retries. A hostile host can send `Retry-After: 0`
+ * (or an HTTP-date in the past, parsing to 0); without a floor, we'd retry
+ * immediately, which is worse-than-useless for the host's rate-limiting and
+ * makes us a poor neighbor. Bounded by `maxRetries` regardless, but the floor
+ * gives the host's window a chance to slide.
+ */
+const MIN_RETRY_AFTER_MS = 250;
+
+const defaultSleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+
+/**
+ * Parse a `Retry-After` header value into milliseconds-to-wait.
+ *
+ * Returns `null` when the value is missing, empty, negative, or unparseable —
+ * callers treat `null` as "don't retry" (we can't pick a delay without a hint).
+ * HTTP-date values in the past return `0` (the server's hint is "you can retry
+ * now"). RFC 7231 §7.1.3.
+ */
+export function parseRetryAfter(value: string | null): number | null {
+  if (value === null) return null;
+  const trimmed = value.trim();
+  if (trimmed === '') return null;
+
+  // delta-seconds form: positive integer count of seconds.
+  if (/^\d+$/.test(trimmed)) {
+    return Number(trimmed) * 1000;
+  }
+
+  // HTTP-date form per RFC 7231 §7.1.1.1 — always contains weekday and month
+  // names. Guard with /[A-Za-z]/ because Date.parse() is permissive: '-5'
+  // parses as year-5 BC, '0' as 1 BC, etc. Requiring at least one letter
+  // restricts us to real HTTP-date strings.
+  if (!/[A-Za-z]/.test(trimmed)) return null;
+  const parsedMs = Date.parse(trimmed);
+  if (!Number.isFinite(parsedMs)) return null;
+  return Math.max(0, parsedMs - Date.now());
+}
+
+export async function authTransport(
+  url: string,
+  headers: Record<string, string>,
+  fetchImpl: typeof fetch,
+  options: AuthTransportOptions = {},
+): Promise<Response> {
+  const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const maxRetryAfterMs = options.maxRetryAfterMs ?? DEFAULT_MAX_RETRY_AFTER_MS;
+  const sleep = options.sleep ?? defaultSleep;
+
+  let currentUrl = url;
+  let currentHeaders: Record<string, string> = { ...headers };
+  let redirects = 0;
+  let retries = 0;
+
+  // Bounded loop: every iteration either returns or strictly advances one of
+  // (retries, redirects), both capped, so termination is guaranteed within
+  // `maxRetries + maxRedirects + 1` fetchImpl calls.
+  while (redirects + retries < maxRedirects + maxRetries + 1) {
+    const init: RequestInit = {
+      headers: currentHeaders,
+      redirect: 'manual',
+    };
+    if (options.signal !== undefined) init.signal = options.signal;
+
+    const response = await fetchImpl(currentUrl, init);
+
+    const retryDelay =
+      retries < maxRetries ? computeRetryDelay(response, maxRetryAfterMs) : null;
+    if (retryDelay !== null) {
+      await sleep(retryDelay);
+      retries++;
+      continue;
+    }
+
+    if (redirects < maxRedirects) {
+      const next = computeRedirect(response, currentUrl, currentHeaders);
+      if (next !== null) {
+        currentUrl = next.url;
+        currentHeaders = next.headers;
+        redirects++;
+        continue;
+      }
+    }
+
+    return response;
+  }
+  // Unreachable: the loop returns or continues on every iteration, and the
+  // loop condition strictly bounds total iterations.
+  throw new Error('authTransport: unreachable iteration cap exceeded');
+}
+
+/**
+ * Decide the wait-time for a 429 response, or `null` if the response is not
+ * a 429 OR has no parseable Retry-After hint (no hint → caller returns the 429
+ * rather than retrying blindly).
+ */
+function computeRetryDelay(response: Response, maxRetryAfterMs: number): number | null {
+  if (response.status !== 429) return null;
+  const retryAfter = parseRetryAfter(response.headers.get('retry-after'));
+  if (retryAfter === null) return null;
+  // Two-sided clamp: never longer than the DoS cap, never shorter than the
+  // good-neighbor floor (defends against `Retry-After: 0` busy-loops).
+  return Math.min(Math.max(retryAfter, MIN_RETRY_AFTER_MS), maxRetryAfterMs);
+}
+
+/**
+ * Decide the next hop for a 3xx redirect, or `null` if the response is not a
+ * redirect / has no Location. Strips Authorization on cross-origin per §8.
+ */
+function computeRedirect(
+  response: Response,
+  currentUrl: string,
+  currentHeaders: Record<string, string>,
+): { url: string; headers: Record<string, string> } | null {
+  if (response.status < 300 || response.status >= 400) return null;
+  const location = response.headers.get('location');
+  if (location === null) return null;
+  const nextUrl = new URL(location, currentUrl).toString();
+  const sameOrigin = new URL(nextUrl).origin === new URL(currentUrl).origin;
+  return {
+    url: nextUrl,
+    headers: sameOrigin ? currentHeaders : stripAuthorization(currentHeaders),
+  };
+}
+
+/**
+ * Remove any header whose name is `Authorization` (case-insensitive). Returns
+ * a new object — does not mutate the input.
+ */
+function stripAuthorization(headers: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() === 'authorization') continue;
+    result[name] = value;
+  }
+  return result;
+}

package/src/link-parser.ts

@@ -211,8 +211,15 @@ export function classifyLink(href: string): LinkType {
   if (href.startsWith('#')) {
     return 'anchor';
   }
+  // Self-contained inline resources: a data: URI embeds its payload and a blob:
+  // URL references an in-memory object. Neither has a target to fetch or an
+  // anchor to resolve, so they are valid-but-nothing-to-validate (skipped), not
+  // "unknown". Common in HTML (inline SVG/PNG/GIF logos).
+  if (href.startsWith('data:') || href.startsWith('blob:')) {
+    return 'embedded';
+  }
   // Any remaining href containing ':' is a protocol-like pattern we don't recognise
-  // (e.g., javascript:, tel:, data:, ftp:) — classify as unknown rather than local file
+  // (e.g., javascript:, tel:, ftp:) — classify as unknown rather than local file
   if (href.includes(':')) {
     return 'unknown';
   }

package/src/link-validator.ts

@@ -59,6 +59,8 @@ export interface ValidateLinkOptions {
   skipGitIgnoreCheck?: boolean;
   /** Git tracker for efficient git-ignore checking (optional, improves performance) */
   gitTracker?: GitTracker;
+  /** Strictly resolve HTML fragment anchors against element ids/names (default: false). HTML fragments are often runtime-defined by JS, so a static miss is not proof of breakage. */
+  checkHtmlAnchors?: boolean;
 }
 
 /**
@@ -93,7 +95,7 @@ export async function validateLink(
       return await validateLocalFileLink(link, sourceFilePath, fragmentsByFile, options);
 
     case 'anchor':
-      return await validateAnchorLink(link, sourceFilePath, fragmentsByFile, options?.projectRoot);
+      return await validateAnchorLink(link, sourceFilePath, fragmentsByFile, options);
 
     case 'external':
       // External URLs are not validated - don't report them
@@ -103,6 +105,11 @@ export async function validateLink(
       // Email links are valid by default
       return null;
 
+    case 'embedded':
+      // Self-contained inline resources (data:/blob:) have no target to
+      // validate — valid by default, don't report them.
+      return null;
+
     case 'unknown':
       return createRegistryIssue(
         'LINK_UNKNOWN',
@@ -251,7 +258,12 @@ async function validateLocalFileLink(
   if (gitIgnoreIssue) return gitIgnoreIssue;
 
   if (resolved.anchor) {
-    const check = checkAnchor(resolved.anchor, fileResult.resolvedPath, fragmentsByFile);
+    const check = checkAnchor(
+      resolved.anchor,
+      fileResult.resolvedPath,
+      fragmentsByFile,
+      options?.checkHtmlAnchors ?? false,
+    );
     if (check === 'broken') {
       return createRegistryIssue(
         'LINK_BROKEN_ANCHOR',
@@ -279,13 +291,13 @@ async function validateAnchorLink(
   link: ResourceLink,
   sourceFilePath: string,
   fragmentsByFile: FragmentIndex,
-  projectRoot?: string,
+  options?: ValidateLinkOptions,
 ): Promise<ValidationIssue | null> {
   // Extract anchor (strip leading #)
   const anchor = link.href.startsWith('#') ? link.href.slice(1) : link.href;
 
   // Validate anchor exists in current file
-  const check = checkAnchor(anchor, sourceFilePath, fragmentsByFile);
+  const check = checkAnchor(anchor, sourceFilePath, fragmentsByFile, options?.checkHtmlAnchors ?? false);
 
   switch (check) {
     case 'skip':
@@ -295,7 +307,7 @@ async function validateAnchorLink(
       return createRegistryIssue(
         'LINK_BROKEN_ANCHOR',
         `Anchor not found: ${link.href}`,
-        linkExtras(link, sourceFilePath, projectRoot, ''),
+        linkExtras(link, sourceFilePath, options?.projectRoot, ''),
       );
     default:
       return assertNever(check);
@@ -383,37 +395,73 @@ export function fragmentIndex(entries: Iterable<readonly [string, Set<string>]>
   return map;
 }
 
+/**
+ * Whether an HTML fragment is a structural, non-anchor hash: an SPA route
+ * (`#/route`) or a hash-encoded param string (`#id=1&mode=x`). Neither is
+ * ever a literal element id, regardless of `checkHtmlAnchors`.
+ */
+function isStructuralHtmlFragment(anchor: string): boolean {
+  return anchor.startsWith('/') || anchor.includes('=') || anchor.includes('&');
+}
+
+/**
+ * Resolve an HTML-target anchor. Isolated from {@link checkAnchor} to keep
+ * cognitive complexity down.
+ *
+ * - Empty fragment / `top` (case-insensitive) — always `'valid'` (HTML
+ *   top-navigation rule).
+ * - Structural non-anchor (`#/route`, `#k=v`, `#k=v&j=w`) — always `'skip'`;
+ *   these are never element ids, so there is nothing to resolve.
+ * - `checkHtmlAnchors === false` (default) — `'skip'`: HTML fragments are
+ *   frequently defined at runtime by JS (hash routers, hash query-params),
+ *   so the static id/name set in the source HTML is not authoritative.
+ * - `checkHtmlAnchors === true` — resolve against the indexed ids/names
+ *   (case-sensitive).
+ */
+function checkHtmlAnchor(
+  anchor: string,
+  entry: FragmentIndexEntry,
+  checkHtmlAnchors: boolean,
+): AnchorCheck {
+  if (anchor === '' || anchor.toLowerCase() === 'top') {
+    return 'valid';
+  }
+  if (isStructuralHtmlFragment(anchor)) {
+    return 'skip';
+  }
+  if (!checkHtmlAnchors) {
+    return 'skip';
+  }
+  return entry.fragments.has(anchor) ? 'valid' : 'broken';
+}
+
 /**
  * Check whether a fragment exists in the target file's anchor set.
  *
  * - `'skip'`  — target file is not indexed; we cannot prove the anchor is
  *   broken, so callers must not emit an issue.
- * - Matching follows the entry's `caseSensitive` policy (HTML ids exact,
- *   markdown slugs case-folded). The index carries the policy, so this never
- *   re-derives the folding rule from the file extension.
- * - For HTML targets the empty fragment (`#`) and `top` (ASCII
- *   case-insensitive) are always valid: per the HTML fragment-navigation
- *   algorithm both scroll to the top of the document regardless of whether a
- *   matching element exists, so `href="#"` / `href="#top"` are not broken.
+ * - HTML targets are delegated to {@link checkHtmlAnchor} (top-navigation
+ *   rule, structural non-anchors, and the `checkHtmlAnchors` opt-in gate).
+ * - Markdown targets resolve against the indexed heading slugs, case-folded.
  *
  * @param anchor - Fragment without the leading `#`.
  * @param targetFilePath - Absolute path of the file the fragment lives in.
  * @param fragmentsByFile - Fragment index carrying each file's matching policy.
+ * @param checkHtmlAnchors - Strictly resolve HTML fragments against indexed
+ *   element ids/names (default: false — see {@link checkHtmlAnchor}).
  */
 export function checkAnchor(
   anchor: string,
   targetFilePath: string,
   fragmentsByFile: FragmentIndex,
+  checkHtmlAnchors = false,
 ): AnchorCheck {
   const entry = fragmentsByFile.get(targetFilePath);
   if (!entry) {
     return 'skip';
   }
-  // HTML spec: the empty fragment and "top" (case-insensitive) always navigate
-  // to the top of the document — valid even with no matching id. This is an
-  // HTML-format navigation rule, distinct from the case-folding policy above.
-  if (isHtmlPath(targetFilePath) && (anchor === '' || anchor.toLowerCase() === 'top')) {
-    return 'valid';
+  if (isHtmlPath(targetFilePath)) {
+    return checkHtmlAnchor(anchor, entry, checkHtmlAnchors);
   }
   const found = entry.caseSensitive
     ? entry.fragments.has(anchor)

package/src/resource-registry.ts

@@ -23,6 +23,7 @@ import {
 } from './frontmatter-link-validator.js';
 import { validateFrontmatter } from './frontmatter-validator.js';
 import { parseHtml } from './html-link-parser.js';
+import { buildLinkAuthEngineConfig } from './link-auth-config-build.js';
 import { parseMarkdown } from './link-parser.js';
 import { fragmentIndexEntry, validateLink, type FragmentIndex, type ValidateLinkOptions } from './link-validator.js';
 import type { ResourceCollectionInterface } from './resource-collection-interface.js';
@@ -93,6 +94,8 @@ export interface ValidateOptions {
   validationMode?: 'strict' | 'permissive';
   /** Check external URLs for validity (default: false) */
   checkExternalUrls?: boolean;
+  /** Strictly validate HTML fragment anchors against element ids (default: false; HTML fragments are often runtime-defined by JS). */
+  checkHtmlAnchors?: boolean;
   /** Disable cache for external URL checks (default: false) */
   noCache?: boolean;
   /**
@@ -527,7 +530,8 @@ export class ResourceRegistry implements ResourceCollectionInterface {
    */
   private async validateAllLinks(
     fragmentsByFile: FragmentIndex,
-    skipGitIgnoreCheck: boolean
+    skipGitIgnoreCheck: boolean,
+    checkHtmlAnchors: boolean
   ): Promise<ValidationIssue[]> {
     const issues: ValidationIssue[] = [];
 
@@ -535,10 +539,11 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       for (const link of resource.links) {
         // Only pass options if projectRoot is defined (exactOptionalPropertyTypes requirement)
         const validateOptions = this.baseDir === undefined
-          ? { skipGitIgnoreCheck }
+          ? { skipGitIgnoreCheck, checkHtmlAnchors }
           : {
               projectRoot: this.baseDir,
               skipGitIgnoreCheck,
+              checkHtmlAnchors,
               ...(this.gitTracker !== undefined && { gitTracker: this.gitTracker })
             };
 
@@ -775,7 +780,8 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     // Validate each link in each resource
     const linkIssues = await this.validateAllLinks(
       fragmentsByFile,
-      options?.skipGitIgnoreCheck ?? false
+      options?.skipGitIgnoreCheck ?? false,
+      options?.checkHtmlAnchors ?? false
     );
     issues.push(...linkIssues);
 
@@ -838,10 +844,20 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     // Determine cache directory
     const cacheDir = this.getCacheDirectory();
 
+    // Expand any `resources.linkAuth` providers from macro refs into the engine
+    // shape (#113 §5). When the adopter has no linkAuth config, the validator
+    // skips the authenticated branch and uses the existing markdown-link-check
+    // path for every URL — identical to pre-#113 behavior.
+    const adopterLinkAuth = this.config?.resources?.linkAuth;
+    const linkAuthConfig = adopterLinkAuth
+      ? buildLinkAuthEngineConfig(adopterLinkAuth)
+      : undefined;
+
     // Create validator
     const validator = new ExternalLinkValidator(cacheDir, {
       timeout: 15000,
       cacheTtlHours: noCache ? 0 : 24,
+      ...(linkAuthConfig !== undefined && { linkAuthConfig }),
     });
 
     // Collect all external URLs from all resources
@@ -911,7 +927,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
    * @private
    */
   private convertValidationResultsToIssues(
-    results: Array<{ url: string; status: 'ok' | 'error'; statusCode: number; error?: string }>,
+    results: Array<{ url: string; status: 'ok' | 'error'; statusCode: number; error?: string; code?: IssueCode }>,
     urlsToValidate: Map<string, Array<{ resourcePath: string; line?: number }>>,
   ): ValidationIssue[] {
     const issues: ValidationIssue[] = [];
@@ -926,7 +942,11 @@ export class ResourceRegistry implements ResourceCollectionInterface {
         continue;
       }
 
-      const issueCode = this.determineExternalUrlIssueCode(result.statusCode, result.error);
+      // Prefer a code surfaced by the validator's authenticated branch (#113 §7) —
+      // those LINK_AUTH_* codes encode per-provider notFoundMeaning routing that
+      // statusCode alone cannot express. Fall back to the statusCode mapping for
+      // the anonymous markdown-link-check path.
+      const issueCode = result.code ?? this.determineExternalUrlIssueCode(result.statusCode, result.error);
       const errorMessage = result.error ?? `HTTP ${result.statusCode}`;
 
       for (const location of locations) {