ash_grant: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

AshGrant is a permission-based authorization extension for Ash Framework. It provides an Apache Shiro-inspired permission system with deny-wins semantics, supporting both RBAC and resource-instance permissions.

Language Policy

All repository content must be written in English, including:

• README.md, CHANGELOG.md, and all documentation
• Code comments and docstrings (@moduledoc, @doc)
• Commit messages and PR descriptions
• CLAUDE.md instructions

Common Commands

# Run tests (auto-creates and migrates test DB)
mix test

# Run a single test file
mix test test/ash_grant/permission_test.exs

# Run a specific test by line number
mix test test/ash_grant/permission_test.exs:42

# Linting
mix credo

# Type checking
mix dialyzer

# Generate documentation
mix docs

# Database management (test only)
mix ecto.setup    # Create and migrate
mix ecto.reset    # Drop, create, and migrate

# Policy configuration testing (NOT mix test)
mix ash_grant.verify test/support/policy_test_fixtures.ex
mix ash_grant.verify priv/policy_tests/           # Run all YAML tests
mix ash_grant.verify path/to/test.yaml --verbose  # Verbose output

Architecture

Core Modules

• AshGrant (lib/ash_grant.ex) - Main extension module, exports check/1 and filter_check/1
• AshGrant.Dsl (lib/ash_grant/dsl.ex) - Spark DSL definition for the ash_grant block
• AshGrant.Permission (lib/ash_grant/permission.ex) - Parses and matches permission strings (resource:instance_id:action:scope). Also exposes diagnostics/1, which reports deprecated/dead grant syntax for offline auditing (never affects authorization)
• AshGrant.Evaluator (lib/ash_grant/evaluator.ex) - Implements deny-wins evaluation logic

Policy Checks

• AshGrant.Check (lib/ash_grant/checks/check.ex) - SimpleCheck for write actions (returns true/false)
• AshGrant.FilterCheck (lib/ash_grant/checks/filter_check.ex) - FilterCheck for read actions (returns filter expression)
• AshGrant.PermissionValidation (lib/ash_grant/permission_validation.ex) - Validates resolved permissions and signals invalid deny+field_group combinations per the field_group_permissions mode (:off/:warn/:strict); never changes the authorization outcome
• AshGrant.IndeterminateMatch (lib/ash_grant/indeterminate_match.ex) - Signals when an Evaluator entry point returns a value that couldn't actually be determined: a type wildcard evaluated with no action_type is silently skipped, so the answer may be wrong (#126, layer 2). Wraps every nil-defaulting entry point (has_access?, get_scope, get_all_scopes, get_write_scopes, get_field_group, get_all_field_groups, find_matching, field_group_grants). Mode :off/:warn/:strict via config :ash_grant, indeterminate_type_wildcard:; never changes the outcome. Sound by construction: guard/6 recomputes the result with the skipped wildcards forced to match and signals only if it differs — so a scope-less/group-less wildcard or a concrete-deny-settled query stays silent (no false positives, which would break :strict). get_matching_instance_ids is unguarded on purpose (it sees only instance perms, where type wildcards are dead per diagnostics/1, not indeterminate)
• AshGrant.FieldFilterCheck (lib/ash_grant/checks/field_filter_check.ex) - FilterCheck for per-record field-group visibility; generated into field_policies by AddFieldPolicies. Builds a per-row predicate from Evaluator.field_group_grants/5 (a field is visible on some records, %Ash.ForbiddenField{} on others)
• AshGrant.FieldCheck (lib/ash_grant/checks/field_check.ex) - legacy action-wide SimpleCheck for field groups (superseded by FieldFilterCheck in generation; still present)