blink-auth

重要：在应用中使用提供方之前，请通过 CLI 或 MCP 启用它们：blink auth-config set --provider google --enabled true

MCP 工具

blink_auth_get_config · blink_auth_set_config

快速开始

# Enable auth providers via CLI
blink auth-config set --provider google --enabled true
blink auth-config set --provider github --enabled true
blink auth-config set --provider email --enabled true

两种身份验证模式

托管模式（快速设置）

重定向到托管的身份验证页面。最适合网站和 MVP。不适用于移动端。

关键提示：在托管模式下，只能使用 blink.auth.login() 和 blink.auth.logout()。调用 signInWithGoogle()、signInWithEmail() 或任何其他身份验证方法都会抛出错误："signInWithGoogle is only available in headless mode"。如果需要自定义身份验证界面，请改用无头模式。

const blink = createClient({
  projectId: import.meta.env.VITE_BLINK_PROJECT_ID || 'your-project-id',
  publishableKey: import.meta.env.VITE_BLINK_PUBLISHABLE_KEY || 'blnk_pk_xxx',
  auth: { mode: 'managed' },
})

blink.auth.login()                            // ✅ Redirects to blink.new/auth
blink.auth.login('https://app.com/dashboard') // ✅ Custom redirect after login
blink.auth.logout()                           // ✅ Sign out

// ❌ These ALL throw in managed mode:
// blink.auth.signInWithGoogle()
// blink.auth.signInWithEmail(email, password)
// blink.auth.signUp({ email, password })

无头模式（自定义界面）

完全控制身份验证界面。移动端（Expo/React Native）及任何自定义登录表单都必须使用此模式。

const blink = createClient({
  projectId: import.meta.env.VITE_BLINK_PROJECT_ID || 'your-project-id',
  publishableKey: import.meta.env.VITE_BLINK_PUBLISHABLE_KEY || 'blnk_pk_xxx',
  auth: { mode: 'headless' },  // ← must be headless for all methods below
})

await blink.auth.signUp({ email, password })
await blink.auth.signInWithEmail(email, password)
await blink.auth.signInWithGoogle()    // ✅ only works in headless mode
await blink.auth.signInWithGitHub()
await blink.auth.signInWithApple()
await blink.auth.signInWithMicrosoft()

模式对比

功能	托管模式	无头模式
设置	1 行	自定义界面
移动端	❌	✅ 必需
品牌标识	Blink 品牌	完全自定义

身份验证状态监听器（React 必需）

useEffect(() => {
  const unsubscribe = blink.auth.onAuthStateChanged((state) => {
    setUser(state.user)
    if (!state.isLoading) setLoading(false)  // Only set false, never reset to true
  })
  return unsubscribe
}, [])

加载状态：加载期间始终显示加载动画或骨架屏，切勿 return null（这会导致生产环境出现空白屏幕）。

使用自定义字段注册

await blink.auth.signUp({
  email: '[email protected]',
  password: 'password123',
  displayName: 'John Doe',
  role: 'editor',
  metadata: { company: 'Acme Inc' },
})

密码重置

await blink.auth.sendPasswordResetEmail(email)
await blink.auth.confirmPasswordReset(token, newPassword)

// Custom flow: generate token, send your own email
const { token, resetUrl } = await blink.auth.generatePasswordResetToken(email)

魔法链接

await blink.auth.sendMagicLink(email)
await blink.auth.verifyMagicLink(token)

RBAC（基于角色的访问控制）

const blink = createClient({
  projectId: import.meta.env.VITE_BLINK_PROJECT_ID || 'your-project-id',
  publishableKey: import.meta.env.VITE_BLINK_PUBLISHABLE_KEY || 'blnk_pk_xxx',
  auth: {
    mode: 'headless',
    roles: {
      admin: { permissions: ['*'] },
      editor: { permissions: ['posts.create', 'posts.update'], inherit: ['viewer'] },
      viewer: { permissions: ['posts.read'] },
    },
  },
})

blink.auth.can('posts.update')    // Check permission
blink.auth.hasRole('admin')       // Check role

核心方法

const user = await blink.auth.me()
await blink.auth.updateMe({ displayName: 'New Name' })
const token = await blink.auth.getValidToken()
await blink.auth.signOut()

身份验证与 Blink API 的交互方式

登录后，SDK 会自动附加 Authorization: Bearer <JWT>。大多数模块都需要身份验证。公开接口例外：分析数据写入、存储上传（仅添加）。

Expo/React Native 设置

import * as WebBrowser from 'expo-web-browser'
import AsyncStorage from '@react-native-async-storage/async-storage'
import { createClient, AsyncStorageAdapter } from '@blinkdotnew/sdk'

const blink = createClient({
  projectId: process.env.EXPO_PUBLIC_BLINK_PROJECT_ID!,
  publishableKey: process.env.EXPO_PUBLIC_BLINK_PUBLISHABLE_KEY!,
  auth: { mode: 'headless', webBrowser: WebBrowser },
  storage: new AsyncStorageAdapter(AsyncStorage),
})