hellhound/testing

Test support: a scripted OpenID provider with its own test PKI, an in-memory record store, and a conformance check for store adapters.

The provider serves discovery, keys, a scripted login page at /authorize, token (authorization code with PKCE S256, rotating refresh tokens, client credentials), userinfo, introspection, revocation and end-session over HTTPS on loopback. Its certificate chains to a root generated at start (or kept by with_trust_anchor for a local run); config and trusting trust that root and allow loopback explicitly, so no production default changes. ID and access tokens are signed ES256 with gose.

Over HTTP

A test browser follows the application’s login redirect to the provider (trusting trust_anchor_pem). /authorize signs in the user that with_login or set_login names (test-user by default, or the request’s login_hint) and answers 303 to the callback with code, state and iss (a self-posting form for form-post). The application needs no test hook:

let assert Ok(provider) =
  testing.start_provider(
    testing.provider_options() |> testing.with_login(testing.SignIn("ada")),
  )
// The app runs `begin_login` and `login_response` in its /login route;
// the browser follows /login -> provider /authorize -> app /callback.
testing.set_login(provider, testing.Refuse("access_denied"))  // next login is cancelled

In process

A unit test that holds the LoginRedirect skips HTTP:

let assert Ok(provider) = testing.start_provider(testing.provider_options())
let assert Ok(client) =
  hellhound.new(testing.config(provider, "https://app.test/callback"))
let assert Ok(Nil) = hellhound.start(client)

let assert Ok(redirect) = hellhound.begin_login(client, browser, hellhound.default_login())
let assert Ok(callback) = testing.authorize(provider, redirect, subject: "ada")
let assert Ok(session) = hellhound.complete_login(client, callback)

Per-subject claims

For one subject, with_granted_scopes scripts the granted scopes, with_email_claims the email and email_verified assertions, and with_extra_claims any other claim a real provider adds to ID tokens and userinfo, such as a namespaced roles claim or name. set_granted_scopes, set_email_claims and set_extra_claims change them for later logins. extra_claim refuses reserved protocol claims with ReservedClaim.

let assert Ok(roles) =
  testing.extra_claim(
    "https://example.test/roles",
    json.array(["operator"], json.string),
  )
testing.provider_options() |> testing.with_extra_claims("ada", [roles])

The application reads them from the verified identity as in production (hellhound.decode_claims, hellhound.name); nothing outside this provider changes.

A local run with a real browser

For local development only, never a deployed environment. By default every start picks a free port and mints a fresh in-memory root, so a browser sees a new issuer and an unknown certificate authority each run. with_port fixes the port and with_trust_anchor keeps one root in a directory you choose, so the issuer and the root stay the same and you trust the root once:

let assert Ok(provider) =
  testing.start(
    testing.provider_options()
    |> testing.with_port(8443)
    |> testing.with_trust_anchor(".local/hellhound"),
  )
// issuer: https://localhost:8443
// trust once: testing.trust_anchor_file(".local/hellhound")

The root may only certify localhost, 127.0.0.1 and ::1 (critical X.509 name constraints, path length 0) and lasts 90 days; its private key is written with mode 0600 in that directory. Keep the directory out of version control. A broken or expired anchor is a TrustAnchorFailed error; replace_trust_anchor mints a new root, which you trust again. Hellhound never runs a trust-store command. To trust the root yourself:

The name constraints limit only clients that enforce a trust anchor’s own constraints. OpenSSL does, and the test suite checks it; Chrome documents enforcement for roots in its platform trust store (untested here); Safari and Firefox are untested. Erlang’s ssl does not apply a trust anchor’s own constraints, so an Erlang client that trusts this root is limited only by its hostname check.

Access tokens

set_access_token_audiences changes the aud of issued access tokens after start, so an application can name its own address once it listens. revoke_access_token revokes one token for introspection and userinfo; a local JWT validator (hellhound/resource) keeps accepting it until it expires, as RFC 9068 tokens carry no revocation channel.

The provider mints tokens with keys it generated; nothing trusts them unless a configuration names the provider’s issuer and root.

Types

Typed standard email claims. None omits that claim entirely. These are provider assertions, not permission or email-format validation.

pub type EmailClaims {
  EmailClaims(
    email: option.Option(String),
    verified: option.Option(Bool),
  )
}

Constructors

One additional claim a subject’s ID tokens and userinfo carry, such as a provider’s namespaced roles claim or a standard profile claim like name. Build it with extra_claim, which refuses reserved names, so a value of this type never names a protocol claim.

pub opaque type ExtraClaim
pub type ExtraClaimError {
  ReservedClaim(name: String)
}

Constructors

  • ReservedClaim(name: String)

    The name is a claim the provider computes or another testing function owns (email and email_verified belong to with_email_claims).

A forged token, for testing that a resource server refuses it.

pub type Forgery {
  UnsignedToken
  HmacWithPublicKey
  UnknownKey
}

Constructors

  • UnsignedToken

    alg: none and an empty signature.

  • HmacWithPublicKey

    HS256 keyed with the provider’s public key (algorithm confusion).

  • UnknownKey

    Signed by a key the provider never published, with an unknown kid.

What the provider’s /authorize endpoint does with a browser that arrives there: the provider’s login page, scripted.

pub type LoginDecision {
  SignIn(subject: String)
  Refuse(error: String)
}

Constructors

  • SignIn(subject: String)

    Sign subject in and redirect back to the client with a code. When the authorization request carries login_hint (Hellhound sends LoginOptions.login_hint), that subject signs in instead, so one provider serves several users at once.

  • Refuse(error: String)

    Redirect back with this OAuth error, as when the user cancels ("access_denied") or prompt=none finds no session ("login_required").

pub opaque type Provider

How the provider behaves. Build from provider_options().

pub opaque type ProviderOptions

Requests the provider has answered, by kind.

pub type RequestCounts {
  RequestCounts(
    discovery: Int,
    authorizations: Int,
    keys: Int,
    code_grants: Int,
    refresh_grants: Int,
    rejected_refresh_grants: Int,
    client_credentials_grants: Int,
    userinfo: Int,
    introspections: Int,
    revocations: Int,
    end_sessions: Int,
    active_refresh_tokens: Int,
  )
}

Constructors

  • RequestCounts(
      discovery: Int,
      authorizations: Int,
      keys: Int,
      code_grants: Int,
      refresh_grants: Int,
      rejected_refresh_grants: Int,
      client_credentials_grants: Int,
      userinfo: Int,
      introspections: Int,
      revocations: Int,
      end_sessions: Int,
      active_refresh_tokens: Int,
    )

    Arguments

    authorizations

    Authorization requests, over HTTP or through authorize, whether they signed someone in or not.

    active_refresh_tokens

    Refresh tokens that are neither rotated nor revoked.

Why start could not start a provider.

pub type StartError {
  StartFailed
  InvalidPort(port: Int)
  PortInUse(port: Int)
  TrustAnchorFailed(directory: String, error: TrustAnchorError)
}

Constructors

  • StartFailed

    The provider’s PKI, state or listener did not start.

  • InvalidPort(port: Int)

    with_port named a port outside 0..65535.

  • PortInUse(port: Int)

    The fixed port of with_port is already in use on 127.0.0.1.

  • TrustAnchorFailed(directory: String, error: TrustAnchorError)

    The root kept in directory (with_trust_anchor) cannot be used. It is never replaced silently: fix it, or call replace_trust_anchor and trust the new root.

pub type TestError {
  ProviderStartFailed
  AuthorizationRefused(reason: String)
}

Constructors

  • ProviderStartFailed

    The provider’s PKI or listener did not start.

  • AuthorizationRefused(reason: String)

    authorize was given a URL the provider does not accept (another client, no S256 challenge, or not this provider’s endpoint).

An access token to mint with issue_access_token. Build from access_token(subject).

pub opaque type TokenSpec

Why a kept trust anchor cannot be used or written.

pub type TrustAnchorError {
  AnchorUnreadable(path: String)
  AnchorCorrupt(path: String)
  AnchorIncomplete(missing: String)
  AnchorNotRegularFile(path: String)
  AnchorMismatch
  AnchorExpired
  AnchorKeyExposed(path: String)
  AnchorWriteFailed(path: String)
  AnchorLocked(path: String)
}

Constructors

  • AnchorUnreadable(path: String)

    A file exists but cannot be read.

  • AnchorCorrupt(path: String)

    A file is not one PEM certificate or one P-256 EC private key.

  • AnchorIncomplete(missing: String)

    One of the two files is missing.

  • AnchorNotRegularFile(path: String)

    An anchor path is a symbolic link (live or dangling) or another kind of entry than a regular file. Links are never followed for the key.

  • AnchorMismatch

    The key’s private scalar does not match the root, or the root is not exactly what Hellhound mints: version 3, ECDSA P-256 with SHA-256, self-issued, at most 90 days, and only its basic constraints, key usage, loopback name constraints and key identifier, each as minted.

  • AnchorExpired

    The root is outside its validity period.

  • AnchorKeyExposed(path: String)

    The private key is readable by its group or by others.

  • AnchorWriteFailed(path: String)

    The directory or a file could not be created or written.

  • AnchorLocked(path: String)

    The directory’s lock (path, the hellhound-root.lock directory) was held for the whole wait of about five seconds. Starts hold it only while they create, load or replace the anchor, so this means either a start killed while holding it left it behind, or a live start is still working (retry). Remove it only after confirming no start is running against the directory; it may hold staged anchor files, readable only by you.

Values

pub fn access_token(subject: String) -> TokenSpec

Defaults: audience the client id, no scopes, five minutes, typ at+jwt.

pub fn authorize(
  provider: Provider,
  redirect: hellhound.LoginRedirect,
  subject subject: String,
) -> Result(request.Request(String), TestError)

Play the browser and the provider’s login page in process: accept the authorization request in redirect for subject and return the callback request Hellhound expects (the query, or a form post, with the binding cookie). subject overrides the provider’s LoginDecision.

pub fn browser_request(
  redirect: hellhound.LoginRedirect,
) -> request.Request(String)

A request from the same browser (it carries the binding cookie of an earlier login), for hellhound.begin_login.

pub fn check_store(
  store: store.Store,
) -> Result(Nil, List(String))

Check a store adapter against the hellhound/store contract with records under keys prefixed hellhound-conformance:: insert only when absent, version and deadline conditions, refusal preservation, concurrent admission, reads of the latest write, and delete_expired deleting exactly the expired records. Returns every violation found. Run it against an empty test table. Adapters must also verify clock sampling after their own queue/lock waits and uncertain commits.

pub fn client_id(provider: Provider) -> String
pub fn config(
  provider: Provider,
  redirect_uri: String,
) -> config.Config

A relying-party configuration for this provider: its issuer, client and secret (client_secret_basic), its root, and loopback destinations.

pub fn extra_claim(
  name: String,
  value: json.Json,
) -> Result(ExtraClaim, ExtraClaimError)

An extra claim with any JSON value, for example a role list or a profile string:

let assert Ok(roles) =
  testing.extra_claim(
    "https://example.test/roles",
    json.array(["operator"], json.string),
  )
let assert Ok(name) = testing.extra_claim("name", json.string("Ada"))

Reserved protocol claims (iss, sub, aud, exp, iat, nbf, jti, nonce, azp, at_hash, c_hash, s_hash, auth_time, sid, cnf, _claim_names, _claim_sources) and the email claims return ReservedClaim. This is a provider assertion for tests, not a permission.

pub fn forged(spec: TokenSpec, forgery: Forgery) -> TokenSpec
pub fn issue_access_token(
  provider: Provider,
  spec: TokenSpec,
) -> String

Mint a JWT access token (RFC 9068) signed with the provider’s current key, or forged as spec says. The provider’s introspection endpoint knows it too.

pub fn issuer(provider: Provider) -> String
pub fn memory_store() -> store.Store

A fresh in-memory record store linked to the caller: a reference implementation of the hellhound/store contract, for tests and for wrapping with delays or failures.

pub fn provider_options() -> ProviderOptions

Defaults: client hellhound-test with a random secret, five-minute access tokens whose audience is the client id, no refresh delay, scopes openid email profile, and /authorize signing in test-user.

pub fn replace_trust_anchor(
  directory: String,
) -> Result(Nil, TrustAnchorError)

Mint a new root in directory and overwrite the one kept there, for an expired or broken anchor. Every client and browser that trusted the old root must trust the new one.

pub fn requests(provider: Provider) -> RequestCounts
pub fn revoke_access_token(
  provider: Provider,
  token: String,
) -> Nil

Revoke one access token, as RFC 7009 revocation or an administrator would. Introspection then answers active: false and userinfo invalid_token.

A resource server that validates JWTs locally (hellhound/resource) does not see this: RFC 9068 tokens carry no revocation channel, so they stay valid until exp. A test that needs a revoked token refused at once uses introspection (hellhound.introspect, or resource’s introspection recipe); with local validation, use short lifetimes (with_access_token_ttl).

pub fn revoke_refresh_tokens(
  provider: Provider,
  subject: String,
) -> Nil

Revoke every refresh token issued to subject, as an administrator ending the grant would. The next refresh answers invalid_grant.

pub fn rotate_signing_key(provider: Provider) -> Nil

Replace the signing key with a new one (new kid). The key set lists the new key first and keeps the previous one.

pub fn service_config(provider: Provider) -> config.Config

A service-client configuration for this provider (client credentials, introspection).

pub fn set_access_token_audiences(
  provider: Provider,
  audiences: List(String),
) -> Nil

aud of access tokens issued from now on (empty: the client id). Tokens issued earlier keep theirs.

pub fn set_clock_skew(
  provider: Provider,
  skew: duration.Duration,
) -> Nil

Make the provider’s clock run ahead (positive) or behind: issued tokens carry iat (and auth_time) shifted by skew.

pub fn set_email_claims(
  provider: Provider,
  subject: String,
  claims: EmailClaims,
) -> Nil

Change one subject’s assertions for future ID tokens and userinfo reads. Previously issued tokens and verified identities remain unchanged.

pub fn set_extra_claims(
  provider: Provider,
  subject: String,
  claims: List(ExtraClaim),
) -> Nil

What with_extra_claims does, for ID tokens and userinfo reads from now on. Previously issued tokens and verified identities remain unchanged, and nothing outside this test provider changes behaviour.

pub fn set_granted_scopes(
  provider: Provider,
  subject: String,
  scopes: List(String),
) -> Nil

What with_granted_scopes does, for logins from now on. An empty list grants no scope at all.

pub fn set_login(
  provider: Provider,
  decision: LoginDecision,
) -> Nil

What /authorize does from now on.

pub fn start(
  options: ProviderOptions,
) -> Result(Provider, StartError)

Start a provider, reporting why it could not start. It is linked to the caller, so it ends with the process that started it; stop_provider ends it earlier.

pub fn start_provider(
  options: ProviderOptions,
) -> Result(Provider, TestError)

Start a provider. It is linked to the caller, so it ends with the test that started it; stop_provider ends it earlier. Any failure is ProviderStartFailed; start reports the cause (PortInUse, TrustAnchorFailed, …) for the with_port and with_trust_anchor options.

pub fn stop_provider(provider: Provider) -> Nil
pub fn trust_anchor_der(provider: Provider) -> BitArray

The provider’s root certificate in DER, the form HTTP Gun’s Anchors takes, for a test client that calls the provider or the application over HTTPS without Hellhound.

pub fn trust_anchor_file(directory: String) -> String

The path of the root certificate kept in directory, the one file a developer adds to their trust store.

pub fn trust_anchor_pem(provider: Provider) -> String

PEM text of the provider’s root certificate.

pub fn trusting(
  config: config.Config,
  provider: Provider,
) -> config.Config

Trust this provider’s root and allow loopback destinations, on any configuration (for example config.resource_server).

pub fn with_access_token_audiences(
  options: ProviderOptions,
  audiences: List(String),
) -> ProviderOptions

aud of access tokens issued by the token endpoint. Default: the client id. set_access_token_audiences changes it after start, for an audience that names an address known only once the application listens.

pub fn with_access_token_ttl(
  options: ProviderOptions,
  ttl: duration.Duration,
) -> ProviderOptions

Lifetime of access tokens issued by the token endpoint.

pub fn with_audiences(
  spec: TokenSpec,
  audiences: List(String),
) -> TokenSpec
pub fn with_client(
  options: ProviderOptions,
  client_id client_id: String,
  secret secret: String,
) -> ProviderOptions

The one registered client. It authenticates with client_secret_basic or client_secret_post.

pub fn with_email_claims(
  options: ProviderOptions,
  subject: String,
  claims: EmailClaims,
) -> ProviderOptions

Override only email claims for one subject in newly issued ID tokens and userinfo. Without an override, the provider retains subject-derived email, verified in ID tokens and no verification claim in userinfo. Reserved protocol claims, identity constructors and production trust are unchanged.

pub fn with_extra_claims(
  options: ProviderOptions,
  subject: String,
  claims: List(ExtraClaim),
) -> ProviderOptions

Add these claims for one subject to newly issued ID tokens and userinfo, replacing any extra claims set for that subject before. A later claim of the same name replaces an earlier one in the list; an empty list removes the subject’s extra claims. A subject without an entry gets none, so existing tokens and userinfo are unchanged.

Only this test provider’s issued evidence changes: the client still verifies every token as in production, and the claims reach the application only through hellhound.decode_claims, the profile accessors and hellhound.decode_userinfo. Verification, token custody, configuration and the opaque VerifiedIdentity are untouched. Reserved protocol claims, identity constructors and production trust are unchanged.

pub fn with_granted_scopes(
  options: ProviderOptions,
  subject: String,
  scopes: List(String),
) -> ProviderOptions

The scopes a login of subject is granted, in place of the scopes the client requested. The access token’s scope claim, the token response and introspection all carry exactly this list, so a test can sign in a user who lacks a scope:

testing.provider_options()
|> testing.with_granted_scopes("ada", ["openid", "approve:refund"])
|> testing.with_granted_scopes("mallory", ["openid"])

The list is granted whether or not the client requested it, and openid is not added: list it if the test needs it. A subject without an entry gets the scopes the client requested. The subject is the one that signs in, so it also applies to a login_hint.

pub fn with_issuer(spec: TokenSpec, issuer: String) -> TokenSpec

Claim another issuer.

pub fn with_login(
  options: ProviderOptions,
  decision: LoginDecision,
) -> ProviderOptions

What /authorize does; set_login changes it after start.

pub fn with_port(
  options: ProviderOptions,
  port: Int,
) -> ProviderOptions

Listen on this port of 127.0.0.1 instead of a free one, so the issuer (https://localhost:<port>) is the same on every run. 0, the default, lets the OS choose. start answers PortInUse when the port is taken. Only loopback is ever served.

pub fn with_refresh_delay(
  options: ProviderOptions,
  delay: duration.Duration,
) -> ProviderOptions

Delay before answering a refresh grant, to widen refresh races.

pub fn with_scopes(
  spec: TokenSpec,
  scopes: List(String),
) -> TokenSpec
pub fn with_token_type(
  spec: TokenSpec,
  token_type: option.Option(String),
) -> TokenSpec

The header typ; None omits it.

pub fn with_trust_anchor(
  options: ProviderOptions,
  directory: String,
) -> ProviderOptions

Keep the provider’s root in directory and reuse it on every start, so a developer trusts it once for a local run with a real browser. The caller chooses the directory; Hellhound picks no global location and never touches a system trust store.

On the first start, the directory (created owner-only if missing) receives hellhound-root.pem, the root to trust (trust_anchor_file), and hellhound-root-key.pem, its private key, with mode 0600. Both are written in an owner-only staging directory and renamed into place, so no other user can open the key even in a directory they can traverse. Later starts load both and sign a new leaf for localhost and 127.0.0.1. A corrupt, incomplete, mismatched, expired or group-readable anchor, or a symbolic link at either path (links are never followed), is a TrustAnchorFailed error, never a silent new root; replace_trust_anchor is the explicit way to mint one. Starts in several processes or worktrees may share the directory: a lock made with mkdir, exclusive across processes, serializes them, so exactly one creates the root and the others load it.

The root is a P-256 CA valid for 90 days, limited by critical X.509 name constraints to localhost, 127.0.0.1 and ::1 with path length 0, so a client that enforces a trust anchor’s name constraints (OpenSSL, tested) refuses anything else it signs; see the module documentation. Its key still sits on disk: trust it only on a developer machine, keep the directory out of version control, and never use this in a deployed environment. Without this option the provider keeps a fresh in-memory root per start. Verification, custody and production trust are unchanged: only a configuration that names this root trusts it.

pub fn with_ttl(
  spec: TokenSpec,
  ttl: duration.Duration,
) -> TokenSpec

Lifetime from now; a negative value mints an expired token.

✨ Search Document