# airdress.machine.*

{/* 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.machine` family. How to read a section, and what
each audience means, is on the [event reference](/events/) page.

## `airdress.machine.approval_renewed`

Owner info Functions

A machine approved before re-authenticated and was approved again: the same id and grants, a renewed authorization.

**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 |
| ----- | ---- | -------- | ----------- |
| `authorized_until` | string | yes |  |
| `fingerprint` | string | yes |  |
| `kid` | string | yes |  |
| `machine_id` | string (uuid) | yes |  |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A machine approved before re-authenticated and was approved again: the same id and grants, a renewed authorization.",
  "properties": {
    "authorized_until": {
      "type": "string"
    },
    "fingerprint": {
      "type": "string"
    },
    "kid": {
      "type": "string"
    },
    "machine_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "authorized_until",
    "fingerprint",
    "kid",
    "machine_id"
  ],
  "title": "MachineApprovalRenewed",
  "type": "object"
}
```

</details>

## `airdress.machine.approved`

Owner info Functions

A new machine was approved: it holds a key the airdress trusts and an authorization until `authorized_until`.

The owner sees every approval, including a shell host a person approved for themselves; that person is told by the shell host's own notice.

**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 |
| ----- | ---- | -------- | ----------- |
| `authorized_until` | string | yes |  |
| `fingerprint` | string | yes |  |
| `kid` | string | yes |  |
| `machine_id` | string (uuid) | yes |  |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A new machine was approved: it holds a key the airdress trusts and an authorization until `authorized_until`.\n\nThe owner sees every approval, including a shell host a person approved for themselves; that person is told by the shell host's own notice.",
  "properties": {
    "authorized_until": {
      "type": "string"
    },
    "fingerprint": {
      "type": "string"
    },
    "kid": {
      "type": "string"
    },
    "machine_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "authorized_until",
    "fingerprint",
    "kid",
    "machine_id"
  ],
  "title": "MachineApproved",
  "type": "object"
}
```

</details>

## `airdress.machine.authorization_changed`

Owner info Functions

The owner changed how long a machine stays authorized, or turned its expiry off.

**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 |
| ----- | ---- | -------- | ----------- |
| `authorized_until` | string | yes |  |
| `machine_id` | string (uuid) | yes |  |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "The owner changed how long a machine stays authorized, or turned its expiry off.",
  "properties": {
    "authorized_until": {
      "type": "string"
    },
    "machine_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "authorized_until",
    "machine_id"
  ],
  "title": "MachineAuthorizationChanged",
  "type": "object"
}
```

</details>

## `airdress.machine.denied`

Owner info Functions

A pending machine enrollment was denied by the owner.

Nothing is recorded but the fact: the user code and who denied it are in the journal line only.

**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**

It carries no fields.

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A pending machine enrollment was denied by the owner.\n\nNothing is recorded but the fact: the user code and who denied it are in the journal line only.",
  "title": "MachineDenied",
  "type": "object"
}
```

</details>

## `airdress.machine.discovery_advertised`

Owner info Functions

This operator is announcing itself on the local network: `origin` is the origin it proposes, `key` its operator key's fingerprint.

Emitted by `serve` when it starts the announcement, so the journal line keeps that module as its target.

**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 |
| ----- | ---- | -------- | ----------- |
| `key` | string | yes |  |
| `origin` | string | yes |  |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "This operator is announcing itself on the local network: `origin` is the origin it proposes, `key` its operator key's fingerprint.\n\nEmitted by `serve` when it starts the announcement, so the journal line keeps that module as its target.",
  "properties": {
    "key": {
      "type": "string"
    },
    "origin": {
      "type": "string"
    }
  },
  "required": [
    "key",
    "origin"
  ],
  "title": "MachineDiscoveryAdvertised",
  "type": "object"
}
```

</details>

## `airdress.machine.enrolled`

Owner info Functions

A machine of the apps role enrolled with a bootstrap and was issued its dispatch credential.

**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.136.

**Data**

| Field | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
| `machine` | string | yes |  |
| `machine_id` | string (uuid) | yes |  |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A machine of the apps role enrolled with a bootstrap and was issued its dispatch credential.",
  "properties": {
    "machine": {
      "type": "string"
    },
    "machine_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "machine",
    "machine_id"
  ],
  "title": "AppsMachineEnrolled",
  "type": "object"
}
```

</details>

## `airdress.machine.enrollment_requested`

Owner info Functions

A machine asked to enroll. It is not a machine of the airdress until the owner approves it by its fingerprint.

**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 |
| ----- | ---- | -------- | ----------- |
| `display_name` | string | yes | The name the machine gave itself. |
| `fingerprint` | string | yes | The `SHA256:` fingerprint of the machine's public key. |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A machine asked to enroll. It is not a machine of the airdress until the owner approves it by its fingerprint.",
  "properties": {
    "display_name": {
      "description": "The name the machine gave itself.",
      "type": "string"
    },
    "fingerprint": {
      "description": "The `SHA256:` fingerprint of the machine's public key.",
      "type": "string"
    }
  },
  "required": [
    "display_name",
    "fingerprint"
  ],
  "title": "MachineEnrollmentRequested",
  "type": "object"
}
```

</details>

## `airdress.machine.linked`

Owner info Functions

An approved machine was linked: the resource of its purpose (`kind`, `name`) was applied for it. A shell host is linked to `person`, who approved it.

**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 |
| ----- | ---- | -------- | ----------- |
| `kind` | string | yes |  |
| `machine_id` | string (uuid) | yes |  |
| `name` | string | yes |  |
| `person` | string or null | no | The person a shell host is linked to; absent for every other purpose. |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "An approved machine was linked: the resource of its purpose (`kind`, `name`) was applied for it. A shell host is linked to `person`, who approved it.",
  "properties": {
    "kind": {
      "type": "string"
    },
    "machine_id": {
      "format": "uuid",
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "person": {
      "description": "The person a shell host is linked to; absent for every other purpose.",
      "format": "uuid",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "kind",
    "machine_id",
    "name"
  ],
  "title": "MachineLinked",
  "type": "object"
}
```

</details>

## `airdress.machine.preauth_key.created`

Owner info Functions

A pre-auth key was minted: how many machines it may enroll, whether they are approved on redemption, how many grants they receive, and until when. The key's secret is never in the event.

**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 |
| ----- | ---- | -------- | ----------- |
| `expires_at` | string | yes |  |
| `grants` | integer (uint) | yes | How many grants an enrolled machine receives. |
| `key_id` | string (uuid) | yes |  |
| `max_uses` | integer (uint32) | yes |  |
| `pre_approved` | boolean | yes |  |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A pre-auth key was minted: how many machines it may enroll, whether they are approved on redemption, how many grants they receive, and until when. The key's secret is never in the event.",
  "properties": {
    "expires_at": {
      "type": "string"
    },
    "grants": {
      "description": "How many grants an enrolled machine receives.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "key_id": {
      "format": "uuid",
      "type": "string"
    },
    "max_uses": {
      "format": "uint32",
      "minimum": 0,
      "type": "integer"
    },
    "pre_approved": {
      "type": "boolean"
    }
  },
  "required": [
    "expires_at",
    "grants",
    "key_id",
    "max_uses",
    "pre_approved"
  ],
  "title": "PreauthKeyCreated",
  "type": "object"
}
```

</details>

## `airdress.machine.preauth_key.redeemed`

Owner info Functions

A machine enrolled with a pre-auth key; with a pre-approved key it is approved in the same step.

**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 |
| ----- | ---- | -------- | ----------- |
| `display_name` | string | yes |  |
| `fingerprint` | string | yes |  |
| `key_id` | string (uuid) | yes |  |
| `pre_approved` | boolean | yes |  |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A machine enrolled with a pre-auth key; with a pre-approved key it is approved in the same step.",
  "properties": {
    "display_name": {
      "type": "string"
    },
    "fingerprint": {
      "type": "string"
    },
    "key_id": {
      "format": "uuid",
      "type": "string"
    },
    "pre_approved": {
      "type": "boolean"
    }
  },
  "required": [
    "display_name",
    "fingerprint",
    "key_id",
    "pre_approved"
  ],
  "title": "PreauthKeyRedeemed",
  "type": "object"
}
```

</details>

## `airdress.machine.preauth_key.refused`

Owner info

A pre-auth key was refused: unknown, wrong, expired, revoked or used up. It names no key id, so nobody reading it can confirm that a guessed id exists. Anybody can cause one, so it is not on 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**

It carries no fields.

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A pre-auth key was refused: unknown, wrong, expired, revoked or used up. It names no key id, so nobody reading it can confirm that a guessed id exists. Anybody can cause one, so it is not on the bus.",
  "title": "PreauthKeyRefused",
  "type": "object"
}
```

</details>

## `airdress.machine.preauth_key.revoked`

Owner info Functions

A pre-auth key was revoked; it enrolls nothing more.

**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 |
| ----- | ---- | -------- | ----------- |
| `key_id` | string (uuid) | yes |  |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A pre-auth key was revoked; it enrolls nothing more.",
  "properties": {
    "key_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "key_id"
  ],
  "title": "PreauthKeyRevoked",
  "type": "object"
}
```

</details>

## `airdress.machine.reauth_requested`

Owner info Functions

A live machine asked to re-authenticate under its own 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 |
| ----- | ---- | -------- | ----------- |
| `fingerprint` | string | yes |  |
| `machine_id` | string (uuid) | yes |  |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A live machine asked to re-authenticate under its own key.",
  "properties": {
    "fingerprint": {
      "type": "string"
    },
    "machine_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "fingerprint",
    "machine_id"
  ],
  "title": "MachineReauthRequested",
  "type": "object"
}
```

</details>

## `airdress.machine.revoked`

Owner info Functions

A machine was revoked, with every key it held.

**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 |
| ----- | ---- | -------- | ----------- |
| `machine_id` | string (uuid) | yes |  |
| `revoked_kids` | array of string | yes | The key ids revoked with it. |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A machine was revoked, with every key it held.",
  "properties": {
    "machine_id": {
      "format": "uuid",
      "type": "string"
    },
    "revoked_kids": {
      "description": "The key ids revoked with it.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "machine_id",
    "revoked_kids"
  ],
  "title": "MachineRevoked",
  "type": "object"
}
```

</details>

## `airdress.machine.source_key.compromised`

Owner warn Functions

A source-signing key already revoked as rotated was reclassified as compromised: what it signed is quarantined from now on.

**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 |
| ----- | ---- | -------- | ----------- |
| `kid` | string | yes |  |
| `machine_id` | string (uuid) | yes |  |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A source-signing key already revoked as rotated was reclassified as compromised: what it signed is quarantined from now on.",
  "properties": {
    "kid": {
      "type": "string"
    },
    "machine_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "kid",
    "machine_id"
  ],
  "title": "MachineSourceKeyCompromised",
  "type": "object"
}
```

</details>

## `airdress.machine.source_key_added`

Owner info Functions

A machine's source-signing key was approved by its fingerprint; the key ids it rotated out, if any, are named.

**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 |
| ----- | ---- | -------- | ----------- |
| `fingerprint` | string | yes |  |
| `kid` | string | yes |  |
| `machine_id` | string (uuid) | yes |  |
| `rotated_out` | array of string | yes |  |

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

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "A machine's source-signing key was approved by its fingerprint; the key ids it rotated out, if any, are named.",
  "properties": {
    "fingerprint": {
      "type": "string"
    },
    "kid": {
      "type": "string"
    },
    "machine_id": {
      "format": "uuid",
      "type": "string"
    },
    "rotated_out": {
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "fingerprint",
    "kid",
    "machine_id",
    "rotated_out"
  ],
  "title": "MachineSourceKeyAdded",
  "type": "object"
}
```

</details>