memgres 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.4.0
+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.0 → 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.0"
+__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.0 → 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.0 → 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.0 → memgres-0.5.0}/memgres/mcp_server.py

@@ -35,8 +35,9 @@ 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
+from .store import Store, build_replace
 
 
 # The MCP `initialize` response carries a server-side `instructions` string; a
@@ -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
@@ -180,9 +182,7 @@ def build_server(cfg: Optional[Config] = None):
         curated caption (set whole, searchable via `memory_find`); `source`/`reason`
         record provenance. `space` picks one of your namespaces by name (`space_id`
         for a shared one); omit both to use your default."""
-        replace = None
-        if replace_old is not None or replace_new is not None:
-            replace = (replace_old or "", replace_new or "")
+        replace = build_replace(replace_old, replace_new)
         with pool.connection() as conn:
             return _mem(_store(conn).write(
                 _token(ctx, token), id=id or None, body=body, diff=diff,

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.0 → 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