prism-verify 0.4.0__tar.gz

prism_verify-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+  pull_request:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --all-extras
+      - run: uv run ruff check src/ tests/
+      - run: uv run mypy src/
+      - run: uv run pytest --tb=short

prism_verify-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,176 @@
+name: Release
+
+# On a published GitHub Release this:
+#   1. publishes the Python package to PyPI via Trusted Publishing (OIDC, no token),
+#   2. builds PyInstaller binaries for each platform + uploads them (+ checksums) to the release,
+#   3. publishes the @mcptoolshop/prism-verify npm wrapper (the npm-launcher) via Trusted Publishing.
+#
+# Org rule: publish workflows fire on `release: published` only. This is the repo's 2nd (and last)
+# workflow file. The cross-OS binary matrix (macos/windows) is the explicit-request exception to the
+# "1 OS / no macos" rule — the npm launcher distributes platform binaries, which requires it.
+#
+# First PyPI publish needs a PyPI *pending publisher* (project prism-verify, workflow release.yml;
+# environment left "(Any)" — these jobs declare no GH environment). First npm publish needs a
+# placeholder publish + a Trusted Publisher on npmjs.com for @mcptoolshop/prism-verify
+# (workflow release.yml).
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false # never cancel an in-flight publish
+
+jobs:
+  pypi:
+    name: Publish to PyPI (Trusted Publishing)
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # OIDC handshake for PyPI Trusted Publishing — the only auth needed
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Verify the tag matches pyproject version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          echo "tag=${TAG} pyproject=${PKG}"
+          if [ "${TAG}" != "${PKG}" ]; then
+            echo "::error::release tag ${TAG} does not match pyproject version ${PKG}"
+            exit 1
+          fi
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI
+        # Trusted Publishing: no token. PEP 740 attestations are on by default (action >= v1.11.0).
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  build-binaries:
+    name: Build PyInstaller binary (${{ matrix.target }})
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: linux-x64
+            ext: ""
+          - os: macos-latest
+            target: darwin-arm64
+            ext: ""
+          # darwin-x64 omitted: macos-13 is deprecated; the arm64 binary runs via Rosetta.
+          - os: windows-latest
+            target: win-x64
+            ext: ".exe"
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv python install 3.12
+      - run: uv venv
+
+      - name: Install prism + PyInstaller
+        # Bundle the [http] extra so the binary covers the CLI + local (Ollama) verification + the
+        # HTTP service + citation verification. Hosted-provider SDKs come with the PyPI install.
+        run: uv pip install ".[http]" "pyinstaller>=6.9.0"
+
+      - name: Build binary
+        shell: bash
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          uv run pyinstaller --onefile --name prism --console \
+            --collect-submodules prism \
+            --collect-submodules pydantic \
+            src/prism/__main__.py
+          OUTNAME="prism-${VERSION}-${{ matrix.target }}${{ matrix.ext }}"
+          mv "dist/prism${{ matrix.ext }}" "dist/${OUTNAME}"
+          echo "ASSET_NAME=${OUTNAME}" >> "$GITHUB_ENV"
+
+      - name: Smoke-test the binary
+        shell: bash
+        run: dist/${{ env.ASSET_NAME }} --version
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: binary-${{ matrix.target }}
+          path: dist/${{ env.ASSET_NAME }}
+
+  release-binaries:
+    name: Upload binaries + checksums to the release
+    needs: build-binaries
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # upload assets to the release
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Generate checksums
+        shell: bash
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          cd artifacts
+          sha256sum * > "checksums-${VERSION}.txt"
+          cat "checksums-${VERSION}.txt"
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: artifacts/*
+
+  npm:
+    name: Publish npm wrapper (Trusted Publishing)
+    needs: release-binaries # the wrapper is only useful once the binaries are on the release
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # npm provenance via Sigstore OIDC
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Verify the npm wrapper version matches the tag
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(node -p "require('./npm/package.json').version")
+          echo "tag=${TAG} npm=${PKG}"
+          if [ "${TAG}" != "${PKG}" ]; then
+            echo "::error::release tag ${TAG} does not match npm/package.json version ${PKG}"
+            exit 1
+          fi
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install npm >= 11.5 for OIDC trusted-publishing auth
+        run: |
+          # Node 22's bundled npm 10.9 races on an in-place `npm install -g npm@latest`
+          # (MODULE_NOT_FOUND: promise-retry). Install npm@latest into a sandbox and shadow it.
+          SANDBOX="$HOME/.npm-cli-sandbox"
+          mkdir -p "$SANDBOX"
+          pushd "$SANDBOX" >/dev/null
+          echo '{"name":"npm-cli-sandbox","version":"0.0.0","private":true}' > package.json
+          npm install --no-save --no-audit --no-fund --silent npm@latest
+          popd >/dev/null
+          echo "$SANDBOX/node_modules/.bin" >> "$GITHUB_PATH"
+          "$SANDBOX/node_modules/.bin/npm" --version
+
+      - name: Publish wrapper with provenance (OIDC trusted publisher)
+        working-directory: npm
+        run: |
+          npm install --no-save --no-audit --no-fund
+          npm publish --provenance --access public

prism_verify-0.4.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.venv/
+venv/
+.env
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+*.db
+*.sqlite
+*.sqlite3
+.coverage
+htmlcov/
+.polyglot-cache.json

prism_verify-0.4.0/CHANGELOG.md

@@ -0,0 +1,209 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-06-02
+
+prism becomes an **installable, HTTP-callable, independently-verifiable runtime service**.
+Research-grounded by a 5-agent study-swarm (`wf_f0f8b9c8-e2c`, 40 cited findings) and
+adversarially verified (3 decorrelated lenses) — design in `design/05-http-and-receipts.md`.
+
+### Added
+- **Ed25519 receipts (production default), version-aware.** Receipt **schema v4** adds `alg` +
+  `kid`; new receipts are signed with **Ed25519 (RFC 8032)** so a *different tool* verifies a
+  prism receipt with prism's **public key — no shared secret** (closes the cross-tool trust gap
+  role-os flagged). Legacy v1/v2/v3 **HMAC receipts still verify**, and the verifier **whitelists
+  `alg` per receipt** (downgrade / algorithm-confusion refused). HMAC stays for legacy + explicit
+  `PRISM_SIGNING_SECRET`; `PRISM_DEV=1` now mints a dev Ed25519 key.
+  - `prism verify-receipt <receipt.json> [--public-key <pem>]` — verify a standalone receipt
+    (the cross-tool path; Ed25519 needs only the public key). Also `POST /verify-receipt`.
+  - `prism keygen` (generate an Ed25519 keypair) and `prism pubkey` (publish the public key + kid).
+- **HTTP/FastAPI runtime surface** (`prism serve`, the `[http]` extra) — the same guarantees as
+  CLI/MCP over HTTP: `POST /verify` (sync; `Prefer: respond-async` → `202` + webhook delivery),
+  `GET /replay/{receipt_id}`, `POST /verify-receipt`, `GET /healthz`, OpenAPI 3.1 at `/docs`.
+  Bearer **API-key auth** (hashed at rest, constant-time, fail-closed), **RFC 9457
+  `application/problem+json`** errors, `Idempotency-Key` (replay / `409` in-flight / `422`
+  mismatch), and denial-of-wallet back-pressure (artifact size cap + per-key rate limit +
+  stricter failed-auth limiter).
+- **Signed-webhook escalate channel** — Standard-Webhooks HMAC over `id.timestamp.payload`
+  (300s tolerance, multi-signature rotation), an **SSRF guard** (https-only; rejects
+  loopback/RFC1918/link-local/metadata, v4+v6), bounded retry → dead-letter, and the
+  **`send_cancel_event()` compensator** (the named undo for the irreversible verdict POST).
+- **PyPI Trusted Publishing** (`.github/workflows/release.yml`) — OIDC, no long-lived token;
+  builds with `uv build` and publishes via `pypa/gh-action-pypi-publish` (PEP 740 attestations on
+  by default) on `release: published`. First publish uses a PyPI *pending publisher*.
+- **npm launcher** (`@mcptoolshop/prism-verify`) — zero-Python `npx @mcptoolshop/prism-verify` via
+  [`@mcptoolshop/npm-launcher`](https://github.com/mcp-tool-shop-org/npm-launcher): the release
+  builds PyInstaller binaries (linux-x64 / darwin-arm64 / win-x64) + a `checksums-<version>.txt`,
+  and the wrapper downloads + **SHA256-verifies** the platform binary at first run. Published via
+  npm Trusted Publishing (OIDC provenance). PyPI remains the primary, full-featured distribution
+  (hosted-provider SDKs + all extras); the npm binary bundles the CLI + local Ollama + HTTP + citations.
+
+### Changed
+- MCP + HTTP now share one engine factory (`prism.core.setup.build_default_engine`) so the
+  transports cannot drift.
+- `cryptography` added as a core dependency (Ed25519 signing/verification).
+
+### Migration notes
+- A v0.3 `~/.prism/receipts.db` migrates to schema v4 in place (`alg` / `kid` columns added);
+  legacy rows backfill `alg=HMAC-SHA256` and keep their original signatures. To verify legacy
+  HMAC receipts after moving to Ed25519, keep `PRISM_SIGNING_SECRET` set alongside the new key.
+- The honest ceiling is disclosed: an on-disk private key is forgeable by a local-root attacker
+  (same as the HMAC secret) — Ed25519 buys **third-party verifiability**, not stronger
+  anti-forgery. HSM + a transparency log is the named hardening path.
+
+### Standards
+- workflow-standards stays **15/15**; each new surface (HTTP / webhook / receipt-signing) carries
+  its own compliance section and a NO-SKIP compensators table (`design/05`, `design/03`).
+
+## [0.3.2] - 2026-06-01
+
+### Added
+- **`prism verify --gate`** — opt-in verdict-coded exit status for shell gating (`0` accept,
+  `10` revise, `20` refuse, `30` escalate). The default (no `--gate`) stays exit `0` on any
+  successful verification, preserving the CLI contract. Lets a shell/CI step — e.g. the role-os
+  citation-verification gate — branch on the verdict without parsing JSON.
+
+### Fixed
+- **Citation retrieval oracle hardening** (surfaced by the role-os citation-gate dogfood). The
+  arXiv existence check now uses `https://export.arxiv.org` directly (the `http://` endpoint
+  301-redirects, which broke the lookup), sends a descriptive `User-Agent`, follows redirects, and
+  **retries transient `429`/`5xx` with backoff** — arXiv rate-limits anonymous bursts, so a burst
+  of citations was previously escalating instead of resolving (the gap the v0.3 study-swarm's Q1
+  predicted). `CitationOracle(retry_delays=...)` is injectable; tests pass `()` for no sleeps.
+
+## [0.3.1] - 2026-06-01
+
+A post-ship adversarial verification pass (3 decorrelated lenses over the v0.3.0 diff) found and
+fixed real defects. v0.3.0 stays immutable; these land as a patch.
+
+### Fixed
+- **Citation oracle cache (was a silent wrong verdict).** The per-identifier cache held the full
+  existence result, but RESOLVED-vs-METADATA_MISMATCH is title-dependent; a repeated arXiv-id / DOI
+  with a different claimed title inherited the first citation's verdict (and the cache is
+  engine-lifetime, so it leaked across requests). The cache now holds only the title-independent
+  retrieved record and recomputes the title match per citation.
+- **DOI request hardening + pin integrity.** An unvalidated DOI suffix was interpolated into the
+  Crossref path (path-traversal / query-param injection), and the signed retrieval pin recorded a
+  URL different from the one httpx actually fetched. The DOI pattern now forbids `?`/`#`/whitespace,
+  `..` segments are rejected, `mailto` travels as a real query param, and the pin records the URL
+  actually issued.
+- **MCP `verify` tool now advertises `citations`.** The CLI was migrated in v0.3.0 but the MCP
+  inputSchema still enumerated only `code`/`tool_call`, making the headline feature unreachable via MCP.
+- **Groundedness prompt-injection defense-in-depth.** The claim and retrieved source are wrapped in
+  `<<<...>>>` untrusted-data markers; groundedness stays advisory over the sound existence floor.
+
+### Tests
+- Crossref-transient (5xx / 429 / timeout / unparseable) → UNRESOLVABLE (not FABRICATED); the cache
+  title-recompute regression; DOI path-traversal rejection; pin-equals-request-URL; a v2→v3 receipt
+  migration; and the MR1 metamorphic test now pins its verdict value.
+
+### Standards
+- workflow-standards remains 15/15; this is a correctness / hardening patch with no scope change.
+
+## [0.3.0] - 2026-06-01
+
+### Added
+- **Citation verification (headline).** A new `ArtifactType.CITATIONS` artifact (a JSON array of
+  citations) is adjudicated through a two-stage pipeline kept deliberately distinct:
+  - a **deterministic retrieval existence floor** (`prism.retrieval`) — arXiv-ID-first, then
+    Crossref DOI — that ANDON-refuses a non-resolving citation (`FABRICATED`) and distinguishes an
+    oracle-down/blocked retrieval (`UNRESOLVABLE` → escalate) from a genuine non-resolution (never
+    read as fabrication);
+  - a **deterministic numeric guard** that catches the "95.8% vs 89%" class an NLI/LLM lens is
+    structurally blind to (Naik 2018); and
+  - a **RAG-fed Groundedness (L4) lens** given the *retrieved* title+abstract, on a family-different
+    verifier.
+  Two-axis verdict mapping with per-citation action verbs (DROP / FIX METADATA / FIX TO MATCH
+  SOURCE / RETRIEVE MANUALLY); the protocol's `CANNOT_CONFIRM` maps to ESCALATE. Research grounding
+  + design: `design/04-citation-verification.md`.
+- **prism-on-prism meta-test (EXTERNAL_VERIFIER 1→3).** Verifies prism's own design-doc citations
+  through a different family + retrieval-backed existence, asserting metamorphic relations (corrupt
+  id → existence flips to refuse; numeric swap → off accept; author reorder → invariant). Non-
+  circular: it checks retrieval, not recall. Closes the launch bootstrap skip.
+- **Compensate-after-verify flow (NAMED_COMPENSATORS 2→3).** verify → signed receipt → delete /
+  prune → asserts the undo, proving the named compensator end-to-end.
+- Receipt **schema v3**: signs `artifact_type` and a hash of the per-citation `retrieval_pins` (the
+  retrieval query + retrieved-source SHA-256), so a citation verdict is replayable.
+
+### Changed
+- **Router walks configured families.** `select_verifier()` skips candidate families with no
+  configured provider instead of dead-ending on `VERIFIER_UNAVAILABLE` — fixes the out-of-box
+  `prism verify` trap (an Anthropic caller with only a local provider was refused).
+- **`BUDGET_EXCEEDED` is now enforced** as a hard latency-budget timeout on the lens fan-out (was
+  declared in `RefusalReason` but never raised).
+- Hosted verifier model IDs reconciled with provider lineups (`gpt-5.4-mini`, `claude-sonnet-4-6`,
+  `claude-haiku-4-5-20251001`), guarded by a test; local verifier pinned to the non-thinking
+  `mistral-small:24b` with `format=json` + `think=false`.
+
+### Fixed
+- **Security:** the Google provider sends its API key via the `x-goog-api-key` header instead of the
+  URL query string, so the credential no longer leaks into error reprs / tracebacks / logs.
+- OpenAI provider uses `max_completion_tokens` (GPT-5 / o-series reject `max_tokens`) and omits
+  `temperature` for reasoning models.
+- The SQLite receipt store is safe across threads (`check_same_thread=False` + a reentrant lock) and
+  supports the context-manager protocol for deterministic close.
+
+### Migration notes
+- An existing `~/.prism/receipts.db` is migrated to schema v3 in place on first open (`artifact_type`
+  + `retrieval_pins` columns added); legacy v1/v2 rows keep their original signatures and still verify.
+
+### Standards
+- workflow-standards **12/15 → 15/15**: EXTERNAL_VERIFIER 1→3, NAMED_COMPENSATORS 2→3, and
+  BUDGET_EXCEEDED enforced. See `design/02-standards-compliance.md`.
+
+## [0.2.0] - 2026-06-01
+
+### Added
+- **Replayable prompt pinning (PIN_PER_STEP).** Receipts now record `lens_prompt_hashes`
+  — a SHA-256 of each lens call's `(system_prompt, user_prompt)` — stamped by the engine
+  and signed into the receipt, so a verification is byte-for-byte replayable.
+- **Named compensators.** `prism receipt delete <id>` and
+  `prism receipt prune --older-than <duration> --yes` (plus the `store.delete_receipt` /
+  `store.prune` APIs) undo the receipt store's only irreversible write.
+- `PRISM_SIGNING_SECRET` / `PRISM_DEV` configuration for the receipt signing secret,
+  documented in the README and SECURITY.md.
+- First end-to-end integration test of `engine.verify()` against mock providers (respx).
+- SECURITY.md with a real threat model and an honest tamper-evident (not tamper-proof)
+  integrity-ceiling disclosure.
+
+### Changed
+- **Expanded the signed-receipt scope.** The HMAC now covers `reasoning_visibility_mode`,
+  `confidence`, `retryable`, a hash of the lens results, and the lens prompt hashes — not
+  just the original 7 fields. Receipts carry a `schema_version`; legacy v1 receipts still
+  verify after the automatic in-place schema migration.
+- The receipt store **requires** an explicit signing secret (`PRISM_SIGNING_SECRET`, an
+  explicit argument, or `PRISM_DEV=1`) and refuses the built-in dev key otherwise.
+- CI now runs when workflow files change (`.github/workflows/**` added to the path filter).
+
+### Fixed
+- Out-of-enum verifier output (e.g. `severity: "high"`, `outcome: "accept"`) or
+  markdown-fenced JSON no longer crashes `verify()` with a raw stack; lens responses
+  degrade gracefully to an `errored` UNCERTAIN result.
+- Verdict aggregation: a FAIL with only minor (or no) findings no longer collapses to
+  ACCEPT, and a mixed PASS + UNCERTAIN now ESCALATEs instead of silently ACCEPTing.
+- A provider outage now refuses with `VERIFIER_UNAVAILABLE` (retryable) instead of being
+  misclassified as a non-retryable `LENS_COLLAPSE`.
+- Ollama / OpenAI providers guard malformed response bodies (raise `ProviderError`
+  instead of a bare `KeyError`).
+- Routing map's local-tier model id corrected (`qwen3-32b` → `qwen3:32b`) to match the
+  Ollama provider.
+- `prism replay` no longer leaks its SQLite connection on the receipt-not-found path.
+
+### Migration notes
+- Receipts written by v0.1.0 under the built-in dev key report `signature_valid: false`
+  once a real `PRISM_SIGNING_SECRET` is set — expected (different key), not tampering.
+- An existing `~/.prism/receipts.db` is migrated in place on first open (new columns
+  added; legacy rows keep their original signatures).
+
+## [0.1.0] - 2026-06-01
+
+### Added
+- Initial release: family-different routing, reasoning-stripping, multi-lens (≥3)
+  verification with submodularity-aware lens-collapse refusal, SQLite HMAC-signed
+  receipts, a CLI (`verify` / `replay`), and an MCP server. 41 tests; CI on 3.11–3.13.

prism_verify-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+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.

prism_verify-0.4.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: prism-verify
+Version: 0.4.0
+Summary: Runtime adjudication service for agent workflows. Family-different, reasoning-stripped, multi-lens verification with replayable receipts.
+Project-URL: Homepage, https://github.com/mcp-tool-shop-org/prism-verify
+Project-URL: Repository, https://github.com/mcp-tool-shop-org/prism-verify
+Project-URL: Issues, https://github.com/mcp-tool-shop-org/prism-verify/issues
+Author-email: mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adjudication,agent,llm,mcp,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: ulid-py>=1.1
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Requires-Dist: fastapi>=0.115; extra == 'all'
+Requires-Dist: google-genai>=1.0; extra == 'all'
+Requires-Dist: mcp>=1.0; extra == 'all'
+Requires-Dist: openai>=1.50; extra == 'all'
+Requires-Dist: uvicorn>=0.30; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: google
+Requires-Dist: google-genai>=1.0; extra == 'google'
+Provides-Extra: http
+Requires-Dist: fastapi>=0.115; extra == 'http'
+Requires-Dist: uvicorn>=0.30; extra == 'http'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: openai>=1.50; extra == 'openai'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/prism-verify/main/assets/prism-verify-logo.png" alt="prism-verify logo" width="500">
+</p>
+
+# prism-verify
+
+Runtime adjudication service for agent workflows. Family-different, reasoning-stripped, multi-lens verification with replayable receipts.
+
+## Install
+
+Install the `prism` CLI (and the HTTP service) on your PATH:
+
+```bash
+uv tool install prism-verify        # or: pipx install prism-verify
+```
+
+Zero Python? Use the npm launcher (downloads + SHA256-verifies a prebuilt binary):
+
+```bash
+npx @mcptoolshop/prism-verify verify --artifact @file.py --intent "..." --caller-family openai
+```
+
+Or add it as a library — extras: `[anthropic]` `[openai]` `[google]` `[mcp]` `[http]` `[all]`:
+
+```bash
+uv add prism-verify
+# or
+pip install "prism-verify[all]"
+```
+
+## Quick start
+
+Prism always verifies with a model family **different** from the caller's (Lock 1), so
+configure at least one alternate-family provider. Set a signing secret (or `PRISM_DEV=1`
+for local play) so receipts can be written:
+
+```bash
+export PRISM_SIGNING_SECRET="$(openssl rand -hex 32)"
+export ANTHROPIC_API_KEY="sk-ant-..."   # alt-family verifier for an OpenAI-family caller
+
+prism verify \
+  --artifact @myfile.py \
+  --intent "Sort a list in O(n log n)" \
+  --caller-family openai \
+  --provider anthropic
+```
+
+## Architecture
+
+Prism enforces four architectural locks at the API contract:
+
+1. **Family-different** — caller's model family is always excluded from verification
+2. **Reasoning-stripped** — producer CoT is stripped before crossing the family boundary
+3. **Multi-lens** — at least 3 independent lenses run in parallel
+4. **Submodularity-aware** — refuses if lenses agree too much (collapsed signal)
+
+## HTTP service
+
+Run prism as an HTTP service (needs the `[http]` extra):
+
+```bash
+prism serve --host 127.0.0.1 --port 8000      # OpenAPI docs at /docs
+```
+
+| Endpoint | What it does |
+|---|---|
+| `POST /verify` | Verify an artifact (same contract as the CLI). Blocks within the budget; `Prefer: respond-async` + a `webhook` URL → `202`, verdict delivered to the (signed) webhook. |
+| `GET /replay/{receipt_id}` | The signed receipt + `signature_valid`. |
+| `POST /verify-receipt` | Verify a standalone receipt (cross-tool). |
+| `GET /healthz` | Liveness + configured verifier families (no auth). |
+
+Set API keys (hashed at rest) — prism is **fail-closed**, so `/verify` is refused until keys
+are configured or you opt into local no-auth:
+
+```bash
+export PRISM_API_KEYS="<sha256(key1)>,<sha256(key2)>"   # callers send: Authorization: Bearer <key>
+export PRISM_WEBHOOK_SECRET="<random>"                  # to sign async/escalate webhook deliveries
+# local dev only:
+export PRISM_HTTP_ALLOW_NO_AUTH=1
+```
+
+Errors are RFC 9457 `application/problem+json`; `POST /verify` honours an `Idempotency-Key`
+header and a per-key rate limit (`429` + `Retry-After`). Async/escalate webhooks are
+Standard-Webhooks-signed, SSRF-guarded (no internal/metadata targets), retried, and carry a
+named cancel-event compensator.
+
+## Receipts & signing (Ed25519, verifiable by anyone)
+
+Every verification produces a signed, replayable receipt in `~/.prism/receipts.db`. v0.4 signs
+new receipts with **Ed25519 (RFC 8032)** by default, so **a different tool can verify a prism
+receipt with prism's public key — no shared secret**:
+
+```bash
+prism keygen --out ~/.prism/signing_key.pem    # generate an Ed25519 keypair
+export PRISM_SIGNING_KEY=~/.prism/signing_key.pem
+prism pubkey                                    # publish this public key + kid to consumers
+
+# a consumer (e.g. role-os) verifies a receipt with ONLY the public key:
+prism verify-receipt receipt.json --public-key prism-pub.pem
+```
+
+The signature covers the verdict, the pre/post-strip artifact hashes, the verifier model, the
+submodularity matrix, the per-lens prompt hashes (byte-for-byte replayable), the citation
+retrieval pins, and the signing `alg`/`kid`. Legacy **HMAC** receipts still verify (set
+`PRISM_SIGNING_SECRET`); `PRISM_DEV=1` mints a dev key for local play. Prism **refuses to start**
+the verify / replay / serve / MCP paths if no key is configured, rather than silently signing
+with a publicly known key.
+
+Manage stored receipts with the compensator commands:
+
+```bash
+prism receipt delete <receipt_id>
+prism receipt prune --older-than 90d --yes
+```
+
+## Security & privacy
+
+- **Threat model.** Prism reads the artifact + intent you pass and the verifier models'
+  responses, and writes signed receipts to a local SQLite DB. It does **not** read your
+  source tree, environment, or credentials beyond the provider API keys you supply via
+  environment variables. Receipt signatures give **third-party verifiability** (Ed25519: a
+  consumer verifies with the public key, no shared secret) but are not tamper-*proof* against a
+  local-root attacker who can read the on-disk private key — that's the same ceiling as the HMAC
+  secret. For genuine tamper-resistance, hold the key in an HSM and anchor receipts in a
+  transparency log (the named hardening path).
+- **HTTP surface.** `prism serve` binds loopback by default, is **fail-closed** (no `/verify`
+  without API keys), hashes keys at rest, and **SSRF-guards** caller-supplied webhook URLs
+  (no internal/link-local/metadata targets). It runs caller-supplied artifacts through a model;
+  an artifact may *attempt* prompt injection but cannot change the verdict schema or exfiltrate
+  prism's provider keys.
+- **No telemetry.** Prism sends requests only to the model providers you configure
+  (Anthropic / OpenAI / Google / local Ollama). Nothing else.
+- Full policy: [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT