agents #

ZDS is a Zig AT Protocol PDS. Start from the protocol, then cross-check against prior implementations.

references #

• specs: https://atproto.com/specs
• lexicon rules: https://atproto.com/specs/lexicon
• reference PDS: https://github.com/bluesky-social/atproto/tree/main/packages/pds
• Tranquil: https://tangled.org/tranquil.farm/tranquil-pds
• Pegasus: https://tangled.org/futur.blue/pegasus
• local notes: sibling notes repo
• protocol primitives: sibling zat.dev/zat repo

Use zat for primitives such as syntax, TIDs, DID/handle resolution, JWT, DAG-CBOR, CAR, MST, repo verification, OAuth helpers, and JSON path helpers. Do not edit zat from this repo unless explicitly asked.

module map #

• main, core: configuration, logging, syntax wrappers, process setup
• http: routing, request parsing, response helpers, CORS
• auth: passwords, app tokens, service auth
• atproto/server: account, session, service-auth XRPCs
• atproto/repo: repo read/write/import/blob XRPCs
• atproto/sync: sync reads, event stream, crawl requests
• atproto/oauth: OAuth metadata, PAR, authorization, token flow
• atproto/identity: DID credentials and PLC operations
• atproto/proxy: generic service proxying through atproto-proxy
• storage: SQLite state, repo commits, MST updates, blobstore metadata
• internal: ZDS-local utilities that keep feature code small; use this for reusable glue such as CLI parsing, sharded locks, passkey adapters, and JOSE compatibility helpers before deciding whether a primitive belongs in zat.
• bench, tools, justfile: local smoke tests, admin operations, and benchmark entry points. Prefer Just targets for repeatable workflows.

invariants #

• Repo writes preserve $type == collection, collection key rules, signed commits, MST updates, sync events, and crawler notification.
• Record bodies are decoded from repo blocks; the record index stores current CID and metadata, not canonical JSON content.
• Blob metadata is in SQLite; blob bytes live in the configured blobstore.
• Unknown lexicons can be accepted, but are not reported as validationStatus: "valid" without validation.
• Invite-required deployments must advertise inviteCodeRequired: true and consume invite codes during account creation.
• Passkeys are stored as account credentials: credential ID, public key, signature counter, friendly name, and timestamps. Password login remains available unless an explicit account policy changes that.
• App passwords are account-owned credentials. Management requires password auth, generated passwords are shown once, and revoking a credential revokes active sessions created with it.
• Password sessions are storage-backed token families. Accept session JWTs only when their JTI is active, and keep subject/actor/controller fields distinct in account-plane audit work.
• OAuth should follow the ATProto OAuth profile and JOSE behavior without relaxing stricter repo-signature verification semantics.
• Appview behavior belongs behind the generic proxy path, not in local Bluesky-specific route implementations.
• Browser-reported failures require browser request/response evidence.

checks #

Before committing code changes:

just test
just smoke
git diff --check
zig zen

Also run just smoke-permissioned when touching com.atproto.space.*, permissioned-data storage, or the /account/spaces resident view.

Use just invite for admin-minted invite codes. Assume ZDS_ADMIN_TOKEN is set in the repo .env; source it before running the target, for example set -a; . ./.env; set +a; just invite. Use just bench ... for local performance probes. Keep commits small. Amend only when asked. Do not revert user or sibling-repo changes unless asked.