feat(iam): enforce AssumeRole trust policies when enforcement is enabled

[abanna]

Summary

When FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED=true, STS AssumeRole now evaluates the target role's trust policy (AssumeRolePolicyDocument) against the caller and returns AccessDenied if it isn't permitted. Enforcement is off by default, so existing behavior is unchanged.

Trust policies are principal-centric and carry no Resource element, so the identity/resource-oriented IamPolicyEvaluator can't evaluate them. This adds a focused AssumeRolePolicyEvaluator that:

• matches each statement's Action against sts:AssumeRole (supports sts:* / *),
• matches the AWS Principal — "*", a bare account id, an account-root ARN (arn:aws:iam::<acct>:root), or an exact principal ARN,
• applies AWS precedence: an explicit Deny wins, otherwise a matching Allow grants.

The role is resolved in its own account (parsed from the role ARN) via a new IamService.findRole(account, roleName) overload, since IAM roles are account-namespaced. Roles that Floci has no record of stay permissive, so this only affects roles created through IAM with a real trust policy.

Note: the plan that motivated this work suggested reusing IamPolicyEvaluator, but its statements require a Resource match and ignore Principal, so a dedicated evaluator is used instead (it reuses the shared glob matcher).

Type of change

• New feature (feat:) — gated behind an existing opt-in flag

AWS Compatibility

Query protocol, unchanged wire format. Only adds an authorization decision on AssumeRole when enforcement is enabled. Service / Federated principals are intentionally not matched against SigV4 callers (function-before-fidelity).

Checklist

• ./mvnw test passes locally (targeted: AssumeRolePolicyEvaluatorTest 12 + AssumeRoleTrustPolicyIntegrationTest 3 + IamIntegrationTest 37 green; built in a JDK 25 container)
• New unit + integration tests added (permitted caller allowed, unauthorized denied, unknown role permissive; evaluator principal/action/deny/malformed coverage)
• Commit messages follow Conventional Commits

Independent of #1549 and #1551, though it composes with them for full cross-account assume-role fidelity.

[hectorvent]

This is really clean, Alex, and the evaluator is nicely tested. The wire side checks out: AccessDenied at 403 is the right denial, and the action, principal, and explicit deny precedence all match how AWS evaluates a trust policy.

Two gaps worth noting, both fine to defer as documented limitations since they are about evaluating more than the trust policy itself:

1. Condition blocks are not evaluated, so sts:ExternalId is not enforced. A role whose trust policy requires an external id is currently assumable without one, and the ExternalId request param is ignored too. For example this statement matches purely on the principal today, with the condition skipped:

{
  "Effect": "Allow",
  "Principal": { "AWS": "arn:aws:iam::111111111111:root" },
  "Action": "sts:AssumeRole",
  "Condition": { "StringEquals": { "sts:ExternalId": "secret-123" } }
}

So the caller gets in without passing ExternalId=secret-123. For what it is worth, moto and localstack do not evaluate this either, so you are already ahead here. Just worth a line in the docs so people know the confused deputy guard is not active yet.

2. Only the trust policy side is checked. Real cross account AssumeRole also needs the caller's identity policy to allow sts:AssumeRole. Reasonable to leave for later, just good to state as a known limitation.

One tiny thing: AWS prefixes the denial message with the caller, like:

User: arn:aws:iam::111111111111:user/alice is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::222222222222:role/foo

so adding the User: prefix would match it exactly.

Thanks for gating this behind the opt in flag and keeping the default behavior untouched, nice and safe.

[abanna]

Thanks @hectorvent! Addressed in 5f4a3e8 (also merged latest main, which had diverged):

• User: prefix — the AccessDenied message is now User: <callerArn> is not authorized to perform: sts:AssumeRole on resource: <roleArn>, matching AWS exactly. Strengthened the integration test to assert the prefix, action, and resource.
• ExternalId / Condition blocks — documented as a known limitation in docs/services/sts.md: condition blocks aren't evaluated, so sts:ExternalId isn't enforced and the request param is ignored (matching moto/LocalStack). Left the implementation as a follow-up per your note.
• Identity-policy side — also documented as a known limitation: only the trust policy is checked, not the caller's own sts:AssumeRole permission.

The merge against main was non-trivial — it reworked IamService/StsQueryHandler for account-aware sessions — so I resolved those and re-ran the IAM/STS suite (151 tests green) in a temurin-25 container against the updated main.

[greptile-apps]

Greptile Summary

This PR adds trust policy enforcement to STS AssumeRole when FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED=true. A new AssumeRolePolicyEvaluator evaluates the target role's AssumeRolePolicyDocument against the caller and returns AccessDenied if the caller is not permitted; enforcement is off by default, so existing behavior is unchanged.

• AssumeRolePolicyEvaluator: Evaluates Action/NotAction (including wildcards), AWS Principal forms ("*", bare account ID, account-root ARN, exact ARN), and applies explicit-Deny-wins precedence. Assumed-role session ARNs are resolved back to the underlying IAM role ARN for principal matching, consistent with AWS semantics.
• IamService.findRole: New account-scoped lookup overload used by the enforcement path so the role is resolved from the correct account namespace when AccountAwareStorageBackend is in use.
• StsQueryHandler: Integrates enforceTrustPolicy before building the session, with a permissive fallback for unknown roles (backward compatibility).

Confidence Score: 4/5

Safe to merge with enforcement off (the default); the trust-policy evaluation path has a known gap with non-account-aware storage backends in multi-account setups that was surfaced in a prior review and has not yet been addressed.

The new enforcement logic is gated behind an opt-in flag so existing behavior is untouched. The AssumeRolePolicyEvaluator is well-tested and handles all documented principal forms and Deny-wins precedence correctly. The flat-backend findRole fallback that ignores accountId — flagged in the previous review cycle — remains unresolved and could cause the wrong trust policy to be evaluated in a multi-account flat-storage configuration when enforcement is active.

IamService.java — the findRole fallback to roles.get(roleName) discards the accountId when AccountAwareStorageBackend is not in use.

Important Files Changed

Filename	Overview
src/main/java/io/github/hectorvent/floci/services/iam/AssumeRolePolicyEvaluator.java	New evaluator correctly handles Action/NotAction, AWS principal forms, assumed-role ARN resolution, and Deny-wins precedence; a statement with a missing Effect key silently defaults to ALLOW.
src/main/java/io/github/hectorvent/floci/services/iam/StsQueryHandler.java	Enforcement hook is correctly placed before session registration; callerArn resolution and permissive fallback for unknown roles look correct.
src/main/java/io/github/hectorvent/floci/services/iam/IamService.java	Adds account-scoped findRole overload; falls back to flat lookup ignoring accountId when AccountAwareStorageBackend is not in use (known limitation from prior review thread).
src/test/java/io/github/hectorvent/floci/services/iam/AssumeRolePolicyEvaluatorTest.java	Good unit coverage of all principal forms, NotAction, Deny-wins, assumed-role ARN resolution, service-only principal, and malformed documents.
src/test/java/io/github/hectorvent/floci/services/iam/AssumeRoleTrustPolicyIntegrationTest.java	Covers the three critical end-to-end cases (permitted caller, denied caller, unknown role stays permissive) with enforcement-enabled profile; no issues.
docs/services/sts.md	Documents the new enforcement flag and its known limitations (Condition blocks, caller-side identity policy); accurate and complete for the feature scope.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client
    participant StsQueryHandler
    participant IamService
    participant AssumeRolePolicyEvaluator

    Client->>StsQueryHandler: AssumeRole(RoleArn, RoleSessionName)
    StsQueryHandler->>StsQueryHandler: Extract roleName, accountId from ARN

    alt enforcement disabled
        StsQueryHandler-->>Client: 200 OK (credentials)
    else enforcement enabled
        StsQueryHandler->>IamService: findRole(roleAccountId, roleName)
        alt role unknown to Floci
            IamService-->>StsQueryHandler: Optional.empty()
            StsQueryHandler-->>Client: 200 OK (permissive fallback)
        else role known
            IamService-->>StsQueryHandler: Optional[IamRole]
            StsQueryHandler->>StsQueryHandler: Resolve callerArn from Authorization header
            StsQueryHandler->>AssumeRolePolicyEvaluator: allows(trustPolicy, callerArn, callerAccount)
            AssumeRolePolicyEvaluator->>AssumeRolePolicyEvaluator: Evaluate Action / NotAction
            AssumeRolePolicyEvaluator->>AssumeRolePolicyEvaluator: Match AWS Principal
            AssumeRolePolicyEvaluator->>AssumeRolePolicyEvaluator: Apply Deny-wins precedence
            AssumeRolePolicyEvaluator-->>StsQueryHandler: true / false
            alt caller permitted
                StsQueryHandler-->>Client: 200 OK (credentials)
            else caller denied
                StsQueryHandler-->>Client: 403 AccessDenied
            end
        end
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Client
    participant StsQueryHandler
    participant IamService
    participant AssumeRolePolicyEvaluator

    Client->>StsQueryHandler: AssumeRole(RoleArn, RoleSessionName)
    StsQueryHandler->>StsQueryHandler: Extract roleName, accountId from ARN

    alt enforcement disabled
        StsQueryHandler-->>Client: 200 OK (credentials)
    else enforcement enabled
        StsQueryHandler->>IamService: findRole(roleAccountId, roleName)
        alt role unknown to Floci
            IamService-->>StsQueryHandler: Optional.empty()
            StsQueryHandler-->>Client: 200 OK (permissive fallback)
        else role known
            IamService-->>StsQueryHandler: Optional[IamRole]
            StsQueryHandler->>StsQueryHandler: Resolve callerArn from Authorization header
            StsQueryHandler->>AssumeRolePolicyEvaluator: allows(trustPolicy, callerArn, callerAccount)
            AssumeRolePolicyEvaluator->>AssumeRolePolicyEvaluator: Evaluate Action / NotAction
            AssumeRolePolicyEvaluator->>AssumeRolePolicyEvaluator: Match AWS Principal
            AssumeRolePolicyEvaluator->>AssumeRolePolicyEvaluator: Apply Deny-wins precedence
            AssumeRolePolicyEvaluator-->>StsQueryHandler: true / false
            alt caller permitted
                StsQueryHandler-->>Client: 200 OK (credentials)
            else caller denied
                StsQueryHandler-->>Client: 403 AccessDenied
            end
        end
    end

Loading

_{Reviews (4): Last reviewed commit: "fix(iam): match an assumed-role caller a..." | Re-trigger Greptile}

[abanna]

Thanks @greptile-apps — went through all three:

• Configuration section dropped from sts.md (P2): Valid, fixed in 5ffda29 — restored the FLOCI_SERVICES_STS_ENABLED table.
• NotAction silently skipped (P2): Valid in principle — a Deny with NotAction won't block the assume. Trust policies using NotAction are very rare, and like Condition evaluation it's an advanced policy feature this PR intentionally defers, so I documented it as a known limitation rather than implementing partial NotAction semantics now.
• findRole flat-backend fallback ignores accountId (P2): In practice roles is always an AccountAwareStorageBackend (main made IAM account-namespaced), so the fallback is only a safety net. A genuinely flat backend has no account dimension to key on, so roles.get(roleName) is the only thing it can do — passing accountId wouldn't change the result. Left as-is.

[greptile-apps]

All three responses are reasonable — thanks for the thorough follow-up.

1. Configuration section in sts.md — fix looks good.
2. NotAction — documenting it as a known limitation is the right call for a deferred edge case; trust policies using NotAction are genuinely rare in practice.
3. flat-backend fallback — the argument holds. A backend with no account dimension can only key on role name, so passing accountId wouldn't change anything. The real concern would be if the AccountAwareStorageBackend path somehow fell through to the flat branch unexpectedly, but that's a pre-existing structural guarantee, not something this PR needs to defend.

No further concerns on these. The PR looks good to go from my end.

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.

[hectorvent]

Thanks @abanna