# `Attesto.LogoutSessionStore`
[🔗](https://github.com/XukuLLC/attesto/blob/v0.13.0/lib/attesto/logout_session_store.ex#L1)

Storage seam for OpenID Connect Back-Channel Logout 1.0.

Back-Channel Logout requires the OP to deliver a `logout_token` to every
Relying Party that holds a session for the End-User when that session ends.
To do that the OP must remember, for each `(session, RP)` pair, where to
send the token. This behaviour is that memory: a row is recorded each time
an ID Token is minted to a back-channel-logout-capable client (the OP is the
party that mints those tokens, so it is the natural place to record the
binding), and enumerated when the end-session endpoint fires.

This is **not** the browser login session — attesto never models that; the
host owns login and supplies the `sid`. This store only persists the OP-side
`(sid, client_id) -> backchannel_logout_uri` delivery map, exactly as
`Attesto.RefreshStore` persists issued refresh families. Killing the actual
login state remains a host concern (the end-session controller's
`:terminate_session` callback).

## Record shape

A stored record (`record/1` input) is a map with:

  * `:sid` - the session id (the value asserted in the ID Token's `sid`
    claim). The per-session key the fan-out matches on.
  * `:subject` - the `sub` the session authenticated. The per-subject key,
    used when logout is requested without a `sid`.
  * `:client_id` - the Relying Party that received the ID Token.
  * `:backchannel_logout_uri` - where the `logout_token` is POSTed.
  * `:session_required` - the client's `backchannel_logout_session_required`
    (whether its `logout_token` MUST carry `sid`).
  * `:expires_at` - absolute expiry, unix seconds (so abandoned sessions are
    swept; mirror the ID Token / session lifetime).

`record/1` is idempotent on `(sid, client_id)`: re-issuing an ID Token for a
session the RP already has refreshes the row rather than duplicating it.

# `criteria`

```elixir
@type criteria() :: %{
  optional(:sid) => String.t() | nil,
  optional(:subject) => String.t() | nil
}
```

The criteria that select which sessions to log out. `:sid` scopes logout to
one session (across each RP that holds it); `:subject` (used when no `sid`
is known) scopes it to every session for the subject. At least one is set.

# `entry`

```elixir
@type entry() :: %{
  sid: String.t(),
  subject: String.t(),
  client_id: String.t(),
  backchannel_logout_uri: String.t(),
  session_required: boolean(),
  expires_at: non_neg_integer()
}
```

A stored back-channel-logout session record (see the module docs).

# `target`

```elixir
@type target() :: %{
  client_id: String.t(),
  backchannel_logout_uri: String.t(),
  sid: String.t() | nil,
  session_required: boolean()
}
```

A fan-out target: one RP to deliver a `logout_token` to.

# `delete`

```elixir
@callback delete(criteria()) :: :ok
```

Remove the session rows matched by `criteria` (same `:sid`/`:subject`
precedence as `targets/1`). Called after the fan-out so a session is
enumerated for logout exactly once.

# `record`

```elixir
@callback record(entry()) :: :ok
```

Record (idempotently on `(sid, client_id)`) that `client_id` holds a
back-channel-logout-capable session `sid` for `subject`, reachable at
`backchannel_logout_uri`. Called when an ID Token is minted to such a client.

# `take_targets`

```elixir
@callback take_targets(criteria()) :: [target()]
```

Atomically enumerate **and remove** the RP targets matched by `criteria`,
returning them (same `:sid`/`:subject` precedence as `targets/1`). This is the
end-session endpoint's fan-out primitive: doing the enumerate and the delete in
one statement (e.g. `DELETE ... RETURNING`) means two concurrent logouts of the
same session cannot both observe the rows and double-deliver, and no row that
is inserted mid-logout is silently dropped. Already-expired rows are ignored.

# `targets`

```elixir
@callback targets(criteria()) :: [target()]
```

List the RP targets to notify for a logout. When `criteria` carries a `:sid`,
scope to that session (every RP that received an ID Token under it); with no
`:sid` but a `:subject`, scope to all of that subject's sessions. Returns the
matching `t:target/0`s (possibly empty). Implementations SHOULD ignore
already-expired rows.

---

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