@bajustone/fortress 1.0.0-rc.1

package/src/core/iam/permission-cache.test.ts

@@ -0,0 +1,115 @@
+import type { Permission } from '../types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createPermissionCache, subjectCacheKey } from './permission-cache';
+
+function perm(id: string, resource = 'post', action = 'read'): Permission {
+  return { id, resource, action, effect: 'ALLOW' };
+}
+
+function userKey(id: string): string {
+  return subjectCacheKey({ type: 'USER', id });
+}
+
+describe('permissionCache', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('returns undefined on cache miss', () => {
+    const cache = createPermissionCache(30_000, 100);
+    expect(cache.get(userKey('1'))).toBeUndefined();
+  });
+
+  it('returns cached permissions on hit', () => {
+    const cache = createPermissionCache(30_000, 100);
+    const perms = [perm('1'), perm('2', 'user', 'write')];
+    cache.set(userKey('1'), perms);
+    expect(cache.get(userKey('1'))).toEqual(perms);
+  });
+
+  it('expires entries after TTL', () => {
+    const cache = createPermissionCache(5_000, 100);
+    cache.set(userKey('1'), [perm('1')]);
+    expect(cache.get(userKey('1'))).toBeDefined();
+
+    vi.advanceTimersByTime(5_001);
+    expect(cache.get(userKey('1'))).toBeUndefined();
+  });
+
+  it('invalidate removes a specific subject', () => {
+    const cache = createPermissionCache(30_000, 100);
+    cache.set(userKey('1'), [perm('1')]);
+    cache.set(userKey('2'), [perm('2')]);
+
+    cache.invalidate(userKey('1'));
+    expect(cache.get(userKey('1'))).toBeUndefined();
+    expect(cache.get(userKey('2'))).toBeDefined();
+  });
+
+  it('invalidateAll clears everything', () => {
+    const cache = createPermissionCache(30_000, 100);
+    cache.set(userKey('1'), [perm('1')]);
+    cache.set(userKey('2'), [perm('2')]);
+
+    cache.invalidateAll();
+    expect(cache.get(userKey('1'))).toBeUndefined();
+    expect(cache.get(userKey('2'))).toBeUndefined();
+  });
+
+  it('drops stale writes that started before invalidation', () => {
+    const cache = createPermissionCache(30_000, 100);
+    const key = userKey('1');
+    const observed = cache.generation(key);
+    cache.invalidate(key);
+
+    expect(cache.set(key, [perm('stale')], observed)).toBe(false);
+    expect(cache.get(key)).toBeUndefined();
+  });
+
+  it('drops stale writes after global invalidation', () => {
+    const cache = createPermissionCache(30_000, 100);
+    const key = userKey('1');
+    const observed = cache.generation(key);
+    cache.invalidateAll();
+
+    expect(cache.set(key, [perm('stale')], observed)).toBe(false);
+  });
+
+  it('evicts oldest entry when at capacity', () => {
+    const cache = createPermissionCache(30_000, 2);
+    cache.set(userKey('1'), [perm('1')]);
+    cache.set(userKey('2'), [perm('2')]);
+    cache.set(userKey('3'), [perm('3')]); // should evict user 1
+
+    expect(cache.get(userKey('1'))).toBeUndefined();
+    expect(cache.get(userKey('2'))).toBeDefined();
+    expect(cache.get(userKey('3'))).toBeDefined();
+  });
+
+  it('does not evict when updating existing entry', () => {
+    const cache = createPermissionCache(30_000, 2);
+    cache.set(userKey('1'), [perm('1')]);
+    cache.set(userKey('2'), [perm('2')]);
+    cache.set(userKey('1'), [perm('1'), perm('3')]); // update, not new entry
+
+    expect(cache.get(userKey('1'))).toHaveLength(2);
+    expect(cache.get(userKey('2'))).toBeDefined();
+  });
+
+  it('user and service account with the same numeric id do not collide', () => {
+    const cache = createPermissionCache(30_000, 100);
+    cache.set(subjectCacheKey({ type: 'USER', id: '42' }), [perm('1')]);
+    cache.set(subjectCacheKey({ type: 'SERVICE_ACCOUNT', id: '42' }), [perm('2', 'deploy', 'run')]);
+
+    const userPerms = cache.get(subjectCacheKey({ type: 'USER', id: '42' }));
+    const saPerms = cache.get(subjectCacheKey({ type: 'SERVICE_ACCOUNT', id: '42' }));
+    expect(userPerms).toHaveLength(1);
+    expect(userPerms![0].id).toBe('1');
+    expect(saPerms).toHaveLength(1);
+    expect(saPerms![0].resource).toBe('deploy');
+  });
+});

package/src/core/iam/permission-cache.ts

@@ -0,0 +1,71 @@
+import type { Permission, Subject } from '../types';
+
+interface CacheEntry {
+  permissions: Permission[];
+  expiresAt: number;
+}
+
+/**
+ * Build a stable cache key for a subject. The `${type}:${id}` form partitions
+ * users from service accounts (and any future subject types) so a USER and a
+ * SERVICE_ACCOUNT with the same numeric id never collide.
+ */
+export function subjectCacheKey(subject: Subject): string {
+  return `${subject.type}:${subject.id}`;
+}
+
+export interface PermissionCache {
+  get: (key: string) => Permission[] | undefined;
+  generation: (key: string) => string;
+  /** Returns false when invalidation occurred after the caller's read began. */
+  set: (key: string, permissions: Permission[], expectedGeneration?: string) => boolean;
+  invalidate: (key: string) => void;
+  invalidateAll: () => void;
+}
+
+export function createPermissionCache(ttlMs: number, maxEntries: number): PermissionCache {
+  const store = new Map<string, CacheEntry>();
+  let generationCounter = 0;
+  // A single monotonic generation avoids unbounded per-subject metadata.
+  // Per-key invalidation may conservatively reject unrelated in-flight writes,
+  // while leaving their already-cached entries intact.
+  const generation = (_key: string): string => String(generationCounter);
+
+  return {
+    get(key: string): Permission[] | undefined {
+      const entry = store.get(key);
+      if (!entry)
+        return undefined;
+      if (Date.now() > entry.expiresAt) {
+        store.delete(key);
+        return undefined;
+      }
+      return entry.permissions;
+    },
+
+    generation,
+
+    set(key: string, permissions: Permission[], expectedGeneration?: string): boolean {
+      if (expectedGeneration !== undefined && expectedGeneration !== generation(key))
+        return false;
+      // Evict oldest entry if at capacity
+      if (store.size >= maxEntries && !store.has(key)) {
+        const oldest = store.keys().next().value;
+        if (oldest !== undefined)
+          store.delete(oldest);
+      }
+      store.set(key, { permissions, expiresAt: Date.now() + ttlMs });
+      return true;
+    },
+
+    invalidate(key: string): void {
+      store.delete(key);
+      generationCounter++;
+    },
+
+    invalidateAll(): void {
+      store.clear();
+      generationCounter++;
+    },
+  };
+}

package/src/core/iam/permission-check-observer.test.ts

@@ -0,0 +1,90 @@
+import type { Fortress } from '../fortress';
+import type { PermissionCheckEvent } from './iam-service';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { createTestAdapter } from '../../testing';
+import { createFortress } from '../fortress';
+
+let fortress: Fortress;
+const SECRET = 'perm-check-observer-test-32chars!!';
+
+async function seedUserAndRole(): Promise<{ userId: string }> {
+  const user = await fortress.auth.createUser({
+    email: 'perm@example.com',
+    name: 'Perm User',
+    password: 'password-123456',
+  });
+  const role = await fortress.iam.createRole('editor', [
+    { resource: 'post', action: 'read' },
+  ]);
+  await fortress.iam.bindRoleToUser(user.id, role.id);
+  return { userId: user.id };
+}
+
+describe('addPermissionCheckObserver', () => {
+  beforeEach(() => {
+    fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      rbac: { cache: { ttlSeconds: 30, maxEntries: 100 } },
+    });
+  });
+
+  it('fires synchronously on every checkPermission call with cached flag', async () => {
+    const { userId } = await seedUserAndRole();
+    const events: PermissionCheckEvent[] = [];
+    fortress.iam.addPermissionCheckObserver(e => void events.push(e));
+
+    const allow1 = await fortress.iam.checkPermission({ type: 'USER', id: userId }, 'post', 'read');
+    const allow2 = await fortress.iam.checkPermission({ type: 'USER', id: userId }, 'post', 'read');
+
+    expect(allow1).toBe(true);
+    expect(allow2).toBe(true);
+    expect(events).toHaveLength(2);
+
+    // First call: cache miss; second call: cache hit.
+    expect(events[0]?.cached).toBe(false);
+    expect(events[1]?.cached).toBe(true);
+
+    // Common fields.
+    for (const ev of events) {
+      expect(ev.subjectType).toBe('USER');
+      expect(ev.subjectId).toBe(userId);
+      expect(ev.resource).toBe('post');
+      expect(ev.action).toBe('read');
+      expect(ev.allowed).toBe(true);
+      expect(ev.durationSeconds).toBeGreaterThan(0);
+    }
+  });
+
+  it('records allowed=false when the subject lacks permission', async () => {
+    const { userId } = await seedUserAndRole();
+    const events: PermissionCheckEvent[] = [];
+    fortress.iam.addPermissionCheckObserver(e => void events.push(e));
+
+    const denied = await fortress.iam.checkPermission({ type: 'USER', id: userId }, 'post', 'delete');
+
+    expect(denied).toBe(false);
+    expect(events).toHaveLength(1);
+    expect(events[0]?.allowed).toBe(false);
+  });
+
+  it('returns an unsubscribe function', async () => {
+    const { userId } = await seedUserAndRole();
+    const events: PermissionCheckEvent[] = [];
+    const off = fortress.iam.addPermissionCheckObserver(e => void events.push(e));
+    off();
+
+    await fortress.iam.checkPermission({ type: 'USER', id: userId }, 'post', 'read');
+    expect(events).toHaveLength(0);
+  });
+
+  it('observer exceptions do not break the permission check', async () => {
+    const { userId } = await seedUserAndRole();
+    fortress.iam.addPermissionCheckObserver(() => {
+      throw new Error('observer bug');
+    });
+
+    const allowed = await fortress.iam.checkPermission({ type: 'USER', id: userId }, 'post', 'read');
+    expect(allowed).toBe(true);
+  });
+});

package/src/core/iam/permission-evaluator.test.ts

@@ -0,0 +1,291 @@
+/* eslint-disable no-template-curly-in-string -- tests use ${variable} syntax intentionally */
+import type { Permission } from '../types';
+
+import { describe, expect, it } from 'vitest';
+import { evaluateConditions, evaluatePermissions } from './permission-evaluator';
+
+function perm(overrides: Partial<Permission> = {}): Permission {
+  return {
+    id: '1',
+    resource: 'post',
+    action: 'update',
+    effect: 'ALLOW',
+    ...overrides,
+  };
+}
+
+describe('evaluatePermissions', () => {
+  describe('allow-only mode', () => {
+    it('returns false when no permissions match', () => {
+      const result = evaluatePermissions(
+        [perm({ resource: 'user', action: 'read' })],
+        'post',
+        'update',
+        'allow-only',
+      );
+      expect(result).toBe(false);
+    });
+
+    it('returns true when an ALLOW permission matches', () => {
+      const result = evaluatePermissions(
+        [perm()],
+        'post',
+        'update',
+        'allow-only',
+      );
+      expect(result).toBe(true);
+    });
+
+    it('returns false when empty permissions', () => {
+      expect(evaluatePermissions([], 'post', 'update', 'allow-only')).toBe(false);
+    });
+
+    it('ignores DENY permissions in allow-only mode', () => {
+      const result = evaluatePermissions(
+        [perm({ effect: 'DENY' }), perm({ id: '2', effect: 'ALLOW' })],
+        'post',
+        'update',
+        'allow-only',
+      );
+      expect(result).toBe(true);
+    });
+  });
+
+  describe('deny-overrides mode', () => {
+    it('denies if any DENY matches even with ALLOW present', () => {
+      const result = evaluatePermissions(
+        [perm({ effect: 'ALLOW' }), perm({ id: '2', effect: 'DENY' })],
+        'post',
+        'update',
+        'deny-overrides',
+      );
+      expect(result).toBe(false);
+    });
+
+    it('allows if only ALLOW matches', () => {
+      const result = evaluatePermissions(
+        [perm({ effect: 'ALLOW' })],
+        'post',
+        'update',
+        'deny-overrides',
+      );
+      expect(result).toBe(true);
+    });
+
+    it('denies if no matching permissions', () => {
+      expect(evaluatePermissions([], 'post', 'update', 'deny-overrides')).toBe(false);
+    });
+  });
+
+  describe('wildcard matching', () => {
+    it('action wildcard matches any action', () => {
+      const result = evaluatePermissions(
+        [perm({ resource: 'post', action: '*' })],
+        'post',
+        'delete',
+        'allow-only',
+      );
+      expect(result).toBe(true);
+    });
+
+    it('resource wildcard matches any resource', () => {
+      const result = evaluatePermissions(
+        [perm({ resource: '*', action: 'read' })],
+        'invoice',
+        'read',
+        'allow-only',
+      );
+      expect(result).toBe(true);
+    });
+
+    it('double wildcard matches everything', () => {
+      const result = evaluatePermissions(
+        [perm({ resource: '*', action: '*' })],
+        'anything',
+        'whatever',
+        'allow-only',
+      );
+      expect(result).toBe(true);
+    });
+
+    it('wildcard does not match when other field is wrong', () => {
+      const result = evaluatePermissions(
+        [perm({ resource: 'post', action: '*' })],
+        'user',
+        'read',
+        'allow-only',
+      );
+      expect(result).toBe(false);
+    });
+
+    it('exact DENY overrides wildcard ALLOW in deny-overrides mode', () => {
+      const result = evaluatePermissions(
+        [
+          perm({ id: '1', resource: 'post', action: '*', effect: 'ALLOW' }),
+          perm({ id: '2', resource: 'post', action: 'delete', effect: 'DENY' }),
+        ],
+        'post',
+        'delete',
+        'deny-overrides',
+      );
+      expect(result).toBe(false);
+    });
+
+    it('wildcard ALLOW still works when no DENY in deny-overrides mode', () => {
+      const result = evaluatePermissions(
+        [perm({ resource: 'post', action: '*', effect: 'ALLOW' })],
+        'post',
+        'update',
+        'deny-overrides',
+      );
+      expect(result).toBe(true);
+    });
+
+    it('conditions still apply on wildcard permissions', () => {
+      const result = evaluatePermissions(
+        [perm({
+          resource: 'post',
+          action: '*',
+          conditions: [{ field: 'resource.ownerId', operator: 'eq', value: '${user.id}' }],
+        })],
+        'post',
+        'update',
+        'allow-only',
+        { resource: { ownerId: 42 }, user: { id: '99' } },
+      );
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('with conditions', () => {
+    it('allows when condition is met', () => {
+      const result = evaluatePermissions(
+        [perm({
+          conditions: [{ field: 'resource.ownerId', operator: 'eq', value: '42' }],
+        })],
+        'post',
+        'update',
+        'allow-only',
+        { resource: { ownerId: 42 } },
+      );
+      expect(result).toBe(true);
+    });
+
+    it('denies when condition is not met', () => {
+      const result = evaluatePermissions(
+        [perm({
+          conditions: [{ field: 'resource.ownerId', operator: 'eq', value: '42' }],
+        })],
+        'post',
+        'update',
+        'allow-only',
+        { resource: { ownerId: 99 } },
+      );
+      expect(result).toBe(false);
+    });
+
+    it('denies when no context provided but conditions exist', () => {
+      const result = evaluatePermissions(
+        [perm({
+          conditions: [{ field: 'resource.ownerId', operator: 'eq', value: '42' }],
+        })],
+        'post',
+        'update',
+        'allow-only',
+      );
+      expect(result).toBe(false);
+    });
+
+    it('supports ${user.id} variable in conditions', () => {
+      const result = evaluatePermissions(
+        [perm({
+          conditions: [{ field: 'resource.ownerId', operator: 'eq', value: '${user.id}' }],
+        })],
+        'post',
+        'update',
+        'allow-only',
+        { resource: { ownerId: 42 }, user: { id: '42' } },
+      );
+      expect(result).toBe(true);
+    });
+
+    it('${user.id} variable mismatch denies', () => {
+      const result = evaluatePermissions(
+        [perm({
+          conditions: [{ field: 'resource.ownerId', operator: 'eq', value: '${user.id}' }],
+        })],
+        'post',
+        'update',
+        'allow-only',
+        { resource: { ownerId: 42 }, user: { id: '99' } },
+      );
+      expect(result).toBe(false);
+    });
+  });
+});
+
+describe('evaluateConditions', () => {
+  it.each(['eq', 'neq', 'in', 'startsWith'] as const)(
+    'fails closed for unresolved values with %s',
+    (operator) => {
+      expect(evaluateConditions(
+        [{ field: 'resource.missing', operator, value: { ref: 'user.missing' } }],
+        { resource: {}, user: {} },
+      )).toBe(false);
+    },
+  );
+
+  it('supports neq operator', () => {
+    const result = evaluateConditions(
+      [{ field: 'resource.status', operator: 'neq', value: 'archived' }],
+      { resource: { status: 'published' } },
+    );
+    expect(result).toBe(true);
+  });
+
+  it('supports in operator', () => {
+    const result = evaluateConditions(
+      [{ field: 'resource.status', operator: 'in', value: ['draft', 'published'] }],
+      { resource: { status: 'published' } },
+    );
+    expect(result).toBe(true);
+  });
+
+  it('in operator denies when value not in list', () => {
+    const result = evaluateConditions(
+      [{ field: 'resource.status', operator: 'in', value: ['draft', 'published'] }],
+      { resource: { status: 'archived' } },
+    );
+    expect(result).toBe(false);
+  });
+
+  it('supports startsWith operator', () => {
+    const result = evaluateConditions(
+      [{ field: 'request.ip', operator: 'startsWith', value: '192.168.' }],
+      { request: { ip: '192.168.1.100' } },
+    );
+    expect(result).toBe(true);
+  });
+
+  it('all conditions must be true (AND logic)', () => {
+    const result = evaluateConditions(
+      [
+        { field: 'resource.ownerId', operator: 'eq', value: '${user.id}' },
+        { field: 'resource.status', operator: 'neq', value: 'archived' },
+      ],
+      { resource: { ownerId: 42, status: 'published' }, user: { id: '42' } },
+    );
+    expect(result).toBe(true);
+  });
+
+  it('fails if any condition is false', () => {
+    const result = evaluateConditions(
+      [
+        { field: 'resource.ownerId', operator: 'eq', value: '${user.id}' },
+        { field: 'resource.status', operator: 'neq', value: 'archived' },
+      ],
+      { resource: { ownerId: 42, status: 'archived' }, user: { id: '42' } },
+    );
+    expect(result).toBe(false);
+  });
+});