# Frozen interfaces

These contracts are shared by every crate. The function signatures in `crates/*/src` are authoritative. Change a signature only together with every caller, and record the change here.

## Hosts in the devnet

| Host | Serves | DID |
|---|---|---|
| `zkwid.test` | N (`zkwid-n`) | `did:web:zkwid.test`, service `#zkwid` of type `ZkwidService` |
| `h.zkwid.test` | H stub (`zkwid-h`) | `did:web:h.zkwid.test`, `#atproto` K256 key |
| `pds.zkwid.test`, `*.pds.zkwid.test` | `atproto-pds` binary | `did:web:pds.zkwid.test` |
| `plc.zkwid.test` | `atproto_testkit` fake PLC | none |

Every https request to these hosts goes through the devnet CONNECT proxy. Process env `HTTPS_PROXY` points at it, and `SSL_CERT_FILE` points at the devnet CA. Any `reqwest::Client` built after `Devnet::start` picks both up.

## Records

All in U's repo.

- `at.zkwid.workload/<rkey>` is `zkwid::lexicon::Workload`. `measurements[i].wasm` is a blob in U's PDS. `measurements[0]` is the shim, `[1..]` are stage2..N.
- `at.zkwid.key/<base32(sha256(challenge))>` is `zkwid::lexicon::Key`. It is written only by N through N's own OAuth session (client `store::N_CLIENT`).
- `at.zkwid.demo.log/<tid>` is `zkwid::lexicon::DemoLog`. The demo workload writes it through N's proxy.
- Reserved, defined in `zkwid::nsid::RESERVED`: `at.zkwid.key` and `at.zkwid.workload`.
  - A workload scope naming a reserved collection makes `client_scope` fail, so its metadata returns 404.
  - The proxy always refuses writes to reserved collections, and refuses every `at.zkwid.*` lxm.

Write records with a `$type` field, using `zkwid::lexicon::record(nsid, &value)`.

## N routes (`zkwid-n`)

| Route | Module |
|---|---|
| `GET /.well-known/did.json` | `did` |
| `GET /oauth-client-metadata.json`, `GET /login?handle=`, `GET /callback` | `oauth` (N's own client, scope `atproto repo:at.zkwid.key`) |
| `GET /{handle}/{rkey}/oauth-client-metadata.json`, `GET /{handle}/{rkey}/login`, `GET /{handle}/{rkey}/callback` | `oauth` (per-workload client, scope `zkwid::scope::client_scope(workload.scope)`) |
| `POST /xrpc/at.zkwid.createChallenge`, `POST /xrpc/at.zkwid.createKey`, `POST /xrpc/at.zkwid.deleteKey` | `keys` |
| `ANY /xrpc/{nsid}` (fallback, not `at.zkwid.*`) | `proxy` |

Login routes answer `302` to the PDS authorize URL. The callback answers `200` with JSON `{ "did": ..., "client": ... }`.

XRPC errors use `{ "error": Name, "message": text }` with status:

- `400` for `InvalidRequest`, `MeasurementMismatch`, `InvalidReceipt`, `ChallengeInvalid`, `ChallengeUsed`
- `401` for `AuthRequired` / `InvalidToken`
- `403` for `HostNotAllowed`, `NotAuthorized`, `ScopeMissing`
- `404` for `WorkloadNotFound`, `KeyNotFound`

## Store keys

- `Store::client_key(client_id_url)` gets or creates a P-256 client assertion key per OAuth client_id.
- `Session.client` is the workload rkey, or `store::N_CLIENT` (`""`) for N's own client.
- Sessions are keyed by (did, client).
- `Store::put_request(state, json)` stores a serialized `atproto_oauth::workflow::OAuthRequest`, together with the client string and the client_id.

## H helpers

- `zkwid_h::stage_bytes(name)` runs `cargo build --release --target wasm32-unknown-unknown` for `stages/<name>` and returns the wasm bytes.
- `zkwid_h::run_stage(wasm, input)` runs a stage natively in wasmi 0.31, providing the same `env.keygen` import the guest does.

## Service auth

- **H calls N:** `atproto_xrpcs::mint_service_auth(h_key, "did:web:h.zkwid.test", "did:web:zkwid.test#zkwid", lxm, 60 s)`.
- **Instance calls the proxy:** the same call with `iss = <instance did:key>`, signed by the instance K256 private key (`KeyData::new(K256Private, seed)`).
  - `lxm` is the proxied NSID.
  - An `atproto-proxy` header is optional.
- **N verifies:** `atproto_xrpcs::verify_service_auth` with `zkwid::resolver::DidKeyResolver { inner: DidResolver }`.
  - The policy is `ServiceAuthPolicy::new(lxm, "did:web:zkwid.test#zkwid")`.
  - The proxy also rejects any jti already in `Store::seen_jti`.

## Challenge

- `zkwid::challenge::mint(n_key, "did:web:zkwid.test", sub = H, repo = U, workload, 300 s)` produces an ES256 JWT with header `typ: zkwid-challenge+jwt`. Its claims are `Challenge`.
- `nonce(token)` is `sha256(token)`.
- `rkey(token)` is `base32-lower-nopad(sha256(token))`.

## ZK (`zkwid-zkvm`)

- `ProveInput { stages, seed, nonce: challenge::nonce(token), aud: "did:web:zkwid.test" }` goes to `prove`, which returns `bincode(Receipt)`.
- N calls `verify(receipt)`, which checks `receipt.verify(image_id())` and returns `Journal`.
- `Journal.key` is the 33-byte compressed K256 public key, `KeyData::new(K256Public, key)`. Its did:key is `KeyData`'s `Display`.
- `Journal.measurements[i]` is `sha256(stages[i])`. It equals `zkwid::measure::cid_digest(workload.measurements[i].wasm.ref.$link)`.
- Dev mode: `RISC0_DEV_MODE=1` makes fake receipts.
- The `zkwid-n/prod` feature enables `zkwid-zkvm/disable-dev-mode`, which enables `risc0-zkvm/disable-dev-mode`.
- wasmi is pinned to 0.31 in both the guest and H.

## Stage ABI (`stages/*`, wasm32-unknown-unknown, no_std)

- **Exports:**
  - `memory`
  - `input_ptr() -> i32`
  - `output_ptr() -> i32`
  - `run(len: i32) -> i32` (returns the output length; a trap means failure)
- **Imports:** module `env`, `keygen(seed_ptr: i32, out_ptr: i32) -> i32`. It reads 32 bytes and writes a 33-byte compressed K256 public key, returning 33.
- **Shim:** the input is a 32-byte seed. It calls `keygen` and outputs the 33-byte public key.
- **Stage2:** the input is JSON `{ "instance": s, "createdAt": t }`. The output is the JSON body of an `at.zkwid.demo.log` record, `{ "$type": "at.zkwid.demo.log", "text": "hello from <instance>", "createdAt": t }`.
- **Build:** `cargo build --release --target wasm32-unknown-unknown --manifest-path stages/<name>/Cargo.toml`. The output is `stages/<name>/target/wasm32-unknown-unknown/release/<name>.wasm`.