sediment-api 0.1.0__tar.gz → 0.3.0__tar.gz

{sediment_api-0.1.0 → sediment_api-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sediment-api
-Version: 0.1.0
+Version: 0.3.0
 Summary: Sediment ingest API: facts in through three doors
 Project-URL: Source, https://github.com/sediment-ai/sediment
 Project-URL: Documentation, https://github.com/sediment-ai/sediment/tree/main/docs
@@ -13,8 +13,8 @@ Requires-Dist: anyio>=4.15.1
 Requires-Dist: fastapi>=0.141.1
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic-settings>=2.15.0
-Requires-Dist: sediment-capture==0.1.0
-Requires-Dist: sediment-core==0.1.0
-Requires-Dist: sediment-derive==0.1.0
-Requires-Dist: sediment-export==0.1.0
+Requires-Dist: sediment-capture==0.3.0
+Requires-Dist: sediment-core==0.3.0
+Requires-Dist: sediment-derive==0.3.0
+Requires-Dist: sediment-export==0.3.0
 Requires-Dist: uvicorn>=0.53.0

{sediment_api-0.1.0 → sediment_api-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sediment-api"
-version = "0.1.0"
+version = "0.3.0"
 description = "Sediment ingest API: facts in through three doors"
 requires-python = ">=3.12"
 license = "AGPL-3.0-or-later"
@@ -12,10 +12,10 @@ dependencies = [
     "httpx>=0.27",
     "uvicorn>=0.53.0",
     "pydantic-settings>=2.15.0",
-    "sediment-core==0.1.0",
-    "sediment-capture==0.1.0",
-    "sediment-derive==0.1.0",
-    "sediment-export==0.1.0",
+    "sediment-core==0.3.0",
+    "sediment-capture==0.3.0",
+    "sediment-derive==0.3.0",
+    "sediment-export==0.3.0",
 ]
 
 [project.urls]

{sediment_api-0.1.0 → sediment_api-0.3.0}/sediment_api/__init__.py

@@ -3,4 +3,4 @@
 
 # Single source for the API version string — FastAPI's ``app.version``
 # (reported by /health) and GET /v1/me both read it, so the two cannot drift.
-__version__ = "0.1.0"
+__version__ = "0.3.0"

{sediment_api-0.1.0 → sediment_api-0.3.0}/sediment_api/config.py

@@ -5,9 +5,10 @@ import json
 import re
 from typing import Annotated
 
-from pydantic import Field, SecretStr, field_validator
+from pydantic import Field, SecretStr, TypeAdapter, field_validator, model_validator
 from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict
-from sediment_core import ForgeHost, normalize_org_id
+from sediment_core import ForgeHost, NonEmptyId, normalize_org_id
+from sediment_core.evidence import CONTEXT_DISCOVERY_SESSION_LIMIT
 
 # Token values that mean "operator never configured a real secret".
 _INSECURE_DEFAULTS = {
@@ -27,6 +28,7 @@ _CLIENT_ID = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$")
 # unthrottled online guesser (see docs/adr/0018) meaningfully more than a
 # short word does.
 _MIN_SECRET_LENGTH = 24
+_RETRIEVAL_GRANT_BYTES_LIMIT = 16 * 1024
 
 
 class Settings(BaseSettings):
@@ -63,6 +65,9 @@ class Settings(BaseSettings):
     # Auth
     api_bearer_token: str = Field(default="", repr=False)
     operator_token: SecretStr = SecretStr("")
+    retrieval_token: SecretStr | None = None
+    retrieval_session_id: NonEmptyId | None = None
+    retrieval_session_ids: Annotated[list[NonEmptyId] | None, NoDecode] = None
     ingest_tokens: Annotated[dict[str, SecretStr], NoDecode] = Field(
         default_factory=dict
     )
@@ -113,6 +118,48 @@ class Settings(BaseSettings):
     def _strip_operator_token(cls, value: SecretStr) -> SecretStr:
         return SecretStr(value.get_secret_value().strip())
 
+    @field_validator("retrieval_token")
+    @classmethod
+    def _strip_retrieval_token(cls, value: SecretStr | None) -> SecretStr | None:
+        return None if value is None else SecretStr(value.get_secret_value().strip())
+
+    @field_validator("retrieval_session_ids", mode="before")
+    @classmethod
+    def _parse_retrieval_sessions(cls, value):
+        if value is None:
+            return None
+        try:
+            encoded = (
+                value
+                if isinstance(value, str)
+                else json.dumps(value, ensure_ascii=False)
+            )
+            if len(encoded.encode("utf-8")) > _RETRIEVAL_GRANT_BYTES_LIMIT:
+                raise ValueError
+            if isinstance(value, str):
+                value = json.loads(value)
+            if (
+                not isinstance(value, list)
+                or not 1 <= len(value) <= CONTEXT_DISCOVERY_SESSION_LIMIT
+                or any(not isinstance(item, str) for item in value)
+            ):
+                raise ValueError
+            normalized = TypeAdapter(list[NonEmptyId]).validate_python(value)
+            if len(set(normalized)) != len(normalized):
+                raise ValueError
+        except (ValueError, TypeError, RecursionError):
+            raise ValueError(
+                "retrieval_session_ids must be a JSON array of 1–32 unique valid IDs within 16 KiB"
+            ) from None
+        return normalized
+
+    @property
+    def context_session_ids(self) -> tuple[NonEmptyId, ...]:
+        """The deployment grant, with no first-member singleton default."""
+        if self.retrieval_session_id is not None:
+            return (self.retrieval_session_id,)
+        return tuple(sorted(self.retrieval_session_ids or ()))
+
     @field_validator("ingest_tokens", mode="before")
     @classmethod
     def _parse_ingest_tokens(cls, value):
@@ -140,7 +187,7 @@ class Settings(BaseSettings):
             if (
                 not isinstance(client_id, str)
                 or not _CLIENT_ID.fullmatch(client_id)
-                or client_id in {"operator", "legacy"}
+                or client_id in {"operator", "legacy", "retrieval"}
             ):
                 raise ValueError(
                     "ingest_tokens contains an invalid or reserved client identifier"
@@ -152,6 +199,40 @@ class Settings(BaseSettings):
             normalized[client_id] = SecretStr(secret.strip())
         return normalized
 
+    @model_validator(mode="after")
+    def _validate_retrieval(self) -> "Settings":
+        # Agent read authority never inherits development-mode exemptions.
+        source_count = sum(
+            source is not None
+            for source in (self.retrieval_session_id, self.retrieval_session_ids)
+        )
+        if source_count != int(self.retrieval_token is not None):
+            raise ValueError(
+                "retrieval_token requires exactly one of retrieval_session_id or retrieval_session_ids"
+            )
+        if self.retrieval_token is None:
+            return self
+        token = self.retrieval_token.get_secret_value()
+        if (
+            token.lower() in _INSECURE_DEFAULTS
+            or len(token) < _MIN_SECRET_LENGTH
+            or any(not 33 <= ord(char) <= 126 for char in token)
+        ):
+            raise ValueError(
+                "retrieval_token must be a strong printable ASCII secret of at least 24 characters"
+            )
+        other_secrets = {
+            self.operator_token.get_secret_value(),
+            self.api_bearer_token,
+            self.github_webhook_secret,
+            *(secret.get_secret_value() for secret in self.ingest_tokens.values()),
+        }
+        if token in other_secrets:
+            raise ValueError(
+                "retrieval_token must differ from all other configured secrets"
+            )
+        return self
+
     def validate_production_security(self) -> list[str]:
         """Return human-readable security problems for a production boot.
 

{sediment_api-0.1.0 → sediment_api-0.3.0}/sediment_api/deps.py

@@ -19,7 +19,7 @@ from typing import Any
 
 from fastapi import Depends, Header, HTTPException, Request
 from sediment_capture import verify_signature
-from sediment_core import FactStore
+from sediment_core import EVIDENCE_REQUEST_BYTES_LIMIT, FactStore, NonEmptyId
 
 from .config import settings
 
@@ -31,6 +31,7 @@ from .config import settings
 # body before its auth dependency runs, so every door's read is pre-auth.
 # ponytail: fixed constant; make it a setting only if a non-GitHub forge needs it
 MAX_BODY_BYTES = 25 * 1024 * 1024
+CONTEXT_REQUEST_BYTES_LIMIT = 16 * 1024
 
 
 class BodySizeLimitMiddleware:
@@ -57,6 +58,24 @@ class BodySizeLimitMiddleware:
             await self.app(scope, receive, send)
             return
 
+        limit = MAX_BODY_BYTES
+        path = scope["path"]
+        root_path = scope.get("root_path", "")
+        if root_path and path.startswith(root_path + "/"):
+            path = path[len(root_path) :]
+        if scope["method"] == "POST" and path in {
+            "/query/evidence/read",
+            "/query/context/evidence/read",
+        }:
+            # FastAPI parses model envelopes before running dependencies. Keep
+            # this operation's smaller bound ahead of that allocation too.
+            limit = min(limit, EVIDENCE_REQUEST_BYTES_LIMIT)
+        elif scope["method"] == "POST" and path in {
+            "/query/context",
+            "/query/context/discover",
+            "/query/context/selected",
+        }:
+            limit = min(limit, CONTEXT_REQUEST_BYTES_LIMIT)
         received = 0
 
         async def capped_receive() -> Any:
@@ -66,25 +85,47 @@ class BodySizeLimitMiddleware:
                 received += len(message.get("body", b""))
                 # Module-global lookup on purpose: tests lower the cap by
                 # patching MAX_BODY_BYTES after the app is constructed.
-                if received > MAX_BODY_BYTES:
+                if received > limit:
                     raise HTTPException(
                         status_code=413, detail="request body too large"
                     )
             return message
 
-        await self.app(scope, capped_receive, send)
+        async def context_send(message: Any) -> None:
+            if message["type"] == "http.response.start":
+                message["headers"] = [
+                    (key, value)
+                    for key, value in message.get("headers", [])
+                    if key.lower() != b"cache-control"
+                ] + [(b"cache-control", b"no-store")]
+            await send(message)
+
+        await self.app(
+            scope,
+            capped_receive,
+            context_send
+            if path
+            in {
+                "/query/context/discover",
+                "/query/context/selected",
+                "/query/context/evidence",
+                "/query/context/evidence/manifest",
+                "/query/context/evidence/read",
+            }
+            else send,
+        )
 
 
 @dataclass(frozen=True)
 class CredentialIdentity:
     """Configured authority only; never a tenant or captured developer identity."""
 
-    authority: Literal["ingest", "operator"]
+    authority: Literal["ingest", "operator", "retrieval"]
     client_id: str
 
 
 def verify_token(authorization: str | None = Header(None)) -> CredentialIdentity:
-    """Authenticate either fixed authority without logging credential material."""
+    """Authenticate configured authorities without logging credential material."""
     scheme, _, credential = (authorization or "").partition(" ")
     credential = credential.strip()
     if scheme.lower() != "bearer" or not credential:
@@ -96,6 +137,12 @@ def verify_token(authorization: str | None = Header(None)) -> CredentialIdentity
             settings.operator_token.get_secret_value(),
             CredentialIdentity("operator", "operator"),
         ),
+        (
+            settings.retrieval_token.get_secret_value()
+            if settings.retrieval_token is not None
+            else "",
+            CredentialIdentity("retrieval", "retrieval"),
+        ),
         (settings.api_bearer_token, CredentialIdentity("ingest", "legacy")),
         *(
             (token.get_secret_value(), CredentialIdentity("ingest", client_id))
@@ -114,6 +161,8 @@ def verify_ingest_token(
     identity: CredentialIdentity = Depends(verify_token),
 ) -> CredentialIdentity:
     """Capture accepts ingest clients and explicit operator demonstrations."""
+    if identity.authority not in {"ingest", "operator"}:
+        raise HTTPException(status_code=403, detail="Ingest authority required")
     return identity
 
 
@@ -126,6 +175,36 @@ def verify_operator_token(
     return identity
 
 
+def verify_retrieval_token(
+    identity: CredentialIdentity = Depends(verify_token),
+) -> CredentialIdentity:
+    """Read the deployment's fixed source without broadening operator reads."""
+    if identity.authority not in {"retrieval", "operator"}:
+        raise HTTPException(status_code=403, detail="Retrieval authority required")
+    if settings.retrieval_session_id is None:
+        raise HTTPException(status_code=404, detail="Context retrieval is disabled")
+    return identity
+
+
+def verify_context_grant_token(
+    identity: CredentialIdentity = Depends(verify_token),
+) -> CredentialIdentity:
+    """Discovery and selection share the configured Session grant."""
+    if identity.authority not in {"retrieval", "operator"}:
+        raise HTTPException(status_code=403, detail="Retrieval authority required")
+    if not settings.context_session_ids:
+        raise HTTPException(status_code=404, detail="Context retrieval is disabled")
+    return identity
+
+
+def require_context_session(session_id: NonEmptyId) -> None:
+    """Refuse before any storage lookup, independent of Session existence."""
+    if session_id not in settings.context_session_ids:
+        raise HTTPException(
+            status_code=403, detail="Session is outside the context grant"
+        )
+
+
 def get_store(request: Request) -> FactStore:
     """Borrow the lifespan-owned PostgreSQL fact store for one request."""
     return request.app.state.fact_store

{sediment_api-0.1.0 → sediment_api-0.3.0}/sediment_api/main.py

@@ -185,6 +185,32 @@ async def validation_error_without_input(
     400/422, never 500. type/loc/msg are what a caller needs to fix the
     request; the offending input is theirs already.
     """
+    endpoint = getattr(request.scope.get("route"), "endpoint", None)
+    if endpoint in {
+        query.query_context_discover,
+        query.query_context_selected,
+        query.query_context_evidence_read,
+    } and any(error.get("type") == "json_invalid" for error in exc.errors()):
+        return JSONResponse(status_code=400, content={"detail": "Malformed JSON body"})
+    if endpoint in {
+        query.query_context_evidence_inventory,
+        query.query_context_evidence_manifest,
+        query.query_context_evidence_read,
+    }:
+        # Exact references reuse the operator envelope. Its error locations can
+        # contain arbitrary extra keys; keep the scoped boundary content-free.
+        return JSONResponse(
+            status_code=422,
+            content={
+                "detail": [
+                    {
+                        "type": "value_error",
+                        "loc": [],
+                        "msg": "Invalid evidence request",
+                    }
+                ]
+            },
+        )
     detail = [
         {"type": e.get("type", ""), "loc": e.get("loc", ()), "msg": e.get("msg", "")}
         for e in exc.errors()