<%= @member.name %>
- Email
- <%= @member.email %>
- Address
- <%= @member.address %>
<%= if can?(@current_user, :update, @member) do %>
<.link patch={~p"/members/#{@member.id}/edit"} class="btn-primary">
Edit Member
<% end %>
```
---
## Special Cases
### 1. Own Credentials Access
**Requirement:** Every user can ALWAYS read and update their own credentials (email, password), regardless of their role.
**Implementation:**
Policy in `User` resource uses a two-tier approach:
- **READ**: Bypass with `expr()` for list queries (auto_filter)
- **UPDATE**: HasPermission with `scope :own` (evaluates PermissionSets)
```elixir
policies do
# SPECIAL CASE: Users can always READ their own account
# Bypass needed for list queries (expr() triggers auto_filter in Ash)
bypass action_type(:read) do
description "Users can always read their own account"
authorize_if expr(id == ^actor(:id))
end
# GENERAL: Check permissions from user's role
# UPDATE uses scope :own from PermissionSets (all sets grant User.update :own)
policy action_type([:read, :create, :update, :destroy]) do
authorize_if Mv.Authorization.Checks.HasPermission
end
end
```
**Why this works:**
- READ bypass handles list queries correctly (auto_filter)
- UPDATE is handled by HasPermission with `scope :own` from PermissionSets
- All permission sets (`:own_data`, `:read_only`, `:normal_user`, `:admin`) grant `User.update :own`
- Even a user with `read_only` (read-only for member data) can update their own credentials
**Important:** UPDATE is NOT an unverrückbarer Spezialfall (hardcoded bypass). It is controlled by PermissionSets. If a permission set is changed to remove `User.update :own`, users with that set will lose the ability to update their credentials. See "User Credentials: Why read_only Can Still Update" below for details.
### 1a. User Credentials: Why read_only Can Still Update
**Question:** If `read_only` means "read-only", why can users with this permission set still update their own credentials?
**Answer:** The `read_only` permission set refers to **member data**, NOT user credentials. All permission sets grant `User.update :own` to allow password changes and profile updates.
**Implementation Details:**
1. **UPDATE is controlled by PermissionSets**, not a hardcoded bypass
2. **All 4 permission sets** (`:own_data`, `:read_only`, `:normal_user`, `:admin`) explicitly grant:
```elixir
%{resource: "User", action: :update, scope: :own, granted: true}
```
3. **HasPermission** evaluates `scope :own` for UPDATE operations (when a changeset with record is present)
4. **No special bypass** is needed for UPDATE - it works correctly via HasPermission
**Why This Design?**
- **Flexibility:** Permission sets can be modified to change UPDATE behavior
- **Consistency:** All permissions are centralized in PermissionSets
- **Clarity:** The name "read_only" refers to member data, not user credentials
- **Maintainability:** Easy to see what each role can do in PermissionSets module
**Warning:** If a permission set is changed to remove `User.update :own`, users with that set will **lose the ability to update their credentials**. This is intentional - UPDATE is controlled by PermissionSets, not hardcoded.
**Example:**
```elixir
# In PermissionSets.get_permissions(:read_only)
resources: [
# User: Can read/update own credentials only
# IMPORTANT: "read_only" refers to member data, NOT user credentials.
# All permission sets grant User.update :own to allow password changes.
%{resource: "User", action: :read, scope: :own, granted: true},
%{resource: "User", action: :update, scope: :own, granted: true},
# Member: Can read all members, no modifications
%{resource: "Member", action: :read, scope: :all, granted: true},
# Note: No Member.update permission - this is the "read_only" part
]
```
### 2. Linked Member Email Editing
**Requirement:** Only administrators can edit the email of a member that is linked to a user (has `user_id` set). This prevents breaking email synchronization.
**Implementation:**
Custom validation in `Member` resource:
```elixir
defmodule Mv.Membership.Member do
use Ash.Resource, ...
validations do
# Only run when email is being changed
validate changing(:email), on: :update do
validate &validate_linked_member_email_change/2
end
end
defp validate_linked_member_email_change(changeset, _context) do
member = changeset.data
actor = changeset.context[:actor]
# If member is not linked to user, allow change
if is_nil(member.user_id) do
:ok
else
# Member is linked - check if actor is admin
if has_admin_permission?(actor) do
:ok
else
{:error, "Only administrators can change email for members linked to user accounts"}
end
end
end
defp has_admin_permission?(nil), do: false
defp has_admin_permission?(actor) do
with %{role: %{permission_set_name: ps_name}} <- actor,
{:ok, ps_atom} <- PermissionSets.permission_set_name_to_atom(ps_name),
permissions <- PermissionSets.get_permissions(ps_atom) do
# Check if actor has User.update permission with scope :all (admin privilege)
Enum.any?(permissions.resources, fn perm ->
perm.resource == "User" and
perm.action == :update and
perm.scope == :all and
perm.granted
end)
else
_ -> false
end
end
end
```
**Why this is needed:**
- Member email and User email are kept in sync
- If a non-admin changes linked member email, it could create inconsistency
- Validation runs AFTER policy check, so normal_user can update member
- But validation blocks email field specifically if member is linked
### 3. System Role Protection
**Requirement:** The "Mitglied" role cannot be deleted because it's the default role for all users.
**Implementation:**
Flag + validation in `Role` resource:
```elixir
defmodule Mv.Authorization.Role do
use Ash.Resource, ...
attributes do
# ...
attribute :is_system_role, :boolean, default: false
end
validations do
validate action(:destroy) do
validate fn _changeset, %{data: role} ->
if role.is_system_role do
{:error, "Cannot delete system role. System roles are required for the application to function."}
else
:ok
end
end
end
end
end
```
**Seeds set the flag:**
```elixir
%{
name: "Mitglied",
permission_set_name: "own_data",
is_system_role: true # <-- Protected!
}
```
**UI hides delete button:**
```heex
<%= if can?(@current_user, :destroy, role) and not role.is_system_role do %>
<.button phx-click="delete">Delete
<% end %>
```
### 4. User Without Role (Edge Case)
**Requirement:** Users without a role should be denied all access (except logout).
**Implementation:**
**Default Assignment:** Seeds assign "Mitglied" role to all existing users
```elixir
# In authorization_seeds.exs
mitglied_role = Ash.get!(Role, name: "Mitglied")
users_without_role = Ash.read!(User, filter: expr(is_nil(role_id)))
Enum.each(users_without_role, fn user ->
Ash.update!(user, %{role_id: mitglied_role.id})
end)
```
**Runtime Handling:** All authorization checks handle missing role gracefully
```elixir
# In HasPermission check
def match?(actor, %{resource: resource, action: action}, _opts) do
with %{role: %{permission_set_name: ps_name}} when not is_nil(ps_name) <- actor,
# ...
else
%{role: nil} ->
{:error, :no_role} # User has no role -> forbidden
_ ->
{:error, :no_permission}
end
end
```
**Result:** User with no role sees empty UI, cannot access pages, gets forbidden on all actions.
### 5. Invalid permission_set_name (Edge Case)
**Requirement:** If a role has an invalid `permission_set_name`, fail gracefully without crashing.
**Implementation:**
**Prevention:** Validation on Role resource
```elixir
validations do
validate attribute(:permission_set_name) do
validate fn _changeset, value ->
if PermissionSets.valid_permission_set?(value) do
:ok
else
{:error, "Invalid permission set name. Must be one of: #{Enum.join(PermissionSets.all_permission_sets(), ", ")}"}
end
end
end
end
```
**Runtime Handling:** All lookups check validity
```elixir
# In PermissionSets module
def permission_set_name_to_atom(name) when is_binary(name) do
atom = String.to_existing_atom(name)
if valid_permission_set?(atom) do
{:ok, atom}
else
{:error, :invalid_permission_set}
end
rescue
ArgumentError -> {:error, :invalid_permission_set}
end
```
**Result:** Invalid `permission_set_name` → authorization fails → forbidden (safe default).
---
## User-Member Linking
### Requirement
Users and Members are separate entities that can be linked. Special rules:
- Only admins can link/unlink users and members
- A user cannot link themselves to an existing member
- A user CAN create a new member and be directly linked to it (self-service)
**Enforcement:** The User resource restricts the `update_user` action (which accepts the `member` argument for link/unlink) to admins only via `Mv.Authorization.Checks.ActorIsAdmin`. The UserLive.Form shows the Member-Linking UI and runs member link/unlink on save only when the current user is admin; non-admins use the `:update` action (email only) for profile edit.
### Approach: Separate Ash Actions
We use **different Ash actions** to enforce different policies:
1. **`create_member_for_self`** - User creates member and links to themselves
2. **`create_member`** - Admin creates member for any user (or unlinked)
3. **`link_member_to_user`** - Admin links existing member to user
4. **`unlink_member_from_user`** - Admin removes user link
5. **`update`** - Standard update (cannot change `user_id`)
### Implementation
```elixir
defmodule Mv.Membership.Member do
use Ash.Resource, ...
actions do
# SELF-SERVICE: User creates member and links to self
create :create_member_for_self do
description "User creates a new member and links it to their own account"
accept [:name, :email, :address, ...] # All fields except user_id
# Automatically set user_id to actor
change set_attribute(:user_id, actor(:id))
# Prevent creating multiple members for same user (optional business rule)
validate fn changeset, _context ->
actor_id = get_change(changeset, :user_id)
case Ash.read(Member, filter: expr(user_id == ^actor_id)) do
{:ok, []} -> :ok # No existing member, allow
{:ok, [_member | _]} -> {:error, "You already have a member profile"}
{:error, _} -> :ok
end
end
end
# ADMIN: Create member with optional user link
create :create_member do
description "Admin creates a new member, optionally linked to a user"
accept [:name, :email, :address, ..., :user_id] # Admin can set user_id
end
# ADMIN: Link existing member to user
update :link_member_to_user do
description "Admin links an existing member to a user account"
accept [:user_id]
validate fn changeset, _context ->
member = changeset.data
# Cannot link if already linked
if is_nil(member.user_id) do
:ok
else
{:error, "Member is already linked to a user"}
end
end
end
# ADMIN: Remove user link from member
update :unlink_member_from_user do
description "Admin removes user link from member"
change set_attribute(:user_id, nil)
end
# STANDARD UPDATE: Cannot change user_id
update :update do
description "Update member data (cannot change user link)"
accept [:name, :email, :address, ...] # user_id NOT in accept list
end
end
policies do
# Self-service member creation
policy action(:create_member_for_self) do
description "Any authenticated user can create member for themselves"
authorize_if actor_present()
end
# Admin-only actions
policy action([:create_member, :link_member_to_user, :unlink_member_from_user]) do
description "Only admin can manage user-member links"
authorize_if Mv.Authorization.Checks.HasPermission
end
# Standard actions (regular permission check)
policy action([:read, :update, :destroy]) do
authorize_if Mv.Authorization.Checks.HasPermission
end
end
end
```
### UI Examples
**User Self-Service:**
```heex
<%= if is_nil(@current_user.member_id) do %>
<.link navigate="/members/new_for_self">
Create My Member Profile
<% end %>
<.simple_form for={@form} phx-submit="create_for_self">
<.input field={@form[:name]} label="Name" />
<.input field={@form[:email]} label="Email" />
<.input field={@form[:address]} label="Address" />
<:actions>
<.button>Create My Profile
```
**Admin Interface:**
```heex
<%= if can?(@current_user, :link_member_to_user, @member) do %>
<%= if is_nil(@member.user_id) do %>
<.form for={@link_form} phx-submit="link_to_user">
<.input field={@link_form[:user_id]} type="select" label="Link to User" options={@users} />
<.button>Link to User
<% else %>
<.button phx-click="unlink_from_user" phx-value-id={@member.id}>
Unlink from User (<%= @member.user.email %>)
<% end %>
<% end %>
```
### Why Separate Actions?
✅ **Clear Intent:** Action name communicates what's happening
✅ **Precise Policies:** Different policies for different operations
✅ **Better UX:** Separate UI flows for self-service vs. admin
✅ **Testable:** Each action can be tested independently
✅ **Idiomatic Ash:** Uses Ash's action system as designed
---
## Future: Phase 2 - Field-Level Permissions
**Status:** Not in MVP, planned for future enhancement
**Goal:** Control which fields a user can read or write, beyond resource-level permissions.
### Strategy
**Extend PermissionSets module with `:fields` key:**
```elixir
def get_permissions(:read_only) do
%{
resources: [...],
pages: [...],
fields: [
# Vorstand can read all member fields except sensitive payment info
%{
resource: "Member",
action: :read,
fields: [:all],
excluded_fields: [:payment_method, :bank_account]
},
# Vorstand cannot write any member fields
%{
resource: "Member",
action: :update,
fields: [] # Empty = no fields writable
}
]
}
end
```
**Read Filtering via Ash Calculations:**
```elixir
defmodule Mv.Membership.Member do
calculations do
calculate :filtered_fields, :map do
calculate fn members, context ->
actor = context[:actor]
# Get allowed fields from PermissionSets
allowed_fields = get_allowed_read_fields(actor, "Member")
# Filter fields
Enum.map(members, fn member ->
Map.take(member, allowed_fields)
end)
end
end
end
end
```
**Write Protection via Custom Validations:**
```elixir
validations do
validate on: :update do
validate fn changeset, context ->
actor = context[:actor]
changed_fields = Map.keys(changeset.attributes)
# Get allowed fields from PermissionSets
allowed_fields = get_allowed_write_fields(actor, "Member")
# Check if any forbidden field is being changed
forbidden = Enum.reject(changed_fields, &(&1 in allowed_fields))
if Enum.empty?(forbidden) do
:ok
else
{:error, "You do not have permission to modify: #{Enum.join(forbidden, ", ")}"}
end
end
end
end
```
**Benefits:**
- ✅ No database schema changes
- ✅ Still uses hardcoded PermissionSets
- ✅ Granular control over sensitive fields
- ✅ Clear error messages
**Estimated Effort:** 2-3 weeks
---
## Future: Phase 3 - Database-Backed Permissions
**Status:** Not in MVP, planned for future when runtime configuration is needed
**Goal:** Move permission definitions from code to database for runtime configuration.
### High-Level Design
**New Tables:**
```sql
CREATE TABLE permission_sets (
id UUID PRIMARY KEY,
name VARCHAR(50) UNIQUE,
description TEXT,
is_system BOOLEAN
);
CREATE TABLE permission_set_resources (
id UUID PRIMARY KEY,
permission_set_id UUID REFERENCES permission_sets(id),
resource_name VARCHAR(100),
action VARCHAR(20),
scope VARCHAR(20),
granted BOOLEAN
);
CREATE TABLE permission_set_pages (
id UUID PRIMARY KEY,
permission_set_id UUID REFERENCES permission_sets(id),
page_pattern VARCHAR(255)
);
```
**Migration Strategy:**
1. Create new tables
2. Seed from current `PermissionSets` module
3. Create new `HasResourcePermission` check that queries DB
4. Add ETS cache for performance
5. Replace `HasPermission` with `HasResourcePermission` in policies
6. Test thoroughly
7. Deploy
8. Eventually remove `PermissionSets` module
**ETS Cache:**
```elixir
defmodule Mv.Authorization.PermissionCache do
def get_permissions(permission_set_id) do
case :ets.lookup(:permission_cache, permission_set_id) do
[{^permission_set_id, permissions}] ->
permissions
[] ->
permissions = load_from_db(permission_set_id)
:ets.insert(:permission_cache, {permission_set_id, permissions})
permissions
end
end
def invalidate(permission_set_id) do
:ets.delete(:permission_cache, permission_set_id)
end
end
```
**Benefits:**
- ✅ Runtime permission configuration
- ✅ More flexible than hardcoded
- ✅ Can add new permission sets without code changes
**Trade-offs:**
- ⚠️ More complex (DB queries, cache, invalidation)
- ⚠️ Slightly slower (mitigated by cache)
- ⚠️ More testing needed
**Estimated Effort:** 3-4 weeks
**Decision Point:** Migrate to Phase 3 only if:
- Need to add permission sets frequently
- Need per-tenant permission customization
- MVP hardcoded approach is limiting business
See [Migration Strategy](#migration-strategy) for detailed migration plan.
---
## Migration Strategy
### Three-Phase Approach
**Phase 1: MVP (2-3 weeks) - CURRENT**
- Hardcoded PermissionSets module
- `HasPermission` check reads from module
- Role table with `permission_set_name` string
- Zero DB queries for permission checks
**Phase 2: Field-Level (2-3 weeks) - FUTURE**
- Extend PermissionSets with `:fields` key
- Ash Calculations for read filtering
- Custom Validations for write protection
- No database schema changes
**Phase 3: Database-Backed (3-4 weeks) - FUTURE**
- New tables: `permission_sets`, `permission_set_resources`, `permission_set_pages`
- New `HasResourcePermission` check queries DB
- ETS cache for performance
- Runtime permission configuration
### When to Migrate?
**Stay with MVP if:**
- 4 permission sets are sufficient
- Permission changes are rare (quarterly or less)
- Code deployments for permission changes are acceptable
- Performance is critical (< 1μs checks)
**Migrate to Phase 2 if:**
- Need field-level granularity
- Different roles need access to different fields
- Still OK with hardcoded permissions
**Migrate to Phase 3 if:**
- Need frequent permission changes
- Need per-tenant customization
- Want non-technical users to configure permissions
- OK with slightly more complex system
### Migration from MVP to Phase 3
**Step-by-step:**
1. **Create DB Tables** (1 day)
- Run migrations for `permission_sets`, `permission_set_resources`, `permission_set_pages`
- Add indexes
2. **Seed from PermissionSets Module** (1 day)
- Script that reads from `PermissionSets.get_permissions/1`
- Inserts into new tables
- Verify data integrity
3. **Create HasResourcePermission Check** (2 days)
- New check that queries DB
- Same logic as `HasPermission` but different data source
- Comprehensive tests
4. **Implement ETS Cache** (2 days)
- Cache module
- Cache invalidation on updates
- Performance tests
5. **Update Policies** (3 days)
- Replace `HasPermission` with `HasResourcePermission` in all resources
- Test each resource thoroughly
6. **Update UI Helpers** (1 day)
- Modify `MvWeb.Authorization` to query DB
- Use cache for performance
7. **Update Page Plug** (1 day)
- Modify `CheckPagePermission` to query DB
- Use cache
8. **Integration Testing** (3 days)
- Full user journey tests
- Performance testing
- Load testing
9. **Deploy to Staging** (1 day)
- Feature flag approach
- Run both systems in parallel
- Compare results
10. **Deploy to Production** (1 day)
- Gradual rollout
- Monitor performance
- Rollback plan ready
11. **Cleanup** (1 day)
- Remove old `HasPermission` check
- Remove `PermissionSets` module
- Update documentation
**Total:** ~3-4 weeks
---
## Security Considerations
### Threat Model
**Threats Addressed:**
1. **Unauthorized Data Access:** Policies prevent users from accessing data outside their permissions
2. **Privilege Escalation:** Role-based system prevents users from granting themselves higher privileges
3. **UI Tampering:** Backend policies enforce authorization even if UI is bypassed
4. **Session Hijacking:** Mitigation handled by existing authentication system (not in scope)
**Threats NOT Addressed:**
1. **SQL Injection:** Ash Framework handles query building securely
2. **XSS:** Phoenix LiveView handles HTML escaping
3. **CSRF:** Phoenix CSRF tokens (existing)
### Defense in Depth
**Three Layers of Authorization:**
1. **Page Access Layer (Plug):**
- Blocks unauthorized page access
- Runs before LiveView mounts
- Fast fail for obvious violations
2. **UI Layer (Authorization Helpers):**
- Hides buttons/links user can't use
- Prevents confusing "forbidden" errors
- Improves UX
3. **Resource Layer (Ash Policies):**
- **Primary enforcement point**
- Cannot be bypassed
- Filters queries automatically
**Even if attacker:**
- Tampers with UI → Backend policies still enforce
- Calls API directly → Policies apply
- Modifies page JavaScript → Policies apply
### Authorization Best Practices
**DO:**
- ✅ Always preload `:role` relationship for actor
- ✅ Log authorization failures for debugging
- ✅ Use explicit policies (no implicit allow)
- ✅ Test policies with all role types
- ✅ Test special cases (nil role, invalid permission_set_name)
**DON'T:**
- ❌ Trust UI-level checks alone
- ❌ Skip policy checks for "admin"
- ❌ Use `bypass` or `skip_authorization` in production
- ❌ Expose raw permission logic in API responses
### Audit Logging (Future)
**Not in MVP, but planned:**
```elixir
defmodule Mv.Authorization.AuditLog do
def log_authorization_failure(actor, resource, action, reason) do
Ash.create!(AuditLog, %{
user_id: actor.id,
resource: inspect(resource),
action: action,
outcome: "forbidden",
reason: reason,
ip_address: get_ip_address(),
timestamp: DateTime.utc_now()
})
end
end
```
**Benefits:**
- Track suspicious authorization attempts
- Compliance (GDPR requires access logs)
- Debugging production issues
---
## Appendix
### Glossary
- **Permission Set:** Named collection of permissions (e.g., "admin", "read_only")
- **Role:** Database entity linking users to permission sets
- **Scope:** Range of records permission applies to (:own, :linked, :all)
- **Actor:** Currently authenticated user in Ash context
- **Policy:** Ash authorization rule on a resource
- **System Role:** Role that cannot be deleted (is_system_role=true)
- **Special Case:** Authorization rule that takes precedence over general permissions
### Resource Name Mapping
The `HasPermission` check extracts resource names via `Module.split() |> List.last()`:
| Ash Module | Resource Name (String) |
|------------|------------------------|
| `Mv.Accounts.User` | "User" |
| `Mv.Membership.Member` | "Member" |
| `Mv.Membership.CustomFieldValue` | "CustomFieldValue" |
| `Mv.Membership.CustomField` | "CustomField" |
| `Mv.Authorization.Role` | "Role" |
These strings must match exactly in `PermissionSets` module.
### Permission Set Summary
| Permission Set | Typical Roles | Key Characteristics |
|----------------|---------------|---------------------|
| **own_data** | Mitglied | Can only access own data and linked member |
| **read_only** | Vorstand, Buchhaltung | Read all data, no modifications |
| **normal_user** | Kassenwart | Create/Read/Update members (no delete), full CRUD on properties, no admin |
| **admin** | Admin | Unrestricted access, wildcard pages |
### Edge Case Reference
| Edge Case | Behavior | Implementation |
|-----------|----------|----------------|
| User without role | Access denied everywhere | Seeds assign default role, runtime checks handle gracefully |
| Invalid permission_set_name | Access denied | Validation on Role, runtime safety checks |
| System role deletion | Forbidden | Validation prevents deletion if `is_system_role=true` |
| Linked member email | Admin-only edit | Custom validation in Member resource |
| Own credentials | Always accessible | Special policy before general check |
### Testing Checklist
**For Each Resource:**
- [ ] All 5 roles tested (Mitglied, Vorstand, Kassenwart, Buchhaltung, Admin)
- [ ] All actions tested (read, create, update, destroy)
- [ ] All scopes tested (own, linked, all)
- [ ] Special cases tested
- [ ] Edge cases tested (nil role, invalid permission_set_name)
**For UI:**
- [ ] Buttons/links show/hide correctly per role
- [ ] Page access controlled per role
- [ ] No broken links (all visible links are accessible)
**Integration:**
- [ ] One complete user journey per role
- [ ] Cross-resource scenarios (e.g., Member -> CustomFieldValue)
- [ ] Special cases in context (e.g., linked member email during full edit flow)
### Useful Commands
```bash
# Run all authorization tests
mix test test/mv/authorization
# Run integration tests
mix test test/integration
# Run with coverage
mix test --cover
# Generate migrations
mix ash.codegen
# Run seeds
mix run priv/repo/seeds/authorization_seeds.exs
# Check permission for user in IEx
iex> user = Mv.Accounts.get_user!("user-id")
iex> MvWeb.Authorization.can?(user, :create, Mv.Membership.Member)
# Check page access in IEx
iex> MvWeb.Authorization.can_access_page?(user, "/members/new")
```
---
## Authorization Bootstrap Patterns
This section clarifies three different mechanisms for bypassing standard authorization, their purposes, and when to use each.
### Overview
The codebase uses two authorization bypass mechanisms:
1. **system_actor** - Admin user for systemic operations
2. **authorize?: false** - Bootstrap bypass for circular dependencies
**Both are necessary and serve different purposes.**
**Note:** The NoActor bypass has been removed to prevent masking authorization bugs in tests. All tests now explicitly use `system_actor` for authorization.
### 1. System Actor
**Purpose:** Admin user for systemic operations that must always succeed regardless of user permissions.
**Implementation:**
```elixir
system_actor = Mv.Helpers.SystemActor.get_system_actor()
# => %User{email: "system@mila.local", role: %{permission_set_name: "admin"}}
```
**Security:**
- No password (hashed_password = nil) → cannot login
- No OIDC ID (oidc_id = nil) → cannot authenticate
- Cached in Agent for performance
- Created automatically in test environment if missing
**Use Cases:**
- **Email synchronization** (User ↔ Member email sync)
- **Email uniqueness validation** (cross-resource checks)
- **Cycle generation** (mandatory side effect)
- **OIDC account linking** (user not yet logged in)
- **Cross-resource validations** (must work regardless of actor)
**Example:**
```elixir
def get_linked_member(%{member_id: id}) do
system_actor = SystemActor.get_system_actor()
opts = Helpers.ash_actor_opts(system_actor)
# Email sync must work regardless of user permissions
Ash.get(Mv.Membership.Member, id, opts)
end
```
**Why not `authorize?: false`?**
- System actor is explicit (clear intent: "systemic operation")
- Policies are evaluated (with admin rights)
- Audit trail (actor.email = "system@mila.local")
- Consistent authorization flow
- Testable
### 2. authorize?: false
**Purpose:** Skip policies for bootstrap scenarios with circular dependencies.
**Use Cases:**
**1. Seeds** - No admin exists yet to use as actor:
```elixir
# priv/repo/seeds.exs
Accounts.create_user!(%{email: admin_email},
authorize?: false # Bootstrap: no admin exists yet
)
```
**2. SystemActor Bootstrap** - Chicken-and-egg problem:
```elixir
# lib/mv/helpers/system_actor.ex
defp find_user_by_email(email) do
# Need to find system actor, but loading requires system actor!
Mv.Accounts.User
|> Ash.Query.filter(email == ^email)
|> Ash.read_one(authorize?: false) # Bootstrap only
end
```
**3. Actor.ensure_loaded** - Circular dependency:
```elixir
# lib/mv/authorization/actor.ex
defp load_role(actor) do
# Actor needs role for authorization,
# but loading role requires authorization!
Ash.load(actor, :role, authorize?: false) # Bootstrap only
end
```
**4. assign_default_role** - User creation:
```elixir
# User doesn't have actor during creation
Mv.Authorization.Role
|> Ash.Query.filter(name == "Mitglied")
|> Ash.read_one(authorize?: false) # Bootstrap only
```
**Security:**
- Very powerful - skips ALL policies
- Use sparingly and document every usage
- Only for bootstrap scenarios
- All current usages are legitimate
### Comparison
| Aspect | system_actor | authorize?: false |
|--------|--------------|-------------------|
| **Environment** | All | All |
| **Actor** | Admin user | nil |
| **Policies** | Evaluated | Skipped |
| **Audit Trail** | Yes (system@mila.local) | No |
| **Use Case** | Systemic operations, test fixtures | Bootstrap |
| **Explicit?** | Function call | Query option |
### Decision Guide
**Use system_actor when:**
- ✅ Systemic operation must always succeed
- ✅ Email synchronization
- ✅ Cycle generation
- ✅ Cross-resource validations
- ✅ OIDC flows (user not logged in)
**Use authorize?: false when:**
- ✅ Bootstrap scenario (seeds)
- ✅ Circular dependency (SystemActor bootstrap, Actor.ensure_loaded)
- ⚠️ Document with comment explaining why
**DON'T:**
- ❌ Use `authorize?: false` for user-initiated actions
- ❌ Use `authorize?: false` when `system_actor` would work
- ❌ Skip actor in tests (always use system_actor)
### The Circular Dependency Problem
**SystemActor Bootstrap:**
```
SystemActor.get_system_actor()
↓ calls find_user_by_email()
↓ needs to query User
↓ User policies require actor
↓ but we're loading the actor!
Solution: authorize?: false for bootstrap query
```
**Actor.ensure_loaded:**
```
Authorization check (HasPermission)
↓ needs actor.role.permission_set_name
↓ but role is %Ash.NotLoaded{}
↓ load role with Ash.load(actor, :role)
↓ but loading requires authorization
↓ which needs actor.role!
Solution: authorize?: false for role load
```
**Why this is safe:**
- Actor is loading their OWN data (role relationship)
- Actor already passed authentication boundary
- Role contains no sensitive data (just permission_set reference)
- Alternative (denormalize permission_set_name) adds complexity
### Examples
**Good - system_actor for systemic operation:**
```elixir
defp check_if_email_used(email) do
system_actor = SystemActor.get_system_actor()
opts = Helpers.ash_actor_opts(system_actor)
# Validation must work regardless of current actor
Ash.read(User, opts)
end
```
**Good - authorize?: false for bootstrap:**
```elixir
# Seeds - no admin exists yet
Accounts.create_user!(%{email: admin_email}, authorize?: false)
```
**Bad - authorize?: false for user action:**
```elixir
# WRONG: Bypasses all policies for user-initiated action
def delete_member(member) do
Ash.destroy(member, authorize?: false) # ❌ Don't do this!
end
# CORRECT: Use actor
def delete_member(member, actor) do
Ash.destroy(member, actor: actor) # ✅ Policies enforced
end
```
---
**Document Version:** 2.0 (Clean Rewrite)
**Last Updated:** 2026-01-23
**Implementation Status:** ✅ Complete (2026-01-08)
**Status:** Ready for Implementation
**Changes from V1:**
- Complete rewrite focused on MVP (hardcoded permissions)
- Removed all database-backed permission details from MVP sections
- Unified naming (HasPermission for MVP)
- Added Role resource policies
- Clarified resource-specific :linked scope
- Moved Phase 2 and Phase 3 to clearly marked "Future" sections
- Fixed Buchhaltung inconsistency (read_only everywhere)
- Added comprehensive security section
- Enhanced edge case documentation
**Changes from V2.0:**
- Added "Authorization Bootstrap Patterns" section explaining system_actor and authorize?: false
- Removed NoActor bypass (all tests now use system_actor for explicit authorization)
---
**End of Architecture Document**