Module hasura 

Hasura’s authentication contract.

Hasura settles three things about a request before any query runs: whether the caller is authenticated at all, which role it is speaking as, and what session variables that role carries. The first is what makes the other two safe, and reading them apart is the fault this module exists to fix.

A caller that holds the admin secret is an administrator, and an administrator may ask to be treated as someone else: X-Hasura-Role: user alongside the secret says “answer as user would be answered”, and the other x-hasura-* headers are that role’s session variables. Naming a role is therefore something an authenticated caller does, not an alternative to authenticating – a role header arriving on its own is an unauthenticated request, and Hasura refuses it.

Where this deliberately differs from Hasura

Hasura configured with no admin secret treats every caller as an administrator, which means an unsecured deployment also lets any caller name its own role and its own identity. This server does not: with no secret configured, x-hasura-* headers are ignored entirely and session variables come from a verified token, as they did before this module existed. A policy reading a value the caller chose is not a policy, and the failure is silent – the query succeeds, against the wrong rows.

Nothing is lost by it. Every case in Hasura’s corpus that names a role sends the secret beside it, because that is what Hasura’s own suite does.

Structs

HasuraAuthConfig

What this server was told about who may claim what.

HasuraIdentity

Who the caller is, in Hasura’s sense of the word.

Enums

SecretOutcome

What the admin secret alone can settle about a request.

TokenRole

Who a verified token’s bearer speaks as.

Constants

ADMIN_ROLE

The name a caller with the secret speaks as unless it asks for another.

BACKEND_ONLY_HEADER

The header whose value is read as a boolean, and Hasura’s refusal for one that is not.

ROLE_NOT_ALLOWED

Hasura’s wording for a caller that asked to be a role its token does not list.

SECRET_INVALID

Likewise.

SECRET_MISSING

Hasura’s own wording, which a migrating client may be matching on.

Functions

allowed_roles

The roles a token allows its bearer to ask to be.

backend_only_requested

Whether a caller asked for the fields a backend_only permission hides.

boolean_text

What Hasura reads as true and false in a header, and the words it uses when a header is neither.

from_admin_secret

Settle what the admin secret says about a request.

role_for_token

Settle which role a verified token speaks as, given what the caller asked for.

role_from_claims

The role a verified token names, if it names one.

session_from_claims

Collect x-hasura-* claims from a verified token as session variables.

session_from_headers

Reduce x-hasura-* headers to session variables.

unauthenticated

The identity a request falls to when nothing authenticated it.

unreadable_boolean_header

Whether a request carries that header with something unreadable in it.