@open-core/identity 1.2.0 → 1.2.2

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

@@ -0,0 +1,149 @@
+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);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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 { Server } from "@open-core/framework";
+import { v4 as uuidv4 } from "uuid";
+import { IDENTITY_OPTIONS } from "../../tokens";
+import { IdentityStore } from "../../contracts";
+import bcrypt from "bcryptjs";
+/**
+ * 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.
+ *
+ * @injectable
+ * @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) {
+        super();
+        this.options = options;
+        this.store = store;
+        /** Cost factor for bcrypt hashing */
+        this.saltRounds = 10;
+    }
+    /**
+     * Authenticates a player using a username and password.
+     *
+     * @param player - The framework player entity.
+     * @param credentials - Object containing `username` and `password` strings.
+     * @returns A promise resolving to the authentication result.
+     */
+    async authenticate(player, credentials) {
+        const username = credentials.username;
+        const password = credentials.password;
+        if (!username || !password) {
+            return { success: false, error: "Username and password are required" };
+        }
+        const account = await this.store.findByUsername(username);
+        if (!account) {
+            return { success: false, error: "Invalid credentials" };
+        }
+        const passwordHash = account.passwordHash;
+        if (!passwordHash) {
+            return { success: false, error: "Account has no password set" };
+        }
+        const isValid = await bcrypt.compare(password, passwordHash);
+        if (!isValid) {
+            return { success: false, error: "Invalid credentials" };
+        }
+        if (this.isBanned(account)) {
+            return { success: false, error: account.banReason ?? "Account is banned" };
+        }
+        player.linkAccount(account.linkedId);
+        return { success: true, accountID: account.linkedId };
+    }
+    /**
+     * Registers a new account with a username and password.
+     *
+     * @param player - The framework player entity.
+     * @param credentials - Object containing `username` and `password` strings.
+     * @returns A promise resolving to the registration result.
+     */
+    async register(player, credentials) {
+        const username = credentials.username;
+        const password = credentials.password;
+        if (!username || !password) {
+            return { success: false, error: "Username and password are required" };
+        }
+        const existing = await this.store.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({
+            username,
+            passwordHash,
+            identifier: primaryIdentifier,
+            linkedId: uuidv4(),
+            roleName: this.options.principal.defaultRole || "user",
+        });
+        player.linkAccount(account.linkedId);
+        return { success: true, accountID: account.linkedId, isNewAccount: true };
+    }
+    /**
+     * 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.
+     */
+    async validateSession(player) {
+        const accountId = player.accountID;
+        if (!accountId)
+            return { success: false, error: "Not authenticated" };
+        const account = await this.store.findByLinkedId(accountId);
+        if (!account || this.isBanned(account)) {
+            return { success: false, error: "Session invalid or account banned" };
+        }
+        return { success: true, accountID: account.linkedId };
+    }
+    /**
+     * Performs logout logic for the player.
+     *
+     * @param player - The framework player entity.
+     */
+    async logout(player) {
+        // Session state is managed by the framework.
+    }
+    /**
+     * Internal helper to determine if an account is currently prohibited.
+     *
+     * @param account - The account to check.
+     * @returns True if the account is banned and the ban hasn't expired.
+     * @internal
+     */
+    isBanned(account) {
+        if (!account.isBanned)
+            return false;
+        if (account.banExpiresAt && account.banExpiresAt < new Date()) {
+            return false;
+        }
+        return true;
+    }
+};
+CredentialsAuthProvider = __decorate([
+    injectable(),
+    __param(0, inject(IDENTITY_OPTIONS)),
+    __metadata("design:paramtypes", [Object, IdentityStore])
+], CredentialsAuthProvider);
+export { CredentialsAuthProvider };

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

@@ -0,0 +1,82 @@
+import { Server } from "@open-core/framework";
+import { IdentityStore } from "../../contracts";
+import type { IdentityOptions } from "../../types";
+/**
+ * Result structure for authentication operations.
+ *
+ * @public
+ */
+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;
+}
+/**
+ * Local Authentication Provider for the OpenCore Identity System.
+ *
+ * This provider implements the framework's {@link Server.AuthProviderContract} and
+ * handles the logic for local (identifier-based) authentication strategies.
+ *
+ * @injectable
+ * @public
+ */
+export declare class LocalAuthProvider extends Server.AuthProviderContract {
+    private readonly options;
+    private readonly store;
+    private readonly config;
+    /**
+     * Initializes a new instance of the IdentityAuthProvider.
+     *
+     * @param options - Identity system configuration options.
+     * @param store - Persistence layer for account data.
+     * @param config - Framework configuration service.
+     */
+    constructor(options: IdentityOptions, store: IdentityStore, config: Server.ConfigService);
+    /**
+     * Authenticates a player based on the configured strategy.
+     *
+     * @param player - The player to authenticate.
+     * @param credentials - Optional credentials (used in API or credentials mode).
+     * @returns A promise resolving to an {@link AuthResult}.
+     */
+    authenticate(player: Server.Player, credentials: Record<string, unknown>): Promise<AuthResult>;
+    /**
+     * Registers a new player identity.
+     *
+     * @param player - The player to register.
+     * @param credentials - Registration data.
+     * @returns A promise resolving to an {@link AuthResult}.
+     */
+    register(player: Server.Player, credentials: Record<string, unknown>): Promise<AuthResult>;
+    /**
+     * Validates the current session for a player.
+     *
+     * @param player - The player whose session to validate.
+     * @returns A promise resolving to an {@link AuthResult}.
+     */
+    validateSession(player: Server.Player): Promise<AuthResult>;
+    /**
+     * Clears the authentication state for a player.
+     *
+     * @param player - The player to log out.
+     */
+    logout(player: Server.Player): Promise<void>;
+    /**
+     * Internal implementation for local authentication strategy.
+     *
+     * @internal
+     */
+    private authenticateLocally;
+    /**
+     * Internal implementation for API-based authentication strategy.
+     *
+     * @internal
+     */
+    private authenticateViaApi;
+}
+export {};

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

@@ -0,0 +1,151 @@
+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);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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 { Server } from "@open-core/framework";
+import { v4 as uuidv4 } from "uuid";
+import { IDENTITY_OPTIONS } from "../../tokens";
+import { IdentityStore } from "../../contracts";
+/**
+ * Local Authentication Provider for the OpenCore Identity System.
+ *
+ * This provider implements the framework's {@link Server.AuthProviderContract} and
+ * handles the logic for local (identifier-based) authentication strategies.
+ *
+ * @injectable
+ * @public
+ */
+let LocalAuthProvider = class LocalAuthProvider extends Server.AuthProviderContract {
+    /**
+     * Initializes a new instance of the IdentityAuthProvider.
+     *
+     * @param options - Identity system configuration options.
+     * @param store - Persistence layer for account data.
+     * @param config - Framework configuration service.
+     */
+    constructor(options, store, config) {
+        super();
+        this.options = options;
+        this.store = store;
+        this.config = config;
+    }
+    /**
+     * Authenticates a player based on the configured strategy.
+     *
+     * @param player - The player to authenticate.
+     * @param credentials - Optional credentials (used in API or credentials mode).
+     * @returns A promise resolving to an {@link AuthResult}.
+     */
+    async authenticate(player, credentials) {
+        try {
+            if (this.options.auth.mode === "api") {
+                return await this.authenticateViaApi(player, credentials);
+            }
+            return await this.authenticateLocally(player);
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : "Internal authentication error",
+            };
+        }
+    }
+    /**
+     * Registers a new player identity.
+     *
+     * @param player - The player to register.
+     * @param credentials - Registration data.
+     * @returns A promise resolving to an {@link AuthResult}.
+     */
+    async register(player, credentials) {
+        return { success: false, error: "Registration not implemented in current mode" };
+    }
+    /**
+     * Validates the current session for a player.
+     *
+     * @param player - The player whose session to validate.
+     * @returns A promise resolving to an {@link AuthResult}.
+     */
+    async validateSession(player) {
+        const accountId = player.accountID;
+        if (!accountId)
+            return { success: false, error: "No active session" };
+        const account = await this.store.findByLinkedId(accountId);
+        if (!account)
+            return { success: false, error: "Account no longer exists" };
+        if (account.isBanned && (!account.banExpiresAt || account.banExpiresAt > new Date())) {
+            return { success: false, error: account.banReason ?? "Account is banned" };
+        }
+        return { success: true, accountID: account.linkedId };
+    }
+    /**
+     * Clears the authentication state for a player.
+     *
+     * @param player - The player to log out.
+     */
+    async logout(player) {
+        // Session state is managed by the framework's player entity.
+    }
+    /**
+     * Internal implementation for local authentication strategy.
+     *
+     * @internal
+     */
+    async authenticateLocally(player) {
+        const primaryType = this.options.auth.primaryIdentifier || "license";
+        const identifiers = player.getIdentifiers();
+        const identifierValue = identifiers.find(id => id.startsWith(`${primaryType}:`));
+        if (!identifierValue) {
+            return { success: false, error: `Missing required identifier: ${primaryType}` };
+        }
+        let account = await this.store.findByIdentifier(identifierValue);
+        let isNew = false;
+        if (!account) {
+            if (this.options.auth.autoCreate === false) {
+                return { success: false, error: "Account not found and auto-create is disabled" };
+            }
+            account = await this.store.create({
+                identifier: identifierValue,
+                linkedId: uuidv4(),
+                roleName: "user",
+            });
+            isNew = true;
+        }
+        if (account.isBanned) {
+            if (account.banExpiresAt && account.banExpiresAt < new Date()) {
+                await this.store.setBan(account.id, false);
+            }
+            else {
+                return {
+                    success: false,
+                    error: account.banReason ?? "Account is banned",
+                };
+            }
+        }
+        player.linkAccount(account.linkedId);
+        return { success: true, accountID: account.linkedId, isNewAccount: isNew };
+    }
+    /**
+     * Internal implementation for API-based authentication strategy.
+     *
+     * @internal
+     */
+    async authenticateViaApi(player, credentials) {
+        return { success: false, error: "API Auth Mode not yet fully implemented" };
+    }
+};
+LocalAuthProvider = __decorate([
+    injectable(),
+    __param(0, inject(IDENTITY_OPTIONS)),
+    __metadata("design:paramtypes", [Object, IdentityStore, Server.ConfigService])
+], LocalAuthProvider);
+export { LocalAuthProvider };

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

@@ -0,0 +1 @@
+"use strict";

package/dist/providers/principal/api-principal.provider.d.ts

@@ -0,0 +1,50 @@
+import { Server } from "@open-core/framework";
+import type { IdentityOptions } from "../../types";
+/**
+ * Principal provider that resolves roles and permissions from an external HTTP API.
+ *
+ * This provider implements the framework's {@link Server.PrincipalProviderContract} by
+ * performing network requests to a remote service. It includes an in-memory cache
+ * to optimize frequent authorization checks.
+ *
+ * @injectable
+ * @public
+ */
+export declare class ApiPrincipalProvider extends Server.PrincipalProviderContract {
+    private readonly options;
+    private readonly http;
+    /**
+     * In-memory cache for resolved principals.
+     * Key: clientId (number)
+     */
+    private readonly cache;
+    /** Cache TTL in milliseconds */
+    private readonly cacheTtl;
+    /**
+     * Initializes a new instance of the ApiPrincipalProvider.
+     *
+     * @param options - Identity system configuration options.
+     * @param http - Framework HTTP service for remote communication.
+     */
+    constructor(options: IdentityOptions, http: Server.HttpService);
+    /**
+     * Resolves the Principal for a connected player via external API.
+     *
+     * @param player - The framework player entity.
+     * @returns A promise resolving to the {@link Server.Principal} or null if not authenticated.
+     */
+    getPrincipal(player: Server.Player): Promise<Server.Principal | null>;
+    /**
+     * Forces a refresh of the cached principal data from the API.
+     *
+     * @param player - The player whose principal should be refreshed.
+     */
+    refreshPrincipal(player: Server.Player): Promise<void>;
+    /**
+     * Resolves a principal for offline workflows using a stable account ID via API.
+     *
+     * @param linkedID - The linked account identifier.
+     * @returns A promise resolving to the principal or null.
+     */
+    getPrincipalByLinkedID(linkedID: string): Promise<Server.Principal | null>;
+}

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

@@ -0,0 +1,84 @@
+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);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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 { Server } from "@open-core/framework";
+import { IDENTITY_OPTIONS } from "../../tokens";
+/**
+ * Principal provider that resolves roles and permissions from an external HTTP API.
+ *
+ * This provider implements the framework's {@link Server.PrincipalProviderContract} by
+ * performing network requests to a remote service. It includes an in-memory cache
+ * to optimize frequent authorization checks.
+ *
+ * @injectable
+ * @public
+ */
+let ApiPrincipalProvider = class ApiPrincipalProvider extends Server.PrincipalProviderContract {
+    /**
+     * Initializes a new instance of the ApiPrincipalProvider.
+     *
+     * @param options - Identity system configuration options.
+     * @param http - Framework HTTP service for remote communication.
+     */
+    constructor(options, http) {
+        super();
+        this.options = options;
+        this.http = http;
+        /**
+         * In-memory cache for resolved principals.
+         * Key: clientId (number)
+         */
+        this.cache = new Map();
+        this.cacheTtl = options.principal.cacheTtl ?? 300000;
+    }
+    /**
+     * Resolves the Principal for a connected player via external API.
+     *
+     * @param player - The framework player entity.
+     * @returns A promise resolving to the {@link Server.Principal} or null if not authenticated.
+     */
+    async getPrincipal(player) {
+        const cached = this.cache.get(player.clientID);
+        if (cached && cached.expiresAt > Date.now())
+            return cached.principal;
+        const linkedId = player.accountID;
+        if (!linkedId)
+            return null;
+        // Placeholder: Implementation would use this.http.get(...) 
+        return null;
+    }
+    /**
+     * Forces a refresh of the cached principal data from the API.
+     *
+     * @param player - The player whose principal should be refreshed.
+     */
+    async refreshPrincipal(player) {
+        this.cache.delete(player.clientID);
+        await this.getPrincipal(player);
+    }
+    /**
+     * Resolves a principal for offline workflows using a stable account ID via API.
+     *
+     * @param linkedID - The linked account identifier.
+     * @returns A promise resolving to the principal or null.
+     */
+    async getPrincipalByLinkedID(linkedID) {
+        return null;
+    }
+};
+ApiPrincipalProvider = __decorate([
+    injectable(),
+    __param(0, inject(IDENTITY_OPTIONS)),
+    __metadata("design:paramtypes", [Object, Server.HttpService])
+], ApiPrincipalProvider);
+export { ApiPrincipalProvider };

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

@@ -0,0 +1,77 @@
+import { Server } from "@open-core/framework";
+import { IdentityStore, RoleStore } from "../../contracts";
+import type { IdentityOptions } from "../../types";
+/**
+ * Authorization provider implementation for the OpenCore Framework.
+ *
+ * This provider resolves player principals (roles and permissions) by
+ * interacting with the configured {@link IdentityStore} and {@link RoleStore}.
+ * It includes a high-performance in-memory cache to minimize database
+ * overhead during frequent security checks (e.g., in `@Guard` decorators).
+ *
+ * @injectable
+ * @public
+ */
+export declare class IdentityPrincipalProvider extends Server.PrincipalProviderContract {
+    private readonly options;
+    private readonly accountStore;
+    private readonly roleStore?;
+    /**
+     * In-memory cache for resolved principals.
+     * Key: clientId (number)
+     */
+    private readonly cache;
+    /** Cache TTL in milliseconds */
+    private readonly cacheTtl;
+    /**
+     * Initializes a new instance of the IdentityPrincipalProvider.
+     *
+     * @param options - Identity system configuration options.
+     * @param accountStore - Persistence layer for account data.
+     * @param roleStore - Optional persistence layer for dynamic roles.
+     */
+    constructor(options: IdentityOptions, accountStore: IdentityStore, roleStore?: RoleStore | undefined);
+    /**
+     * Resolves the security Principal for a connected player.
+     *
+     * This method first checks the internal cache. If missing or expired,
+     * it resolves the account and its effective permissions.
+     *
+     * @param player - The framework player entity.
+     * @returns A promise resolving to the {@link Server.Principal} or null if not authenticated.
+     */
+    getPrincipal(player: Server.Player): Promise<Server.Principal | null>;
+    /**
+     * Invalidates the cache and re-resolves the principal for a player.
+     *
+     * @param player - The player whose principal should be refreshed.
+     */
+    refreshPrincipal(player: Server.Player): Promise<void>;
+    /**
+     * Resolves a principal for offline workflows using a stable account ID.
+     *
+     * @param linkedID - The linked account identifier.
+     * @returns A promise resolving to the principal or null.
+     */
+    getPrincipalByLinkedID(linkedID: string): Promise<Server.Principal | null>;
+    /**
+     * Internal logic to resolve effective permissions and construct the Principal.
+     *
+     * @param linkedId - The stable account ID.
+     * @returns Resolves the role, merges permissions, and returns the Principal.
+     * @internal
+     */
+    private resolvePrincipal;
+    /**
+     * Merges role-based permissions with account-specific overrides.
+     *
+     * Overrides starting with '-' are removed, and those starting with '+'
+     * (or without prefix) are added to the final set.
+     *
+     * @param base - Base permissions from the role.
+     * @param overrides - Custom overrides from the account.
+     * @returns The unified list of effective permissions.
+     * @internal
+     */
+    private mergePermissions;
+}