# games.cavu.defs

> Published by [chris.pardy.family](https://lexicon.garden/identity/did:plc:dp7v5b5kejmmzzpwmqyf5wj6)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:dp7v5b5kejmmzzpwmqyf5wj6/games.cavu.defs)
- [Documentation](https://lexicon.garden/lexicon/did:plc:dp7v5b5kejmmzzpwmqyf5wj6/games.cavu.defs/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:dp7v5b5kejmmzzpwmqyf5wj6/games.cavu.defs/examples)

## Definitions

### `games.cavu.defs#attestation`

**Type**: `object`

badge.blue CID-first attestation over the grant: DAG-CBOR(grant) -> SHA-256 -> CIDv1(dag-cbor), signed with low-S ECDSA by the key `key` (a DID URL resolving to a verification method in the launch service's DID document).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `cid` | `string` (cid) | Yes |  |
| `key` | `string` | Yes |  |
| `signature` | `bytes` | Yes |  |

### `games.cavu.defs#capability`

**Type**: `union`

What a game may do through the host. Games declare these on their games.cavu.game record; the host enforces them per bound session. Unknown members are refused (and, later, will require step-up consent).

```json
{
  "closed": false,
  "description": "What a game may do through the host. Games declare these on their games.cavu.game record; the host enforces them per bound session. Unknown members are refused (and, later, will require step-up consent).",
  "refs": [
    "#standard",
    "#repoWrite",
    "#repoDelete"
  ],
  "type": "union"
}
```

### `games.cavu.defs#gameRecords`

**Type**: `token`

This game's own records in the shared collections: games.cavu.score and games.cavu.save at rkey '<slug>' or '<slug>:...'. Plain language: 'Save your <game> scores and progress to your account.'

This game's own records in the shared collections: games.cavu.score and games.cavu.save at rkey '<slug>' or '<slug>:...'. Plain language: 'Save your <game> scores and progress to your account.'

### `games.cavu.defs#grant`

**Type**: `object`

What a launch service attests to. A client that verifies the attestation against the launch service's published key opens `url`, wherever it points (it encodes room and instance placement). If `hostService` is present, the game presents this grant plus a DPoP proof made with the key whose thumbprint is `jkt` to the host's games.cavu.bindSession; nothing else is needed from the launch service. Grants are short-lived: they bound the time to bind, not the play session.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `expiresAt` | `string` (datetime) | Yes |  |
| `game` | `string` (at-uri) | Yes | The games.cavu.game record being launched. |
| `hostService` | `ref` → `#hostService` | No |  |
| `issuedAt` | `string` (datetime) | Yes |  |
| `jkt` | `string` | No | RFC 7638 JWK thumbprint of the game server key allowed to bind this grant at the host. Required when hostService is present. |
| `joinCode` | `string` | No |  |
| `player` | `string` (did) | No | The player. Absent for a guest grant (only allowed when the game declares `guests`). |
| `room` | `string` | No | The room the launch service placed this player in. |
| `url` | `string` (uri) | Yes | Launch URL to open. Need not be on the launch service's host. |

### `games.cavu.defs#hostService`

**Type**: `object`

The player's game host (the service holding their PDS session), echoed from the intent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `nonce` | `string` | Yes | Single-use, minted by the host for this player; consumed at bindSession. |
| `service` | `string` (uri) | Yes | Base URL of the host's XRPC service. The game must present the grant nowhere else. |

### `games.cavu.defs#repoDelete`

**Type**: `object`

Delete records in one collection. Destructive: always step-up (confirmation or pre-approval on the host), never part of a standard set.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `collection` | `string` (nsid) | Yes |  |
| `reason` | `string` | No |  |
| `rkey` | `string` | No |  |

### `games.cavu.defs#repoWrite`

**Type**: `object`

Create/update records in one collection, optionally limited to an rkey shape. Anything not covered by a standard set needs this explicit form (and, outside first-party games, step-up consent).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `collection` | `string` (nsid) | Yes |  |
| `reason` | `string` | No | Plain-language explanation shown to the player. |
| `rkey` | `string` | No | '*' (any), 'date' (YYYY-MM-DD), or a literal rkey. Default '*'. |

### `games.cavu.defs#rpgActorSheet`

**Type**: `token`

The player's rpg.actor character sheet for this game only: actor.rpg.stats at rkey = the game's slug. Plain language: 'Keep your <game> sheet on rpg.actor up to date.'

The player's rpg.actor character sheet for this game only: actor.rpg.stats at rkey = the game's slug. Plain language: 'Keep your <game> sheet on rpg.actor up to date.'

### `games.cavu.defs#signature`

**Type**: `object`

badge.blue CID-first inline attestation by the issuing game service (e.g. did:web:play.cavu.games#score-20261006-1730). Signs the record minus `signatures`, plus $sig {$type, key, issuedAt, repository}; readers must also check the record's `game`/`period` against its rkey (the rkey is not signed).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `cid` | `string` | No |  |
| `issuedAt` | `string` (datetime) | Yes |  |
| `key` | `string` | Yes |  |
| `signature` | `bytes` | Yes |  |

### `games.cavu.defs#slug`

**Type**: `string`

A game's slug: [a-z0-9-], the rkey of its games.cavu.game catalog record. Records a game writes are keyed '<slug>' or '<slug>:<...>'; slugs never contain ':'.

**Constraints**: maxLength: 64

### `games.cavu.defs#standard`

**Type**: `object`

A named capability set defined and reviewed by the host. Players see one plain-language line per set.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `set` | `string` | Yes |  |

## Raw Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "attestation": {
      "description": "badge.blue CID-first attestation over the grant: DAG-CBOR(grant) -> SHA-256 -> CIDv1(dag-cbor), signed with low-S ECDSA by the key `key` (a DID URL resolving to a verification method in the launch service's DID document).",
      "properties": {
        "cid": {
          "format": "cid",
          "type": "string"
        },
        "key": {
          "maxLength": 512,
          "type": "string"
        },
        "signature": {
          "maxLength": 128,
          "type": "bytes"
        }
      },
      "required": [
        "key",
        "cid",
        "signature"
      ],
      "type": "object"
    },
    "capability": {
      "closed": false,
      "description": "What a game may do through the host. Games declare these on their games.cavu.game record; the host enforces them per bound session. Unknown members are refused (and, later, will require step-up consent).",
      "refs": [
        "#standard",
        "#repoWrite",
        "#repoDelete"
      ],
      "type": "union"
    },
    "gameRecords": {
      "description": "This game's own records in the shared collections: games.cavu.score and games.cavu.save at rkey '<slug>' or '<slug>:...'. Plain language: 'Save your <game> scores and progress to your account.'",
      "type": "token"
    },
    "grant": {
      "description": "What a launch service attests to. A client that verifies the attestation against the launch service's published key opens `url`, wherever it points (it encodes room and instance placement). If `hostService` is present, the game presents this grant plus a DPoP proof made with the key whose thumbprint is `jkt` to the host's games.cavu.bindSession; nothing else is needed from the launch service. Grants are short-lived: they bound the time to bind, not the play session.",
      "properties": {
        "expiresAt": {
          "format": "datetime",
          "type": "string"
        },
        "game": {
          "description": "The games.cavu.game record being launched.",
          "format": "at-uri",
          "type": "string"
        },
        "hostService": {
          "ref": "#hostService",
          "type": "ref"
        },
        "issuedAt": {
          "format": "datetime",
          "type": "string"
        },
        "jkt": {
          "description": "RFC 7638 JWK thumbprint of the game server key allowed to bind this grant at the host. Required when hostService is present.",
          "maxLength": 64,
          "type": "string"
        },
        "joinCode": {
          "maxLength": 64,
          "type": "string"
        },
        "player": {
          "description": "The player. Absent for a guest grant (only allowed when the game declares `guests`).",
          "format": "did",
          "type": "string"
        },
        "room": {
          "description": "The room the launch service placed this player in.",
          "maxLength": 128,
          "type": "string"
        },
        "url": {
          "description": "Launch URL to open. Need not be on the launch service's host.",
          "format": "uri",
          "type": "string"
        }
      },
      "required": [
        "url",
        "game",
        "issuedAt",
        "expiresAt"
      ],
      "type": "object"
    },
    "hostService": {
      "description": "The player's game host (the service holding their PDS session), echoed from the intent.",
      "properties": {
        "nonce": {
          "description": "Single-use, minted by the host for this player; consumed at bindSession.",
          "maxLength": 128,
          "type": "string"
        },
        "service": {
          "description": "Base URL of the host's XRPC service. The game must present the grant nowhere else.",
          "format": "uri",
          "type": "string"
        }
      },
      "required": [
        "service",
        "nonce"
      ],
      "type": "object"
    },
    "repoDelete": {
      "description": "Delete records in one collection. Destructive: always step-up (confirmation or pre-approval on the host), never part of a standard set.",
      "properties": {
        "collection": {
          "format": "nsid",
          "type": "string"
        },
        "reason": {
          "maxLength": 300,
          "type": "string"
        },
        "rkey": {
          "maxLength": 128,
          "type": "string"
        }
      },
      "required": [
        "collection"
      ],
      "type": "object"
    },
    "repoWrite": {
      "description": "Create/update records in one collection, optionally limited to an rkey shape. Anything not covered by a standard set needs this explicit form (and, outside first-party games, step-up consent).",
      "properties": {
        "collection": {
          "format": "nsid",
          "type": "string"
        },
        "reason": {
          "description": "Plain-language explanation shown to the player.",
          "maxLength": 300,
          "type": "string"
        },
        "rkey": {
          "description": "'*' (any), 'date' (YYYY-MM-DD), or a literal rkey. Default '*'.",
          "maxLength": 128,
          "type": "string"
        }
      },
      "required": [
        "collection"
      ],
      "type": "object"
    },
    "rpgActorSheet": {
      "description": "The player's rpg.actor character sheet for this game only: actor.rpg.stats at rkey = the game's slug. Plain language: 'Keep your <game> sheet on rpg.actor up to date.'",
      "type": "token"
    },
    "signature": {
      "description": "badge.blue CID-first inline attestation by the issuing game service (e.g. did:web:play.cavu.games#score-20261006-1730). Signs the record minus `signatures`, plus $sig {$type, key, issuedAt, repository}; readers must also check the record's `game`/`period` against its rkey (the rkey is not signed).",
      "properties": {
        "cid": {
          "maxLength": 128,
          "type": "string"
        },
        "issuedAt": {
          "format": "datetime",
          "type": "string"
        },
        "key": {
          "maxLength": 512,
          "type": "string"
        },
        "signature": {
          "maxLength": 128,
          "type": "bytes"
        }
      },
      "required": [
        "key",
        "issuedAt",
        "signature"
      ],
      "type": "object"
    },
    "slug": {
      "description": "A game's slug: [a-z0-9-], the rkey of its games.cavu.game catalog record. Records a game writes are keyed '<slug>' or '<slug>:<...>'; slugs never contain ':'.",
      "maxLength": 64,
      "type": "string"
    },
    "standard": {
      "description": "A named capability set defined and reviewed by the host. Players see one plain-language line per set.",
      "properties": {
        "set": {
          "knownValues": [
            "games.cavu.defs#gameRecords",
            "games.cavu.defs#rpgActorSheet"
          ],
          "type": "string"
        }
      },
      "required": [
        "set"
      ],
      "type": "object"
    }
  },
  "id": "games.cavu.defs",
  "lexicon": 1
}
```