상태
Registry 상태: UNPUBLISHED. 이 SDK는 저장소 소스 checkout에서만 설치하고 외부 package registry를 사용하지 마세요.
Package 상태는 현재 package입니다. 이 package는 PKCE S256을 사용하는 Hosted Auth redirect, deep-link callback의 state 및 nonce 검증, 검증된 ID token claims, authorization code exchange, 주입된 storage adapter를 통한 secure session 영속화로 구성된 native token-session contract를 구현합니다.
프로덕션 인프라에서의 실제 IdP 왕복 테스트는 수동 검증 대기 중입니다. 이 페이지는 구현된 동작을 문서화하며, 준비 완료를 의미하지 않습니다.
공급자 설정
XidProvider에 TokenCache(플랫폼 안전 저장소)와 BrowserInterface(인앱 브라우저)를 주입하세요. 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
issuer="https://xid.dev"
clientId="your_client_id"
redirectUri="myapp://auth/callback"
tokenCache={tokenCache}
browser={browser}
>
<RootNavigator />
</XidProvider>
)
}로그인
signIn()은 PKCE S256 authorize URL을 구성하고 verifier, OAuth state, nonce를 token cache에 저장한 다음 browser adapter를 열어 반환된 code를 검증된 native session으로 교환합니다. 브라우저 실패, state 불일치, ID token 검증 오류, token exchange 오류는 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()}
/>
)
}딥 링크 콜백
browser adapter가 redirect를 직접 캡처할 수 없으면 app manifest에 redirect URI scheme을 등록하고 deep link를 handleRedirect(url)로 전달합니다. 이 함수는 OAuth state, verifier, nonce를 검증하고 소비한 다음 code를 교환하고 ID token을 검증하여 native session을 저장합니다.
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 |
컴포넌트 | tokenCache, browser, issuer, clientId, redirectUri, scopes, 선택적 fetcher를 사용하는 native token-session context를 제공합니다. |
useSignIn |
hook | signIn(options?)은 전체 리디렉션 흐름을 실행합니다. handleRedirect(url)는 딥 링크 콜백을 처리합니다. signInState는 idle, pending, complete, cancelled, error를 보고합니다. |
useSignOut |
hook | signOut()은 로컬 session과 legacy credentials를 지웁니다. signOutState는 진행 상태 또는 storage failures를 보고하며 revoke request는 전송하지 않습니다. |
useXidRnContext |
hook | 원시 어댑터 컨텍스트(고급 사용 및 테스트) |
exchangeCodeForTokens |
function | grant_type authorization_code와 PKCE 검증자를 사용해 token 엔드포인트로 저수준 POST 요청; TokenSet을 반환합니다 |
saveTokenSet / clearTokenSet |
함수 | TokenCache 어댑터에서 토큰 세트를 저장하거나 제거합니다 |
TOKEN_KEYS |
as const 객체 | 현재 session envelope와 대기 중인 PKCE, state, nonce records의 TokenCache key names입니다. legacy token keys는 cleanup 용도로만 사용됩니다. |
createPkceVerifier / createPkceChallenge |
함수 | PKCE S256 유틸리티는 @xid-kit/protocol(Web Crypto)에 위임됩니다 |
createRandomString / base64UrlEncode |
함수 | OAuth state를 위한 URL 안전 무작위 문자열; base64url 인코딩 헬퍼 |
Native hooks 및 controls
@xid-kit/react와 달리 이 package는 자체 native token context를 사용합니다. useAuth, useUser, useSession, useSignIn, useSignOut, useXidRnContext, SignedIn, SignedOut, XidLoaded, XidLoading, exchangeCodeForTokens, saveTokenSet, readTokenSet, clearTokenSet을 export하며 React Web SDK를 import하거나 다시 export하지 않습니다.
타입
| 유형 | 설명 |
|---|---|
XidProviderProps |
Native provider props: children, tokenCache, browser, issuer, clientId, redirectUri, 선택적 scopes(기본값 openid, profile, email), 선택적 fetcher |
TokenCache |
저장소 어댑터 계약: getToken, saveToken, deleteToken(모두 비동기) |
BrowserInterface |
BrowserResult로 resolve되는 openAuthSession(url, redirectUri) |
BrowserResult |
성공(콜백 URL 포함), 취소, 닫기의 유니온 |
SignInOptions |
signIn 호출별 오버라이드: redirectUri, scopes |
SignInState / SignOutState |
hook이 반환하는 판별 상태 유니온 |
UseSignInReturn / UseSignOutReturn |
hook 반환 형태: 액션과 상태 |
TokenExchangeInput / TokenSet |
exchangeCodeForTokens의 입력과 결과: accessToken, idToken, expiresIn, 검증된 ID token claims |
XidRnContextValue |
useXidRnContext가 반환하는 어댑터 컨텍스트 형태 |
알려진 제한 사항
- SDK에는 DPoP sender binding이 없고 offline_access를 거부하며 access token이 만료되면 새로운 authorization flow가 필요합니다.
- useAuth().isSignedIn은 ID token 검증이 완료된 뒤에만 로컬에 저장된 session을 반영합니다. Web cookie session은 읽지 않습니다.
- 조직 컨텍스트는 저장된 토큰에서 아직 채워지지 않습니다.
보안
- PKCE S256 전용 인가 코드. implicit 또는 password grant는 지원하지 않습니다.
- 공개 클라이언트는 클라이언트 비밀값을 저장하지 않습니다.
- PKCE 검증자와 OAuth state는 주입된 안전 저장소 어댑터에 보관되며 코드 교환 후 삭제됩니다.
- signOut은 refresh 또는 revoke request 없이 로컬 session과 legacy credentials를 지웁니다. storage failures는 signOutState에 표시됩니다.