Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,3 +98,12 @@ To recover a partially completed delivery:
The run summary records the source/tag/digest, output ref and main readback, and whether delivery advanced main or created a historical ref. A native installation proves client packaging only; authenticated read-only aggregate MCP access still requires the separate connection described above. Private docs and cloud deployment follow their own authorized workflows.

MIT licensed; see [LICENSE](LICENSE).


## Public skill archives

New canonical builds run the application's `cmd/skillpack` at the exact source commit. It calls the same `skills.PublicIndex` and `skills.PublicArchive` functions used by the runtime; this repository does not serialize a second ZIP format or author a second procedure. The native ZIP includes `public/index.json`, five deterministic ZIPs, and `public/source.json` with the same app and packager identities. Each per-skill ZIP contains exactly `SKILL.md` and `references/procedure.md`, unchanged, with raw-byte SHA-256 in the v0.2 index. Contributor skills and agent-specific native metadata do not enter those two-file archives.

The existing signed application release candidate authenticates the enclosing native package digest. The receiver accepts either the complete legacy package or the complete new public-artifact inventory, verifies regular files, bounded sizes, exact member content and digests, and preserves immutable tags and prior releases. Downloaded packages remain data: the receiver never executes the producer or package content. Marketing mirrors those exact verified bytes at the versioned URLs in the index. An empty website index means no capable release has been synchronized yet.

Activation requires publishing a reviewed packager revision and updating the application's immutable packager pin through the normal release workflow; these source changes do not publish or deploy that revision. Historical packages without the new public inventory stay valid.
67 changes: 65 additions & 2 deletions scripts/package.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@

import argparse
import hashlib
import io
import tarfile
import json
from pathlib import Path
import re
Expand All @@ -26,6 +28,57 @@
"plugin.json", ".claude-plugin/plugin.json", "source.json", "README.md"
}} | {"LICENSE", ".claude-plugin/marketplace.json", ".agents/plugins/marketplace.json"}

PUBLIC = {"public/index.json", "public/source.json"} | {f"public/{name}.zip" for name in SKILLS}

# Go emits this fixed UTC modification timestamp; older artifacts omit it.
PUBLIC_MODIFIED_EXTRA = bytes.fromhex("555405000100a6ce12")


def generated(root):
return GENERATED | ({f"plugins/{NAME}/{path}" for path in PUBLIC}
if (Path(root) / "plugins" / NAME / "public").exists() else set())


def produce_public(source_root, source_commit, output, version):
# Execute the canonical producer only during trusted build, never in the release receiver.
with tempfile.TemporaryDirectory(prefix="hitkeep-skillpack-source-") as directory:
source = Path(directory)
raw = git(source_root, "archive", source_commit, "--", "go.mod", "go.sum", "appurl", "skills", "cmd/skillpack")
with tarfile.open(fileobj=io.BytesIO(raw)) as archive:
archive.extractall(source, filter="data")
subprocess.run(["go", "run", "./cmd/skillpack", "--output", str(output),
"--base-url", f"https://hitkeep.com/skills/v{version}"], cwd=source, check=True)


def verify_public(plugin, version):
public = plugin / "public"
index = json.loads((public / "index.json").read_bytes())
source = json.loads((plugin / "source.json").read_bytes())
if (json.loads((public / "source.json").read_bytes()) !=
{key: source[key] for key in ("repository", "commit", "packager_commit")}):
raise ValueError("public artifact source identity mismatch")
if (set(index) != {"$schema", "skills"} or
index["$schema"] != "https://schemas.agentskills.io/discovery/0.2.0/schema.json" or
len(index["skills"]) != len(SKILLS) or {entry["name"] for entry in index["skills"]} != SKILLS):
raise ValueError("public artifact index inventory mismatch")
for entry in index["skills"]:
name = entry["name"]
raw = (public / (name + ".zip")).read_bytes()
if (set(entry) != {"name", "type", "description", "url", "digest"} or entry["type"] != "archive" or
not isinstance(entry["description"], str) or not entry["description"] or
entry["url"] != f"https://hitkeep.com/skills/v{version}/{name}.zip" or
entry["digest"] != "sha256:" + hashlib.sha256(raw).hexdigest()):
raise ValueError("public artifact index entry mismatch")
with zipfile.ZipFile(io.BytesIO(raw)) as archive:
if archive.namelist() != ["SKILL.md", "references/procedure.md"] or archive.comment:
raise ValueError("public artifact archive inventory mismatch")
for item in archive.infolist():
if ((item.external_attr >> 16) != 0o100644 or item.file_size > 1024 * 1024 or
item.compress_type != zipfile.ZIP_STORED or item.flag_bits != 8 or item.extra not in (b"", PUBLIC_MODIFIED_EXTRA) or item.comment or
item.date_time != (1980, 1, 1, 0, 0, 0) or
archive.read(item) != (plugin / "skills" / name / item.filename).read_bytes()):
raise ValueError("public artifact differs from canonical source")


def git(root, *args):
result = subprocess.run(["git", "-C", str(root), *args], capture_output=True)
Expand Down Expand Up @@ -74,7 +127,7 @@ def sync(source_root: Path, source_commit: str, version: str, root: Path = ROOT)
if root.is_symlink():
raise ValueError("symlink in output root")
root = root.resolve()
for relative in GENERATED:
for relative in GENERATED | {f"plugins/{NAME}/{path}" for path in PUBLIC}:
path = root / relative
if any(parent.is_symlink() for parent in (path, *path.parents)):
raise ValueError("symlink in output path")
Expand Down Expand Up @@ -104,8 +157,14 @@ def sync(source_root: Path, source_commit: str, version: str, root: Path = ROOT)
"packager_commit": packager_commit,
"sha256": {path: hashlib.sha256(data).hexdigest() for path, data in files.items()},
})
if (plugin / "public").exists():
shutil.rmtree(plugin / "public")
produce_public(source_root, source_commit, plugin / "public", version)
write_json(plugin / "public/source.json", {key: json.loads((plugin / "source.json").read_text())[key]
for key in ("repository", "commit", "packager_commit")})
verify_source(source_root, source_commit, stage)
for relative in sorted(GENERATED):
for relative in sorted(generated(stage)):
(root / relative).parent.mkdir(parents=True, exist_ok=True)
os.replace(stage / relative, root / relative)


Expand Down Expand Up @@ -155,6 +214,8 @@ def verify(root=ROOT):
if set(source["sha256"]) != expected:
raise ValueError("canonical source allowlist changed")
allowed = expected | {"plugin.json", ".claude-plugin/plugin.json", "source.json", "README.md"}
if (plugin / "public").exists():
allowed |= PUBLIC
allowed_dirs = {parent.as_posix() for relative in allowed for parent in Path(relative).parents if parent != Path(".")}
actual = set()
for path in plugin.rglob("*"):
Expand All @@ -173,6 +234,8 @@ def verify(root=ROOT):
for relative, digest in source["sha256"].items():
if hashlib.sha256((plugin / relative).read_bytes()).hexdigest() != digest:
raise ValueError(f"canonical content changed: {relative}")
if (plugin / "public").exists():
verify_public(plugin, version)
return version, sorted(actual)


Expand Down
20 changes: 13 additions & 7 deletions scripts/release_delivery.py
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,9 @@ def unpack(raw, root):
'plugin.json', '.claude-plugin/plugin.json', 'source.json', 'README.md'}}
with zipfile.ZipFile(io.BytesIO(raw)) as archive:
entries = archive.infolist()
if len(entries) != len(expected) or {item.filename for item in entries} != expected:
names = {item.filename for item in entries}
public = {f'{package.NAME}/{path}' for path in package.PUBLIC}
if names not in (expected, expected | public) or len(entries) != len(names):
raise ValueError('unsafe or incomplete package ZIP allowlist')
if any((item.external_attr >> 16) != 0o100644 or item.file_size > 1024 * 1024 for item in entries):
raise ValueError('non-regular, executable or oversized package ZIP content')
Expand Down Expand Up @@ -203,7 +205,7 @@ def prepare(tag, sha, digest, root, temp):
if package.verify(stage)[0] != tag[1:]:
raise ValueError('package version differs from release')
return dict(tag=tag, sha=sha, digest=digest, head=head, release=release,
candidate=mraw, tree={path: (stage / path).read_bytes() for path in package.GENERATED})
candidate=mraw, tree={path: (stage / path).read_bytes() for path in package.generated(stage)})


def matching_tree(root, commit, files):
Expand All @@ -213,18 +215,20 @@ def matching_tree(root, commit, files):
if entry:
metadata, path = entry.split(b'\t', 1)
entries[path.decode()] = tuple(metadata.decode().split()[:2])
if (set(files) != package.GENERATED or
entries != dict.fromkeys(package.GENERATED, ('100644', 'blob'))):
public = {f'plugins/{package.NAME}/{path}' for path in package.PUBLIC}
if (set(files) not in (package.GENERATED, package.GENERATED | public) or
set(entries) not in (package.GENERATED, package.GENERATED | public) or
any(mode != ('100644', 'blob') for mode in entries.values())):
raise ValueError('generated tree membership or regular non-executable modes differ from allowlist')
actual = {path: package.git(root, 'show', commit + ':' + path) for path in package.GENERATED}
actual = {path: package.git(root, 'show', commit + ':' + path) for path in entries}
with tempfile.TemporaryDirectory(prefix='hitkeep-assistant-tree-') as directory:
stage = Path(directory)
for relative, data in actual.items():
path = stage / relative
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(data)
package.verify(stage)
for path in package.GENERATED:
for path in set(actual) & set(files):
if path.endswith('/marketplace.json'):
current, expected = json.loads(actual[path]), json.loads(files[path])
if path == '.claude-plugin/marketplace.json':
Expand Down Expand Up @@ -283,6 +287,8 @@ def write(state, root, temp):
commit = head
if not matches_main:
command('git', '-C', str(gitroot), 'read-tree', head)
for path in sorted({f'plugins/{package.NAME}/{path}' for path in package.PUBLIC} - set(state['tree'])):
command('git', '-C', str(gitroot), 'update-index', '--force-remove', '--', path)
for path, data in sorted(state['tree'].items()):
blob = command('git', '-C', str(gitroot), 'hash-object', '-w', '--stdin', data=data).decode().strip()
command('git', '-C', str(gitroot), 'update-index', '--add', '--cacheinfo', '100644,' + blob + ',' + path)
Expand All @@ -293,7 +299,7 @@ def write(state, root, temp):
commit = command('git', '-C', str(gitroot), 'commit-tree', tree, '-p', head,
data=('chore: sync HitKeep ' + state['tag'] + '\n').encode(), env=env).decode().strip()
paths = command('git', '-C', str(gitroot), 'diff-tree', '--no-commit-id', '--name-only', '-r', commit).decode().splitlines()
if not paths or not set(paths) <= package.GENERATED:
if not paths or not set(paths) <= set(state['tree']) | {f'plugins/{package.NAME}/{path}' for path in package.PUBLIC}:
raise ValueError('generated diff changes non-allowlisted files')
push = ('git', '-C', str(gitroot), '-c', 'credential.helper=', '-c', 'credential.helper=!gh auth git-credential', 'push', 'origin')
if newest and not matches_main:
Expand Down
58 changes: 55 additions & 3 deletions tests/test_package.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@
import hashlib
import tempfile
import unittest
import io
import zipfile
from unittest.mock import patch

ROOT = Path(__file__).resolve().parents[1]
spec = importlib.util.spec_from_file_location("package", ROOT / "scripts/package.py")
Expand All @@ -21,6 +24,10 @@ def setUp(self):
for name in ("plugins", ".claude-plugin", ".agents"):
shutil.copytree(ROOT / name, self.root / name)
self.plugin = self.root / "plugins/hitkeep-analytics"
from test_release_delivery import fixture_public
mock = patch.object(package, "produce_public", side_effect=fixture_public)
mock.start()
self.addCleanup(mock.stop)

def source(self):
source = self.root / "upstream"
Expand All @@ -36,6 +43,49 @@ def git(*args):
git("-c", "user.name=Fixture", "-c", "user.email=fixture@example.invalid", "commit", "-qm", "fixture")
return source, git("rev-parse", "HEAD"), git

def test_public_archives_are_exact_deterministic_canonical_files(self):
source, commit, _ = self.source()
package.sync(source, commit, "2.16.0", self.root)
public = self.plugin / "public"
index = json.loads((public / "index.json").read_text())
self.assertEqual(index["$schema"], "https://schemas.agentskills.io/discovery/0.2.0/schema.json")
self.assertEqual({entry["name"] for entry in index["skills"]}, package.SKILLS)
self.assertEqual({p.name for p in public.iterdir()}, {"index.json", "source.json"} | {name + ".zip" for name in package.SKILLS})
self.assertEqual(json.loads((public / "source.json").read_text())["commit"], commit)
for entry in index["skills"]:
raw = (public / (entry["name"] + ".zip")).read_bytes()
self.assertEqual(entry["digest"], "sha256:" + hashlib.sha256(raw).hexdigest())
self.assertEqual(entry["url"], "https://hitkeep.com/skills/v2.16.0/" + entry["name"] + ".zip")
with zipfile.ZipFile(io.BytesIO(raw)) as archive:
self.assertEqual(archive.namelist(), ["SKILL.md", "references/procedure.md"])
for item in archive.infolist():
self.assertEqual(archive.read(item), (self.plugin / "skills" / entry["name"] / item.filename).read_bytes())
self.assertEqual(item.compress_type, zipfile.ZIP_STORED)
self.assertEqual(item.date_time, (1980, 1, 1, 0, 0, 0))
self.assertEqual(item.external_attr >> 16, 0o100644)
self.assertEqual(item.flag_bits, 8)
self.assertEqual(item.extra, b"")

(public / (index["skills"][0]["name"] + ".zip")).write_bytes(b"tampered")
with self.assertRaisesRegex(ValueError, "public artifact"):
package.verify(self.root)

def test_public_timestamp_metadata_accepts_only_legacy_or_fixed_go_epoch(self):
from test_release_delivery import fixture_public
source, commit, _ = self.source()
fixed_epoch = bytes.fromhex("555405000100a6ce12")
for extra, accepted in [(b"", True), (fixed_epoch, True), (fixed_epoch[:-1] + b"\x13", False), (b"\x00\x00\x00\x00", False)]:
with self.subTest(extra=extra):
def produce(*args):
return fixture_public(*args, timestamp_extra=extra)
with patch.object(package, "produce_public", side_effect=produce):
if accepted:
package.sync(source, commit, "2.16.0", self.root)
package.verify(self.root)
else:
with self.assertRaisesRegex(ValueError, "public artifact"):
package.sync(source, commit, "2.16.0", self.root)

def test_rehashed_tamper_fails_independent_source_verification(self):
source, commit, _ = self.source()
package.sync(source, commit, "2.15.1", self.root)
Expand All @@ -45,8 +95,8 @@ def test_rehashed_tamper_fails_independent_source_verification(self):
data = json.loads(inventory.read_text())
data["sha256"]["skills/hitkeep-analytics/SKILL.md"] = hashlib.sha256(path.read_bytes()).hexdigest()
inventory.write_text(json.dumps(data))
package.verify(self.root)
with self.assertRaisesRegex(ValueError, "upstream content"):
# Rehashing the authored file cannot authorize a different archive or canonical source.
with self.assertRaisesRegex(ValueError, "public artifact|upstream content"):
package.verify_source(source, commit, self.root)

def test_sync_uses_immutable_source_and_updates_versions(self):
Expand Down Expand Up @@ -113,7 +163,9 @@ def test_symlink_is_rejected(self):

def test_mismatched_version_is_rejected(self):
path = self.plugin / ".claude-plugin/plugin.json"
path.write_text(path.read_text().replace('"2.15.0"', '"0.0.0"'))
data = json.loads(path.read_text())
data["version"] = "0.0.0"
path.write_text(json.dumps(data))
with self.assertRaisesRegex(ValueError, "manifest mismatch"):
package.verify(self.root)

Expand Down
Loading
Loading