@onlineapps/service-common 1.1.2 → 1.2.0

package/README.md

@@ -67,6 +67,41 @@ Waits for all infrastructure services to be reported as healthy by Registry.
 - `INFRASTRUCTURE_HEALTH_WAIT_MAX_TIME` - Maximum wait time in ms
 - `INFRASTRUCTURE_HEALTH_WAIT_CHECK_INTERVAL` - Check interval in ms
 
+### Scoped registry — `isVisible` / `sqlVisible` and friends
+
+The single home of the registry visibility rule: *a registry row is visible to a
+caller `{tenant_id, workspace_id}` iff it is `system`, or it is owned by exactly
+that workspace.* Business services must not hand-write this predicate.
+
+Normative contract: [`api/docs/biz/30-operations/scoped-registry.md`](../../docs/biz/30-operations/scoped-registry.md).
+
+| Export | Purpose |
+|---|---|
+| `isVisible(record, ctx)` | pure predicate — works over SQL rows, Redis, config files, connector responses |
+| `filterVisible(records, ctx)` | apply the predicate to a collection |
+| `pickVisibleOne(records, ctx)` | read-time resolution; throws on 0 or >1 visible rows (no precedence, no `LIMIT 1`) |
+| `sqlVisible(alias)` | the same rule as a `WHERE` fragment, for DB pushdown |
+| `sqlVisibleParams(ctx)` | named replacements (`__vis_tid`, `__vis_wid`) for that fragment |
+| `assertScopeTriple(record)` | write-time invariant: `scope='system' ⟺ owner columns NULL` |
+| `assertUniqueInScope(existingVisible, candidate, keyFn)` | write-time collision guard — refuses a definition that would shadow a visible one |
+
+```js
+const { sqlVisible, sqlVisibleParams } = require('@onlineapps/service-common');
+
+const rows = await sequelize.query(
+  `SELECT uuid, code FROM ing_connector c WHERE ${sqlVisible('c')}`,
+  { replacements: sqlVisibleParams(ctx), type: QueryTypes.SELECT }
+);
+```
+
+The predicate is the source of truth; the SQL fragment is a pushdown
+optimization. A parity unit test evaluates the fragment in-memory with SQL
+three-valued logic and fails if the two renderings ever disagree.
+
+All helpers fail fast: a missing or non-integer `tenant_id`/`workspace_id`
+throws rather than degrading into "system rows only", which would silently hide
+a workspace's own definitions.
+
 ## Architecture
 
 This library is used by:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-common",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "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/errors/BusinessError.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// See: docs/standards/error-handling-contract.md
+// See: docs/biz/70-contracts/error-handling.md
 const ERROR_TYPES = {
   TRANSIENT: 'TRANSIENT',
   BUSINESS: 'BUSINESS',

package/src/errors/errorMiddleware.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// See: docs/standards/error-handling-contract.md
+// See: docs/biz/70-contracts/error-handling.md
 const { BusinessError, isBusinessError } = require('./BusinessError');
 
 function businessErrorHandler(err, req, res, next) {

package/src/index.js

@@ -51,6 +51,23 @@ const {
   extractTenantContext,
   ROLES_VERSION_PREFIX
 } = require('./jwt');
+const {
+  REDACTED_PLACEHOLDER,
+  sensitiveFieldsForOperation,
+  redactSensitiveDeep
+} = require('./redactSensitive');
+const {
+  isVisible,
+  filterVisible,
+  pickVisibleOne,
+  sqlVisible,
+  sqlVisibleParams,
+  assertScopeTriple,
+  assertUniqueInScope,
+  ScopedRegistryError,
+  SCOPE_SYSTEM,
+  SCOPE_WORKSPACE
+} = require('./scopedRegistry');
 
 module.exports = {
   // Infrastructure readiness utilities (used by both infrastructure and business services)
@@ -98,7 +115,26 @@ 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,
+
+  // Scoped-registry visibility rule (system ∪ own workspace)
+  // See: docs/biz/30-operations/scoped-registry.md
+  isVisible,
+  filterVisible,
+  pickVisibleOne,
+  sqlVisible,
+  sqlVisibleParams,
+  assertScopeTriple,
+  assertUniqueInScope,
+  ScopedRegistryError,
+  SCOPE_SYSTEM,
+  SCOPE_WORKSPACE
 };
 
 

package/src/jwt/extractTenantContext.js

@@ -18,7 +18,7 @@
  * @returns {object} { tenant_id, tenant_uuid, workspace_id, person_id, person_uuid, role }
  * @throws {Error} with .statusCode = 400, 401, or 403
  */
-// See: docs/standards/tenant-context-contract.md
+// See: docs/biz/20-tenancy/tenant-context.md
 function extractTenantContext(auth, headers, options) {
   const { requireWorkspace = true } = options || {};
 

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
+};

package/src/scopedRegistry/ScopedRegistryError.js

@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+ * Error raised by the scoped-registry contract helpers.
+ *
+ * Message format follows ARCHITECTURE_PRINCIPLES §5:
+ *   [ScopedRegistry] Problem - Expected/Fix.
+ *
+ * `details` carries machine-readable context so a business service can map it
+ * onto its own domain error codes without re-parsing the message.
+ */
+class ScopedRegistryError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'ScopedRegistryError';
+    this.details = details;
+    Error.captureStackTrace(this, ScopedRegistryError);
+  }
+}
+
+module.exports = { ScopedRegistryError };

package/src/scopedRegistry/index.js

@@ -0,0 +1,260 @@
+'use strict';
+
+/**
+ * Scoped Registry — the one place the registry visibility rule lives.
+ *
+ * Contract: api/docs/biz/30-operations/scoped-registry.md
+ *
+ *   A registry row is visible to a caller {tenant_id, workspace_id} iff it is
+ *   `system`, or it is owned by exactly that workspace.
+ *
+ * The rule is rendered two ways: `isVisible` (pure predicate, works over any
+ * source — SQL rows, Redis, config files, connector responses) and `sqlVisible`
+ * (WHERE fragment, a pushdown optimization for DB-backed registries). The
+ * predicate is the source of truth; a parity unit test asserts the two agree.
+ *
+ * Pure module: no config, no env, no state (ARCHITECTURE_PRINCIPLES §1, §3).
+ */
+
+const { ScopedRegistryError } = require('./ScopedRegistryError');
+
+const SCOPE_SYSTEM = 'system';
+const SCOPE_WORKSPACE = 'workspace';
+const KNOWN_SCOPES = [SCOPE_SYSTEM, SCOPE_WORKSPACE];
+
+// SQL named replacements. Prefixed to avoid colliding with a caller's own
+// replacement keys in the same query.
+const PARAM_TENANT = '__vis_tid';
+const PARAM_WORKSPACE = '__vis_wid';
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Validate the caller context. Both identifiers are required integers — a
+ * missing or loosely-typed value must never degrade into "system rows only",
+ * which would silently hide a workspace's own definitions.
+ */
+function requireContext(ctx) {
+  if (!ctx || typeof ctx !== 'object') {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Missing caller context - Expected an object with integer tenant_id and workspace_id. '
+      + 'Fix: pass the ctx injected by the orchestrator.',
+      { ctx }
+    );
+  }
+  if (!Number.isInteger(ctx.tenant_id)) {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Invalid caller context - tenant_id must be an integer. '
+      + `Fix: pass ctx.tenant_id from the injected tenant context (got ${JSON.stringify(ctx.tenant_id)}).`,
+      { tenant_id: ctx.tenant_id }
+    );
+  }
+  if (!Number.isInteger(ctx.workspace_id)) {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Invalid caller context - workspace_id must be an integer. '
+      + `Fix: pass ctx.workspace_id from the injected tenant context (got ${JSON.stringify(ctx.workspace_id)}).`,
+      { workspace_id: ctx.workspace_id }
+    );
+  }
+  return { tenant_id: ctx.tenant_id, workspace_id: ctx.workspace_id };
+}
+
+function requireScope(record) {
+  if (!record || typeof record !== 'object') {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Missing record - Expected an object carrying scope, owner_tenant_id, owner_workspace_id. '
+      + 'Fix: pass a registry row.',
+      { record }
+    );
+  }
+  if (!KNOWN_SCOPES.includes(record.scope)) {
+    throw new ScopedRegistryError(
+      `[ScopedRegistry] Unknown scope "${record.scope}" - Expected '${SCOPE_SYSTEM}' or '${SCOPE_WORKSPACE}'. `
+      + 'Fix: correct the row, or add the new scope to the contract first.',
+      { scope: record.scope }
+    );
+  }
+  return record.scope;
+}
+
+/**
+ * The canonical visibility rule (§2.1).
+ *
+ * @param {{scope: string, owner_tenant_id: ?number, owner_workspace_id: ?number}} record
+ * @param {{tenant_id: number, workspace_id: number}} ctx
+ * @returns {boolean}
+ */
+function isVisible(record, ctx) {
+  const scope = requireScope(record);
+  const { tenant_id, workspace_id } = requireContext(ctx);
+
+  if (scope === SCOPE_SYSTEM) return true;
+
+  // A workspace row with NULL owners violates the §1.1 invariant. It is
+  // visible to nobody — matching SQL, where NULL = :tid yields NULL, not TRUE.
+  return record.owner_tenant_id === tenant_id
+      && record.owner_workspace_id === workspace_id;
+}
+
+/**
+ * Apply the rule to any in-memory collection (§2.1).
+ */
+function filterVisible(records, ctx) {
+  if (!Array.isArray(records)) {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Invalid records - Expected an array of registry rows. '
+      + `Fix: pass the collection to filter (got ${typeof records}).`,
+      { records }
+    );
+  }
+  requireContext(ctx);
+  return records.filter((record) => isVisible(record, ctx));
+}
+
+/**
+ * Read-time resolution with ambiguity fail-fast (§4.B).
+ *
+ * Never applies precedence: if both a system row and a workspace row are
+ * visible for one logical lookup, that is a collision that slipped past the
+ * write-time guard, and the caller gets an error rather than a silent winner.
+ */
+function pickVisibleOne(records, ctx) {
+  const visible = filterVisible(records, ctx);
+
+  if (visible.length === 0) {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] No visible record - Expected exactly one row visible to this caller. '
+      + 'Fix: check the lookup key, or register the definition for this workspace.',
+      { visibleCount: 0, tenant_id: ctx.tenant_id, workspace_id: ctx.workspace_id }
+    );
+  }
+  if (visible.length > 1) {
+    throw new ScopedRegistryError(
+      `[ScopedRegistry] Ambiguous record - ${visible.length} rows are visible for a single lookup, expected 1. `
+      + 'Fix: remove the shadowing definition; workspace rows must not overlap system ones.',
+      {
+        visibleCount: visible.length,
+        scopes: visible.map((r) => r.scope),
+        tenant_id: ctx.tenant_id,
+        workspace_id: ctx.workspace_id
+      }
+    );
+  }
+  return visible[0];
+}
+
+/**
+ * The same rule rendered as a SQL WHERE fragment (§2.2).
+ *
+ * Bind the returned fragment with `sqlVisibleParams(ctx)`. The alias is
+ * interpolated, so it is restricted to a plain identifier.
+ *
+ * @param {string} alias table alias used in the query
+ * @returns {string}
+ */
+function sqlVisible(alias) {
+  if (typeof alias !== 'string' || alias.trim() === '') {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Missing table alias - Expected a non-empty identifier. '
+      + "Fix: pass the alias used in the query, e.g. sqlVisible('c').",
+      { alias }
+    );
+  }
+  if (!IDENTIFIER.test(alias)) {
+    throw new ScopedRegistryError(
+      `[ScopedRegistry] Invalid table alias "${alias}" - Expected a plain identifier [A-Za-z_][A-Za-z0-9_]*. `
+      + 'Fix: alias the table in the query and pass that identifier.',
+      { alias }
+    );
+  }
+
+  return `(${alias}.scope = '${SCOPE_SYSTEM}' `
+    + `OR (${alias}.owner_tenant_id = :${PARAM_TENANT} AND ${alias}.owner_workspace_id = :${PARAM_WORKSPACE}))`;
+}
+
+/**
+ * Named replacements for the fragment returned by `sqlVisible` (§2.2).
+ */
+function sqlVisibleParams(ctx) {
+  const { tenant_id, workspace_id } = requireContext(ctx);
+  return { [PARAM_TENANT]: tenant_id, [PARAM_WORKSPACE]: workspace_id };
+}
+
+/**
+ * Enforce the scope triple invariant on write (§1.1):
+ * scope='system' ⟺ owner_tenant_id IS NULL AND owner_workspace_id IS NULL.
+ */
+function assertScopeTriple(record) {
+  const scope = requireScope(record);
+  const hasTenant = record.owner_tenant_id !== null && record.owner_tenant_id !== undefined;
+  const hasWorkspace = record.owner_workspace_id !== null && record.owner_workspace_id !== undefined;
+
+  if (scope === SCOPE_SYSTEM && (hasTenant || hasWorkspace)) {
+    throw new ScopedRegistryError(
+      "[ScopedRegistry] Invalid scope triple - a 'system' row must have owner_tenant_id and owner_workspace_id NULL. "
+      + "Fix: clear both owner columns, or set scope='workspace'.",
+      { scope, owner_tenant_id: record.owner_tenant_id, owner_workspace_id: record.owner_workspace_id }
+    );
+  }
+  if (scope === SCOPE_WORKSPACE && !(hasTenant && hasWorkspace)) {
+    throw new ScopedRegistryError(
+      "[ScopedRegistry] Invalid scope triple - a 'workspace' row must have both owner_tenant_id and owner_workspace_id set. "
+      + "Fix: set both owner columns, or set scope='system'.",
+      { scope, owner_tenant_id: record.owner_tenant_id, owner_workspace_id: record.owner_workspace_id }
+    );
+  }
+  return record;
+}
+
+/**
+ * Write-time collision guard (§4.A).
+ *
+ * Called with the set of rows already visible to the writer. If the candidate's
+ * business natural key is taken, registration is refused — a workspace can
+ * never persist a definition that shadows a system one.
+ *
+ * @param {Array} existingVisible rows already visible to the caller
+ * @param {Object} candidate the row about to be written
+ * @param {Function} keyFn maps a row to its business natural key
+ */
+function assertUniqueInScope(existingVisible, candidate, keyFn) {
+  if (!Array.isArray(existingVisible)) {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Invalid existing set - Expected an array of rows already visible to the writer. '
+      + 'Fix: load the caller-visible set before registering.',
+      { existingVisible }
+    );
+  }
+  if (typeof keyFn !== 'function') {
+    throw new ScopedRegistryError(
+      '[ScopedRegistry] Missing key function - Expected a function mapping a row to its business natural key. '
+      + "Fix: pass e.g. (r) => `${r.code}/${r.version}`.",
+      { keyFn }
+    );
+  }
+
+  const candidateKey = keyFn(candidate);
+  const occupant = existingVisible.find((row) => keyFn(row) === candidateKey);
+
+  if (occupant) {
+    throw new ScopedRegistryError(
+      `[ScopedRegistry] Range occupied - "${candidateKey}" is already defined in scope "${occupant.scope}". `
+      + 'Fix: choose a different key, or reuse the existing definition.',
+      { key: candidateKey, occupiedByScope: occupant.scope }
+    );
+  }
+  return candidate;
+}
+
+module.exports = {
+  isVisible,
+  filterVisible,
+  pickVisibleOne,
+  sqlVisible,
+  sqlVisibleParams,
+  assertScopeTriple,
+  assertUniqueInScope,
+  ScopedRegistryError,
+  SCOPE_SYSTEM,
+  SCOPE_WORKSPACE
+};