@msdongcha/auth-kit 0.0.0-stage → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.1
+
+- 初始发布：无 UI Auth-kit 核心、配置校验、跳转决策、显式 SessionAdapter 与 refresh single-flight。

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# @msdongcha/auth-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## 初始化
+
+```bash
+pnpm add @msdongcha/auth-kit
+```
+
+`TokenStore` 由业务应用实现。SDK 只通过它读取、轮换和清理 token；不会读取 React、Router、页面状态或浏览器存储。
+
+```ts
+import { create, type TokenStore } from '@msdongcha/auth-kit'
+
+const tokenStore: TokenStore = {
+  get: () => {
+    const accessToken = sessionStorage.getItem('access_token')
+    const refreshToken = sessionStorage.getItem('refresh_token')
+    return accessToken ? { accessToken, refreshToken: refreshToken ?? undefined } : null
+  },
+  set: ({ accessToken, refreshToken }) => {
+    sessionStorage.setItem('access_token', accessToken)
+    if (refreshToken) sessionStorage.setItem('refresh_token', refreshToken)
+    else sessionStorage.removeItem('refresh_token')
+  },
+  clear: () => {
+    sessionStorage.removeItem('access_token')
+    sessionStorage.removeItem('refresh_token')
+  },
+}
+
+const auth = create({
+  authDomain: 'https://iam.example.com',
+  app: 'business-web',
+  tokenStore,
+})
+```
+
+`authDomain` 必须是 HTTPS；仅当 `runtime` 为 `development` 或 `test` 时允许 localhost HTTP。`app` 是认证入口使用的应用标识。`fetchImpl` 用于注入 fetch 实现或测试替身。
+
+不要配置 `allowedCallbackOrigins`。回跳地址的白名单只由 IAM 服务端配置和校验，SDK 不在客户端复制这项授权决策。
+
+## `create(config)` 返回的客户端
+
+### `validate()`
+
+校验认证域名及当前 runtime 是否允许该 URL。
+
+```ts
+const result = auth.validate()
+if (!result.ok) console.error(result.error)
+```
+
+### `buildAuthorizeUrl(options?)`
+
+创建 IAM 登录地址，只输出 `app`、`return_to` 和可选的 `state` 参数。
+
+```ts
+const result = auth.buildAuthorizeUrl({
+  returnTo: 'https://business.example.com/orders',
+  state: 'csrf-state',
+})
+
+if (result.ok) window.location.assign(result.value)
+```
+
+显式传入 `returnTo` 时优先使用。浏览器中省略它时，SDK 使用当前页面的绝对 URL，并删除查询或 hash 中的 `access_token`、`refresh_token`、`code`、`id_token` 和 `token` 参数。非浏览器环境必须显式传入有效的 `returnTo`，否则返回 `RETURN_TO_UNAVAILABLE`。SDK 只校验 URL 格式与 runtime；最终回跳是否允许由 IAM 服务端决定。
+
+`appCode`、`clientId` 和 `callbackUrl` 仍是迁移期的兼容别名，分别归一化为 `app` 和 `returnTo`；SDK 不会输出 `client_id` 或 `callback_url`。
+
+### `login(username, password)`
+
+向 `POST /api/v1/auth/token` 发送 `{ username, password }`，将返回的 token 写入 `TokenStore`，并返回 token、可选的可信上下文和身份信息。
+
+```ts
+const result = await auth.login('alice', 'secret')
+if (!result.ok) throw new Error(result.error)
+```
+
+### `refreshToken()`
+
+使用 `TokenStore` 中的 refresh token 调用 `POST /api/v1/auth/refresh`。同一客户端实例中的并发刷新会合并为一次请求；成功后轮换 token，失败时清空 token。
+
+```ts
+const result = await auth.refreshToken()
+if (!result.ok) window.location.assign('/login')
+```
+
+### `getIdentity()`
+
+从 `TokenStore` 读取 access token，以 Bearer token 调用 `GET /api/v1/auth/me`，返回 IAM 远程响应中的 user、roles 和 permissions。SDK 不使用 JWKS，也不在本地解析 token。
+
+```ts
+const result = await auth.getIdentity()
+if (result.ok && result.value.permissions.includes('orders:read')) {
+  // 渲染订单入口
+}
+```
+
+### `getContext()`
+
+同样通过 `GET /api/v1/auth/me` 获取远程数据，但只在响应包含可信的 `principal_kind`、`selected_tenant`、`default_target` 和 `app_access` 时返回 `AuthContext`。缺少这些字段时返回 `AUTH_CONTEXT_MISSING`；`app_access.allowed` 为 false 时返回 `APP_ACCESS_DENIED`。不会从 roles 或 memberships 推断上下文。
+
+```ts
+const result = await auth.getContext()
+if (result.ok) console.log(result.value.selectedTenant)
+```
+
+### `logout()`
+
+只清空 `TokenStore`，不发送网络请求。
+
+```ts
+await auth.logout()
+```
+
+## 其他公开工具
+
+### `sanitizeCallbackUrl(url)`
+
+返回已删除认证参数的路径、查询和 hash，适合回调页在写入 TokenStore 后清理浏览器地址。
+
+```ts
+window.history.replaceState(null, '', sanitizeCallbackUrl(window.location.href))
+```
+
+### `resolveTenantDecision(input)`
+
+优先消费 `AuthContext` 中受信任的 selected tenant。只有显式设置 `allowLegacyDefault: true` 时，才兼容一个激活的 legacy `isDefault` membership。
+
+```ts
+const decision = resolveTenantDecision({ context: authContext })
+if (decision.ok) useTenant(decision.value.selectedTenant.id)
+```
+
+### `createAuthKit(config)`
+
+旧版兼容入口。它返回 `validateConfiguration()`、`buildAuthorizeUrl()`、`decideDestination(context)` 和 `applySession(result, adapter?)`。新业务使用 `create()`；此入口仅保留给仍依赖旧配置和返回形状的调用方。
+
+### `createRefreshCoordinator()`
+
+创建旧版 refresh single-flight 协调器。`refresh(task)` 会让同一实例中并发的布尔刷新任务共用一个 Promise。
+
+```ts
+const coordinator = createRefreshCoordinator()
+await coordinator.refresh(() => refreshBusinessSession())
+```
+
+## 公开类型与结果
+
+`AuthKitConfig`、`AuthClient`、`TokenStore`、`TokenSet`、`AuthIdentity`、`AuthContext`、`AuthKitResult`、`LoginResult`、`AuthorizeOptions`、`TenantDecision` 和相关 legacy 类型均从包根导出。由 `create()` 返回的客户端方法返回 `{ ok: true, value }` 或 `{ ok: false, error, retryable? }`；调用方应先判断 `ok` 再读取 `value`。
+
+SDK 可以解包 IAM 的 `{ success, message, data }` 响应信封，也兼容裸 JSON 响应。它不实现 IAM 后端授权、回跳白名单或 JWKS token 校验。

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+export type PrincipalKind = 'PLATFORM_ADMIN' | 'BUSINESS_TENANT_MEMBER' | 'BUSINESS_ONLY' | 'TENANT_OR_BUSINESS';
+export interface SelectedTenant {
+    id: string;
+    membershipId: string;
+}
+export interface DefaultTarget {
+    kind: 'PLATFORM' | 'BUSINESS';
+    url: string;
+}
+export interface AppAccess {
+    allowed: boolean;
+    roles: string[];
+}
+export interface AuthContext {
+    userId?: string;
+    principalKind?: PrincipalKind;
+    selectedTenant?: SelectedTenant;
+    defaultTarget?: DefaultTarget;
+    appAccess?: AppAccess;
+    permissions?: string[];
+    expiresAt?: number;
+    clientId?: string;
+    appCode?: string;
+    tenantId?: string;
+    membershipId?: string;
+    tenantPlatformUrl?: string;
+    callbackUrl?: string;
+}
+export interface AuthResult<T> {
+    context?: AuthContext;
+    accessToken?: string;
+    refreshToken?: string;
+    value?: T;
+}
+export interface TokenSet {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn?: number;
+}
+export interface TokenStore {
+    get: () => TokenSet | null;
+    set: (tokens: TokenSet) => void;
+    clear: () => void;
+}
+export interface SessionAdapter<T = void> {
+    set: (result: AuthResult<unknown>) => T | Promise<T>;
+    clear?: () => void | Promise<void>;
+}
+export interface AuthKitConfig {
+    authDomain: string;
+    app?: string;
+    /** @deprecated 请改用 app。 */
+    appCode?: string;
+    /** @deprecated 请改用 app。 */
+    clientId?: string;
+    tokenStore?: TokenStore;
+    fetchImpl?: typeof fetch;
+    runtime?: 'development' | 'test' | 'staging' | 'production';
+}
+export interface LegacyAuthKitConfig {
+    clientId: string;
+    appCode: string;
+    callbackUrl: string;
+    loginEntryUrl?: string;
+    runtimeLoginEntryUrl?: string;
+    buildLoginEntryUrl?: string;
+    developmentLoginEntryUrl?: string;
+    allowedLoginOrigins?: readonly string[];
+    isLoginHost?: boolean;
+}
+export type AuthErrorCode = 'AUTH_DOMAIN_MISSING' | 'AUTH_DOMAIN_INVALID' | 'CALLBACK_URL_INVALID' | 'RETURN_TO_UNAVAILABLE' | 'AUTH_ENTRY_CALLBACK_LOOP' | 'LOGIN_REQUIRED' | 'INVALID_CREDENTIALS' | 'AUTH_CONTEXT_MISSING' | 'PRINCIPAL_CONTEXT_INVALID' | 'TENANT_CONTEXT_INVALID' | 'TENANT_ACCESS_DENIED' | 'APP_ACCESS_DENIED' | 'CALLBACK_REJECTED' | 'TOKEN_EXPIRED' | 'REFRESH_FAILED' | 'LOGOUT_FAILED' | 'AUTH_PROTOCOL_UNAVAILABLE';
+export type AuthKitError = AuthErrorCode | 'LOGIN_ENTRY_URL_MISSING' | 'INVALID_LOGIN_ENTRY_URL' | 'LOGIN_ENTRY_ORIGIN_DENIED' | 'INVALID_CALLBACK' | 'CROSS_APP_CONTEXT' | 'IDENTITY_CONTEXT_MISSING';
+export type AuthKitResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: AuthKitError;
+    retryable?: boolean;
+};
+export interface LoginResult extends TokenSet {
+    context?: AuthContext;
+    identity?: AuthIdentity;
+}
+export interface AuthIdentity {
+    userId: string;
+    userName?: string;
+    tenantId?: string;
+    membershipId?: string;
+    roles: string[];
+    permissions: string[];
+    attrs?: Record<string, unknown>;
+}
+export interface AuthorizeOptions {
+    returnTo?: string;
+    app?: string;
+    /** @deprecated 请改用 returnTo。 */
+    callbackUrl?: string;
+    /** @deprecated 请改用 app。 */
+    appCode?: string;
+    /** @deprecated 请改用 app。 */
+    clientId?: string;
+    state?: string;
+}
+export interface AuthClient {
+    validate: () => AuthKitResult<void>;
+    buildAuthorizeUrl: (options?: AuthorizeOptions) => AuthKitResult<string>;
+    login: (username: string, password: string) => Promise<AuthKitResult<LoginResult>>;
+    refreshToken: () => Promise<AuthKitResult<LoginResult>>;
+    getIdentity: () => Promise<AuthKitResult<AuthIdentity>>;
+    getContext: () => Promise<AuthKitResult<AuthContext>>;
+    logout: () => Promise<AuthKitResult<void>>;
+}
+/** 清理不应保留在 history 或 referrer 的认证参数。 */
+export declare function sanitizeCallbackUrl(value: string): string;
+export interface LegacyMembershipCandidate {
+    membershipId: string;
+    tenantId: string;
+    membershipStatus?: string;
+    isDefault?: boolean | number;
+    appAccess?: boolean;
+}
+export interface TenantDecision {
+    selectedTenant: SelectedTenant;
+    source: 'trusted-context' | 'legacy-is-default';
+}
+/** 只消费后端 selected tenant；旧接口仅允许 is_default 兼容，不猜 joined_at 或身份。 */
+export declare function resolveTenantDecision(input: {
+    context?: Pick<AuthContext, 'principalKind' | 'selectedTenant' | 'appAccess'>;
+    memberships?: readonly LegacyMembershipCandidate[];
+    allowLegacyDefault?: boolean;
+}): AuthKitResult<TenantDecision>;
+export declare function create(config: AuthKitConfig): AuthClient;
+/** 创建旧版兼容实例；新业务接入请使用 create。 */
+export declare function createAuthKit(config: LegacyAuthKitConfig): {
+    validateConfiguration: () => AuthKitResult<{
+        loginEntryUrl: string;
+    }>;
+    buildAuthorizeUrl: (_requestedTenantId?: string) => AuthKitResult<{
+        url: string;
+    }>;
+    decideDestination: (context: AuthContext) => AuthKitResult<{
+        url: string;
+        ignoredCallback: boolean;
+    }>;
+    applySession: (result: AuthResult<unknown>, adapter?: SessionAdapter) => Promise<AuthResult<unknown>>;
+};
+/** 同一标签页只保留一个刷新请求；传输和存储仍由宿主负责。 */
+export declare function createRefreshCoordinator(): {
+    refresh(task: () => Promise<boolean>): Promise<boolean>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,360 @@
+const SENSITIVE_CALLBACK_PARAMS = ['access_token', 'refresh_token', 'code', 'id_token', 'token'];
+function removeSensitiveCallbackParams(url) {
+    for (const param of SENSITIVE_CALLBACK_PARAMS)
+        url.searchParams.delete(param);
+    const hash = url.hash.slice(1);
+    const queryIndex = hash.indexOf('?');
+    const hashQuery = queryIndex >= 0 ? hash.slice(queryIndex + 1) : hash.includes('=') ? hash : null;
+    if (!hashQuery)
+        return url;
+    const hashParams = new URLSearchParams(hashQuery);
+    for (const param of SENSITIVE_CALLBACK_PARAMS)
+        hashParams.delete(param);
+    const sanitizedHashQuery = hashParams.toString();
+    url.hash = queryIndex >= 0
+        ? sanitizedHashQuery ? `${hash.slice(0, queryIndex)}?${sanitizedHashQuery}` : hash.slice(0, queryIndex)
+        : sanitizedHashQuery;
+    return url;
+}
+/** 清理不应保留在 history 或 referrer 的认证参数。 */
+export function sanitizeCallbackUrl(value) {
+    const url = removeSensitiveCallbackParams(new URL(value));
+    return `${url.pathname}${url.search}${url.hash}`;
+}
+function parseHttpUrl(value, allowLocalhost = true) {
+    try {
+        const url = new URL(value);
+        if (url.protocol === 'https:')
+            return url;
+        if (allowLocalhost && url.protocol === 'http:' && (url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]'))
+            return url;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function currentBrowserUrl() {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        return removeSensitiveCallbackParams(new URL(window.location.href)).toString();
+    }
+    catch {
+        return null;
+    }
+}
+function ok(value) {
+    return { ok: true, value };
+}
+function fail(error, retryable = false) {
+    return retryable ? { ok: false, error, retryable: true } : { ok: false, error };
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object');
+}
+/** 认证服务与业务接口统一使用响应信封，SDK 对外仍返回既有领域对象。 */
+function unwrapResponse(value) {
+    if (!isRecord(value) || !('success' in value))
+        return { ok: true, value };
+    return value.success === true ? { ok: true, value: value.data } : { ok: false };
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function normalizeContext(value) {
+    if (!isRecord(value))
+        return null;
+    const principalKind = stringValue(value.principal_kind ?? value.principalKind);
+    const tenant = (value.selected_tenant ?? value.selectedTenant);
+    const target = (value.default_target ?? value.defaultTarget);
+    const access = (value.app_access ?? value.appAccess);
+    const tenantId = stringValue(tenant?.id ?? value.tenantId);
+    const membershipId = stringValue(tenant?.membership_id ?? tenant?.membershipId ?? value.membershipId);
+    const appCode = stringValue(value.app_code ?? value.appCode);
+    const userId = stringValue(value.user_id ?? value.userId);
+    if (!principalKind || !tenantId || !membershipId || !appCode || !userId || !target || !access)
+        return null;
+    const targetKind = target.kind;
+    const targetUrl = stringValue(target.url);
+    if ((targetKind !== 'PLATFORM' && targetKind !== 'BUSINESS') || !targetUrl || typeof access.allowed !== 'boolean')
+        return null;
+    return {
+        userId,
+        principalKind,
+        selectedTenant: { id: tenantId, membershipId },
+        defaultTarget: { kind: targetKind, url: targetUrl },
+        appCode,
+        appAccess: { allowed: access.allowed, roles: Array.isArray(access.roles) ? access.roles.filter((role) => typeof role === 'string') : [] },
+        permissions: Array.isArray(value.permissions) ? value.permissions.filter((permission) => typeof permission === 'string') : [],
+        expiresAt: typeof value.expires_at === 'number' ? value.expires_at : typeof value.expiresAt === 'number' ? value.expiresAt : undefined,
+    };
+}
+function toTokenSet(value) {
+    if (!isRecord(value))
+        return null;
+    const accessToken = stringValue(value.access_token ?? value.accessToken);
+    if (!accessToken)
+        return null;
+    const refreshToken = stringValue(value.refresh_token ?? value.refreshToken);
+    const expiresIn = typeof value.expires_in === 'number' ? value.expires_in : typeof value.expiresIn === 'number' ? value.expiresIn : undefined;
+    return { accessToken, refreshToken, expiresIn };
+}
+function normalizeIdentity(value) {
+    if (!isRecord(value))
+        return null;
+    const nestedUser = isRecord(value.user) ? value.user : value;
+    const userId = stringValue(nestedUser.user_id ?? nestedUser.userId);
+    if (!userId)
+        return null;
+    const userName = stringValue(nestedUser.user_name ?? nestedUser.userName);
+    const tenantId = stringValue(value.tenantId ?? nestedUser.tenant_id ?? nestedUser.tenantId);
+    const membershipId = stringValue(value.membershipId ?? nestedUser.membership_id ?? nestedUser.membershipId);
+    const attrs = isRecord(value.attrs) ? value.attrs : undefined;
+    return {
+        userId,
+        ...(userName ? { userName } : {}),
+        ...(tenantId ? { tenantId } : {}),
+        ...(membershipId ? { membershipId } : {}),
+        roles: Array.isArray(nestedUser.roles) ? nestedUser.roles.filter((role) => typeof role === 'string') : [],
+        permissions: Array.isArray(nestedUser.permissions) ? nestedUser.permissions.filter((permission) => typeof permission === 'string') : [],
+        ...(attrs ? { attrs } : {}),
+    };
+}
+/** 只消费后端 selected tenant；旧接口仅允许 is_default 兼容，不猜 joined_at 或身份。 */
+export function resolveTenantDecision(input) {
+    const context = input.context;
+    const trustedPrincipal = context?.principalKind === 'PLATFORM_ADMIN'
+        || context?.principalKind === 'BUSINESS_TENANT_MEMBER'
+        || context?.principalKind === 'BUSINESS_ONLY'
+        || context?.principalKind === 'TENANT_OR_BUSINESS';
+    if (trustedPrincipal && context?.selectedTenant && context.appAccess) {
+        if (!context.appAccess.allowed)
+            return fail('APP_ACCESS_DENIED');
+        return ok({ selectedTenant: context.selectedTenant, source: 'trusted-context' });
+    }
+    if (!input.allowLegacyDefault)
+        return fail('AUTH_CONTEXT_MISSING');
+    const candidates = (input.memberships ?? []).filter((membership) => (membership.membershipStatus === undefined || membership.membershipStatus === 'ACTIVE')
+        && (membership.isDefault === true || membership.isDefault === 1));
+    const accessible = candidates.filter((membership) => membership.appAccess !== false);
+    if (accessible.length !== 1)
+        return fail('TENANT_CONTEXT_INVALID');
+    return ok({
+        selectedTenant: { id: accessible[0].tenantId, membershipId: accessible[0].membershipId },
+        source: 'legacy-is-default',
+    });
+}
+function createMemoryStore() {
+    let tokens = null;
+    return {
+        get: () => tokens,
+        set: (next) => { tokens = next; },
+        clear: () => { tokens = null; },
+    };
+}
+function responseError(status) {
+    if (status === 401)
+        return fail('INVALID_CREDENTIALS');
+    if (status === 403)
+        return fail('APP_ACCESS_DENIED');
+    if (status >= 500)
+        return fail('AUTH_PROTOCOL_UNAVAILABLE', true);
+    return fail('AUTH_PROTOCOL_UNAVAILABLE', status >= 408);
+}
+export function create(config) {
+    const fetchImpl = config.fetchImpl ?? fetch;
+    const tokenStore = config.tokenStore ?? createMemoryStore();
+    const authDomain = config.authDomain.replace(/\/$/, '');
+    let refreshPending = null;
+    function validate() {
+        if (!config.authDomain)
+            return fail('AUTH_DOMAIN_MISSING');
+        if (!parseHttpUrl(config.authDomain, config.runtime === 'development' || config.runtime === 'test'))
+            return fail('AUTH_DOMAIN_INVALID');
+        return ok(undefined);
+    }
+    function buildAuthorizeUrl(options = {}) {
+        const valid = validate();
+        if (!valid.ok)
+            return valid;
+        const url = new URL('/auth/login', `${authDomain}/`);
+        const app = options.app ?? config.app ?? options.appCode ?? options.clientId ?? config.appCode ?? config.clientId ?? '';
+        const configuredReturnTo = options.returnTo ?? options.callbackUrl;
+        const returnTo = configuredReturnTo ?? currentBrowserUrl();
+        if (returnTo === null)
+            return fail('RETURN_TO_UNAVAILABLE');
+        const callbackUrl = parseHttpUrl(returnTo, config.runtime === 'development' || config.runtime === 'test');
+        if (!callbackUrl)
+            return fail('CALLBACK_URL_INVALID');
+        url.searchParams.set('app', app);
+        url.searchParams.set('return_to', callbackUrl.toString());
+        if (options.state)
+            url.searchParams.set('state', options.state);
+        return ok(url.toString());
+    }
+    async function login(username, password) {
+        const valid = validate();
+        if (!valid.ok)
+            return valid;
+        if (!username || !password)
+            return fail('INVALID_CREDENTIALS');
+        try {
+            const response = await fetchImpl(`${authDomain}/api/v1/auth/token`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ username, password }),
+            });
+            if (!response.ok)
+                return responseError(response.status);
+            const responseBody = unwrapResponse(await response.json());
+            if (!responseBody.ok)
+                return fail('AUTH_PROTOCOL_UNAVAILABLE');
+            const body = responseBody.value;
+            const tokens = toTokenSet(body);
+            if (!tokens)
+                return fail('AUTH_PROTOCOL_UNAVAILABLE');
+            tokenStore.set(tokens);
+            const context = isRecord(body) ? normalizeContext(body.context ?? body.auth_context) ?? undefined : undefined;
+            return ok({ ...tokens, context, identity: normalizeIdentity(body) ?? undefined });
+        }
+        catch {
+            return fail('AUTH_PROTOCOL_UNAVAILABLE', true);
+        }
+    }
+    async function runRefresh() {
+        const current = tokenStore.get();
+        if (!current?.refreshToken)
+            return fail('REFRESH_FAILED');
+        try {
+            const response = await fetchImpl(`${authDomain}/api/v1/auth/refresh`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ refresh_token: current.refreshToken }),
+            });
+            if (!response.ok) {
+                tokenStore.clear();
+                return response.status === 401 ? fail('TOKEN_EXPIRED') : responseError(response.status);
+            }
+            const responseBody = unwrapResponse(await response.json());
+            if (!responseBody.ok) {
+                tokenStore.clear();
+                return fail('AUTH_PROTOCOL_UNAVAILABLE');
+            }
+            const body = responseBody.value;
+            const tokens = toTokenSet(body);
+            if (!tokens) {
+                tokenStore.clear();
+                return fail('AUTH_PROTOCOL_UNAVAILABLE');
+            }
+            tokenStore.set(tokens);
+            return ok({ ...tokens, context: isRecord(body) ? normalizeContext(body.context ?? body.auth_context) ?? undefined : undefined, identity: normalizeIdentity(body) ?? undefined });
+        }
+        catch {
+            tokenStore.clear();
+            return fail('REFRESH_FAILED', true);
+        }
+    }
+    function refreshToken() {
+        if (!refreshPending)
+            refreshPending = runRefresh().finally(() => { refreshPending = null; });
+        return refreshPending;
+    }
+    async function getRemoteIdentity() {
+        const current = tokenStore.get();
+        if (!current?.accessToken)
+            return fail('LOGIN_REQUIRED');
+        try {
+            const response = await fetchImpl(`${authDomain}/api/v1/auth/me`, { headers: { Authorization: `Bearer ${current.accessToken}` } });
+            if (!response.ok)
+                return response.status === 401 ? fail('TOKEN_EXPIRED') : responseError(response.status);
+            const responseBody = unwrapResponse(await response.json());
+            if (!responseBody.ok)
+                return fail('AUTH_PROTOCOL_UNAVAILABLE');
+            return ok(responseBody.value);
+        }
+        catch {
+            return fail('AUTH_PROTOCOL_UNAVAILABLE', true);
+        }
+    }
+    async function getContext() {
+        const remoteIdentity = await getRemoteIdentity();
+        if (!remoteIdentity.ok)
+            return remoteIdentity;
+        const context = normalizeContext(remoteIdentity.value);
+        if (!context)
+            return fail('AUTH_CONTEXT_MISSING');
+        if (!context.appAccess?.allowed)
+            return fail('APP_ACCESS_DENIED');
+        return ok(context);
+    }
+    async function getIdentity() {
+        const remoteIdentity = await getRemoteIdentity();
+        if (!remoteIdentity.ok)
+            return remoteIdentity;
+        const identity = normalizeIdentity(remoteIdentity.value);
+        return identity ? ok(identity) : fail('AUTH_PROTOCOL_UNAVAILABLE');
+    }
+    async function logout() {
+        tokenStore.clear();
+        return ok(undefined);
+    }
+    return { validate, buildAuthorizeUrl, login, refreshToken, getIdentity, getContext, logout };
+}
+/** 创建旧版兼容实例；新业务接入请使用 create。 */
+export function createAuthKit(config) {
+    const callbackUrl = parseHttpUrl(config.callbackUrl);
+    const configuredEntry = config.loginEntryUrl ?? config.runtimeLoginEntryUrl ?? config.buildLoginEntryUrl ?? config.developmentLoginEntryUrl;
+    const entryUrl = configuredEntry ? parseHttpUrl(configuredEntry) : null;
+    const allowedOrigins = config.allowedLoginOrigins ?? (entryUrl ? [entryUrl.origin] : []);
+    function validateConfiguration() {
+        if (!configuredEntry)
+            return fail('LOGIN_ENTRY_URL_MISSING');
+        if (!entryUrl || !callbackUrl)
+            return fail('INVALID_LOGIN_ENTRY_URL');
+        if (!allowedOrigins.includes(entryUrl.origin))
+            return fail('LOGIN_ENTRY_ORIGIN_DENIED');
+        return ok({ loginEntryUrl: entryUrl.toString() });
+    }
+    function buildAuthorizeUrl(_requestedTenantId) {
+        const valid = validateConfiguration();
+        if (!valid.ok)
+            return valid;
+        if (config.isLoginHost)
+            return fail('AUTH_ENTRY_CALLBACK_LOOP');
+        const url = new URL(valid.value.loginEntryUrl);
+        url.searchParams.set('app', config.appCode);
+        url.searchParams.set('return_to', callbackUrl.toString());
+        return ok({ url: url.toString() });
+    }
+    function decideDestination(context) {
+        if (!context.clientId || context.clientId !== config.clientId || !context.appCode || context.appCode !== config.appCode || !context.tenantId || !context.membershipId)
+            return fail('IDENTITY_CONTEXT_MISSING');
+        const platformUrl = context.tenantPlatformUrl ? parseHttpUrl(context.tenantPlatformUrl) : null;
+        if (!platformUrl)
+            return fail('IDENTITY_CONTEXT_MISSING');
+        if (context.principalKind === 'PLATFORM_ADMIN')
+            return ok({ url: platformUrl.toString(), ignoredCallback: Boolean(context.callbackUrl) });
+        const callback = context.callbackUrl ? parseHttpUrl(context.callbackUrl) : null;
+        if (callback && callback.origin === callbackUrl?.origin)
+            return ok({ url: callback.toString(), ignoredCallback: false });
+        return ok({ url: platformUrl.toString(), ignoredCallback: false });
+    }
+    async function applySession(result, adapter) {
+        if (adapter)
+            await adapter.set(result);
+        return result;
+    }
+    return { validateConfiguration, buildAuthorizeUrl, decideDestination, applySession };
+}
+/** 同一标签页只保留一个刷新请求；传输和存储仍由宿主负责。 */
+export function createRefreshCoordinator() {
+    let pending = null;
+    return {
+        refresh(task) {
+            if (!pending)
+                pending = task().finally(() => { pending = null; });
+            return pending;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@msdongcha/auth-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Framework-agnostic authentication context, redirect, callback and session coordination utilities.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "CHANGELOG.md"],
+  "sideEffects": false,
+  "engines": { "node": ">=20" },
+  "license": "UNLICENSED",
+  "publishConfig": { "access": "public", "provenance": true },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "lint": "tsc -p tsconfig.build.json --noEmit",
+    "test": "pnpm run build && node --test test/*.test.mjs",
+    "pack:dry-run": "pnpm pack --dry-run"
+  },
+  "devDependencies": { "typescript": "~6.0.2" }
+}