@geniee-inc/sfa-kit 1.7.0 → 1.8.0

package/GUIDE.md

@@ -18,10 +18,10 @@ The package ships built JavaScript and TypeScript declarations only. It contains
 
 ```ts
 import pkg from '@geniee-inc/sfa-kit/package.json';
-// pkg.version -> '1.6.0'
+// pkg.version -> '1.8.0'
 ```
 
-No other subpath resolves: `exports` deliberately exposes only the root entry and `./package.json`, so internal modules cannot be imported directly.
+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.
 
 ## Architecture
 
@@ -600,9 +600,9 @@ function CompanyRow({ record }: { record: SfaRecord }) {
 }
 ```
 
-Returns `{ url: string, target: '_top' | '_blank' } | null`.
+Returns `{ url: string, target: '_blank' } | null`.
 
-- `target` is `'_top'` when running inside an SFA iframe (navigates the parent frame to the record).
+- `target` is always `'_blank'` so the record detail page opens in a new browser tab, preserving the user's current Studio page.
 - Returns `null` in standalone preview mode (no host origin to build a URL from), when no `organizationId` is in context, or when the collection does not have a standard record page (e.g. `schedules`).
 
 ### buildRecordDetailUrl (advanced)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geniee-inc/sfa-kit",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "React hooks and components for building pages that connect to GENIEE SFA/CRM data.",
   "type": "module",
   "main": "./src/index.js",
@@ -12,6 +12,11 @@
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
+    "./signing": {
+      "types": "./src/signing.d.ts",
+      "import": "./src/signing.js",
+      "default": "./src/signing.js"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,

package/src/lib/hooks/useRecordDetailUrl.d.ts

@@ -7,8 +7,8 @@ import type { RecordDetailLink } from '../navigation/record-detail-url';
  * Reads the organization ID from `SfaContext` and the host origin from
  * `document.referrer` (the SFA parent frame). No configuration needed.
  *
- * The returned `target` is always `'_top'` (navigates the SFA parent frame),
- * because the hook only returns a link when running inside an iframe.
+ * The returned `target` is always `'_blank'` so the record opens in a new
+ * browser tab, preserving the user's current Studio page context.
  *
  * @example
  * ```tsx

package/src/lib/hooks/useRecordDetailUrl.js

@@ -9,8 +9,8 @@ import { useSfaContext } from '../provider/useSfaClient';
  * Reads the organization ID from `SfaContext` and the host origin from
  * `document.referrer` (the SFA parent frame). No configuration needed.
  *
- * The returned `target` is always `'_top'` (navigates the SFA parent frame),
- * because the hook only returns a link when running inside an iframe.
+ * The returned `target` is always `'_blank'` so the record opens in a new
+ * browser tab, preserving the user's current Studio page context.
  *
  * @example
  * ```tsx
@@ -37,6 +37,6 @@ export function useRecordDetailUrl(collectionName, recordId) {
         if (url == null) {
             return null;
         }
-        return { url, target: '_top' };
+        return { url, target: '_blank' };
     }, [organizationId, collectionName, recordId]);
 }

package/src/lib/navigation/record-detail-url.d.ts

@@ -24,12 +24,11 @@ export interface RecordDetailLink {
     /** The full URL to the record detail page. */
     readonly url: string;
     /**
-     * Suggested link target. Always `'_top'` because the hook only returns a
-     * link when running inside an iframe, and `_top` navigates the SFA parent
-     * frame to the record detail page. Callers may override with `'_blank'`
-     * in their `<a>` tag if the user prefers a new tab.
+     * Suggested link target. Always `'_blank'` so the record detail page opens
+     * in a new browser tab, preserving the user's current Studio page context.
+     * The SFA iframe sandbox includes `allow-popups` to permit this.
      */
-    readonly target: '_top';
+    readonly target: '_blank';
 }
 /**
  * @description Builds the full URL for a record's detail page in SFA/CRM.

package/src/lib/signing/compute-content-hash.d.ts

@@ -0,0 +1,13 @@
+import type { FileEntry } from './types';
+/**
+ * Computes the SHA-256 content hash matching Keystone's
+ * {@link https://github.com/chikyuinc/chikyu/blob/branch_main/keystone/src/keystone/features/pages/domain/page_bundle_integrity.py compute_content_hash}.
+ *
+ * The file at path "manifest.json" (exact match, root only) is excluded.
+ * Remaining files are sorted lexicographically by path. For each file, the
+ * hash input is: 4-byte big-endian path length, UTF-8 path bytes, 4-byte
+ * big-endian content length, content bytes.
+ *
+ * @returns Hex-encoded SHA-256 digest.
+ */
+export declare function computeContentHash(files: ReadonlyArray<FileEntry>): string;

package/src/lib/signing/compute-content-hash.js

@@ -0,0 +1,47 @@
+import { createHash } from 'node:crypto';
+/**
+ * Computes the SHA-256 content hash matching Keystone's
+ * {@link https://github.com/chikyuinc/chikyu/blob/branch_main/keystone/src/keystone/features/pages/domain/page_bundle_integrity.py compute_content_hash}.
+ *
+ * The file at path "manifest.json" (exact match, root only) is excluded.
+ * Remaining files are sorted lexicographically by path. For each file, the
+ * hash input is: 4-byte big-endian path length, UTF-8 path bytes, 4-byte
+ * big-endian content length, content bytes.
+ *
+ * @returns Hex-encoded SHA-256 digest.
+ */
+export function computeContentHash(files) {
+    const hash = createHash('sha256');
+    const sorted = [...files]
+        .filter(f => f.path !== 'manifest.json')
+        .sort((a, b) => compareByCodePoints(a.path, b.path));
+    for (const entry of sorted) {
+        const pathBytes = Buffer.from(entry.path, 'utf-8');
+        hash.update(uint32BE(pathBytes.length));
+        hash.update(pathBytes);
+        hash.update(uint32BE(entry.content.length));
+        hash.update(entry.content);
+    }
+    return hash.digest('hex');
+}
+/** Encode a number as a 4-byte big-endian buffer. */
+function uint32BE(n) {
+    const buf = Buffer.alloc(4);
+    buf.writeUInt32BE(n);
+    return buf;
+}
+/** Compare two strings by Unicode code point, matching Python's `sorted()`. */
+function compareByCodePoints(a, b) {
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        const ac = a.codePointAt(i);
+        const bc = b.codePointAt(j);
+        if (ac !== bc) {
+            return ac - bc;
+        }
+        i += ac > 0xffff ? 2 : 1;
+        j += bc > 0xffff ? 2 : 1;
+    }
+    return a.length - b.length;
+}

package/src/lib/signing/compute-signature.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Computes the HMAC-SHA-256 bundle signature matching Keystone's
+ * BundleSignatureVerifier.
+ *
+ * Signs the message `"{studioVersion}:{contentHash}"` with the given key.
+ *
+ * @param studioVersion - Studio version stored as page metadata.
+ * @param contentHash - Hex-encoded SHA-256 from {@link computeContentHash}.
+ * @param signingKey - Signing key as a UTF-8 string or raw bytes.
+ * @returns Hex-encoded HMAC-SHA-256 digest.
+ */
+export declare function computeSignature(studioVersion: string, contentHash: string, signingKey: string | Uint8Array): string;

package/src/lib/signing/compute-signature.js

@@ -0,0 +1,19 @@
+import { createHmac } from 'node:crypto';
+/**
+ * Computes the HMAC-SHA-256 bundle signature matching Keystone's
+ * BundleSignatureVerifier.
+ *
+ * Signs the message `"{studioVersion}:{contentHash}"` with the given key.
+ *
+ * @param studioVersion - Studio version stored as page metadata.
+ * @param contentHash - Hex-encoded SHA-256 from {@link computeContentHash}.
+ * @param signingKey - Signing key as a UTF-8 string or raw bytes.
+ * @returns Hex-encoded HMAC-SHA-256 digest.
+ */
+export function computeSignature(studioVersion, contentHash, signingKey) {
+    if (signingKey.length === 0) {
+        throw new Error('signingKey must not be empty');
+    }
+    const message = `${studioVersion}:${contentHash}`;
+    return createHmac('sha256', signingKey).update(message).digest('hex');
+}

package/src/lib/signing/create-manifest-from-directory.d.ts

@@ -0,0 +1,16 @@
+import type { BundleManifest } from './types';
+/**
+ * Reads a dist directory and creates a signed {@link BundleManifest}.
+ *
+ * Walks the directory tree, constructs {@link FileEntry} objects with
+ * forward-slash relative paths, and delegates to {@link createManifest}.
+ *
+ * This function is **Node.js-only** and must not be used in browser
+ * environments. It does NOT write the manifest file to disk; the caller
+ * is responsible for serializing and writing the returned object.
+ *
+ * @param distDir - Absolute or relative path to the dist directory.
+ * @param studioVersion - Studio version stored as page metadata.
+ * @param signingKey - Signing key as a UTF-8 string or raw bytes.
+ */
+export declare function createManifestFromDirectory(distDir: string, studioVersion: string, signingKey: string | Uint8Array): Promise<BundleManifest>;

package/src/lib/signing/create-manifest-from-directory.js

@@ -0,0 +1,46 @@
+import { __awaiter } from "tslib";
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, posix } from 'node:path';
+import { createManifest } from './create-manifest';
+/**
+ * Reads a dist directory and creates a signed {@link BundleManifest}.
+ *
+ * Walks the directory tree, constructs {@link FileEntry} objects with
+ * forward-slash relative paths, and delegates to {@link createManifest}.
+ *
+ * This function is **Node.js-only** and must not be used in browser
+ * environments. It does NOT write the manifest file to disk; the caller
+ * is responsible for serializing and writing the returned object.
+ *
+ * @param distDir - Absolute or relative path to the dist directory.
+ * @param studioVersion - Studio version stored as page metadata.
+ * @param signingKey - Signing key as a UTF-8 string or raw bytes.
+ */
+export function createManifestFromDirectory(distDir, studioVersion, signingKey) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const files = yield collectFiles(distDir);
+        return createManifest(studioVersion, files, signingKey);
+    });
+}
+/**
+ * Recursively collects all files under a directory as {@link FileEntry} objects.
+ * Paths are normalized to POSIX forward slashes.
+ */
+function collectFiles(dir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const entries = yield readdir(dir, { withFileTypes: true, recursive: true });
+        const files = [];
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const parentPath = (_a = entry.parentPath) !== null && _a !== void 0 ? _a : entry.path;
+            const absolutePath = join(parentPath, entry.name);
+            const relativePath = relative(dir, absolutePath);
+            const posixPath = relativePath.split(/[\\/]/).join(posix.sep);
+            const content = yield readFile(absolutePath);
+            files.push({ path: posixPath, content });
+        }
+        return files;
+    });
+}

package/src/lib/signing/create-manifest.d.ts

@@ -0,0 +1,13 @@
+import type { BundleManifest, FileEntry } from './types';
+/**
+ * Creates a signed {@link BundleManifest} from a list of bundle files.
+ *
+ * Returns the three fields Keystone's BundleSignatureVerifier requires.
+ * Callers can spread decorative fields (e.g. `sfaKitVersion` for the npm
+ * package version, `name`, `displayName`) on top before writing to disk.
+ *
+ * @param studioVersion - Studio version stored as page metadata.
+ * @param files - All files in the bundle (manifest.json is automatically excluded).
+ * @param signingKey - Signing key as a UTF-8 string or raw bytes.
+ */
+export declare function createManifest(studioVersion: string, files: ReadonlyArray<FileEntry>, signingKey: string | Uint8Array): BundleManifest;

package/src/lib/signing/create-manifest.js

@@ -0,0 +1,22 @@
+import { computeContentHash } from './compute-content-hash';
+import { computeSignature } from './compute-signature';
+/**
+ * Creates a signed {@link BundleManifest} from a list of bundle files.
+ *
+ * Returns the three fields Keystone's BundleSignatureVerifier requires.
+ * Callers can spread decorative fields (e.g. `sfaKitVersion` for the npm
+ * package version, `name`, `displayName`) on top before writing to disk.
+ *
+ * @param studioVersion - Studio version stored as page metadata.
+ * @param files - All files in the bundle (manifest.json is automatically excluded).
+ * @param signingKey - Signing key as a UTF-8 string or raw bytes.
+ */
+export function createManifest(studioVersion, files, signingKey) {
+    const contentHash = computeContentHash(files);
+    const signature = computeSignature(studioVersion, contentHash, signingKey);
+    return {
+        studio_version: studioVersion,
+        content_hash: contentHash,
+        signature,
+    };
+}

package/src/lib/signing/index.d.ts

@@ -0,0 +1,5 @@
+export type { BundleManifest, FileEntry } from './types';
+export { computeContentHash } from './compute-content-hash';
+export { computeSignature } from './compute-signature';
+export { createManifest } from './create-manifest';
+export { createManifestFromDirectory } from './create-manifest-from-directory';

package/src/lib/signing/index.js

@@ -0,0 +1,4 @@
+export { computeContentHash } from './compute-content-hash';
+export { computeSignature } from './compute-signature';
+export { createManifest } from './create-manifest';
+export { createManifestFromDirectory } from './create-manifest-from-directory';

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

@@ -0,0 +1,21 @@
+/**
+ * The three fields Keystone's BundleSignatureVerifier reads from
+ * manifest.json. Callers can spread decorative fields on top before
+ * writing to disk (e.g. `sfaKitVersion` for the npm package version,
+ * `name`, `displayName`, `entry`).
+ */
+export interface BundleManifest {
+    /** Studio version string (the build version, not the sfa-kit npm version). */
+    studio_version: string;
+    /** SHA-256 hex digest of all non-manifest file contents. */
+    content_hash: string;
+    /** HMAC-SHA-256 hex of `"{studio_version}:{content_hash}"`. */
+    signature: string;
+}
+/** A single file in the bundle, used for content hash computation. */
+export interface FileEntry {
+    /** Relative path using forward slashes (e.g. "index.html", "assets/bundle.js"). */
+    path: string;
+    /** Raw file content as bytes. */
+    content: Uint8Array;
+}

package/src/lib/signing/types.js

@@ -0,0 +1 @@
+export {};

package/src/lib/version.d.ts

@@ -1 +1 @@
-export declare const SFA_KIT_VERSION = "1.7.0";
+export declare const SFA_KIT_VERSION = "1.8.0";

package/src/lib/version.js

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

package/src/signing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bundle signing utilities for Keystone's BundleSignatureVerifier.
+ *
+ * This subpath export (`@geniee-inc/sfa-kit/signing`) is Node.js-only
+ * and should not be imported in browser environments. It uses `node:crypto`
+ * for SHA-256 and HMAC-SHA-256 operations.
+ *
+ * @example
+ * ```ts
+ * import { createManifestFromDirectory } from '@geniee-inc/sfa-kit/signing';
+ *
+ * const manifest = await createManifestFromDirectory('./dist', '0.5.0', signingKey);
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { BundleManifest, FileEntry } from './lib/signing';
+export { computeContentHash, computeSignature, createManifest, createManifestFromDirectory, } from './lib/signing';

package/src/signing.js

@@ -0,0 +1 @@
+export { computeContentHash, computeSignature, createManifest, createManifestFromDirectory, } from './lib/signing';