021-python-clients 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

{021_python_clients-0.1.0.dist-info → 021_python_clients-0.2.0.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: 021-python-clients
-Version: 0.1.0
-Summary: Observed clients for Redis, SQS, QStash, S3, HTTP, email and KMS, built on 021-python-observability
+Version: 0.2.0
+Summary: Observed clients for Redis, SQS, QStash, S3, Vercel Blob, HTTP, email and KMS, built on 021-python-observability
 Project-URL: Repository, https://github.com/from021-io/python-clients
 Project-URL: Changelog, https://github.com/from021-io/python-clients/blob/main/CHANGELOG.md
 Project-URL: Contract, https://github.com/from021-io/python-clients/blob/main/CONTRACT.md
@@ -29,6 +29,9 @@ Provides-Extra: httpx2
 Requires-Dist: httpx2<3,>=2; extra == 'httpx2'
 Provides-Extra: redis
 Requires-Dist: redis<9,>=6; extra == 'redis'
+Provides-Extra: vercel-blob
+Requires-Dist: httpx2<3,>=2; extra == 'vercel-blob'
+Requires-Dist: vercel-blob<0.6,>=0.5; extra == 'vercel-blob'
 Description-Content-Type: text/markdown
 
 # 021-python-clients
@@ -40,20 +43,21 @@ dependency call gets the same span, the same metrics under a stable dependency n
 the same failure type.
 
 ```bash
-uv add "021-python-clients[redis,aws,httpx2]"   # pick the extras you use
+uv add "021-python-clients[redis,aws,httpx2,vercel-blob]"   # pick the extras you use
 ```
 
 | Module | Extra | What it gives |
 | --- | --- | --- |
 | `clients_021.http` | none | `HttpClient`: one httpx client per dependency, timeouts, retries on idempotent methods |
 | `clients_021.httpx2` | `httpx2` | `ObservedTransport` for SDKs built on httpx2 (Anthropic, OpenAI) |
-| `clients_021.redis` | `redis` | `RedisClient`: JSON with TTL, one-time reads, windowed counters, ping |
+| `clients_021.cache.redis` | `redis` | `RedisClient`: JSON with TTL, one-time reads, windowed counters, ping |
 | `clients_021.queue.qstash` | none | `QStashClient`: JSON publishing, deduplication, delivery options and forwarded trace context |
 | `clients_021.queue.sqs` | `aws` | `SqsClient`: send, receive, delete, visibility, trace carried in the message |
-| `clients_021.s3` | `aws` | `S3Client`: put, get, head, delete, presigned URLs |
+| `clients_021.storage.s3` | `aws` | `S3Client`: put, get, head, delete, presigned URLs |
+| `clients_021.storage.vercel_blob` | `vercel-blob` | `VercelBlobClient`: put, get, head and conditional delete for public/private stores |
 | `clients_021.email` | none | `EmailMessage`, the `EmailSender` protocol, `ResendSender` (Resend's HTTP API) |
 | `clients_021.email.ses` | `aws` | `SesSender`: the same protocol over Amazon SES v2 |
-| `clients_021.kms` | `aws` | `KmsClient`: encrypt, decrypt and data keys bound to an encryption context; AES-256-GCM envelopes |
+| `clients_021.crypto.kms` | `aws` | `KmsClient`: encrypt, decrypt and data keys bound to an encryption context; AES-256-GCM envelopes |
 
 Every client takes the service's `Observability` (from `setup_observability`) and a
 `dependency` name, which becomes the `dependency` label of its metrics.
@@ -61,11 +65,16 @@ Every client takes the service's `Observability` (from `setup_observability`) an
 ## Organization
 
 Providers with the same purpose live under one capability package: `email/` contains
-Resend and SES; `queue/` contains SQS and QStash. Import queue clients explicitly:
+Resend and SES; `queue/` contains SQS and QStash; `storage/` contains S3 and Vercel Blob; `cache/`
+contains Redis; `crypto/` contains KMS. HTTP transports remain at the root. Import providers
+explicitly:
 
 ```python
 from clients_021.queue.sqs import SqsClient
 from clients_021.queue.qstash import QStashClient
+from clients_021.storage.s3 import S3Client
+from clients_021.cache.redis import RedisClient
+from clients_021.crypto.kms import KmsClient
 ```
 
 SQS supports polling, receipts and visibility changes; QStash delivers to an HTTP endpoint.
@@ -74,16 +83,20 @@ because both implement the same send operation. A shared package does not imply
 provider implements an interchangeable consumption protocol. Importing `queue` or QStash
 does not load the optional AWS SDK.
 
+The 0.1.0 imports `clients_021.redis`, `clients_021.s3` and `clients_021.kms` remain
+compatible aliases for the same classes and result types. Importing a capability package
+does not load its optional SDKs.
+
 ## What every call gets
 
 - A CLIENT span named `<dependency> <operation>` (`HTTP <dependency>` for HTTP), with the
   system attribute (`db.system.name=redis`, `messaging.system=aws_sqs|resend|aws_ses`,
-  `rpc.service=S3|KMS`).
+  `rpc.service=S3|KMS`, `rpc.system=vercel-blob`).
 - A counter and a duration histogram: `db.client.operation.*` (Redis, shared with SQL),
-  `messaging.client.operation.*` (SQS, QStash, email), `storage.client.operation.*` (S3),
+  `messaging.client.operation.*` (SQS, QStash, email), `storage.client.operation.*` (S3, Vercel Blob),
   `crypto.client.operation.*` (KMS), `http.client.request.*` (HTTP, and the HTTP request
   under QStash and Resend). Labels are bounded; see [CONTRACT.md](CONTRACT.md).
-- Redis, SQS, QStash, S3, email and KMS emit a `dependency.call_failed` warning on failure,
+- Redis, SQS, QStash, S3, Vercel Blob, email and KMS emit a `dependency.call_failed` warning on failure,
   with dependency, operation and error type only. HTTP transports emit spans and metrics.
 - `DependencyUnavailable(dependency, operation, reason)` when the service timed out,
   refused the connection, throttled or failed with a 5xx. Map it to a 503. Errors that mean
@@ -100,8 +113,8 @@ them from a tenant, user or request. All clients apply observability's identifie
 
 ```python
 from clients_021 import DependencyUnavailable, HttpClient
-from clients_021.redis import RedisClient
-from clients_021.s3 import S3Client
+from clients_021.cache.redis import RedisClient
+from clients_021.storage.s3 import S3Client
 from clients_021.queue.sqs import SqsClient
 
 redis = RedisClient.from_url(obs, settings.redis_url)
@@ -123,6 +136,59 @@ http = HttpClient(obs, timeout_seconds=10)
 response = await http.request("GET", jwks_url, dependency="identity-provider")
 ```
 
+### Vercel Blob
+
+```python
+from clients_021.storage.vercel_blob import VercelBlobClient
+
+files = VercelBlobClient(
+    obs,
+    token=settings.blob_token,
+    store_id=settings.blob_store_id,
+    access="private",  # Required; must match the store. Public is also supported.
+    dependency="documents",
+    timeout_seconds=10,
+)
+try:
+    uploaded = await files.put("reports/report.pdf", pdf_bytes, content_type="application/pdf")
+    content = await files.get(uploaded.url)  # bytes, or None for a missing object
+    info = await files.head(uploaded.url)    # metadata, or None for a missing object
+    if info is not None:
+        await files.delete(uploaded.url, if_match=info.etag)
+finally:
+    await files.aclose()
+```
+
+Uses the [official Python Blob SDK](https://vercel.com/docs/vercel-blob/python-sdk-reference),
+`vercel-blob>=0.5,<0.6`, installed with the `vercel-blob` extra. This is the current functional
+SDK API; it does not depend on the earlier `AsyncBlobClient` API or the full `vercel` bundle.
+Credentials and store access are explicit; no environment or default SDK session is used
+for requests. A read-write token's store must match `store_id` (the `store_` prefix is allowed).
+
+`put` returns `BlobUpload` (the SDK's `PutResult`); `head` returns `BlobInfo` (its `HeadResult`).
+These are provider-specific types, not a common S3 protocol. Uploads require a pathname;
+reads, metadata and deletes accept a pathname or a Vercel delivery URL. The SDK validates
+those URLs and does not follow redirects. `get` buffers the entire body in memory.
+
+Each operation has one attempt and a finite total deadline, including body consumption.
+The client reuses its connection pool across calls and closes it through `aclose()`,
+including an injected `httpx2.AsyncBaseTransport`. Call `aclose()` only after in-flight calls
+finish. Calls after close fail locally. SDK sessions are scoped to each operation so
+concurrent clients keep their credentials separate. No trace headers are sent by default.
+
+`allow_overwrite=False` and `add_random_suffix=False` by default. Both can be explicitly
+enabled, along with `cache_control_max_age`. A timeout may follow a successful upload:
+retrying with a random suffix can create another object; overwriting a stable pathname can
+race with other writers. Deleting a missing object succeeds. `if_match` guards a delete
+against a changed ETag. CDN caches can retain deleted content briefly.
+
+429, 5xx, transport failures and deadlines become `DependencyUnavailable`. Authentication,
+missing stores, precondition failures, invalid inputs and malformed responses retain SDK
+exceptions; only a missing object becomes `None` for `get`/`head`. Cancellation propagates.
+The storage operation includes the complete request and response body; this client does
+not emit an additional HTTP metric. Signed URLs, multipart and streaming APIs stay outside
+this initial client.
+
 ### QStash
 
 ```python
@@ -207,7 +273,7 @@ The encryption context is required on every call, so a ciphertext only decrypts
 purpose it was made for:
 
 ```python
-from clients_021.kms import KmsClient
+from clients_021.crypto.kms import KmsClient
 
 keys = KmsClient.create(obs, settings.session_key_arn, region="us-east-1")
 context = {"purpose": "refresh-token", "tenant": tenant_id}
@@ -292,6 +358,8 @@ Retry policies are explicit:
   `DependencyUnavailable`; other rejected statuses and invalid acknowledgements raise
   `QStashResponseError` with a status code and no provider body. Delivery timeouts and
   delays use integer seconds and remain subject to the provider plan's limits.
+- Vercel Blob sends each operation once, with a finite total deadline (10 seconds by default).
+  An injected transport must also avoid automatic retries of uncertain writes.
 - httpx2 SDKs own their retries; `ObservedTransport` adds no extra retry loop.
 
 `DependencyUnavailable` signals a transient dependency failure, **not permission to replay

021_python_clients-0.2.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+clients_021/__init__.py,sha256=sF_9ZsxPumQbZ-9iCXoLP8JcU_tITDT6Xk1mXF9PVuQ,816
+clients_021/_aws.py,sha256=sj2kCfod-vz9J93UyeVzNVLGK3M25yipKdW15KyIkw4,1722
+clients_021/_observe.py,sha256=Xjg5Qck-e8Gt5NQHOND6nzr7DvTn46PmBdccubiD3Dk,3792
+clients_021/errors.py,sha256=GS_fN8mjr7MCOkhqPhH6LweIvQ20Vd29U-aZY8zBeJQ,972
+clients_021/http.py,sha256=-AsGLfngd-eEJnTuZEPdVBI9myYiuggmnrvjQjaMpT8,5045
+clients_021/httpx2.py,sha256=w248IcEtDZtsEDkkvj4Bpfl7MU7IJ08EHqHWhryC_3k,3880
+clients_021/kms.py,sha256=YcZXURpqIZTkjcP0fpWMD6X_adMAYwN7zAJNhUImR4s,183
+clients_021/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clients_021/redis.py,sha256=xC3tji_ldJAwaBntkZTuPhNHLIzl3F3nDzkikMrbJCc,169
+clients_021/s3.py,sha256=6Q5_1emngSB00IwvBdrmV3iAg-Q_Ndco1HGzYObL5FI,231
+clients_021/cache/__init__.py,sha256=3OyQQ-uZeghpgJvvJ2k56_t50q3CCwbAp3dBrCMMcSU,76
+clients_021/cache/redis.py,sha256=DRXCMc8MqY8KsZ50j4X4mUsd0lvvmP-UDuUD2wJXyW8,4932
+clients_021/crypto/__init__.py,sha256=qESFBPQBKcHhdFXqeJzSyEP41yveG7rFrxnpITmqlNU,77
+clients_021/crypto/kms.py,sha256=My5Xyg0bOiT9YHYWojQSszpREEh3bSYMMB26wy6fNEI,7261
+clients_021/email/__init__.py,sha256=ivmdu9hhNDwPqBn3G7uNG0Zpc3DEMnlnWBVVoVQ-fQA,790
+clients_021/email/_message.py,sha256=ulTX2cXPxSVaq_5FVF0e6glePVJ7wiO5P3M4WUWN3N0,3258
+clients_021/email/resend.py,sha256=ugENkEzw9eUlYih3BZcCVQswTF1MDikPgZyuqdapCjc,5347
+clients_021/email/ses.py,sha256=0ukHvuVE0nTU5mYWRy2EaHY5v9dUwi4GSKES93pjqBg,4668
+clients_021/queue/__init__.py,sha256=CesweOrXmX5cyU-mRvqu-4wLkNJI15zi_Lows6SPupY,338
+clients_021/queue/qstash.py,sha256=j3vz_S9-ed0YQZCaWwQg5wPwf8Bv5P1voNsx8WD8Zhc,8315
+clients_021/queue/sqs.py,sha256=jnccgbxyglzs2mR_DsH04IisEwygDlw6s3RxR0UtMTc,6693
+clients_021/storage/__init__.py,sha256=KrJViRHBK7PkIYnagg7vyXp95SzMFp9cUCKEnMeFr84,78
+clients_021/storage/s3.py,sha256=NDtG9QzHSXvrcazTYTq1EH5VjuRd2xMMsMvaumqci4Q,5946
+clients_021/storage/vercel_blob.py,sha256=FlnoKiahqtk3PpLsGpyu_Gy87otg15i4BlJZsIB3LfM,6511
+021_python_clients-0.2.0.dist-info/METADATA,sha256=gx7Jt2wjPNVFhyUHCze-tQ5YVu-Kqrt2GwAyia6HdXs,20595
+021_python_clients-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+021_python_clients-0.2.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+021_python_clients-0.2.0.dist-info/RECORD,,

clients_021/__init__.py

@@ -1,9 +1,10 @@
 """Observed clients for the external services Python services call.
 
 `clients_021.http`, `clients_021.queue.qstash` and `clients_021.email` (Resend) need no extras;
-`clients_021.redis` needs the `redis` extra; `clients_021.queue.sqs`, `clients_021.s3`,
-`clients_021.email.ses` and `clients_021.kms` the `aws` extra; `clients_021.httpx2` the
-`httpx2` extra.
+`clients_021.cache.redis` needs the `redis` extra; `clients_021.queue.sqs`,
+`clients_021.storage.s3`, `clients_021.email.ses` and `clients_021.crypto.kms` the `aws` extra;
+`clients_021.httpx2` the `httpx2` extra.
+`clients_021.storage.vercel_blob` needs the `vercel-blob` extra.
 """
 
 from importlib.metadata import version

clients_021/_observe.py

@@ -2,7 +2,7 @@
 
 The `db` family reuses the instruments 021-python-observability already creates for SQL
 (`db.client.operation.*`), so Redis and Postgres share dashboards. `messaging` (SQS, email),
-`storage` (S3) and `crypto` (KMS) get their own pair on the same meter. Attributes are
+`storage` (S3, Vercel Blob) and `crypto` (KMS) get their own pair on the same meter. Attributes are
 bounded: dependency, operation, status and error.type; never keys, URLs, bodies or ids.
 """
 

clients_021/cache/__init__.py

@@ -0,0 +1 @@
+"""Cache clients. Import providers explicitly; SDKs are optional extras."""

clients_021/cache/redis.py

@@ -0,0 +1,124 @@
+"""Redis, observed: JSON values with a TTL, one-time reads, windowed counters and a ping.
+
+    from clients_021.cache.redis import RedisClient
+
+    redis = RedisClient.from_url(obs, settings.redis_url, dependency="redis")
+    await redis.set_json("session:abc", {"user": "ana"}, ttl_seconds=1800)
+    value = await redis.get_json("session:abc")
+
+Needs the `redis` extra. Calls record `db.client.operation.*` with `dependency` and
+`operation` (`get_json`, `set_json`, `take_json`, `delete`, `incr_window`, `ping`).
+Timeouts and connection failures raise DependencyUnavailable; a wrong command or type
+(`ResponseError`) is a bug and keeps its type.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable
+from typing import Any, cast
+
+from observability_021 import Observability
+from observability_021.config import identifier
+from redis.asyncio import Redis
+from redis.exceptions import AuthenticationError, AuthorizationError
+from redis.exceptions import ConnectionError as RedisConnectionError
+from redis.exceptions import TimeoutError as RedisTimeoutError
+
+from clients_021._observe import observed
+from clients_021.errors import DependencyUnavailable
+
+SYSTEM = {"db.system.name": "redis"}
+
+
+def _classify(error: BaseException) -> str | None:
+    # Both inherit ConnectionError, but retrying cannot fix invalid credentials.
+    if isinstance(error, AuthenticationError | AuthorizationError):
+        return None
+    if isinstance(error, RedisTimeoutError):
+        return "timeout"
+    if isinstance(error, RedisConnectionError):
+        return "connection_error"
+    return None
+
+
+class RedisClient:
+    def __init__(self, obs: Observability, redis: Redis, *, dependency: str = "redis") -> None:
+        self._obs = obs
+        self._redis = redis
+        self.dependency = identifier(dependency)
+
+    @classmethod
+    def from_url(
+        cls,
+        obs: Observability,
+        url: str,
+        *,
+        dependency: str = "redis",
+        timeout_seconds: float = 1.0,
+    ) -> RedisClient:
+        # redis-py's from_url is only partially typed.
+        redis: Redis = Redis.from_url(  # pyright: ignore[reportUnknownMemberType]
+            url, socket_timeout=timeout_seconds, socket_connect_timeout=timeout_seconds
+        )
+        return cls(obs, redis, dependency=dependency)
+
+    def _observed(self, operation: str):  # noqa: ANN202 - an async context manager
+        return observed(
+            self._obs,
+            family="db",
+            system=SYSTEM,
+            dependency=self.dependency,
+            operation=operation,
+            classify=_classify,
+        )
+
+    async def get_json(self, key: str) -> Any:
+        """The decoded value, or None when the key is missing or expired."""
+        async with self._observed("get_json"):
+            raw = await self._redis.get(key)
+        return None if raw is None else json.loads(raw)
+
+    async def set_json(self, key: str, value: Any, *, ttl_seconds: int) -> None:
+        """Every value expires: there is no way to store one forever by mistake."""
+        if ttl_seconds < 1:
+            raise ValueError("ttl_seconds must be at least 1")
+        data = json.dumps(value, separators=(",", ":"))
+        async with self._observed("set_json"):
+            await self._redis.set(key, data, ex=ttl_seconds)
+
+    async def take_json(self, key: str) -> Any:
+        """Reads and deletes in one step (GETDEL): a second caller gets None."""
+        async with self._observed("take_json"):
+            raw = await cast(Awaitable[Any], self._redis.getdel(key))
+        return None if raw is None else json.loads(raw)
+
+    async def delete(self, key: str) -> None:
+        async with self._observed("delete"):
+            await self._redis.delete(key)
+
+    async def incr_window(self, key: str, *, by: int = 1, ttl_seconds: int) -> int:
+        """Adds `by` and returns the total; the key expires `ttl_seconds` after its first hit.
+
+        INCRBY and EXPIRE NX run in one transaction, so a crash between them cannot leave
+        a counter that never expires.
+        """
+        if ttl_seconds < 1:
+            raise ValueError("ttl_seconds must be at least 1")
+        async with self._observed("incr_window"), self._redis.pipeline(transaction=True) as pipe:
+            pipe.incrby(key, by)
+            pipe.expire(key, ttl_seconds, nx=True)
+            total, _ = await pipe.execute()
+        return int(total)
+
+    async def ping(self) -> bool:
+        """True when Redis answers; False (recorded as an error) when it does not."""
+        try:
+            async with self._observed("ping"):
+                # redis-py types ping() for both clients; the asyncio one returns an awaitable.
+                return bool(await self._redis.ping())  # pyright: ignore[reportUnknownMemberType]
+        except DependencyUnavailable:
+            return False
+
+    async def aclose(self) -> None:
+        await self._redis.aclose()

clients_021/crypto/__init__.py

@@ -0,0 +1 @@
+"""Crypto clients. Import providers explicitly; SDKs are optional extras."""

clients_021/crypto/kms.py

@@ -0,0 +1,178 @@
+"""AWS KMS, observed: encrypt, decrypt and data keys, always bound to an encryption context.
+
+    from clients_021.crypto.kms import KmsClient
+
+    keys = KmsClient.create(obs, settings.session_key_id, region="us-east-1")
+    context = {"purpose": "session", "tenant": tenant_id}
+    blob = await keys.encrypt(secret, context=context)
+    secret = await keys.decrypt(blob, context=context)
+    envelope = await keys.seal(large_payload, context=context)   # any size, AES-256-GCM
+    large_payload = await keys.unseal(envelope, context=context)
+
+Needs the `aws` extra. The encryption context is required: decrypting with another context
+fails, so a ciphertext only opens for the purpose it was made for. KMS logs it in CloudTrail
+in plaintext: it identifies the purpose, it is never a secret. Calls record
+`crypto.client.operation.*` with `operation` (`encrypt`, `decrypt`, `generate_data_key`) and
+a span with `rpc.service=KMS`; never key ids, contexts, plaintext or ciphertext.
+Timeouts, connection failures, throttling and 5xx raise DependencyUnavailable. Access
+denied, a disabled key, a wrong context or a tampered ciphertext (`InvalidCiphertextException`)
+and a ciphertext from another key (`IncorrectKeyException`) keep their botocore type.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import struct
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import boto3
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from observability_021 import Observability
+from observability_021.config import identifier
+
+from clients_021 import _aws
+from clients_021._observe import observed
+
+if TYPE_CHECKING:
+    from mypy_boto3_kms import KMSClient
+else:
+    KMSClient = Any
+
+SYSTEM = {"rpc.system": "aws-api", "rpc.service": "KMS"}
+# Envelope layout: version (1 byte), wrapped key length (2 bytes, big endian), wrapped key,
+# nonce (12 bytes), AES-256-GCM ciphertext and tag. The header and context are the AAD.
+_ENVELOPE = struct.Struct(">BH")
+_VERSION = 1
+_NONCE = 12
+_TAG = 16
+
+
+@dataclass(frozen=True, repr=False)
+class DataKey:
+    """A data key: use `plaintext` locally and drop it; store only `ciphertext`."""
+
+    plaintext: bytes
+    ciphertext: bytes
+
+    def __repr__(self) -> str:
+        return "DataKey(<redacted>)"
+
+
+def _context(context: Mapping[str, str]) -> dict[str, str]:
+    if not context or not all(context):
+        raise ValueError("context must be a non-empty mapping with non-empty keys")
+    return dict(context)
+
+
+def _aad(header: bytes, context: dict[str, str]) -> bytes:
+    canonical = json.dumps(context, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return header + canonical.encode()
+
+
+class KmsClient:
+    def __init__(
+        self, obs: Observability, client: KMSClient, key_id: str, *, dependency: str = "kms"
+    ) -> None:
+        if not key_id:
+            raise ValueError("key_id is required")
+        self._obs = obs
+        self._client = client
+        self._key_id = key_id
+        self.dependency = identifier(dependency)
+
+    @classmethod
+    def create(
+        cls,
+        obs: Observability,
+        key_id: str,
+        *,
+        region: str | None = None,
+        endpoint_url: str | None = None,
+        dependency: str = "kms",
+        timeout_seconds: float = 5.0,
+    ) -> KmsClient:
+        client: KMSClient = boto3.client(  # pyright: ignore[reportUnknownMemberType]
+            "kms",
+            region_name=region,
+            endpoint_url=endpoint_url,
+            config=_aws.config(
+                connect_seconds=min(timeout_seconds, 3.0), read_seconds=timeout_seconds
+            ),
+        )
+        return cls(obs, client, key_id, dependency=dependency)
+
+    def _observed(self, operation: str):  # noqa: ANN202 - an async context manager
+        return observed(
+            self._obs,
+            family="crypto",
+            system=SYSTEM,
+            dependency=self.dependency,
+            operation=operation,
+            classify=_aws.classify,
+        )
+
+    async def encrypt(self, plaintext: bytes, *, context: Mapping[str, str]) -> bytes:
+        """Up to 4096 bytes (a KMS limit); use `seal` for anything larger."""
+        encryption_context = _context(context)
+        async with self._observed("encrypt"):
+            response = await asyncio.to_thread(
+                self._client.encrypt,
+                KeyId=self._key_id,
+                Plaintext=plaintext,
+                EncryptionContext=encryption_context,
+            )
+        return response["CiphertextBlob"]
+
+    async def decrypt(self, ciphertext: bytes, *, context: Mapping[str, str]) -> bytes:
+        """Names the key, as KMS recommends: a ciphertext from another key is rejected."""
+        encryption_context = _context(context)
+        async with self._observed("decrypt"):
+            response = await asyncio.to_thread(
+                self._client.decrypt,
+                KeyId=self._key_id,
+                CiphertextBlob=ciphertext,
+                EncryptionContext=encryption_context,
+            )
+        return response["Plaintext"]
+
+    async def generate_data_key(self, *, context: Mapping[str, str]) -> DataKey:
+        """A fresh AES-256 key, in plaintext and wrapped under this client's KMS key."""
+        encryption_context = _context(context)
+        async with self._observed("generate_data_key"):
+            response = await asyncio.to_thread(
+                self._client.generate_data_key,
+                KeyId=self._key_id,
+                KeySpec="AES_256",
+                EncryptionContext=encryption_context,
+            )
+        return DataKey(response["Plaintext"], response["CiphertextBlob"])
+
+    async def seal(self, plaintext: bytes, *, context: Mapping[str, str]) -> bytes:
+        """Envelope encryption: a new data key per call (one KMS request), AES-256-GCM locally."""
+        encryption_context = _context(context)
+        key = await self.generate_data_key(context=encryption_context)
+        header = _ENVELOPE.pack(_VERSION, len(key.ciphertext)) + key.ciphertext
+        nonce = os.urandom(_NONCE)
+        sealed = AESGCM(key.plaintext).encrypt(nonce, plaintext, _aad(header, encryption_context))
+        return header + nonce + sealed
+
+    async def unseal(self, envelope: bytes, *, context: Mapping[str, str]) -> bytes:
+        """Raises ValueError for a malformed envelope, cryptography's InvalidTag if tampered."""
+        encryption_context = _context(context)
+        if len(envelope) < _ENVELOPE.size:
+            raise ValueError("not a sealed envelope")
+        version, size = _ENVELOPE.unpack_from(envelope)
+        end = _ENVELOPE.size + size
+        if version != _VERSION or size == 0 or len(envelope) < end + _NONCE + _TAG:
+            raise ValueError("not a sealed envelope")
+        key = await self.decrypt(envelope[_ENVELOPE.size : end], context=encryption_context)
+        nonce, sealed = envelope[end : end + _NONCE], envelope[end + _NONCE :]
+        return AESGCM(key).decrypt(nonce, sealed, _aad(envelope[:end], encryption_context))
+
+    async def aclose(self) -> None:
+        """Release the underlying SDK connection pools after in-flight calls finish."""
+        await asyncio.to_thread(self._client.close)