Four-eyes governance gate

What it does

/api/v1/approvals/[id] (POST approve | reject) refuses to record a decision unless every governance invariant is satisfied. Two layers:

Single-stage gate (W6.3) — refuses any decision where approverId === requesterId when tenantSettings.aiAnalyzerSettings.governance.fourEyesEnabled is on.
Multi-stage chain (W14) — every approval is backed by an ordered list of approval-request stage rows. Each stage has a requiredRole and an ordinal. Decisions walk the chain in order, failing CLOSED on every guard.

Configuration

The W6.3 self-approval gate is opt-in:

{
  "aiAnalyzerSettings": {
    "governance": {
      "fourEyesEnabled": true
    }
  }
}

The W14 multi-stage chain is always on — every approval has at least one stage row (the migration backfilled one default admin stage per existing approval). To opt into a multi-stage chain, pass stages on creation.

Creating a multi-stage approval

curl -X POST https://playground.kaireonai.com/api/v1/approvals \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "entityType": "offer",
    "entityId": "off_1",
    "entityName": "Q4 Promo",
    "action": "update",
    "payload": { "config": { "discount": 0.30 } },
    "stages": [
      { "stageName": "review",   "requiredRole": "editor" },
      { "stageName": "approve",  "requiredRole": "admin"  }
    ]
  }'

stages is optional. Omitting it produces a single default admin stage — identical to the W6.3 single-stage path. requiredRole must be one of viewer, editor, admin.

Per-stage decision walk

POST /api/v1/approvals/{id} finds the first pending stage, records the decision against it, and updates the parent only when:

The decision is reject → parent flips to rejected immediately.
The decision is approve AND the stage is the last ordinal → parent flips to approved and the stored payload is applied.
Otherwise → parent stays pending; the next stage’s reviewer can decide.

Security defaults — fail CLOSED

Every decision-time guard inverts to “reject” on uncertainty:

Condition	Behavior
`tenantSettings` lookup fails	Fail-CLOSED. The four-eyes gate treats an unreachable settings lookup as `enforce: true, reason: "settings_unavailable"`. A lookup error during a self-approval attempt cannot bypass the gate.
`user.userId` missing	403 — every stage row must be attributed to a real identity. No literal “system” fallback.
`user.role` not `editor` or `admin`	403 — viewers cannot decide on stages even if `requireRole` is widened to allow editors through the route boundary.
`approval.requesterId` missing	403 (gate path).
`approverId === requesterId`	403 (W6.3 gate when on; W14 stage walk always).
Same `approverId` decided on a prior stage	403 — cross-stage four-eyes. One identity cannot single-handedly walk a multi-stage chain.
Stage rows lookup fails	403.
Heal-insert (zero stage rows) fails	403.
Approver’s role does not match the current stage `requiredRole`	403.
A prior stage is still `pending` or was `rejected`	409 (`stage_order`).
All stages already resolved	409 (`no_pending_stages`).
`payload` apply throws (Prisma error, unknown `entityType`, malformed JSON)	Whole transaction rolls back: the stage row’s status flip and the parent’s status flip are reverted together. Returns 409 with `Failed to record decision; transaction rolled back`.

The “approval flipped to approved but the entity didn’t change” silent failure shape is not reachable under W14: the stage update, parent flip, and payload apply commit atomically or fail atomically.

Reading an approval with its stages

GET /api/v1/approvals/{id} now returns the parent plus an ordered stages array so the UI can render the chain progress in one round-trip:

{
  "id": "appr_1",
  "status": "pending",
  "stages": [
    { "id": "s0", "ordinal": 0, "stageName": "review",  "requiredRole": "editor", "status": "approved", "approverId": "u_2" },
    { "id": "s1", "ordinal": 1, "stageName": "approve", "requiredRole": "admin",  "status": "pending",  "approverId": null }
  ]
}

Audit trail

Every stage decision writes one audit-log row with:

action: "approve" | "reject"
entityType: "approval_request"
changes: { stageOrdinal, stageName, stageStatus, parentStatus, decisionScope }
decisionScope: "stage" when the parent stays pending, "request" when this decision flipped the parent to its final state.

Use decisionScope to filter audits when computing “how many requests were resolved this week” — counting on action === "approve" alone now overcounts in proportion to the stage depth.

Migration

prisma/manual-sql/09_parity_w11_to_w19.sql creates the approval_request_stages table and backfills exactly one default stage row per existing pending approval (ordinal=0, requiredRole='admin', status mirrored from the parent). Existing admin-only flows keep their behavior; nothing migrates “into” multi-stage by default.

Known limit (V1)

requiredRole is a single value per stage — exact role match is enforced. There is no role hierarchy (“admin satisfies editor-stage”). A multi-role-per-stage policy is tracked separately as a future extension of the in-memory recordDecision policy in lib/governance/approval-workflow.ts.

Decision-flow publish gate

A third surface applies four-eyes specifically to publishing decision flows. When the tenant setting requirePublishApproval is true (tenant settings), POST /api/v1/decision-flows/publish requires a fresh approved ApprovalRequest with entityType=decisionFlow, action=publish, and entityId equal to the flow id.

One approval = one publish. The successful publish stamps the approval’s id onto the new publishedVersions[] entry, so the same approval cannot authorize a second publish (reason: "consumed").
Two distinct identities guaranteed. The approval flows through the same stage-walk above, which already rejects self-approval and duplicate approvers, so an approved publish request implies a requester and an approver who are not the same person.
Fails CLOSED. If the tenantSettings lookup errors, publish is blocked unless a valid approval exists — matching the self-approval gate’s posture.
A blocked publish returns 422 (title: "Publish approval required", reason: "no_approval" | "consumed") and writes a publish_blocked audit entry (reason: publish_approval_missing | publish_approval_consumed).

Default requirePublishApproval: false leaves one-click publish unchanged. See Decision Flows — publish. Migration: prisma/manual-sql/26_tenant_require_publish_approval.sql. See also: Compliance · Cron jobs · Approvals API

Get Started

Tutorials

Use Cases

Decisioning

Studio

Data Pipelines

AI & ML

Operations & Reporting

Governance & Security

Integrations

Reference

Four-eyes governance gate

What it does

Configuration

Creating a multi-stage approval

Per-stage decision walk

Security defaults — fail CLOSED

Reading an approval with its stages

Audit trail

Migration

Known limit (V1)

Decision-flow publish gate

​What it does

​Configuration

​Creating a multi-stage approval

​Per-stage decision walk

​Security defaults — fail CLOSED

​Reading an approval with its stages

​Audit trail

​Migration

​Known limit (V1)

​Decision-flow publish gate

What it does

Configuration

Creating a multi-stage approval

Per-stage decision walk

Security defaults — fail CLOSED

Reading an approval with its stages

Audit trail

Migration

Known limit (V1)

Decision-flow publish gate