@i4e/invest4edu-access-core 0.40.2 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.40.2",
+  "version": "0.42.0",
   "description": "Shared access-control primitives for NeoFindesk: tenant keystone, role capabilities, reportee tree, entity/role vocabulary, mobile app identity, feature flags, and the unified access engine (registry schema, snapshot resolver, visibleWhen).",
   "type": "module",
   "exports": {
@@ -30,7 +30,8 @@
     "./credits": "./src/credits.js"
   },
   "scripts": {
-    "test": "node --test test/*.test.mjs test/*.test.js"
+    "test": "node --test test/*.test.mjs test/*.test.js",
+    "prepublishOnly": "npm test"
   },
   "files": [
     "src",

package/src/client-profile/profile-service.js

@@ -18,10 +18,16 @@ import { buildSideFilter } from "./side-filter.js";
 import { FIELD_ACTIONS, evaluateFieldChanges, isPersonalLocked } from "./field-policy.js";
 import { PROFILE_TYPES } from "./settings.js";
 import { goalCreationStamp, goalVisibilityFilter } from "./goals.js";
+import { uccFieldsTouched } from "./ucc-followup.js";
 import { buildCapabilityMap, resolveCapabilities } from "../role-capabilities.js";
 import { CLIENT_APP_ROLE_NAMES } from "../portal-roles.js";
 
 const CLIENTS = "distributorclients";
+const UCC_RULES = "uccfieldrules";
+const INVESTOR_PROFILES = "clientinvestorprofiles";
+/** A stored UCC is an alphanumeric code; a failed call leaves BSE's error text there instead. */
+const REAL_UCC = /^[A-Za-z0-9]+$/;
+const UCC_RULES_TTL_MS = 60_000;
 
 /**
  * @param {{ getDb: Function, getSettings: Function, getSideContext?: Function,
@@ -302,5 +308,105 @@ export function createClientProfileService({ getDb, getSettings, getSideContext
     }
   }
 
-  return Object.freeze({ findActiveProfilesByPan, findExisting, attach, attachUser, resolveActor, sideFilterFor, evaluatePersonalEdit, goalContextFor });
+  /* ── UCC follow-up ──────────────────────────────────────────────────────────────────────────
+   * A client never pushes to BSE from the app. When their own successful edit changes a detail the
+   * product's UCC field rules sync to the UCC, the profile is flagged
+   * (`ucc_update_pending { fields, since, last_at, by }`) and the RM is told; backoffice or the RM
+   * runs the UCC update from the web, which clears it. Gated by modes.ucc_followup.
+   */
+  let uccRulesCache = { at: 0, product: null, doc: null };
+  async function uccRulesFor(productCode) {
+    if (uccRulesCache.product === productCode && now().getTime() - uccRulesCache.at < UCC_RULES_TTL_MS) return uccRulesCache.doc;
+    const doc = await db().collection(UCC_RULES).findOne({ product_code: productCode, is_active: { $ne: false } });
+    uccRulesCache = { at: now().getTime(), product: productCode, doc };
+    return doc;
+  }
+
+  /** After a SUCCESSFUL write by `userId` that changed `fields` of `clientId`. Never throws. */
+  async function noteClientUccEdit({ userId, clientId, fields } = {}) {
+    try {
+      const settings = getSettings();
+      if (!isEvaluated(settings, "ucc_followup") || !userId) return { flagged: false, reason: "mode_off" };
+      const cid = toId(clientId);
+      if (!cid) return { flagged: false, reason: "no_client" };
+      const actor = await resolveActor(userId);
+      if (actor?.callerClass !== CALLER_CLASSES.CLIENT) return { flagged: false, reason: "not_client" };
+      const touched = uccFieldsTouched(fields, await uccRulesFor(settings.ucc_followup.product_code));
+      if (!touched.length) return { flagged: false, reason: "no_ucc_fields" };
+      const hasUcc = await db().collection(INVESTOR_PROFILES).findOne(
+        { client_id: cid, "mf_details.ucc_code": { $regex: REAL_UCC } },
+        { projection: { _id: 1 } },
+      );
+      if (!hasUcc) return { flagged: false, reason: "no_ucc" };
+      if (!isEnforced(settings, "ucc_followup")) {
+        onAudit({ kind: "ucc_followup", client_id: clientId, fields: touched });
+        return { flagged: false, reason: "audit" };
+      }
+      const at = now();
+      await db().collection(CLIENTS).updateOne(
+        { _id: cid },
+        {
+          $addToSet: { "ucc_update_pending.fields": { $each: touched } },
+          $min: { "ucc_update_pending.since": at },
+          $set: { "ucc_update_pending.last_at": at, "ucc_update_pending.by": toId(userId) },
+        },
+      );
+      if (emit) {
+        Promise.resolve()
+          .then(() => emit(settings.events.ucc_update_pending, { client_id: String(clientId), fields: touched }, clientEventSubject(settings, clientId)))
+          .catch((err) => onAudit({ kind: "ucc_followup_event_error", client_id: clientId, message: err?.message }));
+      }
+      return { flagged: true, fields: touched };
+    } catch (err) {
+      onAudit({ kind: "ucc_followup_error", client_id: clientId, message: err?.message });
+      return { flagged: false, reason: "error" };
+    }
+  }
+
+  /**
+   * May this caller write to this client? A client-app session only to their own records — the
+   * same person's profiles under one master; portal callers are scoped by their own rules and
+   * always pass here. Gated by modes.own_records_only (audit logs, enforce refuses).
+   * @returns {Promise<{ allowed: boolean, reason?: string }>}
+   */
+  async function callerMayWriteClient({ userId, clientId } = {}) {
+    const settings = getSettings();
+    if (!isEvaluated(settings, "own_records_only") || !userId || !clientId) return { allowed: true };
+    let actor;
+    try {
+      actor = await resolveActor(userId);
+    } catch (err) {
+      onAudit({ kind: "own_records_error", client_id: clientId, message: err?.message });
+      return { allowed: true };
+    }
+    if (actor?.callerClass !== CALLER_CLASSES.CLIENT) return { allowed: true };
+    let own = [];
+    try {
+      const user = await db().collection("users").findOne({ _id: toId(userId) }, { projection: { client_id: 1 } });
+      if (user?.client_id) {
+        const master = await db().collection("masterchildclients").findOne({ child_client_ids: user.client_id }, { projection: { child_client_ids: 1 } });
+        own = (master?.child_client_ids?.length ? master.child_client_ids : [user.client_id]).map(String);
+      }
+    } catch (err) {
+      // A client session whose records cannot be read must not write anywhere.
+      onAudit({ kind: "own_records_error", client_id: clientId, message: err?.message });
+      return { allowed: !isEnforced(settings, "own_records_only"), reason: "unresolved" };
+    }
+    if (own.includes(String(clientId))) return { allowed: true };
+    onAudit({ kind: "own_records_only", client_id: clientId, user_id: String(userId) });
+    return { allowed: !isEnforced(settings, "own_records_only"), reason: "not_own_record" };
+  }
+
+  /** The UCC was updated: nothing is pending any more. Never throws. */
+  async function clearUccPending(clientId) {
+    try {
+      const cid = toId(clientId);
+      if (!cid) return;
+      await db().collection(CLIENTS).updateOne({ _id: cid, ucc_update_pending: { $exists: true } }, { $unset: { ucc_update_pending: "" } });
+    } catch (err) {
+      onAudit({ kind: "ucc_clear_error", client_id: clientId, message: err?.message });
+    }
+  }
+
+  return Object.freeze({ findActiveProfilesByPan, findExisting, attach, attachUser, resolveActor, sideFilterFor, evaluatePersonalEdit, goalContextFor, noteClientUccEdit, clearUccPending, callerMayWriteClient });
 }

package/src/client-profile/settings.js

@@ -73,6 +73,7 @@ export const DEFAULT_CLIENT_PROFILE_SETTINGS = deepFreeze({
     mf_one_investor: MODES.OFF,
     detail_scope: MODES.OFF,
     ucc_followup: MODES.OFF,
+    own_records_only: MODES.OFF,
   },
   corporate_distributor_types: [],
   house_distributor_codes: [],
@@ -186,6 +187,7 @@ export const CLIENT_PROFILE_SETTING_DESCRIPTIONS = Object.freeze({
   "modes.goal_approval": "Hold partner-added goals until the client approves them.",
   "modes.resolve_by_pan": "Show an existing client instead of a duplicate error when a PAN is found.",
   "modes.mf_one_investor": "Refuse a second MF investor for a person who already has one (D9).",
+  "modes.own_records_only": "A client-app session may write only its own records (one person under one master); anything else is refused.",
   "modes.ucc_followup": "Flag a profile for a UCC update when its client changes UCC details in the app (never pushed by the client).",
   "modes.detail_scope": "A client's full record by id only for callers whose client list includes them; everyone else gets the limited card (R15).",
   "modes.linked_visibility": "Clients reached only through a secondary mapping or a linked user appear in lists, as the limited card.",