@tailor-platform/erp-kit 0.0.1 → 0.1.0

package/src/modules/user-management/docs/features/role-based-access-control.md

@@ -0,0 +1,76 @@
+# Role-Based Access Control
+
+## Overview
+
+Role-Based Access Control (RBAC) implements a permission-to-role-to-user authorization model. Permissions define specific allowed actions on resources, roles bundle related permissions together, and users are assigned one or more roles. This model simplifies access management by allowing administrators to manage permissions at the role level rather than per-user.
+
+The RBAC implementation follows the principle of least privilege, ensuring users only have access to what they need for their job function.
+
+## Business Purpose
+
+Organizations need granular access control that scales with team size:
+
+- **Simplified Administration**: Instead of managing permissions per user, administrators assign roles
+- **Consistency**: All users with the same role have identical permissions
+- **Separation of Duties**: Different roles can have non-overlapping permissions to prevent fraud
+- **Auditability**: Clear mapping from user to roles to permissions supports compliance reviews
+- **Scalability**: Adding new users requires only role assignment, not permission configuration
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Define Permission] --> B[Permission Created]
+    B --> C[Assign Permission to Role]
+    C --> D[Role Has Permission]
+
+    E[Create Role] --> F[Role Created]
+    F --> C
+
+    G[Assign Role to User] --> H{User Active?}
+    H -->|No| I[Return Error: USER_NOT_ACTIVE]
+    H -->|Yes| J[User Has Role]
+    J --> K[User Inherits Role's Permissions]
+
+    subgraph Permission Check
+    L[Check User Permission] --> M[Get User's Roles]
+    M --> N[Get Roles' Permissions]
+    N --> O{Has Required Permission?}
+    O -->|Yes| P[Access Granted]
+    O -->|No| Q[Access Denied]
+    end
+```
+
+## Scenario Patterns
+
+- **Permission Definition**: Administrator defines `orders:read` and `orders:write` permissions. The format `resource:action` clearly identifies what resource and operation is controlled.
+- **Role Creation**: Administrator creates "Sales Representative" role and assigns `orders:read` permission. Creates "Sales Manager" role with both `orders:read` and `orders:write` permissions.
+- **User Role Assignment**: New sales hire is assigned "Sales Representative" role. User immediately inherits all permissions associated with that role.
+- **Role Promotion**: Sales rep promoted to manager. Administrator assigns "Sales Manager" role. User can retain or lose previous role based on business policy.
+- **Role Revocation**: User transfers to different department. Administrator revokes current role and assigns appropriate role for new position.
+- **Idempotent Assignment**: Assigning the same role to a user twice does not create duplicate assignments or return an error. The operation is idempotent.
+- **Inactive User Restriction**: Attempt to assign role to PENDING or INACTIVE user fails. Only ACTIVE users can receive role assignments.
+
+## Test Cases
+
+- Creating a permission with valid key format should succeed
+- Permission key must follow `resource:action` format
+- Duplicate permission keys should be rejected
+- Creating a role with valid name should succeed
+- Assigning permission to role should succeed
+- Assigning same permission to role twice should be idempotent (no error)
+- Revoking permission from role should remove the association
+- Assigning role to ACTIVE user should succeed
+- Assigning role to PENDING user should fail with USER_NOT_ACTIVE error
+- Assigning role to INACTIVE user should fail with USER_NOT_ACTIVE error
+- Assigning same role to user twice should be idempotent (no error)
+- Revoking role from user should remove the user-role association
+- Assigning role to non-existent user should fail with USER_NOT_FOUND error
+- Assigning non-existent role to user should fail with ROLE_NOT_FOUND error
+- Assigning non-existent permission to role should fail with PERMISSION_NOT_FOUND error
+
+## Reference Links
+
+- [NIST RBAC Model](https://csrc.nist.gov/projects/role-based-access-control)
+- [Odoo Access Rights](https://www.odoo.com/documentation/19.0/applications/general/users/access_rights.html)
+- [OWASP Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html)

package/src/modules/user-management/docs/features/user-account-management.md

@@ -0,0 +1,64 @@
+# User Account Management
+
+## Overview
+
+User Account Management handles the complete user lifecycle from creation through deactivation. Each user has a status that controls their access to the system: PENDING (awaiting activation), ACTIVE (full access), or INACTIVE (access revoked). Status transitions follow defined rules to ensure security and auditability.
+
+This feature provides the foundation for all identity-related operations in the ERP system.
+
+## Business Purpose
+
+Organizations need controlled user provisioning to ensure only authorized individuals can access the system. The status-based lifecycle provides:
+
+- **Onboarding control**: New users start in PENDING status until verified
+- **Access management**: Only ACTIVE users can perform operations
+- **Offboarding safety**: Deactivated users retain their data for audit purposes while losing access
+- **Compliance tracking**: Clear status transitions support regulatory requirements
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create User] --> B[Status: PENDING]
+    B --> C{Verification Complete?}
+    C -->|Yes| D[Activate User]
+    D --> E[Status: ACTIVE]
+    E --> F{Employee Leaves?}
+    F -->|Yes| G[Deactivate User]
+    G --> H[Status: INACTIVE]
+    H --> I{Employee Returns?}
+    I -->|Yes| J[Reactivate User]
+    J --> E
+
+    subgraph Valid Transitions
+    B -->|activateUser| E
+    E -->|deactivateUser| H
+    H -->|reactivateUser| E
+    end
+```
+
+## Scenario Patterns
+
+- **New Employee Onboarding**: HR creates user account with name and email, user starts in PENDING status. After background check and IT setup complete, administrator activates the user.
+- **Employee Departure**: When employee resigns or is terminated, administrator deactivates user account. User data is preserved for audit and historical reporting, but all access is revoked.
+- **Contractor Return Engagement**: Previously offboarded contractor returns for new project. Administrator reactivates existing account rather than creating duplicate, preserving historical associations.
+- **Duplicate Prevention**: Attempt to create user with existing email address is rejected with clear error, preventing duplicate accounts.
+- **Invalid Activation**: Attempt to activate already-active user or deactivate already-inactive user returns appropriate error with current status.
+
+## Test Cases
+
+- Creating a user with unique email should succeed and set status to PENDING
+- Creating a user with duplicate email should fail with USER_ALREADY_EXISTS error
+- Activating a PENDING user should transition status to ACTIVE
+- Activating an already ACTIVE user should fail with INVALID_STATUS_TRANSITION error
+- Deactivating an ACTIVE user should transition status to INACTIVE
+- Deactivating a PENDING user should fail with INVALID_STATUS_TRANSITION error
+- Reactivating an INACTIVE user should transition status to ACTIVE
+- Reactivating a PENDING user should fail with INVALID_STATUS_TRANSITION error
+- User email should be validated for proper format
+- User name should be required and non-empty
+
+## Reference Links
+
+- [Odoo User Management](https://www.odoo.com/documentation/19.0/applications/general/users.html)
+- [NIST Identity Management Guidelines](https://pages.nist.gov/800-63-3/sp800-63a.html)

package/src/modules/user-management/docs/models/AuditEvent.md

@@ -0,0 +1,34 @@
+# AuditEvent
+
+## Description
+
+AuditEvent captures immutable records of all security-relevant events in the User Management module. Every user lifecycle change, role assignment, and permission modification is logged with the actor identity, timestamp, and event details. These records cannot be modified or deleted, ensuring a trustworthy history for compliance and security investigations.
+
+Event types include: USER_CREATED, USER_ACTIVATED, USER_DEACTIVATED, USER_REACTIVATED, ROLE_ASSIGNED, ROLE_REVOKED, PERMISSION_ASSIGNED, PERMISSION_REVOKED.
+
+## Domain Model Definitions
+
+### Model type
+
+AppendOnly
+
+### Command Definitions
+
+- [logAuditEvent](../commands/LogAuditEvent.md)
+
+### Models
+
+- AuditEvent
+
+### Invariants
+
+- Event type must be a valid event type (USER_CREATED, USER_ACTIVATED, USER_DEACTIVATED, USER_REACTIVATED, ROLE_ASSIGNED, ROLE_REVOKED, PERMISSION_ASSIGNED, PERMISSION_REVOKED)
+- Actor ID is required (identifies who performed the action)
+- Timestamp is required (auto-generated at creation)
+- Records cannot be updated after creation
+- Records cannot be deleted
+
+### Relationships
+
+- **References User as Actor**: Each event records which user performed the action
+- **References Target Entity**: Each event references the affected entity (user, role, or permission depending on event type)

package/src/modules/user-management/docs/models/Permission.md

@@ -0,0 +1,31 @@
+# Permission
+
+## Description
+
+Permission defines a specific allowed action on a resource within the ERP system. Each permission uses the `resource:action` format (e.g., `orders:read`, `users:delete`) to clearly identify what resource and operation is controlled. Permissions are the atomic unit of authorization and are bundled into roles for assignment to users.
+
+Examples: `orders:read`, `orders:write`, `users:create`, `reports:export`.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createPermission](../commands/CreatePermission.md)
+
+### Models
+
+- Permission
+
+### Invariants
+
+- Permission key must be unique across all permissions
+- Permission key must follow `resource:action` format
+- Permission key is required and cannot be empty
+
+### Relationships
+
+- **Referenced By RolePermission**: Permission is assigned to roles through RolePermission join records

package/src/modules/user-management/docs/models/Role.md

@@ -0,0 +1,31 @@
+# Role
+
+## Description
+
+Role represents a named collection of permissions that can be assigned to users. Roles provide a level of abstraction between permissions and users, simplifying access management by allowing administrators to manage permissions at the role level rather than per-user. Common examples include "Sales Representative", "Sales Manager", or "Administrator".
+
+Roles follow the principle of least privilege, bundling only the permissions necessary for a specific job function.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createRole](../commands/CreateRole.md)
+
+### Models
+
+- Role
+
+### Invariants
+
+- Role name must be unique across all roles
+- Role name is required and cannot be empty
+
+### Relationships
+
+- **Has Many RolePermissions**: Role contains permissions through RolePermission join records
+- **Has Many UserRoles**: Role is assigned to users through UserRole join records

package/src/modules/user-management/docs/models/RolePermission.md

@@ -0,0 +1,33 @@
+# RolePermission
+
+## Description
+
+RolePermission is a join model that represents the assignment of a permission to a role. This many-to-many relationship enables roles to have multiple permissions and permissions to be assigned to multiple roles. When a user is assigned a role, they inherit all permissions assigned to that role.
+
+The assignment operation is idempotent - assigning the same permission twice does not create duplicate records.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [assignPermissionToRole](../commands/AssignPermissionToRole.md)
+- [revokePermissionFromRole](../commands/RevokePermissionFromRole.md)
+
+### Models
+
+- RolePermission
+
+### Invariants
+
+- Role-Permission combination must be unique (no duplicate assignments)
+- Referenced role must exist
+- Referenced permission must exist
+
+### Relationships
+
+- **Belongs To Role**: Each RolePermission record references exactly one role
+- **Belongs To Permission**: Each RolePermission record references exactly one permission

package/src/modules/user-management/docs/models/User.md

@@ -0,0 +1,47 @@
+# User
+
+## Description
+
+User represents an identity in the ERP system with a lifecycle managed through status transitions. Each user has an email (unique identifier), name, and status that controls system access. The status-based lifecycle ensures controlled provisioning: users start PENDING until verified, become ACTIVE for full access, and transition to INACTIVE when access should be revoked while preserving data for audit purposes.
+
+This model provides the foundation for all identity-related operations in the ERP system.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Pending: createUser
+    Pending --> Active: activateUser
+    Active --> Inactive: deactivateUser
+    Inactive --> Active: reactivateUser
+```
+
+### Command Definitions
+
+- [createUser](../commands/CreateUser.md)
+- [activateUser](../commands/ActivateUser.md)
+- [deactivateUser](../commands/DeactivateUser.md)
+- [reactivateUser](../commands/ReactivateUser.md)
+
+### Models
+
+- User
+
+### Invariants
+
+- Email must be unique across all users (active and inactive)
+- Email must follow valid email format
+- Name is required and cannot be empty
+- Status must be one of PENDING, ACTIVE, or INACTIVE
+- Only ACTIVE users can receive role assignments
+
+### Relationships
+
+- **Has Many UserRoles**: User is assigned roles through UserRole join records
+- **Referenced By AuditEvent**: User actions are recorded in audit events as actor or target

package/src/modules/user-management/docs/models/UserRole.md

@@ -0,0 +1,34 @@
+# UserRole
+
+## Description
+
+UserRole is a join model that represents the assignment of a role to a user. This many-to-many relationship enables users to have multiple roles and roles to be assigned to multiple users. Role assignments are only valid for users in ACTIVE status, ensuring that pending or inactive users cannot accumulate permissions.
+
+The assignment operation is idempotent - assigning the same role twice does not create duplicate records.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [assignRoleToUser](../commands/AssignRoleToUser.md)
+- [revokeRoleFromUser](../commands/RevokeRoleFromUser.md)
+
+### Models
+
+- UserRole
+
+### Invariants
+
+- User-Role combination must be unique (no duplicate assignments)
+- Referenced user must exist
+- Referenced role must exist
+- User must be in ACTIVE status to receive role assignment
+
+### Relationships
+
+- **Belongs To User**: Each UserRole record references exactly one user
+- **Belongs To Role**: Each UserRole record references exactly one role

package/src/modules/user-management/docs/plans/2026-01-30-flattened-permissions-design.md

@@ -0,0 +1,52 @@
+# Flattened User Permissions Design
+
+## Problem
+
+Authorization checks require joining User → UserRole → Role → RolePermission → Permission. This is slow and complex. We want permissions denormalized directly on the User record for fast lookups.
+
+## Solution
+
+Add a `permissions` field to User that contains a flattened array of permission keys. Recompute automatically when role/permission assignments change.
+
+## Data Model
+
+```typescript
+// User.permissions
+permissions: string[] | null; // e.g., ["orders:read", "orders:write", "users:read"]
+```
+
+## Recompute Function
+
+`src/lib/recomputeUserPermissions.ts`:
+
+- Query: User → UserRole → RolePermission → Permission
+- Deduplicate permission keys
+- Update User.permissions field
+- Return computed array
+
+## Trigger Points
+
+| Command                  | Affected Users           | Approach     |
+| ------------------------ | ------------------------ | ------------ |
+| assignRoleToUser         | Single user              | Synchronous  |
+| revokeRoleFromUser       | Single user              | Synchronous  |
+| assignPermissionToRole   | All users with that role | Asynchronous |
+| revokePermissionFromRole | All users with that role | Asynchronous |
+
+## Async Executors
+
+For role-permission changes (which affect multiple users), executors handle recomputation asynchronously:
+
+- `recomputeOnRolePermissionCreated` - Triggers on RolePermission create
+- `recomputeOnRolePermissionDeleted` - Triggers on RolePermission delete
+
+Located in `src/executor/recomputeOnRolePermissionChange.ts`.
+
+## Trade-offs
+
+- **Pro**: Fast authorization (single field read, no joins)
+- **Pro**: Simple permission checks (`user.permissions.includes("orders:read")`)
+- **Pro**: Single-user operations remain fast (synchronous)
+- **Pro**: Multi-user operations don't block requests (asynchronous)
+- **Con**: Storage overhead (denormalized data)
+- **Con**: Eventual consistency for role-permission changes

package/src/modules/user-management/executor/recomputeOnRolePermissionChange.ts

@@ -0,0 +1,61 @@
+import { createExecutor, recordCreatedTrigger, recordDeletedTrigger } from "@tailor-platform/sdk";
+import { getDB } from "../generated/kysely-tailordb";
+import { rolePermission } from "../db/rolePermission";
+import { recomputePermissionsForUsersWithRole } from "../lib/recomputeUserPermissions";
+
+/**
+ * Executor: recomputeOnRolePermissionCreated
+ *
+ * Triggers when a RolePermission record is created (permission assigned to role).
+ * Recomputes permissions for all users with that role asynchronously.
+ */
+
+export const recomputeOnRolePermissionCreated = function recomputeOnRolePermissionCreated({
+  namespace,
+}: {
+  namespace: string;
+}) {
+  return createExecutor({
+    name: "recompute-on-role-permission-created",
+    description: "Recompute permissions for all users when a permission is assigned to a role",
+    trigger: recordCreatedTrigger({
+      type: rolePermission,
+    }),
+    operation: {
+      kind: "jobFunction",
+      body: async ({ newRecord }) => {
+        // @ts-expect-error unsure at build time
+        const db = getDB(namespace);
+        await recomputePermissionsForUsersWithRole(db, newRecord.roleId);
+      },
+    },
+  });
+};
+
+/**
+ * Executor: recomputeOnRolePermissionDeleted
+ *
+ * Triggers when a RolePermission record is deleted (permission revoked from role).
+ * Recomputes permissions for all users with that role asynchronously.
+ */
+export const recomputeOnRolePermissionDeleted = function recomputeOnRolePermissionDeleted({
+  namespace,
+}: {
+  namespace: string;
+}) {
+  return createExecutor({
+    name: "recompute-on-role-permission-deleted",
+    description: "Recompute permissions for all users when a permission is revoked from a role",
+    trigger: recordDeletedTrigger({
+      type: rolePermission,
+    }),
+    operation: {
+      kind: "jobFunction",
+      body: async ({ oldRecord }) => {
+        // @ts-expect-error unsure at build time
+        const db = getDB(namespace);
+        await recomputePermissionsForUsersWithRole(db, oldRecord.roleId);
+      },
+    },
+  });
+};

package/src/modules/user-management/generated/enums.ts

@@ -0,0 +1,24 @@
+/**
+ * Type of audit event
+ */
+export const AuditEventEventType = {
+  USER_CREATED: "USER_CREATED",
+  USER_ACTIVATED: "USER_ACTIVATED",
+  USER_DEACTIVATED: "USER_DEACTIVATED",
+  USER_REACTIVATED: "USER_REACTIVATED",
+  ROLE_ASSIGNED: "ROLE_ASSIGNED",
+  ROLE_REVOKED: "ROLE_REVOKED",
+  PERMISSION_ASSIGNED: "PERMISSION_ASSIGNED",
+  PERMISSION_REVOKED: "PERMISSION_REVOKED",
+} as const;
+export type AuditEventEventType = (typeof AuditEventEventType)[keyof typeof AuditEventEventType];
+
+/**
+ * User status
+ */
+export const UserStatus = {
+  PENDING: "PENDING",
+  ACTIVE: "ACTIVE",
+  INACTIVE: "INACTIVE",
+} as const;
+export type UserStatus = (typeof UserStatus)[keyof typeof UserStatus];

package/src/modules/user-management/generated/kysely-tailordb.ts

@@ -0,0 +1,112 @@
+import {
+  type ColumnType,
+  Kysely,
+  type KyselyConfig,
+  type Transaction as KyselyTransaction,
+  type Insertable as KyselyInsertable,
+  type Selectable as KyselySelectable,
+  type Updateable as KyselyUpdateable,
+} from "kysely";
+import { TailordbDialect } from "@tailor-platform/function-kysely-tailordb";
+
+type Timestamp = ColumnType<Date, Date | string, Date | string>;
+type Generated<T> =
+  T extends ColumnType<infer S, infer I, infer U>
+    ? ColumnType<S, I | undefined, U>
+    : ColumnType<T, T | undefined, T>;
+
+export interface Namespace {
+  "main-db": {
+    AuditEvent: {
+      id: Generated<string>;
+      eventType:
+        | "USER_CREATED"
+        | "USER_ACTIVATED"
+        | "USER_DEACTIVATED"
+        | "USER_REACTIVATED"
+        | "ROLE_ASSIGNED"
+        | "ROLE_REVOKED"
+        | "PERMISSION_ASSIGNED"
+        | "PERMISSION_REVOKED";
+      actorId: string;
+      targetId: string | null;
+      targetType: string | null;
+      payload: string | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    };
+
+    Permission: {
+      id: Generated<string>;
+      key: string;
+      description: string | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    };
+
+    Role: {
+      id: Generated<string>;
+      name: string;
+      description: string | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    };
+
+    RolePermission: {
+      id: Generated<string>;
+      roleId: string;
+      permissionId: string;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    };
+
+    User: {
+      id: Generated<string>;
+      email: string;
+      name: string;
+      status: "PENDING" | "ACTIVE" | "INACTIVE";
+      permissions: string[] | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    };
+
+    UserRole: {
+      id: Generated<string>;
+      userId: string;
+      roleId: string;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    };
+  };
+}
+
+export function getDB<const N extends keyof Namespace>(
+  namespace: N,
+  kyselyConfig?: Omit<KyselyConfig, "dialect">,
+): Kysely<Namespace[N]> {
+  const client = new tailordb.Client({ namespace });
+  return new Kysely<Namespace[N]>({
+    dialect: new TailordbDialect(client),
+    ...kyselyConfig,
+  });
+}
+
+export type DB<N extends keyof Namespace = keyof Namespace> = ReturnType<typeof getDB<N>>;
+
+export type Transaction<K extends keyof Namespace | DB = keyof Namespace> =
+  K extends DB<infer N>
+    ? KyselyTransaction<Namespace[N]>
+    : K extends keyof Namespace
+      ? KyselyTransaction<Namespace[K]>
+      : never;
+
+type TableName = {
+  [N in keyof Namespace]: keyof Namespace[N];
+}[keyof Namespace];
+export type Table<T extends TableName> = {
+  [N in keyof Namespace]: T extends keyof Namespace[N] ? Namespace[N][T] : never;
+}[keyof Namespace];
+
+export type Insertable<T extends keyof Namespace[keyof Namespace]> = KyselyInsertable<Table<T>>;
+export type Selectable<T extends keyof Namespace[keyof Namespace]> = KyselySelectable<Table<T>>;
+export type Updateable<T extends keyof Namespace[keyof Namespace]> = KyselyUpdateable<Table<T>>;

package/src/modules/user-management/index.ts

@@ -0,0 +1,32 @@
+export { defineModule } from "./module";
+export { permissions, own, all } from "./permissions";
+
+// generated types
+export { AuditEventEventType, UserStatus } from "./generated/enums";
+
+// errors
+export {
+  UserNotFoundError,
+  UserAlreadyExistsError,
+  UserNotActiveError,
+  InvalidEmailError,
+  MissingRequiredFieldError,
+  InvalidStatusTransitionError,
+  PermissionNotFoundError,
+  DuplicatePermissionKeyError,
+  InvalidPermissionKeyFormatError,
+  RoleNotFoundError,
+  DuplicateRoleNameError,
+  AssignmentNotFoundError,
+  InvalidEventTypeError,
+} from "./lib/errors";
+
+// input types
+export { type ActivateUserInput } from "./command/activateUser";
+export { type DeactivateUserInput } from "./command/deactivateUser";
+export { type ReactivateUserInput } from "./command/reactivateUser";
+export { type AssignPermissionToRoleInput } from "./command/assignPermissionToRole";
+export { type RevokePermissionFromRoleInput } from "./command/revokePermissionFromRole";
+export { type AssignRoleToUserInput } from "./command/assignRoleToUser";
+export { type RevokeRoleFromUserInput } from "./command/revokeRoleFromUser";
+export { type LogAuditEventInput } from "./command/logAuditEvent";