# AshIAM

AWS IAM-style policy evaluation for Ash Framework.

This extension provides IAM-style authorization for Ash resources using AWS IAM-like policy documents. It supports wildcard matching, deny precedence, configurable policy sources, and multiple policy documents.

## Features

- **AWS IAM-compatible policy evaluation** - Uses the same logic as AWS IAM
- **High-performance authorization** - Sub-microsecond evaluation with regex caching
- **Multiple policy documents** - Support for both single and multiple policy documents
- **Deny precedence** - Explicit deny statements override allow statements
- **Wildcard matching** - Support for wildcard patterns in resources and actions
- **Configurable policy sources** - Get policies from actor attributes or custom fetchers
- **Ash integration** - Seamlessly integrates with Ash.Policy.Authorizer

## Performance

AshIam is optimized for production use with much Claude README enthusiasm!

- **~2μs average evaluation time** for simple policies
- **100x+ performance improvement** over basic implementations
- **Regex pattern caching** to avoid recompilation
- **Early termination** on explicit deny statements
- **ETS-based caching** for compiled patterns

See [PERFORMANCE.md](PERFORMANCE.md) for detailed benchmarks and optimization guide.

## Installation

The package can be installed by adding `ash_iam` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:ash_iam, "~> 1.1.0"}
  ]
end
```

## Quick Start

1. Add the extension to your resource:

```elixir
defmodule MyApp.User do
  use Ash.Resource,
    domain: MyApp.Domain,
    data_layer: Ash.DataLayer.Ets,
    authorizers: [Ash.Policy.Authorizer],
    extensions: [AshIam]

  # ... your resource definition

  iam do
    permission_base "myapp:user"
  end
end
```

2. Provide IAM policy documents in your actor:

```elixir
actor = %{
  iam_policy: %{
    "Statement" => [
      %{"Effect" => "Allow", "Action" => ["*"], "Resource" => ["myapp:user:*"]},
      %{"Effect" => "Deny", "Action" => ["destroy"], "Resource" => ["myapp:user:5"]}
    ]
  }
}

# Policies are automatically evaluated by Ash
MyApp.User |> Ash.read(actor: actor)
```

## Policy Format

Policies follow AWS IAM JSON format:

```elixir
%{
  "Statement" => [
    %{
      "Effect" => "Allow" | "Deny",
      "Action" => ["action1", "action2", "*"],
      "Resource" => ["resource:pattern:*", "*"]
    }
  ]
}
```

Multiple policy documents are also supported:

```elixir
[
  %{"Statement" => [...]},
  %{"Statement" => [...]}
]
```

## Configuration

### Resource Configuration

- `permission_base` - The base resource identifier (required)
- `action_to_iam_mapping` - Maps Ash actions to IAM verbs
- `policy_key` - Actor attribute containing the policy (default: `:iam_policy`)
- `policy_fetcher` - Custom function to fetch policies

### Application Configuration

```elixir
config :ash_iam, iam_stem: "production"
```

This adds a prefix to all permission bases during evaluation.

Documentation can be found at [https://hexdocs.pm/ash_iam](https://hexdocs.pm/ash_iam).