@eifi1/ui-kit 0.54.0 → 0.55.0

package/dist/lib/session-refresh.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/session-refresh.ts"],"sourcesContent":["/**\n * Renewing a session when the access token runs out: the client half of\n * docs/auth-harmonization.md §11 (round 0.34 C7, KS U6), lifted from keksdose's\n * `refreshOnce` (Kurvenschmiede's is the same, line for line) and corrected where the\n * three apps' reviews found it wrong. It ends kastlan's sign-out over a network blip (B3).\n *\n * THE KIT OWNS THE RULE, THE APP OWNS THE CALL (§11.2, decision 1). The kit decides when\n * to refresh, who waits, what a failure means, when the session is over and whether a\n * renewal may still be stored. The app keeps its endpoint, its token storage, its\n * sign-out and where it navigates, and hands them in as {@link SessionRefreshOptions}.\n *\n *  - **One flight per tab** (decision 2): every 401 that arrives while a refresh runs\n *    waits for it, and so does `session.refresh()` (kastlan's boot).\n *  - **Definitive** (decision 3): the device holds no refresh token (`refresh` resolves\n *    `null`), the refresh answers 401 or 403, or the request replayed with the fresh\n *    token gets a 401 again. Only then does the app sign out (`onEnded`), and only while\n *    that session is still the app's.\n *  - **Transient** (decision 4): everything else. The session stays: nothing is signed\n *    out, stored or redirected, and the kit shows nothing. The request rejects with its\n *    OWN 401, marked ({@link isTransientRefreshFailure}), so the app's message can say\n *    \"can't reach the server\" instead of \"not signed in\".\n *  - **Retries only where waiting helps** (decision 5, KS 7): no answer, the kit's own\n *    timeout, 408, 429 and 5xx get up to three attempts, 1 s and then 3 s apart, each cut\n *    off after 15 s; none while the browser reports itself offline. Any other answer, and\n *    anything that is not an HTTP error, ends the flight at the first attempt.\n *  - **A stale session is never written back** (§11.7, ka 3, KS 3, KS 4): every request\n *    is stamped with `currentToken()` when it goes out, and every flight notes it when it\n *    starts. A 401 to a request sent with an older token replays it with the app's token\n *    now, without a refresh; a flight whose session changed while it ran stores nothing\n *    and ends nothing. The access token is the session's identity because every change\n *    the apps make replaces it — a refresh, another tab, a company switch, a password\n *    change, a sign-in, a demo start, a sign-out.\n *\n * Framework-free like `server-wake.ts`: {@link attachSessionRefresh} takes the app's\n * axios instance as an ARGUMENT, typed structurally, so the kit never imports axios.\n */\n\nimport type { AxiosLikeInstance, ServerWakeAxiosConfig } from \"./server-wake\";\nimport { httpStatusOf } from \"./http-status\";\n\n/** What the app's `refresh` resolves: the new access token, plus whatever its `store`\n *  needs (its refresh token, the user). */\nexport interface SessionRenewal {\n  /** The new access token; the waiting requests are replayed with it. */\n  token: string;\n  /**\n   * `false`: store the renewal, but replay nothing — each waiting request rejects with\n   * its 401, unmarked. kastlan's refresh can land in another company (§11.5, ka 3): a\n   * waiting write, such as the handover's `POST /sync`, must not be replayed into it.\n   */\n  replay?: false;\n}\n\n/** What the app hands {@link createSessionRefresh} (§11.4). */\nexport interface SessionRefreshOptions<R extends SessionRenewal> {\n  /**\n   * The app's own `POST /auth/refresh`, on a BARE client — never the instance the kit is\n   * attached to, so the refresh cannot re-enter the interceptor. It **writes nothing**:\n   * the kit hands the answer to `store`, and only while the session is unchanged.\n   *\n   * Resolves the answer as a renewal, or `null` when the device holds no refresh token.\n   * Throws on failure, and the kit classifies the throw: a 401 or 403 is definitive; no\n   * answer (an axios error without a `response`), the kit's own timeout, 408, 429 and\n   * 5xx are transient and retried; any other answer, and anything that is not an HTTP\n   * error (a bug in this function), is transient and not retried. The status is read\n   * from `err.response.status` (axios), `err.status` or `err.statusCode`.\n   *\n   * `signal` aborts when the attempt runs past `timeoutMs`; pass it to the request.\n   */\n  refresh: (signal: AbortSignal) => Promise<R | null>;\n  /** Writes the renewal: the tokens and the user (a missing refresh token keeps the\n   *  stored one). Called only while the session the flight renews is still the app's,\n   *  and before the waiting requests are replayed — so it writes the token SYNCHRONOUSLY\n   *  where `currentToken` reads it: the replay goes through the app's own request\n   *  interceptor again, and is stamped then. A throw is the app's bug: the waiting\n   *  requests and `session.refresh()` reject with it. */\n  store: (renewal: R) => void;\n  /** The access token the app sends NOW, read where its request interceptor reads it;\n   *  `null` when there is none. */\n  currentToken: () => string | null;\n  /** Whether the session is a demo: a demo's 401 ends it, with no refresh tried\n   *  (landing-demo §5.5). */\n  isDemo: () => boolean;\n  /**\n   * The session is over: drop the tokens and the user, then navigate — `/demo/ended` for\n   * a demo, else the sign-in with the page it came from (auth §5.2). Called once per\n   * session, however many requests found out (KS 8), and never by `session.refresh()`.\n   */\n  onEnded: (ended: { demo: boolean }) => void;\n  /** Whether a URL is a signed-out step, whose 401 judges the form and never the\n   *  session. Replaces the default list, {@link isSignedOutStep}. */\n  isSignedOutStep?: (url: string) => boolean;\n  /** Attempts for a refresh that got no answer, timed out, or got a 408, 429 or 5xx.\n   *  Default 3. */\n  attempts?: number;\n  /** The waits before the second and later attempts; the last one repeats. Default\n   *  `[1000, 3000]`. */\n  backoffMs?: readonly number[];\n  /** Each attempt is cut off after this, and its `signal` aborted. Default 15 000. */\n  timeoutMs?: number;\n}\n\n/** What `session.refresh()` resolves (§11.4), by `result`:\n *\n * | `result` | When | What the kit has done |\n * |---|---|---|\n * | `\"renewed\"` | a renewal while the session was unchanged | `store(renewal)` |\n * | `\"ended\"` | definitive | nothing; `onEnded` only for requests that waited on the same flight |\n * | `\"transient\"` | transient | nothing |\n * | `\"changed\"` | the session changed while it ran | nothing; read the app's own state |\n */\nexport type SessionRefreshOutcome<R extends SessionRenewal = SessionRenewal> =\n  { result: \"renewed\"; renewal: R } | { result: \"ended\" } | { result: \"transient\" } | { result: \"changed\" };\n\n/** The flight {@link createSessionRefresh} makes; {@link attachSessionRefresh} hooks it\n *  to an axios instance. */\nexport interface SessionRefresh<R extends SessionRenewal = SessionRenewal> {\n  /**\n   * The same flight, for a caller outside the interceptor — kastlan's boot. Joins a\n   * running flight, or starts one. Never calls `onEnded`: the caller decides what an\n   * `\"ended\"` means for it.\n   */\n  refresh(): Promise<SessionRefreshOutcome<R>>;\n}\n\n// ── The signed-out steps ──────────────────────────────────────────────────────\n\n/**\n * Every `/auth/` call made without a session, the union of the three apps' lists\n * (§11.3): signing in (with its `2fa` and `set-password` steps, and a passkey's), up,\n * into a demo, a password reset, the verification link, the invitation check, the email\n * change's confirmation link, and the refresh itself. NOT `resend-verification` (KS 1):\n * in keksdose and Kurvenschmiede it needs a session; in kastlan it never answers 401.\n */\nconst SIGNED_OUT_STEPS = [\n  \"login\",\n  \"passkey/login\",\n  \"register\",\n  \"demo-session\",\n  \"password-reset\",\n  \"verify-email\",\n  \"invitations/check\",\n  \"me/email/confirm\",\n  \"refresh\",\n] as const;\n\n/**\n * Whether a request's URL is a signed-out step — the kit's default list (§11.3), exported\n * for an app's tests and for an app's own `isSignedOutStep` that adds to it.\n *\n * **Whole steps only** (KS 2): the part of the path after its `auth/` segment, without\n * the query string, is the entry itself or starts with the entry and a `/`. So\n * `login/2fa` is `login`'s, but `register` never catches `/auth/passkey/register/begin`\n * (adding a passkey, which needs a session), `invitations/check` never\n * `/auth/invitations/accept`, and `me/email/confirm` never `/auth/me/email`. Relative and\n * absolute URLs alike; a URL with no `auth` segment is no step.\n */\nexport function isSignedOutStep(url: string): boolean {\n  const path = url.replace(/[?#].*$/s, \"\").replace(/^([a-z][a-z\\d+.-]*:)?\\/\\/[^/]*/i, \"\");\n  const segments = path.split(\"/\");\n  const at = segments.indexOf(\"auth\");\n  if (at < 0) return false;\n  const step = segments.slice(at + 1).join(\"/\");\n  return SIGNED_OUT_STEPS.some((entry) => step === entry || step.startsWith(`${entry}/`));\n}\n\n// ── The marker ────────────────────────────────────────────────────────────────\n\n/** On the request's own axios error, after a transient failure (decision 8). A\n *  `Symbol.for` key: shared by every copy of the kit in a page, and left out of\n *  `JSON.stringify`, so a log that serialises the error doesn't print it (kk 2). */\nconst TRANSIENT = Symbol.for(\"@eifi1/ui-kit:session-refresh.transient\");\n\n/**\n * Whether a request was refused because the refresh behind it failed TRANSIENTLY —\n * offline, a timeout, a 5xx — and not because the session is over (decision 8). The\n * error is the request's own 401, `err.response?.status` and every check an app already\n * has keep working; this reads the mark the kit put on it, so the app's message can say\n * \"can't reach the server\" instead of \"not signed in\". Read it FIRST: keksdose's sync\n * chip, kastlan's handover sync and Kurvenschmiede's `apiErrorMessage` count it as\n * offline (§11.5).\n *\n * Not the refresh's own error: its config carries the refresh token in its body, into any\n * log or crash report that keeps the error.\n */\nexport function isTransientRefreshFailure(error: unknown): boolean {\n  return typeof error === \"object\" && error !== null && (error as Record<symbol, unknown>)[TRANSIENT] === true;\n}\n\n// ── The flight ────────────────────────────────────────────────────────────────\n\n/** A flight's result, as the interceptor needs it: `\"ended\"` keeps the session it ended. */\ntype Flight<R extends SessionRenewal> =\n  | { result: \"renewed\"; renewal: R }\n  | { result: \"ended\"; token: string | null }\n  | { result: \"transient\" }\n  | { result: \"changed\" };\n\n/** What one attempt came to. */\ntype Attempt<R> = { renewal: R } | \"definitive\" | \"retry\" | \"transient\";\n\n/** What {@link attachSessionRefresh} needs of a session. Kept off the public interface:\n *  only what {@link createSessionRefresh} made can be attached. */\ninterface Engine {\n  token(): string | null;\n  isDemo(): boolean;\n  isSignedOutStep(url: string): boolean;\n  join(): Promise<Flight<SessionRenewal>>;\n  end(token: string | null, demo: boolean): void;\n}\n\nconst engines = new WeakMap<SessionRefresh<SessionRenewal>, Engine>();\n\n/** The kit's own timeout, told apart from anything the app's `refresh` throws. */\nconst TIMED_OUT = Symbol(\"timed out\");\n\nfunction isOffline(): boolean {\n  return typeof navigator !== \"undefined\" && navigator.onLine === false;\n}\n\n/** A refresh's throw, classified (§11.4). The status is read where `isRateLimited` reads\n *  it — `httpStatusOf`, one probe for axios, ofetch and Node errors (DUP-11). */\nfunction classify(error: unknown): \"definitive\" | \"retry\" | \"transient\" {\n  if (error === TIMED_OUT) return \"retry\";\n  if (typeof error !== \"object\" || error === null) return \"transient\";\n  const status = httpStatusOf(error);\n  if (status === undefined) {\n    // No answer: axios marks its own errors, and one without a response never reached a\n    // server (offline, DNS, CORS, its own timeout). Anything else is a bug in `refresh`.\n    return (error as { isAxiosError?: unknown }).isAxiosError === true ? \"retry\" : \"transient\";\n  }\n  if (status === 401 || status === 403) return \"definitive\";\n  if (status === 408 || status === 429 || status >= 500) return \"retry\";\n  return \"transient\";\n}\n\nconst sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));\n\n/**\n * Make the flight: `const session = createSessionRefresh({ refresh, store, currentToken,\n * isDemo, onEnded })`, then {@link attachSessionRefresh}`(api, session)`. One per tab.\n */\nexport function createSessionRefresh<R extends SessionRenewal>(options: SessionRefreshOptions<R>): SessionRefresh<R> {\n  const { attempts = 3, backoffMs = [1000, 3000], timeoutMs = 15_000 } = options;\n  // An empty string is no token: the stamp and the flight compare tokens, and \"\" against\n  // `null` must not read as a change of session.\n  const token = () => options.currentToken() || null;\n\n  /** One call of the app's `refresh`, cut off after `timeoutMs` even if it ignores the\n   *  signal. */\n  const attempt = async (): Promise<Attempt<R>> => {\n    const controller = new AbortController();\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    const timeout = new Promise<never>((_, reject) => {\n      timer = setTimeout(() => {\n        reject(TIMED_OUT);\n        controller.abort();\n      }, timeoutMs);\n    });\n    try {\n      // Through `then`, so a `refresh` that throws before it returns a promise is\n      // classified like one that rejects.\n      const renewal = await Promise.race([Promise.resolve().then(() => options.refresh(controller.signal)), timeout]);\n      return renewal ? { renewal } : \"definitive\";\n    } catch (error) {\n      return classify(error);\n    } finally {\n      clearTimeout(timer);\n    }\n  };\n\n  const run = async (): Promise<Flight<R>> => {\n    // The session this flight renews (§11.3 step 5).\n    const noted = token();\n    const changed = () => token() !== noted;\n    let outcome = await attempt();\n    for (let made = 1; outcome === \"retry\"; made += 1) {\n      // No further attempt while the browser says it is offline, nor for a session that\n      // is no longer the app's: whatever the answer, it would be \"changed\".\n      if (made >= attempts || isOffline() || changed()) break;\n      await sleep(backoffMs[made - 1] ?? backoffMs[backoffMs.length - 1] ?? 0);\n      if (isOffline() || changed()) break;\n      outcome = await attempt();\n    }\n    // A late answer never writes the old session back over a sign-out, a demo start or a\n    // password change, and the old session's refusal never signs anyone out (KS 3).\n    if (changed()) return { result: \"changed\" };\n    if (outcome === \"definitive\") return { result: \"ended\", token: noted };\n    if (outcome === \"retry\" || outcome === \"transient\") return { result: \"transient\" };\n    options.store(outcome.renewal);\n    return { result: \"renewed\", renewal: outcome.renewal };\n  };\n\n  let flight: Promise<Flight<R>> | null = null;\n  const join = () => {\n    // Cleared before any waiter resumes (`finally` settles first), so a waiter that\n    // needs another flight starts a new one.\n    flight ??= run().finally(() => {\n      flight = null;\n    });\n    return flight;\n  };\n\n  /** The session `onEnded` was last called for: once per session (KS 8). */\n  let ended: { token: string | null } | undefined;\n\n  const session: SessionRefresh<R> = {\n    async refresh() {\n      const outcome = await join();\n      return outcome.result === \"ended\" ? { result: \"ended\" } : outcome;\n    },\n  };\n  engines.set(session, {\n    token,\n    isDemo: () => options.isDemo(),\n    isSignedOutStep: options.isSignedOutStep ?? isSignedOutStep,\n    join,\n    end(endedToken, demo) {\n      if (ended && ended.token === endedToken) return;\n      ended = { token: endedToken };\n      options.onEnded({ demo });\n    },\n  });\n  return session;\n}\n\n// ── axios ─────────────────────────────────────────────────────────────────────\n\n/** The config fields the kit reads and writes — what axios's request config has. */\ninterface SessionRefreshAxiosConfig extends ServerWakeAxiosConfig {\n  /** axios's `AxiosHeaders` (written through its `set`), or a plain record. */\n  headers?: unknown;\n}\n\n/** An axios instance, structurally: {@link AxiosLikeInstance}, plus `request(config)` for\n *  the replay. `axios.create()`'s result fits it as is. `NoInfer`, because axios's\n *  `request` takes the WIDER `AxiosRequestConfig`: inferred from there, the config type\n *  no longer fits the interceptors, which hand out `InternalAxiosRequestConfig`. */\ninterface SessionRefreshInstance<\n  C extends SessionRefreshAxiosConfig,\n  R extends { config: C },\n> extends AxiosLikeInstance<C, R> {\n  request(config: NoInfer<C>): Promise<unknown>;\n}\n\n/** The keys the kit keeps on a request's config, as `attachServerWake` keeps\n *  `_serverWake`: never a header. Plain string keys holding primitives, because axios\n *  copies the config on a replay (`mergeConfig`) and a symbol key would be dropped. */\nconst STAMP = \"_sessionStamp\";\nconst REFRESHED = \"_sessionRefreshed\";\nconst RESTAMPED = \"_sessionRestamped\";\ntype Marked = {\n  /** `currentToken()` when the request went out. */\n  [STAMP]?: string | null;\n  /** Replayed after a refresh: a 401 now is definitive (decision 3). */\n  [REFRESHED]?: boolean;\n  /** Replayed because it was sent with an older token: once for this reason. */\n  [RESTAMPED]?: boolean;\n};\n\n/** `Authorization: Bearer <token>` on a config about to be replayed. The app's own\n *  request interceptor runs again on the replay and writes the same, from the same\n *  source. */\nfunction authorize(config: SessionRefreshAxiosConfig, token: string): void {\n  const value = `Bearer ${token}`;\n  const headers = config.headers;\n  if (typeof headers !== \"object\" || headers === null) {\n    config.headers = { Authorization: value };\n  } else if (typeof (headers as { set?: unknown }).set === \"function\") {\n    (headers as { set(name: string, value: string): unknown }).set(\"Authorization\", value);\n  } else {\n    (headers as Record<string, unknown>).Authorization = value;\n  }\n}\n\n/**\n * Hook a session to an axios instance: `attachSessionRefresh(api, session)`. Adds a\n * request interceptor (the stamp) and a response interceptor (the 401), and returns a\n * function that ejects both.\n *\n * Attach it LAST (§11.3, kk 4): after `attachServerWake`, which asks to be first, and\n * after the app's own response interceptors (logging, a watchdog of its own). axios runs\n * response interceptors in the order they were added, and each of those must see the 401\n * settle before the refresh is awaited. The request side's order does not matter.\n *\n * On a 401, in this order (§11.3):\n *\n *  1. a signed-out step → reject, nothing else;\n *  2. sent with an older token → replayed with the app's token now, with no refresh, once\n *     for this reason; with no token now, reject;\n *  3. a demo → `onEnded({ demo: true })`, reject;\n *  4. already replayed after a refresh → definitive: `onEnded({ demo: false })`, reject;\n *  5. otherwise it joins the flight, or starts it. A renewal replays it once with the\n *     renewal's token (`replay: false`: rejects, unmarked); definitive ends the session;\n *     transient rejects, marked; a session that changed meanwhile sends it through step\n *     2 again.\n *\n * Every rejection is the request's OWN error. Any other status passes through untouched.\n */\nexport function attachSessionRefresh<C extends SessionRefreshAxiosConfig, R extends { config: C }>(\n  instance: SessionRefreshInstance<C, R>,\n  session: SessionRefresh<SessionRenewal>,\n): () => void {\n  const engine = engines.get(session);\n  if (!engine) throw new TypeError(\"attachSessionRefresh takes the session createSessionRefresh made\");\n\n  const onUnauthorized = async (error: object, config: C & Marked): Promise<unknown> => {\n    if (engine.isSignedOutStep(config.url ?? \"\")) throw error;\n    // A config the kit never stamped (sent before it was attached) counts as current.\n    const stamp = config[STAMP] === undefined ? engine.token() : config[STAMP];\n    const replay = (token: string) => {\n      authorize(config, token);\n      return instance.request(config);\n    };\n    for (;;) {\n      const now = engine.token();\n      // 2. The session it was sent for is gone, and whatever ended it has already done\n      // what follows (ka 3, KS 3, KS 4).\n      if (stamp !== now) {\n        if (now === null || config[RESTAMPED]) throw error;\n        config[RESTAMPED] = true;\n        return replay(now);\n      }\n      // 3. A demo has nothing to refresh: its token lives as long as its account\n      // (landing-demo §5.5).\n      if (engine.isDemo()) {\n        engine.end(now, true);\n        throw error;\n      }\n      // 4. A replay for an older token doesn't count here: the app's current token may\n      // simply have expired too, which needs a refresh, not a sign-out.\n      if (config[REFRESHED]) {\n        engine.end(now, false);\n        throw error;\n      }\n      // 5. The flight.\n      const flight = await engine.join();\n      if (flight.result === \"changed\") continue;\n      if (flight.result === \"ended\") {\n        engine.end(flight.token, false);\n        throw error;\n      }\n      if (flight.result === \"transient\") {\n        (error as Record<symbol, unknown>)[TRANSIENT] = true;\n        throw error;\n      }\n      if (flight.renewal.replay === false) throw error;\n      config[REFRESHED] = true;\n      return replay(flight.renewal.token);\n    }\n  };\n\n  const request = instance.interceptors.request.use(\n    (config) => {\n      (config as C & Marked)[STAMP] = engine.token();\n      return config;\n    },\n    (error) => Promise.reject(error),\n  );\n  const response = instance.interceptors.response.use(\n    (res) => res,\n    (error) => {\n      const failed = error as { config?: C & Marked; response?: { status?: unknown } } | null;\n      if (failed?.response?.status !== 401 || !failed.config) return Promise.reject(error);\n      return onUnauthorized(failed, failed.config);\n    },\n  );\n  return () => {\n    instance.interceptors.request.eject(request);\n    instance.interceptors.response.eject(response);\n  };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/lib/session-refresh.ts"],"sourcesContent":["/**\n * Renewing a session when the access token runs out: the client half of\n * docs/auth-harmonization.md §11 (round 0.34 C7, KS U6), lifted from keksdose's\n * `refreshOnce` (Kurvenschmiede's is the same, line for line) and corrected where the\n * three apps' reviews found it wrong. It ends kastlan's sign-out over a network blip (B3).\n *\n * THE KIT OWNS THE RULE, THE APP OWNS THE CALL (§11.2, decision 1). The kit decides when\n * to refresh, who waits, what a failure means, when the session is over and whether a\n * renewal may still be stored. The app keeps its endpoint, its token storage, its\n * sign-out and where it navigates, and hands them in as {@link SessionRefreshOptions}.\n *\n *  - **One flight per tab** (decision 2): every 401 that arrives while a refresh runs\n *    waits for it, and so does `session.refresh()` (kastlan's boot).\n *  - **Definitive** (decision 3): the device holds no refresh token (`refresh` resolves\n *    `null`), the refresh answers 401 or 403, or the request replayed with the fresh\n *    token gets a 401 again. Only then does the app sign out (`onEnded`), and only while\n *    that session is still the app's.\n *  - **Transient** (decision 4): everything else. The session stays: nothing is signed\n *    out, stored or redirected, and the kit shows nothing. The request rejects with its\n *    OWN 401, marked ({@link isTransientRefreshFailure}), so the app's message can say\n *    \"can't reach the server\" instead of \"not signed in\".\n *  - **Retries only where waiting helps** (decision 5, KS 7): no answer, the kit's own\n *    timeout, 408, 429 and 5xx get up to three attempts, 1 s and then 3 s apart, each cut\n *    off after 15 s; none while the browser reports itself offline. Any other answer, and\n *    anything that is not an HTTP error, ends the flight at the first attempt.\n *  - **A stale session is never written back** (§11.7, ka 3, KS 3, KS 4): every request\n *    is stamped with `currentToken()` when it goes out, and every flight notes it when it\n *    starts. A 401 to a request sent with an older token replays it with the app's token\n *    now, without a refresh; a flight whose session changed while it ran stores nothing\n *    and ends nothing. The access token is the session's identity because every change\n *    the apps make replaces it — a refresh, another tab, a company switch, a password\n *    change, a sign-in, a demo start, a sign-out.\n *\n * Framework-free like `server-wake.ts`: {@link attachSessionRefresh} takes the app's\n * axios instance as an ARGUMENT, typed structurally, so the kit never imports axios.\n *\n * Since 0.55, {@link watchSessionElsewhere} beside it: the session ending in ANOTHER tab,\n * or while this page sat in the back/forward cache (kastlan reuse audit 2026-11-02,\n * proposal 6).\n */\n\nimport type { AxiosLikeInstance, ServerWakeAxiosConfig } from \"./server-wake\";\nimport { httpStatusOf } from \"./http-status\";\n\n/** What the app's `refresh` resolves: the new access token, plus whatever its `store`\n *  needs (its refresh token, the user). */\nexport interface SessionRenewal {\n  /** The new access token; the waiting requests are replayed with it. */\n  token: string;\n  /**\n   * `false`: store the renewal, but replay nothing — each waiting request rejects with\n   * its 401, unmarked. kastlan's refresh can land in another company (§11.5, ka 3): a\n   * waiting write, such as the handover's `POST /sync`, must not be replayed into it.\n   */\n  replay?: false;\n}\n\n/** What the app hands {@link createSessionRefresh} (§11.4). */\nexport interface SessionRefreshOptions<R extends SessionRenewal> {\n  /**\n   * The app's own `POST /auth/refresh`, on a BARE client — never the instance the kit is\n   * attached to, so the refresh cannot re-enter the interceptor. It **writes nothing**:\n   * the kit hands the answer to `store`, and only while the session is unchanged.\n   *\n   * Resolves the answer as a renewal, or `null` when the device holds no refresh token.\n   * Throws on failure, and the kit classifies the throw: a 401 or 403 is definitive; no\n   * answer (an axios error without a `response`), the kit's own timeout, 408, 429 and\n   * 5xx are transient and retried; any other answer, and anything that is not an HTTP\n   * error (a bug in this function), is transient and not retried. The status is read\n   * from `err.response.status` (axios), `err.status` or `err.statusCode`.\n   *\n   * `signal` aborts when the attempt runs past `timeoutMs`; pass it to the request.\n   */\n  refresh: (signal: AbortSignal) => Promise<R | null>;\n  /** Writes the renewal: the tokens and the user (a missing refresh token keeps the\n   *  stored one). Called only while the session the flight renews is still the app's,\n   *  and before the waiting requests are replayed — so it writes the token SYNCHRONOUSLY\n   *  where `currentToken` reads it: the replay goes through the app's own request\n   *  interceptor again, and is stamped then. A throw is the app's bug: the waiting\n   *  requests and `session.refresh()` reject with it. */\n  store: (renewal: R) => void;\n  /** The access token the app sends NOW, read where its request interceptor reads it;\n   *  `null` when there is none. */\n  currentToken: () => string | null;\n  /** Whether the session is a demo: a demo's 401 ends it, with no refresh tried\n   *  (landing-demo §5.5). */\n  isDemo: () => boolean;\n  /**\n   * The session is over: drop the tokens and the user, then navigate — `/demo/ended` for\n   * a demo, else the sign-in with the page it came from (auth §5.2). Called once per\n   * session, however many requests found out (KS 8), and never by `session.refresh()`.\n   */\n  onEnded: (ended: { demo: boolean }) => void;\n  /** Whether a URL is a signed-out step, whose 401 judges the form and never the\n   *  session. Replaces the default list, {@link isSignedOutStep}. */\n  isSignedOutStep?: (url: string) => boolean;\n  /** Attempts for a refresh that got no answer, timed out, or got a 408, 429 or 5xx.\n   *  Default 3. */\n  attempts?: number;\n  /** The waits before the second and later attempts; the last one repeats. Default\n   *  `[1000, 3000]`. */\n  backoffMs?: readonly number[];\n  /** Each attempt is cut off after this, and its `signal` aborted. Default 15 000. */\n  timeoutMs?: number;\n}\n\n/** What `session.refresh()` resolves (§11.4), by `result`:\n *\n * | `result` | When | What the kit has done |\n * |---|---|---|\n * | `\"renewed\"` | a renewal while the session was unchanged | `store(renewal)` |\n * | `\"ended\"` | definitive | nothing; `onEnded` only for requests that waited on the same flight |\n * | `\"transient\"` | transient | nothing |\n * | `\"changed\"` | the session changed while it ran | nothing; read the app's own state |\n */\nexport type SessionRefreshOutcome<R extends SessionRenewal = SessionRenewal> =\n  { result: \"renewed\"; renewal: R } | { result: \"ended\" } | { result: \"transient\" } | { result: \"changed\" };\n\n/** The flight {@link createSessionRefresh} makes; {@link attachSessionRefresh} hooks it\n *  to an axios instance. */\nexport interface SessionRefresh<R extends SessionRenewal = SessionRenewal> {\n  /**\n   * The same flight, for a caller outside the interceptor — kastlan's boot. Joins a\n   * running flight, or starts one. Never calls `onEnded`: the caller decides what an\n   * `\"ended\"` means for it.\n   */\n  refresh(): Promise<SessionRefreshOutcome<R>>;\n}\n\n// ── The signed-out steps ──────────────────────────────────────────────────────\n\n/**\n * Every `/auth/` call made without a session, the union of the three apps' lists\n * (§11.3): signing in (with its `2fa` and `set-password` steps, and a passkey's), up,\n * into a demo, a password reset, the verification link, the invitation check, the email\n * change's confirmation link, and the refresh itself. NOT `resend-verification` (KS 1):\n * in keksdose and Kurvenschmiede it needs a session; in kastlan it never answers 401.\n */\nconst SIGNED_OUT_STEPS = [\n  \"login\",\n  \"passkey/login\",\n  \"register\",\n  \"demo-session\",\n  \"password-reset\",\n  \"verify-email\",\n  \"invitations/check\",\n  \"me/email/confirm\",\n  \"refresh\",\n] as const;\n\n/**\n * Whether a request's URL is a signed-out step — the kit's default list (§11.3), exported\n * for an app's tests and for an app's own `isSignedOutStep` that adds to it.\n *\n * **Whole steps only** (KS 2): the part of the path after its `auth/` segment, without\n * the query string, is the entry itself or starts with the entry and a `/`. So\n * `login/2fa` is `login`'s, but `register` never catches `/auth/passkey/register/begin`\n * (adding a passkey, which needs a session), `invitations/check` never\n * `/auth/invitations/accept`, and `me/email/confirm` never `/auth/me/email`. Relative and\n * absolute URLs alike; a URL with no `auth` segment is no step.\n */\nexport function isSignedOutStep(url: string): boolean {\n  const path = url.replace(/[?#].*$/s, \"\").replace(/^([a-z][a-z\\d+.-]*:)?\\/\\/[^/]*/i, \"\");\n  const segments = path.split(\"/\");\n  const at = segments.indexOf(\"auth\");\n  if (at < 0) return false;\n  const step = segments.slice(at + 1).join(\"/\");\n  return SIGNED_OUT_STEPS.some((entry) => step === entry || step.startsWith(`${entry}/`));\n}\n\n// ── The marker ────────────────────────────────────────────────────────────────\n\n/** On the request's own axios error, after a transient failure (decision 8). A\n *  `Symbol.for` key: shared by every copy of the kit in a page, and left out of\n *  `JSON.stringify`, so a log that serialises the error doesn't print it (kk 2). */\nconst TRANSIENT = Symbol.for(\"@eifi1/ui-kit:session-refresh.transient\");\n\n/**\n * Whether a request was refused because the refresh behind it failed TRANSIENTLY —\n * offline, a timeout, a 5xx — and not because the session is over (decision 8). The\n * error is the request's own 401, `err.response?.status` and every check an app already\n * has keep working; this reads the mark the kit put on it, so the app's message can say\n * \"can't reach the server\" instead of \"not signed in\". Read it FIRST: keksdose's sync\n * chip, kastlan's handover sync and Kurvenschmiede's `apiErrorMessage` count it as\n * offline (§11.5).\n *\n * Not the refresh's own error: its config carries the refresh token in its body, into any\n * log or crash report that keeps the error.\n */\nexport function isTransientRefreshFailure(error: unknown): boolean {\n  return typeof error === \"object\" && error !== null && (error as Record<symbol, unknown>)[TRANSIENT] === true;\n}\n\n// ── The flight ────────────────────────────────────────────────────────────────\n\n/** A flight's result, as the interceptor needs it: `\"ended\"` keeps the session it ended. */\ntype Flight<R extends SessionRenewal> =\n  | { result: \"renewed\"; renewal: R }\n  | { result: \"ended\"; token: string | null }\n  | { result: \"transient\" }\n  | { result: \"changed\" };\n\n/** What one attempt came to. */\ntype Attempt<R> = { renewal: R } | \"definitive\" | \"retry\" | \"transient\";\n\n/** What {@link attachSessionRefresh} needs of a session. Kept off the public interface:\n *  only what {@link createSessionRefresh} made can be attached. */\ninterface Engine {\n  token(): string | null;\n  isDemo(): boolean;\n  isSignedOutStep(url: string): boolean;\n  join(): Promise<Flight<SessionRenewal>>;\n  end(token: string | null, demo: boolean): void;\n}\n\nconst engines = new WeakMap<SessionRefresh<SessionRenewal>, Engine>();\n\n/** The kit's own timeout, told apart from anything the app's `refresh` throws. */\nconst TIMED_OUT = Symbol(\"timed out\");\n\nfunction isOffline(): boolean {\n  return typeof navigator !== \"undefined\" && navigator.onLine === false;\n}\n\n/** A refresh's throw, classified (§11.4). The status is read where `isRateLimited` reads\n *  it — `httpStatusOf`, one probe for axios, ofetch and Node errors (DUP-11). */\nfunction classify(error: unknown): \"definitive\" | \"retry\" | \"transient\" {\n  if (error === TIMED_OUT) return \"retry\";\n  if (typeof error !== \"object\" || error === null) return \"transient\";\n  const status = httpStatusOf(error);\n  if (status === undefined) {\n    // No answer: axios marks its own errors, and one without a response never reached a\n    // server (offline, DNS, CORS, its own timeout). Anything else is a bug in `refresh`.\n    return (error as { isAxiosError?: unknown }).isAxiosError === true ? \"retry\" : \"transient\";\n  }\n  if (status === 401 || status === 403) return \"definitive\";\n  if (status === 408 || status === 429 || status >= 500) return \"retry\";\n  return \"transient\";\n}\n\nconst sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));\n\n/**\n * Make the flight: `const session = createSessionRefresh({ refresh, store, currentToken,\n * isDemo, onEnded })`, then {@link attachSessionRefresh}`(api, session)`. One per tab.\n */\nexport function createSessionRefresh<R extends SessionRenewal>(options: SessionRefreshOptions<R>): SessionRefresh<R> {\n  const { attempts = 3, backoffMs = [1000, 3000], timeoutMs = 15_000 } = options;\n  // An empty string is no token: the stamp and the flight compare tokens, and \"\" against\n  // `null` must not read as a change of session.\n  const token = () => options.currentToken() || null;\n\n  /** One call of the app's `refresh`, cut off after `timeoutMs` even if it ignores the\n   *  signal. */\n  const attempt = async (): Promise<Attempt<R>> => {\n    const controller = new AbortController();\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    const timeout = new Promise<never>((_, reject) => {\n      timer = setTimeout(() => {\n        reject(TIMED_OUT);\n        controller.abort();\n      }, timeoutMs);\n    });\n    try {\n      // Through `then`, so a `refresh` that throws before it returns a promise is\n      // classified like one that rejects.\n      const renewal = await Promise.race([Promise.resolve().then(() => options.refresh(controller.signal)), timeout]);\n      return renewal ? { renewal } : \"definitive\";\n    } catch (error) {\n      return classify(error);\n    } finally {\n      clearTimeout(timer);\n    }\n  };\n\n  const run = async (): Promise<Flight<R>> => {\n    // The session this flight renews (§11.3 step 5).\n    const noted = token();\n    const changed = () => token() !== noted;\n    let outcome = await attempt();\n    for (let made = 1; outcome === \"retry\"; made += 1) {\n      // No further attempt while the browser says it is offline, nor for a session that\n      // is no longer the app's: whatever the answer, it would be \"changed\".\n      if (made >= attempts || isOffline() || changed()) break;\n      await sleep(backoffMs[made - 1] ?? backoffMs[backoffMs.length - 1] ?? 0);\n      if (isOffline() || changed()) break;\n      outcome = await attempt();\n    }\n    // A late answer never writes the old session back over a sign-out, a demo start or a\n    // password change, and the old session's refusal never signs anyone out (KS 3).\n    if (changed()) return { result: \"changed\" };\n    if (outcome === \"definitive\") return { result: \"ended\", token: noted };\n    if (outcome === \"retry\" || outcome === \"transient\") return { result: \"transient\" };\n    options.store(outcome.renewal);\n    return { result: \"renewed\", renewal: outcome.renewal };\n  };\n\n  let flight: Promise<Flight<R>> | null = null;\n  const join = () => {\n    // Cleared before any waiter resumes (`finally` settles first), so a waiter that\n    // needs another flight starts a new one.\n    flight ??= run().finally(() => {\n      flight = null;\n    });\n    return flight;\n  };\n\n  /** The session `onEnded` was last called for: once per session (KS 8). */\n  let ended: { token: string | null } | undefined;\n\n  const session: SessionRefresh<R> = {\n    async refresh() {\n      const outcome = await join();\n      return outcome.result === \"ended\" ? { result: \"ended\" } : outcome;\n    },\n  };\n  engines.set(session, {\n    token,\n    isDemo: () => options.isDemo(),\n    isSignedOutStep: options.isSignedOutStep ?? isSignedOutStep,\n    join,\n    end(endedToken, demo) {\n      if (ended && ended.token === endedToken) return;\n      ended = { token: endedToken };\n      options.onEnded({ demo });\n    },\n  });\n  return session;\n}\n\n// ── axios ─────────────────────────────────────────────────────────────────────\n\n/** The config fields the kit reads and writes — what axios's request config has. */\ninterface SessionRefreshAxiosConfig extends ServerWakeAxiosConfig {\n  /** axios's `AxiosHeaders` (written through its `set`), or a plain record. */\n  headers?: unknown;\n}\n\n/** An axios instance, structurally: {@link AxiosLikeInstance}, plus `request(config)` for\n *  the replay. `axios.create()`'s result fits it as is. `NoInfer`, because axios's\n *  `request` takes the WIDER `AxiosRequestConfig`: inferred from there, the config type\n *  no longer fits the interceptors, which hand out `InternalAxiosRequestConfig`. */\ninterface SessionRefreshInstance<\n  C extends SessionRefreshAxiosConfig,\n  R extends { config: C },\n> extends AxiosLikeInstance<C, R> {\n  request(config: NoInfer<C>): Promise<unknown>;\n}\n\n/** The keys the kit keeps on a request's config, as `attachServerWake` keeps\n *  `_serverWake`: never a header. Plain string keys holding primitives, because axios\n *  copies the config on a replay (`mergeConfig`) and a symbol key would be dropped. */\nconst STAMP = \"_sessionStamp\";\nconst REFRESHED = \"_sessionRefreshed\";\nconst RESTAMPED = \"_sessionRestamped\";\ntype Marked = {\n  /** `currentToken()` when the request went out. */\n  [STAMP]?: string | null;\n  /** Replayed after a refresh: a 401 now is definitive (decision 3). */\n  [REFRESHED]?: boolean;\n  /** Replayed because it was sent with an older token: once for this reason. */\n  [RESTAMPED]?: boolean;\n};\n\n/** `Authorization: Bearer <token>` on a config about to be replayed. The app's own\n *  request interceptor runs again on the replay and writes the same, from the same\n *  source. */\nfunction authorize(config: SessionRefreshAxiosConfig, token: string): void {\n  const value = `Bearer ${token}`;\n  const headers = config.headers;\n  if (typeof headers !== \"object\" || headers === null) {\n    config.headers = { Authorization: value };\n  } else if (typeof (headers as { set?: unknown }).set === \"function\") {\n    (headers as { set(name: string, value: string): unknown }).set(\"Authorization\", value);\n  } else {\n    (headers as Record<string, unknown>).Authorization = value;\n  }\n}\n\n/**\n * Hook a session to an axios instance: `attachSessionRefresh(api, session)`. Adds a\n * request interceptor (the stamp) and a response interceptor (the 401), and returns a\n * function that ejects both.\n *\n * Attach it LAST (§11.3, kk 4): after `attachServerWake`, which asks to be first, and\n * after the app's own response interceptors (logging, a watchdog of its own). axios runs\n * response interceptors in the order they were added, and each of those must see the 401\n * settle before the refresh is awaited. The request side's order does not matter.\n *\n * On a 401, in this order (§11.3):\n *\n *  1. a signed-out step → reject, nothing else;\n *  2. sent with an older token → replayed with the app's token now, with no refresh, once\n *     for this reason; with no token now, reject;\n *  3. a demo → `onEnded({ demo: true })`, reject;\n *  4. already replayed after a refresh → definitive: `onEnded({ demo: false })`, reject;\n *  5. otherwise it joins the flight, or starts it. A renewal replays it once with the\n *     renewal's token (`replay: false`: rejects, unmarked); definitive ends the session;\n *     transient rejects, marked; a session that changed meanwhile sends it through step\n *     2 again.\n *\n * Every rejection is the request's OWN error. Any other status passes through untouched.\n */\nexport function attachSessionRefresh<C extends SessionRefreshAxiosConfig, R extends { config: C }>(\n  instance: SessionRefreshInstance<C, R>,\n  session: SessionRefresh<SessionRenewal>,\n): () => void {\n  const engine = engines.get(session);\n  if (!engine) throw new TypeError(\"attachSessionRefresh takes the session createSessionRefresh made\");\n\n  const onUnauthorized = async (error: object, config: C & Marked): Promise<unknown> => {\n    if (engine.isSignedOutStep(config.url ?? \"\")) throw error;\n    // A config the kit never stamped (sent before it was attached) counts as current.\n    const stamp = config[STAMP] === undefined ? engine.token() : config[STAMP];\n    const replay = (token: string) => {\n      authorize(config, token);\n      return instance.request(config);\n    };\n    for (;;) {\n      const now = engine.token();\n      // 2. The session it was sent for is gone, and whatever ended it has already done\n      // what follows (ka 3, KS 3, KS 4).\n      if (stamp !== now) {\n        if (now === null || config[RESTAMPED]) throw error;\n        config[RESTAMPED] = true;\n        return replay(now);\n      }\n      // 3. A demo has nothing to refresh: its token lives as long as its account\n      // (landing-demo §5.5).\n      if (engine.isDemo()) {\n        engine.end(now, true);\n        throw error;\n      }\n      // 4. A replay for an older token doesn't count here: the app's current token may\n      // simply have expired too, which needs a refresh, not a sign-out.\n      if (config[REFRESHED]) {\n        engine.end(now, false);\n        throw error;\n      }\n      // 5. The flight.\n      const flight = await engine.join();\n      if (flight.result === \"changed\") continue;\n      if (flight.result === \"ended\") {\n        engine.end(flight.token, false);\n        throw error;\n      }\n      if (flight.result === \"transient\") {\n        (error as Record<symbol, unknown>)[TRANSIENT] = true;\n        throw error;\n      }\n      if (flight.renewal.replay === false) throw error;\n      config[REFRESHED] = true;\n      return replay(flight.renewal.token);\n    }\n  };\n\n  const request = instance.interceptors.request.use(\n    (config) => {\n      (config as C & Marked)[STAMP] = engine.token();\n      return config;\n    },\n    (error) => Promise.reject(error),\n  );\n  const response = instance.interceptors.response.use(\n    (res) => res,\n    (error) => {\n      const failed = error as { config?: C & Marked; response?: { status?: unknown } } | null;\n      if (failed?.response?.status !== 401 || !failed.config) return Promise.reject(error);\n      return onUnauthorized(failed, failed.config);\n    },\n  );\n  return () => {\n    instance.interceptors.request.eject(request);\n    instance.interceptors.response.eject(response);\n  };\n}\n\n// ── Another tab ───────────────────────────────────────────────────────────────\n\n/** What the app hands {@link watchSessionElsewhere}. */\nexport interface SessionElsewhereOptions {\n  /**\n   * Whether this tab's session is over: this tab holds one, and the storage every tab\n   * shares no longer does — its token removed by a sign-out elsewhere, the storage\n   * cleared — or holds another account's. Read where the app's request interceptor reads\n   * the token (`readStored`), against what this tab keeps in memory. A renewal elsewhere\n   * rewrites the token and is no end; a tab with no session has nothing to end.\n   */\n  ended: () => boolean;\n  /**\n   * The session is over in this tab: drop what this tab holds of it (the user, the query\n   * cache, the unlocked keys), then leave with a full load, of the sign-in or the demo's\n   * end. Not the app's whole sign-out: the other tab has already removed what the device\n   * kept, and may since have stored a session that is not this tab's to delete.\n   *\n   * Called once per session: further `storage` events while `ended` still reads `true`\n   * call nothing, until it has read `false` again. A restored page is asked afresh.\n   */\n  onEnded: () => void;\n  /** Also check a page the browser brings back from its back/forward cache (`pageshow`\n   *  with `persisted`). Default `true`. */\n  checkRestored?: boolean;\n}\n\n/**\n * Watch for this tab's session ending in another tab (kastlan reuse audit 2026-11-02,\n * proposal 6): `const stop = watchSessionElsewhere({ ended, onEnded })`, once per tab,\n * beside the app's session store. Returns the function that stops watching.\n *\n * The session belongs to the device — its tokens sit in localStorage, which every tab\n * shares — and the account on screen to the tab: the user, the query cache and the\n * unlocked keys sit in this tab's memory. A sign-out in another tab changed the first and\n * left the second, so this tab kept the previous account on screen and wrote its data\n * back into the offline copy the other tab had just wiped (refactor audit 2026-10-30:\n * keksdose FS-2, kastlan FLW-1). Two moments tell it:\n *\n *  - a `storage` event: another tab wrote or removed a key. `ended` is read after every\n *    one, whatever its key — it reads the state, so it needs no list of keys, and a\n *    cleared storage (`key` null) counts like any removal;\n *  - a page restored from the back/forward cache (`pageshow` with `persisted`). Frozen\n *    there, it heard no `storage` event and came back on the previous account, where it\n *    could renew the old session and store its tokens again over the sign-out (keksdose\n *    F-31; kastlan listened to `storage` alone). A fresh load reads the storage anyway,\n *    so nothing is checked when the watch starts, nor on a `pageshow` that is no restore.\n *\n * Framework-free and storage-free: `ended` is the app's read, guarded where it reads\n * (the kit's `readStored` never throws). Nothing is watched where there is no `window`.\n */\nexport function watchSessionElsewhere(options: SessionElsewhereOptions): () => void {\n  if (typeof window === \"undefined\") return () => undefined;\n  /** `onEnded` was called, and `ended` has not read `false` since. */\n  let told = false;\n  const check = () => {\n    if (!options.ended()) {\n      told = false;\n      return;\n    }\n    if (told) return;\n    told = true;\n    options.onEnded();\n  };\n  const onStorage = () => check();\n  const onPageShow = (event: PageTransitionEvent) => {\n    if (!event.persisted) return;\n    // A page shown again is asked again, told or not: its `onEnded` left with a full load,\n    // the browser kept the page, and Back brought it back on the previous account.\n    told = false;\n    check();\n  };\n  window.addEventListener(\"storage\", onStorage);\n  if (options.checkRestored !== false) window.addEventListener(\"pageshow\", onPageShow);\n  return () => {\n    window.removeEventListener(\"storage\", onStorage);\n    window.removeEventListener(\"pageshow\", onPageShow);\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/rhf/fields.js

@@ -73,7 +73,7 @@ function RhfField({
   showLabel = true
 }) {
   const helpMark = fieldHelpMark(help, label);
-  const shownHint = useInlineHint(hint, helpMark !== void 0);
+  const shownHint = useInlineHint(hint, helpMark !== void 0, label);
   const labelEl = showLabel && hasContent(label) && /* @__PURE__ */ jsx(RhfLabel, { required, children: label });
   return /* @__PURE__ */ jsx(
     FormField,
@@ -477,7 +477,7 @@ function RangeBody({
 }) {
   const { id, formItemId, formMessageId, describedBy } = useFormField();
   const helpMark = fieldHelpMark(help, label);
-  const shownHint = useInlineHint(hint, helpMark !== void 0);
+  const shownHint = useInlineHint(hint, helpMark !== void 0, label);
   const triggerRef = useMemo(() => mergeRefs(from.ref, to.ref), [from.ref, to.ref]);
   const invalid = fromState.invalid || toState.invalid;
   const messages = [fromState.error?.message, toState.error?.message].filter(
@@ -821,7 +821,7 @@ function RhfCheckbox({
   className,
   ...boxProps
 }) {
-  const description = useInlineHint(hint);
+  const description = useInlineHint(hint, false, label);
   return /* @__PURE__ */ jsx(
     RhfField,
     {