codex-workspace-bootstrap 0.7.0__tar.gz → 0.8.0__tar.gz

{codex_workspace_bootstrap-0.7.0/src/codex_workspace_bootstrap.egg-info → codex_workspace_bootstrap-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-workspace-bootstrap
-Version: 0.7.0
+Version: 0.8.0
 Summary: Preflight AI coding repositories before Codex, Copilot, Cline, Claude, Gemini, Continue, or Cursor touches them.
 Author: kohli217
 License: MIT
@@ -40,10 +40,23 @@ Dynamic: license-file
 
 Windows-first. Local by default. CI-friendly. Designed for repositories used with Codex, Copilot, Cline, Claude Code, Gemini CLI, Continue, Cursor, and similar coding agents.
 
-[日本語ガイド](docs/README.ja.md) · [Examples](docs/EXAMPLES.md) · [GitHub Action](docs/GITHUB_ACTION.md) · [Roadmap](docs/ROADMAP.md) · [Releases](https://github.com/kohli217/codex-workspace-bootstrap/releases)
+[日本語ガイド](docs/README.ja.md) · [Examples](docs/EXAMPLES.md) · [GitHub Action](docs/GITHUB_ACTION.md) · [GitHub App](docs/GITHUB_APP.md) · [Free GitHub App deployment](deploy/cloudflare/README.md) · [Cloud Run alternative](deploy/cloudrun/README.md) · [Integration contract](docs/INTEGRATIONS.md) · [Roadmap](docs/ROADMAP.md) · [Releases](https://github.com/kohli217/codex-workspace-bootstrap/releases)
 
 > Community-maintained project. Not an official OpenAI product and not affiliated with OpenAI.
 
+## Why add this to your repository?
+
+AI coding agents can move fast, but they can also follow stale or conflicting repository instructions. `codex-workspace-bootstrap` adds one repeatable check before that happens.
+
+| Common failure | What `cwb` does |
+| --- | --- |
+| One instruction says `npm`, another says `pnpm` | Flags the mismatch before an agent edits the repository. |
+| An instruction tells the agent to run a test/lint script that does not exist | Reports the invalid command instead of letting the mistake reach the agent. |
+| A risky file such as `.env.production` is Git-tracked | Surfaces it as a blocking risk signal without printing its contents. |
+| The repository is still missing important readiness pieces | `cwb preflight . --require-ready` can fail CI until the repository reaches `READY`. |
+
+It is local-first: the core preflight does not send repository contents to a remote AI service.
+
 ## The 20-second demo
 
 ```powershell
@@ -219,6 +232,14 @@ cwb preflight . --require-ready
 
 Use `--require-ready` when CI should reject both `NEEDS ATTENTION` and `BLOCKED`, including missing repository-wide AI instructions or essential repository markers.
 
+For a remote service such as a GitHub App, skip host-machine tool availability checks while keeping repository evidence, Git tracking, risk filenames, and instruction integrity checks:
+
+```powershell
+cwb preflight . --repository-only
+```
+
+This prevents a remote scanner from reporting the scanner host's Node.js, package-manager, WSL, PowerShell, or Codex availability as if it belonged to the inspected repository.
+
 ### Detailed audit
 
 ```powershell
@@ -267,7 +288,7 @@ The reusable Action is published on GitHub Marketplace.
 - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
   with:
     python-version: "3.13"
-- uses: kohli217/codex-workspace-bootstrap@v0.7.0
+- uses: kohli217/codex-workspace-bootstrap@v0.8.0
   with:
     path: .
     strict: "true"
@@ -281,6 +302,32 @@ See [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md).
 
 Read-only evaluations against real public repositories are documented in [docs/PUBLIC_REPO_EVALUATIONS.md](docs/PUBLIC_REPO_EVALUATIONS.md). They are reproducible technical evaluations, not claims of third-party adoption.
 
+## GitHub App
+
+For public OSS repositories, CWB can also run as a self-hosted GitHub App. A verified `push` or `pull_request` event triggers repository-only preflight against the exact event revision and publishes a **CWB Preflight** Check Run on that commit.
+
+The preferred zero-cost development deployment uses:
+
+```text
+GitHub App
+  -> Cloudflare Worker + Queue (Free)
+  -> GitHub Actions in this public repository
+  -> short-lived repository-scoped installation token
+  -> CWB Preflight Check
+```
+
+This path does not require a Google Cloud billing account. It is intentionally **public-repository-only**: private-repository events are rejected before they are queued into the public Actions worker.
+
+The App keeps the minimum repository permissions documented by the project: Checks read/write, Contents read-only, and Pull requests read-only.
+
+See [docs/GITHUB_APP.md](docs/GITHUB_APP.md) for the integration contract and [deploy/cloudflare/README.md](deploy/cloudflare/README.md) for the completely free development deployment.
+
+## Integration boundary
+
+The CLI, reusable GitHub Action, GitHub App, and future AI-agent skills share one preflight engine and one policy evaluator. Machine-readable reports declare a schema version so integrations can detect incompatible changes instead of silently drifting.
+
+See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md). The minimum GitHub App permissions and webhook subscriptions are defined in [docs/GITHUB_APP.md](docs/GITHUB_APP.md) and mirrored by code-level regression tests.
+
 ## Where it fits
 
 This project is a **preflight layer**, not an AI coding agent and not a deep security scanner.
@@ -334,7 +381,7 @@ py -m pip install codex-workspace-bootstrap
 Pinned GitHub release artifact:
 
 ```powershell
-py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.7.0/codex_workspace_bootstrap-0.7.0-py3-none-any.whl"
+py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.8.0/codex_workspace_bootstrap-0.8.0-py3-none-any.whl"
 ```
 
 ## Development

{codex_workspace_bootstrap-0.7.0 → codex_workspace_bootstrap-0.8.0}/README.md

@@ -12,10 +12,23 @@
 
 Windows-first. Local by default. CI-friendly. Designed for repositories used with Codex, Copilot, Cline, Claude Code, Gemini CLI, Continue, Cursor, and similar coding agents.
 
-[日本語ガイド](docs/README.ja.md) · [Examples](docs/EXAMPLES.md) · [GitHub Action](docs/GITHUB_ACTION.md) · [Roadmap](docs/ROADMAP.md) · [Releases](https://github.com/kohli217/codex-workspace-bootstrap/releases)
+[日本語ガイド](docs/README.ja.md) · [Examples](docs/EXAMPLES.md) · [GitHub Action](docs/GITHUB_ACTION.md) · [GitHub App](docs/GITHUB_APP.md) · [Free GitHub App deployment](deploy/cloudflare/README.md) · [Cloud Run alternative](deploy/cloudrun/README.md) · [Integration contract](docs/INTEGRATIONS.md) · [Roadmap](docs/ROADMAP.md) · [Releases](https://github.com/kohli217/codex-workspace-bootstrap/releases)
 
 > Community-maintained project. Not an official OpenAI product and not affiliated with OpenAI.
 
+## Why add this to your repository?
+
+AI coding agents can move fast, but they can also follow stale or conflicting repository instructions. `codex-workspace-bootstrap` adds one repeatable check before that happens.
+
+| Common failure | What `cwb` does |
+| --- | --- |
+| One instruction says `npm`, another says `pnpm` | Flags the mismatch before an agent edits the repository. |
+| An instruction tells the agent to run a test/lint script that does not exist | Reports the invalid command instead of letting the mistake reach the agent. |
+| A risky file such as `.env.production` is Git-tracked | Surfaces it as a blocking risk signal without printing its contents. |
+| The repository is still missing important readiness pieces | `cwb preflight . --require-ready` can fail CI until the repository reaches `READY`. |
+
+It is local-first: the core preflight does not send repository contents to a remote AI service.
+
 ## The 20-second demo
 
 ```powershell
@@ -191,6 +204,14 @@ cwb preflight . --require-ready
 
 Use `--require-ready` when CI should reject both `NEEDS ATTENTION` and `BLOCKED`, including missing repository-wide AI instructions or essential repository markers.
 
+For a remote service such as a GitHub App, skip host-machine tool availability checks while keeping repository evidence, Git tracking, risk filenames, and instruction integrity checks:
+
+```powershell
+cwb preflight . --repository-only
+```
+
+This prevents a remote scanner from reporting the scanner host's Node.js, package-manager, WSL, PowerShell, or Codex availability as if it belonged to the inspected repository.
+
 ### Detailed audit
 
 ```powershell
@@ -239,7 +260,7 @@ The reusable Action is published on GitHub Marketplace.
 - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
   with:
     python-version: "3.13"
-- uses: kohli217/codex-workspace-bootstrap@v0.7.0
+- uses: kohli217/codex-workspace-bootstrap@v0.8.0
   with:
     path: .
     strict: "true"
@@ -253,6 +274,32 @@ See [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md).
 
 Read-only evaluations against real public repositories are documented in [docs/PUBLIC_REPO_EVALUATIONS.md](docs/PUBLIC_REPO_EVALUATIONS.md). They are reproducible technical evaluations, not claims of third-party adoption.
 
+## GitHub App
+
+For public OSS repositories, CWB can also run as a self-hosted GitHub App. A verified `push` or `pull_request` event triggers repository-only preflight against the exact event revision and publishes a **CWB Preflight** Check Run on that commit.
+
+The preferred zero-cost development deployment uses:
+
+```text
+GitHub App
+  -> Cloudflare Worker + Queue (Free)
+  -> GitHub Actions in this public repository
+  -> short-lived repository-scoped installation token
+  -> CWB Preflight Check
+```
+
+This path does not require a Google Cloud billing account. It is intentionally **public-repository-only**: private-repository events are rejected before they are queued into the public Actions worker.
+
+The App keeps the minimum repository permissions documented by the project: Checks read/write, Contents read-only, and Pull requests read-only.
+
+See [docs/GITHUB_APP.md](docs/GITHUB_APP.md) for the integration contract and [deploy/cloudflare/README.md](deploy/cloudflare/README.md) for the completely free development deployment.
+
+## Integration boundary
+
+The CLI, reusable GitHub Action, GitHub App, and future AI-agent skills share one preflight engine and one policy evaluator. Machine-readable reports declare a schema version so integrations can detect incompatible changes instead of silently drifting.
+
+See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md). The minimum GitHub App permissions and webhook subscriptions are defined in [docs/GITHUB_APP.md](docs/GITHUB_APP.md) and mirrored by code-level regression tests.
+
 ## Where it fits
 
 This project is a **preflight layer**, not an AI coding agent and not a deep security scanner.
@@ -306,7 +353,7 @@ py -m pip install codex-workspace-bootstrap
 Pinned GitHub release artifact:
 
 ```powershell
-py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.7.0/codex_workspace_bootstrap-0.7.0-py3-none-any.whl"
+py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.8.0/codex_workspace_bootstrap-0.8.0-py3-none-any.whl"
 ```
 
 ## Development

{codex_workspace_bootstrap-0.7.0 → codex_workspace_bootstrap-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-workspace-bootstrap"
-version = "0.7.0"
+version = "0.8.0"
 description = "Preflight AI coding repositories before Codex, Copilot, Cline, Claude, Gemini, Continue, or Cursor touches them."
 readme = "README.md"
 requires-python = ">=3.10"

{codex_workspace_bootstrap-0.7.0 → codex_workspace_bootstrap-0.8.0}/src/codex_workspace_bootstrap/__init__.py

@@ -1,3 +1,3 @@
 """codex-workspace-bootstrap package."""
 
-__version__ = "0.7.0"
+__version__ = "0.8.0"

{codex_workspace_bootstrap-0.7.0 → codex_workspace_bootstrap-0.8.0}/src/codex_workspace_bootstrap/audit.py

@@ -194,7 +194,7 @@ def _preview(paths: list[str], limit: int = 8) -> str:
     return f"{visible}{suffix}"
 
 
-def audit_repository(root: Path) -> list[Check]:
+def audit_repository(root: Path, *, include_local_toolchain: bool = True) -> list[Check]:
     root = root.resolve()
     checks: list[Check] = []
 
@@ -285,8 +285,9 @@ def audit_repository(root: Path) -> list[Check]:
         )
     )
 
-    for label, command in COMMON_TOOLS:
-        checks.append(_tool_check(label, command))
+    if include_local_toolchain:
+        for label, command in COMMON_TOOLS:
+            checks.append(_tool_check(label, command))
 
     if (root / "package.json").is_file() and not (root / "package.json").is_symlink():
         managers = detect_node_package_managers(root)
@@ -300,9 +301,10 @@ def audit_repository(root: Path) -> list[Check]:
                         + ", ".join(sorted(managers)),
                     )
                 )
-            for manager in sorted(managers):
-                command = NODE_PACKAGE_MANAGER_COMMANDS[manager]
-                checks.append(_tool_check(manager, command))
+            if include_local_toolchain:
+                for manager in sorted(managers):
+                    command = NODE_PACKAGE_MANAGER_COMMANDS[manager]
+                    checks.append(_tool_check(manager, command))
         else:
             checks.append(
                 Check(

{codex_workspace_bootstrap-0.7.0 → codex_workspace_bootstrap-0.8.0}/src/codex_workspace_bootstrap/cli.py

@@ -10,7 +10,7 @@ from .agents import generate_agents
 from .audit import audit_repository, summary
 from .doctor import doctor_findings
 from .fixes import apply_fix_plan, build_fix_plan
-from .preflight import build_preflight, render_markdown
+from .preflight import build_preflight, evaluate_preflight_policy, render_markdown
 from .sarif import checks_to_sarif, preflight_report_to_sarif
 
 
@@ -46,6 +46,11 @@ def _parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Return a non-zero exit code unless the preflight state is READY",
     )
+    preflight.add_argument(
+        "--repository-only",
+        action="store_true",
+        help="Skip local toolchain availability checks and evaluate repository evidence only",
+    )
 
     fix = sub.add_parser("fix", help="Preview safe repository-readiness fixes")
     fix.add_argument("path", nargs="?", default=".")
@@ -91,13 +96,17 @@ def _run_preflight(
     strict: bool,
     fail_on_integrity: bool,
     require_ready: bool,
+    repository_only: bool,
 ) -> int:
     root = Path(path).expanduser().resolve()
     if not root.exists() or not root.is_dir():
         print(f"error: repository path does not exist or is not a directory: {root}", file=sys.stderr)
         return 2
 
-    report = build_preflight(root)
+    report = build_preflight(
+        root,
+        include_local_toolchain=not repository_only,
+    )
 
     print("AI Repository Preflight")
     print(f"Repository: {root}")
@@ -163,13 +172,13 @@ def _run_preflight(
             "Preflight SARIF report",
         )
 
-    if strict and report["state"] == "BLOCKED":
-        return 1
-    if fail_on_integrity and report["instruction_summary"]["findings"]:
-        return 1
-    if require_ready and report["state"] != "READY":
-        return 1
-    return 0
+    decision = evaluate_preflight_policy(
+        report,
+        strict=strict,
+        fail_on_integrity=fail_on_integrity,
+        require_ready=require_ready,
+    )
+    return 0 if decision.passed else 1
 
 
 def _run_fix(path: str, apply: bool) -> int:
@@ -301,6 +310,7 @@ def main(argv: list[str] | None = None) -> int:
             args.strict,
             args.fail_on_integrity,
             args.require_ready,
+            args.repository_only,
         )
     if args.command == "fix":
         return _run_fix(args.path, args.apply)

codex_workspace_bootstrap-0.8.0/src/codex_workspace_bootstrap/integrations/__init__.py

@@ -0,0 +1 @@
+"""Delivery adapters built on the stable preflight integration contract."""

codex_workspace_bootstrap-0.8.0/src/codex_workspace_bootstrap/integrations/github.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from ..preflight import (
+    PREFLIGHT_REPORT_SCHEMA_VERSION,
+    PolicyDecision,
+    evaluate_preflight_policy,
+    render_markdown,
+)
+
+
+GitHubCheckConclusion = Literal["success", "neutral", "failure"]
+
+
+@dataclass(frozen=True)
+class GitHubCheckResult:
+    """GitHub Check Run fields derived from one preflight report."""
+
+    name: str
+    conclusion: GitHubCheckConclusion
+    title: str
+    summary: str
+    policy: PolicyDecision
+
+    def to_check_run_fields(self) -> dict[str, object]:
+        """Return Check Run fields that a caller can combine with head_sha."""
+
+        return {
+            "name": self.name,
+            "status": "completed",
+            "conclusion": self.conclusion,
+            "output": {
+                "title": self.title,
+                "summary": self.summary,
+            },
+        }
+
+
+def build_github_check(
+    report: dict[str, object],
+    *,
+    strict: bool = True,
+    fail_on_integrity: bool = False,
+    require_ready: bool = False,
+    name: str = "CWB Preflight",
+) -> GitHubCheckResult:
+    """Map a preflight report to a GitHub Check without making network calls."""
+
+    schema_version = report.get("schema_version")
+    if schema_version != PREFLIGHT_REPORT_SCHEMA_VERSION:
+        raise ValueError(
+            "unsupported preflight schema version: "
+            f"{schema_version!r}; expected {PREFLIGHT_REPORT_SCHEMA_VERSION}"
+        )
+
+    decision = evaluate_preflight_policy(
+        report,
+        strict=strict,
+        fail_on_integrity=fail_on_integrity,
+        require_ready=require_ready,
+    )
+    state = str(report.get("state", "UNKNOWN"))
+
+    if not decision.passed:
+        conclusion: GitHubCheckConclusion = "failure"
+    elif state == "READY":
+        conclusion = "success"
+    else:
+        conclusion = "neutral"
+
+    return GitHubCheckResult(
+        name=name,
+        conclusion=conclusion,
+        title=f"CWB preflight: {state}",
+        summary=render_markdown(report),
+        policy=decision,
+    )

codex_workspace_bootstrap-0.8.0/src/codex_workspace_bootstrap/integrations/github_actions_worker.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+import argparse
+import base64
+from dataclasses import asdict
+import json
+import os
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, urlparse
+from urllib.request import Request, urlopen
+
+from .github_runtime import (
+    GitHubAppRuntimeError,
+    GitHubScanResult,
+    execute_github_scan_with_token,
+)
+from .github_webhook import GitHubWebhookTarget
+
+
+_MAX_RESPONSE_BYTES = 1024 * 1024
+
+
+class GitHubActionsWorkerError(RuntimeError):
+    """Raised when the free GitHub Actions worker cannot authenticate or run."""
+
+
+def _base64url_decode(value: str) -> bytes:
+    if not value.strip():
+        raise GitHubActionsWorkerError("scan payload must not be empty")
+    padding = "=" * (-len(value) % 4)
+    try:
+        return base64.urlsafe_b64decode((value + padding).encode("ascii"))
+    except (ValueError, UnicodeEncodeError) as exc:
+        raise GitHubActionsWorkerError("scan payload is not valid base64url") from exc
+
+
+def decode_scan_payload(encoded: str) -> tuple[str, str, GitHubWebhookTarget]:
+    try:
+        payload = json.loads(_base64url_decode(encoded).decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise GitHubActionsWorkerError("scan payload is not valid UTF-8 JSON") from exc
+    if not isinstance(payload, dict):
+        raise GitHubActionsWorkerError("scan payload must be a JSON object")
+
+    delivery_id = payload.get("delivery_id")
+    broker_grant = payload.get("broker_grant")
+    target = payload.get("target")
+    if not isinstance(delivery_id, str) or not delivery_id.strip():
+        raise GitHubActionsWorkerError("scan payload is missing delivery_id")
+    if not isinstance(broker_grant, str) or not broker_grant.strip():
+        raise GitHubActionsWorkerError("scan payload is missing broker_grant")
+    if not isinstance(target, dict):
+        raise GitHubActionsWorkerError("scan payload is missing target")
+
+    event = target.get("event")
+    repository = target.get("repository")
+    head_sha = target.get("head_sha")
+    installation_id = target.get("installation_id")
+    if event not in {"push", "pull_request"}:
+        raise GitHubActionsWorkerError("scan payload has unsupported event")
+    if not isinstance(repository, str) or repository.count("/") != 1:
+        raise GitHubActionsWorkerError("scan payload has invalid repository")
+    if not isinstance(head_sha, str) or not head_sha.strip():
+        raise GitHubActionsWorkerError("scan payload is missing head_sha")
+    if (
+        isinstance(installation_id, bool)
+        or not isinstance(installation_id, int)
+        or installation_id <= 0
+    ):
+        raise GitHubActionsWorkerError("scan payload is missing installation_id")
+
+    number = target.get("pull_request_number")
+    if number is not None and (
+        isinstance(number, bool)
+        or not isinstance(number, int)
+        or number <= 0
+    ):
+        raise GitHubActionsWorkerError("scan payload has invalid pull_request_number")
+
+    def optional_text(name: str) -> str | None:
+        value = target.get(name)
+        if value is None:
+            return None
+        if not isinstance(value, str) or not value.strip():
+            raise GitHubActionsWorkerError(f"scan payload has invalid {name}")
+        return value
+
+    return delivery_id, broker_grant, GitHubWebhookTarget(
+        event=event,
+        repository=repository,
+        head_sha=head_sha,
+        installation_id=installation_id,
+        action=optional_text("action"),
+        pull_request_number=number,
+        merge_commit_sha=optional_text("merge_commit_sha"),
+        ref=optional_text("ref"),
+    )
+
+
+def _read_json_response(response) -> dict[str, object]:
+    raw = response.read(_MAX_RESPONSE_BYTES + 1)
+    if len(raw) > _MAX_RESPONSE_BYTES:
+        raise GitHubActionsWorkerError("remote response exceeded size limit")
+    try:
+        value = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise GitHubActionsWorkerError("remote service returned invalid JSON") from exc
+    if not isinstance(value, dict):
+        raise GitHubActionsWorkerError("remote service returned non-object JSON")
+    return value
+
+
+def request_actions_oidc_token(
+    *,
+    audience: str,
+    request_url: str | None = None,
+    request_token: str | None = None,
+) -> str:
+    url = request_url or os.environ.get("ACTIONS_ID_TOKEN_REQUEST_URL", "")
+    bearer = request_token or os.environ.get("ACTIONS_ID_TOKEN_REQUEST_TOKEN", "")
+    if not url or not bearer:
+        raise GitHubActionsWorkerError(
+            "GitHub Actions OIDC environment is unavailable; id-token: write is required"
+        )
+
+    separator = "&" if "?" in url else "?"
+    request = Request(
+        url + separator + urlencode({"audience": audience}),
+        headers={"Authorization": f"Bearer {bearer}"},
+        method="GET",
+    )
+    try:
+        with urlopen(request, timeout=20) as response:
+            body = _read_json_response(response)
+    except HTTPError as exc:
+        raise GitHubActionsWorkerError(
+            f"GitHub Actions OIDC request failed with HTTP {exc.code}"
+        ) from exc
+    except URLError as exc:
+        raise GitHubActionsWorkerError("GitHub Actions OIDC request failed") from exc
+
+    value = body.get("value")
+    if not isinstance(value, str) or not value.strip():
+        raise GitHubActionsWorkerError("GitHub Actions OIDC response is missing value")
+    return value
+
+
+def _validated_token_endpoint(endpoint: str) -> str:
+    parsed = urlparse(endpoint)
+    if (
+        parsed.scheme != "https"
+        or not parsed.netloc
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise GitHubActionsWorkerError(
+            "token endpoint must be an absolute HTTPS URL without credentials, query, or fragment"
+        )
+    return endpoint.rstrip("/")
+
+
+def request_installation_token(
+    *,
+    endpoint: str,
+    oidc_token: str,
+    delivery_id: str,
+    broker_grant: str,
+    target: GitHubWebhookTarget,
+) -> str:
+    if target.installation_id is None:
+        raise GitHubActionsWorkerError("scan target is missing installation_id")
+    url = _validated_token_endpoint(endpoint)
+    request = Request(
+        url,
+        data=json.dumps(
+            {
+                "delivery_id": delivery_id,
+                "broker_grant": broker_grant,
+                "target": asdict(target),
+            },
+            separators=(",", ":"),
+        ).encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {oidc_token}",
+            "Content-Type": "application/json",
+            "User-Agent": "codex-workspace-bootstrap",
+        },
+        method="POST",
+    )
+    try:
+        with urlopen(request, timeout=20) as response:
+            body = _read_json_response(response)
+    except HTTPError as exc:
+        raise GitHubActionsWorkerError(
+            f"installation-token broker returned HTTP {exc.code}"
+        ) from exc
+    except URLError as exc:
+        raise GitHubActionsWorkerError(
+            "installation-token broker request failed"
+        ) from exc
+
+    token = body.get("token")
+    if not isinstance(token, str) or not token.strip():
+        raise GitHubActionsWorkerError(
+            "installation-token broker response is missing token"
+        )
+    return token
+
+
+def execute_actions_scan(
+    *,
+    encoded_payload: str,
+    token_endpoint: str,
+) -> GitHubScanResult:
+    delivery_id, broker_grant, target = decode_scan_payload(encoded_payload)
+    audience = _validated_token_endpoint(token_endpoint)
+    oidc_token = request_actions_oidc_token(audience=audience)
+    installation_token = request_installation_token(
+        endpoint=audience,
+        oidc_token=oidc_token,
+        delivery_id=delivery_id,
+        broker_grant=broker_grant,
+        target=target,
+    )
+    return execute_github_scan_with_token(
+        target,
+        installation_token=installation_token,
+        external_id=delivery_id,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--payload",
+        default=os.environ.get("CWB_SCAN_PAYLOAD", ""),
+        help="base64url-encoded normalized GitHub scan target",
+    )
+    parser.add_argument(
+        "--token-endpoint",
+        default=os.environ.get("CWB_TOKEN_ENDPOINT", ""),
+        help="Cloudflare HTTPS installation-token broker endpoint",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        result = execute_actions_scan(
+            encoded_payload=args.payload,
+            token_endpoint=args.token_endpoint,
+        )
+    except (GitHubActionsWorkerError, GitHubAppRuntimeError) as exc:
+        print(f"CWB GitHub App scan failed: {exc}")
+        return 1
+
+    suffix = " (deduplicated)" if result.deduplicated else ""
+    print(
+        f"CWB GitHub App scan: {result.repository}@{result.commit_sha} "
+        f"-> {result.conclusion}{suffix}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())