diff --git a/.github/workflows/audit.yml b/.github/workflows/audit.yml new file mode 100644 index 0000000..3118682 --- /dev/null +++ b/.github/workflows/audit.yml @@ -0,0 +1,21 @@ +# SPDX-License-Identifier: AGPL-3.0-only +name: Audit public publication boundary +on: + pull_request: + push: + branches: [main] +permissions: + contents: read +jobs: + audit: + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5 + with: + fetch-depth: 0 + persist-credentials: false + - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6 + with: + python-version: '3.12' + - run: python release.py check-repository + - run: python -m unittest -v test_release diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..b2b3295 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,137 @@ +# SPDX-License-Identifier: AGPL-3.0-only +name: Build and publish binary SDKs +on: + workflow_dispatch: + inputs: + engine_commit: + description: Full commit from the private engine's matching runtime- tag + required: true +permissions: + contents: read +concurrency: + group: sdk-${{ inputs.engine_commit }} + cancel-in-progress: false +jobs: + build: + if: github.ref == 'refs/heads/main' + strategy: + fail-fast: false + matrix: + include: + - os: ubuntu-22.04 + target: linux-x64 + - os: windows-2022 + target: windows-x64 + - os: macos-15 + target: macos-universal + runs-on: ${{ matrix.os }} + env: + ENGINE_COMMIT: ${{ inputs.engine_commit }} + SDK_TARGET: ${{ matrix.target }} + steps: + - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5 + with: + path: automation + fetch-depth: 0 + persist-credentials: false + - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6 + with: + python-version: '3.12' + - name: Audit automation and validate the requested commit + shell: bash + run: | + python automation/release.py check-repository --root automation + python -c 'import os,re; assert re.fullmatch("[0-9a-f]{40}",os.environ["ENGINE_COMMIT"])' + - name: Temporarily check out the private tagged source + uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5 + with: + repository: RakuenSoftware/wol-engine + ref: runtime-${{ inputs.engine_commit }} + token: ${{ secrets.ENGINE_SOURCE_TOKEN }} + path: private-engine + submodules: recursive + persist-credentials: false + - name: Verify the private tag's exact commit + working-directory: private-engine + shell: bash + run: test "$(git rev-parse HEAD)" = "$ENGINE_COMMIT" + - uses: actions/setup-dotnet@26b0ec14cb23fa6904739307f278c14f94c95bf1 # v5 + with: + dotnet-version: '10.0.403' + - run: python -m pip install scons==4.11.1 + - name: Install Linux tools + if: runner.os == 'Linux' + run: sudo apt-get update && sudo apt-get install -y g++ pkg-config patch libx11-dev libxrandr-dev libwayland-dev libxkbcommon0 libxcursor1 libxinerama1 libxi6 libgl1 + - name: Set up Windows compiler + if: runner.os == 'Windows' + shell: pwsh + run: | + $vs = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -latest -products '*' -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath + if (!$vs) { throw 'Visual C++ build tools are missing' } + cmd /c "`"$vs\VC\Auxiliary\Build\vcvars64.bat`" >nul && set" | ForEach-Object { + if ($_ -match '^([^=]+)=(.*)$') { [Environment]::SetEnvironmentVariable($matches[1], $matches[2], 'Process') } + } + foreach ($name in @('INCLUDE', 'LIB', 'LIBPATH', 'VCINSTALLDIR', 'VCToolsInstallDir', 'WindowsSdkDir', 'WindowsSDKVersion', 'UniversalCRTSdkDir', 'UCRTVersion')) { + $value = [Environment]::GetEnvironmentVariable($name, 'Process') + if ($value) { "$name=$value" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append } + } + "$env:PATH;C:\Program Files\Git\usr\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append + - name: Compile and qualify the private engine without publishing compiler output + shell: python + run: | + import os, pathlib, subprocess, sys + log = pathlib.Path(os.environ['RUNNER_TEMP']) / 'private-sdk-build.log' + with log.open('w') as stream: + result = subprocess.run([sys.executable, 'scripts/package_runtime.py', os.environ['SDK_TARGET'], '--output', 'dist/sdk', '--release-repository', 'RakuenSoftware/wol-engine-release'], cwd='private-engine', stdout=stream, stderr=subprocess.STDOUT) + if result.returncode: + raise SystemExit('SDK compilation/qualification failed. Compiler output was withheld; inspect privately.') + - name: Audit and copy only approved binary SDK files + shell: bash + run: python automation/release.py stage --input private-engine/dist --output "$RUNNER_TEMP/approved-sdk" --commit "$ENGINE_COMMIT" --target "$SDK_TARGET" + - name: Remove the private checkout and compiler output + if: always() + shell: python + run: | + import os, pathlib, shutil + shutil.rmtree(pathlib.Path(os.environ['GITHUB_WORKSPACE']) / 'private-engine', ignore_errors=True) + (pathlib.Path(os.environ['RUNNER_TEMP']) / 'private-sdk-build.log').unlink(missing_ok=True) + - name: Upload only audited archives and checksums + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + with: + name: sdk-${{ matrix.target }} + path: | + ${{ runner.temp }}/approved-sdk/*.zip + ${{ runner.temp }}/approved-sdk/*.sha256 + if-no-files-found: error + retention-days: 7 + publish: + needs: build + runs-on: ubuntu-22.04 + permissions: + contents: write + env: + ENGINE_COMMIT: ${{ inputs.engine_commit }} + steps: + - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5 + with: + path: automation + fetch-depth: 0 + persist-credentials: false + - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6 + with: + python-version: '3.12' + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 + with: + path: incoming + merge-multiple: true + - name: Independently audit all three SDKs before publication + shell: bash + run: | + python automation/release.py check-repository --root automation + python automation/release.py stage --input incoming --output "$RUNNER_TEMP/release-sdk" --commit "$ENGINE_COMMIT" + - name: Publish binary assets without engine source access + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + shell: bash + run: gh release create "runtime-$ENGINE_COMMIT" "$RUNNER_TEMP/release-sdk/"*.zip "$RUNNER_TEMP/release-sdk/"*.sha256 --target "$GITHUB_SHA" --prerelease --title "WoL Engine SDK $ENGINE_COMMIT" --notes 'Native Linux, Windows and universal macOS binary SDKs. All three were qualified and independently audited before publication. No implementation source, compiler logs or debug symbols are included. Compiled binaries remain inspectable.' diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d2567df --- /dev/null +++ b/.gitignore @@ -0,0 +1,25 @@ +# Private inputs and build outputs must never enter Git. +engine/ +private-engine/ +_private*/ +runtime/ +native/ +addons/ +managed/ +.dependen*/ +dist/ +*.zip +*.sha256 +*.dll +*.exe +*.so +*.dylib +*.pdb +*.cs +*.gd +*.gdshader +*.gdshaderinc +*.log +*.pem +.env* +__pycache__/ diff --git a/README.md b/README.md index b42308e..8b46365 100644 --- a/README.md +++ b/README.md @@ -1 +1,75 @@ -# wol-engine-release \ No newline at end of file + +# WoL Engine binary releases + +This public repository owns build automation and binary SDK publication. The +engine implementation stays in the private `RakuenSoftware/wol-engine` +repository. Project Vagrant vendors the downloaded SDK archives from this +repository's Releases page. + +## Publication boundary + +- Public Git history contains only the explicitly allowed automation, tests, + documentation and licence files. The audit checks all reachable history, so + deleting a forbidden file in a later commit does not make it acceptable. +- Only a manual run of the workflow on `main` can access the source credential. + Pull request checks never receive it. Maintainers who can change `main` or + workflows are trusted with this credential; review those changes accordingly. +- Each fresh GitHub-hosted Linux, Windows and Mac runner temporarily checks out + an exact private `runtime-<40-character SHA>` tag into a separate sibling + directory. The tag's resolved commit must match the requested SHA. +- Compiler output goes to a temporary private file. Failure reports are generic. + The workflow removes the source checkout and compiler output before uploading + anything. There are no build caches, source artifacts or diagnostic uploads. +- The publication audit verifies archive identity, provenance, every file hash, + platform binary formats and a restricted file inventory. It rejects nonempty + C# files, loose shaders, implementation source, debug/symbol packages, + credentials and logs. Checksum files must contain only their exact checksum + record. Godot dependency packages are also inspected. +- Only approved ZIP archives and SHA-256 records reach the artifact service. + A separate publishing job has no private source credential and independently + audits all three platforms before creating a release. Any failed platform or + audit prevents publication. + +SDKs intentionally include empty C# resource identity stubs, engine branding, +Godot scene resources, licence notices and compiled managed/native binaries. +Compiled code can be inspected or decompiled. Shader programs are compiled into +the managed assembly and can also be recovered from it. This boundary prevents +shipping loose implementation source; it does not provide irreversible secrecy +for software that users execute. + +## Enable builds + +1. Merge the private engine packaging changes that remove loose shader sources + and support `--release-repository RakuenSoftware/wol-engine-release`. +2. Configure the repository Actions secret `ENGINE_SOURCE_TOKEN` with a + fine-grained credential granting **Contents: read** only on the private + `RakuenSoftware/wol-engine` repository. Do not paste credentials into issues, + workflow inputs, commits or logs. Keep automatic pull request reviews enabled. +3. Merge this repository's reviewed automation to `main`. Create a private + engine tag `runtime-` for the reviewed source to build. +4. Run **Build and publish binary SDKs** on `main` with that exact commit SHA. + All three native-host SDK jobs must pass. The release contains three ZIP + archives and their checksum records; GitHub's automatic source archives + contain only this public automation repository. +5. Download those release assets and vendor them into Project Vagrant with its + existing `tools/release.py --vendor-runtime` command. + +The first build must use the new packager. Existing SDKs containing loose shader +files are deliberately rejected. Old downloads are not retroactively removed +by this pipeline. + +## Verification + +```sh +python -m unittest -v test_release +python release.py check-repository +python release.py stage --input downloaded-sdk-assets --output approved-sdk --commit FULL_SHA +``` + +The automated tests use deliberate miniature fixtures; they do not build SDKs +locally. Real native compilation and binary consumer qualification run in CI. +If compilation fails, reproduce in the private repository to inspect diagnostics. +Do not add public compiler logs to troubleshoot a private build. + +Automation in this repository is AGPL-3.0-only. SDK components retain their own +licences and required notices; this repository's licence does not relicense them. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..3efdd67 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,15 @@ + +# Reporting a suspected source exposure + +Contact a RakuenSoftware repository administrator privately. Do not include +suspected private source or credentials in a public issue, pull request, comment +or attachment. Identify the release/run URL and affected file paths privately. + +Administrators should disable the build workflow and revoke its read-only source +credential while investigating. Quarantine affected public artifacts and examine +repository history, run logs and release assets privately. Removing a download +does not revoke copies already obtained. Preserve licence notices on binaries. + +Only trusted maintainers may change publication workflows or dispatch builds. +Review changes to the file allowlist, credential permissions, checkout paths, +log handling and artifact paths as changes to the source publication boundary. diff --git a/release.py b/release.py new file mode 100644 index 0000000..ba93139 --- /dev/null +++ b/release.py @@ -0,0 +1,203 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: AGPL-3.0-only +"""Own the public repository and binary SDK publication boundary.""" +import argparse +import hashlib +import io +import json +from pathlib import Path, PurePosixPath +import re +import shutil +import stat +import struct +import subprocess +import sys +import zipfile + + +class SDKRelease: + TARGETS = {"linux-x64": ("linux", "x86_64", "so"), + "windows-x64": ("windows", "x86_64", "dll"), + "macos-universal": ("macos", "universal", "dylib")} + PUBLIC_FILES = {"LICENSE", "README.md", "SECURITY.md", "AGENTS.md", ".gitignore", "release.py", + "test_release.py", ".github/workflows/build.yml", ".github/workflows/audit.yml"} + FORBIDDEN = {".c", ".cpp", ".cc", ".cxx", ".h", ".hpp", ".hxx", ".gd", ".gdshader", ".gdshaderinc", + ".glsl", ".hlsl", ".shader", ".pdb", ".snupkg", ".csproj", ".sln", ".map", ".py", ".sh", ".ps1", ".js", ".ts", ".rs", ".log"} + SOURCE_TEXT = re.compile(rb'(?m)^\s*(?:namespace\s+Wol\.Engine\b|(?:public|internal)\s+(?:(?:partial|sealed|static|abstract)\s+)*(?:class|struct|interface|record)\s+\w+|shader_type\s+\w+\s*;|void\s+(?:vertex|fragment)\s*\(|#include\s*[<"])') + SECRET_TEXT = re.compile(rb'(?:-----BEGIN (?:OPENSSH |RSA |EC )?PRIVATE KEY-----|github_pat_[A-Za-z0-9_]{20,}|gh[pousr]_[A-Za-z0-9_]{20,})') + + @classmethod + def check_repository(cls, root): + root = Path(root) + paths = set(subprocess.check_output(["git", "ls-files", "-z"], cwd=root).decode().split("\0")) - {""} + revisions = subprocess.check_output(["git", "rev-list", "--all"], cwd=root).decode().splitlines() + for revision in revisions: + paths.update(subprocess.check_output(["git", "ls-tree", "-r", "--name-only", "-z", revision], cwd=root).decode().split("\0")) + if paths - cls.PUBLIC_FILES - {""}: + raise ValueError("Repository contains an unapproved path") + blobs = set() + for revision in revisions: + for row in subprocess.check_output(["git", "ls-tree", "-r", revision], cwd=root).splitlines(): + metadata, _ = row.split(b"\t", 1) + mode, kind, oid = metadata.split() + if kind != b"blob" or mode not in (b"100644", b"100755"): + raise ValueError("Repository contains a symlink or submodule") + blobs.add(oid.decode()) + for oid in blobs: + data = subprocess.check_output(["git", "cat-file", "blob", oid], cwd=root) + if len(data) > 100_000 or cls.SOURCE_TEXT.search(data) or cls.SECRET_TEXT.search(data): + raise ValueError("Repository content failed the publication policy") + for name in paths - {""}: + path = root / name + if path.exists() and (path.is_symlink() or cls.SOURCE_TEXT.search(path.read_bytes()) or cls.SECRET_TEXT.search(path.read_bytes())): + raise ValueError("Working tree failed the publication policy") + + @classmethod + def check_sdk(cls, archive, commit, target): + if not re.fullmatch(r"[0-9a-f]{40}", commit) or target not in cls.TARGETS: + raise ValueError("Invalid SDK identity") + archive = Path(archive) + if archive.name != f"wol-engine-{commit}-{target}.zip": + raise ValueError("Unexpected SDK archive name") + sidecar = archive.with_suffix(".zip.sha256").read_bytes() + checksum = sidecar[:64].decode("ascii") + if not re.fullmatch(r"[0-9a-f]{64}", checksum) or sidecar != (checksum + " " + archive.name + "\n").encode("ascii"): + raise ValueError("Unexpected checksum sidecar content") + with archive.open("rb") as stream: + if hashlib.file_digest(stream, "sha256").hexdigest() != checksum: + raise ValueError("SDK archive checksum mismatch") + native_platform, arch, extension = cls.TARGETS[target] + required = {"WolEngine.props", "GodotApi.props", "native/spatial.gdextension", + f"native/bin/libspatial.{native_platform}.template_release.{arch}.{extension}", + "managed/Debug/WolEngine.dll", "managed/Release/WolEngine.dll"} + editor = {"linux-x64": "editor/Godot_v4.7.2-stable_mono_linux.x86_64", + "windows-x64": "editor/Godot_v4.7.2-stable_mono_win64.exe", + "macos-universal": "editor/Godot.app/Contents/MacOS/Godot"}[target] + required.add(editor) + with zipfile.ZipFile(archive) as packed: + members = packed.infolist() + names = [m.filename for m in members] + if len(names) != len(set(names)) or len(names) > 4000 or sum(m.file_size for m in members) > 4 * 1024**3: + raise ValueError("Invalid SDK archive structure") + manifest = json.loads(packed.read("RUNTIME.json")) + if set(manifest) != {"schema", "target", "godot", "commit", "release", "editor", "files"}: + raise ValueError("Unexpected SDK manifest fields") + if manifest.get("schema") != 1 or manifest.get("commit") != commit or manifest.get("target") != target or manifest.get("godot") != "4.7.2": + raise ValueError("SDK manifest identity mismatch") + expected_release = f"https://github.com/RakuenSoftware/wol-engine-release/releases/tag/runtime-{commit}" + if manifest.get("release") != expected_release: + raise ValueError("SDK release origin mismatch") + files = manifest["files"] + if set(names) != set(files) | {"RUNTIME.json"} or not required <= set(files) or manifest.get("editor") != editor: + raise ValueError("SDK file manifest mismatch") + for member in members: + name = member.filename + path = PurePosixPath(name) + if path.is_absolute() or ".." in path.parts or "\\" in name or ":" in name or path.as_posix() != name or member.is_dir() or stat.S_ISLNK(member.external_attr >> 16): + raise ValueError("Unsafe SDK member") + if name == "RUNTIME.json": + continue + data = packed.read(member) + if hashlib.sha256(data).hexdigest() != files[name]: + raise ValueError("SDK member checksum mismatch") + suffix = path.suffix.lower() + if suffix in cls.FORBIDDEN or cls.SECRET_TEXT.search(data): + raise ValueError("Implementation, diagnostics or credentials in SDK") + allowed = name in required + allowed |= bool(re.fullmatch(r"\.dependencies/godot-api/api/(Debug|Release)/GodotSharp(?:Editor)?\.dll", name)) + allowed |= bool(re.fullmatch(r"licenses/[A-Za-z0-9_.-]+\.(?:txt|md)", name)) + allowed |= name == "runtime/display/graphics_settings.tscn" + allowed |= bool(re.fullmatch(r"runtime/branding/(?:wol_icon\.(?:png|svg)|wol_splash\.(?:png|svg)|wol\.svg|README\.md)", name)) + allowed |= name.startswith("runtime/") and (name.endswith(".cs") or name.endswith(".cs.uid") or name == "runtime/display/graphics_settings.tscn.uid") + if name.startswith("editor/"): + allowed |= suffix in {".dll", ".exe", ".json", ".nupkg", ".icns", ".car", ".plist", ".strings"} + allowed |= name in {"editor/Godot_v4.7.2-stable_mono_linux.x86_64", "editor/Godot.app/Contents/MacOS/Godot", "editor/Godot.app/Contents/PkgInfo", "editor/Godot.app/Contents/CodeResources", "editor/Godot.app/Contents/_CodeSignature/CodeResources"} + if suffix == ".nupkg": + allowed = bool(re.search(r"/GodotSharp/Tools/nupkgs/(?:GodotSharp(?:Editor)?|Godot\.NET\.Sdk|Godot\.SourceGenerators)\.4\.7\.2\.nupkg$", name)) + if name == "editor/GodotSharp/Tools/GodotTools.OpenVisualStudio": + allowed = target == "windows-x64" and data.startswith((b"MZ", b"\x7fELF")) + if not allowed: + raise ValueError("Unapproved SDK file") + if suffix == ".nupkg": + with zipfile.ZipFile(io.BytesIO(data)) as nested: + for entry in nested.infolist(): + inner = PurePosixPath(entry.filename) + if inner.is_absolute() or ".." in inner.parts or "\\" in entry.filename or stat.S_ISLNK(entry.external_attr >> 16): + raise ValueError("Unsafe dependency package") + content = nested.read(entry) + if inner.suffix.lower() in {".pdb", ".gdshader", ".gdshaderinc", ".glsl", ".hlsl"} or cls.SECRET_TEXT.search(content) or re.search(rb"namespace\s+Wol\.Engine\b", content): + raise ValueError("Private implementation or symbols in dependency package") + if suffix == ".cs" and data.strip(): + raise ValueError("Nonempty C# implementation in SDK") + if suffix in {".dll", ".exe"} and not data.startswith(b"MZ"): + raise ValueError("Invalid PE binary") + if name.startswith("managed/"): + # Owned assemblies must not embed portable PDBs or CodeView paths. + pe = struct.unpack_from("', 'GodotApi.props': b'', 'native/spatial.gdextension': b'[configuration]', + f'native/bin/libspatial.{platform}.template_release.{arch}.{extension}': native, + 'managed/Debug/WolEngine.dll': managed or self.pe, 'managed/Release/WolEngine.dll': managed or self.pe, + editor: native, 'runtime/PublicIdentity.cs': b'\n'} + files.update(extra or {}) + manifest = {'schema': 1, 'godot': '4.7.2', 'target': target, 'commit': self.commit, 'editor': editor, + 'release': f'https://github.com/RakuenSoftware/wol-engine-release/releases/tag/runtime-{self.commit}', + 'files': {name: hashlib.sha256(data).hexdigest() for name, data in files.items()}} + manifest.update(manifest_extra or {}) + archive = self.root / f'wol-engine-{self.commit}-{target}.zip' + with zipfile.ZipFile(archive, 'w') as packed: + for name, data in files.items(): packed.writestr(name, data) + packed.writestr('RUNTIME.json', json.dumps(manifest)) + archive.with_suffix('.zip.sha256').write_text(hashlib.sha256(archive.read_bytes()).hexdigest() + ' ' + archive.name + '\n') + return archive + + def test_native_targets_and_empty_identity_stubs(self): + for target in SDKRelease.TARGETS: + with self.subTest(target=target): + SDKRelease.check_sdk(self.sdk(target), self.commit, target) + + def test_source_diagnostics_disguises_and_traversal_are_rejected(self): + cases = [('runtime/Engine.cs', b'namespace Wol.Engine; public class Secret {}'), + ('runtime/hidden.gdshader', b'shader_type spatial;'), + ('runtime/Engine.pdb', b'symbols'), ('logs/build.log', b'compiler context'), + ('.git/config', b'private repository configuration'), ('../../Engine.cs', b'source'), + ('runtime/branding/README.md', b'namespace Wol.Engine;'), + ('native/bin/extra.dll', self.pe), ('runtime/Engine.glsl', b'void fragment() {}')] + for name, data in cases: + with self.subTest(name=name), self.assertRaises(ValueError): + SDKRelease.check_sdk(self.sdk(extra={name: data}), self.commit, 'linux-x64') + + def test_embedded_symbols_and_private_source_in_dependency_packages_are_rejected(self): + pe = bytearray(self.pe) + bytearray(128) + struct.pack_into('