A three-source conformance checker for AT Protocol Personal Data Servers (spec + lexicons + reference behavior). Pre-alpha.

Generator: extend to identity/admin/moderation/temp/label namespaces #1

Closed katsuricata.com
Closed opened by and assigned to katsuricata.com

The contract generator (src/generate.ts) currently walks repo, server, and sync (20 contract checks over the 51-endpoint PINNED_ENDPOINT_SET).

Extend NAMESPACES and EXAMPLE_INPUTS to cover identity, admin, moderation, temp, and label. Most endpoints should need only example values, as the generator mechanics are proven. Expect per-endpoint hint work: admin endpoints need an admin auth class, some endpoints will need skip reasons documented (lifecycle-shaped or out-of-band state).

Done when: pnpm generate emits checks for the new namespaces, stale-file cleanup removes superseded files, and pnpm tsx src/e2e.ts stays green.

Done. Landed in two commits on main (a5c6d02 harness, ef44426 generator), e2e green from the committed tree.

The generator now walks all eight com.atproto lexicon dirs, so the pinned set went 51 -> 85 endpoints and the contract checks 20 -> 38. Stale-file cleanup did its job along the way (it removed the updateAccountSigningKey check I'd briefly emitted before realizing that endpoint doesn't exist, see below).

The admin auth class was the one piece of real plumbing, as called out in the issue:

  • xrpc.ts gets configureAdminAuth(); a variant's auth: 'admin' resolves to a Basic admin:<password> header and fails closed when the run has no admin creds.
  • runner.ts skips requires.auth: 'admin' checks with admin-auth-unavailable rather than failing, since you can't admin a PDS you don't own.
  • cli.ts reads PDSUITE_ADMIN_PASSWORD; e2e.ts/oracle.ts use the TestPds hardcoded password so the admin checks actually run in e2e instead of skipping.

A few things the issue assumed would generate turned out not to exist in the reference PDS. Each got a documented skip rather than an unwinnable must:

  • identity.resolveDid, resolveIdentity, refreshIdentity and six of the seven temp endpoints have no registered route in the reference at all.
  • admin.updateAccountSigningKey was the trap: it's in the lexicon and even "responds" (400 InvalidToken), but that's the OAuth-proxy fallback for an unregistered route, not the endpoint. Skipped, with that noted in the hint.
  • admin.searchAccounts likewise. moderation.createReport and admin.sendEmail skip because they proxy to a mod service / mailer the dev oracle doesn't have (same 502/environmental class as sync.listHosts).

Two choices worth a look:

  • admin.deleteAccount generates, but its happy path targets the CAR fixture's did:example:pdsuite-import -- an account that was never provisioned -- so the destructive mutation harms no real user and alice's session survives for the checks after it. Same trick as importRepo.
  • Admin queries also get the no-auth-401 probe (normally it's mutations only). Rationale: account emails and invite codes must never answer unauthenticated, so a read leaking is as bad as a write going through. And missing-required probes send admin creds, since auth runs before validation and an unauthenticated probe would 401 where it means to see a 400.

pnpm e2e: 40 lexicon pass / 0 fail, endpoint inventory 85/85 on the oracle.

Sign up or Sign in to add to the discussion.