hyperbrowser 1.14.0__tar.gz → 1.15.0__tar.gz

{hyperbrowser-1.14.0 → hyperbrowser-1.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperbrowser
-Version: 1.14.0
+Version: 1.15.0
 Summary: Python SDK for hyperbrowser
 License: MIT
 License-File: LICENSE
@@ -268,7 +268,9 @@ Things to know:
 - Attaching secrets needs an API key with `secrets.use`; filling also needs
   `browser.sessions.update`. The team needs the secrets feature. Sessions with
   credentials run as Firecracker browsers with Chrome's password manager off.
-  A vault attaches the secrets its entries hold when the session is created.
+  A vault is attached by reference, so each fill uses the secrets its entries
+  name at that moment; `session.vaults` lists the attached vaults as `id` and
+  `name`.
 - Fills are recorded in the session's event log as `credential_filled` and
   `credential_fill_refused`. Their metadata names the `credential` or `vault`;
   for 1Password fills, `onePasswordToken` (the op_token's name) and its
@@ -282,9 +284,12 @@ Things to know:
     (409) is the same for frames.
   - `CREDENTIAL_ORIGIN_NOT_ALLOWED` (403): the page's origin (in `details`)
     isn't allowed; nothing was typed.
-  - `CREDENTIAL_NOT_ATTACHED` (403): the secret (or a 1Password fill's
-    op_token) wasn't attached when the session was created, or a vault entry
-    now points at another secret.
+  - `CREDENTIAL_NOT_ATTACHED` (403): the secret, vault or 1Password fill's
+    op_token wasn't attached to the session, directly or as an entry of an
+    attached vault.
+  - `SECRET_REQUIRES_CUSTOMER_UNWRAP` (400): a customer-protected secret
+    can't be typed into a page (see
+    [Customer-protected secrets](#customer-protected-secrets)).
   - `CREDENTIAL_NOT_READY` (409): the secret has no allowed origins or no
     value.
   - `SECRET_TYPE_MISMATCH` (409): an `op_token` can't be attached or filled
@@ -857,6 +862,105 @@ Things to know:
     `SECRET_ONEPASSWORD_FAILED` (502/503) are retryable.
   - `retryable` is the API's flag when it sends one.
 
+### Customer-protected secrets
+
+A secret created with `protection="customer"` is also wrapped with your own
+key, so the platform stores nothing it can open alone. Each version is sealed
+to the platform key as usual, then wrapped locally with your key. To use one,
+unwrap it locally and pass the result. Only the platform can open the
+unwrapped envelope, and it checks that the envelope belongs to the version
+you pinned.
+
+```python
+import os
+
+from hyperbrowser import Hyperbrowser, create_customer_key
+
+client = Hyperbrowser()
+
+# RSA (2048 bits or more), EC P-256/P-384/P-521, X25519 or X448: a
+# cryptography key object, PEM/DER or a JWK dict. A public key can wrap;
+# unwrapping needs the private key.
+customer_key = create_customer_key(os.environ["HB_CUSTOMER_KEY_PEM"])
+
+client.secrets.create({"name": "db-pass", "value": "hunter2", "customer_key": customer_key})
+client.secrets.add_version("db-pass", "hunter3", customer_key=customer_key)
+
+# A reference pinned to the version unwrapped: name, version and unwrapped.
+db_pass = client.secrets.unwrap("db-pass", customer_key)
+sandbox = client.sandboxes.create({"image_name": "my-image", "secrets": {"DB_PASS": db_pass}})
+sandbox.exec("python migrate.py", secrets={"DB_PASS": db_pass})
+
+# A vault's customer-protected entries, unwrapped together. Its other entries
+# are delivered as usual.
+app_env = client.vaults.unwrap("app-env", customer_key)
+sandbox.processes.start("python worker.py", vault=app_env)
+
+# A customer-protected op_token, for sandboxes and 1Password fills.
+token = client.secrets.unwrap("op-token", customer_key)
+sandbox.exec(
+    "python app.py",
+    one_password={
+        "token": token,
+        "vault": "Engineering",
+        "fields": {"DB_PASS": {"item": "Postgres", "field": "password"}},
+    },
+)
+```
+
+- `protection` is `"platform"` (the default) or `"customer"`, and is fixed when
+  the secret is created. Passing `customer_key` to `create` implies
+  `"customer"`. Creating one without a value gives an empty secret; add its
+  first version with `add_version(secret, value, customer_key=...)`.
+- The key's `kid` is its RFC 7638 thumbprint unless the JWK has a `kid` or you
+  pass `create_customer_key(key, kid=...)`. RSA keys wrap with `RSA-OAEP-256`.
+  EC and OKP keys default to `ECDH-ES+A256KW`; pass `algorithm="ECDH-ES"` for
+  direct key agreement. To keep the private key in a KMS or HSM, implement the
+  `CustomerKey` protocol yourself: `kid`, `wrap(inner_envelope,
+  encryption_context)` and `unwrap(wrapped_envelope)` produce and open a
+  compact JWE with protected header `{"alg", "enc": "A256GCM", "kid", "ctx"}`.
+  `ctx` must be the secret's `encryption_context`. With `AsyncHyperbrowser`,
+  either method may be a coroutine; the sync client refuses one.
+- `unwrap(secret, keys, version=...)` unwraps the latest version by default.
+  `vaults.unwrap(vault, keys)` unwraps the versions the vault's entries
+  resolve to now. Both take a list of keys, such as during a rotation, and use
+  the one whose `kid` wrapped each version (`customer_key_mismatch` if none
+  did). The unwrapped envelope is checked against the version's
+  `inner_digest` locally, and again by the API.
+- An unwrapped reference must pin a number, never `"latest"`. A vault
+  reference is refused with `SECRET_VAULT_CHANGED` when an entry was repointed
+  or moved to a newer version since it was unwrapped; unwrap it again.
+- Customer-protected secrets can't be typed into browser pages, including as
+  vault entries in a fill (`SECRET_REQUIRES_CUSTOMER_UNWRAP`). A
+  customer-protected `op_token` can still sign 1Password fills: pass the
+  unwrapped reference as `one_password`'s `token`.
+- Rotate your key with `rewrap(secret, from_key=..., to_key=...)`. It unwraps
+  each version still wrapped with another key and rewraps it with `to_key`,
+  all locally; the value and the version numbers don't change. It skips
+  versions already wrapped with `to_key`, so an interrupted rotation resumes
+  where it stopped. `get_wrapped_version` and `replace_version_wrapping` are
+  the single-version steps, for wrapping done elsewhere.
+- Version details include `outer_kid`, the customer key that wrapped them, and
+  `retires_at`. A version whose platform key is retired is refused with
+  `SECRET_KEY_RETIRED`: add a new version.
+- Fetching wrapped versions needs `secrets.use`, and rewrapping needs
+  `secrets.manage`. Signed-in users must be team owners or admins.
+- Error codes from the API:
+  - `SECRET_REQUIRES_CUSTOMER_UNWRAP` (400): a customer-protected secret was
+    used without its unwrapped envelope, unwrapped with `"latest"` instead of a
+    pinned version, or used where it can't be (a fill).
+  - `SECRET_PROTECTION_MISMATCH` (400): an unwrapped envelope for a secret
+    that isn't customer-protected, or a version uploaded in the other
+    protection's form.
+  - `SECRET_DIGEST_MISMATCH` (409): the unwrapped envelope (or a rewrap's
+    `inner_digest`) doesn't match the version.
+  - `SECRET_VERSION_DUPLICATE` (409): another version already holds this
+    inner envelope; rewrap that version instead.
+  - `SECRET_VAULT_CHANGED` (409): a vault entry resolves to another secret or
+    version than the one unwrapped; unwrap the vault again.
+  - `SECRET_KEY_RETIRED` (409): the version was sealed to a retired platform
+    key; add a new version.
+
 ### List sandboxes with filters
 
 ```python

{hyperbrowser-1.14.0 → hyperbrowser-1.15.0}/README.md

@@ -239,7 +239,9 @@ Things to know:
 - Attaching secrets needs an API key with `secrets.use`; filling also needs
   `browser.sessions.update`. The team needs the secrets feature. Sessions with
   credentials run as Firecracker browsers with Chrome's password manager off.
-  A vault attaches the secrets its entries hold when the session is created.
+  A vault is attached by reference, so each fill uses the secrets its entries
+  name at that moment; `session.vaults` lists the attached vaults as `id` and
+  `name`.
 - Fills are recorded in the session's event log as `credential_filled` and
   `credential_fill_refused`. Their metadata names the `credential` or `vault`;
   for 1Password fills, `onePasswordToken` (the op_token's name) and its
@@ -253,9 +255,12 @@ Things to know:
     (409) is the same for frames.
   - `CREDENTIAL_ORIGIN_NOT_ALLOWED` (403): the page's origin (in `details`)
     isn't allowed; nothing was typed.
-  - `CREDENTIAL_NOT_ATTACHED` (403): the secret (or a 1Password fill's
-    op_token) wasn't attached when the session was created, or a vault entry
-    now points at another secret.
+  - `CREDENTIAL_NOT_ATTACHED` (403): the secret, vault or 1Password fill's
+    op_token wasn't attached to the session, directly or as an entry of an
+    attached vault.
+  - `SECRET_REQUIRES_CUSTOMER_UNWRAP` (400): a customer-protected secret
+    can't be typed into a page (see
+    [Customer-protected secrets](#customer-protected-secrets)).
   - `CREDENTIAL_NOT_READY` (409): the secret has no allowed origins or no
     value.
   - `SECRET_TYPE_MISMATCH` (409): an `op_token` can't be attached or filled
@@ -828,6 +833,105 @@ Things to know:
     `SECRET_ONEPASSWORD_FAILED` (502/503) are retryable.
   - `retryable` is the API's flag when it sends one.
 
+### Customer-protected secrets
+
+A secret created with `protection="customer"` is also wrapped with your own
+key, so the platform stores nothing it can open alone. Each version is sealed
+to the platform key as usual, then wrapped locally with your key. To use one,
+unwrap it locally and pass the result. Only the platform can open the
+unwrapped envelope, and it checks that the envelope belongs to the version
+you pinned.
+
+```python
+import os
+
+from hyperbrowser import Hyperbrowser, create_customer_key
+
+client = Hyperbrowser()
+
+# RSA (2048 bits or more), EC P-256/P-384/P-521, X25519 or X448: a
+# cryptography key object, PEM/DER or a JWK dict. A public key can wrap;
+# unwrapping needs the private key.
+customer_key = create_customer_key(os.environ["HB_CUSTOMER_KEY_PEM"])
+
+client.secrets.create({"name": "db-pass", "value": "hunter2", "customer_key": customer_key})
+client.secrets.add_version("db-pass", "hunter3", customer_key=customer_key)
+
+# A reference pinned to the version unwrapped: name, version and unwrapped.
+db_pass = client.secrets.unwrap("db-pass", customer_key)
+sandbox = client.sandboxes.create({"image_name": "my-image", "secrets": {"DB_PASS": db_pass}})
+sandbox.exec("python migrate.py", secrets={"DB_PASS": db_pass})
+
+# A vault's customer-protected entries, unwrapped together. Its other entries
+# are delivered as usual.
+app_env = client.vaults.unwrap("app-env", customer_key)
+sandbox.processes.start("python worker.py", vault=app_env)
+
+# A customer-protected op_token, for sandboxes and 1Password fills.
+token = client.secrets.unwrap("op-token", customer_key)
+sandbox.exec(
+    "python app.py",
+    one_password={
+        "token": token,
+        "vault": "Engineering",
+        "fields": {"DB_PASS": {"item": "Postgres", "field": "password"}},
+    },
+)
+```
+
+- `protection` is `"platform"` (the default) or `"customer"`, and is fixed when
+  the secret is created. Passing `customer_key` to `create` implies
+  `"customer"`. Creating one without a value gives an empty secret; add its
+  first version with `add_version(secret, value, customer_key=...)`.
+- The key's `kid` is its RFC 7638 thumbprint unless the JWK has a `kid` or you
+  pass `create_customer_key(key, kid=...)`. RSA keys wrap with `RSA-OAEP-256`.
+  EC and OKP keys default to `ECDH-ES+A256KW`; pass `algorithm="ECDH-ES"` for
+  direct key agreement. To keep the private key in a KMS or HSM, implement the
+  `CustomerKey` protocol yourself: `kid`, `wrap(inner_envelope,
+  encryption_context)` and `unwrap(wrapped_envelope)` produce and open a
+  compact JWE with protected header `{"alg", "enc": "A256GCM", "kid", "ctx"}`.
+  `ctx` must be the secret's `encryption_context`. With `AsyncHyperbrowser`,
+  either method may be a coroutine; the sync client refuses one.
+- `unwrap(secret, keys, version=...)` unwraps the latest version by default.
+  `vaults.unwrap(vault, keys)` unwraps the versions the vault's entries
+  resolve to now. Both take a list of keys, such as during a rotation, and use
+  the one whose `kid` wrapped each version (`customer_key_mismatch` if none
+  did). The unwrapped envelope is checked against the version's
+  `inner_digest` locally, and again by the API.
+- An unwrapped reference must pin a number, never `"latest"`. A vault
+  reference is refused with `SECRET_VAULT_CHANGED` when an entry was repointed
+  or moved to a newer version since it was unwrapped; unwrap it again.
+- Customer-protected secrets can't be typed into browser pages, including as
+  vault entries in a fill (`SECRET_REQUIRES_CUSTOMER_UNWRAP`). A
+  customer-protected `op_token` can still sign 1Password fills: pass the
+  unwrapped reference as `one_password`'s `token`.
+- Rotate your key with `rewrap(secret, from_key=..., to_key=...)`. It unwraps
+  each version still wrapped with another key and rewraps it with `to_key`,
+  all locally; the value and the version numbers don't change. It skips
+  versions already wrapped with `to_key`, so an interrupted rotation resumes
+  where it stopped. `get_wrapped_version` and `replace_version_wrapping` are
+  the single-version steps, for wrapping done elsewhere.
+- Version details include `outer_kid`, the customer key that wrapped them, and
+  `retires_at`. A version whose platform key is retired is refused with
+  `SECRET_KEY_RETIRED`: add a new version.
+- Fetching wrapped versions needs `secrets.use`, and rewrapping needs
+  `secrets.manage`. Signed-in users must be team owners or admins.
+- Error codes from the API:
+  - `SECRET_REQUIRES_CUSTOMER_UNWRAP` (400): a customer-protected secret was
+    used without its unwrapped envelope, unwrapped with `"latest"` instead of a
+    pinned version, or used where it can't be (a fill).
+  - `SECRET_PROTECTION_MISMATCH` (400): an unwrapped envelope for a secret
+    that isn't customer-protected, or a version uploaded in the other
+    protection's form.
+  - `SECRET_DIGEST_MISMATCH` (409): the unwrapped envelope (or a rewrap's
+    `inner_digest`) doesn't match the version.
+  - `SECRET_VERSION_DUPLICATE` (409): another version already holds this
+    inner envelope; rewrap that version instead.
+  - `SECRET_VAULT_CHANGED` (409): a vault entry resolves to another secret or
+    version than the one unwrapped; unwrap the vault again.
+  - `SECRET_KEY_RETIRED` (409): the version was sealed to a retired platform
+    key; add a new version.
+
 ### List sandboxes with filters
 
 ```python

hyperbrowser-1.15.0/hyperbrowser/__init__.py

@@ -0,0 +1,13 @@
+from .client.sync import Hyperbrowser
+from .client.async_client import AsyncHyperbrowser
+from .config import ClientConfig
+from .customer_key import CustomerKey, create_customer_key, secret_envelope_digest
+
+__all__ = [
+    "Hyperbrowser",
+    "AsyncHyperbrowser",
+    "ClientConfig",
+    "CustomerKey",
+    "create_customer_key",
+    "secret_envelope_digest",
+]

{hyperbrowser-1.14.0 → hyperbrowser-1.15.0}/hyperbrowser/client/managers/async_manager/sandbox.py

@@ -81,6 +81,7 @@ from ..sandboxes.image_resolution import (
 )
 from ..sandboxes.shared import (
     OnePasswordSourceInput,
+    VaultSourceInput,
     SecretReferences,
     _build_sandbox_exposed_url,
     _copy_model,
@@ -337,7 +338,7 @@ class SandboxHandle:
         run_as: Optional[str] = None,
         max_output_bytes: int = 64 * 1024 * 1024,
         secrets: Optional[SecretReferences] = None,
-        vault: Optional[str] = None,
+        vault: Optional[VaultSourceInput] = None,
         one_password: Optional[OnePasswordSourceInput] = None,
     ):
         """Run a command to completion.
@@ -345,6 +346,8 @@ class SandboxHandle:
         ``secrets`` maps environment variable names to stored secrets (a name,
         or ``{"name": ..., "version": N}``). ``vault`` names a vault whose
         entries become variables too; ``secrets`` win on a clash.
+        Customer-protected secrets are passed as the references
+        ``secrets.unwrap()`` and ``vaults.unwrap()`` return.
         ``one_password`` sets variables from fields of a 1Password vault
         (``{"token": op_token_secret, "vault": ..., "fields": {ENV: {"item",
         "section", "field"}}}``); those variables may come from nothing else.

{hyperbrowser-1.14.0 → hyperbrowser-1.15.0}/hyperbrowser/client/managers/async_manager/sandboxes/sandbox_processes.py

@@ -27,6 +27,7 @@ from .....types import (
 )
 from ...sandboxes.shared import (
     OnePasswordSourceInput,
+    VaultSourceInput,
     SecretReferences,
     _normalize_exec_params,
     _runtime_process_payload,
@@ -355,7 +356,7 @@ class SandboxProcessesApi:
         run_as: Optional[str] = None,
         max_output_bytes: int = DEFAULT_MAX_PROCESS_OUTPUT_BYTES,
         secrets: Optional[SecretReferences] = None,
-        vault: Optional[str] = None,
+        vault: Optional[VaultSourceInput] = None,
         one_password: Optional[OnePasswordSourceInput] = None,
     ) -> SandboxProcessResult:
         handle = await self.start(
@@ -388,7 +389,7 @@ class SandboxProcessesApi:
         run_as: Optional[str] = None,
         max_output_bytes: int = DEFAULT_MAX_PROCESS_OUTPUT_BYTES,
         secrets: Optional[SecretReferences] = None,
-        vault: Optional[str] = None,
+        vault: Optional[VaultSourceInput] = None,
         one_password: Optional[OnePasswordSourceInput] = None,
     ) -> SandboxProcessHandle:
         """Start a process.

{hyperbrowser-1.14.0 → hyperbrowser-1.15.0}/hyperbrowser/client/managers/async_manager/secret.py

@@ -1,20 +1,33 @@
 import asyncio
-from typing import Dict, Optional, Sequence, Union
+from typing import Dict, List, Literal, Optional, Sequence, Union
 
 from ..._request import coerce_request, dump_request
+from ....customer_key import (
+    CustomerKey,
+    CustomerKeys,
+    check_customer_key,
+    check_customer_keys,
+    check_unwrapped,
+    customer_key_for,
+    secret_envelope_digest,
+    async_result,
+)
 from ....exceptions import HyperbrowserError
 from ....models.secret import (
     CreateSecretParams,
+    ReplaceSecretVersionWrappingParams,
     Secret,
     SecretDeleteResult,
     SecretDetail,
     SecretListParams,
     SecretListResponse,
+    SecretReference,
     SecretsPublicKey,
     SecretVersion,
     SecretValue,
     SecretVersionDeleteResult,
     UpdateSecretParams,
+    WrappedSecretVersion,
 )
 from ....sandbox_common import (
     ensure_response_ok,
@@ -28,7 +41,11 @@ from ....secrets_common import (
     SECRET_NAME_LOOKUP_LIMIT,
     SecretsSealer,
     browser_metadata,
+    check_customer_protection,
     check_secret_version,
+    check_secret_version_or_latest,
+    create_secret_protection,
+    invalid_request,
     is_not_found,
     looks_like_secret_id,
     secret_not_found_error,
@@ -37,6 +54,9 @@ from ....secrets_common import (
     update_secret_body,
 )
 from ....types import CreateSecretParams as CreateSecretParamsDict
+from ....types import (
+    ReplaceSecretVersionWrappingParams as ReplaceSecretVersionWrappingParamsDict,
+)
 from ....types import SecretListParams as SecretListParamsDict
 from ....types import UpdateSecretParams as UpdateSecretParamsDict
 
@@ -47,6 +67,11 @@ class SecretManager:
     Values are encrypted on this machine to the platform's public key and are
     never returned by the API. Methods that take ``secret`` accept a secret's
     ID or its exact name.
+
+    A customer-protected secret's versions are also wrapped locally with your
+    own key (``create_customer_key()``, or your own ``CustomerKey``), so the
+    platform stores nothing it can open alone. Each use passes the reference
+    ``unwrap()`` returns.
     """
 
     def __init__(self, client):
@@ -80,10 +105,14 @@ class SecretManager:
         account token, which starts with ``ops_``). ``allowed_origins`` makes
         a ``secret`` or ``totp`` fillable into browser pages on those origins.
 
+        ``protection="customer"`` wraps each version with your own key as
+        well; passing ``customer_key`` implies it, and wraps the first version.
+
         The value and the public key are checked before the secret is created,
         so a bad value or an unavailable key leaves nothing behind.
         """
         normalized = coerce_request(params, CreateSecretParams)
+        protection = create_secret_protection(normalized)
         payload = None
         sealer = None
         if normalized.value is not None:
@@ -91,17 +120,16 @@ class SecretManager:
                 normalized.type or "secret", normalized.value
             )
             sealer = SecretsSealer(await self.get_public_key())
-        secret = Secret(
-            **await self._request(
-                "POST",
-                "/secrets",
-                data=normalized.model_dump(by_alias=True, exclude_none=True),
-            )
-        )
+        body = normalized.model_dump(by_alias=True, exclude_none=True)
+        if protection is not None:
+            body["protection"] = protection
+        secret = Secret(**await self._request("POST", "/secrets", data=body))
         if sealer is None or payload is None:
             return secret
         try:
-            version = await self._add_version(secret, payload, sealer)
+            version = await self._add_version(
+                secret, payload, sealer, normalized.customer_key
+            )
         except Exception as error:
             raise secret_value_not_stored_error(secret.id, secret.name, error)
         return secret.model_copy(update={"latest_version": version.version})
@@ -136,17 +164,136 @@ class SecretManager:
             secret, {"metadata": browser_metadata(allowed_origins)}
         )
 
-    async def add_version(self, secret: str, value: SecretValue) -> SecretVersion:
+    async def add_version(
+        self,
+        secret: str,
+        value: SecretValue,
+        *,
+        customer_key: Optional[CustomerKey] = None,
+    ) -> SecretVersion:
         """Encrypt ``value`` locally and store it as the secret's next version.
 
         The value is checked against the secret's type first: a ``totp``
-        secret takes a base32 seed or an ``otpauth://totp/`` URI.
+        secret takes a base32 seed or an ``otpauth://totp/`` URI. A
+        customer-protected secret's value is also wrapped with
+        ``customer_key``.
         """
         secret_payload_bytes(None, value)
+        if customer_key is not None:
+            check_customer_key(customer_key)
         resolved = (await self._resolve(secret))[0]
+        check_customer_protection(resolved, customer_key)
         payload = secret_payload_bytes(resolved.type, value)
         return await self._add_version(
-            resolved, payload, SecretsSealer(await self.get_public_key())
+            resolved, payload, SecretsSealer(await self.get_public_key()), customer_key
+        )
+
+    async def get_wrapped_version(
+        self, secret: str, version: Union[int, Literal["latest"]] = "latest"
+    ) -> WrappedSecretVersion:
+        """A customer-protected version's wrapped envelope, for unwrapping with
+        your own key. Most callers want ``unwrap()``, which also unwraps it."""
+        check_secret_version_or_latest(version)
+        secret_id = (await self._resolve(secret))[0].id
+        return await self._get_wrapped(secret_id, version)
+
+    async def unwrap(
+        self,
+        secret: str,
+        customer_key: CustomerKeys,
+        *,
+        version: Union[int, Literal["latest"]] = "latest",
+    ) -> SecretReference:
+        """Unwrap a customer-protected version locally with your own key.
+
+        Returns the reference each use passes: as a sandbox's or process's
+        ``secrets`` entry, or as a 1Password ``token``. It is pinned to the
+        version unwrapped. The unwrapped envelope is checked against the
+        digest stored with the version, and only the platform can open it.
+        ``customer_key`` may be a list, such as during a rotation; the key
+        whose ``kid`` wrapped the version is used.
+        """
+        check_secret_version_or_latest(version)
+        check_customer_keys(customer_key)
+        resolved = (await self._resolve(secret))[0]
+        wrapped = await self._get_wrapped(resolved.id, version)
+        inner = await self._unwrap(
+            wrapped,
+            customer_key,
+            f"Version {wrapped.version} of secret {resolved.name}",
+        )
+        return SecretReference(
+            name=resolved.name, version=wrapped.version, unwrapped=inner
+        )
+
+    async def rewrap(
+        self,
+        secret: str,
+        *,
+        from_key: CustomerKeys,
+        to_key: CustomerKey,
+        versions: Optional[Sequence[int]] = None,
+    ) -> List[WrappedSecretVersion]:
+        """Rewrap a customer-protected secret's versions with a new key, for
+        rotating your own key.
+
+        Each version is unwrapped with ``from_key`` and wrapped with
+        ``to_key`` locally; the value never changes and the platform never
+        sees it. Without ``versions``, every version not yet wrapped with
+        ``to_key`` is rewrapped, so an interrupted rotation can be resumed.
+        Returns the versions rewrapped.
+        """
+        check_customer_keys(from_key, "from_key")
+        check_customer_key(to_key, "to_key")
+        if versions is not None:
+            if isinstance(versions, (str, bytes)):
+                raise invalid_request("versions must be a list of version numbers")
+            for version in versions:
+                check_secret_version(version)
+        detail = await self.get(secret)
+        if detail.protection != "customer":
+            raise invalid_request(
+                f"Secret {detail.name} is not customer-protected; it has no wrapping"
+            )
+        wanted = (
+            list(versions)
+            if versions is not None
+            else [
+                item.version for item in detail.versions if item.outer_kid != to_key.kid
+            ]
+        )
+        rewrapped = []
+        for version in wanted:
+            wrapped = await self._get_wrapped(detail.id, version)
+            inner = await self._unwrap(
+                wrapped, from_key, f"Version {version} of secret {detail.name}"
+            )
+            envelope = await async_result(
+                to_key.wrap(inner, detail.encryption_context), "wrap"
+            )
+            rewrapped.append(
+                await self._replace_wrapping(
+                    detail.id, version, envelope, wrapped.inner_digest
+                )
+            )
+        return rewrapped
+
+    async def replace_version_wrapping(
+        self,
+        secret: str,
+        version: int,
+        params: Union[
+            ReplaceSecretVersionWrappingParamsDict, ReplaceSecretVersionWrappingParams
+        ],
+    ) -> WrappedSecretVersion:
+        """Replace a customer-protected version's outer envelope with one you
+        wrapped yourself. ``inner_digest`` must match the version's: only the
+        wrapping changes, never the value. ``rewrap()`` does this for you."""
+        check_secret_version(version)
+        request = coerce_request(params, ReplaceSecretVersionWrappingParams)
+        secret_id = (await self._resolve(secret))[0].id
+        return await self._replace_wrapping(
+            secret_id, version, request.envelope, request.inner_digest
         )
 
     async def delete(self, secret: str) -> SecretDeleteResult:
@@ -169,14 +316,54 @@ class SecretManager:
         return SecretVersionDeleteResult(**payload)
 
     async def _add_version(
-        self, secret: Secret, payload: bytes, sealer: SecretsSealer
+        self,
+        secret: Secret,
+        payload: bytes,
+        sealer: SecretsSealer,
+        customer_key: Optional[CustomerKey] = None,
     ) -> SecretVersion:
         # Always the context the API returned; it differs by secret type.
         envelope = sealer.seal(secret.encryption_context, payload)
+        data: Dict[str, object] = {"envelope": envelope}
+        if customer_key is not None:
+            data = {
+                "envelope": await async_result(
+                    customer_key.wrap(envelope, secret.encryption_context), "wrap"
+                ),
+                "innerDigest": secret_envelope_digest(envelope),
+                "innerKid": sealer.kid,
+            }
+        response = await self._request(
+            "POST", f"/secrets/{secret.id}/versions", data=data
+        )
+        return SecretVersion(**response)
+
+    async def _get_wrapped(
+        self, secret_id: str, version: Union[int, str]
+    ) -> WrappedSecretVersion:
+        return WrappedSecretVersion(
+            **await self._request(
+                "GET", f"/secrets/{secret_id}/versions/{version}/wrapped"
+            )
+        )
+
+    async def _replace_wrapping(
+        self, secret_id: str, version: int, envelope: str, inner_digest: str
+    ) -> WrappedSecretVersion:
         payload = await self._request(
-            "POST", f"/secrets/{secret.id}/versions", data={"envelope": envelope}
+            "PUT",
+            f"/secrets/{secret_id}/versions/{version}/wrapping",
+            data={"envelope": envelope, "innerDigest": inner_digest},
         )
-        return SecretVersion(**payload)
+        return WrappedSecretVersion(**payload)
+
+    @staticmethod
+    async def _unwrap(
+        wrapped: WrappedSecretVersion, keys: CustomerKeys, label: str
+    ) -> str:
+        key = customer_key_for(keys, wrapped.outer_kid, label)
+        inner = await async_result(key.unwrap(wrapped.envelope), "unwrap")
+        return check_unwrapped(inner, wrapped.inner_digest, label)
 
     async def _get_by_id(self, secret_id: str) -> SecretDetail:
         return SecretDetail(**await self._request("GET", f"/secrets/{secret_id}"))