Supabase Auth Callback Worker

English version | 中文版

这是一个 Cloudflare Worker，用于接收 Supabase 认证回调，验证邮箱验证结果或 OAuth 授权结果，并把成功后的 session 转成自定义 Deep Link，唤起本地 App。

功能概览

• 接收邮箱验证回调：/auth/email-callback
• 接收 OAuth 回调：/auth/oauth-callback
• 健康检查：/health
• 支持两种邮箱验证入口：
  • token_hash + type 形式（手工 / 兼容模式）
  • 真实 Supabase 邮件重定向返回的 ?code=... / ?error=... / #access_token=...
• 成功时返回漂亮的 HTML 成功页，并尝试跳转 myapp://... Deep Link
• 失败时返回漂亮的 HTML 错误页，并显示中文 + 英文失败原因
• 可选：验证成功后异步发送欢迎邮件（Resend）
• 可选：支持 OAuth PKCE code 交换，并自动生成 Deep Link

端点说明

1. 健康检查

GET /health

返回 JSON：

{
  "status": "ok",
  "time": "2026-09-18T12:00:00.000Z"
}

2. 邮箱验证回调

GET /auth/email-callback?token_hash=xxx&type=email

或真实 Supabase 回调形式：

GET /auth/email-callback?code=eb...
GET /auth/email-callback?error=access_denied&error_code=otp_expired&error_description=Email+link+is+invalid+or+has+expired
GET /auth/email-callback#access_token=...&refresh_token=...&expires_in=3600&token_type=bearer

它会做这些事：

1. 若是 token_hash / type 模式，调用 Supabase /auth/v1/verify
2. 若是 code 模式，尝试交换 PKCE 授权码
3. 若是 error 模式，读取失败参数并渲染错误页
4. 若是 #access_token= 模式，直接生成 Deep Link
5. 生成 myapp://callback#... 这种自定义 scheme 的深链接
6. 返回对应的 HTML 状态页

3. OAuth 回调

GET /auth/oauth-callback?code=xxx
GET /auth/oauth-callback?code=xxx&code_verifier=yyy

Worker 会请求：

POST {SUPABASE_URL}/auth/v1/token?grant_type=pkce

并使用返回的 session 生成 deep link。该回调主要用于自己维护 PKCE 流程的 OAuth 登录场景。

Deep Link 生成规则

Worker 会把 session 参数拼成 hash 片段：

#access_token=...&refresh_token=...&expires_in=3600&token_type=bearer

然后生成：

${DEEP_LINK_SCHEME}://${DEEP_LINK_HOST}${sessionHash}

例如：

myapp://callback#access_token=xxx&refresh_token=yyy&expires_in=3600&token_type=bearer

App 收到这个链接之后，就能用 access_token / refresh_token 直接恢复登录状态。

结果页

Worker 会返回两个状态页：

• 成功页：绿色主题，显示“邮箱验证成功 / 登录成功”，并尝试跳转 App
• 失败页：红色主题，显示“邮箱验证失败 / OAuth 失败”，并显示中文/英文原因

成功页会自动在 700ms 后尝试 window.location.href = deepLink，如果没有自动跳转，就显示手动“打开 App”按钮。

环境变量

在 Cloudflare Worker 中使用这些变量：

SUPABASE_URL="https://xxx.supabase.co"
SUPABASE_ANON_KEY="..."
SUPABASE_REDIRECT_URL="http://127.0.0.1:8787/auth/email-callback"
DEEP_LINK_SCHEME="myapp"
DEEP_LINK_HOST="callback"

# 可选：邮件通知
RESEND_API_KEY="re_xxx"
MAIL_FROM="no-reply@yourdomain.com"
MAIL_FROM_NAME="Your App"
MAIL_REPLY_TO="support@yourdomain.com"
MAIL_ENABLED="true"
APP_NAME="Your App"

说明：

• SUPABASE_URL：Supabase Project URL
• SUPABASE_ANON_KEY：Supabase 的 anon / publishable key
• SUPABASE_REDIRECT_URL：用于邮箱验证的回调地址，必须和 Supabase Auth 配置中的 Redirect URL 一致
• DEEP_LINK_SCHEME：App 的 custom scheme，例如 myapp
• DEEP_LINK_HOST：App 的 deep link host，例如 callback
• MAIL_ENABLED：邮件功能开关，默认开启；但必须同时存在 RESEND_API_KEY 和 MAIL_FROM 才真正可用

Mailer（可选）

src/mailer.js 中实现了 Resend 邮件发送：

• isMailerEnabled(env)：判断是否允许发送邮件
• sendEmail(env, mail)：通用发送接口
• sendWelcomeEmail(env, to, appName)：验证成功后的欢迎邮件

发送条件：

RESEND_API_KEY 存在
MAIL_FROM 存在
MAIL_ENABLED != "false"

如果未满足条件，Worker 会静默跳过发送，不影响认证流程。

本地开发

npm install
npx wrangler dev --ip 0.0.0.0 --port 8787

然后访问：

http://127.0.0.1:8787/health
http://127.0.0.1:8787/auth/email-callback?token_hash=xxx&type=email

生产部署

npx wrangler login
npx wrangler deploy

如果要设置敏感变量：

npx wrangler secret put SUPABASE_URL
npx wrangler secret put SUPABASE_ANON_KEY
npx wrangler secret put RESEND_API_KEY

其余非敏感变量可放在 wrangler.toml 的 [vars] 中。

Supabase 配置建议

1. Auth URL 配置

在 Supabase 控制台里配置：

• Site URL
• Redirect URLs

至少包含：

http://127.0.0.1:8787/auth/email-callback
https://your-worker-url.workers.dev/auth/email-callback

如果你在认证邮件模板中使用自定义 redirect_to，请确保它和这里配置的一致。

2. 邮箱验证码模板

这个 Worker 接收的标准邮箱验证入口通常是：

{redirectTo}?token_hash={tokenHash}&type=email

也支持 Supabase 实际回调返回的 ?code=... 或 ?error=... 形式，因此可以直接用在真实邮件跳转场景中。

典型用例

邮箱注册成功后

1. 用户点击来自 Supabase 的确认邮件链接
2. Worker 拦截后验证 token
3. 生成 Deep Link
4. 页面展示成功，同时跳转到 App
5. 如配置了 Resend，则异步发送欢迎邮件

OAuth 登录成功后

1. 前端拿到 OAuth code
2. 请求 Worker /auth/oauth-callback?code=...
3. Worker 调用 Supabase token 接口
4. 返回成功页并生成 App deep link

链接失效或过期

1. Supabase 返回 error=access_denied&error_code=otp_expired...
2. Worker 解析其中的中文/英文失败原因
3. 页面展示失败页，并提示用户重新请求验证邮件

注意事项

• 不要把 service_role secret 传给 Worker 或前端
• SUPABASE_REDIRECT_URL 必须和 Supabase Auth 配置一致
• 邮件发送是可选功能，未配置要素时自动关闭
• Deep Link 与系统 App Scheme 需要在客户端中注册好，否则页面可能跳转失败

许可证

本项目按你所在仓库的实际许可证发布。

OAuth 登录

await supabase.auth.signInWithOAuth(
  OAuthProvider.google,
  redirectTo: 'com.yourcompany.storyapp://auth',
);

上面的 OAuth 写法让 Supabase 直接把登录结果交给 Flutter，推荐用于 supabase_flutter。此流程不经过 /auth/oauth-callback，也不需要把 Flutter SDK 内部的 code_verifier 传给 Worker。

如果客户端自行实现 PKCE 并能安全保存 code_verifier，才使用 Worker OAuth 地址：

redirectTo: 'https://your-worker.workers.dev/auth/oauth-callback'

回调请求必须包含与授权请求对应的 code_verifier，并且该地址也必须加入 Supabase 的 Authentication → URL Configuration → Redirect URLs。