@open-core/identity

Enterprise-grade identity, authentication, and authorization plugin for the OpenCore Framework.

Documentation Index

• Architecture & Dependency Injection - Learn about constructor injection and DI.
• Authentication Modes - Details on local, credentials, and api auth.
• Principal Modes - Details on roles, db, and api authorization.
• Implementing Contracts - 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.

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):

   import { Identity, IdentityStore } from "@open-core/identity";
   
   class MyStore extends IdentityStore {
     /* ... */
   }
   
   // Register it before installation
   Identity.setIdentityStore(MyStore);

2. Install the Plugin:

   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.

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.

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.

Identity.install({
  auth: {
    mode: "api",
    primaryIdentifier: "license",
    api: {
      baseUrl: "https://auth.example.com",
      authPath: "/auth",
      registerPath: "/register",
      sessionPath: "/session",
      logoutPath: "/logout",
    },
  },
  // ...
});

Usage Example

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