langgraph-tenancy 0.1.0__py3-none-any.whl

langgraph_tenancy/__init__.py

@@ -0,0 +1,65 @@
+"""Tenant isolation for LangGraph persistence.
+
+LangGraph's own threat model: "Without application-level auth, any caller
+with a valid thread_id can access that thread's state." This package is that
+application-level wall, as a drop-in wrapper:
+
+```python
+from langgraph_tenancy import (
+    TenantScopedCheckpointer, TenantScopedStore, InMemoryUsageLedger,
+)
+
+ledger = InMemoryUsageLedger()
+checkpointer = TenantScopedCheckpointer(PostgresSaver(...), usage_ledger=ledger)
+store = TenantScopedStore(InMemoryStore())
+
+graph = builder.compile(checkpointer=checkpointer, store=store)
+
+graph.invoke(
+    {"messages": [...]},
+    config={"configurable": {"thread_id": "t1", "tenant_id": "acme"}},
+)
+
+ledger.totals("acme")  # per-tenant token usage, for free
+```
+
+Guarantees:
+- No tenant_id in config -> the call raises; nothing is read or written.
+- Thread ids and store namespaces are physically tenant-prefixed in storage.
+- `list(None)` (enumerate all tenants' threads) is refused.
+- Maintenance ops (delete/copy/prune) require an explicit `for_tenant()` handle.
+"""
+
+from langgraph_tenancy._checkpointer import (
+    TenantCheckpointerHandle,
+    TenantScopedCheckpointer,
+)
+from langgraph_tenancy._errors import (
+    InvalidTenantError,
+    TenancyError,
+    TenantRequiredError,
+    UnscopedAccessError,
+)
+from langgraph_tenancy._store import TenantScopedStore
+from langgraph_tenancy._usage import (
+    InMemoryUsageLedger,
+    TenantUsage,
+    UsageLedger,
+    UsageRecord,
+    extract_usage,
+)
+
+__all__ = [
+    "InMemoryUsageLedger",
+    "InvalidTenantError",
+    "TenancyError",
+    "TenantCheckpointerHandle",
+    "TenantRequiredError",
+    "TenantScopedCheckpointer",
+    "TenantScopedStore",
+    "TenantUsage",
+    "UnscopedAccessError",
+    "UsageLedger",
+    "UsageRecord",
+    "extract_usage",
+]

langgraph_tenancy/_checkpointer.py

@@ -0,0 +1,254 @@
+"""Tenant-scoped wrapper around any `BaseCheckpointSaver`.
+
+Design:
+- Reads `tenant_id` from `config["configurable"]` on every call. Missing
+  tenant -> `TenantRequiredError`. There is no unscoped fallback.
+- Physically prefixes `thread_id` with the tenant (``acme::thread-1``) before
+  it reaches the inner saver, and strips the prefix from everything returned.
+  A wrong-thread_id bug in app code therefore cannot cross a tenant boundary:
+  the key the database sees is always tenant-qualified.
+- Blocks the dangerous raw-API escape hatches: `list(None)` and
+  `delete_thread(...)` without a tenant.
+- Optionally records per-tenant token usage from checkpointed messages into a
+  `UsageLedger` (see `_usage.py`) — same integration point, free metering.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator, Sequence
+from typing import Any
+
+from langchain_core.runnables import RunnableConfig
+from langgraph.checkpoint.base import (
+    BaseCheckpointSaver,
+    ChannelVersions,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+)
+
+from langgraph_tenancy._errors import (
+    InvalidTenantError,
+    TenantRequiredError,
+    UnscopedAccessError,
+)
+from langgraph_tenancy._usage import UsageLedger, extract_usage
+
+SEP = "::"
+
+
+def _validate_tenant(tenant: Any, where: str) -> str:
+    if not isinstance(tenant, str) or not tenant:
+        raise TenantRequiredError(where)
+    if SEP in tenant:
+        raise InvalidTenantError(f"tenant_id may not contain '{SEP}': {tenant!r}")
+    return tenant
+
+
+class TenantScopedCheckpointer(BaseCheckpointSaver):
+    """Wrap a checkpointer so every operation is scoped to one tenant."""
+
+    def __init__(
+        self,
+        inner: BaseCheckpointSaver,
+        *,
+        usage_ledger: UsageLedger | None = None,
+    ) -> None:
+        super().__init__(serde=inner.serde)
+        self.inner = inner
+        self.usage_ledger = usage_ledger
+
+    # -- scoping helpers ----------------------------------------------------
+
+    def _scope(self, config: RunnableConfig, where: str) -> tuple[str, RunnableConfig]:
+        conf = config.get("configurable") or {}
+        tenant = _validate_tenant(conf.get("tenant_id"), where)
+        thread_id = conf.get("thread_id")
+        scoped_thread = f"{tenant}{SEP}{thread_id}"
+        return tenant, {
+            **config,
+            "configurable": {**conf, "thread_id": scoped_thread},
+        }
+
+    def _unscope_config(
+        self, tenant: str, config: RunnableConfig | None
+    ) -> RunnableConfig | None:
+        if config is None:
+            return None
+        conf = config.get("configurable") or {}
+        thread_id = conf.get("thread_id")
+        prefix = f"{tenant}{SEP}"
+        if isinstance(thread_id, str) and thread_id.startswith(prefix):
+            conf = {**conf, "thread_id": thread_id[len(prefix) :], "tenant_id": tenant}
+        return {**config, "configurable": conf}
+
+    def _unscope_tuple(
+        self, tenant: str, tup: CheckpointTuple | None
+    ) -> CheckpointTuple | None:
+        if tup is None:
+            return None
+        return CheckpointTuple(
+            config=self._unscope_config(tenant, tup.config),
+            checkpoint=tup.checkpoint,
+            metadata=tup.metadata,
+            parent_config=self._unscope_config(tenant, tup.parent_config),
+            pending_writes=tup.pending_writes,
+        )
+
+    # -- core protocol (sync) -----------------------------------------------
+
+    @property
+    def config_specs(self) -> list:
+        return self.inner.config_specs
+
+    def get_next_version(self, current: Any, channel: None = None) -> Any:
+        return self.inner.get_next_version(current, channel)
+
+    def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        tenant, scoped = self._scope(config, "get_tuple()")
+        return self._unscope_tuple(tenant, self.inner.get_tuple(scoped))
+
+    def list(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> Iterator[CheckpointTuple]:
+        if config is None:
+            raise UnscopedAccessError(
+                "list(None) would enumerate every tenant's threads; "
+                "pass a config with tenant_id (and optionally thread_id)."
+            )
+        tenant, scoped = self._scope(config, "list()")
+        scoped_before = self._scope(before, "list(before=...)")[1] if before else None
+        for tup in self.inner.list(
+            scoped, filter=filter, before=scoped_before, limit=limit
+        ):
+            yield self._unscope_tuple(tenant, tup)
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        tenant, scoped = self._scope(config, "put()")
+        if self.usage_ledger is not None:
+            for record in extract_usage(checkpoint):
+                self.usage_ledger.record(tenant, record)
+        result = self.inner.put(scoped, checkpoint, metadata, new_versions)
+        return self._unscope_config(tenant, result)
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        _, scoped = self._scope(config, "put_writes()")
+        self.inner.put_writes(scoped, writes, task_id, task_path)
+
+    # -- blocked / redirected escape hatches ----------------------------------
+
+    def delete_thread(self, thread_id: str) -> None:
+        raise UnscopedAccessError(
+            "delete_thread() has no tenant context; "
+            "use for_tenant(tenant_id).delete_thread(thread_id)."
+        )
+
+    def delete_for_runs(self, run_ids: Sequence[str]) -> None:
+        raise UnscopedAccessError(
+            "delete_for_runs() cannot be tenant-scoped (run ids are global); "
+            "call it on the inner saver explicitly if you accept that."
+        )
+
+    def for_tenant(self, tenant_id: str) -> TenantCheckpointerHandle:
+        """Admin/maintenance handle pinned to one tenant."""
+        return TenantCheckpointerHandle(
+            self, _validate_tenant(tenant_id, "for_tenant()")
+        )
+
+    # -- core protocol (async) ------------------------------------------------
+
+    async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        tenant, scoped = self._scope(config, "aget_tuple()")
+        return self._unscope_tuple(tenant, await self.inner.aget_tuple(scoped))
+
+    async def alist(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> AsyncIterator[CheckpointTuple]:
+        if config is None:
+            raise UnscopedAccessError(
+                "alist(None) would enumerate every tenant's threads; "
+                "pass a config with tenant_id (and optionally thread_id)."
+            )
+        tenant, scoped = self._scope(config, "alist()")
+        scoped_before = self._scope(before, "alist(before=...)")[1] if before else None
+        async for tup in self.inner.alist(
+            scoped, filter=filter, before=scoped_before, limit=limit
+        ):
+            yield self._unscope_tuple(tenant, tup)
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        tenant, scoped = self._scope(config, "aput()")
+        if self.usage_ledger is not None:
+            for record in extract_usage(checkpoint):
+                self.usage_ledger.record(tenant, record)
+        result = await self.inner.aput(scoped, checkpoint, metadata, new_versions)
+        return self._unscope_config(tenant, result)
+
+    async def aput_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        _, scoped = self._scope(config, "aput_writes()")
+        await self.inner.aput_writes(scoped, writes, task_id, task_path)
+
+    async def adelete_thread(self, thread_id: str) -> None:
+        self.delete_thread(thread_id)
+
+
+class TenantCheckpointerHandle:
+    """Maintenance operations pre-bound to a single tenant.
+
+    Exists because `BaseCheckpointSaver.delete_thread/copy_thread/prune` take
+    bare thread ids with no config, so there is no per-call tenant to read.
+    """
+
+    def __init__(self, parent: TenantScopedCheckpointer, tenant: str) -> None:
+        self._inner = parent.inner
+        self._tenant = tenant
+
+    def _scoped(self, thread_id: str) -> str:
+        return f"{self._tenant}{SEP}{thread_id}"
+
+    def delete_thread(self, thread_id: str) -> None:
+        self._inner.delete_thread(self._scoped(thread_id))
+
+    def copy_thread(self, source_thread_id: str, target_thread_id: str) -> None:
+        self._inner.copy_thread(
+            self._scoped(source_thread_id), self._scoped(target_thread_id)
+        )
+
+    def prune(
+        self, thread_ids: Sequence[str], *, strategy: str = "keep_latest"
+    ) -> None:
+        self._inner.prune([self._scoped(t) for t in thread_ids], strategy=strategy)

langgraph_tenancy/_errors.py

@@ -0,0 +1,39 @@
+"""Errors raised by langgraph-tenancy.
+
+Every error here exists to turn a silent cross-tenant leak into a loud failure.
+"""
+
+
+class TenancyError(Exception):
+    """Base class for all tenancy errors."""
+
+
+class TenantRequiredError(TenancyError):
+    """Raised when an operation runs without a tenant_id in scope.
+
+    The wrapper never falls back to an unscoped read or write: no tenant, no data.
+    """
+
+    def __init__(self, where: str) -> None:
+        super().__init__(
+            f"{where} requires a tenant. Pass it in the run config: "
+            "config={'configurable': {'thread_id': ..., 'tenant_id': ...}} "
+            "or use .for_tenant(tenant_id) for out-of-band access."
+        )
+
+
+class UnscopedAccessError(TenancyError):
+    """Raised for operations that would touch data across tenant boundaries.
+
+    Example: `checkpointer.list(None)` on a raw saver enumerates every
+    customer's threads. This wrapper refuses that call instead.
+    """
+
+
+class InvalidTenantError(TenancyError):
+    """Raised when a tenant_id could be used to escape its scope.
+
+    The tenant id becomes part of storage keys, so it must not contain the
+    separator (or be empty) — otherwise tenant "a" could craft ids that
+    collide with tenant "a::b".
+    """

langgraph_tenancy/_store.py

@@ -0,0 +1,124 @@
+"""Tenant-scoped wrapper around any `BaseStore`.
+
+Raw `BaseStore` namespaces are pure convention — any caller can `get()`,
+`search()`, or `list_namespaces()` across all of them. This wrapper prepends
+the tenant id as the root namespace segment on every operation and strips it
+from every result, so two tenants using the identical namespace tuple
+(e.g. ``("memories",)``) land in physically distinct locations.
+
+Tenant resolution, in order:
+1. A pinned tenant from `.for_tenant(tenant_id)` (out-of-band/admin access).
+2. The ambient run config via `langgraph.config.get_config()` — inside a node,
+   the `tenant_id` you passed to `graph.invoke(...)` is picked up automatically.
+3. Otherwise: `TenantRequiredError`. Never an unscoped operation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from langgraph.store.base import (
+    BaseStore,
+    GetOp,
+    ListNamespacesOp,
+    MatchCondition,
+    Op,
+    PutOp,
+    Result,
+    SearchOp,
+)
+
+from langgraph_tenancy._errors import InvalidTenantError, TenantRequiredError
+
+SEP = "::"
+
+
+class TenantScopedStore(BaseStore):
+    def __init__(self, inner: BaseStore, *, _tenant: str | None = None) -> None:
+        self.inner = inner
+        self._tenant = _tenant
+
+    def for_tenant(self, tenant_id: str) -> TenantScopedStore:
+        """A view of the store pinned to one tenant, for use outside a run."""
+        self._validate(tenant_id)
+        return TenantScopedStore(self.inner, _tenant=tenant_id)
+
+    # -- tenant resolution ----------------------------------------------------
+
+    @staticmethod
+    def _validate(tenant: Any) -> str:
+        if not isinstance(tenant, str) or not tenant:
+            raise TenantRequiredError("store access")
+        if SEP in tenant:
+            raise InvalidTenantError(f"tenant_id may not contain '{SEP}': {tenant!r}")
+        return tenant
+
+    def _current_tenant(self) -> str:
+        if self._tenant is not None:
+            return self._tenant
+        try:
+            from langgraph.config import get_config
+
+            config = get_config()
+        except Exception:
+            config = None
+        tenant = ((config or {}).get("configurable") or {}).get("tenant_id")
+        return self._validate(tenant)
+
+    # -- op rewriting -----------------------------------------------------------
+
+    def _scope_op(self, tenant: str, op: Op) -> Op:
+        if isinstance(op, (GetOp, PutOp)):
+            return op._replace(namespace=(tenant, *op.namespace))
+        if isinstance(op, SearchOp):
+            return op._replace(namespace_prefix=(tenant, *op.namespace_prefix))
+        if isinstance(op, ListNamespacesOp):
+            conditions = list(op.match_conditions or ())
+            for i, cond in enumerate(conditions):
+                if cond.match_type == "prefix":
+                    conditions[i] = MatchCondition(
+                        match_type="prefix", path=(tenant, *cond.path)
+                    )
+                    break
+            else:
+                conditions.insert(
+                    0, MatchCondition(match_type="prefix", path=(tenant,))
+                )
+            return op._replace(
+                match_conditions=tuple(conditions),
+                max_depth=None if op.max_depth is None else op.max_depth + 1,
+            )
+        raise TypeError(f"unsupported op: {op!r}")
+
+    def _unscope_result(self, tenant: str, op: Op, result: Result) -> Result:
+        if isinstance(op, GetOp) and result is not None:
+            result.namespace = tuple(result.namespace[1:])
+            return result
+        if isinstance(op, SearchOp):
+            for item in result:
+                item.namespace = tuple(item.namespace[1:])
+            return result
+        if isinstance(op, ListNamespacesOp):
+            return [tuple(ns[1:]) for ns in result if ns and ns[0] == tenant]
+        return result
+
+    # -- BaseStore protocol -------------------------------------------------------
+
+    def batch(self, ops: Iterable[Op]) -> list[Result]:
+        tenant = self._current_tenant()
+        ops = list(ops)
+        results = self.inner.batch([self._scope_op(tenant, op) for op in ops])
+        return [
+            self._unscope_result(tenant, op, result)
+            for op, result in zip(ops, results, strict=True)
+        ]
+
+    async def abatch(self, ops: Iterable[Op]) -> list[Result]:
+        tenant = self._current_tenant()
+        ops = list(ops)
+        results = await self.inner.abatch([self._scope_op(tenant, op) for op in ops])
+        return [
+            self._unscope_result(tenant, op, result)
+            for op, result in zip(ops, results, strict=True)
+        ]

langgraph_tenancy/_usage.py

@@ -0,0 +1,95 @@
+"""Per-tenant token usage, extracted at the checkpoint boundary.
+
+LangGraph already persists `usage_metadata` on every AI message inside
+`checkpoint["channel_values"]` — it is just never indexed or aggregated.
+Since the tenant-scoped checkpointer sees every checkpoint anyway, it can
+pull usage out and attribute it to the tenant for free.
+
+Messages are deduplicated by message id, so re-checkpointing the same
+conversation does not double-count.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from threading import Lock
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True)
+class UsageRecord:
+    message_id: str
+    model: str | None
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+
+
+class UsageLedger(Protocol):
+    """Anything that can receive per-tenant usage records.
+
+    Swap the in-memory default for one backed by your own Postgres table,
+    StatsD, OpenMeter, etc.
+    """
+
+    def record(self, tenant_id: str, record: UsageRecord) -> None: ...
+
+
+@dataclass
+class TenantUsage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    messages: int = 0
+    by_model: dict[str, int] = field(default_factory=lambda: defaultdict(int))
+
+
+class InMemoryUsageLedger:
+    """Reference ledger: per-tenant totals, deduped by message id."""
+
+    def __init__(self) -> None:
+        self._seen: set[tuple[str, str]] = set()
+        self._totals: dict[str, TenantUsage] = defaultdict(TenantUsage)
+        self._lock = Lock()
+
+    def record(self, tenant_id: str, record: UsageRecord) -> None:
+        with self._lock:
+            key = (tenant_id, record.message_id)
+            if key in self._seen:
+                return
+            self._seen.add(key)
+            usage = self._totals[tenant_id]
+            usage.input_tokens += record.input_tokens
+            usage.output_tokens += record.output_tokens
+            usage.total_tokens += record.total_tokens
+            usage.messages += 1
+            if record.model:
+                usage.by_model[record.model] += record.total_tokens
+
+    def totals(self, tenant_id: str) -> TenantUsage:
+        with self._lock:
+            return self._totals[tenant_id]
+
+
+def extract_usage(checkpoint: dict[str, Any]) -> list[UsageRecord]:
+    """Pull usage records out of message objects in a checkpoint's channels."""
+    records: list[UsageRecord] = []
+    for value in (checkpoint.get("channel_values") or {}).values():
+        items = value if isinstance(value, (list, tuple)) else [value]
+        for item in items:
+            usage = getattr(item, "usage_metadata", None)
+            message_id = getattr(item, "id", None)
+            if not usage or not message_id:
+                continue
+            model = (getattr(item, "response_metadata", None) or {}).get("model_name")
+            records.append(
+                UsageRecord(
+                    message_id=message_id,
+                    model=model,
+                    input_tokens=usage.get("input_tokens", 0),
+                    output_tokens=usage.get("output_tokens", 0),
+                    total_tokens=usage.get("total_tokens", 0),
+                )
+            )
+    return records

langgraph_tenancy-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: langgraph-tenancy
+Version: 0.1.0
+Summary: Tenant isolation and per-tenant usage metering for LangGraph checkpointers and stores
+Project-URL: Source, https://github.com/ac12644/langgraph-tenancy
+Project-URL: Issues, https://github.com/ac12644/langgraph-tenancy/issues
+Author-email: Abhishek Chauhan <ac12644@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,checkpointer,langgraph,llm,multi-tenant,tenant-isolation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: langchain-core>=0.2.38
+Requires-Dist: langgraph-checkpoint>=2.0.0
+Provides-Extra: test
+Requires-Dist: langgraph-checkpoint-postgres>=2.0.0; extra == 'test'
+Requires-Dist: langgraph>=0.4; extra == 'test'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langgraph-tenancy
+
+[![CI](https://github.com/ac12644/langgraph-tenancy/actions/workflows/ci.yml/badge.svg)](https://github.com/ac12644/langgraph-tenancy/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/langgraph-tenancy)](https://pypi.org/project/langgraph-tenancy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Tenant isolation for LangGraph persistence — as a drop-in wrapper.**
+
+LangGraph's own [threat model](https://github.com/langchain-ai/langgraph/blob/main/.github/THREAT_MODEL.md) says it plainly:
+
+> Checkpoint savers index by `thread_id`. Without application-level auth, any
+> caller with a valid thread_id can access that thread's state. [...] Users
+> embedding LangGraph directly must implement their own access controls.
+
+If you run a multi-tenant product on open-source LangGraph, the only thing
+between Customer A's agent state and Customer B's is a query filter in your
+application code. This package replaces that convention with enforcement.
+
+## Install
+
+```bash
+pip install langgraph-tenancy
+```
+
+## Usage
+
+Wrap your existing checkpointer and store. Nothing else changes.
+
+```python
+from langgraph_tenancy import (
+    TenantScopedCheckpointer,
+    TenantScopedStore,
+    InMemoryUsageLedger,
+)
+
+ledger = InMemoryUsageLedger()
+checkpointer = TenantScopedCheckpointer(PostgresSaver(...), usage_ledger=ledger)
+store = TenantScopedStore(InMemoryStore())
+
+graph = builder.compile(checkpointer=checkpointer, store=store)
+
+# tenant_id is now REQUIRED on every invocation
+graph.invoke(
+    {"messages": ["hello"]},
+    config={"configurable": {"thread_id": "t1", "tenant_id": "acme"}},
+)
+
+# free per-tenant token metering, extracted from checkpointed messages
+ledger.totals("acme")  # TenantUsage(input_tokens=..., output_tokens=..., by_model={...})
+```
+
+## What it enforces
+
+| Raw LangGraph behavior | With `langgraph-tenancy` |
+|---|---|
+| Any caller with a `thread_id` reads that thread | Threads are physically keyed `tenant::thread`; wrong-thread_id bugs cannot cross tenants |
+| Missing filter → silent unscoped query | Missing `tenant_id` → `TenantRequiredError`, nothing read or written |
+| `checkpointer.list(None)` enumerates **every** tenant's threads | Refused with `UnscopedAccessError` |
+| Store namespaces are convention; any node can read any namespace | Every op is rooted at the tenant segment, resolved from the run config automatically |
+| `delete_thread("t1")` deletes whoever owns `t1` | Requires an explicit `for_tenant("acme").delete_thread("t1")` handle |
+| `usage_metadata` buried in checkpoint blobs, unqueryable | Aggregated per tenant (and per model), deduped by message id |
+
+## No magic
+
+The entire mechanism is key prefixing plus mandatory-context checks, in two
+small files you can audit in ten minutes:
+
+- thread ids become `"{tenant_id}::{thread_id}"` before reaching your
+  database; the prefix is stripped from everything returned.
+- store namespaces `("memories",)` become `("{tenant_id}", "memories")`.
+- tenant ids containing the separator are rejected, so `acme` can never craft
+  a key that collides with another tenant's space.
+
+It composes with any `BaseCheckpointSaver` / `BaseStore` implementation —
+Postgres, SQLite, Redis, MongoDB, in-memory — because it never touches
+storage itself.
+
+## What it is not
+
+- Not authentication. You decide which tenant a request belongs to; this
+  package guarantees that decision is enforced everywhere downstream.
+- Not encryption. Combine with `EncryptedSerializer` for at-rest encryption.
+- Not a replacement for database-level controls in high-assurance setups
+  (RLS, schema-per-tenant) — it's the layer that makes your *application*
+  unable to leak, whatever the database allows.
+
+## Tested
+
+The adversarial test suite — every test attempts a cross-tenant access the
+raw LangGraph API allows — runs against `InMemorySaver` **and** a real
+`PostgresSaver` in CI. The isolation guarantees are proven on actual SQL
+storage, not just the in-memory reference.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[test]"
+uv run pytest                 # postgres tests skip if no server is reachable
+
+# to run the postgres leg locally:
+export LG_TENANCY_PG_URI=postgresql://user@localhost:5432/langgraph_tenancy_test
+uv run pytest
+```
+
+## Status
+
+Early (0.1.x). Covered today: sync + async checkpointer paths, sync store
+paths, in-memory and Postgres backends. Not yet covered: subgraph
+`checkpoint_ns` edge cases, `AsyncPostgresSaver`, `PostgresStore`, store TTL
+ops. Issues and PRs welcome.
+
+## License
+
+[MIT](LICENSE)

langgraph_tenancy-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+langgraph_tenancy/__init__.py,sha256=F2t9sXO1R0WtWKjf0v_aiSA7bbz1XuLIdSVyT_OrpI8,1808
+langgraph_tenancy/_checkpointer.py,sha256=qZ9hZ_CiEE4fwpQYhsVtt4jWQgpboWxGY7Gh40zKDdM,9366
+langgraph_tenancy/_errors.py,sha256=DBfUDtR2s5M9XTx2AIlp9R9CuiUFM7IFnWFK0TVZR4E,1262
+langgraph_tenancy/_store.py,sha256=Ih4DG3l-RhcQZuOdzDJryMM3TUV_Hxgk7SRunWLmCGQ,4673
+langgraph_tenancy/_usage.py,sha256=0jtSj9UojrC1gXFwjy2xVA82ZcgKZbTdP0PnLMtQPfw,3229
+langgraph_tenancy-0.1.0.dist-info/METADATA,sha256=TsPnEIf8HqpvfE9KAzlDSVLXIbLyYG5uOBWGY5dVRtw,5874
+langgraph_tenancy-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+langgraph_tenancy-0.1.0.dist-info/licenses/LICENSE,sha256=9YWSUfU-xUgeinePkdw2ZBhuU-slmV2bnqRbsc67eD8,1073
+langgraph_tenancy-0.1.0.dist-info/RECORD,,

langgraph_tenancy-0.1.0.dist-info/WHEEL

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

langgraph_tenancy-0.1.0.dist-info/licenses/LICENSE

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