# Authorization Quick Start Guide

## TL;DR - Is the @key pattern good for production?

**Short answer:** The enhanced version (named permissions) is better.

**Original pattern:**
```elixir
@key 12345
def html(%{keys: keys}) when is_map_key(keys, @key)
```

**Enhanced pattern (use this):**
```elixir
@required_permission "index:view"
def html(%{keys: keys}) do
  case Auth.Authorization.authorized?(keys, @required_permission) do
    {:ok, true} -> render_html()
    {:error, _} -> unauthorized_html()
  end
end
```

## Why Enhanced is Better

| Feature | Original | Enhanced |
|---------|----------|----------|
| Readability | Magic numbers | Named permissions |
| Scalability | Per-module | Centralized |
| Audit trail | None | Built-in |
| Flexibility | One permission | Multiple patterns |
| Efficiency | O(1) ✅ | O(1) ✅ |

## Quick Usage

### Check a single permission

```elixir
Auth.Authorization.authorized?(user_keys, "index:view")
# => {:ok, true} or {:error, :forbidden}
```

### Check multiple permissions (ALL required)

```elixir
Auth.Authorization.authorized_all?(user_keys, ["reports:read", "reports:write"])
# => true or false
```

### Check multiple permissions (ANY required)

```elixir
Auth.Authorization.authorized_any?(user_keys, ["admin:manage", "reports:admin"])
# => true or false
```

### Add audit logging

```elixir
Auth.Authorization.authorized?(user_keys, "admin:manage", audit: true)
```

## Adding New Permissions

1. Edit `lib/auth/authorization.ex`
2. Add to `@permissions` map:

```elixir
@permissions %{
  "my_module:action" => 99999,  # Choose unique number
  # ...
}
```

3. Use in your module:

```elixir
defmodule MyModule do
  @required_permission "my_module:action"

  def my_function(%{keys: keys}) do
    case Auth.Authorization.authorized?(keys, @required_permission) do
      {:ok, true} -> do_work()
      {:error, _} -> "Unauthorized"
    end
  end
end
```

## File Structure

```
lib/
├── auth/
│   ├── authorization.ex          # Core authorization logic
│   └── authorization_plug.ex     # Route-level middleware
├── floki/
│   └── index.ex                  # Example: module-level auth
└── my_mcp_server_router.ex       # Cookie encryption & user loading
```

## See Also

- Full documentation: `docs/AUTHORIZATION.md`
- Example module: `lib/floki/index.ex`
- Router integration: `lib/my_mcp_server_router.ex`