Skip to content

Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.

feat(release): SHA-256 release manifest tooling — release_sign.py + verify_release.py

Daniel144d52f0337e
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f61c3c7..383bb94 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -55,7 +55,9 @@ jobs:
python3 -m py_compile scripts/drift_history.py
python3 -m py_compile scripts/sync_flow.py
python3 -m py_compile scripts/release_report.py
- echo "All 32 scripts passed syntax check"
+ python3 -m py_compile scripts/release_sign.py
+ python3 -m py_compile scripts/verify_release.py
+ echo "All 34 scripts passed syntax check"
test:
name: Test suite (manifests + sync_flow)
diff --git a/scripts/release_sign.py b/scripts/release_sign.py
new file mode 100644
index 0000000..b23d534
--- /dev/null
+++ b/scripts/release_sign.py
@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""
+Generate a SHA-256 manifest of every git-tracked file in the repository.
+
+The manifest is published alongside each release tag (attached to the
+GitHub release artifacts) so users — and the install scripts — can
+verify the contents of a checkout against the maintainer's signed
+record.
+
+Usage
+=====
+
+Generate a manifest for the current working tree::
+
+ python scripts/release_sign.py > release-manifest.json
+
+Compare two manifests to find drift between releases::
+
+ python scripts/release_sign.py --compare old.json new.json
+
+Threat model
+============
+This manifest defends against tag rewrites and partial supply-chain
+tampering where an attacker can modify some repository files but not
+the published manifest. It does NOT defend against a fully compromised
+release (manifest + files both replaced by an attacker who controls
+the GitHub repo). For that level of trust the maintainer signs the
+manifest with a GPG key whose fingerprint is published out of band
+(SECURITY.md, the maintainer's site, etc.).
+
+Output schema
+=============
+::
+
+ {
+ "version": "v2.0.0", # plugin.json version
+ "tag": "v2.0.0", # git tag or "(uncommitted)"
+ "commit": "abc123…", # git HEAD
+ "generated_at": "2026-05-17T14:32:00Z",
+ "files": {
+ "scripts/url_safety.py": "<sha256 hex>",
+ …
+ },
+ "tree_sha256": "<sha256 hex of the sorted manifest itself>"
+ }
+
+The ``tree_sha256`` field lets a single hash be quoted in a release
+note or signed with GPG without needing to attach the whole JSON.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterable
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def _git(*args: str) -> str:
+ """Run ``git`` from the repo root and return stripped stdout."""
+ result = subprocess.run(
+ ["git", "-C", str(REPO_ROOT), *args],
+ check=True,
+ capture_output=True,
+ text=True,
+ )
+ return result.stdout.strip()
+
+
+def _git_or_none(*args: str) -> str | None:
+ try:
+ return _git(*args)
+ except subprocess.CalledProcessError:
+ return None
+
+
+def _tracked_files() -> list[str]:
+ """Return every file tracked by git (sorted, repo-relative)."""
+ out = _git("ls-files")
+ return sorted(line for line in out.splitlines() if line)
+
+
+def _sha256(path: Path) -> str:
+ h = hashlib.sha256()
+ with path.open("rb") as fh:
+ for chunk in iter(lambda: fh.read(65536), b""):
+ h.update(chunk)
+ return h.hexdigest()
+
+
+def _read_plugin_version() -> str:
+ manifest = REPO_ROOT / ".claude-plugin" / "plugin.json"
+ try:
+ with manifest.open() as fh:
+ return json.load(fh).get("version", "unknown")
+ except (OSError, json.JSONDecodeError):
+ return "unknown"
+
+
+def build_manifest(files: Iterable[str] | None = None) -> dict:
+ """Build the SHA-256 manifest for the current working tree."""
+ if files is None:
+ files = _tracked_files()
+
+ hashes: dict[str, str] = {}
+ for rel in files:
+ abs_path = REPO_ROOT / rel
+ if not abs_path.is_file():
+ # Submodule entries and broken symlinks fall through git
+ # ls-files; skip them but record the absence.
+ continue
+ hashes[rel] = _sha256(abs_path)
+
+ # Compute a hash-of-hashes so a single value identifies the whole
+ # manifest. Deterministic ordering: sorted file paths, one
+ # ``<sha> <path>\n`` line each (matching sha256sum's wire format).
+ tree_input = "".join(f"{sha} {path}\n" for path, sha in sorted(hashes.items()))
+ tree_sha = hashlib.sha256(tree_input.encode("utf-8")).hexdigest()
+
+ return {
+ "version": _read_plugin_version(),
+ "tag": _git_or_none("describe", "--tags", "--exact-match") or "(uncommitted)",
+ "commit": _git_or_none("rev-parse", "HEAD") or "(uncommitted)",
+ "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+ "files": hashes,
+ "tree_sha256": tree_sha,
+ }
+
+
+def compare(old: dict, new: dict) -> dict:
+ """Diff two manifests; return added / removed / changed files."""
+ old_files = old.get("files", {})
+ new_files = new.get("files", {})
+ return {
+ "added": sorted(set(new_files) - set(old_files)),
+ "removed": sorted(set(old_files) - set(new_files)),
+ "changed": sorted(
+ p for p in set(new_files) & set(old_files) if old_files[p] != new_files[p]
+ ),
+ "tree_sha256_old": old.get("tree_sha256"),
+ "tree_sha256_new": new.get("tree_sha256"),
+ }
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(
+ description="Generate or compare claude-seo release SHA-256 manifests."
+ )
+ parser.add_argument(
+ "--compare",
+ nargs=2,
+ metavar=("OLD", "NEW"),
+ help="Diff two manifests instead of generating a new one.",
+ )
+ parser.add_argument(
+ "--indent",
+ type=int,
+ default=2,
+ help="JSON indentation (default 2).",
+ )
+ args = parser.parse_args()
+
+ if args.compare:
+ with open(args.compare[0]) as fh:
+ old = json.load(fh)
+ with open(args.compare[1]) as fh:
+ new = json.load(fh)
+ json.dump(compare(old, new), sys.stdout, indent=args.indent)
+ sys.stdout.write("\n")
+ return 0
+
+ manifest = build_manifest()
+ json.dump(manifest, sys.stdout, indent=args.indent)
+ sys.stdout.write("\n")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/verify_release.py b/scripts/verify_release.py
new file mode 100644
index 0000000..061a934
--- /dev/null
+++ b/scripts/verify_release.py
@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""
+Verify the integrity of a claude-seo checkout against a release manifest.
+
+Usage
+=====
+
+After installing from a tag::
+
+ python scripts/verify_release.py path/to/release-manifest.json
+
+The script returns exit code 0 when every file in the manifest is
+present and matches the recorded SHA-256, and exit code 1 (with a
+human-readable report) on any mismatch, missing file, or extra file.
+
+This pairs with ``scripts/release_sign.py`` (used by the maintainer to
+generate the manifest at release time) and the GitHub release
+attachment workflow that publishes the manifest alongside each tag.
+
+Threat model
+============
+See SECURITY.md "Tampered install" section. Verification catches tag
+force-pushes and partial supply-chain tampering, but does NOT defend
+against an attacker who can replace both the source files and the
+published manifest. For that level of trust, the manifest must be
+signed by the maintainer's GPG key whose fingerprint is published
+out of band.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def _sha256(path: Path) -> str:
+ h = hashlib.sha256()
+ with path.open("rb") as fh:
+ for chunk in iter(lambda: fh.read(65536), b""):
+ h.update(chunk)
+ return h.hexdigest()
+
+
+def verify(manifest_path: Path, root: Path = REPO_ROOT) -> dict:
+ """Compare a manifest against the working tree at ``root``.
+
+ Returns a dict with:
+ ok : True iff every file in manifest matches.
+ manifest : the manifest payload (for the caller to display
+ version/tag/commit context).
+ mismatched : paths whose SHA-256 differs.
+ missing : paths in manifest but absent from disk.
+ extra : paths on disk (and git-tracked) but not in
+ manifest. Empty unless caller passes a tracked
+ file list; default behaviour leaves this empty.
+ """
+ with manifest_path.open() as fh:
+ manifest = json.load(fh)
+
+ expected = manifest.get("files", {})
+ mismatched: list[dict] = []
+ missing: list[str] = []
+
+ for rel, expected_sha in sorted(expected.items()):
+ abs_path = root / rel
+ if not abs_path.is_file():
+ missing.append(rel)
+ continue
+ actual_sha = _sha256(abs_path)
+ if actual_sha != expected_sha:
+ mismatched.append(
+ {"path": rel, "expected": expected_sha, "actual": actual_sha}
+ )
+
+ return {
+ "ok": not (mismatched or missing),
+ "manifest": {
+ "version": manifest.get("version"),
+ "tag": manifest.get("tag"),
+ "commit": manifest.get("commit"),
+ "generated_at": manifest.get("generated_at"),
+ "tree_sha256": manifest.get("tree_sha256"),
+ },
+ "checked": len(expected),
+ "mismatched": mismatched,
+ "missing": missing,
+ }
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(
+ description="Verify a claude-seo checkout against a release manifest."
+ )
+ parser.add_argument(
+ "manifest", type=Path, help="Path to release-manifest.json."
+ )
+ parser.add_argument(
+ "--root",
+ type=Path,
+ default=REPO_ROOT,
+ help="Repository root to verify (default: this checkout).",
+ )
+ parser.add_argument(
+ "--json",
+ action="store_true",
+ help="Emit a JSON report instead of human-readable text.",
+ )
+ args = parser.parse_args()
+
+ if not args.manifest.is_file():
+ print(f"Error: manifest not found: {args.manifest}", file=sys.stderr)
+ return 2
+
+ result = verify(args.manifest, args.root)
+
+ if args.json:
+ json.dump(result, sys.stdout, indent=2)
+ sys.stdout.write("\n")
+ else:
+ m = result["manifest"]
+ status = "OK" if result["ok"] else "FAIL"
+ print(f"Verification: {status}")
+ print(f" Manifest version: {m['version']} tag: {m['tag']}")
+ print(f" Manifest commit: {m['commit']}")
+ print(f" Generated at: {m['generated_at']}")
+ print(f" Tree SHA-256: {m['tree_sha256']}")
+ print(f" Files checked: {result['checked']}")
+ if result["mismatched"]:
+ print(f"\n Mismatched ({len(result['mismatched'])}):")
+ for row in result["mismatched"]:
+ print(f" - {row['path']}")
+ print(f" expected: {row['expected']}")
+ print(f" actual: {row['actual']}")
+ if result["missing"]:
+ print(f"\n Missing ({len(result['missing'])}):")
+ for path in result["missing"]:
+ print(f" - {path}")
+
+ return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())