space-data-module-sdk 0.8.3 → 0.8.5

package/src/bundle/sigdomain.js

@@ -0,0 +1,179 @@
+/**
+ * DOMAIN SEPARATION for detached Ed25519 signatures over content the signer did
+ * not author. This is the JavaScript mirror of the node's Go package
+ * `sdn-server/internal/sigdomain` (and its maintained kubo twin
+ * `kubo/sdn/sigdomain`). All three must agree byte-for-byte: the module SDK is
+ * the verifier for the browser AND the Node/WasmEdge loader, so a divergence
+ * here is not a JS bug, it is an artifact that loads on the node and is refused
+ * in the browser.
+ *
+ * WHAT IT CLOSES. Under the owner's Adversarial-Security bond posture the
+ * PUBLISHER KEY IS THE NODE KEY: one bonded key signs several unrelated kinds
+ * of statement (dataset publications, module artifacts, and — reserved — update
+ * manifests). The node also exposes a signing ENDPOINT over that key. If every
+ * statement kind were a bare SHA-256 digest, a caller could hand the endpoint
+ * the bytes of one kind of document and staple the returned signature onto
+ * another: a cross-protocol forgery oracle. Prefixing a distinct, REGISTERED
+ * domain label puts each statement kind in a disjoint message space.
+ *
+ * SHAPE, and it is fixed-width on purpose:
+ *
+ *     domain || 0x00 || contentHash        (contentHash = 32 raw bytes)
+ *
+ * An ASCII label, a NUL that cannot occur inside the label, then a fixed-width
+ * tail. There is no length ambiguity anywhere in the preimage, so two different
+ * (domain, hash) pairs can never collide onto the same statement bytes.
+ *
+ * REGISTRATION IS MANDATORY. `statement()` refuses any domain not in the
+ * registry below, exactly as Go's `sigdomain.Statement` does. A signer or
+ * verifier that takes a domain from the wire must therefore still land inside a
+ * domain a human added here, which is what keeps "a new signed statement kind"
+ * a reviewed change rather than a request parameter.
+ *
+ * The registry, the descriptions and the preimage bytes are pinned as shared
+ * cross-language test vectors — `test/support/statement-domain-vectors.json`,
+ * byte-identical to the node's `internal/modulert/testdata/` copy, generated by
+ * the Go side and asserted by both suites.
+ */
+
+/**
+ * Width of the content hash every registered domain commits to: SHA-256, raw
+ * (not hex).
+ */
+export const CONTENT_HASH_SIZE = 32;
+
+/**
+ * A MODULE ARTIFACT: the SHA-256 of a module's PORTABLE payload — the
+ * trailer-stripped bytes the runtime instantiates and the capability policy
+ * identifies by content hash. This is the value carried in the publication
+ * trailer's signature entry as `statementDomain`; a module verifier requires
+ * exactly this domain, so an update-manifest signature can never be replayed
+ * into a module trailer, nor the reverse.
+ */
+export const DOMAIN_MODULE_PUBLICATION_V1 = "SDN-MODULE-PUBLICATION-V1";
+
+/**
+ * RESERVED for the SDN-owned signed updater, signed by the same node key under
+ * the same one-publisher-key policy. Registered here ahead of its producer, for
+ * the same reason the Go registry does: deciding the namespace in advance and
+ * in one place is the entire value of a registry. Nothing signs it yet, and a
+ * module verifier must REFUSE it.
+ */
+export const DOMAIN_UPDATE_MANIFEST_V1 = "SDN-UPDATE-MANIFEST-V1";
+
+/**
+ * The CLOSED set of statement domains this SDK will verify. The map value is a
+ * short human description: this table is the answer to "what can the bonded
+ * node key be made to say?". Mirrors Go's `sigdomain.registry` exactly,
+ * including the description strings, which the shared vectors assert.
+ */
+const REGISTRY = new Map([
+  [
+    DOMAIN_MODULE_PUBLICATION_V1,
+    "module artifact, portable-payload SHA-256",
+  ],
+  [
+    DOMAIN_UPDATE_MANIFEST_V1,
+    "update manifest, canonical manifest SHA-256 (reserved; no producer yet)",
+  ],
+]);
+
+const domainTextEncoder = new TextEncoder();
+
+// Go's `strings.TrimSpace` trims `unicode.IsSpace`, which is the Unicode
+// White_Space property. JavaScript's `String.prototype.trim` trims a DIFFERENT
+// set: it adds U+FEFF (ZWNBSP/BOM) and omits U+0085 (NEL). Those two characters
+// are the entire difference, and each one is a cross-runtime split:
+//
+//   " …DOMAIN" -> Go trims, JS does not -> node ACCEPTS, browser REFUSES
+//   "DOMAIN"  -> JS trims, Go does not -> browser ACCEPTS, node REFUSES
+//
+// Neither is forgeable (the statement and the trusted-signer check still bind)
+// and no producer emits one — which is exactly why it would have sat there
+// unnoticed until some proxy or editor introduced a BOM. So the wire-facing
+// trim is Go's set, spelled out, not JS's default.
+const GO_WHITE_SPACE =
+  "\\u0009-\\u000D\\u0020\\u0085\\u00A0\\u1680\\u2000-\\u200A\\u2028\\u2029\\u202F\\u205F\\u3000";
+const GO_TRIM_PATTERN = new RegExp(
+  `^[${GO_WHITE_SPACE}]+|[${GO_WHITE_SPACE}]+$`,
+  "g",
+);
+
+/**
+ * Trim exactly what Go's `strings.TrimSpace` trims — no more, no less. Use this
+ * on every field of a signature entry that the node also trims, so the two
+ * implementations accept the same set of strings.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function trimGoWhitespace(value) {
+  return String(value ?? "").replace(GO_TRIM_PATTERN, "");
+}
+
+export class SignatureDomainError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "SignatureDomainError";
+    this.code = code;
+  }
+}
+
+/** Whether `domain` is a known statement domain. */
+export function registered(domain) {
+  return REGISTRY.has(domain);
+}
+
+/** The registered domains, sorted — mirrors Go's `sigdomain.Domains()`. */
+export function domains() {
+  return [...REGISTRY.keys()].sort();
+}
+
+/** Human description of a registered domain, or "". */
+export function describe(domain) {
+  return REGISTRY.get(domain) ?? "";
+}
+
+/**
+ * Build the exact byte string an Ed25519 signature over `contentHash` must
+ * cover for `domain`:
+ *
+ *     domain || 0x00 || contentHash
+ *
+ * This is the ONLY way this SDK constructs a signable preimage for a registered
+ * domain, so signer and verifier cannot drift.
+ *
+ * Throws — never a partial or best-effort statement — on an unregistered domain
+ * or a content hash that is not exactly {@link CONTENT_HASH_SIZE} raw bytes.
+ * Refusing a wrong-width hash matters: a caller that passed hex TEXT instead of
+ * raw bytes would otherwise get a perfectly valid signature over the wrong
+ * preimage.
+ *
+ * @param {string} domain
+ * @param {Uint8Array} contentHash - 32 raw bytes
+ * @returns {Uint8Array}
+ */
+export function statement(domain, contentHash) {
+  if (!registered(domain)) {
+    throw new SignatureDomainError(
+      "unregistered_statement_domain",
+      `signature statement domain is not registered: ${JSON.stringify(domain)} (registered: ${domains().join(", ")})`,
+    );
+  }
+  const hash = new Uint8Array(contentHash ?? []);
+  if (hash.length !== CONTENT_HASH_SIZE) {
+    throw new SignatureDomainError(
+      "invalid_content_hash",
+      `signature statement content hash must be ${CONTENT_HASH_SIZE} raw bytes, got ${hash.length}`,
+    );
+  }
+  // UTF-8, which for the registry's ASCII labels is byte-for-byte what Go's
+  // `append(out, domain...)` writes. Encoding rather than assuming ASCII keeps
+  // the two implementations equivalent by construction, not by convention.
+  const label = domainTextEncoder.encode(domain);
+  const out = new Uint8Array(label.length + 1 + CONTENT_HASH_SIZE);
+  out.set(label, 0);
+  out[label.length] = 0;
+  out.set(hash, label.length + 1);
+  return out;
+}