# `AshAi.Mcp.OAuth.Store`
[🔗](https://github.com/ash-project/ash_ai/blob/v1.5.6/lib/ash_ai/mcp/oauth/store.ex#L5)

Persists what `AshAi.Mcp.OAuth` needs between requests.

AshAi never stores credentials itself. Configure a store with
`store: {module, store_opts}` (or just `store: module`); every callback
receives `store_opts` as its last argument. `mix ash_ai.gen.mcp_oauth`
generates a store backed by `ash_postgres`, with its secrets encrypted by
`ash_cloak`.

Three kinds of records are stored:

- `AshAi.Mcp.OAuth.Client` - a client registered through Dynamic Client
  Registration, keyed by the MCP server it was registered for and the
  authorization server's issuer. Each MCP server gets its own registration,
  so the authorization server asks for consent again instead of reusing a
  grant made for another MCP server.
- `AshAi.Mcp.OAuth.Token` - the tokens for one MCP server and one owner. The
  owner is whatever the caller passes as `:owner`, such as a user id; AshAi
  treats it as opaque.

An MCP server is identified by its canonical resource URI (see
`AshAi.Mcp.OAuth.canonical_resource/1`).
- `AshAi.Mcp.OAuth.Pending` - an authorization in progress, keyed by its
  `state` parameter, from `AshAi.Mcp.OAuth.authorize_url/3` until the
  callback.

Each struct has `to_map/1` and `from_map/1` for JSON-safe serialization, and
hides its secrets from `inspect/1`. Encrypt the secrets at rest. Client
secrets, access and refresh tokens, and PKCE verifiers all grant access.

`c:with_lock/4` must serialize callers for the same server and owner, across
nodes if the application runs on several. Token refresh runs inside it and
re-reads the token first, so concurrent requests refresh a rotating refresh
token only once. The function it runs makes requests to the authorization
server, so don't hold a database connection or transaction for the lock: a
row lock or advisory lock does, and a slow authorization server would then
exhaust the connection pool. A lease works instead, such as a row claimed
with a conditional update until a timestamp, as the store
`mix ash_ai.gen.mcp_oauth` generates does.

# `opts`

```elixir
@type opts() :: term()
```

# `delete_token`

```elixir
@callback delete_token(server :: String.t(), owner :: term(), opts()) :: :ok
```

Deletes the tokens for `server` and `owner`, if any.

# `get_client`

```elixir
@callback get_client(server :: String.t(), issuer :: String.t(), opts()) ::
  {:ok, AshAi.Mcp.OAuth.Client.t()} | :error
```

The client registered for the MCP server `server` with the authorization server `issuer`.

# `get_token`

```elixir
@callback get_token(server :: String.t(), owner :: term(), opts()) ::
  {:ok, AshAi.Mcp.OAuth.Token.t()} | :error
```

The tokens `owner` holds for the MCP server `server`.

# `put_client`

```elixir
@callback put_client(server :: String.t(), AshAi.Mcp.OAuth.Client.t(), opts()) ::
  :ok | {:error, term()}
```

Stores a client registered for `server`, replacing any for `server` and its issuer.

# `put_pending`

```elixir
@callback put_pending(AshAi.Mcp.OAuth.Pending.t(), opts()) :: :ok | {:error, term()}
```

Stores an authorization in progress.

# `put_token`

```elixir
@callback put_token(
  server :: String.t(),
  owner :: term(),
  AshAi.Mcp.OAuth.Token.t(),
  opts()
) ::
  :ok | {:error, term()}
```

Stores tokens, replacing any existing ones for `server` and `owner`.

# `take_pending`

```elixir
@callback take_pending(state :: String.t(), opts()) ::
  {:ok, AshAi.Mcp.OAuth.Pending.t()} | :error
```

Removes and returns the authorization in progress with this `state`.

A pending authorization must be usable only once, so remove it as part of the
same operation.

# `with_lock`

```elixir
@callback with_lock(server :: String.t(), owner :: term(), (-&gt; result), opts()) ::
  result | {:error, term()}
when result: term()
```

Runs `fun` while holding a lock for `server` and `owner`, returning its result.

When the lock can't be had in reasonable time, return `{:error, reason}`
without running `fun`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
