@i4e/invest4edu-access-core 0.37.0 → 0.39.0

package/README.md

@@ -115,6 +115,16 @@ Model.find(q).setOptions({ skipTenant: true });          // one query
 - `MOBILE_LOGIN_SOURCES`, `CLIENT_APP_LOGIN_SOURCES`, `PARTNER_APP_HATS`,
   `APP_BUNDLE_ID_PATTERN`, `appBundleIdOf` (`/mobile-app-identity`) — which mobile app a login
   came from, which hats it flags, and the bundle id its session keeps
+- `clientProfile` namespace (`/client-profile`) — the two-profile client model. Settings
+  (`resolveClientProfileSettings`, `MODES`, collection names), sides and tagging (`sideKeyOf`,
+  `profileTypeFor`, `orderSideFor`, `primaryLockFor`, `primaryFromLead`), access level
+  (`clientAccessFor`, `callerClassOf`, `linkedViewOf`), the side filter (`buildSideFilter`) and
+  the personal-details field policy (`buildFieldPolicyIndex`, `evaluateFieldChanges`,
+  `effectivePolicyFor`, `changedFields`). Every behaviour is read from a `clientprofilesettings`
+  document and each has an `off | audit | enforce` mode, defaulting to `off`. Business
+  identifiers (distributor codes, role names, product codes) have EMPTY defaults and come from
+  each environment's settings document. Design and tracker:
+  https://claude.ai/artifact/JrCTutgQkp32r3NeU2uvmk
 
 ## Not covered
 **Aggregation pipelines** — add an explicit `{ $match: { account_id } }` stage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.37.0",
+  "version": "0.39.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": {
@@ -22,6 +22,7 @@
     "./route-features": "./src/route-features.js",
     "./route-screen": "./src/route-screen.js",
     "./report-audience": "./src/report-audience.js",
+    "./client-profile": "./src/client-profile/index.js",
     "./mobile-app-identity": "./src/mobile-app-identity.js",
     "./subscription-lifecycle": "./src/subscription-lifecycle.js",
     "./entitlement-store": "./src/entitlement-store.js",

package/src/client-profile/access.js

@@ -0,0 +1,149 @@
+/**
+ * Access level on a client — full, linked or none — and who the caller is.
+ *
+ * ── The rule ─────────────────────────────────────────────────────────────────────────────────
+ * A caller's view of a client depends on HOW they reach it, not only whether they can:
+ *
+ *   full    — they own it: the client's E1, RM, partner RM or creator is them or a reportee; its
+ *             distributor is one whose RM they are (the source arm); they hold whole-book access;
+ *             or their firm is the client's PRIMARY distributor.
+ *   linked  — they reach it only because they did business on it: a secondary distributor
+ *             mapping for their firm, or a `linked_users` entry for them or a reportee. They get
+ *             the limited card and their own records.
+ *   none    — neither.
+ *
+ * Full always wins over linked, so an owner who also transacted is never downgraded.
+ *
+ * Pure: the caller's visibility sets (user ids incl. reportees, firm distributor ids, source
+ * distributor ids) are computed by the backend's existing visibility code and passed in.
+ */
+import { primaryMappingOf, sideKeyOf } from "./sides.js";
+
+export const ACCESS_LEVELS = Object.freeze({ FULL: "full", LINKED: "linked", NONE: "none" });
+
+export const CALLER_CLASSES = Object.freeze({
+  CLIENT: "client",
+  PARTNER: "partner",
+  OPS: "ops",
+  EMPLOYEE: "employee",
+});
+
+/** The reasons a caller can reach a client. Owner reasons give full access; link reasons linked. */
+export const MATCH_REASONS = Object.freeze({
+  OWNER_USER: "owner_user",
+  SOURCE_DISTRIBUTOR: "source_distributor",
+  PRIMARY_DISTRIBUTOR: "primary_distributor",
+  FULL_RECORD_ACCESS: "full_record_access",
+  SECONDARY_DISTRIBUTOR: "secondary_distributor",
+  LINKED_USER: "linked_user",
+});
+
+const OWNER_REASONS = new Set([
+  MATCH_REASONS.OWNER_USER,
+  MATCH_REASONS.SOURCE_DISTRIBUTOR,
+  MATCH_REASONS.PRIMARY_DISTRIBUTOR,
+  MATCH_REASONS.FULL_RECORD_ACCESS,
+]);
+
+/**
+ * Who is calling.
+ *
+ * @param {{ roles?: string[], distributorId?: *, isClientApp?: boolean }} session
+ * @param {object} settings  resolved client-profile settings (for `field_lock.ops_roles`)
+ */
+export function callerClassOf({ roles = [], distributorId = null, isClientApp = false } = {}, settings) {
+  if (isClientApp) return CALLER_CLASSES.CLIENT;
+  if (distributorId) return CALLER_CLASSES.PARTNER;
+  const opsRoles = settings?.field_lock?.ops_roles ?? [];
+  if (roles.some((r) => opsRoles.includes(r))) return CALLER_CLASSES.OPS;
+  return CALLER_CLASSES.EMPLOYEE;
+}
+
+/**
+ * Every reason the caller reaches this client.
+ *
+ * @param {object} client  a distributorclients document (needs the owner fields, distributor_id,
+ *                         distributor_mappings, linked_users)
+ * @param {{ userIds?: Iterable, firmDistributorIds?: Iterable, sourceDistributorIds?: Iterable,
+ *           fullRecordAccess?: boolean, houseDistributorIds?: Iterable }} caller
+ * @param {object} settings  resolved settings (`access.owner_user_fields`)
+ * @returns {string[]}  MATCH_REASONS values
+ */
+export function matchReasonsFor(client, caller = {}, settings) {
+  const reasons = [];
+  if (!client) return reasons;
+  const users = toKeySet(caller.userIds);
+  const firm = toKeySet(caller.firmDistributorIds);
+  const source = toKeySet(caller.sourceDistributorIds);
+  const ctx = { houseDistributorIds: caller.houseDistributorIds };
+
+  if (caller.fullRecordAccess) reasons.push(MATCH_REASONS.FULL_RECORD_ACCESS);
+  const ownerFields = settings?.access?.owner_user_fields ?? [];
+  if (ownerFields.some((f) => client[f] && users.has(String(client[f])))) reasons.push(MATCH_REASONS.OWNER_USER);
+
+  const primary = primaryMappingOf(client);
+  if (primary.distributor_id && source.has(String(primary.distributor_id))) reasons.push(MATCH_REASONS.SOURCE_DISTRIBUTOR);
+  if (primary.distributor_id && firm.has(String(primary.distributor_id))) reasons.push(MATCH_REASONS.PRIMARY_DISTRIBUTOR);
+
+  const primaryKey = sideKeyOf(primary.distributor_id, ctx);
+  for (const m of client.distributor_mappings ?? []) {
+    if (!m || m.is_primary || m.status === "inactive" || !m.distributor_id) continue;
+    if (sideKeyOf(m.distributor_id, ctx) === primaryKey) continue;
+    if (firm.has(String(m.distributor_id))) {
+      reasons.push(MATCH_REASONS.SECONDARY_DISTRIBUTOR);
+      break;
+    }
+  }
+  if ((client.linked_users ?? []).some((l) => l && users.has(String(l.user_id)))) reasons.push(MATCH_REASONS.LINKED_USER);
+  return [...new Set(reasons)];
+}
+
+/** Collapse match reasons to an access level. */
+export function accessLevelFor(reasons = []) {
+  if (reasons.some((r) => OWNER_REASONS.has(r))) return ACCESS_LEVELS.FULL;
+  if (reasons.length) return ACCESS_LEVELS.LINKED;
+  return ACCESS_LEVELS.NONE;
+}
+
+/** Convenience: reasons and level in one call. */
+export function clientAccessFor(client, caller, settings) {
+  const reasons = matchReasonsFor(client, caller, settings);
+  return { level: accessLevelFor(reasons), reasons };
+}
+
+/**
+ * Reduce a client document to what a linked caller may see, masking the configured fields.
+ * Arrays of contacts keep only a masked number per entry.
+ */
+export function linkedViewOf(client, settings) {
+  const fields = settings?.linked_view?.fields ?? [];
+  const masked = new Set(settings?.linked_view?.masked_fields ?? []);
+  const out = {};
+  for (const f of fields) {
+    if (!(f in (client ?? {}))) continue;
+    out[f] = masked.has(f) ? maskValue(client[f], settings?.linked_view?.masked_contact_keys) : client[f];
+  }
+  return out;
+}
+
+/** Keep the last 4 characters of a value, or of each listed key inside contact entries. */
+export function maskValue(value, contactKeys = []) {
+  if (value === null || value === undefined) return value;
+  if (Array.isArray(value)) {
+    return value.map((entry) => {
+      if (entry && typeof entry === "object") {
+        const copy = { ...entry };
+        for (const k of contactKeys) if (k in copy) copy[k] = maskValue(copy[k]);
+        return copy;
+      }
+      return maskValue(entry, contactKeys);
+    });
+  }
+  const s = String(value);
+  if (s.length <= 4) return "•".repeat(s.length);
+  return "•".repeat(s.length - 4) + s.slice(-4);
+}
+
+function toKeySet(values) {
+  return new Set([...(values ?? [])].filter((v) => v !== null && v !== undefined).map(String));
+}

package/src/client-profile/attach-plugin.js

@@ -0,0 +1,53 @@
+/**
+ * Mongoose plugin factory: record the person who created a document on the client it names.
+ *
+ * Both backends add it to the models whose documents are "business done on a client" (v1 orders,
+ * v2 goals, …). The backend injects its own `attach` (its profile service's `attachUser`), so the
+ * package still imports no driver and no models.
+ *
+ *   schema.plugin(createAttachPlugin({ attach }), { via: ATTACH_TRIGGERS.ORDER })
+ *
+ * After a NEW document is saved — or inserted in bulk — `attach` runs with the document's client
+ * and creator, in the save's session (a rolled-back transaction rolls the attach back too). It
+ * never throws: an attach failure must not fail the save that triggered it.
+ *
+ * @param {{ attach: (args: { clientId, userId, via, stamps, session, doc }) => Promise<unknown> }} deps
+ *   `doc` is the saved document, for backends that also act on it (v1 locks the primary on the
+ *   first order).
+ */
+export function createAttachPlugin({ attach }) {
+  if (typeof attach !== "function") throw new Error("createAttachPlugin: `attach` is required");
+
+  return function clientProfileAttachPlugin(schema, { via, clientField = "client_id", creatorField = "created_by" } = {}) {
+    if (!via) throw new Error("clientProfileAttachPlugin: `via` is required");
+
+    const run = async (doc, session) => {
+      const clientId = doc?.[clientField];
+      const userId = doc?.[creatorField];
+      if (!clientId || !userId) return;
+      try {
+        await attach({
+          clientId,
+          userId,
+          via,
+          stamps: { rmId: doc.rm_id ?? null, distEmpRmId: doc.dist_emp_rm_id ?? null, departmentId: doc.department_id ?? null },
+          session,
+          doc,
+        });
+      } catch {
+        // never fail the save
+      }
+    };
+
+    schema.pre("save", function markNew() {
+      this.$locals.clientProfileWasNew = this.isNew;
+    });
+    schema.post("save", async (doc) => {
+      if (!doc.$locals?.clientProfileWasNew) return;
+      await run(doc, doc.$session?.() ?? undefined);
+    });
+    schema.post("insertMany", async (docs) => {
+      for (const doc of docs ?? []) await run(doc, undefined); // eslint-disable-line no-await-in-loop
+    });
+  };
+}

package/src/client-profile/change-requests.js

@@ -0,0 +1,155 @@
+/**
+ * Corporate change requests (D5) — a partner's edit to a corporate client's personal details is
+ * HELD until the client confirms it with a one-time code sent to their stored mobile.
+ *
+ * Storage: `client_profile_change_requests`, one row per request:
+ *   { client_id, requested_by, distributor_id, source, payload, fields, status, otp_hash,
+ *     otp_salt, attempts, expires_at, created_at, decided_at, decided_by }
+ *   status: pending → applied | rejected | expired
+ *
+ * The request stores the ORIGINAL write (`source` names the backend endpoint, `payload` its
+ * body). On confirmation the backend replays that write through its own handler, so validation,
+ * FundCore sync and audit behave exactly as for a direct edit. This service never writes the
+ * client itself.
+ *
+ * Messages go out as events (`settings.events.*`) through the injected `emit` — the OTP is in the
+ * requested event's payload for the Events Framework to deliver; it is never logged or returned.
+ */
+import crypto from "crypto";
+import { CLIENT_PROFILE_COLLECTIONS, clientEventSubject } from "./settings.js";
+
+export const CHANGE_REQUEST_STATUS = Object.freeze({
+  PENDING: "pending",
+  APPLIED: "applied",
+  REJECTED: "rejected",
+  EXPIRED: "expired",
+});
+
+/** Why a confirmation did not go through. */
+export const CHANGE_REQUEST_FAILURES = Object.freeze({
+  NOT_FOUND: "not_found",
+  NOT_PENDING: "not_pending",
+  EXPIRED: "expired",
+  WRONG_CODE: "wrong_code",
+  TOO_MANY_ATTEMPTS: "too_many_attempts",
+});
+
+const hashOtp = (otp, salt) => crypto.createHash("sha256").update(`${salt}:${otp}`).digest("hex");
+const defaultOtp = () => String(crypto.randomInt(0, 1_000_000)).padStart(6, "0");
+
+/**
+ * @param {{ getDb: Function, getSettings: Function, emit?: Function, toId?: Function,
+ *           now?: () => Date, generateOtp?: () => string, maxAttempts?: number }} deps
+ */
+export function createChangeRequestService({ getDb, getSettings, emit = async () => ({}), toId = (v) => v, now = () => new Date(), generateOtp = defaultOtp, maxAttempts = 5 }) {
+  const coll = () => getDb().collection(CLIENT_PROFILE_COLLECTIONS.CHANGE_REQUESTS);
+
+  /** Who hears about an outcome: the partner (and firm) that asked. Ids only, as strings. */
+  const outcomeParties = (request) => ({
+    requested_by: request?.requested_by ? String(request.requested_by) : null,
+    distributor_id: request?.distributor_id ? String(request.distributor_id) : null,
+  });
+
+  /**
+   * Hold a write for the client's confirmation and send them the code.
+   * @returns {Promise<{ requestId: *, expiresAt: Date }>}
+   */
+  async function create({ clientId, requestedBy, distributorId = null, source, payload, fields = [], mobile = null }) {
+    const settings = getSettings();
+    const otp = generateOtp();
+    const salt = crypto.randomBytes(8).toString("hex");
+    const created = now();
+    const expiresAt = new Date(created.getTime() + settings.change_request.ttl_minutes * 60 * 1000);
+    const row = {
+      client_id: toId(clientId),
+      requested_by: toId(requestedBy),
+      distributor_id: distributorId ? toId(distributorId) : null,
+      source,
+      payload,
+      fields,
+      status: CHANGE_REQUEST_STATUS.PENDING,
+      otp_hash: hashOtp(otp, salt),
+      otp_salt: salt,
+      attempts: 0,
+      expires_at: expiresAt,
+      created_at: created,
+    };
+    const { insertedId } = await coll().insertOne(row);
+    await emit(settings.events.profile_change_requested, {
+      change_request_id: String(insertedId),
+      client_id: String(clientId),
+      fields,
+      otp,
+      expires_at: expiresAt.toISOString(),
+      valid_minutes: String(settings.change_request.ttl_minutes),
+    }, clientEventSubject(settings, clientId, { mobile }));
+    return { requestId: insertedId, expiresAt };
+  }
+
+  /**
+   * Check the code. On success the request is marked applied and returned so the backend can
+   * replay it; the backend reports a replay failure through `markFailed`.
+   * @returns {Promise<{ ok: true, request: object } | { ok: false, reason: string }>}
+   */
+  async function confirm({ requestId, otp, decidedBy = null }) {
+    const settings = getSettings();
+    const id = toId(requestId);
+    const request = await coll().findOne({ _id: id });
+    if (!request) return { ok: false, reason: CHANGE_REQUEST_FAILURES.NOT_FOUND };
+    if (request.status !== CHANGE_REQUEST_STATUS.PENDING) return { ok: false, reason: CHANGE_REQUEST_FAILURES.NOT_PENDING };
+    if (now() > new Date(request.expires_at)) {
+      await coll().updateOne({ _id: id, status: CHANGE_REQUEST_STATUS.PENDING }, { $set: { status: CHANGE_REQUEST_STATUS.EXPIRED, decided_at: now() } });
+      await emit(settings.events.profile_change_expired, { change_request_id: String(id), client_id: String(request.client_id), ...outcomeParties(request) }, clientEventSubject(settings, request.client_id));
+      return { ok: false, reason: CHANGE_REQUEST_FAILURES.EXPIRED };
+    }
+    if (request.attempts >= maxAttempts) return { ok: false, reason: CHANGE_REQUEST_FAILURES.TOO_MANY_ATTEMPTS };
+    if (hashOtp(String(otp ?? ""), request.otp_salt) !== request.otp_hash) {
+      await coll().updateOne({ _id: id }, { $inc: { attempts: 1 } });
+      return { ok: false, reason: CHANGE_REQUEST_FAILURES.WRONG_CODE };
+    }
+    // Atomic claim: two confirmations of one request cannot both apply it.
+    const claimed = await coll().updateOne(
+      { _id: id, status: CHANGE_REQUEST_STATUS.PENDING },
+      { $set: { status: CHANGE_REQUEST_STATUS.APPLIED, decided_at: now(), decided_by: toId(decidedBy) } },
+    );
+    if (claimed.modifiedCount !== 1) return { ok: false, reason: CHANGE_REQUEST_FAILURES.NOT_PENDING };
+    await emit(settings.events.profile_change_applied, { change_request_id: String(id), client_id: String(request.client_id), fields: request.fields, ...outcomeParties(request) }, clientEventSubject(settings, request.client_id));
+    return { ok: true, request };
+  }
+
+  /** The client (or ops) declines the change. */
+  async function reject({ requestId, decidedBy = null }) {
+    const settings = getSettings();
+    const id = toId(requestId);
+    const res = await coll().updateOne(
+      { _id: id, status: CHANGE_REQUEST_STATUS.PENDING },
+      { $set: { status: CHANGE_REQUEST_STATUS.REJECTED, decided_at: now(), decided_by: toId(decidedBy) } },
+    );
+    if (res.modifiedCount === 1) {
+      const request = await coll().findOne({ _id: id }, { projection: { client_id: 1, requested_by: 1, distributor_id: 1 } });
+      await emit(settings.events.profile_change_rejected, { change_request_id: String(id), client_id: String(request?.client_id), ...outcomeParties(request) }, clientEventSubject(settings, request?.client_id));
+      return { ok: true };
+    }
+    return { ok: false, reason: CHANGE_REQUEST_FAILURES.NOT_PENDING };
+  }
+
+  /** A confirmed request whose replay failed: recorded, never silently lost. */
+  async function markFailed({ requestId, error }) {
+    await coll().updateOne({ _id: toId(requestId) }, { $set: { apply_error: String(error).slice(0, 500) } });
+  }
+
+  /** Pending requests for a client (for the "change pending" badge). OTP fields are never returned. */
+  async function listPending(clientId) {
+    return coll().find(
+      { client_id: toId(clientId), status: CHANGE_REQUEST_STATUS.PENDING, expires_at: { $gt: now() } },
+      { projection: { otp_hash: 0, otp_salt: 0, payload: 0 } },
+    ).toArray();
+  }
+
+  /** One request without its code fields — e.g. to route confirmation to the backend that owns it. */
+  async function get(requestId) {
+    return coll().findOne({ _id: toId(requestId) }, { projection: { otp_hash: 0, otp_salt: 0 } });
+  }
+
+  return Object.freeze({ create, confirm, reject, markFailed, listPending, get });
+}

package/src/client-profile/config-store.js

@@ -0,0 +1,93 @@
+/**
+ * The configuration store both backends use — load, cache, kill switch.
+ *
+ * v1 and v2 read the same three things (the settings document, the field-policy rows, and the ids
+ * of the configured house distributors). Rather than two copies of that loader, each backend
+ * creates one store here and hands it its database handle, logger and environment. The store
+ * owns no connection and imports no driver: `getDb()` returns the backend's native `Db` (or
+ * undefined before it connects).
+ *
+ * Behaviour:
+ *   - before the first load, and on any failed load, the last good configuration is served; the
+ *     very first configuration is the package defaults, where every mode is `off`
+ *   - problems in the documents are logged once per distinct set, never thrown
+ *   - `env.CLIENT_PROFILE_MODE = "off"` forces every mode off whatever the document says
+ */
+import {
+  CLIENT_PROFILE_COLLECTIONS,
+  CLIENT_PROFILE_SETTINGS_DOC_ID,
+  MODES,
+  resolveClientProfileSettings,
+} from "./settings.js";
+import { buildFieldPolicyIndex } from "./field-policy.js";
+
+/** The environment variable that forces every mode off. */
+export const CLIENT_PROFILE_KILL_SWITCH_ENV = "CLIENT_PROFILE_MODE";
+
+/**
+ * @param {{ getDb: () => (object|undefined), logger?: { warn: Function }, env?: object }} deps
+ */
+export function createClientProfileConfigStore({ getDb, logger, env = {} } = {}) {
+  let settings = resolveClientProfileSettings(null).settings;
+  let fieldPolicyIndex = new Map();
+  let houseDistributorIds = [];
+  let lastProblemsKey = "";
+
+  const warn = (message) => {
+    try { logger?.warn?.(message); } catch { /* logging must never break a load */ }
+  };
+
+  const isKilled = () => {
+    const value = String(env[CLIENT_PROFILE_KILL_SWITCH_ENV] || "").toLowerCase();
+    return value === MODES.OFF || value === "false";
+  };
+
+  const reportProblems = (what, problems) => {
+    const key = `${what}:${problems.join("|")}`;
+    if (!problems.length || key === lastProblemsKey) return;
+    lastProblemsKey = key;
+    warn(`client-profile config: ${what} problems (defaults used for these): ${problems.join("; ")}`);
+  };
+
+  const getSettings = () => {
+    if (!isKilled()) return settings;
+    const modes = Object.fromEntries(Object.keys(settings.modes).map((m) => [m, MODES.OFF]));
+    return Object.freeze({ ...settings, modes: Object.freeze(modes) });
+  };
+
+  const load = async () => {
+    const db = getDb?.();
+    if (!db) return getSettings();
+    try {
+      const doc = await db.collection(CLIENT_PROFILE_COLLECTIONS.SETTINGS).findOne({ _id: CLIENT_PROFILE_SETTINGS_DOC_ID });
+      const { settings: resolved, problems } = resolveClientProfileSettings(doc);
+
+      const rows = await db.collection(CLIENT_PROFILE_COLLECTIONS.FIELD_POLICIES).find({ is_active: { $ne: false } }).toArray();
+      const { index, problems: policyProblems } = buildFieldPolicyIndex(rows);
+
+      const codes = resolved.house_distributor_codes;
+      const house = codes.length
+        ? (await db.collection("distributors").find({ distributor_code: { $in: codes } }, { projection: { _id: 1 } }).toArray())
+          .map(({ _id: id }) => String(id))
+        : [];
+
+      // Swap all three together so no reader ever sees settings from one load and policies from another.
+      settings = resolved;
+      fieldPolicyIndex = index;
+      houseDistributorIds = house;
+      reportProblems("settings", problems);
+      reportProblems("field policies", policyProblems);
+    } catch (err) {
+      warn(`client-profile config: load failed, keeping the last good configuration: ${err.message}`);
+    }
+    return getSettings();
+  };
+
+  return Object.freeze({
+    load,
+    getSettings,
+    getFieldPolicyIndex: () => fieldPolicyIndex,
+    getSideContext: () => ({ houseDistributorIds }),
+    isKilled,
+  });
+}

package/src/client-profile/errors.js

@@ -0,0 +1,25 @@
+/**
+ * Stable result and error codes for the client-profile rules.
+ *
+ * Callers branch on the CODE, never on text. The human text lives in settings (`messages`), so a
+ * wording change is a config edit and every backend says the same thing.
+ */
+export const CLIENT_PROFILE_ERRORS = Object.freeze({
+  /** A personal field was changed by a caller who may not change it. */
+  PERSONAL_FIELD_LOCKED: "CLIENT_PROFILE.PERSONAL_FIELD_LOCKED",
+  /** A personal field was changed and must be confirmed by the client before it applies. */
+  CONFIRMATION_REQUIRED: "CLIENT_PROFILE.CONFIRMATION_REQUIRED",
+  /** The person already has an MF investor; a second is never created. */
+  MF_INVESTOR_EXISTS: "CLIENT_PROFILE.MF_INVESTOR_EXISTS",
+  /** The caller has no way to act on this client. */
+  CLIENT_NOT_IN_SCOPE: "CLIENT_PROFILE.CLIENT_NOT_IN_SCOPE",
+  /** A second profile of a type the person already holds was attempted. */
+  PROFILE_TYPE_EXISTS: "CLIENT_PROFILE.PROFILE_TYPE_EXISTS",
+  /** Not an error: a client with this PAN already exists; the caller may act on it (D4). */
+  EXISTING_CLIENT_FOUND: "CLIENT_PROFILE.EXISTING_CLIENT_FOUND",
+  /** The settings document failed validation; defaults were used for the listed keys. */
+  SETTINGS_INVALID: "CLIENT_PROFILE.SETTINGS_INVALID",
+});
+
+/** Every code, for exhaustiveness checks (the messages table must cover each one). */
+export const CLIENT_PROFILE_ERROR_CODES = Object.freeze(Object.values(CLIENT_PROFILE_ERRORS));