@skillsmith/core 0.5.2 → 0.5.4

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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"}