WardrikVault.Grants behaviour (wardrik_vault v0.1.0-rc.1)

Copy Markdown

The behaviour for grants: credentials a principal gives by authorizing an account, like OAuth tokens.

{WardrikVault, name: MyApp.Vault, store: store, keys: keys, grants: {MyApp.OAuth, opts}}

When a tool needs a credential, the vault calls:

  • renew/5 if the principal holds it as a grant.
  • ask/4 if nobody holds it, or the grant won't unseal.
  • refused/4 when a service refuses the grant.

Each callback gets the vault's name first and the module's opts last.

Write what comes back from authorizing with WardrikVault.put/5 and kind: :grant. Pass :if_vsn so two renewals never write over each other.

Summary

Types

grant()

A grant as the vault holds it. vsn is the version to write a renewal over.

Callbacks

ask(name, t, t, opts)

Returns {:authorize, url} for the principal to authorize name at, or {:error, :not_found}.

refused(name, t, t, opts)

Called when a service refuses the grant held as name.

renew(name, t, t, grant, opts)

Returns the credential grant gives. Renews it first if it has run out.

Types

grant()

@type grant() :: %{value: binary(), vsn: WardrikStore.vsn()}

A grant as the vault holds it. vsn is the version to write a renewal over.

Callbacks

ask(name, t, t, opts)

@callback ask(GenServer.name(), String.t(), WardrikCore.Principal.t(), opts :: term()) ::
  {:authorize, String.t()} | {:error, term()}

Returns {:authorize, url} for the principal to authorize name at, or {:error, :not_found}.

refused(name, t, t, opts)

@callback refused(GenServer.name(), String.t(), WardrikCore.Principal.t(), opts :: term()) ::
  :ok

Called when a service refuses the grant held as name.

renew(name, t, t, grant, opts)

@callback renew(
  GenServer.name(),
  String.t(),
  WardrikCore.Principal.t(),
  grant(),
  opts :: term()
) ::
  {:ok, term()} | {:authorize, String.t()} | {:error, term()}

Returns the credential grant gives. Renews it first if it has run out.