accounts/docs/api/auth.md

Authentication And Authorization / 认证与鉴权

中文

当前认证模型

accounts.svc.plus 不是“纯 JWT API”，而是：

• 以 session token 为主控制面事实来源。
• 以 xc_session cookie 和 Authorization: Bearer <session-token> 为主调用方式。
• 在 auth.enable 打开时，为部分路由叠加 JWT middleware。
• 对 /api/internal/* 使用 internal service token。
• 对 /api/agent-server/v1/users|status 使用 agent token。

这意味着“JWT 已启用”并不等于“业务只靠 JWT 运行”；很多 handler 仍会继续读取 session。

认证方式总表

方式	典型接口	传入位置	成功后得到什么
Session token	/api/auth/login /api/auth/session /api/auth/xworkmate/*	Authorization 或 xc_session cookie	当前用户上下文、管理员权限、XWorkmate profile 读写能力。
JWT refresh	POST /api/auth/token/refresh	JSON body refresh_token	新 access_token。
OAuth exchange code	POST /api/auth/token/exchange	JSON body exchange_code	真实 session token，字段名同时以 token / access_token 返回。
Internal service token	/api/internal/*	Authorization: Bearer <token>	受信任服务读接口。
Agent token	/api/agent-server/v1/users /api/agent-server/v1/status	Authorization: Bearer <token>	Agent 身份、client 列表拉取、状态上报。

Session issuance paths

以下路径会签发新的 session token：

入口	请求字段	成功返回	备注
POST /api/auth/login	identifier/account/username/email + password，或邮箱 + totpCode	message、token、access_token、expiresAt、expires_in、user	如果用户已启用 MFA 且未提交验证码，则不会发 session，而是先返回 MFA challenge。
POST /api/auth/register/verify	email、code	message、token、expiresAt、user 或 verified=true	已创建用户走“验证邮箱并自动登录”；预注册验证码走“仅标记 verified”。
POST /api/auth/password/reset/confirm	token、password	message、token、expiresAt、user	重置密码成功后直接进入新会话。
POST /api/auth/mfa/verify	mfa_ticket/mfaToken、code/totpCode	message、token、access_token、expiresAt、expires_in、user	登录后补做 MFA 的完成步骤。
POST /api/auth/mfa/totp/verify	token、code	message、token、expiresAt、user	首次启用 TOTP 成功后直接签发 session。
GET /api/auth/oauth/callback/:provider	query code	307 redirect 到前端 /login?exchange_code=...	callback 自身不直接输出 JSON，而是先创建 session，再下发一次性 exchange code。

注册与邮箱验证

POST /api/auth/register/send

项	内容
请求字段	email
成功返回	200 {"message":"verification email sent"}
前置条件	邮箱格式合法；不在 blacklist；若邮箱已存在且未验证，则继续发送验证邮件。
失败返回	invalid_request、invalid_email、email_blacklisted、smtp_timeout、verification_failed、email_already_exists。

POST /api/auth/register

项	内容
请求字段	name、email、password、code
成功返回	201 {"message":"registration successful","user":...}
前置条件	name 非空；邮箱合法；密码长度至少 8；若启用邮箱验证则 code 必须存在且匹配。
关键副作用	创建 store.User；自动 upsert 7 天 trial store.Subscription。
失败返回	name_required、missing_credentials、invalid_email、password_too_short、verification_required、invalid_code、email_already_exists、name_already_exists。

POST /api/auth/register/verify

项	内容
请求字段	email、code
成功返回 A	200 {"message":"email verified","token":"...","expiresAt":"...","user":...}
成功返回 B	200 {"message":"verification successful","verified":true}
分支解释	若命中已创建用户的 email verification，接口会把用户标记为已验证并直接签发 session；若命中注册前验证码，只做“验证码通过”标记。
失败返回	token_in_query、invalid_request、invalid_code、verification_failed、session_creation_failed。

登录、MFA challenge 与会话读取

POST /api/auth/login

项	内容
请求字段	identifier、account、username、email、password、totpCode
标准成功返回	message、token、access_token、expiresAt、expires_in、mfaRequired=false、user
MFA challenge 返回	message="mfa required"、mfaRequired=true、mfaMethod="totp"、mfaTicket、mfa_ticket、兼容字段 mfaToken
真实规则	先按 identifier -> account -> username -> email 解析登录标识。若用户已启用 MFA 但未提交 totpCode，登录不发 session，只发 challenge。
失败返回	credentials_in_query、invalid_request、missing_credentials、user_not_found、invalid_credentials、password_required、email_not_verified、sandbox_no_login、mfa_challenge_creation_failed。

POST /api/auth/mfa/verify

项	内容
请求字段	mfa_ticket、mfaToken、code、totpCode、method
成功返回	message、token、access_token、expiresAt、expires_in、user
前置条件	method 仅支持 totp；ticket 必须存在且未过期；用户已启用 MFA。
失败返回	mfa_ticket_required、mfa_code_required、unsupported_mfa_method、invalid_mfa_ticket、mfa_not_enabled、invalid_mfa_code。

GET /api/auth/session

项	内容
认证	需要有效 session；若启用 token middleware，还会先经过 JWT + active-user 检查。
成功返回	{"user": ...}，其中可能附带 tenantId、tenants、XWorkmate access 视图。
失败返回	session_token_required、invalid_session、session_user_lookup_failed、account_suspended。

DELETE /api/auth/session

项	内容
认证	需要有效 session。
成功返回	204 No Content
副作用	删除进程内 session，并清空 cookie。

TOTP 启用、查询与关闭

POST /api/auth/mfa/totp/provision

项	内容
请求字段	token、issuer、account
成功返回	secret、otpauth_url、issuer、account、mfaToken、mfa、user
入口模式	可使用已有 mfa token，也可使用当前 session 自动创建新的 MFA challenge。
失败返回	invalid_request、invalid_mfa_token、mfa_token_required、invalid_session、mfa_already_enabled、read_only_account、mfa_secret_generation_failed、mfa_setup_failed。

POST /api/auth/mfa/totp/verify

项	内容
请求字段	token、code
成功返回	{"message":"mfa_verified","token":"...","expiresAt":"...","user":...}
特殊失败	多次错误会进入 429 {"error":"mfa_challenge_locked","retryAt":"...","mfaToken":"..."}。
常见失败	mfa_token_required、invalid_mfa_token、mfa_secret_missing、mfa_code_required、invalid_mfa_code、mfa_update_failed。

GET /api/auth/mfa/status

项	内容
输入来源	query token / identifier / email，header X-MFA-Token，或 Authorization session token。
成功返回	enabled、mfa、user。若按 identifier 查询且用户不存在，返回 200 {"mfa_enabled":false}。
失败返回	mfa_status_failed、mfa_token_required。

POST /api/auth/mfa/disable

项	内容
认证	当前 session token，优先从 Authorization 读取，也接受 query token。
成功返回	{"message":"mfa_disabled","user":...}
失败返回	session_token_required、invalid_session、mfa_disable_failed、mfa_not_enabled、read_only_account。

OAuth 与 exchange code

GET /api/auth/oauth/login/:provider

项	内容
路径参数	provider，当前实现支持 github 与 google。
成功返回	307 Temporary Redirect 到 provider authorization URL。
失败返回	provider_not_found。

GET /api/auth/oauth/callback/:provider

项	内容
输入	query code，可选由 state 带回前端 URL。
成功行为	交换 provider token，拉取 profile，创建或复用用户，确保 store.Identity 绑定，然后签发 session + 一次性 exchange code，最后 307 跳转到前端 /login?exchange_code=...。
失败返回	provider_not_found、code_missing、oauth_exchange_failed、fetch_profile_failed、email_missing、email_not_verified、store_error、user_creation_failed、session_creation_failed、exchange_code_creation_failed。

POST /api/auth/token/exchange

项	内容
请求字段	exchange_code
成功返回	token、access_token、token_type、expiresAt、expires_in、user
语义	不是按 user claims 自签 token，而是把 callback 阶段暂存的一次性 code 换回真实 session。
失败返回	invalid_request、invalid_exchange_code、session_user_lookup_failed。

JWT refresh

POST /api/auth/token/refresh

项	内容
请求字段	refresh_token
成功返回	access_token、token_type="Bearer"、expires_in
前置条件	h.tokenService != nil；refresh token 合法且未过期。
失败返回	token_service_unavailable、invalid_request、invalid_refresh_token。

POST /api/auth/refresh

别名路由，行为与 POST /api/auth/token/refresh 完全一致。

密码重置

POST /api/auth/password/reset

项	内容
请求字段	email
成功返回	202 {"message":"if the account exists a reset email will be sent"}
实现说明	handler 本身按邮箱驱动；但该路由被挂在 authProtected 组下，因此启用 JWT middleware 后会多一层前置认证。
失败返回	email_in_query、invalid_request、email_required、password_reset_failed、read_only_account。

POST /api/auth/password/reset/confirm

项	内容
请求字段	token、password
成功返回	message、token、expiresAt、user
前置条件	password 长度至少 8；reset token 有效；若用户是 demo/read-only account 则拒绝。
失败返回	credentials_in_query、invalid_request、password_too_short、invalid_token、password_reset_failed、read_only_account、session_creation_failed。

XWorkmate profile 与 Vault-backed secrets

GET /api/auth/xworkmate/profile

项	内容
成功返回	edition、tenant、membershipRole、profileScope、canEditIntegrations、canManageTenant、profile、tokenConfigured
profile 字段	BRIDGE_SERVER_URL、bridgeServerOrigin、vaultUrl、vaultNamespace、vaultSecretPath、vaultSecretKey、secretLocators、apisixUrl
失败返回	tenant_membership_required、tenant_not_found、xworkmate_context_failed、xworkmate_profile_read_failed。

GET /api/auth/xworkmate/profile/sync

项	内容
成功返回	BRIDGE_SERVER_URL、BRIDGE_AUTH_TOKEN
语义	给 bridge / desktop sync 使用的精简同步视图，不返回完整 profile。
失败返回	tenant_membership_required、tenant_not_found、bridge_server_url_unavailable、bridge_auth_token_unavailable。

PUT /api/auth/xworkmate/profile

项	内容
请求字段	允许直接传 profile payload，或 { "profile": {...} }
禁止字段	raw token/password/api key 不允许持久化；命中时返回 token_persistence_forbidden。
成功返回	与 GET /xworkmate/profile 同形。
失败返回	xworkmate_profile_forbidden、read_only_account、invalid_request、token_persistence_forbidden、xworkmate_profile_write_failed。

GET /api/auth/xworkmate/secrets

项	内容
成功返回	tenant、membershipRole、profileScope、canEditIntegrations、vaultBackendEnabled、tokenConfigured、secrets
secrets[] 元素	target、provider、secretPath、secretKey、configured、required 等元数据；绝不返回 raw secret。
失败返回	xworkmate_secret_read_failed、xworkmate_context_failed、tenant_not_found。

PUT /api/auth/xworkmate/secrets/:target

项	内容
路径参数	target，例如 bridge auth token 对应的 secret target。
请求字段	value
成功返回	secret、profileScope、tokenConfigured
失败返回	xworkmate_secret_forbidden、read_only_account、xworkmate_secret_unknown_target、xworkmate_secret_value_required、xworkmate_secret_write_failed、xworkmate_profile_write_failed。

DELETE /api/auth/xworkmate/secrets/:target

项	内容
路径参数	target
成功返回	secret、profileScope、tokenConfigured
语义	删除 Vault/backend secret，但保留 locator 元数据。
失败返回	xworkmate_secret_forbidden、read_only_account、xworkmate_secret_unknown_target、xworkmate_secret_delete_failed。

English

Current Auth Model

accounts.svc.plus is not a pure JWT API. It is:

• session-first for the current control plane,
• primarily called through the xc_session cookie or Authorization: Bearer <session-token>,
• optionally wrapped by JWT middleware when auth.enable is on,
• protected by an internal service token for /api/internal/*,
• and protected by agent tokens for /api/agent-server/v1/users|status.

So “JWT enabled” does not mean “business logic runs only on JWT”; many handlers still resolve sessions explicitly.

Authentication Modes

Mode	Example APIs	Input location	Successful outcome
Session token	/api/auth/login, /api/auth/session, /api/auth/xworkmate/*	Authorization header or xc_session cookie	User context, admin permissions, XWorkmate profile access.
JWT refresh	POST /api/auth/token/refresh	JSON body refresh_token	A new access_token.
OAuth exchange code	POST /api/auth/token/exchange	JSON body exchange_code	The real session token, returned in both token and access_token.
Internal service token	/api/internal/*	Authorization: Bearer <token>	Trusted service-to-service reads.
Agent token	/api/agent-server/v1/users, /api/agent-server/v1/status	Authorization: Bearer <token>	Agent identity, client-list reads, status reporting.

Session Issuance Paths

The following flows mint a new session token:

Entry point	Request fields	Success shape	Notes
POST /api/auth/login	identifier/account/username/email plus password, or email plus totpCode	message, token, access_token, expiresAt, expires_in, user	If MFA is enabled and no TOTP code is provided, the handler returns an MFA challenge instead of a session.
POST /api/auth/register/verify	email, code	message, token, expiresAt, user or verified=true	Existing-user email verification auto-logs the user in; pre-registration verification only marks the email as verified.
POST /api/auth/password/reset/confirm	token, password	message, token, expiresAt, user	A successful password reset immediately creates a session.
POST /api/auth/mfa/verify	mfa_ticket/mfaToken, code/totpCode	message, token, access_token, expiresAt, expires_in, user	Completes the MFA step after login.
POST /api/auth/mfa/totp/verify	token, code	message, token, expiresAt, user	First-time TOTP enablement also ends with a new session.
GET /api/auth/oauth/callback/:provider	query code	307 redirect to frontend /login?exchange_code=...	The callback creates the session first, then issues a one-time exchange code instead of returning JSON directly.

Registration And Email Verification

POST /api/auth/register/send

Item	Details
Request fields	email
Success	200 {"message":"verification email sent"}
Preconditions	Valid email format; not blacklisted; existing unverified users can still receive verification mail.
Failures	invalid_request, invalid_email, email_blacklisted, smtp_timeout, verification_failed, email_already_exists.

POST /api/auth/register

Item	Details
Request fields	name, email, password, code
Success	201 {"message":"registration successful","user":...}
Preconditions	Non-empty name; valid email; password length at least 8; when email verification is enabled, code must exist and match.
Side effects	Creates store.User and upserts a 7-day trial store.Subscription.
Failures	name_required, missing_credentials, invalid_email, password_too_short, verification_required, invalid_code, email_already_exists, name_already_exists.

POST /api/auth/register/verify

Item	Details
Request fields	email, code
Success A	200 {"message":"email verified","token":"...","expiresAt":"...","user":...}
Success B	200 {"message":"verification successful","verified":true}
Branching	Existing-user verification marks the user as verified and issues a session; pre-registration verification only confirms the code.
Failures	token_in_query, invalid_request, invalid_code, verification_failed, session_creation_failed.

Login, MFA Challenge, And Session Reads

POST /api/auth/login

Item	Details
Request fields	identifier, account, username, email, password, totpCode
Standard success	message, token, access_token, expiresAt, expires_in, mfaRequired=false, user
MFA challenge	message="mfa required", mfaRequired=true, mfaMethod="totp", mfaTicket, mfa_ticket, compatibility field mfaToken
Behavior	Identifier resolution order is identifier -> account -> username -> email. If MFA is enabled and no TOTP code is provided, the handler returns a challenge instead of a session.
Failures	credentials_in_query, invalid_request, missing_credentials, user_not_found, invalid_credentials, password_required, email_not_verified, sandbox_no_login, mfa_challenge_creation_failed.

POST /api/auth/mfa/verify

Item	Details
Request fields	mfa_ticket, mfaToken, code, totpCode, method
Success	message, token, access_token, expiresAt, expires_in, user
Preconditions	Only totp is supported; the ticket must exist and not be expired; the user must have MFA enabled.
Failures	mfa_ticket_required, mfa_code_required, unsupported_mfa_method, invalid_mfa_ticket, mfa_not_enabled, invalid_mfa_code.

GET /api/auth/session

Item	Details
Auth	Requires a valid session. If token middleware is enabled, the request also passes JWT + active-user checks first.
Success	{"user": ...} and may include tenantId, tenants, and XWorkmate access metadata.
Failures	session_token_required, invalid_session, session_user_lookup_failed, account_suspended.

DELETE /api/auth/session

Item	Details
Auth	Requires a valid session.
Success	204 No Content
Side effect	Removes the process-local session and clears the cookie.

TOTP Provisioning, Status, And Disable

POST /api/auth/mfa/totp/provision

Item	Details
Request fields	token, issuer, account
Success	secret, otpauth_url, issuer, account, mfaToken, mfa, user
Entry modes	Uses an existing MFA token or can bootstrap a new MFA challenge from the current session.
Failures	invalid_request, invalid_mfa_token, mfa_token_required, invalid_session, mfa_already_enabled, read_only_account, mfa_secret_generation_failed, mfa_setup_failed.

POST /api/auth/mfa/totp/verify

Item	Details
Request fields	token, code
Success	{"message":"mfa_verified","token":"...","expiresAt":"...","user":...}
Special failure	Repeated failures can lock the challenge and return 429 {"error":"mfa_challenge_locked","retryAt":"...","mfaToken":"..."}.
Common failures	mfa_token_required, invalid_mfa_token, mfa_secret_missing, mfa_code_required, invalid_mfa_code, mfa_update_failed.

GET /api/auth/mfa/status

Item	Details
Inputs	query token / identifier / email, header X-MFA-Token, or Authorization session token.
Success	enabled, mfa, user. If queried by identifier and the user does not exist, it returns 200 {"mfa_enabled":false}.
Failures	mfa_status_failed, mfa_token_required.

POST /api/auth/mfa/disable

Item	Details
Auth	Current session token, preferably from Authorization; also accepts query token.
Success	{"message":"mfa_disabled","user":...}
Failures	session_token_required, invalid_session, mfa_disable_failed, mfa_not_enabled, read_only_account.

OAuth And Exchange Code

GET /api/auth/oauth/login/:provider

Item	Details
Path param	provider; the current code supports github and google.
Success	307 Temporary Redirect to the provider authorization URL.
Failure	provider_not_found.

GET /api/auth/oauth/callback/:provider

Item	Details
Input	query code; the state value may carry a frontend URL.
Success behavior	Exchanges the provider code, fetches the profile, creates or reuses the user, ensures the store.Identity binding exists, issues a session plus a one-time exchange code, then redirects to the frontend /login?exchange_code=....
Failures	provider_not_found, code_missing, oauth_exchange_failed, fetch_profile_failed, email_missing, email_not_verified, store_error, user_creation_failed, session_creation_failed, exchange_code_creation_failed.

POST /api/auth/token/exchange

Item	Details
Request fields	exchange_code
Success	token, access_token, token_type, expiresAt, expires_in, user
Semantics	This does not mint a token from caller-provided claims. It converts the one-time code created during the OAuth callback back into the real session.
Failures	invalid_request, invalid_exchange_code, session_user_lookup_failed.

JWT Refresh

POST /api/auth/token/refresh

Item	Details
Request fields	refresh_token
Success	access_token, token_type="Bearer", expires_in
Preconditions	h.tokenService != nil; the refresh token must be valid and not expired.
Failures	token_service_unavailable, invalid_request, invalid_refresh_token.

POST /api/auth/refresh

Alias route with the exact same behavior as POST /api/auth/token/refresh.

Password Reset

POST /api/auth/password/reset

Item	Details
Request fields	email
Success	202 {"message":"if the account exists a reset email will be sent"}
Implementation note	The handler itself is email-driven, but the route is mounted under the protected auth group, so enabling JWT middleware adds an extra precondition.
Failures	email_in_query, invalid_request, email_required, password_reset_failed, read_only_account.

POST /api/auth/password/reset/confirm

Item	Details
Request fields	token, password
Success	message, token, expiresAt, user
Preconditions	Password length at least 8; reset token must be valid; demo/read-only users are rejected.
Failures	credentials_in_query, invalid_request, password_too_short, invalid_token, password_reset_failed, read_only_account, session_creation_failed.

XWorkmate Profile And Vault-Backed Secrets

GET /api/auth/xworkmate/profile

Item	Details
Success	edition, tenant, membershipRole, profileScope, canEditIntegrations, canManageTenant, profile, tokenConfigured
profile fields	BRIDGE_SERVER_URL, bridgeServerOrigin, vaultUrl, vaultNamespace, vaultSecretPath, vaultSecretKey, secretLocators, apisixUrl
Failures	tenant_membership_required, tenant_not_found, xworkmate_context_failed, xworkmate_profile_read_failed.

GET /api/auth/xworkmate/profile/sync

Item	Details
Success	BRIDGE_SERVER_URL, BRIDGE_AUTH_TOKEN
Semantics	A reduced sync view used by bridge / desktop flows instead of the full profile.
Failures	tenant_membership_required, tenant_not_found, bridge_server_url_unavailable, bridge_auth_token_unavailable.

PUT /api/auth/xworkmate/profile

Item	Details
Request fields	Accepts either a raw profile payload or { "profile": {...} }
Forbidden fields	Raw token/password/api-key persistence is rejected with token_persistence_forbidden.
Success	Same shape as GET /xworkmate/profile.
Failures	xworkmate_profile_forbidden, read_only_account, invalid_request, token_persistence_forbidden, xworkmate_profile_write_failed.

GET /api/auth/xworkmate/secrets

Item	Details
Success	tenant, membershipRole, profileScope, canEditIntegrations, vaultBackendEnabled, tokenConfigured, secrets
secrets[]	Contains target, provider, secretPath, secretKey, configured, required, and similar metadata. It never returns the raw secret value.
Failures	xworkmate_secret_read_failed, xworkmate_context_failed, tenant_not_found.

PUT /api/auth/xworkmate/secrets/:target

Item	Details
Path param	target, for example the bridge-auth-token secret target.
Request fields	value
Success	secret, profileScope, tokenConfigured
Failures	xworkmate_secret_forbidden, read_only_account, xworkmate_secret_unknown_target, xworkmate_secret_value_required, xworkmate_secret_write_failed, xworkmate_profile_write_failed.

DELETE /api/auth/xworkmate/secrets/:target

Item	Details
Path param	target
Success	secret, profileScope, tokenConfigured
Semantics	Deletes the Vault/backend secret while preserving locator metadata.
Failures	xworkmate_secret_forbidden, read_only_account, xworkmate_secret_unknown_target, xworkmate_secret_delete_failed.