@open-core/framework 0.1.0-alpha.1 → 0.2.0-beta.1

package/dist/{server/services → runtime/server/services/core}/player.service.js

@@ -5,21 +5,46 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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); }
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlayerService = void 0;
 const tsyringe_1 = require("tsyringe");
-const player_1 = require("../entities/player");
+const adapters_1 = require("../../../../adapters");
+const IEntityServer_1 = require("../../../../adapters/contracts/IEntityServer");
+const INetTransport_1 = require("../../../../adapters/contracts/INetTransport");
+const IPlayerServer_1 = require("../../../../adapters/contracts/IPlayerServer");
+const logger_1 = require("../../../../kernel/shared/logger");
+const entities_1 = require("../../entities");
 /**
  * Service responsible for managing the lifecycle of player sessions.
  * It acts as the central registry for all connected players, mapping FiveM client IDs
  * to Core `Player` entities.
+ *
+ * @remarks
+ * This service is used as a singleton in the dependency container.
+ * It exposes the operations defined by {@link PlayerDirectoryPort} and {@link PlayerSessionLifecyclePort}.
  */
 let PlayerService = class PlayerService {
-    constructor() {
+    constructor(playerInfo, playerServer, entityServer, netTransport) {
+        this.playerInfo = playerInfo;
+        this.playerServer = playerServer;
+        this.entityServer = entityServer;
+        this.netTransport = netTransport;
         /**
          * Internal map storing active player sessions indexed by their FiveM client ID (source).
          */
         this.playersByClient = new Map();
+        this.playerAdapters = {
+            playerInfo: this.playerInfo,
+            playerServer: this.playerServer,
+            entityServer: this.entityServer,
+            netTransport: this.netTransport,
+        };
     }
     /**
      * Initializes a new player session for a connecting client.
@@ -37,8 +62,12 @@ let PlayerService = class PlayerService {
             identifiers,
             meta: {},
         };
-        const player = new player_1.Player(session);
+        const player = new entities_1.Player(session, this.playerAdapters);
         this.playersByClient.set(clientID, player);
+        logger_1.loggers.session.debug('Player session bound', {
+            clientID,
+            totalPlayers: this.playersByClient.size,
+        });
         return player;
     }
     /**
@@ -64,11 +93,12 @@ let PlayerService = class PlayerService {
      *
      * @param clientID - The FiveM server ID of the player disconnecting.
      */
-    unbindByClient(clientID) {
-        const player = this.playersByClient.get(clientID);
-        if (!player)
-            return;
+    unbind(clientID) {
         this.playersByClient.delete(clientID);
+        logger_1.loggers.session.debug('Player session unbound', {
+            clientID,
+            totalPlayers: this.playersByClient.size,
+        });
     }
     /**
      * Retrieves the `Player` entity associated with a specific FiveM client ID.
@@ -77,8 +107,16 @@ let PlayerService = class PlayerService {
      * @returns The `Player` instance if found, or `null` if the session does not exist.
      */
     getByClient(clientID) {
-        var _a;
-        return (_a = this.playersByClient.get(clientID)) !== null && _a !== void 0 ? _a : null;
+        return this.playersByClient.get(clientID);
+    }
+    getMany(clientIds) {
+        const result = [];
+        for (const id of clientIds) {
+            const player = this.playersByClient.get(id);
+            if (player)
+                result.push(player);
+        }
+        return result;
     }
     /**
      * Helper to retrieve the authenticated Account ID for a given client.
@@ -87,9 +125,8 @@ let PlayerService = class PlayerService {
      * @returns The bound Account ID (string/UUID) if the player is logged in, or `null` otherwise.
      */
     getPlayerId(clientID) {
-        var _a;
         const player = this.playersByClient.get(clientID);
-        return (_a = player === null || player === void 0 ? void 0 : player.accountID) !== null && _a !== void 0 ? _a : null;
+        return player === null || player === void 0 ? void 0 : player.accountID;
     }
     /**
      * Stores arbitrary metadata in the player's session.
@@ -113,9 +150,9 @@ let PlayerService = class PlayerService {
      * @param key - The metadata key to retrieve.
      * @returns The value cast to type `T`, or `undefined` if the key or player doesn't exist.
      */
-    getMeta(clientID, key) {
+    async getMeta(clientID, key) {
         const player = this.playersByClient.get(clientID);
-        return player === null || player === void 0 ? void 0 : player.getMeta(key);
+        return await (player === null || player === void 0 ? void 0 : player.getMeta(key));
     }
     /**
      * Returns a list of all currently active `Player` entities.
@@ -125,8 +162,55 @@ let PlayerService = class PlayerService {
     getAll() {
         return Array.from(this.playersByClient.values());
     }
+    // ═══════════════════════════════════════════════════════════════
+    // Extended Query Methods
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Retrieves a Player by their persistent account ID.
+     *
+     * @param accountId - The unique account identifier to search for.
+     * @returns The Player if found, or `undefined` if not online.
+     */
+    getByAccountId(accountId) {
+        for (const player of this.playersByClient.values()) {
+            if (player.accountID === accountId) {
+                return player;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Returns the current number of connected players.
+     *
+     * @returns Player count.
+     */
+    getPlayerCount() {
+        return this.playersByClient.size;
+    }
+    /**
+     * Checks if a player with the given account ID is currently online.
+     *
+     * @param accountId - The account identifier to check.
+     * @returns `true` if online, `false` otherwise.
+     */
+    isOnline(accountId) {
+        for (const player of this.playersByClient.values()) {
+            if (player.accountID === accountId) {
+                return true;
+            }
+        }
+        return false;
+    }
 };
 exports.PlayerService = PlayerService;
 exports.PlayerService = PlayerService = __decorate([
-    (0, tsyringe_1.injectable)()
+    (0, tsyringe_1.injectable)(),
+    __param(0, (0, tsyringe_1.inject)(adapters_1.IPlayerInfo)),
+    __param(1, (0, tsyringe_1.inject)(IPlayerServer_1.IPlayerServer)),
+    __param(2, (0, tsyringe_1.inject)(IEntityServer_1.IEntityServer)),
+    __param(3, (0, tsyringe_1.inject)(INetTransport_1.INetTransport)),
+    __metadata("design:paramtypes", [adapters_1.IPlayerInfo,
+        IPlayerServer_1.IPlayerServer,
+        IEntityServer_1.IEntityServer,
+        INetTransport_1.INetTransport])
 ], PlayerService);

package/dist/runtime/server/services/core/principal.service.d.ts

@@ -0,0 +1,28 @@
+import { PrincipalProviderContract } from '../../contracts';
+import { Principal } from '../../contracts/security/permission.types';
+import { GuardOptions } from '../../decorators/guard';
+import { Player } from '../../entities';
+import { PrincipalPort } from '../ports/principal.port';
+/**
+ * Local principal service for CORE/STANDALONE mode.
+ *
+ * @remarks
+ * This service wraps the user-provided PrincipalProviderContract and provides
+ * convenience methods for permission checking. All operations are performed locally.
+ */
+export declare class LocalPrincipalService extends PrincipalPort {
+    private readonly provider;
+    constructor(provider: PrincipalProviderContract);
+    getPrincipal(player: Player): Promise<Principal | null>;
+    getPrincipalByAccountId(accountId: string): Promise<Principal | null>;
+    refreshPrincipal(player: Player): Promise<void>;
+    hasPermission(player: Player, permission: string): Promise<boolean>;
+    hasRank(player: Player, requiredRank: number): Promise<boolean>;
+    hasAnyPermission(player: Player, permissions: string[]): Promise<boolean>;
+    hasAllPermissions(player: Player, permissions: string[]): Promise<boolean>;
+    getPermissions(player: Player): Promise<string[]>;
+    getRank(player: Player): Promise<number | null>;
+    getPrincipalName(player: Player): Promise<string | null>;
+    getPrincipalMeta(player: Player, key: string): Promise<unknown>;
+    enforce(player: Player, requirements: GuardOptions): Promise<void>;
+}

package/dist/runtime/server/services/core/principal.service.js

@@ -0,0 +1,126 @@
+"use strict";
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalPrincipalService = void 0;
+const tsyringe_1 = require("tsyringe");
+const utils_1 = require("../../../../kernel/utils");
+const contracts_1 = require("../../contracts");
+const principal_port_1 = require("../ports/principal.port");
+/**
+ * Local principal service for CORE/STANDALONE mode.
+ *
+ * @remarks
+ * This service wraps the user-provided PrincipalProviderContract and provides
+ * convenience methods for permission checking. All operations are performed locally.
+ */
+let LocalPrincipalService = class LocalPrincipalService extends principal_port_1.PrincipalPort {
+    constructor(provider) {
+        super();
+        this.provider = provider;
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Principal Queries
+    // ═══════════════════════════════════════════════════════════════
+    async getPrincipal(player) {
+        return await this.provider.getPrincipal(player);
+    }
+    async getPrincipalByAccountId(accountId) {
+        return await this.provider.getPrincipalByLinkedID(accountId);
+    }
+    async refreshPrincipal(player) {
+        await this.provider.refreshPrincipal(player);
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Quick Authorization Checks
+    // ═══════════════════════════════════════════════════════════════
+    async hasPermission(player, permission) {
+        const principal = await this.provider.getPrincipal(player);
+        if (!principal)
+            return false;
+        // Check for wildcard (super-admin) or specific permission
+        return principal.permissions.includes('*') || principal.permissions.includes(permission);
+    }
+    async hasRank(player, requiredRank) {
+        const principal = await this.provider.getPrincipal(player);
+        if (!principal || principal.rank === undefined)
+            return false;
+        return principal.rank >= requiredRank;
+    }
+    async hasAnyPermission(player, permissions) {
+        const principal = await this.provider.getPrincipal(player);
+        if (!principal)
+            return false;
+        // Wildcard grants all permissions
+        if (principal.permissions.includes('*'))
+            return true;
+        return permissions.some((perm) => principal.permissions.includes(perm));
+    }
+    async hasAllPermissions(player, permissions) {
+        const principal = await this.provider.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
+    // ═══════════════════════════════════════════════════════════════
+    async getPermissions(player) {
+        var _a;
+        const principal = await this.provider.getPrincipal(player);
+        return (_a = principal === null || principal === void 0 ? void 0 : principal.permissions) !== null && _a !== void 0 ? _a : [];
+    }
+    async getRank(player) {
+        var _a;
+        const principal = await this.provider.getPrincipal(player);
+        return (_a = principal === null || principal === void 0 ? void 0 : principal.rank) !== null && _a !== void 0 ? _a : null;
+    }
+    async getPrincipalName(player) {
+        var _a;
+        const principal = await this.provider.getPrincipal(player);
+        return (_a = principal === null || principal === void 0 ? void 0 : principal.name) !== null && _a !== void 0 ? _a : null;
+    }
+    async getPrincipalMeta(player, key) {
+        var _a, _b;
+        const principal = await this.provider.getPrincipal(player);
+        return (_b = (_a = principal === null || principal === void 0 ? void 0 : principal.meta) === null || _a === void 0 ? void 0 : _a[key]) !== null && _b !== void 0 ? _b : null;
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Access Control Enforcement
+    // ═══════════════════════════════════════════════════════════════
+    async enforce(player, requirements) {
+        if (requirements.rank !== undefined) {
+            const principal = await this.provider.getPrincipal(player);
+            if (!principal) {
+                throw new utils_1.AppError('AUTH:UNAUTHORIZED', 'No principal found', 'core');
+            }
+            if (principal.rank === undefined) {
+                throw new utils_1.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 utils_1.AppError('AUTH:PERMISSION_DENIED', `Access Denied: Requires minimum rank level ${requirements.rank}`, 'core');
+            }
+        }
+        if (requirements.permission) {
+            const hasPerm = await this.hasPermission(player, requirements.permission);
+            if (!hasPerm) {
+                throw new utils_1.AppError('AUTH:PERMISSION_DENIED', `Access Denied: Missing required permission '${requirements.permission}'`, 'core');
+            }
+        }
+    }
+};
+exports.LocalPrincipalService = LocalPrincipalService;
+exports.LocalPrincipalService = LocalPrincipalService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [contracts_1.PrincipalProviderContract])
+], LocalPrincipalService);

package/dist/runtime/server/services/core/vehicle-modification.service.d.ts

@@ -0,0 +1,104 @@
+import { VehicleService } from './vehicle.service'
+import type { VehicleModificationOptions, VehicleMods } from '../../types/vehicle.types'
+/**
+ * Service for handling vehicle modifications with validation.
+ *
+ * This service is separated from VehicleService to maintain single responsibility.
+ * All modifications are validated server-side before being applied.
+ *
+ * Security features:
+ * - Ownership validation
+ * - Proximity checks
+ * - Modification limits
+ * - Audit logging
+ */
+export declare class VehicleModificationService {
+  private readonly vehicleService
+  constructor(vehicleService: VehicleService)
+  /**
+   * Applies modifications to a vehicle with validation.
+   *
+   * @param options - Modification options
+   * @returns Success status
+   */
+  applyModifications(options: VehicleModificationOptions): boolean
+  /**
+   * Sets vehicle colors with validation.
+   *
+   * @param networkId - Network ID of the vehicle
+   * @param primaryColor - Primary color ID
+   * @param secondaryColor - Secondary color ID
+   * @param requestedBy - Client ID requesting the change
+   * @returns Success status
+   */
+  setColors(
+    networkId: number,
+    primaryColor: number,
+    secondaryColor: number,
+    requestedBy?: number,
+  ): boolean
+  /**
+   * Sets vehicle livery with validation.
+   *
+   * @param networkId - Network ID of the vehicle
+   * @param livery - Livery index
+   * @param requestedBy - Client ID requesting the change
+   * @returns Success status
+   */
+  setLivery(networkId: number, livery: number, requestedBy?: number): boolean
+  /**
+   * Toggles vehicle turbo with validation.
+   *
+   * @param networkId - Network ID of the vehicle
+   * @param enabled - Whether turbo should be enabled
+   * @param requestedBy - Client ID requesting the change
+   * @returns Success status
+   */
+  setTurbo(networkId: number, enabled: boolean, requestedBy?: number): boolean
+  /**
+   * Sets vehicle window tint with validation.
+   *
+   * @param networkId - Network ID of the vehicle
+   * @param tint - Tint level (0-6)
+   * @param requestedBy - Client ID requesting the change
+   * @returns Success status
+   */
+  setWindowTint(networkId: number, tint: number, requestedBy?: number): boolean
+  /**
+   * Sets vehicle neon lights with validation.
+   *
+   * @param networkId - Network ID of the vehicle
+   * @param enabled - Array of [left, right, front, back] enabled states
+   * @param color - RGB color array
+   * @param requestedBy - Client ID requesting the change
+   * @returns Success status
+   */
+  setNeon(
+    networkId: number,
+    enabled: [boolean, boolean, boolean, boolean],
+    color?: [number, number, number],
+    requestedBy?: number,
+  ): boolean
+  /**
+   * Resets all modifications on a vehicle.
+   *
+   * @param networkId - Network ID of the vehicle
+   * @param requestedBy - Client ID requesting the reset
+   * @returns Success status
+   */
+  resetModifications(networkId: number, requestedBy?: number): boolean
+  /**
+   * Gets the current modifications of a vehicle.
+   *
+   * @param networkId - Network ID of the vehicle
+   * @returns Vehicle mods or undefined
+   */
+  getModifications(networkId: number): VehicleMods | undefined
+  /**
+   * Validates modification values to prevent exploits.
+   *
+   * @param mods - Modifications to validate
+   * @returns Validated modifications
+   */
+  private validateMods
+}