@dk/hipp 0.1.5 → 0.1.7

package/README.md

@@ -1,4 +1,4 @@
-# 🚀 HIPP: High Integrity Package Publisher
+# HIPP: High Integrity Package Publisher
 
 By Dmytri Kleiner <dev@dmytri.to>
 
@@ -7,43 +7,51 @@ 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.
+
 ---
 
-## 🧐 Why HIPP?
+## 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:
 
-### 1. Integrity Failure in standard workflow
 `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. 
+the code in the registry matches the code at that tag.
 
 **HIPP ensures they are fundamentally linked by extracting the version directly
-from the Git Tag.**
+from the Git Tag, and cryptographically signing the package contents.**
+
+### No "Chore" Noise
 
-### 2. Chore" Noise & Merge Conflicts
 Every release usually requires a "chore: bump version" commit. When multiple
 branches are developed simultaneously, these version changes cause constant,
-trivial merge conflicts. 
+trivial merge conflicts.
 
 **HIPP makes your `package.json` version immutable (0.0.0), so it never
 conflicts and your git history stays clean.**
 
 ---
 
-## 🛠 Usage
+## Usage
+
+### Setup
 
-### 1. The Setup 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`. This is the **HIPP Doctrine**.
 
 ```json
 { "name": "your-package", "version": "0.0.0" }
 ```
 
-### 2. Tag and Publish with HIPP
+2. Ensure `package-lock.json` exists and is tracked by git.
+
+### Tag and Publish
 
 ```bash
 git tag v1.0.0
@@ -51,26 +59,82 @@ npx @dk/hipp
 ```
 
 HIPP will:
-1.  **Verify**: Ensure the `0.0.0` doctrine is being followed.
-2.  **Clean Check**: Ensure your git status is clean (no uncommitted local
-    "drift").
-3.  **Validate**: Extract and verify the latest tag against Semver rules.
-4.  **Confirm**: Ask for a 🚀 confirmation before ignition.
-5.  **Restore**: Automatically return your local files to `0.0.0` after the
-    smoke clears.
+
+1. **Key Generation**: Generate Ed25519 signing keys if needed (`hipp.priv`, `hipp.pub`)
+2. **Verify**: Ensure the `0.0.0` doctrine is being followed
+3. **Clean Check**: Ensure your git status is clean
+4. **Validate**: Extract and verify the latest tag against Semver rules
+5. **Sign**: Create a cryptographic manifest of your package content
+6. **Publish**: Publish to npm from a staging directory (never mutating your source)
+7. **Confirm**: Ask for confirmation before ignition (skip with `-y`)
+
+### Signing Keys
+
+On first run, HIPP generates an Ed25519 keypair:
+
+- **`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.
 
 ### Options
-* `-y, --yes`: Skip the confirmation (ideal for CI/CD pipelines).
 
-If you need to pass additional flags to npm publish (like access or a custom registry), use the -- separator:
-Bash
+* `-y, --yes`: Skip the confirmation prompt (ideal for CI/CD pipelines).
+
+To pass additional flags to npm publish (like access or a custom registry), use `--`:
+
+```bash
+npx @dk/hipp -- --access public --tag beta
+```
+
+---
+
+## Verification
+
+HIPP provides out-of-band verification to guarantee package integrity:
+
+```bash
+npx @dk/hipp verify @dk/your-package[@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
+
+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
 
-`npx @dk/hipp -- --access public --tag beta`
+### Integrity Rules
 
+HIPP enforces strict integrity rules:
+
+- `package.json` version must be `0.0.0`
+- `package-lock.json` must exist and be tracked by git
+- `npm ci --ignore-scripts --dry-run` must succeed
+- Repository must be clean
+- HEAD must be on a branch with an upstream
+- HEAD must exactly match upstream
+- HEAD must have an exact v-prefixed semver tag
+- The exact tag must exist on origin and match locally
+- HEAD commit must be contained in an origin remote branch
+- Only git-tracked files are staged
+- Only staged `package.json` is rewritten
+
+---
+
+## 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
+## License
 
 **0BSD** (BSD Zero Clause License)  By Dmytri Kleiner <dev@dmytri.to>
 
@@ -83,5 +147,14 @@ FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
 INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 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. ```
+PERFORMANCE OF THIS SOFTWARE.
+```json
+{
+  "origin": "git@github.com:dmytri/hipp.git",
+  "tag": "v0.1.7"
+}
+```
+
+```npx @dk/hipp @dk/hipp@0.1.7```
 
+<!-- HIPP-MANIFEST -->```eyJoYXNoIjoiODYxNDgxZmM3Yzk0ZTM4YTJhZjdjNDc3ZmJkMDcyMTA2YTMyYTI2MjdkYmM1ZTg4MTI1OTk1ODMyYjdlMzhhMiIsInNpZ25hdHVyZSI6IkVnUTBSZUMzU0hKanovdFZoWlY0V3U1SVJOMDJTSlFPWUtxOFBrdHFpcUhvWnRTbE5pQWxrN25nWDcySldxL0ZRa2JTVE10TldlZUNrSG9hczAwR0N3PT0ifQ==```<!-- /HIPP-MANIFEST -->

package/hipp.js

@@ -42,6 +42,126 @@ function sha256(input) {
   return crypto.createHash('sha256').update(input).digest('hex');
 }
 
+function getPrivateKeyPath() {
+  return path.join(process.cwd(), 'hipp.priv');
+}
+
+function getPublicKeyPath() {
+  return path.join(process.cwd(), 'hipp.pub');
+}
+
+function generateKeyPair() {
+  const { generateKeyPairSync } = crypto;
+  const { privateKey, publicKey } = generateKeyPairSync('ed25519', {
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+  return { privateKey, publicKey };
+}
+
+function loadOrGenerateKeys() {
+  const privPath = getPrivateKeyPath();
+  const pubPath = getPublicKeyPath();
+
+  if (fs.existsSync(privPath) && fs.existsSync(pubPath)) {
+    return {
+      privateKey: fs.readFileSync(privPath, 'utf8'),
+      publicKey: fs.readFileSync(pubPath, 'utf8'),
+    };
+  }
+
+  log.info('🔑 Generating Ed25519 keypair...');
+  const { privateKey, publicKey } = generateKeyPair();
+
+  fs.writeFileSync(privPath, privateKey, { mode: 0o600 });
+  fs.writeFileSync(pubPath, publicKey);
+
+  log.success('🔑 Keypair generated.');
+
+  const gitignorePath = path.join(process.cwd(), '.gitignore');
+  let gitignore = '';
+  if (fs.existsSync(gitignorePath)) {
+    gitignore = fs.readFileSync(gitignorePath, 'utf8');
+  }
+  if (!gitignore.includes('hipp.priv')) {
+    fs.writeFileSync(gitignorePath, gitignore.trimEnd() + '\nhipp.priv\n');
+    log.info('📝 Added hipp.priv to .gitignore');
+  }
+
+  return { privateKey, publicKey };
+}
+
+function signContent(data, privateKey) {
+  const signature = crypto.sign(null, Buffer.from(data), {
+    key: privateKey,
+    dsaEncoding: 'ieee-p1363',
+  });
+  return signature.toString('base64');
+}
+
+function verifySignature(data, signature, publicKey) {
+  const verify = crypto.verify;
+  return verify(null, Buffer.from(data), {
+    key: publicKey,
+    dsaEncoding: 'ieee-p1363',
+  }, Buffer.from(signature, 'base64'));
+}
+
+function createManifest(hash, signature) {
+  return Buffer.from(JSON.stringify({ hash, signature })).toString('base64');
+}
+
+function parseManifest(manifestBase64) {
+  try {
+    return JSON.parse(Buffer.from(manifestBase64, 'base64').toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function buildSignData(hash, origin, tag) {
+  return `${hash}\n${origin}\n${tag}\n`;
+}
+
+const MANIFEST_START = '<!-- HIPP-MANIFEST -->';
+const MANIFEST_END = '<!-- /HIPP-MANIFEST -->';
+
+function appendManifestToReadme(readmeContent, manifest) {
+  return `${readmeContent}${MANIFEST_START}\`\`\`${manifest}\`\`\`${MANIFEST_END}\n`;
+}
+
+function extractManifestFromReadme(readmeContent) {
+  const startIdx = readmeContent.indexOf(MANIFEST_START);
+  if (startIdx === -1) return null;
+  const endIdx = readmeContent.indexOf(MANIFEST_END, startIdx);
+  if (endIdx === -1) return null;
+  const content = readmeContent.slice(startIdx + MANIFEST_START.length, endIdx).trim();
+  const match = content.match(/^```(.+)```$/s);
+  if (!match) return null;
+  return match[1];
+}
+
+function stripManifestFromReadme(readmeContent) {
+  const startIdx = readmeContent.indexOf(MANIFEST_START);
+  const endIdx = readmeContent.indexOf(MANIFEST_END, startIdx);
+  if (startIdx === -1 || endIdx === -1) return readmeContent;
+
+  const endLineIdx = readmeContent.indexOf('\n', endIdx);
+  const endOfManifest = endLineIdx !== -1 ? endLineIdx + 1 : readmeContent.length;
+
+  const beforeWithNewline = readmeContent.slice(0, startIdx);
+  const lastNewlineBefore = beforeWithNewline.lastIndexOf('\n');
+  const before = lastNewlineBefore !== -1 ? beforeWithNewline.slice(0, lastNewlineBefore) : beforeWithNewline;
+
+  const after = readmeContent.slice(endOfManifest);
+  return before + '\n' + after;
+}
+
+function computeReadmeHash(readmeContent) {
+  const stripped = stripManifestFromReadme(readmeContent);
+  return sha256(stripped);
+}
+
 function safeStageName(name) {
   return name.replace(/[^a-zA-Z0-9._-]/g, '-');
 }
@@ -237,6 +357,106 @@ function copyTrackedFiles(stageDir, files) {
   }
 }
 
+async function runVerify(packageSpec) {
+  const [pkgName, pkgVersion] = packageSpec.split('@');
+  log.info(`🔍 HIPP Verify: ${pkgName}${pkgVersion ? '@' + pkgVersion : ''}`);
+
+  const registryUrl = 'https://registry.npmjs.org';
+  const fetchUrl = `${registryUrl}/${encodeURIComponent(pkgName)}/${pkgVersion ? pkgVersion : 'latest'}`;
+
+  log.info(`📦 Fetching from npm...`);
+  let tarballUrl;
+  try {
+    const fetchResult = runCmd('curl', ['-s', '-L', '-w', '%{url_effective}', '-o', '/dev/null', fetchUrl]);
+    tarballUrl = fetchResult.stdout.trim();
+  } catch {
+    fail(`❌ Failed to fetch package info for ${pkgName}`);
+  }
+
+  const tarballPath = path.join(os.tmpdir(), `hipp-verify-${safeStageName(pkgName)}-tgz`);
+  try {
+    log.info(`📦 Downloading tarball...`);
+    const curlResult = runCmd('curl', ['-s', '-L', '-o', tarballPath, tarballUrl]);
+    if (curlResult.status !== 0) {
+      fail(`❌ Failed to download tarball`);
+    }
+
+    log.info(`📦 Extracting tarball...`);
+    runCmd('tar', ['-xzf', tarballPath, '-C', os.tmpdir()], { stdio: 'pipe' });
+
+    const packageDir = path.join(os.tmpdir(), 'package');
+    const stagedReadmePath = path.join(packageDir, 'README.md');
+
+    if (!fs.existsSync(stagedReadmePath)) {
+      fail(`❌ README.md not found in package`);
+    }
+
+    const stagedReadme = fs.readFileSync(stagedReadmePath, 'utf8');
+    const manifestBase64 = extractManifestFromReadme(stagedReadme);
+    if (!manifestBase64) {
+      fail(`❌ Manifest not found in README`);
+    }
+
+    const manifest = parseManifest(manifestBase64);
+    if (!manifest || !manifest.hash || !manifest.signature) {
+      fail(`❌ Invalid manifest format`);
+    }
+
+    log.info(`📦 Extracting tarball to staging...`);
+    runCmd('tar', ['-xzf', tarballPath, '-C', os.tmpdir()], { stdio: 'pipe' });
+
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), `hipp-verify-git-`));
+    try {
+      log.info(`🌿 Fetching from git origin...`);
+
+      const originUrl = manifest.origin;
+      const tag = manifest.tag;
+
+      git(['clone', '--branch', tag, '--depth', '1', originUrl, tmpDir], { stdio: 'pipe' });
+
+      const clonedReadmePath = path.join(tmpDir, 'README.md');
+      if (!fs.existsSync(clonedReadmePath)) {
+        fail(`❌ README.md not found in git at tag ${tag}`);
+      }
+
+      const clonedReadme = fs.readFileSync(clonedReadmePath, 'utf8');
+      const clonedHash = computeReadmeHash(clonedReadme);
+
+      if (clonedHash !== manifest.hash) {
+        fail(`❌ Hash mismatch: git content does not match npm manifest`);
+      }
+
+      log.success(`🔒 Content hash verified: ${manifest.hash.slice(0, 12)}...`);
+
+      const publicKeyPath = path.join(tmpDir, 'hipp.pub');
+      if (!fs.existsSync(publicKeyPath)) {
+        fail(`❌ hipp.pub not found in git at tag ${tag}`);
+      }
+
+      const publicKey = fs.readFileSync(publicKeyPath, 'utf8');
+      const signData = buildSignData(manifest.hash, originUrl, tag);
+      const signatureValid = verifySignature(signData, manifest.signature, publicKey);
+
+      if (!signatureValid) {
+        fail(`❌ Signature verification failed`);
+      }
+
+      log.success(`🔏 Signature verified`);
+      log.success(`✅ Package ${pkgName} verified successfully!`);
+      log.info(`📍 Origin: ${originUrl}`);
+      log.info(`📍 Tag: ${tag}`);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  } finally {
+    fs.rmSync(tarballPath, { recursive: true, force: true });
+    const packageExtractDir = path.join(os.tmpdir(), 'package');
+    if (fs.existsSync(packageExtractDir)) {
+      fs.rmSync(packageExtractDir, { recursive: true, force: true });
+    }
+  }
+}
+
 async function confirmPrompt(name, version) {
   const rl = readline.createInterface({
     input: process.stdin,
@@ -266,6 +486,19 @@ async function run() {
   }
 
   const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+
+  loadOrGenerateKeys();
+
+  const pubPath = getPublicKeyPath();
+  try {
+    git(['ls-files', '--error-unmatch', 'hipp.pub']);
+  } catch {
+    log.info('📝 Committing hipp.pub to repo...');
+    git(['add', 'hipp.pub']);
+    git(['commit', '-m', 'Add hipp public key for package signing']);
+    log.success('📝 hipp.pub committed.');
+  }
+
   ensureCleanRepo(pkg);
 
   const { rawTag, version } = getVersionFromExactTagOnHead();
@@ -296,11 +529,31 @@ async function run() {
     log.info(`🏗️  Staging tracked files to ${stageDir}...`);
     copyTrackedFiles(stageDir, trackedFiles);
 
+    const { privateKey } = loadOrGenerateKeys();
+
     const stagedPkgPath = path.join(stageDir, 'package.json');
     const stagedPkg = JSON.parse(fs.readFileSync(stagedPkgPath, 'utf8'));
     stagedPkg.version = version;
     fs.writeFileSync(stagedPkgPath, JSON.stringify(stagedPkg, null, 2) + '\n');
 
+    const stagedReadmePath = path.join(stageDir, 'README.md');
+    let stagedReadme = '';
+    if (fs.existsSync(stagedReadmePath)) {
+      stagedReadme = fs.readFileSync(stagedReadmePath, 'utf8');
+    }
+
+    stagedReadme += '\n```json\n{\n  "origin": "' + provenance.remoteUrl + '",\n  "tag": "' + rawTag + '"\n}\n```\n\n```npx @dk/hipp ' + pkg.name + '@' + version + '```\n\n';
+
+    const readmeHash = computeReadmeHash(stagedReadme);
+    const dataToSign = buildSignData(readmeHash, provenance.remoteUrl, rawTag);
+    const signature = signContent(dataToSign, privateKey);
+    const manifest = createManifest(readmeHash, signature);
+    stagedReadme = appendManifestToReadme(stagedReadme, manifest);
+
+    fs.writeFileSync(stagedReadmePath, stagedReadme);
+
+    log.success('🔏 Manifest signed.');
+
     log.info('🔥 Ignition...');
 
     const result = spawnSync('npm', ['publish', ...npmArgs], {
@@ -330,11 +583,18 @@ async function run() {
   }
 }
 
-if (process.argv.includes('--help') || process.argv.includes('-h')) {
+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);
+} 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]
 
 Options:
   -y, --yes   Skip confirmation prompt

package/hipp.pub

@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEA4/mM4ila/URYTYCmHIA33cuDFWtauGHo6TImvHimVa8=
+-----END PUBLIC KEY-----

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dk/hipp",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "High Integrity Package Publisher",
   "main": "hipp.js",
   "bin": {