linji.at / zds
atproto pds in zig
Star
Fork 0
Watch
zds docs invite-codes.md
3.2 kB
Markdown
at main

invite codes #

ZDS invite codes are modeled after the official PDS tables and XRPC surface. They are account-creation credentials, not sessions and not repo records.

shape #

  • com.atproto.server.describeServer reports whether account creation requires an invite through inviteCodeRequired.
  • com.atproto.server.createInviteCode creates one code with a configured useCount.
  • com.atproto.server.createInviteCodes creates batches of codes.
  • com.atproto.server.getAccountInviteCodes lists codes owned by the current account and their recorded uses.

Admin code creation requires Authorization: Bearer $ZDS_ADMIN_TOKEN, matching the official PDS admin-token boundary. Tranquil routes invite administration through its own infra/user store traits, but it is still privileged infrastructure behavior rather than normal account auth.

storage #

The official PDS stores invite metadata in invite_code and each redemption in invite_code_use. Availability is computed by comparing availableUses with the number of uses. ZDS follows that model:

  • invite_codes.available_uses is the total allowed redemptions.
  • invite_codes.disabled prevents future redemptions.
  • invite_codes.for_account records which account owns or was gifted the code.
  • invite_codes.created_by records who minted it.
  • invite_code_uses records each account that consumed a code.

Tranquil has the same conceptual model, but its PostgreSQL path decrements available_uses as part of consumption and also records the use. Both implementations treat disabled or exhausted codes as invalid.

behavior #

Invite codes do not expire in the official PDS, Tranquil, or ZDS. A code can be used more than once only when it was created with useCount > 1. Once the number of recorded uses reaches available_uses, createAccount returns InvalidInviteCode.

When ZDS_INVITE_REQUIRED=true, createAccount rejects missing, unknown, disabled, or exhausted invite codes. Account creation and invite use recording happen in the same SQLite transaction while the store lock is held, so racing requests cannot both consume a one-use code.

When invite-required mode starts against an empty database, ZDS creates one bootstrap code and logs it. After that, mint codes through the XRPC endpoint. For local admin operations, assume ZDS_ADMIN_TOKEN is set in the repo .env and source it before running the Just target:

set -a; . ./.env; set +a; just invite https://pds.zat.dev

For a multi-use code:

set -a; . ./.env; set +a; just invite https://pds.zat.dev 3

For a code assigned to a specific DID:

set -a; . ./.env; set +a; just invite https://pds.zat.dev 1 did:plc:...

reference notes #

  • The official PDS can periodically create account-owned invite codes when createAvailable=true and invite interval/epoch config is enabled.
  • ZDS supports bootstrap and admin-minted invite codes for gated onboarding. Routine interval-based account issuance is a separate policy surface.
  • PDS Gatekeeper is adjacent prior art for captcha, 2FA, and migration-only account creation at the boundary; those policies are separate from core invite-code accounting.