@h-ai/kit 0.1.0-alpha9 → 1.0.0-beta.1

package/dist/kit-a2a-types-4dapztu2.d.ts

@@ -0,0 +1,136 @@
+import { RequestEvent } from '@sveltejs/kit';
+import { f as HandleA2AOperations, h as HandleConfig } from './kit-types-BkNdyKj8.js';
+
+/**
+ * @h-ai/kit — A2A API Key 认证器
+ *
+ * 从请求头或 query 参数中提取 API Key，调用 IAM apiKey.verifyApiKey 验证。
+ * @module kit-a2a-auth
+ */
+
+/**
+ * A2A API Key 认证器配置
+ * @example
+ * ```ts
+ * import type { A2AApiKeyAuthConfig } from '@h-ai/kit'
+ *
+ * const value: A2AApiKeyAuthConfig = { in: 'header', name: 'X-Agent-Key' }
+ * void value
+ * ```
+ */
+interface A2AApiKeyAuthConfig {
+    /** API Key 的传递位置 */
+    in: 'header' | 'query';
+    /** 参数名 */
+    name: string;
+}
+/**
+ * 创建 A2A API Key 认证函数
+ *
+ * 根据配置从请求头或 query 参数中提取 API Key，
+ * 通过 `iam.apiKey.verifyApiKey()` 验证后返回调用方上下文。
+ *
+ * - 无 API Key → 返回 `null`（由调用方拒绝请求）
+ * - 验证失败 → 返回 `null`（拒绝）
+ * - 验证成功 → 返回 `{ agentId, apiKeyId, scopes }`
+ *
+ * @param config - API Key 提取配置
+ * @returns authenticate 函数，可直接赋给 HandleA2AConfig.authenticate
+ * @example 模块内部上下文
+ * ```ts
+ * const authenticate = createA2AApiKeyAuthenticator({ in: 'header', name: 'X-Agent-Key' })
+ * // 应用先初始化 IAM；拒绝返回 null，交给路由转为 401。
+ * void authenticate
+ * ```
+ */
+declare function createA2AApiKeyAuthenticator(config: A2AApiKeyAuthConfig): (event: RequestEvent) => Promise<Record<string, unknown> | null>;
+
+/**
+ * @h-ai/kit — A2A Handle 拦截器
+ *
+ * 在 SvelteKit Handle Hook 中拦截 A2A 端点（Agent Card 发现 + JSON-RPC 处理），
+ * 自动处理请求并返回 Response，不匹配时返回 null 由 Handle 继续后续流程。
+ * @module kit-a2a-handle
+ */
+
+/**
+ * A2A 解析后的内部配置
+ * @example
+ * ```ts
+ * import type { ResolvedA2AConfig } from '@h-ai/kit'
+ *
+ * function paths(config: ResolvedA2AConfig) { return [config.cardPath, config.rpcPath] }
+ * ```
+ */
+interface ResolvedA2AConfig {
+    operations: HandleA2AOperations;
+    cardPath: string;
+    rpcPath: string;
+    authenticate?: (event: RequestEvent) => Promise<Record<string, unknown> | null | undefined>;
+}
+/**
+ * 解析 A2A 配置（简单模式 / 配置模式）
+ *
+ * - 简单模式：直接传入 `ai.a2a` 操作对象，使用默认路径
+ * - 配置模式：传入 `{ operations, rpcPath?, cardPath?, authenticate? }`
+ *
+ * @param input - HandleConfig.a2a 配置
+ * @returns 解析后的配置，或 `null` 表示未配置
+ * @example 模块内部上下文
+ * ```ts
+ * function resolve(operations: HandleA2AOperations) {
+ *   return resolveA2AConfig({ operations, rpcPath: '/a2a', authenticate: async () => null })
+ * }
+ * ```
+ */
+declare function resolveA2AConfig(input: HandleConfig['a2a']): ResolvedA2AConfig | null;
+/**
+ * 处理 A2A 端点请求
+ *
+ * 匹配 Agent Card GET 和 JSON-RPC POST 端点，返回 Response。
+ * 不匹配时返回 `null`，由 Handle 继续后续流程。
+ *
+ * @param event - SvelteKit RequestEvent
+ * @param requestId - 当前请求 ID（用于响应头）
+ * @param config - 解析后的 A2A 配置
+ * @returns 匹配时返回 Response，不匹配返回 null
+ * @example 模块内部上下文
+ * ```ts
+ * async function handle(event: RequestEvent, config: ResolvedA2AConfig) {
+ *   return handleA2ARequest(event, 'req_1', config) // null 表示路径未匹配，交给后续 handle。
+ * }
+ * ```
+ */
+declare function handleA2ARequest(event: RequestEvent, requestId: string, config: ResolvedA2AConfig): Promise<Response | null>;
+
+/**
+ * @h-ai/kit — A2A 类型定义
+ *
+ * Kit A2A 路由处理器相关类型
+ * @module kit-a2a-types
+ */
+
+/**
+ * A2A 路由处理器配置
+ * @example
+ * ```ts
+ * import type { KitA2AHandlerConfig } from '@h-ai/kit'
+ *
+ * const value: KitA2AHandlerConfig = { authenticate: async () => null }
+ * void value
+ * ```
+ */
+interface KitA2AHandlerConfig {
+    /**
+     * 可选的认证回调
+     *
+     * 验证入站 A2A 请求的身份。返回 null/undefined 表示认证失败（401）。
+     * 未配置此项才允许匿名请求；回调可抛出 SvelteKit HTTP 错误。
+     *
+     * - `'apiKey'`：自动使用 IAM API Key 认证
+     * - 函数：自定义认证回调
+     */
+    authenticate?: 'apiKey' | ((event: RequestEvent) => Promise<Record<string, unknown> | null | undefined>);
+}
+
+export { type A2AApiKeyAuthConfig as A, type KitA2AHandlerConfig as K, type ResolvedA2AConfig as R, createA2AApiKeyAuthenticator as c, handleA2ARequest as h, resolveA2AConfig as r };

package/dist/kit-client-auth-BnhrkzZF.d.ts

@@ -0,0 +1,422 @@
+import { IamCreateCaptchaInputSchema, IamPublicConfig, IamLoginInput, IamRegisterInput } from '@h-ai/api-contract';
+import { HaiResult } from '@h-ai/core';
+import { CryptoFunctions } from '@h-ai/crypto';
+import { PasswordCredentials, AuthRequestContext, AuthResult, OtpCredentials, LdapCredentials, ApiKeyCredentials, RegisterOptions } from '@h-ai/iam';
+import { k as KitPublicConfig } from './kit-types-BkNdyKj8.js';
+import { z } from 'zod';
+
+/**
+ * @h-ai/kit — Bearer 认证工具
+ *
+ * 提供服务端认证 Cookie 管理（login / logout）与浏览器端 Token 存储工具。
+ * @module kit-auth
+ */
+
+/**
+ * 服务端认证写入/删除 Cookie 依赖；由当前请求提供并执行安全属性。
+ * @example 模块内部上下文
+ * ```ts
+ * function signIn(cookies: CookieWriter, credentials: PasswordCredentials) {
+ *   return login(cookies, credentials) // 业务调用者检查 success 后消费身份。
+ * }
+ * ```
+ */
+interface CookieWriter {
+    set: (name: string, value: string, options: {
+        path: string;
+        httpOnly: boolean;
+        sameSite: 'lax' | 'strict' | 'none';
+        secure: boolean;
+        maxAge?: number;
+    }) => void;
+    delete: (name: string, options: {
+        path: string;
+    }) => void;
+}
+/**
+ * 浏览器 Token 存储器；使用页面内存或平台安全存储，禁止写入 Web Storage。
+ * @example 模块内部上下文
+ * ```ts
+ * const store: BrowserTokenStore = getDefaultBrowserTokenStore()
+ * store.clear() // 当前页面内存状态；不持有服务端会话真值。
+ * ```
+ */
+interface BrowserTokenStore {
+    get: () => string | null;
+    set: (token: string) => void;
+    clear: () => void;
+}
+/**
+ * 服务端登录（密码）：内部调用 iam.auth.login，成功时自动写入 Token Cookie。
+ *
+ * @param cookies - SvelteKit cookies 对象
+ * @param credentials - 密码凭证（identifier + password）
+ * @param context - 宿主提供的可信登录元数据，不从凭据输入复制 IP。
+ * @returns 认证结果（成功时 Cookie 已自动写入）
+ * @example 模块内部上下文
+ * ```ts
+ * async function signIn(cookies: CookieWriter, credentials: PasswordCredentials) {
+ *   const result = await login(cookies, credentials)
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
+ * ```
+ */
+declare function login(cookies: CookieWriter, credentials: PasswordCredentials, context?: AuthRequestContext): Promise<HaiResult<AuthResult>>;
+/**
+ * 服务端登录（OTP 验证码）：内部调用 iam.auth.loginWithOtp，成功时自动写入 Token Cookie。
+ *
+ * @param cookies - SvelteKit cookies 对象
+ * @param credentials - OTP 凭证（identifier + code）
+ * @param context - 宿主提供的可信登录元数据。
+ * @returns 认证结果（成功时 Cookie 已自动写入）
+ * @example 模块内部上下文
+ * ```ts
+ * async function signIn(cookies: CookieWriter, credentials: OtpCredentials) {
+ *   const result = await loginWithOtp(cookies, credentials)
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
+ * ```
+ */
+declare function loginWithOtp(cookies: CookieWriter, credentials: OtpCredentials, context?: AuthRequestContext): Promise<HaiResult<AuthResult>>;
+/**
+ * 服务端登录（LDAP）：内部调用 iam.auth.loginWithLdap，成功时自动写入 Token Cookie。
+ *
+ * @param cookies - SvelteKit cookies 对象
+ * @param credentials - LDAP 凭证（username + password）
+ * @param context - 宿主提供的可信登录元数据。
+ * @returns 认证结果（成功时 Cookie 已自动写入）
+ * @example 模块内部上下文
+ * ```ts
+ * async function signIn(cookies: CookieWriter, credentials: LdapCredentials) {
+ *   const result = await loginWithLdap(cookies, credentials)
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
+ * ```
+ */
+declare function loginWithLdap(cookies: CookieWriter, credentials: LdapCredentials, context?: AuthRequestContext): Promise<HaiResult<AuthResult>>;
+/**
+ * 服务端登录（API Key）：内部调用 iam.auth.loginWithApiKey，成功时自动写入 Token Cookie。
+ *
+ * @param cookies - SvelteKit cookies 对象
+ * @param credentials - API Key 凭证（key）
+ * @param context - 宿主提供的可信登录元数据。
+ * @returns 认证结果（成功时 Cookie 已自动写入）
+ * @example 模块内部上下文
+ * ```ts
+ * async function signIn(cookies: CookieWriter, credentials: ApiKeyCredentials) {
+ *   const result = await loginWithApiKey(cookies, credentials)
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
+ * ```
+ */
+declare function loginWithApiKey(cookies: CookieWriter, credentials: ApiKeyCredentials, context?: AuthRequestContext): Promise<HaiResult<AuthResult>>;
+/**
+ * 服务端注册并登录：内部调用 iam.auth.registerAndLogin，成功时自动写入 Token Cookie。
+ *
+ * @param cookies - SvelteKit cookies 对象
+ * @param options - 注册选项（username、password、email 等）
+ * @returns 认证结果（成功时 Cookie 已自动写入）
+ * @example 模块内部上下文
+ * ```ts
+ * async function signIn(cookies: CookieWriter, credentials: RegisterOptions) {
+ *   const result = await registerAndLogin(cookies, credentials)
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
+ * ```
+ */
+declare function registerAndLogin(cookies: CookieWriter, options: RegisterOptions, context?: AuthRequestContext): Promise<HaiResult<AuthResult>>;
+/**
+ * 服务端登出：委托 iam.auth.logout 原子撤销凭据，并始终清除当前请求的 Token Cookie。
+ * Cookie 清理只代表本地退出；服务端撤销失败仍返回失败，不能由调用端改成成功响应。
+ *
+ * @param cookies - SvelteKit cookies 对象
+ * @param accessToken - 访问令牌（为 null/undefined 时仅清除 Cookie）
+ * @returns 服务端撤销结果；无令牌时仅清理 Cookie 并成功，有令牌但未配置认证操作时失败。
+ * @remarks 底层控制流异常仍以 Promise 拒绝传播；Cookie 清理不吞掉业务失败。
+ * @example 模块内部上下文
+ * ```ts
+ * async function signOut(cookies: CookieWriter, accessToken: string) {
+ *   const result = await logout(cookies, accessToken)
+ *   if (!result.success) return result.error.code
+ *   return result.data
+ * }
+ * ```
+ */
+declare function logout(cookies: CookieWriter, accessToken?: string | null): Promise<HaiResult<void>>;
+/**
+ * 写入默认浏览器端 Access Token（仅页面内存，不持久化到 localStorage）。
+ * @param token - 当前页面内存中使用的 access token，不写入 Web Storage。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * kit.auth.setBrowserToken('example-only-token')
+ * // 页面注销时同步清除浏览器内存令牌。
+ * kit.auth.clearBrowserToken()
+ * ```
+ */
+declare function setBrowserToken(token: string): void;
+/**
+ * 清除默认浏览器端 Access Token（仅页面内存）。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * kit.auth.clearBrowserToken()
+ * ```
+ */
+declare function clearBrowserToken(): void;
+
+/**
+ * @h-ai/kit — 统一客户端
+ *
+ * 将 CSRF Token 附加与可选传输加密封装为统一 `apiFetch`。
+ * 应用层只需调用一次 `createKitClient()`，后续 API 调用即可复用同一套安全能力。
+ * @module kit-client
+ */
+
+/**
+ * 传输加密客户端配置
+ * @example
+ * ```ts
+ * import type { ClientTransportConfig } from '@h-ai/kit'
+ * import { crypto } from '@h-ai/crypto'
+ *
+ * function configAfterInit(): ClientTransportConfig { return { crypto, excludePaths: ['/api/health'] } }
+ * ```
+ */
+interface ClientTransportConfig {
+    /** 宿主构建挂载目录，默认空字符串；SvelteKit 使用 $app/paths.base。 */
+    basePath?: string;
+    /** 可选本地明文上限；缺省跟随服务端握手。 */
+    maxPlaintextBytes?: number;
+    /** @h-ai/crypto 服务实例 */
+    crypto: CryptoFunctions;
+    /** 密钥交换端点 URL（默认 `'/api/_hai/key-exchange'`） */
+    keyExchangeUrl?: string;
+    /** 排除路径（命中后强制走明文），需与服务端 transport.excludePaths 保持一致 */
+    excludePaths?: readonly string[];
+}
+/**
+ * Kit 客户端配置
+ * @example
+ * ```ts
+ * import type { KitClientConfig } from '@h-ai/kit'
+ *
+ * const value: KitClientConfig = { auth: true }
+ * void value
+ * ```
+ */
+interface KitClientConfig {
+    /** 标准鉴别明确失效时原地登录原用户；成功才对被拒绝的请求重试一次。 */
+    recoverSession?: () => Promise<boolean>;
+    /** 会话终端分组，默认web；服务端按终端与全局配额共同限制。 */
+    terminalType?: 'web' | 'app' | 'desktop' | 'api';
+    /**
+     * 传输加密配置。
+     * - 不提供 / undefined：不启用传输加密，仅 CSRF
+     * - 提供对象：启用传输加密
+     */
+    transport?: ClientTransportConfig;
+    /** CSRF Cookie 名称（默认 `'hai_csrf'`） */
+    csrfCookieName?: string;
+    /** CSRF Header 名称（默认 `'X-CSRF-Token'`） */
+    csrfHeaderName?: string;
+    /**
+     * 认证配置：自动从浏览器存储读取 Access Token 并注入请求头。
+     * - `true`：使用默认页面内存存储（由 `kit.auth.setBrowserToken()` 写入，不读写 localStorage）
+     * - `BrowserTokenStore`：使用自定义存储
+     * - 不提供 / `false`：不自动注入
+     */
+    auth?: boolean | BrowserTokenStore;
+}
+/**
+ * Kit 客户端实例
+ * @example
+ * ```ts
+ * import type { KitClient } from '@h-ai/kit'
+ *
+ * async function read(client: KitClient) {
+ *   const response = await client.apiFetch('/api/health')
+ *   if (!response.ok) throw new Error('Request failed')
+ *   return response.json()
+ * }
+ * ```
+ */
+interface KitClient {
+    /** 统一 API fetch（写请求自动附加 CSRF，启用 transport 时自动加解密） */
+    apiFetch: (input: RequestInfo | URL, init?: RequestInit, options?: {
+        recoverSession?: boolean;
+        reauthorize?: () => Promise<string | null | undefined>;
+    }) => Promise<Response>;
+    /** 传输加密是否就绪（未启用传输加密时始终为 true） */
+    readonly ready: boolean;
+    /**
+     * 手动触发密钥交换（transport 启用时）。
+     *
+     * 注意：本方法是 Client 形态的合规例外，密钥协商失败时 `throw`（与 `@h-ai/api-client` 一致），
+     * 调用方需自行 `try/catch`，不返回 `HaiResult`。
+     */
+    init: () => Promise<void>;
+    /** 销毁密钥状态 */
+    destroy: () => void;
+}
+/**
+ * 在浏览器启动时安装同源 transport fetch 包装。
+ *
+ * 该包装作用于同源 `/api/*` 与 SvelteKit `__data.json` 请求，页面文档、
+ * 静态资源以及 multipart/form-data 等上传请求保持原样。应用只需安装一次，
+ * 后续 `fetch` / SvelteKit 内部 data fetch / `kit.client.create()` 明文发送路径
+ * 都会共用这层传输加密能力。
+ * @param transportConfig - 已初始化 crypto、同源密钥交换路径及排除路径；省略时不安装包装。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * // 不传配置时不安装全局包装；启用时应传已初始化 crypto 与同源端点。
+ * kit.client.installBrowserTransportFetch()
+ * ```
+ */
+declare function installBrowserTransportFetch(transportConfig?: ClientTransportConfig): void;
+/**
+ * 用 `config/_kit.yml` 解析后的 {@link KitPublicConfig} 公共投影 一次性安装浏览器端传输加密。
+ *
+ * 行为：
+ * - `config.transport === false` 时直接返回（不启用传输加密）；
+ * - 否则启动 {@link installBrowserTransportFetch}，并预热 {@link CryptoFunctions} 模块。
+ *
+ * 应用层（SvelteKit `+layout.svelte` 或浏览器入口）只需调用此函数一次，
+ * 之后宿主 basePath 下的同源 `/api/*` 与 `__data.json` 请求都会自动走传输加密。
+ *
+ * @param config 已解析的 kit 公共传输配置
+ * @param deps  外部依赖
+ * @param deps.crypto `@h-ai/crypto` 模块实例
+ * @param deps.basePath 宿主构建挂载目录，默认空字符串；SvelteKit 使用 $app/paths.base。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * import { crypto } from '@h-ai/crypto'
+ *
+ * function installAfterCryptoInit() {
+ *   kit.client.installBrowserTransport({ transport: { keyExchangePath: '/api/_hai/key-exchange', excludePaths: ['/api/health'] } }, { crypto })
+ * }
+ * ```
+ */
+declare function installBrowserTransport(config: KitPublicConfig, deps: {
+    crypto: CryptoFunctions;
+    basePath?: string;
+}): void;
+/**
+ * 创建 Kit 客户端
+ *
+ * 返回统一的 `apiFetch`，内部自动完成：
+ * 1. CSRF Token 附加（写方法自动读取 Cookie + 设置 Header）
+ * 2. 密钥交换（首次写请求时 lazy init，transport 启用时）
+ * 3. 请求体加密（transport 启用时）
+ * 4. 响应体解密（transport 启用时）
+ *
+ * @param config - 客户端配置
+ * @returns KitClient 实例
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const client = kit.client.create({ auth: true })
+ * try {
+ *   await client.init() // Client API 使用 Promise 拒绝；不是 HaiResult。
+ *   const response = await client.apiFetch('/api/health')
+ *   if (!response.ok) throw new Error('Request failed')
+ * } finally {
+ *   client.destroy()
+ * }
+ * ```
+ */
+declare function createKitClient(config?: KitClientConfig): KitClient;
+
+/** 与标准 Kit 认证端点配套的表单动作；复用已有 CSRF/transport fetch。 */
+
+/**
+ * 创建标准 Cookie 认证表单动作；复用可选 apiFetch 以保留 CSRF 和传输配置。
+ * @param options - 可复用的 apiFetch 和标准认证端点 basePath。
+ * @param options.apiFetch - 已装配 CSRF/transport 的 fetch；省略时使用默认 Kit 客户端。
+ * @param options.basePath - 同源认证端点前缀，默认 /api/auth。
+ * @returns 标准表单动作；业务返回 HaiResult，网络/格式错误会拒绝 Promise。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const actions = kit.client.createAuthActions({ basePath: '/api/auth' })
+ * void actions
+ * ```
+ */
+declare function createKitAuthActions(options?: {
+    apiFetch?: KitClient['apiFetch'];
+    basePath?: string;
+}): {
+    bindPageExit(options?: {
+        enabled?: boolean;
+    }): () => void;
+    createCaptcha(input: z.input<typeof IamCreateCaptchaInputSchema>): Promise<HaiResult<{
+        id: string;
+        challenge: {
+            parameters: {
+                algorithm: "PBKDF2/SHA-256";
+                nonce: string;
+                salt: string;
+                cost: number;
+                keyLength: number;
+                keyPrefix: string;
+                keySignature?: string | undefined;
+                data?: Record<string, string | number | boolean | null> | undefined;
+            };
+            signature?: string | undefined;
+        };
+    }>>;
+    publicConfig(): Promise<HaiResult<IamPublicConfig | null>>;
+    login(input: IamLoginInput & {
+        method?: "password" | "ldap" | "email" | "sms";
+        code?: string;
+    }): Promise<HaiResult<unknown>>;
+    register: (input: IamRegisterInput) => Promise<HaiResult<unknown>>;
+    sendOtp: (identifier: string, options?: {
+        captcha?: string;
+    }) => Promise<HaiResult<unknown>>;
+    requestPasswordReset: (identifier: string, options?: {
+        captcha?: string;
+    }) => Promise<HaiResult<unknown>>;
+    confirmPasswordReset: (token: string, newPassword: string) => Promise<HaiResult<unknown>>;
+    renewPassword: (input: {
+        identifier: string;
+        password: string;
+        newPassword: string;
+        captcha?: string;
+    }) => Promise<HaiResult<unknown>>;
+    reauthenticate(password: string, operation: string): Promise<{
+        success: false;
+        error: {
+            code: string | number;
+            message: string;
+            traceId?: string | undefined;
+            httpStatus?: number | undefined;
+            system?: string | undefined;
+            module?: string | undefined;
+            cause?: unknown;
+            suggestion?: string | undefined;
+            ext?: Record<string, unknown> | undefined;
+        };
+    } | {
+        success: true;
+        data: {
+            ticket: string;
+            expiresAt: number;
+        };
+    }>;
+};
+
+export { type ClientTransportConfig as C, type KitClient as K, createKitAuthActions as a, installBrowserTransportFetch as b, createKitClient as c, clearBrowserToken as d, type KitClientConfig as e, loginWithOtp as f, loginWithLdap as g, loginWithApiKey as h, installBrowserTransport as i, logout as j, login as l, registerAndLogin as r, setBrowserToken as s };