@tailor-platform/erp-kit 0.2.2 → 0.4.0

package/src/modules/audit/command/activateAuditPolicy.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import { type CommandContext, InsufficientPermissionError } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PolicyNotFoundError,
+  InvalidStateError,
+  IncompletePolicyError,
+  ConflictingActivePolicyError,
+  EntityTypeNotRegisteredError,
+  UnauthorizedError,
+} from "../lib/errors.generated";
+import { draftPolicy, activePolicy, inactivePolicy, companyBoundEntity } from "../testing/fixtures";
+import { run } from "./activateAuditPolicy";
+import { activateAuditPolicy } from "./activateAuditPolicy.generated";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["audit:activateAuditPolicy"],
+};
+
+describe("activateAuditPolicy", () => {
+  it("activates DRAFT policy to ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy); // policy lookup
+    spies.select.mockReturnValueOnce(companyBoundEntity); // entity registration check
+    spies.select.mockReturnValueOnce(undefined); // no conflicting policy
+    spies.update.mockReturnValue({ ...draftPolicy, status: "ACTIVE" });
+
+    const result = await run(db, { policyId: "policy-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy.status).toBe("ACTIVE");
+    }
+  });
+
+  it("begins audit capture after activation", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+    spies.select.mockReturnValueOnce(companyBoundEntity); // entity registration check
+    spies.select.mockReturnValueOnce(undefined);
+    spies.update.mockReturnValue({ ...draftPolicy, status: "ACTIVE" });
+
+    const result = await run(db, { policyId: "policy-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy.status).toBe("ACTIVE");
+    }
+    // Verify that the DB update sets status to ACTIVE, which is the gate for logAuditEvent to capture events
+    expect(spies.set).toHaveBeenCalledWith(expect.objectContaining({ status: "ACTIVE" }));
+    expect(spies.update).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects activation of ACTIVE policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activePolicy);
+
+    const result = await run(db, { policyId: activePolicy.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateError);
+    }
+  });
+
+  it("rejects activation of INACTIVE policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactivePolicy);
+
+    const result = await run(db, { policyId: inactivePolicy.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateError);
+    }
+  });
+
+  it("rejects activation when conflicting ACTIVE policy exists", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy); // policy lookup
+    spies.select.mockReturnValueOnce(companyBoundEntity); // entity registration check
+    spies.select.mockReturnValueOnce(activePolicy); // conflicting policy
+
+    const result = await run(db, { policyId: "policy-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ConflictingActivePolicyError);
+    }
+  });
+
+  it("rejects activation when entity name is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const policyNoEntity = { ...draftPolicy, entityName: "" };
+    spies.select.mockReturnValueOnce(policyNoEntity);
+
+    const result = await run(db, { policyId: "policy-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(IncompletePolicyError);
+    }
+  });
+
+  it("rejects activation when operation type is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const policyNoOp = { ...draftPolicy, operationType: "" };
+    spies.select.mockReturnValueOnce(policyNoOp);
+
+    const result = await run(db, { policyId: "policy-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(IncompletePolicyError);
+    }
+  });
+
+  it("rejects when policy does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { policyId: "nonexistent" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(PolicyNotFoundError);
+    }
+  });
+
+  it("rejects when caller lacks manageAuditPolicies permission", async () => {
+    const { db } = createMockDb<Transaction>();
+    const command = activateAuditPolicy();
+    const noPermCtx: CommandContext = {
+      actorId: "test-actor",
+      permissions: [],
+    };
+
+    const result = await command(db, { policyId: "policy-1" }, noPermCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InsufficientPermissionError);
+    }
+  });
+
+  it("rejects when company-scoped caller activates policy for a different company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy); // policy with companyId: "company-1"
+    const scopedCtx = { ...ctx, companyId: "company-2" };
+
+    const result = await run(db, { policyId: "policy-1" }, scopedCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+
+  it("rejects when global-scoped caller activates company-scoped policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy); // policy with companyId: "company-1"
+    const globalCtx = { ...ctx, companyId: null };
+
+    const result = await run(db, { policyId: "policy-1" }, globalCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+
+  it("rejects when target entity is no longer registered", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy); // policy lookup
+    spies.select.mockReturnValueOnce(undefined); // entity not found
+
+    const result = await run(db, { policyId: "policy-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(EntityTypeNotRegisteredError);
+    }
+  });
+});

package/src/modules/audit/command/activateAuditPolicy.ts

@@ -0,0 +1,97 @@
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  PolicyNotFoundError,
+  InvalidStateError,
+  IncompletePolicyError,
+  ConflictingActivePolicyError,
+  EntityTypeNotRegisteredError,
+  UnauthorizedError,
+} from "../lib/errors.generated";
+
+export interface ActivateAuditPolicyInput {
+  policyId: string;
+}
+
+/**
+ * Function: activateAuditPolicy
+ *
+ * Transitions an audit policy from DRAFT to ACTIVE status, enabling audit
+ * capture for the specified entity, operation type, and scope. Activation is
+ * rejected if a conflicting ACTIVE policy already exists for the same
+ * (entityName, companyId, operationType) combination.
+ */
+export async function run(db: Transaction, input: ActivateAuditPolicyInput, ctx: CommandContext) {
+  const { policyId } = input;
+
+  // 1. Find policy with forUpdate
+  const existing = await db
+    .selectFrom("AuditPolicy")
+    .selectAll()
+    .where("id", "=", policyId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new PolicyNotFoundError(policyId));
+  }
+
+  // 2. Scope authorization
+  if (ctx.companyId !== undefined) {
+    if (ctx.companyId !== null && existing.companyId !== ctx.companyId) {
+      return err(new UnauthorizedError(ctx.actorId));
+    }
+    if (ctx.companyId === null && existing.companyId !== null) {
+      return err(new UnauthorizedError(ctx.actorId));
+    }
+  }
+
+  // 3. Must be DRAFT
+  if (existing.status !== "DRAFT") {
+    return err(new InvalidStateError(policyId));
+  }
+
+  // 4. Check required fields
+  if (!existing.entityName || !existing.operationType) {
+    return err(new IncompletePolicyError(policyId));
+  }
+
+  // 5. Verify entity is still registered
+  const entity = await db
+    .selectFrom("AuditableEntity")
+    .selectAll()
+    .where("entityName", "=", existing.entityName)
+    .executeTakeFirst();
+
+  if (!entity) {
+    return err(new EntityTypeNotRegisteredError(existing.entityName));
+  }
+
+  // 6. Check for conflicting ACTIVE policy (forUpdate to prevent concurrent activations)
+  const conflicting = await db
+    .selectFrom("AuditPolicy")
+    .selectAll()
+    .where("entityName", "=", existing.entityName)
+    .where("companyId", existing.companyId ? "=" : "is", existing.companyId)
+    .where("operationType", "=", existing.operationType)
+    .where("status", "=", "ACTIVE")
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (conflicting) {
+    return err(new ConflictingActivePolicyError(policyId));
+  }
+
+  // 5. Set status ACTIVE
+  const policy = await db
+    .updateTable("AuditPolicy")
+    .set({
+      status: "ACTIVE",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", policyId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ policy: policy! });
+}

package/src/modules/audit/command/createAuditPolicy.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../../shared";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./createAuditPolicy";
+
+export const createAuditPolicy = defineCommand(permissions.createAuditPolicy, run);

package/src/modules/audit/command/createAuditPolicy.test.ts

@@ -0,0 +1,395 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb, testPermissionDenied } from "../../../testing/index";
+import type { CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  EntityTypeNotRegisteredError,
+  ScopeMismatchError,
+  InvalidOperationTypeError,
+  InvalidFieldNameError,
+  DuplicateFieldNameError,
+  InvalidSensitivityModeError,
+  UnauthorizedError,
+} from "../lib/errors.generated";
+import {
+  companyBoundEntity,
+  globalEntity,
+  draftPolicy,
+  globalDraftPolicy,
+} from "../testing/fixtures";
+import { run } from "./createAuditPolicy";
+import { createAuditPolicy } from "./createAuditPolicy.generated";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["audit:createAuditPolicy"],
+};
+
+describe("createAuditPolicy", () => {
+  it("creates policy in DRAFT status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+    spies.insert.mockReturnValue({ ...draftPolicy, id: "new-policy-id" });
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        companyId: "company-1",
+        operationType: "UPDATE",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy.status).toBe("DRAFT");
+    }
+  });
+
+  it("creates policy with company scope for company-bound entity", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+    spies.insert.mockReturnValue({ ...draftPolicy, id: "new-policy-id", companyId: "company-1" });
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        companyId: "company-1",
+        operationType: "CREATE",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy.companyId).toBe("company-1");
+    }
+  });
+
+  it("creates policy with global scope for global entity", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(globalEntity);
+    spies.insert.mockReturnValue({ ...globalDraftPolicy, id: "new-policy-id" });
+
+    const result = await run(
+      db,
+      {
+        entityName: "User",
+        operationType: "CREATE",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy.companyId).toBeNull();
+    }
+  });
+
+  it("creates policy with field-level rules and sensitivity modes", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+    spies.insert.mockReturnValue({ ...draftPolicy, id: "new-policy-id" });
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        companyId: "company-1",
+        operationType: "UPDATE",
+        fieldRules: [
+          { fieldName: "amount", sensitivityMode: "CAPTURE" },
+          { fieldName: "customerId", sensitivityMode: "MASK" },
+        ],
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    // Policy insert + 2 field rule inserts
+    expect(spies.insert).toHaveBeenCalledTimes(3);
+  });
+
+  it("creates policy without field-level rules (audits all eligible fields)", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+    spies.insert.mockReturnValue({ ...draftPolicy, id: "new-policy-id" });
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        companyId: "company-1",
+        operationType: "UPDATE",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    // Only policy insert, no field rule inserts
+    expect(spies.insert).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects when entityName is not registered", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        entityName: "NonExistentEntity",
+        operationType: "CREATE",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(EntityTypeNotRegisteredError);
+    }
+  });
+
+  it("rejects company-scoped policy for global entity", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(globalEntity);
+
+    const result = await run(
+      db,
+      {
+        entityName: "User",
+        companyId: "company-1",
+        operationType: "CREATE",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ScopeMismatchError);
+    }
+  });
+
+  it("rejects global policy for company-bound entity", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        operationType: "CREATE",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ScopeMismatchError);
+    }
+  });
+
+  it("rejects duplicate field names in field-level rules", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        companyId: "company-1",
+        operationType: "UPDATE",
+        fieldRules: [
+          { fieldName: "amount", sensitivityMode: "CAPTURE" },
+          { fieldName: "amount", sensitivityMode: "MASK" },
+        ],
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateFieldNameError);
+    }
+  });
+
+  it("rejects field names not in entity's auditableFields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        companyId: "company-1",
+        operationType: "UPDATE",
+        fieldRules: [{ fieldName: "nonExistentField" }],
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidFieldNameError);
+    }
+  });
+
+  it("rejects invalid sensitivity mode", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        companyId: "company-1",
+        operationType: "UPDATE",
+        fieldRules: [{ fieldName: "amount", sensitivityMode: "INVALID_MODE" }],
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidSensitivityModeError);
+    }
+  });
+
+  it("rejects invalid operation type", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        companyId: "company-1",
+        operationType: "INVALID_OP",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidOperationTypeError);
+    }
+  });
+
+  it("rejects empty field name in field-level rules", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        companyId: "company-1",
+        operationType: "UPDATE",
+        fieldRules: [{ fieldName: "" }],
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidFieldNameError);
+    }
+  });
+
+  it("defaults sensitivityMode to CAPTURE when not specified", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(companyBoundEntity);
+    spies.insert.mockReturnValue({ ...draftPolicy, id: "new-policy-id" });
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        companyId: "company-1",
+        operationType: "UPDATE",
+        fieldRules: [{ fieldName: "amount" }],
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    // Verify the field rule insert was called with sensitivityMode defaulting to CAPTURE
+    expect(spies.values).toHaveBeenCalledWith(
+      expect.objectContaining({
+        fieldName: "amount",
+        sensitivityMode: "CAPTURE",
+      }),
+    );
+  });
+
+  it(
+    "rejects when caller lacks manageAuditPolicies permission",
+    testPermissionDenied(createAuditPolicy(), {
+      entityName: "SalesOrder",
+      companyId: "company-1",
+      operationType: "UPDATE",
+    }),
+  );
+
+  it("rejects when company-scoped caller creates policy for a different company", async () => {
+    const { db } = createMockDb<Transaction>();
+    const scopedCtx = { ...ctx, companyId: "company-2" };
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        companyId: "company-1",
+        operationType: "CREATE",
+      },
+      scopedCtx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+
+  it("creates policy with global scope when companyId is explicitly null", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(globalEntity);
+    spies.insert.mockReturnValue({ ...globalDraftPolicy, id: "new-policy-id" });
+
+    const result = await run(
+      db,
+      {
+        entityName: "User",
+        companyId: null,
+        operationType: "CREATE",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy.companyId).toBeNull();
+    }
+  });
+
+  it("rejects when global-scoped caller creates company-scoped policy", async () => {
+    const { db } = createMockDb<Transaction>();
+    const globalCtx = { ...ctx, companyId: null };
+
+    const result = await run(
+      db,
+      {
+        entityName: "SalesOrder",
+        companyId: "company-1",
+        operationType: "CREATE",
+      },
+      globalCtx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+});