category: reference

tags:

- phase-2

- username

- routing

Added username field to the Users table and updated the resolver to route by `{username}.wikibot.io` instead of `{user_id}.wikibot.io`. Internal storage paths (EFS, wiki_id, ACL keys) remain UUID-based.

- Added `username` attribute (type S) to Users table

- Added `username-index` GSI (hash_key: `username`, projection: ALL)

- `RESERVED_USERNAMES` — 18 reserved names (admin, www, api, dev, mcp, wiki, etc.)

- `validate_username(username)` — lowercase alphanumeric + hyphens, 3-30 chars, no leading/trailing hyphens; returns `(valid, error)`

- `get_by_username(username)` — GSI query on `username-index`

- `set_username(user_id, username)` — validates format, checks reserved list, checks uniqueness via GSI, then updates

- `exchange_auth_code()` return dict now includes `needs_username: bool` (true when user has no username set)

- New endpoint: `POST /admin/username` with body `{"username": "..."}`

- Returns 200 on success, 400 for invalid/reserved, 409 for taken

- Normalizes input to lowercase before validation

- After `wikibot login`, if `needs_username` is true, prompts user for username and calls `POST /admin/username`

- `_set_username()` helper handles the API call and output

- `_parse_host()` now extracts username (not user_id) from subdomain — docstrings updated

- `__call__()` uses `get_by_username(username)` instead of `get(user_id)`

- Extracts `user_id` from the looked-up user record for downstream UUID-based paths

- 404 if username not found

- **Username validation**: valid formats, too short/long, leading/trailing hyphens, uppercase, special chars, reserved names, empty

- **GSI lookup**: `get_by_username` found and not found

- **set_username**: success, invalid format, reserved, duplicate, idempotent

- **POST /admin/username**: success, invalid, reserved, taken, unauthenticated, empty, case normalization

- **needs_username**: new user gets `true`, existing user with username gets `false`

- **Resolver**: all existing tests updated to use username subdomain; new test verifying UUID-based internal paths

All 230 runnable tests pass. 15 pre-existing `fastmcp` import failures unrelated.

Committed on `worktree-agent-a245f93f` (commit `8d37f26`), based on `phase-2`.