Home / Reference implementations / Approval inbox

Approval inbox

Draft Illustrative reference — annotated, runnable code against the Draft contracts. Not a production implementation (in-memory store, no real authentication).

When policy returns require-approval (see the policy model), the action parks: it cannot execute until a human records a decision. This reference implements the gate — parking, deciding, expiry — and shows how the decision becomes evidence.

Gate semantics

  • Park: a require-approval decision creates an approval request with the allowed approver roles and an expiry. The action is frozen — it cannot be executed, modified, or re-proposed under the same id.
  • Decide: an approver whose role is in the allowed set records approve or reject with their identity and a timestamp. The decision is final; it cannot be changed, only superseded by a new action.
  • Expire: if no decision is recorded before expiry, the request lapses to expired — equivalent to a rejection, and recorded as such.
  • Evidence: the approval record (approver, role, decision, timestamps) is embedded in the action's evidence receipt. A deny from policy can never be routed to approval.

Reference code

Illustrative referenceapproval-inbox.js — save as one file and run with node approval-inbox.js.
// Illustrative reference: human approval gate (Node.js, stdlib only).
// Handles the require-approval path of the execution chain.
"use strict";

// In-memory stores. A production inbox persists these per tenant.
const requests = new Map(); // approvalId -> approval request

function nowIso() {
  return new Date().toISOString();
}

function parkForApproval({ actionId, roles, expiresAfterMinutes, policyVersion, matchedRule }) {
  const approvalId = "apr_" + Math.random().toString(36).slice(2, 10);
  const request = {
    approval_id: approvalId,
    action_id: actionId,
    status: "pending", // pending | approved | rejected | expired
    allowed_roles: roles,
    policy_version: policyVersion,
    matched_rule: matchedRule,
    created_at: nowIso(),
    expires_at: new Date(Date.now() + expiresAfterMinutes * 60 * 1000).toISOString(),
    decision: null,
  };
  requests.set(approvalId, request);
  return request;
}

function isExpired(request) {
  return new Date(request.expires_at).getTime() <= Date.now();
}

function sweepExpiries() {
  for (const request of requests.values()) {
    if (request.status === "pending" && isExpired(request)) {
      request.status = "expired";
      request.decision = {
        decided_by: null,
        role: null,
        decision: "expired",
        decided_at: nowIso(),
        note: "No decision before expiry; treated as rejected.",
      };
    }
  }
}

function decide({ approvalId, approverId, approverRole, decision, note }) {
  sweepExpiries();
  const request = requests.get(approvalId);
  if (!request) throw new Error("unknown approval: " + approvalId);
  if (request.status !== "pending") throw new Error("approval is already " + request.status);
  if (!request.allowed_roles.includes(approverRole)) {
    throw new Error("role '" + approverRole + "' may not decide this approval");
  }
  if (decision !== "approve" && decision !== "reject") throw new Error("decision must be approve or reject");

  request.status = decision === "approve" ? "approved" : "rejected";
  request.decision = {
    decided_by: approverId,
    role: approverRole,
    decision,
    decided_at: nowIso(),
    note: note || null,
  };
  return request;
}

// The approval record as it appears inside the action's evidence receipt.
function approvalEvidence(request) {
  if (!request.decision) return null;
  return {
    approval_id: request.approval_id,
    decided_by: request.decision.decided_by,
    role: request.decision.role,
    decision: request.decision.decision,
    decided_at: request.decision.decided_at,
    expires_at: request.expires_at,
  };
}

function pendingApprovals() {
  sweepExpiries();
  return [...requests.values()].filter((r) => r.status === "pending");
}

// --- Demo ---
function demo() {
  const req = parkForApproval({
    actionId: "act_demo001",
    roles: ["billing-approver"],
    expiresAfterMinutes: 240,
    policyVersion: "0.1.0",
    matchedRule: "approve-refunds",
  });
  console.log("parked:", req.approval_id, "| status:", req.status);

  try {
    decide({ approvalId: req.approval_id, approverId: "amy", approverRole: "support", decision: "approve" });
  } catch (err) {
    console.log("expected rejection:", err.message);
  }

  const decided = decide({
    approvalId: req.approval_id,
    approverId: "jo",
    approverRole: "billing-approver",
    decision: "approve",
    note: "Customer confirmed the duplicate charge.",
  });
  console.log("decided:", decided.status, "by", decided.decision.decided_by);
  console.log("evidence fragment:", JSON.stringify(approvalEvidence(decided)));
  console.log("pending:", pendingApprovals().length);
}

if (require.main === module) demo();

module.exports = { parkForApproval, decide, pendingApprovals, approvalEvidence };

Demo run

Illustrative referenceExpected output of node approval-inbox.js.
parked: apr_k3j8s2d1 | status: pending
expected rejection: role 'support' may not decide this approval
decided: approved by jo
evidence fragment: {"approval_id":"apr_k3j8s2d1","decided_by":"jo","role":"billing-approver","decision":"approve","decided_at":"...","expires_at":"..."}
pending: 0

Related: policy model (the require-approval effect), evidence model (where the approval record lands), governed webhook (which parks into this gate).