@geniee-inc/sfa-kit 1.17.0 → 1.19.0

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/bundle/build-static-bundle.d.ts

@@ -1,17 +1,18 @@
-import type { BundleManifest } from '../signing/types.js';
+import type { BundleManifest, ContentHashManifest } from '../signing/types.js';
 export interface BuildStaticBundleOptions {
     /** Entry module that mounts the page, e.g. `entry.tsx`. */
     readonly entry: string;
     /** Directory the bundle is written to. Created if absent. */
     readonly outDir: string;
     /**
-     * The Studio build version this bundle targets — not the sfa-kit npm version.
+     * @deprecated Omit it. The bundle is then signed over `content_hash` alone.
      *
-     * NOTE: required on purpose. The signature covers
-     * `"{studio_version}:{content_hash}"` and Keystone reads the field back
-     * separately, so a default would sign the wrong version perfectly well.
+     * When given, the bundle is signed in the legacy format, over
+     * `"{studio_version}:{content_hash}"`, and the value is written to the
+     * manifest. Kept so that builds which still pass it keep producing a manifest
+     * with `studio_version`. Keystone accepts both formats.
      */
-    readonly studioVersion: string;
+    readonly studioVersion?: string;
     /** Keystone API base, e.g. `https://keystone-api-staging.chikyu.mobi`. */
     readonly apiBase: string;
     /** The same Bearer token the rest of the Keystone API is called with. */
@@ -19,17 +20,32 @@ export interface BuildStaticBundleOptions {
     /** Title of the generated `index.html`. */
     readonly title?: string;
     /**
-     * Extra manifest fields, e.g. `name` or `displayName`. Keystone ignores
-     * everything but the three signed fields, which cannot be overridden here.
+     * Extra manifest fields, e.g. `name` or `displayName`. Keystone ignores them.
+     * The fields this builder writes (`content_hash`, `signature`,
+     * `sfa_kit_version` and `studio_version`) cannot be set here.
      */
     readonly manifestExtras?: Readonly<Record<string, unknown>>;
 }
+/**
+ * @deprecated Omit `studioVersion`. Given one, the bundle is signed in the
+ * legacy format, over `"{studio_version}:{content_hash}"`, and the manifest
+ * carries `studio_version` beside `sfa_kit_version`. See the next overload for
+ * everything else this function does.
+ *
+ * NOTE: the order of the three overloads matters, since a call resolves to the
+ * first that matches: a `studioVersion` string here, none next, and one known
+ * only at run time (`string | undefined`) last.
+ */
+export declare function buildStaticBundle(options: BuildStaticBundleOptions & {
+    readonly studioVersion: string;
+}): Promise<BundleManifest & Pick<ContentHashManifest, 'sfa_kit_version'>>;
 /**
  * @description Builds the framework-free static bundle a page is uploaded as
- * to become a custom tab, and signs it.
+ * to become a custom tab, and signs it over `content_hash` alone.
  *
  * Produces `index.html`, `assets/bundle.js` and a signed `manifest.json` in
- * `outDir`. The caller zips that directory's contents — the files have to sit
+ * `outDir`. The manifest records this package's version as `sfa_kit_version`.
+ * The caller zips that directory's contents — the files have to sit
  * at the zip root. Zipping is left out because Node ships no zip writer, and a
  * dependency for it would reach a package whose runtime needs only `tslib`.
  *
@@ -42,4 +58,14 @@ export interface BuildStaticBundleOptions {
  *
  * @returns The manifest that was written.
  */
-export declare function buildStaticBundle({ entry, outDir, studioVersion, apiBase, accessToken, title, manifestExtras, }: BuildStaticBundleOptions): Promise<BundleManifest>;
+export declare function buildStaticBundle(options: BuildStaticBundleOptions & {
+    readonly studioVersion?: undefined;
+}): Promise<ContentHashManifest>;
+/**
+ * For a `studioVersion` known only at run time (`string | undefined`), such as
+ * a forwarded command-line flag. The result is the legacy manifest when one is
+ * given and the current format otherwise, so `studio_version` reads as
+ * `string | undefined`. See the previous overload for everything else this
+ * function does.
+ */
+export declare function buildStaticBundle(options: BuildStaticBundleOptions): Promise<ContentHashManifest | (BundleManifest & Pick<ContentHashManifest, 'sfa_kit_version'>)>;

package/src/lib/bundle/build-static-bundle.js

@@ -3,8 +3,9 @@ import { mkdir, readFile, readdir, rm, stat, writeFile, } from 'node:fs/promises
 import { join, posix, relative } from 'node:path';
 import { computeContentHash } from '../signing/compute-content-hash.js';
 import { readBundleFiles } from '../signing/read-bundle-files.js';
+import { SFA_KIT_VERSION } from '../version.js';
 import { loadEsbuild } from './esbuild-loader.js';
-import { requestSignature } from './request-signature.js';
+import { isHexDigest, requestSignature } from './request-signature.js';
 /** Where the bundled script lands inside the output directory. */
 const BUNDLE_PATH = 'assets/bundle.js';
 /** esbuild writes this beside the script when the entry imports any CSS. */
@@ -31,29 +32,23 @@ const UNEXPECTED_SHOWN = 5;
  */
 const JUNK_FILES = new Set(['.DS_Store', 'Thumbs.db']);
 /**
- * @description Builds the framework-free static bundle a page is uploaded as
- * to become a custom tab, and signs it.
+ * Manifest keys this builder writes. A caller's `manifestExtras` never set them.
  *
- * Produces `index.html`, `assets/bundle.js` and a signed `manifest.json` in
- * `outDir`. The caller zips that directory's contents — the files have to sit
- * at the zip root. Zipping is left out because Node ships no zip writer, and a
- * dependency for it would reach a package whose runtime needs only `tslib`.
- *
- * Signing is not optional, and a failure removes the output: an unsigned bundle
- * uploads successfully while Keystone's verifier runs in `disabled` mode and
- * only starts failing at `enforced`, so a half-built directory left behind is
- * something a caller can still zip and upload by mistake.
- *
- * **Node.js only**, and needs `esbuild` installed alongside the kit.
- *
- * @returns The manifest that was written.
+ * NOTE: `studio_version` is listed even for builds that leave it out. Keystone
+ * checks a manifest carrying one in the legacy format, so an extra holding it
+ * would turn a correctly signed bundle into a 422.
  */
+const OWN_MANIFEST_KEYS = new Set([
+    'studio_version',
+    'sfa_kit_version',
+    'content_hash',
+    'signature',
+]);
 export function buildStaticBundle(_a) {
     return __awaiter(this, arguments, void 0, function* ({ entry, outDir, studioVersion, apiBase, accessToken, title = 'SFA/CRM', manifestExtras = {}, }) {
         for (const [name, value] of [
             ['entry', entry],
             ['outDir', outDir],
-            ['studioVersion', studioVersion],
             ['apiBase', apiBase],
             ['accessToken', accessToken],
         ]) {
@@ -66,6 +61,11 @@ export function buildStaticBundle(_a) {
                 throw new Error(`${name} is required and must not be empty`);
             }
         }
+        // NOTE: refused rather than read as "omitted". The overloads promise a
+        // manifest carrying studio_version whenever a studioVersion is passed.
+        if (studioVersion != null && studioVersion.trim() === '') {
+            throw new Error('studioVersion must not be empty. Omit it to sign content_hash alone.');
+        }
         // Serialised now so a value that cannot be JSON — cyclic, a BigInt — fails
         // before anything is written, rather than after Keystone has signed.
         assertSerialisable(manifestExtras);
@@ -90,20 +90,27 @@ export function buildStaticBundle(_a) {
             // manifest.json is written last: the hash covers every other file, so the
             // directory has to be complete before it is computed.
             const contentHash = computeContentHash(yield readBundleFiles(outDir));
-            const manifest = {
-                studio_version: studioVersion,
-                content_hash: contentHash,
-                signature: yield requestSignature({
-                    apiBase,
-                    accessToken,
-                    studioVersion,
-                    contentHash,
-                }),
-            };
-            yield writeFile(join(outDir, 'manifest.json'), 
-            // NOTE: the decorative fields go first so the three signed ones cannot be
-            // overwritten by a caller's extras.
-            `${JSON.stringify(Object.assign(Object.assign({}, manifestExtras), manifest), null, 2)}\n`, 'utf-8');
+            const signature = yield requestSignature({
+                apiBase,
+                accessToken,
+                studioVersion,
+                contentHash,
+            });
+            // NOTE: one object per format, not a conditional spread. The current
+            // format must not carry `studio_version` at all (see ContentHashManifest).
+            const manifest = studioVersion == null
+                ? {
+                    sfa_kit_version: SFA_KIT_VERSION,
+                    content_hash: contentHash,
+                    signature,
+                }
+                : {
+                    studio_version: studioVersion,
+                    sfa_kit_version: SFA_KIT_VERSION,
+                    content_hash: contentHash,
+                    signature,
+                };
+            yield writeFile(join(outDir, 'manifest.json'), `${JSON.stringify(Object.assign(Object.assign({}, withoutOwnKeys(manifestExtras)), manifest), null, 2)}\n`, 'utf-8');
             return manifest;
         }
         catch (thrown) {
@@ -118,6 +125,16 @@ export function buildStaticBundle(_a) {
         }
     });
 }
+/**
+ * Drops the keys this builder writes from a caller's extras.
+ *
+ * NOTE: spreading the extras first is not enough. A build without a
+ * studioVersion writes no `studio_version`, so one in the extras would survive
+ * the spread; {@link OWN_MANIFEST_KEYS} says why it must not reach the manifest.
+ */
+function withoutOwnKeys(extras) {
+    return Object.fromEntries(Object.entries(extras).filter(([key]) => !OWN_MANIFEST_KEYS.has(key)));
+}
 /** Fails now on a value `JSON.stringify` would reject after the bundle is signed. */
 function assertSerialisable(extras) {
     try {
@@ -140,8 +157,8 @@ function assertSerialisable(extras) {
  *
  * NOTE: matching those names is not enough to claim the directory. `index.html`
  * beside `assets/bundle.js` is also what a hand-written static site looks like,
- * and deleting one would be unrecoverable. A `manifest.json` carrying the three
- * signed fields is the proof, because only this builder writes one.
+ * and deleting one would be unrecoverable. The manifest is the proof; see
+ * {@link hasOwnManifest} for what counts.
  */
 function prepareOutDir(outDir) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -205,7 +222,24 @@ function prepareOutDir(outDir) {
         yield removeOwnOutput(outDir);
     });
 }
-/** Whether the directory carries a manifest only this builder could have written. */
+/**
+ * @description Whether the directory holds a previous build this builder may
+ * overwrite.
+ *
+ * NOTE: `content_hash` and `signature` alone are not proof. Any signed bundle
+ * carries them, and accepting one would let a rebuild delete another bundle's
+ * files. Each format also needs its version field: `sfa_kit_version` in the
+ * current format, `studio_version` in the legacy one (the condition earlier
+ * releases used).
+ *
+ * Neither field proves this builder wrote the manifest. GUIDE.md's hand-built
+ * flow writes `sfa_kit_version` too, and `createManifest` or a hand-run
+ * equivalent writes `studio_version`. Both identify a bundle built through
+ * sfa-kit, not this builder alone. Nothing in a manifest narrows it further,
+ * and refusing those would block rebuilding over existing output directories.
+ * What is lost is bounded: only the paths in `OWN_OUTPUT` are removed, and any
+ * other file stops the build first.
+ */
 function hasOwnManifest(outDir) {
     return __awaiter(this, void 0, void 0, function* () {
         const raw = yield readFile(join(outDir, 'manifest.json'), 'utf-8').catch(() => null);
@@ -213,13 +247,19 @@ function hasOwnManifest(outDir) {
             return false;
         try {
             const parsed = JSON.parse(raw);
-            return ['studio_version', 'content_hash', 'signature'].every(field => typeof parsed[field] === 'string' && parsed[field] !== '');
+            const hasHexDigests = isHexDigest(parsed['content_hash']) && isHexDigest(parsed['signature']);
+            const hasVersionField = isNonEmptyString(parsed['sfa_kit_version']) ||
+                isNonEmptyString(parsed['studio_version']);
+            return hasHexDigests && hasVersionField;
         }
         catch (_a) {
             return false;
         }
     });
 }
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}
 /**
  * @description Deletes the files this builder writes, and nothing else.
  *

package/src/lib/bundle/request-signature.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Whether `value` has the shape Keystone gives `content_hash` and `signature`.
+ *
+ * NOTE: shared with the builder's previous-build check, so the shape the
+ * signer accepts and the shape a rebuild recognises cannot drift apart.
+ */
+export declare function isHexDigest(value: unknown): value is string;
 /**
  * @description Asks Keystone to sign a bundle, returning the signature.
  *
@@ -6,6 +13,11 @@
  * per project while the key must be identical across all of them (SFAJAI-186).
  * The caller computes `contentHash` locally and Keystone signs it.
  *
+ * Without `studioVersion`, Keystone signs `contentHash` alone. With it, Keystone
+ * returns the legacy signature over `"{studio_version}:{content_hash}"`, and the
+ * caller must write the same `studio_version` into the manifest for it to
+ * verify.
+ *
  * NOTE: every failure throws. An unsigned bundle uploads successfully while
  * Keystone's verifier runs in `disabled` mode, so returning "no signature" here
  * would produce an artifact that looks fine and starts being rejected the day
@@ -17,6 +29,6 @@
 export declare function requestSignature({ apiBase, accessToken, studioVersion, contentHash, }: {
     readonly apiBase: string;
     readonly accessToken: string;
-    readonly studioVersion: string;
+    readonly studioVersion?: string;
     readonly contentHash: string;
 }): Promise<string>;