Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

15.9 KB
Raw Blame
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,
      };
  }
}