wasl/Backend/app/Models/User.php

<?php

namespace App\Models;

use App\Casts\Encryptable;
use App\Enums\UserStatus;
use App\Models\Traits\HasUuid;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\SoftDeletes;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Spatie\Permission\Traits\HasRoles;

/**
 * @property string $uuid
 * @property string $full_name
 * @property string $phone_number       AES-256 encrypted — NEVER log/expose raw
 * @property string $phone_hash         SHA-256 for lookup/search
 * @property string|null $email
 * @property string|null $national_id   AES-256 encrypted
 * @property string|null $national_id_hash
 * @property string|null $password      bcrypt/argon2id
 * @property string|null $pin_hash      argon2id for 6-digit PIN
 * @property string $status             UserStatus enum value
 * @property int $kyc_level            0=none, 1=phone, 2=id, 3=full
 * @property string $language
 * @property string $country_code
 * @property int $failed_login_count
 * @property \Illuminate\Support\Carbon|null $locked_until
 * @property \Illuminate\Support\Carbon|null $last_login_at
 * @property string|null $last_login_ip
 * @property \Illuminate\Support\Carbon|null $phone_verified_at
 * @property \Illuminate\Support\Carbon|null $email_verified_at
 */
class User extends Authenticatable
{
    use HasFactory;
    use Notifiable;
    use HasRoles;
    use SoftDeletes;
    use HasUuid;

    protected $table = 'users';

    // Guarded — use $fillable explicitly
    protected $guarded = ['id', 'uuid', 'created_at', 'updated_at', 'deleted_at'];

    protected $fillable = [
        'full_name',
        'phone_number',
        'phone_hash',
        'email',
        'national_id',
        'national_id_hash',
        'password',
        'pin_hash',
        'status',
        'kyc_level',
        'language',
        'country_code',
        'failed_login_count',
        'locked_until',
        'last_login_at',
        'last_login_ip',
        'phone_verified_at',
        'email_verified_at',
    ];

    // ── Encryption casts ── NEVER log or expose these fields raw ──
    protected $casts = [
        'phone_number'   => Encryptable::class,
        'national_id'    => Encryptable::class,
        'password'       => 'hashed',
        'pin_hash'       => 'hashed',
        'status'         => UserStatus::class,
        'kyc_level'      => 'integer',
        'failed_login_count' => 'integer',
        'locked_until'   => 'datetime',
        'last_login_at'  => 'datetime',
        'phone_verified_at' => 'datetime',
        'email_verified_at' => 'datetime',
    ];

    // ── Hide sensitive fields from API/array serialization ──
    protected $hidden = [
        'id',
        'password',
        'pin_hash',
        'phone_number',      // encrypted ciphertext
        'national_id',       // encrypted ciphertext
        'phone_hash',        // internal hash
        'national_id_hash',  // internal hash
        'failed_login_count',
        'locked_until',
        'created_at',
        'updated_at',
        'deleted_at',
    ];

    protected $visible = [
        'uuid',
        'full_name',
        'email',
        'status',
        'kyc_level',
        'language',
        'country_code',
        'phone_verified_at',
        'last_login_at',
    ];

    // ── Helper: get masked phone for display (e.g., +963 *** 456) ──
    public function maskedPhone(): ?string
    {
        $phone = $this->phone_number;
        if (!$phone || strlen($phone) < 6) {
            return null;
        }
        $len = strlen($phone);
        $maskLen = max(3, $len - 6);
        return substr($phone, 0, 3) . str_repeat('*', $maskLen) . substr($phone, -3);
    }

    // ── Relationships ──

    public function wallets()
    {
        return $this->hasMany(Wallet::class);
    }

    public function devices()
    {
        return $this->hasMany(UserDevice::class);
    }

    public function kycDocuments()
    {
        return $this->hasMany(KycDocument::class);
    }

    public function transactions()
    {
        // Transactions where user is either sender or receiver (via wallets)
        return Transaction::whereIn('debit_wallet_id', $this->wallets()->select('id'))
            ->orWhereIn('credit_wallet_id', $this->wallets()->select('id'));
    }

    // ── Status helpers ──

    public function isActive(): bool
    {
        return $this->status === UserStatus::ACTIVE;
    }

    public function canTransact(): bool
    {
        return $this->isActive() && $this->kyc_level > 0;
    }

    public function isLocked(): bool
    {
        return $this->locked_until && $this->locked_until->isFuture();
    }

    public function isPhoneVerified(): bool
    {
        return !is_null($this->phone_verified_at);
    }

    // ── Scopes ──

    public function scopeActive($query)
    {
        return $query->where('status', UserStatus::ACTIVE);
    }

    public function scopeByPhoneHash($query, string $hash)
    {
        return $query->where('phone_hash', $hash);
    }
}