@bajustone/fortress 1.0.0-rc.1

package/src/core/policy/diff.ts

@@ -0,0 +1,288 @@
+/**
+ * Compute the {@link PolicyPlan} that reconciles the live IAM state with
+ * a declarative {@link PolicyDocument}.
+ *
+ * The diff is intentionally additive-by-default: missing resources,
+ * actions, roles, permissions, groups, and service accounts produce
+ * `create-*` / `add-*` ops. Deletions only appear when `prune: true` is
+ * passed — most operators want their first apply to be safe.
+ *
+ * @module
+ */
+
+import type { IamService } from '../iam/iam-service';
+import type { Permission, Role, ServiceAccount } from '../types';
+import type {
+  DiffPolicyOptions,
+  PolicyDocument,
+  PolicyOp,
+  PolicyPermission,
+  PolicyPlan,
+} from './types';
+import { Errors } from '../errors';
+
+function permissionKey(perm: { resource: string; action: string; effect?: string }): string {
+  return `${perm.resource}::${perm.action}::${perm.effect ?? 'ALLOW'}`;
+}
+
+function describePerm(perm: PolicyPermission): string {
+  return `${perm.resource}:${perm.action}${perm.effect && perm.effect !== 'ALLOW' ? ` (${perm.effect})` : ''}`;
+}
+
+/**
+ * Compute the diff between a {@link PolicyDocument} (desired state) and
+ * the live IAM state. Pass the returned {@link PolicyPlan} to
+ * {@link applyPolicyPlan} to reconcile.
+ */
+export async function diffPolicy(
+  policy: PolicyDocument,
+  iam: IamService,
+  options: DiffPolicyOptions = {},
+): Promise<PolicyPlan> {
+  const declaredCount = (policy.resources?.length ?? 0)
+    + (policy.roles?.length ?? 0)
+    + (policy.groups?.length ?? 0)
+    + (policy.serviceAccounts?.length ?? 0);
+  if (options.prune && declaredCount === 0 && !options.allowEmptyPrune) {
+    throw Errors.badRequest(
+      'Refusing to prune with an empty policy; pass allowEmptyPrune: true to acknowledge deleting all managed IAM state',
+    );
+  }
+  const ops: PolicyOp[] = [];
+
+  // ── Resources ──────────────────────────────────────────────────────
+  const existingResources = await iam.getResources();
+  const existingResourceMap = existingResources.resources;
+  const declaredResourceNames = new Set<string>();
+
+  for (const resource of policy.resources ?? []) {
+    declaredResourceNames.add(resource.name);
+    const existing = existingResourceMap[resource.name];
+    if (!existing) {
+      ops.push({
+        kind: 'create-resource',
+        resource,
+        description: `Create resource '${resource.name}' with actions [${resource.actions.join(', ')}]`,
+      });
+      continue;
+    }
+    const existingActions = new Set(existing.actions);
+    for (const action of resource.actions) {
+      if (!existingActions.has(action)) {
+        ops.push({
+          kind: 'add-resource-action',
+          resource: resource.name,
+          action,
+          description: `Add action '${action}' to resource '${resource.name}'`,
+        });
+      }
+    }
+  }
+  // Note: we don't prune resources/actions even with `prune: true` because
+  // dropping a resource cascades to permissions/role-bindings. Operators
+  // should remove unused resources manually via the admin API.
+
+  // ── Roles ──────────────────────────────────────────────────────────
+  const existingRoles = await iam.getRoles();
+  const existingRoleByName = new Map<string, Role>(existingRoles.map(role => [role.name, role]));
+  const declaredRoleNames = new Set<string>();
+
+  for (const role of policy.roles ?? []) {
+    declaredRoleNames.add(role.name);
+    const existing = existingRoleByName.get(role.name);
+    if (!existing) {
+      ops.push({
+        kind: 'create-role',
+        role,
+        description: `Create role '${role.name}' with ${role.permissions.length} permission(s)`,
+      });
+      continue;
+    }
+    if ((existing.description ?? '') !== (role.description ?? '')) {
+      ops.push({
+        kind: 'update-role-description',
+        role: role.name,
+        from: existing.description ?? undefined,
+        to: role.description,
+        description: `Update description on role '${role.name}'`,
+      });
+    }
+    const detail = await iam.getRole(existing.id);
+    const existingPerms = new Map<string, Permission>(
+      detail.permissions.map(perm => [permissionKey(perm), perm]),
+    );
+    const desiredPerms = new Map<string, PolicyPermission>(
+      role.permissions.map(perm => [permissionKey(perm), perm]),
+    );
+    for (const [key, perm] of desiredPerms) {
+      if (!existingPerms.has(key)) {
+        ops.push({
+          kind: 'add-role-permission',
+          role: role.name,
+          permission: perm,
+          description: `Add permission ${describePerm(perm)} to role '${role.name}'`,
+        });
+      }
+    }
+    for (const [key, perm] of existingPerms) {
+      if (!desiredPerms.has(key)) {
+        ops.push({
+          kind: 'remove-role-permission',
+          role: role.name,
+          permission: {
+            resource: perm.resource,
+            action: perm.action,
+            effect: perm.effect,
+          },
+          description: `Remove permission ${perm.resource}:${perm.action} from role '${role.name}'`,
+        });
+      }
+    }
+  }
+  if (options.prune) {
+    for (const role of existingRoles) {
+      if (role.isSystem)
+        continue;
+      if (!declaredRoleNames.has(role.name)) {
+        ops.push({
+          kind: 'delete-role',
+          role: role.name,
+          description: `Delete role '${role.name}' (prune)`,
+        });
+      }
+    }
+  }
+
+  // ── Groups ─────────────────────────────────────────────────────────
+  const { groups: existingGroups } = await iam.listGroups({ limit: 10_000 });
+  const existingGroupByName = new Map(existingGroups.map(group => [group.name, group]));
+  const declaredGroupNames = new Set<string>();
+  for (const group of policy.groups ?? []) {
+    declaredGroupNames.add(group.name);
+    const existing = existingGroupByName.get(group.name);
+    if (!existing) {
+      ops.push({
+        kind: 'create-group',
+        group,
+        description: `Create group '${group.name}'`,
+      });
+      continue;
+    }
+    if ((existing.description ?? '') !== (group.description ?? '')) {
+      ops.push({
+        kind: 'update-group-description',
+        group: group.name,
+        from: existing.description ?? undefined,
+        to: group.description,
+        description: `Update description on group '${group.name}'`,
+      });
+    }
+  }
+  if (options.prune) {
+    for (const group of existingGroups) {
+      if (!declaredGroupNames.has(group.name)) {
+        ops.push({
+          kind: 'delete-group',
+          group: group.name,
+          description: `Delete group '${group.name}' (prune)`,
+        });
+      }
+    }
+  }
+
+  // ── Service accounts ───────────────────────────────────────────────
+  const { serviceAccounts: existingSAs } = await iam.listServiceAccounts({ limit: 10_000 });
+  const existingSaByName = new Map<string, ServiceAccount>(existingSAs.map(sa => [sa.name, sa]));
+  const declaredSaNames = new Set<string>();
+
+  for (const sa of policy.serviceAccounts ?? []) {
+    declaredSaNames.add(sa.name);
+    const existing = existingSaByName.get(sa.name);
+    if (!existing) {
+      ops.push({
+        kind: 'create-service-account',
+        serviceAccount: sa,
+        description: `Create service account '${sa.name}'`,
+      });
+      // bind roles after create — emit binding ops too.
+      for (const roleName of sa.roles ?? []) {
+        ops.push({
+          kind: 'bind-service-account-role',
+          serviceAccount: sa.name,
+          role: roleName,
+          description: `Bind role '${roleName}' to service account '${sa.name}'`,
+        });
+      }
+      continue;
+    }
+    const changes: Record<string, unknown> = {};
+    if (sa.displayName !== undefined && existing.displayName !== sa.displayName)
+      changes.displayName = sa.displayName;
+    if (sa.description !== undefined && existing.description !== sa.description)
+      changes.description = sa.description;
+    if (sa.isActive !== undefined && existing.isActive !== sa.isActive)
+      changes.isActive = sa.isActive;
+    if (Object.keys(changes).length > 0) {
+      ops.push({
+        kind: 'update-service-account',
+        serviceAccount: sa.name,
+        changes,
+        description: `Update fields on service account '${sa.name}'`,
+      });
+    }
+    // Policies manage global SA bindings. Read the authoritative binding rows
+    // rather than inferring roles from effective permissions (which is
+    // ambiguous for shared/direct permissions and invisible for empty roles).
+    const desiredRoles = new Set(sa.roles ?? []);
+    const allRoles = await iam.getRoles();
+    const roleByName = new Map(allRoles.map(role => [role.name, role]));
+    const roleNameById = new Map(allRoles.map(role => [role.id, role.name]));
+    const bindings = await iam.listRoleBindingsForSubject(
+      { type: 'SERVICE_ACCOUNT', id: existing.id },
+      null,
+    );
+    const currentRoleNames = new Set(
+      bindings
+        .map(binding => roleNameById.get(binding.roleId))
+        .filter((name): name is string => name !== undefined),
+    );
+    for (const desired of desiredRoles) {
+      if (
+        !currentRoleNames.has(desired)
+        && (roleByName.has(desired) || declaredRoleNames.has(desired))
+      ) {
+        ops.push({
+          kind: 'bind-service-account-role',
+          serviceAccount: sa.name,
+          role: desired,
+          description: `Bind role '${desired}' to service account '${sa.name}'`,
+        });
+      }
+    }
+    if (options.prune) {
+      for (const current of currentRoleNames) {
+        if (!desiredRoles.has(current)) {
+          ops.push({
+            kind: 'unbind-service-account-role',
+            serviceAccount: sa.name,
+            role: current,
+            description: `Unbind role '${current}' from service account '${sa.name}' (prune)`,
+          });
+        }
+      }
+    }
+  }
+  if (options.prune) {
+    for (const sa of existingSAs) {
+      if (!declaredSaNames.has(sa.name)) {
+        ops.push({
+          kind: 'delete-service-account',
+          serviceAccount: sa.name,
+          description: `Delete service account '${sa.name}' (prune)`,
+        });
+      }
+    }
+  }
+
+  return { ops, inSync: ops.length === 0 };
+}

package/src/core/policy/loader.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { loadPolicy, parsePolicyDocument, resolvePolicyPath } from './loader';
+
+const tempDirs: string[] = [];
+const sparseArray: unknown[] = [];
+sparseArray.length = 1;
+
+afterEach(async () => {
+  const { rm } = await import('node:fs/promises');
+  await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true })));
+});
+
+describe('policy loader', () => {
+  it('loads an env-specific file asynchronously and validates it', async () => {
+    const { mkdtemp, writeFile } = await import('node:fs/promises');
+    const { join } = await import('node:path');
+    const { tmpdir } = await import('node:os');
+    const cwd = await mkdtemp(join(tmpdir(), 'fortress-policy-'));
+    tempDirs.push(cwd);
+    await writeFile(join(cwd, 'fortress.policy.json'), JSON.stringify({ groups: [{ name: 'base' }] }));
+    await writeFile(join(cwd, 'fortress.policy.production.json'), JSON.stringify({
+      roles: [{ name: 'reader', permissions: [{ resource: 'article', action: 'read' }] }],
+    }));
+
+    expect(await resolvePolicyPath({ cwd, env: 'production' }))
+      .toBe(join(cwd, 'fortress.policy.production.json'));
+    const { policy } = await loadPolicy({ cwd, env: 'production' });
+    expect(policy.roles?.[0].name).toBe('reader');
+  });
+
+  it('allows annotations and deduplicates equivalent ALLOW permissions', () => {
+    const policy = parsePolicyDocument({
+      $comment: 'documented annotation',
+      roles: [{
+        name: 'reader',
+        permissions: [
+          { resource: 'article', action: 'read' },
+          { resource: 'article', action: 'read', effect: 'ALLOW' },
+        ],
+      }],
+    });
+    expect(policy.roles?.[0].permissions).toEqual([
+      { resource: 'article', action: 'read' },
+    ]);
+  });
+
+  it.each([
+    [null, 'must be an object'],
+    [[], 'must be an object'],
+    [{ groups: sparseArray }, 'dense array of objects'],
+    [{ unknown: [] }, 'Unknown policy field'],
+    [{ $comment: 1 }, '$comment must be a string'],
+    [{ $schema: false }, '$schema must be a string'],
+    [{ roles: [{ name: 'x' }] }, 'permissions must be an array'],
+    [{ roles: [{ name: 'x', permissions: [{ resource: 'r', action: 'a', effect: 'MAYBE' }] }] }, 'effect must be ALLOW or DENY'],
+    [{ groups: [{ name: 'x' }, { name: 'x' }] }, 'duplicate name'],
+    [{ serviceAccounts: [{ name: 'bot', roles: 'reader' }] }, 'roles must be an array'],
+    [{ roles: [{ name: 'x', permissions: [{ resource: 'r', action: 'a', effectt: 'DENY' }] }] }, 'Unknown field'],
+    [{ groups: [{ name: 'x', descriptino: 'typo' }] }, 'Unknown field'],
+  ])('rejects malformed policy documents', (value, message) => {
+    expect(() => parsePolicyDocument(value)).toThrow(message);
+  });
+});

package/src/core/policy/loader.ts

@@ -0,0 +1,214 @@
+/**
+ * Load a {@link PolicyDocument} from disk with optional env-specific
+ * override. Node filesystem/path modules are imported only when these
+ * file-oriented helpers run, keeping the package root import runtime-neutral.
+ *
+ * @module
+ */
+
+import type { PolicyDocument } from './types';
+import { Errors } from '../errors';
+
+export interface LoadPolicyOptions {
+  /** Override the default `fortress.policy.json` path. */
+  filePath?: string;
+  /** Pick an env-specific file (`fortress.policy.<env>.json`). Defaults to `process.env.FORTRESS_ENV`. */
+  env?: string;
+  /** Working directory when resolving the default file paths. Defaults to `process.cwd()`. */
+  cwd?: string;
+}
+
+/** Default base file name. */
+export const DEFAULT_POLICY_FILE = 'fortress.policy.json';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function stringField(value: unknown, path: string): string {
+  if (typeof value !== 'string' || value.length === 0)
+    throw Errors.badRequest(`${path} must be a non-empty string`);
+  return value;
+}
+
+function optionalString(value: unknown, path: string): string | undefined {
+  if (value === undefined)
+    return undefined;
+  return stringField(value, path);
+}
+
+function collection(value: unknown, path: string): Record<string, unknown>[] {
+  if (value === undefined)
+    return [];
+  if (
+    !Array.isArray(value)
+    || value.some(item => !isRecord(item))
+    || Object.keys(value).length !== value.length
+  ) {
+    throw Errors.badRequest(`${path} must be a dense array of objects`);
+  }
+  return value;
+}
+
+function assertAllowedFields(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  path: string,
+): void {
+  const allowedSet = new Set(allowed);
+  for (const key of Object.keys(value)) {
+    if (!allowedSet.has(key))
+      throw Errors.badRequest(`Unknown field '${path}.${key}'`);
+  }
+}
+
+function assertUniqueNames(items: Array<{ name: string }>, path: string): void {
+  const names = new Set<string>();
+  for (const item of items) {
+    if (names.has(item.name))
+      throw Errors.badRequest(`${path} contains duplicate name '${item.name}'`);
+    names.add(item.name);
+  }
+}
+
+/** Validate and normalize an untrusted policy JSON value. */
+export function parsePolicyDocument(value: unknown): PolicyDocument {
+  if (!isRecord(value))
+    throw Errors.badRequest('Policy document must be an object');
+  const allowed = new Set(['$comment', '$schema', 'resources', 'roles', 'groups', 'serviceAccounts']);
+  for (const annotation of ['$comment', '$schema'] as const) {
+    if (value[annotation] !== undefined && typeof value[annotation] !== 'string')
+      throw Errors.badRequest(`${annotation} must be a string`);
+  }
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key))
+      throw Errors.badRequest(`Unknown policy field '${key}'`);
+  }
+
+  const resources = collection(value.resources, 'resources').map((item, index) => {
+    assertAllowedFields(item, ['name', 'actions', 'description'], `resources[${index}]`);
+    if (!Array.isArray(item.actions) || item.actions.some(action => typeof action !== 'string' || action.length === 0))
+      throw Errors.badRequest(`resources[${index}].actions must be an array of non-empty strings`);
+    return {
+      name: stringField(item.name, `resources[${index}].name`),
+      actions: [...new Set(item.actions as string[])],
+      description: optionalString(item.description, `resources[${index}].description`),
+    };
+  });
+  const roles = collection(value.roles, 'roles').map((item, index) => {
+    assertAllowedFields(item, ['name', 'description', 'permissions'], `roles[${index}]`);
+    if (!Array.isArray(item.permissions))
+      throw Errors.badRequest(`roles[${index}].permissions must be an array of objects`);
+    const permissions = collection(item.permissions, `roles[${index}].permissions`).map((permission, permissionIndex) => {
+      assertAllowedFields(
+        permission,
+        ['resource', 'action', 'effect'],
+        `roles[${index}].permissions[${permissionIndex}]`,
+      );
+      const effect = permission.effect;
+      if (effect !== undefined && effect !== 'ALLOW' && effect !== 'DENY')
+        throw Errors.badRequest(`roles[${index}].permissions[${permissionIndex}].effect must be ALLOW or DENY`);
+      const normalizedEffect: 'ALLOW' | 'DENY' = effect === 'DENY' ? 'DENY' : 'ALLOW';
+      return {
+        resource: stringField(permission.resource, `roles[${index}].permissions[${permissionIndex}].resource`),
+        action: stringField(permission.action, `roles[${index}].permissions[${permissionIndex}].action`),
+        ...(normalizedEffect === 'DENY' ? { effect: normalizedEffect } : {}),
+      };
+    });
+    const uniquePermissions = new Map(
+      permissions.map(permission => [
+        `${permission.resource}\u0000${permission.action}\u0000${permission.effect ?? 'ALLOW'}`,
+        permission,
+      ]),
+    );
+    return {
+      name: stringField(item.name, `roles[${index}].name`),
+      description: optionalString(item.description, `roles[${index}].description`),
+      permissions: [...uniquePermissions.values()],
+    };
+  });
+  const groups = collection(value.groups, 'groups').map((item, index) => {
+    assertAllowedFields(item, ['name', 'description'], `groups[${index}]`);
+    return {
+      name: stringField(item.name, `groups[${index}].name`),
+      description: optionalString(item.description, `groups[${index}].description`),
+    };
+  });
+  const serviceAccounts = collection(value.serviceAccounts, 'serviceAccounts').map((item, index) => {
+    assertAllowedFields(
+      item,
+      ['name', 'displayName', 'description', 'isActive', 'roles'],
+      `serviceAccounts[${index}]`,
+    );
+    if (item.roles !== undefined && (!Array.isArray(item.roles) || item.roles.some(role => typeof role !== 'string' || role.length === 0)))
+      throw Errors.badRequest(`serviceAccounts[${index}].roles must be an array of non-empty strings`);
+    if (item.isActive !== undefined && typeof item.isActive !== 'boolean')
+      throw Errors.badRequest(`serviceAccounts[${index}].isActive must be a boolean`);
+    return {
+      name: stringField(item.name, `serviceAccounts[${index}].name`),
+      displayName: optionalString(item.displayName, `serviceAccounts[${index}].displayName`),
+      description: optionalString(item.description, `serviceAccounts[${index}].description`),
+      ...(typeof item.isActive === 'boolean' ? { isActive: item.isActive } : {}),
+      ...(Array.isArray(item.roles) ? { roles: [...new Set(item.roles as string[])] } : {}),
+    };
+  });
+
+  assertUniqueNames(resources, 'resources');
+  assertUniqueNames(roles, 'roles');
+  assertUniqueNames(groups, 'groups');
+  assertUniqueNames(serviceAccounts, 'serviceAccounts');
+  return {
+    ...(value.resources !== undefined ? { resources } : {}),
+    ...(value.roles !== undefined ? { roles } : {}),
+    ...(value.groups !== undefined ? { groups } : {}),
+    ...(value.serviceAccounts !== undefined ? { serviceAccounts } : {}),
+  };
+}
+
+async function exists(filePath: string): Promise<boolean> {
+  const { access } = await import('node:fs/promises');
+  try {
+    await access(filePath);
+    return true;
+  }
+  catch (err) {
+    if ((err as { code?: string }).code === 'ENOENT')
+      return false;
+    throw err;
+  }
+}
+
+/** Return the resolved policy-file path for an environment, or `null` if no file exists. */
+export async function resolvePolicyPath(options: LoadPolicyOptions = {}): Promise<string | null> {
+  if (options.filePath)
+    return await exists(options.filePath) ? options.filePath : null;
+
+  const { join } = await import('node:path');
+  const cwd = options.cwd ?? process.cwd();
+  const env = options.env ?? process.env.FORTRESS_ENV;
+  if (env) {
+    const envPath = join(cwd, `fortress.policy.${env}.json`);
+    if (await exists(envPath))
+      return envPath;
+  }
+  const basePath = join(cwd, DEFAULT_POLICY_FILE);
+  return await exists(basePath) ? basePath : null;
+}
+
+/** Load and parse a policy document. Throws when the file is missing or unparseable. */
+export async function loadPolicy(options: LoadPolicyOptions = {}): Promise<{ policy: PolicyDocument; filePath: string }> {
+  const filePath = await resolvePolicyPath(options);
+  if (!filePath)
+    throw Errors.notFound(`No policy file found (looked for fortress.policy.<env>.json then fortress.policy.json)`);
+  try {
+    const { readFile } = await import('node:fs/promises');
+    const text = await readFile(filePath, 'utf-8');
+    const parsed = JSON.parse(text) as unknown;
+    return { policy: parsePolicyDocument(parsed), filePath };
+  }
+  catch (err) {
+    if (err instanceof SyntaxError)
+      throw Errors.badRequest(`Failed to parse policy file ${filePath}: ${err.message}`);
+    throw err;
+  }
+}