plamentsv/auth-validation

AUTH_VALIDATION Skill (Soroban)

Trigger Pattern: Always required for Soroban audits Inject Into: Breadth agents, depth agents Finding prefix: [AV-N] Rules referenced: R4, R6, R10, R13

Soroban's authorization model differs fundamentally from EVM: instead of msg.sender, callers invoke require_auth() or require_auth_for_args() on an Address. Missing or incorrectly scoped auth is the most common critical bug class on Soroban.

1. Auth Inventory

For EVERY pub fn in each contract, determine whether it modifies state and whether auth is present:

| Function | Modifies State? | Modifies Balance/Config/Ownership? | require_auth Present? | Auth Address | Missing? | |----------|----------------|-------------------------------------|------------------------|-------------|----------| | {fn_name} | YES/NO | YES/NO | YES/NO | {address_var or NONE} | FLAG if modifies state but NO auth |

Critical patterns to flag:

• Any function writing to storage without a prior require_auth() call
• Any function that transfers funds or mints tokens without auth
• Any function that updates privileged config (admin, fee, whitelist) without auth

Soroban note: require_auth() panics if the address has not authorized the invocation. It does NOT return a bool — absence means the call proceeds without authorization.

2. Auth Tree Propagation

When a contract calls another contract via invoke_contract, the auth context must propagate to sub-calls. Trace each cross-contract invocation:

| Calling Fn | Sub-Contract Invocation | Auth Expected in Sub-Call? | AuthorizedInvocation Provided? | Sub-Call Protected? | |------------|------------------------|---------------------------|----------------------------------|---------------------| | {fn} | invoke_contract({contract}, {fn}) | YES/NO | YES/NO | YES/NO |

Attack surface: If a top-level function calls require_auth(user) but then invokes a sub-contract on behalf of the user without passing the correct AuthorizedInvocation tree, the sub-contract cannot verify the user actually authorized the sub-call.

Check for:

• require_auth() at top level but no auth context propagated to sub-contract invocations
• Sub-contracts that perform privileged operations but rely on the caller to have checked auth (missing defense-in-depth)
• invoke_contract_check_auth used as a bypass for normal require_auth flow

3. Custom Account Contracts (__check_auth)

For any contract implementing the CustomAccountInterface (contains __check_auth):

| Check | Present? | Correct? | Notes | |-------|----------|---------|-------| | Signature verification against stored public keys | YES/NO | YES/NO | | | Replay protection (nonce or sequence number) | YES/NO | YES/NO | | | Signature threshold enforcement (multi-sig) | YES/NO | YES/NO | | | context.signature_payload used (not raw payload) | YES/NO | YES/NO | | | Auth invocation tree validated against expected function | YES/NO | YES/NO | |

Critical: __check_auth is called by the host to verify whether an address has authorized an invocation. Bugs here allow bypassing authorization for ALL operations that use this account contract.

Specific checks:

• Verify the function uses context.signature_payload (the canonical payload) rather than constructing its own hash
• Verify nonce is incremented atomically to prevent replay
• For multi-sig: verify the threshold check uses >= not > (off-by-one)
• Verify sub_invocations in the auth tree are validated, not just the top-level call
• Sub-invocation auth bypass (host issue #788): When contract B calls contract A with different require_auth argument sets in the same transaction, a custom auth contract that approves one call may inadvertently authorize both. Verify the __check_auth implementation distinguishes between different invocation contexts.
• Spending limits: If the custom account implements spending limits, verify limits are checked BEFORE authorization and decremented atomically. A gap between check and decrement allows multiple calls within one transaction to bypass the limit.
• Session keys / delegated auth: If the custom account supports session keys, verify (1) session key scope is enforced (only authorized functions/amounts), (2) session keys expire, (3) revocation is immediate (not deferred to next transaction)

4. Auth Argument Matching (require_auth_for_args)

require_auth_for_args binds authorization to specific argument values. Verify the correct arguments are passed:

| Function | Uses require_auth_for_args? | Arguments Passed | Arguments That Should Be Bound | Mismatch? | |----------|------------------------------|-----------------|-------------------------------|-----------| | {fn} | YES/NO | {args list} | {expected critical args} | FLAG if mismatch |

Attack: If approve(spender, amount) calls require_auth_for_args(owner, (spender, wrong_amount)), an attacker can get the owner to authorize a small amount but then pass a larger amount in the actual call.

Pattern to check:

• Does require_auth_for_args bind ALL security-critical parameters (amounts, recipients, token addresses)?
• Are the bound arguments the actual runtime values, not hardcoded or stale values?
• Is the args tuple in the same order as the function signature (order matters for serialization)?
• Determinism requirement: The mapping between invocation arguments and auth arguments MUST be deterministic. If require_auth_for_args computes its argument set from mutable state that could change between the user signing and the transaction executing, the auth can be bypassed or a different operation authorized than what was signed.

5. Missing Auth Patterns

Exhaustively check for state modifications without any form of auth:

| Pattern | Location | Auth Present? | Finding? | |---------|----------|--------------|---------| | Balance modification (token.transfer, token.mint, token.burn) | {file:line} | YES/NO | [AV-N] if NO | | Config update (admin, fee_rate, paused, whitelist) | {file:line} | YES/NO | [AV-N] if NO | | Ownership transfer or role grant | {file:line} | YES/NO | [AV-N] if NO | | Emergency/pause functions | {file:line} | YES/NO | [AV-N] if NO | | Initialization functions (callable once) | {file:line} | YES/NO | [AV-N] if NO |

Init function special case: Soroban contracts frequently have an initialize() or init() function that stores the initial admin. If this function has no auth check AND no "already initialized" guard, anyone can reinitialize the contract and replace the admin.

Check the initialization guard pattern:

// SAFE: checks not-yet-initialized
if env.storage().instance().has(&DataKey::Admin) {
    panic!("already initialized");
}
// UNSAFE: no guard → anyone can reinitialize

Finding Template

**ID**: [AV-N]
**Severity**: [Critical if balance/ownership, High if config, Medium if view-only privileged]
**Step Execution**: ✓1,2,3,4,5 | ✗(reasons) | ?(uncertain)
**Rules Applied**: [R4:✓/✗, R6:✓/✗, R10:✓/✗, R13:✓/✗]
**Location**: src/{contract}.rs:LineN
**Title**: Missing `require_auth` on `{fn_name}` allows unauthorized {action}
**Description**: [Specific missing auth with code reference showing the unguarded state mutation]
**Impact**: [What attacker achieves: fund theft, admin takeover, config manipulation, unauthorized minting]

---

Step Execution Checklist (MANDATORY)

| Section | Required | Completed? | Notes | |---------|----------|------------|-------| | 1. Auth Inventory | YES | ✓/✗/? | Every pub fn with state modification | | 2. Auth Tree Propagation | IF cross-contract calls present | ✓/✗(N/A)/? | Every invoke_contract | | 3. Custom Account Contracts | IF __check_auth present | ✓/✗(N/A)/? | Full check_auth implementation audit | | 4. Auth Argument Matching | IF require_auth_for_args used | ✓/✗(N/A)/? | Verify all critical args bound | | 5. Missing Auth Patterns | YES | ✓/✗/? | Balances, config, init functions |