@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### New Features ✨
+
+- (py-client) Add disposition and cache-control options to object URLs and pre-signed URLs (FS-570).
+
 ## 0.2.10
 
 ### New Features ✨
 
@@ -254,6 +254,40 @@ with urllib.request.urlopen(url) as resp:
     content = resp.read()
 ```
 
+### Download response options
+
+Both `Session.object_url` and `Session.presigned_object_url` accept keyword-only
+`response_content_disposition` and `response_cache_control` options:
+
+```python
+url = session.presigned_object_url(
+    "GET",
+    "my-key",
+    response_content_disposition="inline",
+    response_cache_control="private, max-age=300",
+)
+```
+
+Disposition accepts `inline` or `attachment`, defaulting to `attachment` when omitted.
+The stored filename is retained. Cache control is passed through as an HTTP header value;
+it is not interpreted or limited by authorization expiry. A cached response can remain
+usable after the URL expires. Omitting cache control preserves the server's existing behavior.
+
+These options apply only to successful GET/HEAD responses, including ranged downloads.
+404 and other error responses retain their existing headers and caching behavior.
+Successful downloads include `X-Content-Type-Options: nosniff`; inline responses also include
+`Content-Security-Policy: sandbox` without relaxation tokens. Inline MIME types are not
+restricted by an allowlist. Sandboxing is a browser safeguard, not content sanitization,
+and does not prevent all external resource loads.
+
+The object's declared content type and compression encoding cannot be overridden.
+Content-language and expires overrides are not supported.
+
+Pre-signed URLs bind both options into the signature. JWT-bearing `object_url` URLs
+only authenticate the JWT's claims, so recipients can edit the response options.
+Existing URLs and signatures are unchanged when the options are omitted.
+Deploy server support before callers rely on these options; older servers ignore them.
+
 ## Configuration
 
 In production, store the `Client` and `Usecase` at module level and reuse them.
 
@@ -10,7 +10,7 @@
 from io import BytesIO
 from os import PathLike
 from typing import IO, Any, Literal, NamedTuple, cast
-from urllib.parse import urlparse
+from urllib.parse import quote, urlencode, urlparse
 
 import sentry_sdk
 import urllib3
@@ -52,6 +52,23 @@
 USER_AGENT = f"objectstore-client/{version('objectstore-client')}"
 
 
+def _response_options_query(
+    disposition: Literal["inline", "attachment"] | None,
+    cache_control: str | None,
+) -> str:
+    """Encode individual response options without changing legacy URLs."""
+    pairs: list[tuple[str, str]] = []
+    if disposition is not None:
+        if disposition not in ("inline", "attachment"):
+            raise ValueError(
+                f"unsupported response content disposition {disposition!r}"
+            )
+        pairs.append(("response-content-disposition", disposition))
+    if cache_control is not None:
+        pairs.append(("response-cache-control", cache_control))
+    return urlencode(pairs, quote_via=quote)
+
+
 class GetResponse(NamedTuple):
     metadata: Metadata
     payload: IO[bytes]
@@ -94,7 +111,7 @@ def __init__(
                 "usecase name must contain only ASCII letters, digits, '_' or '-'"
             )
         self._name = name
-        
+
         if resumable_threshold_bytes != "none" and (
             type(resumable_threshold_bytes) is not int or resumable_threshold_bytes < 0
         ):
@@ -709,7 +726,14 @@ def get(
             span.set_attribute("objectstore.decompressed", decompressed)
             return GetResponse(metadata, stream)
 
-    def object_url(self, key: str, token_validity: timedelta | None = None) -> str:
+    def object_url(
+        self,
+        key: str,
+        token_validity: timedelta | None = None,
+        *,
+        response_content_disposition: Literal["inline", "attachment"] | None = None,
+        response_cache_control: str | None = None,
+    ) -> str:
         """
         Generates a GET url to the object with the given `key`.
 
@@ -721,10 +745,23 @@ def object_url(self, key: str, token_validity: timedelta | None = None) -> str:
         information is embedded in the returned URL's query string, valid
         for the given duration.
 
+        Response options apply only to successful GET/HEAD responses. Disposition
+        defaults to attachment; inline responses include browser sandboxing without
+        restricting MIME types. Cache control is passed through independently of
+        authorization expiry, so cached responses can outlive the URL's validity.
+
+        These options are not bound by the JWT and can be changed by recipients.
+        Use :meth:`presigned_object_url` to bind the options to a signature.
+
         Raises ``ValueError`` if ``token_validity`` is provided but no
-        ``SecretKey`` is configured on this session.
+        ``SecretKey`` is configured on this session, or if disposition is invalid.
         """
         url = self._make_url(key, full=True)
+        query = _response_options_query(
+            response_content_disposition, response_cache_control
+        )
+        if query:
+            url = f"{url}?{query}"
         if token_validity is None:
             return url
 
@@ -734,13 +771,17 @@ def object_url(self, key: str, token_validity: timedelta | None = None) -> str:
         )
         # A JWT's compact serialization is base64url, whose alphabet is URL-safe,
         # so it can go in the query string as-is with no further encoding.
-        return f"{url}?{PARAM_AUTH}={token}"
+        separator = "&" if query else "?"
+        return f"{url}{separator}{PARAM_AUTH}={token}"
 
     def presigned_object_url(
         self,
         method: Literal["GET", "HEAD"],
         key: str,
         duration: timedelta = timedelta(hours=1),
+        *,
+        response_content_disposition: Literal["inline", "attachment"] | None = None,
+        response_cache_control: str | None = None,
     ) -> str:
         """
         Generates a pre-signed URL authorizing a single ``method`` request on the
@@ -752,12 +793,19 @@ def presigned_object_url(
 
         Raises ``ValueError`` if no ``SecretKey`` is configured on this
         session's client, if ``method`` is not supported, or if ``duration``
-        is above the one-week maximum.
+        is above the one-week maximum, or if disposition is invalid.
 
         The returned URL carries a signature that allows the recipient to perform
         a request without an auth token. It can be handed to any HTTP client;
         the URL is already percent-encoded, and must be transmitted verbatim.
 
+        Response options apply only to successful GET/HEAD responses. Disposition
+        defaults to attachment; inline responses include browser sandboxing without
+        restricting MIME types. Cache control is passed through independently of
+        authorization expiry, so cached responses can outlive the URL's validity.
+
+        Both response options are included in the signature when supplied.
+
         Note that `HEAD` and `GET` are considered equivalent from the point of view
         of signatures, meaning that a signature for `GET` can also be used for
         `HEAD`, and viceversa.
@@ -795,6 +843,12 @@ def presigned_object_url(
                 f"&{presign.PARAM_DURATION}={duration_secs}"
             )
 
+            response_query = _response_options_query(
+                response_content_disposition, response_cache_control
+            )
+            if response_query:
+                encoded_query = f"{encoded_query}&{response_query}"
+
             canonical = presign.build_canonical_form(
                 method, encoded_path, encoded_query
             )
 
@@ -1094,6 +1094,83 @@ def test_presigned_get_encoding_corner_cases(server_url: str, key: str) -> None:
     assert body == payload
 
 
+@pytest.mark.parametrize("method", ["GET", "HEAD"])
+def test_presigned_response_options(server_url: str, method: str) -> None:
+    session = _presign_session(server_url)
+    key = "inline-café/looks%20encoded&+"
+    session.put(b"<html>example</html>", key=key, content_type="text/html")
+    cache_control = 'private, max-age=3600, x="a&b=+%?#"'
+    url = session.presigned_object_url(
+        "GET",
+        key,
+        response_content_disposition="inline",
+        response_cache_control=cache_control,
+    )
+    with urllib.request.urlopen(urllib.request.Request(url, method=method)) as response:
+        assert response.status == 200
+        assert response.headers["content-disposition"] == "inline"
+        assert response.headers["cache-control"] == cache_control
+        assert response.headers["content-type"] == "text/html"
+        assert response.headers["content-security-policy"] == "sandbox"
+        assert response.headers["x-content-type-options"] == "nosniff"
+        assert response.read() == (b"" if method == "HEAD" else b"<html>example</html>")
+
+    changed_case = url.replace(
+        "response-content-disposition", "RESPONSE-CONTENT-DISPOSITION"
+    )
+    status, _ = _fetch(changed_case, method=method)
+    assert status == 200
+    for tampered in [
+        url.replace("=inline", "=attachment"),
+        url.replace("max-age%3D3600", "max-age%3D60"),
+        url.replace("response-content-disposition=inline&", ""),
+    ]:
+        status, _ = _fetch(tampered, method=method)
+        assert status == 401
+
+
+def test_jwt_response_options_remain_editable(server_url: str) -> None:
+    session = _presign_session(server_url)
+    session.put(b"example", key="jwt-options")
+    url = session.object_url(
+        "jwt-options",
+        token_validity=timedelta(minutes=5),
+        response_content_disposition="inline",
+        response_cache_control="no-store",
+    )
+    for target, expected in [
+        (url, "inline"),
+        (url.replace("=inline", "=attachment"), "attachment"),
+    ]:
+        with urllib.request.urlopen(target) as response:
+            assert response.status == 200
+            assert response.headers["content-disposition"] == expected
+            assert response.headers["cache-control"] == "no-store"
+
+
+def test_inline_preserves_stored_mime_type_and_compression(server_url: str) -> None:
+    session = Client(server_url, token=TestSecretKey.get()).session(
+        Usecase("test-usecase", compression="zstd"), org=42, project=1337
+    )
+    payload = b'<svg xmlns="http://www.w3.org/2000/svg"><script>example</script></svg>'
+    session.put(payload, key="svg-options", content_type="image/svg+xml")
+    url = session.object_url(
+        "svg-options",
+        token_validity=timedelta(minutes=5),
+        response_content_disposition="inline",
+    )
+    # Unsupported overrides cannot change the stored metadata.
+    url += "&response-content-type=text/html&response-content-encoding=gzip"
+    with urllib.request.urlopen(url) as response:
+        assert response.headers["content-type"] == "image/svg+xml"
+        assert response.headers["content-encoding"] == "zstd"
+        assert response.headers["content-security-policy"] == "sandbox"
+        with zstandard.ZstdDecompressor().stream_reader(
+            BytesIO(response.read())
+        ) as reader:
+            assert reader.read() == payload
+
+
 def test_object_url_read_only_token_succeeds(server_url: str) -> None:
     session = _presign_session(server_url)
     session.put(b"read only hello", key="read-only-url")
 
@@ -2,10 +2,17 @@
 
 import base64
 import os
+from datetime import UTC, datetime, timedelta
+from unittest.mock import patch
+from urllib.parse import parse_qs, urlsplit
 
-from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+import pytest
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
 from cryptography.hazmat.primitives.serialization import load_pem_public_key
-from objectstore_client import presign, utils
+from objectstore_client import Client, Usecase, presign, utils
 from objectstore_client.auth import SecretKey
 
 TEST_EDDSA_PRIVKEY_PATH = os.path.join(os.path.dirname(__file__), "ed25519.private.pem")
@@ -73,3 +80,96 @@ def test_sign_canonical_form_roundtrips_with_public_key() -> None:
     signature = base64.urlsafe_b64decode(signature_b64 + padding)
     assert len(signature) == 64
     public_key.verify(signature, canonical.encode())  # raises on mismatch
+
+
+@pytest.mark.parametrize("key", ["café/looks%20encoded&+", "nested/space key"])
+def test_response_options_are_encoded_and_signed(key: str) -> None:
+    with open(TEST_EDDSA_PRIVKEY_PATH) as f:
+        secret = SecretKey("test_kid", f.read())
+    session = Client("https://example.com/prefix", token=secret).session(
+        Usecase("testing"), org=1
+    )
+    cache_control = 'private, max-age=3600, x="a&b=+%?#"'
+    with patch("objectstore_client.client.datetime") as clock:
+        clock.now.return_value = datetime(2026, 4, 20, 13, 37, tzinfo=UTC)
+        legacy = session.presigned_object_url("GET", key)
+        explicit_none = session.presigned_object_url(
+            "GET", key, response_content_disposition=None, response_cache_control=None
+        )
+        url = session.presigned_object_url(
+            "GET",
+            key,
+            response_content_disposition="inline",
+            response_cache_control=cache_control,
+        )
+    assert legacy == explicit_none
+    legacy_path = utils.encode_path(f"/prefix/v1/objects/testing/org=1/{key}")
+    legacy_query = "os_kid=test_kid&os_timestamp=2026-04-20T13:37:00Z&os_duration=3600"
+    legacy_signature = secret.signature_for_canonical_form(
+        presign.build_canonical_form("GET", legacy_path, legacy_query)
+    )
+    assert (
+        legacy
+        == f"https://example.com:443{legacy_path}?{legacy_query}&os_sig={legacy_signature}"
+    )
+    parsed = urlsplit(url)
+    assert parsed.path == urlsplit(legacy).path
+    query = parse_qs(parsed.query)
+    assert query["response-content-disposition"] == ["inline"]
+    assert query["response-cache-control"] == [cache_control]
+    assert len(query) == 6
+    assert "%26" in parsed.query and "%2B" in parsed.query
+    canonical = presign.build_canonical_form("GET", parsed.path, parsed.query)
+    assert secret.signature_for_canonical_form(canonical) == query["os_sig"][0]
+    altered = parsed.query.replace("=inline", "=attachment")
+    assert (
+        secret.signature_for_canonical_form(
+            presign.build_canonical_form("GET", parsed.path, altered)
+        )
+        != query["os_sig"][0]
+    )
+
+
+def test_legacy_canonical_vector() -> None:
+    path = "/prefix/v1/objects/testing/org=1;project=2/caf%C3%A9/looks%2520encoded&+"
+    query = (
+        "unknown=b&os_sig=ignored&dup=b&&OS_KID=test&dup=a&flag"
+        "&encoded=a%26b%3D%2B&unknown=a"
+    )
+    expected = (
+        f"GET\n{path}\n"
+        "dup=a&dup=b&encoded=a%26b%3D%2B&flag&os_kid=test&unknown=a&unknown=b"
+    )
+    assert presign.build_canonical_form("HEAD", path, query) == expected
+    signature = Ed25519PrivateKey.from_private_bytes(bytes([7]) * 32).sign(
+        expected.encode()
+    )
+    assert base64.urlsafe_b64encode(signature).decode().rstrip("=") == (
+        "2_8Qv-7PKMDMd-ku1kF33Xh8aPXjLj3QaIE_nLJuaDUGxtWUDQzCiU6Uz0Mb1zgH"
+        "tfsCTB6CcQoZitooeJgmBw"
+    )
+
+
+def test_jwt_url_options_roundtrip_without_binding_token() -> None:
+    with open(TEST_EDDSA_PRIVKEY_PATH) as f:
+        secret = SecretKey("test_kid", f.read())
+    session = Client("https://example.com/prefix", token=secret).session(
+        Usecase("testing")
+    )
+    with patch.object(session, "mint_token", return_value="same.jwt.token"):
+        legacy = session.object_url("key", token_validity=timedelta(minutes=5))
+        url = session.object_url(
+            "key",
+            token_validity=timedelta(minutes=5),
+            response_content_disposition="inline",
+            response_cache_control='private, x="&=+"',
+        )
+    assert parse_qs(urlsplit(url).query) == {
+        "os_auth": ["same.jwt.token"],
+        "response-content-disposition": ["inline"],
+        "response-cache-control": ['private, x="&=+"'],
+    }
+    assert legacy.endswith("?os_auth=same.jwt.token")
+    assert session.object_url(
+        "key", response_content_disposition=None
+    ) == session.object_url("key")