Controls

controls keeps what an audit asks for in one place. You list the controls of a framework such as SOC 2 or ISO 27001, attach evidence to each control, plan the evidence that has to be collected again on a schedule, and publish policies that every member acknowledges. Each control's status follows from its evidence and tasks, and posture rolls it up per framework.

better-supabase add controls

import { createControls } from "better-supabase/blocks/controls";

The module requires tenant, access and versions. With attachments a piece of evidence can be a file, with notifications a missed task notifies its assignee, with outbox it records the events, and with audit every change is audited.

TablesCopy Anchor Link

Members with controls.read read every table.

Frameworks and controlsCopy Anchor Link

const controls = createControls({ transport });

const soc2 = await controls
  .saveFramework(organizationId, {
    key: "soc2",
    name: "SOC 2",
    version: "2017",
  })
  .orThrow();

const access = await controls
  .saveControl({
    frameworkId: soc2.id,
    code: "CC6.1",
    title: "Logical access",
    ownerId,
  })
  .orThrow();

Saving a framework with a key that exists, or a control with a code that exists in the framework, updates it. A control with applicable: false is out of scope. Frameworks, controls, evidence tasks and policies need controls.manage.

A control's status is computed, never stored:

Evidence and tasksCopy Anchor Link

await controls
  .addEvidence(access.id, {
    attachmentId,
    note: "Quarterly access review",
    validUntil: Temporal.PlainDate.from("2026-12-31"),
  })
  .orThrow();

const task = await controls
  .saveEvidenceTask(access.id, {
    title: "Review access",
    intervalDays: 90,
    assigneeId,
  })
  .orThrow();

Evidence is an attachment in the organization, a note, or both; adding it needs controls.collect. A task is due on dueOn (default today) and is overdue once that day has passed. Evidence added with evidenceTaskId answers the task: its due date moves intervalDays past today, and the evidence is valid until then unless validUntil says otherwise. A task's assignee may collect for it without controls.collect.

Run notifyOverdue daily with the service role, for example from a job. It records evidence_task.missed once for each lapse and notifies the assignee, or the control's owner when the task has none.

PostureCopy Anchor Link

const [framework] = await controls.posture(organizationId).orThrow();
// { total, passing, failing, notStarted, notApplicable, overdueTasks }

posture returns one rollup per framework, or for one framework when you pass its id.

PoliciesCopy Anchor Link

const policy = await controls
  .savePolicy(organizationId, {
    key: "acceptable-use",
    title: "Acceptable use",
  })
  .orThrow();

await controls
  .publishPolicy(policy.id, { body: markdown }, "2026 edition")
  .orThrow();
await controls.acknowledgePolicy(policy.id).orThrow();

publishPolicy stores the content as a frozen version and makes it current. Members acknowledge the current version with controls.acknowledge; publishing again asks everyone to acknowledge the new version. policies(organizationId, { pendingOnly: true }) lists the policies waiting for the caller, and acknowledgements(policyId) lists every member with the time they acknowledged the current version. An archived policy can't be published or acknowledged.

ErrorsCopy Anchor Link

EventsCopy Anchor Link

control.saved, control.evidence_added, evidence_task.missed, policy.published and policy.acknowledged. The events page lists their payloads.