API Auth

Sign-in

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.

Users and sessions, passkeys and face login.

Class	What it is
Caligrafy\Auth	Class that defines the properties and methods of an authentication mechanism for UI and API
Caligrafy\Passkey	Passkey wraps lbuchs/webauthn (MIT, no dependencies besides ext-openssl).
Caligrafy\PasskeyException	(no doc comment)
Caligrafy\FaceLogin	Face login checks used with FaceDetector.liveness() (public/js/services/detect.js)
Caligrafy\FaceLoginException	(no doc comment)

class Caligrafy\Auth

namespace Caligrafy;

class Auth extends \stdClass

Source: framework/core/Auth.php:19

Class that defines the properties and methods of an authentication mechanism for UI and API

Public properties

• public static $api = false

Methods

• Auth::activateAPI()
• Auth::authentication()
• Auth::authorize()
• Auth::unauthorize()
• Auth::api()
• Auth::active()
• Auth::model()
• Auth::reset()
• Auth::find()
• Auth::authorized()
• Auth::guard()
• Auth::logout()
• Auth::user()

Auth::activateAPI()

public static function activateAPI()

Activate API by creating an API token

Returns boolean: of success of completion of the method

Source: framework/core/Auth.php:29

Auth::authentication()

public static function authentication($modelname, $tablename)

Activate User Authentication - instructs the framework that an authentication can be used

Parameters

• $modelname: defines the name of the model associated with the Authentication
• $tablename: defines the name of the database table associated with the Authentication

Returns boolean: of success of completion of the method

Source: framework/core/Auth.php:40

Auth::authorize()

public static function authorize($user)

Method used upon login to authorize the logged in user

Parameters

• $user Model: defines the user model that needs to be authorized

Returns boolean: of success of completion of the method

Source: framework/core/Auth.php:52

Auth::unauthorize()

public static function unauthorize()

Method used upon logout to unauthorize all users

Source: framework/core/Auth.php:64

Auth::api()

public static function api()

Getter that returns the API token

Source: framework/core/Auth.php:71

Auth::active()

public static function active()

Whether authentication is set up (Auth::authentication() was called in web.php)

Source: framework/core/Auth.php:79

Auth::model()

public static function model()

A copy of the authentication model (null when authentication is off): Route::auth() finds users with it

Source: framework/core/Auth.php:87

Auth::reset()

public static function reset()

Turns authentication off again (tests)

Source: framework/core/Auth.php:95

Auth::find()

public static function find($id)

Loads a user by id with the authentication model (null when authentication is off or the user does not exist)

Parameters

• $id

Source: framework/core/Auth.php:103

Auth::authorized()

public static function authorized()

Method that checks if the user in session is authorized to perform actions

Returns boolean: of whether or not the user is valid and allowed to perform actions

Source: framework/core/Auth.php:117

Auth::guard()

public static function guard(
    $permissionAttribute,
    $acceptedPermission,
    $loginUrl = "/login",
    $notAuthorized = '/notAuthorized'
)

Method that checks if the user in session has permissions to access

Parameters

• $permissionAttribute
• $acceptedPermission
• $loginUrl, default "/login"
• $notAuthorized, default '/notAuthorized'

Returns boolean: of whether or not the user is valid and allowed to perform actions

Source: framework/core/Auth.php:132

Auth::logout()

public static function logout($redirectUrl = '/')

Method that logs the user out

Parameters

• $redirectUrl, default '/'

Source: framework/core/Auth.php:150

Auth::user()

public static function user()

Method that returns the currently logged in user

Returns currently: logged in user

Source: framework/core/Auth.php:164

class Caligrafy\Passkey

namespace Caligrafy;

class Passkey extends \stdClass

Source: framework/core/Passkey.php:34

Passkey wraps lbuchs/webauthn (MIT, no dependencies besides ext-openssl). The browser side is public/js/services/passkey.js (PasskeyClient.create() / PasskeyClient.get()).

Registration (logged-in user): registrationOptions($id, $username) -> navigator.credentials.create() -> register($response, $id) Authentication: authenticationOptions([$id]) -> navigator.credentials.get() -> authenticate($response) returns the user id

The challenge of each ceremony is kept in the session: single use, it expires after $timeout seconds. Relying party: PASSKEY_RP_ID (the domain, ex: example.com) and PASSKEY_ORIGIN (ex: https://www.example.com) in .env. Without them the request host is used, which is fine in development: set both in production. Passkeys need https, except on localhost.

Table (see the face login recipe / wiki 9.9.2):

passkeys (id, user_id, credential_id, public_key, sign_count, name, transports, aaguid, created_at, last_used_at)

Constants

• SESSION_KEY = '__passkey_challenge'

Public properties

• public $timeout = 120
• public $userVerification = 'required'
• public $residentKey = 'required'

Methods

• ->__construct()
• ->rpId()
• ->origin()
• ->registrationOptions()
• ->register()
• ->authenticationOptions()
• ->authenticate()
• ->credentials()
• ->findCredential()
• ->remove()
• Passkey::toBase64Url()
• Passkey::fromBase64Url()

->__construct()

public function __construct($rpName = null, $rpId = null, $origin = null, $table = 'passkeys')

Parameters

• $rpName string|null, default null: name shown by the browser (default APP_NAME or the rp id)
• $rpId string|null, default null: domain (default PASSKEY_RP_ID, else the request host)
• $origin string|null, default null: exact origin the browser must report (default PASSKEY_ORIGIN, else APP_PROTOCOL://request host)
• $table string, default 'passkeys': credentials table

Source: framework/core/Passkey.php:54

->rpId()

public function rpId()

No doc comment.

Source: framework/core/Passkey.php:74

->origin()

public function origin()

No doc comment.

Source: framework/core/Passkey.php:75

->registrationOptions()

public function registrationOptions($userId, $userName, $displayName = null)

Options for navigator.credentials.create() (pass them to PasskeyClient.create())

Parameters

• $userId mixed: id of the logged-in user (stored as the WebAuthn user handle: never an email or a name)
• $userName
• $displayName, default null

Source: framework/core/Passkey.php:81

->register()

public function register($response, $userId, $name = null)

Verifies the response of navigator.credentials.create() and stores the credential

Parameters

• $response array: from PasskeyClient.create(): id, clientDataJSON, attestationObject, transports
• $userId
• $name, default null

Returns array: the stored credential (without the public key)

• @throws PasskeyException

Source: framework/core/Passkey.php:97

->authenticationOptions()

public function authenticationOptions($userId = null)

Options for navigator.credentials.get() (pass them to PasskeyClient.get())

Parameters

• $userId mixed, default null: Optional. Limits the prompt to this user's passkeys; null lets the browser offer any discoverable passkey of the site (login without a username)

Source: framework/core/Passkey.php:135

->authenticate()

public function authenticate($response)

Verifies the response of navigator.credentials.get()

Parameters

• $response array: from PasskeyClient.get(): id, clientDataJSON, authenticatorData, signature, userHandle

Returns string: the id of the user who owns the passkey

• @throws PasskeyException (401)

Source: framework/core/Passkey.php:150

->credentials()

public function credentials($userId)

Storage: override these 4 methods to keep the credentials somewhere else

Parameters

• $userId

Source: framework/core/Passkey.php:179

->findCredential()

public function findCredential($credentialId)

No doc comment.

Parameters

• $credentialId

Source: framework/core/Passkey.php:184

->remove()

public function remove($userId, $credentialId)

No doc comment.

Parameters

• $userId
• $credentialId

Source: framework/core/Passkey.php:201

Passkey::toBase64Url()

public static function toBase64Url($binary)

No doc comment.

Parameters

• $binary

Source: framework/core/Passkey.php:250

Passkey::fromBase64Url()

public static function fromBase64Url($value)

No doc comment.

Parameters

• $value

Source: framework/core/Passkey.php:256

class Caligrafy\PasskeyException

namespace Caligrafy;

class PasskeyException extends \Exception

Source: framework/core/Passkey.php:32

No doc comment on this class.

No public methods.

class Caligrafy\FaceLogin

namespace Caligrafy;

class FaceLogin extends \stdClass

Source: framework/core/FaceLogin.php:30

Face login checks used with FaceDetector.liveness() (public/js/services/detect.js)

1. challenge($username) issues a nonce and $count of the CHALLENGES in a random order, kept in the session
2. the browser runs detector.liveness({ challenges }) and posts { nonce, liveness, prints }
3. verify($response, $username) consumes the nonce (single use, short lived) and checks the liveness result and the prints: enough of them, consistent with each other (same face) and not identical (a replayed static print)
4. match($prints, $enrolled) finds the account whose enrolled prints are close to every print

Face prints are computed in the browser: these checks stop photos, naive replays and stolen requests, they do not stop a determined attacker who controls the browser. Use a passkey (Caligrafy\Passkey) for sensitive accounts.

Distances are euclidean between 128-number face-api descriptors: same person usually < 0.5, others > 0.6

Constants

• SESSION_KEY = '__face_challenge'
• CHALLENGES =['turn-left', 'turn-right', 'smile']

Public properties

• public static $match = 0.5
• public static $spread = 0.6
• public static $distinct = 0.001
• public static $minPrints = 3
• public static $maxPrints = 12
• public static $count = 2
• public static $ttl = 60
• public static $clock = null

Methods

• FaceLogin::challenge()
• FaceLogin::consume()
• FaceLogin::verify()
• FaceLogin::checkPrints()
• FaceLogin::match()
• FaceLogin::enrolledElsewhere()
• FaceLogin::printHash()
• FaceLogin::descriptor()
• FaceLogin::distance()

FaceLogin::challenge()

public static function challenge($username = null, $count = null, $ttl = null)

Issues a new challenge and keeps it in the session (it replaces any previous one)

Parameters

• $username string|null, default null: the account the check is for (null: 1:N login)
• $count int|null, default null: number of challenges (1 to 3, default self::$count)
• $ttl, default null

Returns array: ['nonce' => string, 'challenges' => [...], 'expires_in' => seconds]

Source: framework/core/FaceLogin.php:55

FaceLogin::consume()

public static function consume($nonce, $username = null)

Takes the challenge out of the session: a nonce can be used once, even when the check then fails

Parameters

• $nonce
• $username, default null

Returns array: the challenge

• @throws FaceLoginException (401) when there is no challenge, the nonce differs, it expired or is for another account

Source: framework/core/FaceLogin.php:81

FaceLogin::verify()

public static function verify($response, $username = null)

Consumes the nonce and checks the liveness result and the prints of a response

Parameters

• $response array: ['nonce' => .., 'liveness' => ['passed' => true, 'challenges' => 'name' =>, 'passed' =>], .., 'prints' => 128 numbers] or ['descriptor' => [128 numbers, ..]]
• $username, default null

Returns array: the prints: [[128 floats], ..]

• @throws FaceLoginException 401 (nonce) or 422 (liveness, prints)

Source: framework/core/FaceLogin.php:105

FaceLogin::checkPrints()

public static function checkPrints($prints)

Validates the prints of one check: count, format, same face, not identical

Parameters

• $prints

Returns array: [[128 floats], ..]

Source: framework/core/FaceLogin.php:128

FaceLogin::match()

public static function match($prints, $enrolled)

Finds the account that matches every print

Parameters

• $prints array: [[128 floats], ..] from verify()
• $enrolled array: 'user' => id, 'descriptor' => [128 floats, ..]

Returns array|null: ['user' => id, 'distance' => mean distance] or null when no account matches

Source: framework/core/FaceLogin.php:162

FaceLogin::enrolledElsewhere()

public static function enrolledElsewhere($prints, $enrolled, $user = null)

Prints of a new enrolment must not match another account (one person, one account)

Parameters

• $prints
• $enrolled
• $user, default null

Returns mixed: the id of the account that already has this face, or null

Source: framework/core/FaceLogin.php:188

FaceLogin::printHash()

public static function printHash($descriptor)

Hash of a print to remember the prints already accepted (an exact replay with a new nonce is refused)

Parameters

• $descriptor

Source: framework/core/FaceLogin.php:203

FaceLogin::descriptor()

public static function descriptor($d)

128 finite numbers as floats, or null

Parameters

• $d

Source: framework/core/FaceLogin.php:211

FaceLogin::distance()

public static function distance($a, $b)

No doc comment.

Parameters

• $a
• $b

Source: framework/core/FaceLogin.php:224

class Caligrafy\FaceLoginException

namespace Caligrafy;

class FaceLoginException extends \Exception

Source: framework/core/FaceLogin.php:28

No doc comment on this class.

No public methods.