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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 112 additions & 0 deletions .github/workflows/build-appsite-release-bundle.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# Produces a portable verified release ZIP for the site owner when the
# labeled self-hosted appsite-deploy runner is unavailable.
# It NEVER writes to a VPS, changes DNS, or starts publication.
name: Prepare app site owner-only VPS release ZIP

on:
pull_request:
branches: [main]
paths:
- 'index.html'
- 'apps.html'
- 'robots.txt'
- 'sitemap.xml'
- 'press/**'
- 'guides/**'
- 'support/**'
- 'privacy-policy/**'
- 'scripts/preflight_app_discovery.py'
- 'scripts/publish_app_discovery.sh'
- 'scripts/publish_stale_policy_pages.sh'
- 'scripts/test_preflight_app_discovery.py'
- 'scripts/test_press_kit.py'
- 'scripts/test_publish_app_discovery_staging.py'
- 'scripts/build_site_release_bundle.py'
- 'scripts/test_site_release_bundle.py'
- '.github/workflows/build-appsite-release-bundle.yml'
push:
branches: [main]
paths:
- 'index.html'
- 'apps.html'
- 'robots.txt'
- 'sitemap.xml'
- 'press/**'
- 'guides/**'
- 'support/**'
- 'privacy-policy/**'
- 'scripts/preflight_app_discovery.py'
- 'scripts/publish_app_discovery.sh'
- 'scripts/publish_stale_policy_pages.sh'
- 'scripts/test_preflight_app_discovery.py'
- 'scripts/test_press_kit.py'
- 'scripts/test_publish_app_discovery_staging.py'
- 'scripts/build_site_release_bundle.py'
- 'scripts/test_site_release_bundle.py'
- '.github/workflows/build-appsite-release-bundle.yml'
workflow_dispatch:

permissions:
contents: read

jobs:
bundle:
runs-on: ubuntu-latest
timeout-minutes: 12
steps:
- name: Check out exact release source
uses: actions/checkout@v4
with:
persist-credentials: false
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Verify publisher source and five localized press pages
run: |
python3 scripts/preflight_app_discovery.py
python3 -m unittest \
scripts.test_preflight_app_discovery \
scripts.test_press_kit \
scripts.test_publish_app_discovery_staging \
scripts.test_site_release_bundle -v
- name: Create source-only ZIP (no network or VPS access)
shell: bash
run: |
set -euo pipefail
mkdir -p "$RUNNER_TEMP/appsite"
python3 scripts/build_site_release_bundle.py \
--output "$RUNNER_TEMP/appsite/appsite-vps-source-${GITHUB_SHA:0:12}.zip"
python3 - <<'PY'
from pathlib import Path
from zipfile import ZipFile
import os
folder = Path(os.environ['RUNNER_TEMP']) / 'appsite'
archives = list(folder.glob('appsite-vps-source-*.zip'))
assert len(archives) == 1, 'one ZIP per verified source checkout'
with ZipFile(archives[0]) as z:
names = z.namelist()
assert len(names) == 46, f'44 site documents + hash manifest + instructions; got {len(names)}'
assert z.testzip() is None
assert all(n.startswith('site/') or n in ('SHA256SUMS.txt', 'DEPLOY_README.txt') for n in names)
PY
- name: Save reviewed release ZIP for the owner (main only)
if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
uses: actions/upload-artifact@v4
with:
name: appsite-vps-source-${{ github.sha }}
path: ${{ runner.temp }}/appsite/*.zip
if-no-files-found: error
retention-days: 14
- name: Clarify publication status
if: always()
shell: bash
run: |
{
echo '## Source bundle — this is NOT a production deployment'
echo ''
echo '- Existing VPS release requires explicit owner approval on the separate **publish to VPS** workflow.'
echo '- Bundle contains only existing allowlisted public app pages and approved policy HTML.'
echo '- Public URLs remain unverified until the owner applies and reruns the live smoke test.'
echo '- No SSH, domain transfer, indexing submission, social post, or traffic event is performed.'
} >> "$GITHUB_STEP_SUMMARY"
161 changes: 161 additions & 0 deletions scripts/build_site_release_bundle.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
#!/usr/bin/env python3
"""Build a portable, read-only appdevelopsk.com VPS release bundle.

This script packages ONLY the exact files allowed by the existing owner-only
app discovery and privacy-policy publishing scripts. It never touches a VPS,
changes a GitHub branch, sends events, or requires SSH/network access.

Usage:
python3 scripts/build_site_release_bundle.py --output /tmp/appsite-release.zip
"""
import argparse
import hashlib
import json
import re
import shlex
import sys
import zipfile
from pathlib import Path, PurePosixPath

ROOT = Path(__file__).resolve().parents[1]
APP_PUBLISHER = "scripts/publish_app_discovery.sh"
POLICY_PUBLISHER = "scripts/publish_stale_policy_pages.sh"
PRESS = {
"press/index.html",
"press/es/index.html",
"press/pt-br/index.html",
"press/ja/index.html",
"press/id/index.html",
}
MAX_FILE_BYTES = 5_000_000
MAX_TOTAL_BYTES = 25_000_000
README = """APP SITE — OWNER-CONTROLLED RELEASE BUNDLE

This ZIP is source-only. Creating or downloading it does NOT publish a site.
The root-level site/ directory preserves paths relative to the VPS web root.
SHA256SUMS.txt verifies the exact bytes included; it is not a deployed SHA.

PREFERRED RELEASE:
GitHub Actions -> publish to VPS -> main -> mode=dry-run; review.
The owner may then authorize a separate mode=apply on the self-hosted VPS
runner. Do NOT use this bundle to bypass a failed source preflight.

ALTERNATIVE WHEN THE SELF-HOSTED RUNNER IS UNAVAILABLE:
1. Extract this ZIP into a private temporary directory on a trusted computer.
2. From that extracted directory, run:
sha256sum -c SHA256SUMS.txt
3. Owner verifies the SSH host/user, web-root path and exact file list.
4. Owner uploads only its site/ contents with their relative directories:
rsync -rlcv --itemize-changes -- site/ USER@VPS:/var/www/html/
Do not add --delete. Do not blindly copy files to an unverified host.
5. Run source post-release read-only probes:
bash scripts/check_app_discovery_live.sh
bash scripts/publish_stale_policy_pages.sh --check-live
6. Confirm all five /press/ locale routes return HTTP 200 on
https://appdevelopsk.com and the expected canonical/hreflang, then
check the public app catalog and support landing metadata.

This includes 27 app-discovery documents and 17 approved policy documents
from current source. It is NOT a complete VPS backup, nginx configuration,
database migration, browser test, app-store release, or SEO indexing proof.
"""


def shell_array(text, name):
if name == "files":
pattern = r"(?m)^files=\(([^)\n]*)\)\s*$"
elif name == "slugs":
pattern = r"(?ms)^slugs=\(\s*(.*?)^\)\s*$"
else:
raise ValueError("unsupported manifest variable")
found = re.findall(pattern, text)
if len(found) != 1:
raise ValueError("expected exactly one explicit " + name + "=(...) manifest")
parts = shlex.split(found[0], comments=True)
if not parts or len(parts) != len(set(parts)):
raise ValueError(name + " manifest is empty or has duplicate entries")
return parts


def release_manifest(root=ROOT):
scripts = root / "scripts"
apps = shell_array((scripts / "publish_app_discovery.sh").read_text(encoding="utf-8"), "files")
policies = shell_array((scripts / "publish_stale_policy_pages.sh").read_text(encoding="utf-8"), "slugs")
if len(apps) != 27 or len(policies) != 17:
raise ValueError("publisher manifest count changed; review before bundling")
if not PRESS.issubset(set(apps)):
raise ValueError("one or more of the five press routes are not in publisher manifest")
if not {"index.html", "apps.html", "sitemap.xml", "robots.txt",
"support/brain-burst/index.html", "support/debate-me/index.html"}.issubset(apps):
raise ValueError("critical app discovery/SEO pages missing from publisher manifest")
if any(not re.fullmatch(r"[a-z0-9-]+", slug) for slug in policies):
raise ValueError("unsafe privacy-policy slug")
files = apps + ["privacy-policy/" + slug + "/index.html" for slug in policies]
if len(files) != len(set(files)):
raise ValueError("publisher allowlists overlap")
total = 0
for filename in files:
path = PurePosixPath(filename)
if (path.is_absolute() or ".." in path.parts or "." in path.parts
or path.as_posix() != filename or "\\" in filename):
raise ValueError("unsafe release path: " + filename)
actual = root / filename
if (not actual.is_file() or actual.is_symlink()
or not actual.resolve().is_relative_to(root.resolve())):
raise ValueError("missing or unsafe source file: " + filename)
size = actual.stat().st_size
if size <= 0 or size > MAX_FILE_BYTES:
raise ValueError("missing, empty or oversized source file: " + filename)
total += size
if total > MAX_TOTAL_BYTES:
raise ValueError("release is too large for the reviewed source-only bundle")
return files


def zip_bytes(root, files, out):
out.parent.mkdir(parents=True, exist_ok=True)
checksum_rows = []
with zipfile.ZipFile(out, "w", compression=zipfile.ZIP_DEFLATED,
compresslevel=6) as archive:
for filename in sorted(files):
content = (root / filename).read_bytes()
source = "site/" + filename
archive.writestr(source, content)
checksum_rows.append(hashlib.sha256(content).hexdigest() + " " + source)
archive.writestr("SHA256SUMS.txt", "\n".join(checksum_rows) + "\n")
archive.writestr("DEPLOY_README.txt", README)
return hashlib.sha256(out.read_bytes()).hexdigest()


def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--output", required=True, type=Path,
help="Local output .zip path; never a production web root")
args = parser.parse_args()
if args.output.suffix.lower() != ".zip":
parser.error("--output must be a .zip filename")
output = args.output.resolve()
if output.is_relative_to(ROOT):
parser.error("do not create ZIP anywhere inside the public website source tree")
try:
files = release_manifest(ROOT)
digest = zip_bytes(ROOT, files, output)
except (OSError, ValueError, zipfile.BadZipFile) as exc:
print(type(exc).__name__ + ": " + str(exc), file=sys.stderr)
return 1
print(json.dumps({
"status": "source_bundle_created_not_deployed",
"output": str(output),
"sha256": digest,
"appDiscoveryFiles": 27,
"policyFiles": 17,
"totalFiles": len(files),
"pressRoutes": sorted(PRESS),
"publishesToVps": False,
"urlIndexingRequested": False,
}, indent=2))
return 0


if __name__ == "__main__":
sys.exit(main())
91 changes: 91 additions & 0 deletions scripts/test_site_release_bundle.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
"""Offline tests for owner-controlled, no-credentials VPS release ZIP."""
import hashlib
import re
import shutil
import tempfile
import unittest
import zipfile
from pathlib import Path

from scripts import build_site_release_bundle as bundle


class AppsiteReleaseBundleTests(unittest.TestCase):
def test_exact_publish_manifest_has_five_press_and_seventeen_policies(self):
files = bundle.release_manifest()
self.assertEqual(len(files), 44)
self.assertEqual(len(files), len(set(files)))
self.assertTrue(bundle.PRESS.issubset(files))
self.assertEqual(sum(x.startswith("privacy-policy/") for x in files), 17)
self.assertNotIn(".env", "\n".join(files))
self.assertFalse(any(".." in Path(x).parts or "." in Path(x).parts for x in files))

def test_zip_contains_exact_site_payload_with_matching_checksum_file(self):
files = bundle.release_manifest()
with tempfile.TemporaryDirectory() as tmp:
output = Path(tmp) / "appsite.zip"
digest = bundle.zip_bytes(bundle.ROOT, files, output)
self.assertEqual(digest, hashlib.sha256(output.read_bytes()).hexdigest())
with zipfile.ZipFile(output) as z:
expected = {"site/" + f for f in files} | {"SHA256SUMS.txt", "DEPLOY_README.txt"}
self.assertEqual(set(z.namelist()), expected)
self.assertEqual(z.testzip(), None)
hashes = {}
for line in z.read("SHA256SUMS.txt").decode().splitlines():
checksum, name = line.split(" ", 1)
self.assertNotIn(name, hashes)
hashes[name] = checksum
self.assertEqual(set(hashes), {"site/" + f for f in files})
for name, checksum in hashes.items():
with self.subTest(name=name):
self.assertEqual(hashlib.sha256(z.read(name)).hexdigest(), checksum)
self.assertEqual(z.read(name), (bundle.ROOT / name.removeprefix("site/")).read_bytes())
readme = z.read("DEPLOY_README.txt").decode()
self.assertIn("source-only", readme)
self.assertIn("mode=dry-run", readme)
self.assertIn("mode=apply", readme)
self.assertIn("Do not add --delete", readme)

def test_publisher_slug_path_traversal_fails_closed(self):
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp)
(root / "scripts").mkdir()
for filename in (bundle.APP_PUBLISHER, bundle.POLICY_PUBLISHER):
shutil.copy2(bundle.ROOT / filename, root / filename)
old = (root / bundle.POLICY_PUBLISHER).read_text()
self.assertIn("battery-charging-map", old)
(root / bundle.POLICY_PUBLISHER).write_text(
old.replace("battery-charging-map", "../outside", 1))
with self.assertRaises(ValueError):
bundle.release_manifest(root)

def test_any_missing_press_route_fails_before_archive(self):
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp)
(root / "scripts").mkdir()
for filename in (bundle.APP_PUBLISHER, bundle.POLICY_PUBLISHER):
shutil.copy2(bundle.ROOT / filename, root / filename)
script = root / bundle.APP_PUBLISHER
text = script.read_text()
self.assertIn("press/id/index.html", text)
script.write_text(text.replace("press/id/index.html",
"press/nonexistent/index.html", 1))
with self.assertRaises(ValueError):
bundle.release_manifest(root)

def test_archive_builder_never_needs_vps_or_credentials(self):
source = (bundle.ROOT / "scripts/build_site_release_bundle.py").read_text()
# Deployment instructions (README) legitimately mention SSH and rsync;
# only the executable packaging code must be free of network commands.
executable = source.split("def shell_array", 1)[1]
self.assertNotIn("subprocess", executable)
self.assertNotIn("urllib.request", executable)
self.assertNotIn("ssh ", executable)
self.assertNotIn("rsync -", executable)
self.assertNotIn("os.system", executable)
self.assertNotIn("eval(", executable)
self.assertIn("publishesToVps", executable)


if __name__ == "__main__":
unittest.main()
Loading