engraphis 0.5.2__tar.gz → 0.7.0__tar.gz

{engraphis-0.5.2/engraphis.egg-info → engraphis-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engraphis
-Version: 0.5.2
+Version: 0.7.0
 Summary: Local-first AI memory engine for agents — Ebbinghaus decay, interaction-aware recall, bi-temporal facts, hybrid retrieval, and an MCP server. You bring the LLM.
 Author: The Engraphis Authors
 License: Apache-2.0

{engraphis-0.5.2 → engraphis-0.7.0}/engraphis/autosync.py

@@ -2,62 +2,44 @@
 
 Cloud sync (``core/sync.py`` + the relay transport) already replicates the memory store
 across a user's devices and, on Team, across the whole group. By default a human presses
-"Sync now" in the dashboard (or crons ``scripts/sync.py``). This module adds the two
-hands-off options the Team tier asks for — both **opt-in, both off by default**, and both
-toggleable by any team member (not just admins), because keeping the shared store converged
-is everyone's job:
+"Sync now" in the dashboard (or crons ``scripts/sync.py``). This module adds the hands-off
+option the Team tier asks for: a *persisted auto-sync policy* plus a background runner, so
+the store — and every teammate's view of it — stays converged **on a cadence** (minimum
+5 minutes) without anyone clicking.
 
-* **cadence** (``enabled`` + ``cadence_minutes``) — sync the whole team's store on a timer.
-* **on_update** (``on_update``) — sync shortly after *this* member changes a memory, so
-  their edit reaches the rest of the team without waiting for the next tick.
-
-A background loop (``dashboard_app._maybe_start_autosync``) drives both: it wakes on the
-cadence clock and on a write signal (:func:`mark_dirty`, raised by a small dashboard
-middleware after any successful memory-write request), debounces a burst of edits, then
-runs one convergent sync.
+Cadence-only on purpose. A fixed interval caps relay traffic to a known ceiling (at most a
+handful of syncs an hour), whereas syncing on every edit would make load — and, on a
+metered relay host, cost — scale with how much the team types. Each sync is a full-state
+bundle per workspace (export + upload + pull peers), so predictable beats chatty.
 
 House style (AGENTS.md §3): pure policy helpers + thin IO, exactly like
 :mod:`engraphis.automation`. There is deliberately **no gate in here** — the sync-feature
-gate lives at the entry points (the ``/api/sync/*`` routes) and, non-bypassably, at the
-relay itself, which verifies the license server-side. ``run_once`` re-uses the same audited
+gate lives at the entry points (the ``/api/sync/*`` routes; changing the policy is
+admin-only in team mode, see ``inspector/auth.min_role``) and, non-bypassably, at the relay
+itself, which verifies the license server-side. ``run_once`` re-uses the same audited
 per-workspace sync the dashboard button already calls: it adds a *trigger*, never a new
 trust boundary. A pulled bundle is still untrusted and still validated/clamped by
-``SyncEngine.apply_bundle`` whether a human, the timer, or an edit initiated the pull
-(SECURITY.md, docs/SYNC.md).
+``SyncEngine.apply_bundle`` whether a human or the timer initiated the pull (SECURITY.md,
+docs/SYNC.md).
 """
 from __future__ import annotations
 
 import json
 import os
-import threading
 import time
 from pathlib import Path
 from typing import Any, Optional
 
-#: Everything off until the operator opts in; a 15-minute cadence balances freshness
-#: against relay chatter, floored at ``MIN_CADENCE_MINUTES`` so a fat-fingered 0 can't
-#: hammer the relay.
+#: Off until the operator opts in; a 15-minute cadence balances freshness against relay
+#: chatter, floored at ``MIN_CADENCE_MINUTES`` so a fat-fingered 0 can't hammer the relay.
 DEFAULT_POLICY: dict = {
-    "enabled": False,        # cadence (timer) sync
+    "enabled": False,
     "cadence_minutes": 15,
-    "on_update": False,      # sync shortly after a local memory write
 }
 MIN_CADENCE_MINUTES = 5
-#: Settle window (seconds) after the first write in a burst before we sync, so a flurry of
-#: edits collapses into one push instead of one-per-edit.
-UPDATE_DEBOUNCE_SECONDS = 3.0
 
 _POLICY_KEYS = set(DEFAULT_POLICY)
 
-# ── write-signal plumbing (in-memory, per dashboard process) ──────────────────────────
-#: Set by :func:`mark_dirty` to wake the background loop the moment a write lands.
-WAKE = threading.Event()
-#: Timestamp of the earliest un-synced write in the current burst (0.0 == nothing pending).
-_DIRTY_AT: float = 0.0
-#: Cached ``on_update`` flag so the hot write path never touches disk. ``None`` == unknown
-#: (lazily loaded from the policy on first use; refreshed by :func:`save_policy`).
-_ON_UPDATE: Optional[bool] = None
-
 
 def policy_path() -> Path:
     """Where the auto-sync policy is persisted (next to the DB, else ~/.engraphis)."""
@@ -81,14 +63,16 @@ def _read() -> dict:
 
 
 def normalize_policy(raw: dict) -> dict:
-    """Coerce arbitrary input into a safe, fully-populated policy (never raises)."""
+    """Coerce arbitrary input into a safe, fully-populated policy (never raises).
+
+    ``cadence_minutes`` is floored at :data:`MIN_CADENCE_MINUTES` (5) so neither a slip of
+    the finger nor a crafted request can drive the relay faster than once every 5 minutes."""
     raw = raw if isinstance(raw, dict) else {}
     p = dict(DEFAULT_POLICY)
     for k in _POLICY_KEYS:
         if k in raw:
             p[k] = raw[k]
     p["enabled"] = bool(p["enabled"])
-    p["on_update"] = bool(p["on_update"])
     try:
         p["cadence_minutes"] = max(MIN_CADENCE_MINUTES, int(p["cadence_minutes"] or 15))
     except (TypeError, ValueError):
@@ -124,18 +108,14 @@ def _write(doc: dict) -> None:
 def save_policy(policy: dict) -> dict:
     """Persist the auto-sync policy, preserving last_run/last_result telemetry."""
     existing = _read()
-    norm = normalize_policy(policy)
-    _write({"policy": norm,
+    _write({"policy": normalize_policy(policy),
             "last_run": existing.get("last_run"),
             "last_result": existing.get("last_result")})
-    global _ON_UPDATE
-    _ON_UPDATE = norm["on_update"]   # keep the hot-path cache honest
-    WAKE.set()                        # let the loop re-evaluate cadence/on_update at once
     return load_policy()
 
 
 def due(policy: dict, *, now: Optional[float] = None) -> bool:
-    """True when an enabled *cadence* policy is due to run (interval elapsed since run)."""
+    """True when an enabled policy is due to run (cadence elapsed since last_run)."""
     if not policy.get("enabled"):
         return False
     now = time.time() if now is None else now
@@ -148,42 +128,6 @@ def due(policy: dict, *, now: Optional[float] = None) -> bool:
         return True
 
 
-# ── write signalling (called from the dashboard middleware, cheap + no disk IO) ───────
-def _on_update_enabled() -> bool:
-    """Cached view of the ``on_update`` flag; lazily loads the policy once, then trusts
-    :func:`save_policy` to refresh it. Keeps :func:`mark_dirty` off the disk."""
-    global _ON_UPDATE
-    if _ON_UPDATE is None:
-        _ON_UPDATE = bool(load_policy().get("on_update"))
-    return _ON_UPDATE
-
-
-def mark_dirty(*, now: Optional[float] = None) -> None:
-    """Signal that a local memory write happened. No-op unless ``on_update`` is enabled, so
-    it is safe (and free) to call from the request path on every write. Records the burst's
-    start time and wakes the background loop; the loop debounces before syncing."""
-    if not _on_update_enabled():
-        return
-    global _DIRTY_AT
-    if not _DIRTY_AT:                         # remember the *first* write of the burst
-        _DIRTY_AT = time.time() if now is None else now
-    WAKE.set()
-
-
-def dirty_since() -> float:
-    """Timestamp of the oldest pending write (0.0 if nothing is pending)."""
-    return _DIRTY_AT
-
-
-def consume_dirty() -> bool:
-    """Atomically clear + report the pending-write flag. True == a write was pending."""
-    global _DIRTY_AT
-    if _DIRTY_AT:
-        _DIRTY_AT = 0.0
-        return True
-    return False
-
-
 def _record(summary: dict, *, now: Optional[float] = None) -> None:
     """Stamp last_run + a compact last_result onto the persisted policy (best-effort)."""
     now = time.time() if now is None else now
@@ -193,7 +137,6 @@ def _record(summary: dict, *, now: Optional[float] = None) -> None:
                 "last_run": float(now),
                 "last_result": {
                     "at": float(now),
-                    "trigger": summary.get("trigger", "manual"),
                     "workspaces": int(summary.get("workspaces", 0) or 0),
                     "exported": int(summary.get("exported", 0) or 0),
                     "added": int(summary.get("added", 0) or 0),
@@ -204,12 +147,11 @@ def _record(summary: dict, *, now: Optional[float] = None) -> None:
         pass
 
 
-def run_once(service: Any = None, *, trigger: str = "auto", now: Optional[float] = None,
+def run_once(service: Any = None, *, now: Optional[float] = None,
              record: bool = True) -> dict:
     """Run one auto-sync pass across every workspace — if this device is licensed for sync
     and has a key configured. Never raises: a relay/transport failure lands in the
-    summary's ``errors`` so the background loop keeps ticking. ``trigger`` (``"cadence"`` /
-    ``"update"`` / ``"auto"``) is recorded for telemetry. Records last_run/last_result
+    summary's ``errors`` so the background loop keeps ticking. Records last_run/last_result
     unless ``record`` is False. Returns the sync summary, or a ``{"skipped": ...}`` note
     when the plan/key isn't ready (so the loop no-ops cheaply instead of hammering the
     relay)."""
@@ -221,7 +163,6 @@ def run_once(service: Any = None, *, trigger: str = "auto", now: Optional[float]
     from engraphis.routes import v2_api
     svc = service if service is not None else v2_api.service()
     summary = v2_api._sync_all(svc)
-    summary["trigger"] = trigger
     try:                    # keep the dashboard's "last synced" line honest for auto runs
         v2_api._SYNC_STATE["last"] = summary
     except Exception:  # noqa: BLE001

{engraphis-0.5.2 → engraphis-0.7.0}/engraphis/dashboard_app.py

@@ -30,7 +30,8 @@ _INDEX = _STATIC / "index.html"
 # the auth bootstrap endpoints themselves (state/login/setup must work while logged
 # out) — same shape as engraphis/inspector/app.py's _PUBLIC set.
 _PUBLIC = {"/", "/api/health", "/api/ready", "/api/auth/state", "/api/auth/login",
-           "/api/auth/setup", "/api/auth/logout", "/webhooks/polar"}
+           "/api/auth/setup", "/api/auth/logout", "/api/auth/forgot", "/api/auth/reset",
+           "/webhooks/polar"}
 
 
 def create_app() -> FastAPI:

{engraphis-0.5.2 → engraphis-0.7.0}/engraphis/inspector/auth.py

@@ -32,6 +32,9 @@ SESSION_TTL_SECONDS = 12 * 3600
 LOCKOUT_FAILS = 5           # failures within LOCKOUT_WINDOW …
 LOCKOUT_WINDOW = 900        # … lock the account for LOCKOUT_SECONDS
 LOCKOUT_SECONDS = 60
+RESET_TOKEN_TTL_SECONDS = 1800   # a "forgot password" link is single-use, 30 min
+RESET_REQUEST_MAX = 3            # … and throttled per-email so it can't mail-bomb
+RESET_REQUEST_WINDOW = 3600      # an inbox (independent of the login lockout above)
 
 ROLES = ("viewer", "member", "admin")
 _ROLE_RANK = {r: i for i, r in enumerate(ROLES)}
@@ -55,6 +58,14 @@ CREATE TABLE IF NOT EXISTS auth_sessions (
     expires_at REAL NOT NULL
 );
 CREATE INDEX IF NOT EXISTS idx_sess_user ON auth_sessions(user_id);
+CREATE TABLE IF NOT EXISTS password_resets (
+    token_hash TEXT PRIMARY KEY,
+    user_id    TEXT NOT NULL REFERENCES users(id),
+    created_at REAL NOT NULL,
+    expires_at REAL NOT NULL,
+    used       INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_reset_user ON password_resets(user_id);
 CREATE TABLE IF NOT EXISTS audit_events (
     id          INTEGER PRIMARY KEY AUTOINCREMENT,
     ts          REAL NOT NULL,
@@ -140,6 +151,7 @@ class AuthStore:
         self.conn.executescript(_SCHEMA)
         self.iterations = int(iterations)
         self._failures: dict = {}   # email -> list[fail_ts] (in-memory throttle)
+        self._reset_requests: dict = {}   # email -> list[req_ts] (forgot-password throttle)
         self._last_prune: float = 0.0
 
     # ── users ──────────────────────────────────────────────────────────────────
@@ -299,6 +311,79 @@ class AuthStore:
         user["token"] = token
         return user
 
+    # ── password reset ("forgot password") ─────────────────────────────────────
+    def request_password_reset(self, email: str) -> Optional[dict]:
+        """Issue a single-use password-reset token for *email*, or return ``None``.
+
+        Returns ``None`` both when the address doesn't match an (enabled) account
+        AND when the per-email throttle is exceeded — callers MUST treat every
+        ``None`` identically (always respond as if the email might have been sent)
+        so a client can't enumerate registered users, or fingerprint the throttle,
+        by watching for a different HTTP response. Raises :class:`AuthError` only
+        for a malformed email string (also caller-swallowable for the same reason).
+
+        Any previously issued, still-unused token for this user is invalidated —
+        only the most recent reset link works, so an old email lying around in an
+        inbox can't be replayed after a newer one was requested.
+        """
+        email = self._clean_email(email)
+        now = time.time()
+        hits = [t for t in self._reset_requests.get(email, []) if now - t < RESET_REQUEST_WINDOW]
+        throttled = len(hits) >= RESET_REQUEST_MAX
+        hits.append(now)
+        self._reset_requests[email] = hits
+        if throttled:
+            self.record_event("password_reset.throttled", actor_email=email)
+            return None
+        row = self.conn.execute(
+            "SELECT id, email, name, disabled FROM users WHERE email=?", (email,)).fetchone()
+        if row is None or row["disabled"]:
+            return None
+        self.conn.execute("DELETE FROM password_resets WHERE user_id=? AND used=0", (row["id"],))
+        token = secrets.token_urlsafe(32)
+        self.conn.execute(
+            "INSERT INTO password_resets (token_hash, user_id, created_at, expires_at, used) "
+            "VALUES (?,?,?,?,0)",
+            (_hash_token(token), row["id"], now, now + RESET_TOKEN_TTL_SECONDS))
+        self.conn.commit()
+        self.record_event("password_reset.requested", actor_id=row["id"], actor_email=email)
+        return {"token": token, "email": row["email"], "name": row["name"]}
+
+    def reset_password(self, token: str, new_password: str) -> dict:
+        """Consume a password-reset token and set *new_password*.
+
+        Raises :class:`AuthError` on an invalid, expired, or already-used token, or
+        when the password fails :func:`_validate_password`. On success: every
+        existing session for the user is revoked (a token that leaked alongside a
+        stolen session, or a session left open on a shared machine, must not
+        survive the reset), the login lockout is cleared, and a fresh session is
+        created — same shape as :meth:`login`'s return (``user["token"]``) — so the
+        caller can sign the user straight back in.
+        """
+        _validate_password(new_password)
+        row = self.conn.execute(
+            "SELECT user_id, expires_at, used FROM password_resets WHERE token_hash=?",
+            (_hash_token(token),)).fetchone()
+        if row is None or row["used"] or row["expires_at"] < time.time():
+            raise AuthError("invalid or expired reset link")
+        user = self.get_user(row["user_id"])
+        if user is None or user["disabled"]:
+            raise AuthError("invalid or expired reset link")
+        self.conn.execute(
+            "UPDATE users SET pw_hash=? WHERE id=?",
+            (_hash_password(new_password, iterations=self.iterations), user["id"]))
+        self.conn.execute("UPDATE password_resets SET used=1 WHERE token_hash=?",
+                          (_hash_token(token),))
+        self.conn.commit()
+        self.revoke_user_sessions(user["id"])
+        self._failures.pop(user["email"], None)
+        self.record_event("password_reset.completed", actor_id=user["id"],
+                          actor_email=user["email"])
+        new_token = self.create_session(user["id"])
+        result = self.get_user(user["id"])
+        result["token"] = new_token
+        return result
+
     # ── sessions (raw token to the client, hash in the DB) ─────────────────────
     def create_session(self, user_id: str, *, ttl: int = SESSION_TTL_SECONDS) -> str:
         token = secrets.token_urlsafe(32)

{engraphis-0.5.2 → engraphis-0.7.0}/engraphis/inspector/webhooks.py

@@ -409,6 +409,37 @@ and will share it with you separately — this email does not contain it.
 """
 
 
+def _password_reset_email_text(name: str, reset_url: str) -> str:
+    greeting = "Hi %s," % name if name else "Hi,"
+    return f"""{greeting}
+
+Someone requested a password reset for your Engraphis dashboard account. If this
+was you, choose a new password here — this link works once and expires in 30
+minutes:
+
+    {reset_url}
+
+If you didn't request this, you can safely ignore this email: your password has
+not been changed.
+
+— The Engraphis team
+"""
+
+
+def send_password_reset_email(to: str, name: str, reset_url: str) -> None:
+    """Deliver a one-time password-reset link to *to* (``/api/auth/forgot``).
+
+    Raises on delivery failure (see :func:`_send_text_email`); the caller
+    (``routes.v2_team.forgot``) treats this as best-effort and must never let a
+    delivery failure change the HTTP response — the "forgot password" endpoint
+    always answers identically regardless of outcome, so a failed send can't be
+    used to fingerprint which addresses have accounts.
+    """
+    subject = "Reset your Engraphis dashboard password"
+    text_body = _password_reset_email_text(name, reset_url)
+    _send_text_email(to, subject, text_body)
+
+
 def send_team_invite_email(to: str, name: str, role: str) -> None:
     """Notify a newly added dashboard team member (``/api/auth/users``) that
     their account exists.

{engraphis-0.5.2 → engraphis-0.7.0}/engraphis/routes/v2_api.py

@@ -196,6 +196,19 @@ def workspaces_describe(req: _DescribeWsReq):
     return _run(service().set_workspace_description, req.workspace, req.description)
 
 
+class _CopyWsReq(BaseModel):
+    workspace: str
+    new_name: Optional[str] = None
+
+
+@router.post("/workspaces/copy")
+def workspaces_copy(req: _CopyWsReq):
+    """Duplicate ``workspace`` into a new one (see MemoryService.copy_workspace). When
+    ``new_name`` is omitted the name is auto-generated so the dashboard's Copy button
+    is a single click."""
+    return _run(service().copy_workspace, req.workspace, req.new_name)
+
+
 class _DeleteWsReq(BaseModel):
     workspace: str
 
@@ -773,23 +786,27 @@ def sync_run():
 
 
 class _AutoSyncReq(BaseModel):
-    enabled: Optional[bool] = None
+    enabled: Optional[bool] = None            # cadence (timer) sync
     cadence_minutes: Optional[int] = None
 
 
 @router.get("/sync/auto")
 def sync_auto_get():
-    """The background auto-sync policy for the dashboard toggle (enabled + cadence + last
-    run). Ungated read — it only ever reports a local preference, and defaults to off."""
+    """The background auto-sync policy for the dashboard toggle (cadence + last run).
+    License-ungated read (it only reports a local preference and defaults to off); in team
+    mode the dashboard's role gate still limits it to signed-in users, and only admins can
+    POST changes (the toggle renders read-only for members/viewers)."""
     from engraphis import autosync
     return autosync.load_policy()
 
 
 @router.post("/sync/auto")
 def sync_auto_set(req: _AutoSyncReq):
-    """Enable/disable background auto-sync and set its cadence (minutes). Pro/Team — the
-    same ``sync`` feature the button needs. The loop itself is licensed-gated too, so a
-    stale toggle can never reach the relay after a plan lapses."""
+    """Enable/disable background cadence auto-sync and set its interval (minutes, floored at
+    5). Pro/Team — the same ``sync`` feature the button needs. In team mode this route is
+    **admin-only** (``inspector/auth.min_role``): auto-sync is an account-wide control.
+    The loop itself is licensed-gated too, so a stale toggle can never reach the relay
+    after a plan lapses."""
     _paid("sync")
     from engraphis import autosync
     cur = autosync.load_policy()

{engraphis-0.5.2 → engraphis-0.7.0}/engraphis/routes/v2_team.py

@@ -46,6 +46,15 @@ class LoginReq(BaseModel):
     password: str = Field(..., min_length=1, max_length=128)
 
 
+class ForgotReq(BaseModel):
+    email: str = Field(..., min_length=1, max_length=254)
+
+
+class ResetReq(BaseModel):
+    token: str = Field(..., min_length=10, max_length=256)
+    password: str = Field(..., min_length=10, max_length=128)
+
+
 class NewUserReq(BaseModel):
     email: str = Field(..., min_length=5, max_length=254)
     name: str = Field(default="", max_length=120)
@@ -143,6 +152,44 @@ def attach(app: FastAPI, service):
         _set_cookie(response, u.pop("token"), secure=request.url.scheme == "https")
         return {"user": u}
 
+    @router.post("/forgot")
+    def forgot(body: ForgotReq, request: Request):
+        """Request a password-reset link. Always answers ``{"ok": true}`` — the
+        response is identical whether or not the email matches an account, the
+        account is disabled, or the per-email throttle kicked in, so a client
+        can't enumerate registered users by watching for a different reply.
+
+        If (and only if) a matching, enabled account exists and the throttle
+        allows it, a single-use reset link is emailed. Delivery is best-effort:
+        a failure is logged server-side and never surfaced to the caller, for the
+        same anti-enumeration reason (see send_password_reset_email's docstring).
+        """
+        try:
+            info = store.request_password_reset(body.email)
+        except AuthError:
+            info = None
+        if info:
+            base = os.environ.get("ENGRAPHIS_DASHBOARD_URL", "").strip().rstrip("/")
+            reset_url = base + "/?reset_token=" + info["token"]
+            try:
+                from engraphis.inspector.webhooks import send_password_reset_email
+                send_password_reset_email(info["email"], info["name"], reset_url)
+            except Exception as exc:  # noqa: BLE001 — must never change the response
+                logger.warning("password reset email to %s failed: %s", info["email"], exc)
+        return {"ok": True}
+
+    @router.post("/reset")
+    def reset(body: ResetReq, request: Request, response: Response):
+        """Consume a password-reset token issued by ``/forgot`` and sign the user
+        back in with a fresh session (old sessions are revoked — see
+        AuthStore.reset_password)."""
+        try:
+            u = store.reset_password(body.token, body.password)
+        except AuthError as exc:
+            raise HTTPException(status_code=400, detail={"error": str(exc)})
+        _set_cookie(response, u.pop("token"), secure=request.url.scheme == "https")
+        return {"user": u}
+
     @router.post("/logout")
     def logout(request: Request, response: Response):
         tok = request.cookies.get(_COOKIE)