@bajustone/fortress 1.0.0-rc.1

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

@@ -0,0 +1,198 @@
+import type { Permission, PermissionCondition, PermissionContext } from '../types';
+
+const VARIABLE_PATTERN = /^\$\{(.+)\}$/;
+
+export type EvaluationMode = 'allow-only' | 'deny-overrides';
+
+/**
+ * Check whether a credential-level scope set allows the requested
+ * resource/action. `null`/`undefined` means the credential is unscoped and
+ * inherits the subject's full IAM permissions; an empty array allows nothing.
+ */
+export function withinCredentialScope(
+  scopes: string[] | null | undefined,
+  resource: string,
+  action: string,
+): boolean {
+  if (scopes == null)
+    return true;
+  return scopes.some(scope =>
+    scope === '*'
+    || scope === `${resource}:*`
+    || scope === `${resource}:${action}`,
+  );
+}
+
+/**
+ * Evaluate a set of permissions against a resource+action request.
+ *
+ * - 'allow-only': if any ALLOW matches → allow, otherwise deny
+ * - 'deny-overrides' (AWS-style):
+ *   1. Collect all matching permissions
+ *   2. If any DENY matches → deny (overrides everything)
+ *   3. If any ALLOW matches → allow
+ *   4. Otherwise → deny (implicit)
+ */
+export function evaluatePermissions(
+  permissions: Permission[],
+  resource: string,
+  action: string,
+  mode: EvaluationMode,
+  context?: PermissionContext,
+): boolean {
+  const matching = permissions.filter(p =>
+    matchesResourceAction(p, resource, action),
+  );
+
+  if (matching.length === 0)
+    return false;
+
+  // Evaluate conditions on each matching permission
+  const evaluated = matching.map(p => ({
+    effect: p.effect,
+    conditionsMet: !p.conditions?.length || evaluateConditions(p.conditions, context),
+  }));
+
+  // Only consider permissions where conditions are met
+  const effective = evaluated.filter(e => e.conditionsMet);
+
+  if (effective.length === 0)
+    return false;
+
+  if (mode === 'deny-overrides') {
+    // Any DENY → deny (overrides everything)
+    if (effective.some(e => e.effect === 'DENY'))
+      return false;
+    // Any ALLOW → allow
+    return effective.some(e => e.effect === 'ALLOW');
+  }
+
+  // allow-only: any ALLOW → allow
+  return effective.some(e => e.effect === 'ALLOW');
+}
+
+function matchesResourceAction(permission: Permission, resource: string, action: string): boolean {
+  return matchesWildcard(permission.resource, resource)
+    && matchesWildcard(permission.action, action);
+}
+
+function matchesWildcard(pattern: string, value: string): boolean {
+  if (pattern === '*')
+    return true;
+  return pattern === value;
+}
+
+/**
+ * Evaluate all conditions. All conditions must be true (AND logic).
+ */
+export function evaluateConditions(
+  conditions: PermissionCondition[],
+  context?: PermissionContext,
+): boolean {
+  if (!context)
+    return false;
+
+  return conditions.every(condition => evaluateCondition(condition, context));
+}
+
+function evaluateCondition(condition: PermissionCondition, context: PermissionContext): boolean {
+  const actualValue = resolveFieldValue(condition.field, context);
+  const expectedValue = resolveExpectedValue(condition.value, context);
+  // Missing fields/references are never comparable. In particular, `neq`
+  // must not turn an unresolved value into an accidental grant.
+  if (
+    actualValue === undefined
+    || expectedValue === undefined
+    || (Array.isArray(expectedValue) && expectedValue.includes(undefined))
+  ) {
+    return false;
+  }
+
+  switch (condition.operator) {
+    case 'eq':
+      return String(actualValue) === String(expectedValue);
+    case 'neq':
+      return String(actualValue) !== String(expectedValue);
+    case 'in': {
+      const list = Array.isArray(expectedValue) ? expectedValue : [expectedValue];
+      return list.map(String).includes(String(actualValue));
+    }
+    case 'startsWith':
+      return String(actualValue).startsWith(String(expectedValue));
+    default:
+      return false;
+  }
+}
+
+/**
+ * Resolve a dotted field path from the permission context.
+ * e.g., "resource.ownerId" → context.resource.ownerId
+ */
+function resolveFieldValue(field: string, context: PermissionContext): unknown {
+  const [section, ...rest] = field.split('.');
+  const key = rest.join('.');
+
+  let source: Record<string, unknown> | undefined;
+  if (section === 'resource')
+    source = context.resource;
+  else if (section === 'request')
+    source = context.request;
+  else if (section === 'user')
+    source = context.user;
+
+  if (!source || !key)
+    return undefined;
+
+  return getNestedValue(source, key);
+}
+
+/**
+ * Resolve expected value — supports both ${variable} template syntax
+ * and structured ConditionRef objects ({ ref: "user.id" }).
+ */
+function resolveExpectedValue(
+  value: string | string[] | { ref: string } | { ref: string }[],
+  context: PermissionContext,
+): unknown {
+  if (Array.isArray(value)) {
+    return value.map((v) => {
+      if (typeof v === 'object' && 'ref' in v)
+        return resolveFieldValue(v.ref, context);
+      return resolveSingleValue(v, context);
+    });
+  }
+  if (typeof value === 'object' && 'ref' in value)
+    return resolveFieldValue(value.ref, context);
+  return resolveSingleValue(value, context);
+}
+
+function resolveSingleValue(value: string, context: PermissionContext): unknown {
+  const match = VARIABLE_PATTERN.exec(value);
+  if (!match)
+    return value;
+
+  // It's a variable reference like ${user.id}
+  return resolveFieldValue(match[1], context);
+}
+
+// L-tier: prototype-pollution-safe key set. Reading `__proto__` /
+// `constructor` / `prototype` off an attacker-controlled object would
+// either return the prototype chain or let a condition spoof an
+// inherited value as a real field. We skip these keys defensively even
+// though all currently-known callers feed plain object literals.
+const FORBIDDEN_PROTO_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object')
+      return undefined;
+    if (FORBIDDEN_PROTO_KEYS.has(part))
+      return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return current;
+}

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

@@ -0,0 +1,166 @@
+import type { Fortress } from '../fortress';
+import { describe, expect, it } from 'vitest';
+import { createTestAdapter } from '../../testing';
+import { createFortress } from '../fortress';
+import { endpoint, obj, str } from '../schema-builder';
+
+const SECRET = 'permission-sync-test-secret-3232!';
+
+async function buildFortress(): Promise<Fortress> {
+  const fortress = createFortress({
+    jwt: { key: SECRET },
+    database: createTestAdapter(),
+    routes: {
+      listSchools: endpoint('GET', '/schools')
+        .summary('List schools')
+        .security('bearer')
+        .permission('school', 'list')
+        .response(200, 'OK', obj({ data: str() }, 'data'))
+        .handler('listSchools')
+        .build(),
+      readSchool: endpoint('GET', '/schools/:id')
+        .summary('Read school')
+        .security('bearer')
+        .permission('school', 'read')
+        .params(obj({ id: str() }, 'id'))
+        .response(200, 'OK', obj({ data: str() }, 'data'))
+        .handler('readSchool')
+        .build(),
+      createSchool: endpoint('POST', '/schools')
+        .summary('Create school')
+        .security('bearer')
+        .permission('school', 'create')
+        .response(201, 'Created', obj({ data: str() }, 'data'))
+        .handler('createSchool')
+        .build(),
+      // Endpoint without a permission declaration — should be ignored.
+      ping: endpoint('GET', '/ping')
+        .summary('Ping')
+        .security('none')
+        .response(200, 'OK', obj({ ok: str() }, 'ok'))
+        .handler('ping')
+        .build(),
+    },
+  });
+  await fortress.migrate();
+  return fortress;
+}
+
+describe('fortress.syncPermissionsFromManifest', () => {
+  it('discovers unique (resource, action) pairs and creates each permission', async () => {
+    const fortress = await buildFortress();
+    const result = await fortress.syncPermissionsFromManifest();
+
+    // Default scope is fortress.endpoints, which includes the 3 host
+    // perms plus the system permissions declared on fortress's own
+    // auth/IAM endpoints. We assert the host perms made it in and that
+    // every discovered perm was created (none existed before).
+    expect(result.discovered).toBeGreaterThanOrEqual(3);
+    expect(result.created).toBe(result.discovered);
+    expect(result.existing).toBe(0);
+
+    const perms = await fortress.iam.listPermissions();
+    const keys = perms.map(p => `${p.resource}:${p.action}`);
+    expect(keys).toContain('school:create');
+    expect(keys).toContain('school:list');
+    expect(keys).toContain('school:read');
+  });
+
+  it('is idempotent on a partially seeded database', async () => {
+    const fortress = await buildFortress();
+    await fortress.iam.createPermission({ resource: 'school', action: 'list' });
+
+    const first = await fortress.syncPermissionsFromManifest();
+    // The pre-seeded school:list is the only existing perm; everything
+    // else discovered should be a fresh insert.
+    expect(first.existing).toBe(1);
+    expect(first.created).toBe(first.discovered - 1);
+
+    // Re-running adds nothing.
+    const second = await fortress.syncPermissionsFromManifest();
+    expect(second.created).toBe(0);
+    expect(second.existing).toBe(second.discovered);
+  });
+
+  it('binds manifest-discovered permissions onto a role when spec is "*"', async () => {
+    const fortress = await buildFortress();
+    // A stale/unrelated permission in the DB must not be pulled in by '*'.
+    await fortress.iam.createPermission({ resource: 'stale', action: 'delete' });
+
+    const result = await fortress.syncPermissionsFromManifest({
+      defaultRoles: { admin: '*' },
+    });
+
+    expect(result.roles.admin?.created).toBe(true);
+    expect(result.roles.admin?.bound).toBe(result.discovered);
+
+    const roles = await fortress.iam.getRoles();
+    const admin = roles.find(r => r.name === 'admin');
+    expect(admin).toBeDefined();
+    const detail = await fortress.iam.getRole(admin!.id);
+    expect(detail.permissions.length).toBe(result.discovered);
+    // Spot-check that the host perms are among them and stale DB-only perms are not.
+    const keys = detail.permissions.map(p => `${p.resource}:${p.action}`);
+    expect(keys).toContain('school:create');
+    expect(keys).not.toContain('stale:delete');
+  });
+
+  it('binds only the listed permissions when spec is a string list', async () => {
+    const fortress = await buildFortress();
+    const result = await fortress.syncPermissionsFromManifest({
+      defaultRoles: { member: ['school:read', 'school:list'] },
+    });
+
+    expect(result.roles.member?.bound).toBe(2);
+
+    const roles = await fortress.iam.getRoles();
+    const member = roles.find(r => r.name === 'member')!;
+    const detail = await fortress.iam.getRole(member.id);
+    const keys = detail.permissions.map(p => `${p.resource}:${p.action}`).sort();
+    expect(keys).toEqual(['school:list', 'school:read']);
+  });
+
+  it('only grants on re-run — never revokes', async () => {
+    const fortress = await buildFortress();
+    await fortress.syncPermissionsFromManifest({
+      defaultRoles: { member: ['school:read', 'school:list', 'school:create'] },
+    });
+
+    // Subsequent call asks for fewer perms — existing should stay, but the
+    // report should not count already-bound permissions as newly bound.
+    const second = await fortress.syncPermissionsFromManifest({
+      defaultRoles: { member: ['school:read'] },
+    });
+    expect(second.roles.member?.bound).toBe(0);
+
+    const roles = await fortress.iam.getRoles();
+    const member = roles.find(r => r.name === 'member')!;
+    const detail = await fortress.iam.getRole(member.id);
+    const keys = detail.permissions.map(p => `${p.resource}:${p.action}`).sort();
+    expect(keys).toEqual(['school:create', 'school:list', 'school:read']);
+  });
+
+  it('rejects an invalid role-permission spec', async () => {
+    const fortress = await buildFortress();
+    await expect(
+      fortress.syncPermissionsFromManifest({ defaultRoles: { admin: ['nocolon'] } }),
+    ).rejects.toThrow(/Invalid permission spec/);
+  });
+
+  it('accepts an explicit endpoints array', async () => {
+    const fortress = await buildFortress();
+    const result = await fortress.syncPermissionsFromManifest({
+      endpoints: [
+        endpoint('GET', '/x')
+          .summary('x')
+          .security('bearer')
+          .permission('widget', 'twiddle')
+          .response(200, 'OK')
+          .handler('x')
+          .build(),
+      ],
+    });
+    expect(result.discovered).toBe(1);
+    expect(result.created).toBe(1);
+  });
+});

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

@@ -0,0 +1,192 @@
+/**
+ * Manifest-driven permission seeding.
+ *
+ * `endpoint().permission(resource, action)` declares the permission an
+ * endpoint needs, but a freshly migrated database has no `Permission` row
+ * for it. Every consumer used to write the same seed script: walk
+ * `fortress.endpoints`, dedupe `(resource, action)` pairs, call
+ * `iam.createPermission(...)` for each, optionally bind defaults onto a
+ * couple of well-known roles.
+ *
+ * This module replaces that script. It's idempotent (re-runs safely on a
+ * partially seeded DB) and exposed on the {@link Fortress} instance as
+ * `fortress.syncPermissionsFromManifest()`.
+ */
+
+import type { EndpointDefinition } from '../endpoint';
+import type { Permission } from '../types';
+import type { IamService } from './iam-service';
+import { Errors } from '../errors';
+
+/** Options accepted by {@link runPermissionSync}. */
+export interface PermissionSyncOptions {
+  /**
+   * Endpoints to scan for `meta.permission` declarations. Defaults to the
+   * full set registered on the Fortress instance when called via
+   * {@link import('../fortress').Fortress.syncPermissionsFromManifest}.
+   */
+  endpoints?: EndpointDefinition[];
+
+  /**
+   * Optional role-name → permissions map. For each role:
+   *
+   * - `'*'` binds every permission discovered in `endpoints` to the role.
+   * - `['resource:action', ...]` binds only the named permissions (one
+   *   string per `(resource, action)` pair, colon-separated).
+   *
+   * Roles are created on demand; existing roles get any missing
+   * permissions added. Permissions on a role that aren't requested here
+   * are left in place \u2014 this only grants, never revokes.
+   *
+   * ```ts
+   * await fortress.syncPermissionsFromManifest({\n   *   defaultRoles: {\n   *     admin: '*',\n   *     member: ['school:read', 'school:list'],\n   *   },\n   * });\n   * ```
+   */
+  defaultRoles?: Record<string, '*' | readonly string[]>;
+}
+
+/** Result returned by {@link runPermissionSync}. */
+export interface PermissionSyncResult {
+  /** Number of unique `(resource, action)` pairs discovered. */
+  discovered: number;
+  /**
+   * Number of permissions that already existed in the database before
+   * the sync started. (The adapter's `findOrCreatePermission` doesn't
+   * distinguish, so this is computed by counting pre-existing
+   * permissions; new inserts = `discovered - existing`.)
+   */
+  existing: number;
+  /** Number of new permission rows inserted by this sync run. */
+  created: number;
+  /**
+   * Roles touched by `defaultRoles`, keyed by role name. `bound` is the
+   * number of permission bindings newly added during this sync run.
+   * Already-bound permissions do not double-count.
+   */
+  roles: Record<string, { created: boolean; bound: number }>;
+}
+
+interface PermissionKey {
+  resource: string;
+  action: string;
+}
+
+function collectUniquePermissions(endpoints: EndpointDefinition[]): PermissionKey[] {
+  const seen = new Set<string>();
+  const result: PermissionKey[] = [];
+  for (const ep of endpoints) {
+    const perm = ep.meta?.permission;
+    if (!perm)
+      continue;
+    const key = `${perm.resource}:${perm.action}`;
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    result.push({ resource: perm.resource, action: perm.action });
+  }
+  return result;
+}
+
+function parseRolePermSpec(spec: string): PermissionKey {
+  const colon = spec.indexOf(':');
+  if (colon < 1 || colon === spec.length - 1) {
+    throw Errors.badRequest(
+      `Invalid permission spec '${spec}'; expected '<resource>:<action>'`,
+    );
+  }
+  return { resource: spec.slice(0, colon), action: spec.slice(colon + 1) };
+}
+
+function dedupePermissions(perms: readonly PermissionKey[]): PermissionKey[] {
+  const seen = new Set<string>();
+  const result: PermissionKey[] = [];
+  for (const perm of perms) {
+    const key = `${perm.resource}:${perm.action}`;
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    result.push(perm);
+  }
+  return result;
+}
+
+/**
+ * Seed permissions from a set of endpoints and (optionally) bind them onto
+ * default roles. Safe to call repeatedly. See {@link PermissionSyncOptions}
+ * for shape.
+ */
+export async function runPermissionSync(
+  iam: IamService,
+  endpoints: EndpointDefinition[],
+  opts: PermissionSyncOptions = {},
+): Promise<PermissionSyncResult> {
+  const unique = collectUniquePermissions(endpoints);
+
+  // Snapshot existing permissions so we can report created vs. existing.
+  // `findOrCreatePermission` upserts, so we can't tell after the fact.
+  const before: Permission[] = await iam.listPermissions();
+  const existingKeys = new Set(before.map((p: Permission) => `${p.resource}:${p.action}`));
+
+  for (const perm of unique)
+    await iam.createPermission(perm);
+
+  const existing = unique.filter(p => existingKeys.has(`${p.resource}:${p.action}`)).length;
+  const created = unique.length - existing;
+
+  const rolesReport: Record<string, { created: boolean; bound: number }> = {};
+
+  if (opts.defaultRoles) {
+    const allRoles = await iam.getRoles();
+    const rolesByName = new Map(allRoles.map(r => [r.name, r] as const));
+
+    for (const [roleName, spec] of Object.entries(opts.defaultRoles)) {
+      let permsToBind: PermissionKey[];
+      if (spec === '*') {
+        // `*` means every permission discovered from the supplied endpoint
+        // manifest, not every permission that happens to exist in the DB.
+        permsToBind = unique;
+      }
+      else {
+        permsToBind = (spec as readonly string[]).map(parseRolePermSpec);
+      }
+      permsToBind = dedupePermissions(permsToBind);
+
+      const existingRole = rolesByName.get(roleName);
+      let roleCreated = false;
+      let roleId: string;
+      if (existingRole) {
+        roleId = existingRole.id;
+      }
+      else {
+        // createRole both inserts the role and binds the supplied
+        // permissions in one call, so we can skip the explicit bind loop
+        // below for the create path.
+        const role = await iam.createRole(roleName, permsToBind);
+        roleId = role.id;
+        roleCreated = true;
+      }
+
+      let bound = 0;
+      if (!roleCreated) {
+        const roleDetail = await iam.getRole(roleId);
+        const existingRolePerms = new Set(
+          roleDetail.permissions.map((p: Permission) => `${p.resource}:${p.action}`),
+        );
+        for (const perm of permsToBind) {
+          const key = `${perm.resource}:${perm.action}`;
+          if (existingRolePerms.has(key))
+            continue;
+          await iam.addPermissionToRole(roleId, perm);
+          existingRolePerms.add(key);
+          bound++;
+        }
+      }
+      else {
+        bound = permsToBind.length;
+      }
+
+      rolesReport[roleName] = { created: roleCreated, bound };
+    }
+  }
+
+  return { discovered: unique.length, existing, created, roles: rolesReport };
+}

package/src/core/iam/resource-sync.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+
+import { generateResourceTypes, parseResourceFile } from './resource-sync';
+
+describe('parseResourceFile', () => {
+  it('accepts the canonical map shape and deduplicates actions', () => {
+    expect(parseResourceFile({
+      $schema: 'ignored annotation',
+      resources: { article: { actions: ['read', 'read'], description: 'Articles' } },
+    })).toEqual({
+      resources: { article: { actions: ['read'], description: 'Articles' } },
+    });
+  });
+
+  it.each([
+    [null, 'must be an object'],
+    [{ resources: [] }, 'legacy resources array'],
+    [{ resources: { article: { actions: 'read' } } }, 'actions must be an array'],
+    [{ resources: { article: { actions: ['read', 1] } } }, 'actions must be an array'],
+    [{ resources: { article: { actions: [], description: 1 } } }, 'description must be a string'],
+    [JSON.parse('{"resources":{"__proto__":{"actions":["read"]}}}'), 'reserved or empty'],
+  ])('rejects malformed resource documents', (value, message) => {
+    expect(() => parseResourceFile(value)).toThrow(message);
+  });
+});
+
+describe('generateResourceTypes', () => {
+  it('generates TypeScript types from resource definitions', () => {
+    const types = generateResourceTypes({
+      resources: {
+        user: { actions: ['create', 'read', 'update', 'delete'] },
+        post: { actions: ['create', 'read', 'publish'] },
+      },
+    });
+
+    expect(types).toContain('"user"');
+    expect(types).toContain('"post"');
+    expect(types).toContain('"create" | "read" | "update" | "delete"');
+    expect(types).toContain('"create" | "read" | "publish"');
+    expect(types).toContain('FortressResource');
+    expect(types).toContain('FortressAction');
+  });
+
+  it('handles empty resources', () => {
+    const types = generateResourceTypes({ resources: {} });
+    expect(types).toContain('never');
+  });
+
+  it('escapes resource/action literals and handles empty action sets', () => {
+    const types = generateResourceTypes({
+      resources: {
+        'blog-post': { actions: [] },
+        'quoted': { actions: ['read\'quote'] },
+      },
+    });
+    expect(types).toContain('R extends "blog-post" ? never');
+    expect(types).toContain('"read\'quote"');
+  });
+
+  it('handles single resource', () => {
+    const types = generateResourceTypes({
+      resources: {
+        invoice: { actions: ['create', 'void'] },
+      },
+    });
+
+    expect(types).toContain('"invoice"');
+    expect(types).toContain('"create" | "void"');
+  });
+});