feat(app): add plugin system with auth plugin and static assets

Add new application structure:
- app/main.py - application entry point
- app/plugins/ - plugin system with auth plugin:
  - api/ - REST API endpoints and schemas
  - authorization/ - auth policies, providers, hooks
  - domain/ - business logic (service, models, jwt, password)
  - injection/ - route injection and guards
  - ops/ - operational utilities
  - runtime/ - runtime configuration
  - security/ - middleware, CSRF, dependencies
  - storage/ - user repositories and models
- app/static/ - static assets (scalar.js for API docs)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

backend/app/main.py

@@ -0,0 +1,15 @@
+"""Entry point for running the Gateway API via `python app/main.py`.
+
+Useful for IDE debugging (e.g., PyCharm / VS Code debug configurations).
+Equivalent to: PYTHONPATH=. uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
+"""
+
+import uvicorn
+
+if __name__ == "__main__":
+    uvicorn.run(
+        "app.gateway.app:app",
+        host="0.0.0.0",
+        port=8001,
+        reload=True,
+    )

backend/app/plugins/README.md

@@ -0,0 +1,314 @@
+# app.plugins Design Overview
+
+This document describes the current role of `backend/app/plugins`, its plugin design contract, dependency boundaries, and how the current `auth` plugin provides services with minimal intrusion into the host application.
+
+## 1. Overall Role
+
+`app.plugins` is the application-side plugin boundary.
+
+Its purpose is not to implement a generic plugin marketplace. Instead, it provides a clear boundary inside `app` for separable business capabilities, so that a capability can:
+
+1. carry its own domain model, runtime state, and adapters inside the plugin
+2. interact with the host application only through a limited set of seams
+3. remain replaceable, removable, and extensible over time
+
+The only real plugin currently implemented under this directory is [`auth`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth).
+
+The current direction is not “put all logic into app”. It is:
+
+1. the host application owns unified bootstrap, shared infrastructure, and top-level router assembly
+2. each plugin owns its own business contract, persistence definitions, runtime state, and outward-facing adapters
+
+## 2. Plugin Design Contract
+
+### 2.1 A plugin should carry its own implementation
+
+The primary contract visible in the current codebase is:
+
+A plugin’s own ORM, runtime, domain, and adapters should be implemented inside the plugin itself. Core business behavior should not be scattered into unrelated external modules.
+
+The `auth` plugin already follows that pattern with a fairly complete internal structure:
+
+1. `domain`
+   - config, errors, JWT, password logic, domain models, service
+2. `storage`
+   - plugin-owned ORM models, repository contracts, and repository implementations
+3. `runtime`
+   - plugin-owned runtime config state
+4. `api`
+   - plugin-owned HTTP router and schemas
+5. `security`
+   - plugin-owned middleware, dependencies, CSRF logic, and LangGraph adapter
+6. `authorization`
+   - plugin-owned permission model, policy resolution, and hooks
+7. `injection`
+   - plugin-owned route-policy loading, injection, and validation
+
+In other words, a plugin should be a self-contained capability module, not a bag of helpers.
+
+### 2.2 The host app should provide shared infrastructure, not plugin internals
+
+The current contract is not that every plugin must be fully infrastructure-independent.
+
+It is:
+
+1. a plugin may reuse the application’s shared `engine`, `session_factory`, FastAPI app, and router tree
+2. but the plugin must still own its table definitions, repositories, runtime config, and business/auth behavior
+
+This is stated explicitly in [`auth/plugin.toml`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/plugin.toml):
+
+1. `storage.mode = "shared_infrastructure"`
+2. the plugin owns its storage definitions and repositories
+3. but it reuses the application’s shared persistence infrastructure
+
+So the real rule is not “never reuse infrastructure”. The real rule is “do not outsource plugin business semantics to the rest of the app”.
+
+### 2.3 Dependencies should remain one-way
+
+The intended dependency direction in the current design is:
+
+```text
+gateway / app bootstrap
+  -> plugin public adapters
+     -> plugin domain / storage / runtime
+```
+
+Not:
+
+```text
+plugin domain
+  -> depends on app business modules
+```
+
+A plugin may depend on:
+
+1. shared persistence infrastructure
+2. `app.state` provided by the host application
+3. generic framework capabilities such as FastAPI / Starlette
+
+But its core business rules should not depend on unrelated app business modules, otherwise hot-swappability becomes unrealistic.
+
+## 3. The Current auth Plugin Structure
+
+The current `auth` plugin is effectively a self-contained authentication and authorization package with its own models, services, and adapters.
+
+### 3.1 domain
+
+[`auth/domain`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/domain) owns:
+
+1. `config.py`
+   - auth-related configuration definition and loading
+2. `errors.py`
+   - error codes and response contracts
+3. `jwt.py`
+   - token encoding and decoding
+4. `password.py`
+   - password hashing and verification
+5. `models.py`
+   - auth domain models
+6. `service.py`
+   - `AuthService` as the core business service
+
+`AuthService` depends only on the plugin’s own `DbUserRepository` plus the shared session factory. The auth business logic is not reimplemented in `gateway`.
+
+### 3.2 storage
+
+[`auth/storage`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/storage) clearly shows the “ORM is owned by the plugin” contract:
+
+1. [`models.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/storage/models.py)
+   - defines the plugin-owned `users` table model
+2. [`contracts.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/storage/contracts.py)
+   - defines `User`, `UserCreate`, and `UserRepositoryProtocol`
+3. [`repositories.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/storage/repositories.py)
+   - implements `DbUserRepository`
+
+The key point is:
+
+1. the plugin defines its own ORM model
+2. the plugin defines its own repository protocol
+3. the plugin implements its own repository
+4. external code only needs to provide a session or session factory
+
+That is the minimal shared seam the boundary should preserve.
+
+### 3.3 runtime
+
+[`auth/runtime/config_state.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/runtime/config_state.py) keeps plugin-owned runtime config state:
+
+1. `get_auth_config()`
+2. `set_auth_config()`
+3. `reset_auth_config()`
+
+This matters because runtime state is also part of the plugin boundary. If future plugins need their own caches, state holders, or feature flags, they should follow the same pattern and keep them inside the plugin.
+
+### 3.4 adapters
+
+The `auth` plugin exposes capability through four main adapter groups:
+
+1. `api/router.py`
+   - HTTP endpoints
+2. `security/*`
+   - middleware, dependencies, request-user resolution, actor-context bridge
+3. `authorization/*`
+   - capabilities, policy evaluators, auth hooks
+4. `injection/*`
+   - route-policy registry, guard injection, startup validation
+
+These adapters all follow the same rule:
+
+1. entry-point behavior is defined inside the plugin
+2. the host app only assembles and wires it
+
+## 4. How a Plugin Interacts with the Host App
+
+### 4.1 The top-level router only includes plugin routers
+
+[`app/gateway/router.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/gateway/router.py) simply:
+
+1. imports `app.plugins.auth.api.router`
+2. calls `include_router(auth_router)`
+
+That means the host app integrates auth HTTP behavior by assembly, not by duplicating login/register logic in `gateway`.
+
+### 4.2 registrar performs wiring, not takeover
+
+In [`app/gateway/registrar.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/gateway/registrar.py), the host app mainly does this:
+
+1. `app.state.authz_hooks = build_authz_hooks()`
+2. loads and validates the route-policy registry
+3. calls `install_route_guards(app)`
+4. calls `app.add_middleware(CSRFMiddleware)`
+5. calls `app.add_middleware(AuthMiddleware)`
+
+So the host app only wires the plugin in:
+
+1. register middleware
+2. install route guards
+3. expose hooks and registries through `app.state`
+
+The actual auth logic, authz logic, and route-policy semantics still live inside the plugin.
+
+### 4.3 The plugin reuses shared sessions, but still owns business repositories
+
+In [`auth/security/dependencies.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/security/dependencies.py):
+
+1. the plugin reads the shared session factory from `request.app.state.persistence.session_factory`
+2. constructs `DbUserRepository` itself
+3. constructs `AuthService` itself
+
+This is a good low-intrusion seam:
+
+1. the outside world provides only shared infrastructure handles
+2. the plugin decides how to instantiate its internal dependencies
+
+## 5. Hot-Swappability and Low-Intrusion Principles
+
+### 5.1 If a plugin serves other modules, it should minimize intrusion
+
+When a plugin provides services to the rest of the app, the preferred patterns are:
+
+1. expose a router
+2. expose middleware or dependencies
+3. expose hooks or protocols
+4. inject a small number of shared objects through `app.state`
+5. use config-driven route policies or capabilities instead of hardcoding checks inside business routes
+
+Patterns to avoid:
+
+1. large plugin-specific branches spread across `gateway`
+2. unrelated business modules importing plugin ORM internals and rebuilding plugin logic themselves
+3. plugin state being maintained across many global modules
+
+### 5.2 Low-intrusion seams already visible in auth
+
+The current `auth` plugin already uses four important low-intrusion seams:
+
+1. router integration
+   - `gateway.router` only calls `include_router`
+2. middleware integration
+   - `registrar` only registers `AuthMiddleware` and `CSRFMiddleware`
+3. policy injection
+   - `install_route_guards(app)` appends `Depends(enforce_route_policy)` uniformly to routes
+4. hook seam
+   - `authz_hooks` is exposed via `app.state`, so permission providers and policy builders can be replaced
+
+This structure has three practical benefits:
+
+1. host-app changes stay concentrated in the assembly layer
+2. plugin core logic stays concentrated inside the plugin directory
+3. swapping implementations does not require editing business routes one by one
+
+### 5.3 Route policy is a key low-intrusion mechanism
+
+[`auth/injection/registry_loader.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/injection/registry_loader.py), [`validation.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/injection/validation.py), and [`route_injector.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/injection/route_injector.py) together form an important contract:
+
+1. route policies live in the plugin-owned `route_policies.yaml`
+2. startup validates that policy entries and real routes stay aligned
+3. guards are attached by uniform injection instead of manual per-endpoint code
+
+That allows the plugin to:
+
+1. describe which routes are public, which capabilities are required, and which owner policies apply
+2. avoid large invasive changes to the host routing layer
+3. remain easier to replace or trim down later
+
+## 6. What “ORM and runtime are implemented inside the plugin” Should Mean
+
+That contract should be read as three concrete rules:
+
+1. data models belong to the plugin
+   - the plugin’s own tables, Pydantic contracts, repository protocols, and repository implementations stay inside the plugin directory
+2. runtime state belongs to the plugin
+   - plugin-owned config caches, context bridges, and plugin-level hooks stay inside the plugin
+3. the outside world exposes infrastructure, not plugin semantics
+   - for example shared `session_factory`, FastAPI app, and `app.state`
+
+Using `auth` as the example:
+
+1. the `users` table is defined inside the plugin, not in `app.infra`
+2. `AuthService` is implemented inside the plugin, not in `gateway`
+3. `get_auth_config()` is maintained inside the plugin, not cached elsewhere
+4. `AuthMiddleware`, `route_guard`, and `AuthzHooks` are all provided by the plugin itself
+
+This is the structural prerequisite for meaningful pluginization later.
+
+## 7. Current Scope and Non-Goals
+
+At the current stage, the role of `app.plugins` is mainly:
+
+1. to create module boundaries for separable application-side capabilities
+2. to let each plugin own its own domain/storage/runtime/adapters
+3. to connect plugins to the host app through assembly-oriented seams
+
+The current non-goals are also clear:
+
+1. this is not yet a full generic plugin discovery/installation system
+2. plugins are not dynamically enabled or disabled at runtime
+3. shared infrastructure is not being duplicated into every plugin
+
+So at this stage, “hot-swappable” should be interpreted more precisely as:
+
+1. plugin boundaries stay as independent as possible
+2. integration points stay concentrated in the assembly layer
+3. replacing or removing a plugin should mostly affect a small number of places such as `registrar`, router includes, and `app.state` hooks
+
+## 8. Suggested Evolution Rules
+
+If `app.plugins` is going to become a more stable plugin boundary, the codebase should keep following these rules:
+
+1. each plugin directory should keep a `domain` / `storage` / `runtime` / `adapter` split
+2. plugin-owned ORM and repositories should not drift into shared business directories
+3. when a plugin serves the rest of the app, it should prefer exposing protocols, hooks, routers, and middleware over forcing external code to import internal implementation details
+4. seams between a plugin and the host app should stay mostly limited to:
+   - `router.include_router(...)`
+   - `app.add_middleware(...)`
+   - `app.state.*`
+   - lifespan/bootstrap wiring
+5. config-driven integration should be preferred over scattered hardcoded integration
+6. startup validation should be preferred over implicit runtime failure
+
+## 9. Summary
+
+The current `app.plugins` contract can be summarized in one sentence:
+
+Each plugin owns its own business implementation, ORM, and runtime; the host application provides shared infrastructure and assembly seams; and services should be integrated through low-intrusion, replaceable boundaries so the system can evolve toward real hot-swappability.

backend/app/plugins/README_zh.md

@@ -0,0 +1,310 @@
+# app.plugins 设计说明
+
+本文基于当前代码实现，说明 `backend/app/plugins` 的定位、插件设计契约、依赖边界，以及当前 `auth` 插件是如何在尽量少侵入宿主应用的前提下提供服务的。
+
+## 1. 总体定位
+
+`app.plugins` 是应用侧插件边界。它的目标不是做一个通用插件市场，而是在 `app` 这一层给可拆分的业务能力预留清晰边界，使某一类能力可以：
+
+1. 在插件内部自带领域模型、运行时状态和适配器
+2. 只通过有限的接缝与宿主应用交互
+3. 在未来保持“可替换、可裁剪、可扩展”
+
+当前目录下实际落地的插件是 [`auth`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth)。
+
+从当前实现看，`app.plugins` 的方向不是“所有逻辑都塞进 app”，而是：
+
+1. 宿主应用负责统一启动、共享基础设施和总路由装配
+2. 插件负责自己的业务契约、持久化定义、运行时状态和外部适配器
+
+## 2. 插件设计契约
+
+### 2.1 插件内部要自带完整能力
+
+当前代码体现出的首要契约是：
+
+插件自己的 ORM、runtime、domain、adapter，原则上都应由插件内部实现，不要把核心业务依赖散落到外部模块。
+
+以 `auth` 插件为例，它内部已经自带了完整分层：
+
+1. `domain`
+   - 配置、错误、JWT、密码、领域模型、服务
+2. `storage`
+   - 插件自己的 ORM 模型、仓储契约和仓储实现
+3. `runtime`
+   - 插件自己的运行时配置状态
+4. `api`
+   - 插件自己的 HTTP router 和 schema
+5. `security`
+   - 插件自己的 middleware、dependency、csrf、LangGraph 适配
+6. `authorization`
+   - 插件自己的权限模型、policy 解析和 hook
+7. `injection`
+   - 插件自己的路由策略注册、注入和校验逻辑
+
+换句话说，插件不是一组零散 helper，而应该是一个自闭合的功能模块。
+
+### 2.2 宿主应用只提供共享基础设施，不承接插件内部逻辑
+
+当前约束不是“插件完全独立进程”，而是：
+
+1. 插件可以复用应用共享的 `engine`、`session_factory`、FastAPI app、路由树
+2. 但插件自己的表结构、仓储、运行时配置、鉴权逻辑，仍然应由插件自己拥有
+
+这一点在 [`auth/plugin.toml`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/plugin.toml) 里写得很明确：
+
+1. `storage.mode = "shared_infrastructure"`
+2. 说明插件拥有自己的 storage definitions 和 repositories
+3. 但复用应用共享的 persistence infrastructure
+
+所以这里的契约不是“禁止复用基础设施”，而是“不要把插件内部业务实现外包给 app 其他模块”。
+
+### 2.3 依赖方向要单向
+
+按当前实现，比较理想的依赖方向是：
+
+```text
+gateway / app bootstrap
+  -> plugin public adapters
+     -> plugin domain / storage / runtime
+```
+
+而不是：
+
+```text
+plugin domain
+  -> 依赖 app 里的业务模块
+```
+
+插件可以使用：
+
+1. 共享持久化基础设施
+2. 宿主应用提供的 `app.state`
+3. FastAPI / Starlette 等通用框架能力
+
+但不应该把自己的核心业务规则建立在别的业务模块之上，否则后续无法热插拔。
+
+## 3. 当前 auth 插件的实际结构
+
+当前 `auth` 插件可以概括为一套“自带模型、自带服务、自带适配器”的认证授权包。
+
+### 3.1 domain
+
+[`auth/domain`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/domain) 负责：
+
+1. `config.py`
+   - 认证相关配置定义与加载
+2. `errors.py`
+   - 错误码和错误响应契约
+3. `jwt.py`
+   - token 编解码
+4. `password.py`
+   - 密码哈希和校验
+5. `models.py`
+   - auth 域模型
+6. `service.py`
+   - `AuthService`，作为核心业务服务
+
+`AuthService` 本身只依赖插件内部的 `DbUserRepository` 和共享 session factory，没有把认证逻辑散到 `gateway`。
+
+### 3.2 storage
+
+[`auth/storage`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/storage) 明确体现了“ORM 由插件自己内部实现”的契约：
+
+1. [`models.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/storage/models.py)
+   - 定义插件自己的 `users` 表模型
+2. [`contracts.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/storage/contracts.py)
+   - 定义 `User`、`UserCreate` 和 `UserRepositoryProtocol`
+3. [`repositories.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/storage/repositories.py)
+   - 实现 `DbUserRepository`
+
+这里的关键点是：
+
+1. 插件自己定义 ORM model
+2. 插件自己定义 repository protocol
+3. 插件自己实现 repository
+4. 外部只需要给它 session / session_factory
+
+这就是插件边界应该保持的最小共享面。
+
+### 3.3 runtime
+
+[`auth/runtime/config_state.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/runtime/config_state.py) 维护插件自己的 runtime config state：
+
+1. `get_auth_config()`
+2. `set_auth_config()`
+3. `reset_auth_config()`
+
+这说明运行时配置状态也属于插件内部，而不是由外部模块代持。后续如果别的插件需要自己的缓存、状态机、feature flag，也应沿这个模式内聚在插件内部。
+
+### 3.4 adapters
+
+`auth` 插件对外暴露能力主要通过四类 adapter：
+
+1. `api/router.py`
+   - HTTP 接口
+2. `security/*`
+   - middleware、dependency、request user 解析、actor context bridge
+3. `authorization/*`
+   - capability、policy evaluator、auth hooks
+4. `injection/*`
+   - route policy registry、guard 注入、启动校验
+
+这类 adapter 的共同特征是：
+
+1. 入口能力在插件内定义
+2. 宿主应用只负责调用和装配
+
+## 4. 插件如何与宿主应用交互
+
+### 4.1 总路由只 include，不重写插件逻辑
+
+[`app/gateway/router.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/gateway/router.py) 只是：
+
+1. 引入 `app.plugins.auth.api.router`
+2. `include_router(auth_router)`
+
+这说明宿主应用对 auth HTTP 能力的接入是装配式的，而不是在 `gateway` 里重写一套登录/注册逻辑。
+
+### 4.2 registrar 负责启动装配，不负责接管插件实现
+
+[`app/gateway/registrar.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/gateway/registrar.py) 里，宿主应用做的事情主要是：
+
+1. `app.state.authz_hooks = build_authz_hooks()`
+2. 加载并校验 route policy registry
+3. `install_route_guards(app)`
+4. `app.add_middleware(CSRFMiddleware)`
+5. `app.add_middleware(AuthMiddleware)`
+
+也就是说，宿主应用只负责把插件接进来：
+
+1. 注册 middleware
+2. 安装 route guard
+3. 把 hooks 和 registry 放到 `app.state`
+
+真正的鉴权逻辑、认证逻辑、路由策略语义仍然在插件内部。
+
+### 4.3 共享会话工厂，但业务仓储仍归插件
+
+在 [`auth/security/dependencies.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/security/dependencies.py) 中：
+
+1. 插件从 `request.app.state.persistence.session_factory` 取得共享 session factory
+2. 然后自己构造 `DbUserRepository`
+3. 再自己构造 `AuthService`
+
+这就是一个很典型的低侵入接缝：
+
+1. 外部只提供共享基础设施句柄
+2. 插件自己决定如何实例化内部依赖
+
+## 5. 热插拔与低侵入原则
+
+### 5.1 如果要向其他模块提供服务，应尽量减少入侵
+
+插件给其他模块提供服务时，优先选下面这些方式：
+
+1. 暴露 router
+2. 暴露 middleware / dependency
+3. 暴露 hook 或 protocol
+4. 通过 `app.state` 注入少量共享对象
+5. 使用配置驱动的 route policy / capability，而不是把判断逻辑硬编码进业务路由
+
+不推荐的方式是：
+
+1. 在 `gateway` 大量写插件特定分支
+2. 让别的业务模块直接 import 插件内部 ORM 细节后自行拼逻辑
+3. 把插件状态散落到全局多个模块中共同维护
+
+### 5.2 当前 auth 插件已经体现出的低侵入点
+
+当前 `auth` 插件的低侵入接入点主要有四个：
+
+1. 路由接入
+   - `gateway.router` 只 `include_router`
+2. 中间件接入
+   - `registrar` 只注册 `AuthMiddleware` / `CSRFMiddleware`
+3. 策略注入
+   - `install_route_guards(app)` 给路由统一追加 `Depends(enforce_route_policy)`
+4. hook 接缝
+   - `authz_hooks` 通过 `app.state` 暴露，策略构建和权限提供器可以替换
+
+这套结构的好处是：
+
+1. 宿主应用改动面集中在装配层
+2. 插件核心实现集中在插件目录内部
+3. 替换实现时，不需要在业务路由里逐个修改
+
+### 5.3 route policy 是低侵入的关键机制
+
+[`auth/injection/registry_loader.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/injection/registry_loader.py)、[`validation.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/injection/validation.py) 和 [`route_injector.py`](/Users/rayhpeng/workspace/open-source/deer-flow/backend/app/plugins/auth/injection/route_injector.py) 共同形成了一套很关键的契约：
+
+1. 路由策略写在插件自己的 `route_policies.yaml`
+2. 启动时会校验策略表和真实路由是否一致
+3. guard 通过统一注入附着到路由，而不是每个 endpoint 手写一遍
+
+这使得插件能够：
+
+1. 用配置描述“哪些路由公开、需要哪些 capability、需要哪些 owner policy”
+2. 避免对宿主路由层做大规模侵入
+3. 在未来更容易替换或裁剪某个插件
+
+## 6. 关于“ORM、runtime 都由自己内部实现”的具体说明
+
+这条契约建议明确理解为以下三点：
+
+1. 数据模型归插件
+   - 插件自己的表、Pydantic contract、repository protocol、repository implementation 都放在插件目录内
+2. 运行时状态归插件
+   - 插件自己的配置缓存、上下文桥、插件级 hooks 都在插件内部维护
+3. 外部只暴露基础设施，不接管插件语义
+   - 例如共享 `session_factory`、FastAPI app、`app.state`
+
+拿 `auth` 举例：
+
+1. `users` 表在插件里定义，不在 `app.infra` 定义
+2. `AuthService` 在插件里实现，不在 `gateway` 实现
+3. `get_auth_config()` 在插件里维护，不由别的模块缓存
+4. `AuthMiddleware`、`route_guard`、`AuthzHooks` 都由插件自己提供
+
+这是后续做插件化时最重要的结构前提。
+
+## 7. 当前作用范围与非目标
+
+就当前实现而言，`app.plugins` 的作用范围主要是：
+
+1. 为应用侧可拆分能力建立模块边界
+2. 让插件拥有自己的 domain/storage/runtime/adapter
+3. 通过装配式接缝接入宿主应用
+
+当前非目标也很明确：
+
+1. 还不是一个完整的通用插件发现/安装系统
+2. 还没有做到运行时动态启停插件
+3. 也不是把共享基础设施完全复制进每个插件
+
+所以“热插拔”在当前阶段更准确的含义是：
+
+1. 插件边界尽量独立
+2. 接入点尽量集中在装配层
+3. 替换或移除时，改动尽量局限在 `registrar`、`router include`、`app.state` hooks 这些少数位置
+
+## 8. 后续演进建议
+
+如果后续要继续把 `app.plugins` 做成更稳定的插件边界，建议保持这些规则：
+
+1. 每个插件目录内部都保持 `domain` / `storage` / `runtime` / `adapter` 分层
+2. 插件自己的 ORM 与 repository 不要下沉到共享业务目录
+3. 插件向外提供服务时优先暴露 protocol、hook、router、middleware，而不是要求外部 import 内部实现细节
+4. 插件与宿主应用的接缝尽量限制在：
+   - `router.include_router(...)`
+   - `app.add_middleware(...)`
+   - `app.state.*`
+   - 生命周期装配
+5. 配置驱动优先于散落的硬编码接入
+6. 启动期校验优先于运行时隐式失败
+
+## 9. 设计总结
+
+可以把当前 `app.plugins` 的契约总结为一句话：
+
+插件内部拥有自己的业务实现、ORM 和 runtime；宿主应用只提供共享基础设施和装配接缝；对外服务时尽量通过低侵入、可替换的方式接入，以便后续做到真正的热插拔和边界演进。

backend/app/plugins/__init__.py

@@ -0,0 +1 @@
+"""Application plugin packages."""

backend/app/plugins/auth/README.md

@@ -0,0 +1,21 @@
+# Auth Plugin
+
+This package is the future Level 2 auth plugin boundary for DeerFlow.
+
+Scope:
+
+- Auth domain logic: config, errors, models, JWT, password hashing, service
+- Auth adapters: HTTP router, FastAPI dependencies, middleware, LangGraph adapter
+- Auth storage: user/account models and repositories
+
+Non-scope:
+
+- Shared app/container bootstrap
+- Shared persistence engine/session lifecycle
+- Generic plugin discovery/registration framework
+
+Target architecture:
+
+- The plugin owns its storage definitions and business logic
+- The plugin reuses the application's shared persistence infrastructure
+- The gateway only assembles the plugin instead of owning auth logic directly

backend/app/plugins/auth/__init__.py

@@ -0,0 +1,14 @@
+"""Auth plugin package.
+
+Level 2 plugin goal:
+- Own auth domain logic
+- Own auth adapters (router, dependencies, middleware, LangGraph adapter)
+- Own auth storage definitions
+- Reuse the application's shared persistence/session infrastructure
+"""
+
+from app.plugins.auth.authorization.hooks import build_authz_hooks
+
+__all__ = [
+    "build_authz_hooks",
+]

backend/app/plugins/auth/api/__init__.py

@@ -0,0 +1,17 @@
+"""HTTP API layer for the auth plugin."""
+
+from app.plugins.auth.api.router import (
+    ChangePasswordRequest,
+    LoginResponse,
+    MessageResponse,
+    RegisterRequest,
+    router,
+)
+
+__all__ = [
+    "ChangePasswordRequest",
+    "LoginResponse",
+    "MessageResponse",
+    "RegisterRequest",
+    "router",
+]

backend/app/plugins/auth/api/router.py

@@ -0,0 +1,171 @@
+"""Authentication endpoints for the auth plugin."""
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
+from fastapi.security import OAuth2PasswordRequestForm
+
+from app.plugins.auth.api.schemas import (
+    ChangePasswordRequest,
+    InitializeAdminRequest,
+    LoginResponse,
+    MessageResponse,
+    RegisterRequest,
+    _check_rate_limit,
+    _get_client_ip,
+    _login_attempts,
+    _record_login_failure,
+    _record_login_success,
+)
+from app.plugins.auth.domain.errors import AuthErrorResponse
+from app.plugins.auth.domain.jwt import create_access_token
+from app.plugins.auth.domain.models import UserResponse
+from app.plugins.auth.domain.service import AuthServiceError
+from app.plugins.auth.runtime.config_state import get_auth_config
+from app.plugins.auth.security.csrf import is_secure_request
+from app.plugins.auth.security.dependencies import CurrentAuthService, get_current_user_from_request
+
+router = APIRouter(prefix="/api/v1/auth", tags=["auth"])
+
+
+def _set_session_cookie(response: Response, token: str, request: Request) -> None:
+    config = get_auth_config()
+    is_https = is_secure_request(request)
+    response.set_cookie(
+        key="access_token",
+        value=token,
+        httponly=True,
+        secure=is_https,
+        samesite="lax",
+        max_age=config.token_expiry_days * 24 * 3600 if is_https else None,
+    )
+
+
+@router.post("/login/local", response_model=LoginResponse)
+async def login_local(
+    request: Request,
+    response: Response,
+    auth_service: CurrentAuthService,
+    form_data: OAuth2PasswordRequestForm = Depends(),
+):
+    client_ip = _get_client_ip(request)
+    _check_rate_limit(client_ip)
+    try:
+        user = await auth_service.login_local(form_data.username, form_data.password)
+    except AuthServiceError as exc:
+        _record_login_failure(client_ip)
+        raise HTTPException(
+            status_code=exc.status_code,
+            detail=AuthErrorResponse(code=exc.code, message=exc.message).model_dump(),
+        ) from exc
+
+    _record_login_success(client_ip)
+    token = create_access_token(str(user.id), token_version=user.token_version)
+    _set_session_cookie(response, token, request)
+    return LoginResponse(
+        expires_in=get_auth_config().token_expiry_days * 24 * 3600,
+        needs_setup=user.needs_setup,
+    )
+
+
+@router.post("/register", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def register(request: Request, response: Response, body: RegisterRequest, auth_service: CurrentAuthService):
+    try:
+        user = await auth_service.register(body.email, body.password)
+    except AuthServiceError as exc:
+        raise HTTPException(
+            status_code=exc.status_code,
+            detail=AuthErrorResponse(code=exc.code, message=exc.message).model_dump(),
+        ) from exc
+
+    token = create_access_token(str(user.id), token_version=user.token_version)
+    _set_session_cookie(response, token, request)
+    return UserResponse(id=str(user.id), email=user.email, system_role=user.system_role)
+
+
+@router.post("/logout", response_model=MessageResponse)
+async def logout(request: Request, response: Response):
+    response.delete_cookie(key="access_token", secure=is_secure_request(request), samesite="lax")
+    return MessageResponse(message="Successfully logged out")
+
+
+@router.post("/change-password", response_model=MessageResponse)
+async def change_password(
+    request: Request,
+    response: Response,
+    body: ChangePasswordRequest,
+    auth_service: CurrentAuthService,
+):
+    user = await get_current_user_from_request(request)
+    try:
+        user = await auth_service.change_password(
+            user,
+            current_password=body.current_password,
+            new_password=body.new_password,
+            new_email=body.new_email,
+        )
+    except AuthServiceError as exc:
+        raise HTTPException(
+            status_code=exc.status_code,
+            detail=AuthErrorResponse(code=exc.code, message=exc.message).model_dump(),
+        ) from exc
+
+    token = create_access_token(str(user.id), token_version=user.token_version)
+    _set_session_cookie(response, token, request)
+    return MessageResponse(message="Password changed successfully")
+
+
+@router.get("/me", response_model=UserResponse)
+async def get_me(request: Request):
+    user = await get_current_user_from_request(request)
+    return UserResponse(id=str(user.id), email=user.email, system_role=user.system_role, needs_setup=user.needs_setup)
+
+
+@router.get("/setup-status")
+async def setup_status(auth_service: CurrentAuthService):
+    return {"needs_setup": await auth_service.get_setup_status()}
+
+
+@router.post("/initialize", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def initialize_admin(
+    request: Request,
+    response: Response,
+    body: InitializeAdminRequest,
+    auth_service: CurrentAuthService,
+):
+    try:
+        user = await auth_service.initialize_admin(body.email, body.password)
+    except AuthServiceError as exc:
+        raise HTTPException(
+            status_code=exc.status_code,
+            detail=AuthErrorResponse(code=exc.code, message=exc.message).model_dump(),
+        ) from exc
+
+    token = create_access_token(str(user.id), token_version=user.token_version)
+    _set_session_cookie(response, token, request)
+    return UserResponse(id=str(user.id), email=user.email, system_role=user.system_role)
+
+
+@router.get("/oauth/{provider}")
+async def oauth_login(provider: str):
+    if provider not in ["github", "google"]:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"Unsupported OAuth provider: {provider}")
+    raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="OAuth login not yet implemented")
+
+
+@router.get("/callback/{provider}")
+async def oauth_callback(provider: str, code: str, state: str):
+    raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="OAuth callback not yet implemented")
+
+
+__all__ = [
+    "ChangePasswordRequest",
+    "InitializeAdminRequest",
+    "LoginResponse",
+    "MessageResponse",
+    "RegisterRequest",
+    "_check_rate_limit",
+    "_get_client_ip",
+    "_login_attempts",
+    "_record_login_failure",
+    "_record_login_success",
+    "router",
+]

backend/app/plugins/auth/api/schemas.py

@@ -0,0 +1,176 @@
+"""HTTP schemas and request helpers for the auth plugin API."""
+
+from __future__ import annotations
+
+import os
+import time
+from ipaddress import ip_address, ip_network
+
+from fastapi import HTTPException, Request
+from pydantic import BaseModel, EmailStr, Field, field_validator
+
+_COMMON_PASSWORDS: frozenset[str] = frozenset(
+    {
+        "password",
+        "password1",
+        "password12",
+        "password123",
+        "password1234",
+        "12345678",
+        "123456789",
+        "1234567890",
+        "qwerty12",
+        "qwertyui",
+        "qwerty123",
+        "abc12345",
+        "abcd1234",
+        "iloveyou",
+        "letmein1",
+        "welcome1",
+        "welcome123",
+        "admin123",
+        "administrator",
+        "passw0rd",
+        "p@ssw0rd",
+        "monkey12",
+        "trustno1",
+        "sunshine",
+        "princess",
+        "football",
+        "baseball",
+        "superman",
+        "batman123",
+        "starwars",
+        "dragon123",
+        "master123",
+        "shadow12",
+        "michael1",
+        "jennifer",
+        "computer",
+    }
+)
+_MAX_LOGIN_ATTEMPTS = 5
+_LOCKOUT_SECONDS = 300
+_MAX_TRACKED_IPS = 10000
+_login_attempts: dict[str, tuple[int, float]] = {}
+
+
+class LoginResponse(BaseModel):
+    expires_in: int
+    needs_setup: bool = False
+
+
+class RegisterRequest(BaseModel):
+    email: EmailStr
+    password: str = Field(..., min_length=8)
+
+    _strong_password = field_validator("password")(classmethod(lambda cls, v: _validate_strong_password(v)))
+
+
+class ChangePasswordRequest(BaseModel):
+    current_password: str
+    new_password: str = Field(..., min_length=8)
+    new_email: EmailStr | None = None
+
+    _strong_password = field_validator("new_password")(classmethod(lambda cls, v: _validate_strong_password(v)))
+
+
+class MessageResponse(BaseModel):
+    message: str
+
+
+class InitializeAdminRequest(BaseModel):
+    email: EmailStr
+    password: str = Field(..., min_length=8)
+
+    _strong_password = field_validator("password")(classmethod(lambda cls, v: _validate_strong_password(v)))
+
+
+def _password_is_common(password: str) -> bool:
+    return password.lower() in _COMMON_PASSWORDS
+
+
+def _validate_strong_password(value: str) -> str:
+    if _password_is_common(value):
+        raise ValueError("Password is too common; choose a stronger password.")
+    return value
+
+
+def _trusted_proxies() -> list:
+    raw = os.getenv("AUTH_TRUSTED_PROXIES", "").strip()
+    if not raw:
+        return []
+    nets = []
+    for entry in raw.split(","):
+        entry = entry.strip()
+        if not entry:
+            continue
+        try:
+            nets.append(ip_network(entry, strict=False))
+        except ValueError:
+            pass
+    return nets
+
+
+def _get_client_ip(request: Request) -> str:
+    peer_host = request.client.host if request.client else None
+    trusted = _trusted_proxies()
+    if trusted and peer_host:
+        try:
+            peer_ip = ip_address(peer_host)
+            if any(peer_ip in net for net in trusted):
+                real_ip = request.headers.get("x-real-ip", "").strip()
+                if real_ip:
+                    return real_ip
+        except ValueError:
+            pass
+    return peer_host or "unknown"
+
+
+def _check_rate_limit(ip: str) -> None:
+    record = _login_attempts.get(ip)
+    if record is None:
+        return
+    fail_count, lock_until = record
+    if fail_count >= _MAX_LOGIN_ATTEMPTS:
+        if time.time() < lock_until:
+            raise HTTPException(status_code=429, detail="Too many login attempts. Try again later.")
+        del _login_attempts[ip]
+
+
+def _record_login_failure(ip: str) -> None:
+    if len(_login_attempts) >= _MAX_TRACKED_IPS:
+        now = time.time()
+        expired = [k for k, (c, t) in _login_attempts.items() if c >= _MAX_LOGIN_ATTEMPTS and now >= t]
+        for key in expired:
+            del _login_attempts[key]
+        if len(_login_attempts) >= _MAX_TRACKED_IPS:
+            by_time = sorted(_login_attempts.items(), key=lambda kv: kv[1][1])
+            for key, _ in by_time[: len(by_time) // 2]:
+                del _login_attempts[key]
+
+    record = _login_attempts.get(ip)
+    if record is None:
+        _login_attempts[ip] = (1, 0.0)
+    else:
+        new_count = record[0] + 1
+        lock_until = time.time() + _LOCKOUT_SECONDS if new_count >= _MAX_LOGIN_ATTEMPTS else 0.0
+        _login_attempts[ip] = (new_count, lock_until)
+
+
+def _record_login_success(ip: str) -> None:
+    _login_attempts.pop(ip, None)
+
+
+__all__ = [
+    "ChangePasswordRequest",
+    "InitializeAdminRequest",
+    "LoginResponse",
+    "MessageResponse",
+    "RegisterRequest",
+    "_check_rate_limit",
+    "_get_client_ip",
+    "_login_attempts",
+    "_record_login_failure",
+    "_record_login_success",
+]

backend/app/plugins/auth/authorization/__init__.py

@@ -0,0 +1,31 @@
+"""Authorization layer for the auth plugin."""
+
+from app.plugins.auth.authorization.authentication import get_auth_context
+from app.plugins.auth.authorization.hooks import (
+    AuthzHooks,
+    build_authz_hooks,
+    build_permission_provider,
+    build_policy_chain_builder,
+    get_authz_hooks,
+    get_default_authz_hooks,
+)
+from app.plugins.auth.authorization.types import (
+    AuthContext,
+    Permissions,
+    ALL_PERMISSIONS,
+)
+
+_ALL_PERMISSIONS = ALL_PERMISSIONS
+
+__all__ = [
+    "AuthContext",
+    "AuthzHooks",
+    "Permissions",
+    "_ALL_PERMISSIONS",
+    "build_authz_hooks",
+    "build_permission_provider",
+    "build_policy_chain_builder",
+    "get_auth_context",
+    "get_authz_hooks",
+    "get_default_authz_hooks",
+]

backend/app/plugins/auth/authorization/authentication.py

@@ -0,0 +1,43 @@
+"""Authentication helpers used by auth-plugin authorization decorators."""
+
+from __future__ import annotations
+
+from fastapi import Request
+
+from app.plugins.auth.authorization.providers import PermissionProvider, default_permission_provider
+from app.plugins.auth.authorization.types import AuthContext
+
+
+def get_auth_context(request: Request) -> AuthContext | None:
+    """Get AuthContext, preferring Starlette-style request.auth."""
+
+    auth = request.scope.get("auth")
+    if isinstance(auth, AuthContext):
+        return auth
+    return getattr(request.state, "auth", None)
+
+
+def set_auth_context(request: Request, auth_context: AuthContext) -> AuthContext:
+    """Persist AuthContext on the standard request surfaces."""
+
+    request.scope["auth"] = auth_context
+    request.state.auth = auth_context
+    return auth_context
+
+
+async def authenticate_request(
+    request: Request,
+    *,
+    permission_provider: PermissionProvider = default_permission_provider,
+) -> AuthContext:
+    """Authenticate request and build AuthContext."""
+
+    from app.plugins.auth.security.dependencies import get_optional_user_from_request
+
+    user = await get_optional_user_from_request(request)
+    if user is None:
+        return AuthContext(user=None, permissions=[])
+    return AuthContext(user=user, permissions=permission_provider(user))
+
+
+__all__ = ["authenticate_request", "get_auth_context", "set_auth_context"]

backend/app/plugins/auth/authorization/authorization.py

@@ -0,0 +1,84 @@
+"""Authorization requirement and policy evaluation helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import HTTPException, Request
+
+from app.plugins.auth.authorization.policies import require_thread_owner
+from app.plugins.auth.authorization.types import AuthContext
+
+
+@dataclass(frozen=True)
+class PermissionRequirement:
+    """Authorization requirement for a single route action."""
+
+    resource: str
+    action: str
+    owner_check: bool = False
+    require_existing: bool = False
+
+    @property
+    def permission(self) -> str:
+        return f"{self.resource}:{self.action}"
+
+
+PolicyEvaluator = Callable[[Request, AuthContext, PermissionRequirement, Mapping[str, Any]], Awaitable[None]]
+
+
+def ensure_authenticated(auth: AuthContext) -> None:
+    if not auth.is_authenticated:
+        raise HTTPException(status_code=401, detail="Authentication required")
+
+
+def ensure_capability(auth: AuthContext, requirement: PermissionRequirement) -> None:
+    if not auth.has_permission(requirement.resource, requirement.action):
+        raise HTTPException(status_code=403, detail=f"Permission denied: {requirement.permission}")
+
+
+async def evaluate_owner_policy(
+    request: Request,
+    auth: AuthContext,
+    requirement: PermissionRequirement,
+    route_params: Mapping[str, Any],
+) -> None:
+    if not requirement.owner_check:
+        return
+
+    thread_id = route_params.get("thread_id")
+    if thread_id is None:
+        raise ValueError("require_permission with owner_check=True requires 'thread_id' parameter")
+
+    await require_thread_owner(
+        request,
+        auth,
+        thread_id=thread_id,
+        require_existing=requirement.require_existing,
+    )
+
+
+async def evaluate_requirement(
+    request: Request,
+    auth: AuthContext,
+    requirement: PermissionRequirement,
+    route_params: Mapping[str, Any],
+    *,
+    policy_evaluators: tuple[PolicyEvaluator, ...],
+) -> None:
+    ensure_authenticated(auth)
+    ensure_capability(auth, requirement)
+    for evaluator in policy_evaluators:
+        await evaluator(request, auth, requirement, route_params)
+
+
+__all__ = [
+    "PermissionRequirement",
+    "PolicyEvaluator",
+    "ensure_authenticated",
+    "ensure_capability",
+    "evaluate_owner_policy",
+    "evaluate_requirement",
+]

backend/app/plugins/auth/authorization/hooks.py

@@ -0,0 +1,62 @@
+"""Auth-plugin authz extension hooks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import Request
+
+from app.plugins.auth.authorization.providers import PermissionProvider, default_permission_provider
+from app.plugins.auth.authorization.registry import PolicyChainBuilder, build_default_policy_evaluators
+
+
+@dataclass(frozen=True)
+class AuthzHooks:
+    """Extension hooks for permission and policy resolution."""
+
+    permission_provider: PermissionProvider = default_permission_provider
+    policy_chain_builder: PolicyChainBuilder = build_default_policy_evaluators
+
+
+DEFAULT_AUTHZ_HOOKS = AuthzHooks()
+
+
+def get_default_authz_hooks() -> AuthzHooks:
+    return DEFAULT_AUTHZ_HOOKS
+
+
+def get_authz_hooks(request: Request | Any | None = None) -> AuthzHooks:
+    if request is not None:
+        app = getattr(request, "app", None)
+        state = getattr(app, "state", None)
+        hooks = getattr(state, "authz_hooks", None)
+        if isinstance(hooks, AuthzHooks):
+            return hooks
+    return DEFAULT_AUTHZ_HOOKS
+
+
+def build_permission_provider() -> PermissionProvider:
+    return default_permission_provider
+
+
+def build_policy_chain_builder() -> PolicyChainBuilder:
+    return build_default_policy_evaluators
+
+
+def build_authz_hooks() -> AuthzHooks:
+    return AuthzHooks(
+        permission_provider=build_permission_provider(),
+        policy_chain_builder=build_policy_chain_builder(),
+    )
+
+
+__all__ = [
+    "AuthzHooks",
+    "DEFAULT_AUTHZ_HOOKS",
+    "build_authz_hooks",
+    "build_permission_provider",
+    "build_policy_chain_builder",
+    "get_authz_hooks",
+    "get_default_authz_hooks",
+]

backend/app/plugins/auth/authorization/policies.py

@@ -0,0 +1,101 @@
+"""Authorization policies for resource ownership and access checks."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import HTTPException, Request
+
+from app.plugins.auth.authorization.types import AuthContext
+
+
+def _get_thread_owner_id(thread_meta: Any) -> str | None:
+    owner_id = getattr(thread_meta, "user_id", None)
+    if owner_id is not None:
+        return str(owner_id)
+
+    metadata = getattr(thread_meta, "metadata", None) or {}
+    metadata_owner_id = metadata.get("user_id")
+    if metadata_owner_id is not None:
+        return str(metadata_owner_id)
+    return None
+
+
+async def _thread_exists_via_legacy_sources(request: Request, auth: AuthContext, *, thread_id: str) -> bool:
+    from app.gateway.dependencies.repositories import get_run_repository
+
+    principal_id = auth.principal_id
+    run_store = get_run_repository(request)
+    runs = await run_store.list_by_thread(
+        thread_id,
+        limit=1,
+        user_id=principal_id,
+    )
+    if runs:
+        return True
+
+    checkpointer = getattr(request.app.state, "checkpointer", None)
+    if checkpointer is None:
+        return False
+
+    checkpoint_tuple = await checkpointer.aget_tuple(
+        {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
+    )
+    return checkpoint_tuple is not None
+
+
+async def require_thread_owner(
+    request: Request,
+    auth: AuthContext,
+    *,
+    thread_id: str,
+    require_existing: bool,
+) -> None:
+    """Ensure the current user owns the thread referenced by ``thread_id``."""
+
+    from app.gateway.dependencies.repositories import get_thread_meta_repository
+
+    thread_repo = get_thread_meta_repository(request)
+    thread_meta = await thread_repo.get_thread_meta(thread_id)
+    if thread_meta is None:
+        allowed = not require_existing
+        if not allowed:
+            allowed = await _thread_exists_via_legacy_sources(request, auth, thread_id=thread_id)
+    else:
+        owner_id = _get_thread_owner_id(thread_meta)
+        allowed = owner_id in (None, str(auth.user.id))
+
+    if not allowed:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Thread {thread_id} not found",
+        )
+
+
+async def require_run_owner(
+    request: Request,
+    auth: AuthContext,
+    *,
+    thread_id: str,
+    run_id: str,
+    require_existing: bool,
+) -> None:
+    """Ensure the current user owns the run referenced by ``run_id``."""
+
+    from app.gateway.dependencies import get_run_repository
+
+    run_store = get_run_repository(request)
+    run = await run_store.get(run_id)
+    if run is None:
+        allowed = not require_existing
+    else:
+        allowed = run.get("thread_id") == thread_id
+
+    if not allowed:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Run {run_id} not found",
+        )
+
+
+__all__ = ["require_run_owner", "require_thread_owner"]

backend/app/plugins/auth/authorization/providers.py

@@ -0,0 +1,18 @@
+"""Default permission provider hooks for auth-plugin authorization."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from app.plugins.auth.authorization.types import ALL_PERMISSIONS
+
+PermissionProvider = Callable[[object], list[str]]
+
+
+def default_permission_provider(user: object) -> list[str]:
+    """Return the current static permission set for an authenticated user."""
+
+    return list(ALL_PERMISSIONS)
+
+
+__all__ = ["PermissionProvider", "default_permission_provider"]

backend/app/plugins/auth/authorization/registry.py

@@ -0,0 +1,23 @@
+"""Registry/build helpers for default authorization evaluators."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from app.plugins.auth.authorization.authorization import PolicyEvaluator
+
+
+PolicyChainBuilder = Callable[[], tuple["PolicyEvaluator", ...]]
+
+
+def build_default_policy_evaluators() -> tuple["PolicyEvaluator", ...]:
+    """Return the default policy chain for auth-plugin authorization."""
+
+    from app.plugins.auth.authorization.authorization import evaluate_owner_policy
+
+    return (evaluate_owner_policy,)
+
+
+__all__ = ["PolicyChainBuilder", "build_default_policy_evaluators"]

backend/app/plugins/auth/authorization/types.py

@@ -0,0 +1,67 @@
+"""Authorization context and capability constants for the auth plugin."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import HTTPException
+
+if TYPE_CHECKING:
+    from app.plugins.auth.domain.models import User
+
+
+class Permissions:
+    """Permission constants for resource:action format."""
+
+    THREADS_READ = "threads:read"
+    THREADS_WRITE = "threads:write"
+    THREADS_DELETE = "threads:delete"
+
+    RUNS_CREATE = "runs:create"
+    RUNS_READ = "runs:read"
+    RUNS_CANCEL = "runs:cancel"
+
+
+class AuthContext:
+    """Authentication context for the current request."""
+
+    __slots__ = ("user", "permissions")
+
+    def __init__(self, user: User | None = None, permissions: list[str] | None = None):
+        self.user = user
+        self.permissions = permissions or []
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self.user is not None
+
+    @property
+    def principal_id(self) -> str | None:
+        if self.user is None:
+            return None
+        return str(self.user.id)
+
+    @property
+    def capabilities(self) -> tuple[str, ...]:
+        return tuple(self.permissions)
+
+    def has_permission(self, resource: str, action: str) -> bool:
+        return f"{resource}:{action}" in self.permissions
+
+    def require_user(self) -> User:
+        if not self.user:
+            raise HTTPException(status_code=401, detail="Authentication required")
+        return self.user
+
+
+ALL_PERMISSIONS: list[str] = [
+    Permissions.THREADS_READ,
+    Permissions.THREADS_WRITE,
+    Permissions.THREADS_DELETE,
+    Permissions.RUNS_CREATE,
+    Permissions.RUNS_READ,
+    Permissions.RUNS_CANCEL,
+]
+
+
+__all__ = ["ALL_PERMISSIONS", "AuthContext", "Permissions"]

backend/app/plugins/auth/domain/__init__.py

@@ -0,0 +1,28 @@
+"""Domain layer for the auth plugin."""
+
+from app.plugins.auth.domain.config import AuthConfig, load_auth_config_from_env
+from app.plugins.auth.domain.errors import AuthErrorCode, AuthErrorResponse, TokenError, token_error_to_code
+from app.plugins.auth.domain.jwt import TokenPayload, create_access_token, decode_token
+from app.plugins.auth.domain.models import User, UserResponse
+from app.plugins.auth.domain.password import hash_password, hash_password_async, verify_password, verify_password_async
+from app.plugins.auth.domain.service import AuthService, AuthServiceError
+
+__all__ = [
+    "AuthConfig",
+    "AuthErrorCode",
+    "AuthErrorResponse",
+    "AuthService",
+    "AuthServiceError",
+    "TokenError",
+    "TokenPayload",
+    "User",
+    "UserResponse",
+    "create_access_token",
+    "decode_token",
+    "hash_password",
+    "hash_password_async",
+    "load_auth_config_from_env",
+    "token_error_to_code",
+    "verify_password",
+    "verify_password_async",
+]

backend/app/plugins/auth/domain/config.py

@@ -0,0 +1,42 @@
+"""Auth configuration schema and environment loader."""
+
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field
+
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+
+class AuthConfig(BaseModel):
+    """JWT and auth-related configuration."""
+
+    jwt_secret: str = Field(..., description="Secret key for JWT signing. MUST be set via AUTH_JWT_SECRET.")
+    token_expiry_days: int = Field(default=7, ge=1, le=30)
+    oauth_github_client_id: str | None = Field(default=None)
+    oauth_github_client_secret: str | None = Field(default=None)
+
+
+def load_auth_config_from_env() -> AuthConfig:
+    """Build an auth config from environment variables."""
+
+    jwt_secret = os.environ.get("AUTH_JWT_SECRET")
+    if not jwt_secret:
+        jwt_secret = secrets.token_urlsafe(32)
+        os.environ["AUTH_JWT_SECRET"] = jwt_secret
+        logger.warning(
+            "⚠ AUTH_JWT_SECRET is not set — using an auto-generated ephemeral secret. "
+            "Sessions will be invalidated on restart. "
+            "For production, add AUTH_JWT_SECRET to your .env file: "
+            'python -c "import secrets; print(secrets.token_urlsafe(32))"'
+        )
+    return AuthConfig(jwt_secret=jwt_secret)
+
+
+__all__ = ["AuthConfig", "load_auth_config_from_env"]

backend/app/plugins/auth/domain/errors.py

@@ -0,0 +1,33 @@
+"""Typed error definitions for auth plugin."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+
+class AuthErrorCode(StrEnum):
+    INVALID_CREDENTIALS = "invalid_credentials"
+    TOKEN_EXPIRED = "token_expired"
+    TOKEN_INVALID = "token_invalid"
+    USER_NOT_FOUND = "user_not_found"
+    EMAIL_ALREADY_EXISTS = "email_already_exists"
+    PROVIDER_NOT_FOUND = "provider_not_found"
+    NOT_AUTHENTICATED = "not_authenticated"
+    SYSTEM_ALREADY_INITIALIZED = "system_already_initialized"
+
+
+class TokenError(StrEnum):
+    EXPIRED = "expired"
+    INVALID_SIGNATURE = "invalid_signature"
+    MALFORMED = "malformed"
+
+
+class AuthErrorResponse(BaseModel):
+    code: AuthErrorCode
+    message: str
+
+
+def token_error_to_code(err: TokenError) -> AuthErrorCode:
+    if err == TokenError.EXPIRED:
+        return AuthErrorCode.TOKEN_EXPIRED
+    return AuthErrorCode.TOKEN_INVALID

backend/app/plugins/auth/domain/jwt.py

@@ -0,0 +1,37 @@
+"""JWT token creation and verification."""
+
+from datetime import UTC, datetime, timedelta
+
+import jwt
+from pydantic import BaseModel
+
+from app.plugins.auth.domain.errors import TokenError
+from app.plugins.auth.runtime.config_state import get_auth_config
+
+
+class TokenPayload(BaseModel):
+    sub: str
+    exp: datetime
+    iat: datetime | None = None
+    ver: int = 0
+
+
+def create_access_token(user_id: str, expires_delta: timedelta | None = None, token_version: int = 0) -> str:
+    config = get_auth_config()
+    expiry = expires_delta or timedelta(days=config.token_expiry_days)
+    now = datetime.now(UTC)
+    payload = {"sub": user_id, "exp": now + expiry, "iat": now, "ver": token_version}
+    return jwt.encode(payload, config.jwt_secret, algorithm="HS256")
+
+
+def decode_token(token: str) -> TokenPayload | TokenError:
+    config = get_auth_config()
+    try:
+        payload = jwt.decode(token, config.jwt_secret, algorithms=["HS256"])
+        return TokenPayload(**payload)
+    except jwt.ExpiredSignatureError:
+        return TokenError.EXPIRED
+    except jwt.InvalidSignatureError:
+        return TokenError.INVALID_SIGNATURE
+    except jwt.PyJWTError:
+        return TokenError.MALFORMED

backend/app/plugins/auth/domain/models.py

@@ -0,0 +1,32 @@
+"""User Pydantic models for the auth plugin."""
+
+from datetime import UTC, datetime
+from typing import Literal
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
+
+
+def _utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+class User(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID = Field(default_factory=uuid4, description="Primary key")
+    email: EmailStr = Field(..., description="Unique email address")
+    password_hash: str | None = Field(None, description="bcrypt hash, nullable for OAuth users")
+    system_role: Literal["admin", "user"] = Field(default="user")
+    created_at: datetime = Field(default_factory=_utc_now)
+    oauth_provider: str | None = Field(None, description="e.g. 'github', 'google'")
+    oauth_id: str | None = Field(None, description="User ID from OAuth provider")
+    needs_setup: bool = Field(default=False, description="True for auto-created admin until setup completes")
+    token_version: int = Field(default=0, description="Incremented on password change to invalidate old JWTs")
+
+
+class UserResponse(BaseModel):
+    id: str
+    email: str
+    system_role: Literal["admin", "user"]
+    needs_setup: bool = False

backend/app/plugins/auth/domain/password.py

@@ -0,0 +1,21 @@
+"""Password hashing utilities using bcrypt directly."""
+
+import asyncio
+
+import bcrypt
+
+
+def hash_password(password: str) -> str:
+    return bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    return bcrypt.checkpw(plain_password.encode("utf-8"), hashed_password.encode("utf-8"))
+
+
+async def hash_password_async(password: str) -> str:
+    return await asyncio.to_thread(hash_password, password)
+
+
+async def verify_password_async(plain_password: str, hashed_password: str) -> bool:
+    return await asyncio.to_thread(verify_password, plain_password, hashed_password)

backend/app/plugins/auth/domain/service.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from http import HTTPStatus
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from app.plugins.auth.domain.errors import AuthErrorCode
+from app.plugins.auth.domain.models import User
+from app.plugins.auth.domain.password import hash_password_async, verify_password_async
+from app.plugins.auth.storage import DbUserRepository, UserCreate
+from app.plugins.auth.storage.contracts import User as StoreUser
+
+
+@dataclass(slots=True)
+class AuthServiceError(Exception):
+    code: AuthErrorCode
+    message: str
+    status_code: int
+
+
+def _to_auth_user(user: StoreUser) -> User:
+    return User(
+        id=UUID(user.id),
+        email=user.email,
+        password_hash=user.password_hash,
+        system_role=user.system_role,  # type: ignore[arg-type]
+        created_at=user.created_time,
+        oauth_provider=user.oauth_provider,
+        oauth_id=user.oauth_id,
+        needs_setup=user.needs_setup,
+        token_version=user.token_version,
+    )
+
+
+def _to_store_user(user: User) -> StoreUser:
+    return StoreUser(
+        id=str(user.id),
+        email=user.email,
+        password_hash=user.password_hash,
+        system_role=user.system_role,
+        oauth_provider=user.oauth_provider,
+        oauth_id=user.oauth_id,
+        needs_setup=user.needs_setup,
+        token_version=user.token_version,
+        created_time=user.created_at,
+        updated_time=None,
+    )
+
+
+class AuthService:
+    def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
+        self._session_factory = session_factory
+
+    async def login_local(self, email: str, password: str) -> User:
+        async with self._session_factory() as session:
+            repo = DbUserRepository(session)
+            user = await repo.get_user_by_email(email)
+            if user is None or user.password_hash is None:
+                raise AuthServiceError(
+                    code=AuthErrorCode.INVALID_CREDENTIALS,
+                    message="Incorrect email or password",
+                    status_code=HTTPStatus.UNAUTHORIZED,
+                )
+            if not await verify_password_async(password, user.password_hash):
+                raise AuthServiceError(
+                    code=AuthErrorCode.INVALID_CREDENTIALS,
+                    message="Incorrect email or password",
+                    status_code=HTTPStatus.UNAUTHORIZED,
+                )
+            return _to_auth_user(user)
+
+    async def register(self, email: str, password: str) -> User:
+        async with self._session_factory() as session:
+            repo = DbUserRepository(session)
+            try:
+                user = await repo.create_user(
+                    UserCreate(
+                        email=email,
+                        password_hash=await hash_password_async(password),
+                        system_role="user",
+                    )
+                )
+                await session.commit()
+            except ValueError as exc:
+                await session.rollback()
+                raise AuthServiceError(
+                    code=AuthErrorCode.EMAIL_ALREADY_EXISTS,
+                    message="Email already registered",
+                    status_code=HTTPStatus.BAD_REQUEST,
+                ) from exc
+            return _to_auth_user(user)
+
+    async def change_password(
+        self,
+        user: User | StoreUser,
+        *,
+        current_password: str,
+        new_password: str,
+        new_email: str | None = None,
+    ) -> User:
+        if user.password_hash is None:
+            raise AuthServiceError(
+                code=AuthErrorCode.INVALID_CREDENTIALS,
+                message="OAuth users cannot change password",
+                status_code=HTTPStatus.BAD_REQUEST,
+            )
+        if not await verify_password_async(current_password, user.password_hash):
+            raise AuthServiceError(
+                code=AuthErrorCode.INVALID_CREDENTIALS,
+                message="Current password is incorrect",
+                status_code=HTTPStatus.BAD_REQUEST,
+            )
+
+        async with self._session_factory() as session:
+            repo = DbUserRepository(session)
+            updated_email = user.email
+            if new_email is not None:
+                existing = await repo.get_user_by_email(new_email)
+                if existing and existing.id != str(user.id):
+                    raise AuthServiceError(
+                        code=AuthErrorCode.EMAIL_ALREADY_EXISTS,
+                        message="Email already in use",
+                        status_code=HTTPStatus.BAD_REQUEST,
+                    )
+                updated_email = new_email
+
+            updated_user = user.model_copy(
+                update={
+                    "email": updated_email,
+                    "password_hash": await hash_password_async(new_password),
+                    "token_version": user.token_version + 1,
+                    "needs_setup": False if user.needs_setup and new_email is not None else user.needs_setup,
+                }
+            )
+
+            updated = await repo.update_user(_to_store_user(_to_auth_user(updated_user) if isinstance(updated_user, StoreUser) else updated_user))
+            await session.commit()
+            return _to_auth_user(updated)
+
+    async def get_setup_status(self) -> bool:
+        async with self._session_factory() as session:
+            repo = DbUserRepository(session)
+            admin_count = await repo.count_admin_users()
+            return admin_count == 0
+
+    async def initialize_admin(self, email: str, password: str) -> User:
+        async with self._session_factory() as session:
+            repo = DbUserRepository(session)
+            admin_count = await repo.count_admin_users()
+            if admin_count > 0:
+                raise AuthServiceError(
+                    code=AuthErrorCode.SYSTEM_ALREADY_INITIALIZED,
+                    message="System already initialized",
+                    status_code=HTTPStatus.CONFLICT,
+                )
+            try:
+                user = await repo.create_user(
+                    UserCreate(
+                        email=email,
+                        password_hash=await hash_password_async(password),
+                        system_role="admin",
+                        needs_setup=False,
+                    )
+                )
+                await session.commit()
+            except ValueError as exc:
+                await session.rollback()
+                raise AuthServiceError(
+                    code=AuthErrorCode.SYSTEM_ALREADY_INITIALIZED,
+                    message="System already initialized",
+                    status_code=HTTPStatus.CONFLICT,
+                ) from exc
+            return _to_auth_user(user)

backend/app/plugins/auth/injection/__init__.py

@@ -0,0 +1,17 @@
+"""Config-driven route authorization injection for the auth plugin."""
+
+from app.plugins.auth.injection.registry_loader import (
+    RoutePolicyRegistry,
+    RoutePolicySpec,
+    load_route_policy_registry,
+)
+from app.plugins.auth.injection.route_injector import install_route_guards
+from app.plugins.auth.injection.validation import validate_route_policy_registry
+
+__all__ = [
+    "RoutePolicyRegistry",
+    "RoutePolicySpec",
+    "install_route_guards",
+    "load_route_policy_registry",
+    "validate_route_policy_registry",
+]

backend/app/plugins/auth/injection/registry_loader.py

@@ -0,0 +1,112 @@
+"""Load auth route policies from the plugin's YAML registry."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from starlette.routing import compile_path
+import yaml
+
+_POLICY_FILE = Path(__file__).resolve().parents[1] / "route_policies.yaml"
+
+
+@dataclass(frozen=True)
+class RoutePolicySpec:
+    public: bool = False
+    capability: str | None = None
+    policies: tuple[str, ...] = ()
+    require_existing: bool = True
+
+
+@dataclass(frozen=True)
+class RoutePolicyEntry:
+    method: str
+    path: str
+    spec: RoutePolicySpec
+    path_regex: object = field(repr=False)
+
+    def matches_request(self, method: str, path: str) -> bool:
+        if self.method != method.upper():
+            return False
+        return self.path_regex.match(path) is not None
+
+
+class RoutePolicyRegistry:
+    def __init__(self, entries: list[RoutePolicyEntry]) -> None:
+        self._entries = entries
+        self._specs = {(entry.method, entry.path): entry.spec for entry in entries}
+
+    def get(self, method: str, path_template: str) -> RoutePolicySpec | None:
+        return self._specs.get((method.upper(), path_template))
+
+    def has(self, method: str, path_template: str) -> bool:
+        return (method.upper(), path_template) in self._specs
+
+    def match_request(self, method: str, path: str) -> RoutePolicySpec | None:
+        normalized_method = method.upper()
+        for entry in self._entries:
+            if entry.matches_request(normalized_method, path):
+                return entry.spec
+        return None
+
+    def is_public_request(self, method: str, path: str) -> bool:
+        spec = self.match_request(method, path)
+        return bool(spec and spec.public)
+
+    @property
+    def keys(self) -> set[tuple[str, str]]:
+        return set(self._specs)
+
+
+def _normalize_methods(item: dict) -> tuple[str, ...]:
+    methods = item.get("methods")
+    if methods is None:
+        methods = [item["method"]]
+    if isinstance(methods, str):
+        methods = [methods]
+    return tuple(str(method).upper() for method in methods)
+
+
+def _build_spec(item: dict) -> RoutePolicySpec:
+    return RoutePolicySpec(
+        public=bool(item.get("public", False)),
+        capability=item.get("capability"),
+        policies=tuple(item.get("policies", [])),
+        require_existing=bool(item.get("require_existing", True)),
+    )
+
+
+def load_route_policy_registry() -> RoutePolicyRegistry:
+    payload = yaml.safe_load(_POLICY_FILE.read_text(encoding="utf-8")) or {}
+    raw_routes: list[dict] = []
+    for section, entries in payload.items():
+        if section == "routes":
+            if isinstance(entries, list):
+                raw_routes.extend(entries)
+            continue
+        if not isinstance(entries, list):
+            continue
+        for item in entries:
+            normalized = dict(item)
+            if section == "public":
+                normalized["public"] = True
+            raw_routes.append(normalized)
+    entries: list[RoutePolicyEntry] = []
+    for item in raw_routes:
+        path = str(item["path"])
+        spec = _build_spec(item)
+        path_regex, _, _ = compile_path(path)
+        for method in _normalize_methods(item):
+            entries.append(
+                RoutePolicyEntry(
+                    method=method,
+                    path=path,
+                    spec=spec,
+                    path_regex=path_regex,
+                )
+            )
+    return RoutePolicyRegistry(entries)
+
+
+__all__ = ["RoutePolicyRegistry", "RoutePolicySpec", "load_route_policy_registry"]

backend/app/plugins/auth/injection/route_guard.py

@@ -0,0 +1,102 @@
+"""Runtime route guard backed by the auth plugin's route policy registry."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from fastapi import HTTPException, Request
+
+from app.plugins.auth.authorization.authentication import (
+    authenticate_request,
+    get_auth_context,
+    set_auth_context,
+)
+from app.plugins.auth.authorization.authorization import ensure_authenticated
+from app.plugins.auth.authorization.hooks import get_authz_hooks
+from app.plugins.auth.authorization.policies import require_run_owner, require_thread_owner
+from app.plugins.auth.injection.registry_loader import RoutePolicyRegistry, RoutePolicySpec
+
+PolicyGuard = Callable[[Request, RoutePolicySpec], Awaitable[None]]
+
+
+async def _check_capability(request: Request, spec: RoutePolicySpec) -> None:
+    if not spec.capability:
+        return
+
+    auth = get_auth_context(request)
+    if auth is None:
+        raise HTTPException(status_code=500, detail="Missing auth context")
+
+    if ":" not in spec.capability:
+        raise RuntimeError(f"Invalid capability format: {spec.capability}")
+    resource, action = spec.capability.split(":", 1)
+    if not auth.has_permission(resource, action):
+        raise HTTPException(status_code=403, detail=f"Permission denied: {spec.capability}")
+
+
+async def _guard_thread_owner(request: Request, spec: RoutePolicySpec) -> None:
+    auth = get_auth_context(request)
+    if auth is None:
+        raise HTTPException(status_code=500, detail="Missing auth context")
+    thread_id = request.path_params.get("thread_id")
+    if not isinstance(thread_id, str):
+        raise RuntimeError("owner:thread policy requires thread_id path parameter")
+    await require_thread_owner(request, auth, thread_id=thread_id, require_existing=spec.require_existing)
+
+
+async def _guard_run_owner(request: Request, spec: RoutePolicySpec) -> None:
+    auth = get_auth_context(request)
+    if auth is None:
+        raise HTTPException(status_code=500, detail="Missing auth context")
+    thread_id = request.path_params.get("thread_id")
+    run_id = request.path_params.get("run_id")
+    if not isinstance(thread_id, str) or not isinstance(run_id, str):
+        raise RuntimeError("owner:run policy requires thread_id and run_id path parameters")
+    await require_run_owner(
+        request,
+        auth,
+        thread_id=thread_id,
+        run_id=run_id,
+        require_existing=spec.require_existing,
+    )
+
+
+_POLICY_GUARDS: dict[str, PolicyGuard] = {
+    "owner:thread": _guard_thread_owner,
+    "owner:run": _guard_run_owner,
+}
+
+
+async def enforce_route_policy(request: Request) -> None:
+    registry = getattr(request.app.state, "auth_route_policy_registry", None)
+    if not isinstance(registry, RoutePolicyRegistry):
+        raise RuntimeError("Auth route policy registry is not configured")
+
+    route = request.scope.get("route")
+    path_template = getattr(route, "path", None)
+    if not isinstance(path_template, str):
+        raise RuntimeError("Unable to resolve route path for authorization")
+
+    spec = registry.get(request.method, path_template)
+    if spec is None:
+        raise RuntimeError(f"Missing auth route policy for {request.method} {path_template}")
+    if spec.public:
+        return
+
+    auth = get_auth_context(request)
+    if auth is None:
+        hooks = get_authz_hooks(request)
+        auth = await authenticate_request(request, permission_provider=hooks.permission_provider)
+        set_auth_context(request, auth)
+
+    ensure_authenticated(auth)
+    await _check_capability(request, spec)
+
+    for policy_name in spec.policies:
+        guard = _POLICY_GUARDS.get(policy_name)
+        if guard is None:
+            raise RuntimeError(f"Unknown route policy guard: {policy_name}")
+        await guard(request, spec)
+
+
+__all__ = ["enforce_route_policy"]

backend/app/plugins/auth/injection/route_injector.py

@@ -0,0 +1,39 @@
+"""Inject config-driven auth guards into FastAPI routes."""
+
+from __future__ import annotations
+
+from fastapi import Depends, FastAPI
+from fastapi.dependencies.utils import get_dependant, get_flat_dependant, get_parameterless_sub_dependant
+from fastapi.routing import APIRoute, _should_embed_body_fields, get_body_field, request_response
+
+from app.plugins.auth.injection.route_guard import enforce_route_policy
+
+
+def _rebuild_route(route: APIRoute) -> None:
+    route.dependant = get_dependant(path=route.path_format, call=route.endpoint, scope="function")
+    for depends in route.dependencies[::-1]:
+        route.dependant.dependencies.insert(
+            0,
+            get_parameterless_sub_dependant(depends=depends, path=route.path_format),
+        )
+    route._flat_dependant = get_flat_dependant(route.dependant)
+    route._embed_body_fields = _should_embed_body_fields(route._flat_dependant.body_params)
+    route.body_field = get_body_field(
+        flat_dependant=route._flat_dependant,
+        name=route.unique_id,
+        embed_body_fields=route._embed_body_fields,
+    )
+    route.app = request_response(route.get_route_handler())
+
+
+def install_route_guards(app: FastAPI) -> None:
+    for route in app.routes:
+        if not isinstance(route, APIRoute):
+            continue
+        if any(getattr(dependency, "dependency", None) is enforce_route_policy for dependency in route.dependencies):
+            continue
+        route.dependencies.append(Depends(enforce_route_policy))
+        _rebuild_route(route)
+
+
+__all__ = ["install_route_guards"]

backend/app/plugins/auth/injection/validation.py

@@ -0,0 +1,38 @@
+"""Validation helpers for config-driven auth route policies."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+from fastapi.routing import APIRoute
+
+from app.plugins.auth.injection.registry_loader import RoutePolicyRegistry
+
+_IGNORED_METHODS = frozenset({"HEAD", "OPTIONS"})
+
+
+def _iter_route_keys(app: FastAPI) -> set[tuple[str, str]]:
+    keys: set[tuple[str, str]] = set()
+    for route in app.routes:
+        if not isinstance(route, APIRoute):
+            continue
+        for method in route.methods:
+            if method in _IGNORED_METHODS:
+                continue
+            keys.add((method, route.path))
+    return keys
+
+
+def validate_route_policy_registry(app: FastAPI, registry: RoutePolicyRegistry) -> None:
+    route_keys = _iter_route_keys(app)
+    missing = sorted(route_keys - registry.keys)
+    extra = sorted(registry.keys - route_keys)
+    problems: list[str] = []
+    if missing:
+        problems.append("Missing route policy entries:\n" + "\n".join(f"  - {method} {path}" for method, path in missing))
+    if extra:
+        problems.append("Unknown route policy entries:\n" + "\n".join(f"  - {method} {path}" for method, path in extra))
+    if problems:
+        raise RuntimeError("\n\n".join(problems))
+
+
+__all__ = ["validate_route_policy_registry"]

backend/app/plugins/auth/ops/__init__.py

@@ -0,0 +1,6 @@
+"""Operational tooling for the auth plugin."""
+
+from app.plugins.auth.ops.credential_file import write_initial_credentials
+from app.plugins.auth.ops.reset_admin import main
+
+__all__ = ["main", "write_initial_credentials"]

backend/app/plugins/auth/ops/credential_file.py

@@ -0,0 +1,28 @@
+"""Write initial admin credentials to a restricted file instead of logs."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from deerflow.config.paths import get_paths
+
+_CREDENTIAL_FILENAME = "admin_initial_credentials.txt"
+
+
+def write_initial_credentials(email: str, password: str, *, label: str = "initial") -> Path:
+    target = get_paths().base_dir / _CREDENTIAL_FILENAME
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    content = (
+        f"# DeerFlow admin {label} credentials\n# This file is generated on first boot or password reset.\n# Change the password after login via Settings -> Account,\n# then delete this file.\n#\nemail: {email}\npassword: {password}\n"
+    )
+
+    fd = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        fh.write(content)
+
+    return target.resolve()
+
+
+__all__ = ["write_initial_credentials"]

backend/app/plugins/auth/ops/reset_admin.py

@@ -0,0 +1,74 @@
+"""CLI tool to reset an admin password."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import secrets
+import sys
+
+from sqlalchemy import select
+
+from app.plugins.auth.domain.password import hash_password
+from app.plugins.auth.ops.credential_file import write_initial_credentials
+from app.plugins.auth.storage import DbUserRepository
+from app.plugins.auth.storage.models import User as UserModel
+
+
+async def _run(email: str | None) -> int:
+    from store.persistence import create_persistence
+
+    app_persistence = await create_persistence()
+    await app_persistence.setup()
+    try:
+        if email:
+            async with app_persistence.session_factory() as session:
+                repo = DbUserRepository(session)
+                user = await repo.get_user_by_email(email)
+        else:
+            async with app_persistence.session_factory() as session:
+                stmt = select(UserModel).where(UserModel.system_role == "admin").limit(1)
+                row = (await session.execute(stmt)).scalar_one_or_none()
+                if row is None:
+                    user = None
+                else:
+                    repo = DbUserRepository(session)
+                    user = await repo.get_user_by_id(row.id)
+
+        if user is None:
+            print(f"Error: user '{email}' not found." if email else "Error: no admin user found.", file=sys.stderr)
+            return 1
+
+        new_password = secrets.token_urlsafe(16)
+        updated_user = user.model_copy(
+            update={
+                "password_hash": hash_password(new_password),
+                "token_version": user.token_version + 1,
+                "needs_setup": True,
+            }
+        )
+        async with app_persistence.session_factory() as session:
+            repo = DbUserRepository(session)
+            await repo.update_user(updated_user)
+            await session.commit()
+
+        cred_path = write_initial_credentials(user.email, new_password, label="reset")
+        print(f"Password reset for: {user.email}")
+        print(f"Credentials written to: {cred_path} (mode 0600)")
+        print("Next login will require setup (new email + password).")
+        return 0
+    finally:
+        await app_persistence.aclose()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reset admin password")
+    parser.add_argument("--email", help="Admin email (default: first admin found)")
+    args = parser.parse_args()
+
+    exit_code = asyncio.run(_run(args.email))
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

backend/app/plugins/auth/plugin.toml

@@ -0,0 +1,18 @@
+[plugin]
+name = "auth"
+summary = "Cookie-based authentication and authorization"
+version = "0.1.0"
+description = "Owns DeerFlow authentication, authorization adapters, and auth storage definitions while reusing shared persistence infrastructure."
+author = "DeerFlow"
+tags = ["auth", "gateway", "session"]
+
+[capabilities]
+router = true
+middleware = true
+dependencies = true
+langgraph_adapter = true
+storage = true
+
+[storage]
+mode = "shared_infrastructure"
+notes = "This plugin owns its storage definitions and repositories but uses the application's shared engine and session factory."

backend/app/plugins/auth/route_policies.yaml

@@ -0,0 +1,204 @@
+public:
+  - method: POST
+    path: /api/v1/auth/login/local
+  - method: POST
+    path: /api/v1/auth/register
+  - method: POST
+    path: /api/v1/auth/logout
+  - method: GET
+    path: /api/v1/auth/setup-status
+  - method: POST
+    path: /api/v1/auth/initialize
+  - method: GET
+    path: /api/v1/auth/oauth/{provider}
+  - method: GET
+    path: /api/v1/auth/callback/{provider}
+  - method: GET
+    path: /docs
+
+auth:
+  - method: POST
+    path: /api/v1/auth/change-password
+  - method: GET
+    path: /api/v1/auth/me
+
+threads:
+  - method: POST
+    path: /api/threads
+    capability: threads:write
+  - method: POST
+    path: /api/threads/search
+    capability: threads:read
+  - method: DELETE
+    path: /api/threads/{thread_id}
+    capability: threads:delete
+    policies: [owner:thread]
+    require_existing: false
+  - method: GET
+    path: /api/threads/{thread_id}/state
+    capability: threads:read
+    policies: [owner:thread]
+  - method: POST
+    path: /api/threads/{thread_id}/state
+    capability: threads:write
+    policies: [owner:thread]
+  - method: POST
+    path: /api/threads/{thread_id}/history
+    capability: threads:read
+    policies: [owner:thread]
+
+runs:
+  - method: GET
+    path: /api/threads/{thread_id}/runs
+    capability: runs:read
+    policies: [owner:thread]
+  - method: GET
+    path: /api/threads/{thread_id}/runs/{run_id}
+    capability: runs:read
+    policies: [owner:run]
+  - method: GET
+    path: /api/threads/{thread_id}/runs/{run_id}/messages
+    capability: runs:read
+    policies: [owner:run]
+  - method: POST
+    path: /api/threads/{thread_id}/runs
+    capability: runs:create
+    policies: [owner:thread]
+  - method: POST
+    path: /api/threads/{thread_id}/runs/stream
+    capability: runs:create
+    policies: [owner:thread]
+  - method: POST
+    path: /api/threads/{thread_id}/runs/wait
+    capability: runs:create
+    policies: [owner:thread]
+  - method: POST
+    path: /api/threads/runs
+    capability: runs:create
+  - method: POST
+    path: /api/threads/runs/stream
+    capability: runs:create
+  - method: POST
+    path: /api/threads/runs/wait
+    capability: runs:create
+  - methods: [GET, POST]
+    path: /api/threads/{thread_id}/runs/{run_id}/stream
+    capability: runs:read
+    policies: [owner:run]
+  - method: GET
+    path: /api/threads/{thread_id}/runs/{run_id}/join
+    capability: runs:read
+    policies: [owner:run]
+  - method: POST
+    path: /api/threads/{thread_id}/runs/{run_id}/cancel
+    capability: runs:cancel
+    policies: [owner:run]
+  - method: DELETE
+    path: /api/threads/{thread_id}/runs/{run_id}
+    capability: runs:cancel
+    policies: [owner:run]
+
+feedback:
+  - method: PUT
+    path: /api/threads/{thread_id}/runs/{run_id}/feedback
+    policies: [owner:run]
+  - method: POST
+    path: /api/threads/{thread_id}/runs/{run_id}/feedback
+    policies: [owner:run]
+  - method: GET
+    path: /api/threads/{thread_id}/runs/{run_id}/feedback
+    policies: [owner:run]
+  - method: GET
+    path: /api/threads/{thread_id}/runs/{run_id}/feedback/stats
+    policies: [owner:run]
+  - method: DELETE
+    path: /api/threads/{thread_id}/runs/{run_id}/feedback
+    policies: [owner:run]
+  - method: DELETE
+    path: /api/threads/{thread_id}/runs/{run_id}/feedback/{feedback_id}
+    policies: [owner:run]
+
+suggestions:
+  - method: POST
+    path: /api/threads/{thread_id}/suggestions
+    capability: threads:read
+    policies: [owner:thread]
+
+uploads:
+  - method: POST
+    path: /api/threads/{thread_id}/uploads
+    capability: threads:write
+    policies: [owner:thread]
+    require_existing: false
+  - method: GET
+    path: /api/threads/{thread_id}/uploads/list
+    capability: threads:read
+    policies: [owner:thread]
+  - method: DELETE
+    path: /api/threads/{thread_id}/uploads/{filename}
+    capability: threads:delete
+    policies: [owner:thread]
+
+artifacts:
+  - method: GET
+    path: /api/threads/{thread_id}/artifacts/{path:path}
+    capability: threads:read
+    policies: [owner:thread]
+
+agents:
+  - method: GET
+    path: /api/agents
+  - method: GET
+    path: /api/agents/check
+  - method: GET
+    path: /api/agents/{name}
+  - method: POST
+    path: /api/agents
+  - method: PUT
+    path: /api/agents/{name}
+  - method: GET
+    path: /api/user-profile
+  - method: PUT
+    path: /api/user-profile
+  - method: DELETE
+    path: /api/agents/{name}
+
+channels:
+  - method: GET
+    path: /api/channels/
+  - method: POST
+    path: /api/channels/{name}/restart
+
+mcp:
+  - method: GET
+    path: /api/mcp/config
+  - method: PUT
+    path: /api/mcp/config
+
+models:
+  - method: GET
+    path: /api/models
+  - method: GET
+    path: /api/models/{model_name}
+
+skills:
+  - method: GET
+    path: /api/skills
+  - method: POST
+    path: /api/skills/install
+  - method: GET
+    path: /api/skills/custom
+  - method: GET
+    path: /api/skills/custom/{skill_name}
+  - method: PUT
+    path: /api/skills/custom/{skill_name}
+  - method: DELETE
+    path: /api/skills/custom/{skill_name}
+  - method: GET
+    path: /api/skills/custom/{skill_name}/history
+  - method: POST
+    path: /api/skills/custom/{skill_name}/rollback
+  - method: GET
+    path: /api/skills/{skill_name}
+  - method: PUT
+    path: /api/skills/{skill_name}

backend/app/plugins/auth/runtime/__init__.py

@@ -0,0 +1,5 @@
+"""Runtime state utilities for the auth plugin."""
+
+from app.plugins.auth.runtime.config_state import get_auth_config, reset_auth_config, set_auth_config
+
+__all__ = ["get_auth_config", "reset_auth_config", "set_auth_config"]

backend/app/plugins/auth/runtime/config_state.py

@@ -0,0 +1,27 @@
+"""Runtime state holder for auth configuration."""
+
+from __future__ import annotations
+
+from app.plugins.auth.domain.config import AuthConfig, load_auth_config_from_env
+
+_auth_config: AuthConfig | None = None
+
+
+def get_auth_config() -> AuthConfig:
+    global _auth_config
+    if _auth_config is None:
+        _auth_config = load_auth_config_from_env()
+    return _auth_config
+
+
+def set_auth_config(config: AuthConfig) -> None:
+    global _auth_config
+    _auth_config = config
+
+
+def reset_auth_config() -> None:
+    global _auth_config
+    _auth_config = None
+
+
+__all__ = ["get_auth_config", "reset_auth_config", "set_auth_config"]

backend/app/plugins/auth/security/__init__.py

@@ -0,0 +1,47 @@
+"""Security layer for the auth plugin."""
+
+from app.plugins.auth.security.actor_context import (
+    bind_request_actor_context,
+    bind_user_actor_context,
+    resolve_request_user_id,
+)
+from app.plugins.auth.security.csrf import (
+    CSRF_COOKIE_NAME,
+    CSRF_HEADER_NAME,
+    CSRFMiddleware,
+    get_csrf_token,
+    is_secure_request,
+)
+from app.plugins.auth.security.dependencies import (
+    CurrentAuthService,
+    CurrentUserRepository,
+    get_auth_service,
+    get_current_user_from_request,
+    get_current_user_id,
+    get_optional_user_from_request,
+    get_user_repository,
+)
+from app.plugins.auth.security.langgraph import add_owner_filter, auth, authenticate
+from app.plugins.auth.security.middleware import AuthMiddleware
+
+__all__ = [
+    "CSRF_COOKIE_NAME",
+    "CSRF_HEADER_NAME",
+    "CSRFMiddleware",
+    "AuthMiddleware",
+    "CurrentAuthService",
+    "CurrentUserRepository",
+    "add_owner_filter",
+    "auth",
+    "authenticate",
+    "bind_request_actor_context",
+    "bind_user_actor_context",
+    "get_auth_service",
+    "get_csrf_token",
+    "get_current_user_from_request",
+    "get_current_user_id",
+    "get_optional_user_from_request",
+    "get_user_repository",
+    "is_secure_request",
+    "resolve_request_user_id",
+]

backend/app/plugins/auth/security/actor_context.py

@@ -0,0 +1,43 @@
+"""Auth-plugin bridge from request user to runtime actor context."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+
+from fastapi import Request
+
+from deerflow.runtime.actor_context import ActorContext, bind_actor_context, reset_actor_context
+
+
+def resolve_request_user_id(request: Request) -> str | None:
+    scope = getattr(request, "scope", None)
+    user = scope.get("user") if isinstance(scope, dict) else None
+    if user is None:
+        state = getattr(request, "state", None)
+        state_vars = vars(state) if state is not None and hasattr(state, "__dict__") else {}
+        user = state_vars.get("user")
+    user_id = getattr(user, "id", None)
+    if user_id is None:
+        return None
+    return str(user_id)
+
+
+@contextmanager
+def bind_request_actor_context(request: Request):
+    token = bind_actor_context(ActorContext(user_id=resolve_request_user_id(request)))
+    try:
+        yield
+    finally:
+        reset_actor_context(token)
+
+
+@contextmanager
+def bind_user_actor_context(user_id: str | None):
+    token = bind_actor_context(ActorContext(user_id=str(user_id) if user_id is not None else None))
+    try:
+        yield
+    finally:
+        reset_actor_context(token)
+
+
+__all__ = ["bind_request_actor_context", "bind_user_actor_context", "resolve_request_user_id"]

backend/app/plugins/auth/security/csrf.py

@@ -0,0 +1,106 @@
+"""CSRF protection middleware and helpers for cookie-based auth flows."""
+
+import secrets
+from collections.abc import Callable
+
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp
+
+CSRF_COOKIE_NAME = "csrf_token"
+CSRF_HEADER_NAME = "X-CSRF-Token"
+CSRF_TOKEN_LENGTH = 64  # bytes
+
+
+def is_secure_request(request: Request) -> bool:
+    """Detect whether the original client request was made over HTTPS."""
+    return request.headers.get("x-forwarded-proto", request.url.scheme) == "https"
+
+
+def generate_csrf_token() -> str:
+    """Generate a secure random CSRF token."""
+    return secrets.token_urlsafe(CSRF_TOKEN_LENGTH)
+
+
+def should_check_csrf(request: Request) -> bool:
+    """Determine if a request needs CSRF validation."""
+    if request.method not in ("POST", "PUT", "DELETE", "PATCH"):
+        return False
+
+    path = request.url.path.rstrip("/")
+    if path == "/api/v1/auth/me":
+        return False
+    return True
+
+
+_AUTH_EXEMPT_PATHS: frozenset[str] = frozenset(
+    {
+        "/api/v1/auth/login/local",
+        "/api/v1/auth/logout",
+        "/api/v1/auth/register",
+        "/api/v1/auth/initialize",
+    }
+)
+
+
+def is_auth_endpoint(request: Request) -> bool:
+    """Check if the request is to an auth endpoint."""
+    return request.url.path.rstrip("/") in _AUTH_EXEMPT_PATHS
+
+
+class CSRFMiddleware(BaseHTTPMiddleware):
+    """Implement CSRF protection using the double-submit cookie pattern."""
+
+    def __init__(self, app: ASGIApp) -> None:
+        super().__init__(app)
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        _is_auth = is_auth_endpoint(request)
+
+        if should_check_csrf(request) and not _is_auth:
+            cookie_token = request.cookies.get(CSRF_COOKIE_NAME)
+            header_token = request.headers.get(CSRF_HEADER_NAME)
+
+            if not cookie_token or not header_token:
+                return JSONResponse(
+                    status_code=403,
+                    content={"detail": "CSRF token missing. Include X-CSRF-Token header."},
+                )
+
+            if not secrets.compare_digest(cookie_token, header_token):
+                return JSONResponse(
+                    status_code=403,
+                    content={"detail": "CSRF token mismatch."},
+                )
+
+        response = await call_next(request)
+
+        if _is_auth and request.method == "POST":
+            csrf_token = generate_csrf_token()
+            response.set_cookie(
+                key=CSRF_COOKIE_NAME,
+                value=csrf_token,
+                httponly=False,
+                secure=is_secure_request(request),
+                samesite="strict",
+            )
+
+        return response
+
+
+def get_csrf_token(request: Request) -> str | None:
+    """Get the CSRF token from the current request's cookies."""
+    return request.cookies.get(CSRF_COOKIE_NAME)
+
+
+__all__ = [
+    "CSRF_COOKIE_NAME",
+    "CSRF_HEADER_NAME",
+    "CSRFMiddleware",
+    "generate_csrf_token",
+    "get_csrf_token",
+    "is_auth_endpoint",
+    "is_secure_request",
+    "should_check_csrf",
+]

backend/app/plugins/auth/security/dependencies.py

@@ -0,0 +1,119 @@
+"""Security dependency helpers for the auth plugin."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from app.plugins.auth.domain.errors import (
+    AuthErrorCode,
+    AuthErrorResponse,
+    TokenError,
+    token_error_to_code,
+)
+from app.plugins.auth.domain.jwt import decode_token
+from app.plugins.auth.domain.service import AuthService
+from app.plugins.auth.storage import DbUserRepository, UserRepositoryProtocol
+
+
+def _get_session_factory(request: Request) -> async_sessionmaker[AsyncSession] | None:
+    persistence = getattr(request.app.state, "persistence", None)
+    if persistence is None:
+        return None
+    return getattr(persistence, "session_factory", None)
+
+
+@asynccontextmanager
+async def _auth_session(request: Request) -> AsyncIterator[AsyncSession]:
+    injected = getattr(request.state, "_auth_session", None)
+    if injected is not None:
+        yield injected
+        return
+
+    session_factory = _get_session_factory(request)
+    if session_factory is None:
+        raise HTTPException(status_code=503, detail="Auth session not available")
+
+    async with session_factory() as session:
+        yield session
+
+
+async def get_user_repository(request: Request) -> UserRepositoryProtocol:
+    async with _auth_session(request) as session:
+        return DbUserRepository(session)
+
+
+def get_auth_service(request: Request) -> AuthService:
+    session_factory = _get_session_factory(request)
+    if session_factory is None:
+        raise HTTPException(status_code=503, detail="Auth session factory not available")
+    return AuthService(session_factory)
+
+
+async def get_current_user_from_request(request: Request):
+    access_token = request.cookies.get("access_token")
+    if not access_token:
+        raise HTTPException(
+            status_code=401,
+            detail=AuthErrorResponse(code=AuthErrorCode.NOT_AUTHENTICATED, message="Not authenticated").model_dump(),
+        )
+
+    payload = decode_token(access_token)
+    if isinstance(payload, TokenError):
+        raise HTTPException(
+            status_code=401,
+            detail=AuthErrorResponse(
+                code=token_error_to_code(payload),
+                message=f"Token error: {payload.value}",
+            ).model_dump(),
+        )
+
+    async with _auth_session(request) as session:
+        user_repo = DbUserRepository(session)
+        user = await user_repo.get_user_by_id(payload.sub)
+    if user is None:
+        raise HTTPException(
+            status_code=401,
+            detail=AuthErrorResponse(code=AuthErrorCode.USER_NOT_FOUND, message="User not found").model_dump(),
+        )
+
+    if user.token_version != payload.ver:
+        raise HTTPException(
+            status_code=401,
+            detail=AuthErrorResponse(
+                code=AuthErrorCode.TOKEN_INVALID,
+                message="Token revoked (password changed)",
+            ).model_dump(),
+        )
+
+    return user
+
+
+async def get_optional_user_from_request(request: Request):
+    try:
+        return await get_current_user_from_request(request)
+    except HTTPException:
+        return None
+
+
+async def get_current_user_id(request: Request) -> str | None:
+    user = await get_optional_user_from_request(request)
+    return user.id if user else None
+
+
+CurrentUserRepository = Annotated[UserRepositoryProtocol, Depends(get_user_repository)]
+CurrentAuthService = Annotated[AuthService, Depends(get_auth_service)]
+
+__all__ = [
+    "CurrentAuthService",
+    "CurrentUserRepository",
+    "get_auth_service",
+    "get_current_user_from_request",
+    "get_current_user_id",
+    "get_optional_user_from_request",
+    "get_user_repository",
+]

backend/app/plugins/auth/security/langgraph.py

@@ -0,0 +1,64 @@
+"""LangGraph auth adapter for the auth plugin."""
+
+from __future__ import annotations
+
+import secrets
+from types import SimpleNamespace
+
+from langgraph_sdk import Auth
+
+from app.plugins.auth.security.dependencies import get_current_user_from_request
+
+auth = Auth()
+
+_CSRF_METHODS = frozenset({"POST", "PUT", "DELETE", "PATCH"})
+
+
+def _check_csrf(request) -> None:
+    method = getattr(request, "method", "") or ""
+    if method.upper() not in _CSRF_METHODS:
+        return
+
+    cookie_token = request.cookies.get("csrf_token")
+    header_token = request.headers.get("x-csrf-token")
+
+    if not cookie_token or not header_token:
+        raise Auth.exceptions.HTTPException(
+            status_code=403,
+            detail="CSRF token missing. Include X-CSRF-Token header.",
+        )
+
+    if not secrets.compare_digest(cookie_token, header_token):
+        raise Auth.exceptions.HTTPException(status_code=403, detail="CSRF token mismatch.")
+
+
+@auth.authenticate
+async def authenticate(request):
+    _check_csrf(request)
+    resolver_request = SimpleNamespace(
+        cookies=getattr(request, "cookies", {}),
+        state=SimpleNamespace(_auth_session=getattr(request, "_auth_session", None)),
+        app=SimpleNamespace(state=SimpleNamespace(persistence=getattr(request, "_persistence", None))),
+    )
+
+    try:
+        user = await get_current_user_from_request(resolver_request)
+    except Exception as exc:
+        status_code = getattr(exc, "status_code", None)
+        if status_code is None:
+            raise
+        detail = getattr(exc, "detail", "Not authenticated")
+        message = detail.get("message") if isinstance(detail, dict) else str(detail)
+        raise Auth.exceptions.HTTPException(status_code=status_code, detail=message) from exc
+
+    return user.id
+
+
+@auth.on
+async def add_owner_filter(ctx: Auth.types.AuthContext, value: dict):
+    metadata = value.setdefault("metadata", {})
+    metadata["user_id"] = ctx.user.identity
+    return {"user_id": ctx.user.identity}
+
+
+__all__ = ["add_owner_filter", "auth", "authenticate"]

backend/app/plugins/auth/security/middleware.py

@@ -0,0 +1,78 @@
+"""Global authentication middleware for the auth plugin."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from fastapi import HTTPException, Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp
+
+from app.plugins.auth.authorization import _ALL_PERMISSIONS, AuthContext
+from app.plugins.auth.domain.errors import AuthErrorCode, AuthErrorResponse
+from app.plugins.auth.injection.registry_loader import RoutePolicyRegistry
+from app.plugins.auth.security.dependencies import get_current_user_from_request
+from deerflow.runtime.actor_context import ActorContext, bind_actor_context, reset_actor_context
+
+_PUBLIC_PATH_PREFIXES: tuple[str, ...] = ("/health", "/docs", "/redoc", "/openapi.json")
+
+_PUBLIC_EXACT_PATHS: frozenset[str] = frozenset(
+    {
+        "/api/v1/auth/login/local",
+        "/api/v1/auth/register",
+        "/api/v1/auth/logout",
+        "/api/v1/auth/setup-status",
+        "/api/v1/auth/initialize",
+    }
+)
+
+
+def _is_public(path: str) -> bool:
+    stripped = path.rstrip("/")
+    if stripped in _PUBLIC_EXACT_PATHS:
+        return True
+    return any(path.startswith(prefix) for prefix in _PUBLIC_PATH_PREFIXES)
+
+
+class AuthMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app: ASGIApp) -> None:
+        super().__init__(app)
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        registry = getattr(request.app.state, "auth_route_policy_registry", None)
+        is_public = False
+        if isinstance(registry, RoutePolicyRegistry):
+            is_public = registry.is_public_request(request.method, request.url.path)
+        if is_public or _is_public(request.url.path):
+            return await call_next(request)
+
+        if not request.cookies.get("access_token"):
+            return JSONResponse(
+                status_code=401,
+                content={
+                    "detail": AuthErrorResponse(
+                        code=AuthErrorCode.NOT_AUTHENTICATED,
+                        message="Authentication required",
+                    ).model_dump()
+                },
+            )
+
+        try:
+            user = await get_current_user_from_request(request)
+        except HTTPException as exc:
+            return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+
+        auth_context = AuthContext(user=user, permissions=_ALL_PERMISSIONS)
+        request.scope["user"] = user
+        request.scope["auth"] = auth_context
+        request.state.user = user
+        request.state.auth = auth_context
+        token = bind_actor_context(ActorContext(user_id=str(user.id)))
+        try:
+            return await call_next(request)
+        finally:
+            reset_actor_context(token)
+
+
+__all__ = ["AuthMiddleware", "_is_public"]

backend/app/plugins/auth/storage/__init__.py

@@ -0,0 +1,17 @@
+"""Auth plugin storage package.
+
+This package owns auth-specific ORM models and repositories while
+continuing to use the application's shared persistence infrastructure.
+"""
+
+from app.plugins.auth.storage.contracts import User, UserCreate, UserRepositoryProtocol
+from app.plugins.auth.storage.models import User as UserModel
+from app.plugins.auth.storage.repositories import DbUserRepository
+
+__all__ = [
+    "DbUserRepository",
+    "User",
+    "UserCreate",
+    "UserModel",
+    "UserRepositoryProtocol",
+]

backend/app/plugins/auth/storage/contracts.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Protocol
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+def _new_user_id() -> str:
+    return str(uuid4())
+
+
+class UserCreate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(default_factory=_new_user_id)
+    email: str
+    password_hash: str | None = None
+    system_role: str = "user"
+    oauth_provider: str | None = None
+    oauth_id: str | None = None
+    needs_setup: bool = False
+    token_version: int = 0
+
+
+class User(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    email: str
+    password_hash: str | None
+    system_role: str
+    oauth_provider: str | None
+    oauth_id: str | None
+    needs_setup: bool
+    token_version: int
+    created_time: datetime
+    updated_time: datetime | None
+
+
+class UserRepositoryProtocol(Protocol):
+    async def create_user(self, data: UserCreate) -> User: ...
+
+    async def get_user_by_id(self, user_id: str) -> User | None: ...
+
+    async def get_user_by_email(self, email: str) -> User | None: ...
+
+    async def get_user_by_oauth(self, provider: str, oauth_id: str) -> User | None: ...
+
+    async def update_user(self, data: User) -> User: ...
+
+    async def count_users(self) -> int: ...
+
+    async def count_admin_users(self) -> int: ...

backend/app/plugins/auth/storage/models.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from sqlalchemy import Boolean, Integer, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from store.persistence.base_model import Base
+
+
+class User(Base):
+    """Application user table."""
+
+    __tablename__ = "users"
+    __table_args__ = (
+        UniqueConstraint("oauth_provider", "oauth_id", name="uq_users_oauth_identity"),
+        {"comment": "Application user table."},
+    )
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True, unique=True, index=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    password_hash: Mapped[str | None] = mapped_column(String(255), default=None)
+    system_role: Mapped[str] = mapped_column(String(16), default="user", index=True)
+    oauth_provider: Mapped[str | None] = mapped_column(String(64), default=None)
+    oauth_id: Mapped[str | None] = mapped_column(String(255), default=None)
+    needs_setup: Mapped[bool] = mapped_column(Boolean, default=False)
+    token_version: Mapped[int] = mapped_column(Integer, default=0)

backend/app/plugins/auth/storage/repositories.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from sqlalchemy import func, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.plugins.auth.storage.contracts import User, UserCreate, UserRepositoryProtocol
+from app.plugins.auth.storage.models import User as UserModel
+
+
+def _to_user(model: UserModel) -> User:
+    return User(
+        id=model.id,
+        email=model.email,
+        password_hash=model.password_hash,
+        system_role=model.system_role,
+        oauth_provider=model.oauth_provider,
+        oauth_id=model.oauth_id,
+        needs_setup=model.needs_setup,
+        token_version=model.token_version,
+        created_time=model.created_time,
+        updated_time=model.updated_time,
+    )
+
+
+class DbUserRepository(UserRepositoryProtocol):
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def create_user(self, data: UserCreate) -> User:
+        model = UserModel(
+            id=data.id,
+            email=data.email,
+            password_hash=data.password_hash,
+            system_role=data.system_role,
+            oauth_provider=data.oauth_provider,
+            oauth_id=data.oauth_id,
+            needs_setup=data.needs_setup,
+            token_version=data.token_version,
+        )
+        self._session.add(model)
+        try:
+            await self._session.flush()
+        except IntegrityError as exc:
+            await self._session.rollback()
+            raise ValueError("User already exists") from exc
+        await self._session.refresh(model)
+        return _to_user(model)
+
+    async def get_user_by_id(self, user_id: str) -> User | None:
+        model = await self._session.get(UserModel, user_id)
+        return _to_user(model) if model else None
+
+    async def get_user_by_email(self, email: str) -> User | None:
+        result = await self._session.execute(select(UserModel).where(UserModel.email == email))
+        model = result.scalar_one_or_none()
+        return _to_user(model) if model else None
+
+    async def get_user_by_oauth(self, provider: str, oauth_id: str) -> User | None:
+        result = await self._session.execute(
+            select(UserModel).where(
+                UserModel.oauth_provider == provider,
+                UserModel.oauth_id == oauth_id,
+            )
+        )
+        model = result.scalar_one_or_none()
+        return _to_user(model) if model else None
+
+    async def update_user(self, data: User) -> User:
+        model = await self._session.get(UserModel, data.id)
+        if model is None:
+            raise LookupError(f"User {data.id} not found")
+        model.email = data.email
+        model.password_hash = data.password_hash
+        model.system_role = data.system_role
+        model.oauth_provider = data.oauth_provider
+        model.oauth_id = data.oauth_id
+        model.needs_setup = data.needs_setup
+        model.token_version = data.token_version
+        try:
+            await self._session.flush()
+        except IntegrityError as exc:
+            await self._session.rollback()
+            raise ValueError("User already exists") from exc
+        await self._session.refresh(model)
+        return _to_user(model)
+
+    async def count_users(self) -> int:
+        return await self._session.scalar(select(func.count()).select_from(UserModel)) or 0
+
+    async def count_admin_users(self) -> int:
+        return (
+            await self._session.scalar(
+                select(func.count()).select_from(UserModel).where(UserModel.system_role == "admin")
+            )
+            or 0
+        )