Auth Contracts

This page defines the behaviors you can rely on when integrating with Auth.

Entry-point contract

$auth = auth();
$jwtAuth = auth('jwt');
  • auth(?string $adapter = null): Quantum\Auth\Auth
  • no adapter argument means auth.default is used
  • supported adapter names are session and jwt
  • unknown adapter names fail during resolution

Quantum\Auth\Auth is a forwarding wrapper. It only supports methods implemented by the active adapter.

Auth service contract

Each adapter resolves a service class from auth.<adapter>.service and requires that service to implement Quantum\Auth\Contracts\AuthServiceInterface.

Required methods:

  • get(string $field, ?string $value): ?User
  • add(array $data): User
  • update(string $field, ?string $value, array $data): ?User
  • userSchema(): array

Practical expectations for the service

Your service must be able to:

  • find a user by the mapped username field
  • persist hashed passwords, activation tokens, reset tokens, remember tokens, OTP fields, and refresh tokens
  • return a schema that maps every logical auth key to a real storage field name

If the resolved service does not implement AuthServiceInterface, factory resolution fails.

User schema contract

userSchema() must return an array that includes a name entry for every logical key in AuthKeys.

A field may also include visible => true.

Visible fields are the only fields that Auth:

  • stores in session auth state
  • embeds in JWT access-token data
  • uses when rebuilding Quantum\Auth\User from session or token payloads

Practical consequence: if a field is not marked visible, auth()->user() will not expose it when the current user comes from session or access-token data.

Return-value contract

Common methods behave like this:

  • signin(...)
  • session adapter: true on immediate success, or OTP token string when two-factor auth is enabled
  • JWT adapter: token array on immediate success, or OTP token string when two-factor auth is enabled
  • signout(): bool
  • check(): bool
  • user(): ?Quantum\Auth\User
  • signup(array $userData, ?array $customData = null): Quantum\Auth\User
  • activate(string $token): void
  • forget(string $username): ?string
  • reset(string $token, string $password): void
  • resendOtp(string $otpToken): string
  • refreshUser(string $uuid): bool
  • verifyOtp(int $otp, string $otpToken)
  • session adapter: bool
  • JWT adapter: array<string,string> with fresh tokens

Because signin() and verifyOtp() are adapter-dependent, treat them as flow-specific methods rather than assuming a single return type across all adapters.

Failure contract

Auth throws package exceptions for the user-facing failures that matter most:

  • incorrect credentials
  • inactive account
  • incorrect verification code
  • expired verification code
  • invalid user schema

Other failures can also bubble up from dependent packages such as Config, DI, Mailer, Session, JWT, or your auth service implementation.

Token and state contracts

  • Passwords are hashed before user creation and password reset.
  • Activation, reset, remember, refresh, and OTP tokens are generated by Auth and stored through your auth service.
  • JWT access tokens contain only visible user fields.
  • JWT access tokens are returned in base64-wrapped form by the JWT auth adapter.
  • The JWT adapter sets JWT leeway to 1, which affects token verification through the wrapped JwtToken instance.

User object contract

auth()->user() returns Quantum\Auth\User or null.

The returned user object is a lightweight data container:

  • getData() returns the stored field array
  • getFieldValue($field) reads one field
  • property access such as $user->email proxies to getFieldValue() when that field exists

Do not assume it is a full ORM model unless your own auth service wraps and rehydrates it that way elsewhere.