Create your first extension

import { randomUUID } from 'node:crypto';
import { IamError, type AuditEvent, type IamPlugin, type StoredRecord } from 'better-iam/core';

/** The one active freeze of a tenant, stored in the extension's own collection. */
export interface ChangeFreeze extends StoredRecord {
  reason: string;
  startedBy: string;
  startedAt: number;
}

export interface ChangeFreezeOptions {
  /** Called after a freeze starts or ends, once the change has committed. */
  onChange?(event: AuditEvent): Promise<void> | void;
}

const COLLECTION = 'changeFreezes';
/** The natural key of the active freeze: at most one per tenant, enforced by the database. */
const ACTIVE = 'active';
/** Access changes the freeze blocks: creating, updating, and deleting roles, policies, and bindings. */
const FROZEN_ACTIONS = /^iam:(roles|policies|bindings):(create|update|delete)$/;

/** Rejects anything but a JSON object with only the listed fields. */
function fields(value: unknown, allowed: string[]): Record<string, unknown> {
  if (!value || typeof value !== 'object' || Array.isArray(value))
    throw new IamError('INVALID_INPUT', 'A JSON object is required');
  const input = value as Record<string, unknown>;
  for (const key of Object.keys(input))
    if (!allowed.includes(key)) throw new IamError('INVALID_INPUT', `Unexpected field ${key}`);
  return input;
}

export function changeFreeze(options: ChangeFreezeOptions = {}): IamPlugin {
  return {
    id: 'change-freeze',
    actions: ['freeze:read', 'freeze:start', 'freeze:end'],
    endpoints: [
      {
        method: 'POST',
        path: 'start',
        action: 'freeze:start',
        validate(value) {
          const input = fields(value, ['tenantId', 'reason']);
          const reason = typeof input.reason === 'string' ? input.reason.trim() : '';
          if (!reason || reason.length > 200)
            throw new IamError('INVALID_INPUT', 'reason must be 1-200 characters');
          return { tenantId: input.tenantId, reason };
        },
        async handler({ store, principal, tenantId }, input) {
          const [current] = await store.find<ChangeFreeze>(COLLECTION, { tenantId, uniqueKey: ACTIVE });
          if (current) throw new IamError('CONFLICT', 'A change freeze is already active', 409);
          return store.insert<ChangeFreeze>(COLLECTION, {
            id: randomUUID(),
            tenantId,
            uniqueKey: ACTIVE,
            reason: String(input.reason),
            startedBy: principal.identity.id,
            startedAt: Date.now(),
          });
        },
      },
      {
        method: 'POST',
        path: 'end',
        action: 'freeze:end',
        validate(value) {
          const input = fields(value, ['tenantId']);
          return { tenantId: input.tenantId };
        },
        async handler({ store, tenantId }) {
          const [current] = await store.find<ChangeFreeze>(COLLECTION, { tenantId, uniqueKey: ACTIVE });
          if (!current) throw new IamError('NOT_FOUND', 'No change freeze is active', 404);
          await store.delete(COLLECTION, current.id);
          return { ended: current };
        },
      },
      {
        method: 'POST',
        path: 'status',
        action: 'freeze:read',
        validate(value) {
          const input = fields(value, ['tenantId']);
          return { tenantId: input.tenantId };
        },
        async handler({ store, tenantId }) {
          const [current] = await store.find<ChangeFreeze>(COLLECTION, { tenantId, uniqueKey: ACTIVE });
          return { freeze: current ?? null };
        },
      },
    ],
    hooks: {
      // Runs inside every operation's transaction, after authorization and before the change.
      async beforeOperation({ store, tenantId, action }) {
        if (!FROZEN_ACTIONS.test(action)) return;
        const [current] = await store.find<ChangeFreeze>(COLLECTION, { tenantId, uniqueKey: ACTIVE });
        if (current)
          throw new IamError('CHANGE_FREEZE', `Access changes are frozen: ${current.reason}`, 409);
      },
    },
    // Runs after commit from the audit dispatcher, at least once per event.
    async afterAudit(event) {
      if (event.outcome !== 'allow') return;
      if (event.action === 'freeze:start' || event.action === 'freeze:end')
        await options.onChange?.(event);
    },
    // Removes the extension's records when a retention purge deletes tenants.
    async purge(store, tenantIds) {
      for (const tenantId of tenantIds)
        for (const freeze of await store.find<ChangeFreeze>(COLLECTION, { tenantId }))
          await store.delete(COLLECTION, freeze.id);
    },
  };
}

import { betterIam } from 'better-iam';
import { changeFreeze } from './iam/change-freeze';
import config from './better-iam.config.mjs';

export const iam = betterIam({
  ...config,
  plugins: [
    changeFreeze({
      onChange: (event) => {
        console.log(`${event.action} in tenant ${event.tenantId} by ${event.actorId}`);
      },
    }),
  ],
});

import { iam } from '../iam';

const owner = { token: process.env.OWNER_TOKEN! };
const tenantId = process.env.TENANT_ID!;

const releaseManager = await iam.api.roles.create(owner, {
  tenantId,
  name: 'Release manager',
  permissions: ['freeze:read', 'freeze:start', 'freeze:end'],
});
await iam.api.bindings.create(owner, {
  tenantId,
  roleId: releaseManager.id,
  subjectType: 'identity',
  subjectId: process.env.RELEASE_MANAGER_ID!,
});

import { iam } from '../iam';

// Every few seconds: hand committed audit events to plugins, events.onEvent, and subscribers.
setInterval(() => {
  iam.events.dispatch().catch((error) => console.error('audit dispatch failed', error));
}, 5_000);

import { afterEach, describe, expect, it } from 'vitest';
import type { AuditEvent } from 'better-iam/core';
import { changeFreeze, type ChangeFreeze } from '../iam/change-freeze';
import { createIamFixture, type IamFixture } from './iam-fixture';

let f: IamFixture | undefined;
afterEach(async () => {
  await f?.close();
});

describe('change-freeze extension', () => {
  it('blocks access changes while a freeze is active', async () => {
    const changes: AuditEvent[] = [];
    f = await createIamFixture({
      plugins: [changeFreeze({ onChange: (event) => void changes.push(event) })],
    });
    const { iam, ownerCredential, tenantId } = f;
    const call = (path: string, input: Record<string, unknown> = {}) =>
      iam.callPlugin(ownerCredential, { pluginId: 'change-freeze', path, tenantId, input });

    const started = (await call('start', { reason: 'Quarter-end close' })) as ChangeFreeze;
    expect(started).toMatchObject({ tenantId, reason: 'Quarter-end close' });
    await expect(call('start', { reason: 'again' })).rejects.toMatchObject({ code: 'CONFLICT' });
    await expect(call('start', { reason: 'x', extra: 1 })).rejects.toMatchObject({
      code: 'INVALID_INPUT',
    });

    // The check refuses writes and lets reads through.
    await expect(
      iam.api.roles.create(ownerCredential, { tenantId, name: 'Auditor', permissions: ['freeze:read'] }),
    ).rejects.toMatchObject({ code: 'CHANGE_FREEZE', status: 409 });
    await expect(iam.api.roles.list(ownerCredential, { tenantId })).resolves.toBeDefined();

    await call('end');
    await expect(
      iam.api.roles.create(ownerCredential, { tenantId, name: 'Auditor', permissions: ['freeze:read'] }),
    ).resolves.toMatchObject({ name: 'Auditor' });

    // People need a role that grants the action.
    const bob = await f.member('bob');
    await expect(
      iam.callPlugin(bob.credential, { pluginId: 'change-freeze', path: 'status', tenantId }),
    ).rejects.toMatchObject({ code: 'ACCESS_DENIED' });
    const ada = await f.member('ada', ['freeze:read']);
    await expect(
      iam.callPlugin(ada.credential, { pluginId: 'change-freeze', path: 'status', tenantId }),
    ).resolves.toEqual({ freeze: null });

    // Events reach afterAudit only when the dispatcher runs.
    expect(changes).toHaveLength(0);
    await iam.events.dispatch();
    expect(changes.map((event) => event.action).sort()).toEqual(['freeze:end', 'freeze:start']);
  });
});