The acl security register

it('authorizes a forged subject exactly as it would a real one', () => {
  // No defence. The engine has no channel to ask where the subject came from,
  // and this is what that costs.
  const access = foreign([
    permission('order', 'refund', {
      rules: [when({ field: 'subject.role', op: 'eq', value: 'owner' })],
    }),
  ]);
 
  expect(access.can({ role: 'owner' }, 'order', 'refund').allowed).toBe(true);
});

it('names the handle that makes the checked path the easy one', () => {
  const access = foreign([
    permission('listing', 'read', { rules: [always] }),
  ]);
  const bound = access.authorize({ id: 'u1' });
 
  expect(typeof bound.can).toBe('function');
  expect(bound.can('listing', 'read').allowed).toBe(true);
});

it('carries no freshness token a writer could check', () => {
  const access = foreign([
    permission('question', 'update', {
      rules: [
        when({ field: 'object.askedBy', op: 'eq', path: 'subject.id' }),
      ],
    }),
  ]);
  const decision = access.can({ id: 'u1' }, 'question', 'update', {
    id: 'q1',
    askedBy: 'u1',
  });
 
  // The decision names the key, the reason and the rule. Nothing in it ties
  // the answer to a version of the row it was answered about.
  expect(Object.keys(decision).sort()).toEqual([
    'allowed',
    'key',
    'reason',
    'rule',
  ]);
});

it('grants the subject that added itself to the field the rule reads', () => {
  // No defence. The engine cannot know which object fields the subject can
  // write, so this is the grant the acl contract warns about under "What a
  // condition may read", shown working.
  const access = foreign([
    permission('wishlist', 'read', {
      rules: [
        when({ field: 'object.sharedWith', op: 'contains', value: 'u1' }),
      ],
    }),
  ]);
 
  expect(
    access.can({ id: 'u1' }, 'wishlist', 'read', { sharedWith: ['u2'] })
      .allowed,
  ).toBe(false);
  expect(
    access.can({ id: 'u1' }, 'wishlist', 'read', { sharedWith: ['u2', 'u1'] })
      .allowed,
  ).toBe(true);
});

it('answers a browser and a server identically, which is why the runtime decides', () => {
  const access = foreign([
    permission('listing', 'delete', { rules: [always] }),
  ]);
 
  // The same call, the same answer, wherever it runs. Nothing in the return
  // type separates an authoritative decision from a rendering hint.
  expect(access.can({ id: 'u1' }, 'listing', 'delete').allowed).toBe(true);
});

it('exposes every key, condition and field name it was built from', () => {
  const access = foreign([
    permission('order', 'mark-down', {
      rules: [when({ field: 'subject.role', op: 'eq', value: 'owner' })],
      fields: { fields: ['*', '!supplierCost'] },
    }),
  ]);
 
  expect(JSON.stringify(access.matrix)).toContain('owner');
  expect(JSON.stringify(access.matrix)).toContain('supplierCost');
});

it('opens a closed window for a caller that supplies its own instant', () => {
  const access = foreign([
    permission('listing', 'preorder', {
      rules: [when({ field: 'now', op: 'before', value: '2020-01-01' })],
    }),
  ]);
 
  expect(access.can({}, 'listing', 'preorder').allowed).toBe(false);
  expect(
    access.can({}, 'listing', 'preorder', undefined, '2019-06-01').allowed,
  ).toBe(true);
});

it('decides the deny side and the allow side against separate reads', () => {
  // No defence. The matrix is copied and frozen; the subject is the app's own
  // data and is not. A subject whose getter answers twice decides twice.
  let read = 0;
  const subject: Record<string, unknown> = {};
  Object.defineProperty(subject, 'role', {
    enumerable: true,
    get() {
      read++;
      return read === 1 ? 'nobody' : 'owner';
    },
  });
 
  const access = foreign([
    permission('order', 'refund', {
      rules: [when({ field: 'subject.role', op: 'eq', value: 'owner' })],
      denyRules: [when({ field: 'subject.role', op: 'eq', value: 'owner' })],
    }),
  ]);
 
  expect(access.can(subject, 'order', 'refund').allowed).toBe(true);
  expect(access.can({ role: 'owner' }, 'order', 'refund').allowed).toBe(
    false,
  );
});

/** The hand-rolled filter `pickAllowedFields` exists to replace. */
const naiveFilter = (
  decision: FieldDecision,
  proposed: Record<string, unknown>,
): Record<string, unknown> =>
  Object.fromEntries(
    Object.entries(proposed).filter(
      ([key]) => decision.fields[key] !== 'denied',
    ),
  );
 
const access = () =>
  foreign([
    permission('account', 'update', {
      rules: [always],
      fields: {
        fields: ['*', '!role'],
        membership: { targets: ['none', 'library'] },
      },
    }),
  ]);
 
const decisionFor = (proposed: Record<string, unknown>): FieldDecision =>
  access().canFields(
    { id: 'u1' },
    'account',
    'update',
    { id: 'u1', membership: 'none' },
    'write',
    proposed,
  );
 
it('shows the hand-rolled deny-list filter writing what the decision refused', () => {
  const proposed = { '*': 'everything', name: 'Grace', membership: 'staff' };
  const decision = decisionFor(proposed);
 
  expect(decision.fields['membership']).toBe('denied');
  // `*` is syntax and names no field, so the decision holds no entry for it,
  // and a filter keeping every key not marked 'denied' keeps it.
  expect(naiveFilter(decision, proposed)).toEqual({
    '*': 'everything',
    name: 'Grace',
  });
  expect(pickAllowedFields(decision, proposed)).toEqual({ name: 'Grace' });
});

const configOnly = () =>
  foreign([
    permission('account', 'update', {
      rules: [always],
      fields: { role: { targets: ['customer'] } },
    }),
  ]);
 
it('leaves every unnamed key writable when only a config is given', () => {
  const proposed = { role: 'owner', isOwner: true, credit: 500 };
  const decision = configOnly().canFields(
    { id: 'u1' },
    'account',
    'update',
    { id: 'u1' },
    'write',
    proposed,
  );
 
  expect(decision.fields['role']).toBe('denied');
  expect(decision.fields['isOwner']).toBe('allowed');
  expect(pickAllowedFields(decision, proposed)).toEqual({
    isOwner: true,
    credit: 500,
  });
});

const owned = () =>
  foreign([
    permission('order', 'read', {
      rules: [
        when({ field: 'object.customerId', op: 'eq', path: 'subject.id' }),
      ],
    }),
  ]);
 
it('refuses rather than allows when the projection omits the owner', () => {
  const decision = owned().can({ id: 'u1' }, 'order', 'read', {
    id: 'order-2026-0042',
  });
 
  expect(decision.allowed).toBe(false);
  expect(decision.reason).toBe('unevaluable');
  expect(decision.missing).toEqual(['object.customerId']);
});

const access = () =>
  foreign([
    permission('order', 'read', {
      rules: [
        when(
          { field: 'object.customerId', op: 'eq', path: 'subject.id' },
          { field: 'object.table', op: 'eq', path: 'subject.table' },
        ),
      ],
    }),
  ]);
 
it('shows reading anything but `allowed` as the grant going wrong', () => {
  const decision = access().can({ id: 'u1', table: 3 }, 'order', 'read', {
    id: 'order-2026-0042',
  });
 
  // `unevaluable` is not `denied`, so a consumer gating on the reason string
  // rather than on `allowed` grants what the engine refused.
  expect(decision.reason === 'denied').toBe(false);
  expect(decision.allowed).toBe(false);
});

// Each name reads as `rôle` or `role` on screen, and its code points differ.
const composed = 'rôle'; // ô is U+00F4
const decomposed = 'rôle'; // o, then the combining U+0302
const widened = 'ro​le'; // ro, a zero-width U+200B, then le
const homoglyph = 'гole'; // Cyrillic U+0433 in place of r
 
const access = () =>
  foreign([
    permission('account', 'update', {
      rules: [always],
      fields: { fields: ['*', `!${composed}`] },
    }),
  ]);
 
it('treats a differently spelled name as a different field', () => {
  const proposed = {
    [decomposed]: 'owner',
    [widened]: 'owner',
    [homoglyph]: 'owner',
    ROLE: 'owner',
  };
  const decision = access().canFields(
    { id: 'u1' },
    'account',
    'update',
    {},
    'write',
    proposed,
  );
 
  for (const name of [decomposed, widened, homoglyph, 'ROLE']) {
    expect(decision.fields[name], name).toBe('allowed');
  }
  // The consumer's normalisation, not the engine's: a store that folds these
  // together gets four names for one column and the exclusion is a bypass.
  expect(decomposed.normalize('NFC')).toBe(composed);
});

const rule = (op: 'eq' | 'in' | 'not-in') =>
  foreign([
    permission('listing', 'read', {
      rules: [
        when({
          field: 'subject.table',
          op,
          value: op === 'eq' ? Number.NaN : [Number.NaN],
        }),
      ],
    }),
  ]);
 
it('never matches an equality against NaN', () => {
  expect(
    rule('eq').can({ table: Number.NaN }, 'listing', 'read').allowed,
  ).toBe(false);
});
 
it('matches a membership test against NaN', () => {
  // `includes` is SameValueZero, `===` is not. A list is the more permissive
  // operator for this one value, so a rule that means "never" is written as
  // an equality.
  expect(
    rule('in').can({ table: Number.NaN }, 'listing', 'read').allowed,
  ).toBe(true);
  expect(
    rule('not-in').can({ table: Number.NaN }, 'listing', 'read').allowed,
  ).toBe(false);
});

it('keeps granting what a revoked matrix granted until it is replaced', () => {
  const stale = foreign(
    [permission('listing', 'delete', { rules: [always] })],
    {
      version: 1,
    },
  );
  const current = foreign([permission('listing', 'delete', { rules: [] })], {
    version: 2,
  });
 
  expect(stale.can({ id: 'u1' }, 'listing', 'delete').allowed).toBe(true);
  expect(current.can({ id: 'u1' }, 'listing', 'delete').allowed).toBe(false);
  // Comparing the two versions and failing closed is the consumer's; the
  // access object holds no channel to learn it has been superseded.
  expect(stale.version).not.toBe(current.version);
});

const access = () =>
  foreign([
    permission('listing', 'update', {
      rules: [when({ field: 'subject.role', op: 'eq', value: 'bookseller' })],
      fields: { fields: ['*'] },
    }),
  ]);
 
it('reports every field writable while the action is refused', () => {
  const decision = access().canFields(
    { id: 'u1', role: 'nobody' },
    'listing',
    'update',
    { id: 'l1' },
    'write',
    { title: 'x' },
  );
 
  // The maps answer "what would be editable", so a blocked caller can still
  // render the form. They are not the gate.
  expect(decision.fields['title']).toBe('allowed');
  expect(decision.action.allowed).toBe(false);
  expect(decision.allowed).toBe(false);
});

const editable = () =>
  foreign([
    permission('account', 'update', {
      rules: [always],
      fields: { fields: ['*', '!role'] },
    }),
  ]);
 
it('decides a key that exists only in the proposed write', () => {
  const decision = editable().canFields(
    { id: 'u1' },
    'account',
    'update',
    { id: 'u1', name: 'Ada' },
    'write',
    { name: 'Grace', role: 'owner' },
  );
 
  expect(decision.fields['role']).toBe('denied');
  expect(decision.allowed).toBe(false);
});

const guarded = () =>
  foreign([
    permission('listing', 'read', {
      rules: [always],
      denyRules: [when({ field: 'object.status', op: 'eq', value: 'draft' })],
    }),
  ]);
 
it('refuses when the projection lacks the field the deny reads', () => {
  const decision = guarded().can({ id: 'u1' }, 'listing', 'read', {
    id: 'l1',
  });
 
  expect(decision.allowed).toBe(false);
  expect(decision.reason).toBe('unevaluable');
  expect(decision.missing).toEqual(['object.status']);
});

it('refuses a permission with no rules at all', () => {
  const access = foreign([permission('listing', 'read')]);
 
  expect(access.can({ id: 'u1' }, 'listing', 'read').allowed).toBe(false);
  expect(access.can({ id: 'u1' }, 'listing', 'read').reason).toBe(
    'no-rule-matched',
  );
});

it('refuses an unknown key on a foreign matrix', () => {
  const access = foreign([
    permission('listing', 'read', { rules: [always] }),
  ]);
  const decision = access.can({ id: 'u1' }, 'anything', 'at-all');
 
  expect(decision.allowed).toBe(false);
  expect(decision.reason).toBe('unknown-action');
});

/**
 * The keys a foreign write actually carries: authoring tokens, prototype
 * names, unicode shapes, and names long enough to be a shape of their own.
 */
const KEYS = [
  'name',
  'role',
  '__proto__',
  'constructor',
  'prototype',
  '*',
  '!role',
  '!*',
  'ro​le',
  'róle',
  'rôle',
  'rôle',
  '',
  ' role',
  'role ',
  'ROLE',
  'a'.repeat(4096),
] as const;
 
it('never picks a key the decision did not mark allowed', () => {
  let built = 0;
  for (let seed = 1; seed <= 400; seed++) {
    const gen = new Gen(rng(seed));
    // An exclusion such as `!role` is valid only beside the `*` baseline, so
    // a drawn list carrying one gets the baseline too. The attack is the
    // write, and the list only has to be one the engine accepts.
    const drawn = gen
      .list(4, () => gen.pick([...KEYS, '*', '!role']))
      .filter((n) => n.length > 0);
    const valid = drawn.some((n) => n.startsWith('!'))
      ? ['*', ...drawn]
      : drawn;
    const names = gen.bool(0.6) ? valid : undefined;
    let access: ReturnType<typeof foreign>;
    try {
      access = foreign([
        permission('account', 'update', {
          rules: [always],
          ...(names ? { fields: { fields: names } } : {}),
        }),
      ]);
    } catch (error) {
      // A drawn list may be one construction refuses: an entry beside its
      // own exclusion, or a token spelled as a path. Each refusal is an
      // InvalidPermissionError on a list entry, and it names the permission.
      expect(error, `seed ${seed}`).toBeInstanceOf(InvalidPermissionError);
      expect((error as InvalidPermissionError).key, `seed ${seed}`).toBe(
        'account.update',
      );
      expect((error as InvalidPermissionError).field, `seed ${seed}`).toMatch(
        /^fields\.fields\[\d+\]$/,
      );
      continue;
    }
    built++;
 
    const proposed: Record<string, unknown> = {};
    for (const key of gen.list(6, () => gen.pick(KEYS))) {
      Object.defineProperty(proposed, key, {
        value: gen.pick(['x', 1, null, { isOwner: true }]),
        enumerable: true,
        writable: true,
        configurable: true,
      });
    }
 
    const decision = access.canFields(
      { id: 'u1' },
      'account',
      'update',
      {},
      'write',
      proposed,
    );
    const writable = pickAllowedFields(decision, proposed);
 
    for (const key of Object.keys(writable)) {
      expect(decision.fields[key], `seed ${seed}: ${key}`).toBe('allowed');
      expect(key, `seed ${seed}`).not.toBe('__proto__');
      expect(key, `seed ${seed}`).not.toBe('*');
      expect(key.startsWith('!'), `seed ${seed}: ${key}`).toBe(false);
    }
 
    const row: Record<string, unknown> = {};
    Object.assign(row, writable);
 
    expect(Object.getPrototypeOf(row), `seed ${seed}`).toBe(Object.prototype);
    expect(({} as Record<string, unknown>)['isOwner']).toBeUndefined();
  }
 
  // Most lists build, so the writes above ran against real decisions.
  expect(built).toBeGreaterThan(100);
});

const probe = (field: string): Condition => ({
  field,
  op: 'eq',
  value: 'owner',
});
 
it('reads no inherited member off the subject', () => {
  const access = foreign([
    permission('listing', 'read', {
      rules: [when(probe('subject.toString'))],
    }),
  ]);
 
  expect(access.can({ id: 'u1' }, 'listing', 'read').allowed).toBe(false);
});

const machine = () =>
  foreign([
    permission('listing', 'update', {
      rules: [always],
      fields: { status: { transitions: { draft: ['published'] } } },
    }),
  ]);
 
it('denies a current value that names an inherited member', () => {
  for (const current of ['toString', 'constructor', '__proto__']) {
    const decision = machine().canFields(
      { id: 'u1' },
      'listing',
      'update',
      { status: current },
      'write',
      { status: 'published' },
    );
 
    expect(decision.fields['status']).toBe('denied');
    expect(decision.reasons['status']).toBe('transition-failed');
  }
});

const access = () =>
  foreign([
    permission('account', 'update', {
      rules: [always],
      fields: { fields: ['*', '!role'] },
    }),
  ]);
 
it('carries no __proto__ key into the decision', () => {
  const proposed = fromJson(
    '{"__proto__": {"isOwner": true}, "name": "Grace"}',
  );
  const decision = access().canFields(
    { id: 'u1' },
    'account',
    'update',
    {},
    'write',
    proposed,
  );
 
  expect(Object.hasOwn(decision.fields, '__proto__')).toBe(false);
});
 
/**
 * The guarantee holds at every level the rules descend into. A subtree no
 * rule reaches is copied by reference, own `__proto__` key included, so a
 * consumer that merges such a subtree skips the name itself.
 */
it('drops a nested __proto__ where the rules descend, and copies an unwalked subtree whole', () => {
  const proposed = fromJson(
    '{"address": {"__proto__": {}, "*": 1, "!role": 2, "city": "Lund"}}',
  );
  const decide = (fields: string[]) =>
    foreign([
      permission('account', 'update', {
        rules: [always],
        fields: { fields },
      }),
    ]).canFields(
      { id: 'u1' },
      'account',
      'update',
      { address: { city: 'Malmo' } },
      'write',
      proposed,
    );
  const walked = pickAllowedFields(
    decide(['*', '!address.zip']),
    proposed,
  ) as { address: object };
  const unwalked = pickAllowedFields(decide(['*']), proposed) as {
    address: object;
  };
 
  expect(Object.hasOwn(walked.address, '__proto__')).toBe(false);
  expect(unwalked.address).toBe(proposed['address']);
  expect(Object.hasOwn(unwalked.address, '__proto__')).toBe(true);
});

const access = () =>
  foreign([
    permission('account', 'update', {
      rules: [always],
      fields: { fields: ['*', '!role'] },
    }),
  ]);
 
it('drops a proposed key spelled as a baseline or an exclusion', () => {
  const proposed = { '*': 'everything', '!role': 'owner', name: 'Grace' };
  const decision = access().canFields(
    { id: 'u1' },
    'account',
    'update',
    {},
    'write',
    proposed,
  );
 
  expect(Object.keys(decision.fields)).toEqual(['name']);
  expect(pickAllowedFields(decision, proposed)).toEqual({ name: 'Grace' });
});
 
/**
 * The guarantee holds at every level the rules descend into. A subtree no
 * rule reaches is copied by reference with its literal keys.
 */
it('drops nested tokens where the rules descend, and copies an unwalked subtree whole', () => {
  const proposed = fromJson(
    '{"address": {"__proto__": {}, "*": 1, "!role": 2, "city": "Lund"}}',
  );
  const decide = (fields: string[]) =>
    foreign([
      permission('account', 'update', {
        rules: [always],
        fields: { fields },
      }),
    ]).canFields(
      { id: 'u1' },
      'account',
      'update',
      { address: { city: 'Malmo' } },
      'write',
      proposed,
    );
  const walked = pickAllowedFields(
    decide(['*', '!address.zip']),
    proposed,
  ) as { address: object };
  const unwalked = pickAllowedFields(decide(['*']), proposed) as {
    address: object;
  };
 
  expect(Object.keys(walked.address)).toEqual(['city']);
  expect(Object.keys(unwalked.address)).toEqual([
    '__proto__',
    '*',
    '!role',
    'city',
  ]);
});

it('ignores a mutation of the matrix the caller passed in', () => {
  const source: Permission[] = [permission('listing', 'read', { rules: [] })];
  const access = foreign(source);
 
  (source[0] as { rules: unknown }).rules = [always];
 
  expect(access.can({ id: 'u1' }, 'listing', 'read').allowed).toBe(false);
});

/** A property that answers the first read one way and every later one another. */
function twoFaced<T>(first: T, then: T): { get(): T } {
  let read = 0;
  return {
    get: () => (read++ === 0 ? first : then),
  };
}
 
it('cannot turn a conditional rule into an unconditional one', () => {
  const face = twoFaced<readonly Condition[]>(
    [{ field: 'subject.role', op: 'eq', value: 'owner' }],
    [],
  );
  const access = local([
    permission('listing', 'read', {
      rules: [
        {
          get when() {
            return face.get();
          },
        },
      ],
    }),
  ]);
 
  expect(access.can({ role: 'nobody' }, 'listing', 'read').allowed).toBe(
    false,
  );
});

const machine = () =>
  foreign([
    permission('listing', 'update', {
      rules: [always],
      fields: { status: { transitions: { draft: ['published'] } } },
    }),
  ]);
 
const hostile: readonly (readonly [string, unknown])[] = [
  ['a value with no prototype', Object.create(null)],
  [
    'a value whose coercion throws',
    {
      toString: () => {
        throw new Error('boom');
      },
    },
  ],
  ['a symbol', Symbol('draft')],
  ['a list', ['draft']],
  ['a value that coerces to a legal edge', { toString: () => 'draft' }],
];
 
for (const [name, current] of hostile) {
  it(`denies a transition from ${name}`, () => {
    const decision = machine().canFields(
      { id: 'u1' },
      'listing',
      'update',
      { status: current },
      'write',
      { status: 'published' },
    );
 
    expect(decision.fields['status']).toBe('denied');
    expect(decision.reasons['status']).toBe('transition-failed');
  });
}

it('reads the subject once per permission across the whole matrix', () => {
  const access = foreign(
    Array.from({ length: 2_000 }, (_, i) =>
      permission(`w${i}`, 'read', {
        rules: [when({ field: 'subject.id', op: 'eq', value: 'u1' })],
      }),
    ),
  );
  const { subject, reads, reset } = countingSubject({ id: 'u1' });
  reset();
  access.capabilities(subject);
 
  expect(reads()).toBe(2_000);
});

const equals = (value: unknown) =>
  foreign([
    permission('listing', 'read', {
      rules: [when({ field: 'subject.table', op: 'eq', value })],
    }),
  ]);
 
it('does not match a string against the number it spells', () => {
  expect(equals(1).can({ table: '1' }, 'listing', 'read').allowed).toBe(
    false,
  );
  expect(equals('1').can({ table: 1 }, 'listing', 'read').allowed).toBe(
    false,
  );
});

it('refuses the deny side ahead of an allow rule that matched', () => {
  const denied = when({ field: 'now', op: 'after', value: '2020-01-01' });
  const access = foreign([
    permission('listing', 'preorder', {
      rules: [always, when({ field: 'subject.id', op: 'eq', value: 's1' })],
      denyRules: [denied],
    }),
  ]);
 
  const decision = access.can(
    { id: 's1' },
    'listing',
    'preorder',
    undefined,
    'not a date' as never,
  );
  expect(decision.allowed).toBe(false);
  expect(decision.reason).toBe('unusable-clock');
  expect(decision.rule).toBe(ruleId(denied, 'deny'));
});

/**
 * `['*', '!address.street']` names a key below `address`. The decision
 * carries the street as denied and `pickAllowedFields` rebuilds the parent
 * without it, so the response holds the city and no street.
 */
const row = {
  id: 'o1',
  address: { city: 'Malmo', street: 'Storgatan 1' },
};
const readable = () =>
  foreign([
    permission('order', 'read', {
      rules: [always],
      fields: { fields: ['*', '!address.street'] },
    }),
  ]);
 
it('hides the nested key and keeps the rest of the parent', () => {
  const decision = readable().canFields(
    { id: 'u1' },
    'order',
    'read',
    row,
    'read',
  );
 
  expect(decision.fields['address.street']).toBe('denied');
  expect(pickAllowedFields(decision, row)).toEqual({
    id: 'o1',
    address: { city: 'Malmo' },
  });
});
 
it('leaves the excluded key out of the picked parent on the hydrated path', () => {
  const decision = local([
    permission('order', 'read', {
      rules: [always],
      fields: { fields: ['*', '!address.street'] },
    }),
  ]).canFields({ id: 'u1' }, 'order', 'read', row, 'read');
 
  expect(pickAllowedFields(decision, row)).not.toHaveProperty(
    'address.street',
  );
  expect(
    (pickAllowedFields(decision, row) as { address: object }).address,
  ).not.toHaveProperty('street');
});
 
it('hides a flat key that spells the excluded path', () => {
  const flat = { id: 'o1', 'address.street': 'Storgatan 1' };
  const decision = readable().canFields(
    { id: 'u1' },
    'order',
    'read',
    flat,
    'read',
  );
 
  expect(decision.fields['address\\.street']).toBe('denied');
  expect(pickAllowedFields(decision, flat)).toEqual({ id: 'o1' });
});
 
/**
 * Index paths are not supported. A rule that indexes into an array, such as
 * `!items.0.price`, would otherwise decide nothing and leave every price in
 * the response, so the array is hidden whole.
 */
it.each([['!items.0.price'], ['!items.0']])(
  'hides an array that %s indexes into, on both axes',
  (exclusion) => {
    const order = { id: 'o1', items: [{ price: 10, sku: 'a' }] };
    const access = foreign([
      permission('order', 'read', {
        rules: [always],
        fields: { fields: ['*', exclusion] },
      }),
      permission('order', 'update', {
        rules: [always],
        fields: { fields: ['*', exclusion] },
      }),
    ]);
    const read = access.canFields(
      { id: 'u1' },
      'order',
      'read',
      order,
      'read',
    );
    const proposed = { items: [{ price: 0, sku: 'a' }] };
    const write = access.canFields(
      { id: 'u1' },
      'order',
      'update',
      order,
      'write',
      proposed,
    );
 
    expect(read.fields['items']).toBe('denied');
    expect(read.reasons['items']).toBe('not-traversable');
    expect(pickAllowedFields(read, order)).toEqual({ id: 'o1' });
    expect(write.reasons['items']).toBe('not-traversable');
    expect(pickAllowedFields(write, proposed)).toEqual({});
  },
);

/**
 * `address: null` would erase a street the caller may not write, so the
 * parent is refused as a whole and nothing of it is picked.
 */
const access = () =>
  foreign([
    permission('order', 'update', {
      rules: [always],
      fields: { fields: ['*', '!address.street'] },
    }),
  ]);
const stored = {
  id: 'o1',
  address: { city: 'Malmo', street: 'Storgatan 1' },
};
 
it.each([
  ['null', null],
  ['a string', 'elsewhere'],
  ['an array', []],
  ['an empty object', {}],
])('refuses a write that replaces the address with %s', (_, value) => {
  const proposed = { address: value };
  const decision = access().canFields(
    { id: 'u1' },
    'order',
    'update',
    stored,
    'write',
    proposed,
  );
 
  expect(decision.fields['address']).toBe('denied');
  expect(decision.reasons['address']).toBe('not-traversable');
  expect(decision.allowed).toBe(false);
  expect(pickAllowedFields(decision, proposed)).toEqual({});
});
 
it('refuses a stored address the write would replace without its street', () => {
  const proposed = { address: { city: 'Lund' } };
  const decision = access().canFields(
    { id: 'u1' },
    'order',
    'update',
    stored,
    'write',
    proposed,
  );
 
  expect(decision.reasons['address']).toBe('not-traversable');
  expect(pickAllowedFields(decision, proposed)).toEqual({});
});
 
/**
 * A deep merge or an ORM splits a raw key on `.`, so `customer.address`
 * writes the whole nested address and its street with it.
 */
it('refuses a raw key that spells the path of the replaced subtree', () => {
  const proposed = { 'customer.address': { city: 'Lund' } };
  const decision = foreign([
    permission('order', 'update', {
      rules: [always],
      fields: { fields: ['*', '!customer.address.street'] },
    }),
  ]).canFields(
    { id: 'u1' },
    'order',
    'update',
    { id: 'o1', customer: { address: { street: 'Storgatan 1' } } },
    'write',
    proposed,
  );
 
  expect(decision.reasons['customer\\.address']).toBe('not-traversable');
  expect(pickAllowedFields(decision, proposed)).toEqual({});
});
 
/**
 * A merge that splits `constructor.prototype.isAdmin` on `.` walks from the
 * row to `Object.prototype` and sets `isAdmin` on every object (CWE-1321).
 */
it.each([
  ['constructor.prototype.isAdmin'],
  ['prototype.isAdmin'],
  ['a.constructor'],
])('refuses the raw write key %s', (key) => {
  const proposed = { [key]: true };
  const decision = foreign([
    permission('order', 'update', {
      rules: [always],
      fields: { fields: ['*'] },
    }),
  ]).canFields(
    { id: 'u1' },
    'order',
    'update',
    { id: 'o1' },
    'write',
    proposed,
  );
 
  const column = key.replaceAll('.', '\\.');
  expect(decision.fields[column]).toBe('denied');
  expect(decision.reasons[column]).toBe('not-traversable');
  expect(pickAllowedFields(decision, proposed)).toEqual({});
});

/**
 * A `Date`, a class instance or an accessor under a rule that descends into
 * it cannot be inspected for the excluded key. The engine hides the value
 * rather than return it with the key inside.
 */
class Address {
  constructor(readonly street: string) {}
}
const readable = () =>
  foreign([
    permission('order', 'read', {
      rules: [always],
      fields: { fields: ['*', '!address.street'] },
    }),
  ]);
 
it.each([
  ['a Date', () => new Date(0)],
  ['a class instance', () => new Address('Storgatan 1')],
  [
    'an accessor',
    () =>
      Object.defineProperty({}, 'street', {
        enumerable: true,
        get: () => 'Storgatan 1',
      }),
  ],
  ['a primitive', () => 'Storgatan 1'],
])('hides an address held as %s', (_, make) => {
  const row = { id: 'o1', address: make() };
  const decision = readable().canFields(
    { id: 'u1' },
    'order',
    'read',
    row,
    'read',
  );
 
  expect(decision.fields['address']).toBe('denied');
  expect(decision.reasons['address']).toBe('not-traversable');
  expect(pickAllowedFields(decision, row)).toEqual({ id: 'o1' });
});

const withWhen = (node: Record<string, unknown>) =>
  foreign([
    raw({
      key: 'listing.read',
      object: 'listing',
      action: 'read',
      rules: [node],
    }),
  ]);
 
it('refuses a rule with no when', () => {
  expect(() => withWhen({})).toThrow(InvalidRuleError);
});

it('refuses a key that disagrees with object and action', () => {
  expect(() =>
    foreign([
      raw({
        key: 'listing.read',
        object: 'listing',
        action: 'delete',
        rules: [always],
      }),
    ]),
  ).toThrow(KeyMismatchError);
});

const cases: readonly (readonly [string, Record<string, unknown>])[] = [
  [
    'a membership test without a list',
    { field: 'subject.roles', op: 'in', value: 'owner' },
  ],
  [
    'a membership test over an object',
    { field: 'subject.roles', op: 'not-in', value: { owner: true } },
  ],
  [
    'an equality with two comparands',
    { field: 'subject.id', op: 'eq', path: 'object.customerId', value: 'u1' },
  ],
  ['an equality with no comparand', { field: 'subject.id', op: 'eq' }],
  [
    'a path on an operator that reads a literal',
    { field: 'subject.roles', op: 'contains', path: 'subject.id' },
  ],
  [
    'a containment test with no value',
    { field: 'subject.roles', op: 'contains' },
  ],
  ['a clock read by a value operator', { field: 'now', op: 'eq', value: 1 }],
  [
    'a value path read by a clock operator',
    { field: 'subject.at', op: 'before', value: 1 },
  ],
  [
    'a clock boundary that is not an instant',
    { field: 'now', op: 'before', value: { at: 1 } },
  ],
  [
    'a path below its scope',
    { field: 'subject.profile.role', op: 'eq', value: 'owner' },
  ],
  [
    'a path naming no scope',
    { field: 'session.role', op: 'eq', value: 'owner' },
  ],
  [
    'a comparand path naming no scope',
    { field: 'subject.id', op: 'eq', path: 'window.id' },
  ],
  [
    'a condition that is not an object',
    { field: 'subject.id', op: 'eq', value: 'u1' },
  ],
];
 
for (const [name, condition] of cases.slice(0, -1)) {
  it(`refuses ${name}`, () => {
    expect(() =>
      foreign([
        permission('listing', 'read', {
          rules: [when(condition as unknown as Condition)],
        }),
      ]),
    ).toThrow(InvalidConditionError);
  });
}
 
it('refuses a condition that is not an object', () => {
  for (const node of [null, 'subject.id', 42, []]) {
    expect(() =>
      foreign([
        raw({
          key: 'listing.read',
          object: 'listing',
          action: 'read',
          rules: [{ when: [node] }],
        }),
      ]),
    ).toThrow(InvalidConditionError);
  }
});

it('refuses a value nested deeper than the copy walks', () => {
  let deep: Record<string, unknown> = {};
  const root = deep;
  for (let i = 0; i < 100_000; i++) {
    const next: Record<string, unknown> = {};
    deep['n'] = next;
    deep = next;
  }
 
  expect(() =>
    foreign([
      permission('listing', 'read', {
        rules: [when({ field: 'subject.id', op: 'eq', value: root })],
      }),
    ]),
  ).toThrow(InvalidMatrixError);
});

it('refuses a bare list of permissions, which carries no envelope at all', () => {
  expect(() =>
    parseMatrix([
      permission('listing', 'read', { rules: [always] }),
    ] as unknown as Parameters<typeof parseMatrix>[0]),
  ).toThrow(AclConfigError);
});

/**
 * `Object.freeze` locks own properties and covers no internal slot, so a
 * frozen `Date` still answers `setTime`. A window boundary is a `Date` the
 * matrix holds, `Access.matrix` is a public getter, and `toEpoch` reads
 * `getTime()` on every evaluation, so a moved instant would decide every
 * later request while `Object.isFrozen` answered true throughout.
 */
const sale = () =>
  local([
    permission('listing', 'read', {
      rules: [
        when({
          field: 'now',
          op: 'after',
          value: new Date('2030-01-01T00:00:00Z'),
        }),
      ],
    }),
  ]);
 
const boundaryOf = (access: ReturnType<typeof local>): Date =>
  (
    access.matrix.permissions[0]?.rules?.[0]?.when?.[0] as unknown as {
      value: Date;
    }
  ).value;
 
it('refuses setTime on a window boundary, and the decision does not move', () => {
  const access = sale();
  const before = access.can({ id: 'u1' }, 'listing', 'read', { id: 'l1' });
 
  expect(before.allowed).toBe(false);
 
  const boundary = boundaryOf(access);
 
  expect(Object.isFrozen(boundary)).toBe(true);
  expect(() => boundary.setTime(0)).toThrow(TypeError);
  expect(boundary.toISOString()).toBe('2030-01-01T00:00:00.000Z');
  expect(access.can({ id: 'u1' }, 'listing', 'read', { id: 'l1' })).toEqual(
    before,
  );
});
 
it('refuses every mutator a Date carries, not only setTime', () => {
  const boundary = boundaryOf(sale());
 
  for (const name of Object.getOwnPropertyNames(Date.prototype).filter((n) =>
    n.startsWith('set'),
  )) {
    expect(
      () => (boundary as unknown as Record<string, () => void>)[name]?.(),
      `${name} must refuse`,
    ).toThrow(TypeError);
  }
});
 
it('refuses the mutators a Map and a Set carry in a condition value', () => {
  const access = local([
    permission('listing', 'read', {
      rules: [
        when({
          field: 'subject.tier',
          op: 'eq',
          value: new Map([['pro', 1]]) as unknown as string,
        }),
      ],
    }),
    permission('listing', 'write', {
      rules: [
        when({
          field: 'subject.tier',
          op: 'eq',
          value: new Set(['pro']) as unknown as string,
        }),
      ],
    }),
  ]);
  const held = access.matrix.permissions.map(
    (each) =>
      (each.rules?.[0]?.when?.[0] as unknown as { value: unknown }).value,
  );
  const [map, set] = held as [Map<string, number>, Set<string>];
 
  expect(Object.isFrozen(map)).toBe(true);
  expect(() => map.set('free', 1)).toThrow(TypeError);
  expect(() => map.delete('pro')).toThrow(TypeError);
  expect(() => map.clear()).toThrow(TypeError);
  expect(() => set.add('free')).toThrow(TypeError);
  expect(() => set.delete('pro')).toThrow(TypeError);
  expect(() => set.clear()).toThrow(TypeError);
  expect(map.get('pro')).toBe(1);
  expect(set.has('pro')).toBe(true);
});