memgres 0.8.0__tar.gz → 0.11.0__tar.gz

{memgres-0.8.0 → memgres-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.8.0
+Version: 0.11.0
 Summary: Drop-in memory for AI agents: one Postgres, lexical + semantic recall, diff-versioned history, GDPR-erasable.
 Author: mozgsml
 License-Expression: MIT
@@ -214,6 +214,7 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `MEMGRES_KEY_MODE` | `single` | `single` (no auth, one space) · `open` (bring-your-own token, self-registers) · `managed` (admin-provisioned). See [docs/TENANCY.md](docs/TENANCY.md) |
 | `MEMGRES_ADMIN_TOKEN` | — | global admin bearer for provisioning (managed mode) |
 | `MEMGRES_TOKEN` | — | default token used when a call passes none (single-tenant endpoints) |
+| `MEMGRES_TOKEN_SINK` | — | absolute directory a minted secret is **written to** (`<token-id>.token`, `0600`) instead of being returned. Set it when provisioning is done by an agent — a secret in a tool result is a secret in a transcript. See [docs/TENANCY.md](docs/TENANCY.md) |
 | `MEMGRES_TREE` | `true` | `ltree` path column + GiST index (fast subtree select) |
 | `MEMGRES_REQUIRE_TITLE` | `true` | `true` = a write that stores content must supply `title`. Captions are what name a memory in results and what title-weighted ranking weighs; `move`/`retag` are exempt (they store no content) |
 | `MEMGRES_REQUIRE_PARENT` | `false` | `true` = a node's parent path must already exist |

{memgres-0.8.0 → memgres-0.11.0}/README.md

@@ -178,6 +178,7 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `MEMGRES_KEY_MODE` | `single` | `single` (no auth, one space) · `open` (bring-your-own token, self-registers) · `managed` (admin-provisioned). See [docs/TENANCY.md](docs/TENANCY.md) |
 | `MEMGRES_ADMIN_TOKEN` | — | global admin bearer for provisioning (managed mode) |
 | `MEMGRES_TOKEN` | — | default token used when a call passes none (single-tenant endpoints) |
+| `MEMGRES_TOKEN_SINK` | — | absolute directory a minted secret is **written to** (`<token-id>.token`, `0600`) instead of being returned. Set it when provisioning is done by an agent — a secret in a tool result is a secret in a transcript. See [docs/TENANCY.md](docs/TENANCY.md) |
 | `MEMGRES_TREE` | `true` | `ltree` path column + GiST index (fast subtree select) |
 | `MEMGRES_REQUIRE_TITLE` | `true` | `true` = a write that stores content must supply `title`. Captions are what name a memory in results and what title-weighted ranking weighs; `move`/`retag` are exempt (they store no content) |
 | `MEMGRES_REQUIRE_PARENT` | `false` | `true` = a node's parent path must already exist |

{memgres-0.8.0 → memgres-0.11.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.8.0"
+__version__ = "0.11.0"

{memgres-0.8.0 → memgres-0.11.0}/memgres/admin.py

@@ -353,7 +353,8 @@ def create_namespace(conn, p: Principal, *, owner_user_id: str, name: str,
 
 def edit_namespace(conn, p: Principal, *, namespace_id: str,
                    description: Optional[str] = None,
-                   instruction: Optional[str] = None) -> dict:
+                   instruction: Optional[str] = None,
+                   name: Optional[str] = None) -> dict:
     """Amend a namespace's description or routing instruction.
 
     `create_namespace` is an idempotent upsert that ignores conflicts, so
@@ -361,21 +362,106 @@ def edit_namespace(conn, p: Principal, *, namespace_id: str,
     the instruction agents read to choose a namespace could not be fixed through
     any door at all.
     """
-    require_namespace_admin(conn, p, namespace_id)
+    # Description and instruction are administration; the NAME is closer to
+    # disposal — renaming out from under an owner breaks every by-name call they
+    # and every member make, and an admin member was given authority over the
+    # contents, not over how the namespace is addressed.
+    if name is not None:
+        require_namespace_owner(conn, p, namespace_id)
+    else:
+        require_namespace_admin(conn, p, namespace_id)
     identity.edit_namespace(conn, namespace_id, description=description,
-                            instruction=instruction)
-    return {"namespace_id": namespace_id}
+                            instruction=instruction, name=name)
+    out = {"namespace_id": namespace_id}
+    if name is not None:
+        out["name"] = name
+        out["warning"] = ("renamed — anyone addressing it by the old name now "
+                          "gets 'no such namespace'. Ids and aliases still work")
+    return out
+
+
+def require_namespace_owner(conn, p: Principal, namespace_id: str) -> None:
+    """Owner-or-superadmin, a tier narrower than `require_namespace_admin`.
+
+    For the acts that dispose of the namespace itself rather than work inside
+    it. An admin MEMBER was given authority over the contents; giving away
+    somebody else's namespace is not part of that, and the difference only
+    matters here — which is why this is its own check rather than a flag.
+    """
+    require_namespace_admin(conn, p, namespace_id)      # ceiling + scope + exists
+    # A namespace-pinned token is issued to WORK in that namespace; disposing of
+    # it is a step beyond what the pin implies, and the deployment-wide acts all
+    # demand an unscoped credential for the same reason.
+    if p.scope_namespace_id is not None:
+        raise Forbidden("this act needs an unscoped admin credential")
+    if p.is_admin:
+        return
+    if identity.namespace_owner(conn, namespace_id) != p.user_id:
+        raise Forbidden("only the owner (or a superadmin) may do this")
 
 
 def add_member(conn, p: Principal, *, namespace_id: str, user_id: str,
                permission: str = "read") -> dict:
-    """Share a namespace with another user — cross-tenant, so superadmin only."""
-    require_superadmin(p)
+    """Share a namespace with another user.
+
+    Authorized per-NAMESPACE, not deployment-wide. It used to demand superadmin,
+    on the reasoning that sharing reaches across tenants — but the thing being
+    shared is the caller's OWN namespace, and requiring the deployment's root
+    for that made "let a colleague into my cabinet" an operator ticket. What it
+    still demands is an admin-ceiling credential for that namespace, so a
+    read-only or differently-scoped token cannot hand out access.
+    """
+    require_namespace_admin(conn, p, namespace_id)
     identity.add_member(conn, namespace_id, user_id, permission)
     return {"namespace_id": namespace_id, "user_id": user_id,
             "permission": permission}
 
 
+def remove_member(conn, p: Principal, *, namespace_id: str, user_id: str) -> dict:
+    """Un-share a namespace. `removed: false` means they were not a member.
+
+    The other half of `add_member`, and its absence was the sharpest gap in this
+    control plane: access could be granted and never taken back except by
+    revoking every token the person held, which cuts them off from everything
+    rather than from this.
+    """
+    require_namespace_admin(conn, p, namespace_id)
+    return {"namespace_id": namespace_id, "user_id": user_id,
+            "removed": identity.remove_member(conn, namespace_id, user_id)}
+
+
+def transfer_namespace(conn, p: Principal, *, namespace_id: str,
+                       new_owner_user_id: str,
+                       keep_previous_owner: Optional[str] = "admin") -> dict:
+    """Hand a namespace to another account — owner or superadmin.
+
+    The outgoing owner stays behind as an `admin` member unless
+    `keep_previous_owner` is null. Defaulting to keeping them is the safer
+    footing: the alternative is a single call that removes the caller from a
+    namespace whose contents they may be the only one who knows.
+    """
+    require_namespace_owner(conn, p, namespace_id)
+    return identity.transfer_namespace(
+        conn, namespace_id, new_owner_user_id,
+        keep_previous_owner=keep_previous_owner)
+
+
+def set_disabled(conn, p: Principal, *, user_id: str, disabled: bool) -> dict:
+    """Switch an account off, or back on. Every token it holds stops at once.
+
+    Offboarding as ONE act. Doing it by revoking tokens one at a time is a loop
+    that has to be complete to be correct, and nothing stops a new token being
+    issued afterwards. Reversible and destructive of nothing — authorship,
+    namespaces and memberships all survive, which is what makes it usable for
+    "gone for now" as well as "gone".
+    """
+    require_manage_users(p)
+    _require_target_is_plain_user(conn, p, user_id,
+                                  "disabling an account" if disabled
+                                  else "re-enabling an account")
+    return identity.set_disabled(conn, user_id, disabled)
+
+
 def list_namespaces(conn, p: Principal, *, owner_user_id: Optional[str] = None,
                     limit: Optional[int] = None, offset: int = 0) -> List[dict]:
     """Deployment-wide namespace inventory.
@@ -407,24 +493,149 @@ def list_spaces(conn, p: Principal) -> List[dict]:
 
 # ─── tokens ──────────────────────────────────────────────────────────────────
 
+def _unreachable_warning(conn, user_id: str,
+                         namespace_id: Optional[str]) -> Optional[str]:
+    """Warn when a credential is about to be scoped to a namespace its owner
+    cannot reach.
+
+    Scoping is not granting: reach comes from ownership or membership, and a
+    token pinned to a namespace the account is not in is perfectly valid and
+    reaches nothing. The person enrols, everything answers "no namespace", and
+    it reads as a broken server rather than an unfinished provisioning. A
+    warning rather than a refusal, because issuing the credential first and
+    adding the membership after is a legitimate order.
+    """
+    if not namespace_id:
+        return None
+    if identity.reaches(conn, user_id, namespace_id) is not None:
+        return None
+    return ("that user cannot reach this namespace yet, so the token will be "
+            "valid and see NOTHING — add them with memory_admin_add_member "
+            "(or hand the namespace over) before they try to use it")
+
+
 def issue_token(conn, p: Principal, *, user_id: str,
                 namespace_id: Optional[str] = None, permission: str = "write",
-                label: str = "", expires_days: Optional[int] = None) -> dict:
+                label: str = "", expires_days: Optional[int] = None,
+                sink_dir: str = "", defer_delivery: bool = False) -> dict:
     """Mint a token for `user_id`. The secret is returned once and never again.
 
     `expires_days` rather than a timestamp: both doors were converting the same
     way, so the conversion belongs here.
+
+    `sink_dir` (the deployment's `MEMGRES_TOKEN_SINK`) diverts the secret to a
+    0600 file on the server and returns its path instead — see
+    `identity.stash_secret`. The caller then never holds the secret at all,
+    which is the point when the caller is an agent.
     """
     require_manage_users(p)
     _require_target_is_plain_user(conn, p, user_id, "issuing a token")
     expires_at = None
     if expires_days:
         expires_at = dt.datetime.now(dt.timezone.utc) + dt.timedelta(days=expires_days)
+    warning = _unreachable_warning(conn, user_id, namespace_id)
     secret, tid = identity.issue_token(conn, user_id, namespace_id=namespace_id,
                                        permission=permission, label=label,
                                        expires_at=expires_at)
-    return {"token": secret, "id": tid,
-            "note": "store this now — it is not recoverable"}
+    if defer_delivery:
+        # The caller will commit and THEN write the file. Writing it inside the
+        # transaction leaves a 0600 file holding a live-looking secret for a
+        # token that a rollback removed — the CLI already delivers outside its
+        # transaction for exactly this reason, and the doors did not.
+        return {"secret": secret, "id": tid, "warning": warning}
+    out = deliver_secret(secret, tid, sink_dir)
+    if warning:
+        out["warning"] = warning
+    return out
+
+
+def deliver_key(out: dict, sink_dir: str) -> dict:
+    """Apply the deployment's delivery policy to a freshly minted ENROLLMENT KEY.
+
+    The 0.9.0 wave took the token out of the reply and left the key in it — but
+    a key is a bearer credential for as long as it lives, and whoever reads it
+    first gets the account it names. An operator who set a sink said "secrets do
+    not come back in replies", and meant this one too.
+    """
+    if not sink_dir or "key" not in out:
+        return out
+    key = out.pop("key")
+    out["path"] = identity.stash_secret(sink_dir, out["id"], key,
+                                        suffix=".key")
+    out["delivered"] = "file"
+    out["exposed"] = False
+    out["note"] = ("the key was written to that file on the server and "
+                   "deliberately NOT returned here — read it there and hand it "
+                   "to its owner")
+    return out
+
+
+def deliver_secret(secret: str, token_id: str, sink_dir: str) -> dict:
+    """The reply for a freshly minted token: the secret itself, or — when the
+    deployment set a sink — only where it was put. One function so both minting
+    doors (this module and the MCP self-service tool) cannot disagree about
+    whether a secret is allowed into a response body."""
+    if sink_dir:
+        path = identity.stash_secret(sink_dir, token_id, secret)
+        return {"id": token_id, "delivered": "file", "path": path,
+                "exposed": False,
+                "note": "the secret was written to that file on the server and "
+                        "deliberately NOT returned here — read it there"}
+    return {"token": secret, "id": token_id, "exposed": True,
+            "note": "store this now — it is not recoverable. This secret was "
+                    "returned in a reply: if that reply reached an LLM, treat "
+                    "the token as exposed and rotate it once delivered. Set "
+                    "MEMGRES_TOKEN_SINK to stop returning secrets at all."}
+
+
+def create_enrollment(conn, p: Principal, *, user_id: str,
+                      namespace_id: Optional[str] = None,
+                      permission: str = "write", label: str = "",
+                      expires_minutes: Optional[int] = None) -> dict:
+    """Mint a one-time key that lets `user_id` bind a token THEY generate.
+
+    Provisioning-tier, and gated exactly like `issue_token`, because it grants
+    the same thing by another route: whoever redeems it ends up holding a
+    credential for that account. What it does not do is put a secret anywhere —
+    the key is worthless after one use and after `expires_minutes`, and the
+    token itself is created on the far side and never travels.
+    """
+    require_manage_users(p)
+    _require_target_is_plain_user(conn, p, user_id, "issuing an enrollment key")
+    kw = {} if expires_minutes is None else {"expires_minutes": expires_minutes}
+    out = identity.create_enrollment(
+        conn, user_id, namespace_id=namespace_id, permission=permission,
+        label=label, created_by=p.user_id, **kw)
+    out["note"] = ("give this key to its owner over any channel you would use "
+                   "for a meeting link — it is single-use and short-lived. They "
+                   "generate their own token, put it in their client's config, "
+                   "and call memory_enroll with this key.")
+    warning = _unreachable_warning(conn, user_id, namespace_id)
+    if warning:
+        out["warning"] = warning
+    return out
+
+
+def list_enrollments(conn, p: Principal, *,
+                     user_id: Optional[str] = None) -> List[dict]:
+    """Enrollment keys and what became of them — metadata only, never a key."""
+    require_manage_users(p)
+    if user_id is not None:
+        _require_target_is_plain_user(conn, p, user_id, "listing enrollment keys")
+        return identity.list_enrollments(conn, user_id=user_id)
+    # Unfiltered, the listing handed a user_manager the credential timeline of
+    # the accounts ABOVE it — `list_tokens` refuses exactly that. The guard has
+    # to apply to the shape without a target too, or it is only a speed bump.
+    return identity.list_enrollments(conn, plain_users_only=not p.is_admin)
+
+
+def revoke_enrollment(conn, p: Principal, *, enrollment_id: str) -> bool:
+    """Kill an unredeemed key. False if it was already spent, revoked or absent."""
+    require_manage_users(p)
+    _require_target_is_plain_user(conn, p,
+                                  identity.enrollment_owner(conn, enrollment_id),
+                                  "revoking an enrollment key")
+    return identity.revoke_enrollment(conn, enrollment_id)
 
 
 def revoke_token(conn, p: Principal, *, token_id: str) -> bool:
@@ -524,11 +735,26 @@ def request_access(conn, p: Principal, *, namespace_id: str,
     """
     if p.user_id is None:
         raise identity.AuthError("this token has no owning user")
+    # You may not ask for more than this credential could exercise if granted.
+    # A read-only agent token filing an `admin` request is the input half of an
+    # over-grant: the approver sees a plausible ask and the account keeps the
+    # membership long after that token is gone.
+    permission = identity.perm_min(permission, p.permission)
     perm = identity.reaches(conn, p.user_id, namespace_id)
     if perm is not None:
         return {"status": "already_reachable", "permission": perm}
     identity.request_access(conn, p.user_id, namespace_id, permission)
-    return {"status": "submitted"}
+    # What is actually pending, which is not always what was asked: a request
+    # you already hold may be lowered but not raised, and a read-only credential
+    # cannot ask beyond its ceiling. Saying so beats a receipt that agrees with
+    # you and a grant that does not.
+    with conn.cursor() as cur:
+        cur.execute("SELECT requested_permission FROM access_request WHERE "
+                    "requester_user_id=%s AND namespace_id=%s",
+                    (p.user_id, identity._as_uuid(namespace_id)))
+        row = cur.fetchone()
+    return {"status": "submitted",
+            "permission": row[0] if row else permission}
 
 
 def list_requests(conn, p: Principal, *, namespace_id: str) -> List[dict]:
@@ -537,16 +763,32 @@ def list_requests(conn, p: Principal, *, namespace_id: str) -> List[dict]:
     return identity.list_requests(conn, namespace_id)
 
 
-def decide_access(conn, p: Principal, *, request_id: str, approve: bool) -> None:
-    """Approve or deny a request, authorized against the namespace it targets."""
+def decide_access(conn, p: Principal, *, request_id: str, approve: bool,
+                  expect_permission: Optional[str] = None) -> None:
+    """Approve or deny a request, authorized against the namespace it targets.
+
+    `expect_permission` is the permission the approver SAW in `list_requests`.
+    Pass it: without it, approval grants whatever the row says when it is read,
+    and a requester can raise their own pending ask between the listing and the
+    decision. `request_access` no longer amends a pending request, so this is
+    the second lock on the same door rather than the only one.
+
+    Both "no such request" and "a request you may not decide" answer the same
+    way, for the same reason `request_access` does: which uuids are real is not
+    something a refusal should confirm.
+    """
     with conn.cursor() as cur:
         cur.execute("SELECT namespace_id FROM access_request WHERE id=%s",
                     (request_id,))
         row = cur.fetchone()
     if row is None:
         raise identity.SpaceNotFound("no such request")
-    require_namespace_admin(conn, p, str(row[0]))
+    try:
+        require_namespace_admin(conn, p, str(row[0]))
+    except (Forbidden, identity.SpaceNotFound):
+        raise identity.SpaceNotFound("no such request") from None
     if approve:
-        identity.approve_request(conn, request_id)
+        identity.approve_request(conn, request_id,
+                                 expect_permission=expect_permission)
     else:
         identity.deny_request(conn, request_id)

{memgres-0.8.0 → memgres-0.11.0}/memgres/bootstrap.py

@@ -44,22 +44,26 @@ 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."""
+    # O_NOFOLLOW on the READ as well: whoever can plant a symlink here would
+    # otherwise CHOOSE the deployment's bootstrap admin token by pointing this
+    # at a file they wrote. Reading through it is the more dangerous half.
     try:
-        with open(path, "r", encoding="utf-8") as f:
+        fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)
+        with os.fdopen(fd, "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}")
+        raise BootstrapError(
+            f"cannot read MEMGRES_ADMIN_TOKEN_FILE {path!r}: {e}"
+            + (" (a symlink is refused here on purpose)"
+               if os.path.islink(path) else ""))
     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
+        identity.write_private(path, secret + "\n")
     except OSError as e:
         raise BootstrapError(f"cannot write MEMGRES_ADMIN_TOKEN_FILE {path!r}: {e}")
     return secret, path

{memgres-0.8.0 → memgres-0.11.0}/memgres/config.py

@@ -70,6 +70,12 @@ class Config:
                                  # path only. Mutually exclusive with admin_token.
     admin_role: str              # role the bootstrap admin is seeded with:
                                  # user_manager (default) | superadmin
+    token_sink: str              # directory a freshly minted token secret is
+                                 # WRITTEN to (0600) instead of being returned in
+                                 # the reply. Set it when the caller is an agent:
+                                 # a secret in a tool result is a secret in a chat
+                                 # transcript, and every transcript is copied,
+                                 # summarized and stored. Empty = return it.
     # organization
     tree_enabled: bool           # ltree path column + GiST index for fast subtree selection
     require_title: bool          # True = a write that stores CONTENT must caption it
@@ -182,6 +188,11 @@ class Config:
             raise ValueError(
                 "MEMGRES_ADMIN_ROLE must be user_manager or superadmin "
                 f"(got {self.admin_role!r})")
+        if self.token_sink and not os.path.isabs(self.token_sink):
+            # A relative sink resolves against each process's CWD, so the server
+            # and the CLI would write the same operator's secrets to different
+            # directories — and neither would say so.
+            raise ValueError("MEMGRES_TOKEN_SINK must be an absolute path")
         if self.admin_token and self.admin_token_file:
             raise ValueError(
                 "set only one of MEMGRES_ADMIN_TOKEN / MEMGRES_ADMIN_TOKEN_FILE")
@@ -208,6 +219,7 @@ def load() -> Config:
         admin_token=_str("MEMGRES_ADMIN_TOKEN", ""),
         admin_token_file=_str("MEMGRES_ADMIN_TOKEN_FILE", ""),
         admin_role=_str("MEMGRES_ADMIN_ROLE", "user_manager"),
+        token_sink=_str("MEMGRES_TOKEN_SINK", ""),
         tree_enabled=_bool("MEMGRES_TREE", True),
         require_title=_bool("MEMGRES_REQUIRE_TITLE", True),
         require_parent=_bool("MEMGRES_REQUIRE_PARENT", False),