@geniee-inc/sfa-kit 1.17.0 → 1.19.0

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

@@ -2,7 +2,9 @@
  * Computes the HMAC-SHA-256 bundle signature matching Keystone's
  * BundleSignatureVerifier.
  *
- * Signs the message `"{studioVersion}:{contentHash}"` with the given key.
+ * Signs the message `"{studioVersion}:{contentHash}"` with the given key. This
+ * is the legacy format; a manifest without `studio_version` is checked
+ * against `contentHash` alone (see `ContentHashManifest`).
  *
  * **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
@@ -13,7 +15,7 @@
  * ```ts
  * const files = await readBundleFiles('dist');
  * const contentHash = computeContentHash(files);
- * // POST /v1/pages/sign { studio_version, content_hash } -> { signature }
+ * // POST /v1/pages/sign { content_hash } -> { signature }
  * ```
  *
  * Reach for this only from a service that legitimately holds the key. Signing

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

@@ -3,7 +3,9 @@ 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.
+ * Signs the message `"{studioVersion}:{contentHash}"` with the given key. This
+ * is the legacy format; a manifest without `studio_version` is checked
+ * against `contentHash` alone (see `ContentHashManifest`).
  *
  * **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
@@ -14,7 +16,7 @@ import { createHmac } from 'node:crypto';
  * ```ts
  * const files = await readBundleFiles('dist');
  * const contentHash = computeContentHash(files);
- * // POST /v1/pages/sign { studio_version, content_hash } -> { signature }
+ * // POST /v1/pages/sign { content_hash } -> { signature }
  * ```
  *
  * Reach for this only from a service that legitimately holds the key. Signing

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

@@ -2,15 +2,17 @@ import type { BundleManifest, FileEntry } from './types.js';
 /**
  * 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.
+ * Returns the three fields of the legacy format, signed over
+ * `"{studio_version}:{content_hash}"`. Callers can spread decorative fields
+ * (e.g. `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.
+ * {@link computeContentHash}, posts it alone to Keystone's
+ * `POST /v1/pages/sign`, and writes the current format, a
+ * `ContentHashManifest` (see GUIDE.md). It does not write `studio_version`:
+ * Keystone checks a manifest carrying one in this legacy format, so a signature
+ * over `content_hash` alone would not verify.
  *
  * @param studioVersion - Studio version stored as page metadata.
  * @param files - All files in the bundle (manifest.json is automatically excluded).

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

@@ -3,15 +3,17 @@ import { computeSignature } from './compute-signature.js';
 /**
  * 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.
+ * Returns the three fields of the legacy format, signed over
+ * `"{studio_version}:{content_hash}"`. Callers can spread decorative fields
+ * (e.g. `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.
+ * {@link computeContentHash}, posts it alone to Keystone's
+ * `POST /v1/pages/sign`, and writes the current format, a
+ * `ContentHashManifest` (see GUIDE.md). It does not write `studio_version`:
+ * Keystone checks a manifest carrying one in this legacy format, so a signature
+ * over `content_hash` alone would not verify.
  *
  * @param studioVersion - Studio version stored as page metadata.
  * @param files - All files in the bundle (manifest.json is automatically excluded).

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

@@ -1,4 +1,4 @@
-export type { BundleManifest, FileEntry } from './types.js';
+export type { BundleManifest, FileEntry, ContentHashManifest, } from './types.js';
 export { computeContentHash } from './compute-content-hash.js';
 export { readBundleFiles } from './read-bundle-files.js';
 export { computeSignature } from './compute-signature.js';

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

@@ -1,8 +1,9 @@
 /**
- * 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`).
+ * The legacy manifest format: the signature covers
+ * `"{studio_version}:{content_hash}"`. Keystone still accepts it, and
+ * {@link createManifest} and `buildStaticBundle` given a `studioVersion` still
+ * produce it. Callers can spread decorative fields on top before writing to
+ * disk (e.g. `name`, `displayName`, `entry`).
  */
 export interface BundleManifest {
     /** Studio version string (the build version, not the sfa-kit npm version). */
@@ -12,6 +13,34 @@ export interface BundleManifest {
     /** HMAC-SHA-256 hex of `"{studio_version}:{content_hash}"`. */
     signature: string;
 }
+/**
+ * The manifest `buildStaticBundle` writes when no `studioVersion` is given.
+ *
+ * Keystone reads a manifest without `studio_version` as this format and checks
+ * the signature against `content_hash` alone. `content_hash` covers every
+ * other file in the bundle, so that is what makes an edited bundle fail.
+ */
+export interface ContentHashManifest {
+    /**
+     * The sfa-kit version that ran the build. Not signed: Keystone stores it for
+     * troubleshooting only.
+     *
+     * NOTE: this is the copy of sfa-kit that ran the bundler. esbuild bundles
+     * whichever copy the entry module imports, which is normally the same one,
+     * but a project with two installed copies can bundle the other.
+     */
+    sfa_kit_version: string;
+    /** SHA-256 hex digest of all non-manifest file contents. */
+    content_hash: string;
+    /** HMAC-SHA-256 hex of `content_hash`. */
+    signature: string;
+    /**
+     * Never present in this format. Keystone picks the format by whether the
+     * manifest carries `studio_version`, so one that does is a legacy
+     * {@link BundleManifest}, not this.
+     */
+    studio_version?: never;
+}
 /** 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"). */

package/src/lib/version.d.ts

@@ -1 +1 @@
-export declare const SFA_KIT_VERSION = "1.17.0";
+export declare const SFA_KIT_VERSION = "1.19.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.17.0';
+export const SFA_KIT_VERSION = '1.19.0';

package/src/signing.d.ts

@@ -14,10 +14,10 @@
  * import { readBundleFiles, computeContentHash } from '@geniee-inc/sfa-kit/signing';
  *
  * const contentHash = computeContentHash(await readBundleFiles('./dist'));
- * // POST /v1/pages/sign { studio_version, content_hash } -> { signature }
+ * // POST /v1/pages/sign { content_hash } -> { signature }
  * ```
  *
  * @packageDocumentation
  */
-export type { BundleManifest, FileEntry } from './lib/signing/index.js';
+export type { BundleManifest, FileEntry, ContentHashManifest, } from './lib/signing/index.js';
 export { computeContentHash, readBundleFiles, computeSignature, createManifest, createManifestFromDirectory, } from './lib/signing/index.js';