@geniee-inc/sfa-kit 1.17.0 → 1.18.0

package/GUIDE.md

@@ -128,7 +128,7 @@ Every page uses `SfaLoginGate` as the outermost wrapper. It auto-detects the hos
 
 ### Props
 
-- **`apiBase`** (optional) — Overrides the auto-detected Keystone API endpoint. When omitted, the endpoint is resolved from a hostname: the embedding SFA/CRM host's when the page runs inside the iframe, the page's own when it runs standalone. Non-production environments (`stg.chikyu.mobi`, `dev01`-`dev09`, `devdc`, `deva0`, `dev-docker`, `dev.chikyu.local`, `localhost`, `127.0.0.1`, `[::1]`, and every Amplify host of the new frontend under `*.amplify.axiom.chikyu.mobi`: PR previews plus the `devNN.waf.` / `stg.waf.` record-detail hosts) use `https://keystone-api-staging.chikyu.mobi`; everything else (`app.chikyu.net`, any hostname not in that list) uses `https://keystone-api-production.chikyu.mobi`. Production is the fallback on purpose so a page that reaches a customer never silently talks to staging.
+- **`apiBase`** (optional) — Overrides the auto-detected Keystone API endpoint. When omitted, the endpoint is resolved from a hostname: the embedding SFA/CRM host's when the page runs inside the iframe, the page's own when it runs standalone. `dev09` (`dev09.chikyu.mobi` and `dev09.waf.amplify.axiom.chikyu.mobi`) has a Keystone of its own and uses `https://keystone-api-dev09.chikyu.mobi`. The other non-production environments (`stg.chikyu.mobi`, `dev01`-`dev08`, `devdc`, `deva0`, `dev-docker`, `dev.chikyu.local`, `localhost`, `127.0.0.1`, `[::1]`, and every Amplify host of the new frontend under `*.amplify.axiom.chikyu.mobi`: PR previews plus the `devNN.waf.` / `stg.waf.` record-detail hosts) use `https://keystone-api-staging.chikyu.mobi`; everything else (`app.chikyu.net`, any hostname not in that list) uses `https://keystone-api-production.chikyu.mobi`. Production is the fallback on purpose so a page that reaches a customer never silently talks to staging.
 - **`trustedOrigin`** (optional) — The origin of the SFA/CRM host page (e.g. `"https://app.chikyu.net"`). When provided and the page runs inside an iframe, `SfaLoginGate` uses the postMessage code-exchange flow (`POST /v1/auth/exchange`) instead of a login form. Injected automatically by Keystone's content endpoint at serve time.
 - **`defaultOrganizationId`** (optional) — The org ID to auto-select when the user's account belongs to multiple organizations. **Set this to the org that generated the page's metadata** (the org used in Step 0 schema discovery). Without this prop, multi-org accounts auto-select the first available org, which may not be the intended one. Use an env var, not a literal: `defaultOrganizationId={Number(process.env.NEXT_PUBLIC_DEFAULT_ORG_ID)}`.
 - **`objectKey`** (optional) — The object this page is built for (e.g. `"companies"`). The standalone DevToolbar shows it in the page-info tooltip and in the record ID placeholder. Pass it at **both** levels; omit it only if the page genuinely has no object.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geniee-inc/sfa-kit",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "React hooks and components for building pages that connect to GENIEE SFA/CRM data.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.d.ts

@@ -34,7 +34,7 @@ export { ErrorBoundary } from './lib/components/ErrorBoundary';
 export { EmptyState } from './lib/components/EmptyState';
 export { FetchErrorState } from './lib/components/FetchErrorState';
 export { ErrorSnackbar } from './lib/components/ErrorSnackbar';
-export type { SfaAuth, SfaApiMode, SfaClientConfig, SfaRecord, SfaListResponse, SfaListParams, SfaFieldValue, SfaFieldKind, SfaFieldValueMapping, FieldGroupSpec, FieldGroupLayout, SfaFieldDescriptor, SfaFieldOption, SfaRelationDescriptor, SfaObjectDetail, SfaObjectSummary, SfaObjectCatalog, SfaObjectPermissions, SfaObjectOrigin, SfaRelationshipKind, SfaCardinality, SfaDescribeResult, SfaFieldTypeDescriptor, SfaFieldTypeCatalog, SfaFilterOperator, SfaCreateOptions, SfaFieldError, SfaBulkRowStatus, SfaBulkRowResult, SfaBulkRowError, SfaBulkUpdateRow, SfaBulkDeleteRow, } from './lib/provider/types';
+export type { SfaAuth, SfaApiMode, SfaAuthErrorHandler, SfaClientConfig, SfaRecord, SfaListResponse, SfaListParams, SfaFieldValue, SfaFieldKind, SfaFieldValueMapping, FieldGroupSpec, FieldGroupLayout, SfaFieldDescriptor, SfaFieldOption, SfaRelationDescriptor, SfaObjectDetail, SfaObjectSummary, SfaObjectCatalog, SfaObjectPermissions, SfaObjectOrigin, SfaRelationshipKind, SfaCardinality, SfaDescribeResult, SfaFieldTypeDescriptor, SfaFieldTypeCatalog, SfaFilterOperator, SfaCreateOptions, SfaFieldError, SfaBulkRowStatus, SfaBulkRowResult, SfaBulkRowError, SfaBulkUpdateRow, SfaBulkDeleteRow, } from './lib/provider/types';
 export { SFA_BULK_MAX_ROWS } from './lib/provider/SfaClient';
 export type { SfaSession, AuthResult, OrganizationChoice, } from './lib/auth/types';
 export { buildRecordDetailUrl, resolveHostOrigin, } from './lib/navigation/record-detail-url';

package/src/lib/auth/resolve-api-base.d.ts

@@ -1,12 +1,14 @@
 export declare const KEYSTONE_PRODUCTION_API_BASE = "https://keystone-api-production.chikyu.mobi";
 export declare const KEYSTONE_STAGING_API_BASE = "https://keystone-api-staging.chikyu.mobi";
+export declare const KEYSTONE_DEV09_API_BASE = "https://keystone-api-dev09.chikyu.mobi";
 /**
  * @description Resolves the Keystone API base URL from an origin.
  *
- * Every non-production chikyu environment — `stg.chikyu.mobi`, the dev tier,
- * local development, and Amplify PR previews — uses the staging Keystone API.
- * Everything else — `app.chikyu.net`, an origin this table does not know, or
- * no origin at all — uses production.
+ * `dev09` has a keystone of its own. Every other non-production chikyu
+ * environment — `stg.chikyu.mobi`, the rest of the dev tier, local development,
+ * and Amplify PR previews — uses the staging Keystone API. Everything else —
+ * `app.chikyu.net`, an origin this table does not know, or no origin at all —
+ * uses production.
  *
  * Production is the fallback on purpose: a page that reaches a real customer
  * must never silently talk to staging. A developer on an unrecognised host

package/src/lib/auth/resolve-api-base.js

@@ -1,6 +1,10 @@
 export const KEYSTONE_PRODUCTION_API_BASE = 'https://keystone-api-production.chikyu.mobi';
 export const KEYSTONE_STAGING_API_BASE = 'https://keystone-api-staging.chikyu.mobi';
-/** Dev-tier chikyu (legacy frontend) hosts: dev01-dev09, devdc, deva0, and the like. */
+export const KEYSTONE_DEV09_API_BASE = 'https://keystone-api-dev09.chikyu.mobi';
+/**
+ * Dev-tier chikyu (legacy frontend) hosts: dev01-dev08, devdc, deva0, and the
+ * like. `dev09` matches this too but is taken by `DEV09_HOSTNAMES` first.
+ */
 const DEV_HOST_PATTERN = /^dev\w+\.chikyu\.mobi$/;
 /**
  * Amplify-hosted new frontend. Covers PR previews
@@ -21,13 +25,26 @@ const LOCAL_HOSTNAMES = new Set([
 ]);
 /** Shared pre-production chikyu environments. */
 const STAGING_HOSTNAMES = new Set(['stg.chikyu.mobi']);
+/**
+ * dev09 has a keystone of its own. One keystone delegates to exactly one chikyu
+ * environment, so the staging keystone follows `stg` and this one follows
+ * `dev09`, the JapanAI Studio integration environment. Both of dev09's frontends
+ * are listed: the legacy chikyu host and the Amplify host that frames the page.
+ * Exact hostnames, because `DEV_HOST_PATTERN` and `AMPLIFY_PATTERN` below would
+ * otherwise claim them for staging.
+ */
+const DEV09_HOSTNAMES = new Set([
+    'dev09.chikyu.mobi',
+    'dev09.waf.amplify.axiom.chikyu.mobi',
+]);
 /**
  * @description Resolves the Keystone API base URL from an origin.
  *
- * Every non-production chikyu environment — `stg.chikyu.mobi`, the dev tier,
- * local development, and Amplify PR previews — uses the staging Keystone API.
- * Everything else — `app.chikyu.net`, an origin this table does not know, or
- * no origin at all — uses production.
+ * `dev09` has a keystone of its own. Every other non-production chikyu
+ * environment — `stg.chikyu.mobi`, the rest of the dev tier, local development,
+ * and Amplify PR previews — uses the staging Keystone API. Everything else —
+ * `app.chikyu.net`, an origin this table does not know, or no origin at all —
+ * uses production.
  *
  * Production is the fallback on purpose: a page that reaches a real customer
  * must never silently talk to staging. A developer on an unrecognised host
@@ -41,6 +58,8 @@ export function resolveApiBase(origin) {
     const hostname = hostnameOf(origin);
     if (hostname == null)
         return KEYSTONE_PRODUCTION_API_BASE;
+    if (DEV09_HOSTNAMES.has(hostname))
+        return KEYSTONE_DEV09_API_BASE;
     const isNonProduction = STAGING_HOSTNAMES.has(hostname) ||
         LOCAL_HOSTNAMES.has(hostname) ||
         DEV_HOST_PATTERN.test(hostname) ||

package/src/lib/auth/useEmbedSession.d.ts

@@ -1,3 +1,4 @@
+import type { SfaAuthErrorHandler } from '../provider/types';
 import type { EmbedContext } from './embed-protocol';
 import type { SfaSession } from './types';
 export type EmbedPhase = {
@@ -28,7 +29,7 @@ export type EmbedPhase = {
 export interface EmbedSessionState {
     readonly phase: EmbedPhase;
     /** Passed to SfaProvider so a 401 triggers the code-request fallback. */
-    readonly handleAuthError: () => void;
+    readonly handleAuthError: SfaAuthErrorHandler;
 }
 /**
  * @description Keeps an embedded page authenticated over the postMessage

package/src/lib/auth/useEmbedSession.js

@@ -21,12 +21,23 @@ const CODE_TIMEOUT_SECONDS = 15;
 /** Consecutive failed attempts to obtain a usable session before giving up. */
 const MAX_RECOVERY_ATTEMPTS = 4;
 /**
- * A 401 landing within this window of the previous one belongs to the same
- * recovery run. Without it, a token Keystone happily mints but the API keeps
- * rejecting loops forever, because every exchange succeeds and resets counters.
+ * A rejection landing within this window of the run's start belongs to the
+ * same recovery run. Without it, a token Keystone happily mints but the API
+ * keeps rejecting loops forever, because every exchange succeeds and resets
+ * the retry counters.
+ *
+ * NOTE: only rejections of the token currently held are counted — a reply
+ * about a token already replaced is dropped before it gets here. The window
+ * therefore bounds a genuine loop, and no longer trips on the stragglers of a
+ * session that is recovering perfectly well.
+ *
+ * NOTE: a backstop for a fast loop, not a precise detector. Separating a loop
+ * from an endpoint answering 401 where it means 403 needs to know whether any
+ * request *succeeded* with the replacement token, which nothing reports — the
+ * client only calls back on failure.
  */
 const AUTH_ERROR_WINDOW_SECONDS = 30;
-/** 401-triggered recovery cycles allowed inside AUTH_ERROR_WINDOW_SECONDS. */
+/** Rejections of the current token allowed inside AUTH_ERROR_WINDOW_SECONDS. */
 const MAX_AUTH_ERROR_CYCLES = 3;
 /** An exchange still unsettled after this long is treated as abandoned. */
 const STALE_EXCHANGE_SECONDS = 20;
@@ -84,6 +95,8 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
     const [phase, setPhase] = useState({ step: 'waiting_for_code' });
     const refreshTimerRef = useRef(null);
     const retryTimerRef = useRef(null);
+    /** ホストから最初のコードが届くのを待つタイマー。届いた時点で止める。 */
+    const codeTimeoutRef = useRef(null);
     const exchangingRef = useRef(false);
     const exchangeStartedAtRef = useRef(0);
     /** 追い越された交換の結果で新しいセッションを上書きしないための世代番号。 */
@@ -99,15 +112,23 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
     /** 連鎖の起点。最後の 1 件ではなく最初の 1 件から窓を測る。 */
     const authErrorRunStartedAtRef = useRef(0);
     /**
-     * 401 を受けてコードを要求済みかどうか。SfaClient は 401 を返した
-     * リクエストごとに onAuthError を呼ぶため、並行リクエストの分をまとめる。
+     * 直近に交換できたトークン。401 がどのトークンに対するものかの照合に使う。
+     * 拒否として受理した時点で null にする。SfaClient は 401 を返した
+     * リクエストごとに onAuthError を呼ぶので、同じトークンの並行分は以降
+     * 照合に失敗して落ちる。
      */
-    const isAuthErrorPendingRef = useRef(false);
+    const currentTokenRef = useRef(null);
     const hasEverAuthenticatedRef = useRef(false);
     /** 同じ復帰の試行でコンソールに書いたかどうか。交換成功で false に戻す。 */
     const hasLoggedExchangeFailureRef = useRef(false);
     /** 打ち切り済み。以降は再要求も画面遷移もしない。 */
     const isSettledRef = useRef(false);
+    /**
+     * 後片付け済み。SfaClient は解体後も生き続け、飛んでいたリクエストが 401 で
+     * 返ると onAuthError を呼ぶ。isSettledRef では代用できない（依存変更による
+     * 再実行でも立ってしまい、生きているセッションまで止まる）。
+     */
+    const isTornDownRef = useRef(false);
     const clearRefreshTimer = useCallback(() => {
         if (refreshTimerRef.current != null) {
             clearTimeout(refreshTimerRef.current);
@@ -120,6 +141,12 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
             retryTimerRef.current = null;
         }
     }, []);
+    const clearCodeTimeout = useCallback(() => {
+        if (codeTimeoutRef.current != null) {
+            clearTimeout(codeTimeoutRef.current);
+            codeTimeoutRef.current = null;
+        }
+    }, []);
     const isTokenUsable = useCallback(() => {
         const session = sessionRef.current;
         return session != null && session.expiresAt > Date.now();
@@ -127,13 +154,17 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
     /** 打ち切って画面を差し替える。手元に使えるものが何も残っていないとき。 */
     const settle = useCallback((next) => {
         isSettledRef.current = true;
+        // 待ち時間のタイマーを止める。終了画面が書き換わるのを防いでいるのは
+        // ハンドラ側の waiting_for_code 判定のほうで、ここは残り 15 秒を
+        // 空回りさせないための後片付け
+        clearCodeTimeout();
         // 進行中の交換を無効化する。これが無いと、打ち切った後に解決した交換が
         // authenticated を書き戻し、二度と操作できない画面が残る。
         exchangeGenerationRef.current += 1;
         clearRefreshTimer();
         clearRetryTimer();
         setPhase(next);
-    }, [clearRefreshTimer, clearRetryTimer]);
+    }, [clearCodeTimeout, clearRefreshTimer, clearRetryTimer]);
     /**
      * 状態画面は子ツリーがまだ描画されていないときだけ出す。認証済みの表示中は
      * phase を動かさず、ページの状態をそのまま残す。打ち切り後も動かさない。
@@ -154,9 +185,21 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
             ? current
             : { step: 'exchanging' });
     }, []);
-    const sendCodeRequest = useCallback(() => {
-        sendToHost({ type: 'sfa-kit:code-request' }, trustedOrigin);
+    // NOTE: 宛先は ref から読む。trustedOrigin を直接閉じ込めると、張り済みの
+    // タイマーが差し替え前の宛先へ送り続ける。あわせて sendCodeRequest の同一性が
+    // 安定し、これを使うコールバック（armCodeRetry / requestCode / scheduleRefresh）
+    // も張り直しの対象から外れる。
+    //
+    // NOTE: 代入はレンダー中ではなく effect で行う。並行レンダリングでは破棄される
+    // レンダーがあり、その値が残ると、一度も有効になっていない宛先へ送ることになる。
+    // useRef の初期値があるので、最初の effect までの窓が空になることはない。
+    const trustedOriginRef = useRef(trustedOrigin);
+    useEffect(() => {
+        trustedOriginRef.current = trustedOrigin;
     }, [trustedOrigin]);
+    const sendCodeRequest = useCallback(() => {
+        sendToHost({ type: 'sfa-kit:code-request' }, trustedOriginRef.current);
+    }, []);
     /** 打ち切り後にトークンが切れた時点で next に落とすためのタイマー。 */
     const scheduleExpiryCutoff = useCallback((next) => {
         clearRefreshTimer();
@@ -243,6 +286,10 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
         }, delaySeconds * 1000);
     }, [clearRefreshTimer, requestCode]);
     const handleCodeReceived = useCallback((code, context) => __awaiter(this, void 0, void 0, function* () {
+        // コードが届いた時点でホストは手順に対応している。取りこぼした 1 通でも
+        // それは変わらないので、打ち切り済みかどうかの判定より先に止める。
+        // settle() 側と同じく、表示を守っているのはハンドラ側の判定のほう。
+        clearCodeTimeout();
         if (isSettledRef.current)
             return;
         const startedAt = Date.now();
@@ -265,7 +312,7 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
             if (exchangeGenerationRef.current !== generation)
                 return;
             recoveryAttemptsRef.current = 0;
-            isAuthErrorPendingRef.current = false;
+            currentTokenRef.current = session.accessToken;
             hasLoggedExchangeFailureRef.current = false;
             hasEverAuthenticatedRef.current = true;
             sessionRef.current = session;
@@ -317,6 +364,7 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
         }
     }), [
         apiBase,
+        clearCodeTimeout,
         scheduleRefresh,
         armCodeRetry,
         clearRetryTimer,
@@ -325,12 +373,37 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
         showStatusIfNotMounted,
         showExchangingIfNotMounted,
     ]);
-    const handleAuthError = useCallback(() => {
-        if (isSettledRef.current)
+    const handleAuthError = useCallback((rejectedToken) => {
+        // 解体後の 401 で復帰を始めない。もう無い画面のために使い捨てコードを
+        // ホストへ要求し続けることになる
+        if (isTornDownRef.current || isSettledRef.current)
             return;
-        if (isAuthErrorPendingRef.current)
+        // 認証なしで飛んだリクエストの 401。埋め込みでは SfaProvider に
+        // トークンが渡ってから子ツリーを描き、exchangeCode も空のトークンを
+        // 弾くので、この経路は発生しない。発生するようになったら落とすのでは
+        // なく本物の拒否として扱うこと — さもないと、全部のリクエストが 401 に
+        // なる画面が認証済みの見た目のまま残る。
+        //
+        // NOTE: 下の照合に任せず明示的に落とす。任せると「undefined は string と
+        // 一致しない」という偶然が唯一の根拠になり、currentTokenRef の型を
+        // string | undefined に揃えるリファクタが、型エラーを出さないまま
+        // この分岐を反転させる。
+        if (rejectedToken == null)
             return;
-        isAuthErrorPendingRef.current = true;
+        // 差し替え済みのトークンについての返事は捨てる。ホストへコードを
+        // 要求し直しても、そのリクエストはもう存在しないトークンのものなので
+        // 何も直らず、動いているセッションを巻き添えにするだけになる。
+        // 復帰中（currentTokenRef が null）の分もここで落ちる。
+        //
+        // 並行リクエストの重複もここで落ちる。最初の 1 件で currentTokenRef を
+        // null にするため、同じトークンの 2 件目以降は照合に失敗する。
+        //
+        // NOTE: 文字列の一致で見分けられるのは、Keystone が 1 回ごとに異なる
+        // トークンを出すから（jti に uuid4 が入る）。同じ値が再発行されると、
+        // 差し替え後に届いた遅れ分が新しいトークンの拒否と区別できなくなる。
+        if (rejectedToken !== currentTokenRef.current)
+            return;
+        currentTokenRef.current = null;
         const now = Date.now();
         // 窓は連鎖の起点から測る。直近の 1 件から測ると、正常に復帰している
         // 25 秒間隔の 401 でも窓が滑り続けて打ち切りに達してしまう。
@@ -340,13 +413,18 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
             authErrorRunStartedAtRef.current = now;
         }
         authErrorCyclesRef.current += 1;
-        // ここに達した時点で交換自体は通り続けている。その 401 は差し替え前の
-        // トークンで投げられたリクエストの遅れ着信であることが多く、手元では
-        // 見分けられない（onAuthError は拒否されたトークンを渡さない）。
-        // 動いているセッションを巻き添えにしない側を採る。
+        // ここに達するのは、いま持っているトークンが実際に拒否された場合だけ。
+        // それでも上限を置くのは、Keystone が発行するそばから API に拒否される
+        // 状態を止めるため。交換自体は成功し続けるので、見張り側の試行回数は
+        // 毎回 0 に戻り、上限が無ければ永久に回り続ける。
         if (authErrorCyclesRef.current > MAX_AUTH_ERROR_CYCLES) {
-            // 手元のトークンが期限内なら表示は保ち、コードの取り直しだけをやめて、
-            // 失効した時点でセッション切れとして扱う。
+            // 表示は保ち、コードの取り直しだけをやめて、失効した時点でセッション
+            // 切れとして扱う。
+            //
+            // NOTE: ここまで来たトークンは期限内だが拒否されている（照合を通った
+            // ので、遅れ着信ではない）。つまり残す画面ではリクエストが通らない。
+            // それでも畳まないのは、入力中の内容を失わせないため。どちらを採るかは
+            // 挙動の選択なので、変えるなら SFAJAI-202 の判断ごと見直すこと。
             //
             // 据え置きにする必要がある。ホストは要求を受けてから非同期にコードを
             // 発行するので、打ち切った後に以前の要求への応答が届く。交換を続けて
@@ -367,6 +445,61 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
         requestCode();
         showStatusIfNotMounted({ step: 'waiting_for_code' });
     }, [requestCode, clearRefreshTimer, stopRetrying, showStatusIfNotMounted]);
+    /** 直前に使っていた認証先。同一性の変化と、値の変化を見分けるために持つ。 */
+    const previousApiBaseRef = useRef(apiBase);
+    /**
+     * @description 認証先が変わっていれば、旧 API を前提にした状態をすべて捨てて
+     * やり直す。変わっていなければ何もしない。
+     *
+     * 判定を内側に持つのは、依存の同一性が変わっただけの張り直しで走らせない
+     * ため。やり直す理由は認証先が変わったことであって、effect が走り直した
+     * ことではない。
+     *
+     * 交換を始めた時点の apiBase が、その結果が通用する認証先を決める。返ってくる
+     * トークンは旧 API が発行したものなので採用できない。採用すると SfaProvider が
+     * 新しい API へ旧トークンを送り続けることになる。
+     *
+     * NOTE: 世代を進めるだけでは足りない。世代がずれると handleCodeReceived の
+     * finally が exchangingRef を戻さず、張り直されたメッセージ effect が送る ready
+     * への返事まで「交換中」と見なされて STALE_EXCHANGE_SECONDS の間無視される。
+     *
+     * NOTE: isSettledRef は戻さない。打ち切り済みの画面は認証先を変えても復帰しない。
+     * 復帰させるなら settle() が消したタイマー群も張り直す必要があり、終了画面を
+     * 出したまま裏で再試行が走る状態を招く。再読み込みを復帰手段とする。
+     */
+    const restartIfAuthTargetChanged = useCallback((nextApiBase) => {
+        if (previousApiBaseRef.current === nextApiBase)
+            return;
+        previousApiBaseRef.current = nextApiBase;
+        exchangeGenerationRef.current += 1;
+        exchangingRef.current = false;
+        // 旧 API のトークンは新しい認証先では通らない。保持判定から外す
+        sessionRef.current = null;
+        // NOTE: これ以降、旧トークンについての 401 は照合に失敗して捨てられる。
+        // 旧トークンで復帰を始めても新しい認証先では通らないので意味がない。
+        // 復帰はメッセージ effect が送り直す ready と、下で張る見張りが担う。
+        currentTokenRef.current = null;
+        // 認証先ごとに試行回数を数え直す。引き継ぐと上限の手前から始まることになり、
+        // armCodeRetry は上限判定を送信より先に行うため、新しい認証先へ
+        // code-request を 1 通も送らないまま打ち切られる。
+        //
+        // NOTE: 上限に達するには同じ認証先が 1 分ほど続く必要がある。それより短い
+        // 間隔で認証先が変わり続ける限り打ち切りには達しない。apiBase は
+        // resolveApiBase の純粋な結果で、ページの寿命の間は変わらない前提。
+        recoveryAttemptsRef.current = 0;
+        authErrorCyclesRef.current = 0;
+        authErrorRunStartedAtRef.current = 0;
+        // ready はメッセージ effect が送り直す。ここでは応答が無かったときの
+        // 見張りだけ張る
+        armCodeRetryRef.current();
+        // NOTE: 先回り更新のタイマーはここで消さない。refreshTimerRef は打ち切り後の
+        // 失効タイマー（scheduleExpiryCutoff）も兼ねており、消すと「セッション期限切れ」
+        // へ落ちなくなる。旧セッションの期限で残っても、交換が成功した時点で
+        // scheduleRefresh が張り替えるため実害はない。
+    }, []);
+    useEffect(() => {
+        restartIfAuthTargetChanged(apiBase);
+    }, [apiBase, restartIfAuthTargetChanged]);
     useEffect(() => {
         const handleMessage = (event) => {
             var _a;
@@ -382,7 +515,16 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
         // If the host never sends a code (e.g. mintSfaKitExchangeCode is not
         // implemented or the host page doesn't support the embed protocol),
         // show an error instead of hanging on "Connecting..." forever.
-        const codeTimeout = setTimeout(() => {
+        //
+        // NOTE: settle では閉じない。ホストが遅いだけなら、期限を過ぎて届いた
+        // コードでそのまま復帰できる。打ち切ってしまうと、有効なコードが数秒後に
+        // 来ているのに再読み込みするまで死んだままになる。
+        //
+        // 待ち状態のときだけ出す。この判定が effect の張り直しも兼ねる — 既に
+        // 認証済み・交換中・別の理由で打ち切り済みなら、どれも
+        // waiting_for_code ではないので、より正確な表示を上書きしない。
+        codeTimeoutRef.current = setTimeout(() => {
+            codeTimeoutRef.current = null;
             setPhase(current => {
                 if (current.step !== 'waiting_for_code')
                     return current;
@@ -393,12 +535,40 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
                 };
             });
         }, CODE_TIMEOUT_SECONDS * 1000);
+        // NOTE: 消すのはこの effect が張ったコード待ちタイマーだけ。更新・再試行の
+        // タイマーはこの effect の持ち物ではなく、フックが載っている間ずっと生きる。
+        // ここで消すと、認証済みのまま apiBase や trustedOrigin が変わっただけで
+        // 先回り更新が失われ、誰も張り直さないままトークンが期限切れになる。
         return () => {
             window.removeEventListener('message', handleMessage);
-            clearTimeout(codeTimeout);
-            clearRefreshTimer();
-            clearRetryTimer();
+            clearCodeTimeout();
         };
-    }, [trustedOrigin, handleCodeReceived, clearRefreshTimer, clearRetryTimer]);
+    }, [trustedOrigin, handleCodeReceived, clearCodeTimeout]);
+    // NOTE: 解体は依存を持たない effect に分ける。上のメッセージ effect の後片付けは
+    // 依存の同一性が変わるたびに走るので、そこで世代を進めると、認証先は同じままの
+    // 張り直しでも進行中の交換が捨てられる。認証先が変わった場合の破棄は専用の
+    // effect（authTargetRef）が担う。ここは本当にアンマウントするときだけ走る。
+    useEffect(() => {
+        // ref は再マウントを越えて残る。StrictMode や Fast Refresh は
+        // マウント → 解体 → 再マウントと走るので、ここで戻さないと
+        // handleAuthError が最初の行で return し続け、401 から復帰できなくなる。
+        isTornDownRef.current = false;
+        return () => {
+            isTornDownRef.current = true;
+            // 解体後に解決した交換で、この下で消すタイマーを張り直させない。
+            // 世代を進めると handleCodeReceived が結果を捨てる。進行中の交換は
+            // どれも現行世代のものではなくなるため、居座り判定も解除する。
+            exchangeGenerationRef.current += 1;
+            exchangingRef.current = false;
+            // NOTE: clearRefreshTimer / clearRetryTimer は経由せず直接消す。経由すると
+            // 依存配列が空でなくなり、「アンマウント時だけ」がそれらの同一性の安定に
+            // 依存する。両者は settle → armCodeRetry → scheduleRefresh →
+            // handleCodeReceived まで伝播しているため、影響範囲が広い。
+            if (refreshTimerRef.current != null)
+                clearTimeout(refreshTimerRef.current);
+            if (retryTimerRef.current != null)
+                clearTimeout(retryTimerRef.current);
+        };
+    }, []);
     return { phase, handleAuthError };
 }

package/src/lib/provider/SfaClient.d.ts

@@ -124,6 +124,19 @@ export declare class SfaClient implements SfaClientInterface {
     private objectsPath;
     /** @description Returns the field-types catalog path for the current mode. */
     private fieldTypesPath;
+    /**
+     * @description Sets the auth headers, returning the token it used.
+     *
+     * NOTE: the caller keeps that token so a 401 can name it. Reading `this.auth`
+     * at the 401 would give the same value today — `auth` is readonly and
+     * `SfaProvider` builds a new client per token — but returning it from here
+     * keeps the answer true by construction.
+     *
+     * NOTE: this owns the `Authorization` header. It runs after any caller
+     * headers are spread in, so a caller-supplied one is overwritten — and if
+     * the client has no auth, the returned `undefined` would not describe it.
+     * Callers pass `If-Match` and the like, never `Authorization`.
+     */
     private applyAuth;
     /**
      * @description GET request with auth headers. Works for all read-only

package/src/lib/provider/SfaClient.js

@@ -388,14 +388,31 @@ export class SfaClient {
         return this.mode === 'direct' ? '/v1/field-types' : '/field-types';
     }
     // ── Private transport ──
+    /**
+     * @description Sets the auth headers, returning the token it used.
+     *
+     * NOTE: the caller keeps that token so a 401 can name it. Reading `this.auth`
+     * at the 401 would give the same value today — `auth` is readonly and
+     * `SfaProvider` builds a new client per token — but returning it from here
+     * keeps the answer true by construction.
+     *
+     * NOTE: this owns the `Authorization` header. It runs after any caller
+     * headers are spread in, so a caller-supplied one is overwritten — and if
+     * the client has no auth, the returned `undefined` would not describe it.
+     * Callers pass `If-Match` and the like, never `Authorization`.
+     */
     applyAuth(headers) {
         var _a;
-        if ((_a = this.auth) === null || _a === void 0 ? void 0 : _a.accessToken) {
-            headers['Authorization'] = `Bearer ${this.auth.accessToken}`;
+        const accessToken = (_a = this.auth) === null || _a === void 0 ? void 0 : _a.accessToken;
+        if (accessToken) {
+            headers['Authorization'] = `Bearer ${accessToken}`;
         }
         if (this.organizationId) {
             headers['organization-id'] = this.organizationId;
         }
+        // NOTE: 空文字は「トークンを送っていない」。値として返すと、受け手は
+        // 差し替え済みの遅れ着信と区別できず、認証なしの 401 を握り潰す
+        return accessToken || undefined;
     }
     /**
      * @description GET request with auth headers. Works for all read-only
@@ -408,7 +425,7 @@ export class SfaClient {
             const headers = {
                 'Content-Type': 'application/json',
             };
-            this.applyAuth(headers);
+            const sentToken = this.applyAuth(headers);
             const response = yield globalThis.fetch(url, {
                 method: 'GET',
                 headers,
@@ -416,7 +433,7 @@ export class SfaClient {
             });
             if (!response.ok) {
                 if (response.status === 401)
-                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this);
+                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this, sentToken);
                 const text = yield response.text().catch(() => '');
                 throw new SfaApiError(response.status, response.statusText, text, url);
             }
@@ -434,7 +451,7 @@ export class SfaClient {
             const headers = {
                 'Content-Type': 'application/json',
             };
-            this.applyAuth(headers);
+            const sentToken = this.applyAuth(headers);
             const response = yield globalThis.fetch(url, {
                 method: 'POST',
                 headers,
@@ -443,7 +460,7 @@ export class SfaClient {
             });
             if (!response.ok) {
                 if (response.status === 401)
-                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this);
+                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this, sentToken);
                 const text = yield response.text().catch(() => '');
                 throw new SfaApiError(response.status, response.statusText, text, url);
             }
@@ -460,7 +477,7 @@ export class SfaClient {
             var _a;
             const url = `${this.apiBase}${path}`;
             const headers = Object.assign({ 'Content-Type': 'application/json' }, options === null || options === void 0 ? void 0 : options.headers);
-            this.applyAuth(headers);
+            const sentToken = this.applyAuth(headers);
             const response = yield globalThis.fetch(url, {
                 method,
                 headers,
@@ -469,7 +486,7 @@ export class SfaClient {
             });
             if (!response.ok) {
                 if (response.status === 401)
-                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this);
+                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this, sentToken);
                 const text = yield response.text().catch(() => '');
                 if (response.status === 412) {
                     throw SfaConflictError.fromBody(response.status, response.statusText, text, url);

package/src/lib/provider/SfaProvider.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { SfaApiMode, SfaAuth, SfaClientInterface } from './types';
+import type { SfaApiMode, SfaAuth, SfaAuthErrorHandler, SfaClientInterface } from './types';
 export interface SfaContextValue {
     readonly client: SfaClientInterface;
     readonly auth: SfaAuth | undefined;
@@ -14,7 +14,7 @@ interface SfaProviderProps {
     readonly auth?: SfaAuth;
     readonly mode?: SfaApiMode;
     readonly organizationId?: string;
-    readonly onAuthError?: () => void;
+    readonly onAuthError?: SfaAuthErrorHandler;
     /**
      * Disable mutation hooks (create/update/delete). Defaults to false.
      *

package/src/lib/provider/SfaProvider.js

@@ -38,7 +38,7 @@ export function SfaProvider({ apiBase, auth, mode, organizationId, onAuthError,
         auth: stableAuth,
         mode: resolvedMode,
         organizationId: resolvedOrgId,
-        onAuthError: () => { var _a; return (_a = onAuthErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onAuthErrorRef); },
+        onAuthError: rejectedToken => { var _a; return (_a = onAuthErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onAuthErrorRef, rejectedToken); },
     }), [apiBase, stableAuth, resolvedMode, resolvedOrgId]);
     const value = useMemo(() => ({
         client,

package/src/lib/provider/types.d.ts

@@ -2,12 +2,23 @@ export interface SfaAuth {
     readonly accessToken: string;
 }
 export type SfaApiMode = 'direct' | 'proxy';
+/**
+ * @description Called when a request came back 401, naming the token it was
+ * sent with.
+ *
+ * `rejectedToken` is the access token that request carried, or `undefined`
+ * when it went out unauthenticated. A caller that swaps tokens needs it to
+ * tell a late reply about a token it has already replaced from a rejection of
+ * the one it holds now: the first is nothing to act on, the second means the
+ * session has to be re-established.
+ */
+export type SfaAuthErrorHandler = (rejectedToken: string | undefined) => void;
 export interface SfaClientConfig {
     readonly apiBase: string;
     readonly auth?: SfaAuth;
     readonly mode: SfaApiMode;
     readonly organizationId?: string;
-    readonly onAuthError?: () => void;
+    readonly onAuthError?: SfaAuthErrorHandler;
 }
 /**
  * @description Normalized field kinds aligned with keystone's 10-type model.

package/src/lib/version.d.ts

@@ -1 +1 @@
-export declare const SFA_KIT_VERSION = "1.17.0";
+export declare const SFA_KIT_VERSION = "1.18.0";

package/src/lib/version.js

@@ -1,3 +1,3 @@
 // このファイルは libs/sfa-kit/scripts/sync-version.cjs が生成する。
 // 手で編集しないこと。バージョンを上げるときは libs/sfa-kit/package.json を変更する。
-export const SFA_KIT_VERSION = '1.17.0';
+export const SFA_KIT_VERSION = '1.18.0';