API AuthRoutes

Caligrafy\AuthRoutes

Caligrafy Quill 2.26.0. Generated from the source by php qa/build-api-reference.php; the guides explain how to use these classes, this reference says exactly what each public method takes and returns. Back to the API reference.

Part of Routing and requests.

namespace Caligrafy;

class AuthRoutes

Source: framework/core/AuthRoutes.php:40

Class AuthRoutes (2.19.0) Route::auth() (after Auth::authentication('User', 'users') in web.php) registers, with the views of the authentication module (application/views/Auth/login.pug and register.pug):

GET  /login           the sign-in page (a signed-in person goes to 'home')
POST /login           signs in: the username (or 'identifier') and passcode fields, checked with the model's
                      findByUsername() (another identifier: its findBy($column, $value), else the query builder)
                      and verifyPassword() (an old encrypted passcode is upgraded to a hash); a new session id
                      (session_regenerate_id(true)) and a new CSRF token; then 'home'
GET|POST /logout      signs out: a new session id and CSRF token, then 'logout'
GET  /notAuthorized   where Auth::guard() sends people below the level a page needs (403)
GET|POST /register    the sign-up page and the register_user capability (every input its rules declare), then the
                      sign-in page, or signed in and 'home' with 'signInAfterRegister' ('register' => false: none)
with 'passkeys' => true, the JSON endpoints of Caligrafy\Passkey (the passkeys table of the face login recipe, the
page sends the X-CSRF-Token header; public/js/services/passkey.js in the browser):
POST /passkey/register/options, /passkey/register (signed in), /passkey/login/options, /passkey/login

Failed sign-ins are counted per IP and username (Throttle, in the Cache): after 'attempts' (5) within 'lock' seconds (900) that username is refused from that address (429) until the window ends. Options: prefix (''), home ('/'), logout ('/'), register (true, or the name of the capability), attempts, lock, views (['login' => 'Auth/login', 'register' => 'Auth/register']), passkeys (false), identifier ('username': the users column people sign in with and the name of its field, 'email' for instance), signInAfterRegister (false), attemptsPerUser (2.19.6: failures of one username from any address before it is locked, 0 = off), level (2.19.5: the lowest permission level that may sign in, 0 by default; below it, the sign-in is refused like a wrong password), messages (what sign-in and sign-up say: 'invalid', 'locked' ({minutes} is the wait), 2.19.3; 'mismatch', 'register_invalid', 'register_taken', 'registered', 2.19.4; see AuthRoutes::MESSAGES). A failed sign-in shows the page again with what the person typed in the identifier field (never the password). A JSON request (Accept: application/json) gets JSON answers and needs the X-CSRF-Token header. Not provided by the framework, so refused with a LogicException: 'face' (the face login recipe has its own controller and tables) and 'reset' (password reset: the users table has no email address).

Constants

• RETURN_TO = '__auth_return': the session key of the page to go back to after signing in (2.20.0)
• SIGNED_IN_BY = '__auth_signed_in_by': the session key of how this session signed in (2.21.3)
• DUMMY_HASH = '$2y$10$B0NLUgDUK3CbImwrVfa/FuOtSOKrb7DZTGG3USPSF4Comn4cy5RtG'
• MESSAGES = ...

Public properties

• public static $signUp = null: bool|null whether a Route::auth of this request has a sign-up page (null: no Route::auth)
• public static $regenerate = null: callable|null replaces session_regenerate_id(true) (tests)

Methods

• AuthRoutes::signUpOpen()
• AuthRoutes::mayEnter()
• AuthRoutes::options()
• AuthRoutes::register()
• AuthRoutes::attempt()
• AuthRoutes::signIn()
• AuthRoutes::rememberSignIn()
• AuthRoutes::signedInBy()
• AuthRoutes::signOut()
• AuthRoutes::regenerate()
• AuthRoutes::finder()
• AuthRoutes::registerInput()
• AuthRoutes::registration()
• AuthRoutes::ip()
• AuthRoutes::safeReturn()

AuthRoutes::signUpOpen()

public static function signUpOpen()

Whether the site has a sign-up page (2.19.6, the top bar and the sign-in page): true without Route::auth, and when a Route::auth of the request has one; false when every Route::auth says 'register' => false

Source: framework/core/AuthRoutes.php:67

AuthRoutes::mayEnter()

public static function mayEnter($user, $level)

Whether a user may sign in: their permission level (Context::$levelAttribute) is at least Route::auth's 'level'

Parameters

• $user
• $level

Source: framework/core/AuthRoutes.php:75

AuthRoutes::options()

public static function options(array $options)

The options with their defaults

Parameters

• $options array

Source: framework/core/AuthRoutes.php:90

AuthRoutes::register()

public static function register(array $options = array())

Registers the routes (Route::auth)

Parameters

• $options array, default array()

Source: framework/core/AuthRoutes.php:128

AuthRoutes::attempt()

public static function attempt(
    $username,
    $password,
    $ip,
    Throttle $throttle,
    callable $find,
    $level = 0,
    $perUser = 0
)

Checks a username and a password, with the failures counted per IP and username

Parameters

• $username string: the value of the identifier (the username, the email address...)
• $password
• $ip
• $throttle Throttle
• $find callable: function (string $username): ?user (a model with verifyPassword())
• $level, default 0
• $perUser, default 0

Returns array: ['status' => 'ok', 'user' => $user] | ['status' => 'invalid'] | ['status' => 'locked']

Source: framework/core/AuthRoutes.php:157

AuthRoutes::signIn()

public static function signIn($user, ?callable $authorize = null, $how = null)

Signs a user in: a new session id (fixation), a new CSRF token, then Auth::authorize()

Parameters

• $user
• $authorize ?callable, default null: replaces Auth::authorize (tests)
• $how, default null

Source: framework/core/AuthRoutes.php:190

AuthRoutes::rememberSignIn()

public static function rememberSignIn($how)

Records how this session signed in (2.21.3), for what only some sign-ins may do: 'password', 'passkey', 'face'... signIn() does it with its third argument; a page that signs in with Auth::authorize() calls it itself.

Parameters

• $how

Source: framework/core/AuthRoutes.php:202

AuthRoutes::signedInBy()

public static function signedInBy()

How this session signed in (2.21.3): 'password' or 'passkey' through Route::auth, what the application recorded otherwise, null when nobody recorded it. A sign-in that does not prove a person (a face without a liveness check) must not be able to change how the account signs in: check this first.

Source: framework/core/AuthRoutes.php:216

AuthRoutes::signOut()

public static function signOut(?callable $unauthorize = null)

Signs out: Auth::unauthorize(), a new session id and a new CSRF token

Parameters

• $unauthorize ?callable, default null

Source: framework/core/AuthRoutes.php:224

AuthRoutes::regenerate()

public static function regenerate()

session_regenerate_id(true) and a new CSRF token (self::$regenerate in tests)

Source: framework/core/AuthRoutes.php:234

AuthRoutes::finder()

public static function finder($model, $identifier = 'username')

How a user is found by the value people sign in with: findByUsername() for 'username' when the model has it, else the model's findBy($column, $value), else a bound query of the query builder on the model's table

Parameters

• $model
• $identifier, default 'username'

Returns callable: function (string $value): ?user

Source: framework/core/AuthRoutes.php:249

AuthRoutes::registerInput()

public static function registerInput($capability, array $parameters)

What the sign-up form sends to the register capability: every input its rules declare (the username and the passcode when the capability is unknown)

Parameters

• $capability
• $parameters array

Source: framework/core/AuthRoutes.php:268

AuthRoutes::registration()

public static function registration(array $o, array $p, Context $context, $json = false)

What a sign-up leads to, without a request (signUp() answers it; tests)

Parameters

• $o array: the options (options())
• $p array: the parameters of the form
• $context Context
• $json bool, default false: a JSON request (its CSRF header is checked before)

Returns array: ['status' => int, 'json' => array] | ['view' => name, 'data' => array] | ['redirect' => path]

Source: framework/core/AuthRoutes.php:291

AuthRoutes::ip()

public static function ip()

The address of the request (REMOTE_ADDR: a forwarded header can be written by anyone)

Source: framework/core/AuthRoutes.php:325

AuthRoutes::safeReturn()

public static function safeReturn($return)

Whether ?return= of the sign-in page is a page of this site (2.20.0): a path, never another site

Parameters

• $return

Source: framework/core/AuthRoutes.php:335