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

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

@@ -0,0 +1,99 @@
+"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.RemotePrincipalService = void 0;
+const tsyringe_1 = require("tsyringe");
+const adapters_1 = require("../../../../adapters");
+const runtime_1 = require("../../runtime");
+const principal_port_1 = require("../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.
+ */
+let RemotePrincipalService = class RemotePrincipalService extends principal_port_1.PrincipalPort {
+    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;
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Principal Queries
+    // ═══════════════════════════════════════════════════════════════
+    async getPrincipal(player) {
+        return await this.core.getPrincipal(player.clientID);
+    }
+    async getPrincipalByAccountId(accountId) {
+        return await this.core.getPrincipalByAccountId(accountId);
+    }
+    async refreshPrincipal(player) {
+        await this.core.refreshPrincipal(player.clientID);
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Quick Authorization Checks
+    // ═══════════════════════════════════════════════════════════════
+    async hasPermission(player, permission) {
+        return await this.core.hasPermission(player.clientID, permission);
+    }
+    async hasRank(player, requiredRank) {
+        return await this.core.hasRank(player.clientID, requiredRank);
+    }
+    async hasAnyPermission(player, permissions) {
+        return await this.core.hasAnyPermission(player.clientID, permissions);
+    }
+    async hasAllPermissions(player, permissions) {
+        return await this.core.hasAllPermissions(player.clientID, permissions);
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Property Getters
+    // ═══════════════════════════════════════════════════════════════
+    async getPermissions(player) {
+        return await this.core.getPermissions(player.clientID);
+    }
+    async getRank(player) {
+        return await this.core.getRank(player.clientID);
+    }
+    async getPrincipalName(player) {
+        return await this.core.getPrincipalName(player.clientID);
+    }
+    async getPrincipalMeta(player, key) {
+        return await this.core.getPrincipalMeta(player.clientID, key);
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Access Control Enforcement
+    // ═══════════════════════════════════════════════════════════════
+    async enforce(player, requirements) {
+        await this.core.enforce(player.clientID, requirements);
+    }
+};
+exports.RemotePrincipalService = RemotePrincipalService;
+exports.RemotePrincipalService = RemotePrincipalService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __param(0, (0, tsyringe_1.inject)(adapters_1.IExports)),
+    __metadata("design:paramtypes", [adapters_1.IExports])
+], RemotePrincipalService);

package/dist/runtime/server/services/remote/server-bridge.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Server bridge provides a unified interface to interact with player data
+ * regardless of whether the code is running in CORE mode or not.
+ * It automatically routes calls to the appropriate implementation.
+ */
+export declare const serverBridge: {
+    /**
+     * Gets the player ID for a given client ID
+     * @param clientID - The client ID to look up
+     * @returns The player ID if found, null otherwise
+     */
+    getPlayerId(clientID: number): string | undefined;
+    /**
+     * Retrieves metadata for a player
+     * @template T - The expected type of the metadata value
+     * @param clientID - The client ID of the player
+     * @param key - The metadata key to retrieve
+     * @returns A promise that resolves with the metadata value, or undefined if not found
+     */
+    getPlayerMeta<T = unknown>(clientID: number, key: string): Promise<T | undefined>;
+    /**
+     * Sets metadata for a player
+     * @param clientID - The client ID of the player
+     * @param key - The metadata key to set
+     * @param value - The value to store
+     */
+    setPlayerMeta(clientID: number, key: string, value: unknown): void;
+    /**
+     * Gets the principal (user identity) for a client
+     * @param clientID - The client ID to look up
+     * @returns A promise that resolves with the principal object, or null if not found
+     */
+    getPrincipal(clientID: number): Promise<any>;
+};

package/dist/runtime/server/services/remote/server-bridge.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverBridge = void 0;
+const container_1 = require("../../../../kernel/di/container");
+const contracts_1 = require("../../contracts");
+const core_1 = require("../../core");
+const runtime_1 = require("../../runtime");
+const player_directory_port_1 = require("../ports/player-directory.port");
+/**
+ * Server bridge provides a unified interface to interact with player data
+ * regardless of whether the code is running in CORE mode or not.
+ * It automatically routes calls to the appropriate implementation.
+ */
+exports.serverBridge = {
+    /**
+     * Gets the player ID for a given client ID
+     * @param clientID - The client ID to look up
+     * @returns The player ID if found, null otherwise
+     */
+    getPlayerId(clientID) {
+        if (core_1._mode !== 'RESOURCE') {
+            return getPlayerService().getPlayerId(clientID);
+        }
+        return getCoreExports().getPlayerId(clientID);
+    },
+    /**
+     * Retrieves metadata for a player
+     * @template T - The expected type of the metadata value
+     * @param clientID - The client ID of the player
+     * @param key - The metadata key to retrieve
+     * @returns A promise that resolves with the metadata value, or undefined if not found
+     */
+    async getPlayerMeta(clientID, key) {
+        if (core_1._mode !== 'RESOURCE') {
+            return getPlayerService().getMeta(clientID, key);
+        }
+        return getCoreExports().getPlayerMeta(clientID, key);
+    },
+    /**
+     * Sets metadata for a player
+     * @param clientID - The client ID of the player
+     * @param key - The metadata key to set
+     * @param value - The value to store
+     */
+    setPlayerMeta(clientID, key, value) {
+        if (core_1._mode !== 'RESOURCE') {
+            getPlayerService().setMeta(clientID, key, value);
+            return;
+        }
+        getCoreExports().setPlayerMeta(clientID, key, value);
+    },
+    /**
+     * Gets the principal (user identity) for a client
+     * @param clientID - The client ID to look up
+     * @returns A promise that resolves with the principal object, or null if not found
+     */
+    async getPrincipal(clientID) {
+        if (core_1._mode !== 'RESOURCE') {
+            const player = getPlayerService().getByClient(clientID);
+            if (!player)
+                return null;
+            return getPrincipalProvider().getPrincipal(player);
+        }
+        return getCoreExports().getPrincipal(clientID);
+    },
+};
+/**
+ * Gets the core exports interface from the global scope
+ * @returns The CoreExports interface implementation
+ * @throws Error if core exports are not available
+ */
+function getCoreExports() {
+    var _a;
+    const { coreResourceName } = (0, runtime_1.getRuntimeContext)();
+    const core = (_a = globalThis.exports) === null || _a === void 0 ? void 0 : _a[coreResourceName];
+    if (!core) {
+        throw new Error(`[OpenCore] Core exports are unavailable for resource '${coreResourceName}'. Is the core resource loaded?`);
+    }
+    return core;
+}
+/**
+ * Gets the player service from the dependency injection container
+ * @returns An instance of PlayerServiceContract
+ */
+function getPlayerService() {
+    return container_1.di.resolve(player_directory_port_1.PlayerDirectoryPort);
+}
+/**
+ * Gets the principal provider from the dependency injection container
+ * @returns An instance of PrincipalProviderContract
+ */
+function getPrincipalProvider() {
+    return container_1.di.resolve(contracts_1.PrincipalProviderContract);
+}

package/dist/runtime/server/services/services.register.d.ts

@@ -0,0 +1,14 @@
+import { RuntimeContext } from '../runtime';
+/**
+ * Registers server runtime services in the dependency injection container.
+ *
+ * @remarks
+ * This function enforces feature gating based on the runtime mode:
+ * - In `RESOURCE` mode, some features require explicit grants (`resourceGrants`).
+ * - Service bindings may resolve to local implementations (CORE mode) or remote proxies.
+ *
+ * @param ctx - Runtime context containing mode, feature flags, and optional resource grants.
+ *
+ * @throws Error - If a forbidden feature is enabled in `RESOURCE` mode without the corresponding grant.
+ */
+export declare function registerServicesServer(ctx: RuntimeContext): void;

package/dist/runtime/server/services/services.register.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerServicesServer = registerServicesServer;
+const index_1 = require("../../../kernel/di/index");
+const database_1 = require("../database");
+const chat_service_1 = require("./chat.service");
+const command_service_1 = require("./core/command.service");
+const player_service_1 = require("./core/player.service");
+const principal_service_1 = require("./core/principal.service");
+const http_service_1 = require("./http/http.service");
+const persistence_service_1 = require("./persistence.service");
+const player_session_lifecycle_port_1 = require("./ports/player-session-lifecycle.port");
+const player_directory_port_1 = require("./ports/player-directory.port");
+const principal_port_1 = require("./ports/principal.port");
+const remote_command_service_1 = require("./remote/remote-command.service");
+const remote_player_service_1 = require("./remote/remote-player.service");
+const remote_principal_service_1 = require("./remote/remote-principal.service");
+const command_execution_port_1 = require("./ports/command-execution.port");
+/**
+ * Registers server runtime services in the dependency injection container.
+ *
+ * @remarks
+ * This function enforces feature gating based on the runtime mode:
+ * - In `RESOURCE` mode, some features require explicit grants (`resourceGrants`).
+ * - Service bindings may resolve to local implementations (CORE mode) or remote proxies.
+ *
+ * @param ctx - Runtime context containing mode, feature flags, and optional resource grants.
+ *
+ * @throws Error - If a forbidden feature is enabled in `RESOURCE` mode without the corresponding grant.
+ */
+function registerServicesServer(ctx) {
+    const { mode, features, resourceGrants } = ctx;
+    if (mode === 'RESOURCE') {
+        if (features.database.enabled && !(resourceGrants === null || resourceGrants === void 0 ? void 0 : resourceGrants.database)) {
+            throw new Error(`[OpenCore] Feature 'database' is forbidden in RESOURCE mode unless resourceGrants.database=true`);
+        }
+        if (features.principal.enabled && !(resourceGrants === null || resourceGrants === void 0 ? void 0 : resourceGrants.principal)) {
+            throw new Error(`[OpenCore] Feature 'principal' is forbidden in RESOURCE mode unless resourceGrants.principal=true`);
+        }
+        if (features.auth.enabled && !(resourceGrants === null || resourceGrants === void 0 ? void 0 : resourceGrants.auth)) {
+            throw new Error(`[OpenCore] Feature 'auth' is forbidden in RESOURCE mode unless resourceGrants.auth=true`);
+        }
+    }
+    if (features.players.enabled) {
+        if (features.players.provider === 'local' || mode === 'CORE') {
+            index_1.di.registerSingleton(player_service_1.PlayerService);
+            index_1.di.register(player_directory_port_1.PlayerDirectoryPort, { useToken: player_service_1.PlayerService });
+            index_1.di.register(player_session_lifecycle_port_1.PlayerSessionLifecyclePort, { useToken: player_service_1.PlayerService });
+        }
+        else {
+            index_1.di.registerSingleton(player_directory_port_1.PlayerDirectoryPort, remote_player_service_1.RemotePlayerService);
+        }
+    }
+    if (mode === 'RESOURCE' && features.players.enabled) {
+        index_1.di.register(player_session_lifecycle_port_1.PlayerSessionLifecyclePort, {
+            useFactory: () => {
+                throw new Error('[OpenCore] PlayerSessionLifecyclePort is not available in RESOURCE mode');
+            },
+        });
+    }
+    if (features.sessionLifecycle.enabled && mode !== 'RESOURCE') {
+        index_1.di.registerSingleton(persistence_service_1.PlayerPersistenceService, persistence_service_1.PlayerPersistenceService);
+    }
+    if (features.principal.enabled) {
+        if (features.principal.provider === 'local' || mode === 'CORE' || mode === 'STANDALONE') {
+            // CORE/STANDALONE: Local principal service wraps user's PrincipalProviderContract
+            index_1.di.registerSingleton(principal_service_1.LocalPrincipalService);
+            index_1.di.register(principal_port_1.PrincipalPort, { useToken: principal_service_1.LocalPrincipalService });
+        }
+        else {
+            // RESOURCE: Remote principal service delegates to CORE
+            index_1.di.registerSingleton(principal_port_1.PrincipalPort, remote_principal_service_1.RemotePrincipalService);
+        }
+    }
+    if (features.auth.enabled && features.auth.provider === 'core' && mode === 'RESOURCE') {
+        throw new Error("[OpenCore] Feature 'auth' with provider='core' in RESOURCE mode is not implemented yet (missing RemoteAuthProvider).");
+    }
+    if (features.database.enabled) {
+        index_1.di.registerSingleton(database_1.DatabaseService);
+    }
+    if (features.commands.enabled) {
+        if (features.commands.provider === 'local' || mode === 'CORE') {
+            // CORE/STANDALONE: local command execution
+            index_1.di.registerSingleton(command_service_1.CommandService);
+            index_1.di.register(command_execution_port_1.CommandExecutionPort, { useToken: command_service_1.CommandService });
+        }
+        else {
+            // RESOURCE: remote command execution (delegates to CORE)
+            index_1.di.registerSingleton(command_execution_port_1.CommandExecutionPort, remote_command_service_1.RemoteCommandService);
+        }
+    }
+    if (features.http.enabled) {
+        index_1.di.registerSingleton(http_service_1.HttpService);
+    }
+    if (features.chat.enabled) {
+        index_1.di.registerSingleton(chat_service_1.ChatService);
+    }
+}

package/dist/runtime/server/services/types/linked-id.d.ts

@@ -0,0 +1,6 @@
+import { UUIDTypes } from 'uuid';
+/**
+ * Type representing a linked account identifier. This come from your persistence layer
+ * and is used to associate a Player session with their stored data.
+ */
+export type LinkedID = string | UUIDTypes | number;

package/dist/runtime/server/services/types/player-session.object.d.ts

@@ -0,0 +1,11 @@
+import { LinkedID } from './linked-id';
+export interface PlayerSession {
+    clientID: number;
+    accountID?: LinkedID;
+    identifiers?: {
+        license?: string;
+        steam?: string;
+        discord?: string;
+    };
+    meta: Record<string, unknown>;
+}

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

@@ -0,0 +1,94 @@
+import { VehicleModificationOptions, VehicleMods } from '../types/vehicle.types';
+import { VehicleService } from './vehicle.service';
+/**
+ * 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;
+}