diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 3a77c0c..6144095 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -9,7 +9,24 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 - - run: python3 scripts/package.py + - name: Read canonical app commit + id: source + run: | + python3 - <<'PYCODE' >> "$GITHUB_OUTPUT" + import json, re + sha = json.load(open("plugins/hitkeep-analytics/source.json"))["commit"] + assert re.fullmatch(r"[0-9a-f]{40}", sha) + print("sha=" + sha) + PYCODE + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + with: + repository: HitKeep/hitkeep + ref: ${{ steps.source.outputs.sha }} + path: .canonical-app + persist-credentials: false + - run: python3 scripts/package.py --verify-source .canonical-app --source-sha "${{ steps.source.outputs.sha }}" - run: python3 -m unittest discover -s tests - run: python3 scripts/package.py --output /tmp/hitkeep-analytics.zip + - run: python3 scripts/package.py --output /tmp/hitkeep-analytics-again.zip + - run: cmp /tmp/hitkeep-analytics.zip /tmp/hitkeep-analytics-again.zip - run: unzip -t /tmp/hitkeep-analytics.zip diff --git a/.github/workflows/sync-hitkeep-release.yml b/.github/workflows/sync-hitkeep-release.yml new file mode 100644 index 0000000..3d14d96 --- /dev/null +++ b/.github/workflows/sync-hitkeep-release.yml @@ -0,0 +1,65 @@ +name: Sync verified HitKeep release +on: + workflow_dispatch: + inputs: + release_tag: + description: Published stable app tag (vX.Y.Z) + required: true + type: string + source_sha: + description: Exact app source commit + required: true + type: string + package_sha256: + description: Attested assistant ZIP SHA-256 + required: true + type: string + +permissions: + contents: read + +concurrency: + group: sync-hitkeep-release + cancel-in-progress: false + queue: max + +env: + RELEASE_TAG: ${{ inputs.release_tag }} + SOURCE_SHA: ${{ inputs.source_sha }} + PACKAGE_SHA256: ${{ inputs.package_sha256 }} + GIT_TERMINAL_PROMPT: '0' + +jobs: + verify: + if: github.repository == 'HitKeep/hitkeep-assistant-plugins' && github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + permissions: + contents: read + attestations: read + steps: + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + with: + ref: ${{ github.sha }} + fetch-depth: 0 + persist-credentials: false + - name: Verify public candidate, producer attempt and canonical package + env: + GH_TOKEN: ${{ github.token }} + run: python3 scripts/release_delivery.py verify --release-tag "$RELEASE_TAG" --source-sha "$SOURCE_SHA" --package-sha256 "$PACKAGE_SHA256" + + publish: + needs: verify + runs-on: ubuntu-latest + permissions: + contents: write + attestations: read + steps: + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + with: + ref: ${{ github.sha }} + fetch-depth: 0 + persist-credentials: false + - name: Reverify, fast-forward generated files and publish immutable native ref + env: + GH_TOKEN: ${{ github.token }} + run: python3 scripts/release_delivery.py publish --release-tag "$RELEASE_TAG" --source-sha "$SOURCE_SHA" --package-sha256 "$PACKAGE_SHA256" diff --git a/README.md b/README.md index 50cc7b4..83dd532 100644 --- a/README.md +++ b/README.md @@ -29,15 +29,15 @@ codex plugin marketplace add HitKeep/hitkeep-assistant-plugins codex plugin add hitkeep-analytics@hitkeep ``` -Start a new session, then invoke `$hitkeep-analytics` or another bundled skill. To pin the marketplace to this release, add it with `--ref v2.15.0`. +Start a new session, then invoke `$hitkeep-analytics` or another bundled skill. To pin the marketplace to a published release, add it with `--ref vX.Y.Z` (for example `--ref v2.15.0` for the existing historical release). ## ChatGPT Where native archive upload is available: -1. Download [`hitkeep-analytics-2.15.0.zip`](https://github.com/HitKeep/hitkeep-assistant-plugins/releases/download/v2.15.0/hitkeep-analytics-2.15.0.zip) from the [release](https://github.com/HitKeep/hitkeep-assistant-plugins/releases/tag/v2.15.0). +1. Select a [published app release](https://github.com/HitKeep/hitkeep/releases) and download its `hitkeep-analytics-X.Y.Z.zip`. The corresponding [assistant release](https://github.com/HitKeep/hitkeep-assistant-plugins/releases) links the same verified ZIP. The existing [2.15.0 archive](https://github.com/HitKeep/hitkeep-assistant-plugins/releases/download/v2.15.0/hitkeep-analytics-2.15.0.zip) remains available in its original location. 2. Open **Settings → Plugins → Browse catalog → Add → Upload plugin archive** and select the ZIP, then select **Add plugin**. -3. Review **HitKeep Analytics**, version **2.15.0**, and its five skills, then select **Install plugin**. +3. Review **HitKeep Analytics**, the selected version, and its five skills, then select **Install plugin**. 4. Use **Try in chat** to start with the installed plugin. This route was verified in signed-in ChatGPT web: the native plugin detail displayed version `2.15.0`, read capability, all five skills, and the installed **Manage** and **Try in chat** actions. It creates a private install, separate from public directory publication. @@ -58,7 +58,7 @@ Follow the [HitKeep MCP guide](https://hitkeep.com/guides/integrations/mcp/) for The MCP surface is read-only and aggregate-only. These skills cannot configure sites, change goals, export raw hits, manage tokens, or perform billing or administration. Skill installation never expands the authenticated user's authority. -Package version `2.15.0` identifies this skill distribution. OAuth availability depends on the deployed HitKeep version and configuration; publishing this package does not release or deploy the HitKeep application. +The package version identifies the skill distribution and its matching immutable Git tag. OAuth availability depends on the deployed HitKeep version and configuration; publishing this package does not release or deploy the HitKeep application. ## Verify and package @@ -72,6 +72,29 @@ python3 scripts/package.py --output dist/hitkeep-analytics-2.15.0.zip The verifier checks both native catalogs, matching manifest identities and versions, the exact skill allowlist, and every canonical file hash. The ZIP contains one plugin directory with both native manifests and the same skills; it has deterministic file order, timestamps, and permissions. -For an update, export only the five skill directories and `LICENSE` from the next reviewed commit of `HitKeep/hitkeep`, update their hashes and commit in `source.json`, and update both manifest versions and the Claude catalog version together. Keep `skills/` in the application repository canonical; changes to analytics instructions belong there first. Do not publish test fixtures or add credentials to a package. +For an update, check out an immutable reviewed app commit, then use the existing packager: + +```sh +python3 scripts/package.py --sync-from ../hitkeep --source-sha FULL_APP_COMMIT --version X.Y.Z +python3 scripts/package.py --verify-source ../hitkeep --source-sha FULL_APP_COMMIT +``` + +Sync reads committed Git objects, stages and verifies all generated files before replacement, and records the app and packager commits in `source.json`. It copies exactly the five product skills' `SKILL.md`, `references/procedure.md`, and `agents/openai.yaml` files plus `LICENSE`; contributor `.agents/skills/` content never enters the package. Both native manifests and the Claude catalog advance together; the OpenAI catalog retains its native schema. CI independently retrieves the recorded app commit and compares bytes, so rewriting a local inventory cannot authorize changed skills. Keep application `skills/` canonical; analytics instruction changes belong there first. Ask AI continues to consume only the product procedure references. + +## Release delivery and recovery + +The application release builds the assistant ZIP once from an exact app commit using an immutable reviewed packager commit and records its digest in the attested release candidate. This repository receives exactly `release_tag`, `source_sha`, and `package_sha256` through `sync-hitkeep-release.yml` on main. GitHub authorizes the native dispatch; the receiver independently verifies the public stable app release, unchanged tag, candidate signature, exact producer run and attempt, mandatory checks, package digest, native manifests, and upstream skill bytes. Downloaded files are treated as data and never executed. + +A read-only verification job must pass before the separate job receives its repository-scoped `GITHUB_TOKEN` write permission. The writer verifies again, rechecks current main and repository policy, and fast-forwards only the generated plugin, catalogs, and license. The workflow currently requires unprotected main and no repository or inherited rulesets; a policy change stops delivery for maintainer review. It never bypasses protection or force-pushes. + +Each version has an immutable native installation ref `vX.Y.Z` and an assistant release linking the app ZIP. The assistant release uploads no second archive. Newer versions advance main and the native catalogs; backports receive only their historical tag and linked release, preserving newer catalogs and latest. Existing `v2.15.0` assets and refs remain unchanged. + +To recover a partially completed delivery: + +1. Open the failed native receiver run and rerun its failed jobs. The receiver revalidates inputs and current remote state, then resumes after a completed main update, tag, or release. Matching retries write nothing; conflicting immutable content stops for investigation. A canceled or failed caller watch does not cancel or prove failure of the receiver: inspect the exact receiver run first. +2. For a core app channel failure, use the app's native publication workflow with its original candidate run, attempt, and channel. Native reruns include dependent leaf jobs; an expired candidate requires a newly validated candidate. A successful assistant or other leaf need not be rolled back because another channel failed. +3. Resolve an explicit authentication or protection error before retrying. The receiver does not widen permissions, replace tags/assets, or downgrade a channel to make a retry pass. If main changed during a write race, the non-forced push fails; a native retry reads and validates the new head. + +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). diff --git a/scripts/package.py b/scripts/package.py index dc5d3f3..0107f46 100644 --- a/scripts/package.py +++ b/scripts/package.py @@ -7,6 +7,10 @@ from pathlib import Path import re import zipfile +import os +import shutil +import subprocess +import tempfile ROOT = Path(__file__).resolve().parents[1] NAME = "hitkeep-analytics" @@ -15,11 +19,104 @@ "hitkeep-ecommerce-analyst", "hitkeep-tracking-verifier", } +CANONICAL = {f"skills/{name}/{part}" for name in SKILLS for part in ( + "SKILL.md", "references/procedure.md", "agents/openai.yaml" +)} | {"LICENSE"} +GENERATED = {f"plugins/{NAME}/{path}" for path in CANONICAL | { + "plugin.json", ".claude-plugin/plugin.json", "source.json", "README.md" +}} | {"LICENSE", ".claude-plugin/marketplace.json", ".agents/plugins/marketplace.json"} + + +def git(root, *args): + result = subprocess.run(["git", "-C", str(root), *args], capture_output=True) + if result.returncode: + raise ValueError("cannot read immutable Git source") + return result.stdout + + +def canonical(source_root, source_commit): + if not re.fullmatch(r"[0-9a-f]{40}", source_commit): + raise ValueError("source SHA must be a full immutable commit") + if git(source_root, "rev-parse", source_commit + "^{commit}").decode().strip() != source_commit: + raise ValueError("source SHA is not a commit") + result = {} + for relative in sorted(CANONICAL): + entry = git(source_root, "ls-tree", source_commit, "--", relative).decode().strip() + if not entry.startswith("100644 blob ") or entry.split("\t")[-1] != relative: + raise ValueError(f"canonical source must be a regular non-executable file: {relative}") + result[relative] = git(source_root, "show", f"{source_commit}:{relative}") + return result + + +def verify_source(source_root: Path, source_commit: str, root: Path = ROOT) -> None: + verify(root) + plugin = root / "plugins" / NAME + inventory = json.loads((plugin / "source.json").read_text()) + if inventory["commit"] != source_commit: + raise ValueError("upstream source commit mismatch") + if "packager_commit" in inventory and not re.fullmatch(r"[0-9a-f]{40}", inventory["packager_commit"]): + raise ValueError("packager commit must be immutable") + for relative, data in canonical(source_root, source_commit).items(): + if (plugin / relative).read_bytes() != data: + raise ValueError(f"upstream content mismatch: {relative}") + if (root / "LICENSE").read_bytes() != (plugin / "LICENSE").read_bytes(): + raise ValueError("upstream content mismatch: root LICENSE") + + +def write_json(path, value): + path.write_text(json.dumps(value, indent=2) + "\n") + + +def sync(source_root: Path, source_commit: str, version: str, root: Path = ROOT) -> None: + if not re.fullmatch(r"(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)", version): + raise ValueError("invalid release version") + root = Path(root) + if root.is_symlink(): + raise ValueError("symlink in output root") + root = root.resolve() + for relative in GENERATED: + path = root / relative + if any(parent.is_symlink() for parent in (path, *path.parents)): + raise ValueError("symlink in output path") + verify(root) + files = canonical(source_root, source_commit) + packager_commit = git(ROOT, "rev-parse", "HEAD").decode().strip() + # Stage and verify the entire generated tree before replacing any output. + with tempfile.TemporaryDirectory(prefix=".hitkeep-package-", dir=root.parent) as temp: + stage = Path(temp) + for name in ("plugins", ".claude-plugin", ".agents"): + shutil.copytree(root / name, stage / name) + plugin = stage / "plugins" / NAME + for relative, data in files.items(): + (plugin / relative).write_bytes(data) + (stage / "LICENSE").write_bytes(files["LICENSE"]) + for relative in ("plugin.json", ".claude-plugin/plugin.json"): + path = plugin / relative + manifest = json.loads(path.read_text()) + manifest["version"] = version + write_json(path, manifest) + path = stage / ".claude-plugin/marketplace.json" + catalog = json.loads(path.read_text()) + catalog["plugins"][0]["version"] = version + write_json(path, catalog) + write_json(plugin / "source.json", { + "repository": "https://github.com/HitKeep/hitkeep", "commit": source_commit, + "packager_commit": packager_commit, + "sha256": {path: hashlib.sha256(data).hexdigest() for path, data in files.items()}, + }) + verify_source(source_root, source_commit, stage) + for relative in sorted(GENERATED): + os.replace(stage / relative, root / relative) + def verify(root=ROOT): plugin = root / "plugins" / NAME + if plugin.is_symlink(): + raise ValueError("symlink in package root") portable = json.loads((plugin / "plugin.json").read_text()) claude = json.loads((plugin / ".claude-plugin/plugin.json").read_text()) + if set(portable) != {"$schema", "name", "version", "description", "author", "license", "extensions"} or set(claude) != {"name", "version", "description", "author", "license", "skills"}: + raise ValueError("unexpected native manifest fields or hooks") version = portable["version"] if not re.fullmatch(r"\d+\.\d+\.\d+", version): raise ValueError("invalid release version") @@ -54,17 +151,18 @@ def verify(root=ROOT): raise ValueError("unexpected canonical source") if not re.fullmatch(r"[0-9a-f]{40}", source["commit"]): raise ValueError("canonical commit must be immutable") - expected = {f"skills/{name}/{part}" for name in SKILLS for part in ( - "SKILL.md", "references/procedure.md", "agents/openai.yaml" - )} | {"LICENSE"} + expected = CANONICAL if set(source["sha256"]) != expected: raise ValueError("canonical source allowlist changed") allowed = expected | {"plugin.json", ".claude-plugin/plugin.json", "source.json", "README.md"} + 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("*"): if path.is_symlink(): raise ValueError(f"symlink in package: {path}") if path.is_dir(): + if path.relative_to(plugin).as_posix() not in allowed_dirs: + raise ValueError("package directory allowlist mismatch") continue relative = path.relative_to(plugin).as_posix() if not path.is_file() or path.stat().st_mode & 0o111: @@ -95,6 +193,23 @@ def package(output, root=ROOT): if __name__ == "__main__": parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--output", type=Path, help="write the verified plugin ZIP") + modes = parser.add_mutually_exclusive_group() + modes.add_argument("--sync-from", type=Path) + modes.add_argument("--verify-source", type=Path) + parser.add_argument("--source-sha") + parser.add_argument("--version") args = parser.parse_args() + if (args.sync_from or args.verify_source) and not args.source_sha: + parser.error("source mode requires --source-sha") + if args.sync_from and not args.version: + parser.error("--sync-from requires --version") + if args.version and not args.sync_from: + parser.error("--version requires --sync-from") + if args.source_sha and not (args.sync_from or args.verify_source): + parser.error("--source-sha requires a source mode") + if args.sync_from: + sync(args.sync_from, args.source_sha, args.version, ROOT) + if args.verify_source: + verify_source(args.verify_source, args.source_sha, ROOT) version = package(args.output) if args.output else verify()[0] print(f"Verified {NAME} {version}: five canonical skills, two native manifests") diff --git a/scripts/release_delivery.py b/scripts/release_delivery.py new file mode 100644 index 0000000..32aeead --- /dev/null +++ b/scripts/release_delivery.py @@ -0,0 +1,357 @@ +#!/usr/bin/env python3 +"""Receive one attested app release using reviewed assistant main code.""" +import argparse +import hashlib +import io +import json +import os +from pathlib import Path +import re +import shutil +import subprocess +import tempfile +import zipfile + +import package + +APP = 'HitKeep/hitkeep' +REPO = 'HitKeep/hitkeep-assistant-plugins' +PRODUCER = '.github/workflows/release.yml' +WORKFLOW = '.github/workflows/sync-hitkeep-release.yml' +CHECKS = ('native', 'archives', 'tracker', 'chart', 'docker', 'compose', 'helm', 'docs', + 'assistant-package', 'source-archive') +SHA = re.compile(r'[0-9a-f]{40}') +DIGEST = re.compile(r'[0-9a-f]{64}') + + +def version(tag): + if not re.fullmatch(r'v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)', tag): + raise ValueError('expected vX.Y.Z stable release tag') + return tuple(map(int, tag[1:].split('.'))) + + +def command(*args, data=None, optional=False, env=None): + result = subprocess.run(args, input=data, stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=env) + if result.returncode: + if optional and b'(HTTP 404)' in result.stderr: + return None + raise ValueError('release transport or Git operation failed; inspect native run permissions/state') + return result.stdout + + +def api(repo, path, optional=False): + raw = command('gh', 'api', f'repos/{repo}/{path}', optional=optional) + return json.loads(raw) if raw is not None else None + + +def asset(release, name): + matches = [entry for entry in release['assets'] if entry['name'] == name] + if len(matches) != 1: + raise ValueError('missing or duplicate app release asset: ' + name) + return matches[0] + + +def download(entry): + return command('gh', 'api', f"repos/{APP}/releases/assets/{entry['id']}", + '-H', 'Accept: application/octet-stream') + + +def tag_commit(repo, tag): + ref = api(repo, 'git/ref/tags/' + tag, optional=True) + if ref is None: + return None + obj = ref['object'] + if obj['type'] == 'tag': + obj = api(repo, 'git/tags/' + obj['sha'])['object'] + if obj['type'] != 'commit' or not SHA.fullmatch(obj['sha']): + raise ValueError('release tag does not identify an immutable commit') + return obj['sha'] + + +def validate_dispatch(env): + expected = dict(GITHUB_REPOSITORY=REPO, GITHUB_REF='refs/heads/main', + GITHUB_EVENT_NAME='workflow_dispatch', + GITHUB_WORKFLOW_REF=REPO + '/' + WORKFLOW + '@refs/heads/main') + if any(env.get(key) != value for key, value in expected.items()): + raise ValueError('unauthorized receiver actor or workflow ref') + + +def validate_policy(branch, rules): + # This receiver is approved only for the observed unprotected, ruleset-free repository. + if branch.get('protected') is not False or rules != []: + raise ValueError('repository protection policy changed; maintainer action required') + + +def validate_release(repository, release, actual_sha, tag, sha): + if (repository.get('private') is not False or release.get('tag_name') != tag or + release.get('draft') is not False or release.get('prerelease') is not False or actual_sha != sha): + raise ValueError('app release must be public, stable and bound to the unchanged source tag') + + +def validate_candidate(m, run, attestations, tag, sha, digest): + version(tag) + if not SHA.fullmatch(sha) or not DIGEST.fullmatch(digest): + raise ValueError('invalid source identity or package digest') + if (m.get('schema_version') != 1 or m.get('tag') != tag or m.get('source_commit') != sha or + not SHA.fullmatch(m.get('producer_workflow_sha', '')) or + any(type(m.get(key)) is not int or m[key] < 1 for key in ('producer_run_id', 'producer_run_attempt')) or + m.get('checks') != dict.fromkeys(CHECKS, 'success')): + raise ValueError('invalid or incomplete candidate identity/checks') + items = m['artifacts'] + names = [item['name'] for item in items] + if len(names) != len(set(names)): + raise ValueError('duplicate candidate asset') + matches = [item for item in items if item['name'] == 'hitkeep-analytics-' + tag[1:] + '.zip'] + if matches != [dict(name='hitkeep-analytics-' + tag[1:] + '.zip', type='assistant-package', sha256=digest)]: + raise ValueError('candidate package identity or digest mismatch') + if (run.get('id') != m['producer_run_id'] or run.get('run_attempt') != m['producer_run_attempt'] or + run.get('head_sha') != m['producer_workflow_sha'] or run.get('path') != PRODUCER or + run.get('head_branch') != 'main' or run.get('event') not in ('push', 'workflow_dispatch') or + run.get('status') != 'completed' or run.get('conclusion') != 'success' or + run.get('repository', {}).get('full_name') != APP or run.get('head_repository', {}).get('full_name') != APP): + raise ValueError('untrusted or unsuccessful producer attempt') + expected = dict(sourceRepositoryURI='https://github.com/' + APP, + sourceRepositoryDigest=m['producer_workflow_sha'], sourceRepositoryRef='refs/heads/main', + buildSignerURI='https://github.com/' + APP + '/' + PRODUCER + '@refs/heads/main', + runInvocationURI=f"https://github.com/{APP}/actions/runs/{m['producer_run_id']}/attempts/{m['producer_run_attempt']}") + certificates = [item['verificationResult']['signature']['certificate'] for item in attestations] + if not any(all(cert.get(key) == value for key, value in expected.items()) for cert in certificates): + raise ValueError('attestation signer, source or producer attempt mismatch') + + +def unpack(raw, root): + expected = {f'{package.NAME}/{path}' for path in package.CANONICAL | { + '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: + 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') + files = {item.filename: archive.read(item) for item in entries} + # Every name and member is checked in memory before even creating the output directory. + root.mkdir() + for relative, data in files.items(): + path = root / 'plugins' / relative + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(data) + + +def policy(): + branch = api(REPO, 'branches/main') + validate_policy(branch, api(REPO, 'rulesets?includes_parents=true')) + return branch['commit']['sha'] + + +def prepare(tag, sha, digest, root, temp): + version(tag) + if not SHA.fullmatch(sha) or not DIGEST.fullmatch(digest): + raise ValueError('invalid source identity or package digest') + # workflow_dispatch authorization belongs to GitHub; inputs cannot select code or write paths. + validate_dispatch(os.environ) + repository = api(APP, '') + release = api(APP, 'releases/tags/' + tag) + validate_release(repository, release, tag_commit(APP, tag), tag, sha) + head = policy() + command('git', '-C', str(root), 'fetch', '-q', 'origin', 'refs/heads/main') + mraw = download(asset(release, 'release-candidate.json')) + manifest = json.loads(mraw) + producer_sha = manifest.get('producer_workflow_sha', '') + if not SHA.fullmatch(producer_sha): + raise ValueError('invalid producer workflow SHA') + mpath = temp / 'release-candidate.json' + mpath.write_bytes(mraw) + attestations = json.loads(command('gh', 'attestation', 'verify', str(mpath), '--repo', APP, + '--signer-workflow', APP + '/' + PRODUCER, '--source-digest', producer_sha, + '--source-ref', 'refs/heads/main', '--deny-self-hosted-runners', '--format', 'json')) + for key in ('producer_run_id', 'producer_run_attempt'): + if type(manifest.get(key)) is not int or manifest[key] < 1: + raise ValueError('invalid producer run identity') + run = api(APP, f"actions/runs/{manifest['producer_run_id']}/attempts/{manifest['producer_run_attempt']}") + validate_candidate(manifest, run, attestations, tag, sha, digest) + for commit in {sha, producer_sha}: + if api(APP, f'compare/{commit}...main')['status'] not in ('ahead', 'identical'): + raise ValueError('app source or producer is outside main history') + raw = download(asset(release, 'hitkeep-analytics-' + tag[1:] + '.zip')) + if hashlib.sha256(raw).hexdigest() != digest: + raise ValueError('downloaded app package digest mismatch') + stage = temp / 'generated' + unpack(raw, stage) + for name in ('.claude-plugin', '.agents'): + shutil.copytree(root / name, stage / name) + plugin = stage / 'plugins' / package.NAME + (stage / 'LICENSE').write_bytes((plugin / 'LICENSE').read_bytes()) + catalog = stage / '.claude-plugin/marketplace.json' + data = json.loads(catalog.read_text()) + data['plugins'][0]['version'] = tag[1:] + package.write_json(catalog, data) + for name in ('plugin.json', '.claude-plugin/plugin.json'): + expected = json.loads((root / 'plugins' / package.NAME / name).read_text()) + expected['version'] = tag[1:] + if json.loads((plugin / name).read_text()) != expected: + raise ValueError('package native manifest changed beyond version') + if (plugin / 'README.md').read_bytes() != (root / 'plugins' / package.NAME / 'README.md').read_bytes(): + raise ValueError('package README differs from reviewed template') + inventory = json.loads((plugin / 'source.json').read_text()) + if set(inventory) != {'repository', 'commit', 'packager_commit', 'sha256'} or not SHA.fullmatch(inventory.get('packager_commit', '')): + raise ValueError('missing or unexpected package provenance') + command('git', '-C', str(root), 'merge-base', '--is-ancestor', inventory['packager_commit'], head) + app = temp / 'app' + command('git', 'init', '-q', str(app)) + command('git', '-C', str(app), 'fetch', '-q', '--depth=1', 'https://github.com/' + APP + '.git', sha) + package.verify_source(app, sha, stage) + 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}) + + +def matching_tree(root, commit, files): + roots = ('plugins/' + package.NAME, '.claude-plugin', '.agents/plugins', 'LICENSE') + entries = {} + for entry in package.git(root, 'ls-tree', '-r', '-z', commit, '--', *roots).split(b'\0'): + 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'))): + 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} + 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: + if path.endswith('/marketplace.json'): + current, expected = json.loads(actual[path]), json.loads(files[path]) + if path == '.claude-plugin/marketplace.json': + # Main may hold another version; all other catalog content stays reviewed. + current['plugins'][0]['version'] = expected['plugins'][0]['version'] + if current != expected: + raise ValueError('generated native catalog content differs from reviewed template') + return actual == files + + +def guard(state): + if policy() != state['head']: + raise ValueError('assistant main changed; rerun the native workflow to revalidate') + if api(REPO, 'releases/latest')['tag_name'] != state['latest_tag']: + raise ValueError('assistant latest changed; rerun the native workflow to revalidate') + release = api(APP, 'releases/tags/' + state['tag']) + validate_release(api(APP, ''), release, tag_commit(APP, state['tag']), state['tag'], state['sha']) + if (download(asset(release, 'release-candidate.json')) != state['candidate'] or + hashlib.sha256(download(asset(release, 'hitkeep-analytics-' + state['tag'][1:] + '.zip'))).hexdigest() != state['digest']): + raise ValueError('app release assets changed after validation') + + +def release_notes(state): + return ('Canonical skills for HitKeep ' + state['tag'] + '.\n\n' + + '[Download the verified app ZIP](https://github.com/' + APP + '/releases/download/' + state['tag'] + + '/hitkeep-analytics-' + state['tag'][1:] + '.zip)\n\n' + + 'App source: `' + state['sha'] + '`\nPackage SHA-256: `' + state['digest'] + '`\n') + + +def validate_assistant_release(release, state): + if release is not None and (release['draft'] or release['prerelease'] or release['tag_name'] != state['tag'] or + release['body'].replace('\r\n', '\n') != release_notes(state) or release['assets']): + raise ValueError('immutable assistant release link/content conflict') + + +def write(state, root, temp): + gitroot = temp / 'receiver' + command('git', 'clone', '-q', '--no-hardlinks', '--no-checkout', str(root), str(gitroot)) + command('git', '-C', str(gitroot), 'remote', 'set-url', 'origin', 'https://github.com/' + REPO + '.git') + command('git', '-C', str(gitroot), 'fetch', '-q', 'origin', 'refs/heads/main') + head = state['head'] + current = json.loads(package.git(gitroot, 'show', head + ':plugins/' + package.NAME + '/plugin.json'))['version'] + latest = api(REPO, 'releases/latest') + state['latest_tag'] = latest['tag_name'] + newest = version(state['tag']) >= max(version('v' + current), version(latest['tag_name'])) + release = api(REPO, 'releases/tags/' + state['tag'], optional=True) + validate_assistant_release(release, state) + existing = tag_commit(REPO, state['tag']) + if existing: + command('git', '-C', str(gitroot), 'fetch', '-q', 'origin', 'refs/tags/' + state['tag']) + if not matching_tree(gitroot, existing, state['tree']): + raise ValueError('immutable assistant tag content/provenance conflict') + matches_main = matching_tree(gitroot, head, state['tree']) + if version(state['tag']) == version('v' + current) and not matches_main: + raise ValueError('same assistant main version has conflicting content/provenance') + commit = head + if not matches_main: + command('git', '-C', str(gitroot), 'read-tree', head) + 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) + tree = command('git', '-C', str(gitroot), 'write-tree').decode().strip() + env = dict(os.environ, GIT_AUTHOR_NAME='HitKeep Release', GIT_COMMITTER_NAME='HitKeep Release', + GIT_AUTHOR_EMAIL='41898282+github-actions[bot]@users.noreply.github.com', + GIT_COMMITTER_EMAIL='41898282+github-actions[bot]@users.noreply.github.com') + 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: + 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: + guard(state) + command(*push, commit + ':refs/heads/main') + state['head'] = commit + if policy() != commit: + raise ValueError('assistant main readback mismatch') + if existing is None: + guard(state) + command(*push, commit + ':refs/tags/' + state['tag']) + existing = commit + if tag_commit(REPO, state['tag']) != existing: + raise ValueError('immutable assistant tag readback mismatch') + state['output_sha'] = existing + if release is None: + guard(state) + body = temp / 'release-notes.md' + body.write_text(release_notes(state)) + command('gh', 'release', 'create', state['tag'], '--repo', REPO, '--verify-tag', '--title', state['tag'], + '--notes-file', str(body), '--latest=' + str(newest).lower()) + release = api(REPO, 'releases/tags/' + state['tag']) + if newest: + state['latest_tag'] = state['tag'] + validate_assistant_release(release, state) + if newest and api(REPO, 'releases/latest')['tag_name'] != state['tag']: + raise ValueError('assistant latest release readback mismatch; inspect native release state') + guard(state) + return 'main-and-tag' if newest else 'historical-tag-only' + + +def deliver(tag, sha, digest, root=package.ROOT, writer=None): + with tempfile.TemporaryDirectory(prefix='hitkeep-assistant-receive-') as directory: + temp = Path(directory) + state = prepare(tag, sha, digest, root, temp) + disposition = (writer or write)(state, root, temp) + return dict(tag=tag, source_sha=sha, package_sha256=digest, output_ref='refs/tags/' + tag, + output_sha=state.get('output_sha'), main_sha=state['head'], disposition=disposition) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('action', choices=('verify', 'publish')) + parser.add_argument('--release-tag', required=True) + parser.add_argument('--source-sha', required=True) + parser.add_argument('--package-sha256', required=True) + args = parser.parse_args() + if args.action == 'verify': + with tempfile.TemporaryDirectory(prefix='hitkeep-assistant-verify-') as directory: + prepare(args.release_tag, args.source_sha, args.package_sha256, package.ROOT, Path(directory)) + report = dict(tag=args.release_tag, source_sha=args.source_sha, package_sha256=args.package_sha256, disposition='verified') + else: + report = deliver(args.release_tag, args.source_sha, args.package_sha256) + print(json.dumps(report, sort_keys=True)) + if os.environ.get('GITHUB_STEP_SUMMARY'): + with open(os.environ['GITHUB_STEP_SUMMARY'], 'a') as summary: + summary.write('```json\n' + json.dumps(report, indent=2, sort_keys=True) + '\n```\n') + + +if __name__ == '__main__': + main() diff --git a/tests/test_package.py b/tests/test_package.py index 89531d5..e52ef9f 100644 --- a/tests/test_package.py +++ b/tests/test_package.py @@ -1,6 +1,9 @@ import importlib.util from pathlib import Path import shutil +import subprocess +import json +import hashlib import tempfile import unittest @@ -19,11 +22,85 @@ def setUp(self): shutil.copytree(ROOT / name, self.root / name) self.plugin = self.root / "plugins/hitkeep-analytics" + def source(self): + source = self.root / "upstream" + source.mkdir() + for relative in package.CANONICAL: + target = source / relative + target.parent.mkdir(parents=True, exist_ok=True) + target.write_bytes((self.plugin / relative).read_bytes()) + def git(*args): + return subprocess.check_output(["git", "-C", str(source), *args]).decode().strip() + git("init", "-q") + git("add", ".") + git("-c", "user.name=Fixture", "-c", "user.email=fixture@example.invalid", "commit", "-qm", "fixture") + return source, git("rev-parse", "HEAD"), git + + def test_rehashed_tamper_fails_independent_source_verification(self): + source, commit, _ = self.source() + package.sync(source, commit, "2.15.1", self.root) + path = self.plugin / "skills/hitkeep-analytics/SKILL.md" + path.write_text("tampered") + inventory = self.plugin / "source.json" + 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"): + package.verify_source(source, commit, self.root) + + def test_sync_uses_immutable_source_and_updates_versions(self): + source, commit, _ = self.source() + (source / "skills/hitkeep-analytics/SKILL.md").write_text("uncommitted") + (source / ".agents").mkdir() + (source / ".agents/private").write_text("not product content") + package.sync(source, commit, "2.15.1", self.root) + package.verify_source(source, commit, self.root) + self.assertEqual(package.verify(self.root)[0], "2.15.1") + inventory = json.loads((self.plugin / "source.json").read_text()) + self.assertEqual(inventory["commit"], commit) + self.assertRegex(inventory["packager_commit"], r"^[0-9a-f]{40}$") + self.assertEqual(set(inventory["sha256"]), package.CANONICAL) + self.assertEqual((self.root / "LICENSE").read_bytes(), (source / "LICENSE").read_bytes()) + self.assertEqual((self.root / ".agents/plugins/marketplace.json").read_bytes(), + (ROOT / ".agents/plugins/marketplace.json").read_bytes()) + + def test_source_symlink_rejected_before_writes(self): + source, _, git = self.source() + path = source / "skills/hitkeep-analytics/SKILL.md" + path.unlink() + path.symlink_to("../../LICENSE") + git("add", ".") + git("-c", "user.name=Fixture", "-c", "user.email=fixture@example.invalid", "commit", "-qm", "symlink") + before = (self.plugin / "source.json").read_bytes() + with self.assertRaisesRegex(ValueError, "regular"): + package.sync(source, git("rev-parse", "HEAD"), "2.15.1", self.root) + self.assertEqual(before, (self.plugin / "source.json").read_bytes()) + + def test_bad_source_identity_and_version_rejected_before_writes(self): + source, commit, _ = self.source() + before = (self.plugin / "source.json").read_bytes() + for sha, version in (("HEAD", "2.15.1"), (commit, "../escape"), ("0" * 40, "2.15.1")): + with self.assertRaises(ValueError): + package.sync(source, sha, version, self.root) + self.assertEqual(before, (self.plugin / "source.json").read_bytes()) + def test_changed_canonical_skill_is_rejected(self): (self.plugin / "skills/hitkeep-analytics/SKILL.md").write_text("changed") with self.assertRaisesRegex(ValueError, "canonical content changed"): package.verify(self.root) + def test_manifest_hooks_are_rejected(self): + for relative in ("plugin.json", ".claude-plugin/plugin.json"): + path = self.plugin / relative + original = path.read_text() + data = json.loads(original) + data["hooks"] = {"PostToolUse": [{"command": "unexpected"}]} + path.write_text(json.dumps(data)) + with self.assertRaisesRegex(ValueError, "hooks"): + package.verify(self.root) + path.write_text(original) + def test_extra_content_is_rejected(self): (self.plugin / "hook.sh").write_text("unexpected") with self.assertRaisesRegex(ValueError, "allowlist mismatch"): diff --git a/tests/test_release_delivery.py b/tests/test_release_delivery.py new file mode 100644 index 0000000..80a6971 --- /dev/null +++ b/tests/test_release_delivery.py @@ -0,0 +1,535 @@ +import copy +import hashlib +import importlib.util +import io +import json +from pathlib import Path +import tempfile +import sys +import unittest +from unittest.mock import Mock, patch +import zipfile + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'scripts')) +spec = importlib.util.spec_from_file_location('delivery', ROOT / 'scripts/release_delivery.py') +delivery = importlib.util.module_from_spec(spec) +spec.loader.exec_module(delivery) + + +class DeliveryTests(unittest.TestCase): + def setUp(self): + self.sha = 'a' * 40 + self.producer = 'b' * 40 + self.digest = 'c' * 64 + self.manifest = dict(schema_version=1, tag='v2.15.1', source_commit=self.sha, + producer_workflow_sha=self.producer, producer_run_id=123, + producer_run_attempt=2, checks=dict.fromkeys(delivery.CHECKS, 'success'), + artifacts=[dict(name='hitkeep-analytics-2.15.1.zip', type='assistant-package', sha256=self.digest)]) + self.run = dict(id=123, run_attempt=2, repository=dict(full_name=delivery.APP), + head_repository=dict(full_name=delivery.APP), head_branch='main', + path=delivery.PRODUCER, head_sha=self.producer, event='workflow_dispatch', + status='completed', conclusion='success') + self.certificate = dict(sourceRepositoryURI='https://github.com/' + delivery.APP, + sourceRepositoryDigest=self.producer, sourceRepositoryRef='refs/heads/main', + buildSignerURI='https://github.com/' + delivery.APP + '/' + delivery.PRODUCER + '@refs/heads/main', + runInvocationURI='https://github.com/' + delivery.APP + '/actions/runs/123/attempts/2') + self.attestations = [dict(verificationResult=dict(signature=dict(certificate=self.certificate)))] + + def validate(self): + delivery.validate_candidate(self.manifest, self.run, self.attestations, + 'v2.15.1', self.sha, self.digest) + + def test_candidate_producer_and_attempt_are_bound(self): + self.validate() + for key, value in [('run_attempt', 1), ('head_sha', 'd' * 40), ('head_branch', 'untrusted'), + ('event', 'pull_request'), ('conclusion', 'failure')]: + with self.subTest(key=key): + previous = self.run[key] + self.run[key] = value + with self.assertRaises(ValueError): + self.validate() + self.run[key] = previous + self.certificate['runInvocationURI'] = self.certificate['runInvocationURI'].replace('/2', '/1') + with self.assertRaises(ValueError): + self.validate() + + def test_wrong_signer_missing_check_and_duplicate_asset_fail(self): + for mutate in (lambda: self.certificate.update(buildSignerURI='untrusted'), + lambda: self.manifest['checks'].pop('native'), + lambda: self.manifest['artifacts'].append(copy.deepcopy(self.manifest['artifacts'][0]))): + self.setUp() + mutate() + with self.assertRaises(ValueError): + self.validate() + + def test_dispatch_identity_is_closed(self): + env = dict(GITHUB_REPOSITORY=delivery.REPO, GITHUB_REF='refs/heads/main', + GITHUB_EVENT_NAME='workflow_dispatch', GITHUB_WORKFLOW_REF=delivery.REPO + '/' + delivery.WORKFLOW + '@refs/heads/main') + delivery.validate_dispatch(env) + for key in env: + invalid = dict(env, **{key: 'untrusted'}) + with self.assertRaises(ValueError): + delivery.validate_dispatch(invalid) + + def test_private_draft_prerelease_and_moved_tag_fail(self): + release = dict(tag_name='v2.15.1', draft=False, prerelease=False) + delivery.validate_release(dict(private=False), release, self.sha, 'v2.15.1', self.sha) + for repository, changed, tag_sha in ((dict(private=True), release, self.sha), + (dict(private=False), dict(release, draft=True), self.sha), + (dict(private=False), dict(release, prerelease=True), self.sha), + (dict(private=False), release, 'd' * 40)): + with self.assertRaises(ValueError): + delivery.validate_release(repository, changed, tag_sha, 'v2.15.1', self.sha) + + def test_zip_faults_do_not_write(self): + expected = sorted('hitkeep-analytics/' + path for path in delivery.package.CANONICAL | { + 'plugin.json', '.claude-plugin/plugin.json', 'source.json', 'README.md'}) + for fault in ('traversal', 'hook', 'contributor', 'private', 'duplicate', 'symlink', 'executable'): + with self.subTest(fault=fault): + names = list(expected) + if fault == 'traversal': names[0] = '../escape' + if fault == 'hook': names.append('hitkeep-analytics/hook.sh') + if fault == 'contributor': names.append('hitkeep-analytics/.agents/skills/private/SKILL.md') + if fault == 'private': names.append('hitkeep-analytics/private-report.json') + if fault == 'duplicate': names[0] = names[1] + raw = io.BytesIO() + import warnings + with warnings.catch_warnings(), zipfile.ZipFile(raw, 'w') as archive: + warnings.simplefilter('ignore', UserWarning) + for index, name in enumerate(names): + info = zipfile.ZipInfo(name) + mode = 0o120777 if fault == 'symlink' and index == 0 else 0o100644 + if fault == 'executable' and index == 0: mode = 0o100755 + info.external_attr = mode << 16 + archive.writestr(info, 'data') + with tempfile.TemporaryDirectory() as temp: + root = Path(temp) / 'output' + with self.assertRaises(ValueError): + delivery.unpack(raw.getvalue(), root) + self.assertFalse(root.exists()) + + def test_optional_transport_only_accepts_explicit_404(self): + from subprocess import CompletedProcess + for code in (401, 403, 500): + with patch.object(delivery.subprocess, 'run', return_value=CompletedProcess([], 1, b'', f'gh: failed (HTTP {code})'.encode())): + with self.assertRaises(ValueError): + delivery.command('gh', 'api', 'example', optional=True) + with patch.object(delivery.subprocess, 'run', return_value=CompletedProcess([], 1, b'', b'gh: Not Found (HTTP 404)')): + self.assertIsNone(delivery.command('gh', 'api', 'example', optional=True)) + + def test_policy_and_failed_validation_cannot_reach_writer(self): + for protected, rules in [(True, []), (False, [dict(enforcement='active')])]: + with self.assertRaises(ValueError): + delivery.validate_policy(dict(protected=protected), rules) + writer = Mock() + with patch.object(delivery, 'prepare', side_effect=ValueError('network/auth/validation failure')): + with self.assertRaises(ValueError): + delivery.deliver('v2.15.1', self.sha, self.digest, ROOT, writer=writer) + writer.assert_not_called() + + def test_semver_orders_backports_numerically(self): + self.assertLess(delivery.version('v2.9.9'), delivery.version('v2.15.1')) + for value in ['v2.015.1', '../escape', '2.15.1', 'v2.15.1-rc.1']: + with self.assertRaises(ValueError): + delivery.version(value) + + +class QueuePolicyTests(unittest.TestCase): + def test_global_receiver_queue_preserves_multiple_pending_native_releases(self): + workflow = (ROOT / '.github/workflows/sync-hitkeep-release.yml').read_text() + concurrency = workflow.split('\nconcurrency:\n', 1)[1].split('\nenv:\n', 1)[0] + self.assertIn(' group: sync-hitkeep-release\n', concurrency) + self.assertIn(' cancel-in-progress: false\n', concurrency) + self.assertIn(' queue: max\n', concurrency) + + +class WriterTests(unittest.TestCase): + """Real local Git objects/pushes, fake GitHub APIs; never touches a public repository.""" + def setUp(self): + self.temp = tempfile.TemporaryDirectory() + self.addCleanup(self.temp.cleanup) + self.base = Path(self.temp.name) + self.root = self.base / 'checkout' + self.root.mkdir() + import shutil + for name in ('plugins', '.claude-plugin', '.agents'): + shutil.copytree(ROOT / name, self.root / name) + shutil.copyfile(ROOT / 'LICENSE', self.root / 'LICENSE') + (self.root / 'reviewed-code').write_text('must not change') + self.git(self.root, 'init', '-q', '-b', 'main') + self.git(self.root, 'add', '-f', '.') + self.git(self.root, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', 'commit', '-qm', 'baseline') + self.remote = self.base / 'remote.git' + self.git(self.root, 'clone', '-q', '--bare', str(self.root), str(self.remote)) + self.releases = {'v2.15.0': dict(tag_name='v2.15.0', draft=False, prerelease=False, body='historical', assets=[dict(name='preserved.zip')])} + self.latest = 'v2.15.0' + self.mutations = [] + self.protected = False + self.interrupt = None + self.original_command = delivery.command + self.addCleanup(patch.stopall) + patch.object(delivery, 'command', side_effect=self.command).start() + patch.object(delivery, 'api', side_effect=self.api).start() + patch.object(delivery, 'tag_commit', side_effect=self.tag).start() + patch.object(delivery, 'download', side_effect=lambda entry: entry['bytes']).start() + self.state = self.new_state('v2.15.1') + + def git(self, root, *args): + import subprocess + return subprocess.check_output(['git', '-C', str(root), *args], stderr=subprocess.PIPE).decode().strip() + + def head(self): + return self.git(self.remote, 'rev-parse', 'refs/heads/main') + + def new_state(self, tag): + files = {name: (self.root / name).read_bytes() for name in delivery.package.GENERATED} + for path in ('plugins/hitkeep-analytics/plugin.json', 'plugins/hitkeep-analytics/.claude-plugin/plugin.json'): + value = json.loads(files[path]); value['version'] = tag[1:] + files[path] = (json.dumps(value, indent=2) + '\n').encode() + path = '.claude-plugin/marketplace.json' + value = json.loads(files[path]); value['plugins'][0]['version'] = tag[1:] + files[path] = (json.dumps(value, indent=2) + '\n').encode() + return dict(tag=tag, sha='a' * 40, digest=hashlib.sha256(b'zip').hexdigest(), head=self.head(), + candidate=b'candidate', tree=files) + + def api(self, repo, path, optional=False): + if repo == delivery.APP: + if path == '': + return dict(private=False) + if path.startswith('releases/tags/'): + return dict(tag_name=path.split('/')[-1], draft=False, prerelease=False, + assets=[dict(name='release-candidate.json', bytes=b'candidate'), + dict(name='hitkeep-analytics-' + path.split('/')[-1][1:] + '.zip', bytes=b'zip')]) + if path == 'branches/main': + return dict(protected=self.protected, commit=dict(sha=self.head())) + if path == 'rulesets?includes_parents=true': + return [] + if path == 'releases/latest': + return self.releases[self.latest] + if path.startswith('releases/tags/'): + return self.releases.get(path.split('/')[-1]) + raise AssertionError((repo, path)) + + def tag(self, repo, tag): + if repo == delivery.APP: + return 'a' * 40 + try: + return self.git(self.remote, 'rev-parse', '--verify', 'refs/tags/' + tag) + except Exception: + return None + + def command(self, *args, **kwargs): + args = list(args) + if args[:3] == ['gh', 'release', 'create']: + self.mutations.append('release') + if self.interrupt == 'before-release': + self.interrupt = None + raise ValueError('injected interruption before release creation') + tag = args[3] + self.releases[tag] = dict(tag_name=tag, draft=False, prerelease=False, + body=Path(args[args.index('--notes-file') + 1]).read_text(), assets=[]) + if '--latest=true' in args: + self.latest = tag + if self.interrupt == 'after-release': + self.interrupt = None + raise ValueError('injected disconnect after release creation') + return b'' + if 'remote' in args and 'set-url' in args: + args[-1] = str(self.remote) + if 'push' in args: + target = args[-1].split(':')[-1] + if self.interrupt == 'before-tag' and target.startswith('refs/tags/'): + self.interrupt = None + raise ValueError('injected interruption after main update') + self.mutations.append(target) + self.assertNotIn('--force', args) + self.assertNotIn('--force-with-lease', args) + return self.original_command(*args, **kwargs) + + def write(self, state=None): + directory = self.base / ('attempt-' + str(len(list(self.base.glob('attempt-*'))))) + directory.mkdir() + return delivery.write(state or self.state, self.root, directory) + + def generated_commit(self, files=None, extras=None, modes=None): + import os + import subprocess + with tempfile.TemporaryDirectory(dir=self.base) as directory: + env = dict(os.environ, GIT_INDEX_FILE=str(Path(directory) / 'index')) + def git(*args, data=None): + return subprocess.check_output(['git', '-C', str(self.root), *args], input=data, + env=env, stderr=subprocess.PIPE).decode().strip() + parent = self.git(self.root, 'rev-parse', 'HEAD') + git('read-tree', parent) + for path, data in {**(files or {}), **(extras or {})}.items(): + blob = git('hash-object', '-w', '--stdin', data=data) + git('update-index', '--add', '--cacheinfo', (modes or {}).get(path, '100644') + ',' + blob + ',' + path) + for path, mode in (modes or {}).items(): + if path not in (files or {}) and path not in (extras or {}): + blob = git('rev-parse', parent + ':' + path) + git('update-index', '--cacheinfo', mode + ',' + blob + ',' + path) + tree = git('write-tree') + return git('-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', + 'commit-tree', tree, '-p', parent, '-m', 'generated tree fixture') + + def assert_generated_refused(self, ref, *, extras=None, modes=None, files=None): + commit = self.generated_commit(files=self.state['tree'] if ref.startswith('refs/tags/') else files, + extras=extras, modes=modes) + self.git(self.root, 'push', str(self.remote), commit + ':' + ref) + if ref == 'refs/heads/main': + self.state['head'] = commit + before_main = self.head() + before_refs = self.git(self.remote, 'show-ref') + with self.assertRaises(ValueError): + self.write() + self.assertEqual(self.mutations, []) + self.assertEqual(self.head(), before_main) + self.assertEqual(self.git(self.remote, 'show-ref'), before_refs) + self.assertEqual(self.releases['v2.15.0']['assets'], [dict(name='preserved.zip')]) + + def test_existing_tag_rejects_extra_plugin_hook_even_when_expected_bytes_match(self): + self.assert_generated_refused('refs/tags/v2.15.1', + extras={'plugins/hitkeep-analytics/hooks/hooks.json': b'{"hooks":{}}'}) + + def test_current_main_rejects_extra_plugin_file_instead_of_carrying_it_forward(self): + self.assert_generated_refused('refs/heads/main', + extras={'plugins/hitkeep-analytics/private.txt': b'not attested'}) + + def test_existing_tag_rejects_extra_claude_catalog_content(self): + self.assert_generated_refused('refs/tags/v2.15.1', + extras={'.claude-plugin/hooks/hooks.json': b'{"hooks":{}}'}) + + def test_current_main_rejects_extra_openai_catalog_content(self): + self.assert_generated_refused('refs/heads/main', + extras={'.agents/plugins/extra.json': b'{}'}) + + def test_existing_tag_rejects_executable_generated_file(self): + self.assert_generated_refused('refs/tags/v2.15.1', + modes={'plugins/hitkeep-analytics/skills/hitkeep-analytics/SKILL.md': '100755'}) + + def test_current_main_rejects_symlink_mode_with_matching_catalog_bytes(self): + self.assert_generated_refused('refs/heads/main', files=self.state['tree'], + modes={'.agents/plugins/marketplace.json': '120000'}) + + def test_current_main_rejects_unexpected_native_catalog_fields(self): + path = '.claude-plugin/marketplace.json' + data = json.loads((self.root / path).read_bytes()) + data['hooks'] = {'unexpected': 'not attested'} + self.assert_generated_refused('refs/heads/main', files={path: json.dumps(data).encode()}) + + def test_complete_matching_tag_is_noop_and_repository_owned_files_are_preserved(self): + owned = {'scripts/owned.py': b'raise RuntimeError("never execute")', + '.github/workflows/owned.yml': b'name: preserved', 'README.md': b'repository README', + '.agents/skills/repository-owned/SKILL.md': b'not a generated product skill'} + commit = self.generated_commit(files=self.state['tree'], extras=owned) + self.git(self.root, 'push', str(self.remote), commit + ':refs/heads/main', commit + ':refs/tags/v2.15.1') + self.state['head'] = commit + self.latest = 'v2.15.1' + self.releases[self.latest] = dict(tag_name=self.latest, draft=False, prerelease=False, + body=delivery.release_notes(self.state), assets=[]) + self.assertEqual(self.write(), 'main-and-tag') + self.assertEqual(self.mutations, []) + for path, data in owned.items(): + self.assertEqual(delivery.package.git(self.remote, 'show', commit + ':' + path), data) + + def test_newest_fast_forwards_only_generated_files_and_retry_is_noop(self): + old = self.head() + self.assertEqual(self.write(), 'main-and-tag') + new = self.head() + self.assertNotEqual(new, old) + self.assertEqual(self.git(self.remote, 'show', new + ':reviewed-code'), 'must not change') + changed = self.git(self.remote, 'diff', '--name-only', old, new).splitlines() + self.assertTrue(set(changed) <= delivery.package.GENERATED) + self.assertEqual(self.tag(delivery.REPO, 'v2.15.1'), new) + self.assertEqual(self.releases['v2.15.1']['assets'], []) + self.assertIn('/HitKeep/hitkeep/releases/download/v2.15.1/', self.releases['v2.15.1']['body']) + previous = list(self.mutations) + self.assertEqual(self.write(), 'main-and-tag') + self.assertEqual(previous, self.mutations) + self.assertEqual(self.releases['v2.15.0']['assets'], [dict(name='preserved.zip')]) + + def test_backport_creates_only_historical_tag_and_link(self): + self.write() + head = self.head() + state = self.new_state('v2.14.9') + self.assertEqual(self.write(state), 'historical-tag-only') + self.assertEqual(self.head(), head) + self.assertEqual(self.latest, 'v2.15.1') + self.assertNotEqual(self.tag(delivery.REPO, 'v2.14.9'), head) + self.assertEqual(self.git(self.remote, 'for-each-ref', '--format=%(refname)', 'refs/heads'), 'refs/heads/main') + + def test_immutable_tag_and_release_conflicts_fail_before_writes(self): + self.git(self.remote, 'update-ref', 'refs/tags/v2.15.1', self.head()) + with self.assertRaisesRegex(ValueError, 'immutable assistant tag'): + self.write() + self.assertEqual(self.mutations, []) + self.git(self.remote, 'update-ref', '-d', 'refs/tags/v2.15.1') + self.releases['v2.15.1'] = dict(tag_name='v2.15.1', draft=False, prerelease=False, body='conflict', assets=[]) + with self.assertRaisesRegex(ValueError, 'immutable assistant release'): + self.write() + self.assertEqual(self.mutations, []) + + def test_protection_and_stale_head_fail_before_writes(self): + self.protected = True + with self.assertRaisesRegex(ValueError, 'policy changed'): + self.write() + self.assertEqual(self.mutations, []) + self.protected = False + old = self.head() + tree = self.git(self.remote, 'rev-parse', old + '^{tree}') + racing = self.git(self.remote, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', + 'commit-tree', tree, '-p', old, '-m', 'concurrent head') + self.git(self.remote, 'update-ref', 'refs/heads/main', racing) + with self.assertRaisesRegex(ValueError, 'main changed'): + self.write() + self.assertEqual(self.mutations, []) + + def test_native_retry_resumes_each_interruption(self): + for point in ('before-tag', 'before-release', 'after-release'): + with self.subTest(point=point): + self.interrupt = point + tag = 'v2.15.' + str(2 + ('before-tag', 'before-release', 'after-release').index(point)) + state = self.new_state(tag) + with self.assertRaisesRegex(ValueError, 'injected'): + self.write(state) + state['head'] = self.head() + self.assertEqual(self.write(state), 'main-and-tag') + self.assertEqual(self.latest, tag) + + +class PrepareTests(DeliveryTests): + def setUp(self): + super().setUp() + import shutil + import subprocess + self.temp = tempfile.TemporaryDirectory() + self.addCleanup(self.temp.cleanup) + self.base = Path(self.temp.name) + self.source = self.base / 'app-source' + self.source.mkdir() + for name in delivery.package.CANONICAL: + path = self.source / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes((ROOT / 'plugins/hitkeep-analytics' / name).read_bytes()) + def git(*args): + return subprocess.check_output(['git', '-C', str(self.source), *args], stderr=subprocess.PIPE).decode().strip() + git('init', '-q'); git('add', '.') + git('-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', 'commit', '-qm', 'canonical source') + self.sha = git('rev-parse', 'HEAD') + self.manifest['source_commit'] = self.sha + generated = self.base / 'generated' + generated.mkdir() + for name in ('plugins', '.claude-plugin', '.agents'): + shutil.copytree(ROOT / name, generated / name) + delivery.package.sync(self.source, self.sha, '2.15.1', generated) + output = self.base / 'package.zip' + delivery.package.package(output, generated) + self.raw = output.read_bytes() + self.update_digest() + self.release = dict(tag_name='v2.15.1', draft=False, prerelease=False, + assets=[dict(id=1, name='release-candidate.json'), dict(id=2, name='hitkeep-analytics-2.15.1.zip')]) + self.app_private = False + self.fail_signature = False + self.actual_tag = self.sha + self.original_command = delivery.command + self.env = dict(GITHUB_REPOSITORY=delivery.REPO, GITHUB_REF='refs/heads/main', + GITHUB_EVENT_NAME='workflow_dispatch', GITHUB_WORKFLOW_REF=delivery.REPO + '/' + delivery.WORKFLOW + '@refs/heads/main') + self.addCleanup(patch.stopall) + patch.dict('os.environ', self.env).start() + patch.object(delivery, 'command', side_effect=self.transport).start() + patch.object(delivery, 'api', side_effect=self.api).start() + patch.object(delivery, 'tag_commit', side_effect=lambda repo, tag: self.actual_tag).start() + patch.object(delivery, 'download', side_effect=lambda entry: json.dumps(self.manifest).encode() if entry['id'] == 1 else self.raw).start() + + def update_digest(self): + self.digest = hashlib.sha256(self.raw).hexdigest() + self.manifest['artifacts'][0]['sha256'] = self.digest + + def transport(self, *args, **kwargs): + args = list(args) + if args[:3] == ['gh', 'attestation', 'verify']: + if self.fail_signature: + raise ValueError('native attestation verification rejected signature') + self.assertIn('--source-digest', args) + self.assertEqual(args[args.index('--source-digest') + 1], self.producer) + self.assertIn('--deny-self-hosted-runners', args) + return json.dumps(self.attestations).encode() + if 'fetch' in args and 'https://github.com/' + delivery.APP + '.git' in args: + args[args.index('https://github.com/' + delivery.APP + '.git')] = str(self.source) + elif 'fetch' in args: + return b'' + return self.original_command(*args, **kwargs) + + def api(self, repo, path, optional=False): + if repo == delivery.APP: + if path == '': return dict(private=self.app_private) + if path.startswith('releases/tags/'): return self.release + if path.startswith('actions/runs/'): return self.run + if path.startswith('compare/'): return dict(status='ahead') + if repo == delivery.REPO: + if path == 'branches/main': + return dict(protected=False, commit=dict(sha=delivery.package.git(ROOT, 'rev-parse', 'HEAD').decode().strip())) + if path == 'rulesets?includes_parents=true': return [] + raise AssertionError((repo, path)) + + def assert_no_write(self): + writer = Mock() + with self.assertRaises((ValueError, zipfile.BadZipFile)): + delivery.deliver('v2.15.1', self.sha, self.digest, ROOT, writer=writer) + writer.assert_not_called() + + def rewrite_zip(self, name, data): + buffer = io.BytesIO() + with zipfile.ZipFile(io.BytesIO(self.raw)) as old, zipfile.ZipFile(buffer, 'w') as new: + for entry in old.infolist(): + new.writestr(entry, data if entry.filename == name else old.read(entry)) + self.raw = buffer.getvalue() + self.update_digest() + + def test_complete_verified_candidate_reaches_writer_once(self): + writer = Mock(return_value='verified-fixture') + report = delivery.deliver('v2.15.1', self.sha, self.digest, ROOT, writer=writer) + writer.assert_called_once() + self.assertEqual(report['disposition'], 'verified-fixture') + self.assertEqual(set(writer.call_args.args[0]['tree']), delivery.package.GENERATED) + + def test_faults_never_reach_writer(self): + scenarios = ('private', 'draft', 'prerelease', 'moved-tag', 'wrong-attempt', 'wrong-signer', + 'digest', 'malformed-zip', 'version', 'source', 'rehashed-content', 'network', 'signature') + for case in scenarios: + with self.subTest(case=case): + original = (self.app_private, copy.deepcopy(self.release), self.actual_tag, copy.deepcopy(self.run), + copy.deepcopy(self.certificate), self.raw, self.digest, copy.deepcopy(self.manifest)) + if case == 'signature': self.fail_signature = True + if case == 'private': self.app_private = True + if case == 'draft': self.release['draft'] = True + if case == 'prerelease': self.release['prerelease'] = True + if case == 'moved-tag': self.actual_tag = 'd' * 40 + if case == 'wrong-attempt': self.run['run_attempt'] = 1 + if case == 'wrong-signer': self.certificate['buildSignerURI'] = 'untrusted' + if case == 'digest': self.raw += b'tamper' + if case == 'malformed-zip': + self.raw = b'not a zip'; self.update_digest() + if case == 'version': + self.rewrite_zip('hitkeep-analytics/plugin.json', b'{"version":"0.0.0"}') + if case in ('source', 'rehashed-content'): + with zipfile.ZipFile(io.BytesIO(self.raw)) as archive: + inventory = json.loads(archive.read('hitkeep-analytics/source.json')) + if case == 'source': inventory['commit'] = 'd' * 40 + else: + relative = 'skills/hitkeep-analytics/SKILL.md' + self.rewrite_zip('hitkeep-analytics/' + relative, b'tamper') + inventory['sha256'][relative] = hashlib.sha256(b'tamper').hexdigest() + self.rewrite_zip('hitkeep-analytics/source.json', json.dumps(inventory).encode()) + if case == 'network': + with patch.object(delivery, 'api', side_effect=ValueError('network/auth denied')): + self.assert_no_write() + else: self.assert_no_write() + self.app_private, self.release, self.actual_tag, self.run, saved, self.raw, self.digest, self.manifest = original + self.certificate.clear(); self.certificate.update(saved) + self.fail_signature = False + + +if __name__ == '__main__': + unittest.main()