@xid-kit/react-native

Hosted Auth 리디렉션, PKCE S256, 딥 링크 콜백, 안전한 토큰 저장소 어댑터를 위한 React Native provider 및 hook.

상태

패키지 상태: 현재 패키지. Hosted Auth PKCE S256 리디렉션, 딥 링크 콜백의 CSRF state 검증, token 엔드포인트에 대한 인증 코드 교환, 주입된 저장소 어댑터를 통한 안전한 토큰 영속성으로 구성된 공유 네이티브 계약을 구현합니다.

프로덕션 인프라에서의 실제 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
      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을 생성하고, 검증자와 OAuth state를 토큰 캐시에 저장한 후 브라우저 어댑터를 열어 반환된 코드를 토큰으로 교환합니다. 브라우저 오류, CSRF state 불일치, 토큰 교환 오류는 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 스킴을 등록하고 딥 링크를 handleRedirect(url)로 전달하세요. OAuth state를 검증하고 코드를 교환하며 토큰 세트를 저장합니다.

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)는 딥 링크 콜백을 처리합니다. signInState는 idle, pending, complete, cancelled, error를 보고합니다.
`useSignOut`	hook	signOut()은 로컬 토큰 세트를 지우고 useAuth().signOut을 통해 서버 세션을 폐기합니다. signOutState는 진행 상황을 보고합니다.
`useXidRnContext`	hook	원시 어댑터 컨텍스트(고급 사용 및 테스트)
`exchangeCodeForTokens`	function	grant_type authorization_code와 PKCE 검증자를 사용해 token 엔드포인트로 저수준 POST 요청; TokenSet을 반환합니다
`saveTokenSet / clearTokenSet`	함수	TokenCache 어댑터에서 토큰 세트를 저장하거나 제거합니다
`TOKEN_KEYS`	as const 객체	액세스, refresh, ID 토큰과 PKCE 검증자 및 OAuth state를 위한 TokenCache 키 이름
`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 속성에 tokenCache, browser, issuer, clientId, redirectUri, 그리고 선택적 scopes(기본값: openid, profile, email)를 추가합니다.
`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, refreshToken, idToken, expiresIn
`XidRnContextValue`	useXidRnContext가 반환하는 어댑터 컨텍스트 형태

알려진 제한 사항

토큰 만료 시 자동 세션 갱신이 없습니다. 저장된 refresh 토큰은 애플리케이션 관리 갱신에 사용할 수 있습니다.
useAuth().isSignedIn은 TokenCache 내용이 아닌 XidClient cookie 세션을 반영합니다. 실시간 인증 상태를 반영하려면 토큰 교환 성공 후 클라이언트 상태를 다시 로드하세요.
조직 컨텍스트는 저장된 토큰에서 아직 채워지지 않습니다.

보안

PKCE S256 전용 인가 코드. implicit 또는 password grant는 지원하지 않습니다.
공개 클라이언트는 클라이언트 비밀값을 저장하지 않습니다.
PKCE 검증자와 OAuth state는 주입된 안전 저장소 어댑터에 보관되며 코드 교환 후 삭제됩니다.
signOut은 로컬 토큰 세트를 지우고 서버 세션을 폐기합니다. 실패는 무시되지 않고 signOutState에 나타납니다.