memorymaster 3.18.0__tar.gz → 3.21.0__tar.gz

{memorymaster-3.18.0/memorymaster.egg-info → memorymaster-3.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymaster
-Version: 3.18.0
+Version: 3.21.0
 Summary: Production-grade memory reliability system for AI coding agents. Lifecycle-managed claims with citations, conflict detection, steward governance, and MCP integration.
 Author: wolverin0
 License: MIT
@@ -52,7 +52,7 @@ Lifecycle-managed claims with citations, conflict detection, steward governance,
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-1953-green.svg)]()
+[![Tests](https://img.shields.io/badge/tests-2194-green.svg)]()
 [![MCP Tools](https://img.shields.io/badge/MCP%20tools-24-purple.svg)]()
 [![CLI Commands](https://img.shields.io/badge/CLI%20commands-86-orange.svg)]()
 [![PyPI](https://img.shields.io/pypi/v/memorymaster.svg)](https://pypi.org/project/memorymaster/)
@@ -87,6 +87,9 @@ recent PR status, and sensitivity-filter invariants.
 - **Hybrid retrieval**: vector (sentence-transformers / Gemini) + FTS5 + freshness + confidence
 - **Context optimizer**: `query_for_context(budget=4000)` returns auto-curated memory that fits your token budget
 - **Entity graph** with typed relationships and alias resolution
+- **Rule-shaped claims** (new in v3.21.0): prescriptive `when <trigger>, do <action> because <rationale>` claims (`ingest_rule` / `query_rules`) — the shape an agent needs to actually change behaviour next time, not just recall a fact
+- **Correction mining** (new in v3.21.0): `mine-rules` scans the verbatim transcript archive for user corrections and distills them into rule claims; the Stop hook also mines each session's latest correction automatically
+- **Versioned schema migrations** (new in v3.20.0): `migrate` applies SQLite/Postgres migrations with sha256 drift detection; incremental `export-delta` ships small claim deltas for cheap cross-machine sync
 - **Steward governance**: multi-probe validators (filesystem, format, citation, semantic, tool) with proposal review
 - **Conflict resolution**: 5-tier auto (confidence > freshness > citations > LLM > manual)
 - **Auto-redaction** at ingest: JWT, GitHub tokens, Bearer, AWS keys, SSH keys, custom patterns
@@ -187,7 +190,7 @@ For zero-cost offline use, install [Ollama](https://ollama.com), `ollama pull ll
 }
 ```
 
-22 MCP tools: `init_db`, `ingest_claim`, `run_cycle`, `run_steward`, `classify_query`, `query_memory`, `query_for_context`, `list_claims`, `redact_claim_payload`, `pin_claim`, `compact_memory`, `list_events`, `search_verbatim`, `open_dashboard`, `list_steward_proposals`, `resolve_steward_proposal`, `extract_entities`, `entity_stats`, `find_related_claims`, `quality_scores`, `recompute_tiers`, `federated_query`.
+24 MCP tools: `init_db`, `ingest_claim`, `ingest_rule`, `query_rules`, `run_cycle`, `run_steward`, `classify_query`, `query_memory`, `query_for_context`, `list_claims`, `redact_claim_payload`, `pin_claim`, `compact_memory`, `list_events`, `search_verbatim`, `open_dashboard`, `list_steward_proposals`, `resolve_steward_proposal`, `extract_entities`, `entity_stats`, `find_related_claims`, `quality_scores`, `recompute_tiers`, `federated_query`.
 
 See [`.mcp.json.example`](.mcp.json.example) for the full template.
 

{memorymaster-3.18.0 → memorymaster-3.21.0}/README.md

@@ -6,7 +6,7 @@ Lifecycle-managed claims with citations, conflict detection, steward governance,
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-1953-green.svg)]()
+[![Tests](https://img.shields.io/badge/tests-2194-green.svg)]()
 [![MCP Tools](https://img.shields.io/badge/MCP%20tools-24-purple.svg)]()
 [![CLI Commands](https://img.shields.io/badge/CLI%20commands-86-orange.svg)]()
 [![PyPI](https://img.shields.io/pypi/v/memorymaster.svg)](https://pypi.org/project/memorymaster/)
@@ -41,6 +41,9 @@ recent PR status, and sensitivity-filter invariants.
 - **Hybrid retrieval**: vector (sentence-transformers / Gemini) + FTS5 + freshness + confidence
 - **Context optimizer**: `query_for_context(budget=4000)` returns auto-curated memory that fits your token budget
 - **Entity graph** with typed relationships and alias resolution
+- **Rule-shaped claims** (new in v3.21.0): prescriptive `when <trigger>, do <action> because <rationale>` claims (`ingest_rule` / `query_rules`) — the shape an agent needs to actually change behaviour next time, not just recall a fact
+- **Correction mining** (new in v3.21.0): `mine-rules` scans the verbatim transcript archive for user corrections and distills them into rule claims; the Stop hook also mines each session's latest correction automatically
+- **Versioned schema migrations** (new in v3.20.0): `migrate` applies SQLite/Postgres migrations with sha256 drift detection; incremental `export-delta` ships small claim deltas for cheap cross-machine sync
 - **Steward governance**: multi-probe validators (filesystem, format, citation, semantic, tool) with proposal review
 - **Conflict resolution**: 5-tier auto (confidence > freshness > citations > LLM > manual)
 - **Auto-redaction** at ingest: JWT, GitHub tokens, Bearer, AWS keys, SSH keys, custom patterns
@@ -141,7 +144,7 @@ For zero-cost offline use, install [Ollama](https://ollama.com), `ollama pull ll
 }
 ```
 
-22 MCP tools: `init_db`, `ingest_claim`, `run_cycle`, `run_steward`, `classify_query`, `query_memory`, `query_for_context`, `list_claims`, `redact_claim_payload`, `pin_claim`, `compact_memory`, `list_events`, `search_verbatim`, `open_dashboard`, `list_steward_proposals`, `resolve_steward_proposal`, `extract_entities`, `entity_stats`, `find_related_claims`, `quality_scores`, `recompute_tiers`, `federated_query`.
+24 MCP tools: `init_db`, `ingest_claim`, `ingest_rule`, `query_rules`, `run_cycle`, `run_steward`, `classify_query`, `query_memory`, `query_for_context`, `list_claims`, `redact_claim_payload`, `pin_claim`, `compact_memory`, `list_events`, `search_verbatim`, `open_dashboard`, `list_steward_proposals`, `resolve_steward_proposal`, `extract_entities`, `entity_stats`, `find_related_claims`, `quality_scores`, `recompute_tiers`, `federated_query`.
 
 See [`.mcp.json.example`](.mcp.json.example) for the full template.
 

{memorymaster-3.18.0 → memorymaster-3.21.0}/memorymaster/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "3.4.1"
+__version__ = "3.21.0"

{memorymaster-3.18.0 → memorymaster-3.21.0}/memorymaster/cli.py

@@ -23,7 +23,9 @@ from memorymaster.cli_handlers_curation import COMMAND_HANDLERS
 from memorymaster.cli_handlers_basic import (
     _handle_decay,
     _handle_entity_graph_export,
+    _handle_export_delta,
     _handle_ingest_daydream,
+    _handle_migrate,
     _handle_recompute_confidence_priors,
     _handle_wiki_suggest_links,
     handle_mcp_usage_report,
@@ -38,6 +40,8 @@ COMMAND_HANDLERS["ingest-daydream"] = _handle_ingest_daydream
 COMMAND_HANDLERS["mcp-usage-report"] = (
     lambda args, service, parser, effective_db: handle_mcp_usage_report(args, effective_db)
 )
+COMMAND_HANDLERS["migrate"] = _handle_migrate
+COMMAND_HANDLERS["export-delta"] = _handle_export_delta
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -51,6 +55,11 @@ def build_parser() -> argparse.ArgumentParser:
 
     sub.add_parser("init-db", help="Create schema in SQLite database")
 
+    migrate = sub.add_parser("migrate", help="Apply pending versioned schema migrations (v3.20.0+)")
+    migrate_mode = migrate.add_mutually_exclusive_group()
+    migrate_mode.add_argument("--list", action="store_true", help="List known migrations without touching the DB")
+    migrate_mode.add_argument("--status", action="store_true", help="Report applied vs pending per migration")
+
     sub.add_parser("stealth-status", help="Show whether stealth mode is active and which DB is in use")
 
     ingest = sub.add_parser("ingest", help="Ingest a raw claim with citations")
@@ -447,6 +456,13 @@ def build_parser() -> argparse.ArgumentParser:
     mine_cmd.add_argument("--scope", default="project", help="Scope for ingested claims")
     mine_cmd.add_argument("--max", type=int, default=100, help="Max claims to ingest")
 
+    mine_rules_cmd = sub.add_parser("mine-rules", help="Mine verbatim corrections into rule-shaped claims (v3.21.0-R1b)")
+    mine_rules_cmd.add_argument("--since-id", dest="since_id", type=int, default=None, help="Override the stored watermark; start scanning after this verbatim id")
+    mine_rules_cmd.add_argument("--limit", type=int, default=None, help="Max candidate windows to examine this run (caps LLM calls)")
+    mine_rules_cmd.add_argument("--batch-size", dest="batch_size", type=int, default=200, help="Rows fetched per SQL pre-filter page (default: 200)")
+    mine_rules_cmd.add_argument("--provider", default="claude_cli", help="LLM provider for this run (default: claude_cli)")
+    mine_rules_cmd.add_argument("--reset", action="store_true", help="Clear the stored watermark before running (re-scan from the start)")
+
     verify_cmd = sub.add_parser("verify-claims", help="Cross-check claims against current codebase")
     verify_cmd.add_argument("--scope", default="", help="Scope filter")
     verify_cmd.add_argument("--limit", type=int, default=200, help="Max claims to check")
@@ -504,6 +520,13 @@ def build_parser() -> argparse.ArgumentParser:
     merge_cmd = sub.add_parser("merge-db", help="Merge claims from a remote memorymaster DB (bidirectional sync)")
     merge_cmd.add_argument("--source", required=True, help="Path to source DB file to merge from")
 
+    delta_cmd = sub.add_parser(
+        "export-delta",
+        help="Export claims changed since a watermark into a small SQLite delta file (incremental sync)",
+    )
+    delta_cmd.add_argument("--since", default="", help="ISO-8601 watermark; export claims with updated_at after this (empty = full export)")
+    delta_cmd.add_argument("--output", required=True, help="Path to write the delta SQLite file (overwritten if it exists)")
+
     daily = sub.add_parser("daily-note", help="Generate a daily note summarizing today's activity")
     daily.add_argument("--date", default="", help="Date to generate for (YYYY-MM-DD, default: today)")
     daily.add_argument("--output", default="", help="Directory to save .md file (default: print to stdout)")
@@ -556,7 +579,7 @@ def main(argv: list[str] | None = None) -> int:
     effective_db = _resolve_db_path(args)
 
     # Commands that don't need MemoryService run first; service is lazy-created once for all others.
-    _NO_SERVICE_COMMANDS = {"stealth-status", "export-metrics", "wiki-freshness", "mcp-usage-report"}
+    _NO_SERVICE_COMMANDS = {"stealth-status", "export-metrics", "wiki-freshness", "mcp-usage-report", "export-delta"}
 
     try:
         handler = COMMAND_HANDLERS.get(args.command)

{memorymaster-3.18.0 → memorymaster-3.21.0}/memorymaster/cli_handlers_basic.py

@@ -1357,3 +1357,95 @@ def _handle_check_staleness(args: argparse.Namespace, service, parser: argparse.
     return 0
 
 
+def _handle_migrate(args: argparse.Namespace, service, parser: argparse.ArgumentParser, effective_db: str) -> int:
+    """v3.20.0-S1: apply pending schema migrations, or report status.
+
+    Default (no flags): apply every pending migration in version order.
+    --list: dump known migrations (version + description) without touching the DB.
+    --status: query the DB and show applied vs pending per migration.
+    """
+    from memorymaster.migrations import (
+        MigrationRunner,
+        discover_migrations,
+    )
+    from memorymaster.store_factory import is_postgres_dsn
+
+    # --list works without a DB connection at all.
+    if getattr(args, "list", False):
+        migrations = discover_migrations()
+        if args.json_output:
+            payload = [{"version": m.version, "description": m.description} for m in migrations]
+            print(_json_envelope(payload))
+        else:
+            print(f"known migrations ({len(migrations)}):")
+            for m in migrations:
+                print(f"  v{m.version:04d}  {m.description}")
+        return 0
+
+    backend = "postgres" if is_postgres_dsn(effective_db) else "sqlite"
+    store = service.store
+    with store.connect() as conn:
+        runner = MigrationRunner(conn, backend=backend)
+
+        if getattr(args, "status", False):
+            entries = runner.status()
+            if args.json_output:
+                payload = [
+                    {
+                        "version": e.version,
+                        "description": e.description,
+                        "applied": e.applied,
+                        "applied_at": e.applied_at,
+                    }
+                    for e in entries
+                ]
+                print(_json_envelope(payload))
+            else:
+                print(f"backend={backend} db={effective_db}")
+                for e in entries:
+                    marker = "[applied]" if e.applied else "[pending]"
+                    when = f" applied_at={e.applied_at}" if e.applied_at else ""
+                    print(f"  v{e.version:04d}  {marker} {e.description}{when}")
+            return 0
+
+        # Default: apply pending
+        newly = runner.apply_pending()
+        if args.json_output:
+            print(_json_envelope({"applied": newly, "backend": backend}))
+        else:
+            if not newly:
+                print(f"migrate: nothing to apply (backend={backend}, db={effective_db})")
+            else:
+                print(f"migrate: applied {len(newly)} migration(s) on backend={backend}:")
+                for v in newly:
+                    print(f"  v{v:04d}")
+    return 0
+
+
+def _handle_export_delta(args: argparse.Namespace, service, parser: argparse.ArgumentParser, effective_db: str) -> int:
+    """Export claims changed since a watermark into a small SQLite delta file.
+
+    The delta file is a valid `merge-db --source` input. Prints (or JSON-emits)
+    the export counts and the new watermark — callers should record
+    `max_updated_at` and pass it as `--since` on the next run.
+    """
+    from memorymaster.delta_sync import export_delta
+
+    t0 = time.perf_counter()
+    result = export_delta(effective_db, args.since, args.output)
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+    if args.json_output:
+        print(_json_envelope(result, query_ms=elapsed_ms))
+    else:
+        since_label = result["since"] or "(full export)"
+        print(
+            f"export-delta: {result['exported']} claims + {result['citations']} citations "
+            f"since {since_label} -> {args.output}"
+        )
+        if result["max_updated_at"]:
+            print(f"  next watermark (--since): {result['max_updated_at']}")
+        else:
+            print("  delta is empty — nothing changed since the watermark")
+    return 0
+
+

{memorymaster-3.18.0 → memorymaster-3.21.0}/memorymaster/cli_handlers_curation.py

@@ -343,6 +343,31 @@ def _handle_mine_transcript(args: argparse.Namespace, service, parser: argparse.
     return 0
 
 
+def _handle_mine_rules(args: argparse.Namespace, service, parser: argparse.ArgumentParser, effective_db: str) -> int:
+    from memorymaster.rule_miner import mine_rules
+    t0 = time.perf_counter()
+    result = mine_rules(
+        effective_db,
+        service,
+        since_id=getattr(args, "since_id", None),
+        limit=getattr(args, "limit", None),
+        batch_size=getattr(args, "batch_size", 200),
+        provider=getattr(args, "provider", "claude_cli"),
+        reset=getattr(args, "reset", False),
+    )
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+    if args.json_output:
+        print(_json_envelope(result, query_ms=elapsed_ms))
+    else:
+        abort = f", ABORTED ({result['aborted_reason']})" if result.get("aborted_reason") else ""
+        print(
+            f"Mined rules: {result['candidates']} candidates, {result['llm_calls']} llm calls, "
+            f"{result['ingested']} ingested, {result['duplicates']} dupes, {result['skipped']} skipped "
+            f"(watermark={result['last_id']}{abort}, {elapsed_ms:.0f}ms)"
+        )
+    return 0
+
+
 def _handle_wiki_breakdown(args: argparse.Namespace, service, parser: argparse.ArgumentParser, effective_db: str) -> int:
     from memorymaster.wiki_engine import breakdown
     t0 = time.perf_counter()
@@ -703,6 +728,7 @@ COMMAND_HANDLERS: dict[str, object] = {
     "wiki-freshness": _handle_wiki_freshness,
     "bases-generate": _handle_bases_generate,
     "mine-transcript": _handle_mine_transcript,
+    "mine-rules": _handle_mine_rules,
     "verify-claims": _handle_verify_claims,
     "extract-entities": _handle_extract_entities,
     "entity-stats": _handle_entity_stats,

{memorymaster-3.18.0 → memorymaster-3.21.0}/memorymaster/config_templates/hooks/memorymaster-auto-ingest.py

@@ -180,6 +180,27 @@ Only: bug root causes, decisions, gotchas, constraints. Never: credentials, IPs,
         pass
 
 
+def _run_rule_extraction(transcript_path, cwd):
+    """R1b ongoing: mine the latest correction in this session into a rule claim.
+
+    Reuses memorymaster.rule_miner.mine_transcript_rules (single source of truth
+    for the correction->rule prompt + ingest path). Bounded to one window per
+    stop to keep the hook fast; rules land as low-confidence candidates."""
+    try:
+        if not transcript_path or not os.path.exists(transcript_path) or not os.path.exists(DB_PATH):
+            return
+        from memorymaster.rule_miner import mine_transcript_rules
+        from memorymaster.service import MemoryService
+
+        scope = "project:" + os.path.basename(cwd).lower().replace(" ", "-") if cwd else "global"
+        svc = MemoryService(DB_PATH, workspace_root=Path(cwd or PROJECT_ROOT))
+        stats = mine_transcript_rules(transcript_path, svc, scope=scope, max_windows=1)
+        if stats.get("ingested"):
+            sys.stderr.write(f"[MemoryMaster] mined {stats['ingested']} rule(s) from corrections\n")
+    except Exception:
+        pass
+
+
 def main():
     try:
         data = json.loads(sys.stdin.read() or "{}")
@@ -232,6 +253,9 @@ def main():
     # Not time to block — run passive Gemini extraction
     _run_gemini_extraction(transcript_path, cwd)
 
+    # R1b: mine the latest correction in this session into a rule claim
+    _run_rule_extraction(transcript_path, cwd)
+
     sys.stdout.write(json.dumps({"decision": "approve"}))
 
 

{memorymaster-3.18.0 → memorymaster-3.21.0}/memorymaster/dashboard.py

@@ -19,6 +19,7 @@ import urllib.error
 import urllib.request
 from urllib.parse import parse_qs, urlparse
 
+from memorymaster import dashboard_auth
 from memorymaster.config import get_config
 from memorymaster.review import build_review_queue, queue_to_dicts
 from memorymaster.security import is_sensitive_claim
@@ -626,6 +627,9 @@ class DashboardHTTPServer(ThreadingHTTPServer):
         self.db_target = str(db_target) if db_target is not None else "memorymaster.db"
         self.workspace_root = Path(workspace_root) if workspace_root is not None else Path.cwd()
         self._operator_proc: subprocess.Popen[str] | None = None
+        # Pin the configured host:port string so the CSRF check can compare it
+        # against the request's Origin/Referer header in authenticate POST routes.
+        self.configured_host_port = f"{server_address[0]}:{server_address[1]}"
         super().__init__(server_address, DashboardRequestHandler)
 
     def operator_status(self) -> dict[str, Any]:
@@ -701,10 +705,45 @@ class DashboardRequestHandler(BaseHTTPRequestHandler):
     def _server(self) -> DashboardHTTPServer:
         return self.server  # type: ignore[return-value]
 
+    def _enforce_auth(self, *, method: str, route: str) -> bool:
+        """Run the v3.19.0-H2 auth + role + CSRF gates. Returns True on pass.
+
+        On failure, the JSON error response has already been written; the
+        caller must return immediately without dispatching the route.
+        Health endpoints (/health, /healthz, /readyz) are intentionally
+        exempt so external monitors can probe without credentials.
+        """
+        if route in {"/health", "/healthz", "/readyz"}:
+            return True
+
+        decision = dashboard_auth.authenticate(self.headers)
+        decision = dashboard_auth.authorize(decision, method=method, route=route)
+        if not decision.ok:
+            self._write_json(
+                {"ok": False, "error": decision.reason},
+                status=decision.status,
+            )
+            return False
+
+        if method.upper() == "POST":
+            csrf = dashboard_auth.check_csrf(
+                self.headers,
+                configured_host_port=getattr(self._server, "configured_host_port", None),
+            )
+            if not csrf.ok:
+                self._write_json(
+                    {"ok": False, "error": csrf.reason},
+                    status=csrf.status,
+                )
+                return False
+        return True
+
     def do_GET(self) -> None:  # noqa: N802
         parsed = urlparse(self.path)
         route = parsed.path
         try:
+            if not self._enforce_auth(method="GET", route=route):
+                return
             if _route_get_request(self, route, parsed.query):
                 return
             self._write_json({"ok": False, "error": "Not found"}, status=HTTPStatus.NOT_FOUND)
@@ -717,6 +756,8 @@ class DashboardRequestHandler(BaseHTTPRequestHandler):
         parsed = urlparse(self.path)
         route = parsed.path
         try:
+            if not self._enforce_auth(method="POST", route=route):
+                return
             payload = self._read_json_body()
             if route == "/api/triage/action":
                 self._handle_triage_action(payload)
@@ -1443,6 +1484,12 @@ def create_dashboard_server(
     port: int = 8765,
     operator_log_jsonl: str | Path = "artifacts/operator/operator_events.jsonl",
 ) -> DashboardHTTPServer:
+    # v3.19.0-H2: refuse non-loopback bind without an auth secret unless the
+    # operator explicitly opts in. Raises dashboard_auth.BindUnsafeError on
+    # an unsafe configuration; callers should let it propagate so the
+    # mistake is visible at startup instead of silently exposed.
+    dashboard_auth.check_bind_safety(host)
+
     if service is None:
         if db_target is None:
             db_target = "memorymaster.db"

memorymaster-3.21.0/memorymaster/dashboard_auth.py

@@ -0,0 +1,196 @@
+"""HTTP-layer authentication, CSRF, and bind-safety for the dashboard (v3.19.0-H2).
+
+The dashboard's prior posture was "trusted local-only" — zero HTTP auth,
+default loopback bind. Anyone who could reach the port had full read +
+operator-control. This module adds opt-in token auth with viewer/operator
+role separation, CSRF for browser POSTs, and refusal to bind non-loopback
+hosts without an explicit secret.
+
+Backwards compatibility: when no auth secrets are configured (both
+``MEMORYMASTER_DASHBOARD_TOKEN_VIEWER`` and ``MEMORYMASTER_DASHBOARD_TOKEN_OPERATOR``
+are empty), the dashboard runs in legacy mode — no auth enforced. Bind
+safety still applies: legacy mode refuses non-loopback bind unless the
+operator explicitly opts in with ``MEMORYMASTER_DASHBOARD_UNSAFE_BIND=1``.
+
+Env vars:
+    MEMORYMASTER_DASHBOARD_TOKEN_VIEWER     — bearer token granting read-only access
+    MEMORYMASTER_DASHBOARD_TOKEN_OPERATOR   — bearer token granting full mutating access
+    MEMORYMASTER_DASHBOARD_UNSAFE_BIND      — set to 1 to allow non-loopback bind
+                                              without an auth secret (logs WARNING)
+"""
+from __future__ import annotations
+
+import hmac
+import logging
+import os
+from dataclasses import dataclass
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+
+class DashboardRole(str, Enum):
+    VIEWER = "viewer"
+    OPERATOR = "operator"
+
+
+# Routes that require operator role regardless of HTTP method. POST routes
+# always require operator role separately. This list captures GET routes that
+# are mutating-adjacent (start/stop operator control, stream that may carry
+# sensitive operator events).
+OPERATOR_ONLY_GET_ROUTES: frozenset[str] = frozenset({
+    "/api/operator/control",  # POST in practice but pin it here for completeness
+    "/api/operator/stream",   # SSE — operator-only since it streams operator events
+})
+
+# POST routes — all require operator.
+POST_OPERATOR_ROUTES: frozenset[str] = frozenset({
+    "/api/triage/action",
+    "/api/operator/control",
+    "/api/action-proposals/status",
+})
+
+
+@dataclass(frozen=True)
+class AuthDecision:
+    """Outcome of an authentication or authorization check."""
+
+    ok: bool
+    role: DashboardRole | None = None
+    reason: str = ""
+    status: int = 200
+
+
+class BindUnsafeError(RuntimeError):
+    """Raised when the dashboard refuses to bind a non-loopback host without auth."""
+
+
+def _env_token(name: str) -> str:
+    return os.environ.get(name, "").strip()
+
+
+def legacy_mode() -> bool:
+    """True when no auth secrets are configured (back-compat path).
+
+    Legacy mode preserves the pre-v3.19 behaviour for loopback bind — no
+    auth check, no CSRF. Bind safety still applies regardless.
+    """
+    return not (
+        _env_token("MEMORYMASTER_DASHBOARD_TOKEN_VIEWER")
+        or _env_token("MEMORYMASTER_DASHBOARD_TOKEN_OPERATOR")
+    )
+
+
+def _extract_bearer(headers) -> str:
+    raw = headers.get("Authorization", "") if headers else ""
+    if not raw or not raw.lower().startswith("bearer "):
+        return ""
+    return raw[7:].strip()
+
+
+def authenticate(headers) -> AuthDecision:
+    """Map an incoming request's Authorization header to a role.
+
+    Behaviour:
+    - Legacy mode (no tokens set): return ok with role=operator (no enforcement).
+    - Missing token: 401 (``missing_token``).
+    - Token matches operator: ok with role=operator.
+    - Token matches viewer: ok with role=viewer.
+    - Token unrecognized: 401 (``invalid_token``).
+
+    Constant-time comparison (``hmac.compare_digest``) prevents timing attacks.
+    """
+    if legacy_mode():
+        return AuthDecision(True, role=DashboardRole.OPERATOR)
+
+    token = _extract_bearer(headers)
+    if not token:
+        return AuthDecision(False, reason="missing_token", status=401)
+
+    op_token = _env_token("MEMORYMASTER_DASHBOARD_TOKEN_OPERATOR")
+    vw_token = _env_token("MEMORYMASTER_DASHBOARD_TOKEN_VIEWER")
+
+    if op_token and hmac.compare_digest(token, op_token):
+        return AuthDecision(True, role=DashboardRole.OPERATOR)
+    if vw_token and hmac.compare_digest(token, vw_token):
+        return AuthDecision(True, role=DashboardRole.VIEWER)
+    return AuthDecision(False, reason="invalid_token", status=401)
+
+
+def authorize(decision: AuthDecision, *, method: str, route: str) -> AuthDecision:
+    """Refine an authentication decision against the role-vs-route policy.
+
+    Returns 403 (``role_required_operator``) for routes where viewer is
+    insufficient. Passes ``decision`` through unchanged on success.
+    """
+    if not decision.ok:
+        return decision
+
+    method_u = method.upper()
+    operator_required = (
+        method_u == "POST"
+        or route in OPERATOR_ONLY_GET_ROUTES
+        or route in POST_OPERATOR_ROUTES
+    )
+    if operator_required and decision.role != DashboardRole.OPERATOR:
+        return AuthDecision(
+            False,
+            role=decision.role,
+            reason="role_required_operator",
+            status=403,
+        )
+    return decision
+
+
+def check_csrf(headers, *, configured_host_port: str | None) -> AuthDecision:
+    """Validate Origin/Referer for browser-originated POSTs.
+
+    Non-browser clients (curl, scripts, MCP-style integrations) typically
+    omit ``Origin`` — those requests pass through unchallenged. Browsers
+    always set ``Origin``; when present, it must contain the configured
+    host:port string. Returns 403 (``csrf_origin_mismatch``) on mismatch.
+
+    Legacy mode skips CSRF entirely.
+    """
+    if legacy_mode():
+        return AuthDecision(True)
+
+    origin = ""
+    if headers:
+        origin = headers.get("Origin", "") or headers.get("Referer", "") or ""
+    if not origin:
+        return AuthDecision(True)  # non-browser caller
+    if configured_host_port and configured_host_port not in origin:
+        return AuthDecision(False, reason="csrf_origin_mismatch", status=403)
+    return AuthDecision(True)
+
+
+def check_bind_safety(host: str) -> None:
+    """Refuse non-loopback bind without an auth secret or explicit opt-in.
+
+    Raises ``BindUnsafeError`` if all of: (a) host is non-loopback,
+    (b) no auth tokens configured, (c) ``MEMORYMASTER_DASHBOARD_UNSAFE_BIND``
+    not set. Otherwise returns silently. Logs a WARNING for the unsafe opt-in
+    case so operators see they're running exposed.
+    """
+    loopback_hosts = {"127.0.0.1", "::1", "localhost", ""}
+    if host in loopback_hosts:
+        return
+    if not legacy_mode():
+        return  # token-based auth is enforced; non-loopback bind is acceptable
+
+    unsafe_raw = os.environ.get("MEMORYMASTER_DASHBOARD_UNSAFE_BIND", "").strip().lower()
+    if unsafe_raw in {"1", "true", "yes", "on"}:
+        logger.warning(
+            "dashboard binding to non-loopback host '%s' with no auth secret "
+            "and MEMORYMASTER_DASHBOARD_UNSAFE_BIND=1 — running exposed",
+            host,
+        )
+        return
+
+    raise BindUnsafeError(
+        f"Refusing to bind dashboard to non-loopback host '{host}' without auth secret. "
+        f"Set MEMORYMASTER_DASHBOARD_TOKEN_OPERATOR (and optionally "
+        f"MEMORYMASTER_DASHBOARD_TOKEN_VIEWER), or explicitly opt-in with "
+        f"MEMORYMASTER_DASHBOARD_UNSAFE_BIND=1."
+    )