packattest 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PackAttest contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# PackAttest
+
+> No file is published unless it is seen, selected, and confirmed.
+
+Review the exact npm package artifact before publish.
+PackAttest shows the final tarball, highlights what changed since the previous release, and publishes only the files you explicitly approve.
+
+## Quick Start
+
+```bash
+git clone https://github.com/Divohna/PackAttest.git
+cd <repo-dir>
+npm install
+npm install -g .
+cd /path/to/your-package
+pa review
+```
+
+Typical flow:
+
+- run `pa review` before releasing
+- inspect the exact packaged files and warnings
+- select only the files you want shipped
+- commit the resulting `.packattest` file for CI
+- run `pa publish` locally or `pa verify` in CI
+
+## Demo
+
+Example review session:
+
+```text
+PackAttest — review
+
+Packing artifact... your-package-1.4.0.tgz
+Fetching previous published version... v1.3.9
+
+Diff vs previous: 2 added, 1 modified, 8 unchanged
+
+? Select files to publish  (Space to toggle, A to select all, Enter to confirm)
+❯ ◯ + package/dist/index.js            (18.4KB)
+  ◯ + package/dist/index.js.map        (41.2KB)  [source map]
+  ◯ + package/.env.production          (0.6KB)   [env file]
+  ◯ ~ package/package.json             (0.8KB)
+  ◯   package/README.md                (5.6KB)
+
+? Type "publish 3 files" to confirm › publish 3 files
+
+Attestation written: .packattest
+? Publish now? › Yes
+
+Repacking constrained artifact... ok
+Publishing...
+Done.
+```
+
+The point is not to guess what is safe. The point is to force review of the actual package payload before it leaves your machine.
+
+## Problem
+
+Modern package publishing workflows rely on ignore files and implicit inclusion rules.
+That is fragile for three reasons:
+
+1. ignore rules are easy to forget or misconfigure
+2. they are defined before the final build artifact exists
+3. they do not force review of what will actually be published
+
+As a result, accidental leaks often happen at the artifact stage rather than the source stage.
+
+## Solution
+
+PackAttest is a publish-time verification layer for package release workflows.
+
+Before a package is published, PackAttest:
+
+- enumerates the exact files in the final artifact
+- shows the full file list to the user
+- requires explicit user selection of files to publish
+- compares the current artifact against the previous published version
+- blocks publish if changes have not been reviewed
+
+## Core Principles
+
+1. **Artifact is truth**  
+   Decisions are based on the final package contents, not source-tree assumptions.
+
+2. **No implicit inclusion**  
+   Nothing is published merely because it exists in a folder or matched an old rule.
+
+3. **Explicit human intent**  
+   The user must actively choose what to publish.
+
+4. **Diff-based review**  
+   Review effort should focus on what changed since the previous published version.
+
+5. **Federated trust**  
+   No single baseline file is trusted on its own. Decisions combine:
+   - previous published artifact
+   - current artifact
+   - explicit user selection
+   - policy checks
+
+## Installation
+
+Install from source:
+
+```bash
+git clone https://github.com/Divohna/PackAttest.git
+cd <repo-dir>
+npm install
+npm install -g .
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `pa review` | Enumerate artifact, diff against previous release, interactively select files, write attestation |
+| `pa publish` | Verify the current artifact against an existing `.packattest`, repack the selected files, and publish |
+| `pa verify` | CI mode: run the same verification, repack, and publish flow with step-by-step log output |
+
+## How It Works
+
+Run `pa review` from your package directory to inspect the exact artifact that `npm pack` would publish.
+
+The `.packattest` file records the exact artifact hash, selected files, reviewer identity, and source commit. Commit it to your repository for CI use.
+
+### CI mode
+
+Add to your release workflow:
+
+```bash
+pa verify
+```
+
+`pa verify` re-packs the artifact, checks its hash against the `.packattest` attestation, repacks the constrained artifact, and publishes. It fails hard if the artifact has changed since the last `pa review`.
+
+`pa publish` performs the same guarded publish flow locally, but with simpler interactive-oriented output.
+
+## Why This Model Is Different
+
+Traditional systems trust configuration.
+PackAttest trusts reality and requires the user to confirm intent.
+
+That means:
+
+- the system may enumerate files automatically
+- the system must not silently choose files on the user's behalf
+- the system must not pre-select files by default
+- the system must block unreviewed additions
+
+## Security Properties
+
+PackAttest is designed to prevent:
+
+- accidental inclusion of source maps
+- accidental inclusion of archives or debug files
+- drift in build outputs
+- silent scope expansion between releases
+
+PackAttest does not claim to prevent:
+
+- deliberate malicious publishing
+- secrets embedded inside an explicitly approved file
+- compromise of the developer workstation
+
+## MVP Scope
+
+Version 0.1.0 is a proof of concept focused on:
+
+- `npm pack` integration
+- file enumeration
+- diff against previous published package
+- interactive file selection
+- publish confirmation
+- blocking unselected files
+
+## Repository Layout
+
+```text
+packattest/
+├── README.md
+├── LICENSE
+├── package.json
+├── .packattest           ← written by pa review, commit for CI use
+├── docs/
+│   ├── RFC.md
+│   └── design.md
+├── test/
+│   ├── helpers.js
+│   ├── artifact.test.js
+│   ├── attestation.test.js
+│   ├── diff.test.js
+│   ├── policy.test.js
+│   ├── repack.test.js
+│   └── ui.test.js
+└── cli/
+    ├── index.js
+    ├── commands/
+    │   ├── review.js
+    │   ├── publish.js
+    │   └── verify.js
+    └── lib/
+        ├── artifact.js
+        ├── attestation.js
+        ├── diff.js
+        ├── policy.js
+        ├── registry.js
+        ├── repack.js
+        └── ui.js
+```
+
+## Status
+
+The CLI is fully implemented. All three commands (`pa review`, `pa publish`, `pa verify`) are functional.
+
+Current version: **v0.1.0**
+
+## Contributing
+
+Feedback, critiques, design objections, and implementation help are welcome.
+
+### Development setup
+
+```bash
+git clone https://github.com/Divohna/PackAttest.git
+cd <repo-dir>
+npm install
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Run the CLI locally without installing globally:
+
+```bash
+node cli/index.js review
+node cli/index.js publish
+node cli/index.js verify
+```
+
+After making changes, regenerate the `.packattest` attestation by running `pa review` (or `node cli/index.js review`) from the repo root and committing the updated file.
+
+## License
+
+MIT

package/cli/commands/publish.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const { execSync } = require('child_process');
+const { read: readAttestation } = require('../lib/attestation');
+const { pack, enumerate, canonicalHash } = require('../lib/artifact');
+const { repack } = require('../lib/repack');
+
+async function publish({ otp } = {}) {
+  const cwd = process.cwd();
+
+  console.log('PackAttest — publish\n');
+
+  // Load attestation
+  const attestation = readAttestation(cwd);
+  if (!attestation) {
+    console.error('No .packattest file found. Run `pa review` first.');
+    process.exit(1);
+  }
+
+  console.log(`Attested by:    ${attestation.reviewer}`);
+  console.log(`Attested at:    ${attestation.reviewed_at}`);
+  console.log(`Attested hash:  ${attestation.artifact_hash}`);
+  console.log(`Files selected: ${attestation.selected_files.length}\n`);
+
+  // Pack + enumerate current artifact
+  process.stdout.write('Packing current artifact... ');
+  let tarballPath;
+  try {
+    tarballPath = await pack(cwd);
+  } catch (err) {
+    console.error('\nnpm pack failed:', err.message);
+    process.exit(1);
+  }
+  console.log(path.relative(cwd, tarballPath));
+
+  const entries = await enumerate(tarballPath);
+  const hash = canonicalHash(entries);
+
+  // Verify hash matches attestation
+  process.stdout.write('Verifying artifact hash... ');
+  if (hash !== attestation.artifact_hash) {
+    console.error('\nFAIL: artifact has changed since review.');
+    console.error(`  Attested: ${attestation.artifact_hash}`);
+    console.error(`  Current:  ${hash}`);
+    console.error('\nRun `pa review` again.');
+    try { fs.unlinkSync(tarballPath); } catch {}
+    process.exit(1);
+  }
+  console.log('ok');
+
+  // Verify all selected files exist in current artifact
+  const entryPaths = new Set(entries.map(e => e.path));
+  for (const f of attestation.selected_files) {
+    if (!entryPaths.has(f)) {
+      console.error(`\nFAIL: attested file not found in artifact: ${f}`);
+      try { fs.unlinkSync(tarballPath); } catch {}
+      process.exit(1);
+    }
+  }
+
+  // Repack
+  const tmpPath = path.join(os.tmpdir(), `packattest-${Date.now()}.tgz`);
+  process.stdout.write('Repacking constrained artifact... ');
+  try {
+    await repack(entries, attestation.selected_files, tmpPath);
+  } catch (err) {
+    console.error('\nRepack failed:', err.message);
+    try { fs.unlinkSync(tarballPath); } catch {}
+    process.exit(1);
+  }
+  console.log('ok');
+
+  // Publish
+  console.log('Publishing...\n');
+  try {
+    const otpFlag = otp ? ` --otp ${otp}` : '';
+    execSync(`npm publish "${tmpPath}"${otpFlag}`, { stdio: 'inherit', cwd });
+  } catch {
+    console.error('\nPublish failed.');
+    process.exit(1);
+  } finally {
+    try { fs.unlinkSync(tmpPath); } catch {}
+    try { fs.unlinkSync(tarballPath); } catch {}
+  }
+
+  console.log('\nDone.');
+}
+
+module.exports = publish;

package/cli/commands/review.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const prompts = require('prompts');
+const { pack, enumerate, canonicalHash } = require('../lib/artifact');
+const { computeDiff } = require('../lib/diff');
+const { checkPolicy } = require('../lib/policy');
+const { write: writeAttestation } = require('../lib/attestation');
+const { repack } = require('../lib/repack');
+const { fetchPreviousArtifact } = require('../lib/registry');
+const { choiceTitle, printDiffSummary } = require('../lib/ui');
+
+async function review({ otp } = {}) {
+  const cwd = process.cwd();
+  const pkgJson = require(path.join(cwd, 'package.json'));
+
+  // Collect temp files for cleanup on any exit path
+  const tmpFiles = [];
+  process.on('exit', () => {
+    for (const p of tmpFiles) try { fs.unlinkSync(p); } catch {}
+  });
+
+  console.log('PackAttest — review\n');
+
+  // 1. Pack
+  process.stdout.write('Packing artifact... ');
+  let tarballPath;
+  try {
+    tarballPath = await pack(cwd);
+  } catch (err) {
+    console.error('\nnpm pack failed:', err.message);
+    process.exit(1);
+  }
+  tmpFiles.push(tarballPath);
+  console.log(path.relative(cwd, tarballPath));
+
+  // 2. Enumerate + hash
+  const entries = await enumerate(tarballPath);
+  const hash = canonicalHash(entries);
+
+  // 3. Fetch previous artifact + diff
+  process.stdout.write('Fetching previous published version... ');
+  let diffEntries;
+  let prev;
+  try {
+    prev = await fetchPreviousArtifact(pkgJson.name);
+  } catch (err) {
+    console.error(`\nRegistry lookup failed: ${err.message}`);
+    console.error('Cannot verify diff against previous version. Aborting to avoid skipping review.');
+    process.exit(1);
+  }
+
+  if (prev) {
+    tmpFiles.push(prev.path);
+    console.log(`v${prev.version}`);
+    const prevEntries = await enumerate(prev.path);
+    diffEntries = computeDiff(entries, prevEntries);
+    printDiffSummary(diffEntries);
+  } else {
+    console.log('not found (first-publish mode)');
+    diffEntries = entries.map(e => ({ ...e, status: 'added' }));
+  }
+
+  // 4. Policy checks
+  const policyMap = new Map();
+  for (const entry of entries) {
+    const warnings = checkPolicy(entry);
+    if (warnings.length) policyMap.set(entry.path, warnings);
+  }
+
+  // 5. Build multiselect choices (current-artifact files only, sorted)
+  const current = diffEntries.filter(e => e.status !== 'removed');
+  if (current.length === 0) {
+    console.log('\nNo files in artifact.');
+    process.exit(0);
+  }
+
+  const choices = current.map(entry => ({
+    title: choiceTitle(entry, policyMap.get(entry.path) || []),
+    value: entry.path,
+  }));
+
+  // 6. Interactive selection
+  console.log('');
+  const { selectedPaths } = await prompts({
+    type: 'multiselect',
+    name: 'selectedPaths',
+    message: 'Select files to publish',
+    choices,
+    hint: '- Space to toggle, A to select all, Enter to confirm',
+    min: 1,
+    onState(state) {
+      if (state.aborted) {
+        console.log('\nAborted.');
+        process.exit(1);
+      }
+    },
+  });
+
+  if (!selectedPaths || selectedPaths.length === 0) {
+    console.log('No files selected. Aborting.');
+    process.exit(1);
+  }
+
+  // 7. Confirmation phrase
+  const n = selectedPaths.length;
+  const expected = `publish ${n} file${n === 1 ? '' : 's'}`;
+
+  console.log(`\nReady to publish ${n} file${n === 1 ? '' : 's'}:\n`);
+  selectedPaths.forEach(p => console.log(`  ${p}`));
+  console.log('');
+
+  const { confirmation } = await prompts({
+    type: 'text',
+    name: 'confirmation',
+    message: `Type "${expected}" to confirm`,
+    onState(state) {
+      if (state.aborted) {
+        console.log('\nAborted.');
+        process.exit(1);
+      }
+    },
+  });
+
+  if (confirmation !== expected) {
+    console.log('Confirmation did not match. Aborting.');
+    process.exit(1);
+  }
+
+  // 8. Write attestation
+  const { path: attPath } = writeAttestation(cwd, {
+    packageName: pkgJson.name,
+    packageVersion: pkgJson.version,
+    artifactHash: hash,
+    selectedFiles: selectedPaths,
+  });
+  console.log(`\nAttestation written: ${path.relative(cwd, attPath)}`);
+
+  // 9. Offer to publish now
+  const { publishNow } = await prompts({
+    type: 'confirm',
+    name: 'publishNow',
+    message: 'Publish now?',
+    initial: true,
+    onState(state) {
+      if (state.aborted) {
+        console.log('');
+        process.exit(0);
+      }
+    },
+  });
+
+  if (!publishNow) {
+    console.log('\nRun `pa publish` when ready.');
+    return;
+  }
+
+  // 10. Repack + publish
+  await runPublish({ entries, selectedPaths, cwd, tmpFiles, otp });
+}
+
+async function runPublish({ entries, selectedPaths, cwd, tmpFiles, otp }) {
+  const os = require('os');
+  const { execSync } = require('child_process');
+  const tmpPath = path.join(os.tmpdir(), `packattest-${Date.now()}.tgz`);
+  tmpFiles.push(tmpPath);
+
+  process.stdout.write('\nRepacking constrained artifact... ');
+  try {
+    await repack(entries, selectedPaths, tmpPath);
+  } catch (err) {
+    console.error('\nRepack failed:', err.message);
+    process.exit(1);
+  }
+  console.log('ok');
+
+  console.log('Publishing...\n');
+  try {
+    const otpFlag = otp ? ` --otp ${otp}` : '';
+    execSync(`npm publish "${tmpPath}"${otpFlag}`, { stdio: 'inherit', cwd });
+  } catch {
+    console.error('\nPublish failed.');
+    process.exit(1);
+  }
+
+  console.log('\nDone.');
+}
+
+module.exports = review;

package/cli/commands/verify.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const { execSync } = require('child_process');
+const { read: readAttestation } = require('../lib/attestation');
+const { pack, enumerate, canonicalHash } = require('../lib/artifact');
+const { repack } = require('../lib/repack');
+
+async function verify({ otp } = {}) {
+  const cwd = process.cwd();
+
+  console.log('PackAttest — verify (CI mode)\n');
+
+  const attestation = readAttestation(cwd);
+  if (!attestation) {
+    console.error('FAIL: no .packattest attestation found.');
+    process.exit(1);
+  }
+
+  console.log(`Package:        ${attestation.package_name}@${attestation.package_version}`);
+  console.log(`Attested by:    ${attestation.reviewer}`);
+  console.log(`Attested at:    ${attestation.reviewed_at}`);
+  console.log(`Source commit:  ${attestation.source_commit}`);
+  console.log(`Files selected: ${attestation.selected_files.length}\n`);
+
+  // Step 1: Pack + enumerate
+  process.stdout.write('[1/5] Packing artifact... ');
+  let tarballPath;
+  try {
+    tarballPath = await pack(cwd);
+  } catch (err) {
+    console.error('\nFAIL: npm pack failed:', err.message);
+    process.exit(1);
+  }
+  console.log('ok');
+
+  const entries = await enumerate(tarballPath);
+  const hash = canonicalHash(entries);
+
+  // Step 2: Verify canonical hash
+  process.stdout.write('[2/5] Verifying artifact hash... ');
+  if (hash !== attestation.artifact_hash) {
+    console.error('\nFAIL: artifact has changed since review.');
+    console.error(`  Attested: ${attestation.artifact_hash}`);
+    console.error(`  Current:  ${hash}`);
+    try { fs.unlinkSync(tarballPath); } catch {}
+    process.exit(1);
+  }
+  console.log('ok');
+
+  // Step 3: Verify selected files exist in artifact
+  process.stdout.write('[3/5] Verifying selected files exist... ');
+  const entryPaths = new Set(entries.map(e => e.path));
+  for (const f of attestation.selected_files) {
+    if (!entryPaths.has(f)) {
+      console.error(`\nFAIL: attested file missing from artifact: ${f}`);
+      try { fs.unlinkSync(tarballPath); } catch {}
+      process.exit(1);
+    }
+  }
+  console.log('ok');
+
+  // Step 4: Repack constrained artifact
+  const tmpPath = path.join(os.tmpdir(), `packattest-ci-${Date.now()}.tgz`);
+  process.stdout.write('[4/5] Repacking constrained artifact... ');
+  try {
+    await repack(entries, attestation.selected_files, tmpPath);
+  } catch (err) {
+    console.error('\nFAIL: repack failed:', err.message);
+    try { fs.unlinkSync(tarballPath); } catch {}
+    process.exit(1);
+  }
+  console.log('ok');
+
+  // Step 5: Publish
+  process.stdout.write('[5/5] Publishing... ');
+  try {
+    const otpFlag = otp ? ` --otp ${otp}` : '';
+    execSync(`npm publish "${tmpPath}"${otpFlag}`, { stdio: 'inherit', cwd });
+  } catch {
+    console.error('\nFAIL: publish failed.');
+    process.exit(1);
+  } finally {
+    try { fs.unlinkSync(tmpPath); } catch {}
+    try { fs.unlinkSync(tarballPath); } catch {}
+  }
+  console.log('\nDone.');
+}
+
+module.exports = verify;

package/cli/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+'use strict';
+
+const { program } = require('commander');
+const pkg = require('../package.json');
+
+program
+  .name('pa')
+  .description('Artifact review and attestation for package publishes')
+  .version(pkg.version);
+
+program
+  .command('review')
+  .description('Enumerate artifact, review diff, select files, write attestation')
+  .option('--otp <code>', 'npm one-time password for 2FA')
+  .action((opts) => require('./commands/review')(opts).catch(err => { console.error(err.message); process.exit(1); }));
+
+program
+  .command('publish')
+  .description('Verify current artifact against attestation, repack, and publish')
+  .option('--otp <code>', 'npm one-time password for 2FA')
+  .action((opts) => require('./commands/publish')(opts).catch(err => { console.error(err.message); process.exit(1); }));
+
+program
+  .command('verify')
+  .description('CI: same verification, repack, and publish flow with step-by-step logs')
+  .option('--otp <code>', 'npm one-time password for 2FA')
+  .action((opts) => require('./commands/verify')(opts).catch(err => { console.error(err.message); process.exit(1); }));
+
+program.parse();

package/cli/lib/artifact.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const zlib = require('zlib');
+const tar = require('tar-stream');
+
+async function pack(cwd = process.cwd()) {
+  const raw = execSync('npm pack --json', {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  const result = JSON.parse(raw.toString());
+  return path.resolve(cwd, result[0].filename);
+}
+
+async function enumerate(tarballPath) {
+  return new Promise((resolve, reject) => {
+    const entries = [];
+    const extract = tar.extract();
+
+    extract.on('entry', (header, stream, next) => {
+      if (header.type === 'symlink') {
+        const linkTarget = header.linkname || '';
+        const hash = crypto.createHash('sha256').update(linkTarget).digest('hex');
+        entries.push({
+          path: header.name,
+          size: 0,
+          sha256: hash,
+          _content: Buffer.alloc(0),
+          _header: { mode: header.mode, mtime: header.mtime, uid: header.uid, gid: header.gid, uname: header.uname, gname: header.gname, type: 'symlink', linkname: linkTarget },
+        });
+        stream.resume();
+        next();
+        return;
+      }
+
+      if (header.type !== 'file') {
+        stream.resume();
+        next();
+        return;
+      }
+
+      const chunks = [];
+      const hash = crypto.createHash('sha256');
+
+      stream.on('data', chunk => {
+        chunks.push(chunk);
+        hash.update(chunk);
+      });
+
+      stream.on('end', () => {
+        const content = Buffer.concat(chunks);
+        entries.push({
+          path: header.name,
+          size: content.length,
+          sha256: hash.digest('hex'),
+          _content: content,
+          _header: { mode: header.mode, mtime: header.mtime, uid: header.uid, gid: header.gid, uname: header.uname, gname: header.gname },
+        });
+        next();
+      });
+
+      stream.on('error', reject);
+    });
+
+    extract.on('finish', () => resolve(entries));
+    extract.on('error', reject);
+
+    fs.createReadStream(tarballPath)
+      .on('error', reject)
+      .pipe(zlib.createGunzip())
+      .on('error', reject)
+      .pipe(extract);
+  });
+}
+
+function canonicalManifest(entries) {
+  return [...entries]
+    .sort((a, b) => a.path.localeCompare(b.path))
+    .map(e => ({ path: e.path, size: e.size, sha256: e.sha256 }));
+}
+
+function canonicalHash(entries) {
+  const manifest = canonicalManifest(entries);
+  const digest = crypto
+    .createHash('sha256')
+    .update(JSON.stringify(manifest))
+    .digest('hex');
+  return `sha256:${digest}`;
+}
+
+module.exports = { pack, enumerate, canonicalManifest, canonicalHash };

package/cli/lib/attestation.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const ATTESTATION_FILE = '.packattest';
+
+function gitUser() {
+  try {
+    return 'git:' + execSync('git config user.name', { stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim();
+  } catch {
+    return 'git:unknown';
+  }
+}
+
+function sourceCommit() {
+  try {
+    return execSync('git rev-parse HEAD', { stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+function write(cwd, { packageName, packageVersion, artifactHash, selectedFiles }) {
+  const pkg = require('../../package.json');
+  const record = {
+    version: 1,
+    package_name: packageName,
+    package_version: packageVersion,
+    artifact_hash: artifactHash,
+    selected_files: selectedFiles,
+    reviewed_at: new Date().toISOString(),
+    reviewer: gitUser(),
+    source_commit: sourceCommit(),
+    tool_version: pkg.version,
+  };
+
+  const dest = path.join(cwd, ATTESTATION_FILE);
+  fs.writeFileSync(dest, JSON.stringify(record, null, 2) + '\n');
+  return { path: dest, record };
+}
+
+function read(cwd) {
+  const src = path.join(cwd, ATTESTATION_FILE);
+  if (!fs.existsSync(src)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(src, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { write, read, ATTESTATION_FILE };

package/cli/lib/diff.js

@@ -0,0 +1,29 @@
+'use strict';
+
+// status: 'added' | 'modified' | 'unchanged' | 'removed'
+function computeDiff(currentEntries, previousEntries) {
+  const prevMap = new Map(previousEntries.map(e => [e.path, e]));
+  const currMap = new Map(currentEntries.map(e => [e.path, e]));
+  const result = [];
+
+  for (const entry of currentEntries) {
+    const prev = prevMap.get(entry.path);
+    if (!prev) {
+      result.push({ ...entry, status: 'added' });
+    } else if (prev.sha256 !== entry.sha256) {
+      result.push({ ...entry, status: 'modified' });
+    } else {
+      result.push({ ...entry, status: 'unchanged' });
+    }
+  }
+
+  for (const entry of previousEntries) {
+    if (!currMap.has(entry.path)) {
+      result.push({ ...entry, status: 'removed' });
+    }
+  }
+
+  return result.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+module.exports = { computeDiff };

package/cli/lib/policy.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const path = require('path');
+
+const RULES = [
+  {
+    test: p => p.endsWith('.map'),
+    label: 'source map',
+  },
+  {
+    test: p => /\.(zip|tar|tar\.gz|tgz|rar|7z)$/i.test(p),
+    label: 'archive',
+  },
+  {
+    test: p => p.endsWith('.log'),
+    label: 'log file',
+  },
+  {
+    test: p => /\.env(\.|$)/i.test(path.basename(p)),
+    label: 'env file',
+  },
+  {
+    test: p => /\.(pem|key|p12|pfx|jks)$/i.test(p),
+    label: 'key/cert file',
+  },
+  {
+    test: (p, size) => size > 1024 * 1024,
+    label: 'large file (>1MB)',
+  },
+];
+
+function checkPolicy(entry) {
+  return RULES
+    .filter(rule => rule.test(entry.path, entry.size))
+    .map(rule => rule.label);
+}
+
+module.exports = { checkPolicy };

package/cli/lib/registry.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function httpsGet(url) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers: { 'User-Agent': 'packattest/0.1.0' } }, res => {
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          return httpsGet(res.headers.location).then(resolve).catch(reject);
+        }
+        const chunks = [];
+        res.on('data', c => chunks.push(c));
+        res.on('end', () => resolve({ status: res.statusCode, body: Buffer.concat(chunks) }));
+        res.on('error', reject);
+      })
+      .on('error', reject);
+  });
+}
+
+async function fetchPreviousArtifact(packageName, { _fetch = httpsGet } = {}) {
+  const encoded = packageName.startsWith('@')
+    ? '@' + encodeURIComponent(packageName.slice(1))
+    : encodeURIComponent(packageName);
+
+  let manifest;
+  try {
+    const { status, body } = await _fetch(`https://registry.npmjs.org/${encoded}/latest`);
+    if (status === 404) return null; // genuinely unpublished
+    if (status !== 200) {
+      throw new Error(`Registry returned HTTP ${status} for ${packageName}`);
+    }
+    manifest = JSON.parse(body.toString());
+  } catch (err) {
+    if (err.message && err.message.startsWith('Registry returned')) throw err;
+    throw new Error(`Failed to fetch registry metadata for ${packageName}: ${err.message}`);
+  }
+
+  if (!manifest?.dist?.tarball) {
+    throw new Error(`Registry metadata for ${packageName}@${manifest.version} has no tarball URL`);
+  }
+
+  const version = manifest.version;
+  const safe = packageName.replace(/[^a-z0-9]/gi, '-');
+  const tmpPath = path.join(os.tmpdir(), `packattest-prev-${safe}-${version}.tgz`);
+
+  try {
+    const { status, body } = await _fetch(manifest.dist.tarball);
+    if (status !== 200) {
+      throw new Error(`Tarball download returned HTTP ${status}`);
+    }
+    fs.writeFileSync(tmpPath, body);
+    return { path: tmpPath, version };
+  } catch (err) {
+    throw new Error(`Failed to download previous tarball for ${packageName}@${version}: ${err.message}`);
+  }
+}
+
+module.exports = { fetchPreviousArtifact };

package/cli/lib/repack.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const fs = require('fs');
+const zlib = require('zlib');
+const tar = require('tar-stream');
+const { enumerate } = require('./artifact');
+
+async function repack(entries, selectedPaths, outputPath) {
+  const selectedSet = new Set(selectedPaths);
+  const selectedEntries = entries.filter(e => selectedSet.has(e.path));
+
+  if (selectedEntries.length !== selectedPaths.length) {
+    const found = new Set(selectedEntries.map(e => e.path));
+    const missing = selectedPaths.filter(p => !found.has(p));
+    throw new Error(`Selected files not found in artifact: ${missing.join(', ')}`);
+  }
+
+  await new Promise((resolve, reject) => {
+    const pack = tar.pack();
+    const out = fs.createWriteStream(outputPath);
+
+    pack.pipe(zlib.createGzip()).pipe(out);
+    out.on('finish', resolve);
+    out.on('error', reject);
+    pack.on('error', reject);
+
+    (async () => {
+      for (const entry of selectedEntries) {
+        await new Promise((res, rej) => {
+          if (entry._header && entry._header.type === 'symlink') {
+            const hdr = { name: entry.path, type: 'symlink', linkname: entry._header.linkname };
+            if (entry._header.mode != null) hdr.mode = entry._header.mode;
+            if (entry._header.mtime != null) hdr.mtime = entry._header.mtime;
+            if (entry._header.uid != null) hdr.uid = entry._header.uid;
+            if (entry._header.gid != null) hdr.gid = entry._header.gid;
+            if (entry._header.uname != null) hdr.uname = entry._header.uname;
+            if (entry._header.gname != null) hdr.gname = entry._header.gname;
+            pack.entry(hdr, err => (err ? rej(err) : res()));
+          } else {
+            const hdr = { name: entry.path, size: entry._content.length };
+            if (entry._header) {
+              if (entry._header.mode != null) hdr.mode = entry._header.mode;
+              if (entry._header.mtime != null) hdr.mtime = entry._header.mtime;
+              if (entry._header.uid != null) hdr.uid = entry._header.uid;
+              if (entry._header.gid != null) hdr.gid = entry._header.gid;
+              if (entry._header.uname != null) hdr.uname = entry._header.uname;
+              if (entry._header.gname != null) hdr.gname = entry._header.gname;
+            }
+            pack.entry(hdr, entry._content, err => (err ? rej(err) : res()));
+          }
+        });
+      }
+      pack.finalize();
+    })().catch(reject);
+  });
+
+  // Verify: re-enumerate and check exact match
+  const repacked = await enumerate(outputPath);
+  const repackedPaths = new Set(repacked.map(e => e.path));
+
+  for (const p of selectedPaths) {
+    if (!repackedPaths.has(p)) {
+      throw new Error(`Verification failed: ${p} is missing from constrained artifact`);
+    }
+  }
+  if (repacked.length !== selectedPaths.length) {
+    throw new Error(
+      `Verification failed: constrained artifact has ${repacked.length} files, expected ${selectedPaths.length}`
+    );
+  }
+}
+
+module.exports = { repack };

package/cli/lib/ui.js

@@ -0,0 +1,35 @@
+'use strict';
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+const STATUS_SYMBOL = {
+  added: '+',
+  modified: '~',
+  removed: '-',
+  unchanged: ' ',
+};
+
+function choiceTitle(entry, warnings) {
+  const sym = STATUS_SYMBOL[entry.status] || ' ';
+  const warn = warnings.length ? '  ' + warnings.map(w => `[${w}]`).join(' ') : '';
+  return `${sym} ${entry.path}  (${formatSize(entry.size)})${warn}`;
+}
+
+function printDiffSummary(diffEntries) {
+  const counts = { added: 0, modified: 0, removed: 0, unchanged: 0 };
+  for (const e of diffEntries) counts[e.status] = (counts[e.status] || 0) + 1;
+
+  const parts = [];
+  if (counts.added) parts.push(`${counts.added} added`);
+  if (counts.modified) parts.push(`${counts.modified} modified`);
+  if (counts.removed) parts.push(`${counts.removed} removed`);
+  if (counts.unchanged) parts.push(`${counts.unchanged} unchanged`);
+
+  console.log(`\nDiff vs previous: ${parts.join(', ') || 'no changes'}`);
+}
+
+module.exports = { formatSize, choiceTitle, printDiffSummary };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "packattest",
+  "version": "0.1.0",
+  "description": "Artifact review and attestation for package publishes",
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Divohna/PackAttest.git"
+  },
+  "homepage": "https://github.com/Divohna/PackAttest#readme",
+  "bugs": {
+    "url": "https://github.com/Divohna/PackAttest/issues"
+  },
+  "type": "commonjs",
+  "files": [
+    "cli/",
+    "LICENSE",
+    "README.md"
+  ],
+  "bin": {
+    "pa": "./cli/index.js"
+  },
+  "scripts": {
+    "start": "node cli/index.js",
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "security",
+    "publishing",
+    "npm",
+    "artifact",
+    "release",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "prompts": "^2.4.2",
+    "tar-stream": "^3.1.7"
+  }
+}