@qlover/oauth-wrapper 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,341 @@
+import { StorageInterface, RequestExecutorInterface, RequestAdapterConfig } from '@qlover/fe-corekit';
+import { LoggerInterface } from '@qlover/logger';
+import { z } from 'zod';
+
+interface OAuthGatewayAuthorizeParams {
+    /**
+     * 服务端 URL
+     */
+    readonly serverUrl: string;
+    /**
+     * 服务端鉴权用的客户端 ID
+     */
+    readonly clientId: string;
+    /**
+     * 鉴权范围
+     *
+     * @default `'openid profile email'`
+     */
+    readonly scope?: string;
+    /**
+     * 鉴权成功后回调地址, 会接收的鉴权回调参数
+     *
+     * @default `'oauth/callback'`
+     */
+    readonly redirectPath?: string;
+    /**
+     * 跳转目标
+     * - _self: 当前窗口
+     * - _blank: 新窗口
+     *
+     * @default _self
+     */
+    readonly target?: '_self' | '_blank';
+}
+type OAuthGatewayTokenRequest = {
+    readonly grant_type: 'authorization_code' | 'refresh_token';
+    readonly code: string;
+    readonly redirect_uri: string;
+    readonly client_id: string;
+    readonly code_verifier: string;
+};
+type OAuthGatewayTokenResult = {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    scope?: string;
+};
+type OAuthGatewayUserinfoResult = {
+    sub: string;
+    email: string;
+    name: string;
+    roles?: string[] | undefined;
+};
+type OAuthGatewayCallbackParams = {
+    code?: string;
+    state?: string;
+    error?: string;
+    error_description?: string;
+};
+interface OAuthGatwayInterface {
+    /**
+     * 开始鉴权
+     *
+     * - 跳转 OAuth 授权页面
+     */
+    authorize(params: OAuthGatewayAuthorizeParams): Promise<void>;
+    authorize(authorizeUrl: string): Promise<void>;
+    /**
+     * 获取令牌
+     *
+     * - 请求服务端获取令牌
+     */
+    getToken(request: OAuthGatewayTokenRequest): Promise<OAuthGatewayTokenResult>;
+    /**
+     * 获取用户信息
+     *
+     * - 请求服务端获取用户信息
+     */
+    getUserInfo(accessToken: string): Promise<OAuthGatewayUserinfoResult>;
+    /**
+     * 处理 OAuth 回调
+     *
+     * 你可以在回调页面直接调用该方法即可
+     *
+     * 回调页面见 {@link authorize} {@link OAuthGatewayAuthorizeParams}
+     *
+     * - 处理 OAuth 回调参数
+     */
+    oAuthWrapperCallback(params?: OAuthGatewayCallbackParams | URLSearchParams): Promise<unknown>;
+    /**
+     * RFC 7009 — revoke the refresh token on the authorization server when provided.
+     */
+    revokeToken(options?: {
+        refreshToken?: string;
+    }): Promise<void>;
+}
+
+interface OAuthClientInterface {
+    /**
+     * 是否已配置
+     */
+    isConfigured(): boolean;
+    /**
+     * 开始鉴权
+     *
+     * @param params
+     */
+    startOAuthLogin(params?: OAuthGatewayAuthorizeParams): Promise<void>;
+    /**
+     * RFC 7009 — revoke the refresh token on the authorization server when provided.
+     */
+    revokeToken(refreshToken?: string | null): Promise<void>;
+}
+
+declare const OAuthWrapperEndpoints: {
+    readonly authorize: "/oauth/authorize";
+    readonly token: "/oauth/token";
+    readonly revoke: "/oauth/revoke";
+    readonly userinfo: "/userinfo";
+};
+declare const DEFAULT_OAUTH_AUTHORIZE_PATH: "/oauth/authorize";
+type OAuthAuthorizationConfig = {
+    serverUrl: string;
+    clientId: string;
+    /**
+     * @default 'openid profile email'
+     */
+    scope?: string;
+    /**
+     * @default 'oauth/callback'
+     */
+    redirectPath?: string;
+};
+declare const DEFAULT_PKCE_STORAGE_KEY = "oauth-wrapper-pkcesession";
+type OAuthLocaleIn = 'path' | 'query' | 'header' | 'none';
+type OAuthLocaleOptions = {
+    /** Locale value; omit when locale is not used */
+    locale?: string;
+    /**
+     * Where locale is applied.
+     * Defaults to `path` when `locale` is set, otherwise `none`.
+     */
+    localeIn?: OAuthLocaleIn;
+    /** Query param name when `localeIn` is `query`. @default `'locale'` */
+    localeQueryParam?: string;
+    /** Header name for token/userinfo requests. @default `'Accept-Language'` */
+    localeHeader?: string;
+};
+type OAuthUrlOptions = {
+    origin?: string;
+    routerPrefix?: string;
+};
+/**
+ * Static OAuth browser client configuration (not reactive / not persisted as async state).
+ */
+type OAuthClientConfig = OAuthAuthorizationConfig & OAuthUrlOptions & OAuthLocaleOptions;
+declare const defaultOAuthClientConfig: OAuthClientConfig;
+declare function resolveOAuthClientConfig(partial?: Partial<OAuthClientConfig>): OAuthClientConfig;
+
+declare const OAuthUserInfoSchema: z.ZodObject<{
+    sub: z.ZodString;
+    email: z.ZodEmail;
+    name: z.ZodString;
+    roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type OAuthUserInfo = z.infer<typeof OAuthUserInfoSchema>;
+declare const OAuthTokenResponseSchema: z.ZodObject<{
+    access_token: z.ZodString;
+    token_type: z.ZodOptional<z.ZodLiteral<"Bearer">>;
+    expires_in: z.ZodOptional<z.ZodNumber>;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OAuthTokenResponse = z.infer<typeof OAuthTokenResponseSchema>;
+declare const OAuthTokenErrorSchema: z.ZodObject<{
+    error: z.ZodString;
+    error_description: z.ZodOptional<z.ZodString>;
+    error_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OAuthCallbackParams = {
+    code?: string;
+    state?: string;
+    error?: string;
+    error_description?: string;
+};
+type OAuthUserMapper = (userinfo: OAuthUserInfo, accessToken: string, refreshToken?: string) => unknown | Promise<unknown>;
+
+/**
+ * PKCE session persisted across the authorize redirect.
+ */
+type PKCESession = {
+    readonly state: string;
+    readonly codeVerifier: string;
+    readonly locale?: string;
+};
+type OAuthClientStoreOptions = {
+    pkceStorage?: StorageInterface<string, PKCESession>;
+    /**
+     * @default {@link DEFAULT_PKCE_STORAGE_KEY}
+     */
+    pkceStorageKey?: string;
+};
+/**
+ * Session-scoped PKCE storage for the authorization code flow.
+ */
+declare class PKCESessionStore {
+    private readonly pkceStorage;
+    private readonly pkceStorageKey;
+    constructor(options?: OAuthClientStoreOptions);
+    savePkceSession(session: PKCESession): void;
+    loadPkceSession(): PKCESession | null;
+    clearPkceSession(): void;
+}
+
+type OAuthGatewayRequestConfig = RequestAdapterConfig<string>;
+type OAuthGatewayOptions = {
+    store: PKCESessionStore;
+    config: OAuthAuthorizationConfig | null;
+    mapUser: OAuthUserMapper;
+    /** When provided, token/userinfo requests go through the executor; otherwise uses fetch */
+    requester?: RequestExecutorInterface<OAuthGatewayRequestConfig>;
+} & OAuthUrlOptions & OAuthLocaleOptions & {
+    authorizePath?: string;
+};
+declare class OAuthGateway<T = unknown> implements OAuthGatwayInterface {
+    private readonly options;
+    private readonly callbackInflight;
+    constructor(options: OAuthGatewayOptions);
+    private get localeOptions();
+    private get authorizePath();
+    private get urlOptions();
+    private getServerUrl;
+    private buildRequestHeaders;
+    private requestJson;
+    /**
+     * @override
+     */
+    authorize(params: OAuthGatewayAuthorizeParams): Promise<void>;
+    /**
+     * @override
+     */
+    authorize(authorizeUrl: string): Promise<void>;
+    /**
+     * @override
+     */
+    getToken(request: OAuthGatewayTokenRequest): Promise<OAuthGatewayTokenResult>;
+    /**
+     * @override
+     */
+    getUserInfo(accessToken: string): Promise<OAuthGatewayUserinfoResult>;
+    /**
+     * @override
+     */
+    oAuthWrapperCallback(params?: OAuthGatewayCallbackParams | URLSearchParams): Promise<T>;
+    private runOAuthWrapperCallback;
+    /**
+     * @override
+     */
+    revokeToken(options?: {
+        refreshToken?: string;
+    }): Promise<void>;
+    private postRevokeToken;
+}
+
+type OAuthClientInfrastructureOptions<T extends OAuthUserInfo> = {
+    serviceName?: string | symbol;
+    gateway?: OAuthGateway<T>;
+    mapUser?: OAuthUserMapper;
+    requester?: RequestExecutorInterface<RequestAdapterConfig<string>>;
+    logger?: LoggerInterface;
+    authorizePath?: string;
+};
+type OAuthClientOptions<T extends OAuthUserInfo = OAuthUserInfo> = OAuthClientInfrastructureOptions<T> & OAuthClientStoreOptions & {
+    config?: Partial<OAuthClientConfig>;
+} & Partial<OAuthClientConfig>;
+declare class OAuthClient<T extends OAuthUserInfo = OAuthUserInfo> implements OAuthClientInterface {
+    readonly serviceName: string | symbol;
+    readonly config: OAuthClientConfig;
+    protected readonly authorizePath: string;
+    protected readonly mapUser?: OAuthUserMapper;
+    protected readonly requester?: RequestExecutorInterface<RequestAdapterConfig<string>>;
+    protected readonly logger?: LoggerInterface;
+    protected readonly pkceStore: PKCESessionStore;
+    protected readonly gateway: OAuthGateway<T>;
+    constructor(options: OAuthClientOptions<T>);
+    patchConfig(config: Partial<OAuthClientConfig>): void;
+    protected get authorizationConfig(): OAuthAuthorizationConfig | null;
+    protected get urlOptions(): OAuthUrlOptions;
+    protected get localeOptions(): OAuthLocaleOptions;
+    getGateway(): OAuthGateway<T>;
+    getLogger(): LoggerInterface | undefined;
+    /**
+     * @override
+     */
+    isConfigured(): boolean;
+    /**
+     * @override
+     */
+    startOAuthLogin(params?: OAuthGatewayAuthorizeParams): Promise<void>;
+    completeOAuthCallback(params?: Parameters<OAuthGateway<T>['oAuthWrapperCallback']>[0]): Promise<T>;
+    parseOAuthCallbackSearchParams(searchParams: URLSearchParams): Parameters<OAuthGateway<T>['oAuthWrapperCallback']>[0];
+    /**
+     * @override
+     */
+    revokeToken(refreshToken?: string | null): Promise<void>;
+    /**
+     * Fetch user profile from the OAuth userinfo endpoint and map it via {@link mapUser}.
+     */
+    fetchUserInfo(accessToken: string, refreshToken?: string): Promise<T>;
+}
+
+type ResolvedOAuthAuthorizationConfig = OAuthAuthorizationConfig & {
+    scope: string;
+    redirectPath: string;
+};
+declare function buildAuthorizeSearchParams(input: {
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    state: string;
+    codeChallenge: string;
+}): URLSearchParams;
+declare function mergeOAuthAuthorizationConfig(params: Partial<OAuthGatewayAuthorizeParams> | undefined, baseConfig: OAuthAuthorizationConfig | null | undefined): ResolvedOAuthAuthorizationConfig | null;
+declare function buildOAuthRedirectUri(redirectPath: string, options?: OAuthUrlOptions & OAuthLocaleOptions): string;
+declare function formatOAuthAuthorizeUrl(serverUrl: string, authorizePath: string, searchParams: URLSearchParams, localeOptions?: OAuthLocaleOptions): string;
+type BuildOAuthAuthorizeUrlInput = {
+    config: ResolvedOAuthAuthorizationConfig;
+    authorizePath: string;
+    state: string;
+    codeChallenge: string;
+    redirectPath?: string;
+    scope?: string;
+} & OAuthUrlOptions & OAuthLocaleOptions;
+declare function buildOAuthAuthorizeUrl(input: BuildOAuthAuthorizeUrlInput): string;
+declare function buildOAuthLocaleHeaders(options?: OAuthLocaleOptions): Record<string, string>;
+
+declare function parseOAuthTokenResponse(json: unknown): OAuthTokenResponse;
+declare function parseOAuthTokenError(json: unknown, fallback: string): string;
+declare function parseOAuthUserInfoResponse(json: unknown): OAuthUserInfo;
+
+export { type BuildOAuthAuthorizeUrlInput, DEFAULT_OAUTH_AUTHORIZE_PATH, DEFAULT_PKCE_STORAGE_KEY, type OAuthAuthorizationConfig, type OAuthCallbackParams, OAuthClient, type OAuthClientConfig, type OAuthClientInterface, type OAuthClientOptions, type OAuthClientStoreOptions, OAuthGateway, type OAuthGatewayAuthorizeParams, type OAuthGatewayCallbackParams, type OAuthGatewayOptions, type OAuthGatewayRequestConfig, type OAuthGatewayTokenRequest, type OAuthGatewayTokenResult, type OAuthGatewayUserinfoResult, type OAuthGatwayInterface, type OAuthLocaleIn, type OAuthLocaleOptions, OAuthTokenErrorSchema, type OAuthTokenResponse, OAuthTokenResponseSchema, type OAuthUrlOptions, type OAuthUserInfo, OAuthUserInfoSchema, type OAuthUserMapper, OAuthWrapperEndpoints, type PKCESession, PKCESessionStore, type ResolvedOAuthAuthorizationConfig, buildAuthorizeSearchParams, buildOAuthAuthorizeUrl, buildOAuthLocaleHeaders, buildOAuthRedirectUri, defaultOAuthClientConfig, formatOAuthAuthorizeUrl, mergeOAuthAuthorizationConfig, parseOAuthTokenError, parseOAuthTokenResponse, parseOAuthUserInfoResponse, resolveOAuthClientConfig };