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

package/dist/content-cache.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Per-entry content cache for the linkAuth content-fetch primitive (design
+ * issue #113 §6.2 + §6.3).
+ *
+ * Layout: under `cacheDir/` each entry is two files keyed by `sha256(url).hex`:
+ *   - `<hash>.json` — metadata (status, content-type, etag/last-modified,
+ *                     fetchedAt, rewrittenUrl, schema version)
+ *   - `<hash>.bin`  — raw response bytes, binary-clean
+ *
+ * The split lets one entry read load only what we need: metadata for the
+ * TTL/version check, then the bytes only on a hit. A single-JSON layout would
+ * have meant base64-encoding bytes (~33% bloat) and reparsing every entry on
+ * every lookup. Two-file layout pays one extra `open()` per hit and scales
+ * better as content size grows.
+ *
+ * **Cross-user isolation is the caller's job** (§6.3) — pass a cacheDir
+ * already scoped to the OS user (e.g. `<cacheDir>/content/auth-<osUser>/`).
+ * The cache class itself only knows about the directory it was given.
+ *
+ * **TTL** defaults to 30 minutes per §6.3. The content-fetch primitive's
+ * `forceRefresh` option bypasses the cache; this class has no `clear()` —
+ * stale entries fall out naturally on TTL expiry, and `forceRefresh` covers
+ * "I authenticated as the wrong identity" per §6.3.
+ *
+ * **Fail-soft IO** per #125 review: ENOENT/EACCES/EROFS/corrupted-JSON all
+ * degrade to a miss (for reads) or a no-op (for writes). A non-persisted
+ * entry costs an extra fetch on the next run; an exception costs the whole
+ * current run.
+ *
+ * **Strict metadata shape**: `set()` writes only declared `ContentMetadata`
+ * fields, even if the caller passes structurally-typed extras. The fetch
+ * primitive is the authority on what may be persisted, and a cache that
+ * silently passes through unknown fields could leak a token value if the
+ * primitive (or future code) ever forgot.
+ */
+export interface ContentMetadata {
+    readonly status: number;
+    readonly contentType: string | null;
+    readonly etag: string | null;
+    readonly lastModified: string | null;
+    /** Epoch ms when the response was received (used for TTL evaluation). */
+    readonly fetchedAt: number;
+    /** The rewritten URL the bytes were fetched from (§6.3 cache-key discipline). */
+    readonly rewrittenUrl: string;
+}
+export interface ContentCacheEntry {
+    readonly bytes: Uint8Array;
+    readonly metadata: ContentMetadata;
+}
+export declare class ContentCache {
+    private readonly cacheDir;
+    private readonly ttlMs;
+    /**
+     * @param cacheDir - Already-OS-user-scoped directory for entries. Caller
+     *   builds this; the class does not know about users or scoping.
+     * @param ttlMinutes - Time-to-live in minutes. Defaults to the §6.3 30-min
+     *   "session" window.
+     */
+    constructor(cacheDir: string, ttlMinutes?: number);
+    get(url: string): Promise<ContentCacheEntry | null>;
+    set(url: string, bytes: Uint8Array, metadata: ContentMetadata): Promise<void>;
+    private keyFor;
+    private isExpired;
+    private readMetadata;
+    private readBytes;
+}
+//# sourceMappingURL=content-cache.d.ts.map

package/dist/content-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-cache.d.ts","sourceRoot":"","sources":["../src/content-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAiBH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAMD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;;;OAKG;gBACS,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAE,MAA4B;IAKhE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAqBnD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCnF,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,SAAS;YAIH,YAAY;YAYZ,SAAS;CAWxB"}

package/dist/content-cache.js

@@ -0,0 +1,160 @@
+/**
+ * Per-entry content cache for the linkAuth content-fetch primitive (design
+ * issue #113 §6.2 + §6.3).
+ *
+ * Layout: under `cacheDir/` each entry is two files keyed by `sha256(url).hex`:
+ *   - `<hash>.json` — metadata (status, content-type, etag/last-modified,
+ *                     fetchedAt, rewrittenUrl, schema version)
+ *   - `<hash>.bin`  — raw response bytes, binary-clean
+ *
+ * The split lets one entry read load only what we need: metadata for the
+ * TTL/version check, then the bytes only on a hit. A single-JSON layout would
+ * have meant base64-encoding bytes (~33% bloat) and reparsing every entry on
+ * every lookup. Two-file layout pays one extra `open()` per hit and scales
+ * better as content size grows.
+ *
+ * **Cross-user isolation is the caller's job** (§6.3) — pass a cacheDir
+ * already scoped to the OS user (e.g. `<cacheDir>/content/auth-<osUser>/`).
+ * The cache class itself only knows about the directory it was given.
+ *
+ * **TTL** defaults to 30 minutes per §6.3. The content-fetch primitive's
+ * `forceRefresh` option bypasses the cache; this class has no `clear()` —
+ * stale entries fall out naturally on TTL expiry, and `forceRefresh` covers
+ * "I authenticated as the wrong identity" per §6.3.
+ *
+ * **Fail-soft IO** per #125 review: ENOENT/EACCES/EROFS/corrupted-JSON all
+ * degrade to a miss (for reads) or a no-op (for writes). A non-persisted
+ * entry costs an extra fetch on the next run; an exception costs the whole
+ * current run.
+ *
+ * **Strict metadata shape**: `set()` writes only declared `ContentMetadata`
+ * fields, even if the caller passes structurally-typed extras. The fetch
+ * primitive is the authority on what may be persisted, and a cache that
+ * silently passes through unknown fields could leak a token value if the
+ * primitive (or future code) ever forgot.
+ */
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { safePath } from '@vibe-agent-toolkit/utils';
+/**
+ * Cache schema version. Bump when `ContentMetadata` or the on-disk layout
+ * changes. Entries with a missing or non-matching version are read as a miss
+ * (rather than misparsed) — the next fetch repopulates them under the new
+ * schema.
+ */
+const CACHE_VERSION = 1;
+const DEFAULT_TTL_MINUTES = 30;
+export class ContentCache {
+    cacheDir;
+    ttlMs;
+    /**
+     * @param cacheDir - Already-OS-user-scoped directory for entries. Caller
+     *   builds this; the class does not know about users or scoping.
+     * @param ttlMinutes - Time-to-live in minutes. Defaults to the §6.3 30-min
+     *   "session" window.
+     */
+    constructor(cacheDir, ttlMinutes = DEFAULT_TTL_MINUTES) {
+        this.cacheDir = cacheDir;
+        this.ttlMs = ttlMinutes * 60 * 1000;
+    }
+    async get(url) {
+        const key = this.keyFor(url);
+        const jsonPath = safePath.join(this.cacheDir, `${key}.json`);
+        const binPath = safePath.join(this.cacheDir, `${key}.bin`);
+        const stored = await this.readMetadata(jsonPath);
+        if (stored === null)
+            return null;
+        if (stored.version !== CACHE_VERSION)
+            return null;
+        if (this.isExpired(stored))
+            return null;
+        const bytes = await this.readBytes(binPath);
+        if (bytes === null)
+            return null;
+        // Strip the version field — that is an on-disk concern, not part of
+        // the caller-facing `ContentMetadata` contract.
+        return {
+            bytes,
+            metadata: pickMetadata(stored),
+        };
+    }
+    async set(url, bytes, metadata) {
+        const key = this.keyFor(url);
+        const jsonPath = safePath.join(this.cacheDir, `${key}.json`);
+        const binPath = safePath.join(this.cacheDir, `${key}.bin`);
+        // Whitelist exactly the declared ContentMetadata fields — defense in depth
+        // against a caller that smuggles extra structurally-typed fields, so a
+        // future regression in the primitive cannot accidentally persist a token
+        // through this cache.
+        const stored = { ...pickMetadata(metadata), version: CACHE_VERSION };
+        try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- cacheDir is constructor parameter, controlled by caller
+            await fs.mkdir(this.cacheDir, { recursive: true });
+            // Write order matters: .bin first, then .json. The reader checks .json
+            // first (version + TTL); a partially-written entry where .bin lands but
+            // .json doesn't reads as a miss (no .json). The hazard we are avoiding
+            // is the reverse — a fresh .json with a stale .bin from a prior set()
+            // for the same URL would serve old bytes under new metadata. Writing
+            // .json second guarantees that whenever .json reflects the new entry,
+            // .bin already does too.
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- binPath derived from cacheDir
+            await fs.writeFile(binPath, Buffer.from(bytes));
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- jsonPath derived from cacheDir
+            await fs.writeFile(jsonPath, JSON.stringify(stored), 'utf-8');
+        }
+        catch {
+            // Fail-soft per #125 review: a write IO failure (EACCES on the dir,
+            // ENOSPC on the disk, EROFS on read-only mounts) becomes a no-op. The
+            // current run still has the fresh bytes; only the disk persistence is
+            // lost.
+        }
+    }
+    keyFor(url) {
+        return createHash('sha256').update(url).digest('hex');
+    }
+    isExpired(stored) {
+        return Date.now() - stored.fetchedAt > this.ttlMs;
+    }
+    async readMetadata(jsonPath) {
+        try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- jsonPath derived from cacheDir
+            const raw = await fs.readFile(jsonPath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            // ENOENT (never written), EACCES (perms revoked), SyntaxError
+            // (corrupted JSON) — all degrade to a miss. The next fetch repopulates.
+            return null;
+        }
+    }
+    async readBytes(binPath) {
+        try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- binPath derived from cacheDir
+            const buf = await fs.readFile(binPath);
+            // Return a fresh Uint8Array view that does not alias the Node Buffer's
+            // underlying ArrayBuffer slab — callers may mutate or store the bytes.
+            return new Uint8Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Single source of truth for the on-disk metadata field list. Used in both
+ * `set()` (whitelist before write — strips smuggled fields, including the
+ * `version` field on round-trip) and `get()` (drop the `version` field before
+ * returning to the caller). Centralizing the list means future §8 audits
+ * only need to inspect one place.
+ */
+function pickMetadata(source) {
+    return {
+        status: source.status,
+        contentType: source.contentType,
+        etag: source.etag,
+        lastModified: source.lastModified,
+        fetchedAt: source.fetchedAt,
+        rewrittenUrl: source.rewrittenUrl,
+    };
+}
+//# sourceMappingURL=content-cache.js.map

package/dist/content-cache.js.map

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

package/dist/external-link-cache.d.ts

@@ -5,6 +5,12 @@ interface CacheEntry {
     statusCode: number;
     statusMessage: string;
     timestamp: number;
+    /**
+     * Schema version. Optional for backwards-compat: legacy entries without
+     * `version` are treated as a cache miss, forcing a refetch. Reading on
+     * version mismatch produces a miss rather than a parse error.
+     */
+    version?: number;
 }
 /**
  * External link validation cache
@@ -42,11 +48,19 @@ export declare class ExternalLinkCache {
      */
     constructor(cacheDir: string, ttlHours?: number);
     /**
-     * Load cache from disk
+     * Load cache from disk. Fail-soft: any IO error (ENOENT, EACCES, EROFS,
+     * corrupted JSON, …) degrades to an empty cache instead of throwing.
+     *
+     * Why no error propagation: `vat resources validate` should keep running
+     * when the cache file isn't reachable (read-only filesystem, permission
+     * mismatch, full disk) — a missing cache costs an extra network round-trip,
+     * an exception costs the whole run. Per #125 review.
      */
     private loadCache;
     /**
-     * Save cache to disk
+     * Save cache to disk. Fail-soft: any IO error becomes a no-op instead of
+     * throwing. Same rationale as `loadCache` — a non-persisted entry costs an
+     * extra fetch on the next run, an exception costs the whole current run.
      */
     private saveCache;
     /**

package/dist/external-link-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"external-link-cache.d.ts","sourceRoot":"","sources":["../src/external-link-cache.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,UAAU,UAAU;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CAClB;AASD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,KAAK,CAA0B;IAEvC;;;;;OAKG;gBACS,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAK;IAM3C;;OAEG;YACW,SAAS;IAsBvB;;OAEG;YACW,SAAS;IAWvB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAiBpB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAKnB;;OAEG;IACH,OAAO,CAAC,SAAS;IAOjB;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAkBlD;;;;;;OAMG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAahF;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAiB7D"}
+{"version":3,"file":"external-link-cache.d.ts","sourceRoot":"","sources":["../src/external-link-cache.ts"],"names":[],"mappings":"AAaA;;GAEG;AACH,UAAU,UAAU;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AASD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,KAAK,CAA0B;IAEvC;;;;;OAKG;gBACS,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAK;IAM3C;;;;;;;;OAQG;YACW,SAAS;IAqBvB;;;;OAIG;YACW,SAAS;IAiBvB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAiBpB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAKnB;;OAEG;IACH,OAAO,CAAC,SAAS;IAOjB;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA2BlD;;;;;;OAMG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAchF;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAiB7D"}

package/dist/external-link-cache.js

@@ -1,6 +1,13 @@
 import { createHash } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import { safePath } from '@vibe-agent-toolkit/utils';
+/**
+ * Cache schema version. Incremented when CacheEntry shape changes; entries
+ * written by an older code path that read as a different version are treated
+ * as cache misses (rather than misparsed) — forward-compat for slice 3's
+ * content-cache additions and any future entry-shape evolution.
+ */
+const CACHE_VERSION = 1;
 /**
  * External link validation cache
  *
@@ -41,7 +48,13 @@ export class ExternalLinkCache {
         this.cacheFile = safePath.join(cacheDir, 'external-links.json');
     }
     /**
-     * Load cache from disk
+     * Load cache from disk. Fail-soft: any IO error (ENOENT, EACCES, EROFS,
+     * corrupted JSON, …) degrades to an empty cache instead of throwing.
+     *
+     * Why no error propagation: `vat resources validate` should keep running
+     * when the cache file isn't reachable (read-only filesystem, permission
+     * mismatch, full disk) — a missing cache costs an extra network round-trip,
+     * an exception costs the whole run. Per #125 review.
      */
     async loadCache() {
         if (this.cache !== null) {
@@ -55,26 +68,34 @@ export class ExternalLinkCache {
             this.cache = JSON.parse(data);
             return this.cache;
         }
-        catch (error) {
-            // Handle missing file or corrupted JSON - start with empty cache
-            if (error.code === 'ENOENT' || error instanceof SyntaxError) {
-                this.cache = {};
-                return this.cache;
-            }
-            throw error;
+        catch {
+            // All IO and parse errors degrade to an empty cache. Subsequent
+            // reads see the same empty cache (this.cache is set), so we don't
+            // re-spam mkdir/read on every lookup within the same run.
+            this.cache = {};
+            return this.cache;
         }
     }
     /**
-     * Save cache to disk
+     * Save cache to disk. Fail-soft: any IO error becomes a no-op instead of
+     * throwing. Same rationale as `loadCache` — a non-persisted entry costs an
+     * extra fetch on the next run, an exception costs the whole current run.
      */
     async saveCache() {
         if (this.cache === null) {
             return;
         }
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- cacheDir is constructor parameter, controlled by caller
-        await fs.mkdir(this.cacheDir, { recursive: true });
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- cacheFile is derived from cacheDir
-        await fs.writeFile(this.cacheFile, JSON.stringify(this.cache, null, 2), 'utf-8');
+        try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- cacheDir is constructor parameter, controlled by caller
+            await fs.mkdir(this.cacheDir, { recursive: true });
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- cacheFile is derived from cacheDir
+            await fs.writeFile(this.cacheFile, JSON.stringify(this.cache, null, 2), 'utf-8');
+        }
+        catch {
+            // No-op on IO failure. The in-memory cache (`this.cache`) is still
+            // authoritative for the current run; only the disk persistence is
+            // lost.
+        }
     }
     /**
      * Normalize URL for caching
@@ -129,6 +150,14 @@ export class ExternalLinkCache {
         if (!entry) {
             return null;
         }
+        // Forward-compat: an entry written under a different (or missing)
+        // schema version is treated as a miss. Forces a refetch rather than
+        // silently misparsing a slice-3+ shape with slice-2 reader code.
+        if (entry.version !== CACHE_VERSION) {
+            delete cache[key];
+            await this.saveCache();
+            return null;
+        }
         if (this.isExpired(entry)) {
             delete cache[key];
             await this.saveCache();
@@ -150,6 +179,7 @@ export class ExternalLinkCache {
             statusCode,
             statusMessage,
             timestamp: Date.now(),
+            version: CACHE_VERSION,
         };
         await this.saveCache();
     }

package/dist/external-link-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"external-link-cache.js","sourceRoot":"","sources":["../src/external-link-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAkBrD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,iBAAiB;IACZ,QAAQ,CAAS;IACjB,QAAQ,CAAS;IACjB,SAAS,CAAS;IAC3B,KAAK,GAAqB,IAAI,CAAC;IAEvC;;;;;OAKG;IACH,YAAY,QAAgB,EAAE,QAAQ,GAAG,EAAE;QAC1C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC;IACjE,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,SAAS;QACtB,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,KAAK,CAAC;QACnB,CAAC;QAED,IAAI,CAAC;YACJ,8HAA8H;YAC9H,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,yGAAyG;YACzG,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACxD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAc,CAAC;YAC3C,OAAO,IAAI,CAAC,KAAK,CAAC;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,iEAAiE;YACjE,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;gBACxF,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;gBAChB,OAAO,IAAI,CAAC,KAAK,CAAC;YACnB,CAAC;YACD,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,SAAS;QACtB,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO;QACR,CAAC;QAED,8HAA8H;QAC9H,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,yGAAyG;QACzG,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAClF,CAAC;IAED;;;;OAIG;IACK,YAAY,CAAC,GAAW;QAC/B,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YAC5B,qBAAqB;YACrB,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;YACjB,wBAAwB;YACxB,IAAI,UAAU,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YACnC,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC9B,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACtC,CAAC;YACD,OAAO,UAAU,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACR,kCAAkC;YAClC,OAAO,GAAG,CAAC;QACZ,CAAC;IACF,CAAC;IAED;;;;OAIG;IACK,WAAW,CAAC,GAAW;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QAC1C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9D,CAAC;IAED;;OAEG;IACK,SAAS,CAAC,KAAiB;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAC7C,OAAO,GAAG,GAAG,KAAK,CAAC;IACpB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,CAAC,GAAW;QACpB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAClC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAEzB,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACb,CAAC;QAED,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC;YAClB,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,OAAO,KAAK,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,UAAkB,EAAE,aAAqB;QAC/D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAElC,KAAK,CAAC,GAAG,CAAC,GAAG;YACZ,UAAU;YACV,aAAa;YACb,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACrB,CAAC;QAEF,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACV,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAChB,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ;QACb,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE;YACnC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;YACzB,6DAA6D;YAC7D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACzB,OAAO,KAAK,CAAC;YACd,CAAC;YACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC,MAAM,CAAC;QAEV,OAAO;YACN,KAAK,EAAE,IAAI,CAAC,MAAM;YAClB,OAAO;SACP,CAAC;IACH,CAAC;CACD"}
+{"version":3,"file":"external-link-cache.js","sourceRoot":"","sources":["../src/external-link-cache.ts"],"names":[],"mappings":"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"}

package/dist/external-link-validator.d.ts

@@ -1,3 +1,6 @@
+import type { IssueCode } from '@vibe-agent-toolkit/agent-schema';
+import { type LinkAuthConfig } from '@vibe-agent-toolkit/utils';
+import { type LinkAuthDeps } from './link-auth-deps-memo.js';
 /**
  * Configuration options for external link validation
  */
@@ -10,6 +13,38 @@ export interface ExternalLinkValidatorOptions {
     retries?: number;
     /** User agent string for requests (default: generic) */
     userAgent?: string;
+    /**
+     * Optional linkAuth config (per issue #113). When set, URLs whose host is
+     * claimed by a provider in this config bypass the anonymous markdown-link-check
+     * path and use an authenticated direct fetch instead. URLs no provider claims
+     * continue to use markdown-link-check.
+     */
+    linkAuthConfig?: LinkAuthConfig;
+    /**
+     * Override the `fetch` implementation used by the authenticated branch.
+     * Defaults to `globalThis.fetch`. Tests inject a stub; advanced adopters
+     * may inject a wrapper for corporate proxies, custom TLS, or telemetry.
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Override the linkAuth engine's token-resolution dependencies (env map +
+     * runCommand). Defaults to reading `process.env` and running real commands
+     * via `safeExecSync`. Tests inject a deterministic env; advanced adopters
+     * usually leave unset.
+     */
+    linkAuthDeps?: LinkAuthDeps;
+    /**
+     * Override the sleep used between 429 retries. Defaults to `setTimeout`.
+     * Test-only — production benefits from real wall-clock delay so Retry-After
+     * hints are honored.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * OS user to scope the authenticated cache by (#113 §6.3). Defaults to
+     * `os.userInfo().username` with env-var fallbacks. Tests inject a fixed
+     * value; production callers omit.
+     */
+    osUser?: string;
 }
 /**
  * Result of validating a single external link
@@ -25,6 +60,21 @@ export interface LinkValidationResult {
     error?: string;
     /** Whether result came from cache */
     cached: boolean;
+    /**
+     * Set when the authenticated branch classified the response (issue #113 §7).
+     * Consumers use this directly instead of mapping `statusCode` to a code, so
+     * `notFoundMeaning`-dependent routing (404 → `LINK_AUTH_DEAD` vs
+     * `LINK_AUTH_DEAD_OR_UNAUTHORIZED`) reflects the matched provider's config.
+     *
+     * Invariant: `code` is set iff the URL hit the authenticated branch AND
+     * the outcome maps to a `LINK_AUTH_*` code per §7 (`unverified`, or any
+     * classified status: `unauthorized`, `forbidden`, `dead`,
+     * `dead_or_unauthorized`). Unset on the anonymous markdown-link-check path,
+     * on `unsupported` (no provider claimed the host), and on classifier-`null`
+     * statuses (5xx, unclassified) where the consumer's status-code mapping
+     * (`EXTERNAL_URL_*`) is the correct fallback.
+     */
+    code?: IssueCode;
 }
 /**
  * Validates external URLs in markdown content
@@ -47,7 +97,18 @@ export interface LinkValidationResult {
  */
 export declare class ExternalLinkValidator {
     private readonly cache;
+    /**
+     * Auth-branch cache — scoped to a per-OS-user subdirectory of `cacheDir`
+     * (#113 §6.3) so two users on a shared machine never read each other's
+     * authenticated results. Distinct from `cache` (the anonymous cache, which
+     * stays shared across users for the markdown-link-check path).
+     */
+    private readonly authCache;
     private readonly options;
+    private readonly linkAuthConfig;
+    private readonly fetchImpl;
+    private readonly linkAuthDeps;
+    private readonly sleep;
     /**
      * Create a new external link validator
      *
@@ -69,16 +130,28 @@ export declare class ExternalLinkValidator {
      * @returns Array of validation results
      */
     validateLinks(urls: string[]): Promise<LinkValidationResult[]>;
+    /**
+     * Issue an authenticated fetch for `originalUrl` using the engine's plan
+     * (rewritten URL + auth headers + provider's check config), classify the
+     * response per #113 §7, and write a status-cache entry. Cache is keyed by
+     * the *rewritten* URL (§6.3) — the original `blob/` URL 404s, so caching
+     * by original would poison results.
+     */
+    private validateAuthenticatedLink;
     /**
      * Check a link using markdown-link-check
      */
     private checkLink;
     /**
-     * Clear the validation cache
+     * Clear both validation caches (anonymous + authenticated).
+     *
+     * Adopters call this after rotating a token or invalidating link data —
+     * the operation must wipe both surfaces or stale auth results survive
+     * (a real bug: a 401 cached under the old token would haunt the new one).
      */
     clearCache(): Promise<void>;
     /**
-     * Get cache statistics
+     * Get combined cache statistics across both caches.
      */
     getCacheStats(): Promise<{
         total: number;

package/dist/external-link-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"external-link-validator.d.ts","sourceRoot":"","sources":["../src/external-link-validator.ts"],"names":[],"mappings":"AAyCA;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC5C,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,qBAAqB;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IAEjE;;;;;OAKG;gBACS,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,4BAAiC;IAaxE;;;;;OAKG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsC9D;;;;;OAKG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAIpE;;OAEG;YACW,SAAS;IAkEvB;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAGlE"}
+{"version":3,"file":"external-link-validator.d.ts","sourceRoot":"","sources":["../src/external-link-validator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAGL,KAAK,cAAc,EAEpB,MAAM,2BAA2B,CAAC;AAKnC,OAAO,EAAE,KAAK,YAAY,EAA4B,MAAM,0BAA0B,CAAC;AAyHvF;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC5C,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,qBAAqB;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAKtB;IACF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8C;IAEpE;;;;;OAKG;gBACS,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,4BAAiC;IA4BxE;;;;;OAKG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA6D9D;;;;;OAKG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAIpE;;;;;;OAMG;YACW,yBAAyB;IAyDvC;;OAEG;YACW,SAAS;IAkEvB;;;;;;OAMG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAIlE"}