@open-core/framework 1.0.2-beta.1 → 1.0.5-beta.1

package/dist/runtime/server/implementations/remote/player.remote.js

@@ -0,0 +1,204 @@
+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); }
+};
+import { inject, injectable } from 'tsyringe';
+import { IExports, IPlayerInfo } from '../../../../adapters';
+import { IPlatformCapabilities } from '../../../../adapters/contracts/IPlatformCapabilities';
+import { EventsAPI } from '../../../../adapters/contracts/transport/events.api';
+import { IEntityServer } from '../../../../adapters/contracts/server/IEntityServer';
+import { IPlayerServer } from '../../../../adapters/contracts/server/IPlayerServer';
+import { loggers } from '../../../../kernel/logger';
+import { Player } from '../../entities';
+import { getRuntimeContext } from '../../runtime';
+import { Players } from '../../ports/players.api-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 RemotePlayerImplementation = class RemotePlayerImplementation extends Players {
+    playerInfo;
+    exportsService;
+    playerServer;
+    entityServer;
+    events;
+    platformCapabilities;
+    /**
+     * Cached adapters bundle for Player instances
+     */
+    playerAdapters;
+    constructor(playerInfo, exportsService, playerServer, entityServer, events, platformCapabilities) {
+        super();
+        this.playerInfo = playerInfo;
+        this.exportsService = exportsService;
+        this.playerServer = playerServer;
+        this.entityServer = entityServer;
+        this.events = events;
+        this.platformCapabilities = platformCapabilities;
+        const defaultSpawnModel = this.platformCapabilities.getConfig('defaultSpawnModel') ?? 'mp_m_freemode_01';
+        this.playerAdapters = {
+            playerInfo: this.playerInfo,
+            playerServer: this.playerServer,
+            entityServer: this.entityServer,
+            events: this.events,
+            defaultSpawnModel,
+        };
+    }
+    /**
+     * Gets typed access to CORE resource exports.
+     */
+    get core() {
+        const { coreResourceName } = 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 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) {
+            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 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)
+                loggers.exports.error(error.message, undefined, error);
+            else
+                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) {
+            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 [];
+        }
+    }
+    getAccountLinked(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 {
+            return undefined;
+        }
+    }
+    /**
+     * Gets the current player count from CORE.
+     */
+    getPlayerCount() {
+        try {
+            return this.core.getPlayerCount();
+        }
+        catch {
+            // 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 {
+            return false;
+        }
+    }
+};
+RemotePlayerImplementation = __decorate([
+    injectable(),
+    __param(0, inject(IPlayerInfo)),
+    __param(1, inject(IExports)),
+    __param(2, inject(IPlayerServer)),
+    __param(3, inject(IEntityServer)),
+    __param(4, inject(EventsAPI)),
+    __param(5, inject(IPlatformCapabilities)),
+    __metadata("design:paramtypes", [IPlayerInfo,
+        IExports,
+        IPlayerServer,
+        IEntityServer,
+        EventsAPI,
+        IPlatformCapabilities])
+], RemotePlayerImplementation);
+export { RemotePlayerImplementation };

package/dist/runtime/server/implementations/remote/principal.remote.d.ts

@@ -0,0 +1,33 @@
+import { IExports } from '../../../../adapters';
+import { Principal } from '../../types/principal.type';
+import { GuardOptions } from '../../decorators/guard';
+import { Player } from '../../entities';
+import { Authorization } from '../../ports/authorization.api-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 RemotePrincipalImplementation extends Authorization {
+    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>;
+}

package/dist/runtime/server/implementations/remote/principal.remote.js

@@ -0,0 +1,97 @@
+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); }
+};
+import { inject, injectable } from 'tsyringe';
+import { IExports } from '../../../../adapters';
+import { getRuntimeContext } from '../../runtime';
+import { Authorization } from '../../ports/authorization.api-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 RemotePrincipalImplementation = class RemotePrincipalImplementation extends Authorization {
+    exportsService;
+    constructor(exportsService) {
+        super();
+        this.exportsService = exportsService;
+    }
+    /**
+     * Gets typed access to CORE resource exports.
+     */
+    get core() {
+        const { coreResourceName } = 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);
+    }
+};
+RemotePrincipalImplementation = __decorate([
+    injectable(),
+    __param(0, inject(IExports)),
+    __metadata("design:paramtypes", [IExports])
+], RemotePrincipalImplementation);
+export { RemotePrincipalImplementation };

package/dist/runtime/server/index.d.ts

@@ -0,0 +1,9 @@
+export * from './api';
+export { Server, createServerRuntime } from './server.runtime';
+export type { ServerApi } from './server.runtime';
+export type { ServerPluginApi } from './library/plugin/server-plugin-api';
+export type { OpenCorePlugin, PluginInstallContext } from './library/plugin';
+export declare namespace Server {
+    type Player = import('./entities/player').Player;
+    type NPC = import('./entities/npc').NPC;
+}

package/dist/runtime/server/index.js

@@ -0,0 +1,4 @@
+import { GLOBAL_CONTAINER } from '../../kernel/di/container';
+globalThis.oc_container = GLOBAL_CONTAINER;
+export * from './api';
+export { Server, createServerRuntime } from './server.runtime';

package/dist/runtime/server/library/create-server-library.d.ts

@@ -0,0 +1,13 @@
+import { OpenCoreServerLibrary } from '../../core/library/types';
+/**
+ * Creates a server-side OpenCore library wrapper.
+ *
+ * @remarks
+ * - Internal events use the local in-memory library bus.
+ * - `emitExternal` emits a server-side cross-resource event using the exact
+ *   naming convention `opencore:<libName>:<eventName>` (or custom namespace).
+ * - This helper does not replace RPC for request/response flows.
+ */
+export declare function createServerLibrary(name: string, opts?: {
+    namespace?: string;
+}): OpenCoreServerLibrary;

package/dist/runtime/server/library/create-server-library.js

@@ -0,0 +1,48 @@
+import { coreLogger } from '../../../kernel/logger';
+import { buildLibraryEventId, createLibraryBase, createLibraryConfigAccessor, } from '../../core/library';
+import { emitLibraryEvent } from '../bus/library-event.bus';
+/**
+ * Creates a server-side OpenCore library wrapper.
+ *
+ * @remarks
+ * - Internal events use the local in-memory library bus.
+ * - `emitExternal` emits a server-side cross-resource event using the exact
+ *   naming convention `opencore:<libName>:<eventName>` (or custom namespace).
+ * - This helper does not replace RPC for request/response flows.
+ */
+export function createServerLibrary(name, opts) {
+    const base = createLibraryBase(name, opts);
+    const logger = coreLogger.server(`Library:${base.name}`);
+    const emitInternal = base.emit;
+    return {
+        ...base,
+        side: 'server',
+        emit(eventName, payload) {
+            emitInternal(eventName, payload);
+            const eventId = buildLibraryEventId(base.name, eventName);
+            const envelope = {
+                payload,
+                meta: {
+                    libraryName: base.name,
+                    eventName,
+                    eventId,
+                    namespace: base.namespace,
+                    side: 'server',
+                },
+            };
+            emitLibraryEvent(eventId, envelope);
+        },
+        emitExternal(eventName, payload) {
+            emit(base.buildEventName(eventName), payload);
+        },
+        emitNetExternal(eventName, target, payload) {
+            emitNet(base.buildEventName(eventName), target, payload);
+        },
+        getLogger() {
+            return logger;
+        },
+        getConfig() {
+            return createLibraryConfigAccessor(base.namespace);
+        },
+    };
+}

package/dist/runtime/server/library/index.d.ts

@@ -0,0 +1,4 @@
+export { createServerLibrary } from './create-server-library';
+export { buildLibraryEventId } from '../../core/library';
+export type { OpenCorePlugin, PluginInstallContext, ServerPluginApi, } from './plugin';
+export type { LibraryEventEnvelope, LibraryEventId, LibraryEventName, LibraryEventMetadata, LibraryName, LibraryNamespace, OpenCoreLibraryBase, OpenCoreLibraryConfigAccessor, OpenCoreServerLibrary, } from '../../core/library/types';

package/dist/runtime/server/library/index.js

@@ -0,0 +1,2 @@
+export { createServerLibrary } from './create-server-library';
+export { buildLibraryEventId } from '../../core/library';

package/dist/runtime/server/library/plugin/index.d.ts

@@ -0,0 +1,4 @@
+export * from './plugin-context';
+export * from './plugin.interface';
+export * from './plugin-registry';
+export * from './server-plugin-api';

package/dist/runtime/server/library/plugin/index.js

@@ -0,0 +1,4 @@
+export * from './plugin-context';
+export * from './plugin.interface';
+export * from './plugin-registry';
+export * from './server-plugin-api';

package/dist/runtime/server/library/plugin/plugin-context.d.ts

@@ -0,0 +1,10 @@
+import type { ServerApi } from '../../server.runtime';
+export interface PluginInstallContext {
+    readonly server: ServerApi;
+    readonly di: {
+        register(token: any, value: any): void;
+    };
+    readonly config: {
+        get<T = any>(key: string): T | undefined;
+    };
+}

package/dist/runtime/server/library/plugin/plugin-registry.d.ts

@@ -0,0 +1,7 @@
+import type { PluginInstallContext } from './plugin-context';
+import type { OpenCorePlugin } from './plugin.interface';
+export declare class PluginRegistry {
+    private readonly installed;
+    installAll(plugins: OpenCorePlugin[], ctx: PluginInstallContext): Promise<void>;
+    startAll(ctx: PluginInstallContext): Promise<void>;
+}

package/dist/runtime/server/library/plugin/plugin-registry.js

@@ -0,0 +1,25 @@
+export class PluginRegistry {
+    installed = new Map();
+    async installAll(plugins, ctx) {
+        for (const plugin of plugins) {
+            if (this.installed.has(plugin.name)) {
+                throw new Error(`Plugin "${plugin.name}" already installed`);
+            }
+            await plugin.install(ctx);
+            this.installed.set(plugin.name, plugin);
+        }
+    }
+    async startAll(ctx) {
+        for (const plugin of this.installed.values()) {
+            if (typeof plugin.start !== 'function')
+                continue;
+            try {
+                await plugin.start(ctx);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Plugin "${plugin.name}" failed to start: ${message}`);
+            }
+        }
+    }
+}

package/dist/runtime/server/library/plugin/plugin.interface.d.ts

@@ -0,0 +1,19 @@
+import type { PluginInstallContext } from './plugin-context';
+export interface OpenCorePlugin {
+    /**
+     * Unique plugin name.
+     */
+    readonly name: string;
+    /**
+     * Called during OpenCore.init().
+     */
+    install(ctx: PluginInstallContext): void | Promise<void>;
+    /**
+     * Called after platform capabilities and core services are ready.
+     *
+     * @remarks
+     * Use this hook for runtime-dependent initialization (DI resolutions that
+     * require platform adapters, starting timers, engine boot, etc).
+     */
+    start?(ctx: PluginInstallContext): void | Promise<void>;
+}

package/dist/runtime/server/library/plugin/server-plugin-api.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Empty interface for module augmentation.
+ */
+export interface ServerPluginApi {
+}

package/dist/runtime/server/ports/authorization.api-port.d.ts

@@ -0,0 +1,149 @@
+import { Principal } from '../types/principal.type';
+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 Authorization {
+    /**
+     * 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 - 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>;
+}