@jcoder-stack/abp-react 0.1.1 → 0.1.3

package/README.md

@@ -1,37 +1,37 @@
 # @jcoder-stack/abp-react
 
-`abp-react-start` 的运行时内核——从零自研的纯 React ABP 前端框架，总览见仓库根 README。
+The runtime core of `abp-react-start` — a pure-React frontend framework for ABP backends. See the repository root README for the big picture.
 
-各域按**子路径**导出，没有把所有东西糊在一起的根导出：一个根导出会让纯前端的 bundle 拖进 `proxy`/`auth` 这类服务端代码。
+Every domain is exported through a **subpath**; there is no root export: an aggregate entry point would drag server-side modules like `proxy` and `auth` into the browser bundle.
 
-| 子路径 | 职责 |
+| Subpath | Responsibility |
 | --- | --- |
-| `@jcoder-stack/abp-react/logger` | 同构日志：作用域、字段绑定、默认脱敏、env 开关 |
-| `@jcoder-stack/abp-react/core` | ABP 线上格式归一：application-configuration 的类型 + zod（容错解析）、`PagedResult<T>`、错误信封（`HttpError`/`toHttpError`） |
-| `@jcoder-stack/abp-react/auth` | 授权认证核心：登录策略层（OIDC/password）+ 会话层（加密分块 cookie、刷新、登出）；宿主无关、后端无关 |
-| `@jcoder-stack/abp-react/proxy` | ABP 代理网关与调用层：贴 Bearer 转发、401→刷新→重放、幂等重试、超时；策略头组装、会话代调、身份派生；ABP auth 运行时工厂 `createAbpAuthRuntime` 与登录/回调/登出/文化/租户 handler |
-| `@jcoder-stack/abp-react/permissions` | 权限判定原语 `isGranted` + 变参 checker |
-| `@jcoder-stack/abp-react/i18n` | 两层合并 translator（后端 ABP 资源覆盖前端词库），可注入 interpolate/plural |
-| `@jcoder-stack/abp-react/react` | `AppConfigProvider` / `SessionProvider` + hooks（用户/权限/设置/特性/本地化/菜单）+ `<PermissionGuard>`/`<FeatureGuard>` |
-| `@jcoder-stack/abp-react/router` | TanStack Router beforeLoad 路由守卫 `requireAuth` / `requirePermission` |
+| `@jcoder-stack/abp-react/logger` | Isomorphic logging: scopes, field binding, redaction by default, env switches |
+| `@jcoder-stack/abp-react/core` | Normalizing ABP wire formats: application-configuration types + zod (tolerant parsing), `PagedResult<T>`, the error envelope (`HttpError`/`toHttpError`) |
+| `@jcoder-stack/abp-react/auth` | Authentication core: the sign-in strategy layer (OIDC/password) + the session layer (encrypted chunked cookies, refresh, logout); host-agnostic and backend-agnostic |
+| `@jcoder-stack/abp-react/proxy` | The ABP proxy gateway and call layer: Bearer-attached forwarding, 401→refresh→replay, idempotent retries, timeouts; policy-header assembly, session brokering, identity derivation; the ABP auth runtime factory `createAbpAuthRuntime` plus the login/callback/logout/culture/tenant handlers |
+| `@jcoder-stack/abp-react/permissions` | The permission primitive `isGranted` + a variadic checker |
+| `@jcoder-stack/abp-react/i18n` | A two-layer merging translator (backend ABP resources override the frontend catalog), with injectable interpolate/plural |
+| `@jcoder-stack/abp-react/react` | `AppConfigProvider` / `SessionProvider` + hooks (user/permissions/settings/features/localization/menu) + `<PermissionGuard>`/`<FeatureGuard>` |
+| `@jcoder-stack/abp-react/router` | TanStack Router beforeLoad guards `requireAuth` / `requirePermission` |
 
-## 安装
+## Install
 
 ```bash
 bun add @jcoder-stack/abp-react
 ```
 
-多数项目是配合 `@jcoder-stack/cli` 使用的——`jc-abp init` 会把接线代码落进你的项目，之后这些文件归你维护。手工接线见下。
+Most projects use it together with `@jcoder-stack/cli` — `jc-abp init` writes the wiring code into your project, and those files are yours to maintain afterwards. Manual wiring is described below.
 
 ## peerDependencies
 
-`react`、`@tanstack/react-router`、`zod` 三者全部声明为 **optional** peer：纯 BFF 消费者只用 `/proxy`、`/auth`，不该被逼装 React 与 router；纯前端消费者只用 `/react`、`/i18n`，也不该被逼装 zod。装哪几个由你实际用到的子路径决定，缺的那些包管理器不会报警。
+`react`, `@tanstack/react-router`, and `zod` are all declared as **optional** peers: a pure BFF consumer only uses `/proxy` and `/auth` and should not be forced to install React and the router; a pure frontend consumer only uses `/react` and `/i18n` and should not be forced to install zod. Install whichever ones the subpaths you actually use require — package managers stay silent about the missing rest.
 
-## 用法
+## Usage
 
-### 服务端：auth 运行时
+### Server side: the auth runtime
 
-`createAbpAuthRuntime` 从环境变量读配置（`AUTH_ISSUER`、`AUTH_CLIENT_ID`、`AUTH_SESSION_SECRET`、`AUTH_REDIRECT_URI`、`AUTH_ABP_BASE_URL`），返回登录/回调/登出所需的一切。每个覆盖项都有默认值：
+`createAbpAuthRuntime` reads its configuration from environment variables (`AUTH_ISSUER`, `AUTH_CLIENT_ID`, `AUTH_SESSION_SECRET`, `AUTH_REDIRECT_URI`, `AUTH_ABP_BASE_URL`) and returns everything the login/callback/logout handlers need. Every override has a default:
 
 ```ts
 import { createAbpAuthRuntime } from "@jcoder-stack/abp-react/proxy";
@@ -45,11 +45,11 @@ export const createRuntime = () =>
   });
 ```
 
-`AUTH_SESSION_SECRET` 至少 32 字符——会话 cookie 用它经 HKDF 派生 AES-GCM 密钥，短于此长度会直接抛错而非静默产出弱密钥。
+`AUTH_SESSION_SECRET` must be at least 32 characters — the session cookie derives its AES-GCM key from it via HKDF, and anything shorter throws outright instead of silently producing a weak key.
 
-### 客户端：Provider 与 hooks
+### Client side: providers and hooks
 
-两个 Provider 分开挂：配置（本地化/设置/特性）与身份的失效时机不同，合成一个会让身份刷新连带重建 translator。
+The two providers are mounted separately: configuration (localization/settings/features) and identity invalidate at different times, and folding them into one would make an identity refresh rebuild the translator along with it.
 
 ```tsx
 import { AppConfigProvider, SessionProvider } from "@jcoder-stack/abp-react/react";
@@ -61,9 +61,9 @@ import { AppConfigProvider, SessionProvider } from "@jcoder-stack/abp-react/reac
 </AppConfigProvider>;
 ```
 
-`messages` 需引用稳定（模块常量或 `useMemo`）——它参与 translator 的重建判定。回调 props（`onMissingKey`、`createTranslator`）经 ref 读取，写成内联箭头函数不会导致 context 重建。
+`messages` needs a stable reference (a module constant or `useMemo`) — it participates in the translator rebuild check. Callback props (`onMissingKey`, `createTranslator`) are read through refs, so writing them as inline arrows does not rebuild the context.
 
-### 路由守卫
+### Route guards
 
 ```ts
 import { requireAuth, requirePermission } from "@jcoder-stack/abp-react/router";
@@ -73,7 +73,7 @@ export const Route = createFileRoute("/_layout/_authed")({
 });
 ```
 
-守卫是**纯 UX**——真正的安全判定在 ABP 服务端。`requirePermission` 缺权限时跳 `/forbidden`；匿名用户没有任何 grantedPolicies，默认也会落到 403，传 `loginPath` 可让未认证访客先去登录：
+The guards are **pure UX** — the real authorization decision lives in the ABP backend. `requirePermission` redirects to `/forbidden` when the permission is missing; an anonymous user has no grantedPolicies at all, so they land on the 403 too by default. Pass `loginPath` to send unauthenticated visitors to sign in first:
 
 ```ts
 beforeLoad: requirePermission(IdentityPermissions.Users.Default, {
@@ -81,6 +81,6 @@ beforeLoad: requirePermission(IdentityPermissions.Users.Default, {
 });
 ```
 
-推荐的做法仍是把受保护页面挂在一个跑 `requireAuth()` 的父路由下，`loginPath` 用于单独使用 `requirePermission` 的场景。
+The recommended layout is still to nest protected pages under a parent route running `requireAuth()`; `loginPath` is for the cases where `requirePermission` is used on its own.
 
-两者都要求祖先路由的 `beforeLoad` 已把 `identity` 放进 route context；没放会抛出带指引的错误而不是静默放行。
+Both guards require an ancestor route's `beforeLoad` to have put `identity` into the route context; when it is missing they throw an error with guidance instead of silently letting the request through.

package/dist/auth.d.ts

@@ -1,8 +1,8 @@
-import { a as CookieOptions, T as TokenClient } from './oidc-7fu5kKVF.js';
-export { A as Auth, b as COOKIE_CHUNK_SIZE, C as Codec, c as CodecSchema, d as OidcMetadata, O as OidcStrategy, S as SessionManager, e as TokenClientConfig, f as TokenGrant, g as chunkCookieValue, h as clearChunkedCookie, i as clearCookie, j as createAuth, k as createCodec, l as createSessionManager, m as createTokenClient, n as discoverMetadata, o as oidcMetadataSchema, p as oidcStrategy, q as parseCookieHeader, r as readChunkedCookie, s as serializeCookie, t as toTokenResult } from './oidc-7fu5kKVF.js';
+import { C as CookieOptions, T as TokenClient } from './oidc-CIQh5yHw.js';
+export { A as Auth, a as COOKIE_CHUNK_SIZE, b as Codec, c as CodecSchema, O as OidcMetadata, d as OidcStrategy, S as SessionManager, e as TokenClientConfig, f as TokenGrant, g as chunkCookieValue, h as clearChunkedCookie, i as clearCookie, j as createAuth, k as createCodec, l as createSessionManager, m as createTokenClient, n as discoverMetadata, o as oidcMetadataSchema, p as oidcStrategy, q as parseCookieHeader, r as readChunkedCookie, s as serializeCookie, t as toTokenResult } from './oidc-CIQh5yHw.js';
 import { e as Logger } from './logger-BSnS65IC.js';
-import { S as SessionStore, b as AuthStrategy } from './types-Bj0MpXtI.js';
-export { A as AuthSession, B as BeginInput, C as CompleteInput, F as FetchFn, H as Handshake, I as Identity, c as IdentityContext, a as IdentityResolver, T as TokenResult, d as authSessionSchema, e as authTokensSchema, h as handshakeSchema } from './types-Bj0MpXtI.js';
+import { S as SessionStore, A as AuthStrategy } from './types-BeHmw3RC.js';
+export { a as AuthSession, B as BeginInput, C as CompleteInput, F as FetchFn, H as Handshake, I as Identity, b as IdentityContext, c as IdentityResolver, T as TokenResult, d as authSessionSchema, e as authTokensSchema, h as handshakeSchema } from './types-BeHmw3RC.js';
 import 'zod';
 
 /** 默认 SessionStore：把整个 AuthSession 密封进（超长时分块的）加密 cookie，自包含无后端。 */

package/dist/{oidc-7fu5kKVF.d.ts → oidc-CIQh5yHw.d.ts}

@@ -1,5 +1,5 @@
 import { e as Logger } from './logger-BSnS65IC.js';
-import { F as FetchFn, T as TokenResult, A as AuthSession, S as SessionStore, b as AuthStrategy, c as IdentityContext, I as Identity, a as IdentityResolver, B as BeginInput, H as Handshake } from './types-Bj0MpXtI.js';
+import { F as FetchFn, T as TokenResult, a as AuthSession, S as SessionStore, A as AuthStrategy, b as IdentityContext, I as Identity, c as IdentityResolver, B as BeginInput, H as Handshake } from './types-BeHmw3RC.js';
 import { z } from 'zod';
 
 /** 把值密封成（并从中解封）AES-GCM 加密、URL 安全的字符串。 */
@@ -199,4 +199,4 @@ declare function oidcStrategy(cfg: {
     handshakeMaxAgeSeconds?: number;
 }): OidcStrategy;
 
-export { type Auth as A, type Codec as C, type OidcStrategy as O, type SessionManager as S, type TokenClient as T, type CookieOptions as a, COOKIE_CHUNK_SIZE as b, type CodecSchema as c, type OidcMetadata as d, type TokenClientConfig as e, type TokenGrant as f, chunkCookieValue as g, clearChunkedCookie as h, clearCookie as i, createAuth as j, createCodec as k, createSessionManager as l, createTokenClient as m, discoverMetadata as n, oidcMetadataSchema as o, oidcStrategy as p, parseCookieHeader as q, readChunkedCookie as r, serializeCookie as s, toTokenResult as t };
+export { type Auth as A, type CookieOptions as C, type OidcMetadata as O, type SessionManager as S, type TokenClient as T, COOKIE_CHUNK_SIZE as a, type Codec as b, type CodecSchema as c, type OidcStrategy as d, type TokenClientConfig as e, type TokenGrant as f, chunkCookieValue as g, clearChunkedCookie as h, clearCookie as i, createAuth as j, createCodec as k, createSessionManager as l, createTokenClient as m, discoverMetadata as n, oidcMetadataSchema as o, oidcStrategy as p, parseCookieHeader as q, readChunkedCookie as r, serializeCookie as s, toTokenResult as t };

package/dist/proxy.d.ts

@@ -1,6 +1,6 @@
 import { e as Logger } from './logger-BSnS65IC.js';
-import { A as AuthSession, I as Identity, a as IdentityResolver, F as FetchFn, H as Handshake } from './types-Bj0MpXtI.js';
-import { A as Auth, O as OidcStrategy, C as Codec, a as CookieOptions } from './oidc-7fu5kKVF.js';
+import { a as AuthSession, I as Identity, c as IdentityResolver, F as FetchFn, H as Handshake } from './types-BeHmw3RC.js';
+import { A as Auth, d as OidcStrategy, b as Codec, C as CookieOptions } from './oidc-CIQh5yHw.js';
 import { A as ApplicationConfiguration } from './application-configuration-DhOZRqtz.js';
 import { z } from 'zod';
 
@@ -95,10 +95,12 @@ declare const abpAuthEnvSchema: z.ZodObject<{
     sessionSecret: z.ZodString;
     abpBaseUrl: z.ZodString;
     debug: z.ZodDefault<z.ZodBoolean>;
+    extraCaFile: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type AbpAuthEnv = z.infer<typeof abpAuthEnvSchema>;
 /**
  * 把 AUTH_* 记录解析成 AbpAuthEnv。
+ * 缺失/不合法时抛聚合后的人话错误（点名 .env 里的变量名），原始 ZodError 挂在 `cause` 上。
  * @param env 通常是 process.env。
  * @param opts.schema 覆盖默认 zod schema（`abpAuthEnvSchema`），用于给 AUTH_* 契约加更严的
  *   校验/精化；解析产物必须仍是 AbpAuthEnv（类型系统兜底，故只能 `.extend()`/`.merge()` 等
@@ -198,4 +200,28 @@ declare function handleSetCulture(request: Request): Response;
 /** GET /api/tenant?tenant=t1&returnUrl=/：落租户 cookie（缺 tenant 则清除）并弹回。 */
 declare function handleSetTenant(request: Request): Response;
 
-export { type AbpAuthEnv, type AbpAuthRuntimeOptions, type AbpCallRuntime, type AbpProxy, type AbpProxyAuth, AbpProxyError, type AbpProxyRequest, type AbpProxyResponse, type AppState, type AuthCookieConfig, type AuthCookieSettings, type AuthRuntime, CULTURE_COOKIE, DEFAULT_LOGIN_COOKIE, DEFAULT_LOGIN_COOKIE_MAX_AGE, DEFAULT_SESSION_COOKIE, DEFAULT_SESSION_COOKIE_MAX_AGE, SWITCH_COOKIE_MAX_AGE, TENANT_COOKIE, abpAuthEnvSchema, buildPolicyHeaders, callAbpWithSession, cookieAttributesOf, createAbpAuthRuntime, createAbpIdentityResolver, createAbpProxy, deriveIdentity, handleCallback, handleLogin, handleLogout, handleSetCulture, handleSetTenant, loadAppState, resolveAbpAuthEnv };
+/**
+ * 若 error 源于 TLS 证书不受信，返回对应的 OpenSSL 错误码，否则返回 null。
+ * 沿 `cause` 链与 AggregateError 的 `errors` 向下找——fetch 抛出的是包了一层的 `TypeError: fetch failed`。
+ */
+declare function tlsTrustFailureCode(error: unknown): string | null;
+/** 若 error 表示上游不可达（拒连/解析失败/超时），返回错误码，否则返回 null。查找方式同上。 */
+declare function upstreamUnreachableCode(error: unknown): string | null;
+/** 上游不可达时的处置说明；`code` 取自 {@link upstreamUnreachableCode}，`url` 为请求的上游地址。 */
+declare function upstreamUnreachableMessage(code: string, url: string): string;
+/** 证书不受信时的处置说明；`code` 取自 {@link tlsTrustFailureCode}，`url` 为请求的上游地址。 */
+declare function tlsTrustFailureMessage(code: string, url: string): string;
+interface RuntimeCaApi {
+    getCACertificates?: (kind: "default") => string[];
+    setDefaultCACertificates?: (certs: readonly string[]) => void;
+}
+type InstallExtraCaResult = "installed" | "already-installed" | "unsupported";
+/**
+ * 把一张 PEM 证书追加进进程默认 CA，让此后所有 TLS 连接（含全局 fetch）信任它。
+ * 与 `NODE_EXTRA_CA_CERTS` 不同，这条路是运行时 API（Node >= 22.15），dotenv 读完 .env 再调也来得及。
+ * 运行时没有该 API（旧 Node、Bun）时返回 "unsupported"，由调用方决定怎么提示；文件不可读则抛错。
+ * @param caApi 测试注入口，默认 `node:tls`。
+ */
+declare function installExtraCa(caFile: string, caApi?: RuntimeCaApi): InstallExtraCaResult;
+
+export { type AbpAuthEnv, type AbpAuthRuntimeOptions, type AbpCallRuntime, type AbpProxy, type AbpProxyAuth, AbpProxyError, type AbpProxyRequest, type AbpProxyResponse, type AppState, type AuthCookieConfig, type AuthCookieSettings, type AuthRuntime, CULTURE_COOKIE, DEFAULT_LOGIN_COOKIE, DEFAULT_LOGIN_COOKIE_MAX_AGE, DEFAULT_SESSION_COOKIE, DEFAULT_SESSION_COOKIE_MAX_AGE, type InstallExtraCaResult, SWITCH_COOKIE_MAX_AGE, TENANT_COOKIE, abpAuthEnvSchema, buildPolicyHeaders, callAbpWithSession, cookieAttributesOf, createAbpAuthRuntime, createAbpIdentityResolver, createAbpProxy, deriveIdentity, handleCallback, handleLogin, handleLogout, handleSetCulture, handleSetTenant, installExtraCa, loadAppState, resolveAbpAuthEnv, tlsTrustFailureCode, tlsTrustFailureMessage, upstreamUnreachableCode, upstreamUnreachableMessage };

package/dist/proxy.js

@@ -124,11 +124,34 @@ var abpAuthEnvSchema = z.object({
   postLogoutRedirectUri: z.string().url().optional(),
   sessionSecret: z.string().min(32),
   abpBaseUrl: z.string().url(),
-  debug: z.boolean().default(false)
+  debug: z.boolean().default(false),
+  /** 额外信任的 CA 证书路径（PEM）；本地 ABP 自签证书场景用，见 installExtraCa。 */
+  extraCaFile: z.string().optional()
 });
+var ENV_NAMES = {
+  issuer: "AUTH_ISSUER",
+  clientId: "AUTH_CLIENT_ID",
+  clientSecret: "AUTH_CLIENT_SECRET",
+  scope: "AUTH_SCOPE",
+  redirectUri: "AUTH_REDIRECT_URI",
+  postLogoutRedirectUri: "AUTH_POST_LOGOUT_REDIRECT_URI",
+  sessionSecret: "AUTH_SESSION_SECRET",
+  abpBaseUrl: "AUTH_ABP_BASE_URL",
+  debug: "AUTH_DEBUG",
+  extraCaFile: "AUTH_EXTRA_CA_FILE"
+};
+function describeIssues(error, raw) {
+  return error.issues.map((issue) => {
+    const field = String(issue.path[0] ?? "");
+    const name = ENV_NAMES[field] ?? field;
+    const value = raw[field];
+    const detail = value === void 0 || value === "" ? "not set" : issue.message;
+    return `${name} (${detail})`;
+  }).join(", ");
+}
 function resolveAbpAuthEnv(env, opts = {}) {
   const schema = opts.schema ?? abpAuthEnvSchema;
-  return schema.parse({
+  const raw = {
     issuer: env.AUTH_ISSUER,
     clientId: env.AUTH_CLIENT_ID,
     clientSecret: env.AUTH_CLIENT_SECRET,
@@ -137,11 +160,23 @@ function resolveAbpAuthEnv(env, opts = {}) {
     postLogoutRedirectUri: env.AUTH_POST_LOGOUT_REDIRECT_URI,
     sessionSecret: env.AUTH_SESSION_SECRET,
     abpBaseUrl: env.AUTH_ABP_BASE_URL,
-    debug: env.AUTH_DEBUG === "true"
-  });
+    debug: env.AUTH_DEBUG === "true",
+    // `AUTH_EXTRA_CA_FILE=` 的空值行等同未设置，不能拿空串去 readFileSync。
+    extraCaFile: env.AUTH_EXTRA_CA_FILE === "" ? void 0 : env.AUTH_EXTRA_CA_FILE
+  };
+  const parsed = schema.safeParse(raw);
+  if (parsed.success) return parsed.data;
+  throw new Error(
+    `auth env is missing or invalid: ${describeIssues(parsed.error, raw)}. Fill these in the project's .env (start from .env.example \u2014 each variable is documented there).`,
+    { cause: parsed.error }
+  );
 }
 
 // src/proxy/tls-trust.ts
+import { readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import tls from "tls";
 var TRUST_FAILURE_CODES = /* @__PURE__ */ new Set([
   "CERT_HAS_EXPIRED",
   "CERT_NOT_YET_VALID",
@@ -153,29 +188,65 @@ var TRUST_FAILURE_CODES = /* @__PURE__ */ new Set([
   "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
   "UNABLE_TO_VERIFY_LEAF_SIGNATURE"
 ]);
+var UNREACHABLE_CODES = /* @__PURE__ */ new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "ETIMEDOUT",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT"
+]);
 var MAX_DEPTH = 5;
 function property(value, key) {
   if (typeof value !== "object" || value === null) return void 0;
   return value[key];
 }
-function search(value, depth) {
+function search(value, depth, codes) {
   if (depth > MAX_DEPTH || typeof value !== "object" || value === null) return null;
   const code = property(value, "code");
-  if (typeof code === "string" && TRUST_FAILURE_CODES.has(code)) return code;
+  if (typeof code === "string" && codes.has(code)) return code;
   const aggregated = property(value, "errors");
   if (Array.isArray(aggregated)) {
     for (const inner of aggregated) {
-      const found = search(inner, depth + 1);
+      const found = search(inner, depth + 1, codes);
       if (found !== null) return found;
     }
   }
-  return search(property(value, "cause"), depth + 1);
+  return search(property(value, "cause"), depth + 1, codes);
 }
 function tlsTrustFailureCode(error) {
-  return search(error, 0);
+  return search(error, 0, TRUST_FAILURE_CODES);
+}
+function upstreamUnreachableCode(error) {
+  return search(error, 0, UNREACHABLE_CODES);
+}
+function upstreamUnreachableMessage(code, url) {
+  return `abp proxy: cannot reach the ABP backend (${code}) at ${new URL(url).origin}. The backend is not running, or AUTH_ABP_BASE_URL in .env points at the wrong place. Start the backend (or fix the address) and reload.`;
 }
 function tlsTrustFailureMessage(code, url) {
-  return `abp proxy: upstream TLS certificate is not trusted (${code}) at ${new URL(url).origin}. Node verifies against its own CA list and ignores the OS keychain, so a self-signed dev certificate the browser accepts still fails here. Start the server with NODE_EXTRA_CA_CERTS=<pem path>; it is read at startup, so putting it in .env has no effect.`;
+  return `abp proxy: upstream TLS certificate is not trusted (${code}) at ${new URL(url).origin}. Node verifies against its own CA list and ignores the OS keychain, so a self-signed dev certificate the browser accepts still fails here. Export the certificate and set AUTH_EXTRA_CA_FILE=<pem path> in .env (Node >= 22.15), or start the server with NODE_EXTRA_CA_CERTS=<pem path> \u2014 that one is read at startup, so .env cannot carry it.`;
+}
+function expandHome(path) {
+  if (path !== "~" && !path.startsWith("~/")) return path;
+  return join(homedir(), path.slice(2));
+}
+function installExtraCa(caFile, caApi = tls) {
+  if (typeof caApi.getCACertificates !== "function" || typeof caApi.setDefaultCACertificates !== "function") {
+    return "unsupported";
+  }
+  const resolved = expandHome(caFile);
+  let pem;
+  try {
+    pem = readFileSync(resolved, "utf8");
+  } catch (error) {
+    throw new Error(`extra CA file is not readable: ${resolved}`, { cause: error });
+  }
+  const current = caApi.getCACertificates("default");
+  if (current.includes(pem)) return "already-installed";
+  caApi.setDefaultCACertificates([...current, pem]);
+  return "installed";
 }
 
 // src/proxy/proxy.ts
@@ -277,7 +348,9 @@ function createAbpProxy(opts) {
             opts.logger?.debug("proxy retry after network error", { attempt, path: req.path });
             if (await backoff()) continue;
           }
-          const failure = tlsCode === null ? error : new Error(tlsTrustFailureMessage(tlsCode, url), { cause: error });
+          const unreachableCode = tlsCode === null ? upstreamUnreachableCode(error) : null;
+          const explanation = tlsCode !== null ? tlsTrustFailureMessage(tlsCode, url) : unreachableCode !== null ? upstreamUnreachableMessage(unreachableCode, url) : null;
+          const failure = explanation === null ? error : new Error(explanation, { cause: error });
           if (setCookies.length > 0) {
             throw new AbpProxyError("abp proxy request failed after refresh", setCookies, {
               cause: failure
@@ -330,7 +403,16 @@ function cookieAttributesOf(settings) {
   return { secure: settings.secure, sameSite: settings.sameSite };
 }
 function createAbpAuthRuntime(envRecord, opts = {}) {
-  const env = resolveAbpAuthEnv(envRecord, { schema: opts.envSchema });
+  let env;
+  try {
+    env = resolveAbpAuthEnv(envRecord, { schema: opts.envSchema });
+  } catch (error) {
+    const fallback = opts.logger ?? createLogger({ scope: "auth", config: resolveConfig({}) });
+    fallback.error("auth env resolution failed", {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    throw error;
+  }
   const cookies = {
     session: {
       ...opts.cookies?.session,
@@ -347,6 +429,20 @@ function createAbpAuthRuntime(envRecord, opts = {}) {
     scope: "auth",
     config: resolveConfig({ LOG_LEVEL: env.debug ? "debug" : "info" })
   });
+  if (env.extraCaFile !== void 0) {
+    const outcome = installExtraCa(env.extraCaFile);
+    if (outcome === "unsupported") {
+      logger.warn(
+        "AUTH_EXTRA_CA_FILE is set but this runtime lacks tls.setDefaultCACertificates (Node >= 22.15 required); falling back \u2014 start the process with NODE_EXTRA_CA_CERTS instead",
+        { caFile: env.extraCaFile }
+      );
+    } else {
+      logger.info("extra CA certificate trusted for upstream TLS", {
+        caFile: env.extraCaFile,
+        outcome
+      });
+    }
+  }
   const tokenClient = createTokenClient({
     issuer: env.issuer,
     clientId: env.clientId,
@@ -569,6 +665,11 @@ export {
   handleLogout,
   handleSetCulture,
   handleSetTenant,
+  installExtraCa,
   loadAppState,
-  resolveAbpAuthEnv
+  resolveAbpAuthEnv,
+  tlsTrustFailureCode,
+  tlsTrustFailureMessage,
+  upstreamUnreachableCode,
+  upstreamUnreachableMessage
 };

package/dist/react.d.ts

@@ -2,7 +2,7 @@ import { ReactNode } from 'react';
 import { A as ApplicationConfiguration } from './application-configuration-DhOZRqtz.js';
 import { F as FrontendCatalog, a as TranslatorOptions, T as Translator } from './translator-B3hyoZmK.js';
 import { G as GrantedPolicies } from './is-granted-C0-1wvoW.js';
-import { I as Identity } from './types-Bj0MpXtI.js';
+import { I as Identity } from './types-BeHmw3RC.js';
 import { PermissionChecker } from './permissions.js';
 import 'zod';
 

package/dist/router.d.ts

@@ -1,4 +1,4 @@
-import { I as Identity } from './types-Bj0MpXtI.js';
+import { I as Identity } from './types-BeHmw3RC.js';
 import { P as PermissionStrategy } from './is-granted-C0-1wvoW.js';
 import 'zod';
 

package/dist/{types-Bj0MpXtI.d.ts → types-BeHmw3RC.d.ts}

@@ -94,4 +94,4 @@ interface IdentityContext {
 type IdentityResolver = (session: AuthSession | null, ctx: IdentityContext) => Promise<Identity>;
 type FetchFn = typeof fetch;
 
-export { type AuthSession as A, type BeginInput as B, type CompleteInput as C, type FetchFn as F, type Handshake as H, type Identity as I, type SessionStore as S, type TokenResult as T, type IdentityResolver as a, type AuthStrategy as b, type IdentityContext as c, authSessionSchema as d, authTokensSchema as e, handshakeSchema as h };
+export { type AuthStrategy as A, type BeginInput as B, type CompleteInput as C, type FetchFn as F, type Handshake as H, type Identity as I, type SessionStore as S, type TokenResult as T, type AuthSession as a, type IdentityContext as b, type IdentityResolver as c, authSessionSchema as d, authTokensSchema as e, handshakeSchema as h };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jcoder-stack/abp-react",
-  "description": "纯 React ABP 前端框架运行时：日志、ABP 类型与 zod 解析、fetch client、认证会话、ABP 代理网关、权限、i18n、React Provider/hooks、TanStack Router 守卫；按子路径分域导出",
-  "version": "0.1.1",
+  "description": "Pure-React runtime for ABP backends: logging, ABP types with zod parsing, fetch client, auth sessions, the ABP proxy gateway, permissions, i18n, React providers/hooks, and TanStack Router guards — exported per domain via subpaths",
+  "version": "0.1.3",
   "type": "module",
   "license": "MIT",
   "repository": {