envlockup 0.2.0__tar.gz

envlockup-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+*.tgz
+.venv/
+__pycache__/
+*.egg-info/
+build/
+.pytest_cache/

envlockup-0.2.0/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.

envlockup-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,83 @@
+# 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/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "envlockup"
+version = "0.2.0"
+description = "Read envlockup files from Python: encrypted .env files you can commit, decrypted with your SSH or age key."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "denisbilli" }]
+requires-python = ">=3.10"
+dependencies = [
+  "cryptography>=41",
+  "bcrypt>=4", # passphrase-protected OpenSSH keys
+]
+keywords = ["dotenv", "env", "secrets", "encryption", "ssh", "age"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Security :: Cryptography",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/denisbilli/envlockup"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/envlockup"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

envlockup-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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 `)")