# airdress.federation.*

{/* Generated by scripts/generate-event-reference.mjs from https://schemas.airdress.co/operator/events/v1.json (operator v0.1.138).
    Do not edit by hand: run `pnpm generate:event-reference` and commit the result. */}

The events in the `airdress.federation` family. How to read a section, and what
each audience means, is on the [event reference](/events/) page.

## `airdress.federation.binding_conflict`

Owner warn Functions

The owner's registry and a stapled hub binding disagree about which keys speak for an airdress. The registry is used; a person should look at why.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- **Functions bound to this operator's events** (`source: operator`).

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `airdress` | string | yes |  |
| `binding_kid` | string | yes |  |
| `registry_spki` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "The owner's registry and a stapled hub binding disagree about which keys speak for an airdress. The registry is used; a person should look at why.",
  "properties": {
    "airdress": {
      "type": "string"
    },
    "binding_kid": {
      "type": "string"
    },
    "registry_spki": {
      "type": "string"
    }
  },
  "required": [
    "airdress",
    "binding_kid",
    "registry_spki"
  ],
  "title": "FederationBindingConflict",
  "type": "object"
}
```

</details>

## `airdress.federation.binding_refused`

Owner warn

A peer's operator binding was refused: `reason` says why (no transport identity, revoked, a binding that did not verify, …). Anybody can cause one, so it stays off the bus.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: it is kept off that path as too frequent or too internal. A subscription with a function target still receives it.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `airdress` | string | yes |  |
| `peer_spki` | string | yes | The first eight bytes of the peer's SPKI hash, hex; empty when it presented none. |
| `reason` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A peer's operator binding was refused: `reason` says why (no transport identity, revoked, a binding that did not verify, …). Anybody can cause one, so it stays off the bus.",
  "properties": {
    "airdress": {
      "type": "string"
    },
    "peer_spki": {
      "description": "The first eight bytes of the peer's SPKI hash, hex; empty when it presented none.",
      "type": "string"
    },
    "reason": {
      "type": "string"
    }
  },
  "required": [
    "airdress",
    "peer_spki",
    "reason"
  ],
  "title": "FederationBindingRefused",
  "type": "object"
}
```

</details>

## `airdress.federation.delivery_status_changed`

Owner debug App stream

A federated message this airdress sent changed delivery status.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- **The app's event stream**, as `delivery_status`: devices it concerns hear of it at once.
- Not functions bound to this operator's events: it is kept off that path as too frequent or too internal. A subscription with a function target still receives it.

**Versions**

- Version 1: first carried by operator v0.1.133.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `airdress` | string | yes |  |
| `message_id` | string (uuid) | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A federated message this airdress sent changed delivery status.",
  "properties": {
    "airdress": {
      "type": "string"
    },
    "message_id": {
      "format": "uuid",
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "airdress",
    "message_id",
    "status",
    "updated_at"
  ],
  "title": "DeliveryStatusChanged",
  "type": "object"
}
```

</details>

## `airdress.federation.from_not_authorized`

Owner warn Functions

A federation envelope claimed to come from an airdress its authenticated peer may not speak for, and was refused.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- **Functions bound to this operator's events** (`source: operator`).

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `claimed_from` | string | yes |  |
| `may_speak_for` | array of string | yes |  |
| `peer_spki` | string | yes | The first eight bytes of the peer's SPKI hash, hex. |
| `source` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A federation envelope claimed to come from an airdress its authenticated peer may not speak for, and was refused.",
  "properties": {
    "claimed_from": {
      "type": "string"
    },
    "may_speak_for": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "peer_spki": {
      "description": "The first eight bytes of the peer's SPKI hash, hex.",
      "type": "string"
    },
    "source": {
      "type": "string"
    }
  },
  "required": [
    "claimed_from",
    "may_speak_for",
    "peer_spki",
    "source"
  ],
  "title": "FederationFromNotAuthorized",
  "type": "object"
}
```

</details>

## `airdress.federation.own_binding_expired`

Owner error Functions

This operator's own hub binding lapsed without a refresh; peers refuse it for that airdress until the hub answers again. Once per lapse.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- **Functions bound to this operator's events** (`source: operator`).

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `airdress` | string | yes |  |
| `expired_at` | integer (int64) | yes | Unix seconds. |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "This operator's own hub binding lapsed without a refresh; peers refuse it for that airdress until the hub answers again. Once per lapse.",
  "properties": {
    "airdress": {
      "type": "string"
    },
    "expired_at": {
      "description": "Unix seconds.",
      "format": "int64",
      "type": "integer"
    }
  },
  "required": [
    "airdress",
    "expired_at"
  ],
  "title": "OwnBindingExpired",
  "type": "object"
}
```

</details>

## `airdress.federation.own_binding_refreshed`

Owner info Functions

This operator's own hub binding for an airdress was refreshed: the hub signed a new version naming this operator's transport key.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- **Functions bound to this operator's events** (`source: operator`).

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `airdress` | string | yes |  |
| `binding_version` | integer (int64) | yes |  |
| `expires_at` | string | yes |  |
| `kid` | string | yes |  |
| `spki` | string | yes | The first eight bytes of the transport key's SPKI hash, hex. |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "This operator's own hub binding for an airdress was refreshed: the hub signed a new version naming this operator's transport key.",
  "properties": {
    "airdress": {
      "type": "string"
    },
    "binding_version": {
      "format": "int64",
      "type": "integer"
    },
    "expires_at": {
      "type": "string"
    },
    "kid": {
      "type": "string"
    },
    "spki": {
      "description": "The first eight bytes of the transport key's SPKI hash, hex.",
      "type": "string"
    }
  },
  "required": [
    "airdress",
    "binding_version",
    "expires_at",
    "kid",
    "spki"
  ],
  "title": "OwnBindingRefreshed",
  "type": "object"
}
```

</details>

## `airdress.federation.peer_admitted`

Owner debug

A federation peer was admitted, by the owner's registry or a stapled hub binding (`source`). One per request, so it stays off the bus.

**Audience: owner.** About the airdress as a whole. Only the owner receives it: the owner's devices and the owner's subscriptions.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: it is kept off that path as too frequent or too internal. A subscription with a function target still receives it.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `kid` | string | yes |  |
| `source` | string | yes |  |
| `spki` | string | yes | The first eight bytes of the peer's SPKI hash, hex. |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A federation peer was admitted, by the owner's registry or a stapled hub binding (`source`). One per request, so it stays off the bus.",
  "properties": {
    "kid": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "spki": {
      "description": "The first eight bytes of the peer's SPKI hash, hex.",
      "type": "string"
    }
  },
  "required": [
    "kid",
    "source",
    "spki"
  ],
  "title": "FederationPeerAdmitted",
  "type": "object"
}
```

</details>

## `airdress.federation.request_received`

The person it concerns info

First contact from another airdress, delivered to `principal_id` as a message request.

**Audience: the person it concerns.** About one person on the airdress. It reaches only that person: their own devices and subscriptions they made themselves. The owner's subscriptions never receive another person's events.

**Where it goes**

- **The operator's journal**, as one log line at this level, and **the event log**, where `airdress events tail` reads it.
- **Subscriptions** that name it, within its audience.
- Not functions bound to this operator's events: functions act for the owner, and this event is about someone else.

**Versions**

- Version 1: first carried by operator v0.1.138.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `from` | string | yes |  |
| `principal_id` | string (uuid) | yes | The person the request is for. Not in the journal line, which never carried it. |
| `to` | string | yes |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "First contact from another airdress, delivered to `principal_id` as a message request.",
  "properties": {
    "from": {
      "type": "string"
    },
    "principal_id": {
      "description": "The person the request is for. Not in the journal line, which never carried it.",
      "format": "uuid",
      "type": "string"
    },
    "to": {
      "type": "string"
    }
  },
  "required": [
    "from",
    "principal_id",
    "to"
  ],
  "title": "FederationRequestReceived",
  "type": "object"
}
```

</details>