seekrit 0.1.0__tar.gz

seekrit-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+/dist
+/build
+*.egg-info/
+.venv/
+.pytest_cache/

seekrit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seekrit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seekrit-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: seekrit
+Version: 0.1.0
+Summary: Read-path SDK for seekrit — resolve and decrypt secrets client-side with a service token.
+Project-URL: Homepage, https://seekrit.dev
+Project-URL: Documentation, https://seekrit.dev/docs
+Project-URL: Source, https://github.com/seekritdev/python-sdk
+Author: seekrit
+License-Expression: MIT
+License-File: LICENSE
+Keywords: encryption,secrets,secrets-manager,seekrit,zero-knowledge
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=41
+Description-Content-Type: text/markdown
+
+# seekrit — Python SDK
+
+Read-path SDK for [seekrit](https://seekrit.dev). Authenticate with a service
+token, resolve your environment, and get **decrypted** secrets — the API only
+ever returns ciphertext; decryption happens in your process.
+
+> This repo is a **read-only mirror** published from seekrit's monorepo so the
+> code that holds your token and decrypts plaintext is auditable. Don't commit
+> here — it's overwritten on each sync. Issues and PRs welcome.
+
+## Install
+
+```sh
+pip install seekrit
+```
+
+Requires Python 3.9+. The only dependency is [`cryptography`](https://cryptography.io).
+
+## Usage
+
+```python
+import seekrit
+
+client = seekrit.Client()            # token from $SEEKRIT_TOKEN
+secrets = client.resolve()           # {"DATABASE_URL": "postgres://…", …}
+
+db_url = client.get("DATABASE_URL")
+api_key = client.get("API_KEY", default="")
+```
+
+Load everything into the process environment:
+
+```python
+import os, seekrit
+seekrit.Client().into_env()          # existing os.environ vars win by default
+print(os.environ["DATABASE_URL"])
+```
+
+### Configuration
+
+| Argument | Env var | Default |
+| --- | --- | --- |
+| `token` | `SEEKRIT_TOKEN` | — (required) |
+| `api_url` | `SEEKRIT_API_URL` | `https://api.seekrit.dev` |
+| `overrides` | — | `{}` |
+| `timeout` | — | `30.0` (seconds) |
+
+A service token binds to a single app environment (plus its composed group
+slices). To pull a different environment slice of a composed group, pass
+`overrides` (the `?with=` override):
+
+```python
+seekrit.Client(overrides={"shared": "dev"}).resolve()
+```
+
+### Errors
+
+- `SeekritApiError` — non-2xx from the API; has `.status` and `.code`
+  (`"unauthorized"`, `"forbidden"`, `"not_found"`, …).
+- `SeekritCryptoError` — a token or ciphertext could not be parsed/decrypted.
+- `SeekritError` — base class (also covers network failures).
+
+The client is **fail-closed**: any resolve or decrypt failure raises rather than
+returning partial results.
+
+## Zero-knowledge
+
+`GET /v1/resolve` returns ciphertext plus a data-encryption key wrapped to your
+token's public key. This SDK recovers the token's private key, unwraps the DEK
+(ECDH P-256 → HKDF-SHA256 → AES-256-GCM), and decrypts each secret
+(AES-256-GCM, AAD-bound to `environmentId/NAME`) — the exact scheme used by the
+CLI, `seekrit run`, and every other seekrit client. See
+[seekrit.dev/docs](https://seekrit.dev/docs/concepts/encryption).
+
+## License
+
+MIT

seekrit-0.1.0/README.md

@@ -0,0 +1,77 @@
+# seekrit — Python SDK
+
+Read-path SDK for [seekrit](https://seekrit.dev). Authenticate with a service
+token, resolve your environment, and get **decrypted** secrets — the API only
+ever returns ciphertext; decryption happens in your process.
+
+> This repo is a **read-only mirror** published from seekrit's monorepo so the
+> code that holds your token and decrypts plaintext is auditable. Don't commit
+> here — it's overwritten on each sync. Issues and PRs welcome.
+
+## Install
+
+```sh
+pip install seekrit
+```
+
+Requires Python 3.9+. The only dependency is [`cryptography`](https://cryptography.io).
+
+## Usage
+
+```python
+import seekrit
+
+client = seekrit.Client()            # token from $SEEKRIT_TOKEN
+secrets = client.resolve()           # {"DATABASE_URL": "postgres://…", …}
+
+db_url = client.get("DATABASE_URL")
+api_key = client.get("API_KEY", default="")
+```
+
+Load everything into the process environment:
+
+```python
+import os, seekrit
+seekrit.Client().into_env()          # existing os.environ vars win by default
+print(os.environ["DATABASE_URL"])
+```
+
+### Configuration
+
+| Argument | Env var | Default |
+| --- | --- | --- |
+| `token` | `SEEKRIT_TOKEN` | — (required) |
+| `api_url` | `SEEKRIT_API_URL` | `https://api.seekrit.dev` |
+| `overrides` | — | `{}` |
+| `timeout` | — | `30.0` (seconds) |
+
+A service token binds to a single app environment (plus its composed group
+slices). To pull a different environment slice of a composed group, pass
+`overrides` (the `?with=` override):
+
+```python
+seekrit.Client(overrides={"shared": "dev"}).resolve()
+```
+
+### Errors
+
+- `SeekritApiError` — non-2xx from the API; has `.status` and `.code`
+  (`"unauthorized"`, `"forbidden"`, `"not_found"`, …).
+- `SeekritCryptoError` — a token or ciphertext could not be parsed/decrypted.
+- `SeekritError` — base class (also covers network failures).
+
+The client is **fail-closed**: any resolve or decrypt failure raises rather than
+returning partial results.
+
+## Zero-knowledge
+
+`GET /v1/resolve` returns ciphertext plus a data-encryption key wrapped to your
+token's public key. This SDK recovers the token's private key, unwraps the DEK
+(ECDH P-256 → HKDF-SHA256 → AES-256-GCM), and decrypts each secret
+(AES-256-GCM, AAD-bound to `environmentId/NAME`) — the exact scheme used by the
+CLI, `seekrit run`, and every other seekrit client. See
+[seekrit.dev/docs](https://seekrit.dev/docs/concepts/encryption).
+
+## License
+
+MIT

seekrit-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "seekrit"
+version = "0.1.0"
+description = "Read-path SDK for seekrit — resolve and decrypt secrets client-side with a service token."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "seekrit" }]
+keywords = ["seekrit", "secrets", "secrets-manager", "encryption", "zero-knowledge"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Security :: Cryptography",
+]
+dependencies = ["cryptography>=41"]
+
+[project.urls]
+Homepage = "https://seekrit.dev"
+Documentation = "https://seekrit.dev/docs"
+Source = "https://github.com/seekritdev/python-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/seekrit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/seekrit", "tests", "testdata", "README.md"]

seekrit-0.1.0/src/seekrit/__init__.py

@@ -0,0 +1,29 @@
+"""seekrit — read-path SDK for the zero-knowledge secrets manager.
+
+    import seekrit
+
+    client = seekrit.Client()          # reads $SEEKRIT_TOKEN
+    secrets = client.resolve()         # {"DATABASE_URL": "...", ...}
+    db = client.get("DATABASE_URL")
+
+Secrets are decrypted in-process; the API only ever sees ciphertext.
+"""
+
+from ._client import Client, DEFAULT_API_URL
+from ._crypto import TokenKey, decrypt_secret, materialize, secret_aad
+from .errors import SeekritApiError, SeekritCryptoError, SeekritError
+
+__version__ = "0.1.0"  # x-release-please-version
+
+__all__ = [
+    "Client",
+    "DEFAULT_API_URL",
+    "TokenKey",
+    "decrypt_secret",
+    "materialize",
+    "secret_aad",
+    "SeekritError",
+    "SeekritApiError",
+    "SeekritCryptoError",
+    "__version__",
+]

seekrit-0.1.0/src/seekrit/_client.py

@@ -0,0 +1,108 @@
+"""The resolve client: fetch ``GET /v1/resolve`` and decrypt it locally."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Dict, Mapping, MutableMapping, Optional
+
+from ._crypto import TokenKey, materialize
+from .errors import SeekritApiError, SeekritCryptoError, SeekritError
+
+DEFAULT_API_URL = "https://api.seekrit.dev"
+
+
+class Client:
+    """A read-only seekrit client bound to one service token.
+
+    A service token selects exactly one app environment (plus its composed
+    group slices); resolving returns the merged, decrypted secrets for it.
+
+    Args:
+        token: ``skt_...`` service token. Defaults to ``$SEEKRIT_TOKEN``.
+        api_url: API base URL. Defaults to ``$SEEKRIT_API_URL`` or
+            ``https://api.seekrit.dev``.
+        overrides: optional ``{group_slug: env_slug}`` map to pull a different
+            environment slice of a composed group (the ``?with=`` override).
+        timeout: per-request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        *,
+        api_url: Optional[str] = None,
+        overrides: Optional[Mapping[str, str]] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        token = token or os.environ.get("SEEKRIT_TOKEN")
+        if not token:
+            raise SeekritError("no service token: pass token= or set SEEKRIT_TOKEN")
+        self._token = token
+        self._key = TokenKey.parse(token)  # fail fast on a bad token
+        self._api_url = (api_url or os.environ.get("SEEKRIT_API_URL") or DEFAULT_API_URL).rstrip("/")
+        self._overrides = dict(overrides or {})
+        self._timeout = timeout
+
+    def resolve(self) -> Dict[str, str]:
+        """Fetch, decrypt, and merge; return ``{NAME: value}``."""
+        return materialize(self._fetch(), self._key)
+
+    def get(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """Return a single secret's value, or ``default`` if it is not present."""
+        return self.resolve().get(name, default)
+
+    def into_env(
+        self,
+        env: Optional[MutableMapping[str, str]] = None,
+        *,
+        override: bool = False,
+    ) -> Dict[str, str]:
+        """Load resolved secrets into ``env`` (default ``os.environ``).
+
+        By default an existing variable is left untouched (process env wins);
+        pass ``override=True`` to let resolved secrets take precedence.
+        Returns the merged secrets that were resolved.
+        """
+        target = os.environ if env is None else env
+        merged = self.resolve()
+        for name, value in merged.items():
+            if override or name not in target:
+                target[name] = value
+        return merged
+
+    # -- internal ---------------------------------------------------------
+
+    def _fetch(self) -> dict:
+        url = self._api_url + "/v1/resolve"
+        query = "&".join(f"with={g}:{e}" for g, e in sorted(self._overrides.items()))
+        if query:
+            url += "?" + query
+        request = urllib.request.Request(
+            url,
+            method="GET",
+            headers={"authorization": f"Bearer {self._token}", "accept": "application/json"},
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                return json.loads(response.read())
+        except urllib.error.HTTPError as exc:
+            raise self._api_error(exc.code, exc.read()) from exc
+        except urllib.error.URLError as exc:
+            raise SeekritError(f"resolve request failed: {exc.reason}") from exc
+
+    @staticmethod
+    def _api_error(status: int, body: bytes) -> SeekritApiError:
+        code, message = "internal", f"HTTP {status}"
+        try:
+            error = json.loads(body).get("error", {})
+            code = error.get("code", code)
+            message = error.get("message", message)
+        except (ValueError, AttributeError):
+            pass
+        return SeekritApiError(status, code, message)
+
+
+__all__ = ["Client", "DEFAULT_API_URL", "SeekritError", "SeekritApiError", "SeekritCryptoError"]

seekrit-0.1.0/src/seekrit/_crypto.py

@@ -0,0 +1,127 @@
+"""Zero-knowledge read path, byte-compatible with ``@seekrit/crypto``.
+
+Three steps, matching ``crates/seekrit-core`` and ``packages/crypto``:
+
+1. Recover the service token's P-256 private key  (:class:`TokenKey`).
+2. Unwrap each environment DEK                     (:meth:`TokenKey.unwrap_dek`).
+3. Decrypt each secret                             (:func:`decrypt_secret`).
+
+Blob formats (all segments base64url, no padding):
+
+* token       ``skt_<id>_<pkcs8 private key>``
+* wrapped DEK ``wd1.<ephemeral pub (raw SEC1)>.<hkdf salt>.<iv>.<ciphertext||tag>``
+* secret      ``sc1.<iv>.<ciphertext||tag>``
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+from typing import Dict, List
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives.serialization import load_der_private_key
+
+from .errors import SeekritCryptoError
+
+_HKDF_INFO = b"seekrit/wrap-dek/v1"
+# Only the first two underscores are separators; the key segment may contain "_".
+_TOKEN_RE = re.compile(r"^(skt_[0-9A-Za-z]+)_([A-Za-z0-9_-]+)$")
+
+
+def _b64url_decode(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+def _split_blob(blob: str, prefix: str, segments: int) -> List[str]:
+    parts = blob.split(".")
+    if not parts or parts[0] != prefix:
+        raise SeekritCryptoError(f'expected a "{prefix}" blob, got "{parts[0] if parts else ""}"')
+    if len(parts) != segments + 1 or any(p == "" for p in parts):
+        raise SeekritCryptoError(f'malformed "{prefix}" blob')
+    return parts[1:]
+
+
+def secret_aad(environment_id: str, name: str) -> bytes:
+    """AAD binding a secret ciphertext to its environment and name."""
+    return f"{environment_id}/{name}".encode("utf-8")
+
+
+class TokenKey:
+    """The P-256 private key recovered from a ``skt_...`` service token."""
+
+    __slots__ = ("token_id", "_private_key")
+
+    def __init__(self, token_id: str, private_key: ec.EllipticCurvePrivateKey) -> None:
+        self.token_id = token_id
+        self._private_key = private_key
+
+    @classmethod
+    def parse(cls, token: str) -> "TokenKey":
+        match = _TOKEN_RE.match(token)
+        if not match:
+            raise SeekritCryptoError("not a valid seekrit service token")
+        token_id, key_b64 = match.group(1), match.group(2)
+        try:
+            key = load_der_private_key(_b64url_decode(key_b64), password=None)
+        except Exception as exc:  # noqa: BLE001 - opaque on purpose
+            raise SeekritCryptoError("service token private key is corrupted") from exc
+        if not isinstance(key, ec.EllipticCurvePrivateKey):
+            raise SeekritCryptoError("service token key is not an EC private key")
+        return cls(token_id, key)
+
+    def unwrap_dek(self, wrapped: str) -> bytes:
+        """Recover a 32-byte environment DEK from a ``wd1.`` blob."""
+        eph_b64, salt_b64, iv_b64, ct_b64 = _split_blob(wrapped, "wd1", 4)
+        try:
+            peer = ec.EllipticCurvePublicKey.from_encoded_point(
+                ec.SECP256R1(), _b64url_decode(eph_b64)
+            )
+            shared = self._private_key.exchange(ec.ECDH(), peer)
+            wrapping_key = HKDF(
+                algorithm=hashes.SHA256(),
+                length=32,
+                salt=_b64url_decode(salt_b64),
+                info=_HKDF_INFO,
+            ).derive(shared)
+            dek = AESGCM(wrapping_key).decrypt(_b64url_decode(iv_b64), _b64url_decode(ct_b64), None)
+        except (InvalidTag, ValueError) as exc:
+            raise SeekritCryptoError(
+                "DEK unwrap failed: wrong private key or tampered grant"
+            ) from exc
+        if len(dek) != 32:
+            raise SeekritCryptoError("unwrapped DEK has wrong length")
+        return dek
+
+
+def decrypt_secret(dek: bytes, blob: str, aad: bytes) -> str:
+    """Decrypt an ``sc1.`` secret ciphertext to its UTF-8 plaintext."""
+    iv_b64, ct_b64 = _split_blob(blob, "sc1", 2)
+    try:
+        plaintext = AESGCM(dek).decrypt(_b64url_decode(iv_b64), _b64url_decode(ct_b64), aad)
+    except (InvalidTag, ValueError) as exc:
+        raise SeekritCryptoError(
+            "secret decryption failed: wrong key, tampered data, or mismatched context"
+        ) from exc
+    return plaintext.decode("utf-8")
+
+
+def materialize(resolve_response: dict, key: TokenKey) -> Dict[str, str]:
+    """Decrypt every layer and merge by precedence.
+
+    ``layers`` arrive lowest precedence first (composed groups, then the app
+    environment); later layers overwrite earlier ones on a name collision.
+    """
+    merged: Dict[str, str] = {}
+    for layer in resolve_response["layers"]:
+        dek = key.unwrap_dek(layer["wrappedDek"])
+        env_id = layer["environmentId"]
+        for secret in layer["secrets"]:
+            merged[secret["name"]] = decrypt_secret(
+                dek, secret["ciphertext"], secret_aad(env_id, secret["name"])
+            )
+    return merged

seekrit-0.1.0/src/seekrit/errors.py

@@ -0,0 +1,31 @@
+"""Exception hierarchy for the seekrit SDK."""
+
+from __future__ import annotations
+
+
+class SeekritError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class SeekritCryptoError(SeekritError):
+    """A token, wrapped DEK, or secret ciphertext could not be parsed or decrypted.
+
+    Deliberately unspecific: a decrypt failure does not distinguish "wrong key"
+    from "tampered data" from "mismatched context", to avoid acting as an oracle.
+    """
+
+
+class SeekritApiError(SeekritError):
+    """The resolve API returned a non-2xx response.
+
+    Attributes:
+        status: HTTP status code.
+        code: the ``error.code`` string from the API (e.g. ``"unauthorized"``,
+            ``"forbidden"``, ``"not_found"``), or ``"internal"`` if the body did
+            not parse.
+    """
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(f"{status} {code}: {message}")
+        self.status = status
+        self.code = code

seekrit-0.1.0/testdata/vectors.json

@@ -0,0 +1,65 @@
+{
+  "token": "skt_r36AUXMxoX0xkQoH8vimHN_MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg1bTaK96XZQzEUpfGe5dlc-sp3n7mF8WpZNVJweEJZ06hRANCAATgUoWLRDgyG0qsUzdQXzr1VSL-p9kSp_zhAULqF2qHUAWDPcuoX-f4JTUX6lyzPEs_0chQ9nKvgmEJUpXx9_q5",
+  "tokenId": "skt_r36AUXMxoX0xkQoH8vimHN",
+  "publicKeyJwk": "{\"key_ops\":[],\"ext\":true,\"kty\":\"EC\",\"x\":\"4FKFi0Q4MhtKrFM3UF869VUi_qfZEqf84QFC6hdqh1A\",\"y\":\"BYM9y6hf5_glNRfqXLM8Sz_RyFD2cq-CYQlSlfH3-rk\",\"crv\":\"P-256\"}",
+  "resolve": {
+    "scope": {
+      "orgId": "org_test",
+      "orgSlug": "acme",
+      "appId": "app_test",
+      "appSlug": "web",
+      "envId": "env_apptest0000000000001",
+      "envSlug": "production"
+    },
+    "layers": [
+      {
+        "source": "group",
+        "environmentId": "env_grouptest0000000001",
+        "slug": "production",
+        "groupSlug": "shared",
+        "wrappedDek": "wd1.BEoGSn3SoICO6tA13EjveZHvxTTRVijE0OUpBkzVkFU28q_jfgY4P9IkyrpjMVJK27zogh61rwC_NUBjoe2TKhY.5EI1On9xCtVuntRHMA6xFA.JNqiqNRxDpNN3hkP.8RxEujnGaEIUIVq9VVcOZlpC07-gxgyz25VCtffNZWSRh8J8iFfMA6p-_ubXSfv5",
+        "secrets": [
+          {
+            "name": "SHARED",
+            "ciphertext": "sc1.4XNyaS_ilRPDTlIg.LhAGzqP_cm4fx_dKeST8_3NITle_77x0Qjo"
+          },
+          {
+            "name": "DATABASE_URL",
+            "ciphertext": "sc1.-THIwVQA7yVq6SWt.1RaVPddl8QDuhc2wValcmtArCxafHBCAk24Fv00gB_FNc6k"
+          },
+          {
+            "name": "UNICODE",
+            "ciphertext": "sc1.7qB3RU8qhHKpqwbB.BsKeZYWDv4Qp9cWIB0I684pLazslk2nFtIq-OvgDjIaTaw3Pbw"
+          }
+        ]
+      },
+      {
+        "source": "app",
+        "environmentId": "env_apptest0000000000001",
+        "slug": "production",
+        "wrappedDek": "wd1.BMywXqAVq3Ee3XX7mGBt2KLcRRwPLQn9FjlXc19Z8HNdDPsg-KyKLwg_uz4tgQ8MdVevMgtjfBkOiqmAi7ENI2Y.FLBNZ3z8-8CnYoBN-Azr9g.2x8wkp6BSw9QjnG2.3b32qenHIHC92eCehRW6QGWNFTlIe3nTKPje0WsRFWSHkjV6PYIxCXmlQaAJJkp3",
+        "secrets": [
+          {
+            "name": "SHARED",
+            "ciphertext": "sc1.QF697pJ61KM9Xqj2.HH9PNlW7aIIWZvpLm6yc8ZCRRemlxoOS"
+          },
+          {
+            "name": "API_KEY",
+            "ciphertext": "sc1.x4G_KqJP7ags8SBf.obw89lhKqcMAy1vzjdTjch88R7Trx9JtFWS2Rw"
+          },
+          {
+            "name": "EMPTY",
+            "ciphertext": "sc1.qdub6o6QejpKH97e.KFe1fiDvtHF3agstKhL5ng"
+          }
+        ]
+      }
+    ]
+  },
+  "expectedManagedValues": {
+    "SHARED": "from-app",
+    "DATABASE_URL": "postgres://group/db",
+    "UNICODE": "héllo-🌍-\n-tab\tend",
+    "API_KEY": "sk-app-12345",
+    "EMPTY": ""
+  }
+}

seekrit-0.1.0/tests/test_vectors.py

@@ -0,0 +1,60 @@
+"""Cross-implementation parity: decrypt the shared golden vectors and assert we
+recover exactly what the canonical @seekrit/crypto (WebCrypto) produced.
+
+Runnable with either ``pytest`` or ``python -m unittest``.
+"""
+
+import base64
+import json
+import unittest
+from pathlib import Path
+
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+)
+
+import seekrit
+from seekrit import SeekritCryptoError
+
+VECTORS = json.loads((Path(__file__).parent.parent / "testdata" / "vectors.json").read_text())
+
+
+def _make_valid_but_different_token() -> str:
+    """A well-formed token carrying a freshly generated (wrong) P-256 key."""
+    pkcs8 = ec.generate_private_key(ec.SECP256R1()).private_bytes(
+        Encoding.DER, PrivateFormat.PKCS8, NoEncryption()
+    )
+    key_b64 = base64.urlsafe_b64encode(pkcs8).rstrip(b"=").decode("ascii")
+    return "skt_AAAAAAAAAAAAAAAAAAAAAA_" + key_b64
+
+
+class VectorTest(unittest.TestCase):
+    def test_materialize_matches_expected(self):
+        key = seekrit.TokenKey.parse(VECTORS["token"])
+        merged = seekrit.materialize(VECTORS["resolve"], key)
+        self.assertEqual(merged, VECTORS["expectedManagedValues"])
+
+    def test_app_layer_wins_over_group(self):
+        key = seekrit.TokenKey.parse(VECTORS["token"])
+        merged = seekrit.materialize(VECTORS["resolve"], key)
+        self.assertEqual(merged["SHARED"], "from-app")
+
+    def test_unicode_and_empty_round_trip(self):
+        key = seekrit.TokenKey.parse(VECTORS["token"])
+        merged = seekrit.materialize(VECTORS["resolve"], key)
+        self.assertEqual(merged["UNICODE"], "héllo-🌍-\n-tab\tend")
+        self.assertEqual(merged["EMPTY"], "")
+
+    def test_wrong_token_cannot_unwrap(self):
+        # A valid, well-formed token holding the wrong key must not silently
+        # succeed — the DEK grant was wrapped to a different public key.
+        key = seekrit.TokenKey.parse(_make_valid_but_different_token())
+        with self.assertRaises(SeekritCryptoError):
+            seekrit.materialize(VECTORS["resolve"], key)
+
+
+if __name__ == "__main__":
+    unittest.main()