---
title: "@xid-kit/react-native"
description: "用于 Hosted Auth 重定向、PKCE S256、deep-link callback 和安全 token 存储适配器的 React Native provider 和 hook。"
locale: "zh-Hans"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/zh-hans/llms.txt
> Use this file to discover all available pages before exploring further.

# @xid-kit/react-native

## 状态

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

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

## Provider 配置

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

```tsx
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'` 的形式暴露。

```tsx
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 集。

```tsx
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](/zh-hans/sdks/react) 原样重导出：`useAuth`、`useUser`、`useSession`、`useSessionList`、`useOrganization`、`useOrganizationList`、`useAPIKeys`、`SignedIn`、`SignedOut`、`Protect`、`XidLoaded`、`XidLoading`、`XidFailed` 和 `XidDegraded`。

## 类型

| 类型 | 描述 |
| --- | --- |
| `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 中反映，而不是被吞掉。

Source: https://xid.dev/zh-hans/sdks/react-native/index.mdx