ten-grd 0.2.0__py3-none-any.whl

ten_grd/__init__.py

@@ -0,0 +1,17 @@
+"""Tennant Guard: tenant isolation primitives for agentic developers."""
+from .adapters import InMemoryAdapter, IsolationAdapter
+from .client import TenantGuard
+from .context import TenantContext, current_context, tenant_scope
+from .engine import VerificationResult, VerificationStatus, Z3InvariantEngine
+from .exceptions import (GuardError, InvalidContextError, InvalidOperationError,
+                         IsolationViolationError, VerificationError, AdapterError)
+from .predicates import And, Eq, Not, Or
+
+__version__ = "0.2.0"
+__all__ = [
+    "TenantGuard", "TenantContext", "tenant_scope", "current_context",
+    "InMemoryAdapter", "IsolationAdapter", "Z3InvariantEngine",
+    "VerificationResult", "VerificationStatus", "Eq", "And", "Or", "Not",
+    "GuardError", "InvalidContextError", "InvalidOperationError",
+    "IsolationViolationError", "VerificationError", "AdapterError",
+]

ten_grd/adapters.py

@@ -0,0 +1,48 @@
+"""Trusted adapter contract and atomic, in-memory reference implementation."""
+from threading import RLock
+from typing import Protocol
+
+from .exceptions import InvalidOperationError, IsolationViolationError
+from .operations import Operation, OperationKind, Record
+from .predicates import matches
+
+
+class IsolationAdapter(Protocol):
+    """Implementations must preserve the exact checked operation semantics.
+
+    An adapter is trusted enforcement code, not an untrusted plugin. Backend
+    implementations must bind ownership atomically and document model fidelity.
+    """
+    def execute(self, operation: Operation) -> tuple[Record, ...]: ...
+
+
+class InMemoryAdapter:
+    """Reference metadata semantics; intentionally not a persistent backend."""
+
+    def __init__(self):
+        self._records: dict[tuple[str, str], Record] = {}
+        self._lock = RLock()
+
+    def execute(self, operation: Operation) -> tuple[Record, ...]:
+        if type(operation) is not Operation:
+            raise InvalidOperationError("Expected an Operation")
+        operation.validate()
+        with self._lock:
+            if operation.kind is OperationKind.SEARCH:
+                return tuple(record for record in self._records.values()
+                             if record.tenant_id == operation.tenant_id
+                             and matches(operation.selector, record.fields()))
+            key = (operation.tenant_id, operation.record_id)
+            if operation.kind is OperationKind.PUT:
+                record = operation.record
+                if (record.tenant_id != operation.tenant_id
+                        or not matches(operation.selector, record.fields())):
+                    raise IsolationViolationError("Write does not satisfy its checked scope")
+                self._records[key] = record
+                return (record,)
+            record = self._records.get(key)
+            if record is None or not matches(operation.selector, record.fields()):
+                return ()
+            if operation.kind is OperationKind.DELETE:
+                del self._records[key]
+            return (record,)

ten_grd/client.py

@@ -0,0 +1,61 @@
+"""Guarded operations for agent tools, memory, and application data."""
+from .context import current_context
+from .engine import Z3InvariantEngine
+from .exceptions import InvalidOperationError, IsolationViolationError, VerificationError
+from .operations import Operation, OperationKind, Record
+from .predicates import And, Eq, Predicate, matches, validate_predicate
+
+
+class TenantGuard:
+    def __init__(self, adapter, *, engine=None):
+        self._adapter = adapter
+        self._engine = engine if engine is not None else Z3InvariantEngine()
+
+    def search(self, predicate: Predicate | None = None) -> tuple[Record, ...]:
+        return self._run(OperationKind.SEARCH, predicate=predicate)
+
+    def get(self, record_id: str) -> Record | None:
+        records = self._run(OperationKind.GET, record_id=record_id)
+        return records[0] if records else None
+
+    def put(self, record_id: str, data, *, metadata=None) -> Record:
+        context = current_context()
+        record = Record.create(context.tenant_id, record_id, data, metadata)
+        records = self._run(OperationKind.PUT, record_id=record_id, record=record)
+        if len(records) != 1 or records[0] != record:
+            raise VerificationError("Adapter did not return the exact written record")
+        return records[0]
+
+    def delete(self, record_id: str) -> bool:
+        return bool(self._run(OperationKind.DELETE, record_id=record_id))
+
+    def _run(self, kind, *, predicate=None, record_id=None, record=None):
+        context = current_context()
+        terms = [Eq("tenant_id", context.tenant_id)]
+        if predicate is not None:
+            validate_predicate(predicate)
+            terms.append(predicate)
+        if record_id is not None:
+            terms.append(Eq("record_id", record_id))
+        operation = Operation(context.tenant_id, kind, And(tuple(terms)),
+                              record_id, record)
+        result = self._engine.verify_operation(context, operation)
+        result.require_proven()
+        if (result.operation_digest != operation.digest
+                or result.policy_version != context.policy_version):
+            raise VerificationError("Verification evidence does not match the operation")
+        if current_context() != context:
+            raise VerificationError("Tenant context changed during verification")
+        records = self._adapter.execute(operation)
+        # Materialize and validate the entire batch before returning any content.
+        if type(records) is not tuple:
+            raise InvalidOperationError("Adapter must return a materialized record tuple")
+        if kind is not OperationKind.SEARCH and len(records) > 1:
+            raise VerificationError("Adapter returned multiple records for one target")
+        for item in records:
+            if type(item) is not Record:
+                raise IsolationViolationError("Adapter returned an unsupported or unlabeled record")
+            self._engine.verify_ownership(context, item.tenant_id)
+            if not matches(operation.selector, item.fields()):
+                raise IsolationViolationError("Adapter result falls outside the checked selector")
+        return records

ten_grd/context.py

@@ -0,0 +1,49 @@
+"""Request-local scope supplied by the host authentication boundary."""
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+from .exceptions import InvalidContextError
+
+_MAX_IDENTIFIER = 256
+
+
+def validate_identifier(value: str, name: str) -> None:
+    if (not isinstance(value, str) or not value or len(value) > _MAX_IDENTIFIER
+            or value != value.strip() or any(ord(c) < 32 for c in value)):
+        raise InvalidContextError(f"{name} must be a nonempty canonical identifier")
+
+
+@dataclass(frozen=True)
+class TenantContext:
+    """Create only after the host validates identity and tenant membership."""
+    tenant_id: str
+    subject_id: str
+    request_id: str
+    policy_version: str = "1"
+
+    def __post_init__(self):
+        for name in ("tenant_id", "subject_id", "request_id", "policy_version"):
+            validate_identifier(getattr(self, name), name)
+
+
+_current: ContextVar[TenantContext | None] = ContextVar("ten_grd_context", default=None)
+
+
+def current_context() -> TenantContext:
+    context = _current.get()
+    if context is None:
+        raise InvalidContextError("No authenticated tenant context is active")
+    return context
+
+
+@contextmanager
+def tenant_scope(context: TenantContext):
+    """Bind validated context; always restore the prior scope on exit."""
+    if type(context) is not TenantContext:
+        raise InvalidContextError("Expected a validated TenantContext")
+    token = _current.set(context)
+    try:
+        yield context
+    finally:
+        _current.reset(token)

ten_grd/engine.py

@@ -0,0 +1,154 @@
+"""Prove isolation of the supported selector model; fail closed otherwise."""
+from dataclasses import dataclass
+from enum import Enum
+import hashlib
+import json
+import z3
+
+from .context import TenantContext, validate_identifier
+from .exceptions import (GuardError, IsolationViolationError,
+                         InvalidOperationError, VerificationError)
+from .operations import Operation, OperationKind
+from .predicates import And, Eq, Not, Or, predicate_data, validate_predicate
+
+MODEL_VERSION = "string-metadata-v1"
+
+
+class VerificationStatus(str, Enum):
+    PROVEN = "proven"
+    VIOLATION = "violation"
+    UNKNOWN = "unknown"
+    UNSUPPORTED = "unsupported"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class VerificationResult:
+    status: VerificationStatus
+    operation_digest: str
+    policy_version: str
+    reason: str
+    model_version: str = MODEL_VERSION
+
+    def require_proven(self):
+        if self.status is VerificationStatus.VIOLATION:
+            raise IsolationViolationError(self.reason)
+        if self.status is not VerificationStatus.PROVEN:
+            raise VerificationError(self.reason)
+
+
+class Z3InvariantEngine:
+    """No raw queries or caller-provided filter booleans are accepted."""
+
+    def __init__(self, timeout_ms: int = 1000):
+        if type(timeout_ms) is not int or not 1 <= timeout_ms <= 60_000:
+            raise ValueError("timeout_ms must be between 1 and 60000")
+        self.timeout_ms = timeout_ms
+
+    def verify_selector(self, context: TenantContext, selector) -> VerificationResult:
+        return self._verify(context, selector, "")
+
+    def verify_scope(self, context: TenantContext, selector, *, required) -> VerificationResult:
+        """Prove tenant, subject, policy and additional cache scope dimensions."""
+        try:
+            if type(context) is not TenantContext:
+                raise InvalidOperationError("Validated context required")
+            expected = {"tenant_id": context.tenant_id, "subject_id": context.subject_id,
+                        "policy_version": context.policy_version}
+            extra = dict(required)
+            if any(key in expected and expected[key] != value for key, value in extra.items()):
+                return VerificationResult(VerificationStatus.VIOLATION, "", "",
+                                          "Scope conflicts with authenticated context")
+            expected.update(extra)
+            validate_predicate(And(tuple(Eq(k, v) for k, v in expected.items())))
+            return self._verify(context, selector, "", required=expected)
+        except Exception:
+            return VerificationResult(VerificationStatus.UNSUPPORTED, "", "",
+                                      "Scope requirements are unsupported")
+
+    def verify_operation(self, context: TenantContext,
+                         operation: Operation) -> VerificationResult:
+        try:
+            if type(operation) is not Operation:
+                raise InvalidOperationError("Expected an immutable Operation")
+            operation.validate()
+            if type(context) is not TenantContext or operation.tenant_id != context.tenant_id:
+                return VerificationResult(VerificationStatus.VIOLATION, "",
+                                          "", "Operation tenant differs from active context")
+            if (operation.kind is OperationKind.PUT
+                    and operation.record.tenant_id != context.tenant_id):
+                raise IsolationViolationError("Write ownership differs from context")
+            return self._verify(context, operation.selector, operation.digest)
+        except GuardError:
+            return VerificationResult(VerificationStatus.UNSUPPORTED, "", "",
+                                      "Operation is outside the supported contract")
+
+    def _verify(self, context, selector, digest, required=None):
+        try:
+            if type(context) is not TenantContext:
+                raise InvalidOperationError("A validated context is required")
+            validate_predicate(selector)
+            if not digest:
+                raw = json.dumps([context.tenant_id, context.policy_version,
+                                  predicate_data(selector), required], ensure_ascii=True)
+                digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()
+            # Per-call contexts prevent Z3 AST/solver sharing across requests.
+            ctx = z3.Context()
+            solver = z3.Solver(ctx=ctx)
+            solver.set(timeout=self.timeout_ms)
+            fields = {}
+
+            def field(name):
+                if name not in fields:
+                    index = len(fields)
+                    fields[name] = (z3.String(f"v{index}", ctx=ctx),
+                                    z3.Bool(f"p{index}", ctx=ctx))
+                return fields[name]
+
+            def compile_node(node):
+                if type(node) is Eq:
+                    value, present = field(node.field)
+                    return z3.And(present, value == z3.StringVal(node.value, ctx=ctx))
+                if type(node) is And:
+                    terms = [compile_node(p) for p in node.terms]
+                    return z3.And(*terms) if terms else z3.BoolVal(True, ctx=ctx)
+                if type(node) is Or:
+                    terms = [compile_node(p) for p in node.terms]
+                    return z3.Or(*terms) if terms else z3.BoolVal(False, ctx=ctx)
+                return z3.Not(compile_node(node.term))
+
+            selected = compile_node(selector)
+            expected = {"tenant_id": context.tenant_id}
+            expected.update(required or {})
+            violations = []
+            for name, expected_value in expected.items():
+                value, present = field(name)
+                violations.append(z3.Or(z3.Not(present),
+                                        value != z3.StringVal(expected_value, ctx=ctx)))
+            solver.add(selected, z3.Or(*violations))
+            outcome = solver.check()
+            if outcome == z3.unsat:
+                status, reason = VerificationStatus.PROVEN, "Selector preserves tenant ownership"
+            elif outcome == z3.sat:
+                status, reason = VerificationStatus.VIOLATION, "Selector can include foreign or unlabeled data"
+            else:
+                status = VerificationStatus.UNKNOWN
+                reason = "Solver inconclusive: " + solver.reason_unknown()
+            return VerificationResult(status, digest, context.policy_version, reason)
+        except GuardError:
+            return VerificationResult(VerificationStatus.UNSUPPORTED, digest, "",
+                                      "Selector or context is unsupported")
+        except Exception:
+            # Do not expose solver/input details or interpret errors as success.
+            return VerificationResult(VerificationStatus.ERROR, digest, "",
+                                      "Verification failed")
+
+    def verify_ownership(self, context: TenantContext, owner: str) -> None:
+        if type(context) is not TenantContext:
+            raise VerificationError("A validated context is required")
+        try:
+            validate_identifier(owner, "owner")
+        except GuardError as exc:
+            raise IsolationViolationError("Resource ownership is missing or invalid") from exc
+        if owner != context.tenant_id:
+            raise IsolationViolationError("Resource belongs to another tenant")

ten_grd/exceptions.py

@@ -0,0 +1,25 @@
+"""Failures never authorize an operation."""
+
+
+class GuardError(Exception):
+    """Base error raised before protected output is exposed."""
+
+
+class InvalidContextError(GuardError):
+    """A valid host-authenticated tenant context is required."""
+
+
+class InvalidOperationError(GuardError):
+    """The operation is outside the supported contract."""
+
+
+class VerificationError(GuardError):
+    """Verification did not establish isolation."""
+
+
+class IsolationViolationError(VerificationError):
+    """A modeled violation or foreign-owned result was detected."""
+
+
+class AdapterError(GuardError):
+    """A backend operation failed; execution never falls back to broader scope."""

ten_grd/integrations/__init__.py

@@ -0,0 +1 @@
+"""Optional backends. Import modules individually to load only needed drivers."""

ten_grd/integrations/_shared.py

@@ -0,0 +1,53 @@
+"""Shared record codec and enforcement for backend adapters."""
+from ..context import current_context
+from ..exceptions import IsolationViolationError, VerificationError
+from ..operations import Operation, OperationKind, Record
+from ..predicates import And, Eq, matches, validate_predicate
+
+
+def payload(record):
+    return {"tenant_id": record.tenant_id, "record_id": record.record_id,
+            "data_json": record.data_json, "metadata": dict(record.metadata)}
+
+
+def decode_record(value):
+    try:
+        if type(value) is not dict or set(value) != {"tenant_id", "record_id", "data_json", "metadata"}:
+            raise ValueError()
+        if type(value["metadata"]) is not dict:
+            raise ValueError()
+        return Record(value["tenant_id"], value["record_id"], value["data_json"],
+                      tuple(value["metadata"].items()))
+    except Exception:
+        raise IsolationViolationError("Backend returned an invalid ownership envelope") from None
+
+
+def authorize(context, operation, engine):
+    result = engine.verify_operation(context, operation)
+    result.require_proven()
+    if (result.operation_digest != operation.digest
+            or result.policy_version != context.policy_version
+            or current_context() != context):
+        raise VerificationError("Operation evidence or active context changed")
+
+
+def scoped_operation(context, predicate=None, *, kind=OperationKind.SEARCH,
+                     record_id=None, record=None):
+    terms = [Eq("tenant_id", context.tenant_id)]
+    if predicate is not None:
+        validate_predicate(predicate)
+        terms.append(predicate)
+    if record_id is not None:
+        terms.append(Eq("record_id", record_id))
+    return Operation(context.tenant_id, kind, And(tuple(terms)), record_id, record)
+
+
+def checked_records(context, operation, records, engine):
+    result = tuple(records)
+    for record in result:
+        engine.verify_ownership(context, record.tenant_id)
+        if not matches(operation.selector, record.fields()):
+            raise IsolationViolationError("Backend result is outside the verified selector")
+    if current_context() != context:
+        raise VerificationError("Active context changed during backend execution")
+    return result

ten_grd/integrations/cache.py

@@ -0,0 +1,126 @@
+"""Exact cache scopes bind tenant, subject, policy and configuration."""
+from dataclasses import dataclass
+import hashlib
+import json
+
+from ..context import current_context, validate_identifier
+from ..engine import Z3InvariantEngine
+from ..exceptions import AdapterError, InvalidOperationError, IsolationViolationError, VerificationError
+from ..operations import _json
+from ..predicates import And, Eq
+
+
+@dataclass(frozen=True)
+class CacheScope:
+    tenant_id: str
+    subject_id: str
+    policy_version: str
+    namespace: str
+    model_version: str
+
+    def fields(self):
+        return dict(tenant_id=self.tenant_id, subject_id=self.subject_id,
+                    policy_version=self.policy_version, namespace=self.namespace,
+                    model_version=self.model_version)
+
+    def selector(self):
+        return And(tuple(Eq(k, v) for k, v in self.fields().items()))
+
+
+@dataclass(frozen=True)
+class CacheHit:
+    value_json: str
+
+    @property
+    def data(self):
+        return json.loads(self.value_json)
+
+
+def active_scope(namespace, model_version, engine):
+    context = current_context()
+    scope = CacheScope(context.tenant_id, context.subject_id, context.policy_version,
+                       namespace, model_version)
+    engine.verify_scope(context, scope.selector(), required=scope.fields()).require_proven()
+    if current_context() != context:
+        raise VerificationError("Active context changed during cache verification")
+    return context, scope
+
+
+def request_json(request):
+    encoded = _json(request)
+    if len(encoded) > 65536:
+        raise InvalidOperationError("Cache request exceeds 64 KiB")
+    return encoded
+
+
+def cache_key(scope, encoded_request):
+    # Hashing is NOT modeled as injective. Reads validate the full binding.
+    canonical = _json(["ten-grd-cache-v1", scope.fields(), encoded_request])
+    return "ten-grd:cache:v1:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def validate_ttl(ttl_seconds):
+    if type(ttl_seconds) is not int or not 1 <= ttl_seconds <= 31_536_000:
+        raise InvalidOperationError("TTL must be an integer between 1 and 31536000 seconds")
+
+
+class RedisCache:
+    """Synchronous redis-py client or compatible backend; no broad-scope fallback."""
+    def __init__(self, client, *, namespace, model_version, engine=None):
+        validate_identifier(namespace, "namespace")
+        validate_identifier(model_version, "model_version")
+        self.client, self.namespace, self.model_version = client, namespace, model_version
+        self.engine = engine if engine is not None else Z3InvariantEngine()
+
+    def _binding(self, request):
+        context, scope = active_scope(self.namespace, self.model_version, self.engine)
+        encoded = request_json(request)
+        return context, scope, encoded, cache_key(scope, encoded)
+
+    def set(self, request, data, *, ttl_seconds=300):
+        validate_ttl(ttl_seconds)
+        context, scope, encoded, key = self._binding(request)
+        value_json = _json(data)
+        if len(value_json) > 1_048_576:
+            raise InvalidOperationError("Cached value exceeds 1 MiB")
+        envelope = _json({"scope": scope.fields(), "request_json": encoded,
+                          "value_json": value_json})
+        if current_context() != context:
+            raise VerificationError("Active context changed before cache write")
+        try:
+            written = self.client.set(key, envelope, ex=ttl_seconds)
+        except Exception:
+            raise AdapterError("Redis cache write failed") from None
+        if not written:
+            raise AdapterError("Redis did not acknowledge the cache write")
+
+    def get(self, request):
+        context, scope, encoded, key = self._binding(request)
+        try:
+            raw = self.client.get(key)
+        except Exception:
+            raise AdapterError("Redis cache lookup failed") from None
+        if raw is None:
+            return None
+        try:
+            envelope = json.loads(raw)
+            if (type(envelope) is not dict or envelope["scope"] != scope.fields()
+                    or envelope["request_json"] != encoded
+                    or not isinstance(envelope["value_json"], str)):
+                raise ValueError()
+            value = json.loads(envelope["value_json"])
+            canonical = _json(value)
+            if len(canonical) > 1_048_576:
+                raise ValueError()
+        except Exception:
+            raise IsolationViolationError("Cache hit has invalid ownership or request binding") from None
+        if current_context() != context:
+            raise VerificationError("Active context changed during cache lookup")
+        return CacheHit(canonical)
+
+    def delete(self, request):
+        _, _, _, key = self._binding(request)
+        try:
+            return bool(self.client.delete(key))
+        except Exception:
+            raise AdapterError("Redis cache invalidation failed") from None

ten_grd/integrations/langchain.py

@@ -0,0 +1,89 @@
+"""LangChain tools with invocation-local scope and no tenant arguments."""
+import asyncio
+from functools import wraps
+from typing import Any
+from pydantic import BaseModel, ConfigDict, Field
+from langchain_core.tools import StructuredTool
+
+from ..context import current_context
+from ..exceptions import InvalidOperationError, VerificationError
+from ..predicates import Eq
+
+
+class _Args(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class _RecordArgs(_Args):
+    record_id: str
+
+
+class _SearchArgs(_Args):
+    field: str | None = None
+    value: str | None = None
+
+
+class _PutArgs(_RecordArgs):
+    data: Any
+    metadata: dict[str, str] | None = None
+
+
+class _RetrievalArgs(_Args):
+    query: str
+    limit: int = Field(default=10, ge=1, le=1000)
+
+
+def _tool(function, name, description, schema):
+    @wraps(function)
+    async def asynchronous(*args, **kwargs):
+        # to_thread propagates the invocation's contextvars, not creation scope.
+        return await asyncio.to_thread(function, *args, **kwargs)
+    return StructuredTool.from_function(func=function, coroutine=asynchronous,
+                                        name=name, description=description, args_schema=schema)
+
+
+def _prefix(prefix):
+    if not isinstance(prefix, str) or not prefix.isidentifier() or len(prefix) > 64:
+        raise InvalidOperationError("Tool prefix must be an identifier of at most 64 characters")
+
+
+def memory_tools(guard, *, prefix="grd", include_writes=False):
+    """Host authenticates each invocation; tools never capture a tenant at creation."""
+    _prefix(prefix)
+    def read(record_id):
+        record = guard.get(record_id)
+        return None if record is None else record.data
+
+    def search(field=None, value=None):
+        if (field is None) != (value is None):
+            raise InvalidOperationError("Provide both field and value, or neither")
+        predicate = None if field is None else Eq(field, value)
+        return [{"record_id": record.record_id, "data": record.data}
+                for record in guard.search(predicate)]
+
+    tools = [
+        _tool(read, prefix + "_read", "Read a record in the authenticated tenant.", _RecordArgs),
+        _tool(search, prefix + "_search", "Search records in the authenticated tenant.", _SearchArgs),
+    ]
+    if include_writes:
+        def put(record_id, data, metadata=None):
+            return guard.put(record_id, data, metadata=metadata).data
+        def delete(record_id):
+            return guard.delete(record_id)
+        tools.extend([
+            _tool(put, prefix + "_put", "Write a record in the authenticated tenant.", _PutArgs),
+            _tool(delete, prefix + "_delete", "Delete a record in the authenticated tenant.", _RecordArgs),
+        ])
+    return tools
+
+
+def retrieval_tool(retriever, embed_query, *, name="grd_retrieve"):
+    _prefix(name)
+    def retrieve(query, limit=10):
+        context = current_context()
+        vector = embed_query(query)
+        if current_context() != context:
+            raise VerificationError("Embedding callback changed the active context")
+        return [{"record_id": hit.record.record_id, "data": hit.record.data, "score": hit.score}
+                for hit in retriever.search(vector, limit=limit)]
+    return _tool(retrieve, name, "Retrieve documents within the authenticated tenant.", _RetrievalArgs)