ADR-0028: Calls to systems we do not own are guarded, signed, keyed and recorded before they are sent

  • Status: Accepted
  • Date: 2026-11-11
  • Scope: core (any product that calls an address a user, a customer or a model supplied, or delivers events to
    another party’s system)

Context

The agents platform calls its tenants’ own systems: operations imported from an OpenAPI document, MCP servers, and
webhooks that receive a confirmed action (agents 0009-calls-to-tenant-systems, 0020-actions-end-a-conversation-and-land-in-the-inbox,
0021-a-tools-kind-is-what-it-is-for-not-how-it-is-carried-out). The address of each comes from a person or from
a model, and the call often changes something on the other side (books a time, cancels it). Building it showed the
same needs every time:

  • an address that points inward (localhost, a private range, a metadata endpoint), directly or through a redirect;
  • a receiver that cannot tell our call from anyone’s, nor which of our users it is acting for;
  • a call sent twice — a retry, a resend, a timeout that actually succeeded — doing the thing twice;
  • a failed call losing what the user had confirmed;
  • an event whose shape changed under a receiver that parses it.

Decision

1. Every address from outside passes an egress guard, on every hop

Before connecting: https only, and every address the host resolves to is public. A redirect is followed only after
its target passes the same check, up to a small number of hops; a response is capped in size and in time. A
guard’s switches for private addresses or plain http exist for tests only. The guard runs before every call,
not when the address is saved: DNS answers change.

2. Every outgoing call is signed, and the signed payload is versioned

The signature is an HMAC over a timestamp, the method, the path and query, the identity we act for, the call’s
idempotency key and a hash of the body, sent as v<N>=<hex> with the timestamp in its own header. The receiver
checks it before trusting anything the request claims, including who the user is. The payload never changes
without a new version; a version never released is replaced, not kept beside the new one.

3. Every call carries an idempotency key, stable for one logical delivery

The key is fresh for a one-off call and the same on every attempt of one delivery (derived from what is delivered:
<record id>:<destination>). Because it is signed, it is also the call’s nonce. Receivers deduplicate on the key,
never on the bytes: a JSON store may reorder an object’s keys, so a resent body can differ byte for byte and be
the same content.

4. The record is written first; delivering is a separate, recorded attempt

What the user confirmed is stored before any delivery starts, in its own transaction, and a failed delivery never
undoes it. Each attempt is kept on the record: when, where, what it sent, its key, the outcome and a reason. A
resend sends the same arguments with the same key, outside a transaction (core 0002-clean-architecture-and-use-cases:
no transaction across a remote call). Only a delivery whose latest attempt failed can be resent; a test record is
delivered nowhere.

5. An event we send whole has a type and a version

When the receiver gets our object rather than its own operation’s arguments (a webhook), the body names its
type and version. Its shape changes only with a new version.

6. A request sent to us again is the same request

The other direction: a client request that may be retried carries an Idempotency-Key; the same key returns the
first request’s result (waiting while it is still being processed), and the same key with a different body is a
conflict, never a second execution.

Consequences

  • An address a model found, or a user pasted, cannot reach our network.
  • A receiver can trust who is calling and whom for, and can make its side idempotent with one lookup.
  • Resending is safe to offer to a user, and automatic retries become a scheduling question, not a correctness one.
  • Accepted: two resends at the same moment are not locked against each other; the key makes the duplicate
    harmless at a receiver that honours it.
  • A receiver that ignores the key can still act twice; the integration guide must say to honour it.