@dk/hipp 0.1.15 → 0.1.17

package/README.md

@@ -2,40 +2,30 @@
 
 By Dmytri Kleiner <dev@dmytri.to>
 
-**HIPP** is a minimalist, stateless publishing tool designed to eliminate the
-friction of version-bump commits. It treats your **Git Tags** as the single
-source of truth, enforcing a "Ground State" where your `package.json` version
-remains permanently at `0.0.0`.
-
-HIPP provides **cryptographic signing** and **out-of-band verification** to
-guarantee that the package in the npm registry exactly matches your git tag.
+**HIPP** is a minimalist, stateless publishing tool that eliminates version-bump
+commits and merge conflicts by treating Git Tags as the single source of truth.
+Your `package.json` version stays permanently at `0.0.0`.
 
 ---
 
-## Why HIPP?
-
-### Integrity
+## The Problem
 
-Traditional NPM versioning requires you to store your "Version of Truth" inside
-your source code files (`package.json`). This creates a **State Conflict** that
-leads to several systemic problems:
+Traditional NPM versioning requires storing the "Version of Truth" in `package.json`.
+This creates a **State Conflict**:
 
-`npm version` and `git tag` are two distinct, non-atomic actions. If you tag a
-commit but forget to update the JSON (or vice-versa), your registry package and
-your Git history diverge. This scenario makes it impossible to guarantee that
-the code in the registry matches the code at that tag.
+- `npm version` and `git tag` are two distinct, non-atomic actions
+- If you tag a commit but forget to update the JSON (or vice-versa), your
+  registry package and Git history diverge
+- Every release requires a "chore: bump version" commit
+- When multiple branches are developed simultaneously, these trivial changes
+  cause constant merge conflicts
 
-**HIPP ensures they are fundamentally linked by extracting the version directly
-from the Git Tag, and cryptographically signing the package contents.**
+## The Solution
 
-### No "Chore" Noise
+**HIPP makes `package.json` version immutable (0.0.0)** - the **HIPP Doctrine**.
 
-Every release usually requires a "chore: bump version" commit. When multiple
-branches are developed simultaneously, these version changes cause constant,
-trivial merge conflicts.
-
-**HIPP makes your `package.json` version immutable (0.0.0), so it never
-conflicts and your git history stays clean.**
+Version is extracted directly from the Git Tag during publish. Your Git history
+stays clean, and your registry package is guaranteed to match your Git tag.
 
 ---
 
@@ -43,7 +33,7 @@ conflicts and your git history stays clean.**
 
 ### Setup
 
-1. Set your project's `package.json` version to `0.0.0`. This is the **HIPP Doctrine**.
+1. Set your project's `package.json` version to `0.0.0`:
 
 ```json
 { "name": "your-package", "version": "0.0.0" }
@@ -72,11 +62,20 @@ HIPP will:
 
 On first run, HIPP generates an Ed25519 keypair:
 
-- **`hipp.priv`** - Your private signing key. **Never committed to git.** Added to `.gitignore` automatically.
+- **`hipp.priv`** - Your private signing key. **Never committed to git.**
+  Added to `.gitignore` automatically.
 - **`hipp.pub`** - Your public verification key. **Committed to git** automatically.
 
 The private key holder can sign packages. The public key verifies signatures.
 
+**Key rotation**: Delete `hipp.pub` and run HIPP again. A new keypair will be
+generated and committed automatically. Verification uses the public key from
+the specific git revision at the tag, so previous packages remain verifiable
+with their original keys.
+
+**Multiple publishers**: Each developer can use their own private key. Delete
+`hipp.pub`, run HIPP, and a new keypair will be generated for that revision.
+
 ### Options
 
 * `-y, --yes`: Skip the confirmation prompt (ideal for CI/CD pipelines).
@@ -91,26 +90,97 @@ npx @dk/hipp -- --access public --tag beta
 
 ## Verification
 
-HIPP provides out-of-band verification to guarantee package integrity:
+HIPP provides out-of-band verification to prove package integrity:
 
 ```bash
 npx @dk/hipp verify @dk/your-package[@version]
+npx @dk/hipp verify           # verifies the installed hipp version
 ```
 
 ### How Verification Works
 
-1. **Fetch from npm**: Downloads the package tarball and extracts the manifest
-2. **Fetch from git**: Clones the repository at the tagged commit and extracts the public key
-3. **Hash Verification**: Computes the hash of the git content and compares with the manifest
-4. **Signature Verification**: Verifies the manifest signature using the public key
+**Step 1: Get manifest from npm**
+
+1. Fetch the package tarball from npm registry
+2. Extract the README and parse the JSON manifest appended to it
+
+The manifest contains:
+```json
+{
+  "origin": "git@github.com:dk/your-package.git",
+  "tag": "v1.0.0",
+  "hash": "<sha256-of-tarball>",
+  "signature": "<base64-ed25519-signature>",
+  "name": "Jane Developer",
+  "email": "jane@example.com"
+}
+```
+
+**Step 2: Clone git and verify**
+
+3. Clone the repository at the tagged commit (using origin/tag from manifest)
+4. Stage all tracked files
+5. Run `npm pack` to create a tarball
+6. Compute SHA256 hash of the clean tarball
+7. Compare with the `hash` field from the npm manifest
+
+**Step 3: Verify signature**
+
+8. Read `hipp.pub` from the cloned repository
+9. Verify the signature was created by signing:
+   `hash + "\n" + origin + "\n" + tag + "\n" + name + "\n" + email`
+
+**Step 4: Rebuild verification**
+
+10. Append the manifest to the staged README
+11. Update the staged `package.json` version to match the tag
+12. Run `npm pack` again and verify the hash matches the npm tarball
+
+### Three Verification Checks
+
+| Check | What it proves |
+|-------|----------------|
+| **1. Signature** | The manifest was signed by the holder of the private key matching `hipp.pub` |
+| **2. Manifest hash** | The claimed hash is accurate for this exact git revision |
+| **3. Rebuild** | The npm tarball exactly matches what you'd produce from clean git source |
+
+### What Verification Guarantees
+
+- **Integrity**: The code in npm exactly matches git at the tagged commit
+- **Authenticity**: The package was published by the holder of the private key
+- **Reproducibility**: The npm tarball is byte-for-byte identical to a git rebuild
+
+### What Verification Does NOT Guarantee
+
+- **Code is safe or bug-free**: Malicious or buggy code can be signed
+- **Publisher is trustworthy**: The key holder could sign bad code intentionally
+
+Verification proves that npm matches git - it says nothing about whether that
+code is correct or safe.
+
+---
+
+## Dual-Channel Trust
+
+npm and git serve as independent verification channels:
+
+- **npm** records *when* and *what* was published by *whom*
+- **git** records the source code and the public key
+
+An attacker would need to compromise both registries to forge a valid package.
+This doesn't prove code is safe, but it proves the code in npm matches git.
+
+---
+
+## Security
 
-If both checks pass, you can be certain that:
-- The package contents in npm exactly match the git tag
-- The manifest was signed by the holder of the private key
+HIPP uses **Ed25519** public-key signatures. The private key never leaves your
+machine. The public key is distributed via git. Anyone can verify a signed
+package, but only private key holders can publish.
 
 ### Integrity Rules
 
-HIPP enforces strict integrity rules:
+HIPP enforces strict integrity rules when publishing:
 
 - `package.json` version must be `0.0.0`
 - `package-lock.json` must exist and be tracked by git
@@ -126,14 +196,6 @@ HIPP enforces strict integrity rules:
 
 ---
 
-## Security
-
-HIPP uses **Ed25519** public-key signatures. The private key never leaves your
-machine. The public key is distributed via git. Anyone can verify a signed
-package, but only private key holders can publish.
-
----
-
 ## License
 
 **0BSD** (BSD Zero Clause License)  By Dmytri Kleiner <dev@dmytri.to>
@@ -149,34 +211,13 @@ LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 PERFORMANCE OF THIS SOFTWARE.
 
-
-```json
-{
-  "origin": "git@github.com:dmytri/hipp.git",
-  "tag": "v0.1.10"
-}
-```
-
-```npx @dk/hipp @dk/hipp@0.1.10
-```
-
-<!-- HIPP-META -->
-```json
-{
-  "origin": "git@github.com:dmytri/hipp.git",
-  "tag": "v0.1.11"
-}
-```
-
-```npx @dk/hipp @dk/hipp@0.1.11
-```
-<!-- /HIPP-META -->
-
 ```json
 {
   "origin": "git@github.com:dmytri/hipp.git",
-  "tag": "v0.1.15",
-  "hash": "cee8b863e598809fe8a194c1f102c857a0698e8158bef9e39493b31da6411226",
-  "signature": "Hc5fpg5Kg67ztJBdbtM3DvdrccL1e0KEyYwenwVIHLqcCNadXT9oatpgkO9dFaaGkCMUfttMGtWv8iJtYy+tBg=="
+  "tag": "v0.1.17",
+  "hash": "7a9817b5d57a5c5c43cac3d608d4a0e907dcbdf8031252a62b29195391b38b26",
+  "signature": "/o75TYcgRUS0pVQEmJeCamZ5z6wTDQtawuaKYd4lbZCBWuqEeuaPECRefTgzC7tDr6bCyFd6p4biPGWIroBlCA==",
+  "name": "Dmytri Kleiner",
+  "email": "dev@dmytri.to"
 }
 ```

package/hipp.js

@@ -27,6 +27,12 @@ function git(args, options = {}) {
   }).trim();
 }
 
+function getGitUserInfo() {
+  const name = git(['config', 'user.name']);
+  const email = git(['config', 'user.email']);
+  return { name, email };
+}
+
 function runCmd(cmd, args, options = {}) {
   const result = spawnSync(cmd, args, {
     encoding: 'utf8',
@@ -64,10 +70,18 @@ function loadOrGenerateKeys() {
   const pubPath = getPublicKeyPath();
 
   if (fs.existsSync(privPath) && fs.existsSync(pubPath)) {
-    return {
-      privateKey: fs.readFileSync(privPath, 'utf8'),
-      publicKey: fs.readFileSync(pubPath, 'utf8'),
-    };
+    const privateKey = fs.readFileSync(privPath, 'utf8');
+    const publicKey = fs.readFileSync(pubPath, 'utf8');
+
+    const testData = 'hipp-key-validation';
+    const testSignature = signContent(testData, privateKey);
+    const valid = verifySignature(testData, testSignature, publicKey);
+
+    if (valid) {
+      return { privateKey, publicKey };
+    }
+
+    log.warn('⚠️  Key mismatch detected. Generating new keypair...');
   }
 
   log.info('🔑 Generating Ed25519 keypair...');
@@ -107,20 +121,8 @@ function verifySignature(data, signature, publicKey) {
   }, Buffer.from(signature, 'base64'));
 }
 
-function createManifest(hash, signature) {
-  return JSON.stringify({ hash, signature }, null, 2);
-}
-
-function parseManifest(manifestStr) {
-  try {
-    return JSON.parse(manifestStr);
-  } catch {
-    return null;
-  }
-}
-
-function buildSignData(hash, origin, tag) {
-  return `${hash}\n${origin}\n${tag}\n`;
+function buildSignData(hash, origin, tag, name, email) {
+  return `${hash}\n${origin}\n${tag}\n${name}\n${email}\n`;
 }
 
 function findLastJsonBlock(readmeContent) {
@@ -408,33 +410,18 @@ function copyTrackedFilesFromDir(stageDir, repoDir, files) {
 }
 
 async function runVerify(packageSpec) {
-  let pkgName, pkgVersion;
-  if (packageSpec.startsWith('@')) {
-    const atIndex = packageSpec.indexOf('@', 1);
-    if (atIndex === -1) {
-      pkgName = packageSpec;
-      pkgVersion = undefined;
-    } else {
-      pkgName = packageSpec.slice(0, atIndex);
-      pkgVersion = packageSpec.slice(atIndex + 1);
-    }
-  } else {
-    const atIndex = packageSpec.indexOf('@');
-    if (atIndex === -1) {
-      pkgName = packageSpec;
-      pkgVersion = undefined;
-    } else {
-      pkgName = packageSpec.slice(0, atIndex);
-      pkgVersion = packageSpec.slice(atIndex + 1);
-    }
-  }
+  const npa = require('npm-package-arg');
+  const parsed = npa(packageSpec);
+  const pkgName = parsed.name;
+  const pkgVersion = parsed.fetchSpec;
   log.info(`🔍 HIPP Verify: ${pkgName}${pkgVersion ? '@' + pkgVersion : ''}`);
 
-  const registryUrl = `https://registry.npmjs.org/${encodeURIComponent(pkgName)}/${pkgVersion || 'latest'}`;
+  const registryUrl = `https://registry.npmjs.org/${parsed.escapedName}/${pkgVersion || 'latest'}`;
 
-  log.info(`📦 Fetching from npm...`);
+  log.info(`📦 Fetching manifest from npm...`);
   const registryJson = runCmd('curl', ['-s', '-L', registryUrl]);
   let tarballUrl;
+  let manifest;
   try {
     const json = JSON.parse(registryJson.stdout.trim());
     tarballUrl = json.dist.tarball;
@@ -452,6 +439,10 @@ async function runVerify(packageSpec) {
       fail(`❌ Failed to download tarball`);
     }
 
+    const npmTarballContent = fs.readFileSync(tarballPath);
+    const npmHash = sha256(npmTarballContent);
+    log.success(`📦 NPM tarball hash: ${npmHash.slice(0, 12)}...`);
+
     if (fs.existsSync(extractDir)) {
       fs.rmSync(extractDir, { recursive: true });
     }
@@ -464,25 +455,25 @@ async function runVerify(packageSpec) {
     }
 
     const packageDir = path.join(extractDir, 'package');
-    const stagedReadmePath = path.join(packageDir, 'README.md');
+    const npmReadmePath = path.join(packageDir, 'README.md');
 
-    if (!fs.existsSync(stagedReadmePath)) {
-      fail(`❌ README.md not found in package at ${stagedReadmePath}`);
+    if (!fs.existsSync(npmReadmePath)) {
+      fail(`❌ README.md not found in npm package`);
     }
 
-    const stagedReadme = fs.readFileSync(stagedReadmePath, 'utf8');
-    const manifest = findLastJsonBlock(stagedReadme);
-    if (!manifest || !manifest.origin || !manifest.tag || !manifest.hash || !manifest.signature) {
+    const npmReadme = fs.readFileSync(npmReadmePath, 'utf8');
+    manifest = findLastJsonBlock(npmReadme);
+    if (!manifest || !manifest.origin || !manifest.tag || !manifest.hash || !manifest.signature || !manifest.name || !manifest.email) {
       fail(`❌ Manifest not found or invalid in README`);
     }
 
-    const { origin: originUrl, tag, hash: npmHash, signature } = manifest;
+    const { origin: originUrl, tag, signature, name, email } = manifest;
 
+    log.info(`🌿 Cloning git origin at tag ${tag}...`);
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), `hipp-verify-git-`));
     const stageDir = fs.mkdtempSync(path.join(os.tmpdir(), `hipp-verify-stage-`));
 
     try {
-      log.info(`🌿 Fetching from git origin at tag ${tag}...`);
       git(['clone', '--branch', tag, '--depth', '1', originUrl, tmpDir], { stdio: 'pipe' });
 
       const publicKeyPath = path.join(tmpDir, 'hipp.pub');
@@ -496,24 +487,52 @@ async function runVerify(packageSpec) {
       const trackedFiles = getTrackedFilesFromDir(tmpDir);
       copyTrackedFilesFromDir(stageDir, tmpDir, trackedFiles);
 
-      log.info(`📦 Packing to verify content hash...`);
-      const { tarballHash } = packAndHash(stageDir);
+      log.info(`📦 Packing clean git files...`);
+      const { tarballHash: cleanHash } = packAndHash(stageDir);
+      log.success(`📦 Clean hash: ${cleanHash.slice(0, 12)}...`);
 
-      if (tarballHash !== npmHash) {
-        fail(`❌ Hash mismatch: git content does not match npm manifest`);
+      log.info(`🔍 Check 2: Verifying manifest hash...`);
+      if (cleanHash !== manifest.hash) {
+        fail(`❌ Manifest hash mismatch: clean git tarball does not match manifest`);
       }
+      log.success(`🔒 Manifest hash verified`);
 
-      log.success(`🔒 Content hash verified: ${npmHash.slice(0, 12)}...`);
-
-      const signData = buildSignData(npmHash, originUrl, tag);
+      log.info(`🔍 Check 1: Verifying signature...`);
+      const signData = buildSignData(manifest.hash, originUrl, tag, name, email);
       const signatureValid = verifySignature(signData, signature, publicKey);
-
       if (!signatureValid) {
         fail(`❌ Signature verification failed`);
       }
-
       log.success(`🔏 Signature verified`);
-      log.success(`✅ Package ${pkgName} verified successfully!`);
+
+      log.info(`🔍 Check 3: Rebuilding from source...`);
+      const stagedReadmePath = path.join(stageDir, 'README.md');
+      let stagedReadme = fs.readFileSync(stagedReadmePath, 'utf8');
+      stagedReadme = stagedReadme.trimEnd() + '\n\n```json\n' + JSON.stringify(manifest, null, 2) + '\n```\n';
+      fs.writeFileSync(stagedReadmePath, stagedReadme);
+
+      const stagedPkgPath = path.join(stageDir, 'package.json');
+      const stagedPkg = JSON.parse(fs.readFileSync(stagedPkgPath, 'utf8'));
+      const tagVersion = semver.clean(tag);
+      if (!tagVersion) {
+        fail(`❌ Tag ${tag} is not valid semver`);
+      }
+      stagedPkg.version = tagVersion;
+      fs.writeFileSync(stagedPkgPath, JSON.stringify(stagedPkg, null, 2) + '\n');
+
+      const { tarballHash: rebuildHash } = packAndHash(stageDir);
+      log.success(`📦 Rebuild hash: ${rebuildHash.slice(0, 12)}...`);
+
+      if (rebuildHash !== npmHash) {
+        log.error(`❌ Rebuild mismatch!`);
+        log.error(`   NPM tarball:  ${npmHash}`);
+        log.error(`   Git rebuild:  ${rebuildHash}`);
+        fail(`❌ Package integrity compromised`);
+      }
+      log.success(`🔄 Rebuild verified`);
+
+      log.success(`✅ Verified: all checks passed`);
+      log.info(`📍 Publisher: ${name} <${email}>`);
       log.info(`📍 Origin: ${originUrl}`);
       log.info(`📍 Tag: ${tag}`);
     } finally {
@@ -613,7 +632,8 @@ async function run() {
       stagedReadme = fs.readFileSync(stagedReadmePath, 'utf8');
     }
 
-    const dataToSign = buildSignData(tarballHash, provenance.remoteUrl, rawTag);
+    const { name, email } = getGitUserInfo();
+    const dataToSign = buildSignData(tarballHash, provenance.remoteUrl, rawTag, name, email);
     const signature = signContent(dataToSign, privateKey);
 
     const manifestJson = {
@@ -621,6 +641,8 @@ async function run() {
       tag: rawTag,
       hash: tarballHash,
       signature: signature,
+      name: name,
+      email: email,
     };
 
     stagedReadme = stagedReadme.trimEnd() + '\n\n```json\n' + JSON.stringify(manifestJson, null, 2) + '\n```\n';
@@ -666,19 +688,33 @@ const isVerify = process.argv.includes('verify');
 const verifyIndex = process.argv.indexOf('verify');
 const packageSpec = verifyIndex !== -1 ? process.argv[verifyIndex + 1] : null;
 
-if (isVerify && packageSpec) {
-  runVerify(packageSpec);
+if (isVerify) {
+  const specToVerify = packageSpec;
+  if (specToVerify) {
+    runVerify(specToVerify);
+  } else {
+    const hippPkgPath = path.join(path.dirname(process.argv[1]), 'package.json');
+    const hippPkg = JSON.parse(fs.readFileSync(hippPkgPath, 'utf8'));
+    runVerify(`${hippPkg.name}@${hippPkg.version}`);
+  }
 } else if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(`\x1b[36mHIPP - High Integrity Package Publisher\x1b[0m
 
 Usage:
   npx hipp [options] [-- npm-options]
-  npx hipp verify <package>[@version]
+  npx hipp verify [@package[@version]]
+
+  Without arguments, verifies the installed hipp version.
 
 Options:
   -y, --yes   Skip confirmation prompt
   -h, --help  Show this help
 
+Verify: Downloads npm tarball, clones git at tag, runs all three verification checks:
+  1. Signature verification (manifest signed by private key)
+  2. Manifest hash (clean git tarball matches manifest hash)
+  3. Rebuild verification (npm tarball equals git rebuild with manifest+version)
+
 Integrity rules:
   - package.json version must be 0.0.0
   - package-lock.json must exist and be tracked

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dk/hipp",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "High Integrity Package Publisher",
   "main": "hipp.js",
   "bin": {
@@ -11,6 +11,7 @@
   },
   "author": "Dmytri Kleiner <dev@dmytri.to>",
   "dependencies": {
+    "npm-package-arg": "^13.0.2",
     "semver": ">=7.6.0"
   },
   "engines": {