context-graph-spaces 0.1.0__py3-none-any.whl

context_graph_spaces/__init__.py

@@ -0,0 +1,13 @@
+"""Context Graph's Enterprise edition: personal and shared memory spaces for many users on one Memgraph.
+
+Selected by ``edition = "enterprise"`` in the Context Graph config file, which
+makes :class:`EnterpriseSpaces` the space resolver. The admin side provisions
+spaces from a spec (:mod:`.spec`, :mod:`.provision`, ``context-graph-spaces
+plan|apply``).
+"""
+
+from .provision import Applied, Plan, apply, observed_state, plan
+from .resolver import EnterpriseSpaces
+from .spec import Spec, SpecError, load_spec
+
+__all__ = ["Applied", "EnterpriseSpaces", "Plan", "Spec", "SpecError", "apply", "load_spec", "observed_state", "plan"]

context_graph_spaces/cli.py

@@ -0,0 +1,123 @@
+"""``context-graph-spaces``: the admin's commands for provisioning spaces from a spec.
+
+The admin connection comes from flags, falling back to ``MEMGRAPH_URL`` /
+``MEMGRAPH_USER`` / ``MEMGRAPH_PASSWORD``. This is an interactive admin tool,
+not a hook, so the config-file-only rule for hooks doesn't apply; the admin's
+login is never written anywhere.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import TYPE_CHECKING, Any, cast
+
+from .provision import SERVICE_ACCOUNT, Plan, Query, Step, apply, observed_state, plan
+from .spec import SpecError, load_spec
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from .spec import Spec
+
+#: Where the reconcile worker finds the service login's password.
+SERVICE_PASSWORD_ENV = "CG_SERVICE_PASSWORD"
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run ``plan`` or ``apply``; returns the process exit code."""
+    parser = argparse.ArgumentParser(prog="context-graph-spaces", description=__doc__)
+    parser.add_argument("--url", default=os.environ.get("MEMGRAPH_URL", "bolt://localhost:7687"))
+    parser.add_argument("--user", default=os.environ.get("MEMGRAPH_USER", ""), help="An admin login.")
+    parser.add_argument("--password", default=os.environ.get("MEMGRAPH_PASSWORD", ""))
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name, text in (("plan", "Show what apply would change."), ("apply", "Make Memgraph match the spec.")):
+        command = commands.add_parser(name, help=text)
+        command.add_argument("spec", help="The spaces spec (TOML).")
+        command.add_argument("--prune", action="store_true", help="Also drop removed users and databases.")
+    reconcile = commands.add_parser("reconcile", help="Reconcile shared spaces' changed memory files, as cg_service.")
+    reconcile.add_argument("spec", help="The spaces spec (TOML): which shared spaces to reconcile.")
+    reconcile.add_argument("--watch", action="store_true", help="Keep going, one pass every --interval seconds.")
+    reconcile.add_argument("--interval", type=float, default=30.0)
+    args = parser.parse_args(argv)
+
+    try:
+        spec = load_spec(args.spec)
+    except SpecError as exc:
+        print(exc, file=sys.stderr)
+        return 2
+    if args.command == "reconcile":
+        return _reconcile(spec, args.url, watch=args.watch, interval=args.interval)
+    query, close = admin_query(args.url, args.user, args.password)
+    try:
+        if args.command == "plan":
+            _print_plan(plan(spec, observed_state(query, spec.members), prune=args.prune))
+            return 0
+        applied = apply(spec, query, prune=args.prune)
+    finally:
+        close()
+    _print_steps(applied.steps, "Applied" if applied.steps else "Nothing to change; Memgraph matches the spec.")
+    _print_kept(applied.kept)
+    for login, password in sorted(applied.passwords.items()):
+        if login == SERVICE_ACCOUNT:
+            print(f"\nNew service login {login!r} for the shared-space reconcile worker; it isn't stored anywhere.")
+            print(f"  Give the worker: {SERVICE_PASSWORD_ENV}='{password}'")
+            continue
+        print(f"\nNew login {login!r}. Hand this to them once; it isn't stored anywhere:")
+        print(f"  memgraph-context-graph join {args.url} {login} --password='{password}'")
+    return 0
+
+
+def _reconcile(spec: Spec, url: str, *, watch: bool, interval: float) -> int:
+    """Run the worker once, or every *interval* seconds with *watch*; exit 1 if the last pass had an error."""
+    import time
+
+    from .worker import reconcile_spaces
+
+    password = os.environ.get(SERVICE_PASSWORD_ENV)
+    if not password:
+        print(f"Set {SERVICE_PASSWORD_ENV} to {SERVICE_ACCOUNT}'s password (apply printed it once).", file=sys.stderr)
+        return 2
+    while True:
+        reports = reconcile_spaces(spec, url=url, password=password)
+        for report in reports:
+            if report.error:
+                print(f"{report.space}: not reconciled: {report.error}", file=sys.stderr)
+                continue
+            failed = "".join(f"\n  failed {path}: {error}" for path, error in report.failed)
+            print(f"{report.space}: {len(report.completed)} reconciled, {report.pruned} leftovers removed{failed}")
+        if not watch:
+            return 1 if any(report.error or report.failed for report in reports) else 0
+        time.sleep(interval)
+
+
+def admin_query(url: str, user: str, password: str) -> tuple[Query, Any]:
+    """A :data:`~.provision.Query` over one admin driver, and the function that closes it."""
+    import neo4j
+
+    driver = neo4j.GraphDatabase.driver(url, auth=(user, password))
+
+    def query(statement: str, database: str | None, params: dict[str, Any] | None) -> list[dict[str, Any]]:
+        # Auth and multi-database DDL can't run in an explicit transaction, so each statement gets its own session.
+        with driver.session(database=database) as session:
+            # The driver's stubs want a LiteralString; admin DDL is built from names spec._NAME has validated.
+            return [record.data() for record in session.run(cast("Any", statement), params or {})]
+
+    return query, driver.close
+
+
+def _print_plan(the_plan: Plan) -> None:
+    _print_steps(the_plan.steps, "Plan:" if the_plan.steps else "Nothing to change; Memgraph matches the spec.")
+    _print_kept(the_plan.kept)
+
+
+def _print_steps(steps: list[Step], heading: str) -> None:
+    print(heading)
+    for step in steps:
+        print(f"  + {step.summary}")
+
+
+def _print_kept(kept: list[str]) -> None:
+    if kept:
+        print(f"Kept (pass --prune to drop): {', '.join(kept)}")

context_graph_spaces/provision.py

@@ -0,0 +1,421 @@
+"""Provisioning: make Memgraph's databases, users, roles and grants match a :class:`~.spec.Spec`.
+
+``plan`` reads Memgraph's current state and lists the changes; ``apply`` runs
+them. Both are idempotent: once Memgraph matches the spec, ``plan`` is empty.
+
+The shapes it maintains (map #501):
+
+- Each member ``<login>`` has a personal database ``u_<login>`` as their main
+  database, reached through a role that may do anything inside it.
+- Each shared space ``<name>`` is a database ``space_<name>``. Its members hold
+  a role, assigned on that database only, that may read everything there and
+  create or change only the spec's labels and edge types.
+- ``cg_service`` holds a worker role on every shared database; it writes what
+  members can't, such as Chunks and entities.
+- Each member's personal database holds ``(:SpaceMembership {space, database})``
+  nodes naming the shared spaces they belong to: an unprivileged login can't
+  list its own grants, and recall needs to know which spaces to read. Memgraph's
+  grants stay the authority; a stale node only costs a permission error.
+
+Roles are named after a hash of what they grant, so changing a space's labels
+creates a new role, moves members onto it (new grant before the old revoke, so
+access never lapses), and drops the old one. That keeps ``plan`` a structural
+diff: Memgraph can list label and property grants, but revoking them unevenly
+(a label wildcard revoke clears specific label rules, a property wildcard revoke
+doesn't) makes editing a role in place unsafe.
+
+Only objects with the provisioner's prefixes (``u_``, ``space_``, ``cg_``) are
+ever changed; an admin's other users, roles and databases are left alone.
+Removing a member or space revokes access but keeps its data: databases and
+users are dropped only with ``prune``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, cast
+
+if TYPE_CHECKING:
+    from .spec import SharedSpace, Spec
+
+SERVICE_ACCOUNT = "cg_service"
+#: The label of a member's catalog of their shared spaces, in their personal database.
+MEMBERSHIP_LABEL = "SpaceMembership"
+_OWNED_PREFIXES = ("u_", "space_", "cg_")
+_PRIVILEGES = "MATCH, CREATE, MERGE, SET, DELETE, REMOVE"
+_OWNER_PRIVILEGES = _PRIVILEGES + ", INDEX, STATS, CONSTRAINT"
+_EVERYTHING = (
+    "GRANT * ON NODES CONTAINING LABELS * TO ROLE {role}",
+    "GRANT * ON EDGES OF TYPE * TO ROLE {role}",
+    "GRANT READ, SET PROPERTY {{*}} ON NODES CONTAINING LABELS * TO ROLE {role}",
+    "GRANT READ, SET PROPERTY {{*}} ON EDGES OF TYPE * TO ROLE {role}",
+)
+
+
+def personal_database(login: str) -> str:
+    """The database holding *login*'s personal space."""
+    return f"u_{login}"
+
+
+def shared_database(space: str) -> str:
+    """The database holding shared space *space*."""
+    return f"space_{space}"
+
+
+def _owned(name: str) -> bool:
+    return name.startswith(_OWNED_PREFIXES)
+
+
+@dataclass(frozen=True)
+class Role:
+    """A role the provisioner owns: the databases it reaches and the grants it carries."""
+
+    prefix: str
+    databases: tuple[str, ...]
+    grants: tuple[str, ...]
+
+    @property
+    def name(self) -> str:
+        """``<prefix>_<hash of databases and grants>``: a different grant set is a different role."""
+        digest = hashlib.sha256("\n".join((*self.databases, *self.grants)).encode()).hexdigest()[:8]
+        return f"{self.prefix}_{digest}"
+
+    def statements(self) -> list[str]:
+        """Create the role and give it everything it carries."""
+        return [
+            f"CREATE ROLE {self.name}",
+            *(f"GRANT DATABASE {database} TO ROLE {self.name}" for database in self.databases),
+            *(grant.format(role=self.name) for grant in self.grants),
+        ]
+
+
+@dataclass(frozen=True)
+class Assignment:
+    """*user* holds *role* on *database*."""
+
+    user: str
+    role: str
+    database: str
+
+
+@dataclass
+class State:
+    """The provisioner's objects, as desired from a spec or as observed in Memgraph."""
+
+    databases: set[str] = field(default_factory=set)
+    users: set[str] = field(default_factory=set)
+    roles: dict[str, Role | None] = field(default_factory=dict)
+    assignments: set[Assignment] = field(default_factory=set)
+    #: profile name -> (memory limit in MB, databases it's attached to)
+    profiles: dict[str, tuple[int | None, frozenset[str]]] = field(default_factory=dict)
+    #: login -> the shared spaces their catalog names, as (space, database)
+    catalogs: dict[str, frozenset[tuple[str, str]]] = field(default_factory=dict)
+    #: login -> the databases they can reach, directly or through a role (observed only)
+    access: dict[str, frozenset[str]] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Step:
+    """One change: what it does, in words, and the statements that do it, each with the database to run it on."""
+
+    summary: str
+    statements: tuple[tuple[str, str | None], ...] = ()
+
+
+@dataclass
+class Plan:
+    """The changes that make Memgraph match the spec, in the order they must run."""
+
+    steps: list[Step] = field(default_factory=list)
+    #: Logins ``apply`` will create, which need a generated password.
+    new_users: list[str] = field(default_factory=list)
+    #: What a removal keeps because ``prune`` wasn't asked for.
+    kept: list[str] = field(default_factory=list)
+
+    @property
+    def empty(self) -> bool:
+        """Whether Memgraph already matches the spec."""
+        return not self.steps
+
+
+def desired_state(spec: Spec) -> State:
+    """What Memgraph should hold for *spec*."""
+    state = State()
+    for login in spec.members:
+        database = personal_database(login)
+        role = Role(
+            f"cg_u_{login}",
+            (database,),
+            (f"GRANT {_OWNER_PRIVILEGES} TO ROLE {{role}}", *_EVERYTHING),
+        )
+        state.databases.add(database)
+        state.users.add(login)
+        state.roles[role.name] = role
+        state.assignments.add(Assignment(login, role.name, database))
+        state.catalogs[login] = frozenset((space.name, shared_database(space.name)) for space in spec.spaces_of(login))
+    for space in spec.spaces:
+        database = shared_database(space.name)
+        role = _member_role(space)
+        state.databases.add(database)
+        state.roles[role.name] = role
+        state.assignments.update(Assignment(login, role.name, database) for login in space.members)
+    if spec.spaces:
+        worker = Role(
+            "cg_worker",
+            tuple(sorted(shared_database(space.name) for space in spec.spaces)),
+            (f"GRANT {_OWNER_PRIVILEGES} TO ROLE {{role}}", *_EVERYTHING),
+        )
+        state.users.add(SERVICE_ACCOUNT)
+        state.roles[worker.name] = worker
+        state.assignments.update(Assignment(SERVICE_ACCOUNT, worker.name, database) for database in worker.databases)
+    limits: dict[int, set[str]] = {}
+    if spec.personal_memory_limit_mb:
+        limits.setdefault(spec.personal_memory_limit_mb, set()).update(map(personal_database, spec.members))
+    for space in spec.spaces:
+        if space.memory_limit_mb:
+            limits.setdefault(space.memory_limit_mb, set()).add(shared_database(space.name))
+    state.profiles = {f"cg_{mb}mb": (mb, frozenset(databases)) for mb, databases in limits.items()}
+    return state
+
+
+def _member_role(space: SharedSpace) -> Role:
+    grants = [
+        f"GRANT {_PRIVILEGES} TO ROLE {{role}}",
+        "GRANT READ ON NODES CONTAINING LABELS * TO ROLE {role}",
+        "GRANT READ ON EDGES OF TYPE * TO ROLE {role}",
+        "GRANT READ {{*}} ON NODES CONTAINING LABELS * TO ROLE {role}",
+        "GRANT READ {{*}} ON EDGES OF TYPE * TO ROLE {role}",
+    ]
+    for label in space.labels:
+        grants += [
+            f"GRANT * ON NODES CONTAINING LABELS :{label} TO ROLE {{role}}",
+            f"GRANT READ, SET PROPERTY {{{{*}}}} ON NODES CONTAINING LABELS :{label} TO ROLE {{role}}",
+        ]
+    for edge_type in space.edge_types:
+        grants += [
+            f"GRANT * ON EDGES OF TYPE :{edge_type} TO ROLE {{role}}",
+            f"GRANT READ, SET PROPERTY {{{{*}}}} ON EDGES OF TYPE :{edge_type} TO ROLE {{role}}",
+        ]
+    return Role(f"space_{space.name}_member", (shared_database(space.name),), tuple(grants))
+
+
+#: Runs one statement as the admin: (statement, database or None for the admin's main one, parameters).
+Query = Callable[[str, str | None, dict[str, Any] | None], list[dict[str, Any]]]
+
+
+def observed_state(query: Query, members: Iterable[str] = ()) -> State:
+    """What Memgraph holds of the provisioner's objects.
+
+    *members* are logins to inspect even if they hold no role yet.
+    """
+    state = State()
+    state.databases = {row["Name"] for row in query("SHOW DATABASES", None, None) if _owned(row["Name"])}
+    all_users = {row["user"] for row in query("SHOW USERS", None, None)}
+    state.roles = {
+        row["role"]: None for row in query("SHOW ROLES", None, None) if not row.get("builtin") and _owned(row["role"])
+    }
+    holders = {SERVICE_ACCOUNT} & all_users
+    for role in state.roles:
+        holders.update(row["users"] for row in query(f"SHOW USERS FOR ROLE {role}", None, None))
+    holders.update(set(members) & all_users)
+    # A removed member holds no role any more; their personal database still marks them as ours.
+    holders.update(user for user in all_users if personal_database(user) in state.databases)
+    state.users = holders
+    for user in holders:
+        rows = query(f"SHOW DATABASE PRIVILEGES FOR USER {user}", None, None)
+        state.access[user] = frozenset(name for row in rows for name in row.get("grants") or ())
+    for user in holders:
+        for database in state.databases:
+            for row in query(f"SHOW ROLE FOR {user} ON DATABASE {database}", None, None):
+                if row.get("role") in state.roles:
+                    state.assignments.add(Assignment(user, row["role"], database))
+    for row in query("SHOW TENANT PROFILES", None, None):
+        if _owned(row["profile"]):
+            databases = frozenset(name.strip() for name in str(row.get("databases") or "").split(",") if name.strip())
+            state.profiles[row["profile"]] = (_megabytes(row.get("memory_limit")), databases)
+    for user in holders - {SERVICE_ACCOUNT}:
+        database = personal_database(user)
+        if database in state.databases:
+            rows = query(
+                f"MATCH (m:{MEMBERSHIP_LABEL}) RETURN m.space AS space, m.database AS database", database, None
+            )
+            state.catalogs[user] = frozenset((row["space"], row["database"]) for row in rows)
+    return state
+
+
+def _megabytes(text: Any) -> int | None:
+    """``"64.00MiB"`` -> 64; anything else (``"UNLIMITED"``) -> None."""
+    value = str(text or "")
+    if value.endswith("MiB"):
+        return round(float(value[:-3]))
+    if value.endswith("GiB"):
+        return round(float(value[:-3]) * 1024)
+    return None
+
+
+def plan(spec: Spec, observed: State, *, prune: bool = False) -> Plan:
+    """The steps that turn *observed* into *spec*'s desired state."""
+    desired = desired_state(spec)
+    result = Plan()
+    steps = result.steps
+
+    for database in sorted(desired.databases - observed.databases):
+        steps.append(Step(f"create database {database}", ((f"CREATE DATABASE {database}", None),)))
+    for name, (mb, databases) in sorted(desired.profiles.items()):
+        current = observed.profiles.get(name)
+        if current is None:
+            steps.append(
+                Step(
+                    f"create tenant profile {name}",
+                    ((f"CREATE TENANT PROFILE {name} LIMIT memory_limit {mb} MB", None),),
+                )
+            )
+        for database in sorted(databases - (current[1] if current else frozenset())):
+            steps.append(
+                Step(f"limit {database} with {name}", ((f"SET TENANT PROFILE ON DATABASE {database} TO {name}", None),))
+            )
+    for name in sorted(set(desired.roles) - set(observed.roles)):
+        role = desired.roles[name]
+        assert role is not None
+        steps.append(Step(f"create role {name}", tuple((statement, None) for statement in role.statements())))
+    for login in sorted(desired.users - observed.users):
+        result.new_users.append(login)
+        # The password is generated at apply time, never shown by plan.
+        steps.append(
+            Step(f"create user {login}", (("CREATE USER IF NOT EXISTS {login} IDENTIFIED BY {password}", login),))
+        )
+    for login in sorted(desired.users - observed.users - {SERVICE_ACCOUNT}):
+        steps.append(Step(f"make {personal_database(login)} {login}'s main database", _main_database(login)))
+    for assignment in sorted(desired.assignments - observed.assignments, key=_order):
+        steps.append(
+            Step(
+                f"give {assignment.user} {assignment.role} on {assignment.database}",
+                ((f"GRANT ROLE {assignment.role} TO {assignment.user} ON {assignment.database}", None),),
+            )
+        )
+    for login, spaces in sorted(desired.catalogs.items()):
+        if observed.catalogs.get(login, frozenset()) != spaces:
+            names = ", ".join(sorted(space for space, _ in spaces)) or "none"
+            steps.append(Step(f"record {login}'s shared spaces: {names}", ((_CATALOG, login),)))
+
+    for assignment in sorted(observed.assignments - desired.assignments, key=_order):
+        steps.append(
+            Step(
+                f"take {assignment.role} on {assignment.database} from {assignment.user}",
+                ((f"REVOKE ROLE {assignment.role} FROM {assignment.user} ON {assignment.database}", None),),
+            )
+        )
+    for name in sorted(set(observed.roles) - set(desired.roles)):
+        steps.append(Step(f"drop role {name}", ((f"DROP ROLE {name}", None),)))
+    for login in sorted(observed.users - desired.users):
+        database = personal_database(login)
+        if database in observed.access.get(login, frozenset()):
+            steps.append(
+                Step(
+                    f"revoke {login}'s access to {database}", ((f"REVOKE DATABASE {database} FROM USER {login}", None),)
+                )
+            )
+        if prune:
+            steps.append(Step(f"drop user {login}", ((f"DROP USER {login}", None),)))
+        else:
+            result.kept.append(f"user {login}")
+    for name, (_, databases) in sorted(observed.profiles.items()):
+        wanted = desired.profiles.get(name, (None, frozenset()))[1]
+        for database in sorted(databases - wanted):
+            steps.append(Step(f"unlimit {database}", ((f"REMOVE TENANT PROFILE FROM DATABASE {database}", None),)))
+        if name not in desired.profiles:
+            steps.append(Step(f"drop tenant profile {name}", ((f"DROP TENANT PROFILE {name}", None),)))
+    for database in sorted(observed.databases - desired.databases):
+        if prune:
+            steps.append(Step(f"drop database {database}", ((f"DROP DATABASE {database} FORCE", None),)))
+        else:
+            result.kept.append(f"database {database}")
+    return result
+
+
+def _main_database(login: str) -> tuple[tuple[str, str | None], ...]:
+    # The direct grant is what SET MAIN DATABASE needs: revoking it clears the main database even when a role
+    # still reaches the database.
+    database = personal_database(login)
+    return ((f"GRANT DATABASE {database} TO USER {login}", None), (f"SET MAIN DATABASE {database} FOR {login}", None))
+
+
+#: Catalog rewrite marker: run against a member's personal database with their shared spaces.
+_CATALOG = "-- catalog --"
+
+
+def _order(assignment: Assignment) -> tuple[str, str, str]:
+    return (assignment.user, assignment.database, assignment.role)
+
+
+@dataclass
+class Applied:
+    """What ``apply`` did: the steps run and the passwords of users it created (shown once, never stored)."""
+
+    steps: list[Step]
+    passwords: dict[str, str]
+    kept: list[str]
+
+
+def apply(spec: Spec, query: Query, *, prune: bool = False) -> Applied:
+    """Make Memgraph match *spec*, then return what was done.
+
+    Raises:
+        neo4j.exceptions.Neo4jError: a statement Memgraph rejected; the steps before it stay applied, and
+            re-running ``apply`` continues from where it stopped.
+    """
+    the_plan = plan(spec, observed_state(query, spec.members), prune=prune)
+    desired = desired_state(spec)
+    passwords = {login: secrets.token_urlsafe(18) for login in the_plan.new_users}
+    for step in the_plan.steps:
+        for statement, target in step.statements:
+            if statement == _CATALOG:
+                assert target is not None
+                _write_catalog(query, target, desired.catalogs[target])
+            elif "{password}" in statement:
+                assert target is not None
+                # token_urlsafe only yields [A-Za-z0-9_-], so the quoted literal can't be broken out of;
+                # Memgraph's CREATE USER takes no query parameters.
+                query(statement.format(login=target, password=f"'{passwords[target]}'"), None, None)
+            else:
+                query(statement, target, None)
+    # Memgraph can't report a user's main database, so plan can't see it drift (a revoke clears it); re-assert it.
+    for login in spec.members:
+        for statement, target in _main_database(login):
+            query(statement, target, None)
+    # Members can't create indexes or constraints in a shared space, so the memory store's schema is set up here.
+    for space in spec.spaces:
+        setup_shared_schema(query, shared_database(space.name))
+    return Applied(the_plan.steps, passwords, the_plan.kept)
+
+
+def setup_shared_schema(query: Query, database: str) -> None:
+    """Create sessions-graph's constraints and indexes in shared *database*, as the admin; idempotent."""
+    from sessions_graph import SessionsGraph
+
+    SessionsGraph(cast("Any", _OnDatabase(query, database))).setup()
+
+
+class _OnDatabase:
+    """The ``query`` half of memgraph-toolbox's client, pinned to one database over an admin :data:`Query`."""
+
+    def __init__(self, query: Query, database: str) -> None:
+        self._query = query
+        self._database = database
+
+    def query(self, statement: str, params: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        return self._query(statement, self._database, params)
+
+
+def _write_catalog(query: Query, login: str, spaces: frozenset[tuple[str, str]]) -> None:
+    rows = [{"space": space, "database": shared} for space, shared in sorted(spaces)]
+    query(
+        f"MATCH (m:{MEMBERSHIP_LABEL}) DETACH DELETE m "
+        f"WITH count(*) AS _ UNWIND $rows AS row "
+        f"CREATE (:{MEMBERSHIP_LABEL} {{space: row.space, database: row.database}})",
+        personal_database(login),
+        {"rows": rows},
+    )

context_graph_spaces/resolver.py

@@ -0,0 +1,129 @@
+"""The Enterprise edition's space resolver: the Memgraph login is the user.
+
+memgraph-context-graph finds :class:`EnterpriseSpaces` through the
+``memgraph_context_graph.editions`` entry point when the config file says
+``edition = "enterprise"``. Map #501's rules, as code:
+
+- Identity is the login (``[memgraph] user``). Memgraph authenticates it on
+  every connection, so it can't be claimed. A configured
+  ``identity.user_id`` or ``memgraph.database`` is refused rather than ignored,
+  because either would silently disagree with the login. A hook payload's
+  ``user_id`` is ignored.
+- The personal space is the login's main database, reached by naming no
+  database. Hooks therefore resolve their target without a single query.
+- Shared spaces are read from the ``(:SpaceMembership)`` catalog that
+  ``context-graph-spaces apply`` writes into the personal database. That is the
+  one query, made only by long-lived readers (the MCP server's recall and
+  memory tools), and cached until :meth:`EnterpriseSpaces.refresh`.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING, Any
+
+from memgraph_context_graph.spaces import EDITION_ENTERPRISE, PERSONAL, MemgraphTarget, Space, SpaceError
+
+from .provision import MEMBERSHIP_LABEL
+
+if TYPE_CHECKING:
+    from memgraph_context_graph.adapters._identity import HookConfig
+
+#: The longest a connection outlives a revoked grant, in seconds. Memgraph checks grants when a connection
+#: opens, so a long-lived reader (the MCP server) would otherwise keep a removed member's access until restart.
+REVOCATION_DELAY_SECONDS = 60.0
+
+#: Config keys the login decides in Enterprise; writing them is an error.
+_REFUSED_KEYS = {
+    "identity.user_id": "the user is your Memgraph login",
+    "memgraph.database": "your personal space is your login's main database",
+}
+
+
+class EnterpriseSpaces:
+    """One login's personal space and the shared spaces it belongs to."""
+
+    edition = EDITION_ENTERPRISE
+
+    def __init__(self, config: HookConfig) -> None:
+        """Check *config* is a valid Enterprise config.
+
+        Raises:
+            SpaceError: no ``[memgraph] user``, or a key the login decides is set.
+        """
+        for key, reason in _REFUSED_KEYS.items():
+            if key in config.present:
+                raise SpaceError(f"Remove {key} from the config file: in the Enterprise edition {reason}.")
+        if not config.memgraph_user:
+            raise SpaceError("The Enterprise edition needs [memgraph] user: your Memgraph login.")
+        self._login = config.memgraph_user
+        self._personal = Space(
+            PERSONAL,
+            MemgraphTarget(
+                url=config.memgraph_url,
+                user=config.memgraph_user,
+                password=config.memgraph_password,
+                database=None,
+                max_connection_lifetime=REVOCATION_DELAY_SECONDS,
+            ),
+        )
+        self._lock = threading.Lock()
+        self._shared: dict[str, Space] | None = None
+
+    def user_id(self, payload: dict[str, Any] | None = None) -> str | None:
+        """The login; a payload can't name anyone else."""
+        return self._login
+
+    def personal(self) -> Space:
+        """The login's main database."""
+        return self._personal
+
+    def readable(self) -> list[Space]:
+        """The personal space, then the shared spaces the catalog lists, in name order."""
+        return [self._personal, *sorted(self._shared_spaces().values(), key=lambda space: space.name)]
+
+    def shared_space(self, name: str) -> Space:
+        """The shared space *name*, if the login belongs to it.
+
+        Raises:
+            SpaceError: the catalog doesn't list *name*.
+        """
+        spaces = self._shared_spaces()
+        if name not in spaces:
+            known = ", ".join(sorted(spaces)) or "none"
+            raise SpaceError(f"You aren't a member of a shared space named {name!r} (yours: {known}).")
+        return spaces[name]
+
+    def refresh(self) -> None:
+        """Forget the cached catalog, e.g. after Memgraph refused a space it listed."""
+        with self._lock:
+            self._shared = None
+
+    def _shared_spaces(self) -> dict[str, Space]:
+        with self._lock:
+            if self._shared is None:
+                self._shared = self._read_catalog()
+            return self._shared
+
+    def _read_catalog(self) -> dict[str, Space]:
+        from memgraph_toolbox.api.memgraph import Memgraph
+
+        target = self._personal.target
+        client = Memgraph(**target.client_kwargs(), user_agent="context-graph-spaces")
+        try:
+            rows = client.query(f"MATCH (m:{MEMBERSHIP_LABEL}) RETURN m.space AS space, m.database AS database")
+        finally:
+            client.close()
+        return {
+            row["space"]: Space(
+                row["space"],
+                MemgraphTarget(
+                    url=target.url,
+                    user=target.user,
+                    password=target.password,
+                    database=row["database"],
+                    max_connection_lifetime=target.max_connection_lifetime,
+                ),
+            )
+            for row in rows
+        }

context_graph_spaces/spec.py

@@ -0,0 +1,157 @@
+"""The spaces spec: who the members are and which shared spaces they belong to.
+
+An admin keeps one TOML file, reviewed like code, and ``context-graph-spaces
+apply`` makes Memgraph match it::
+
+    members = ["ante", "bob"]
+    personal_memory_limit_mb = 2048        # optional, per personal space
+
+    [spaces.payments]
+    members = ["ante", "bob"]
+    memory_limit_mb = 4096                 # optional
+    labels = ["Memory", "MemoryVersion"]   # optional; what members may write
+    edge_types = ["HAS_MEMORY"]            # optional
+
+Every member gets a personal space automatically; it isn't listed. A shared
+space's ``labels``/``edge_types`` default to the curated memory the memory tool
+writes (map #501: v1 shares curated memory only). They are data, not code, so
+widening what a space holds is an edit here.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # tomli is tomllib's backport
+    import tomli as tomllib
+
+#: What members may create and change in a shared space by default: the
+#: memory tool's files, their history, and what links them to the space and
+#: project. Chunks and entities are left to the space's reconcile worker;
+#: members may only drop a file's HAS_CHUNK links, which deleting the file does.
+DEFAULT_SHARED_LABELS = ("Memory", "MemoryVersion", "User", "Project")
+DEFAULT_SHARED_EDGE_TYPES = ("HAS_MEMORY", "HAS_MEMORY_VERSION", "PREVIOUS_VERSION", "ABOUT", "HAS_CHUNK")
+
+# Logins and space names become database, role and user names in DDL, which
+# Memgraph can't parameterize; this pattern is the guard that keeps them inert.
+_NAME = re.compile(r"^[a-z][a-z0-9_]{0,39}$")
+_LABEL = re.compile(r"^[A-Za-z][A-Za-z0-9_]{0,63}$")
+#: Prefixes the provisioner owns; a member login can't take one.
+RESERVED_PREFIXES = ("cg_", "space_", "u_")
+
+
+class SpecError(ValueError):
+    """The spec file is malformed or inconsistent."""
+
+
+@dataclass(frozen=True)
+class SharedSpace:
+    """One shared space: its members and what they may write in it."""
+
+    name: str
+    members: tuple[str, ...]
+    labels: tuple[str, ...] = DEFAULT_SHARED_LABELS
+    edge_types: tuple[str, ...] = DEFAULT_SHARED_EDGE_TYPES
+    memory_limit_mb: int | None = None
+
+
+@dataclass(frozen=True)
+class Spec:
+    """The whole desired state: members and shared spaces."""
+
+    members: tuple[str, ...]
+    spaces: tuple[SharedSpace, ...] = ()
+    personal_memory_limit_mb: int | None = None
+
+    def spaces_of(self, login: str) -> list[SharedSpace]:
+        """The shared spaces *login* belongs to, in spec order."""
+        return [space for space in self.spaces if login in space.members]
+
+
+def load_spec(path: str | Path) -> Spec:
+    """Read and validate a spec file.
+
+    Raises:
+        SpecError: the file isn't valid TOML or breaks a rule above.
+    """
+    try:
+        data = tomllib.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise SpecError(f"Can't read spec {path}: {exc}") from exc
+    return parse_spec(data)
+
+
+def parse_spec(data: dict[str, Any]) -> Spec:
+    """Validate a parsed spec mapping.
+
+    Raises:
+        SpecError: unknown keys, bad names, members of a space who aren't members, duplicate entries.
+    """
+    _no_unknown_keys(data, {"members", "spaces", "personal_memory_limit_mb"}, "the spec")
+    members = _names(data.get("members", []), "members", login=True)
+    spaces = []
+    for name, body in (data.get("spaces") or {}).items():
+        where = f"[spaces.{name}]"
+        if not isinstance(body, dict):
+            raise SpecError(f"{where} must be a table")
+        _no_unknown_keys(body, {"members", "labels", "edge_types", "memory_limit_mb"}, where)
+        _check_name(name, where)
+        space_members = _names(body.get("members", []), f"{where} members", login=True)
+        if outsiders := sorted(set(space_members) - set(members)):
+            raise SpecError(f"{where} lists {', '.join(outsiders)}, who aren't in the top-level members")
+        spaces.append(
+            SharedSpace(
+                name=name,
+                members=space_members,
+                labels=_labels(body.get("labels", DEFAULT_SHARED_LABELS), f"{where} labels"),
+                edge_types=_labels(body.get("edge_types", DEFAULT_SHARED_EDGE_TYPES), f"{where} edge_types"),
+                memory_limit_mb=_limit(body.get("memory_limit_mb"), f"{where} memory_limit_mb"),
+            )
+        )
+    return Spec(
+        members=members,
+        spaces=tuple(spaces),
+        personal_memory_limit_mb=_limit(data.get("personal_memory_limit_mb"), "personal_memory_limit_mb"),
+    )
+
+
+def _no_unknown_keys(table: dict[str, Any], known: set[str], where: str) -> None:
+    if unknown := sorted(set(table) - known):
+        raise SpecError(f"Unknown key(s) in {where}: {', '.join(unknown)}")
+
+
+def _names(value: Any, where: str, *, login: bool) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise SpecError(f"{where} must be a list of names")
+    for item in value:
+        _check_name(item, where)
+        if login and item.startswith(RESERVED_PREFIXES):
+            raise SpecError(f"{where}: {item!r} starts with a reserved prefix ({', '.join(RESERVED_PREFIXES)})")
+    if len(set(value)) != len(value):
+        raise SpecError(f"{where} lists a name twice")
+    return tuple(value)
+
+
+def _check_name(name: str, where: str) -> None:
+    if not _NAME.match(name):
+        raise SpecError(f"{where}: {name!r} must be lowercase letters, digits and _, starting with a letter")
+
+
+def _labels(value: Any, where: str) -> tuple[str, ...]:
+    if not isinstance(value, (list, tuple)) or not all(isinstance(item, str) and _LABEL.match(item) for item in value):
+        raise SpecError(f"{where} must be a list of label or edge-type names")
+    return tuple(value)
+
+
+def _limit(value: Any, where: str) -> int | None:
+    if value is None:
+        return None
+    if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+        raise SpecError(f"{where} must be a positive whole number of megabytes")
+    return value

context_graph_spaces/worker.py

@@ -0,0 +1,126 @@
+"""The shared-space reconcile worker: what members write, it extracts.
+
+Members may only write curated memory into a shared space, so the derived
+graph there (Chunks, entities, their relations, the memory passages recall
+embeds) is written by one login, ``cg_service``, run by the org next to
+``apply`` (map #501). Personal spaces keep reconciling locally, as before.
+
+Each pass, per shared space in the spec:
+
+1. Remove what deleted files left behind. A member's delete keeps its hands
+   off Chunks (it can't touch them), so their file's extraction outlives it.
+2. Reconcile every file marked ``extraction_status = 'pending'`` with
+   sessions-graph's own per-file reconciliation (GLiNER2 under the space's
+   adopted ontology, no LLM).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from .provision import SERVICE_ACCOUNT, shared_database
+
+if TYPE_CHECKING:
+    from sessions_graph import SessionsGraph
+
+    from memgraph_toolbox.api.memgraph import Memgraph
+
+    from .spec import Spec
+
+
+@dataclass
+class SpaceReport:
+    """One shared space's pass: files reconciled or failed, and leftovers removed."""
+
+    space: str
+    completed: list[str] = field(default_factory=list)
+    failed: list[tuple[str, str]] = field(default_factory=list)
+    pruned: int = 0
+    error: str | None = None
+
+
+def reconcile_spaces(
+    spec: Spec,
+    *,
+    url: str,
+    password: str,
+    extraction_backend: Any = None,
+    limit: int = 100,
+) -> list[SpaceReport]:
+    """One pass over every shared space in *spec*, as the service login.
+
+    A space that can't be reached is reported and skipped; the others still run.
+    """
+    from sessions_graph import SessionsGraph
+
+    from memgraph_toolbox.api.memgraph import Memgraph
+
+    reports = []
+    for space in spec.spaces:
+        report = SpaceReport(space.name)
+        client = None
+        try:
+            client = Memgraph(
+                url=url,
+                username=SERVICE_ACCOUNT,
+                password=password,
+                database=shared_database(space.name),
+                user_agent="context-graph-spaces-worker",
+            )
+            report.pruned = prune_deleted_extractions(client)
+            asyncio.run(_reconcile_pending(SessionsGraph(client), report, extraction_backend, limit))
+        # One space's failure is reported, and must not stop the others.
+        except Exception as exc:
+            report.error = f"{type(exc).__name__}: {exc}"
+        finally:
+            if client is not None:
+                client.close()
+        reports.append(report)
+    return reports
+
+
+async def _reconcile_pending(graph: SessionsGraph, report: SpaceReport, backend: Any, limit: int) -> None:
+    for memory_id in graph.get_pending_memory_reconciliations(limit=limit):
+        result = await graph.reconcile_memory(memory_id, extraction_backend=backend)
+        if result.status == "completed":
+            report.completed.append(result.path or memory_id)
+        else:
+            report.failed.append((result.path or memory_id, result.error or "unknown error"))
+
+
+def prune_deleted_extractions(db: Memgraph) -> int:
+    """Remove the extraction of memory files that no longer exist; returns how many relationships went.
+
+    The same cleanup :func:`sessions_graph.memory_store.forget_extraction` does for a live file, keyed on
+    the provenance ids that no longer name a ``(:Memory)``: in a shared space every source is a memory file.
+    """
+    live = [row["id"] for row in db.query("MATCH (m:Memory) RETURN m.memory_id AS id")]
+    relations = db.query(
+        "MATCH ()-[r]->() WHERE r.source_id IS NOT NULL AND NOT r.source_id IN $live "
+        "WITH r DELETE r RETURN count(*) AS n",
+        {"live": live},
+    )
+    db.query(
+        """
+        MATCH (c:Chunk)<-[mention:MENTIONED_IN]-(e)
+        WITH c, mention, e, [s IN coalesce(mention.sources, []) WHERE s IN $live] AS kept
+        SET mention.sources = kept
+        WITH c, mention, e, kept
+        WHERE size(kept) = 0
+        DELETE mention
+        WITH DISTINCT e
+        WHERE NOT EXISTS { MATCH (e)-[:MENTIONED_IN]->() }
+        DETACH DELETE e
+        """,
+        {"live": live},
+    )
+    db.query(
+        """
+        MATCH (c:Chunk)
+        WHERE NOT EXISTS { MATCH (c)<-[:HAS_CHUNK]-() } AND NOT EXISTS { MATCH (c)<-[:MENTIONED_IN]-() }
+        DETACH DELETE c
+        """
+    )
+    return relations[0]["n"] if relations else 0

context_graph_spaces-0.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: context-graph-spaces
+Version: 0.1.0
+Summary: The Enterprise edition of Context Graph: personal and shared memory spaces for many users on one Memgraph
+License: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: memgraph-context-graph>=0.5.0
+Requires-Dist: memgraph-toolbox
+Requires-Dist: neo4j>=5.0
+Requires-Dist: sessions-graph[reconciliation]>=0.6.0
+Requires-Dist: tomli>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=9.0.3; extra == 'test'
+Requires-Dist: sessions-graph[memgraph-context-graph,reconciliation]>=0.8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# context-graph-spaces
+
+The Enterprise edition of [Context Graph](../README.md): memory for many users on
+one shared, licensed Memgraph. Each user gets a **personal space**, and teams get
+**shared spaces**. Memgraph Enterprise enforces the isolation through
+multi-tenancy, role-based access control and label- and property-based access
+control. Our code doesn't filter.
+
+The Community edition (one user, one database) doesn't need this package and
+doesn't change when it's installed. A user's config file selects Enterprise
+explicitly:
+
+```toml
+edition = "enterprise"
+
+[memgraph]
+url = "bolt://memgraph.corp:7687"
+user = "ante"        # your Memgraph login is your identity
+password = "..."
+```
+
+## For admins: provisioning
+
+Spaces are declared in a spec file and applied idempotently:
+
+```toml
+members = ["ante", "bob"]
+personal_memory_limit_mb = 2048
+
+[spaces.payments]
+members = ["ante", "bob"]
+memory_limit_mb = 4096
+# labels = [...]       # what members may write; defaults to curated memory
+# edge_types = [...]
+```
+
+```bash
+export MEMGRAPH_URL=bolt://memgraph.corp:7687 MEMGRAPH_USER=<admin> MEMGRAPH_PASSWORD=...
+context-graph-spaces plan spaces.toml     # what would change
+context-graph-spaces apply spaces.toml    # make it so; prints one-time setup lines for new logins
+```
+
+What `apply` maintains:
+
+| Object | Name | Who |
+|---|---|---|
+| Personal database | `u_<login>` | its owner (main database), plus nobody else |
+| Shared database | `space_<name>` | members: read everything, write only the spec's labels |
+| Roles | `cg_u_<login>_<hash>`, `space_<name>_member_<hash>`, `cg_worker_<hash>` | named after what they grant |
+| Service login | `cg_service` | writes Chunks and entities in shared spaces |
+| Tenant profiles | `cg_<mb>mb` | memory caps from the spec |
+
+Removing someone from the spec revokes their access. Removing a space revokes
+access to it. Users and databases are only dropped with `--prune`. Only objects
+with the `u_`, `space_` and `cg_` prefixes are ever touched.
+
+## The shared-space worker
+
+Members can write only curated memory into a shared space. The derived graph
+there (chunks, entities, relations, and the embeddings recall uses) is written by
+one service login, `cg_service`. Run the worker next to `apply`, with the
+password `apply` printed once:
+
+```bash
+export CG_SERVICE_PASSWORD=...
+context-graph-spaces reconcile spaces.toml --watch     # one pass every 30s
+```
+
+Each pass, for each shared space, it does two things:
+
+1. It removes what deleted files left behind. A member's delete can't touch chunks.
+2. It reconciles changed memory files with GLiNER2 under the space's ontology.
+   No LLM is involved.
+
+Personal spaces keep reconciling locally, as in Community.
+
+## Tests
+
+The tests run end-to-end against a licensed Memgraph. The licence is read from
+`MEMGRAPH_ENTERPRISE_LICENSE` and `MEMGRAPH_ORGANIZATION_NAME` (the repo's `.env`
+locally, secrets in CI):
+
+```bash
+./scripts/dev-memgraph.sh test-enterprise
+```

context_graph_spaces-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+context_graph_spaces/__init__.py,sha256=v4yE-LH5HO9_67ndC0Ld_yqq7Kn3pXpHG9zMQZy0Vas,629
+context_graph_spaces/cli.py,sha256=-nwfVKm4nsIjjN7HKo3apP4PBIxfVRR_fWWM3WYRDno,5649
+context_graph_spaces/provision.py,sha256=v4wMb30m_OXb4aJ2aSzCTqZWfgIolsWCQbTpoz5WHf4,18790
+context_graph_spaces/resolver.py,sha256=T_1_HJjfE3cn1H2osGZZjwagCgQOl9FuUD-yvVxcGSQ,5164
+context_graph_spaces/spec.py,sha256=gdXn8QUHl22qFsbhewXUM7B8-LEzq4sz0nmjBMbIuYU,6231
+context_graph_spaces/worker.py,sha256=Z3M6r8dgnVCPn8AVz55cT4g83jVYSoOioaqrFbAeg4w,4477
+context_graph_spaces-0.1.0.dist-info/METADATA,sha256=y3sFG1CMEQuA1RxaNr__efT6tgwaW-x7IsZrPxCs0Qc,3793
+context_graph_spaces-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+context_graph_spaces-0.1.0.dist-info/entry_points.txt,sha256=O85B0thfaYurm7g6lovSMNNusOHd2x9BYycoNNUGopI,166
+context_graph_spaces-0.1.0.dist-info/licenses/LICENSE,sha256=QFsrXi0IKm1YS_3TeJb28R7alTFl6_f4B-JzRlnqcTg,1065
+context_graph_spaces-0.1.0.dist-info/RECORD,,

context_graph_spaces-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

context_graph_spaces-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+context-graph-spaces = context_graph_spaces.cli:main
+
+[memgraph_context_graph.editions]
+enterprise = context_graph_spaces.resolver:EnterpriseSpaces

context_graph_spaces-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Memgraph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.