@open-core/identity 1.0.0

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

@@ -0,0 +1,28 @@
+import { Server } from "@open-core/framework";
+import { AccountService } from "../account.service";
+/**
+ * Local authentication provider that auto-creates accounts based on FiveM identifiers.
+ * This is the default/traditional authentication method for FiveM servers.
+ *
+ * Features:
+ * - Auto-creates accounts on first connection
+ * - Uses FiveM identifiers (license/discord/steam)
+ * - Stores accounts in local database
+ * - Generates UUID-based linkedId
+ */
+export declare class LocalAuthProvider implements Server.AuthProviderContract {
+    private readonly accounts;
+    private readonly config;
+    constructor(accounts: AccountService, config: Server.ConfigService);
+    /**
+     * Get the linked account ID (linkedId or numeric ID as fallback)
+     */
+    private getLinkedId;
+    authenticate(player: Server.Player, credentials: Record<string, unknown>): Promise<Server.AuthResult>;
+    register(player: Server.Player, credentials: Record<string, unknown>): Promise<Server.AuthResult>;
+    validateSession(player: Server.Player): Promise<Server.AuthResult>;
+    logout(player: Server.Player): Promise<void>;
+    private mergeIdentifiers;
+    private extractIdentifiers;
+    private extractFromPlayer;
+}

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

@@ -0,0 +1,135 @@
+"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.LocalAuthProvider = void 0;
+const tsyringe_1 = require("tsyringe");
+const framework_1 = require("@open-core/framework");
+const account_service_1 = require("../account.service");
+/**
+ * Local authentication provider that auto-creates accounts based on FiveM identifiers.
+ * This is the default/traditional authentication method for FiveM servers.
+ *
+ * Features:
+ * - Auto-creates accounts on first connection
+ * - Uses FiveM identifiers (license/discord/steam)
+ * - Stores accounts in local database
+ * - Generates UUID-based linkedId
+ */
+let LocalAuthProvider = class LocalAuthProvider {
+    constructor(accounts, config) {
+        this.accounts = accounts;
+        this.config = config;
+    }
+    /**
+     * Get the linked account ID (linkedId or numeric ID as fallback)
+     */
+    getLinkedId(account) {
+        return account.linkedId ?? String(account.id);
+    }
+    async authenticate(player, credentials) {
+        const identifiers = this.mergeIdentifiers(credentials, player);
+        const { account, isNew } = await this.accounts.findOrCreate(identifiers);
+        if (this.accounts.isBanExpired(account)) {
+            await this.accounts.unban(account.id);
+            account.banned = false;
+            account.banExpires = null;
+            account.banReason = null;
+        }
+        if (account.banned) {
+            return {
+                success: false,
+                error: account.banReason ?? "Account banned",
+                accountID: this.getLinkedId(account),
+            };
+        }
+        const linkedId = this.getLinkedId(account);
+        player.linkAccount(linkedId);
+        await this.accounts.touchLastLogin(account.id);
+        return {
+            success: true,
+            accountID: linkedId,
+            isNewAccount: isNew,
+        };
+    }
+    async register(player, credentials) {
+        // Registration flow is equivalent to authenticate with auto-create.
+        return this.authenticate(player, credentials);
+    }
+    async validateSession(player) {
+        const linked = player.accountID;
+        if (!linked) {
+            // Attempt implicit authentication using identifiers if auto-create is enabled.
+            const autoCreate = this.config.getBoolean("identity_auto_create", true);
+            if (!autoCreate) {
+                return { success: false, error: "Not authenticated" };
+            }
+            return this.authenticate(player, {});
+        }
+        const account = await this.accounts.findByLinkedId(String(linked));
+        if (!account) {
+            return { success: false, error: "Account not found", accountID: linked };
+        }
+        if (this.accounts.isBanExpired(account)) {
+            await this.accounts.unban(account.id);
+            account.banned = false;
+        }
+        if (account.banned) {
+            return {
+                success: false,
+                error: account.banReason ?? "Account banned",
+                accountID: this.getLinkedId(account),
+            };
+        }
+        return { success: true, accountID: this.getLinkedId(account) };
+    }
+    async logout(player) {
+        // The framework session holds the account binding; clearing meta is enough for now.
+        player.setMeta("identity:session", null);
+    }
+    mergeIdentifiers(credentials, player) {
+        const fromCredentials = this.extractIdentifiers(credentials);
+        const fromPlayer = this.extractFromPlayer(player);
+        return {
+            license: fromCredentials.license ?? fromPlayer.license ?? null,
+            discord: fromCredentials.discord ?? fromPlayer.discord ?? null,
+            steam: fromCredentials.steam ?? fromPlayer.steam ?? null,
+        };
+    }
+    extractIdentifiers(input) {
+        return {
+            license: typeof input.license === "string" ? input.license : null,
+            discord: typeof input.discord === "string" ? input.discord : null,
+            steam: typeof input.steam === "string" ? input.steam : null,
+        };
+    }
+    extractFromPlayer(player) {
+        const identifiers = player.getIdentifiers();
+        const result = {
+            license: null,
+            discord: null,
+            steam: null,
+        };
+        for (const raw of identifiers) {
+            if (raw.startsWith("license:"))
+                result.license = raw.slice("license:".length);
+            if (raw.startsWith("discord:"))
+                result.discord = raw.slice("discord:".length);
+            if (raw.startsWith("steam:"))
+                result.steam = raw.slice("steam:".length);
+        }
+        return result;
+    }
+};
+exports.LocalAuthProvider = LocalAuthProvider;
+exports.LocalAuthProvider = LocalAuthProvider = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [account_service_1.AccountService, framework_1.Server.ConfigService])
+], LocalAuthProvider);

package/dist/services/cache/memory-cache.service.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Simple in-memory cache with TTL support.
+ * Used to cache API responses and reduce external calls.
+ */
+export declare class MemoryCacheService {
+    private cache;
+    private cleanupInterval;
+    private readonly defaultTtlMs;
+    private readonly cleanupIntervalMs;
+    constructor();
+    /**
+     * Get a value from cache if it exists and hasn't expired
+     */
+    get<T>(key: string): T | null;
+    /**
+     * Set a value in cache with TTL
+     */
+    set<T>(key: string, value: T, ttlMs?: number): void;
+    /**
+     * Delete a specific key from cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Get current cache size
+     */
+    size(): number;
+    /**
+     * Check if a key exists in cache (and is not expired)
+     */
+    has(key: string): boolean;
+    /**
+     * Start automatic cleanup of expired entries
+     */
+    private startCleanup;
+    /**
+     * Clean up all expired entries
+     */
+    private cleanExpired;
+    /**
+     * Stop the cleanup interval (useful for testing or shutdown)
+     */
+    stopCleanup(): void;
+}

package/dist/services/cache/memory-cache.service.js

@@ -0,0 +1,108 @@
+"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.MemoryCacheService = void 0;
+const tsyringe_1 = require("tsyringe");
+/**
+ * Simple in-memory cache with TTL support.
+ * Used to cache API responses and reduce external calls.
+ */
+let MemoryCacheService = class MemoryCacheService {
+    constructor() {
+        this.cache = new Map();
+        this.cleanupInterval = null;
+        this.defaultTtlMs = 300000; // 5 minutes
+        this.cleanupIntervalMs = 60000; // 1 minute
+        this.startCleanup();
+    }
+    /**
+     * Get a value from cache if it exists and hasn't expired
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return null;
+        }
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    /**
+     * Set a value in cache with TTL
+     */
+    set(key, value, ttlMs) {
+        const expiresAt = Date.now() + (ttlMs ?? this.defaultTtlMs);
+        this.cache.set(key, { value, expiresAt });
+    }
+    /**
+     * Delete a specific key from cache
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all cache entries
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get current cache size
+     */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Check if a key exists in cache (and is not expired)
+     */
+    has(key) {
+        return this.get(key) !== null;
+    }
+    /**
+     * Start automatic cleanup of expired entries
+     */
+    startCleanup() {
+        this.cleanupInterval = setInterval(() => {
+            this.cleanExpired();
+        }, this.cleanupIntervalMs);
+    }
+    /**
+     * Clean up all expired entries
+     */
+    cleanExpired() {
+        const now = Date.now();
+        const keysToDelete = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (now > entry.expiresAt) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            this.cache.delete(key);
+        }
+    }
+    /**
+     * Stop the cleanup interval (useful for testing or shutdown)
+     */
+    stopCleanup() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+    }
+};
+exports.MemoryCacheService = MemoryCacheService;
+exports.MemoryCacheService = MemoryCacheService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [])
+], MemoryCacheService);

package/dist/services/identity-auth.provider.d.ts

@@ -0,0 +1,18 @@
+import { Server } from "@open-core/framework";
+import { AccountService } from "./account.service";
+export declare class IdentityAuthProvider implements Server.AuthProviderContract {
+    private readonly accounts;
+    private readonly config;
+    constructor(accounts: AccountService, config: Server.ConfigService);
+    /**
+     * Get the linked account ID (linkedId or numeric ID as fallback)
+     */
+    private getLinkedId;
+    authenticate(player: Server.Player, credentials: Record<string, unknown>): Promise<Server.AuthResult>;
+    register(player: Server.Player, credentials: Record<string, unknown>): Promise<Server.AuthResult>;
+    validateSession(player: Server.Player): Promise<Server.AuthResult>;
+    logout(player: Server.Player): Promise<void>;
+    private mergeIdentifiers;
+    private extractIdentifiers;
+    private extractFromPlayer;
+}

package/dist/services/identity-auth.provider.js

@@ -0,0 +1,125 @@
+"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.IdentityAuthProvider = void 0;
+const tsyringe_1 = require("tsyringe");
+const framework_1 = require("@open-core/framework");
+const account_service_1 = require("./account.service");
+let IdentityAuthProvider = class IdentityAuthProvider {
+    constructor(accounts, config) {
+        this.accounts = accounts;
+        this.config = config;
+    }
+    /**
+     * Get the linked account ID (linkedId or numeric ID as fallback)
+     */
+    getLinkedId(account) {
+        return account.linkedId ?? String(account.id);
+    }
+    async authenticate(player, credentials) {
+        const identifiers = this.mergeIdentifiers(credentials, player);
+        const { account, isNew } = await this.accounts.findOrCreate(identifiers);
+        if (this.accounts.isBanExpired(account)) {
+            await this.accounts.unban(account.id);
+            account.banned = false;
+            account.banExpires = null;
+            account.banReason = null;
+        }
+        if (account.banned) {
+            return {
+                success: false,
+                error: account.banReason ?? "Account banned",
+                accountID: this.getLinkedId(account),
+            };
+        }
+        const linkedId = this.getLinkedId(account);
+        player.linkAccount(linkedId);
+        await this.accounts.touchLastLogin(account.id);
+        return {
+            success: true,
+            accountID: linkedId,
+            isNewAccount: isNew,
+        };
+    }
+    async register(player, credentials) {
+        // Registration flow is equivalent to authenticate with auto-create.
+        return this.authenticate(player, credentials);
+    }
+    async validateSession(player) {
+        const linked = player.accountID;
+        if (!linked) {
+            // Attempt implicit authentication using identifiers if auto-create is enabled.
+            const autoCreate = this.config.getBoolean("identity_auto_create", true);
+            if (!autoCreate) {
+                return { success: false, error: "Not authenticated" };
+            }
+            return this.authenticate(player, {});
+        }
+        const account = await this.accounts.findByLinkedId(String(linked));
+        if (!account) {
+            return { success: false, error: "Account not found", accountID: linked };
+        }
+        if (this.accounts.isBanExpired(account)) {
+            await this.accounts.unban(account.id);
+            account.banned = false;
+        }
+        if (account.banned) {
+            return {
+                success: false,
+                error: account.banReason ?? "Account banned",
+                accountID: this.getLinkedId(account),
+            };
+        }
+        return { success: true, accountID: this.getLinkedId(account) };
+    }
+    async logout(player) {
+        // The framework session holds the account binding; clearing meta is enough for now.
+        player.setMeta("identity:session", null);
+    }
+    mergeIdentifiers(credentials, player) {
+        const fromCredentials = this.extractIdentifiers(credentials);
+        const fromPlayer = this.extractFromPlayer(player);
+        return {
+            license: fromCredentials.license ?? fromPlayer.license ?? null,
+            discord: fromCredentials.discord ?? fromPlayer.discord ?? null,
+            steam: fromCredentials.steam ?? fromPlayer.steam ?? null,
+        };
+    }
+    extractIdentifiers(input) {
+        return {
+            license: typeof input.license === "string" ? input.license : null,
+            discord: typeof input.discord === "string" ? input.discord : null,
+            steam: typeof input.steam === "string" ? input.steam : null,
+        };
+    }
+    extractFromPlayer(player) {
+        const identifiers = player.getIdentifiers();
+        const result = {
+            license: null,
+            discord: null,
+            steam: null,
+        };
+        for (const raw of identifiers) {
+            if (raw.startsWith("license:"))
+                result.license = raw.slice("license:".length);
+            if (raw.startsWith("discord:"))
+                result.discord = raw.slice("discord:".length);
+            if (raw.startsWith("steam:"))
+                result.steam = raw.slice("steam:".length);
+        }
+        return result;
+    }
+};
+exports.IdentityAuthProvider = IdentityAuthProvider;
+exports.IdentityAuthProvider = IdentityAuthProvider = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [account_service_1.AccountService, framework_1.Server.ConfigService])
+], IdentityAuthProvider);

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

@@ -0,0 +1,29 @@
+import { Server } from "@open-core/framework";
+import { AccountService } from "./account.service";
+import { AccountRepository } from "../repositories/account.repository";
+export declare class IdentityPrincipalProvider 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/identity-principal.provider.js

@@ -0,0 +1,104 @@
+"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.IdentityPrincipalProvider = 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");
+let IdentityPrincipalProvider = class IdentityPrincipalProvider {
+    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.IdentityPrincipalProvider = IdentityPrincipalProvider;
+exports.IdentityPrincipalProvider = IdentityPrincipalProvider = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [account_service_1.AccountService,
+        account_repository_1.AccountRepository])
+], IdentityPrincipalProvider);

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

@@ -0,0 +1,27 @@
+import { Server } from "@open-core/framework";
+import { MemoryCacheService } from "../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?: {...} }
+ */
+export declare class ApiPrincipalProvider implements Server.PrincipalProviderContract {
+    private readonly config;
+    private readonly http;
+    private readonly cache;
+    private apiConfig;
+    private cacheTtl;
+    constructor(config: Server.ConfigService, http: Server.HttpService, cache: MemoryCacheService);
+    getPrincipal(player: Server.Player): Promise<Server.Principal | null>;
+    refreshPrincipal(player: Server.Player): Promise<void>;
+    getPrincipalByLinkedID(linkedID: string): Promise<Server.Principal | null>;
+    private parseHeaders;
+}