@xid-kit/core

Client navigateur pour l'état de session, l'accès JWT de courte durée et les assistants de l'API de gestion.

Installer et configurer

Statut du registre : UNPUBLISHED. Installez ce SDK uniquement depuis un checkout du code source du dépôt ; n’utilisez pas de registre de paquets externe.

Pour une application de développeur sur une autre origine, configurez mode: 'oidc' avec issuer, clientId et un redirectUri exact. Utilisez le mode same-origin uniquement lorsque l’application route les points de terminaison d’authentification Core sur son origine exacte. XID ne possède aucun identifiant publishable-key.

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)

Cycle de vie de session

load() lit /v1/me et hydrate l’utilisateur, la session et l’organisation active.
signInPassword() établit une session cookie via le flux de mot de passe Hosted Auth.
getToken() retourne un JWT de courte durée pour les appels API. Vérifiez sans réseau sur votre serveur avec JWKS.
setActiveOrganization() change le contexte d’organisation et vide le cache de jeton avant de recharger l’état.
signOut() révoque le cookie de session du navigateur.

Assistants de l’API de gestion

Les helpers Management API sont réservés au serveur ou à une origine strictement identique. Construisez un client distinct avec sk_live_* ou sk_test_* sur le serveur; le mode navigateur OIDC rejette ces opérations.

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 exportée

Exporter	Type	Objectif
`XidClient`	class	Client navigateur de niveau supérieur : load, signIn, getToken, setActiveOrganization, signOut et assistants de l’API de gestion
`XidStore`	class	Store réactif indépendant du framework ; s’abonner avec useSyncExternalStore dans les liaisons framework
`TokenManager`	class	Cache JWT de courte durée et rafraîchissement planifié (usage avancé et tests)
`XidApiClient`	class	Client HTTP pour les points de terminaison /v1/me et token
`XidNetworkError`	class	Levée lors d’échecs de transport : erreur réseau, réponse non-JSON, 5xx sans corps structuré
`makeXidError`	function	Construit un XidError structuré pour les échecs de validation locaux sans aller-retour réseau
`isXidErrorShape`	function	Type guard : vérifie si une valeur inconnue est conforme à la structure XidError depuis le réseau
`decodeTokenClaims`	function	Décode les revendications du payload JWT uniquement pour la planification d’expiration ; ne vérifie pas la signature
`isTokenExpiring`	function	Retourne true lorsque le token expire dans la fenêtre de tolérance (défaut 10 s)
`SESSION_STATUS`	tuple as const	Valeurs valides du statut de session : active, pending, expired, removed, ended, revoked
`CLIENT_STATUS`	tuple as const	Valeurs valides du statut client : loading, ready, degraded, error
`PACKAGE`	constante string	Identifiant du nom de package ‘@xid-kit/core’

Types

Type	Description
`XidUser`	Vue en lecture seule de l’utilisateur authentifié (sans secrets ni hachages)
`XidOrganization`	Vue publique de l’organisation
`XidOrganizationMembership`	Appartenance d’un utilisateur à une organisation avec rôle et permissions
`XidSession`	Vue de session incluant le statut, l’expiration et l’organisation active
`XidApiKey`	Clé API sans secret (vue liste)
`XidApiKeyWithSecret`	Clé API retournée une seule fois à la création ; contient le champ key
`XidPage<T>`	Enveloppe de réponse paginée par curseur
`CreateApiKeyInput`	Entrée pour createApiKey
`SignInPasswordInput`	Entrée pour signInPassword
`SignInResult`	Résultat de signInPassword : étape suivante ou URL de redirection
`SessionStatus`	Union des valeurs de SESSION_STATUS
`ClientStatus`	Union des valeurs de CLIENT_STATUS
`XidState`	Instantané complet de l’état SDK souscrit depuis XidStore
`XidStateListener`	Type de callback de listener de changement d’état
`Unsubscribe`	Type de retour de XidStore.subscribe
`GetTokenOptions`	Options pour getToken : skipCache, leewaySeconds, signal
`XidClientOptions`	Options discriminées du constructeur XidClient: same-origin accepte apiUrl, secretKey, fetcher et now; oidc exige issuer, clientId et redirectUri.
`TokenResponse`	Structure de réponse brute du point de terminaison token
`ClientStateResponse`	Structure de réponse brute de /v1/me
`DecodedTokenClaims`	Revendications du payload JWT retournées par decodeTokenClaims

Documentation connexe

Liaisons framework : @xid-kit/react. Vérification serveur : @xid-kit/backend.