状态
包状态为 当前包。它实现了共享原生契约:带 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 原样重导出: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 中反映,而不是被吞掉。