@openora/core 0.4.0 → 0.4.1-canary.100

package/dist/pam/tag/service/tag-evaluation.service.d.ts

@@ -1,13 +1,20 @@
-import { type WalletReader, type IdentityReader } from '@openora/core/contracts';
+import { type WalletReader, type IdentityReader, type AdminUserDirectory, type User } from '@openora/core/contracts';
 import { TagService } from './tag.service.js';
 import { TagRuleService } from './tag-rule.service.js';
-export declare const SYSTEM_ACTOR_ID = "00000000-0000-0000-0000-000000000000";
+export type TagEvaluationServiceDeps = {
+    tag: TagService;
+    rule: TagRuleService;
+    walletReader: WalletReader;
+    identityReader: IdentityReader;
+    adminUserDirectory: AdminUserDirectory;
+};
 export declare class TagEvaluationService {
     private readonly tag;
     private readonly rule;
     private readonly walletReader;
     private readonly identityReader;
-    constructor(tag: TagService, rule: TagRuleService, walletReader: WalletReader, identityReader: IdentityReader);
+    private readonly adminUserDirectory;
+    constructor(deps: TagEvaluationServiceDeps);
     /** Loads a rule; returns null when it does not exist or is disabled. Never throws for a missing row. */
     private getEnabledRule;
     /** Idempotently assigns a tag; swallows TagAlreadyInUseError. */
@@ -19,37 +26,154 @@ export declare class TagEvaluationService {
      * Called on wallet.deposit.completed.
      */
     onDepositCompleted(payload: unknown): Promise<void>;
+    /** True when the withdrawal_review rule is enabled and amount crosses its threshold. Shared by the event path and the synchronous command-port path below so both stay in lockstep. */
+    private _withdrawalReviewThresholdCrossed;
+    /**
+     * Assigns withdrawal_review when a single withdrawal attempt exceeds its threshold.
+     * Called on wallet.withdrawal.requested (the attempt, before funds move) so the
+     * review tag lands before payout. Sticky - never auto-removed here or anywhere else.
+     * This is the async, best-effort fan-out path (other consumers may want the event) -
+     * wallet's own auto-approval decision does NOT wait on this; it calls
+     * evaluateWithdrawalRequested below instead. Idempotent with that path via
+     * TagAlreadyInUseError (see tryAssignTag).
+     */
+    onWithdrawalRequested(payload: unknown): Promise<void>;
+    /**
+     * Synchronous, transactional counterpart to onWithdrawalRequested, bound behind
+     * TAG_EVALUATION_COMMANDS. wallet.withdraw() awaits this on its own transaction handle
+     * BEFORE its maybeAutoApprove reads risk tags, so a withdrawal_review assignment is
+     * guaranteed committed before the auto-approval decision runs - closing the race the
+     * fire-and-forget EventBus emit above cannot (an EventBus emit is never awaited by the
+     * emitter). Money-adjacent: never events-only for this decision (see
+     * messaging-and-microservices "money never flows over events"). Any error here
+     * propagates and aborts the caller's withdrawal transaction - a review-gate evaluation
+     * failure must block the withdrawal rather than silently skip review.
+     */
+    evaluateWithdrawalRequested(tx: unknown, args: {
+        userId: User['id'];
+        amount: string;
+    }): Promise<void>;
+    private evaluateBasicKycNeededOnDeposit;
     /**
      * Evaluates the high_risk rule based on withdrawal amount and frequency.
-     * Called on wallet.withdrawal.completed.
-     * Only assigns the tag when a threshold is crossed; never auto-removes
-     * (risk designation requires an explicit admin clear).
+     * Called on wallet.withdrawal.completed. Only assigns the tag when a threshold is
+     * crossed; removal is handled separately by the daily resweep in runDailyEvaluation
+     * (a rolling-window count/amount can drop back under threshold with no new
+     * withdrawal, so it can't be detected event-driven-only). Records which breach
+     * condition(s) fired in assignMetadata - the resweep uses this to know whether the
+     * amount dimension (never resweepable, see _runHighRiskResweep) was involved.
      */
     onWithdrawalCompleted(payload: unknown): Promise<void>;
     /**
-     * Removes the inactive tag when a player logs in.
-     * Called on identity.user.login.
+     * Handles password login side effects:
+     *  - removes inactive/dormant_high_roller on activity
+     *  - assigns multi_account + bonus_abuser when another player has used this login IP
      */
     onUserLogin(payload: unknown): Promise<void>;
     /**
-     * Applies the kyc_pending tag on KYC submission and clears any prior kyc_rejected.
-     * Called on compliance.kyc.submitted. Respects the kyc_pending rule's isEnabled flag.
+     * Phone-login path mirrors password-login risk evaluation. The signal is the same
+     * authenticated session IP; the login method is intentionally not encoded in the tag.
+     */
+    onUserPhoneLogin(payload: unknown): Promise<void>;
+    private onAuthenticatedLogin;
+    private evaluateSharedLoginIp;
+    /**
+     * Applies kyc_pending on KYC submission only while the profile still has a pending-like
+     * status, and clears basic_kyc_needed / advanced_kyc_needed. Does not clear kyc_rejected:
+     * that sticky tag remains until a later approved state explicitly clears it.
      */
     onKycSubmitted(payload: unknown): Promise<void>;
+    private removeKycNeededTags;
+    private evaluateBasicKycNeededOnRejection;
     /**
-     * Manages kyc_pending / kyc_rejected lifecycle on KYC status changes.
-     * Called on compliance.kyc.updated. Respects the kyc_pending rule's isEnabled flag.
+     * Manages kyc_pending / kyc_rejected / basic_kyc_needed / advanced_kyc_needed lifecycle
+     * on KYC status changes. Called on compliance.kyc.updated. Assignment respects each tag
+     * rule's isEnabled flag; terminal cleanup still runs so disabled rules cannot strand old
+     * active rows.
      *
      * Transitions:
-     *   verified / manually_overridden -> remove kyc_pending + kyc_rejected
-     *   rejected                       -> remove kyc_pending, assign kyc_rejected
-     *   resubmission_requested         -> assign kyc_pending
+     *   approved / manually_overridden -> remove kyc_pending + kyc_rejected + basic_kyc_needed + advanced_kyc_needed
+     *   rejected                       -> remove kyc_pending, assign kyc_rejected, evaluate basic_kyc_needed
+     *   resubmission_requested         -> assign kyc_pending, keep kyc_rejected sticky
      */
     onKycStatusUpdated(payload: unknown): Promise<void>;
     /**
-     * Daily scheduled evaluation: assigns inactive to players who have not logged in
-     * for rule.thresholdDays days. Removal is handled by onUserLogin on next login.
+     * Assigns advanced_kyc_needed as a pure label over compliance's own re-KYC decision.
+     * Called on compliance.kyc.reverify_required. Respects the advanced_kyc_needed rule's
+     * isEnabled flag.
+     */
+    onKycReverifyRequired(payload: unknown): Promise<void>;
+    /**
+     * Assigns high_risk as a pure label over compliance's own device/IP screening decision.
+     * Called on compliance.kyc.high_risk_signal_detected. Respects the high_risk rule's
+     * isEnabled flag; never auto-removes (risk designation requires an explicit admin clear).
+     */
+    onKycHighRiskSignalDetected(payload: unknown): Promise<void>;
+    /**
+     * Assigns self_excluded when a player activates self-exclusion.
+     * Called on rg.self_exclusion.activated.
+     */
+    onSelfExclusionActivated(payload: unknown): Promise<void>;
+    /**
+     * Removes self_excluded when a player's self-exclusion is lifted.
+     * Called on rg.self_exclusion.lifted.
+     */
+    onSelfExclusionLifted(payload: unknown): Promise<void>;
+    /**
+     * Replaces the single mutable `level` tag with the player's new level.
+     * Called on player.level.changed (emitted by PlayerService.update() after commit).
+     * Not sticky - the level value lives only in assignReason text, never as a separate
+     * tag key per level. The swap goes through TagService.replacePlayerTag: removal of
+     * the prior active row (silent no-op when absent) + insert of the new one on ONE
+     * transaction, so a mid-swap failure can never strand the player with the old row
+     * removed and no new one committed. The loser of a concurrent replace throws
+     * TagAlreadyInUseError with nothing committed - swallowed here as the usual
+     * idempotent no-op (player.level itself stays the source of truth).
+     */
+    onPlayerLevelChanged(payload: unknown): Promise<void>;
+    /**
+     * Daily scheduled evaluation, three independent sweeps:
+     *  - inactive: assigns to players who have not logged in for rule.thresholdDays
+     *    days. Removal is handled by onUserLogin on next login.
+     *  - dormant_high_roller: a co-occurrence check, not a history lookup - high_roller
+     *    is only re-evaluated on deposit, so a player who goes quiet never loses it via
+     *    that path. Assigns to players who are both currently inactive (per this tag's
+     *    OWN thresholdDays, decoupled from the inactive rule's) and currently hold an
+     *    active high_roller tag. Removal is handled by onUserLogin on next login.
+     *  - high_risk resweep: removal-only, frequency dimension only. A rolling
+     *    withdrawal-count window can drop back under threshold with no new withdrawal
+     *    to trigger onWithdrawalCompleted, so current holders are rechecked here and
+     *    removed once the count falls below threshold. Deliberately does NOT recheck
+     *    the amount dimension - assignment's amount check has no time bound, so a
+     *    windowed recheck would silently de-designate a still-risky player once their
+     *    triggering withdrawal ages out of the window (an AML false negative). Now gated
+     *    on each holder's assignMetadata (recorded at assignment): a holder whose
+     *    metadata shows an amount breach is skipped regardless of their current count,
+     *    and a holder with null metadata (pre-migration/legacy row, or manually
+     *    assigned) is also skipped - "unknown why this was assigned" is treated as
+     *    "do not auto-remove". Skipped entirely when thresholdDays or thresholdCount is
+     *    null - an amount-only high_risk rule isn't resweepable by the cron; it stays
+     *    until an admin clears it or a future withdrawal re-triggers assignment.
      */
     runDailyEvaluation(): Promise<void>;
+    private _runInactiveSweep;
+    private _runDormantHighRollerSweep;
+    /**
+     * Frequency-only removal. Assignment (onWithdrawalCompleted) checks a single
+     * withdrawal's amount with no time bound, so an amount-only breach from outside
+     * this rolling window is invisible to a windowed recheck - resweeping it would
+     * silently de-designate a still-risky player (an AML false negative). Only the
+     * count dimension, which IS windowed at assignment time, is safe to resweep. Each
+     * holder's assignMetadata (recorded at assignment) records which breach dimension(s)
+     * fired; a holder whose metadata shows an amount breach, or whose metadata is null
+     * (pre-migration/legacy row or manual assignment - unknown why it was assigned), is
+     * skipped regardless of their current windowed count - pinned until an admin
+     * manually clears the tag or a future onWithdrawalCompleted re-evaluation populates
+     * metadata. Skipped entirely when thresholdDays or thresholdCount is null - an
+     * amount-only rule has no frequency dimension to resweep against and is never
+     * auto-cleared by the cron, only by an admin or a future onWithdrawalCompleted
+     * re-evaluation.
+     */
+    private _runHighRiskResweep;
 }
 //# sourceMappingURL=tag-evaluation.service.d.ts.map

package/dist/pam/tag/service/tag-evaluation.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tag-evaluation.service.d.ts","sourceRoot":"","sources":["../../../../src/pam/tag/service/tag-evaluation.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,cAAc,EAGpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,UAAU,EAAoD,MAAM,kBAAkB,CAAC;AAChG,OAAO,EAAE,cAAc,EAAwB,MAAM,uBAAuB,CAAC;AAE7E,eAAO,MAAM,eAAe,yCAAyC,CAAC;AAEtE,qBAAa,oBAAoB;IAE7B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,cAAc;gBAHd,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,cAAc,EACpB,YAAY,EAAE,YAAY,EAC1B,cAAc,EAAE,cAAc;IAGjD,wGAAwG;YAC1F,cAAc;IAW5B,iEAAiE;YACnD,YAAY;IAiB1B,uEAAuE;YACzD,YAAY;IAiB1B;;;OAGG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BzD;;;;;OAKG;IACG,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB5D;;;OAGG;IACG,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlD;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrD;;;;;;;;OAQG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBzD;;;OAGG;IACG,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;CAW1C"}
+{"version":3,"file":"tag-evaluation.service.d.ts","sourceRoot":"","sources":["../../../../src/pam/tag/service/tag-evaluation.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,cAAc,EAEnB,KAAK,kBAAkB,EAGvB,KAAK,IAAI,EACV,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,UAAU,EAAoD,MAAM,kBAAkB,CAAC;AAChG,OAAO,EAAE,cAAc,EAAwB,MAAM,uBAAuB,CAAC;AAgB7E,MAAM,MAAM,wBAAwB,GAAG;IACrC,GAAG,EAAE,UAAU,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC;IACrB,YAAY,EAAE,YAAY,CAAC;IAC3B,cAAc,EAAE,cAAc,CAAC;IAC/B,kBAAkB,EAAE,kBAAkB,CAAC;CACxC,CAAC;AAEF,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;gBAE5C,IAAI,EAAE,wBAAwB;IAQ1C,wGAAwG;YAC1F,cAAc;IAe5B,iEAAiE;YACnD,YAAY;IA4B1B,uEAAuE;YACzD,YAAY;IAsB1B;;;OAGG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO;IA4CzC,uLAAuL;YACzK,iCAAiC;IAQ/C;;;;;;;;OAQG;IACG,qBAAqB,CAAC,OAAO,EAAE,OAAO;IAW5C;;;;;;;;;;OAUG;IACG,2BAA2B,CAC/B,EAAE,EAAE,OAAO,EACX,IAAI,EAAE;QAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAC3C,OAAO,CAAC,IAAI,CAAC;YA4BF,+BAA+B;IAgB7C;;;;;;;;OAQG;IACG,qBAAqB,CAAC,OAAO,EAAE,OAAO;IAuC5C;;;;OAIG;IACG,WAAW,CAAC,OAAO,EAAE,OAAO;IASlC;;;OAGG;IACG,gBAAgB,CAAC,OAAO,EAAE,OAAO;YAKzB,oBAAoB;YAOpB,qBAAqB;IAyCnC;;;;OAIG;IACG,cAAc,CAAC,OAAO,EAAE,OAAO;YAsBvB,mBAAmB;YASnB,iCAAiC;IAe/C;;;;;;;;;;OAUG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO;IAwCzC;;;;OAIG;IACG,qBAAqB,CAAC,OAAO,EAAE,OAAO;IAiB5C;;;;OAIG;IACG,2BAA2B,CAAC,OAAO,EAAE,OAAO;IAkBlD;;;OAGG;IACG,wBAAwB,CAAC,OAAO,EAAE,OAAO;IAS/C;;;OAGG;IACG,qBAAqB,CAAC,OAAO,EAAE,OAAO;IAK5C;;;;;;;;;;OAUG;IACG,oBAAoB,CAAC,OAAO,EAAE,OAAO;IAuB3C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,kBAAkB;YAMV,iBAAiB;YAoBjB,0BAA0B;IAuBxC;;;;;;;;;;;;;;;OAeG;YACW,mBAAmB;CA0ClC"}