@tailor-platform/erp-kit 0.2.2 → 0.4.0

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

@@ -0,0 +1,131 @@
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  EntityTypeNotRegisteredError,
+  ScopeMismatchError,
+  InvalidOperationTypeError,
+  InvalidFieldNameError,
+  DuplicateFieldNameError,
+  InvalidSensitivityModeError,
+  UnauthorizedError,
+} from "../lib/errors.generated";
+
+const VALID_OPERATION_TYPES = ["CREATE", "UPDATE", "DELETE"];
+const VALID_SENSITIVITY_MODES = ["CAPTURE", "MASK", "HASH", "EXCLUDE"];
+
+export interface CreateAuditPolicyInput {
+  entityName: string;
+  companyId?: string | null;
+  operationType: string;
+  fieldRules?: { fieldName: string; sensitivityMode?: string }[];
+}
+
+/**
+ * Function: createAuditPolicy
+ *
+ * Creates a new audit policy in DRAFT status. Validates the entity name,
+ * scope, operation type, and optional field-level rules before inserting.
+ */
+export async function run(db: Transaction, input: CreateAuditPolicyInput, ctx: CommandContext) {
+  const { entityName, companyId, operationType, fieldRules } = input;
+
+  // 1. Scope authorization: company-scoped caller can only create for their company
+  if (ctx.companyId !== undefined) {
+    if (ctx.companyId !== null && companyId !== ctx.companyId) {
+      return err(new UnauthorizedError(ctx.actorId));
+    }
+    if (ctx.companyId === null && companyId != null) {
+      return err(new UnauthorizedError(ctx.actorId));
+    }
+  }
+
+  // 2. Look up AuditableEntity by entityName
+  const entity = await db
+    .selectFrom("AuditableEntity")
+    .where("entityName", "=", entityName)
+    .selectAll()
+    .executeTakeFirst();
+
+  if (!entity) {
+    return err(new EntityTypeNotRegisteredError(entityName));
+  }
+
+  // 2. Validate scope match
+  if (entity.entityScope === "COMPANY_BOUND" && !companyId) {
+    return err(new ScopeMismatchError(entityName));
+  }
+  if (entity.entityScope === "GLOBAL" && companyId) {
+    return err(new ScopeMismatchError(entityName));
+  }
+
+  // 3. Validate operationType
+  if (!VALID_OPERATION_TYPES.includes(operationType)) {
+    return err(new InvalidOperationTypeError(operationType));
+  }
+
+  // 4. Validate field rules (if provided)
+  if (fieldRules && fieldRules.length > 0) {
+    // Parse auditable fields (supports both legacy string[] and new {fieldName, fieldType?}[] formats)
+    const rawFields = JSON.parse(entity.auditableFields) as string[] | { fieldName: string }[];
+    const auditableFieldNames = new Set<string>(
+      rawFields.map((f) => (typeof f === "string" ? f : f.fieldName)),
+    );
+    const seenFields = new Set<string>();
+
+    for (const rule of fieldRules) {
+      // Empty field name
+      if (!rule.fieldName || rule.fieldName.trim() === "") {
+        return err(new InvalidFieldNameError(rule.fieldName ?? ""));
+      }
+
+      // Field not in entity's auditableFields
+      if (!auditableFieldNames.has(rule.fieldName)) {
+        return err(new InvalidFieldNameError(rule.fieldName));
+      }
+
+      // Duplicate field names
+      if (seenFields.has(rule.fieldName)) {
+        return err(new DuplicateFieldNameError(rule.fieldName));
+      }
+      seenFields.add(rule.fieldName);
+
+      // Invalid sensitivity mode
+      if (rule.sensitivityMode && !VALID_SENSITIVITY_MODES.includes(rule.sensitivityMode)) {
+        return err(new InvalidSensitivityModeError(rule.sensitivityMode));
+      }
+    }
+  }
+
+  // 5. Insert AuditPolicy with status=DRAFT
+  const policy = await db
+    .insertInto("AuditPolicy")
+    .values({
+      entityName,
+      companyId: companyId ?? null,
+      operationType,
+      status: "DRAFT",
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  // 6. Insert PolicyFieldRule records (if field rules provided)
+  if (fieldRules && fieldRules.length > 0) {
+    for (const rule of fieldRules) {
+      await db
+        .insertInto("PolicyFieldRule")
+        .values({
+          auditPolicyId: policy!.id,
+          fieldName: rule.fieldName,
+          sensitivityMode: rule.sensitivityMode ?? "CAPTURE",
+          createdAt: new Date(),
+          updatedAt: null,
+        })
+        .returningAll()
+        .executeTakeFirst();
+    }
+  }
+
+  return ok({ policy: policy! });
+}

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

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

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

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { CommandContext } from "../../../shared";
+import { InsufficientPermissionError } from "../../../shared/errors";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { PolicyNotFoundError, InvalidStateError, UnauthorizedError } from "../lib/errors.generated";
+import { draftPolicy, activePolicy, inactivePolicy } from "../testing/fixtures";
+import { run } from "./deactivateAuditPolicy";
+import { deactivateAuditPolicy } from "./deactivateAuditPolicy.generated";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["audit:deactivateAuditPolicy"],
+};
+
+describe("deactivateAuditPolicy", () => {
+  it("deactivates ACTIVE policy to INACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activePolicy); // policy lookup
+    spies.update.mockReturnValue({ ...activePolicy, status: "INACTIVE" });
+
+    const result = await run(db, { policyId: activePolicy.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy.status).toBe("INACTIVE");
+    }
+  });
+
+  it("stops new audit capture after deactivation", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activePolicy);
+    spies.update.mockReturnValue({ ...activePolicy, status: "INACTIVE" });
+
+    const result = await run(db, { policyId: activePolicy.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy.status).toBe("INACTIVE");
+    }
+    // Verify that the DB update sets status to INACTIVE, which is the gate that stops logAuditEvent capture
+    expect(spies.set).toHaveBeenCalledWith(expect.objectContaining({ status: "INACTIVE" }));
+    expect(spies.update).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not delete previously recorded audit entries", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activePolicy);
+    spies.update.mockReturnValue({ ...activePolicy, status: "INACTIVE" });
+
+    const result = await run(db, { policyId: activePolicy.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policy.status).toBe("INACTIVE");
+    }
+    // Verify no delete operations are issued — previously recorded audit entries are preserved
+    expect(spies.delete).not.toHaveBeenCalled();
+  });
+
+  it("rejects deactivation of DRAFT policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+
+    const result = await run(db, { policyId: draftPolicy.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateError);
+    }
+  });
+
+  it("rejects deactivation 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 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 = deactivateAuditPolicy();
+    const noPermCtx: CommandContext = {
+      actorId: "test-actor",
+      permissions: [],
+    };
+
+    const result = await command(db, { policyId: activePolicy.id }, noPermCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InsufficientPermissionError);
+    }
+  });
+
+  it("rejects when company-scoped caller deactivates policy for a different company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activePolicy); // policy with companyId: "company-1"
+    const scopedCtx = { ...ctx, companyId: "company-2" };
+
+    const result = await run(db, { policyId: activePolicy.id }, scopedCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+
+  it("rejects when global-scoped caller deactivates company-scoped policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activePolicy); // policy with companyId: "company-1"
+    const globalCtx = { ...ctx, companyId: null };
+
+    const result = await run(db, { policyId: activePolicy.id }, globalCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+});

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

@@ -0,0 +1,58 @@
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { PolicyNotFoundError, InvalidStateError, UnauthorizedError } from "../lib/errors.generated";
+
+export interface DeactivateAuditPolicyInput {
+  policyId: string;
+}
+
+/**
+ * Function: deactivateAuditPolicy
+ *
+ * Transitions an audit policy from ACTIVE to INACTIVE status, stopping new
+ * audit capture for the specified entity, operation type, and scope. Previously
+ * recorded audit entries are not deleted.
+ */
+export async function run(db: Transaction, input: DeactivateAuditPolicyInput, 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 ACTIVE
+  if (existing.status !== "ACTIVE") {
+    return err(new InvalidStateError(policyId));
+  }
+
+  // 3. Set status INACTIVE
+  const policy = await db
+    .updateTable("AuditPolicy")
+    .set({
+      status: "INACTIVE",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", policyId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ policy: policy! });
+}

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

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

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

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { PolicyNotFoundError, InvalidStateError, UnauthorizedError } from "../lib/errors.generated";
+import { InsufficientPermissionError } from "../../../shared";
+import { draftPolicy, activePolicy, inactivePolicy } from "../testing/fixtures";
+import { run } from "./deleteAuditPolicy";
+import { deleteAuditPolicy } from "./deleteAuditPolicy.generated";
+
+const ctx = { actorId: "test-actor", permissions: ["audit:deleteAuditPolicy"] };
+
+describe("deleteAuditPolicy", () => {
+  it("deletes DRAFT policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+
+    const result = await run(db, { policyId: draftPolicy.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.policyId).toBe(draftPolicy.id);
+    }
+  });
+
+  it("deletes associated PolicyFieldRules when deleting policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+
+    const result = await run(db, { policyId: draftPolicy.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    // delete spy should be called twice: once for PolicyFieldRules, once for AuditPolicy
+    expect(spies.delete).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not affect previously recorded audit entries", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftPolicy);
+
+    const result = await run(db, { policyId: draftPolicy.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    // delete spy is called only for PolicyFieldRule and AuditPolicy, not AuditEntry
+    expect(spies.delete).toHaveBeenCalledTimes(2);
+  });
+
+  it("rejects deletion 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 deletion 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 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 denied = { actorId: "test-actor", permissions: [] as string[] };
+    const cmd = deleteAuditPolicy();
+
+    const result = await cmd(db, { policyId: draftPolicy.id }, denied);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InsufficientPermissionError);
+    }
+  });
+
+  it("rejects when company-scoped caller deletes 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: draftPolicy.id }, scopedCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+
+  it("rejects when global-scoped caller deletes 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: draftPolicy.id }, globalCtx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnauthorizedError);
+    }
+  });
+});

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

@@ -0,0 +1,52 @@
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { PolicyNotFoundError, InvalidStateError, UnauthorizedError } from "../lib/errors.generated";
+
+export interface DeleteAuditPolicyInput {
+  policyId: string;
+}
+
+/**
+ * Function: deleteAuditPolicy
+ *
+ * Permanently removes a DRAFT audit policy and its associated field rules.
+ * Only policies in DRAFT status can be deleted.
+ */
+export async function run(db: Transaction, input: DeleteAuditPolicyInput, ctx: CommandContext) {
+  const { policyId } = input;
+
+  // 1. Find policy by ID with forUpdate
+  const existing = await db
+    .selectFrom("AuditPolicy")
+    .selectAll()
+    .where("id", "=", policyId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new PolicyNotFoundError(policyId));
+  }
+
+  // Scope authorization checks
+  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));
+    }
+  }
+
+  // 2. Not DRAFT → InvalidStateError
+  if (existing.status !== "DRAFT") {
+    return err(new InvalidStateError(policyId));
+  }
+
+  // 3. Delete associated PolicyFieldRules
+  await db.deleteFrom("PolicyFieldRule").where("auditPolicyId", "=", policyId).execute();
+
+  // 4. Delete AuditPolicy
+  await db.deleteFrom("AuditPolicy").where("id", "=", policyId).execute();
+
+  return ok({ policyId });
+}

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

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