mail-address-semantics/mas-modes-v0.1-spec/CONTRACT.md

# MAS mode contract v0.1

How email hands a conversation to another communication mode, and how
email works inside a control flow it does not own. The bundle is
versioned separately from the MAS address specification. In MAS terms,
`ticket!callback@D` *requests* a handoff to `callback` (address spec §7).
This contract defines what can happen to that request.

The keywords MUST, MUST NOT, SHOULD and MAY are used as in RFC 2119.

## 1. Concepts

- **Case.** A unit of communication. It is addressed by a canonical MAS
  resource address (`ticket=gs-1@D`), and identified by that address and a
  `key`. Email chooses the key from the address-spec equivalence of the
  target (§8), so equivalent addresses get the same key. Other parties
  treat the key as opaque and echo it back unchanged (MCP-4).
- **Thread.** The durable record of a case: inbound and outbound mail, plus
  every mode status.
- **Mode.** A communication channel other than email (`callback`, `chat`,
  ...), reached through a **mode endpoint** that speaks this contract.
- **Handoff.** One attempt to continue a case in a mode. It has a
  `handoff_id` and a status (§4).
- **Role.** For each resource type, email is either **master** or **slave**
  (§3). The role is fixed for the life of a case.
- **Outside master.** In the slave role, the system that owns the control
  flow (a CMS, ticketing or support system, or a framework).

## 2. Parties and transport

There are three parties: `email`, `mode` and `master`. Messages are JSON
objects, sent as HTTP `POST` with `Content-Type: application/json`. Every
message carries the envelope:

| Field | Meaning |
|---|---|
| `mas_modes_version` | `"0.1"` |
| `type` | message type (§5) |
| `id` | sender-chosen unique id; the idempotency key |
| `case` | `{address, key}`: canonical resource address and email's opaque case key (§1). Absent only in `case.intake` and `case.assign`. |

- **Idempotency.** A receiver MUST treat a repeated `id` as already
  processed, and SHOULD return the original response.
- **Ordering.** `handoff.status` carries `seq`, increasing per handoff. A
  receiver MUST ignore a status whose `seq` is not greater than the last
  one it accepted, and answers `{"ok": true, "ignored": "stale"}`.
- **Responses.** `2xx` with `{"ok": true, ...}` means the message was
  accepted. `4xx` with `{"ok": false, "error": CODE, "detail": ...}` means
  it was refused and MUST NOT be retried unchanged. `5xx` or no answer
  means the sender MAY retry with the same `id`.

## 3. Roles

### 3.1 Email as master

Email owns the case, the thread and the timeouts.

1. Mail to an intake address creates a case. Email then sends the
   participant one **acknowledgement** from the case address, so they learn
   it (MCP-1); principle 10 applies. Mail to the case address is recorded
   on that case.
   On `!MODE` to an intake or resource address, email creates or finds the
   case and sends `handoff.request` to the mode endpoint configured for
   that resource type and mode. If the statute does not enable the mode,
   email records `refused` (`mode-not-enabled`) itself. For a new case,
   the acknowledgement says so and no separate resume mail follows. If no
   endpoint is configured, or the endpoint refuses or cannot be reached,
   email records `refused` (`mode-unavailable`) and resumes (item 3).
2. Email sets a **deadline** for each handoff. If no terminal status
   (§4) has arrived by then, email records `timed-out`, sends
   `handoff.cancel` to the mode, and resumes by email.
3. Every status is recorded in the thread. On every terminal status, email
   **resumes**: it sends the case's participant one mail from the case
   address, saying what happened. The mail MUST name the outcome: the
   terminal status as written in §4 (`completed`, `timed-out`, ...) and,
   when present, the `reason` or `detail` (MCP-3). Principle 10 (§6)
   applies.
4. **Details** (MCP-2). A detail is a line `Field: value` in a mail body.
   Field names are compared ignoring case, and the first occurrence wins.
   Email reads the fields the role configuration names (`fields`) from the
   mail that requests a handoff, and puts them in `handoff.request`'s
   `details`. `negotiating` with `needs` makes email ask the participant
   with one mail that lists each needed field on its own line as
   `Field: ...`, with the field name capitalized. A later mail on the case
   that supplies needed fields is sent to the mode as `handoff.update`.

### 3.2 Email as slave

The outside master owns the control flow, case identifiers and timeouts.

1. **Case identifiers come from the master.** Intake mail (no case yet) is
   reported as `case.intake` with an `intake_ref`. The master answers with
   `case.assign`, giving the resource id, which email adopts as the case
   address `TYPE=ID@D`. Email MUST NOT invent case identifiers in this
   role. Until assigned, the intake stays pending. `case.assign` MAY carry
   the case's initial `policy`. A mode requested in the intake mail
   (`requested_mode`) is handled under that policy once the case exists.
2. Inbound mail on a case is reported as `case.message`.
3. **Sending.** Email sends only on `mail.send` from the master, unless the
   case policy (`case.policy`) sets `autonomous_send: true`. Then email
   MAY also send acknowledgements and negotiation questions itself. A
   `mail.send` is always a reply to a message already recorded on the case
   (`in_reply_to`): the recipient is that message's sender. A requested
   send can still be refused under §6, and the refusal is the response.
   Policy fields the master does not set take the email side's defaults
   for the resource type.
4. **Transfers.** The case policy sets `transfers` to `"block"` or to
   `{"webhook": URL, "peer": ID}` (the peer must be known to email, §7.3).
   With `block`, a `!MODE` request is reported as `handoff.requested` with
   `"forwarded": false`, followed by one `handoff.status` `refused` with
   reason `blocked`, and nothing else happens (MCP-6). With a webhook,
   email sends `handoff.request` to that URL, reports `handoff.requested`
   with `"forwarded": true`, and relays every status the mode sends (and
   one it records itself, such as `mode-unavailable`) as `handoff.status`.
   It numbers them with its own `seq`. Email's own `requested` is not
   relayed: `handoff.requested` stands for it. Email does the negotiation
   (3.1 item 4) only when `autonomous_send` is true.
5. **Timeouts belong to the master.** Email sets no deadline and never
   records `timed-out`. The master MAY end a handoff with `handoff.cancel`.

## 4. Handoff status machine

| From | Allowed next statuses |
|---|---|
| (new) | `requested` |
| `requested` | `negotiating`, `scheduled`, `running`, `refused`, `failed`, `cancelled`, `timed-out` |
| `negotiating` | `negotiating`, `scheduled`, `refused`, `expired`, `cancelled`, `timed-out` |
| `scheduled` | `running`, `attempted`, `expired`, `cancelled`, `timed-out` |
| `attempted` | `scheduled`, `failed`, `expired`, `cancelled`, `timed-out` |
| `running` | `completed`, `failed`, `cancelled`, `timed-out` |

**Terminal** statuses are `completed`, `failed`, `expired`, `refused`,
`cancelled` and `timed-out`. Nothing follows a terminal status.

- `requested`: recorded by email when it sends `handoff.request`.
- `negotiating`: the mode needs details. `needs` lists field names
  (`phone`, `time`, ...).
- `scheduled`: has `at` (RFC 3339) when known. Going from `attempted` to
  `scheduled` is a retry.
- `attempted`: an attempt did not reach the participant. `outcome`, e.g.
  `no-answer`.
- `refused`: has `reason`, one of `mode-unavailable`, `mode-not-enabled`,
  `declined`, `out-of-hours`, `blocked`.
- `timed-out`: recorded only by the timeout owner: email as master, or the
  master's own bookkeeping. A mode MUST NOT send it.
- `cancelled`: after `handoff.cancel`.

A receiver MUST refuse a transition that the table does not allow
(`error: invalid-transition`).

## 5. Message types

| Type | From → to | Payload |
|---|---|---|
| `handoff.request` | email → mode | `handoff_id`, `mode`, `details` (known fields), `status_url` (where statuses go), `participant` (`{address}`) |
| `handoff.update` | email → mode | `handoff_id`, `details` |
| `handoff.cancel` | email → mode, master → email | `handoff_id`, `reason` |
| `handoff.status` | mode → email, email → master (relay) | `handoff_id`, `seq`, `status`, plus `needs` / `at` / `outcome` / `reason` / `detail` |
| `case.intake` | email → master | `intake_ref`, `resource_type`, `event` (gateway event), `requested_mode` |
| `case.assign` | master → email | `intake_ref`, `resource_id`, optional `policy` (`{autonomous_send, transfers}`) |
| `case.message` | email → master | `event`, `message_ref` |
| `case.policy` | master → email | `autonomous_send` (bool), `transfers` (`"block"` or `{"webhook": URL, "peer": ID}`) |
| `handoff.requested` | email → master | `handoff_id`, `mode`, `forwarded` (bool) |
| `mail.send` | master → email | `in_reply_to` (a `message_ref`), `subject`, `body` |

`status_url` contains the per-handoff token (§7.3). `event` is the normalized gateway event (`schema/mas-event-v0.1.schema.json`).
`message_ref` is the email side's id for a recorded inbound message.

`mail.send` responses: `{"ok": true, "sent": true}`, or `{"ok": false,
"error": "refused", "reason": R}` with R one of `unauthenticated-sender`,
`automated-sender`, `send-cap-reached`, `unknown-message`. With
`send-cap-reached` the response also carries `held` (bool, §6).

`case.assign` responds `{"ok": true, "case": {address, key},
"message_ref": M}`, where M is the intake message, now recorded on the
case. When `autonomous_send` is on, the response also has `acknowledged`
(bool). When the intake requested a mode, it has `handoff_id`.

### 5.1 Other errors

Besides §7.4, a receiver answers with these codes (MCP-5):

| Code | HTTP | Meaning |
|---|---|---|
| `schema` | 400 | the message does not validate against the schema |
| `invalid-resource-id` | 400 | `case.assign` id does not make a valid resource address |
| `unknown-handoff` | 404 | no such handoff at this URL, or the `handoff_id` / `case` do not match it |
| `unknown-case` | 404 | no case with this key |
| `unknown-intake` | 404 | no intake with this `intake_ref` |
| `invalid-transition` | 409 | the status may not follow the current one (§4) |
| `already-assigned` | 409 | the intake already has a case |
| `case-exists` | 409 | a case with the same key exists |
| `refused` | 409 | `mail.send` not sent, with `reason` (§5) |

## 6. Principle 10 in both roles

Email MUST NOT send mail to a sender that did not pass DMARC (as read
from trusted `Authentication-Results`), to automated mail (`Auto-Submitted`
other than `no`, or `Precedence: bulk | list | junk`), or to the null
sender. It MUST NOT send once its send cap is reached. These rules hold
whoever asks for the send: email itself as master, the case's autonomous
policy, or a master's `mail.send`.

The send cap is **one cap per deployment**. Every mail email sends, in
either role and from any application behind it, counts against the same
total. Over the cap, a mail is **held**: recorded unsent, and reported to
whoever asked as `send-cap-reached`. Held mail MUST be deleted after a
configured maximum age (default 7 days). It MUST NOT be stored once held
mail would exceed a configured maximum size (default 100 MB); the mail is
then reported as not held. Mail actually sent is never purged, because it
is what the cap counts.

## 7. Peer authentication and transport security

Contract messages steer real mail (`mail.send`, `case.assign`,
`case.policy`) and change what customers are told (`handoff.status`).
Every party MUST therefore know who sent a message before acting on it.

### 7.1 Peers and keys

Each party has a **peer id** (`email`, `cms-1`, `callback-1`, ...).
Every pair of parties that exchange messages shares a secret key of at
least 32 random octets. Keys are pairwise: email holds one key per master,
mode endpoint and gateway it talks to, and the other party holds the same
key for email. Keys are configuration, never part of a message.

### 7.2 Signed requests (MUST)

Every contract request MUST carry three HTTP headers. Gateway events
(gateway → email) MUST carry them when the gateway and the email side are
on different hosts. A deployment MAY leave them off for events on
loopback; the email side is then configured to accept unsigned events,
and only from loopback.

| Header | Value |
|---|---|
| `MAS-Modes-Peer` | the sender's peer id |
| `MAS-Modes-Timestamp` | the time of sending, as integer Unix seconds |
| `MAS-Modes-Signature` | `v1=` followed by the lower-case hex HMAC-SHA256, keyed with the pair's key, of `TIMESTAMP + "." + BODY`, where BODY is the exact request body octets |

The receiver MUST:

1. look up the key for `MAS-Modes-Peer`. If the peer is unknown, refuse
   with `401 unauthenticated-peer`;
2. recompute the signature over the received octets and compare it in
   constant time. On a mismatch or missing header, refuse with
   `401 unauthenticated-peer`;
3. refuse a timestamp more than 300 seconds from its own clock with
   `401 replayed`;
4. only then parse and act on the body. A repeated message `id` inside
   the window gets the original response (§2), so a captured request
   cannot cause a second effect.

Responses are not signed. They travel on the connection the signer opened.
Mutual TLS MAY be used in addition, but it does not replace signing: the
peer id and the authorization in §7.3 come from the signed headers.

### 7.3 Authorization

Authentication says who sent a message. Email then also checks that this
peer may send it:

- **Master commands** (`case.assign`, `case.policy`, `mail.send`,
  `handoff.cancel` to email) are accepted only from the peer configured
  as master for the case's resource type (for `case.assign`, the intake's
  resource type). Anyone else gets `403 wrong-peer`.
- **Mode statuses.** Each handoff is bound to the peer it was sent to.
  `handoff.request` carries a `status_url` that contains an unguessable
  per-handoff token (at least 128 bits). Email accepts a `handoff.status`
  only at that URL, and only from that peer (`403 wrong-peer`). A
  `handoff_id` alone is not enough.
- **Primed webhooks** (slave role). `transfers.webhook` MUST name the
  receiving mode's `peer`, which MUST be a peer email already has a key
  for. Otherwise `case.policy` and `case.assign` are refused with
  `400 unknown-peer`. A master can therefore direct handoffs only to
  modes the email operator has provisioned. It cannot make email sign
  requests to an arbitrary URL with a key it chose.
- **Mode endpoints** accept `handoff.request`, `handoff.update` and
  `handoff.cancel` only from email's peer id.
- **Masters** accept `case.*`, `handoff.requested` and relayed
  `handoff.status` only from email's peer id.

### 7.4 Errors

| Code | HTTP | Meaning |
|---|---|---|
| `unauthenticated-peer` | 401 | unknown peer, missing or bad signature |
| `replayed` | 401 | timestamp outside the window |
| `wrong-peer` | 403 | authenticated, but not allowed to send this |
| `unknown-peer` | 400 | a webhook names a peer email has no key for |

A sender MUST NOT retry `401` or `403` unchanged.

## 8. Conformance

`conformance/` holds valid and invalid messages, the transition table as
data, the callback scenarios (`scenarios.json`), and scripted flows. Each
flow is a sequence of inbound mail, contract messages and clock ticks,
with the expected email-side reaction, defined in `conformance/FLOWS.md`
and runnable from the bundle alone.
`conformance/auth.json` holds signing vectors and verification cases for
section 7; every party MUST pass them. Flows `a-*` check authorization at
the email side. An email-side implementation claims `MAS-MODES-EMAIL-MASTER`
or `MAS-MODES-EMAIL-SLAVE` by passing the flows for that role.