@tailor-platform/erp-kit 0.0.1 → 0.1.1

package/src/modules/shared/requirePermission.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { InsufficientPermissionError } from "./errors";
+import { requirePermission } from "./requirePermission";
+import type { CommandContext } from "./types";
+
+describe("requirePermission", () => {
+  const ctx: CommandContext = {
+    actorId: "user-1",
+    permissions: [
+      "primitives:createCategory",
+      "primitives:activateCategory",
+      "inventory:createItem",
+    ],
+  };
+
+  it("does not throw when permission is present", () => {
+    expect(() => requirePermission(ctx, "primitives:createCategory")).not.toThrow();
+    expect(() => requirePermission(ctx, "inventory:createItem")).not.toThrow();
+  });
+
+  it("throws InsufficientPermissionError when permission is missing", () => {
+    expect(() => requirePermission(ctx, "primitives:deleteCategory")).toThrow(
+      InsufficientPermissionError,
+    );
+  });
+
+  it("includes actorId and permission key in error", () => {
+    try {
+      requirePermission(ctx, "orders:createOrder");
+      expect.fail("Should have thrown");
+    } catch (err) {
+      const error = err as InstanceType<typeof InsufficientPermissionError>;
+      expect(error.name).toBe("InsufficientPermissionError");
+      expect(error.code).toBe("INSUFFICIENT_PERMISSION");
+      expect(error.message).toContain("user-1");
+      expect(error.message).toContain("orders:createOrder");
+    }
+  });
+
+  it("throws when permissions array is empty", () => {
+    const emptyCtx: CommandContext = { actorId: "user-2", permissions: [] };
+
+    expect(() => requirePermission(emptyCtx, "primitives:createCategory")).toThrow(
+      InsufficientPermissionError,
+    );
+  });
+});

package/src/modules/shared/requirePermission.ts

@@ -0,0 +1,8 @@
+import type { CommandContext } from "./types";
+import { InsufficientPermissionError } from "./errors";
+
+export function requirePermission(ctx: CommandContext, key: string): void {
+  if (!ctx.permissions.includes(key)) {
+    throw new InsufficientPermissionError(ctx.actorId, key);
+  }
+}

package/src/modules/shared/types.ts

@@ -0,0 +1,4 @@
+export interface CommandContext {
+  actorId: string;
+  permissions: readonly string[];
+}

package/src/modules/testing/index.ts

@@ -0,0 +1,120 @@
+import { vi, expect } from "vitest";
+import type { Kysely } from "kysely";
+import { InsufficientPermissionError, type CommandContext, type Command } from "../shared/internal";
+
+export type Spy = ReturnType<typeof vi.fn>;
+
+export interface QueryBuilder {
+  where(...args: unknown[]): QueryBuilder;
+  selectAll(...args: unknown[]): QueryBuilder;
+  select(...args: unknown[]): QueryBuilder;
+  innerJoin(...args: unknown[]): QueryBuilder;
+  values(...args: unknown[]): QueryBuilder;
+  returningAll(...args: unknown[]): QueryBuilder;
+  set(...args: unknown[]): QueryBuilder;
+  orderBy(...args: unknown[]): QueryBuilder;
+  executeTakeFirst(): unknown;
+  executeTakeFirstOrThrow(): unknown;
+  execute(): unknown;
+}
+
+export interface MockDbSpies {
+  select: Spy;
+  update: Spy;
+  insert: Spy;
+  delete: Spy;
+  values: Spy;
+  set: Spy;
+}
+
+function makeBuilder(executeSpy: Spy, valuesSpy: Spy, setSpy: Spy): QueryBuilder {
+  const builder: QueryBuilder = {} as QueryBuilder;
+  builder.where = () => builder;
+  builder.selectAll = () => builder;
+  builder.select = () => builder;
+  builder.innerJoin = () => builder;
+  builder.values = (...args: unknown[]) => {
+    valuesSpy(...args);
+    return builder;
+  };
+  builder.returningAll = () => builder;
+  builder.set = (...args: unknown[]) => {
+    setSpy(...args);
+    return builder;
+  };
+  builder.orderBy = () => builder;
+  builder.executeTakeFirst = () => executeSpy();
+  builder.executeTakeFirstOrThrow = () => executeSpy();
+  builder.execute = () => executeSpy();
+  return builder;
+}
+
+export function createMockDb<T = Kysely<Record<string, unknown>>>(): {
+  db: T;
+  spies: MockDbSpies;
+  reset: () => void;
+} {
+  const select = vi.fn();
+  const update = vi.fn();
+  const insert = vi.fn();
+  const del = vi.fn();
+  const values = vi.fn();
+  const set = vi.fn();
+
+  const db = {
+    selectFrom: () => makeBuilder(select, values, set),
+    updateTable: () => makeBuilder(update, values, set),
+    insertInto: () => makeBuilder(insert, values, set),
+    deleteFrom: () => makeBuilder(del, values, set),
+  } as unknown as T;
+
+  return {
+    db,
+    spies: { select, update, insert, delete: del, values, set },
+    reset: () => {
+      select.mockReset();
+      update.mockReset();
+      insert.mockReset();
+      del.mockReset();
+      values.mockReset();
+      set.mockReset();
+    },
+  };
+}
+
+export function testNotFound<TInput>(
+  command: Command<TInput, unknown>,
+  input: TInput,
+  ctx: CommandContext,
+  ErrorClass: abstract new (...args: never[]) => Error,
+) {
+  return async () => {
+    const { db, spies } = createMockDb();
+    spies.select.mockReturnValue(undefined);
+    await expect(command(db, input, ctx)).rejects.toBeInstanceOf(ErrorClass);
+  };
+}
+
+export function testPermissionDenied<TInput>(command: Command<TInput, unknown>, input: TInput) {
+  return async () => {
+    const { db } = createMockDb();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(command(db, input, denied)).rejects.toBeInstanceOf(InsufficientPermissionError);
+  };
+}
+
+export function testIdempotent<TInput>(
+  command: Command<TInput, Record<string, unknown>>,
+  input: TInput,
+  ctx: CommandContext,
+  existingEntity: Record<string, unknown>,
+  entityKey: string,
+) {
+  return async () => {
+    const { db, spies } = createMockDb();
+    spies.select.mockReturnValue(existingEntity);
+    const result = await command(db, input, ctx);
+    expect(result[entityKey]).toEqual(existingEntity);
+    expect(spies.update).not.toHaveBeenCalled();
+  };
+}

package/src/modules/user-management/README.md

@@ -0,0 +1,38 @@
+# README
+
+## Overview
+
+The User Management module provides identity and access control capabilities for the ERP system. It manages user accounts through their lifecycle (creation, activation, deactivation) and implements Role-Based Access Control (RBAC) for authorization. All security-relevant changes are logged to an immutable audit trail.
+
+This module serves as a foundational component that other modules depend on for user identity and authorization checks.
+
+## Key Features
+
+- **User Account Lifecycle**: Create, activate, deactivate, and reactivate user accounts with clear status transitions (PENDING, ACTIVE, INACTIVE)
+- **Email Uniqueness**: Enforce unique email addresses across all user accounts
+- **Role-Based Access Control**: Define roles that bundle permissions, and assign roles to users for scalable authorization
+- **Permission Management**: Define granular permissions using a `resource:action` format (e.g., `orders:read`, `inventory:write`)
+- **Audit Trail**: Capture immutable records of all security-relevant events for compliance and investigation
+
+## Module Scope
+
+### In Scope
+
+- User CRUD operations with status management (PENDING, ACTIVE, INACTIVE)
+- Role definitions and role-to-user assignments
+- Permission definitions and permission-to-role assignments
+- Audit logging of user lifecycle and authorization changes
+- Status-based access restrictions (e.g., only active users can be assigned roles)
+
+### Out of Scope
+
+- External identity provider integration (SAML, OIDC, OAuth)
+- Multi-factor authentication (MFA)
+- Single sign-on (SSO) federation
+- Fine-grained attribute-based access control (ABAC)
+- Password storage and authentication mechanisms
+- Session management
+
+## Module Dependencies
+
+- None (this is a foundational module)

package/src/modules/user-management/command/activateUser.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb, testNotFound, testPermissionDenied } from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { InvalidStatusTransitionError, UserNotFoundError } from "../lib/errors";
+import { activeUser, baseAuditEvent, inactiveUser, pendingUser } from "../testing/fixtures";
+import { activateUser } from "./activateUser";
+
+describe("activateUser", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["user-management:activateUser"],
+  };
+
+  it(
+    "throws when user does not exist",
+    testNotFound(
+      activateUser,
+      { userId: "nonexistent-user", actorId: "actor-1" },
+      ctx,
+      UserNotFoundError,
+    ),
+  );
+
+  it("throws when user is already ACTIVE", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(activeUser);
+
+    await expect(
+      activateUser(db, { userId: activeUser.id, actorId: "actor-1" }, ctx),
+    ).rejects.toBeInstanceOf(InvalidStatusTransitionError);
+  });
+
+  it("throws when user is INACTIVE (use reactivateUser instead)", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(inactiveUser);
+
+    await expect(
+      activateUser(db, { userId: inactiveUser.id, actorId: "actor-1" }, ctx),
+    ).rejects.toBeInstanceOf(InvalidStatusTransitionError);
+  });
+
+  // Success cases
+  it("activates PENDING user to ACTIVE", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activatedUser = {
+      ...pendingUser,
+      status: "ACTIVE" as const,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+    const createdAuditEvent = {
+      ...baseAuditEvent,
+      eventType: "USER_ACTIVATED" as const,
+      actorId: "actor-1",
+      targetId: pendingUser.id,
+    };
+
+    spies.select.mockReturnValue(pendingUser);
+    spies.update.mockReturnValue(activatedUser);
+    spies.insert.mockReturnValue(createdAuditEvent);
+
+    const result = await activateUser(
+      db,
+      {
+        userId: pendingUser.id,
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+
+    expect(result.user.status).toBe("ACTIVE");
+    expect(result.user.updatedAt).not.toBeNull();
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("logs USER_ACTIVATED audit event", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activatedUser = {
+      ...pendingUser,
+      status: "ACTIVE" as const,
+      updatedAt: new Date("2024-01-15T00:00:00.000Z"),
+    };
+    const createdAuditEvent = {
+      ...baseAuditEvent,
+      eventType: "USER_ACTIVATED" as const,
+      actorId: "actor-1",
+      targetId: pendingUser.id,
+    };
+
+    spies.select.mockReturnValue(pendingUser);
+    spies.update.mockReturnValue(activatedUser);
+    spies.insert.mockReturnValue(createdAuditEvent);
+
+    const result = await activateUser(
+      db,
+      {
+        userId: pendingUser.id,
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+
+    expect(result.auditEvent.eventType).toBe("USER_ACTIVATED");
+    expect(result.auditEvent.actorId).toBe("actor-1");
+    expect(result.auditEvent.targetId).toBe(pendingUser.id);
+  });
+
+  it(
+    "throws when permission is missing",
+    testPermissionDenied(activateUser, { userId: "some-user", actorId: "actor-1" }),
+  );
+});

package/src/modules/user-management/command/activateUser.ts

@@ -0,0 +1,67 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { InvalidStatusTransitionError, UserNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface ActivateUserInput {
+  userId: string;
+  actorId: string;
+  from?: string[];
+}
+
+/**
+ * Function: activateUser
+ *
+ * Transitions a user from PENDING to ACTIVE status.
+ * Only PENDING users can be activated; use reactivateUser for INACTIVE users.
+ */
+export const activateUser = defineCommand(
+  permissions.activateUser,
+  async (db: DB, input: ActivateUserInput) => {
+    // 1. Find user by ID
+    const user = await db
+      .selectFrom("User")
+      .selectAll()
+      .where("id", "=", input.userId)
+      .executeTakeFirst();
+
+    // 2. If not found, throw error
+    if (!user) {
+      throw new UserNotFoundError(input.userId);
+    }
+
+    // 3. Validate status transition
+    const validFromStatuses = input.from ?? ["PENDING"];
+    if (!validFromStatuses.includes(user.status)) {
+      throw new InvalidStatusTransitionError(user.status, "ACTIVE");
+    }
+
+    // 4. Update status to ACTIVE
+    const updatedUser = await db
+      .updateTable("User")
+      .set({
+        status: "ACTIVE",
+        updatedAt: new Date(),
+      })
+      .where("id", "=", input.userId)
+      .returningAll()
+      .executeTakeFirst();
+
+    // 5. Log USER_ACTIVATED audit event
+    const auditEvent = await db
+      .insertInto("AuditEvent")
+      .values({
+        eventType: "USER_ACTIVATED",
+        actorId: input.actorId,
+        targetId: input.userId,
+        targetType: "User",
+        payload: JSON.stringify({ previousStatus: user.status }),
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    return { user: updatedUser!, auditEvent: auditEvent! };
+  },
+);

package/src/modules/user-management/command/assignPermissionToRole.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import { InsufficientPermissionError, type CommandContext } from "../../shared/internal";
+import { createMockDb } from "../../testing/index";
+import { DB } from "../generated/kysely-tailordb";
+import { PermissionNotFoundError, RoleNotFoundError } from "../lib/errors";
+import { baseAuditEvent, basePermission, baseRole, baseRolePermission } from "../testing/fixtures";
+import { assignPermissionToRole } from "./assignPermissionToRole";
+
+describe("assignPermissionToRole", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["user-management:assignPermissionToRole"],
+  };
+
+  it("throws when role does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    await expect(
+      assignPermissionToRole(
+        db,
+        {
+          roleId: "nonexistent-role",
+          permissionId: basePermission.id,
+          actorId: "actor-1",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(RoleNotFoundError);
+  });
+
+  it("throws when permission does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseRole) // Role found
+      .mockReturnValueOnce(undefined); // Permission not found
+
+    await expect(
+      assignPermissionToRole(
+        db,
+        {
+          roleId: baseRole.id,
+          permissionId: "nonexistent-permission",
+          actorId: "actor-1",
+        },
+        ctx,
+      ),
+    ).rejects.toBeInstanceOf(PermissionNotFoundError);
+  });
+
+  it("returns success when assignment already exists (idempotent)", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseRole) // Role found
+      .mockReturnValueOnce(basePermission) // Permission found
+      .mockReturnValueOnce(baseRolePermission); // Assignment already exists
+
+    const result = await assignPermissionToRole(
+      db,
+      {
+        roleId: baseRole.id,
+        permissionId: basePermission.id,
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+
+    expect(result.rolePermission).toEqual(baseRolePermission);
+    expect(spies.insert).not.toHaveBeenCalled();
+  });
+
+  it("creates RolePermission and logs PERMISSION_ASSIGNED event", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const newRolePermission = {
+      ...baseRolePermission,
+      id: "new-role-permission-id",
+    };
+    const createdAuditEvent = {
+      ...baseAuditEvent,
+      eventType: "PERMISSION_ASSIGNED" as const,
+      actorId: "actor-1",
+      targetId: baseRole.id,
+      targetType: "Role",
+    };
+
+    spies.select
+      .mockReturnValueOnce(baseRole) // Role found
+      .mockReturnValueOnce(basePermission) // Permission found
+      .mockReturnValueOnce(undefined); // No existing assignment
+    spies.insert.mockReturnValueOnce(newRolePermission).mockReturnValueOnce(createdAuditEvent);
+
+    const result = await assignPermissionToRole(
+      db,
+      {
+        roleId: baseRole.id,
+        permissionId: basePermission.id,
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+
+    expect(result.rolePermission.roleId).toBe(baseRole.id);
+    expect(result.rolePermission.permissionId).toBe(basePermission.id);
+    expect(result.auditEvent?.eventType).toBe("PERMISSION_ASSIGNED");
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("throws when permission is missing", async () => {
+    const { db } = createMockDb<DB>();
+    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
+    await expect(
+      assignPermissionToRole(
+        db,
+        { roleId: "role-1", permissionId: "perm-1", actorId: "actor-1" },
+        denied,
+      ),
+    ).rejects.toBeInstanceOf(InsufficientPermissionError);
+  });
+});

package/src/modules/user-management/command/assignPermissionToRole.ts

@@ -0,0 +1,87 @@
+import { defineCommand } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { PermissionNotFoundError, RoleNotFoundError } from "../lib/errors";
+import { permissions } from "../permissions";
+
+export interface AssignPermissionToRoleInput {
+  roleId: string;
+  permissionId: string;
+  actorId: string;
+}
+
+/**
+ * Function: assignPermissionToRole
+ *
+ * Assigns a permission to a role. Operation is idempotent - assigning
+ * the same permission twice does not create duplicate records or error.
+ *
+ * Note: Permissions for affected users are recomputed asynchronously via executor.
+ */
+export const assignPermissionToRole = defineCommand(
+  permissions.assignPermissionToRole,
+  async (db: DB, input: AssignPermissionToRoleInput) => {
+    const role = await db
+      .selectFrom("Role")
+      .selectAll()
+      .where("id", "=", input.roleId)
+      .executeTakeFirst();
+
+    if (!role) {
+      throw new RoleNotFoundError(input.roleId);
+    }
+
+    const permission = await db
+      .selectFrom("Permission")
+      .selectAll()
+      .where("id", "=", input.permissionId)
+      .executeTakeFirst();
+
+    if (!permission) {
+      throw new PermissionNotFoundError(input.permissionId);
+    }
+
+    // Idempotent: return existing assignment without creating duplicates
+    const existingAssignment = await db
+      .selectFrom("RolePermission")
+      .selectAll()
+      .where("roleId", "=", input.roleId)
+      .where("permissionId", "=", input.permissionId)
+      .executeTakeFirst();
+
+    if (existingAssignment) {
+      return { rolePermission: existingAssignment };
+    }
+
+    // Permission recomputation for affected users is handled asynchronously by executor
+    const rolePermission = await db
+      .insertInto("RolePermission")
+      .values({
+        roleId: input.roleId,
+        permissionId: input.permissionId,
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    const auditEvent = await db
+      .insertInto("AuditEvent")
+      .values({
+        eventType: "PERMISSION_ASSIGNED",
+        actorId: input.actorId,
+        targetId: input.roleId,
+        targetType: "Role",
+        payload: JSON.stringify({
+          roleId: input.roleId,
+          permissionId: input.permissionId,
+          permissionKey: permission.key,
+        }),
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    return { rolePermission: rolePermission!, auditEvent: auditEvent! };
+  },
+);