memgres 0.7.2__tar.gz → 0.9.0__tar.gz

{memgres-0.7.2 → memgres-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.7.2
+Version: 0.9.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 |
@@ -351,11 +352,12 @@ secret and can't switch user):
       "headers": { "Authorization": "Bearer mgk_…" } } } }
   ```
 
-A *namespace-scoped* token also locks the agent to one space. Only a genuinely
-multi-tenant endpoint (open/managed, **no** pinned token) exposes a `token` tool
-argument for the model to supply — force it either way with
-`MEMGRES_MCP_TOKEN_ARG=on|off`. Single mode needs no token. Full model in
-[docs/TENANCY.md](docs/TENANCY.md).
+A *namespace-scoped* token also locks the agent to one space. **No tool takes a
+`token` argument**: a deployment names its caller in configuration — an
+`Authorization` header on http, `MEMGRES_TOKEN` in the env of a stdio server's
+client entry — and both transports can carry one, so an argument could only ever
+name an identity the deployment did not choose. Single mode needs no token at
+all. Full model in [docs/TENANCY.md](docs/TENANCY.md).
 
 **B. From your own agent code** — your loop calls the HTTP API or the `Store`
 library after the model produces text (see the examples above). Use this when you

{memgres-0.7.2 → memgres-0.9.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 |
@@ -315,11 +316,12 @@ secret and can't switch user):
       "headers": { "Authorization": "Bearer mgk_…" } } } }
   ```
 
-A *namespace-scoped* token also locks the agent to one space. Only a genuinely
-multi-tenant endpoint (open/managed, **no** pinned token) exposes a `token` tool
-argument for the model to supply — force it either way with
-`MEMGRES_MCP_TOKEN_ARG=on|off`. Single mode needs no token. Full model in
-[docs/TENANCY.md](docs/TENANCY.md).
+A *namespace-scoped* token also locks the agent to one space. **No tool takes a
+`token` argument**: a deployment names its caller in configuration — an
+`Authorization` header on http, `MEMGRES_TOKEN` in the env of a stdio server's
+client entry — and both transports can carry one, so an argument could only ever
+name an identity the deployment did not choose. Single mode needs no token at
+all. Full model in [docs/TENANCY.md](docs/TENANCY.md).
 
 **B. From your own agent code** — your loop calls the HTTP API or the `Store`
 library after the model produces text (see the examples above). Use this when you

{memgres-0.7.2 → memgres-0.9.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.7.2"
+__version__ = "0.9.0"

{memgres-0.7.2 → memgres-0.9.0}/memgres/admin.py

@@ -409,11 +409,17 @@ def list_spaces(conn, p: Principal) -> List[dict]:
 
 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 = "") -> 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")
@@ -423,8 +429,68 @@ def issue_token(conn, p: Principal, *, user_id: str,
     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"}
+    return deliver_secret(secret, tid, sink_dir)
+
+
+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.")
+    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)
+
+
+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:

{memgres-0.7.2 → memgres-0.9.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),

{memgres-0.7.2 → memgres-0.9.0}/memgres/identity.py

@@ -26,6 +26,7 @@ from __future__ import annotations
 
 import hashlib
 import hmac
+import os
 import re
 import secrets
 from dataclasses import dataclass
@@ -34,6 +35,21 @@ from typing import List, Optional, Sequence, Tuple
 # ─── token format: mgk_ + 43 url-safe chars (256-bit) ────────────────────────
 TOKEN_RE = re.compile(r"^mgk_[A-Za-z0-9_-]{43}$")
 
+# ─── enrollment key format: mge_ + the same 256 bits ─────────────────────────
+# A DIFFERENT prefix on purpose. The two are handled by different code paths and
+# have opposite lifetimes — one is durable, one dies in half an hour — so a
+# credential that leaks should be identifiable on sight, by a human reading a
+# log and by the server refusing it in the wrong slot.
+ENROLL_RE = re.compile(r"^mge_[A-Za-z0-9_-]{43}$")
+
+# An enrollment key is a credential for as long as it lives, so the default is
+# short. There is deliberately NO upper limit: an operator provisioning someone
+# who is on holiday for two weeks needs a key that survives until they are back,
+# and a server-side cap would only push them into re-issuing keys by hand. The
+# risk of a long window is real and belongs to whoever chooses it, which is why
+# the listing reports every key's expiry.
+DEFAULT_ENROLL_MINUTES = 30
+
 
 def bearer_token(authorization: Optional[str],
                  x_memgres_token: Optional[str]) -> Optional[str]:
@@ -1064,6 +1080,189 @@ def issue_token(conn, user_id: str, *, namespace_id: Optional[str] = None,
         return secret, str(cur.fetchone()[0])
 
 
+def stash_secret(sink_dir: str, token_id: str, secret: str) -> str:
+    """Write a freshly minted secret to ``<sink_dir>/<token_id>.token`` (0600)
+    and return the path.
+
+    The out-of-band delivery channel for a deployment whose callers are agents.
+    Returning the secret in the reply is fine for a program; for an LLM it means
+    the secret is now in a transcript that gets logged, summarized and shipped
+    to a model provider. Handing back a path instead keeps the operator's own
+    shell as the only place the secret is ever rendered.
+
+    The directory is created 0700 if missing, and the file is opened with
+    ``O_CREAT`` at 0600 so the secret is never briefly world-readable.
+    """
+    os.makedirs(sink_dir, mode=0o700, exist_ok=True)
+    path = os.path.join(sink_dir, f"{token_id}.token")
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as fh:
+        fh.write(secret + "\n")
+    os.chmod(path, 0o600)               # tighten even if the file pre-existed
+    return path
+
+
+# ─── enrollment: bind a token the client generated itself ────────────────────
+def new_enrollment_key() -> str:
+    """A fresh one-time key: ``mge_`` + 43 url-safe chars."""
+    return "mge_" + secrets.token_urlsafe(32)
+
+
+def valid_enrollment_format(key: str) -> bool:
+    return bool(key) and bool(ENROLL_RE.match(key))
+
+
+def is_unbound(conn, cfg, secret: Optional[str]) -> bool:
+    """Is this a well-formed credential that simply doesn't belong to anyone yet?
+
+    The question `resolve` cannot answer: it raises ``AuthError`` for an unknown
+    token, a revoked one and an expired one alike, and only the first of those
+    may enroll. Asked separately rather than folded into `resolve` so that
+    authentication keeps exactly one outcome — a Principal or a refusal — and no
+    caller can accidentally treat "may enroll" as "is authenticated".
+    """
+    if cfg.key_mode != "managed" or not valid_format(secret or ""):
+        return False
+    with conn.cursor() as cur:
+        cur.execute("SELECT 1 FROM token WHERE token_hash=%s",
+                    (token_hash(secret),))
+        return cur.fetchone() is None
+
+
+def create_enrollment(conn, user_id: str, *, namespace_id: Optional[str] = None,
+                      permission: str = "write", label: str = "",
+                      created_by: Optional[str] = None,
+                      expires_minutes: int = DEFAULT_ENROLL_MINUTES) -> dict:
+    """Mint a one-time key that lets its holder bind ONE self-generated token to
+    `user_id`. Returns the key (once) plus its id and expiry.
+
+    The ceiling and the scope are decided HERE, by whoever provisions — not by
+    the person redeeming it. Otherwise enrolling would be a way to ask for more
+    authority than you were given.
+
+    `expires_minutes` defaults to 30 and accepts anything above zero — a key for
+    someone who will not be at their desk today is a legitimate need, and the
+    window is the issuer's judgement, not the server's.
+    """
+    if permission not in _RANK:
+        raise ValueError(f"bad permission: {permission}")
+    minutes = int(expires_minutes or DEFAULT_ENROLL_MINUTES)
+    if minutes < 1:
+        raise ValueError("expires_minutes must be at least 1")
+    key = new_enrollment_key()
+    with conn.cursor() as cur:
+        cur.execute(
+            "INSERT INTO enrollment_key (key_hash, user_id, namespace_id, "
+            "permission, label, created_by, expires_at) VALUES "
+            "(%s, %s, %s, %s, %s, %s, now() + make_interval(mins => %s)) "
+            "RETURNING id, expires_at",
+            (token_hash(key), user_id, namespace_id, permission, label,
+             created_by, minutes))
+        eid, exp = cur.fetchone()
+    return {"key": key, "id": str(eid), "expires_at": exp,
+            "user_id": user_id, "permission": permission,
+            "namespace_id": namespace_id}
+
+
+def redeem_enrollment(conn, key: str, secret: str) -> dict:
+    """Bind `secret` — a token the caller generated — to the account `key` names.
+
+    Every refusal here is deliberate and distinct:
+
+    * a spent key says so, because that is the ONLY signal a stolen key gives.
+      Its rightful holder finding it already redeemed is how the theft is
+      noticed at all; collapsing it into "invalid key" would erase the alarm.
+    * a secret the server already knows is refused rather than re-bound. A
+      revoked token could otherwise be revived by enrolling it somewhere else,
+      which would make revocation a suggestion.
+    """
+    if not valid_enrollment_format(key):
+        raise AuthError("malformed enrollment key (expected mge_ + 43 url-safe chars)")
+    if not valid_format(secret or ""):
+        raise AuthError("the credential to bind must be mgk_ + 43 url-safe chars")
+    with conn.cursor() as cur:
+        cur.execute(
+            "SELECT id, user_id, namespace_id, permission, label, "
+            "       used_at IS NOT NULL, revoked_at IS NOT NULL, "
+            "       expires_at <= now() "
+            "FROM enrollment_key WHERE key_hash=%s FOR UPDATE",
+            (token_hash(key),))
+        row = cur.fetchone()
+        if row is None:
+            raise AuthError("unknown enrollment key")
+        eid, uid, nsid, perm, label, used, revoked, expired = row
+        if used:
+            raise AuthError("this enrollment key was already redeemed — if that "
+                            "was not you, tell whoever issued it: the token it "
+                            "created belongs to someone else")
+        if revoked:
+            raise AuthError("enrollment key revoked")
+        if expired:
+            raise AuthError("enrollment key expired")
+        cur.execute("SELECT 1 FROM token WHERE token_hash=%s", (token_hash(secret),))
+        if cur.fetchone() is not None:
+            raise AuthError("that credential is already known to this server — "
+                            "generate a fresh one")
+        tid = register_token(conn, str(uid), secret, namespace_id=
+                             str(nsid) if nsid else None,
+                             permission=perm, label=label or "enrolled")
+        cur.execute("UPDATE enrollment_key SET used_at=now(), used_token_id=%s "
+                    "WHERE id=%s", (tid, eid))
+    return {"user_id": str(uid), "token_id": tid, "permission": perm,
+            "namespace_id": str(nsid) if nsid else None,
+            "enrollment_id": str(eid)}
+
+
+def list_enrollments(conn, *, user_id: Optional[str] = None) -> List[dict]:
+    """Pending and spent keys — metadata only, never the key itself."""
+    # `expired` is computed by the DATABASE: the key's clock and the reader's
+    # are not the same clock, and a listing that disagreed with what redeeming
+    # does would be worse than no listing.
+    sql = ("SELECT id, user_id, namespace_id, permission, label, created_by, "
+           "created_at, expires_at, used_at, used_token_id, revoked_at, "
+           "expires_at <= now() AS expired FROM enrollment_key")
+    args: list = []
+    if user_id is not None:
+        sql += " WHERE user_id=%s"
+        args.append(user_id)
+    sql += " ORDER BY created_at DESC, id"
+    with conn.cursor() as cur:
+        cur.execute(sql, args)
+        cols = [c.name for c in cur.description]
+        out = []
+        for r in cur.fetchall():
+            d = dict(zip(cols, r))
+            for k in ("id", "user_id", "namespace_id", "created_by",
+                      "used_token_id"):
+                d[k] = str(d[k]) if d[k] else None
+            d["state"] = ("revoked" if d["revoked_at"] else
+                          "redeemed" if d["used_at"] else
+                          "expired" if d.pop("expired") else "pending")
+            d.pop("expired", None)
+            out.append(d)
+        return out
+
+
+def revoke_enrollment(conn, enrollment_id: str) -> bool:
+    """Kill an unredeemed key. False if it was already spent, revoked or absent —
+    a redeemed key is NOT revocable, because what needs killing then is the token
+    it produced, and pretending otherwise would leave that token alive."""
+    with conn.cursor() as cur:
+        cur.execute("UPDATE enrollment_key SET revoked_at=now() WHERE id=%s "
+                    "AND revoked_at IS NULL AND used_at IS NULL RETURNING id",
+                    (enrollment_id,))
+        return cur.fetchone() is not None
+
+
+def enrollment_owner(conn, enrollment_id: str) -> Optional[str]:
+    """Whose account a key would bind to — the target for an authority check."""
+    with conn.cursor() as cur:
+        cur.execute("SELECT user_id FROM enrollment_key WHERE id=%s",
+                    (enrollment_id,))
+        r = cur.fetchone()
+        return str(r[0]) if r else None
+
+
 def register_token(conn, user_id: str, secret: str, *,
                    namespace_id: Optional[str] = None, permission: str = "write",
                    label: str = "", expires_at=None) -> str:

{memgres-0.7.2 → memgres-0.9.0}/memgres/info.py

@@ -1,7 +1,7 @@
 """Effective server configuration, exposed read-only for introspection.
 
-An agent shouldn't have to guess the write ceilings, which recall modes are
-available, or how memories are embedded. ``server_info`` distills the loaded
+An agent shouldn't have to guess the write ceilings, how long a memory is kept,
+which recall modes are available, or how memories are embedded. ``server_info`` distills the loaded
 ``Config`` (plus the live embedder's dimension, if one is built) into a small,
 non-sensitive dict. It deliberately carries **no** secrets — no token, no api
 key, no database url — so it is safe to return unauthenticated.
@@ -16,6 +16,15 @@ from .config import Config
 from .schema import SCHEMA_VERSION
 
 
+def _retention_policy(days: int, renew_on_read: bool) -> str:
+    """One plain sentence a human (or an agent explaining itself) can quote."""
+    if days <= 0:
+        return "kept indefinitely — memories do not expire"
+    touch = ("any touch, a read included, starts the window again"
+             if renew_on_read else "only a write restarts the window")
+    return f"deleted {days} days after the last touch ({touch})"
+
+
 def server_info(cfg: Config, embed_dim: Optional[int] = None) -> dict:
     """Effective limits + capabilities, from the loaded config (and the live
     embedder's dimension when available). Never includes secrets.
@@ -25,6 +34,7 @@ def server_info(cfg: Config, embed_dim: Optional[int] = None) -> dict:
     layout this build migrates to."""
     lexical_only = cfg.embed_provider == "none"
     dim = embed_dim if embed_dim is not None else (cfg.embed_dim or None)
+    days = cfg.retention_days
     return {
         "version": __version__,
         "schema_version": SCHEMA_VERSION,
@@ -43,6 +53,18 @@ def server_info(cfg: Config, embed_dim: Optional[int] = None) -> dict:
             "model": cfg.embed_model or None,
             "dim": dim,
         },
+        # How long a memory survives, said out loud. A client that cannot see
+        # this has to guess whether what it stores today will still be there in a
+        # month — and "kept indefinitely" is the answer it guesses WRONG about
+        # most often, because nothing in a reply hints that an expiry exists at
+        # all. `days: null` is the unlimited case, spelled again in `policy`.
+        "retention": {
+            "days": days if days > 0 else None,
+            "expires": days > 0,
+            # A read renewing the window only means anything if there is one.
+            "renew_on_read": bool(days > 0 and cfg.renew_on_read),
+            "policy": _retention_policy(days, cfg.renew_on_read),
+        },
         "recall_modes": ["lexical"] if lexical_only
         else ["lexical", "semantic", "hybrid", "auto"],
         "vector_backend": cfg.vector_backend,