@onlineapps/service-common 1.1.1 → 1.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-common",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Common utilities for both infrastructure services and business services (JWT auth, Redis/Postgres clients, business errors, runtime config)",
   "main": "src/index.js",
   "scripts": {

package/src/index.js

@@ -51,6 +51,11 @@ const {
   extractTenantContext,
   ROLES_VERSION_PREFIX
 } = require('./jwt');
+const {
+  REDACTED_PLACEHOLDER,
+  sensitiveFieldsForOperation,
+  redactSensitiveDeep
+} = require('./redactSensitive');
 
 module.exports = {
   // Infrastructure readiness utilities (used by both infrastructure and business services)
@@ -98,7 +103,13 @@ module.exports = {
   verifyAccessToken,
   createJwtValidator,
   extractTenantContext,
-  ROLES_VERSION_PREFIX
+  ROLES_VERSION_PREFIX,
+
+  // Sensitive-input redaction for observability sinks (SecretBox F1.5)
+  // See: docs/architecture/secretbox.md §8
+  REDACTED_PLACEHOLDER,
+  sensitiveFieldsForOperation,
+  redactSensitiveDeep
 };
 
 

package/src/redactSensitive.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * Sensitive-input redaction (SecretBox F1.5).
+ * Contract: api/docs/architecture/secretbox.md §8.
+ *
+ * Pure, dependency-free helpers used by every layer that logs, traces, or
+ * otherwise persists workflow/operation inputs (gateway, orchestrator, monitoring
+ * consumer). Single implementation — no duplication across layers.
+ *
+ * Operations declare sensitive input fields at operation level in operations.json:
+ *   "sensitive_input_fields": ["value", ...]
+ * (NOT inside the JSON Schema — service-wrapper compiles input schemas with AJV
+ * strict:true, which throws on unknown keywords.)
+ *
+ * `redactSensitiveDeep` deep-clones the value and replaces any object key whose
+ * name is in `fieldNames` with the REDACTED placeholder, at any depth. It never
+ * mutates the input. Over-redaction (a sensitive field name matching elsewhere in
+ * the same payload) is acceptable and safe for observability sinks.
+ *
+ * IMPORTANT: this is for observability/log/trace copies only. The execution message
+ * that carries the value to its owning handler MUST NOT be redacted.
+ */
+
+const REDACTED_PLACEHOLDER = '[REDACTED]';
+const CIRCULAR_PLACEHOLDER = '[Circular]';
+
+/**
+ * Extract the sensitive input field names for one operation from a service spec
+ * (the `registry:service:<name>:spec` shape, or a local operations.json object).
+ * @param {object} serviceSpec - object with `.operations[<op>]`.
+ * @param {string} operationName
+ * @returns {string[]} field names (empty array when none / not found).
+ */
+function sensitiveFieldsForOperation(serviceSpec, operationName) {
+  const op =
+    serviceSpec &&
+    serviceSpec.operations &&
+    typeof serviceSpec.operations === 'object'
+      ? serviceSpec.operations[operationName]
+      : undefined;
+  const list = op && op.sensitive_input_fields;
+  return Array.isArray(list) ? list.filter((f) => typeof f === 'string' && f.length > 0) : [];
+}
+
+function _walk(node, fields, seen) {
+  if (node === null || typeof node !== 'object') return node;
+  // Do not recurse into non-plain objects; return a shallow copy where safe.
+  if (node instanceof Date) return new Date(node.getTime());
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(node)) return node;
+  if (seen.has(node)) return CIRCULAR_PLACEHOLDER;
+  seen.add(node);
+
+  if (Array.isArray(node)) {
+    return node.map((el) => _walk(el, fields, seen));
+  }
+
+  const out = {};
+  for (const key of Object.keys(node)) {
+    if (fields.has(key)) {
+      out[key] = REDACTED_PLACEHOLDER;
+    } else {
+      out[key] = _walk(node[key], fields, seen);
+    }
+  }
+  return out;
+}
+
+/**
+ * Deep-clone `value`, replacing any object property named in `fieldNames` with
+ * the REDACTED placeholder. Does not mutate the input.
+ * @param {*} value - any JSON-ish value (object/array/primitive).
+ * @param {string[]|Set<string>} fieldNames - sensitive field names to redact.
+ * @returns {*} redacted deep clone (or the original value when there is nothing
+ *   to redact — no sensitive fields means no mutation risk).
+ */
+function redactSensitiveDeep(value, fieldNames) {
+  const fields = fieldNames instanceof Set ? fieldNames : new Set(fieldNames || []);
+  if (fields.size === 0) return value;
+  return _walk(value, fields, new WeakSet());
+}
+
+module.exports = {
+  REDACTED_PLACEHOLDER,
+  sensitiveFieldsForOperation,
+  redactSensitiveDeep
+};