authz

func AssertAuthCoverage ¶

func AssertAuthCoverage(schema graphql.ExecutableSchema, exempt ...string) error

AssertAuthCoverage @notice Fails if any field reachable through the schema can be resolved without an @auth annotation. Call it from a test.

func TestAuthCoverage(t *testing.T) {
    schema := generated.NewExecutableSchema(generated.Config{Resolvers: &graph.Resolver{}})
    if err := authz.AssertAuthCoverage(schema, "Query.health", "Mutation.login"); err != nil {
        t.Fatal(err)
    }
}

@dev Deny-by-default, enforced by a test rather than by discipline, and it is the highest value component in this library. The failure mode of resolver-level authorization is a *forgotten* check, and a forgotten check is invisible: it compiles, it passes review, and it returns data. Walking the schema is the only way to see the absence of something.

It is a test and not a check inside New on purpose. A schema author adding a public field should get a red test they can annotate away, not a server that refuses to boot in production because someone shipped a schema change on a Friday.

Every uncovered field is reported at once, sorted, because an implementer annotating a schema wants the whole list and not a fifty-iteration game of whack-a-mole.

Covered means: the field carries @auth, or its parent type does. A field whose parent type is annotated @auth(requires: ANONYMOUS) is public by explicit decision, which is exactly the distinction this function exists to be able to draw.

@param schema the generated executable schema @param exempt field paths deliberately left unannotated, e.g. "Query.health" @return error naming every uncovered field, or nil

func AssertDirectivesWired ¶

func AssertDirectivesWired(directiveRoot any) error

AssertDirectivesWired @notice Fails if any directive implementation on a generated DirectiveRoot is nil.

authz.AssertDirectivesWired(generated.DirectiveRoot{Auth: authz.Directive(...)})

@dev A companion to AssertAuthCoverage rather than part of it, because the two see different things: the schema walk cannot reach the consumer's generated DirectiveRoot struct, which is a type in their module.

It exists because forgetting to wire a directive is a *runtime* error in gqlgen — every annotated field fails with "directive auth is not implemented" on the first request that touches it, and there is no startup validation. Reflection over the struct's func fields is the only way to see that from outside.

@param directiveRoot the generated DirectiveRoot value or pointer @return error naming every unset directive, or nil

func Directive ¶

func Directive(opts DirectiveOptions) func(ctx context.Context, obj any, next graphql.Resolver, requires AuthLevel, roles []string, mfa *bool, proves []string) (any, error)

Directive @notice The @auth implementation, for your generated DirectiveRoot.

c.Directives.Auth = authz.Directive(authz.DirectiveOptions{})

@dev Reads only the context, and never touches the database. That is a hard requirement, not an optimisation: a directive on a field of a list type runs once per row, so a check costing a query is an N+1 that appears only under production load — and luima ships no dataloader to soften it. Everything needed is already on the Principal, resolved once by the middleware.

Nullability interacts with denial, and it is worth knowing before annotating: an error on a nullable field yields null plus an error entry, while on a non-null field it nulls the *parent*, which can blank an entire object. Prefer nullable types for conditionally visible fields.

proves: [] is not the same as an absent proves:. An all-of over an empty set is vacuously true, so the natural implementation allows while the annotation still reads as a restriction, and a schema-generation step that emits [] for an absent list would widen every field it touched without a word. kal denies instead — for anonymous and authenticated callers alike, before any other check — and there is no way to satisfy it. That is the point: nothing writes an empty list on purpose. Omit the argument to mean "no proof requirement".

mfa: true denies until something has stamped auth_sessions.mfa_at, and the window below is measured from it. [session.Sessions.RecordMFA] is that writer and any consumer can reach it, whatever factor it verified first; zkauthn calls it too, so a Groth16 deployment and a TOTP one land in the same column. Failing closed stays the direction — a step-up requirement that silently passes is worse than one that visibly blocks.

The window is compared against the process clock while mfa_at is written by the database's (gotcha 81), so keep both on NTP: the two clocks meet here and nowhere else.

@param opts zero value for the defaults @return func the directive implementation, matching gqlgen's generated field type

func HasRole ¶

func HasRole(ctx context.Context, role string) bool

HasRole @notice Whether the caller holds the named role, case-insensitively.

@param ctx the resolver context @param role the role to look for @return bool false for an anonymous caller

func Scope ¶

func Scope(ctx context.Context, column string) func(*orm.Query) *orm.Query

Scope @notice The caller's ownership predicate, as a luima crud option.

@dev This is the real enforcement, and it is the thing a policy engine structurally cannot give you. A boolean answers "may Alice read document 7"; it does not stop a list query from returning every document, and it cannot be applied to a DELETE without a read-then-check round trip that has a TOCTOU window. Composing the predicate into the statement has neither problem, and the database enforces it.

func (r *mutationResolver) DeleteDoc(ctx context.Context, id string) (bool, error) {
    return luima.Delete(ctx, r.DB, &model.Doc{ID: id}, authz.Scope(ctx, "owner_id"))
}

What falls out for free: a row that exists but is not yours matches nothing, so RowsAffected() is 0, so crud.Delete returns false and crud.Update reports "not found". "Not yours" and "does not exist" become indistinguishable to the caller — which is the correct answer to give an unauthorized one anyway.

An anonymous caller yields a predicate matching nothing, never an open query. Failing closed matters most exactly where the middleware did not run.

The column name is not user input: it comes from the resolver, at compile time. It is still written through pg.Ident, because a variant that ever took it from a request must not be one edit away from SQL injection.

Escape hatch by function type, not interface: anyone whose authorization genuinely needs an external engine calls it inside their own closure and returns q.Where("id = any(?)", pg.Array(ids)). No Authorizer abstraction that exists to be overridden once.

TOCTOU: every crud helper takes orm.DB, so db.RunInTransaction plus passing the *pg.Tx closes the window between a check and a write, and SELECT … FOR UPDATE is expressible through these same options.

@param ctx the resolver context @param column the owning column on the model's table @return func a query option: the ownership predicate, a no-op for a bypass-role caller, or a predicate matching nothing when the caller is anonymous

func WithBypassRole ¶

func WithBypassRole(ctx context.Context, role string) context.Context

WithBypassRole @notice Names the role for which Scope is a no-op — the admin path, as one explicit branch rather than a second set of queries.

@dev Carried on the context rather than read from a package-level var, because a package var would let any consumer in the binary redefine every other consumer's admin role. kal's middleware installs this from Config; a test can install it directly.

@param ctx the parent context @param role the bypass role name; empty installs nothing @return context.Context ctx with the bypass role attached

func WithPrincipal ¶

func WithPrincipal(ctx context.Context, p *Principal) context.Context

WithPrincipal @notice Returns a context carrying p. The session middleware's seam — and a test's.

@dev Exported because the middleware lives in another package and tests need to fabricate callers. That does not weaken the unexported-key property: the key prevents *accidental* collision and overwrite; code that imports authz and calls this does it on purpose, in plain sight.

@param ctx the parent context @param p the caller; nil stores nothing and returns ctx unchanged @return context.Context ctx with p reachable through From and Require

func WithRLS ¶

func WithRLS(ctx context.Context, db *pg.DB, fn func(orm.DB) error) error

WithRLS @notice Runs fn in a transaction whose Postgres session variables carry the caller, for policies written against current_setting.

@dev The third layer of authorization, and the point of it is that it survives a forgotten check in the two above. Four things about this function are load-bearing, and each of them has silently broken a production deployment:

1. Everything happens inside RunInTransaction. SET LOCAL outside a transaction is a no-op — Postgres warns and moves on — and with a connection pool the setting would land on one pooled connection while the query ran on another.
2. set_config's third argument is true, which is what makes the setting transaction-local. A plain session-scoped SET outlives the transaction and leaks to whichever request borrows that connection next: a cross-tenant data leak that only appears under concurrency. It is also what keeps this compatible with PgBouncer in transaction pooling mode, precisely because it dies at COMMIT.
3. set_config with bound parameters, not "SET LOCAL app.user_id = …". SET is not a parameterizable statement, so the string form forces concatenation, which is SQL injection in the one function whose job is authorization.
4. An anonymous caller sets empty strings rather than skipping the settings. A policy must then fail closed — see the warning below.

Two more, on the SQL side, that this function cannot enforce for you:

• ALTER TABLE … FORCE ROW LEVEL SECURITY, or the table owner bypasses every policy. Most migration setups connect as the owner, which means RLS silently does nothing. This is the single most common way an RLS deployment is quietly broken.

• Never write a policy where a NULL or empty setting is permissive. current_setting('app.user_id', true) returns NULL when unset — the true is mandatory or it raises — so a policy reading "current_setting(...) is null or owner_id = ..." fails open on every unconfigured connection.

A policy with both of those right looks like this. nullif turns the anonymous caller's empty string into NULL, and NULL never equals anything, so the predicate matches no rows:

alter table docs enable row level security;
alter table docs force  row level security;
create policy docs_owner on docs
  to app_user
  using      (owner_id = nullif(current_setting('app.user_id', true), '')::uuid)
  with check (owner_id = nullif(current_setting('app.user_id', true), '')::uuid);

Prefer this GUC approach over SET ROLE: a client with any SQL-injection foothold can issue RESET ROLE and escape back to the authenticator role, whereas a GUC hands out no role-switching primitive.

@param ctx the resolver context, read for the caller @param db the pool; a transaction is opened on it @param fn runs with the tx, which it must use for every query the policies should see @return error fn's error, or the transaction's

func WithRLSSettings ¶ added in v0.4.0

func WithRLSSettings(ctx context.Context, db *pg.DB, extra map[string]string,
	fn func(orm.DB) error) error

WithRLSSettings @notice WithRLS, plus consumer settings on the same transaction.

@dev Read WithRLS's doc comment first; all four of its traps apply here unchanged. This exists because a consumer whose tenancy is not a single owner column — an org, a project, a region — otherwise has to copy that function into their own repository and re-derive all four.

The one thing this adds: extra keys are validated against ^app\.[a-z_][a-z0-9_]*$ even though set_config takes its name as a bound parameter and needs no such check. The validation is not load-bearing against injection — it is there so a typo becomes an error instead of a setting no policy reads, which is a policy that silently matches nothing or, worse, silently matches everything.

app.user_id and app.roles are refused; see [reservedSettings] for the bypass that allows.

Keys are applied in sorted order and in one statement, so the query log shows a stable statement rather than one shape per map iteration.

@param ctx the resolver context, read for the caller @param db the pool; a transaction is opened on it @param extra settings to set transaction-locally; keys must be app.-prefixed, and may not be

app.user_id or app.roles. Nil is WithRLS.

@param fn runs with the tx, which it must use for every query the policies should see @return error a rejected key, fn's error, or the transaction's