@jcoder-stack/abp-react 0.1.0

package/dist/proxy.js

@@ -0,0 +1,535 @@
+import {
+  createLogger,
+  resolveConfig
+} from "./chunk-UDMHSDXZ.js";
+import {
+  AuthError,
+  clearCookie,
+  createAuth,
+  createCodec,
+  createCookieSessionStore,
+  createTokenClient,
+  formatCultureCookie,
+  handshakeSchema,
+  oidcStrategy,
+  parseCookieHeader,
+  parseCultureCookie,
+  passwordStrategy,
+  sanitizeReturnUrl,
+  serializeCookie
+} from "./chunk-QQFH53SC.js";
+import {
+  parseApplicationConfiguration,
+  toHttpError
+} from "./chunk-HWT6PBBS.js";
+
+// src/proxy/abp-call.ts
+var TENANT_COOKIE = "__tenant";
+var CULTURE_COOKIE = ".AspNetCore.Culture";
+function buildPolicyHeaders(session, cookieHeader) {
+  const cookies = parseCookieHeader(cookieHeader);
+  const headers = {};
+  const tenant = session?.tenant ?? cookies[TENANT_COOKIE];
+  if (tenant) headers.__tenant = tenant;
+  const culture = parseCultureCookie(cookies[CULTURE_COOKIE]) ?? session?.culture;
+  if (culture) headers["Accept-Language"] = culture;
+  return headers;
+}
+var POLICY_HEADERS = /* @__PURE__ */ new Set(["__tenant", "accept-language"]);
+function callAbpWithSession(rt, session, cookieHeader, req) {
+  const policy = buildPolicyHeaders(session, cookieHeader);
+  const callerHeaders = Object.fromEntries(
+    Object.entries(req.headers ?? {}).filter(([key]) => !POLICY_HEADERS.has(key.toLowerCase()))
+  );
+  return rt.proxy.send(
+    { ...req, headers: { ...callerHeaders, ...policy } },
+    {
+      session,
+      refresh: () => session === null ? Promise.resolve(null) : rt.auth.session.refresh(session, cookieHeader)
+    }
+  );
+}
+
+// src/proxy/abp-identity.ts
+var APP_CONFIG_PATH = "/api/abp/application-configuration";
+function deriveIdentity(config, opts = {}) {
+  const user = config.currentUser;
+  const id = user.isAuthenticated ? user.id ?? null : null;
+  if (user.isAuthenticated && id === null) {
+    opts.logger?.warn("application-configuration reported an authenticated user without an id", {
+      userName: user.userName ?? void 0
+    });
+  }
+  return {
+    isAuthenticated: id !== null,
+    user: id === null ? null : {
+      id,
+      userName: user.userName ?? "",
+      email: user.email ?? void 0,
+      roles: user.roles
+    },
+    grantedPolicies: config.auth.grantedPolicies,
+    tenant: config.currentTenant.id === null ? null : { id: config.currentTenant.id, name: config.currentTenant.name }
+  };
+}
+async function loadAppState(rt, session, cookieHeader) {
+  const res = await callAbpWithSession(rt, session, cookieHeader, {
+    path: APP_CONFIG_PATH,
+    method: "GET"
+  });
+  if (res.status >= 400) {
+    let payload2;
+    if (typeof res.body === "string") {
+      try {
+        payload2 = JSON.parse(res.body);
+      } catch {
+        payload2 = res.body;
+      }
+    }
+    throw toHttpError(res.status, payload2);
+  }
+  let payload;
+  try {
+    if (typeof res.body !== "string")
+      throw new Error("non-text application-configuration response");
+    payload = JSON.parse(res.body);
+  } catch (error) {
+    rt.logger.warn("application-configuration returned non-JSON body", {
+      status: res.status,
+      error: String(error)
+    });
+    throw toHttpError(res.status, typeof res.body === "string" ? res.body : void 0);
+  }
+  const config = parseApplicationConfiguration(payload, {
+    onError: (error) => rt.logger.warn("application-configuration shape drift", { error: String(error) })
+  });
+  return {
+    config,
+    identity: deriveIdentity(config, { logger: rt.logger }),
+    setCookies: res.setCookies
+  };
+}
+function createAbpIdentityResolver(rt) {
+  return async (session, ctx) => (await loadAppState(rt(), session, ctx.cookieHeader)).identity;
+}
+
+// src/proxy/auth-env.ts
+import { z } from "zod";
+var abpAuthEnvSchema = z.object({
+  issuer: z.string().url(),
+  clientId: z.string().min(1),
+  clientSecret: z.string().optional(),
+  scope: z.string().default("openid profile"),
+  redirectUri: z.string().url(),
+  postLogoutRedirectUri: z.string().url().optional(),
+  sessionSecret: z.string().min(32),
+  abpBaseUrl: z.string().url(),
+  debug: z.boolean().default(false)
+});
+function resolveAbpAuthEnv(env, opts = {}) {
+  const schema = opts.schema ?? abpAuthEnvSchema;
+  return schema.parse({
+    issuer: env.AUTH_ISSUER,
+    clientId: env.AUTH_CLIENT_ID,
+    clientSecret: env.AUTH_CLIENT_SECRET,
+    scope: env.AUTH_SCOPE,
+    redirectUri: env.AUTH_REDIRECT_URI,
+    postLogoutRedirectUri: env.AUTH_POST_LOGOUT_REDIRECT_URI,
+    sessionSecret: env.AUTH_SESSION_SECRET,
+    abpBaseUrl: env.AUTH_ABP_BASE_URL,
+    debug: env.AUTH_DEBUG === "true"
+  });
+}
+
+// src/proxy/proxy.ts
+var AbpProxyError = class extends Error {
+  constructor(message, setCookies, opts) {
+    super(message, opts);
+    this.setCookies = setCookies;
+    this.name = "AbpProxyError";
+  }
+  setCookies;
+};
+var IDEMPOTENT = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+var isRetryableStatus = (status) => status >= 500 || status === 429;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var discardBody = (res) => res.body?.cancel().catch(() => {
+});
+var FORWARDABLE = /* @__PURE__ */ new Set([
+  "content-type",
+  "accept",
+  "accept-language",
+  "if-match",
+  "if-none-match",
+  "x-requested-with",
+  "content-disposition",
+  "__tenant"
+]);
+var EXPOSED_RESPONSE_HEADERS = [
+  "content-type",
+  "content-disposition",
+  "content-length",
+  "etag",
+  "cache-control",
+  "last-modified"
+];
+function exposeHeaders(headers) {
+  const out = new Headers();
+  for (const name of EXPOSED_RESPONSE_HEADERS) {
+    const value = headers.get(name);
+    if (value !== null) out.set(name, value);
+  }
+  return out;
+}
+function sanitizeHeaders(headers) {
+  if (headers === void 0) return {};
+  return Object.fromEntries(
+    Object.entries(headers).filter(([key]) => FORWARDABLE.has(key.toLowerCase()))
+  );
+}
+var ABSOLUTE_OR_PROTOCOL_RELATIVE = /^([a-z][a-z0-9+.-]*:)?\/\//i;
+function resolveTargetUrl(path, baseUrl) {
+  if (ABSOLUTE_OR_PROTOCOL_RELATIVE.test(path)) {
+    throw new Error("abp proxy: path escapes baseUrl");
+  }
+  const base = new URL(baseUrl);
+  const basePath = base.pathname.endsWith("/") ? base.pathname : `${base.pathname}/`;
+  const target = new URL(path.replace(/^\//, ""), new URL(basePath, base.origin));
+  if (target.origin !== base.origin || !`${target.pathname}/`.startsWith(basePath)) {
+    throw new Error("abp proxy: path escapes baseUrl");
+  }
+  return target.toString();
+}
+function createAbpProxy(opts) {
+  const fetchFn = opts.fetchFn ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const retries = opts.retry?.retries ?? 2;
+  return {
+    async send(req, auth) {
+      const method = (req.method ?? "GET").toUpperCase();
+      const maxRetries = IDEMPOTENT.has(method) ? retries : 0;
+      const url = resolveTargetUrl(req.path, opts.baseUrl);
+      const budget = opts.totalTimeoutMs === void 0 ? void 0 : AbortSignal.timeout(opts.totalTimeoutMs);
+      const stops = [req.signal, budget].filter((signal) => signal !== void 0);
+      const stopped = () => stops.some((signal) => signal.aborted);
+      const stopReason = () => stops.find((signal) => signal.aborted)?.reason;
+      let session = auth.session;
+      let setCookies = [];
+      let refreshedOnce = false;
+      let attempt = 0;
+      const backoff = async () => {
+        await sleep(2 ** attempt * 100);
+        attempt++;
+        return !stopped();
+      };
+      for (; ; ) {
+        let res;
+        try {
+          res = await fetchFn(url, {
+            method,
+            headers: {
+              ...sanitizeHeaders(req.headers),
+              ...session === null ? {} : { Authorization: `Bearer ${session.tokens.accessToken}` }
+            },
+            body: req.body,
+            signal: AbortSignal.any([...stops, AbortSignal.timeout(timeoutMs)])
+          });
+        } catch (error) {
+          if (attempt < maxRetries && !stopped()) {
+            opts.logger?.debug("proxy retry after network error", { attempt, path: req.path });
+            if (await backoff()) continue;
+          }
+          if (setCookies.length > 0) {
+            throw new AbpProxyError("abp proxy request failed after refresh", setCookies, {
+              cause: error
+            });
+          }
+          throw error;
+        }
+        if (res.status === 401 && !refreshedOnce && session?.tokens.refreshToken !== void 0) {
+          refreshedOnce = true;
+          const refreshed = await auth.refresh();
+          if (refreshed !== null) {
+            session = refreshed.session;
+            setCookies = refreshed.setCookies;
+            opts.logger?.debug("proxy replaying after refresh", { path: req.path });
+            await discardBody(res);
+            continue;
+          }
+        }
+        if (isRetryableStatus(res.status) && attempt < maxRetries && !stopped()) {
+          opts.logger?.debug("proxy retry", { attempt, status: res.status, path: req.path });
+          await discardBody(res);
+          if (await backoff()) continue;
+          if (setCookies.length > 0) {
+            throw new AbpProxyError("abp proxy request aborted after refresh", setCookies, {
+              cause: stopReason()
+            });
+          }
+          throw stopReason();
+        }
+        const contentType = res.headers.get("content-type") ?? "";
+        const isText = /^text\/|[+/]json|[+/]xml|urlencoded/i.test(contentType) || contentType === "";
+        return {
+          status: res.status,
+          headers: exposeHeaders(res.headers),
+          body: isText ? await res.text() : await res.arrayBuffer(),
+          setCookies
+        };
+      }
+    }
+  };
+}
+
+// src/proxy/auth-runtime.ts
+var DEFAULT_SESSION_COOKIE = "auth_session";
+var DEFAULT_LOGIN_COOKIE = "auth_login";
+var DEFAULT_SESSION_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
+var DEFAULT_LOGIN_COOKIE_MAX_AGE = 600;
+var SWITCH_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+function cookieAttributesOf(settings) {
+  return { secure: settings.secure, sameSite: settings.sameSite };
+}
+function createAbpAuthRuntime(envRecord, opts = {}) {
+  const env = resolveAbpAuthEnv(envRecord, { schema: opts.envSchema });
+  const cookies = {
+    session: {
+      ...opts.cookies?.session,
+      name: opts.cookies?.session?.name ?? DEFAULT_SESSION_COOKIE,
+      maxAge: opts.cookies?.session?.maxAge ?? DEFAULT_SESSION_COOKIE_MAX_AGE
+    },
+    login: {
+      ...opts.cookies?.login,
+      name: opts.cookies?.login?.name ?? DEFAULT_LOGIN_COOKIE,
+      maxAge: opts.cookies?.login?.maxAge ?? DEFAULT_LOGIN_COOKIE_MAX_AGE
+    }
+  };
+  const logger = opts.logger ?? createLogger({
+    scope: "auth",
+    config: resolveConfig({ LOG_LEVEL: env.debug ? "debug" : "info" })
+  });
+  const tokenClient = createTokenClient({
+    issuer: env.issuer,
+    clientId: env.clientId,
+    clientSecret: env.clientSecret,
+    scope: env.scope,
+    fetchFn: opts.fetchFn,
+    logger,
+    // `__tenant` 是 ABP 的多租户约定，不属于 OIDC 协议，由这层注入，协议客户端保持后端无关。
+    tenantPropagation: (tenant) => ({
+      headers: { [TENANT_COOKIE]: tenant },
+      query: { [TENANT_COOKIE]: tenant }
+    })
+  });
+  const oidc = oidcStrategy({
+    tokenClient,
+    redirectUri: env.redirectUri,
+    now: opts.now,
+    logger,
+    // 服务端寿命跟着握手 cookie 的 maxAge 走，两者错开会让延长 cookie 寿命变成静默的 handshake_expired。
+    handshakeMaxAgeSeconds: cookies.login.maxAge
+  });
+  const strategies = [];
+  if (opts.strategies?.oidc !== false) strategies.push(oidc);
+  if (opts.strategies?.password !== false)
+    strategies.push(passwordStrategy({ tokenClient, now: opts.now, logger }));
+  const proxy = createAbpProxy({
+    baseUrl: env.abpBaseUrl,
+    fetchFn: opts.fetchFn,
+    timeoutMs: opts.proxy?.timeoutMs,
+    retry: opts.proxy?.retries === void 0 ? void 0 : { retries: opts.proxy.retries },
+    totalTimeoutMs: opts.proxy?.totalTimeoutMs,
+    logger
+  });
+  const callRuntime = {
+    proxy,
+    logger,
+    get auth() {
+      return auth;
+    }
+  };
+  const auth = createAuth({
+    strategies,
+    store: createCookieSessionStore({
+      secret: env.sessionSecret,
+      cookieName: cookies.session.name,
+      maxAge: cookies.session.maxAge,
+      cookieOptions: cookieAttributesOf(cookies.session),
+      logger
+    }),
+    resolveIdentity: opts.resolveIdentity ?? createAbpIdentityResolver(() => callRuntime),
+    refreshGrant: tokenClient.refreshGrant,
+    revoke: tokenClient.revoke,
+    logger,
+    now: opts.now,
+    skewSeconds: opts.session?.skewSeconds,
+    coalesceTtlMs: opts.session?.coalesceTtlMs,
+    revokeTimeoutMs: opts.session?.revokeTimeoutMs
+  });
+  return {
+    env,
+    auth,
+    oidc,
+    proxy,
+    handshakeCodec: createCodec(env.sessionSecret, handshakeSchema, {
+      usage: "handshake",
+      onError: (error) => logger.debug("handshake cookie open failed", { error: String(error) })
+    }),
+    logger,
+    cookies,
+    postLogoutRedirectUri: opts.postLogoutRedirectUri ?? env.postLogoutRedirectUri
+  };
+}
+
+// src/proxy/auth-handlers.ts
+function originOf(value) {
+  if (value === null || value === "null") return null;
+  try {
+    return new URL(value).origin;
+  } catch {
+    return null;
+  }
+}
+function isSameSiteRequest(request) {
+  const fetchSite = request.headers.get("sec-fetch-site");
+  if (fetchSite !== null) return fetchSite === "same-origin" || fetchSite === "none";
+  const selfOrigin = new URL(request.url).origin;
+  const origin = originOf(request.headers.get("origin"));
+  if (origin !== null) return origin === selfOrigin;
+  const referer = originOf(request.headers.get("referer"));
+  if (referer !== null) return referer === selfOrigin;
+  return true;
+}
+var CROSS_SITE_RESPONSE = () => new Response("cross-site request rejected", { status: 403 });
+async function handleLogin(request, rt) {
+  const url = new URL(request.url);
+  const cookies = parseCookieHeader(request.headers.get("cookie"));
+  const { redirectUrl, handshake } = await rt.oidc.begin({
+    returnUrl: sanitizeReturnUrl(url.searchParams.get("returnUrl")),
+    tenant: cookies[TENANT_COOKIE] ?? null
+  });
+  const headers = new Headers({ Location: redirectUrl });
+  headers.append(
+    "Set-Cookie",
+    serializeCookie(rt.cookies.login.name, await rt.handshakeCodec.seal(handshake), {
+      ...cookieAttributesOf(rt.cookies.login),
+      maxAge: rt.cookies.login.maxAge
+    })
+  );
+  return new Response(null, { status: 302, headers });
+}
+function callbackFailure(rt, code) {
+  const headers = new Headers({ Location: `/login?error=${code}` });
+  headers.append(
+    "Set-Cookie",
+    clearCookie(rt.cookies.login.name, cookieAttributesOf(rt.cookies.login))
+  );
+  return new Response(null, { status: 302, headers });
+}
+async function handleCallback(request, rt) {
+  const url = new URL(request.url);
+  const cookies = parseCookieHeader(request.headers.get("cookie"));
+  const sealed = cookies[rt.cookies.login.name];
+  const handshake = sealed === void 0 ? null : await rt.handshakeCodec.open(sealed);
+  if (handshake === null) return callbackFailure(rt, "session_open_failed");
+  try {
+    const result = await rt.oidc.complete({
+      kind: "callback",
+      params: url.searchParams,
+      handshake
+    });
+    const setCookies = await rt.auth.session.establish(result, {
+      tenant: cookies[TENANT_COOKIE] ?? null,
+      culture: parseCultureCookie(cookies[CULTURE_COOKIE]),
+      cookieHeader: request.headers.get("cookie")
+    });
+    const headers = new Headers({ Location: sanitizeReturnUrl(handshake.returnUrl) });
+    for (const cookie of setCookies) headers.append("Set-Cookie", cookie);
+    headers.append(
+      "Set-Cookie",
+      clearCookie(rt.cookies.login.name, cookieAttributesOf(rt.cookies.login))
+    );
+    return new Response(null, { status: 302, headers });
+  } catch (error) {
+    const code = error instanceof AuthError ? error.code : "exchange_failed";
+    rt.logger.warn("login callback failed", { code });
+    return callbackFailure(rt, code);
+  }
+}
+async function handleLogout(request, rt) {
+  if (!isSameSiteRequest(request)) return CROSS_SITE_RESPONSE();
+  const cookieHeader = request.headers.get("cookie");
+  const session = await rt.auth.session.current(cookieHeader);
+  let location = rt.postLogoutRedirectUri ?? "/";
+  try {
+    location = await rt.oidc.logoutUrl({
+      idToken: session?.tokens.idToken,
+      postLogoutRedirectUri: rt.postLogoutRedirectUri
+    }) ?? location;
+  } catch {
+  }
+  const headers = new Headers({ Location: location });
+  for (const cookie of await rt.auth.session.destroy(cookieHeader)) {
+    headers.append("Set-Cookie", cookie);
+  }
+  return new Response(null, { status: 302, headers });
+}
+var TENANT_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+var CULTURE_PATTERN = /^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8}){0,4}$/;
+function handleSetCulture(request) {
+  if (!isSameSiteRequest(request)) return CROSS_SITE_RESPONSE();
+  const url = new URL(request.url);
+  const culture = url.searchParams.get("culture");
+  if (!culture) return new Response("culture is required", { status: 400 });
+  if (!CULTURE_PATTERN.test(culture)) {
+    return new Response("culture is not a valid BCP-47 tag", { status: 400 });
+  }
+  const headers = new Headers({ Location: sanitizeReturnUrl(url.searchParams.get("returnUrl")) });
+  headers.append(
+    "Set-Cookie",
+    serializeCookie(CULTURE_COOKIE, formatCultureCookie(culture), {
+      httpOnly: false,
+      maxAge: SWITCH_COOKIE_MAX_AGE
+    })
+  );
+  return new Response(null, { status: 302, headers });
+}
+function handleSetTenant(request) {
+  if (!isSameSiteRequest(request)) return CROSS_SITE_RESPONSE();
+  const url = new URL(request.url);
+  const tenant = url.searchParams.get("tenant");
+  if (tenant !== null && tenant !== "" && !TENANT_PATTERN.test(tenant)) {
+    return new Response("tenant is not a valid identifier", { status: 400 });
+  }
+  const headers = new Headers({ Location: sanitizeReturnUrl(url.searchParams.get("returnUrl")) });
+  headers.append(
+    "Set-Cookie",
+    tenant ? serializeCookie(TENANT_COOKIE, tenant, { httpOnly: false, maxAge: SWITCH_COOKIE_MAX_AGE }) : clearCookie(TENANT_COOKIE, { httpOnly: false })
+  );
+  return new Response(null, { status: 302, headers });
+}
+export {
+  AbpProxyError,
+  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
+};

package/dist/react.d.ts

@@ -0,0 +1,125 @@
+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 { PermissionChecker } from './permissions.js';
+import 'zod';
+
+interface AppConfigProviderProps {
+    config: ApplicationConfiguration;
+    messages?: FrontendCatalog;
+    fallbackCulture?: string;
+    /** 缺 key 回调；始终读最新一次传入的实现，可安全写成内联箭头函数。 */
+    onMissingKey?: (key: string) => void;
+    /** translator 工厂注入点（如换 ICU 引擎）；只在 translator 重建时读取，不必引用稳定。 */
+    createTranslator?: (opts: TranslatorOptions) => Translator;
+    children: ReactNode;
+}
+/** app-config（localization/settings/features）Provider；auth 相关内容走 SessionProvider。 */
+declare function AppConfigProvider(props: AppConfigProviderProps): ReactNode;
+/** 解析后的 ABP application-configuration。 */
+declare function useAppConfig(): ApplicationConfiguration;
+/** 可调用的本地化助手：L(key, ...args)、L.plural、L.has。 */
+interface Localize {
+    (key: string, ...args: unknown[]): string;
+    plural(key: string, count: number, ...args: unknown[]): string;
+    has(key: string): boolean;
+}
+declare function useLocalization(): Localize;
+/** 当前 culture 名（如 "en"、"zh-Hans"）。 */
+declare function useCulture(): string;
+declare function useSetting(name: string): string | undefined;
+declare function useSettingBoolean(name: string): boolean;
+declare function useFeature(name: string): string | undefined;
+declare function useFeatureEnabled(name: string): boolean;
+interface FeatureGuardProps {
+    feature: string;
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+/** ABP feature 开启时渲染 children，否则 fallback（默认 null）。 */
+declare function FeatureGuard(props: FeatureGuardProps): ReactNode;
+
+/** A declarative menu node; pruned by buildMenu against permissions / features / auth. */
+interface MenuItem<To extends string = string> {
+    key: string;
+    label: string;
+    to?: To;
+    icon?: ReactNode;
+    order?: number;
+    requiredPolicy?: string | string[];
+    requiredFeature?: string;
+    requireAuth?: boolean;
+    children?: MenuItem<To>[];
+}
+/** Inputs buildMenu prunes against: granted policies, feature values, and auth state. */
+interface MenuBuildContext {
+    grantedPolicies: GrantedPolicies;
+    features?: Record<string, string | undefined>;
+    isAuthenticated?: boolean;
+}
+/** Prune a menu tree by permissions/features/auth; parents with no link and no surviving children are dropped; a linked parent that loses every child comes back without a `children` key at all, so renderers never draw an empty expander; sorted by order ascending. Pure. */
+declare function buildMenu<To extends string>(items: MenuItem<To>[], ctx: MenuBuildContext): MenuItem<To>[];
+/** Statically concatenate multiple menu lists into one (v1: no dedup). */
+declare function mergeMenu<To extends string>(...lists: MenuItem<To>[][]): MenuItem<To>[];
+/** Depth-first: the ancestor chain (inclusive) of the exact `to === pathname` match, else the longest `to` prefix match, else []. Pure. */
+declare function findBreadcrumbs<To extends string>(items: MenuItem<To>[], pathname: string): MenuItem<To>[];
+/** The breadcrumb chain for the given pathname against a menu tree; pass the pathname from your router. Memoized. */
+declare function useBreadcrumbs<To extends string>(items: MenuItem<To>[], pathname: string): MenuItem<To>[];
+/** The pruned menu tree for the given config, built against the current ABP context. Memoized. */
+declare function useMenu<To extends string>(items: MenuItem<To>[]): MenuItem<To>[];
+
+/** 会话上下文值：Identity + 派生的状态/权限检查 + 服务端重取。 */
+interface SessionValue {
+    identity: Identity;
+    status: "authenticated" | "anonymous";
+    can: PermissionChecker;
+    /** 从服务端重取身份；被更新的注水身份或更晚发起的 reload 超越时，本次结果被丢弃。 */
+    reload(): Promise<void>;
+}
+interface SessionProviderProps {
+    /** SSR 注水的初始身份；prop 变化（路由 invalidate）时跟随。 */
+    identity: Identity;
+    /** reload 的取数通道（应用注入 getIdentityFn 这类 server fn）。 */
+    fetchIdentity?: () => Promise<Identity>;
+    children: ReactNode;
+}
+/** 以 Identity 为中心的会话 Provider；token 永远不会出现在这棵树里。 */
+declare function SessionProvider(props: SessionProviderProps): ReactNode;
+/** 读会话上下文；在 <SessionProvider> 外使用时抛错。 */
+declare function useSession(): SessionValue;
+/** 当前用户（匿名时 null）。 */
+declare function useCurrentUser(): Identity["user"];
+/** 能力转述表（policy → boolean）；单点检查用 usePermission。 */
+declare function useGrantedPolicies(): Record<string, boolean>;
+declare function usePermissionChecker(): PermissionChecker;
+/** 单个 policy（或数组=全部）是否被授予。 */
+declare function usePermission(policy: string | string[]): boolean;
+interface PermissionGuardBaseProps {
+    requireAuth?: boolean;
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+/** 权限检查三选一（省略三者则只剩 requireAuth 门槛）；`never` 分支让同传两个在编译期即被拒。 */
+type PermissionGuardProps = PermissionGuardBaseProps & ({
+    policy: string | string[];
+    all?: never;
+    any?: never;
+} | {
+    policy?: never;
+    all: string[];
+    any?: never;
+} | {
+    policy?: never;
+    all?: never;
+    any: string[];
+} | {
+    policy?: never;
+    all?: never;
+    any?: never;
+});
+/** 权限检查通过时渲染 children，否则 fallback（默认 null）。feature 门槛请外套 FeatureGuard。 */
+declare function PermissionGuard(props: PermissionGuardProps): ReactNode;
+
+export { AppConfigProvider, type AppConfigProviderProps, FeatureGuard, type FeatureGuardProps, type Localize, type MenuBuildContext, type MenuItem, PermissionGuard, type PermissionGuardProps, SessionProvider, type SessionProviderProps, type SessionValue, buildMenu, findBreadcrumbs, mergeMenu, useAppConfig, useBreadcrumbs, useCulture, useCurrentUser, useFeature, useFeatureEnabled, useGrantedPolicies, useLocalization, useMenu, usePermission, usePermissionChecker, useSession, useSetting, useSettingBoolean };