Coverage for scripts / live_release_validation / emulator.py: 100.00%

1"""Explicit, verified emulator opt-in for the live validation harness. 

2 

3The harness is local-only by design: ``require_local_execution`` refuses to 

4run inside GitHub Actions so ordinary CI can never touch a real AWS account. 

5One narrowly scoped exception exists: running the ENTIRE harness against a 

6local AWS emulator (Floci) — the CI rehearsal layer documented in 

7docs/FLOCI_TESTING.md. The exception is opt-in and fails closed: 

8 

91. ``GCO_LIVE_VALIDATION_EMULATOR`` must name the emulator's base URL; 

102. ``AWS_ENDPOINT_URL`` must point at exactly that URL, so every SDK client 

11 in the run — harness, CLI, CDK — resolves to the emulator; 

123. the URL must be plain ``http://`` on an allow-listed local hostname 

13 (every real AWS endpoint is HTTPS on ``*.amazonaws.com``); and 

144. STS must echo the fabricated 12-digit access-key id back as the caller 

15 account — emulator multi-account behavior that real AWS cannot imitate, 

16 because a fabricated key id never passes real signature validation. 

17 

18Any violation raises before a checkpoint or AWS client exists. Nothing else 

19about the harness changes in emulator mode: preflight still pins account, 

20SHA, branch, and worktree cleanliness, and cleanup still runs. This is a 

21deliberate testability seam, not an emulator compatibility layer — no other 

22harness code consults it. 

23""" 

24 

25from __future__ import annotations 

26 

27import os 

28from urllib.parse import urlparse 

29 

30EMULATOR_ENDPOINT_ENV = "GCO_LIVE_VALIDATION_EMULATOR" 

31 

32_ALLOWED_EMULATOR_HOSTNAMES = frozenset({"localhost", "127.0.0.1", "floci"}) 

33 

34 

35def emulator_endpoint_requested() -> str | None: 

36 """The declared emulator endpoint, or None for a real-AWS run.""" 

37 value = os.environ.get(EMULATOR_ENDPOINT_ENV, "").strip() 

38 return value or None 

39 

40 

41def verify_emulator_endpoint(endpoint: str) -> None: 

42 """Prove ``endpoint`` is an emulator or raise ``RuntimeError``. 

43 

44 Performs the static URL checks and the STS identity-echo probe described 

45 in the module docstring. Callers must invoke this BEFORE building any 

46 other AWS client so a misconfigured run dies without side effects. 

47 """ 

48 normalized = endpoint.rstrip("/") 

49 parsed = urlparse(normalized) 

50 if parsed.scheme != "http": 

51 raise RuntimeError( 

52 f"Emulator endpoint {endpoint!r} must be plain http; https implies a real service" 

53 ) 

54 if (parsed.hostname or "") not in _ALLOWED_EMULATOR_HOSTNAMES: 

55 raise RuntimeError( 

56 f"Emulator endpoint host {parsed.hostname!r} is not an allowed emulator host " 

57 f"({', '.join(sorted(_ALLOWED_EMULATOR_HOSTNAMES))})" 

58 ) 

59 configured = os.environ.get("AWS_ENDPOINT_URL", "").rstrip("/") 

60 if configured != normalized: 

61 raise RuntimeError( 

62 "AWS_ENDPOINT_URL must point at the declared emulator endpoint " 

63 f"({normalized!r}), got {configured!r}; refusing a split-endpoint run" 

64 ) 

65 access_key = os.environ.get("AWS_ACCESS_KEY_ID", "") 

66 if len(access_key) != 12 or not access_key.isdigit(): 

67 raise RuntimeError( 

68 "Emulator runs require a fabricated 12-digit AWS_ACCESS_KEY_ID (the emulator " 

69 "account id); refusing credentials that could belong to a real principal" 

70 ) 

71 

72 import boto3 

73 

74 identity = boto3.client("sts").get_caller_identity() 

75 account = str(identity.get("Account") or "") 

76 if account != access_key: 

77 raise RuntimeError( 

78 f"STS at {normalized} answered account {account!r} instead of echoing the " 

79 f"fabricated key id {access_key!r}; this endpoint does not behave like an " 

80 "emulator, so the run is refused" 

81 )