<%= @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 places this check BEFORE the general `HasPermission` check:
```elixir
policies do
# SPECIAL CASE: Takes precedence over role permissions
policy action_type([:read, :update]) do
description "Users can always read and update their own account"
authorize_if expr(id == ^actor(:id))
end
# GENERAL: For other operations (e.g., admin reading other users)
policy action_type([:read, :create, :update, :destroy]) do
authorize_if Mv.Authorization.Checks.HasPermission
end
end
```
**Why this works:**
- Ash evaluates policies top-to-bottom
- First matching policy wins
- Special case catches own-account access before checking permissions
- Even a user with `own_data` (no admin permissions) can update their credentials
### 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)
### 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.Property` | "Property" |
| `Mv.Membership.PropertyType` | "PropertyType" |
| `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 -> Property)
- [ ] 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")
```
---
**Document Version:** 2.0 (Clean Rewrite)
**Last Updated:** 2025-01-13
**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
---
**End of Architecture Document**