Compliance center

Every audit asks the same questions about identity: must people use a second factor, and do they? Do sessions and API keys end? Do leavers lose their access? Is access reviewed, and how many people can do everything? Can anyone edit the logs? Answering them usually means screenshots and spreadsheets pulled together once a year.

The compliance center answers them continuously. Built-in checks read the tenant's identity and access state; a tenant turns them into controls, evaluates them every day, accepts individual findings with time-boxed exceptions that a second person approves, sees the status of each framework requirement, and hands its auditors a signed evidence pack they can verify offline.

await iam.api.compliance.adoptFramework(admin, { tenantId, framework: 'soc2' });
const { run, results } = await iam.api.compliance.evaluate(admin, { tenantId });
const [soc2] = await iam.api.compliance.status(admin, { tenantId, framework: 'soc2' });

Routes: POST /api/iam/compliance/adoptFramework, POST /api/iam/compliance/evaluate, POST /api/iam/compliance/status

Checks

Each check returns a status (pass, fail, warn or not-applicable), metrics, and findings that name what needs attention: identity:ID, session:ID (an API key), trust:ID, role:ID, campaign:ID, request:ID, or tenant:ID:condition for an organization-wide setting (tenant:ID:mfa-optional). Stored findings identify people only by ID; people's names are added when results are read, for callers who may read the directory (iam:identities:read). The API reference and catalog list every parameter with its range, and @better-iam/server exports the checks and mappings as complianceChecks and complianceFrameworks.

Controls

A control is a check as your organization runs it: a key, a name, parameters, and the requirements it evidences.

• adoptFramework (soc2, iso27001, nist-800-53 or gdpr) creates one control per check the framework uses, keyed by the check's id and mapped as framework:requirement (soc2:CC6.1). Frameworks share controls: adopting a second one adds its mappings to the controls that exist.
• createControl runs a check with your own parameters and mappings, for example inactive accounts after 30 days, mapped to an internal policy as well as to SOC 2.

await iam.api.compliance.createControl(admin, {
  tenantId,
  key: 'inactive-30',
  name: 'Accounts unused for 30 days are reviewed',
  checkId: 'inactive-accounts',
  params: { days: 30 },
  mappings: ['internal:POL-7', 'soc2:CC6.2'],
});

Route: POST /api/iam/compliance/createControl

A tenant holds at most 200 controls. updateControl changes parameters, mappings or enabled; disabled controls are not evaluated, and keep the requirements they are mapped to from passing. deleteControl revokes the control's exceptions, which stay as history.

Evaluating

evaluate (iam:compliance:evaluate) runs the enabled controls, at most once a minute per organization (RATE_LIMITED otherwise). The checks read outside any transaction, so evaluating a large directory never holds the store's write lock; the results are then written in one short transaction. Each result records the status, the status before exceptions (rawStatus), a summary, metrics and up to 200 findings; evaluate returns the statuses and counts, and listResults the findings. A check that cannot run fails its control rather than passing by omission. The run keeps counts per status and a SHA-256 digest of its results, which is also written to the tamper-evident audit log as compliance:evaluate. When a control starts or stops failing, the run records compliance:control:fail or compliance:control:recover: subscribe a webhook to hear about regressions.

Results more than three days old are marked stale, and a stale control counts as not evaluated in the requirement status, so a scheduler that stopped running cannot leave old passes standing.

Exceptions

Some findings are accepted for a while: a person on leave, a service account with a compensating control, a fix that is planned. createException names the control, the finding's subject, a reason, and an expiry at most a year away. The exception starts pending; once a second person approves it with approveException, and until it expires, the finding is marked excepted and no longer counts toward its control's status. There are no permanent exceptions.

const exception = await iam.api.compliance.createException(admin, {
  tenantId,
  controlKey: 'inactive-30',
  subject: `identity:${aliceId}`,
  reason: 'On parental leave until December',
  expiresAt: Date.parse('2026-12-31T00:00:00Z'),
});
// Someone else with iam:compliance:manage approves it.
await iam.api.compliance.approveException(otherAdmin, { tenantId, exceptionId: exception.id });

Routes: POST /api/iam/compliance/createException, POST /api/iam/compliance/approveException

Nobody may propose or approve an exception for a finding about themselves, and audit-integrity findings cannot be excepted at all. revokeException ends an exception or withdraws a pending one; revoked exceptions stay as history, in listExceptions and in evidence packs, until the retention sweep removes them 400 days after they expire.

Requirement status

status shows each requirement of a framework with its controls: no-control when nothing evidences it, and otherwise the worst of its controls, where a disabled control counts as disabled and one without a fresh result as not-evaluated, so neither lets the requirement pass. total, covered and passing count the requirements, those with a control, and those that pass.

Evidence for auditors

exportEvidence returns a JSON pack with the controls (of one framework, or all; disabled ones marked), their parameters, mappings, latest results and findings, every exception with its approval and revocation history, the latest 30 runs with their digests, and the audit chain head. The pack carries a SHA-256 digest of its content and an Ed25519 signature by a key derived from the deployment secret; the digest is also recorded in the audit chain when the pack is exported.

import { verifyEvidencePack } from '@better-iam/server';

const pack = await iam.api.compliance.exportEvidence(admin, { tenantId, framework: 'soc2' });
const jwks = await iam.api.compliance.evidenceKeys(admin, { tenantId });
// The auditor, offline, with no access to your deployment:
const { valid, reason } = verifyEvidencePack(pack, jwks);

Routes: POST /api/iam/compliance/exportEvidence, POST /api/iam/compliance/evidenceKeys

evidenceKeys publishes the public keys as a JWKS, the current secret's first and then those of previousSecrets, so packs keep verifying across secret rotations. verifyEvidence makes the same check on the server, and also accepts version 1 packs, which were signed with an HMAC before evidence keys existed. Packs name people by ID, and by email address for callers who may read the directory, so handle them as personal data.

Permissions

iam:compliance:read covers the readers, status, evidence and its keys; iam:compliance:evaluate running evaluations; and iam:compliance:manage adopting frameworks, controls, and proposing, approving and revoking exceptions. Evaluations read the whole directory whoever starts them, so readers see findings about people they might not otherwise read, by ID unless they may also read the directory. The console page is Governance › Compliance.

Options

The compliance center has no deployment option: the compliance group is always available and its collections are part of the ordinary migration (npx better-iam migrate or iam.initialize()). Evidence packs are signed with a key derived from the deployment secret. A control takes these fields in createControl and updateControl:

adoptFramework takes framework: soc2, iso27001, nist-800-53 or gdpr. A tenant holds at most 200 controls.

Schema

Results and runs carry an expiresAt 400 days out, after which iam.sweepExpired() removes them.

Routes

Every method is a POST under the handler's base path (default /api/iam) and needs a credential. The browser client calls the same routes as client.compliance.<method>.

iam.compliance.evaluateAll() is the scheduled job, and verifyEvidencePack (from @better-iam/server) the offline verifier; neither is a route.

Errors