@open-core/identity 1.0.0 → 1.2.1

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

@@ -0,0 +1,164 @@
+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";
+import { IdentityStore, RoleStore } from "../../contracts";
+/**
+ * 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
+ */
+let IdentityPrincipalProvider = class IdentityPrincipalProvider extends Server.PrincipalProviderContract {
+    /**
+     * 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, accountStore, roleStore) {
+        super();
+        this.options = options;
+        this.accountStore = accountStore;
+        this.roleStore = roleStore;
+        /**
+         * In-memory cache for resolved principals.
+         * Key: clientId (number)
+         */
+        this.cache = new Map();
+        this.cacheTtl = options.principal.cacheTtl ?? 300000; // 5 minutes default
+    }
+    /**
+     * 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.
+     */
+    async getPrincipal(player) {
+        const clientId = player.clientID;
+        const cached = this.cache.get(clientId);
+        if (cached && cached.expiresAt > Date.now()) {
+            return cached.principal;
+        }
+        const linkedId = player.accountID;
+        if (!linkedId)
+            return null;
+        const principal = await this.resolvePrincipal(linkedId);
+        if (principal) {
+            this.cache.set(clientId, {
+                principal,
+                expiresAt: Date.now() + this.cacheTtl,
+            });
+        }
+        return principal;
+    }
+    /**
+     * Invalidates the cache and re-resolves the principal for a player.
+     *
+     * @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.
+     *
+     * @param linkedID - The linked account identifier.
+     * @returns A promise resolving to the principal or null.
+     */
+    async getPrincipalByLinkedID(linkedID) {
+        return this.resolvePrincipal(linkedID);
+    }
+    /**
+     * 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
+     */
+    async resolvePrincipal(linkedId) {
+        const account = await this.accountStore.findByLinkedId(linkedId);
+        if (!account)
+            return null;
+        let role;
+        if (this.options.principal.mode === "roles") {
+            role = this.options.principal.roles?.[account.roleName];
+        }
+        else if (this.roleStore) {
+            const dbRole = await this.roleStore.findByName(account.roleName);
+            if (dbRole)
+                role = dbRole;
+        }
+        if (!role) {
+            const defaultName = this.options.principal.defaultRole || "user";
+            role = this.options.principal.roles?.[defaultName];
+        }
+        if (!role)
+            return null;
+        const effectivePermissions = this.mergePermissions(role.permissions, account.customPermissions);
+        return {
+            id: account.linkedId,
+            name: role.displayName || role.name,
+            rank: role.rank,
+            permissions: effectivePermissions,
+            meta: {
+                accountId: account.id,
+                roleName: role.name,
+            },
+        };
+    }
+    /**
+     * 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
+     */
+    mergePermissions(base, overrides) {
+        const perms = new Set(base);
+        for (const override of overrides) {
+            if (override.startsWith("-")) {
+                perms.delete(override.substring(1));
+            }
+            else if (override.startsWith("+")) {
+                perms.add(override.substring(1));
+            }
+            else {
+                perms.add(override);
+            }
+        }
+        return Array.from(perms);
+    }
+};
+IdentityPrincipalProvider = __decorate([
+    injectable(),
+    __param(0, inject(IDENTITY_OPTIONS)),
+    __metadata("design:paramtypes", [Object, IdentityStore,
+        RoleStore])
+], IdentityPrincipalProvider);
+export { IdentityPrincipalProvider };

package/dist/repositories/account.repository.d.ts

@@ -1,4 +1,4 @@
-import { Server } from "@open-core/framework";
+import { Repository, type DatabaseContract } from "@open-core/framework/server";
 import type { Account } from "../entities/account.entity";
 import type { Role } from "../entities/role.entity";
 import type { CreateAccountInput, IdentifierType } from "../types";
@@ -21,10 +21,10 @@ interface AccountRow {
 /**
  * Repository for the accounts table.
  */
-export declare class AccountRepository extends Server.Repository<Account> {
-    protected readonly db: Server.DatabaseContract;
+export declare class AccountRepository extends Repository<Account> {
+    protected readonly db: DatabaseContract;
     protected tableName: string;
-    constructor(db: Server.DatabaseContract);
+    constructor(db: DatabaseContract);
     findByLinkedId(linkedId: string): Promise<Account | null>;
     findByIdentifier(type: IdentifierType, value: string): Promise<Account | null>;
     createAccount(input: CreateAccountInput): Promise<Account>;

package/dist/repositories/account.repository.js

@@ -1,11 +1,8 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AccountRepository = void 0;
-const framework_1 = require("@open-core/framework");
+import { Repository } from "@open-core/framework/server";
 /**
  * Repository for the accounts table.
  */
-class AccountRepository extends framework_1.Server.Repository {
+export class AccountRepository extends Repository {
     constructor(db) {
         super(db);
         this.db = db;
@@ -182,4 +179,3 @@ class AccountRepository extends framework_1.Server.Repository {
         }
     }
 }
-exports.AccountRepository = AccountRepository;

package/dist/repositories/role.repository.d.ts

@@ -1,4 +1,4 @@
-import { Server } from "@open-core/framework";
+import { Repository, type DatabaseContract } from "@open-core/framework/server";
 import type { Role } from "../entities/role.entity";
 interface RoleRow {
     id?: number;
@@ -13,10 +13,10 @@ interface RoleRow {
  * Repository for the roles table.
  * Manages CRUD operations for roles with custom queries for defaults and names.
  */
-export declare class RoleRepository extends Server.Repository<Role> {
-    protected readonly db: Server.DatabaseContract;
+export declare class RoleRepository extends Repository<Role> {
+    protected readonly db: DatabaseContract;
     protected tableName: string;
-    constructor(db: Server.DatabaseContract);
+    constructor(db: DatabaseContract);
     /**
      * Find a role by its internal name.
      *

package/dist/repositories/role.repository.js

@@ -1,12 +1,9 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RoleRepository = void 0;
-const framework_1 = require("@open-core/framework");
+import { Repository } from "@open-core/framework/server";
 /**
  * Repository for the roles table.
  * Manages CRUD operations for roles with custom queries for defaults and names.
  */
-class RoleRepository extends framework_1.Server.Repository {
+export class RoleRepository extends Repository {
     constructor(db) {
         super(db);
         this.db = db;
@@ -76,4 +73,3 @@ class RoleRepository extends framework_1.Server.Repository {
         };
     }
 }
-exports.RoleRepository = RoleRepository;

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

@@ -1,78 +1,73 @@
-import { Server } from "@open-core/framework";
-import type { Account } from "../entities/account.entity";
-import type { AccountIdentifiers, BanOptions, IdentifierType } from "../types";
-import { AccountRepository } from "../repositories/account.repository";
-import { RoleService } from "./role.service";
+import { IdentityStore } from "../contracts";
+import type { IdentityAccount, IdentityOptions } from "../types";
+/**
+ * High-level service for managing identity accounts and security policies.
+ *
+ * Provides a programmer-friendly API for account administration, including
+ * role assignment, permission overrides, and ban management.
+ *
+ * @public
+ * @injectable
+ */
 export declare class AccountService {
-    private readonly repo;
-    private readonly roleService;
-    private readonly config;
-    constructor(repo: AccountRepository, roleService: RoleService, config: Server.ConfigService);
-    findById(id: number): Promise<Account | null>;
-    findByLinkedId(linkedId: string): Promise<Account | null>;
-    findByIdentifier(type: IdentifierType, value: string): Promise<Account | null>;
-    findOrCreate(identifiers: AccountIdentifiers): Promise<{
-        account: Account;
-        isNew: boolean;
-    }>;
-    ban(accountId: number, options: BanOptions): Promise<void>;
-    unban(accountId: number): Promise<void>;
-    isBanExpired(account: Account): boolean;
+    private readonly store;
+    private readonly options;
+    constructor(store: IdentityStore, options: IdentityOptions);
     /**
-     * Add a custom permission to an account (override/additional to role).
+     * Retrieves an account by its unique numeric or internal ID.
      *
-     * @param accountId - Account ID
-     * @param permission - Permission string to add
+     * @param id - The internal account identifier.
+     * @returns A promise resolving to the account or null if not found.
      */
-    addCustomPermission(accountId: number, permission: string): Promise<void>;
+    findById(id: string): Promise<IdentityAccount | null>;
     /**
-     * Remove a custom permission from an account.
+     * Retrieves an account by its stable linked ID.
      *
-     * @param accountId - Account ID
-     * @param permission - Permission string to remove
+     * @param linkedId - The stable ID (UUID or external system ID).
+     * @returns A promise resolving to the account or null if not found.
      */
-    removeCustomPermission(accountId: number, permission: string): Promise<void>;
+    findByLinkedId(linkedId: string): Promise<IdentityAccount | null>;
     /**
-     * Get effective permissions for an account (role + custom).
+     * Assigns a security role to an account.
      *
-     * @param accountId - Account ID
-     * @returns Combined permissions array
+     * @param accountId - The linked ID of the account.
+     * @param roleName - Technical name of the role to assign.
      */
-    getEffectivePermissions(accountId: number): Promise<string[]>;
+    assignRole(accountId: string, roleName: string): Promise<void>;
     /**
-     * Assign a role to an account.
+     * Grants a custom permission override to an account.
      *
-     * @param accountId - Account ID
-     * @param roleId - Role ID to assign (null to remove role)
-     */
-    assignRole(accountId: number, roleId: number | null): Promise<void>;
-    /**
-     * Combine role permissions with account custom permissions.
-     * Custom permissions starting with '-' negate the base permission.
+     * This override takes precedence over role permissions.
+     * Use the `+` prefix for clarity (optional).
      *
-     * @param role - Role with base permissions
-     * @param customPerms - Account custom permissions
-     * @returns Combined permissions array
+     * @param accountId - The linked ID of the account.
+     * @param permission - The permission string to grant.
      */
-    private combinePermissions;
-    touchLastLogin(accountId: number, date?: Date): Promise<void>;
-    private lookupExisting;
-    private identifierPriority;
+    addCustomPermission(accountId: string, permission: string): Promise<void>;
     /**
-     * Find account by username (for credentials auth)
-     * Note: This is a basic implementation. For production, add an index on username.
+     * 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 permission - The permission string to remove or revoke.
      */
-    findByUsername(_username: string): Promise<Account | null>;
+    removeCustomPermission(accountId: string, permission: string): Promise<void>;
     /**
-     * Update account identifiers (for credentials auth identifier merging)
+     * 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.
      */
-    updateIdentifiers(): Promise<void>;
+    ban(accountId: string, options?: {
+        reason?: string;
+        durationMs?: number;
+    }): Promise<void>;
     /**
-     * Create account with credentials (for CredentialsAuthProvider)
+     * Lifts an active ban from an account.
+     *
+     * @param accountId - The linked ID of the account.
      */
-    createWithCredentials(input: {
-        username: string;
-        passwordHash: string;
-        identifiers: AccountIdentifiers;
-    }): Promise<Account>;
+    unban(accountId: string): Promise<void>;
 }

package/dist/services/account.service.js

@@ -1,4 +1,3 @@
-"use strict";
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -8,200 +7,115 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AccountService = void 0;
-const tsyringe_1 = require("tsyringe");
-const framework_1 = require("@open-core/framework");
-const crypto_1 = require("crypto");
-const account_repository_1 = require("../repositories/account.repository");
-const role_service_1 = require("./role.service");
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject } from "tsyringe";
+import { IDENTITY_OPTIONS } from "../tokens";
+import { IdentityStore } from "../contracts";
+/**
+ * High-level service for managing identity accounts and security policies.
+ *
+ * Provides a programmer-friendly API for account administration, including
+ * role assignment, permission overrides, and ban management.
+ *
+ * @public
+ * @injectable
+ */
 let AccountService = class AccountService {
-    constructor(repo, roleService, config) {
-        this.repo = repo;
-        this.roleService = roleService;
-        this.config = config;
+    constructor(store, options) {
+        this.store = store;
+        this.options = options;
     }
+    /**
+     * Retrieves an account by its unique numeric or internal ID.
+     *
+     * @param id - The internal account identifier.
+     * @returns A promise resolving to the account or null if not found.
+     */
     async findById(id) {
-        return this.repo.findById(id);
+        return this.store.findByLinkedId(id); // Using linkedId as the primary public handle
     }
+    /**
+     * Retrieves an account by its stable linked ID.
+     *
+     * @param linkedId - The stable ID (UUID or external system ID).
+     * @returns A promise resolving to the account or null if not found.
+     */
     async findByLinkedId(linkedId) {
-        return this.repo.findByLinkedId(linkedId);
-    }
-    async findByIdentifier(type, value) {
-        return this.repo.findByIdentifier(type, value);
+        return this.store.findByLinkedId(linkedId);
     }
-    async findOrCreate(identifiers) {
-        const existing = await this.lookupExisting(identifiers);
-        if (existing) {
-            return { account: existing, isNew: false };
-        }
-        // Get default role for new accounts
-        const defaultRole = await this.roleService.getDefaultRole();
-        // Auto-generate linkedId by default (UUID format for local accounts)
-        const created = await this.repo.createAccount({
-            linkedId: (0, crypto_1.randomUUID)(),
-            externalSource: "local",
-            license: identifiers.license ?? null,
-            discord: identifiers.discord ?? null,
-            steam: identifiers.steam ?? null,
-            username: null,
-            roleId: defaultRole?.id ?? null,
-        });
-        return { account: created, isNew: true };
-    }
-    async ban(accountId, options) {
-        const expires = options.durationMs
-            ? new Date(Date.now() + options.durationMs)
-            : null;
-        await this.repo.setBan(accountId, true, options.reason ?? "Banned", expires);
-    }
-    async unban(accountId) {
-        await this.repo.setBan(accountId, false, null, null);
-    }
-    isBanExpired(account) {
-        if (!account.banned)
-            return false;
-        if (!account.banExpires)
-            return false;
-        return account.banExpires.getTime() <= Date.now();
+    /**
+     * Assigns a security role to an account.
+     *
+     * @param accountId - The linked ID of the account.
+     * @param roleName - Technical name of the role to assign.
+     */
+    async assignRole(accountId, roleName) {
+        await this.store.update(accountId, { roleName });
     }
     /**
-     * Add a custom permission to an account (override/additional to role).
+     * Grants a custom permission override to an account.
+     *
+     * This override takes precedence over role permissions.
+     * Use the `+` prefix for clarity (optional).
      *
-     * @param accountId - Account ID
-     * @param permission - Permission string to add
+     * @param accountId - The linked ID of the account.
+     * @param permission - The permission string to grant.
      */
     async addCustomPermission(accountId, permission) {
-        const account = await this.repo.findById(accountId);
+        const account = await this.store.findByLinkedId(accountId);
         if (!account)
             return;
-        const permissions = new Set(account.customPermissions ?? []);
+        const permissions = new Set(account.customPermissions);
         permissions.add(permission);
-        await this.repo.updateCustomPermissions(accountId, Array.from(permissions));
+        await this.store.update(accountId, {
+            customPermissions: Array.from(permissions),
+        });
     }
     /**
-     * Remove a custom permission from an account.
+     * Revokes a custom permission override.
+     *
+     * To explicitly deny a permission that a role might grant, use the `-` prefix
+     * (e.g., `-chat.use`).
      *
-     * @param accountId - Account ID
-     * @param permission - Permission string to remove
+     * @param accountId - The linked ID of the account.
+     * @param permission - The permission string to remove or revoke.
      */
     async removeCustomPermission(accountId, permission) {
-        const account = await this.repo.findById(accountId);
+        const account = await this.store.findByLinkedId(accountId);
         if (!account)
             return;
-        const filtered = (account.customPermissions ?? []).filter((p) => p !== permission && p !== `-${permission}`);
-        await this.repo.updateCustomPermissions(accountId, filtered);
-    }
-    /**
-     * Get effective permissions for an account (role + custom).
-     *
-     * @param accountId - Account ID
-     * @returns Combined permissions array
-     */
-    async getEffectivePermissions(accountId) {
-        const result = await this.repo.findByIdWithRole(accountId);
-        if (!result)
-            return [];
-        return this.combinePermissions(result.role, result.account.customPermissions);
+        const permissions = new Set(account.customPermissions);
+        permissions.delete(permission);
+        await this.store.update(accountId, {
+            customPermissions: Array.from(permissions),
+        });
     }
     /**
-     * Assign a role to an account.
+     * Prohibits an account from connecting to the server.
      *
-     * @param accountId - Account ID
-     * @param roleId - Role ID to assign (null to remove role)
+     * @param accountId - The linked ID of the account.
+     * @param options - Ban details including optional reason and duration.
      */
-    async assignRole(accountId, roleId) {
-        await this.repo.updateRole(accountId, roleId);
+    async ban(accountId, options = {}) {
+        const expiresAt = options.durationMs
+            ? new Date(Date.now() + options.durationMs)
+            : null;
+        await this.store.setBan(accountId, true, options.reason, expiresAt);
     }
     /**
-     * Combine role permissions with account custom permissions.
-     * Custom permissions starting with '-' negate the base permission.
+     * Lifts an active ban from an account.
      *
-     * @param role - Role with base permissions
-     * @param customPerms - Account custom permissions
-     * @returns Combined permissions array
+     * @param accountId - The linked ID of the account.
      */
-    combinePermissions(role, customPerms) {
-        const base = new Set(role?.permissions ?? []);
-        for (const perm of customPerms) {
-            if (perm.startsWith("-")) {
-                // Negation: remove the base permission
-                base.delete(perm.slice(1));
-            }
-            else {
-                // Addition: add custom permission
-                base.add(perm);
-            }
-        }
-        return Array.from(base);
-    }
-    async touchLastLogin(accountId, date = new Date()) {
-        await this.repo.updateLastLogin(accountId, date);
-    }
-    async lookupExisting(identifiers) {
-        const ordered = this.identifierPriority();
-        for (const key of ordered) {
-            const value = identifiers[key];
-            if (!value)
-                continue;
-            const found = await this.repo.findByIdentifier(key, value);
-            if (found)
-                return found;
-        }
-        // Fallback: try any provided identifiers
-        for (const [key, value] of Object.entries(identifiers)) {
-            if (!value)
-                continue;
-            const found = await this.repo.findByIdentifier(key, value);
-            if (found)
-                return found;
-        }
-        return null;
-    }
-    identifierPriority() {
-        const fromConfig = this.config.get("identity_primary_identifier", "license");
-        const base = ["license", "discord", "steam"];
-        return [fromConfig, ...base.filter((id) => id !== fromConfig)];
-    }
-    /**
-     * Find account by username (for credentials auth)
-     * Note: This is a basic implementation. For production, add an index on username.
-     */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    async findByUsername(_username) {
-        // TODO: Add findByUsername method to AccountRepository for better performance
-        // For now, this is a placeholder that credentials auth will need
-        throw new Error("findByUsername not implemented - add to AccountRepository for credentials auth");
-    }
-    /**
-     * Update account identifiers (for credentials auth identifier merging)
-     */
-    async updateIdentifiers() {
-        // This is a placeholder - in production you'd want a proper update method
-        // For now, credentials auth can work without this
-        console.warn("updateIdentifiers not fully implemented - identifiers not merged");
-    }
-    /**
-     * Create account with credentials (for CredentialsAuthProvider)
-     */
-    async createWithCredentials(input) {
-        const defaultRole = await this.roleService.getDefaultRole();
-        // Note: This creates an account without password_hash field
-        // You'll need to add password_hash to Account entity and migration 005
-        return this.repo.createAccount({
-            linkedId: (0, crypto_1.randomUUID)(),
-            externalSource: "credentials",
-            username: input.username,
-            license: input.identifiers.license ?? null,
-            discord: input.identifiers.discord ?? null,
-            steam: input.identifiers.steam ?? null,
-            roleId: defaultRole?.id ?? null,
-        });
+    async unban(accountId) {
+        await this.store.setBan(accountId, false);
     }
 };
-exports.AccountService = AccountService;
-exports.AccountService = AccountService = __decorate([
-    (0, tsyringe_1.injectable)(),
-    __metadata("design:paramtypes", [account_repository_1.AccountRepository,
-        role_service_1.RoleService, framework_1.Server.ConfigService])
+AccountService = __decorate([
+    injectable(),
+    __param(1, inject(IDENTITY_OPTIONS)),
+    __metadata("design:paramtypes", [IdentityStore, Object])
 ], AccountService);
+export { AccountService };