@open-core/identity 1.2.0 → 1.2.2

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

@@ -1,73 +1,52 @@
-import type { Role } from "../entities/role.entity";
-import type { CreateRoleInput, UpdateRoleInput } from "../types";
-import { RoleRepository } from "../repositories/role.repository";
+import { RoleStore } from "../contracts";
+import type { IdentityOptions, IdentityRole } from "../types";
 /**
- * Service for managing roles and their permissions.
- * Handles CRUD operations and permission management for roles.
+ * High-level service for managing security roles and their associated permissions.
+ *
+ * Provides a programmer-friendly API for role administration, including creation,
+ * updates, and permission retrieval. This service interacts with the configured
+ * {@link RoleStore}.
+ *
+ * @public
+ * @injectable
  */
 export declare class RoleService {
-    private readonly repo;
-    constructor(repo: RoleRepository);
+    private readonly store;
+    private readonly options;
     /**
-     * Find a role by its ID.
+     * Initializes a new instance of the RoleService.
      *
-     * @param id - Role ID
-     * @returns The role or null if not found
+     * @param store - Persistence layer for role definitions.
+     * @param options - Identity system configuration options.
      */
-    findById(id: number): Promise<Role | null>;
+    constructor(store: RoleStore, options: IdentityOptions);
     /**
-     * Find a role by its internal name.
+     * Persists a new security role definition.
      *
-     * @param name - Role name (e.g., 'admin', 'user')
-     * @returns The role or null if not found
+     * @param role - The complete role definition to create.
+     * @returns A promise that resolves when the role is saved.
      */
-    findByName(name: string): Promise<Role | null>;
+    create(role: IdentityRole): Promise<void>;
     /**
-     * Get all roles.
+     * Updates an existing role's rank or permissions.
      *
-     * @returns Array of all roles
+     * @param name - The unique technical name of the role to update.
+     * @param data - Partial object containing the fields to modify.
+     * @returns A promise that resolves when the update is complete.
      */
-    getAll(): Promise<Role[]>;
+    update(name: string, data: Partial<Omit<IdentityRole, "name">>): Promise<void>;
     /**
-     * Get the default role for new accounts.
+     * Permanently removes a role definition from the system.
      *
-     * @returns The default role or null if none is configured
+     * @param name - The technical name of the role to delete.
+     * @returns A promise that resolves when the role is deleted.
      */
-    getDefaultRole(): Promise<Role | null>;
+    delete(name: string): Promise<void>;
     /**
-     * Create a new role.
+     * Retrieves the full list of permissions granted to a specific role.
      *
-     * @param input - Role creation data
-     * @returns The created role
+     * @param name - The technical name of the role.
+     * @returns A promise resolving to an array of permission strings.
      */
-    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>;
+    getPermissions(name: string): Promise<string[]>;
 }

package/dist/services/role.service.js

@@ -7,136 +7,81 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { injectable } from "tsyringe";
-import { RoleRepository } from "../repositories/role.repository";
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject } from "tsyringe";
+import { IDENTITY_OPTIONS } from "../tokens";
+import { RoleStore } from "../contracts";
 /**
- * Service for managing roles and their permissions.
- * Handles CRUD operations and permission management for roles.
+ * High-level service for managing security roles and their associated permissions.
+ *
+ * Provides a programmer-friendly API for role administration, including creation,
+ * updates, and permission retrieval. This service interacts with the configured
+ * {@link RoleStore}.
+ *
+ * @public
+ * @injectable
  */
 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.
+     * Initializes a new instance of the RoleService.
      *
-     * @param name - Role name (e.g., 'admin', 'user')
-     * @returns The role or null if not found
+     * @param store - Persistence layer for role definitions.
+     * @param options - Identity system configuration options.
      */
-    async findByName(name) {
-        return this.repo.findByName(name);
+    constructor(store, options) {
+        this.store = store;
+        this.options = options;
     }
     /**
-     * Get all roles.
+     * Persists a new security role definition.
      *
-     * @returns Array of all roles
+     * @param role - The complete role definition to create.
+     * @returns A promise that resolves when the role is saved.
      */
-    async getAll() {
-        const result = await this.repo.findMany();
-        return result.data;
+    async create(role) {
+        await this.store.save(role);
     }
     /**
-     * Get the default role for new accounts.
+     * Updates an existing role's rank or permissions.
      *
-     * @returns The default role or null if none is configured
+     * @param name - The unique technical name of the role to update.
+     * @param data - Partial object containing the fields to modify.
+     * @returns A promise that resolves when the update is complete.
      */
-    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);
+    async update(name, data) {
+        const existing = await this.store.findByName(name);
         if (!existing)
-            return null;
-        const updated = {
+            return;
+        await this.store.save({
             ...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);
+            ...data,
+        });
     }
     /**
-     * Add a permission to a role.
+     * Permanently removes a role definition from the system.
      *
-     * @param roleId - Role ID
-     * @param permission - Permission string to add
+     * @param name - The technical name of the role to delete.
+     * @returns A promise that resolves when the role is deleted.
      */
-    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));
+    async delete(name) {
+        await this.store.delete(name);
     }
     /**
-     * Remove a permission from a role.
+     * Retrieves the full list of permissions granted to a specific role.
      *
-     * @param roleId - Role ID
-     * @param permission - Permission string to remove
+     * @param name - The technical name of the role.
+     * @returns A promise resolving to an array of permission strings.
      */
-    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);
+    async getPermissions(name) {
+        const role = await this.store.findByName(name);
+        return role?.permissions || [];
     }
 };
 RoleService = __decorate([
     injectable(),
-    __metadata("design:paramtypes", [RoleRepository])
+    __param(1, inject(IDENTITY_OPTIONS)),
+    __metadata("design:paramtypes", [RoleStore, Object])
 ], RoleService);
 export { RoleService };

package/dist/tokens.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Injection Token for the Identity configuration options.
+ * Required because IdentityOptions is an interface and cannot be injected by type.
+ *
+ * @public
+ */
+export declare const IDENTITY_OPTIONS = "IdentityOptions";

package/dist/tokens.js

@@ -0,0 +1,7 @@
+/**
+ * Injection Token for the Identity configuration options.
+ * Required because IdentityOptions is an interface and cannot be injected by type.
+ *
+ * @public
+ */
+export const IDENTITY_OPTIONS = "IdentityOptions";

package/dist/types.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Authentication strategy modes.
+ *
+ * - `local`: Automatic authentication based on FiveM connection identifiers (e.g., license, discord).
+ *   Ideal for traditional FiveM servers where account creation should be transparent.
+ * - `credentials`: Manual authentication using username and password.
+ *   Suitable for servers with an integrated registration system.
+ * - `api`: Delegation of authentication to an external HTTP API.
+ *   Useful for servers integrated with a web dashboard or external auth service.
+ *
+ * @public
+ */
+export type AuthMode = "local" | "credentials" | "api";
+/**
+ * Authorization and principal resolution modes.
+ *
+ * - `roles`: Uses a static role hierarchy defined in the application code.
+ *   Provides the best performance and version control for role definitions.
+ * - `db`: Fetches roles and permissions dynamically from a persistent store.
+ * - `api`: Fetches principal data from an external HTTP API on demand.
+ *
+ * @public
+ */
+export type PrincipalMode = "roles" | "db" | "api";
+/**
+ * Represents a security role within the identity system.
+ *
+ * Roles define base permissions and a rank hierarchy used by the framework's `@Guard` decorator.
+ *
+ * @public
+ */
+export interface IdentityRole {
+    /**
+     * Technical identifier for the role (e.g., 'admin', 'moderator', 'user').
+     */
+    name: string;
+    /**
+     * Hierarchical weight.
+     *
+     * Used for rank-based authorization.
+     * Logic: UserRank >= RequiredRank.
+     */
+    rank: number;
+    /**
+     * List of permission strings granted to this role by default.
+     *
+     * Supports '*' wildcard for full framework access.
+     */
+    permissions: string[];
+    /**
+     * Human-readable label for UI display or chat prefix.
+     */
+    displayName?: string;
+}
+/**
+ * Global configuration options for the OpenCore Identity System.
+ *
+ * @public
+ */
+export interface IdentityOptions {
+    /**
+     * Authentication configuration.
+     */
+    auth: {
+        /**
+         * The strategy to use for authenticating players.
+         */
+        mode: AuthMode;
+        /**
+         * Whether to automatically create a new account when a player connects
+         * with valid identifiers that are not yet registered.
+         *
+         * Only applicable when mode is 'local'.
+         * @defaultValue true
+         */
+        autoCreate?: boolean;
+        /**
+         * The primary FiveM identifier used to unique-link an account.
+         * @defaultValue 'license'
+         */
+        primaryIdentifier?: string;
+    };
+    /**
+     * Authorization and permissions configuration.
+     */
+    principal: {
+        /**
+         * The strategy to use for resolving roles and permissions.
+         */
+        mode: PrincipalMode;
+        /**
+         * Static role definitions.
+         *
+         * Required when mode is 'roles'.
+         */
+        roles?: Record<string, IdentityRole>;
+        /**
+         * The name of the role assigned to newly created accounts.
+         * @defaultValue 'user'
+         */
+        defaultRole?: string;
+        /**
+         * Time-to-live in milliseconds for cached principal data.
+         *
+         * Since principal resolution is a high-frequency operation, caching is
+         * critical for performance.
+         * @defaultValue 300000 (5 minutes)
+         */
+        cacheTtl?: number;
+    };
+}
+/**
+ * Represents a persistent identity account.
+ *
+ * This object links a FiveM player to their persistent roles, permissions,
+ * and operational status (e.g., bans).
+ *
+ * @public
+ */
+export interface IdentityAccount {
+    /**
+     * Internal unique database/store ID.
+     */
+    id: string;
+    /**
+     * External stable ID used by the framework (linkedID).
+     *
+     * Usually a UUID or an external system ID.
+     */
+    linkedId: string;
+    /**
+     * Primary connection identifier (e.g., 'license:123...').
+     */
+    identifier: string;
+    /**
+     * Current technical role name assigned to this account.
+     */
+    roleName: string;
+    /**
+     * Optional technical username for credentials-based authentication.
+     */
+    username?: string | null;
+    /**
+     * Hashed password for credentials-based authentication.
+     *
+     * @internal
+     */
+    passwordHash?: string | null;
+    /**
+     * List of specific permission overrides for this account.
+     *
+     * - `+perm`: Explicitly grant a permission.
+     * - `-perm`: Explicitly revoke a permission (even if granted by role).
+     */
+    customPermissions: string[];
+    /**
+     * Whether the account is currently prohibited from connecting.
+     */
+    isBanned: boolean;
+    /**
+     * The reason provided for the current ban.
+     */
+    banReason?: string;
+    /**
+     * Timestamp when the ban expires.
+     *
+     * If null and isBanned is true, the ban is permanent.
+     */
+    banExpiresAt?: Date | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-core/identity",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Enterprise-grade identity, authentication, and authorization plugin for OpenCore Framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -39,14 +39,13 @@
   "packageManager": "pnpm@10.13.1",
   "dependencies": {
     "@open-core/framework": "^0.2.4",
-    "bcrypt": "^6.0.0",
+    "bcryptjs": "^3.0.3",
     "reflect-metadata": "^0.2.2",
     "tsyringe": "^4.10.0",
     "uuid": "^13.0.0",
     "zod": "^4.1.13"
   },
   "devDependencies": {
-    "@types/bcrypt": "^6.0.0",
     "@types/node": "^22.19.1",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",