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:
- macOS, current user:
security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db .local/hellhound/hellhound-root.pem; undo withsecurity remove-trusted-cert .local/hellhound/hellhound-root.pem. - Debian or Ubuntu: copy it to
/usr/local/share/ca-certificates/hellhound-local.crtand runsudo update-ca-certificates; Fedora: copy it to/etc/pki/ca-trust/source/anchors/and runsudo update-ca-trust. - Chrome or Chromium on Linux:
certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n "Hellhound local" -i .local/hellhound/hellhound-root.pem. Firefox keeps its own store (Settings, Certificates, Import).
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
-
EmailClaims( email: option.Option(String), verified: option.Option(Bool), )
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 (
emailandemail_verifiedbelong towith_email_claims).
A forged token, for testing that a resource server refuses it.
pub type Forgery {
UnsignedToken
HmacWithPublicKey
UnknownKey
}
Constructors
-
UnsignedTokenalg: noneand an empty signature. -
HmacWithPublicKeyHS256 keyed with the provider’s public key (algorithm confusion).
-
UnknownKeySigned 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
subjectin and redirect back to the client with a code. When the authorization request carrieslogin_hint(Hellhound sendsLoginOptions.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") orprompt=nonefinds no session ("login_required").
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
-
StartFailedThe provider’s PKI, state or listener did not start.
-
InvalidPort(port: Int)with_portnamed a port outside 0..65535. -
PortInUse(port: Int)The fixed port of
with_portis 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 callreplace_trust_anchorand trust the new root.
pub type TestError {
ProviderStartFailed
AuthorizationRefused(reason: String)
}
Constructors
-
ProviderStartFailedThe provider’s PKI or listener did not start.
-
AuthorizationRefused(reason: String)authorizewas 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.
-
AnchorMismatchThe 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.
-
AnchorExpiredThe 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, thehellhound-root.lockdirectory) 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 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 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 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_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_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_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.