Initial commit: Port Nimara CRM (Layers 0-4)

Full CRM rebuild with Next.js 15, TypeScript, Tailwind, Drizzle ORM,
PostgreSQL, Redis, BullMQ, MinIO, and Socket.io. Includes 461 source
files covering clients, berths, interests/pipeline, documents/EOI,
expenses/invoices, email, notifications, dashboard, admin, and
client portal. CI/CD via Gitea Actions with Docker builds.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

tests/unit/security-permission-checks.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Security: Permission Deep Merge
+ *
+ * Verifies that deepMerge() correctly applies port-level role permission
+ * overrides on top of base role permissions.
+ *
+ * This function is the core of the permission override system:
+ *   - Base role permissions are defined at the role level
+ *   - Port-specific overrides are merged in on top
+ *   - deepMerge must not drop base keys or silently fail
+ *
+ * The security guarantee: a permission set to `false` in the base role
+ * CAN be upgraded to `true` by an explicit override, but only for the
+ * specific port.  This must work correctly in both directions.
+ */
+import { describe, expect, it } from 'vitest';
+import { deepMerge } from '@/lib/api/helpers';
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('deepMerge — basic override behaviour', () => {
+  it('override replaces a single base value', () => {
+    const base = { clients: { view: true, create: true, delete: false } };
+    const override = { clients: { delete: true } };
+    const result = deepMerge(base, override);
+    expect((result.clients as Record<string, boolean>).delete).toBe(true);
+  });
+
+  it('preserves base keys not mentioned in override', () => {
+    const base = { clients: { view: true, create: true, delete: false } };
+    const override = { clients: { delete: true } };
+    const result = deepMerge(base, override);
+    expect((result.clients as Record<string, boolean>).view).toBe(true);
+    expect((result.clients as Record<string, boolean>).create).toBe(true);
+  });
+
+  it('override can add a new permission key that did not exist in base', () => {
+    const base = { clients: { view: true } };
+    const override = { clients: { export: true } };
+    const result = deepMerge(base, override);
+    expect((result.clients as Record<string, boolean>).export).toBe(true);
+    // Base key still present
+    expect((result.clients as Record<string, boolean>).view).toBe(true);
+  });
+
+  it('override can revoke a permission (true → false)', () => {
+    const base = { clients: { view: true, delete: true } };
+    const override = { clients: { delete: false } };
+    const result = deepMerge(base, override);
+    expect((result.clients as Record<string, boolean>).delete).toBe(false);
+    expect((result.clients as Record<string, boolean>).view).toBe(true);
+  });
+});
+
+describe('deepMerge — nested structure preservation', () => {
+  it('deep merges two levels of nesting without data loss', () => {
+    const base = { admin: { manage_users: false, manage_settings: true } };
+    const override = { admin: { manage_users: true } };
+    const result = deepMerge(base, override);
+    expect((result.admin as Record<string, boolean>).manage_users).toBe(true);
+    expect((result.admin as Record<string, boolean>).manage_settings).toBe(true);
+  });
+
+  it('handles three levels of nesting', () => {
+    const base = { reports: { export: { csv: true, pdf: false } } };
+    const override = { reports: { export: { pdf: true } } };
+    const result = deepMerge(base, override);
+    const exportPerms = (result.reports as Record<string, unknown>).export as Record<string, boolean>;
+    expect(exportPerms.pdf).toBe(true);
+    expect(exportPerms.csv).toBe(true);
+  });
+
+  it('completely separate top-level keys are merged independently', () => {
+    const base = { clients: { view: true }, invoices: { view: false } };
+    const override = { invoices: { view: true } };
+    const result = deepMerge(base, override);
+    expect((result.clients as Record<string, boolean>).view).toBe(true);
+    expect((result.invoices as Record<string, boolean>).view).toBe(true);
+  });
+
+  it('adds entirely new top-level resource permission group', () => {
+    const base = { clients: { view: true } };
+    const override = { pipeline: { view: true, manage: true } };
+    const result = deepMerge(base, override);
+    expect((result.pipeline as Record<string, boolean>).view).toBe(true);
+    expect((result.pipeline as Record<string, boolean>).manage).toBe(true);
+    // Original unchanged
+    expect((result.clients as Record<string, boolean>).view).toBe(true);
+  });
+});
+
+describe('deepMerge — immutability', () => {
+  it('does not mutate the target object', () => {
+    const base = { clients: { view: true, delete: false } };
+    const override = { clients: { delete: true } };
+    deepMerge(base, override);
+    // Original base must be unmodified
+    expect((base.clients as Record<string, boolean>).delete).toBe(false);
+  });
+
+  it('does not mutate the source object', () => {
+    const base = { clients: { view: true } };
+    const override = { clients: { view: false } };
+    deepMerge(base, override);
+    expect((override.clients as Record<string, boolean>).view).toBe(false); // unchanged
+  });
+});
+
+describe('deepMerge — edge cases', () => {
+  it('empty override returns a copy of the base', () => {
+    const base = { clients: { view: true } };
+    const result = deepMerge(base, {});
+    expect(result).toEqual(base);
+  });
+
+  it('empty base + non-empty override returns the override', () => {
+    const override = { clients: { view: true } };
+    const result = deepMerge({}, override);
+    expect(result).toEqual(override);
+  });
+
+  it('both empty returns empty object', () => {
+    const result = deepMerge({}, {});
+    expect(result).toEqual({});
+  });
+
+  it('scalar override value wins over nested base value (array not merged)', () => {
+    // When source has a non-object value for a key that base has as an object,
+    // the source scalar replaces the base object — this is the defined behaviour
+    const base = { meta: { x: 1 } };
+    const override = { meta: 'string-value' };
+    const result = deepMerge(base, override as unknown as Record<string, unknown>);
+    expect(result.meta).toBe('string-value');
+  });
+
+  it('null override value replaces nested base object', () => {
+    const base = { clients: { view: true } };
+    const override = { clients: null };
+    const result = deepMerge(base, override as unknown as Record<string, unknown>);
+    expect(result.clients).toBeNull();
+  });
+});