feat(auth): define provider-neutral authorization contracts

[djwhitt]

Summary

Introduce the provider-neutral authentication and authorization contracts that the OIDC stack will build on:

• Smolquery.Auth.Principal — a structurally validated stable identity with no provider claim bag or token material
• Smolquery.Auth.Context — one principal, an explicit current scope, a closed capability set, and assertion expiry that is required for OIDC and optional for static credentials
• Smolquery.Auth.Policy — fail-closed, expiry-aware authorization that preserves the 401/403 distinction and identifies unknown internal capabilities
• Smolquery.Auth — one attachment seam for Plug connections and LiveView sockets

This is deliberately a behavior-neutral foundation. The existing static API-key and web Basic-auth flows are not rewired in this PR. OIDC discovery, JWT verification, browser redirects, role mapping, and route enforcement are also outside this PR.

Closes T-229. Refs PL-27.

Why this is a separate layer

Without an internal contract, adding OIDC directly to SmolqueryApi.Auth or SmolqueryWeb.Auth would make provider-specific claims the application's authorization model. Controllers and LiveViews would eventually learn about groups, roles, scope, email addresses, or one provider's token shape.

This layer creates the boundary first:

flowchart LR
    subgraph Authenticators[Authentication adapters — outside this PR]
        APIKey[Static API key]
        Basic[Web Basic auth]
        OIDC[OIDC / OAuth tokens]
    end

    APIKey -.-> Principal
    Basic -.-> Principal
    OIDC -.-> Principal

    Principal[Auth.Principal<br/>who authenticated]
    Principal --> Context[Auth.Context<br/>principal + scope + capabilities + expiry]
    Context --> Attach{Request carrier}
    Attach --> Conn[Plug.Conn assigns]
    Attach --> Socket[LiveView.Socket assigns]
    Conn --> Policy[Auth.Policy]
    Socket --> Policy
    Policy --> App[Controllers / LiveViews]

Loading

Authentication adapters are responsible for interpreting provider-specific inputs. Consumers of this contract receive a Principal and ask Policy about a normalized capability.

Design

Principal: identity without provider leakage

Smolquery.Auth.Principal carries:

Field	Meaning
id	Stable opaque identifier used by smolquery
authn	:oidc, :api_key, or :basic
kind	:user or :service
issuer / subject	Canonical external identity for OIDC principals
display_name	Optional descriptive metadata; never identity or authorization input
client_id	Optional calling-client metadata

There is intentionally no field for raw tokens, refresh tokens, provider claims, email, username, groups, or roles.

OIDC identity

The canonical external identity is the exact pair {issuer, subject}. Neither value is trimmed, case-folded, or otherwise normalized.

Principal.oidc/4 derives an opaque, stable pseudonymous identifier using a versioned encoding:

oidc:v1:<base64url(sha256(
  uint32be(byte_size(issuer)) || issuer ||
  uint32be(byte_size(subject)) || subject
))>

Length framing prevents delimiter ambiguity, so {a\0b, c} cannot collide at the encoding layer with {a, b\0c}. Lengths are unsigned big-endian 32-bit byte counts; the full SHA-256 digest uses unpadded base64url. The v1 prefix makes the durable derivation explicit. A fixed test vector prevents accidental changes to this encoding.

Principal.well_formed?/1 recomputes the OIDC ID from issuer and subject; a struct with a substituted ID is structurally rejected. This check does not prove authentication provenance. Only trusted authentication adapters may construct principals, and client input is never decoded directly into these structs.

Smolquery treats differing exact {issuer, subject} pairs as distinct identities, including pairwise subjects issued to different clients or sectors. It never links identities through mutable display claims such as email or username. The derived ID relies on SHA-256 collision resistance and is pseudonymous audit data, not anonymous or categorically non-PII.

Local identities

Principal.local/4 represents credentials managed by smolquery. It accepts only :api_key or :basic; callers cannot create a caller-selected :oidc identity. The caller supplies a stable non-secret source key such as static:api, never the credential itself. The constructor does not retain that source key; it derives the final ID in an authentication-specific namespace:

api_key:v1:<base64url(sha256(frame("api_key:v1:", source_key)))>
basic:v1:<base64url(sha256(frame("basic:v1:", source_key)))>

The disjoint constructor-owned namespaces prevent local identities from colliding with OIDC or with one another. Local ID validation also requires one canonical unpadded base64url encoding.

Both constructors:

• return tagged results;
• require non-empty binary identifiers;
• accept only display_name and client_id options;
• reject duplicate or unknown options;
• reject invalid kinds, authentication methods, and metadata.

Context: authorization is scoped

Smolquery.Auth.Context combines:

%Smolquery.Auth.Context{
  principal: principal,
  scope: :single_tenant,
  capabilities: MapSet.new([:query, :ingest]),
  expires_at: 1_786_800_000
}

The capability vocabulary is closed:

Capability	Intended boundary
:web_access	Enter the human UI
:query	Read metadata and run/read query jobs
:ingest	Insert and load rows
:catalog_manage	Create datasets/tables and update table policy
:platform_operate	Fleet-wide kill, restart, and drain operations

:platform_operate is deliberately separate from tenant-administrator permissions.

Capabilities are stored in a MapSet, so duplicates collapse. Unknown atoms and strings fail construction rather than becoming dynamic atoms or implicit grants. granted?/2 also fails closed for unknown capabilities and malformed contexts.

expires_at is a Unix epoch time in integer seconds and belongs to the request or session context rather than the stable principal identity. It is required for OIDC contexts and optional for local static contexts, which may use nil. Context.active?/2 uses the strict boundary now < expires_at; the context is expired at equality. OIDC adapters must validate token timestamps and apply their bounded clock-skew policy before constructing the context. Policy rechecks the absolute expiry on every authorization decision so a long-lived LiveView socket cannot retain capability access indefinitely.

The single-tenant sentinel

The current scope is explicitly :single_tenant. It is not derived from:

• OIDC issuer;
• email domain;
• provider organization;
• groups or roles.

This makes the scope explicit while leaving a replacement seam for a membership lookup:

(principal_id, tenant_id) -> tenant-scoped capabilities

The PR does not make catalog keys, storage paths, query engines, or datasets tenant-isolated.

Policy: preserve authentication versus authorization

Smolquery.Auth.Policy.authorize/2 has one fail-closed decision path:

flowchart TD
    Start[authorize context, capability] --> Active{Well-formed active context?}
    Active -- No --> Unauthenticated[error: unauthenticated<br/>HTTP adapter maps to 401]
    Active -- Yes --> Known{Known internal capability?}
    Known -- No --> Invalid[error: invalid_capability<br/>programmer/configuration defect]
    Known -- Yes --> Granted{Capability granted?}
    Granted -- Yes --> Allowed[ok]
    Granted -- No --> Forbidden[error: forbidden<br/>HTTP adapter maps to 403]

Loading

The domain layer returns tagged decisions rather than HTTP responses. At HTTP integration boundaries, these decisions map as follows:

• :unauthenticated to 401;
• :forbidden to 403;
• :invalid_capability to an internal programming/configuration failure, never an end-user denial.

A missing, malformed, or expired context is not treated as an authenticated principal with insufficient permissions; it remains unauthenticated. authorize/2 reads Unix time from the system clock, while authorize/3 accepts an explicit timestamp for deterministic tests.

One Plug and LiveView attachment seam

Smolquery.Auth stores a well-formed context under the stable assign key:

:smolquery_auth_context

The same API works for both request carriers:

conn = Smolquery.Auth.assign_context(conn, context)
{:ok, context} = Smolquery.Auth.fetch_context(conn)

socket = Smolquery.Auth.assign_context(socket, context)
{:ok, context} = Smolquery.Auth.fetch_context(socket)

This avoids putting identity into conn.private, which already carries API runtime-instance state, and provides the same normalized attachment contract for Plug connections and LiveView sockets. Route and mount enforcement remain outside this PR.

Assignment rejects malformed contexts. Fetching a missing or malformed assignment returns :error. These attachment checks prove structure only; they do not authenticate a caller or authorize a capability. Trusted adapters establish authentication provenance before assignment, and every access decision goes through Policy, which checks expiry and capabilities. Regression coverage includes partial struct-tagged principal maps and malformed MapSet internals so structural checks fail closed without raising.

Security properties

• Exact {issuer, subject} is the OIDC identity; display metadata cannot change or merge it.
• Derived IDs are opaque stable pseudonymous identifiers, use disjoint authentication namespaces, and are treated as potentially sensitive audit data.
• Raw tokens and arbitrary provider claims have no place in the principal struct.
• Authentication methods and capabilities are closed atom sets; request data is never converted with String.to_atom/1.
• Unknown capability grants fail construction; unknown capabilities requested by trusted application code are distinguished as internal defects.
• Substituted OIDC IDs, invalid local ID encodings, partial struct-tagged maps, invalid scopes, malformed capability sets, and malformed assignments fail structural checks without raising.
• Missing, malformed, or expired identity remains distinguishable from insufficient permission.
• Structural checks do not establish authentication provenance; only trusted adapters construct and attach contexts.
• Principal and tenant identifiers are not introduced as telemetry labels.

What this PR does not do

• No OIDC discovery or JWKS cache
• No JWT signature or claim validation
• No authorization-code/PKCE browser flow
• No provider-role or scope mapping
• No route or LiveView authorization changes
• No job ownership or actor persistence
• No tenant provisioning or data isolation
• No change to internal-secret, gen_rpc TLS, or Erlang-distribution TLS boundaries

Those concerns are outside this PR so the provider-neutral contract remains independently reviewable.

Validation

• 31 focused auth-contract checks pass
• Checks (mix ci), the fast test suite, and Dialyzer pass
• Integration and cluster workflows pass

The tests cover:

• stable OIDC ID derivation and a fixed compatibility vector;
• stable local ID derivation, fixed API-key and Basic compatibility vectors, and disjoint API-key, Basic, and OIDC namespaces;
• canonical local base64url encoding and repeated-prefix rejection;
• cross-issuer and length-boundary identity separation;
• display metadata not affecting or merging identity;
• invalid constructors and structurally inconsistent principals;
• capability normalization, deduplication, and rejection;
• strict expiry behavior before and at the timestamp boundary;
• partial struct-tagged principal maps and malformed context and MapSet internals failing closed without raising;
• 401, 403, and invalid-internal-capability policy decisions;
• Plug and LiveView assignment round trips and malformed-assignment rejection.

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}