# `Attesto.PairwiseSubject`
[🔗](https://github.com/XukuLLC/attesto/blob/v2.28.0/lib/attesto/pairwise_subject.ex#L1)

Pairwise Subject Identifiers (OpenID Connect Core 1.0 §8.1).

A pairwise `sub` is a different value for each sector of Relying Parties, so
two clients in different sectors cannot correlate one End-User by comparing
subject identifiers. This module holds the two pure rules: which sector a
client belongs to, and how a `sub` is derived for it.

## Sector identifier

§8.1 defines the sector identifier as the host component of the client's
`sector_identifier_uri` when it registered one, and otherwise the host
component of its registered `redirect_uri`, which then requires every
registered redirect URI to share one host. This module implements the
second form only: `sector_identifier/1` takes the registered redirect URIs
and answers `{:error, :multiple_hosts}` when they span hosts. Fetching and
validating a `sector_identifier_uri` document (§8.1) is not implemented, so a
client whose redirect URIs span hosts cannot use pairwise identifiers.

## Derivation

`derive/3` computes

    base64url(HMAC-SHA256(salt, len(sector) || sector || local_subject))

where `len(sector)` is the sector identifier's byte length as a 32-bit
integer. §8.1 allows any method that is deterministic, cannot be reversed by
anyone but the provider, and gives different results per sector. The length
prefix keeps two different `(sector, subject)` pairs from producing the same
input. The value is stable for as long as the salt, the sector identifier
and the local subject are: changing the salt, or moving a client to another
redirect host, changes every `sub` that client sees.

# `derive`

```elixir
@spec derive(String.t(), String.t(), binary()) :: String.t()
```

Derive the pairwise `sub` for `local_subject` in `sector_identifier`.

Raises `ArgumentError` for a salt shorter than `min_salt_bytes/0` or an
empty sector identifier or subject.

# `min_salt_bytes`

```elixir
@spec min_salt_bytes() :: pos_integer()
```

The minimum salt length `derive/3` accepts, in bytes.

# `seal_subject`

```elixir
@spec seal_subject(String.t(), String.t(), binary()) :: String.t()
```

Encrypt `local_subject` for recovery by the authorization server or a same-deployment
resource server sharing `salt`.

Pads the length-prefixed subject to a multiple of 64 bytes
and derives a single-use AES-256-GCM key per call from a fresh random 32-byte
token nonce via HMAC-SHA256, with `pairwise_sub` as associated authenticated
data. Two tokens therefore carry distinct ciphertexts that cannot be
correlated, short subjects share the same ciphertext size, and the ciphertext
is bound to its `sub`.

# `sector_identifier`

```elixir
@spec sector_identifier([String.t()]) ::
  {:ok, String.t()}
  | {:error, :no_redirect_uris | :invalid_redirect_uri | :multiple_hosts}
```

The sector identifier for a client with these registered redirect URIs: the
host they all share, lowercased.

Returns `{:error, :no_redirect_uris}` for an empty list,
`{:error, :invalid_redirect_uri}` when one has no host, and
`{:error, :multiple_hosts}` when they do not all share one host.

# `subject_types`

```elixir
@spec subject_types() :: [String.t()]
```

The subject types this module knows: `["public", "pairwise"]`.

# `unseal_subject`

```elixir
@spec unseal_subject(term(), term(), term()) :: {:ok, String.t()} | :error
```

Decrypt a sealed subject produced by `seal_subject/3`, authenticating against
`pairwise_sub` and `salt`.

# `valid_salt?`

```elixir
@spec valid_salt?(term()) :: boolean()
```

Whether `salt` is usable: a binary of at least `min_salt_bytes/0` bytes.

---

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