games_app/backend/src/services/fundApprovalService.ts

385 lines
13 KiB
TypeScript

/**
* Super-admin approval workflow for sensitive platform fund operations.
*/
import * as fundOperationRequestRepository from '../repositories/fundOperationRequestRepository';
import type {
FundOperationRequestRow,
FundOperationStatus,
FundOperationType,
} from '../repositories/fundOperationRequestRepository';
import * as roleRepository from '../repositories/roleRepository';
import * as userRepository from '../repositories/userRepository';
import { bumpUserTokenOnRoleChange } from './rbacService';
import * as auditLogRepository from '../repositories/auditLogRepository';
import * as securityNotificationService from './securityNotificationService';
import * as adminCreditService from './adminCreditService';
import * as treasuryService from './treasuryService';
import * as bonusPoolRepository from '../repositories/bonusPoolRepository';
import * as sweepService from './sweepService';
import * as depositSweepBatchRepository from '../repositories/depositSweepBatchRepository';
import type { RoleName } from '../models';
export class FundApprovalError extends Error {
constructor(message: string) {
super(message);
this.name = 'FundApprovalError';
}
}
export type FundRequestDto = {
id: string;
operationType: FundOperationType;
status: FundOperationStatus;
payload: Record<string, unknown>;
requestedBy: string;
approvedBy: string | null;
rejectionReason: string | null;
executionResult: Record<string, unknown> | null;
createdAt: string;
approvedAt: string | null;
executedAt: string | null;
};
function toDto(row: FundOperationRequestRow): FundRequestDto {
return {
id: row.id,
operationType: row.operation_type,
status: row.status,
payload: row.payload,
requestedBy: row.requested_by,
approvedBy: row.approved_by,
rejectionReason: row.rejection_reason,
executionResult: row.execution_result,
createdAt: row.created_at.toISOString(),
approvedAt: row.approved_at?.toISOString() ?? null,
executedAt: row.executed_at?.toISOString() ?? null,
};
}
export async function createFundRequest(input: {
operationType: FundOperationType;
payload: Record<string, unknown>;
requestedBy: string;
}): Promise<FundRequestDto> {
const canRequest = await roleRepository.userHasPermission(
input.requestedBy,
'fund_operation.request'
);
if (!canRequest) throw new FundApprovalError('Permission denied: fund_operation.request');
let row;
try {
row = await fundOperationRequestRepository.createRequest({
operationType: input.operationType,
payload: input.payload,
requestedBy: input.requestedBy,
});
} catch (e) {
const msg = e instanceof Error ? e.message : '';
if (/operation_type_check|violates check constraint/i.test(msg)) {
throw new FundApprovalError(
'Database schema is missing this operation type. Run db migrations and restart the backend.'
);
}
throw e;
}
await auditLogRepository.create({
userId: input.requestedBy,
action: 'fund_operation_requested',
resourceType: 'fund_operation_request',
resourceId: row.id,
metadata: { operation_type: input.operationType },
});
return toDto(row);
}
async function executeApprovedRequest(
request: FundOperationRequestRow,
approverId: string
): Promise<Record<string, unknown>> {
const approvedBy = approverId;
switch (request.operation_type) {
case 'ledger_credit': {
const { userId, walletTypeId, adjustmentType, amountRaw, reason } = request.payload as {
userId: string;
walletTypeId: number;
adjustmentType: 'bonus' | 'admin_adjustment';
amountRaw: string;
reason: string;
};
const result = await adminCreditService.grantLedgerCredit({
userId,
walletTypeId,
adjustmentType,
amountRaw,
reason,
approvedBy,
requestedBy: request.requested_by,
});
return result;
}
case 'treasury_cold_to_hot': {
const { walletTypeId, amountRaw, notes } = request.payload as {
walletTypeId: number;
amountRaw: string;
notes?: string;
};
const result = await treasuryService.requestColdToHotFunding(request.requested_by, {
walletTypeId,
amountRaw: BigInt(amountRaw),
notes,
approvedBy,
});
return result;
}
case 'bonus_pool_fund': {
const { walletTypeId, amountRaw } = request.payload as {
walletTypeId: number;
amountRaw: string;
};
const amount = BigInt(amountRaw);
await bonusPoolRepository.fundPool(walletTypeId, amount);
const pools = await bonusPoolRepository.listPools();
return { message: 'Pool funded', pools };
}
case 'sweep_manual': {
// Legacy: promote open batches to Approvals; also run any rare unbatched pending rows.
const { createSweepBatchApprovalRequests } = await import('./sweepBatchService');
const batchesSubmitted = await createSweepBatchApprovalRequests();
const processedUnbatched = await sweepService.processPendingSweeps({ unbatchedOnly: true });
return { batchesSubmitted, processedUnbatched };
}
case 'sweep_batch': {
const { batchId } = request.payload as { batchId: string };
const processed = await sweepService.executeApprovedBatch(batchId);
return { batchId, processed };
}
case 'treasury_hot_to_cold_gas': {
const { walletTypeId, amountRaw, notes } = request.payload as {
walletTypeId: number;
amountRaw: string;
notes?: string;
};
return treasuryService.executeHotToColdGas({
walletTypeId,
amountRaw: BigInt(amountRaw),
notes,
requestedBy: request.requested_by,
approvedBy,
});
}
case 'treasury_cold_to_hot_gas': {
const { walletTypeId, amountRaw, notes } = request.payload as {
walletTypeId: number;
amountRaw: string;
notes?: string;
};
return treasuryService.requestColdToHotGasFunding(request.requested_by, {
walletTypeId,
amountRaw: BigInt(amountRaw),
notes,
approvedBy,
});
}
default:
throw new FundApprovalError(`Unknown operation type: ${request.operation_type}`);
}
}
export async function approveFundRequest(
requestId: string,
approverId: string
): Promise<FundRequestDto> {
const canApprove = await roleRepository.userHasPermission(approverId, 'fund_operation.approve');
if (!canApprove) throw new FundApprovalError('Permission denied: fund_operation.approve');
const existing = await fundOperationRequestRepository.findById(requestId);
if (!existing) throw new FundApprovalError('Request not found');
if (existing.status !== 'pending_approval') {
throw new FundApprovalError(`Request is not pending (status: ${existing.status})`);
}
const approved = await fundOperationRequestRepository.markApproved(requestId, approverId);
if (!approved) throw new FundApprovalError('Failed to approve request');
try {
const executionResult = await executeApprovedRequest(approved, approverId);
await fundOperationRequestRepository.markExecuted(requestId, executionResult);
await auditLogRepository.create({
userId: approverId,
action: 'fund_operation_approved',
resourceType: 'fund_operation_request',
resourceId: requestId,
metadata: { operation_type: approved.operation_type, execution_result: executionResult },
});
const final = await fundOperationRequestRepository.findById(requestId);
return toDto(final!);
} catch (e) {
const msg = e instanceof Error ? e.message : 'Execution failed';
await fundOperationRequestRepository.markFailed(requestId, msg);
await auditLogRepository.create({
userId: approverId,
action: 'fund_operation_failed',
resourceType: 'fund_operation_request',
resourceId: requestId,
metadata: { error: msg },
});
throw new FundApprovalError(msg);
}
}
export async function rejectFundRequest(
requestId: string,
approverId: string,
reason: string
): Promise<FundRequestDto> {
const canApprove = await roleRepository.userHasPermission(approverId, 'fund_operation.approve');
if (!canApprove) throw new FundApprovalError('Permission denied: fund_operation.approve');
const trimmed = reason?.trim();
if (!trimmed) throw new FundApprovalError('Rejection reason is required');
const rejected = await fundOperationRequestRepository.markRejected(requestId, approverId, trimmed);
if (!rejected) throw new FundApprovalError('Request not found or not pending');
await auditLogRepository.create({
userId: approverId,
action: 'fund_operation_rejected',
resourceType: 'fund_operation_request',
resourceId: requestId,
metadata: { reason: trimmed },
});
return toDto(rejected);
}
export async function cancelFundRequest(
requestId: string,
actorId: string
): Promise<FundRequestDto> {
const existing = await fundOperationRequestRepository.findById(requestId);
if (!existing) throw new FundApprovalError('Request not found');
if (existing.status !== 'pending_approval') {
throw new FundApprovalError('Only pending requests can be cancelled');
}
const isRequester = existing.requested_by === actorId;
const isSuperAdmin = await roleRepository.userHasRole(actorId, 'super_admin');
if (!isRequester && !isSuperAdmin) {
throw new FundApprovalError('Only the requester or a super admin can cancel');
}
const cancelled = await fundOperationRequestRepository.markCancelled(requestId);
if (!cancelled) throw new FundApprovalError('Failed to cancel request');
return toDto(cancelled);
}
export async function getFundRequest(requestId: string): Promise<FundRequestDto | null> {
const row = await fundOperationRequestRepository.findById(requestId);
return row ? toDto(row) : null;
}
export async function listFundRequests(filters: {
status?: FundOperationStatus;
operationType?: FundOperationType;
limit?: number;
offset?: number;
}): Promise<{ items: FundRequestDto[]; total: number }> {
const result = await fundOperationRequestRepository.listRequests(filters);
return { items: result.items.map(toDto), total: result.total };
}
export type UserRoleName = RoleName;
export async function updateUserRoles(
targetUserId: string,
roleNames: string[],
adminUserId: string,
notifyCtx: { ipAddress?: string; userAgent?: string } = {}
): Promise<{ userId: string; roles: string[] }> {
const canManage = await roleRepository.userHasPermission(adminUserId, 'user.manage_roles');
if (!canManage) throw new FundApprovalError('Permission denied: user.manage_roles');
const unique = [...new Set(roleNames.map((r) => r.trim().toLowerCase()))].filter((r) =>
roleRepository.isKnownRoleName(r)
);
if (!unique.length) throw new FundApprovalError('At least one role is required');
const currentRoles = await roleRepository.getUserRoleNames(targetUserId);
const permissionsBefore = await roleRepository.getUserPermissions(targetUserId);
const removingSuperAdmin =
currentRoles.includes('super_admin') && !unique.includes('super_admin');
if (removingSuperAdmin) {
const count = await roleRepository.countUsersWithRoleName('super_admin');
if (count <= 1) {
throw new FundApprovalError('At least one super administrator must remain on the platform');
}
}
const removingAdmin = currentRoles.includes('admin') && !unique.includes('admin');
if (removingAdmin) {
const adminCount = await roleRepository.countUsersWithRoleName('admin');
if (adminCount <= 1) {
throw new FundApprovalError('At least one administrator must remain on the platform');
}
}
if (
targetUserId === adminUserId &&
currentRoles.includes('admin') &&
!unique.includes('admin')
) {
throw new FundApprovalError('You cannot remove your own administrator role');
}
await roleRepository.setUserRoles(targetUserId, unique);
await bumpUserTokenOnRoleChange(targetUserId);
const permissionsAfter = await roleRepository.getUserPermissions(targetUserId);
await auditLogRepository.create({
userId: adminUserId,
action: 'admin_user_roles_changed',
resourceType: 'user',
resourceId: targetUserId,
metadata: {
changed: ['roles'],
before: { roles: currentRoles },
after: { roles: unique },
},
});
const permsBeforeSorted = [...permissionsBefore].sort();
const permsAfterSorted = [...permissionsAfter].sort();
const permissionsChanged =
JSON.stringify(permsBeforeSorted) !== JSON.stringify(permsAfterSorted);
if (permissionsChanged) {
await auditLogRepository.create({
userId: adminUserId,
action: 'admin_user_permissions_changed',
resourceType: 'user',
resourceId: targetUserId,
metadata: {
changed: ['permissions'],
before: { permissions: permsBeforeSorted },
after: { permissions: permsAfterSorted },
},
});
}
void securityNotificationService.notifyRolesChanged(targetUserId, unique, notifyCtx);
if (permissionsChanged) {
void securityNotificationService.notifyPermissionsChanged(
targetUserId,
permsAfterSorted,
notifyCtx
);
}
return { userId: targetUserId, roles: unique };
}