@open-core/identity 1.0.0 → 1.2.1

package/dist/services/role.service.js

@@ -1,4 +1,3 @@
-"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);
@@ -8,138 +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);
 };
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RoleService = void 0;
-const tsyringe_1 = require("tsyringe");
-const role_repository_1 = require("../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 || [];
     }
 };
-exports.RoleService = RoleService;
-exports.RoleService = RoleService = __decorate([
-    (0, tsyringe_1.injectable)(),
-    __metadata("design:paramtypes", [role_repository_1.RoleRepository])
+RoleService = __decorate([
+    injectable(),
+    __param(1, inject(IDENTITY_OPTIONS)),
+    __metadata("design:paramtypes", [RoleStore, Object])
 ], RoleService);
+export { RoleService };

package/dist/setup.js

@@ -1,18 +1,15 @@
-"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");
+import { AccountRepository } from "./repositories/account.repository";
+import { RoleRepository } from "./repositories/role.repository";
+import { AccountService } from "./services/account.service";
+import { RoleService } from "./services/role.service";
+import { MemoryCacheService } from "./services/cache/memory-cache.service";
+import { LocalAuthProvider } from "./services/auth/local-auth.provider";
+import { CredentialsAuthProvider } from "./services/auth/credentials-auth.provider";
+import { ApiAuthProvider } from "./services/auth/api-auth.provider";
+import { LocalPrincipalProvider } from "./services/principal/local-principal.provider";
+import { ApiPrincipalProvider } from "./services/principal/api-principal.provider";
+import { IdentityAuthProvider } from "./services/identity-auth.provider";
+import { IdentityPrincipalProvider } from "./services/identity-principal.provider";
 /**
  * Register all Identity module singletons with the DI container.
  *
@@ -45,49 +42,49 @@ const identity_principal_provider_1 = require("./services/identity-principal.pro
  * });
  * ```
  */
-function setupIdentity(container, options = {}) {
+export 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);
+    container.registerSingleton(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);
+        container.registerSingleton(AccountRepository);
+        container.registerSingleton(RoleRepository);
+        container.registerSingleton(AccountService);
+        container.registerSingleton(RoleService);
     }
     // Register Auth Provider based on strategy
     switch (authProvider) {
         case "credentials":
-            container.registerSingleton("AuthProviderContract", credentials_auth_provider_1.CredentialsAuthProvider);
+            container.registerSingleton("AuthProviderContract", 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);
+            container.registerSingleton("AuthProviderContract", 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);
+            container.registerSingleton("AuthProviderContract", LocalAuthProvider);
             // Register LocalAuthProvider as the legacy IdentityAuthProvider for compatibility
-            container.registerSingleton(identity_auth_provider_1.IdentityAuthProvider, local_auth_provider_1.LocalAuthProvider);
+            container.registerSingleton(IdentityAuthProvider, LocalAuthProvider);
             break;
     }
     // Register Principal Provider based on strategy
     switch (principalProvider) {
         case "api":
-            container.registerSingleton("PrincipalProviderContract", api_principal_provider_1.ApiPrincipalProvider);
+            container.registerSingleton("PrincipalProviderContract", 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);
+            container.registerSingleton("PrincipalProviderContract", LocalPrincipalProvider);
             // Register LocalPrincipalProvider as the legacy IdentityPrincipalProvider for compatibility
-            container.registerSingleton(identity_principal_provider_1.IdentityPrincipalProvider, local_principal_provider_1.LocalPrincipalProvider);
+            container.registerSingleton(IdentityPrincipalProvider, LocalPrincipalProvider);
             break;
     }
 }

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/auth.types.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/types/index.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

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,9 +1,17 @@
 {
   "name": "@open-core/identity",
-  "version": "1.0.0",
-  "description": "Flexible identity and authentication system for OpenCore Framework",
+  "version": "1.2.1",
+  "description": "Enterprise-grade identity, authentication, and authorization plugin for OpenCore Framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "clean": "rimraf dist",
@@ -30,7 +38,7 @@
   },
   "packageManager": "pnpm@10.13.1",
   "dependencies": {
-    "@open-core/framework": "^1.0.1-beta.1",
+    "@open-core/framework": "^0.2.4",
     "bcrypt": "^6.0.0",
     "reflect-metadata": "^0.2.2",
     "tsyringe": "^4.10.0",
@@ -39,15 +47,12 @@
   },
   "devDependencies": {
     "@types/bcrypt": "^6.0.0",
-    "@types/node": "^22.7.5",
-    "@typescript-eslint/eslint-plugin": "^8.48.1",
-    "@typescript-eslint/parser": "^8.48.1",
+    "@types/node": "^22.19.1",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.4",
     "prettier": "3.7.1",
-    "rimraf": "^6.0.1",
+    "rimraf": "^6.1.2",
     "typescript": "^5.9.3"
   },
   "files": [

package/migrations/001_accounts_table.sql

@@ -1,16 +0,0 @@
-CREATE TABLE IF NOT EXISTS accounts (
-  id INT AUTO_INCREMENT PRIMARY KEY,
-  linked_id VARCHAR(255) UNIQUE NULL,
-  external_source VARCHAR(32) NULL,
-  license VARCHAR(64) UNIQUE,
-  discord VARCHAR(32) UNIQUE,
-  steam VARCHAR(32) UNIQUE,
-  username VARCHAR(64),
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  last_login_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  banned BOOLEAN DEFAULT FALSE,
-  ban_reason TEXT,
-  ban_expires TIMESTAMP NULL,
-  permissions JSON DEFAULT '[]'
-);
-

package/migrations/002_roles_table.sql

@@ -1,21 +0,0 @@
--- Migration 002: Create roles table
--- This table stores security roles/ranks with hierarchical permissions.
-
-CREATE TABLE IF NOT EXISTS roles (
-  id INT AUTO_INCREMENT PRIMARY KEY,
-  name VARCHAR(64) NOT NULL UNIQUE,
-  display_name VARCHAR(128) NOT NULL,
-  rank INT NOT NULL DEFAULT 0,
-  permissions JSON DEFAULT '[]',
-  is_default BOOLEAN DEFAULT FALSE,
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  
-  INDEX idx_name (name),
-  INDEX idx_is_default (is_default)
-);
-
--- Insert default role for new accounts
-INSERT INTO roles (name, display_name, rank, permissions, is_default) 
-VALUES ('user', 'Player', 0, '[]', TRUE)
-ON DUPLICATE KEY UPDATE name=name;
-

package/migrations/003_alter_accounts_add_role.sql

@@ -1,24 +0,0 @@
--- Migration 003: Alter accounts table to use role-based permissions
--- IMPORTANT: Run this AFTER creating roles and inserting at least a default role.
-
--- Add role_id foreign key column
-ALTER TABLE accounts 
-  ADD COLUMN role_id INT NULL AFTER username;
-
--- Add custom_permissions column for per-account overrides
-ALTER TABLE accounts 
-  ADD COLUMN custom_permissions JSON DEFAULT '[]' AFTER role_id;
-
--- Drop old flat permissions column
-ALTER TABLE accounts 
-  DROP COLUMN IF EXISTS permissions;
-
--- Add foreign key constraint to roles
-ALTER TABLE accounts 
-  ADD CONSTRAINT fk_accounts_role
-  FOREIGN KEY (role_id) REFERENCES roles(id) 
-  ON DELETE SET NULL;
-
--- Add index for faster role lookups
-CREATE INDEX idx_role_id ON accounts(role_id);
-

package/migrations/004_rename_uuid_to_linked_id.sql

@@ -1,12 +0,0 @@
--- Migration to rename uuid column to linked_id and add external_source
--- This migration is for existing installations that already have the accounts table
-
--- Rename uuid column to linked_id and increase length to support various ID formats
-ALTER TABLE accounts CHANGE COLUMN uuid linked_id VARCHAR(255) UNIQUE NULL;
-
--- Add external_source column to track account origin
-ALTER TABLE accounts ADD COLUMN external_source VARCHAR(32) NULL AFTER linked_id;
-
--- Update existing records to mark them as 'local' source
-UPDATE accounts SET external_source = 'local' WHERE external_source IS NULL;
-

package/migrations/005_add_password_hash.sql

@@ -1,7 +0,0 @@
--- Add password_hash column for credentials-based authentication
--- This is optional and only needed if using CredentialsAuthProvider
-
-ALTER TABLE accounts ADD COLUMN password_hash VARCHAR(255) NULL AFTER username;
-
--- Note: For existing systems, passwords can be set via AccountService.setPassword()
-