v2.9.0: 设置新增 ZITADEL 统一登录(OIDC Authorization Code+PKCE,身份主键 (issuer,subject),JIT 建号即管理员,docs/12);账号密码 tab 支持修改用户名(验密+重签会话);新增 docs/API.md 全量 API 文档;迁移 0006(oidc_identities/oidc_states)
This commit is contained in:
bigcode
@@ -161,7 +161,7 @@ export function App() {
|
||||
</Content>
|
||||
</Layout>
|
||||
</Layout>
|
||||
<SettingsModal open={settingsOpen} onClose={() => setSettingsOpen(false)} />
|
||||
<SettingsModal open={settingsOpen} onClose={() => setSettingsOpen(false)} onUsernameChanged={setUsername} />
|
||||
</>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -310,7 +310,7 @@ export const retainEmails = (ids: string[]) =>
|
||||
export interface OperationLogRow {
|
||||
id: string;
|
||||
action: string;
|
||||
target_type: "account" | "domain" | "mailbox" | "email" | "webhook";
|
||||
target_type: "account" | "domain" | "mailbox" | "email" | "webhook" | "user" | "settings";
|
||||
target_id: string | null;
|
||||
target_name: string | null;
|
||||
detail: string | null;
|
||||
@@ -338,6 +338,22 @@ export interface SettingsInfo {
|
||||
/** 实际请求的 scope(点号分隔,空格分隔多个) */
|
||||
scope: string;
|
||||
};
|
||||
/** ZITADEL 统一登录配置与当前账号绑定情况 */
|
||||
oidc: {
|
||||
issuer: string;
|
||||
client_id: string;
|
||||
enabled: boolean;
|
||||
/** JIT:未绑定的统一登录身份自动创建本地用户(即管理员) */
|
||||
jit: boolean;
|
||||
/** settings = 后台设置;env = 部署变量兜底;none = 未配置 */
|
||||
source: "settings" | "env" | "none";
|
||||
/** 授权 scope(固定 openid profile) */
|
||||
scopes: string;
|
||||
/** 需要在 ZITADEL 控制台应用里登记的回调地址 */
|
||||
redirect_uri: string;
|
||||
/** 当前账号已绑定的统一登录身份(未绑定为 null) */
|
||||
identity: { issuer: string; subject: string; display_name: string | null; email: string | null } | null;
|
||||
};
|
||||
/** 需要在 Cloudflare Dashboard 登记的授权回调地址 */
|
||||
redirect_uri: string;
|
||||
}
|
||||
@@ -345,10 +361,12 @@ export interface SettingsInfo {
|
||||
export const getSettings = () => api<SettingsInfo>("/api/settings");
|
||||
|
||||
/** 保存设置
|
||||
* webhook.key / cf_oauth.secret 语义一致:undefined 保留原值、空串清除、非空设置新值 */
|
||||
* webhook.key / cf_oauth.secret 语义一致:undefined 保留原值、空串清除、非空设置新值
|
||||
* oidc.enabled / oidc.jit 缺省表示沿用已保存的开关状态 */
|
||||
export const putSettings = (body: {
|
||||
webhook?: { url: string; headers: Record<string, string>; key?: string };
|
||||
cf_oauth?: { client_id: string; secret?: string; scope?: string };
|
||||
oidc?: { issuer: string; client_id: string; enabled?: boolean; jit?: boolean };
|
||||
}) => api("/api/settings", "PUT", body);
|
||||
|
||||
/** # 成员变量: 授权配置自检结果 **/
|
||||
@@ -376,6 +394,16 @@ export const deleteCfOAuth = () => api("/api/settings/cf-oauth", "DELETE");
|
||||
export const changePassword = (old_password: string, new_password: string) =>
|
||||
api("/api/settings/password", "PUT", { old_password, new_password });
|
||||
|
||||
/** 修改登录用户名(需当前密码确认;成功后服务端重签会话 cookie) */
|
||||
export const changeUsername = (new_username: string, password: string) =>
|
||||
api<{ ok: boolean; username: string }>("/api/settings/username", "PUT", { new_username, password });
|
||||
|
||||
/** 清除后台保存的 ZITADEL 统一登录配置(env 兜底仍可用) */
|
||||
export const deleteOidc = () => api("/api/settings/oidc", "DELETE");
|
||||
|
||||
/** 统一登录探测(公开接口,登录页用):enabled 时显示「ZITADEL 统一登录」按钮 */
|
||||
export const oidcStatus = () => api<{ enabled: boolean; issuer: string | null }>("/auth/status");
|
||||
|
||||
/* ---- API/MCP Key(单一 Key,设置模态窗口内使用;API 与 MCP 共用) ---- */
|
||||
|
||||
/** 生成(轮换)Key:明文仅本次返回 */
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
/**
|
||||
* 设置模态窗口(v2.3.0):
|
||||
* - 三个 tab:全局 Webhook(含 API/MCP Key 卡片)、Cloudflare 接入、账号密码
|
||||
* 设置模态窗口(v2.3.0;v2.9.0 四 tab):
|
||||
* - 全局 Webhook(含 API/MCP Key 卡片)、Cloudflare 接入、ZITADEL 统一登录、账号密码(用户名+密码)
|
||||
* - 单一 API/MCP Key(API 与 MCP 共用),凭据存 settings 表,明文仅生成时返回一次
|
||||
* - Cloudflare OAuth 客户端(Client ID / Secret)也在设置里维护,Secret 加密存储只回 last4,
|
||||
* 保存后立即生效,无需重新部署;未配置时账号页「添加账号」不可用
|
||||
* - ZITADEL 统一登录:issuer + Client ID(PKCE 公共客户端无 secret),回调地址 {origin}/auth/callback;
|
||||
* 登录成功即管理员(本平台没有权限设置),JIT 自动建号可开关
|
||||
* - 内容高度不超过屏幕(超出滚动)
|
||||
*/
|
||||
import { useCallback, useEffect, useState } from "react";
|
||||
@@ -18,6 +20,7 @@ import {
|
||||
Modal,
|
||||
Popconfirm,
|
||||
Space,
|
||||
Switch,
|
||||
Tabs,
|
||||
Tag,
|
||||
Typography,
|
||||
@@ -28,12 +31,15 @@ import {
|
||||
DeleteOutlined,
|
||||
KeyOutlined,
|
||||
PlusOutlined,
|
||||
SafetyOutlined,
|
||||
} from "@ant-design/icons";
|
||||
import {
|
||||
changePassword,
|
||||
changeUsername,
|
||||
createApiKey,
|
||||
deleteApiKey,
|
||||
deleteCfOAuth,
|
||||
deleteOidc,
|
||||
getSettings,
|
||||
oauthPreflight,
|
||||
putSettings,
|
||||
@@ -45,7 +51,16 @@ import {
|
||||
/** # 函数
|
||||
* 设置模态窗口组件
|
||||
*/
|
||||
export function SettingsModal({ open, onClose }: { open: boolean; onClose: () => void }) {
|
||||
export function SettingsModal({
|
||||
open,
|
||||
onClose,
|
||||
onUsernameChanged,
|
||||
}: {
|
||||
open: boolean;
|
||||
onClose: () => void;
|
||||
/** 用户名修改成功后回调(顶栏展示名同步) */
|
||||
onUsernameChanged?: (username: string) => void;
|
||||
}) {
|
||||
const { message } = App.useApp();
|
||||
const [info, setInfo] = useState<SettingsInfo | null>(null);
|
||||
|
||||
@@ -77,7 +92,8 @@ export function SettingsModal({ open, onClose }: { open: boolean; onClose: () =>
|
||||
items={[
|
||||
{ key: "webhook", label: "全局 Webhook", children: info ? <WebhookTab info={info} onSaved={load} /> : null },
|
||||
{ key: "cloudflare", label: <span><CloudServerOutlined style={{ marginRight: 6 }} />Cloudflare 接入</span>, children: info ? <CloudflareTab info={info} onSaved={load} /> : null },
|
||||
{ key: "password", label: "账号密码", children: <PasswordTab /> },
|
||||
{ key: "oidc", label: <span><SafetyOutlined style={{ marginRight: 6 }} />ZITADEL 统一登录</span>, children: info ? <ZitadelTab info={info} onSaved={load} /> : null },
|
||||
{ key: "password", label: "账号密码", children: <AccountTab onUsernameChanged={onUsernameChanged} /> },
|
||||
]}
|
||||
/>
|
||||
</Modal>
|
||||
@@ -494,16 +510,40 @@ function CloudflareTab({ info, onSaved }: { info: SettingsInfo; onSaved: () => v
|
||||
);
|
||||
}
|
||||
|
||||
/** # 成员变量: 账号密码 tab 的表单集合(用户名表单 + 密码表单) **/
|
||||
interface UsernameFormValues {
|
||||
new_username: string;
|
||||
password: string;
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 账号密码 tab:修改登录密码
|
||||
* 账号密码 tab:修改登录用户名(v2.9.0)+ 修改登录密码;成功后同步顶栏展示名
|
||||
*/
|
||||
function PasswordTab() {
|
||||
function AccountTab({ onUsernameChanged }: { onUsernameChanged?: (username: string) => void }) {
|
||||
const { message } = App.useApp();
|
||||
const [nameForm] = Form.useForm<UsernameFormValues>();
|
||||
const [pwdForm] = Form.useForm<{
|
||||
old_password: string;
|
||||
new_password: string;
|
||||
confirm: string;
|
||||
}>();
|
||||
const [savingName, setSavingName] = useState(false);
|
||||
|
||||
/** 修改用户名(需当前密码确认) */
|
||||
const saveUsername = async () => {
|
||||
const values = await nameForm.validateFields();
|
||||
setSavingName(true);
|
||||
try {
|
||||
const res = await changeUsername(values.new_username.trim(), values.password);
|
||||
message.success(`用户名已更新为 ${res.username},下次登录请使用新用户名`);
|
||||
onUsernameChanged?.(res.username);
|
||||
nameForm.resetFields();
|
||||
} catch (err) {
|
||||
message.error(err instanceof Error ? err.message : "修改失败");
|
||||
} finally {
|
||||
setSavingName(false);
|
||||
}
|
||||
};
|
||||
|
||||
/** 修改密码 */
|
||||
const savePassword = async () => {
|
||||
@@ -518,6 +558,30 @@ function PasswordTab() {
|
||||
};
|
||||
|
||||
return (
|
||||
<Space orientation="vertical" size="large" style={{ width: "100%" }}>
|
||||
<Form form={nameForm} layout="vertical" onFinish={() => void saveUsername()}>
|
||||
<Form.Item
|
||||
name="new_username"
|
||||
label="新用户名"
|
||||
rules={[
|
||||
{ required: true, message: "请输入新用户名" },
|
||||
{ pattern: /^[a-zA-Z0-9_.-]{2,32}$/, message: "2-32 位,仅字母、数字、_ . -" },
|
||||
]}
|
||||
>
|
||||
<Input placeholder="字母 / 数字 / _ . -" autoComplete="username" />
|
||||
</Form.Item>
|
||||
<Form.Item
|
||||
name="password"
|
||||
label="当前密码(确认身份)"
|
||||
rules={[{ required: true, message: "请输入当前密码" }]}
|
||||
>
|
||||
<Input.Password autoComplete="current-password" />
|
||||
</Form.Item>
|
||||
<Button type="primary" htmlType="submit" loading={savingName}>
|
||||
更新用户名
|
||||
</Button>
|
||||
</Form>
|
||||
|
||||
<Form form={pwdForm} layout="vertical" onFinish={() => void savePassword()}>
|
||||
<Form.Item name="old_password" label="原密码" rules={[{ required: true, message: "请输入原密码" }]}>
|
||||
<Input.Password autoComplete="current-password" />
|
||||
@@ -545,5 +609,163 @@ function PasswordTab() {
|
||||
更新密码
|
||||
</Button>
|
||||
</Form>
|
||||
</Space>
|
||||
);
|
||||
}
|
||||
|
||||
/** # 成员变量: ZITADEL 统一登录表单值(开关单独存 state,避免受控告警) **/
|
||||
interface OidcFormValues {
|
||||
issuer: string;
|
||||
client_id: string;
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* ZITADEL 统一登录 tab(v2.9.0):issuer + Client ID(PKCE 无 secret)+ 启用/JIT 开关;
|
||||
* 回调地址需在 ZITADEL 控制台应用里登记;登录成功即管理员(本平台没有权限设置)
|
||||
*/
|
||||
function ZitadelTab({ info, onSaved }: { info: SettingsInfo; onSaved: () => void }) {
|
||||
const { message } = App.useApp();
|
||||
const [form] = Form.useForm<OidcFormValues>();
|
||||
const [saving, setSaving] = useState(false);
|
||||
const [enabled, setEnabled] = useState(info.oidc.enabled);
|
||||
const [jit, setJit] = useState(info.oidc.jit);
|
||||
const meta = info.oidc;
|
||||
|
||||
useEffect(() => {
|
||||
form.setFieldsValue({ issuer: meta.issuer, client_id: meta.client_id });
|
||||
setEnabled(meta.enabled);
|
||||
setJit(meta.jit);
|
||||
}, [meta.issuer, meta.client_id, meta.enabled, meta.jit, form]);
|
||||
|
||||
/** 保存统一登录配置 */
|
||||
const save = async () => {
|
||||
const values = await form.validateFields();
|
||||
setSaving(true);
|
||||
try {
|
||||
await putSettings({
|
||||
oidc: { issuer: values.issuer.trim(), client_id: values.client_id.trim(), enabled, jit },
|
||||
});
|
||||
message.success("ZITADEL 统一登录配置已保存");
|
||||
onSaved();
|
||||
} catch (err) {
|
||||
message.error(err instanceof Error ? err.message : "保存失败");
|
||||
} finally {
|
||||
setSaving(false);
|
||||
}
|
||||
};
|
||||
|
||||
/** 清除后台保存的配置 */
|
||||
const clear = async () => {
|
||||
setSaving(true);
|
||||
try {
|
||||
await deleteOidc();
|
||||
message.success("已清除后台保存的配置(env 兜底仍可用)");
|
||||
form.resetFields();
|
||||
onSaved();
|
||||
} catch (err) {
|
||||
message.error(err instanceof Error ? err.message : "清除失败");
|
||||
} finally {
|
||||
setSaving(false);
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<Space orientation="vertical" size="large" style={{ width: "100%" }}>
|
||||
<Alert
|
||||
type={meta.source === "none" ? "info" : meta.enabled ? "success" : "info"}
|
||||
showIcon
|
||||
message={
|
||||
meta.source === "none"
|
||||
? "尚未配置:在 ZITADEL 控制台(Qiaonao Internal Apps 项目)为 WmailHub 建一个应用(Auth Code + PKCE,无 secret),把 Client ID 填到这里。"
|
||||
: `已配置(来源:${meta.source === "settings" ? "后台设置" : "部署环境变量"})${meta.enabled ? ",登录页已显示「ZITADEL 统一登录」入口。" : ",当前未启用。"}`
|
||||
}
|
||||
description={
|
||||
<>
|
||||
在 ZITADEL 控制台的应用 Redirect URI 里登记下面的回调地址;所有通过统一登录登录的用户都是
|
||||
<b>管理员</b>(本平台没有权限设置)。
|
||||
</>
|
||||
}
|
||||
/>
|
||||
|
||||
<Form form={form} layout="vertical">
|
||||
<Form.Item label="回调地址(Redirect URI)">
|
||||
<Typography.Paragraph copyable={{ text: meta.redirect_uri }} className="mono" style={{ marginBottom: 0 }}>
|
||||
{meta.redirect_uri}
|
||||
</Typography.Paragraph>
|
||||
</Form.Item>
|
||||
<Form.Item
|
||||
name="issuer"
|
||||
label="Issuer"
|
||||
rules={[{ required: true, message: "请填写 Issuer" }]}
|
||||
extra="如 https://auth.my.qiaonao.net(HTTPS;本机联调允许 http://localhost)"
|
||||
>
|
||||
<Input placeholder="https://auth.my.qiaonao.net" autoComplete="off" />
|
||||
</Form.Item>
|
||||
<Form.Item
|
||||
name="client_id"
|
||||
label="Client ID"
|
||||
rules={[{ required: true, message: "请填写 Client ID" }]}
|
||||
extra="ZITADEL 应用的 Client ID;认证方式是 Authorization Code + PKCE,不需要 Client Secret"
|
||||
>
|
||||
<Input placeholder="ZITADEL 应用 Client ID" autoComplete="off" />
|
||||
</Form.Item>
|
||||
<Form.Item label="授权 Scope">
|
||||
<span className="mono">{meta.scopes}</span>{" "}
|
||||
<Typography.Text type="secondary">(固定;userinfo 取身份,实例无 SMTP 拿不到邮箱 claim 也不影响登录)</Typography.Text>
|
||||
</Form.Item>
|
||||
<Form.Item label="启用统一登录" style={{ marginBottom: 8 }}>
|
||||
<Switch checked={enabled} onChange={setEnabled} />
|
||||
<Typography.Text type="secondary" style={{ marginLeft: 12 }}>
|
||||
启用后登录页显示「ZITADEL 统一登录」按钮;密码登录不受影响(双通道并存)
|
||||
</Typography.Text>
|
||||
</Form.Item>
|
||||
<Form.Item label="自动创建本地账号(JIT)" style={{ marginBottom: 8 }}>
|
||||
<Switch checked={jit} onChange={setJit} />
|
||||
<Typography.Text type="secondary" style={{ marginLeft: 12 }}>
|
||||
开启:未绑定的统一登录身份首次登录自动创建本地用户(即管理员);关闭:未绑定身份拒绝登录
|
||||
</Typography.Text>
|
||||
</Form.Item>
|
||||
<Space>
|
||||
<Button type="primary" loading={saving} onClick={() => void save()}>
|
||||
保存
|
||||
</Button>
|
||||
{meta.source === "settings" && (
|
||||
<Popconfirm
|
||||
title="清除后台保存的统一登录配置?"
|
||||
description="若未配置部署环境变量兜底,清除后登录页不再显示统一登录入口;已建立的绑定保留。"
|
||||
onConfirm={() => void clear()}
|
||||
>
|
||||
<Button danger icon={<DeleteOutlined />} disabled={saving}>
|
||||
清除
|
||||
</Button>
|
||||
</Popconfirm>
|
||||
)}
|
||||
</Space>
|
||||
</Form>
|
||||
|
||||
<Card size="small" title="当前账号绑定" style={{ width: "100%" }}>
|
||||
{meta.identity ? (
|
||||
<Descriptions size="small" column={1}>
|
||||
<Descriptions.Item label="身份">
|
||||
<Tag color="green">已绑定</Tag>
|
||||
<span className="mono">{meta.identity.display_name ?? "(无展示名)"}</span>
|
||||
</Descriptions.Item>
|
||||
<Descriptions.Item label="Subject">
|
||||
<span className="mono">{meta.identity.subject}</span>
|
||||
</Descriptions.Item>
|
||||
<Descriptions.Item label="Issuer">
|
||||
<span className="mono">{meta.identity.issuer}</span>
|
||||
</Descriptions.Item>
|
||||
<Descriptions.Item label="邮箱">
|
||||
{meta.identity.email ? <span className="mono">{meta.identity.email}</span> : <Typography.Text type="secondary">未提供(IdP 未配置 SMTP,正常现象)</Typography.Text>}
|
||||
</Descriptions.Item>
|
||||
</Descriptions>
|
||||
) : (
|
||||
<Typography.Text type="secondary">
|
||||
当前账号未绑定统一登录身份;绑定后可直接用 ZITADEL 登录本站(启用 JIT 时首次登录会自动建新账号)。
|
||||
</Typography.Text>
|
||||
)}
|
||||
</Card>
|
||||
</Space>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1,9 +1,18 @@
|
||||
/** 登录页:用户名密码(默认 admin/admin) */
|
||||
import { useState } from "react";
|
||||
import { useNavigate } from "react-router-dom";
|
||||
import { Button, Card, Form, Input, App } from "antd";
|
||||
import { LockOutlined, UserOutlined } from "@ant-design/icons";
|
||||
import { login } from "../api.ts";
|
||||
/** 登录页:用户名密码(默认 admin/admin)+ ZITADEL 统一登录(启用时显示,v2.9.0) */
|
||||
import { useEffect, useState } from "react";
|
||||
import { useNavigate, useSearchParams } from "react-router-dom";
|
||||
import { Alert, Button, Card, Divider, Form, Input, App } from "antd";
|
||||
import { LockOutlined, SafetyOutlined, UserOutlined } from "@ant-design/icons";
|
||||
import { login, oidcStatus } from "../api.ts";
|
||||
|
||||
/** # 成员变量: 统一登录错误码 -> 中文文案(与后端 routes/oidc.ts 的 OIDC_ERROR_TEXT 保持一致) **/
|
||||
const OIDC_ERROR_TEXT: Record<string, string> = {
|
||||
oidc_disabled: "统一登录未启用",
|
||||
oidc_unavailable: "统一登录服务暂时不可用,请稍后重试或使用密码登录",
|
||||
state_invalid: "登录状态校验失败(可能已过期),请重新登录",
|
||||
oidc_exchange_failed: "统一登录兑换失败,请重新登录",
|
||||
oidc_not_linked: "该统一登录账号未绑定本站用户,请使用密码登录或联系管理员",
|
||||
};
|
||||
|
||||
/** # 函数
|
||||
* 登录页组件
|
||||
@@ -11,7 +20,17 @@ import { login } from "../api.ts";
|
||||
export function LoginPage() {
|
||||
const navigate = useNavigate();
|
||||
const { message } = App.useApp();
|
||||
const [params] = useSearchParams();
|
||||
const [loading, setLoading] = useState(false);
|
||||
const [oidc, setOidc] = useState<{ enabled: boolean; issuer: string | null }>({ enabled: false, issuer: null });
|
||||
const oidcError = params.get("error");
|
||||
|
||||
useEffect(() => {
|
||||
// 探测统一登录是否启用(公开接口;失败静默,不影响密码登录)
|
||||
void oidcStatus()
|
||||
.then(setOidc)
|
||||
.catch(() => undefined);
|
||||
}, []);
|
||||
|
||||
return (
|
||||
<div className="login-page">
|
||||
@@ -23,6 +42,14 @@ export function LoginPage() {
|
||||
<div style={{ textAlign: "center", marginBottom: 20 }} className="muted">
|
||||
Cloudflare Email Workers 邮件接收平台
|
||||
</div>
|
||||
{oidcError && (
|
||||
<Alert
|
||||
type="error"
|
||||
showIcon
|
||||
style={{ marginBottom: 16 }}
|
||||
message={OIDC_ERROR_TEXT[oidcError] ?? `统一登录失败(${oidcError})`}
|
||||
/>
|
||||
)}
|
||||
<Form
|
||||
layout="vertical"
|
||||
onFinish={async (values) => {
|
||||
@@ -48,6 +75,25 @@ export function LoginPage() {
|
||||
登录
|
||||
</Button>
|
||||
</Form>
|
||||
{oidc.enabled && (
|
||||
<>
|
||||
<Divider plain style={{ margin: "18px 0 14px" }}>
|
||||
或
|
||||
</Divider>
|
||||
<Button
|
||||
block
|
||||
size="large"
|
||||
icon={<SafetyOutlined />}
|
||||
title={oidc.issuer ? `通过 ${oidc.issuer} 统一登录` : "ZITADEL 统一登录"}
|
||||
onClick={() => {
|
||||
// 登录成功后统一回 /(当前在登录页,必然是未登录状态;return 缺省即 /)
|
||||
window.location.href = "/auth/login";
|
||||
}}
|
||||
>
|
||||
ZITADEL 统一登录
|
||||
</Button>
|
||||
</>
|
||||
)}
|
||||
<div style={{ marginTop: 14, textAlign: "center" }} className="muted">
|
||||
默认账号 admin / admin,登录后请尽快修改
|
||||
</div>
|
||||
|
||||
@@ -16,6 +16,8 @@ const TYPE_META: Record<string, { label: string; color: string }> = {
|
||||
mailbox: { label: "邮箱", color: "purple" },
|
||||
email: { label: "邮件", color: "orange" },
|
||||
webhook: { label: "Webhook", color: "blue" },
|
||||
user: { label: "用户", color: "volcano" },
|
||||
settings: { label: "设置", color: "default" },
|
||||
};
|
||||
|
||||
/** # 成员变量: 动作名 -> 中文标签(未收录的动作原样展示) **/
|
||||
@@ -40,6 +42,11 @@ const ACTION_LABEL: Record<string, string> = {
|
||||
"webhook.clear": "清除 Webhook",
|
||||
"webhook.deliver": "Webhook 投递成功",
|
||||
"webhook.deliver_failed": "Webhook 投递失败",
|
||||
"user.rename": "修改用户名",
|
||||
"user.oidc_login": "统一登录",
|
||||
"user.oidc_signup": "统一登录(自动建号)",
|
||||
"settings.oidc": "配置统一登录",
|
||||
"settings.oidc_clear": "清除统一登录配置",
|
||||
};
|
||||
|
||||
/** # 函数
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
* 路由分区:
|
||||
* /api/health 健康检查
|
||||
* /api/auth/* 用户登录/登出/会话(cookie)
|
||||
* /auth/* ZITADEL 统一登录:status / login / callback(OIDC Authorization Code + PKCE)
|
||||
* /api/accounts|domains|mailboxes|emails 管理资源 CRUD(会话保护)
|
||||
* /api/settings/* 设置:全局 Webhook / 改密码(会话保护)
|
||||
* /api/oauth/* Cloudflare OAuth(会话保护)
|
||||
@@ -23,6 +24,7 @@ import { internalRoutes } from "./routes/internal.ts";
|
||||
import { resourceRoutes } from "./routes/resources.ts";
|
||||
import { settingsRoutes } from "./routes/settings.ts";
|
||||
import { oauthRoutes } from "./routes/oauth.ts";
|
||||
import { oidcRoutes } from "./routes/oidc.ts";
|
||||
import { apiV1Routes } from "./routes/apiv1.ts";
|
||||
import { mcpRoutes } from "./routes/mcp.ts";
|
||||
import { adminRoutes } from "./routes/admin.ts";
|
||||
@@ -50,6 +52,7 @@ export function createApp(
|
||||
app.get("/api/health", (c) => c.json({ ok: true, name: APP_NAME, version: APP_VERSION }));
|
||||
|
||||
app.route("/api/auth", authRoutes());
|
||||
app.route("/auth", oidcRoutes());
|
||||
app.route("/internal", internalRoutes());
|
||||
app.route("/api/oauth", oauthRoutes());
|
||||
app.route("/api/settings", settingsRoutes());
|
||||
|
||||
+5
-2
@@ -133,11 +133,14 @@ export function authRoutes() {
|
||||
return c.json({ ok: true });
|
||||
});
|
||||
|
||||
/** 当前登录用户信息 */
|
||||
/** 当前登录用户信息(用户名以库内为准:v2.9.0 起支持改用户名,旧会话 cookie 的 payload 可能是旧名) */
|
||||
app.get("/me", async (c) => {
|
||||
const payload = await verifySessionToken(c.env, readSessionCookie(c.req.raw));
|
||||
if (!payload) return c.json({ error: "unauthorized" }, 401);
|
||||
return c.json({ user: { id: payload.uid, username: payload.username }, now: nowIso() });
|
||||
const row = await c.env.DB.prepare("SELECT username FROM users WHERE id = ?")
|
||||
.bind(payload.uid)
|
||||
.first<{ username: string }>();
|
||||
return c.json({ user: { id: payload.uid, username: row?.username ?? payload.username }, now: nowIso() });
|
||||
});
|
||||
|
||||
return app;
|
||||
|
||||
@@ -55,6 +55,11 @@ export interface Env {
|
||||
CF_OAUTH_REDIRECT_URI?: string;
|
||||
/** 本地联调:允许 webhook endpoint 指向私网/localhost("1"),生产严禁开启 **/
|
||||
WMAILHUB_ALLOW_PRIVATE_WEBHOOKS?: string;
|
||||
/** ZITADEL 统一登录兜底配置(后台未保存 settings 时生效);issuer 须 HTTPS **/
|
||||
OIDC_ISSUER?: string;
|
||||
OIDC_CLIENT_ID?: string;
|
||||
/** "false" 关闭,其余视为开启(仅在有 issuer+client_id 兜底时有意义) **/
|
||||
OIDC_ENABLED?: string;
|
||||
}
|
||||
|
||||
/** # 成员变量: Workers 执行上下文最小接口 **/
|
||||
|
||||
@@ -0,0 +1,152 @@
|
||||
/**
|
||||
* ZITADEL 统一登录路由(docs/12,v2.9.0):
|
||||
* GET /auth/status 统一登录是否启用(公开,登录页探测;只回 enabled 与 issuer)
|
||||
* GET /auth/login 发起授权:生成 state+PKCE 存库,302 到 IdP 授权端点
|
||||
* GET /auth/callback 授权回调:一次性 state 校验 → 换码 → userinfo → 解析/JIT 建号 → 签发本地会话 cookie
|
||||
*
|
||||
* 安全:state 一次性(用后即删,10 分钟过期)承担 CSRF 防护——浏览器从 IdP 跨站重定向回来时
|
||||
* SameSite=Strict 的会话 cookie 不会携带,回调不校验会话;PKCE S256 防授权码拦截。
|
||||
* 回跳路径只接受站内路径(防开放重定向);所有失败都 302 回 /login?error=<code> 并附中文文案。
|
||||
*/
|
||||
|
||||
import { Hono, type Context } from "hono";
|
||||
import type { Env, AppVars } from "../env.ts";
|
||||
import { ids } from "../../../shared/src/index.ts";
|
||||
import { issueSessionToken, sessionSetCookie } from "../auth.ts";
|
||||
import { logOperation } from "../services/logs.ts";
|
||||
import {
|
||||
buildOidcAuthorizeUrl,
|
||||
createPkce,
|
||||
discoverOidcEndpoints,
|
||||
exchangeOidcCode,
|
||||
getOidcConfig,
|
||||
oidcRedirectUri,
|
||||
resolveOrProvisionIdentity,
|
||||
safeLocalPath,
|
||||
} from "../services/oidc.ts";
|
||||
import { nowIso } from "../util.ts";
|
||||
|
||||
type App = Hono<{ Bindings: Env; Variables: AppVars }>;
|
||||
|
||||
/** # 成员变量: OIDC state 有效期(秒) **/
|
||||
const OIDC_STATE_TTL_SECONDS = 600;
|
||||
|
||||
/** # 成员变量: 登录页错误码 → 中文文案(与前端 Login.tsx 的映射保持一致) **/
|
||||
export const OIDC_ERROR_TEXT: Record<string, string> = {
|
||||
oidc_disabled: "统一登录未启用",
|
||||
oidc_unavailable: "统一登录服务暂时不可用,请稍后重试或使用密码登录",
|
||||
state_invalid: "登录状态校验失败(可能已过期),请重新登录",
|
||||
oidc_exchange_failed: "统一登录兑换失败,请重新登录",
|
||||
oidc_not_linked: "该统一登录账号未绑定本站用户,请使用密码登录或联系管理员",
|
||||
};
|
||||
|
||||
/** # 函数
|
||||
* 装配统一登录路由(全部公开:status 供登录页探测,login/callback 是重定向链)
|
||||
*/
|
||||
export function oidcRoutes(): App {
|
||||
const app = new Hono<{ Bindings: Env; Variables: AppVars }>();
|
||||
|
||||
/** 探测:登录页据此显示「ZITADEL 统一登录」按钮 */
|
||||
app.get("/status", async (c) => {
|
||||
const cfg = await getOidcConfig(c.env);
|
||||
return c.json({ enabled: Boolean(cfg?.enabled), issuer: cfg?.issuer ?? null });
|
||||
});
|
||||
|
||||
/** 发起授权 */
|
||||
app.get("/login", async (c) => {
|
||||
const cfg = await getOidcConfig(c.env);
|
||||
if (!cfg || !cfg.enabled) return redirectError(c, "oidc_disabled");
|
||||
let authorizationEndpoint: string;
|
||||
try {
|
||||
authorizationEndpoint = (await discoverOidcEndpoints(c.env, cfg.issuer)).authorization_endpoint;
|
||||
} catch (err) {
|
||||
console.error(JSON.stringify({ t: nowIso(), lvl: "error", msg: "oidc discovery failed", error: String(err) }));
|
||||
return redirectError(c, "oidc_unavailable");
|
||||
}
|
||||
// 顺手清理过期 state(旁路,失败不打断)
|
||||
try {
|
||||
await c.env.DB.prepare("DELETE FROM oidc_states WHERE expires_at < ?").bind(nowIso()).run();
|
||||
} catch {
|
||||
// ignore
|
||||
}
|
||||
const { verifier, challenge } = await createPkce();
|
||||
const state = `oidc_${ids.oauthState()}`;
|
||||
const returnTo = safeLocalPath(c.req.query("return"));
|
||||
await c.env.DB.prepare(
|
||||
"INSERT INTO oidc_states (state, code_verifier, return_to, created_at, expires_at) VALUES (?, ?, ?, ?, ?)",
|
||||
)
|
||||
.bind(state, verifier, returnTo, nowIso(), new Date(Date.now() + OIDC_STATE_TTL_SECONDS * 1000).toISOString())
|
||||
.run();
|
||||
const url = buildOidcAuthorizeUrl({
|
||||
authorizationEndpoint,
|
||||
clientId: cfg.clientId,
|
||||
redirectUri: oidcRedirectUri(new URL(c.req.url).origin),
|
||||
state,
|
||||
codeChallenge: challenge,
|
||||
});
|
||||
return c.redirect(url, 302);
|
||||
});
|
||||
|
||||
/** 授权回调:state → code → userinfo → 本地会话 */
|
||||
app.get("/callback", async (c) => {
|
||||
const cfg = await getOidcConfig(c.env);
|
||||
if (!cfg || !cfg.enabled) return redirectError(c, "oidc_disabled");
|
||||
const url = new URL(c.req.url);
|
||||
// IdP 侧拒绝(access_denied / invalid_scope …):带回错误码,不在回调地址上停留
|
||||
const idpError = url.searchParams.get("error");
|
||||
if (idpError) {
|
||||
return redirectError(c, idpError in OIDC_ERROR_TEXT ? idpError : "oidc_exchange_failed");
|
||||
}
|
||||
// 一次性 state:存在且未过期则删除并取回 verifier/return_to(CSRF 防护核心)
|
||||
const state = url.searchParams.get("state") ?? "";
|
||||
const row = state
|
||||
? await c.env.DB.prepare("SELECT code_verifier, return_to, expires_at FROM oidc_states WHERE state = ?")
|
||||
.bind(state)
|
||||
.first<{ code_verifier: string; return_to: string; expires_at: string }>()
|
||||
: null;
|
||||
if (row) await c.env.DB.prepare("DELETE FROM oidc_states WHERE state = ?").bind(state).run();
|
||||
if (!row || row.expires_at < nowIso()) return redirectError(c, "state_invalid");
|
||||
|
||||
const code = url.searchParams.get("code") ?? "";
|
||||
let sub = "";
|
||||
try {
|
||||
const endpoints = await discoverOidcEndpoints(c.env, cfg.issuer);
|
||||
const ui = await exchangeOidcCode({
|
||||
endpoints,
|
||||
clientId: cfg.clientId,
|
||||
redirectUri: oidcRedirectUri(url.origin),
|
||||
code,
|
||||
verifier: row.code_verifier,
|
||||
});
|
||||
sub = ui.sub;
|
||||
const resolved = await resolveOrProvisionIdentity(c.env, cfg, cfg.issuer, ui);
|
||||
if (!resolved) return redirectError(c, "oidc_not_linked");
|
||||
const token = await issueSessionToken(c.env, resolved.userId, resolved.username);
|
||||
c.header("Set-Cookie", sessionSetCookie(token));
|
||||
await logOperation(c.env, {
|
||||
action: resolved.created ? "user.oidc_signup" : "user.oidc_login",
|
||||
targetType: "user",
|
||||
targetId: resolved.userId,
|
||||
targetName: resolved.username,
|
||||
detail: { issuer: cfg.issuer, jit: resolved.created },
|
||||
operator: resolved.username,
|
||||
});
|
||||
return c.redirect(row.return_to, 302);
|
||||
} catch (err) {
|
||||
// 日志只记错误形态与 sub 前缀,不记 code/token/完整身份
|
||||
console.error(
|
||||
JSON.stringify({ t: nowIso(), lvl: "error", msg: "oidc callback failed", sub_prefix: sub.slice(0, 8), error: String(err) }),
|
||||
);
|
||||
return redirectError(c, "oidc_exchange_failed");
|
||||
}
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 302 回登录页并携带错误码(登录页映射成中文文案)
|
||||
*/
|
||||
function redirectError(c: Context<{ Bindings: Env; Variables: AppVars }>, code: string): Response {
|
||||
return c.redirect(`/login?error=${encodeURIComponent(code)}`, 302);
|
||||
}
|
||||
@@ -1,11 +1,13 @@
|
||||
/**
|
||||
* 设置路由(v2.3.0):
|
||||
* GET /api/settings 读取:全局 Webhook / API Key 元信息 / Cloudflare OAuth 客户端 / 当前用户
|
||||
* PUT /api/settings 保存:全局 Webhook、Cloudflare OAuth 客户端
|
||||
* 设置路由(v2.3.0 起;v2.9.0 增 ZITADEL 统一登录配置与改用户名):
|
||||
* GET /api/settings 读取:全局 Webhook / API Key 元信息 / Cloudflare OAuth 客户端 / ZITADEL 统一登录 / 当前用户
|
||||
* PUT /api/settings 保存:全局 Webhook、Cloudflare OAuth 客户端、ZITADEL 统一登录
|
||||
* POST /api/settings/api-key 生成(轮换)单一 API/MCP Key,明文仅返回一次
|
||||
* DEL /api/settings/api-key 撤销并删除 API Key
|
||||
* DEL /api/settings/cf-oauth 清除后台保存的 Cloudflare OAuth 客户端凭据
|
||||
* DEL /api/settings/oidc 清除后台保存的 ZITADEL 统一登录配置(env 兜底仍可用)
|
||||
* PUT /api/settings/password 修改登录密码
|
||||
* PUT /api/settings/username 修改登录用户名(验当前密码,成功后重签会话 cookie)
|
||||
* API 与 MCP 共用同一 Key,凭据存 settings 表(不再单独建表);
|
||||
* Cloudflare OAuth Client Secret 同样只存加密密文,接口只回 last4。
|
||||
*/
|
||||
@@ -13,6 +15,7 @@
|
||||
import { Hono } from "hono";
|
||||
import type { Env, AppVars } from "../env.ts";
|
||||
import { requireSession } from "../middleware.ts";
|
||||
import { issueSessionToken, sessionSetCookie } from "../auth.ts";
|
||||
import {
|
||||
checkWebhookUrl,
|
||||
generateWmailKey,
|
||||
@@ -30,6 +33,15 @@ import {
|
||||
saveOAuthClient,
|
||||
} from "../services/cfapi.ts";
|
||||
import { getGlobalWebhookKey, normalizeWebhookHeaders, saveGlobalWebhook } from "../services/webhook_delivery.ts";
|
||||
import {
|
||||
clearOidcConfig,
|
||||
getOidcConfig,
|
||||
oidcRedirectUri,
|
||||
readOidcSettingRaw,
|
||||
saveOidcConfig,
|
||||
validateIssuerUrl,
|
||||
OIDC_SCOPES,
|
||||
} from "../services/oidc.ts";
|
||||
import { logOperation, operatorName } from "../services/logs.ts";
|
||||
import { nowIso, readJson } from "../util.ts";
|
||||
|
||||
@@ -73,21 +85,41 @@ export function settingsRoutes(): App {
|
||||
// settings 损坏时按未配置处理
|
||||
}
|
||||
}
|
||||
// ZITADEL 统一登录配置(不含 secret 类字段;PKCE 公共客户端本就无 secret)+ 当前账号绑定情况
|
||||
const oidcCfg = await getOidcConfig(c.env);
|
||||
const identity = await c.env.DB.prepare(
|
||||
"SELECT issuer, subject, display_name, email FROM oidc_identities WHERE user_id = ?",
|
||||
)
|
||||
.bind(userId)
|
||||
.first<{ issuer: string; subject: string; display_name: string | null; email: string | null }>();
|
||||
return c.json({
|
||||
username: user?.username ?? "",
|
||||
webhook,
|
||||
api_key: await apiKeyMeta(c.env),
|
||||
cf_oauth: { ...(await oauthClientMeta(c.env)), scope: await getOAuthScopes(c.env) },
|
||||
oidc: {
|
||||
issuer: oidcCfg?.issuer ?? "",
|
||||
client_id: oidcCfg?.clientId ?? "",
|
||||
enabled: oidcCfg?.enabled ?? false,
|
||||
jit: oidcCfg?.jit ?? true,
|
||||
source: oidcCfg?.source ?? "none",
|
||||
scopes: OIDC_SCOPES,
|
||||
// 供前端展示:需要在 ZITADEL 控制台应用里登记的回调地址
|
||||
redirect_uri: oidcRedirectUri(new URL(c.req.url).origin),
|
||||
// 当前登录账号已绑定的统一登录身份(未绑定为 null)
|
||||
identity: identity ?? null,
|
||||
},
|
||||
// 供前端展示:需要在 Cloudflare Dashboard 登记的回调地址
|
||||
redirect_uri: oauthRedirectUri(c.env, new URL(c.req.url).origin),
|
||||
});
|
||||
});
|
||||
|
||||
/** 保存设置:全局 Webhook、Cloudflare OAuth 客户端 */
|
||||
/** 保存设置:全局 Webhook、Cloudflare OAuth 客户端、ZITADEL 统一登录 */
|
||||
app.put("/", async (c) => {
|
||||
const body = await readJson<{
|
||||
webhook?: { url?: string; headers?: unknown; key?: string };
|
||||
cf_oauth?: { client_id?: string; secret?: string; scope?: string };
|
||||
oidc?: { issuer?: string; client_id?: string; enabled?: boolean; jit?: boolean };
|
||||
}>(c.req.raw);
|
||||
|
||||
if (body.webhook) {
|
||||
@@ -141,6 +173,29 @@ export function settingsRoutes(): App {
|
||||
}
|
||||
}
|
||||
|
||||
if (body.oidc) {
|
||||
const issuer = (body.oidc.issuer ?? "").trim().replace(/\/+$/, "");
|
||||
const clientId = (body.oidc.client_id ?? "").trim();
|
||||
if (issuer) {
|
||||
const invalid = validateIssuerUrl(issuer);
|
||||
if (invalid) return c.json({ error: invalid }, 400);
|
||||
}
|
||||
if (clientId && !issuer) return c.json({ error: "填写 Client ID 时请同时填写 Issuer" }, 400);
|
||||
// 开关缺省沿用已保存值(再保存表单不丢开关状态);未保存过默认 jit 开、enabled 关
|
||||
const prev = await readOidcSettingRaw(c.env);
|
||||
const enabled = body.oidc.enabled ?? prev?.enabled ?? false;
|
||||
const jit = body.oidc.jit ?? prev?.jit ?? true;
|
||||
if (enabled && (!issuer || !clientId)) return c.json({ error: "启用统一登录前请完整填写 Issuer 与 Client ID" }, 400);
|
||||
await saveOidcConfig(c.env, { issuer, client_id: clientId, enabled, jit });
|
||||
await logOperation(c.env, {
|
||||
action: "settings.oidc",
|
||||
targetType: "settings",
|
||||
targetName: "ZITADEL 统一登录",
|
||||
detail: { enabled, jit, issuer, configured: Boolean(issuer && clientId) },
|
||||
operator: await operatorName(c.env, c.get("userId")),
|
||||
});
|
||||
}
|
||||
|
||||
return c.json({ ok: true });
|
||||
});
|
||||
|
||||
@@ -189,5 +244,51 @@ export function settingsRoutes(): App {
|
||||
return c.json({ ok: true });
|
||||
});
|
||||
|
||||
/** 修改登录用户名:需当前密码确认;成功后重签会话 cookie(payload 内含用户名) */
|
||||
app.put("/username", async (c) => {
|
||||
const body = await readJson<{ new_username?: string; password?: string }>(c.req.raw);
|
||||
const newUsername = (body.new_username ?? "").trim();
|
||||
if (!/^[a-zA-Z0-9_.-]{2,32}$/.test(newUsername)) {
|
||||
return c.json({ error: "用户名需 2-32 位,仅字母、数字、_ . -" }, 400);
|
||||
}
|
||||
const userId = c.get("userId") ?? "";
|
||||
const user = await c.env.DB.prepare("SELECT id, username, password_hash FROM users WHERE id = ?")
|
||||
.bind(userId)
|
||||
.first<{ id: string; username: string; password_hash: string }>();
|
||||
if (!user) return c.json({ error: "user not found" }, 404);
|
||||
if (!(await verifyPassword(body.password ?? "", user.password_hash))) {
|
||||
return c.json({ error: "密码不正确" }, 400);
|
||||
}
|
||||
if (newUsername !== user.username) {
|
||||
const dup = await c.env.DB.prepare("SELECT id FROM users WHERE username = ?").bind(newUsername).first<{ id: string }>();
|
||||
if (dup && dup.id !== userId) return c.json({ error: "用户名已存在" }, 409);
|
||||
await c.env.DB.prepare("UPDATE users SET username = ? WHERE id = ?").bind(newUsername, userId).run();
|
||||
await logOperation(c.env, {
|
||||
action: "user.rename",
|
||||
targetType: "user",
|
||||
targetId: userId,
|
||||
targetName: newUsername,
|
||||
detail: { from: user.username },
|
||||
operator: newUsername,
|
||||
});
|
||||
}
|
||||
// 重签会话:旧 cookie 的 payload 里还是旧用户名(/me 会兜底读库,这里让 cookie 也保持一致)
|
||||
const token = await issueSessionToken(c.env, userId, newUsername);
|
||||
c.header("Set-Cookie", sessionSetCookie(token));
|
||||
return c.json({ ok: true, username: newUsername });
|
||||
});
|
||||
|
||||
/** 清除后台保存的 ZITADEL 统一登录配置(env 兜底仍可用;已建立的绑定不受影响) */
|
||||
app.delete("/oidc", async (c) => {
|
||||
await clearOidcConfig(c.env);
|
||||
await logOperation(c.env, {
|
||||
action: "settings.oidc_clear",
|
||||
targetType: "settings",
|
||||
targetName: "ZITADEL 统一登录",
|
||||
operator: await operatorName(c.env, c.get("userId")),
|
||||
});
|
||||
return c.json({ ok: true });
|
||||
});
|
||||
|
||||
return app;
|
||||
}
|
||||
|
||||
@@ -10,7 +10,7 @@ import { ids } from "../../../shared/src/index.ts";
|
||||
import { nowIso } from "../util.ts";
|
||||
|
||||
/** # 成员变量: 操作对象类型 **/
|
||||
export type OpTargetType = "account" | "domain" | "mailbox" | "email" | "webhook";
|
||||
export type OpTargetType = "account" | "domain" | "mailbox" | "email" | "webhook" | "user" | "settings";
|
||||
|
||||
/** # 成员变量: 写一条操作日志的参数 **/
|
||||
export interface OperationLogInput {
|
||||
|
||||
@@ -0,0 +1,350 @@
|
||||
/**
|
||||
* ZITADEL 统一登录(docs/12,v2.9.0):OIDC Authorization Code + PKCE(无 client secret)。
|
||||
*
|
||||
* - 配置存 settings 表(设置 → ZITADEL 统一登录),env OIDC_ISSUER/OIDC_CLIENT_ID 兜底;
|
||||
* 回调地址固定为 {origin}/auth/callback,不在代码/配置里硬编码 issuer 与 client_id
|
||||
* - 身份主键是 (issuer, subject):email 仅作资料展示(实例无 SMTP,可能缺失),绝不参与判定
|
||||
* - 令牌只在服务端瞬时使用(code 换 access_token → userinfo 取身份),不落库、不进前端与日志
|
||||
* - JIT(自动建号)可配置;按需求本平台登录成功即管理员,没有权限设置
|
||||
*/
|
||||
|
||||
import type { Env } from "../env.ts";
|
||||
import { hashPassword, ids } from "../../../shared/src/index.ts";
|
||||
import { getSetting, setSetting } from "../db.ts";
|
||||
import { nowIso } from "../util.ts";
|
||||
|
||||
/** # 成员变量: settings 表里 OIDC 配置的键 **/
|
||||
export const OIDC_SETTING_KEY = "oidc_config";
|
||||
|
||||
/** # 成员变量: 授权 scope(固定:userinfo 取身份必需 openid;profile 带展示名 claim) **/
|
||||
export const OIDC_SCOPES = "openid profile";
|
||||
|
||||
/** # 成员变量: 后台保存的 OIDC 配置(settings 表 JSON) **/
|
||||
interface OidcConfigSetting {
|
||||
/** IdP 签发者,如 https://auth.my.qiaonao.net(末尾不带斜杠) **/
|
||||
issuer: string;
|
||||
/** ZITADEL 应用的 Client ID(PKCE 公共客户端,无 secret) **/
|
||||
client_id: string;
|
||||
/** 是否启用(登录页显示统一登录入口) **/
|
||||
enabled: boolean;
|
||||
/** JIT:未绑定的统一登录身份是否自动创建本地用户(创建后即管理员) **/
|
||||
jit: boolean;
|
||||
}
|
||||
|
||||
/** # 成员变量: 生效配置(source 标明来源,同 Cloudflare OAuth 的语义) **/
|
||||
export interface OidcConfig {
|
||||
issuer: string;
|
||||
clientId: string;
|
||||
enabled: boolean;
|
||||
jit: boolean;
|
||||
/** settings = 后台设置;env = 部署环境变量兜底;none = 未配置 */
|
||||
source: "settings" | "env" | "none";
|
||||
}
|
||||
|
||||
/** # 成员变量: discovery 拿到的端点 **/
|
||||
export interface OidcEndpoints {
|
||||
authorization_endpoint: string;
|
||||
token_endpoint: string;
|
||||
userinfo_endpoint: string;
|
||||
}
|
||||
|
||||
/** # 成员变量: discovery 缓存(issuer → 端点),IdP 不可达时沿用旧值,不影响已登录会话 **/
|
||||
const discoveryCache = new Map<string, { fetchedAt: number; endpoints: OidcEndpoints }>();
|
||||
|
||||
/** # 成员变量: discovery 缓存有效期(毫秒) **/
|
||||
const DISCOVERY_TTL_MS = 3600 * 1000;
|
||||
|
||||
/** # 函数
|
||||
* 读取生效的 OIDC 配置:settings 优先,env 兜底;两处都没有返回 null
|
||||
*/
|
||||
export async function getOidcConfig(env: Env): Promise<OidcConfig | null> {
|
||||
const raw = await getSetting(env, OIDC_SETTING_KEY);
|
||||
if (raw) {
|
||||
try {
|
||||
const cfg = JSON.parse(raw) as Partial<OidcConfigSetting>;
|
||||
if (cfg.issuer && cfg.client_id) {
|
||||
return {
|
||||
issuer: cfg.issuer,
|
||||
clientId: cfg.client_id,
|
||||
enabled: cfg.enabled !== false && Boolean(cfg.issuer && cfg.client_id),
|
||||
jit: cfg.jit !== false,
|
||||
source: "settings",
|
||||
};
|
||||
}
|
||||
} catch {
|
||||
// settings 损坏时落到 env 兜底
|
||||
}
|
||||
}
|
||||
if (env.OIDC_ISSUER && env.OIDC_CLIENT_ID) {
|
||||
return {
|
||||
issuer: env.OIDC_ISSUER.replace(/\/+$/, ""),
|
||||
clientId: env.OIDC_CLIENT_ID,
|
||||
enabled: env.OIDC_ENABLED !== "false",
|
||||
jit: true,
|
||||
source: "env",
|
||||
};
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 校验 issuer URL:必须是 https(本机 localhost 允许 http 便于联调)
|
||||
* 返回值: 合法返回 null,否则返回中文错误信息
|
||||
*/
|
||||
export function validateIssuerUrl(issuer: string): string | null {
|
||||
let u: URL;
|
||||
try {
|
||||
u = new URL(issuer);
|
||||
} catch {
|
||||
return "Issuer 不是合法 URL";
|
||||
}
|
||||
const localhost = ["localhost", "127.0.0.1", "[::1]", "::1"].includes(u.hostname);
|
||||
if (u.protocol !== "https:" && !localhost) return "Issuer 必须是 HTTPS 地址";
|
||||
return null;
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 统一登录回调地址(需要在 ZITADEL 控制台应用里登记)
|
||||
*/
|
||||
export function oidcRedirectUri(origin: string): string {
|
||||
return `${origin}/auth/callback`;
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 拉取(带缓存)IdP 的 OIDC discovery 端点
|
||||
* 参数: env - 运行环境;issuer - 签发者
|
||||
* 返回值: authorization/token/userinfo 三端点;IdP 不可达且无缓存时抛错(不 panic,由路由转 502/跳错误)
|
||||
*/
|
||||
export async function discoverOidcEndpoints(env: Env, issuer: string): Promise<OidcEndpoints> {
|
||||
const hit = discoveryCache.get(issuer);
|
||||
if (hit && Date.now() - hit.fetchedAt < DISCOVERY_TTL_MS) return hit.endpoints;
|
||||
const resp = await fetch(`${issuer}/.well-known/openid-configuration`, {
|
||||
headers: { Accept: "application/json" },
|
||||
signal: AbortSignal.timeout(10_000),
|
||||
});
|
||||
if (!resp.ok) throw new Error(`discovery ${resp.status}`);
|
||||
const doc = (await resp.json()) as Partial<OidcEndpoints>;
|
||||
if (!doc.authorization_endpoint || !doc.token_endpoint || !doc.userinfo_endpoint) {
|
||||
throw new Error("discovery missing endpoints");
|
||||
}
|
||||
const endpoints: OidcEndpoints = {
|
||||
authorization_endpoint: doc.authorization_endpoint,
|
||||
token_endpoint: doc.token_endpoint,
|
||||
userinfo_endpoint: doc.userinfo_endpoint,
|
||||
};
|
||||
discoveryCache.set(issuer, { fetchedAt: Date.now(), endpoints });
|
||||
return endpoints;
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 清空 discovery 缓存(测试用)
|
||||
*/
|
||||
export function resetOidcDiscoveryCache(): void {
|
||||
discoveryCache.clear();
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 生成 PKCE code_verifier 与 S256 code_challenge(RFC 7636)
|
||||
*/
|
||||
export async function createPkce(): Promise<{ verifier: string; challenge: string }> {
|
||||
const bytes = crypto.getRandomValues(new Uint8Array(32));
|
||||
const verifier = base64Url(bytes);
|
||||
const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
|
||||
return { verifier, challenge: base64Url(new Uint8Array(digest)) };
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 构造授权端点跳转 URL(Authorization Code + PKCE;state 由调用方生成并存库)
|
||||
*/
|
||||
export function buildOidcAuthorizeUrl(args: {
|
||||
authorizationEndpoint: string;
|
||||
clientId: string;
|
||||
redirectUri: string;
|
||||
state: string;
|
||||
codeChallenge: string;
|
||||
}): string {
|
||||
const q = new URLSearchParams({
|
||||
client_id: args.clientId,
|
||||
redirect_uri: args.redirectUri,
|
||||
response_type: "code",
|
||||
scope: OIDC_SCOPES,
|
||||
state: args.state,
|
||||
code_challenge: args.codeChallenge,
|
||||
code_challenge_method: "S256",
|
||||
});
|
||||
return `${args.authorizationEndpoint}?${q.toString()}`;
|
||||
}
|
||||
|
||||
/** # 成员变量: userinfo 返回的身份字段(全部可为空,除 sub) **/
|
||||
export interface OidcUserInfo {
|
||||
sub: string;
|
||||
name?: string;
|
||||
given_name?: string;
|
||||
family_name?: string;
|
||||
preferred_username?: string;
|
||||
nickname?: string;
|
||||
email?: string;
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 用授权码换 token 并访问 userinfo 取身份(服务端瞬时使用,令牌不落库不外传)
|
||||
* 说明:身份取自 userinfo 的 sub —— access_token 是本服务直接从 token 端点(TLS)换来的,
|
||||
* 绑定到本次 state 校验通过的会话,无需再做 ID Token 签名验证
|
||||
* 参数: endpoints - discovery 端点;clientId/redirectUri - 与发起时一致;code - 授权码;verifier - PKCE verifier
|
||||
* 返回值: userinfo;换码或 userinfo 失败抛错(调用方 fail closed)
|
||||
*/
|
||||
export async function exchangeOidcCode(args: {
|
||||
endpoints: OidcEndpoints;
|
||||
clientId: string;
|
||||
redirectUri: string;
|
||||
code: string;
|
||||
verifier: string;
|
||||
}): Promise<OidcUserInfo> {
|
||||
const body = new URLSearchParams({
|
||||
grant_type: "authorization_code",
|
||||
code: args.code,
|
||||
redirect_uri: args.redirectUri,
|
||||
client_id: args.clientId,
|
||||
code_verifier: args.verifier,
|
||||
});
|
||||
const tokenResp = await fetch(args.endpoints.token_endpoint, {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
|
||||
body: body.toString(),
|
||||
signal: AbortSignal.timeout(10_000),
|
||||
});
|
||||
if (!tokenResp.ok) throw new Error(`token endpoint ${tokenResp.status}`);
|
||||
const token = (await tokenResp.json()) as { access_token?: string; token_type?: string };
|
||||
if (!token.access_token) throw new Error("token response missing access_token");
|
||||
const uiResp = await fetch(args.endpoints.userinfo_endpoint, {
|
||||
headers: { Authorization: `Bearer ${token.access_token}`, Accept: "application/json" },
|
||||
signal: AbortSignal.timeout(10_000),
|
||||
});
|
||||
if (!uiResp.ok) throw new Error(`userinfo ${uiResp.status}`);
|
||||
const ui = (await uiResp.json()) as OidcUserInfo;
|
||||
if (!ui.sub) throw new Error("userinfo missing sub");
|
||||
return ui;
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 展示名兜底链(docs/12):name → given+family → preferred_username → nickname → 邮箱本地部分 → "统一账号 " + subject 前 12 位
|
||||
*/
|
||||
export function oidcDisplayName(ui: OidcUserInfo): string {
|
||||
const chain = [
|
||||
ui.name?.trim(),
|
||||
[ui.given_name?.trim(), ui.family_name?.trim()].filter(Boolean).join(" ").trim() || null,
|
||||
ui.preferred_username?.trim(),
|
||||
ui.nickname?.trim(),
|
||||
ui.email?.includes("@") ? ui.email.split("@")[0] : null,
|
||||
`统一账号 ${ui.sub.slice(0, 12)}`,
|
||||
];
|
||||
for (const v of chain) if (v) return v;
|
||||
return `统一账号 ${ui.sub.slice(0, 12)}`;
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 解析或按 JIT 建立统一登录身份对应的本地用户
|
||||
* 参数: env - 运行环境;cfg - 生效配置;ui - userinfo;issuer - 签发者
|
||||
* 返回值: 本地用户 id 与用户名;未绑定且 JIT 关闭返回 null
|
||||
*/
|
||||
export async function resolveOrProvisionIdentity(
|
||||
env: Env,
|
||||
cfg: OidcConfig,
|
||||
issuer: string,
|
||||
ui: OidcUserInfo,
|
||||
): Promise<{ userId: string; username: string; created: boolean } | null> {
|
||||
const existing = await env.DB.prepare("SELECT user_id FROM oidc_identities WHERE issuer = ? AND subject = ?")
|
||||
.bind(issuer, ui.sub)
|
||||
.first<{ user_id: string }>();
|
||||
const now = nowIso();
|
||||
const displayName = oidcDisplayName(ui);
|
||||
if (existing) {
|
||||
// 重复绑定同一 subject:刷新资料,不报冲突
|
||||
await env.DB.prepare("UPDATE oidc_identities SET display_name = ?, email = ?, updated_at = ? WHERE issuer = ? AND subject = ?")
|
||||
.bind(displayName, ui.email ?? null, now, issuer, ui.sub)
|
||||
.run();
|
||||
const user = await env.DB.prepare("SELECT id, username FROM users WHERE id = ?")
|
||||
.bind(existing.user_id)
|
||||
.first<{ id: string; username: string }>();
|
||||
if (user) return { userId: user.id, username: user.username, created: false };
|
||||
// 身份指向的用户被删:落回 JIT 流程重建
|
||||
}
|
||||
if (!cfg.jit) return null;
|
||||
const userId = ids.user();
|
||||
const username = await uniqueUsername(env, displayName);
|
||||
// 密码哈希用随机串:该账号不能被密码登录,只能走统一登录(管理员可在设置里改密)
|
||||
const randomPassword = base64Url(crypto.getRandomValues(new Uint8Array(24)));
|
||||
await env.DB.prepare("INSERT INTO users (id, username, password_hash, created_at) VALUES (?, ?, ?, ?)")
|
||||
.bind(userId, username, await hashPassword(randomPassword), now)
|
||||
.run();
|
||||
await env.DB.prepare(
|
||||
`INSERT INTO oidc_identities (id, issuer, subject, user_id, display_name, email, created_at, updated_at)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
|
||||
ON CONFLICT(issuer, subject) DO UPDATE SET user_id = excluded.user_id,
|
||||
display_name = excluded.display_name, email = excluded.email, updated_at = excluded.updated_at`,
|
||||
)
|
||||
.bind(ids.identity(), issuer, ui.sub, userId, displayName, ui.email ?? null, now, now)
|
||||
.run();
|
||||
return { userId, username, created: true };
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 由展示名生成不冲突的本地用户名(小写字母/数字/_.-,2-32 位,冲突追加 -2/-3…)
|
||||
*/
|
||||
async function uniqueUsername(env: Env, base: string): Promise<string> {
|
||||
let slug = base.toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "").slice(0, 32);
|
||||
if (slug.length < 2) slug = `sso-${slug}`.slice(0, 32);
|
||||
let candidate = slug;
|
||||
for (let i = 2; ; i++) {
|
||||
const dup = await env.DB.prepare("SELECT id FROM users WHERE username = ?").bind(candidate).first();
|
||||
if (!dup) return candidate;
|
||||
candidate = `${slug.slice(0, 29)}-${i}`;
|
||||
}
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 校验回跳路径:只接受站内路径(防开放重定向)
|
||||
*/
|
||||
export function safeLocalPath(p: string | null | undefined): string {
|
||||
if (p && p.startsWith("/") && !p.startsWith("//") && !p.includes("\\")) return p;
|
||||
return "/";
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* bytes → base64url(无填充)
|
||||
*/
|
||||
function base64Url(bytes: Uint8Array): string {
|
||||
let bin = "";
|
||||
for (const b of bytes) bin += String.fromCharCode(b);
|
||||
return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 保存后台 OIDC 配置(settings 表)
|
||||
*/
|
||||
export async function saveOidcConfig(
|
||||
env: Env,
|
||||
cfg: { issuer: string; client_id: string; enabled: boolean; jit: boolean },
|
||||
): Promise<void> {
|
||||
await setSetting(env, OIDC_SETTING_KEY, JSON.stringify(cfg));
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 读取后台保存的原始 OIDC 配置(未保存返回 null;用于保存时合并开关)
|
||||
*/
|
||||
export async function readOidcSettingRaw(env: Env): Promise<OidcConfigSetting | null> {
|
||||
const raw = await getSetting(env, OIDC_SETTING_KEY);
|
||||
if (!raw) return null;
|
||||
try {
|
||||
return JSON.parse(raw) as OidcConfigSetting;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 清除后台保存的 OIDC 配置(env 兜底仍可用)
|
||||
*/
|
||||
export async function clearOidcConfig(env: Env): Promise<void> {
|
||||
await env.DB.prepare("DELETE FROM settings WHERE key = ?").bind(OIDC_SETTING_KEY).run();
|
||||
}
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
Webhook、API、MCP 全部属于 Console,Email Worker 不实现这些能力。
|
||||
|
||||
> 全量 HTTP 端点参考(含 Console Web API、/api/v1、MCP、/auth 统一登录)见 [docs/API.md](./API.md);本文只讲设计要点。
|
||||
|
||||
## Webhook(三级:邮箱 -> 域名 -> 全局)
|
||||
|
||||
收到邮件后按 邮箱 -> 域名 -> 全局 的顺序取第一个已配置的 Webhook(无配置则逐级回退),
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
# 12. ZITADEL 统一登录(v2.9.0)
|
||||
|
||||
Console 支持通过自建 ZITADEL 实例做 SSO 登录:OIDC **Authorization Code + PKCE**(公共客户端,无 client secret),与用户名密码登录双通道并存,互不替代。
|
||||
|
||||
## 12.1 配置
|
||||
|
||||
入口:设置 → **ZITADEL 统一登录** tab。配置存 settings 表,部署环境变量兜底(与 Cloudflare OAuth 同语义):
|
||||
|
||||
| 来源 | 说明 |
|
||||
|------|------|
|
||||
| `settings` | 后台设置保存的 `{ issuer, client_id, enabled, jit }`(主) |
|
||||
| `env` | `OIDC_ISSUER` + `OIDC_CLIENT_ID`(可选 `OIDC_ENABLED=false` 关闭) |
|
||||
| `none` | 未配置,登录页不显示统一登录入口 |
|
||||
|
||||
- **Issuer**:如 `https://auth.my.qiaonao.net`(必须 HTTPS;本机联调允许 `http://localhost`)。
|
||||
- **Client ID**:在 ZITADEL 控制台(项目 → 应用)为 WmailHub 建应用,认证方式选 Code + PKCE,不需要 secret。
|
||||
- **回调地址(Redirect URI)**:`{Console origin}/auth/callback`,必须登记进 ZITADEL 应用。
|
||||
- **Scope**:固定 `openid profile`(userinfo 取身份;实例未配 SMTP 时拿不到 email claim,不影响登录)。
|
||||
|
||||
## 12.2 流程与安全
|
||||
|
||||
```
|
||||
GET /auth/status 公开探测 { enabled, issuer }(登录页据此显示按钮)
|
||||
GET /auth/login 生成 state + PKCE verifier 存 oidc_states(10 分钟,一次性)→ 302 授权端点
|
||||
GET /auth/callback state 用后即删 → code 换 token → userinfo 取 sub → 解析/JIT 建号 → 签发本地会话 cookie → 302 /
|
||||
```
|
||||
|
||||
- 身份主键 **(issuer, subject)**,存 `oidc_identities`;email 只是资料展示,**绝不作为身份键**(实例无 SMTP,邮箱可能缺失)。
|
||||
- 令牌只在服务端瞬时使用(换 userinfo),不落库、不进前端、不进日志;身份取 userinfo 的 `sub`,不做 ID Token 签名验证(access_token 由本服务直接从 token 端点换得)。
|
||||
- 回跳路径只接受站内路径(防开放重定向);所有失败 302 回 `/login?error=<code>`,登录页映射中文文案。
|
||||
- 本地会话(HMAC cookie)独立于 IdP:IdP 挂掉时已登录用户不受影响;IdP 不可达时 discovery 报错走 `oidc_unavailable`,进程不 panic。
|
||||
|
||||
## 12.3 账号模型
|
||||
|
||||
- **登录成功即管理员**:本平台没有权限设置,任何能完成统一登录的身份与密码登录用户权限完全一致。
|
||||
- **JIT(自动建号)**:设置里可开关(默认开)。开启时未绑定的身份首次登录自动创建本地用户(用户名取展示名兜底链 slug 化,冲突加 `-2/-3`;密码哈希为随机串,即该账号不能密码登录);关闭时未绑定身份拒绝登录(`oidc_not_linked`)。
|
||||
- 展示名兜底链:`name` → `given_name + family_name` → `preferred_username` → `nickname` → 邮箱本地部分 → `统一账号 <sub 前 12 位>`。
|
||||
- 重复登录同一 subject:刷新 `display_name/email` 资料,不报冲突。
|
||||
- **登出仅清本地会话**,不做 IdP end_session(避免把整个 ZITADEL SSO 会话登掉,影响其他接入应用)——有意偏离,非遗漏。
|
||||
|
||||
## 12.4 数据库(migrations/0006)
|
||||
|
||||
- `oidc_identities(id, issuer, subject, user_id, display_name, email, created_at, updated_at)`,UNIQUE(issuer, subject)
|
||||
- `oidc_states(state, code_verifier, return_to, created_at, expires_at)`,一次性
|
||||
|
||||
## 12.5 验收自查(v2.9.0 实测)
|
||||
|
||||
- [x] Authorization Code + PKCE(S256),非 implicit(token 请求带 `code_verifier` 有测试)
|
||||
- [x] state 一次性、10 分钟过期、校验后才换码(重放测试)
|
||||
- [x] 令牌不落前端、不落库、不进日志
|
||||
- [x] 身份主键 (issuer, subject),email 仅资料
|
||||
- [x] 本地会话独立于 IdP;登录页/应用无 token 互踢死循环(前端无 token 概念,纯 cookie 会话)
|
||||
- [x] 登出仅本地会话(有意偏离,见 12.3)
|
||||
- [x] 密码登录通道完整保留(回归测试覆盖)
|
||||
- [x] JIT 可配置;开启时建号即管理员(按需求)
|
||||
- [x] 日志无敏感信息(operation_logs 只记动作/用户名/issuer/开关布尔)
|
||||
+275
@@ -0,0 +1,275 @@
|
||||
# WmailHub API 文档
|
||||
|
||||
适用版本:**v2.9.0**(版本号以 `/api/health` 返回为准)。Base URL:生产 `https://wmailhub.adx9.com`,本地开发 `http://127.0.0.1:18787`。
|
||||
|
||||
## 目录
|
||||
|
||||
- [认证方式](#认证方式)
|
||||
- [健康检查与探测](#健康检查与探测)
|
||||
- [登录会话 API(/api/auth)](#登录会话-apiapiauth)
|
||||
- [ZITADEL 统一登录(/auth)](#zitadel-统一登录auth)
|
||||
- [Console Web API(/api/*,Cookie 会话)](#console-web-apiapi-cookie-会话)
|
||||
- [开放 API(/api/v1/*,Bearer Key)](#开放-apiapiv1bearer-key)
|
||||
- [MCP(/api/v1/mcp)](#mcpapiv1mcp)
|
||||
- [Webhook(收件推送)](#webhook收件推送)
|
||||
- [内部 API(/internal,Email Worker 专用)](#内部-apiinternalemail-worker-专用)
|
||||
- [错误码约定](#错误码约定)
|
||||
|
||||
---
|
||||
|
||||
## 认证方式
|
||||
|
||||
三套通道并存,按端点区分:
|
||||
|
||||
| 通道 | 适用端点 | 凭据 |
|
||||
|------|----------|------|
|
||||
| **Cookie 会话** | `/api/auth/*`、`/api/*`(Console Web)、`/api/admin/*`、`/api/settings/*`、`/api/oauth/*` | 登录后 `wmh_session` Cookie(HttpOnly,7 天) |
|
||||
| **Bearer Key** | `/api/v1/*`(含 `/api/v1/mcp`) | `Authorization: Bearer wmh_…`(32 位;API 与 MCP 共用同一 Key) |
|
||||
| **HMAC 签名** | `/internal/*` | Email Worker 专用,见 docs/04 / docs/11 |
|
||||
|
||||
- Key 在 **设置 → 全局 Webhook → API / MCP Key** 生成/轮换/撤销;明文仅生成时返回一次,服务端只存 SHA-256;新 Key 生成后旧 Key 立即失效。
|
||||
- Cookie 会话的写请求有 CSRF 防护:带 Cookie 时 `Origin`/`Referer` 必须与站点 Host 一致,否则 403。Bearer Key 调用不受影响。
|
||||
|
||||
## 健康检查与探测
|
||||
|
||||
### GET /api/health
|
||||
|
||||
公开。返回 `{ ok: true, name: "WmailHub", version: "2.9.0" }`。
|
||||
|
||||
### GET /auth/status
|
||||
|
||||
公开。统一登录探测:返回 `{ enabled: boolean, issuer: string | null }`,登录页据此显示「ZITADEL 统一登录」按钮。
|
||||
|
||||
## 登录会话 API(/api/auth)
|
||||
|
||||
### POST /api/auth/login
|
||||
|
||||
```json
|
||||
{ "username": "admin", "password": "admin" }
|
||||
```
|
||||
|
||||
成功 `200 { ok: true, user: { id, username } }` 并下发会话 Cookie;失败 `401 {"error":"invalid username or password"}`。默认账号 `admin / admin`(首次启动自动播种)。
|
||||
|
||||
### POST /api/auth/logout
|
||||
|
||||
清除会话 Cookie,返回 `{ ok: true }`。(ZITADEL 登录的用户同样只清本地会话,IdP 侧 SSO 会话保留。)
|
||||
|
||||
### GET /api/auth/me
|
||||
|
||||
返回当前用户 `{ user: { id, username }, now }`;未登录 `401`。用户名以库内实时数据为准。
|
||||
|
||||
## ZITADEL 统一登录(/auth)
|
||||
|
||||
OIDC Authorization Code + PKCE(无 client secret),与密码登录双通道并存;**登录成功即管理员**(本平台没有权限设置)。配置入口:设置 → ZITADEL 统一登录(issuer + client_id;回调地址 `{origin}/auth/callback` 需登记到 ZITADEL 应用)。详细设计见 docs/12。
|
||||
|
||||
| 端点 | 说明 |
|
||||
|------|------|
|
||||
| `GET /auth/login` | 发起授权,302 到 IdP;可选 `?return=/<站内路径>` 指定回跳(默认 `/`)。未启用 302 → `/login?error=oidc_disabled` |
|
||||
| `GET /auth/callback` | IdP 回调(浏览器重定向,无需调用):一次性 state 校验 → 换码 → userinfo → 建号/匹配 → 下发会话 Cookie → 302 回站内;失败 302 → `/login?error=<code>` |
|
||||
|
||||
错误码:`oidc_disabled` / `oidc_unavailable` / `state_invalid` / `oidc_exchange_failed` / `oidc_not_linked`(JIT 关闭且身份未绑定)。
|
||||
|
||||
## Console Web API(/api/*,Cookie 会话)
|
||||
|
||||
以下端点未登录一律 `401`。分页参数统一 `limit`(默认 20,最大 100)与 `offset`,列表返回 `{ items, total }`。
|
||||
|
||||
### Cloudflare 账号 /api/accounts
|
||||
|
||||
| 方法与路径 | 说明 |
|
||||
|------------|------|
|
||||
| `GET /api/accounts` | 账号列表 |
|
||||
| `GET /api/accounts/:id` | 账号详情(接入步骤、OAuth 连接、域名、Worker 凭据) |
|
||||
| `PATCH /api/accounts/:id` | 改名 `{ name }` |
|
||||
| `DELETE /api/accounts/:id` | 删除账号(级联清理 Cloudflare 侧 Email Routing/Worker,尽力而为) |
|
||||
| `POST /api/accounts/batch-delete` | 批量删除 `{ ids: string[] }` → `{ ok, deleted, failed[] }` |
|
||||
| `POST /api/accounts/token` | API Token 接入 `{ name, token }`(后端先探 Cloudflare 再接入)→ `{ ok, account_id }` |
|
||||
| `POST /api/accounts/:id/rotate` | 轮换 Worker 凭据;secret 仅本次返回,已配域名自动重部署 |
|
||||
| `GET /api/accounts/:id/worker-secret` | 本地/运维:读取当前 Worker credential |
|
||||
|
||||
### 域名 /api/domains
|
||||
|
||||
| 方法与路径 | 说明 |
|
||||
|------------|------|
|
||||
| `GET /api/domains` | 域名列表(含各域名 Webhook 配置与邮箱计数) |
|
||||
| `GET /api/domains/filters/accounts` | 账号筛选项 |
|
||||
| `POST /api/domains/:id/setup` | 配置 Email Workers(部署 Worker + 开 Routing + catch-all)→ `{ ok, error? }` |
|
||||
| `PUT /api/domains/:id/webhook` | 域名级 Webhook `{ url, headers?, key? }`(url 空串清除;key undefined 保留、空格清除) |
|
||||
| `DELETE /api/domains/:id/webhook` | 清除域名级 Webhook |
|
||||
| `DELETE /api/domains/:id` / `POST /api/domains/batch-delete` | 删除(级联邮箱与邮件) |
|
||||
|
||||
### 邮箱 /api/mailboxes
|
||||
|
||||
| 方法与路径 | 说明 |
|
||||
|------------|------|
|
||||
| `GET /api/mailboxes?domain_id=` | 邮箱列表 |
|
||||
| `POST /api/mailboxes` | 创建 `{ domain_id, address, retention_seconds?, catch_all? }` → `{ ok, id, address }`;重名 409 |
|
||||
| `PATCH /api/mailboxes/:id` | `{ status?: "active"\|"disabled", retention_seconds?: number\|null }`(null=回到全局默认 86400 秒) |
|
||||
| `PUT /api/mailboxes/:id/webhook` | 邮箱级 Webhook,语义同域名级 |
|
||||
| `DELETE /api/mailboxes/:id/webhook` | 清除邮箱级 Webhook |
|
||||
| `DELETE /api/mailboxes/:id` / `POST /api/mailboxes/batch-delete` | 删除 |
|
||||
|
||||
Webhook 生效顺序:**邮箱 → 域名 → 全局**,取第一个已配置的。
|
||||
|
||||
### 邮件 /api/emails
|
||||
|
||||
| 方法与路径 | 说明 |
|
||||
|------------|------|
|
||||
| `GET /api/emails?domain_id=&mailbox_id=&q=&limit=&offset=` | 列表(仅未过期) |
|
||||
| `GET /api/emails/:id` | 详情(正文 text/html/markdown + 附件列表);过期 `410` |
|
||||
| `GET /api/emails/:id/attachments/:attId` | 下载附件 |
|
||||
| `GET /api/emails/:id/raw` | 原始 EML |
|
||||
| `DELETE /api/emails/:id` / `POST /api/emails/batch-delete` | 删除 |
|
||||
| `POST /api/emails/retain` | 保留 `{ ids }`(永不过期,Cron 跳过)→ `{ ok, retained }` |
|
||||
|
||||
### 操作日志 /api/logs
|
||||
|
||||
`GET /api/logs?target_type=&action=&q=&limit=&offset=`。`target_type` ∈ `account/domain/mailbox/email/webhook/user/settings`;库里最多保留 10000 条。
|
||||
|
||||
### 设置 /api/settings
|
||||
|
||||
| 方法与路径 | 说明 |
|
||||
|------------|------|
|
||||
| `GET /api/settings` | 全量读取:当前用户名、全局 Webhook(key 只回 last4)、API Key 元信息、Cloudflare OAuth、ZITADEL 统一登录(含回调地址与当前账号绑定身份) |
|
||||
| `PUT /api/settings` | 保存 `{ webhook?, cf_oauth?, oidc? }`;`webhook.key`/`cf_oauth.secret`:undefined 保留、空串清除、非空设置;`oidc: { issuer, client_id, enabled?, jit? }`(开关缺省沿用已存值) |
|
||||
| `PUT /api/settings/password` | 改密码 `{ old_password, new_password }`(≥6 位) |
|
||||
| `PUT /api/settings/username` | 改用户名 `{ new_username, password }`(需当前密码;2-32 位字母/数字/`_ . -`;成功重签会话 Cookie;重名 409) |
|
||||
| `POST /api/settings/api-key` | 生成(轮换)API/MCP Key → `201 { key, created_at }`(明文仅此一次) |
|
||||
| `DELETE /api/settings/api-key` | 撤销并删除 Key |
|
||||
| `DELETE /api/settings/cf-oauth` | 清除 Cloudflare OAuth 凭据(env 兜底仍可用) |
|
||||
| `DELETE /api/settings/oidc` | 清除统一登录配置(已建立的绑定保留) |
|
||||
|
||||
### Cloudflare OAuth /api/oauth
|
||||
|
||||
| 方法与路径 | 说明 |
|
||||
|------------|------|
|
||||
| `GET /api/oauth/mode` | `{ mode: "cloudflare"|"unconfigured", source, scope }` |
|
||||
| `GET /api/oauth/cloudflare/start` | 生成一次性 state,返回 `{ url, state }`(浏览器跳 url 完成授权) |
|
||||
| `GET /api/oauth/cloudflare/callback` | 授权回调(浏览器重定向,无需调用) |
|
||||
| `GET /api/oauth/cloudflare/preflight` | 授权配置自检(探测 Cloudflare 授权端点 + scope 探测) |
|
||||
| `GET /api/oauth/connections` | 已建立的 OAuth 连接(不含 token) |
|
||||
|
||||
### 管理 /api/admin
|
||||
|
||||
`GET /api/admin/version`;`GET /api/admin/stats`(Dashboard 统计 + 最近 8 封邮件);`POST /api/admin/cron/run`(手动触发 TTL 清理与 Webhook 投递)。
|
||||
|
||||
## 开放 API(/api/v1/*,Bearer Key)
|
||||
|
||||
认证:`Authorization: Bearer wmh_…`;无 Key/Key 无效 `401`。所有邮件读取强制只返回**未过期**邮件。
|
||||
|
||||
### GET /api/v1/accounts
|
||||
|
||||
`{ items: [{ id, name, cloudflare_account_id, worker_id, status, created_at }] }`
|
||||
|
||||
### GET /api/v1/domains
|
||||
|
||||
`{ items: [{ id, name, status, account_id, created_at }] }`
|
||||
|
||||
### GET /api/v1/mailboxes
|
||||
|
||||
`{ items: [{ id, address, status, is_catch_all, retention_seconds, domain_id, domain_name }] }`
|
||||
|
||||
### POST /api/v1/mailboxes
|
||||
|
||||
```json
|
||||
{ "domain_id": "dom_xxx", "address": "hello", "retention_seconds": 86400, "webhook": "https://hooks.example.com/wmail" }
|
||||
```
|
||||
|
||||
- `domain_id` **可省略(v2.8.0 起)**:随机分配一个已启用 Email Workers 的域名;此时 `address` 必须为本地部分(不带 `@`)。
|
||||
- `webhook` **可选(v2.8.0 起)**:创建时直接配置邮箱级 Webhook(先校验再建邮箱,校验失败不留半截数据;SSRF 规则同 Console——拒绝私网/localhost/元数据地址)。
|
||||
- 返回 `201 { ok: true, id, address, webhook? }`;错误:`400 address required` / `404 domain not found` / `409 mailbox already exists` / `409 no available domain (none has Email Workers enabled)`。
|
||||
|
||||
### DELETE /api/v1/mailboxes/:id
|
||||
|
||||
成功 `{ ok: true }`;不存在 `404`。
|
||||
|
||||
### GET /api/v1/emails?mailbox_id=&limit=&offset=
|
||||
|
||||
`{ items: [{ id, mailbox_id, mailbox_address, message_id, from_address, to_addresses, subject, size, received_at, expires_at }] }`(仅未过期)。
|
||||
|
||||
### GET /api/v1/emails/:id
|
||||
|
||||
`{ email: { …全字段含 text_body/html_body/markdown_body }, attachments: [{ id, filename, content_type, size, content_id }] }`;不存在 `404`,已过期 `410 {"error":"email expired"}`。
|
||||
|
||||
#### curl 示例
|
||||
|
||||
```bash
|
||||
KEY="wmh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||
BASE="https://wmailhub.adx9.com"
|
||||
|
||||
# 随机域名建邮箱 + 邮箱级 Webhook
|
||||
curl -s -X POST "$BASE/api/v1/mailboxes" \
|
||||
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
|
||||
-d '{"address":"hello","webhook":"https://hooks.example.com/wmail"}'
|
||||
|
||||
# 拉最近邮件(取第一条详情)
|
||||
curl -s -H "Authorization: Bearer $KEY" "$BASE/api/v1/emails?limit=1"
|
||||
```
|
||||
|
||||
## MCP(/api/v1/mcp)
|
||||
|
||||
Streamable HTTP(JSON-RPC 2.0,协议版本 `2025-06-18`),**仅 POST**(GET → 405),Bearer Key 与 API 共用。方法:`initialize` → `notifications/initialized` → `tools/list` / `tools/call`;`ping` 可用。
|
||||
|
||||
MCP 客户端配置:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"wmailhub": {
|
||||
"type": "http",
|
||||
"url": "https://wmailhub.adx9.com/api/v1/mcp",
|
||||
"headers": { "Authorization": "Bearer wmh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 工具清单(v2.9.0 共 6 个)
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `list_domains` | — | 列出可用域名(创建邮箱的 domain_id 由此获取) |
|
||||
| `list_mailboxes` | — | 列出邮箱(含域名与保留策略) |
|
||||
| `list_emails` | `mailbox_id?`, `limit?` | 列出未过期邮件(按收到时间倒序) |
|
||||
| `get_email` | `email_id` | 邮件详情(正文 + 附件);过期返回资源错误 -32002 |
|
||||
| `create_mailbox` | `address`, `domain_id?`, `retention_seconds?`, `webhook?` | 创建邮箱;`domain_id` 省略时随机分配(此时 address 须为本地部分);`webhook` 为可选邮箱级 Webhook URL |
|
||||
| `delete_mailbox` | `mailbox_id` | 删除邮箱 |
|
||||
|
||||
错误约定:`-32601` 未知方法/工具、`-32602` 参数错误、`-32002` 资源不存在(如邮件过期)。
|
||||
|
||||
## Webhook(收件推送)
|
||||
|
||||
收到邮件时按 邮箱 → 域名 → 全局 取第一个已配置的 Webhook 入队投递。Payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "email.received",
|
||||
"id": "msg_xxx",
|
||||
"mailbox": "hello@example.com",
|
||||
"from": "user@example.org",
|
||||
"to": ["hello@example.com"],
|
||||
"subject": "Hello",
|
||||
"text": "Hello World",
|
||||
"markdown": "Hello **World**",
|
||||
"received_at": "2026-09-30T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
请求头:`X-WmailHub-Event`、`X-WmailHub-Delivery`、`X-WmailHub-Timestamp`、`X-WmailHub-Signature`(签名 = `HMAC-SHA256(key, "<timestamp>.<body>")`,配了 key 才有);配置 key 时默认携带 `Authorization: Bearer <key>`,自定义头优先。`2xx` 为成功;5xx/超时按指数退避重试,耗尽后置 `exhausted`;Cron 周期性重投 `pending/failed`。
|
||||
|
||||
## 内部 API(/internal,Email Worker 专用)
|
||||
|
||||
`POST /internal/email/authorize` 与 `POST /internal/email/ingest`:Email Worker 取收件凭据与投递邮件,HMAC 签名认证,协议见 docs/04 与 docs/11,不对外暴露。
|
||||
|
||||
## 错误码约定
|
||||
|
||||
| 状态码 | 场景 |
|
||||
|--------|------|
|
||||
| 400 | 参数缺失/非法(webhook URL 不合法、用户名格式错误等) |
|
||||
| 401 | 未登录 / Bearer Key 缺失或无效 |
|
||||
| 403 | CSRF 校验失败(带 Cookie 的跨源写请求) |
|
||||
| 404 | 资源不存在 |
|
||||
| 409 | 冲突(邮箱已存在、无可用域名、用户名已存在) |
|
||||
| 410 | 邮件已过期(Gone) |
|
||||
| 503 | 依赖未配置(如 Cloudflare OAuth 未配置时添加账号) |
|
||||
|
||||
错误响应统一为 `{"error": "<中文或英文消息>"}`。
|
||||
@@ -0,0 +1,25 @@
|
||||
-- ZITADEL 统一登录(v2.9.0):身份绑定 + 一次性授权 state
|
||||
-- 身份主键是 (issuer, subject),email 仅作资料展示、绝不参与判定(实例无 SMTP,邮箱可能缺失)
|
||||
|
||||
-- OIDC 身份绑定:统一登录账号 ↔ 本地 users 的映射(重复登录同一 subject 刷新资料,不报冲突)
|
||||
CREATE TABLE IF NOT EXISTS oidc_identities (
|
||||
id TEXT PRIMARY KEY,
|
||||
issuer TEXT NOT NULL, -- IdP 签发者(如 https://auth.my.qiaonao.net)
|
||||
subject TEXT NOT NULL, -- IdP 的 sub(身份主键的一部分)
|
||||
user_id TEXT NOT NULL, -- 本地 users.id
|
||||
display_name TEXT, -- 展示名(兜底链取值,可为空)
|
||||
email TEXT, -- 纯资料,可为空,永不作为身份键
|
||||
created_at TEXT NOT NULL,
|
||||
updated_at TEXT NOT NULL,
|
||||
UNIQUE(issuer, subject)
|
||||
);
|
||||
CREATE INDEX IF NOT EXISTS idx_oidc_identities_user ON oidc_identities(user_id);
|
||||
|
||||
-- OIDC 一次性 state:承载 code_verifier(PKCE)与回跳路径,用后即删
|
||||
CREATE TABLE IF NOT EXISTS oidc_states (
|
||||
state TEXT PRIMARY KEY,
|
||||
code_verifier TEXT NOT NULL,
|
||||
return_to TEXT NOT NULL,
|
||||
created_at TEXT NOT NULL,
|
||||
expires_at TEXT NOT NULL
|
||||
);
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "wmailhub",
|
||||
"version": "2.8.0",
|
||||
"version": "2.9.0",
|
||||
"description": "WmailHub - 基于 Cloudflare Email Workers 的轻量邮件接收与转发平台(Console 直连 Email Worker)",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
|
||||
@@ -34,4 +34,6 @@ export const ids = {
|
||||
oauthState: () => newId("st"),
|
||||
credential: () => newId("cred"),
|
||||
log: () => newId("oplog"),
|
||||
/** OIDC 身份绑定 id **/
|
||||
identity: () => newId("oidc"),
|
||||
};
|
||||
|
||||
@@ -0,0 +1,288 @@
|
||||
/**
|
||||
* ZITADEL 统一登录与用户名修改测试(v2.9.0):
|
||||
* - /auth/status、/auth/login(302 到授权端点)、/auth/callback(state 一次性 + PKCE + JIT 建号/复用)
|
||||
* - 未绑定 + JIT 关闭拒绝;配置校验(issuer 必须 HTTPS);discovery/token/userinfo 在传输层打桩
|
||||
* - PUT /api/settings/username:验密、重名 409、改后新旧用户名登录行为、/me 读库返回新名
|
||||
*/
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { authedFetch, loginCookie, makeTestEnv, type TestEnv } from "./helpers.ts";
|
||||
import { resetOidcDiscoveryCache } from "../console/src/services/oidc.ts";
|
||||
|
||||
/** # 成员变量: 桩 IdP 的 issuer(测试配置写入 settings) **/
|
||||
const ISSUER = "https://sso.example.test";
|
||||
|
||||
/** # 成员变量: 桩返回的 userinfo(subject 可按用例切换) **/
|
||||
let mockUserInfo: Record<string, unknown> = { sub: "sub-001", name: "Zed", preferred_username: "zed" };
|
||||
|
||||
/** # 成员变量: 桩记录到的 IdP 调用(token 请求体里应能验到 PKCE verifier 的存在) **/
|
||||
let idpCalls: { url: string; body: string | null }[] = [];
|
||||
|
||||
/** # 成员变量: 真实 fetch(用例结束后恢复) **/
|
||||
const REAL_FETCH = globalThis.fetch;
|
||||
|
||||
/** # 函数
|
||||
* 安装 IdP 传输层打桩:discovery / token / userinfo 三个端点,其余放行
|
||||
*/
|
||||
function installIdpStub() {
|
||||
idpCalls = [];
|
||||
globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
|
||||
const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
|
||||
if (url === `${ISSUER}/.well-known/openid-configuration`) {
|
||||
return Response.json({
|
||||
issuer: ISSUER,
|
||||
authorization_endpoint: `${ISSUER}/oauth/v2/authorize`,
|
||||
token_endpoint: `${ISSUER}/oauth/v2/token`,
|
||||
userinfo_endpoint: `${ISSUER}/oauth/v2/userinfo`,
|
||||
});
|
||||
}
|
||||
if (url === `${ISSUER}/oauth/v2/token`) {
|
||||
idpCalls.push({ url, body: typeof init?.body === "string" ? init.body : null });
|
||||
return Response.json({ access_token: "at_test", token_type: "Bearer", expires_in: 600 });
|
||||
}
|
||||
if (url === `${ISSUER}/oauth/v2/userinfo`) {
|
||||
return Response.json(mockUserInfo);
|
||||
}
|
||||
return REAL_FETCH(input as Request, init);
|
||||
}) as typeof fetch;
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 在测试 env 里启用统一登录(后台 settings 配置,JIT 可选)
|
||||
*/
|
||||
async function enableOidc(t: TestEnv, jit = true) {
|
||||
const cookie = await loginCookie(t);
|
||||
const resp = await authedFetch(t, cookie, "http://localhost/api/settings", {
|
||||
method: "PUT",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ oidc: { issuer: ISSUER, client_id: "cid-123", enabled: true, jit } }),
|
||||
});
|
||||
expect(resp.status).toBe(200);
|
||||
return cookie;
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 走一遍 /auth/login,取回 302 Location 与其中的 state
|
||||
*/
|
||||
async function startLogin(t: import("./helpers.ts").TestEnv) {
|
||||
const resp = await t.app.fetch(new Request("http://localhost/auth/login"), t.env);
|
||||
const loc = resp.headers.get("Location") ?? "";
|
||||
return { resp, loc, state: new URL(loc).searchParams.get("state") ?? "" };
|
||||
}
|
||||
|
||||
/** # 函数
|
||||
* 从 Set-Cookie 头取会话 cookie
|
||||
*/
|
||||
function cookieOf(resp: Response): string {
|
||||
const m = /wmh_session=([^;]+)/.exec(resp.headers.get("Set-Cookie") ?? "");
|
||||
if (!m) throw new Error(`no session cookie: ${resp.headers.get("Set-Cookie")}`);
|
||||
return `wmh_session=${m[1]}`;
|
||||
}
|
||||
|
||||
describe("ZITADEL 统一登录(/auth)", () => {
|
||||
test("未配置时 status enabled=false;/auth/login 拒绝并回登录页", async () => {
|
||||
const t = await makeTestEnv();
|
||||
const status = (await (await t.app.fetch(new Request("http://localhost/auth/status"), t.env)).json()) as { enabled: boolean };
|
||||
expect(status.enabled).toBe(false);
|
||||
const resp = await t.app.fetch(new Request("http://localhost/auth/login"), t.env);
|
||||
expect(resp.status).toBe(302);
|
||||
expect(resp.headers.get("Location")).toContain("/login?error=oidc_disabled");
|
||||
});
|
||||
|
||||
test("配置校验:issuer 非 HTTPS 拒绝(localhost 例外);启用缺 Client ID 拒绝", async () => {
|
||||
const t = await makeTestEnv();
|
||||
const cookie = await loginCookie(t);
|
||||
const put = (body: unknown) =>
|
||||
authedFetch(t, cookie, "http://localhost/api/settings", {
|
||||
method: "PUT",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify(body),
|
||||
});
|
||||
expect((await put({ oidc: { issuer: "ftp://x.example", client_id: "c", enabled: false } })).status).toBe(400);
|
||||
expect((await put({ oidc: { issuer: "", client_id: "c", enabled: false } })).status).toBe(400);
|
||||
expect(
|
||||
(await put({ oidc: { issuer: "http://localhost:8080", client_id: "c", enabled: false } })).status,
|
||||
).toBe(200); // localhost 允许 http(联调)
|
||||
expect((await put({ oidc: { issuer: "https://sso2.example.test", client_id: "", enabled: true } })).status).toBe(400);
|
||||
});
|
||||
|
||||
test("启用后 status=true;发起授权 302 携带 PKCE 与 state,入库一次性", async () => {
|
||||
installIdpStub();
|
||||
resetOidcDiscoveryCache();
|
||||
const t = await makeTestEnv();
|
||||
await enableOidc(t);
|
||||
const status = (await (await t.app.fetch(new Request("http://localhost/auth/status"), t.env)).json()) as { enabled: boolean };
|
||||
expect(status.enabled).toBe(true);
|
||||
|
||||
const { resp, loc, state } = await startLogin(t);
|
||||
expect(resp.status).toBe(302);
|
||||
expect(loc.startsWith(`${ISSUER}/oauth/v2/authorize?`)).toBe(true);
|
||||
expect(loc).toContain("code_challenge_method=S256");
|
||||
expect(loc).toContain("response_type=code");
|
||||
expect(state).toBeTruthy();
|
||||
const row = await t.env.DB.prepare("SELECT code_verifier, return_to FROM oidc_states WHERE state = ?").bind(state).first();
|
||||
expect(row).toBeTruthy();
|
||||
});
|
||||
|
||||
test("完整登录链:JIT 自动建号(即管理员)→ 会话可用 → 同 subject 复用同一用户", async () => {
|
||||
installIdpStub();
|
||||
resetOidcDiscoveryCache();
|
||||
const t = await makeTestEnv();
|
||||
await enableOidc(t, true);
|
||||
mockUserInfo = { sub: "sub-jit", name: "Zed Zhan", email: "zed@wtox.net" };
|
||||
|
||||
// 第一次登录:JIT 建号
|
||||
const first = await startLogin(t);
|
||||
const cb = await t.app.fetch(new Request(`http://localhost/auth/callback?code=good&state=${first.state}`), t.env);
|
||||
expect(cb.status).toBe(302);
|
||||
expect(cb.headers.get("Location")).toBe("/");
|
||||
const cookie1 = cookieOf(cb);
|
||||
const me = (await (await authedFetch(t, cookie1, "http://localhost/api/auth/me")).json()) as {
|
||||
user: { username: string };
|
||||
};
|
||||
expect(me.user.username).toBe("zed-zhan"); // 展示名 slug 化
|
||||
|
||||
// state 一次性:重放同一回调被拒
|
||||
const replay = await t.app.fetch(new Request(`http://localhost/auth/callback?code=good&state=${first.state}`), t.env);
|
||||
expect(replay.headers.get("Location")).toContain("state_invalid");
|
||||
|
||||
// 库里:用户 + 身份绑定 + token 请求带 code_verifier(PKCE)
|
||||
const users = await t.env.DB.prepare("SELECT id, username FROM users").all<{ id: string; username: string }>();
|
||||
expect(users.results.filter((u) => u.username === "zed-zhan")).toHaveLength(1);
|
||||
const ident = await t.env.DB.prepare("SELECT user_id, display_name, email FROM oidc_identities WHERE issuer = ? AND subject = ?")
|
||||
.bind(ISSUER, "sub-jit")
|
||||
.first<{ user_id: string; display_name: string; email: string }>();
|
||||
expect(ident?.email).toBe("zed@wtox.net");
|
||||
expect(idpCalls[0]?.body).toContain("code_verifier=");
|
||||
|
||||
// 第二次登录:同一 subject 复用同一用户,不重复建号
|
||||
const second = await startLogin(t);
|
||||
const cb2 = await t.app.fetch(new Request(`http://localhost/auth/callback?code=good&state=${second.state}`), t.env);
|
||||
expect(cb2.status).toBe(302);
|
||||
const ident2 = await t.env.DB.prepare("SELECT user_id FROM oidc_identities WHERE issuer = ? AND subject = ?")
|
||||
.bind(ISSUER, "sub-jit")
|
||||
.first<{ user_id: string }>();
|
||||
expect(ident2?.user_id).toBe(ident?.user_id);
|
||||
const users2 = await t.env.DB.prepare("SELECT COUNT(*) AS n FROM users").first<{ n: number }>();
|
||||
expect(users2?.n).toBe(2); // admin + zed-zhan
|
||||
});
|
||||
|
||||
test("JIT 关闭:未绑定身份拒绝登录,不建用户", async () => {
|
||||
installIdpStub();
|
||||
resetOidcDiscoveryCache();
|
||||
const t = await makeTestEnv();
|
||||
await enableOidc(t, false);
|
||||
mockUserInfo = { sub: "sub-unknown", preferred_username: "stranger" };
|
||||
const { state } = await startLogin(t);
|
||||
const cb = await t.app.fetch(new Request(`http://localhost/auth/callback?code=good&state=${state}`), t.env);
|
||||
expect(cb.headers.get("Location")).toContain("oidc_not_linked");
|
||||
const users = await t.env.DB.prepare("SELECT COUNT(*) AS n FROM users").first<{ n: number }>();
|
||||
expect(users?.n).toBe(1); // 仍只有 admin
|
||||
});
|
||||
|
||||
test("篡改 state 拒绝;userinfo 缺 sub 时 fail closed", async () => {
|
||||
installIdpStub();
|
||||
resetOidcDiscoveryCache();
|
||||
const t = await makeTestEnv();
|
||||
await enableOidc(t, true);
|
||||
const bad = await t.app.fetch(new Request("http://localhost/auth/callback?code=x&state=bogus"), t.env);
|
||||
expect(bad.headers.get("Location")).toContain("state_invalid");
|
||||
|
||||
mockUserInfo = { preferred_username: "nosub" };
|
||||
const { state } = await startLogin(t);
|
||||
const cb = await t.app.fetch(new Request(`http://localhost/auth/callback?code=good&state=${state}`), t.env);
|
||||
expect(cb.headers.get("Location")).toContain("oidc_exchange_failed");
|
||||
});
|
||||
|
||||
test("展示名兜底链:name → given+family → preferred_username → subject 前缀", async () => {
|
||||
const { oidcDisplayName } = await import("../console/src/services/oidc.ts");
|
||||
expect(oidcDisplayName({ sub: "s1", name: "A" })).toBe("A");
|
||||
expect(oidcDisplayName({ sub: "s2", given_name: "San", family_name: "Zhang" })).toBe("San Zhang");
|
||||
expect(oidcDisplayName({ sub: "s3", preferred_username: "pz" })).toBe("pz");
|
||||
expect(oidcDisplayName({ sub: "1234567890abcdef" })).toBe("统一账号 1234567890ab");
|
||||
});
|
||||
});
|
||||
|
||||
describe("修改用户名(PUT /api/settings/username)", () => {
|
||||
test("需当前密码;改后新名可登录、旧名失效、/me 返回新名", async () => {
|
||||
const t = await makeTestEnv();
|
||||
const cookie = await loginCookie(t);
|
||||
|
||||
// 密码错误拒绝
|
||||
const bad = await authedFetch(t, cookie, "http://localhost/api/settings/username", {
|
||||
method: "PUT",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ new_username: "boss", password: "wrong" }),
|
||||
});
|
||||
expect(bad.status).toBe(400);
|
||||
|
||||
// 非法字符拒绝
|
||||
const invalid = await authedFetch(t, cookie, "http://localhost/api/settings/username", {
|
||||
method: "PUT",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ new_username: "has space", password: "admin" }),
|
||||
});
|
||||
expect(invalid.status).toBe(400);
|
||||
|
||||
// 正常修改:重签会话
|
||||
const ok = await authedFetch(t, cookie, "http://localhost/api/settings/username", {
|
||||
method: "PUT",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ new_username: "boss", password: "admin" }),
|
||||
});
|
||||
expect(ok.status).toBe(200);
|
||||
const renewed = cookieOf(ok);
|
||||
|
||||
// 旧 cookie(旧 payload 用户名)仍可用,但 /me 以库为准返回新名
|
||||
const meOld = (await (await authedFetch(t, cookie, "http://localhost/api/auth/me")).json()) as { user: { username: string } };
|
||||
expect(meOld.user.username).toBe("boss");
|
||||
// 新签 cookie 同样
|
||||
const meNew = (await (await authedFetch(t, renewed, "http://localhost/api/auth/me")).json()) as { user: { username: string } };
|
||||
expect(meNew.user.username).toBe("boss");
|
||||
|
||||
// 新用户名 + 原密码可登录;旧用户名登录 401
|
||||
const loginNew = await t.app.fetch(
|
||||
new Request("http://localhost/api/auth/login", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ username: "boss", password: "admin" }),
|
||||
}),
|
||||
t.env,
|
||||
);
|
||||
expect(loginNew.status).toBe(200);
|
||||
const loginOld = await t.app.fetch(
|
||||
new Request("http://localhost/api/auth/login", {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ username: "admin", password: "admin" }),
|
||||
}),
|
||||
t.env,
|
||||
);
|
||||
expect(loginOld.status).toBe(401);
|
||||
});
|
||||
|
||||
test("与其他用户重名返回 409;GET /api/settings 回传 oidc 配置与未绑定身份", async () => {
|
||||
const t = await makeTestEnv();
|
||||
const cookie = await loginCookie(t);
|
||||
// 建第二个用户直接插库
|
||||
const { hashPassword, ids } = await import("../shared/src/index.ts");
|
||||
await t.env.DB.prepare("INSERT INTO users (id, username, password_hash, created_at) VALUES (?, ?, ?, ?)")
|
||||
.bind(ids.user(), "taken", await hashPassword("x".repeat(8)), new Date().toISOString())
|
||||
.run();
|
||||
const dup = await authedFetch(t, cookie, "http://localhost/api/settings/username", {
|
||||
method: "PUT",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ new_username: "taken", password: "admin" }),
|
||||
});
|
||||
expect(dup.status).toBe(409);
|
||||
|
||||
const info = (await (await authedFetch(t, cookie, "http://localhost/api/settings")).json()) as {
|
||||
username: string;
|
||||
oidc: { enabled: boolean; redirect_uri: string; identity: unknown; source: string };
|
||||
};
|
||||
expect(info.username).toBe("admin");
|
||||
expect(info.oidc.enabled).toBe(false);
|
||||
expect(info.oidc.source).toBe("none");
|
||||
expect(info.oidc.redirect_uri).toBe("http://localhost/auth/callback");
|
||||
expect(info.oidc.identity).toBeNull();
|
||||
});
|
||||
});
|
||||
+30
-2
@@ -34,6 +34,12 @@ const check = (step: string, ok: boolean, note?: string) => {
|
||||
await page.goto(`${BASE}/login`, { waitUntil: "domcontentloaded" });
|
||||
await page.waitForSelector("input[placeholder='用户名']", { timeout: 8000 });
|
||||
check("登录页渲染(含 LOGO/表单)", (await page.title()).includes("WmailHub"));
|
||||
// 统一登录未启用时(v2.9.0):登录页不显示 ZITADEL 按钮;/auth/status 可探测
|
||||
await page.waitForTimeout(400); // 等 /auth/status 探测返回
|
||||
check(
|
||||
"登录页 ZITADEL 按钮按启用状态显示(默认关闭不显示)",
|
||||
(await page.locator("button:has-text('ZITADEL 统一登录')").count()) === 0,
|
||||
);
|
||||
await page.screenshot({ path: `${SHOT_DIR}/01-login.png` });
|
||||
|
||||
// 2. 登录 admin/admin
|
||||
@@ -101,8 +107,8 @@ await page.click(".ant-dropdown .ant-dropdown-menu-item:has-text('设置')");
|
||||
await page.waitForSelector(".ant-modal:has-text('全局 Webhook')", { timeout: 8000 });
|
||||
const tabLabels = await page.locator(".ant-modal .ant-tabs-tab").allInnerTexts();
|
||||
check(
|
||||
"设置模态窗口经头像下拉打开(全局 Webhook / Cloudflare 接入 / 账号密码 三 tab)",
|
||||
tabLabels.length === 3 && tabLabels.some((t) => t.includes("Cloudflare 接入")),
|
||||
"设置模态窗口经头像下拉打开(全局 Webhook / Cloudflare 接入 / ZITADEL 统一登录 / 账号密码 四 tab)",
|
||||
tabLabels.length === 4 && tabLabels.some((t) => t.includes("Cloudflare 接入")) && tabLabels.some((t) => t.includes("ZITADEL 统一登录")),
|
||||
tabLabels.join(" | "),
|
||||
);
|
||||
await page.screenshot({ path: `${SHOT_DIR}/09-settings-webhook.png` });
|
||||
@@ -115,6 +121,28 @@ const redirectText =
|
||||
(await page.locator(".ant-modal .mono").filter({ hasText: "/api/oauth/cloudflare/callback" }).first().textContent()) ?? "";
|
||||
check("Cloudflare 接入 tab 显示授权回调地址", redirectText.includes("/api/oauth/cloudflare/callback"), redirectText.trim());
|
||||
await page.screenshot({ path: `${SHOT_DIR}/09b-settings-cloudflare.png` });
|
||||
|
||||
// ZITADEL 统一登录 tab(v2.9.0):回调地址 /auth/callback + Issuer/Client ID 表单 + 启用/JIT 开关
|
||||
await page.click(".ant-modal .ant-tabs-tab:has-text('ZITADEL 统一登录')");
|
||||
await page.waitForSelector(".ant-modal :text('Issuer')", { timeout: 8000 });
|
||||
const oidcModalText = (await page.locator(".ant-modal").innerText()) ?? "";
|
||||
check(
|
||||
"ZITADEL tab 显示回调地址 /auth/callback 与启用/JIT 开关",
|
||||
oidcModalText.includes("/auth/callback") &&
|
||||
(await page.locator(".ant-modal .ant-switch").count()) === 2 &&
|
||||
oidcModalText.includes("管理员"),
|
||||
oidcModalText.split("\n").slice(0, 6).join(" / "),
|
||||
);
|
||||
await page.screenshot({ path: `${SHOT_DIR}/09c-settings-oidc.png` });
|
||||
|
||||
// 账号密码 tab(v2.9.0):用户名修改表单 + 密码表单
|
||||
await page.click(".ant-modal .ant-tabs-tab:has-text('账号密码')");
|
||||
await page.waitForSelector(".ant-modal :text('新用户名')", { timeout: 8000 });
|
||||
const accountModalText = (await page.locator(".ant-modal").innerText()) ?? "";
|
||||
check(
|
||||
"账号密码 tab 含用户名修改(新用户名 + 当前密码)与密码表单",
|
||||
accountModalText.includes("新用户名") && accountModalText.includes("更新用户名") && accountModalText.includes("更新密码"),
|
||||
);
|
||||
await page.click(".ant-modal .ant-tabs-tab:has-text('全局 Webhook')");
|
||||
await page.waitForSelector(".ant-modal :text('Webhook URL')", { timeout: 8000 });
|
||||
|
||||
|
||||
Reference in New Issue
Block a user