@open-core/identity 1.0.0

package/dist/services/principal/api-principal.provider.js

@@ -0,0 +1,141 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiPrincipalProvider = void 0;
+const tsyringe_1 = require("tsyringe");
+const framework_1 = require("@open-core/framework");
+const memory_cache_service_1 = require("../cache/memory-cache.service");
+/**
+ * API-based principal provider that fetches permissions from external API.
+ * Does NOT require local database (uses memory cache only).
+ *
+ * Features:
+ * - GETs principal data from external API by linkedId
+ * - Caches results in RAM with configurable TTL
+ * - Falls back to empty permissions if API fails
+ * - Optionally syncs to local DB if configured
+ *
+ * Expected API endpoint: GET {principalUrl}/principals/{linkedId}
+ * Response: { name?: string, rank?: number, permissions: string[], meta?: {...} }
+ */
+let ApiPrincipalProvider = class ApiPrincipalProvider {
+    constructor(config, http, cache) {
+        this.config = config;
+        this.http = http;
+        this.cache = cache;
+        // Load API configuration from convars
+        const principalUrl = this.config.get("identity_api_principal_url", "") ||
+            this.config.get("identity_api_auth_url", "") ||
+            "http://localhost:3000/api";
+        this.apiConfig = {
+            authUrl: principalUrl,
+            principalUrl: principalUrl,
+            headers: this.parseHeaders(this.config.get("identity_api_headers", "")),
+            timeoutMs: this.config.getNumber("identity_api_timeout", 5000),
+        };
+        this.cacheTtl = this.config.getNumber("identity_cache_ttl", 300000); // 5 min default
+    }
+    async getPrincipal(player) {
+        const linked = player.accountID;
+        if (!linked) {
+            throw new framework_1.Utils.AppError("UNAUTHORIZED", "Player is not authenticated (no linked account)", "server");
+        }
+        // Check cache first
+        const cacheKey = `principal:${linked}`;
+        const cached = this.cache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        // Fetch from API
+        try {
+            const url = `${this.apiConfig.principalUrl}/principals/${linked}`;
+            const response = await this.http.get(url, {
+                headers: this.apiConfig.headers,
+                timeoutMs: this.apiConfig.timeoutMs,
+            });
+            const principal = {
+                id: String(linked),
+                name: response.name,
+                rank: response.rank,
+                permissions: response.permissions ?? [],
+                meta: response.meta ?? {},
+            };
+            // Cache the result
+            this.cache.set(cacheKey, principal, this.cacheTtl);
+            return principal;
+        }
+        catch (error) {
+            // If API fails, return empty principal or throw based on config
+            const allowFallback = this.config.getBoolean("identity_api_allow_fallback", false);
+            if (allowFallback) {
+                return {
+                    id: String(linked),
+                    permissions: [],
+                    meta: {},
+                };
+            }
+            throw new framework_1.Utils.AppError("UNAUTHORIZED", `Failed to fetch principal from API: ${error instanceof Error ? error.message : "Unknown error"}`, "server");
+        }
+    }
+    async refreshPrincipal(player) {
+        const linked = player.accountID;
+        if (linked) {
+            // Clear cache to force refresh
+            this.cache.delete(`principal:${linked}`);
+        }
+        const principal = await this.getPrincipal(player);
+        player.setMeta("identity:principal", principal);
+    }
+    async getPrincipalByLinkedID(linkedID) {
+        // Check cache first
+        const cacheKey = `principal:${linkedID}`;
+        const cached = this.cache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        // Fetch from API
+        try {
+            const url = `${this.apiConfig.principalUrl}/principals/${linkedID}`;
+            const response = await this.http.get(url, {
+                headers: this.apiConfig.headers,
+                timeoutMs: this.apiConfig.timeoutMs,
+            });
+            const principal = {
+                id: linkedID,
+                name: response.name,
+                rank: response.rank,
+                permissions: response.permissions ?? [],
+                meta: response.meta ?? {},
+            };
+            // Cache the result
+            this.cache.set(cacheKey, principal, this.cacheTtl);
+            return principal;
+        }
+        catch {
+            return null;
+        }
+    }
+    parseHeaders(headersString) {
+        if (!headersString)
+            return {};
+        try {
+            return JSON.parse(headersString);
+        }
+        catch {
+            return {};
+        }
+    }
+};
+exports.ApiPrincipalProvider = ApiPrincipalProvider;
+exports.ApiPrincipalProvider = ApiPrincipalProvider = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [framework_1.Server.ConfigService, framework_1.Server.HttpService, memory_cache_service_1.MemoryCacheService])
+], ApiPrincipalProvider);

package/dist/services/principal/local-principal.provider.d.ts

@@ -0,0 +1,39 @@
+import { Server } from "@open-core/framework";
+import { AccountService } from "../account.service";
+import { AccountRepository } from "../../repositories/account.repository";
+/**
+ * Local principal provider that reads roles and permissions from local database.
+ * This is the default/traditional principal provider for FiveM servers.
+ *
+ * Features:
+ * - Reads from local database (accounts + roles tables)
+ * - Combines role permissions with custom account permissions
+ * - Supports permission negation (e.g., "-admin.ban")
+ * - Caches in player metadata
+ */
+export declare class LocalPrincipalProvider implements Server.PrincipalProviderContract {
+    private readonly accounts;
+    private readonly repo;
+    constructor(accounts: AccountService, repo: AccountRepository);
+    getPrincipal(player: Server.Player): Promise<Server.Principal | null>;
+    refreshPrincipal(player: Server.Player): Promise<void>;
+    getPrincipalByLinkedID(linkedID: string): Promise<Server.Principal | null>;
+    /**
+     * Builds a Principal from account and role.
+     * Combines role permissions with account custom permissions.
+     *
+     * @param account - Account entity
+     * @param role - Role entity (or null if no role assigned)
+     * @returns Principal with combined permissions
+     */
+    private toPrincipal;
+    /**
+     * Combine role permissions with account custom permissions.
+     * Custom permissions starting with '-' negate the base permission.
+     *
+     * @param role - Role with base permissions
+     * @param customPerms - Account custom permissions
+     * @returns Combined permissions array
+     */
+    private combinePermissions;
+}

package/dist/services/principal/local-principal.provider.js

@@ -0,0 +1,114 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalPrincipalProvider = void 0;
+const tsyringe_1 = require("tsyringe");
+const framework_1 = require("@open-core/framework");
+const account_service_1 = require("../account.service");
+const account_repository_1 = require("../../repositories/account.repository");
+/**
+ * Local principal provider that reads roles and permissions from local database.
+ * This is the default/traditional principal provider for FiveM servers.
+ *
+ * Features:
+ * - Reads from local database (accounts + roles tables)
+ * - Combines role permissions with custom account permissions
+ * - Supports permission negation (e.g., "-admin.ban")
+ * - Caches in player metadata
+ */
+let LocalPrincipalProvider = class LocalPrincipalProvider {
+    constructor(accounts, repo) {
+        this.accounts = accounts;
+        this.repo = repo;
+    }
+    async getPrincipal(player) {
+        const linked = player.accountID;
+        if (!linked) {
+            throw new framework_1.Utils.AppError("UNAUTHORIZED", "Player is not authenticated (no linked account)", "server");
+        }
+        const result = await this.repo.findByLinkedIdWithRole(String(linked));
+        if (!result) {
+            throw new framework_1.Utils.AppError("UNAUTHORIZED", "Linked account not found", "server");
+        }
+        const { account, role } = result;
+        if (this.accounts.isBanExpired(account)) {
+            await this.accounts.unban(account.id);
+            account.banned = false;
+        }
+        if (account.banned) {
+            throw new framework_1.Utils.AppError("PERMISSION_DENIED", "Account is banned", "server", {
+                banReason: account.banReason,
+                banExpires: account.banExpires,
+            });
+        }
+        return this.toPrincipal(account, role);
+    }
+    async refreshPrincipal(player) {
+        const principal = await this.getPrincipal(player);
+        player.setMeta("identity:principal", principal);
+    }
+    async getPrincipalByLinkedID(linkedID) {
+        const result = await this.repo.findByLinkedIdWithRole(linkedID);
+        if (!result || result.account.banned)
+            return null;
+        return this.toPrincipal(result.account, result.role);
+    }
+    /**
+     * Builds a Principal from account and role.
+     * Combines role permissions with account custom permissions.
+     *
+     * @param account - Account entity
+     * @param role - Role entity (or null if no role assigned)
+     * @returns Principal with combined permissions
+     */
+    toPrincipal(account, role) {
+        const effectivePermissions = this.combinePermissions(role, account.customPermissions);
+        return {
+            id: account.linkedId ?? String(account.id),
+            name: role?.displayName ?? undefined,
+            rank: role?.rank ?? undefined,
+            permissions: effectivePermissions,
+            meta: {
+                accountId: account.id,
+                roleId: role?.id,
+                roleName: role?.name,
+            },
+        };
+    }
+    /**
+     * Combine role permissions with account custom permissions.
+     * Custom permissions starting with '-' negate the base permission.
+     *
+     * @param role - Role with base permissions
+     * @param customPerms - Account custom permissions
+     * @returns Combined permissions array
+     */
+    combinePermissions(role, customPerms) {
+        const base = new Set(role?.permissions ?? []);
+        for (const perm of customPerms) {
+            if (perm.startsWith("-")) {
+                // Negation: remove the base permission
+                base.delete(perm.slice(1));
+            }
+            else {
+                // Addition: add custom permission
+                base.add(perm);
+            }
+        }
+        return Array.from(base);
+    }
+};
+exports.LocalPrincipalProvider = LocalPrincipalProvider;
+exports.LocalPrincipalProvider = LocalPrincipalProvider = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [account_service_1.AccountService,
+        account_repository_1.AccountRepository])
+], LocalPrincipalProvider);

package/dist/services/role.service.d.ts

@@ -0,0 +1,73 @@
+import type { Role } from "../entities/role.entity";
+import type { CreateRoleInput, UpdateRoleInput } from "../types";
+import { RoleRepository } from "../repositories/role.repository";
+/**
+ * Service for managing roles and their permissions.
+ * Handles CRUD operations and permission management for roles.
+ */
+export declare class RoleService {
+    private readonly repo;
+    constructor(repo: RoleRepository);
+    /**
+     * Find a role by its ID.
+     *
+     * @param id - Role ID
+     * @returns The role or null if not found
+     */
+    findById(id: number): Promise<Role | null>;
+    /**
+     * Find a role by its internal name.
+     *
+     * @param name - Role name (e.g., 'admin', 'user')
+     * @returns The role or null if not found
+     */
+    findByName(name: string): Promise<Role | null>;
+    /**
+     * Get all roles.
+     *
+     * @returns Array of all roles
+     */
+    getAll(): Promise<Role[]>;
+    /**
+     * Get the default role for new accounts.
+     *
+     * @returns The default role or null if none is configured
+     */
+    getDefaultRole(): Promise<Role | null>;
+    /**
+     * Create a new role.
+     *
+     * @param input - Role creation data
+     * @returns The created role
+     */
+    create(input: CreateRoleInput): Promise<Role>;
+    /**
+     * Update an existing role.
+     *
+     * @param id - Role ID
+     * @param input - Update data
+     * @returns The updated role or null if not found
+     */
+    update(id: number, input: UpdateRoleInput): Promise<Role | null>;
+    /**
+     * Delete a role.
+     *
+     * @param id - Role ID
+     * @returns true if deleted, false if not found
+     */
+    delete(id: number): Promise<boolean>;
+    /**
+     * Add a permission to a role.
+     *
+     * @param roleId - Role ID
+     * @param permission - Permission string to add
+     */
+    addPermission(roleId: number, permission: string): Promise<void>;
+    /**
+     * Remove a permission from a role.
+     *
+     * @param roleId - Role ID
+     * @param permission - Permission string to remove
+     */
+    removePermission(roleId: number, permission: string): Promise<void>;
+}

package/dist/services/role.service.js

@@ -0,0 +1,145 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleService = void 0;
+const tsyringe_1 = require("tsyringe");
+const role_repository_1 = require("../repositories/role.repository");
+/**
+ * Service for managing roles and their permissions.
+ * Handles CRUD operations and permission management for roles.
+ */
+let RoleService = class RoleService {
+    constructor(repo) {
+        this.repo = repo;
+    }
+    /**
+     * Find a role by its ID.
+     *
+     * @param id - Role ID
+     * @returns The role or null if not found
+     */
+    async findById(id) {
+        return this.repo.findById(id);
+    }
+    /**
+     * Find a role by its internal name.
+     *
+     * @param name - Role name (e.g., 'admin', 'user')
+     * @returns The role or null if not found
+     */
+    async findByName(name) {
+        return this.repo.findByName(name);
+    }
+    /**
+     * Get all roles.
+     *
+     * @returns Array of all roles
+     */
+    async getAll() {
+        const result = await this.repo.findMany();
+        return result.data;
+    }
+    /**
+     * Get the default role for new accounts.
+     *
+     * @returns The default role or null if none is configured
+     */
+    async getDefaultRole() {
+        return this.repo.getDefaultRole();
+    }
+    /**
+     * Create a new role.
+     *
+     * @param input - Role creation data
+     * @returns The created role
+     */
+    async create(input) {
+        const now = new Date();
+        const role = {
+            id: 0, // Will be set by DB
+            name: input.name,
+            displayName: input.displayName,
+            rank: input.rank,
+            permissions: input.permissions ?? [],
+            isDefault: input.isDefault ?? false,
+            createdAt: now,
+        };
+        return this.repo.save(role);
+    }
+    /**
+     * Update an existing role.
+     *
+     * @param id - Role ID
+     * @param input - Update data
+     * @returns The updated role or null if not found
+     */
+    async update(id, input) {
+        const existing = await this.repo.findById(id);
+        if (!existing)
+            return null;
+        const updated = {
+            ...existing,
+            ...(input.displayName !== undefined && {
+                displayName: input.displayName,
+            }),
+            ...(input.rank !== undefined && { rank: input.rank }),
+            ...(input.permissions !== undefined && {
+                permissions: input.permissions,
+            }),
+        };
+        if (input.isDefault !== undefined) {
+            await this.repo.setDefault(id, input.isDefault);
+            updated.isDefault = input.isDefault;
+        }
+        return this.repo.save(updated);
+    }
+    /**
+     * Delete a role.
+     *
+     * @param id - Role ID
+     * @returns true if deleted, false if not found
+     */
+    async delete(id) {
+        return this.repo.delete(id);
+    }
+    /**
+     * Add a permission to a role.
+     *
+     * @param roleId - Role ID
+     * @param permission - Permission string to add
+     */
+    async addPermission(roleId, permission) {
+        const role = await this.repo.findById(roleId);
+        if (!role)
+            return;
+        const permissions = new Set(role.permissions);
+        permissions.add(permission);
+        await this.repo.updatePermissions(roleId, Array.from(permissions));
+    }
+    /**
+     * Remove a permission from a role.
+     *
+     * @param roleId - Role ID
+     * @param permission - Permission string to remove
+     */
+    async removePermission(roleId, permission) {
+        const role = await this.repo.findById(roleId);
+        if (!role)
+            return;
+        const filtered = role.permissions.filter((p) => p !== permission);
+        await this.repo.updatePermissions(roleId, filtered);
+    }
+};
+exports.RoleService = RoleService;
+exports.RoleService = RoleService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [role_repository_1.RoleRepository])
+], RoleService);

package/dist/setup.d.ts

@@ -0,0 +1,58 @@
+import type { DependencyContainer } from "tsyringe";
+/**
+ * Configuration options for Identity module setup
+ */
+export interface IdentitySetupOptions {
+    /**
+     * Authentication provider strategy
+     * - 'local': Auto-create accounts by FiveM identifiers (default)
+     * - 'credentials': Username/password authentication
+     * - 'api': External API authentication
+     */
+    authProvider?: "local" | "credentials" | "api";
+    /**
+     * Principal provider strategy
+     * - 'local': Read roles/permissions from local DB (default)
+     * - 'api': Fetch roles/permissions from external API
+     */
+    principalProvider?: "local" | "api";
+    /**
+     * Whether to use local database for accounts/roles
+     * - true: Use DB (default for 'local' strategies)
+     * - false: Skip DB registration (only cache, for 'api' strategies)
+     */
+    useDatabase?: boolean;
+}
+/**
+ * Register all Identity module singletons with the DI container.
+ *
+ * This function should be called once during server bootstrap to set up
+ * the authentication and authorization providers.
+ *
+ * @param container - The tsyringe DependencyContainer instance
+ * @param options - Configuration options for authentication and principal strategies
+ *
+ * @example
+ * ```ts
+ * import { container } from "tsyringe";
+ * import { Identity } from "@open-core/identity";
+ *
+ * // Default setup (local auth + local principals + DB)
+ * Identity.setup(container);
+ *
+ * // API-based setup (no DB required)
+ * Identity.setup(container, {
+ *   authProvider: 'api',
+ *   principalProvider: 'api',
+ *   useDatabase: false
+ * });
+ *
+ * // Credentials setup (DB required)
+ * Identity.setup(container, {
+ *   authProvider: 'credentials',
+ *   principalProvider: 'local',
+ *   useDatabase: true
+ * });
+ * ```
+ */
+export declare function setupIdentity(container: DependencyContainer, options?: IdentitySetupOptions): void;

package/dist/setup.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupIdentity = setupIdentity;
+const account_repository_1 = require("./repositories/account.repository");
+const role_repository_1 = require("./repositories/role.repository");
+const account_service_1 = require("./services/account.service");
+const role_service_1 = require("./services/role.service");
+const memory_cache_service_1 = require("./services/cache/memory-cache.service");
+const local_auth_provider_1 = require("./services/auth/local-auth.provider");
+const credentials_auth_provider_1 = require("./services/auth/credentials-auth.provider");
+const api_auth_provider_1 = require("./services/auth/api-auth.provider");
+const local_principal_provider_1 = require("./services/principal/local-principal.provider");
+const api_principal_provider_1 = require("./services/principal/api-principal.provider");
+const identity_auth_provider_1 = require("./services/identity-auth.provider");
+const identity_principal_provider_1 = require("./services/identity-principal.provider");
+/**
+ * Register all Identity module singletons with the DI container.
+ *
+ * This function should be called once during server bootstrap to set up
+ * the authentication and authorization providers.
+ *
+ * @param container - The tsyringe DependencyContainer instance
+ * @param options - Configuration options for authentication and principal strategies
+ *
+ * @example
+ * ```ts
+ * import { container } from "tsyringe";
+ * import { Identity } from "@open-core/identity";
+ *
+ * // Default setup (local auth + local principals + DB)
+ * Identity.setup(container);
+ *
+ * // API-based setup (no DB required)
+ * Identity.setup(container, {
+ *   authProvider: 'api',
+ *   principalProvider: 'api',
+ *   useDatabase: false
+ * });
+ *
+ * // Credentials setup (DB required)
+ * Identity.setup(container, {
+ *   authProvider: 'credentials',
+ *   principalProvider: 'local',
+ *   useDatabase: true
+ * });
+ * ```
+ */
+function setupIdentity(container, options = {}) {
+    const { authProvider = "local", principalProvider = "local", useDatabase = authProvider !== "api" && principalProvider !== "api", } = options;
+    // Always register cache service (needed for API providers)
+    container.registerSingleton(memory_cache_service_1.MemoryCacheService);
+    // Register database-dependent services only if needed
+    if (useDatabase) {
+        container.registerSingleton(account_repository_1.AccountRepository);
+        container.registerSingleton(role_repository_1.RoleRepository);
+        container.registerSingleton(account_service_1.AccountService);
+        container.registerSingleton(role_service_1.RoleService);
+    }
+    // Register Auth Provider based on strategy
+    switch (authProvider) {
+        case "credentials":
+            container.registerSingleton("AuthProviderContract", credentials_auth_provider_1.CredentialsAuthProvider);
+            // Also register as IdentityAuthProvider for backward compatibility
+            // Note: CredentialsAuthProvider is not compatible with IdentityAuthProvider interface
+            // Users should use the new provider directly
+            break;
+        case "api":
+            container.registerSingleton("AuthProviderContract", api_auth_provider_1.ApiAuthProvider);
+            // Note: ApiAuthProvider is not compatible with IdentityAuthProvider interface
+            // Users should use the new provider directly
+            break;
+        case "local":
+        default:
+            container.registerSingleton("AuthProviderContract", local_auth_provider_1.LocalAuthProvider);
+            // Register LocalAuthProvider as the legacy IdentityAuthProvider for compatibility
+            container.registerSingleton(identity_auth_provider_1.IdentityAuthProvider, local_auth_provider_1.LocalAuthProvider);
+            break;
+    }
+    // Register Principal Provider based on strategy
+    switch (principalProvider) {
+        case "api":
+            container.registerSingleton("PrincipalProviderContract", api_principal_provider_1.ApiPrincipalProvider);
+            // Note: ApiPrincipalProvider is not compatible with IdentityPrincipalProvider interface
+            // Users should use the new provider directly
+            break;
+        case "local":
+        default:
+            container.registerSingleton("PrincipalProviderContract", local_principal_provider_1.LocalPrincipalProvider);
+            // Register LocalPrincipalProvider as the legacy IdentityPrincipalProvider for compatibility
+            container.registerSingleton(identity_principal_provider_1.IdentityPrincipalProvider, local_principal_provider_1.LocalPrincipalProvider);
+            break;
+    }
+}