@open-core/identity 1.2.6 → 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/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,18 +86,24 @@ 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).");

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;
 }

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

@@ -11,29 +11,26 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { injectable, inject } from "tsyringe";
-import { Server } from "@open-core/framework";
 import { IDENTITY_OPTIONS } from "../../tokens";
+import { 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
  */
-let ApiAuthProvider = class ApiAuthProvider extends Server.AuthProviderContract {
+let ApiAuthProvider = class ApiAuthProvider extends AuthService {
     /**
      * Initializes a new instance of the ApiAuthProvider.
      *
      * @param options - Identity system configuration options.
-     * @param http - Framework HTTP service for remote communication.
      */
-    constructor(options, http) {
+    constructor(options) {
         super();
         this.options = options;
-        this.http = http;
     }
     /**
      * Authenticates a player by sending credentials to the external API.
@@ -43,8 +40,7 @@ let ApiAuthProvider = class ApiAuthProvider extends Server.AuthProviderContract
      * @returns A promise resolving to the remote authentication result.
      */
     async authenticate(player, credentials) {
-        // Placeholder: Implementation would use this.http.post(...)
-        return { success: false, error: "API Auth implementation pending" };
+        return this.requestAuth("authenticate", player, credentials);
     }
     /**
      * Registers a player identity via the external API.
@@ -54,7 +50,7 @@ let ApiAuthProvider = class ApiAuthProvider extends Server.AuthProviderContract
      * @returns A promise resolving to the remote registration result.
      */
     async register(player, credentials) {
-        return { success: false, error: "API Registration implementation pending" };
+        return this.requestAuth("register", player, credentials);
     }
     /**
      * Validates the player's remote session.
@@ -63,7 +59,7 @@ let ApiAuthProvider = class ApiAuthProvider extends Server.AuthProviderContract
      * @returns A promise resolving to the remote session validation result.
      */
     async validateSession(player) {
-        return { success: false, error: "API session validation pending" };
+        return this.requestAuth("session", player, {});
     }
     /**
      * Notifies the external API that the player has logged out.
@@ -71,12 +67,90 @@ let ApiAuthProvider = class ApiAuthProvider extends Server.AuthProviderContract
      * @param player - The framework player entity.
      */
     async logout(player) {
-        // API logout logic
+        const result = await this.requestAuth("logout", player, {});
+        if (result.success) {
+            player.unlinkAccount();
+        }
+    }
+    async requestAuth(action, player, credentials) {
+        const config = this.options.auth.api;
+        if (!config?.baseUrl) {
+            return { success: false, error: "API auth is not configured" };
+        }
+        const identifiers = player.getPlayerIdentifiers();
+        const primaryIdentifier = this.options.auth.primaryIdentifier || "license";
+        const primary = identifiers.find((identifier) => identifier.type === primaryIdentifier);
+        const payload = {
+            action,
+            accountId: player.accountID ?? null,
+            primaryIdentifier: primary?.value ?? null,
+            identifiers: identifiers.map((identifier) => ({
+                type: identifier.type,
+                value: identifier.value,
+            })),
+            credentials,
+        };
+        try {
+            const response = await fetch(this.resolveUrl(config, action), {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    ...config.headers,
+                },
+                body: JSON.stringify(payload),
+                signal: this.getAbortSignal(config.timeoutMs),
+            });
+            if (!response.ok) {
+                return {
+                    success: false,
+                    error: `API auth failed (${response.status})`,
+                };
+            }
+            const data = (await response.json());
+            if (!data.success || !data.accountId) {
+                return {
+                    success: false,
+                    error: data.error ?? "Authentication rejected",
+                };
+            }
+            if (action !== "logout") {
+                player.linkAccount(String(data.accountId));
+            }
+            return {
+                success: true,
+                accountID: String(data.accountId),
+                isNewAccount: data.isNewAccount,
+                account: data.account,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : "API auth error",
+            };
+        }
+    }
+    resolveUrl(config, action) {
+        const base = config.baseUrl.replace(/\/$/, "");
+        const pathMap = {
+            authenticate: config.authPath ?? "/auth",
+            register: config.registerPath ?? "/register",
+            session: config.sessionPath ?? "/session",
+            logout: config.logoutPath ?? "/logout",
+        };
+        return `${base}${pathMap[action]}`;
+    }
+    getAbortSignal(timeoutMs) {
+        if (!timeoutMs || timeoutMs <= 0)
+            return undefined;
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(), timeoutMs);
+        return controller.signal;
     }
 };
 ApiAuthProvider = __decorate([
     injectable(),
     __param(0, inject(IDENTITY_OPTIONS)),
-    __metadata("design:paramtypes", [Object, Server.HttpService])
+    __metadata("design:paramtypes", [Object])
 ], ApiAuthProvider);
 export { ApiAuthProvider };

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

@@ -1,21 +1,21 @@
-import { Server } from "@open-core/framework";
+import { Server } from "@open-core/framework/server";
 import { IdentityStore, RoleStore } from "../../contracts";
+import { AuthResult, AuthService } from "../../auth.service";
 /**
  * Authentication provider for username and password credentials.
  *
- * This provider implements the framework's {@link Server.AuthProviderContract} using
- * bcrypt for password hashing and validation. It requires an implementation
- * of {@link IdentityStore} that supports username-based lookups.
+ * This provider uses bcrypt for password hashing and validation. It requires
+ * an implementation of {@link IdentityStore} that supports username lookups.
  *
  * @injectable
  * @public
  */
-export declare class CredentialsAuthProvider extends Server.AuthProviderContract {
+export declare class CredentialsAuthProvider extends AuthService {
     private readonly accountStore;
     private readonly roleStore;
     /** Cost factor for bcrypt hashing */
     private readonly saltRounds;
-    constructor(accountStore: IdentityStore<string, string, string>, roleStore: RoleStore<string>);
+    constructor(accountStore: IdentityStore, roleStore: RoleStore);
     /**
      * Authenticates a player using a username and password.
      *
@@ -23,7 +23,7 @@ export declare class CredentialsAuthProvider extends Server.AuthProviderContract
      * @param credentials - Object containing `username` and `password` strings.
      * @returns A promise resolving to the 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 new account with a username and password.
      *
@@ -31,14 +31,14 @@ export declare class CredentialsAuthProvider extends Server.AuthProviderContract
      * @param credentials - Object containing `username` and `password` strings.
      * @returns A promise resolving to the registration result.
      */
-    register(player: Server.Player, credentials: Record<string, unknown>): Promise<Server.AuthResult>;
+    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.
      */
-    validateSession(player: Server.Player): Promise<Server.AuthResult>;
+    validateSession(player: Server.Player): Promise<AuthResult>;
     /**
      * Performs logout logic for the player.
      *