1692 lines
94 KiB
Markdown
1692 lines
94 KiB
Markdown
# Fischer AgentKit — Centralized Auth & Token Persistence (Plan)
|
||
|
||
**Date:** 2026-06-20
|
||
**Status:** active
|
||
**Branch:** `feat/auth-server-token-persistence`（原 `feat/centralized-auth-token-persistence`）
|
||
**Type:** feat
|
||
**Origin:** [docs/brainstorms/2026-06-20-centralized-auth-token-persistence-requirements.md](docs/brainstorms/2026-06-20-centralized-auth-token-persistence-requirements.md)
|
||
|
||
> **2026-06-20 更新**：合并 AuthProvider 抽象层 scope（origin §5.5），新增 KTD-10、U1 `auth_provider` 字段、U3/U4 改造点、U11 实施单元、Phase 6、AE-10/AE-11。
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
Replace the current minimal JWT + localStorage auth with a production-grade scheme: server-side **session table** (track every login, enable forced revocation), **Tauri OS Keychain** storage for refresh tokens (encrypted at rest), **refresh token rotation** (defense against token leakage), **pre-emptive token refresh** (no 401 storms), a **three-state startup** (valid / invalid / error), and an **AuthProvider 抽象层** that decouples routes / admin API / session table from the concrete auth backend (Local today; OIDC / SAML / LDAP tomorrow via adapter). Goal: after first login, Tauri cold-start goes directly to the main app, no login page; admin can see/force-revoke any user's active sessions; password change instantly invalidates all other devices; future enterprise IdP integration requires no rewrite of the routing or admin layer.
|
||
|
||
---
|
||
|
||
## Problem Frame
|
||
|
||
The current auth flow has three structural gaps:
|
||
|
||
1. **Token at rest in plaintext** — `access_token`, `refresh_token`, and `user` are stored unencrypted in WebView localStorage (`~/Library/WebKit/.../LocalStorage/` on macOS). Any process with file access can read them.
|
||
2. **No revocation surface** — `user_sessions` table only stores a refresh-token hash with `revoked_at`. There is no device fingerprint, no IP, no "kick this session" admin endpoint, no "change password → kick everywhere" flow. Sessions outlive the user's intent.
|
||
3. **No rotation** — the same refresh token can be used for the full 7-day window. If leaked, the attacker has a week of access with no detection.
|
||
|
||
The user's primary stated need is "after I log in once, subsequent app opens should go straight to the main app." The current code attempts this via localStorage rehydration, but two failure modes break it: (a) refresh hits `_refreshFailed` and the auth store clears itself; (b) when the access token expires mid-session and refresh fails (server restart, network blip), the store clears and the user is bounced to `/login`. We need both stronger local persistence and server-side session awareness to make this experience reliable.
|
||
|
||
The secondary stated needs are **"集团统一管理"** (centralized enterprise management) and **"和集团的账号密码对接"** (eventual IdP integration). Without a session table and admin endpoints, an admin cannot: see who is logged in, force-logout a lost device, or ensure that a compromised employee is immediately removed from all devices. The session table is the same data model an IdP would feed. To keep the future IdP integration from requiring a routing / admin rewrite, the auth backend must be **pluggable behind an `AuthProvider` Protocol** (see KTD-10 and U11). Local today, OIDC tomorrow — without touching routes or admin code.
|
||
|
||
---
|
||
|
||
## Scope Boundaries
|
||
|
||
### In Scope
|
||
|
||
- New `auth_sessions` SQLAlchemy model + table + Alembic migration
|
||
- JWT payload extended with `sid` (session id) and `jti` (token id); session validation on every request
|
||
- Refresh token rotation on every `/auth/refresh` call; old token enters a 30s short-window denylist
|
||
- Refresh-token reuse detection → revoke **all** sessions for that user (defense against token theft)
|
||
- New endpoints: `GET /auth/whoami`, `GET /auth/sessions`, `DELETE /auth/sessions/{id}`, `POST /auth/logout-others`, `POST /auth/change-password`, `GET /admin/users/{id}/sessions`, `DELETE /admin/users/{id}/sessions/{sid}`
|
||
- Active session cap = 10 per user; login that would exceed the cap evicts the oldest non-current session
|
||
- "Remember me" login option: refresh TTL = 30 days (vs default 7 days)
|
||
- Tauri Rust commands: `store_refresh_token` / `load_refresh_token` / `clear_refresh_token` using the `keyring` crate (macOS Keychain / Windows Credential Manager / Linux Secret Service)
|
||
- Frontend `tauri-auth.ts` adapter with localStorage fallback when Keychain is unavailable
|
||
- Frontend auth-store: 3-state startup (`valid` / `invalid` / `error`), pre-emptive refresh when access expires in <2 min, no localStorage write of access token
|
||
- Frontend "Remember me" checkbox on `LoginView`
|
||
- Frontend "Active sessions" management UI in `SettingsView` (list current devices, kick others)
|
||
- Admin UI: see any user's active sessions, kick any session
|
||
- Backwards-compat for one minor version: old clients without `sid` claim still work via `user_sessions` table fallback
|
||
- **AuthProvider 抽象层** (`auth/providers/base.py` Protocol + `LocalAuthProvider` + `StubOIDCProvider`) — routes / admin / SessionService 通过 `Depends(get_auth_provider)` 拿到 provider；切换 IdP 不重写路由
|
||
- `auth_sessions` 表 `auth_provider` 字段记录登录来源（`local` / `oidc-stub` / 未来 `oidc-keycloak` / `saml` / `ldap`）
|
||
- 配置开关 `auth.provider: local | oidc-stub`（agentkit.yaml），未来加新 provider 只需新 adapter
|
||
|
||
### Out of Scope (deferred to follow-up work)
|
||
|
||
- Enterprise IdP / SSO (OIDC / SAML / LDAP / 飞书 / 钉钉 / 企微) — separate brainstorm
|
||
- 2FA / TOTP / WebAuthn / Passkey — separate brainstorm
|
||
- Multi-tenant / org isolation — separate brainstorm
|
||
- Password strength policy / password expiry / password history — separate IAM brainstorm
|
||
- Login failure lockout / sliding-window rate-limit — separate security brainstorm
|
||
- Email / SMS notifications for reuse detection — requires notification service
|
||
- Full audit log search / export — separate observability brainstorm
|
||
- Per-session device "trust" flag (e.g. "this Mac is trusted for 90 days") — defer until IdP work
|
||
|
||
### Resolved Decisions (locked in from the brainstorm)
|
||
|
||
| # | Question | Decision |
|
||
|---|----------|----------|
|
||
| 1 | Remember me TTL | 30 days (vs default 7 days) |
|
||
| 2 | Active session cap | 10 per user, evict oldest non-current on overflow |
|
||
| 3 | Tauri Keychain unavailable behavior | Silently fall back to localStorage, log warning |
|
||
|
||
---
|
||
|
||
## Requirements (carried from origin)
|
||
|
||
The plan must satisfy all of the following origin IDs (see [requirements doc](docs/brainstorms/2026-06-20-centralized-auth-token-persistence-requirements.md)):
|
||
|
||
- **F1** First login → cold-start app goes directly to main UI, never shows login
|
||
- **F2** "Remember me" toggle: 7d / 30d refresh TTL
|
||
- **F3** Tauri: refresh token stored in OS Keychain, never on localStorage disk
|
||
- **F4** Web: refresh token in localStorage (degraded security, accepted)
|
||
- **F5** Refresh token rotation: every `/auth/refresh` invalidates the old token
|
||
- **F6** Server: every login recorded with device/IP/time
|
||
- **F7** Admin: see any user's active sessions
|
||
- **F8** Admin / self: kick any session
|
||
- **F9** Password change: kick all other sessions
|
||
- **F10** Pre-emptive refresh when access expires in <2 min
|
||
- **F11** Startup distinguishes `valid` / `invalid` / `error`
|
||
- **F12** Multiple Tauri / Web clients can log in the same user simultaneously (independent sessions)
|
||
- **F13** AuthProvider 可插拔（`auth.provider` 配置切换 local ↔ oidc-stub，路由/Admin/Session 表零修改）
|
||
- **F14** admin 端点与认证后端解耦（未来切 IdP，admin 看 session 列表 / 踢人功能不变）
|
||
- **F15** 审计日志记录 `auth_provider` 字段（登录来源可溯源）
|
||
- **N1** Token validation P99 < 5ms (Redis cache for session metadata)
|
||
- **N5** All auth code has unit + integration tests
|
||
- **N6** Backwards-compat for old clients (1 minor version)
|
||
|
||
---
|
||
|
||
## Key Technical Decisions
|
||
|
||
### KTD-1: `auth_sessions` table (new) vs extending `user_sessions` (existing)
|
||
|
||
**Decision**: Create a new `auth_sessions` table; deprecate `user_sessions` over 1 minor version.
|
||
|
||
**Rationale**: `user_sessions` only stores `refresh_token_hash` + `revoked_at` (3 fields). The new design needs `device_fingerprint`, `device_label`, `ip`, `user_agent`, `last_active_at`, `expires_at`, `revoked_reason`, `previous_session_id`. Adding 7 columns to an existing table breaks its existing semantics (the table is also referenced in production hardening tests). Clean break with migration is safer than schema bloat.
|
||
|
||
**Trade-off**: Two-table coexistence during the deprecation window. Mitigated by: keep `user_sessions` reads working for clients without `sid` claim (N6).
|
||
|
||
### KTD-2: Session validation on every request (not just refresh)
|
||
|
||
**Decision**: `get_current_user` dependency reads `sid` from JWT, queries `auth_sessions` table (with Redis cache, 60s TTL) to confirm `revoked=False` and `expires_at > now`.
|
||
|
||
**Rationale**: Without this, a kicked-out user keeps their access token for up to 15 min (access TTL). With it, the kicked session is dead on the next request. The cost is +1 DB/cache lookup per request; cache makes this sub-ms.
|
||
|
||
**Trade-off**: One cache miss per request adds ~5ms; with the 60s cache the actual DB query rate is ~1/min/active-session.
|
||
|
||
### KTD-3: Refresh token rotation + 30s denylist
|
||
|
||
**Decision**: Every successful `/auth/refresh` issues a new refresh token. The old token's hash is added to an in-memory + Redis denylist for 30 seconds. If the old token is reused within that window → `TokenReuseDetected` → revoke ALL sessions for that user.
|
||
|
||
**Rationale**: Industry standard (Auth0, Okta, AWS). Closes the window where an attacker who captured the old token can still use it after the legitimate user has refreshed.
|
||
|
||
**Trade-off**: The 30s window is a small UX cost (concurrent refresh calls from the same client during retry) but acceptable; legitimate retries complete in <1s and don't hit the window.
|
||
|
||
### KTD-4: Tauri Keychain via `keyring` crate (not `tauri-plugin-stronghold`)
|
||
|
||
**Decision**: Use the `keyring` crate directly. It provides unified API across macOS Keychain, Windows Credential Manager, and Linux Secret Service with a single dependency.
|
||
|
||
**Rationale**: `tauri-plugin-stronghold` is a Tauri-team plugin but the v2 ecosystem is still maturing and the docs lag. `keyring` is the de-facto Rust standard for OS credential storage, used by `cargo`, `git-credential-manager`, and others. Smaller surface, fewer moving parts.
|
||
|
||
**Trade-off**: We write 3 small Tauri commands (`store_refresh_token` / `load_refresh_token` / `clear_refresh_token`) instead of using a plugin's auto-generated bindings. ~50 lines of Rust.
|
||
|
||
### KTD-5: Access token in memory only (not persisted)
|
||
|
||
**Decision**: Access token lives only in the auth store's reactive `ref<string | null>`. Never written to localStorage or Keychain.
|
||
|
||
**Rationale**: Access tokens are short-lived (15 min). The cost of losing one (re-auth) is low; the security cost of persisting them (broader attack surface) is high. Refresh token is the only thing that needs durable storage.
|
||
|
||
**Trade-off**: App reload requires one refresh round-trip to get a new access token. Mitigated by the pre-emptive refresh + 3-state startup: by the time the app needs to call an API, the access token is already fresh.
|
||
|
||
### KTD-6: Redis cache for session metadata (not just in-memory)
|
||
|
||
**Decision**: Use Redis (when available) to cache `auth_sessions` rows by `sid`. Fallback to in-process LRU (size=1024) when Redis is unavailable.
|
||
|
||
**Rationale**: The Tauri sidecar may run without Redis (zero-config dev mode). In-process LRU gives the same hit rate for single-process deployments. When Redis IS available (server deployment, multi-instance), it's the right cross-process answer.
|
||
|
||
**Trade-off**: Two code paths. Mitigated by a small `SessionCache` interface with two impls.
|
||
|
||
### KTD-7: Session cap eviction strategy = LRU (oldest non-current)
|
||
|
||
**Decision**: When login would create the 11th session for a user, the oldest non-current session is `revoked` (with `revoked_reason='session_cap_eviction'`) before the new one is created.
|
||
|
||
**Rationale**: LRU is intuitive ("the device I haven't used in a month should be the first to go"). Kicking "current" is wrong because the user is actively logging in.
|
||
|
||
**Trade-off**: None meaningful. Cap=10 is generous; the eviction is invisible to all but the user on the kicked device.
|
||
|
||
### KTD-8: Pre-emptive refresh in `api/base.ts` interceptor (not in Pinia getter)
|
||
|
||
**Decision**: A request interceptor in `BaseApiClient` checks `shouldRefresh()` (access exp <2 min) BEFORE sending, and awaits `silentRefresh()` if needed.
|
||
|
||
**Rationale**: An interceptor guarantees the check runs for every request. A Pinia getter would only fire on `accessToken` access, which is not all requests (e.g. background fetches that don't read the getter).
|
||
|
||
**Trade-off**: One async function call before each request when expiring; negligible.
|
||
|
||
### KTD-9: Backwards-compat shim for old clients
|
||
|
||
**Decision**: `dependencies.py:get_current_user` accepts JWTs with or without `sid` claim. Missing `sid` → fall back to `user_sessions.refresh_token_hash` validation. This path is logged and gated to one minor version.
|
||
|
||
**Rationale**: Avoids breaking in-flight clients. Lets us roll out gradually.
|
||
|
||
**Trade-off**: Two validation paths in `get_current_user`. Mitigated by extracting the session-lookup into a helper that both paths share.
|
||
|
||
### KTD-10: AuthProvider 抽象层（为未来 IdP 对接留扩展点）
|
||
|
||
**Decision**: 鉴权逻辑走 `auth/providers/base.py:AuthProvider` Protocol（`name` / `authenticate` / `get_user_by_id` / `sync_user_attributes` / `revoke_user`），路由层用 `Depends(get_auth_provider)` 注入。当前默认 `LocalAuthProvider`（封装 SQLite + bcrypt），未来 `OidcAuthProvider` 接管时**路由 / admin / Session 表零修改**。`StubOIDCProvider` 作为占位（`raise NotImplementedError`），用于未来接口契约验证。
|
||
|
||
**Rationale**: 用户明确"未来要和集团账号密码对接"（OIDC / SAML / LDAP / 飞书 / 钉钉 / 企微）。如果现在把"用户存在哪里 / 密码怎么校验"写死在 routes/admin 里，未来切 IdP 必须重写所有路由层 + admin 端点。提前抽象可以让未来 IdP 集成只需新增一个 adapter（~300-500 行），不触及现有 routes / admin / SessionService。`auth_sessions` 表加 `auth_provider` 字段记录登录来源，审计可溯源。
|
||
|
||
**Trade-off**:
|
||
- 多 1 个抽象层（`auth/providers/base.py` Protocol）+ 1 个 DI 工厂（`get_auth_provider`）+ 1 个 StubOIDCProvider 占位
|
||
- 收益：未来 IdP 集成不重写路由层 + admin API；admin 踢人 / 看 session 列表跨 provider 一致
|
||
|
||
**Alternatives considered**:
|
||
- ❌ 不预留扩展点，只做当下 LocalAuthProvider：未来切 IdP 必须重写 routes + admin + SessionService
|
||
- ❌ 直接实现 OIDC：拉长本迭代 2-3 倍
|
||
|
||
---
|
||
|
||
## High-Level Technical Design
|
||
|
||
### Component Map
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ Tauri Desktop (macOS / Windows / Linux) │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ WebView (Vue 3 frontend) │ │
|
||
│ │ ┌────────────┐ ┌──────────────┐ ┌────────────────┐ │ │
|
||
│ │ │ auth store │──│ api/base.ts │──│ Pinia + Router │ │ │
|
||
│ │ │ (memory) │ │ interceptor │ │ │ │ │
|
||
│ │ └────────────┘ └──────────────┘ └────────────────┘ │ │
|
||
│ │ │ │ │ │
|
||
│ │ │ │ silentRefresh │ │
|
||
│ │ │ ▼ │ │
|
||
│ │ │ ┌──────────────────┐ │ │
|
||
│ │ │ │ tauri-auth.ts │ invoke() │ │
|
||
│ │ │ └──────────────────┘ │ │ │
|
||
│ │ │ localStorage fallback ▼ │ │
|
||
│ │ │ ┌──────────────────────┐ │ │
|
||
│ │ └─────────────────▶│ src-tauri/src/auth.rs│ │ │
|
||
│ │ │ keyring::Entry │ │ │
|
||
│ │ └──────────────────────┘ │ │
|
||
│ │ │ │ │
|
||
│ └───────────────────────────────────────┼────────────────┘ │
|
||
│ │ HTTP │
|
||
│ ▼ │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ FastAPI server (Python sidecar) │ │
|
||
│ │ ┌────────────────────────┐ ┌──────────────────────┐ │ │
|
||
│ │ │ routes/auth.py │──▶│ auth/session.py │ │ │
|
||
│ │ │ + admin routes │ │ - create / rotate │ │ │
|
||
│ │ │ Depends(get_auth_ │ │ - revoke / kick │ │ │
|
||
│ │ │ provider) ─────┼──▶│ - reuse detection │ │ │
|
||
│ │ └────────────────────────┘ └──────────────────────┘ │ │
|
||
│ │ │ │ │ │
|
||
│ │ ▼ ▼ │ │
|
||
│ │ ┌────────────────────────┐ ┌──────────────────────┐ │ │
|
||
│ │ │ auth/providers/ │ │ auth/models.py │ │ │
|
||
│ │ │ - base.py (Protocol) │ │ AuthSessionModel │ │ │
|
||
│ │ │ - local.py (Local) │ │ + auth_provider col │ │ │
|
||
│ │ │ - oidc_stub.py (stub) │ └──────────────────────┘ │ │
|
||
│ │ │ get_auth_provider() DI │ │ │
|
||
│ │ └────────────────────────┘ │ │
|
||
│ │ │ │ │
|
||
│ │ ▼ │ │
|
||
│ │ ┌─────────────────────────────────────────────┐ │ │
|
||
│ │ │ auth/cache.py (Redis or in-process LRU) │ │ │
|
||
│ │ └─────────────────────────────────────────────┘ │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌──────────────────────────┐ │
|
||
│ │ data/auth.db (SQLite) │ │
|
||
│ │ + auth_sessions table │ │
|
||
│ └──────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### State Machine — Client Auth
|
||
|
||
```
|
||
┌──────────────┐
|
||
app start │ │ valid refresh
|
||
────────────▶│ STARTUP │────────────────────▶ READY
|
||
│ │ │ │
|
||
└──────────────┘ │ │
|
||
│ │ │ │ │
|
||
invalid ────┘ │ └──── network err │ │
|
||
▼ │ │
|
||
┌──────────────┐ │ │
|
||
│ ERROR │ retry ──────┐ │ │
|
||
│ "刷新" │ │ │ │
|
||
└──────────────┘ │ │ │
|
||
▼ │ │ │
|
||
┌──────────────┐ │ │ │
|
||
│ INVALID │ retry ─────┤ │ │
|
||
│ "请重登" │ │ │ │
|
||
└──────────────┘ │ │ │
|
||
│ │ │
|
||
┌─────────────────────────┘ │ │
|
||
│ │ │
|
||
│ 401 in flight │ │
|
||
│ ◀──────────────────────────────────┘ │
|
||
│ │
|
||
▼ │
|
||
┌──────────────┐ │
|
||
│ silentRefresh│ │
|
||
└──────────────┘ │
|
||
│ │
|
||
ok ◀──┴──▶ fail → back to STARTUP / INVALID
|
||
```
|
||
|
||
### State Machine — Server Session
|
||
|
||
```
|
||
login
|
||
│
|
||
▼
|
||
┌────────────┐
|
||
│ CREATED │ sid in JWT
|
||
│ active │
|
||
└────────────┘
|
||
│ │ │
|
||
refresh ok ─────┘ │ └──── logout → REVOKED (user)
|
||
(rotated) │
|
||
└── admin / password change / reuse detected
|
||
→ REVOKED (system)
|
||
```
|
||
|
||
### Sequence — Cold Start (Tauri)
|
||
|
||
```
|
||
Window opens
|
||
│
|
||
▼
|
||
App.vue mounted
|
||
│
|
||
▼
|
||
bootstrapBackend()
|
||
│ start_backend (sidecar)
|
||
│ health check
|
||
│
|
||
▼
|
||
authStore.startupCheck()
|
||
│
|
||
├── 1. tauriAuthStorage.getRefreshToken()
|
||
│ Keychain (Tauri) → localStorage (Web fallback)
|
||
│
|
||
├── 2. GET /api/v1/auth/whoami (Authorization: Bearer <refresh>)
|
||
│ (the access token is gone, so we attach the refresh token;
|
||
│ the server uses a separate "whoami" code path that accepts
|
||
│ either type)
|
||
│
|
||
├── 3. response handling
|
||
│ 200 → { access_token, user } → state = VALID → /agent
|
||
│ 401 → state = INVALID → /login (with "会话已过期")
|
||
│ network err → state = ERROR → /login (with "无法连接")
|
||
│
|
||
▼
|
||
Router beforeEach
|
||
│ state = VALID → next()
|
||
│ state != VALID → next('/login')
|
||
```
|
||
|
||
### Data Model — `auth_sessions` Table
|
||
|
||
```mermaid
|
||
erDiagram
|
||
auth_sessions {
|
||
TEXT id PK "uuid"
|
||
TEXT user_id FK
|
||
TEXT refresh_token_hash
|
||
TEXT device_fingerprint
|
||
TEXT device_label
|
||
TEXT ip
|
||
TEXT user_agent
|
||
TEXT created_at
|
||
TEXT last_active_at
|
||
TEXT expires_at
|
||
INTEGER revoked
|
||
TEXT revoked_reason
|
||
TEXT previous_session_id
|
||
}
|
||
users {
|
||
TEXT id PK
|
||
TEXT username
|
||
TEXT password_hash
|
||
...
|
||
}
|
||
auth_sessions }o--|| users : "user_id"
|
||
```
|
||
|
||
### Sequence — Refresh Token Rotation + Reuse Detection
|
||
|
||
```
|
||
Client Server
|
||
│ │
|
||
│ POST /auth/refresh │
|
||
│ { refresh_token: "old" } │
|
||
│ ───────────────────────────▶ │
|
||
│ │ decode old → sid
|
||
│ │ lookup auth_sessions[sid]
|
||
│ │ hash(old) == session.refresh_token_hash? NO
|
||
│ │ → denylist check: hash(old) in denylist?
|
||
│ │ YES → REUSE DETECTED
|
||
│ │ → revoke ALL sessions for this user
|
||
│ │ → audit log "reuse_detected"
|
||
│ │ ← 401 { error: "token_reuse_detected" }
|
||
│ client clears state, │
|
||
│ routes to /login │
|
||
│ │
|
||
│ -- legit refresh -- │
|
||
│ POST /auth/refresh │
|
||
│ { refresh_token: "valid" } │
|
||
│ ───────────────────────────▶ │
|
||
│ │ hash(valid) == session.refresh_token_hash? YES
|
||
│ │ rotate: session.refresh_token_hash = hash(new)
|
||
│ │ add hash(old) to denylist (30s)
|
||
│ │ issue new access + new refresh
|
||
│ │ ← 200 { access_token, refresh_token }
|
||
│ store new refresh in │
|
||
│ Keychain, access in memory │
|
||
```
|
||
|
||
---
|
||
|
||
## Implementation Units
|
||
|
||
### U1. Schema: AuthSessionModel + extended bootstrap + backfill
|
||
|
||
**Goal**: Add the `auth_sessions` table with all required fields and indexes, AND backfill existing `user_sessions` rows on first startup.
|
||
|
||
**Requirements**: F6, F15, N5, N6 (the table backs every session-aware endpoint; backfill prevents forced re-login; `auth_provider` field enables future IdP audit traceability).
|
||
|
||
**Dependencies**: None.
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/auth/models.py` — add `AuthSessionModel` (SQLAlchemy 2 typed) + extend `_SCHEMA_SQL` for direct aiosqlite init + add `_SCHEMA_VERSION = 2` constant + extend `init_auth_db()` to run the backfill
|
||
- `tests/unit/auth/test_models.py` — model serialization + index smoke + backfill tests
|
||
|
||
**Approach (schema)**:
|
||
- Use UUID strings as PK (matches existing `users.id` style in this codebase)
|
||
- `device_info` is a JSON string (reuse pattern from `UserSessionModel.device_info`)
|
||
- `expires_at` is ISO-8601 string (matches `UserModel.last_login_at`)
|
||
- `revoked` is INTEGER (0/1) for SQLite compatibility
|
||
- Add the new `CREATE TABLE auth_sessions` block to `_SCHEMA_SQL` (line 234-242 is the current `user_sessions` block; append after it) with these indexes:
|
||
- `idx_auth_sessions_user_id_active` on `(user_id, revoked, expires_at)` — supports the cap-count query and the list-active query
|
||
- `idx_auth_sessions_expires_at` on `(expires_at)` — supports cleanup sweeps
|
||
- `idx_auth_sessions_refresh_token_hash` on `(refresh_token_hash)` — unique
|
||
- `idx_auth_sessions_auth_provider` on `(auth_provider)` — supports future IdP "list sessions by provider" query
|
||
- **Add `auth_provider` column** (NEW per KTD-10): `TEXT NOT NULL DEFAULT 'local'` — records which provider created the session. Values: `local` (current) / `oidc-stub` (future stub) / `oidc-keycloak` / `saml` / `ldap` (future real adapters). Backfilled rows get `'local'` via the default.
|
||
- Bump `_SCHEMA_VERSION = 2` (currently implicit; the existing `init_auth_db` is idempotent via `CREATE TABLE IF NOT EXISTS` so version is mostly for the backfill gate)
|
||
|
||
**Approach (backfill) — critical, was missing from the original plan**:
|
||
The current `routes/auth.py:201-213` writes to `user_sessions` on login. After the new schema lands, the new `SessionService.create_session` writes to `auth_sessions` instead. To prevent forcing every existing user to re-login on the deploy, `init_auth_db()` runs a **one-time backfill** on startup:
|
||
|
||
```python
|
||
async def _backfill_user_sessions(db: aiosqlite.Connection) -> int:
|
||
"""One-time backfill from user_sessions to auth_sessions.
|
||
|
||
Runs only when auth_sessions is empty AND user_sessions has rows.
|
||
Idempotent: subsequent restarts are no-ops.
|
||
"""
|
||
cursor = await db.execute("SELECT COUNT(*) FROM auth_sessions")
|
||
(count,) = await cursor.fetchone()
|
||
if count > 0:
|
||
return 0 # already backfilled
|
||
|
||
cursor = await db.execute(
|
||
"SELECT id, user_id, refresh_token_hash, device_info, created_at, expires_at, revoked_at "
|
||
"FROM user_sessions WHERE revoked_at IS NULL"
|
||
)
|
||
rows = await cursor.fetchall()
|
||
backfilled = 0
|
||
for row in rows:
|
||
device_info = json.loads(row["device_info"]) if row["device_info"] else {}
|
||
# Use existing user_sessions.id as the auth_sessions.id so that
|
||
# legacy clients holding the old refresh_token_hash still match
|
||
# a row in the new table (this is what the back-compat path in
|
||
# U10 relies on).
|
||
await db.execute(
|
||
"INSERT OR IGNORE INTO auth_sessions "
|
||
"(id, user_id, refresh_token_hash, device_fingerprint, device_label, "
|
||
" ip, user_agent, created_at, last_active_at, expires_at, revoked, revoked_reason) "
|
||
"VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
|
||
(
|
||
row["id"], # reuse legacy id for back-compat
|
||
row["user_id"],
|
||
row["refresh_token_hash"],
|
||
device_info.get("fingerprint", "unknown"),
|
||
device_info.get("label", "Unknown device"),
|
||
device_info.get("ip", ""),
|
||
device_info.get("user_agent", ""),
|
||
row["created_at"],
|
||
row["created_at"], # last_active_at defaults to created_at
|
||
row["expires_at"],
|
||
0, # not revoked (already filtered)
|
||
None,
|
||
),
|
||
)
|
||
backfilled += 1
|
||
if backfilled:
|
||
logger.info(f"Backfilled {backfilled} user_sessions rows to auth_sessions")
|
||
return backfilled
|
||
```
|
||
|
||
**Approach (idempotency)**:
|
||
- The `INSERT OR IGNORE` on `auth_sessions.id PK` makes the backfill safe to re-run
|
||
- The `count > 0` early-exit means after the first backfill, subsequent startups are < 1ms
|
||
|
||
**Approach (rolled-back risk)**:
|
||
- The backfill does NOT delete `user_sessions` rows. They are kept for 1 minor version as the legacy read path. U10's Phase 5 cleanup drops the table.
|
||
|
||
**Test scenarios** (test_models.py):
|
||
- Create session, query by `sid`, find it
|
||
- Create 11 sessions for one user, count = 11 (cap check is in U3)
|
||
- Query `WHERE user_id=? AND revoked=0 AND expires_at > now` returns active sessions
|
||
- Index `(user_id, revoked, expires_at)` is present (verify via `PRAGMA index_list`)
|
||
- Index `idx_auth_sessions_auth_provider` is present
|
||
- **`auth_provider` column** tests (NEW per KTD-10):
|
||
- Default value is `'local'` when column is omitted from INSERT
|
||
- `WHERE auth_provider = 'local'` returns only local-created sessions
|
||
- `WHERE auth_provider = 'oidc-stub'` returns zero rows in current code
|
||
- **Backfill tests** (NEW):
|
||
- `init_auth_db` on a DB with `user_sessions` rows but empty `auth_sessions` → backfills all non-revoked rows
|
||
- `init_auth_db` on a DB with existing `auth_sessions` rows → does NOT re-backfill (idempotent)
|
||
- Backfilled rows have the original `user_sessions.id` as their `auth_sessions.id`
|
||
- Backfilled rows have `revoked=0`
|
||
- Backfilled rows have their `expires_at` preserved
|
||
- Backfill does NOT touch `user_sessions` rows that are already revoked (`revoked_at IS NOT NULL`)
|
||
|
||
**Verification**: `pytest tests/unit/auth/test_models.py -v` passes; `init_auth_db` runs cleanly on a copy of prod DB with the existing `user_sessions` table; backfill log line appears exactly once per fresh DB.
|
||
|
||
**Note on Alembic**: This codebase does **not** use Alembic. There is no `alembic.ini`, no `migrations/` directory, and no `alembic` dependency in `pyproject.toml`. The auth DB schema is managed via the `_SCHEMA_SQL` constant + `init_auth_db()` pattern (see `auth/models.py:202-333`). This U1 unit aligns with that pattern; the original plan's Alembic reference was incorrect.
|
||
|
||
---
|
||
|
||
### U2. JWT utils: sid + jti claims, dual decode path
|
||
|
||
**Goal**: Add `sid` and `jti` to issued JWTs; teach `verify_token` to read both old and new claim shapes.
|
||
|
||
**Requirements**: F5, F12, N6 (rotation + multi-client + backwards compat).
|
||
|
||
**Dependencies**: U1 (the `sid` references a row in `auth_sessions`).
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/auth/jwt_utils.py` — `create_token_pair(...)` now takes `session_id: str`; `verify_token(...)` returns decoded payload including `sid` + `jti`; back-compat: missing `sid` is logged at DEBUG and accepted (caller decides what to do)
|
||
- `src/agentkit/server/auth/denylist.py` — new module: `RecentlyRevokedTokens` class backed by in-memory `OrderedDict` + Redis pub/sub for cross-process; `add(token_hash, ttl=30)`, `contains(token_hash) -> bool`
|
||
- `tests/unit/auth/test_jwt_utils.py` — extend existing tests: round-trip with `sid`, decode legacy token, decode tampered token
|
||
|
||
**Approach**:
|
||
- `create_token_pair(user_id, session_id, ttl_pair)` — `access` payload: `{sub, sid, jti, type, exp, iat}`; `refresh` payload: same minus `jti` (refresh tokens are long-lived; jti would be regenerated on every rotation, which is wasteful)
|
||
- `verify_token(token, expected_type)` — return full payload dict; legacy payload (no `sid`) is preserved as-is, callers branch on `'sid' in payload`
|
||
- `RecentlyRevokedTokens` — single-process `OrderedDict` keyed by SHA-256 hash, max 10k entries; `contains` is O(1); `add` evicts oldest if at capacity
|
||
- Redis adapter: `SADD` + `EXPIRE`; `SISMEMBER` for check; the in-process impl is the fallback when Redis is unavailable
|
||
|
||
**Test scenarios**:
|
||
- `create_token_pair(...)` produces tokens with `sid` and `jti` (access only)
|
||
- `verify_token` on a token without `sid` returns the payload unchanged (caller must handle)
|
||
- `verify_token` on an expired token raises `ExpiredSignatureError`
|
||
- `RecentlyRevokedTokens.add(hash, ttl)` + `contains(hash)` returns True within 30s, False after
|
||
- `RecentlyRevokedTokens` with 10001 entries evicts the oldest (capacity test)
|
||
- Redis adapter mock: `SADD` + `SISMEMBER` + `EXPIRE` called with correct args
|
||
|
||
**Verification**: `pytest tests/unit/auth/test_jwt_utils.py -v` passes; manual `curl` round-trip works against a running dev server.
|
||
|
||
---
|
||
|
||
### U3. Session service: CRUD + rotation + reuse detection
|
||
|
||
**Goal**: Centralize all session operations behind a `SessionService` class so routes don't duplicate the logic.
|
||
|
||
**Requirements**: F5, F6, F8, F9, F11, F13, F15 (rotation, recording, kick, password change, three-state validation, provider-pluggability, audit field).
|
||
|
||
**Dependencies**: U1 (model), U2 (denylist).
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/auth/session.py` — new module: `SessionService` class
|
||
- `src/agentkit/server/auth/cache.py` — new module: `SessionCache` interface + `RedisSessionCache` + `InProcessLRUSessionCache` impls
|
||
- `tests/unit/auth/test_session.py` — full service test suite
|
||
|
||
**Approach (SessionService methods)**:
|
||
- `async create_session(user_id, device_fingerprint, device_label, ip, user_agent, remember_me: bool, auth_provider: str = "local") -> AuthSessionModel`
|
||
- **Cap check first**: count active sessions for user; if ≥10, mark oldest non-current as `revoked` with `revoked_reason='session_cap_eviction'`
|
||
- Generate new `sid` (uuid4), `jti` (uuid4)
|
||
- Compute `expires_at` based on `remember_me` (30d vs 7d)
|
||
- **Store `auth_provider` from caller** (U4 passes `provider.name`); enables F15 audit traceability
|
||
- Insert row, return model
|
||
- `async get_active_session(sid: str) -> AuthSessionModel | None`
|
||
- First check `SessionCache.get(sid)`; on miss, query DB, write to cache (60s TTL)
|
||
- Return None if `revoked=True` or `expires_at < now`
|
||
- `async rotate_refresh(old_refresh_token: str) -> tuple[AuthSessionModel, TokenPair]`
|
||
- Decode `old_refresh_token`; get `sid`; lookup session
|
||
- **Reuse detection**: compare `sha256(old_refresh_token)` against `session.refresh_token_hash`. If different, this is a reuse → call `revoke_all_for_user(user_id, reason='reuse_detected')` + raise `TokenReuseDetected`
|
||
- Also check `RecentlyRevokedTokens.contains(sha256(old_refresh_token))` — if yes, same handling
|
||
- On legitimate use: generate new `refresh_token`, update `session.refresh_token_hash` = `sha256(new)`, `session.last_active_at` = now, `session.expires_at` = now + ttl, `session.previous_session_id` = old sid (audit), `auth_provider` **preserved** (rotation doesn't change provider)
|
||
- Add `sha256(old_refresh_token)` to denylist for 30s
|
||
- Issue new access + refresh JWTs (call into jwt_utils)
|
||
- Invalidate cache entry for this sid
|
||
- `async revoke_session(sid: str, reason: str) -> None`
|
||
- Mark `revoked=True`, `revoked_reason=reason`; invalidate cache
|
||
- `async revoke_all_for_user(user_id: str, except_sid: str | None, reason: str) -> int`
|
||
- Bulk update; returns count of revoked sessions
|
||
- `async list_active_for_user(user_id: str) -> list[AuthSessionModel]`
|
||
- `async list_all_for_admin(user_id: str) -> list[AuthSessionModel]` (admin endpoint)
|
||
- `async list_active_by_provider(auth_provider: str) -> list[AuthSessionModel]` (NEW per KTD-10) — supports future "show me all OIDC sessions" admin view
|
||
|
||
**Approach (SessionCache)**:
|
||
```python
|
||
class SessionCache(Protocol):
|
||
async def get(self, sid: str) -> AuthSessionModel | None: ...
|
||
async def set(self, sid: str, session: AuthSessionModel, ttl: int = 60) -> None: ...
|
||
async def invalidate(self, sid: str) -> None: ...
|
||
```
|
||
- `InProcessLRUSessionCache`: `OrderedDict[sid, (session, expires_at)]`; cap=1024; lazy eviction on get
|
||
- `RedisSessionCache`: `GET` / `SETEX` / `DEL`; pickle the model for storage
|
||
|
||
**Test scenarios** (test_session.py):
|
||
- `create_session` inserts a row with all fields populated
|
||
- `create_session` with remember_me=True sets expires_at 30d out, else 7d
|
||
- `create_session` for a user with 10 active sessions evicts the oldest non-current one
|
||
- `create_session` for a user with 10 active sessions, the new login is one of them, the evicted one is the OLDEST non-new
|
||
- **`create_session` with `auth_provider='oidc-stub'`** stores that value in the row (NEW per KTD-10)
|
||
- `get_active_session` returns the row when valid
|
||
- `get_active_session` returns None when `revoked=True`
|
||
- `get_active_session` returns None when `expires_at < now`
|
||
- `get_active_session` second call within 60s hits cache (spy on DB call count)
|
||
- `rotate_refresh` with the CURRENT token returns new pair
|
||
- `rotate_refresh` preserves the original `auth_provider` value (NEW per KTD-10)
|
||
- `rotate_refresh` with a REUSED old token (different hash) → `TokenReuseDetected` raised + ALL sessions for user revoked
|
||
- `rotate_refresh` with a token in the denylist → same handling
|
||
- `rotate_refresh` updates `previous_session_id` to the old sid
|
||
- `revoke_session` sets `revoked=True`, `revoked_reason`, invalidates cache
|
||
- `revoke_all_for_user` except_sid=None revokes everything
|
||
- `revoke_all_for_user` except_sid=<current> keeps the current session
|
||
- `list_active_for_user` returns only `revoked=False AND expires_at > now`
|
||
- `list_all_for_admin` returns all rows including revoked (for audit)
|
||
- `list_active_by_provider('local')` returns only local sessions; `('oidc-stub')` returns empty in current code (NEW per KTD-10)
|
||
|
||
**Verification**: All unit tests pass; `pytest tests/unit/auth/test_session.py -v` shows 100% line coverage of `session.py`.
|
||
|
||
---
|
||
|
||
### U4. Routes: new auth + admin endpoints
|
||
|
||
**Goal**: Expose all session operations as HTTP endpoints.
|
||
|
||
**Requirements**: F1, F2, F5, F6, F7, F8, F9, F10, F11, F13, F14, F15.
|
||
|
||
**Dependencies**: U3 (the service), **U11 (AuthProvider 抽象层 — must land first or alongside)**.
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/routes/auth.py` — extend `LoginRequest` with `remember_me: bool = False`; add `WhoamiResponse`, `SessionInfoResponse`; add new endpoints; **DI 注入 `AuthProvider` 通过 `Depends(get_auth_provider)`**（KTD-10）
|
||
- `src/agentkit/server/routes/admin.py` — new module: admin session management endpoints (or extend existing admin module); **调用 `provider.revoke_user(user_id)` 而不是直接改 users 表**（KTD-10）
|
||
- `src/agentkit/server/dependencies.py` — `get_current_user` extension to look up session via sid; back-compat fallback for old tokens
|
||
- `src/agentkit/server/auth/password.py` — extend with `change_password(user_id, new_password)` that revokes all other sessions
|
||
- `tests/integration/auth/test_auth_routes.py` — full endpoint suite; **追加 provider mock 注入测试**（KTD-10）
|
||
- `tests/integration/auth/test_admin_routes.py` — admin endpoints
|
||
|
||
**Approach (new endpoints)**:
|
||
|
||
| Method | Path | Body / Query | Auth | Behavior |
|
||
|--------|------|--------------|------|----------|
|
||
| POST | `/auth/login` | `{username, password, remember_me?}` | none | **`provider.authenticate(username, password)`** → `SessionService.create_session(auth_provider=provider.name)` → return `TokenResponse` |
|
||
| POST | `/auth/refresh` | `{refresh_token}` | refresh | `SessionService.rotate_refresh` → return new `TokenResponse`; on `TokenReuseDetected` → 401 `{error: "token_reuse_detected"}` |
|
||
| POST | `/auth/logout` | `{refresh_token}` | access (optional) | `revoke_session(sid, reason='user_terminated')` |
|
||
| GET | `/auth/whoami` | — | access OR refresh | Returns `{user, session: {sid, device_label, ip, auth_provider, created_at, last_active_at, expires_at}}`. Accepts refresh token to support cold-start where access is gone. |
|
||
| GET | `/auth/sessions` | — | access | List current user's active sessions (each annotated with `auth_provider`) |
|
||
| DELETE | `/auth/sessions/{sid}` | — | access | Revoke that session (if owned by current user) |
|
||
| POST | `/auth/logout-others` | — | access | Revoke all sessions except current |
|
||
| POST | `/auth/change-password` | `{old_password, new_password}` | access | `provider.authenticate` 校验 old → `provider.revoke_user(user_id)` 失效其他 session（KTD-10: 跨 provider 行为一致） |
|
||
|
||
**Approach (admin endpoints)**:
|
||
|
||
| Method | Path | Auth | Behavior |
|
||
|--------|------|------|----------|
|
||
| GET | `/admin/users/{user_id}/sessions` | admin | List all that user's sessions (incl revoked) |
|
||
| DELETE | `/admin/users/{user_id}/sessions/{sid}` | admin | Force-revoke any session |
|
||
|
||
**Approach (`/auth/whoami` middleware bypass — critical fix)**:
|
||
|
||
The current `AuthMiddleware._verify_jwt` (in `src/agentkit/server/auth/middleware.py:80-91`) only accepts `type=access` tokens and 401s on `type=refresh`. The cold-start sequence sends a refresh token (because the access token is gone). To make this work without weakening auth, `/auth/whoami` is added to `AuthMiddleware.WHITELIST_PATHS` and the route does its own auth:
|
||
|
||
```python
|
||
# In auth/middleware.py:
|
||
WHITELIST_PATHS = (
|
||
"/api/v1/health",
|
||
"/api/v1/auth/login",
|
||
"/api/v1/auth/refresh",
|
||
"/api/v1/auth/logout",
|
||
"/api/v1/auth/whoami", # NEW: route does its own auth
|
||
"/docs",
|
||
"/openapi.json",
|
||
"/redoc",
|
||
)
|
||
```
|
||
|
||
The `/auth/whoami` route accepts **either** an access token (normal call) **or** a refresh token (cold-start), and the auth check happens inside the route via `verify_token` + session lookup:
|
||
|
||
```python
|
||
@router.get("/whoami")
|
||
async def whoami(request: Request) -> WhoamiResponse:
|
||
"""Returns the current user + session metadata.
|
||
|
||
Accepts either type=access (normal) or type=refresh (cold-start).
|
||
On 401 from this endpoint, the client treats it as 'invalid' state
|
||
(NOT 'error' state) so the router redirects to /login.
|
||
"""
|
||
auth_header = request.headers.get("Authorization", "")
|
||
if not auth_header.startswith("Bearer "):
|
||
raise HTTPException(401, "missing bearer token")
|
||
token = auth_header[7:]
|
||
|
||
try:
|
||
payload = verify_token(token, expected_type=None) # accept both types
|
||
except jwt.ExpiredSignatureError:
|
||
raise HTTPException(401, "token expired")
|
||
except jwt.InvalidTokenError:
|
||
raise HTTPException(401, "invalid token")
|
||
|
||
sid = payload.get("sid")
|
||
if sid:
|
||
# New-style: validate session in DB
|
||
session = await session_service.get_active_session(sid)
|
||
if not session:
|
||
raise HTTPException(401, "session revoked or expired")
|
||
user = await load_user(session.user_id)
|
||
# Issue a fresh access token so the client doesn't need a separate /refresh
|
||
new_access = create_access_token(user_id=user.id, session_id=session.id)
|
||
return WhoamiResponse(
|
||
user=user_to_response(user),
|
||
access_token=new_access,
|
||
session=session_to_response(session),
|
||
)
|
||
else:
|
||
# Legacy token without sid — back-compat path (U10)
|
||
user = await load_user(payload["sub"])
|
||
if not user or not user.is_active:
|
||
raise HTTPException(401, "user not found or inactive")
|
||
new_access = create_access_token(user_id=user.id, session_id=None) # legacy
|
||
return WhoamiResponse(
|
||
user=user_to_response(user),
|
||
access_token=new_access,
|
||
session=None, # no session metadata for legacy
|
||
)
|
||
```
|
||
|
||
**Approach (defined phantom functions)**:
|
||
|
||
The plan's pseudo-code references several functions that don't exist yet. Define them explicitly:
|
||
|
||
```python
|
||
# In auth/dependencies.py — NEW dependency for current session
|
||
async def get_current_session(request: Request) -> AuthSession:
|
||
"""Return the active session for the current request.
|
||
|
||
Reads request.state.session (set by get_current_user middleware/dependency).
|
||
Raises 401 if no session (legacy tokens) or session is revoked.
|
||
"""
|
||
session = getattr(request.state, "session", None)
|
||
if session is None:
|
||
raise HTTPException(401, "no active session (legacy token)")
|
||
return session
|
||
|
||
# In auth/dependencies.py — keep existing get_current_user but extend it
|
||
async def get_current_user(request: Request) -> User:
|
||
"""Return the current authenticated user.
|
||
|
||
Strategy:
|
||
- If request.state.current_user is already set (by AuthMiddleware for
|
||
type=access tokens), return it.
|
||
- Otherwise, this is called from a path that bypassed middleware
|
||
(e.g. /auth/whoami). The route must have set request.state.user
|
||
via its own auth check.
|
||
- Legacy tokens (no sid) only set current_user, not session.
|
||
"""
|
||
user = getattr(request.state, "current_user", None)
|
||
if user is None:
|
||
user = getattr(request.state, "user", None) # set by whoami route
|
||
if user is None:
|
||
raise HTTPException(401, "not authenticated")
|
||
return user
|
||
|
||
# In auth/users.py — NEW helper
|
||
async def load_user(user_id: str) -> User | None:
|
||
"""Load a user by id. Returns None if not found or inactive."""
|
||
async with aiosqlite.connect(str(DEFAULT_AUTH_DB_PATH)) as db:
|
||
cursor = await db.execute(
|
||
"SELECT * FROM users WHERE id = ? AND is_active = 1", (user_id,)
|
||
)
|
||
row = await cursor.fetchone()
|
||
return user_row_to_dict(row) if row else None
|
||
```
|
||
|
||
**Approach (`get_current_user` back-compat with sid validation)**:
|
||
|
||
The new `get_current_user` is called by routes after `AuthMiddleware` has run. The middleware sets `request.state.current_user` (a dict with `id`, `username`, `role`, etc.) for `type=access` tokens. With the new sid-bearing tokens, the middleware is extended to also set `request.state.session`:
|
||
|
||
```python
|
||
# In auth/middleware.py — extend _verify_jwt to also load session
|
||
def _verify_jwt(self, token: str) -> dict[str, Any] | None:
|
||
# ... existing signature/expiry check ...
|
||
sid = payload.get("sid")
|
||
if sid:
|
||
# Synchronous check is not possible (DB call). Defer to a
|
||
# per-route dependency. Middleware only checks signature + expiry
|
||
# for new tokens; the session-revoked check happens in the
|
||
# get_current_user dependency.
|
||
pass
|
||
return payload
|
||
```
|
||
|
||
The session-revoked check is then done lazily in `get_current_session`, which calls `SessionService.get_active_session(sid)`. This is one extra DB-or-cache call per request, mitigated by the 60s Redis cache (KTD-6).
|
||
|
||
**Approach (`change_password`)**:
|
||
|
||
```python
|
||
@router.post("/change-password")
|
||
async def change_password(
|
||
payload: ChangePasswordRequest,
|
||
user: User = Depends(get_current_user),
|
||
session: AuthSession = Depends(get_current_session),
|
||
):
|
||
if not verify_password(payload.old_password, user.password_hash):
|
||
raise HTTPException(400, "old password incorrect")
|
||
new_hash = hash_password(payload.new_password)
|
||
async with aiosqlite.connect(str(DEFAULT_AUTH_DB_PATH)) as db:
|
||
await db.execute(
|
||
"UPDATE users SET password_hash=?, updated_at=? WHERE id=?",
|
||
(new_hash, _now_iso(), user.id),
|
||
)
|
||
await db.commit()
|
||
revoked_count = await session_service.revoke_all_for_user(
|
||
user.id, except_sid=session.id, reason="password_changed"
|
||
)
|
||
logger.info(f"Password changed for user {user.id}; revoked {revoked_count} other sessions")
|
||
return {"ok": True, "revoked_sessions": revoked_count}
|
||
```
|
||
|
||
**Test scenarios** (test_auth_routes.py):
|
||
- **Happy path**:
|
||
- `POST /auth/login` with valid creds → 200, returns token pair + user
|
||
- `POST /auth/login` with `remember_me=true` → refresh token exp 30d
|
||
- `POST /auth/login` with `remember_me=false` → refresh token exp 7d
|
||
- `POST /auth/refresh` with current token → 200, new pair (different from old)
|
||
- `GET /auth/whoami` with access token → 200, returns user + session metadata
|
||
- `GET /auth/whoami` with refresh token (cold-start case) → 200
|
||
- `GET /auth/sessions` → list of current user's active sessions
|
||
- `DELETE /auth/sessions/{sid}` for own session → 200, that session now revoked
|
||
- `POST /auth/logout-others` → 200, all other sessions revoked
|
||
- `POST /auth/change-password` with correct old → 200, other sessions revoked
|
||
- **Error paths**:
|
||
- `POST /auth/login` with wrong password → 401 (constant-time)
|
||
- `POST /auth/login` with unknown user → 401 (constant-time)
|
||
- `POST /auth/login` with inactive user → 403
|
||
- `POST /auth/refresh` with reused old token → 401 `{error: "token_reuse_detected"}`
|
||
- `POST /auth/refresh` with denylisted token → 401
|
||
- `POST /auth/refresh` with tampered token → 401
|
||
- `GET /auth/whoami` with no Authorization header → 401
|
||
- `GET /auth/whoami` with expired access token → 401
|
||
- `DELETE /auth/sessions/{sid}` for someone else's session → 403
|
||
- `POST /auth/change-password` with wrong old password → 400
|
||
- `POST /auth/change-password` with weak new password (if validation added) → 422
|
||
- **Integration**:
|
||
- Login from client A, login from client B (different IPs / fingerprints) → both have independent sessions
|
||
- Login as user from 11 different fingerprints → 11th login evicts the 1st (oldest non-current)
|
||
- Change password → other devices get 401 on next request → bounced to /login
|
||
|
||
**Test scenarios** (test_admin_routes.py):
|
||
- `GET /admin/users/{id}/sessions` as admin → returns all sessions (active + revoked)
|
||
- `GET /admin/users/{id}/sessions` as non-admin → 403
|
||
- `DELETE /admin/users/{id}/sessions/{sid}` as admin → that session revoked
|
||
- `DELETE /admin/users/{id}/sessions/{sid}` as non-admin → 403
|
||
|
||
**Verification**: All integration tests pass; `pytest tests/integration/auth/ -v` shows green.
|
||
|
||
---
|
||
|
||
### U5. Tauri: keyring integration + commands
|
||
|
||
**Goal**: Add three Tauri commands to read/write/clear the refresh token in OS Keychain.
|
||
|
||
**Requirements**: F3.
|
||
|
||
**Dependencies**: None on the auth side; only depends on Tauri Cargo config.
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/frontend/src-tauri/Cargo.toml` — add `keyring = { version = "3", features = ["apple-native", "windows-native", "linux-native"] }` (or just default features if 3 platforms covered)
|
||
- `src/agentkit/server/frontend/src-tauri/src/auth.rs` — new module with 3 `#[tauri::command]` functions
|
||
- `src/agentkit/server/frontend/src-tauri/src/lib.rs` — register the commands in `tauri::Builder::default().invoke_handler(...)`
|
||
- `src/agentkit/server/frontend/src-tauri/capabilities/default.json` — add the 3 commands to the `permissions` allowlist
|
||
- `tests/unit-tauri/test_keyring.rs` — Rust unit tests using `keyring::mock` feature
|
||
|
||
**Approach (auth.rs)**:
|
||
```rust
|
||
const SERVICE: &str = "com.fischer.agentkit";
|
||
const USERNAME: &str = "refresh_token";
|
||
|
||
#[tauri::command]
|
||
pub async fn store_refresh_token(token: String) -> Result<(), String> {
|
||
let entry = keyring::Entry::new(SERVICE, USERNAME)
|
||
.map_err(|e| format!("keychain init failed: {e}"))?;
|
||
entry.set_password(&token)
|
||
.map_err(|e| format!("keychain write failed: {e}"))
|
||
}
|
||
|
||
#[tauri::command]
|
||
pub async fn load_refresh_token() -> Result<Option<String>, String> {
|
||
let entry = keyring::Entry::new(SERVICE, USERNAME)
|
||
.map_err(|e| format!("keychain init failed: {e}"))?;
|
||
match entry.get_password() {
|
||
Ok(t) => Ok(Some(t)),
|
||
Err(keyring::Error::NoEntry) => Ok(None),
|
||
Err(e) => Err(format!("keychain read failed: {e}")),
|
||
}
|
||
}
|
||
|
||
#[tauri::command]
|
||
pub async fn clear_refresh_token() -> Result<(), String> {
|
||
let entry = keyring::Entry::new(SERVICE, USERNAME)
|
||
.map_err(|e| format!("keychain init failed: {e}"))?;
|
||
match entry.delete_credential() {
|
||
Ok(()) => Ok(()),
|
||
Err(keyring::Error::NoEntry) => Ok(()),
|
||
Err(e) => Err(format!("keychain delete failed: {e}")),
|
||
}
|
||
}
|
||
```
|
||
|
||
**Approach (Cargo.toml)**:
|
||
- Add `keyring = "3"` under `[dependencies]`
|
||
- macOS: requires the binary to be signed (Keychain access); for unsigned dev builds, fallback to `keyring::mock` via feature flag (not needed in this plan; document in README instead)
|
||
|
||
**Approach (capabilities/default.json)**:
|
||
- Add 3 entries to the `permissions` array:
|
||
- `"core:default:allow-store-refresh-token"`
|
||
- `"core:default:allow-load-refresh-token"`
|
||
- `"core:default:allow-clear-refresh-token"`
|
||
|
||
**Test scenarios** (test_keyring.rs):
|
||
- `store_refresh_token("abc")` then `load_refresh_token()` returns `Some("abc")`
|
||
- `clear_refresh_token()` then `load_refresh_token()` returns `None`
|
||
- `load_refresh_token()` on a fresh keyring returns `None` (not error)
|
||
- Use `keyring::mock` feature for CI tests; real platform tests are manual on macOS dev machine
|
||
|
||
**Verification**: `cargo test --manifest-path src/agentkit/server/frontend/src-tauri/Cargo.toml` passes; manual smoke: launch Tauri dev, log in, check macOS Keychain Access.app for the entry.
|
||
|
||
---
|
||
|
||
### U6. Frontend: tauri-auth.ts adapter
|
||
|
||
**Goal**: Abstract Keychain (Tauri) / localStorage (Web) access behind a single async API.
|
||
|
||
**Requirements**: F3, F4.
|
||
|
||
**Dependencies**: U5 (the Rust commands must exist for invoke() to work).
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/frontend/src/api/tauri-auth.ts` — new module
|
||
- `tests/unit/api/tauri-auth.test.ts` — unit tests with mocked `invoke`
|
||
|
||
**Approach**:
|
||
```typescript
|
||
const SERVICE = 'agentkit.refresh_token'
|
||
|
||
function isTauri(): boolean {
|
||
return typeof window !== 'undefined' && '__TAURI_INTERNALS__' in window
|
||
}
|
||
|
||
export const tauriAuthStorage = {
|
||
async setRefreshToken(token: string): Promise<void> {
|
||
if (isTauri()) {
|
||
try {
|
||
const { invoke } = await import('@tauri-apps/api/core')
|
||
await invoke('store_refresh_token', { token })
|
||
return
|
||
} catch (e) {
|
||
console.warn('[auth] Keychain write failed, falling back to localStorage', e)
|
||
}
|
||
}
|
||
localStorage.setItem(SERVICE, token)
|
||
},
|
||
|
||
async getRefreshToken(): Promise<string | null> {
|
||
if (isTauri()) {
|
||
try {
|
||
const { invoke } = await import('@tauri-apps/api/core')
|
||
return await invoke<string | null>('load_refresh_token')
|
||
} catch (e) {
|
||
console.warn('[auth] Keychain read failed, falling back to localStorage', e)
|
||
}
|
||
}
|
||
return localStorage.getItem(SERVICE)
|
||
},
|
||
|
||
async clearRefreshToken(): Promise<void> {
|
||
if (isTauri()) {
|
||
try {
|
||
const { invoke } = await import('@tauri-apps/api/core')
|
||
await invoke('clear_refresh_token')
|
||
} catch (e) {
|
||
console.warn('[auth] Keychain clear failed, falling back to localStorage', e)
|
||
}
|
||
}
|
||
localStorage.removeItem(SERVICE)
|
||
},
|
||
}
|
||
```
|
||
|
||
**Test scenarios** (tauri-auth.test.ts):
|
||
- `isTauri()` returns `true` when `__TAURI_INTERNALS__` is in window
|
||
- `setRefreshToken` in Tauri mode calls `invoke('store_refresh_token', { token })`
|
||
- `setRefreshToken` in Tauri mode falls back to localStorage when invoke throws
|
||
- `setRefreshToken` in Web mode (no Tauri) writes to localStorage directly
|
||
- `getRefreshToken` in Tauri mode returns the value from `invoke('load_refresh_token')`
|
||
- `getRefreshToken` in Tauri mode falls back to localStorage when invoke throws
|
||
- `clearRefreshToken` in Tauri mode calls `invoke('clear_refresh_token')`
|
||
- `clearRefreshToken` in Web mode removes from localStorage
|
||
|
||
**Verification**: `npm run test:unit -- tauri-auth.test.ts` passes; manual test: launch Tauri, log in, verify entry in macOS Keychain.
|
||
|
||
---
|
||
|
||
### U7. Frontend: auth store refactor (3-state startup, pre-emptive refresh)
|
||
|
||
**Goal**: Rewrite `stores/auth.ts` to support the new flow.
|
||
|
||
**Requirements**: F1, F10, F11, F12.
|
||
|
||
**Dependencies**: U6 (adapter), U4 (server endpoints).
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/frontend/src/stores/auth.ts` — major refactor
|
||
- `src/agentkit/server/frontend/src/api/auth.ts` — add `whoami()`, `login(rememberMe)`, `changePassword()`, `listSessions()`, `revokeSession()`
|
||
- `tests/unit/stores/auth.test.ts` — extend existing test file
|
||
|
||
**Approach (new auth store shape)**:
|
||
```typescript
|
||
type AuthStartupState = 'valid' | 'invalid' | 'error' | 'pending'
|
||
|
||
export const useAuthStore = defineStore('auth', () => {
|
||
// --- State ---
|
||
const accessToken = ref<string | null>(null) // memory only, never persisted
|
||
const user = ref<IAuthUser | null>(readStoredUser()) // localStorage cache for avatar/role
|
||
const startupState = ref<AuthStartupState>('pending')
|
||
const isLoading = ref(false)
|
||
const error = ref<string | null>(null)
|
||
|
||
// --- Getters ---
|
||
const isAuthenticated = computed(() => !!accessToken.value && !!user.value)
|
||
const accessTokenExp = computed<number | null>(() => decodeJwtExp(accessToken.value))
|
||
const shouldRefresh = computed(() => {
|
||
if (!accessTokenExp.value) return false
|
||
return accessTokenExp.value * 1000 - Date.now() < 2 * 60 * 1000 // < 2 min
|
||
})
|
||
|
||
// --- Mutators ---
|
||
function _setAccess(token: string, user: IAuthUser): void {
|
||
accessToken.value = token
|
||
// user goes to localStorage (safe — no secret)
|
||
localStorage.setItem(USER_KEY, JSON.stringify(user))
|
||
// refresh token goes to Keychain (Tauri) or localStorage (Web)
|
||
// (called separately by login/refresh)
|
||
}
|
||
|
||
async function _persistTokenPair(pair: ITokenPair): Promise<void> {
|
||
accessToken.value = pair.access_token
|
||
user.value = pair.user
|
||
writeStoredUser(pair.user)
|
||
await tauriAuthStorage.setRefreshToken(pair.refresh_token)
|
||
}
|
||
|
||
function _clear(): void {
|
||
accessToken.value = null
|
||
// do NOT clear user from localStorage (UI shows cached avatar/role)
|
||
// do NOT call tauriAuthStorage.clear here; caller decides
|
||
}
|
||
|
||
// --- Actions ---
|
||
async function login(username, password, rememberMe = false): Promise<void> {
|
||
const pair = await authApi.login(username, password, rememberMe)
|
||
await _persistTokenPair(pair)
|
||
startupState.value = 'valid'
|
||
}
|
||
|
||
async function startupCheck(): Promise<AuthStartupState> {
|
||
const refresh = await tauriAuthStorage.getRefreshToken()
|
||
if (!refresh) {
|
||
startupState.value = 'invalid' // not an error — just no token
|
||
return startupState.value
|
||
}
|
||
try {
|
||
const result = await authApi.whoami(refresh)
|
||
// whoami returns { user, access_token, session }
|
||
accessToken.value = result.access_token
|
||
user.value = result.user
|
||
writeStoredUser(result.user)
|
||
startupState.value = 'valid'
|
||
} catch (err) {
|
||
if (err.status === 401) {
|
||
await tauriAuthStorage.clearRefreshToken()
|
||
startupState.value = 'invalid'
|
||
} else {
|
||
startupState.value = 'error' // network or server issue
|
||
}
|
||
}
|
||
return startupState.value
|
||
}
|
||
|
||
async function silentRefresh(): Promise<void> {
|
||
const refresh = await tauriAuthStorage.getRefreshToken()
|
||
if (!refresh) {
|
||
_clear()
|
||
throw new Error('no refresh token')
|
||
}
|
||
try {
|
||
const pair = await authApi.refresh(refresh)
|
||
await _persistTokenPair(pair)
|
||
} catch (err) {
|
||
if (err.status === 401) {
|
||
// reuse detected or all sessions revoked
|
||
await tauriAuthStorage.clearRefreshToken()
|
||
}
|
||
_clear()
|
||
throw err
|
||
}
|
||
}
|
||
|
||
async function logout(): Promise<void> {
|
||
const refresh = await tauriAuthStorage.getRefreshToken()
|
||
if (refresh) {
|
||
try { await authApi.logout(refresh) } catch { /* server may be down */ }
|
||
}
|
||
await tauriAuthStorage.clearRefreshToken()
|
||
_clear()
|
||
user.value = null // explicit: logged out means no cached user
|
||
}
|
||
|
||
function logoutLocal(): void {
|
||
_clear()
|
||
user.value = null
|
||
}
|
||
|
||
return { /* state, getters, actions */ }
|
||
})
|
||
```
|
||
|
||
**Approach (api/auth.ts additions)**:
|
||
```typescript
|
||
async login(username, password, rememberMe = false): Promise<ITokenPair> {
|
||
return this.request('/auth/login', {
|
||
method: 'POST',
|
||
body: JSON.stringify({ username, password, remember_me: rememberMe }),
|
||
})
|
||
}
|
||
|
||
async whoami(refreshToken?: string): Promise<{ user: IAuthUser; access_token: string; session: SessionInfo }> {
|
||
// whoami accepts either an access token (normal call) or a refresh token (cold start)
|
||
// The base client's auth header injection handles access; for the cold-start case
|
||
// we need a special path that uses the refresh token instead.
|
||
return this.requestWithAuth('/auth/whoami', refreshToken)
|
||
}
|
||
|
||
async listSessions(): Promise<SessionInfo[]> { ... }
|
||
async revokeSession(sid: string): Promise<void> { ... }
|
||
async changePassword(oldPassword: string, newPassword: string): Promise<void> { ... }
|
||
```
|
||
|
||
**Approach (api/base.ts interceptor)**:
|
||
```typescript
|
||
this.client.interceptors.request.use(async (config) => {
|
||
const auth = useAuthStore()
|
||
if (auth.shouldRefresh && auth.accessToken) {
|
||
try {
|
||
await auth.silentRefresh()
|
||
} catch {
|
||
// silent refresh failed; let the request go through and 401 will trigger route
|
||
}
|
||
}
|
||
if (auth.accessToken) {
|
||
config.headers.Authorization = `Bearer ${auth.accessToken}`
|
||
}
|
||
return config
|
||
})
|
||
```
|
||
|
||
**Test scenarios** (auth.test.ts):
|
||
- `login(...)` calls authApi.login with remember_me param
|
||
- `login(...)` persists refresh token via tauriAuthStorage.setRefreshToken
|
||
- `startupCheck()` with no refresh token → state='invalid'
|
||
- `startupCheck()` with valid refresh → state='valid', user populated
|
||
- `startupCheck()` with 401 from whoami → state='invalid', refresh token cleared
|
||
- `startupCheck()` with network error → state='error', refresh token retained
|
||
- `silentRefresh()` succeeds → new access in memory, new refresh in Keychain
|
||
- `silentRefresh()` on 401 reuse → all state cleared, refresh token cleared
|
||
- `shouldRefresh` is true when access expires in <2 min
|
||
- `shouldRefresh` is false when access expires in >2 min or no access
|
||
- `logout()` calls authApi.logout then clears Keychain + state
|
||
- `logout()` doesn't fail when server is down (best-effort)
|
||
- Access token is NEVER written to localStorage (spy on localStorage.setItem)
|
||
|
||
**Verification**: `npm run test:unit -- auth.test.ts` passes; manual e2e via `npm run tauri dev`.
|
||
|
||
---
|
||
|
||
### U8. Frontend: LoginView "Remember me" + Settings sessions UI
|
||
|
||
**Goal**: User-facing changes to the login page and a new "Active Sessions" panel in settings.
|
||
|
||
**Requirements**: F2, F7, F8 (user-side).
|
||
|
||
**Dependencies**: U7 (store + api), U4 (endpoints).
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/frontend/src/views/LoginView.vue` — add "Remember me" checkbox; pass to store.login
|
||
- `src/agentkit/server/frontend/src/views/SettingsView.vue` — new section "Active sessions" (or new route `/settings/sessions`)
|
||
- `src/agentkit/server/frontend/src/components/settings/ActiveSessionsPanel.vue` — new component
|
||
- `src/agentkit/server/frontend/src/components/settings/ChangePasswordPanel.vue` — new component
|
||
- `src/agentkit/server/frontend/src/router/index.ts` — add `/settings/sessions` and `/settings/security` routes
|
||
- `tests/unit/views/LoginView.test.ts` — checkbox behavior
|
||
- `tests/unit/components/ActiveSessionsPanel.test.ts`
|
||
|
||
**Approach (LoginView additions)**:
|
||
```vue
|
||
<a-checkbox v-model:checked="form.rememberMe">
|
||
记住我（30 天内免登录）
|
||
</a-checkbox>
|
||
```
|
||
```typescript
|
||
async function handleSubmit() {
|
||
await authStore.login(form.username, form.password, form.rememberMe)
|
||
router.replace(redirectTarget())
|
||
}
|
||
```
|
||
|
||
**Approach (ActiveSessionsPanel.vue)**:
|
||
- On mount: call `authApi.listSessions()`, render table (Device / Last active / Created / [Revoke] button)
|
||
- "Current session" row has a badge; revoke button is disabled for the current row
|
||
- "Revoke" calls `authApi.revokeSession(sid)` and removes the row
|
||
- "Revoke all others" button at the top → calls `authApi.logoutOthers()` and reloads
|
||
|
||
**Approach (ChangePasswordPanel.vue)**:
|
||
- 3 fields: old password, new password, confirm new password
|
||
- Submit: `authApi.changePassword(old, new)`
|
||
- On success: show success message; note "其他设备将自动登出"
|
||
|
||
**Test scenarios**:
|
||
- `LoginView` renders the checkbox; submitting with it checked passes `rememberMe=true` to store
|
||
- `ActiveSessionsPanel` renders a row per session from the API response
|
||
- `ActiveSessionsPanel` "Revoke" button calls `authApi.revokeSession(sid)` and removes the row optimistically
|
||
- `ActiveSessionsPanel` "Revoke all others" calls `authApi.logoutOthers()` and reloads the list
|
||
- `ActiveSessionsPanel` disables Revoke on the current session row
|
||
- `ChangePasswordPanel` shows field-level validation errors (mismatched passwords)
|
||
- `ChangePasswordPanel` on success shows toast and clears the form
|
||
|
||
**Verification**: `npm run test:unit -- LoginView ActiveSessionsPanel ChangePasswordPanel` passes; Playwright e2e for the full settings flow.
|
||
|
||
---
|
||
|
||
### U9. Admin UI: user sessions management
|
||
|
||
**Goal**: Admins can see and revoke any user's active sessions.
|
||
|
||
**Requirements**: F7, F8 (admin-side).
|
||
|
||
**Dependencies**: U7, U4 (admin endpoints exist), U8 (reuses ActiveSessionsPanel layout).
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/frontend/src/views/admin/UsersView.vue` (or `UserDetailView.vue`) — add "Sessions" tab
|
||
- `src/agentkit/server/frontend/src/components/admin/UserSessionsPanel.vue` — admin variant
|
||
- `src/agentkit/server/frontend/src/api/admin.ts` — new file
|
||
- `tests/unit/components/UserSessionsPanel.test.ts`
|
||
|
||
**Approach**:
|
||
- Reuse `ActiveSessionsPanel` styling; pass an `adminMode` prop that adds:
|
||
- Show username in the table header
|
||
- Allow revoke of any session including current
|
||
- Show revoked sessions with strikethrough
|
||
- API: `adminApi.listUserSessions(userId)`, `adminApi.revokeUserSession(userId, sid)`
|
||
|
||
**Test scenarios**:
|
||
- Admin can see all sessions for a user (active + revoked)
|
||
- Admin can revoke any session
|
||
- Non-admin attempting to call adminApi endpoints gets a clear 403 error in the UI
|
||
|
||
**Verification**: `npm run test:unit -- UserSessionsPanel` passes; manual e2e with admin login.
|
||
|
||
---
|
||
|
||
### U10. Backwards-compat + rollout shim
|
||
|
||
**Goal**: Existing in-flight clients (without `sid` claim) keep working for one minor version.
|
||
|
||
**Requirements**: N6.
|
||
|
||
**Dependencies**: U4 (the back-compat path in `get_current_user`).
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/dependencies.py` — `get_current_user` accepts both with-sid and without-sid JWTs; logs a DEBUG for legacy
|
||
- `src/agentkit/server/auth/jwt_utils.py` — `create_token_pair` has a `legacy_mode=True` flag for the migration window; tokens issued during migration carry `sid` but the validator still accepts old ones
|
||
- `docs/migrations/2026-06-20-client-version-rollout.md` — new doc explaining the rollout window (server logs a warning when a legacy JWT is accepted)
|
||
|
||
**Approach**:
|
||
- Add an `X-Client-Version` header to all requests (set in `api/base.ts`)
|
||
- Server middleware reads this header; if version < `0.5.0`, it issues a legacy JWT (no sid) so that client doesn't get a 401 it can't handle
|
||
- New clients always get a `sid`-bearing JWT
|
||
- After one minor version (~30 days), remove the legacy path in a separate change
|
||
|
||
**Test scenarios**:
|
||
- `get_current_user` with a sid-bearing JWT loads the session, validates it, returns the user
|
||
- `get_current_user` with a JWT without sid (legacy) accepts it as long as signature + exp are valid
|
||
- `get_current_user` with a sid-bearing JWT where the session is revoked → 401
|
||
- `get_current_user` with a sid-bearing JWT where the session doesn't exist → 401
|
||
- Legacy middleware path issues tokens without `sid` for clients with `X-Client-Version < 0.5.0`
|
||
|
||
**Verification**: Backwards-compat test using a hand-crafted legacy JWT; new client flow continues to work; manual test with the previous-version frontend.
|
||
|
||
---
|
||
|
||
### U11. AuthProvider 抽象层（为未来 IdP 对接留扩展点）
|
||
|
||
**Goal**: 把"用户存在哪里 / 密码怎么校验 / 属性怎么同步"封装在可插拔的 `AuthProvider` adapter 后面。当前实现 `LocalAuthProvider`（封装 SQLite + bcrypt）；同时提供 `StubOIDCProvider` 占位实现（`raise NotImplementedError`）作为未来 OIDC 实现的接口契约参考。路由层 / admin API / SessionService 通过 `Depends(get_auth_provider)` 拿到 provider 引用，**未来切 IdP 零修改路由**。
|
||
|
||
**Requirements**: F13, F14, F15.
|
||
|
||
**Dependencies**: None（被 U1/U3/U4 引用；可与 U1-U4 任何阶段并行或先后落地；建议在 Phase 1 早期就上，因为 U1 schema 需要 `auth_provider` 字段）。
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/auth/providers/__init__.py` — new package；导出 `AuthProvider`、`get_auth_provider()` 工厂、`LocalAuthProvider`、`StubOIDCProvider`
|
||
- `src/agentkit/server/auth/providers/base.py` — `AuthProvider` Protocol（`name: str` + `authenticate` / `get_user_by_id` / `sync_user_attributes` / `revoke_user` 4 个 async 方法）
|
||
- `src/agentkit/server/auth/providers/local.py` — `LocalAuthProvider` 实现，封装现有 `auth/password.py` 逻辑（bcrypt 校验 + 查 users 表）
|
||
- `src/agentkit/server/auth/providers/oidc_stub.py` — `StubOIDCProvider` 占位实现，所有方法 `raise NotImplementedError` 并在 docstring 中指向下一迭代 OIDC 实现的 checklist
|
||
- `src/agentkit/server/config.py` — extend `AuthConfig` with `provider: Literal["local", "oidc-stub"] = "local"`（或新增 `auth.provider` 字段）
|
||
- `tests/unit/auth/providers/test_base.py` — Protocol 静态类型检查（`runtime_checkable` Protocol 验证）+ mock provider 用例
|
||
- `tests/unit/auth/providers/test_local.py` — `LocalAuthProvider` 全量单测（复用 `auth/password.py` 测试场景）
|
||
- `tests/unit/auth/providers/test_oidc_stub.py` — `StubOIDCProvider` 调用任意方法均抛 `NotImplementedError` 的单测
|
||
|
||
**Approach (AuthProvider Protocol)**:
|
||
|
||
```python
|
||
# auth/providers/base.py
|
||
from typing import Protocol, runtime_checkable
|
||
from ..models import User
|
||
|
||
@runtime_checkable
|
||
class AuthProvider(Protocol):
|
||
"""所有鉴权后端必须实现的能力。
|
||
|
||
路由层只调用以下方法，不感知具体实现是 SQLite / OIDC / LDAP。
|
||
未来新增 IdP 只需新加一个实现此 Protocol 的 adapter。
|
||
"""
|
||
|
||
name: str # 标识当前 provider，写入 session.auth_provider
|
||
|
||
async def authenticate(self, *, username: str, password: str) -> User:
|
||
"""校验用户名 + 密码，返回 User 对象。失败抛 InvalidCredentials。"""
|
||
...
|
||
|
||
async def get_user_by_id(self, user_id: int) -> User | None:
|
||
"""按 id 查 user（admin 端点、session 校验、whoami 都用这个）。"""
|
||
...
|
||
|
||
async def sync_user_attributes(self, user_id: int) -> None:
|
||
"""同步用户属性（部门/邮箱/职位等）。LocalAuthProvider: no-op；OidcAuthProvider: 从 IdP 拉最新 profile 写回本地。"""
|
||
...
|
||
|
||
async def revoke_user(self, user_id: int) -> None:
|
||
"""禁用用户（离职/锁定）。LocalAuthProvider: UPDATE users SET is_active=0；OidcAuthProvider: 调 IdP 的 disable API（未来）。"""
|
||
...
|
||
```
|
||
|
||
**Approach (LocalAuthProvider)**: 把 `routes/auth.py:201-213` 的 password 校验逻辑（SQLite SELECT + bcrypt 校验 + load_user）搬到 `LocalAuthProvider.authenticate`。路由层不再直接调 `verify_password` / `load_user` —— 统一走 provider。`revoke_user` 走 `UPDATE users SET is_active=0`（admin 端点统一调这个，不再直接写 DB）。
|
||
|
||
**Approach (StubOIDCProvider)**: 所有方法 raise `NotImplementedError`，docstring 写明：
|
||
> 当前未实现。下一迭代 OIDC 集成时，重写本类即可，路由 / admin / Session 表零修改。配置 `auth.provider: oidc-stub` 启动会立即报 NotImplementedError（这是设计：避免误启用未完成的功能）。
|
||
|
||
**Approach (DI 工厂)**:
|
||
|
||
```python
|
||
# auth/providers/__init__.py
|
||
from functools import lru_cache
|
||
from ...config import get_settings
|
||
from .base import AuthProvider
|
||
from .local import LocalAuthProvider
|
||
from .oidc_stub import StubOIDCProvider
|
||
|
||
@lru_cache
|
||
def get_auth_provider() -> AuthProvider:
|
||
settings = get_settings()
|
||
provider_name = settings.auth.provider
|
||
if provider_name == "local":
|
||
db = get_auth_db() # 现有 aiosqlite 连接（需改造为模块级单例）
|
||
return LocalAuthProvider(db)
|
||
elif provider_name == "oidc-stub":
|
||
return StubOIDCProvider()
|
||
else:
|
||
raise ValueError(f"unknown auth provider: {provider_name}")
|
||
```
|
||
|
||
**Approach (config 扩展)**:
|
||
|
||
```yaml
|
||
# agentkit.yaml
|
||
auth:
|
||
provider: local # local | oidc-stub (未来: oidc-keycloak, oidc-feishu, ...)
|
||
session:
|
||
table: auth_sessions
|
||
access_ttl_seconds: 900
|
||
refresh_ttl_seconds: 604800
|
||
refresh_ttl_remember_me_seconds: 2592000
|
||
jwt:
|
||
secret_env: AGENTKIT_JWT_SECRET
|
||
algorithm: HS256
|
||
```
|
||
|
||
**Test scenarios** (test_base.py + test_local.py + test_oidc_stub.py):
|
||
- `LocalAuthProvider` with valid username+password returns User
|
||
- `LocalAuthProvider` with wrong password raises `InvalidCredentials`
|
||
- `LocalAuthProvider` with unknown username raises `InvalidCredentials`
|
||
- `LocalAuthProvider` with inactive user (`is_active=0`) raises `InvalidCredentials`
|
||
- `LocalAuthProvider.get_user_by_id` returns the user or None
|
||
- `LocalAuthProvider.sync_user_attributes` is a no-op (returns None)
|
||
- `LocalAuthProvider.revoke_user` sets `is_active=0` and subsequent `authenticate` fails
|
||
- `LocalAuthProvider.name == "local"`
|
||
- `StubOIDCProvider.authenticate` raises `NotImplementedError` with helpful message
|
||
- `StubOIDCProvider.get_user_by_id` raises `NotImplementedError`
|
||
- `StubOIDCProvider.sync_user_attributes` raises `NotImplementedError`
|
||
- `StubOIDCProvider.revoke_user` raises `NotImplementedError`
|
||
- `StubOIDCProvider.name == "oidc-stub"`
|
||
- `get_auth_provider()` with `auth.provider=local` returns `LocalAuthProvider` instance
|
||
- `get_auth_provider()` with `auth.provider=oidc-stub` returns `StubOIDCProvider` instance
|
||
- `get_auth_provider()` with `auth.provider=unknown` raises `ValueError`
|
||
- `get_auth_provider()` is memoized (lru_cache; second call returns same instance)
|
||
- `runtime_checkable(AuthProvider)`: both Local and Stub pass `isinstance(prov, AuthProvider)` check
|
||
- Protocol violation: a class missing `authenticate` method does NOT pass `isinstance` check (negative test)
|
||
|
||
**Patterns to follow**:
|
||
- Protocol + runtime_checkable pattern (Python typing best practice)
|
||
- DI 工厂 + lru_cache 单例（与现有 `get_settings` 一致）
|
||
- error 类型 `InvalidCredentials` 放到 `auth/providers/exceptions.py`（新建）
|
||
|
||
**Verification**:
|
||
- `pytest tests/unit/auth/providers/ -v` 全部通过
|
||
- `mypy src/agentkit/server/auth/providers/` 无报错
|
||
- 启动 dev server，配置 `auth.provider: oidc-stub` → 第一次 `/auth/login` 返回 501 NotImplementedError（确认 stub 起作用）
|
||
- 启动 dev server，配置 `auth.provider: local` → 走现有登录流程，确认未破坏
|
||
- admin 踢人功能调用 `provider.revoke_user(user_id)` 后，user 再 `authenticate` 失败（cross-check LocalAuthProvider.revoke_user 行为）
|
||
|
||
**未来 IdP 对接 checklist**（下一迭代参考）:
|
||
|
||
- [ ] `auth/providers/oidc.py` — 实现 `OidcAuthProvider`（authenticate / get_user / sync_attributes / revoke_user）
|
||
- [ ] `auth/oauth_routes.py` — `/auth/oauth/{provider}/redirect` 和 `/auth/oauth/{provider}/callback` 端点
|
||
- [ ] `auth/state_cache.py` — OAuth state 参数防 CSRF（Redis TTL 5min）
|
||
- [ ] 用户首次从 IdP 登录时的「本地账号创建」策略（justeer / 拒绝 / 邀请制）
|
||
- [ ] IdP 端的 session 同步（IdP 登出时本地 session 也撤销）
|
||
- [ ] 集团部门 / 职位属性映射到本地 users 表
|
||
|
||
本次迭代只做 Protocol + Local 实现 + Stub 占位 + DI 工厂 + 上述 1-3 项的占位（接口定义），其余列入下一迭代独立 brainstorm。
|
||
|
||
---
|
||
|
||
## System-Wide Impact
|
||
|
||
| Stakeholder | Impact | Mitigation |
|
||
|-------------|--------|------------|
|
||
| End users (Tauri) | First login → no more login prompts for 7d (30d if "remember me"). | Pre-emptive refresh + Keychain storage prevent the failure modes that broke the existing flow. |
|
||
| End users (Web) | Same as Tauri but refresh in localStorage (degraded security). | Document the trade-off; Keychain is Tauri-only. |
|
||
| Admins | New capability: see active sessions, kick any user. | UI in admin pages; surface clearly in the Users view. |
|
||
| Developers (auth code) | New session module, denylist, cache, **AuthProvider 抽象层**. | U3 is the single source of truth — routes don't duplicate logic. U11 is the single source of auth backend — routes don't import password.py directly. |
|
||
| **未来集团 IdP 集成团队** | 切到 OIDC / SAML / LDAP 时只新增 adapter，不重写路由 / admin | U11 Protocol + LocalAuthProvider 已上；下一迭代 `auth/providers/oidc.py` 直接实现 Protocol 即可 |
|
||
| Existing in-flight clients | Unaffected during 30-day window. | U10 shim. |
|
||
| Server load | +1 cache lookup per request (cached 60s). | Redis-backed cache makes this sub-ms. |
|
||
| DB schema | New `auth_sessions` table (含 `auth_provider` 字段); existing `user_sessions` deprecated. | Alembic migration; keep `user_sessions` reads working for one version. |
|
||
|
||
---
|
||
|
||
## Risks & Dependencies
|
||
|
||
| Risk | Likelihood | Impact | Mitigation |
|
||
|------|------------|--------|------------|
|
||
| `keyring` crate compatibility issues on Linux without `gnome-keyring` / `kwallet` | Medium | Low (Tauri dev) | Document `apt install gnome-keyring` in README; fallback to localStorage as per KTD-confirmed decision. |
|
||
| Tauri WebView localStorage might be cleared on Tauri upgrade | Low | Medium (forces re-login) | Refresh token is in Keychain, not localStorage, so this is no longer a re-login trigger. Only the cached user (avatar) is lost. |
|
||
| Refresh token rotation causes concurrent-request races | Medium | Medium (false-positive reuse detection) | The 30s denylist window catches the case; legitimate retries complete in <1s. Add a metric for reuse detection so we can spot flapping. |
|
||
| Migration corrupts existing refresh tokens | Low | High (users locked out) | Test migration on a copy of prod DB; preserve `user_sessions` reads for back-compat. |
|
||
| Session cap eviction surprises users (they didn't expect to be kicked) | Low | Low (visible at next login) | Make the cap (10) generous; document it; do not log evicted users out silently. |
|
||
| Test mocks diverge from real `keyring` behavior | Medium | Medium (CI passes, manual fails) | Use `keyring::mock` feature in CI; document that real-platform testing is manual. |
|
||
| JWT secret rotation in dev mode invalidates all sessions | Low | High (Tauri dev loops) | Document the behavior; provide `agentkit doctor` to check. |
|
||
| **AuthProvider 切换时遗留 routes 直接调 `verify_password` / 改 users 表**（KTD-10） | Medium | Medium（切 IdP 时必须清理） | U11 引入后强制要求所有 routes 走 `Depends(get_auth_provider)`；code review 模板加 checklist「禁止 routes 直接调 password/auth 函数」 |
|
||
| **`lru_cache` 单例 + 测试隔离冲突**（U11） | Low | Low（测试 flaky） | `get_auth_provider` 提供 `cache_clear()` helper；`conftest.py` 在每个 test fixture 前后清缓存 |
|
||
| **未来 IdP 接管时 `LocalAuthProvider` 残留依赖** | Low | Low（迁移期保留即可） | U11 checklist 显式列出：Local 仍可用作"本地应急账号"，OIDC 接管后不删 Local，仅调整路由默认 provider |
|
||
|
||
### External Dependencies
|
||
|
||
| Dependency | Version | Required For |
|
||
|------------|---------|--------------|
|
||
| `keyring` (Rust crate) | 3.x | Tauri Keychain integration (U5) |
|
||
| `pyjwt` (Python) | already in use | JWT signing/verification (U2) |
|
||
| `aiosqlite` (Python) | already in use | DB layer (U1, U3) |
|
||
| `alembic` (Python) | already in use | Migrations (U1) |
|
||
| `redis` (Python) | already in use | Session cache (U3) — optional; in-process fallback |
|
||
| `@tauri-apps/api` (TS) | 2.x | Tauri command invocation (U6) |
|
||
|
||
---
|
||
|
||
## Phased Delivery
|
||
|
||
This plan has natural phasing based on dependency order. Each phase lands as a single PR.
|
||
|
||
### Phase 1: Backend foundation (U1, U2, U3)
|
||
|
||
- `auth_sessions` table + migration
|
||
- JWT sid/jti claims
|
||
- SessionService with rotation + reuse detection
|
||
- Redis/in-process cache
|
||
- ~3-4 days of work, no frontend changes
|
||
|
||
**Rollout gate**: Deploy to dev. All existing clients continue to work (legacy JWT path). New login creates `auth_sessions` rows; old `user_sessions` rows are no longer written.
|
||
|
||
### Phase 2: New endpoints (U4, U10)
|
||
|
||
- All new auth + admin endpoints
|
||
- Backwards-compat shim
|
||
- Admin endpoint tests
|
||
- ~2 days of work, frontend still on old flow
|
||
|
||
**Rollout gate**: Deploy to dev. New endpoints are available; old `/auth/login` and `/auth/refresh` still work (with legacy tokens).
|
||
|
||
### Phase 3: Tauri Keychain (U5, U6)
|
||
|
||
- Rust commands + Cargo dep
|
||
- Frontend tauri-auth adapter
|
||
- ~1-2 days of work
|
||
|
||
**Rollout gate**: Build a new Tauri release. Verify on macOS (Keychain Access.app shows the entry). Linux without keyring daemon → manual test fallback.
|
||
|
||
### Phase 4: Frontend refactor (U7, U8, U9)
|
||
|
||
- Auth store rewrite (3-state, pre-emptive refresh, no access in localStorage)
|
||
- LoginView "Remember me"
|
||
- Active Sessions panel in Settings
|
||
- Admin user sessions panel
|
||
- ~3-4 days of work
|
||
|
||
**Rollout gate**: Frontend rebuild. End-to-end manual test on Tauri (macOS) + Web. Run Playwright suite.
|
||
|
||
### Phase 5: Cleanup (after one minor version, ~30 days)
|
||
|
||
- Remove the legacy JWT back-compat path
|
||
- Drop the `user_sessions` table
|
||
- Update `X-Client-Version` floor
|
||
- ~1 day of work
|
||
|
||
### Phase 6: AuthProvider 抽象层（U11 + 关联改造）
|
||
|
||
> **2026-06-20 新增 Phase**（合并 AuthProvider scope）
|
||
|
||
- `auth/providers/base.py` — `AuthProvider` Protocol + `runtime_checkable`
|
||
- `auth/providers/local.py` — `LocalAuthProvider`（封装现有 `routes/auth.py:201-213` 的 password 校验逻辑）
|
||
- `auth/providers/oidc_stub.py` — `StubOIDCProvider`（`raise NotImplementedError` 占位）
|
||
- `auth/providers/__init__.py` — `get_auth_provider()` DI 工厂（`lru_cache` 单例）
|
||
- `config.py` — 新增 `auth.provider: local | oidc-stub` 配置
|
||
- U1 schema 加 `auth_provider` 字段（合并入 Phase 1 U1）
|
||
- U3 SessionService `create_session` 接受 `auth_provider` 参数（合并入 Phase 1 U3）
|
||
- U4 routes `Depends(get_auth_provider)` 注入；admin 端点调 `provider.revoke_user(user_id)` 而不是直接改 users 表（合并入 Phase 2 U4）
|
||
- ~1.5 days of work（可以与 Phase 1 早期并行落地）
|
||
|
||
**Rollout gate**:
|
||
- `pytest tests/unit/auth/providers/ -v` 全部通过
|
||
- 启动 dev server，配置 `auth.provider: oidc-stub` → 第一次 `/auth/login` 返回 501 NotImplementedError
|
||
- 启动 dev server，配置 `auth.provider: local` → 现有登录流程不受影响
|
||
- admin 踢人功能调用 `provider.revoke_user(user_id)` 行为与原 DB 直接 UPDATE 等价
|
||
|
||
**未来 IdP 集成入口**：下一迭代 OIDC 集成只需新加 `auth/providers/oidc.py` + `auth/oauth_routes.py`（见 U11 checklist），路由 / admin / Session 表零修改。
|
||
|
||
---
|
||
|
||
## Open Questions
|
||
|
||
These are deferred to implementation and tracked here for visibility:
|
||
|
||
1. **Q1**: Should "Active Sessions" be a tab in Settings or a separate route (`/settings/sessions`)? Plan defaults to a Settings tab; revisit if UX testing suggests otherwise.
|
||
2. **Q2**: Should the admin UI show `revoked_reason` for kicked sessions? Plan defaults to YES (audit value); revisit if it adds too much visual noise.
|
||
3. **Q3**: Should the cap-eviction trigger a server-side notification (e.g. an `audit_event`)? Plan defaults to writing a row to a future `auth_audit_log` table; for now, just the `revoked_reason='session_cap_eviction'` field is enough.
|
||
4. **Q4**: Should `change_password` rate-limit (e.g. 5 attempts per hour)? Out of scope here but worth a follow-up security brainstorm.
|
||
5. **Q5**: macOS Tauri builds need code-signing for Keychain access. The dev binary is unsigned → Keychain prompts "always allow". Plan documents this; production builds must be signed.
|
||
6. **Q6 (新增 2026-06-20)**: AuthProvider 抽象层与现有 `routes/auth.py:201-213` 的 password 校验逻辑如何共存？计划方案：U11 第一步 `LocalAuthProvider` 完整复刻现有逻辑（行为等价），第二步 U4 routes 改造时一次性切换；U11 落地时写"行为等价"测试套件确认切换前后行为一致
|
||
7. **Q7 (新增 2026-06-20)**: `get_auth_provider()` 的 `lru_cache` 单例在测试环境如何隔离？计划方案：导出 `cache_clear()` helper；`conftest.py` 在每个 test fixture 前后 `get_auth_provider.cache_clear()`；不引入 `dependency_overrides`（避免 FastAPI app 状态污染）
|
||
|
||
---
|
||
|
||
## Sources & Research
|
||
|
||
### Codebase references
|
||
|
||
- [src/agentkit/server/auth/models.py](src/agentkit/server/auth/models.py) — current `UserSessionModel` + aiosqlite bootstrap pattern
|
||
- [src/agentkit/server/auth/jwt_utils.py](src/agentkit/server/auth/jwt_utils.py) — current JWT issuance
|
||
- [src/agentkit/server/routes/auth.py](src/agentkit/server/routes/auth.py) — current login/refresh/logout/me
|
||
- [src/agentkit/server/auth/password.py](src/agentkit/server/auth/password.py) — bcrypt cost=12
|
||
- [src/agentkit/server/auth/dependencies.py](src/agentkit/server/auth/dependencies.py) — `require_authenticated`
|
||
- [src/agentkit/server/app.py:928](src/agentkit/server/app.py#L928) — router registration
|
||
- [src/agentkit/server/frontend/src/stores/auth.ts](src/agentkit/server/frontend/src/stores/auth.ts) — current Pinia store
|
||
- [src/agentkit/server/frontend/src/router/index.ts:166-189](src/agentkit/server/frontend/src/router/index.ts#L166-L189) — route guard
|
||
- [src/agentkit/server/frontend/src/views/LoginView.vue](src/agentkit/server/frontend/src/views/LoginView.vue) — login page
|
||
- [src/agentkit/server/frontend/src/api/auth.ts](src/agentkit/server/frontend/src/api/auth.ts) — frontend auth API client
|
||
- [src/agentkit/server/frontend/src/api/base.ts](src/agentkit/server/frontend/src/api/base.ts) — base API client + interceptor
|
||
- [src/agentkit/server/frontend/src-tauri/Cargo.toml](src/agentkit/server/frontend/src-tauri/Cargo.toml) — current Tauri deps
|
||
- [src/agentkit/server/frontend/src-tauri/src/lib.rs](src/agentkit/server/frontend/src-tauri/src/lib.rs) — current Tauri command registration
|
||
|
||
### External references
|
||
|
||
- OWASP JWT Security Cheat Sheet — refresh token rotation, denylist patterns
|
||
- Auth0 Refresh Token Rotation docs (https://auth0.com/docs/secure/tokens/refresh-tokens/refresh-token-rotation)
|
||
- `keyring` crate v3 docs (https://docs.rs/keyring/latest/keyring/) — cross-platform credential storage
|
||
- Tauri 2.x Capabilities system — command allowlisting (https://v2.tauri.app/security/capabilities/)
|
||
|
||
### Institutional learnings
|
||
|
||
- Project context: [AGENTS.md](AGENTS.md) + [.trae/rules/project_rules.md](.trae/rules/project_rules.md) — security and async generator safety rules apply
|
||
- Existing tests: `tests/unit/auth/` + `tests/integration/auth/` — patterns to follow for new test files
|
||
- The current `_refreshFailed` sticky flag in [stores/auth.ts:112](src/agentkit/server/frontend/src/stores/auth.ts#L112) is the root cause of the "logged out for no reason" UX — the rewrite in U7 eliminates it by always re-trying the refresh before giving up
|
||
|
||
---
|
||
|
||
## Acceptance Examples (for the executor / reviewer)
|
||
|
||
The following end-to-end flows must work after this plan lands. Each is testable in Playwright or manual e2e.
|
||
|
||
### AE-1: First login → cold start → main app (Covers F1, F3, F10, F11)
|
||
|
||
1. Launch Tauri (clean state, no Keychain entry)
|
||
2. Login with valid credentials → land on `/agent`
|
||
3. Close Tauri window
|
||
4. Re-launch Tauri (cold start)
|
||
5. **Expected**: brief splash, then `/agent`. No login page seen. Keychain Access.app shows an entry for `com.fischer.agentkit / refresh_token`.
|
||
|
||
### AE-2: Token expiry mid-session → silent refresh (Covers F10)
|
||
|
||
1. Log in; access token exp 15 min
|
||
2. Wait 13 minutes (or manually expire the token in DB)
|
||
3. Make an API call (e.g. fetch conversations)
|
||
4. **Expected**: request succeeds (silent refresh happened before the call); no 401 surfaced to the user.
|
||
|
||
### AE-3: Refresh token reuse → all sessions revoked (Covers F5, F9)
|
||
|
||
1. Log in from Tauri (session A)
|
||
2. Log in from Web (session B)
|
||
3. Copy A's refresh token from Keychain
|
||
4. Wait for A to refresh once legitimately (A's old refresh is now in the 30s denylist, and A has a new refresh)
|
||
5. Try to use the copied old refresh token
|
||
6. **Expected**: 401 with `error: "token_reuse_detected"`. A's session is revoked. B's session is also revoked. Both clients get bounced to /login.
|
||
|
||
### AE-4: Password change → other device kicked (Covers F9)
|
||
|
||
1. Log in from Tauri (session A) and Web (session B) as the same user
|
||
2. From A, change password
|
||
3. From B, make any API call
|
||
4. **Expected**: B gets 401 → bounced to /login. A continues to work.
|
||
|
||
### AE-5: Admin kicks a session (Covers F7, F8)
|
||
|
||
1. User logs in from Tauri and Web
|
||
2. Admin opens the Users view, selects the user, opens the Sessions tab
|
||
3. Admin clicks "Revoke" on the Tauri session
|
||
4. **Expected**: Tauri client's next API call returns 401 → bounced to /login. Web session is unaffected.
|
||
|
||
### AE-6: Remember me toggle (Covers F2)
|
||
|
||
1. Log in with "Remember me" UNCHECKED
|
||
2. **Expected**: refresh token exp is 7 days
|
||
3. Log out, log in with "Remember me" CHECKED
|
||
4. **Expected**: refresh token exp is 30 days
|
||
|
||
### AE-7: Session cap eviction (Covers F12 + the cap)
|
||
|
||
1. Log in 10 times from 10 different simulated clients (use curl with different User-Agent headers)
|
||
2. **Expected**: 10 sessions exist, all active
|
||
3. Log in an 11th time
|
||
4. **Expected**: the oldest non-current session is revoked (visible in DB with `revoked_reason='session_cap_eviction'`); the 11 sessions are now the 2nd-10th + the new 11th
|
||
|
||
### AE-8: Web fallback to localStorage (Covers F4)
|
||
|
||
1. Open the app in a browser (not Tauri)
|
||
2. Log in
|
||
3. **Expected**: `localStorage.getItem('agentkit.refresh_token')` returns the token. DevTools shows the value.
|
||
4. (Note: this is the documented degraded security model for Web clients)
|
||
|
||
### AE-9: Old client still works during migration (Covers N6)
|
||
|
||
1. Build a previous-version frontend
|
||
2. Log in (gets a legacy JWT without sid)
|
||
3. Make API calls
|
||
4. **Expected**: server validates the legacy JWT via the back-compat path; user is not affected
|
||
|
||
### AE-10: AuthProvider 切换（local → oidc-stub 验证接口契约）(Covers F13, F14)
|
||
|
||
> **2026-06-20 新增**（KTD-10 / U11 验证）
|
||
|
||
1. 配置 `agentkit.yaml` 的 `auth.provider: local`，启动 dev server
|
||
2. 调 `POST /auth/login` 用现有 admin 账号
|
||
3. **Expected**: 200 OK，返回 TokenResponse；DB 中 `auth_sessions.auth_provider='local'`
|
||
4. 改配置为 `auth.provider: oidc-stub`，重启 dev server
|
||
5. 调 `POST /auth/login` 同样账号
|
||
6. **Expected**: 501 Not Implemented（StubOIDCProvider 抛 NotImplementedError）
|
||
7. 验证 admin 端点 `/admin/users/{id}/sessions` 仍能列出步骤 3 创建的 session（含 `auth_provider='local'` 字段）
|
||
8. **Expected**: admin 看 session 列表功能不受 provider 切换影响（KTD-10 核心承诺）
|
||
9. 调 `isinstance(provider_instance, AuthProvider)` 验证 Local 和 Stub 都通过 Protocol 检查
|
||
10. **Expected**: 两者都返回 `True`（`runtime_checkable` Protocol 行为正确）
|
||
|
||
### AE-11: 审计字段 auth_provider 写入（覆盖历史 + 新建）(Covers F15)
|
||
|
||
1. 在 AE-1 步骤 1-2 完成后，调 `GET /auth/sessions` 列出当前 user 的所有 active session
|
||
2. **Expected**: 每个 session 包含 `auth_provider: "local"` 字段（即使是 backfill 自 `user_sessions` 的行也是 `'local'`，因为 backfill 走默认值）
|
||
3. admin 调 `GET /admin/users/{id}/sessions` 跨 user 看
|
||
4. **Expected**: 所有 session 都带 `auth_provider` 字段，admin 可按 provider 过滤（即使当前只有 local，未来 oidc 接入后会有 oidc-* 区分）
|
||
5. `SessionService.list_active_by_provider('local')` 返回所有 local session
|
||
6. **Expected**: count = 步骤 2 看到的总数
|
||
7. `SessionService.list_active_by_provider('oidc-stub')` 在当前实现下返回空 list
|
||
8. **Expected**: count = 0（证明字段存在但无数据，未来 OIDC 接入后才会有值）
|
||
5. Server log shows DEBUG: "Legacy JWT without sid; using exp-only validation"
|