@dk/hipp 0.1.16 → 0.1.19

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
-
-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:
+## The Problem
 
-`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.
+Traditional NPM versioning requires storing the "Version of Truth" in `package.json`.
+This creates a **State Conflict**:
 
-**HIPP ensures they are fundamentally linked by extracting the version directly
-from the Git Tag, and cryptographically signing the package contents.**
+- `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
 
-### No "Chore" Noise
+## The Solution
 
-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 `package.json` version immutable (0.0.0)** - the **HIPP Doctrine**.
 
-**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,10 +90,11 @@ 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
@@ -102,8 +102,7 @@ npx @dk/hipp verify @dk/your-package[@version]
 **Step 1: Get manifest from npm**
 
 1. Fetch the package tarball from npm registry
-2. Extract the README from the tarball
-3. Parse the JSON manifest appended to the README
+2. Extract the README and parse the JSON manifest appended to it
 
 The manifest contains:
 ```json
@@ -111,42 +110,73 @@ The manifest contains:
   "origin": "git@github.com:dk/your-package.git",
   "tag": "v1.0.0",
   "hash": "<sha256-of-tarball>",
-  "signature": "<base64-ed25519-signature>"
+  "signature": "<base64-ed25519-signature>",
+  "name": "Jane Developer",
+  "email": "jane@example.com"
 }
 ```
 
-**Step 2: Clone git and stage**
+**Step 2: Clone git and verify**
 
-4. Clone the repository at the tagged commit (using origin/tag from manifest)
-5. Copy all tracked files to a staging directory
+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 content integrity**
+**Step 3: Verify signature**
 
-6. Run `npm pack` in the staging directory
-7. Compute the SHA256 hash of the resulting tarball
-8. Compare this hash with the `hash` field from the npm manifest
+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`
 
-**If the hashes match**: The npm package exactly matches the git repository at the tagged commit.
+**Step 4: Rebuild verification**
 
-**Step 4: Verify signature authenticity**
+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
 
-9. Read `hipp.pub` from the cloned repository at the tagged commit
-10. Verify the signature using the public key
+### Three Verification Checks
 
-The signature was created by signing: `hash + "\n" + origin + "\n" + tag`
-
-**If the signature is valid**: The package was published by the holder of the private key matching `hipp.pub`.
+| 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
 
-| Check | Guarantees |
-|-------|-----------|
-| **Hash match** | npm package content exactly matches git at the tagged commit |
-| **Signature valid** | Published by holder of the private key matching `hipp.pub` |
+- **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.
 
-This provides two independent guarantees:
-- **Integrity**: The code in npm is exactly what was in git at the tag
-- **Authenticity**: The publisher controls the private key for `hipp.pub`
+---
+
+## 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
+
+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
 
@@ -166,14 +196,6 @@ HIPP enforces strict integrity rules when publishing:
 
 ---
 
-## 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>
@@ -189,11 +211,21 @@ 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.
 
+## Verify
+
+Verify this package with [@dk/hipp](https://www.npmjs.com/package/@dk/hipp):
+
+```bash
+npx @dk/hipp verify @dk/hipp@0.1.19
+```
+
 ```json
 {
   "origin": "git@github.com:dmytri/hipp.git",
-  "tag": "v0.1.16",
-  "hash": "935d7b90b43afd348840645f7fd629054bf50716c317fc41065b2cccf7513680",
-  "signature": "QIM4TZ3kuYv7/z3RZSkVPK74XI1PFyD/XLARR2evDCEwNOt1VlXIPXwaMZFn1kH0gDQxx3PuF73Kokld+dMjBw=="
+  "tag": "v0.1.19",
+  "hash": "adcdd07b563c5667d405b36ee1e391710e1baf4ee9434b1fd2f5a11c2acdecf0",
+  "signature": "MdkA4AbDX4ofShqXKJxwWX+x+RWQJU16WpSkFvHU8LihgdIBJbsyNvzIfrjm+3cll2FdR5u3+/dwv+a0rHbUDw==",
+  "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,57 @@ 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');
+      const tagVersion = semver.clean(tag);
+      if (!tagVersion) {
+        fail(`❌ Tag ${tag} is not valid semver`);
+      }
+      stagedReadme = stagedReadme.trimEnd() + '\n\n## Verify\n\n' +
+        'Verify this package with [@dk/hipp](https://www.npmjs.com/package/@dk/hipp):\n\n' +
+        '```bash\n' +
+        `npx @dk/hipp verify ${pkgName}@${tagVersion}\n` +
+        '```\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'));
+      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 +637,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,9 +646,16 @@ 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';
+    stagedReadme = stagedReadme.trimEnd() + '\n\n## Verify\n\n' +
+      'Verify this package with [@dk/hipp](https://www.npmjs.com/package/@dk/hipp):\n\n' +
+      '```bash\n' +
+      `npx @dk/hipp verify ${pkg.name}@${version}\n` +
+      '```\n\n' +
+      '```json\n' + JSON.stringify(manifestJson, null, 2) + '\n```\n';
     fs.writeFileSync(stagedReadmePath, stagedReadme);
 
     const stagedPkgPath = path.join(stageDir, 'package.json');
@@ -666,19 +698,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.16",
+  "version": "0.1.19",
   "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": {