@xid-kit/core

세션 상태, 단기 JWT 접근, 관리 API 헬퍼를 위한 브라우저 클라이언트입니다.

설치 및 설정

Registry 상태: UNPUBLISHED. 이 SDK는 저장소 소스 checkout에서만 설치하고 외부 package registry를 사용하지 마세요.

다른 origin의 개발자 앱에서는 issuer, clientId, 정확한 redirectUri와 함께 mode: 'oidc'를 구성합니다. 애플리케이션이 정확히 동일한 origin에서 Core auth endpoints를 라우팅하는 경우에만 same-origin mode를 사용합니다. XID에는 publishable-key credential이 없습니다.

import { XidClient } from '@xid-kit/core'

const xid = new XidClient({
  mode: 'oidc',
  issuer: 'https://xid.dev',
  clientId: 'client_abc123',
  redirectUri: 'https://app.example.com/auth/callback',
})

const authorization = await xid.createAuthorizationUrl({ returnUrl: '/dashboard' })
if (!authorization.ok) throw new Error(authorization.error.message)
window.location.assign(authorization.value)

세션 수명주기

load()은 /v1/me를 읽어 사용자, 세션, 활성 조직을 초기화합니다.
signInPassword()는 Hosted Auth 비밀번호 흐름을 통해 cookie 세션을 생성합니다.
getToken()은 API 호출용 단기 JWT를 반환합니다. 백엔드에서 JWKS를 이용해 네트워크 호출 없이 검증하세요.
setActiveOrganization()은 조직 컨텍스트를 전환하고 상태를 다시 로드하기 전에 token 캐시를 초기화합니다.
signOut()은 브라우저 세션 cookie를 폐기합니다.

관리 API 헬퍼

Management API helpers는 server-side 또는 정확한 same-origin에서만 사용할 수 있습니다. server에서 sk_live_* 또는 sk_test_*를 사용해 별도 client를 구성합니다. OIDC browser mode에서는 이러한 작업을 거부합니다.

const management = new XidClient({
  apiUrl: 'https://xid.dev',
  secretKey: process.env.XID_SECRET_KEY,
})

const keys = await management.listApiKeys()
if (!keys.ok) throw new Error(keys.error.message)

const created = await management.createApiKey({ name: 'CI deploy', scopes: ['read'] })
if (!created.ok) throw new Error(created.error.message)

const revoked = await management.revokeApiKey({ id: created.value.id })
if (!revoked.ok) throw new Error(revoked.error.message)

내보내진 API

내보내기	종류	목적
`XidClient`	class	최상위 브라우저 클라이언트: load, signIn, getToken, setActiveOrganization, signOut 및 관리 API 헬퍼
`XidStore`	class	프레임워크에 독립적인 반응형 store; 프레임워크 바인딩에서 useSyncExternalStore로 구독합니다
`TokenManager`	class	단기 JWT 캐시 및 예약 갱신 (고급 사용 및 테스트)
`XidApiClient`	class	/v1/me 및 token 엔드포인트용 HTTP 클라이언트
`XidNetworkError`	class	전송 실패 시 던집니다: 네트워크 오류, JSON이 아닌 응답, 구조화된 본문이 없는 5xx
`makeXidError`	function	네트워크 왕복 없이 로컬 검증 실패에 대한 구조화된 XidError를 생성합니다
`isXidErrorShape`	function	타입 가드: 알 수 없는 값이 네트워크의 XidError 형태를 따르는지 확인합니다
`decodeTokenClaims`	function	만료 스케줄링 전용으로 JWT 페이로드 클레임을 디코딩합니다; 서명은 검증하지 않습니다
`isTokenExpiring`	function	토큰이 leeway 창 내에서 만료될 때 true를 반환합니다 (기본값 10초)
`SESSION_STATUS`	as const 튜플	유효한 세션 상태 값: active, pending, expired, removed, ended, revoked
`CLIENT_STATUS`	as const 튜플	유효한 클라이언트 상태 값: loading, ready, degraded, error
`PACKAGE`	문자열 상수	패키지 이름 식별자 ‘@xid-kit/core’

타입

유형	설명
`XidUser`	인증된 사용자의 읽기 전용 보기 (비밀값 및 해시 제외)
`XidOrganization`	공개 조직 보기
`XidOrganizationMembership`	역할 및 권한이 포함된 조직 내 사용자 멤버십
`XidSession`	상태, 만료, 활성 조직을 포함한 세션 보기
`XidApiKey`	비밀값이 없는 API 키 (목록 보기)
`XidApiKeyWithSecret`	생성 시 한 번만 반환되는 API 키; key 필드 포함
`XidPage<T>`	cursor 기반 페이지네이션 응답 envelope
`CreateApiKeyInput`	createApiKey 입력
`SignInPasswordInput`	signInPassword 입력
`SignInResult`	signInPassword 결과: 다음 단계 또는 리디렉션 URL
`SessionStatus`	SESSION_STATUS 값의 union
`ClientStatus`	CLIENT_STATUS 값의 union
`XidState`	XidStore에서 구독하는 전체 SDK 상태 스냅샷
`XidStateListener`	상태 변경 리스너 callback 타입
`Unsubscribe`	XidStore.subscribe의 반환 타입
`GetTokenOptions`	getToken 옵션: skipCache, leewaySeconds, signal
`XidClientOptions`	판별 가능한 XidClient constructor options입니다. same-origin은 apiUrl, secretKey, fetcher, now를 허용하고 oidc에는 issuer, clientId, redirectUri가 필요합니다.
`TokenResponse`	token 엔드포인트 응답 원본 형태
`ClientStateResponse`	/v1/me 응답 원본 형태
`DecodedTokenClaims`	decodeTokenClaims가 반환하는 JWT 페이로드 클레임