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.
On this page
Gate semantics
- Park: a
require-approvaldecision 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
approveorrejectwith 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
denyfrom 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).