@vibe-agent-toolkit/resources 0.1.39-rc.13 → 0.1.39-rc.14

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/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';
@@ -838,10 +839,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 +922,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 +937,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) {

package/src/schemas/link-auth.ts

@@ -3,24 +3,26 @@
  *
  * Validates the shape of an adopter's linkAuth configuration: providers
  * (each either a `use: <macro>` reference or a full inline provider) plus
- * an optional cache config. Strict — typos in provider field names are
- * errors, per Postel's law ("writing our output → conservative").
+ * an optional cache config. **Passthrough** — per the repo Postel's Law
+ * rule, schemas that parse external data (adopter `vibe-agent-toolkit.config.yaml`)
+ * are liberal: unknown fields pass through rather than abort the parse, so
+ * an adopter with a forward-compatible field or a typo gets `vat resources
+ * validate` degrading gracefully instead of crashing. Typo-catching DX is
+ * a separate lint/warn pass, not a hard parse failure.
  *
  * Provider entries accept EITHER:
  *   - `{ use: <name>, ...overrides }` — reference a shipped macro by name;
- *     override fields are deep-merged on top at expansion time. Overrides
- *     are NOT strictly typed at this layer because they must match the
- *     macro's shape, which we cannot see until expansion. A typo in an
- *     override silently no-ops; the full provider shape is validated
- *     after expansion (slice 2 wires that).
- *   - A full inline `{ match, rewrite, auth, token, check }` — every field
- *     required, every nested object strict.
+ *     override fields are deep-merged on top at expansion time.
+ *   - A full inline `{ match, rewrite, auth, token, check }` — every required
+ *     field present, with declared-field types still enforced (passthrough
+ *     only relaxes unknown-key handling, not type checking on known fields).
  *
  * Mirrors the runtime types in `@vibe-agent-toolkit/utils`'s `link-auth/`
  * module. Keep these aligned: a config that parses here must satisfy the
  * `Provider` / `LinkAuthConfig` interfaces over there.
  *
- * Per design issue #113 §4 (vocabulary) and §5 (macros).
+ * Per design issue #113 §4 (vocabulary) and §5 (macros), and the repo
+ * CLAUDE.md Postel's Law rule for adopter-facing configs.
  */
 
 import { z } from 'zod';
@@ -37,7 +39,7 @@ export const ProviderMatchSchema = z
       .optional()
       .describe('Globs that, if any match the hostname, exclude this provider'),
   })
-  .strict()
+  .passthrough()
   .describe('Provider selection — match.host + optional excludeHost globs');
 
 export const RewriteRuleSchema = z
@@ -49,7 +51,7 @@ export const RewriteRuleSchema = z
       .describe('Computed variables, each a template that references captures from `when`'),
     to: z.string().min(1).describe('URL template — interpolates ${capture} and ${var}'),
   })
-  .strict()
+  .passthrough()
   .describe('A single rewrite rule (one entry in a provider\'s ordered rewrite list)');
 
 export const ProviderAuthSchema = z
@@ -58,17 +60,32 @@ export const ProviderAuthSchema = z
       .record(z.string(), z.string())
       .describe('Header name → value template. Values interpolate ${token} and any capture/var.'),
   })
-  .strict()
+  .passthrough()
   .describe('Auth headers attached to the authenticated fetch');
 
+/**
+ * Optional fetch-mode header overrides (§6.2). Same shape as ProviderAuth,
+ * different role: `auth.headers` covers the health-check request; `fetch.headers`
+ * covers content retrieval (e.g. GitHub `application/vnd.github.raw` instead of
+ * `application/vnd.github+json`). Both templates expand against the same context.
+ */
+export const ProviderFetchSchema = z
+  .object({
+    headers: z
+      .record(z.string(), z.string())
+      .describe('Header name → value template, same templating as auth.headers.'),
+  })
+  .passthrough()
+  .describe('Optional content-fetch header overrides — distinct from health-check headers');
+
 export const TokenSourceSchema = z
   .union([
-    z.object({ env: z.string().min(1) }).strict(),
+    z.object({ env: z.string().min(1) }).passthrough(),
     z
       .object({
         command: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]),
       })
-      .strict(),
+      .passthrough(),
   ])
   .describe('A single token source — env var, or argv command (preferred), or convenience string');
 
@@ -85,22 +102,25 @@ export const ProviderCheckSchema = z
         'Per-host: does 404 mean "dead" (honest 404 host like Graph) or "ambiguous" (masking host like GitHub)?',
       ),
   })
-  .strict()
+  .passthrough()
   .describe('Status-to-outcome classifier (consumed by the resources layer, not the pure engine)');
 
 // ---------------------------------------------------------------------------
 // Provider entry (inline OR macro reference)
 // ---------------------------------------------------------------------------
 
-const InlineProviderSchema = z
+export const InlineProviderSchema = z
   .object({
     match: ProviderMatchSchema,
     rewrite: z.array(RewriteRuleSchema).min(1).describe('Ordered rewrite rules — first matching wins'),
     auth: ProviderAuthSchema,
+    fetch: ProviderFetchSchema
+      .optional()
+      .describe('Optional fetch-mode header override (§6.2) — content retrieval, distinct from health-check'),
     token: z.array(TokenSourceSchema).describe('Ordered token sources — first non-empty wins'),
     check: ProviderCheckSchema,
   })
-  .strict();
+  .passthrough();
 
 const MacroProviderSchema = z
   .object({
@@ -128,7 +148,7 @@ export const LinkAuthCacheSchema = z
       .optional()
       .describe('Content cache TTL in minutes (default 30 — used by slice 3 content-fetch)'),
   })
-  .strict();
+  .passthrough();
 
 export const LinkAuthConfigSchema = z
   .object({
@@ -137,10 +157,16 @@ export const LinkAuthConfigSchema = z
       .array(ProviderEntrySchema)
       .describe('Ordered list of providers — first claiming-by-host wins'),
   })
-  .strict()
+  .passthrough()
   .describe('`resources.linkAuth` — authenticated external link resolution config');
 
-export type LinkAuthConfig = z.infer<typeof LinkAuthConfigSchema>;
+/**
+ * Adopter-facing config shape — what an `vibe-agent-toolkit.config.yaml`
+ * parses to. Distinct from `@vibe-agent-toolkit/utils`'s `LinkAuthConfig`
+ * (the engine shape, with fully-expanded providers only). The bridge
+ * function `buildLinkAuthEngineConfig` converts between the two.
+ */
+export type LinkAuthProjectConfig = z.infer<typeof LinkAuthConfigSchema>;
 export type ProviderEntry = z.infer<typeof ProviderEntrySchema>;
 export type RewriteRule = z.infer<typeof RewriteRuleSchema>;
 export type TokenSource = z.infer<typeof TokenSourceSchema>;