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

package/dist/{server → runtime/server}/services/parallel/worker.d.ts

@@ -8,7 +8,7 @@
  * When FiveM or the target environment supports native worker threads,
  * this script can be used as the worker entry point.
  */
-import type { WorkerMessage, WorkerResponse } from './types';
+import { WorkerMessage, WorkerResponse } from './types';
 /**
  * Execute a compute function from its string body
  */

package/dist/{server → runtime/server}/services/persistence.service.d.ts

@@ -1,4 +1,4 @@
-import type { Player } from '../entities/player';
+import { Player } from '../entities/player';
 /**
  * Internal service that orchestrates player data persistence.
  *

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

@@ -8,9 +8,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlayerPersistenceService = void 0;
 const tsyringe_1 = require("tsyringe");
-const container_1 = require("../container");
-const persistence_1 = require("../templates/persistence");
-const logger_1 = require("../../shared/logger");
+const container_1 = require("../../../kernel/di/container");
+const logger_1 = require("../../../kernel/shared/logger");
+const contracts_1 = require("../contracts");
 /**
  * Internal service that orchestrates player data persistence.
  *
@@ -31,8 +31,8 @@ let PlayerPersistenceService = class PlayerPersistenceService {
         if (this.initialized)
             return;
         try {
-            if (container_1.di.isRegistered(persistence_1.PlayerPersistenceContract)) {
-                const provider = container_1.di.resolve(persistence_1.PlayerPersistenceContract);
+            if (container_1.di.isRegistered(contracts_1.PlayerPersistenceContract)) {
+                const provider = container_1.di.resolve(contracts_1.PlayerPersistenceContract);
                 this.provider = provider;
                 logger_1.loggers.bootstrap.info('Player Persistence Provider initialized', {
                     autoSaveEnabled: provider.config.autoSaveEnabled,
@@ -115,9 +115,12 @@ let PlayerPersistenceService = class PlayerPersistenceService {
     async saveAllPlayers(players) {
         if (!this.provider)
             return;
-        const savePromises = players.map((player) => this.provider.onSessionSave(player).catch((error) => {
-            logger_1.loggers.session.error('Failed to save player data during bulk save', { clientId: player.clientID }, error);
-        }));
+        const savePromises = players.map((player) => {
+            var _a;
+            return (_a = this.provider) === null || _a === void 0 ? void 0 : _a.onSessionSave(player).catch((error) => {
+                logger_1.loggers.session.error('Failed to save player data during bulk save', { clientId: player.clientID }, error);
+            });
+        });
         await Promise.all(savePromises);
         logger_1.loggers.session.info('Bulk player save completed', { playerCount: players.length });
     }
@@ -129,8 +132,9 @@ let PlayerPersistenceService = class PlayerPersistenceService {
             return;
         const intervalMs = this.provider.config.autoSaveIntervalMs;
         const interval = setInterval(async () => {
+            var _a;
             try {
-                await this.provider.onAutoSave(player);
+                await ((_a = this.provider) === null || _a === void 0 ? void 0 : _a.onAutoSave(player));
                 logger_1.loggers.session.debug('Player auto-save completed', { clientId: player.clientID });
             }
             catch (error) {

package/dist/runtime/server/services/ports/command-execution.port.d.ts

@@ -0,0 +1,41 @@
+import { CommandMetadata } from '../../decorators/command';
+import { Player } from '../../entities';
+/**
+ * Command information returned by getAllCommands.
+ */
+export interface CommandInfo {
+    command: string;
+    description?: string;
+    usage?: string;
+    isPublic: boolean;
+}
+/**
+ * Abstract port for command registration and execution.
+ *
+ * @remarks
+ * This port provides mode-agnostic access to the command system.
+ * Implementations:
+ * - CommandService (local): CORE/STANDALONE modes maintain command registry locally
+ * - RemoteCommandService (remote): RESOURCE mode delegates to CORE via exports
+ */
+export declare abstract class CommandExecutionPort {
+    /**
+     * Registers a command handler.
+     *
+     * @param metadata - Command metadata from decorator
+     * @param handler - Bound method to invoke when command is executed
+     */
+    abstract register(metadata: CommandMetadata, handler: Function): void;
+    /**
+     * Executes a registered command.
+     *
+     * @param player - Player invoking the command
+     * @param commandName - Command name (without leading slash)
+     * @param args - Raw argument strings
+     */
+    abstract execute(player: Player, commandName: string, args: string[]): Promise<void>;
+    /**
+     * Returns all registered commands.
+     */
+    abstract getAllCommands(): CommandInfo[];
+}

package/dist/runtime/server/services/ports/command-execution.port.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandExecutionPort = void 0;
+/**
+ * Abstract port for command registration and execution.
+ *
+ * @remarks
+ * This port provides mode-agnostic access to the command system.
+ * Implementations:
+ * - CommandService (local): CORE/STANDALONE modes maintain command registry locally
+ * - RemoteCommandService (remote): RESOURCE mode delegates to CORE via exports
+ */
+class CommandExecutionPort {
+}
+exports.CommandExecutionPort = CommandExecutionPort;

package/dist/runtime/server/services/ports/player-directory.port.d.ts

@@ -0,0 +1,107 @@
+import { Player } from '../../entities';
+/**
+ * Core port that provides access to active player sessions.
+ *
+ * @remarks
+ * This port defines a framework-owned boundary for querying and managing player-related data
+ * regardless of the current runtime mode (CORE, RESOURCE, etc.).
+ *
+ * Implementations of this port are responsible for resolving player information
+ * from the authoritative source (local session store, remote core exports, etc.).
+ *
+ * Consumers should treat returned {@link Player} instances as runtime representations
+ * of connected clients, not as persistent domain models.
+ *
+ * **Mode Differences:**
+ * - **CORE/STANDALONE**: Data is local and authoritative
+ * - **RESOURCE**: Data is fetched from CORE via exports
+ */
+export declare abstract class PlayerDirectoryPort {
+    /**
+     * Returns the {@link Player} associated with a given FiveM client ID.
+     *
+     * @param clientID - The FiveM server client ID (`source`).
+     * @returns The corresponding {@link Player} instance, or `undefined` if the player is not connected.
+     */
+    abstract getByClient(clientID: number): Player | undefined;
+    /**
+     * Returns a group of {@link Player} associated with a given fivem clients ids
+     *
+     * @param clientIds The fivem server client ID (`source`)
+     */
+    abstract getMany(clientIds: number[]): Player[];
+    /**
+     * Returns all currently connected players.
+     *
+     * @returns An array of {@link Player} instances representing all active clients.
+     */
+    abstract getAll(): Player[];
+    /**
+     * Returns the persistent account identifier associated with a client.
+     *
+     * @remarks
+     * The returned identifier is typically assigned after authentication and may be
+     * `undefined` if the player has not completed the login or character selection flow.
+     *
+     * @param clientID - The FiveM server client ID (`source`).
+     * @returns The linked account ID, or `undefined` if none is associated.
+     */
+    abstract getPlayerId(clientID: number): string | undefined;
+    /**
+     * Retrieves a metadata value associated with a player session.
+     *
+     * @remarks
+     * Metadata values are transient and scoped to the current session.
+     * Implementations may resolve this data locally or delegate to the core runtime.
+     *
+     * @typeParam T - The expected type of the stored value.
+     * @param clientID - The FiveM server client ID (`source`).
+     * @param key - The metadata key to retrieve.
+     * @returns The stored value, or `undefined` if the key does not exist.
+     */
+    abstract getMeta<T = unknown>(clientID: number, key: string): Promise<T | undefined>;
+    /**
+     * Stores a metadata value in the player session.
+     *
+     * @remarks
+     * Metadata is intended for transient runtime state such as flags, gameplay context,
+     * or temporary attributes. It is not persisted across reconnects.
+     *
+     * @param clientID - The FiveM server client ID (`source`).
+     * @param key - The metadata key to store.
+     * @param value - The value to associate with the given key.
+     */
+    abstract setMeta(clientID: number, key: string, value: unknown): void;
+    /**
+     * Returns the {@link Player} associated with a persistent account ID.
+     *
+     * @remarks
+     * Searches all connected players for one with the matching accountID.
+     * Returns `undefined` if no player with that account is currently online.
+     *
+     * @param accountId - The persistent account identifier.
+     * @returns The corresponding {@link Player} instance, or `undefined` if not online.
+     */
+    getByAccountId?(accountId: string): Player | undefined;
+    /**
+     * Returns the current number of connected players.
+     *
+     * @remarks
+     * More efficient than `getAll().length` for implementations that
+     * can provide a count without fetching all player data.
+     *
+     * @returns The number of currently connected players.
+     */
+    getPlayerCount?(): number;
+    /**
+     * Checks if a player with the given account ID is currently online.
+     *
+     * @remarks
+     * More efficient than `getByAccountId() !== undefined` for implementations
+     * that can check presence without fetching full player data.
+     *
+     * @param accountId - The persistent account identifier.
+     * @returns `true` if the player is online, `false` otherwise.
+     */
+    isOnline?(accountId: string): boolean;
+}

package/dist/runtime/server/services/ports/player-directory.port.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlayerDirectoryPort = void 0;
+/**
+ * Core port that provides access to active player sessions.
+ *
+ * @remarks
+ * This port defines a framework-owned boundary for querying and managing player-related data
+ * regardless of the current runtime mode (CORE, RESOURCE, etc.).
+ *
+ * Implementations of this port are responsible for resolving player information
+ * from the authoritative source (local session store, remote core exports, etc.).
+ *
+ * Consumers should treat returned {@link Player} instances as runtime representations
+ * of connected clients, not as persistent domain models.
+ *
+ * **Mode Differences:**
+ * - **CORE/STANDALONE**: Data is local and authoritative
+ * - **RESOURCE**: Data is fetched from CORE via exports
+ */
+class PlayerDirectoryPort {
+}
+exports.PlayerDirectoryPort = PlayerDirectoryPort;

package/dist/runtime/server/services/ports/player-session-lifecycle.port.d.ts

@@ -0,0 +1,49 @@
+import { Player } from '../../entities';
+import { LinkedID } from '../types/linked-id';
+import { PlayerSession } from '../types/player-session.object';
+/**
+ * Core port responsible for managing the lifecycle of player sessions.
+ *
+ * @remarks
+ * This port defines the authoritative boundary for creating, linking, and
+ * destroying player sessions within the framework.
+ *
+ * Implementations of this port own the session state and are expected to be
+ * invoked in response to connection, authentication, and disconnection events.
+ */
+export declare abstract class PlayerSessionLifecyclePort {
+    /**
+     * Creates and binds a new player session to a connected client.
+     *
+     * @remarks
+     * This method is typically called when a player joins the server or completes
+     * the initial handshake phase. The returned {@link Player} represents the
+     * runtime session associated with the client.
+     *
+     * @param clientID - The FiveM server client ID (`source`).
+     * @param identifiers - Optional platform identifiers (license, steam, etc.).
+     * @returns The newly created {@link Player} instance.
+     */
+    abstract bind(clientID: number, identifiers?: PlayerSession['identifiers']): Player;
+    /**
+     * Terminates and removes the player session associated with a client.
+     *
+     * @remarks
+     * This method should be called when the client disconnects to ensure
+     * session state is properly cleaned up and memory is released.
+     *
+     * @param clientID - The FiveM server client ID (`source`).
+     */
+    abstract unbind(clientID: number): void;
+    /**
+     * Links an authenticated account to an existing player session.
+     *
+     * @remarks
+     * This method is typically invoked after successful authentication or
+     * character selection to associate persistent data with the active session.
+     *
+     * @param clientID - The FiveM server client ID (`source`).
+     * @param accountID - The persistent account identifier.
+     */
+    abstract linkAccount(clientID: number, accountID: LinkedID): void;
+}

package/dist/runtime/server/services/ports/player-session-lifecycle.port.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlayerSessionLifecyclePort = void 0;
+/**
+ * Core port responsible for managing the lifecycle of player sessions.
+ *
+ * @remarks
+ * This port defines the authoritative boundary for creating, linking, and
+ * destroying player sessions within the framework.
+ *
+ * Implementations of this port own the session state and are expected to be
+ * invoked in response to connection, authentication, and disconnection events.
+ */
+class PlayerSessionLifecyclePort {
+}
+exports.PlayerSessionLifecyclePort = PlayerSessionLifecyclePort;

package/dist/runtime/server/services/ports/principal.port.d.ts

@@ -0,0 +1,149 @@
+import { Principal } from '../../contracts/security/permission.types';
+import { GuardOptions } from '../../decorators/guard';
+import { Player } from '../../entities';
+/**
+ * Core port that provides access to player authorization and permissions.
+ *
+ * @remarks
+ * This port defines a framework-owned boundary for querying permission-related data
+ * regardless of the current runtime mode (CORE, RESOURCE, etc.).
+ *
+ * Implementations of this port are responsible for resolving permission information
+ * from the authoritative source (local provider, remote core exports, etc.).
+ *
+ * **Mode Differences:**
+ * - **CORE/STANDALONE**: Uses the user-provided PrincipalProviderContract directly
+ * - **RESOURCE**: Delegates to CORE via exports
+ *
+ * **Usage:**
+ * ```typescript
+ * @injectable()
+ * class MyService {
+ *   constructor(private principal: PrincipalPort) {}
+ *
+ *   async canBan(player: Player): Promise<boolean> {
+ *     return await this.principal.hasPermission(player, 'admin.ban')
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class PrincipalPort {
+    /**
+     * Gets the full Principal object for a player.
+     *
+     * @param player - The player entity
+     * @returns Principal data or null if not authenticated
+     */
+    abstract getPrincipal(player: Player): Promise<Principal | null>;
+    /**
+     * Gets Principal by account ID (works for offline players too).
+     *
+     * @param accountId - Database account identifier
+     * @returns Principal data or null
+     */
+    abstract getPrincipalByAccountId(accountId: string): Promise<Principal | null>;
+    /**
+     * Forces a refresh of the player's permissions from persistence.
+     *
+     * @remarks
+     * Use this after promoting/demoting a player while they're online.
+     *
+     * @param player - The player to refresh
+     */
+    abstract refreshPrincipal(player: Player): Promise<void>;
+    /**
+     * Checks if player has a specific permission.
+     *
+     * @remarks
+     * Supports wildcard '*' permission for super-admin access.
+     *
+     * @param player - The player entity
+     * @param permission - Permission string to check
+     * @returns True if player has permission
+     */
+    abstract hasPermission(player: Player, permission: string): Promise<boolean>;
+    /**
+     * Checks if player has at least the required rank.
+     *
+     * @remarks
+     * Uses numeric comparison: playerRank >= requiredRank
+     *
+     * @param player - The player entity
+     * @param requiredRank - Minimum rank value
+     * @returns True if playerRank >= requiredRank
+     */
+    abstract hasRank(player: Player, requiredRank: number): Promise<boolean>;
+    /**
+     * Checks if player has ANY of the specified permissions.
+     *
+     * @param player - The player entity
+     * @param permissions - Array of permissions to check
+     * @returns True if player has at least one permission
+     */
+    abstract hasAnyPermission(player: Player, permissions: string[]): Promise<boolean>;
+    /**
+     * Checks if player has ALL of the specified permissions.
+     *
+     * @param player - The player entity
+     * @param permissions - Array of permissions to check
+     * @returns True if player has all permissions
+     */
+    abstract hasAllPermissions(player: Player, permissions: string[]): Promise<boolean>;
+    /**
+     * Gets all permissions for a player.
+     *
+     * @param player - The player entity
+     * @returns Array of permission strings
+     */
+    abstract getPermissions(player: Player): Promise<string[]>;
+    /**
+     * Gets the rank value for a player.
+     *
+     * @param player - The player entity
+     * @returns Rank number or null if not set
+     */
+    abstract getRank(player: Player): Promise<number | null>;
+    /**
+     * Gets the principal name/role name for a player.
+     *
+     * @param player - The player entity
+     * @returns Role name or null
+     */
+    abstract getPrincipalName(player: Player): Promise<string | null>;
+    /**
+     * Gets principal metadata for a player.
+     *
+     * @param player - The player entity
+     * @param key - Metadata key
+     * @returns Metadata value or null
+     */
+    abstract getPrincipalMeta(player: Player, key: string): Promise<unknown>;
+    /**
+     * Enforces access control requirements, throwing on failure.
+     *
+     * @remarks
+     * This is the primary method used by `@Guard` decorator and security validation.
+     * It validates rank and/or permission requirements and throws `AppError` if
+     * the player doesn't meet the criteria.
+     *
+     * **Validation Order:**
+     * 1. Rank check (if `rank` specified)
+     * 2. Permission check (if `permission` specified)
+     *
+     * @param player - The player entity to validate
+     * @param requirements - Guard options containing rank and/or permission requirements
+     *
+     * @throws AppError - `AUTH:UNAUTHORIZED` if player has no principal
+     * @throws AppError - `GAME:NO_RANK_IN_PRINCIPAL` if rank check requested but principal has no rank
+     * @throws AppError - `AUTH:PERMISSION_DENIED` if player doesn't meet requirements
+     *
+     * @example
+     * ```typescript
+     * // In a service or controller
+     * await this.principal.enforce(player, { rank: 5 })
+     * await this.principal.enforce(player, { permission: 'admin.ban' })
+     * await this.principal.enforce(player, { rank: 3, permission: 'mod.kick' })
+     * ```
+     */
+    abstract enforce(player: Player, requirements: GuardOptions): Promise<void>;
+}

package/dist/runtime/server/services/ports/principal.port.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrincipalPort = void 0;
+/**
+ * Core port that provides access to player authorization and permissions.
+ *
+ * @remarks
+ * This port defines a framework-owned boundary for querying permission-related data
+ * regardless of the current runtime mode (CORE, RESOURCE, etc.).
+ *
+ * Implementations of this port are responsible for resolving permission information
+ * from the authoritative source (local provider, remote core exports, etc.).
+ *
+ * **Mode Differences:**
+ * - **CORE/STANDALONE**: Uses the user-provided PrincipalProviderContract directly
+ * - **RESOURCE**: Delegates to CORE via exports
+ *
+ * **Usage:**
+ * ```typescript
+ * @injectable()
+ * class MyService {
+ *   constructor(private principal: PrincipalPort) {}
+ *
+ *   async canBan(player: Player): Promise<boolean> {
+ *     return await this.principal.hasPermission(player, 'admin.ban')
+ *   }
+ * }
+ * ```
+ */
+class PrincipalPort {
+}
+exports.PrincipalPort = PrincipalPort;

package/dist/runtime/server/services/rate-limiter.service.d.ts

@@ -0,0 +1,23 @@
+/**
+ * In-memory rate limiter used by security-related decorators.
+ *
+ * @remarks
+ * This service is intentionally simple and process-local.
+ * It is primarily used by {@link Throttle} to enforce per-player call limits.
+ */
+export declare class RateLimiterService {
+    private hits;
+    /**
+     * Checks whether a key is still within the rate limit window.
+     *
+     * @param key - Unique identifier for the caller/action.
+     * @param limit - Maximum number of calls allowed within the time window.
+     * @param windowMs - Sliding window size in milliseconds.
+     * @returns `true` if the call is allowed; `false` if the limit was exceeded.
+     */
+    checkLimit(key: string, limit: number, windowMs: number): boolean;
+    /**
+     * Best-effort cleanup to prevent unbounded memory growth.
+     */
+    private cleanup;
+}

package/dist/{server → runtime/server}/services/rate-limiter.service.js

@@ -8,10 +8,25 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RateLimiterService = void 0;
 const tsyringe_1 = require("tsyringe");
+/**
+ * In-memory rate limiter used by security-related decorators.
+ *
+ * @remarks
+ * This service is intentionally simple and process-local.
+ * It is primarily used by {@link Throttle} to enforce per-player call limits.
+ */
 let RateLimiterService = class RateLimiterService {
     constructor() {
         this.hits = new Map();
     }
+    /**
+     * Checks whether a key is still within the rate limit window.
+     *
+     * @param key - Unique identifier for the caller/action.
+     * @param limit - Maximum number of calls allowed within the time window.
+     * @param windowMs - Sliding window size in milliseconds.
+     * @returns `true` if the call is allowed; `false` if the limit was exceeded.
+     */
     checkLimit(key, limit, windowMs) {
         const now = Date.now();
         const timestamps = this.hits.get(key) || [];
@@ -25,6 +40,9 @@ let RateLimiterService = class RateLimiterService {
             this.cleanup();
         return true;
     }
+    /**
+     * Best-effort cleanup to prevent unbounded memory growth.
+     */
     cleanup() {
         const now = Date.now();
         for (const [key, times] of this.hits.entries()) {

package/dist/runtime/server/services/remote/remote-command.service.d.ts

@@ -0,0 +1,63 @@
+import { IExports } from '../../../../adapters/contracts/IExports';
+import { CommandMetadata } from '../../decorators/command';
+import { Player } from '../../entities';
+import { CommandExecutionPort, type CommandInfo } from '../ports/command-execution.port';
+/**
+ * Remote command service for RESOURCE mode.
+ *
+ * @remarks
+ * In RESOURCE mode, this service:
+ * - Stores command handlers and metadata locally in the resource
+ * - Registers command metadata with CORE via exports
+ * - Executes handlers when invoked by CORE via net event
+ * - Validates arguments using Zod schemas (same as CommandService)
+ *
+ * Flow:
+ * 1. Resource declares @Command → metadata registered with CORE
+ * 2. Player executes command → CORE validates security and emits event to resource
+ * 3. Resource receives event → validates schema → executes handler
+ *
+ * Security validation is split:
+ * - CORE validates: @Guard (rank/permission), @Throttle (rate limit), @RequiresState
+ * - RESOURCE validates: Zod schema (not serializable, must be local)
+ */
+export declare class RemoteCommandService extends CommandExecutionPort {
+    private exportsService;
+    private commands;
+    constructor(exportsService: IExports);
+    /**
+     * Gets typed access to CORE resource exports.
+     */
+    private get core();
+    /**
+     * Registers a command handler locally and with CORE.
+     *
+     * @remarks
+     * The handler and full metadata are stored locally for schema validation.
+     * Only serializable metadata is sent to CORE for security validation.
+     */
+    register(metadata: CommandMetadata, handler: Function): void;
+    /**
+     * Executes a command handler stored in this resource.
+     *
+     * @remarks
+     * Called by the resource's command execution controller when CORE
+     * emits a command execution event to this resource.
+     *
+     * CORE has already validated:
+     * - @Guard (rank/permission requirements)
+     * - @Throttle (rate limiting)
+     * - @RequiresState (player state)
+     * - @Public (authentication - if not public, player must be authenticated)
+     *
+     * This method validates:
+     * - Zod schema (argument types and structure)
+     *
+     * @throws AppError - If schema validation fails or command not found
+     */
+    execute(player: Player, commandName: string, args: string[]): Promise<void>;
+    /**
+     * Returns all commands registered in CORE (local + remote).
+     */
+    getAllCommands(): CommandInfo[];
+}