Skip to content

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 send scope), ADR 0028 (adds /approvals/* to the API routes)

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.upsert on 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 active or the workflow’s activation epoch differs from the run’s (isRunStopped in core/src/engine/run.ts, ADR 0017).
  • A send step holds from, subject, and body inline. Templates and sending domains do not exist yet. There is no workflows.stop action 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.
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
  • A sending version has at least one send_email step. 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, currentVersion today) 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) to active, makes the latest version live, and increments the activation epoch (ADR 0017).
  • Publishing makes the latest version of an active workflow 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.activate does 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 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.activate activates or publishes it at once, as today.
  • If the latest version is sending, workflows.activate changes 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_verified if a from address of the version is not on a verified sending domain of the workspace (ADR 0034), and with no_approvers if the workspace has no approver and the delivery is email.
  • 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 a POST body.
  • 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 IdGenerator port, secret(), which returns 256 random bits (base64url) and is implemented with WebCrypto in adapters/webcrypto; the action handler receives the generator in its dependencies. The workflows.activate handler, in order:
    1. reads the workspace’s approvers from ControlStore (with response delivery, the single pseudo-approver caller);
    2. mints one secret per approver with IdGenerator.secret() and hashes each;
    3. runs the project-store command that creates or reuses the pending approval and stores the hashes, and commits;
    4. hands the links to the ApprovalDelivery port, outside any transaction;
    5. 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.activate returns approval_delivery_failed; calling it again mints and mails new links.
  • Repeating workflows.activate for 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 with rate_limited and 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 response delivery below.
  • POST /approvals/<projectId>/<linkId>/decision with { "secret", "decision": "approve" | "decline" } decides. It is an endpoint action (ADR 0019), authenticated by the link like unsubscribe, so a decision is deliberately not an MCP tool, and no api action can approve or decline.
  • The endpoint resolves projectId through ControlStore first; an unknown project is 404, and no Durable Object is addressed. It mints a ProjectScope for 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 that core/auth mints 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. The caller pseudo-approver of response delivery 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 approved with the deciding link and time. Decline makes it declined with 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 (an api action, scope read) returns an approval’s status, bound values, expiry, and decider ID, without any secret.

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.
  • ApprovalDelivery is a port: deliver(approval summary, links). Its adapters are selected by SEND_APPROVAL_DELIVERY:
    • email (the default): mails each approver their link through SystemMailer (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-approver caller) in the optional approvalLink field of the workflows.activate output. 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.
  • approvalLink is declared in the output schema of workflows.activate, so OpenAPI and the MCP tool describe it identically; it is absent unless the delivery is response.
  • GET /approvals/<projectId>/<linkId> returns a static page with no approval content and decides nothing (link scanners follow GET links, as for unsubscribe in ADR 0024). Its script reads the secret from the fragment and posts it to POST /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 carry Content-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, and X-Content-Type-Options: nosniff. No session cookie is read or set.
  • The send scope of ADR 0026 covers actions that send at once (test sends, a future direct send). Activation keeps the admin scope.
  • 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.

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=response exists 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 configure SystemMailer first. 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 owner or admin role when Better Auth exists (ADR 0025). Self-hosted installations use ADMIN_EMAILS. Rejected: waiting for Better Auth before real mail can be sent.

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.

  • 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 write scope 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_approvals and send_approval_links in 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 api approve 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.

Recorded when plan row A2 was built (2026-11-13):

  • A link secret is cl_apsec_ followed by IdGenerator.secret(), so log redaction masks it (ADR 0026, ADR 0032).
  • The cloud mode’s refusal of response delivery was built with response delivery in A2, not in A4.
  • response delivery 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; and rate_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 from domain was removed can still be viewed and declined.
  • A refused view or decision gives the refusal in error.reason of 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 by SEND_APPROVAL_DELIVERY in the composition root: the caller pseudo-approver with response; with email, the workspace’s approvers read through ControlStore.approversOf, or the approvers of ADMIN_EMAILS on a self-hosted installation. ApprovalDelivery only delivers, and reports the links that reached their recipient. The operator writes a workspace’s approvers with PUT /operator/workspaces/:workspaceId/approvers, an operator endpoint in the manner of ADR 0035; it refuses with conflict while ADMIN_EMAILS names 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 read decidedBy can 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 refuses ADMIN_EMAILS, and response delivery with it is a configuration error.
  • Who may view or decide is who would get a link now: with response only the caller link, otherwise only the approvers, so a link handed to the caller stops working after a switch to email, and an approver’s link after a switch back. A link of a removed approver is refused with conflict and the reason approver_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) and approval_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.