datahub/backend/app/Model/ApiKey.php

<?php

declare(strict_types=1);

namespace App\Model;

use Hyperf\Database\Model\Relations\BelongsTo;
use Hyperf\DbConnection\Model\Model;

/**
 * @property int $id
 * @property int $user_id
 * @property string $name
 * @property string $key_hash
 * @property string $key_prefix
 * @property \Carbon\Carbon $last_used_at
 * @property \Carbon\Carbon $expires_at
 * @property bool $enabled
 * @property \Carbon\Carbon $created_at
 */
class ApiKey extends Model
{
    protected ?string $table = 'api_keys';

    public bool $timestamps = false;

    protected array $fillable = [
        'user_id',
        'name',
        'key_hash',
        'key_prefix',
        'last_used_at',
        'expires_at',
        'enabled',
    ];

    protected array $hidden = [
        'key_hash',
    ];

    protected array $casts = [
        'id' => 'integer',
        'user_id' => 'integer',
        'enabled' => 'boolean',
        'last_used_at' => 'datetime',
        'expires_at' => 'datetime',
        'created_at' => 'datetime',
    ];

    /**
     * 所属用户
     */
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class, 'user_id');
    }

    /**
     * 生成新 API Key，返回模型和明文
     *
     * 明文仅在生成时可见，后续无法再次获取
     */
    public static function generate(int $user_id, string $name, ?string $expires_at = null): array
    {
        $plain_key = bin2hex(random_bytes(32));

        $model = static::query()->create([
            'user_id' => $user_id,
            'name' => $name,
            'key_hash' => hash('sha256', $plain_key),
            'key_prefix' => substr($plain_key, 0, 8),
            'expires_at' => $expires_at,
            'enabled' => true,
            'created_at' => \Carbon\Carbon::now(),
        ]);

        return ['api_key' => $model, 'plain_key' => $plain_key];
    }

    /**
     * 通过明文 key 查找有效的 ApiKey 记录
     */
    public static function findByPlainKey(string $plain_key): ?static
    {
        $hash = hash('sha256', $plain_key);

        return static::query()
            ->where('key_hash', $hash)
            ->where('enabled', true)
            ->where(function ($query): void {
                $query->whereNull('expires_at')
                    ->orWhere('expires_at', '>', \Carbon\Carbon::now());
            })
            ->first();
    }

    /**
     * 检查 API Key 是否有效（未过期且启用）
     */
    public function isValid(): bool
    {
        if (!$this->enabled) {
            return false;
        }

        if ($this->expires_at !== null && $this->expires_at->isPast()) {
            return false;
        }

        return true;
    }
}