# `Caracola.StirShaken.Passport`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/stir_shaken/passport.ex#L1)

Personal Assertion Tokens (PASSporT, RFC 8225) with the SHAKEN extension
(RFC 8588), signed with ES256.

A PASSporT is a JSON Web Token in compact serialization: the base64url
encoded header, claims and signature, separated by dots. The JSON
objects have their keys sorted and no whitespace (RFC 8225 §9).

# `claims`

```elixir
@type claims() :: %{required(String.t()) =&gt; term()}
```

The claims of a PASSporT (RFC 8225, RFC 8588), by name.

# `t`

```elixir
@type t() :: %{
  header: map(),
  claims: claims(),
  signing_input: binary(),
  signature: binary()
}
```

A decoded PASSporT: header, claims, signing input and signature.

# `decode`

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

Decodes a PASSporT, without checking its signature.

    iex> token = "eyJhbGciOiJFUzI1NiJ9.eyJpYXQiOjF9.AAAA"
    iex> {:ok, %{header: header, claims: claims}} = Caracola.StirShaken.Passport.decode(token)
    iex> {header, claims}
    {%{"alg" => "ES256"}, %{"iat" => 1}}
    iex> Caracola.StirShaken.Passport.decode("nope")
    :error

# `encode`

```elixir
@spec encode(map(), claims(), :public_key.private_key()) :: String.t()
```

Encodes and signs a PASSporT. `header` gets `alg` (ES256) and `typ`
(passport).

# `verify`

```elixir
@spec verify(t(), :public_key.public_key()) :: boolean()
```

Checks the ES256 signature of a decoded PASSporT with a public key.

---

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