# Destinations: governed egress

A destination is a place Bucker **sends data to**: an HTTPS endpoint that receives the events and
logs a filter selects, cut to the fields you name, scrubbed, and signed. It is the one door through
which telemetry leaves on purpose, so it is governed like the most sensitive configuration there is:
proposed by a person or an agent, approved by a person, inert until a second approval turns it on,
and unable to send **more** than a person approved without a person's own act.

Everything on this page is **opt-in and inert by default**. A deployment with no destination
configured sends nothing, opens no connection and stores no row.

## What a destination is

| Part | What it holds |
|---|---|
| Kind | `http_webhook` or `object_store`. `snowflake` and `bigquery` are reserved and refused, naming WH-09. Two more kinds exist only as the **umbrella** rows below. |
| Host | An entry on your organization's **egress allow-list** (`egressHostId`). A person adds hosts; a destination can only name one that is already there, and never Bucker's own ingest or API host (the loop guard). |
| Credential | A connection (`connectionId`) a person binds. A destination that signs with a secret cannot go live without one. |
| Filter | A closed predicate (`key`, `op`, `value`, ANDed) over what is sent. **No filter selects nothing.** |
| Field allow-list | The only fields that leave. A field not named is never sent. |
| Tier | `agent` (the default, the strictest scrub) or `stored`. |
| Pace | A batches-a-minute limit and an optional request path under the host. |
| State | `draft`, `enabled`, `paused`, `disabled`. The delivery ledger also keeps its own pause. |

A destination never carries a URL or a secret in anything an agent can write. The schemas have no
field for one.

## What leaves, in order

The order is the security property, and the preview shows exactly this function's output:

1. **Suppressed subjects** are dropped (the subject is read from the whole row, so a field that is
   never sent can still decide a row is not).
2. **Your rules** for the destination run (the pipeline rules, `transformations_*`). A rule whose
   expression cannot be evaluated **holds the batch and pauses the destination**; it never sends
   unfiltered.
3. **The cut**: only the allow-listed paths survive. It comes *after* the rules, because a `set` or
   rename rule can introduce a field, and a field nobody allow-listed must not leave.
4. **The scrub** at the destination's tier, with your organization's own scrub rules.
5. **The signature**: Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`)
   over exactly the bytes sent. The id is derived from the batch, so a retry is the same message to
   the receiver.

Delivery runs through the **delivery ledger**: every batch has a row, a state, attempts and a
receipt; a receiver's `Retry-After` is honoured; a failing hour pauses the destination and tells the
owners; a dead batch holds the position until a person replays it. Rows are sent in one-minute
windows, oldest first, starting from the moment the destination was enabled (it does not backfill
history).

## Setting one up

1. **Preview.** `POST .../destinations/preview`, or `destinations_list` with `include: [preview]`
   and a `candidate`. It returns the **exact payload** for recent matching events at the proposed
   tier (no network call, by construction), the 7-day matching volume and bytes a day, the fields
   with the personal-data categories each may carry, the egress diff (host, fields and tier before
   and after), the lineage dependents (`not_available` until the lineage package lands), and a
   **digest** good for 10 to 15 minutes. The digest is bound to your organization, the name and the
   resulting cut, and carries the measured volume, so the figure an approver reads is the one that
   was shown.
2. **Propose.** `POST .../destinations` or the `destination_propose` tool, with that digest. The act
   is `pipeline.destination.create`, which **always asks**. The destination is filled in and is
   **still a draft**.
3. **Bind the credential.** A person points the destination at a connection
   (`POST .../destinations/:name/bind`, `egress:admin`). The host is added through the egress-host
   routes and the credential through the connection routes; `bind` takes ids, never a URL or a
   secret.
4. **Go live.** `state: enabled` is its own act, `pipeline.destination.enable`, and asks again. It
   needs a cut, an allow-listed host and (for an HTTP webhook) a credential.

## Changing one

`POST .../destinations/:name/update` and the `destinations_update` tool take exactly **one** change.
The act is derived from the difference between the destination as it is and the one you ask for,
never from an argument.

| Change | Act | Risk | Applies |
|---|---|---|---|
| `state: paused` | `pipeline.destination.pause` | ELEVATED | Allowed. **SENSITIVE and asked** when the target carries alert, monitor, SLO or status events. |
| `state: enabled` from a pause | `pipeline.destination.resume` | SENSITIVE | Asked. Releases what the pause held. |
| `state: enabled` from a draft | `pipeline.destination.enable` | SENSITIVE | Asked (ask floor). |
| Fewer fields, a stricter tier, a tighter filter | `pipeline.destination.narrow` | ELEVATED | Allowed under a policy; needs a preview digest. |
| A pace change | `pipeline.destination.update` | SENSITIVE | Asked (ask floor). |
| `suppression` | `pipeline.suppression.create` | ELEVATED | Allowed. Stops one subject's rows. |
| `replay` | `pipeline.delivery.replay` | SENSITIVE | Asked; **CRITICAL with dual control** when the target changed since the first attempt or the range exceeds 30 days. See the note below. |

### What an agent can never do

**A change that lets more leave, or leave somewhere else, is `pipeline.destination.widen`: a
person's act with `egress:admin`.** The governed path refuses it before anyone is asked, naming the
act. Concretely, all of these are widenings:

- a field added;
- a lower tier (`agent` to `stored`);
- any change of host or request path;
- a filter that is not **provably** narrower (it narrows only if it keeps every clause the old one
  had; a reworded clause is a widening);
- dropping a rule that protected a field.

A mixed change (one field removed, another added) is a widening. The never-widen property test runs
thousands of random plans over all five dimensions and asserts that nothing the family would let an
agent apply holds less back than before. A new destination is born at the `agent` tier; choosing
`stored` is a person's act too.

Deleting a destination, removing a suppression, adding a host and setting a credential are
human-only and have no tool. They are refused to an agent, a service and an OAuth-client human, and
each writes one audit row.

## Suppressions

A suppression stops one subject's rows reaching one destination. The key you give is an opaque
pseudonym; an email address, a phone number or a sentence is refused. It is stored and echoed **only
as a keyed hash** (an HMAC under the deployment's secret and your organization), so a stored row, a
plan, an operation record and every answer carry the hash and nothing that was typed. No tool returns
even the hash: `destinations_list` returns a **count**. A person with `pii:read` sees the hashes in
the dashboard (`GET .../suppressions`). Removing one is consent loosening and is a person's act.

## Existing webhooks and sinks

Every outbound webhook and warehouse sink gets exactly one **umbrella** destination row (an additive
backfill, idempotent, named `umbrella-webhook-...` or `umbrella-sink-...`, a name space customers
cannot take), so pause, a field list and the delivery ledger cover them too.

- **Pausing the umbrella pauses the real thing.** The pause is written under the webhook's or sink's
  own ledger key, the one the sender reads, and the webhook's delivery pass skips it.
- **A field list on a webhook umbrella** cuts the `data` of each body to those paths and scrubs it at
  the row's tier at send time, and the signature covers the bytes that left. With no list the body is
  sent exactly as stored; setting one is a narrowing, clearing it is a widening.

## Tools

| Tool | Relation | What it does |
|---|---|---|
| `destinations_list` | `read` (preview: `configure_pipeline`, held) | The destinations a project sees, with rules, deliveries and the preview on request. Suppressions as counts. Names, hosts, field paths and payload rows are fenced and untrusted. |
| `destination_propose` | `configure_pipeline` (held) | The governed create. Always asks. |
| `destinations_update` | `configure_pipeline` (held) | The governed change, the act derived from the diff. |

All three are in the `pipeline` toolset. The write tools are **held** until the security review of the
OAuth authorization server is signed off: they are not listed for any token a production path can
mint, and the engine repeats the check.

## Notes for operators

- **Replay of dead batches** is implemented and tested, but its act (`pipeline.delivery.replay`) is not
  yet registrable with the engine: the registry requires an irreversible act to be CRITICAL as a class,
  and this one is SENSITIVE with a CRITICAL derivation. Until that registry row changes, the replay
  doors answer `replay_not_registered`, and a person resumes a paused destination to release what was
  held.
- **A preview digest expires in 10 to 15 minutes.** The check runs again when the approved change is
  retried, so an approval that takes longer than that is refused with `preview_expired` and applies
  nothing (the yes is not spent); preview the change again and propose it again.
- **`object_store` destinations** share the model and the governance; their delivery rides the
  customer-bucket export sink and is not part of the HTTP delivery pass yet.
