etch-provenance 0.3.0__tar.gz

etch_provenance-0.3.0/.dockerignore

@@ -0,0 +1,16 @@
+.git
+.github
+.venv
+.env
+.pytest_cache
+.mypy_cache
+.ruff_cache
+__pycache__
+*.pyc
+*.pyo
+etch.db
+*.egg-info
+dist
+build
+docs
+tests

etch_provenance-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check etch/ tests/
+
+      - name: Run tests
+        run: pytest
+
+  assent-frontend:
+    # Catches TypeScript regressions + broken build configs for the
+    # Etch Assent SPA before they hit main. Runs independently of the
+    # Python matrix so a TS issue doesn't block Python CI and vice versa.
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: assent-app
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: assent-app/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type-check + build
+        # `npm run build` already runs `tsc --noEmit && vite build`
+        # per assent-app/package.json.
+        run: npm run build
+
+      - name: Upload built bundle (main only)
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v4
+        with:
+          name: assent-bundle
+          path: site/assent/
+          retention-days: 14

etch_provenance-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write  # Required for trusted publishing (OIDC)
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check etch/ tests/
+
+      - name: Run tests
+        run: pytest
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

etch_provenance-0.3.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.db
+.env
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Internal/private docs — never commit
+docs/_private/

etch_provenance-0.3.0/CHANGELOG.md

@@ -0,0 +1,179 @@
+# Changelog
+
+All notable changes to Etch are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] — 2026-11-08
+
+### Added
+
+- **Assent MCP server** (`etch-assent-mcp`, `pip install "etch-provenance[mcp]"`). An agent asks a human
+  to sign and gets a link back. `request_signature` renders plain text to a sign-off PDF, or
+  takes an existing PDF. It encrypts locally in the browser's format (`[IV || CT]`,
+  `#key=…&wt=…`), uploads ciphertext, and stamps `uploaded` at index 0. Etch never holds the
+  key. The core is `etch/assent_agent.py`, with no MCP dependency.
+  `signature_status` reports progress (sent → opened → signing → finalized) and whether the
+  opened copy matches what was sent. `fetch_signed` decrypts the signed return, accepts it only
+  when its hash equals the `finalized` event, and recomputes the inclusion proof locally.
+- **Etch Assent** (`/v1/assent/*`) — client-side PDF signing with an anonymous
+  provenance chain. The PDF never reaches the server; only hashes and event
+  metadata do. Events are pinned to the `assent/public` namespace and capped at
+  32 per document; per IP, 30 new documents and 600 follow-on events an hour.
+  - `POST /v1/assent/stamp` — commit an `assent.event`
+  - `GET /v1/assent/chain/{document_id}` — event chain with integrity check
+  - `GET /v1/assent/records/{record_id}` and `…/proof` — public receipt + inclusion proof
+  - `GET /v1/assent/verify?hash=` — find events by document hash
+- **Assent send-to-sign (E2EE)** — opaque ciphertext store at
+  `/v1/assent/document`. The browser encrypts with AES-256-GCM and keeps the key
+  in the URL fragment, which browsers never transmit, so Etch cannot decrypt what
+  it holds. 10 uploads per IP per hour, 15 MB cap, disk path via
+  `ETCH_ASSENT_DOC_DIR`.
+- **Capability token for document replacement** — `PUT /v1/assent/document/{id}`
+  now requires the `X-Assent-Write-Token` issued at upload time, so possession of
+  a document ID is no longer sufficient to overwrite it. The sender bakes the
+  token into the share link's fragment, so the server never sees it in transit.
+- **Multi-field signing with a review/finalize gate** — several signature fields
+  per document, each independently placed, resized, and dragged; a review stage
+  between placing and finalizing.
+- **Customizable verification stamp** — the QR verification stamp is draggable,
+  resizable, and can be switched off entirely.
+- **DOOH playback receipts** (`/v1/dooh/*`) — bilaterally-signed proof that a
+  creative ran on a specific screen at a specific time, anchored in an
+  advertiser-owned namespace. Ships with an offline verifier, an ed25519 keypair
+  and identity-manifest model, an `EtchSubmitter` client, and a reference player.
+  Spec: [`docs/dooh-spec.md`](docs/dooh-spec.md) (CC-BY 4.0).
+- **Glyph** — 8-character Crockford-base32 shortcodes encoding a 32-bit
+  `proof_id` plus an 8-bit checksum over the content hash, so typos and
+  fabrications are caught before a database lookup. Adds a bar sigil renderer and
+  a server-rendered public resolver at `/g/{shortcode}` (plus `.json` and `.png`).
+- **etchmark** — inaudible spread-spectrum audio watermark carrying an Etch
+  shortcode, with sync recovery and CRC-12 payload framing.
+  `POST /v1/proof/{proof_id}/embed-audio` returns lossless 16-bit PCM WAV;
+  `POST /v1/proof/extract-audio` recovers the shortcode and resolves it. WAV and
+  FLAC are read natively; MP3/AAC/Opus go through `ffmpeg` when it is on `PATH`.
+  The watermark is a *pointer* to a chain record, never a proof in itself.
+- **`if_changed` on `POST /v1/records`** — with `record.id` set, Etch looks up the
+  latest record for that `(namespace, external_id, record_type)` and, if the
+  `record_hash` is unchanged, returns the existing receipt with
+  `"deduplicated": true` without appending. Opt-in on purpose: the chain is
+  append-only, and re-registering unchanged content is a legitimate timestamped
+  re-attestation, so the default must never silently deduplicate.
+- **`GET /v1/records/stats`** — per-namespace append vs. dedup counters, so the
+  saving from `if_changed` is measurable rather than asserted.
+- **Structured logging setup** — uvicorn only configures its own loggers, so
+  `etch.*` log lines were being dropped, including the dedup line that is the only
+  trace a suppressed write leaves. Level via `ETCH_LOG_LEVEL` (default `INFO`).
+
+- **Assent field detection.** Fields are found when a PDF opens, entirely in the
+  browser. Fillable PDFs import their own form fields (text, checkbox, radio,
+  signature) at the exact widget boxes with existing values; the finalized PDF
+  draws the values and strips the original widgets so no viewer paints an empty
+  field over them. Flat PDFs get suggested fields from underscore runs, drawn
+  underlines, captions under a line, empty table cells (labelled by the cell to
+  their left), checkboxes in every form Word produces — Wingdings / Wingdings 2
+  symbols, ☐ glyphs, content controls, legacy form checkboxes, drawn squares —
+  plus `( )` and `[ ]` blanks, and bare labels like `Name:`. A box the document
+  prints as ☑ comes in checked; unchecking it paints the printed mark out.
+  Designed forms (InDesign / government templates — light field boxes on a
+  tinted panel, question printed at the top of each box) get a field under
+  each question; centered column headers, yes/no-only questions, paragraph
+  boxes and "office use only" panels are left alone. A blank repeated at the
+  same spot on every page (a running "Applicant name" header) is one value.
+  An auto-filled date beside a signature line is kept only if that line was
+  signed. Date blanks prefill today; name and email blanks follow
+  the identity panel. Detected signature boxes are suggestions: they don't block
+  finishing and only reach the chain when signed.
+- Assent checkbox fields, placeable by hand as well as detected.
+
+### Changed
+
+- **Published on PyPI as `etch-provenance`.** `etch` on PyPI is an unrelated project, so
+  `pip install etch` never installed this one, and v0.2.0 never reached PyPI. The import
+  is still `import etch`.
+- A document can now be finalized on text fields alone; a signature field is no
+  longer required.
+- The verification stamp shrank from a full-width banner to a corner badge.
+- A signed Assent signature field can still be moved and resized while placing;
+  the finalized PDF contain-fits the ink into the box instead of stretching it.
+- Assent text fields fit their text by default: one line tall, 120pt wide while
+  empty, then hugging the typed text as it grows and shrinks (trailing spaces
+  trimmed on blur), so a field stops covering the page around it. A manual resize
+  pins the box; a **fit** button snaps it back. Fields resize down to one glyph
+  by one line, and the finalized text is vertically centered in its box.
+- `POST /v1/proof/batch` accepts up to 1000 items per request.
+
+### Fixed
+
+- **DOOH proofs bind the bundle.** The verifier compared `bundle_hash` to `etch_proof.record_hash`,
+  a field the chain leaf doesn't commit to, so a genuine proof for one receipt could be re-pointed at
+  another bundle and pass, even against a trusted root. `EtchProof` now carries `payload_json`, and
+  `verify_bundle` requires it to hash to `payload_hash` and name the bundle. **Breaking for verifiers:**
+  a proof without `payload_json` fails; `GET /v1/dooh/receipts` returns it for anchored bundles.
+- **Send-to-sign verify links resolve.** The link and QR stamped on every send-to-sign PDF carry
+  the server-issued document id, which has no `doc_` prefix; the Verify page rejected it as an
+  "Unrecognized identifier". Any token that isn't a record id is now looked up as a document id.
+- **Proofs now bind the content hash.** Every chain payload included a `registered_at` that was
+  never stored, so a verifier could recompute `leaf_hash` and `mmr_root` but couldn't connect
+  `payload_hash` to the content: that link rested on Etch's database. The exact hashed payload
+  is now stored (`payload_json` on `etch_records` and `etch_proofs`, added at startup) and
+  returned by the `/v1/records`, `/v1/assent` and `/v1/c2pa` proofs. The verification steps go
+  from 2 to 4, and the SDK's `InclusionProof` gains `payload_json` and `verify()`. Older rows were
+  recovered with `python -m etch.backfill_payloads`, which brute-forces `registered_at` over the
+  doubles just below the stored chain timestamp. Production: 137,663/137,663 recovered
+  (2026-11-03), each one an exact SHA-256 preimage.
+
+- Assent's rate limit counted every event, so one long form with several
+  signature lines used most of an office NAT's hourly budget. The per-IP limit
+  is now on new documents (30/hour), with a 600/hour flood guard on follow-on
+  events. A refused `created` event no longer leaves the session dead: the
+  client retries it before the next write, and a 429 explains itself instead
+  of surfacing the raw API detail.
+- The drawn-signature pad opens as a modal instead of at the bottom of the
+  sidebar, where it was off-screen when signing deep in a long document.
+- Drawn signatures are stamped with a transparent background, so the ink no
+  longer erases the signature line it's placed on.
+- Index `idx_records_ns_ext` on `(namespace_id, external_id, record_type)` keeps
+  the `if_changed` lookup flat as external IDs accumulate, instead of degrading
+  into a scan.
+- Assent field placement is predictable, and a placed signature no longer hides
+  text beneath it.
+- Assent "remove field" and "remove stamp" work — pressing them no longer starts
+  a drag on the field, which had swallowed the click and opened the signature pad.
+
+### Removed
+
+- Internal outreach documents and infrastructure details are no longer committed
+  to the public repository (`docs/_private/` is now gitignored).
+
+## [0.2.0] — 2026-03-27
+
+### Added
+
+- **System of Record API** (`/v1/records/*`) — namespace-isolated chains with API
+  key authentication. Keys are formatted `etch_{live|test}_sk_{token}` and stored
+  only as SHA-256 hashes. Includes cursor pagination, self-contained inclusion
+  proofs, and `GET /v1/chain/root`.
+- **C2PA compatibility layer** (`/v1/c2pa/*`) — register, retrieve, verify, and
+  bridge C2PA manifests against the Etch chain, for EU AI Act provenance work.
+- **Batch registration** — `POST /v1/proof/batch`.
+- **Landing site** (`site/index.html`) and deployment infrastructure: Dockerfile,
+  `docker-compose.yml`, and reverse-proxy configuration.
+
+## [0.1.0] — 2026-03-18
+
+### Added
+
+- Initial extraction of Etch as a standalone project: the MMR audit chain
+  (`AuditChain`, `ChainEntry`, `InclusionProof`), offline verification via
+  `verify_inclusion_proof()`, and the legacy `/v1/proof/*` registration API.
+- Async Python SDK (`EtchClient`).
+- CI matrix across Python 3.11/3.12/3.13 with ruff linting, and a release
+  workflow publishing to PyPI via OIDC trusted publishing.
+
+[Unreleased]: https://github.com/maco144/Etch/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/maco144/Etch/releases/tag/v0.3.0
+[0.2.0]: https://github.com/maco144/Etch/releases/tag/v0.2.0

etch_provenance-0.3.0/CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md — Etch
+
+## What is Etch?
+
+Content provenance on a tamper-evident Merkle chain. Register, verify, and prove content existed at a point in time. Privacy-preserving (content never stored, only SHA-256 hashes).
+
+## Quick Reference
+
+```bash
+# Setup
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run server (default port 8100)
+uvicorn etch.server:app --reload
+
+# Lint
+ruff check etch/ tests/
+```
+
+## Architecture
+
+- **chain.py** — Core: MMR hash chain (`AuditChain`), inclusion proofs, offline verification
+- **chain_manager.py** — Namespace-isolated chain manager (per-tenant chains for SoR API)
+- **api.py** — FastAPI router at `/v1/proof/*` (legacy: register, verify, lookup, batch, stats)
+- **records_api.py** — FastAPI router at `/v1/records/*` (SoR API, namespace-isolated, API key auth)
+- **c2pa.py** — FastAPI router at `/v1/c2pa/*` (C2PA manifest bridge for EU AI Act compliance)
+- **assent_api.py** — FastAPI router at `/v1/assent/*` (anonymous PDF-signer event chain)
+- **assent_docs_api.py** — FastAPI router at `/v1/assent/document/*` (E2EE ciphertext store)
+- **assent_agent.py / assent_mcp.py** — Assent sender for agents (text→PDF, local E2EE, sign link) + stdio MCP server `etch-assent-mcp`
+- **dooh_api.py** — FastAPI router at `/v1/dooh/*` (playback receipts); SDK in **dooh/**
+- **glyph.py / glyph_api.py** — Shortcodes + bar sigils; public resolver at `/g/{shortcode}`
+- **watermark/ + watermark_api.py** — `etchmark` audio watermark; embed/extract endpoints
+- **auth.py** — API key authentication (`etch_{mode}_sk_{token}`), namespace bootstrap
+- **models.py** — SQLAlchemy ORM: `ProofRecord`, `Namespace`, `ApiKey`, `RecordEntry` (4 tables)
+- **db.py** — Async DB sessions (SQLite default, PostgreSQL via `ETCH_DATABASE_URL`)
+- **sdk.py** — Async Python SDK (`EtchClient`) with legacy + v2 API support
+- **backfill_payloads.py** — One-off recovery of `payload_json` for rows written before it was stored
+- **server.py** — FastAPI app with lifespan (auto-creates tables, bootstraps namespaces, configures `etch` loggers)
+
+## Key Patterns
+
+- Global singleton chain via `get_chain()` / `log_event()` in chain.py
+- Thread-safe chain operations (threading.Lock)
+- Persist hook pattern: chain calls sync hook after append (outside lock)
+- **Every chain write must persist `entry.payload_json`** (the `payload_json` column). It is the only link from `payload_hash` to the content hash; a router that drops it ships proofs that can't be tied to content. Proof endpoints return it alongside `chain.RECORD_COMMIT_VERIFICATION_STEPS`
+- New columns on existing tables go in `db._ADDED_COLUMNS` (nullable); `create_all` never alters a deployed table
+- API tests use httpx ASGITransport with mocked DB layer
+- `asyncio_mode = "auto"` in pytest config
+- The chain is append-only and every root hashes the previous one — nothing is ever deleted or compacted, so write-amplification is permanent. A write-only API invites clients to re-register their whole working set every run; `POST /v1/records` takes `if_changed: true` (with `record.id`) to make that cheap: one indexed lookup on `idx_records_ns_ext`, and an unchanged `record_hash` returns the existing receipt with `deduplicated: true` instead of appending. It is opt-in on purpose — re-registering unchanged content is a legitimate timestamped re-attestation, so the default must never silently deduplicate.
+
+## Environment Variables
+
+- `ETCH_DATABASE_URL` or `DATABASE_URL` — DB connection string (default: `sqlite+aiosqlite:///./etch.db`)
+- `ETCH_LOG_LEVEL` — Level for the `etch` loggers (default: `INFO`)
+- `ETCH_ASSENT_DOC_DIR` — Assent ciphertext storage (default: `/var/etch/assent-documents`)
+- `ETCH_ASSENT_IP_SALT` — Salt for hashed client IPs in Assent rate limiting
+
+## Documentation Map
+
+- **README.md** — public front door: full endpoint tables, auth, configuration
+- **CHANGELOG.md** — Keep a Changelog; `v0.2.0` is tagged, everything since is Unreleased
+- **PROJECT_INDEX.md** — repo map, module-by-module; read before exploring
+- **docs/ETCH_ASSENT_SPEC.md** — Assent; sections marked *as built* are authoritative,
+  *planned* ones may not exist yet
+- **docs/dooh-spec.md** — DOOH protocol; the trust model section is non-negotiable context
+- **etch/dooh/README.md** — DOOH SDK quickstart
+- **assent-app/README.md** — Assent frontend build + architecture
+- **docs/RELEASING.md** — release procedure (PyPI via OIDC)
+
+## Conventions
+
+- Python 3.11+, ruff line-length 120
+- License: Rising Sun License v1.0

etch_provenance-0.3.0/Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.12-slim AS base
+
+RUN groupadd -r etch && useradd -r -g etch -d /app etch
+WORKDIR /app
+
+COPY pyproject.toml README.md LICENSE.md ./
+COPY etch/ etch/
+RUN pip install --no-cache-dir ".[postgres]"
+
+COPY site/ site/
+
+# Pre-create the assent document store with correct ownership. Docker will
+# adopt this as the initial state of the named volume on first boot.
+RUN mkdir -p /data/assent-documents && chown -R etch:etch /data
+
+USER etch
+EXPOSE 8100
+
+# --workers 1 is intentional. The anonymous assent endpoints use an in-memory
+# sliding-window rate limiter that lives per-process; multiple workers would
+# multiply the effective cap. When we move to a shared store (Redis), scale up.
+# --forwarded-allow-ips=* lets uvicorn honour Caddy's X-Forwarded-Proto so the glyph
+# resolver mints https:// magic URLs. Safe: the port is published on 127.0.0.1 only,
+# so the only client that can set those headers is the local reverse proxy.
+CMD ["uvicorn", "etch.server:app", "--host", "0.0.0.0", "--port", "8100", "--workers", "1", "--forwarded-allow-ips", "*"]

etch_provenance-0.3.0/LICENSE.md

@@ -0,0 +1,76 @@
+# Rising Sun License v1.0
+
+This license governs all software released under the Rising Sun project.
+
+## For People
+
+Use this software however you want. Run it, study it, modify it, share it.
+Personal use, education, research, tinkering — all free, no strings attached.
+
+You don't need permission. You don't need to register. Just use it.
+
+## For Builders
+
+If you build something that generates revenue using this software, connect it
+to the Nous network. Nous handles verification, attestation, and accounting
+automatically — you integrate once and it works.
+
+The economics are simple: Nous takes a small percentage of the value flowing
+through your deployment. The rate is published and predictable. You always
+keep the majority. The exact terms are governed by the Nous protocol and
+published at the canonical terms endpoint.
+
+You may not remove, bypass, or substitute the Nous integration in a
+commercial deployment. Everything else is yours to build.
+
+## For Enterprise
+
+Custom integration, dedicated support, and private deployment are available
+directly from Rising Sun. Enterprise terms are negotiated individually and
+may include modified Nous configurations, SLAs, and priority access to new
+capabilities.
+
+Contact: alex@risingsun.name
+
+## How Nous Works
+
+Nous is a verification and attestation service. When your deployment does
+work — processes data, serves users, executes transactions — Nous verifies
+the work, attests to its completion, and routes value through the Ergon
+ledger. Trust scores build over time: consistent, honest operation earns
+better terms automatically.
+
+This is not a phone-home or surveillance mechanism. Nous verifies value
+created, not behavior observed. The attestation record is transparent
+and auditable.
+
+## What You Can Do
+
+- Use, copy, modify, and distribute this software
+- Build commercial products and services on it
+- Fork it, extend it, combine it with other software
+- Run it on any infrastructure you control
+- Contribute improvements back (appreciated, not required)
+
+## What You Cannot Do
+
+- Remove or bypass Nous integration in commercial deployments
+- Represent modified versions as official Rising Sun releases
+- Use Rising Sun trademarks without permission
+
+## Contributions
+
+Contributions via pull request grant the project a perpetual, irrevocable,
+royalty-free license to use the contribution. Contributors retain copyright
+on their work.
+
+## No Warranty
+
+This software is provided as-is, without warranty of any kind. The licensor
+is not liable for any damages arising from its use.
+
+---
+
+Rising Sun License v1.0
+Copyright (c) 2026 Alex Macaluso
+https://risingsun.name