envlockup 0.2.0__py3-none-any.whl

envlockup/__init__.py

@@ -0,0 +1,133 @@
+"""Read envlockup files: .env files whose values are encrypted for SSH or age keys.
+
+    import envlockup
+    envlockup.config()          # like python-dotenv's load_dotenv(), decrypting as it goes
+
+The private key is looked for in this order:
+
+    1. ENVLOCKUP_PRIVATE_KEY  the key itself (CI and servers: store it as a single secret)
+    2. ENVLOCKUP_IDENTITY     path to a key file
+    3. ~/.ssh/id_ed25519    your SSH key
+
+1 and 2 are "explicit": when set, nothing else is tried. A passphrase-protected
+SSH key is unlocked with ENVLOCKUP_SSH_PASSPHRASE. ssh-agent is not supported yet
+by the Python package.
+
+Files are created and edited with the envlockup CLI from npm.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import MutableMapping
+
+from ._keys import Identity, parse_identity
+from ._vault import SealedFile
+from .errors import (
+    DecryptError,
+    EnvlockupError,
+    FormatError,
+    NoKeyError,
+    NotARecipientError,
+    RecipientListError,
+    PassphraseRequiredError,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "config",
+    "load",
+    "DecryptError",
+    "EnvlockupError",
+    "FormatError",
+    "NoKeyError",
+    "NotARecipientError",
+    "RecipientListError",
+    "PassphraseRequiredError",
+]
+
+# Removed from the environment once the file is decrypted, so the rest of the
+# application (and anything it starts) never sees the key.
+SECRET_ENV_VARS = ("ENVLOCKUP_PRIVATE_KEY", "ENVLOCKUP_SSH_PASSPHRASE")
+
+
+def _default_path() -> Path:
+    return Path(os.environ.get("ENVLOCKUP_FILE") or ".env")
+
+
+def _find_identity(private_key: str | None, identity_path: str | os.PathLike[str] | None) -> tuple[str, str] | None:
+    """(key text, where it came from), or None."""
+    if private_key:
+        return private_key, "private_key argument"
+    if identity_path:
+        return Path(identity_path).read_text(encoding="utf-8"), str(identity_path)
+    inline = os.environ.get("ENVLOCKUP_PRIVATE_KEY", "").strip()
+    if inline:
+        # CI systems often flatten multi-line secrets; accept literal "\n".
+        return (inline if "\n" in inline else inline.replace("\\n", "\n")), "ENVLOCKUP_PRIVATE_KEY"
+    file = os.environ.get("ENVLOCKUP_IDENTITY")
+    if file:
+        return Path(file).read_text(encoding="utf-8"), file
+    default = Path.home() / ".ssh" / "id_ed25519"
+    if default.is_file():
+        return default.read_text(encoding="utf-8"), str(default)
+    return None
+
+
+def load(
+    path: str | os.PathLike[str] | None = None,
+    *,
+    private_key: str | None = None,
+    identity: str | os.PathLike[str] | None = None,
+    passphrase: str | None = None,
+) -> dict[str, str]:
+    """Decrypt a file and return its variables, without touching os.environ.
+
+    `path` defaults to $ENVLOCKUP_FILE or .env in the current directory. Pass
+    `private_key` (key text) or `identity` (key file path) to skip the default
+    lookup. The private key is only needed when the file has encrypted values.
+    """
+    file = Path(path) if path is not None else _default_path()
+    sealed = SealedFile(file.read_text(encoding="utf-8", errors="replace"))
+    if sealed.has_encrypted_values:
+        found = _find_identity(private_key, identity)
+        if found is None:
+            hint = " ssh-agent is not supported by the Python package yet." if sealed.agent_recipients else ""
+            raise NoKeyError(
+                f"{file} contains encrypted values but no private key was found. "
+                f"Use ~/.ssh/id_ed25519, or set ENVLOCKUP_PRIVATE_KEY or ENVLOCKUP_IDENTITY.{hint}"
+            )
+        text, source = found
+        key: Identity = parse_identity(text, source, passphrase or os.environ.get("ENVLOCKUP_SSH_PASSPHRASE"))
+        sealed.unlock(key)
+    return sealed.decrypt_all()
+
+
+def config(
+    path: str | os.PathLike[str] | None = None,
+    *,
+    override: bool = False,
+    private_key: str | None = None,
+    identity: str | os.PathLike[str] | None = None,
+    passphrase: str | None = None,
+    environ: MutableMapping[str, str] | None = None,
+) -> dict[str, str]:
+    """Load the file into os.environ (or `environ`) and return its variables.
+
+    Variables already set are kept unless `override` is true, as in dotenv. A
+    missing file returns {}; a file that cannot be decrypted raises, because
+    silently starting without secrets is worse.
+    """
+    file = Path(path) if path is not None else _default_path()
+    if not file.is_file():
+        return {}
+    parsed = load(file, private_key=private_key, identity=identity, passphrase=passphrase)
+    target = os.environ if environ is None else environ
+    for name, value in parsed.items():
+        if override or name not in target:
+            target[name] = value
+    # The key has done its job; don't leave it around for the rest of the app.
+    for name in SECRET_ENV_VARS:
+        os.environ.pop(name, None)
+    return parsed

envlockup/__main__.py

@@ -0,0 +1,132 @@
+"""python -m envlockup: read envlockup files from the command line.
+
+Edit them with the envlockup CLI from npm (`npx envlockup set NAME`).
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import SECRET_ENV_VARS, _find_identity, load
+from ._dotenv import format_value
+from ._keys import is_encrypted_ssh_key
+from .errors import EnvlockupError, PassphraseRequiredError
+
+USAGE = """python -m envlockup [-f FILE] [-i KEY] <command>
+
+Commands:
+  get NAME               Print one decrypted value.
+  decrypt [--format json]
+                         Print the whole file decrypted, in dotenv format
+                         (or as a JSON object).
+  run [--override] -- COMMAND [ARGS]...
+                         Run COMMAND with the variables in its environment.
+                         Nothing decrypted is written to disk.
+
+Options:
+  -f, --file FILE        File to use (default: $ENVLOCKUP_FILE or .env)
+  -i, --identity KEY     Private key file (default: $ENVLOCKUP_PRIVATE_KEY,
+                         $ENVLOCKUP_IDENTITY, or ~/.ssh/id_ed25519)
+"""
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="python -m envlockup", usage=USAGE, add_help=True)
+    p.add_argument("-f", "--file")
+    p.add_argument("-i", "--identity")
+    sub = p.add_subparsers(dest="command", required=True)
+    get = sub.add_parser("get")
+    get.add_argument("name")
+    decrypt = sub.add_parser("decrypt")
+    decrypt.add_argument("--format", choices=["dotenv", "json"], default="dotenv")
+    run = sub.add_parser("run")
+    run.add_argument("--override", action="store_true")
+    run.add_argument("argv", nargs=argparse.REMAINDER)
+    return p
+
+
+def _values(args: argparse.Namespace) -> dict[str, str]:
+    try:
+        return load(args.file, identity=args.identity)
+    except PassphraseRequiredError:
+        # Ask interactively, like the Node CLI, when there is someone to ask.
+        if not sys.stdin.isatty():
+            raise
+        found = _find_identity(None, args.identity)
+        if not found or not is_encrypted_ssh_key(found[0]):
+            raise
+        passphrase = getpass.getpass(f"Passphrase for {found[1]}: ")
+        return load(args.file, identity=args.identity, passphrase=passphrase)
+
+
+def _run(command: list[str], env: dict[str, str]) -> int:
+    if os.name == "posix":
+        # Replace this process, so the command gets signals and keeps our PID
+        # (what systemd, supervisord and Docker expect).
+        try:
+            os.execvpe(command[0], command, env)
+        except OSError as err:
+            print(f"envlockup: cannot run {command[0]}: {err.strerror}", file=sys.stderr)
+            return 127
+    # Windows: resolve .exe/.cmd through PATHEXT, then wait for the child.
+    exe = shutil.which(command[0], path=env.get("PATH")) or command[0]
+    try:
+        return subprocess.call([exe, *command[1:]], env=env)
+    except OSError as err:
+        print(f"envlockup: cannot run {command[0]}: {err.strerror}", file=sys.stderr)
+        return 127
+    except KeyboardInterrupt:
+        return 130
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "get":
+            values = _values(args)
+            if args.name not in values:
+                print(f"envlockup: {args.name} is not set", file=sys.stderr)
+                return 1
+            print(values[args.name])
+        elif args.command == "decrypt":
+            values = _values(args)
+            if args.format == "json":
+                print(json.dumps(values, ensure_ascii=False, indent=2))
+            else:
+                lines = []
+                for name, value in values.items():
+                    try:
+                        lines.append(f"{name}={format_value(value)}")
+                    except ValueError:
+                        print(f"envlockup: {name} cannot be written in dotenv syntax (it mixes ', \" and `); use --format json", file=sys.stderr)
+                        return 1
+                if lines:
+                    print("\n".join(lines))
+        elif args.command == "run":
+            command = args.argv[1:] if args.argv[:1] == ["--"] else args.argv
+            if not command:
+                print("usage: python -m envlockup run -- COMMAND [ARGS]...", file=sys.stderr)
+                return 2
+            values = _values(args)
+            env = dict(os.environ)
+            for name in SECRET_ENV_VARS:
+                env.pop(name, None)
+            for name, value in values.items():
+                if args.override or name not in env:
+                    env[name] = value
+            return _run(command, env)
+    except (EnvlockupError, OSError) as err:
+        print(f"envlockup: {err}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

envlockup/_bech32.py

@@ -0,0 +1,56 @@
+# Bech32 (BIP 173) as used by age for `age1...` recipients and
+# `AGE-SECRET-KEY-1...` identities. age does not enforce the 90 character limit.
+
+from __future__ import annotations
+
+_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l"
+_GENERATOR = (0x3B6A57B2, 0x26508E6D, 0x1EA119FA, 0x3D4233DD, 0x2A1462B3)
+
+
+def _polymod(values: list[int]) -> int:
+    chk = 1
+    for v in values:
+        top = chk >> 25
+        chk = ((chk & 0x1FFFFFF) << 5) ^ v
+        for i in range(5):
+            if (top >> i) & 1:
+                chk ^= _GENERATOR[i]
+    return chk
+
+
+def _hrp_expand(hrp: str) -> list[int]:
+    return [ord(c) >> 5 for c in hrp] + [0] + [ord(c) & 31 for c in hrp]
+
+
+def _convert_bits(data: list[int], frm: int, to: int) -> bytes:
+    acc = bits = 0
+    out = []
+    maxv = (1 << to) - 1
+    for value in data:
+        acc = (acc << frm) | value
+        bits += frm
+        while bits >= to:
+            bits -= to
+            out.append((acc >> bits) & maxv)
+    if bits >= frm or ((acc << (to - bits)) & maxv) != 0:
+        raise ValueError("invalid bech32 padding")
+    return bytes(out)
+
+
+def decode(s: str) -> tuple[str, bytes]:
+    if s != s.lower() and s != s.upper():
+        raise ValueError("mixed-case bech32 string")
+    lower = s.lower()
+    pos = lower.rfind("1")
+    if pos < 1 or pos + 7 > len(lower):
+        raise ValueError("invalid bech32 string")
+    hrp = lower[:pos]
+    words = []
+    for c in lower[pos + 1 :]:
+        v = _CHARSET.find(c)
+        if v == -1:
+            raise ValueError("invalid bech32 character")
+        words.append(v)
+    if _polymod(_hrp_expand(hrp) + words) != 1:
+        raise ValueError("invalid bech32 checksum")
+    return hrp, _convert_bits(words[:-6], 5, 8)

envlockup/_dotenv.py

@@ -0,0 +1,95 @@
+# A port of the dotenv 16/17 parser (lib/main.js), so that a file means the same
+# thing to Python as to Node's dotenv and to envlockup. python-dotenv parses
+# differently and is not used.
+#
+# The JavaScript regex is translated by hand, because JavaScript and Python
+# disagree on what \s, \w, ^, $ and . match:
+#
+#   \s  JavaScript's whitespace set (includes U+FEFF, excludes U+001C-U+001F and U+0085)
+#   \w  ASCII letters, digits and _
+#   ^ $ with the m flag, line starts/ends at \n, \r, U+2028 and U+2029
+#   .   anything but those four line terminators
+#
+# The shared test vectors (test/vectors.json) check this against dotenv itself.
+
+from __future__ import annotations
+
+import re
+
+_WS_CHARS = "\t\n\x0b\x0c\r \xa0 " + "".join(chr(c) for c in range(0x2000, 0x200B)) + "

  　"
+_S = "[\t\n\x0b\x0c\r \xa0  - 

  　]"
+_BOL = "(?<![^\n\r

])"  # start of input, or just after a line terminator
+_EOL = "(?![^\n\r

])"  # end of input, or just before a line terminator
+_DOT = "[^\n\r\u2028\u2029]"
+
+# dotenv: /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg
+_LINE = re.compile(
+    _BOL
+    + _S + "*"
+    + "(?:export" + _S + "+)?"
+    + "([A-Za-z0-9_.-]+)"
+    + "(?:" + _S + "*=" + _S + "*?|:" + _S + "+?)"
+    + "("
+    + _S + r"*'(?:\\'|[^'])*'|"
+    + _S + r'*"(?:\\"|[^"])*"|'
+    + _S + r"*`(?:\\`|[^`])*`|"
+    + r"[^#\r\n]+"
+    + ")?"
+    + _S + "*"
+    + "(?:#" + _DOT + "*)?"
+    + _EOL
+)
+
+# dotenv: value.replace(/^(['"`])([\s\S]*)\1$/mg, '$2')
+_QUOTED = re.compile(_BOL + r"(['\"`])([\s\S]*)\1" + _EOL)
+
+
+def split_lines(text: str) -> list[str]:
+    lines = re.split(r"\r\n?|\n", text)
+    if lines and lines[-1] == "":
+        lines.pop()
+    return lines
+
+
+def _unquote(raw: str) -> str:
+    value = raw.strip(_WS_CHARS)
+    quote = value[:1]
+    value = _QUOTED.sub(r"\2", value)
+    if quote == '"':
+        value = value.replace("\\n", "\n").replace("\\r", "\r")
+    return value
+
+
+def parse_entries(lines: list[str]) -> list[tuple[str, str]]:
+    """(name, value) pairs in file order. Later definitions win, as in dotenv."""
+    text = "\n".join(lines)
+    return [(m.group(1), _unquote(m.group(2) or "")) for m in _LINE.finditer(text)]
+
+
+def parse(text: str) -> dict[str, str]:
+    return dict(parse_entries(split_lines(text)))
+
+
+_BARE = re.compile(r"[A-Za-z0-9_./:@%+,=~-]*")
+
+
+def format_value(value: str) -> str:
+    """Serialize a value so that dotenv (and this parser) read it back unchanged.
+
+    Same rules as formatValue in the Node implementation. Raises ValueError for
+    the rare values dotenv's syntax cannot represent.
+    """
+    if _BARE.fullmatch(value):
+        return value
+    # dotenv turns every \r\n or \r into \n before parsing; only the \r escape inside double quotes survives.
+    if "\r" in value:
+        if '"' not in value and not re.search(r"\\[nr]", value):
+            return '"' + value.replace("\r", "\\r") + '"'
+        raise ValueError("this value cannot be written as a dotenv value (it has a carriage return and a \" or \\n)")
+    if "'" not in value:
+        return f"'{value}'"
+    if '"' not in value and not re.search(r"\\[nr]", value):
+        return f'"{value}"'
+    if "`" not in value:
+        return f"`{value}`"
+    raise ValueError("this value cannot be written as a dotenv value (it mixes ', \" and `)")

envlockup/_keys.py

@@ -0,0 +1,270 @@
+# Identities (private keys that can decrypt a file) and the age v1 stanzas
+# they open (https://age-encryption.org/v1):
+#
+#   ssh-ed25519  an OpenSSH ed25519 key file, as in age
+#   X25519       a native age key (AGE-SECRET-KEY-1...), for CI and servers;
+#                also what an ssh-agent recipient line wraps for
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import re
+import struct
+from dataclasses import dataclass
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey, X25519PublicKey
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+
+from . import _bech32
+from .errors import EnvlockupError, PassphraseRequiredError
+
+X25519_LABEL = b"age-encryption.org/v1/X25519"
+SSH_ED25519_LABEL = b"age-encryption.org/v1/ssh-ed25519"
+_ZERO_NONCE = bytes(12)
+
+
+# --- Primitives ---------------------------------------------------------------------
+
+
+def hkdf(ikm: bytes, salt: bytes, info: bytes, length: int = 32) -> bytes:
+    """HKDF-SHA256 (RFC 5869). An empty salt is equivalent to HashLen zero bytes."""
+    prk = hmac.new(salt, ikm, hashlib.sha256).digest()
+    out, prev, i = b"", b"", 1
+    while len(out) < length:
+        prev = hmac.new(prk, prev + info + bytes([i]), hashlib.sha256).digest()
+        out += prev
+        i += 1
+    return out[:length]
+
+
+def open_sealed(key: bytes, ciphertext: bytes, aad: bytes | None = None) -> bytes:
+    """ChaCha20-Poly1305 with a zero nonce. Raises InvalidTag."""
+    if len(ciphertext) < 16:
+        raise InvalidTag()
+    return ChaCha20Poly1305(key).decrypt(_ZERO_NONCE, ciphertext, aad)
+
+
+def _x25519(scalar: bytes, point: bytes) -> bytes:
+    """X25519(scalar, point). Rejects the all-zero output, as required by age."""
+    if len(point) != 32:
+        raise ValueError("X25519 point must be 32 bytes")
+    shared = X25519PrivateKey.from_private_bytes(scalar).exchange(X25519PublicKey.from_public_bytes(point))
+    if shared == bytes(32):
+        raise ValueError("invalid X25519 point (low order)")
+    return shared
+
+
+def _x25519_base(scalar: bytes) -> bytes:
+    return X25519PrivateKey.from_private_bytes(scalar).public_key().public_bytes(
+        serialization.Encoding.Raw, serialization.PublicFormat.Raw
+    )
+
+
+def b64(data: bytes) -> str:
+    return base64.b64encode(data).decode().rstrip("=")
+
+
+def unb64(s: str) -> bytes:
+    """Strict unpadded base64: only the canonical encoding of the bytes is accepted."""
+    if not re.fullmatch(r"[A-Za-z0-9+/]*", s) or len(s) % 4 == 1:
+        raise ValueError("invalid base64")
+    raw = base64.b64decode(s + "=" * (-len(s) % 4))
+    if base64.b64encode(raw).rstrip(b"=").decode() != s:
+        raise ValueError("invalid base64")
+    return raw
+
+
+# --- SSH wire format --------------------------------------------------------------
+
+
+class _Reader:
+    def __init__(self, buf: bytes) -> None:
+        self.buf = buf
+        self.pos = 0
+
+    def u32(self) -> int:
+        if self.pos + 4 > len(self.buf):
+            raise ValueError("truncated SSH key")
+        (v,) = struct.unpack_from(">I", self.buf, self.pos)
+        self.pos += 4
+        return v
+
+    def string(self) -> bytes:
+        n = self.u32()
+        if self.pos + n > len(self.buf):
+            raise ValueError("truncated SSH key")
+        v = self.buf[self.pos : self.pos + n]
+        self.pos += n
+        return v
+
+    @property
+    def done(self) -> bool:
+        return self.pos == len(self.buf)
+
+
+def _ssh_string(data: bytes) -> bytes:
+    return struct.pack(">I", len(data)) + data
+
+
+def ssh_key_type(wire: bytes) -> str:
+    return _Reader(wire).string().decode()
+
+
+def ed25519_from_wire(wire: bytes) -> bytes:
+    r = _Reader(wire)
+    key_type = r.string().decode()
+    if key_type != "ssh-ed25519":
+        raise ValueError(f"unsupported SSH key type {key_type} (only ssh-ed25519 is supported)")
+    key = r.string()
+    if len(key) != 32 or not r.done:
+        raise ValueError("malformed ssh-ed25519 key")
+    if not is_ed25519_point(key):
+        raise ValueError("malformed ssh-ed25519 key (not a point on the curve)")
+    return key
+
+
+_P = 2**255 - 19
+_D = -121665 * pow(121666, _P - 2, _P) % _P
+
+
+def is_ed25519_point(public_key: bytes) -> bool:
+    """Whether 32 bytes decode to a point on the Ed25519 curve (RFC 8032, 5.1.3)."""
+    if len(public_key) != 32:
+        return False
+    y = int.from_bytes(public_key, "little") & ((1 << 255) - 1)
+    if y >= _P:
+        return False
+    x2 = (y * y - 1) * pow(_D * y * y + 1, _P - 2, _P) % _P
+    if x2 == 0:
+        return public_key[31] >> 7 == 0
+    return pow(x2, (_P - 1) // 2, _P) == 1
+
+
+def decode_age_recipient(s: str) -> bytes:
+    hrp, data = _bech32.decode(s)
+    if hrp != "age" or len(data) != 32:
+        raise ValueError("invalid age recipient")
+    return data
+
+
+def fingerprint(material: bytes) -> str:
+    """Matches `ssh-keygen -l` for SSH keys, and the Node CLI for age keys."""
+    return "SHA256:" + b64(hashlib.sha256(material).digest())
+
+
+# --- Identities -------------------------------------------------------------------
+
+
+@dataclass
+class Stanza:
+    type: str
+    args: list[str]
+    body: bytes
+
+
+class Identity:
+    fingerprint: str
+
+    def unwrap(self, stanza: Stanza) -> bytes | None:
+        raise NotImplementedError
+
+
+class X25519Identity(Identity):
+    def __init__(self, secret: bytes) -> None:
+        self._secret = secret
+        self._public = _x25519_base(secret)
+        self.fingerprint = fingerprint(self._public)
+
+    def unwrap(self, stanza: Stanza) -> bytes | None:
+        if stanza.type != "X25519" or len(stanza.args) != 1:
+            return None
+        try:
+            share = unb64(stanza.args[0])
+            shared = _x25519(self._secret, share)
+            key = hkdf(shared, share + self._public, X25519_LABEL)
+            return open_sealed(key, stanza.body)
+        except (ValueError, InvalidTag):
+            return None
+
+
+class SSHEd25519Identity(Identity):
+    def __init__(self, public_key: bytes, seed: bytes) -> None:
+        self._wire = _ssh_string(b"ssh-ed25519") + _ssh_string(public_key)
+        # age's X25519 scalar for an Ed25519 seed. Its public half equals the
+        # Ed25519 public key mapped to Curve25519, which the stanza is wrapped for.
+        self._secret = hashlib.sha512(seed).digest()[:32]
+        self._ours = _x25519_base(self._secret)
+        self._tag = b64(hashlib.sha256(self._wire).digest()[:4])
+        self.fingerprint = fingerprint(self._wire)
+
+    def unwrap(self, stanza: Stanza) -> bytes | None:
+        if stanza.type != "ssh-ed25519" or len(stanza.args) != 2 or stanza.args[0] != self._tag:
+            return None
+        try:
+            share = unb64(stanza.args[1])
+            tweak = hkdf(b"", self._wire, SSH_ED25519_LABEL)
+            shared = _x25519(tweak, _x25519(self._secret, share))
+            key = hkdf(shared, share + self._ours, SSH_ED25519_LABEL)
+            return open_sealed(key, stanza.body)
+        except (ValueError, InvalidTag):
+            return None
+
+
+_OPENSSH = re.compile(r"-----BEGIN OPENSSH PRIVATE KEY-----([\s\S]*?)-----END OPENSSH PRIVATE KEY-----")
+_MAGIC = b"openssh-key-v1\0"
+
+
+def _find_age_secret(text: str) -> str | None:
+    for line in re.split(r"\r?\n", text):
+        if line.strip().startswith("AGE-SECRET-KEY-1"):
+            return line.strip()
+    return None
+
+
+def is_encrypted_ssh_key(text: str) -> bool:
+    if _find_age_secret(text):
+        return False
+    m = _OPENSSH.search(text)
+    if not m:
+        return False
+    raw = base64.b64decode(re.sub(r"\s+", "", m.group(1)))
+    return raw.startswith(_MAGIC) and _Reader(raw[len(_MAGIC) :]).string() != b"none"
+
+
+def parse_identity(text: str, source: str, passphrase: str | None = None) -> Identity:
+    """An OpenSSH ed25519 key file, or an age identity (AGE-SECRET-KEY-1..., optionally in an age-keygen file)."""
+    age = _find_age_secret(text)
+    if age:
+        try:
+            hrp, data = _bech32.decode(age)
+        except ValueError:
+            hrp, data = "", b""
+        if hrp != "age-secret-key-" or len(data) != 32:
+            raise EnvlockupError(f"{source}: invalid age secret key")
+        return X25519Identity(data)
+
+    m = _OPENSSH.search(text)
+    if not m:
+        raise EnvlockupError(f"{source} is not an OpenSSH private key")
+    encrypted = is_encrypted_ssh_key(text)
+    if encrypted and not passphrase:
+        raise PassphraseRequiredError(source)
+    try:
+        key = serialization.load_ssh_private_key(
+            m.group(0).encode(), password=passphrase.encode() if encrypted and passphrase else None
+        )
+    except ValueError as err:
+        raise EnvlockupError(f"wrong passphrase for {source}" if encrypted else f"{source} is corrupted ({err})") from None
+    except Exception as err:  # unsupported cipher or key format
+        raise EnvlockupError(f"{source}: {err}") from None
+    if not isinstance(key, Ed25519PrivateKey):
+        raise EnvlockupError(f"{source} is not an ssh-ed25519 key")
+    raw = serialization.PrivateFormat.Raw
+    seed = key.private_bytes(serialization.Encoding.Raw, raw, serialization.NoEncryption())
+    public = key.public_key().public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+    return SSHEd25519Identity(public, seed)

envlockup/_vault.py

@@ -0,0 +1,211 @@
+# Reading an envlockup file (see docs/DESIGN.md in the repository):
+#
+#   #envlockup:v1 ...
+#   #envlockup:recipient <type> <public key> <stanza args...> <wrapped key> [label]
+#   API_KEY=envlockup:v1:<base64url(salt || ciphertext || tag)>
+#   PORT=3000
+#
+# Writing (set, add, remove, ...) is done with the envlockup CLI from npm.
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import re
+
+from cryptography.exceptions import InvalidTag
+
+from ._dotenv import parse_entries, split_lines
+from ._keys import (
+    Identity,
+    Stanza,
+    decode_age_recipient,
+    ed25519_from_wire,
+    hkdf,
+    open_sealed,
+    ssh_key_type,
+    unb64,
+)
+from .errors import DecryptError, FormatError, NotARecipientError, RecipientListError
+
+HEADER = "#envlockup:"
+VERSION_LINE = "#envlockup:v1"
+RECIPIENT_LINE = "#envlockup:recipient "
+MAC_LINE = "#envlockup:mac "
+VALUE_PREFIX = "envlockup:v1:"
+VALUE_INFO = b"github.com/denisbilli/envlockup/v1/value"
+RECIPIENTS_INFO = b"github.com/denisbilli/envlockup/v1/recipients"
+
+# Per recipient type: how many tokens the public key takes, the stanza it uses
+# and how many stanza arguments follow.
+_LINE_LAYOUT = {
+    "ssh-ed25519": (1, "ssh-ed25519", 2),
+    "X25519": (1, "X25519", 1),
+    "ssh-agent": (3, "X25519", 1),
+}
+_WS = re.compile(r"[\s]+")
+
+
+def is_encrypted_value(value: str) -> bool:
+    return value.startswith(VALUE_PREFIX)
+
+
+def _is_version_line(line: str) -> bool:
+    return line == VERSION_LINE or line.startswith(VERSION_LINE + " ")
+
+
+def _check_recipient(kind: str, tokens: list[str]) -> None:
+    """Validate the public key on a recipient line, as the Node implementation does."""
+    if kind == "X25519":
+        if not tokens[0].startswith("age1"):
+            raise ValueError("not an age recipient")
+        decode_age_recipient(tokens[0])
+    elif kind == "ssh-ed25519":
+        ed25519_from_wire(unb64(tokens[0].rstrip("=")))
+    else:
+        decode_age_recipient(tokens[0])
+        if ssh_key_type(unb64(tokens[2].rstrip("="))) != tokens[1]:
+            raise ValueError("SSH key type mismatch")
+
+
+def _parse_recipient_line(line: str) -> Stanza:
+    parts = _WS.split(line[len(RECIPIENT_LINE) :].strip())
+    layout = _LINE_LAYOUT.get(parts[0])
+    if not layout or len(parts) < 2 + layout[0] + layout[2]:
+        raise FormatError(f"malformed envlockup recipient line: {line}")
+    key_tokens, stanza_type, n_args = layout
+    key_end = 1 + key_tokens
+    stanza_end = key_end + n_args
+    try:
+        _check_recipient(parts[0], parts[1:key_end])
+        return Stanza(stanza_type, parts[key_end:stanza_end], unb64(parts[stanza_end]))
+    except (ValueError, UnicodeDecodeError) as err:
+        raise FormatError(f"malformed envlockup recipient line ({err}): {line}") from None
+
+
+def _recipients_mac(data_key: bytes, lines: list[str]) -> str:
+    """HMAC over the recipient lines as they appear in the file, each prefixed with its length."""
+    mac = hmac.new(hkdf(data_key, b"", RECIPIENTS_INFO), digestmod=hashlib.sha256)
+    for line in lines:
+        raw = line.encode("utf-8")
+        mac.update(len(raw).to_bytes(4, "big"))
+        mac.update(raw)
+    return base64.urlsafe_b64encode(mac.digest()).rstrip(b"=").decode()
+
+
+def _value_aad(name: str) -> bytes:
+    return (VALUE_PREFIX + name).encode()
+
+
+def _decrypt_value(data_key: bytes, name: str, value: str) -> str:
+    encoded = value[len(VALUE_PREFIX) :]
+    raw = b""
+    # Strict: unpadded base64url in its canonical form only, as in every implementation.
+    if re.fullmatch(r"[A-Za-z0-9_-]*", encoded) and len(encoded) % 4 != 1:
+        raw = base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4))
+        if base64.urlsafe_b64encode(raw).rstrip(b"=").decode() != encoded:
+            raw = b""
+    if len(raw) < 32:
+        raise DecryptError(f"{name}: malformed encrypted value")
+    key = hkdf(data_key, raw[:16], VALUE_INFO)
+    try:
+        return open_sealed(key, raw[16:], _value_aad(name)).decode("utf-8", errors="replace")
+    except InvalidTag:
+        raise DecryptError(
+            f"{name}: cannot decrypt. The value was changed or moved from another variable, or it was "
+            "encrypted before the data key changed on another branch (a `remove` merged with a `set`). "
+            f"Set it again with `envlockup set {name}`."
+        ) from None
+
+
+class SealedFile:
+    """A parsed envlockup (or plain dotenv) file."""
+
+    def __init__(self, text: str) -> None:
+        lines = split_lines(text)
+        self.sealed = any(_is_version_line(line) for line in lines)
+        self.stanzas: list[Stanza] = []
+        self.agent_recipients = 0
+        self._recipient_lines: list[str] = []
+        macs = [line[len(MAC_LINE) :].strip() for line in lines if line.startswith(MAC_LINE)]
+        if len(macs) > 1:
+            raise FormatError("envlockup file has more than one #envlockup:mac line")
+        self._mac = macs[0] if macs else None
+        for line in lines:
+            if line.startswith(RECIPIENT_LINE):
+                self.stanzas.append(_parse_recipient_line(line))
+                self._recipient_lines.append(line)
+                if line[len(RECIPIENT_LINE) :].lstrip().startswith("ssh-agent "):
+                    self.agent_recipients += 1
+            elif line.startswith(HEADER) and not _is_version_line(line) and not line.startswith(MAC_LINE):
+                raise FormatError(f"unsupported envlockup header line (is envlockup up to date?): {line}")
+        if self.sealed and not self.stanzas:
+            raise FormatError("envlockup file has no recipients")
+        self.entries = parse_entries(lines)
+        self._data_key: bytes | None = None
+
+    @property
+    def has_encrypted_values(self) -> bool:
+        return any(is_encrypted_value(v) for _, v in self.entries)
+
+    def unlock(self, identity: Identity) -> None:
+        """Recover the data key with `identity`, check that every value decrypts and
+        that the recipient list is the one last signed with the data key."""
+        # Anyone can write a stanza for a public key, so a key that unwraps but does
+        # not decrypt the values may be a forgery placed before the real stanza.
+        failure: Exception | None = None
+        list_failure: RecipientListError | None = None
+        for stanza in self.stanzas:
+            key = identity.unwrap(stanza)
+            if key is None:
+                continue
+            try:
+                if len(key) != 32:
+                    raise FormatError("malformed data key")
+                for name, value in self.entries:
+                    if is_encrypted_value(value):
+                        _decrypt_value(key, name, value)
+            except (FormatError, DecryptError) as err:
+                failure = failure or err
+                continue
+            expected = _recipients_mac(key, self._recipient_lines)
+            if self._mac is None or not hmac.compare_digest(self._mac.encode(), expected.encode()):
+                list_failure = list_failure or RecipientListError(missing=self._mac is None)
+                continue
+            self._data_key = key
+            return
+        if list_failure is not None:
+            raise list_failure
+        if failure is not None:
+            raise failure
+        raise NotARecipientError(identity.fingerprint)
+
+    def plaintext_overrides(self) -> list[str]:
+        """Names defined in plaintext after an encrypted definition of the same name."""
+        encrypted: set[str] = set()
+        found: list[str] = []
+        for name, value in self.entries:
+            if is_encrypted_value(value):
+                encrypted.add(name)
+            elif name in encrypted and name not in found:
+                found.append(name)
+        return found
+
+    def decrypt_all(self) -> dict[str, str]:
+        """All variables, decrypted. Later definitions win, as in dotenv, except that a
+        plaintext definition after an encrypted one is refused: it needs no key to write."""
+        for name in self.plaintext_overrides():
+            raise FormatError(
+                f"{name} is encrypted, then set again in plaintext further down the file. "
+                "Anyone who can edit the file can add such a line, so it is not used. "
+                f"Delete the line you don't want, or run `envlockup set {name}`."
+            )
+        out: dict[str, str] = {}
+        for name, value in self.entries:
+            if is_encrypted_value(value):
+                if self._data_key is None:
+                    raise DecryptError("the file is locked: a private key is needed to read encrypted values")
+                value = _decrypt_value(self._data_key, name, value)
+            out[name] = value
+        return out

envlockup/errors.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+
+class EnvlockupError(Exception):
+    """Base class for every envlockup error."""
+
+
+class FormatError(EnvlockupError):
+    """The file's envlockup lines are malformed, or from a newer version."""
+
+
+class DecryptError(EnvlockupError):
+    """A value does not decrypt: it was changed, or moved from another variable."""
+
+
+class RecipientListError(EnvlockupError):
+    """The recipient lines are not the ones last signed by someone who could decrypt the file."""
+
+    def __init__(self, missing: bool = False) -> None:
+        super().__init__(
+            (
+                "the file has no #envlockup:mac line, so nobody can tell whether its recipient list was changed. "
+                if missing
+                else "the recipient list was changed by someone who could not decrypt the file "
+                "(a #envlockup:recipient line was added, removed or edited). "
+            )
+            + "Compare `envlockup recipients` with a version you trust; "
+            "if every key is one you expect, run `envlockup recipients --accept`."
+        )
+        self.missing = missing
+
+
+class NotARecipientError(EnvlockupError):
+    """The private key is not one the file is encrypted for."""
+
+    def __init__(self, fingerprint: str) -> None:
+        super().__init__(
+            f"this file is not encrypted for your key ({fingerprint}). "
+            "Run `npx envlockup pubkey` and send the line it prints to someone who can open the file, "
+            "so they can run `npx envlockup add` with it."
+        )
+        self.fingerprint = fingerprint
+
+
+class NoKeyError(EnvlockupError):
+    """The file has encrypted values and no private key was found."""
+
+
+class PassphraseRequiredError(EnvlockupError):
+    """The SSH key is protected by a passphrase and none was given."""
+
+    def __init__(self, source: str) -> None:
+        super().__init__(f"the SSH key {source} is protected by a passphrase: set ENVLOCKUP_SSH_PASSPHRASE")
+        self.source = source

envlockup-0.2.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.5
+Name: envlockup
+Version: 0.2.0
+Summary: Read envlockup files from Python: encrypted .env files you can commit, decrypted with your SSH or age key.
+Project-URL: Homepage, https://github.com/denisbilli/envlockup
+Author: denisbilli
+License-Expression: MIT
+License-File: LICENSE
+Keywords: age,dotenv,encryption,env,secrets,ssh
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: bcrypt>=4
+Requires-Dist: cryptography>=41
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# envlockup for Python
+
+Read [envlockup](https://github.com/denisbilli/envlockup) files from Python, without
+Node.js. envlockup files are `.env` files whose values are encrypted, so they can be
+committed; they are decrypted with your SSH key or a dedicated age key.
+
+```sh
+pip install envlockup
+```
+
+The package is imported as `envlockup`. It only reads files: create and edit them
+with the envlockup CLI from npm (`npx envlockup init`, `npx envlockup set NAME`, ...).
+
+## Usage
+
+At the top of your entry point (`manage.py`, `wsgi.py`, `asgi.py`, `celery.py`,
+...), before anything reads settings:
+
+```python
+import envlockup
+envlockup.config()  # loads .env into os.environ, decrypting it
+```
+
+Variables already in the environment win, as with python-dotenv; pass
+`override=True` to change that. A missing file is ignored; a file that cannot be
+decrypted raises, because starting without secrets is worse.
+
+Other options:
+
+```python
+envlockup.config(BASE_DIR / ".env")        # explicit path (default: $ENVLOCKUP_FILE or ./.env)
+values = envlockup.load(".env")            # a dict, os.environ untouched
+envlockup.load(".env", identity="/etc/app/key", passphrase="...")
+```
+
+**python-decouple** reads `os.environ` before the `.env` file, so calling
+`envlockup.config()` first is all it takes: `config("SECRET_KEY")` returns the
+decrypted value.
+
+Or, without touching the code, run the app through envlockup:
+
+```sh
+python -m envlockup run -- gunicorn app.wsgi
+```
+
+On Linux and macOS the command replaces the envlockup process (same PID, signals go
+straight to it), which suits systemd, supervisord and Docker.
+
+## Keys
+
+The private key is looked for in this order:
+
+1. `ENVLOCKUP_PRIVATE_KEY`: the key itself. For servers and CI, create one with
+   `npx envlockup keygen` and store the printed `AGE-SECRET-KEY-1...`.
+2. `ENVLOCKUP_IDENTITY`: path to a key file.
+3. `~/.ssh/id_ed25519`.
+
+When 1 or 2 is set, nothing else is tried. A passphrase-protected SSH key is
+unlocked with `ENVLOCKUP_SSH_PASSPHRASE` (or a prompt, in `python -m envlockup`).
+`config()` and `run` remove `ENVLOCKUP_PRIVATE_KEY` and `ENVLOCKUP_SSH_PASSPHRASE`
+from the environment once the file is decrypted.
+
+ssh-agent is not supported by the Python package yet.
+
+## Command line
+
+```
+python -m envlockup [-f FILE] [-i KEY] get NAME
+python -m envlockup [-f FILE] [-i KEY] decrypt [--format json]
+python -m envlockup [-f FILE] [-i KEY] run [--override] -- COMMAND [ARGS]...
+```
+
+## Compatibility
+
+Files are parsed exactly like Node's `dotenv` package (and the envlockup CLI), not
+like python-dotenv. The test suite runs the same vectors as the Node
+implementation (`test/vectors.json` in the repository), generated with the real
+`dotenv` package.
+
+The file format is described in
+[docs/DESIGN.md](https://github.com/denisbilli/envlockup/blob/main/docs/DESIGN.md), and
+what it protects against in
+[docs/THREAT_MODEL.md](https://github.com/denisbilli/envlockup/blob/main/docs/THREAT_MODEL.md).

envlockup-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+envlockup/__init__.py,sha256=Y-q_JX1uZzo7b5M3-agqm9PURr_cwjciMZXMo60rP6M,4883
+envlockup/__main__.py,sha256=KDqL6ZnYDkb7xLd79-Ap3UlR5N8AixgkmViisOKAmF0,4935
+envlockup/_bech32.py,sha256=oiUukNVIYRYTvaYUigi7zFXNpV26t4VPRymAxSzf1QQ,1717
+envlockup/_dotenv.py,sha256=elxO60Oru3wDSuxPpcPMTrY8pL4KGW7xJk9yGB_klz4,3413
+envlockup/_keys.py,sha256=lIPM0vRLqd9KFF3-tKw5ibM2oZIyojUyuXRnd-W3NFA,9449
+envlockup/_vault.py,sha256=ZDmVNplSt5t_shOJRE3Rceb1-odo-CTeka7MwJwicDg,8706
+envlockup/errors.py,sha256=n-XqK1SLC4HRmIENQrSpBbqinw9vyPV2IbUoIUeRWjU,2002
+envlockup/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+envlockup-0.2.0.dist-info/METADATA,sha256=7g4zajKkVzqrvi-IVY9c2pycL_nLjn8tvbTPkSzBpAY,3586
+envlockup-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+envlockup-0.2.0.dist-info/licenses/LICENSE,sha256=xxl9tDe-E_kjwmMMOD_PERRidS8vTfU4UFuJk9vb0aA,1067
+envlockup-0.2.0.dist-info/RECORD,,

envlockup-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

envlockup-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 denisbilli
+
+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.