memgres 0.4.1__tar.gz → 0.5.0__tar.gz

{memgres-0.4.1 → memgres-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.4.1
+Version: 0.5.0
 Summary: Drop-in memory for AI agents: one Postgres, lexical + semantic recall, diff-versioned history, GDPR-erasable.
 Author: mozgsml
 License-Expression: MIT

{memgres-0.4.1 → memgres-0.5.0}/memgres/_version.py

@@ -8,4 +8,4 @@ here at release; nowhere else carries the number.
 PEP 440: a ``.devN`` suffix marks an unreleased build ahead of the last tag.
 """
 
-__version__ = "0.4.1"
+__version__ = "0.5.0"

memgres-0.5.0/memgres/admin_cli.py

@@ -0,0 +1,109 @@
+"""``memgres-grant-superadmin`` — promote a user to the superadmin service role.
+
+The break-glass path for creating a superadmin when bootstrap seeded only a
+``user_manager`` (or none), and the way out of a lockout (the last superadmin was
+revoked). Like Django's ``createsuperuser``, it talks **directly to the database**
+(``MEMGRES_DATABASE_URL``) — so the gate is host/DB access, not a network token.
+
+    memgres-grant-superadmin --list                 # show users + roles
+    memgres-grant-superadmin --user <uuid>
+    memgres-grant-superadmin --token-label <label>  # resolve the user by a token label
+    memgres-grant-superadmin --revoke --user <uuid> # demote (anti-lockout applies)
+
+A raw ``UPDATE`` is the last-ditch fallback; prefer this so the change is
+validated (real user, anti-lockout) rather than silently wrong.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import identity
+from .config import load
+
+
+def _resolve_user(conn, args) -> str:
+    """Return the target user id from --user or --token-label, or exit with a
+    clear message."""
+    if args.user:
+        with conn.cursor() as cur:
+            cur.execute("SELECT id FROM app_user WHERE id=%s", (args.user,))
+            if cur.fetchone() is None:
+                raise SystemExit(f"no such user: {args.user}")
+        return args.user
+    # by token label — must be unambiguous
+    with conn.cursor() as cur:
+        cur.execute("SELECT DISTINCT user_id FROM token WHERE label=%s "
+                    "AND revoked_at IS NULL", (args.token_label,))
+        rows = cur.fetchall()
+    if not rows:
+        raise SystemExit(f"no active token labelled {args.token_label!r}")
+    if len(rows) > 1:
+        raise SystemExit(
+            f"token label {args.token_label!r} maps to {len(rows)} users — "
+            "use --user <uuid> instead")
+    return str(rows[0][0])
+
+
+def _list_users(conn) -> None:
+    with conn.cursor() as cur:
+        cur.execute("SELECT id, role, name, description FROM app_user "
+                    "ORDER BY role DESC, created_at")
+        rows = cur.fetchall()
+    if not rows:
+        print("(no users yet)")
+        return
+    print(f"{'id':36}  {'role':12}  name / description")
+    for uid, role, name, desc in rows:
+        label = name or desc or ""
+        print(f"{str(uid):36}  {role:12}  {label}")
+
+
+def main(argv=None) -> None:  # pragma: no cover - thin entrypoint
+    import logging
+
+    import psycopg
+
+    logging.basicConfig(level=logging.INFO,
+                        format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+    p = argparse.ArgumentParser(
+        prog="memgres-grant-superadmin",
+        description="Promote (or demote) a user's superadmin service role.")
+    p.add_argument("--list", action="store_true",
+                   help="list users and their roles, then exit")
+    p.add_argument("--user", metavar="UUID", help="target user id")
+    p.add_argument("--token-label", metavar="LABEL",
+                   help="resolve the target user by one of its token labels")
+    p.add_argument("--revoke", action="store_true",
+                   help="demote the user out of superadmin (anti-lockout applies)")
+    p.add_argument("--demote-to", default="user", choices=("user", "user_manager"),
+                   help="role to demote to with --revoke (default: user)")
+    args = p.parse_args(argv)
+
+    cfg = load()
+    with psycopg.connect(cfg.database_url or "") as conn:
+        conn.autocommit = True
+        try:
+            if args.list:
+                _list_users(conn)
+                return
+            if not args.user and not args.token_label:
+                p.error("give --user or --token-label (or --list)")
+            uid = _resolve_user(conn, args)
+            if args.revoke:
+                identity.revoke_superadmin(conn, uid, demote_to=args.demote_to)
+                print(f"revoked superadmin from {uid} (now {args.demote_to})")
+            else:
+                identity.grant_superadmin(conn, uid)
+                print(f"granted superadmin to {uid}")
+        except identity.AuthError as e:          # anti-lockout
+            raise SystemExit(f"refused: {e}")
+        except psycopg.errors.UndefinedColumn:
+            raise SystemExit(
+                "this database has no service-role column yet — start "
+                "memgres-server/-mcp once to migrate it, then retry.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

memgres-0.5.0/memgres/bootstrap.py

@@ -0,0 +1,126 @@
+"""First-admin onboarding for a managed deployment.
+
+A ``managed`` server needs one control-plane admin to exist before anyone can be
+provisioned. This module seeds that first admin **once**, at startup, from a
+bootstrap secret — then goes inert. It is deliberately separate from
+:mod:`memgres.identity` (pure DB logic) because it also does file I/O and
+logging.
+
+Invariants (see the epic ``meta.memgres.admin_as_role_and_mcp``):
+
+* seeding fires **only when the database holds zero admin users** — a fresh
+  install. Once any admin exists, the env/file secret is inert (never a standing
+  backdoor); the stored token authenticates its real user from then on.
+* the secret is stored **hashed, as an ordinary token** of the seeded user, so
+  the same value later resolves to that attributed user, not an anonymous root.
+* only ``managed`` mode bootstraps; ``single``/``open`` are untouched.
+
+Secret precedence (config rejects setting both):
+
+* ``MEMGRES_ADMIN_TOKEN`` — the secret itself, in the env.
+* ``MEMGRES_ADMIN_TOKEN_FILE`` — a path, **read-or-create** (Jenkins-style):
+  present and non-empty → read it; missing/empty → generate an ``mgk_`` token,
+  write it ``0600``, and log the **path only** (never the secret). The operator
+  copies it out and deletes the file on their own schedule.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional, Tuple
+
+from . import identity
+from .config import Config
+
+log = logging.getLogger("memgres.bootstrap")
+
+
+class BootstrapError(RuntimeError):
+    """The bootstrap configuration is unusable (bad secret, unwritable file)."""
+
+
+def _read_or_create_token_file(path: str) -> Tuple[str, Optional[str]]:
+    """Return ``(secret, generated_path)``. If the file has a token, read it
+    (``generated_path`` None). If missing/empty, generate a fresh ``mgk_`` token,
+    write it ``0600``, and return the path so the caller can log it."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            existing = f.read().strip()
+    except FileNotFoundError:
+        existing = ""
+    except OSError as e:                                  # unreadable → fail loud
+        raise BootstrapError(f"cannot read MEMGRES_ADMIN_TOKEN_FILE {path!r}: {e}")
+    if existing:
+        return existing, None
+
+    secret = identity.new_token()
+    try:
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(secret + "\n")
+        os.chmod(path, 0o600)            # tighten even if the file pre-existed
+    except OSError as e:
+        raise BootstrapError(f"cannot write MEMGRES_ADMIN_TOKEN_FILE {path!r}: {e}")
+    return secret, path
+
+
+def _bootstrap_secret(cfg: Config) -> Tuple[Optional[str], Optional[str]]:
+    """Resolve the bootstrap secret from config → ``(secret, generated_path)``.
+    ``(None, None)`` when the operator supplied no source."""
+    if cfg.admin_token_file:
+        return _read_or_create_token_file(cfg.admin_token_file)
+    if cfg.admin_token:
+        return cfg.admin_token, None
+    return None, None
+
+
+def bootstrap_admin(conn, cfg: Config) -> Optional[str]:
+    """Seed the first service admin if the database has none. Returns the seeded
+    user's id, or ``None`` when nothing was seeded (not managed, admins already
+    exist, or no bootstrap source). Idempotent — safe to call on every startup.
+
+    Runs in its own transaction so a partial seed never commits."""
+    if cfg.key_mode != "managed":
+        return None
+
+    with conn.transaction():
+        if identity.count_service_admins(conn) > 0:
+            return None                  # control plane exists → env/file inert
+
+        secret, generated_path = _bootstrap_secret(cfg)
+        if not secret:
+            log.warning(
+                "memgres: managed mode has no service admin and neither "
+                "MEMGRES_ADMIN_TOKEN nor MEMGRES_ADMIN_TOKEN_FILE is set. "
+                "No one can be provisioned until you seed an admin — set a "
+                "bootstrap token, or run the memgres-grant-superadmin CLI.")
+            return None
+        if not identity.valid_format(secret):
+            # A legacy or weak env secret: don't crash (it still works as the
+            # anonymous break-glass root via identity.resolve), but it can't be
+            # stored as an attributable token. Warn and leave the DB adminless.
+            log.warning(
+                "memgres: the bootstrap token is not a strong mgk_ token, so no "
+                "attributable superadmin was seeded — it still works as the "
+                "anonymous env root. For an attributed admin, set a strong "
+                "MEMGRES_ADMIN_TOKEN (mgk_ + 43 url-safe chars) or leave "
+                "MEMGRES_ADMIN_TOKEN_FILE empty to have one generated.")
+            return None
+
+        uid = identity.create_user(
+            conn, name="bootstrap-admin",
+            description="seeded at startup from the bootstrap token",
+            role=cfg.admin_role)
+        identity.register_token(conn, uid, secret, permission="admin",
+                                label="bootstrap")
+
+    if generated_path:
+        log.warning(
+            "memgres: no admin token was provided — generated one and wrote it "
+            "to %s (mode 0600). Copy it now; it is NOT logged and won't be shown "
+            "again. Delete the file once you've stored the token.", generated_path)
+    else:
+        log.info("memgres: seeded the first service admin (role=%s) from the "
+                 "bootstrap token", cfg.admin_role)
+    return uid

{memgres-0.4.1 → memgres-0.5.0}/memgres/config.py

@@ -61,7 +61,15 @@ class Config:
                                  # (set in MCP/env for a single-tenant deployment)
     # identity / tenancy (see docs/TENANCY.md)
     key_mode: str                # single | open | managed  (how tokens/users are minted)
-    admin_token: str             # global-admin bearer: provision users/namespaces anywhere
+    admin_token: str             # bootstrap/break-glass bearer (managed): seeds the
+                                 # first service admin at startup, then resolves to
+                                 # that real user (see memgres.bootstrap)
+    admin_token_file: str        # read-or-create path for the bootstrap token
+                                 # (Jenkins-style): present → read it; missing/empty
+                                 # → generate an mgk_ token, write it 0600, log the
+                                 # path only. Mutually exclusive with admin_token.
+    admin_role: str              # role the bootstrap admin is seeded with:
+                                 # user_manager (default) | superadmin
     # organization
     tree_enabled: bool           # ltree path column + GiST index for fast subtree selection
     require_parent: bool         # False = sparse paths (create food.apple with no food row);
@@ -158,6 +166,13 @@ class Config:
             raise ValueError(f"unknown MEMGRES_VECTOR_BACKEND: {self.vector_backend}")
         if self.key_mode not in ("single", "open", "managed"):
             raise ValueError(f"unknown MEMGRES_KEY_MODE: {self.key_mode}")
+        if self.admin_role not in ("user_manager", "superadmin"):
+            raise ValueError(
+                "MEMGRES_ADMIN_ROLE must be user_manager or superadmin "
+                f"(got {self.admin_role!r})")
+        if self.admin_token and self.admin_token_file:
+            raise ValueError(
+                "set only one of MEMGRES_ADMIN_TOKEN / MEMGRES_ADMIN_TOKEN_FILE")
         if self.embed_provider != "none" and self.vector_backend == "pgvector" \
                 and self.embed_dim <= 0:
             raise ValueError(
@@ -179,6 +194,8 @@ def load() -> Config:
         default_token=_str("MEMGRES_TOKEN", ""),
         key_mode=_str("MEMGRES_KEY_MODE", "single"),
         admin_token=_str("MEMGRES_ADMIN_TOKEN", ""),
+        admin_token_file=_str("MEMGRES_ADMIN_TOKEN_FILE", ""),
+        admin_role=_str("MEMGRES_ADMIN_ROLE", "user_manager"),
         tree_enabled=_bool("MEMGRES_TREE", True),
         require_parent=_bool("MEMGRES_REQUIRE_PARENT", False),
         history_enabled=_bool("MEMGRES_HISTORY", True),

{memgres-0.4.1 → memgres-0.5.0}/memgres/identity.py

@@ -48,6 +48,16 @@ def bearer_token(authorization: Optional[str],
 # permission lattice
 _RANK = {"read": 1, "write": 2, "admin": 3}
 
+# service roles (app_user.role) — orthogonal to the per-namespace permission
+# lattice above. `user` is the default; the two admin roles govern the CONTROL
+# plane (provisioning) and, for superadmin, cross-namespace data access:
+#   user         — owns namespaces, manages access to its OWN spaces only.
+#   user_manager — user + create users + (re)issue tokens. No cross-tenant data.
+#   superadmin   — full root: read/write any namespace, grant any access,
+#                  grant/revoke roles. Principal.is_admin derives from this.
+SERVICE_ROLES = ("user", "user_manager", "superadmin")
+_ADMIN_ROLES = ("user_manager", "superadmin")
+
 
 class AuthError(PermissionError):
     """Bad/expired/revoked token, or the token may not do this here."""
@@ -91,46 +101,66 @@ class Principal:
     scope_namespace_id: Optional[str]      # scoped to one ns, or None = all the user's
     token_id: Optional[str] = None
     token_hash: Optional[str] = None
-    is_admin: bool = False                 # global admin (MEMGRES_ADMIN_TOKEN)
+    is_admin: bool = False                 # full root: env break-glass (user_id
+                                           # None) or a superadmin-role user
     provisional: bool = False              # valid token, user not yet materialized
+    role: str = "user"                     # service role of the owning user
+
+
+def can_manage_users(p: "Principal") -> bool:
+    """May this principal provision users / (re)issue tokens? True for a
+    user_manager, a superadmin, or the env break-glass root."""
+    return p.is_admin or p.role in _ADMIN_ROLES
 
 
 # ─── authentication ──────────────────────────────────────────────────────────
 def resolve(conn, cfg, secret: Optional[str]) -> Principal:
     """Authenticate a bearer secret into a :class:`Principal`.
 
-    * global admin token → admin principal;
-    * known token → its user/ceiling/scope (rejects revoked/expired);
+    * known token → its user/ceiling/scope/role (rejects revoked/expired). A
+      token whose user is a superadmin resolves with ``is_admin`` — so once
+      bootstrap has stored the env token as a real superadmin's token, that same
+      secret authenticates as the *attributed* user, not the anonymous root.
+    * env ``admin_token`` (break-glass) → anonymous admin principal. Tried only
+      *after* the stored-token lookup, so a seeded env token attributes to its
+      user; reachable before the first seed, or in modes bootstrap skips.
     * unknown but well-formed token in ``open`` mode → *provisional* principal
       (user materialized on first write); in ``managed`` mode → rejected.
     """
-    if cfg.admin_token and secret and hmac.compare_digest(secret, cfg.admin_token):
-        return Principal(user_id=None, permission="admin",
-                         scope_namespace_id=None, is_admin=True)
     if not secret:
         raise AuthError("a token is required")
-    if not valid_format(secret):
-        raise AuthError("malformed token (expected mgk_ + 43 url-safe chars)")
 
     h = token_hash(secret)
-    with conn.cursor() as cur:
-        cur.execute(
-            "SELECT id, user_id, namespace_id, permission, "
-            "       (revoked_at IS NOT NULL) AS revoked, "
-            "       (expires_at IS NOT NULL AND expires_at <= now()) AS expired "
-            "FROM token WHERE token_hash=%s", (h,))
-        row = cur.fetchone()
-        if row is not None:
-            tid, uid, nsid, perm, revoked, expired = row
-            if revoked:
-                raise AuthError("token revoked")
-            if expired:
-                raise AuthError("token expired")
-            cur.execute("UPDATE token SET last_used_at=now() WHERE id=%s", (tid,))
-            return Principal(user_id=str(uid), permission=perm,
-                             scope_namespace_id=str(nsid) if nsid else None,
-                             token_id=str(tid), token_hash=h)
+    if valid_format(secret):
+        with conn.cursor() as cur:
+            cur.execute(
+                "SELECT t.id, t.user_id, t.namespace_id, t.permission, "
+                "       (t.revoked_at IS NOT NULL) AS revoked, "
+                "       (t.expires_at IS NOT NULL AND t.expires_at <= now()) AS expired, "
+                "       u.role "
+                "FROM token t JOIN app_user u ON u.id = t.user_id "
+                "WHERE t.token_hash=%s", (h,))
+            row = cur.fetchone()
+            if row is not None:
+                tid, uid, nsid, perm, revoked, expired, role = row
+                if revoked:
+                    raise AuthError("token revoked")
+                if expired:
+                    raise AuthError("token expired")
+                cur.execute("UPDATE token SET last_used_at=now() WHERE id=%s", (tid,))
+                return Principal(user_id=str(uid), permission=perm,
+                                 scope_namespace_id=str(nsid) if nsid else None,
+                                 token_id=str(tid), token_hash=h, role=role,
+                                 is_admin=(role == "superadmin"))
+
+    # env break-glass root — any format (an operator may set a non-mgk secret);
+    # constant-time compare. Never reached for a seeded env token (matched above).
+    if cfg.admin_token and hmac.compare_digest(secret, cfg.admin_token):
+        return Principal(user_id=None, permission="admin",
+                         scope_namespace_id=None, is_admin=True)
 
+    if not valid_format(secret):
+        raise AuthError("malformed token (expected mgk_ + 43 url-safe chars)")
     if cfg.key_mode == "open":
         # accepted, but nothing is created until the first write
         return Principal(user_id=None, permission="write",
@@ -197,7 +227,8 @@ def resolve_space(conn, principal: Principal, *, space_id: Optional[str] = None,
     default). Reads never create. The returned permission is the token ceiling
     min the caller's membership; the caller enforces it against the op needed.
     """
-    if principal.is_admin:
+    if principal.is_admin and principal.user_id is None:
+        # env break-glass root: anonymous, addresses only by id
         if space_id:
             return str(space_id), "admin"
         raise AuthError("global admin must address a space by id")
@@ -216,11 +247,14 @@ def resolve_space(conn, principal: Principal, *, space_id: Optional[str] = None,
             raise AuthError("token is scoped to a different namespace")
 
     with conn.cursor() as cur:
-        # 1) by id — reach anything owned or shared
+        # 1) by id — reach anything owned or shared; a superadmin user reaches
+        #    ANY space by id (full root), still capped by its token ceiling.
         if space_id is not None:
             _scoped_ok(space_id)
             perm = _reach(cur, uid, str(space_id))
             if perm is None:
+                if principal.is_admin:
+                    return str(space_id), perm_min("admin", ceiling)
                 raise SpaceNotFound(f"namespace {space_id} not reachable")
             return str(space_id), perm_min(perm, ceiling)
 
@@ -259,13 +293,72 @@ def resolve_space(conn, principal: Principal, *, space_id: Optional[str] = None,
 
 
 # ─── management: users / namespaces / members ────────────────────────────────
-def create_user(conn, name: str = "", description: str = "") -> str:
+def create_user(conn, name: str = "", description: str = "",
+                role: str = "user") -> str:
+    if role not in SERVICE_ROLES:
+        raise ValueError(f"bad role: {role}")
     with conn.cursor() as cur:
-        cur.execute("INSERT INTO app_user (name, description) VALUES (%s, %s) "
-                    "RETURNING id", (name, description))
+        cur.execute("INSERT INTO app_user (name, description, role) "
+                    "VALUES (%s, %s, %s) RETURNING id", (name, description, role))
         return str(cur.fetchone()[0])
 
 
+# ─── service roles (control plane; see SERVICE_ROLES) ────────────────────────
+def count_service_admins(conn) -> int:
+    """How many users hold an admin role (user_manager or superadmin). Zero ⇒ a
+    fresh install with no control plane — the trigger for bootstrap seeding."""
+    with conn.cursor() as cur:
+        cur.execute("SELECT count(*) FROM app_user WHERE role IN "
+                    "('user_manager','superadmin')")
+        return int(cur.fetchone()[0])
+
+
+def count_superadmins(conn) -> int:
+    with conn.cursor() as cur:
+        cur.execute("SELECT count(*) FROM app_user WHERE role='superadmin'")
+        return int(cur.fetchone()[0])
+
+
+def get_role(conn, user_id: str) -> Optional[str]:
+    with conn.cursor() as cur:
+        cur.execute("SELECT role FROM app_user WHERE id=%s", (user_id,))
+        row = cur.fetchone()
+        return row[0] if row else None
+
+
+def set_role(conn, user_id: str, role: str) -> None:
+    """Set a user's service role directly. Callers that lower a superadmin must
+    guard against lockout themselves; :func:`revoke_superadmin` does that."""
+    if role not in SERVICE_ROLES:
+        raise ValueError(f"bad role: {role}")
+    with conn.cursor() as cur:
+        cur.execute("UPDATE app_user SET role=%s WHERE id=%s", (role, user_id))
+        if cur.rowcount == 0:
+            raise SpaceNotFound(f"no such user {user_id}")
+
+
+def grant_superadmin(conn, user_id: str) -> None:
+    set_role(conn, user_id, "superadmin")
+
+
+def revoke_superadmin(conn, user_id: str, *, demote_to: str = "user") -> None:
+    """Drop a user out of the superadmin role. Anti-lockout: refuses to remove
+    the **last** superadmin (recover such a lockout via the grant CLI)."""
+    if demote_to not in SERVICE_ROLES or demote_to == "superadmin":
+        raise ValueError(f"bad demote target: {demote_to}")
+    with conn.cursor() as cur:
+        cur.execute("SELECT role FROM app_user WHERE id=%s", (user_id,))
+        row = cur.fetchone()
+        if row is None:
+            raise SpaceNotFound(f"no such user {user_id}")
+        if row[0] != "superadmin":
+            return                        # nothing to revoke
+        cur.execute("SELECT count(*) FROM app_user WHERE role='superadmin'")
+        if int(cur.fetchone()[0]) <= 1:
+            raise AuthError("cannot revoke the last superadmin")
+        cur.execute("UPDATE app_user SET role=%s WHERE id=%s", (demote_to, user_id))
+
+
 def create_namespace(conn, owner_user_id: str, name: str, *,
                      description: str = "", instruction: str = "") -> str:
     """Create (or return the existing) namespace ``name`` owned by the user."""

{memgres-0.4.1 → memgres-0.5.0}/memgres/mcp_server.py

@@ -35,6 +35,7 @@ except ImportError:  # mcp SDK 1.x
 from . import identity
 from .config import Config, load
 from .embeddings import get_embedder
+from .bootstrap import bootstrap_admin
 from .schema import migrate
 from .store import Store, build_replace
 
@@ -87,6 +88,7 @@ def build_server(cfg: Optional[Config] = None):
                           max_size=cfg.pool_size, open=True)
     with pool.connection() as conn:
         migrate(conn, cfg)
+        bootstrap_admin(conn, cfg)      # seed first service admin once (managed)
     # Start the in-process embed worker (if warranted) and set cfg.embed_dispatch
     # to match, so writes defer to it. Kept alive by its own daemon thread.
     from .embed_worker import wire_server

memgres-0.5.0/memgres/migrations/0008_service_roles.sql

@@ -0,0 +1,27 @@
+-- memgres service roles (schema v9, additive — old readers ignore the column).
+--
+-- A user's *service* role, orthogonal to the per-namespace membership lattice
+-- (read/write/admin) which governs data access WITHIN a space. The service role
+-- governs the CONTROL PLANE — provisioning users/tokens and, for a superadmin,
+-- reaching across namespaces:
+--
+--   user          (default) — owns namespaces, manages access to its OWN spaces
+--                             (via request/approve); no cross-tenant powers.
+--   user_manager            — user + create users + (re)issue tokens on loss.
+--                             Provisioning only; does NOT read others' data nor
+--                             manage other spaces' access.
+--   superadmin              — full root: read/write ANY namespace, grant any
+--                             access, grant/revoke service roles. Principal.is_admin
+--                             derives from this (replaces the anonymous env-root).
+--
+-- Bootstrap seeds the FIRST admin user (see identity.bootstrap_admin); the role
+-- it seeds is MEMGRES_ADMIN_ROLE (default user_manager). Later escalation is the
+-- memgres-grant-superadmin CLI, not this migration.
+ALTER TABLE app_user
+    ADD COLUMN IF NOT EXISTS role text NOT NULL DEFAULT 'user'
+        CHECK (role IN ('user', 'user_manager', 'superadmin'));
+
+-- Find superadmins fast (anti-lockout counts them; bootstrap checks for zero
+-- admins of any kind). Partial index — the admin rows are a tiny minority.
+CREATE INDEX IF NOT EXISTS app_user_role_idx ON app_user (role)
+    WHERE role <> 'user';

{memgres-0.4.1 → memgres-0.5.0}/memgres/schema.py

@@ -18,7 +18,7 @@ from pathlib import Path
 from .config import Config
 
 # The version this build migrates the database TO (the latest migration it carries).
-SCHEMA_VERSION = 8
+SCHEMA_VERSION = 9
 
 # The compatibility FLOOR: the schema version of the most recent backward-
 # INCOMPATIBLE migration — one that changed the shape/semantics old code relied on
@@ -33,6 +33,7 @@ SCHEMA_VERSION = 8
 #   v6 (0005): dropped the whole-body doc vector, moved ranking to chunks → BREAKING.
 #   v7 (0006): added min_reader_version column → additive, floor stays 6.
 #   v8 (0007): added embed_attempts/embed_failed_at → additive, floor stays 6.
+#   v9 (0008): added app_user.role service role → additive, floor stays 6.
 SCHEMA_BREAKING_VERSION = 6
 
 # Dev layout: repo/migrations next to the package. When packaged, migrations are

{memgres-0.4.1 → memgres-0.5.0}/memgres/server.py

@@ -30,6 +30,7 @@ from .config import Config, load
 from .diffing import DiffConflict
 from .embeddings import get_embedder
 from .identity import SpaceNotFound
+from .bootstrap import bootstrap_admin
 from .schema import migrate
 from .store import Conflict, NoParent, NotFound, Store, TooLarge, build_replace
 
@@ -65,6 +66,7 @@ def create_app(cfg: Optional[Config] = None):
     # closures below capture the finalized cfg.
     with psycopg.connect(cfg.database_url or "") as _mc:
         migrate(_mc, cfg)               # idempotent; stamps embed model/dim
+        bootstrap_admin(_mc, cfg)       # seed first service admin once (managed)
     from .embed_worker import wire_server
     _worker, cfg, backend = wire_server(cfg, embedder)
     pool = ConnectionPool(cfg.database_url or "", min_size=1,
@@ -367,20 +369,40 @@ def create_app(cfg: Optional[Config] = None):
             _guard(lambda: _decide_access(conn, tok, req_id, False))
             return {"denied": req_id}
 
-    # ─── admin provisioning (MEMGRES_ADMIN_TOKEN) ───────────────────────────
-    import hmac as _hmac
-
-    def admin(authorization: Optional[str] = Header(None),
-              x_memgres_token: Optional[str] = Header(None)):
+    # ─── admin provisioning (service roles + env break-glass) ───────────────
+    # Provisioning is gated by the caller's service role, resolved from its
+    # token — not by a single shared secret. Two tiers:
+    #   require_manage_users — user_manager, superadmin, or the env break-glass
+    #     root: create users/namespaces, (re)issue & revoke tokens.
+    #   require_superadmin   — superadmin or env root only: cross-tenant access
+    #     (add_member) and granting/revoking the superadmin role.
+    def _admin_principal(authorization, x_memgres_token):
         tok = identity.bearer_token(authorization, x_memgres_token)
-        # constant-time compare; empty admin_token disables admin entirely
-        if not cfg.admin_token or not tok or \
-                not _hmac.compare_digest(tok, cfg.admin_token):
-            raise HTTPException(403, "admin token required")
+        with pool.connection() as conn:
+            try:
+                return identity.resolve(conn, cfg, tok)
+            except identity.AuthError as e:
+                raise HTTPException(403, str(e))
+
+    def require_manage_users(authorization: Optional[str] = Header(None),
+                             x_memgres_token: Optional[str] = Header(None)):
+        p = _admin_principal(authorization, x_memgres_token)
+        if not identity.can_manage_users(p):
+            raise HTTPException(403, "user management requires user_manager or "
+                                     "superadmin")
+        return p
+
+    def require_superadmin(authorization: Optional[str] = Header(None),
+                           x_memgres_token: Optional[str] = Header(None)):
+        p = _admin_principal(authorization, x_memgres_token)
+        if not p.is_admin:                       # superadmin user or env root
+            raise HTTPException(403, "superadmin required")
+        return p
 
     class NewUser(BaseModel):
         name: str = ""
         description: str = ""
+        role: str = "user"
 
     class NewNamespace(BaseModel):
         owner_user_id: str
@@ -399,20 +421,27 @@ def create_app(cfg: Optional[Config] = None):
         user_id: str
         permission: str = "read"
 
-    @app.post("/admin/users", status_code=201, dependencies=[Depends(admin)])
-    def admin_create_user(req: NewUser):
+    @app.post("/admin/users", status_code=201)
+    def admin_create_user(req: NewUser,
+                          p=Depends(require_manage_users)):
+        # minting an admin-role user is itself a superadmin act — a user_manager
+        # must not escalate anyone (nor itself, via a fresh admin user).
+        if req.role != "user" and not p.is_admin:
+            raise HTTPException(403, "granting an admin role requires superadmin")
         with pool.connection() as conn:
             return {"id": _guard(lambda: identity.create_user(
-                conn, req.name, req.description))}
+                conn, req.name, req.description, role=req.role))}
 
-    @app.post("/admin/namespaces", status_code=201, dependencies=[Depends(admin)])
+    @app.post("/admin/namespaces", status_code=201,
+              dependencies=[Depends(require_manage_users)])
     def admin_create_namespace(req: NewNamespace):
         with pool.connection() as conn:
             return {"id": _guard(lambda: identity.create_namespace(
                 conn, req.owner_user_id, req.name, description=req.description,
                 instruction=req.instruction))}
 
-    @app.post("/admin/tokens", status_code=201, dependencies=[Depends(admin)])
+    @app.post("/admin/tokens", status_code=201,
+              dependencies=[Depends(require_manage_users)])
     def admin_issue_token(req: NewToken):
         import datetime as dt
         exp = None
@@ -425,18 +454,20 @@ def create_app(cfg: Optional[Config] = None):
             return {"token": secret, "id": tid,
                     "note": "store this now — it is not recoverable"}
 
-    @app.post("/admin/tokens/{token_id}/revoke", dependencies=[Depends(admin)])
+    @app.post("/admin/tokens/{token_id}/revoke",
+              dependencies=[Depends(require_manage_users)])
     def admin_revoke_token(token_id: str):
         with pool.connection() as conn:
             return {"revoked": _guard(lambda: identity.revoke_token(conn, token_id))}
 
-    @app.get("/admin/users/{user_id}/tokens", dependencies=[Depends(admin)])
+    @app.get("/admin/users/{user_id}/tokens",
+             dependencies=[Depends(require_manage_users)])
     def admin_list_tokens(user_id: str):
         with pool.connection() as conn:
             return _guard(lambda: identity.list_tokens(conn, user_id))
 
     @app.post("/admin/namespaces/{space_id}/members", status_code=201,
-              dependencies=[Depends(admin)])
+              dependencies=[Depends(require_superadmin)])
     def admin_add_member(space_id: str, req: NewMember):
         with pool.connection() as conn:
             _guard(lambda: identity.add_member(
@@ -444,6 +475,31 @@ def create_app(cfg: Optional[Config] = None):
             return {"namespace_id": space_id, "user_id": req.user_id,
                     "permission": req.permission}
 
+    # ─── service-role management (superadmin only) ──────────────────────────
+    @app.post("/admin/users/{user_id}/grant-superadmin",
+              dependencies=[Depends(require_superadmin)])
+    def admin_grant_superadmin(user_id: str):
+        with pool.connection() as conn:
+            _guard(lambda: identity.grant_superadmin(conn, user_id))
+            return {"user_id": user_id, "role": "superadmin"}
+
+    class RevokeSuper(BaseModel):
+        demote_to: str = "user"
+
+    @app.post("/admin/users/{user_id}/revoke-superadmin",
+              dependencies=[Depends(require_superadmin)])
+    def admin_revoke_superadmin(user_id: str, req: RevokeSuper):
+        with pool.connection() as conn:
+            try:
+                identity.revoke_superadmin(conn, user_id, demote_to=req.demote_to)
+            except identity.AuthError as e:      # anti-lockout: last superadmin
+                raise HTTPException(409, str(e))
+            except (identity.SpaceNotFound, KeyError):
+                raise HTTPException(404, "no such user")
+            except ValueError as e:
+                raise HTTPException(422, str(e))
+            return {"user_id": user_id, "role": req.demote_to}
+
     return app
 
 

{memgres-0.4.1 → memgres-0.5.0}/memgres.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.4.1
+Version: 0.5.0
 Summary: Drop-in memory for AI agents: one Postgres, lexical + semantic recall, diff-versioned history, GDPR-erasable.
 Author: mozgsml
 License-Expression: MIT

{memgres-0.4.1 → memgres-0.5.0}/memgres.egg-info/SOURCES.txt

@@ -3,7 +3,9 @@ README.md
 pyproject.toml
 memgres/__init__.py
 memgres/_version.py
+memgres/admin_cli.py
 memgres/blame.py
+memgres/bootstrap.py
 memgres/config.py
 memgres/diffing.py
 memgres/embed_worker.py
@@ -32,6 +34,7 @@ memgres/migrations/0004_title.sql
 memgres/migrations/0005_chunk_index.sql
 memgres/migrations/0006_reader_floor.sql
 memgres/migrations/0007_embed_retry.sql
+memgres/migrations/0008_service_roles.sql
 memgres/vector/__init__.py
 memgres/vector/base.py
 memgres/vector/pgvector.py
@@ -53,6 +56,7 @@ tests/test_migration_upgrade.py
 tests/test_qdrant_ca.py
 tests/test_qdrant_integration.py
 tests/test_replace_build.py
+tests/test_roles_bootstrap.py
 tests/test_search_integration.py
 tests/test_security_integration.py
 tests/test_segments.py

{memgres-0.4.1 → memgres-0.5.0}/memgres.egg-info/entry_points.txt

@@ -1,4 +1,5 @@
 [console_scripts]
+memgres-grant-superadmin = memgres.admin_cli:main
 memgres-mcp = memgres.mcp_server:main
 memgres-reembed = memgres.reembed:main
 memgres-server = memgres.server:main

{memgres-0.4.1 → memgres-0.5.0}/pyproject.toml

@@ -40,6 +40,7 @@ memgres-server = "memgres.server:main"
 memgres-mcp = "memgres.mcp_server:main"
 memgres-worker = "memgres.worker:main"
 memgres-reembed = "memgres.reembed:main"
+memgres-grant-superadmin = "memgres.admin_cli:main"
 
 [build-system]
 requires = ["setuptools>=68"]

memgres-0.5.0/tests/test_roles_bootstrap.py

@@ -0,0 +1,236 @@
+"""Service roles + first-admin bootstrap, against a live Postgres.
+
+Covers the seed (env / token-file read-or-create), the zero-admins invariant and
+idempotency, attribution of a seeded token to its real user, the superadmin
+data-root vs. a user_manager's lack of cross-tenant access, grant/revoke with
+anti-lockout, and the REST role gating.
+"""
+
+import os
+import stat
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import pytest  # noqa: E402
+
+psycopg = pytest.importorskip("psycopg")
+
+from memgres import bootstrap as bs  # noqa: E402
+from memgres import identity  # noqa: E402
+from memgres.config import load  # noqa: E402
+from memgres.schema import migrate  # noqa: E402
+
+DSN = os.environ.get("MEMGRES_TEST_DSN",
+                     "postgresql://memgres:memgres@localhost:55432/memgres")
+
+
+def _reachable() -> bool:
+    try:
+        psycopg.connect(DSN, connect_timeout=2).close()
+        return True
+    except Exception:
+        return False
+
+
+pytestmark = pytest.mark.skipif(not _reachable(), reason="no test Postgres")
+
+
+@pytest.fixture
+def env(monkeypatch):
+    """Fresh schema + a clean MEMGRES_ env pointed at the test DB (managed)."""
+    with psycopg.connect(DSN, autocommit=True) as c, c.cursor() as cur:
+        cur.execute("DROP SCHEMA public CASCADE; CREATE SCHEMA public;")
+    for k in list(os.environ):
+        if k.startswith("MEMGRES_"):
+            monkeypatch.delenv(k, raising=False)
+    monkeypatch.setenv("MEMGRES_DATABASE_URL", DSN)
+    monkeypatch.setenv("MEMGRES_EMBED_PROVIDER", "none")
+    monkeypatch.setenv("MEMGRES_KEY_MODE", "managed")
+    return monkeypatch
+
+
+def _conn():
+    return psycopg.connect(DSN, autocommit=True)
+
+
+# ─── bootstrap seeding ───────────────────────────────────────────────────────
+def test_seeds_user_manager_by_default_and_is_idempotent(env):
+    tok = identity.new_token()
+    env.setenv("MEMGRES_ADMIN_TOKEN", tok)
+    cfg = load()
+    with _conn() as conn:
+        migrate(conn, cfg)
+        uid = bs.bootstrap_admin(conn, cfg)
+        assert uid and identity.count_service_admins(conn) == 1
+        assert identity.get_role(conn, uid) == "user_manager"
+
+        # the env token now resolves to that REAL user — attributed, not anon root
+        p = identity.resolve(conn, cfg, tok)
+        assert p.user_id == uid and p.role == "user_manager"
+        assert p.is_admin is False and identity.can_manage_users(p)
+
+        # inert on a second call, and even if the env token changes
+        assert bs.bootstrap_admin(conn, cfg) is None
+        env.setenv("MEMGRES_ADMIN_TOKEN", identity.new_token())
+        assert bs.bootstrap_admin(conn, load()) is None
+        assert identity.count_service_admins(conn) == 1
+
+
+def test_seeds_superadmin_with_full_data_root(env):
+    env.setenv("MEMGRES_ADMIN_ROLE", "superadmin")
+    tok = identity.new_token()
+    env.setenv("MEMGRES_ADMIN_TOKEN", tok)
+    cfg = load()
+    with _conn() as conn:
+        migrate(conn, cfg)
+        bs.bootstrap_admin(conn, cfg)
+        # a separate tenant with a private namespace
+        other = identity.create_user(conn, "tenant")
+        ns = identity.create_namespace(conn, other, "private")
+
+        p = identity.resolve(conn, cfg, tok)
+        assert p.is_admin and p.role == "superadmin"
+        # reaches ANY namespace by id, as admin (capped by the token ceiling)
+        nsid, perm = identity.resolve_space(conn, p, space_id=ns)
+        assert nsid == ns and perm == "admin"
+
+
+def test_user_manager_has_no_cross_tenant_data_access(env):
+    tok = identity.new_token()               # default role: user_manager
+    env.setenv("MEMGRES_ADMIN_TOKEN", tok)
+    cfg = load()
+    with _conn() as conn:
+        migrate(conn, cfg)
+        bs.bootstrap_admin(conn, cfg)
+        other = identity.create_user(conn, "tenant")
+        ns = identity.create_namespace(conn, other, "private")
+
+        p = identity.resolve(conn, cfg, tok)
+        assert identity.can_manage_users(p) and not p.is_admin
+        with pytest.raises(identity.SpaceNotFound):
+            identity.resolve_space(conn, p, space_id=ns)
+
+
+def test_token_file_is_generated_0600_when_absent(env, tmp_path):
+    path = tmp_path / "initial_admin_token"
+    env.setenv("MEMGRES_ADMIN_TOKEN_FILE", str(path))
+    cfg = load()
+    with _conn() as conn:
+        migrate(conn, cfg)
+        uid = bs.bootstrap_admin(conn, cfg)
+        assert uid
+        secret = path.read_text().strip()
+        assert identity.valid_format(secret)
+        assert stat.S_IMODE(os.stat(path).st_mode) == 0o600
+        assert identity.resolve(conn, cfg, secret).user_id == uid
+
+
+def test_token_file_existing_secret_is_used(env, tmp_path):
+    tok = identity.new_token()
+    path = tmp_path / "initial_admin_token"
+    path.write_text(tok + "\n")
+    env.setenv("MEMGRES_ADMIN_TOKEN_FILE", str(path))
+    cfg = load()
+    with _conn() as conn:
+        migrate(conn, cfg)
+        uid = bs.bootstrap_admin(conn, cfg)
+        assert identity.resolve(conn, cfg, tok).user_id == uid
+        assert path.read_text().strip() == tok        # left untouched
+
+
+def test_non_mgk_env_token_skips_seed_but_still_works_as_root(env):
+    env.setenv("MEMGRES_ADMIN_TOKEN", "legacy-plain-secret")
+    cfg = load()
+    with _conn() as conn:
+        migrate(conn, cfg)
+        assert bs.bootstrap_admin(conn, cfg) is None
+        assert identity.count_service_admins(conn) == 0
+        p = identity.resolve(conn, cfg, "legacy-plain-secret")
+        assert p.is_admin and p.user_id is None       # anonymous break-glass
+
+
+@pytest.mark.parametrize("mode", ["single", "open"])
+def test_bootstrap_noop_outside_managed(env, mode):
+    env.setenv("MEMGRES_KEY_MODE", mode)
+    env.setenv("MEMGRES_ADMIN_TOKEN", identity.new_token())
+    cfg = load()
+    with _conn() as conn:
+        migrate(conn, cfg)
+        assert bs.bootstrap_admin(conn, cfg) is None
+        assert identity.count_service_admins(conn) == 0
+
+
+# ─── role management + anti-lockout ──────────────────────────────────────────
+def test_grant_revoke_superadmin_anti_lockout(env):
+    env.setenv("MEMGRES_ADMIN_ROLE", "superadmin")
+    tok = identity.new_token()
+    env.setenv("MEMGRES_ADMIN_TOKEN", tok)
+    cfg = load()
+    with _conn() as conn:
+        migrate(conn, cfg)
+        a = bs.bootstrap_admin(conn, cfg)
+
+        # the only superadmin can't be revoked
+        with pytest.raises(identity.AuthError):
+            identity.revoke_superadmin(conn, a)
+
+        b = identity.create_user(conn, "b")
+        identity.grant_superadmin(conn, b)
+        assert identity.count_superadmins(conn) == 2
+
+        identity.revoke_superadmin(conn, a)              # now allowed
+        assert identity.get_role(conn, a) == "user"
+        assert identity.count_superadmins(conn) == 1
+
+        with pytest.raises(identity.AuthError):          # b is the last one again
+            identity.revoke_superadmin(conn, b)
+
+
+# ─── REST role gating ────────────────────────────────────────────────────────
+@pytest.fixture
+def managed_client(env):
+    pytest.importorskip("fastapi")
+    pytest.importorskip("psycopg_pool")
+    from fastapi.testclient import TestClient
+
+    from memgres.server import create_app
+
+    env.setenv("MEMGRES_ADMIN_ROLE", "superadmin")
+    tok = identity.new_token()
+    env.setenv("MEMGRES_ADMIN_TOKEN", tok)
+    app = create_app(load())                              # bootstrap seeds at startup
+    with TestClient(app) as c:
+        yield c, tok
+
+
+def test_rest_role_gating(managed_client):
+    c, admin_tok = managed_client
+    H = {"Authorization": f"Bearer {admin_tok}"}
+
+    # superadmin mints a user_manager and a token for it
+    mgr = c.post("/admin/users", json={"name": "mgr", "role": "user_manager"},
+                 headers=H).json()["id"]
+    mtok = c.post("/admin/tokens", json={"user_id": mgr, "permission": "admin"},
+                  headers=H).json()["token"]
+    Hm = {"Authorization": f"Bearer {mtok}"}
+
+    # a user_manager may create plain users …
+    assert c.post("/admin/users", json={"name": "u"}, headers=Hm).status_code == 201
+    # … but may NOT mint an admin-role user (no privilege escalation) …
+    assert c.post("/admin/users", json={"name": "x", "role": "superadmin"},
+                  headers=Hm).status_code == 403
+    # … nor grant the superadmin role.
+    assert c.post(f"/admin/users/{mgr}/grant-superadmin",
+                  headers=Hm).status_code == 403
+
+    # a superadmin can promote, then anti-lockout is enforced on the last one
+    assert c.post(f"/admin/users/{mgr}/grant-superadmin",
+                  headers=H).status_code == 200
+    # demote the manager back (two supers now → allowed)
+    assert c.post(f"/admin/users/{mgr}/revoke-superadmin", json={},
+                  headers=H).status_code == 200
+
+    # no auth at all → 403
+    assert c.post("/admin/users", json={"name": "z"}).status_code == 403