@ktuban/safe-json-loader 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 K Tuban
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+Got it, K — let’s update your **README.md** so it reflects the new helpers (`parseSafeJsonString` and `sanitizeParsedJsonObject`) alongside the loader. This way, developers see clearly how to use the library in **all entry points**: files, URLs, raw strings, and already‑parsed objects (like Express `req.body`).  
+
+Here’s the polished, industry‑grade README update:
+
+---
+
+# **safe-json-loader**
+
+A **security‑hardened JSON loader and sanitizer** for Node.js that protects against prototype pollution, excessive depth, oversized payloads, unsafe remote JSON, and directory‑based DoS attacks.  
+Supports:
+
+- Local JSON files  
+- Local directories of JSON files  
+- Remote JSON URLs  
+- Remote JSON indexes (`[]` or `{ files: [] }`)  
+- Safe parsing of raw JSON strings  
+- Safe sanitization of already‑parsed JSON objects  
+- Safe serialization via `safe-json-stringify`  
+
+---
+
+## **Features**
+
+- 🔐 **Security‑first design**  
+  - Strips `__proto__`, `constructor`, and `prototype`  
+  - Rebuilds objects using `Object.create(null)`  
+  - Enforces maximum JSON depth  
+  - Enforces per‑file and total directory size limits  
+  - Enforces maximum number of files  
+  - Safe remote loading with timeout, content‑type validation, and concurrency limits  
+
+- 🧹 **Helpers for all entry points**  
+  - `loadSafeJsonResources()` → load from file, directory, or URL  
+  - `parseSafeJsonString()` → sanitize raw JSON strings  
+  - `sanitizeParsedJsonObject()` → sanitize already‑parsed objects (e.g. Express `req.body`)  
+
+- 🧪 **TypeScript‑first**  
+  - Full type definitions  
+  - Strongly typed loader output  
+
+---
+
+## **Installation**
+
+```bash
+npm install safe-json-loader safe-json-stringify
+```
+
+Node.js **18+** required.
+
+---
+
+## **Usage**
+
+### **1. Load from file, directory, or URL**
+
+```ts
+import { loadSafeJsonResources } from "safe-json-loader";
+
+const files = await loadSafeJsonResources("./configs");
+
+for (const file of files) {
+  console.log(file.name);
+  console.log(file.data);
+}
+```
+
+---
+
+### **2. Parse and sanitize a raw JSON string**
+
+```ts
+import { parseSafeJsonString } from "safe-json-loader";
+
+const safeObj = parseSafeJsonString('{"user":{"__proto__":{"polluted":true}}}', {
+  maxJsonDepth: 30,
+});
+
+console.log(safeObj);
+// => { user: {} }   // pollution stripped
+```
+
+---
+
+### **3. Sanitize an already‑parsed JSON object (Express example)**
+
+```ts
+import express from "express";
+import { sanitizeParsedJsonObject } from "safe-json-loader";
+
+const app = express();
+app.use(express.json());
+
+app.post("/api/data", (req, res) => {
+  try {
+    const safeBody = sanitizeParsedJsonObject(req.body, { maxJsonDepth: 30 });
+    res.json({ ok: true, sanitized: safeBody });
+  } catch (err: any) {
+    res.status(400).json({ error: err.message, code: err.code });
+  }
+});
+```
+
+---
+
+### **4. Safe serialization**
+
+```ts
+import safeStringify from "safe-json-stringify";
+
+const json = safeStringify(file.data);
+```
+
+---
+
+## **Options**
+
+```ts
+interface SafeJsonLoaderOptions {
+  maxFiles?: number;            // default 100
+  maxTotalBytes?: number;       // default 10 MB
+  maxFileBytes?: number;        // default 2 MB
+  httpTimeoutMs?: number;       // default 8000
+  maxConcurrency?: number;      // default 5
+  looseJsonContentType?: boolean; // default true
+  maxJsonDepth?: number;        // default 50
+  logger?: JsonLoaderLogger;
+  onFileLoaded?: (file) => void;
+  onFileSkipped?: (info) => void;
+}
+```
+
+---
+
+## **Returned Structure**
+
+Each loaded file has the shape:
+
+```ts
+interface LoadedJsonFile {
+  name: string;       // file name or URL basename
+  data: JsonValue;    // sanitized JSON
+  __source: string;   // absolute path or URL
+}
+```
+
+---
+
+## **Security Guarantees**
+
+- ✔ Prototype pollution prevented  
+- ✔ No inherited prototypes  
+- ✔ Depth‑limited  
+- ✔ Size‑limited  
+- ✔ Safe remote fetch  
+- ✔ Concurrency‑limited  
+- ✔ Sanitized before user code touches it  
+
+---
+
+## **Error Handling**
+
+All errors are thrown as:
+
+```ts
+class JsonLoaderError extends Error {
+  code: string;
+}
+```
+
+Example:
+
+```ts
+try {
+  await loadSafeJsonResources("./bad.json");
+} catch (err) {
+  console.error(err.code, err.message);
+}
+```
+
+---
+
+## **License**
+
+MIT
+
+---
+
+👉 With this update, your README now documents **all three entry points**: loader, string parser, and object sanitizer.  
+
+always sanitize `req.body` before schema validation, always set `maxJsonDepth` in production) 

package/dist/cjs/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Public types
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./logger.js"), exports);
+__exportStar(require("./safeJsonLoader.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AACA,eAAe;AACf,6CAA2B;AAC3B,8CAA4B;AAC5B,sDAAoC"}

package/dist/cjs/logger.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleJsonLoaderLogger = void 0;
+exports.mergeOptions = mergeOptions;
+exports.logWith = logWith;
+// logger.ts
+const safe_json_stringify_1 = __importDefault(require("safe-json-stringify"));
+const NOOP_LOGGER = {
+    log: () => {
+        // no‑op
+    },
+};
+const DEFAULT_OPTIONS = {
+    maxFiles: 100,
+    maxTotalBytes: 10 * 1024 * 1024, // 10 MB
+    maxFileBytes: 2 * 1024 * 1024, // 2 MB
+    httpTimeoutMs: 8000,
+    maxConcurrency: 5,
+    looseJsonContentType: true,
+    maxJsonDepth: 50,
+    logger: NOOP_LOGGER,
+    onFileLoaded: () => { },
+    onFileSkipped: () => { },
+};
+function mergeOptions(opts) {
+    const logger = opts?.logger ?? DEFAULT_OPTIONS.logger;
+    return {
+        ...DEFAULT_OPTIONS,
+        ...opts,
+        logger,
+        onFileLoaded: opts?.onFileLoaded ?? DEFAULT_OPTIONS.onFileLoaded,
+        onFileSkipped: opts?.onFileSkipped ?? DEFAULT_OPTIONS.onFileSkipped,
+    };
+}
+/**
+ * Simple adapter to allow direct use of console as logger, if desired.
+ */
+class ConsoleJsonLoaderLogger {
+    log(level, message, meta) {
+        const payload = meta ? `${message} | ${(0, safe_json_stringify_1.default)(meta)}` : message;
+        switch (level) {
+            case "debug":
+                console.debug(payload);
+                break;
+            case "info":
+                console.info(payload);
+                break;
+            case "warn":
+                console.warn(payload);
+                break;
+            case "error":
+                console.error(payload);
+                break;
+        }
+    }
+}
+exports.ConsoleJsonLoaderLogger = ConsoleJsonLoaderLogger;
+/**
+ * Helper to log with a specific log level using resolved options.
+ */
+function logWith(options, level, message, meta) {
+    options.logger.log(level, message, meta);
+}
+//# sourceMappingURL=logger.js.map

package/dist/cjs/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":";;;;;;AA4BA,oCAYC;AA4BD,0BAOC;AA3ED,YAAY;AACZ,8EAA4C;AAQ5C,MAAM,WAAW,GAAqB;IACpC,GAAG,EAAE,GAAG,EAAE;QACR,QAAQ;IACV,CAAC;CACF,CAAC;AAEF,MAAM,eAAe,GAAkC;IACrD,QAAQ,EAAE,GAAG;IACb,aAAa,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,QAAQ;IACzC,YAAY,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,EAAI,OAAO;IACxC,aAAa,EAAE,IAAI;IACnB,cAAc,EAAE,CAAC;IACjB,oBAAoB,EAAE,IAAI;IAC1B,YAAY,EAAE,EAAE;IAChB,MAAM,EAAE,WAAW;IACnB,YAAY,EAAE,GAAG,EAAE,GAAE,CAAC;IACtB,aAAa,EAAE,GAAG,EAAE,GAAE,CAAC;CACxB,CAAC;AAEF,SAAgB,YAAY,CAC1B,IAA4B;IAE5B,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,eAAe,CAAC,MAAM,CAAC;IAEtD,OAAO;QACL,GAAG,eAAe;QAClB,GAAG,IAAI;QACP,MAAM;QACN,YAAY,EAAE,IAAI,EAAE,YAAY,IAAI,eAAe,CAAC,YAAY;QAChE,aAAa,EAAE,IAAI,EAAE,aAAa,IAAI,eAAe,CAAC,aAAa;KACpE,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAa,uBAAuB;IAClC,GAAG,CAAC,KAAe,EAAE,OAAe,EAAE,IAA8B;QAClE,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,MAAM,IAAA,6BAAS,EAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QACnE,QAAQ,KAAK,EAAE,CAAC;YACd,KAAK,OAAO;gBACV,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBACvB,MAAM;YACR,KAAK,MAAM;gBACT,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACtB,MAAM;YACR,KAAK,MAAM;gBACT,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACtB,MAAM;YACR,KAAK,OAAO;gBACV,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBACvB,MAAM;QACV,CAAC;IACH,CAAC;CACF;AAlBD,0DAkBC;AAED;;GAEG;AACH,SAAgB,OAAO,CACrB,OAAsC,EACtC,KAAe,EACf,OAAe,EACf,IAA8B;IAE9B,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAC3C,CAAC"}

package/dist/cjs/safeJsonLoader.js

@@ -0,0 +1,391 @@
+"use strict";
+// safeJsonLoader.ts
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonLoaderError = void 0;
+exports.sanitizePrototypePollution = sanitizePrototypePollution;
+exports.loadSafeJsonResources = loadSafeJsonResources;
+exports.parseSafeJsonString = parseSafeJsonString;
+exports.sanitizeParsedJsonObject = sanitizeParsedJsonObject;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const node_fetch_1 = __importDefault(require("node-fetch"));
+const logger_js_1 = require("./logger.js");
+/* -------------------------------------------------------------------------- */
+/*  ERROR TYPE                                                                */
+/* -------------------------------------------------------------------------- */
+class JsonLoaderError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "JsonLoaderError";
+        this.code = code;
+    }
+}
+exports.JsonLoaderError = JsonLoaderError;
+/* -------------------------------------------------------------------------- */
+/*  HELPERS                                                                   */
+/* -------------------------------------------------------------------------- */
+function isHttpUrl(str) {
+    return /^https?:\/\//i.test(str);
+}
+function isJsonFile(file) {
+    return path_1.default.extname(file).toLowerCase() === ".json";
+}
+function ensureStringInput(input) {
+    if (typeof input === "string")
+        return input;
+    if (input.href)
+        return String(input);
+    return String(input);
+}
+// Minimal concurrency limiter to avoid external deps.
+function createLimiter(maxConcurrency) {
+    let active = 0;
+    const queue = [];
+    const next = () => {
+        active--;
+        if (queue.length > 0) {
+            const fn = queue.shift();
+            fn();
+        }
+    };
+    const run = (task) => new Promise((resolve, reject) => {
+        const execute = () => {
+            active++;
+            task()
+                .then((result) => {
+                next();
+                resolve(result);
+            })
+                .catch((err) => {
+                next();
+                reject(err);
+            });
+        };
+        if (active < maxConcurrency) {
+            execute();
+        }
+        else {
+            queue.push(execute);
+        }
+    });
+    return run;
+}
+/* -------------------------------------------------------------------------- */
+/*  SECURITY: PROTOTYPE POLLUTION SANITIZER                                   */
+/* -------------------------------------------------------------------------- */
+const POLLUTION_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Deeply clones and strips dangerous keys to mitigate prototype pollution.
+ * Uses Object.create(null) to avoid inheriting from Object.prototype.
+ */
+function sanitizePrototypePollution(input, options) {
+    const maxDepth = options?.maxDepth ?? 1_000; // extremely high default, actual limit enforced separately
+    return deepSanitize(input, 0, maxDepth);
+}
+function deepSanitize(value, depth, maxDepth) {
+    if (depth > maxDepth) {
+        // Hard stop; caller should usually enforce a much smaller depth via options.maxJsonDepth.
+        throw new JsonLoaderError(`Maximum JSON depth exceeded during sanitation (depth > ${maxDepth}).`, "JSON_DEPTH_SANITATION_LIMIT");
+    }
+    if (Array.isArray(value)) {
+        const out = new Array(value.length);
+        for (let i = 0; i < value.length; i++) {
+            out[i] = deepSanitize(value[i], depth + 1, maxDepth);
+        }
+        return out;
+    }
+    if (value && typeof value === "object") {
+        const out = Object.create(null);
+        for (const key of Object.keys(value)) {
+            if (POLLUTION_KEYS.has(key)) {
+                continue;
+            }
+            out[key] = deepSanitize(value[key], depth + 1, maxDepth);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Computes maximum depth of a JSON value.
+ */
+function calculateDepth(value, currentDepth = 0) {
+    if (value === null)
+        return currentDepth;
+    if (Array.isArray(value)) {
+        let max = currentDepth;
+        for (const item of value) {
+            const depth = calculateDepth(item, currentDepth + 1);
+            if (depth > max)
+                max = depth;
+        }
+        return max;
+    }
+    if (typeof value === "object") {
+        let max = currentDepth;
+        for (const key of Object.keys(value)) {
+            const depth = calculateDepth(value[key], currentDepth + 1);
+            if (depth > max)
+                max = depth;
+        }
+        return max;
+    }
+    return currentDepth;
+}
+/* -------------------------------------------------------------------------- */
+/*  REMOTE JSON LOADING                                                       */
+/* -------------------------------------------------------------------------- */
+async function fetchWithTimeout(url, opts) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), opts.httpTimeoutMs);
+    try {
+        const res = await (0, node_fetch_1.default)(url, { method: "GET", signal: controller.signal });
+        clearTimeout(timeoutId);
+        return res;
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        throw new JsonLoaderError(`Failed to fetch remote JSON at ${url}: ${err?.message ?? String(err)}`, "REMOTE_FETCH_ERROR");
+    }
+}
+function assertJsonContentType(url, res, opts) {
+    const ct = res.headers.get("content-type") ?? "";
+    const lc = ct.toLowerCase();
+    const isJson = opts.looseJsonContentType
+        ? lc.includes("json")
+        : lc.startsWith("application/json");
+    if (!isJson) {
+        throw new JsonLoaderError(`Remote URL does not advertise JSON content-type at ${url}: '${ct}'`, "REMOTE_CONTENT_TYPE_ERROR");
+    }
+}
+async function loadRemoteJson(url, opts) {
+    const res = await fetchWithTimeout(url, opts);
+    if (!res.ok) {
+        throw new JsonLoaderError(`Remote fetch failed at ${url}: ${res.status} ${res.statusText}`, "REMOTE_FETCH_STATUS_ERROR");
+    }
+    assertJsonContentType(url, res, opts);
+    const raw = (await res.json());
+    const sanitized = sanitizePrototypePollution(raw, {
+        maxDepth: opts.maxJsonDepth,
+    });
+    return sanitized;
+}
+async function loadRemoteIndex(indexUrl, indexJson, opts, limitRun) {
+    let fileList;
+    if (Array.isArray(indexJson)) {
+        fileList = indexJson;
+    }
+    else if (indexJson &&
+        typeof indexJson === "object" &&
+        Array.isArray(indexJson.files)) {
+        fileList = indexJson.files;
+    }
+    if (!Array.isArray(fileList)) {
+        throw new JsonLoaderError(`Remote directory index ${indexUrl} must return an array or { files: [] }.`, "REMOTE_INDEX_FORMAT_ERROR");
+    }
+    const urls = fileList.filter((item) => typeof item === "string");
+    if (urls.length === 0) {
+        return [];
+    }
+    if (urls.length > opts.maxFiles) {
+        throw new JsonLoaderError(`Remote directory index at ${indexUrl} lists ${urls.length} files, exceeding maxFiles=${opts.maxFiles}.`, "REMOTE_INDEX_LIMIT_ERROR");
+    }
+    (0, logger_js_1.logWith)(opts, "debug", "Loading remote index", {
+        indexUrl,
+        fileCount: urls.length,
+    });
+    const tasks = urls.map((fileUrl) => limitRun(async () => {
+        if (!isHttpUrl(fileUrl)) {
+            throw new JsonLoaderError(`Invalid remote file URL in index at ${indexUrl}: ${fileUrl}`, "REMOTE_INDEX_URL_ERROR");
+        }
+        const data = await loadRemoteJson(fileUrl, opts);
+        const file = Object.freeze({
+            name: path_1.default.basename(new URL(fileUrl).pathname),
+            data,
+            __source: fileUrl,
+        });
+        opts.onFileLoaded(file);
+        (0, logger_js_1.logWith)(opts, "info", "Remote JSON file loaded", {
+            url: fileUrl,
+        });
+        return file;
+    }));
+    return Promise.all(tasks);
+}
+/* -------------------------------------------------------------------------- */
+/*  LOCAL FILE JSON LOADER                                                    */
+/* -------------------------------------------------------------------------- */
+async function loadLocalJsonFile(filePath, opts) {
+    const stats = await promises_1.default.stat(filePath);
+    if (stats.size > opts.maxFileBytes) {
+        opts.onFileSkipped({
+            source: filePath,
+            reason: `File exceeds maxFileBytes=${opts.maxFileBytes}`,
+        });
+        (0, logger_js_1.logWith)(opts, "warn", "Skipping local file due to size limit", {
+            filePath,
+            size: stats.size,
+            maxFileBytes: opts.maxFileBytes,
+        });
+        throw new JsonLoaderError(`Local file too large: ${filePath} (${stats.size} bytes > ${opts.maxFileBytes}).`, "LOCAL_FILE_SIZE_ERROR");
+    }
+    const content = await promises_1.default.readFile(filePath, "utf8");
+    let raw;
+    try {
+        raw = JSON.parse(content);
+    }
+    catch (err) {
+        throw new JsonLoaderError(`Invalid JSON in file ${filePath}: ${err?.message ?? String(err)}`, "LOCAL_JSON_PARSE_ERROR");
+    }
+    const sanitized = sanitizePrototypePollution(raw, {
+        maxDepth: opts.maxJsonDepth,
+    });
+    const file = Object.freeze({
+        name: path_1.default.basename(filePath),
+        data: sanitized,
+        __source: filePath,
+    });
+    opts.onFileLoaded(file);
+    (0, logger_js_1.logWith)(opts, "info", "Local JSON file loaded", { filePath });
+    return file;
+}
+async function loadLocalDirectory(dirPath, opts, limitRun) {
+    const files = await promises_1.default.readdir(dirPath);
+    const jsonFiles = files.filter(isJsonFile);
+    if (jsonFiles.length === 0) {
+        (0, logger_js_1.logWith)(opts, "debug", "No JSON files found in directory", { dirPath });
+        return [];
+    }
+    if (jsonFiles.length > opts.maxFiles) {
+        throw new JsonLoaderError(`Directory ${dirPath} contains ${jsonFiles.length} JSON files, exceeding maxFiles=${opts.maxFiles}.`, "LOCAL_DIR_LIMIT_ERROR");
+    }
+    // Enforce total size limit
+    let totalSize = 0;
+    const filePaths = [];
+    for (const file of jsonFiles) {
+        const full = path_1.default.join(dirPath, file);
+        const stats = await promises_1.default.stat(full);
+        totalSize += stats.size;
+        if (totalSize > opts.maxTotalBytes) {
+            throw new JsonLoaderError(`Total size of JSON files in ${dirPath} exceeds maxTotalBytes=${opts.maxTotalBytes}.`, "LOCAL_DIR_TOTAL_SIZE_ERROR");
+        }
+        filePaths.push(full);
+    }
+    (0, logger_js_1.logWith)(opts, "debug", "Loading local directory", {
+        dirPath,
+        fileCount: filePaths.length,
+        totalSize,
+    });
+    const tasks = filePaths.map((filePath) => limitRun(() => loadLocalJsonFile(filePath, opts)));
+    return Promise.all(tasks);
+}
+/* -------------------------------------------------------------------------- */
+/*  PUBLIC API: SAFE JSON LOADER                                              */
+/* -------------------------------------------------------------------------- */
+/**
+ * Load one or more JSON resources from:
+ *  - Local file (.json)
+ *  - Local directory (all .json files)
+ *  - Remote URL returning JSON (object/array)
+ *  - Remote URL acting as an index of JSON URLs (array or { files: [] })
+ *
+ * Security features:
+ *  - Prototype‑pollution‑safe deep clone (strips __proto__, constructor, prototype)
+ *  - Max depth for parsed JSON structures
+ *  - Max file size and total directory size
+ *  - Concurrency limit for I/O (local and remote)
+ *  - HTTP timeout and content‑type checks
+ *
+ * This function does not enforce any domain/schema validation — callers
+ * should layer their own validation on top of the loaded `data`.
+ */
+async function loadSafeJsonResources(input, options) {
+    const inputStr = ensureStringInput(input);
+    if (!inputStr) {
+        throw new JsonLoaderError("Input path/URL must be a non-empty string.", "INPUT_VALIDATION_ERROR");
+    }
+    const opts = (0, logger_js_1.mergeOptions)(options);
+    const limitRun = createLimiter(opts.maxConcurrency);
+    /* ---------------------------------- REMOTE --------------------------------- */
+    if (isHttpUrl(inputStr)) {
+        const json = await loadRemoteJson(inputStr, opts);
+        if (Array.isArray(json) ||
+            (json &&
+                typeof json === "object" &&
+                Array.isArray(json.files))) {
+            return loadRemoteIndex(inputStr, json, opts, limitRun);
+        }
+        const file = Object.freeze({
+            name: path_1.default.basename(new URL(inputStr).pathname),
+            data: json,
+            __source: inputStr,
+        });
+        opts.onFileLoaded(file);
+        (0, logger_js_1.logWith)(opts, "info", "Remote JSON file loaded", { url: inputStr });
+        return [file];
+    }
+    /* ----------------------------------- LOCAL ---------------------------------- */
+    const resolved = path_1.default.resolve(inputStr);
+    let stats;
+    try {
+        stats = await promises_1.default.stat(resolved);
+    }
+    catch {
+        throw new JsonLoaderError(`Local path does not exist: ${resolved}`, "LOCAL_PATH_NOT_FOUND");
+    }
+    if (stats.isFile()) {
+        if (!isJsonFile(resolved)) {
+            throw new JsonLoaderError(`File is not a .json file: ${resolved}`, "LOCAL_FILE_EXTENSION_ERROR");
+        }
+        return [await loadLocalJsonFile(resolved, opts)];
+    }
+    if (stats.isDirectory()) {
+        return loadLocalDirectory(resolved, opts, limitRun);
+    }
+    throw new JsonLoaderError(`Unsupported path type: ${resolved}`, "LOCAL_PATH_TYPE_ERROR");
+}
+/**
+ * Safely parse and sanitize a JSON string.
+ *
+ * - Parses JSON with error handling
+ * - Strips prototype pollution keys (__proto__, constructor, prototype)
+ * - Enforces max depth
+ *
+ * @param input Raw JSON string
+ * @param opts  Loader options (maxJsonDepth, etc.)
+ * @returns Safe, sanitized JSON object
+ */
+function parseSafeJsonString(input, opts) {
+    let raw;
+    try {
+        raw = JSON.parse(input);
+    }
+    catch (err) {
+        throw new JsonLoaderError(`Invalid JSON string: ${err?.message ?? String(err)}`, "STRING_JSON_PARSE_ERROR");
+    }
+    const sanitized = sanitizePrototypePollution(raw, {
+        maxDepth: opts?.maxJsonDepth ?? 50,
+    });
+    return sanitized;
+}
+/**
+ * Sanitize an already-parsed JSON object.
+ *
+ * - Strips prototype pollution keys (__proto__, constructor, prototype)
+ * - Enforces max depth
+ *
+ * @param input Parsed JSON object (e.g. req.body in Express)
+ * @param opts  Loader options (maxJsonDepth, etc.)
+ * @returns Safe, sanitized JSON object
+ */
+function sanitizeParsedJsonObject(input, opts) {
+    const sanitized = sanitizePrototypePollution(input, {
+        maxDepth: opts?.maxJsonDepth ?? 50,
+    });
+    return sanitized;
+}
+//# sourceMappingURL=safeJsonLoader.js.map