limitsdb 0.5.0__py3-none-any.whl

limitsdb/cli/ldb_crypt.py

@@ -0,0 +1,44 @@
+"""Command line interface for encrypting secret configuration values."""
+
+from __future__ import annotations
+
+import argparse
+
+from limitsdb.core.ldb_crypto import load_or_create_key
+from limitsdb.core.ldb_errors import LimitsDbError
+from limitsdb.core.ldb_logger import configure_logger, get_logger
+from limitsdb.core.ldb_utils import encrypt_secrets_in_place
+
+configure_logger(level="WARNING")
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Encrypt cleartext secrets in secrets.json",
+    )
+    parser.add_argument("--schema", required=True, help="Schema name (folder under schemas/)")
+    parser.add_argument("--profile", help="Profile name (e.g., dev, prod)")
+    parser.add_argument("--config-dir", help="Configuration root (overrides autodiscovery)")
+    return parser.parse_args()
+
+
+def run_cli() -> None:
+    """Entry point for the ``ldb-crypt`` command."""
+    logger = get_logger("crypt")
+    try:
+        args = _parse_args()
+        load_or_create_key()
+        updated = encrypt_secrets_in_place(
+            schema=args.schema, profile=getattr(args, "profile", None), config_root=getattr(args, "config_dir", None)
+        )
+        if updated:
+            logger.info("Secrets updated: %s", updated)
+        else:
+            logger.info("No secrets to update (file missing or already encrypted).")
+    except (LimitsDbError, ValueError) as exc:
+        logger.error("%s", exc)
+        raise SystemExit(1) from exc
+
+
+if __name__ == "__main__":  # pragma: no cover
+    run_cli()

limitsdb/cli/ldb_impl.py

@@ -0,0 +1,207 @@
+"""Bootstrap database objects required by LimitsDb."""
+
+from __future__ import annotations
+
+import argparse
+
+from limitsdb.core.ldb_crypto import load_or_create_key
+from limitsdb.core.ldb_errors import LimitsDbError
+from limitsdb.core.ldb_logger import configure_logger, get_logger, reconfigure_logger
+from limitsdb.core.ldb_params_config import Config, build_config
+from limitsdb.core.ldb_utils import encrypt_secrets_in_place
+from limitsdb.db.ldb_engine_loader import get_db_engine
+from limitsdb.db.ldb_engines import (
+    ColumnDefinition,
+    DatabaseLinkDefinition,
+    RoleDefinition,
+    SequenceDefinition,
+    TableDefinition,
+    UserDefinition,
+)
+
+configure_logger(level="WARNING")
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Ensure LimitsDb control objects exist in the database.",
+    )
+    parser.add_argument("--schema", required=True, help="Schema name (folder under schemas/)")
+    parser.add_argument("--profile", help="Profile name (e.g., dev, prod)")
+    parser.add_argument("--config-dir", help="Configuration root (overrides autodiscovery)")
+    parser.add_argument("--config-file", help="Additional configuration overlay")
+    parser.add_argument(
+        "--set", action="append", default=[], help="Overrides like key=value; supports dotted keys for nesting"
+    )
+    parser.add_argument(
+        "--log-level", default="INFO", choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"], help="Logging level"
+    )
+    return parser.parse_args()
+
+
+def _build_control_tables(owner: str) -> list[TableDefinition]:
+    return [
+        TableDefinition(
+            owner=owner,
+            name="LDB_CTL",
+            columns=(
+                ColumnDefinition("CTL_OWNER", "string", length=50, nullable=False),
+                ColumnDefinition("CTL_TABLE_NAME", "string", length=50, nullable=False),
+                ColumnDefinition("CTL_PROCESS_DATE", "date"),
+                ColumnDefinition("CTL_ACTION", "string", length=11, nullable=False),
+                ColumnDefinition("CTL_STATUS", "string", length=10, nullable=False),
+                ColumnDefinition("CTL_PROCESS_START", "date"),
+                ColumnDefinition("CTL_PROCESS_END", "date"),
+                ColumnDefinition("CTL_ROWS_PROCESSED", "number", precision=18, scale=0),
+                ColumnDefinition("CTL_PLSQL", "clob"),
+            ),
+            primary_key=("CTL_OWNER", "CTL_TABLE_NAME"),
+        ),
+        TableDefinition(
+            owner=owner,
+            name="LDB_LOG",
+            columns=(
+                ColumnDefinition("LOG_ID", "number", precision=18, scale=0, nullable=False),
+                ColumnDefinition("LOG_OWNER", "string", length=50, nullable=False),
+                ColumnDefinition("LOG_TABLE_NAME", "string", length=50, nullable=False),
+                ColumnDefinition("LOG_PROCESS_DATE", "date", nullable=False),
+                ColumnDefinition("LOG_ACTION", "string", length=11, nullable=False),
+                ColumnDefinition("LOG_STATUS", "string", length=10, nullable=False),
+                ColumnDefinition("LOG_PROCESS_START", "date", nullable=False),
+                ColumnDefinition("LOG_PROCESS_END", "date"),
+                ColumnDefinition("LOG_MESSAGE", "string", length=4000),
+                ColumnDefinition("LOG_ROWS_PROCESSED", "number", precision=18, scale=0),
+                ColumnDefinition("LOG_PLSQL", "clob"),
+            ),
+            primary_key=("LOG_ID",),
+        ),
+    ]
+
+
+def _build_sequences(owner: str) -> list[SequenceDefinition]:
+    return [
+        SequenceDefinition(owner=owner, name="LDB_LOG_ID"),
+    ]
+
+
+def run_cli() -> None:
+    logger = get_logger("impl")
+    try:
+        args = _parse_args()
+        reconfigure_logger(level=args.log_level)
+
+        load_or_create_key()
+        encrypt_secrets_in_place(
+            schema=args.schema,
+            profile=getattr(args, "profile", None),
+            config_root=getattr(args, "config_dir", None),
+        )
+        cfg_dict = build_config({}, args)
+        config = Config.from_dict(cfg_dict)
+        connections = config.connections
+        administration = config.administration
+
+        if not administration.source.username or not administration.source.password:
+            raise ValueError("admin_source_username and admin_source_password are required")
+        if not administration.history.username or not administration.history.password:
+            raise ValueError("admin_history_username and admin_history_password are required")
+        if not connections.source.username or not connections.source.password:
+            raise ValueError("source_username and source_password are required")
+        if not connections.history.username or not connections.history.password:
+            raise ValueError("history_username and history_password are required")
+        if not connections.history.dsn:
+            raise ValueError("history_dsn is required to create the database link")
+        if not connections.source.dsn:
+            raise ValueError("source_dsn is required to create the database link")
+
+        engine = get_db_engine(connections.db_engine)
+    except (LimitsDbError, ValueError) as exc:
+        logger.error("%s", exc)
+        raise SystemExit(1) from exc
+
+    source_roles = [RoleDefinition(name=administration.source_role_name)]
+    source_privileges = getattr(engine, "REQUIRED_SYSTEM_PRIVILEGES", ())
+    history_privileges = getattr(engine, "REQUIRED_SYSTEM_PRIVILEGES", ())
+
+    source_user = UserDefinition(
+        name=connections.source.username,
+        password=connections.source.password,
+        default_tablespace=administration.source_default_tablespace or None,
+        roles=(administration.source_role_name,),
+        roles_with_admin_option=(administration.source_role_name,),
+        system_privileges=source_privileges,
+    )
+    history_roles = [RoleDefinition(name=administration.history_role_name)]
+    history_user = UserDefinition(
+        name=connections.history.username,
+        password=connections.history.password,
+        default_tablespace=administration.history_default_tablespace or None,
+        roles=(administration.history_role_name,),
+        roles_with_admin_option=(administration.history_role_name,),
+        system_privileges=history_privileges,
+    )
+    source_tables = _build_control_tables(connections.source.username)
+    source_sequences = _build_sequences(connections.source.username)
+    history_tables = _build_control_tables(connections.history.username)
+    history_sequences = _build_sequences(connections.history.username)
+    source_db_link = DatabaseLinkDefinition(
+        name=administration.source_to_history_dblink_name,
+        username=connections.history.username,
+        password=connections.history.password,
+        dsn=connections.history.dsn,
+    )
+    history_db_link = DatabaseLinkDefinition(
+        name=administration.history_to_source_dblink_name,
+        username=connections.source.username,
+        password=connections.source.password,
+        dsn=connections.source.dsn,
+    )
+
+    summary: dict[str, list[str]] = {}
+
+    source_admin_conn = engine.get_connection(config, admin=True, env="SOURCE")
+    try:
+        summary["source_roles"] = engine.ensure_roles(source_admin_conn, source_roles)
+        summary["source_users"] = engine.ensure_users(source_admin_conn, [source_user])
+        summary["source_tables"] = engine.ensure_tables(source_admin_conn, source_tables)
+        summary["source_sequences"] = engine.ensure_sequences(source_admin_conn, source_sequences)
+        summary["source_supporting_objects"] = engine.ensure_supporting_objects(
+            source_admin_conn, connections.source.username
+        )
+    finally:
+        engine.close_connection(source_admin_conn)
+
+    history_admin_conn = engine.get_connection(config, admin=True, env="HISTORY")
+    try:
+        summary["history_roles"] = engine.ensure_roles(history_admin_conn, history_roles)
+        summary["history_users"] = engine.ensure_users(history_admin_conn, [history_user])
+        summary["history_tables"] = engine.ensure_tables(history_admin_conn, history_tables)
+        summary["history_sequences"] = engine.ensure_sequences(history_admin_conn, history_sequences)
+        summary["history_supporting_objects"] = engine.ensure_supporting_objects(
+            history_admin_conn, connections.history.username
+        )
+    finally:
+        engine.close_connection(history_admin_conn)
+
+    source_user_conn = engine.get_connection(config, admin=False, env="SOURCE")
+    try:
+        summary["source_database_links"] = engine.ensure_database_links(source_user_conn, [source_db_link])
+    finally:
+        engine.close_connection(source_user_conn)
+
+    history_user_conn = engine.get_connection(config, admin=False, env="HISTORY")
+    try:
+        summary["history_database_links"] = engine.ensure_database_links(history_user_conn, [history_db_link])
+    finally:
+        engine.close_connection(history_user_conn)
+
+    anything_created = any(summary.values())
+    for key, values in summary.items():
+        if values:
+            logger.info("Created %s: %s", key.replace("_", " "), ", ".join(values))
+    if not anything_created:
+        logger.info("All LimitsDb database objects are already present.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    run_cli()

limitsdb/cli/ldb_init.py

@@ -0,0 +1,60 @@
+"""Command line interface for bootstrapping schema/profile configurations."""
+
+from __future__ import annotations
+
+import argparse
+
+from limitsdb.core.ldb_crypto import load_or_create_key
+from limitsdb.core.ldb_logger import configure_logger, get_logger, reconfigure_logger
+from limitsdb.core.ldb_utils import init_schema
+
+configure_logger(level="WARNING")
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Initialize schema/profile config files",
+    )
+    parser.add_argument("--schema", required=True, help="Schema name (folder under schemas/)")
+    parser.add_argument("--profile", help="Profile name (e.g., dev, prod)")
+    parser.add_argument("--config-dir", help="Configuration root (overrides autodiscovery)")
+    parser.add_argument("--overwrite", action="store_true", help="Overwrite existing files")
+    parser.add_argument("--no-examples", action="store_true", help="Do not copy example ILM templates")
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        help="Logging level (e.g., DEBUG, INFO, WARNING)",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+    )
+    return parser.parse_args()
+
+
+def run_cli() -> None:
+    """Entry point for the ``ldb-init`` command."""
+    logger = get_logger("init")
+    try:
+        args = _parse_args()
+        reconfigure_logger(level=args.log_level)
+        # Ensure key exists (idempotent); secrets will be auto-encrypted if present.
+        load_or_create_key()
+        logger.info("Creating configuration files with defaults and help")
+        cfg_path, ilm_path, secrets_path, ilm_examples_path = init_schema(
+            schema=args.schema,
+            profile=getattr(args, "profile", None),
+            config_root=getattr(args, "config_dir", None),
+            overwrite=bool(args.overwrite),
+            with_examples=not bool(args.no_examples),
+            auto_encrypt=True,
+        )
+        logger.info("Initialized: %s", cfg_path)
+        logger.info("Initialized: %s", ilm_path)
+        logger.info("Initialized: %s", secrets_path)
+        if ilm_examples_path:
+            logger.info("Initialized: %s", ilm_examples_path)
+    except ValueError as exc:
+        logger.error("%s", exc)
+        raise SystemExit(1) from exc
+
+
+if __name__ == "__main__":  # pragma: no cover
+    run_cli()

limitsdb/cli/ldb_run.py

@@ -0,0 +1,53 @@
+"""Command line interface to execute ILM runs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from limitsdb.core.ldb_crypto import load_or_create_key
+from limitsdb.core.ldb_errors import LimitsDbError
+from limitsdb.core.ldb_logger import configure_logger, get_logger, reconfigure_logger
+from limitsdb.core.ldb_params_config import Config, build_config, parse_args
+from limitsdb.core.ldb_runner import ldb_run
+from limitsdb.core.ldb_utils import encrypt_secrets_in_place, secret_keys_from_config
+
+# Boot the logger early with a conservative level; we'll reconfigure after loading config.
+configure_logger(level="WARNING")
+
+
+def _mask_secrets(config_dict: dict[str, Any]) -> dict[str, Any]:
+    masked = dict(config_dict)
+    for key in secret_keys_from_config():
+        if masked.get(key):
+            masked[key] = "****"
+    return masked
+
+
+def run_cli() -> None:
+    """Entry point for the ``ldb-run`` command."""
+    logger = get_logger("run")
+    try:
+        args = parse_args()
+        if hasattr(args, "log_level"):
+            reconfigure_logger(level=args.log_level)
+        # Ensure encryption key exists and auto-encrypt secrets if user left cleartext.
+        load_or_create_key()
+        encrypt_secrets_in_place(
+            schema=args.schema,
+            profile=getattr(args, "profile", None),
+            config_root=getattr(args, "config_dir", None),
+        )
+        # Build final config and run
+        cfg_dict = build_config({}, args)
+        config = Config.from_dict(cfg_dict)
+        reconfigure_logger(level=config.execution.log_level)
+        logger.debug("Effective config: %s", _mask_secrets(config.to_dict()))
+        ldb_run(config)
+    except (LimitsDbError, ValueError, KeyError) as exc:
+        logger.error("%s", exc)
+        logger.error(exc, exc_info=True)
+        raise SystemExit(1) from exc
+
+
+if __name__ == "__main__":  # pragma: no cover
+    run_cli()

limitsdb/core/ldb_config_loader.py

@@ -0,0 +1,198 @@
+# limitsdb/core/ldb_config_loader.py
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+
+from limitsdb.core.ldb_crypto import decrypt as _DECRYPT
+from limitsdb.core.ldb_crypto import is_encrypted as _IS_ENC
+from limitsdb.core.ldb_errors import ConfigurationError, SecretError
+from limitsdb.core.ldb_logger import get_logger
+from limitsdb.core.ldb_utils import get_config_roots, resolve_schema_file, secret_keys_from_config
+
+logger = get_logger("config_loader")
+
+
+# --- utils --------------------------------------------------------------------
+def _deep_merge(a: Mapping[str, Any], b: Mapping[str, Any]) -> dict[str, Any]:
+    res: dict[str, Any] = dict(a)
+    for k, v in b.items():
+        av = res.get(k)
+        if isinstance(av, Mapping) and isinstance(v, Mapping):
+            res[k] = _deep_merge(cast(Mapping[str, Any], av), cast(Mapping[str, Any], v))
+        else:
+            res[k] = v
+    return res
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        text = path.read_text(encoding="utf-8")
+        data: Any = yaml.safe_load(text)
+    except (OSError, UnicodeError, yaml.YAMLError) as exc:
+        raise ConfigurationError(f"Unable to read YAML configuration at {path}: {exc}") from exc
+    if data is None:
+        return {}
+    if isinstance(data, dict):
+        return cast(dict[str, Any], data)
+    raise ConfigurationError(f"YAML root must be a mapping (dict) in {path}")
+
+
+def _load_secrets(path: Path) -> dict[str, Any]:
+    try:
+        data: Any = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise SecretError(f"Unable to read secrets file at {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise SecretError(f"Secrets root must be a mapping (object) in {path}")
+    return cast(dict[str, Any], data)
+
+
+def read_env_overrides(bindings: Mapping[str, str]) -> dict[str, Any]:
+    """Read only environment variables explicitly registered by Config metadata."""
+    out: dict[str, Any] = {}
+    for env_name, config_key in bindings.items():
+        if env_name not in os.environ:
+            continue
+        value = os.environ[env_name]
+        # basic typing
+        if value.lower() in ("true", "false"):
+            out[config_key] = value.lower() == "true"
+            continue
+        try:
+            out[config_key] = int(value)
+            continue
+        except ValueError:
+            pass
+        try:
+            out[config_key] = float(value)
+            continue
+        except ValueError:
+            pass
+        out[config_key] = value
+    return out
+
+
+def _automatic_config_paths(*, schema: str, profile: str | None, explicit_config_dir: str | None) -> list[Path]:
+    """Return existing runtime-config layers from lowest to highest priority."""
+    filename = f"config.{profile}.yml" if profile else "config.yml"
+    if explicit_config_dir:
+        roots = [Path(explicit_config_dir)]
+    else:
+        user_root, system_root = get_config_roots()
+        roots = [system_root, user_root]
+    return [path for root in roots if (path := root / "schemas" / schema / filename).exists()]
+
+
+def _apply_dot_set(cfg: dict[str, Any], key: str, value: Any) -> None:
+    cur = cfg
+    parts = key.split(".")
+    for p in parts[:-1]:
+        if p not in cur or not isinstance(cur[p], dict):
+            cur[p] = {}
+        cur = cur[p]
+    cur[parts[-1]] = value
+
+
+def _apply_overrides(cfg: dict[str, Any], kvs: dict[str, Any]) -> dict[str, Any]:
+    out = dict(cfg)
+    for k, v in kvs.items():
+        _apply_dot_set(out, k, v)
+    return out
+
+
+# --- loaders ------------------------------------------------------------------
+def load_runtime_config(
+    *,
+    schema: str,
+    profile: str | None,
+    cli_sets: dict[str, Any],
+    env_bindings: Mapping[str, str] | None = None,
+    explicit_config_file: str | None = None,
+    explicit_config_dir: str | None = None,
+    enforce_encrypted_secrets: bool = True,
+) -> dict[str, Any]:
+    """
+    config_file → registered environment variables → --set
+    Then inject **decrypted** secrets from schemas/<schema>/secrets*.json.
+    If enforce_encrypted_secrets=True, plaintext secrets are rejected.
+    """
+    cfg: dict[str, Any] = {}
+    # 1-2) System then user config, or the single explicitly selected root.
+    for config_path in _automatic_config_paths(schema=schema, profile=profile, explicit_config_dir=explicit_config_dir):
+        cfg = _deep_merge(cfg, _load_yaml(config_path))
+    # 3) Explicit config file is an overlay, not a replacement for the
+    # automatically discovered layers.
+    if explicit_config_file:
+        config_file = resolve_schema_file(
+            schema=schema,
+            profile=profile,
+            explicit_config_dir=explicit_config_dir,
+            explicit_file=explicit_config_file,
+            prefix_name="config",
+            extension_name="yml",
+            description="configuration file",
+        )
+        assert config_file is not None
+        cfg = _deep_merge(cfg, _load_yaml(Path(config_file)))
+    # 4) ENV
+    env_over = read_env_overrides(env_bindings or {})
+    if env_over:
+        cfg = _apply_overrides(cfg, env_over)
+    # 5) CLI --set
+    if cli_sets:
+        cfg = _apply_overrides(cfg, cli_sets)
+    # 6) Secrets (user > system), strictly enforced
+    secrets: dict[str, Any] = {}
+    secrets_path = resolve_schema_file(
+        schema=schema,
+        profile=profile,
+        explicit_config_dir=explicit_config_dir,
+        explicit_file=None,
+        prefix_name="secrets",
+        extension_name="json",
+        description="secrets file",
+    )
+    if secrets_path:
+        secrets = _load_secrets(Path(secrets_path))
+    if secrets:
+        for k in secret_keys_from_config():
+            val = secrets.get(k)
+            if val is None or val == "":
+                continue
+            if isinstance(val, str) and _IS_ENC(val):
+                try:
+                    cfg[k] = _DECRYPT(val)
+                except Exception as exc:
+                    raise SecretError(f"Unable to decrypt secret '{k}' at {secrets_path}") from exc
+            else:
+                if enforce_encrypted_secrets:
+                    where = f" at {secrets_path}" if secrets_path else ""
+                    raise SecretError(f"Secret '{k}' must be encrypted (enc:v1:aes256gcm:...){where}")
+                cfg[k] = val  # only if you explicitly disabled enforcement
+    # minimal defaults
+    return cfg
+
+
+def load_ilm_config(*, schema: str, profile: str | None, explicit_config_dir: str | None = None) -> dict[str, Any]:
+    """Load ILM config from schema/profile layers."""
+    ilm: dict[str, Any] = {}
+    ilm_config_path = resolve_schema_file(
+        schema=schema,
+        profile=profile,
+        explicit_config_dir=explicit_config_dir,
+        explicit_file=None,
+        prefix_name="ilm",
+        extension_name="yml",
+        description="ILM configuration file",
+    )
+    if ilm_config_path:
+        ilm = _load_yaml(Path(ilm_config_path))
+    return ilm

limitsdb/core/ldb_crypto.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import os
+import stat
+from pathlib import Path
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from limitsdb.core.ldb_errors import SecretError
+
+LDB_DIR = Path(os.path.expanduser("~/.limitsdb"))
+KEY_PATH = LDB_DIR / "ldb.key"
+
+
+def _b64e(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).decode("ascii")
+
+
+def _b64d(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s.encode("ascii"))
+
+
+def _ensure_dir() -> None:
+    LDB_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _chmod600(path: Path) -> None:
+    try:
+        os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError as exc:
+        raise SecretError(f"Unable to restrict permissions on key file {path}") from exc
+
+
+def _generate_aes256_key() -> bytes:
+    return AESGCM.generate_key(256)
+
+
+def load_or_create_key() -> bytes:
+    env = os.getenv("LDB_MASTER_KEY")
+    if env:
+        if all(c in "0123456789abcdefABCDEF" for c in env) and len(env) == 64:
+            return bytes.fromhex(env)
+        try:
+            k = base64.b64decode(env)
+            if len(k) == 32:
+                return k
+        except (binascii.Error, ValueError):
+            pass
+        if len(env) == 32:
+            return env.encode("utf-8")
+        raise SecretError("Invalid LDB_MASTER_KEY: use hex(64) / base64(32B) / raw(32B).")
+
+    _ensure_dir()
+    if KEY_PATH.exists():
+        data = KEY_PATH.read_bytes()
+        try:
+            key = base64.b64decode(data)
+        except (binascii.Error, ValueError):
+            key = data
+        if len(key) != 32:
+            raise SecretError(f"Invalid key at {KEY_PATH} (expected 32 bytes).")
+        return key
+
+    key = _generate_aes256_key()
+    KEY_PATH.write_bytes(base64.b64encode(key))
+    _chmod600(KEY_PATH)
+    return key
+
+
+def encrypt(plaintext: str, key: bytes | None = None) -> str:
+    key = key or load_or_create_key()
+    aes = AESGCM(key)
+    nonce = os.urandom(12)
+    ct = aes.encrypt(nonce, plaintext.encode("utf-8"), associated_data=None)
+    return f"enc:v1:aes256gcm:{_b64e(nonce)}:{_b64e(ct)}"
+
+
+def is_encrypted(val: str) -> bool:
+    return val.startswith("enc:v1:aes256gcm:")
+
+
+def decrypt(token: str, key: bytes | None = None) -> str:
+    if not is_encrypted(token):
+        raise SecretError("Attempted to decrypt a non-encrypted token.")
+    key = key or load_or_create_key()
+    _, _, _, nonce_b64, ct_b64 = token.split(":", 4)
+    aes = AESGCM(key)
+    pt = aes.decrypt(_b64d(nonce_b64), _b64d(ct_b64), associated_data=None)
+    return pt.decode("utf-8")