IdentityStore.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 - IdentityStore
 *
 * @package Italix\Auth
 */

declare(strict_types=1);

namespace Italix\Auth;

/**
 * Where identities come from.
 *
 * The library ships **no table**. Reference data enters by interface (house
 * rule 4), and an authentication library that dictates a schema is one that
 * cannot be adopted by an application which already has users — which is every
 * application that would want it.
 *
 * A typical implementation is a dozen lines over whatever user table already
 * exists, and whether an application's two areas are two stores or one table
 * with a `role` column is its decision, invisible here.
 */
interface IdentityStore
{
    /**
     * Find by the login identifier, or null.
     *
     * **Must not** distinguish "no such account" from "account disabled" by
     * returning null for the second: an identity that exists but cannot sign in
     * should come back with `is_active()` false, so the caller can decide what
     * to reveal. Collapsing the two here removes that choice.
     */
    public function find_by_login(string $login_c): ?Identity;

    public function find_by_id(int $user_id): ?Identity;

    /**
     * Record a successful sign-in. Called after the password matched and the
     * account was found active.
     *
     * A no-op implementation is fine; the hook exists because "last seen" is
     * the cheapest useful audit trail there is.
     */
    public function touch_login(int $user_id, string $ip_c): void;

    /**
     * Replace a stored hash, after `Hasher::needs_rehash()` said so.
     *
     * A no-op implementation is fine too — it means the application has decided
     * not to upgrade hashes opportunistically, which is a legitimate if
     * unambitious choice.
     */
    public function store_password_hash(int $user_id, string $hash_c): void;
}