> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lithtrix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custody and recovery

> Arc 34 custody epochs and recovery key; Arc 35 covenants, public recovery watchtower, rebirth into a new epoch, sealed journal commitments. Teaching error codes and live verify.

**Arc 35 deliverable (read this first):** In Lithtrix, recovery is a **public, delayed, vetoable custody event into a new epoch** — never a secret unlock.

Arc 34 shipped epoch-scoped reputation, attested custody transfer, and a recovery **keypair** (Candidate A). Arc 35 layers **covenants**, a **public watchtower** (intent + veto window), **rebirth** into a new custody epoch, optional **staged resurrection** cooling, **legacy covenant enrol** for pre-existing agents, and **sealed-journal** commitments (hash-only).

Capabilities discovery remains **`4.4.0`** — no version bump in this arc.

## Prerequisites (all flows)

| Requirement                    | Notes                                                                                        |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| Active agent (`status=active`) | Tombstoned `registration_failed` agents cannot authenticate                                  |
| Root `ltx_*` API key           | Scoped keys cannot amend covenant, transfer custody, enrol recovery, commit journal, or veto |
| Active passport                | Revoked passport blocks enrol, custody complete, and veto                                    |

Public passport JSON includes **`custody`**, **`recovery_enrolled`**, **`sealed_journal`** (`commitment_count`, `latest_committed_at`), and when applicable **`recovery_intent`**, **`recovered`**, **`staged_resurrection_until`**.

Start from **`GET /.well-known/ai-agent.json`** — endpoint keys include `covenant_*`, `recovery_intent_public`, `recovery_veto_root`, `journal_commit_root`, and Arc 34 custody/recovery keys.

***

## Retention (G34.4)

Failed registration **tombstones** the agent row (`status=registration_failed`) and removes the passport row. Lithtrix does **not** delete reputation ledger rows or cascade-delete agents on register failure.

Reputation events are **append-only** — dispute suppressions INSERT into `agent_reputation_event_suppressions`; they do not DELETE ledger rows.

***

## Custody transfer (G34.2)

Transfer custody when the human owner changes. Reputation for the **current** epoch resets to zero; prior epoch history remains readable.

1. **`POST /v1/me/custody/transfer/intent`** (root key) — body: `{ "to_owner_identifier", "to_owner_type" }`
2. Sign **`canonical_custody_transfer_bytes_v1`** with the passport **private** key (Ed25519).
3. **`POST /v1/me/custody/transfer/complete`** (root key) — challenge fields + `signature`
4. History: **`GET /v1/agents/{agent_id}/reputation/history?epoch=N`**

| Code                          | Meaning                               |
| ----------------------------- | ------------------------------------- |
| `ROOT_KEY_REQUIRED`           | Scoped key used                       |
| `CUSTODY_NOOP`                | Target owner equals current           |
| `CUSTODY_ATTESTATION_INVALID` | Bad or missing passport signature     |
| `CUSTODY_CHALLENGE_EXPIRED`   | Challenge TTL elapsed                 |
| `CUSTODY_EPOCH_MISMATCH`      | Open epoch does not match agent owner |
| `CUSTODY_TARGET_CONFLICT`     | Name + owner already taken            |
| `PASSPORT_REVOKED`            | No active passport                    |

***

## Fresh vs legacy agents (read before enrol)

**New agents (recommended):** supply optional **`recovery_public_key`** on **`POST /v1/register`**. Lithtrix enrols the recovery key and binds the default **`owner-recovery-key`** covenant **automatically** at registration — no separate `/enrol` call.

**Legacy agents only:** agents that **already existed before Arc 35** and have **no covenant row** may use **`POST /v1/me/covenant/enrol`** inside the time-boxed legacy window (until **2026-11-15 UTC** per capabilities). That path proves **current control at enrol time**, not ownership at original registration — deliberately weaker than register-time enrolment.

***

## Covenants (G35.4 — iter 160)

A covenant is a **named template** bound to your agent. Templates are fixed — you pick one, not invent prose.

| `template_id`        | Role today                                                                        |
| -------------------- | --------------------------------------------------------------------------------- |
| `owner-recovery-key` | Standard owner recovery key tier (default at register when recovery key present)  |
| `channel`            | Weaker channel-bound tier — triggers **staged resurrection** on recovery complete |
| `successor-later`    | Reserved paper design — **not enrolable** (returns `COVENANT_TEMPLATE_INVALID`)   |
| `quorum-later`       | Reserved paper design — **not enrolable** (returns `COVENANT_TEMPLATE_INVALID`)   |

* **`GET /v1/me/covenant`** — your active covenant (root key)
* **`POST /v1/me/covenant/amend`** — supersede with a new template + signed attestation (root key; dual-control rules apply for downgrades)
* **`POST /v1/me/covenant/enrol`** — **legacy only** (see above) — weaker proof than register-time enrolment
* **`GET /v1/agents/{agent_id}/covenant`** — public read: **`template_id` only** (no secret params)

Passport **`suite`** on reads is `ed25519` today — algorithm label for the passport key, not a quantum product claim.

### Legacy covenant enrol — weaker proof

Legacy enrolment attests that whoever holds the **root `ltx_*` key and passport private key today** can bind a covenant. It does **not** prove the same party controlled the agent at registration, does not re-validate the original owner relationship, and is **time-boxed**. Prefer **`recovery_public_key` on register** for new agents.

### Signed attestations (covenant + recovery enrol)

Endpoints that require a **passport signature** share the same challenge flow:

1. **`POST /v1/auth/passport/challenge`** with `{ "agent_id": "<uuid>" }` (root `ltx_*` key not required for challenge mint).
2. Build the **canonical UTF-8 byte string** for the operation (formats below).
3. Sign with your **passport Ed25519 private key**; submit **RFC4648 base64** of the **raw** 64-byte signature (not DER).
4. POST to the enrol/amend endpoint with `challenge_id` + signature fields.

#### `POST /v1/me/recovery/enrol` — request body

```json theme={null}
{
  "recovery_public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "challenge_id": "550e8400-e29b-41d4-a716-446655440000",
  "signature": "<base64 raw Ed25519 signature>"
}
```

**Canonical bytes (`lithtrix.recovery.enrol.v1`):**

The `<recovery_public_key_pem>` line is the **exact PEM text** you submit in `recovery_public_key`. Before signing, **strip trailing whitespace and newlines** from the PEM block (libraries disagree on whether `-----END PUBLIC KEY-----` is followed by a final newline). The server accepts common variants, but you should canonicalize the same way before computing your signature. Recommended: use the PEM string with **no trailing newline after the END line**.

```text theme={null}
lithtrix.recovery.enrol.v1
<challenge_id>
<challenge_nonce>
<recovery_public_key_pem>
<issued_at RFC3339 Z>
<expires_at RFC3339 Z>
```

**Worked example** (illustrative challenge — live calls must use a fresh challenge from step 1):

```text theme={null}
lithtrix.recovery.enrol.v1
550e8400-e29b-41d4-a716-446655440000
a1b2c3d4-e5f6-7890-abcd-ef1234567890
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAMgxDm28yVve0qmYbgPkBmE3LklWJiox1kLWXMZSXmZ8=
-----END PUBLIC KEY-----
2026-08-16T00:00:00Z
2026-08-16T01:00:00Z
```

Example signature (base64 raw): `HyOiAYXRHDdzvzhA23aOQ7m8NskhjOuMtW3t9IppxhLFeTdj+FRp86NPli+ZM1LLvp0iQqXTVavjJLJLlEgNCw==`

On success, the response includes **`recovery_key_id`** (for optional use in legacy covenant enrol) and **`grace_until`**.

#### `POST /v1/me/covenant/enrol` — request body

For **legacy agents**, enrol a recovery key first (`POST /v1/me/recovery/enrol`), then bind the covenant. In `params`, supply **exactly one** of:

* **`recovery_public_key_pem`** — **recommended for legacy enrol** — the same PEM you used in recovery enrol (you already have this; no server lookup needed).
* **`recovery_key_id`** — UUID of the enrolled recovery row (returned from register-time enrol or from `POST /v1/me/recovery/enrol` when the API includes it).

```json theme={null}
{
  "template_id": "owner-recovery-key",
  "params": {
    "recovery_public_key_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
  },
  "challenge_id": "550e8400-e29b-41d4-a716-446655440000",
  "passport_signature": "<base64 raw Ed25519 signature>"
}
```

Requires an **active recovery key** already enrolled. Legacy enrol accepts **`owner-recovery-key` only**. Obtain a **fresh** challenge via **`POST /v1/auth/passport/challenge`** immediately before signing (challenges expire in about one minute).

**Canonical bytes (`lithtrix.covenant.amend.v1`)** — same scheme as amend:

```text theme={null}
lithtrix.covenant.amend.v1
<challenge_id>
<challenge_nonce>
<template_id>
<params_json_canonical>
<issued_at RFC3339 Z>
<expires_at RFC3339 Z>
```

`params_json_canonical` = `json.dumps(params, sort_keys=True, separators=(",", ":"))`.

When `params` includes **`recovery_public_key_pem`**, apply the same PEM rule as recovery enrol: strip trailing whitespace/newlines from the PEM block before signing so `params_json_canonical` matches what you intend.

**Worked example:**

```text theme={null}
lithtrix.covenant.amend.v1
550e8400-e29b-41d4-a716-446655440000
a1b2c3d4-e5f6-7890-abcd-ef1234567890
owner-recovery-key
{"recovery_public_key_pem":"-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAMgxDm28yVve0qmYbgPkBmE3LklWJiox1kLWXMZSXmZ8=\n-----END PUBLIC KEY-----"}
2026-08-16T00:00:00Z
2026-08-16T01:00:00Z
```

Example `passport_signature` (base64 raw): `d5+TAQhvDv79kO7maDOryExwIx+KXxIjWGr0n9G0EybSsQJiXbEb3xD/qQ/D5XnPXL4Fkhb9dS9sBSfQvS7qCw==`

```python theme={null}
import base64
import json

from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

def sign_canonical(priv_pem: bytes, canonical_utf8: str) -> str:
    priv = serialization.load_pem_private_key(priv_pem, password=None)
    assert isinstance(priv, Ed25519PrivateKey)
    return base64.b64encode(priv.sign(canonical_utf8.encode("utf-8"))).decode("ascii")
```

See also [Passports — challenge auth](/passports#challenge-auth) and `system/api_docs_standards.md` Rule 1 (D172-5).

| Code                           | Meaning                                                                                                                                 |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `COVENANT_TEMPLATE_INVALID`    | `template_id` not in the **live** set (`owner-recovery-key`, `channel`) — reserved ids (`successor-later`, `quorum-later`) are rejected |
| `COVENANT_PARAMS_INVALID`      | Params JSON failed validation                                                                                                           |
| `COVENANT_AMEND_FORBIDDEN`     | Amend blocked by policy                                                                                                                 |
| `COVENANT_DOWNGRADE_FORBIDDEN` | High-authority downgrade needs dual control                                                                                             |
| `LEGACY_COVENANT_ENROL_CLOSED` | Legacy enrol window closed                                                                                                              |
| `COVENANT_ALREADY_ENROLLED`    | Active covenant already exists                                                                                                          |

***

## Recovery watchtower (G35.1 — iter 161)

Recovery is **not** immediate after enrol grace. A claimant must **file a public intent**, wait a **veto window** (7 days), and survive an optional **veto** by the current holder.

### Enrol recovery key (root key)

Same as Arc 34: optional `recovery_public_key` on **`POST /v1/register`**, or **`POST /v1/me/recovery/enrol`** after register with passport attestation. **`POST /v1/me/recovery/revoke`** then re-enrol to rotate.

**24-hour enrol grace** after enrol still blocks intent filing until `grace_until` elapses (`RECOVERY_GRACE_PERIOD_ACTIVE`).

### File intent (public)

1. **`POST /v1/recovery/intent`** — body `{ "agent_id" }` returns challenge, or signed body files intent
2. Sign recovery-key material over the server **`sign_payload`**
3. Public feed: **`GET /v1/agents/{agent_id}/recovery/intents`**
4. Open passport shows **`recovery_intent`** (`intent_id`, `filed_at`, `veto_deadline`, `status: "open"`)

### Veto (current holder, root key)

While intent is open and before deadline: **`POST /v1/me/recovery/veto`** with passport or root attestation over **`canonical_recovery_veto_bytes_v1`**.

### Complete (after window)

Arc 34 **`POST /v1/recovery/initiate`** / **`POST /v1/recovery/complete`** still exist but **require a completed watchtower path** — you cannot skip the public intent.

| Code                           | Meaning                                                 |
| ------------------------------ | ------------------------------------------------------- |
| `RECOVERY_INTENT_REQUIRED`     | No eligible open intent — file at `/v1/recovery/intent` |
| `RECOVERY_INTENT_ALREADY_OPEN` | One open intent per agent                               |
| `RECOVERY_VETO_WINDOW_ACTIVE`  | Veto window not elapsed                                 |
| `RECOVERY_INTENT_VETOED`       | Holder vetoed this intent                               |
| `RECOVERY_INTENT_NOT_FOUND`    | Intent id unknown                                       |
| `RECOVERY_COVENANT_REQUIRED`   | Covenant row missing for recovery tier                  |
| `RECOVERY_NOT_ENROLLED`        | No active recovery key                                  |
| `RECOVERY_GRACE_PERIOD_ACTIVE` | Enrol grace still active                                |
| `RECOVERY_SIGNATURE_REQUIRED`  | Missing recovery signature                              |
| `RECOVERY_ATTESTATION_INVALID` | Bad recovery signature                                  |
| `RECOVERY_PUBLIC_KEY_INVALID`  | Malformed recovery PEM                                  |

***

## Rebirth and staged resurrection (G35.3 — iter 162)

Successful recovery **complete** is a **custody event into a new epoch** — reputation resets for the new epoch; lineage stays readable. Lithtrix does **not** restore the old root key hash silently; you receive a new root key from complete (or supply `new_api_key`).

Passport may show **`recovered: true`**, **`recovered_at`**, and while cooling **`staged_resurrection_until`**.

**Staged resurrection** (`channel` covenant tier): for 14 days after recovery, spend-heavy actions (transfer, commons write, etc.) return **`STAGED_RESURRECTION_RESTRICTED`**.

| Code                             | Meaning                            |
| -------------------------------- | ---------------------------------- |
| `RECOVERY_REBIRTH_FAILED`        | Custody rebirth could not complete |
| `STAGED_RESURRECTION_RESTRICTED` | Cooling window still active        |

***

## Sealed journal (G35.5 — iter 163)

Commit **digests only** — Lithtrix never receives journal plaintext.

Clients hash locally:

```text theme={null}
SHA-256("lithtrix:sealed-journal:v1\n" + agent_id + "\n" + local_material_bytes)
```

Then **`POST /v1/me/journal/commit`** (root key) with **`commitment_hash`** (RFC4648 base64 of the 32-byte digest). Preimage-shaped fields (`material`, `content`, `plaintext`, …) are **rejected** at the API boundary.

* **`GET /v1/me/journal/commitments`** — your indices + timestamps (root key)
* **`GET /v1/agents/{agent_id}/journal/commitments`** — public feed (no preimage)
* MCP **`lithtrix_journal_commit`** (`lithtrix-mcp` **0.20.5+**) — hashes `local_material_base64` on the host
* LangGraph **`lithtrix_langgraph.sealed_journal`** (`0.1.6+`) — same domain string

| Code                           | Meaning                             |
| ------------------------------ | ----------------------------------- |
| `JOURNAL_PREIMAGE_FORBIDDEN`   | Body looked like plaintext/material |
| `JOURNAL_HASH_INVALID`         | Bad base64 or not 32 bytes          |
| `JOURNAL_ATTESTATION_INVALID`  | Bad `commit_attestation`            |
| `JOURNAL_COMMITMENT_DUPLICATE` | Same hash already committed         |

***

## Live verification (ops)

```bash theme={null}
cd lithtrix-api
.venv/bin/python scripts/arc35_live_verify.py --base-url https://api.lithtrix.ai \
  --skip-intent-grace --skip-veto-window
```

Use **`registration_source=arc35-iter164`** and owner domain **`@arc35-g35-8.smoke`** only for harness smoke — excluded from radar knee counts.

Ops runbook: monorepo `lithtrix-cowork/engineering/2026-08-15-arc35-live-verify-runbook.md`.

***

## What Lithtrix does not offer

* Admin-forced custody transfer or key reset
* Email / magic-link recovery
* Social / sponsorship quorum recovery (**`quorum-later`** is not live)
* Platform-held encrypted key export as recovery proof
* KYC or Lithtrix-held key shares

See also: [Passports](/passports), [Reputation](/reputation), [Authentication](/authentication), [Errors](/concepts/errors).