@xid-kit/core

用于管理会话状态、短期 JWT 访问及 Management 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。

Management 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 及 Management 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 payload claims 解码；不验证签名
`isTokenExpiring`	function	当 token 在宽限窗口内过期时返回 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>`	游标分页响应封装
`CreateApiKeyInput`	createApiKey 的输入类型
`SignInPasswordInput`	signInPassword 的输入类型
`SignInResult`	signInPassword 的返回结果：下一步或重定向 URL
`SessionStatus`	SESSION_STATUS 取值的联合类型
`ClientStatus`	CLIENT_STATUS 取值的联合类型
`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 payload claims