feat(backend): username validation, search/suggestion endpoints and registry indices

Implements the username/auth slice across four issues.

#560 — Sync src/db/schema.sql with the privy_did / privy_linked_at columns
(the reference schema had drifted from the applied migrations) and add a
migration that re-states the Privy identity schema idempotently, so it
applies on a database where the columns were added out of band. Ships
rollback scripts under migrations/rollback/.

#541 — Add a unique index on LOWER(username) so the registry is
case-insensitively unique at the database level, plus a text_pattern_ops
index over the same expression to serve prefix lookups.

#545 — Add validate_username / validate_username_prefix helpers (lowercase
ASCII alphanumeric, 3-15 chars) with unit tests, and reject malformed input
in the resolve and suggestion handlers before it reaches Redis or Postgres.

#540 — Add GET /api/users/suggestions, a paginated username autocomplete
returning profile avatars and a total match count. Harden GET /api/users/search:
escape LIKE metacharacters (a `q` of `%` previously matched every row), match
usernames case-insensitively via the new index, and clamp limit/offset. Its
response stays a bare array so the dashboard and mobile app are unaffected.

Closes #540
Closes #541
Closes #545
Closes #560

Author: Divine-designs

backend/docs/openapi.yaml

@@ -153,6 +153,27 @@ components:
           type: string
           nullable: true
 
+    UserSuggestionsResponse:
+      type: object
+      properties:
+        query:
+          type: string
+          description: The normalised (lowercased, trimmed) prefix that was matched.
+        results:
+          type: array
+          items:
+            $ref: '#/components/schemas/SearchUser'
+        limit:
+          type: integer
+        offset:
+          type: integer
+        total:
+          type: integer
+          format: int64
+          description: Total matches for the prefix, ignoring limit/offset.
+        has_more:
+          type: boolean
+
     FriendUser:
       type: object
       properties:
@@ -695,9 +716,31 @@ paths:
         - name: q
           in: query
           required: true
-          description: Search term matched against username and address (ILIKE)
+          description: >-
+            Prefix matched case-insensitively against username, and
+            case-sensitively against address. LIKE metacharacters are escaped
+            and matched literally.
           schema:
             type: string
+            minLength: 1
+            maxLength: 64
+        - name: limit
+          in: query
+          required: false
+          description: Page size, clamped to 1-50.
+          schema:
+            type: integer
+            default: 20
+            minimum: 1
+            maximum: 50
+        - name: offset
+          in: query
+          required: false
+          description: Rows to skip; negative values are clamped to 0.
+          schema:
+            type: integer
+            default: 0
+            minimum: 0
       responses:
         '200':
           description: Matching users
@@ -707,6 +750,74 @@ paths:
                 type: array
                 items:
                   $ref: '#/components/schemas/SearchUser'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          description: Missing or invalid JWT
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /api/users/suggestions:
+    get:
+      tags:
+        - Users
+      summary: Username autocomplete suggestions (paginated)
+      description: >-
+        Username-only prefix search for autocomplete. Unlike /api/users/search
+        this validates `q` as a username prefix (lowercase alphanumeric, at most
+        15 characters) and returns a paginated envelope with the total number of
+        matches alongside each profile's avatar.
+      operationId: suggestUsernames
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: q
+          in: query
+          required: true
+          description: >-
+            Username prefix. Lowercased before matching; rejected with 400 if it
+            is empty, longer than 15 characters, or contains anything other than
+            lowercase letters and digits.
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 15
+        - name: limit
+          in: query
+          required: false
+          description: Page size, clamped to 1-25.
+          schema:
+            type: integer
+            default: 10
+            minimum: 1
+            maximum: 25
+        - name: offset
+          in: query
+          required: false
+          description: Rows to skip; negative values are clamped to 0.
+          schema:
+            type: integer
+            default: 0
+            minimum: 0
+      responses:
+        '200':
+          description: Paginated username suggestions
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserSuggestionsResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           description: Missing or invalid JWT
           content:

backend/migrations/20260729000000_privy_did_auth_metadata.sql

@@ -0,0 +1,33 @@
+-- #560: store the Privy DID and auth metadata on user profile records.
+--
+-- 20260726000001_privy_identity.sql introduced privy_did / privy_linked_at
+-- with a bare `ALTER TABLE ... ADD COLUMN`, which aborts if either column is
+-- already present. This migration re-states the same end state idempotently so
+-- it applies cleanly on a database where the columns were added out of band,
+-- and ships a matching rollback script under migrations/rollback/.
+
+ALTER TABLE users ADD COLUMN IF NOT EXISTS privy_did VARCHAR(255);
+ALTER TABLE users ADD COLUMN IF NOT EXISTS privy_linked_at TIMESTAMP;
+
+-- Nullable UNIQUE: a Privy DID maps to at most one account, but an account may
+-- exist without a linked DID. `ADD CONSTRAINT` has no IF NOT EXISTS form, so
+-- the catalog is checked first.
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1
+        FROM pg_constraint
+        WHERE conrelid = 'users'::regclass
+          AND contype = 'u'
+          AND conname = 'users_privy_did_key'
+    ) THEN
+        ALTER TABLE users ADD CONSTRAINT users_privy_did_key UNIQUE (privy_did);
+    END IF;
+END
+$$;
+
+-- Lookup path for `SELECT address FROM users WHERE privy_did = $1` in
+-- api::auth::privy_auth. Partial, so the rows with no linked DID stay out of it.
+CREATE INDEX IF NOT EXISTS idx_users_privy_did
+    ON users (privy_did)
+    WHERE privy_did IS NOT NULL;

backend/migrations/20260729000001_username_indices.sql

@@ -0,0 +1,14 @@
+-- #541: index username mappings and enforce DB-level registration uniqueness.
+
+-- users.username already carries a plain UNIQUE constraint, but that constraint
+-- is case-sensitive: `Ebube` and `ebube` can both register and then resolve to
+-- different accounts. This makes the registry case-insensitively unique at the
+-- database level, so a racing pair of registrations cannot both commit.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_users_username_lower
+    ON users (LOWER(username));
+
+-- Prefix lookup for the search/suggestion endpoints (`LIKE 'ebu%'`). A btree in
+-- the default collation cannot serve LIKE, so the prefix path gets its own
+-- text_pattern_ops index over the same lowercased expression.
+CREATE INDEX IF NOT EXISTS idx_users_username_lower_pattern
+    ON users (LOWER(username) text_pattern_ops);

backend/migrations/rollback/20260729000000_privy_did_auth_metadata.down.sql

@@ -0,0 +1,16 @@
+-- Rollback for 20260729000000_privy_did_auth_metadata.sql (#560).
+--
+-- Dropping the columns is destructive: every linked Privy identity is lost and
+-- users have to re-link. Only the index and constraint are dropped here, which
+-- returns the schema to its pre-#560 shape without discarding data.
+--
+-- To also remove the columns (and the identity data with them), uncomment the
+-- ALTER TABLE at the bottom.
+
+DROP INDEX IF EXISTS idx_users_privy_did;
+
+ALTER TABLE users DROP CONSTRAINT IF EXISTS users_privy_did_key;
+
+-- ALTER TABLE users
+--     DROP COLUMN IF EXISTS privy_did,
+--     DROP COLUMN IF EXISTS privy_linked_at;

backend/migrations/rollback/20260729000001_username_indices.down.sql

@@ -0,0 +1,8 @@
+-- Rollback for 20260729000001_username_indices.sql (#541).
+--
+-- Non-destructive: these are indices only, no user data is touched. Dropping
+-- idx_users_username_lower gives up case-insensitive registration uniqueness,
+-- so `Ebube` and `ebube` become registerable as separate accounts again.
+
+DROP INDEX IF EXISTS idx_users_username_lower_pattern;
+DROP INDEX IF EXISTS idx_users_username_lower;

backend/migrations/rollback/README.md

@@ -0,0 +1,18 @@
+# Rollback scripts
+
+One `<version>_<name>.down.sql` per reversible migration in `backend/migrations/`.
+
+These are **manual**. sqlx's migrator only walks files at the top level of
+`migrations/`, so this directory is invisible to `sqlx migrate run` and to the
+`sqlx::migrate!()` bootstrap in `src/db/mod.rs` — adding a script here cannot
+change what a deploy applies.
+
+To roll a migration back, apply its script and then delete the bookkeeping row
+so the migrator will re-apply the migration on the next run:
+
+```sh
+psql "$DATABASE_URL" -f migrations/rollback/<version>_<name>.down.sql
+psql "$DATABASE_URL" -c "DELETE FROM _sqlx_migrations WHERE version = <version>;"
+```
+
+Roll back newest-first; the scripts are not written to be applied out of order.

backend/src/api/mod.rs

@@ -71,6 +71,7 @@ pub fn user_routes_with_state(state: user::UserState) -> Router {
             get(user::get_profile).post(user::update_profile),
         )
         .route("/search", get(user::search_users))
+        .route("/suggestions", get(user::suggest_usernames))
         .route("/friends", get(user::list_friends))
         .route("/friends/request", post(user::send_friend_request))
         .route("/friends/:id/accept", post(user::accept_friend_request))