payload-guard-filter 1.0.1 → 1.2.0

package/dist/cli.js

@@ -149,16 +149,57 @@ function init() {
     console.log('  2. Import shapes into your Express routes');
     console.log('  3. Use res.guardJson(shape, data) to filter responses\n');
 }
+function sync() {
+    const targetDir = process.cwd();
+    const shapesDir = path.join(targetDir, 'src', 'shapes');
+    const outputPath = path.join(targetDir, 'src', 'types', 'generated.ts');
+    console.log('\n🔄 payload-guard sync\n');
+    if (!fs.existsSync(shapesDir)) {
+        console.log(`❌ Shapes directory not found: ${shapesDir}`);
+        console.log('Use "npx payload-guard init" to create basic shapes first.\n');
+        return;
+    }
+    const files = fs.readdirSync(shapesDir).filter(f => f.endsWith('.ts'));
+    if (files.length === 0) {
+        console.log('⚠️ No shape files found to sync.\n');
+        return;
+    }
+    let content = `/**\n * Generated by payload-guard sync\n * DO NOT EDIT MANUALLY\n */\n\nimport { InferShape } from 'payload-guard';\n`;
+    files.forEach(file => {
+        const filePath = path.join(shapesDir, file);
+        const fileName = path.parse(file).name;
+        const fileContent = fs.readFileSync(filePath, 'utf8');
+        // Simple regex to find exported shapes
+        const exportRegex = /export const (\w+) = (guard\.shape|buildShape)\(/g;
+        let match;
+        content += `\n// From ${file}\nimport * as ${fileName}Shapes from '../shapes/${fileName}';\n`;
+        while ((match = exportRegex.exec(fileContent)) !== null) {
+            const shapeName = match[1];
+            const typeName = shapeName.endsWith('Shape')
+                ? shapeName.replace('Shape', '')
+                : shapeName.charAt(0).toUpperCase() + shapeName.slice(1);
+            content += `export type ${typeName} = InferShape<typeof ${fileName}Shapes.${shapeName}>;\n`;
+        }
+    });
+    const outputDir = path.dirname(outputPath);
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+    }
+    fs.writeFileSync(outputPath, content);
+    console.log(`✅ Generated types in: ${outputPath}\n`);
+}
 function showHelp() {
     console.log(`
 🛡️  payload-guard CLI
 
 Usage:
   npx payload-guard init    Create example files in current directory
+  npx payload-guard sync    Sync shapes to TypeScript types
   npx payload-guard help    Show this help message
 
 Examples:
   npx payload-guard init
+  npx payload-guard sync
   `);
 }
 // Parse arguments
@@ -168,6 +209,9 @@ switch (command) {
     case 'init':
         init();
         break;
+    case 'sync':
+        sync();
+        break;
     case 'help':
     case '--help':
     case '-h':

package/dist/core/compiler.d.ts

@@ -5,6 +5,10 @@ interface CompileOptions {
     strict?: boolean;
     redact?: (key: string, value: unknown) => unknown;
     logger?: (msg: string, level?: 'warn' | 'error' | 'info') => void;
+    /** Maximum array length to process (memory safety) */
+    maxArrayLength?: number;
+    /** Parent path for nested field warnings (internal) */
+    _parentPath?: string;
 }
 /**
  * Compile a shape descriptor into an optimized filter function

package/dist/core/compiler.js

@@ -57,11 +57,20 @@ function compile(shape, opts = {}) {
     }
     // Array shape
     if (isArrayShape(shape)) {
-        const itemFn = compile(shape.item, opts);
+        const itemFn = compile(shape.item, { ...opts, _parentPath: (opts._parentPath || '') + '[]' });
         return (value) => {
             if (!Array.isArray(value))
                 return [];
-            return value.map(item => {
+            // Memory safety: slice array if maxArrayLength is set
+            let arr = value;
+            if (opts.maxArrayLength && arr.length > opts.maxArrayLength) {
+                if (opts.dev) {
+                    const path = opts._parentPath || 'array';
+                    (opts.logger ?? console.warn)(`[payload-guard] ${path}: array truncated from ${arr.length} to ${opts.maxArrayLength} items (maxArrayLength)`, 'warn');
+                }
+                arr = arr.slice(0, opts.maxArrayLength);
+            }
+            return arr.map(item => {
                 try {
                     return itemFn(item);
                 }
@@ -92,7 +101,7 @@ function compile(shape, opts = {}) {
             }
             continue;
         }
-        fieldFilters[key] = compile(shapeObj[key], opts);
+        fieldFilters[key] = compile(shapeObj[key], { ...opts, _parentPath: (opts._parentPath ? opts._parentPath + '.' : '') + key });
     }
     return (value) => {
         if (value == null || typeof value !== 'object')

package/dist/core/perf.d.ts

@@ -1,7 +1,10 @@
 export declare function byteSize(v: unknown): number;
+export declare function formatBytes(bytes: number): string;
 export declare function metric(before: unknown, after: unknown): {
     before: number;
     after: number;
     saved: number;
     percent: number;
+    formatBefore: string;
+    formatAfter: string;
 };

package/dist/core/perf.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.byteSize = byteSize;
+exports.formatBytes = formatBytes;
 exports.metric = metric;
 function byteSize(v) {
     try {
@@ -10,10 +11,25 @@ function byteSize(v) {
         return 0;
     }
 }
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + sizes[i];
+}
 function metric(before, after) {
     const b = byteSize(before);
     const a = byteSize(after);
     const saved = Math.max(0, b - a);
     const pct = b === 0 ? 0 : Math.round((saved / b) * 10000) / 100;
-    return { before: b, after: a, saved, percent: pct };
+    return {
+        before: b,
+        after: a,
+        saved,
+        percent: pct,
+        formatBefore: formatBytes(b),
+        formatAfter: formatBytes(a)
+    };
 }

package/dist/core/types.d.ts

@@ -31,14 +31,26 @@ export interface GuardConfig {
     strict?: boolean;
     /** Redaction hook: return replacement value for a key */
     redact?: (key: string, value: unknown) => unknown;
-    /** Logger integration hook */
+    /**
+     * Logger integration hook for custom logging (pino, winston, etc.)
+     * @example
+     * logger: (msg, level) => pino[level || 'info'](msg)
+     */
     logger?: (msg: string, level?: 'warn' | 'error' | 'info') => void;
     /** Maximum payload size (bytes) for middleware processing; if exceeded, processing is skipped */
     maxPayloadSize?: number;
+    /** Skip processing if payload exceeds maxPayloadSize (default: true) */
+    skipLargePayload?: boolean;
+    /** Maximum array length to process (memory safety) */
+    maxArrayLength?: number;
     /** Routes to ignore (prefix match) */
     ignoreRoutes?: string[];
     /** Enable payload metrics (measure before/after sizes) */
     payloadMetrics?: boolean;
+    /** Sanitize request headers (remove sensitive headers) */
+    sanitizeHeaders?: boolean;
+    /** Sensitive header names to filter (default: authorization, cookie, x-api-key) */
+    sensitiveHeaders?: string[];
 }
 export interface GuardMiddlewareOptions extends GuardConfig {
     /** Sanitize request body */

package/dist/middleware/express.js

@@ -19,10 +19,12 @@ const security_1 = require("../core/security");
  * ```
  */
 function guardMiddleware(opts = {}) {
-    const { sanitizeBody = false, requestShape, sensitiveFields = [], devMode = false, filterResponse = false, maxPayloadSize, ignoreRoutes = [], payloadMetrics = false, } = opts;
+    const { sanitizeBody = false, requestShape, sensitiveFields = [], devMode = false, filterResponse = false, maxPayloadSize, skipLargePayload = true, maxArrayLength, ignoreRoutes = [], payloadMetrics = false, sanitizeHeaders = false, sensitiveHeaders = ['authorization', 'cookie', 'x-api-key', 'x-auth-token'], } = opts;
+    // Default sensitive headers
+    const DEFAULT_SENSITIVE_HEADERS = ['authorization', 'cookie', 'x-api-key', 'x-auth-token', 'x-session-id'];
     // Pre-compile request shape if provided
     const compiledRequestShape = requestShape
-        ? (0, compiler_1.compile)(requestShape, { sensitive: sensitiveFields, dev: devMode })
+        ? (0, compiler_1.compile)(requestShape, { sensitive: sensitiveFields, dev: devMode, maxArrayLength, logger: opts.logger })
         : null;
     // Response filter cache for shapes to avoid recompiling per request
     const responseFilterCache = new WeakMap();
@@ -32,6 +34,20 @@ function guardMiddleware(opts = {}) {
             if (ignoreRoutes && ignoreRoutes.some(p => req.path.startsWith(p))) {
                 return next();
             }
+            const routeName = `[${req.method}] ${req.path}`;
+            // Sanitize headers if enabled
+            if (sanitizeHeaders && req.headers) {
+                const allSensitiveHeaders = [...DEFAULT_SENSITIVE_HEADERS, ...(sensitiveHeaders || [])];
+                for (const header of allSensitiveHeaders) {
+                    const headerLower = header.toLowerCase();
+                    if (req.headers[headerLower]) {
+                        if (devMode) {
+                            (opts.logger ?? console.warn)(`[payload-guard] ${routeName}: Sensitive header "${header}" removed`, 'warn');
+                        }
+                        delete req.headers[headerLower];
+                    }
+                }
+            }
             // Sanitize request body
             if (sanitizeBody && req.body && typeof req.body === 'object') {
                 // max payload size check
@@ -40,9 +56,17 @@ function guardMiddleware(opts = {}) {
                         const size = Buffer.byteLength(JSON.stringify(req.body || ''), 'utf8');
                         if (size > maxPayloadSize) {
                             if (devMode) {
-                                opts.logger?.('[payload-guard] payload exceeds maxPayloadSize; skipping sanitization', 'warn');
+                                (opts.logger ?? console.warn)(`[payload-guard] ${routeName}: payload exceeds maxPayloadSize (${size} > ${maxPayloadSize} bytes)`, 'warn');
+                            }
+                            // Skip processing if skipLargePayload is true (default), else still process
+                            if (!skipLargePayload) {
+                                if (compiledRequestShape) {
+                                    req.body = compiledRequestShape(req.body);
+                                }
+                                else {
+                                    req.body = (0, security_1.removeSensitive)(req.body, sensitiveFields);
+                                }
                             }
-                            // do not block; skip processing
                         }
                         else {
                             if (compiledRequestShape) {
@@ -56,7 +80,7 @@ function guardMiddleware(opts = {}) {
                     catch (e) {
                         // if serialization fails, skip and continue
                         if (devMode)
-                            opts.logger?.('[payload-guard] error checking payload size: ' + String(e), 'warn');
+                            (opts.logger ?? console.warn)('[payload-guard] error checking payload size: ' + String(e), 'warn');
                     }
                 }
                 else {
@@ -68,13 +92,20 @@ function guardMiddleware(opts = {}) {
                     }
                 }
             }
-            // Dev mode: warn about sensitive fields in request
+            // Dev mode: warn about sensitive fields in request with full path
             if (devMode && req.body && typeof req.body === 'object') {
-                for (const key of Object.keys(req.body)) {
-                    if ((0, security_1.isSensitive)(key, sensitiveFields)) {
-                        console.warn(`[payload-guard] ⚠️ Sensitive field "${key}" present in request body`);
+                const warnSensitive = (obj, path) => {
+                    for (const key of Object.keys(obj)) {
+                        const fullPath = path ? `${path}.${key}` : key;
+                        if ((0, security_1.isSensitive)(key, sensitiveFields)) {
+                            (opts.logger ?? console.warn)(`[payload-guard] ${routeName}: Unexpected field: ${fullPath}`, 'warn');
+                        }
+                        if (obj[key] && typeof obj[key] === 'object' && !Array.isArray(obj[key])) {
+                            warnSensitive(obj[key], fullPath);
+                        }
                     }
-                }
+                };
+                warnSensitive(req.body, '');
             }
             // Attach guardJson helper to response
             res.guardJson = function (shape, data) {
@@ -109,13 +140,18 @@ function guardMiddleware(opts = {}) {
                     const isStreamLike = data && typeof data.pipe === 'function';
                     if (isStreamLike)
                         return res.json(data);
+                    // timing start
+                    const start = performance.now();
                     const filtered = filterFn(data);
+                    const end = performance.now();
+                    const duration = (end - start).toFixed(2);
                     // metrics
                     if (payloadMetrics) {
                         try {
                             const { metric } = require('../core/perf');
                             const m = metric(data, filtered);
-                            opts.logger?.(`[payload-guard] payload metrics: reduced ${m.before}→${m.after} bytes (${m.percent}%)`, 'info');
+                            const reduction = `reduced ${m.formatBefore} -> ${m.formatAfter} (${m.percent}%)`;
+                            (opts.logger ?? console.info)(`[payload-guard] ${routeName}: ${reduction} in ${duration}ms`, 'info');
                         }
                         catch { }
                     }

package/package.json

@@ -1,23 +1,23 @@
 {
   "name": "payload-guard-filter",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Lightweight, zero-dependency shape-based payload filtering and sanitization for Node.js and browser",
   "main": "dist/index.js",
-  "module": "dist/index.mjs",
+  "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.mjs",
+      "import": "./dist/index.js",
       "require": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
     "./express": {
-      "import": "./dist/express.mjs",
+      "import": "./dist/express.js",
       "require": "./dist/express.js",
       "types": "./dist/express.d.ts"
     },
     "./client": {
-      "import": "./dist/client.mjs",
+      "import": "./dist/client.js",
       "require": "./dist/client.js",
       "types": "./dist/client.d.ts"
     }
@@ -41,7 +41,8 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "lint": "eslint src --ext .ts",
-    "format": "prettier --write \"src/**/*.ts\""
+    "format": "prettier --write \"src/**/*.ts\"",
+    "benchmark": "npx ts-node benchmarks/run.ts"
   },
   "keywords": [
     "payload",
@@ -59,6 +60,7 @@
   ],
   "author": "",
   "license": "MIT",
+  "sideEffects": false,
   "engines": {
     "node": ">=18.0.0"
   },