tegwick
3c2cdcdf79
Registration: attributive, with the declared completeness_trade recorded on the receiver side rather than only in the emitter, per §9.6's requirement that the trade travel with the trail. tenants ["*"] is justified rather than inherited — tenant-engine's events carry the affected tenant, the set is every tenant including ones created later, and an explicit list would fail closed at exactly the moment a tenant is provisioned, dead-lettering the creation evidence of the tenant whose creation it is. source stays pinned exactly. Ingress ANDs namespace and pod label; a weaker evidence class is not a reason for a wider network rule. All inert until the token exists. Then the finding T04 existed to find: tenant-engine cannot deliver a single event today. envelope_for sends five required fields under other names — event_id, action, resource, observed_at, details — and omits correlation_id entirely, so normalize() raises invalid_event. Verified by running the real envelope through the real function, not by reading. Worse than an ordinary integration bug. The drain treats 400 as terminal, so the outbox row is marked handled while audit-core holds only a dead letter, which is not chained and is not custody. Lost on both sides, and since the drain is non-blocking and attributive, nothing fails loudly — a silent total loss of the stream presenting as a working integration. Taking the correction the intake invited rather than accepting a lossy record. normalize() is NOT relaxed to accept the alternate spellings: a receiver that guesses which sender key means which stored field has made the mapping its own, and the record stops being the sender's assertion. correlation_id cannot be synthesized at all — an invented one ties an event to an operation audit-core never observed. Root cause is ours. The accepted envelope was published nowhere a sender could read it; audit-backend-contract.md describes the stored record, and a sender reading it would reasonably infer exactly the names tenant-engine used. schema_version audit-core.event.v1alpha1 selects nothing here and gave a false impression of a negotiated contract. Published docs/event-envelope.md as the wire contract, including the point that a 400 means the event is not in the archive and must be treated as a defect to fix rather than a delivery outcome. T05 moved to wait: nothing to prove end to end until an event can be accepted. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Nb7Q6ZmXppNDkTWytfYqfv Assistant: claude-code Assistant-Model: opus Assistant-Process: 2069992@bnt-lap001 Assistant-Session: 167dd7f8-2a25-4be1-aa46-3b6f1a5f94c6
110 lines
4.7 KiB
Markdown
110 lines
4.7 KiB
Markdown
# The ingest envelope: what `POST /v1/events` accepts
|
|
|
|
`AUDIT-WP-0010-T04`. Written because it was not written down, and a sender
|
|
built against a shape the receiver does not implement.
|
|
|
|
This is the wire contract for a sender. It is the authority; anything a sender
|
|
infers from another sender's code, from `docs/audit-backend-contract.md` (which
|
|
describes the *storage* record, not the request), or from a schema name, is a
|
|
guess.
|
|
|
|
## Request
|
|
|
|
```
|
|
POST /v1/events
|
|
Authorization: Bearer <sender token>
|
|
Idempotency-Key: <the event's id — must equal the body's "id">
|
|
Content-Type: application/json
|
|
```
|
|
|
|
## Body — all eight fields are required
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `id` | string | The event id. Must equal the `Idempotency-Key` header exactly, or the request is rejected `idempotency_key_mismatch` |
|
|
| `type` | string | The domain event type. Stored as the record's `action` |
|
|
| `source` | string | The emitting system. Checked against the credential's permitted sources |
|
|
| `subject` | string | What the event is about. Stored as the record's `resource` |
|
|
| `tenant` | string | The affected tenant. Checked against the credential's permitted tenants by **exact string equality** |
|
|
| `correlation_id` | string | Ties an event to the request or operation that caused it |
|
|
| `occurred_at` | string | RFC 3339 **with an explicit offset**. A naive timestamp is rejected — it is ambiguous by up to a day |
|
|
| `data` | object | The event payload. Stored verbatim under `details.data`, subject to the sender's `secret_policy` |
|
|
|
|
Every one of the eight must be present **and truthy**. An empty string, an
|
|
empty object, or `null` fails the same way a missing key does.
|
|
|
|
There is no `schema_version` field. A body carrying one is not rejected for it —
|
|
unknown top-level keys are ignored — but it is not stored and it selects
|
|
nothing. Do not treat a version string as a contract with this receiver.
|
|
|
|
### Minimal accepted body
|
|
|
|
```json
|
|
{
|
|
"id": "a5f3...",
|
|
"type": "role.granted",
|
|
"source": "tenant-engine",
|
|
"subject": "tenant:acme",
|
|
"tenant": "tenant:acme",
|
|
"correlation_id": "req-9f21",
|
|
"occurred_at": "2026-09-10T11:04:12+00:00",
|
|
"data": {"role": "admin", "granted_by": "u-1"}
|
|
}
|
|
```
|
|
|
|
## What the receiver derives, and a sender must not send
|
|
|
|
These are set by audit-core and any value a sender supplies for them is
|
|
ignored. Sending them is harmless but misleading, because it looks like the
|
|
sender controls them.
|
|
|
|
| Stored field | Where it comes from |
|
|
| --- | --- |
|
|
| `observed_at` | normalized from `occurred_at` |
|
|
| `action` | `type` |
|
|
| `resource` | `subject` |
|
|
| `scope` | always `"tenant"` |
|
|
| `outcome` | always `"recorded"` — this receiver records; it does not adjudicate |
|
|
| `actor` | always `null` at ingest. If the acting principal matters, put it inside `data` |
|
|
| `details.redaction` | added when `secret_policy` removed something |
|
|
|
|
`outcome` and `actor` being fixed is deliberate and worth understanding: an
|
|
audit event here is a record that a sender said something, not a finding about
|
|
it. A sender that wants an outcome recorded puts it in `data`, where it reads
|
|
as the sender's claim rather than the archive's.
|
|
|
|
## Responses
|
|
|
|
| Status | Meaning |
|
|
| --- | --- |
|
|
| `202` | Accepted and stored |
|
|
| `200` | Duplicate `id` — already stored, reconciled rather than re-linked. Not an error; do not retry |
|
|
| `400` | Rejected and **dead-lettered**. Body carries the reason: `invalid_event`, `idempotency_key_mismatch`, `source_not_allowed`, `tenant_not_allowed`, `secret_shaped_field` |
|
|
| `401` | Unknown or expired token |
|
|
| `403` | The credential lacks `may_write` |
|
|
|
|
**A 400 means the event is not in the archive.** It is retained in the
|
|
dead-letter surface with its reason, which is a diagnostic queue, not custody:
|
|
it is not chained, and it is not what a reviewer reads. A sender whose drain
|
|
treats 400 as terminal will lose the event on both sides — its outbox marks the
|
|
row handled and audit-core holds only a dead letter. Treat a 400 as an
|
|
integration defect to fix, never as a delivery outcome to record and move on
|
|
from.
|
|
|
|
## Rejection is total, not partial
|
|
|
|
There is no lossy accept. If a required field is missing the whole event is
|
|
rejected — audit-core does not store a partial record with a synthesized
|
|
`correlation_id` or a defaulted timestamp, because a record the archive
|
|
partly invented is worse than no record: a reviewer cannot tell which fields
|
|
the sender actually asserted.
|
|
|
|
This is why an envelope mismatch is loud rather than silent, and it is the
|
|
intended behaviour.
|
|
|
|
## Before you write a drain
|
|
|
|
Post one event against a non-production receiver and check for `202`. Every
|
|
field above is checked on the first request, so a single successful post
|
|
validates the whole envelope. A sender that first exercises the path in
|
|
production discovers the contract through its dead-letter queue.
|