@open-core/framework 1.0.2-beta.1 → 1.0.5-beta.1

package/dist/runtime/server/controllers/player-export.controller.js

@@ -0,0 +1,172 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject } from 'tsyringe';
+import { Controller } from '../decorators/controller';
+import { Export } from '../decorators/export';
+import { Players } from '../ports/players.api-port';
+/**
+ * Exports player directory functionality for RESOURCE mode access.
+ *
+ * @remarks
+ * This controller provides a complete API for remote resources to:
+ * - Query player data (by client ID, account ID, or all players)
+ * - Check online status and player count
+ * - Read/write session metadata
+ * - Manage player state flags
+ */
+let PlayerExportController = class PlayerExportController {
+    playerService;
+    constructor(playerService) {
+        this.playerService = playerService;
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Basic Player Queries
+    // ═══════════════════════════════════════════════════════════════
+    getPlayerId(clientID) {
+        return this.playerService.getAccountLinked(clientID);
+    }
+    getPlayerData(clientID) {
+        const player = this.playerService.getByClient(clientID);
+        return player?.serialize() ?? null;
+    }
+    getManyData(clientIds) {
+        return this.playerService.getMany(clientIds).map((p) => p.serialize());
+    }
+    getAllPlayersData() {
+        return this.playerService.getAll().map((p) => p.serialize());
+    }
+    getPlayerByAccountId(accountId) {
+        const players = this.playerService.getAll();
+        const player = players.find((p) => p.accountID === accountId);
+        return player?.serialize() ?? null;
+    }
+    getPlayerCount() {
+        return this.playerService.getAll().length;
+    }
+    isPlayerOnline(accountId) {
+        const players = this.playerService.getAll();
+        return players.some((p) => p.accountID === accountId);
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Metadata Operations
+    // ═══════════════════════════════════════════════════════════════
+    async getPlayerMeta(clientID, key) {
+        return await this.playerService.getMeta(clientID, key);
+    }
+    setPlayerMeta(clientID, key, value) {
+        this.playerService.setMeta(clientID, key, value);
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // State Management
+    // ═══════════════════════════════════════════════════════════════
+    getPlayerStates(clientID) {
+        const player = this.playerService.getByClient(clientID);
+        return player?.getStates() ?? [];
+    }
+    hasPlayerState(clientID, state) {
+        const player = this.playerService.getByClient(clientID);
+        return player?.hasState(state) ?? false;
+    }
+    addPlayerState(clientID, state) {
+        const player = this.playerService.getByClient(clientID);
+        player?.addState(state);
+    }
+    removePlayerState(clientID, state) {
+        const player = this.playerService.getByClient(clientID);
+        player?.removeState(state);
+    }
+};
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number]),
+    __metadata("design:returntype", Object)
+], PlayerExportController.prototype, "getPlayerId", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number]),
+    __metadata("design:returntype", Object)
+], PlayerExportController.prototype, "getPlayerData", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Array]),
+    __metadata("design:returntype", Array)
+], PlayerExportController.prototype, "getManyData", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Array)
+], PlayerExportController.prototype, "getAllPlayersData", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Object)
+], PlayerExportController.prototype, "getPlayerByAccountId", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Number)
+], PlayerExportController.prototype, "getPlayerCount", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Boolean)
+], PlayerExportController.prototype, "isPlayerOnline", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, String]),
+    __metadata("design:returntype", Promise)
+], PlayerExportController.prototype, "getPlayerMeta", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, String, Object]),
+    __metadata("design:returntype", void 0)
+], PlayerExportController.prototype, "setPlayerMeta", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number]),
+    __metadata("design:returntype", Array)
+], PlayerExportController.prototype, "getPlayerStates", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, String]),
+    __metadata("design:returntype", Boolean)
+], PlayerExportController.prototype, "hasPlayerState", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, String]),
+    __metadata("design:returntype", void 0)
+], PlayerExportController.prototype, "addPlayerState", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, String]),
+    __metadata("design:returntype", void 0)
+], PlayerExportController.prototype, "removePlayerState", null);
+PlayerExportController = __decorate([
+    Controller(),
+    __param(0, inject(Players)),
+    __metadata("design:paramtypes", [Players])
+], PlayerExportController);
+export { PlayerExportController };

package/dist/runtime/server/controllers/principal-export.controller.d.ts

@@ -0,0 +1,79 @@
+import { Principal, PrincipalProviderContract } from '../contracts/index';
+import { GuardOptions } from '../decorators/guard';
+import { Players } from '../ports/players.api-port';
+/**
+ * Exports principal/permission functionality for RESOURCE mode access.
+ *
+ * @remarks
+ * This controller provides a complete API for remote resources to:
+ * - Query player permissions and ranks
+ * - Perform quick authorization checks
+ * - Refresh cached permissions
+ * - Query offline player permissions by account ID
+ */
+export declare class PrincipalExportController {
+    private readonly playerService;
+    private readonly principalProvider;
+    constructor(playerService: Players, principalProvider: PrincipalProviderContract);
+    /**
+     * Gets the full Principal object for a player.
+     */
+    getPrincipal(source: number): Promise<Principal | null>;
+    /**
+     * Gets Principal by account ID (works for offline players too).
+     */
+    getPrincipalByAccountId(accountId: string): Promise<Principal | null>;
+    /**
+     * Forces a refresh of the player's permissions from persistence.
+     */
+    refreshPrincipal(source: number): Promise<void>;
+    /**
+     * Checks if player has a specific permission.
+     *
+     * @remarks
+     * Supports wildcard '*' permission for super-admin access.
+     */
+    hasPermission(source: number, permission: string): Promise<boolean>;
+    /**
+     * Checks if player has at least the required rank.
+     *
+     * @remarks
+     * Uses numeric comparison: playerRank >= requiredRank
+     */
+    hasRank(source: number, requiredRank: number): Promise<boolean>;
+    /**
+     * Checks if player has ANY of the specified permissions.
+     */
+    hasAnyPermission(source: number, permissions: string[]): Promise<boolean>;
+    /**
+     * Checks if player has ALL of the specified permissions.
+     */
+    hasAllPermissions(source: number, permissions: string[]): Promise<boolean>;
+    /**
+     * Gets all permissions for a player.
+     */
+    getPermissions(source: number): Promise<string[]>;
+    /**
+     * Gets the rank value for a player.
+     */
+    getRank(source: number): Promise<number | null>;
+    /**
+     * Gets the principal name/role name for a player.
+     */
+    getPrincipalName(source: number): Promise<string | null>;
+    /**
+     * Gets principal metadata for a player.
+     */
+    getPrincipalMeta(source: number, key: string): Promise<unknown>;
+    /**
+     * Enforces access control requirements, throwing on failure.
+     *
+     * @remarks
+     * Used by RESOURCE mode to delegate security validation to CORE.
+     * Validates rank and/or permission requirements and throws if player
+     * doesn't meet the criteria.
+     *
+     * @throws AppError - AUTH:UNAUTHORIZED, GAME:NO_RANK_IN_PRINCIPAL, or AUTH:PERMISSION_DENIED
+     */
+    enforce(source: number, requirements: GuardOptions): Promise<void>;
+}

package/dist/runtime/server/controllers/principal-export.controller.js

@@ -0,0 +1,292 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject } from 'tsyringe';
+import { AppError } from '../../../kernel/error/app.error';
+import { PrincipalProviderContract } from '../contracts/index';
+import { Export } from '../decorators/export';
+import { Controller } from '../decorators/index';
+import { Players } from '../ports/players.api-port';
+/**
+ * Exports principal/permission functionality for RESOURCE mode access.
+ *
+ * @remarks
+ * This controller provides a complete API for remote resources to:
+ * - Query player permissions and ranks
+ * - Perform quick authorization checks
+ * - Refresh cached permissions
+ * - Query offline player permissions by account ID
+ */
+let PrincipalExportController = class PrincipalExportController {
+    playerService;
+    principalProvider;
+    constructor(playerService, principalProvider) {
+        this.playerService = playerService;
+        this.principalProvider = principalProvider;
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Principal Queries
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Gets the full Principal object for a player.
+     */
+    async getPrincipal(source) {
+        const player = this.playerService.getByClient(source);
+        if (!player)
+            return null;
+        return await this.principalProvider.getPrincipal(player);
+    }
+    /**
+     * Gets Principal by account ID (works for offline players too).
+     */
+    async getPrincipalByAccountId(accountId) {
+        return await this.principalProvider.getPrincipalByLinkedID(accountId);
+    }
+    /**
+     * Forces a refresh of the player's permissions from persistence.
+     */
+    async refreshPrincipal(source) {
+        const player = this.playerService.getByClient(source);
+        if (!player)
+            return;
+        await this.principalProvider.refreshPrincipal(player);
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Quick Authorization Checks
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Checks if player has a specific permission.
+     *
+     * @remarks
+     * Supports wildcard '*' permission for super-admin access.
+     */
+    async hasPermission(source, permission) {
+        const player = this.playerService.getByClient(source);
+        if (!player)
+            return false;
+        const principal = await this.principalProvider.getPrincipal(player);
+        if (!principal)
+            return false;
+        // Check for wildcard (super-admin) or specific permission
+        return principal.permissions.includes('*') || principal.permissions.includes(permission);
+    }
+    /**
+     * Checks if player has at least the required rank.
+     *
+     * @remarks
+     * Uses numeric comparison: playerRank >= requiredRank
+     */
+    async hasRank(source, requiredRank) {
+        const player = this.playerService.getByClient(source);
+        if (!player)
+            return false;
+        const principal = await this.principalProvider.getPrincipal(player);
+        if (!principal || principal.rank === undefined)
+            return false;
+        return principal.rank >= requiredRank;
+    }
+    /**
+     * Checks if player has ANY of the specified permissions.
+     */
+    async hasAnyPermission(source, permissions) {
+        const player = this.playerService.getByClient(source);
+        if (!player)
+            return false;
+        const principal = await this.principalProvider.getPrincipal(player);
+        if (!principal)
+            return false;
+        // Wildcard grants all permissions
+        if (principal.permissions.includes('*'))
+            return true;
+        return permissions.some((perm) => principal.permissions.includes(perm));
+    }
+    /**
+     * Checks if player has ALL of the specified permissions.
+     */
+    async hasAllPermissions(source, permissions) {
+        const player = this.playerService.getByClient(source);
+        if (!player)
+            return false;
+        const principal = await this.principalProvider.getPrincipal(player);
+        if (!principal)
+            return false;
+        // Wildcard grants all permissions
+        if (principal.permissions.includes('*'))
+            return true;
+        return permissions.every((perm) => principal.permissions.includes(perm));
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Property Getters
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Gets all permissions for a player.
+     */
+    async getPermissions(source) {
+        const player = this.playerService.getByClient(source);
+        if (!player)
+            return [];
+        const principal = await this.principalProvider.getPrincipal(player);
+        return principal?.permissions ?? [];
+    }
+    /**
+     * Gets the rank value for a player.
+     */
+    async getRank(source) {
+        const player = this.playerService.getByClient(source);
+        if (!player)
+            return null;
+        const principal = await this.principalProvider.getPrincipal(player);
+        return principal?.rank ?? null;
+    }
+    /**
+     * Gets the principal name/role name for a player.
+     */
+    async getPrincipalName(source) {
+        const player = this.playerService.getByClient(source);
+        if (!player)
+            return null;
+        const principal = await this.principalProvider.getPrincipal(player);
+        return principal?.name ?? null;
+    }
+    /**
+     * Gets principal metadata for a player.
+     */
+    async getPrincipalMeta(source, key) {
+        const player = this.playerService.getByClient(source);
+        if (!player)
+            return null;
+        const principal = await this.principalProvider.getPrincipal(player);
+        return principal?.meta?.[key] ?? null;
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Access Control Enforcement
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Enforces access control requirements, throwing on failure.
+     *
+     * @remarks
+     * Used by RESOURCE mode to delegate security validation to CORE.
+     * Validates rank and/or permission requirements and throws if player
+     * doesn't meet the criteria.
+     *
+     * @throws AppError - AUTH:UNAUTHORIZED, GAME:NO_RANK_IN_PRINCIPAL, or AUTH:PERMISSION_DENIED
+     */
+    async enforce(source, requirements) {
+        const player = this.playerService.getByClient(source);
+        if (!player) {
+            throw new AppError('GAME:PLAYER_NOT_FOUND', `Player not found: ${source}`, 'core');
+        }
+        if (requirements.rank !== undefined) {
+            const principal = await this.principalProvider.getPrincipal(player);
+            if (!principal) {
+                throw new AppError('AUTH:UNAUTHORIZED', 'No principal found', 'core');
+            }
+            if (principal.rank === undefined) {
+                throw new AppError('GAME:NO_RANK_IN_PRINCIPAL', "You're trying to compare a Principal rank, but there's no defined rank!", 'core');
+            }
+            if (principal.rank < requirements.rank) {
+                throw new AppError('AUTH:PERMISSION_DENIED', `Access Denied: Requires minimum rank level ${requirements.rank}`, 'core');
+            }
+        }
+        if (requirements.permission) {
+            const principal = await this.principalProvider.getPrincipal(player);
+            if (!principal) {
+                throw new AppError('AUTH:PERMISSION_DENIED', `Access Denied: Missing required permission '${requirements.permission}'`, 'core');
+            }
+            const hasPerm = principal.permissions.includes('*') ||
+                principal.permissions.includes(requirements.permission);
+            if (!hasPerm) {
+                throw new AppError('AUTH:PERMISSION_DENIED', `Access Denied: Missing required permission '${requirements.permission}'`, 'core');
+            }
+        }
+    }
+};
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number]),
+    __metadata("design:returntype", Promise)
+], PrincipalExportController.prototype, "getPrincipal", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], PrincipalExportController.prototype, "getPrincipalByAccountId", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number]),
+    __metadata("design:returntype", Promise)
+], PrincipalExportController.prototype, "refreshPrincipal", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, String]),
+    __metadata("design:returntype", Promise)
+], PrincipalExportController.prototype, "hasPermission", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, Number]),
+    __metadata("design:returntype", Promise)
+], PrincipalExportController.prototype, "hasRank", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, Array]),
+    __metadata("design:returntype", Promise)
+], PrincipalExportController.prototype, "hasAnyPermission", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, Array]),
+    __metadata("design:returntype", Promise)
+], PrincipalExportController.prototype, "hasAllPermissions", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number]),
+    __metadata("design:returntype", Promise)
+], PrincipalExportController.prototype, "getPermissions", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number]),
+    __metadata("design:returntype", Promise)
+], PrincipalExportController.prototype, "getRank", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number]),
+    __metadata("design:returntype", Promise)
+], PrincipalExportController.prototype, "getPrincipalName", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, String]),
+    __metadata("design:returntype", Promise)
+], PrincipalExportController.prototype, "getPrincipalMeta", null);
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, Object]),
+    __metadata("design:returntype", Promise)
+], PrincipalExportController.prototype, "enforce", null);
+PrincipalExportController = __decorate([
+    Controller(),
+    __param(0, inject(Players)),
+    __param(1, inject(PrincipalProviderContract)),
+    __metadata("design:paramtypes", [Players,
+        PrincipalProviderContract])
+], PrincipalExportController);
+export { PrincipalExportController };

package/dist/runtime/server/controllers/ready.controller.d.ts

@@ -0,0 +1,4 @@
+export declare class ReadyController {
+    private isReady;
+    isCoreReady(): boolean;
+}

package/dist/runtime/server/controllers/ready.controller.js

@@ -0,0 +1,27 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Controller } from '../decorators/controller';
+import { Export } from '../decorators/export';
+let ReadyController = class ReadyController {
+    isReady = true;
+    isCoreReady() {
+        return this.isReady;
+    }
+};
+__decorate([
+    Export(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Boolean)
+], ReadyController.prototype, "isCoreReady", null);
+ReadyController = __decorate([
+    Controller()
+], ReadyController);
+export { ReadyController };

package/dist/runtime/server/controllers/remote-command-execution.controller.d.ts

@@ -0,0 +1,52 @@
+import { IEngineEvents } from '../../../adapters/contracts/IEngineEvents';
+import { IResourceInfo } from '../../../adapters/contracts/IResourceInfo';
+import { CommandErrorObserverContract } from '../contracts/security/command-error-observer.contract';
+import { CommandExecutionPort } from '../ports/internal/command-execution.port';
+import { Players } from '../ports/players.api-port';
+/**
+ * Controller for executing remote commands in RESOURCE mode.
+ *
+ * @remarks
+ * Listens for command execution events from CORE and invokes
+ * the local handler stored in RemoteCommandService.
+ *
+ * Flow:
+ * 1. Player executes command → sent to CORE
+ * 2. CORE validates and emits local event to owning resource
+ * 3. This controller receives event → looks up handler → executes
+ *
+ * @note Uses IEngineEvents.on() (local event) not @OnNet (network event)
+ * because CORE→RESOURCE communication is server-to-server.
+ * Event registration happens in constructor via adapter layer.
+ */
+export declare class RemoteCommandExecutionController {
+    private commandService;
+    private playerDirectory;
+    private readonly commandErrorObserver;
+    private engineEvents;
+    private resourceInfo;
+    constructor(commandService: CommandExecutionPort, playerDirectory: Players, commandErrorObserver: CommandErrorObserverContract, engineEvents: IEngineEvents, resourceInfo: IResourceInfo);
+    /**
+     * Invokes the global {@link CommandErrorObserverContract} safely.
+     *
+     * @remarks
+     * Observers are user-land code; failures must never break command execution.
+     */
+    private safeObserve;
+    /**
+     * Registers the event handler for command execution from CORE.
+     *
+     * @remarks
+     * Event format: `opencore:command:execute:{resourceName}`
+     * Uses adapter layer instead of direct FiveM globals.
+     */
+    private registerEventHandler;
+    /**
+     * Handles command execution requests from CORE.
+     *
+     * @param clientID - The client ID of the player executing the command
+     * @param commandName - The command to execute
+     * @param args - Command arguments
+     */
+    private handleCommandExecution;
+}