pn-new-crm/tests/unit/security-permission-checks.test.ts

/**
 * 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();
  });
});