# System Reference

This document describes the deployed Aeonora proof of concept as it exists today.

## System boundary

```text
owner browser
  plaintext Markdown + 24 words + passkey PRF
            |
            | AES-256-GCM ciphertext only
            v
Aeonora vault API ---------> Vercel Blob mutable pointer
            |
            +--------------> authenticated Kubo add
                                   |
                                   v
                              immutable IPFS CID

owner wallet
  signs Base Sepolia transactions
            |
            v
AeonoraRegistry
  agent ID + controller + commitments + CID + lifecycle
```

Plaintext exists in the authorized browser or CLI runtime. It is not intentionally sent to Vercel, Kubo, Cloudflare, or the EVM.

## Deployed components

| Component | Current implementation | Role | Trust or limitation |
|---|---|---|---|
| Landing, docs, vault UI | Vercel at `aeonora.net` | Browser interface | Deployment account can replace the client |
| Vault API | Vercel Function `/api/vault/` | Authenticated mutable sync | Vercel can delete or withhold the mutable pointer |
| Mutable storage | Vercel Blob | Latest encrypted envelope | Public ciphertext; authorization protects mutation |
| IPFS write service | `pin.aeonora.net` | Authenticated, size-limited Kubo adds | One VPS and one disk |
| IPFS gateway | `ipfs.aeonora.net/ipfs/<CID>` | Immutable encrypted reads | Availability depends on the current pin |
| Registry contract | `AeonoraRegistry.sol` | Identity, lineage, controller, lifecycle, receipts, brain pointer | Locally EVM-tested; no canonical public deployment or external audit |
| DNS and edge proxy | Cloudflare | DNS and TLS proxy | External operational dependency |

## Browser recovery and access

- The UI generates a 256-bit BIP-39 mnemonic displayed as 24 words.
- PBKDF2-SHA-256 runs for 600,000 iterations.
- `aeonora-vault-access/v1` derives the bearer capability.
- `aeonora-brain-encryption/v1` derives the AES key.
- The vault ID is the first 128 bits of SHA-256 over the encoded bearer token.
- A passkey wraps the recovery phrase with a WebAuthn PRF-derived AES-GCM key and stores that wrapped value in local browser storage.

The server cannot recover a lost phrase. Anyone with the phrase can derive both decryption and remote-access material.

## Vault API

The API accepts `aeonora-sync/v1` payloads up to 4 MiB with a monotonic version, commitment lineage, and an `aeonora-encrypted-brain/v1` envelope. Updates use Vercel Blob ETags. Conflicting writers receive HTTP 409.

| Method | Path | Result |
|---|---|---|
| `POST` | `/api/vault/` | Create a token-derived vault |
| `GET` | `/api/vault/?id=<vaultId>` | Read the encrypted latest version |
| `PUT` | `/api/vault/?id=<vaultId>` | Store the next encrypted version |
| `DELETE` | `/api/vault/?id=<vaultId>` | Delete the mutable hosted pointer |

Every request needs a bearer token of at least 32 bytes. Deleting the hosted pointer does not erase an already pinned IPFS snapshot.

## Portable CLI

`aeonora-portable` captures Markdown, creates a canonical encrypted bundle, registers a stable local identity, and wraps the brain key for an X25519 runtime key.

```text
init <brainDir> <runtimeId> [workspace]
restore <workspace> <outputDir>
migrate <workspace> <runtimeId> [outputDir]
verify <workspace>
push <workspace> [endpoint]
pull <workspace> [outputDir]
connect <workspace> <endpoint> <vaultId> <token>
```

Migration rotates the brain data key and preserves the local `agentId`. Remote sync cannot rewrap an independently changed brain into another workspace automatically; migration must occur through the owning workspace.

## Harness adapters

`aeonora-adapter` captures and installs supported Markdown surfaces. It does not move credentials, proprietary session databases, model state, or runtime processes.

| Adapter | Captured surfaces | Installed bridge |
|---|---|---|
| Hermes | `memories/`, `skills/`, `MEMORY.md`, `USER.md`, `SOUL.md`, `AGENTS.md`, `.hermes.md` | `AGENTS.md` |
| OpenClaw | `memory/`, `skills/`, `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md`, `TOOLS.md` | `AGENTS.md` |
| NanoClaw | supported Markdown under `groups/`, memory, and skills | `instructions.prepend.md` |
| OpenHands | `AGENTS.md` and documented skill or microagent directories | `AGENTS.md` |

Symlinks are skipped. Install copies the restored brain under `.aeonora/brain/` and adds one idempotent bridge instruction.

## Registry contract

`AeonoraRegistry` supports deterministic registration, constitution lineage, suspension, reactivation, deduplicated receipt commitments, two-step controller transfer, two-day delayed recovery, recovery cancellation, and versioned encrypted-brain pointers.

The chain proves transaction ordering and committed bytes. It does not prove that an agent acted truthfully or that an off-chain action succeeded.

## Failure behavior

| Failure | Expected result |
|---|---|
| Model or harness changes | Markdown can be restored into a supported adapter surface |
| Browser session closes | Phrase restores the vault; an enrolled passkey may unlock that device |
| Vercel object is deleted | A known pinned CID may still retrieve the encrypted snapshot |
| Current VPS disappears | IPFS retrieval can fail because only one independent pin exists |
| Recovery phrase is lost | Aeonora cannot decrypt or recover the vault |
| Recovery phrase is disclosed | Treat the vault as compromised |
| Old runtime copied plaintext | Rotation protects future snapshots but cannot erase copied data |

Related: [demo guide](demo-guide.md), [operations](operations.md), [protocol](protocol.md), and [security policy](../SECURITY.md).