# How to Operate the Aeonora Proof of Concept

This guide covers verification, deployment, IPFS checks, backup, and recovery for the current proof of concept.

## Prerequisites

- Node.js 22 or later and npm.
- Docker Compose for self-hosted IPFS.
- Vercel and Cloudflare access only when changing the hosted deployment.
- A funded wallet only when exercising a public-chain flow.

## Verify a checkout

```bash
npm install
npm run check:release
```

This runs local self-checks, end-to-end flows, Solidity compilation, the site build, the 10-check portability eval, and `npm audit`.

Run production checks separately. They create and clean up temporary encrypted vaults:

```bash
npm run check:production-security
npm run check:passkey
```

## Run the site locally

```bash
npm run build
python3 -m http.server 4173
```

Open `http://127.0.0.1:4173/site/`. Python serves static files only. Browser vault writes require a local Vercel development server or the production origin.

## Run the IPFS services

```bash
mkdir -p infra/ipfs/secrets
openssl rand -out infra/ipfs/secrets/pin-token -hex 32
chmod 600 infra/ipfs/secrets/pin-token
docker compose -f infra/ipfs/compose.yml up -d
curl -X POST http://127.0.0.1:5001/api/v0/id
```

Keep Kubo ports 5001 and 8080 bound to loopback. Expose only peer port 4001. Place `pin-api` behind HTTPS for authenticated remote writes.

Check production without exposing the token:

```bash
curl -fsS https://pin.aeonora.net/health
curl -I https://ipfs.aeonora.net/ipfs/<known-CID>
```

## Hosted configuration

| Variable | Meaning |
|---|---|
| `BLOB_READ_WRITE_TOKEN` | Vercel Blob access for mutable encrypted vaults |
| `IPFS_API_URL` | Authenticated pin endpoint, currently `https://pin.aeonora.net` |
| `IPFS_PIN_TOKEN` | Bearer token accepted by `pin-api` |

Never put these values in committed files, browser JavaScript, screenshots, support messages, or documentation.

## Deploy the web app

```bash
npm run check:release
vercel --prod
```

Then verify:

```bash
curl -fsS https://aeonora.net/ >/dev/null
curl -fsS 'https://aeonora.net/docs/?page=release-status' >/dev/null
npm run check:production-security
npm run check:passkey
```

## Exercise the registry locally

Start an EVM development node with an unlocked funded account, then run:

```bash
npm run compile:contracts
RPC_URL=http://127.0.0.1:8545 DEPLOYER=0xUnlockedDevelopmentAccount npm run deploy:rpc
npm run check:registry-recovery
```

Never use an unlocked production account. The browser app signs Base Sepolia transactions through the user's injected wallet.

## Backup and recovery

Back up user recovery phrases offline, CLI `.aeonora/` workspaces, the Kubo repository volume, and deployment configuration. Do not copy secret values into the repository.

Recovery order:

1. Restore the web deployment and vault API configuration.
2. Restore the Kubo volume or repin known CIDs from an independent copy.
3. Verify the pin health endpoint and one known CID.
4. Run both production E2E commands.
5. Confirm the domain and security headers.

With only the current IPFS node, loss of both the Vercel object and Kubo volume can make a vault unavailable even if its commitment remains on-chain.

## Release checklist

- `npm run check:release` passes.
- Production security and passkey E2Es pass.
- Documentation pages return HTTP 200.
- The pin service is healthy and a known CID is retrievable.
- No secret is tracked in Git.
- Public language says experimental, single-node, and unaudited.
- Any on-chain claim includes network, contract address, and explorer receipt.

Related: [release status](release-status.md), [system reference](system-reference.md), and [security review](security-audit-2026-07-19.md).