@dk/hipp 0.1.30 → 0.1.32

package/README.md

@@ -4,7 +4,7 @@ By Dmytri Kleiner <dev@dmytri.to>
 
 **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`.
+Your `package.json` version stays at `0.0.0` (or matches your latest tag).
 
 ---
 
@@ -22,10 +22,10 @@ This creates a **State Conflict**:
 
 ## The Solution
 
-**HIPP makes `package.json` version immutable (0.0.0)** - the **HIPP Doctrine**.
-
-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.
+**HIPP makes Git tags the source of truth** - the version is always extracted
+from the tag, not `package.json`. You can leave `package.json` at `0.0.0` (HIPP
+rewrites it during publish) or keep it in sync with your tag (HIPP verifies the
+match).
 
 ---
 
@@ -33,13 +33,14 @@ stays clean, and your registry package is guaranteed to match your Git tag.
 
 ### Setup
 
-1. Set your project's `package.json` version to `0.0.0`:
+Set your project's `package.json` version to `0.0.0`, or leave it in sync with
+your latest tag. The git tag is always the source of truth.
 
 ```json
 { "name": "your-package", "version": "0.0.0" }
 ```
 
-2. Ensure `package-lock.json` exists and is tracked by git.
+Ensure `package-lock.json` exists and is tracked by git.
 
 ### Tag and Publish
 
@@ -68,7 +69,7 @@ npx @dk/hipp -- --access public --tag beta
 HIPP will:
 
 1. **Key Generation**: Generate Ed25519 signing keys if needed (`hipp.priv`, `hipp.pub`)
-2. **Verify**: Ensure the `0.0.0` doctrine is being followed
+2. **Verify**: Ensure `package.json` version is `0.0.0` or matches the git tag
 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
@@ -93,6 +94,17 @@ 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.
 
+### Why This Works
+
+The public key in `hipp.pub` is committed to git at the specific revision of
+each release. Verification always uses the key from that historical revision,
+not a current one. This means:
+
+- You don't need to retain your private key — once published, past releases are
+  verifiable from the git history alone
+- A compromised private key can only sign future releases, not forge past ones
+- Multiple publishers work naturally because each release is self-contained
+
 ### Options
 
 * `-y, --yes`: Skip the confirmation prompt (ideal for CI/CD pipelines).
@@ -208,7 +220,7 @@ package, but only private key holders can publish.
 
 HIPP enforces strict integrity rules when publishing:
 
-- `package.json` version must be `0.0.0`
+- `package.json` version must be `0.0.0` or match the git tag
 - `package-lock.json` must exist and be tracked by git
 - `npm ci --ignore-scripts --dry-run` must succeed
 - Repository must be clean
@@ -242,21 +254,21 @@ PERFORMANCE OF THIS SOFTWARE.
 Verify this package with [@dk/hipp](https://www.npmjs.com/package/@dk/hipp):
 
 ```bash
-npx @dk/hipp verify @dk/hipp@0.1.30
+npx @dk/hipp verify @dk/hipp@0.1.32
 ```
 
 ```json
 {
   "origin": "git@github.com:dmytri/hipp.git",
-  "tag": "v0.1.30",
-  "revision": "0d839e7b5eaba3c88a61c64c4524d3552c76140c",
-  "hash": "9005dcdfea5d0d29d28d74fea47954a1c367a2730f7ddb36e89f8683785a3c4a",
-  "signature": "XKG7xLbzCDxYWC2V+RhEoUWyU0Wp4F6ytufa4NJ6824Sl17VR6Abe/Aw/VS1MfOZFxifJrWGB0e8MYdZ1hCaBg==",
+  "tag": "v0.1.32",
+  "revision": "2aa00fdf83fe709d8707ed1b568b104a21b8d3e8",
+  "hash": "f130afe85486afc6f41d3c4f2439e3c9e4cee3fb36fd323a0476908e730daa90",
+  "signature": "CfrmQ5a/cQwW7Sy3pYInuEdPOZH+SlrS3l7g6h0cQmNa38CcsVg9sZI1hG4XZSj9YT2cB6EAetDbOnljPqE8CA==",
   "name": "Dmytri Kleiner",
   "email": "dev@dmytri.to",
   "npm": "11.12.1",
   "node": "v25.8.2",
   "git": "git version 2.47.3",
-  "hipp": "0.1.30"
+  "hipp": "0.1.32"
 }
 ```

package/hipp.js

@@ -218,9 +218,9 @@ function getVersionFromExactTagOnHead() {
   }
 }
 
-function ensureCleanRepo(pkg) {
-  if (pkg.version !== '0.0.0') {
-    fail('❌ Integrity Violation: package.json version must be 0.0.0');
+function ensureCleanRepo(pkg, tagVersion) {
+  if (pkg.version !== '0.0.0' && pkg.version !== tagVersion) {
+    fail(`❌ Integrity Violation: package.json version must be 0.0.0 or match the git tag (v${tagVersion})`);
   }
 
   if (pkg.workspaces) {
@@ -525,6 +525,8 @@ async function runVerify(packageSpec) {
       } else {
         const publicKey = fs.readFileSync(publicKeyPath, 'utf8');
 
+        log.info(`🔑 Public key: hipp.pub from git@rev ${revision.slice(0, 12)} at tag ${tag}`);
+
         log.info(`🏗️  Staging git files...`);
         const trackedFiles = getTrackedFilesFromDir(tmpDir);
         copyTrackedFilesFromDir(stageDir, tmpDir, trackedFiles);
@@ -674,7 +676,7 @@ async function run() {
 
   const { rawTag, version } = getVersionFromExactTagOnHead();
 
-  ensureCleanRepo(pkg);
+  ensureCleanRepo(pkg, version);
 
   const refInfo = ensureMutableRefPolicy();
   const provenance = ensureRemoteProvenance(rawTag, refInfo.head);
@@ -794,14 +796,12 @@ if (isVerify) {
   if (!hasSelf) {
     try {
       const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
-      if (pkg.version === '0.0.0') {
-        const rawTag = git(['describe', '--tags', '--exact-match', 'HEAD']);
-        if (rawTag.startsWith('v')) {
-          const tagVersion = semver.clean(rawTag);
-          if (tagVersion) {
-            runVerify(`${pkg.name}@${tagVersion}`);
-            return;
-          }
+      const rawTag = git(['describe', '--tags', '--exact-match', 'HEAD']);
+      if (rawTag.startsWith('v')) {
+        const tagVersion = semver.clean(rawTag);
+        if (tagVersion && (pkg.version === '0.0.0' || pkg.version === tagVersion)) {
+          runVerify(`${pkg.name}@${tagVersion}`);
+          return;
         }
       }
     } catch {}
@@ -820,8 +820,8 @@ Usage:
   npx hipp verify [@package[@version]]
   npx hipp verify --self
 
-  Without arguments: in a hipp repo (package.json version 0.0.0 with a
-  semver tag on HEAD), verifies the published package at that version.
+  Without arguments: in a hipp repo (package.json version 0.0.0 or matching
+  a semver tag on HEAD), verifies the published package at that version.
   Otherwise verifies @dk/hipp itself.
   --self: always verifies @dk/hipp.
 
@@ -835,7 +835,7 @@ Verify: Downloads npm tarball, clones git at tag, runs all three verification ch
   3. Rebuild verification (npm tarball equals git rebuild with manifest+version)
 
 Integrity rules:
-  - package.json version must be 0.0.0
+  - package.json version must be 0.0.0 or match the git tag
   - package-lock.json must exist and be tracked
   - npm ci --ignore-scripts --dry-run must succeed
   - repository must be clean

package/package.json

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