@bajustone/fortress 1.0.0-rc.1

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

@@ -0,0 +1,232 @@
+/**
+ * Policy-as-code end-to-end tests (P1-7).
+ */
+
+import type { PolicyDocument } from './types';
+import { describe, expect, it } from 'vitest';
+import { createTestAdapter } from '../../testing';
+import { createFortress } from '../fortress';
+import { applyPolicyPlan } from './apply';
+import { diffPolicy } from './diff';
+
+const SECRET = 'policy-test-secret-at-least-32-bytes!';
+
+function freshFortress() {
+  return createFortress({
+    jwt: { key: SECRET },
+    database: createTestAdapter(),
+  });
+}
+
+const basePolicy: PolicyDocument = {
+  roles: [
+    {
+      name: 'editor',
+      description: 'Can edit articles',
+      permissions: [
+        { resource: 'article', action: 'create' },
+        { resource: 'article', action: 'update' },
+      ],
+    },
+  ],
+  groups: [
+    { name: 'engineering', description: 'Engineering team' },
+  ],
+  serviceAccounts: [
+    { name: 'ci-bot', displayName: 'CI Bot', isActive: true, roles: ['editor'] },
+  ],
+};
+
+describe('policy-as-code', () => {
+  it('diff against an empty IAM produces create ops for everything declared', async () => {
+    const fortress = freshFortress();
+    const plan = await diffPolicy(basePolicy, fortress.iam);
+    expect(plan.inSync).toBe(false);
+    const kinds = plan.ops.map(op => op.kind).sort();
+    expect(kinds).toContain('create-role');
+    expect(kinds).toContain('create-group');
+    expect(kinds).toContain('create-service-account');
+    expect(kinds).toContain('bind-service-account-role');
+  });
+
+  it('apply runs every op and leaves the diff in-sync', async () => {
+    const fortress = freshFortress();
+    const plan = await diffPolicy(basePolicy, fortress.iam);
+    const result = await applyPolicyPlan(plan, fortress.iam);
+    expect(result.errors).toEqual([]);
+    expect(result.applied.length).toBeGreaterThan(0);
+
+    const second = await diffPolicy(basePolicy, fortress.iam);
+    expect(second.inSync).toBe(true);
+  });
+
+  it('applies resource operations in memory and converges without filesystem access', async () => {
+    const fortress = freshFortress();
+    const policy: PolicyDocument = {
+      resources: [{ name: 'article', description: 'Articles', actions: ['read', 'write'] }],
+    };
+
+    const result = await applyPolicyPlan(await diffPolicy(policy, fortress.iam), fortress.iam);
+    expect(result.errors).toEqual([]);
+    expect(result.applied.map(op => op.kind)).toEqual(['create-resource']);
+    expect((await fortress.iam.getResources()).resources.article).toMatchObject({
+      description: 'Articles',
+      actions: ['read', 'write'],
+    });
+    expect((await diffPolicy(policy, fortress.iam)).inSync).toBe(true);
+  });
+
+  it('clears role descriptions and converges', async () => {
+    const fortress = freshFortress();
+    await applyPolicyPlan(await diffPolicy(basePolicy, fortress.iam), fortress.iam);
+    const cleared: PolicyDocument = {
+      ...basePolicy,
+      roles: [{ ...basePolicy.roles![0], description: undefined }],
+    };
+
+    const result = await applyPolicyPlan(await diffPolicy(cleared, fortress.iam), fortress.iam);
+    expect(result.errors).toEqual([]);
+    expect((await diffPolicy(cleared, fortress.iam)).inSync).toBe(true);
+    expect((await fortress.iam.getRoles()).find(role => role.name === 'editor')?.description).toBeNull();
+  });
+
+  it('tracks real service-account bindings to zero-permission roles', async () => {
+    const fortress = freshFortress();
+    const policy: PolicyDocument = {
+      roles: [{ name: 'empty-role', permissions: [] }],
+      serviceAccounts: [{ name: 'empty-role-bot', roles: ['empty-role'] }],
+    };
+
+    const result = await applyPolicyPlan(await diffPolicy(policy, fortress.iam), fortress.iam);
+    expect(result.errors).toEqual([]);
+    expect((await diffPolicy(policy, fortress.iam, { prune: true })).inSync).toBe(true);
+  });
+
+  it('binds a newly declared role to an existing service account in one plan', async () => {
+    const fortress = freshFortress();
+    await fortress.iam.createServiceAccount({ name: 'existing-bot' });
+    const policy: PolicyDocument = {
+      roles: [{ name: 'new-role', permissions: [] }],
+      serviceAccounts: [{ name: 'existing-bot', roles: ['new-role'] }],
+    };
+
+    const plan = await diffPolicy(policy, fortress.iam);
+    expect(plan.ops.map(op => op.kind)).toEqual(expect.arrayContaining([
+      'create-role',
+      'bind-service-account-role',
+    ]));
+    const result = await applyPolicyPlan(plan, fortress.iam);
+    expect(result.errors).toEqual([]);
+    expect((await diffPolicy(policy, fortress.iam)).inSync).toBe(true);
+  });
+
+  it('global policy unbinding preserves tenant-scoped role bindings', async () => {
+    const fortress = freshFortress();
+    const role = await fortress.iam.createRole('scoped-role', []);
+    const serviceAccount = await fortress.iam.createServiceAccount({ name: 'scoped-bot' });
+    await fortress.iam.bindRoleToServiceAccount(serviceAccount.id, role.id);
+    await fortress.iam.bindRoleToServiceAccount(serviceAccount.id, role.id, 'tenant-a');
+    const policy: PolicyDocument = {
+      roles: [{ name: 'scoped-role', permissions: [] }],
+      serviceAccounts: [{ name: 'scoped-bot', roles: [] }],
+    };
+
+    const result = await applyPolicyPlan(
+      await diffPolicy(policy, fortress.iam, { prune: true }),
+      fortress.iam,
+    );
+    expect(result.errors).toEqual([]);
+    const remaining = await fortress.iam.listRoleBindingsForSubject({
+      type: 'SERVICE_ACCOUNT',
+      id: serviceAccount.id,
+    });
+    expect(remaining.map(binding => binding.tenantId)).toEqual(['tenant-a']);
+  });
+
+  it('unbinds retained service accounts before pruning their old role', async () => {
+    const fortress = freshFortress();
+    const initial: PolicyDocument = {
+      roles: [{ name: 'old-role', permissions: [] }],
+      serviceAccounts: [{ name: 'retained-bot', roles: ['old-role'] }],
+    };
+    await applyPolicyPlan(await diffPolicy(initial, fortress.iam), fortress.iam);
+    const next: PolicyDocument = {
+      roles: [],
+      serviceAccounts: [{ name: 'retained-bot', roles: [] }],
+    };
+
+    const plan = await diffPolicy(next, fortress.iam, { prune: true });
+    expect(plan.ops.map(op => op.kind)).toEqual(expect.arrayContaining([
+      'unbind-service-account-role',
+      'delete-role',
+    ]));
+    const result = await applyPolicyPlan(plan, fortress.iam);
+    expect(result.errors).toEqual([]);
+    expect((await diffPolicy(next, fortress.iam, { prune: true })).inSync).toBe(true);
+  });
+
+  it('add-role-permission op is emitted when the policy widens a role', async () => {
+    const fortress = freshFortress();
+    await applyPolicyPlan(await diffPolicy(basePolicy, fortress.iam), fortress.iam);
+
+    const widened: PolicyDocument = {
+      ...basePolicy,
+      roles: [
+        {
+          ...basePolicy.roles![0],
+          permissions: [
+            ...basePolicy.roles![0].permissions,
+            { resource: 'article', action: 'delete' },
+          ],
+        },
+      ],
+    };
+    const plan = await diffPolicy(widened, fortress.iam);
+    const ops = plan.ops.map(op => op.kind);
+    expect(ops).toContain('add-role-permission');
+    const result = await applyPolicyPlan(plan, fortress.iam);
+    expect(result.errors).toEqual([]);
+    expect((await diffPolicy(widened, fortress.iam)).inSync).toBe(true);
+  });
+
+  it('remove-role-permission op is emitted when the policy narrows a role', async () => {
+    const fortress = freshFortress();
+    await applyPolicyPlan(await diffPolicy(basePolicy, fortress.iam), fortress.iam);
+
+    const narrowed: PolicyDocument = {
+      ...basePolicy,
+      roles: [
+        {
+          ...basePolicy.roles![0],
+          permissions: [{ resource: 'article', action: 'create' }],
+        },
+      ],
+    };
+    const plan = await diffPolicy(narrowed, fortress.iam);
+    expect(plan.ops.some(op => op.kind === 'remove-role-permission')).toBe(true);
+    const result = await applyPolicyPlan(plan, fortress.iam);
+    expect(result.errors).toEqual([]);
+    expect((await diffPolicy(narrowed, fortress.iam)).inSync).toBe(true);
+  });
+
+  it('requires explicit acknowledgement before pruning with an empty policy', async () => {
+    const fortress = freshFortress();
+    await applyPolicyPlan(await diffPolicy(basePolicy, fortress.iam), fortress.iam);
+
+    // Empty policy with prune should delete role/group/SA.
+    const empty: PolicyDocument = {};
+    await expect(diffPolicy(empty, fortress.iam, { prune: true })).rejects.toThrow('allowEmptyPrune');
+    const plan = await diffPolicy(empty, fortress.iam, { prune: true, allowEmptyPrune: true });
+    const kinds = plan.ops.map(op => op.kind).sort();
+    expect(kinds).toContain('delete-role');
+    expect(kinds).toContain('delete-group');
+    expect(kinds).toContain('delete-service-account');
+
+    const result = await applyPolicyPlan(plan, fortress.iam);
+    expect(result.errors).toEqual([]);
+    expect((await diffPolicy(empty, fortress.iam, {
+      prune: true,
+      allowEmptyPrune: true,
+    })).inSync).toBe(true);
+  });
+});

package/src/core/policy/types.ts

@@ -0,0 +1,105 @@
+/**
+ * Declarative policy types for policy-as-code (P1-7).
+ *
+ * A policy file declares the desired state of Fortress-owned IAM
+ * resources: resources/actions, roles + permissions, groups, and
+ * service accounts (with their role bindings). The diff/apply pipeline
+ * computes the operations needed to reconcile the live database with the
+ * declared state.
+ *
+ * What's covered:
+ * - Resources + actions (extends today's `fortress.resources.json`).
+ * - Roles with permission lists.
+ * - Groups (declared shells; user memberships managed via runtime APIs).
+ * - Service accounts with role bindings.
+ *
+ * What's intentionally NOT covered:
+ * - OAuth clients (have secrets; manage via admin endpoints).
+ * - User accounts / user-group memberships (user data, not policy).
+ * - Tenant data and per-tenant role bindings (large scale; declare in
+ *   per-tenant policy files if needed).
+ *
+ * @module
+ */
+
+/** Resource definition (action list shared with the existing `fortress.resources.json` shape). */
+export interface PolicyResource {
+  name: string;
+  actions: string[];
+  description?: string;
+}
+
+/** Permission entry inside a role declaration. `effect` defaults to ALLOW. */
+export interface PolicyPermission {
+  resource: string;
+  action: string;
+  effect?: 'ALLOW' | 'DENY';
+}
+
+/** Role declaration. Permissions are the *complete* desired set for the role; extras are removed on apply. */
+export interface PolicyRole {
+  name: string;
+  description?: string;
+  permissions: PolicyPermission[];
+}
+
+/** Group declaration. User memberships are intentionally not managed via policy files. */
+export interface PolicyGroup {
+  name: string;
+  description?: string;
+}
+
+/** Service-account declaration. Roles list is the complete desired binding set; extras are unbound on apply. */
+export interface PolicyServiceAccount {
+  name: string;
+  displayName?: string;
+  description?: string;
+  isActive?: boolean;
+  /** Role names to bind to this service account. Bindings outside this list are removed on apply. */
+  roles?: string[];
+}
+
+/** Top-level policy document. */
+export interface PolicyDocument {
+  resources?: PolicyResource[];
+  roles?: PolicyRole[];
+  groups?: PolicyGroup[];
+  serviceAccounts?: PolicyServiceAccount[];
+}
+
+/** Single op produced by `diffPolicy`. Tag is human-readable; `description` flattens for logs. */
+export type PolicyOp
+  = | { kind: 'create-resource'; resource: PolicyResource; description: string }
+    | { kind: 'add-resource-action'; resource: string; action: string; description: string }
+    | { kind: 'create-role'; role: PolicyRole; description: string }
+    | { kind: 'update-role-description'; role: string; from?: string; to?: string; description: string }
+    | { kind: 'add-role-permission'; role: string; permission: PolicyPermission; description: string }
+    | { kind: 'remove-role-permission'; role: string; permission: PolicyPermission; description: string }
+    | { kind: 'delete-role'; role: string; description: string }
+    | { kind: 'create-group'; group: PolicyGroup; description: string }
+    | { kind: 'update-group-description'; group: string; from?: string; to?: string; description: string }
+    | { kind: 'delete-group'; group: string; description: string }
+    | { kind: 'create-service-account'; serviceAccount: PolicyServiceAccount; description: string }
+    | { kind: 'update-service-account'; serviceAccount: string; changes: Record<string, unknown>; description: string }
+    | { kind: 'bind-service-account-role'; serviceAccount: string; role: string; description: string }
+    | { kind: 'unbind-service-account-role'; serviceAccount: string; role: string; description: string }
+    | { kind: 'delete-service-account'; serviceAccount: string; description: string };
+
+/** Diff result returned by `diffPolicy`. */
+export interface PolicyPlan {
+  ops: PolicyOp[];
+  /** `true` when there is nothing to reconcile. */
+  inSync: boolean;
+}
+
+/** Options for `diffPolicy`. */
+export interface DiffPolicyOptions {
+  /**
+   * Prune resources/roles/groups/service-accounts present in the database
+   * but absent from the policy file. Default `false` — apply only adds
+   * and updates unless the operator opts in to deletions.
+   */
+  prune?: boolean;
+  /** Explicitly acknowledge that pruning with no declared entities deletes all managed IAM state. */
+  allowEmptyPrune?: boolean;
+}