@geniee-inc/sfa-kit 1.7.1 → 1.9.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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geniee-inc/sfa-kit",
-  "version": "1.7.1",
+  "version": "1.9.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/provider/SfaClient.d.ts

@@ -12,11 +12,18 @@ export declare class SfaClient implements SfaClientInterface {
     private readonly organizationId;
     private readonly onAuthError;
     readonly mode: SfaApiMode;
+    /** In-memory cache for describe results, keyed by objectKey. Stores Promises
+     *  so concurrent callers share a single in-flight request. */
+    private readonly describeCache;
     constructor(config: SfaClientConfig);
     private resolveBase;
     get(collection: string, recordId: string): Promise<SfaRecord>;
     list(collection: string, params?: SfaListParams): Promise<SfaListResponse>;
     describe(objectKey: string): Promise<SfaDescribeResult>;
+    /** Cached describe fetch. Returns a shared Promise so concurrent callers
+     *  for the same objectKey deduplicate into one HTTP request. On failure the
+     *  entry is evicted so the next caller retries. */
+    private describeObject;
     listObjects(): Promise<SfaObjectCatalog>;
     listFieldTypes(): Promise<SfaFieldTypeCatalog>;
     private assertDirectMode;
@@ -33,6 +40,12 @@ export declare class SfaClient implements SfaClientInterface {
      * another write landed first.
      */
     update(collection: string, recordId: string, fields: Record<string, unknown>, version: string): Promise<SfaRecord>;
+    /**
+     * @description Fetches describe metadata (with cache) and normalizes
+     * cardinality:"many" reference fields to arrays. Falls back to no-op if
+     * describe fails, so a broken metadata endpoint never blocks writes.
+     */
+    private applySchemaAwareNormalization;
     /**
      * @description Deletes a record with optimistic locking. Returns void on
      * success (204). Throws SfaConflictError on 412 if the record was modified

package/src/lib/provider/SfaClient.js

@@ -21,6 +21,9 @@ function timeoutSignal() {
  */
 export class SfaClient {
     constructor(config) {
+        /** In-memory cache for describe results, keyed by objectKey. Stores Promises
+         *  so concurrent callers share a single in-flight request. */
+        this.describeCache = new Map();
         this.apiBase = this.resolveBase(config.apiBase.replace(/\/+$/, ''), config.mode);
         this.auth = config.auth;
         this.mode = config.mode;
@@ -101,10 +104,26 @@ export class SfaClient {
     }
     describe(objectKey) {
         return __awaiter(this, void 0, void 0, function* () {
-            const raw = yield this.fetchGet(this.objectsPath(`/${enc(objectKey)}`));
-            return { object: normalizeObjectDetail(raw) };
+            const object = yield this.describeObject(objectKey);
+            return { object };
         });
     }
+    /** Cached describe fetch. Returns a shared Promise so concurrent callers
+     *  for the same objectKey deduplicate into one HTTP request. On failure the
+     *  entry is evicted so the next caller retries. */
+    describeObject(objectKey) {
+        const cached = this.describeCache.get(objectKey);
+        if (cached)
+            return cached;
+        const promise = this.fetchGet(this.objectsPath(`/${enc(objectKey)}`))
+            .then(raw => normalizeObjectDetail(raw))
+            .catch((err) => {
+            this.describeCache.delete(objectKey);
+            throw err;
+        });
+        this.describeCache.set(objectKey, promise);
+        return promise;
+    }
     listObjects() {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -142,12 +161,13 @@ export class SfaClient {
     create(collection, fields, options) {
         return __awaiter(this, void 0, void 0, function* () {
             this.assertDirectMode();
+            const normalized = yield this.applySchemaAwareNormalization(collection, fields);
             const path = `/v1/objects/${enc(collection)}/records`;
             const extra = {};
             if (options === null || options === void 0 ? void 0 : options.idempotencyKey) {
                 extra['Idempotency-Key'] = options.idempotencyKey;
             }
-            const response = yield this.fetchWithBody('POST', path, { fields: normalizeWriteFields(fields) }, extra);
+            const response = yield this.fetchWithBody('POST', path, { fields: normalizeWriteFields(normalized) }, extra);
             const raw = yield response.json();
             return normalizeKeystoneRecord(raw);
         });
@@ -161,12 +181,32 @@ export class SfaClient {
         return __awaiter(this, void 0, void 0, function* () {
             this.assertDirectMode();
             this.assertRecordId(recordId);
+            const normalized = yield this.applySchemaAwareNormalization(collection, fields);
             const path = `/v1/objects/${enc(collection)}/records/${enc(recordId)}`;
-            const response = yield this.fetchWithBody('PATCH', path, { fields: normalizeWriteFields(fields) }, { 'If-Match': version });
+            const response = yield this.fetchWithBody('PATCH', path, { fields: normalizeWriteFields(normalized) }, { 'If-Match': version });
             const raw = yield response.json();
             return normalizeKeystoneRecord(raw);
         });
     }
+    /**
+     * @description Fetches describe metadata (with cache) and normalizes
+     * cardinality:"many" reference fields to arrays. Falls back to no-op if
+     * describe fails, so a broken metadata endpoint never blocks writes.
+     */
+    applySchemaAwareNormalization(collection, fields) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const detail = yield this.describeObject(collection);
+                return normalizeCardinalityFields(fields, detail.fields);
+            }
+            catch (_a) {
+                // Describe failed -- proceed without cardinality normalization.
+                // The write will either succeed (no many-cardinality fields in payload)
+                // or fail with the same 422 it would have before this feature.
+                return fields;
+            }
+        });
+    }
     /**
      * @description Deletes a record with optimistic locking. Returns void on
      * success (204). Throws SfaConflictError on 412 if the record was modified
@@ -293,6 +333,49 @@ function enc(segment) {
     return encodeURIComponent(segment);
 }
 // ── Keystone record normalization (direct mode) ──
+// ── Write-path normalization ──
+/** Field kinds whose values must be arrays when cardinality is 'many'. */
+const ARRAY_WRAPPABLE_KINDS = new Set([
+    'reference',
+    'user_reference',
+]);
+/**
+ * @description Wraps scalar values in arrays for fields whose schema declares
+ * cardinality:"many". Already-array values, null, and undefined are passed
+ * through unchanged. Runs *before* normalizeWriteFields so SfaFieldValue
+ * wrappers are still intact; when a wrapper is detected its inner `.value`
+ * is wrapped while the wrapper structure is preserved.
+ */
+function normalizeCardinalityFields(fields, descriptors) {
+    const manyFields = new Set();
+    for (const desc of descriptors) {
+        if (desc.cardinality === 'many' && ARRAY_WRAPPABLE_KINDS.has(desc.kind)) {
+            manyFields.add(desc.key);
+        }
+    }
+    if (manyFields.size === 0)
+        return fields;
+    const result = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (manyFields.has(key) && value != null && !Array.isArray(value)) {
+            if (isSfaFieldValue(value)) {
+                // Wrap the inner value; preserve the SfaFieldValue wrapper so the
+                // subsequent normalizeWriteFields step can still unwrap it.
+                const inner = value.value;
+                result[key] =
+                    inner != null && !Array.isArray(inner)
+                        ? Object.assign(Object.assign({}, value), { value: [inner] }) : value;
+            }
+            else {
+                result[key] = [value];
+            }
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
 /**
  * @description Converts a caller-supplied fields map into the raw values
  * expected by Keystone's RecordWrite body. If a value is already a raw value

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.1";
+export declare const SFA_KIT_VERSION = "1.9.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.7.1';
+export const SFA_KIT_VERSION = '1.9.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';