@xid-kit/core

セッション状態、短期 JWT アクセス、Management API ヘルパー向けのブラウザークライアント。

インストールと設定

Registry 状態: UNPUBLISHED。この SDK はリポジトリのソース checkout からのみインストールし、外部 package registry は使用しないでください。

別の origin にある開発者アプリでは、issuer、clientId、完全一致する redirectUri を指定して mode: 'oidc' を設定してください。same-origin mode は、アプリケーションが自身と完全に同じ origin で Core auth endpoints をルーティングする場合にのみ使用してください。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() は組織コンテキストを切り替え、状態を再読み込みする前にトークンキャッシュをクリアします。
signOut() はブラウザーのセッション cookie を取り消します。

Management API ヘルパー

Management API helpers は server-side または完全一致する same-origin でのみ使用できます。サーバー上で 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、Management API ヘルパー
`XidStore`	class	フレームワーク非依存のリアクティブストア。フレームワークバインディングでは useSyncExternalStore でサブスクライブします
`TokenManager`	class	短期 JWT キャッシュとスケジュール更新（高度な使用およびテスト向け）
`XidApiClient`	class	/v1/me およびトークンエンドポイント向けの HTTP クライアント
`XidNetworkError`	class	トランスポート失敗（ネットワークエラー、非 JSON レスポンス、構造化ボディなしの 5xx）でスローされます
`makeXidError`	function	ネットワーク往復なしにローカル検証失敗用の構造化 XidError を構築します
`isXidErrorShape`	function	型ガード：不明な値がワイヤーからの XidError 形状に準拠しているか確認します
`decodeTokenClaims`	function	有効期限スケジューリング専用に JWT ペイロードクレームをデコードします。署名は検証しません
`isTokenExpiring`	function	トークンが許容ウィンドウ内（デフォルト 10 秒）で期限切れになる場合に true を返します
`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>`	カーソルページネーション対応のレスポンスエンベロープ
`CreateApiKeyInput`	createApiKey の入力型
`SignInPasswordInput`	signInPassword の入力型
`SignInResult`	signInPassword の結果：次のステップまたはリダイレクト URL
`SessionStatus`	SESSION_STATUS 値のユニオン
`ClientStatus`	CLIENT_STATUS 値のユニオン
`XidState`	XidStore からサブスクライブされた完全な SDK 状態スナップショット
`XidStateListener`	状態変化リスナーコールバック型
`Unsubscribe`	XidStore.subscribe の戻り値の型
`GetTokenOptions`	getToken のオプション：skipCache、leewaySeconds、signal
`XidClientOptions`	判別可能な XidClient constructor options です。same-origin は apiUrl、secretKey、fetcher、now を受け取り、oidc には issuer、clientId、redirectUri が必要です。
`TokenResponse`	トークンエンドポイントレスポンスの生の形状
`ClientStateResponse`	/v1/me レスポンスの生の形状
`DecodedTokenClaims`	decodeTokenClaims が返す JWT ペイロードクレーム