跳到正文

@xid-kit/react-native

用于 Hosted Auth 重定向、PKCE S256、deep-link callback 和安全 token 存储适配器的 React Native provider 和 hook。

状态

包状态为 当前包。它实现了共享原生契约:带 PKCE S256 的 Hosted Auth 重定向、deep-link callback 上的 CSRF state 验证、对 token 端点的授权码交换,以及通过注入存储适配器的安全 token 持久化。

在真实生产基础设施上的 IdP 往返验证仍待人工核实。本页面记录已实现的行为,不代表生产就绪声明。

Provider 配置

TokenCache(平台安全存储)和 BrowserInterface(应用内浏览器)注入 XidProvider。SDK 不硬绑定任何原生模块;Expo 应用可使用 @xid-kit/expo 中的现成适配器。

import { XidProvider } from '@xid-kit/react-native'
import type { BrowserInterface, TokenCache } from '@xid-kit/react-native'
import * as Keychain from 'react-native-keychain'

const tokenCache: TokenCache = {
  async getToken(key) {
    const result = await Keychain.getGenericPassword({ service: key })
    return result ? result.password : null
  },
  async saveToken(key, value) {
    await Keychain.setGenericPassword('xid', value, { service: key })
  },
  async deleteToken(key) {
    await Keychain.resetGenericPassword({ service: key })
  },
}

const browser: BrowserInterface = {
  async openAuthSession(url, redirectUri) {
    // Open url with your in-app browser library, wait for the redirectUri
    // deep link, then return { type: 'success', url } or { type: 'cancel' }.
    throw new Error('Implement with your preferred in-app browser library.')
  },
}

export function App() {
  return (
    <XidProvider
      publishableKey="pk_live_..."
      apiUrl="https://xid.dev"
      issuer="https://xid.dev"
      clientId="your_client_id"
      redirectUri="myapp://auth/callback"
      tokenCache={tokenCache}
      browser={browser}
    >
      <RootNavigator />
    </XidProvider>
  )
}

登录

signIn() 构建 PKCE S256 授权 URL,将 verifier 和 OAuth state 存入 token 缓存,打开浏览器适配器,并交换返回的 code 获取 token。浏览器失败、CSRF state 不匹配和 token 交换错误会以 signInState.status === 'error' 的形式暴露。

import { useSignIn } from '@xid-kit/react-native'

function SignInScreen() {
  const { signIn, signInState } = useSignIn()

  return (
    <Button
      title={signInState.status === 'pending' ? 'Signing in...' : 'Sign in'}
      onPress={() => void signIn()}
    />
  )
}

深度链接回调

当浏览器适配器无法自行捕获重定向时,在应用清单中注册重定向 URI scheme,并将 deep link 转发给 handleRedirect(url)。它会校验 OAuth state、交换 code 并存储 token 集。

import { useSignIn } from '@xid-kit/react-native'
import { useEffect } from 'react'
import { Linking } from 'react-native'

function DeepLinkHandler() {
  const { handleRedirect } = useSignIn()

  useEffect(() => {
    const sub = Linking.addEventListener('url', ({ url }) => {
      if (url.startsWith('myapp://auth/callback')) {
        void handleRedirect(url)
      }
    })
    return () => sub.remove()
  }, [handleRedirect])

  return null
}

导出的 API

导出 类型 用途
XidProvider 组件 封装 @xid-kit/react provider,注入 tokenCache、browser、issuer、clientId、redirectUri 和 scopes
useSignIn hook signIn(options?) 运行完整重定向流程;handleRedirect(url) 处理 deep-link callback;signInState 报告 idle、pending、complete、cancelled 或 error 状态
useSignOut hook signOut() 清除本地 token 集,然后通过 useAuth().signOut 吊销服务端会话;signOutState 报告进度
useXidRnContext hook 原始适配器上下文(高级用法和测试)
exchangeCodeForTokens function 使用 grant_type authorization_code 和 PKCE verifier 向 token 端点发起底层 POST;返回 TokenSet
saveTokenSet / clearTokenSet 函数 在 TokenCache 适配器中持久化或删除 token 集
TOKEN_KEYS as const 对象 access、refresh 和 ID token 的 TokenCache 密钥名,以及 PKCE verifier 和 OAuth state
createPkceVerifier / createPkceChallenge 函数 PKCE S256 工具委托给 @xid-kit/protocol(Web Crypto)
createRandomString / base64UrlEncode 函数 OAuth state 的 URL 安全随机字符串;base64url 编码辅助工具

来自 @xid-kit/react 的重导出

会话 hook 和控制组件从 @xid-kit/react 原样重导出:useAuthuseUseruseSessionuseSessionListuseOrganizationuseOrganizationListuseAPIKeysSignedInSignedOutProtectXidLoadedXidLoadingXidFailedXidDegraded

类型

类型 描述
XidProviderProps @xid-kit/react provider props,另加 tokenCache、browser、issuer、clientId、redirectUri 和可选 scopes(默认 openid, profile, email)
TokenCache 存储适配器契约:getToken、saveToken、deleteToken(均为异步)
BrowserInterface openAuthSession(url, redirectUri) 解析为 BrowserResult
BrowserResult success(含 callback URL)、cancel 和 dismiss 的联合类型
SignInOptions signIn 的单次调用覆盖选项:redirectUri、scopes
SignInState / SignOutState hook 返回的判别状态联合类型
UseSignInReturn / UseSignOutReturn hook 返回结构:操作加状态
TokenExchangeInput / TokenSet exchangeCodeForTokens 的输入和结果:accessToken、refreshToken、idToken、expiresIn
XidRnContextValue useXidRnContext 返回的适配器上下文结构

已知限制

  • token 过期时无自动会话刷新;存储的 refresh token 可供应用自行管理续期。
  • useAuth().isSignedIn 反映的是 XidClient cookie 会话,而非 TokenCache 内容。成功交换 token 后重新加载客户端状态以驱动实时认证状态。
  • 组织上下文尚未从存储的 token 中填充。

安全

  • 仅支持带 PKCE S256 的授权码流程,不支持 implicit 或 password grant。
  • 公开客户端从不存储客户端密钥。
  • PKCE verifier 和 OAuth state 存在于注入的安全存储适配器中,code 交换后删除。
  • signOut 清除本地 token 集并吊销服务端会话;失败会在 signOutState 中反映,而不是被吞掉。
导航

输入内容以搜索...

使用方向键导航按 Enter 键选择按 Escape 键关闭