docs: add authorization bootstrap patterns section
All checks were successful
continuous-integration/drone/push Build is passing

Document the three authorization bypass mechanisms and when to use each:
- NoActor (test-only bypass)
- system_actor (systemic operations)
- authorize?: false (bootstrap scenarios)
This commit is contained in:
Moritz 2026-01-23 02:53:20 +01:00
parent 41e342a1d6
commit c98ad4085a
Signed by: moritz
GPG key ID: 1020A035E5DD0824
2 changed files with 275 additions and 1 deletions

View file

@ -688,6 +688,44 @@ end
- **User Mode**: User-initiated actions use the actual user actor, policies are enforced
- **System Mode**: Systemic operations use system actor, bypass user permissions
**Authorization Bootstrap Patterns:**
Three mechanisms exist for bypassing standard authorization:
1. **NoActor** (test only) - Allows operations without actor in test environment
```elixir
# Automatically enabled in tests via config/test.exs
# Policies use: bypass action_type(...) do authorize_if NoActor end
member = create_member(%{name: "Test"}) # Works in tests
```
2. **system_actor** (systemic operations) - Admin user for operations that must always succeed
```elixir
# Good: Systemic operation
system_actor = SystemActor.get_system_actor()
Ash.read(Member, actor: system_actor)
# Bad: User-initiated action
# Never use system_actor for user-initiated actions!
```
3. **authorize?: false** (bootstrap only) - Skips policies for circular dependencies
```elixir
# Good: Bootstrap (seeds, SystemActor loading)
Accounts.create_user!(%{email: admin_email}, authorize?: false)
# Bad: User-initiated action
Ash.destroy(member, authorize?: false) # Never do this!
```
**Decision Guide:**
- Use **NoActor** for test fixtures (automatic via config)
- Use **system_actor** for email sync, cycle generation, validations
- Use **authorize?: false** only for bootstrap (seeds, circular dependencies)
- Always document why `authorize?: false` is necessary
**See also:** `docs/roles-and-permissions-architecture.md` (Authorization Bootstrap Patterns section)
### 3.4 Ash Framework
**Resource Definition Best Practices:**