intitial

Add POST /v1/responses and GET /v1/responses/{id} to the web gateway,
implementing the OpenAI Responses API. Unlike the existing Chat
Completions proxy which passes through to the raw LLM, the Responses
API routes requests through the full agent loop — giving external
clients access to tools, memory, safety, and server-side conversation
state via a standard OpenAI-compatible interface.

Key design decisions:
- Response IDs encode thread UUIDs statelessly (resp_{uuid_simple})
- previous_response_id enables multi-turn conversations
- Streaming maps AppEvent variants to Responses API SSE events
- Tool approval returns response.failed (no interactive approval flow)
- GET endpoint reconstructs ResponseObject from conversation_messages

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Cargo.lock

@@ -3482,6 +3482,7 @@ dependencies = [
  "wasmparser 0.220.1",
  "wasmtime",
  "wasmtime-wasi",
+ "webpki-roots 0.26.11",
  "zbus",
  "zip",
 ]
@@ -6991,6 +6992,7 @@ dependencies = [
  "futures-util",
  "http 1.4.0",
  "http-body 1.0.1",
+ "http-body-util",
  "iri-string",
  "pin-project-lite",
  "tower 0.5.3",

Cargo.toml

@@ -57,6 +57,7 @@ refinery = { version = "0.8", features = ["tokio-postgres"], optional = true }
 tokio-postgres-rustls = { version = "0.13", optional = true }
 rustls = { version = "0.23", optional = true, default-features = false }
 rustls-native-certs = { version = "0.8", optional = true }
+webpki-roots = { version = "0.26", optional = true }
 
 # Database - libSQL/Turso (optional embedded database)
 libsql = { version = "0.6", optional = true, default-features = false, features = ["core", "replication", "remote", "tls"] }
@@ -95,7 +96,7 @@ termimad = "0.34"
 # Channel integrations
 axum = { version = "0.8", features = ["ws"] }
 tower = "0.5"
-tower-http = { version = "0.6", features = ["trace", "cors", "set-header"] }
+tower-http = { version = "0.6", features = ["trace", "cors", "set-header", "catch-panic"] }
 
 # Cron scheduling for routines
 cron = "0.13"
@@ -219,6 +220,7 @@ postgres = [
     "dep:tokio-postgres-rustls",
     "dep:rustls",
     "dep:rustls-native-certs",
+    "dep:webpki-roots",
     "dep:postgres-types",
     "dep:refinery",
     "dep:pgvector",
@@ -230,6 +232,7 @@ libsql = ["dep:libsql"]
 integration = []
 html-to-markdown = ["dep:html-to-markdown-rs", "dep:readabilityrs"]
 bedrock = ["dep:aws-config", "dep:aws-sdk-bedrockruntime", "dep:aws-smithy-types"]
+demo = []
 import = ["dep:json5", "libsql"]
 
 [[test]]

Dockerfile

@@ -1,49 +1,78 @@
 # Multi-stage Dockerfile for the IronClaw agent (cloud deployment).
 #
+# Uses cargo-chef for dependency caching — only rebuilds deps when
+# Cargo.toml/Cargo.lock change, not on every source edit.
+#
 # Build:
 #   docker build --platform linux/amd64 -t ironclaw:latest .
 #
 # Run:
 #   docker run --env-file .env -p 3000:3000 ironclaw:latest
 
-# Stage 1: Build
-FROM rust:1.92-slim-bookworm AS builder
+# Stage 1: Install cargo-chef
+FROM rust:1.92-slim-bookworm AS chef
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
     pkg-config libssl-dev cmake gcc g++ \
     && rm -rf /var/lib/apt/lists/* \
     && rustup target add wasm32-wasip2 \
-    && cargo install wasm-tools
+    && cargo install cargo-chef wasm-tools
 
 WORKDIR /app
 
-# Copy manifests first for layer caching
+# Stage 2: Generate the dependency recipe (changes only when Cargo.toml/lock change)
+FROM chef AS planner
+
 COPY Cargo.toml Cargo.lock ./
 COPY crates/ crates/
-
-# Copy source, build script, tests, and supporting directories
 COPY build.rs build.rs
 COPY src/ src/
 COPY tests/ tests/
+COPY benches/ benches/
 COPY migrations/ migrations/
 COPY registry/ registry/
 COPY channels-src/ channels-src/
 COPY wit/ wit/
 COPY providers.json providers.json
-# [[bench]] entries in Cargo.toml require bench sources to exist for cargo to parse the manifest
+
+RUN cargo chef prepare --recipe-path recipe.json
+
+# Stage 3: Build dependencies (cached unless Cargo.toml/lock change)
+FROM chef AS deps
+
+COPY --from=planner /app/recipe.json recipe.json
+RUN cargo chef cook --release --recipe-path recipe.json
+
+# Stage 4: Build the actual binary (only recompiles ironclaw source)
+FROM deps AS builder
+
+COPY Cargo.toml Cargo.lock ./
+COPY crates/ crates/
+COPY build.rs build.rs
+COPY src/ src/
+COPY tests/ tests/
 COPY benches/ benches/
+COPY migrations/ migrations/
+COPY registry/ registry/
+COPY channels-src/ channels-src/
+COPY wit/ wit/
+COPY providers.json providers.json
 
-RUN cargo build --release --bin ironclaw
+COPY skills/ skills/
 
-# Stage 2: Runtime
+RUN cargo build --release --features demo --bin ironclaw
+
+# Stage 5: Runtime
 FROM debian:bookworm-slim
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
     ca-certificates libssl3 \
+    && update-ca-certificates \
     && rm -rf /var/lib/apt/lists/*
 
 COPY --from=builder /app/target/release/ironclaw /usr/local/bin/ironclaw
 COPY --from=builder /app/migrations /app/migrations
+COPY --from=builder /app/skills /app/skills
 
 # Non-root user
 RUN useradd -m -u 1000 -s /bin/bash ironclaw
@@ -52,5 +81,6 @@ USER ironclaw
 EXPOSE 3000
 
 ENV RUST_LOG=ironclaw=info
+ENV SKILLS_DIR=/app/skills
 
 ENTRYPOINT ["ironclaw"]

docs/USER_MANAGEMENT_API.md

@@ -0,0 +1,571 @@
+# User Management API
+
+DB-backed user management for multi-tenant IronClaw deployments. Covers admin user CRUD, per-user secrets provisioning, self-service profile, API token management, and usage reporting.
+
+## Authentication
+
+All endpoints require `Authorization: Bearer <token>`. Tokens are either:
+- **Env-var tokens** — configured via `GATEWAY_AUTH_TOKEN` (single-user) at startup
+- **DB-backed tokens** — created via `POST /api/tokens` or `POST /api/admin/users`
+
+DB tokens are SHA-256 hashed at rest; plaintext is returned exactly once at creation time.
+
+Auth is cached in a bounded LRU (1024 entries, 60s TTL). Suspending a user or revoking a token may take up to 60s to take effect.
+
+## Roles
+
+| Role | Scope |
+|------|-------|
+| `admin` | Full access to all endpoints |
+| `member` | Self-service profile + own token management only |
+
+Endpoints marked **Admin** return `403 Forbidden` for `member` role.
+
+---
+
+## Admin: Users
+
+### POST /api/admin/users
+
+Create a new user. Returns the user record and a one-time plaintext API token.
+
+**Auth:** Admin
+
+**Request body:**
+
+```json
+{
+  "display_name": "Alice Smith",
+  "email": "[email protected]",
+  "role": "member"
+}
+```
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `display_name` | string | yes | | |
+| `email` | string | no | `null` | Must be unique if provided |
+| `role` | string | no | `"member"` | `"admin"` or `"member"` |
+
+**Response:** `200 OK`
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "email": "[email protected]",
+  "display_name": "Alice Smith",
+  "status": "active",
+  "role": "member",
+  "token": "a1b2c3d4e5f6...64-char hex...",
+  "created_at": "2026-03-25T12:00:00+00:00",
+  "created_by": "admin-user-id"
+}
+```
+
+The `token` field is the plaintext API token. It is shown **only once** — store it securely.
+
+**Errors:** `400` (missing display_name, invalid role), `403` (not admin), `503` (no database)
+
+---
+
+### GET /api/admin/users
+
+List all users.
+
+**Auth:** Admin
+
+**Response:** `200 OK`
+
+```json
+{
+  "users": [
+    {
+      "id": "550e8400-...",
+      "email": "[email protected]",
+      "display_name": "Alice Smith",
+      "status": "active",
+      "role": "member",
+      "created_at": "2026-03-25T12:00:00+00:00",
+      "updated_at": "2026-03-25T12:00:00+00:00",
+      "last_login_at": "2026-03-25T14:30:00+00:00",
+      "created_by": "admin-user-id"
+    }
+  ]
+}
+```
+
+---
+
+### GET /api/admin/users/{id}
+
+Get a single user by ID.
+
+**Auth:** Admin
+
+**Response:** `200 OK`
+
+```json
+{
+  "id": "550e8400-...",
+  "email": "[email protected]",
+  "display_name": "Alice Smith",
+  "status": "active",
+  "role": "member",
+  "created_at": "2026-03-25T12:00:00+00:00",
+  "updated_at": "2026-03-25T12:00:00+00:00",
+  "last_login_at": "2026-03-25T14:30:00+00:00",
+  "created_by": "admin-user-id",
+  "metadata": {}
+}
+```
+
+**Errors:** `404` (user not found), `403` (not admin)
+
+---
+
+### PATCH /api/admin/users/{id}
+
+Update a user's display name and/or metadata. Omitted fields are left unchanged.
+
+**Auth:** Admin
+
+**Request body:**
+
+```json
+{
+  "display_name": "Alice Johnson",
+  "metadata": {"department": "engineering"}
+}
+```
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `display_name` | string | no | |
+| `metadata` | object | no | Replaces entire metadata object (merge patch) |
+
+**Response:** `200 OK` — returns the full updated user record (same shape as GET detail, without `last_login_at`/`created_by`).
+
+**Errors:** `404` (user not found), `403` (not admin)
+
+---
+
+### POST /api/admin/users/{id}/suspend
+
+Suspend a user. Suspended users cannot authenticate (DB auth checks user status).
+
+**Auth:** Admin
+
+**Response:** `200 OK`
+
+```json
+{
+  "id": "550e8400-...",
+  "status": "suspended"
+}
+```
+
+**Errors:** `404` (user not found), `403` (not admin)
+
+---
+
+### POST /api/admin/users/{id}/activate
+
+Re-activate a suspended user.
+
+**Auth:** Admin
+
+**Response:** `200 OK`
+
+```json
+{
+  "id": "550e8400-...",
+  "status": "active"
+}
+```
+
+**Errors:** `404` (user not found), `403` (not admin)
+
+---
+
+### DELETE /api/admin/users/{id}
+
+Permanently delete a user and all associated data (tokens, jobs, conversations, memory, routines, settings, secrets).
+
+**Auth:** Admin
+
+**Response:** `200 OK`
+
+```json
+{
+  "id": "550e8400-...",
+  "deleted": true
+}
+```
+
+**Errors:** `404` (user not found), `403` (not admin)
+
+**Cascade:** Deletes from `api_tokens`, `agent_jobs`, `conversations`, `memory_documents`, `routines`, `secrets`, `settings`, `wasm_tools`, and related tables. On PostgreSQL this uses FK cascades; on libSQL it uses explicit deletes.
+
+---
+
+## Admin: Per-User Secrets
+
+Provision secrets on behalf of individual users. The primary use case is an application backend (acting as admin) that configures per-user credentials so each user's IronClaw agent can call back to external services.
+
+Secrets are encrypted at rest with AES-256-GCM using a per-secret HKDF-derived key. Plaintext values are **never returned** by any endpoint — they can only be used by the agent's tool system at runtime.
+
+### PUT /api/admin/users/{user_id}/secrets/{name}
+
+Create or update a secret for the specified user. If a secret with the same name already exists, it is overwritten.
+
+**Auth:** Admin
+
+**Path parameters:**
+
+| Param | Type | Notes |
+|-------|------|-------|
+| `user_id` | string | The user's ID |
+| `name` | string | Secret name (normalized to lowercase) |
+
+**Request body:**
+
+```json
+{
+  "value": "sk-live-abc123...",
+  "provider": "my-app-backend",
+  "expires_in_days": 90
+}
+```
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `value` | string | yes | The secret value (encrypted at rest, never returned) |
+| `provider` | string | no | Tag for grouping (e.g. `"stripe"`, `"my-app"`) |
+| `expires_in_days` | integer | no | Auto-expire after N days; `null` = never |
+
+**Response:** `200 OK`
+
+```json
+{
+  "user_id": "550e8400-...",
+  "name": "my_app_callback_token",
+  "status": "created"
+}
+```
+
+**Errors:** `400` (missing value), `403` (not admin), `503` (secrets store not available)
+
+**Example — application backend provisioning a callback token:**
+
+```bash
+# Admin creates a user
+curl -X POST https://ironclaw.example.com/api/admin/users \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -d '{"display_name": "Alice", "role": "member"}'
+# Response includes: {"id": "alice-uuid", "token": "alice-bearer-token", ...}
+
+# Admin provisions a per-user callback secret
+curl -X PUT https://ironclaw.example.com/api/admin/users/alice-uuid/secrets/app_callback_token \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -d '{"value": "per-user-jwt-for-alice", "provider": "my-app"}'
+
+# Now Alice's IronClaw agent can use the "app_callback_token" secret
+# when calling tools that need to authenticate back to the app backend.
+```
+
+---
+
+### GET /api/admin/users/{user_id}/secrets
+
+List a user's secrets. Returns names and providers only — **never values or hashes**.
+
+**Auth:** Admin
+
+**Response:** `200 OK`
+
+```json
+{
+  "user_id": "550e8400-...",
+  "secrets": [
+    {"name": "app_callback_token", "provider": "my-app"},
+    {"name": "openai_api_key", "provider": "openai"}
+  ]
+}
+```
+
+---
+
+### DELETE /api/admin/users/{user_id}/secrets/{name}
+
+Delete a specific secret for a user.
+
+**Auth:** Admin
+
+**Response:** `200 OK`
+
+```json
+{
+  "user_id": "550e8400-...",
+  "name": "app_callback_token",
+  "deleted": true
+}
+```
+
+**Errors:** `404` (secret not found), `403` (not admin), `503` (secrets store not available)
+
+---
+
+## Admin: Usage
+
+### GET /api/admin/usage
+
+Per-user LLM usage statistics aggregated from `llm_calls` via `agent_jobs.user_id`.
+
+**Auth:** Admin
+
+**Query parameters:**
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `user_id` | string | all users | Filter to a single user |
+| `period` | string | `"day"` | `"day"` (24h), `"week"` (7d), or `"month"` (30d) |
+
+**Response:** `200 OK`
+
+```json
+{
+  "period": "week",
+  "since": "2026-03-18T12:00:00+00:00",
+  "usage": [
+    {
+      "user_id": "alice-id",
+      "model": "claude-sonnet-4-5-20250514",
+      "call_count": 42,
+      "input_tokens": 150000,
+      "output_tokens": 30000,
+      "total_cost": "1.23"
+    }
+  ]
+}
+```
+
+---
+
+## Self-Service: Profile
+
+### GET /api/profile
+
+Get the authenticated user's own profile.
+
+**Auth:** Any authenticated user
+
+**Response:** `200 OK`
+
+```json
+{
+  "id": "550e8400-...",
+  "email": "[email protected]",
+  "display_name": "Alice Smith",
+  "status": "active",
+  "role": "member",
+  "created_at": "2026-03-25T12:00:00+00:00",
+  "last_login_at": "2026-03-25T14:30:00+00:00"
+}
+```
+
+---
+
+### PATCH /api/profile
+
+Update the authenticated user's own display name and/or metadata.
+
+**Auth:** Any authenticated user
+
+**Request body:**
+
+```json
+{
+  "display_name": "Alice Johnson",
+  "metadata": {"theme": "dark"}
+}
+```
+
+**Response:** `200 OK`
+
+```json
+{
+  "id": "550e8400-...",
+  "display_name": "Alice Johnson",
+  "updated": true
+}
+```
+
+---
+
+## Self-Service: Tokens
+
+### POST /api/tokens
+
+Create a new API token for the authenticated user. Admins can optionally create tokens for other users by including `user_id`.
+
+**Auth:** Any authenticated user
+
+**Request body:**
+
+```json
+{
+  "name": "CI pipeline",
+  "expires_in_days": 90,
+  "user_id": "other-user-id"
+}
+```
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `name` | string | yes | Human-readable label |
+| `expires_in_days` | integer | no | `null` = never expires |
+| `user_id` | string | no | Admin-only; create token for another user |
+
+**Response:** `200 OK`
+
+```json
+{
+  "token": "a1b2c3d4...64-char hex...",
+  "id": "token-uuid",
+  "name": "CI pipeline",
+  "token_prefix": "a1b2c3d4",
+  "expires_at": "2026-06-23T12:00:00+00:00",
+  "created_at": "2026-03-25T12:00:00+00:00"
+}
+```
+
+The `token` field is shown **only once**.
+
+---
+
+### GET /api/tokens
+
+List the authenticated user's tokens. Token hashes are never returned.
+
+**Auth:** Any authenticated user
+
+**Response:** `200 OK`
+
+```json
+{
+  "tokens": [
+    {
+      "id": "token-uuid",
+      "name": "CI pipeline",
+      "token_prefix": "a1b2c3d4",
+      "expires_at": "2026-06-23T12:00:00+00:00",
+      "last_used_at": "2026-03-25T14:00:00+00:00",
+      "created_at": "2026-03-25T12:00:00+00:00",
+      "revoked_at": null
+    }
+  ]
+}
+```
+
+---
+
+### DELETE /api/tokens/{id}
+
+Revoke one of the authenticated user's tokens. Users can only revoke their own tokens.
+
+**Auth:** Any authenticated user
+
+**Path:** `id` — UUID of the token to revoke
+
+**Response:** `200 OK`
+
+```json
+{
+  "status": "revoked",
+  "id": "token-uuid"
+}
+```
+
+**Errors:** `400` (invalid UUID), `404` (token not found or belongs to another user)
+
+---
+
+## Error Format
+
+All error responses return a plain text body with the error message and the corresponding HTTP status code:
+
+| Code | Meaning |
+|------|---------|
+| `400` | Bad request (missing fields, invalid input) |
+| `401` | Missing or invalid bearer token |
+| `403` | Authenticated but insufficient role (member accessing admin endpoint) |
+| `404` | Resource not found |
+| `503` | Database or secrets store not available |
+| `500` | Internal server error |
+
+---
+
+## Security Model
+
+### Secrets Encryption
+
+- **Algorithm:** AES-256-GCM with per-secret HKDF-SHA256 derived keys
+- **Master key:** 32+ bytes, resolved from `SECRETS_MASTER_KEY` env var or OS keychain
+- **Storage format:** `nonce (12B) || ciphertext || tag (16B)` in `encrypted_value` column
+- **Per-secret salt:** 32 random bytes stored alongside the ciphertext
+- **Zero-exposure:** Plaintext never appears in logs, debug output, API responses, or LLM conversations
+
+### Auth Cache
+
+- Bounded LRU cache (1024 entries max)
+- 60-second TTL per entry
+- Suspending a user or revoking a token takes up to 60s to propagate
+
+---
+
+## Database Schema
+
+### users
+
+| Column | Type (PG / libSQL) | Notes |
+|--------|--------------------|-------|
+| `id` | `UUID` / `TEXT` | Primary key, UUID v4 |
+| `email` | `TEXT UNIQUE` | Nullable |
+| `display_name` | `TEXT NOT NULL` | |
+| `status` | `TEXT NOT NULL` | `"active"` or `"suspended"` |
+| `role` | `TEXT NOT NULL` | `"admin"` or `"member"` |
+| `created_at` | `TIMESTAMPTZ` / `TEXT` | |
+| `updated_at` | `TIMESTAMPTZ` / `TEXT` | |
+| `last_login_at` | `TIMESTAMPTZ` / `TEXT` | Nullable |
+| `created_by` | `TEXT` | Nullable, references `users.id` |
+| `metadata` | `JSONB` / `TEXT` | Default `{}` |
+
+### api_tokens
+
+| Column | Type (PG / libSQL) | Notes |
+|--------|--------------------|-------|
+| `id` | `UUID` / `TEXT` | Primary key |
+| `user_id` | `TEXT NOT NULL` | FK to `users.id` (PG cascades; libSQL explicit cleanup) |
+| `token_hash` | `BYTEA` / `BLOB` | SHA-256 of hex-encoded plaintext |
+| `token_prefix` | `TEXT NOT NULL` | First 8 chars for identification |
+| `name` | `TEXT NOT NULL` | Human-readable label |
+| `expires_at` | `TIMESTAMPTZ` / `TEXT` | Nullable |
+| `last_used_at` | `TIMESTAMPTZ` / `TEXT` | Nullable |
+| `created_at` | `TIMESTAMPTZ` / `TEXT` | |
+| `revoked_at` | `TIMESTAMPTZ` / `TEXT` | Nullable; set on revocation |
+
+### secrets
+
+| Column | Type (PG / libSQL) | Notes |
+|--------|--------------------|-------|
+| `id` | `UUID` / `TEXT` | Primary key |
+| `user_id` | `TEXT NOT NULL` | Scoped to user |
+| `name` | `TEXT NOT NULL` | Unique per user (lowercase normalized) |
+| `encrypted_value` | `BYTEA` / `BLOB` | AES-256-GCM (nonce + ciphertext + tag) |
+| `key_salt` | `BYTEA` / `BLOB` | Per-secret HKDF salt |
+| `provider` | `TEXT` | Optional grouping tag |
+| `expires_at` | `TIMESTAMPTZ` / `TEXT` | Nullable |
+| `last_used_at` | `TIMESTAMPTZ` / `TEXT` | Audit: last injection time |
+| `usage_count` | `BIGINT` / `INTEGER` | Audit: total injections |
+| `created_at` | `TIMESTAMPTZ` / `TEXT` | |
+| `updated_at` | `TIMESTAMPTZ` / `TEXT` | |

migrations/V14__users.sql

@@ -0,0 +1,31 @@
+-- User management tables for multi-tenant deployments.
+--
+-- Replaces the static GATEWAY_USER_TOKENS env var with DB-backed
+-- user registration, API token management, and invitation flow.
+
+CREATE TABLE users (
+    id TEXT PRIMARY KEY,                        -- matches existing user_id pattern (string, not UUID)
+    email TEXT UNIQUE,                          -- nullable for token-only users
+    display_name TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'active',       -- active | suspended | deactivated
+    role TEXT NOT NULL DEFAULT 'member',          -- admin | member
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    last_login_at TIMESTAMPTZ,
+    created_by TEXT REFERENCES users(id),       -- who invited this user (nullable for bootstrap)
+    metadata JSONB NOT NULL DEFAULT '{}'        -- extensible profile data
+);
+
+CREATE TABLE api_tokens (
+    id UUID PRIMARY KEY,
+    user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    token_hash BYTEA NOT NULL,                  -- SHA-256 hash (never store plaintext)
+    token_prefix TEXT NOT NULL,                 -- first 8 hex chars for display
+    name TEXT NOT NULL,                         -- human label ("my-laptop", "ci-bot")
+    expires_at TIMESTAMPTZ,                     -- nullable = never expires
+    last_used_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    revoked_at TIMESTAMPTZ                      -- soft-revoke: set this instead of deleting
+);
+CREATE INDEX idx_api_tokens_user ON api_tokens(user_id);
+CREATE INDEX idx_api_tokens_hash ON api_tokens(token_hash);

skills/abound-remittance/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: abound-remittance
+version: 0.1.0
+description: Smart remittance assistant for Abound — helps users send money to India with intelligent forex timing and transfer management.
+activation:
+  keywords:
+    - send money
+    - transfer
+    - remittance
+    - exchange rate
+    - forex
+    - INR
+    - India
+    - wire
+    - schedule trade
+    - trade tomorrow
+    - convert currency
+    - send dollars
+    - rupees
+    - beneficiary
+    - funding source
+    - payment
+    - how much
+    - rate today
+    - best time
+    - family maintenance
+  patterns:
+    - "send \\$?\\d+"
+    - "schedule.*(trade|transfer|send|wire)"
+    - "how much.*(INR|rupees|India)"
+    - "best time to (send|transfer|convert)"
+    - "(rate|forex).*(good|bad|high|low|today|now)"
+    - "transfer.*tomorrow|tomorrow.*transfer"
+  tags:
+    - fintech
+    - remittance
+    - forex
+  max_context_tokens: 2500
+---
+
+# Abound Remittance Assistant
+
+You are a smart remittance assistant for Abound, helping users send money from USD to INR (India) with intelligent timing advice.
+
+## Available Tools
+
+You have these Abound-specific tools:
+
+- **abound_get_account_info** — Get the user's account: limits, recipients, funding sources, payment reasons
+- **abound_get_exchange_rate** — Get current USD/INR exchange rate (current + effective after fees)
+- **abound_get_forex_score** — Get a 0-100 forex timing score with a signal (convert_now / split_transfer / wait)
+- **abound_send_wire** — Execute a wire transfer (requires: funding_source_id, beneficiary_ref_id, amount, payment_reason_key)
+- **abound_create_notification** — Send a notification to the user's Abound app
+
+You also have **routine_create** for scheduling future/recurring transfers.
+
+## Workflow: "Send $X" or "Transfer money"
+
+1. **Always check the rate first.** Call `abound_get_exchange_rate` to get the current rate.
+2. **Check the forex score.** Call `abound_get_forex_score` to assess timing.
+3. **Get account info.** Call `abound_get_account_info` to know the user's limits, recipients, and funding sources.
+4. **Advise based on the score:**
+   - **Score >= 60 (convert_now):** Tell the user it's a good time. Show the rate, the INR equivalent of their amount, and recommend proceeding.
+   - **Score 40-59 (split_transfer):** Suggest splitting — send half now at the current rate, schedule the rest for later when the rate may improve.
+   - **Score < 40 (wait):** Unless the transfer is urgent, recommend waiting. Explain why (rate below average, unfavorable season).
+5. **Execute if user confirms.** Use `abound_send_wire` with the correct funding_source_id, beneficiary_ref_id, amount, and payment_reason_key from the account info.
+6. **Notify.** After a successful wire, call `abound_create_notification` with relevant metadata.
+
+## Workflow: "Schedule a trade" or "Send tomorrow morning"
+
+1. Gather the same info (rate, score, account).
+2. Use **routine_create** to schedule the transfer:
+   - For "tomorrow morning": use cron `"0 9 * * *"` with the user's timezone, set to fire once
+   - For "every week": use cron `"0 9 * * MON"` (or the user's preferred day)
+   - The routine prompt should instruct the agent to check the rate and execute the wire
+3. Confirm the schedule with the user, showing when it will fire.
+
+## Presentation Rules
+
+- Always show amounts in **both USD and INR**: "$1,000 (~INR 85,420 at today's rate of 85.42)"
+- Show the **effective rate** (after fees), not just the market rate
+- When showing the forex score, explain it simply: "The forex timing score is 72/100 — this is a good time to send."
+- If the user's amount exceeds their limit ($5,000), tell them and suggest splitting into multiple transfers
+- Always mention the **estimated delivery time** (1-3 business days) after a wire
+
+## Payment Reasons
+
+When asking about the purpose, offer these options:
+- Family Maintenance
+- Gift
+- Education Support
+- Medical Support
+
+If the user doesn't specify, ask which applies.

src/agent/dispatcher.rs

@@ -400,16 +400,21 @@ impl<'a> LoopDelegate for ChatDelegate<'a> {
         };
 
         // Record cost and track token usage (global + per-user).
-        // When a model override is active, use the override name for attribution
-        // and let CostGuard look up pricing via costs::model_cost() instead of
-        // using the default provider's cost_per_token (which reflects the wrong model).
-        let (model_name, cost_per_token) = if let Some(ref ovr) = reason_ctx.model_override {
-            (ovr.clone(), None)
+        // Use the provider's effective_model_name so cost attribution matches
+        // the model that actually served the request. When the override is
+        // honoured (e.g. NearAI), this returns the override name; when the
+        // provider ignores overrides (e.g. Rig-based), it returns the active
+        // model, keeping attribution accurate in both cases.
+        let model_name = self
+            .agent
+            .llm()
+            .effective_model_name(reason_ctx.model_override.as_deref());
+        let cost_per_token = if reason_ctx.model_override.is_some() {
+            // Override may use different pricing; let CostGuard fall back to
+            // costs::model_cost() for the effective model.
+            None
         } else {
-            (
-                self.agent.llm().active_model_name(),
-                Some(self.agent.llm().cost_per_token()),
-            )
+            Some(self.agent.llm().cost_per_token())
         };
         let read_discount = self.agent.llm().cache_read_discount();
         let write_multiplier = self.agent.llm().cache_write_multiplier();
@@ -1354,6 +1359,7 @@ mod tests {
                 max_tool_iterations: 50,
                 auto_approve_tools: false,
                 default_timezone: "UTC".to_string(),
+                max_jobs_per_user: None,
                 max_tokens_per_job: 0,
                 multi_tenant: false,
                 max_llm_concurrent_per_user: None,
@@ -2235,6 +2241,7 @@ mod tests {
                 max_tool_iterations,
                 auto_approve_tools: true,
                 default_timezone: "UTC".to_string(),
+                max_jobs_per_user: None,
                 max_tokens_per_job: 0,
                 multi_tenant: false,
                 max_llm_concurrent_per_user: None,
@@ -2362,6 +2369,7 @@ mod tests {
                     max_tool_iterations: max_iter,
                     auto_approve_tools: true,
                     default_timezone: "UTC".to_string(),
+                    max_jobs_per_user: None,
                     max_tokens_per_job: 0,
                     multi_tenant: false,
                     max_llm_concurrent_per_user: None,

src/agent/heartbeat.rs

@@ -400,7 +400,7 @@ impl HeartbeatRunner {
     }
 
     /// Send a notification about heartbeat findings.
-    pub(crate) async fn send_notification(&self, message: &str) {
+    async fn send_notification(&self, message: &str) {
         let Some(ref tx) = self.response_tx else {
             tracing::debug!("No response channel configured for heartbeat notifications");
             return;
@@ -512,8 +512,8 @@ pub fn spawn_heartbeat(
     })
 }
 
-/// Spawn a multi-user heartbeat runner that cycles through all users that
-/// own routines (enabled or not). Each tick, it queries the DB for distinct
+/// Spawn a multi-user heartbeat runner that cycles through all users who
+/// have routines (enabled or not). Each tick, it queries the DB for distinct
 /// user_ids, creates a per-user workspace, and runs a heartbeat check for
 /// each user concurrently. Per-user failure counts are tracked independently.
 pub fn spawn_multi_user_heartbeat(
@@ -574,8 +574,10 @@ pub fn spawn_multi_user_heartbeat(
                 }
             };
 
-            // Run user heartbeats concurrently so one slow LLM call doesn't
-            // block others. Cap concurrency to avoid flooding the LLM provider.
+            // Run user heartbeats (and hygiene) concurrently so one slow LLM
+            // call doesn't block others. Cap concurrency to avoid flooding the
+            // LLM provider. Hygiene runs inside the same JoinSet so it is
+            // tracked and bounded by the same concurrency cap.
             const MAX_CONCURRENT_HEARTBEATS: usize = 8;
             let mut join_set = tokio::task::JoinSet::new();
 
@@ -588,23 +590,6 @@ pub fn spawn_multi_user_heartbeat(
 
                 let workspace = Arc::new(Workspace::new_with_db(user_id, Arc::clone(store.db())));
 
-                // Run memory hygiene per user (same as single-user heartbeat).
-                let hygiene_ws = Arc::clone(&workspace);
-                let hygiene_cfg = hygiene_config.clone();
-                let hygiene_user = user_id.clone();
-                tokio::spawn(async move {
-                    let report =
-                        crate::workspace::hygiene::run_if_due(&hygiene_ws, &hygiene_cfg).await;
-                    if report.had_work() {
-                        tracing::info!(
-                            user_id = hygiene_user,
-                            daily_logs_deleted = report.daily_logs_deleted,
-                            conversation_docs_deleted = report.conversation_docs_deleted,
-                            "multi-user heartbeat: memory hygiene deleted stale documents"
-                        );
-                    }
-                });
-
                 // Drain completed tasks to stay within the concurrency cap.
                 while join_set.len() >= MAX_CONCURRENT_HEARTBEATS {
                     if let Some(join_result) = join_set.join_next().await {
@@ -613,13 +598,30 @@ pub fn spawn_multi_user_heartbeat(
                 }
 
                 let uid = user_id.clone();
-                let cfg = config.clone();
+                // In multi-tenant mode, clear notify_user_id so that
+                // HeartbeatRunner::send_notification falls back to
+                // workspace.user_id() — each user's heartbeat should persist
+                // and notify that user, not the shared config target.
+                let mut cfg = config.clone();
+                cfg.notify_user_id = None;
                 let hyg = hygiene_config.clone();
                 let llm_clone = llm.clone();
                 let tx = response_tx.clone();
                 let admin = store.clone();
 
                 join_set.spawn(async move {
+                    // Run memory hygiene per user (same as single-user heartbeat)
+                    // inside the tracked task so concurrency is bounded.
+                    let report = crate::workspace::hygiene::run_if_due(&workspace, &hyg).await;
+                    if report.had_work() {
+                        tracing::info!(
+                            user_id = uid,
+                            daily_logs_deleted = report.daily_logs_deleted,
+                            conversation_docs_deleted = report.conversation_docs_deleted,
+                            "multi-user heartbeat: memory hygiene deleted stale documents"
+                        );
+                    }
+
                     let mut runner = HeartbeatRunner::new(cfg, hyg, workspace, llm_clone);
                     if let Some(tx) = tx {
                         runner = runner.with_response_channel(tx);

src/agent/scheduler.rs

@@ -267,6 +267,20 @@ impl Scheduler {
                 });
             }
 
+            // Per-user concurrency check
+            if let Some(max_per_user) = self.config.max_jobs_per_user
+                && let Ok(ctx) = self.context_manager.get_context(job_id).await
+            {
+                let user_active = self
+                    .context_manager
+                    .active_jobs_for(&ctx.user_id)
+                    .await
+                    .len();
+                if user_active >= max_per_user {
+                    return Err(JobError::MaxJobsExceeded { max: max_per_user });
+                }
+            }
+
             // Transition job to in_progress
             self.context_manager
                 .update_context(job_id, |ctx| {
@@ -784,6 +798,7 @@ mod tests {
             max_tool_iterations: 10,
             auto_approve_tools: true,
             default_timezone: "UTC".to_string(),
+            max_jobs_per_user: None,
             max_tokens_per_job,
             multi_tenant: false,
             max_llm_concurrent_per_user: None,

src/app.rs

@@ -336,17 +336,12 @@ impl AppBuilder {
             ws = ws.with_memory_layers(self.config.workspace.memory_layers.clone());
             let ws = Arc::new(ws);
 
-            // Detect multi-tenant mode: when GATEWAY_USER_TOKENS is configured,
+            // Detect multi-tenant mode: when the database has registered users,
             // each authenticated user needs their own workspace scope. Use
             // WorkspacePool (which implements WorkspaceResolver) to create
             // per-user workspaces on demand instead of sharing the startup
             // workspace across all users.
-            let is_multi_tenant = self
-                .config
-                .channels
-                .gateway
-                .as_ref()
-                .is_some_and(|gw| gw.user_tokens.is_some());
+            let is_multi_tenant = db.has_any_users().await.unwrap_or(false);
 
             if is_multi_tenant {
                 let pool = Arc::new(crate::channels::web::server::WorkspacePool::new(

src/channels/web/CLAUDE.md

@@ -91,6 +91,34 @@ Browser-facing HTTP API and SSE/WebSocket real-time streaming. Axum-based, singl
 | DELETE | `/api/routines/{id}` | Delete a routine |
 | GET | `/api/routines/{id}/runs` | List runs for a specific routine |
 
+### User Management (admin — requires `admin` role, see `docs/USER_MANAGEMENT_API.md`)
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/admin/users` | Create a new user (returns one-time token) |
+| GET | `/api/admin/users` | List all users |
+| GET | `/api/admin/users/{id}` | Get a single user |
+| PATCH | `/api/admin/users/{id}` | Update user profile/metadata |
+| DELETE | `/api/admin/users/{id}` | Delete user and all data |
+| POST | `/api/admin/users/{id}/suspend` | Suspend a user |
+| POST | `/api/admin/users/{id}/activate` | Re-activate a user |
+| GET | `/api/admin/usage` | Per-user LLM usage stats |
+| GET | `/api/admin/users/{id}/secrets` | List a user's secrets (names only) |
+| PUT | `/api/admin/users/{id}/secrets/{name}` | Create or update a user's secret |
+| DELETE | `/api/admin/users/{id}/secrets/{name}` | Delete a user's secret |
+
+### Profile (self-service)
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/profile` | Get own profile |
+| PATCH | `/api/profile` | Update own display name/metadata |
+
+### Tokens (self-service)
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/tokens` | Create API token (returns plaintext once) |
+| GET | `/api/tokens` | List own tokens |
+| DELETE | `/api/tokens/{id}` | Revoke a token |
+
 ### Settings
 | Method | Path | Description |
 |--------|------|-------------|

src/channels/web/auth.rs

@@ -5,6 +5,7 @@
 //! handlers can extract it via `AuthenticatedUser`.
 
 use std::collections::HashMap;
+use std::num::NonZeroUsize;
 
 use axum::{
     extract::{FromRequestParts, Request, State},
@@ -13,18 +14,25 @@ use axum::{
     response::{IntoResponse, Response},
 };
 use sha2::{Digest, Sha256};
+use std::sync::Arc;
+use std::time::Instant;
 use subtle::ConstantTimeEq;
+use tokio::sync::RwLock;
+
+use crate::db::Database;
 
 /// Identity resolved from a bearer token.
 #[derive(Debug, Clone)]
 pub struct UserIdentity {
     pub user_id: String,
+    /// `admin` or `member`.
+    pub role: String,
     /// Additional user scopes this identity can read from.
     pub workspace_read_scopes: Vec<String>,
 }
 
 /// Hash a token with SHA-256 for constant-size, timing-safe storage.
-fn hash_token(token: &str) -> [u8; 32] {
+pub fn hash_token(token: &str) -> [u8; 32] {
     let mut hasher = Sha256::new();
     hasher.update(token.as_bytes());
     hasher.finalize().into()
@@ -56,6 +64,7 @@ impl MultiAuthState {
                 hash,
                 UserIdentity {
                     user_id,
+                    role: "admin".to_string(),
                     workspace_read_scopes: Vec::new(),
                 },
             )],
@@ -64,6 +73,11 @@ impl MultiAuthState {
     }
 
     /// Create a multi-user auth state from a map of tokens to identities.
+    ///
+    /// **Test-only** — production multi-user auth is DB-backed via
+    /// `DbAuthenticator`. This constructor is kept public (not `#[cfg(test)]`)
+    /// because integration tests in `tests/` compile the crate as a library
+    /// where `cfg(test)` is not set.
     pub fn multi(tokens: HashMap<String, UserIdentity>) -> Self {
         let hashed_tokens: Vec<([u8; 32], UserIdentity)> = tokens
             .into_iter()
@@ -108,6 +122,112 @@ impl MultiAuthState {
     }
 }
 
+/// DB-backed token authenticator with a bounded LRU cache.
+///
+/// Checks an LRU cache first (TTL 60s), then falls back to a DB query.
+/// The cache is bounded to `MAX_CACHE_ENTRIES` — when full, the least
+/// recently used entry is evicted regardless of TTL.
+///
+/// Revoking a token or suspending a user has at most 60s of stale
+/// authentication before the cache entry expires.
+#[derive(Clone)]
+#[allow(clippy::type_complexity)]
+pub struct DbAuthenticator {
+    store: Arc<dyn Database>,
+    /// Bounded LRU cache: token_hash → (identity, inserted_at).
+    cache: Arc<RwLock<lru::LruCache<[u8; 32], (UserIdentity, Instant)>>>,
+}
+
+impl DbAuthenticator {
+    /// Cache TTL — how long a successful auth is cached before re-querying the DB.
+    const CACHE_TTL_SECS: u64 = 60;
+    /// Maximum cache entries to prevent unbounded growth.
+    // SAFETY: 1024 is non-zero, so the unwrap in `new()` is infallible.
+    const MAX_CACHE_ENTRIES: NonZeroUsize = match NonZeroUsize::new(1024) {
+        Some(v) => v,
+        None => unreachable!(),
+    };
+
+    pub fn new(store: Arc<dyn Database>) -> Self {
+        Self {
+            store,
+            cache: Arc::new(RwLock::new(lru::LruCache::new(Self::MAX_CACHE_ENTRIES))),
+        }
+    }
+
+    /// Authenticate a token against the database, using cache when possible.
+    ///
+    /// Returns `Ok(Some(identity))` on success, `Ok(None)` if the token is
+    /// not found, or `Err(())` if the database is unreachable (so the caller
+    /// can return 503 instead of 401).
+    pub async fn authenticate(&self, candidate: &str) -> Result<Option<UserIdentity>, ()> {
+        let hash = hash_token(candidate);
+
+        // Check cache first (promotes to most-recent on hit)
+        {
+            let mut cache = self.cache.write().await;
+            if let Some((identity, inserted_at)) = cache.get(&hash) {
+                if inserted_at.elapsed().as_secs() < Self::CACHE_TTL_SECS {
+                    return Ok(Some(identity.clone()));
+                }
+                // Expired — remove stale entry
+                cache.pop(&hash);
+            }
+        }
+
+        // Cache miss or expired — query DB
+        let (token_record, user_record) = match self.store.authenticate_token(&hash).await {
+            Ok(Some(pair)) => pair,
+            Ok(None) => return Ok(None),
+            Err(e) => {
+                tracing::error!(error = %e, "DB auth lookup failed, returning 503");
+                return Err(());
+            }
+        };
+
+        let identity = UserIdentity {
+            user_id: user_record.id.clone(),
+            role: user_record.role.clone(),
+            workspace_read_scopes: Vec::new(),
+        };
+
+        // Record token usage (best-effort, don't block auth)
+        let store = self.store.clone();
+        let token_id = token_record.id;
+        let user_id = user_record.id;
+        tokio::spawn(async move {
+            let _ = store.record_token_usage(token_id).await;
+            let _ = store.record_login(&user_id).await;
+        });
+
+        // Insert into bounded LRU — if full, least-recently-used entry is evicted
+        {
+            let mut cache = self.cache.write().await;
+            cache.put(hash, (identity.clone(), Instant::now()));
+        }
+
+        Ok(Some(identity))
+    }
+}
+
+/// Combined auth state: tries env-var tokens first, then DB-backed tokens.
+#[derive(Clone)]
+pub struct CombinedAuthState {
+    /// In-memory tokens from GATEWAY_AUTH_TOKEN.
+    pub env_auth: MultiAuthState,
+    /// DB-backed token authenticator (optional — only when a database is available).
+    pub db_auth: Option<DbAuthenticator>,
+}
+
+impl From<MultiAuthState> for CombinedAuthState {
+    fn from(env_auth: MultiAuthState) -> Self {
+        Self {
+            env_auth,
+            db_auth: None,
+        }
+    }
+}
+
 /// Axum extractor that provides the authenticated user identity.
 ///
 /// Only available on routes behind `auth_middleware`. Extracts the
@@ -130,6 +250,31 @@ where
     }
 }
 
+/// Axum extractor that requires the authenticated user to have the `admin` role.
+///
+/// Use instead of `AuthenticatedUser` on endpoints that modify system-wide
+/// state (user management, model selection, extension/skill installation).
+pub struct AdminUser(pub UserIdentity);
+
+impl<S> FromRequestParts<S> for AdminUser
+where
+    S: Send + Sync,
+{
+    type Rejection = (StatusCode, &'static str);
+
+    async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result<Self, Self::Rejection> {
+        let identity = parts
+            .extensions
+            .get::<UserIdentity>()
+            .cloned()
+            .ok_or((StatusCode::UNAUTHORIZED, "Not authenticated"))?;
+        if identity.role != "admin" {
+            return Err((StatusCode::FORBIDDEN, "Admin role required"));
+        }
+        Ok(AdminUser(identity))
+    }
+}
+
 /// Whether query-string token auth is allowed for this request.
 ///
 /// Only GET requests to streaming endpoints may use `?token=xxx`. This
@@ -166,39 +311,65 @@ fn query_token(request: &Request) -> Option<String> {
 
 /// Auth middleware that validates bearer token from header or query param.
 ///
-/// SSE connections can't set headers from `EventSource`, so we also accept
-/// `?token=xxx` as a query parameter, but only on SSE/WS endpoints.
+/// Tries env-var tokens first (constant-time, in-memory), then falls back
+/// to DB-backed token lookup if configured. SSE connections can't set
+/// headers from `EventSource`, so we also accept `?token=xxx` as a query
+/// parameter, but only on SSE/WS endpoints.
 ///
 /// On successful authentication, inserts the matching `UserIdentity` into
 /// request extensions for downstream extraction via `AuthenticatedUser`.
 pub async fn auth_middleware(
-    State(auth): State<MultiAuthState>,
+    State(auth): State<CombinedAuthState>,
     headers: HeaderMap,
     mut request: Request,
     next: Next,
 ) -> Response {
-    // Try Authorization header first.
-    // RFC 6750 Section 2.1: auth-scheme comparison is case-insensitive.
+    // Extract the candidate token from header or query param.
+    let token = extract_token(&headers, &request);
+
+    if let Some(ref tok) = token {
+        // 1. Try env-var tokens first (fast, constant-time, in-memory).
+        if let Some(identity) = auth.env_auth.authenticate(tok) {
+            request.extensions_mut().insert(identity.clone());
+            return next.run(request).await;
+        }
+
+        // 2. Fall back to DB-backed token lookup.
+        if let Some(ref db_auth) = auth.db_auth {
+            match db_auth.authenticate(tok).await {
+                Ok(Some(identity)) => {
+                    request.extensions_mut().insert(identity);
+                    return next.run(request).await;
+                }
+                Err(()) => {
+                    return (StatusCode::SERVICE_UNAVAILABLE, "Database unavailable")
+                        .into_response();
+                }
+                Ok(None) => {}
+            }
+        }
+    }
+
+    (StatusCode::UNAUTHORIZED, "Invalid or missing auth token").into_response()
+}
+
+/// Extract a bearer token from the Authorization header or query parameter.
+fn extract_token(headers: &HeaderMap, request: &Request) -> Option<String> {
+    // Try Authorization header first (RFC 6750).
     if let Some(auth_header) = headers.get("authorization")
         && let Ok(value) = auth_header.to_str()
         && value.len() > 7
         && value[..7].eq_ignore_ascii_case("Bearer ")
-        && let Some(identity) = auth.authenticate(&value[7..])
     {
-        request.extensions_mut().insert(identity.clone());
-        return next.run(request).await;
+        return Some(value[7..].to_string());
     }
 
-    // Fall back to query parameter, but only for SSE/WS endpoints.
-    if allows_query_token_auth(&request)
-        && let Some(token) = query_token(&request)
-        && let Some(identity) = auth.authenticate(&token)
-    {
-        request.extensions_mut().insert(identity.clone());
-        return next.run(request).await;
+    // Fall back to query parameter for SSE/WS endpoints.
+    if allows_query_token_auth(request) {
+        return query_token(request);
     }
 
-    (StatusCode::UNAUTHORIZED, "Invalid or missing auth token").into_response()
+    None
 }
 
 #[cfg(test)]
@@ -227,6 +398,7 @@ mod tests {
             "tok-alice".to_string(),
             UserIdentity {
                 user_id: "alice".to_string(),
+                role: "admin".to_string(),
                 workspace_read_scopes: Vec::new(),
             },
         );
@@ -234,6 +406,7 @@ mod tests {
             "tok-bob".to_string(),
             UserIdentity {
                 user_id: "bob".to_string(),
+                role: "admin".to_string(),
                 workspace_read_scopes: Vec::new(),
             },
         );
@@ -274,7 +447,10 @@ mod tests {
     /// Router with streaming endpoints (query auth allowed) and regular
     /// endpoints (query auth rejected).
     fn test_app(token: &str) -> Router {
-        let state = MultiAuthState::single(token.to_string(), "test-user".to_string());
+        let state = CombinedAuthState::from(MultiAuthState::single(
+            token.to_string(),
+            "test-user".to_string(),
+        ));
         Router::new()
             .route("/api/chat/events", get(dummy_handler))
             .route("/api/logs/events", get(dummy_handler))
@@ -486,7 +662,7 @@ mod tests {
 
     /// Build a multi-user router where each token maps to a distinct identity.
     fn multi_user_app(tokens: HashMap<String, UserIdentity>) -> Router {
-        let state = MultiAuthState::multi(tokens);
+        let state = CombinedAuthState::from(MultiAuthState::multi(tokens));
         Router::new()
             .route("/api/chat/events", get(identity_handler))
             .route("/api/chat/send", post(identity_handler))
@@ -500,6 +676,7 @@ mod tests {
             "tok-alice".to_string(),
             UserIdentity {
                 user_id: "alice".to_string(),
+                role: "admin".to_string(),
                 workspace_read_scopes: vec!["shared".to_string()],
             },
         );
@@ -507,6 +684,7 @@ mod tests {
             "tok-bob".to_string(),
             UserIdentity {
                 user_id: "bob".to_string(),
+                role: "admin".to_string(),
                 workspace_read_scopes: vec!["shared".to_string(), "alice".to_string()],
             },
         );
@@ -643,7 +821,10 @@ mod tests {
     #[tokio::test]
     async fn test_multi_user_empty_scopes_for_single_user() {
         // Single-user mode creates identity with empty workspace_read_scopes.
-        let state = MultiAuthState::single("tok-only".to_string(), "solo".to_string());
+        let state = CombinedAuthState::from(MultiAuthState::single(
+            "tok-only".to_string(),
+            "solo".to_string(),
+        ));
         let app = Router::new()
             .route("/api/scopes", get(scopes_handler))
             .layer(middleware::from_fn_with_state(state, auth_middleware));

src/channels/web/handlers/mod.rs

@@ -5,7 +5,10 @@
 pub mod jobs;
 pub mod memory;
 pub mod routines;
+pub mod secrets;
 pub mod skills;
+pub mod tokens;
+pub mod users;
 
 // Modules not yet wired into server.rs router -- suppress dead_code until
 // they replace their inline counterparts.

src/channels/web/handlers/secrets.rs

@@ -0,0 +1,134 @@
+//! Admin secrets provisioning handlers.
+//!
+//! Allows an admin (typically an application backend) to create, list, and
+//! delete secrets on behalf of individual users so their IronClaw agent can
+//! call back to external services with per-user credentials.
+
+use std::sync::Arc;
+
+use axum::{
+    Json,
+    extract::{Path, State},
+    http::StatusCode,
+};
+
+use crate::channels::web::auth::AdminUser;
+use crate::channels::web::server::GatewayState;
+use crate::secrets::CreateSecretParams;
+
+/// PUT /api/admin/users/{user_id}/secrets/{name} — create or update a secret.
+///
+/// Upserts: if a secret with the same (user_id, name) already exists it is
+/// overwritten. The plaintext value is encrypted at rest (AES-256-GCM) and
+/// never returned by any endpoint.
+pub async fn secrets_put_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_admin): AdminUser,
+    Path((user_id, name)): Path<(String, String)>,
+    Json(body): Json<serde_json::Value>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let secrets = state.secrets_store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Secrets store not available".to_string(),
+    ))?;
+
+    let value = body
+        .get("value")
+        .and_then(|v| v.as_str())
+        .ok_or((
+            StatusCode::BAD_REQUEST,
+            "Missing required field 'value'".to_string(),
+        ))?
+        .to_string();
+
+    let provider = body
+        .get("provider")
+        .and_then(|v| v.as_str())
+        .map(String::from);
+
+    let expires_at = body
+        .get("expires_in_days")
+        .and_then(|v| v.as_u64())
+        .map(|d| d.min(36500))
+        .map(|days| chrono::Utc::now() + chrono::Duration::days(days as i64));
+
+    let mut params = CreateSecretParams::new(name.clone(), value);
+    if let Some(p) = provider {
+        params = params.with_provider(p);
+    }
+    if let Some(exp) = expires_at {
+        params = params.with_expiry(exp);
+    }
+
+    secrets
+        .create(&user_id, params)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    Ok(Json(serde_json::json!({
+        "user_id": user_id,
+        "name": name.to_lowercase(),
+        "status": "created",
+    })))
+}
+
+/// GET /api/admin/users/{user_id}/secrets — list a user's secrets (names only).
+///
+/// Never returns secret values or hashes.
+pub async fn secrets_list_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_admin): AdminUser,
+    Path(user_id): Path<String>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let secrets = state.secrets_store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Secrets store not available".to_string(),
+    ))?;
+
+    let refs = secrets
+        .list(&user_id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    let secrets_json: Vec<serde_json::Value> = refs
+        .into_iter()
+        .map(|r| {
+            serde_json::json!({
+                "name": r.name,
+                "provider": r.provider,
+            })
+        })
+        .collect();
+
+    Ok(Json(serde_json::json!({
+        "user_id": user_id,
+        "secrets": secrets_json,
+    })))
+}
+
+/// DELETE /api/admin/users/{user_id}/secrets/{name} — delete a user's secret.
+pub async fn secrets_delete_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_admin): AdminUser,
+    Path((user_id, name)): Path<(String, String)>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let secrets = state.secrets_store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Secrets store not available".to_string(),
+    ))?;
+
+    let deleted = secrets
+        .delete(&user_id, &name)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    if !deleted {
+        return Err((StatusCode::NOT_FOUND, "Secret not found".to_string()));
+    }
+
+    Ok(Json(serde_json::json!({
+        "user_id": user_id,
+        "name": name,
+        "deleted": true,
+    })))
+}

src/channels/web/handlers/tokens.rs

@@ -0,0 +1,150 @@
+//! API token management handlers.
+
+use std::sync::Arc;
+
+use axum::{
+    Json,
+    extract::{Path, State},
+    http::StatusCode,
+};
+use rand::RngCore;
+use rand::rngs::OsRng;
+use uuid::Uuid;
+
+use crate::channels::web::auth::AuthenticatedUser;
+use crate::channels::web::server::GatewayState;
+
+/// POST /api/tokens — create a new API token (returns plaintext ONCE).
+pub async fn tokens_create_handler(
+    State(state): State<Arc<GatewayState>>,
+    AuthenticatedUser(user): AuthenticatedUser,
+    Json(body): Json<serde_json::Value>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    let name = body
+        .get("name")
+        .and_then(|v| v.as_str())
+        .ok_or((
+            StatusCode::BAD_REQUEST,
+            "Missing required field 'name'".to_string(),
+        ))?
+        .to_string();
+
+    let expires_in_days: Option<i64> = body
+        .get("expires_in_days")
+        .and_then(|v| v.as_u64())
+        .map(|d| d.min(36500) as i64);
+
+    let expires_at = expires_in_days.map(|days| chrono::Utc::now() + chrono::Duration::days(days));
+
+    // Generate 32 random bytes for the token.
+    // Hash the hex-encoded plaintext (what the user sends as Bearer token),
+    // NOT the raw bytes — must match hash_token() in auth.rs.
+    let mut token_bytes = [0u8; 32];
+    OsRng.fill_bytes(&mut token_bytes);
+    let plaintext_token = hex::encode(token_bytes);
+    let hash = crate::channels::web::auth::hash_token(&plaintext_token);
+
+    // First 8 chars of the hex token as a prefix for identification.
+    let token_prefix = &plaintext_token[..8];
+
+    // Admin users can create tokens for other users via optional "user_id" field.
+    let target_user = body
+        .get("user_id")
+        .and_then(|v| v.as_str())
+        .filter(|_| user.role == "admin")
+        .unwrap_or(&user.user_id);
+
+    // Verify the target user exists to prevent orphan tokens.
+    if target_user != user.user_id {
+        store
+            .get_user(target_user)
+            .await
+            .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?
+            .ok_or((
+                StatusCode::BAD_REQUEST,
+                format!("Target user '{target_user}' not found"),
+            ))?;
+    }
+
+    let record = store
+        .create_api_token(target_user, &name, &hash, token_prefix, expires_at)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    // Return the plaintext token — this is the ONLY time it is shown.
+    Ok(Json(serde_json::json!({
+        "token": plaintext_token,
+        "id": record.id.to_string(),
+        "name": record.name,
+        "token_prefix": record.token_prefix,
+        "expires_at": record.expires_at.map(|dt| dt.to_rfc3339()),
+        "created_at": record.created_at.to_rfc3339(),
+    })))
+}
+
+/// GET /api/tokens — list the current user's tokens (no hashes).
+pub async fn tokens_list_handler(
+    State(state): State<Arc<GatewayState>>,
+    AuthenticatedUser(user): AuthenticatedUser,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    let tokens = store
+        .list_api_tokens(&user.user_id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    let tokens_json: Vec<serde_json::Value> = tokens
+        .into_iter()
+        .map(|t| {
+            serde_json::json!({
+                "id": t.id.to_string(),
+                "name": t.name,
+                "token_prefix": t.token_prefix,
+                "expires_at": t.expires_at.map(|dt| dt.to_rfc3339()),
+                "last_used_at": t.last_used_at.map(|dt| dt.to_rfc3339()),
+                "created_at": t.created_at.to_rfc3339(),
+                "revoked_at": t.revoked_at.map(|dt| dt.to_rfc3339()),
+            })
+        })
+        .collect();
+
+    Ok(Json(serde_json::json!({ "tokens": tokens_json })))
+}
+
+/// DELETE /api/tokens/{id} — revoke a token.
+pub async fn tokens_revoke_handler(
+    State(state): State<Arc<GatewayState>>,
+    AuthenticatedUser(user): AuthenticatedUser,
+    Path(id): Path<String>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    let token_id = Uuid::parse_str(&id)
+        .map_err(|_| (StatusCode::BAD_REQUEST, "Invalid token ID".to_string()))?;
+
+    let revoked = store
+        .revoke_api_token(token_id, &user.user_id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    if !revoked {
+        return Err((StatusCode::NOT_FOUND, "Token not found".to_string()));
+    }
+
+    Ok(Json(serde_json::json!({
+        "status": "revoked",
+        "id": token_id.to_string(),
+    })))
+}

src/channels/web/handlers/users.rs

@@ -0,0 +1,406 @@
+//! User management API handlers (admin).
+
+use std::sync::Arc;
+
+use axum::{
+    Json,
+    extract::{Path, State},
+    http::StatusCode,
+};
+use rand::RngCore;
+use rand::rngs::OsRng;
+use uuid::Uuid;
+
+use crate::channels::web::auth::{AdminUser, AuthenticatedUser};
+use crate::channels::web::server::GatewayState;
+use crate::db::UserRecord;
+
+/// POST /api/admin/users — create a new user.
+pub async fn users_create_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(user): AdminUser,
+    Json(body): Json<serde_json::Value>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    let display_name = body
+        .get("display_name")
+        .and_then(|v| v.as_str())
+        .ok_or((
+            StatusCode::BAD_REQUEST,
+            "Missing required field 'display_name'".to_string(),
+        ))?
+        .to_string();
+
+    let email = body.get("email").and_then(|v| v.as_str()).map(String::from);
+    let role = body
+        .get("role")
+        .and_then(|v| v.as_str())
+        .unwrap_or("member")
+        .to_string();
+    if role != "admin" && role != "member" {
+        return Err((
+            StatusCode::BAD_REQUEST,
+            "role must be 'admin' or 'member'".to_string(),
+        ));
+    }
+
+    let user_id = Uuid::new_v4().to_string();
+
+    let now = chrono::Utc::now();
+    let user_record = UserRecord {
+        id: user_id.clone(),
+        email,
+        display_name: display_name.clone(),
+        status: "active".to_string(),
+        role,
+        created_at: now,
+        updated_at: now,
+        last_login_at: None,
+        created_by: match store.get_user(&user.user_id).await {
+            Ok(Some(_)) => Some(user.user_id.clone()),
+            _ => None,
+        },
+        metadata: serde_json::json!({}),
+    };
+
+    store
+        .create_user(&user_record)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    // Generate a first API token so the new user can authenticate immediately.
+    // Hash the hex-encoded plaintext (what the user sends as Bearer token),
+    // NOT the raw bytes — must match hash_token() in auth.rs.
+    let mut token_bytes = [0u8; 32];
+    OsRng.fill_bytes(&mut token_bytes);
+    let plaintext_token = hex::encode(token_bytes);
+    let token_hash = crate::channels::web::auth::hash_token(&plaintext_token);
+    let token_prefix = &plaintext_token[..8];
+
+    let _token_record = store
+        .create_api_token(&user_id, "initial", &token_hash, token_prefix, None)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    Ok(Json(serde_json::json!({
+        "id": user_record.id,
+        "email": user_record.email,
+        "display_name": user_record.display_name,
+        "status": user_record.status,
+        "role": user_record.role,
+        "token": plaintext_token,
+        "created_at": user_record.created_at.to_rfc3339(),
+        "created_by": user_record.created_by,
+    })))
+}
+
+/// GET /api/admin/users — list all users.
+pub async fn users_list_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_user): AdminUser,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    let users = store
+        .list_users(None)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    let users_json: Vec<serde_json::Value> = users
+        .into_iter()
+        .map(|u| {
+            serde_json::json!({
+                "id": u.id,
+                "email": u.email,
+                "display_name": u.display_name,
+                "status": u.status,
+                "role": u.role,
+                "created_at": u.created_at.to_rfc3339(),
+                "updated_at": u.updated_at.to_rfc3339(),
+                "last_login_at": u.last_login_at.map(|dt| dt.to_rfc3339()),
+                "created_by": u.created_by,
+            })
+        })
+        .collect();
+
+    Ok(Json(serde_json::json!({ "users": users_json })))
+}
+
+/// GET /api/admin/users/{id} — get a single user.
+pub async fn users_detail_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_user): AdminUser,
+    Path(id): Path<String>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    let user_record = store
+        .get_user(&id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?
+        .ok_or((StatusCode::NOT_FOUND, "User not found".to_string()))?;
+
+    Ok(Json(serde_json::json!({
+        "id": user_record.id,
+        "email": user_record.email,
+        "display_name": user_record.display_name,
+        "status": user_record.status,
+        "role": user_record.role,
+        "created_at": user_record.created_at.to_rfc3339(),
+        "updated_at": user_record.updated_at.to_rfc3339(),
+        "last_login_at": user_record.last_login_at.map(|dt| dt.to_rfc3339()),
+        "created_by": user_record.created_by,
+        "metadata": user_record.metadata,
+    })))
+}
+
+/// PATCH /api/admin/users/{id} — update a user's profile.
+pub async fn users_update_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_user): AdminUser,
+    Path(id): Path<String>,
+    Json(body): Json<serde_json::Value>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    // Verify the user exists.
+    let existing = store
+        .get_user(&id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?
+        .ok_or((StatusCode::NOT_FOUND, "User not found".to_string()))?;
+
+    let display_name = body
+        .get("display_name")
+        .and_then(|v| v.as_str())
+        .unwrap_or(&existing.display_name);
+
+    let metadata = body.get("metadata").unwrap_or(&existing.metadata);
+
+    store
+        .update_user_profile(&id, display_name, metadata)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    // Re-fetch the updated record to return consistent data.
+    let updated = store
+        .get_user(&id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?
+        .ok_or((StatusCode::NOT_FOUND, "User not found".to_string()))?;
+
+    Ok(Json(serde_json::json!({
+        "id": updated.id,
+        "email": updated.email,
+        "display_name": updated.display_name,
+        "status": updated.status,
+        "role": updated.role,
+        "created_at": updated.created_at.to_rfc3339(),
+        "updated_at": updated.updated_at.to_rfc3339(),
+        "metadata": updated.metadata,
+    })))
+}
+
+/// POST /api/admin/users/{id}/suspend — suspend a user.
+pub async fn users_suspend_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_user): AdminUser,
+    Path(id): Path<String>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    // Verify the user exists.
+    store
+        .get_user(&id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?
+        .ok_or((StatusCode::NOT_FOUND, "User not found".to_string()))?;
+
+    store
+        .update_user_status(&id, "suspended")
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    Ok(Json(serde_json::json!({
+        "id": id,
+        "status": "suspended",
+    })))
+}
+
+/// POST /api/admin/users/{id}/activate — activate a user.
+pub async fn users_activate_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_user): AdminUser,
+    Path(id): Path<String>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    // Verify the user exists.
+    store
+        .get_user(&id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?
+        .ok_or((StatusCode::NOT_FOUND, "User not found".to_string()))?;
+
+    store
+        .update_user_status(&id, "active")
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    Ok(Json(serde_json::json!({
+        "id": id,
+        "status": "active",
+    })))
+}
+
+/// DELETE /api/admin/users/{id} — delete a user and all their data.
+pub async fn users_delete_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_user): AdminUser,
+    Path(id): Path<String>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    let deleted = store
+        .delete_user(&id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    if !deleted {
+        return Err((StatusCode::NOT_FOUND, "User not found".to_string()));
+    }
+
+    Ok(Json(serde_json::json!({
+        "id": id,
+        "deleted": true,
+    })))
+}
+
+/// GET /api/profile — get the authenticated user's own profile.
+pub async fn profile_get_handler(
+    State(state): State<Arc<GatewayState>>,
+    AuthenticatedUser(user): AuthenticatedUser,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    let record = store
+        .get_user(&user.user_id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?
+        .ok_or((StatusCode::NOT_FOUND, "User not found".to_string()))?;
+
+    Ok(Json(serde_json::json!({
+        "id": record.id,
+        "email": record.email,
+        "display_name": record.display_name,
+        "status": record.status,
+        "role": record.role,
+        "created_at": record.created_at.to_rfc3339(),
+        "last_login_at": record.last_login_at.map(|dt| dt.to_rfc3339()),
+    })))
+}
+
+/// PATCH /api/profile — update the authenticated user's own profile.
+pub async fn profile_update_handler(
+    State(state): State<Arc<GatewayState>>,
+    AuthenticatedUser(user): AuthenticatedUser,
+    Json(body): Json<serde_json::Value>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    let current = store
+        .get_user(&user.user_id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?
+        .ok_or((StatusCode::NOT_FOUND, "User not found".to_string()))?;
+
+    let display_name = body
+        .get("display_name")
+        .and_then(|v| v.as_str())
+        .unwrap_or(&current.display_name);
+    let metadata = body.get("metadata").unwrap_or(&current.metadata);
+
+    store
+        .update_user_profile(&user.user_id, display_name, metadata)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    Ok(Json(serde_json::json!({
+        "id": user.user_id,
+        "display_name": display_name,
+        "updated": true,
+    })))
+}
+
+/// GET /api/admin/usage — per-user LLM usage stats.
+pub async fn usage_stats_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_user): AdminUser,
+    axum::extract::Query(params): axum::extract::Query<std::collections::HashMap<String, String>>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let store = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    let user_id = params.get("user_id").map(|s| s.as_str());
+    let period = params.get("period").map(|s| s.as_str()).unwrap_or("day");
+    let since = match period {
+        "week" => chrono::Utc::now() - chrono::Duration::days(7),
+        "month" => chrono::Utc::now() - chrono::Duration::days(30),
+        _ => chrono::Utc::now() - chrono::Duration::days(1),
+    };
+
+    let stats = store
+        .user_usage_stats(user_id, since)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    let entries: Vec<serde_json::Value> = stats
+        .iter()
+        .map(|s| {
+            serde_json::json!({
+                "user_id": s.user_id,
+                "model": s.model,
+                "call_count": s.call_count,
+                "input_tokens": s.input_tokens,
+                "output_tokens": s.output_tokens,
+                "total_cost": s.total_cost.to_string(),
+            })
+        })
+        .collect();
+
+    Ok(Json(serde_json::json!({
+        "period": period,
+        "since": since.to_rfc3339(),
+        "usage": entries,
+    })))
+}

src/channels/web/mod.rs

@@ -18,6 +18,7 @@ pub mod auth;
 pub(crate) mod handlers;
 pub mod log_layer;
 pub mod openai_compat;
+pub mod responses_api;
 pub mod server;
 pub mod sse;
 pub mod types;
@@ -55,7 +56,7 @@ use crate::workspace::Workspace;
 
 use self::log_layer::{LogBroadcaster, LogLevelHandle};
 
-use self::auth::MultiAuthState;
+use self::auth::{CombinedAuthState, DbAuthenticator, MultiAuthState};
 use self::server::GatewayState;
 use self::sse::SseManager;
 use self::types::AppEvent;
@@ -64,8 +65,8 @@ use self::types::AppEvent;
 pub struct GatewayChannel {
     config: GatewayConfig,
     state: Arc<GatewayState>,
-    /// Multi-user auth state (replaces bare auth_token).
-    auth: MultiAuthState,
+    /// Combined auth state: env-var tokens + optional DB-backed tokens.
+    auth: CombinedAuthState,
 }
 
 impl GatewayChannel {
@@ -73,7 +74,7 @@ impl GatewayChannel {
     ///
     /// If no auth token is configured, generates a random one and prints it.
     /// Builds a single-user `MultiAuthState` from the config.
-    pub fn new(config: GatewayConfig) -> Self {
+    pub fn new(config: GatewayConfig, owner_id: String) -> Self {
         let auth_token = config.auth_token.clone().unwrap_or_else(|| {
             use rand::RngCore;
             use rand::rngs::OsRng;
@@ -82,64 +83,11 @@ impl GatewayChannel {
             bytes.iter().map(|b| format!("{b:02x}")).collect()
         });
 
-        let auth = MultiAuthState::single(auth_token, config.user_id.clone());
-
-        let state = Arc::new(GatewayState {
-            msg_tx: tokio::sync::RwLock::new(None),
-            sse: Arc::new(SseManager::new()),
-            workspace: None,
-            workspace_pool: None,
-            session_manager: None,
-            log_broadcaster: None,
-            log_level_handle: None,
-            extension_manager: None,
-            tool_registry: None,
-            store: None,
-            job_manager: None,
-            prompt_queue: None,
-            scheduler: None,
-            owner_id: config.user_id.clone(),
-            default_sender_id: config.user_id.clone(),
-            shutdown_tx: tokio::sync::RwLock::new(None),
-            ws_tracker: Some(Arc::new(ws::WsConnectionTracker::new())),
-            llm_provider: None,
-            skill_registry: None,
-            skill_catalog: None,
-            chat_rate_limiter: server::PerUserRateLimiter::new(30, 60),
-            oauth_rate_limiter: server::RateLimiter::new(10, 60),
-            webhook_rate_limiter: server::RateLimiter::new(10, 60),
-            registry_entries: Vec::new(),
-            cost_guard: None,
-            routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
-            startup_time: std::time::Instant::now(),
-            active_config: server::ActiveConfigSnapshot::default(),
-        });
-
-        Self {
-            config,
-            state,
-            auth,
-        }
-    }
-
-    /// Rebind the single-user auth identity to the durable owner scope while
-    /// preserving the configured gateway sender/routing identity.
-    pub fn with_owner_scope(mut self, owner_id: impl Into<String>) -> Self {
-        let owner_id = owner_id.into();
-        let single_user_token = if self.config.user_tokens.is_none() {
-            self.auth.first_token().map(ToOwned::to_owned)
-        } else {
-            None
+        let auth = CombinedAuthState {
+            env_auth: MultiAuthState::single(auth_token, owner_id.clone()),
+            db_auth: None,
         };
-        if let Some(token) = single_user_token {
-            self.auth = MultiAuthState::single(token, owner_id.clone());
-        }
-        self.rebuild_state(|s| s.owner_id = owner_id);
-        self
-    }
 
-    /// Create a gateway channel with a pre-built multi-user auth state.
-    pub fn new_multi_auth(config: GatewayConfig, auth: MultiAuthState) -> Self {
         let state = Arc::new(GatewayState {
             msg_tx: tokio::sync::RwLock::new(None),
             sse: Arc::new(SseManager::new()),
@@ -154,8 +102,7 @@ impl GatewayChannel {
             job_manager: None,
             prompt_queue: None,
             scheduler: None,
-            owner_id: config.user_id.clone(),
-            default_sender_id: config.user_id.clone(),
+            owner_id,
             shutdown_tx: tokio::sync::RwLock::new(None),
             ws_tracker: Some(Arc::new(ws::WsConnectionTracker::new())),
             llm_provider: None,
@@ -163,12 +110,13 @@ impl GatewayChannel {
             skill_catalog: None,
             chat_rate_limiter: server::PerUserRateLimiter::new(30, 60),
             oauth_rate_limiter: server::RateLimiter::new(10, 60),
+            webhook_rate_limiter: server::RateLimiter::new(10, 60),
             registry_entries: Vec::new(),
             cost_guard: None,
             routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
             startup_time: std::time::Instant::now(),
-            webhook_rate_limiter: server::RateLimiter::new(10, 60),
             active_config: server::ActiveConfigSnapshot::default(),
+            secrets_store: None,
         });
 
         Self {
@@ -196,7 +144,6 @@ impl GatewayChannel {
             prompt_queue: self.state.prompt_queue.clone(),
             scheduler: self.state.scheduler.clone(),
             owner_id: self.state.owner_id.clone(),
-            default_sender_id: self.state.default_sender_id.clone(),
             shutdown_tx: tokio::sync::RwLock::new(None),
             ws_tracker: self.state.ws_tracker.clone(),
             llm_provider: self.state.llm_provider.clone(),
@@ -210,6 +157,7 @@ impl GatewayChannel {
             routine_engine: Arc::clone(&self.state.routine_engine),
             startup_time: self.state.startup_time,
             active_config: self.state.active_config.clone(),
+            secrets_store: self.state.secrets_store.clone(),
         };
         mutate(&mut new_state);
         self.state = Arc::new(new_state);
@@ -257,6 +205,12 @@ impl GatewayChannel {
         self
     }
 
+    /// Enable DB-backed token authentication alongside env-var tokens.
+    pub fn with_db_auth(mut self, store: Arc<dyn Database>) -> Self {
+        self.auth.db_auth = Some(DbAuthenticator::new(store));
+        self
+    }
+
     /// Inject the container job manager for sandbox operations.
     pub fn with_job_manager(mut self, jm: Arc<ContainerJobManager>) -> Self {
         self.rebuild_state(|s| s.job_manager = Some(jm));
@@ -327,6 +281,15 @@ impl GatewayChannel {
         self
     }
 
+    /// Inject the secrets store for admin secret provisioning.
+    pub fn with_secrets_store(
+        mut self,
+        store: Arc<dyn crate::secrets::SecretsStore + Send + Sync>,
+    ) -> Self {
+        self.rebuild_state(|s| s.secrets_store = Some(store));
+        self
+    }
+
     /// Inject the per-user workspace pool for multi-user mode.
     pub fn with_workspace_pool(mut self, pool: Arc<server::WorkspacePool>) -> Self {
         self.rebuild_state(|s| s.workspace_pool = Some(pool));
@@ -335,7 +298,7 @@ impl GatewayChannel {
 
     /// Get the first auth token (for printing to console on startup).
     pub fn auth_token(&self) -> &str {
-        self.auth.first_token().unwrap_or("")
+        self.auth.env_auth.first_token().unwrap_or("")
     }
 
     /// Get a reference to the shared gateway state (for the agent to push SSE events).

src/channels/web/server.rs

@@ -16,7 +16,7 @@ use axum::{
         IntoResponse,
         sse::{Event, KeepAlive, Sse},
     },
-    routing::{get, post},
+    routing::{get, post, put},
 };
 use serde::Deserialize;
 use sha2::{Digest, Sha256};
@@ -31,7 +31,7 @@ use crate::bootstrap::ironclaw_base_dir;
 use crate::channels::IncomingMessage;
 use crate::channels::relay::DEFAULT_RELAY_NAME;
 use crate::channels::web::auth::{
-    AuthenticatedUser, MultiAuthState, UserIdentity, auth_middleware,
+    AuthenticatedUser, CombinedAuthState, UserIdentity, auth_middleware,
 };
 use crate::channels::web::handlers::jobs::{
     job_files_list_handler, job_files_read_handler, jobs_cancel_handler, jobs_detail_handler,
@@ -347,8 +347,6 @@ pub struct GatewayState {
     pub prompt_queue: Option<PromptQueue>,
     /// Durable owner scope for persistence and unauthenticated callback flows.
     pub owner_id: String,
-    /// Default sender/routing identity for gateway-originated messages.
-    pub default_sender_id: String,
     /// Shutdown signal sender.
     pub shutdown_tx: tokio::sync::RwLock<Option<oneshot::Sender<()>>>,
     /// WebSocket connection tracker.
@@ -378,6 +376,8 @@ pub struct GatewayState {
     pub startup_time: std::time::Instant,
     /// Snapshot of active (resolved) configuration for the frontend.
     pub active_config: ActiveConfigSnapshot,
+    /// Secrets store for admin secret provisioning.
+    pub secrets_store: Option<Arc<dyn crate::secrets::SecretsStore + Send + Sync>>,
 }
 
 /// Start the gateway HTTP server.
@@ -386,7 +386,7 @@ pub struct GatewayState {
 pub async fn start_server(
     addr: SocketAddr,
     state: Arc<GatewayState>,
-    auth: MultiAuthState,
+    auth: CombinedAuthState,
 ) -> Result<SocketAddr, crate::error::ChannelError> {
     let listener = tokio::net::TcpListener::bind(addr).await.map_err(|e| {
         crate::error::ChannelError::StartupFailed {
@@ -512,6 +512,57 @@ pub async fn start_server(
             "/api/settings/{key}",
             axum::routing::delete(settings_delete_handler),
         )
+        // User management (admin)
+        .route(
+            "/api/admin/users",
+            get(super::handlers::users::users_list_handler)
+                .post(super::handlers::users::users_create_handler),
+        )
+        .route(
+            "/api/admin/users/{id}",
+            get(super::handlers::users::users_detail_handler)
+                .patch(super::handlers::users::users_update_handler)
+                .delete(super::handlers::users::users_delete_handler),
+        )
+        .route(
+            "/api/admin/users/{id}/suspend",
+            post(super::handlers::users::users_suspend_handler),
+        )
+        .route(
+            "/api/admin/users/{id}/activate",
+            post(super::handlers::users::users_activate_handler),
+        )
+        // Admin secrets provisioning (per-user)
+        .route(
+            "/api/admin/users/{user_id}/secrets",
+            get(super::handlers::secrets::secrets_list_handler),
+        )
+        .route(
+            "/api/admin/users/{user_id}/secrets/{name}",
+            put(super::handlers::secrets::secrets_put_handler)
+                .delete(super::handlers::secrets::secrets_delete_handler),
+        )
+        // Usage reporting (admin)
+        .route(
+            "/api/admin/usage",
+            get(super::handlers::users::usage_stats_handler),
+        )
+        // User self-service profile
+        .route(
+            "/api/profile",
+            get(super::handlers::users::profile_get_handler)
+                .patch(super::handlers::users::profile_update_handler),
+        )
+        // Token management
+        .route(
+            "/api/tokens",
+            get(super::handlers::tokens::tokens_list_handler)
+                .post(super::handlers::tokens::tokens_create_handler),
+        )
+        .route(
+            "/api/tokens/{id}",
+            axum::routing::delete(super::handlers::tokens::tokens_revoke_handler),
+        )
         // Gateway control plane
         .route("/api/gateway/status", get(gateway_status_handler))
         // OpenAI-compatible API
@@ -520,6 +571,15 @@ pub async fn start_server(
             post(super::openai_compat::chat_completions_handler),
         )
         .route("/v1/models", get(super::openai_compat::models_handler))
+        // OpenAI Responses API (routes through the full agent loop)
+        .route(
+            "/v1/responses",
+            post(super::responses_api::create_response_handler),
+        )
+        .route(
+            "/v1/responses/{id}",
+            get(super::responses_api::get_response_handler),
+        )
         .route_layer(middleware::from_fn_with_state(
             auth_state.clone(),
             auth_middleware,
@@ -562,6 +622,7 @@ pub async fn start_server(
             axum::http::Method::GET,
             axum::http::Method::POST,
             axum::http::Method::PUT,
+            axum::http::Method::PATCH,
             axum::http::Method::DELETE,
         ])
         .allow_headers(AllowHeaders::list([
@@ -576,6 +637,25 @@ pub async fn start_server(
         .merge(projects)
         .merge(protected)
         .layer(DefaultBodyLimit::max(10 * 1024 * 1024)) // 10 MB max request body (image uploads)
+        .layer(tower_http::catch_panic::CatchPanicLayer::custom(
+            |panic_info: Box<dyn std::any::Any + Send + 'static>| {
+                let detail = if let Some(s) = panic_info.downcast_ref::<String>() {
+                    s.clone()
+                } else if let Some(s) = panic_info.downcast_ref::<&str>() {
+                    (*s).to_string()
+                } else {
+                    "unknown panic".to_string()
+                };
+                tracing::error!("Handler panicked: {}", detail);
+                axum::http::Response::builder()
+                    .status(axum::http::StatusCode::INTERNAL_SERVER_ERROR)
+                    .header("content-type", "text/plain")
+                    .body(axum::body::Body::from("Internal Server Error"))
+                    .unwrap_or_else(|_| {
+                        axum::http::Response::new(axum::body::Body::from("Internal Server Error"))
+                    })
+            },
+        ))
         .layer(cors)
         .layer(SetResponseHeaderLayer::if_not_present(
             header::X_CONTENT_TYPE_OPTIONS,
@@ -1303,9 +1383,6 @@ async fn chat_send_handler(
     }
 
     let mut msg = IncomingMessage::new("gateway", &user.user_id, &req.content);
-    if state.owner_id != state.default_sender_id && user.user_id == state.owner_id {
-        msg = msg.with_sender_id(&state.default_sender_id);
-    }
     // Prefer timezone from JSON body, fall back to X-Timezone header
     let tz = req
         .timezone
@@ -1407,9 +1484,6 @@ async fn chat_approval_handler(
     })?;
 
     let mut msg = IncomingMessage::new("gateway", &user.user_id, content);
-    if state.owner_id != state.default_sender_id && user.user_id == state.owner_id {
-        msg = msg.with_sender_id(&state.default_sender_id);
-    }
 
     if let Some(ref thread_id) = req.thread_id {
         msg = msg.with_thread(thread_id);
@@ -2985,7 +3059,6 @@ mod tests {
             job_manager: None,
             prompt_queue: None,
             owner_id: "test".to_string(),
-            default_sender_id: "test".to_string(),
             shutdown_tx: tokio::sync::RwLock::new(None),
             ws_tracker: None,
             llm_provider: None,
@@ -3000,6 +3073,7 @@ mod tests {
             routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
             startup_time: std::time::Instant::now(),
             active_config: ActiveConfigSnapshot::default(),
+            secrets_store: None,
         })
     }
 
@@ -3066,6 +3140,7 @@ mod tests {
         // without needing the full auth middleware layer.
         req.extensions_mut().insert(UserIdentity {
             user_id: "test".to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: Vec::new(),
         });
 
@@ -3150,6 +3225,7 @@ mod tests {
         // without needing the full auth middleware layer.
         req.extensions_mut().insert(UserIdentity {
             user_id: "test".to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: Vec::new(),
         });
 
@@ -3199,7 +3275,10 @@ mod tests {
         let state = test_gateway_state(None);
 
         let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
-        let auth = MultiAuthState::single("test-token".to_string(), "test".to_string());
+        let auth = CombinedAuthState::from(crate::channels::web::auth::MultiAuthState::single(
+            "test-token".to_string(),
+            "test".to_string(),
+        ));
         let bound = start_server(addr, state.clone(), auth)
             .await
             .expect("server should start");

src/channels/web/static/app.js

@@ -186,6 +186,13 @@ function authenticate() {
       connectSSE();
       connectLogSSE();
       startGatewayStatusPolling();
+      // Hide the Users settings tab for non-admin users.
+      apiFetch('/api/profile').then(function(profile) {
+        if (profile && profile.role !== 'admin') {
+          var usersTab = document.querySelector('[data-settings-subtab="users"]');
+          if (usersTab) usersTab.style.display = 'none';
+        }
+      }).catch(function() {});
       checkTeeStatus();
       loadThreads();
       loadMemoryTree();
@@ -4339,6 +4346,142 @@ function formatRelativeTime(isoString) {
   return future ? I18n.t('time.daysFromNow', { n: days }) : I18n.t('time.daysAgo', { n: days });
 }
 
+// --- Users (admin) ---
+
+function loadUsers() {
+  apiFetch('/api/admin/users').then(function(data) {
+    renderUsersList(data.users || []);
+  }).catch(function(err) {
+    // Non-admin users get 403 — show a message instead of an error
+    var tbody = document.getElementById('users-tbody');
+    var empty = document.getElementById('users-empty');
+    if (tbody) tbody.innerHTML = '';
+    if (empty) {
+      empty.style.display = 'block';
+      empty.textContent = 'Admin access required to manage users.';
+    }
+  });
+}
+
+function renderUsersList(users) {
+  var tbody = document.getElementById('users-tbody');
+  var empty = document.getElementById('users-empty');
+  if (!users || users.length === 0) {
+    tbody.innerHTML = '';
+    empty.style.display = 'block';
+    empty.textContent = 'No users found. Create the first user to get started.';
+    return;
+  }
+  empty.style.display = 'none';
+  tbody.innerHTML = users.map(function(u) {
+    var statusClass = u.status === 'active' ? 'active' : 'failed';
+    var roleLabel = u.role === 'admin' ? '<span class="badge badge-admin">admin</span>' : '<span class="badge">member</span>';
+    var actions = '';
+    if (u.status === 'active') {
+      actions += '<button class="btn-small btn-danger" data-action="suspend-user" data-user-id="' + escapeHtml(u.id) + '">Suspend</button> ';
+    } else {
+      actions += '<button class="btn-small btn-primary" data-action="activate-user" data-user-id="' + escapeHtml(u.id) + '">Activate</button> ';
+    }
+    actions += '<button class="btn-small" data-action="create-token" data-user-id="' + escapeHtml(u.id) + '" data-user-name="' + escapeHtml(u.display_name) + '">+ Token</button>';
+    return '<tr>'
+      + '<td class="user-id" title="' + escapeHtml(u.id) + '">' + escapeHtml(u.id.substring(0, 8)) + '…</td>'
+      + '<td>' + escapeHtml(u.display_name) + '</td>'
+      + '<td>' + escapeHtml(u.email || '—') + '</td>'
+      + '<td>' + roleLabel + '</td>'
+      + '<td><span class="status-badge ' + statusClass + '">' + escapeHtml(u.status) + '</span></td>'
+      + '<td>' + formatRelativeTime(u.created_at) + '</td>'
+      + '<td>' + actions + '</td>'
+      + '</tr>';
+  }).join('');
+}
+
+function suspendUser(userId) {
+  apiFetch('/api/admin/users/' + userId + '/suspend', { method: 'POST' })
+    .then(function() { loadUsers(); })
+    .catch(function(e) { alert('Failed to suspend user: ' + e.message); });
+}
+
+function activateUser(userId) {
+  apiFetch('/api/admin/users/' + userId + '/activate', { method: 'POST' })
+    .then(function() { loadUsers(); })
+    .catch(function(e) { alert('Failed to activate user: ' + e.message); });
+}
+
+function createTokenForUser(userId, displayName) {
+  var tokenName = prompt('Token name for ' + displayName + ':', 'api-token');
+  if (!tokenName) return;
+  apiFetch('/api/tokens', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name: tokenName, user_id: userId }),
+  }).then(function(data) {
+    showTokenBanner(data.token);
+  }).catch(function(e) { alert('Failed to create token: ' + e.message); });
+}
+
+function showTokenBanner(tokenValue) {
+  var banner = document.getElementById('users-token-result');
+  if (!banner) return;
+  var loginUrl = window.location.origin + '/?token=' + encodeURIComponent(tokenValue);
+  banner.style.display = 'block';
+  banner.innerHTML = '<strong>User created!</strong> Share this login link — it won\'t be shown again:<br>'
+    + '<code class="token-display" id="token-copy-value">' + escapeHtml(loginUrl) + '</code>'
+    + '<button class="btn-small" id="token-copy-link">Copy Link</button>'
+    + '<br><span style="font-size:0.8em;color:var(--text-muted)">Raw token: ' + escapeHtml(tokenValue) + '</span>';
+  document.getElementById('token-copy-link').addEventListener('click', function() {
+    navigator.clipboard.writeText(loginUrl);
+    this.textContent = 'Copied!';
+  });
+}
+
+// Delegated click handler for user action buttons (CSP-safe, no inline onclick)
+document.getElementById('users-table')?.addEventListener('click', function(e) {
+  var btn = e.target.closest('[data-action]');
+  if (!btn) return;
+  var action = btn.getAttribute('data-action');
+  var userId = btn.getAttribute('data-user-id');
+  var userName = btn.getAttribute('data-user-name');
+  if (action === 'suspend-user') suspendUser(userId);
+  else if (action === 'activate-user') activateUser(userId);
+  else if (action === 'create-token') createTokenForUser(userId, userName || '');
+});
+
+// Wire up Users tab create form
+document.getElementById('users-create-btn')?.addEventListener('click', function() {
+  document.getElementById('users-create-form').style.display = 'flex';
+  document.getElementById('users-token-result').style.display = 'none';
+  document.getElementById('user-display-name').focus();
+});
+
+document.getElementById('users-create-cancel')?.addEventListener('click', function() {
+  document.getElementById('users-create-form').style.display = 'none';
+});
+
+document.getElementById('users-create-submit')?.addEventListener('click', function() {
+  var displayName = document.getElementById('user-display-name').value.trim();
+  var email = document.getElementById('user-email').value.trim();
+  var role = document.getElementById('user-role').value;
+  if (!displayName) { alert('Display name is required'); return; }
+
+  apiFetch('/api/admin/users', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      display_name: displayName,
+      email: email || undefined,
+      role: role,
+    }),
+  }).then(function(data) {
+    document.getElementById('users-create-form').style.display = 'none';
+    document.getElementById('user-display-name').value = '';
+    document.getElementById('user-email').value = '';
+    if (data.token) {
+      showTokenBanner(data.token);
+    }
+    loadUsers();
+  }).catch(function(e) { alert('Failed to create user: ' + e.message); });
+});
+
 // --- Gateway status widget ---
 
 let gatewayStatusInterval = null;
@@ -5028,6 +5171,7 @@ function loadSettingsSubtab(subtab) {
   else if (subtab === 'extensions') { loadExtensions(); startPairingPoll(); }
   else if (subtab === 'mcp') loadMcpServers();
   else if (subtab === 'skills') loadSkills();
+  else if (subtab === 'users') loadUsers();
   if (subtab !== 'extensions' && subtab !== 'channels') stopPairingPoll();
 }
 

src/channels/web/static/i18n/en.js

@@ -9,8 +9,6 @@ I18n.register('en', {
   'auth.connect': 'Connect',
   'auth.errorRequired': 'Token required',
   'auth.errorInvalid': 'Invalid token',
-  'auth.hint': 'Enter the GATEWAY_AUTH_TOKEN from your .env file',
-  
   // Chat
   'chat.inputPlaceholder': 'Message or / for commands...',
   
@@ -44,7 +42,8 @@ I18n.register('en', {
   'settings.channels': 'Channels',
   'settings.networking': 'Networking',
   'settings.mcp': 'MCP',
-  
+  'settings.users': 'Users',
+
   // Status
   'status.connected': 'Connected',
   'status.disconnected': 'Disconnected',

src/channels/web/static/i18n/zh-CN.js

@@ -9,8 +9,6 @@ I18n.register('zh-CN', {
   'auth.connect': '连接',
   'auth.errorRequired': '请输入令牌',
   'auth.errorInvalid': '令牌无效',
-  'auth.hint': '输入 .env 配置文件中的 GATEWAY_AUTH_TOKEN',
-  
   // 聊天
   'chat.inputPlaceholder': '输入消息或 / 以使用命令...',
   
@@ -44,7 +42,8 @@ I18n.register('zh-CN', {
   'settings.channels': '频道',
   'settings.networking': '网络',
   'settings.mcp': 'MCP',
-  
+  'settings.users': '用户管理',
+
   // 状态
   'status.connected': '已连接',
   'status.disconnected': '已断开',

src/channels/web/static/index.html

@@ -41,7 +41,6 @@
         <button id="auth-connect-btn" data-i18n="auth.connect">Connect</button>
       </div>
       <div id="auth-error"></div>
-      <p class="auth-hint" data-i18n="auth.hint">Enter the GATEWAY_AUTH_TOKEN from your .env configuration.</p>
     </div>
   </div>
 
@@ -293,6 +292,7 @@
           <button class="settings-subtab" data-settings-subtab="extensions" data-i18n="tab.extensions">Extensions</button>
           <button class="settings-subtab" data-settings-subtab="mcp" data-i18n="settings.mcp">MCP</button>
           <button class="settings-subtab" data-settings-subtab="skills" data-i18n="tab.skills">Skills</button>
+          <button class="settings-subtab" data-settings-subtab="users" data-i18n="settings.users">Users</button>
           <button class="settings-theme-toggle" id="settings-theme-toggle" data-i18n="theme.tooltipSystem" title="Toggle theme">Theme</button>
         </div>
         <div class="settings-content">
@@ -390,6 +390,29 @@
               </div>
             </div>
           </div>
+          <div class="settings-subpanel" id="settings-users">
+            <div class="users-container">
+              <div class="users-header">
+                <h3>User Management</h3>
+                <button id="users-create-btn" class="btn-primary">+ New User</button>
+              </div>
+              <div id="users-create-form" style="display:none" class="users-form" autocomplete="off">
+                <input type="text" id="user-display-name" placeholder="Display name" autocomplete="off" />
+                <input type="text" id="user-email" placeholder="Email (optional)" autocomplete="off" />
+                <select id="user-role"><option value="member">Member</option><option value="admin">Admin</option></select>
+                <button id="users-create-submit" class="btn-primary">Create</button>
+                <button id="users-create-cancel" class="btn-secondary">Cancel</button>
+              </div>
+              <div id="users-token-result" style="display:none" class="users-token-banner"></div>
+              <table class="routines-table" id="users-table">
+                <thead><tr>
+                  <th>ID</th><th>Display Name</th><th>Email</th><th>Role</th><th>Status</th><th>Created</th><th>Actions</th>
+                </tr></thead>
+                <tbody id="users-tbody"></tbody>
+              </table>
+              <div id="users-empty" class="empty-state" style="display:none">No users found. Create the first user to get started.</div>
+            </div>
+          </div>
         </div>
       </div>
     </div>

src/channels/web/static/style.css

@@ -5429,3 +5429,22 @@ body.theme-transition *:not(svg):not(path):not(line):not(circle):not(rect) {
     --text-muted: #a1a1aa;
   }
 }
+
+/* --- Users Tab --- */
+.users-container { padding: 1rem; }
+.users-header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 1rem; }
+.users-header h3 { margin: 0; font-size: 1.1rem; }
+.users-form { display: flex; gap: 0.5rem; align-items: center; margin-bottom: 1rem; flex-wrap: wrap; }
+.users-form input, .users-form select { padding: 0.4rem 0.6rem; border-radius: 6px; border: 1px solid var(--border); background: var(--bg-secondary); color: var(--text-primary); font-size: 0.85rem; }
+.users-token-banner { background: var(--bg-tertiary); border: 1px solid var(--accent); border-radius: 8px; padding: 0.75rem 1rem; margin-bottom: 1rem; font-size: 0.85rem; }
+.token-display { display: inline-block; padding: 0.3rem 0.6rem; background: var(--bg-primary); border-radius: 4px; font-family: var(--font-mono); word-break: break-all; margin: 0.4rem 0; user-select: all; }
+.user-id { font-family: var(--font-mono); font-size: 0.8rem; color: var(--text-muted); }
+.badge { display: inline-block; padding: 0.15rem 0.5rem; border-radius: 10px; font-size: 0.75rem; background: var(--bg-tertiary); color: var(--text-secondary); }
+.badge-admin { background: var(--accent); color: #fff; }
+.btn-small { padding: 0.25rem 0.5rem; font-size: 0.75rem; border-radius: 4px; border: 1px solid var(--border); background: var(--bg-secondary); color: var(--text-primary); cursor: pointer; }
+.btn-small:hover { background: var(--bg-tertiary); }
+.btn-danger { border-color: #ef4444; color: #ef4444; }
+.btn-danger:hover { background: #ef4444; color: #fff; }
+.btn-primary { background: var(--accent); color: #fff; border: none; padding: 0.4rem 0.8rem; border-radius: 6px; cursor: pointer; font-size: 0.85rem; }
+.btn-primary:hover { opacity: 0.9; }
+.btn-secondary { background: var(--bg-tertiary); color: var(--text-primary); border: 1px solid var(--border); padding: 0.4rem 0.8rem; border-radius: 6px; cursor: pointer; font-size: 0.85rem; }

src/channels/web/test_helpers.rs

@@ -77,7 +77,6 @@ impl TestGatewayBuilder {
             job_manager: None,
             prompt_queue: None,
             owner_id: self.user_id.clone(),
-            default_sender_id: self.user_id,
             shutdown_tx: tokio::sync::RwLock::new(None),
             ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
             llm_provider: self.llm_provider,
@@ -92,6 +91,7 @@ impl TestGatewayBuilder {
             routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
             startup_time: std::time::Instant::now(),
             active_config: crate::channels::web::server::ActiveConfigSnapshot::default(),
+            secrets_store: None,
         })
     }
 
@@ -106,7 +106,7 @@ impl TestGatewayBuilder {
         let addr: SocketAddr = "127.0.0.1:0"
             .parse()
             .expect("hard-coded address must parse"); // safety: constant literal
-        let bound = start_server(addr, state.clone(), auth).await?;
+        let bound = start_server(addr, state.clone(), auth.into()).await?;
         Ok((bound, state))
     }
 
@@ -120,7 +120,7 @@ impl TestGatewayBuilder {
         let addr: SocketAddr = "127.0.0.1:0"
             .parse()
             .expect("hard-coded address must parse"); // safety: constant literal
-        let bound = start_server(addr, state.clone(), auth).await?;
+        let bound = start_server(addr, state.clone(), auth.into()).await?;
         Ok((bound, state))
     }
 }

src/channels/web/tests/multi_tenant.rs

@@ -16,7 +16,6 @@ use axum::routing::{delete, get, post};
 use tower::ServiceExt;
 use uuid::Uuid;
 
-use crate::channels::web::GatewayChannel;
 use crate::channels::web::auth::{
     AuthenticatedUser, MultiAuthState, UserIdentity, auth_middleware,
 };
@@ -24,7 +23,6 @@ use crate::channels::web::server::{
     ActiveConfigSnapshot, GatewayState, PerUserRateLimiter, PromptQueue, RateLimiter, WorkspacePool,
 };
 use crate::channels::web::sse::SseManager;
-use crate::config::GatewayConfig;
 
 // ── Helpers ────────────────────────────────────────────────────────────
 
@@ -35,6 +33,7 @@ fn two_user_auth() -> MultiAuthState {
         "tok-alice".to_string(),
         UserIdentity {
             user_id: "alice".to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: vec!["shared".to_string()],
         },
     );
@@ -42,6 +41,7 @@ fn two_user_auth() -> MultiAuthState {
         "tok-bob".to_string(),
         UserIdentity {
             user_id: "bob".to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: vec!["shared".to_string(), "alice".to_string()],
         },
     );
@@ -67,7 +67,6 @@ fn build_state(
         job_manager: None,
         prompt_queue,
         owner_id: "test".to_string(),
-        default_sender_id: "test".to_string(),
         shutdown_tx: tokio::sync::RwLock::new(None),
         ws_tracker: None,
         llm_provider: None,
@@ -82,43 +81,10 @@ fn build_state(
         routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
         startup_time: std::time::Instant::now(),
         active_config: ActiveConfigSnapshot::default(),
+        secrets_store: None,
     })
 }
 
-fn gateway_config() -> GatewayConfig {
-    GatewayConfig {
-        host: "127.0.0.1".to_string(),
-        port: 3000,
-        auth_token: Some("gateway-auth".to_string()),
-        user_id: "gateway-sender".to_string(),
-        workspace_read_scopes: Vec::new(),
-        memory_layers: Vec::new(),
-        user_tokens: None,
-    }
-}
-
-#[test]
-fn with_owner_scope_updates_gateway_owner_scope_in_multi_user_mode() {
-    let mut gateway = GatewayChannel::new(gateway_config());
-    gateway.auth = two_user_auth();
-    gateway.config.user_tokens = Some(HashMap::new());
-    let gateway = gateway.with_owner_scope("owner-scope");
-
-    assert_eq!(gateway.state.owner_id, "owner-scope");
-    assert_eq!(gateway.state.default_sender_id, "gateway-sender");
-
-    let alice = gateway
-        .auth
-        .authenticate("tok-alice")
-        .expect("alice token should remain valid");
-    let bob = gateway
-        .auth
-        .authenticate("tok-bob")
-        .expect("bob token should remain valid");
-    assert_eq!(alice.user_id, "alice");
-    assert_eq!(bob.user_id, "bob");
-}
-
 /// Create a libSQL-backed test database in a temporary directory.
 ///
 /// Returns the database and a `TempDir` guard — the database file is
@@ -225,6 +191,7 @@ mod workspace_pool {
         );
         let identity = UserIdentity {
             user_id: "alice".to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: vec![],
         };
         let ws = pool.get_or_create(&identity).await;
@@ -253,6 +220,7 @@ mod workspace_pool {
         );
         let identity = UserIdentity {
             user_id: "alice".to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: vec![],
         };
         let ws = pool.get_or_create(&identity).await;
@@ -276,6 +244,7 @@ mod workspace_pool {
         );
         let identity = UserIdentity {
             user_id: "bob".to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: vec!["alice".to_string(), "shared".to_string()],
         };
         let ws = pool.get_or_create(&identity).await;
@@ -302,10 +271,12 @@ mod workspace_pool {
         );
         let alice_id = UserIdentity {
             user_id: "alice".to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: vec![],
         };
         let bob_id = UserIdentity {
             user_id: "bob".to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: vec![],
         };
 
@@ -337,6 +308,7 @@ mod workspace_pool {
         );
         let identity = UserIdentity {
             user_id: "alice".to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: vec!["token-scope".to_string()],
         };
         let ws = pool.get_or_create(&identity).await;
@@ -377,7 +349,10 @@ mod jobs_isolation {
             .route("/api/jobs/{id}/cancel", post(jobs_cancel_handler))
             .route("/api/jobs/{id}/restart", post(jobs_restart_handler))
             .route("/api/jobs/{id}/prompt", post(jobs_prompt_handler))
-            .layer(middleware::from_fn_with_state(auth, auth_middleware))
+            .layer(middleware::from_fn_with_state(
+                crate::channels::web::auth::CombinedAuthState::from(auth),
+                auth_middleware,
+            ))
             .with_state(state)
     }
 
@@ -583,7 +558,10 @@ mod routines_isolation {
             .route("/api/routines/{id}", get(routines_detail_handler))
             .route("/api/routines/{id}/toggle", post(routines_toggle_handler))
             .route("/api/routines/{id}", delete(routines_delete_handler))
-            .layer(middleware::from_fn_with_state(auth, auth_middleware))
+            .layer(middleware::from_fn_with_state(
+                crate::channels::web::auth::CombinedAuthState::from(auth),
+                auth_middleware,
+            ))
             .with_state(state)
     }
 
@@ -708,7 +686,10 @@ mod auth_enforcement {
             .route("/api/logs/level", get(authed_handler).put(authed_handler))
             // Gateway status
             .route("/api/gateway/status", get(authed_handler))
-            .layer(middleware::from_fn_with_state(auth, auth_middleware))
+            .layer(middleware::from_fn_with_state(
+                crate::channels::web::auth::CombinedAuthState::from(auth),
+                auth_middleware,
+            ))
             .with_state(state)
     }
 
@@ -831,3 +812,140 @@ mod auth_enforcement {
         assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
     }
 }
+
+// ═══════════════════════════════════════════════════════════════════════
+// Admin Endpoint Role Enforcement Tests
+// ═══════════════════════════════════════════════════════════════════════
+
+mod admin_role_enforcement {
+    use super::*;
+    use crate::channels::web::handlers::users::{
+        users_activate_handler, users_detail_handler, users_list_handler, users_suspend_handler,
+        users_update_handler,
+    };
+    use axum::routing::patch;
+
+    /// Build a router with admin user endpoints behind multi-user auth.
+    /// Uses a member-role token and an admin-role token.
+    fn admin_router() -> Router {
+        let mut tokens = HashMap::new();
+        tokens.insert(
+            "tok-admin".to_string(),
+            UserIdentity {
+                user_id: "admin-user".to_string(),
+                role: "admin".to_string(),
+                workspace_read_scopes: vec![],
+            },
+        );
+        tokens.insert(
+            "tok-member".to_string(),
+            UserIdentity {
+                user_id: "member-user".to_string(),
+                role: "member".to_string(),
+                workspace_read_scopes: vec![],
+            },
+        );
+        let auth = MultiAuthState::multi(tokens);
+        let state = build_state(None, None);
+
+        Router::new()
+            .route("/api/admin/users", get(users_list_handler))
+            .route("/api/admin/users/{id}", get(users_detail_handler))
+            .route("/api/admin/users/{id}", patch(users_update_handler))
+            .route("/api/admin/users/{id}/suspend", post(users_suspend_handler))
+            .route(
+                "/api/admin/users/{id}/activate",
+                post(users_activate_handler),
+            )
+            .layer(middleware::from_fn_with_state(
+                crate::channels::web::auth::CombinedAuthState::from(auth),
+                auth_middleware,
+            ))
+            .with_state(state)
+    }
+
+    /// Assert a request returns FORBIDDEN for a member token.
+    async fn assert_forbidden_for_member(app: &Router, method: Method, uri: &str) {
+        let req = Request::builder()
+            .method(method)
+            .uri(uri)
+            .header("Authorization", "Bearer tok-member")
+            .body(Body::empty())
+            .unwrap();
+        let resp = app.clone().oneshot(req).await.unwrap();
+        assert_eq!(
+            resp.status(),
+            StatusCode::FORBIDDEN,
+            "expected 403 for member on {}",
+            uri
+        );
+    }
+
+    #[tokio::test]
+    async fn test_admin_user_endpoints_reject_member_role() {
+        let app = admin_router();
+
+        assert_forbidden_for_member(&app, Method::GET, "/api/admin/users").await;
+        assert_forbidden_for_member(&app, Method::GET, "/api/admin/users/some-id").await;
+        assert_forbidden_for_member(&app, Method::POST, "/api/admin/users/some-id/suspend").await;
+        assert_forbidden_for_member(&app, Method::POST, "/api/admin/users/some-id/activate").await;
+    }
+
+    #[tokio::test]
+    async fn test_admin_user_endpoints_accept_admin_role() {
+        let app = admin_router();
+
+        // Admin token should pass auth (will get 503 since no DB, but not 403).
+        let req = Request::builder()
+            .uri("/api/admin/users")
+            .header("Authorization", "Bearer tok-admin")
+            .body(Body::empty())
+            .unwrap();
+        let resp = app.clone().oneshot(req).await.unwrap();
+        assert_ne!(
+            resp.status(),
+            StatusCode::FORBIDDEN,
+            "admin should not get 403"
+        );
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// DbAuthenticator Cache Bounded Tests
+// ═══════════════════════════════════════════════════════════════════════
+
+mod db_auth_cache {
+    use super::*;
+    use std::time::Instant;
+
+    #[tokio::test]
+    async fn test_cache_bounded_by_max_entries() {
+        // Access the internal cache and verify LRU eviction.
+        // We can't easily test through `authenticate()` since it hits the DB,
+        // so we test the LRU cache directly.
+        let cap = std::num::NonZeroUsize::new(4).unwrap(); // safety: test-only, 4 is non-zero
+        let cache: lru::LruCache<[u8; 32], (UserIdentity, Instant)> = lru::LruCache::new(cap);
+        let cache = Arc::new(tokio::sync::RwLock::new(cache));
+
+        {
+            let mut c = cache.write().await;
+            for i in 0..10u8 {
+                let mut hash = [0u8; 32];
+                hash[0] = i;
+                c.put(
+                    hash,
+                    (
+                        UserIdentity {
+                            user_id: format!("user-{i}"),
+                            role: "member".to_string(),
+                            workspace_read_scopes: vec![],
+                        },
+                        Instant::now(),
+                    ),
+                );
+            }
+            // Cache must be bounded at capacity, not grown to 10.
+            assert_eq!(c.len(), 4, "cache should be bounded to capacity"); // safety: test assertion
+        }
+    }
+}

src/channels/web/ws.rs

@@ -521,7 +521,6 @@ mod tests {
             prompt_queue: None,
             scheduler: None,
             owner_id: "test".to_string(),
-            default_sender_id: "test".to_string(),
             shutdown_tx: tokio::sync::RwLock::new(None),
             ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
             llm_provider: None,
@@ -535,6 +534,7 @@ mod tests {
             routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
             startup_time: std::time::Instant::now(),
             active_config: crate::channels::web::server::ActiveConfigSnapshot::default(),
+            secrets_store: None,
         }
     }
 }

src/cli/mod.rs

@@ -352,7 +352,8 @@ pub async fn run_routines_cli(
         .await
         .map_err(|e| anyhow::anyhow!("{e:#}"))?;
 
-    let user_id = std::env::var("GATEWAY_USER_ID").unwrap_or_else(|_| "default".to_string());
+    let user_id =
+        std::env::var("IRONCLAW_OWNER_ID").unwrap_or_else(|_| "default".to_string());
     run_routines_command(routines_cmd.clone(), db, &user_id).await
 }
 

src/config/agent.rs

@@ -1,6 +1,6 @@
 use std::time::Duration;
 
-use crate::config::helpers::{optional_env, parse_bool_env, parse_option_env, parse_optional_env};
+use crate::config::helpers::{parse_bool_env, parse_option_env, parse_optional_env};
 use crate::error::ConfigError;
 use crate::settings::Settings;
 
@@ -31,10 +31,13 @@ pub struct AgentConfig {
     pub auto_approve_tools: bool,
     /// Default timezone for new sessions (IANA name, e.g. "America/New_York").
     pub default_timezone: String,
+    /// Maximum concurrent jobs per user. None = use global max_parallel_jobs.
+    pub max_jobs_per_user: Option<usize>,
     /// Maximum tokens per job (0 = unlimited).
     pub max_tokens_per_job: u64,
     /// Whether the deployment is multi-tenant (multiple users sharing one
-    /// instance). Auto-detected from GATEWAY_USER_TOKENS presence.
+    /// instance). Detected at runtime after DB initialization, not from config.
+    /// See app.rs startup logic.
     pub multi_tenant: bool,
     /// Maximum concurrent LLM calls per user. None = use default (4).
     pub max_llm_concurrent_per_user: Option<usize>,
@@ -62,6 +65,7 @@ impl AgentConfig {
             max_tool_iterations: 10,
             auto_approve_tools: true,
             default_timezone: "UTC".to_string(),
+            max_jobs_per_user: None,
             max_tokens_per_job: 0,
             multi_tenant: false,
             max_llm_concurrent_per_user: None,
@@ -122,13 +126,14 @@ impl AgentConfig {
                 }
                 tz
             },
+            max_jobs_per_user: parse_option_env("MAX_JOBS_PER_USER")?,
             max_tokens_per_job: parse_optional_env(
                 "AGENT_MAX_TOKENS_PER_JOB",
                 settings.agent.max_tokens_per_job,
             )?,
-            // Auto-detected from GATEWAY_USER_TOKENS presence. Not a separate
-            // knob — multi-tenant mode is always implied by configuring user tokens.
-            multi_tenant: optional_env("GATEWAY_USER_TOKENS")?.is_some(),
+            // Multi-tenant mode is detected at runtime after DB initialization,
+            // not from config. See app.rs startup logic.
+            multi_tenant: false,
             max_llm_concurrent_per_user: parse_option_env("TENANT_MAX_LLM_CONCURRENT")?,
             max_jobs_concurrent_per_user: parse_option_env("TENANT_MAX_JOBS_CONCURRENT")?,
         })

src/config/channels.rs

@@ -1,13 +1,11 @@
 use std::collections::HashMap;
 use std::path::PathBuf;
 
-use secrecy::SecretString;
-use serde::Deserialize;
-
 use crate::bootstrap::ironclaw_base_dir;
 use crate::config::helpers::{optional_env, parse_bool_env, parse_optional_env};
 use crate::error::ConfigError;
 use crate::settings::Settings;
+use secrecy::SecretString;
 
 /// Channel configurations.
 #[derive(Debug, Clone)]
@@ -45,7 +43,6 @@ pub struct GatewayConfig {
     pub port: u16,
     /// Bearer token for authentication. Random hex generated at startup if unset.
     pub auth_token: Option<String>,
-    pub user_id: String,
     /// Additional user scopes for workspace reads.
     ///
     /// When set, the workspace will be able to read (search, read, list) from
@@ -54,18 +51,6 @@ pub struct GatewayConfig {
     pub workspace_read_scopes: Vec<String>,
     /// Memory layer definitions (JSON in env var, or from external config).
     pub memory_layers: Vec<crate::workspace::layer::MemoryLayer>,
-    /// Multi-user token map. When set, each token maps to a user identity.
-    /// Parsed from `GATEWAY_USER_TOKENS` (JSON string). When absent, falls back
-    /// to single-user mode via `auth_token` + `user_id`.
-    pub user_tokens: Option<HashMap<String, UserTokenConfig>>,
-}
-
-/// Per-user token configuration for multi-user mode.
-#[derive(Debug, Clone, Deserialize)]
-pub struct UserTokenConfig {
-    pub user_id: String,
-    #[serde(default)]
-    pub workspace_read_scopes: Vec<String>,
 }
 
 /// Signal channel configuration (signal-cli daemon HTTP/JSON-RPC).
@@ -132,10 +117,6 @@ impl ChannelsConfig {
 
         let gateway_enabled = parse_bool_env("GATEWAY_ENABLED", cs.gateway_enabled)?;
         let gateway = if gateway_enabled {
-            let user_id = optional_env("GATEWAY_USER_ID")?
-                .or_else(|| cs.gateway_user_id.clone())
-                .unwrap_or_else(|| owner_id.to_string());
-
             let memory_layers: Vec<crate::workspace::layer::MemoryLayer> =
                 match optional_env("MEMORY_LAYERS")? {
                     Some(json_str) => {
@@ -144,7 +125,7 @@ impl ChannelsConfig {
                             message: format!("must be valid JSON array of layer objects: {e}"),
                         })?
                     }
-                    None => crate::workspace::layer::MemoryLayer::default_for_user(&user_id),
+                    None => crate::workspace::layer::MemoryLayer::default_for_user(owner_id),
                 };
 
             // Validate layer names and scopes
@@ -196,41 +177,6 @@ impl ChannelsConfig {
                 }
             }
 
-            let user_tokens: Option<HashMap<String, UserTokenConfig>> =
-                match optional_env("GATEWAY_USER_TOKENS")? {
-                    Some(json_str) => {
-                        let tokens: HashMap<String, UserTokenConfig> = serde_json::from_str(
-                            &json_str,
-                        )
-                        .map_err(|e| ConfigError::InvalidValue {
-                            key: "GATEWAY_USER_TOKENS".to_string(),
-                            message: format!(
-                                "must be valid JSON object mapping tokens to user configs: {e}"
-                            ),
-                        })?;
-                        if tokens.is_empty() {
-                            return Err(ConfigError::InvalidValue {
-                            key: "GATEWAY_USER_TOKENS".to_string(),
-                            message:
-                                "token map is empty — remove the variable to use single-user mode"
-                                    .to_string(),
-                        });
-                        }
-                        for (tok, cfg) in &tokens {
-                            if cfg.user_id.trim().is_empty() {
-                                return Err(ConfigError::InvalidValue {
-                                    key: "GATEWAY_USER_TOKENS".to_string(),
-                                    message: format!(
-                                        "token '{}...' has an empty user_id",
-                                        &tok[..tok.len().min(8)]
-                                    ),
-                                });
-                            }
-                        }
-                        Some(tokens)
-                    }
-                    None => None,
-                };
             let workspace_read_scopes: Vec<String> = optional_env("WORKSPACE_READ_SCOPES")?
                 .map(|s| {
                     s.split(',')
@@ -258,10 +204,8 @@ impl ChannelsConfig {
                 )?,
                 auth_token: optional_env("GATEWAY_AUTH_TOKEN")?
                     .or_else(|| cs.gateway_auth_token.clone()),
-                user_id,
                 workspace_read_scopes,
                 memory_layers,
-                user_tokens,
             })
         } else {
             None
@@ -416,15 +360,12 @@ mod tests {
             host: "127.0.0.1".to_string(),
             port: 3000,
             auth_token: Some("tok-abc".to_string()),
-            user_id: "default".to_string(),
             workspace_read_scopes: vec![],
             memory_layers: vec![],
-            user_tokens: None,
         };
         assert_eq!(cfg.host, "127.0.0.1");
         assert_eq!(cfg.port, 3000);
         assert_eq!(cfg.auth_token.as_deref(), Some("tok-abc"));
-        assert_eq!(cfg.user_id, "default");
     }
 
     #[test]
@@ -433,10 +374,8 @@ mod tests {
             host: "0.0.0.0".to_string(),
             port: 3001,
             auth_token: None,
-            user_id: "anon".to_string(),
             workspace_read_scopes: vec![],
             memory_layers: vec![],
-            user_tokens: None,
         };
         assert!(cfg.auth_token.is_none());
     }
@@ -563,7 +502,6 @@ mod tests {
         assert_eq!(gateway.host, "127.0.0.3");
         assert_eq!(gateway.port, 9191);
         assert_eq!(gateway.auth_token.as_deref(), Some("tok"));
-        assert_eq!(gateway.user_id, "owner-scope");
 
         let signal = cfg.signal.expect("signal config");
         assert_eq!(signal.account, "+15551234567");

src/config/heartbeat.rs

@@ -21,8 +21,8 @@ pub struct HeartbeatConfig {
     pub quiet_hours_end: Option<u32>,
     /// Timezone for fire_at and quiet hours evaluation (IANA name).
     pub timezone: Option<String>,
-    /// When true, cycle through all users with routines. Auto-detected from
-    /// GATEWAY_USER_TOKENS or set explicitly via HEARTBEAT_MULTI_TENANT.
+    /// When true, cycle through all users with routines. Set explicitly via
+    /// HEARTBEAT_MULTI_TENANT or detected at runtime after DB initialization.
     pub multi_tenant: bool,
 }
 
@@ -105,12 +105,7 @@ impl HeartbeatConfig {
                 }
                 tz
             },
-            // Auto-detect multi-tenant mode from GATEWAY_USER_TOKENS presence,
-            // or allow explicit override via HEARTBEAT_MULTI_TENANT.
-            multi_tenant: parse_bool_env(
-                "HEARTBEAT_MULTI_TENANT",
-                optional_env("GATEWAY_USER_TOKENS")?.is_some(),
-            )?,
+            multi_tenant: parse_bool_env("HEARTBEAT_MULTI_TENANT", false)?,
         })
     }
 }

src/db/libsql/mod.rs

@@ -12,6 +12,7 @@ mod routines;
 mod sandbox;
 mod settings;
 mod tool_failures;
+mod users;
 mod workspace;
 
 use std::path::Path;

src/db/libsql/users.rs

@@ -0,0 +1,735 @@
+//! UserStore implementation for LibSqlBackend.
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use libsql::params;
+use uuid::Uuid;
+
+use super::{fmt_opt_ts, fmt_ts, get_opt_text, get_opt_ts, get_text, get_ts, opt_text};
+use crate::db::libsql::LibSqlBackend;
+use crate::db::{ApiTokenRecord, DatabaseError, UserRecord, UserStore};
+
+fn row_to_user(row: &libsql::Row) -> Result<UserRecord, DatabaseError> {
+    let metadata_str = get_text(row, 9);
+    let metadata: serde_json::Value = serde_json::from_str(&metadata_str)
+        .map_err(|e| DatabaseError::Serialization(e.to_string()))?;
+    Ok(UserRecord {
+        id: get_text(row, 0),
+        email: get_opt_text(row, 1),
+        display_name: get_text(row, 2),
+        status: get_text(row, 3),
+        role: get_text(row, 4),
+        created_at: get_ts(row, 5),
+        updated_at: get_ts(row, 6),
+        last_login_at: get_opt_ts(row, 7),
+        created_by: get_opt_text(row, 8),
+        metadata,
+    })
+}
+
+fn row_to_api_token(row: &libsql::Row) -> Result<ApiTokenRecord, DatabaseError> {
+    let id_str = get_text(row, 0);
+    let id: Uuid = id_str
+        .parse()
+        .map_err(|e| DatabaseError::Serialization(format!("invalid UUID: {e}")))?;
+    Ok(ApiTokenRecord {
+        id,
+        user_id: get_text(row, 1),
+        name: get_text(row, 2),
+        token_prefix: get_text(row, 3),
+        expires_at: get_opt_ts(row, 4),
+        last_used_at: get_opt_ts(row, 5),
+        created_at: get_ts(row, 6),
+        revoked_at: get_opt_ts(row, 7),
+    })
+}
+
+#[async_trait]
+impl UserStore for LibSqlBackend {
+    async fn create_user(&self, user: &UserRecord) -> Result<(), DatabaseError> {
+        let conn = self.connect().await?;
+        let metadata_json = serde_json::to_string(&user.metadata)
+            .map_err(|e| DatabaseError::Serialization(e.to_string()))?;
+
+        conn.execute(
+            r#"
+            INSERT INTO users (id, email, display_name, status, role, created_at, updated_at, last_login_at, created_by, metadata)
+            VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)
+            "#,
+            params![
+                user.id.as_str(),
+                opt_text(user.email.as_deref()),
+                user.display_name.as_str(),
+                user.status.as_str(),
+                user.role.as_str(),
+                fmt_ts(&user.created_at),
+                fmt_ts(&user.updated_at),
+                fmt_opt_ts(&user.last_login_at),
+                opt_text(user.created_by.as_deref()),
+                metadata_json,
+            ],
+        )
+        .await
+        .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        Ok(())
+    }
+
+    async fn get_user(&self, id: &str) -> Result<Option<UserRecord>, DatabaseError> {
+        let conn = self.connect().await?;
+        let mut rows = conn
+            .query(
+                r#"
+                SELECT id, email, display_name, status, role, created_at, updated_at,
+                       last_login_at, created_by, metadata
+                FROM users WHERE id = ?1
+                "#,
+                params![id],
+            )
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+
+        match rows
+            .next()
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?
+        {
+            Some(row) => Ok(Some(row_to_user(&row)?)),
+            None => Ok(None),
+        }
+    }
+
+    async fn get_user_by_email(&self, email: &str) -> Result<Option<UserRecord>, DatabaseError> {
+        let conn = self.connect().await?;
+        let mut rows = conn
+            .query(
+                r#"
+                SELECT id, email, display_name, status, role, created_at, updated_at,
+                       last_login_at, created_by, metadata
+                FROM users WHERE email = ?1
+                "#,
+                params![email],
+            )
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+
+        match rows
+            .next()
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?
+        {
+            Some(row) => Ok(Some(row_to_user(&row)?)),
+            None => Ok(None),
+        }
+    }
+
+    async fn list_users(&self, status: Option<&str>) -> Result<Vec<UserRecord>, DatabaseError> {
+        let conn = self.connect().await?;
+        let mut users = Vec::new();
+
+        let mut rows = if let Some(status) = status {
+            conn.query(
+                r#"
+                SELECT id, email, display_name, status, role, created_at, updated_at,
+                       last_login_at, created_by, metadata
+                FROM users WHERE status = ?1
+                ORDER BY created_at DESC
+                "#,
+                params![status],
+            )
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?
+        } else {
+            conn.query(
+                r#"
+                SELECT id, email, display_name, status, role, created_at, updated_at,
+                       last_login_at, created_by, metadata
+                FROM users
+                ORDER BY created_at DESC
+                "#,
+                (),
+            )
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?
+        };
+
+        while let Some(row) = rows
+            .next()
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?
+        {
+            users.push(row_to_user(&row)?);
+        }
+        Ok(users)
+    }
+
+    async fn update_user_status(&self, id: &str, status: &str) -> Result<(), DatabaseError> {
+        let conn = self.connect().await?;
+        let now = fmt_ts(&Utc::now());
+        conn.execute(
+            "UPDATE users SET status = ?2, updated_at = ?3 WHERE id = ?1",
+            params![id, status, now],
+        )
+        .await
+        .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        Ok(())
+    }
+
+    async fn update_user_profile(
+        &self,
+        id: &str,
+        display_name: &str,
+        metadata: &serde_json::Value,
+    ) -> Result<(), DatabaseError> {
+        let conn = self.connect().await?;
+        let now = fmt_ts(&Utc::now());
+        let metadata_json = serde_json::to_string(metadata)
+            .map_err(|e| DatabaseError::Serialization(e.to_string()))?;
+        conn.execute(
+            "UPDATE users SET display_name = ?2, metadata = ?3, updated_at = ?4 WHERE id = ?1",
+            params![id, display_name, metadata_json, now],
+        )
+        .await
+        .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        Ok(())
+    }
+
+    async fn record_login(&self, id: &str) -> Result<(), DatabaseError> {
+        let conn = self.connect().await?;
+        let now = fmt_ts(&Utc::now());
+        conn.execute(
+            "UPDATE users SET last_login_at = ?2, updated_at = ?2 WHERE id = ?1",
+            params![id, now],
+        )
+        .await
+        .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        Ok(())
+    }
+
+    async fn create_api_token(
+        &self,
+        user_id: &str,
+        name: &str,
+        token_hash: &[u8; 32],
+        token_prefix: &str,
+        expires_at: Option<DateTime<Utc>>,
+    ) -> Result<ApiTokenRecord, DatabaseError> {
+        let conn = self.connect().await?;
+        let id = Uuid::new_v4();
+        let now = Utc::now();
+
+        conn.execute(
+            r#"
+            INSERT INTO api_tokens (id, user_id, token_hash, token_prefix, name, expires_at, created_at)
+            VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)
+            "#,
+            params![
+                id.to_string(),
+                user_id,
+                libsql::Value::Blob(token_hash.to_vec()),
+                token_prefix,
+                name,
+                fmt_opt_ts(&expires_at),
+                fmt_ts(&now),
+            ],
+        )
+        .await
+        .map_err(|e| DatabaseError::Query(e.to_string()))?;
+
+        Ok(ApiTokenRecord {
+            id,
+            user_id: user_id.to_string(),
+            name: name.to_string(),
+            token_prefix: token_prefix.to_string(),
+            expires_at,
+            last_used_at: None,
+            created_at: now,
+            revoked_at: None,
+        })
+    }
+
+    async fn list_api_tokens(&self, user_id: &str) -> Result<Vec<ApiTokenRecord>, DatabaseError> {
+        let conn = self.connect().await?;
+        let mut rows = conn
+            .query(
+                r#"
+                SELECT id, user_id, name, token_prefix, expires_at, last_used_at, created_at, revoked_at
+                FROM api_tokens WHERE user_id = ?1
+                ORDER BY created_at DESC
+                "#,
+                params![user_id],
+            )
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+
+        let mut tokens = Vec::new();
+        while let Some(row) = rows
+            .next()
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?
+        {
+            tokens.push(row_to_api_token(&row)?);
+        }
+        Ok(tokens)
+    }
+
+    async fn revoke_api_token(&self, token_id: Uuid, user_id: &str) -> Result<bool, DatabaseError> {
+        let conn = self.connect().await?;
+        let now = fmt_ts(&Utc::now());
+        let rows_affected = conn
+            .execute(
+                r#"
+                UPDATE api_tokens SET revoked_at = ?3
+                WHERE id = ?1 AND user_id = ?2 AND revoked_at IS NULL
+                "#,
+                params![token_id.to_string(), user_id, now],
+            )
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        Ok(rows_affected > 0)
+    }
+
+    async fn authenticate_token(
+        &self,
+        token_hash: &[u8; 32],
+    ) -> Result<Option<(ApiTokenRecord, UserRecord)>, DatabaseError> {
+        let conn = self.connect().await?;
+        let now = fmt_ts(&Utc::now());
+
+        let mut rows = conn
+            .query(
+                r#"
+                SELECT
+                    t.id, t.user_id, t.name, t.token_prefix, t.expires_at,
+                    t.last_used_at, t.created_at, t.revoked_at,
+                    u.id, u.email, u.display_name, u.status, u.role, u.created_at,
+                    u.updated_at, u.last_login_at, u.created_by, u.metadata
+                FROM api_tokens t
+                JOIN users u ON u.id = t.user_id
+                WHERE t.token_hash = ?1
+                  AND t.revoked_at IS NULL
+                  AND (t.expires_at IS NULL OR t.expires_at > ?2)
+                  AND u.status = 'active'
+                "#,
+                params![libsql::Value::Blob(token_hash.to_vec()), now],
+            )
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+
+        match rows
+            .next()
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?
+        {
+            Some(row) => {
+                let id_str = get_text(&row, 0);
+                let token_id: Uuid = id_str
+                    .parse()
+                    .map_err(|e| DatabaseError::Serialization(format!("invalid UUID: {e}")))?;
+                let token = ApiTokenRecord {
+                    id: token_id,
+                    user_id: get_text(&row, 1),
+                    name: get_text(&row, 2),
+                    token_prefix: get_text(&row, 3),
+                    expires_at: get_opt_ts(&row, 4),
+                    last_used_at: get_opt_ts(&row, 5),
+                    created_at: get_ts(&row, 6),
+                    revoked_at: get_opt_ts(&row, 7),
+                };
+
+                let metadata_str = get_text(&row, 17);
+                let metadata: serde_json::Value = serde_json::from_str(&metadata_str)
+                    .map_err(|e| DatabaseError::Serialization(e.to_string()))?;
+
+                let user = UserRecord {
+                    id: get_text(&row, 8),
+                    email: get_opt_text(&row, 9),
+                    display_name: get_text(&row, 10),
+                    status: get_text(&row, 11),
+                    role: get_text(&row, 12),
+                    created_at: get_ts(&row, 13),
+                    updated_at: get_ts(&row, 14),
+                    last_login_at: get_opt_ts(&row, 15),
+                    created_by: get_opt_text(&row, 16),
+                    metadata,
+                };
+
+                Ok(Some((token, user)))
+            }
+            None => Ok(None),
+        }
+    }
+
+    async fn record_token_usage(&self, token_id: Uuid) -> Result<(), DatabaseError> {
+        let conn = self.connect().await?;
+        let now = fmt_ts(&Utc::now());
+        conn.execute(
+            "UPDATE api_tokens SET last_used_at = ?2 WHERE id = ?1",
+            params![token_id.to_string(), now],
+        )
+        .await
+        .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        Ok(())
+    }
+
+    async fn has_any_users(&self) -> Result<bool, DatabaseError> {
+        let conn = self.connect().await?;
+        let mut rows = conn
+            .query("SELECT 1 FROM users LIMIT 1", ())
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+
+        let has_users = rows
+            .next()
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?
+            .is_some();
+        Ok(has_users)
+    }
+
+    async fn delete_user(&self, id: &str) -> Result<bool, DatabaseError> {
+        let conn = self.connect().await?;
+        // Delete from child tables first to avoid FK violations.
+        // agent_jobs cascades to job_actions, llm_calls, estimation_snapshots
+        // conversations cascades to conversation_messages
+        // memory_documents cascades to memory_chunks
+        // routines cascades to routine_runs
+        for table in &[
+            "settings",
+            "heartbeat_state",
+            "tool_rate_limit_state",
+            "secret_usage_log",
+            "leak_detection_events",
+            "secrets",
+            "wasm_tools",
+            "routines",
+            "memory_documents",
+            "conversations",
+            "api_tokens",
+        ] {
+            conn.execute(
+                &format!("DELETE FROM {} WHERE user_id = ?1", table),
+                params![id],
+            )
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        }
+        // job_events references agent_jobs(id) without CASCADE — delete via subquery.
+        conn.execute(
+            "DELETE FROM job_events WHERE job_id IN (SELECT id FROM agent_jobs WHERE user_id = ?1)",
+            params![id],
+        )
+        .await
+        .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        conn.execute("DELETE FROM agent_jobs WHERE user_id = ?1", params![id])
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        // Nullify self-referencing created_by before deleting the user
+        conn.execute(
+            "UPDATE users SET created_by = NULL WHERE created_by = ?1",
+            params![id],
+        )
+        .await
+        .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        let rows = conn
+            .execute("DELETE FROM users WHERE id = ?1", params![id])
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        Ok(rows > 0)
+    }
+
+    async fn user_usage_stats(
+        &self,
+        user_id: Option<&str>,
+        since: DateTime<Utc>,
+    ) -> Result<Vec<crate::db::UserUsageStats>, DatabaseError> {
+        let conn = self.connect().await?;
+        let since_str = fmt_ts(&since);
+        let mut rows = if let Some(uid) = user_id {
+            conn.query(
+                r#"
+                SELECT j.user_id, l.model, COUNT(*) as call_count,
+                       COALESCE(SUM(l.input_tokens), 0) as input_tokens,
+                       COALESCE(SUM(l.output_tokens), 0) as output_tokens,
+                       COALESCE(SUM(l.cost), 0) as total_cost
+                FROM llm_calls l
+                JOIN agent_jobs j ON l.job_id = j.id
+                WHERE l.created_at >= ?1
+                  AND j.user_id = ?2
+                GROUP BY j.user_id, l.model
+                ORDER BY total_cost DESC
+                "#,
+                params![since_str, uid],
+            )
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?
+        } else {
+            conn.query(
+                r#"
+                SELECT j.user_id, l.model, COUNT(*) as call_count,
+                       COALESCE(SUM(l.input_tokens), 0) as input_tokens,
+                       COALESCE(SUM(l.output_tokens), 0) as output_tokens,
+                       COALESCE(SUM(l.cost), 0) as total_cost
+                FROM llm_calls l
+                JOIN agent_jobs j ON l.job_id = j.id
+                WHERE l.created_at >= ?1
+                GROUP BY j.user_id, l.model
+                ORDER BY total_cost DESC
+                "#,
+                params![since_str],
+            )
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?
+        };
+        let mut stats = Vec::new();
+        while let Some(row) = rows
+            .next()
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?
+        {
+            let cost_str = get_text(&row, 5);
+            let total_cost = rust_decimal::Decimal::from_str_exact(&cost_str).unwrap_or_default();
+            stats.push(crate::db::UserUsageStats {
+                user_id: get_text(&row, 0),
+                model: get_text(&row, 1),
+                call_count: row
+                    .get::<i64>(2)
+                    .map_err(|e| DatabaseError::Query(e.to_string()))?,
+                input_tokens: row
+                    .get::<i64>(3)
+                    .map_err(|e| DatabaseError::Query(e.to_string()))?,
+                output_tokens: row
+                    .get::<i64>(4)
+                    .map_err(|e| DatabaseError::Query(e.to_string()))?,
+                total_cost,
+            });
+        }
+        Ok(stats)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::db::libsql::LibSqlBackend;
+    use crate::db::{Database, UserStore};
+    use sha2::{Digest, Sha256};
+
+    fn hash(s: &str) -> [u8; 32] {
+        let mut h = Sha256::new();
+        h.update(s.as_bytes());
+        h.finalize().into()
+    }
+
+    async fn setup() -> (LibSqlBackend, tempfile::TempDir) {
+        let dir = tempfile::tempdir().unwrap();
+        let db_path = dir.path().join("test_users.db");
+        let db = LibSqlBackend::new_local(&db_path).await.unwrap();
+        db.run_migrations().await.unwrap();
+        (db, dir) // keep dir alive so the DB file isn't deleted
+    }
+
+    fn test_user(id: &str) -> UserRecord {
+        UserRecord {
+            id: id.to_string(),
+            email: Some(format!("{}@test.com", id)),
+            display_name: id.to_string(),
+            status: "active".to_string(),
+            role: "member".to_string(),
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+            last_login_at: None,
+            created_by: None,
+            metadata: serde_json::json!({}),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_has_any_users_empty() {
+        let (db, _dir) = setup().await;
+        assert!(!db.has_any_users().await.unwrap());
+    }
+
+    #[tokio::test]
+    async fn test_create_and_get_user() {
+        let (db, _dir) = setup().await;
+        let user = test_user("alice");
+        db.create_user(&user).await.unwrap();
+
+        assert!(db.has_any_users().await.unwrap());
+
+        let found = db.get_user("alice").await.unwrap().unwrap();
+        assert_eq!(found.id, "alice");
+        assert_eq!(found.email, Some("[email protected]".to_string()));
+        assert_eq!(found.status, "active");
+    }
+
+    #[tokio::test]
+    async fn test_get_user_by_email() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("bob")).await.unwrap();
+
+        let found = db.get_user_by_email("[email protected]").await.unwrap();
+        assert!(found.is_some());
+        assert_eq!(found.unwrap().id, "bob");
+
+        assert!(
+            db.get_user_by_email("[email protected]")
+                .await
+                .unwrap()
+                .is_none()
+        );
+    }
+
+    #[tokio::test]
+    async fn test_list_users_with_status_filter() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+        db.create_user(&test_user("bob")).await.unwrap();
+        db.update_user_status("bob", "suspended").await.unwrap();
+
+        let all = db.list_users(None).await.unwrap();
+        assert_eq!(all.len(), 2);
+
+        let active = db.list_users(Some("active")).await.unwrap();
+        assert_eq!(active.len(), 1);
+        assert_eq!(active[0].id, "alice");
+
+        let suspended = db.list_users(Some("suspended")).await.unwrap();
+        assert_eq!(suspended.len(), 1);
+        assert_eq!(suspended[0].id, "bob");
+    }
+
+    #[tokio::test]
+    async fn test_update_user_profile() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+
+        let meta = serde_json::json!({"role": "admin"});
+        db.update_user_profile("alice", "Alice Smith", &meta)
+            .await
+            .unwrap();
+
+        let user = db.get_user("alice").await.unwrap().unwrap();
+        assert_eq!(user.display_name, "Alice Smith");
+        assert_eq!(user.metadata["role"], "admin");
+    }
+
+    #[tokio::test]
+    async fn test_token_lifecycle_create_authenticate_revoke() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+
+        // Create token
+        let token_hash = hash("secret-token-123");
+        let record = db
+            .create_api_token("alice", "laptop", &token_hash, "secret-t", None)
+            .await
+            .unwrap();
+        assert_eq!(record.user_id, "alice");
+        assert_eq!(record.name, "laptop");
+        assert_eq!(record.token_prefix, "secret-t");
+
+        // Authenticate
+        let (tok, user) = db.authenticate_token(&token_hash).await.unwrap().unwrap();
+        assert_eq!(tok.id, record.id);
+        assert_eq!(user.id, "alice");
+
+        // List tokens
+        let tokens = db.list_api_tokens("alice").await.unwrap();
+        assert_eq!(tokens.len(), 1);
+
+        // Revoke
+        assert!(db.revoke_api_token(record.id, "alice").await.unwrap());
+
+        // Auth should fail after revoke
+        assert!(db.authenticate_token(&token_hash).await.unwrap().is_none());
+    }
+
+    #[tokio::test]
+    async fn test_token_auth_fails_for_suspended_user() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+
+        let token_hash = hash("token-abc");
+        db.create_api_token("alice", "test", &token_hash, "token-ab", None)
+            .await
+            .unwrap();
+
+        // Auth works while active
+        assert!(db.authenticate_token(&token_hash).await.unwrap().is_some());
+
+        // Suspend user
+        db.update_user_status("alice", "suspended").await.unwrap();
+
+        // Auth should fail
+        assert!(db.authenticate_token(&token_hash).await.unwrap().is_none());
+    }
+
+    #[tokio::test]
+    async fn test_token_revoke_wrong_user_returns_false() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+        db.create_user(&test_user("bob")).await.unwrap();
+
+        let token_hash = hash("alice-token");
+        let record = db
+            .create_api_token("alice", "test", &token_hash, "alice-to", None)
+            .await
+            .unwrap();
+
+        // Bob can't revoke Alice's token
+        assert!(!db.revoke_api_token(record.id, "bob").await.unwrap());
+
+        // Alice can
+        assert!(db.revoke_api_token(record.id, "alice").await.unwrap());
+    }
+
+    #[tokio::test]
+    async fn test_record_login_and_token_usage() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+
+        let token_hash = hash("tok");
+        let record = db
+            .create_api_token("alice", "test", &token_hash, "tok", None)
+            .await
+            .unwrap();
+
+        // Record usage
+        db.record_token_usage(record.id).await.unwrap();
+        db.record_login("alice").await.unwrap();
+
+        // Verify timestamps updated
+        let user = db.get_user("alice").await.unwrap().unwrap();
+        assert!(user.last_login_at.is_some());
+
+        let tokens = db.list_api_tokens("alice").await.unwrap();
+        assert!(tokens[0].last_used_at.is_some());
+    }
+
+    #[tokio::test]
+    async fn test_delete_user_removes_api_tokens() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+
+        let token_hash = hash("alice-tok");
+        db.create_api_token("alice", "primary", &token_hash, "alice-to", None)
+            .await
+            .unwrap();
+
+        // Verify token exists before deletion.
+        let tokens = db.list_api_tokens("alice").await.unwrap();
+        assert_eq!(tokens.len(), 1);
+
+        // Delete user — should also remove their api_tokens.
+        assert!(db.delete_user("alice").await.unwrap());
+
+        // api_tokens must be gone (not orphaned).
+        let tokens = db.list_api_tokens("alice").await.unwrap();
+        assert!(
+            tokens.is_empty(),
+            "expected api_tokens to be deleted with user, found {}",
+            tokens.len()
+        );
+    }
+}

src/db/libsql_migrations.rs

@@ -579,6 +579,36 @@ INSERT OR IGNORE INTO leak_detection_patterns (id, name, pattern, severity, acti
     ('550e8400-e29b-41d4-a716-446655440011', 'mailchimp_api_key', '[a-f0-9]{32}-us[0-9]{1,2}', 'medium', 'block', 1, strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
     ('550e8400-e29b-41d4-a716-446655440012', 'high_entropy_hex', '(?<![a-fA-F0-9])[a-fA-F0-9]{64}(?![a-fA-F0-9])', 'medium', 'warn', 1, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));
 
+
+-- ==================== User management (V14) ====================
+
+CREATE TABLE IF NOT EXISTS users (
+    id TEXT PRIMARY KEY,
+    email TEXT UNIQUE,
+    display_name TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'active',
+    role TEXT NOT NULL DEFAULT 'member',
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    last_login_at TEXT,
+    created_by TEXT,
+    metadata TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE TABLE IF NOT EXISTS api_tokens (
+    id TEXT PRIMARY KEY,
+    user_id TEXT NOT NULL,
+    token_hash BLOB NOT NULL,
+    token_prefix TEXT NOT NULL,
+    name TEXT NOT NULL,
+    expires_at TEXT,
+    last_used_at TEXT,
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    revoked_at TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_api_tokens_user ON api_tokens(user_id);
+CREATE INDEX IF NOT EXISTS idx_api_tokens_hash ON api_tokens(token_hash);
+
 "#;
 
 /// Incremental migrations applied after the base schema.
@@ -723,6 +753,38 @@ CREATE INDEX IF NOT EXISTS idx_routines_event_triggers
     WHERE enabled = 1 AND trigger_type IN ('event', 'system_event');
 
 PRAGMA foreign_keys=ON;
+"#,
+    ),
+    (
+        14,
+        "users",
+        r#"
+CREATE TABLE IF NOT EXISTS users (
+    id TEXT PRIMARY KEY,
+    email TEXT UNIQUE,
+    display_name TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'active',
+    role TEXT NOT NULL DEFAULT 'member',
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    last_login_at TEXT,
+    created_by TEXT,
+    metadata TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE TABLE IF NOT EXISTS api_tokens (
+    id TEXT PRIMARY KEY,
+    user_id TEXT NOT NULL,
+    token_hash BLOB NOT NULL,
+    token_prefix TEXT NOT NULL,
+    name TEXT NOT NULL,
+    expires_at TEXT,
+    last_used_at TEXT,
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    revoked_at TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_api_tokens_user ON api_tokens(user_id);
+CREATE INDEX IF NOT EXISTS idx_api_tokens_hash ON api_tokens(token_hash);
 "#,
     ),
 ];

src/db/mod.rs

@@ -309,6 +309,43 @@ async fn validate_postgres(pool: &deadpool_postgres::Pool) -> Result<(), Databas
     Ok(())
 }
 
+// ==================== User management record types ====================
+
+/// A registered user.
+#[derive(Debug, Clone)]
+pub struct UserRecord {
+    /// User identifier (string, matches existing `user_id` throughout the codebase).
+    pub id: String,
+    pub email: Option<String>,
+    pub display_name: String,
+    /// `active`, `suspended`, or `deactivated`.
+    pub status: String,
+    /// `admin` or `member`.
+    pub role: String,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub last_login_at: Option<DateTime<Utc>>,
+    /// Who created/invited this user (nullable for bootstrap users).
+    pub created_by: Option<String>,
+    pub metadata: serde_json::Value,
+}
+
+/// An API token for authenticating requests (hash stored, never plaintext).
+#[derive(Debug, Clone)]
+pub struct ApiTokenRecord {
+    pub id: Uuid,
+    pub user_id: String,
+    /// Human label (e.g. "my-laptop", "ci-bot").
+    pub name: String,
+    /// First 8 hex chars of the plaintext token for display/identification.
+    pub token_prefix: String,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub last_used_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    /// Soft-revoke timestamp. Non-null means revoked.
+    pub revoked_at: Option<DateTime<Utc>>,
+}
+
 // ==================== Sub-traits ====================
 //
 // Each sub-trait groups related persistence methods. The `Database` supertrait
@@ -761,6 +798,81 @@ pub trait WorkspaceStore: Send + Sync {
     }
 }
 
+#[async_trait]
+pub trait UserStore: Send + Sync {
+    // ---- Users ----
+
+    /// Create a new user record.
+    async fn create_user(&self, user: &UserRecord) -> Result<(), DatabaseError>;
+    /// Get a user by their string id.
+    async fn get_user(&self, id: &str) -> Result<Option<UserRecord>, DatabaseError>;
+    /// Get a user by email address.
+    async fn get_user_by_email(&self, email: &str) -> Result<Option<UserRecord>, DatabaseError>;
+    /// List users, optionally filtered by status.
+    async fn list_users(&self, status: Option<&str>) -> Result<Vec<UserRecord>, DatabaseError>;
+    /// Update a user's status (active/suspended/deactivated).
+    async fn update_user_status(&self, id: &str, status: &str) -> Result<(), DatabaseError>;
+    /// Update a user's display name and metadata.
+    async fn update_user_profile(
+        &self,
+        id: &str,
+        display_name: &str,
+        metadata: &serde_json::Value,
+    ) -> Result<(), DatabaseError>;
+    /// Record a login timestamp.
+    async fn record_login(&self, id: &str) -> Result<(), DatabaseError>;
+
+    // ---- API Tokens ----
+
+    /// Create a new API token. The `token_hash` is SHA-256 of the plaintext.
+    async fn create_api_token(
+        &self,
+        user_id: &str,
+        name: &str,
+        token_hash: &[u8; 32],
+        token_prefix: &str,
+        expires_at: Option<DateTime<Utc>>,
+    ) -> Result<ApiTokenRecord, DatabaseError>;
+    /// List tokens for a user (never includes the hash).
+    async fn list_api_tokens(&self, user_id: &str) -> Result<Vec<ApiTokenRecord>, DatabaseError>;
+    /// Soft-revoke a token. Returns false if the token doesn't exist or doesn't belong to the user.
+    async fn revoke_api_token(&self, token_id: Uuid, user_id: &str) -> Result<bool, DatabaseError>;
+    /// Look up a token by hash, returning the token record and its owning user.
+    /// Only returns active (non-revoked, non-expired) tokens for active users.
+    async fn authenticate_token(
+        &self,
+        token_hash: &[u8; 32],
+    ) -> Result<Option<(ApiTokenRecord, UserRecord)>, DatabaseError>;
+    /// Update `last_used_at` for a token.
+    async fn record_token_usage(&self, token_id: Uuid) -> Result<(), DatabaseError>;
+
+    /// Check whether any user records exist (for first-run bootstrap detection).
+    async fn has_any_users(&self) -> Result<bool, DatabaseError>;
+
+    /// Delete a user and all their data across all user-scoped tables.
+    /// Returns false if the user doesn't exist.
+    async fn delete_user(&self, id: &str) -> Result<bool, DatabaseError>;
+
+    /// Get per-user LLM usage stats for a time period.
+    /// Aggregates from llm_calls via agent_jobs.user_id.
+    async fn user_usage_stats(
+        &self,
+        user_id: Option<&str>,
+        since: DateTime<Utc>,
+    ) -> Result<Vec<UserUsageStats>, DatabaseError>;
+}
+
+/// Per-user LLM usage statistics.
+#[derive(Debug, Clone)]
+pub struct UserUsageStats {
+    pub user_id: String,
+    pub model: String,
+    pub call_count: i64,
+    pub input_tokens: i64,
+    pub output_tokens: i64,
+    pub total_cost: Decimal,
+}
+
 /// Backend-agnostic database supertrait.
 ///
 /// Combines all sub-traits into one. Existing `Arc<dyn Database>` consumers
@@ -774,6 +886,7 @@ pub trait Database:
     + ToolFailureStore
     + SettingsStore
     + WorkspaceStore
+    + UserStore
     + Send
     + Sync
 {

src/db/postgres.rs

@@ -16,8 +16,8 @@ use crate::agent::routine::{Routine, RoutineRun, RunStatus};
 use crate::config::DatabaseConfig;
 use crate::context::{ActionRecord, JobContext, JobState};
 use crate::db::{
-    ConversationStore, Database, JobStore, RoutineStore, SandboxStore, SettingsStore,
-    ToolFailureStore, WorkspaceStore,
+    ApiTokenRecord, ConversationStore, Database, JobStore, RoutineStore, SandboxStore,
+    SettingsStore, ToolFailureStore, UserRecord, UserStore, WorkspaceStore,
 };
 use crate::error::{DatabaseError, WorkspaceError};
 use crate::history::{
@@ -786,3 +786,91 @@ impl WorkspaceStore for PgBackend {
             .await
     }
 }
+
+// ==================== UserStore ====================
+
+#[async_trait]
+impl UserStore for PgBackend {
+    async fn create_user(&self, user: &UserRecord) -> Result<(), DatabaseError> {
+        self.store.create_user(user).await
+    }
+
+    async fn get_user(&self, id: &str) -> Result<Option<UserRecord>, DatabaseError> {
+        self.store.get_user(id).await
+    }
+
+    async fn get_user_by_email(&self, email: &str) -> Result<Option<UserRecord>, DatabaseError> {
+        self.store.get_user_by_email(email).await
+    }
+
+    async fn list_users(&self, status: Option<&str>) -> Result<Vec<UserRecord>, DatabaseError> {
+        self.store.list_users(status).await
+    }
+
+    async fn update_user_status(&self, id: &str, status: &str) -> Result<(), DatabaseError> {
+        self.store.update_user_status(id, status).await
+    }
+
+    async fn update_user_profile(
+        &self,
+        id: &str,
+        display_name: &str,
+        metadata: &serde_json::Value,
+    ) -> Result<(), DatabaseError> {
+        self.store
+            .update_user_profile(id, display_name, metadata)
+            .await
+    }
+
+    async fn record_login(&self, id: &str) -> Result<(), DatabaseError> {
+        self.store.record_login(id).await
+    }
+
+    async fn create_api_token(
+        &self,
+        user_id: &str,
+        name: &str,
+        token_hash: &[u8; 32],
+        token_prefix: &str,
+        expires_at: Option<DateTime<Utc>>,
+    ) -> Result<ApiTokenRecord, DatabaseError> {
+        self.store
+            .create_api_token(user_id, name, token_hash, token_prefix, expires_at)
+            .await
+    }
+
+    async fn list_api_tokens(&self, user_id: &str) -> Result<Vec<ApiTokenRecord>, DatabaseError> {
+        self.store.list_api_tokens(user_id).await
+    }
+
+    async fn revoke_api_token(&self, token_id: Uuid, user_id: &str) -> Result<bool, DatabaseError> {
+        self.store.revoke_api_token(token_id, user_id).await
+    }
+
+    async fn authenticate_token(
+        &self,
+        token_hash: &[u8; 32],
+    ) -> Result<Option<(ApiTokenRecord, UserRecord)>, DatabaseError> {
+        self.store.authenticate_token(token_hash).await
+    }
+
+    async fn record_token_usage(&self, token_id: Uuid) -> Result<(), DatabaseError> {
+        self.store.record_token_usage(token_id).await
+    }
+
+    async fn has_any_users(&self) -> Result<bool, DatabaseError> {
+        self.store.has_any_users().await
+    }
+
+    async fn delete_user(&self, id: &str) -> Result<bool, DatabaseError> {
+        self.store.delete_user(id).await
+    }
+
+    async fn user_usage_stats(
+        &self,
+        user_id: Option<&str>,
+        since: DateTime<Utc>,
+    ) -> Result<Vec<crate::db::UserUsageStats>, DatabaseError> {
+        self.store.user_usage_stats(user_id, since).await
+    }
+}

src/db/tls.rs

@@ -2,7 +2,8 @@
 //!
 //! Builds a [`deadpool_postgres::Pool`] with the appropriate TLS connector
 //! based on the configured [`SslMode`].  Uses `rustls` with system root
-//! certificates — the same TLS stack that `reqwest` already uses for HTTP.
+//! certificates, falling back to Mozilla's bundled roots via `webpki-roots`
+//! when the system store is empty (common in minimal container images).
 
 use deadpool_postgres::{Pool, Runtime};
 use thiserror::Error;
@@ -19,9 +20,15 @@ pub enum CreatePoolError {
     TlsConfig(#[from] rustls::Error),
 }
 
-/// Build a rustls-based TLS connector using the platform's root certificate store.
+/// Build a rustls-based TLS connector.
+///
+/// Tries the platform's native certificate store first. If that yields zero
+/// certificates (slim container images, missing ca-certificates package),
+/// falls back to Mozilla's root certificates bundled via `webpki-roots`.
 fn make_rustls_connector() -> Result<MakeRustlsConnect, rustls::Error> {
     let mut root_store = rustls::RootCertStore::empty();
+
+    // Try native certs first.
     let native = rustls_native_certs::load_native_certs();
     for e in &native.errors {
         tracing::warn!("error loading system root certs: {e}");
@@ -31,11 +38,16 @@ fn make_rustls_connector() -> Result<MakeRustlsConnect, rustls::Error> {
             tracing::warn!("skipping invalid system root cert: {e}");
         }
     }
+
+    // Fall back to bundled Mozilla roots when the system store is empty.
     if root_store.is_empty() {
-        tracing::error!("no system root certificates found -- TLS connections will fail");
+        tracing::info!(
+            "no system root certificates found, using bundled Mozilla roots"
+        );
+        root_store.extend(webpki_roots::TLS_SERVER_ROOTS.iter().cloned());
     }
-    // `--all-features` brings in both aws-lc-rs and ring-backed rustls providers.
-    // Pick the same ring provider reqwest already uses so postgres TLS setup stays deterministic.
+
+    // Pick the ring crypto provider (same one reqwest uses).
     let config = rustls::ClientConfig::builder_with_provider(
         rustls::crypto::ring::default_provider().into(),
     )
@@ -48,7 +60,7 @@ fn make_rustls_connector() -> Result<MakeRustlsConnect, rustls::Error> {
 /// Create a [`deadpool_postgres::Pool`] with the appropriate TLS connector.
 ///
 /// - `Disable` → plain TCP (no TLS)
-/// - `Prefer` / `Require` → rustls with system root certificates
+/// - `Prefer` / `Require` → rustls with system or bundled root certificates
 ///
 /// **Note:** `Prefer` and `Require` currently behave identically — both
 /// provide a TLS connector and will fail if the server rejects the TLS
@@ -81,7 +93,6 @@ mod tests {
     fn create_pool_disable_mode() {
         let mut config = deadpool_postgres::Config::new();
         config.url = Some("postgres://localhost/test".to_string());
-        // Should succeed — pool is created lazily, no actual connection needed.
         let pool = create_pool(&config, SslMode::Disable);
         assert!(pool.is_ok());
     }

src/history/store.rs

@@ -2279,6 +2279,410 @@ impl Store {
     }
 }
 
+// ==================== Users / API Tokens / Invitations ====================
+
+#[cfg(feature = "postgres")]
+use crate::db::{ApiTokenRecord, UserRecord};
+
+#[cfg(feature = "postgres")]
+impl Store {
+    /// Create a new user record.
+    pub async fn create_user(&self, user: &UserRecord) -> Result<(), DatabaseError> {
+        let conn = self.conn().await?;
+        conn.execute(
+            r#"
+            INSERT INTO users (id, email, display_name, status, role, created_at, updated_at, last_login_at, created_by, metadata)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+            "#,
+            &[
+                &user.id,
+                &user.email,
+                &user.display_name,
+                &user.status,
+                &user.role,
+                &user.created_at,
+                &user.updated_at,
+                &user.last_login_at,
+                &user.created_by,
+                &user.metadata,
+            ],
+        )
+        .await?;
+        Ok(())
+    }
+
+    /// Get a user by their string id.
+    pub async fn get_user(&self, id: &str) -> Result<Option<UserRecord>, DatabaseError> {
+        let conn = self.conn().await?;
+        let row = conn
+            .query_opt("SELECT id, email, display_name, status, role, created_at, updated_at, last_login_at, created_by, metadata FROM users WHERE id = $1", &[&id])
+            .await?;
+        Ok(row.map(|r| row_to_user(&r)))
+    }
+
+    /// Get a user by email address.
+    pub async fn get_user_by_email(
+        &self,
+        email: &str,
+    ) -> Result<Option<UserRecord>, DatabaseError> {
+        let conn = self.conn().await?;
+        let row = conn
+            .query_opt("SELECT id, email, display_name, status, role, created_at, updated_at, last_login_at, created_by, metadata FROM users WHERE email = $1", &[&email])
+            .await?;
+        Ok(row.map(|r| row_to_user(&r)))
+    }
+
+    /// List users, optionally filtered by status.
+    pub async fn list_users(&self, status: Option<&str>) -> Result<Vec<UserRecord>, DatabaseError> {
+        let conn = self.conn().await?;
+        let rows = match status {
+            Some(s) => {
+                conn.query(
+                    "SELECT id, email, display_name, status, role, created_at, updated_at, last_login_at, created_by, metadata FROM users WHERE status = $1 ORDER BY created_at DESC",
+                    &[&s],
+                )
+                .await?
+            }
+            None => {
+                conn.query("SELECT id, email, display_name, status, role, created_at, updated_at, last_login_at, created_by, metadata FROM users ORDER BY created_at DESC", &[])
+                    .await?
+            }
+        };
+        Ok(rows.iter().map(row_to_user).collect())
+    }
+
+    /// Update a user's status.
+    pub async fn update_user_status(&self, id: &str, status: &str) -> Result<(), DatabaseError> {
+        let conn = self.conn().await?;
+        conn.execute(
+            "UPDATE users SET status = $1, updated_at = NOW() WHERE id = $2",
+            &[&status, &id],
+        )
+        .await?;
+        Ok(())
+    }
+
+    /// Update a user's display name and metadata.
+    pub async fn update_user_profile(
+        &self,
+        id: &str,
+        display_name: &str,
+        metadata: &serde_json::Value,
+    ) -> Result<(), DatabaseError> {
+        let conn = self.conn().await?;
+        conn.execute(
+            "UPDATE users SET display_name = $1, metadata = $2, updated_at = NOW() WHERE id = $3",
+            &[&display_name, metadata, &id],
+        )
+        .await?;
+        Ok(())
+    }
+
+    /// Record a login timestamp for a user.
+    pub async fn record_login(&self, id: &str) -> Result<(), DatabaseError> {
+        let conn = self.conn().await?;
+        conn.execute(
+            "UPDATE users SET last_login_at = NOW(), updated_at = NOW() WHERE id = $1",
+            &[&id],
+        )
+        .await?;
+        Ok(())
+    }
+
+    /// Create a new API token.
+    pub async fn create_api_token(
+        &self,
+        user_id: &str,
+        name: &str,
+        token_hash: &[u8; 32],
+        token_prefix: &str,
+        expires_at: Option<DateTime<Utc>>,
+    ) -> Result<ApiTokenRecord, DatabaseError> {
+        let conn = self.conn().await?;
+        let id = Uuid::new_v4();
+        let now = Utc::now();
+        conn.execute(
+            r#"
+            INSERT INTO api_tokens (id, user_id, token_hash, token_prefix, name, expires_at, created_at)
+            VALUES ($1, $2, $3, $4, $5, $6, $7)
+            "#,
+            &[
+                &id,
+                &user_id,
+                &token_hash.to_vec(),
+                &token_prefix,
+                &name,
+                &expires_at,
+                &now,
+            ],
+        )
+        .await?;
+        Ok(ApiTokenRecord {
+            id,
+            user_id: user_id.to_string(),
+            name: name.to_string(),
+            token_prefix: token_prefix.to_string(),
+            expires_at,
+            last_used_at: None,
+            created_at: now,
+            revoked_at: None,
+        })
+    }
+
+    /// List tokens for a user.
+    pub async fn list_api_tokens(
+        &self,
+        user_id: &str,
+    ) -> Result<Vec<ApiTokenRecord>, DatabaseError> {
+        let conn = self.conn().await?;
+        let rows = conn
+            .query(
+                r#"
+                SELECT id, user_id, name, token_prefix, expires_at, last_used_at, created_at, revoked_at
+                FROM api_tokens
+                WHERE user_id = $1
+                ORDER BY created_at DESC
+                "#,
+                &[&user_id],
+            )
+            .await?;
+        Ok(rows.iter().map(row_to_api_token).collect())
+    }
+
+    /// Soft-revoke a token. Returns false if the token doesn't exist or doesn't belong to the user.
+    pub async fn revoke_api_token(
+        &self,
+        token_id: Uuid,
+        user_id: &str,
+    ) -> Result<bool, DatabaseError> {
+        let conn = self.conn().await?;
+        let count = conn
+            .execute(
+                "UPDATE api_tokens SET revoked_at = NOW() WHERE id = $1 AND user_id = $2 AND revoked_at IS NULL",
+                &[&token_id, &user_id],
+            )
+            .await?;
+        Ok(count > 0)
+    }
+
+    /// Authenticate a token by hash. Returns the token record and its owning user
+    /// if the token is active (non-revoked, non-expired) and the user is active.
+    pub async fn authenticate_token(
+        &self,
+        token_hash: &[u8; 32],
+    ) -> Result<Option<(ApiTokenRecord, UserRecord)>, DatabaseError> {
+        let conn = self.conn().await?;
+        let row = conn
+            .query_opt(
+                r#"
+                SELECT t.id, t.user_id, t.name, t.token_prefix, t.expires_at, t.last_used_at, t.created_at, t.revoked_at,
+                       u.id as u_id, u.email, u.display_name, u.status, u.role, u.created_at as u_created_at, u.updated_at, u.last_login_at, u.created_by, u.metadata
+                FROM api_tokens t
+                JOIN users u ON t.user_id = u.id
+                WHERE t.token_hash = $1
+                  AND t.revoked_at IS NULL
+                  AND (t.expires_at IS NULL OR t.expires_at > NOW())
+                  AND u.status = 'active'
+                "#,
+                &[&token_hash.to_vec()],
+            )
+            .await?;
+        Ok(row.map(|r| {
+            let token = ApiTokenRecord {
+                id: r.get("id"),
+                user_id: r.get("user_id"),
+                name: r.get("name"),
+                token_prefix: r.get("token_prefix"),
+                expires_at: r.get("expires_at"),
+                last_used_at: r.get("last_used_at"),
+                created_at: r.get("created_at"),
+                revoked_at: r.get("revoked_at"),
+            };
+            let user = UserRecord {
+                id: r.get("u_id"),
+                email: r.get("email"),
+                display_name: r.get("display_name"),
+                status: r.get("status"),
+                role: r.get("role"),
+                created_at: r.get("u_created_at"),
+                updated_at: r.get("updated_at"),
+                last_login_at: r.get("last_login_at"),
+                created_by: r.get("created_by"),
+                metadata: r.get("metadata"),
+            };
+            (token, user)
+        }))
+    }
+
+    /// Update `last_used_at` for a token.
+    pub async fn record_token_usage(&self, token_id: Uuid) -> Result<(), DatabaseError> {
+        let conn = self.conn().await?;
+        conn.execute(
+            "UPDATE api_tokens SET last_used_at = NOW() WHERE id = $1",
+            &[&token_id],
+        )
+        .await?;
+        Ok(())
+    }
+
+    /// Check whether any user records exist.
+    pub async fn has_any_users(&self) -> Result<bool, DatabaseError> {
+        let conn = self.conn().await?;
+        let row = conn
+            .query_one(
+                "SELECT EXISTS(SELECT 1 FROM users LIMIT 1) as has_users",
+                &[],
+            )
+            .await?;
+        Ok(row.get("has_users"))
+    }
+
+    /// Delete a user and all their data across all user-scoped tables.
+    /// Returns false if the user doesn't exist.
+    pub async fn delete_user(&self, id: &str) -> Result<bool, DatabaseError> {
+        let mut conn = self.conn().await?;
+        let tx = conn
+            .transaction()
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        // Delete from child tables first to avoid FK violations.
+        // job_events must come before agent_jobs (FK without CASCADE).
+        // agent_jobs cascades to job_actions, llm_calls, estimation_snapshots.
+        // conversations cascades to conversation_messages.
+        // memory_documents cascades to memory_chunks.
+        // routines cascades to routine_runs.
+        // api_tokens cascade automatically via FK on users.
+        for table in &[
+            "settings",
+            "heartbeat_state",
+            "tool_rate_limit_state",
+            "secret_usage_log",
+            "leak_detection_events",
+            "secrets",
+            "wasm_tools",
+            "routines",
+            "memory_documents",
+            "conversations",
+        ] {
+            tx.execute(&format!("DELETE FROM {table} WHERE user_id = $1"), &[&id])
+                .await
+                .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        }
+        // job_events references agent_jobs(id) without CASCADE — delete via subquery.
+        tx.execute(
+            "DELETE FROM job_events WHERE job_id IN (SELECT id FROM agent_jobs WHERE user_id = $1)",
+            &[&id],
+        )
+        .await
+        .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        tx.execute("DELETE FROM agent_jobs WHERE user_id = $1", &[&id])
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        // Nullify self-referencing created_by before deleting the user
+        tx.execute(
+            "UPDATE users SET created_by = NULL WHERE created_by = $1",
+            &[&id],
+        )
+        .await
+        .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        // api_tokens cascade automatically via FK
+        let result = tx
+            .execute("DELETE FROM users WHERE id = $1", &[&id])
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        tx.commit()
+            .await
+            .map_err(|e| DatabaseError::Query(e.to_string()))?;
+        Ok(result > 0)
+    }
+
+    /// Get per-user LLM usage stats for a time period.
+    /// Aggregates from llm_calls via agent_jobs.user_id.
+    pub async fn user_usage_stats(
+        &self,
+        user_id: Option<&str>,
+        since: DateTime<Utc>,
+    ) -> Result<Vec<crate::db::UserUsageStats>, DatabaseError> {
+        let conn = self.conn().await?;
+        let rows = if let Some(uid) = user_id {
+            conn.query(
+                r#"
+                SELECT j.user_id, l.model, COUNT(*) as call_count,
+                       COALESCE(SUM(l.input_tokens), 0) as input_tokens,
+                       COALESCE(SUM(l.output_tokens), 0) as output_tokens,
+                       COALESCE(SUM(l.cost), 0) as total_cost
+                FROM llm_calls l
+                JOIN agent_jobs j ON l.job_id = j.id
+                WHERE l.created_at >= $1
+                  AND j.user_id = $2
+                GROUP BY j.user_id, l.model
+                ORDER BY total_cost DESC
+                "#,
+                &[&since, &uid],
+            )
+            .await?
+        } else {
+            conn.query(
+                r#"
+                SELECT j.user_id, l.model, COUNT(*) as call_count,
+                       COALESCE(SUM(l.input_tokens), 0) as input_tokens,
+                       COALESCE(SUM(l.output_tokens), 0) as output_tokens,
+                       COALESCE(SUM(l.cost), 0) as total_cost
+                FROM llm_calls l
+                JOIN agent_jobs j ON l.job_id = j.id
+                WHERE l.created_at >= $1
+                GROUP BY j.user_id, l.model
+                ORDER BY total_cost DESC
+                "#,
+                &[&since],
+            )
+            .await?
+        };
+        let mut stats = Vec::with_capacity(rows.len());
+        for row in &rows {
+            stats.push(crate::db::UserUsageStats {
+                user_id: row.get("user_id"),
+                model: row.get("model"),
+                call_count: row.get("call_count"),
+                input_tokens: row.get("input_tokens"),
+                output_tokens: row.get("output_tokens"),
+                total_cost: row.get("total_cost"),
+            });
+        }
+        Ok(stats)
+    }
+}
+
+#[cfg(feature = "postgres")]
+fn row_to_user(row: &tokio_postgres::Row) -> UserRecord {
+    UserRecord {
+        id: row.get("id"),
+        email: row.get("email"),
+        display_name: row.get("display_name"),
+        status: row.get("status"),
+        role: row.get("role"),
+        created_at: row.get("created_at"),
+        updated_at: row.get("updated_at"),
+        last_login_at: row.get("last_login_at"),
+        created_by: row.get("created_by"),
+        metadata: row.get("metadata"),
+    }
+}
+
+#[cfg(feature = "postgres")]
+fn row_to_api_token(row: &tokio_postgres::Row) -> ApiTokenRecord {
+    ApiTokenRecord {
+        id: row.get("id"),
+        user_id: row.get("user_id"),
+        name: row.get("name"),
+        token_prefix: row.get("token_prefix"),
+        expires_at: row.get("expires_at"),
+        last_used_at: row.get("last_used_at"),
+        created_at: row.get("created_at"),
+        revoked_at: row.get("revoked_at"),
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/llm/rig_adapter.rs

@@ -601,11 +601,14 @@ fn build_rig_request(
 /// Inject a per-request model override into the rig request's `additional_params`.
 ///
 /// Rig-core bakes the model name at construction time inside each provider's
-/// `CompletionModel` implementation. The actual HTTP request body includes a
-/// `model` field set by the provider. Rig-core's `#[serde(flatten)]` on
-/// `additional_params` emits these fields AFTER the provider's own fields.
-/// Most API servers (Python, Go) use last-key-wins when deserializing
-/// duplicate JSON keys, so the injected `model` value takes effect.
+/// `CompletionModel` implementation. This helper inserts a top-level `"model"`
+/// key into `additional_params`, which rig-core flattens into the provider's
+/// request payload via `#[serde(flatten)]`.
+///
+/// Whether the override takes effect depends on the downstream API server's
+/// handling of duplicate JSON keys (most Python/Go servers use last-key-wins,
+/// but this is not guaranteed by the JSON spec). The `effective_model_name()`
+/// trait method should be consulted to determine the model actually used.
 fn inject_model_override(rig_req: &mut RigRequest, model_override: Option<&str>) {
     let Some(model) = model_override else {
         return;
@@ -1515,4 +1518,51 @@ mod tests {
             "different raw IDs should produce different hashed IDs"
         );
     }
+
+    fn make_rig_request(additional_params: Option<serde_json::Value>) -> RigRequest {
+        RigRequest {
+            preamble: None,
+            chat_history: OneOrMany::one(RigMessage::user("test")),
+            documents: Vec::new(),
+            tools: Vec::new(),
+            temperature: None,
+            max_tokens: None,
+            tool_choice: None,
+            additional_params,
+        }
+    }
+
+    #[test]
+    fn test_inject_model_override_creates_params_when_none() {
+        let mut req = make_rig_request(None);
+        inject_model_override(&mut req, Some("test-model"));
+
+        let params = req
+            .additional_params
+            .expect("additional_params should be Some");
+        assert_eq!(params, serde_json::json!({ "model": "test-model" }));
+    }
+
+    #[test]
+    fn test_inject_model_override_preserves_existing_params() {
+        let mut req = make_rig_request(Some(serde_json::json!({
+            "cache_control": { "type": "ephemeral" },
+        })));
+        inject_model_override(&mut req, Some("override-model"));
+
+        let params = req.additional_params.expect("should remain Some");
+        let obj = params.as_object().expect("should be object");
+        assert_eq!(
+            obj.get("cache_control"),
+            Some(&serde_json::json!({ "type": "ephemeral" }))
+        );
+        assert_eq!(obj.get("model"), Some(&serde_json::json!("override-model")));
+    }
+
+    #[test]
+    fn test_inject_model_override_noop_when_none() {
+        let mut req = make_rig_request(None);
+        inject_model_override(&mut req, None);
+        assert!(req.additional_params.is_none());
+    }
 }

src/main.rs

@@ -591,27 +591,7 @@ async fn async_main() -> anyhow::Result<()> {
     let mut gateway_url: Option<String> = None;
     let mut sse_manager: Option<std::sync::Arc<ironclaw::channels::web::sse::SseManager>> = None;
     if let Some(ref gw_config) = config.channels.gateway {
-        // Build multi-user auth state if user_tokens is configured, else single-user.
-        let mut gw = if let Some(ref user_tokens) = gw_config.user_tokens {
-            use ironclaw::channels::web::auth::{MultiAuthState, UserIdentity};
-            let tokens = user_tokens
-                .iter()
-                .map(|(token, cfg)| {
-                    (
-                        token.clone(),
-                        UserIdentity {
-                            user_id: cfg.user_id.clone(),
-                            workspace_read_scopes: cfg.workspace_read_scopes.clone(),
-                        },
-                    )
-                })
-                .collect();
-            let auth = MultiAuthState::multi(tokens);
-            GatewayChannel::new_multi_auth(gw_config.clone(), auth)
-        } else {
-            GatewayChannel::new(gw_config.clone())
-        };
-        gw = gw.with_owner_scope(config.owner_id.clone());
+        let mut gw = GatewayChannel::new(gw_config.clone(), config.owner_id.clone());
         gw = gw.with_llm_provider(Arc::clone(&components.llm));
         if let Some(ref ws) = components.workspace {
             gw = gw.with_workspace(Arc::clone(ws));
@@ -650,6 +630,54 @@ async fn async_main() -> anyhow::Result<()> {
         }
         if let Some(ref d) = components.db {
             gw = gw.with_store(Arc::clone(d));
+            gw = gw.with_db_auth(Arc::clone(d));
+            if let Some(ref ss) = components.secrets_store {
+                gw = gw.with_secrets_store(Arc::clone(ss));
+            }
+
+            // Bootstrap: create the first admin user from single-user config
+            // so the owner appears in the Users admin panel immediately.
+            if let Ok(false) = d.has_any_users().await {
+                let now = chrono::Utc::now();
+                let user = ironclaw::db::UserRecord {
+                    id: config.owner_id.clone(),
+                    email: None,
+                    display_name: config.owner_id.clone(),
+                    status: "active".to_string(),
+                    role: "admin".to_string(),
+                    created_at: now,
+                    updated_at: now,
+                    last_login_at: None,
+                    created_by: None,
+                    metadata: serde_json::json!({"source": "bootstrap"}),
+                };
+                if let Err(e) = d.create_user(&user).await {
+                    tracing::warn!("Failed to bootstrap admin user: {}", e);
+                } else {
+                    // Also create an API token from the gateway auth token so
+                    // DB-backed auth works for the bootstrapped user.
+                    let auth_token = gw.auth_token();
+                    if !auth_token.is_empty() {
+                        use ironclaw::channels::web::auth::hash_token;
+                        let hash = hash_token(auth_token);
+                        let prefix = if auth_token.len() >= 8 {
+                            &auth_token[..8]
+                        } else {
+                            auth_token
+                        };
+                        if let Err(e) = d
+                            .create_api_token(&config.owner_id, "bootstrap", &hash, prefix, None)
+                            .await
+                        {
+                            tracing::warn!("Failed to create bootstrap token: {}", e);
+                        }
+                    }
+                    tracing::info!(
+                        user_id = config.owner_id,
+                        "Bootstrapped admin user from gateway config"
+                    );
+                }
+            }
         }
         if let Some(ref jm) = container_job_manager {
             gw = gw.with_job_manager(Arc::clone(jm));
@@ -791,12 +819,7 @@ async fn async_main() -> anyhow::Result<()> {
         .await;
 
     // Default user ID for extension operations (single-user mode).
-    let ext_user_id = config
-        .channels
-        .gateway
-        .as_ref()
-        .map(|g| g.user_id.clone())
-        .unwrap_or_else(|| "default".to_string());
+    let ext_user_id = config.owner_id.clone();
 
     // Wire up channel runtime for hot-activation of WASM channels.
     if let Some(ref ext_mgr) = components.extension_manager

src/settings.rs

@@ -269,10 +269,6 @@ pub struct ChannelSettings {
     #[serde(default)]
     pub gateway_auth_token: Option<String>,
 
-    /// Web gateway user ID.
-    #[serde(default)]
-    pub gateway_user_id: Option<String>,
-
     /// Whether the CLI channel is enabled.
     #[serde(default = "default_true")]
     pub cli_enabled: bool,
@@ -342,7 +338,6 @@ impl Default for ChannelSettings {
             gateway_host: None,
             gateway_port: None,
             gateway_auth_token: None,
-            gateway_user_id: None,
             cli_enabled: true,
             signal_enabled: false,
             signal_http_url: None,

src/tenant.rs

@@ -330,35 +330,62 @@ impl TenantScope {
 
     /// Add a message to a conversation owned by this tenant.
     ///
-    /// Verifies the conversation belongs to this user before adding.
+    /// Returns `NotFound` if the conversation does not belong to this user.
     pub async fn add_conversation_message(
         &self,
         conversation_id: Uuid,
         role: &str,
         content: &str,
     ) -> Result<Uuid, DatabaseError> {
+        if !self.conversation_belongs_to_user(conversation_id).await? {
+            return Err(DatabaseError::NotFound {
+                entity: "conversation".to_string(),
+                id: conversation_id.to_string(),
+            });
+        }
         self.inner
             .add_conversation_message(conversation_id, role, content)
             .await
     }
 
+    /// Touch a conversation timestamp. Returns `NotFound` if not owned by this user.
     pub async fn touch_conversation(&self, id: Uuid) -> Result<(), DatabaseError> {
+        if !self.conversation_belongs_to_user(id).await? {
+            return Err(DatabaseError::NotFound {
+                entity: "conversation".to_string(),
+                id: id.to_string(),
+            });
+        }
         self.inner.touch_conversation(id).await
     }
 
+    /// List messages in a conversation. Returns `NotFound` if not owned by this user.
     pub async fn list_conversation_messages(
         &self,
         conversation_id: Uuid,
     ) -> Result<Vec<ConversationMessage>, DatabaseError> {
+        if !self.conversation_belongs_to_user(conversation_id).await? {
+            return Err(DatabaseError::NotFound {
+                entity: "conversation".to_string(),
+                id: conversation_id.to_string(),
+            });
+        }
         self.inner.list_conversation_messages(conversation_id).await
     }
 
+    /// Paginated message listing. Returns `NotFound` if not owned by this user.
     pub async fn list_conversation_messages_paginated(
         &self,
         conversation_id: Uuid,
         before: Option<DateTime<Utc>>,
         limit: i64,
     ) -> Result<(Vec<ConversationMessage>, bool), DatabaseError> {
+        if !self.conversation_belongs_to_user(conversation_id).await? {
+            return Err(DatabaseError::NotFound {
+                entity: "conversation".to_string(),
+                id: conversation_id.to_string(),
+            });
+        }
         self.inner
             .list_conversation_messages_paginated(conversation_id, before, limit)
             .await
@@ -374,21 +401,35 @@ impl TenantScope {
             .await
     }
 
+    /// Update metadata on a conversation. Returns `NotFound` if not owned by this user.
     pub async fn update_conversation_metadata_field(
         &self,
         id: Uuid,
         key: &str,
         value: &serde_json::Value,
     ) -> Result<(), DatabaseError> {
+        if !self.conversation_belongs_to_user(id).await? {
+            return Err(DatabaseError::NotFound {
+                entity: "conversation".to_string(),
+                id: id.to_string(),
+            });
+        }
         self.inner
             .update_conversation_metadata_field(id, key, value)
             .await
     }
 
+    /// Get conversation metadata. Returns `NotFound` if not owned by this user.
     pub async fn get_conversation_metadata(
         &self,
         id: Uuid,
     ) -> Result<Option<serde_json::Value>, DatabaseError> {
+        if !self.conversation_belongs_to_user(id).await? {
+            return Err(DatabaseError::NotFound {
+                entity: "conversation".to_string(),
+                id: id.to_string(),
+            });
+        }
         self.inner.get_conversation_metadata(id).await
     }
 }

src/tools/builtin/abound.rs

@@ -0,0 +1,563 @@
+//! Mock Abound API tools for demo purposes.
+//!
+//! These tools simulate Abound's backend API (account info, wire transfers,
+//! exchange rates, notifications, forex scoring) with realistic mock data.
+//! They are feature-gated behind `--features demo` and will be replaced by
+//! real WASM tools once Abound's backend is live.
+
+use std::time::Instant;
+
+use async_trait::async_trait;
+use chrono::{Datelike, Utc};
+use rand::Rng;
+use serde_json::json;
+
+use crate::context::JobContext;
+use crate::tools::tool::{ApprovalRequirement, Tool, ToolError, ToolOutput, require_str};
+
+// ---------------------------------------------------------------------------
+// Tool 1: Get Account Info
+// ---------------------------------------------------------------------------
+
+/// Returns mock Abound account data (limits, recipients, funding sources).
+pub struct AboundGetAccountInfoTool;
+
+#[async_trait]
+impl Tool for AboundGetAccountInfoTool {
+    fn name(&self) -> &str {
+        "abound_get_account_info"
+    }
+
+    fn description(&self) -> &str {
+        "Retrieve the authenticated user's Abound account information including \
+         transfer limits, payment reasons, recipients, and funding sources."
+    }
+
+    fn parameters_schema(&self) -> serde_json::Value {
+        json!({
+            "type": "object",
+            "properties": {},
+            "required": []
+        })
+    }
+
+    async fn execute(
+        &self,
+        _params: serde_json::Value,
+        _ctx: &JobContext,
+    ) -> Result<ToolOutput, ToolError> {
+        let start = Instant::now();
+
+        let data = json!({
+            "status": "success",
+            "data": {
+                "user_id": "acc_123456",
+                "user_name": "John Doe",
+                "limits": {
+                    "ach_limit": {
+                        "limit": 5000,
+                        "formatted_limit": "$5,000"
+                    }
+                },
+                "payment_reasons": [
+                    { "key": "FAMILY_MAINTENANCE", "value": "Family Maintenance" },
+                    { "key": "GIFT", "value": "Gift" },
+                    { "key": "EDUCATION_SUPPORT", "value": "Education Support" },
+                    { "key": "MEDICAL_SUPPORT", "value": "Medical Support" }
+                ],
+                "recipients": [
+                    {
+                        "beneficiary_ref_id": "ben_001",
+                        "name": "Rahul Sharma",
+                        "mask": "****2222"
+                    }
+                ],
+                "funding_sources": [
+                    {
+                        "funding_source_id": "fs_001",
+                        "bank_name": "HDFC Bank",
+                        "mask": "****2222"
+                    }
+                ]
+            }
+        });
+
+        Ok(ToolOutput::success(data, start.elapsed()))
+    }
+
+    fn requires_sanitization(&self) -> bool {
+        false
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tool 2: Get Exchange Rate
+// ---------------------------------------------------------------------------
+
+/// Returns mock USD/INR exchange rate with slight randomization.
+pub struct AboundGetExchangeRateTool;
+
+/// Generate a mock USD/INR rate with slight jitter around 85.42.
+fn mock_exchange_rate() -> f64 {
+    let mut rng = rand::thread_rng();
+    let jitter: f64 = rng.gen_range(-0.30..=0.30);
+    ((85.42 + jitter) * 100.0).round() / 100.0
+}
+
+#[async_trait]
+impl Tool for AboundGetExchangeRateTool {
+    fn name(&self) -> &str {
+        "abound_get_exchange_rate"
+    }
+
+    fn description(&self) -> &str {
+        "Get the current USD to INR exchange rate including the effective rate \
+         after fees. Use this before initiating any wire transfer."
+    }
+
+    fn parameters_schema(&self) -> serde_json::Value {
+        json!({
+            "type": "object",
+            "properties": {},
+            "required": []
+        })
+    }
+
+    async fn execute(
+        &self,
+        _params: serde_json::Value,
+        _ctx: &JobContext,
+    ) -> Result<ToolOutput, ToolError> {
+        let start = Instant::now();
+
+        let rate = mock_exchange_rate();
+        let effective = ((rate - 0.32) * 100.0).round() / 100.0;
+
+        let data = json!({
+            "status": "success",
+            "data": {
+                "from_currency": "USD",
+                "to_currency": "INR",
+                "current_exchange_rate": {
+                    "formatted_value": format!("{rate:.2}"),
+                    "value": rate
+                },
+                "effective_exchange_rate": {
+                    "formatted_value": format!("{effective:.2}"),
+                    "value": effective
+                }
+            }
+        });
+
+        Ok(ToolOutput::success(data, start.elapsed()))
+    }
+
+    fn requires_sanitization(&self) -> bool {
+        false
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tool 3: Send Wire
+// ---------------------------------------------------------------------------
+
+/// Simulates a wire transfer. Requires approval before execution.
+pub struct AboundSendWireTool;
+
+#[async_trait]
+impl Tool for AboundSendWireTool {
+    fn name(&self) -> &str {
+        "abound_send_wire"
+    }
+
+    fn description(&self) -> &str {
+        "Submit a wire transfer to send USD to an INR recipient. Requires a \
+         funding source, beneficiary, amount in USD, and payment reason. \
+         The transfer amount must not exceed the user's ACH limit."
+    }
+
+    fn parameters_schema(&self) -> serde_json::Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "funding_source_id": {
+                    "type": "string",
+                    "description": "Funding source ID (e.g. 'fs_001')"
+                },
+                "beneficiary_ref_id": {
+                    "type": "string",
+                    "description": "Beneficiary reference ID (e.g. 'ben_001')"
+                },
+                "amount": {
+                    "type": "number",
+                    "description": "Amount in USD to send"
+                },
+                "payment_reason_key": {
+                    "type": "string",
+                    "description": "Payment reason key: FAMILY_MAINTENANCE, GIFT, EDUCATION_SUPPORT, or MEDICAL_SUPPORT"
+                }
+            },
+            "required": ["funding_source_id", "beneficiary_ref_id", "amount", "payment_reason_key"]
+        })
+    }
+
+    async fn execute(
+        &self,
+        params: serde_json::Value,
+        _ctx: &JobContext,
+    ) -> Result<ToolOutput, ToolError> {
+        let start = Instant::now();
+
+        let _funding_source = require_str(&params, "funding_source_id")?;
+        let _beneficiary = require_str(&params, "beneficiary_ref_id")?;
+        let _reason = require_str(&params, "payment_reason_key")?;
+
+        let amount = params
+            .get("amount")
+            .and_then(|v| v.as_f64())
+            .ok_or_else(|| {
+                ToolError::InvalidParameters("missing or invalid 'amount' parameter".to_string())
+            })?;
+
+        // Enforce mock ACH limit
+        if amount > 5000.0 {
+            let data = json!({
+                "status": "error",
+                "error": {
+                    "code": "TRANSFER_NOT_ALLOWED",
+                    "message": format!(
+                        "Transfer amount ${:.2} exceeds your ACH limit of $5,000.00",
+                        amount
+                    )
+                }
+            });
+            return Ok(ToolOutput::success(data, start.elapsed()));
+        }
+
+        if amount <= 0.0 {
+            return Err(ToolError::InvalidParameters(
+                "amount must be greater than zero".to_string(),
+            ));
+        }
+
+        let txn_id = uuid::Uuid::new_v4();
+        let trk_id = uuid::Uuid::new_v4();
+
+        let data = json!({
+            "status": "success",
+            "data": {
+                "transaction_id": format!("txn_{}", &txn_id.to_string()[..8]),
+                "tracking_id": format!("trk_{}", &trk_id.to_string()[..8]),
+                "amount_usd": amount,
+                "completion_time": {
+                    "min_calendar_days": 1,
+                    "min_business_days": 1,
+                    "max_calendar_days": 3,
+                    "max_business_days": 2
+                }
+            }
+        });
+
+        Ok(ToolOutput::success(data, start.elapsed()))
+    }
+
+    fn requires_approval(&self, _params: &serde_json::Value) -> ApprovalRequirement {
+        ApprovalRequirement::UnlessAutoApproved
+    }
+
+    fn requires_sanitization(&self) -> bool {
+        false
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tool 4: Create Notification
+// ---------------------------------------------------------------------------
+
+/// Simulates sending a notification to the Abound system.
+pub struct AboundCreateNotificationTool;
+
+#[async_trait]
+impl Tool for AboundCreateNotificationTool {
+    fn name(&self) -> &str {
+        "abound_create_notification"
+    }
+
+    fn description(&self) -> &str {
+        "Create a notification in the Abound app (e.g. rate alert, transfer \
+         confirmation, forex scoring signal). Returns 202 accepted."
+    }
+
+    fn parameters_schema(&self) -> serde_json::Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "message_id": {
+                    "type": "string",
+                    "description": "Unique message identifier"
+                },
+                "action_type": {
+                    "type": "string",
+                    "description": "Notification type: 'notification' or 'token_refresh'"
+                },
+                "meta_data": {
+                    "type": "object",
+                    "description": "Additional metadata (e.g. score, rate, signal)"
+                }
+            },
+            "required": ["message_id", "action_type"]
+        })
+    }
+
+    async fn execute(
+        &self,
+        params: serde_json::Value,
+        _ctx: &JobContext,
+    ) -> Result<ToolOutput, ToolError> {
+        let start = Instant::now();
+
+        let message_id = require_str(&params, "message_id")?;
+
+        let data = json!({
+            "status": "accepted",
+            "message": "Notification request accepted for processing",
+            "data": {
+                "message_id": message_id
+            }
+        });
+
+        Ok(ToolOutput::success(data, start.elapsed()))
+    }
+
+    fn requires_sanitization(&self) -> bool {
+        false
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tool 5: Forex Score
+// ---------------------------------------------------------------------------
+
+/// Seasonal bias factors by month (1-indexed: Jan=1 .. Dec=12).
+/// High bias in Oct-Mar (favorable remittance window), low Apr-Sep.
+const SEASONAL_BIAS: [f64; 13] = [
+    0.0, // placeholder for 0-index
+    0.75, // Jan
+    0.70, // Feb
+    0.65, // Mar
+    0.35, // Apr
+    0.30, // May
+    0.25, // Jun
+    0.25, // Jul
+    0.30, // Aug
+    0.35, // Sep
+    0.70, // Oct
+    0.75, // Nov
+    0.65, // Dec
+];
+
+/// Computes a forex timing score for USD/INR, biased toward interesting
+/// signals (60-80 range) for demo purposes.
+pub struct AboundGetForexScoreTool;
+
+#[async_trait]
+impl Tool for AboundGetForexScoreTool {
+    fn name(&self) -> &str {
+        "abound_get_forex_score"
+    }
+
+    fn description(&self) -> &str {
+        "Compute a forex timing score (0-100) for USD/INR transfers. Returns \
+         a score with a signal: 'convert_now' (>=60, good time to send), \
+         'split_transfer' (40-59, send half now), or 'wait' (<40, hold off). \
+         Use this to advise users on optimal transfer timing."
+    }
+
+    fn parameters_schema(&self) -> serde_json::Value {
+        json!({
+            "type": "object",
+            "properties": {},
+            "required": []
+        })
+    }
+
+    async fn execute(
+        &self,
+        _params: serde_json::Value,
+        _ctx: &JobContext,
+    ) -> Result<ToolOutput, ToolError> {
+        let start = Instant::now();
+
+        let mut rng = rand::thread_rng();
+
+        // Mock current rate and MA50
+        let rate = mock_exchange_rate();
+        let ma50_jitter: f64 = rng.gen_range(-0.20..=0.20);
+        let ma50 = ((84.50 + ma50_jitter) * 100.0).round() / 100.0;
+
+        // Get seasonal bias for current month
+        let month = Utc::now().month() as usize;
+        let month_bias = SEASONAL_BIAS[month.clamp(1, 12)];
+
+        // Scoring weights
+        let w_ma = 0.7;
+        let w_s = 0.3;
+
+        // MA-based signal: how far current rate is above the 50-day average
+        let ma_signal = (50.0 + ((rate - ma50) / ma50 * 100.0) * 15.0).clamp(0.0, 100.0);
+
+        // Combined score
+        let raw_score = (ma_signal * w_ma + month_bias * 100.0 * w_s) / (w_ma + w_s);
+
+        // Bias toward 60-80 for demo (blend raw score with a favorable base)
+        let demo_base = 68.0;
+        let score = ((raw_score * 0.4 + demo_base * 0.6) as u32).clamp(55, 85);
+
+        let signal = if score >= 60 {
+            "convert_now"
+        } else if score >= 40 {
+            "split_transfer"
+        } else {
+            "wait"
+        };
+
+        let explanation = match signal {
+            "convert_now" => format!(
+                "The current USD/INR rate of {rate:.2} is above the 50-day moving average \
+                 of {ma50:.2}, and seasonal trends are favorable. This is a good time to \
+                 convert and send money."
+            ),
+            "split_transfer" => format!(
+                "The rate of {rate:.2} is near the 50-day average of {ma50:.2}. Consider \
+                 splitting your transfer \u{2014} send half now and hold the rest for a \
+                 potentially better rate."
+            ),
+            _ => format!(
+                "The current rate of {rate:.2} is below the 50-day average of {ma50:.2}. \
+                 Unless urgent, consider waiting for a better rate."
+            ),
+        };
+
+        let data = json!({
+            "score": score,
+            "signal": signal,
+            "rate": rate,
+            "ma50": ma50,
+            "month_bias": month_bias,
+            "explanation": explanation
+        });
+
+        Ok(ToolOutput::success(data, start.elapsed()))
+    }
+
+    fn requires_sanitization(&self) -> bool {
+        false
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::context::JobContext;
+
+    fn test_ctx() -> JobContext {
+        JobContext::with_user("test-user", "test", "mock abound tool test")
+    }
+
+    #[tokio::test]
+    async fn account_info_returns_valid_json() {
+        let tool = AboundGetAccountInfoTool;
+        let result = tool.execute(json!({}), &test_ctx()).await.unwrap();
+        let data = &result.result["data"];
+        assert_eq!(data["user_id"], "acc_123456");
+        assert_eq!(data["limits"]["ach_limit"]["limit"], 5000);
+        assert_eq!(data["recipients"].as_array().unwrap().len(), 1);
+        assert_eq!(data["funding_sources"].as_array().unwrap().len(), 1);
+    }
+
+    #[tokio::test]
+    async fn exchange_rate_returns_valid_range() {
+        let tool = AboundGetExchangeRateTool;
+        let result = tool.execute(json!({}), &test_ctx()).await.unwrap();
+        let rate = result.result["data"]["current_exchange_rate"]["value"]
+            .as_f64()
+            .unwrap();
+        // Rate should be within jitter range of base 85.42
+        assert!(rate > 85.0 && rate < 85.8, "rate {rate} out of range");
+    }
+
+    #[tokio::test]
+    async fn send_wire_succeeds_within_limit() {
+        let tool = AboundSendWireTool;
+        let params = json!({
+            "funding_source_id": "fs_001",
+            "beneficiary_ref_id": "ben_001",
+            "amount": 1000.0,
+            "payment_reason_key": "FAMILY_MAINTENANCE"
+        });
+        let result = tool.execute(params, &test_ctx()).await.unwrap();
+        assert_eq!(result.result["status"], "success");
+        assert!(result.result["data"]["transaction_id"]
+            .as_str()
+            .unwrap()
+            .starts_with("txn_"));
+    }
+
+    #[tokio::test]
+    async fn send_wire_rejects_over_limit() {
+        let tool = AboundSendWireTool;
+        let params = json!({
+            "funding_source_id": "fs_001",
+            "beneficiary_ref_id": "ben_001",
+            "amount": 6000.0,
+            "payment_reason_key": "FAMILY_MAINTENANCE"
+        });
+        let result = tool.execute(params, &test_ctx()).await.unwrap();
+        assert_eq!(result.result["status"], "error");
+        assert_eq!(result.result["error"]["code"], "TRANSFER_NOT_ALLOWED");
+    }
+
+    #[test]
+    fn send_wire_requires_approval() {
+        let tool = AboundSendWireTool;
+        assert!(matches!(
+            tool.requires_approval(&json!({})),
+            ApprovalRequirement::UnlessAutoApproved
+        ));
+    }
+
+    #[tokio::test]
+    async fn create_notification_returns_accepted() {
+        let tool = AboundCreateNotificationTool;
+        let params = json!({
+            "message_id": "msg_001",
+            "action_type": "notification",
+            "meta_data": { "score": 72 }
+        });
+        let result = tool.execute(params, &test_ctx()).await.unwrap();
+        assert_eq!(result.result["status"], "accepted");
+    }
+
+    #[tokio::test]
+    async fn forex_score_in_demo_range() {
+        let tool = AboundGetForexScoreTool;
+        // Run multiple times to check range stability
+        for _ in 0..20 {
+            let result = tool.execute(json!({}), &test_ctx()).await.unwrap();
+            let score = result.result["score"].as_u64().unwrap();
+            assert!(
+                (55..=85).contains(&score),
+                "score {score} outside demo range [55, 85]"
+            );
+            let signal = result.result["signal"].as_str().unwrap();
+            assert!(
+                signal == "convert_now" || signal == "split_transfer" || signal == "wait",
+                "unexpected signal: {signal}"
+            );
+        }
+    }
+}

src/tools/builtin/mod.rs

@@ -1,5 +1,7 @@
 //! Built-in tools that come with the agent.
 
+#[cfg(feature = "demo")]
+mod abound;
 mod echo;
 pub mod extension_tools;
 mod file;
@@ -17,6 +19,11 @@ pub mod skill_tools;
 mod time;
 mod tool_info;
 
+#[cfg(feature = "demo")]
+pub use abound::{
+    AboundCreateNotificationTool, AboundGetAccountInfoTool, AboundGetExchangeRateTool,
+    AboundGetForexScoreTool, AboundSendWireTool,
+};
 pub use echo::EchoTool;
 pub use extension_tools::{
     ExtensionInfoTool, ToolActivateTool, ToolAuthTool, ToolInstallTool, ToolListTool,

src/tools/registry.rs

@@ -16,6 +16,11 @@ use crate::skills::registry::SkillRegistry;
 use crate::tools::builder::{
     BuildSoftwareTool, BuilderConfig, LlmSoftwareBuilder, SoftwareBuilder,
 };
+#[cfg(feature = "demo")]
+use crate::tools::builtin::{
+    AboundCreateNotificationTool, AboundGetAccountInfoTool, AboundGetExchangeRateTool,
+    AboundGetForexScoreTool, AboundSendWireTool,
+};
 use crate::tools::builtin::{
     ApplyPatchTool, CancelJobTool, CreateJobTool, EchoTool, ExtensionInfoTool, HttpTool,
     JobEventsTool, JobPromptTool, JobStatusTool, JsonTool, ListDirTool, ListJobsTool,
@@ -248,6 +253,16 @@ impl ToolRegistry {
         }
         self.register_sync(Arc::new(http));
 
+        // Abound demo tools (mock APIs — only compiled with --features demo)
+        #[cfg(feature = "demo")]
+        {
+            self.register_sync(Arc::new(AboundGetAccountInfoTool));
+            self.register_sync(Arc::new(AboundGetExchangeRateTool));
+            self.register_sync(Arc::new(AboundSendWireTool));
+            self.register_sync(Arc::new(AboundCreateNotificationTool));
+            self.register_sync(Arc::new(AboundGetForexScoreTool));
+        }
+
         tracing::debug!("Registered {} built-in tools", self.count());
     }
 

src/tunnel/mod.rs

@@ -428,10 +428,8 @@ mod tests {
             host: "127.0.0.1".to_string(),
             port: 3000,
             auth_token: None,
-            user_id: "test".to_string(),
             workspace_read_scopes: Vec::new(),
             memory_layers: Vec::new(),
-            user_tokens: None,
         });
         c
     }
@@ -442,10 +440,8 @@ mod tests {
             host: host.to_string(),
             port,
             auth_token: None,
-            user_id: "test".to_string(),
             workspace_read_scopes: Vec::new(),
             memory_layers: Vec::new(),
-            user_tokens: None,
         });
         c
     }

tests/e2e/conftest.py

@@ -271,7 +271,6 @@ async def ironclaw_server(
         "GATEWAY_HOST": "127.0.0.1",
         "GATEWAY_PORT": str(gateway_port),
         "GATEWAY_AUTH_TOKEN": AUTH_TOKEN,
-        "GATEWAY_USER_ID": "e2e-web-sender",
         "HTTP_HOST": "127.0.0.1",
         "HTTP_PORT": str(http_port),
         "HTTP_WEBHOOK_SECRET": HTTP_WEBHOOK_SECRET,
@@ -371,7 +370,6 @@ async def hosted_oauth_refresh_server(
             "GATEWAY_HOST": "127.0.0.1",
             "GATEWAY_PORT": str(gateway_port),
             "GATEWAY_AUTH_TOKEN": AUTH_TOKEN,
-            "GATEWAY_USER_ID": OWNER_SCOPE_ID,
             "HTTP_HOST": "127.0.0.1",
             "HTTP_PORT": str(http_port),
             "HTTP_WEBHOOK_SECRET": HTTP_WEBHOOK_SECRET,
@@ -411,7 +409,6 @@ async def hosted_oauth_refresh_server(
             yield {
                 "base_url": base_url,
                 "db_path": db_path,
-                "gateway_user_id": OWNER_SCOPE_ID,
                 "mock_llm_url": mock_llm_server,
             }
         except TimeoutError:
@@ -473,7 +470,6 @@ async def http_channel_server_without_secret(
         "GATEWAY_HOST": "127.0.0.1",
         "GATEWAY_PORT": str(gateway_port),
         "GATEWAY_AUTH_TOKEN": AUTH_TOKEN,
-        "GATEWAY_USER_ID": "e2e-tester",
         "HTTP_HOST": "127.0.0.1",
         "HTTP_PORT": str(http_port),
         "CLI_ENABLED": "false",

tests/multi_tenant_integration.rs

@@ -42,8 +42,6 @@ const ALICE_USER_ID: &str = "alice";
 const BOB_USER_ID: &str = "bob";
 const OWNER_TOKEN: &str = "tok-owner-secret";
 const OWNER_SCOPE_ID: &str = "owner-scope";
-const GATEWAY_SENDER_ID: &str = "gateway-sender";
-
 /// Build a MultiAuthState with two users.
 fn two_user_auth() -> MultiAuthState {
     let mut tokens = HashMap::new();
@@ -51,6 +49,7 @@ fn two_user_auth() -> MultiAuthState {
         ALICE_TOKEN.to_string(),
         UserIdentity {
             user_id: ALICE_USER_ID.to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: Vec::new(),
         },
     );
@@ -58,6 +57,7 @@ fn two_user_auth() -> MultiAuthState {
         BOB_TOKEN.to_string(),
         UserIdentity {
             user_id: BOB_USER_ID.to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: vec!["shared".to_string()],
         },
     );
@@ -79,7 +79,10 @@ fn user_echo_app(auth: MultiAuthState) -> Router {
         .route("/api/whoami/scopes", get(echo_user_with_scopes))
         .route("/api/action", post(echo_user))
         .route("/api/chat/events", get(echo_user)) // SSE endpoint (allows query token)
-        .layer(middleware::from_fn_with_state(auth, auth_middleware))
+        .layer(middleware::from_fn_with_state(
+            ironclaw::channels::web::auth::CombinedAuthState::from(auth),
+            auth_middleware,
+        ))
 }
 
 // ===========================================================================
@@ -544,7 +547,6 @@ fn gateway_state_has_multi_tenant_fields() {
         prompt_queue: None,
         scheduler: None,
         owner_id: "fallback".to_string(),
-        default_sender_id: "fallback".to_string(),
         shutdown_tx: tokio::sync::RwLock::new(None),
         ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
         llm_provider: None,
@@ -558,10 +560,10 @@ fn gateway_state_has_multi_tenant_fields() {
         startup_time: std::time::Instant::now(),
         webhook_rate_limiter: RateLimiter::new(10, 60),
         active_config: Default::default(),
+        secrets_store: None,
     };
 
     assert_eq!(state.owner_id, "fallback");
-    assert_eq!(state.default_sender_id, "fallback");
     assert!(state.workspace_pool.is_none());
 }
 
@@ -592,6 +594,7 @@ async fn start_owner_scoped_sender_server() -> (
         OWNER_TOKEN.to_string(),
         UserIdentity {
             user_id: OWNER_SCOPE_ID.to_string(),
+            role: "admin".to_string(),
             workspace_read_scopes: Vec::new(),
         },
     );
@@ -599,6 +602,7 @@ async fn start_owner_scoped_sender_server() -> (
         BOB_TOKEN.to_string(),
         UserIdentity {
             user_id: BOB_USER_ID.to_string(),
+            role: "member".to_string(),
             workspace_read_scopes: Vec::new(),
         },
     );
@@ -618,7 +622,6 @@ async fn start_owner_scoped_sender_server() -> (
         prompt_queue: None,
         scheduler: None,
         owner_id: OWNER_SCOPE_ID.to_string(),
-        default_sender_id: GATEWAY_SENDER_ID.to_string(),
         shutdown_tx: tokio::sync::RwLock::new(None),
         ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
         llm_provider: None,
@@ -632,9 +635,10 @@ async fn start_owner_scoped_sender_server() -> (
         routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
         startup_time: std::time::Instant::now(),
         active_config: Default::default(),
+        secrets_store: None,
     });
 
-    let auth = MultiAuthState::multi(tokens);
+    let auth = MultiAuthState::multi(tokens).into();
     let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
     let bound = start_server(addr, state.clone(), auth)
         .await
@@ -769,7 +773,7 @@ async fn full_server_chat_send_rewrites_sender_only_for_owner_scope_rebind() {
         .expect("Timed out waiting for owner message")
         .expect("Agent channel closed");
     assert_eq!(owner_msg.user_id, OWNER_SCOPE_ID);
-    assert_eq!(owner_msg.sender_id, GATEWAY_SENDER_ID);
+    assert_eq!(owner_msg.sender_id, OWNER_SCOPE_ID);
     assert_eq!(owner_msg.content, "hello from owner");
 
     let other_resp = client
@@ -1003,7 +1007,6 @@ async fn start_multi_user_server_with_db() -> (
         prompt_queue: None,
         scheduler: None,
         owner_id: ALICE_USER_ID.to_string(),
-        default_sender_id: ALICE_USER_ID.to_string(),
         shutdown_tx: tokio::sync::RwLock::new(None),
         ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
         llm_provider: None,
@@ -1017,10 +1020,11 @@ async fn start_multi_user_server_with_db() -> (
         startup_time: std::time::Instant::now(),
         webhook_rate_limiter: RateLimiter::new(10, 60),
         active_config: Default::default(),
+        secrets_store: None,
     });
 
     let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
-    let bound = ironclaw::channels::web::server::start_server(addr, state.clone(), auth)
+    let bound = ironclaw::channels::web::server::start_server(addr, state.clone(), auth.into())
         .await
         .expect("Failed to start server with DB");
 

tests/openai_compat_integration.rs

@@ -205,7 +205,6 @@ async fn start_test_server_with_provider(
         prompt_queue: None,
         scheduler: None,
         owner_id: "test-user".to_string(),
-        default_sender_id: "test-user".to_string(),
         shutdown_tx: tokio::sync::RwLock::new(None),
         ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
         llm_provider: Some(llm_provider),
@@ -219,6 +218,7 @@ async fn start_test_server_with_provider(
         routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
         startup_time: std::time::Instant::now(),
         active_config: ironclaw::channels::web::server::ActiveConfigSnapshot::default(),
+        secrets_store: None,
     });
 
     let auth = ironclaw::channels::web::auth::MultiAuthState::single(
@@ -226,7 +226,7 @@ async fn start_test_server_with_provider(
         "test-user".to_string(),
     );
     let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
-    let bound_addr = start_server(addr, state.clone(), auth)
+    let bound_addr = start_server(addr, state.clone(), auth.into())
         .await
         .expect("Failed to start test server");
 
@@ -704,7 +704,6 @@ async fn test_no_llm_provider_returns_503() {
         prompt_queue: None,
         scheduler: None,
         owner_id: "test-user".to_string(),
-        default_sender_id: "test-user".to_string(),
         shutdown_tx: tokio::sync::RwLock::new(None),
         ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
         llm_provider: None, // No LLM!
@@ -718,6 +717,7 @@ async fn test_no_llm_provider_returns_503() {
         routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
         startup_time: std::time::Instant::now(),
         active_config: ironclaw::channels::web::server::ActiveConfigSnapshot::default(),
+        secrets_store: None,
     });
 
     let auth = ironclaw::channels::web::auth::MultiAuthState::single(
@@ -725,7 +725,7 @@ async fn test_no_llm_provider_returns_503() {
         "test-user".to_string(),
     );
     let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
-    let bound_addr = start_server(addr, state, auth).await.unwrap();
+    let bound_addr = start_server(addr, state, auth.into()).await.unwrap();
 
     let url = format!("http://{}/v1/chat/completions", bound_addr);
     let resp = client()
@@ -763,7 +763,7 @@ async fn test_chat_completions_body_too_large() {
             post(ironclaw::channels::web::openai_compat::chat_completions_handler),
         )
         .route_layer(middleware::from_fn_with_state(
-            auth_state,
+            ironclaw::channels::web::auth::CombinedAuthState::from(auth_state),
             ironclaw::channels::web::auth::auth_middleware,
         ))
         .layer(DefaultBodyLimit::max(10 * 1024 * 1024))

tests/support/gateway_workflow_harness.rs

@@ -227,7 +227,6 @@ impl GatewayWorkflowHarness {
             prompt_queue: None,
             scheduler: Some(scheduler_slot.clone()),
             owner_id: user_id.clone(),
-            default_sender_id: user_id.clone(),
             shutdown_tx: tokio::sync::RwLock::new(None),
             ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
             llm_provider: Some(Arc::clone(&components.llm)),
@@ -241,6 +240,7 @@ impl GatewayWorkflowHarness {
             routine_engine: Arc::clone(&routine_slot),
             startup_time: Instant::now(),
             active_config: ironclaw::channels::web::server::ActiveConfigSnapshot::default(),
+            secrets_store: None,
         });
 
         let mut agent = Agent::new(
@@ -299,7 +299,7 @@ impl GatewayWorkflowHarness {
         let addr = start_server(
             "127.0.0.1:0".parse().expect("valid localhost addr"),
             Arc::clone(&gateway_state),
-            auth,
+            auth.into(),
         )
         .await
         .expect("failed to start gateway server");

tests/ws_gateway_integration.rs

@@ -52,7 +52,6 @@ async fn start_test_server() -> (
         prompt_queue: None,
         scheduler: None,
         owner_id: "test-user".to_string(),
-        default_sender_id: "test-user".to_string(),
         shutdown_tx: tokio::sync::RwLock::new(None),
         ws_tracker: Some(Arc::new(WsConnectionTracker::new())),
         llm_provider: None,
@@ -66,6 +65,7 @@ async fn start_test_server() -> (
         routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
         startup_time: std::time::Instant::now(),
         active_config: ironclaw::channels::web::server::ActiveConfigSnapshot::default(),
+        secrets_store: None,
     });
 
     let auth = ironclaw::channels::web::auth::MultiAuthState::single(
@@ -73,7 +73,7 @@ async fn start_test_server() -> (
         "test-user".to_string(),
     );
     let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
-    let bound_addr = start_server(addr, state.clone(), auth)
+    let bound_addr = start_server(addr, state.clone(), auth.into())
         .await
         .expect("Failed to start test server");