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

package/dist/runtime/server/runtime.js

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRuntimeContextOrThrow = void 0;
+exports.setRuntimeContext = setRuntimeContext;
+exports.getRuntimeContext = getRuntimeContext;
+exports.getFrameworkModeScope = getFrameworkModeScope;
+exports.resolveRuntimeOptions = resolveRuntimeOptions;
+exports.validateRuntimeOptions = validateRuntimeOptions;
+const FEATURE_NAMES = [
+    'players',
+    'netEvents',
+    'fiveMEvents',
+    'commands',
+    'exports',
+    'http',
+    'chat',
+    'database',
+    'principal',
+    'auth',
+    'sessionLifecycle',
+];
+const FEATURE_ALLOWED_SCOPES = {
+    players: ['core', 'resource', 'standalone'],
+    netEvents: ['core', 'resource', 'standalone'],
+    fiveMEvents: ['core', 'resource', 'standalone'],
+    commands: ['core', 'resource', 'standalone'],
+    exports: ['core', 'resource', 'standalone'],
+    http: ['core', 'resource', 'standalone'],
+    chat: ['core', 'resource', 'standalone'],
+    database: ['core', 'resource', 'standalone'],
+    principal: ['core', 'resource', 'standalone'],
+    auth: ['core', 'resource', 'standalone'],
+    sessionLifecycle: ['core', 'standalone'],
+};
+let runtimeContext = null;
+function setRuntimeContext(ctx) {
+    runtimeContext = ctx;
+}
+function getRuntimeContext() {
+    if (!runtimeContext) {
+        throw new Error('[OpenCore] RuntimeContext is not initialized. Call Server.init({ mode, ... }) before using the framework.');
+    }
+    return runtimeContext;
+}
+function getFrameworkModeScope(mode) {
+    if (mode === 'CORE')
+        return 'core';
+    if (mode === 'RESOURCE')
+        return 'resource';
+    return 'standalone';
+}
+function createDefaultFeatures(mode) {
+    const scope = getFrameworkModeScope(mode);
+    // Provider logic:
+    // - CORE/STANDALONE: All features use 'local' (run locally)
+    // - RESOURCE: Some features delegate to CORE ('core'), others run locally ('local')
+    const playersProvider = mode === 'RESOURCE' ? 'core' : 'local';
+    const commandsProvider = mode === 'RESOURCE' ? 'core' : 'local';
+    const principalProvider = mode === 'RESOURCE' ? 'core' : 'local';
+    const authProvider = mode === 'RESOURCE' ? 'core' : 'local';
+    // These always use 'local' regardless of mode
+    const netEventsProvider = 'local';
+    const fiveMEventsProvider = 'local';
+    const exportsProvider = 'local';
+    const httpProvider = 'local';
+    const chatProvider = 'local';
+    const databaseProvider = 'local';
+    const sessionLifecycleProvider = 'local';
+    const sessionLifecycleEnabled = mode !== 'RESOURCE';
+    // Features that should auto-export in CORE mode for RESOURCE access
+    const commandsExport = mode === 'CORE';
+    const playersExport = mode === 'CORE';
+    const principalExport = mode === 'CORE';
+    return {
+        players: {
+            enabled: true,
+            provider: playersProvider,
+            export: playersExport,
+            scope,
+            required: false,
+        },
+        netEvents: {
+            enabled: true,
+            provider: netEventsProvider,
+            export: false,
+            scope,
+            required: false,
+        },
+        fiveMEvents: {
+            enabled: sessionLifecycleEnabled,
+            provider: fiveMEventsProvider,
+            export: false,
+            scope,
+            required: false,
+        },
+        commands: {
+            enabled: false,
+            provider: commandsProvider,
+            export: commandsExport,
+            scope,
+            required: false,
+        },
+        exports: { enabled: false, provider: exportsProvider, export: false, scope, required: false },
+        http: { enabled: false, provider: httpProvider, export: false, scope, required: false },
+        chat: { enabled: false, provider: chatProvider, export: false, scope, required: false },
+        database: { enabled: false, provider: databaseProvider, export: false, scope, required: false },
+        principal: {
+            enabled: false,
+            provider: principalProvider,
+            export: principalExport,
+            scope,
+            required: false,
+        },
+        auth: { enabled: false, provider: authProvider, export: false, scope, required: false },
+        sessionLifecycle: {
+            enabled: sessionLifecycleEnabled,
+            provider: sessionLifecycleProvider,
+            export: false,
+            scope,
+            required: false,
+        },
+    };
+}
+function resolveRuntimeOptions(options) {
+    var _a;
+    const defaults = createDefaultFeatures(options.mode);
+    const features = Object.assign({}, defaults);
+    if (options.features) {
+        for (const name of FEATURE_NAMES) {
+            const override = options.features[name];
+            if (!override)
+                continue;
+            features[name] = Object.assign(Object.assign({}, defaults[name]), override);
+        }
+    }
+    return {
+        mode: options.mode,
+        features,
+        coreResourceName: (_a = options.coreResourceName) !== null && _a !== void 0 ? _a : 'core',
+        resourceGrants: options.resourceGrants,
+        devMode: options.devMode,
+    };
+}
+function assertFeatureKeys(features) {
+    const keys = Object.keys(features);
+    for (const key of keys) {
+        if (!FEATURE_NAMES.includes(key)) {
+            throw new Error(`[OpenCore] Unknown feature: '${key}'`);
+        }
+    }
+}
+function validateRuntimeOptions(options) {
+    var _a;
+    const { mode, features } = options;
+    assertFeatureKeys(features);
+    // If in RESOURCE mode, must have coreResourceName
+    if (mode === 'RESOURCE' && !options.coreResourceName) {
+        throw new Error('[OpenCore] RESOURCE mode requires coreResourceName to be specified');
+    }
+    // Determine which features need CORE exports in RESOURCE mode
+    const needsCoreExports = mode === 'RESOURCE' &&
+        (features.players.provider === 'core' ||
+            features.commands.provider === 'core' ||
+            features.principal.provider === 'core' ||
+            features.auth.provider === 'core');
+    // Validate coreResourceName exists if needed
+    if (mode === 'RESOURCE') {
+        const { coreResourceName } = options;
+        if (needsCoreExports) {
+            const core = (_a = globalThis.exports) === null || _a === void 0 ? void 0 : _a[coreResourceName];
+            if (!core) {
+                throw new Error(`[OpenCore] CORE resource '${coreResourceName}' not found. Ensure it is started before RESOURCE mode resources.`);
+            }
+        }
+    }
+    const scope = getFrameworkModeScope(mode);
+    for (const name of FEATURE_NAMES) {
+        const f = features[name];
+        if (!f.enabled) {
+            if (f.required) {
+                throw new Error(`[OpenCore] Feature '${name}' is required but disabled`);
+            }
+            continue;
+        }
+        const allowedScopes = FEATURE_ALLOWED_SCOPES[name];
+        if (!allowedScopes.includes(scope)) {
+            throw new Error(`[OpenCore] Feature '${name}' is not allowed in scope '${scope}' (allowed: ${allowedScopes.join(', ')})`);
+        }
+        if (f.scope !== scope) {
+            throw new Error(`[OpenCore] Invalid scope for feature '${name}': expected '${scope}' for mode '${mode}', received '${f.scope}'`);
+        }
+        if (f.export && !features.exports.enabled) {
+            throw new Error(`[OpenCore] Feature '${name}' cannot be exported when 'exports' is disabled`);
+        }
+        // Validate provider combinations
+        if (mode === 'CORE' && f.provider === 'core') {
+            throw new Error(`[OpenCore] Feature '${name}' cannot use provider='core' in CORE mode (use 'local' instead)`);
+        }
+        if (mode === 'RESOURCE' && f.provider === 'core' && f.export) {
+            throw new Error(`[OpenCore] Feature '${name}' cannot set export=true when provider='core' in RESOURCE mode`);
+        }
+    }
+    // Feature-specific validations
+    if (features.players.enabled && mode === 'RESOURCE' && features.players.provider !== 'core') {
+        throw new Error(`[OpenCore] Feature 'players' must use provider 'core' in RESOURCE mode`);
+    }
+    if (features.principal.enabled && mode === 'RESOURCE' && features.principal.provider !== 'core') {
+        throw new Error(`[OpenCore] Feature 'principal' must use provider 'core' in RESOURCE mode`);
+    }
+    if (features.auth.enabled && mode === 'RESOURCE' && features.auth.provider !== 'core') {
+        throw new Error(`[OpenCore] Feature 'auth' must use provider 'core' in RESOURCE mode`);
+    }
+    if (features.commands.enabled && mode === 'RESOURCE' && features.commands.provider !== 'core') {
+        throw new Error(`[OpenCore] Feature 'commands' must use provider 'core' in RESOURCE mode`);
+    }
+    // Commands export validation
+    if (features.commands.export && mode !== 'CORE') {
+        throw new Error(`[OpenCore] Feature 'commands' can only be exported in CORE mode (current mode: '${mode}')`);
+    }
+    // Validate dependencies
+    if (features.commands.enabled && !features.players.enabled) {
+        throw new Error(`[OpenCore] Feature 'commands' requires 'players' to be enabled`);
+    }
+    if (features.netEvents.enabled && !features.players.enabled) {
+        throw new Error(`[OpenCore] Feature 'netEvents' requires 'players' to be enabled`);
+    }
+    if (features.chat.enabled && !features.players.enabled) {
+        throw new Error(`[OpenCore] Feature 'chat' requires 'players' to be enabled`);
+    }
+}
+/**
+ * @deprecated Use validateRuntimeOptions instead
+ */
+exports.validateRuntimeContextOrThrow = validateRuntimeOptions;

package/dist/runtime/server/services/access-control.service.d.ts

@@ -0,0 +1,59 @@
+import { Server } from '../../..'
+import { PrincipalProviderContract } from '../contracts'
+/**
+ * **Core Security Service**
+ *
+ * This service acts as the central enforcement point for the Access Control system.
+ * It uses the configured `PrincipalProvider` to query roles and validates them against requirements.
+ *
+ * It is primarily used internally by the `@Guard` decorator, but can be injected
+ * into services to perform manual checks.
+ */
+export declare class AccessControlService {
+  private readonly principalProvider
+  constructor(principalProvider: PrincipalProviderContract)
+  /**
+   * Verifies if a player meets a minimum numeric rank requirement.
+   *
+   * @param player - The target player.
+   * @param minRank - The minimum numeric value required (Inclusive).
+   *
+   * @returns `true` if `Principal.rank >= minRank`.
+   *
+   * @throws {AppError} code `UNAUTHORIZED` if the player has no Principal (not logged in).
+   * @throws {AppError} code `NO_RANK_IN_PRINCIPAL` if the Principal exists but has no `rank` defined.
+   */
+  hasRank(player: Server.Player, minRank: number): Promise<boolean>
+  /**
+   * Verifies if a player possesses a specific permission string.
+   *
+   * @remarks
+   * This method supports the **Wildcard ('*')** permission. If the principal has `'*'`
+   * in their permissions array, this method always returns `true`.
+   *
+   * @param player - The target player.
+   * @param permission - The specific permission key (e.g., `'admin.ban'`).
+   * @returns `true` if the player has the permission or the wildcard.
+   */
+  hasPermission(player: Server.Player, permission: string): Promise<boolean>
+  /**
+   * **Strict Enforcement**
+   *
+   * Validates a set of requirements against a player. If any requirement fails,
+   * it throws an exception, halting the execution flow.
+   *
+   * Used primarily by the `@Guard` decorator logic.
+   *
+   * @param player - The server player to validate.
+   * @param requirements - An object containing rank and/or permission constraints.
+   *
+   * @throws {AppError} code `PERMISSION_DENIED` if validation fails.
+   */
+  enforce(
+    player: Server.Player,
+    requirements: {
+      minRank?: number
+      permission?: string
+    },
+  ): Promise<void>
+}

package/dist/runtime/server/services/access-control.service.js

@@ -0,0 +1,127 @@
+'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)
+  })
+Object.defineProperty(exports, '__esModule', { value: true })
+exports.AccessControlService = void 0
+const tsyringe_1 = require('tsyringe')
+const utils_1 = require('../../../kernel/utils')
+const contracts_1 = require('../contracts')
+/**
+ * **Core Security Service**
+ *
+ * This service acts as the central enforcement point for the Access Control system.
+ * It uses the configured `PrincipalProvider` to query roles and validates them against requirements.
+ *
+ * It is primarily used internally by the `@Guard` decorator, but can be injected
+ * into services to perform manual checks.
+ */
+let AccessControlService = class AccessControlService {
+  constructor(principalProvider) {
+    this.principalProvider = principalProvider
+  }
+  /**
+   * Verifies if a player meets a minimum numeric rank requirement.
+   *
+   * @param player - The target player.
+   * @param minRank - The minimum numeric value required (Inclusive).
+   *
+   * @returns `true` if `Principal.rank >= minRank`.
+   *
+   * @throws {AppError} code `UNAUTHORIZED` if the player has no Principal (not logged in).
+   * @throws {AppError} code `NO_RANK_IN_PRINCIPAL` if the Principal exists but has no `rank` defined.
+   */
+  async hasRank(player, minRank) {
+    const principal = await this.principalProvider.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',
+      )
+    return principal.rank >= minRank
+  }
+  /**
+   * Verifies if a player possesses a specific permission string.
+   *
+   * @remarks
+   * This method supports the **Wildcard ('*')** permission. If the principal has `'*'`
+   * in their permissions array, this method always returns `true`.
+   *
+   * @param player - The target player.
+   * @param permission - The specific permission key (e.g., `'admin.ban'`).
+   * @returns `true` if the player has the permission or the wildcard.
+   */
+  async hasPermission(player, permission) {
+    const principal = await this.principalProvider.getPrincipal(player)
+    if (!principal) return false
+    if (principal.permissions.includes('*')) return true
+    return principal.permissions.includes(permission)
+  }
+  /**
+   * **Strict Enforcement**
+   *
+   * Validates a set of requirements against a player. If any requirement fails,
+   * it throws an exception, halting the execution flow.
+   *
+   * Used primarily by the `@Guard` decorator logic.
+   *
+   * @param player - The server player to validate.
+   * @param requirements - An object containing rank and/or permission constraints.
+   *
+   * @throws {AppError} code `PERMISSION_DENIED` if validation fails.
+   */
+  async enforce(player, requirements) {
+    if (requirements.minRank !== undefined) {
+      const hasRank = await this.hasRank(player, requirements.minRank)
+      if (!hasRank) {
+        throw new utils_1.AppError(
+          'AUTH:PERMISSION_DENIED',
+          `Access Denied: Requires minimum rank level ${requirements.minRank}`,
+          '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.AccessControlService = AccessControlService
+exports.AccessControlService = AccessControlService = __decorate(
+  [
+    (0, tsyringe_1.injectable)(),
+    __metadata('design:paramtypes', [contracts_1.PrincipalProviderContract]),
+  ],
+  AccessControlService,
+)

package/dist/runtime/server/services/appearance.service.d.ts

@@ -0,0 +1,99 @@
+import { INetTransport } from '../../../adapters/contracts/INetTransport';
+import { IPedAppearanceServer } from '../../../adapters/contracts/IPedAppearanceServer';
+import { IPlayerServer } from '../../../adapters/contracts/IPlayerServer';
+import { AppearanceValidationResult, PlayerAppearance } from '../../../kernel/shared';
+/**
+ * Server-side appearance management service.
+ *
+ * @remarks
+ * Handles validating and applying ped appearance data on the server.
+ * Provides security validation and server-authoritative appearance control.
+ *
+ * **Security Model:**
+ * - All appearance changes should be validated server-side
+ * - Server applies components/props directly (available natives)
+ * - Server emits events to client for client-only natives (headBlend, overlays, tattoos)
+ * - Client never sends appearance data directly to other clients
+ *
+ * **Persistence:**
+ * The framework does NOT handle persistence internally.
+ * After calling `applyAppearance`, you receive the validated data back.
+ * You decide when and where to save it (database, file, etc.).
+ *
+ * @example
+ * ```typescript
+ * // Apply appearance to a player
+ * const result = await appearanceService.applyAppearance(playerSrc, appearanceData)
+ * if (result.success) {
+ *   // Save to your database
+ *   await myDatabase.saveAppearance(playerId, result.appearance)
+ * }
+ *
+ * // Validate appearance without applying
+ * const validation = appearanceService.validateAppearance(appearanceData)
+ * if (!validation.valid) {
+ *   console.log('Errors:', validation.errors)
+ * }
+ * ```
+ */
+export declare class AppearanceService {
+    private readonly pedAdapter;
+    private readonly playerServer;
+    private readonly netTransport;
+    constructor(pedAdapter: IPedAppearanceServer, playerServer: IPlayerServer, netTransport: INetTransport);
+    /**
+     * Applies validated appearance to a player.
+     *
+     * @remarks
+     * This method:
+     * 1. Validates the appearance data
+     * 2. Applies server-side natives (components, props)
+     * 3. Emits event to client for client-only natives
+     * 4. Returns the validated appearance for persistence
+     *
+     * @param playerSrc - Player source/client ID
+     * @param appearance - Appearance data to apply
+     * @returns Result with success status and validated appearance
+     */
+    applyAppearance(playerSrc: string, appearance: PlayerAppearance): Promise<{
+        success: boolean;
+        appearance?: PlayerAppearance;
+        errors?: string[];
+    }>;
+    /**
+     * Applies only components and props (server-side available natives).
+     *
+     * @remarks
+     * Use this for quick clothing changes without full appearance update.
+     *
+     * @param playerSrc - Player source/client ID
+     * @param appearance - Partial appearance with components/props only
+     * @returns Success status
+     */
+    applyClothing(playerSrc: string, appearance: Pick<PlayerAppearance, 'components' | 'props'>): boolean;
+    /**
+     * Resets a player's appearance to default.
+     *
+     * @param playerSrc - Player source/client ID
+     * @returns Success status
+     */
+    resetAppearance(playerSrc: string): boolean;
+    /**
+     * Validates appearance data without applying it.
+     *
+     * @remarks
+     * Use this to validate appearance data before storing or applying.
+     * All validation rules are enforced to prevent invalid/malicious data.
+     *
+     * @param appearance - Appearance data to validate
+     * @returns Validation result with errors if any
+     */
+    validateAppearance(appearance: Partial<PlayerAppearance>): AppearanceValidationResult;
+    /**
+     * Applies server-side appearance natives (components and props only).
+     *
+     * @param ped - Ped entity handle
+     * @param appearance - Appearance data
+     */
+    private applyServerSideAppearance;
+}