@onlineapps/service-common 1.1.3 → 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.3",
+  "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

@@ -56,6 +56,18 @@ const {
   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)
@@ -109,7 +121,20 @@ module.exports = {
   // See: docs/architecture/secretbox.md §8
   REDACTED_PLACEHOLDER,
   sensitiveFieldsForOperation,
-  redactSensitiveDeep
+  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/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
+};