procurement-ingest/tests/test_cross_account_principal_pin.py

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

The SHOC integration deliberately trusts EXACTLY ONE foreign principal:
``arn:aws:iam::396287094661:role/shoc-backend-dev`` (API resource policy in
api.tf, HMAC secret + KMS grants in wo_shoc.tf). The exact ARN is pinned as
the ``shoc_consumer_role_arn`` variable default and in
``terraform.tfvars.example``; grant sites consume ``local.shoc_consumer_role_arn``
only. Future shoc-backend-staging/-prod 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.
"""

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"

# The one foreign principal the app may trust.
ALLOWED_FOREIGN_PRINCIPAL = "arn:aws:iam::396287094661:role/shoc-backend-dev"

# Files allowed to embed that ARN as a literal (default + example). Grant
# sites must use local.shoc_consumer_role_arn 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_arn"\s*\{(.*?)^\}',
    re.DOTALL | re.MULTILINE,
)
_DEFAULT_VALUE_RE = re.compile(r'default\s*=\s*"([^"]+)"')
_TFVARS_VALUE_RE = re.compile(
    r'^shoc_consumer_role_arn\s*=\s*"([^"]+)"\s*$',
    re.MULTILINE,
)
_LOCAL_REF = "local.shoc_consumer_role_arn"


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


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

    Grant sites consume the variable via local.shoc_consumer_role_arn. Pinning
    the default restores the exact-principal invariant the former CDK scan
    enforced: widening 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_arn"
    default = _DEFAULT_VALUE_RE.search(block.group(1))
    assert default, (
        "variable shoc_consumer_role_arn must set default = "
        f'"{ALLOWED_FOREIGN_PRINCIPAL}" so the exact principal is pinned in-repo'
    )
    assert default.group(1) == ALLOWED_FOREIGN_PRINCIPAL, (
        f"shoc_consumer_role_arn default is {default.group(1)!r}, expected "
        f"{ALLOWED_FOREIGN_PRINCIPAL!r}"
    )


def test_tfvars_example_is_the_pinned_foreign_principal():
    match = _TFVARS_VALUE_RE.search(TFVARS_EXAMPLE.read_text())
    assert match, (
        "terraform.tfvars.example must set shoc_consumer_role_arn to the pinned ARN"
    )
    assert match.group(1) == ALLOWED_FOREIGN_PRINCIPAL, (
        f"terraform.tfvars.example shoc_consumer_role_arn is {match.group(1)!r}, "
        f"expected {ALLOWED_FOREIGN_PRINCIPAL!r}"
    )


def test_only_the_pinned_foreign_principal_appears_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 != ALLOWED_FOREIGN_PRINCIPAL 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 role as a literal.
    assert {name for name, _ in findings} == ALLOWED_LITERAL_FILES


def test_grant_files_use_local_shoc_consumer_role_arn_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_arn 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}"
        )