/*
 * SPDX-License-Identifier: GPL-3.0-or-later
 */
package com.runicgateway.app.core.auth

/**
 * At-rest home for the opaque trusted-device token (TRUSTED_DEVICES_MFA.md). It is
 * the native analogue of the web `rg_trust` cookie: a device that holds a valid
 * token skips the TOTP step on its next login (never the password).
 *
 * Deliberately **separate** from [TokenStore] and untouched by session teardown —
 * the token must **survive logout and a dead-refresh sign-out**, because it is only
 * ever consulted at a *fresh* login (exactly the moment after the session is gone).
 * Clearing it there would make the feature a no-op. It is scoped to the username it
 * was minted for so it is never replayed for a different account on a shared device,
 * and is cleared only by an explicit untrust, a Settings → Server switch, or a
 * server-side revocation (password change/reset, TOTP disable) that renders it dead.
 *
 * Tokens are sensitive, so the production impl uses EncryptedSharedPreferences —
 * never plain prefs or logs. Kept behind an interface for an in-memory test fake.
 */
interface TrustTokenStore {
    /** The stored trust token for [username], or null if this device isn't trusted for them. */
    fun tokenFor(username: String): String?

    /** Persist [token] as the trust token for [username] (overwrites any prior one). */
    fun save(username: String, token: String)

    /** Drop the trust token — untrust-all and the Settings → Server hard reset. */
    fun clear()
}
