@geniee-inc/sfa-kit 1.14.1 → 1.17.0

package/GUIDE.md

@@ -21,7 +21,97 @@ import pkg from '@geniee-inc/sfa-kit/package.json';
 // pkg.version -> '1.14.0'
 ```
 
-Two additional subpaths are available: `@geniee-inc/sfa-kit/signing` exposes bundle-signing utilities (`computeContentHash`, `computeSignature`, `createManifest`, `createManifestFromDirectory`) for Node.js environments, and `./package.json` exposes the manifest. Internal modules cannot be imported directly.
+Three additional subpaths are available: `@geniee-inc/sfa-kit/signing` exposes bundle-manifest utilities, `@geniee-inc/sfa-kit/bundle` builds and signs a static bundle in one call (both Node.js-only), and `./package.json` exposes the manifest. Internal modules cannot be imported directly.
+
+### Static bundle manifest (custom-tab uploads)
+
+A page uploaded through GENIEE's SFA/CRM settings UI as a custom tab is a framework-free static bundle — `index.html` + `manifest.json` + `assets/` — not a Next.js app. Its `manifest.json` carries the three fields Keystone's `BundleSignatureVerifier` reads: `studio_version`, `content_hash`, `signature`.
+
+**The signing key lives only in Keystone, so a page build never computes the signature itself.** It hashes the bundle locally and asks Keystone to sign:
+
+```ts
+import {
+  readBundleFiles,
+  computeContentHash,
+} from '@geniee-inc/sfa-kit/signing';
+import type { BundleManifest } from '@geniee-inc/sfa-kit/signing';
+
+const files = await readBundleFiles('dist');
+const contentHash = computeContentHash(files);
+
+// Keystone holds the signing key, so ask it for the signature. The Bearer token
+// is the same one the rest of the API is called with.
+const response = await fetch(`${apiBase}/v1/pages/sign`, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${accessToken}`,
+  },
+  body: JSON.stringify({
+    studio_version: studioVersion,
+    content_hash: contentHash,
+  }),
+});
+if (!response.ok) throw new Error(`Signing failed: ${response.status}`);
+const { signature } = (await response.json()) as { signature: string };
+
+const manifest: BundleManifest = {
+  studio_version: studioVersion, // the Studio build version, NOT the sfa-kit npm version
+  content_hash: contentHash,
+  signature,
+};
+```
+
+### Building the bundle
+
+`@geniee-inc/sfa-kit/bundle` does the whole build in one call: it bundles the entry module with esbuild, writes `index.html`, hashes the result, gets the signature from Keystone and writes `manifest.json`.
+
+```ts
+import { buildStaticBundle } from '@geniee-inc/sfa-kit/bundle';
+
+await buildStaticBundle({
+  entry: 'entry.tsx', // renders <SfaLoginGate>…</SfaLoginGate> into #root
+  outDir: 'dist',
+  studioVersion: '0.5.0', // the Studio build version, NOT the sfa-kit npm version
+  apiBase: 'https://keystone-api-staging.chikyu.mobi',
+  accessToken: token,
+});
+```
+
+Or from the command line, which is the shorter path when a build script drives it:
+
+```bash
+SFA_KIT_ACCESS_TOKEN=<token> npx sfa-kit-bundle \
+  --entry entry.tsx \
+  --out dist \
+  --studio-version 0.5.0 \
+  --api-base https://keystone-api-staging.chikyu.mobi
+```
+
+The token comes from the environment rather than a flag, so it stays out of shell history and the process list.
+
+Then zip the **contents** of `dist/` — the bundle's files have to sit at the zip root, not inside a wrapper folder. Zipping is left to the caller: Node ships no zip writer, and every caller already has one.
+
+`esbuild` is an optional peer dependency; install it alongside the kit. Its options are fixed: JS, JSX, TS and CSS bundle, but there is no loader for images or fonts, so a page importing a `.png`, `.svg` or a font — including through `url()` in CSS — fails to build. Inline such assets as data URIs, or reference them by absolute URL.
+Nothing is written when signing fails, so a failed build never leaves an unsigned bundle behind to be uploaded by mistake.
+
+`studioVersion` has no default on purpose. The signature covers `"{studio_version}:{content_hash}"` and Keystone reads the field back separately, so a guessed value produces a valid signature over the wrong version.
+
+### Signing exports
+
+The lower-level pieces `buildStaticBundle` uses, for a caller that builds its own way:
+
+| Export                        | Needs the signing key |
+| ----------------------------- | --------------------- |
+| `readBundleFiles`             | No                    |
+| `computeContentHash`          | No                    |
+| `computeSignature`            | **Yes**               |
+| `createManifest`              | **Yes**               |
+| `createManifestFromDirectory` | **Yes**               |
+
+The three key-taking exports exist for the service that holds the key. Calling them from a page build means inventing a key, which Keystone will not accept — and the mistake is invisible at first, because bundle verification ships in `disabled` mode: the upload succeeds, and only starts failing once the mode is switched to `enforced`.
+
+`content_hash` must come from `computeContentHash`, never from hashing files back to back. The algorithm length-prefixes each path and each file's contents before feeding them into one running SHA-256; without those prefixes `"ab" + "c"` and `"a" + "bc"` hash identically, and the result never matches Keystone's own computation.
 
 ## Architecture
 
@@ -286,9 +376,11 @@ that did land, and those are not recoverable anywhere else.
   whole picture leaves it looking neither written nor retryable. Re-read the
   records to find out what landed
 - `failed` — the rows that did not land **and can be sent again**: `conflict`,
-  `invalid` and `not_attempted`. Retry exactly these. What makes that safe is
-  that they did not apply; there is no server-side de-duplication to fall back
-  on
+  `invalid`, `not_attempted`, `not_found` and `not_permitted`. Retry exactly
+  these. What makes that safe is that they did not apply; there is no
+  server-side de-duplication to fall back on. Read each row's `status` before
+  offering a retry: `not_found` and `not_permitted` are the server's settled
+  answer, and resending alone will not change it
 - `unresolved` — the rows that may already be written but cannot be reported
   either way. They keep whatever `id` arrived. **Re-read these; never retry
   them**: a create that already landed would be written twice
@@ -375,7 +467,9 @@ return (
       <ErrorSnackbar
         error={null}
         message={`${results.length} 件中 ${updated.length} 件を保存しました。${failed.length} 件は保存されていません。`}
-        onRetry={() => void bulkUpdate(rowsFor(failed)).catch(() => undefined)}
+        onRetry={() =>
+          void bulkUpdate(rowsFor(resendable(failed))).catch(() => undefined)
+        }
         onClose={reset}
       />
     )}
@@ -385,17 +479,42 @@ return (
 
 Counts only: which row failed and why belongs in the grid, where the reader
 acts on it — `results` carries each row's `index` and its per-field errors.
-Offer `onRetry` for `failed` rows; `unresolved` rows are re-read instead, so
-label the action accordingly (`retryLabel`).
+`unresolved` rows are re-read instead, so label the action accordingly
+(`retryLabel`).
+
+Offer `onRetry` for the `failed` rows a resend can still change — that is what
+`resendable` stands for above:
+
+```tsx
+const SETTLED = new Set(['not_found', 'not_permitted']);
+
+const resendable = (rows: readonly SfaBulkRowResult[]) =>
+  rows.filter(row => !SETTLED.has(row.status));
+```
+
+Every row in `failed` is safe to send again, but a `not_found` or
+`not_permitted` one comes back refused however often it is sent. Showing those
+under a retry button gives the reader an action that cannot succeed; report
+what they say instead.
 
 A row counts as written only when it carries what a write produces: the record
 for a create or an update, the id for a delete. Anything short of that is
 `failed` or `unresolved`, and which one is decided by what the answer says,
-not by elimination. Three statuses mean the row did not apply, and only those
-may be sent again: `conflict`, `invalid`, and `not_attempted` — the last for a
-row the call ran out of budget before starting, which is resent exactly as it
-was. A `conflict` carries the server's current record: retry with the
-`version` it reports, or re-read first if none arrived.
+not by elimination. Five statuses mean the row did not apply, and only those
+may be sent again:
+
+| Status          | What it means                                      | What to do                                                                 |
+| --------------- | -------------------------------------------------- | -------------------------------------------------------------------------- |
+| `conflict`      | Another write got there first                      | Retry with the `version` the row reports, or re-read first if none arrived |
+| `invalid`       | The row failed validation                          | Correct the row from its per-field errors, then resend                     |
+| `not_attempted` | The call ran out of budget before starting the row | Resend exactly as it was                                                   |
+| `not_found`     | The record the row named does not exist            | Tell the reader; a resend answers the same                                 |
+| `not_permitted` | The caller may not write that record               | Tell the reader; a resend answers the same                                 |
+
+`not_found` and `not_permitted` are refusals of a row the call did reach, so no
+write happened and resending is safe — it is simply futile until the record or
+the permission changes. Their `error.code` may be an empty string: keystone has
+not minted one for `not_permitted`, so branch on `status` rather than `code`.
 
 Everything else is `unresolved`: `indeterminate`, the server saying it cannot
 tell whether the row applied; a claimed success missing what it should carry —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geniee-inc/sfa-kit",
-  "version": "1.14.1",
+  "version": "1.17.0",
   "description": "React hooks and components for building pages that connect to GENIEE SFA/CRM data.",
   "type": "module",
   "main": "./src/index.js",
@@ -17,8 +17,19 @@
       "import": "./src/signing.js",
       "default": "./src/signing.js"
     },
+    "./bundle": {
+      "types": "./src/bundle.d.ts",
+      "import": "./src/bundle.js",
+      "default": "./src/bundle.js"
+    },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "sfa-kit-bundle": "./src/bin/sfa-kit-bundle.js"
+  },
+  "engines": {
+    "node": ">=20.1.0"
+  },
   "sideEffects": false,
   "files": [
     "src",
@@ -33,9 +44,15 @@
   "license": "MIT",
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "esbuild": ">=0.18.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"
+  },
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    }
   }
 }

package/src/bin/sfa-kit-bundle.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * @description Runs the bundler from the command line.
+ *
+ * Exported so the test suite drives the same entry point the `bin` does, and
+ * so a caller embedding it can pass argv explicitly.
+ *
+ * @returns The process exit code. 0 on success, 1 on any failure.
+ */
+export declare function runBundleCli(argv: readonly string[], env: Readonly<Record<string, string | undefined>>, out: {
+    log(message: string): void;
+    error(message: string): void;
+}): Promise<number>;

package/src/bin/sfa-kit-bundle.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import { __awaiter } from "tslib";
+import { basename } from 'node:path';
+import { parseArgs } from 'node:util';
+import { buildStaticBundle } from '../lib/bundle/index.js';
+/** The access token is read from here, never from an argument. */
+const TOKEN_ENV = 'SFA_KIT_ACCESS_TOKEN';
+const USAGE = `sfa-kit-bundle — build and sign a static bundle for an SFA/CRM custom tab
+
+Usage:
+  ${TOKEN_ENV}=<token> npx sfa-kit-bundle \\
+    --entry entry.tsx \\
+    --out dist \\
+    --studio-version 0.5.0 \\
+    --api-base https://keystone-api-staging.chikyu.mobi
+
+Options:
+  --entry           Entry module that mounts the page into #root. Required.
+  --out             Output directory. Required.
+  --studio-version  The Studio build version this bundle targets, not the
+                    sfa-kit npm version. Required.
+  --api-base        Keystone API base, without a trailing slash. Required.
+  --title           <title> of the generated index.html. Default: SFA/CRM.
+  --help            Show this message.
+
+Environment:
+  ${TOKEN_ENV}  Bearer token for Keystone, the same one the rest of the
+  API is called with. Required, and read from the environment rather than an
+  argument so it does not land in shell history or in the process list.
+
+Writes index.html, assets/bundle.js and a signed manifest.json. Zip the
+contents of the output directory — the files have to sit at the zip root.
+Needs esbuild installed alongside the kit.`;
+const OPTIONS = {
+    entry: { type: 'string' },
+    out: { type: 'string' },
+    'studio-version': { type: 'string' },
+    'api-base': { type: 'string' },
+    title: { type: 'string' },
+    help: { type: 'boolean' },
+};
+/**
+ * @description Reads the flags, reporting a malformed command line as data.
+ *
+ * NOTE: `parseArgs` throws on a misspelled flag, a flag with no value, and a
+ * stray positional. Left to propagate, those would reject the promise the bin
+ * only attaches `.then()` to, and the user would get a stack trace where the
+ * usage text belongs.
+ */
+function parseCliOptions(argv) {
+    try {
+        const { values } = parseArgs({
+            args: [...argv],
+            options: OPTIONS,
+            allowPositionals: false,
+        });
+        return { values };
+    }
+    catch (thrown) {
+        return { error: thrown instanceof Error ? thrown.message : String(thrown) };
+    }
+}
+/**
+ * @description Runs the bundler from the command line.
+ *
+ * Exported so the test suite drives the same entry point the `bin` does, and
+ * so a caller embedding it can pass argv explicitly.
+ *
+ * @returns The process exit code. 0 on success, 1 on any failure.
+ */
+export function runBundleCli(argv, env, out) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f;
+        const parsed = parseCliOptions(argv);
+        if (parsed.error != null) {
+            out.error(`${parsed.error}\n\n${USAGE}`);
+            return 1;
+        }
+        const values = parsed.values;
+        if (values.help) {
+            out.log(USAGE);
+            return 0;
+        }
+        const missing = ['entry', 'out', 'studio-version', 'api-base']
+            .filter(name => { var _a; return ((_a = values[name]) !== null && _a !== void 0 ? _a : '') === ''; })
+            .map(name => `--${name}`);
+        const accessToken = (_a = env[TOKEN_ENV]) !== null && _a !== void 0 ? _a : '';
+        if (accessToken === '')
+            missing.push(TOKEN_ENV);
+        if (missing.length > 0) {
+            out.error(`Missing required: ${missing.join(', ')}\n\n${USAGE}`);
+            return 1;
+        }
+        try {
+            const manifest = yield buildStaticBundle(Object.assign({ entry: (_b = values.entry) !== null && _b !== void 0 ? _b : '', outDir: (_c = values.out) !== null && _c !== void 0 ? _c : '', studioVersion: (_d = values['studio-version']) !== null && _d !== void 0 ? _d : '', apiBase: (_e = values['api-base']) !== null && _e !== void 0 ? _e : '', accessToken }, (((_f = values.title) !== null && _f !== void 0 ? _f : '') === '' ? {} : { title: values.title })));
+            out.log(`Built and signed ${values.out} ` +
+                `(studio_version ${manifest.studio_version}, ` +
+                `content_hash ${manifest.content_hash}).`);
+            return 0;
+        }
+        catch (thrown) {
+            // NOTE: buildStaticBundle removes what it wrote, so there is normally
+            // nothing left to upload. The one case where output survives — cleanup
+            // itself failing — says so in its own message.
+            out.error(`${thrown instanceof Error ? thrown.message : String(thrown)}\n` +
+                'Nothing was signed, so nothing is ready to upload.');
+            return 1;
+        }
+    });
+}
+/** True when this module is what node was asked to run, not an import of it. */
+function isEntryPoint() {
+    // NOTE: the file name, not a substring of the path. `includes()` would also
+    // fire for a consumer script under, say, ~/work/sfa-kit-bundle-demo/, which
+    // would start the CLI merely because that script imported runBundleCli.
+    //
+    // `import.meta.url` would be the exact comparison, but Jest transforms this
+    // file to CommonJS, where that syntax does not parse and the whole suite
+    // fails to load.
+    const invoked = process.argv[1];
+    if (invoked == null)
+        return false;
+    const name = basename(invoked);
+    return name === 'sfa-kit-bundle' || name === 'sfa-kit-bundle.js';
+}
+/* istanbul ignore next -- the process wiring is exercised by running the bin */
+if (isEntryPoint()) {
+    // NOTE: no top-level await — the package's module target does not allow it.
+    void runBundleCli(process.argv.slice(2), process.env, {
+        log: message => console.log(message),
+        error: message => console.error(message),
+    })
+        .then(code => {
+        process.exitCode = code;
+    })
+        .catch((thrown) => {
+        // Nothing above should reject, but an unhandled rejection would exit 0
+        // on some Node versions — reporting a failed build as a success.
+        console.error(thrown instanceof Error ? thrown.message : String(thrown));
+        process.exitCode = 1;
+    });
+}

package/src/bundle.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Static bundle builder for GENIEE SFA/CRM custom-tab uploads.
+ *
+ * This subpath export (`@geniee-inc/sfa-kit/bundle`) is Node.js-only and needs
+ * `esbuild` installed alongside the kit. It produces the framework-free
+ * `index.html` + `assets/bundle.js` + signed `manifest.json` a page is uploaded
+ * as; the caller zips the result.
+ *
+ * @example
+ * ```ts
+ * import { buildStaticBundle } from '@geniee-inc/sfa-kit/bundle';
+ *
+ * await buildStaticBundle({
+ *   entry: 'entry.tsx',
+ *   outDir: 'dist',
+ *   studioVersion: '0.5.0',
+ *   apiBase: 'https://keystone-api-staging.chikyu.mobi',
+ *   accessToken: token,
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { BundleManifest } from './lib/signing/index.js';
+export type { BuildStaticBundleOptions } from './lib/bundle/index.js';
+export { buildStaticBundle } from './lib/bundle/index.js';

package/src/bundle.js

@@ -0,0 +1 @@
+export { buildStaticBundle } from './lib/bundle/index.js';

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

@@ -0,0 +1,12 @@
+import { type ReactNode } from 'react';
+interface ObjectKeyGuardProps {
+    readonly objectKey: string;
+    readonly children: ReactNode;
+}
+/**
+ * objectKey が組織のオブジェクトカタログに存在することを検証する。
+ * 不一致の場合はページ本体の代わりにエラーバナーを表示し、
+ * singular / typo のキーがリフレッシュ時に 404 で壊れる前に検出する。
+ */
+export declare function ObjectKeyGuard({ objectKey, children }: ObjectKeyGuardProps): JSX.Element;
+export {};

package/src/lib/auth/ObjectKeyGuard.js

@@ -0,0 +1,61 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useObjectCatalog } from '../hooks/useObjectCatalog';
+import { font, space } from '../theme';
+/**
+ * objectKey が組織のオブジェクトカタログに存在することを検証する。
+ * 不一致の場合はページ本体の代わりにエラーバナーを表示し、
+ * singular / typo のキーがリフレッシュ時に 404 で壊れる前に検出する。
+ */
+export function ObjectKeyGuard({ objectKey, children }) {
+    const { objects, isLoading, error } = useObjectCatalog();
+    // カタログ取得中やエラー時はブロックせずそのまま表示する。
+    // ガードが止めるのは「カタログに無い」と確定した場合のみ。
+    if (isLoading || error || objects.length === 0)
+        return _jsx(_Fragment, { children: children });
+    const knownKeys = objects.map(o => o.key);
+    if (knownKeys.includes(objectKey))
+        return _jsx(_Fragment, { children: children });
+    // 提案のみ大文字小文字を無視する。一致判定は API がキーを厳密比較するため厳密のまま
+    const target = objectKey.toLowerCase();
+    const suggestion = knownKeys.find(knownKey => {
+        const key = knownKey.toLowerCase();
+        return key.startsWith(target) || target.startsWith(key);
+    });
+    return (_jsx("div", { style: {
+            padding: space.lg,
+            fontFamily: font.family,
+            maxWidth: 560,
+            margin: '80px auto',
+        }, children: _jsxs("div", { style: {
+                background: '#FEF2F2',
+                border: '1px solid #FECACA',
+                borderRadius: 8,
+                padding: space.lg,
+            }, children: [_jsx("div", { style: {
+                        fontWeight: 700,
+                        fontSize: 15,
+                        color: '#991B1B',
+                        marginBottom: 8,
+                    }, children: "Invalid object key" }), _jsxs("p", { style: {
+                        margin: 0,
+                        fontSize: 14,
+                        color: '#7F1D1D',
+                        lineHeight: 1.5,
+                    }, children: [_jsx("code", { style: {
+                                background: '#FEE2E2',
+                                padding: '2px 6px',
+                                borderRadius: 4,
+                                fontSize: 13,
+                            }, children: objectKey }), ' ', "does not match any object in this organization.", suggestion && (_jsxs(_Fragment, { children: [' ', "Did you mean", ' ', _jsx("code", { style: {
+                                        background: '#DCFCE7',
+                                        padding: '2px 6px',
+                                        borderRadius: 4,
+                                        fontSize: 13,
+                                        color: '#166534',
+                                    }, children: suggestion }), "?"] }))] }), _jsx("p", { style: {
+                        margin: '12px 0 0',
+                        fontSize: 12,
+                        color: '#9CA3AF',
+                        lineHeight: 1.4,
+                    }, children: "Object keys are the plural collection name from the object catalogue (e.g. \"business_discussions\", not \"business_discussion\"). Check the objectKey prop on SfaLoginGate and the manifest." })] }) }));
+}

package/src/lib/auth/SfaLoginGate.js

@@ -6,6 +6,7 @@ import { color, font, radius, space, baseContainerStyle, baseButtonStyle, } from
 import { SFA_KIT_VERSION } from '../version';
 import { DevToolbar } from './DevToolbar';
 import { authenticate } from './keystone-auth';
+import { ObjectKeyGuard } from './ObjectKeyGuard';
 import { KEYSTONE_PRODUCTION_API_BASE, resolveApiBase, } from './resolve-api-base';
 import { loadSession, saveSession, clearSession, loadLastOrgId, } from './session-store';
 import { StandalonePreviewCtx } from './StandalonePreviewContext';
@@ -102,7 +103,7 @@ export function SfaLoginGate({ apiBase, trustedOrigin, defaultOrganizationId, ob
             return (_jsx(EmbedStatus, { title: "\u63A5\u7D9A\u3067\u304D\u307E\u305B\u3093", message: "SFA/CRM \u306E\u30DB\u30B9\u30C8\u30AA\u30EA\u30B8\u30F3\u3092\u78BA\u8A8D\u3067\u304D\u306A\u3044\u305F\u3081\u3001\u3053\u306E\u30DA\u30FC\u30B8\u3092\u8868\u793A\u3067\u304D\u307E\u305B\u3093\u3002\u57CB\u3081\u8FBC\u307F\u8A2D\u5B9A\u3092\u7BA1\u7406\u8005\u306B\u3054\u78BA\u8A8D\u304F\u3060\u3055\u3044\u3002" }));
         }
         // Embedded: the SFA/CRM host that framed us decides the environment.
-        return (_jsx(EmbedFlow, { trustedOrigin: resolvedOrigin, apiBase: apiBase !== null && apiBase !== void 0 ? apiBase : resolveApiBase(resolvedOrigin), children: children }));
+        return (_jsx(EmbedFlow, { objectKey: objectKey, trustedOrigin: resolvedOrigin, apiBase: apiBase !== null && apiBase !== void 0 ? apiBase : resolveApiBase(resolvedOrigin), children: children }));
     }
     // Standalone: there is no host, so the page's own origin decides.
     return (_jsx(StandaloneFlow, { apiBase: apiBase !== null && apiBase !== void 0 ? apiBase : resolveApiBase(resolvePageOrigin()), defaultOrganizationId: defaultOrganizationId, objectKey: objectKey, level: level, children: children }));
@@ -110,7 +111,7 @@ export function SfaLoginGate({ apiBase, trustedOrigin, defaultOrganizationId, ob
 // ---------------------------------------------------------------------------
 // Embed flow (iframe + postMessage)
 // ---------------------------------------------------------------------------
-function EmbedFlow({ trustedOrigin, apiBase, children, }) {
+function EmbedFlow({ objectKey, trustedOrigin, apiBase, children, }) {
     const normalizedBase = useMemo(() => apiBase.replace(/\/+$/, ''), [apiBase]);
     const { phase, handleAuthError } = useEmbedSession({
         apiBase: normalizedBase,
@@ -135,7 +136,7 @@ function EmbedFlow({ trustedOrigin, apiBase, children, }) {
     }
     if (!auth)
         return null;
-    return (_jsx(EmbedContextValue.Provider, { value: phase.context, children: _jsx(SfaProvider, { apiBase: normalizedBase, auth: auth, mode: "direct", organizationId: phase.session.organizationId, onAuthError: handleAuthError, children: children }) }));
+    return (_jsx(EmbedContextValue.Provider, { value: phase.context, children: _jsx(SfaProvider, { apiBase: normalizedBase, auth: auth, mode: "direct", organizationId: phase.session.organizationId, onAuthError: handleAuthError, children: objectKey ? (_jsx(ObjectKeyGuard, { objectKey: objectKey, children: children })) : (children) }) }));
 }
 function EmbedStatus({ title, message, showReload, }) {
     const handleReload = useCallback(() => {
@@ -241,7 +242,7 @@ function StandaloneFlow({ apiBase, defaultOrganizationId, objectKey, level, chil
     if (!session || !auth) {
         return (_jsx(LoginForm, { defaultApiBase: apiBase, defaultOrganizationId: defaultOrganizationId, onSubmit: handleLogin, status: status, error: error }));
     }
-    return (_jsx(SfaProvider, { apiBase: activeBase, auth: auth, mode: "direct", organizationId: session.organizationId, onAuthError: handleLogout, children: _jsxs(StandalonePreviewCtx.Provider, { value: previewControls, children: [_jsx(DevToolbar, { organizationId: session.organizationId, preview: previewControls, objectKey: objectKey, level: resolvedLevel, onLogout: handleLogout }), children] }) }));
+    return (_jsx(SfaProvider, { apiBase: activeBase, auth: auth, mode: "direct", organizationId: session.organizationId, onAuthError: handleLogout, children: _jsxs(StandalonePreviewCtx.Provider, { value: previewControls, children: [_jsx(DevToolbar, { organizationId: session.organizationId, preview: previewControls, objectKey: objectKey, level: resolvedLevel, onLogout: handleLogout }), objectKey ? (_jsx(ObjectKeyGuard, { objectKey: objectKey, children: children })) : (children)] }) }));
 }
 // ---------------------------------------------------------------------------
 // GENIEE SFA/CRM-branded login form

package/src/lib/bundle/build-static-bundle.d.ts

@@ -0,0 +1,45 @@
+import type { BundleManifest } 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.
+     *
+     * 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.
+     */
+    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. */
+    readonly accessToken: string;
+    /** 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.
+     */
+    readonly manifestExtras?: Readonly<Record<string, unknown>>;
+}
+/**
+ * @description Builds the framework-free static bundle a page is uploaded as
+ * to become a custom tab, and signs it.
+ *
+ * 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.
+ */
+export declare function buildStaticBundle({ entry, outDir, studioVersion, apiBase, accessToken, title, manifestExtras, }: BuildStaticBundleOptions): Promise<BundleManifest>;