@allbluecn/web-app 0.10.3 → 0.11.1

package/src/server/email/templates/billing/subscription-canceled.tsx

@@ -0,0 +1,51 @@
+import { Section, Text } from '@react-email/components'
+import { EmailLayout } from '../_base/email-layout'
+import { EmailButton } from '../_base/button'
+import { registerTemplate, type EmailLocale } from '../../registry'
+
+interface SubscriptionCanceledProps {
+  locale: EmailLocale
+  planName: string
+  endDate: string
+  dashboardUrl: string
+  unsubscribeUrl?: string
+}
+
+const T = {
+  zh: {
+    subject: '订阅已取消',
+    preview: '你的订阅已取消',
+    heading: '订阅已取消',
+    body: (plan: string, end: string) => `你的 AllBlue「${plan}」订阅已取消，服务将持续至 ${end}。可随时重新订阅。`,
+    cta: '重新订阅',
+  },
+  en: {
+    subject: 'Subscription canceled',
+    preview: 'Your subscription was canceled',
+    heading: 'Canceled',
+    body: (plan: string, end: string) => `Your AllBlue "${plan}" subscription was canceled. Service continues until ${end}. You can resubscribe any time.`,
+    cta: 'Resubscribe',
+  },
+} as const
+
+function SubscriptionCanceledEmail({ locale, planName, endDate, dashboardUrl, unsubscribeUrl }: SubscriptionCanceledProps) {
+  const t = T[locale]
+  return (
+    <EmailLayout locale={locale} preview={t.preview} heading={t.heading} unsubscribeUrl={unsubscribeUrl} footerKind="transactional">
+      <Text className="text-base text-fg-2 mx-auto mt-0 mb-8 max-w-[380px] font-sans">{t.body(planName, endDate)}</Text>
+      <Section className="mb-6 text-center">
+        <EmailButton href={dashboardUrl} label={t.cta} />
+      </Section>
+    </EmailLayout>
+  )
+}
+
+export function registerSubscriptionCanceledTemplate() {
+  registerTemplate({
+    key: 'billing.subscription-canceled',
+    category: 'billing',
+    transactional: true,
+    subject: { zh: T.zh.subject, en: T.en.subject },
+    component: SubscriptionCanceledEmail,
+  })
+}

package/src/server/email/templates/billing/subscription-ending.tsx

@@ -0,0 +1,51 @@
+import { Section, Text } from '@react-email/components'
+import { EmailLayout } from '../_base/email-layout'
+import { EmailButton } from '../_base/button'
+import { registerTemplate, type EmailLocale } from '../../registry'
+
+interface SubscriptionEndingProps {
+  locale: EmailLocale
+  planName: string
+  endDate: string
+  dashboardUrl: string
+  unsubscribeUrl?: string
+}
+
+const T = {
+  zh: {
+    subject: '你的订阅即将到期',
+    preview: '订阅即将到期',
+    heading: '即将到期',
+    body: (plan: string, end: string) => `你的 AllBlue「${plan}」订阅将于 ${end} 到期，请及时续订。`,
+    cta: '续订',
+  },
+  en: {
+    subject: 'Your subscription is ending soon',
+    preview: 'Subscription ending soon',
+    heading: 'Ending soon',
+    body: (plan: string, end: string) => `Your AllBlue "${plan}" subscription ends on ${end}. Renew to keep your access.`,
+    cta: 'Renew',
+  },
+} as const
+
+function SubscriptionEndingEmail({ locale, planName, endDate, dashboardUrl, unsubscribeUrl }: SubscriptionEndingProps) {
+  const t = T[locale]
+  return (
+    <EmailLayout locale={locale} preview={t.preview} heading={t.heading} unsubscribeUrl={unsubscribeUrl} footerKind="transactional">
+      <Text className="text-base text-fg-2 mx-auto mt-0 mb-8 max-w-[380px] font-sans">{t.body(planName, endDate)}</Text>
+      <Section className="mb-6 text-center">
+        <EmailButton href={dashboardUrl} label={t.cta} />
+      </Section>
+    </EmailLayout>
+  )
+}
+
+export function registerSubscriptionEndingTemplate() {
+  registerTemplate({
+    key: 'billing.subscription-ending',
+    category: 'billing',
+    transactional: true,
+    subject: { zh: T.zh.subject, en: T.en.subject },
+    component: SubscriptionEndingEmail,
+  })
+}

package/src/server/email/templates/notification/mirror.tsx

@@ -0,0 +1,50 @@
+import { Section, Text } from '@react-email/components'
+import { EmailLayout } from '../_base/email-layout'
+import { EmailButton } from '../_base/button'
+import { registerTemplate, type EmailLocale } from '../../registry'
+
+interface NotificationMirrorProps {
+  locale: EmailLocale
+  title: string
+  body?: string
+  link?: string
+  linkLabel?: string
+  unsubscribeUrl?: string
+}
+
+const T = {
+  zh: {
+    subject: '你有一条新通知',
+    defaultLinkLabel: '查看详情',
+  },
+  en: {
+    subject: 'You have a new notification',
+    defaultLinkLabel: 'View details',
+  },
+} as const
+
+function NotificationMirrorEmail({ locale, title, body, link, linkLabel, unsubscribeUrl }: NotificationMirrorProps) {
+  const t = T[locale]
+  return (
+    <EmailLayout locale={locale} preview={title} heading={title} unsubscribeUrl={unsubscribeUrl} footerKind="notification">
+      {body ? (
+        <Text className="text-base text-fg-2 mx-auto mt-0 mb-8 max-w-[380px] font-sans">{body}</Text>
+      ) : null}
+      {link ? (
+        <Section className="mb-6 text-center">
+          <EmailButton href={link} label={linkLabel ?? t.defaultLinkLabel} />
+        </Section>
+      ) : null}
+    </EmailLayout>
+  )
+}
+
+export function registerNotificationMirrorTemplate() {
+  registerTemplate({
+    key: 'notification.mirror',
+    category: 'notification',
+    transactional: false,
+    subject: { zh: T.zh.subject, en: T.en.subject },
+    component: NotificationMirrorEmail,
+  })
+}

package/src/server/email/templates/product/changelog-confirm.tsx

@@ -0,0 +1,53 @@
+import { Section, Text } from '@react-email/components'
+import { EmailLayout } from '../_base/email-layout'
+import { EmailButton } from '../_base/button'
+import { registerTemplate, type EmailLocale } from '../../registry'
+
+interface ChangelogConfirmProps {
+  locale: EmailLocale
+  confirmUrl: string
+  unsubscribeUrl?: string
+}
+
+const T = {
+  zh: {
+    subject: '确认订阅 AllBlue 开发更新',
+    preview: '请确认订阅 AllBlue 开发更新',
+    heading: '确认订阅',
+    body: '感谢订阅 AllBlue 开发更新。请点击下方按钮确认订阅（链接 24 小时内有效）。无营销邮件，可随时退订。',
+    cta: '确认订阅',
+    urlLabel: '如果按钮无法点击，请复制以下链接：',
+  },
+  en: {
+    subject: 'Confirm your AllBlue updates subscription',
+    preview: 'Confirm your AllBlue developer updates subscription',
+    heading: 'Confirm subscription',
+    body: 'Thanks for subscribing to AllBlue developer updates. Click the button below to confirm your subscription (link valid for 24 hours). No marketing emails. Unsubscribe any time.',
+    cta: 'Confirm subscription',
+    urlLabel: 'If the button does not work, copy this link:',
+  },
+} as const
+
+function ChangelogConfirmEmail({ locale, confirmUrl, unsubscribeUrl }: ChangelogConfirmProps) {
+  const t = T[locale]
+  return (
+    <EmailLayout locale={locale} preview={t.preview} heading={t.heading} unsubscribeUrl={unsubscribeUrl} footerKind="notification">
+      <Text className="text-base text-fg-2 mx-auto mt-0 mb-8 max-w-[380px] font-sans">{t.body}</Text>
+      <Section className="mb-6 text-center">
+        <EmailButton href={confirmUrl} label={t.cta} />
+      </Section>
+      <Text className="text-sm text-fg-3 break-all font-sans">{t.urlLabel}</Text>
+      <Text className="text-sm text-fg-3 break-all font-sans">{confirmUrl}</Text>
+    </EmailLayout>
+  )
+}
+
+export function registerChangelogConfirmTemplate() {
+  registerTemplate({
+    key: 'product.changelog-confirm',
+    category: 'product',
+    transactional: false,
+    subject: { zh: T.zh.subject, en: T.en.subject },
+    component: ChangelogConfirmEmail,
+  })
+}

package/src/server/email/templates/product/changelog-release.tsx

@@ -0,0 +1,65 @@
+import { Section, Text } from '@react-email/components'
+import { EmailLayout } from '../_base/email-layout'
+import { EmailButton } from '../_base/button'
+import { registerTemplate, type EmailLocale } from '../../registry'
+
+interface ChangelogReleaseProps {
+  locale: EmailLocale
+  version: string
+  highlights: string
+  detailUrl: string
+  unsubscribeUrl?: string
+}
+
+const T = {
+  zh: {
+    subject: 'AllBlue v{version} 发布',
+    preview: 'AllBlue 新版本发布',
+    heading: '新版本发布',
+    body: (version: string) => `AllBlue v${version} 已发布。`,
+    highlightsLabel: '本次更新要点：',
+    cta: '查看更新日志',
+  },
+  en: {
+    subject: 'AllBlue v{version} released',
+    preview: 'New AllBlue version released',
+    heading: 'New release',
+    body: (version: string) => `AllBlue v${version} has been released.`,
+    highlightsLabel: 'Highlights:',
+    cta: 'View changelog',
+  },
+} as const
+
+function ChangelogReleaseEmail({ locale, version, highlights, detailUrl, unsubscribeUrl }: ChangelogReleaseProps) {
+  const t = T[locale]
+  const highlightsList = highlights ? highlights.split('\n').filter(Boolean) : []
+  return (
+    <EmailLayout locale={locale} preview={t.preview} heading={t.heading} unsubscribeUrl={unsubscribeUrl} footerKind="notification">
+      <Text className="text-base text-fg-2 mx-auto mt-0 mb-6 max-w-[380px] font-sans">{t.body(version)}</Text>
+      {highlightsList.length > 0 ? (
+        <Section className="mb-8">
+          <Text className="text-sm text-fg-3 m-0 mb-2 font-sans">{t.highlightsLabel}</Text>
+          {highlightsList.map((line, i) => (
+            <Text key={i} className="font-14 text-fg-2 m-0 font-sans">· {line}</Text>
+          ))}
+        </Section>
+      ) : null}
+      <Section className="mb-6 text-center">
+        <EmailButton href={detailUrl} label={t.cta} />
+      </Section>
+    </EmailLayout>
+  )
+}
+
+export function registerChangelogReleaseTemplate() {
+  registerTemplate({
+    key: 'product.changelog-release',
+    category: 'product',
+    transactional: false,
+    subject: {
+      zh: (vars) => `AllBlue v${(vars.version as string) ?? ''} 发布`,
+      en: (vars) => `AllBlue v${(vars.version as string) ?? ''} released`,
+    },
+    component: ChangelogReleaseEmail,
+  })
+}

package/src/server/email/templates/team/apply-notify.tsx

@@ -0,0 +1,53 @@
+import { Section, Text } from '@react-email/components'
+import { EmailLayout } from '../_base/email-layout'
+import { EmailButton } from '../_base/button'
+import { registerTemplate, type EmailLocale } from '../../registry'
+
+interface TeamApplyNotifyProps {
+  locale: EmailLocale
+  applicantEmail: string
+  approveUrl: string
+  unsubscribeUrl?: string
+}
+
+const T = {
+  zh: {
+    subject: '新的团队加入申请',
+    preview: '有人申请加入你的团队',
+    heading: '加入申请',
+    greeting: '你好：',
+    body: (email: string) => `有人以邮箱 ${email} 申请加入你的团队，请前往管理页面处理。`,
+    cta: '查看申请',
+  },
+  en: {
+    subject: 'New team join request',
+    preview: 'Someone requested to join your team',
+    heading: 'Join request',
+    greeting: 'Hi,',
+    body: (email: string) => `Someone with email ${email} requested to join your team. Please review it in the management page.`,
+    cta: 'Review request',
+  },
+} as const
+
+function TeamApplyNotifyEmail({ locale, applicantEmail, approveUrl, unsubscribeUrl }: TeamApplyNotifyProps) {
+  const t = T[locale]
+  return (
+    <EmailLayout locale={locale} preview={t.preview} heading={t.heading} unsubscribeUrl={unsubscribeUrl} footerKind="transactional">
+      <Text className="text-base text-fg-2 mt-0 mb-6 font-sans">{t.greeting}</Text>
+      <Text className="text-base text-fg-2 mx-auto mt-0 mb-8 max-w-[380px] font-sans">{t.body(applicantEmail)}</Text>
+      <Section className="mb-6 text-center">
+        <EmailButton href={approveUrl} label={t.cta} />
+      </Section>
+    </EmailLayout>
+  )
+}
+
+export function registerTeamApplyNotifyTemplate() {
+  registerTemplate({
+    key: 'team.apply-notify',
+    category: 'team',
+    transactional: true,
+    subject: { zh: T.zh.subject, en: T.en.subject },
+    component: TeamApplyNotifyEmail,
+  })
+}

package/src/server/email/templates/team/approved.tsx

@@ -0,0 +1,53 @@
+import { Section, Text } from '@react-email/components'
+import { EmailLayout } from '../_base/email-layout'
+import { EmailButton } from '../_base/button'
+import { registerTemplate, type EmailLocale } from '../../registry'
+
+interface TeamApprovedProps {
+  locale: EmailLocale
+  teamName?: string
+  inviteUrl: string
+  unsubscribeUrl?: string
+}
+
+const T = {
+  zh: {
+    subject: '你的加入申请已通过',
+    preview: '团队申请已批准',
+    heading: '申请已通过',
+    greeting: '你好：',
+    body: (team?: string) => (team ? `你的加入「${team}」团队的申请已通过。` : '你的团队加入申请已通过。'),
+    cta: '加入团队',
+  },
+  en: {
+    subject: 'Your join request was approved',
+    preview: 'Team request approved',
+    heading: 'Request approved',
+    greeting: 'Hi,',
+    body: (team?: string) => (team ? `Your request to join "${team}" has been approved.` : 'Your team join request has been approved.'),
+    cta: 'Join team',
+  },
+} as const
+
+function TeamApprovedEmail({ locale, teamName, inviteUrl, unsubscribeUrl }: TeamApprovedProps) {
+  const t = T[locale]
+  return (
+    <EmailLayout locale={locale} preview={t.preview} heading={t.heading} unsubscribeUrl={unsubscribeUrl} footerKind="transactional">
+      <Text className="text-base text-fg-2 mt-0 mb-6 font-sans">{t.greeting}</Text>
+      <Text className="text-base text-fg-2 mx-auto mt-0 mb-8 max-w-[380px] font-sans">{t.body(teamName)}</Text>
+      <Section className="mb-6 text-center">
+        <EmailButton href={inviteUrl} label={t.cta} />
+      </Section>
+    </EmailLayout>
+  )
+}
+
+export function registerTeamApprovedTemplate() {
+  registerTemplate({
+    key: 'team.approved',
+    category: 'team',
+    transactional: true,
+    subject: { zh: T.zh.subject, en: T.en.subject },
+    component: TeamApprovedEmail,
+  })
+}

package/src/server/email/templates/team/invite.tsx

@@ -0,0 +1,57 @@
+import { Section, Text } from '@react-email/components'
+import { EmailLayout } from '../_base/email-layout'
+import { EmailButton } from '../_base/button'
+import { registerTemplate, type EmailLocale } from '../../registry'
+
+interface TeamInviteProps {
+  locale: EmailLocale
+  ownerUsername: string
+  inviteUrl: string
+  expiresAt: string
+  unsubscribeUrl?: string
+}
+
+const T = {
+  zh: {
+    subject: '邀请你加入 AllBlue 团队',
+    preview: '你收到一个团队邀请',
+    heading: '团队邀请',
+    greeting: '你好：',
+    body: (owner: string) => `${owner || '团队成员'} 邀请你加入 AllBlue 团队。点击下方按钮接受邀请（${'过期时间见下'}）。`,
+    cta: '接受邀请',
+    expiresLabel: '有效期至：',
+  },
+  en: {
+    subject: 'You are invited to an AllBlue team',
+    preview: 'You received a team invitation',
+    heading: 'Team invitation',
+    greeting: 'Hi,',
+    body: (owner: string) => `${owner || 'A team member'} invited you to join an AllBlue team. Click the button below to accept.`,
+    cta: 'Accept invite',
+    expiresLabel: 'Valid until:',
+  },
+} as const
+
+function TeamInviteEmail({ locale, ownerUsername, inviteUrl, expiresAt, unsubscribeUrl }: TeamInviteProps) {
+  const t = T[locale]
+  return (
+    <EmailLayout locale={locale} preview={t.preview} heading={t.heading} unsubscribeUrl={unsubscribeUrl} footerKind="transactional">
+      <Text className="text-base text-fg-2 mt-0 mb-6 font-sans">{t.greeting}</Text>
+      <Text className="text-base text-fg-2 mx-auto mt-0 mb-8 max-w-[380px] font-sans">{t.body(ownerUsername)}</Text>
+      <Section className="mb-6 text-center">
+        <EmailButton href={inviteUrl} label={t.cta} />
+      </Section>
+      <Text className="text-sm text-fg-3 font-sans">{t.expiresLabel} {expiresAt}</Text>
+    </EmailLayout>
+  )
+}
+
+export function registerTeamInviteTemplate() {
+  registerTemplate({
+    key: 'team.invite',
+    category: 'team',
+    transactional: true,
+    subject: { zh: T.zh.subject, en: T.en.subject },
+    component: TeamInviteEmail,
+  })
+}

package/src/server/fetch-guard.ts

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 服务端 fetch 目标准入判定（SSRF 防护）。
+// 纯函数模块，仅依赖全局 URL，禁止 import prisma 等重模块，
+// 以便同时被服务端路由与单元测试消费。
+
+export class FetchGuardError extends Error {
+  constructor(url: string, reason: string) {
+    super(`拒绝 fetch 目标 ${url}：${reason}`)
+    this.name = "FetchGuardError"
+  }
+}
+
+export interface FetchGuardOptions {
+  /** 显式允许私网/回环目标（SearXNG 等自托管内网服务场景） */
+  allowPrivate?: boolean
+  /** 主机白名单（提供时仅放行列表内主机，与 allowPrivate 独立判定） */
+  allowedHosts?: string[]
+}
+
+/**
+ * 判定点分十进制 IPv4 是否落在私网/回环/链路本地/未指定/组播保留段。
+ * 这些地址段是 SSRF 的主要攻击面：本机服务（127.0.0.1）、内网资产（10/172.16/192.168）、
+ * 云元数据端点（169.254.169.254，可窃取实例凭证）。
+ */
+function isPrivateIPv4(host: string): boolean {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host)
+  if (!m) return false
+  const a = Number(m[1])
+  const b = Number(m[2])
+  if (a === 127 || a === 10 || a === 0) return true
+  if (a === 172 && b >= 16 && b <= 31) return true
+  if (a === 192 && b === 168) return true
+  if (a === 169 && b === 254) return true
+  if (a >= 224) return true
+  return false
+}
+
+/** 32 位整数转点分十进制，供整数形式 IPv4 与 IPv6 映射地址复用 */
+function toDotQuad(n: number): string {
+  return [(n >>> 24) & 255, (n >>> 16) & 255, (n >>> 8) & 255, n & 255].join(".")
+}
+
+/**
+ * 解析 32 位整数形式的 IP 混淆（十进制/十六进制/八进制），返回点分十进制。
+ * 纵深防御：WHATWG URL 在 Node 24 已会把这类主机规范化，但不同运行时
+ * （浏览器 WebKit、旧版 Node、上游中间件改写后的 hostname）行为不一致，
+ * 不能依赖上游规范化结果。非整数形式或超出 32 位返回 null，交由调用方继续判定。
+ */
+function normalizeIntegerIp(host: string): string | null {
+  let n: number | null = null
+  if (/^\d+$/.test(host)) n = Number(host)
+  else if (/^0x[0-9a-f]+$/i.test(host)) n = Number.parseInt(host.slice(2), 16)
+  else if (/^0[0-7]+$/.test(host)) n = Number.parseInt(host.slice(1), 8)
+  if (n === null || !Number.isSafeInteger(n) || n < 0 || n > 0xffffffff) return null
+  return toDotQuad(n)
+}
+
+/**
+ * 展开 IPv6 压缩形式为 8 组 16 位整数（NaN 标记非法段），解析失败返回 null。
+ * WHATWG URL 会把 IPv4-mapped 的点分十进制归一为十六进制组（::ffff:127.0.0.1 → ::ffff:7f00:1），
+ * 但仍保留点分十进制分支，防止上游未规范化时漏判。
+ */
+function expandIPv6(addr: string): number[] | null {
+  if (!addr.includes(":")) return null
+  const halves = addr.split("::")
+  if (halves.length > 2) return null
+  const toGroups = (seg: string): number[] =>
+    seg === ""
+      ? []
+      : seg.split(":").flatMap((t) => {
+          if (t.includes(".")) {
+            const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(t)
+            if (!m) return [NaN]
+            const n =
+              (Number(m[1]) << 24) | (Number(m[2]) << 16) | (Number(m[3]) << 8) | Number(m[4])
+            return [(n >>> 16) & 0xffff, n & 0xffff]
+          }
+          const v = Number.parseInt(t, 16)
+          return [v > 0xffff || Number.isNaN(v) ? NaN : v]
+        })
+  const head = toGroups(halves[0])
+  const tail = toGroups(halves[1] ?? "")
+  if (head.includes(NaN) || tail.includes(NaN)) return null
+  if (halves.length === 1 && head.length !== 8) return null
+  if (head.length + tail.length > 8) return null
+  return [...head, ...Array.from({ length: 8 - head.length - tail.length }, () => 0), ...tail]
+}
+
+/**
+ * 判定 IPv6 是否落在私网/保留段。SSRF 最经典绕过是 IPv4-mapped（::ffff:0:0/96）
+ * 伪装成 IPv6 直连回环/内网/云元数据，必须按末两组还原 32 位后再走 IPv4 判定。
+ */
+function isPrivateIPv6(addr: string): boolean {
+  const g = expandIPv6(addr)
+  if (!g) return false
+  const first = g[0]
+  if (first === 0 && g.every((v) => v === 0)) return true // :: 未指定（等同 0.0.0.0）
+  if (first === 0 && g.slice(1, 7).every((v) => v === 0) && g[7] === 1) return true // ::1 回环
+  if (first >= 0xfe80 && first <= 0xfebf) return true // fe80::/10 链路本地
+  if (first >= 0xfc00 && first <= 0xfdff) return true // fc00::/7 ULA 私有段
+  // 内嵌 IPv4 统一判定：::/96 兼容、::ffff:0:0/96 映射与翻译三种形态。
+  // 结构一致——前 6 组至多一个 0xffff 标记、标记之前全零、末两组为 32 位 IPv4。
+  // 注意不能只用 indexOf(0xffff) 判定：compatible 形态无 ffff 标记会漏拦。
+  const ffffIdx = g.indexOf(0xffff)
+  const markerCount = g.slice(0, 6).filter((v) => v === 0xffff).length
+  const prefixSlice = ffffIdx === -1 ? g.slice(0, 6) : g.slice(0, ffffIdx)
+  const prefixAllZero = prefixSlice.every((v) => v === 0)
+  const isEmbeddedIPv4 = ffffIdx <= 5 && markerCount <= 1 && prefixAllZero
+  if (isEmbeddedIPv4) {
+    return isPrivateIPv4(toDotQuad((g[6] << 16) | g[7]))
+  }
+  return false
+}
+
+/**
+ * 校验 fetch 目标 URL 可访问，通过则返回规范化后的 URL 供 fetch 使用。
+ * 不抛异常即视为放行；违规抛 FetchGuardError 携带原因说明。
+ */
+export function assertFetchableUrl(
+  input: string,
+  options: FetchGuardOptions = {},
+): URL {
+  let url: URL
+  try {
+    url = new URL(input)
+  } catch {
+    throw new FetchGuardError(input, "无效 URL")
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new FetchGuardError(input, `协议 ${url.protocol} 不在允许范围（仅 http/https）`)
+  }
+
+  // IPv6 主机在 WHATWG URL 中带方括号（[::1]），剥离后与判定规则对齐
+  const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "")
+
+  // 先过一遍整数形式归一化，再判定私网，防止十六进制等混淆绕过点分十进制正则。
+  // 含冒号即 IPv6 字面量，交由 IPv6 判定（含 IPv4-mapped 还原），两者互斥不叠加
+  const isPrivate =
+    host === "localhost" ||
+    host.endsWith(".localhost") ||
+    host.endsWith(".internal") ||
+    (host.includes(":") ? isPrivateIPv6(host) : isPrivateIPv4(normalizeIntegerIp(host) ?? host))
+
+  if (isPrivate && !options.allowPrivate) {
+    throw new FetchGuardError(input, "私网/回环/链路本地地址被 SSRF 防护拒绝")
+  }
+
+  if (options.allowedHosts && !options.allowedHosts.includes(host)) {
+    throw new FetchGuardError(input, `主机 ${host} 不在白名单`)
+  }
+
+  return url
+}