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

package/dist/runtime/server/services/remote/remote-command.service.js

@@ -0,0 +1,139 @@
+"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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemoteCommandService = void 0;
+const tsyringe_1 = require("tsyringe");
+const IExports_1 = require("../../../../adapters/contracts/IExports");
+const logger_1 = require("../../../../kernel/shared/logger");
+const utils_1 = require("../../../../kernel/utils");
+const command_validation_helper_1 = require("../../helpers/command-validation.helper");
+const runtime_1 = require("../../runtime");
+const command_execution_port_1 = require("../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)
+ */
+let RemoteCommandService = class RemoteCommandService extends command_execution_port_1.CommandExecutionPort {
+    constructor(exportsService) {
+        super();
+        this.exportsService = exportsService;
+        this.commands = new Map();
+    }
+    /**
+     * Gets typed access to CORE resource exports.
+     */
+    get core() {
+        const { coreResourceName } = (0, runtime_1.getRuntimeContext)();
+        const coreExports = this.exportsService.getResource(coreResourceName);
+        if (!coreExports) {
+            throw new Error(`[OpenCore] CORE resource '${coreResourceName}' exports not found. ` +
+                `Ensure the CORE resource is started BEFORE RESOURCE mode resources. ` +
+                `Add 'ensure ${coreResourceName}' before this resource in server.cfg`);
+        }
+        return coreExports;
+    }
+    /**
+     * 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, handler) {
+        var _a, _b, _c, _d;
+        const commandKey = metadata.command.toLowerCase();
+        // Store handler with full metadata locally (for schema validation)
+        this.commands.set(commandKey, {
+            meta: metadata,
+            handler,
+        });
+        // Register metadata with CORE (security only, schema is not serializable)
+        this.core.registerCommand({
+            command: metadata.command,
+            description: metadata.description,
+            usage: metadata.usage,
+            isPublic: (_a = metadata.isPublic) !== null && _a !== void 0 ? _a : false,
+            resourceName: GetCurrentResourceName(),
+            security: metadata.security,
+        });
+        const publicFlag = metadata.isPublic ? ' [Public]' : '';
+        const schemaFlag = metadata.schema ? ' [Validated]' : '';
+        const securityFlags = [];
+        if ((_b = metadata.security) === null || _b === void 0 ? void 0 : _b.guard)
+            securityFlags.push('Guard');
+        if ((_c = metadata.security) === null || _c === void 0 ? void 0 : _c.throttle)
+            securityFlags.push('Throttle');
+        if ((_d = metadata.security) === null || _d === void 0 ? void 0 : _d.requiresState)
+            securityFlags.push('RequiresState');
+        const securityInfo = securityFlags.length > 0 ? ` (${securityFlags.join(', ')})` : '';
+        logger_1.loggers.command.debug(`Registered remote command: /${metadata.command}${publicFlag}${schemaFlag}${securityInfo} (delegated to CORE)`);
+    }
+    /**
+     * 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
+     */
+    async execute(player, commandName, args) {
+        const entry = this.commands.get(commandName.toLowerCase());
+        if (!entry) {
+            logger_1.loggers.command.error(`Handler not found for remote command: ${commandName}`, {
+                command: commandName,
+                resource: GetCurrentResourceName(),
+            });
+            throw new utils_1.AppError('COMMAND:NOT_FOUND', `Command not found: ${commandName}`, 'server');
+        }
+        const { meta, handler } = entry;
+        return await (0, command_validation_helper_1.validateAndExecuteCommand)(meta, player, args, handler);
+    }
+    /**
+     * Returns all commands registered in CORE (local + remote).
+     */
+    getAllCommands() {
+        return this.core.getAllCommands();
+    }
+};
+exports.RemoteCommandService = RemoteCommandService;
+exports.RemoteCommandService = RemoteCommandService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __param(0, (0, tsyringe_1.inject)(IExports_1.IExports)),
+    __metadata("design:paramtypes", [IExports_1.IExports])
+], RemoteCommandService);

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

@@ -0,0 +1,62 @@
+import { IExports, IPlayerInfo } from '../../../../adapters';
+import { IEntityServer } from '../../../../adapters/contracts/IEntityServer';
+import { INetTransport } from '../../../../adapters/contracts/INetTransport';
+import { IPlayerServer } from '../../../../adapters/contracts/IPlayerServer';
+import { Player } from '../../entities';
+import { PlayerDirectoryPort } from '../ports/player-directory.port';
+/**
+ * Player service implementation for `RESOURCE` mode.
+ *
+ * @remarks
+ * This service delegates all player operations to CORE via exports.
+ * It creates local Player instances hydrated with real session data from CORE,
+ * ensuring RESOURCE mode has access to accurate player information.
+ */
+export declare class RemotePlayerService extends PlayerDirectoryPort {
+    private readonly playerInfo;
+    private readonly exportsService;
+    private readonly playerServer;
+    private readonly entityServer;
+    private readonly netTransport;
+    /**
+     * Cached adapters bundle for Player instances
+     */
+    private readonly playerAdapters;
+    constructor(playerInfo: IPlayerInfo, exportsService: IExports, playerServer: IPlayerServer, entityServer: IEntityServer, netTransport: INetTransport);
+    /**
+     * Gets typed access to CORE resource exports.
+     */
+    private get core();
+    /**
+     * Creates a local Player instance from serialized data.
+     *
+     * @remarks
+     * The returned Player is hydrated with session data from CORE,
+     * including accountID, identifiers, metadata, and states.
+     */
+    private createPlayerFromData;
+    /**
+     * Returns a Player instance with real session data from CORE.
+     */
+    getByClient(clientID: number): Player | undefined;
+    getMany(clientIds: number[]): Player[];
+    /**
+     * Returns all connected players with real session data from CORE.
+     */
+    getAll(): Player[];
+    getPlayerId(clientID: number): string | undefined;
+    getMeta<T = unknown>(clientID: number, key: string): Promise<T | undefined>;
+    setMeta(clientID: number, key: string, value: unknown): void;
+    /**
+     * Finds a player by their persistent account ID.
+     */
+    getByAccountId(accountId: string): Player | undefined;
+    /**
+     * Gets the current player count from CORE.
+     */
+    getPlayerCount(): number;
+    /**
+     * Checks if a player with given account ID is online.
+     */
+    isOnline(accountId: string): boolean;
+}

package/dist/runtime/server/services/remote/remote-player.service.js

@@ -0,0 +1,191 @@
+"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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemotePlayerService = void 0;
+const tsyringe_1 = require("tsyringe");
+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");
+const runtime_1 = require("../../runtime");
+const player_directory_port_1 = require("../ports/player-directory.port");
+/**
+ * Player service implementation for `RESOURCE` mode.
+ *
+ * @remarks
+ * This service delegates all player operations to CORE via exports.
+ * It creates local Player instances hydrated with real session data from CORE,
+ * ensuring RESOURCE mode has access to accurate player information.
+ */
+let RemotePlayerService = class RemotePlayerService extends player_directory_port_1.PlayerDirectoryPort {
+    constructor(playerInfo, exportsService, playerServer, entityServer, netTransport) {
+        super();
+        this.playerInfo = playerInfo;
+        this.exportsService = exportsService;
+        this.playerServer = playerServer;
+        this.entityServer = entityServer;
+        this.netTransport = netTransport;
+        this.playerAdapters = {
+            playerInfo: this.playerInfo,
+            playerServer: this.playerServer,
+            entityServer: this.entityServer,
+            netTransport: this.netTransport,
+        };
+    }
+    /**
+     * Gets typed access to CORE resource exports.
+     */
+    get core() {
+        const { coreResourceName } = (0, runtime_1.getRuntimeContext)();
+        const coreExports = this.exportsService.getResource(coreResourceName);
+        if (!coreExports) {
+            throw new Error(`[OpenCore] CORE resource '${coreResourceName}' exports not found. ` +
+                `Ensure the CORE resource is started BEFORE RESOURCE mode resources.`);
+        }
+        return coreExports;
+    }
+    /**
+     * Creates a local Player instance from serialized data.
+     *
+     * @remarks
+     * The returned Player is hydrated with session data from CORE,
+     * including accountID, identifiers, metadata, and states.
+     */
+    createPlayerFromData(data) {
+        const player = new entities_1.Player({
+            clientID: data.clientID,
+            accountID: data.accountID,
+            identifiers: data.identifiers,
+            meta: data.meta,
+        }, this.playerAdapters);
+        // Restore state flags
+        for (const state of data.states) {
+            player.addState(state);
+        }
+        return player;
+    }
+    /**
+     * Returns a Player instance with real session data from CORE.
+     */
+    getByClient(clientID) {
+        try {
+            const data = this.core.getPlayerData(clientID);
+            if (!data)
+                return undefined;
+            return this.createPlayerFromData(data);
+        }
+        catch (error) {
+            logger_1.loggers.session.warn(`Failed to get player data from CORE`, {
+                clientID,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Fallback to basic player
+            return new entities_1.Player({ clientID, meta: {} }, this.playerAdapters);
+        }
+    }
+    getMany(clientIds) {
+        try {
+            const many = this.core.getManyData(clientIds);
+            return many.map((data) => this.createPlayerFromData(data));
+        }
+        catch (error) {
+            if (error instanceof Error)
+                logger_1.loggers.exports.error(error.message, undefined, error);
+            else
+                logger_1.loggers.exports.error('unknown error', undefined);
+            return [];
+        }
+    }
+    /**
+     * Returns all connected players with real session data from CORE.
+     */
+    getAll() {
+        try {
+            const allData = this.core.getAllPlayersData();
+            return allData.map((data) => this.createPlayerFromData(data));
+        }
+        catch (error) {
+            logger_1.loggers.session.warn(`Failed to get all players from CORE, using fallback`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // In RESOURCE mode fallback, return empty - we can't enumerate without CORE
+            return [];
+        }
+    }
+    getPlayerId(clientID) {
+        return this.core.getPlayerId(clientID);
+    }
+    async getMeta(clientID, key) {
+        return this.core.getPlayerMeta(clientID, key);
+    }
+    setMeta(clientID, key, value) {
+        this.core.setPlayerMeta(clientID, key, value);
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Extended methods (delegated to CORE)
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Finds a player by their persistent account ID.
+     */
+    getByAccountId(accountId) {
+        try {
+            const data = this.core.getPlayerByAccountId(accountId);
+            if (!data)
+                return undefined;
+            return this.createPlayerFromData(data);
+        }
+        catch (_a) {
+            return undefined;
+        }
+    }
+    /**
+     * Gets the current player count from CORE.
+     */
+    getPlayerCount() {
+        try {
+            return this.core.getPlayerCount();
+        }
+        catch (_a) {
+            // In RESOURCE mode, we can't enumerate without CORE
+            return 0;
+        }
+    }
+    /**
+     * Checks if a player with given account ID is online.
+     */
+    isOnline(accountId) {
+        try {
+            return this.core.isPlayerOnline(accountId);
+        }
+        catch (_a) {
+            return false;
+        }
+    }
+};
+exports.RemotePlayerService = RemotePlayerService;
+exports.RemotePlayerService = RemotePlayerService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __param(0, (0, tsyringe_1.inject)(adapters_1.IPlayerInfo)),
+    __param(1, (0, tsyringe_1.inject)(adapters_1.IExports)),
+    __param(2, (0, tsyringe_1.inject)(IPlayerServer_1.IPlayerServer)),
+    __param(3, (0, tsyringe_1.inject)(IEntityServer_1.IEntityServer)),
+    __param(4, (0, tsyringe_1.inject)(INetTransport_1.INetTransport)),
+    __metadata("design:paramtypes", [adapters_1.IPlayerInfo,
+        adapters_1.IExports,
+        IPlayerServer_1.IPlayerServer,
+        IEntityServer_1.IEntityServer,
+        INetTransport_1.INetTransport])
+], RemotePlayerService);

package/dist/runtime/server/services/remote/remote-principal.provider.d.ts

@@ -0,0 +1,55 @@
+import { Player } from '../../entities'
+import { Principal, PrincipalProviderContract } from '../../contracts'
+import { IExports } from '../../../../adapters'
+import type { LinkedID } from '../types/linked-id'
+/**
+ * Principal provider implementation for `RESOURCE` mode.
+ *
+ * @remarks
+ * This provider delegates all principal/permission operations to CORE via exports.
+ * It provides the full PrincipalProviderContract interface for RESOURCE mode.
+ */
+export declare class RemotePrincipalProvider extends PrincipalProviderContract {
+  private readonly exportsService
+  constructor(exportsService: IExports)
+  /**
+   * Gets typed access to CORE resource exports.
+   */
+  private get core()
+  /**
+   * Gets the Principal for a connected player.
+   */
+  getPrincipal(player: Player): Promise<Principal | null>
+  /**
+   * Forces a refresh of the player's permissions from persistence.
+   */
+  refreshPrincipal(player: Player): Promise<void>
+  /**
+   * Gets Principal by account ID (works for offline players too).
+   */
+  getPrincipalByLinkedID(linkedID: LinkedID): Promise<Principal | null>
+  /**
+   * Quick permission check without fetching full Principal.
+   */
+  hasPermission(clientID: number, permission: string): Promise<boolean>
+  /**
+   * Quick rank check without fetching full Principal.
+   */
+  hasRank(clientID: number, requiredRank: number): Promise<boolean>
+  /**
+   * Check if player has any of the specified permissions.
+   */
+  hasAnyPermission(clientID: number, permissions: string[]): Promise<boolean>
+  /**
+   * Check if player has all of the specified permissions.
+   */
+  hasAllPermissions(clientID: number, permissions: string[]): Promise<boolean>
+  /**
+   * Get all permissions for a player.
+   */
+  getPermissions(clientID: number): Promise<string[]>
+  /**
+   * Get the rank value for a player.
+   */
+  getRank(clientID: number): Promise<number | null>
+}

package/dist/runtime/server/services/remote/remote-principal.provider.js

@@ -0,0 +1,130 @@
+'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) ||
+  ((k, v) => {
+    if (typeof Reflect === 'object' && typeof Reflect.metadata === 'function')
+      return Reflect.metadata(k, v)
+  })
+var __param =
+  (this && this.__param) ||
+  ((paramIndex, decorator) => (target, key) => {
+    decorator(target, key, paramIndex)
+  })
+Object.defineProperty(exports, '__esModule', { value: true })
+exports.RemotePrincipalProvider = void 0
+const tsyringe_1 = require('tsyringe')
+const runtime_1 = require('../../runtime')
+const contracts_1 = require('../../contracts')
+const adapters_1 = require('../../../../adapters')
+/**
+ * Principal provider implementation for `RESOURCE` mode.
+ *
+ * @remarks
+ * This provider delegates all principal/permission operations to CORE via exports.
+ * It provides the full PrincipalProviderContract interface for RESOURCE mode.
+ */
+let RemotePrincipalProvider = class RemotePrincipalProvider extends contracts_1.PrincipalProviderContract {
+  constructor(exportsService) {
+    super()
+    this.exportsService = exportsService
+  }
+  /**
+   * Gets typed access to CORE resource exports.
+   */
+  get core() {
+    const { coreResourceName } = (0, runtime_1.getRuntimeContext)()
+    const coreExports = this.exportsService.getResource(coreResourceName)
+    if (!coreExports) {
+      throw new Error(
+        `[OpenCore] CORE resource '${coreResourceName}' exports not found. ` +
+          `Ensure the CORE resource is started BEFORE RESOURCE mode resources.`,
+      )
+    }
+    return coreExports
+  }
+  /**
+   * Gets the Principal for a connected player.
+   */
+  async getPrincipal(player) {
+    return await this.core.getPrincipal(player.clientID)
+  }
+  /**
+   * Forces a refresh of the player's permissions from persistence.
+   */
+  async refreshPrincipal(player) {
+    await this.core.refreshPrincipal(player.clientID)
+  }
+  /**
+   * Gets Principal by account ID (works for offline players too).
+   */
+  async getPrincipalByLinkedID(linkedID) {
+    return await this.core.getPrincipalByAccountId(linkedID.toString())
+  }
+  // ═══════════════════════════════════════════════════════════════
+  // Convenience methods (not part of contract, but useful)
+  // ═══════════════════════════════════════════════════════════════
+  /**
+   * Quick permission check without fetching full Principal.
+   */
+  async hasPermission(clientID, permission) {
+    return await this.core.hasPermission(clientID, permission)
+  }
+  /**
+   * Quick rank check without fetching full Principal.
+   */
+  async hasRank(clientID, requiredRank) {
+    return await this.core.hasRank(clientID, requiredRank)
+  }
+  /**
+   * Check if player has any of the specified permissions.
+   */
+  async hasAnyPermission(clientID, permissions) {
+    return await this.core.hasAnyPermission(clientID, permissions)
+  }
+  /**
+   * Check if player has all of the specified permissions.
+   */
+  async hasAllPermissions(clientID, permissions) {
+    return await this.core.hasAllPermissions(clientID, permissions)
+  }
+  /**
+   * Get all permissions for a player.
+   */
+  async getPermissions(clientID) {
+    return await this.core.getPermissions(clientID)
+  }
+  /**
+   * Get the rank value for a player.
+   */
+  async getRank(clientID) {
+    return await this.core.getRank(clientID)
+  }
+}
+exports.RemotePrincipalProvider = RemotePrincipalProvider
+exports.RemotePrincipalProvider = RemotePrincipalProvider = __decorate(
+  [
+    (0, tsyringe_1.injectable)(),
+    __param(0, (0, tsyringe_1.inject)(adapters_1.IExports)),
+    __metadata('design:paramtypes', [adapters_1.IExports]),
+  ],
+  RemotePrincipalProvider,
+)

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

@@ -0,0 +1,33 @@
+import { IExports } from '../../../../adapters';
+import { Principal } from '../../contracts/security/permission.types';
+import { GuardOptions } from '../../decorators/guard';
+import { Player } from '../../entities';
+import { PrincipalPort } from '../ports/principal.port';
+/**
+ * Principal service implementation for `RESOURCE` mode.
+ *
+ * @remarks
+ * This service delegates all principal/permission operations to CORE via exports.
+ * It provides the full PrincipalPort interface for RESOURCE mode, allowing
+ * transparent usage regardless of whether running in CORE or RESOURCE mode.
+ */
+export declare class RemotePrincipalService extends PrincipalPort {
+    private readonly exportsService;
+    constructor(exportsService: IExports);
+    /**
+     * Gets typed access to CORE resource exports.
+     */
+    private get core();
+    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>;
+}