# zkwid.at (N): measured-workload keys and OAuth proxy, atproto-native

## Context

A hosted service H (e.g. a knotless CI runner) runs instances of a requester workload R: a shim plus stage2..N WASM. Each instance must act on behalf of user U with exactly the OAuth scopes U approved for that workload.

N (zkwid.at) is the service built here. It does four things:

1. For each workload record in U's repo, it hosts a dedicated OAuth client. U consents once per workload, and N stores the resulting session.
2. It creates `at.zkwid.key` (K) in U's repo only after a successful ZK exchange. H proves in RISC Zero that the measured shim (chain M) produced K's public key for N's challenge. U's workload record must list M and list H as an allowed host. H holds K's private key.
   - Only N can write K, using N's own OAuth client and its `repo:at.zkwid.key` scope.
   - Workload clients never get any `at.zkwid.*` scope, so workloads cannot mint keys.
3. It reverse-proxies XRPC calls from instances that sign service-auth JWTs with a K key, forwarding them through U's session within the workload's scopes.
4. Revocation is a record deletion. Deleting K revokes one instance; deleting the workload record revokes all of them.

Scope:

- H is a stub. U_ATRepo is a real `atproto-pds` from ../atproto-crates.
- Changes to knotless and socialweb-computer-kcp are documented as future work only, not built.
- ZK gates key creation only.
  - Backend: RISC Zero 3.0.x, using `RISC0_DEV_MODE` receipts in the devnet and real succinct receipts in production.
  - M is an ordered list of blob CIDs ("DICE-lite"). Full DICE is deferred.
- Code stays minimal: no comments, small crates, `at.zkwid.*` NSIDs only.
- Auth, OAuth, CIDs and keys all come from atproto-crates.

## Actors and identifiers

| Actor | Identifier | Dev host (via CONNECT proxy) |
|---|---|---|
| N | `did:web:zkwid.test`, service `#zkwid` | `zkwid.test` |
| H stub | `did:web:h.zkwid.test`, `#atproto` key | `h.zkwid.test` |
| U | did:plc from a fake PLC directory | account on `pds.zkwid.test` |
| Instance | `did:key:<K pub>`, self-certifying `iss` | none |

- Client ID: `https://zkwid.test/<handle>/<rkey>/oauth-client-metadata.json`.
- We use the path form. The spec allows any path. The subdomain form can exceed the 63-byte DNS label limit, and handles that already contain dashes make it ambiguous.
- If U's handle changes, the client ID changes. This is documented.

## Lexicons (`lexicons/at/zkwid/`)

- **`at.zkwid.workload`** (record, in U's repo, rkey `any`, used in the URL): `{ measurements: [{ name, wasm: blob }], scope: string, hosts: [did], createdAt }`. The PDS hosts the stage blobs.
- **`at.zkwid.key`** (record, in U's repo, written by N, rkey tid): `{ key: did:key, workload: strongRef, host: did, instance: string, createdAt, expiresAt }`.
- **`at.zkwid.createChallenge`** (procedure on N, caller H): input `{ repo, workload: strongRef }`, output `{ challenge }`.
  - The challenge is a stateless JWT signed by N's `#atproto` key: ES256, `typ: zkwid-challenge+jwt`, claims `{ iss: N, sub: H, repo: U, workload: { uri, cid }, exp: now + 300 s, jti }`.
  - N stores nothing for it.
- **`at.zkwid.createKey`** (procedure on N, caller H): input `{ challenge, instance, receipt: bytes }`, output `{ uri, cid, key }`.
  - The key and the measurements come from the receipt journal, never from caller fields.
  - K's rkey is `base32(sha256(challenge))`, so a reused challenge collides with the existing record. That makes it single-use, with U's repo as the only state.
  - Errors: `WorkloadNotFound`, `MeasurementMismatch`, `HostNotAllowed`, `InvalidReceipt`, `ChallengeInvalid`, `ChallengeUsed`, `NotAuthorized`.
- **Journal**, committed by the guest: `{ measurements: [cid], key: did:key, nonce: sha256(challenge), aud: did }`.
  - The guest measures every stage blob and runs the shim in wasmi.
  - The shim calls the guest import `keygen(seed)`, which derives a K256 key natively in the guest with the accelerated `k256` crate. The seed is a private witness held by H.
- **`at.zkwid.deleteKey`** (procedure on N, caller H): `{ uri }`.
- **`at.zkwid.demo.log`** (record): the demo workload writes this through the proxy.

## N behaviour

**Client metadata** at `GET /<handle>/<rkey>/oauth-client-metadata.json`:

- N resolves the handle to the DID and PDS, then fetches `at.zkwid.workload/<rkey>`.
- The document is a confidential web client with:
  - `scope = "atproto " + workload.scope`
  - N refuses to serve the document (404) if `workload.scope` names any `at.zkwid.*` resource
  - `private_key_jwt` with ES256 and an inline `jwks` holding a client key per workload, stored in the DB
  - `redirect_uris = [https://zkwid.test/<handle>/<rkey>/callback]`
  - `dpop_bound_access_tokens: true`
- It is served with status 200 and no redirect.

**OAuth flow:**

- `GET /<handle>/<rkey>/login` runs `atproto_oauth::workflow::oauth_init` (PAR, PKCE, DPoP).
- `GET /<handle>/<rkey>/callback` runs `oauth_complete_with_binding` and stores the session keyed by (U DID, rkey).
- Refresh goes through `atproto_oauth::refresh::RefreshCoordinator`, with an atomic swap in the store.

**N's own client** (`https://zkwid.test/oauth-client-metadata.json`):

- Scope is `atproto repo:at.zkwid.key`. U consents to it once, during onboarding.
- N stores this session per U. It is the only credential that ever writes or deletes K.

**`at.zkwid.createChallenge`:**

- Verify H's service auth (`lxm` = createChallenge).
- Fetch the workload by strongRef and check that `iss ∈ workload.hosts`.
- Mint the challenge JWT with `atproto_oauth::jwt::mint`. N stores nothing.

**`at.zkwid.createKey`:**

1. Run `atproto_xrpcs::verify_service_auth` with `iss` = H, `aud` = `did:web:zkwid.test#zkwid` and `lxm` = createKey. No jti cache is needed, because a replayed request hits the fixed rkey.
2. Verify the challenge JWT:
   - the signature is N's key;
   - `typ` is `zkwid-challenge+jwt`;
   - it has not expired;
   - `sub` equals the caller.
3. Fetch the workload record from the challenge's strongRef, requiring the CID to match. Check that `iss ∈ hosts` and that both N's own session and the workload session exist for U.
4. Run `receipt.verify(ZKWID_GUEST_ID)` and decode the journal. Require:
   - `journal.measurements == workload.measurements[*].wasm.ref`
   - `journal.nonce == sha256(challenge)`
   - `journal.aud == did:web:zkwid.test`
5. `createRecord` K at rkey `base32(sha256(challenge))` using N's own session. If the record already exists, return `ChallengeUsed`. Otherwise index `did:key` → K uri.
6. The verifier is built with `disable-dev-mode` unless the devnet flag `ZKWID_DEV_RECEIPTS=1` is set.

**Proxy** at `ANY /xrpc/<nsid>`, for anything that is not an `at.zkwid.*` method:

1. Verify the JWT with `verify_service_auth` through a resolver that synthesizes a document for `did:key` issuers and delegates everything else to `DidResolver`. Check `aud` = N, `lxm` = path NSID, jti not replayed.
2. Look up K from the `did:key` index, then `getRecord` both K and the workload live (30 s cache) to confirm neither was revoked.
3. Check scope with `atproto_oauth::scopes::ScopesSet`:
   - `allows_repo(collection, action)` for repo writes, reading the collection from the body.
   - `allows_rpc(lxm, aud)` for other calls, using `aud` from the `atproto-proxy` header.
   - Always deny `at.zkwid.key` and `at.zkwid.workload`.
4. Forward the call to U's PDS with `atproto_client` DPoP using the stored session.
   - Buffer the body so DPoP-nonce and refresh retries can resend it.
   - Return the status and body verbatim and strip forwarded headers. This follows the atproto-reverse-proxy pattern, but nothing is ported from its Go code.

**Store:** SQLite holding:

- per-workload client keys and sessions
- N's own sessions
- the `did:key` → K index
- the proxy jti cache

It holds no challenge state.

## Repo layout

```
Cargo.toml              workspace; path deps ../atproto-crates/crates/{atproto-oauth,atproto-xrpcs,atproto-identity,atproto-client,atproto-dasl,atproto-record,atproto-testkit}
lexicons/at/zkwid/      workload.json key.json createKey.json deleteKey.json demo/log.json
crates/zkwid/           lib: lexicon types, measure (compute_raw_cid), client-metadata builder, scope check, did:key resolver
crates/zkwid-n/         bin N: axum routes above + store.rs
crates/zkwid-zkvm/      risc0 methods crate (build.rs embed_methods) + guest/: measure stages, run shim in wasmi, keygen import, commit Journal
crates/zkwid-h/         stub H: did:web doc, seed, prove via zkwid-zkvm, createChallenge/createKey/deleteKey, instance runs stage2 in wasmi, proxy calls
crates/zkwid-dev/       devnet: FakePlcDirectory, spawns `pds`, local CA (rcgen) + CONNECT proxy, U account, seeds U_ATRepo, headless consent
stages/shim stages/stage2   wasm32 no_std; stage2 emits the demo.log record body
tests/e2e.rs            in crates/zkwid-dev: full flow + negatives
docs/future-work.md     knotless, socialweb-computer-kcp, ZK/DICE
```

## Dev network (mirrors atproto-crates/tools/conformance)

1. Start `FakePlcDirectory` and the `pds` binary (`--features clap`) with:
   - `PDS_HOSTNAME=pds.zkwid.test`
   - `PDS_TRUSTED_PROXY_HOPS=1`
   - `PDS_ALLOW_DEV_DEFAULTS`
   - non-production egress
2. Generate a CA and leaves with rcgen. Run a CONNECT proxy that maps `{zkwid,h.zkwid,pds.zkwid}.test:443` to loopback TLS terminators.
3. Every process gets `HTTPS_PROXY` and `SSL_CERT_FILE`. This requires Linux, as in the conformance harness.
4. Create U, upload the stage blobs, and write `at.zkwid.workload/demo`.
5. Approve consent headlessly through the PDS one-step JSON authorize POST.

## Waves of parallel subagents

Every wave ends with a gate: `cargo build --workspace && cargo test --workspace`, run by the coordinator (me). Agents work in separate crates, so they never edit the same files. The coordinator owns `Cargo.toml` and the lexicons.

- **Wave 0 (coordinator, serial).** Workspace skeleton, lexicon JSON, frozen interfaces in `crates/zkwid` (type and fn signatures, `todo!()` bodies), the `Devnet` struct API, N's route table, and env vars. Spike: build `pds` and boot it once.
- **Wave 1 (5 agents in parallel):**
  - A: `crates/zkwid` bodies and unit tests.
  - B: `crates/zkwid-dev` devnet: PLC, PDS, CA, proxy, account, seeding, both consents.
  - C: `stages/*` and the H stub core (did:web doc, seed, the native wasmi runner for stage2).
  - D: N OAuth (N's own client plus per-workload clients, metadata routes, login, callback, session store, refresh).
  - Z: `crates/zkwid-zkvm` guest and host prove fn, `Journal`, and a dev-mode round-trip test.
- **Wave 2 (3 agents in parallel):**
  - E: N `createChallenge`, `createKey` (receipt verify), and `deleteKey`.
  - F: N proxy (did:key JWT verify, live K check, scope check, forward).
  - G: H stub client calls (challenge, prove, createKey as H, instance JWT, proxy writes).
- **Wave 3 (2 agents in parallel):**
  - H: `tests/e2e.rs`, the full flow plus negatives.
  - I: `docs/future-work.md` and the README.
- **Wave 4 (coordinator):** `/code-review` and `/simplify` passes, then fixes.

Each agent brief contains its crate path, the frozen interfaces, the atproto-crates functions to reuse (listed above), the no-comments/minimal style rule, and its gate command.

## Verification

`cargo test -p zkwid-dev --test e2e` boots the devnet and asserts:

**Happy path:**

1. The metadata scope equals `atproto <workload.scope> repo:at.zkwid.key`.
2. After consent, N holds a session.
3. createKey from H puts K in U's repo.
4. The instance JWT is accepted, and the proxied `createRecord at.zkwid.demo.log` lands in U's repo.

**Negatives, each refused:**

- workload client metadata never contains `at.zkwid`, and a workload whose scope names `at.zkwid.key` gets a 404 for its metadata
- a proxied workload call that tries to create `at.zkwid.key` → 403, and none is created
- createKey with no receipt, a tampered journal, or a wrong ImageID → `InvalidReceipt`
- an expired, forged, or re-signed challenge, or one whose `sub` is another H → `ChallengeInvalid`
- a reused challenge, even with a fresh receipt → `ChallengeUsed`, leaving exactly one K for that challenge
- a journal key K created without any receipt cannot exist: every K maps to a verified receipt in N's log
- measurement mismatch → `MeasurementMismatch` and no K
- H not in hosts → `HostNotAllowed`
- K deleted → proxy 401
- workload deleted → 401
- out-of-scope collection → 403
- proxy write to `at.zkwid.key` → 403
- replayed jti → 401
- expired JWT → 401
- wrong `aud` → 401

## Future work (documented only)

- **knotless (H):**
  - The runner measures the workload stages, generates a per-run key, calls `at.zkwid.createKey` with its did:web service auth, passes N's URL and the key to the instance, and calls `deleteKey` when the run finishes.
  - The run identity is the `dev.knotless.check` at-uri, used as `instance`.
- **socialweb-computer-kcp:**
  - Accept `at.zkwid.key` as a signer-binding kind, in place of `badgeBlueKeys market_requester`. The RFP is then signed by the instance key.
  - Add a policy workflow that checks K → workload → measurements and hosts.
- **ZK / DICE:**
  - Real succinct receipts on a GPU or Boundless prover. Measure prove time.
  - A chain-head CDI.
  - Publish the receipt as a blob referenced from K, so third parties can audit it.
  - Note the limit: without a TEE, H knows the seed. The proof binds K to an execution of the measured shim and to N's challenge. It does not protect the key from H, which U already trusts.
- **Lexicon publishing:** a `_lexicon.zkwid.at` TXT record and `com.atproto.lexicon.schema` records.