@zskj-idaas/sdk

IDaaS OIDC Client SDK — 适用于浏览器应用的 OpenID Connect 客户端，支持 Authorization Code Flow with PKCE。

特性

• 零运行时依赖 — 轻量、无外部依赖
• PKCE 支持 — 自动生成 code_verifier / code_challenge
• 双模块输出 — 同时支持 ESM 和 CommonJS
• TypeScript — 完整的类型定义
• OIDC Discovery — 自动发现 OpenID 配置端点
• Token 管理 — 自动存储、过期检测、静默刷新
• 认证 Fetch — 内置带 Bearer Token 的 fetch 封装

安装

npm install @zskj-idaas/sdk
# 或
pnpm add @zskj-idaas/sdk
# 或
yarn add @zskj-idaas/sdk

快速开始

import { IdaasClient } from '@zskj-idaas/sdk';

const client = new IdaasClient({
  issuer: 'https://your-idaas-server.com',
  clientId: 'your-client-id',
  redirectUri: 'http://localhost:3000/callback',
  scope: 'openid profile email',
});

// 初始化（自动发现 OIDC 端点）
await client.init();

// 发起登录
await client.login();

API 参考

new IdaasClient(config)

创建 SDK 客户端实例。

interface IdaasConfig {
  issuer: string;               // OIDC 提供者地址
  clientId: string;             // 客户端 ID
  clientSecret?: string;        // 客户端密钥（机密客户端）
  redirectUri: string;          // 登录回调地址
  postLogoutRedirectUri?: string; // 登出后跳转地址
  scope?: string;               // 请求的 scope（默认: 'openid profile email'）
  autoDiscovery?: boolean;      // 是否自动发现端点（默认: true）
  storagePrefix?: string;       // 存储 key 前缀（默认: 'idaas'）
}

client.init(): Promise<AuthState>

初始化客户端，执行 OIDC Discovery 并返回当前认证状态。

client.login(extraParams?): Promise<void>

发起 OIDC 授权码登录流程，跳转到授权端点。

// 附加额外参数
await client.login({ prompt: 'login', login_hint: '[email protected]' });

client.handleCallback(callbackUrl?): Promise<TokenSet>

处理授权回调，用授权码交换 Token。

// 在回调页面调用
const tokens = await client.handleCallback();

client.getUserInfo(forceRefresh?): Promise<UserInfo | null>

获取当前用户信息。

client.getAccessToken(): Promise<string | null>

获取有效的 Access Token（过期时自动刷新）。

client.getIdToken(): string | null

获取 ID Token。

client.getAuthState(): AuthState

获取当前认证状态。

interface AuthState {
  isAuthenticated: boolean;
  user: UserInfo | null;
  accessToken: string | null;
  idToken: string | null;
  expiresAt: number | null;
}

client.isAuthenticated(): boolean

检查是否已认证。

client.logout(): Promise<void>

执行 OIDC 登出流程。

client.revokeToken(): Promise<void>

撤销 Refresh Token。

client.fetch(url, init?): Promise<Response>

带认证的 fetch 封装，自动附加 Authorization 头。

const res = await client.fetch('/api/protected-resource');
const data = await res.json();

完整示例

import { IdaasClient } from '@zskj-idaas/sdk';
import type { AuthState, UserInfo } from '@zskj-idaas/sdk';

const client = new IdaasClient({
  issuer: 'https://idaas.example.com',
  clientId: 'my-app',
  redirectUri: `${window.location.origin}/callback`,
  postLogoutRedirectUri: window.location.origin,
});

// 应用启动时初始化
async function bootstrap() {
  const state: AuthState = await client.init();

  if (state.isAuthenticated) {
    const user: UserInfo | null = await client.getUserInfo();
    console.log('已登录:', user?.name);
  }
}

// 回调页面处理
async function handleCallback() {
  try {
    await client.handleCallback();
    window.location.href = '/';
  } catch (err) {
    console.error('登录失败:', err);
  }
}

// 调用受保护的 API
async function fetchData() {
  const res = await client.fetch('https://api.example.com/data');
  return res.json();
}

导出内容

// 类
export { IdaasClient } from './client';
export { TokenStorage } from './storage';

// 工具函数
export { createPKCE, generateState, generateNonce } from './crypto';

// 类型
export type { IdaasConfig, TokenSet, UserInfo, AuthState } from './types';

浏览器兼容性

需要支持 Web Crypto API 的现代浏览器：

• Chrome 63+
• Firefox 57+
• Safari 11.1+
• Edge 79+

License

MIT