0033. Sending workflows go live only after a human approves them out of band
- Status: Accepted (decided by the maintainer)
- Date: 2026-11-11
- Supersedes: the activation confirmation token of ADR 0016
- Amends: ADR 0005 (resolves its open confirmation mechanism), ADR 0017 (separates publishing from activation), ADR 0026 (defines the
sendscope), ADR 0028 (adds/approvals/*to the API routes)
Context
Section titled “Context”ADR 0005 requires user confirmation for sending actions, enforced on the server, because MCP clients may ignore tool annotations. ADR 0016 chose a short-lived token that workflows.preview_triggers returns and workflows.activate requires. Until a confirmation exists, apps/workers refuses every email provider but the fake one (ADR 0031).
The ADR 0016 token goes back to the caller that asked for it. An AI assistant that holds the API key can fetch the preview and activate in the next call, so the token proves that a preview was fetched, not that a person saw it. The product exists for exactly this caller: the user’s own AI creates and operates workflows over MCP.
Facts about the code at b2a1af2:
- Only secret project keys (
cl_sk_) exist, so the credential an AI holds can do everything the API can do (ADR 0030). Restricted keys, MCP OAuth, Better Auth, the dashboard, and the audit log are not built. workflows.upserton an active workflow saves a new version, and new runs start on it at once. An approved workflow could be changed into one that sends anything, with no new confirmation.- A run is stopped when its workflow is not
activeor the workflow’s activation epoch differs from the run’s (isRunStoppedincore/src/engine/run.ts, ADR 0017). - A send step holds
from,subject, andbodyinline. Templates and sending domains do not exist yet. There is noworkflows.stopaction yet. - MCP elicitation lets a server ask the client to collect input from the user, but the client renders and answers it, so the server cannot tell a person’s answer from the client’s.
Alternatives considered
Section titled “Alternatives considered”| Mechanism | Why not |
|---|---|
| The ADR 0016 preview token, returned to the caller | The caller can complete it alone; it proves nothing about a person |
| MCP elicitation | Answered by the client; not verifiable on the server |
A separate send scope or approval key that the AI is not given |
Only cl_sk_ keys exist, and users will paste the one key they have into their assistant; once OAuth exists, a grant acts as the user |
| A dashboard approval | The dashboard does not exist yet, and a dashboard session is the same user as an MCP grant (see Open) |
| A one-time link mailed to approvers (chosen) | Needs a channel the API credential does not give: the approver’s mailbox |
Decision
Section titled “Decision”- A sending version has at least one
send_emailstep. Outbound webhook steps do not make a version sending; they go to the user’s own endpoints. - A workflow has a latest version (the last one saved,
currentVersiontoday) and a live version (the one new runs start on; null until the workflow is first activated). “Active version” is not used. - Activation moves a workflow from
draft(or, once stop exists,stopped) toactive, makes the latest version live, and increments the activation epoch (ADR 0017). - Publishing makes the latest version of an
activeworkflow live. It does not change the status or the activation epoch, so runs already started stay on the version they pinned and keep running and sending (ADR 0007). This is the “publishing a new version switches the active version atomically” of ADR 0017. workflows.activatedoes whichever applies: activation for a workflow that is not active, publishing for one that is.- A send approval is a person’s decision to let one sending version go live, by activation or publishing. It is a project resource.
- An approver is a person who may approve for the workspace (see “Approvers during the validation phase”).
- The definition hash is SHA-256 over the RFC 8785 canonical JSON of a version’s definition, computed once when the version is saved and stored on the version. It is the only hash of a definition; “version hash” is not used.
Saving, activating, and publishing
Section titled “Saving, activating, and publishing”- Saving a version never changes the live version. Event and time triggers start runs on the live version only.
- If the latest version is not sending,
workflows.activateactivates or publishes it at once, as today. - If the latest version is sending,
workflows.activatechanges nothing on the workflow. It creates a pending send approval, or returns the pending one for the same version, and mails links to it. The workflow goes live when the approval is approved. - The request is refused with
sender_not_verifiedif afromaddress of the version is not on a verified sending domain of the workspace (ADR 0034), and withno_approversif the workspace has no approver and the delivery isemail.
What an approval binds to
Section titled “What an approval binds to”- The project, the workflow, the version number, the version’s definition hash, and the workflow’s re-entry policy at the time of the request. Together these decide who gets mail, what, when, and how often.
- The re-entry policy binding is forward-looking: today every workflow has the default policy. Once the policy can change (only while stopped, ADR 0017), changing it on a sending workflow means the next activation needs an approval that shows the new policy.
- The whole definition is covered, not only the send steps, because the trigger, delays, and conditions decide who gets the mail and when.
- When templates become their own resources, the binding also covers the definition hashes of the pinned template versions the definition references.
- The decision checks every bound value again; a mismatch refuses it.
- An approval has one approval link per approver, so the decision names who made it. A link row holds the approver’s control-plane ID (no address), the SHA-256 hash of the link’s secret, and when it was last mailed.
- The link is
https://<app domain>/approvals/<projectId>/<linkId>#<secret>. The secret has 256 bits of randomness. It is in the fragment, which browsers never send in a request, so it does not reach request logs of the platform; the page reads it and sends it in aPOSTbody. - Every mailing mints a new secret for each link and replaces the stored hash, so a resend works and an older mail’s link stops working. Core does not read randomness (ADR 0018), so secrets come from a new method on the existing
IdGeneratorport,secret(), which returns 256 random bits (base64url) and is implemented with WebCrypto inadapters/webcrypto; the action handler receives the generator in its dependencies. Theworkflows.activatehandler, in order:- reads the workspace’s approvers from
ControlStore(withresponsedelivery, the single pseudo-approvercaller); - mints one secret per approver with
IdGenerator.secret()and hashes each; - runs the project-store command that creates or reuses the pending approval and stores the hashes, and commits;
- hands the links to the
ApprovalDeliveryport, outside any transaction; - after a successful delivery, runs a second command that records each link’s mailed time. A delivery failure leaves an unmailed link that nobody can use, and
workflows.activatereturnsapproval_delivery_failed; calling it again mints and mails new links.
- reads the workspace’s approvers from
- Repeating
workflows.activatefor the same pending version mails new links again. There is no hourly throttle. Approval mail is capped per project per day by configuration, counted in the project store; over the cap, the request fails withrate_limitedand creates nothing. A workspace-wide cap would need a counter outside any one project store and is deferred until approvers are workspace users. - Secrets are never written to logs, queues, step logs, or any API or MCP response, except the
responsedelivery below.
Deciding
Section titled “Deciding”POST /approvals/<projectId>/<linkId>/decisionwith{ "secret", "decision": "approve" | "decline" }decides. It is anendpointaction (ADR 0019), authenticated by the link like unsubscribe, so a decision is deliberately not an MCP tool, and noapiaction can approve or decline.- The endpoint resolves
projectIdthroughControlStorefirst; an unknown project is 404, and no Durable Object is addressed. It mints aProjectScopefor that project and calls the decide command, which compares the secret’s hash with the link row (in constant time) before it reads anything else. A mismatch returns 404 and writes nothing. This adds a verified approval link to the sources thatcore/authmints a scope from (Tenant model). - The endpoint also checks, through
ControlStore, that the link’s approver is still an approver of the workspace; a removed approver’s link is refused. Thecallerpseudo-approver ofresponsedelivery has no control-plane row and skips this check, so the first slice needs no control-plane approvers. - Approve, in one project-store transaction: the approval is pending and unexpired; the workflow’s latest version, its definition hash, and its re-entry policy still match the approval; then the workflow is activated or published as described above, and the approval becomes
approvedwith the deciding link and time. Decline makes itdeclinedwith the same record. - Until the audit log exists, the decider and time on the approval row are the record. The audit log entry (written through the outbox, idempotent on the approval ID) is its own later change.
sendApprovals.get(anapiaction, scoperead) returns an approval’s status, bound values, expiry, and decider ID, without any secret.
Approval and workflow states
Section titled “Approval and workflow states”Approval status is stored as pending, approved, declined, or cancelled. expired (24 hours after the request) and superseded (the workflow’s latest version is no longer the approval’s version) are derived when read, never stored.
| Workflow | Approval | Event | Result |
|---|---|---|---|
draft |
none | activate, latest not sending | activated |
draft |
none | activate, latest sending | pending approval created, links mailed |
draft |
pending | approve | activated (epoch + 1); approval approved |
active |
none | activate, live = latest | no-op; returns the workflow |
active |
none | activate, latest not sending | published, epoch unchanged |
active |
none | activate, latest sending | pending approval created, links mailed; v(live) keeps running |
active |
pending | approve | published, epoch unchanged; runs on the old version keep running and sending |
| any | pending | activate again, same version | same approval, new links mailed (within the daily caps) |
| any | pending | save a new version | approval reads as superseded; its links refuse to decide |
| any | pending for v2, v3 saved | activate | a new pending approval for v3; v2’s reads as superseded. At most one approval per workflow is pending and not superseded |
| any | pending | decline | approval declined; workflow unchanged |
| any | pending | 24 hours pass | approval reads as expired; its links refuse to decide |
| any | pending | the deciding approver was removed | that link refuses; other approvers’ links still work |
| any | none | activate, latest sending, workspace has no approver (email delivery) |
refused with no_approvers |
active |
pending | stop (when built) | approval cancelled |
| any | pending | workflow deleted (when built) | approval cancelled |
stopped (when built) |
none | activate, latest sending | new approval needed, even for the version that was live before |
- One approval allows one activation or publication. Activating again after a stop, even the same version, needs a new approval.
- A send never checks the approval. Runs are pinned to the version that was live when they started, and stop and activation epochs govern them.
Delivery of the links
Section titled “Delivery of the links”ApprovalDeliveryis a port:deliver(approval summary, links). Its adapters are selected bySEND_APPROVAL_DELIVERY:email(the default): mails each approver their link throughSystemMailer(ADR 0029). The mail names the project, the workflow and version, the trigger, the re-entry policy, and each send step’s from address, subject, and body. It holds no customer data.response: returns one link (for the pseudo-approvercaller) in the optionalapprovalLinkfield of theworkflows.activateoutput. It is for self-hosted installations and local development only; the cloud mode refuses to start with it. It is also the path the tests use.
approvalLinkis declared in the output schema ofworkflows.activate, so OpenAPI and the MCP tool describe it identically; it is absent unless the delivery isresponse.
The approval page
Section titled “The approval page”GET /approvals/<projectId>/<linkId>returns a static page with no approval content and decides nothing (link scanners followGETlinks, as for unsubscribe in ADR 0024). Its script reads the secret from the fragment and posts it toPOST /approvals/<projectId>/<linkId>/view, which returns the approval’s content as JSON after the same checks as a decision.- The page renders that content only as text (
textContent), never as HTML, because the subject and body were written by an AI and are shown on the app domain. Responses carryContent-Security-Policy: default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; form-action 'self'; base-uri 'none'; frame-ancestors 'none',Referrer-Policy: no-referrer, andX-Content-Type-Options: nosniff. No session cookie is read or set.
Other sending actions
Section titled “Other sending actions”- The
sendscope of ADR 0026 covers actions that send at once (test sends, a future direct send). Activation keeps theadminscope. - Test sends (
runs.test, ADR 0015) need no approval but go only to verified test recipients. How a recipient is verified is out of scope here and decided with test runs. - An action that sends to a recipient chosen at call time, outside a workflow (for example a transactional send API, still open), needs an approved template, with this mechanism bound to the template version. It is not part of this decision’s implementation.
Choices decided by the maintainer
Section titled “Choices decided by the maintainer”Three points were put to the maintainer, who chose as follows on 2026-11-11.
- Escape hatch for installations without system mail.
SEND_APPROVAL_DELIVERY=responseexists for self-hosted installations and local development only, and the cloud mode refuses to start with it. Rejected: no escape hatch, which would force every self-host and development setup to configureSystemMailerfirst. Also rejected: a CLI that approves with an admin secret, which is a second approval path to build and secure. - Strictness. Every change to a live sending workflow, and every reactivation, even of the same version, needs a new approval. Rejected: reusing an approval when the same version is reactivated. Also rejected: hashing only the send steps, which would let a trigger or condition change reach new recipients without a person seeing it.
- Approvers during the validation phase. On the managed service, approvers are operator-provisioned addresses in the control plane, and approval mail goes through Cloudflare Email Service (ADR 0029) even though it is in beta. They switch to workspace users with the
owneroradminrole when Better Auth exists (ADR 0025). Self-hosted installations useADMIN_EMAILS. Rejected: waiting for Better Auth before real mail can be sent.
Approval is always on
Section titled “Approval is always on”The approval is enforced in core for every provider, including the fake one, so tests and development exercise the same path as production. Once it is built, the composition-time check assertEmailProviderAllowed is removed, and the provider is chosen by configuration (ADR 0034).
Amendment (2026-11-18, ADR 0044, decided by the maintainer): approval is no longer always on. Each workspace has the setting sendApprovalRequired, off by default on the managed service and on self-hosted installations. Where it is on, this ADR applies unchanged, a rollback to an earlier live version included; where it is off, workflows.activate (and a rollback) takes effect at once, after the sender check, and mails nothing. Pause and rollback come with it, and there is no send cap and no notification when approval is turned off. Proposed in ADR 0044, not decided: only an owner’s session changes the setting (ADR 0041, Proposed; until it is built, the operator), the design of pause and rollback, and a record of who made each version live. Where approval is on, it is still enforced in core for every provider.
Amendment (2026-11-19, ADR 0041): when users exist, a workspace’s approvers are its admin users, read from memberships; there is no owner role. The approvers table and its operator endpoint are retired in that change. Self-hosted ADMIN_EMAILS users are admins of every workspace through membership rows. Where this ADR says owner or admin, read admin.
Consequences
Section titled “Consequences”- An AI assistant can draft, validate, and request activation of a sending workflow over MCP, but mail starts only after a person opens a link it does not receive. Nothing on the server can tell a person from an agent that also controls the approver’s mailbox and a browser; the guarantee is that approval needs a channel other than the API credential.
- The approval does not bind the recipients. A caller with
writescope can still create customers with any address and fire the trigger event of a live workflow; the approved content and trigger, plan limits, sender protection (ADR 0024), and publishable key restrictions bound that. When templates gain variables, values from customer attributes are escaped and length-limited, so attributes cannot replace approved content. - Every change to a live sending workflow costs one approval mail and one click. That friction is intended.
workflows.preview_triggers(ADR 0016) remains a read-only preview and returns no token.- New state: the live version on each workflow, the definition hash on each version,
send_approvalsandsend_approval_linksin the project store, and approver addresses in the control plane until users exist. - Open:
- The approval channel of the dashboard. A dashboard session is the user, and so is an MCP OAuth grant, so an
apiapprove action alone would let the assistant approve. It needs proof of a fresh human presence (for example a new email code or a passkey) and is decided with the dashboard. - The value of the daily approval-mail cap, a workspace-wide cap once approvers are users, and the approval lifetime if 24 hours proves too short in use.
- The approval channel of the dashboard. A dashboard session is the user, and so is an MCP OAuth grant, so an
Implementation notes
Section titled “Implementation notes”Recorded when plan row A2 was built (2026-11-13):
- A link secret is
cl_apsec_followed byIdGenerator.secret(), so log redaction masks it (ADR 0026, ADR 0032). - The cloud mode’s refusal of
responsedelivery was built withresponsedelivery in A2, not in A4. responsedelivery lives in core (responseApprovalDelivery). It uses no platform API and no other port, unlike the fake email provider, which is an adapter (adapters/email-fake).- Two error codes were added:
conflict(409), for a decision on an approval that is not pending, has expired, is superseded, or no longer matches; andrate_limited(429), for the daily cap.
Recorded when plan row A3 was built (2026-11-15):
- “The same checks as a decision” for the view means the checks both decisions make: the secret, then every bound value. The sender check of ADR 0034 applies only to approving, as it does for the decision, so an approval whose
fromdomain was removed can still be viewed and declined. - A refused view or decision gives the refusal in
error.reasonof its 409 body, which the page shows.
Recorded when plan row A4b was built (2026-11-15):
- The recipients of approval links are injected next to the delivery (
SendApprovalDeps.recipients), chosen together bySEND_APPROVAL_DELIVERYin the composition root: thecallerpseudo-approver withresponse; withemail, the workspace’s approvers read throughControlStore.approversOf, or the approvers ofADMIN_EMAILSon a self-hosted installation.ApprovalDeliveryonly delivers, and reports the links that reached their recipient. The operator writes a workspace’s approvers withPUT /operator/workspaces/:workspaceId/approvers, an operator endpoint in the manner of ADR 0035; it refuses withconflictwhileADMIN_EMAILSnames the approvers. - A self-hosted installation’s
ADMIN_EMAILS, when set, approves for every workspace in place of the control plane’s lists. Its approver IDs are pseudonymous:deriveId("adm", "approver", address), an unkeyed SHA-256, so whoever can readdecidedBycan test whether a guessed address is an approver. That is accepted for self-hosting, where the API key holder and the admins are one installation; a keyed hash would need an installation secret. The cloud mode refusesADMIN_EMAILS, andresponsedelivery with it is a configuration error. - Who may view or decide is who would get a link now: with
responseonly thecallerlink, otherwise only the approvers, so a link handed to the caller stops working after a switch toemail, and an approver’s link after a switch back. A link of a removed approver is refused withconflictand the reasonapprover_removed, for the view as for the decision. The view and decision endpoints read the recipients only after the secret matched, so a request without a valid secret costs no control-plane read. - A re-request deletes a pending approval’s links of approvers who are no longer listed, so such a link cannot decide even if its approver returns.
- Two error codes were added:
no_approvers(422) andapproval_delivery_failed(502), which carries how many of the links the call sent were delivered (delivery: { delivered, total }), counts only. - Amends “calling it again mints and mails new links” above (2026-11-15): after a request that did not reach every approver, calling again mints and mails new links only for the approvers whose link was never delivered; the others keep their working links. Otherwise one permanently refused address would re-mail every approver on each retry, invalidate the links they already have, and use up the project’s daily cap. Once every link was delivered, a request again re-mints and mails every link.
- Approval mail is sent to at most 5 approvers at once. It puts the link and the fixed instructions first, and the workflow’s content, written by its author, last, between framing lines with every line quoted, so instructions or links forged in it stay visibly quoted.
Amendment (2026-11-19, pending ADR 0048 and ADR 0050, Proposed): a send approval may be of kind conclusion: an experiment conclusion that ends a holdout, where approval is required. It binds the workflow, the activation epoch, the live version and its definition hash, the experiment ID, its arms hash, and the winner, and follows ADR 0044’s rule of at most one pending approval per workflow. Every action that creates an approval is first confirmed on the server (ADR 0050); approval remains the only proof that a person decided.