guardian_paseto v0.2.1 Guardian.Token.Paseto

Implements the Guardian Token callbacks for Paseto.

This module ought to only be used from Guardian. I.e., please don’t touch this module. If you’re needing the underlying primitives for Paseto, please visit https://github.com/GrappigPanda/Paseto

A short summary of what a token is (as a string):

Tokens are broken up into several components:

  • version: v1 or v2 — v2 suggested
  • purpose: Local or Public — Local -> Symmetric Encryption for payload & Public -> Asymmetric Encryption for payload
  • payload: A signed or encrypted & b64 encoded string
  • footer: An optional value, often used for storing keyIDs or other similar info.

Link to this section Summary

Functions

Creates a Guardian.claims map with stringified keys

Handles generating a token

Handles decoding a token to get the claims

Grabs the claims from the token without having done any verification

revoke callback specifically implemented for Guardian.Token

Generates a unique identifier for the token

Verifies a claims object was issued by the issuing key

Link to this section Functions

Link to this function build_claims(mod, resource, sub, claims \\ %{}, opts \\ [])
build_claims(
  mod :: module(),
  resource :: any(),
  sub :: String.t(),
  optional(claims()) :: Guardian.claims(),
  optional(opts()) :: Keyword.t()
) :: {:ok, Guardian.claims()} | {:error, atom()}

Creates a Guardian.claims map with stringified keys.

Link to this function create_token(mod, claims, opts)
create_token(mod :: module(), claims :: map(), opts :: Keyword.t()) ::
  {:ok, String.t()}
  | Guardian.Token.signing_error()
  | Guardian.Token.encoding_error()
  | Guardian.Token.secret_error()

Handles generating a token:

Tokens are broken up into several components:

  • version: v1 or v2 — v2 suggested
  • purpose: Local or Public — Local -> Symmetric Encryption for payload & Public -> Asymmetric Encryption for payload
  • payload: A signed or encrypted & b64 encoded string
  • footer: An optional value, often used for storing keyIDs or other similar info.
Link to this function decode_token(mod, token, opts)
decode_token(mod :: module(), token :: String.t(), Keyword.t()) ::
  {:ok, %{token: String.t()}}
  | Guardian.secret_error()
  | Guardian.decoding_error()

Handles decoding a token to get the claims.

NOTE: This is the first part of a 2-part hack involving decode_token and verify_claims. See verify_claims for more information, but, in short, we’ll be returning the token within a map so that verify_claims can fully work.

Link to this function peek(mod, token)
peek(mod :: module(), token :: Guardian.token()) :: map()

Grabs the claims from the token without having done any verification.

NOTE: This will only work on public purposed Paseto tokens due to the fact that encrytped tokens inherently can’t be looked at without also verifying.

Link to this function refresh(mod, original_token, opts)
refresh(mod :: module(), token :: Guardian.token(), opts :: Keyword.t()) ::
  {:ok, {Guardian.token(), Guardian.claims()},
   {Guardian.token(), Guardian.claims()}}
  | {:error, any()}

Refreshes a token.

Link to this function revoke(mod, claims, token, opts)
revoke(
  mod :: module(),
  claims :: map(),
  token :: String.t(),
  opts :: Keyword.t()
) :: {:ok, map()}

revoke callback specifically implemented for Guardian.Token.

NOTE: There is no actual revokation method for a Paseto, so this just returns the claims

Link to this function token_id()
token_id() :: String.t()

Generates a unique identifier for the token.

Link to this function verify_claims(mod, map, opts)
verify_claims(
  mod :: module(),
  token :: %{token: String.t()},
  opts :: Keyword.t()
) :: {:ok, Guardian.claims()} | {:error, any()}

Verifies a claims object was issued by the issuing key.

NOTE: The claims argument being passed in will actually be an entire token due to the limitations of verification for Guardian—in short, the entire token is needed to verify the validity of a Paseto.