feat: DB-backed user management, admin secrets provisioning, and multi-tenant isolation

[ilblackdragon]

Summary

Complete multi-tenant user management system replacing static env-var tokens with DB-backed authentication, admin APIs, per-user secrets provisioning, and role-based access control.

DB-Backed User Management

• UserStore trait with dual-backend support (PostgreSQL + libSQL) — users, api_tokens tables with full CRUD
• CombinedAuthState — env-var tokens checked first, then DB-backed tokens via DbAuthenticator with bounded LRU cache (1024 entries, 60s TTL)
• Startup migration — automatically imports the single-user env-var token as the first admin user when DB is empty
• Token security — SHA-256 hashed at rest, plaintext returned exactly once at creation

Admin API (role-gated)

• POST/GET /api/admin/users — create and list users
• GET/PATCH/DELETE /api/admin/users/{id} — get, update, delete individual users
• POST /api/admin/users/{id}/suspend and /activate — user lifecycle
• GET /api/admin/usage — per-user LLM usage stats (filterable by user and period)

Admin Secrets Provisioning

• PUT /api/admin/users/{user_id}/secrets/{name} — create/update per-user secrets (AES-256-GCM encrypted)
• GET /api/admin/users/{user_id}/secrets — list secrets (names only, never values)
• DELETE /api/admin/users/{user_id}/secrets/{name} — delete secrets
• Use case: Application backend provisions callback tokens per user so each user's IronClaw agent can authenticate back to the app

Self-Service Endpoints

• GET/PATCH /api/profile — users view/edit their own profile
• POST/GET /api/tokens, DELETE /api/tokens/{id} — users manage their own API tokens
• Admins can create tokens for other users via optional user_id field

Role-Based Access Control

• Two roles: admin (full access) and member (self-service only)
• AdminUser axum extractor returns 403 for non-admin tokens
• All /api/admin/* endpoints require admin role

Multi-Tenant Isolation (from #1614)

• TenantCtx for compile-time tenant scoping
• Per-user budgets, model selection, heartbeat cycling
• User-scoped webhook endpoints
• Per-user workspace pool with configurable read scopes

Web UI

• Users admin tab (under Settings) with create, suspend, activate, delete
• Token display on user creation (shown once)
• CSP-compliant event delegation for action buttons

Review Feedback Addressed

• Bounded LRU cache — replaced HashMap with lru::LruCache so token cache can't grow unbounded
• Admin auth on all admin endpoints — list, detail, update, suspend, activate all gated with AdminUser
• libSQL FK cascade gap — delete_user() explicitly cleans up api_tokens (no FK cascade in libSQL)
• User ID collisions — switched from display-name derivation to Uuid::new_v4()
• libSQL query alignment — get_invitation_by_hash now checks status + expiry like PostgreSQL
• Sort order consistency — both backends use ORDER BY created_at DESC

Documentation

• docs/USER_MANAGEMENT_API.md — full API spec with request/response examples, error codes, security model, and database schema

Key Commits

Commit	Description
80cee7d	UserStore trait + dual-backend migrations
27c43e1	DB-backed auth, user/token API handlers
29e9aeb	Role-based access control (admin/member)
aa35c2e	Remove GATEWAY_USER_TOKENS, address initial review
ffe872f	User deletion, self-service profile, usage API
8f1e0df	TenantCtx for compile-time tenant isolation
4006ba2	Review feedback — LRU cache, admin auth, FK cleanup
5692fcd	Admin secrets provisioning API + documentation

Test plan

• cargo clippy --all --all-features — zero warnings
• cargo fmt -- --check — clean
• scripts/check_no_panics.py — no panics in production code
• Unit tests: admin role enforcement (403 for members, pass for admins)
• Unit tests: LRU cache bounded at capacity
• Unit tests: delete_user removes api_tokens on libSQL
• Integration tests: full user lifecycle (create → token → auth → suspend → delete)
• Manual: verify admin secrets provisioning end-to-end with a real secrets backend

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the gateway's security and flexibility by moving user and API token management from static environment variables to a robust, database-backed system. This change enables dynamic user registration, fine-grained control over API tokens, and a structured invitation process, laying the groundwork for multi-tenant deployments and improved administrative capabilities. The new architecture ensures that authentication is both efficient and scalable, with a clear path for migrating existing configurations.

Highlights

• Database-backed User Management: Implemented a comprehensive DB-backed user management system, replacing static environment variables for user tokens with dynamic runtime user creation, API token management, and an invitation flow.
• New Database Schema: Introduced new database tables: users for user profiles, api_tokens for managing API keys, and invitations for user registration via invite links. This includes PostgreSQL migration V14 and LibSQL schema updates.
• Authentication Refactor: Refactored the authentication mechanism to use CombinedAuthState, which prioritizes existing environment variable tokens and falls back to a new DbAuthenticator with an in-memory LRU cache for database-backed tokens.
• New API Endpoints: Added 12 new API endpoints under /api/admin/users, /api/tokens, and /api/invitations for creating, listing, updating, suspending/activating users, creating/listing/revoking API tokens, and creating/listing/accepting invitations.
• Startup Migration for Existing Users: Implemented a startup migration process that automatically imports users defined in the GATEWAY_USER_TOKENS environment variable into the database if the user table is empty, ensuring a smooth transition to DB-backed authentication.
• Extensive Integration Tests: Included 10 new integration tests to cover the full lifecycle of user, token, and invitation management, ensuring robustness and correctness of the new features.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive multi-tenant user management system, replacing static environment variable tokens with database-backed user registration, API token management, and an invitation flow. New database tables for users, API tokens, and invitations have been added, along with corresponding API handlers for creating, listing, updating, suspending, and activating users, as well as managing API tokens and invitations. The authentication middleware has been updated to support both existing environment variable tokens and the new database-backed tokens, with a migration path for existing env-var users. However, there are a few areas for improvement: the DbAuthenticator's cache eviction logic is flawed and can lead to unbounded memory growth, the let-chain syntax used in auth.rs might violate the project's MSRV, and the user ID generation logic from display names is fragile and prone to collisions or invalid IDs.

[gemini-code-assist]

The cache eviction logic is flawed and can lead to uncontrolled memory growth. The logic only triggers when the cache is full, and it only removes entries that have expired. If the cache becomes full of entries that are not yet expired, no eviction will occur, and the cache size will grow beyond MAX_CACHE_ENTRIES.

Additionally, the comment on line 125 describes this as an "LRU cache", but the implementation is a HashMap with time-based eviction, which is misleading.

To fix this, I recommend using a proper LRU cache implementation, such as the lru crate. This would provide correct LRU semantics, prevent unbounded memory growth, and simplify the caching logic.

[ilblackdragon]

Fixed in aa35c2e — cache eviction now prunes stale entries on every insert, not just when full. Also, GATEWAY_USER_TOKENS was removed entirely — DB-backed auth is the only multi-user path now.

[gemini-code-assist]

This code uses a let-chain (if let ... && ...), which is a relatively new Rust feature (stabilized in 1.65). The project's general rules state that features not supported by the Minimum Supported Rust Version (MSRV) should be avoided to ensure compatibility. If the project's MSRV is lower than 1.65, this could cause compilation issues.

A similar pattern is used in auth_middleware on line 289. It would be safer to refactor this to use nested if let statements for better compatibility.

Suggested change

	if let Some((identity, inserted_at)) = cache.get(&hash)
	&& inserted_at.elapsed().as_secs() < Self::CACHE_TTL_SECS
	{
	return Some(identity.clone());
	if let Some((identity, inserted_at)) = cache.get(&hash) {
	if inserted_at.elapsed().as_secs() < Self::CACHE_TTL_SECS {
	return Some(identity.clone());
	}
	}

References

1. Avoid using language features, such as let-chains, that are not supported by the project's Minimum Supported Rust Version (MSRV) to ensure compatibility.

[ilblackdragon]

let_chains is stable since Rust 1.87. Project uses Rust 1.94.

[gemini-code-assist]

The logic for generating a user_id from a display_name is fragile and can lead to issues:

• Collisions: Different display names could result in the same user ID (e.g., "John Doe" and "john-doe"). Since user_id is a primary key, this will cause a database error on creation.
• Invalid IDs: A display name containing only whitespace or non-alphanumeric characters could result in an empty or invalid user ID, also causing an error.

This same logic is also used in src/channels/web/handlers/invitations.rs.

Consider implementing a more robust slug generation mechanism. A good approach would be to use a slugification library (like slug) and append a short random string to ensure uniqueness, or to check for uniqueness in the database before attempting to insert.

[ilblackdragon]

Fixed in aa35c2e — user IDs now use Uuid::new_v4().to_string() instead of display-name derivation.

[zmanian]

Review: DB-backed user management

Well-structured feature PR with correct dual-backend support. Several issues to address:

Critical

1. User ID generation is collision-prone (handlers/users.rs, handlers/invitations.rs): IDs derived from display_name.to_lowercase().split_whitespace().join("") -- "John Smith" and "john smith" collide, empty names produce empty IDs, no uniqueness handling. Generate UUID-based IDs, or handle the UNIQUE constraint violation with a 409 instead of 500.

2. No authorization on admin endpoints: All /api/admin/users/* endpoints only check AuthenticatedUser but never verify admin privileges. Any authenticated user can create/list/suspend other users. Add role checking, or document this as intentional for this iteration.

3. Invitation acceptance endpoint routing confusion: POST /api/invitations/accept is behind auth_middleware but the handler doesn't extract AuthenticatedUser. New users can't accept invitations since they don't have a token yet. Move to the public router if unauthenticated access is intended.

High

4. Backend query inconsistency: PostgreSQL get_invitation_by_hash filters status = 'pending' AND expires_at > NOW() but the libSQL version only filters on invite_token_hash -- no status or expiry check. Align the queries.

5. HashMap cache is not actually LRU: DbAuthenticator cache uses HashMap with TTL sweep, not LRU. If 1024 entries arrive within the 60s TTL, the map grows unbounded. Use an LRU crate or add fallback eviction.

6. 60-second stale cache after suspension/revocation: Documented but significant. Consider adding invalidate_user() for security-critical actions.

Medium

7. unwrap_or_default() on UUID parse (db/libsql/users.rs): Silently produces Uuid::nil() on corruption. Return Result with DatabaseError::Serialization.

8. SELECT * in PostgreSQL queries: get_user/get_user_by_email use SELECT * while rest of codebase enumerates columns. Align for consistency.

9. Non-atomic invitation acceptance: Three sequential DB ops (create user, create token, mark accepted) without a transaction. Wrap in transaction or add idempotency handling.

Low

10. Sort order inconsistency: list_users sorts ascending in PostgreSQL, descending in libSQL.
11. Token hashing duplicated across 4 locations -- consolidate into shared utility.
12. status fields use String instead of enums per CLAUDE.md strong-types preference.

Positive notes

• Dual-backend support is complete and migrations are correct
• Token hashing uses SHA-256, never stored in plaintext
• Env-var migration path is thoughtful
• Integration tests are thorough (10 tests covering full lifecycle)
• No .unwrap() in production code

[ilblackdragon]

@zmanian Thanks for the thorough review. Addressed in aa35c2e:

Fixed:

1. User ID: Uuid::new_v4().to_string() — no more display-name collisions
2. Invitation accept: moved to public router (no auth required)
3. libSQL get_invitation_by_hash: aligned with postgres (status='pending' AND expires_at > now)
4. HashMap cache: eviction runs on every insert, not just when full
5. Sort order: both backends use ORDER BY created_at DESC
6. UUID parse: returns DatabaseError::Serialization instead of unwrap_or_default
7. SELECT *: replaced with explicit column lists in postgres

Also in this commit:

• Removed GATEWAY_USER_TOKENS entirely (never went to production)
• Multi-tenant detection moved to runtime via db.has_any_users()
• Removed new_multi_auth() constructor (-181 lines net)

Acknowledged (separate PRs):
2. Admin authorization — intentionally open for this iteration (RBAC is Issue #3)
9. Non-atomic invitation acceptance — noted; transaction support varies by backend
11. Token hashing consolidation — minor cleanup for later
12. Status enums — agreed, but changing the DB schema type is a migration concern