wyvrnpm 2.12.3 → 2.13.12

package/src/signing/attestation.js

@@ -0,0 +1,301 @@
+'use strict';
+
+const { canonicalize } = require('./canonical');
+
+/**
+ * Builder + validator for the wyvrnpm artefact attestation. Two shapes
+ * coexist on the registry:
+ *
+ *   v1 — fat-zip publish (today's default).
+ *     Binds contentSha256 (the single `wyvrn.zip`) + manifestSha256.
+ *
+ *   v2 — per-config slice publish (recipe `build.publishPerConfig: true`).
+ *     Binds artefactSha256 (a `{ config → sha256 }` map covering every
+ *     `wyvrn-<Config>.zip` slice) + manifestSha256. The signed canonical
+ *     body covers the whole map, so a tampered or omitted slice changes
+ *     the signed bytes and the signature fails — even if the slice the
+ *     consumer is asking for is unchanged.
+ *
+ * Both shapes share name/version/profileHash/manifestSha256/publishedAt/
+ * publisherKeyId/uploadedBy. A v1 attestation is byte-identical to what
+ * pre-2.13.x publishers produced, so existing trust anchors and signed
+ * artefacts on the registry stay verifiable without rotation.
+ */
+
+const ATTESTATION_V1 = 1;
+const ATTESTATION_V2 = 2;
+const SUPPORTED_ATTESTATION_VERSIONS = new Set([ATTESTATION_V1, ATTESTATION_V2]);
+
+// Legacy alias — pre-v2 callers imported `ATTESTATION_VERSION` literally.
+// Keep it pointing at v1 so they keep emitting v1 unless they opt in.
+const ATTESTATION_VERSION = ATTESTATION_V1;
+
+const SHA256_HEX_RE   = /^[0-9a-f]{64}$/;
+const PROFILE_HASH_RE = /^[0-9a-f]{16}$/;
+// keyId lives in keys.json + signature envelope; keep it ASCII + slug-shaped
+// so it round-trips cleanly through filesystems and config files.
+const KEY_ID_RE       = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const ISO8601_RE      = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+// CMake config names are PascalCase, ASCII, no spaces. The slice classifier
+// only emits canonical configs (Debug / Release / RelWithDebInfo /
+// MinSizeRel) but the regex stays generous so a future custom-config
+// extension doesn't require a schema bump.
+const CONFIG_NAME_RE  = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+const REQUIRED_V1 = [
+  'wyvrnAttestationVersion', 'name', 'version', 'profileHash',
+  'contentSha256', 'manifestSha256', 'publishedAt', 'publisherKeyId',
+];
+const REQUIRED_V2 = [
+  'wyvrnAttestationVersion', 'name', 'version', 'profileHash',
+  'artefactSha256', 'manifestSha256', 'publishedAt', 'publisherKeyId',
+];
+
+/**
+ * Build a fully-validated attestation. Dispatch:
+ *   - explicit `wyvrnAttestationVersion`: honoured.
+ *   - else: v2 if `artefactSha256` is supplied; v1 otherwise.
+ *
+ * Both v1 and v2 inputs are mutually exclusive — supplying both
+ * `contentSha256` and `artefactSha256` is incoherent and throws.
+ */
+function buildAttestation(opts) {
+  if (opts == null || typeof opts !== 'object') {
+    throw new Error('attestation: opts must be an object');
+  }
+  const v = opts.wyvrnAttestationVersion;
+  if (v !== undefined && v !== null && !SUPPORTED_ATTESTATION_VERSIONS.has(v)) {
+    throw new Error(
+      `attestation: unsupported wyvrnAttestationVersion ${v}` +
+      ` (this client supports ${[...SUPPORTED_ATTESTATION_VERSIONS].join(', ')})`,
+    );
+  }
+  if (opts.contentSha256 != null && opts.artefactSha256 != null) {
+    throw new Error('attestation: pass either contentSha256 (v1) or artefactSha256 (v2), not both');
+  }
+
+  const route = v ?? (opts.artefactSha256 != null ? ATTESTATION_V2 : ATTESTATION_V1);
+  return route === ATTESTATION_V2 ? buildV2Attestation(opts) : buildV1Attestation(opts);
+}
+
+function buildV1Attestation({
+  name, version, profileHash, contentSha256, manifestSha256,
+  publishedAt, publisherKeyId, uploadedBy = null,
+}) {
+  validateCommon({ name, version, profileHash, manifestSha256, publishedAt, publisherKeyId, uploadedBy });
+  if (typeof contentSha256 !== 'string' || !SHA256_HEX_RE.test(contentSha256)) {
+    throw new Error('attestation: contentSha256 must be 64 lowercase hex chars');
+  }
+  return {
+    wyvrnAttestationVersion: ATTESTATION_V1,
+    name,
+    version,
+    profileHash,
+    contentSha256,
+    manifestSha256,
+    publishedAt,
+    publisherKeyId,
+    uploadedBy,
+  };
+}
+
+function buildV2Attestation({
+  name, version, profileHash, artefactSha256, manifestSha256,
+  publishedAt, publisherKeyId, uploadedBy = null,
+}) {
+  validateCommon({ name, version, profileHash, manifestSha256, publishedAt, publisherKeyId, uploadedBy });
+  if (artefactSha256 === null || typeof artefactSha256 !== 'object' || Array.isArray(artefactSha256)) {
+    throw new Error('attestation: artefactSha256 must be an object keyed by config name');
+  }
+  const entries = Object.entries(artefactSha256);
+  if (entries.length === 0) {
+    throw new Error(
+      'attestation: artefactSha256 must not be empty (use v1 contentSha256 for fat-zip publish)',
+    );
+  }
+  for (const [config, sha] of entries) {
+    if (typeof config !== 'string' || !CONFIG_NAME_RE.test(config)) {
+      throw new Error(
+        `attestation: artefactSha256 key ${JSON.stringify(config)} is not a valid config name`,
+      );
+    }
+    if (typeof sha !== 'string' || !SHA256_HEX_RE.test(sha)) {
+      throw new Error(
+        `attestation: artefactSha256[${JSON.stringify(config)}] must be 64 lowercase hex chars`,
+      );
+    }
+  }
+  // Sort the in-memory shape so deepEqual et al. work intuitively in tests.
+  // canonicalize() sorts at signing time anyway, so this doesn't affect signed bytes.
+  const sortedShape = {};
+  for (const k of Object.keys(artefactSha256).sort()) sortedShape[k] = artefactSha256[k];
+
+  return {
+    wyvrnAttestationVersion: ATTESTATION_V2,
+    name,
+    version,
+    profileHash,
+    artefactSha256: sortedShape,
+    manifestSha256,
+    publishedAt,
+    publisherKeyId,
+    uploadedBy,
+  };
+}
+
+function validateCommon({
+  name, version, profileHash, manifestSha256, publishedAt, publisherKeyId, uploadedBy,
+}) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('attestation: name must be a non-empty string');
+  }
+  if (typeof version !== 'string' || version.length === 0) {
+    throw new Error('attestation: version must be a non-empty string');
+  }
+  if (typeof profileHash !== 'string' || !PROFILE_HASH_RE.test(profileHash)) {
+    throw new Error(`attestation: profileHash must be 16 lowercase hex chars (got "${profileHash}")`);
+  }
+  if (typeof manifestSha256 !== 'string' || !SHA256_HEX_RE.test(manifestSha256)) {
+    throw new Error('attestation: manifestSha256 must be 64 lowercase hex chars');
+  }
+  if (typeof publishedAt !== 'string' || !ISO8601_RE.test(publishedAt)) {
+    throw new Error(`attestation: publishedAt must be ISO 8601 UTC (got "${publishedAt}")`);
+  }
+  if (typeof publisherKeyId !== 'string' || !KEY_ID_RE.test(publisherKeyId)) {
+    throw new Error(`attestation: publisherKeyId must match ${KEY_ID_RE} (got "${publisherKeyId}")`);
+  }
+  if (uploadedBy !== null && (typeof uploadedBy !== 'object' || Array.isArray(uploadedBy))) {
+    throw new Error('attestation: uploadedBy must be null or a plain object');
+  }
+}
+
+/**
+ * Parse and validate an attestation read from disk / network. Dispatches on
+ * `wyvrnAttestationVersion`; rejects unknown versions fail-closed (a future
+ * schema change must come with a verifier upgrade).
+ */
+function parseAttestation(raw) {
+  let obj;
+  try {
+    obj = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  } catch (err) {
+    throw new Error(`attestation: malformed JSON — ${err.message}`);
+  }
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new Error('attestation: must be a JSON object');
+  }
+  const v = obj.wyvrnAttestationVersion;
+  if (!SUPPORTED_ATTESTATION_VERSIONS.has(v)) {
+    throw new Error(
+      `attestation: unsupported wyvrnAttestationVersion ${v}` +
+      ` (this client supports ${[...SUPPORTED_ATTESTATION_VERSIONS].join(', ')})`,
+    );
+  }
+  const required = (v === ATTESTATION_V2) ? REQUIRED_V2 : REQUIRED_V1;
+  for (const field of required) {
+    if (!(field in obj)) {
+      throw new Error(`attestation: missing required field "${field}"`);
+    }
+  }
+  return buildAttestation(obj);
+}
+
+/**
+ * Canonical bytes of an attestation — exactly what gets fed to ed25519.sign
+ * at publish and to ed25519.verify at install. Wrapping the canonicaliser
+ * here documents that "the signed bytes are the canonical attestation, full
+ * stop" without exposing canonical.js as a public API across the signing
+ * subsystem.
+ */
+function canonicalAttestationBytes(att) {
+  return Buffer.from(canonicalize(att), 'utf8');
+}
+
+/**
+ * Confirm the attestation's bound `(name, version, profileHash)` match what
+ * the consumer expected to download. Defends against an attacker swapping a
+ * legitimately-signed attestation for `pkg-A@1.0.0` into the URL path of
+ * `pkg-B@2.0.0`. Throws on mismatch.
+ *
+ * Identical contract for v1 and v2 — both bind these fields the same way.
+ */
+function assertBoundIdentity(att, { name, version, profileHash }) {
+  if (att.name !== name) {
+    throw new Error(`attestation bound to name="${att.name}", expected "${name}"`);
+  }
+  if (att.version !== version) {
+    throw new Error(`attestation bound to version="${att.version}", expected "${version}"`);
+  }
+  if (att.profileHash !== profileHash) {
+    throw new Error(
+      `attestation bound to profileHash="${att.profileHash}", expected "${profileHash}"`,
+    );
+  }
+}
+
+/**
+ * Confirm bound hashes between the attestation and the consumer's local
+ * computation. Dispatches on `att.wyvrnAttestationVersion`:
+ *
+ *   v1: expected = { contentSha256, manifestSha256 }
+ *   v2: expected = { sliceConfig, sliceSha256, manifestSha256 }
+ *     — sliceConfig is the canonical config name of the slice the consumer
+ *       chose (e.g. "Release"); sliceSha256 is its locally-computed hash.
+ *       The function looks up att.artefactSha256[sliceConfig] and asserts.
+ *       A consumer who downloaded multiple slices calls this once per slice.
+ *
+ * manifestSha256 is checked against att.manifestSha256 in both cases so the
+ * single canonical-byte signature still binds the manifest the consumer read.
+ */
+function assertBoundHashes(att, expected) {
+  if (att.manifestSha256 !== expected.manifestSha256) {
+    throw new Error(
+      `attestation manifestSha256="${att.manifestSha256}" does not match local manifest "${expected.manifestSha256}"`,
+    );
+  }
+  if (att.wyvrnAttestationVersion === ATTESTATION_V1) {
+    if (att.contentSha256 !== expected.contentSha256) {
+      throw new Error(
+        `attestation contentSha256="${att.contentSha256}" does not match local zip "${expected.contentSha256}"`,
+      );
+    }
+    return;
+  }
+  if (att.wyvrnAttestationVersion === ATTESTATION_V2) {
+    const { sliceConfig, sliceSha256 } = expected;
+    if (typeof sliceConfig !== 'string' || sliceConfig.length === 0) {
+      throw new Error('assertBoundHashes(v2): expected.sliceConfig required');
+    }
+    if (typeof sliceSha256 !== 'string' || !SHA256_HEX_RE.test(sliceSha256)) {
+      throw new Error('assertBoundHashes(v2): expected.sliceSha256 must be 64 lowercase hex chars');
+    }
+    const recorded = att.artefactSha256[sliceConfig];
+    if (typeof recorded !== 'string') {
+      throw new Error(
+        `attestation has no artefactSha256 entry for config "${sliceConfig}" ` +
+        `(published configs: ${Object.keys(att.artefactSha256).join(', ')})`,
+      );
+    }
+    if (recorded !== sliceSha256) {
+      throw new Error(
+        `attestation artefactSha256[${JSON.stringify(sliceConfig)}]="${recorded}" does not match local slice "${sliceSha256}"`,
+      );
+    }
+    return;
+  }
+  throw new Error(`assertBoundHashes: unsupported attestation version ${att.wyvrnAttestationVersion}`);
+}
+
+module.exports = {
+  ATTESTATION_VERSION,           // legacy alias for ATTESTATION_V1
+  ATTESTATION_V1,
+  ATTESTATION_V2,
+  SUPPORTED_ATTESTATION_VERSIONS,
+  buildAttestation,
+  buildV1Attestation,
+  buildV2Attestation,
+  parseAttestation,
+  canonicalAttestationBytes,
+  assertBoundIdentity,
+  assertBoundHashes,
+};

package/src/signing/canonical.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Deterministic JSON serialisation: keys sorted at every nesting level, no
+ * whitespace, identical output on every platform and Node version.
+ *
+ * Used as the signed payload of the artefact attestation
+ * (claude/PLAN-SIGNING.md §3.1) and as the input to `manifestSha256` so the
+ * published manifest cannot be swapped while the zip stays the same.
+ *
+ * Behavioural notes:
+ *   - Object keys sorted via `Array.prototype.sort()` (UTF-16 code-unit order).
+ *     Our attestation + manifest keys are all ASCII, so this matches the
+ *     RFC 8785 (JCS) ordering that future cross-tool verifiers expect.
+ *   - Primitive serialisation is delegated to `JSON.stringify`, which uses
+ *     ES262 `ToString(Number)` for numbers — the same algorithm JCS mandates.
+ *   - Non-finite numbers (NaN, Infinity, -Infinity) are rejected.
+ *   - `undefined`, functions, and symbols are rejected. JSON has no
+ *     representation for them; silently dropping (the default
+ *     `JSON.stringify` behaviour) would change the signed bytes when a
+ *     caller forgot to populate a field.
+ *   - Arrays preserve their input order — only object keys get sorted.
+ */
+function canonicalize(value) {
+  return _serialize(value, []);
+}
+
+function _serialize(value, pathStack) {
+  if (value === null) return 'null';
+
+  const t = typeof value;
+  if (t === 'boolean') return value ? 'true' : 'false';
+
+  if (t === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new Error(
+        `canonicalize: non-finite number at ${_pathStr(pathStack)} (${value})`,
+      );
+    }
+    return JSON.stringify(value);
+  }
+
+  if (t === 'string') return JSON.stringify(value);
+
+  if (Array.isArray(value)) {
+    const parts = value.map((v, i) => _serialize(v, [...pathStack, i]));
+    return '[' + parts.join(',') + ']';
+  }
+
+  if (t === 'object') {
+    const keys = Object.keys(value).sort();
+    const parts = keys.map((k) =>
+      JSON.stringify(k) + ':' + _serialize(value[k], [...pathStack, k]),
+    );
+    return '{' + parts.join(',') + '}';
+  }
+
+  throw new Error(
+    `canonicalize: unsupported value at ${_pathStr(pathStack)} (typeof=${t})`,
+  );
+}
+
+function _pathStr(stack) {
+  return stack.length === 0 ? '<root>' : stack.map((s) => `[${JSON.stringify(s)}]`).join('');
+}
+
+/**
+ * Convenience: SHA256 of the canonical form, full 64-char lowercase hex.
+ * The shape consumers cite as `manifestSha256` in the attestation block.
+ */
+function sha256OfCanonical(value) {
+  return crypto.createHash('sha256').update(canonicalize(value), 'utf8').digest('hex');
+}
+
+module.exports = {
+  canonicalize,
+  sha256OfCanonical,
+};

package/src/signing/ed25519.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Thin wrappers over Node's built-in `crypto` for Ed25519 signing and key
+ * handling. The whole reason wyvrnpm picked Ed25519 (vs GPG, Sigstore,
+ * Authenticode) is that nothing here shells out — every byte goes through
+ * `node:crypto`, identical on Windows / Linux / macOS.
+ *
+ * Format conventions (mirror what `keys.json` and the publisher's local
+ * `*.pub.pem` / `*.priv.pem` use):
+ *
+ *   - Private keys round-trip as PKCS#8 PEM (Node's native format for
+ *     `createPrivateKey`).
+ *   - Public keys round-trip as SPKI PEM for file storage and as SPKI DER
+ *     base64 for embedding in `keys.json`. Both forms are accepted by the
+ *     verify path; pick whichever is more ergonomic at the call site.
+ *   - Signatures are the raw 64-byte Ed25519 output (RFC 8032). No DER
+ *     wrapping. `wyvrn.sig` carries the base64 form.
+ */
+
+const ALG = 'ed25519';
+const RAW_SIG_LEN = 64;
+
+function generateKeyPair() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync(ALG);
+  return {
+    privateKeyPem: privateKey.export({ format: 'pem',  type: 'pkcs8' }),
+    publicKeyPem:  publicKey.export({ format: 'pem',  type: 'spki' }),
+    publicKeyB64:  publicKey.export({ format: 'der',  type: 'spki' }).toString('base64'),
+  };
+}
+
+/**
+ * Load a private key from a PEM string. Validates that the key is Ed25519;
+ * other algorithms throw fast so a misconfigured publisher can't accidentally
+ * publish with a wrong-shape signature.
+ */
+function loadPrivateKey(pem) {
+  const k = crypto.createPrivateKey({ key: pem, format: 'pem' });
+  if (k.asymmetricKeyType !== ALG) {
+    throw new Error(`expected ed25519 private key, got ${k.asymmetricKeyType}`);
+  }
+  return k;
+}
+
+/**
+ * Load a public key from either an SPKI PEM string (file-based) or a base64
+ * SPKI DER string (registry `keys.json`). Auto-detects by leading marker.
+ */
+function loadPublicKey(input) {
+  if (typeof input !== 'string' || input.length === 0) {
+    throw new Error('loadPublicKey: input must be a non-empty string');
+  }
+  let k;
+  if (input.includes('-----BEGIN')) {
+    k = crypto.createPublicKey({ key: input, format: 'pem' });
+  } else {
+    const der = Buffer.from(input, 'base64');
+    k = crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+  }
+  if (k.asymmetricKeyType !== ALG) {
+    throw new Error(`expected ed25519 public key, got ${k.asymmetricKeyType}`);
+  }
+  return k;
+}
+
+/**
+ * Derive the public key (SPKI PEM + base64 DER) from a private key PEM.
+ * Used by `wyvrnpm key show-pub` and as a sanity check during publisher
+ * bootstrap.
+ */
+function derivePublicKey(privateKeyPem) {
+  const priv = loadPrivateKey(privateKeyPem);
+  const pub  = crypto.createPublicKey(priv);
+  return {
+    publicKeyPem: pub.export({ format: 'pem', type: 'spki' }),
+    publicKeyB64: pub.export({ format: 'der', type: 'spki' }).toString('base64'),
+  };
+}
+
+/**
+ * Sign `bytes` with `privateKey`. `privateKey` may be a PEM string or an
+ * already-loaded KeyObject. Returns a 64-byte raw Ed25519 signature.
+ */
+function sign(privateKey, bytes) {
+  const key = typeof privateKey === 'string' ? loadPrivateKey(privateKey) : privateKey;
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes, 'utf8');
+  // Ed25519 in Node uses null algorithm (key type carries the algorithm).
+  const sig = crypto.sign(null, buf, key);
+  if (sig.length !== RAW_SIG_LEN) {
+    throw new Error(`unexpected ed25519 signature length: ${sig.length}`);
+  }
+  return sig;
+}
+
+/**
+ * Verify `sig` against `bytes` using `publicKey`. `publicKey` may be a PEM
+ * string, a base64 SPKI DER string, or a KeyObject. `sig` may be a Buffer or
+ * a base64 string. Returns boolean — never throws on a bad signature, only
+ * on a malformed key/sig shape.
+ */
+function verify(publicKey, bytes, sig) {
+  const key = typeof publicKey === 'string' ? loadPublicKey(publicKey) : publicKey;
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes, 'utf8');
+  const sigBuf = Buffer.isBuffer(sig) ? sig : Buffer.from(sig, 'base64');
+  if (sigBuf.length !== RAW_SIG_LEN) {
+    throw new Error(`expected ${RAW_SIG_LEN}-byte ed25519 signature, got ${sigBuf.length}`);
+  }
+  return crypto.verify(null, buf, key, sigBuf);
+}
+
+module.exports = {
+  ALG,
+  RAW_SIG_LEN,
+  generateKeyPair,
+  loadPrivateKey,
+  loadPublicKey,
+  derivePublicKey,
+  sign,
+  verify,
+};