vaultctl 0.1.2__tar.gz → 0.2.0__tar.gz

{vaultctl-0.1.2 → vaultctl-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vaultctl
-Version: 0.1.2
+Version: 0.2.0
 Summary: vaultctl is a command-line interface (CLI) tool designed to facilitate operations with HashiCorp Vault.
 Author-email: d4rkfella <georgi.panov@darkfellanetwork.com>
 License: MIT

{vaultctl-0.1.2 → vaultctl-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vaultctl"
-version = "0.1.2"
+version = "0.2.0"
 description = "vaultctl is a command-line interface (CLI) tool designed to facilitate operations with HashiCorp Vault."
 readme = "README.md"
 license = { text = "MIT" }

{vaultctl-0.1.2 → vaultctl-0.2.0}/src/vaultctl/commands/backup_raft_snapshot.py

@@ -6,7 +6,7 @@ import io
 import tarfile
 from enum import Enum
 from pathlib import Path
-from typing import Annotated, cast
+from typing import Annotated
 
 import hvac
 import typer
@@ -20,18 +20,22 @@ from vaultctl.options import (
     AwsProfileOption,
     AwsRegionOption,
     AwsSecretAccessKeyOption,
+    BackupDestinationOption,
     CACertOption,
     CAPathOption,
     K8sMountPointOption,
     K8sRoleOption,
-    OutputFileOption,
-    S3BucketNameOption,
-    S3KeyPrefixOption,
     SkipVerifyOption,
     TimeoutOption,
     TokenOption,
 )
-from vaultctl.utils import handle_s3_authentication, handle_vault_authentication, logger
+from vaultctl.utils import (
+    handle_s3_authentication,
+    handle_vault_authentication,
+    is_s3_uri,
+    logger,
+    parse_s3_uri,
+)
 
 app = typer.Typer()
 
@@ -87,7 +91,7 @@ def verify_internal_checksums(snapshot_data: bytes) -> None:
                 files_in_tar[member.name] = content
 
             if sha_sums_content is None:
-                msg = "SHA256SUMS file not found in the Raft snapshot archive."
+                msg = "SHA256SUMS file not found in the snapshot archive."
                 raise ValueError(
                     msg,
                 )
@@ -119,33 +123,34 @@ def verify_internal_checksums(snapshot_data: bytes) -> None:
 
 
 @app.command(
-    help="Executes a complete workflow for obtaining a HashiCorp Vault Raft snapshot from a cluster, verifying its integrity, and uploading it securely to S3 storage. Provides flexible authentication options for both HashiCorp Vault and S3 APIs.",
+    help="Executes a complete workflow for obtaining a HashiCorp Vault Raft snapshot, verifying its integrity, and saving it to a local path or S3 URI. Provides flexible authentication options for both HashiCorp Vault and S3 APIs.",
 )
 def backup_raft_snapshot(  # noqa: PLR0913
     address: AddressOption,
-    s3_bucket_name: S3BucketNameOption = None,
-    output_file: OutputFileOption = None,
+    destination: BackupDestinationOption = None,
     k8s_role: K8sRoleOption = None,
     k8s_mount_point: K8sMountPointOption = "kubernetes",
-    token: TokenOption = None,
-    ca_cert: CACertOption = None,
-    ca_path: CAPathOption = None,
+    k8s_sa_token_path: Path = Path(
+        "/var/run/secrets/kubernetes.io/serviceaccount/token",
+    ),
     aws_profile: AwsProfileOption = None,
     aws_access_key_id: AwsAccessKeyIdOption = None,
     aws_secret_access_key: AwsSecretAccessKeyOption = None,
     aws_endpoint_url: AwsEndpointUrlOption = None,
     aws_region: AwsRegionOption = "us-east-1",
-    s3_key_prefix: S3KeyPrefixOption = "",
     s3_checksum_algorithm: Annotated[
         S3ChecksumAlgorithm,
         typer.Option(help="The algorithm to use for s3 transport checksum."),
     ] = S3ChecksumAlgorithm.CRC64NVME,
+    token: TokenOption = None,
+    ca_cert: CACertOption = None,
+    ca_path: CAPathOption = None,
     timeout: TimeoutOption = 30,
     *,
     skip_verify: SkipVerifyOption = False,
 ) -> None:
-    if not s3_bucket_name and not output_file:
-        msg = "Either --s3-bucket-name or --output-file is required"
+    if not destination:
+        msg = "--to is required"
         raise typer.BadParameter(msg)
 
     vault_client = handle_vault_authentication(
@@ -163,6 +168,7 @@ def backup_raft_snapshot(  # noqa: PLR0913
         token=token,
         k8s_role=k8s_role,
         k8s_mount_point=k8s_mount_point,
+        k8s_token_path=k8s_sa_token_path,
     )
 
     if vault_client.sys.is_sealed():
@@ -171,12 +177,12 @@ def backup_raft_snapshot(  # noqa: PLR0913
 
     logger.info("Starting backup...")
 
-    logger.info("Requesting raft snapshot...")
+    logger.info("Requesting snapshot...")
     response: Response = vault_client.sys.take_raft_snapshot()
 
     if response.status_code != 200:  # noqa: PLR2004
         logger.error(
-            "Raft snapshot request failed with status code %s.",
+            "Snapshot request failed with status code %s.",
             response.status_code,
         )
         logger.debug("Response body: %s", response.text)
@@ -184,53 +190,52 @@ def backup_raft_snapshot(  # noqa: PLR0913
 
     snapshot_data: bytes = response.content
 
-    logger.info("Raft snapshot retrieved.")
+    logger.info("Snapshot retrieved.")
 
     try:
         verify_internal_checksums(snapshot_data)
-    except (tarfile.TarError, ValueError):
-        logger.exception("Verifying raft snapshot integrity")
+    except tarfile.TarError, ValueError:
+        logger.exception("Verifying snapshot integrity")
         raise typer.Exit(1) from None
 
-    if output_file:
-        output_path = Path(output_file)
+    if not is_s3_uri(destination):
+        output_path = Path(destination)
         if output_path.is_dir():
             timestamp = datetime.datetime.now(tz=datetime.UTC).strftime("%Y%m%d_%H%M%S")
             output_path = output_path / f"vault-snapshot-{timestamp}.snap"
         output_path.write_bytes(snapshot_data)
         logger.info("Snapshot written to %s", output_path)
-        logger.info("Backup completed")
-        return
-
-    s3_bucket_name = cast("str", s3_bucket_name)
-
-    s3_client = handle_s3_authentication(
-        bucket_name=s3_bucket_name,
-        aws_access_key_id=aws_access_key_id,
-        aws_secret_access_key=aws_secret_access_key,
-        aws_region=aws_region,
-        aws_profile=aws_profile,
-        endpoint_url=aws_endpoint_url,
-    )
-
-    timestamp = datetime.datetime.now(tz=datetime.UTC).strftime("%Y%m%d_%H%M%S")
-    snapshot_name = f"vault-snapshot-{timestamp}.snap"
-    s3_key = f"{s3_key_prefix}{snapshot_name}"
+    else:
+        s3_bucket, s3_key = parse_s3_uri(destination)
 
-    try:
-        logger.info("Uploading raft snapshot to %s/%s...", s3_bucket_name, s3_key)
-        s3_client.upload_fileobj(
-            io.BytesIO(snapshot_data),
-            s3_bucket_name,
-            s3_key,
-            ExtraArgs={
-                "ContentType": "application/gzip",
-                "ChecksumAlgorithm": s3_checksum_algorithm.value,
-            },
+        if s3_key.endswith("/"):
+            timestamp = datetime.datetime.now(tz=datetime.UTC).strftime("%Y%m%d_%H%M%S")
+            snapshot_name = f"vault-snapshot-{timestamp}.snap"
+            s3_key = f"{s3_key}{snapshot_name}"
+
+        s3_client = handle_s3_authentication(
+            bucket_name=s3_bucket,
+            aws_access_key_id=aws_access_key_id,
+            aws_secret_access_key=aws_secret_access_key,
+            aws_region=aws_region,
+            aws_profile=aws_profile,
+            endpoint_url=aws_endpoint_url,
         )
-    except ClientError:
-        logger.exception("Uploading raft snapshot")
-        raise typer.Exit(1) from None
 
-    logger.info("Raft snapshot uploaded.")
-    logger.info("Backup completed")
+        try:
+            logger.info("Uploading snapshot to %s/%s...", s3_bucket, s3_key)
+            s3_client.upload_fileobj(
+                io.BytesIO(snapshot_data),
+                s3_bucket,
+                s3_key,
+                ExtraArgs={
+                    "ContentType": "application/gzip",
+                    "ChecksumAlgorithm": s3_checksum_algorithm.value,
+                },
+            )
+            logger.info("Snapshot uploaded.")
+        except ClientError:
+            logger.exception("Uploading snapshot")
+            raise typer.Exit(1) from None
+
+    logger.info("Backup completed successfully.")

{vaultctl-0.1.2 → vaultctl-0.2.0}/src/vaultctl/commands/bootstrap.py

@@ -14,12 +14,8 @@ from vaultctl.options import (
     AwsSecretAccessKeyOption,
     CACertOption,
     CAPathOption,
-    S3BucketNameOption,
-    S3KeyPrefixOption,
+    RestoreSourceOption,
     SkipVerifyOption,
-    SnapshotFileOption,
-    SnapshotNameOption,
-    SnapshotNameRegexOption,
     TimeoutOption,
 )
 
@@ -29,20 +25,15 @@ AUTO_UNSEAL_MAX_ATTEMPT = 10
 
 
 @app.command(
-    help="Init, unseal and force restore a hashicorp vault cluster from S3 storage using raft snapshots",
+    help="Init, unseal and force restore a HashiCorp Vault cluster from a Raft snapshot (S3 or local).",
 )
 def bootstrap(  # noqa: PLR0913
-    ctx: typer.Context,
     address: AddressOption,
-    s3_bucket_name: S3BucketNameOption = None,
-    snapshot_file: SnapshotFileOption = None,
+    source: RestoreSourceOption = None,
     *,
     ca_cert: CACertOption = None,
     ca_path: CAPathOption = None,
     skip_verify: SkipVerifyOption = False,
-    s3_key_prefix: S3KeyPrefixOption = "",
-    filename: SnapshotNameOption = None,
-    filename_regex: SnapshotNameRegexOption = None,
     aws_profile: AwsProfileOption = None,
     aws_access_key_id: AwsAccessKeyIdOption = None,
     aws_secret_access_key: AwsSecretAccessKeyOption = None,
@@ -50,8 +41,8 @@ def bootstrap(  # noqa: PLR0913
     aws_region: AwsRegionOption = "us-east-1",
     timeout: TimeoutOption = 30,
 ) -> None:
-    if not s3_bucket_name and not snapshot_file:
-        msg = "Either --s3-bucket-name or --snapshot-file is required"
+    if not source:
+        msg = "--from is required"
         raise typer.BadParameter(msg)
     client = hvac.Client(
         url=address,
@@ -102,16 +93,11 @@ def bootstrap(  # noqa: PLR0913
         typer.echo("Vault is unsealed and ready. Starting restore...")
 
         restore_raft_snapshot(
-            ctx=ctx,
             address=address,
+            source=source,
             ca_cert=ca_cert,
             ca_path=ca_path,
             skip_verify=skip_verify,
-            s3_bucket_name=s3_bucket_name,
-            snapshot_file=snapshot_file,
-            s3_key_prefix=s3_key_prefix,
-            filename=filename,
-            filename_regex=filename_regex,
             aws_profile=aws_profile,
             aws_access_key_id=aws_access_key_id,
             aws_secret_access_key=aws_secret_access_key,

{vaultctl-0.1.2 → vaultctl-0.2.0}/src/vaultctl/commands/login.py

@@ -69,10 +69,6 @@ def login(  # noqa: C901, PLR0913
     password = kv.get("password")
     token = kv.get("token")
 
-    if method == "userpass" and not username:
-        msg = "'username' must be specified"
-        raise typer.BadParameter(msg)
-
     try:
         if method == "token":
             if not token:
@@ -86,6 +82,8 @@ def login(  # noqa: C901, PLR0913
             token_info = lookup["data"]
 
         elif method == "userpass":
+            if not username:
+                username = typer.prompt("Username", type=str)
             if not password:
                 password = typer.prompt(
                     "Password (will be hidden)",

vaultctl-0.2.0/src/vaultctl/commands/restore_raft_snapshot.py

@@ -0,0 +1,133 @@
+from pathlib import Path
+
+import botocore.exceptions
+import hvac
+import typer
+from hvac.api.system_backend import Raft
+from hvac.exceptions import InvalidRequest, VaultError
+
+from vaultctl.options import (
+    AddressOption,
+    AwsAccessKeyIdOption,
+    AwsEndpointUrlOption,
+    AwsProfileOption,
+    AwsRegionOption,
+    AwsSecretAccessKeyOption,
+    CACertOption,
+    CAPathOption,
+    K8sMountPointOption,
+    K8sRoleOption,
+    RestoreSourceOption,
+    SkipVerifyOption,
+    SnapshotForceRestoreOption,
+    TimeoutOption,
+    TokenOption,
+)
+from vaultctl.utils import (
+    handle_s3_authentication,
+    handle_vault_authentication,
+    is_s3_uri,
+    logger,
+    parse_s3_uri,
+)
+
+app = typer.Typer()
+
+
+@app.command(
+    help="Restore a HashiCorp Vault cluster from a Raft snapshot (S3 or local).",
+)
+def restore_raft_snapshot(  # noqa: PLR0913
+    address: AddressOption,
+    source: RestoreSourceOption = None,
+    k8s_role: K8sRoleOption = None,
+    k8s_mount_point: K8sMountPointOption = "kubernetes",
+    aws_profile: AwsProfileOption = None,
+    aws_access_key_id: AwsAccessKeyIdOption = None,
+    aws_secret_access_key: AwsSecretAccessKeyOption = None,
+    aws_endpoint_url: AwsEndpointUrlOption = None,
+    aws_region: AwsRegionOption = "us-east-1",
+    token: TokenOption = None,
+    ca_cert: CACertOption = None,
+    ca_path: CAPathOption = None,
+    timeout: TimeoutOption = 30,
+    *,
+    force_restore: SnapshotForceRestoreOption = False,
+    skip_verify: SkipVerifyOption = False,
+) -> None:
+    if not source:
+        msg = "--from is required"
+        raise typer.BadParameter(msg)
+
+    vault_client = handle_vault_authentication(
+        hvac.Client(
+            url=address,
+            timeout=timeout,
+            verify=(
+                str(ca_cert)
+                if ca_cert
+                else str(ca_path)
+                if ca_path
+                else (not skip_verify)
+            ),
+        ),
+        token=token,
+        k8s_role=k8s_role,
+        k8s_mount_point=k8s_mount_point,
+    )
+
+    if vault_client.sys.is_sealed():
+        logger.error("Vault is sealed. Cannot proceed.")
+        raise typer.Exit(code=1)
+
+    if not is_s3_uri(source):
+        snapshot_path = Path(source)
+        if snapshot_path.is_dir():
+            msg = "--from must be a file path, not a directory"
+            raise typer.BadParameter(msg)
+        logger.info("Reading snapshot from %s...", snapshot_path)
+        snapshot_data = snapshot_path.read_bytes()
+    else:
+        s3_bucket, s3_key = parse_s3_uri(source)
+        if not s3_key or s3_key.endswith("/"):
+            msg = "S3 URI must point to a specific object, not a prefix"
+            raise typer.BadParameter(msg)
+
+        logger.info("Getting snapshot from S3: %s...", s3_key)
+        s3_client = handle_s3_authentication(
+            bucket_name=s3_bucket,
+            aws_access_key_id=aws_access_key_id,
+            aws_secret_access_key=aws_secret_access_key,
+            aws_region=aws_region,
+            aws_profile=aws_profile,
+            endpoint_url=aws_endpoint_url,
+        )
+
+        try:
+            download_response = s3_client.get_object(Bucket=s3_bucket, Key=s3_key)
+            snapshot_data = download_response["Body"].read()
+        except botocore.exceptions.ClientError:
+            logger.exception("Getting snapshot from S3")
+            raise typer.Exit(1) from None
+
+        logger.info("Snapshot downloaded successfully.")
+
+    raft = Raft(adapter=vault_client.adapter)
+
+    logger.info("Restoring snapshot...")
+
+    if force_restore:
+        logger.warning("Force restore is ENABLED !")
+        try:
+            raft.force_restore_raft_snapshot(snapshot_data)
+        except VaultError, InvalidRequest:
+            logger.exception("Restoring snapshot")
+            raise typer.Exit(1) from None
+    else:
+        try:
+            raft.restore_raft_snapshot(snapshot_data)
+        except VaultError, InvalidRequest:
+            logger.exception("Restoring snapshot")
+            raise typer.Exit(1) from None
+
+    logger.info("Snapshot restored successfully!")

{vaultctl-0.1.2 → vaultctl-0.2.0}/src/vaultctl/options.py

@@ -1,10 +1,9 @@
-import re
 from pathlib import Path
 from typing import Annotated
 
 from typer import Option
 
-from .utils import parse_regex, validate_address, validate_s3_key_prefix
+from .utils import validate_address
 
 AwsEndpointUrlOption = Annotated[
     str | None,
@@ -37,21 +36,6 @@ AwsRegionOption = Annotated[
     Option(envvar="AWS_REGION", help="AWS Region (e.g., us-east-1)."),
 ]
 
-S3BucketNameOption = Annotated[
-    str | None,
-    Option(
-        envvar="S3_BUCKET_NAME",
-        help="Storage bucket where snapshots are stored",
-    ),
-]
-
-S3KeyPrefixOption = Annotated[
-    str,
-    Option(
-        callback=validate_s3_key_prefix,
-    ),
-]
-
 AddressOption = Annotated[
     str,
     Option(
@@ -136,18 +120,34 @@ K8sMountPointOption = Annotated[
     Option(envvar="VAULT_K8S_MOUNT_POINT", help="Vault K8s auth backend mount path."),
 ]
 
-SnapshotNameOption = Annotated[
+K8sSaTokenPathOption = Annotated[
+    Path,
+    Option(
+        envvar="VAULT_K8S_SA_TOKEN_PATH",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        writable=False,
+        resolve_path=True,
+        path_type=str,
+        help="Path to the Kubernetes service account token file used for Vault Kubernetes authentication. The default is /var/run/secrets/kubernetes.io/serviceaccount/token. This can also be specified via the VAULT_K8S_SA_TOKEN_PATH environment variable.",
+    ),
+]
+
+RestoreSourceOption = Annotated[
     str | None,
     Option(
-        help="Name of the Vault snapshot to restore.",
+        "--from",
+        help="Source path. Local file path or S3 URI (e.g., s3://bucket/key).",
     ),
 ]
 
-SnapshotNameRegexOption = Annotated[
-    re.Pattern | None,
+BackupDestinationOption = Annotated[
+    str | None,
     Option(
-        parser=parse_regex,
-        help="Regex pattern to match Vault snapshot names.",
+        "--to",
+        help="Destination path. Local file/directory or S3 URI (e.g., s3://bucket/prefix/).",
     ),
 ]
 
@@ -170,31 +170,3 @@ TimeoutOption = Annotated[
         help="HTTP request timeout in seconds for Vault API calls.",
     ),
 ]
-
-OutputFileOption = Annotated[
-    Path | None,
-    Option(
-        "--output-file",
-        "-o",
-        help="Path to write the snapshot to locally. If a directory, a timestamped filename is generated.",
-        dir_okay=True,
-        writable=True,
-        resolve_path=True,
-        path_type=str,
-    ),
-]
-
-SnapshotFileOption = Annotated[
-    Path | None,
-    Option(
-        "--snapshot-file",
-        "-f",
-        help="Path to a local snapshot file to restore.",
-        exists=True,
-        file_okay=True,
-        dir_okay=False,
-        readable=True,
-        resolve_path=True,
-        path_type=str,
-    ),
-]

{vaultctl-0.1.2 → vaultctl-0.2.0}/src/vaultctl/utils.py

@@ -38,34 +38,6 @@ def parse_regex(value: str) -> re.Pattern:
         raise typer.BadParameter(msg) from e
 
 
-def validate_s3_key_prefix(
-    value: str,
-) -> str:
-    """Validate S3 key prefix format."""
-    if not value:
-        return ""
-    if value.startswith("/"):
-        msg = "S3 key prefix must not start with '/'. Example: backups/2026/"
-        raise typer.BadParameter(
-            msg,
-        )
-
-    pattern = re.compile(r"^[A-Za-z0-9/_\-.]+$")
-    if not pattern.match(value):
-        msg = (
-            "S3 key prefix contains invalid characters. "
-            "Allowed: letters, numbers, '/', '-', '_', '.'"
-        )
-        raise typer.BadParameter(
-            msg,
-        )
-
-    if not value.endswith("/"):
-        value = value + "/"
-
-    return value
-
-
 def validate_address(
     ctx: typer.Context,  # noqa: ARG001
     param: object,  # noqa: ARG001
@@ -81,6 +53,19 @@ def validate_address(
     return value
 
 
+def is_s3_uri(path: str) -> bool:
+    return path.startswith("s3://")
+
+
+def parse_s3_uri(path: str) -> tuple[str, str]:
+    if not path.startswith("s3://"):
+        msg = f"Invalid S3 URI: {path}"
+        raise ValueError(msg)
+    rest = path[5:]
+    bucket, _sep, key = rest.partition("/")
+    return bucket, key
+
+
 def handle_vault_authentication(
     client: hvac.Client,
     token: str | None,
@@ -91,19 +76,27 @@ def handle_vault_authentication(
     token_filepath = Path.home() / ".vault-token"
 
     if token:
+        logger.info("Authenticating to Vault using provided token...")
         client.token = token
         return client
 
     if token_filepath.exists() and (saved_token := token_filepath.read_text().strip()):
+        logger.info(
+            "Authenticating to Vault using existing token from %s...",
+            token_filepath,
+        )
         client.token = saved_token
         return client
 
     if k8s_role:
-        logger.info("Attempting Kubernetes Auth for role: %s...", k8s_role)
+        logger.info(
+            "Authenticating to Vault using Kubernetes Auth method with role: %s...",
+            k8s_role,
+        )
 
         if not k8s_token_path.exists():
             logger.error(
-                "K8s token file not found at %s.",
+                "Token file not found at %s.",
                 k8s_token_path,
             )
             raise typer.Exit(code=1)
@@ -122,13 +115,14 @@ def handle_vault_authentication(
         else:
             return client
 
-    logger.error("Vault client authentication failed.")
+    logger.error(
+        "Vault authentication failed. No valid authentication method found. Please provide a token, use the 'login' command, or configure Kubernetes authentication by providing the role and mount point to use.",
+    )
     raise typer.Exit(code=1)
 
 
 def handle_s3_authentication(  # noqa: PLR0913
     bucket_name: str,
-    *,
     aws_access_key_id: str | None = None,
     aws_secret_access_key: str | None = None,
     aws_session_token: str | None = None,

{vaultctl-0.1.2 → vaultctl-0.2.0}/uv.lock

@@ -411,7 +411,7 @@ wheels = [
 
 [[package]]
 name = "vaultctl"
-version = "0.1.0"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "boto3" },

vaultctl-0.1.2/src/vaultctl/commands/restore_raft_snapshot.py

@@ -1,210 +0,0 @@
-from datetime import datetime
-from pathlib import Path
-from typing import TYPE_CHECKING, cast
-
-import botocore.exceptions
-import hvac
-import typer
-from dateutil.parser import parse as parse_datetime
-from hvac.api.system_backend import Raft
-from hvac.exceptions import InvalidRequest, VaultError
-
-from vaultctl.options import (
-    AddressOption,
-    AwsAccessKeyIdOption,
-    AwsEndpointUrlOption,
-    AwsProfileOption,
-    AwsRegionOption,
-    AwsSecretAccessKeyOption,
-    CACertOption,
-    CAPathOption,
-    K8sMountPointOption,
-    K8sRoleOption,
-    S3BucketNameOption,
-    S3KeyPrefixOption,
-    SkipVerifyOption,
-    SnapshotFileOption,
-    SnapshotForceRestoreOption,
-    SnapshotNameOption,
-    SnapshotNameRegexOption,
-    TimeoutOption,
-    TokenOption,
-)
-from vaultctl.utils import handle_s3_authentication, handle_vault_authentication, logger
-
-if TYPE_CHECKING:
-    import re
-    from collections.abc import Mapping, Sequence
-
-app = typer.Typer()
-
-
-def select_snapshot(
-    contents: Sequence[Mapping[str, object]],
-    filename_regex: re.Pattern | None,
-) -> str:
-    if filename_regex:
-        valid_objects = []
-
-        for o in contents:
-            key = o.get("Key")
-            if not isinstance(key, str):
-                continue
-
-            match = filename_regex.match(key)
-            if not match:
-                continue
-
-            ts_str = match.group(1)
-            try:
-                ts = parse_datetime(ts_str)
-                valid_objects.append({"Key": key, "Timestamp": ts})
-            except ValueError:
-                continue
-
-        if not valid_objects:
-            msg = "No valid snapshots found matching the filename regex with parseable timestamp"
-            raise ValueError(
-                msg,
-            )
-
-        latest_obj = max(valid_objects, key=lambda o: cast("datetime", o["Timestamp"]))
-        return cast("str", latest_obj["Key"])
-
-    valid_objects = [
-        o
-        for o in contents
-        if isinstance(o.get("Key"), str) and isinstance(o.get("LastModified"), datetime)
-    ]
-    if not valid_objects:
-        msg = "No valid snapshots with LastModified found"
-        raise RuntimeError(msg)
-
-    latest_obj = max(valid_objects, key=lambda o: cast("datetime", o["LastModified"]))
-    return cast("str", latest_obj["Key"])
-
-
-@app.command(help="Restore a HashiCorp Vault cluster from an S3 Raft snapshot.")
-def restore_raft_snapshot(  # noqa: C901, PLR0912, PLR0913, PLR0915
-    address: AddressOption,
-    s3_bucket_name: S3BucketNameOption = None,
-    snapshot_file: SnapshotFileOption = None,
-    k8s_role: K8sRoleOption = None,
-    k8s_mount_point: K8sMountPointOption = "kubernetes",
-    filename: SnapshotNameOption = None,
-    filename_regex: SnapshotNameRegexOption = None,
-    aws_profile: AwsProfileOption = None,
-    aws_access_key_id: AwsAccessKeyIdOption = None,
-    aws_secret_access_key: AwsSecretAccessKeyOption = None,
-    aws_endpoint_url: AwsEndpointUrlOption = None,
-    aws_region: AwsRegionOption = "us-east-1",
-    s3_key_prefix: S3KeyPrefixOption = "",
-    token: TokenOption = None,
-    ca_cert: CACertOption = None,
-    ca_path: CAPathOption = None,
-    timeout: TimeoutOption = 30,
-    *,
-    force_restore: SnapshotForceRestoreOption = False,
-    skip_verify: SkipVerifyOption = False,
-) -> None:
-    if not s3_bucket_name and not snapshot_file:
-        msg = "Either --s3-bucket-name or --snapshot-file is required"
-        raise typer.BadParameter(msg)
-
-    vault_client = handle_vault_authentication(
-        hvac.Client(
-            url=address,
-            timeout=timeout,
-            verify=(
-                str(ca_cert)
-                if ca_cert
-                else str(ca_path)
-                if ca_path
-                else (not skip_verify)
-            ),
-        ),
-        token=token,
-        k8s_role=k8s_role,
-        k8s_mount_point=k8s_mount_point,
-    )
-
-    if vault_client.sys.is_sealed():
-        logger.error("Vault is sealed. Cannot proceed.")
-        raise typer.Exit(code=1)
-
-    if snapshot_file:
-        logger.info("Reading snapshot from %s...", snapshot_file)
-        snapshot_data = Path(snapshot_file).read_bytes()
-    else:
-        s3_bucket_name = cast("str", s3_bucket_name)
-        s3_client = handle_s3_authentication(
-            bucket_name=s3_bucket_name,
-            aws_access_key_id=aws_access_key_id,
-            aws_secret_access_key=aws_secret_access_key,
-            aws_region=aws_region,
-            aws_profile=aws_profile,
-            endpoint_url=aws_endpoint_url,
-        )
-
-        if filename:
-            s3_key = f"{s3_key_prefix}{filename}"
-            logger.info("Using snapshot: %s", s3_key)
-        else:
-            logger.info("Selecting latest snapshot from S3...")
-
-            try:
-                list_response = s3_client.list_objects_v2(
-                    Bucket=s3_bucket_name,
-                    Prefix=s3_key_prefix,
-                )
-            except botocore.exceptions.ClientError:
-                logger.exception("Listing S3 bucket contents")
-                raise typer.Exit(1) from None
-
-            if list_response.get("KeyCount", 0) == 0:
-                logger.error(
-                    "No snapshots found in bucket '%s' with prefix '%s'.",
-                    s3_bucket_name,
-                    s3_key_prefix,
-                )
-                raise typer.Exit(1)
-
-            contents = list_response.get("Contents", [])
-            try:
-                s3_key = select_snapshot(contents, filename_regex)
-            except (ValueError, RuntimeError):
-                logger.exception("Selecting snapshot")
-                raise typer.Exit(1) from None
-
-            logger.info("Selected snapshot: %s", s3_key)
-
-        logger.info("Downloading snapshot from S3: %s...", s3_key)
-
-        try:
-            download_response = s3_client.get_object(Bucket=s3_bucket_name, Key=s3_key)
-            snapshot_data = download_response["Body"].read()
-        except botocore.exceptions.ClientError:
-            logger.exception("Downloading snapshot")
-            raise typer.Exit(1) from None
-
-        logger.info("Snapshot downloaded.")
-
-    raft = Raft(adapter=vault_client.adapter)
-
-    if force_restore:
-        logger.warning("Restoring snapshot with force...")
-        try:
-            raft.force_restore_raft_snapshot(snapshot_data)
-        except (VaultError, InvalidRequest):
-            logger.exception("Restoring snapshot")
-            raise typer.Exit(1) from None
-    else:
-        logger.info("Restoring snapshot...")
-        try:
-            raft.restore_raft_snapshot(snapshot_data)
-        except (VaultError, InvalidRequest):
-            logger.exception("Restoring snapshot")
-            raise typer.Exit(1) from None
-
-    logger.info("Snapshot restored.")
-    logger.info("Restore completed")