Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

fix(s3): match AWS object operation error responses (#2432)

gakuto-cw21671c8fbb5d30
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b491491a..66e638b9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,8 @@ Versioning follows [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Fixed
+- **S3 — HEAD identifiers and Iceberg REST routing** — ordinary HEAD responses retain an existing AWS-format request ID and HostId, normalizing only a missing or legacy request ID and filling a missing HostId. Iceberg REST HEAD requests signed with the `s3` scope retain the catalog's JSON error format instead of being rewritten as S3 XML.
+- **S3 — GET/HEAD/DELETE error precedence and responses** — ordinary header-signed downloads under `AUTH=true` check the endpoint/signing region before the bucket's home region, then credentials and missing buckets, matching real AWS observations from Osaka. Authentication errors include S3 signature diagnostics, missing keys include `Key`, and these errors carry matching XML/header request identifiers. HeadObject, HeadBucket and DeleteObject check the bucket's home region first, like PUT; a DELETE sent to another regional endpoint no longer succeeds merely because it was signed for the bucket's home. HEAD returns empty error responses without a Content-Length header, and HeadBucket reports an existing bucket's region even on a denial and its ARN on success. IAM still gates existing objects and buckets, and deleting an absent key remains idempotent. Presigned and subresource requests keep their existing paths.
- **Glue — a job's own botocore loads from where the script asks** — the Spark boot shim imported `botocore` before the job script ran, so a `--py-files` deps zip that holds botocore gave the zipped copy, and a script that then swapped the zip for its extracted folder failed with `DataNotFoundError: Unable to load data for: endpoints`; the shim now patches `Session.create_client` when the script first imports `botocore.session`, and still adds `endpoint_url` only when the caller sets none.
- **Glue — Spark job scripts get `--JOB_NAME` and `--JOB_RUN_ID`** — a Spark job run passed only the job's `DefaultArguments` and the run's `Arguments`, so a script that reads `JOB_NAME` or `JOB_RUN_ID` with `getResolvedOptions` failed; both now reach the script, as on AWS. They replace a value in `DefaultArguments`, and a value in the run's `Arguments` replaces them. `pythonshell` scripts don't get them, as on AWS. `GetJobRun` still shows only the arguments the caller gave.
- **Step Functions — JSONata fields on an inline `Map`** — `Items`, `ItemSelector`, `MaxConcurrency`, `Output` and `Assign` were ignored or read as JSONPath, so the Map iterated over the whole input, iterations got literal `{% ... %}` text, a `MaxConcurrency` expression failed with `States.Runtime`, and `Assign` variables were never set; all five are now evaluated, as on AWS. `Items` that is not an array fails with `States.QueryEvaluationError`.
diff --git a/ministack/app.py b/ministack/app.py
index e5a1ffbb..8c47b99d 100644
--- a/ministack/app.py
+++ b/ministack/app.py
@@ -822,7 +822,7 @@ def _asgi_header_list(headers: dict) -> list:
return header_list
-async def _send_response(send, status, headers, body):
+async def _send_response(send, status, headers, body, *, head=False):
"""Send ASGI HTTP response."""
from ministack.core.responses import StreamingResponse
@@ -830,7 +830,7 @@ async def _send_response(send, status, headers, body):
raise TypeError("StreamingResponse requires _send_streaming_response(send, receive, ...)")
body_bytes = body if isinstance(body, bytes) else body.encode("utf-8")
- if "content-length" not in {k.lower() for k in headers}:
+ if not head and "content-length" not in {k.lower() for k in headers}:
headers["Content-Length"] = str(len(body_bytes))
await send(
{
@@ -873,7 +873,7 @@ async def _send_streaming_response(send, receive, status, headers, streaming):
pass
-async def _send_if_handled(send, response, receive=None) -> bool:
+async def _send_if_handled(send, response, receive=None, *, head=False) -> bool:
"""Send a response tuple and report whether the request was handled."""
if response is None:
return False
@@ -885,7 +885,7 @@ async def _send_if_handled(send, response, receive=None) -> bool:
raise TypeError("StreamingResponse requires the ASGI receive channel")
await _send_streaming_response(send, receive, status, headers, body)
else:
- await _send_response(send, status, headers, body)
+ await _send_response(send, status, headers, body, head=head)
return True
@@ -2389,9 +2389,10 @@ async def _handle_s3_vhost_request(host: str, path: str, method: str, headers: d
# IAM enforcement for S3 virtual-hosted requests
if AUTH:
- upload_error = _get_module("s3").validate_upload_request(method, vhost_path, headers, query_params)
- if upload_error is not None:
- return upload_error
+ object_error = (None if method in {"HEAD", "DELETE"} and access_point_region is not None else
+ _get_module("s3").validate_object_request(method, vhost_path, headers, query_params))
+ if object_error is not None:
+ return object_error
from ministack.core.iam_actions import (
_s3_action,
extract_resource_arn,
@@ -2973,9 +2974,9 @@ async def _dispatch_service_request(
return _unknown_query_error(body, request_id)
if AUTH and service == "s3":
- upload_error = _get_module("s3").validate_upload_request(method, path, headers, query_params)
- if upload_error is not None:
- return upload_error
+ object_error = _get_module("s3").validate_object_request(method, path, headers, query_params)
+ if object_error is not None:
+ return object_error
# AppSync authorizes a GraphQL request by the API's own authorization types.
appsync_graphql = service == "appsync" and method == "POST" and (
@@ -3199,10 +3200,14 @@ async def _dispatch_service_request(
{
**cors,
"x-amzn-requestid": request_id,
- "x-amz-request-id": request_id,
- "x-amz-id-2": base64.b64encode(os.urandom(48)).decode(),
}
)
+ if service == "s3":
+ resp_headers.setdefault("x-amz-request-id", request_id)
+ resp_headers.setdefault("x-amz-id-2", base64.b64encode(os.urandom(48)).decode())
+ else:
+ resp_headers["x-amz-request-id"] = request_id
+ resp_headers["x-amz-id-2"] = base64.b64encode(os.urandom(48)).decode()
return status, resp_headers, resp_body
@@ -3395,27 +3400,47 @@ async def app(scope, receive, send):
):
return
- if await _send_if_handled(
- send,
- await _handle_special_data_plane_request(
- method, path, headers, body, query_params, request_id,
- raw_path=scope["raw_path"].decode("ascii") if scope.get("raw_path") else None,
- raw_query_string=query_string,
- client_ip=(scope.get("client") or ("127.0.0.1",))[0],
- ),
- receive,
- ):
+ # Finalize ordinary S3 HEAD responses after both routing paths, including
+ # IAM denials. Presigns, access points and subresources keep their handlers.
+ head_path = None
+ # Iceberg routes are selected before S3, even when signed with scope s3.
+ if (AUTH and method == "HEAD" and not path.startswith("/iceberg")
+ and detect_service(method, path, headers, query_params) == "s3"):
+ host = headers.get("host", "")
+ bucket = _extract_s3_vhost_bucket(host)
+ candidate = f"/{bucket}{path}" if bucket else path
+ ap_match = _ACCESS_POINT_HOST_RE.match(bucket) if bucket else None
+ has_access_point = ap_match is not None and _get_module("s3").resolve_access_point_host(
+ ap_match.group("name"), ap_match.group("account"), extract_region(headers)) is not None
+ if (not _MRAP_HOST_RE.match(host.split(":")[0].strip())
+ and not (bucket and (_S3_VHOST_EXCLUDE_RE.search(host) or has_access_point
+ or bucket in _NON_S3_VHOST_NAMES))
+ and _get_module("s3").is_standard_object_request(method, candidate, headers, query_params)):
+ head_path = candidate
+
+ response = await _handle_special_data_plane_request(
+ method, path, headers, body, query_params, request_id,
+ raw_path=scope["raw_path"].decode("ascii") if scope.get("raw_path") else None,
+ raw_query_string=query_string,
+ client_ip=(scope.get("client") or ("127.0.0.1",))[0],
+ )
+ if response is not None and head_path is not None:
+ response = _get_module("s3").format_head_response(head_path, headers, response)
+ if await _send_if_handled(send, response, receive, head=head_path is not None):
return
status, resp_headers, resp_body = await _dispatch_service_request(
method, path, headers, body, query_params, request_id
)
+ if head_path is not None:
+ status, resp_headers, resp_body = _get_module("s3").format_head_response(
+ head_path, headers, (status, resp_headers, resp_body))
from ministack.core.responses import StreamingResponse
if isinstance(resp_body, StreamingResponse):
await _send_streaming_response(send, receive, status, resp_headers, resp_body)
else:
- await _send_response(send, status, resp_headers, resp_body)
+ await _send_response(send, status, resp_headers, resp_body, head=head_path is not None)
# ---------------------------------------------------------------------------
diff --git a/ministack/services/s3.py b/ministack/services/s3.py
index 4a3f7a3a..36fd057e 100644
--- a/ministack/services/s3.py
+++ b/ministack/services/s3.py
@@ -1431,8 +1431,8 @@ def _validate_bucket_name(name: str) -> bool:
return True
-def _upload_error(code: str, message: str, status: int, **fields) -> tuple:
- """Error envelope observed on real S3 PutObject (Osaka, 2026-10-16)."""
+def _object_error(code: str, message: str, status: int, **fields) -> tuple:
+ """Error envelope observed on real S3 PUT/GET/DELETE (Osaka, 2026-10-16/18/23)."""
request_id = "".join(random.choices(string.ascii_uppercase + string.digits, k=16))
host_id = base64.b64encode(os.urandom(57)).decode()
root = Element("Error")
@@ -1443,27 +1443,61 @@ def _upload_error(code: str, message: str, status: int, **fields) -> tuple:
"x-amz-id-2": host_id}, _xml_body(root)
-def validate_upload_request(method: str, path: str, headers: dict, query_params: dict) -> tuple | None:
- """Before IAM, check ordinary header-signed uploads in S3's observed order.
+def is_standard_object_request(method: str, path: str, headers: dict, query_params: dict) -> bool:
+ """Limit error precedence changes to ordinary header-signed bucket/object calls."""
+ bucket, key = _parse_bucket_key(path, headers)
+ return (method in {"PUT", "GET", "HEAD", "DELETE"} and bool(bucket) and (bool(key) or method == "HEAD")
+ and "x-amz-copy-source" not in headers and not query_params.keys() - {"x-id"}
+ and headers.get("authorization", "").startswith("AWS4-HMAC-SHA256")
+ and not bucket.endswith((_ACCESS_POINT_ALIAS_SUFFIX, _OBJECT_LAMBDA_ALIAS_SUFFIX)))
+
+
+def format_head_response(path: str, headers: dict, response: tuple) -> tuple:
+ """HEAD observations from real S3, Osaka, 2026-10-23: no error body or length.
+
+ Run after IAM as well as preflight so a HeadBucket denial exposes location,
+ without granting access. Successful HeadObject retains its object metadata.
+ """
+ bucket, key = _parse_bucket_key(path, headers)
+ status, response_headers, _ = response
+ response_headers = {k: v for k, v in response_headers.items()
+ if k.lower() != "content-length" or (key and status in {200, 206})}
+ if status == 301 or status >= 400:
+ response_headers["Content-Type"] = "application/xml"
+ # Preflight already supplies S3 IDs. Normal handlers may supply a UUID,
+ # and IAM denials may supply none: normalize only those request IDs while
+ # retaining an existing HostId and any already compatible RequestId.
+ if not re.fullmatch(r"[A-Z0-9]{16}", response_headers.get("x-amz-request-id", "")):
+ response_headers["x-amz-request-id"] = "".join(random.choices(string.ascii_uppercase + string.digits, k=16))
+ if not response_headers.get("x-amz-id-2"):
+ response_headers["x-amz-id-2"] = base64.b64encode(os.urandom(57)).decode()
+ owner = _bucket_owner_account(bucket) if _validate_bucket_name(bucket) else None
+ if not key and owner is not None:
+ record = _buckets.get_scoped(owner, None, bucket)
+ response_headers["x-amz-bucket-region"] = record.get("region") or os.environ.get("MINISTACK_REGION", "us-east-1")
+ if status == 200:
+ response_headers["x-amz-bucket-arn"] = f"arn:aws:s3:::{bucket}"
+ return status, response_headers, b""
+
+
+def validate_object_request(method: str, path: str, headers: dict, query_params: dict) -> tuple | None:
+ """Before IAM, check ordinary header-signed object calls in S3's observed order.
Called only with AUTH=true. Regional hosts distinguish the endpoint region
from the signing region. The handler still enforces the bucket's home
- region for bare local endpoints. Copy, multipart, presigned and
- bucket-subresource requests keep their existing validation paths.
+ region for bare local endpoints. GET checks the signing region before the
+ bucket's home; PUT, HEAD and DELETE check the home first. Copy, multipart, presigned and
+ subresource requests keep their existing validation paths.
"""
from ministack.core.iam_actions import _auth_failure
from ministack.core.iam_evaluator import AuthError, authenticate
from ministack.core.sigv4 import parse_header_signature
bucket, key = _parse_bucket_key(path, headers)
- if (method != "PUT" or not key or "x-amz-copy-source" in headers
- or query_params.keys() - {"x-id"}
- or not headers.get("authorization", "").startswith("AWS4-HMAC-SHA256")):
+ if not is_standard_object_request(method, path, headers, query_params):
return None
- if bucket.endswith((_ACCESS_POINT_ALIAS_SUFFIX, _OBJECT_LAMBDA_ALIAS_SUFFIX)):
- return None # The S3 handler resolves access point aliases before bucket lookup.
if not _validate_bucket_name(bucket):
- return _upload_error("InvalidBucketName", "The specified bucket is not valid.", 400, BucketName=bucket)
+ return _object_error("InvalidBucketName", "The specified bucket is not valid.", 400, BucketName=bucket)
signature = parse_header_signature(headers)
if isinstance(signature, tuple):
return None # Keep the shared malformed-signature handling.
@@ -1473,17 +1507,25 @@ def validate_upload_request(method: str, path: str, headers: dict, query_params:
regional = re.search(r"(?:^|\.)s3[.-]([a-z]{2}(?:-[a-z]+)+-\d+)\.(.+)$", host)
if regional:
endpoint_region, suffix = regional.groups()
+ if method == "GET" and signature.region != endpoint_region:
+ return _object_error(
+ "AuthorizationHeaderMalformed", "The authorization header is malformed; "
+ f"the region '{signature.region}' is wrong; expecting '{endpoint_region}'", 400, Region=endpoint_region,
+ )
bucket_region = (record or {}).get("region") or os.environ.get("MINISTACK_REGION", "us-east-1")
if record is not None and bucket_region != endpoint_region:
- response = _upload_error(
+ endpoint = f"{bucket}.s3.{bucket_region}.{suffix}"
+ fields = ({"Bucket": bucket, "Endpoint": endpoint} if method == "GET"
+ else {"Endpoint": endpoint, "Bucket": bucket})
+ response = _object_error(
"PermanentRedirect", "The bucket you are attempting to access must be addressed using the specified "
"endpoint. Please send all future requests to this endpoint.", 301,
- Endpoint=f"{bucket}.s3.{bucket_region}.{suffix}", Bucket=bucket,
+ **fields,
)
response[1]["x-amz-bucket-region"] = bucket_region
return response
if signature.region != endpoint_region:
- return _upload_error(
+ return _object_error(
"AuthorizationHeaderMalformed", "The authorization header is malformed; "
f"the region '{signature.region}' is wrong; expecting '{endpoint_region}'", 400, Region=endpoint_region,
)
@@ -1493,9 +1535,9 @@ def validate_upload_request(method: str, path: str, headers: dict, query_params:
fields = denied.details
if code == "InvalidAccessKeyId":
fields = {"AWSAccessKeyId": signature.access_key_id}
- return _upload_error(code, message, status, **fields)
+ return _object_error(code, message, status, **fields)
if record is None:
- return _upload_error("NoSuchBucket", "The specified bucket does not exist", 404, BucketName=bucket)
+ return _object_error("NoSuchBucket", "The specified bucket does not exist", 404, BucketName=bucket)
return None
@@ -5389,12 +5431,17 @@ def _get_object(bucket_name: str, key: str, headers: dict, query_params: dict =
return _error("NoSuchVersion", "The specified version does not exist.", 404, f"/{bucket_name}/{key}")
if key not in bucket["objects"]:
- status, err_headers, err_body = _error(
- "NoSuchKey",
- "The specified key does not exist.",
- 404,
- f"/{bucket_name}/{key}",
- )
+ from ministack.app import AUTH
+
+ if (AUTH and not query_params.keys() - {"x-id"}
+ and headers.get("authorization", "").startswith("AWS4-HMAC-SHA256")):
+ status, err_headers, err_body = _object_error(
+ "NoSuchKey", "The specified key does not exist.", 404, Key=key,
+ )
+ else:
+ status, err_headers, err_body = _error(
+ "NoSuchKey", "The specified key does not exist.", 404, f"/{bucket_name}/{key}",
+ )
# A key hidden by a delete marker announces the marker on its 404.
err_headers.update(_delete_marker_404_headers(bucket_name, key))
return status, err_headers, err_body
diff --git a/tests/test_s3.py b/tests/test_s3.py
index dc5de02d..5e146d1d 100644
--- a/tests/test_s3.py
+++ b/tests/test_s3.py
@@ -10329,6 +10329,7 @@ def test_s3_mrap_requests_are_authorized_on_the_bucket_and_the_mrap(
with second_access_key(user) as credentials:
for action, method, target, body, resource in [
("GetObject", "GET", "/who.txt", b"", "/who.txt"),
+ ("GetObject", "HEAD", "/who.txt", b"", "/who.txt"),
("PutObject", "PUT", "/mrap-put.txt", b"x", "/mrap-put.txt"),
("ListBucket", "GET", "/?list-type=2", b"", ""),
]:
@@ -10337,7 +10338,11 @@ def test_s3_mrap_requests_are_authorized_on_the_bucket_and_the_mrap(
assert status == 200, data
continue
arn = (bucket_arn if denied_on == "bucket" else mrap_arn + ("/object" if resource else "")) + resource
- assert status == 403 and ElementTree.fromstring(data).findtext("Code") == "AccessDenied"
+ assert status == 403
+ if method == "HEAD":
+ assert data == b""
+ continue
+ assert ElementTree.fromstring(data).findtext("Code") == "AccessDenied"
assert ElementTree.fromstring(data).findtext("Message") == (
f'User: {user.arn} is not authorized to perform: s3:{action} on resource: "{arn}" '
f"because no identity-based policy allows the s3:{action} action")
diff --git a/tests/test_s3_access_points.py b/tests/test_s3_access_points.py
index be2ebc39..3d8b91e7 100644
--- a/tests/test_s3_access_points.py
+++ b/tests/test_s3_access_points.py
@@ -296,7 +296,9 @@ def test_access_point_arn_other_account_is_denied(access_point):
assert exc.value.response["Error"]["Code"] in ("AccessDenied", "NoSuchAccessPoint")
-def test_access_point_arn_shaped_bucket_without_access_point_is_a_bucket():
[email protected]("method", ["GET", "HEAD"])
+def test_access_point_arn_shaped_bucket_without_access_point_is_a_bucket(auth_enabled, method):
"""`<name>-<12 digits>` is a valid bucket name; with no access point of
that name it is served as the bucket."""
s3 = _client("s3", "us-east-1")
@@ -305,7 +307,11 @@ def test_access_point_arn_shaped_bucket_without_access_point_is_a_bucket():
try:
s3.put_object(Bucket=name, Key="b.txt", Body=b"bucket")
host = f"{name}.{ENDPOINT.split('://', 1)[1]}"
- assert _raw("GET", host, "/b.txt", "us-east-1")[2] == b"bucket"
+ status, headers, body = _raw(method, host, "/b.txt", "us-east-1")
+ assert status == 200
+ assert body == (b"bucket" if method == "GET" else b"")
+ if auth_enabled and method == "HEAD":
+ assert re.fullmatch(r"[A-Z0-9]{16}", headers["x-amz-request-id"])
finally:
s3.delete_object(Bucket=name, Key="b.txt")
s3.delete_bucket(Bucket=name)
@@ -347,6 +353,45 @@ def test_access_point_alias_upload_permission_contract(
assert body.read() == b"via alias"
[email protected]("target,addressing_style", [("Alias", "path"), ("Alias", "virtual"), ("AccessPointArn", "virtual")])
[email protected]("allow_head", [False, True], ids=["no-permission", "allow"])
+def test_access_point_head_permission_contract(access_point, auth_enabled, iam_user, target, addressing_style, allow_head):
+ _, created = access_point
+ policy = {"Statement": [{"Effect": "Allow", "Action": "s3:GetObject", "Resource": "*"}]}
+ client = iam_user(policy=policy if allow_head else None).client(
+ "s3", region="us-east-1", config=Config(s3={"addressing_style": addressing_style}))
+ if auth_enabled and not allow_head:
+ with pytest.raises(ClientError) as exc:
+ client.head_object(Bucket=created[target], Key="k.txt")
+ assert exc.value.response["ResponseMetadata"]["HTTPStatusCode"] == 403
+ else:
+ response = client.head_object(Bucket=created[target], Key="k.txt")
+ assert response["ResponseMetadata"]["HTTPStatusCode"] == 200
+ assert response["ContentLength"] == 5
+
+
[email protected]("target", ["Alias", "AccessPointArn"])
[email protected]("allow_delete", [False, True], ids=["no-permission", "allow"])
+def test_access_point_delete_permission_contract(bucket, access_point, auth_enabled, iam_user, target, allow_delete):
+ _, created = access_point
+ policy = {"Statement": [{"Effect": "Allow", "Action": "s3:DeleteObject", "Resource": "*"}]}
+ client = iam_user(policy=policy if allow_delete else None).client("s3", region="us-east-1")
+ root = _client("s3", "us-east-1")
+ if auth_enabled and not allow_delete:
+ with pytest.raises(ClientError) as exc:
+ client.delete_object(Bucket=created[target], Key="k.txt")
+ assert exc.value.response["ResponseMetadata"]["HTTPStatusCode"] == 403
+ with root.get_object(Bucket=bucket, Key="k.txt")["Body"] as body:
+ assert body.read() == b"hello"
+ else:
+ assert client.delete_object(Bucket=created[target], Key="k.txt")["ResponseMetadata"]["HTTPStatusCode"] == 204
+ with pytest.raises(ClientError) as exc:
+ root.head_object(Bucket=bucket, Key="k.txt")
+ assert exc.value.response["ResponseMetadata"]["HTTPStatusCode"] == 404
+
+
def _status(call):
try:
return call()["ResponseMetadata"]["HTTPStatusCode"]
diff --git a/tests/test_s3_delete_errors.py b/tests/test_s3_delete_errors.py
new file mode 100644
index 00000000..695e154e
--- /dev/null
+++ b/tests/test_s3_delete_errors.py
@@ -0,0 +1,297 @@
+"""DeleteObject observations from real AWS, Osaka, 2026-10-23.
+
+AWS.Tools.S3 5.0.318 / AWS CLI 2.38.1 used explicit Osaka/Tokyo endpoints
+and bucket-scoped DeleteObject grants. These tests replay the first HTTP
+response locally, before SDK correction. No real AWS requests are made.
+"""
+import base64
+import hashlib
+import http.client
+import os
+import re
+import uuid
+from urllib.parse import parse_qsl, quote, urlencode, urlsplit
+from xml.etree.ElementTree import fromstring
+
+import boto3
+import pytest
+from botocore.auth import S3SigV4Auth
+from botocore.awsrequest import AWSRequest
+from botocore.config import Config
+from botocore.credentials import Credentials
+from botocore.exceptions import ClientError
+
+ENDPOINT = os.environ.get("MINISTACK_ENDPOINT", "http://localhost:4566")
+HOME, TOKYO = "ap-northeast-3", "ap-northeast-1"
+PAYLOAD = b"delete error validation"
+pytestmark = pytest.mark.auth_contract
+
+
+def delete_bucket(s3):
+ name = f"delete-errors-{uuid.uuid4().hex}"
+ s3.create_bucket(Bucket=name, CreateBucketConfiguration={"LocationConstraint": HOME})
+ s3.put_object(Bucket=name, Key="probe.txt", Body=PAYLOAD)
+ yield name
+ s3.delete_object(Bucket=name, Key="probe.txt")
+ s3.delete_bucket(Bucket=name)
+
+
+def delete_client(delete_bucket, iam_user):
+ return iam_user(policy={"Statement": [
+ {"Effect": "Allow", "Action": "s3:DeleteObject", "Resource": f"arn:aws:s3:::{delete_bucket}/*"},
+ ]}).client("s3", region=HOME)
+
+
+def _send(host, path, headers):
+ target = urlsplit(ENDPOINT)
+ connection = http.client.HTTPConnection(target.hostname, target.port or 80, timeout=10)
+ try:
+ connection.request("DELETE", path, headers={**headers, "Host": host})
+ response = connection.getresponse()
+ return response.status, {k.lower(): v for k, v in response.getheaders()}, response.read()
+ finally:
+ connection.close()
+
+
+def _delete(bucket, client, *, credential="valid", endpoint_region=HOME, region=HOME,
+ virtual=False, key="probe.txt", query="", root=False, extra_headers=None):
+ frozen = client._request_signer._credentials.get_frozen_credentials()
+ access_key, secret = frozen.access_key, frozen.secret_key
+ if credential == "unknown":
+ access_key, secret = "AKIAUNKNOWNKEY000001", "wrong"
+ elif credential == "wrong-secret":
+ secret = "wrong"
+ if root:
+ access_key, secret = "test", "any-secret"
+ host = f"s3.{endpoint_region}.{urlsplit(ENDPOINT).netloc}"
+ path = f"/{quote(bucket)}/{quote(key, safe='/')}"
+ if virtual:
+ host, path = f"{bucket}.{host}", f"/{quote(key, safe='/')}"
+ request = AWSRequest(method="DELETE", url=f"http://{host}{path}{query}", headers=extra_headers)
+ S3SigV4Auth(Credentials(access_key, secret), "s3", region).add_auth(request)
+ return _send(host, path + query, dict(request.headers))
+
+
+def _assert_state(client, bucket, *, deleted):
+ if deleted:
+ with pytest.raises(ClientError) as exc:
+ client.get_object(Bucket=bucket, Key="probe.txt")
+ assert exc.value.response["Error"]["Code"] == "NoSuchKey"
+ else:
+ with client.get_object(Bucket=bucket, Key="probe.txt")["Body"] as body:
+ assert body.read() == PAYLOAD
+
+
+def _assert_error(response, code, *, bucket, region=HOME, endpoint_region=HOME, access_key=None):
+ _, headers, body = response
+ error = fromstring(body)
+ messages = {
+ "InvalidBucketName": "The specified bucket is not valid.",
+ "InvalidAccessKeyId": "The AWS Access Key Id you provided does not exist in our records.",
+ "SignatureDoesNotMatch": "The request signature we calculated does not match the signature you provided. "
+ "Check your key and signing method.",
+ "AuthorizationHeaderMalformed": f"The authorization header is malformed; the region '{region}' is wrong; "
+ f"expecting '{endpoint_region}'",
+ "PermanentRedirect": "The bucket you are attempting to access must be addressed using the specified "
+ "endpoint. Please send all future requests to this endpoint.",
+ "NoSuchBucket": "The specified bucket does not exist",
+ }
+ details = {
+ "InvalidBucketName": ["BucketName"], "InvalidAccessKeyId": ["AWSAccessKeyId"],
+ "AuthorizationHeaderMalformed": ["Region"], "PermanentRedirect": ["Endpoint", "Bucket"],
+ "NoSuchBucket": ["BucketName"],
+ "SignatureDoesNotMatch": ["AWSAccessKeyId", "StringToSign", "SignatureProvided", "StringToSignBytes",
+ "CanonicalRequest", "CanonicalRequestBytes"],
+ }
+ expected = ["Code", "Message", *details[code], "RequestId", "HostId"]
+ assert error.findtext("Code") == code
+ assert error.findtext("Message") == messages[code]
+ if code == "SignatureDoesNotMatch":
+ # Diagnostic membership and consistency matter even if AWS varies field order.
+ assert sorted(child.tag for child in error) == sorted(expected)
+ for name in ("CanonicalRequest", "StringToSign"):
+ assert bytes.fromhex(error.findtext(name + "Bytes")).decode() == error.findtext(name)
+ assert error.findtext("CanonicalRequest").startswith("DELETE\n")
+ document = error.findtext("StringToSign")
+ assert document.splitlines()[-1] == hashlib.sha256(error.findtext("CanonicalRequest").encode()).hexdigest()
+ signed = AWSRequest()
+ signed.context["timestamp"] = document.splitlines()[1]
+ signer = S3SigV4Auth(Credentials(error.findtext("AWSAccessKeyId"), "wrong"), "s3", region)
+ assert signer.signature(document, signed) == error.findtext("SignatureProvided")
+ else:
+ assert [child.tag for child in error] == expected
+ assert headers["content-type"] == "application/xml"
+ assert error.findtext("RequestId") == headers["x-amz-request-id"]
+ assert re.fullmatch(r"[A-Z0-9]{16}", error.findtext("RequestId"))
+ assert error.findtext("HostId") == headers["x-amz-id-2"]
+ assert len(base64.b64decode(error.findtext("HostId"), validate=True)) >= 48
+ assert "location" not in headers
+ if code == "PermanentRedirect":
+ assert error.findtext("Endpoint") == f"{bucket}.s3.{HOME}.{urlsplit(ENDPOINT).netloc}"
+ assert error.findtext("Bucket") == bucket
+ assert headers["x-amz-bucket-region"] == HOME
+ else:
+ assert "x-amz-bucket-region" not in headers
+ if code in {"InvalidBucketName", "NoSuchBucket"}:
+ assert error.findtext("BucketName") == bucket
+ if code == "AuthorizationHeaderMalformed":
+ assert error.findtext("Region") == endpoint_region
+ if access_key is not None:
+ assert error.findtext("AWSAccessKeyId") == access_key
+
+
[email protected]("virtual", [False, True], ids=["path", "virtual"])
[email protected]("missing,credential,endpoint_region,region,expected,compat_expected", [
+ # Fixed first-response observations; DELETE success must also remove the object.
+ (False, "valid", HOME, HOME, (204, None), (204, None)),
+ (False, "unknown", HOME, HOME, (403, "InvalidAccessKeyId"), (204, None)),
+ (False, "wrong-secret", HOME, HOME, (403, "SignatureDoesNotMatch"), (204, None)),
+ (True, "valid", HOME, HOME, (404, "NoSuchBucket"), (404, "NoSuchBucket")),
+ (True, "unknown", HOME, HOME, (403, "InvalidAccessKeyId"), (404, "NoSuchBucket")),
+ (True, "wrong-secret", HOME, HOME, (403, "SignatureDoesNotMatch"), (404, "NoSuchBucket")),
+ (False, "valid", HOME, TOKYO, (400, "AuthorizationHeaderMalformed"), (400, "AuthorizationHeaderMalformed")),
+ (False, "unknown", HOME, TOKYO, (400, "AuthorizationHeaderMalformed"), (400, "AuthorizationHeaderMalformed")),
+ (False, "wrong-secret", HOME, TOKYO, (400, "AuthorizationHeaderMalformed"), (400, "AuthorizationHeaderMalformed")),
+ (True, "valid", HOME, TOKYO, (400, "AuthorizationHeaderMalformed"), (404, "NoSuchBucket")),
+ (True, "unknown", HOME, TOKYO, (400, "AuthorizationHeaderMalformed"), (404, "NoSuchBucket")),
+ (True, "wrong-secret", HOME, TOKYO, (400, "AuthorizationHeaderMalformed"), (404, "NoSuchBucket")),
+ # Existing-bucket valid/unknown + Tokyo endpoint/Osaka signature live in
+ # test_delete_home_precedes_signing_region_and_credentials, including state checks.
+ (False, "wrong-secret", TOKYO, HOME, (301, "PermanentRedirect"), (204, None)),
+ (True, "valid", TOKYO, HOME, (400, "AuthorizationHeaderMalformed"), (404, "NoSuchBucket")),
+ (True, "unknown", TOKYO, HOME, (400, "AuthorizationHeaderMalformed"), (404, "NoSuchBucket")),
+ (True, "wrong-secret", TOKYO, HOME, (400, "AuthorizationHeaderMalformed"), (404, "NoSuchBucket")),
+ (False, "valid", TOKYO, TOKYO, (301, "PermanentRedirect"), (301, "PermanentRedirect")),
+ (False, "unknown", TOKYO, TOKYO, (301, "PermanentRedirect"), (301, "PermanentRedirect")),
+ (False, "wrong-secret", TOKYO, TOKYO, (301, "PermanentRedirect"), (301, "PermanentRedirect")),
+ (True, "valid", TOKYO, TOKYO, (404, "NoSuchBucket"), (404, "NoSuchBucket")),
+ (True, "unknown", TOKYO, TOKYO, (403, "InvalidAccessKeyId"), (404, "NoSuchBucket")),
+ (True, "wrong-secret", TOKYO, TOKYO, (403, "SignatureDoesNotMatch"), (404, "NoSuchBucket")),
+])
+def test_delete_combined_errors(delete_bucket, delete_client, s3, auth_enabled,
+ virtual, missing, credential, endpoint_region, region, expected, compat_expected):
+ bucket = f"missing-{delete_bucket}" if missing else delete_bucket
+ expected = expected if auth_enabled else compat_expected
+ response = _delete(bucket, delete_client, virtual=virtual, credential=credential,
+ endpoint_region=endpoint_region, region=region)
+ assert (response[0], fromstring(response[2]).findtext("Code") if response[2] else None) == expected
+ _assert_state(s3, delete_bucket, deleted=not missing and response[0] == 204)
+ if response[0] == 204:
+ assert response[2] == b""
+ elif auth_enabled:
+ access_key = "AKIAUNKNOWNKEY000001" if credential == "unknown" else delete_client._request_signer._credentials.access_key
+ _assert_error(response, expected[1], bucket=bucket, region=region, endpoint_region=endpoint_region,
+ access_key=access_key if expected[1] in {"InvalidAccessKeyId", "SignatureDoesNotMatch"} else None)
+
+
[email protected]("virtual", [False, True])
[email protected]("credential", ["valid", "unknown"])
+def test_delete_home_precedes_signing_region_and_credentials(delete_bucket, delete_client, s3,
+ auth_enabled, virtual, credential):
+ # Fixed AWS observation: redirect, including with an unknown access key.
+ response = _delete(delete_bucket, delete_client, virtual=virtual, credential=credential,
+ endpoint_region=TOKYO, region=HOME)
+ assert response[0] == (301 if auth_enabled else 204)
+ if auth_enabled:
+ _assert_error(response, "PermanentRedirect", bucket=delete_bucket, endpoint_region=TOKYO)
+ else:
+ assert response[2] == b""
+ _assert_state(s3, delete_bucket, deleted=not auth_enabled)
+
+
[email protected]("virtual", [False, True])
[email protected]("credential,region", [("valid", HOME), ("unknown", HOME), ("wrong-secret", HOME), ("valid", TOKYO)])
+def test_delete_missing_key_is_idempotent(delete_bucket, delete_client, s3, auth_enabled, virtual, credential, region):
+ response = _delete(delete_bucket, delete_client, virtual=virtual, credential=credential, region=region, key="missing.txt")
+ code = ("AuthorizationHeaderMalformed" if region != HOME else
+ "InvalidAccessKeyId" if auth_enabled and credential == "unknown" else
+ "SignatureDoesNotMatch" if auth_enabled and credential == "wrong-secret" else None)
+ assert (response[0], fromstring(response[2]).findtext("Code") if response[2] else None) == (
+ 400 if region != HOME else 403 if code else 204, code)
+ if code and auth_enabled:
+ _assert_error(response, code, bucket=delete_bucket, region=region)
+ if not code:
+ assert response[2] == b""
+ assert _delete(delete_bucket, delete_client, virtual=virtual, key="missing.txt")[0] == 204
+ _assert_state(s3, delete_bucket, deleted=False)
+
+
+def test_delete_invalid_name_precedes_credentials(delete_client, auth_enabled):
+ response = _delete("invalid bucket", delete_client, credential="unknown")
+ assert response[0] == (400 if auth_enabled else 404)
+ if auth_enabled:
+ _assert_error(response, "InvalidBucketName", bucket="invalid bucket")
+
+
[email protected]("virtual", [False, True])
[email protected]("denial", ["implicit", "explicit"])
+def test_delete_still_enforces_iam(delete_bucket, iam_user, s3, auth_enabled, virtual, denial):
+ policy = {"Statement": [{"Effect": "Deny", "Action": "s3:DeleteObject", "Resource": "*"}]}
+ client = iam_user(policy=policy if denial == "explicit" else None).client("s3", region=HOME)
+ response = _delete(delete_bucket, client, virtual=virtual)
+ assert response[0] == (403 if auth_enabled else 204)
+ _assert_state(s3, delete_bucket, deleted=not auth_enabled)
+ assert _delete(delete_bucket, client, virtual=virtual, key="missing.txt")[0] == (403 if auth_enabled else 204)
+
+
[email protected]("virtual", [False, True])
+def test_delete_reserved_root_compatibility(delete_bucket, s3, virtual):
+ assert _delete(delete_bucket, s3, virtual=virtual, root=True)[0] == 204
+ _assert_state(s3, delete_bucket, deleted=True)
+
+
[email protected]("virtual", [False, True])
+def test_delete_does_not_grant_foreign_bucket_access(iam_user, auth_enabled, virtual):
+ owner = boto3.client("s3", endpoint_url=ENDPOINT, region_name=HOME,
+ aws_access_key_id="333333333333", aws_secret_access_key="root-secret")
+ bucket = f"foreign-delete-{uuid.uuid4().hex}"
+ owner.create_bucket(Bucket=bucket, CreateBucketConfiguration={"LocationConstraint": HOME})
+ owner.put_object(Bucket=bucket, Key="probe.txt", Body=PAYLOAD)
+ client = iam_user(policy={"Statement": [{"Effect": "Allow", "Action": "s3:DeleteObject", "Resource": "*"}]}).client("s3")
+ try:
+ assert _delete(bucket, client, virtual=virtual)[0] == 403
+ _assert_state(owner, bucket, deleted=False)
+ finally:
+ owner.delete_object(Bucket=bucket, Key="probe.txt")
+ owner.delete_bucket(Bucket=bucket)
+ owner.close()
+
+
[email protected]("virtual", [False, True])
[email protected]("query", ["?versionId=null", "?tagging"])
+def test_delete_subresources_keep_their_iam_path(delete_bucket, iam_user, auth_enabled, virtual, query):
+ client = iam_user().client("s3", region=HOME)
+ response = _delete(f"missing-{delete_bucket}", client, virtual=virtual, query=query)
+ assert response[0] == (403 if auth_enabled else 404)
+
+
[email protected]("virtual", [False, True])
+def test_delete_version_needs_its_own_permission(delete_bucket, delete_client, s3, auth_enabled, virtual):
+ response = _delete(delete_bucket, delete_client, virtual=virtual, query="?versionId=null")
+ assert response[0] == (403 if auth_enabled else 204)
+ _assert_state(s3, delete_bucket, deleted=not auth_enabled)
+
+
[email protected]("virtual", [False, True])
+def test_delete_failed_precondition_preserves_object(delete_bucket, delete_client, s3, virtual):
+ response = _delete(delete_bucket, delete_client, virtual=virtual, extra_headers={"If-Match": '"incorrect"'})
+ assert (response[0], fromstring(response[2]).findtext("Code")) == (412, "PreconditionFailed")
+ _assert_state(s3, delete_bucket, deleted=False)
+
+
[email protected]("virtual", [False, True])
[email protected]("invalid", [False, True], ids=["valid", "bad-signature"])
+def test_delete_presigned_validation_is_preserved(delete_bucket, iam_user, s3, virtual, invalid):
+ client = iam_user(policy={"Statement": [
+ {"Effect": "Allow", "Action": "s3:DeleteObject", "Resource": f"arn:aws:s3:::{delete_bucket}/*"},
+ ]}).client("s3", region=HOME, config=Config(signature_version="s3v4", s3={"addressing_style": "virtual" if virtual else "path"}))
+ target = urlsplit(client.generate_presigned_url("delete_object", Params={"Bucket": delete_bucket, "Key": "probe.txt"}))
+ query = dict(parse_qsl(target.query))
+ if invalid:
+ signature = query["X-Amz-Signature"]
+ query["X-Amz-Signature"] = ("0" if signature[0] != "0" else "1") + signature[1:]
+ response = _send(target.netloc, target.path + "?" + urlencode(query), {})
+ assert response[0] == (403 if invalid else 204)
+ _assert_state(s3, delete_bucket, deleted=not invalid)
diff --git a/tests/test_s3_download_errors.py b/tests/test_s3_download_errors.py
new file mode 100644
index 00000000..55bd8088
--- /dev/null
+++ b/tests/test_s3_download_errors.py
@@ -0,0 +1,266 @@
+"""GetObject observations from real AWS, Osaka, 2026-10-18.
+
+AWS CLI 2.38.1 / AWS.Tools.S3 5.0.318 used explicit Osaka/Tokyo endpoints
+and a bucket-scoped GetObject/ListBucket grant. These tests replay HTTP
+observations locally, before client region correction; they never call AWS.
+AUTH=false assertions preserve MiniStack's permissive compatibility.
+"""
+import base64
+import hashlib
+import http.client
+import os
+import re
+import uuid
+from urllib.parse import quote, urlsplit
+from xml.etree.ElementTree import fromstring
+
+import boto3
+import pytest
+from botocore.auth import S3SigV4Auth
+from botocore.awsrequest import AWSRequest
+from botocore.credentials import Credentials
+
+ENDPOINT = os.environ.get("MINISTACK_ENDPOINT", "http://localhost:4566")
+HOME, TOKYO = "ap-northeast-3", "ap-northeast-1"
+PAYLOAD = b"download error validation"
+pytestmark = pytest.mark.auth_contract
+
+
+def download_bucket(s3):
+ name = f"download-errors-{uuid.uuid4().hex}"
+ s3.create_bucket(Bucket=name, CreateBucketConfiguration={"LocationConstraint": HOME})
+ s3.put_object(Bucket=name, Key="probe.txt", Body=PAYLOAD)
+ yield name
+ s3.delete_object(Bucket=name, Key="probe.txt")
+ s3.delete_bucket(Bucket=name)
+
+
+def download_client(download_bucket, iam_user):
+ return iam_user(policy={"Statement": [
+ {"Effect": "Allow", "Action": "s3:GetObject", "Resource": f"arn:aws:s3:::{download_bucket}/*"},
+ {"Effect": "Allow", "Action": "s3:ListBucket", "Resource": f"arn:aws:s3:::{download_bucket}"},
+ ]}).client("s3", region=HOME)
+
+
+def _download(bucket, client, *, credential="valid", endpoint_region=HOME, region=HOME,
+ virtual=False, key="probe.txt", query="", root=False):
+ frozen = client._request_signer._credentials.get_frozen_credentials()
+ access_key, secret = frozen.access_key, frozen.secret_key
+ if credential == "unknown":
+ access_key, secret = "AKIAUNKNOWNKEY000001", "wrong"
+ elif credential == "wrong-secret":
+ secret = "wrong"
+ if root:
+ access_key, secret = "test", "any-secret"
+ target = urlsplit(ENDPOINT)
+ host = f"s3.{endpoint_region}.{target.netloc}"
+ path = f"/{quote(bucket)}/{quote(key, safe='/')}"
+ if virtual:
+ host, path = f"{bucket}.{host}", f"/{quote(key, safe='/')}"
+ request = AWSRequest(method="GET", url=f"http://{host}{path}{query}")
+ S3SigV4Auth(Credentials(access_key, secret), "s3", region).add_auth(request)
+ connection = http.client.HTTPConnection(target.hostname, target.port or 80, timeout=10)
+ try:
+ connection.request("GET", path + query, headers={**dict(request.headers), "Host": host})
+ response = connection.getresponse()
+ return response.status, {k.lower(): v for k, v in response.getheaders()}, response.read()
+ finally:
+ connection.close()
+
+
+def _assert_error(response, code, *, bucket, key="probe.txt", region=HOME, access_key=None):
+ _, headers, body = response
+ error = fromstring(body)
+ messages = {
+ "InvalidBucketName": "The specified bucket is not valid.",
+ "InvalidAccessKeyId": "The AWS Access Key Id you provided does not exist in our records.",
+ "SignatureDoesNotMatch": "The request signature we calculated does not match the signature you provided. "
+ "Check your key and signing method.",
+ "AuthorizationHeaderMalformed": f"The authorization header is malformed; the region '{region}' is wrong; "
+ f"expecting '{HOME if region == TOKYO else TOKYO}'",
+ "PermanentRedirect": "The bucket you are attempting to access must be addressed using the specified "
+ "endpoint. Please send all future requests to this endpoint.",
+ "NoSuchBucket": "The specified bucket does not exist",
+ "NoSuchKey": "The specified key does not exist.",
+ }
+ details = {
+ "InvalidBucketName": ["BucketName"], "InvalidAccessKeyId": ["AWSAccessKeyId"],
+ "AuthorizationHeaderMalformed": ["Region"], "PermanentRedirect": ["Bucket", "Endpoint"],
+ "NoSuchBucket": ["BucketName"], "NoSuchKey": ["Key"],
+ "SignatureDoesNotMatch": ["AWSAccessKeyId", "StringToSign", "SignatureProvided", "StringToSignBytes",
+ "CanonicalRequest", "CanonicalRequestBytes"],
+ }
+ expected = ["Code", "Message", *details[code], "RequestId", "HostId"]
+ assert error.findtext("Code") == code
+ assert error.findtext("Message") == messages[code]
+ if code == "SignatureDoesNotMatch":
+ # Real GET responses varied the order of the signature diagnostics.
+ assert sorted(child.tag for child in error) == sorted(expected)
+ for name in ("CanonicalRequest", "StringToSign"):
+ assert bytes.fromhex(error.findtext(name + "Bytes")).decode() == error.findtext(name)
+ assert error.findtext("CanonicalRequest").startswith("GET\n")
+ assert error.findtext("StringToSign").splitlines()[-1] == hashlib.sha256(
+ error.findtext("CanonicalRequest").encode()).hexdigest()
+ assert re.fullmatch(r"[a-f0-9]{64}", error.findtext("SignatureProvided"))
+ signed = AWSRequest()
+ document = error.findtext("StringToSign")
+ signed.context["timestamp"] = document.splitlines()[1]
+ signer = S3SigV4Auth(Credentials(error.findtext("AWSAccessKeyId"), "wrong"), "s3", region)
+ assert signer.signature(document, signed) == error.findtext("SignatureProvided")
+ else:
+ assert [child.tag for child in error] == expected
+ assert headers["content-type"] == "application/xml"
+ assert error.findtext("RequestId") == headers["x-amz-request-id"]
+ assert re.fullmatch(r"[A-Z0-9]{16}", error.findtext("RequestId"))
+ assert error.findtext("HostId") == headers["x-amz-id-2"]
+ assert len(base64.b64decode(error.findtext("HostId"), validate=True)) >= 48
+ assert "location" not in headers
+ if code == "PermanentRedirect":
+ assert error.findtext("Endpoint") == f"{bucket}.s3.{HOME}.{urlsplit(ENDPOINT).netloc}"
+ assert error.findtext("Bucket") == bucket
+ assert headers["x-amz-bucket-region"] == HOME
+ else:
+ assert "x-amz-bucket-region" not in headers
+ if code in {"InvalidBucketName", "NoSuchBucket"}:
+ assert error.findtext("BucketName") == bucket
+ if code == "NoSuchKey":
+ assert error.findtext("Key") == key
+ if code == "AuthorizationHeaderMalformed":
+ assert error.findtext("Region") == (HOME if region == TOKYO else TOKYO)
+ if access_key is not None:
+ assert error.findtext("AWSAccessKeyId") == access_key
+
+
[email protected]("virtual", [False, True], ids=["path", "virtual"])
[email protected]("missing,credential,endpoint_region,region,expected,compat_expected", [
+ # Fixed first-response observations; AUTH=false is a separate local contract.
+ (False, "valid", HOME, HOME, (200, None), (200, None)),
+ (False, "unknown", HOME, HOME, (403, "InvalidAccessKeyId"), (200, None)),
+ (False, "wrong-secret", HOME, HOME, (403, "SignatureDoesNotMatch"), (200, None)),
+ (True, "valid", HOME, HOME, (404, "NoSuchBucket"), (404, "NoSuchBucket")),
+ (True, "unknown", HOME, HOME, (403, "InvalidAccessKeyId"), (404, "NoSuchBucket")),
+ (True, "wrong-secret", HOME, HOME, (403, "SignatureDoesNotMatch"), (404, "NoSuchBucket")),
+ (False, "valid", HOME, TOKYO, (400, "AuthorizationHeaderMalformed"), (400, "AuthorizationHeaderMalformed")),
+ (False, "unknown", HOME, TOKYO, (400, "AuthorizationHeaderMalformed"), (400, "AuthorizationHeaderMalformed")),
+ (False, "wrong-secret", HOME, TOKYO, (400, "AuthorizationHeaderMalformed"), (400, "AuthorizationHeaderMalformed")),
+ (True, "valid", HOME, TOKYO, (400, "AuthorizationHeaderMalformed"), (404, "NoSuchBucket")),
+ (True, "unknown", HOME, TOKYO, (400, "AuthorizationHeaderMalformed"), (404, "NoSuchBucket")),
+ (True, "wrong-secret", HOME, TOKYO, (400, "AuthorizationHeaderMalformed"), (404, "NoSuchBucket")),
+ # Existing-bucket valid/unknown + Tokyo endpoint/Osaka signature live in
+ # test_download_signing_region_precedes_home_and_credentials, including wire checks.
+ (False, "wrong-secret", TOKYO, HOME, (400, "AuthorizationHeaderMalformed"), (200, None)),
+ (True, "valid", TOKYO, HOME, (400, "AuthorizationHeaderMalformed"), (404, "NoSuchBucket")),
+ (True, "unknown", TOKYO, HOME, (400, "AuthorizationHeaderMalformed"), (404, "NoSuchBucket")),
+ (True, "wrong-secret", TOKYO, HOME, (400, "AuthorizationHeaderMalformed"), (404, "NoSuchBucket")),
+ (False, "valid", TOKYO, TOKYO, (301, "PermanentRedirect"), (301, "PermanentRedirect")),
+ (False, "unknown", TOKYO, TOKYO, (301, "PermanentRedirect"), (301, "PermanentRedirect")),
+ (False, "wrong-secret", TOKYO, TOKYO, (301, "PermanentRedirect"), (301, "PermanentRedirect")),
+ (True, "valid", TOKYO, TOKYO, (404, "NoSuchBucket"), (404, "NoSuchBucket")),
+ (True, "unknown", TOKYO, TOKYO, (403, "InvalidAccessKeyId"), (404, "NoSuchBucket")),
+ (True, "wrong-secret", TOKYO, TOKYO, (403, "SignatureDoesNotMatch"), (404, "NoSuchBucket")),
+])
+def test_download_combined_errors(download_bucket, download_client, auth_enabled,
+ virtual, missing, credential, endpoint_region, region, expected, compat_expected):
+ bucket = f"missing-{download_bucket}" if missing else download_bucket
+ expected = expected if auth_enabled else compat_expected
+ response = _download(bucket, download_client, credential=credential, endpoint_region=endpoint_region,
+ region=region, virtual=virtual)
+ code = fromstring(response[2]).findtext("Code") if response[0] != 200 else None
+ assert (response[0], code) == expected
+ if response[0] == 200:
+ assert response[2] == PAYLOAD
+ elif auth_enabled:
+ access_key = ("AKIAUNKNOWNKEY000001" if credential == "unknown"
+ else download_client._request_signer._credentials.access_key)
+ _assert_error(response, code, bucket=bucket, region=region,
+ access_key=access_key if code in {"InvalidAccessKeyId", "SignatureDoesNotMatch"} else None)
+
+
[email protected]("virtual", [False, True])
[email protected]("credential", ["valid", "unknown"])
+def test_download_signing_region_precedes_home_and_credentials(download_bucket, download_client, s3,
+ auth_enabled, virtual, credential):
+ # Fixed AWS observation: Osaka bucket + Tokyo endpoint + Osaka signature.
+ # Kept separately as the regression for GET's different priority from HEAD/DELETE.
+ response = _download(download_bucket, download_client, virtual=virtual, credential=credential,
+ endpoint_region=TOKYO, region=HOME)
+ assert response[0] == (400 if auth_enabled else 200)
+ if auth_enabled:
+ _assert_error(response, "AuthorizationHeaderMalformed", bucket=download_bucket, region=HOME)
+ else:
+ assert response[2] == PAYLOAD
+ with s3.get_object(Bucket=download_bucket, Key="probe.txt")["Body"] as body:
+ assert body.read() == PAYLOAD
+
+
[email protected]("virtual", [False, True])
[email protected]("credential,region", [("valid", HOME), ("unknown", HOME), ("wrong-secret", HOME), ("valid", TOKYO)])
+def test_download_missing_key(download_bucket, download_client, auth_enabled, virtual, credential, region):
+ response = _download(download_bucket, download_client, virtual=virtual, credential=credential,
+ region=region, key="missing.txt")
+ code = ("AuthorizationHeaderMalformed" if region != HOME else
+ "InvalidAccessKeyId" if credential == "unknown" else
+ "SignatureDoesNotMatch" if credential == "wrong-secret" else "NoSuchKey")
+ if not auth_enabled:
+ code = "AuthorizationHeaderMalformed" if region != HOME else "NoSuchKey"
+ assert (response[0], fromstring(response[2]).findtext("Code")) == (
+ 400 if code == "AuthorizationHeaderMalformed" else 404 if code == "NoSuchKey" else 403, code,
+ )
+ if auth_enabled:
+ _assert_error(response, code, bucket=download_bucket, key="missing.txt", region=region)
+
+
+def test_download_invalid_name_precedes_credentials(download_client, auth_enabled):
+ response = _download("invalid bucket", download_client, credential="unknown")
+ assert (response[0], fromstring(response[2]).findtext("Code")) == (
+ (400, "InvalidBucketName") if auth_enabled else (404, "NoSuchBucket")
+ )
+ if auth_enabled:
+ _assert_error(response, "InvalidBucketName", bucket="invalid bucket")
+
+
[email protected]("virtual", [False, True])
[email protected]("denial", ["implicit", "explicit"])
+def test_download_still_enforces_iam(download_bucket, iam_user, auth_enabled, virtual, denial):
+ policy = {"Statement": [{"Effect": "Deny", "Action": "s3:GetObject", "Resource": "*"}]}
+ client = iam_user(policy=policy if denial == "explicit" else None).client("s3", region=HOME)
+ response = _download(download_bucket, client, virtual=virtual)
+ if auth_enabled:
+ assert (response[0], fromstring(response[2]).findtext("Code")) == (403, "AccessDenied")
+ else:
+ assert (response[0], response[2]) == (200, PAYLOAD)
+
+
[email protected]("virtual", [False, True])
+def test_download_reserved_root_compatibility(download_bucket, s3, virtual):
+ response = _download(download_bucket, s3, virtual=virtual, root=True)
+ assert (response[0], response[2]) == (200, PAYLOAD)
+
+
[email protected]("virtual", [False, True])
[email protected]("query", ["?versionId=null", "?tagging"])
+def test_download_subresources_keep_their_iam_path(download_bucket, iam_user, auth_enabled, virtual, query):
+ client = iam_user().client("s3", region=HOME)
+ response = _download(f"missing-{download_bucket}", client, virtual=virtual, query=query)
+ assert (response[0], fromstring(response[2]).findtext("Code")) == (
+ (403, "AccessDenied") if auth_enabled else (404, "NoSuchBucket")
+ )
+
+
[email protected]("virtual", [False, True])
+def test_download_does_not_grant_foreign_bucket_access(iam_user, auth_enabled, virtual):
+ owner = boto3.client("s3", endpoint_url=ENDPOINT, region_name=HOME,
+ aws_access_key_id="333333333333", aws_secret_access_key="root-secret")
+ bucket = f"foreign-download-{uuid.uuid4().hex}"
+ owner.create_bucket(Bucket=bucket, CreateBucketConfiguration={"LocationConstraint": HOME})
+ owner.put_object(Bucket=bucket, Key="probe.txt", Body=b"private")
+ client = iam_user(policy={"Statement": [{"Effect": "Allow", "Action": "s3:GetObject", "Resource": "*"}]}).client("s3")
+ try:
+ response = _download(bucket, client, virtual=virtual)
+ assert (response[0], fromstring(response[2]).findtext("Code")) == (403, "AccessDenied")
+ finally:
+ owner.delete_object(Bucket=bucket, Key="probe.txt")
+ owner.delete_bucket(Bucket=bucket)
+ owner.close()
diff --git a/tests/test_s3_head_errors.py b/tests/test_s3_head_errors.py
new file mode 100644
index 00000000..d21ff52b
--- /dev/null
+++ b/tests/test_s3_head_errors.py
@@ -0,0 +1,278 @@
+"""Real AWS HEAD observations (Osaka, 2026-10-23), replayed only against MiniStack.
+
+AWS.Tools.S3 5.0.318 and AWS CLI 2.38.1 used a bucket-scoped GetObject/ListBucket
+grant and explicit Osaka/Tokyo endpoints. Assertions describe the first HTTP
+response, before SDK region correction. HEAD has no XML error diagnostics.
+"""
+import base64
+import http.client
+import os
+import re
+import uuid
+from urllib.parse import quote, urlsplit
+
+import boto3
+import pytest
+from botocore.auth import S3SigV4Auth, S3SigV4QueryAuth
+from botocore.awsrequest import AWSRequest
+from botocore.credentials import Credentials
+
+ENDPOINT = os.environ.get("MINISTACK_ENDPOINT", "http://localhost:4566")
+HOME, TOKYO = "ap-northeast-3", "ap-northeast-1"
+PAYLOAD = b"head error validation"
+pytestmark = pytest.mark.auth_contract
+
+
[email protected]("source", ["region", "authentication", "normal", "iam", "missing-request", "missing-host"])
+def test_head_finalizer_preserves_valid_identifiers(source):
+ """Pure formatting contract: no AUTH/IAM patch, no live AWS request."""
+ from ministack.core.iam_actions import access_denied_response
+ from ministack.services import s3
+
+ host_id = base64.b64encode(b"existing-host-id" * 4).decode()
+ if source in {"region", "authentication", "missing-host"}:
+ code, status = ("PermanentRedirect", 301) if source == "region" else ("InvalidAccessKeyId", 403)
+ response = s3._object_error(code, "formatting probe", status)
+ if source == "missing-host":
+ response[1].pop("x-amz-id-2")
+ elif source == "iam":
+ response = access_denied_response("s3", "s3:GetObject", "arn:aws:iam::000000000000:user/probe", "legacy-id")
+ else:
+ response = 200, {"Content-Type": "text/plain", "Content-Length": "4", "x-amz-id-2": host_id}, b""
+ if source == "normal":
+ response[1]["x-amz-request-id"] = "12345678-1234-1234-1234-123456789abc"
+ original_headers = dict(response[1])
+ result = s3.format_head_response("/id-format-probe/key", {}, response)
+ request_id = result[1]["x-amz-request-id"]
+ assert re.fullmatch(r"[A-Z0-9]{16}", request_id)
+ if re.fullmatch(r"[A-Z0-9]{16}", original_headers.get("x-amz-request-id", "")):
+ assert request_id == original_headers["x-amz-request-id"]
+ if original_headers.get("x-amz-id-2"):
+ assert result[1]["x-amz-id-2"] == original_headers["x-amz-id-2"]
+ assert len(base64.b64decode(result[1]["x-amz-id-2"], validate=True)) >= 48
+ assert result[2] == b""
+ assert s3.format_head_response("/id-format-probe/key", {}, result) == result
+ assert response[1] == original_headers
+
+
+def head_bucket(s3):
+ name = f"head-errors-{uuid.uuid4().hex}"
+ s3.create_bucket(Bucket=name, CreateBucketConfiguration={"LocationConstraint": HOME})
+ s3.put_object(Bucket=name, Key="probe.txt", Body=PAYLOAD, ContentType="text/plain")
+ yield name
+ s3.delete_object(Bucket=name, Key="probe.txt")
+ s3.delete_bucket(Bucket=name)
+
+
+def head_client(head_bucket, iam_user):
+ return iam_user(policy={"Statement": [
+ {"Effect": "Allow", "Action": "s3:GetObject", "Resource": f"arn:aws:s3:::{head_bucket}/*"},
+ {"Effect": "Allow", "Action": "s3:ListBucket", "Resource": f"arn:aws:s3:::{head_bucket}"},
+ ]}).client("s3", region=HOME)
+
+
+def _head(bucket, client, *, key="probe.txt", virtual=False, credential="valid",
+ endpoint_region=HOME, region=HOME, root=False, query="", extra_headers=None, presigned=False):
+ frozen = client._request_signer._credentials.get_frozen_credentials()
+ access_key, secret = frozen.access_key, frozen.secret_key
+ if credential == "unknown":
+ access_key, secret = "AKIAUNKNOWNKEY000001", "wrong"
+ elif credential == "wrong-secret":
+ secret = "wrong"
+ if root:
+ access_key, secret = "test", "any-secret"
+ target = urlsplit(ENDPOINT)
+ host = f"s3.{endpoint_region}.{target.netloc}"
+ path = f"/{quote(bucket)}" + (f"/{quote(key, safe='/')}" if key else "")
+ if virtual:
+ host, path = f"{bucket}.{host}", f"/{quote(key, safe='/')}"
+ request = AWSRequest(method="HEAD", url=f"http://{host}{path}{query}", headers=extra_headers)
+ if presigned:
+ S3SigV4QueryAuth(Credentials(access_key, secret), "s3", region, expires=300).add_auth(request)
+ signed_url = urlsplit(request.url)
+ path, query = signed_url.path, "?" + signed_url.query
+ else:
+ S3SigV4Auth(Credentials(access_key, secret), "s3", region).add_auth(request)
+ connection = http.client.HTTPConnection(target.hostname, target.port or 80, timeout=10)
+ try:
+ connection.request("HEAD", path + query, headers={**dict(request.headers), "Host": host})
+ response = connection.getresponse()
+ return response.status, {k.lower(): v for k, v in response.getheaders()}, response.read()
+ finally:
+ connection.close()
+
+
+def _assert_wire(response, *, bucket, key, expected_region=None):
+ status, headers, body = response
+ assert body == b""
+ assert headers.get("x-amz-bucket-region") == expected_region
+ assert "x-amz-error-code" not in headers
+ assert "x-amz-error-message" not in headers
+ assert re.fullmatch(r"[A-Z0-9]{16}", headers["x-amz-request-id"])
+ assert len(base64.b64decode(headers["x-amz-id-2"], validate=True)) >= 48
+ if key and status == 200:
+ assert headers["content-length"] == str(len(PAYLOAD))
+ assert headers["content-type"] == "text/plain"
+ else:
+ assert "content-length" not in headers
+ assert headers["content-type"] == "application/xml"
+ assert headers.get("x-amz-bucket-arn") == (f"arn:aws:s3:::{bucket}" if not key and status == 200 else None)
+
+
[email protected]("key", ["probe.txt", ""], ids=["HeadObject", "HeadBucket"])
[email protected]("virtual", [False, True], ids=["path", "virtual"])
[email protected]("missing,credential,endpoint_region,region,expected,compat_expected", [
+ # Fixed first-response observations, separately for HeadObject and HeadBucket.
+ # Unlike GET, HEAD checks the bucket's home before the signing scope.
+ (False, "valid", HOME, HOME, 200, 200),
+ (False, "unknown", HOME, HOME, 403, 200),
+ (False, "wrong-secret", HOME, HOME, 403, 200),
+ (True, "valid", HOME, HOME, 404, 404),
+ (True, "unknown", HOME, HOME, 403, 404),
+ (True, "wrong-secret", HOME, HOME, 403, 404),
+ (False, "valid", HOME, TOKYO, 400, 400),
+ (False, "unknown", HOME, TOKYO, 400, 400),
+ (False, "wrong-secret", HOME, TOKYO, 400, 400),
+ (True, "valid", HOME, TOKYO, 400, 404),
+ (True, "unknown", HOME, TOKYO, 400, 404),
+ (True, "wrong-secret", HOME, TOKYO, 400, 404),
+ # Existing-bucket valid/unknown + Tokyo endpoint/Osaka signature live in
+ # test_head_home_precedes_signing_region_and_credentials, including wire checks.
+ (False, "wrong-secret", TOKYO, HOME, 301, 200),
+ (True, "valid", TOKYO, HOME, 400, 404),
+ (True, "unknown", TOKYO, HOME, 400, 404),
+ (True, "wrong-secret", TOKYO, HOME, 400, 404),
+ (False, "valid", TOKYO, TOKYO, 301, 301),
+ (False, "unknown", TOKYO, TOKYO, 301, 301),
+ (False, "wrong-secret", TOKYO, TOKYO, 301, 301),
+ (True, "valid", TOKYO, TOKYO, 404, 404),
+ (True, "unknown", TOKYO, TOKYO, 403, 404),
+ (True, "wrong-secret", TOKYO, TOKYO, 403, 404),
+])
+def test_head_combined_errors(head_bucket, head_client, auth_enabled,
+ key, virtual, missing, credential, endpoint_region, region, expected, compat_expected):
+ bucket = f"missing-{head_bucket}" if missing else head_bucket
+ expected = expected if auth_enabled else compat_expected
+ response = _head(bucket, head_client, key=key, virtual=virtual, credential=credential,
+ endpoint_region=endpoint_region, region=region)
+ assert response[0] == expected
+ assert response[2] == b""
+ if auth_enabled:
+ _assert_wire(response, bucket=bucket, key=key,
+ expected_region=HOME if not missing and (not key or expected == 301) else None)
+
+
[email protected]("key", ["probe.txt", ""], ids=["HeadObject", "HeadBucket"])
[email protected]("virtual", [False, True])
[email protected]("credential", ["valid", "unknown"])
+def test_head_home_precedes_signing_region_and_credentials(head_bucket, head_client, s3,
+ auth_enabled, key, virtual, credential):
+ # Fixed AWS regression: home-region redirect wins over signing/authentication errors.
+ response = _head(head_bucket, head_client, key=key, virtual=virtual, credential=credential,
+ endpoint_region=TOKYO, region=HOME)
+ assert response[0] == (301 if auth_enabled else 200)
+ assert response[2] == b""
+ if auth_enabled:
+ _assert_wire(response, bucket=head_bucket, key=key, expected_region=HOME)
+ with s3.get_object(Bucket=head_bucket, Key="probe.txt")["Body"] as body:
+ assert body.read() == PAYLOAD
+
+
[email protected]("virtual", [False, True])
[email protected]("credential,region", [("valid", HOME), ("unknown", HOME), ("wrong-secret", HOME), ("valid", TOKYO)])
+def test_head_missing_key(head_bucket, head_client, auth_enabled, virtual, credential, region):
+ response = _head(head_bucket, head_client, key="missing.txt", virtual=virtual, credential=credential, region=region)
+ expected = 400 if region != HOME else 403 if auth_enabled and credential != "valid" else 404
+ assert response[0] == expected
+ if auth_enabled:
+ _assert_wire(response, bucket=head_bucket, key="missing.txt")
+
+
[email protected]("key", ["probe.txt", ""])
+def test_head_invalid_name_precedes_credentials(head_client, auth_enabled, key):
+ response = _head("invalid bucket", head_client, key=key, credential="unknown")
+ assert response[0] == (400 if auth_enabled else 404)
+ if auth_enabled:
+ _assert_wire(response, bucket="invalid bucket", key=key)
+
+
[email protected]("key", ["probe.txt", ""])
[email protected]("virtual", [False, True])
[email protected]("denial", ["implicit", "explicit"])
+def test_head_still_enforces_iam(head_bucket, iam_user, auth_enabled, key, virtual, denial):
+ policy = {"Statement": [{"Effect": "Deny", "Action": ["s3:GetObject", "s3:ListBucket"], "Resource": "*"}]}
+ client = iam_user(policy=policy if denial == "explicit" else None).client("s3", region=HOME)
+ response = _head(head_bucket, client, key=key, virtual=virtual)
+ assert response[0] == (403 if auth_enabled else 200)
+ if auth_enabled:
+ _assert_wire(response, bucket=head_bucket, key=key, expected_region=HOME if not key else None)
+
+
[email protected]("key", ["probe.txt", ""])
[email protected]("virtual", [False, True])
+def test_head_reserved_root_compatibility(head_bucket, s3, auth_enabled, key, virtual):
+ response = _head(head_bucket, s3, key=key, virtual=virtual, root=True)
+ assert response[0] == 200
+ if auth_enabled:
+ _assert_wire(response, bucket=head_bucket, key=key, expected_region=HOME if not key else None)
+
+
[email protected]("key", ["probe.txt", ""])
[email protected]("virtual", [False, True])
+def test_head_does_not_grant_foreign_bucket_access(iam_user, auth_enabled, key, virtual):
+ owner = boto3.client("s3", endpoint_url=ENDPOINT, region_name=HOME,
+ aws_access_key_id="333333333333", aws_secret_access_key="root-secret")
+ bucket = f"foreign-head-{uuid.uuid4().hex}"
+ owner.create_bucket(Bucket=bucket, CreateBucketConfiguration={"LocationConstraint": HOME})
+ owner.put_object(Bucket=bucket, Key="probe.txt", Body=PAYLOAD)
+ client = iam_user(policy={"Statement": [{"Effect": "Allow", "Action": "s3:*", "Resource": "*"}]}).client("s3")
+ try:
+ response = _head(bucket, client, key=key, virtual=virtual)
+ assert response[0] == 403
+ if auth_enabled:
+ _assert_wire(response, bucket=bucket, key=key, expected_region=HOME if not key else None)
+ finally:
+ owner.delete_object(Bucket=bucket, Key="probe.txt")
+ owner.delete_bucket(Bucket=bucket)
+ owner.close()
+
+
[email protected]("virtual", [False, True])
+def test_head_version_query_keeps_iam_path(head_bucket, iam_user, auth_enabled, virtual):
+ client = iam_user().client("s3", region=HOME)
+ response = _head(f"missing-{head_bucket}", client, virtual=virtual, query="?versionId=null")
+ assert response[0] == (403 if auth_enabled else 404)
+
+
[email protected]("virtual", [False, True])
[email protected]("credential", ["valid", "wrong-secret"])
+def test_head_presigned_validation_is_preserved(head_bucket, head_client, s3, virtual, credential):
+ response = _head(head_bucket, head_client, virtual=virtual, credential=credential, presigned=True)
+ assert response[0] == (200 if credential == "valid" else 403)
+ assert response[2] == b""
+ if credential == "valid":
+ assert response[1]["content-length"] == str(len(PAYLOAD))
+ assert response[1]["content-type"] == "text/plain"
+ with s3.get_object(Bucket=head_bucket, Key="probe.txt")["Body"] as body:
+ assert body.read() == PAYLOAD
+
+
[email protected]("virtual", [False, True])
+def test_head_conditional_metadata(head_bucket, head_client, auth_enabled, virtual):
+ response = _head(head_bucket, head_client, virtual=virtual)
+ assert response[0] == 200
+ assert response[1]["content-length"] == str(len(PAYLOAD))
+ assert response[2] == b""
+ etag = response[1]["etag"]
+ response = _head(head_bucket, head_client, virtual=virtual, extra_headers={"If-None-Match": etag})
+ assert response[0] == 304
+ assert response[2] == b""
+ if auth_enabled:
+ assert "content-length" not in response[1]
+ assert "content-type" not in response[1]
+ response = _head(head_bucket, head_client, virtual=virtual, extra_headers={"If-Match": '"incorrect"'})
+ assert response[0] == 412
+ if auth_enabled:
+ _assert_wire(response, bucket=head_bucket, key="probe.txt")