tawn 0.1.0__py3-none-any.whl

tawn/__init__.py

@@ -0,0 +1,3 @@
+"""Tawn — the personal digital twin. Capability-gated memory core."""
+
+__version__ = "0.1.0"

tawn/_webserver.py

@@ -0,0 +1,66 @@
+"""Internal entrypoint for the background web server process.
+
+Run as: python -m tawn._webserver <port>
+Not intended for direct user invocation — use `tawn web start/stop`.
+"""
+
+import sys
+
+
+def _start_auto_compiler(engine) -> None:
+    import threading
+    import time
+    from tawn.db import session as db_session
+    from tawn.compiler.compiler import run_compile as run_compiler
+    from tawn.federation.merge import scan_all_sources, merge_pending
+    from tawn.home import tawn_home
+
+    def _bootstrap_then_loop():
+        # Bootstrap: ingest + merge all existing federation files on startup.
+        # Runs in this background thread, not before uvicorn.run() — a
+        # source directory can hold thousands of files (a size cap on
+        # individual files exists, but the walk itself over many entries
+        # still takes real time), and the web server must bind its port
+        # immediately regardless of how long that one-time scan takes.
+        try:
+            with db_session(engine) as s:
+                n = scan_all_sources(tawn_home(), s)
+                if n > 0:
+                    merge_pending(tawn_home(), s)
+        except Exception:
+            pass
+
+        while True:
+            try:
+                with db_session(engine) as session:
+                    run_compiler(tawn_home(), session)
+            except Exception:
+                pass
+            time.sleep(30 * 60)  # 30-minute interval
+
+    t = threading.Thread(target=_bootstrap_then_loop, name="tawn-auto-compiler", daemon=True)
+    t.start()
+
+
+def main(port: int = 8787) -> None:
+    import uvicorn
+    from tawn.db import make_engine
+    from tawn.web import create_app
+
+    from tawn.db import init_db
+    from tawn.updater import start_daily_updater
+    engine = make_engine(pooled=True)
+    init_db(engine)
+    start_daily_updater()
+    _start_auto_compiler(engine)
+    uvicorn.run(
+        create_app(engine),
+        host="127.0.0.1",
+        port=port,
+        log_level="warning",
+    )
+
+
+if __name__ == "__main__":
+    port = int(sys.argv[1]) if len(sys.argv) > 1 else 8787
+    main(port)

tawn/branding.py

@@ -0,0 +1,82 @@
+"""Branded terminal identity (brand/README.md: Cairn × Sandstone & Lapis).
+
+The cairn: three stones, lapis capstone. The wordmark lettering follows
+the drawn monoline mark — rounded, lowercase, final n in lapis.
+Colors are the brand tokens; Rich truecolor degrades gracefully.
+"""
+
+from rich.columns import Columns
+from rich.console import Group
+from rich.padding import Padding
+from rich.table import Table
+from rich.text import Text
+
+# brand tokens (brand/tokens.css) — dark-ground values; terminals are
+# usually dark, and both lapis values pass on light too.
+LAPIS = "#4A7BC8"
+BONE = "#EFE9DC"
+MUTED = "#ADA28C"
+
+_CAIRN = [
+    ("   ▄██▄   ", LAPIS),
+    ("   ▀██▀   ", LAPIS),
+    ("  ▄████▄  ", BONE),
+    ("  ▀████▀  ", BONE),
+    (" ▄██████▄ ", BONE),
+    (" ▀██████▀ ", BONE),
+]
+
+# monoline block lettering — t a w in bone, n in lapis (the letter that
+# makes it *own*), matching the wordmark rule in brand/README.md
+_LETTERS = [
+    ("▄█▄  ▄▀▀▄  █   █  ", "█▀▀▄"),
+    (" █   █▄▄█  █ ▄ █  ", "█  █"),
+    (" ▀▄  █  █  ▀▄▀▄▀  ", "█  █"),
+]
+
+
+def cairn() -> Text:
+    art = Text()
+    for i, (line, color) in enumerate(_CAIRN):
+        art.append(line, style=color)
+        if i < len(_CAIRN) - 1:
+            art.append("\n")
+    return art
+
+
+def wordmark() -> Text:
+    art = Text()
+    for i, (taw, n) in enumerate(_LETTERS):
+        art.append(taw, style=f"bold {BONE}")
+        art.append(n, style=f"bold {LAPIS}")
+        if i < len(_LETTERS) - 1:
+            art.append("\n")
+    return art
+
+
+def banner(version: str) -> Group:
+    lockup = Columns([cairn(), Padding(wordmark(), (1, 0, 0, 2))], padding=(0, 2))
+    tag = Text()
+    tag.append("the twin you own", style=f"italic {MUTED}")
+    tag.append(f"  ·  v{version}", style=MUTED)
+    return Group(lockup, Padding(tag, (0, 0, 0, 1)))
+
+
+def status_table(rows: list[tuple[str, bool, str]]) -> Table:
+    t = Table(show_header=False, box=None, padding=(0, 1))
+    t.add_column(style=MUTED)
+    t.add_column()
+    t.add_column(style=MUTED)
+    for name, ok, detail in rows:
+        mark = Text("●", style="green" if ok else "red")
+        t.add_row(name, mark, detail)
+    return t
+
+
+def commands_table(commands: list[tuple[str, str]]) -> Table:
+    t = Table(show_header=False, box=None, padding=(0, 1))
+    t.add_column(style=f"bold {LAPIS}")
+    t.add_column(style=MUTED)
+    for cmd, desc in commands:
+        t.add_row(cmd, desc)
+    return t

tawn/capability/__init__.py

@@ -0,0 +1 @@
+"""Capability layer: grants, integrity, audit, and the FS chokepoint."""

tawn/capability/audit.py

@@ -0,0 +1,87 @@
+"""Append-only JSONL audit log (spec §10: "audit everything").
+
+Immutability contract: every entry includes a sha256 chain hash linking it
+to the previous entry — tampering breaks the chain. File is chmod 600.
+"""
+
+import csv
+import hashlib
+import io
+import json
+import os
+import stat
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+class AuditLog:
+    def __init__(self, path: Path):
+        self.path = path
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def _last_hash(self) -> str:
+        if not self.path.exists():
+            return "genesis"
+        lines = [l for l in self.path.read_text().splitlines() if l]
+        if not lines:
+            return "genesis"
+        return json.loads(lines[-1]).get("chain", "genesis")
+
+    def record(self, op: str, target: str, ok: bool, detail: str = "", actor: str = "system") -> None:
+        """actor: who initiated this — "cli" | "web" | "chat" | "mcp" | "system"
+        (background jobs: auto-compiler, scheduled snapshots, federation watcher).
+        """
+        prev_hash = self._last_hash()
+        entry = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "op": op,
+            "target": target,
+            "ok": ok,
+            "detail": detail,
+            "actor": actor,
+        }
+        # chain hash = sha256 of prev_hash + this entry (without chain field)
+        payload = prev_hash + json.dumps(entry, sort_keys=True)
+        entry["chain"] = hashlib.sha256(payload.encode()).hexdigest()[:16]
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry) + "\n")
+        # restrict file to owner-only after every write
+        try:
+            os.chmod(self.path, stat.S_IRUSR | stat.S_IWUSR)
+        except OSError:
+            pass
+
+    def entries(self, limit: int = 0, offset: int = 0) -> list[dict]:
+        if not self.path.exists():
+            return []
+        all_entries = [json.loads(line) for line in self.path.read_text().splitlines() if line]
+        if offset:
+            all_entries = all_entries[offset:]
+        if limit:
+            all_entries = all_entries[:limit]
+        return all_entries
+
+    def verify_chain(self) -> bool:
+        """Returns True if no tampering detected."""
+        all_entries = self.entries()
+        prev = "genesis"
+        for entry in all_entries:
+            chain = entry.pop("chain", "")
+            payload = prev + json.dumps(entry, sort_keys=True)
+            expected = hashlib.sha256(payload.encode()).hexdigest()[:16]
+            entry["chain"] = chain
+            if chain != expected:
+                return False
+            prev = chain
+        return True
+
+    def export_csv(self) -> str:
+        buf = io.StringIO()
+        fields = ["ts", "op", "target", "ok", "detail", "actor", "chain"]
+        writer = csv.DictWriter(buf, fieldnames=fields, extrasaction="ignore")
+        writer.writeheader()
+        writer.writerows(self.entries())
+        return buf.getvalue()
+
+    def export_json(self) -> str:
+        return json.dumps(self.entries(), indent=2)

tawn/capability/fs.py

@@ -0,0 +1,67 @@
+"""MediatedFS — the single filesystem chokepoint (design spec §2).
+
+"A write outside write: is impossible by construction, not by good
+behaviour." Every component must do file I/O through this class; direct
+open() elsewhere in the codebase is a review-rejectable defect.
+
+Resolution first, check second: expanduser().resolve() collapses `..`
+and follows symlinks, so a path is judged by where it actually lands.
+The Tawn home is implicitly readable+writable (Tawn manages its own
+state); everything else needs an explicit grant.
+"""
+
+from pathlib import Path
+
+from tawn.capability.audit import AuditLog
+from tawn.capability.grants import Grants
+
+
+class GrantError(PermissionError):
+    """Access outside the granted capability surface."""
+
+
+class MediatedFS:
+    def __init__(self, grants: Grants, audit: AuditLog, home: Path):
+        self.grants = grants
+        self.audit = audit
+        self.home = home.expanduser().resolve()
+
+    # -- policy -------------------------------------------------------------
+
+    @staticmethod
+    def _under(path: Path, root: Path) -> bool:
+        return path == root or root in path.parents
+
+    def _resolve(self, path: Path | str) -> Path:
+        return Path(path).expanduser().resolve()
+
+    def _may_read(self, p: Path) -> bool:
+        roots = [*self.grants.read, *self.grants.write, self.home]
+        return any(self._under(p, r) for r in roots)
+
+    def _may_write(self, p: Path) -> bool:
+        roots = [*self.grants.write, self.home]
+        return any(self._under(p, r) for r in roots)
+
+    def _gate(self, op: str, p: Path, allowed: bool) -> None:
+        self.audit.record(op, str(p), ok=allowed, detail="" if allowed else "no grant")
+        if not allowed:
+            raise GrantError(f"{op} denied outside grants: {p}")
+
+    # -- operations -----------------------------------------------------------
+
+    def read_text(self, path: Path | str) -> str:
+        p = self._resolve(path)
+        self._gate("fs.read", p, self._may_read(p))
+        return p.read_text()
+
+    def write_text(self, path: Path | str, content: str) -> None:
+        p = self._resolve(path)
+        self._gate("fs.write", p, self._may_write(p))
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content)
+
+    def list_dir(self, path: Path | str) -> list[Path]:
+        p = self._resolve(path)
+        self._gate("fs.list", p, self._may_read(p))
+        return sorted(p.iterdir())

tawn/capability/grants.py

@@ -0,0 +1,53 @@
+"""Capability grants (design spec §2): deny-all until the user grants.
+
+grants.yaml is user-editable, git-ignored, integrity-checked (integrity.py).
+"""
+
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field
+
+from tawn.capability.integrity import verify
+
+#: Written by `tawn init`. Deny-all: every list empty, system off.
+DEFAULT_GRANTS_YAML = """\
+# ~/.tawn/grants.yaml — capability grants (deny-all by default)
+# Edit, then run `tawn grant confirm` to accept the change.
+# Docs: design spec §2. Every grant use is written to audit.log.
+read: []      # read-only indexing, e.g. [~/code/projectX, ~/papers]
+write: []     # the ONLY writable paths, e.g. [~/Obsidian/Tawn/reviews]
+observe: []   # ambient watchers, opt-in each, e.g. [vscode, git]
+system: false # full-system awareness; per-session opt-in (§6.4)
+mcp: []       # enabled MCP servers, e.g. [github, gmail-ro]
+"""
+
+
+class Grants(BaseModel):
+    read: list[Path] = Field(default_factory=list)
+    write: list[Path] = Field(default_factory=list)
+    observe: list[str] = Field(default_factory=list)
+    system: bool = False
+    mcp: list[str] = Field(default_factory=list)
+
+    @classmethod
+    def deny_all(cls) -> "Grants":
+        return cls()
+
+    @classmethod
+    def load(cls, path: Path) -> "Grants":
+        if not path.exists():
+            return cls.deny_all()
+        data = yaml.safe_load(path.read_text()) or {}
+        grants = cls.model_validate(data)
+        grants.read = [Path(p).expanduser().resolve() for p in grants.read]
+        grants.write = [Path(p).expanduser().resolve() for p in grants.write]
+        return grants
+
+
+def load_verified(path: Path) -> "Grants":
+    """The only sanctioned way to obtain grants: integrity check, then load."""
+    if not path.exists():
+        return Grants.deny_all()
+    verify(path)
+    return Grants.load(path)

tawn/capability/integrity.py

@@ -0,0 +1,38 @@
+"""grants.yaml integrity (design spec §2: "git-ignored, integrity-checked").
+
+SHA-256 sidecar. A hand edit is legal but must be acknowledged with
+`tawn grant confirm`; until then Tawn refuses to load the grants.
+"""
+
+import hashlib
+from pathlib import Path
+
+
+class IntegrityError(Exception):
+    """grants.yaml changed without `tawn grant confirm` (or sidecar missing)."""
+
+
+def sidecar(path: Path) -> Path:
+    return path.with_name(path.name + ".sha256")
+
+
+def _digest(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def confirm(path: Path) -> str:
+    digest = _digest(path)
+    sidecar(path).write_text(digest + "\n")
+    return digest
+
+
+def verify(path: Path) -> None:
+    side = sidecar(path)
+    if not side.exists():
+        raise IntegrityError(
+            f"{side.name} missing — run `tawn grant confirm` to accept {path.name}"
+        )
+    if side.read_text().strip() != _digest(path):
+        raise IntegrityError(
+            f"{path.name} was edited since last confirm — review it, then run `tawn grant confirm`"
+        )