|
| 1 | +"""M4-A5 GitHub-issued independent server-time proof of protected source digests. |
| 2 | +
|
| 3 | +The GitHub OIDC issuer signs the audience (which binds source bytes hashed by |
| 4 | +protected code), job identity, run_id and issuance UTC. These proofs DO NOT |
| 5 | +establish the publisher's first-serving timestamp or its own signature. The |
| 6 | +source and kickoff publishers are independent; both JWTs have the SAME GitHub |
| 7 | +signing authority. An immutable PostgreSQL server-clock commit remains required |
| 8 | +before any genuine prospective-as-of claim. Never print JWTs or JWKS contents. |
| 9 | +""" |
| 10 | +import os |
| 11 | +import re |
| 12 | +import ssl |
| 13 | +from dataclasses import dataclass |
| 14 | +from datetime import UTC, datetime |
| 15 | +from hashlib import sha256 |
| 16 | +from json import dumps, loads |
| 17 | +from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit |
| 18 | +from urllib.request import ( |
| 19 | + HTTPRedirectHandler, |
| 20 | + HTTPSHandler, |
| 21 | + Request, |
| 22 | + build_opener, |
| 23 | +) |
| 24 | + |
| 25 | +import jwt |
| 26 | +from jwt.algorithms import RSAAlgorithm |
| 27 | + |
| 28 | +from football_forecast.data.contracts import DataError |
| 29 | + |
| 30 | +ISSUER = "https://token.actions.githubusercontent.com" |
| 31 | +DISCOVERY = ISSUER + "/.well-known/openid-configuration" |
| 32 | +JWKS = ISSUER + "/.well-known/jwks" |
| 33 | +REPO = "StanleyLl0yd/FootballForecast" |
| 34 | +REPO_ID = "1422508335" |
| 35 | +ACTOR = "StanleyLl0yd" |
| 36 | +ACTOR_ID = "131160519" |
| 37 | +WORKFLOW = (REPO + |
| 38 | + "/.github/workflows/m4-future-rpl-source-observation.yml@refs/heads/main") |
| 39 | +ENVIRONMENT = "m1-source-import" |
| 40 | +SHA = re.compile(r"^[a-f0-9]{64}$") |
| 41 | +COMMIT = re.compile(r"^[a-f0-9]{40}$") |
| 42 | +MAX_JWT = 10000 |
| 43 | +MAX_JWKS = 100000 |
| 44 | +MAX_PROOF_AGE = 300 |
| 45 | + |
| 46 | + |
| 47 | +class _NoRedirect(HTTPRedirectHandler): |
| 48 | + def redirect_request(self, request, fp, code, msg, headers, newurl): |
| 49 | + raise DataError("M4 OIDC unexpected redirect") |
| 50 | + |
| 51 | + |
| 52 | +@dataclass(frozen=True, slots=True) |
| 53 | +class ProtectedTimeProof: |
| 54 | + """Private live signatures. Never serialize as public outputs or artifacts.""" |
| 55 | + source_jwt: str |
| 56 | + kickoff_jwt: str |
| 57 | + source_jwk_json: str |
| 58 | + kickoff_jwk_json: str |
| 59 | + source_issued_utc: str |
| 60 | + kickoff_issued_utc: str |
| 61 | + |
| 62 | + @property |
| 63 | + def source_token_sha256(self): |
| 64 | + return sha256(self.source_jwt.encode("ascii")).hexdigest() |
| 65 | + |
| 66 | + @property |
| 67 | + def kickoff_token_sha256(self): |
| 68 | + return sha256(self.kickoff_jwt.encode("ascii")).hexdigest() |
| 69 | + |
| 70 | + |
| 71 | +def _deny(): |
| 72 | + raise DataError("M4: trusted GitHub OIDC time proof refused") |
| 73 | + |
| 74 | + |
| 75 | +def _https_json(url: str, *, headers=None, limit=MAX_JWKS): |
| 76 | + opener = build_opener(_NoRedirect(), HTTPSHandler(context=ssl.create_default_context())) |
| 77 | + with opener.open(Request(url, headers=headers or {"Accept": "application/json"}, |
| 78 | + method="GET"), timeout=10) as response: |
| 79 | + if response.status != 200 or "json" not in response.headers.get( |
| 80 | + "Content-Type", "").lower(): |
| 81 | + _deny() |
| 82 | + raw = response.read(limit + 1) |
| 83 | + if not 2 <= len(raw) <= limit: |
| 84 | + _deny() |
| 85 | + def pairs(values): |
| 86 | + row = {} |
| 87 | + for key, value in values: |
| 88 | + if key in row: |
| 89 | + _deny() |
| 90 | + row[key] = value |
| 91 | + return row |
| 92 | + try: |
| 93 | + return loads(raw.decode("utf-8", "strict"), object_pairs_hook=pairs) |
| 94 | + except (UnicodeError, ValueError) as exc: |
| 95 | + raise DataError("M4: invalid OIDC JSON") from exc |
| 96 | + |
| 97 | + |
| 98 | +def _keys_from_github() -> tuple[dict, ...]: |
| 99 | + metadata = _https_json(DISCOVERY, limit=16000) |
| 100 | + if (type(metadata) is not dict or metadata.get("issuer") != ISSUER or |
| 101 | + metadata.get("jwks_uri") != JWKS or |
| 102 | + "RS256" not in metadata.get("id_token_signing_alg_values_supported", [])): |
| 103 | + _deny() |
| 104 | + response = _https_json(JWKS) |
| 105 | + keys = response.get("keys") if type(response) is dict else None |
| 106 | + if type(keys) is not list or not 1 <= len(keys) <= 40: |
| 107 | + _deny() |
| 108 | + return tuple(keys) |
| 109 | + |
| 110 | + |
| 111 | +def _expected_identity(env: dict[str, str]): |
| 112 | + required = { |
| 113 | + "GITHUB_REPOSITORY": REPO, |
| 114 | + "GITHUB_REF": "refs/heads/main", |
| 115 | + "GITHUB_ACTOR": ACTOR, |
| 116 | + } |
| 117 | + if any(env.get(k) != v for k, v in required.items()): |
| 118 | + _deny() |
| 119 | + if (env.get("GITHUB_EVENT_NAME") not in {"issue_comment", "workflow_dispatch"} |
| 120 | + or not COMMIT.fullmatch(env.get("GITHUB_SHA", "")) |
| 121 | + or not env.get("GITHUB_RUN_ID", "").isdigit() |
| 122 | + or not env.get("GITHUB_RUN_ATTEMPT", "").isdigit()): |
| 123 | + _deny() |
| 124 | + |
| 125 | + |
| 126 | +def _claims_time(value): |
| 127 | + if type(value) is not int or not 1_000_000_000 <= value <= 4_000_000_000: |
| 128 | + _deny() |
| 129 | + return value |
| 130 | + |
| 131 | + |
| 132 | +def verify_github_time_jwt( |
| 133 | + token: str, audience: str, jwks: tuple[dict, ...], |
| 134 | + env: dict[str, str], observed_at: datetime, verified_at: datetime, |
| 135 | +) -> tuple[str, str]: |
| 136 | + """Pure detached-signature validation against already verified issuer keys. |
| 137 | +
|
| 138 | + Returns (issuance UTC, canonical public signing JWK). Does not authorize DB |
| 139 | + writes by itself. Runtime JWKS MUST come from fixed HTTPS issuer discovery. |
| 140 | + """ |
| 141 | + _expected_identity(env) |
| 142 | + if (type(token) is not str or not 400 <= len(token) <= MAX_JWT or |
| 143 | + type(audience) is not str or len(audience) > 256 or |
| 144 | + not audience.startswith("ff-m4-2026-27-") or |
| 145 | + not isinstance(observed_at, datetime) or observed_at.tzinfo != UTC or |
| 146 | + not isinstance(verified_at, datetime) or verified_at.tzinfo != UTC or |
| 147 | + type(jwks) is not tuple or not 1 <= len(jwks) <= 40): |
| 148 | + _deny() |
| 149 | + try: |
| 150 | + header = jwt.get_unverified_header(token) |
| 151 | + if (header.get("alg") != "RS256" or |
| 152 | + type(header.get("kid")) is not str or |
| 153 | + not 1 <= len(header["kid"]) <= 256 or |
| 154 | + any(k in header for k in ("jku", "x5u", "jwk", "x5c"))): |
| 155 | + _deny() |
| 156 | + matching = [ |
| 157 | + key for key in jwks if type(key) is dict and |
| 158 | + key.get("kid") == header["kid"] and key.get("kty") == "RSA" and |
| 159 | + key.get("use", "sig") == "sig" and |
| 160 | + key.get("alg", "RS256") == "RS256" and |
| 161 | + type(key.get("n")) is str and type(key.get("e")) is str |
| 162 | + ] |
| 163 | + if len(matching) != 1: |
| 164 | + _deny() |
| 165 | + public_key = RSAAlgorithm.from_jwk(dumps(matching[0])) |
| 166 | + claims = jwt.decode( |
| 167 | + token, public_key, algorithms=["RS256"], audience=audience, issuer=ISSUER, |
| 168 | + options={"require": [ |
| 169 | + "exp", "iat", "nbf", "jti", "sub", "aud", "iss", |
| 170 | + "repository", "repository_id", "actor", "actor_id", |
| 171 | + "ref", "sha", "run_id", "run_attempt", "environment", |
| 172 | + "workflow_ref", "event_name", |
| 173 | + ]}, |
| 174 | + leeway=5, |
| 175 | + ) |
| 176 | + except (ValueError, TypeError, jwt.PyJWTError) as exc: |
| 177 | + raise DataError("M4: invalid cryptographic time signature") from exc |
| 178 | + exact = { |
| 179 | + "repository": REPO, "repository_id": REPO_ID, "actor": ACTOR, |
| 180 | + "actor_id": ACTOR_ID, "ref": "refs/heads/main", |
| 181 | + "sha": env["GITHUB_SHA"], "run_id": env["GITHUB_RUN_ID"], |
| 182 | + "run_attempt": env["GITHUB_RUN_ATTEMPT"], "environment": ENVIRONMENT, |
| 183 | + "workflow_ref": WORKFLOW, "event_name": env["GITHUB_EVENT_NAME"], |
| 184 | + "sub": f"repo:{REPO}:environment:{ENVIRONMENT}", |
| 185 | + } |
| 186 | + if (any(claims.get(k) != v for k, v in exact.items()) or |
| 187 | + claims.get("aud") != audience or |
| 188 | + type(claims.get("jti")) is not str or |
| 189 | + not 12 <= len(claims["jti"]) <= 512): |
| 190 | + _deny() |
| 191 | + issued = _claims_time(claims.get("iat")) |
| 192 | + not_before = _claims_time(claims.get("nbf")) |
| 193 | + expires = _claims_time(claims.get("exp")) |
| 194 | + observed = observed_at.timestamp() |
| 195 | + verified = verified_at.timestamp() |
| 196 | + if (not_before > issued + 5 or expires <= issued or expires > issued + 900 |
| 197 | + or issued + 5 < observed or issued > verified + 5 |
| 198 | + or verified - issued > MAX_PROOF_AGE): |
| 199 | + _deny() |
| 200 | + return datetime.fromtimestamp(issued, UTC).strftime("%Y-%m-%dT%H:%M:%SZ"), dumps( |
| 201 | + matching[0], sort_keys=True, separators=(",", ":"), |
| 202 | + ) |
| 203 | + |
| 204 | + |
| 205 | +def _token_for_audience(audience: str, env: dict[str, str]) -> str: |
| 206 | + base = env.get("ACTIONS_ID_TOKEN_REQUEST_URL", "") |
| 207 | + token = env.get("ACTIONS_ID_TOKEN_REQUEST_TOKEN", "") |
| 208 | + parsed = urlsplit(base) |
| 209 | + if (parsed.scheme != "https" or |
| 210 | + parsed.hostname not in {"pipelines.actions.githubusercontent.com", |
| 211 | + "token.actions.githubusercontent.com"} or |
| 212 | + parsed.username is not None or parsed.password is not None or |
| 213 | + parsed.port not in (None, 443) or not token or len(token) > 6000 or |
| 214 | + len(base) > 2000): |
| 215 | + _deny() |
| 216 | + values = parse_qsl(parsed.query, keep_blank_values=True, strict_parsing=True) |
| 217 | + if any(key == "audience" for key, _ in values): |
| 218 | + _deny() |
| 219 | + url = urlunsplit(( |
| 220 | + parsed.scheme, parsed.netloc, parsed.path, |
| 221 | + urlencode([*values, ("audience", audience)]), "", |
| 222 | + )) |
| 223 | + doc = _https_json(url, headers={ |
| 224 | + "Accept": "application/json", "Authorization": "Bearer " + token, |
| 225 | + }, limit=16000) |
| 226 | + result = doc.get("value") if type(doc) is dict else None |
| 227 | + if type(result) is not str: |
| 228 | + _deny() |
| 229 | + return result |
| 230 | + |
| 231 | + |
| 232 | +def attest_future_source_digests( |
| 233 | + source_sha: str, kickoff_sha: str, source_observed: datetime, |
| 234 | + kickoff_observed: datetime, *, env: dict[str, str] | None = None, |
| 235 | +) -> ProtectedTimeProof: |
| 236 | + """Both publisher bytes must already have been fetched and checked LIVE.""" |
| 237 | + if env is None: |
| 238 | + env = dict(os.environ) |
| 239 | + _expected_identity(env) |
| 240 | + if (type(source_sha) is not str or not SHA.fullmatch(source_sha) |
| 241 | + or type(kickoff_sha) is not str or not SHA.fullmatch(kickoff_sha) |
| 242 | + or source_sha == kickoff_sha |
| 243 | + or not isinstance(source_observed, datetime) or |
| 244 | + not isinstance(kickoff_observed, datetime) or |
| 245 | + source_observed.tzinfo != UTC or kickoff_observed.tzinfo != UTC or |
| 246 | + source_observed > kickoff_observed): |
| 247 | + _deny() |
| 248 | + audience_source = "ff-m4-2026-27-openfoot-sha256-" + source_sha |
| 249 | + audience_kickoff = "ff-m4-2026-27-matchtv-sha256-" + kickoff_sha |
| 250 | + # Independent provider observations. Two GitHub-signed audiences, not |
| 251 | + # two independent OIDC issuers. Never call these third-party-signed. |
| 252 | + source_jwt = _token_for_audience(audience_source, env) |
| 253 | + kickoff_jwt = _token_for_audience(audience_kickoff, env) |
| 254 | + jwks = _keys_from_github() |
| 255 | + verified_at = datetime.now(UTC) |
| 256 | + a_utc, a_jwk = verify_github_time_jwt( |
| 257 | + source_jwt, audience_source, jwks, env, kickoff_observed, verified_at) |
| 258 | + b_utc, b_jwk = verify_github_time_jwt( |
| 259 | + kickoff_jwt, audience_kickoff, jwks, env, kickoff_observed, verified_at) |
| 260 | + if source_jwt == kickoff_jwt or a_utc > b_utc: |
| 261 | + _deny() |
| 262 | + return ProtectedTimeProof( |
| 263 | + source_jwt=source_jwt, kickoff_jwt=kickoff_jwt, |
| 264 | + source_jwk_json=a_jwk, kickoff_jwk_json=b_jwk, |
| 265 | + source_issued_utc=a_utc, kickoff_issued_utc=b_utc, |
| 266 | + ) |
0 commit comments