diff --git a/docs/releasing.md b/docs/releasing.md index 22359470..8a5402db 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -97,23 +97,24 @@ anyone may pull the image without a GitHub login. Publishing it does not make a server reachable; the server has no authentication and stays on a trusted LAN (see [nest storage](nest-storage.md#deploying-with-compose)). -Publication requires an **existing public package**, linked to -`ajisaacs/OpenNest`, with repository Actions access (normally inherited from the -link). The job uses only its scoped `GITHUB_TOKEN`. All package metadata 404s are -refused: a 404 proves neither absence nor visibility. Opaque registry token -success, an empty tag list, or a registry 404 cannot override the metadata check. -Explicit reduced scope and failed registry read access also stop the job. A -package that is private or linked to another repository stops the job before -upload, and the job rechecks public visibility and association after upload. The -clean-runner verification then pulls the returned digest **without logging in**, -which proves anonymous pulls work. +The job uses only its scoped `GITHUB_TOKEN`. An existing package must be public +and linked to `ajisaacs/OpenNest`; a private package or one linked to another +repository stops the job before upload. The first publication creates the +package: GitHub's own `Not Found` package response is accepted only when the +registry also reports the repository unknown, because a package hidden from the +token still has a registry repository. Every other metadata error, denial, +reduced registry scope or failed tag-list read stops the job. Because the source +repository is public and the image carries its `org.opencontainers.image.source` +label, the new package is linked to the repository and public. The job rechecks +public visibility and association after upload, and the clean-runner +verification pulls the returned digest **without logging in**, which proves +anonymous pulls work. -First-package initialization is a one-time owner step outside this workflow: -push any image to `ghcr.io/ajisaacs/opennest-server` under a tag that no release -will use (never `X.Y.Z` or `sha-*`), then in the package settings link it to -`ajisaacs/OpenNest`, give that repository Actions write access and set visibility -to public. There is no automatic bootstrap, extra PAT or bypass setting, and no -workflow changes visibility. +If a first publication fails that recheck (the package came out private), the two +tags are already uploaded and a retry refuses them: in the package settings make +it public and confirm the anonymous pull by hand, or delete the package and +dispatch again. There is no extra PAT or bypass setting, and no workflow changes +visibility. The local gate reads `docker image save` to hash the actual config and verify each layer against its ordered uncompressed rootfs digest. It rejects unexpected diff --git a/scripts/server_image_release.py b/scripts/server_image_release.py index 24fe7937..a2e14b2b 100644 --- a/scripts/server_image_release.py +++ b/scripts/server_image_release.py @@ -117,8 +117,16 @@ def absent(status, headers, body): def package_policy(status, headers, body): + """Return True when GitHub reports no package yet (first publication). + + The repository is public and the image carries its source label, so the first + GITHUB_TOKEN push creates a public package linked to it; readback and the + anonymous pull prove that afterwards. Any other shape fails closed.""" data = json_body(body) require(isinstance(data, dict), "malformed package metadata") + if status == 404 and data.get("message") == "Not Found" and \ + str(data.get("documentation_url", "")).startswith("https://docs.github.com/"): + return True require(status == 200, "package metadata inaccessible; visibility unknown") require(data.get("name") == PACKAGE and data.get("package_type") == "container" and data.get("visibility") == "public" and isinstance(data.get("repository"), dict) and @@ -188,8 +196,12 @@ def preflight(client, release_version, sha): repo = json_body(body) require(status == 200 and isinstance(repo, dict) and repo.get("full_name") == REPO and repo.get("default_branch") == "master", "repository/default branch authorization unproven") - package_policy(*client.get(PACKAGE_API)) + first_publication = package_policy(*client.get(PACKAGE_API)) tags_response = client.get(registry_path("tags/list")) + if first_publication: + # A package hidden from this token would still have a registry repository. + require(absent(*tags_response), "package metadata missing but registry repository exists") + return {"package": IMAGE, "visibility": "public", "first_publication": True} require(tags_response[0] == 200, "existing package registry read access unproven") data = json_body(tags_response[2]) require(isinstance(data, dict) and data.get("name") == REGISTRY_NAME and @@ -439,7 +451,7 @@ def main(): local = local_identity(os.environ.get("LOCAL_IMAGE", "")) if args.operation == "readback": client = Client() - package_policy(*client.get(PACKAGE_API)) + require(not package_policy(*client.get(PACKAGE_API)), "package metadata missing after upload") directory = pathlib.Path(os.environ.get("METADATA_DIR", ".hermes/server-image-metadata")) try: previous = json_body((directory / "local.json").read_bytes()) diff --git a/scripts/test_server_image_release.py b/scripts/test_server_image_release.py index 72871117..93c92b95 100644 --- a/scripts/test_server_image_release.py +++ b/scripts/test_server_image_release.py @@ -134,10 +134,9 @@ class RegistrySafety(unittest.TestCase): with self.assertRaises(release.ReleaseError): release.package_policy(*response(200, wrong)) - def test_package_metadata_404_never_authorizes_bootstrap(self): - with self.assertRaises(release.ReleaseError): - release.package_policy(*response(404, { - "message": "Not Found", "documentation_url": "https://docs.github.com/rest/packages"})) + def test_github_not_found_metadata_means_first_publication(self): + self.assertTrue(release.package_policy(*response(404, { + "message": "Not Found", "documentation_url": "https://docs.github.com/rest/packages"}))) for status, body in ((403, {"message": "Resource not accessible"}), (404, {}), (404, {"message": "Not Found", "documentation_url": "https://evil.test"})): with self.assertRaises(release.ReleaseError): @@ -171,11 +170,20 @@ class RegistrySafety(unittest.TestCase): with self.assertRaises(release.ReleaseError): release.preflight(client, "1.2.3", SHA) - def test_missing_metadata_denies_regardless_of_registry_tags(self): - with self.assertRaises(release.ReleaseError): - release.preflight(self.preflight_client(404), "1.2.3", SHA) - with self.assertRaises(release.ReleaseError): - release.preflight(self.preflight_client(404, ["old"]), "1.2.3", SHA) + def test_first_publication_requires_an_absent_registry_repository(self): + client = self.preflight_client(404) + unknown = response(404, {"errors": [{"code": "NAME_UNKNOWN"}]}) + client.responses[release.registry_path("tags/list")] = unknown + self.assertEqual(release.preflight(client, "1.2.3", SHA), + {"package": release.IMAGE, "visibility": "public", "first_publication": True}) + for tags in ([], ["old"]): + with self.subTest(tags=tags), self.assertRaises(release.ReleaseError): + release.preflight(self.preflight_client(404, tags), "1.2.3", SHA) + for denied in (response(404, {"errors": [{"code": "DENIED"}]}), response(401, {}), response(403, {})): + client = self.preflight_client(404) + client.responses[release.registry_path("tags/list")] = denied + with self.subTest(denied=denied[0]), self.assertRaises(release.ReleaseError): + release.preflight(client, "1.2.3", SHA) def test_preflight_transport_metadata_and_tag_list_errors_fail_closed(self): for path in (release.REPO_API, release.PACKAGE_API, release.registry_path("tags/list")): @@ -502,6 +510,19 @@ class ArchiveIdentity(unittest.TestCase): with self.assertRaisesRegex(release.ReleaseError, "rootfs chain"): release.readback(client, "1.2.3", SHA, local) + def test_readback_refuses_a_package_still_missing_after_upload(self): + client, local = ReadbackSafety().fixture() + client.responses[release.PACKAGE_API] = response(404, { + "message": "Not Found", "documentation_url": "https://docs.github.com/rest/packages"}) + with tempfile.TemporaryDirectory() as directory: + env = {"VERSION": "1.2.3", "SOURCE_SHA": SHA, "METADATA_DIR": directory} + with mock.patch.dict(os.environ, env), mock.patch.object(release, "git", return_value=SHA), \ + mock.patch.object(release, "Client", return_value=client), \ + mock.patch.object(release, "local_identity", return_value=local), \ + mock.patch("sys.argv", ["helper", "readback"]): + with self.assertRaisesRegex(release.ReleaseError, "missing after upload"): + release.main() + def test_readback_requires_the_pre_smoke_identity_stamp(self): client, local = ReadbackSafety().fixture() client.responses[release.PACKAGE_API] = response(200, {"name": release.PACKAGE, @@ -535,15 +556,12 @@ class ArchiveIdentity(unittest.TestCase): class SpecRegressions(unittest.TestCase): - def test_masked_package_404_denies_even_empty_or_missing_registry(self): - safety = RegistrySafety() - for registry in (response(200, {"name": release.REGISTRY_NAME, "tags": []}), - response(404, {"errors": [{"code": "NAME_UNKNOWN"}]})): - client = safety.preflight_client(404) - client.responses[release.registry_path("tags/list")] = registry - with self.subTest(registry=registry), self.assertRaises(release.ReleaseError): - release.preflight(client, "1.2.3", SHA) - self.assertNotIn(release.registry_path("tags/list"), client.calls) + def test_masked_package_404_denies_an_existing_registry_repository(self): + client = RegistrySafety().preflight_client(404) + client.responses[release.registry_path("tags/list")] = response(200, {"name": release.REGISTRY_NAME, "tags": []}) + with self.assertRaises(release.ReleaseError): + release.preflight(client, "1.2.3", SHA) + self.assertFalse(any("/manifests/" in call for call in client.calls)) def test_opaque_reduced_scope_token_cannot_authorize_masked_metadata(self): with mock.patch.dict("os.environ", {"GITHUB_TOKEN": "test-only", "GITHUB_REPOSITORY": release.REPO}):