@xid-kit/core

Browser-Client für Sitzungszustand, kurzlebige JWT-Zugriffe und Management-API-Helfer.

Installieren und konfigurieren

Registry-Status: UNPUBLISHED. Installieren Sie dieses SDK nur aus einem Checkout des Repository-Quellcodes; verwenden Sie keine externe Paket-Registry.

Konfigurieren Sie für eine Entwickler-App auf einem anderen Ursprung mode: 'oidc' mit issuer, clientId und einer exakten redirectUri. Verwenden Sie den same-origin-Modus nur, wenn die Anwendung die Core-Authentifizierungsendpunkte auf ihrem exakten Ursprung routet. XID besitzt keine publishable-key-Anmeldedaten.

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)

Sitzungslebenszyklus

load() liest /v1/me und befüllt Benutzer, Sitzung und aktive Organisation.
signInPassword() richtet eine Cookie-Sitzung über den Hosted Auth Passwort-Ablauf ein.
getToken() gibt ein kurzlebiges JWT für API-Aufrufe zurück. Prüfen Sie es netzwerklos in Ihrem Backend mit JWKS.
setActiveOrganization() wechselt den Organisationskontext und leert den Token-Cache, bevor der Zustand neu geladen wird.
signOut() widerruft den Browser-Sitzungs-Cookie.

Management-API-Helfer

Management-API-Hilfsfunktionen sind nur serverseitig oder bei exakt gleichem Ursprung verfügbar. Erstellen Sie auf dem Server einen separaten Client mit sk_live_* oder sk_test_*; der OIDC-Browsermodus lehnt diese Vorgänge ab.

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)

Exportierte API

Exportieren	Art	Zweck
`XidClient`	class	Oberster Browser-Client: load, signIn, getToken, setActiveOrganization, signOut und Management-API-Helfer
`XidStore`	class	Framework-agnostischer reaktiver Speicher; mit useSyncExternalStore in Framework-Bindungen abonnieren
`TokenManager`	class	Kurzlebiger JWT-Cache und geplante Aktualisierung (erweiterte Nutzung und Tests)
`XidApiClient`	class	HTTP-Client für /v1/me und Token-Endpunkte
`XidNetworkError`	class	Wird bei Transportfehlern geworfen: Netzwerkfehler, Nicht-JSON-Antwort, 5xx ohne strukturierten Body
`makeXidError`	function	Einen strukturierten XidError für lokale Validierungsfehler ohne Netzwerkumlauf erstellen
`isXidErrorShape`	function	Typwächter: prüft, ob ein unbekannter Wert der XidError-Form aus der Übertragung entspricht
`decodeTokenClaims`	function	JWT-Payload-Claims nur für die Ablaufplanung dekodieren; verifiziert die Signatur nicht
`isTokenExpiring`	function	Gibt true zurück, wenn das Token innerhalb des Toleranzfensters abläuft (Standard 10 s)
`SESSION_STATUS`	as const Tupel	Gültige Sitzungsstatuswerte: active, pending, expired, removed, ended, revoked
`CLIENT_STATUS`	as const Tupel	Gültige Client-Statuswerte: loading, ready, degraded, error
`PACKAGE`	Zeichenkettenkonstante	Paketkennzeichner ‘@xid-kit/core’

Typen

Typ	Beschreibung
`XidUser`	Schreibgeschützte Ansicht des authentifizierten Benutzers (keine Geheimnisse oder Hashes)
`XidOrganization`	Öffentliche Organisationsansicht
`XidOrganizationMembership`	Benutzermitgliedschaft in einer Organisation mit Rolle und Berechtigungen
`XidSession`	Sitzungsansicht mit Status, Ablauf und aktiver Organisation
`XidApiKey`	API-Schlüssel ohne Geheimnis (Listenansicht)
`XidApiKeyWithSecret`	API-Schlüssel wird einmalig bei der Erstellung zurückgegeben; enthält das Schlüsselfeld
`XidPage<T>`	Cursor-paginierter Antwort-Envelope
`CreateApiKeyInput`	Eingabe für createApiKey
`SignInPasswordInput`	Eingabe für signInPassword
`SignInResult`	Ergebnis von signInPassword: nächster Schritt oder Weiterleitungs-URL
`SessionStatus`	Vereinigung der SESSION_STATUS-Werte
`ClientStatus`	Vereinigung der CLIENT_STATUS-Werte
`XidState`	Vollständiger SDK-Zustandsschnappschuss, abonniert von XidStore
`XidStateListener`	Callback-Typ für Zustandsänderungs-Listener
`Unsubscribe`	Rückgabetyp von XidStore.subscribe
`GetTokenOptions`	Optionen für getToken: skipCache, leewaySeconds, signal
`XidClientOptions`	Diskriminierte XidClient-Konstruktoroptionen: same-origin akzeptiert apiUrl, secretKey, fetcher und now; oidc erfordert issuer, clientId und redirectUri.
`TokenResponse`	Rohform der Token-Endpunkt-Antwort
`ClientStateResponse`	Rohform der /v1/me-Antwort
`DecodedTokenClaims`	JWT-Payload-Claims, zurückgegeben von decodeTokenClaims

Zugehörige Dokumentation

Framework-Bindungen: @xid-kit/react. Server-Verifizierung: @xid-kit/backend.