@msdongcha/auth-kit 0.0.0-stage → 0.0.1

package/CHANGELOG.md

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

package/README.md

@@ -1,3 +1,25 @@
-# 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.
+无 UI、framework-agnostic 的认证域名校验、统一登录地址、账号密码登录、refresh、可信上下文消费与 logout 工具。它不包含 React、Router、页面、表单、样式或后端授权实现。
+
+```ts
+import { create } from '@msdongcha/auth-kit'
+
+const auth = create({
+  authDomain: 'https://iam.example.com',
+  appCode: 'business-web',
+  allowedCallbackOrigins: ['https://business.example.com'],
+})
+
+const authorizeUrl = auth.buildAuthorizeUrl({
+  callbackUrl: 'https://business.example.com/auth/callback',
+})
+```
+
+`getContext()` 需要后端返回可信 `principal_kind`、`selected_tenant`、`default_target` 和 `app_access`。当前服务端响应缺失这些字段时，SDK 返回 `AUTH_CONTEXT_MISSING` 或 `APP_ACCESS_DENIED`，不会从 roles 或 memberships 猜测。
+
+`getIdentity()` 是旧 `/api/v1/auth/me` 的兼容读取入口，只用于 IAM 内部页面展示 user、tenant、membership、roles 和 permissions；它不能替代可信 `AuthContext`，也不能放行外部业务 callback。
+
+应用应通过一个 `TokenStore` adapter 将 SDK 接到自己的 session store。SDK 负责 login/refresh HTTP 与 token rotation，应用业务 client 只负责 Bearer 注入和一次重试。
+
+`createAuthKit` 和 `createRefreshCoordinator` 保留为旧版本兼容入口，新业务请使用 `create`。

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+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;
+    appCode?: string;
+    clientId?: string;
+    allowedCallbackOrigins?: readonly 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' | 'CALLBACK_ORIGIN_DENIED' | '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 {
+    callbackUrl: string;
+    appCode?: string;
+    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>>;
+}
+/** 清理回调 URL 中不应保留在 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,323 @@
+/** 清理回调 URL 中不应保留在 history 或 referrer 的认证参数。 */
+export function sanitizeCallbackUrl(value) {
+    const url = new URL(value);
+    url.searchParams.delete('access_token');
+    url.searchParams.delete('refresh_token');
+    url.searchParams.delete('code');
+    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 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');
+}
+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 callbackUrl = parseHttpUrl(options.callbackUrl, config.runtime === 'development' || config.runtime === 'test');
+        if (!callbackUrl)
+            return fail('CALLBACK_URL_INVALID');
+        const allowedOrigins = config.allowedCallbackOrigins ?? [];
+        if (allowedOrigins.length > 0 && !allowedOrigins.includes(callbackUrl.origin))
+            return fail('CALLBACK_ORIGIN_DENIED');
+        const url = new URL('/auth/login', `${authDomain}/`);
+        url.searchParams.set('app', options.appCode ?? config.appCode ?? '');
+        url.searchParams.set('client_id', options.clientId ?? config.clientId ?? '');
+        url.searchParams.set('callback_url', callbackUrl.toString());
+        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 body = await response.json();
+            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 body = await response.json();
+            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 getContext() {
+        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 context = normalizeContext(await response.json());
+            if (!context)
+                return fail('AUTH_CONTEXT_MISSING');
+            if (!context.appAccess?.allowed)
+                return fail('APP_ACCESS_DENIED');
+            return ok(context);
+        }
+        catch {
+            return fail('AUTH_PROTOCOL_UNAVAILABLE', true);
+        }
+    }
+    async function getIdentity() {
+        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 identity = normalizeIdentity(await response.json());
+            return identity ? ok(identity) : fail('AUTH_PROTOCOL_UNAVAILABLE');
+        }
+        catch {
+            return fail('AUTH_PROTOCOL_UNAVAILABLE', true);
+        }
+    }
+    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('client_id', config.clientId);
+        url.searchParams.set('app', config.appCode);
+        url.searchParams.set('return_to', callbackUrl.toString());
+        if (requestedTenantId)
+            url.searchParams.set('requested_tenant_id', requestedTenantId);
+        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.1",
+  "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" }
+}