sealedlog 0.1.0__tar.gz

sealedlog-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.3
+Name: sealedlog
+Version: 0.1.0
+Summary: Encrypted, append-only, line-oriented JSON log
+Author: Louis Maddox
+Author-email: Louis Maddox <louismmx@gmail.com>
+Requires-Dist: pynacl>=1.5
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# sealedlog
+
+An encrypted, append-only, line-oriented log for JSON records — think SQLite
+for encrypted append-only JSON logs, minus the SQL. Small, embeddable, no
+daemon, no external services: just a file format and the code to read and
+write it correctly.
+
+- Appending a record is a byte-append to the file — no rewriting, no
+  reordering. Git diffs and merges cleanly on files built this way.
+- Each line decrypts independently. A corrupted or truncated line doesn't
+  block reading the lines before or after it.
+- Lines are bound to the logical stream they were written for. A line copied
+  from one stream into another fails to authenticate, even under the correct
+  key.
+- The key comes from a passphrase via Argon2id, and a wrong passphrase is
+  detected immediately and unambiguously.
+
+See [docs/FORMAT.md](docs/FORMAT.md) for the on-disk format and threat model.
+
+## Usage
+
+```python
+from pathlib import Path
+from sealedlog import SealedLog, Vault
+
+vault = Vault.create("correct horse battery staple", namespace="myapp")
+key = vault.unlock("correct horse battery staple", namespace="myapp")
+
+log = SealedLog(Path("events.jsonl.enc"), key, "orders", namespace="myapp")
+log.append({"order_id": 1, "total": 42})
+
+for record in log:
+    print(record)
+```
+
+`namespace` is your application's own identifier — it, the stream ID, and the
+library's format version are all folded into the authenticated data for every
+line, so two different applications never accidentally produce
+cross-compatible ciphertexts.
+
+## Non-goals
+
+`sealedlog` doesn't know what a "user" or "owner" is, doesn't validate record
+schemas, doesn't fold or merge records, doesn't decide where files live, and
+doesn't coordinate concurrent writers to the same file. All of that is
+application-level policy built on top of a plain sequence of records.
+
+## Development
+
+```sh
+uv sync --all-groups
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```

sealedlog-0.1.0/README.md

@@ -0,0 +1,56 @@
+# sealedlog
+
+An encrypted, append-only, line-oriented log for JSON records — think SQLite
+for encrypted append-only JSON logs, minus the SQL. Small, embeddable, no
+daemon, no external services: just a file format and the code to read and
+write it correctly.
+
+- Appending a record is a byte-append to the file — no rewriting, no
+  reordering. Git diffs and merges cleanly on files built this way.
+- Each line decrypts independently. A corrupted or truncated line doesn't
+  block reading the lines before or after it.
+- Lines are bound to the logical stream they were written for. A line copied
+  from one stream into another fails to authenticate, even under the correct
+  key.
+- The key comes from a passphrase via Argon2id, and a wrong passphrase is
+  detected immediately and unambiguously.
+
+See [docs/FORMAT.md](docs/FORMAT.md) for the on-disk format and threat model.
+
+## Usage
+
+```python
+from pathlib import Path
+from sealedlog import SealedLog, Vault
+
+vault = Vault.create("correct horse battery staple", namespace="myapp")
+key = vault.unlock("correct horse battery staple", namespace="myapp")
+
+log = SealedLog(Path("events.jsonl.enc"), key, "orders", namespace="myapp")
+log.append({"order_id": 1, "total": 42})
+
+for record in log:
+    print(record)
+```
+
+`namespace` is your application's own identifier — it, the stream ID, and the
+library's format version are all folded into the authenticated data for every
+line, so two different applications never accidentally produce
+cross-compatible ciphertexts.
+
+## Non-goals
+
+`sealedlog` doesn't know what a "user" or "owner" is, doesn't validate record
+schemas, doesn't fold or merge records, doesn't decide where files live, and
+doesn't coordinate concurrent writers to the same file. All of that is
+application-level policy built on top of a plain sequence of records.
+
+## Development
+
+```sh
+uv sync --all-groups
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```

sealedlog-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "sealedlog"
+version = "0.1.0"
+description = "Encrypted, append-only, line-oriented JSON log"
+readme = "README.md"
+authors = [
+    { name = "Louis Maddox", email = "louismmx@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pynacl>=1.5",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.13,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.6",
+    "ty>=0.0.1a1",
+    "pytest>=8",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sealedlog-0.1.0/src/sealedlog/__init__.py

@@ -0,0 +1,26 @@
+"""sealedlog: an encrypted, append-only, line-oriented JSON log.
+
+Each line is independently authenticated and bound to the logical stream it
+was written for, so a corrupted line doesn't block reading its neighbors and
+a line copied between streams fails to authenticate. See docs/FORMAT.md for
+the on-disk format and threat model.
+"""
+
+from sealedlog import aead
+from sealedlog.errors import AuthenticationError, SealError, WrongPassphraseError
+from sealedlog.log import LineFailure, SealedLog
+from sealedlog.vault import Vault
+
+seal = aead.seal
+open_ = aead.open_
+
+__all__ = [
+    "AuthenticationError",
+    "LineFailure",
+    "SealedLog",
+    "SealError",
+    "Vault",
+    "WrongPassphraseError",
+    "open_",
+    "seal",
+]

sealedlog-0.1.0/src/sealedlog/_aad.py

@@ -0,0 +1,27 @@
+"""AAD construction: binds a sealed line to the library format version, the
+caller's namespace, and the stream it belongs to.
+
+Fields are length-prefixed rather than joined with a delimiter, so no choice
+of namespace or stream_id — including one containing the delimiter a naive
+scheme would use — can make two distinct (namespace, stream_id) pairs collide
+on the same AAD bytes. See docs/FORMAT.md for the full rationale.
+"""
+
+from __future__ import annotations
+
+FORMAT_VERSION = 1
+VERIFIER_STREAM_ID = "verifier"
+VERIFIER_PLAINTEXT = b"sealedlog-verify"
+
+
+def build_aad(namespace: str, stream_id: str) -> bytes:
+    ns = namespace.encode("utf-8")
+    sid = stream_id.encode("utf-8")
+    return (
+        b"sealedlog"
+        + FORMAT_VERSION.to_bytes(2, "big")
+        + len(ns).to_bytes(4, "big")
+        + ns
+        + len(sid).to_bytes(4, "big")
+        + sid
+    )

sealedlog-0.1.0/src/sealedlog/aead.py

@@ -0,0 +1,47 @@
+"""Stateless byte-level AEAD primitive: XChaCha20-Poly1305 with a fresh random
+nonce per call. No file I/O, no notion of a "stream" or a "key derivation" —
+just seal bytes under a key and associated data, and open them again.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import os
+
+import nacl.bindings as sodium
+import nacl.exceptions
+
+from sealedlog.errors import AuthenticationError
+
+KEY_SIZE = sodium.crypto_aead_xchacha20poly1305_ietf_KEYBYTES
+NONCE_SIZE = sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES
+
+
+def seal(key: bytes, aad: bytes, plaintext: bytes) -> str:
+    """Encrypt `plaintext` under `key`, bound to `aad`. Returns
+    base64(nonce‖ciphertext‖tag).
+    """
+    nonce = os.urandom(NONCE_SIZE)
+    ct = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(plaintext, aad, nonce, key)
+    return base64.b64encode(nonce + ct).decode("ascii")
+
+
+def open_(key: bytes, aad: bytes, sealed: str) -> bytes:
+    """Decrypt a sealed line, verifying it was sealed under `key` and `aad`.
+
+    Raises AuthenticationError on any authentication failure or malformed
+    input (bad base64, too short to contain a nonce) — one error type,
+    regardless of which of those it was.
+    """
+    try:
+        raw = base64.b64decode(sealed, validate=True)
+    except (ValueError, binascii.Error) as e:
+        raise AuthenticationError(f"not valid base64: {e}") from e
+    if len(raw) < NONCE_SIZE:
+        raise AuthenticationError("sealed line too short")
+    nonce, ct = raw[:NONCE_SIZE], raw[NONCE_SIZE:]
+    try:
+        return sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(ct, aad, nonce, key)
+    except nacl.exceptions.CryptoError as e:
+        raise AuthenticationError(f"failed to authenticate line: {e}") from e

sealedlog-0.1.0/src/sealedlog/errors.py

@@ -0,0 +1,17 @@
+"""Exception hierarchy for sealedlog."""
+
+
+class SealError(Exception):
+    """Base for all sealedlog errors."""
+
+
+class WrongPassphraseError(SealError):
+    """Passphrase does not match the vault's verifier."""
+
+
+class AuthenticationError(SealError):
+    """A line failed to authenticate under its expected AAD, or was malformed
+    (not valid base64, too short to contain a nonce). Deliberately one type for
+    both: callers shouldn't have to distinguish "corrupted" from "tampered" from
+    "truncated" to handle a bad line.
+    """

sealedlog-0.1.0/src/sealedlog/log.py

@@ -0,0 +1,68 @@
+"""Append-only encrypted JSONL file, keyed by a stream_id.
+
+Single writer per file: sealedlog does no locking or coordination, and
+assumes the caller doesn't run two writers against the same path at once.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+from sealedlog import aead
+from sealedlog._aad import build_aad
+from sealedlog.errors import AuthenticationError
+
+
+@dataclass(frozen=True, slots=True)
+class LineFailure:
+    lineno: int
+    error: str
+
+
+class SealedLog:
+    def __init__(self, path: Path, key: bytes, stream_id: str, *, namespace: str) -> None:
+        self.path = path
+        self._key = key
+        self._aad = build_aad(namespace, stream_id)
+
+    def append(self, record: dict) -> None:
+        """JSON-encodes and appends one sealed line. Byte-append only —
+        never rewrites or reorders existing lines.
+        """
+        plaintext = json.dumps(record, separators=(",", ":")).encode("utf-8")
+        sealed = aead.seal(self._key, self._aad, plaintext)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(sealed + "\n")
+
+    def __iter__(self) -> Iterator[dict]:
+        """Lazily decrypts and yields records in file order. Raises
+        AuthenticationError on the first bad line — use verify() to survive
+        corruption instead.
+        """
+        for line in self._read_lines():
+            yield json.loads(aead.open_(self._key, self._aad, line))
+
+    def verify(self) -> list[LineFailure]:
+        """Attempts every line; never raises. Returns the failures instead of
+        stopping at the first, so a caller can report all of them in one pass.
+        """
+        failures: list[LineFailure] = []
+        for lineno, line in enumerate(self._read_lines(), start=1):
+            try:
+                aead.open_(self._key, self._aad, line)
+            except AuthenticationError as e:
+                failures.append(LineFailure(lineno=lineno, error=str(e)))
+        return failures
+
+    def _read_lines(self) -> Iterator[str]:
+        if not self.path.exists():
+            return
+        with self.path.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    yield line

sealedlog-0.1.0/src/sealedlog/vault.py

@@ -0,0 +1,84 @@
+"""Passphrase -> key, via Argon2id, with a verifier so a wrong passphrase
+fails immediately instead of producing garbage downstream.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+from dataclasses import dataclass
+
+import nacl.pwhash
+
+from sealedlog import aead
+from sealedlog._aad import VERIFIER_PLAINTEXT, VERIFIER_STREAM_ID, build_aad
+from sealedlog.errors import AuthenticationError, WrongPassphraseError
+
+SALT_SIZE = nacl.pwhash.argon2id.SALTBYTES
+OPSLIMIT_DEFAULT = nacl.pwhash.argon2id.OPSLIMIT_MODERATE
+MEMLIMIT_DEFAULT = nacl.pwhash.argon2id.MEMLIMIT_MODERATE
+
+
+def derive_key(passphrase: str, salt: bytes, opslimit: int, memlimit: int) -> bytes:
+    return nacl.pwhash.argon2id.kdf(
+        aead.KEY_SIZE, passphrase.encode("utf-8"), salt, opslimit=opslimit, memlimit=memlimit
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class Vault:
+    """KDF params, salt, and a sealed verifier. Safe to store as plaintext
+    alongside the encrypted log(s) it unlocks — it reveals nothing without
+    the passphrase.
+    """
+
+    salt: bytes
+    opslimit: int
+    memlimit: int
+    verifier: str
+
+    @classmethod
+    def create(
+        cls,
+        passphrase: str,
+        *,
+        namespace: str,
+        opslimit: int = OPSLIMIT_DEFAULT,
+        memlimit: int = MEMLIMIT_DEFAULT,
+    ) -> Vault:
+        salt = os.urandom(SALT_SIZE)
+        key = derive_key(passphrase, salt, opslimit, memlimit)
+        verifier = aead.seal(key, build_aad(namespace, VERIFIER_STREAM_ID), VERIFIER_PLAINTEXT)
+        return cls(salt=salt, opslimit=opslimit, memlimit=memlimit, verifier=verifier)
+
+    def unlock(self, passphrase: str, *, namespace: str) -> bytes:
+        """Derive the key and check it against the verifier.
+
+        Raises WrongPassphraseError if the passphrase doesn't match — before
+        any real data gets touched.
+        """
+        key = derive_key(passphrase, self.salt, self.opslimit, self.memlimit)
+        try:
+            opened = aead.open_(key, build_aad(namespace, VERIFIER_STREAM_ID), self.verifier)
+        except AuthenticationError as e:
+            raise WrongPassphraseError("passphrase does not match this vault") from e
+        if opened != VERIFIER_PLAINTEXT:
+            raise WrongPassphraseError("passphrase does not match this vault")
+        return key
+
+    def to_dict(self) -> dict:
+        return {
+            "salt": base64.b64encode(self.salt).decode("ascii"),
+            "opslimit": self.opslimit,
+            "memlimit": self.memlimit,
+            "verifier": self.verifier,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Vault:
+        return cls(
+            salt=base64.b64decode(d["salt"]),
+            opslimit=d["opslimit"],
+            memlimit=d["memlimit"],
+            verifier=d["verifier"],
+        )