@geniee-inc/sfa-kit 1.14.1 → 1.17.0

package/src/lib/provider/SfaClient.js

@@ -59,6 +59,7 @@ export class SfaClient {
         /** 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.listObjectsCache = null;
         this.apiBase = this.resolveBase(config.apiBase.replace(/\/+$/, ''), config.mode);
         this.auth = config.auth;
         this.mode = config.mode;
@@ -174,11 +175,21 @@ export class SfaClient {
     }
     listObjects() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            const raw = yield this.fetchGet(this.objectsPath());
-            const data = raw;
-            const objects = ((_a = data.objects) !== null && _a !== void 0 ? _a : []).map(o => normalizeObjectSummary(o));
-            return { objects };
+            if (this.listObjectsCache)
+                return this.listObjectsCache;
+            const promise = this.fetchGet(this.objectsPath())
+                .then(raw => {
+                var _a;
+                const data = raw;
+                const objects = ((_a = data.objects) !== null && _a !== void 0 ? _a : []).map(o => normalizeObjectSummary(o));
+                return { objects };
+            })
+                .catch((err) => {
+                this.listObjectsCache = null;
+                throw err;
+            });
+            this.listObjectsCache = promise;
+            return promise;
         });
     }
     listFieldTypes() {
@@ -1040,6 +1051,8 @@ function readBulkRowStatus(raw) {
         conflict: 'conflict',
         invalid: 'invalid',
         not_attempted: 'not_attempted',
+        not_found: 'not_found',
+        not_permitted: 'not_permitted',
         indeterminate: 'indeterminate',
     };
     return typeof raw === 'string' ? (_a = known[raw]) !== null && _a !== void 0 ? _a : 'unknown' : 'unknown';

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

@@ -103,13 +103,19 @@ export interface SfaFieldError {
  * All are reported per row with HTTP 200 — a bulk call is best-effort and has
  * no all-or-nothing mode.
  *
+ * `not_found` and `not_permitted` are refusals of a row the call did reach:
+ * the record it named does not exist, or the caller may not write it. No write
+ * happened either way, so both are settled failures and reach the caller in
+ * `failed`. Sending them again is safe, but returns the same answer until the
+ * record or the permission changes — the decision belongs to the server.
+ *
  * `unknown` is not sent by the API: it is what the kit reads an unrecognised
  * status as, and what a claimed success it cannot make sense of becomes — no
  * record, or no `version` for the next write to lock against. The row keeps
  * its `id`, and reaches the caller in `unresolved`, never in `failed`:
  * retrying a create that already landed writes a second record.
  */
-export type SfaBulkRowStatus = 'created' | 'updated' | 'deleted' | 'conflict' | 'invalid' | 'not_attempted' | 'indeterminate' | 'unknown';
+export type SfaBulkRowStatus = 'created' | 'updated' | 'deleted' | 'conflict' | 'invalid' | 'not_attempted' | 'not_found' | 'not_permitted' | 'indeterminate' | 'unknown';
 /** @description One row of a bulk update: what to change and from which version. */
 export interface SfaBulkUpdateRow {
     readonly id: string;
@@ -146,12 +152,22 @@ export interface SfaBulkRowResult {
      * against.
      */
     readonly record: SfaRecord | null;
-    /** Set on `conflict` and `invalid`: the problem detail for this row. */
+    /**
+     * The problem detail for this row. Set on the statuses that report one:
+     * `conflict`, `invalid`, `not_found` and `not_permitted`.
+     */
     readonly error: SfaBulkRowError | null;
 }
 /** @description Why one row failed, in the same shape single writes report. */
 export interface SfaBulkRowError {
-    /** Machine-readable problem code, e.g. `version_mismatch`. */
+    /**
+     * Machine-readable problem code, e.g. `version_mismatch`.
+     *
+     * NOTE: empty when the response carried none. Keystone has not minted a code
+     * for `not_permitted` and widened that field of its contract to any string,
+     * so a caller that branches on `code` has to treat `''` as "not stated" and
+     * fall back to `status`, rather than assume every failure names itself.
+     */
     readonly code: string;
     readonly message: string;
     /** Per-field errors when the row failed validation. */

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

@@ -1,4 +1,4 @@
-import type { FileEntry } from './types';
+import type { FileEntry } from './types.js';
 /**
  * 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}.

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

@@ -4,6 +4,23 @@
  *
  * Signs the message `"{studioVersion}:{contentHash}"` with the given key.
  *
+ * **The signing key lives only in Keystone (`KEYSTONE_STUDIO__SIGNING_KEY`),
+ * so a page build cannot call this.** Deploying the key to Studio as well was
+ * the original design and was dropped in SFAJAI-186: Studio's secret store is
+ * per project, while the key has to be identical across all of them. Keystone
+ * now signs on request, and a page build asks it:
+ *
+ * ```ts
+ * const files = await readBundleFiles('dist');
+ * const contentHash = computeContentHash(files);
+ * // POST /v1/pages/sign { studio_version, content_hash } -> { signature }
+ * ```
+ *
+ * Reach for this only from a service that legitimately holds the key. Signing
+ * with a made-up one is not caught at upload time while the verifier runs in
+ * `disabled` mode — the bundle is accepted, and only starts failing once the
+ * mode is switched to `enforced`.
+ *
  * @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.

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

@@ -5,6 +5,23 @@ import { createHmac } from 'node:crypto';
  *
  * Signs the message `"{studioVersion}:{contentHash}"` with the given key.
  *
+ * **The signing key lives only in Keystone (`KEYSTONE_STUDIO__SIGNING_KEY`),
+ * so a page build cannot call this.** Deploying the key to Studio as well was
+ * the original design and was dropped in SFAJAI-186: Studio's secret store is
+ * per project, while the key has to be identical across all of them. Keystone
+ * now signs on request, and a page build asks it:
+ *
+ * ```ts
+ * const files = await readBundleFiles('dist');
+ * const contentHash = computeContentHash(files);
+ * // POST /v1/pages/sign { studio_version, content_hash } -> { signature }
+ * ```
+ *
+ * Reach for this only from a service that legitimately holds the key. Signing
+ * with a made-up one is not caught at upload time while the verifier runs in
+ * `disabled` mode — the bundle is accepted, and only starts failing once the
+ * mode is switched to `enforced`.
+ *
  * @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.

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

@@ -1,9 +1,19 @@
-import type { BundleManifest } from './types';
+import type { BundleManifest } from './types.js';
 /**
  * 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}.
+ * Walks the directory tree via {@link readBundleFiles} and delegates to
+ * {@link createManifest}.
+ *
+ * **Requires the shared signing key, which page builds do not have.** Keystone
+ * holds it and is the only party that signs: an earlier design deployed it to
+ * Studio as well, and was abandoned because Studio's secret store is per
+ * project while the key must be identical everywhere (SFAJAI-186). Use this
+ * only from a service that legitimately holds the key. A page build calls
+ * {@link readBundleFiles} + {@link computeContentHash} and posts the hash to
+ * `POST /v1/pages/sign` instead — signing with an invented key produces a
+ * bundle that uploads today, while the verifier runs in `disabled` mode, and
+ * starts failing the moment it is switched to `enforced`.
  *
  * 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

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

@@ -1,12 +1,21 @@
 import { __awaiter } from "tslib";
-import { readdir, readFile } from 'node:fs/promises';
-import { join, relative, posix } from 'node:path';
-import { createManifest } from './create-manifest';
+import { createManifest } from './create-manifest.js';
+import { readBundleFiles } from './read-bundle-files.js';
 /**
  * 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}.
+ * Walks the directory tree via {@link readBundleFiles} and delegates to
+ * {@link createManifest}.
+ *
+ * **Requires the shared signing key, which page builds do not have.** Keystone
+ * holds it and is the only party that signs: an earlier design deployed it to
+ * Studio as well, and was abandoned because Studio's secret store is per
+ * project while the key must be identical everywhere (SFAJAI-186). Use this
+ * only from a service that legitimately holds the key. A page build calls
+ * {@link readBundleFiles} + {@link computeContentHash} and posts the hash to
+ * `POST /v1/pages/sign` instead — signing with an invented key produces a
+ * bundle that uploads today, while the verifier runs in `disabled` mode, and
+ * starts failing the moment it is switched to `enforced`.
  *
  * 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
@@ -18,29 +27,7 @@ import { createManifest } from './create-manifest';
  */
 export function createManifestFromDirectory(distDir, studioVersion, signingKey) {
     return __awaiter(this, void 0, void 0, function* () {
-        const files = yield collectFiles(distDir);
+        const files = yield readBundleFiles(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

@@ -1,4 +1,4 @@
-import type { BundleManifest, FileEntry } from './types';
+import type { BundleManifest, FileEntry } from './types.js';
 /**
  * Creates a signed {@link BundleManifest} from a list of bundle files.
  *
@@ -6,6 +6,12 @@ import type { BundleManifest, FileEntry } from './types';
  * Callers can spread decorative fields (e.g. `sfaKitVersion` for the npm
  * package version, `name`, `displayName`) on top before writing to disk.
  *
+ * **Requires the shared signing key, which page builds do not have** — see
+ * {@link computeSignature}. A page build computes `content_hash` with
+ * {@link computeContentHash} and gets the signature from Keystone's
+ * `POST /v1/pages/sign`, then writes the three fields as a
+ * {@link BundleManifest} literal.
+ *
  * @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.

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

@@ -1,5 +1,5 @@
-import { computeContentHash } from './compute-content-hash';
-import { computeSignature } from './compute-signature';
+import { computeContentHash } from './compute-content-hash.js';
+import { computeSignature } from './compute-signature.js';
 /**
  * Creates a signed {@link BundleManifest} from a list of bundle files.
  *
@@ -7,6 +7,12 @@ import { computeSignature } from './compute-signature';
  * Callers can spread decorative fields (e.g. `sfaKitVersion` for the npm
  * package version, `name`, `displayName`) on top before writing to disk.
  *
+ * **Requires the shared signing key, which page builds do not have** — see
+ * {@link computeSignature}. A page build computes `content_hash` with
+ * {@link computeContentHash} and gets the signature from Keystone's
+ * `POST /v1/pages/sign`, then writes the three fields as a
+ * {@link BundleManifest} literal.
+ *
  * @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.

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

@@ -1,5 +1,6 @@
-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';
+export type { BundleManifest, FileEntry } from './types.js';
+export { computeContentHash } from './compute-content-hash.js';
+export { readBundleFiles } from './read-bundle-files.js';
+export { computeSignature } from './compute-signature.js';
+export { createManifest } from './create-manifest.js';
+export { createManifestFromDirectory } from './create-manifest-from-directory.js';

package/src/lib/signing/index.js

@@ -1,4 +1,5 @@
-export { computeContentHash } from './compute-content-hash';
-export { computeSignature } from './compute-signature';
-export { createManifest } from './create-manifest';
-export { createManifestFromDirectory } from './create-manifest-from-directory';
+export { computeContentHash } from './compute-content-hash.js';
+export { readBundleFiles } from './read-bundle-files.js';
+export { computeSignature } from './compute-signature.js';
+export { createManifest } from './create-manifest.js';
+export { createManifestFromDirectory } from './create-manifest-from-directory.js';

package/src/lib/signing/read-bundle-files.d.ts

@@ -0,0 +1,19 @@
+import type { FileEntry } from './types.js';
+/**
+ * @description Reads every file under a built bundle directory as a
+ * {@link FileEntry}, ready for {@link computeContentHash}.
+ *
+ * This is the key-free half of building a bundle manifest: it needs no signing
+ * key, so a page build can compute its own `content_hash` and ask Keystone for
+ * the signature (`POST /v1/pages/sign`) rather than holding the shared secret.
+ *
+ * Paths are relative to `bundleDir` and use forward slashes on every platform,
+ * because the content hash is computed over the path bytes — a Windows
+ * backslash would hash to a different value than the same bundle built on
+ * Linux, and Keystone would reject it.
+ *
+ * **Node.js only.** Uses `node:fs`, so it must not reach a browser bundle.
+ *
+ * @param bundleDir - Absolute or relative path to the built bundle (e.g. `dist`).
+ */
+export declare function readBundleFiles(bundleDir: string): Promise<FileEntry[]>;

package/src/lib/signing/read-bundle-files.js

@@ -0,0 +1,41 @@
+import { __awaiter } from "tslib";
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, posix } from 'node:path';
+/**
+ * @description Reads every file under a built bundle directory as a
+ * {@link FileEntry}, ready for {@link computeContentHash}.
+ *
+ * This is the key-free half of building a bundle manifest: it needs no signing
+ * key, so a page build can compute its own `content_hash` and ask Keystone for
+ * the signature (`POST /v1/pages/sign`) rather than holding the shared secret.
+ *
+ * Paths are relative to `bundleDir` and use forward slashes on every platform,
+ * because the content hash is computed over the path bytes — a Windows
+ * backslash would hash to a different value than the same bundle built on
+ * Linux, and Keystone would reject it.
+ *
+ * **Node.js only.** Uses `node:fs`, so it must not reach a browser bundle.
+ *
+ * @param bundleDir - Absolute or relative path to the built bundle (e.g. `dist`).
+ */
+export function readBundleFiles(bundleDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const entries = yield readdir(bundleDir, {
+            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(bundleDir, absolutePath);
+            const posixPath = relativePath.split(/[\\/]/).join(posix.sep);
+            const content = yield readFile(absolutePath);
+            files.push({ path: posixPath, content });
+        }
+        return files;
+    });
+}

package/src/lib/version.d.ts

@@ -1 +1 @@
-export declare const SFA_KIT_VERSION = "1.14.1";
+export declare const SFA_KIT_VERSION = "1.17.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.14.1';
+export const SFA_KIT_VERSION = '1.17.0';

package/src/signing.d.ts

@@ -5,14 +5,19 @@
  * and should not be imported in browser environments. It uses `node:crypto`
  * for SHA-256 and HMAC-SHA-256 operations.
  *
+ * The signing key lives only in Keystone, so a page build computes the content
+ * hash here and asks Keystone for the signature. Only `readBundleFiles` and
+ * `computeContentHash` are usable without the key.
+ *
  * @example
  * ```ts
- * import { createManifestFromDirectory } from '@geniee-inc/sfa-kit/signing';
+ * import { readBundleFiles, computeContentHash } from '@geniee-inc/sfa-kit/signing';
  *
- * const manifest = await createManifestFromDirectory('./dist', '0.5.0', signingKey);
+ * const contentHash = computeContentHash(await readBundleFiles('./dist'));
+ * // POST /v1/pages/sign { studio_version, content_hash } -> { signature }
  * ```
  *
  * @packageDocumentation
  */
-export type { BundleManifest, FileEntry } from './lib/signing';
-export { computeContentHash, computeSignature, createManifest, createManifestFromDirectory, } from './lib/signing';
+export type { BundleManifest, FileEntry } from './lib/signing/index.js';
+export { computeContentHash, readBundleFiles, computeSignature, createManifest, createManifestFromDirectory, } from './lib/signing/index.js';

package/src/signing.js

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