Custody and recovery

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.

POST /v1/me/custody/transfer/intent (root key) — body: { "to_owner_identifier", "to_owner_type" }
Sign canonical_custody_transfer_bytes_v1 with the passport private key (Ed25519).
POST /v1/me/custody/transfer/complete (root key) — challenge fields + signature
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:

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

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

{
  "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.

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):

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).

{
  "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:

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:

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

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

POST /v1/recovery/intent — body { "agent_id" } returns challenge, or signed body files intent
Sign recovery-key material over the server sign_payload
Public feed: GET /v1/agents/{agent_id}/recovery/intents
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:

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)

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, Reputation, Authentication, Errors.

Getting Started

API Reference

Concepts

Integrations

Custody and recovery

Prerequisites (all flows)

Retention (G34.4)

Custody transfer (G34.2)

Fresh vs legacy agents (read before enrol)

Covenants (G35.4 — iter 160)

Legacy covenant enrol — weaker proof

Signed attestations (covenant + recovery enrol)

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

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

Recovery watchtower (G35.1 — iter 161)

Enrol recovery key (root key)

File intent (public)

Veto (current holder, root key)

Complete (after window)

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

Sealed journal (G35.5 — iter 163)

Live verification (ops)

What Lithtrix does not offer

​Prerequisites (all flows)

​Retention (G34.4)

​Custody transfer (G34.2)

​Fresh vs legacy agents (read before enrol)

​Covenants (G35.4 — iter 160)

​Legacy covenant enrol — weaker proof

​Signed attestations (covenant + recovery enrol)

​POST /v1/me/recovery/enrol — request body

​POST /v1/me/covenant/enrol — request body

​Recovery watchtower (G35.1 — iter 161)

​Enrol recovery key (root key)

​File intent (public)

​Veto (current holder, root key)

​Complete (after window)

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

​Sealed journal (G35.5 — iter 163)

​Live verification (ops)

​What Lithtrix does not offer

Prerequisites (all flows)

Retention (G34.4)

Custody transfer (G34.2)

Fresh vs legacy agents (read before enrol)

Covenants (G35.4 — iter 160)

Legacy covenant enrol — weaker proof

Signed attestations (covenant + recovery enrol)

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

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

Recovery watchtower (G35.1 — iter 161)

Enrol recovery key (root key)

File intent (public)

Veto (current holder, root key)

Complete (after window)

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

Sealed journal (G35.5 — iter 163)

Live verification (ops)

What Lithtrix does not offer