You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/stellar-contracts/accounts/authorization-flow.mdx
+62-74Lines changed: 62 additions & 74 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,27 @@
2
2
title: Authorization Flow
3
3
---
4
4
5
-
Authorization in smart accounts is determined by matching the current context against the account's context rules. Rules are gathered, ordered by recency, and evaluated until one satisfies the requirements. If a matching rule is found, its policies (if any) are enforced. Otherwise, authorization fails.
5
+
Authorization in smart accounts is determined by matching each auth context against explicitly selected context rules. The caller supplies `context_rule_ids` in the `AuthPayload`, specifying exactly one rule per auth context. If the selected rule passes all checks, its policies (if any) are enforced. Otherwise, authorization fails.
6
+
7
+
## AuthPayload
8
+
9
+
The `AuthPayload` structure is passed as the signature data in `__check_auth`:
10
+
11
+
```rust
12
+
#[contracttype]
13
+
pubstructAuthPayload {
14
+
/// Signature data mapped to each signer.
15
+
pubsigners:Map<Signer, Bytes>,
16
+
/// Per-context rule IDs, aligned by index with `auth_contexts`.
17
+
pubcontext_rule_ids:Vec<u32>,
18
+
}
19
+
```
20
+
21
+
Each entry in `context_rule_ids` specifies the rule ID to validate against for the corresponding auth context (by index). Its length must equal `auth_contexts.len()`.
22
+
23
+
<Callouttype="warning">
24
+
The `context_rule_ids` are bound into the signed digest: `sha256(signature_payload || context_rule_ids.to_xdr())`. This prevents rule-selection downgrade attacks where an attacker could redirect a signature to a less restrictive rule.
25
+
</Callout>
6
26
7
27
## Detailed Flow
8
28
```mermaid
@@ -14,11 +34,13 @@ sequenceDiagram
14
34
participant Verifier
15
35
participant Policy
16
36
17
-
User->>SmartAccount: Signatures
18
-
SmartAccount->>ContextRule: Match context<br/>(CallContract, Default, ...)
19
-
ContextRule->>ContextRule: Filter expired rules<br/>Sort newest first
Note over ContextRule,Policy: Policy enforcement (panics on failure)
53
+
ContextRule->>Policy: enforce()
54
+
Policy->>Policy: Validate + update state
55
+
56
+
ContextRule-->>SmartAccount: ✓ Authorized
41
57
end
42
58
43
59
SmartAccount-->>User: Success
44
60
```
45
61
46
-
### 1. Rule Collection
62
+
### 1. Rule Lookup
47
63
48
-
The smart account gathers all relevant context rules for evaluation:
64
+
The smart account reads the `context_rule_ids` from the `AuthPayload`. There must be exactly one rule ID per auth context — a mismatch is rejected with `ContextRuleIdsLengthMismatch`.
49
65
50
-
- Retrieve all non-expired rules for the specific context type
51
-
- Include default rules that apply to any context
52
-
- Sort specific and default rules by creation time (newest first)
66
+
For each auth context, the corresponding rule ID is used to look up the context rule directly. The rule must:
53
67
54
-
**Context Type Matching:**
55
-
- For a `CallContract(address)` context, both specific `CallContract(address)` rules and `Default` rules are collected
56
-
- For a `CreateContract(wasm_hash)` context, both specific `CreateContract(wasm_hash)` rules and `Default` rules are collected
57
-
- For any other context, only `Default` rules are collected
58
-
59
-
**Expiration Filtering:**
60
-
Rules with `valid_until` set to a ledger sequence that has passed are automatically filtered out during collection.
68
+
- Exist in the account's storage
69
+
- Not be expired (if `valid_until` is set, it must be ≥ current ledger sequence)
70
+
- Match the context type: a `CallContract(address)` rule matches a `CallContract(address)` context, and `Default` rules match any context
61
71
62
72
### 2. Rule Evaluation
63
73
64
-
For each rule in order (newest and most specific first):
74
+
For each (context, rule_id) pair:
65
75
66
76
#### Step 2.1: Signer Filtering
67
77
@@ -72,51 +82,33 @@ Extract authenticated signers from the rule's signer list. A signer is considere
72
82
73
83
Only authenticated signers proceed to the next step.
74
84
75
-
#### Step 2.2: Policy Validation
85
+
#### Step 2.2: Policy Enforcement
76
86
77
-
If the rule has attached policies, verify that all can be enforced:
87
+
If the rule has attached policies, the smart account calls `enforce()` on each policy. The `enforce()` method both validates conditions and applies state changes — it panics if the policy conditions are not satisfied:
This triggers any necessary state changes such as updating spending counters, recording timestamps, emitting audit events, or modifying allowances.
116
-
117
-
Policy enforcement requires the smart account's authorization, ensuring that policies can only be enforced by the account itself.
118
-
119
-
### 4. Result
111
+
### 3. Result
120
112
121
113
**Success:** Authorization is granted and the transaction proceeds. All policy state changes are committed.
122
114
@@ -151,15 +143,14 @@ ContextRule {
151
143
**Authorization Entries:**`[passkey_signature]`
152
144
153
145
**Flow:**
154
-
1.Collect: Rules 2 (specific) and 1 (default)
146
+
1.Lookup: Client specifies rule ID 2 in `context_rule_ids`
155
147
2. Evaluate Rule 2:
148
+
- Rule matches `CallContract(dex_address)` context and is not expired
156
149
- Signer filtering: Passkey authenticated
157
-
- Policy validation: Spending limit check passes
158
-
- Authorization check: All policies enforceable → Success
159
-
3. Enforce: Update spending counters, emit events
160
-
4. Result: Authorized
150
+
- Policy enforcement: Spending limit validates and updates counters
151
+
- Authorization check: All policies enforced successfully → Success
152
+
3. Result: Authorized
161
153
162
-
If the spending limit had been exceeded, Rule 2 would fail and evaluation would continue to Rule 1 (which would also fail since the passkey doesn't match Alice or Bob).
Copy file name to clipboardExpand all lines: content/stellar-contracts/accounts/context-rules.mdx
+16-15Lines changed: 16 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -44,28 +44,29 @@ Each rule must contain at least one signer OR one policy. This enables pure poli
44
44
### Multiple Rules Per Context
45
45
Multiple rules can exist for the same context type with different signer sets and policies. This allows progressive authorization models where different combinations of credentials grant access to the same operations.
46
46
47
-
### Rule Precedence
48
-
Rules are evaluated in reverse chronological order (newest first). The first matching rule wins. This enables seamless permission updates: adding a new rule with different requirements immediately takes precedence over older rules for the same context.
47
+
### Explicit Rule Selection
48
+
Rules are not iterated or auto-discovered. Instead, off-chain clients specify exactly which context rule to use for each operation via the `context_rule_ids` field in `AuthPayload`. This explicit selection prevents downgrade attacks where an attacker could force the system to fall back to a weaker rule.
49
49
50
50
### Automatic Expiration
51
-
Expired rules are automatically filtered out during authorization evaluation.
51
+
Expired rules are rejected during authorization evaluation.
52
52
53
53
## Context Rule Limits
54
54
55
-
The framework enforces limits to keep costs predictable and encourage proactive context rule management (remove expired or non-valid rules):
56
-
57
-
- Maximum context rules per smart account: 15
58
55
- Maximum signers per context rule: 15
59
56
- Maximum policies per context rule: 5
57
+
- Maximum context rule name size: 20 bytes
58
+
- Maximum external signer key size: 256 bytes
59
+
60
+
There is no upper limit on the total number of context rules per smart account.
60
61
61
62
## Authorization Matching
62
63
63
64
During authorization, the framework:
64
65
65
-
1.Gathers all non-expired rules matching the context type plus default rules
66
-
2.Sorts rules by creation time (newest first)
67
-
3.Evaluates rules in order until one matches
68
-
4.Returns the first matching rule or fails if none match
66
+
1.Reads the `context_rule_ids` from the `AuthPayload` (one rule ID per auth context)
67
+
2.Looks up each rule directly by ID
68
+
3.Validates the rule is not expired and matches the context type
69
+
4.Authenticates signers and enforces policies, or fails if conditions aren't met
69
70
70
71
For detailed documentation on the authorization flow, see [Authorization Flow](/stellar-contracts/accounts/authorization-flow).
71
72
@@ -88,7 +89,7 @@ graph TD
88
89
SA --- CR3
89
90
SA --- CR4
90
91
91
-
style SA fill:#E8E8E8,stroke:#333,stroke-width:2px
92
+
style SA fill:transparent,stroke:#888,stroke-width:2px
0 commit comments