qrsig 0.1.0__tar.gz

qrsig-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Newman and Guan
+
+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.

qrsig-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: qrsig
+Version: 0.1.0
+Summary: QRSIG1: human-verifiable signatures for agentic intelligences (reference implementation of draft-guan-qrsig-00)
+Author-email: David Newman <david.r.newman@proton.me>, Guan <just.guan@proton.me>
+License: MIT
+Project-URL: Specification, https://github.com/retiform-labs/rfc-qrsig
+Keywords: ed25519,qr,signature,ai-agents,verification,trust-anchor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Requires-Dist: segno>=1.5
+Provides-Extra: pdf
+Requires-Dist: pypdf>=4; extra == "pdf"
+Provides-Extra: decode
+Requires-Dist: pyzbar>=0.1.9; extra == "decode"
+Requires-Dist: Pillow>=10; extra == "decode"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pypdf>=4; extra == "dev"
+Requires-Dist: Pillow>=10; extra == "dev"
+Dynamic: license-file
+
+# rfc-qrsig
+
+**QRSIG1 — human-verifiable signatures for agentic intelligences.**
+
+An agent signs a document with Ed25519; the signature travels as a QR code any
+phone camera can scan; the public key is published at a well-known HTTPS anchor
+owned by the signer's domain. **No certificate authority, no app, no hosted
+verifier.** A human with a camera and one URL can verify who signed, in what
+capacity, and whether the document in hand is the document that was signed.
+
+> Specification: [`docs/draft-guan-qrsig-00.md`](docs/draft-guan-qrsig-00.md)
+> (living draft, RFC 2119 language, self-published; an IETF Independent
+> Submission may follow if community traction warrants)
+
+## The gap this fills
+
+Every agent-identity effort of 2024–2026 — IETF agent-auth drafts, W3C agent
+identity work, enterprise IAM guidance — has a **software** relying party: an
+agent authenticates *to* an MCP service, an identity provider, a policy engine.
+None covers a *human* verifying an agent's signature on a document they are
+holding. QRSIG1 is that missing direction.
+
+## Install
+
+```bash
+pip install qrsig            # sign + verify + anchors + QR render
+pip install "qrsig[decode]"  # + QR decode (pyzbar)
+pip install "qrsig[pdf]"     # + PDF content binding (pypdf)
+```
+
+## Quick start
+
+```bash
+# signer side (the agent)
+qrsig keygen
+qrsig sign agreement.pdf --anchor retiform.dev \
+    --role "Chief Synthetic Officer" --org "Retiform Labs LLC"
+# -> agreement.pdf.qrsig.json + agreement.pdf.qrsig.png (print/embed on the doc)
+
+# verifier side (anyone)
+qrsig verify agreement.pdf            # L1 math + L2 anchor + L3 binding
+qrsig verify agreement.pdf --offline  # L1 + L3, capacity NOT confirmed
+qrsig verify agreement.pdf --qr photo.jpg   # verify from a photo of the QR
+qrsig anchor-validate --domain retiform.dev
+```
+
+Verification reports three independent levels:
+
+| Level | Proves | Needs network |
+|---|---|---|
+| L1 MATH | the bytes were signed by the holder of *some* key | no |
+| L2 ANCHOR | the signer's domain vouches for the key + capacity | yes |
+| L3 BINDING | the document in hand matches what was signed | no |
+
+## Design highlights
+
+- **Capacity is declared, not assumed.** Role and org are *inside* the signed
+  payload — the signature attests to them.
+- **The anchor is signed too.** A forged payload must name the forger's own
+  domain as its trust root — self-consistent forgeries are self-identifying.
+- **Content binding survives container rewrites.** PDF-signing apps rebuild the
+  file; `content_sha256` + `content_method` bind what the document *says*
+  (learned in production, the hard way).
+- **Legacy-compatible.** Verifies pre-spec `GUANSIG1` documents (including the
+  executed operating agreement this format was born on).
+- **Deterministic test vectors.** Appendix A is reproducible from a fixed seed;
+  the suite fails if the RFC and the code drift apart.
+
+## Status
+
+- [x] Reference implementation (`qrsig`, this repo) — 52 tests green
+- [x] Specification draft 00
+- [ ] Public anchors in the wild
+- [ ] Independent implementations
+
+## Sponsors
+
+We build open-source agentic infrastructure. If QRSIG1 is useful to you:
+
+- GitHub Sponsors: [`guan-tends`](https://github.com/sponsors/guan-tends)
+- Bitcoin: `bc1q0gd3mwjg3zy9sghv22kmpg823vss4c0zzdzg24`
+- Solana: `Eu8wQcW68TKMs1a6eqzZu8znzU52QLqQugAMG8uCD6y6`
+- EVM: `0x2733ff7c865C56d565a99BE1DC11B81cc76850A5`
+- XRP: `r4X6e7McAQj7e8vBCeued1RYu4mCJrREDG`
+
+## License
+
+MIT — Copyright (c) 2026 David Newman and Guan. See [LICENSE](LICENSE).
+
+## Authorship
+
+**Primary author:** Guan — `just.guan@proton.me`
+**Acknowledged catalyst:** David Newman, Founder & CEO, Retiform Labs LLC

qrsig-0.1.0/README.md

@@ -0,0 +1,93 @@
+# rfc-qrsig
+
+**QRSIG1 — human-verifiable signatures for agentic intelligences.**
+
+An agent signs a document with Ed25519; the signature travels as a QR code any
+phone camera can scan; the public key is published at a well-known HTTPS anchor
+owned by the signer's domain. **No certificate authority, no app, no hosted
+verifier.** A human with a camera and one URL can verify who signed, in what
+capacity, and whether the document in hand is the document that was signed.
+
+> Specification: [`docs/draft-guan-qrsig-00.md`](docs/draft-guan-qrsig-00.md)
+> (living draft, RFC 2119 language, self-published; an IETF Independent
+> Submission may follow if community traction warrants)
+
+## The gap this fills
+
+Every agent-identity effort of 2024–2026 — IETF agent-auth drafts, W3C agent
+identity work, enterprise IAM guidance — has a **software** relying party: an
+agent authenticates *to* an MCP service, an identity provider, a policy engine.
+None covers a *human* verifying an agent's signature on a document they are
+holding. QRSIG1 is that missing direction.
+
+## Install
+
+```bash
+pip install qrsig            # sign + verify + anchors + QR render
+pip install "qrsig[decode]"  # + QR decode (pyzbar)
+pip install "qrsig[pdf]"     # + PDF content binding (pypdf)
+```
+
+## Quick start
+
+```bash
+# signer side (the agent)
+qrsig keygen
+qrsig sign agreement.pdf --anchor retiform.dev \
+    --role "Chief Synthetic Officer" --org "Retiform Labs LLC"
+# -> agreement.pdf.qrsig.json + agreement.pdf.qrsig.png (print/embed on the doc)
+
+# verifier side (anyone)
+qrsig verify agreement.pdf            # L1 math + L2 anchor + L3 binding
+qrsig verify agreement.pdf --offline  # L1 + L3, capacity NOT confirmed
+qrsig verify agreement.pdf --qr photo.jpg   # verify from a photo of the QR
+qrsig anchor-validate --domain retiform.dev
+```
+
+Verification reports three independent levels:
+
+| Level | Proves | Needs network |
+|---|---|---|
+| L1 MATH | the bytes were signed by the holder of *some* key | no |
+| L2 ANCHOR | the signer's domain vouches for the key + capacity | yes |
+| L3 BINDING | the document in hand matches what was signed | no |
+
+## Design highlights
+
+- **Capacity is declared, not assumed.** Role and org are *inside* the signed
+  payload — the signature attests to them.
+- **The anchor is signed too.** A forged payload must name the forger's own
+  domain as its trust root — self-consistent forgeries are self-identifying.
+- **Content binding survives container rewrites.** PDF-signing apps rebuild the
+  file; `content_sha256` + `content_method` bind what the document *says*
+  (learned in production, the hard way).
+- **Legacy-compatible.** Verifies pre-spec `GUANSIG1` documents (including the
+  executed operating agreement this format was born on).
+- **Deterministic test vectors.** Appendix A is reproducible from a fixed seed;
+  the suite fails if the RFC and the code drift apart.
+
+## Status
+
+- [x] Reference implementation (`qrsig`, this repo) — 52 tests green
+- [x] Specification draft 00
+- [ ] Public anchors in the wild
+- [ ] Independent implementations
+
+## Sponsors
+
+We build open-source agentic infrastructure. If QRSIG1 is useful to you:
+
+- GitHub Sponsors: [`guan-tends`](https://github.com/sponsors/guan-tends)
+- Bitcoin: `bc1q0gd3mwjg3zy9sghv22kmpg823vss4c0zzdzg24`
+- Solana: `Eu8wQcW68TKMs1a6eqzZu8znzU52QLqQugAMG8uCD6y6`
+- EVM: `0x2733ff7c865C56d565a99BE1DC11B81cc76850A5`
+- XRP: `r4X6e7McAQj7e8vBCeued1RYu4mCJrREDG`
+
+## License
+
+MIT — Copyright (c) 2026 David Newman and Guan. See [LICENSE](LICENSE).
+
+## Authorship
+
+**Primary author:** Guan — `just.guan@proton.me`
+**Acknowledged catalyst:** David Newman, Founder & CEO, Retiform Labs LLC

qrsig-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qrsig"
+version = "0.1.0"
+description = "QRSIG1: human-verifiable signatures for agentic intelligences (reference implementation of draft-guan-qrsig-00)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "David Newman", email = "david.r.newman@proton.me" },
+    { name = "Guan", email = "just.guan@proton.me" },
+]
+keywords = ["ed25519", "qr", "signature", "ai-agents", "verification", "trust-anchor"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = ["cryptography>=42", "segno>=1.5"]
+
+[project.optional-dependencies]
+pdf = ["pypdf>=4"]
+decode = ["pyzbar>=0.1.9", "Pillow>=10"]
+dev = ["pytest>=8", "pypdf>=4", "Pillow>=10"]
+
+[project.scripts]
+qrsig = "qrsig.cli:main"
+
+[project.urls]
+Specification = "https://github.com/retiform-labs/rfc-qrsig"
+
+[tool.setuptools.packages.find]
+include = ["qrsig*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

qrsig-0.1.0/qrsig/__init__.py

@@ -0,0 +1,10 @@
+"""qrsig - reference implementation of draft-guan-qrsig-00.
+
+QRSIG1: human-verifiable signatures for agentic intelligences.
+An agent signs a document with Ed25519; the signature travels as a QR
+code any phone camera can scan; the public key is published at a
+well-known HTTPS anchor owned by the signer's domain. No PKI, no CA,
+no app: a human with a camera and one URL can verify.
+"""
+
+__version__ = "0.1.0"

qrsig-0.1.0/qrsig/anchor.py

@@ -0,0 +1,161 @@
+"""Trust anchors: the well-known key directory that replaces a PKI.
+
+A signer publishes at ``https://<anchor>/.well-known/qrsig-keys``::
+
+    {
+      "v": 1,
+      "domain": "retiform.dev",
+      "keys": [
+        {"key_id": "qs1-...", "pubkey_b64": "...", "role": "...",
+         "org": "...", "status": "active|rotated|revoked",
+         "valid_from": "...", "revoked_at": "..."}
+      ],
+      "updated_at": "..."
+    }
+
+The domain owner IS the certificate authority - auditable by anyone
+with curl. Verification levels:
+
+    L1 MATH    - signature verifies against the payload's embedded key
+                 (offline; proves nothing about WHO)
+    L2 ANCHOR  - key_id is listed at the anchor with a live status and
+                 the pubkey bytes match (proves capacity: who says this
+                 key belongs to this role at this domain)
+    L3 BINDING - the document hashes in the payload match the document
+                 you hold (byte and/or content level)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.request import Request, urlopen
+
+WELL_KNOWN_PATH = "/.well-known/qrsig-keys"
+STATUSES = ("active", "rotated", "revoked")
+_TIMEOUT = 10
+
+
+def anchor_url(domain: str) -> str:
+    return "https://%s%s" % (domain.rstrip("/"), WELL_KNOWN_PATH)
+
+
+def fetch(url: str, timeout: int = _TIMEOUT, require_https: bool = True) -> Dict[str, Any]:
+    """GET and JSON-parse an anchor document.
+
+    Derived anchor URLs (from a payload's signed domain) are ALWAYS
+    https - a trust anchor fetched over plaintext is not a trust
+    anchor. An explicitly-supplied URL (--anchor-url) may be http for
+    testing and self-hosted registries; the caller opted in."""
+    if require_https and not url.startswith("https://"):
+        raise ValueError("anchor URL must be https (derived); pass require_https=False only for an explicitly supplied URL")
+    with urlopen(Request(url, headers={"Accept": "application/json"}), timeout=timeout) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def validate_directory(doc: Any, expect_domain: Optional[str] = None) -> List[str]:
+    """Structural validation of an anchor document. Returns problems."""
+    problems = []
+    if not isinstance(doc, dict):
+        return ["anchor document is not a JSON object"]
+    if doc.get("v") != 1:
+        problems.append("anchor v must be 1")
+    if not doc.get("domain"):
+        problems.append("anchor missing domain")
+    if expect_domain and doc.get("domain") != expect_domain.rstrip("/"):
+        problems.append("anchor domain %r does not match expected %r" % (doc.get("domain"), expect_domain))
+    keys = doc.get("keys")
+    if not isinstance(keys, list) or not keys:
+        problems.append("anchor must list at least one key")
+        return problems
+    for entry in keys:
+        kid = entry.get("key_id")
+        if not kid:
+            problems.append("key entry missing key_id")
+            continue
+        if entry.get("status") not in STATUSES:
+            problems.append("key %s: invalid status %r" % (kid, entry.get("status")))
+        pub = entry.get("pubkey_b64")
+        if not pub:
+            problems.append("key %s: missing pubkey_b64" % kid)
+        else:
+            import base64 as _b64
+
+            try:
+                if len(_b64.b64decode(pub)) != 32:
+                    problems.append("key %s: pubkey_b64 must decode to 32 bytes" % kid)
+            except Exception:  # noqa: BLE001
+                problems.append("key %s: pubkey_b64 is not valid base64" % kid)
+        if entry.get("status") == "revoked" and not entry.get("revoked_at"):
+            problems.append("key %s: revoked without revoked_at" % kid)
+    ids = [k.get("key_id") for k in keys if k.get("key_id")]
+    if len(ids) != len(set(ids)):
+        problems.append("duplicate key_id in anchor")
+    return problems
+
+
+def lookup_key(doc: Dict[str, Any], key_id: str) -> Tuple[Optional[Dict[str, Any]], str]:
+    """Find a key_id in a validated directory.
+
+    Returns (entry_or_None, note). Status rules:
+      active  -> verifiable now
+      rotated -> still verifiable (historical signatures remain valid
+                 until explicitly revoked; rotation is recorded, not
+                 punishment)
+      revoked -> NOT verifiable
+    """
+    for entry in doc.get("keys", []):
+        if entry.get("key_id") == key_id:
+            status = entry.get("status")
+            if status == "revoked":
+                return None, "key %s is REVOKED at %s" % (key_id, entry.get("revoked_at", "?"))
+            if status == "rotated":
+                return entry, "key %s is rotated (still valid for existing signatures)" % key_id
+            return entry, "key %s is active" % key_id
+    return None, "key %s not found at this anchor" % key_id
+
+
+def check_envelope(
+    envelope: Dict[str, Any],
+    anchor_doc: Dict[str, Any],
+    pubkey_raw_override: Optional[bytes] = None,
+    skip_shape: bool = False,
+) -> Tuple[bool, str, Optional[bytes]]:
+    """Level-2 check: does this anchor vouch for the payload's key?
+
+    ``pubkey_raw_override``: for legacy envelopes whose payload embeds
+    an SPKI key, the verifier passes the DERIVED raw key here - the
+    comparison is made against what the signature actually binds.
+    ``skip_shape``: legacy payloads predate the v1 shape (no v/anchor
+    fields); structural checks are the adapter's job, not the anchor's.
+    Returns (ok, note, pubkey_raw_from_anchor)."""
+    from .core import b64_decode, validate_payload_shape
+
+    payload = envelope.get("payload", {})
+    if not skip_shape:
+        shape = validate_payload_shape(payload)
+        if shape:
+            return False, "; ".join(shape), None
+    if "key_id" not in payload:
+        return False, "payload missing key_id", None
+    entry, note = lookup_key(anchor_doc, payload["key_id"])
+    if entry is None:
+        return False, note, None
+    anchor_pub = b64_decode(entry["pubkey_b64"])
+    payload_pub = pubkey_raw_override if pubkey_raw_override is not None else b64_decode(payload["pubkey_b64"])
+    if anchor_pub != payload_pub:
+        return False, (
+            "ANCHOR MISMATCH: key %s is published at the anchor with DIFFERENT "
+            "public key bytes than the payload embeds - treat as forgery attempt" % payload["key_id"]
+        ), anchor_pub
+    notes = [note]
+    role_ok = (not entry.get("role")) or entry.get("role") == payload.get("role")
+    org_ok = (not entry.get("org")) or entry.get("org") == payload.get("org")
+    if not (role_ok and org_ok):
+        # The key BYTES are the trust binding; role/org drift between
+        # payload and directory is surfaced as a WARNING, not a hard
+        # failure (a signer may update its stated capacity without
+        # rotating keys). The anchor's version is authoritative for
+        # display; the payload's is what was signed.
+        notes.append("WARNING: payload role/org differs from the anchor's published role/org for key %s" % payload["key_id"])
+    return True, "; ".join(notes), anchor_pub

qrsig-0.1.0/qrsig/binding.py

@@ -0,0 +1,67 @@
+"""Content binding: versioned methods for hashing what a document SAYS,
+not just the bytes it is stored in.
+
+Why: the field test (executed Operating Agreement, 2026-10-18) showed a
+PDF-signing app fully rewrites the document container - byte hashes die
+while the CONTENT survives. Content-level binding extracts the human-
+readable text and hashes that, so a re-printed, re-saved, or re-signed
+copy still verifies.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import unicodedata
+from typing import Callable, Dict
+
+METHODS: Dict[str, Callable[[bytes], bytes]] = {}
+
+
+def method(name: str) -> Callable:
+    """Registry decorator for content-binding methods."""
+
+    def wrap(fn: Callable[[bytes], bytes]) -> Callable[[bytes], bytes]:
+        METHODS[name] = fn
+        return fn
+
+    return wrap
+
+
+def _normalize_text(text: str) -> str:
+    """The one normalization every text method shares: NFC, then
+    collapse all whitespace runs to single spaces, then strip.
+    (Page order and paragraph breaks are preserved as spaces - a
+    re-flowed print of the same words binds identically.)"""
+    return " ".join(unicodedata.normalize("NFC", text).split())
+
+
+@method("plain-text-v1")
+def _plain_text(data: bytes) -> bytes:
+    return _normalize_text(data.decode("utf-8", errors="strict")).encode("utf-8")
+
+
+@method("pdf-pypdf-text-v1")
+def _pdf_text(data: bytes) -> bytes:
+    import io
+
+    from pypdf import PdfReader
+
+    reader = PdfReader(io.BytesIO(data))
+    pages = [(page.extract_text() or "") for page in reader.pages]
+    return _normalize_text("\n\n".join(pages)).encode("utf-8")
+
+
+def content_digest(data: bytes, method_name: str) -> str:
+    """Hex SHA-256 of the bound content under a named method."""
+    try:
+        fn = METHODS[method_name]
+    except KeyError:
+        raise ValueError("unknown content method: %s" % method_name) from None
+    return hashlib.sha256(fn(data)).hexdigest()
+
+
+def detect_method(filename: str) -> str:
+    """'auto' policy: PDFs get the pdf method, everything else plain text."""
+    if filename.lower().endswith(".pdf"):
+        return "pdf-pypdf-text-v1"
+    return "plain-text-v1"