@skillsmith/core 0.5.3 → 0.5.4

package/dist/src/sources/LocalFilesystemAdapter.d.ts

@@ -1,8 +1,36 @@
 /**
- * Local Filesystem Source Adapter (SMI-591)
+ * Local Filesystem Source Adapter (SMI-591, SMI-4287, SMI-4319, SMI-4320)
  *
  * Scans local directories for SKILL.md files.
  * Useful for local development and testing.
+ *
+ * SMI-4287 hardening:
+ * - Symlink targets are resolved via `fs.realpath` and checked against the
+ *   adapter's `rootDir`. Targets outside root are skipped with a
+ *   `symlink-escape` warning (unless `allowSymlinksOutsideRoot` is `true`).
+ * - Permission (EACCES/EPERM), not-found (ENOENT), and loop (ELOOP) errors
+ *   are surfaced as `AdapterError` entries on `SourceSearchResult.warnings`
+ *   instead of throwing, so siblings continue to be scanned.
+ * - All `fs.*` calls route through the typed `safeFs` helpers; the historic
+ *   bare `try/catch` for EACCES in `scanDirectory` is removed.
+ *
+ * SMI-4319 hardening:
+ * - `runScan` allocates a fresh `visitedRealpaths: Set<string>` per
+ *   invocation so mutually-recursive / self-looping directory symlinks are
+ *   detected and skipped with a `loop` warning instead of silently wasting
+ *   `maxDepth` traversals.
+ *
+ * SMI-4320 hardening:
+ * - `resolveSkillPath` is now async and routes through `resolveSafeRealpath`
+ *   (byte-wise `startsWith(rootReal + sep)` on realpath outputs — no
+ *   platform lowercasing). Direct-access methods (`getRepository`,
+ *   `fetchSkillContent`, `skillExists`) inherit containment instead of
+ *   relying solely on lexical `validatePath`. This closes the scan-to-fetch
+ *   TOCTOU window where an indexed-then-swapped symlink previously escaped
+ *   containment. `allowSymlinksOutsideRoot` is honoured at every realpath
+ *   callsite. Residual TOCTOU between `resolveSkillPath` and the subsequent
+ *   `fs.readFile` is documented; closing it requires fd-based I/O and is
+ *   tracked as a separate follow-up.
  */
 import { BaseSourceAdapter } from './BaseSourceAdapter.js';
 import type { SourceConfig, SourceLocation, SourceRepository, SourceSearchOptions, SourceSearchResult, SkillContent, SourceHealth } from './types.js';
@@ -18,6 +46,22 @@ export interface LocalFilesystemConfig extends SourceConfig {
     excludePatterns?: string[];
     /** Whether to follow symlinks (default: false) */
     followSymlinks?: boolean;
+    /**
+     * Allow symlinks whose target resolves outside `rootDir` (SMI-4287).
+     *
+     * Default `false`: symlinks pointing outside the scan root are skipped and
+     * a `symlink-escape` entry is added to `SourceSearchResult.warnings`. This
+     * prevents an attacker with write access to `rootDir` from exfiltrating
+     * content from arbitrary locations on the filesystem (GitHub #600).
+     *
+     * Set to `true` only if you trust every symlink inside `rootDir` (e.g.
+     * monorepo layouts that intentionally point at sibling packages). The
+     * caller accepts the security tradeoff.
+     *
+     * Note: this flag has no effect when `followSymlinks` is `false` — symlinks
+     * are never traversed in that case.
+     */
+    allowSymlinksOutsideRoot?: boolean;
 }
 /**
  * Local Filesystem Source Adapter
@@ -37,6 +81,9 @@ export interface LocalFilesystemConfig extends SourceConfig {
  *
  * await adapter.initialize()
  * const result = await adapter.search({})
+ * for (const warning of result.warnings ?? []) {
+ *   console.warn(`[${warning.code}] ${warning.message}`)
+ * }
  * ```
  */
 export declare class LocalFilesystemAdapter extends BaseSourceAdapter {
@@ -44,26 +91,47 @@ export declare class LocalFilesystemAdapter extends BaseSourceAdapter {
     private readonly maxDepth;
     private readonly excludePatterns;
     private readonly followSymlinks;
+    private readonly allowSymlinksOutsideRoot;
     private discoveredSkills;
+    /**
+     * Warnings accumulated during the most recent scan. Consumed and cleared
+     * by `search()` so each caller sees only the warnings from that call's
+     * underlying scan.
+     */
+    private scanWarnings;
     constructor(config: LocalFilesystemConfig);
     /**
      * Initialize by scanning the filesystem
      */
     protected doInitialize(): Promise<void>;
     /**
-     * Check if root directory exists and is accessible
+     * Check if root directory exists and is accessible.
+     *
+     * SMI-4287: routes `fs.stat(rootDir)` through `safeFs` so the raw Node
+     * error is translated to a typed `AdapterError` message.
      */
     protected doHealthCheck(): Promise<Partial<SourceHealth>>;
     /**
-     * Search for skills in the scanned directories
+     * Search for skills in the scanned directories.
+     *
+     * SMI-4287: `warnings` collects non-fatal `AdapterError` entries from the
+     * scan (symlink escapes, permission denials, loops). An empty array is
+     * returned as `undefined` to keep the field strictly optional.
      */
     search(options?: SourceSearchOptions): Promise<SourceSearchResult>;
     /**
-     * Get repository info for a skill location
+     * Get repository info for a skill location.
+     *
+     * SMI-4287: `fs.stat` is routed through `safeFs`; permission errors are
+     * converted to typed Error messages instead of raw Node throws.
      */
     getRepository(location: SourceLocation): Promise<SourceRepository>;
     /**
-     * Fetch skill content from local file
+     * Fetch skill content from local file.
+     *
+     * SMI-4287: both `fs.readFile` and `fs.stat` route through `safeFs`, so
+     * permission errors (EACCES/EPERM) raise typed Errors with path context
+     * instead of raw Node errors.
      */
     fetchSkillContent(location: SourceLocation): Promise<SkillContent>;
     /**
@@ -71,7 +139,10 @@ export declare class LocalFilesystemAdapter extends BaseSourceAdapter {
      */
     skillExists(location: SourceLocation): Promise<boolean>;
     /**
-     * Rescan the filesystem for new skills
+     * Rescan the filesystem for new skills.
+     *
+     * Returns the count of discovered skills. Warnings from the rescan are
+     * available via the next call to `search()`.
      */
     rescan(): Promise<number>;
     /**
@@ -79,9 +150,16 @@ export declare class LocalFilesystemAdapter extends BaseSourceAdapter {
      */
     get skillCount(): number;
     /**
-     * Scan a directory recursively for skill files
+     * Run the recursive scan starting at `rootDir`. Delegates to the extracted
+     * `scanDirectoryRecursive` helper (see `LocalFilesystemAdapter.scan.ts`).
+     *
+     * SMI-4319: allocates a fresh `visitedRealpaths` set per invocation so
+     * back-to-back scans don't share state. Sibling directories within a
+     * single scan share the set (they're in the same call tree), so
+     * cross-linked loops (A↔B) are caught even when the loop isn't on the
+     * descent path from `rootDir`.
      */
-    private scanDirectory;
+    private runScan;
     /**
      * Check if a path/name should be excluded (SMI-722, SMI-726)
      * Uses centralized safe pattern matching to prevent RegExp injection
@@ -89,11 +167,27 @@ export declare class LocalFilesystemAdapter extends BaseSourceAdapter {
     private isExcluded;
     /**
      * Resolve a skill location to a full filesystem path
-     * Validates that the resolved path remains within rootDir to prevent path traversal attacks (SMI-720, SMI-726)
+     * (SMI-720, SMI-726, SMI-4287, SMI-4320).
+     *
+     * Two-stage containment: (1) lexical `validatePath` fast-fails
+     * `../`-style traversal (SMI-720 contract — callers assert the
+     * "Path traversal detected" message), then (2) `resolveSafeRealpath`
+     * enforces realpath byte-wise containment so symlinks can't escape
+     * `rootDir` even when the lexical path is clean. Honours the SMI-4287
+     * `allowSymlinksOutsideRoot` opt-in.
+     *
+     * Not-found behaviour: realpath ENOENT falls back to the lexically
+     * resolved path so downstream `stat` / `readFile` produce the canonical
+     * caller-visible error. TOCTOU caveat: the window between this resolve
+     * and the caller's subsequent read remains open; closing it requires
+     * fd-based I/O and is tracked separately.
      */
     private resolveSkillPath;
     /**
-     * Convert discovered skill to SourceRepository
+     * Convert discovered skill to SourceRepository.
+     *
+     * Returns both the repository and any warnings encountered while reading
+     * the file (typically permission errors on SKILL.md after discovery).
      */
     private skillToRepository;
     /**

package/dist/src/sources/LocalFilesystemAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LocalFilesystemAdapter.d.ts","sourceRoot":"","sources":["../../../src/sources/LocalFilesystemAdapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAA;AAcnB;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,YAAY;IACzD,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAA;IACf,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,kDAAkD;IAClD,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAoBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,sBAAuB,SAAQ,iBAAiB;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,gBAAgB,CAAwB;gBAEpC,MAAM,EAAE,qBAAqB;IAQzC;;OAEG;cACsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAItD;;OAEG;cACa,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAe/D;;OAEG;IACG,MAAM,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAkC5E;;OAEG;IACG,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoCxE;;OAEG;IACG,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAuBxE;;OAEG;IACY,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAUtE;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAM/B;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;OAEG;YACW,aAAa;IAuD3B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAIlB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAqBxB;;OAEG;YACW,iBAAiB;IA6C/B;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,OAAO,CAAC,WAAW;CAGpB;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,qBAAqB,GAC5B,sBAAsB,CAMxB"}
+{"version":3,"file":"LocalFilesystemAdapter.d.ts","sourceRoot":"","sources":["../../../src/sources/LocalFilesystemAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,YAAY,EAEb,MAAM,YAAY,CAAA;AAanB;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,YAAY;IACzD,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAA;IACf,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,kDAAkD;IAClD,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;;;;;;;;;OAcG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAA;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,sBAAuB,SAAQ,iBAAiB;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAS;IAClD,OAAO,CAAC,gBAAgB,CAA8B;IACtD;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAAqB;gBAE7B,MAAM,EAAE,qBAAqB;IASzC;;OAEG;cACsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtD;;;;;OAKG;cACa,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAc/D;;;;;;OAMG;IACG,MAAM,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAmC5E;;;;;OAKG;IACG,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAkCxE;;;;;;OAMG;IACG,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAyBxE;;OAEG;IACY,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAUtE;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAO/B;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;;;;;OASG;YACW,OAAO;IAcrB;;;OAGG;IACH,OAAO,CAAC,UAAU;IAIlB;;;;;;;;;;;;;;;;OAgBG;YACW,gBAAgB;IA2C9B;;;;;OAKG;YACW,iBAAiB;IAiD/B;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,OAAO,CAAC,WAAW;CAGpB;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,qBAAqB,GAC5B,sBAAsB,CAMxB"}

package/dist/src/sources/LocalFilesystemAdapter.helpers.d.ts

@@ -0,0 +1,92 @@
+/**
+ * LocalFilesystemAdapter helpers (SMI-4287, SMI-4319, SMI-4320)
+ *
+ * Typed filesystem wrappers and symlink containment helpers used by
+ * LocalFilesystemAdapter. These surface `AdapterError` return values instead
+ * of throwing, so the adapter can continue scanning past individual failures
+ * (permission, symlink escape, loop) and aggregate them into
+ * `SourceSearchResult.warnings`.
+ *
+ * SMI-4320: drops platform-based `normaliseForFs` in favour of byte-wise
+ * `startsWith(root + sep)` on realpath outputs. The FS itself canonicalises
+ * case via `realpath` — platform heuristics miscategorise case-sensitive
+ * volumes (HFS+ case-sensitive macOS volumes, ext4 case-folded dirs).
+ * `resolveSafeRealpath` now accepts an `allowSymlinksOutsideRoot` opt-in
+ * (see SMI-4287) so direct-access callers can inherit the same containment
+ * policy as the scan loop.
+ */
+import { type Dirent, type Stats } from 'fs';
+import type { AdapterError } from './types.js';
+/**
+ * Success / failure result envelope used by `safeFs` helpers.
+ *
+ * @typeParam T - Type of the successful value
+ */
+export type FsResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: AdapterError;
+};
+/**
+ * Safe filesystem wrappers that return `FsResult<T>` instead of throwing.
+ */
+export declare const safeFs: {
+    readonly readdir: (path: string) => Promise<FsResult<Dirent[]>>;
+    readonly stat: (path: string) => Promise<FsResult<Stats>>;
+    readonly readFile: (path: string, encoding?: BufferEncoding) => Promise<FsResult<string>>;
+    readonly realpath: (path: string) => Promise<FsResult<string>>;
+};
+/**
+ * Byte-wise containment check on two realpath outputs (SMI-4320).
+ *
+ * Compares raw realpath bytes: `candidateReal === rootReal` or
+ * `candidateReal.startsWith(rootReal + sep)`. No platform lowercasing — the
+ * filesystem is authoritative. Case-insensitive volumes (APFS default, NTFS)
+ * already canonicalise case through `fs.realpath`; case-sensitive volumes
+ * (HFS+ case-sensitive, ext4 case-folded) keep distinct paths distinct.
+ *
+ * The trailing-separator guard is load-bearing: without `+ sep`,
+ * `rootDir = /a/root` would accept `/a/rootfoo` as contained.
+ */
+export declare function isRealpathContained(candidateReal: string, rootReal: string): boolean;
+/**
+ * Options accepted by `resolveSafeRealpath`.
+ *
+ * - `allowSymlinksOutsideRoot` (SMI-4287): when `true`, skip the containment
+ *   re-check and return the realpath unconditionally. Callers that opt in
+ *   accept the security tradeoff — used by dev-install tooling that scans
+ *   linked sibling packages.
+ */
+export interface ResolveSafeRealpathOptions {
+    allowSymlinksOutsideRoot?: boolean;
+}
+/**
+ * Resolve `candidate` to a realpath and verify it remains within `root`.
+ *
+ * Runs `fs.realpath` on both the candidate and the root, then performs a
+ * byte-wise `startsWith(rootReal + sep)` check (SMI-4320). On case-insensitive
+ * volumes the FS canonicalises case inside `realpath`; on case-sensitive
+ * volumes distinct cases remain distinct — both outcomes are correct.
+ *
+ * Returns `{ ok: true, value: resolvedRealpath }` on success. On failure
+ * returns an `AdapterError` with:
+ * - `symlink-escape` if the target resolves outside the root
+ * - `loop` on `ELOOP` (circular symlinks)
+ * - `permission` / `not-found` / `io` for other filesystem errors
+ *
+ * Does NOT throw for containment violations (caller drives the warning list).
+ *
+ * SMI-4287 opt-in: when `opts.allowSymlinksOutsideRoot === true`, containment
+ * is skipped entirely. The loop-detection + other realpath errors still apply.
+ *
+ * TOCTOU caveat: this is a check-then-use pattern. Between the realpath
+ * check and a subsequent `fs.readFile`, a malicious actor with write access
+ * inside `rootDir` could swap the symlink target. True atomicity requires
+ * fd-based I/O (`fs.open` + fstat-by-fd + read-by-fd) and is out of scope
+ * here — this helper closes the 99% case where the attack window is
+ * scan-to-fetch (minutes to hours). See plan doc for the residual risk.
+ */
+export declare function resolveSafeRealpath(candidate: string, root: string, opts?: ResolveSafeRealpathOptions): Promise<FsResult<string>>;
+//# sourceMappingURL=LocalFilesystemAdapter.helpers.d.ts.map

package/dist/src/sources/LocalFilesystemAdapter.helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalFilesystemAdapter.helpers.d.ts","sourceRoot":"","sources":["../../../src/sources/LocalFilesystemAdapter.helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAkB,KAAK,MAAM,EAAE,KAAK,KAAK,EAAE,MAAM,IAAI,CAAA;AAE5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CAAA;AA0DrF;;GAEG;AACH,eAAO,MAAM,MAAM;6BACH,MAAM,KAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;0BAGvC,MAAM,KAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;8BAG7B,MAAM,aAAY,cAAc,KAAa,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;8BAGtE,MAAM,KAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;CAGzC,CAAA;AAEV;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpF;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC,wBAAwB,CAAC,EAAE,OAAO,CAAA;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,0BAA+B,GACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CA0B3B"}

package/dist/src/sources/LocalFilesystemAdapter.helpers.js

@@ -0,0 +1,157 @@
+/**
+ * LocalFilesystemAdapter helpers (SMI-4287, SMI-4319, SMI-4320)
+ *
+ * Typed filesystem wrappers and symlink containment helpers used by
+ * LocalFilesystemAdapter. These surface `AdapterError` return values instead
+ * of throwing, so the adapter can continue scanning past individual failures
+ * (permission, symlink escape, loop) and aggregate them into
+ * `SourceSearchResult.warnings`.
+ *
+ * SMI-4320: drops platform-based `normaliseForFs` in favour of byte-wise
+ * `startsWith(root + sep)` on realpath outputs. The FS itself canonicalises
+ * case via `realpath` — platform heuristics miscategorise case-sensitive
+ * volumes (HFS+ case-sensitive macOS volumes, ext4 case-folded dirs).
+ * `resolveSafeRealpath` now accepts an `allowSymlinksOutsideRoot` opt-in
+ * (see SMI-4287) so direct-access callers can inherit the same containment
+ * policy as the scan loop.
+ */
+import { promises as fs } from 'fs';
+import { sep } from 'path';
+/**
+ * Map a Node filesystem error to an `AdapterError.code`.
+ */
+function mapErrnoToCode(err) {
+    const code = err?.code;
+    switch (code) {
+        case 'EACCES':
+        case 'EPERM':
+            return 'permission';
+        case 'ENOENT':
+            return 'not-found';
+        case 'ELOOP':
+            return 'loop';
+        default:
+            return 'io';
+    }
+}
+/**
+ * Build a human-friendly message for an AdapterError.
+ */
+function describe(code, path) {
+    switch (code) {
+        case 'permission':
+            return `Cannot read: ${path}`;
+        case 'not-found':
+            return `Not found: ${path}`;
+        case 'loop':
+            return `Symlink loop detected: ${path}`;
+        case 'symlink-escape':
+            return `Symlink outside root, skipped: ${path}`;
+        case 'io':
+            return `Filesystem error: ${path}`;
+    }
+}
+/**
+ * Wrap a throwing `fs` call into an `FsResult<T>`.
+ */
+async function wrap(path, op) {
+    try {
+        return { ok: true, value: await op() };
+    }
+    catch (error) {
+        const code = mapErrnoToCode(error);
+        return {
+            ok: false,
+            error: {
+                code,
+                path,
+                message: describe(code, path),
+                cause: error,
+            },
+        };
+    }
+}
+/**
+ * Safe filesystem wrappers that return `FsResult<T>` instead of throwing.
+ */
+export const safeFs = {
+    readdir(path) {
+        return wrap(path, () => fs.readdir(path, { withFileTypes: true }));
+    },
+    stat(path) {
+        return wrap(path, () => fs.stat(path));
+    },
+    readFile(path, encoding = 'utf-8') {
+        return wrap(path, () => fs.readFile(path, encoding));
+    },
+    realpath(path) {
+        return wrap(path, () => fs.realpath(path));
+    },
+};
+/**
+ * Byte-wise containment check on two realpath outputs (SMI-4320).
+ *
+ * Compares raw realpath bytes: `candidateReal === rootReal` or
+ * `candidateReal.startsWith(rootReal + sep)`. No platform lowercasing — the
+ * filesystem is authoritative. Case-insensitive volumes (APFS default, NTFS)
+ * already canonicalise case through `fs.realpath`; case-sensitive volumes
+ * (HFS+ case-sensitive, ext4 case-folded) keep distinct paths distinct.
+ *
+ * The trailing-separator guard is load-bearing: without `+ sep`,
+ * `rootDir = /a/root` would accept `/a/rootfoo` as contained.
+ */
+export function isRealpathContained(candidateReal, rootReal) {
+    return candidateReal === rootReal || candidateReal.startsWith(rootReal + sep);
+}
+/**
+ * Resolve `candidate` to a realpath and verify it remains within `root`.
+ *
+ * Runs `fs.realpath` on both the candidate and the root, then performs a
+ * byte-wise `startsWith(rootReal + sep)` check (SMI-4320). On case-insensitive
+ * volumes the FS canonicalises case inside `realpath`; on case-sensitive
+ * volumes distinct cases remain distinct — both outcomes are correct.
+ *
+ * Returns `{ ok: true, value: resolvedRealpath }` on success. On failure
+ * returns an `AdapterError` with:
+ * - `symlink-escape` if the target resolves outside the root
+ * - `loop` on `ELOOP` (circular symlinks)
+ * - `permission` / `not-found` / `io` for other filesystem errors
+ *
+ * Does NOT throw for containment violations (caller drives the warning list).
+ *
+ * SMI-4287 opt-in: when `opts.allowSymlinksOutsideRoot === true`, containment
+ * is skipped entirely. The loop-detection + other realpath errors still apply.
+ *
+ * TOCTOU caveat: this is a check-then-use pattern. Between the realpath
+ * check and a subsequent `fs.readFile`, a malicious actor with write access
+ * inside `rootDir` could swap the symlink target. True atomicity requires
+ * fd-based I/O (`fs.open` + fstat-by-fd + read-by-fd) and is out of scope
+ * here — this helper closes the 99% case where the attack window is
+ * scan-to-fetch (minutes to hours). See plan doc for the residual risk.
+ */
+export async function resolveSafeRealpath(candidate, root, opts = {}) {
+    const candidateResult = await safeFs.realpath(candidate);
+    if (!candidateResult.ok)
+        return candidateResult;
+    if (opts.allowSymlinksOutsideRoot === true) {
+        return candidateResult;
+    }
+    const rootResult = await safeFs.realpath(root);
+    if (!rootResult.ok)
+        return rootResult;
+    if (!isRealpathContained(candidateResult.value, rootResult.value)) {
+        // Report the symlink path the user can identify (not the opaque
+        // realpath target). Including the target would leak the external
+        // location, which is exactly what the guard is protecting against.
+        return {
+            ok: false,
+            error: {
+                code: 'symlink-escape',
+                path: candidate,
+                message: describe('symlink-escape', candidate),
+            },
+        };
+    }
+    return { ok: true, value: candidateResult.value };
+}
+//# sourceMappingURL=LocalFilesystemAdapter.helpers.js.map

package/dist/src/sources/LocalFilesystemAdapter.helpers.js.map

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