@astralibx/staff-engine 0.2.0 → 0.2.2

package/README.md

@@ -70,6 +70,20 @@ app.listen(3000);
 ### Permissions
 
 - **Runtime-configurable groups via API** -- `POST /permission-groups` creates a named group with permission entries. Groups have `groupId`, `label`, `sortOrder`, and an array of entries (key, label, type). No redeploy required to define new permissions.
+
+> **Note:** Permission groups use `label` for display text and `groupId` for the unique identifier -- not `name`.
+
+```ts
+await engine.permissions.createGroup({
+  groupId: 'chat-management',    // unique identifier, kebab-case
+  label: 'Chat Management',      // display text shown in UI
+  permissions: [
+    { key: 'chat:view', label: 'View chats', type: 'view' },
+    { key: 'chat:edit', label: 'Edit chats', type: 'edit' },
+  ],
+  sortOrder: 1,
+});
+```
 - **Edit-to-view cascade** -- when granting a permission ending in `.edit`, the corresponding `.view` key is automatically required. The engine validates this on `PUT /:id/permissions`.
 - **Permission cache (Redis or in-memory)** -- each staff member's resolved permission list is cached after the first lookup. TTL is `permissionCacheTtlMs` (default 5 min). Cache is invalidated immediately on `updatePermissions` or `updateStatus`.
 - **Owner bypasses all checks** -- `requirePermission` middleware skips the permission check entirely when `req.user.role === 'owner'`.
@@ -122,6 +136,27 @@ The factory function returns a single `StaffEngine` object:
 | `engine.models` | Mongoose models (`Staff`, `PermissionGroup`) |
 | `engine.destroy()` | Flush permission cache and clean up resources |
 
+## Seeding Data
+
+Schema factory functions are exported so you can seed data or run scripts without creating a full engine instance:
+
+```ts
+import { createStaffModel, createPermissionGroupModel } from '@astralibx/staff-engine';
+
+const Staff = createStaffModel(connection);
+const PermissionGroup = createPermissionGroupModel(connection);
+
+await PermissionGroup.create({
+  groupId: 'admin',
+  label: 'Admin',
+  permissions: [
+    { key: 'chat:view', label: 'View chats', type: 'view' },
+    { key: 'chat:edit', label: 'Edit chats', type: 'edit' },
+  ],
+  sortOrder: 1,
+});
+```
+
 ## Redis Key Prefix (Required for Multi-Project Deployments)
 
 > **WARNING:** If multiple projects share the same Redis server, you MUST set a unique `keyPrefix` per project. Without this, rate limiter state and permission cache entries will collide across projects.

package/dist/index.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
-var zod = require('zod');
 var core = require('@astralibx/core');
 var staffTypes = require('@astralibx/staff-types');
 var mongoose = require('mongoose');
+var zod = require('zod');
 var jwt2 = require('jsonwebtoken');
 var express = require('express');
 
@@ -403,6 +403,50 @@ function validatePermissionPairs(permissions, allGroups) {
     throw new InvalidPermissionError(missingViewKeys);
   }
 }
+var StaffEngineConfigSchema = zod.z.object({
+  db: zod.z.object({
+    connection: zod.z.unknown().refine((v) => v !== void 0 && v !== null, {
+      message: "db.connection is required"
+    }),
+    collectionPrefix: zod.z.string().optional()
+  }),
+  redis: zod.z.object({
+    connection: zod.z.unknown(),
+    keyPrefix: zod.z.string().optional()
+  }).optional(),
+  logger: zod.z.object({
+    info: zod.z.function(),
+    warn: zod.z.function(),
+    error: zod.z.function()
+  }).optional(),
+  tenantId: zod.z.string().optional(),
+  auth: zod.z.object({
+    jwtSecret: zod.z.string().min(1),
+    staffTokenExpiry: zod.z.string().optional(),
+    ownerTokenExpiry: zod.z.string().optional(),
+    permissionCacheTtlMs: zod.z.number().int().positive().optional()
+  }),
+  adapters: zod.z.object({
+    hashPassword: zod.z.function(),
+    comparePassword: zod.z.function()
+  }),
+  hooks: zod.z.object({
+    onStaffCreated: zod.z.function().optional(),
+    onLogin: zod.z.function().optional(),
+    onLoginFailed: zod.z.function().optional(),
+    onPermissionsChanged: zod.z.function().optional(),
+    onStatusChanged: zod.z.function().optional(),
+    onMetric: zod.z.function().optional()
+  }).optional(),
+  options: zod.z.object({
+    requireEmailUniqueness: zod.z.boolean().optional(),
+    allowSelfPasswordChange: zod.z.boolean().optional(),
+    rateLimiter: zod.z.object({
+      windowMs: zod.z.number().int().positive().optional(),
+      maxAttempts: zod.z.number().int().positive().optional()
+    }).optional()
+  }).optional()
+});
 
 // src/services/staff.service.ts
 var StaffService = class {
@@ -411,105 +455,22 @@ var StaffService = class {
   adapters;
   hooks;
   permissionCache;
-  rateLimiter;
   logger;
   tenantId;
-  jwtSecret;
-  staffTokenExpiry;
-  ownerTokenExpiry;
   requireEmailUniqueness;
-  allowSelfPasswordChange;
   constructor(deps) {
     this.Staff = deps.Staff;
     this.PermissionGroup = deps.PermissionGroup;
     this.adapters = deps.adapters;
     this.hooks = deps.hooks;
     this.permissionCache = deps.permissionCache;
-    this.rateLimiter = deps.rateLimiter;
     this.logger = deps.logger;
     this.tenantId = deps.tenantId;
-    this.jwtSecret = deps.jwtSecret;
-    this.staffTokenExpiry = deps.staffTokenExpiry;
-    this.ownerTokenExpiry = deps.ownerTokenExpiry;
     this.requireEmailUniqueness = deps.requireEmailUniqueness;
-    this.allowSelfPasswordChange = deps.allowSelfPasswordChange;
   }
   get tenantFilter() {
     return this.tenantId ? { tenantId: this.tenantId } : {};
   }
-  generateToken(staffId, role) {
-    const expiresIn = role === staffTypes.STAFF_ROLE.Owner ? this.ownerTokenExpiry : this.staffTokenExpiry;
-    return jwt2__default.default.sign({ staffId, role }, this.jwtSecret, { expiresIn });
-  }
-  async setupOwner(data) {
-    const count = await this.Staff.countDocuments(this.tenantFilter);
-    if (count > 0) throw new SetupError();
-    const hashedPassword = await this.adapters.hashPassword(data.password);
-    let staff;
-    try {
-      const doc = await this.Staff.create({
-        name: data.name,
-        email: data.email.toLowerCase().trim(),
-        password: hashedPassword,
-        role: staffTypes.STAFF_ROLE.Owner,
-        status: staffTypes.STAFF_STATUS.Active,
-        permissions: [],
-        ...this.tenantFilter
-      });
-      staff = doc.toObject();
-    } catch (err) {
-      if (err && typeof err === "object" && "code" in err && err.code === 11e3) {
-        throw new SetupError();
-      }
-      throw err;
-    }
-    const token = this.generateToken(staff._id.toString(), staffTypes.STAFF_ROLE.Owner);
-    this.logger.info("Owner setup complete", { staffId: staff._id.toString() });
-    this.hooks.onStaffCreated?.(staff);
-    this.hooks.onMetric?.({ name: "staff_setup_complete", value: 1 });
-    return { staff, token };
-  }
-  async login(email, password, ip) {
-    if (ip) {
-      const limit = await this.rateLimiter.checkLimit(ip);
-      if (!limit.allowed) {
-        this.hooks.onLoginFailed?.(email, ip);
-        throw new RateLimitError(limit.retryAfterMs);
-      }
-    }
-    const staff = await this.Staff.findOne({
-      email: email.toLowerCase().trim(),
-      ...this.tenantFilter
-    }).select("+password");
-    if (!staff) {
-      if (ip) await this.rateLimiter.recordAttempt(ip);
-      this.hooks.onLoginFailed?.(email, ip);
-      throw new AuthenticationError(ERROR_CODE.InvalidCredentials);
-    }
-    const valid = await this.adapters.comparePassword(password, staff.password);
-    if (!valid) {
-      if (ip) await this.rateLimiter.recordAttempt(ip);
-      this.hooks.onLoginFailed?.(email, ip);
-      throw new AuthenticationError(ERROR_CODE.InvalidCredentials);
-    }
-    if (staff.status === staffTypes.STAFF_STATUS.Inactive) {
-      throw new AuthenticationError(ERROR_CODE.AccountInactive, ERROR_MESSAGE.AccountInactive);
-    }
-    if (staff.status === staffTypes.STAFF_STATUS.Pending) {
-      throw new AuthenticationError(ERROR_CODE.AccountPending, ERROR_MESSAGE.AccountPending);
-    }
-    staff.lastLoginAt = /* @__PURE__ */ new Date();
-    if (ip) staff.lastLoginIp = ip;
-    await staff.save();
-    if (ip) await this.rateLimiter.reset(ip);
-    const token = this.generateToken(staff._id.toString(), staff.role);
-    this.hooks.onLogin?.(staff.toObject(), ip);
-    this.hooks.onMetric?.({ name: "staff_login", value: 1, labels: { role: staff.role } });
-    this.logger.info("Staff login", { staffId: staff._id.toString() });
-    const staffObj = staff.toObject();
-    delete staffObj.password;
-    return { staff: staffObj, token };
-  }
   async create(data) {
     if (this.requireEmailUniqueness) {
       const existing = await this.Staff.findOne({
@@ -610,6 +571,106 @@ var StaffService = class {
     this.logger.info("Staff status updated", { staffId, oldStatus, newStatus: status });
     return staff.toObject();
   }
+};
+var AuthService = class {
+  Staff;
+  adapters;
+  hooks;
+  rateLimiter;
+  logger;
+  tenantId;
+  jwtSecret;
+  staffTokenExpiry;
+  ownerTokenExpiry;
+  allowSelfPasswordChange;
+  constructor(deps) {
+    this.Staff = deps.Staff;
+    this.adapters = deps.adapters;
+    this.hooks = deps.hooks;
+    this.rateLimiter = deps.rateLimiter;
+    this.logger = deps.logger;
+    this.tenantId = deps.tenantId;
+    this.jwtSecret = deps.jwtSecret;
+    this.staffTokenExpiry = deps.staffTokenExpiry;
+    this.ownerTokenExpiry = deps.ownerTokenExpiry;
+    this.allowSelfPasswordChange = deps.allowSelfPasswordChange;
+  }
+  get tenantFilter() {
+    return this.tenantId ? { tenantId: this.tenantId } : {};
+  }
+  generateToken(staffId, role) {
+    const expiresIn = role === staffTypes.STAFF_ROLE.Owner ? this.ownerTokenExpiry : this.staffTokenExpiry;
+    return jwt2__default.default.sign({ staffId, role }, this.jwtSecret, { expiresIn });
+  }
+  async setupOwner(data) {
+    const count = await this.Staff.countDocuments(this.tenantFilter);
+    if (count > 0) throw new SetupError();
+    const hashedPassword = await this.adapters.hashPassword(data.password);
+    let staff;
+    try {
+      const doc = await this.Staff.create({
+        name: data.name,
+        email: data.email.toLowerCase().trim(),
+        password: hashedPassword,
+        role: staffTypes.STAFF_ROLE.Owner,
+        status: staffTypes.STAFF_STATUS.Active,
+        permissions: [],
+        ...this.tenantFilter
+      });
+      staff = doc.toObject();
+    } catch (err) {
+      if (err && typeof err === "object" && "code" in err && err.code === 11e3) {
+        throw new SetupError();
+      }
+      throw err;
+    }
+    const token = this.generateToken(staff._id.toString(), staffTypes.STAFF_ROLE.Owner);
+    this.logger.info("Owner setup complete", { staffId: staff._id.toString() });
+    this.hooks.onStaffCreated?.(staff);
+    this.hooks.onMetric?.({ name: "staff_setup_complete", value: 1 });
+    return { staff, token };
+  }
+  async login(email, password, ip) {
+    if (ip) {
+      const limit = await this.rateLimiter.checkLimit(ip);
+      if (!limit.allowed) {
+        this.hooks.onLoginFailed?.(email, ip);
+        throw new RateLimitError(limit.retryAfterMs);
+      }
+    }
+    const staff = await this.Staff.findOne({
+      email: email.toLowerCase().trim(),
+      ...this.tenantFilter
+    }).select("+password");
+    if (!staff) {
+      if (ip) await this.rateLimiter.recordAttempt(ip);
+      this.hooks.onLoginFailed?.(email, ip);
+      throw new AuthenticationError(ERROR_CODE.InvalidCredentials);
+    }
+    const valid = await this.adapters.comparePassword(password, staff.password);
+    if (!valid) {
+      if (ip) await this.rateLimiter.recordAttempt(ip);
+      this.hooks.onLoginFailed?.(email, ip);
+      throw new AuthenticationError(ERROR_CODE.InvalidCredentials);
+    }
+    if (staff.status === staffTypes.STAFF_STATUS.Inactive) {
+      throw new AuthenticationError(ERROR_CODE.AccountInactive, ERROR_MESSAGE.AccountInactive);
+    }
+    if (staff.status === staffTypes.STAFF_STATUS.Pending) {
+      throw new AuthenticationError(ERROR_CODE.AccountPending, ERROR_MESSAGE.AccountPending);
+    }
+    staff.lastLoginAt = /* @__PURE__ */ new Date();
+    if (ip) staff.lastLoginIp = ip;
+    await staff.save();
+    if (ip) await this.rateLimiter.reset(ip);
+    const token = this.generateToken(staff._id.toString(), staff.role);
+    this.hooks.onLogin?.(staff.toObject(), ip);
+    this.hooks.onMetric?.({ name: "staff_login", value: 1, labels: { role: staff.role } });
+    this.logger.info("Staff login", { staffId: staff._id.toString() });
+    const staffObj = staff.toObject();
+    delete staffObj.password;
+    return { staff: staffObj, token };
+  }
   async resetPassword(staffId, newPassword) {
     const staff = await this.Staff.findOne({ _id: staffId, ...this.tenantFilter });
     if (!staff) throw new StaffNotFoundError(staffId);
@@ -637,11 +698,11 @@ function createAuthMiddleware(jwtSecret, permissionCache, StaffModel, logger, te
       if (!payload.staffId || !payload.role) return null;
       const filter = { _id: payload.staffId };
       if (tenantId) filter.tenantId = tenantId;
-      const staff = await StaffModel.findOne(filter).select("status role").lean();
+      const staff = await StaffModel.findOne(filter).select("name email status role").lean();
       if (!staff) return null;
       if (staff.status !== staffTypes.STAFF_STATUS.Active) return null;
       const permissions = await permissionCache.get(payload.staffId);
-      return { staffId: payload.staffId, role: staff.role, permissions };
+      return { staffId: payload.staffId, name: staff.name, email: staff.email, role: staff.role, permissions };
     } catch {
       return null;
     }
@@ -762,11 +823,11 @@ function handleStaffError(res, error, logger) {
 }
 
 // src/routes/auth.routes.ts
-function createAuthRoutes(staffService, auth, logger, allowSelfPasswordChange) {
+function createAuthRoutes(staffService, authService, auth, logger, allowSelfPasswordChange) {
   const router = express.Router();
   router.post("/setup", async (req, res) => {
     try {
-      const result = await staffService.setupOwner(req.body);
+      const result = await authService.setupOwner(req.body);
       core.sendSuccess(res, result, 201);
     } catch (error) {
       handleStaffError(res, error, logger);
@@ -776,7 +837,7 @@ function createAuthRoutes(staffService, auth, logger, allowSelfPasswordChange) {
     try {
       const { email, password } = req.body;
       const ip = req.ip || req.socket.remoteAddress || "";
-      const result = await staffService.login(email, password, ip);
+      const result = await authService.login(email, password, ip);
       core.sendSuccess(res, result);
     } catch (error) {
       handleStaffError(res, error, logger);
@@ -796,7 +857,7 @@ function createAuthRoutes(staffService, auth, logger, allowSelfPasswordChange) {
       try {
         const user = req.user;
         const { oldPassword, newPassword } = req.body;
-        await staffService.changeOwnPassword(user.staffId, oldPassword, newPassword);
+        await authService.changeOwnPassword(user.staffId, oldPassword, newPassword);
         core.sendSuccess(res, { message: "Password changed successfully" });
       } catch (error) {
         handleStaffError(res, error, logger);
@@ -805,7 +866,7 @@ function createAuthRoutes(staffService, auth, logger, allowSelfPasswordChange) {
   }
   return router;
 }
-function createStaffRoutes(staffService, logger) {
+function createStaffRoutes(staffService, logger, authService) {
   const router = express.Router();
   router.get("/", async (req, res) => {
     try {
@@ -861,7 +922,10 @@ function createStaffRoutes(staffService, logger) {
   });
   router.put("/:staffId/password", async (req, res) => {
     try {
-      await staffService.resetPassword(req.params["staffId"], req.body.password);
+      if (!authService) {
+        throw new Error("AuthService not available");
+      }
+      await authService.resetPassword(req.params["staffId"], req.body.password);
       core.sendSuccess(res, { message: "Password reset successfully" });
     } catch (error) {
       handleStaffError(res, error, logger);
@@ -909,55 +973,11 @@ function createPermissionGroupRoutes(permissionService, auth, logger) {
 // src/routes/index.ts
 function createRoutes(services, auth, logger, allowSelfPasswordChange) {
   const router = express.Router();
-  router.use("/", createAuthRoutes(services.staff, auth, logger, allowSelfPasswordChange));
-  router.use("/", auth.verifyToken, auth.ownerOnly, createStaffRoutes(services.staff, logger));
+  router.use("/", createAuthRoutes(services.staff, services.auth, auth, logger, allowSelfPasswordChange));
+  router.use("/", auth.verifyToken, auth.ownerOnly, createStaffRoutes(services.staff, logger, services.auth));
   router.use("/permission-groups", createPermissionGroupRoutes(services.permissions, auth, logger));
   return router;
 }
-var StaffEngineConfigSchema = zod.z.object({
-  db: zod.z.object({
-    connection: zod.z.unknown().refine((v) => v !== void 0 && v !== null, {
-      message: "db.connection is required"
-    }),
-    collectionPrefix: zod.z.string().optional()
-  }),
-  redis: zod.z.object({
-    connection: zod.z.unknown(),
-    keyPrefix: zod.z.string().optional()
-  }).optional(),
-  logger: zod.z.object({
-    info: zod.z.function(),
-    warn: zod.z.function(),
-    error: zod.z.function()
-  }).optional(),
-  tenantId: zod.z.string().optional(),
-  auth: zod.z.object({
-    jwtSecret: zod.z.string().min(1),
-    staffTokenExpiry: zod.z.string().optional(),
-    ownerTokenExpiry: zod.z.string().optional(),
-    permissionCacheTtlMs: zod.z.number().int().positive().optional()
-  }),
-  adapters: zod.z.object({
-    hashPassword: zod.z.function(),
-    comparePassword: zod.z.function()
-  }),
-  hooks: zod.z.object({
-    onStaffCreated: zod.z.function().optional(),
-    onLogin: zod.z.function().optional(),
-    onLoginFailed: zod.z.function().optional(),
-    onPermissionsChanged: zod.z.function().optional(),
-    onStatusChanged: zod.z.function().optional(),
-    onMetric: zod.z.function().optional()
-  }).optional(),
-  options: zod.z.object({
-    requireEmailUniqueness: zod.z.boolean().optional(),
-    allowSelfPasswordChange: zod.z.boolean().optional(),
-    rateLimiter: zod.z.object({
-      windowMs: zod.z.number().int().positive().optional(),
-      maxAttempts: zod.z.number().int().positive().optional()
-    }).optional()
-  }).optional()
-});
 function createStaffEngine(config) {
   const parseResult = StaffEngineConfigSchema.safeParse(config);
   if (!parseResult.success) {
@@ -1012,13 +1032,20 @@ function createStaffEngine(config) {
     adapters: config.adapters,
     hooks: config.hooks ?? {},
     permissionCache,
+    logger,
+    tenantId: config.tenantId,
+    requireEmailUniqueness: resolvedOptions.requireEmailUniqueness
+  });
+  const authService = new AuthService({
+    Staff: StaffModel,
+    adapters: config.adapters,
+    hooks: config.hooks ?? {},
     rateLimiter,
     logger,
     tenantId: config.tenantId,
     jwtSecret: resolvedAuth.jwtSecret,
     staffTokenExpiry: resolvedAuth.staffTokenExpiry,
     ownerTokenExpiry: resolvedAuth.ownerTokenExpiry,
-    requireEmailUniqueness: resolvedOptions.requireEmailUniqueness,
     allowSelfPasswordChange: resolvedOptions.allowSelfPasswordChange
   });
   const auth = createAuthMiddleware(
@@ -1029,7 +1056,7 @@ function createStaffEngine(config) {
     config.tenantId
   );
   const routes = createRoutes(
-    { staff: staffService, permissions: permissionService },
+    { staff: staffService, auth: authService, permissions: permissionService },
     auth,
     logger,
     resolvedOptions.allowSelfPasswordChange
@@ -1042,6 +1069,7 @@ function createStaffEngine(config) {
     routes,
     auth,
     staff: staffService,
+    authService,
     permissions: permissionService,
     models: { Staff: StaffModel, PermissionGroup: PermissionGroupModel },
     destroy
@@ -1057,6 +1085,7 @@ Object.defineProperty(exports, "DEFAULT_OPTIONS", {
   get: function () { return staffTypes.DEFAULT_OPTIONS; }
 });
 exports.AlxStaffError = AlxStaffError;
+exports.AuthService = AuthService;
 exports.AuthenticationError = AuthenticationError;
 exports.AuthorizationError = AuthorizationError;
 exports.DEFAULTS = DEFAULTS;
@@ -1073,6 +1102,7 @@ exports.PermissionService = PermissionService;
 exports.RateLimitError = RateLimitError;
 exports.RateLimiterService = RateLimiterService;
 exports.SetupError = SetupError;
+exports.StaffEngineConfigSchema = StaffEngineConfigSchema;
 exports.StaffNotFoundError = StaffNotFoundError;
 exports.StaffService = StaffService;
 exports.TokenError = TokenError;