aps-vault 0.41.0__tar.gz

aps_vault-0.41.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: aps-vault
+Version: 0.41.0
+Summary: Client for APS Vault machine API (service tokens), standard library only
+Author: Konstantin Zhebenev
+License: MIT
+Project-URL: Homepage, https://github.com/kzhebenev/aps-vault
+Project-URL: Documentation, https://github.com/kzhebenev/aps-vault/tree/main/docs
+Project-URL: Source, https://github.com/kzhebenev/aps-vault/tree/main/clients/python
+Project-URL: Changelog, https://github.com/kzhebenev/aps-vault/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/kzhebenev/aps-vault/issues
+Keywords: secrets,vault,secret-manager,service-token,sealed-delivery,gost,ml-kem,post-quantum
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Topic :: Security :: Cryptography
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: sealed
+Requires-Dist: cryptography>=42; extra == "sealed"
+Provides-Extra: gost
+Requires-Dist: cryptography>=42; extra == "gost"
+Requires-Dist: gostcrypto>=1.2; extra == "gost"
+Provides-Extra: pkcs11
+Requires-Dist: cryptography>=42; extra == "pkcs11"
+Requires-Dist: python-pkcs11>=0.10; extra == "pkcs11"
+Provides-Extra: pqc
+Requires-Dist: cryptography>=42; extra == "pqc"
+Requires-Dist: kyber-py>=1.2; extra == "pqc"
+
+# aps-vault (Python)
+
+Standard-library client for the APS Vault machine API. Python 3.9+, no dependencies.
+
+```bash
+pip install ./clients/python          # or: pip install aps-vault (once published)
+```
+
+```python
+import os
+from aps_vault import Vault, VaultError
+
+v = Vault("https://vault.example.com", os.environ["VAULT_TOKEN"])   # or Vault.from_env()
+try:
+    dsn_password = v.get("db-password")
+    smtp = v.get_full("smtp")            # {"name","value","login","updated_at",...}
+except VaultError as e:
+    if e.status == 404: ...
+```
+
+- `get(name)` / `get_full(name)` — cached for `cache_ttl` seconds (default 300). While the
+  vault is unreachable a stale cached value is returned (`fail_open_cache=True`), so a vault
+  restart never takes your service down; the first fetch still fails loudly.
+- `put(name, value, login=..., tags=..., url=...)` — token needs `can_write`.
+- `totp(name)` — current 6-digit code, never cached; token needs `can_read_totp`.
+- `list()`, `health()`.
+- Retries 429/5xx/network with 1 s, 2 s, 4 s back-off.
+
+Tokens: pass via environment (`VAULT_TOKEN`) or a `0600` file (`VAULT_TOKEN_FILE`). Never
+commit one, never log one. `Vault` refuses anything that does not look like a service token.
+
+## Sealed delivery (0.17)
+
+If the token is bound to this application's X25519 public key, values arrive encrypted and the
+client decrypts them in-process (needs the optional extra: `pip install 'aps-vault[sealed]'`):
+
+```bash
+python -m aps_vault keygen          # prints VAULT_CLIENT_KEY (private, keep with the token) and client_public_key (for the token)
+python -m aps_vault keygen --gost   # GOST R 34.10-2012 pair → the vault seals with VKO + Kuznyechik-MGM; needs pip install 'aps-vault[gost]'
+```
+```python
+v = Vault(url, token, client_private_key=os.environ["VAULT_CLIENT_KEY"])   # or just set VAULT_CLIENT_KEY
+v.get("db-password")
+```
+
+Without the key the client raises `VaultError("… sealed values …")` rather than returning the
+envelope; with the wrong key it says so. See `docs/SEALED.md`.

aps_vault-0.41.0/README.md

@@ -0,0 +1,47 @@
+# aps-vault (Python)
+
+Standard-library client for the APS Vault machine API. Python 3.9+, no dependencies.
+
+```bash
+pip install ./clients/python          # or: pip install aps-vault (once published)
+```
+
+```python
+import os
+from aps_vault import Vault, VaultError
+
+v = Vault("https://vault.example.com", os.environ["VAULT_TOKEN"])   # or Vault.from_env()
+try:
+    dsn_password = v.get("db-password")
+    smtp = v.get_full("smtp")            # {"name","value","login","updated_at",...}
+except VaultError as e:
+    if e.status == 404: ...
+```
+
+- `get(name)` / `get_full(name)` — cached for `cache_ttl` seconds (default 300). While the
+  vault is unreachable a stale cached value is returned (`fail_open_cache=True`), so a vault
+  restart never takes your service down; the first fetch still fails loudly.
+- `put(name, value, login=..., tags=..., url=...)` — token needs `can_write`.
+- `totp(name)` — current 6-digit code, never cached; token needs `can_read_totp`.
+- `list()`, `health()`.
+- Retries 429/5xx/network with 1 s, 2 s, 4 s back-off.
+
+Tokens: pass via environment (`VAULT_TOKEN`) or a `0600` file (`VAULT_TOKEN_FILE`). Never
+commit one, never log one. `Vault` refuses anything that does not look like a service token.
+
+## Sealed delivery (0.17)
+
+If the token is bound to this application's X25519 public key, values arrive encrypted and the
+client decrypts them in-process (needs the optional extra: `pip install 'aps-vault[sealed]'`):
+
+```bash
+python -m aps_vault keygen          # prints VAULT_CLIENT_KEY (private, keep with the token) and client_public_key (for the token)
+python -m aps_vault keygen --gost   # GOST R 34.10-2012 pair → the vault seals with VKO + Kuznyechik-MGM; needs pip install 'aps-vault[gost]'
+```
+```python
+v = Vault(url, token, client_private_key=os.environ["VAULT_CLIENT_KEY"])   # or just set VAULT_CLIENT_KEY
+v.get("db-password")
+```
+
+Without the key the client raises `VaultError("… sealed values …")` rather than returning the
+envelope; with the wrong key it says so. See `docs/SEALED.md`.

aps_vault-0.41.0/aps_vault/__init__.py

@@ -0,0 +1,504 @@
+"""APS Vault client for Python 3.9+ — standard library only.
+
+    from aps_vault import Vault
+    v = Vault("https://vault.example.com", os.environ["VAULT_TOKEN"])
+    db_password = v.get("db-password")             # str
+    full = v.get_full("db-password")               # {"name","value","login"?,"notes"?,"totp"?,"updated_at"}
+    v.put("db-password", "new-value", login="app")  # token needs can_write
+
+Sealed delivery (0.17): a token bound to this application's X25519 public key gets values
+encrypted to that key — plaintext never crosses the wire or the proxy chain. Generate a key
+pair once (``python -m aps_vault keygen``), hand the public half to the vault administrator
+for the token, keep the private half next to the token:
+
+    v = Vault(url, token, client_private_key=os.environ["VAULT_CLIENT_KEY"])   # base64 raw 32 bytes
+    v.get("db-password")                        # decrypted in this process; needs `cryptography`
+
+Behaviour:
+    * token must be a service token (``vlt_…``) — the master password never belongs in code;
+    * in-memory cache (``cache_ttl``, default 300 s; 0 disables) so a restart storm does not
+      hammer the vault, and a vault restart does not take the application down;
+    * retries with exponential back-off on 429/5xx/network errors (``max_retries``);
+    * ``fail_open_cache=True`` returns the last cached value when the vault is unreachable
+      and the entry is stale — the right trade-off for an encryption key at startup;
+    * nothing is logged; exceptions carry the HTTP status and the server's ``detail``.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Optional
+
+__version__ = "0.41.0"
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """0.37: never follow a redirect — urllib would carry the Authorization header to whatever host the answer names."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        raise urllib.error.HTTPError(req.full_url, code, f"vault: redirect to {newurl[:100]} refused", headers, fp)
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect())
+
+
+class VaultError(Exception):
+    """HTTP-level error from the vault (status + server detail)."""
+
+    def __init__(self, status: int, message: str, body: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+@dataclass
+class _Entry:
+    value: dict
+    expires_at: float
+
+
+SEALED_ALG = "X25519-HKDF-SHA256-AES256GCM"
+_SEALED_INFO = b"aps-vault/sealed/v1"
+SEALED_ALG_GOST = "VKO-GOSTR3410-2012-256-KDFTREE-KUZNYECHIK-MGM"
+_SEALED_LABEL_GOST = b"aps-vault/sealed-gost/v1"
+SEALED_ALG_P256 = "P256-HKDF-SHA256-AES256GCM"
+SEALED_ALG_PQC = "X25519MLKEM768-HKDF-SHA256-AES256GCM"      # 0.27: X25519 + ML-KEM-768 hybrid
+SEALED_ALG_GOST_PQC = "VKO-GOSTR3410-2012-256-MLKEM768-KDFTREE-KUZNYECHIK-MGM"   # 0.32: GOST + ML-KEM-768 hybrid
+_SEALED_LABEL_GOST_PQC = b"aps-vault/sealed-gost-pqc/v1"
+_SEALED_INFO_PQC = b"aps-vault/sealed-pqc/v1"
+_SEALED_INFO_P256 = b"aps-vault/sealed-p256/v1"
+
+
+class Pkcs11Key:
+    """A P-256 private key that lives in a PKCS#11 token — a TPM 2.0 through tpm2-pkcs11, an HSM,
+    a smart card, or SoftHSM2 for tests (0.22). The key never leaves the token: the client only
+    asks it for one ECDH derivation per envelope. Needs `pip install 'aps-vault[pkcs11]'`.
+
+        key = Pkcs11Key("/usr/lib/softhsm/libsofthsm2.so", token_label="node", pin="1234", key_label="vault-node")
+        Pkcs11Key.generate(...)                 # make the pair inside the token (once, at install)
+        Vault(url, token, client_private_key=key)
+    """
+
+    kind = "p256"
+
+    def __init__(self, module: str, token_label: str, pin: str, key_label: str = "aps-vault-node") -> None:
+        self.module, self.token_label, self.pin, self.key_label = module, token_label, pin, key_label
+
+    def _lib(self):
+        try:
+            import pkcs11  # noqa: F401
+        except ImportError:  # pragma: no cover
+            raise RuntimeError("vault: a PKCS#11 key needs the `python-pkcs11` package (pip install 'aps-vault[pkcs11]')") from None
+        import pkcs11
+        return pkcs11, pkcs11.lib(self.module).get_token(token_label=self.token_label)
+
+    @classmethod
+    def generate(cls, module: str, token_label: str, pin: str, key_label: str = "aps-vault-node") -> "Pkcs11Key":
+        """Create a non-extractable P-256 key pair in the token (fails if the label exists)."""
+        self = cls(module, token_label, pin, key_label)
+        pkcs11, tok = self._lib()
+        from pkcs11 import Attribute, KeyType
+        from pkcs11.util.ec import encode_named_curve_parameters
+        with tok.open(user_pin=pin, rw=True) as s:
+            try:
+                s.get_key(label=key_label, object_class=pkcs11.ObjectClass.PRIVATE_KEY)
+                raise RuntimeError(f"vault: a key labelled {key_label!r} already exists in the token")
+            except pkcs11.exceptions.NoSuchKey:
+                pass
+            s.generate_keypair(KeyType.EC, 256, public_template={Attribute.EC_PARAMS: encode_named_curve_parameters("secp256r1")},
+                               private_template={Attribute.EXTRACTABLE: False, Attribute.SENSITIVE: True, Attribute.DERIVE: True}, store=True, label=key_label)
+        return self
+
+    def public_bytes(self) -> bytes:
+        """Uncompressed point 0x04 ‖ X ‖ Y (65 bytes) — what goes into the token's `client_public_key`."""
+        pkcs11, tok = self._lib()
+        from pkcs11.util.ec import encode_ec_public_key
+        from cryptography.hazmat.primitives import serialization
+        with tok.open(user_pin=self.pin) as s:
+            pub = s.get_key(label=self.key_label, object_class=pkcs11.ObjectClass.PUBLIC_KEY)
+            spki = encode_ec_public_key(pub)
+        return serialization.load_der_public_key(spki).public_bytes(serialization.Encoding.X962, serialization.PublicFormat.UncompressedPoint)
+
+    def public_b64(self) -> str:
+        import base64
+        return base64.b64encode(self.public_bytes()).decode()
+
+    def ecdh(self, peer_point: bytes) -> bytes:
+        """Shared secret with the vault's ephemeral point, computed inside the token (CKM_ECDH1_DERIVE)."""
+        pkcs11, tok = self._lib()
+        from pkcs11 import Attribute, KeyType
+        with tok.open(user_pin=self.pin) as s:
+            priv = s.get_key(label=self.key_label, object_class=pkcs11.ObjectClass.PRIVATE_KEY)
+            shared = priv.derive_key(KeyType.GENERIC_SECRET, 256, mechanism_param=(pkcs11.KDF.NULL, None, peer_point),
+                                     template={Attribute.EXTRACTABLE: True, Attribute.SENSITIVE: False})
+            return bytes(shared[Attribute.VALUE])
+
+
+def _p256_unseal(envelope: dict, key, name: str) -> dict:
+    """P-256 envelope: ECDH with the ephemeral point (in software from the scalar, or inside a PKCS#11
+    token), HKDF-SHA256(info = label ‖ epk ‖ our point), AES-256-GCM with the name as AAD."""
+    import base64
+    hashes, _, AESGCM, HKDF, ser = _crypto()
+    from cryptography.hazmat.primitives.asymmetric import ec
+    epk = base64.b64decode(envelope["epk"])
+    try:
+        if isinstance(key, Pkcs11Key):
+            our = key.public_bytes()
+            shared = key.ecdh(epk)
+        else:
+            sk = ec.derive_private_key(int.from_bytes(base64.b64decode(key), "big"), ec.SECP256R1())
+            our = sk.public_key().public_bytes(ser.Encoding.X962, ser.PublicFormat.UncompressedPoint)
+            shared = sk.exchange(ec.ECDH(), ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), epk))
+        k = HKDF(algorithm=hashes.SHA256(), length=32, salt=None, info=_SEALED_INFO_P256 + epk + our).derive(shared)
+        pt = AESGCM(k).decrypt(base64.b64decode(envelope["nonce"]), base64.b64decode(envelope["ct"]), name.encode("utf-8"))
+    except Exception:
+        raise VaultError(0, "vault: sealed value does not open with this private key (wrong key, or the token is bound to another key)") from None
+    return json.loads(pt.decode("utf-8"))
+
+
+def _gost():
+    try:
+        import gostcrypto  # noqa: F401
+    except ImportError:          # pragma: no cover
+        raise RuntimeError("vault: the GOST envelope needs the `gostcrypto` package (pip install 'aps-vault[gost]')") from None
+    from . import gost
+    return gost
+
+
+def _mlkem():
+    try:
+        from kyber_py.ml_kem import ML_KEM_768
+    except ImportError:          # pragma: no cover
+        raise RuntimeError("vault: the post-quantum envelope needs the `kyber-py` package (pip install 'aps-vault[pqc]')") from None
+    return ML_KEM_768
+
+
+def _pqc_unseal(envelope: dict, private_key_b64: str, name: str) -> dict:
+    """Hybrid envelope (0.27): X25519 with the ephemeral key + ML-KEM-768 decapsulation with the key derived
+    from our 64-byte seed; HKDF-SHA256 over both shared secrets (info = label ‖ epk ‖ kem_ct); AES-256-GCM
+    with the secret name as AAD. Private key = X25519 sk (32) ‖ seed (64) = 96 bytes."""
+    import base64
+    hashes, x25519, AESGCM, HKDF, ser = _crypto()
+    kem = _mlkem()
+    raw = base64.b64decode(private_key_b64)
+    if len(raw) != 96:
+        raise VaultError(0, "vault: hybrid private key must be 96 bytes (X25519 sk ‖ ML-KEM-768 seed) — use generate_keypair('pqc')")
+    try:
+        _, dk = kem.key_derive(raw[32:])
+        epk, kem_ct = base64.b64decode(envelope["epk"]), base64.b64decode(envelope["kem"])
+        ss_x = x25519.X25519PrivateKey.from_private_bytes(raw[:32]).exchange(x25519.X25519PublicKey.from_public_bytes(epk))
+        ss_kem = kem.decaps(dk, kem_ct)
+        key = HKDF(algorithm=hashes.SHA256(), length=32, salt=None, info=_SEALED_INFO_PQC + epk + kem_ct).derive(ss_x + ss_kem)
+        pt = AESGCM(key).decrypt(base64.b64decode(envelope["nonce"]), base64.b64decode(envelope["ct"]), name.encode("utf-8"))
+    except Exception:
+        raise VaultError(0, "vault: sealed value does not open with this private key (wrong key, or the token is bound to another key)") from None
+    return json.loads(pt.decode("utf-8"))
+
+
+def _gost_pqc_unseal(envelope: dict, private_key_b64: str, name: str) -> dict:
+    """GOST hybrid envelope (0.32): VKO GOST R 34.10-2012 with the ephemeral key (UKM from the envelope) + ML-KEM-768
+    decapsulation with the key derived from our 64-byte seed; KDF_TREE_256(KEK ‖ ss_kem, label, epk ‖ kem) →
+    Kuznyechik-MGM with the secret name as AAD. Private key = GOST scalar (32) ‖ seed (64) = 96 bytes."""
+    import base64
+    g = _gost()
+    kem = _mlkem()
+    raw = base64.b64decode(private_key_b64)
+    if len(raw) != 96:
+        raise VaultError(0, "vault: GOST hybrid private key must be 96 bytes (GOST scalar ‖ ML-KEM-768 seed) — use generate_keypair('gost-pqc')")
+    try:
+        d = int.from_bytes(raw[:32], "big")
+        _, dk = kem.key_derive(raw[32:])
+        epk, kem_ct = base64.b64decode(envelope["epk"]), base64.b64decode(envelope["kem"])
+        kek = g.vko(d, g.decode_point(epk), base64.b64decode(envelope["ukm"]))
+        ss_kem = kem.decaps(dk, kem_ct)
+        key = g.kdf_tree_256(kek + ss_kem, _SEALED_LABEL_GOST_PQC, epk + kem_ct, 1)
+        pt = g.MGM(g.Kuznyechik(key)).open(base64.b64decode(envelope["nonce"]), base64.b64decode(envelope["ct"]), name.encode("utf-8"))
+    except Exception:
+        raise VaultError(0, "vault: sealed value does not open with this private key (wrong key, or the token is bound to another key)") from None
+    return json.loads(pt.decode("utf-8"))
+
+
+def gost_pqc_public_from_private(private_key_b64: str) -> str:
+    """The base64 1248-byte public key of a 96-byte GOST hybrid private key."""
+    import base64
+    g = _gost()
+    raw = base64.b64decode(private_key_b64)
+    if len(raw) != 96:
+        raise VaultError(0, "vault: GOST hybrid private key must be 96 bytes (GOST scalar ‖ ML-KEM-768 seed)")
+    gost_pk = g.encode_point(g.public_from_private(int.from_bytes(raw[:32], "big")))
+    ek, _ = _mlkem().key_derive(raw[32:])
+    return base64.b64encode(gost_pk + ek).decode()
+
+
+def pqc_public_from_private(private_key_b64: str) -> str:
+    """The base64 1216-byte public key of a 96-byte hybrid private key (for checking what the vault was given)."""
+    import base64
+    _, x25519, _, _, ser = _crypto()
+    raw = base64.b64decode(private_key_b64)
+    x_pk = x25519.X25519PrivateKey.from_private_bytes(raw[:32]).public_key().public_bytes(ser.Encoding.Raw, ser.PublicFormat.Raw)
+    ek, _ = _mlkem().key_derive(raw[32:])
+    return base64.b64encode(x_pk + ek).decode()
+
+
+def _crypto():
+    try:
+        from cryptography.hazmat.primitives import hashes
+        from cryptography.hazmat.primitives.asymmetric import x25519
+        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+        from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+        from cryptography.hazmat.primitives import serialization
+    except ImportError:          # pragma: no cover
+        raise RuntimeError("vault: sealed delivery needs the `cryptography` package (pip install 'aps-vault[sealed]')") from None
+    return hashes, x25519, AESGCM, HKDF, serialization
+
+
+def generate_keypair(kind: str = "x25519") -> "tuple[str, str]":
+    """(private_b64, public_b64) in standard base64. `x25519` (default): raw 32-byte keys.
+    `gost`: GOST R 34.10-2012 key pair on id-tc26-gost-3410-2012-256-paramSetB — 32-byte big-endian
+    scalar and a 64-byte X‖Y little-endian point; the vault then seals with VKO + Kuznyechik-MGM.
+    `p256`: NIST P-256 — 32-byte scalar and a 65-byte uncompressed point; the curve a TPM or any PKCS#11
+    token can hold (see Pkcs11Key for the hardware version).
+    `pqc` (0.27): post-quantum hybrid X25519 + ML-KEM-768 — private = X25519 sk (32) ‖ ML-KEM seed (64),
+    public = X25519 pk (32) ‖ ML-KEM encapsulation key (1184); needs `pip install 'aps-vault[pqc]'`.
+    `gost-pqc` (0.32): GOST hybrid — private = GOST scalar (32) ‖ ML-KEM seed (64), public = GOST point (64) ‖
+    ML-KEM ek (1184) = 1248 bytes; the vault seals with VKO + ML-KEM → KDF_TREE → Kuznyechik-MGM (gost + pqc extras).
+    Give the public half to the vault administrator (token field `client_public_key`); keep the
+    private half with the token (environment / secret store), never in the repository."""
+    import base64
+    if kind == "gost":
+        g = _gost()
+        sk_raw, pk_raw = g.generate_keypair()
+        return base64.b64encode(sk_raw).decode(), base64.b64encode(pk_raw).decode()
+    if kind == "gost-pqc":
+        import os as _os
+        g = _gost()
+        sk_raw, pk_raw = g.generate_keypair()
+        seed = _os.urandom(64)
+        ek, _ = _mlkem().key_derive(seed)
+        return base64.b64encode(sk_raw + seed).decode(), base64.b64encode(pk_raw + ek).decode()
+    if kind == "pqc":
+        _, x25519, _, _, ser = _crypto()
+        import os as _os
+        x = x25519.X25519PrivateKey.generate()
+        seed = _os.urandom(64)
+        ek, _ = _mlkem().key_derive(seed)
+        return (base64.b64encode(x.private_bytes(ser.Encoding.Raw, ser.PrivateFormat.Raw, ser.NoEncryption()) + seed).decode(),
+                base64.b64encode(x.public_key().public_bytes(ser.Encoding.Raw, ser.PublicFormat.Raw) + ek).decode())
+    if kind == "p256":
+        _, _, _, _, ser = _crypto()
+        from cryptography.hazmat.primitives.asymmetric import ec
+        sk = ec.generate_private_key(ec.SECP256R1())
+        return (base64.b64encode(sk.private_numbers().private_value.to_bytes(32, "big")).decode(),
+                base64.b64encode(sk.public_key().public_bytes(ser.Encoding.X962, ser.PublicFormat.UncompressedPoint)).decode())
+    _, x25519, _, _, ser = _crypto()
+    sk = x25519.X25519PrivateKey.generate()
+    return (base64.b64encode(sk.private_bytes(ser.Encoding.Raw, ser.PrivateFormat.Raw, ser.NoEncryption())).decode(),
+            base64.b64encode(sk.public_key().public_bytes(ser.Encoding.Raw, ser.PublicFormat.Raw)).decode())
+
+
+def unseal(envelope: dict, private_key_b64: str, name: str) -> dict:
+    """Open a sealed envelope from GET /api/v1/m/secret/{name}: X25519 with the ephemeral key,
+    HKDF-SHA256 over the shared secret (info = label || epk || our pk), AES-256-GCM with the
+    secret name as AAD. Returns the payload dict ({value, login?, notes?, totp?})."""
+    import base64
+    if envelope.get("alg") == SEALED_ALG_PQC and envelope.get("v") == 1:
+        if isinstance(private_key_b64, Pkcs11Key):
+            raise VaultError(0, "vault: a PKCS#11 key opens only the P-256 envelope, the token sent the hybrid one")
+        return _pqc_unseal(envelope, private_key_b64, name)
+    if envelope.get("alg") == SEALED_ALG_GOST_PQC and envelope.get("v") == 1:
+        if isinstance(private_key_b64, Pkcs11Key):
+            raise VaultError(0, "vault: a PKCS#11 key opens only the P-256 envelope, the token sent the GOST hybrid one")
+        return _gost_pqc_unseal(envelope, private_key_b64, name)
+    if envelope.get("alg") == SEALED_ALG_GOST and envelope.get("v") == 1:
+        return _unseal_gost(envelope, private_key_b64, name)
+    if envelope.get("alg") == SEALED_ALG_P256 and envelope.get("v") == 1:
+        return _p256_unseal(envelope, private_key_b64, name)
+    if isinstance(private_key_b64, Pkcs11Key):
+        raise VaultError(0, f"vault: a PKCS#11 key opens only the P-256 envelope, the token sent {envelope.get('alg')!r}")
+    hashes, x25519, AESGCM, HKDF, ser = _crypto()
+    if envelope.get("alg") != SEALED_ALG or envelope.get("v") != 1:
+        raise VaultError(0, f"vault: unsupported sealed envelope {envelope.get('alg')!r} v{envelope.get('v')!r}")
+    sk = x25519.X25519PrivateKey.from_private_bytes(base64.b64decode(private_key_b64))
+    pk = sk.public_key().public_bytes(ser.Encoding.Raw, ser.PublicFormat.Raw)
+    epk = base64.b64decode(envelope["epk"])
+    shared = sk.exchange(x25519.X25519PublicKey.from_public_bytes(epk))
+    key = HKDF(algorithm=hashes.SHA256(), length=32, salt=None, info=_SEALED_INFO + epk + pk).derive(shared)
+    try:
+        pt = AESGCM(key).decrypt(base64.b64decode(envelope["nonce"]), base64.b64decode(envelope["ct"]), name.encode("utf-8"))
+    except Exception:
+        raise VaultError(0, "vault: sealed value does not open with this private key (wrong key, or the token is bound to another key)") from None
+    return json.loads(pt.decode("utf-8"))
+
+
+def _unseal_gost(envelope: dict, private_key_b64: str, name: str) -> dict:
+    """GOST envelope: VKO GOST R 34.10-2012 (UKM from the envelope) → KEK; KDF_TREE(KEK, label, epk‖our pk)
+    → key; Kuznyechik-MGM with the secret name as AAD."""
+    import base64
+    g = _gost()
+    try:
+        d = int.from_bytes(base64.b64decode(private_key_b64), "big")
+        our_pk = g.encode_point(g.public_from_private(d))
+        epk = base64.b64decode(envelope["epk"])
+        kek = g.vko(d, g.decode_point(epk), base64.b64decode(envelope["ukm"]))
+        key = g.kdf_tree_256(kek, _SEALED_LABEL_GOST, epk + our_pk, 1)
+        pt = g.MGM(g.Kuznyechik(key)).open(base64.b64decode(envelope["nonce"]), base64.b64decode(envelope["ct"]), name.encode("utf-8"))
+    except Exception:
+        raise VaultError(0, "vault: sealed value does not open with this private key (wrong key, or the token is bound to another key)") from None
+    return json.loads(pt.decode("utf-8"))
+
+
+def enroll(base_url: str, code: str, *, name: str = "", gost: bool = False, kind: str | None = None,
+           hardware_key: "Pkcs11Key | None" = None, timeout: float = 10.0) -> dict:
+    """Node enrolment (0.21): generate this machine's key pair, present the one-time code, receive a
+    token sealed to the new key. Returns {token, private_key, public_key, token_name, folder_name,
+    vault_url}. Keep `token` and `private_key` with mode 0600 (VAULT_TOKEN / VAULT_CLIENT_KEY);
+    the token alone opens nothing."""
+    import socket
+    if hardware_key is not None:
+        private, public = hardware_key, hardware_key.public_b64()        # the private key stays in the token
+    else:
+        private, public = generate_keypair(kind or ("gost" if gost else "x25519"))
+    body = json.dumps({"code": code, "public_key": public, "name": name or socket.gethostname()[:64]}).encode("utf-8")
+    req = urllib.request.Request(base_url.rstrip("/") + "/api/enroll", data=body, method="POST",
+                                 headers={"Content-Type": "application/json", "Accept": "application/json", "User-Agent": f"aps-vault-python/{__version__}"})
+    try:
+        with _OPENER.open(req, timeout=timeout) as r:   # nosec — URL is the configured vault
+            data = json.loads(r.read())
+    except urllib.error.HTTPError as e:
+        raw = e.read()
+        try:
+            detail = json.loads(raw).get("detail")
+        except Exception:
+            detail = raw.decode("utf-8", "replace")
+        raise VaultError(e.code, f"vault enrol: HTTP {e.code} {detail}") from None
+    return {"token": data["raw_token"], "private_key": private, "public_key": public, "token_name": data.get("token_name"),
+            "folder_name": data.get("folder_name"), "vault_url": data.get("vault_url") or base_url}
+
+
+class Vault:
+    def __init__(self, base_url: str, token: str, *, cache_ttl: float = 300.0,
+                 timeout: float = 5.0, max_retries: int = 3, fail_open_cache: bool = True,
+                 user_agent: str = f"aps-vault-python/{__version__}", client_private_key: Optional[str] = None) -> None:
+        if not base_url:
+            raise ValueError("vault: base_url required")
+        if not token or not token.startswith("vlt_"):
+            raise ValueError("vault: a service token (vlt_…) is required, not a master password")
+        self._base = base_url.rstrip("/")
+        self._token = token
+        self._ttl = cache_ttl
+        self._timeout = timeout
+        self._retries = max_retries
+        self._fail_open = fail_open_cache
+        self._client_key = client_private_key or os.environ.get("VAULT_CLIENT_KEY") or None
+        self._ua = user_agent
+        self._cache: dict[str, _Entry] = {}
+
+    @classmethod
+    def from_env(cls, **kw: Any) -> "Vault":
+        """VAULT_URL + VAULT_TOKEN, or VAULT_TOKEN_FILE pointing at a 0600 file."""
+        url = os.environ.get("VAULT_URL", "")
+        token = os.environ.get("VAULT_TOKEN", "")
+        if not token and os.environ.get("VAULT_TOKEN_FILE"):
+            with open(os.environ["VAULT_TOKEN_FILE"], encoding="utf-8") as f:
+                token = f.read().strip()
+        return cls(url, token, **kw)
+
+    # ── public API ────────────────────────────────────────────────────────────
+    def health(self) -> dict:
+        return self._req("GET", "/api/v1/m/health")
+
+    def list(self) -> list[dict]:
+        return self._req("GET", "/api/v1/m/secrets")
+
+    def get(self, name: str, version: int | None = None) -> str:
+        """Current value, or an older one by number (`version`) — e.g. the previous encryption
+        key while files encrypted with it are still being re-wrapped."""
+        return self.get_full(name, version)["value"]
+
+    def versions(self, name: str) -> dict:
+        """{"current_version": N, "versions": [{"version", "current", "changed_at", ...}]} — no decrypt."""
+        return self._req("GET", "/api/v1/m/secret/" + urllib.parse.quote(name, safe="") + "/versions")
+
+    def get_full(self, name: str, version: int | None = None) -> dict:
+        if not name:
+            raise ValueError("vault: name required")
+        now = time.time()
+        key = f"{name}@{version}" if version else name
+        hit = self._cache.get(key)
+        if hit and hit.expires_at > now:
+            return hit.value
+        try:
+            data = self._req("GET", "/api/v1/m/secret/" + urllib.parse.quote(name, safe="") + (f"?version={int(version)}" if version else ""))
+        except (VaultError, OSError) as e:
+            if hit and self._fail_open and (not isinstance(e, VaultError) or e.status >= 500 or e.status == 429):
+                return hit.value          # stale but known-good beats an outage
+            raise
+        if isinstance(data, dict) and "sealed" in data:
+            if not self._client_key:
+                raise VaultError(0, "vault: this token delivers sealed values — pass client_private_key (or VAULT_CLIENT_KEY)")
+            # 0.37: the AAD is the name WE asked for — the response's own "name" could come from a swapped envelope
+            payload = unseal(data.pop("sealed"), self._client_key, name)
+            data.update(payload)
+        elif self._client_key and isinstance(data, dict):
+            # 0.37: with a key configured a plaintext answer is not accepted — a tampering proxy could drop the envelope
+            raise VaultError(0, "vault: a client key is configured but the response is not sealed — refusing (a proxy may have replaced it)")
+        if self._ttl > 0:
+            self._cache[key] = _Entry(data, now + self._ttl)
+        return data
+
+    def put(self, name: str, value: str, *, login: str = "", tags: str = "", url: str = "") -> dict:
+        """Create or update a secret in the token's folder (token must have can_write)."""
+        body = {"value": value, "login": login, "tags": tags, "url": url}
+        data = self._req("POST", "/api/v1/m/secret/" + urllib.parse.quote(name, safe=""), body)
+        self._cache.pop(name, None)
+        return data
+
+    def totp(self, name: str) -> Optional[str]:
+        """Current TOTP code (token must have can_read_totp); None if the secret has no seed."""
+        self._cache.pop(name, None)       # codes change every 30 s — never serve from cache
+        ttl, self._ttl = self._ttl, 0
+        try:
+            return self.get_full(name).get("totp")
+        finally:
+            self._ttl = ttl
+
+    def clear_cache(self) -> None:
+        self._cache.clear()
+
+    # ── transport ─────────────────────────────────────────────────────────────
+    def _req(self, method: str, path: str, body: Optional[dict] = None) -> Any:
+        payload = json.dumps(body).encode("utf-8") if body is not None else None
+        last: Optional[Exception] = None
+        for attempt in range(self._retries + 1):
+            req = urllib.request.Request(self._base + path, data=payload, method=method, headers={
+                "Authorization": f"Bearer {self._token}", "Accept": "application/json",
+                "Content-Type": "application/json", "User-Agent": self._ua,
+            })
+            try:
+                with _OPENER.open(req, timeout=self._timeout) as r:   # nosec — URL is the configured vault
+                    return json.loads(r.read() or b"null")
+            except urllib.error.HTTPError as e:
+                raw = e.read()
+                try:
+                    parsed: Any = json.loads(raw)
+                    detail = parsed.get("detail") if isinstance(parsed, dict) else None
+                except Exception:
+                    parsed, detail = raw.decode("utf-8", "replace"), None
+                if (e.code == 429 or e.code >= 500) and attempt < self._retries:
+                    time.sleep(2 ** attempt)
+                    continue
+                raise VaultError(e.code, f"vault {method} {path}: HTTP {e.code} {detail or e.reason}", parsed) from None
+            except (urllib.error.URLError, TimeoutError, OSError) as e:
+                last = e
+                if attempt < self._retries:
+                    time.sleep(2 ** attempt)
+                    continue
+        raise OSError(f"vault: request failed after {self._retries + 1} attempts: {last}")
+
+
+__all__ = ["Vault", "VaultError", "Pkcs11Key", "generate_keypair", "unseal", "enroll", "__version__"]

aps_vault-0.41.0/aps_vault/__main__.py

@@ -0,0 +1,72 @@
+"""python -m aps_vault keygen [--gost|--p256|--pqc|--gost-pqc] — a key pair for sealed delivery (--pqc: X25519 + ML-KEM-768; --gost-pqc: GOST + ML-KEM-768)
+   python -m aps_vault enroll <vault-url> <code> [--gost|--p256|--pqc|--gost-pqc] [--pkcs11 module:token:pin[:label]] [--name <host>] [--out <dir>]
+                                                          — with --pkcs11 the key pair is made INSIDE the token (TPM via
+                                                            tpm2-pkcs11, HSM, smart card) and never leaves it
+                                                          — node enrolment (0.21): make a key pair, redeem the
+                                                            one-time code, store token + key (0600) in <dir>
+                                                            (default: print them)"""
+import os
+import sys
+
+from . import Pkcs11Key, enroll, generate_keypair
+
+
+def _usage(code=2):
+    print(__doc__, file=sys.stderr)
+    sys.exit(code)
+
+
+args = sys.argv[1:]
+if not args:
+    _usage()
+if args[0] == "keygen":
+    if any(a not in ("--gost", "--p256", "--pqc", "--gost-pqc") for a in args[1:]):
+        _usage()
+    kind = "gost-pqc" if "--gost-pqc" in args else "gost" if "--gost" in args else "p256" if "--p256" in args else "pqc" if "--pqc" in args else "x25519"
+    private, public = generate_keypair(kind)
+    print(f"VAULT_CLIENT_KEY={private}        # keep with the token, never in git ({kind})")
+    print(f"client_public_key={public}       # paste into the token in the vault UI")
+elif args[0] == "enroll":
+    if len(args) < 3:
+        _usage()
+    url, code, rest = args[1], args[2], args[3:]
+    kind, name, out, hw = "x25519", "", "", None
+    i = 0
+    while i < len(rest):
+        if rest[i] == "--name" and i + 1 < len(rest):
+            name = rest[i + 1]; i += 2
+        elif rest[i] == "--out" and i + 1 < len(rest):
+            out = rest[i + 1]; i += 2
+        elif rest[i] == "--pkcs11" and i + 1 < len(rest):
+            parts = rest[i + 1].split(":")
+            if len(parts) < 3:
+                _usage()
+            hw = Pkcs11Key.generate(parts[0], parts[1], parts[2], parts[3] if len(parts) > 3 else "aps-vault-node"); i += 2
+        elif rest[i] in ("--gost", "--p256", "--pqc", "--gost-pqc"):
+            kind = rest[i][2:]; i += 1
+        else:
+            _usage()
+    try:
+        r = enroll(url, code, name=name, kind=kind, hardware_key=hw)
+    except Exception as e:
+        print(f"enrol failed: {e}", file=sys.stderr)
+        sys.exit(1)
+    if out:
+        os.makedirs(out, mode=0o700, exist_ok=True)
+        for fn, val in ((("vault.token", r["token"]),) + ((("vault.key", r["private_key"]),) if hw is None else ())):
+            p = os.path.join(out, fn)
+            with open(os.open(p, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600), "w") as f:
+                f.write(val + "\n")
+        if hw is None:
+            print(f"enrolled as {r['token_name']} (folder {r['folder_name']}); VAULT_TOKEN_FILE={out}/vault.token  VAULT_CLIENT_KEY=$(cat {out}/vault.key)  VAULT_URL={r['vault_url']}")
+        else:
+            print(f"enrolled as {r['token_name']} (folder {r['folder_name']}); VAULT_TOKEN_FILE={out}/vault.token; the private key lives in the PKCS#11 token {hw.token_label!r} as {hw.key_label!r}  VAULT_URL={r['vault_url']}")
+    else:
+        print(f"VAULT_URL={r['vault_url']}")
+        print(f"VAULT_TOKEN={r['token']}          # {r['token_name']} → {r['folder_name']}")
+        if hw is None:
+            print(f"VAULT_CLIENT_KEY={r['private_key']}   # the private key: 0600, never in git")
+        else:
+            print(f"# private key inside the PKCS#11 token {hw.token_label!r}, label {hw.key_label!r} — use Pkcs11Key(...) in code")
+else:
+    _usage()

aps_vault-0.41.0/aps_vault/gost.py

@@ -0,0 +1,447 @@
+"""GOST primitives for the Python client's sealed-delivery envelope (0.19) — a verbatim copy of
+backend/gost.py + backend/gostec.py (test_python_client.py checks they stay identical).
+Needs the MIT `gostcrypto` package for Streebog: pip install 'aps-vault[gost]'."""
+from __future__ import annotations
+
+import os
+import struct
+
+# ── Kuznyechik (GOST R 34.12-2015) ───────────────────────────────────────────
+_PI = bytes([
+    252, 238, 221, 17, 207, 110, 49, 22, 251, 196, 250, 218, 35, 197, 4, 77, 233, 119, 240, 219, 147, 46, 153, 186, 23, 54, 241, 187, 20, 205, 95, 193, 249, 24, 101, 90, 226, 92, 239, 33, 129, 28, 60, 66, 139, 1, 142, 79, 5, 132, 2, 174, 227, 106, 143, 160, 6, 11, 237, 152, 127, 212, 211, 31, 235, 52, 44, 81, 234, 200, 72, 171, 242, 42, 104, 162, 253, 58, 206, 204, 181, 112, 14, 86, 8, 12, 118, 18, 191, 114, 19, 71, 156, 183, 93, 135, 21, 161, 150, 41, 16, 123, 154, 199, 243, 145, 120, 111, 157, 158, 178, 177, 50, 117, 25, 61, 255, 53, 138, 126, 109, 84, 198, 128, 195, 189, 13, 87, 223, 245, 36, 169, 62, 168, 67, 201, 215, 121, 214, 246, 124, 34, 185, 3, 224, 15, 236, 222, 122, 148, 176, 188, 220, 232, 40, 80, 78, 51, 10, 74, 167, 151, 96, 115, 30, 0, 98, 68, 26, 184, 56, 130, 100, 159, 38, 65, 173, 69, 70, 146, 39, 94, 85, 47, 140, 163, 165, 125, 105, 213, 149, 59, 7, 88, 179, 64, 134, 172, 29, 247, 48, 55, 107, 228, 136, 217, 231, 137, 225, 27, 131, 73, 76, 63, 248, 254, 141, 83, 170, 144, 202, 216, 133, 97, 32, 113, 103, 164, 45, 43, 9, 91, 203, 155, 37, 208, 190, 229, 108, 82, 89, 166, 116, 210, 230, 244, 180, 192, 209, 102, 175, 194, 57, 75, 99, 182,
+])
+_PI_INV = bytes(256)
+_PI_INV = bytearray(256)
+for _i, _v in enumerate(_PI):
+    _PI_INV[_v] = _i
+_PI_INV = bytes(_PI_INV)
+_LVEC = (148, 32, 133, 16, 194, 192, 1, 251, 1, 192, 194, 16, 133, 32, 148, 1)
+
+
+def _gf_mul(a: int, b: int) -> int:
+    """Multiplication in GF(2^8) with the polynomial x^8 + x^7 + x^6 + x + 1 (0x1C3)."""
+    p = 0
+    while b:
+        if b & 1:
+            p ^= a
+        a <<= 1
+        if a & 0x100:
+            a ^= 0x1C3
+        b >>= 1
+    return p
+
+
+_MUL = [[_gf_mul(a, b) for b in range(256)] for a in range(256)]
+
+
+def _l_step(state: list[int]) -> list[int]:
+    """One R step of the linear transform: shift right, new byte 0 = l(state)."""
+    acc = 0
+    for i in range(16):
+        acc ^= _MUL[state[i]][_LVEC[i]]
+    return [acc] + state[:15]
+
+
+def _l(state: list[int]) -> list[int]:
+    for _ in range(16):
+        state = _l_step(state)
+    return state
+
+
+def _l_inv_step(state: list[int]) -> list[int]:
+    a = state[0]
+    state = state[1:] + [0]
+    acc = 0
+    for i in range(16):
+        acc ^= _MUL[state[i]][_LVEC[i]]
+    state[15] = a ^ acc
+    return state
+
+
+def _l_inv(state: list[int]) -> list[int]:
+    for _ in range(16):
+        state = _l_inv_step(state)
+    return state
+
+
+def _vec(b: bytes) -> list[int]:
+    return list(b)
+
+
+def _to_int(v: list[int]) -> int:
+    return int.from_bytes(bytes(v), "big")
+
+
+# LS tables: LS[i][x] = L(e_i * pi(x)) as a 128-bit int — the linear map is linear, so
+# L(S(block)) = XOR_i LS[i][block[i]]. Inverse tables for decryption: LS_INV[i][x] = L^-1(e_i * x).
+_LS = []
+_LSI = []
+for _pos in range(16):
+    _t = []
+    _ti = []
+    for _x in range(256):
+        _blk = [0] * 16
+        _blk[_pos] = _PI[_x]
+        _t.append(_to_int(_l(_blk)))
+        _blk2 = [0] * 16
+        _blk2[_pos] = _x
+        _ti.append(_to_int(_l_inv(_blk2)))
+    _LS.append(_t)
+    _LSI.append(_ti)
+
+_MASK128 = (1 << 128) - 1
+_SHIFTS = [8 * (15 - i) for i in range(16)]       # byte i of a big-endian 128-bit int
+
+
+def _ls_int(x: int) -> int:
+    acc = 0
+    for i in range(16):
+        acc ^= _LS[i][(x >> _SHIFTS[i]) & 0xFF]
+    return acc
+
+
+def _l_inv_int(x: int) -> int:
+    acc = 0
+    for i in range(16):
+        acc ^= _LSI[i][(x >> _SHIFTS[i]) & 0xFF]
+    return acc
+
+
+def _s_inv_int(x: int) -> int:
+    out = 0
+    for i in range(16):
+        out |= _PI_INV[(x >> _SHIFTS[i]) & 0xFF] << _SHIFTS[i]
+    return out
+
+
+# round constants C_i = L(Vec(i)), i = 1..32
+_C = []
+for _i in range(1, 33):
+    _blk = [0] * 15 + [_i]
+    _C.append(_to_int(_l(_blk)))
+
+
+class Kuznyechik:
+    """GOST R 34.12-2015 block cipher; `key` is 32 bytes."""
+
+    def __init__(self, key: bytes) -> None:
+        if len(key) != 32:
+            raise ValueError("Kuznyechik key must be 32 bytes")
+        k1 = int.from_bytes(key[:16], "big")
+        k2 = int.from_bytes(key[16:], "big")
+        keys = [k1, k2]
+        for i in range(4):
+            for j in range(8):
+                c = _C[8 * i + j]
+                k1, k2 = _ls_int(k1 ^ c) ^ k2, k1
+            keys += [k1, k2]
+        self._k = keys                       # 10 round keys
+        self._kd = keys[::-1]
+
+    def encrypt_block(self, block: bytes) -> bytes:
+        x = int.from_bytes(block, "big")
+        k = self._k
+        for i in range(9):
+            x = _ls_int(x ^ k[i])
+        return (x ^ k[9]).to_bytes(16, "big")
+
+    def decrypt_block(self, block: bytes) -> bytes:
+        x = int.from_bytes(block, "big")
+        k = self._kd
+        x ^= k[0]
+        for i in range(1, 10):
+            x = _s_inv_int(_l_inv_int(x)) ^ k[i]
+        return x.to_bytes(16, "big")
+
+
+# ── MGM (RFC 9058 / R 1323565.1.026-2019) ─────────────────────────────────────
+_R = 0x87          # reduction for the GF(2^128) polynomial w^128 + w^7 + w^2 + w + 1
+
+
+def _gf128_mul(a: int, b: int) -> int:
+    """Multiplication in GF(2^128) with f(w) = w^128 + w^7 + w^2 + w + 1 (RFC 9058 §4.1), MSB-first."""
+    p = 0
+    for _ in range(128):
+        if b & 1:
+            p ^= a
+        carry = a >> 127
+        a = (a << 1) & _MASK128
+        if carry:
+            a ^= _R
+        b >>= 1
+    return p
+
+
+def _incr_r(x: int) -> int:
+    hi, lo = x >> 64, x & ((1 << 64) - 1)
+    return (hi << 64) | ((lo + 1) & ((1 << 64) - 1))
+
+
+def _incr_l(x: int) -> int:
+    hi, lo = x >> 64, x & ((1 << 64) - 1)
+    return (((hi + 1) & ((1 << 64) - 1)) << 64) | lo
+
+
+def _blocks(data: bytes):
+    for i in range(0, len(data), 16):
+        yield data[i:i + 16]
+
+
+class MGM:
+    """AEAD over a 128-bit block cipher: nonce 16 bytes (top bit must be 0), tag 16 bytes."""
+
+    TAG = 16
+    NONCE = 16
+
+    def __init__(self, cipher: Kuznyechik) -> None:
+        self._c = cipher
+
+    def _check_nonce(self, nonce: bytes) -> int:
+        if len(nonce) != 16 or nonce[0] & 0x80:
+            raise ValueError("MGM nonce must be 16 bytes with the top bit clear")
+        return int.from_bytes(nonce, "big")
+
+    def _tag(self, nonce_int: int, aad: bytes, ct: bytes) -> bytes:
+        enc = self._c.encrypt_block
+        z = int.from_bytes(enc(((1 << 127) | nonce_int).to_bytes(16, "big")), "big")
+        acc = 0
+        for part in (aad, ct):
+            for blk in _blocks(part):
+                if len(blk) < 16:
+                    blk = blk + b"\x00" * (16 - len(blk))
+                h = int.from_bytes(enc(z.to_bytes(16, "big")), "big")
+                acc ^= _gf128_mul(h, int.from_bytes(blk, "big"))
+                z = _incr_l(z)
+        h = int.from_bytes(enc(z.to_bytes(16, "big")), "big")
+        length_block = struct.pack(">QQ", len(aad) * 8, len(ct) * 8)
+        acc ^= _gf128_mul(h, int.from_bytes(length_block, "big"))
+        return enc(acc.to_bytes(16, "big"))[: self.TAG]
+
+    def _keystream_xor(self, nonce_int: int, data: bytes) -> bytes:
+        enc = self._c.encrypt_block
+        y = int.from_bytes(enc(nonce_int.to_bytes(16, "big")), "big")   # top bit of the nonce is 0
+        out = bytearray()
+        for blk in _blocks(data):
+            ks = enc(y.to_bytes(16, "big"))
+            out += bytes(a ^ b for a, b in zip(blk, ks))
+            y = _incr_r(y)
+        return bytes(out)
+
+    def seal(self, nonce: bytes, plaintext: bytes, aad: bytes = b"") -> bytes:
+        n = self._check_nonce(nonce)
+        ct = self._keystream_xor(n, plaintext)
+        return ct + self._tag(n, aad, ct)
+
+    def open(self, nonce: bytes, ciphertext: bytes, aad: bytes = b"") -> bytes:
+        n = self._check_nonce(nonce)
+        if len(ciphertext) < self.TAG:
+            raise ValueError("ciphertext too short")
+        ct, tag = ciphertext[: -self.TAG], ciphertext[-self.TAG:]
+        expected = self._tag(n, aad, ct)
+        # constant-time compare
+        diff = 0
+        for a, b in zip(expected, tag):
+            diff |= a ^ b
+        if diff:
+            raise ValueError("MGM tag mismatch")
+        return self._keystream_xor(n, ct)
+
+
+def mgm_nonce() -> bytes:
+    n = bytearray(os.urandom(16))
+    n[0] &= 0x7F
+    return bytes(n)
+
+
+# ── Streebog family via gostcrypto (MIT) ─────────────────────────────────────
+def streebog256(data: bytes) -> bytes:
+    from gostcrypto import gosthash
+    return gosthash.new("streebog256", data=data).digest()
+
+
+def streebog512(data: bytes) -> bytes:
+    from gostcrypto import gosthash
+    return gosthash.new("streebog512", data=data).digest()
+
+
+_HMAC_BLOCK = 64     # Streebog block size (R 50.1.113-2016 §4.1: B = 64 bytes for both lengths)
+
+
+def _hmac(hash_fn, key: bytes, data: bytes) -> bytes:
+    """RFC 2104 HMAC over Streebog. gostcrypto's HMAC refuses keys longer than 64 bytes, whereas
+    the standard hashes them first — and our tokens (vlt_…, 83 characters) are longer."""
+    if len(key) > _HMAC_BLOCK:
+        key = hash_fn(key)
+    key = key + b"\x00" * (_HMAC_BLOCK - len(key))
+    ipad = bytes(b ^ 0x36 for b in key)
+    opad = bytes(b ^ 0x5C for b in key)
+    return hash_fn(opad + hash_fn(ipad + data))
+
+
+def hmac_streebog256(key: bytes, data: bytes) -> bytes:
+    return _hmac(streebog256, key, data)
+
+
+def hmac_streebog512(key: bytes, data: bytes) -> bytes:
+    return _hmac(streebog512, key, data)
+
+
+def kdf_tree_256(key: bytes, label: bytes, seed: bytes, keys: int = 1) -> bytes:
+    """KDF_TREE_GOSTR3411_2012_256 (R 50.1.113-2016 §4.5): K(i) = HMAC256(key, i‖label‖0x00‖seed‖L),
+    i one byte (R = 1), L = 256·keys bits as two bytes big-endian. Returns `keys` × 32 bytes."""
+    if not 1 <= keys <= 255:
+        raise ValueError("keys out of range")
+    L = (256 * keys).to_bytes(2, "big")
+    out = b""
+    for i in range(1, keys + 1):
+        out += hmac_streebog256(key, bytes([i]) + label + b"\x00" + seed + L)
+    return out
+
+
+def pbkdf2_streebog512(password: bytes, salt: bytes, iterations: int, length: int = 32) -> bytes:
+    """PBKDF2 with HMAC_GOSTR3411_2012_512 (R 50.1.111-2016)."""
+    from gostcrypto import gostpbkdf
+    return gostpbkdf.new(password, salt=salt, counter=iterations).derive(length)
+
+
+# ── GOST R 34.10-2012 curve and VKO (backend/gostec.py) ──
+
+# id-tc26-gost-3410-2012-256-paramSetB
+P = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD97
+A = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD94
+B = 0xA6
+Q = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF6C611070995AD10045841B09B761B893
+GX = 0x1
+GY = 0x8D91E471E0989CDA27DF505A453F2B7635294F2DDF23E3B122ACC99C9E9F1E14
+CURVE_NAME = "id-tc26-gost-3410-2012-256-paramSetB"
+
+INF = None
+
+
+def _inv(x: int) -> int:
+    return pow(x % P, P - 2, P)
+
+
+# Jacobian coordinates (X, Y, Z) with x = X/Z², y = Y/Z²: one inversion per scalar multiplication
+# instead of one per step — ~10 ms for a 256-bit scalar in CPython, the affine version takes ~120.
+def _jdouble(pt):
+    X1, Y1, Z1 = pt
+    if Y1 == 0:
+        return (0, 1, 0)
+    S = 4 * X1 * Y1 * Y1 % P
+    Z1sq = Z1 * Z1 % P
+    M = (3 * X1 * X1 + A * Z1sq * Z1sq) % P
+    X3 = (M * M - 2 * S) % P
+    Y3 = (M * (S - X3) - 8 * pow(Y1, 4, P)) % P
+    Z3 = 2 * Y1 * Z1 % P
+    return (X3, Y3, Z3)
+
+
+def _jadd(p1, p2):
+    if p1[2] == 0:
+        return p2
+    if p2[2] == 0:
+        return p1
+    X1, Y1, Z1 = p1
+    X2, Y2, Z2 = p2
+    Z1sq, Z2sq = Z1 * Z1 % P, Z2 * Z2 % P
+    U1, U2 = X1 * Z2sq % P, X2 * Z1sq % P
+    S1, S2 = Y1 * Z2sq * Z2 % P, Y2 * Z1sq * Z1 % P
+    if U1 == U2:
+        if S1 != S2:
+            return (0, 1, 0)
+        return _jdouble(p1)
+    H = (U2 - U1) % P
+    R = (S2 - S1) % P
+    H2 = H * H % P
+    H3 = H2 * H % P
+    X3 = (R * R - H3 - 2 * U1 * H2) % P
+    Y3 = (R * (U1 * H2 - X3) - S1 * H3) % P
+    Z3 = H * Z1 * Z2 % P
+    return (X3, Y3, Z3)
+
+
+def _to_affine(pt):
+    X, Y, Z = pt
+    if Z == 0:
+        return INF
+    zi = _inv(Z)
+    zi2 = zi * zi % P
+    return (X * zi2 % P, Y * zi2 * zi % P)
+
+
+def add(p1, p2):
+    """Affine point addition (tests / small cases)."""
+    if p1 is INF:
+        return p2
+    if p2 is INF:
+        return p1
+    return _to_affine(_jadd((p1[0], p1[1], 1), (p2[0], p2[1], 1)))
+
+
+def mul(k: int, pt):
+    """k·pt by double-and-add in Jacobian coordinates. Not constant-time: the vault's ephemeral
+    scalars are single-use and the client's private key runs on the client's own machine — the same
+    model as the X25519 envelope's libraries."""
+    k %= Q
+    if k == 0 or pt is INF:
+        return INF
+    result = (0, 1, 0)
+    addend = (pt[0], pt[1], 1)
+    while k:
+        if k & 1:
+            result = _jadd(result, addend)
+        addend = _jdouble(addend)
+        k >>= 1
+    return _to_affine(result)
+
+
+def on_curve(pt) -> bool:
+    if pt is INF:
+        return False
+    x, y = pt
+    return 0 <= x < P and 0 <= y < P and (y * y - (x * x * x + A * x + B)) % P == 0
+
+
+def encode_point(pt) -> bytes:
+    x, y = pt
+    return x.to_bytes(32, "little") + y.to_bytes(32, "little")
+
+
+def decode_point(raw: bytes):
+    if len(raw) != 64:
+        raise ValueError("GOST public key must be 64 bytes (X‖Y little-endian)")
+    pt = (int.from_bytes(raw[:32], "little"), int.from_bytes(raw[32:], "little"))
+    if not on_curve(pt):
+        raise ValueError("point is not on the GOST curve")      # prime order (cofactor 1): on the curve ⇒ in the group
+    return pt
+
+
+def generate_private() -> int:
+    while True:
+        d = int.from_bytes(os.urandom(32), "big")
+        if 1 <= d < Q:
+            return d
+
+
+def public_from_private(d: int):
+    return mul(d, (GX, GY))
+
+
+def generate_keypair() -> tuple[bytes, bytes]:
+    """(private 32 bytes big-endian, public 64 bytes X‖Y little-endian)."""
+    d = generate_private()
+    return d.to_bytes(32, "big"), encode_point(public_from_private(d))
+
+
+def vko(private: int, peer, ukm: bytes) -> bytes:
+    """VKO_GOSTR3410_2012_256: Streebog-256 of the shared point UKM·d·Q (little-endian X‖Y)."""
+    if len(ukm) != 8:
+        raise ValueError("UKM must be 8 bytes")
+    u = int.from_bytes(ukm, "little")
+    if u == 0:
+        raise ValueError("UKM must be non-zero")
+    shared = mul((u * private) % Q, peer)
+    if shared is INF:
+        raise ValueError("degenerate shared point")
+    return streebog256(encode_point(shared))

aps_vault-0.41.0/aps_vault.egg-info/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: aps-vault
+Version: 0.41.0
+Summary: Client for APS Vault machine API (service tokens), standard library only
+Author: Konstantin Zhebenev
+License: MIT
+Project-URL: Homepage, https://github.com/kzhebenev/aps-vault
+Project-URL: Documentation, https://github.com/kzhebenev/aps-vault/tree/main/docs
+Project-URL: Source, https://github.com/kzhebenev/aps-vault/tree/main/clients/python
+Project-URL: Changelog, https://github.com/kzhebenev/aps-vault/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/kzhebenev/aps-vault/issues
+Keywords: secrets,vault,secret-manager,service-token,sealed-delivery,gost,ml-kem,post-quantum
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Topic :: Security :: Cryptography
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: sealed
+Requires-Dist: cryptography>=42; extra == "sealed"
+Provides-Extra: gost
+Requires-Dist: cryptography>=42; extra == "gost"
+Requires-Dist: gostcrypto>=1.2; extra == "gost"
+Provides-Extra: pkcs11
+Requires-Dist: cryptography>=42; extra == "pkcs11"
+Requires-Dist: python-pkcs11>=0.10; extra == "pkcs11"
+Provides-Extra: pqc
+Requires-Dist: cryptography>=42; extra == "pqc"
+Requires-Dist: kyber-py>=1.2; extra == "pqc"
+
+# aps-vault (Python)
+
+Standard-library client for the APS Vault machine API. Python 3.9+, no dependencies.
+
+```bash
+pip install ./clients/python          # or: pip install aps-vault (once published)
+```
+
+```python
+import os
+from aps_vault import Vault, VaultError
+
+v = Vault("https://vault.example.com", os.environ["VAULT_TOKEN"])   # or Vault.from_env()
+try:
+    dsn_password = v.get("db-password")
+    smtp = v.get_full("smtp")            # {"name","value","login","updated_at",...}
+except VaultError as e:
+    if e.status == 404: ...
+```
+
+- `get(name)` / `get_full(name)` — cached for `cache_ttl` seconds (default 300). While the
+  vault is unreachable a stale cached value is returned (`fail_open_cache=True`), so a vault
+  restart never takes your service down; the first fetch still fails loudly.
+- `put(name, value, login=..., tags=..., url=...)` — token needs `can_write`.
+- `totp(name)` — current 6-digit code, never cached; token needs `can_read_totp`.
+- `list()`, `health()`.
+- Retries 429/5xx/network with 1 s, 2 s, 4 s back-off.
+
+Tokens: pass via environment (`VAULT_TOKEN`) or a `0600` file (`VAULT_TOKEN_FILE`). Never
+commit one, never log one. `Vault` refuses anything that does not look like a service token.
+
+## Sealed delivery (0.17)
+
+If the token is bound to this application's X25519 public key, values arrive encrypted and the
+client decrypts them in-process (needs the optional extra: `pip install 'aps-vault[sealed]'`):
+
+```bash
+python -m aps_vault keygen          # prints VAULT_CLIENT_KEY (private, keep with the token) and client_public_key (for the token)
+python -m aps_vault keygen --gost   # GOST R 34.10-2012 pair → the vault seals with VKO + Kuznyechik-MGM; needs pip install 'aps-vault[gost]'
+```
+```python
+v = Vault(url, token, client_private_key=os.environ["VAULT_CLIENT_KEY"])   # or just set VAULT_CLIENT_KEY
+v.get("db-password")
+```
+
+Without the key the client raises `VaultError("… sealed values …")` rather than returning the
+envelope; with the wrong key it says so. See `docs/SEALED.md`.

aps_vault-0.41.0/aps_vault.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+aps_vault/__init__.py
+aps_vault/__main__.py
+aps_vault/gost.py
+aps_vault.egg-info/PKG-INFO
+aps_vault.egg-info/SOURCES.txt
+aps_vault.egg-info/dependency_links.txt
+aps_vault.egg-info/requires.txt
+aps_vault.egg-info/top_level.txt

aps_vault-0.41.0/aps_vault.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aps_vault-0.41.0/aps_vault.egg-info/requires.txt

@@ -0,0 +1,15 @@
+
+[gost]
+cryptography>=42
+gostcrypto>=1.2
+
+[pkcs11]
+cryptography>=42
+python-pkcs11>=0.10
+
+[pqc]
+cryptography>=42
+kyber-py>=1.2
+
+[sealed]
+cryptography>=42

aps_vault-0.41.0/aps_vault.egg-info/top_level.txt

@@ -0,0 +1 @@
+aps_vault

aps_vault-0.41.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "aps-vault"
+version = "0.41.0"
+description = "Client for APS Vault machine API (service tokens), standard library only"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = []
+authors = [{ name = "Konstantin Zhebenev" }]
+keywords = ["secrets", "vault", "secret-manager", "service-token", "sealed-delivery", "gost", "ml-kem", "post-quantum"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Security",
+  "Topic :: Security :: Cryptography",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/kzhebenev/aps-vault"
+Documentation = "https://github.com/kzhebenev/aps-vault/tree/main/docs"
+Source = "https://github.com/kzhebenev/aps-vault/tree/main/clients/python"
+Changelog = "https://github.com/kzhebenev/aps-vault/blob/main/CHANGELOG.md"
+Issues = "https://github.com/kzhebenev/aps-vault/issues"
+
+[project.optional-dependencies]
+sealed = ["cryptography>=42"]
+gost = ["cryptography>=42", "gostcrypto>=1.2"]
+pkcs11 = ["cryptography>=42", "python-pkcs11>=0.10"]
+pqc = ["cryptography>=42", "kyber-py>=1.2"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["aps_vault*"]

aps_vault-0.41.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+