grz-db 0.1.0__tar.gz

grz_db-0.1.0/.gitignore

@@ -0,0 +1,195 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore

grz_db-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2025-06-11)
+
+
+### Features
+
+* migrate to monorepo configuration ([36c7360](https://github.com/BfArM-MVH/grz-tools/commit/36c736044ce09473cc664b4471117465c5cab9a3))

grz_db-0.1.0/LICENSE

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

grz_db-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: grz-db
+Version: 0.1.0
+Summary: SQL models for grz-cli and grz-watchdog.
+Project-URL: Homepage, https://github.com/BfArM-MVH/grz-tools
+Project-URL: Repository, https://github.com/BfArM-MVH/grz-tools/tree/main/packages/grz-db
+Project-URL: Documentation, https://github.com/BfArM-MVH/grz-tools
+Project-URL: Issues, https://github.com/BfArM-MVH/grz-tools/issues
+Author-email: Till Hartmann <till.hartmann@bih-charite.de>
+License-File: LICENSE
+Keywords: python
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4.0,>=3.12
+Requires-Dist: alembic>=1.16.1
+Requires-Dist: cryptography>=45.0.3
+Requires-Dist: sqlmodel>=0.0.24
+Description-Content-Type: text/markdown
+
+Libraries, SQL models and alembic migrations for GRZ DB.

grz_db-0.1.0/README.md

@@ -0,0 +1 @@
+Libraries, SQL models and alembic migrations for GRZ DB.

grz_db-0.1.0/alembic.ini

@@ -0,0 +1,45 @@
+# A generic, single database configuration.
+
+[migrations]
+
+# database URL.  This is consumed by the user-maintained env.py script only.
+# other means of configuring database URLs may be customized within the env.py
+# file.
+sqlalchemy.url = sqlite:///test.db
+script_location = grz_db:migrations
+
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

grz_db-0.1.0/pyproject.toml

@@ -0,0 +1,113 @@
+[project]
+name = "grz-db"
+version = "0.1.0"
+description = "SQL models for grz-cli and grz-watchdog."
+authors = [{ name = "Till Hartmann", email = "till.hartmann@bih-charite.de" }]
+readme = "README.md"
+keywords = ['python']
+requires-python = ">=3.12,<4.0"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "alembic>=1.16.1",
+    "cryptography>=45.0.3",
+    "sqlmodel>=0.0.24",
+]
+
+[project.urls]
+Homepage = "https://github.com/BfArM-MVH/grz-tools"
+Repository = "https://github.com/BfArM-MVH/grz-tools/tree/main/packages/grz-db"
+Documentation = "https://github.com/BfArM-MVH/grz-tools"
+Issues = "https://github.com/BfArM-MVH/grz-tools/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/grz_db"]
+
+[tool.hatch.version]
+path = "src/grz_db/__init__.py"
+
+[tool.alembic]
+
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = "%(here)s/src/grz_db/migrations"
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = "%%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s"
+
+# additional paths to be prepended to sys.path. defaults to the current working directory.
+prepend_sys_path = [
+    "."
+]
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the python>=3.9 or backports.zoneinfo library and tzdata library.
+# Any required deps can installed by adding `alembic[tz]` to the pip requirements
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+timezone = "UTC"
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to <script_location>/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# version_locations = [
+#    "%(here)s/alembic/versions",
+#    "%(here)s/foo/bar"
+# ]
+
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = "utf-8"
+
+# This section defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+# [[tool.alembic.post_write_hooks]]
+# format using "black" - use the console_scripts runner,
+# against the "black" entrypoint
+# name = "black"
+# type = "console_scripts"
+# entrypoint = "black"
+# options = "-l 79 REVISION_SCRIPT_FILENAME"
+#
+# [[tool.alembic.post_write_hooks]]
+# lint with attempts to fix using "ruff" - use the exec runner,
+# execute a binary
+# name = "ruff"
+# type = "exec"
+# executable = "%(here)s/.venv/bin/ruff"
+# options = "check --fix REVISION_SCRIPT_FILENAME"

grz_db-0.1.0/src/grz_db/__init__.py

@@ -0,0 +1,530 @@
+import datetime
+import enum
+import logging
+import os
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any, ClassVar, Generic, TypeVar
+
+import cryptography
+from alembic import command as alembic_command
+from alembic.config import Config as AlembicConfig
+from cryptography.hazmat.primitives.asymmetric.types import PrivateKeyTypes, PublicKeyTypes
+from pydantic import ConfigDict
+from sqlalchemy import JSON, Column
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import selectinload
+from sqlmodel import DateTime, Field, Relationship, Session, SQLModel, create_engine, select
+
+__version__ = "0.1.0"
+
+log = logging.getLogger(__name__)
+
+
+class CaseInsensitiveStrEnum(enum.StrEnum):
+    """
+    A StrEnum that is case-insensitive for member lookup and comparison with strings.
+    """
+
+    @classmethod
+    def _missing_(cls, value):
+        """
+        Override to allow case-insensitive lookup of enum members by value.
+        e.g., MyEnum('value') will match MyEnum.VALUE.
+        """
+        if isinstance(value, str):
+            for member in cls:
+                if member.value.casefold() == value.casefold():
+                    return member
+        return None
+
+    def __eq__(self, other):
+        """
+        Override to allow case-insensitive comparison of enum members by value.
+        """
+        if isinstance(other, enum.Enum):
+            return self is other
+        if isinstance(other, str):
+            return self.value.casefold() == other.casefold()
+        return NotImplemented
+
+    def __hash__(self):
+        """
+        Override to make hash consistent with eq.
+        """
+        return hash(self.value.casefold())
+
+
+def serialize_datetime_to_iso_z(dt: datetime.datetime) -> str:
+    """
+    Serializes a datetime object to a canonical ISO 8601 string format with 'Z' for UTC.
+    """
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=datetime.UTC)
+
+    if dt.tzinfo != datetime.UTC and dt.utcoffset() != datetime.timedelta(0):
+        dt = dt.astimezone(datetime.UTC)
+
+    return dt.isoformat()
+
+
+class ListableEnum(enum.StrEnum):
+    """Mixin for enum classes whose members can be listed."""
+
+    @classmethod
+    def list(cls) -> list[str]:
+        """Returns a list of enum members."""
+        return list(map(lambda c: c.value, cls))
+
+
+class SubmissionStateEnum(CaseInsensitiveStrEnum, ListableEnum):
+    """Submission state enum."""
+
+    UPLOADING = "Uploading"
+    UPLOADED = "Uploaded"
+    DOWNLOADING = "Downloading"
+    DOWNLOADED = "Downloaded"
+    DECRYPTING = "Decrypting"
+    DECRYPTED = "Decrypted"
+    VALIDATING = "Validating"
+    VALIDATED = "Validated"
+    ENCRYPTING = "Encrypting"
+    ENCRYPTED = "Encrypted"
+    ARCHIVING = "Archiving"
+    ARCHIVED = "Archived"
+    REPORTED = "Reported"
+    QCING = "QCing"
+    QCED = "QCed"
+    CLEANING = "Cleaning"
+    CLEANED = "Cleaned"
+    FINISHED = "Finished"
+    ERROR = "Error"
+
+
+class ChangeRequestEnum(CaseInsensitiveStrEnum, ListableEnum):
+    """Change request enum."""
+
+    MODIFY = "Modify"
+    DELETE = "Delete"
+    TRANSFER = "Transfer"
+
+
+class BaseSignablePayload(SQLModel):
+    """
+    Base class for SQLModel based payloads
+    that can be signed and can be converted to bytes for verification.
+    Provides a default `to_bytes` method using pydantic's JSON serialization.
+    Provides a default `sign` method using the private key of the author.
+    """
+
+    model_config = ConfigDict(
+        json_encoders={datetime.datetime: serialize_datetime_to_iso_z},
+        populate_by_name=True,
+    )
+
+    def to_bytes(self) -> bytes:
+        """
+        Default serialization: JSON string encoded to UTF-8.
+        """
+        payload_json = self.model_dump_json(by_alias=True)
+        return payload_json.encode("utf8")
+
+    def sign(self, private_key: PrivateKeyTypes) -> bytes:
+        """Sign this payload using the given private key."""
+        bytes_to_sign = self.to_bytes()
+        signature = private_key.sign(bytes_to_sign)
+        public_key_of_private = private_key.public_key()
+        public_key_of_private.verify(signature, bytes_to_sign)
+        return signature
+
+
+P = TypeVar("P", bound=BaseSignablePayload)
+
+
+class VerifiableLog(Generic[P]):
+    """
+    Mixin class for SQLModels that store a signature and can be verified.
+    Subclasses MUST:
+    1. Define `payload_model_class: ClassVar[type[P]]`.
+    2. Have an instance attribute `signature: str`.
+    """
+
+    signature: str
+    payload_model_class: ClassVar[type[P]]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if not hasattr(cls, "payload_model_class"):
+            raise TypeError(f"Class {cls.__name__} lacks 'payload_model_class' attribute required by VerifiableLog.")
+        if not (isinstance(cls.payload_model_class, type) and issubclass(cls.payload_model_class, BaseSignablePayload)):
+            raise TypeError(
+                f"'payload_model_class' in {cls.__name__} must be a class and a subclass of BaseSignedPayload. "
+                f"Got: {cls.payload_model_class}"
+            )
+
+    def verify(self, public_key: PublicKeyTypes) -> bool:
+        """Verify the signature of this log entry."""
+        if not hasattr(self, "signature") or not isinstance(self.signature, str) or not self.signature:
+            log.warning(f"Missing/invalid signature for {self.__class__.__name__} (id: {getattr(self, 'id', 'N/A')}).")
+            return False
+
+        signature_bytes = bytes.fromhex(self.signature)
+        data_for_payload = self.model_dump(by_alias=True, exclude={"signature", "payload_model_class"})
+        payload_to_verify = self.payload_model_class(**data_for_payload)
+        bytes_to_verify = payload_to_verify.to_bytes()
+
+        try:
+            public_key.verify(signature_bytes, bytes_to_verify)
+        except cryptography.exceptions.InvalidSignature:
+            return False
+        except:
+            raise
+        return True
+
+
+class SubmissionBase(SQLModel):
+    """Submission base model."""
+
+    tan_g: str | None = Field(default=None, unique=True, index=True, alias="tanG")
+    pseudonym: str | None = Field(default=None, index=True)
+
+
+class Submission(SubmissionBase, table=True):
+    """Submission table model."""
+
+    __tablename__ = "submissions"
+
+    id: str = Field(primary_key=True, index=True)
+
+    states: list["SubmissionStateLog"] = Relationship(back_populates="submission")
+
+    changes: list["ChangeRequestLog"] = Relationship(back_populates="submission")
+
+
+class SubmissionStateLogBase(SQLModel):
+    """
+    Submission state log base model.
+    Holds state information for each submission.
+    Timestamped.
+    Can optionally have associated JSON data.
+    """
+
+    state: SubmissionStateEnum
+    data: dict[str, Any] | None = Field(default=None, sa_column=Column(JSON))
+    timestamp: datetime.datetime = Field(
+        default_factory=lambda: datetime.datetime.now(datetime.UTC),
+        sa_column=Column(DateTime(timezone=True), nullable=False),
+    )
+
+    model_config = ConfigDict(
+        json_encoders={datetime.datetime: serialize_datetime_to_iso_z},
+        populate_by_name=True,
+    )
+
+
+class SubmissionStateLogPayload(SubmissionStateLogBase, BaseSignablePayload):
+    """
+    Used to bundle data for signature calculation.
+    """
+
+    submission_id: str
+    author_name: str
+
+
+class SubmissionStateLog(SubmissionStateLogBase, VerifiableLog[SubmissionStateLogPayload], table=True):
+    """Submission state log table model."""
+
+    __tablename__ = "submission_states"
+
+    payload_model_class = SubmissionStateLogPayload
+
+    id: int | None = Field(default=None, primary_key=True, index=True)
+    submission_id: str = Field(foreign_key="submissions.id", index=True)
+
+    author_name: str = Field(index=True)
+    signature: str
+
+    submission: Submission | None = Relationship(back_populates="states")
+
+
+class SubmissionStateLogCreate(SubmissionStateLogBase):
+    """Submission state log create model."""
+
+    submission_id: str
+    author_name: str
+    signature: str
+
+
+class SubmissionCreate(SubmissionBase):
+    """Submission create model."""
+
+    id: str
+
+
+class ChangeRequestLogBase(SQLModel):
+    """
+    Base model for change request logs.
+    Timestamped.
+    Can optionally have associated JSON data.
+    """
+
+    change: ChangeRequestEnum
+    data: dict[str, Any] | None = Field(default=None, sa_column=Column(JSON))
+    timestamp: datetime.datetime = Field(
+        default_factory=lambda: datetime.datetime.now(datetime.UTC),
+        sa_column=Column(DateTime(timezone=True), nullable=False),
+    )
+
+    model_config = ConfigDict(
+        json_encoders={datetime.datetime: serialize_datetime_to_iso_z},
+        populate_by_name=True,
+    )
+
+
+class ChangeRequestLogPayload(ChangeRequestLogBase, BaseSignablePayload):
+    """
+    Used to bundle data for signature calculation.
+    """
+
+    submission_id: str
+    author_name: str
+
+
+class ChangeRequestLog(ChangeRequestLogBase, VerifiableLog[ChangeRequestLogPayload], table=True):
+    """Change-request log table model."""
+
+    __tablename__ = "submission_change_requests"
+
+    payload_model_class = ChangeRequestLogPayload
+
+    id: int | None = Field(default=None, primary_key=True, index=True)
+    submission_id: str = Field(foreign_key="submissions.id", index=True)
+
+    author_name: str = Field(index=True)
+    signature: str
+
+    submission: Submission | None = Relationship(back_populates="changes")
+
+
+class SubmissionNotFoundError(ValueError):
+    """Exception for when a submission is not found in the database."""
+
+    def __init__(self, submission_id: str):
+        super().__init__(f"Submission not found for ID {submission_id}")
+
+
+class DuplicateSubmissionError(ValueError):
+    """Exception for when a submission ID already exists in the database."""
+
+    def __init__(self, submission_id: str):
+        super().__init__(f"Duplicate submission ID {submission_id}")
+
+
+class DuplicateTanGError(ValueError):
+    """Exception for when a tanG is already in use."""
+
+    def __init__(self, tan_g: str):
+        super().__init__(f"Duplicate tanG {tan_g}")
+
+
+class DatabaseConfigurationError(Exception):
+    """Exception for database configuration issues."""
+
+    pass
+
+
+class Author:
+    def __init__(self, name: str, private_key_bytes: bytes):
+        self.name = name
+        self.private_key_bytes = private_key_bytes
+
+    def private_key(self) -> PrivateKeyTypes:
+        from functools import partial
+        from getpass import getpass
+
+        from cryptography.hazmat.primitives.serialization import load_ssh_private_key
+
+        passphrase = os.getenv("GRZ_DB_AUTHOR_PASSPHRASE")
+        passphrase_callback = (lambda: passphrase) if passphrase else None
+
+        if not passphrase:
+            passphrase_callback = partial(getpass, prompt=f"Passphrase for GRZ DB author ({self.name}'s) private key: ")
+        log.info(f"Loading private key of {self.name}…")
+        private_key = load_ssh_private_key(
+            self.private_key_bytes,
+            password=passphrase_callback().encode("utf-8"),
+        )
+        return private_key
+
+
+class SubmissionDb:
+    """
+    API entrypoint for managing submissions.
+    """
+
+    def __init__(self, db_url: str, author: Author | None, debug: bool = False):
+        """
+        Initializes the SubmissionDb.
+
+        Args:
+            db_url: Database URL.
+            debug: Whether to echo SQL statements.
+        """
+        self.engine = create_engine(db_url, echo=debug)
+        self._author = author
+
+    @contextmanager
+    def get_session(self) -> Generator[Session, Any, None]:
+        """Get an sqlmodel session."""
+        with Session(self.engine) as session:
+            yield session
+
+    def _get_alembic_config(self, alembic_ini_path: str) -> AlembicConfig:
+        """
+        Loads the alembic configuration.
+
+        Args:
+            alembic_ini_path: Path to alembic ini file.
+        """
+        if not alembic_ini_path or not os.path.exists(alembic_ini_path):
+            raise ValueError(f"Alembic configuration file not found at: {alembic_ini_path}")
+
+        alembic_cfg = AlembicConfig(alembic_ini_path)
+        alembic_cfg.set_main_option("sqlalchemy.url", str(self.engine.url))
+        alembic_cfg.set_main_option("script_location", "grz_db:migrations")
+        return alembic_cfg
+
+    def initialize_schema(self):
+        """Initialize the database."""
+        SQLModel.metadata.create_all(self.engine, checkfirst=True)
+
+    def upgrade_schema(self, alembic_ini_path: str, revision: str = "head"):
+        """
+        Upgrades the database schema using alembic.
+
+        Args:
+            alembic_ini_path: Path to the alembic.ini file.
+            revision: The Alembic revision to upgrade to (default: 'head').
+
+        Raises:
+            RuntimeError: For underlying Alembic errors.
+        """
+        alembic_cfg = self._get_alembic_config(alembic_ini_path)
+        try:
+            alembic_command.upgrade(alembic_cfg, revision)
+        except Exception as e:
+            raise RuntimeError(f"Alembic upgrade failed: {e}") from e
+
+    def add_submission(
+        self,
+        submission_id: str,
+        tan_g: str | None = None,
+        pseudonym: str | None = None,
+    ) -> Submission:
+        """
+        Adds a submission to the database.
+
+        Args:
+            submission_id: Submission ID.
+            tan_g: tanG if in phase 0
+            pseudonym: pseudonym if phase >= 0
+
+        Returns:
+            An instance of Submission.
+        """
+        with self.get_session() as session:
+            existing_submission = session.get(Submission, submission_id)
+            if existing_submission:
+                raise DuplicateSubmissionError(submission_id)
+
+            submission_create = SubmissionCreate(id=submission_id, tan_g=tan_g, pseudonym=pseudonym)
+            db_submission = Submission.model_validate(submission_create)
+
+            session.add(db_submission)
+            try:
+                session.commit()
+                session.refresh(db_submission)
+                return db_submission
+            except IntegrityError as e:
+                session.rollback()
+                if "UNIQUE constraint failed: submissions.tanG" in str(e) and tan_g:
+                    raise DuplicateTanGError(tan_g) from e
+                raise
+            except Exception:
+                session.rollback()
+                raise
+
+    def update_submission_state(
+        self,
+        submission_id: str,
+        state: SubmissionStateEnum,
+        data: dict | None = None,
+    ) -> SubmissionStateLog:
+        """
+        Updates a submission's state to the specified state.
+
+        Args:
+            submission_id: Submission ID of the submission to update.
+            state: New state of the submission.
+            data: Optional data to attach to the update.
+
+        Returns:
+            An instance of SubmissionStateLog.
+        """
+        with self.get_session() as session:
+            submission = session.get(Submission, submission_id)
+            if not submission:
+                raise SubmissionNotFoundError(submission_id)
+
+            state_log_payload = SubmissionStateLogPayload(
+                submission_id=submission_id, author_name=self._author.name, state=state, data=data
+            )
+            signature = state_log_payload.sign(self._author.private_key())
+
+            state_log_create = SubmissionStateLogCreate(**state_log_payload.model_dump(), signature=signature.hex())
+            db_state_log = SubmissionStateLog.model_validate(state_log_create)
+            session.add(db_state_log)
+
+            # Remove tanG once it has been reported?
+            if state == SubmissionStateEnum.REPORTED and submission.tan_g is not None:
+                submission.tan_g = None
+                session.add(submission)
+
+            try:
+                session.commit()
+                session.refresh(db_state_log)
+                if state == SubmissionStateEnum.REPORTED and submission.tan_g is None:
+                    session.refresh(submission)
+                return db_state_log
+            except Exception:
+                session.rollback()
+                raise
+
+    def get_submission(self, submission_id: str) -> Submission | None:
+        """
+        Retrieves a submission and its state history.
+
+        Args:
+            submission_id: Submission ID of the submission to retrieve.
+
+        Returns:
+            An instance of Submission or None.
+        """
+        with self.get_session() as session:
+            statement = (
+                select(Submission).where(Submission.id == submission_id).options(selectinload(Submission.states))
+            )
+            submission = session.exec(statement).first()
+            return submission
+
+    def list_submissions(self) -> list[Submission]:
+        """
+        Lists all submissions in the database.
+
+        Returns:
+            A list of all submissions in the database, ordered by their ID.
+        """
+        with self.get_session() as session:
+            statement = select(Submission).options(selectinload(Submission.states)).order_by(Submission.id)
+            submissions = session.exec(statement).all()
+            return submissions

grz_db-0.1.0/src/grz_db/migrations/README

@@ -0,0 +1 @@
+pyproject configuration, based on the generic configuration.

grz_db-0.1.0/src/grz_db/migrations/env.py

@@ -0,0 +1,78 @@
+"""alembic migrations env.py"""
+
+from logging.config import fileConfig
+
+from alembic import context
+from grz_db import *  # noqa: F403
+from sqlalchemy import engine_from_config, pool
+from sqlmodel import SQLModel
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+# from myapp import mymodel
+# target_metadata = mymodel.Base.metadata
+target_metadata = SQLModel.metadata
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

grz_db-0.1.0/src/grz_db/migrations/script.py.mako

@@ -0,0 +1,29 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

grz_db-0.1.0/src/grz_db/migrations/versions/82607cdce6ee_initial.py

@@ -0,0 +1,88 @@
+"""initial
+
+Revision ID: 82607cdce6ee
+Revises:
+Create Date: 2025-05-28 13:40:18.414894
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "82607cdce6ee"
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "submissions",
+        sa.Column("tan_g", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+        sa.Column("pseudonym", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+        sa.Column("id", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_submissions_id"), "submissions", ["id"], unique=False)
+    op.create_index(op.f("ix_submissions_pseudonym"), "submissions", ["pseudonym"], unique=False)
+    op.create_index(op.f("ix_submissions_tan_g"), "submissions", ["tan_g"], unique=True)
+    op.create_table(
+        "submission_states",
+        sa.Column(
+            "state",
+            sa.Enum(
+                "UPLOADING",
+                "UPLOADED",
+                "DOWNLOADING",
+                "DOWNLOADED",
+                "DECRYPTING",
+                "DECRYPTED",
+                "VALIDATING",
+                "VALIDATED",
+                "ENCRYPTING",
+                "ENCRYPTED",
+                "ARCHIVING",
+                "ARCHIVED",
+                "REPORTED",
+                "QCING",
+                "QCED",
+                "CLEANING",
+                "CLEANED",
+                "FINISHED",
+                "ERROR",
+                name="submissionstateenum",
+            ),
+            nullable=False,
+        ),
+        sa.Column("data", sa.JSON(), nullable=True),
+        sa.Column("timestamp", sa.DateTime(), nullable=False),
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("submission_id", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["submission_id"],
+            ["submissions.id"],
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_submission_states_id"), "submission_states", ["id"], unique=False)
+    op.create_index(op.f("ix_submission_states_submission_id"), "submission_states", ["submission_id"], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f("ix_submission_states_submission_id"), table_name="submission_states")
+    op.drop_index(op.f("ix_submission_states_id"), table_name="submission_states")
+    op.drop_table("submission_states")
+    op.drop_index(op.f("ix_submissions_tan_g"), table_name="submissions")
+    op.drop_index(op.f("ix_submissions_pseudonym"), table_name="submissions")
+    op.drop_index(op.f("ix_submissions_id"), table_name="submissions")
+    op.drop_table("submissions")
+    # ### end Alembic commands ###

grz_db-0.1.0/tests/files/alice.pub

@@ -0,0 +1 @@
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDu+8yDmRM755qm0A4oC9QALzyDgo4rIaOwF01p+ou8G till@Ganymed

grz_db-0.1.0/tests/files/alice.sec

@@ -0,0 +1,8 @@
+-----BEGIN OPENSSH PRIVATE KEY-----
+b3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABBF9yxkGm
+ThDPJqANnAncZAAAAAGAAAAAEAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIDu+8yDmRM755qm0
+A4oC9QALzyDgo4rIaOwF01p+ou8GAAAAkOWnOYjxMIsLYQdDzYJ0I2sbkXa2ppSzu+/dvh
+nkrMAJ9DAvvZk/7tykTcSxynBcf/DDLtb1mJTtuGaQ2MYtvxU0kOVB2sjWqiuNySO8FAKc
+NXGNF+XE/VVUeYmOGH5fGJaiIl32GUmhcOrz6Gb8WBSnB9CvH3FA5nmzSEqShU/vxd4UA7
+z5kwx1VgIvFS9XiQ==
+-----END OPENSSH PRIVATE KEY-----

grz_db-0.1.0/tests/files/known_keys

@@ -0,0 +1 @@
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDu+8yDmRM755qm0A4oC9QALzyDgo4rIaOwF01p+ou8G Alice