auth

func AttachProvider ¶ added in v0.18.47

func AttachProvider(ctx context.Context, p *Provider, cat *catalog.Catalog, logger *slog.Logger)

AttachProvider binds p to cat from a constructor that has no error return.

It is BindToCatalog for the three doors whose constructors predate the bind (`server.New`, `pgwire.NewServer`, `NewGRPCServer`): the refusal is logged and, more importantly, REMEMBERED, so `Provider.BindError` refuses every statement rather than letting an unbound set enforce nothing. Attaching a provider to a catalog goes through this or through BindToCatalog and through nothing else — `TestEveryProviderFieldIsAttachedThroughTheBindingFunction` fails when a site appears that does neither.

func AuthorizeTableFunction ¶ added in v0.18.53

func AuthorizeTableFunction(ctx context.Context, provider *Provider, protocol string,
	funcName string, args []string, namedArgs map[string]string) error

AuthorizeTableFunction is the decision for ONE table-function scan: may this identity read this destination?

A table function is a CAPABILITY, not a relation. `read_csv('/etc/shadow')` reads a file off the server's own disk; `read_json('http://10.0.0.5/x')` makes the server issue an HTTP request from inside the network perimeter; `postgres_query(dsn, sql)` opens an outbound database connection to wherever the caller points it. None of these is in the catalog, so before #943 none of them became an ABAC Resource: `logical.PolicedScanTables` and `StatementBaseTables` both skip a function scan, and a role restricted to one catalog table could still read any file the process could read.

The rule, with auth ENABLED, is DEFAULT DENY:

• No provider / auth disabled: allowed, unchanged. The CLI, the embedded engine without SetAuthProvider and every existing no-auth test read files exactly as they did — that is the documented single-user use.
• A pure function (generate_series, unnest): allowed. It opens nothing.
• No identity under auth enabled: refused.
• An ABAC evaluator installed: the evaluator decides, over `Resource{Type: "table_function", Name: <func>, Attributes: {path, url, host}}` with ActionRead. Deny-overrides with a default deny, so a deployment that has never written a rule about table functions refuses them.
• Legacy roles only (no evaluator): the `admin` permission. There is no way to spell "may read server files" in the `read`/`write`/`admin` vocabulary, and reading arbitrary server-local files is an administrator's capability. No new permission words (ADR-0034).

PostgreSQL's precedent for the default: `pg_read_file` is superuser-only and answers `42501 permission denied for function pg_read_file` to an ordinary role, and `COPY … FROM PROGRAM` needs the `pg_execute_server_program` role (both verified on the oracle server). Server-side file and program access is a privilege there too.

func AuthorizeUDFRead ¶ added in v0.18.53

func AuthorizeUDFRead(ctx context.Context, provider *Provider) error

AuthorizeUDFRead decides a SHOW FUNCTIONS.

It requires an identity and no particular permission. That is PostgreSQL's rule for the same information: a role with no privileges on a function reads its body and its owner out of `pg_proc.prosrc`, and `\sf` prints the whole definition. A function body is not data; it is part of the schema the server publishes to the sessions that may call it.

Under auth ENABLED a caller with no identity is still refused, because a door that reaches here with nobody has no one to answer.

func BindPoliciesToCatalog ¶ added in v0.18.47

func BindPoliciesToCatalog(ctx context.Context, cat *catalog.Catalog,
	abacIn []AccessControlPolicy, legacyIn *PolicySet) ([]AccessControlPolicy, *PolicySet, error)

BindPoliciesToCatalog resolves every relation and column a policy set names against cat and returns the BOUND COPY — each name rewritten to the catalog's own spelling — or an error naming the first that does not resolve.

It binds a COPY and never touches its inputs. Two reasons, and both are contracts this package already makes elsewhere. The evaluator it would otherwise rewrite is being READ by every query in flight (`PolicyEvaluator.ruleMatches`), so rewriting in place is a data race on a live security decision. And a bind that fails partway would leave the RUNNING set half-rewritten, which is the opposite of the promise `UpdateFromConfig` makes: a policy set that cannot be installed installs nothing and the previous one keeps running (#802).

All arguments are optional: a deployment may run ABAC only, legacy `policies:` only, or both. A nil catalog binds nothing and returns the inputs unchanged — the caller has no catalog to resolve against, and the fold-aware comparison in relationEq / policyKey is the floor there.

func Build ¶ added in v0.18.53

func Build(cfg Config) (*Authenticator, *Authorizer, error)

Build creates an Authenticator and Authorizer from configuration, reporting a configuration it cannot honour.

A configuration error is an ERROR, never "authentication disabled" (#931):

• `jwt.enabled` with no secret and no readable public key, an unparseable key file, a typo in the path — `NewJWTVerifier`'s error used to be DISCARDED and the verifier left nil.
• `enabled: true` with no usable mechanism at all: no API keys, no JWT, no mTLS. An operator who wrote `enabled: true` did not ask for an open server.
• A credential naming a role the configuration does not define — an `api_keys` entry, an mTLS `role_map` value, an mTLS `default_role` — and `enabled: true` with credentials but no `roles:` at all. Such a credential authenticates and then holds NO permission, so it can do nothing; before this batch it could read everything, because the data path did not consult the role at all. Either way the configuration cannot mean what the operator wrote, and the doctrine is that such a configuration refuses at LOAD rather than behaving surprisingly at runtime.

On error the returned Authenticator is not a disabled one. It reports Enabled() and refuses EVERY credential with the configuration error, so a caller that ignores the error — and every door reads `Provider.Enabled()`, not this — is closed rather than open. Startup and hot reload both report it: `cmd/wadjet` refuses to start, and `Provider.UpdateFromConfig` refuses the swap and keeps the running state.

func ContextWithEnvironment ¶ added in v0.18.53

func ContextWithEnvironment(ctx context.Context, env Environment) context.Context

ContextWithEnvironment attaches the TRUSTED request environment — the one the PROTOCOL BOUNDARY observed, not one any caller below it can assert.

It is attached where the connection is: the HTTP middleware, the pgwire connection handshake and the gRPC authentication interceptor each know the peer address and which protocol they are, and nothing further down does. Anything the client can set (an `X-Forwarded-For` header, a startup parameter, a gRPC metadata value) is NOT trusted here — a source-address condition that a client could forge is not a control.

`Time` is deliberately NOT stamped at attach time. A pgwire connection lives for hours and a policy conditioned on `env.hour` has to mean the hour the STATEMENT ran, not the hour the socket opened; the decision stamps it (see DecisionEnvironment).

A `SourceIP` carrying a PORT is reduced to its host here, once, so no door has to remember: `net.Conn.RemoteAddr()` and `http.Request.RemoteAddr` are `host:port`, while `env.source_ip` is documented and written as an IP. The HTTP door passed `r.RemoteAddr` straight through, so a documented `env.source_ip eq "127.0.0.1"` rule compared against `127.0.0.1:54321` and never matched (#933).

func ContextWithIdentity ¶

func ContextWithIdentity(ctx context.Context, id *Identity) context.Context

ContextWithIdentity returns a new context with the given identity.

func ContextWithRowFilters ¶

func ContextWithRowFilters(ctx context.Context, filters RowFilters) context.Context

ContextWithRowFilters returns a context carrying row filter predicates.

func ContextWithTableDecisions ¶

func ContextWithTableDecisions(ctx context.Context, decisions TableDecisions) context.Context

ContextWithTableDecisions returns a context carrying ABAC table decisions.

func EnforceDMLPolicies ¶ added in v0.18.38

func EnforceDMLPolicies(ctx context.Context, provider *Provider, cat *catalog.Catalog,
	parsed *plansql.ParsedQuery, protocol string) error

EnforceDMLPolicies applies ABAC to an INSERT / UPDATE / DELETE / MERGE before any row is read or written. It is called from the ONE DML entry point (wadjet.DB.ExecuteParsed), so the embedded door, the pgwire door and the HTTP API server all carry it.

Two rules, and they are the SELECT door's rules said for a statement that writes (ADR-0033):

1. **A DML statement is an ActionWrite.** An identity whose policies grant it no write on the table is refused with 42501 before anything happens. A role allowed only `read` used to be able to run `DELETE FROM t WHERE ssn = '<stored value>'` and destroy the row.

2. **A read inside the statement sees what a SELECT would see.** A column the policy DENIES does not exist, so naming it in a predicate, a SET target or a SET expression is 42703 — before #859 `UPDATE t SET dept='z' WHERE salary = 700009` matched exactly the row with that salary, a working oracle for a column the identity may not read. A MASKED column reads as its mask, so `WHERE ssn = '<stored value>'` matches nothing and `SET dept = ssn` writes '***' instead of copying the stored value into a column the identity may read.

Rule 2 is a SUBSTITUTION rather than a projection because a DML predicate is compiled, not planned (ADR-0031): there is no Scan for a security projection to sit on. Where the substitution cannot be done soundly the statement is REFUSED, never run against the stored row.

No-ops when the provider is nil/disabled, no identity is attached, or the provider has no evaluator — the same contract EnforcePlanPolicies keeps.

func EnforceOptimizedPlan ¶ added in v0.18.38

func EnforceOptimizedPlan(ctx context.Context, cat *catalog.Catalog, plan *logical.Node) (*logical.Node, error)

EnforceOptimizedPlan re-applies the column policies the context carries to any policed scan the OPTIMIZER minted. Call it immediately after logical.Optimize, at every entry point that optimizes a plan.

The decorrelation passes re-parse a subquery from its SQL text and build a fresh Scan for it, after enforcement has run. Those scans read the stored column: `WHERE a.ssn IN (SELECT ssn FROM t b)` compared the outer's mask against the inner's stored value and answered 0 where both sides masked answer every row. It is a no-op — one tree walk — when the context carries no policy.

func EnforcePlanPolicies ¶

func EnforcePlanPolicies(ctx context.Context, provider *Provider, cat *catalog.Catalog, selectInfo *plansql.SelectInfo, plan *logical.Node, protocol string) (context.Context, *logical.Node, error)

EnforcePlanPolicies applies ABAC to a query at plan level: table-access denial, column deny/mask injection and row-filter injection for every table the plan READS. It is THE shared enforcement path — the embedded engine (wadjet.DB.Query), the HTTP door and the coordinator's native-DAG executor all call it with the same inputs, so an identity sees identical policy behavior regardless of which door and which execution path answers.

Masking and denial are PLAN-TIME, at the scan, unconditionally (#859):

• The security projection is built from the TABLE's catalog schema, which is always known here, and never from the scan's pruned column list. `SELECT *`, an aggregate-only SELECT list and a derived table all leave that list empty, and those are exactly the queries a mask matters most for.
• The relations to police come from the PLAN, not from the statement's FROM list. `plansql.SelectInfo.Tables` carries a derived table under its own subquery TEXT, a CTE reference under the CTE's name, and NOTHING at all for the arms of a UNION — so a `UNION ALL` over a masked column was unmasked on every door, and a query with a derived table or a CTE was default-DENIED under the name `"(SELECT ...)"`.
• A column policy that cannot be applied REFUSES. A security control never degrades to a grant (#802).

The returned context carries the resolved policies so the physical planner applies the same projection to an expression subquery, which it plans on its own (physical.buildSubqueryPipeline).

No-ops (returns the plan unchanged) when the provider is nil/disabled, no identity is attached to ctx, or the provider has no evaluator — matching the embedded engine's historical behavior. protocol labels the evaluation environment for policy conditions and audit.

func LoadClientCA ¶

func LoadClientCA(caFile string) (*x509.CertPool, error)

LoadClientCA loads a CA certificate pool for verifying client certificates. Used when building the tls.Config for the HTTP server.

func Middleware ¶

func Middleware(authn *Authenticator, logger *slog.Logger) func(http.Handler) http.Handler

Middleware returns HTTP middleware that authenticates requests. Health check endpoint is always allowed without auth.

func NarrowQueryLimits ¶ added in v0.18.42

func NarrowQueryLimits(a, b *config.QueryLimits) *config.QueryLimits

NarrowQueryLimits folds b into a, keeping the SMALLER of every ceiling either sets. Two policed relations in one statement each impose their own ceiling and the statement is held to the tighter.

func New ¶

func New(cfg Config) (*Authenticator, *Authorizer)

New creates an Authenticator and Authorizer from configuration.

It is Build with the error folded into the Authenticator rather than returned: on a configuration error the Authenticator is ENABLED and refuses every credential (see Build). The signature is kept because it is what the embedded API and a long tail of tests call; a caller that can report the error should call Build.

func NewTLSConfig ¶

func NewTLSConfig(serverCertFile, serverKeyFile string, clientCA *x509.CertPool) (*tls.Config, error)

NewTLSConfig creates a tls.Config for the server with mTLS client verification. serverCert and serverKey are paths to the server's TLS certificate and key. clientCA is the CA pool for verifying client certificates.

func ProviderMiddleware ¶

func ProviderMiddleware(provider *Provider, logger *slog.Logger) func(http.Handler) http.Handler

ProviderMiddleware returns HTTP middleware that reads the current Authenticator from a Provider on every request. This enables hot-reload: when auth config changes, the Provider is atomically updated and subsequent requests see the new config with zero downtime.

func QueryLimitObligation ¶ added in v0.18.42

func QueryLimitObligation(ob Obligation) (target string, n int64, err error)

QueryLimitObligation reads one query_limit obligation, or says why it cannot be enforced as written. ValidateABACPolicies calls it at config load and at hot reload so a policy that cannot be enforced does not load; the evaluator calls it again on a provider built in process.

func RateLimitMiddleware ¶

func RateLimitMiddleware(rl *RateLimiter, logger *slog.Logger) func(http.Handler) http.Handler

RateLimitMiddleware returns HTTP middleware that enforces per-identity rate limits. Unauthenticated requests use the remote address as identity.

func RequirePermission ¶

func RequirePermission(provider *Provider, ctx context.Context, perm string) error

RequirePermission enforces that the caller in ctx holds perm, but only when the provider is present and auth is enabled. It is the gate for privileged DDL (e.g. CREATE/DROP/ALTER ALERT, CREATE/DROP TABLE, ANALYZE, CREATE/DROP FUNCTION) that has no per-row ABAC surface of its own. Fail-closed contract: with auth enabled, a missing identity or an identity lacking perm is rejected; with auth absent/disabled it returns nil (dev/embedded, nothing to enforce).

The refusal carries PostgreSQL's 42501 (insufficient_privilege), because a client branches on the CLASS and this is the only thing it can branch on: an authorization refusal that crossed pgwire without a code arrived as the blanket 42000, indistinguishable from a syntax error, and through the HTTP door as a bare message. `sqlerr.Wrap` keeps the chain, so `errors.Is(err, ErrUnauthorized)` still holds for the in-process callers.

func StampDefiner ¶

func StampDefiner(ctx context.Context, provider *Provider, snap IdentitySnapshot) (context.Context, bool)

StampDefiner stamps snap's identity onto ctx for definer's-rights execution (e.g. a scheduled alert query running as its creator) and reports whether the definer is attributed — i.e. whether a real identity was recorded.

• provider nil / auth disabled: ctx is returned unchanged with true — there is no policy to enforce (dev/embedded).
• auth enabled: snap.ToIdentity() is ALWAYS stamped, even for an empty (legacy) snapshot. A nil identity is refused outright now (ADR-0034 item 7), and an unattributed alert should say WHY rather than fail as "authentication required": stamping a role-less identity routes it into the same default-deny with attributed=false, so the caller can warn that the alert needs recreating under an identity.

The stamped identity's GRANTS are re-resolved from the Authorizer's current role definitions (`Authorizer.ResolveRole`). A snapshot records who the definer was and not what they could do, so the grants cannot be stale: an alert whose creator's role has since lost `write`, or been deleted, is refused on its next tick. Without this the definer carried an empty `Perms` and `Tables`, which the coarse gate and `CanAccessTable` read — so on a `roles:`-only deployment every scheduled alert stopped running.

func StatementBaseTables ¶ added in v0.18.38

func StatementBaseTables(ctx context.Context, cat *catalog.Catalog, info *plansql.SelectInfo) []string

StatementBaseTables lists the relations a statement's FROM and JOIN clauses name that the catalog recognises as TABLES.

It is the filter every access check needs, because plansql.SelectInfo.Tables is not a list of tables: a derived table appears under its own subquery TEXT (`"(SELECT ssn FROM t)"`) and a CTE reference under the CTE's name. Handing those to a default-deny evaluator refused every query with a derived table or a CTE under a policy that named neither (#859). A table function is not a catalog relation and is skipped for the same reason.

With no catalog to ask, it returns the FROM-list names unchanged — the pre-#859 behavior for a caller that cannot tell a table from a subquery.

func TableAccess ¶ added in v0.18.53

func TableAccess(ctx context.Context, provider *Provider, table string, action Action) error

TableAccess is the ONE effective table-access decision every door asks for a catalog table it is about to read metadata of or act on.

It exists because the doors did not agree. `SHOW TABLES` filtered on the HTTP door and on no other; `DESCRIBE` refused on one door and answered on the rest; a DDL statement asked `HasPermission` and never asked whether the identity may touch THAT relation. Each of those is a separate reading of the same question, and a security decision with several readings has the weakest one for its answer. The decision lives here now, and a door that re-implements it has forked it.

The rule, in order:

• Provider nil, or auth disabled: nil. There is nothing to enforce (dev, embedded without SetAuthProvider), and nothing changes.
• A policy set that could not be BOUND to the catalog: refused. An unbindable set enforces nothing, and a rule that matches nothing is a grant beside a broad allow (#882, ADR-0033 rule 3).
• Auth enabled with NO identity in the context: refused. Authentication proves who; a door that reaches here with nobody has no one to authorize.
• The role's `allow` list, in BOTH provider shapes: `HasPermission(id, perm(action))`. It is a COARSE GATE — a policy narrows what a role may do and never widens it — and `admin` grants everything, as it always has.
• Then, with an ABAC evaluator installed: the EVALUATOR decides (`EvaluateTableAccess`), which is deny-overrides with a default deny — explicit denies win, an unmatched request is refused.
• With no evaluator: `CanAccessTable(id, table)`, the other half of the legacy rule. The permission alone is not access to a relation, and the relation alone is not permission to write it.

`table` must be the CATALOG-RESOLVED spelling (`catalog.ResolveTableName`): an unquoted identifier folds at the lexer (#731), and a policy bound to `Users` must police a statement that spelled it `users`.

The environment comes from the context — attached at the protocol boundary, never from a caller below it — through the one builder every enforcement path uses (`DecisionEnvironment`), so `Time` is stamped at DECISION time. A pgwire connection lives for hours; an `env.hour` condition means the hour the statement ran.

The refusal is a `sqlerr` 42501, which every door renders in its own class: pgwire SQLSTATE 42501, HTTP 403, gRPC codes.PermissionDenied, and the same error verbatim on the embedded API. Its TEXT is PostgreSQL's and carries nothing else — not the rule that denied, not the reason. Which rule fired is operator information and goes to the audit log; telling the refused caller is a disclosure, and a policy rule id names the control that stopped them.

func ValidateABACPolicies ¶ added in v0.18.38

func ValidateABACPolicies(policies []AccessControlPolicy) error

ValidateABACPolicies refuses a policy set whose obligations cannot be enforced as written. It runs where ParsePolicies' own refusal runs — at config load and at hot reload — and for the same reason (#802): a column-access control that cannot be understood must refuse to load, because the alternative is an operator who believes a column is masked and is served it in the clear.

The two refusals:

• A `mask_column` obligation carrying NEITHER `value` nor `mask_func`. The enforcement path dropped such an obligation, so the column came back in the clear on every door. The type-derived placeholder ('***', 0, false) belongs to the LEGACY `policies: columns: {col: mask}` form, which MigrateRBACToABAC spells as `mask_func: redact`; an `abac_policies:` obligation says what it means with `value:`.
• A `mask_column` whose `value` is not a SQL EXPRESSION. `value: "***REDACTED***"` — the spelling docs/configuration.md shipped for twelve releases — does not parse, and the fallback turned every masked column, string numeric and timestamp alike, into `0`. A mask that silently redefines itself is the same class of defect as one that silently disappears.

A `deny_column` or `mask_column` with no target names no column and is refused for the same reason.

It also enumerates the SECURITY VOCABULARY — effect, action, condition operator, condition attribute namespace, obligation type — and refuses a word outside it (#932). Every one of those fields used to accept anything: `effect: dney` became an ALLOW that granted what the operator wrote a deny for, an obligation type `deny_colum` was dropped and the column came back in plaintext, and an operator or attribute the evaluator does not implement made its rule never match, which beside a broad allow is a grant. A closed vocabulary that nothing checks is not a vocabulary.

func ValidateStatementColumns ¶ added in v0.18.38

func ValidateStatementColumns(ctx context.Context, provider *Provider, cat *catalog.Catalog, info *plansql.SelectInfo, protocol string) error

ValidateStatementColumns is the plan-time name binding every query entry point runs before it builds a logical plan, done over the schema the CALLING IDENTITY can see.

It replaces a bare physical.Planner.ValidateColumns at those entry points. The unfiltered binder answers `SELECT nosuchcol FROM t` with a hint that lists the table's columns, and a column the policy DENIES has no business in that list: an identity that may not read `salary` may not learn that `salary` exists either. The policy is resolved LAZILY, per table, as the binder resolves relations — so it covers CTE bodies, derived tables, subquery blocks and set-operation arms without needing a plan.

TABLE-LEVEL DENIAL IS DECIDED HERE TOO, since #946, and it has to be.

The position this comment used to state — that table denial stays in EnforcePlanPolicies so the order of the two refusals does not change — was answerable only while the binder's diagnostic said nothing about a relation. It says a great deal: `SELECT nocol FROM secret` answered `unknown column "nocol" (available: id, note)` for an identity that may not read `secret`, on every door and under BOTH provider shapes, and the hint POOLS relations — `SELECT id FROM emp WHERE id = (SELECT MAX(nocol) FROM secret)` published emp's columns unioned with secret's. `docs/security.md` and ADR-0034 say an identity that may not read a table may not read its schema either, and an error's hint is schema.

So the decision is asked PER RELATION as the binder resolves it (policedColumnSource.GetTable), which is the only seam that sees CTE bodies, derived tables, subquery blocks and set-operation arms as well as the FROM list. It is the SHARED rule — `TableAccess`, ADR-0034 item 5 — so the answer and its sentence are the ones every other door gives, and it is installed in BOTH provider shapes: the legacy `roles:` shape denies relations too, and it was publishing their columns just as loudly.

What changes for a denied relation is the CLASS of an existing refusal: 42703 with a column list becomes 42501 with none. What does not change is a relation the identity MAY read (42703 with the list, exactly as before), a relation that does not exist (42P01 — the decision is asked only after the catalog finds the table), or a statement with no provider.

func VisibleTables ¶ added in v0.18.53

func VisibleTables(ctx context.Context, provider *Provider, tables []string) []string

VisibleTables filters tables to the ones TableAccess allows this identity to READ, preserving order.

It is what a listing door (`SHOW TABLES`, the HTTP table list, the gRPC ListTables) hands back, so a name an identity may not read is not published by the listing either. That is a deliberate divergence from PostgreSQL, which shows `\d` to anyone: the product's position is that metadata follows the effective table-access decision (ADR-0034), and the HTTP door already behaved this way before the other doors did.

With the provider nil or auth disabled the input is returned as it is — same slice, same nil-ness — so a no-auth deployment allocates nothing and sees no change.