procurement-ingest/tests/test_cross_account_principal_pin.py

"""Pin the cross-account principal surface of the Terraform app.

The SHOC integration trusts EXACTLY these foreign principals:
``arn:aws:iam::396287094661:role/shoc-backend-dev`` and
``arn:aws:iam::396287094661:role/shoc-backend-staging`` (API resource policy in
api.tf, HMAC secret + KMS grants in wo_shoc.tf). The exact ARNs are pinned as
the ``shoc_consumer_role_arns`` variable default and in
``terraform.tfvars.example``; grant sites consume ``local.shoc_consumer_role_arns``
only. Future shoc-backend-prod (or any other) roles are each a deliberate,
individually-reviewed policy addition — so any new foreign account id or role
ARN appearing under terraform/, or any change to the default/example pin, must
consciously update this test (and go through the mandatory GPT-4.1 cross-family
IAM review).

Raised as a QUESTION in the 2026-07-24 cross-family review of the
webhook emitter policy surface: "how is the exact-one-principal
invariant enforced over time?" — this test is the answer, now an
exact-allowlist rather than a single ARN.
"""

import re
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parents[1]
TF_DIR = REPO_ROOT / "terraform"
VARIABLES_TF = TF_DIR / "variables.tf"
TFVARS_EXAMPLE = TF_DIR / "terraform.tfvars.example"

ALLOWED_FOREIGN_PRINCIPALS = frozenset(
    {
        "arn:aws:iam::396287094661:role/shoc-backend-dev",
        "arn:aws:iam::396287094661:role/shoc-backend-staging",
    }
)

# Files allowed to embed those ARNs as literals (default + example). Grant
# sites must use local.shoc_consumer_role_arns instead.
ALLOWED_LITERAL_FILES = {"variables.tf", "terraform.tfvars.example"}

# Grant sites that must reference the local; dropping one half fails the pin.
GRANT_FILES = ("api.tf", "wo_shoc.tf")

# Accounts that are not "foreign": seahaven-prod (the deploy target).
HOME_ACCOUNTS = {"011934824531"}

_IAM_ARN_RE = re.compile(r"arn:aws:iam::(\d{12}):\S*?(?=[\"'\s])")
_VAR_DEFAULT_RE = re.compile(
    r'variable\s+"shoc_consumer_role_arns"\s*\{(.*?)^\}',
    re.DOTALL | re.MULTILINE,
)
_DEFAULT_LIST_RE = re.compile(r"default\s*=\s*\[(.*?)\]", re.DOTALL)
_QUOTED_RE = re.compile(r'"([^"]+)"')
_TFVARS_LIST_RE = re.compile(
    r"^shoc_consumer_role_arns\s*=\s*\[(.*?)\]",
    re.DOTALL | re.MULTILINE,
)
_LOCAL_REF = "local.shoc_consumer_role_arns"


def _terraform_sources():
    paths = sorted(TF_DIR.glob("*.tf"))
    if TFVARS_EXAMPLE.exists():
        paths.append(TFVARS_EXAMPLE)
    return paths


def _quoted_arns(block: str) -> frozenset[str]:
    return frozenset(_QUOTED_RE.findall(block))


def test_variable_default_is_the_pinned_foreign_principals():
    """The Terraform default must equal the exact trusted ARN set.

    Grant sites consume the variable via local.shoc_consumer_role_arns. Pinning
    the default restores the exact-principal invariant the former CDK scan
    enforced: widening or shrinking trust requires editing this default
    (and this test).
    """
    block = _VAR_DEFAULT_RE.search(VARIABLES_TF.read_text())
    assert block, "variables.tf must declare variable shoc_consumer_role_arns"
    default = _DEFAULT_LIST_RE.search(block.group(1))
    assert default, (
        "variable shoc_consumer_role_arns must set default = [...] so the "
        "exact principals are pinned in-repo"
    )
    arns = _quoted_arns(default.group(1))
    assert arns == ALLOWED_FOREIGN_PRINCIPALS, (
        f"shoc_consumer_role_arns default is {sorted(arns)!r}, expected "
        f"{sorted(ALLOWED_FOREIGN_PRINCIPALS)!r}"
    )


def test_tfvars_example_is_the_pinned_foreign_principals():
    match = _TFVARS_LIST_RE.search(TFVARS_EXAMPLE.read_text())
    assert match, (
        "terraform.tfvars.example must set shoc_consumer_role_arns to the pinned ARNs"
    )
    arns = _quoted_arns(match.group(1))
    assert arns == ALLOWED_FOREIGN_PRINCIPALS, (
        f"terraform.tfvars.example shoc_consumer_role_arns is {sorted(arns)!r}, "
        f"expected {sorted(ALLOWED_FOREIGN_PRINCIPALS)!r}"
    )


def test_only_the_pinned_foreign_principals_appear_in_terraform_sources():
    findings = []
    for path in _terraform_sources():
        for match in _IAM_ARN_RE.finditer(path.read_text()):
            account = match.group(1)
            if account in HOME_ACCOUNTS:
                continue
            findings.append((path.name, match.group(0)))

    unexpected = [
        (name, arn)
        for name, arn in findings
        if arn not in ALLOWED_FOREIGN_PRINCIPALS or name not in ALLOWED_LITERAL_FILES
    ]
    assert not unexpected, (
        "Unexpected foreign IAM principal(s) under terraform/ — every "
        "cross-account trust addition must update this pin deliberately: "
        f"{unexpected}"
    )
    # Both default/example sites must still name the pinned roles as literals.
    assert {name for name, _ in findings} == ALLOWED_LITERAL_FILES
    assert {arn for _, arn in findings} == ALLOWED_FOREIGN_PRINCIPALS


def test_grant_files_use_local_shoc_consumer_role_arns_only():
    """Grant sites must consume the local — never a hardcoded foreign ARN.

    api.tf (API resource policy) and wo_shoc.tf (KMS + secret policy) are the
    two halves of the trust surface. Each must reference
    local.shoc_consumer_role_arns so dropping one half fails CI, and neither
    may embed a raw foreign IAM ARN (that would bypass the variable default pin).
    """
    for filename in GRANT_FILES:
        text = (TF_DIR / filename).read_text()
        assert _LOCAL_REF in text, (
            f"{filename} must reference {_LOCAL_REF} so the SHOC cross-account "
            "grant surface cannot silently drop one half of the trust pair"
        )
        foreign = [
            m.group(0)
            for m in _IAM_ARN_RE.finditer(text)
            if m.group(1) not in HOME_ACCOUNTS
        ]
        assert not foreign, (
            f"{filename} must not hardcode foreign IAM ARNs "
            f"(use {_LOCAL_REF}): {foreign}"
        )