pramana-store 0.0.1__tar.gz

pramana_store-0.0.1/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.pyc
+.pramana/
+.pytest_cache/
+web/node_modules/
+web/dist/
+# Secrets. The trailing slash this line used to have (`.env/`) matched only a
+# *directory* named .env, never the file — which is how .env ended up committed
+# in a1434d1 with a live Postgres password and S3 keys in it. Adding it here
+# does not remove it from history: those credentials must be rotated, and the
+# commit purged, separately.
+.env
+.env.*
+!.env.example

pramana_store-0.0.1/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.5
+Name: pramana-store
+Version: 0.0.1
+Requires-Python: >=3.12
+Requires-Dist: boto3>=1.34
+Requires-Dist: pramana-core
+Requires-Dist: pramana-proto
+Requires-Dist: psycopg[binary,pool]>=3.2

pramana_store-0.0.1/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "pramana-store"
+version = "0.0.1"
+requires-python = ">=3.12"
+dependencies = [
+  "pramana-core",
+  "pramana-proto",
+  "psycopg[binary,pool]>=3.2",
+  "boto3>=1.34",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pramana_store"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[dependency-groups]
+dev = ["pytest"]

pramana_store-0.0.1/src/pramana_store/apikeys.py

@@ -0,0 +1,83 @@
+"""API-key resolution, shared by every service that authenticates one.
+
+Lives here rather than in `services/api` because this package already owns the
+`api_keys` table (schema.sql) and both `services/api` and `services/ingest`
+already depend on it. The alternative — ingest re-implementing the lookup —
+means two definitions of "is this key still valid", and the one that drifts is
+the one that keeps accepting revoked keys.
+
+Only the hash is ever stored, so a key's plaintext cannot be recovered from
+this table; `hash_key` is the single definition of how a presented secret maps
+onto a stored row.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import threading
+import time
+
+from psycopg.rows import dict_row
+
+from pramana_store.postgres import pooled_connect
+
+# Every authenticated request paid its own round-trip here before doing any
+# actual work — against a Postgres with real network latency (a pooler across
+# a real hop; docs/plan.md §21.1 measured 525ms per query to Supabase) that was
+# roughly half of every endpoint's total latency, just to answer a question
+# that almost never changes between two requests a few seconds apart.
+#
+# Cost of caching it: a revoked key keeps authenticating for up to
+# `_CACHE_TTL_S` after revocation, since revoke_api_key() only has a key_id,
+# not the secret whose hash keys this cache, so it cannot evict on revoke.
+# 60s is the accepted ceiling for that window; make revocation write-through
+# if that stops being acceptable.
+_CACHE_TTL_S = 60.0
+_cache: dict[tuple[str, str], tuple[tuple[str, str] | None, float]] = {}
+_cache_lock = threading.Lock()
+
+# Roles allowed to *write* events. An auditor key is read-only by design
+# (docs/PROJECT_SCOPE.md §3: auditors see structure and divergences, never raw
+# payloads) — handing one to an SDK would let it author the very trace its
+# holder is only supposed to inspect.
+WRITER_ROLES = frozenset({"admin", "engineer"})
+
+
+def hash_key(secret: str) -> str:
+    return hashlib.sha256(secret.encode()).hexdigest()
+
+
+def resolve_key(conninfo: str, secret: str) -> tuple[str, str] | None:
+    """Returns (tenant_id, role) for a live key, or None if it is unknown or revoked.
+
+    Cached for `_CACHE_TTL_S` (see module docstring for the revocation-window
+    tradeoff this accepts). A miss (unknown/bad key) is cached too — a client
+    hammering a stale key would otherwise spend a full round-trip per attempt.
+    """
+    key_hash = hash_key(secret)
+    cache_key = (conninfo, key_hash)  # tests point different conninfos at the same hash
+    now = time.monotonic()
+    with _cache_lock:
+        cached = _cache.get(cache_key)
+        if cached is not None and cached[1] > now:
+            return cached[0]
+
+    with pooled_connect(conninfo, row_factory=dict_row) as conn:
+        row = conn.execute(
+            "SELECT tenant_id, role FROM api_keys WHERE hash = %s AND revoked_at IS NULL",
+            (key_hash,),
+        ).fetchone()
+    result = (str(row["tenant_id"]), str(row["role"])) if row else None
+
+    with _cache_lock:
+        _cache[cache_key] = (result, now + _CACHE_TTL_S)
+    return result
+
+
+def invalidate(conninfo: str, key_hash: str) -> None:
+    """Evict one cached resolution immediately — call this from the revoke
+    path so a revoked key stops working right away instead of riding out
+    `_CACHE_TTL_S`. Safe to call for a hash that was never cached.
+    """
+    with _cache_lock:
+        _cache.pop((conninfo, key_hash), None)

pramana_store-0.0.1/src/pramana_store/blob.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import hashlib
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import boto3
+
+from pramana_store.ports import BlobStore
+
+
+def _key(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+# One boto3 client per (endpoint, region) — request handlers construct a
+# fresh S3BlobStore per call (it's tenant-scoped, tenant varies per
+# request), but the underlying client is stateless w.r.t. tenant and
+# reopening it every time paid a full TLS handshake per request against a
+# remote endpoint (Supabase Storage) that a local MinIO/mock never surfaced.
+_S3_CLIENTS: dict[tuple[str | None, str | None], Any] = {}
+
+
+def _s3_client(endpoint_url: str | None, region_name: str | None) -> Any:
+    key = (endpoint_url, region_name)
+    client = _S3_CLIENTS.get(key)
+    if client is None:
+        # region_name: SigV4 (what every S3-compatible provider uses,
+        # including Supabase Storage) signs requests with a region baked in
+        # — omitting it relies on boto3/AWS_DEFAULT_REGION being set, which a
+        # fresh environment usually hasn't.
+        #
+        # max_pool_connections: botocore defaults to 10, which throttled the
+        # payloads-batch route's concurrent blob fetches (docs/plan.md §22) —
+        # the route fires up to 16 GETs in parallel, but only 10 could hold a
+        # pooled HTTP connection at once, so the rest queued behind them in
+        # waves instead of actually running concurrently. Raised to comfortably
+        # cover that batch size.
+        from botocore.config import Config
+
+        client = _S3_CLIENTS[key] = boto3.client(
+            "s3", endpoint_url=endpoint_url, region_name=region_name, config=Config(max_pool_connections=32)
+        )
+    return client
+
+
+class S3BlobStore:
+    """Phase 0 `BlobStore` (docs/plan.md §4) — MinIO locally, S3 in cloud,
+    same code path both ways (docs/plan.md §2).
+    """
+
+    def __init__(
+        self,
+        bucket: str,
+        endpoint_url: str | None = None,
+        region_name: str | None = None,
+        tenant_id: str = "",
+    ):
+        if not tenant_id:
+            raise ValueError("tenant_id is required")
+        self._bucket = bucket
+        self._tenant_id = tenant_id
+        self._s3 = _s3_client(endpoint_url, region_name)
+
+    def _object_key(self, key: str) -> str:
+        return f"{self._tenant_id}/blobs/{key}"
+
+    def put(self, data: bytes) -> str:
+        key = _key(data)
+        self._s3.put_object(Bucket=self._bucket, Key=self._object_key(key), Body=data)
+        return key
+
+    def get(self, key: str) -> bytes:
+        obj = self._s3.get_object(Bucket=self._bucket, Key=self._object_key(key))
+        return bytes(obj["Body"].read())  # boto3 has no usable stubs; .read() types as Any
+
+    def delete(self, key: str) -> None:
+        self._s3.delete_object(Bucket=self._bucket, Key=self._object_key(key))
+        # S3's delete_object is already idempotent (204 whether or not the key
+        # existed) — no not-found error to translate here.
+
+
+class LocalBlobStore:
+    """Test adapter named explicitly in docs/plan.md §4 ("LocalBlobStore
+    (tests)"). Filesystem-backed, same content-addressing scheme.
+    """
+
+    def __init__(self, root: Path | str, tenant_id: str = ""):
+        if not tenant_id:
+            raise ValueError("tenant_id is required")
+        self._root = Path(root) / tenant_id / "blobs"
+        self._root.mkdir(parents=True, exist_ok=True)
+
+    def put(self, data: bytes) -> str:
+        key = _key(data)
+        path = self._root / key
+        if not path.exists():
+            path.write_bytes(data)
+        return key
+
+    def get(self, key: str) -> bytes:
+        path = self._root / key
+        if not path.exists():
+            raise KeyError(key)
+        return path.read_bytes()
+
+    def delete(self, key: str) -> None:
+        path = self._root / key
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            raise KeyError(key) from None
+
+
+def blob_store_factory_from_env() -> Callable[[str], BlobStore]:
+    """Shared by `api` and `ingest` `__main__` boot code so both point at the
+    same backend from the same env vars — local disk only works when both
+    services share a filesystem (e.g. the `make dev` bind mount); a real
+    multi-machine deployment needs `PRAMANA_BLOB_BACKEND=s3`.
+    """
+    backend = os.environ.get("PRAMANA_BLOB_BACKEND", "local")
+    if backend == "s3":
+        bucket = os.environ["PRAMANA_S3_BUCKET"]
+        endpoint_url = os.environ.get("PRAMANA_S3_ENDPOINT_URL")
+        region_name = os.environ.get("PRAMANA_S3_REGION")
+        return lambda tenant_id: S3BlobStore(
+            bucket, endpoint_url=endpoint_url, region_name=region_name, tenant_id=tenant_id
+        )
+    if backend != "local":
+        raise ValueError(f"unknown PRAMANA_BLOB_BACKEND: {backend!r}")
+    blob_dir = os.environ.get("PRAMANA_API_BLOB_DIR", ".pramana/blobs")
+    return lambda tenant_id: LocalBlobStore(blob_dir, tenant_id=tenant_id)

pramana_store-0.0.1/src/pramana_store/plans.py

@@ -0,0 +1,89 @@
+"""Plan limits (docs/PROJECT_SCOPE.md §6), shared by every service that
+needs to know what a tenant's plan allows.
+
+Lives here, not in `pramana_api.billing`, specifically so `services/ingest`
+can enforce the monthly event cap without depending on the whole api
+service (accounts, Stripe, team management) — the same reason
+`pramana_store.apikeys` exists instead of ingest importing `pramana_api`'s
+auth module. `pramana_api.billing` re-exports everything here and adds the
+write-side operations (`set_plan`, seat checks, Stripe linkage) that only
+the api service needs.
+
+ponytail: a plain dict, not a Plan class hierarchy — a handful of plans with
+the same five fields each doesn't earn an abstraction yet.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from pramana_store.postgres import pooled_connect
+
+DEFAULT_PLAN = "free"
+
+PLANS: dict[str, dict[str, Any]] = {
+    "free": {
+        "display_name": "Free",
+        "price_usd_per_month": 0,
+        "evidence_export": False,
+        "max_seats": 3,
+        "retention_days": 30,
+        # Nothing else bounds ingest volume for a free tenant — the
+        # per-tenant rate limiter (services/ingest) is a flat abuse-prevention
+        # ceiling, the same for every plan, not a billing differentiator. A
+        # single chatty free-tier key could otherwise ingest indefinitely at
+        # that ceiling for the whole 30-day retention window at real
+        # infrastructure cost and zero revenue. This is the actual cost
+        # driver (Postgres rows, S3 blobs, compute) that flat-tier pricing
+        # otherwise leaves completely unbounded.
+        "monthly_event_cap": 50_000,
+    },
+    "pro": {
+        "display_name": "Pro",
+        "price_usd_per_month": 99,
+        "evidence_export": True,
+        "max_seats": 10,
+        "retention_days": 365,
+        "monthly_event_cap": 2_000_000,
+    },
+    "enterprise": {
+        "display_name": "Enterprise",
+        # None means "contact sales" / "unlimited", not zero — same
+        # convention as max_seats/retention_days below.
+        "price_usd_per_month": None,
+        "evidence_export": True,
+        "max_seats": None,
+        "retention_days": None,
+        "monthly_event_cap": None,
+    },
+}
+
+
+class UnknownPlanError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class PlanLimits:
+    plan: str
+    display_name: str
+    price_usd_per_month: int | None
+    evidence_export: bool
+    max_seats: int | None
+    retention_days: int | None
+    monthly_event_cap: int | None
+
+
+def plan_limits(plan: str) -> PlanLimits:
+    if plan not in PLANS:
+        raise UnknownPlanError(f"plan must be one of {sorted(PLANS)}, got {plan!r}")
+    return PlanLimits(plan=plan, **PLANS[plan])
+
+
+def get_plan(conninfo: str, tenant_id: str) -> str:
+    with pooled_connect(conninfo) as conn:
+        row = conn.execute("SELECT plan FROM tenants WHERE id = %s", (tenant_id,)).fetchone()
+    if row is None:
+        raise ValueError(f"no such tenant: {tenant_id!r}")
+    return str(row[0])

pramana_store-0.0.1/src/pramana_store/ports.py

@@ -0,0 +1,96 @@
+"""Two of the three seams named in docs/plan.md §4. Bare-noun Protocols, no
+`I`/`Base` prefix. Each has (or is committed to have) >=2 real implementations.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from pramana_proto.v1.event_pb2 import Event
+
+
+class EventRepository(Protocol):
+    """Constructed with tenant_id — there is no query method that can forget
+    the tenant filter (docs/plan.md §4, "multi-tenancy is enforced structurally").
+    """
+
+    def append_if_new(self, event: Event) -> tuple[Event, bool]:
+        """Insert (tenant_id, event_id) if new; seals the hash chain itself
+        (prev_hash/this_hash are computed here, not supplied by the caller —
+        docs/plan.md D2). Returns (stored_event, was_new). On conflict,
+        returns the existing row unchanged (idempotent no-op).
+        """
+        ...
+
+    def chain_head(self, trace_id: str) -> str:
+        """Current this_hash at the head of trace_id's chain, or "" (genesis)."""
+        ...
+
+    def monthly_usage(self) -> int:
+        """Events accepted for this tenant in the current UTC month."""
+        ...
+
+    def get_by_call_site(
+        self, trace_id: str, agent_id: str, call_site_id: str, call_site_ordinal: int
+    ) -> Event | None: ...
+
+    def list_by_trace(self, trace_id: str) -> list[Event]: ...
+
+    def record_divergence(
+        self,
+        *,
+        trace_id: str,
+        agent_id: str,
+        call_site_id: str,
+        call_site_ordinal: int,
+        expected_input_hash: str,
+        actual_input_hash: str,
+        actual_input_ref: str = "",
+    ) -> None:
+        """Divergence is a product feature (docs/LLD.md §4b), not a fault —
+        recorded regardless of policy (HARD_STOP still raises after this)."""
+        ...
+
+    def list_divergences(self, trace_id: str) -> list[dict[str, Any]]: ...
+
+    def get_by_seq(self, trace_id: str, logical_seq: int, agent_id: str | None = None) -> Event | None: ...
+
+    def list_traces(self, limit: int = 200, before_started_at_ns: int | None = None) -> list[dict[str, Any]]: ...
+
+    def list_by_trace_range(self, trace_id: str, from_seq: int, to_seq: int) -> list[Event]: ...
+
+    def save_evidence_bundle(
+        self,
+        *,
+        bundle_id: str,
+        trace_id: str,
+        from_seq: int,
+        to_seq: int,
+        merkle_root: str,
+        signature: str,
+        blob_ref: str,
+    ) -> None: ...
+
+    def get_evidence_bundle(self, bundle_id: str) -> dict[str, Any] | None: ...
+
+    def list_evidence_bundles(self, trace_id: str) -> list[dict[str, Any]]: ...
+
+    def get_agent_graph(self, trace_id: str | None = None) -> list[dict[str, Any]]: ...
+
+
+class BlobStore(Protocol):
+    """Content-addressed: key = sha256(bytes). Put is idempotent."""
+
+    def put(self, data: bytes) -> str:
+        """Returns the content-addressed key."""
+        ...
+
+    def get(self, key: str) -> bytes: ...
+
+    def delete(self, key: str) -> None:
+        """Retention (docs/plan.md §21.3) calls this only after confirming no
+        surviving event still references `key` — safe to raise KeyError /
+        FileNotFoundError on a missing key, the caller treats that as already
+        deleted rather than an error.
+        """
+        ...