cfgit 0.1.0__py3-none-any.whl

cfg/core/hashing.py

@@ -0,0 +1,102 @@
+# Copyright 2026 Mohammad Ausaf. Licensed under the Apache License, Version 2.0.
+"""Canonical record hashing for cfgit."""
+from __future__ import annotations
+
+from copy import deepcopy
+from datetime import datetime, timezone
+from decimal import Decimal
+import fnmatch
+import hashlib
+import json
+import math
+import unicodedata
+from typing import Any
+
+from cfg.core.config import CollectionConfig
+
+
+def stored_doc(doc: dict[str, Any], coll: CollectionConfig) -> dict[str, Any]:
+    """Return the doc shape stored in history.
+
+    Secret fields are removed. Ignored fields stay stored but do not hash.
+    """
+    out = deepcopy(doc)
+    for path in coll.secret_fields:
+        _drop_path(out, path)
+    return out
+
+
+def hash_doc(doc: dict[str, Any], coll: CollectionConfig) -> str:
+    stripped = strip_for_hash(doc, coll)
+    payload = json.dumps(_normalize(stripped), sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def strip_for_hash(doc: dict[str, Any], coll: CollectionConfig) -> dict[str, Any]:
+    out = deepcopy(doc)
+    for key in list(out.keys()):
+        if key in coll.ignore_fields:
+            out.pop(key, None)
+            continue
+        if any(fnmatch.fnmatchcase(key, pat) for pat in coll.ignore_patterns):
+            out.pop(key, None)
+    for path in coll.ignore_paths:
+        _drop_path(out, path)
+    for path in coll.secret_fields:
+        _drop_path(out, path)
+    return out
+
+
+def _drop_path(doc: dict[str, Any], dotted: str) -> None:
+    parts = [p for p in dotted.split(".") if p]
+    if not parts:
+        return
+    cur: Any = doc
+    for part in parts[:-1]:
+        if not isinstance(cur, dict) or part not in cur:
+            return
+        cur = cur[part]
+    if isinstance(cur, dict):
+        cur.pop(parts[-1], None)
+
+
+def _normalize(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            str(k): _normalize(v)
+            for k, v in value.items()
+            if v is not None
+        }
+    if isinstance(value, (list, tuple)):
+        return [_normalize(v) for v in value]
+    if _is_bson_decimal128(value):
+        return _normalize(value.to_decimal())
+    if isinstance(value, str):
+        return unicodedata.normalize("NFC", value)
+    if isinstance(value, bool) or value is None:
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        if math.isnan(value) or math.isinf(value):
+            raise ValueError("cannot hash NaN or Infinity")
+        if value.is_integer():
+            return int(value)
+        return Decimal(str(value)).normalize().to_eng_string()
+    if isinstance(value, Decimal):
+        if value == value.to_integral_value():
+            return int(value)
+        return value.normalize().to_eng_string()
+    if isinstance(value, datetime):
+        dt = value
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        dt = dt.astimezone(timezone.utc)
+        dt = dt.replace(microsecond=(dt.microsecond // 1000) * 1000)
+        return dt.isoformat().replace("+00:00", "Z")
+    return str(value)
+
+
+def _is_bson_decimal128(value: Any) -> bool:
+    cls = value.__class__
+    return cls.__name__ == "Decimal128" and cls.__module__.startswith("bson.")

cfg/core/identity.py

@@ -0,0 +1,213 @@
+# Copyright 2026 Mohammad Ausaf. Licensed under the Apache License, Version 2.0.
+"""Identity resolution for cfgit.
+
+The short fingerprint is for display only. Authentication always uses either a
+database-authenticated principal or a full SHA-256 token hash comparison.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import getpass
+import hashlib
+import hmac
+import os
+import subprocess
+from typing import Any
+
+from cfg.core.config import EnvConfig, IdentityConfig
+
+
+MIN_TOKEN_LENGTH = 8
+
+
+class IdentityError(ValueError):
+    """The environment requires verified identity and cfgit could not prove it."""
+
+
+@dataclass(frozen=True)
+class Identity:
+    author: str
+    mode: str
+    source: str
+    authenticated: bool
+    fingerprint: str
+    principal: str | None = None
+    credential: str | None = None
+
+    @property
+    def display(self) -> str:
+        return f"{self.author}#{self.fingerprint}"
+
+    def history_meta(self) -> dict[str, Any]:
+        meta: dict[str, Any] = {
+            "mode": self.mode,
+            "author": self.author,
+            "source": self.source,
+            "authenticated": self.authenticated,
+            "fingerprint": self.fingerprint,
+        }
+        if self.principal:
+            meta["principal"] = self.principal
+        if self.credential:
+            meta["credential"] = self.credential
+        return meta
+
+
+def resolve_identity(
+    env: EnvConfig,
+    adapter: Any,
+    *,
+    explicit_author: str | None = None,
+) -> Identity:
+    cfg = env.identity
+    if cfg.mode == "open":
+        return self_asserted_identity(resolve_self_asserted_author(explicit_author), cfg=cfg)
+
+    errors: list[str] = []
+    for source in cfg.sources:
+        if source == "token":
+            identity, error = _identity_from_token(cfg, explicit_author=explicit_author)
+        elif source == "db_principal":
+            identity, error = _identity_from_db_principal(cfg, adapter, explicit_author=explicit_author)
+        else:  # config validation should prevent this
+            identity, error = None, f"unsupported identity source {source}"
+        if identity is not None:
+            return identity
+        if error:
+            errors.append(error)
+
+    detail = "; ".join(errors) if errors else "no configured identity source produced a verified identity"
+    raise IdentityError(
+        f"{env.name} requires {cfg.mode} identity, but cfgit could not verify the caller: {detail}"
+    )
+
+
+def resolve_self_asserted_author(explicit: str | None = None) -> str:
+    if explicit:
+        return explicit
+    if os.environ.get("CFG_AUTHOR"):
+        return os.environ["CFG_AUTHOR"]
+    try:
+        out = subprocess.check_output(["git", "config", "user.email"], text=True).strip()
+        if out:
+            return out
+    except Exception:
+        pass
+    return getpass.getuser()
+
+
+def self_asserted_identity(author: str, *, cfg: IdentityConfig) -> Identity:
+    return _identity(
+        author=author,
+        cfg=cfg,
+        mode=cfg.mode,
+        source="self_asserted",
+        authenticated=False,
+    )
+
+
+def hash_token(token: str) -> str:
+    return "sha256:" + hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+def token_fingerprint(token_hash: str, *, chars: int = 5) -> str:
+    return _hash_hex(token_hash)[:chars]
+
+
+def _identity_from_token(
+    cfg: IdentityConfig,
+    *,
+    explicit_author: str | None,
+) -> tuple[Identity | None, str | None]:
+    raw = os.environ.get(cfg.token_env)
+    if not raw:
+        return None, f"{cfg.token_env} is not set"
+    token = raw.strip()
+    if len(token) < MIN_TOKEN_LENGTH:
+        return None, (
+            f"{cfg.token_env} is too short; identity tokens need at least {MIN_TOKEN_LENGTH} "
+            "characters, and short fingerprints are display-only"
+        )
+    hashed = hash_token(token)
+    for item in cfg.tokens:
+        if hmac.compare_digest(hashed, item.token_hash):
+            _reject_author_mismatch(explicit_author, item.author)
+            credential = item.name or f"token:{token_fingerprint(item.token_hash, chars=cfg.fingerprint_chars)}"
+            return (
+                Identity(
+                    author=item.author,
+                    mode=cfg.mode,
+                    source="token",
+                    authenticated=True,
+                    fingerprint=token_fingerprint(item.token_hash, chars=cfg.fingerprint_chars),
+                    principal=credential,
+                    credential=credential,
+                ),
+                None,
+            )
+    return None, f"{cfg.token_env} did not match any configured identity token hash"
+
+
+def _identity_from_db_principal(
+    cfg: IdentityConfig,
+    adapter: Any,
+    *,
+    explicit_author: str | None,
+) -> tuple[Identity | None, str | None]:
+    getter = getattr(adapter, "authenticated_principal", None)
+    if not callable(getter):
+        return None, f"{adapter.backend_name()} adapter does not expose an authenticated DB principal"
+    principal = getter()
+    if not principal:
+        return None, f"{adapter.backend_name()} connection has no authenticated DB principal"
+    author = cfg.principal_map.get(principal) or cfg.principal_map.get(principal.lower()) or principal
+    _reject_author_mismatch(explicit_author, author)
+    return (
+        _identity(
+            author=author,
+            cfg=cfg,
+            mode=cfg.mode,
+            source="db_principal",
+            authenticated=True,
+            principal=principal,
+        ),
+        None,
+    )
+
+
+def _identity(
+    *,
+    author: str,
+    cfg: IdentityConfig,
+    mode: str,
+    source: str,
+    authenticated: bool,
+    principal: str | None = None,
+    credential: str | None = None,
+) -> Identity:
+    return Identity(
+        author=author,
+        mode=mode,
+        source=source,
+        authenticated=authenticated,
+        principal=principal,
+        credential=credential,
+        fingerprint=_fingerprint(author=author, source=source, principal=principal, chars=cfg.fingerprint_chars),
+    )
+
+
+def _fingerprint(*, author: str, source: str, principal: str | None, chars: int) -> str:
+    value = "\0".join([source, author, principal or ""])
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()[:chars]
+
+
+def _reject_author_mismatch(explicit_author: str | None, verified_author: str) -> None:
+    if explicit_author and explicit_author.strip().lower() != verified_author.strip().lower():
+        raise IdentityError(
+            f"--author {explicit_author} does not match verified identity {verified_author}; "
+            "verified modes do not accept self-asserted author strings"
+        )
+
+
+def _hash_hex(value: str) -> str:
+    return value.lower().removeprefix("sha256:")

cfg/interfaces/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2026 Mohammad Ausaf. Licensed under the Apache License, Version 2.0.
+"""Shared interfaces for CLI, MCP, and UI."""