@ktuban/safe-json-loader 1.1.0

package/dist/types/types.d.ts

@@ -0,0 +1,111 @@
+import type { PathLike } from "fs";
+import type { URL } from "url";
+export type JsonPrimitive = string | number | boolean | null;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export interface JsonArray extends Array<JsonValue> {
+}
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+export interface LoadedJsonFile {
+    /** Logical name (basename of path or URL) */
+    name: string;
+    /** Parsed and security‑sanitized JSON data */
+    data: JsonValue;
+    /** Original source (absolute path or URL) */
+    __source: string;
+}
+/**
+ * High‑level logging categories.
+ * Keeps the core loader decoupled from any concrete logging framework.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Abstract logger interface the loader will use.
+ * Callers can pass a custom implementation (winston/pino/console/etc.).
+ */
+export interface JsonLoaderLogger {
+    log(level: LogLevel, message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Options for safe JSON loading.
+ */
+export interface SafeJsonLoaderOptions {
+    /**
+     * Maximum number of JSON files to load per call
+     * (applies to local directories and remote indexes).
+     * Default: 100
+     */
+    maxFiles?: number;
+    /**
+     * Maximum total bytes for all local JSON files combined.
+     * Default: 10 MB
+     */
+    maxTotalBytes?: number;
+    /**
+     * Maximum bytes per local JSON file.
+     * Default: 2 MB
+     */
+    maxFileBytes?: number;
+    /**
+     * HTTP timeout per remote request in milliseconds.
+     * Default: 8000
+     */
+    httpTimeoutMs?: number;
+    /**
+     * Maximum number of concurrent I/O operations (local reads + remote fetches).
+     * Default: 5
+     */
+    maxConcurrency?: number;
+    /**
+     * If true, accept any content‑type containing "json".
+     * If false, require "application/json".
+     * Default: true
+     */
+    looseJsonContentType?: boolean;
+    /**
+     * Maximum allowed depth of parsed JSON structures.
+     * Helps mitigate very deep payloads used for DoS.
+     * Default: 50
+     */
+    maxJsonDepth?: number;
+    /**
+     * Optional logger implementation.
+     * If omitted, a no‑op logger is used.
+     */
+    logger?: JsonLoaderLogger;
+    /**
+     * Optional hook invoked after each file is successfully loaded and sanitized.
+     */
+    onFileLoaded?: (file: LoadedJsonFile) => void;
+    /**
+     * Optional hook invoked when a file is skipped due to limits.
+     */
+    onFileSkipped?: (info: {
+        source: string;
+        reason: string;
+    }) => void;
+}
+/**
+ * Internal fully‑resolved options shape (after merging defaults).
+ */
+export interface ResolvedSafeJsonLoaderOptions extends SafeJsonLoaderOptions {
+    maxFiles: number;
+    maxTotalBytes: number;
+    maxFileBytes: number;
+    httpTimeoutMs: number;
+    maxConcurrency: number;
+    looseJsonContentType: boolean;
+    maxJsonDepth: number;
+    logger: JsonLoaderLogger;
+    onFileLoaded: (file: LoadedJsonFile) => void;
+    onFileSkipped: (info: {
+        source: string;
+        reason: string;
+    }) => void;
+}
+/**
+ * Input accepted by the loader: either a path‑like or a URL string.
+ * We keep it simple: callers pass a string; we decide if it’s local or remote.
+ */
+export type JsonLoadInput = string | PathLike | URL;

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@ktuban/safe-json-loader",
+  "version": "1.1.0",
+  "description": "A security‑hardened JSON loader with prototype‑pollution protection, depth limits, safe parsing, and optional validation layers.",
+  "keywords": [
+    "json",
+    "loader",
+    "security",
+    "prototype-pollution",
+    "sanitization",
+    "safe-parse",
+    "validation",
+    "backend",
+    "nodejs",
+    "library"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "K",
+    "url": "https://github.com/ktuban"
+  },
+  "private": false,
+  "type": "module",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ktuban/safe-json-loader.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ktuban/safe-json-loader/issues"
+  },
+  "homepage": "https://github.com/ktuban/safe-json-loader#readme",
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "npm run clean && npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "tsc --project tsconfig.json --outDir dist/esm --module ES2022",
+    "build:cjs": "tsc --project tsconfig.json --outDir dist/cjs --module CommonJS --declaration false",
+    "build:types": "tsc --project tsconfig.types.json --emitDeclarationOnly --outDir dist/types",
+    "lint": "eslint . --ext .ts",
+    "prepare": "npm run build",
+    "test": "node ./dist/esm/test.js",
+    "start": "node ./dist/esm/index.js"
+  },
+  "dependencies": {
+    "node-fetch": "^3.3.2",
+    "safe-json-stringify":"^1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.7",
+    "@typescript-eslint/eslint-plugin": "^8.53.0",
+    "@typescript-eslint/parser": "^8.53.0",
+    "eslint": "^9.39.2",
+    "rimraf": "^6.1.2",
+    "typescript": "^5.9.3",
+    "@types/safe-json-stringify": "^1.1.5"
+  }
+}