<?php

declare(strict_types=1);

namespace App\Framework\Vault;

use App\Framework\Vault\Exceptions\VaultException;
use App\Framework\Vault\Exceptions\VaultKeyNotFoundException;
use App\Framework\Vault\ValueObjects\SecretKey;
use App\Framework\Vault\ValueObjects\SecretValue;
use App\Framework\Vault\ValueObjects\VaultMetadata;

/**
 * Vault Interface - Secure Secrets Storage
 *
 * All implementations MUST:
 * - Encrypt secrets at rest
 * - Audit all access (read/write/delete)
 * - Provide transactional safety
 * - Support key rotation
 */
interface Vault
{
    /**
     * Get secret value
     *
     * @throws VaultKeyNotFoundException wenn Secret nicht existiert
     * @throws VaultException bei Decryption oder anderen Fehlern
     */
    public function get(SecretKey $key): SecretValue;

    /**
     * Set or update secret value
     *
     * @throws VaultException bei Encryption oder Storage Fehlern
     */
    public function set(SecretKey $key, SecretValue $value): void;

    /**
     * Check if secret exists
     */
    public function has(SecretKey $key): bool;

    /**
     * Delete secret
     *
     * @throws VaultKeyNotFoundException wenn Secret nicht existiert
     */
    public function delete(SecretKey $key): void;

    /**
     * List all secret keys (nicht die Values!)
     *
     * @return array<string>
     */
    public function all(): array;

    /**
     * Get metadata for a secret
     *
     * @throws VaultKeyNotFoundException
     */
    public function getMetadata(SecretKey $key): VaultMetadata;

    /**
     * Rotate encryption key
     *
     * Re-encrypts all secrets with new key.
     * CRITICAL: This is a potentially long-running operation!
     *
     * @return int Number of secrets rotated
     */
    public function rotateEncryptionKey(string $newKey): int;
}
