b2b-platform-utils 1.1.97 → 1.1.99

package/README.md

@@ -36,3 +36,15 @@ process instance identity, deployment version, phase, and timing fields.
 ```bash
 # make sure your .npmrc has a valid auth token for npmjs.org
 npm i platform-utils
+# Exact financial admission helpers
+
+`financialAdmissionMath` is the existing Payment precision arithmetic, shared
+without changing its decimal, rational, posting or wire-format rules.
+`financialAdmissionPlan` provides versioned canonical encoding, deterministic plan
+fingerprints and exact before/after arithmetic for normalized accounting legs.
+RG debit measures actual real-wallet BET debit; bonus balances remain separate.
+
+These helpers do not grant wallet ownership or authorize session identity, funding
+allocation, bonus attribution, reversal eligibility or RG. Payment retains those
+decisions and must verify the plan against its issued context and settlement facts.
+No provider is enrolled or activated by importing either helper.

package/errorsMap.js

@@ -1830,6 +1830,18 @@ const STATIC_ERRORS = [
     httpCode: 422,
     description: "New password must differ from the current password.",
   },
+  {
+    errorCode: 1298,
+    errorKey: "withdrawalKycRequired",
+    httpCode: 409,
+    description: "Verified KYC is required before withdrawal.",
+  },
+  {
+    errorCode: 1299,
+    errorKey: "invalidRiskPermissionConditions",
+    httpCode: 422,
+    description: "Risk permission conditions contain an unsupported permission or condition.",
+  },
 ];
 
 const STATIC_BY_KEY = Object.fromEntries(

package/financialAdmissionMath.js

@@ -0,0 +1,123 @@
+'use strict';
+
+// Fractions are accounting minor units unless explicitly projected to wire major units.
+const LIMIT = 4096;
+function integer(value) {
+  const s = String(value);
+  if (!/^-?(0|[1-9]\d*)$/.test(s) || s.replace('-', '').length > LIMIT)
+    throw new TypeError('precision_integer_invalid');
+  return BigInt(s);
+}
+function rational(n, d = 1n) {
+  n = integer(n);
+  d = integer(d);
+  if (d <= 0n) throw new TypeError('precision_denominator_invalid');
+  let a = n < 0n ? -n : n;
+  let b = d;
+  while (b) [a, b] = [b, a % b];
+  return { n: n / a, d: d / a };
+}
+function decimal(value) {
+  if (typeof value !== 'string' || value.length > LIMIT || !/^-?(0|[1-9]\d*)(\.\d+)?$/.test(value))
+    throw new TypeError('precision_decimal_invalid');
+  const [whole, frac = ''] = value.split('.');
+  return rational(BigInt(whole + frac), 10n ** BigInt(frac.length));
+}
+const add = (a, b) => rational(a.n * b.d + b.n * a.d, a.d * b.d);
+const neg = (a) => rational(-a.n, a.d);
+const mul = (a, b) => rational(a.n * b.n, a.d * b.d);
+function div(a, b) {
+  if (b.n <= 0n) throw new TypeError('precision_divisor_invalid');
+  return rational(a.n * b.d, a.d * b.n);
+}
+const floor = (a) => (a.n >= 0n ? a.n / a.d : -((-a.n + a.d - 1n) / a.d));
+function scaleFactor(scale) {
+  if (!Number.isInteger(scale) || scale < 0 || scale > 255)
+    throw new TypeError('precision_scale_invalid');
+  return rational(10n ** BigInt(scale));
+}
+function minor(value) {
+  const n = integer(value);
+  if ((n < 0n ? -n : n).toString().length > 36) throw new TypeError('precision_ledger_overflow');
+  return n;
+}
+function post(c, r, delta) {
+  const x = add(r, delta);
+  const m = floor(x);
+  return { integerDelta: minor(m), balance: minor(c + m), remainder: add(x, rational(-m)) };
+}
+function convert(wire, session) {
+  return div(
+    mul(
+      mul(decimal(wire), rational(session.wire_multiplier)),
+      scaleFactor(Number(session.accounting_scale)),
+    ),
+    rational(session.fx_numerator, session.fx_denominator),
+  );
+}
+function project(c, r, session) {
+  return div(
+    mul(
+      div(add(rational(c), r), scaleFactor(Number(session.accounting_scale))),
+      rational(session.fx_numerator, session.fx_denominator),
+    ),
+    rational(session.wire_multiplier),
+  );
+}
+function roundHalfUp(a, scale) {
+  const scaled = mul(a, scaleFactor(scale));
+  const sign = scaled.n < 0n ? -1n : 1n;
+  const magnitude = scaled.n * sign;
+  return rational(sign * ((2n * magnitude + scaled.d) / (2n * scaled.d)), 10n ** BigInt(scale));
+}
+function exactDecimal(a, allowRationalOnly = false) {
+  let d = a.d;
+  let twos = 0;
+  let fives = 0;
+  while (d % 2n === 0n) {
+    d /= 2n;
+    twos++;
+  }
+  while (d % 5n === 0n) {
+    d /= 5n;
+    fives++;
+  }
+  if (d !== 1n) {
+    if (allowRationalOnly) return '';
+    throw new TypeError('precision_wire_policy_required');
+  }
+  const places = Math.max(twos, fives);
+  if (places > LIMIT) {
+    if (allowRationalOnly) return '';
+    throw new TypeError('precision_wire_policy_required');
+  }
+  const n = a.n * (10n ** BigInt(places) / a.d);
+  const digits = (n < 0n ? -n : n).toString().padStart(places + 1, '0');
+  const text = places
+    ? `${digits.slice(0, -places)}.${digits.slice(-places)}`.replace(/0+$/, '').replace(/\.$/, '')
+    : digits;
+  return (n < 0n ? '-' : '') + text;
+}
+// Protobuf transports decimal strings, not JavaScript numbers. Repeating values
+// use the existing exact numerator/denominator; only game formats the wire response.
+function serializeWire(a, policy) {
+  if (policy !== 'exact_json_v1') throw new TypeError('precision_wire_policy_required');
+  return exactDecimal(a, true);
+}
+
+module.exports = {
+  rational,
+  decimal,
+  add,
+  neg,
+  mul,
+  div,
+  floor,
+  minor,
+  post,
+  convert,
+  project,
+  exactDecimal,
+  serializeWire,
+  roundHalfUp,
+};

package/financialAdmissionPlan.js

@@ -0,0 +1,150 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+const A = require('./financialAdmissionMath');
+const failure = (code) => Object.assign(new TypeError(code), { code });
+const sequence = (v) => typeof v === 'string' && /^(0|[1-9]\d{0,35})$/.test(v);
+const minor = (v) => typeof v === 'string' && v !== '-0' && /^-?(0|[1-9]\d{0,35})$/.test(v);
+const id = (v) => typeof v === 'string' && v.length > 0 && v.length <= 200 && !/[\x00-\x1f\x7f]/.test(v);
+const fingerprint = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+
+function encode(value, depth = 0) {
+  if (depth > 32) throw failure('financial_admission_canonical_invalid');
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isSafeInteger(value)) return JSON.stringify(value);
+  if (!value || typeof value !== 'object') throw failure('financial_admission_canonical_invalid');
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) if (!Object.hasOwn(value, i)) throw failure('financial_admission_canonical_invalid');
+    return `[${value.map((item) => encode(item, depth + 1)).join(',')}]`;
+  }
+  if (Object.getPrototypeOf(value) !== Object.prototype) throw failure('financial_admission_canonical_invalid');
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (Object.values(descriptors).some((d) => !Object.hasOwn(d, 'value')) || Object.getOwnPropertySymbols(value).length)
+    throw failure('financial_admission_canonical_invalid');
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${encode(value[key], depth + 1)}`).join(',')}}`;
+}
+
+function canonical(value) {
+  const text = encode(value);
+  if (Buffer.byteLength(text) > 262144) throw failure('financial_admission_canonical_too_large');
+  return text;
+}
+
+function digest(value) {
+  return createHash('sha256').update(canonical(value)).digest('hex');
+}
+
+function fraction(n, d) {
+  if (typeof n !== 'string' || typeof d !== 'string') throw failure('financial_admission_fraction_invalid');
+  const r = A.rational(n, d);
+  if (String(r.n) !== n || String(r.d) !== d) throw failure('financial_admission_fraction_invalid');
+  return r;
+}
+
+const STATE_FIELDS = ['balanceRealMinor', 'balanceBonusMinor', 'cashRemainderNumerator',
+  'cashRemainderDenominator', 'cashPrecisionVersion', 'bonusRemainderNumerator',
+  'bonusRemainderDenominator', 'bonusPrecisionVersion'];
+
+function state(value) {
+  if (!value || !minor(value.balanceRealMinor) || !minor(value.balanceBonusMinor))
+    throw failure('financial_admission_state_invalid');
+  for (const prefix of ['cash', 'bonus']) {
+    const r = fraction(value[`${prefix}RemainderNumerator`], value[`${prefix}RemainderDenominator`]);
+    if (!sequence(value[`${prefix}PrecisionVersion`]) || (prefix === 'cash' && (r.n < 0n || r.n >= r.d)))
+      throw failure('financial_admission_state_invalid');
+  }
+  return Object.fromEntries(STATE_FIELDS.map((field) => [field, value[field]]));
+}
+
+/**
+ * Shared exact arithmetic for normalized, already-authorized accounting legs.
+ * This does not authorize allocations, sessions, reversals, bonus attribution or
+ * RG. Payment must independently validate those facts before settlement. No
+ * caller should treat a matching SHA-256 fingerprint as an authorization token.
+ */
+function preparePlan(input) {
+  if (!input || input.protocolVersion !== 1 || !id(input.scope) ||
+      typeof input.walletReference !== 'string' || typeof input.ownershipEpoch !== 'string' ||
+      !/^[a-zA-Z0-9_-]{1,128}$/.test(input.walletReference || '') ||
+      !/^[a-zA-Z0-9_-]{1,128}$/.test(input.ownershipEpoch || '') ||
+      !sequence(input.previousWalletSequence) || !id(input.sessionId) ||
+      !id(input.commandId) || !fingerprint(input.requestFingerprint) ||
+      !fingerprint(input.contextFingerprint) || !id(input.currency) ||
+      !Number.isInteger(input.currencyScale) || input.currencyScale < 0 || input.currencyScale > 255 ||
+      !Array.isArray(input.legs) || !input.legs.length || input.legs.length > 32)
+    throw failure('financial_admission_plan_invalid');
+  const before = state(input.before);
+  const after = { ...before };
+  const legs = [];
+  const seen = new Set();
+  const originals = new Set();
+  let requestedDebit = 0n;
+  let creditSeen = false;
+  for (const leg of input.legs) {
+    if (!leg || !['bet', 'win', 'refund', 'reversal', 'adjustment', 'end_round'].includes(leg.action) ||
+        !id(leg.transactionId)) throw failure('financial_admission_leg_invalid');
+    const key = canonical([leg.action, leg.transactionId]);
+    if (seen.has(key)) throw failure('financial_admission_duplicate_leg');
+    seen.add(key);
+    if (leg.action === 'bet' && creditSeen) throw failure('financial_admission_bet_after_credit');
+    if (['win', 'refund'].includes(leg.action)) creditSeen = true;
+    if (leg.action === 'reversal' && (!id(leg.originalTransactionId) ||
+        !['bet', 'win', 'refund', 'adjustment'].includes(leg.originalAction)))
+      throw failure('financial_admission_original_required');
+    if (leg.action === 'reversal') {
+      const original = canonical([leg.originalAction, leg.originalTransactionId]);
+      if (originals.has(original)) throw failure('financial_admission_duplicate_original');
+      originals.add(original);
+    }
+    const planned = { action: leg.action, transactionId: leg.transactionId,
+      originalTransactionId: leg.action === 'reversal' ? leg.originalTransactionId : '',
+      originalAction: leg.action === 'reversal' ? leg.originalAction : '' };
+    for (const [bucket, balanceField] of [['cash', 'balanceRealMinor'], ['bonus', 'balanceBonusMinor']]) {
+      const delta = fraction(leg[`${bucket}DeltaNumerator`], leg[`${bucket}DeltaDenominator`]);
+      if ((leg.action === 'bet' && delta.n > 0n) ||
+          (['win', 'refund'].includes(leg.action) && delta.n < 0n) ||
+          (leg.action === 'end_round' && delta.n !== 0n))
+        throw failure('financial_admission_leg_sign_invalid');
+      const c = A.minor(after[balanceField]);
+      const r = fraction(after[`${bucket}RemainderNumerator`], after[`${bucket}RemainderDenominator`]);
+      // Preserve existing precision accounting: debit reversals/adjustments need
+      // funds too; a compound credit cannot fund an earlier full BET.
+      if (delta.n < 0n && A.add(A.add(A.rational(c), r), delta).n < 0n)
+        throw failure('financial_admission_insufficient_funds');
+      const next = delta.n === 0n ? { integerDelta: 0n, balance: c, remainder: r } : A.post(c, r, delta);
+      const dr = A.add(next.remainder, A.neg(r));
+      after[balanceField] = String(next.balance);
+      after[`${bucket}RemainderNumerator`] = String(next.remainder.n);
+      after[`${bucket}RemainderDenominator`] = String(next.remainder.d);
+      after[`${bucket}PrecisionVersion`] = String(BigInt(after[`${bucket}PrecisionVersion`]) + (dr.n === 0n ? 0n : 1n));
+      if (!sequence(after[`${bucket}PrecisionVersion`])) throw failure('financial_admission_version_exhausted');
+      // Existing RG eligibility is based on actual real-wallet debit, not bonus.
+      // Freespin/free-bet/session eligibility still belongs to the caller's
+      // established policy checks, independently verified by Payment.
+      if (leg.action === 'bet' && bucket === 'cash') requestedDebit -= next.integerDelta;
+      Object.assign(planned, { [`${bucket}DeltaNumerator`]: String(delta.n), [`${bucket}DeltaDenominator`]: String(delta.d),
+        [`${bucket}IntegerDeltaMinor`]: String(next.integerDelta),
+        [`${bucket}RemainderDeltaNumerator`]: String(dr.n), [`${bucket}RemainderDeltaDenominator`]: String(dr.d) });
+    }
+    legs.push(planned);
+  }
+  const walletSequence = String(BigInt(input.previousWalletSequence) + 1n);
+  if (!sequence(walletSequence) || !sequence(String(requestedDebit))) throw failure('financial_admission_version_exhausted');
+  const plan = { protocolVersion: 1, scope: input.scope, walletReference: input.walletReference,
+    ownershipEpoch: input.ownershipEpoch, previousWalletSequence: input.previousWalletSequence,
+    walletSequence, sessionId: input.sessionId, commandId: input.commandId,
+    requestFingerprint: input.requestFingerprint, contextFingerprint: input.contextFingerprint,
+    currency: input.currency, currencyScale: input.currencyScale, before, after, legs,
+    requestedDebitMinor: String(requestedDebit) };
+  return { plan, fingerprint: digest(['financial-admission-plan-v1', plan]) };
+}
+
+function verifyPlan(plan, expectedFingerprint) {
+  if (!fingerprint(expectedFingerprint)) throw failure('financial_admission_plan_fingerprint_invalid');
+  const computed = preparePlan(plan);
+  if (canonical(computed.plan) !== canonical(plan) || computed.fingerprint !== expectedFingerprint)
+    throw failure('financial_admission_plan_conflict');
+  return computed.plan;
+}
+
+module.exports = { canonical, digest, preparePlan, verifyPlan, state, STATE_FIELDS };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "b2b-platform-utils",
-  "version": "1.1.97",
+  "version": "1.1.99",
   "description": "Shared utilities for Node.js microservices: errors map, local cache, logger, numbers, dates, filesystem, media optimization, paginator, slugger, crypto wrapper, sanitize HTML, sorting.",
   "type": "commonjs",
   "license": "KingSizer",
   "private": false,
   "scripts": {
     "publish-update": "npm version patch --no-git-tag-version && npm publish",
-    "test": "node test/slugger.test.js && node test/lifecycle.test.js"
+    "test": "node test/slugger.test.js && node test/lifecycle.test.js && node test/financialAdmissionPlan.test.js"
   },
   "files": [
     "*.js",