MkExt

MkExt 是基于 WXT、React 和 Base UI 的浏览器插件模板。它提供 popup、options、side panel、新标签页、DevTools、content script 和后台 worker 等入口，你可以用一套 TypeScript 代码构建完整的产品插件。

MkExt 是客户端模板，不包含数据库、邮件服务或 OAuth 服务端。插件需要账号、会话和受保护的产品 API 时，可以与 TanStarter 配合使用。TanStarter 当前 main 分支已经包含本页介绍的插件身份验证支持。

网站：mkext.dev

源码：MkThingsHQ/mkext

集成后能实现什么

两个项目共用 TanStarter 的用户和会话体系。MkExt 将产品 bearer token 存在插件 storage 中，不依赖网站跨站 cookie。

Google 登录时，Chrome Identity API 先获取短期 Google access token；TanStarter 验证它的 audience 必须是你的 Chrome Extension OAuth client，再获取 Google 用户资料，创建或关联 TanStarter 用户，最后返回 TanStarter bearer token。不要把 Google access token 当作产品会话，也不要持久化为产品登录态。

前提条件

• 一个基于当前 main 分支的 TanStarter 应用，并已经配置数据库和基础认证。请先阅读身份验证和环境配置。
• 一个已安装 Bun 的 MkExt checkout。
• 稳定的 Chrome 插件 ID。
• 如果要使用 Google 登录，还需要 Google Cloud 项目和 OAuth consent screen。邮箱/密码登录不需要 Google 配置。

1. 配置 MkExt

将 MkExt 的 .env.example 复制为 .env，并指向 TanStarter 应用的公开 origin：

# 构建期公开配置，会被编译进插件包。
VITE_AUTH_URL="https://app.example.com"

# 仅 Chrome Google 登录需要。这是公开 client ID，不是 client secret。
VITE_GOOGLE_EXTENSION_CLIENT_ID="your-extension-client-id.apps.googleusercontent.com"

VITE_AUTH_URL 只能填写 origin，不要追加 /api/auth。MkExt 会基于它派生 Better Auth 和 Google token 交换端点。所有 VITE_* 变量都会进入插件包，绝不能把 GOOGLE_CLIENT_SECRET、BETTER_AUTH_SECRET、数据库密钥或其他服务端机密写进这个文件。

MkExt manifest 会把这个认证 origin 加入 host permission。设置了 VITE_GOOGLE_EXTENSION_CLIENT_ID 后，Chrome manifest 还会声明 identity 权限、OAuth client ID，以及 openid、email、profile scopes。

2. 获取稳定的 Chrome 插件 ID

Google 的 Chrome Extension OAuth client 与插件 ID 绑定。MkExt 的 WXT 配置中包含 manifest public key，因此常规 Chrome 构建会得到固定 ID。请先构建并加载这个准确的包，再创建 Google client：

cd mkext
bun install
bun run build

打开 chrome://extensions，开启开发者模式，点击加载已解压的扩展程序，选择 build/chrome-mv3，复制 Chrome 显示的插件 ID。

3. 配置 Google OAuth（可选）

在管理产品 OAuth 配置的 Google Cloud 项目中：

1. 完成应用的 OAuth consent screen 配置。
2. 创建一个 Chrome Extension 类型的 OAuth 2.0 client，并填写刚才从 chrome://extensions 复制的插件 ID。
3. 将这个 client ID 同时写入 MkExt 的 VITE_GOOGLE_EXTENSION_CLIENT_ID 和 TanStarter 的 GOOGLE_EXTENSION_CLIENT_ID。
4. 同时保留 TanStarter 常规 Google OAuth 的 client ID 和 client secret。当前 TanStarter 的 Google provider 由 websiteConfig.auth.enableGoogleLogin、GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET 一起启用；插件 client 只是额外允许的 token audience，并不能替代网站 client。

Chrome Extension client 仅用于 Chrome。MkExt 在 Firefox 中会移除 Chrome 专用的 oauth2 manifest 配置，因为 Firefox 不提供相同的 identity.getAuthToken() 流程。

4. 配置 TanStarter

把插件 origin 和 OAuth 配置写入 TanStarter 的服务端运行环境。本地开发使用 .env.local；Cloudflare Workers 部署时使用 wrangler secret put 或你的部署密钥管理方式。

# 生产环境 Better Auth 必填。
BETTER_AUTH_SECRET="generate-a-strong-secret"

# 精确允许跨来源认证的 origin，多个值使用逗号分隔。
BETTER_AUTH_TRUSTED_ORIGINS="chrome-extension://<your-extension-id>"

# TanStarter 常规网页 Google OAuth client，仅服务端使用。
GOOGLE_CLIENT_ID="your-web-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-web-client-secret"

# 必须与 MkExt 的 VITE_GOOGLE_EXTENSION_CLIENT_ID 完全一致。
GOOGLE_EXTENSION_CLIENT_ID="your-extension-client-id.apps.googleusercontent.com"

还要确认 src/config/website.ts 已启用 Google 登录：

auth: {
  enable: true,
  // 插件要提供 Google 登录时要启用这一项
  enableGoogleLogin: true,
  // 插件要提供邮箱/密码登录时要启用这一项
  enableCredentialLogin: true,
}

TanStarter 会根据这些配置：

• 启用 Better Auth 的 bearer-token plugin；
• 仅对配置的插件 origin 开放 Better Auth 和 CORS；
• 接受 Authorization，并暴露 set-auth-token 响应头；
• 验证 Google 插件 token 属于 GOOGLE_EXTENSION_CLIENT_ID；
• 为返回的产品 bearer token 创建普通 TanStarter session。

如需 Firefox 包，可添加对应的 moz-extension://<uuid> origin。Firefox 的 UUID 按 profile 分配，因此 TanStarter 支持显式的 moz-extension://* opt-in。它只解决 origin 边界，不能让 Firefox 获得 Chrome Google Identity API。

5. 完整验证流程

修改 MkExt 的 .env 后，重新构建或重新加载 Chrome 插件，并针对真实 TanStarter 部署验证：

1. 打开插件登录页，用邮箱/密码注册或登录，确认使用的是新建或已有的 TanStarter 账号。
2. 配置 Google 后，选择 Google 登录并完成 Chrome 的账号选择。
3. 确认插件同步会话后显示的是 TanStarter 用户。
4. 从插件调用一个受保护的 TanStarter API，确认 bearer session 被接受。
5. 登出、重新打开插件，确认本地 bearer session 已被清除。

排查时可以按响应定位：403 通常表示 BETTER_AUTH_TRUSTED_ORIGINS 缺少或写错插件 ID；503 表示 TanStarter 未配置 GOOGLE_EXTENSION_CLIENT_ID；Google audience 错误通常表示两端 extension client ID 或 Chrome 插件 ID 不匹配。

下一步