@open-core/identity 1.2.5 → 1.3.0

package/README.md

@@ -1,76 +1,171 @@
-# @open-core/identity
-
-Enterprise-grade identity, authentication, and authorization plugin for the OpenCore Framework.
-
-## Documentation Index
-
-- [Architecture & Dependency Injection](./docs/architecture.md) - Learn about constructor injection and DI.
-- [Authentication Modes](./docs/auth-modes.md) - Details on `local`, `credentials`, and `api` auth.
-- [Principal Modes](./docs/principal-modes.md) - Details on `roles`, `db`, and `api` authorization.
-- [Implementing Contracts](./docs/contracts.md) - How to build your own `IdentityStore` or `RoleStore`.
-
-## Features
-
-- **Multi-Strategy Authentication**: Support for `local`, `credentials`, and `api` strategies.
-- **Hierarchical RBAC**: Rank-based authorization and permission merging.
-- **Constructor Injection**: Services are automatically available in your classes via DI.
-- **Stateless Architecture**: Decoupled persistence via implementable contracts.
-
-## Quick Start (Constructor Injection)
-
-The recommended way to use the identity system is through **Constructor Injection**. The framework handles the lifecycle for you.
-
-```ts
-import { Server } from "@open-core/framework";
-import { AccountService } from "@open-core/identity";
-
-@Server.Controller()
-export class MyController {
-  // AccountService is automatically injected
-  constructor(private readonly accounts: AccountService) {}
-
-  @Server.OnNet("admin:ban")
-  async handleBan(player: Server.Player, targetId: string) {
-    await this.accounts.ban(targetId, { reason: "Policy violation" });
-  }
-}
-```
-
-## Installation & Setup
-
-1.  **Implement your Store** (See [Contracts](./docs/contracts.md)):
-    ```ts
-    import { Identity, IdentityStore } from "@open-core/identity";
-    
-    class MyStore extends IdentityStore { /* ... */ }
-    
-    // Register it before installation
-    Identity.setIdentityStore(MyStore);
-    ```
-
-2.  **Install the Plugin**:
-    ```ts
-    Identity.install({
-      auth: { mode: 'local', autoCreate: true },
-      principal: {
-        mode: 'roles',
-        roles: {
-          admin: { name: 'admin', rank: 100, permissions: ['*'] },
-          user: { name: 'user', rank: 0, permissions: ['chat.use'] }
-        }
-      }
-    });
-    ```
-
-## Exports
-
-The library only exports high-level components to keep your IDE suggestions clean:
-- `Identity`: The main namespace for installation and registration.
-- `AccountService`, `RoleService`: Public services for business logic.
-- `IdentityStore`, `RoleStore`: Abstract contracts for persistence.
-- `IDENTITY_OPTIONS`: Token for advanced DI usage.
-- All relevant types and interfaces.
-
-## License
-
-MIT
+# @open-core/identity
+
+Enterprise-grade identity, authentication, and authorization plugin for the OpenCore Framework.
+
+## Documentation Index
+
+- [Architecture & Dependency Injection](./docs/architecture.md) - Learn about constructor injection and DI.
+- [Authentication Modes](./docs/auth-modes.md) - Details on `local`, `credentials`, and `api` auth.
+- [Principal Modes](./docs/principal-modes.md) - Details on `roles`, `db`, and `api` authorization.
+- [Implementing Contracts](./docs/contracts.md) - How to build your own `IdentityStore` or `RoleStore`.
+
+## Features
+
+- **Multi-Strategy Authentication**: Support for `local`, `credentials`, and `api` strategies.
+- **Hierarchical RBAC**: Rank-based authorization and permission merging.
+- **Constructor Injection**: Services are automatically available in your classes via DI.
+- **Stateless Architecture**: Decoupled persistence via implementable contracts.
+
+## Quick Start (Constructor Injection)
+
+The recommended way to use the identity system is through **Constructor Injection**. The framework handles the lifecycle for you.
+
+```ts
+import { Server } from "@open-core/framework";
+import { AccountService } from "@open-core/identity";
+
+@Server.Controller()
+export class MyController {
+  // AccountService is automatically injected
+  constructor(private readonly accounts: AccountService) {}
+
+  @Server.OnNet("admin:ban")
+  async handleBan(player: Server.Player, targetId: string) {
+    await this.accounts.ban(targetId, { reason: "Policy violation" });
+  }
+}
+```
+
+## Installation & Setup
+
+1.  **Implement your Store** (See [Contracts](./docs/contracts.md)):
+
+    ```ts
+    import { Identity, IdentityStore } from "@open-core/identity";
+
+    class MyStore extends IdentityStore {
+      /* ... */
+    }
+
+    // Register it before installation
+    Identity.setIdentityStore(MyStore);
+    ```
+
+2.  **Install the Plugin**:
+    ```ts
+    Identity.install({
+      auth: { mode: "local", autoCreate: true, primaryIdentifier: "license" },
+      principal: {
+        mode: "roles",
+        roles: {
+          admin: { name: "admin", rank: 100, permissions: ["*"] },
+          user: { name: "user", rank: 0, permissions: ["chat.use"] },
+        },
+      },
+    });
+    ```
+
+## Auth Strategies
+
+All strategies are resolved through `AuthService`. Configure one mode and the framework
+will inject the correct provider.
+
+Quick summary:
+
+- local: identifies by license/steam/discord, no form.
+- credentials: username/password stored on your server.
+- api: delegates to an external HTTP service.
+
+### Local (Identifiers)
+
+What it is: authenticates using player identifiers (license/steam/discord).
+Who it is for: servers that want automatic access without forms.
+
+```ts
+Identity.install({
+  auth: {
+    mode: "local",
+    primaryIdentifier: "license",
+    autoCreate: true,
+  },
+  // ...
+});
+```
+
+### Credentials (Username/Password)
+
+What it is: login and registration with username/password stored on your server.
+Who it is for: servers with custom UI or manual registration.
+
+```ts
+Identity.install({
+  auth: {
+    mode: "credentials",
+  },
+  // ...
+});
+```
+
+### API (External Service)
+
+What it is: delegates all auth to an external HTTP service.
+Who it is for: large networks with a centralized database or SSO.
+
+```ts
+Identity.install({
+  auth: {
+    mode: "api",
+    primaryIdentifier: "license",
+    api: {
+      baseUrl: "https://auth.example.com",
+      authPath: "/auth",
+      registerPath: "/register",
+      sessionPath: "/session",
+      logoutPath: "/logout",
+    },
+  },
+  // ...
+});
+```
+
+## Usage Example
+
+```ts
+import { Server } from "@open-core/framework";
+import { AuthService } from "@open-core/identity";
+
+@Server.Controller()
+export class AuthController {
+  constructor(private readonly auth: AuthService) {}
+
+  @Server.OnNet("auth:login")
+  async login(
+    player: Server.Player,
+    payload: { username: string; password: string },
+  ) {
+    return this.auth.authenticate(player, payload);
+  }
+
+  @Server.OnNet("auth:register")
+  async register(
+    player: Server.Player,
+    payload: { username: string; password: string },
+  ) {
+    return this.auth.register(player, payload);
+  }
+}
+```
+
+## Exports
+
+The library only exports high-level components to keep your IDE suggestions clean:
+
+- `Identity`: The main namespace for installation and registration.
+- `AccountService`, `RoleService`: Public services for business logic.
+- `IdentityStore`, `RoleStore`: Abstract contracts for persistence.
+- `IDENTITY_OPTIONS`: Token for advanced DI usage.
+- All relevant types and interfaces.
+
+## License
+
+MIT

package/dist/auth.service.d.ts

@@ -0,0 +1,48 @@
+import { Server } from "@open-core/framework/server";
+import { IdentityAccount } from "./types";
+/**
+ * Result structure for authentication operations.
+ */
+export interface AuthResult {
+    /** Indicates if the operation was successful */
+    success: boolean;
+    /** The unique identifier for the authenticated account */
+    accountID?: string;
+    /** Error message if the operation failed */
+    error?: string;
+    /** Indicates if a new account was created during the process */
+    isNewAccount?: boolean;
+    /** Generic account Data type  */
+    account?: IdentityAccount;
+}
+export declare abstract class AuthService {
+    /**
+     * Authenticates a player using the selected strategy.
+     *
+     * @param player - The framework player entity.
+     * @param credentials - Strategy-specific credentials.
+     * @returns A promise resolving to the authentication result.
+     */
+    abstract authenticate(player: Server.Player, credentials: Record<string, unknown>): Promise<AuthResult>;
+    /**
+     * Registers a new account for the player.
+     *
+     * @param player - The framework player entity.
+     * @param credentials - Strategy-specific registration data.
+     * @returns A promise resolving to the registration result.
+     */
+    abstract register(player: Server.Player, credentials: Record<string, unknown>): Promise<AuthResult>;
+    /**
+     * Validates if the player's current linked account session is still active.
+     *
+     * @param player - The framework player entity.
+     * @returns A promise resolving to the validation result.
+     */
+    abstract validateSession(player: Server.Player): Promise<AuthResult>;
+    /**
+     * Clears authentication state for the player.
+     *
+     * @param player - The framework player entity.
+     */
+    abstract logout(player: Server.Player): Promise<void>;
+}

package/dist/auth.service.js

@@ -0,0 +1,2 @@
+export class AuthService {
+}

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.d.ts

@@ -37,8 +37,8 @@ export declare namespace Identity {
     /**
      * Installs the Identity plugin into the OpenCore Framework.
      *
-     * This function registers the necessary Authentication and Principal providers
-     * into the framework's SPI via `Server.setAuthProvider` and `Server.setPrincipalProvider`.
+      * This function registers the necessary Authentication service and Principal provider
+      * into the framework's SPI via dependency injection and `Server.setPrincipalProvider`.
      *
      * @param options - Configuration options for the identity system.
      *

package/dist/index.js

@@ -1,8 +1,9 @@
-import { Server } from "@open-core/framework";
+import { Server } from "@open-core/framework/server";
 import { IDENTITY_OPTIONS } from "./tokens";
 import { LocalAuthProvider as LocalAuthImpl } from "./providers/auth/local-auth.provider";
 import { CredentialsAuthProvider as CredentialsAuthImpl } from "./providers/auth/credentials-auth.provider";
 import { ApiAuthProvider as ApiAuthImpl } from "./providers/auth/api-auth.provider";
+import { AuthService } from "./auth.service";
 import { IdentityPrincipalProvider as PrincipalProviderImpl } from "./providers/principal/local-principal.provider";
 import { ApiPrincipalProvider as ApiPrincipalImpl } from "./providers/principal/api-principal.provider";
 import { AccountService as AccountServiceImpl } from "./services/account.service";
@@ -28,7 +29,10 @@ export var Identity;
         const container = globalThis.oc_container;
         if (!container)
             throwContainerError();
+        // Unregister existing if any and register new singleton
+        container.unregister(IdentityStoreContract);
         container.registerSingleton(IdentityStoreContract, store);
+        console.log(`[OpenCore-Identity] IdentityStore registered: ${store.name}`);
     }
     Identity.setIdentityStore = setIdentityStore;
     /**
@@ -41,18 +45,20 @@ export var Identity;
         const container = globalThis.oc_container;
         if (!container)
             throwContainerError();
+        container.unregister(RoleStoreContract);
         container.registerSingleton(RoleStoreContract, store);
+        console.log(`[OpenCore-Identity] RoleStore registered: ${store.name}`);
     }
     Identity.setRoleStore = setRoleStore;
     function throwContainerError() {
         throw new Error("[OpenCore-Identity] Global container (globalThis.oc_container) not found. " +
-            "Ensure the framework is initialized before installing plugins.");
+            "Ensure the framework is installed.");
     }
     /**
      * Installs the Identity plugin into the OpenCore Framework.
      *
-     * This function registers the necessary Authentication and Principal providers
-     * into the framework's SPI via `Server.setAuthProvider` and `Server.setPrincipalProvider`.
+      * This function registers the necessary Authentication service and Principal provider
+      * into the framework's SPI via dependency injection and `Server.setPrincipalProvider`.
      *
      * @param options - Configuration options for the identity system.
      *
@@ -80,23 +86,76 @@ export var Identity;
         // Register Internal Services (concrete classes as tokens)
         container.registerSingleton(AccountServiceImpl);
         container.registerSingleton(RoleServiceImpl);
-        // Configure Auth SPI based on mode
+        // Configure Auth Service based on mode
         if (options.auth.mode === "api") {
-            Server.setAuthProvider(ApiAuthImpl);
+            if (!options.auth.api?.baseUrl) {
+                throw new Error("[OpenCore-Identity] In 'api' auth mode, 'auth.api.baseUrl' is required.");
+            }
+            container.registerSingleton(AuthService, ApiAuthImpl);
         }
         else if (options.auth.mode === "credentials") {
-            Server.setAuthProvider(CredentialsAuthImpl);
+            container.registerSingleton(AuthService, CredentialsAuthImpl);
         }
         else {
-            Server.setAuthProvider(LocalAuthImpl);
+            container.registerSingleton(AuthService, LocalAuthImpl);
         }
         // Configure Principal SPI based on mode
         if (options.principal.mode === "api") {
+            if (!options.principal.api?.baseUrl) {
+                throw new Error("[OpenCore-Identity] In 'api' principal mode, 'principal.api.baseUrl' is required.");
+            }
             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/api-auth.provider.d.ts

@@ -1,25 +1,23 @@
-import { Server } from "@open-core/framework";
+import { Server } from "@open-core/framework/server";
 import type { IdentityOptions } from "../../types";
+import { AuthResult, AuthService } from "../../auth.service";
 /**
  * Authentication provider that delegates logic to an external HTTP API.
  *
- * This provider implements the framework's {@link Server.AuthProviderContract} by
- * performing network requests to a remote authentication service. It is suitable
- * for environments with a centralized user database or SSO.
+ * This provider performs HTTP requests to a remote authentication service.
+ * It is suitable for environments with a centralized user database or SSO.
  *
  * @injectable
  * @public
  */
-export declare class ApiAuthProvider extends Server.AuthProviderContract {
+export declare class ApiAuthProvider extends AuthService {
     private readonly options;
-    private readonly http;
     /**
      * Initializes a new instance of the ApiAuthProvider.
      *
      * @param options - Identity system configuration options.
-     * @param http - Framework HTTP service for remote communication.
      */
-    constructor(options: IdentityOptions, http: Server.HttpService);
+    constructor(options: IdentityOptions);
     /**
      * Authenticates a player by sending credentials to the external API.
      *
@@ -27,7 +25,7 @@ export declare class ApiAuthProvider extends Server.AuthProviderContract {
      * @param credentials - Authentication data (e.g., tokens, external IDs).
      * @returns A promise resolving to the remote authentication result.
      */
-    authenticate(player: Server.Player, credentials: Record<string, unknown>): Promise<Server.AuthResult>;
+    authenticate(player: Server.Player, credentials: Record<string, unknown>): Promise<AuthResult>;
     /**
      * Registers a player identity via the external API.
      *
@@ -35,18 +33,21 @@ export declare class ApiAuthProvider extends Server.AuthProviderContract {
      * @param credentials - Registration data.
      * @returns A promise resolving to the remote registration result.
      */
-    register(player: Server.Player, credentials: Record<string, unknown>): Promise<Server.AuthResult>;
+    register(player: Server.Player, credentials: Record<string, unknown>): Promise<AuthResult>;
     /**
      * Validates the player's remote session.
      *
      * @param player - The framework player entity.
      * @returns A promise resolving to the remote session validation result.
      */
-    validateSession(player: Server.Player): Promise<Server.AuthResult>;
+    validateSession(player: Server.Player): Promise<AuthResult>;
     /**
      * Notifies the external API that the player has logged out.
      *
      * @param player - The framework player entity.
      */
     logout(player: Server.Player): Promise<void>;
+    private requestAuth;
+    private resolveUrl;
+    private getAbortSignal;
 }