@open-core/identity 1.2.5 → 1.2.6

package/dist/contracts.d.ts

@@ -8,7 +8,7 @@ import type { IdentityAccount, IdentityRole } from "./types";
  *
  * @public
  */
-export declare abstract class IdentityStore {
+export declare abstract class IdentityStore<TId = any, TLinkedId = any, TRoleId = any> {
     /**
      * Retrieves an account by its primary connection identifier.
      *
@@ -16,13 +16,20 @@ export declare abstract class IdentityStore {
      * @returns A promise resolving to the account or null if not found.
      */
     abstract findByIdentifier(identifier: string): Promise<IdentityAccount | null>;
+    /**
+     * Retrieves an account by its unique numeric or internal ID.
+     *
+     * @param id - The internal account identifier (database ID).
+     * @returns A promise resolving to the account or null if not found.
+     */
+    abstract findById(id: TId): Promise<IdentityAccount | null>;
     /**
      * Retrieves an account by its linked stable ID.
      *
      * @param linkedId - The stable ID (e.g., a UUID).
      * @returns A promise resolving to the account or null if not found.
      */
-    abstract findByLinkedId(linkedId: string): Promise<IdentityAccount | null>;
+    abstract findByLinkedId(linkedId: TLinkedId): Promise<IdentityAccount | null>;
     /**
      * Retrieves an account by its unique username.
      *
@@ -30,6 +37,19 @@ export declare abstract class IdentityStore {
      * @returns A promise resolving to the account or null if not found.
      */
     abstract findByUsername(username: string): Promise<IdentityAccount | null>;
+    /**
+     * Retrieves all accounts that are currently banned.
+     *
+     * @returns A promise resolving to an array of banned accounts.
+     */
+    abstract findBanned(): Promise<IdentityAccount[]>;
+    /**
+     * Retrieves all accounts assigned to a specific role.
+     *
+     * @param roleId - The role identifier.
+     * @returns A promise resolving to an array of accounts.
+     */
+    abstract findByRole(roleId: TRoleId): Promise<IdentityAccount[]>;
     /**
      * Persists a new identity account.
      *
@@ -37,7 +57,7 @@ export declare abstract class IdentityStore {
      * @returns A promise resolving to the fully created account object.
      */
     abstract create(data: Omit<IdentityAccount, "id"> & {
-        id?: string | number;
+        id?: TId;
         passwordHash?: string;
     }): Promise<IdentityAccount>;
     /**
@@ -46,7 +66,7 @@ export declare abstract class IdentityStore {
      * @param id - The internal account ID.
      * @param data - Partial object containing fields to update.
      */
-    abstract update(id: string | number, data: Partial<Omit<IdentityAccount, "id">>): Promise<void>;
+    abstract update(id: TId, data: Partial<Omit<IdentityAccount, "id">>): Promise<void>;
     /**
      * Prohibits or allows an account from connecting.
      *
@@ -55,7 +75,7 @@ export declare abstract class IdentityStore {
      * @param reason - Optional explanation for the ban.
      * @param expiresAt - Optional expiration timestamp.
      */
-    abstract setBan(id: string | number, banned: boolean, reason?: string, expiresAt?: Date | null): Promise<void>;
+    abstract setBan(id: TId, banned: boolean, reason?: string, expiresAt?: Date | null): Promise<void>;
 }
 /**
  * Persistence contract for security roles.
@@ -65,14 +85,35 @@ export declare abstract class IdentityStore {
  *
  * @public
  */
-export declare abstract class RoleStore {
+export declare abstract class RoleStore<TId = any> {
     /**
      * Retrieves a role definition by its technical identifier.
      *
      * @param id - Technical identifier (e.g., 'admin' or 1).
      * @returns A promise resolving to the role or null if not found.
      */
-    abstract findById(id: string | number): Promise<IdentityRole | null>;
+    abstract findById(id: TId): Promise<IdentityRole | null>;
+    abstract findByName(name: string): Promise<IdentityRole | null>;
+    /**
+     * Retrieves a role by its hierarchical rank.
+     *
+     * @param rank - The numeric rank to search for.
+     * @returns A promise resolving to the role or null if not found.
+     */
+    abstract findByRank(rank: number): Promise<IdentityRole | null>;
+    /**
+     * Retrieves all roles that grant a specific permission.
+     *
+     * @param permission - The permission string to search for.
+     * @returns A promise resolving to an array of roles.
+     */
+    abstract findByPermission(permission: string): Promise<IdentityRole[]>;
+    /**
+     * Retrieves all registered roles in the system.
+     *
+     * @returns A promise resolving to an array of all roles.
+     */
+    abstract findAll(): Promise<IdentityRole[]>;
     /**
      * Resolves the default role for newly connected accounts.
      *
@@ -86,7 +127,7 @@ export declare abstract class RoleStore {
      * @returns A promise resolving to the fully created role object.
      */
     abstract create(role: Omit<IdentityRole, "id"> & {
-        id?: string | number;
+        id?: TId;
     }): Promise<IdentityRole>;
     /**
      * Updates an existing role definition.
@@ -94,11 +135,11 @@ export declare abstract class RoleStore {
      * @param id - Technical identifier of the role to update.
      * @param role - Partial role object containing the fields to modify.
      */
-    abstract update(id: string | number, role: Partial<Omit<IdentityRole, "id">>): Promise<void>;
+    abstract update(id: TId, role: Partial<Omit<IdentityRole, "id">>): Promise<void>;
     /**
      * Removes a role from the system.
      *
      * @param id - Technical identifier of the role to delete.
      */
-    abstract delete(id: string | number): Promise<void>;
+    abstract delete(id: TId): Promise<void>;
 }

package/dist/index.js

@@ -93,10 +93,57 @@ export var Identity;
         // Configure Principal SPI based on mode
         if (options.principal.mode === "api") {
             Server.setPrincipalProvider(ApiPrincipalImpl);
+            if (options.principal.defaultRole && typeof options.principal.defaultRole !== "string") {
+                throw new Error("[OpenCore-Identity] In 'api' principal mode, 'defaultRole' must be a string (the ID returned by the API).");
+            }
         }
         else {
             Server.setPrincipalProvider(PrincipalProviderImpl);
+            // Handle default role auto-creation or validation
+            const defaultRole = options.principal.defaultRole;
+            if (typeof defaultRole === "object") {
+                const roles = options.principal.roles || {};
+                const defaultId = "default_auto";
+                // Inject the role into the configuration if it doesn't exist
+                if (!roles[defaultId]) {
+                    options.principal.roles = {
+                        ...roles,
+                        [defaultId]: { ...defaultRole, id: defaultId },
+                    };
+                    options.principal.defaultRole = defaultId;
+                    console.log(`[OpenCore-Identity] Default role '${defaultId}' created from configuration.`);
+                }
+            }
         }
+        // Handle onReady and waitFor
+        const runInitialization = async () => {
+            // 1. Wait for dependencies if specified
+            if (options.hooks?.waitFor) {
+                const waits = Array.isArray(options.hooks.waitFor)
+                    ? options.hooks.waitFor
+                    : [options.hooks.waitFor];
+                try {
+                    await Promise.all(waits);
+                }
+                catch (err) {
+                    console.error("[OpenCore-Identity] Error waiting for dependencies in 'waitFor':", err);
+                    return;
+                }
+            }
+            // 2. Execute onReady hook
+            if (options.hooks?.onReady) {
+                const accountService = container.resolve(AccountServiceImpl);
+                const roleService = container.resolve(RoleServiceImpl);
+                try {
+                    await options.hooks.onReady({ accounts: accountService, roles: roleService, container });
+                }
+                catch (err) {
+                    console.error("[OpenCore-Identity] Error in onReady hook:", err);
+                }
+            }
+        };
+        // Execute the async flow without blocking the main install call
+        runInitialization();
     }
     Identity.install = install;
 })(Identity || (Identity = {}));

package/dist/providers/auth/credentials-auth.provider.d.ts

@@ -1,6 +1,5 @@
 import { Server } from "@open-core/framework";
-import { IdentityStore } from "../../contracts";
-import type { IdentityOptions } from "../../types";
+import { IdentityStore, RoleStore } from "../../contracts";
 /**
  * Authentication provider for username and password credentials.
  *
@@ -12,17 +11,11 @@ import type { IdentityOptions } from "../../types";
  * @public
  */
 export declare class CredentialsAuthProvider extends Server.AuthProviderContract {
-    private readonly options;
-    private readonly store;
+    private readonly accountStore;
+    private readonly roleStore;
     /** Cost factor for bcrypt hashing */
     private readonly saltRounds;
-    /**
-     * Initializes a new instance of the CredentialsAuthProvider.
-     *
-     * @param options - Identity system configuration options.
-     * @param store - Persistence layer for account and credential data.
-     */
-    constructor(options: IdentityOptions, store: IdentityStore);
+    constructor(accountStore: IdentityStore<string, string, string>, roleStore: RoleStore<string>);
     /**
      * Authenticates a player using a username and password.
      *

package/dist/providers/auth/credentials-auth.provider.js

@@ -7,13 +7,9 @@ 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);
 };
-var __param = (this && this.__param) || function (paramIndex, decorator) {
-    return function (target, key) { decorator(target, key, paramIndex); }
-};
-import { injectable, inject } from "tsyringe";
+import { injectable } from "tsyringe";
 import { Server } from "@open-core/framework";
-import { IDENTITY_OPTIONS } from "../../tokens";
-import { IdentityStore } from "../../contracts";
+import { IdentityStore, RoleStore } from "../../contracts";
 import bcrypt from "bcryptjs";
 /**
  * Authentication provider for username and password credentials.
@@ -26,16 +22,10 @@ import bcrypt from "bcryptjs";
  * @public
  */
 let CredentialsAuthProvider = class CredentialsAuthProvider extends Server.AuthProviderContract {
-    /**
-     * Initializes a new instance of the CredentialsAuthProvider.
-     *
-     * @param options - Identity system configuration options.
-     * @param store - Persistence layer for account and credential data.
-     */
-    constructor(options, store) {
+    constructor(accountStore, roleStore) {
         super();
-        this.options = options;
-        this.store = store;
+        this.accountStore = accountStore;
+        this.roleStore = roleStore;
         /** Cost factor for bcrypt hashing */
         this.saltRounds = 10;
     }
@@ -52,9 +42,9 @@ let CredentialsAuthProvider = class CredentialsAuthProvider extends Server.AuthP
         if (!username || !password) {
             return { success: false, error: "Username and password are required" };
         }
-        const account = await this.store.findByUsername(username);
+        const account = await this.accountStore.findByUsername(username);
         if (!account) {
-            return { success: false, error: "Invalid credentials" };
+            return { success: false, error: "Account not found" };
         }
         const passwordHash = account.passwordHash;
         if (!passwordHash) {
@@ -62,6 +52,7 @@ let CredentialsAuthProvider = class CredentialsAuthProvider extends Server.AuthP
         }
         const isValid = await bcrypt.compare(password, passwordHash);
         if (!isValid) {
+            console.log(`compared and is not the same password!`);
             return { success: false, error: "Invalid credentials" };
         }
         if (this.isBanned(account)) {
@@ -84,18 +75,19 @@ let CredentialsAuthProvider = class CredentialsAuthProvider extends Server.AuthP
         if (!username || !password) {
             return { success: false, error: "Username and password are required" };
         }
-        const existing = await this.store.findByUsername(username);
+        const existing = await this.accountStore.findByUsername(username);
         if (existing) {
             return { success: false, error: "Username already taken" };
         }
         const passwordHash = await bcrypt.hash(password, this.saltRounds);
         const identifiers = player.getIdentifiers();
         const primaryIdentifier = identifiers[0] || `internal:${username}`;
-        const account = await this.store.create({
+        const defaultRole = await this.roleStore.getDefaultRole();
+        const account = await this.accountStore.create({
             username,
             passwordHash,
             identifier: primaryIdentifier,
-            roleId: this.options.principal.defaultRole || "user",
+            roleId: defaultRole.id,
             customPermissions: [],
             isBanned: false,
         });
@@ -113,7 +105,7 @@ let CredentialsAuthProvider = class CredentialsAuthProvider extends Server.AuthP
         const accountId = player.accountID;
         if (!accountId)
             return { success: false, error: "Not authenticated" };
-        const account = await this.store.findByLinkedId(accountId);
+        const account = await this.accountStore.findByLinkedId(accountId);
         if (!account || this.isBanned(account)) {
             return { success: false, error: "Session invalid or account banned" };
         }
@@ -125,7 +117,7 @@ let CredentialsAuthProvider = class CredentialsAuthProvider extends Server.AuthP
      * @param player - The framework player entity.
      */
     async logout(player) {
-        // Session state is managed by the framework.
+        player.unlinkAccount();
     }
     /**
      * Internal helper to determine if an account is currently prohibited.
@@ -145,7 +137,7 @@ let CredentialsAuthProvider = class CredentialsAuthProvider extends Server.AuthP
 };
 CredentialsAuthProvider = __decorate([
     injectable(),
-    __param(0, inject(IDENTITY_OPTIONS)),
-    __metadata("design:paramtypes", [Object, IdentityStore])
+    __metadata("design:paramtypes", [IdentityStore,
+        RoleStore])
 ], CredentialsAuthProvider);
 export { CredentialsAuthProvider };

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

@@ -28,7 +28,6 @@ interface AuthResult {
 export declare class LocalAuthProvider extends Server.AuthProviderContract {
     private readonly options;
     private readonly store;
-    private readonly config;
     /**
      * Initializes a new instance of the IdentityAuthProvider.
      *
@@ -36,7 +35,7 @@ export declare class LocalAuthProvider extends Server.AuthProviderContract {
      * @param store - Persistence layer for account data.
      * @param config - Framework configuration service.
      */
-    constructor(options: IdentityOptions, store: IdentityStore, config: Server.ConfigService);
+    constructor(options: IdentityOptions, store: IdentityStore);
     /**
      * Authenticates a player based on the configured strategy.
      *

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

@@ -31,11 +31,10 @@ let LocalAuthProvider = class LocalAuthProvider extends Server.AuthProviderContr
      * @param store - Persistence layer for account data.
      * @param config - Framework configuration service.
      */
-    constructor(options, store, config) {
+    constructor(options, store) {
         super();
         this.options = options;
         this.store = store;
-        this.config = config;
     }
     /**
      * Authenticates a player based on the configured strategy.
@@ -147,6 +146,6 @@ let LocalAuthProvider = class LocalAuthProvider extends Server.AuthProviderContr
 LocalAuthProvider = __decorate([
     injectable(),
     __param(0, inject(IDENTITY_OPTIONS)),
-    __metadata("design:paramtypes", [Object, IdentityStore, Server.ConfigService])
+    __metadata("design:paramtypes", [Object, IdentityStore])
 ], LocalAuthProvider);
 export { LocalAuthProvider };

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

@@ -116,7 +116,10 @@ let IdentityPrincipalProvider = class IdentityPrincipalProvider extends Server.P
         if (!role) {
             const defaultRoleId = this.options.principal.defaultRole;
             if (defaultRoleId !== undefined && defaultRoleId !== null && defaultRoleId !== "") {
-                role = this.options.principal.roles?.[defaultRoleId];
+                // We ensure defaultRoleId is a valid key (string | number) because Identity.install
+                // converts any IdentityRole object into a registered 'default_auto' string ID.
+                const roleKey = typeof defaultRoleId === "object" ? "default_auto" : defaultRoleId;
+                role = this.options.principal.roles?.[roleKey];
                 if (!role && this.roleStore && this.options.principal.mode === "db") {
                     role = await this.roleStore.getDefaultRole();
                 }

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

@@ -1,4 +1,4 @@
-import { IdentityStore } from "../contracts";
+import { IdentityStore, RoleStore } from "../contracts";
 import type { IdentityAccount } from "../types";
 /**
  * High-level service for managing identity accounts and security policies.
@@ -9,48 +9,33 @@ import type { IdentityAccount } from "../types";
  * @public
  * @injectable
  */
-export declare class AccountService {
-    private readonly store;
-    constructor(store: IdentityStore);
+export declare class AccountService<TId = any, TLinkedId = any, TRoleId = any> {
+    readonly store: IdentityStore<TId, TLinkedId, TRoleId>;
+    constructor(store: IdentityStore<TId, TLinkedId, TRoleId>);
     /**
-     * Retrieves an account by its unique numeric or internal ID.
+     * Retrieves all accounts assigned to a specific role.
      *
-     * @param id - The internal account identifier.
-     * @returns A promise resolving to the account or null if not found.
+     * @param roleId - The role identifier.
+     * @returns A promise resolving to an array of accounts.
      */
-    findById(id: string): Promise<IdentityAccount | null>;
+    findByRole(roleId: TRoleId): Promise<IdentityAccount[]>;
     /**
-     * Retrieves an account by its stable linked ID.
+     * Retrieves all accounts that are currently prohibited from connecting.
      *
-     * @param linkedId - The stable ID (UUID or external system ID).
-     * @returns A promise resolving to the account or null if not found.
+     * @returns A promise resolving to an array of banned accounts.
      */
-    findByLinkedId(linkedId: string): Promise<IdentityAccount | null>;
-    /**
-     * Persists a new identity account.
-     *
-     * @param data - Initial account properties. ID can be provided or left to the store.
-     * @returns A promise resolving to the fully created account object.
-     */
-    create(data: Omit<IdentityAccount, "id"> & {
-        id?: string | number;
-        passwordHash?: string;
-    }): Promise<IdentityAccount>;
-    /**
-     * Updates an existing account's metadata or status.
-     *
-     * @param id - The internal account ID.
-     * @param data - Partial object containing fields to update.
-     * @returns A promise that resolves when the update is complete.
-     */
-    update(id: string | number, data: Partial<Omit<IdentityAccount, "id">>): Promise<void>;
+    findBanned(): Promise<IdentityAccount[]>;
+    assignRole(accountId: TId, roleId: TRoleId, options?: {
+        clearCustomPermissions?: boolean;
+    }): Promise<void>;
     /**
-     * Assigns a security role to an account.
+     * Checks if an account has a specific permission, considering both role and custom overrides.
      *
-     * @param accountId - The unique ID of the account.
-     * @param roleId - Technical identifier of the role to assign.
+     * @param accountId - The account identifier.
+     * @param permission - The permission string to check.
+     * @param roleStore - Required to resolve the role's base permissions.
      */
-    assignRole(accountId: string | number, roleId: string | number): Promise<void>;
+    hasPermission(linkedID: TLinkedId, permission: string, roleStore: RoleStore): Promise<boolean>;
     /**
      * Grants a custom permission override to an account.
      *
@@ -60,24 +45,24 @@ export declare class AccountService {
      * @param accountId - The linked ID of the account.
      * @param permission - The permission string to grant.
      */
-    addCustomPermission(accountId: string, permission: string): Promise<void>;
+    addCustomPermission(linkedID: TLinkedId, permission: string): Promise<void>;
     /**
      * Revokes a custom permission override.
      *
      * To explicitly deny a permission that a role might grant, use the `-` prefix
      * (e.g., `-chat.use`).
      *
-     * @param accountId - The linked ID of the account.
+     * @param linkedID - The linked ID of the account.
      * @param permission - The permission string to remove or revoke.
      */
-    removeCustomPermission(accountId: string, permission: string): Promise<void>;
+    removeCustomPermission(linkedID: TLinkedId, permission: string): Promise<void>;
     /**
      * Prohibits an account from connecting to the server.
      *
      * @param accountId - The linked ID of the account.
      * @param options - Ban details including optional reason and duration.
      */
-    ban(accountId: string, options?: {
+    ban(accountId: TId, options?: {
         reason?: string;
         durationMs?: number;
     }): Promise<void>;
@@ -86,5 +71,5 @@ export declare class AccountService {
      *
      * @param accountId - The linked ID of the account.
      */
-    unban(accountId: string): Promise<void>;
+    unban(accountId: TId): Promise<void>;
 }

package/dist/services/account.service.js

@@ -23,50 +23,53 @@ let AccountService = class AccountService {
         this.store = store;
     }
     /**
-     * Retrieves an account by its unique numeric or internal ID.
+     * Retrieves all accounts assigned to a specific role.
      *
-     * @param id - The internal account identifier.
-     * @returns A promise resolving to the account or null if not found.
+     * @param roleId - The role identifier.
+     * @returns A promise resolving to an array of accounts.
      */
-    async findById(id) {
-        return this.store.findByLinkedId(id); // Using linkedId as the primary public handle
+    async findByRole(roleId) {
+        return this.store.findByRole(roleId);
     }
     /**
-     * Retrieves an account by its stable linked ID.
+     * Retrieves all accounts that are currently prohibited from connecting.
      *
-     * @param linkedId - The stable ID (UUID or external system ID).
-     * @returns A promise resolving to the account or null if not found.
+     * @returns A promise resolving to an array of banned accounts.
      */
-    async findByLinkedId(linkedId) {
-        return this.store.findByLinkedId(linkedId);
+    async findBanned() {
+        return this.store.findBanned();
     }
-    /**
-     * Persists a new identity account.
-     *
-     * @param data - Initial account properties. ID can be provided or left to the store.
-     * @returns A promise resolving to the fully created account object.
-     */
-    async create(data) {
-        return this.store.create(data);
+    async assignRole(accountId, roleId, options = {}) {
+        const updateData = { roleId };
+        if (options.clearCustomPermissions) {
+            updateData.customPermissions = [];
+        }
+        await this.store.update(accountId, updateData);
     }
     /**
-     * Updates an existing account's metadata or status.
+     * Checks if an account has a specific permission, considering both role and custom overrides.
      *
-     * @param id - The internal account ID.
-     * @param data - Partial object containing fields to update.
-     * @returns A promise that resolves when the update is complete.
+     * @param accountId - The account identifier.
+     * @param permission - The permission string to check.
+     * @param roleStore - Required to resolve the role's base permissions.
      */
-    async update(id, data) {
-        await this.store.update(id, data);
-    }
-    /**
-     * Assigns a security role to an account.
-     *
-     * @param accountId - The unique ID of the account.
-     * @param roleId - Technical identifier of the role to assign.
-     */
-    async assignRole(accountId, roleId) {
-        await this.update(accountId, { roleId });
+    async hasPermission(linkedID, permission, roleStore) {
+        const account = await this.store.findByLinkedId(linkedID);
+        if (!account)
+            return false;
+        if (!account.roleId)
+            return account.customPermissions.includes(permission);
+        const role = await roleStore.findById(account.roleId);
+        const basePermissions = role?.permissions || [];
+        // Simple resolution logic (could be more complex with wildcards)
+        const permissions = new Set(basePermissions);
+        for (const override of account.customPermissions) {
+            if (override === `+${permission}` || override === permission)
+                return true;
+            if (override === `-${permission}`)
+                return false;
+        }
+        return permissions.has(permission) || permissions.has("*");
     }
     /**
      * Grants a custom permission override to an account.
@@ -77,13 +80,13 @@ let AccountService = class AccountService {
      * @param accountId - The linked ID of the account.
      * @param permission - The permission string to grant.
      */
-    async addCustomPermission(accountId, permission) {
-        const account = await this.store.findByLinkedId(accountId);
+    async addCustomPermission(linkedID, permission) {
+        const account = await this.store.findByLinkedId(linkedID);
         if (!account)
             return;
         const permissions = new Set(account.customPermissions);
         permissions.add(permission);
-        await this.store.update(accountId, {
+        await this.store.update(account.id, {
             customPermissions: Array.from(permissions),
         });
     }
@@ -93,16 +96,16 @@ let AccountService = class AccountService {
      * To explicitly deny a permission that a role might grant, use the `-` prefix
      * (e.g., `-chat.use`).
      *
-     * @param accountId - The linked ID of the account.
+     * @param linkedID - The linked ID of the account.
      * @param permission - The permission string to remove or revoke.
      */
-    async removeCustomPermission(accountId, permission) {
-        const account = await this.store.findByLinkedId(accountId);
+    async removeCustomPermission(linkedID, permission) {
+        const account = await this.store.findByLinkedId(linkedID);
         if (!account)
             return;
         const permissions = new Set(account.customPermissions);
         permissions.delete(permission);
-        await this.store.update(accountId, {
+        await this.store.update(account.id, {
             customPermissions: Array.from(permissions),
         });
     }

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

@@ -10,38 +10,29 @@ import type { IdentityRole } from "../types";
  * @public
  * @injectable
  */
-export declare class RoleService {
-    private readonly store;
-    constructor(store: RoleStore);
+export declare class RoleService<TId = any> {
+    readonly store: RoleStore<TId>;
+    constructor(store: RoleStore<TId>);
     /**
-     * Persists a new security role definition.
+     * Retrieves all roles that grant a specific permission.
      *
-     * @param role - The initial role properties (ID is optional).
-     * @returns A promise resolving to the created role.
+     * @param permission - The permission string to search for.
+     * @returns A promise resolving to an array of roles.
      */
-    create(role: Omit<IdentityRole, "id"> & {
-        id?: string | number;
-    }): Promise<IdentityRole>;
+    findByPermission(permission: string): Promise<IdentityRole[]>;
     /**
-     * Updates an existing role's rank or permissions.
+     * Retrieves a role by its hierarchical rank.
      *
-     * @param id - The unique technical identifier of the role to update.
-     * @param data - Partial object containing the fields to modify.
-     * @returns A promise that resolves when the update is complete.
+     * @param rank - The numeric rank to search for.
+     * @returns A promise resolving to the role or null if not found.
      */
-    update(id: string | number, data: Partial<Omit<IdentityRole, "id">>): Promise<void>;
+    findByRank(rank: number): Promise<IdentityRole | null>;
     /**
-     * Permanently removes a role definition from the system.
+     * Checks if a role is higher or equal than another based on rank.
      *
-     * @param id - The technical identifier of the role to delete.
-     * @returns A promise that resolves when the role is deleted.
+     * @param roleId - The role to check.
+     * @param requiredRoleId - The required role.
+     * @returns True if roleId has equal or higher rank.
      */
-    delete(id: string | number): Promise<void>;
-    /**
-     * Retrieves the full list of permissions granted to a specific role.
-     *
-     * @param id - The technical identifier of the role.
-     * @returns A promise resolving to an array of permission strings.
-     */
-    getPermissions(id: string | number): Promise<string[]>;
+    isHigherOrEqual(roleId: TId, requiredRoleId: TId): Promise<boolean>;
 }

package/dist/services/role.service.js

@@ -24,42 +24,38 @@ let RoleService = class RoleService {
         this.store = store;
     }
     /**
-     * Persists a new security role definition.
+     * Retrieves all roles that grant a specific permission.
      *
-     * @param role - The initial role properties (ID is optional).
-     * @returns A promise resolving to the created role.
+     * @param permission - The permission string to search for.
+     * @returns A promise resolving to an array of roles.
      */
-    async create(role) {
-        return this.store.create(role);
+    async findByPermission(permission) {
+        return this.store.findByPermission(permission);
     }
     /**
-     * Updates an existing role's rank or permissions.
+     * Retrieves a role by its hierarchical rank.
      *
-     * @param id - The unique technical identifier of the role to update.
-     * @param data - Partial object containing the fields to modify.
-     * @returns A promise that resolves when the update is complete.
+     * @param rank - The numeric rank to search for.
+     * @returns A promise resolving to the role or null if not found.
      */
-    async update(id, data) {
-        await this.store.update(id, data);
+    async findByRank(rank) {
+        return this.store.findByRank(rank);
     }
     /**
-     * Permanently removes a role definition from the system.
+     * Checks if a role is higher or equal than another based on rank.
      *
-     * @param id - The technical identifier of the role to delete.
-     * @returns A promise that resolves when the role is deleted.
+     * @param roleId - The role to check.
+     * @param requiredRoleId - The required role.
+     * @returns True if roleId has equal or higher rank.
      */
-    async delete(id) {
-        await this.store.delete(id);
-    }
-    /**
-     * Retrieves the full list of permissions granted to a specific role.
-     *
-     * @param id - The technical identifier of the role.
-     * @returns A promise resolving to an array of permission strings.
-     */
-    async getPermissions(id) {
-        const role = await this.store.findById(id);
-        return role?.permissions || [];
+    async isHigherOrEqual(roleId, requiredRoleId) {
+        const [role, required] = await Promise.all([
+            this.store.findById(roleId),
+            this.store.findById(requiredRoleId)
+        ]);
+        if (!role || !required)
+            return false;
+        return role.rank >= required.rank;
     }
 };
 RoleService = __decorate([

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+import { AccountService } from "./services/account.service";
+import { RoleService } from "./services/role.service";
 /**
  * Authentication strategy modes.
  *
@@ -29,11 +31,13 @@ export type PrincipalMode = "roles" | "db" | "api";
  *
  * @public
  */
-export interface IdentityRole {
+export interface IdentityRole<TId = any> {
     /**
-     * Technical identifier for the role (e.g., 'admin', 1, 'uuid').
+     * Technical identifier for the role (e.g., 1, 'uuid').
      */
-    id: string | number;
+    id: TId;
+    /** name, common used by identifiers 'admin' */
+    name: string;
     /**
      * Hierarchical weight.
      *
@@ -79,6 +83,15 @@ export interface IdentityOptions {
          * @defaultValue 'license'
          */
         primaryIdentifier?: string;
+        /**
+         * The ID of the role assigned to newly created accounts.
+         *
+         * - If string/number: Used as the ID of an existing role.
+         * - If IdentityRole object without ID: A default role will be created automatically.
+         *
+         * @defaultValue 'user'
+         */
+        defaultRole?: string | number | Omit<IdentityRole, "id">;
     };
     /**
      * Authorization and permissions configuration.
@@ -95,10 +108,10 @@ export interface IdentityOptions {
          */
         roles?: Record<string | number, IdentityRole>;
         /**
-         * The ID of the role assigned to newly created accounts.
-         * @defaultValue 'user'
+         * The default role, if you set a ID (external ID) use string type
+         * or use IdentityRole without id to create a new
          */
-        defaultRole?: string | number;
+        defaultRole?: Omit<IdentityRole, 'id'> | string;
         /**
          * Time-to-live in milliseconds for cached principal data.
          *
@@ -108,6 +121,25 @@ export interface IdentityOptions {
          */
         cacheTtl?: number;
     };
+    /**
+     * Lifecycle hooks for the identity system.
+     */
+    hooks?: {
+        /**
+         * Optional promise or array of promises to wait for before finishing initialization.
+         * Useful for ensuring database connections are established.
+         */
+        waitFor?: Promise<any> | Promise<any>[];
+        /**
+         * Fired when the identity system is fully initialized and registered.
+         * Use this to perform database seeding (e.g., creating default roles).
+         */
+        onReady?: (services: {
+            accounts: AccountService;
+            roles: RoleService;
+            container: any;
+        }) => Promise<void> | void;
+    };
 }
 /**
  * Represents a persistent identity account.
@@ -117,19 +149,19 @@ export interface IdentityOptions {
  *
  * @public
  */
-export interface IdentityAccount {
+export interface IdentityAccount<TId = any, TRoleId = any> {
     /**
      * Internal unique database/store ID.
      */
-    id: string | number;
+    id: TId;
     /**
      * Primary connection identifier (e.g., 'license:123...').
      */
-    identifier: string;
+    identifier?: string;
     /**
      * Current technical role ID assigned to this account.
      */
-    roleId?: string | number;
+    roleId?: TRoleId;
     /**
      * Optional technical username for credentials-based authentication.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-core/identity",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "description": "Enterprise-grade identity, authentication, and authorization plugin for OpenCore Framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -39,7 +39,7 @@
   },
   "packageManager": "pnpm@10.13.1",
   "dependencies": {
-    "@open-core/framework": "^0.2.4",
+    "@open-core/framework": "^0.2.7",
     "bcryptjs": "^3.0.3",
     "reflect-metadata": "^0.2.2",
     "tsyringe": "^4.10.0",