Identity.php

<?php
/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
/**
 * Italix Auth - Identity
 *
 * @package Italix\Auth
 */

declare(strict_types=1);

namespace Italix\Auth;

/**
 * Whoever is asking.
 *
 * Deliberately tiny, and deliberately **not** a user record. An application's
 * user has a name, a tax code, a preferred language and forty other columns;
 * none of that is any of the framework's business. What authorization needs is
 * an id, a way to say "this account may not sign in right now", and a bag of
 * attributes a policy can consult.
 *
 * A tenant id is not on this interface for the same reason. Multi-tenancy is
 * one application's shape, not every application's — a policy reads it through
 * `attribute('tenant_id')`, which costs one method call and keeps the framework
 * free of a concept it should not know.
 */
interface Identity
{
    public function id(): int;

    /**
     * The address or username the account signs in with — for logging and for
     * the rate-limiter key, never for authorization decisions.
     */
    public function login(): string;

    /**
     * Whether the account may sign in at all: activated, not suspended, not
     * deleted. An identity that returns false is refused with `not_activated`
     * before its password is even compared.
     */
    public function is_active(): bool;

    /**
     * The stored password hash, as `password_verify()` expects it.
     */
    public function password_hash(): string;

    /**
     * Anything a policy might need. Returning null for an unknown key is
     * correct and expected — a policy that needs a missing attribute should
     * abstain, not crash.
     *
     * @param  mixed $default
     * @return mixed
     */
    public function attribute(string $key, $default = null);
}