openom-mcp 0.1.0__tar.gz

openom_mcp-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+# --- OpenOM repo hygiene (see CLAUDE.md Rule 2) ---
+
+# Marketing mock - NEVER committed
+OpenOM - Make your deal legible to the buy-side's AI.htm
+OpenOM - Make your deal legible to the buy-side's AI_files/
+
+# Planning scratch - git-ignored by rule
+docs/superpowers/
+.planning/
+
+# Eval / tooling scratch
+.deepeval/
+
+# Real OM corpus - private test fixtures, never committed (confidential)
+OMs/
+
+# --- Python (/core, /cli, /mcp) ---
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# --- Node / TS (/js, /extension) ---
+node_modules/
+*.tsbuildinfo
+.npm/
+extension/src/generated/
+extension/test-results/
+extension/playwright-report/
+
+# --- OS / editor ---
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+coverage/
+extension/*.zip
+
+js/test-results/
+
+# marketing mock (Rule 2 - never commit)
+*.htm
+*_files/
+.playwright-mcp/
+om-normative-spec-draft-v0.1.md
+om-standard-handoff-v4-updated.md
+recon.md
+openOM-decision-memo.md
+
+# audit/backlog scratch is temp - lives in .planning/ (see Rule 2)
+/BACKLOG.md
+/*-audit*.md

openom_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: openom-mcp
+Version: 0.1.0
+Summary: openOM MCP server - deterministic tool surface over openom-core. Zero inference, ever.
+Project-URL: Homepage, https://openom.app
+Project-URL: Documentation, https://openom.app/docs/grounding-ai
+Project-URL: Repository, https://github.com/Vervelio-Labs/OpenOM
+License-Expression: MIT
+Keywords: ai-agents,commercial-real-estate,cre,json-ld,mcp,model-context-protocol,offering-memorandum,open-standard,openom,proptech
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.0
+Requires-Dist: openom-core[render]<0.2,>=0.1
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: boto3>=1.34; extra == 'dev'
+Requires-Dist: fakeredis>=2.20; extra == 'dev'
+Requires-Dist: moto[s3]>=5; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: r2
+Requires-Dist: boto3>=1.34; extra == 'r2'
+Description-Content-Type: text/markdown
+
+# openom-mcp
+
+A thin, **deterministic** [FastMCP](https://github.com/jlowin/fastmcp) server over
+[`openom-core`](../core) - six data verbs, zero inference:
+`om_inspect · om_extract_text · om_extract_images · om_read · om_validate · om_embed`, plus one
+hosted-transport helper `om_request_upload` (reserves a presigned upload target; HTTP transport only).
+So `tools/list` reports **seven** tools.
+Two transports: **stdio** (`om-mcp`) and **hosted Streamable HTTP** (`om-mcp-http`, SSRF-guarded,
+rate-limited, untrusted-parse-isolated).
+
+```sh
+pip install openom-mcp           # depends on openom-core (also from PyPI)
+# from a clone (openom-core is not yet on PyPI): install core first, then mcp:
+pip install -e ./core && pip install -e "./mcp[dev]"
+```
+
+## Connect it to an MCP client (stdio)
+
+Add to your client's MCP config (e.g. Claude Desktop `claude_desktop_config.json`, or any
+`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "openom": { "command": "om-mcp" }
+  }
+}
+```
+
+## Hosted HTTP
+
+`om-mcp-http` serves Streamable HTTP at the **`/mcp`** path (e.g. `http://127.0.0.1:8080/mcp`). By
+default it binds **loopback** (`127.0.0.1:8080`) - safe out of the box, not a world-open server. The
+free **public grounding endpoint** at `https://mcp.openom.app/mcp` is a serverless Cloudflare Worker
+(`/mcp-worker`) exposing the read-side `om_read` + `om_validate` via the byte-parity `/js` core; run
+`om-mcp-http` yourself for the full six-tool surface (extract/embed/inspect). Two-tier validation:
+schema errors block, consistency warnings never do; market truth is out of scope.
+
+**Tool inputs.** The PDF-taking tools (`om_inspect`/`om_read`/`om_extract_*`/`om_embed`) accept a
+`pdf` object that is exactly one of: `{"path": "..."}` (stdio, a local file), `{"url": "https://..."}`
+(HTTP transport, fetched under the SSRF rules), or `{"blobId": "..."}` (HTTP, a prior
+`om_request_upload`). `om_validate` takes a `payload` object.
+
+**Stability.** The seven-tool surface + result shapes are versioned with the spec (`specVersion`
+`0.1`); the `om_read`/`om_validate` shapes match the public Worker ([Ma9]). Breaking tool-surface
+changes ship under a new spec minor. See the repo `spec/CHANGELOG.md`.
+
+### Configuration (env)
+
+Every knob is an environment variable; defaults are safe for local use:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `OPENOM_MCP_HOST` | `127.0.0.1` | Bind address. Set `0.0.0.0` to expose publicly. |
+| `OPENOM_MCP_PORT` | `8080` | Bind port. |
+| `OPENOM_MCP_DNS_REBINDING` | auto | Host/Origin DNS-rebinding defense. **Auto-ON when bound to a non-loopback host.** |
+| `OPENOM_MCP_ALLOWED_HOSTS` | *(empty)* | Comma-separated Host allowlist (set this when binding publicly). |
+| `OPENOM_MCP_ALLOWED_ORIGINS` | *(empty)* | Comma-separated Origin allowlist. |
+| `OPENOM_MCP_RATE_LIMIT` / `_WINDOW` | `120` / `60` | Per-principal request cap per window (seconds). |
+| `OPENOM_MCP_MAX_FETCH_BYTES` | `209715200` | Cap on fetched PDF size (SSRF/DoS guard). |
+| `OPENOM_MCP_MAX_PAGES` | *(unset)* | Per-call page ceiling for extraction. |
+| `OPENOM_MCP_LOG` | - | Log level. |
+
+When you bind publicly (`0.0.0.0`) always set `OPENOM_MCP_ALLOWED_HOSTS`/`_ORIGINS` - the server logs
+a warning if you don't.
+
+**Production backends (env-selectable):**
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `OPENOM_MCP_BLOB_BACKEND` | `local` | `r2` uses Cloudflare R2/S3 (needs `OPENOM_R2_BUCKET`, `OPENOM_R2_ENDPOINT`, `OPENOM_R2_ACCESS_KEY`, `OPENOM_R2_SECRET_KEY`; `boto3` extra). |
+| `OPENOM_MCP_LIMITER` | `memory` | `redis` uses a shared Redis so multiple replicas enforce one global limit (needs `OPENOM_REDIS_URL`; a `redis`-py-compatible client). |
+
+(Both `boto3` and `redis` are imported lazily - neither is a hard dependency.) For anything further,
+`build_http_app(...)` accepts `blob_store` / `rate_limiter` injections directly.
+
+## Grounding an AI agent
+
+Treat an openOM payload as the broker's **asserted opinion**, not fact: attribute every figure to
+`assertedBy` as of `assertedDate`, don't use a payload whose `verification.hashValid` isn't true,
+and never present an OM figure as verified truth (an OM is an advertisement / opinion of value). The
+full guide - MCP config, tool usage, and a system-prompt snippet - is
+**[Grounding AI agents in openOM](../site/openom/docs/grounding-ai.html)** (served at
+`…/openom/docs/grounding-ai.html`).
+
+Tests: `pytest mcp -q`.

openom_mcp-0.1.0/README.md

@@ -0,0 +1,86 @@
+# openom-mcp
+
+A thin, **deterministic** [FastMCP](https://github.com/jlowin/fastmcp) server over
+[`openom-core`](../core) - six data verbs, zero inference:
+`om_inspect · om_extract_text · om_extract_images · om_read · om_validate · om_embed`, plus one
+hosted-transport helper `om_request_upload` (reserves a presigned upload target; HTTP transport only).
+So `tools/list` reports **seven** tools.
+Two transports: **stdio** (`om-mcp`) and **hosted Streamable HTTP** (`om-mcp-http`, SSRF-guarded,
+rate-limited, untrusted-parse-isolated).
+
+```sh
+pip install openom-mcp           # depends on openom-core (also from PyPI)
+# from a clone (openom-core is not yet on PyPI): install core first, then mcp:
+pip install -e ./core && pip install -e "./mcp[dev]"
+```
+
+## Connect it to an MCP client (stdio)
+
+Add to your client's MCP config (e.g. Claude Desktop `claude_desktop_config.json`, or any
+`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "openom": { "command": "om-mcp" }
+  }
+}
+```
+
+## Hosted HTTP
+
+`om-mcp-http` serves Streamable HTTP at the **`/mcp`** path (e.g. `http://127.0.0.1:8080/mcp`). By
+default it binds **loopback** (`127.0.0.1:8080`) - safe out of the box, not a world-open server. The
+free **public grounding endpoint** at `https://mcp.openom.app/mcp` is a serverless Cloudflare Worker
+(`/mcp-worker`) exposing the read-side `om_read` + `om_validate` via the byte-parity `/js` core; run
+`om-mcp-http` yourself for the full six-tool surface (extract/embed/inspect). Two-tier validation:
+schema errors block, consistency warnings never do; market truth is out of scope.
+
+**Tool inputs.** The PDF-taking tools (`om_inspect`/`om_read`/`om_extract_*`/`om_embed`) accept a
+`pdf` object that is exactly one of: `{"path": "..."}` (stdio, a local file), `{"url": "https://..."}`
+(HTTP transport, fetched under the SSRF rules), or `{"blobId": "..."}` (HTTP, a prior
+`om_request_upload`). `om_validate` takes a `payload` object.
+
+**Stability.** The seven-tool surface + result shapes are versioned with the spec (`specVersion`
+`0.1`); the `om_read`/`om_validate` shapes match the public Worker ([Ma9]). Breaking tool-surface
+changes ship under a new spec minor. See the repo `spec/CHANGELOG.md`.
+
+### Configuration (env)
+
+Every knob is an environment variable; defaults are safe for local use:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `OPENOM_MCP_HOST` | `127.0.0.1` | Bind address. Set `0.0.0.0` to expose publicly. |
+| `OPENOM_MCP_PORT` | `8080` | Bind port. |
+| `OPENOM_MCP_DNS_REBINDING` | auto | Host/Origin DNS-rebinding defense. **Auto-ON when bound to a non-loopback host.** |
+| `OPENOM_MCP_ALLOWED_HOSTS` | *(empty)* | Comma-separated Host allowlist (set this when binding publicly). |
+| `OPENOM_MCP_ALLOWED_ORIGINS` | *(empty)* | Comma-separated Origin allowlist. |
+| `OPENOM_MCP_RATE_LIMIT` / `_WINDOW` | `120` / `60` | Per-principal request cap per window (seconds). |
+| `OPENOM_MCP_MAX_FETCH_BYTES` | `209715200` | Cap on fetched PDF size (SSRF/DoS guard). |
+| `OPENOM_MCP_MAX_PAGES` | *(unset)* | Per-call page ceiling for extraction. |
+| `OPENOM_MCP_LOG` | - | Log level. |
+
+When you bind publicly (`0.0.0.0`) always set `OPENOM_MCP_ALLOWED_HOSTS`/`_ORIGINS` - the server logs
+a warning if you don't.
+
+**Production backends (env-selectable):**
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `OPENOM_MCP_BLOB_BACKEND` | `local` | `r2` uses Cloudflare R2/S3 (needs `OPENOM_R2_BUCKET`, `OPENOM_R2_ENDPOINT`, `OPENOM_R2_ACCESS_KEY`, `OPENOM_R2_SECRET_KEY`; `boto3` extra). |
+| `OPENOM_MCP_LIMITER` | `memory` | `redis` uses a shared Redis so multiple replicas enforce one global limit (needs `OPENOM_REDIS_URL`; a `redis`-py-compatible client). |
+
+(Both `boto3` and `redis` are imported lazily - neither is a hard dependency.) For anything further,
+`build_http_app(...)` accepts `blob_store` / `rate_limiter` injections directly.
+
+## Grounding an AI agent
+
+Treat an openOM payload as the broker's **asserted opinion**, not fact: attribute every figure to
+`assertedBy` as of `assertedDate`, don't use a payload whose `verification.hashValid` isn't true,
+and never present an OM figure as verified truth (an OM is an advertisement / opinion of value). The
+full guide - MCP config, tool usage, and a system-prompt snippet - is
+**[Grounding AI agents in openOM](../site/openom/docs/grounding-ai.html)** (served at
+`…/openom/docs/grounding-ai.html`).
+
+Tests: `pytest mcp -q`.

openom_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openom-mcp"
+version = "0.1.0"
+description = "openOM MCP server - deterministic tool surface over openom-core. Zero inference, ever."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+keywords = [
+  "openom", "mcp", "model-context-protocol", "offering-memorandum", "commercial-real-estate",
+  "cre", "proptech", "json-ld", "open-standard", "ai-agents",
+]
+# openom-core pinned to the same 0.x spec line (SemVer: a 0.2 core may change the payload contract).
+dependencies = ["openom-core[render]>=0.1,<0.2", "mcp>=2.0,<3", "httpx>=0.27", "uvicorn>=0.30"]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8", "pytest-cov>=5", "mypy>=1.10", "ruff>=0.5", "boto3>=1.34", "moto[s3]>=5",
+  "fakeredis>=2.20",  # exercise RedisCounterStore without a live server (#51/#52)
+]
+r2 = ["boto3>=1.34"]  # S3BlobStore (R2) adapter - runtime extra for a real deployment
+
+[project.urls]
+Homepage = "https://openom.app"
+Documentation = "https://openom.app/docs/grounding-ai"
+Repository = "https://github.com/Vervelio-Labs/OpenOM"
+
+[project.scripts]
+om-mcp = "openom_mcp.server:main"
+om-mcp-http = "openom_mcp.server:main_http"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openom_mcp"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "W"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]
+# The MCP server SDK exposes an untyped @tool() decorator; the tool fns themselves are fully typed.
+disallow_untyped_decorators = false
+# boto3/botocore ship no py.typed; when installed (CI) mypy emits import-untyped attributed to the
+# IMPORTING file (openom_mcp.blobstore), so it must be disabled globally, not on the boto3 override.
+disable_error_code = ["import-untyped"]
+
+[[tool.mypy.overrides]]
+# Third-party SDK + OPTIONAL runtime deps (boto3/uvicorn/redis are lazy extras, absent in the base
+# env). ignore_missing_imports keeps mypy green whether or not they're installed - no per-line,
+# env-fragile `type: ignore` comments needed.
+module = [
+    "mcp", "mcp.*", "pymupdf", "pymupdf.*",
+    "boto3", "botocore", "botocore.*", "uvicorn", "redis",
+]
+ignore_missing_imports = true
+follow_imports = "skip"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.coverage.run]
+source = ["openom_mcp"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = ["pragma: no cover", "if __name__"]

openom_mcp-0.1.0/src/openom_mcp/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: MIT
+"""openOM MCP server (spec §I) over the deterministic core. Zero inference, ever."""

openom_mcp-0.1.0/src/openom_mcp/apikeys.py

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: MIT
+"""API-key lifecycle for the hosted transport (#52): issue/verify/rotate/revoke + per-key quota.
+
+Deterministic logic over a pluggable ``KeyStore`` (+ the ``CounterStore`` seam from ratelimit.py for
+quota accounting). The hosted deploy binds a real KV/DB + Redis; ``InMemoryKeyStore`` is the
+test/self-host impl. No inference - this is the paid instance's access layer over the
+same deterministic engine.
+
+Security posture: the plaintext key (``omk_<token>``) is shown EXACTLY ONCE, at issue; only its
+SHA-256 hash is ever stored or logged. Verification is hash-lookup + status check; rotation issues a
+new key and revokes the old; revocation is immediate. Quota is a per-key volume cap over a window,
+distinct from the short-window burst rate limit.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from typing import Literal, Protocol
+
+from .ratelimit import CounterStore
+from .tools import ToolError
+
+KEY_PREFIX = "omk_"
+KeyStatus = Literal["active", "revoked"]
+
+
+def hash_key(plaintext: str) -> str:
+    """The stored/loggable identifier for a key: its SHA-256 hex. Never store the plaintext."""
+    return hashlib.sha256(plaintext.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class ApiKeyRecord:
+    key_id: str  # public, non-secret handle (safe to show in a dashboard/logs)
+    key_hash: str  # sha256(plaintext); the lookup key
+    owner: str  # principal that owns the key
+    created: float
+    status: KeyStatus = "active"
+    quota_limit: int = 0  # max calls per quota window; 0 = unlimited
+    quota_window_seconds: int = 86_400  # default: per day
+    revoked_at: float | None = None
+
+
+class KeyStore(Protocol):
+    """Persistence seam. The hosted deploy backs this with a KV/DB; tests use InMemoryKeyStore."""
+
+    def get_by_hash(self, key_hash: str) -> ApiKeyRecord | None: ...
+    def get_by_id(self, key_id: str) -> ApiKeyRecord | None: ...
+    def put(self, record: ApiKeyRecord) -> None: ...
+
+
+class InMemoryKeyStore:
+    """Single-process KeyStore for tests / self-host."""
+
+    def __init__(self) -> None:
+        self._by_hash: dict[str, ApiKeyRecord] = {}
+        self._by_id: dict[str, ApiKeyRecord] = {}
+
+    def get_by_hash(self, key_hash: str) -> ApiKeyRecord | None:
+        return self._by_hash.get(key_hash)
+
+    def get_by_id(self, key_id: str) -> ApiKeyRecord | None:
+        return self._by_id.get(key_id)
+
+    def put(self, record: ApiKeyRecord) -> None:
+        self._by_hash[record.key_hash] = record
+        self._by_id[record.key_id] = record
+
+
+class ApiKeyManager:
+    """Issue / verify / rotate / revoke API keys and enforce per-key quota."""
+
+    def __init__(
+        self,
+        store: KeyStore,
+        counters: CounterStore,
+        *,
+        now: Callable[[], float] = time.time,
+        rng: Callable[[], str] = lambda: secrets.token_urlsafe(24),
+    ) -> None:
+        self.store = store
+        self.counters = counters
+        self.now = now
+        self._rng = rng  # injectable for deterministic tests
+
+    def issue(
+        self, owner: str, *, quota_limit: int = 0, quota_window_seconds: int = 86_400
+    ) -> tuple[str, ApiKeyRecord]:
+        """Mint a new key for ``owner``. Returns (plaintext_shown_once, record). Store keeps only
+        the hash - the plaintext is unrecoverable after this call."""
+        plaintext = KEY_PREFIX + self._rng()
+        record = ApiKeyRecord(
+            key_id="k_" + secrets.token_hex(8),
+            key_hash=hash_key(plaintext),
+            owner=owner,
+            created=self.now(),
+            quota_limit=quota_limit,
+            quota_window_seconds=quota_window_seconds,
+        )
+        self.store.put(record)
+        return plaintext, record
+
+    def verify(self, plaintext: str) -> ApiKeyRecord | None:
+        """Return the ACTIVE record for a plaintext key, or None (unknown / revoked / malformed)."""
+        if not plaintext.startswith(KEY_PREFIX):
+            return None
+        record = self.store.get_by_hash(hash_key(plaintext))
+        if record is None or record.status != "active":
+            return None
+        return record
+
+    def revoke(self, key_id: str) -> bool:
+        """Immediately deactivate a key. Returns True if a key was revoked, False if unknown."""
+        record = self.store.get_by_id(key_id)
+        if record is None or record.status == "revoked":
+            return False
+        self.store.put(replace(record, status="revoked", revoked_at=self.now()))
+        return True
+
+    def rotate(self, key_id: str) -> tuple[str, ApiKeyRecord] | None:
+        """Issue a replacement key for the same owner (same quota policy) and revoke the old one.
+        Returns the new (plaintext, record), or None if ``key_id`` is unknown."""
+        old = self.store.get_by_id(key_id)
+        if old is None:
+            return None
+        new = self.issue(
+            old.owner,
+            quota_limit=old.quota_limit,
+            quota_window_seconds=old.quota_window_seconds,
+        )
+        self.revoke(key_id)
+        return new
+
+    def check_quota(self, record: ApiKeyRecord) -> None:
+        """Count one call against the key's quota window; raise OM-IO-014 when the cap is exceeded.
+        A key with ``quota_limit == 0`` is unlimited (only the burst rate limit applies)."""
+        if record.quota_limit <= 0:
+            return
+        window = record.quota_window_seconds
+        idx = int(self.now() // window)
+        count = self.counters.incr(f"quota:{record.key_id}:{idx}", window)
+        if count > record.quota_limit:
+            retry = max(1, int(window - (self.now() % window)))
+            raise ToolError(
+                "OM-IO-014", "quota exceeded", retryable=True, retry_after=retry
+            )

openom_mcp-0.1.0/src/openom_mcp/blobstore.py

@@ -0,0 +1,180 @@
+# SPDX-License-Identifier: MIT
+"""Blob storage for the hosted transport (spec §K, [OM-SEC-006/013], Q4 retention).
+
+Uploaded/produced PDFs live as short-lived blobs (≤24h TTL + delete-on-completion). ``BlobStore``
+is the interface; ``LocalBlobStore`` (tmpdir + an injected clock) proves the TTL/delete/authz
+semantics offline for the gate. ``S3BlobStore`` (the R2 adapter, Task 8) implements the same
+interface for production. Zero inference, zero network in this module's tested path.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .tools import ToolError
+
+
+def new_blob_id() -> str:
+    """An unguessable blob id (≥128 bits of entropy, URL-safe) ([OM-SEC-013])."""
+    return secrets.token_urlsafe(32)
+
+
+def _iso(epoch: float) -> str:
+    return datetime.fromtimestamp(epoch, tz=UTC).isoformat()
+
+
+class BlobStore(ABC):
+    """Single-tenant, TTL-bounded blob storage keyed by an unguessable ``blobId``."""
+
+    @abstractmethod
+    def create_upload(self, principal: str) -> dict[str, str]:
+        """Reserve a blob and return ``{blobId, presignedPut, expiresAt}`` for a client upload."""
+
+    @abstractmethod
+    def get(self, blob_id: str, principal: str) -> bytes:
+        """Return the blob bytes, or raise OM-IO-006 (missing/expired) / OM-IO-007 (authz)."""
+
+    @abstractmethod
+    def put_result(self, data: bytes, principal: str) -> dict[str, str]:
+        """Store produced bytes; return ``{blobId, presignedGet, expiresAt}``."""
+
+    @abstractmethod
+    def delete(self, blob_id: str) -> None:
+        """Remove a blob (idempotent)."""
+
+
+class LocalBlobStore(BlobStore):
+    """Filesystem-backed store for tests/self-host. Presigned URLs are loopback stubs."""
+
+    def __init__(
+        self, root: Path, *, ttl_seconds: int = 86400, now: Callable[[], float] = time.time
+    ) -> None:
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.ttl = ttl_seconds
+        self.now = now
+        self._meta: dict[str, dict[str, float | str]] = {}
+
+    def _record(self, blob_id: str, principal: str) -> str:
+        created = self.now()
+        self._meta[blob_id] = {"owner": principal, "created": created}
+        return _iso(created + self.ttl)
+
+    def create_upload(self, principal: str) -> dict[str, str]:
+        blob_id = new_blob_id()
+        expires = self._record(blob_id, principal)
+        return {"blobId": blob_id, "presignedPut": f"local://put/{blob_id}", "expiresAt": expires}
+
+    def put_result(self, data: bytes, principal: str) -> dict[str, str]:
+        blob_id = new_blob_id()
+        expires = self._record(blob_id, principal)
+        (self.root / blob_id).write_bytes(data)
+        return {"blobId": blob_id, "presignedGet": f"local://get/{blob_id}", "expiresAt": expires}
+
+    def get(self, blob_id: str, principal: str) -> bytes:
+        meta = self._meta.get(blob_id)
+        path = self.root / blob_id
+        if meta is None or not path.exists():
+            raise ToolError("OM-IO-006", "blobId not found or expired")
+        if self.now() - float(meta["created"]) > self.ttl:  # TTL backstop
+            self.delete(blob_id)
+            raise ToolError("OM-IO-006", "blobId not found or expired")
+        if meta["owner"] != principal:  # existence-then-authz (anti-IDOR, OM-SEC-013)
+            raise ToolError("OM-IO-007", "blobId not authorized for this principal")
+        return path.read_bytes()
+
+    def delete(self, blob_id: str) -> None:
+        self._meta.pop(blob_id, None)
+        (self.root / blob_id).unlink(missing_ok=True)
+
+
+class S3BlobStore(BlobStore):
+    """R2/S3 adapter with **server-bound ownership** (#50). Ownership is recorded by a companion
+    ``_owners/<blobId>`` object that ONLY this server writes - never derived from client-supplied
+    object metadata - so a presigned PUT (which can write only the data object) cannot forge or
+    omit ownership. ``get`` reads the server-written owner for authz; TTL is enforced both by a
+    ≤24h bucket lifecycle rule and from the object's ``LastModified``. boto3 is an optional extra;
+    inject ``client`` for tests. authz/TTL semantics match ``LocalBlobStore``.
+    """
+
+    def __init__(
+        self, *, bucket: str, endpoint_url: str = "", access_key: str = "", secret_key: str = "",
+        ttl_seconds: int = 86400, client: Any = None,
+    ) -> None:
+        self.bucket = bucket
+        self.ttl = ttl_seconds
+        self.s3 = client if client is not None else self._make_client(
+            endpoint_url, access_key, secret_key
+        )
+
+    @staticmethod
+    def _make_client(  # pragma: no cover - real boto3 client; moto tests inject a client
+        endpoint_url: str, access_key: str, secret_key: str
+    ) -> Any:
+        import boto3
+
+        return boto3.client(
+            "s3", endpoint_url=endpoint_url,
+            aws_access_key_id=access_key, aws_secret_access_key=secret_key,
+        )
+
+    def _expires(self) -> str:
+        return _iso(time.time() + self.ttl)
+
+    @staticmethod
+    def _owner_key(blob_id: str) -> str:
+        return f"_owners/{blob_id}"
+
+    def _bind_owner(self, blob_id: str, principal: str) -> None:
+        # Server-written, not client-controlled: the presigned PUT covers only the data key.
+        self.s3.put_object(
+            Bucket=self.bucket, Key=self._owner_key(blob_id), Body=principal.encode()
+        )
+
+    def create_upload(self, principal: str) -> dict[str, str]:
+        blob_id = new_blob_id()
+        self._bind_owner(blob_id, principal)
+        url = self.s3.generate_presigned_url(
+            "put_object", Params={"Bucket": self.bucket, "Key": blob_id},
+            ExpiresIn=min(self.ttl, 3600),
+        )
+        return {"blobId": blob_id, "presignedPut": url, "expiresAt": self._expires()}
+
+    def put_result(self, data: bytes, principal: str) -> dict[str, str]:
+        blob_id = new_blob_id()
+        self._bind_owner(blob_id, principal)
+        self.s3.put_object(Bucket=self.bucket, Key=blob_id, Body=data)
+        url = self.s3.generate_presigned_url(
+            "get_object", Params={"Bucket": self.bucket, "Key": blob_id},
+            ExpiresIn=min(self.ttl, 3600),
+        )
+        return {"blobId": blob_id, "presignedGet": url, "expiresAt": self._expires()}
+
+    def get(self, blob_id: str, principal: str) -> bytes:
+        from botocore.exceptions import ClientError
+
+        try:  # authz first, from the server-written owner record (anti-IDOR, anti-forge)
+            owner = self.s3.get_object(Bucket=self.bucket, Key=self._owner_key(blob_id))
+        except ClientError as exc:
+            raise ToolError("OM-IO-006", "blobId not found or expired") from exc
+        if owner["Body"].read().decode() != principal:
+            raise ToolError("OM-IO-007", "blobId not authorized for this principal")
+        try:
+            obj = self.s3.get_object(Bucket=self.bucket, Key=blob_id)
+        except ClientError as exc:
+            raise ToolError("OM-IO-006", "blobId not found or expired") from exc
+        if time.time() - obj["LastModified"].timestamp() > self.ttl:
+            self.delete(blob_id)
+            raise ToolError("OM-IO-006", "blobId not found or expired")
+        body: bytes = obj["Body"].read()
+        return body
+
+    def delete(self, blob_id: str) -> None:
+        self.s3.delete_object(Bucket=self.bucket, Key=blob_id)
+        self.s3.delete_object(Bucket=self.bucket, Key=self._owner_key(blob_id))