Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { z } from "zod";
export const authRegionSchema = z.enum(["cn", "global"]);
export type AuthRegion = z.infer<typeof authRegionSchema>;
export const socialProviderSchema = z.enum(["apple", "google", "wechat"]);
export type SocialProvider = z.infer<typeof socialProviderSchema>;
export const membershipSchema = z.object({
id: z.string().min(1),
passportId: z.string().min(1).optional(),
kind: z.enum(["personal", "org"]),
role: z.enum(["owner", "admin", "member"]),
displayName: z.string(),
// 用户自助设置的头像(auth-server PATCH /api/me/profile);null = 未设置。
// optional 兼容尚未升级的旧 auth-server 响应(缺字段不整份拒绝)。
avatarUrl: z.string().nullable().optional(),
email: z.string().nullable(),
orgId: z.string().nullable(),
orgName: z.string().nullable(),
// 企业 logo(auth console 组织设置上传);personal 或未设置 = null。
// optional 兼容尚未升级的旧 auth-server 响应(缺字段不整份拒绝)。
orgLogoUrl: z.string().nullable().optional(),
});
export type AuthMembership = z.infer<typeof membershipSchema>;
/**
* 人机验证(CAPTCHA)配置:auth-server 开启时经 GET /api/auth/providers 下发。
* requiredFor 声明哪些动作发起前必须先完成挑战。
* 客户端预认邮箱与短信发码;服务端当前可只下发邮箱动作,后续下发短信动作
* 即可启用既有客户端闸门,无需变更 wire 结构。
* 关闭时服务端整字段省略 → undefined = 不需要人机验证。
*/
export const captchaRequiredActionSchema = z.enum([
"email_request_code",
"phone_request_code",
]);
export type CaptchaRequiredAction = z.infer<typeof captchaRequiredActionSchema>;
export const captchaConfigSchema = z.object({
provider: z.literal("turnstile"),
siteKey: z.string().min(1),
// 服务端可 append-only 扩展动作;当前客户端预认邮箱与短信发码,其他未知
// 动作忽略,避免一个未来动作让整份 providers 响应解析失败。
requiredFor: z
.array(z.string())
.transform((actions) =>
actions.filter(
(action): action is CaptchaRequiredAction =>
captchaRequiredActionSchema.safeParse(action).success,
),
),
});
export type CaptchaConfig = z.infer<typeof captchaConfigSchema>;
/**
* auth-server 托管 Turnstile 挑战页的固定路径(wire 契约)。
* 完整地址 = authApiBaseUrl + 本路径 +
* `?action=<email_request_code|phone_request_code>&theme=<light|dark>&lang=<BCP-47>`;
* 页面把结果写进 location.hash(`cindy-captcha=ok.<token>` / `err.<code>`)
* 或经 ReactNativeWebView.postMessage 回传(双宿主同页兼容)。
*/
export const CAPTCHA_CHALLENGE_PAGE_PATH = "/captcha/turnstile";
export const providerConfigSchema = z.object({
region: authRegionSchema,
attribution: z.enum(["phone", "email"]),
email: z.boolean(),
phone: z.boolean(),
social: z.array(socialProviderSchema),
// optional 兼容尚未升级的旧 auth-server 响应(缺字段不整份拒绝)。
captcha: captchaConfigSchema.optional(),
});
export type ProviderConfig = z.infer<typeof providerConfigSchema>;
/** 企业 SSO discovery(POST /api/auth/sso/discovery,按组织 ID/slug/已验证域名探测)。 */
export const ssoOrgConnectionSchema = z.object({
connectionId: z.string().min(1),
protocol: z.enum(["oidc", "saml", "cas"]),
connectionName: z.string(),
});
export type SsoOrgConnection = z.infer<typeof ssoOrgConnectionSchema>;
export const ssoOrgDiscoverySchema = z.object({
region: authRegionSchema,
orgName: z.string(),
// 不设 min(1):服务端对「企业存在但未启用 SSO」可能返回 200 + connections:[]。
// 让空数组通过 schema 校验,由 CindyAuthClient.discoverSsoOrg 显式映射成精确的
// ORG_SSO_NOT_FOUND,而不是被当成 INVALID_RESPONSE 落到通用错误文案。
connections: z.array(ssoOrgConnectionSchema),
});
export type SsoOrgDiscovery = z.infer<typeof ssoOrgDiscoverySchema>;
export const loginMethodSchema = z.discriminatedUnion("type", [
z.object({ type: z.literal("email_code") }),
z.object({
type: z.literal("sso"),
connectionId: z.string().min(1),
protocol: z.enum(["oidc", "saml", "cas"]),
orgName: z.string(),
connectionName: z.string(),
ssoRequired: z.boolean(),
}),
]);
export type LoginMethod = z.infer<typeof loginMethodSchema>;
/**
* Discovery 允许服务端 append-only 增加未知登录方式。未知项丢弃,避免整份
* `methods` 校验失败变成 INVALID_RESPONSE,把已经认识的 email_code / sso
* 一起挡掉(移动端会落到「登录未完成」兜底,验证码发不出去)。
*/
const knownLoginMethodTypes = new Set(["email_code", "sso"]);
export function recognizeLoginMethods(items: readonly unknown[]): LoginMethod[] {
return items.flatMap((item) => {
// 有 string type 且不在已知集 = 服务端新增方式,向前兼容丢弃。
if (
typeof item === "object" &&
item !== null &&
"type" in item &&
typeof item.type === "string" &&
item.type.length > 0 &&
!knownLoginMethodTypes.has(item.type)
) {
return [];
}
// 其余(已知 type、缺 type、type 非字符串)一律严格 parse,
// 字段残缺抛错由调用方转为 INVALID_RESPONSE,不静默丢弃。
return [loginMethodSchema.parse(item)];
});
}
/**
* 把企业 SSO discovery 结果映射成 LoginMethod 列表。
* 多连接时复用 method-choice 让用户选 IdP;唯一连接由
* `soleAutoStartSsoMethod` 判定后,UI 直接投影 browser-redirect
* (ssoRequired=false:入口本身即用户主动选 SSO,无需再提示强制)。
*/
export function ssoOrgDiscoveryToMethods(
discovery: SsoOrgDiscovery,
): LoginMethod[] {
return discovery.connections.map((connection) => ({
type: "sso" as const,
connectionId: connection.connectionId,
protocol: connection.protocol,
orgName: discovery.orgName,
connectionName: connection.connectionName,
ssoRequired: false,
}));
}
export type SsoLoginMethod = Extract<LoginMethod, { type: "sso" }>;
/**
* method-choice 只在真正有选择时出现。探测结果只剩一种方式时,
* 调用方应直接发起它,不要再出「选择登录方式」。
*
* 覆盖:唯一 SSO;唯一邮箱验证码。不覆盖:SSO + 个人邮箱;多条 SSO。
*/
export function soleLoginMethod(
methods: readonly LoginMethod[],
): LoginMethod | null {
return methods.length === 1 ? (methods[0] ?? null) : null;
}
/** 唯一 SSO、没有个人邮箱替补时,应直接打开该 SSO。 */
export function soleAutoStartSsoMethod(
methods: readonly LoginMethod[],
): SsoLoginMethod | null {
const sole = soleLoginMethod(methods);
return sole?.type === "sso" ? sole : null;
}
export const tokenPairSchema = z.object({
accessToken: z.string().min(1),
refreshToken: z.string().min(1),
membership: membershipSchema,
});
export type AuthTokenPair = z.infer<typeof tokenPairSchema>;
export const accountTokenPairSchema = z.object({
accountToken: z.string().min(1),
accountRefreshToken: z.string().min(1),
});
export type AccountTokenPair = z.infer<typeof accountTokenPairSchema>;
const optionalAccountTokenFields = {
accountToken: z.string().min(1).optional(),
accountRefreshToken: z.string().min(1).optional(),
accountDeletionRestored: z.literal(true).optional(),
};
const okOutcomeSchema = tokenPairSchema.extend({
status: z.literal("ok"),
...optionalAccountTokenFields,
});
const selectAccountOutcomeSchema = z.object({
status: z.literal("select_account"),
loginTicket: z.string().min(1),
accounts: z.array(membershipSchema).min(1),
...optionalAccountTokenFields,
});
const bindingRequiredOutcomeSchema = z.object({
status: z.literal("binding_required"),
bindType: z.enum(["phone", "email"]),
bindTicket: z.string().min(1),
});
const ssoVerificationRequiredOutcomeSchema = z.object({
status: z.literal("sso_verification_required"),
verificationTicket: z.string().min(1),
channel: z.enum(["email", "sms"]),
targetMasked: z.string().min(1),
});
export const loginOutcomeSchema = z
.discriminatedUnion("status", [
okOutcomeSchema,
selectAccountOutcomeSchema,
bindingRequiredOutcomeSchema,
ssoVerificationRequiredOutcomeSchema,
])
.superRefine((outcome, ctx) => {
if (outcome.status !== "ok" && outcome.status !== "select_account") return;
if (
Boolean(outcome.accountToken) !== Boolean(outcome.accountRefreshToken)
) {
ctx.addIssue({
code: "custom",
message:
"accountToken and accountRefreshToken must be returned together",
});
}
});
export type LoginOutcome = z.infer<typeof loginOutcomeSchema>;
export type AuthSuccess = z.infer<typeof okOutcomeSchema>;
export const accountMembershipSchema = membershipSchema.extend({
orgSlug: z.string().nullable(),
});
export type AccountMembership = z.infer<typeof accountMembershipSchema>;
export const meResponseSchema = z.object({
membership: membershipSchema,
passportId: z.string().min(1),
identities: z.array(membershipSchema),
});
export type AuthMe = z.infer<typeof meResponseSchema>;
export const accountDeletionAvailabilitySchema = z.object({
available: z.boolean(),
verification: z
.object({
channel: z.enum(["email", "sms"]),
maskedTarget: z.string().min(1),
})
.optional(),
manualAppleRevocationRequired: z.boolean(),
});
export type AccountDeletionAvailability = z.infer<
typeof accountDeletionAvailabilitySchema
>;
export const accountDeletionChallengeSchema = z.object({
challengeId: z.string().min(1),
receiptToken: z.string().min(1),
channel: z.enum(["email", "sms"]),
maskedTarget: z.string().min(1),
expiresAt: z.string().datetime(),
});
export type AccountDeletionChallenge = z.infer<
typeof accountDeletionChallengeSchema
>;
export const accountDeletionStatusSchema = z.object({
status: z.enum(["pending", "processing", "completed", "cancelled"]),
requestedAt: z.string().datetime(),
deleteAfter: z.string().datetime(),
processingAt: z.string().datetime().optional(),
completedAt: z.string().datetime().optional(),
cancelledAt: z.string().datetime().optional(),
});
export type AccountDeletionStatus = z.infer<
typeof accountDeletionStatusSchema
>;
/**
* 托管回调链路(desktop 系统浏览器登录)的授权码取回结果。
*
* 背景:RFC 8252 loopback 会把 `127.0.0.1:<port>` 与授权码一起暴露在浏览器地址栏,
* 唤起 app 的系统弹框也显示该 IP。托管回调改为让 auth-server 接住 provider 回调、
* 按 clientState 短期暂存授权码,客户端轮询取回——浏览器全程停在自有域名上。
*
* 语义:
* - `pending`:用户尚未完成授权,继续轮询;
* - `ok`:取到一次性授权码(服务端应即时失效),客户端接着走 PKCE 换 token;
* - `error`:provider 或 auth-server 侧失败,`error` 为可展示的错误码;
* - `expired`:暂存已过 TTL 或已被取走,本次尝试作废。
*/
export const desktopAuthorizationPollSchema = z.discriminatedUnion("status", [
z.object({ status: z.literal("pending") }),
z.object({ status: z.literal("ok"), code: z.string().min(1) }),
z.object({ status: z.literal("error"), error: z.string().min(1) }),
z.object({ status: z.literal("expired") }),
]);
export type DesktopAuthorizationPoll = z.infer<
typeof desktopAuthorizationPollSchema
>;
export type AuthClientType = "desktop" | "mobile" | "web";
export type VerificationKind = "email" | "phone";
export type SsoVerificationChannel = "email" | "sms";
/** 发码类型到 providers.captcha.requiredFor wire action 的唯一映射。 */
export function captchaRequiredActionForVerificationKind(
kind: VerificationKind,
): CaptchaRequiredAction {
return kind === "email" ? "email_request_code" : "phone_request_code";
}
export type AuthFlowState =
| { step: "identifier"; providers: ProviderConfig }
| {
step: "realm-confirmation";
targetRegion: AuthRegion;
/** Present for email discovery; personal verification still uses the build region. */
email?: string;
/** Host retains the successful personal login; declining resumes it in its original region. */
personalLoginAvailable?: boolean;
providers: ProviderConfig;
methods: LoginMethod[];
}
| { step: "method-choice"; email: string; methods: LoginMethod[] }
| { step: "verification-code"; kind: VerificationKind; identifier: string }
| { step: "browser-redirect"; label: string }
| { step: "account-selection"; accounts: AuthMembership[] }
| {
step: "sso-verification";
channel: SsoVerificationChannel;
targetMasked: string;
codeRequested: boolean;
}
| {
step: "binding";
bindType: VerificationKind;
codeRequested: boolean;
contact?: string;
}
| { step: "completed"; membership: AuthMembership }
| {
step: "error";
code: string;
recoverTo: Exclude<AuthFlowState["step"], "error">;
};
export type AuthFlowAction =
| { type: "providers-loaded"; providers: ProviderConfig }
| {
type: "realm-switch-required";
targetRegion: AuthRegion;
email?: string;
personalLoginAvailable?: boolean;
providers: ProviderConfig;
methods: LoginMethod[];
}
| { type: "discovery-loaded"; email: string; methods: LoginMethod[] }
| { type: "code-requested"; kind: VerificationKind; identifier: string }
| { type: "browser-started"; label: string }
| { type: "outcome"; outcome: LoginOutcome }
| {
type: "sso-verification-code-requested";
channel: SsoVerificationChannel;
targetMasked: string;
}
| {
type: "binding-code-requested";
bindType: VerificationKind;
contact: string;
}
| {
type: "failed";
code: string;
recoverTo: Exclude<AuthFlowState["step"], "error">;
};
/** Pure UI-state projection. Secret login/bind tickets stay in platform controllers. */
export function reduceAuthFlow(
_state: AuthFlowState | null,
action: AuthFlowAction,
): AuthFlowState {
switch (action.type) {
case "providers-loaded":
return { step: "identifier", providers: action.providers };
case "realm-switch-required":
return {
step: "realm-confirmation",
targetRegion: action.targetRegion,
...(action.email !== undefined ? { email: action.email } : {}),
...(action.personalLoginAvailable ? { personalLoginAvailable: true } : {}),
providers: action.providers,
methods: action.methods,
};
case "discovery-loaded":
return {
step: "method-choice",
email: action.email,
methods: action.methods,
};
case "code-requested":
return {
step: "verification-code",
kind: action.kind,
identifier: action.identifier,
};
case "browser-started":
return { step: "browser-redirect", label: action.label };
case "binding-code-requested":
return {
step: "binding",
bindType: action.bindType,
codeRequested: true,
contact: action.contact,
};
case "sso-verification-code-requested":
return {
step: "sso-verification",
channel: action.channel,
targetMasked: action.targetMasked,
codeRequested: true,
};
case "failed":
return { step: "error", code: action.code, recoverTo: action.recoverTo };
case "outcome":
if (action.outcome.status === "ok") {
return { step: "completed", membership: action.outcome.membership };
}
if (action.outcome.status === "select_account") {
return { step: "account-selection", accounts: action.outcome.accounts };
}
if (action.outcome.status === "sso_verification_required") {
return {
step: "sso-verification",
channel: action.outcome.channel,
targetMasked: action.outcome.targetMasked,
codeRequested: false,
};
}
return {
step: "binding",
bindType: action.outcome.bindType,
codeRequested: false,
};
}
}