xypriss 9.12.40 → 9.12.41

package/dist/index.d.ts

@@ -321,18 +321,88 @@ interface PaginationInfo {
  * Configuration for internal response manipulation.
  *
 /**
- * Rules for masking or replacing fields in responses.
+ * Defines a rule for masking, replacing, or redacting field keys/values in JSON responses.
+ *
+ * Response manipulation rules are processed natively by XHSC (Go engine) with zero Node.js overhead.
+ * They allow automatic redaction of sensitive credentials, PII (emails, API keys), and system file paths.
+ *
+ * @see {@link https://xypriss.nehonix.com/docs/security/response-manipulation}
+ *
+ * @example
+ * ### 1. Redact Internal System Paths in Error Messages (`replaceMatch`)
+ * ```ts
+ * {
+ *   valuePattern: /(?<=\s|^|["':(])(?:[a-zA-Z]:[/\\][a-zA-Z0-9_.-]+(?:[/\\][a-zA-Z0-9_.-]+)*|\/(?:[a-zA-Z0-9_.-]+\/)+[a-zA-Z0-9_.-]*)/g,
+ *   replaceMatch: "[REDACTED_PATH]",
+ * }
+ * // Input:  { error: "fs.move failed: /tmp/xuser/521f00d8/file.jpg to /storage/public" }
+ * // Output: { error: "fs.move failed: [REDACTED_PATH] to [REDACTED_PATH]" }
+ * ```
+ *
+ * @example
+ * ### 2. Partial Masking of API Keys preserving prefix (`preserve`)
+ * ```ts
+ * {
+ *   field: "api_key",
+ *   preserve: 4,
+ * }
+ * // Input:  { api_key: "xy_live_998877665544332211" }
+ * // Output: { api_key: "xy_l********************" }
+ * ```
+ *
+ * @example
+ * ### 3. Complete Field Replacement (`replacement`)
+ * ```ts
+ * {
+ *   field: "user.password",
+ *   replacement: "********",
+ * }
+ * // Input:  { user: { password: "mySecretPassword123" } }
+ * // Output: { user: { password: "********" } }
+ * ```
  *
  * @interface ResponseManipulationRule
  */
 interface ResponseManipulationRule {
-    /** Field name (dot notation) or RegExp pattern for matching keys */
+    /**
+     * Target field name (dot notation e.g., `"user.password"`) or RegExp pattern for matching JSON keys.
+     * If omitted, the rule evaluates against all JSON string values using `valuePattern`.
+     */
     field?: string | RegExp;
-    /** RegExp pattern for matching field values */
+    /**
+     * RegExp pattern for matching string field values (e.g. matching file paths, email formats, or JWT tokens).
+     */
     valuePattern?: RegExp;
-    /** Mask string (e.g., "****") or replacement value */
+    /**
+     * Replacement string for replacing **ONLY the matched substring** (via regex substitution)
+     * instead of replacing the entire JSON field value.
+     *
+     * @example
+     * // Replaces "/tmp/secret.png" with "[REDACTED_PATH]" inside a longer error string
+     * replaceMatch: "[REDACTED_PATH]"
+     */
+    replaceMatch?: string;
+    /**
+     * When set to `true`, forces `replacement` to operate as a substring replacement for `valuePattern`
+     * matches rather than replacing the entire field value.
+     * @default false
+     */
+    replaceOnlyMatch?: boolean;
+    /**
+     * Replacement value or mask string for replacing the **ENTIRE field value**.
+     * Can be a string, number, boolean, or object.
+     *
+     * @example
+     * replacement: "[MASKED_CREDENTIAL]"
+     */
     replacement?: any;
-    /** Number of characters to preserve (at the beginning) for string masking */
+    /**
+     * Number of initial characters to preserve unmasked when masking string values.
+     *
+     * @example
+     * // preserve: 4 on "123456789" produces "1234*****"
+     * preserve: 4
+     */
     preserve?: number;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xypriss",
-    "version": "9.12.40",
+    "version": "9.12.41",
     "description": "XyPriss is a high-performance, TypeScript-first hyper-system web framework powered by a native Go core (XHSC), featuring robust multi-tenant sandboxing, secure native file streaming, and zero Express dependencies.",
     "author": {
         "DEV.to": "https://dev.to/nehonix",