regent-receipt-verify 0.1.0__tar.gz

regent_receipt_verify-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/
+node_modules/
+*.tgz
+.DS_Store

regent_receipt_verify-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

regent_receipt_verify-0.1.0/NOTICE

@@ -0,0 +1,3 @@
+Copyright 2026 Regent Protocol
+
+Licensed under the Apache License, Version 2.0 (the "License"); see LICENSE.

regent_receipt_verify-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.5
+Name: regent-receipt-verify
+Version: 0.1.0
+Summary: Verify Regent Control receipts and allow tokens offline against a saved JWKS; open mandate and policy reveals
+Project-URL: Homepage, https://github.com/regent-protocol/regent-receipt-verify
+Project-URL: Source, https://github.com/regent-protocol/regent-receipt-verify
+Project-URL: Issues, https://github.com/regent-protocol/regent-receipt-verify/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# regent-receipt-verify
+
+Verify a Regent Control **receipt** or **allow token** without Regent: only the token and a JWKS
+you saved while the issuer was reachable. Nothing calls the network. One dependency
+(`cryptography`) for RS256.
+
+```
+pip install regent-receipt-verify
+curl -s https://control-api.regentprotocol.org/v1/control/.well-known/jwks.json > jwks-2026-09.json   # save it now, keep it with the receipts
+regent-verify @receipt.txt --jwks jwks-2026-09.json --request request.json --mandate mandate-v2-reveal.json --policy policy-v3-reveal.json
+```
+
+```python
+from regent_receipt_verify import verify
+res = verify(token, jwks, request={"tool": "stripe", "action": "charge.create", "resource": None, "args": {...}},
+             mandate_reveal=reveal_from_owner, policy_reveal=policy_reveal_from_org)
+res.valid, res.kind, res.claims, res.args_hash_match, res.mandate_match, res.policy_match
+```
+
+What it proves:
+
+| check | meaning |
+|---|---|
+| signature (RS256, kid from the JWKS) | Regent's issuer signed exactly these claims |
+| `kind` receipt / allow / budget | a receipt (`typ receipt+jwt`, `aud regent-receipt`) can never pass as an access token |
+| `expired` | receipts carry a 10-year evidence period; an allow token lives about a minute, so for evidence its expiry is a note, not a failure |
+| `args_hash_match` | the token authorised this exact request (tool, action, resource, args) and nothing else |
+| `mandate_match` | the owner's revealed mandate version (snapshot + salt, `terms-v2`) opens the receipt's `mandate_hash` |
+| `policy_match` | the organisation's revealed policy version (text + profile + salt, `policy-v1`) opens `policy_hash`; starter-pack decisions need only the public text |
+
+Key rotation: pass `--jwks` several times (every JWKS you saved). Exit code 0 when the signature
+verifies and every supplied check matches.
+
+Test vectors are minted by the real issuer (`packages/receipt-verify-vectors`), and the same
+file drives the Node package `@regent-protocol/receipt-verify`.

regent_receipt_verify-0.1.0/README.md

@@ -0,0 +1,35 @@
+# regent-receipt-verify
+
+Verify a Regent Control **receipt** or **allow token** without Regent: only the token and a JWKS
+you saved while the issuer was reachable. Nothing calls the network. One dependency
+(`cryptography`) for RS256.
+
+```
+pip install regent-receipt-verify
+curl -s https://control-api.regentprotocol.org/v1/control/.well-known/jwks.json > jwks-2026-09.json   # save it now, keep it with the receipts
+regent-verify @receipt.txt --jwks jwks-2026-09.json --request request.json --mandate mandate-v2-reveal.json --policy policy-v3-reveal.json
+```
+
+```python
+from regent_receipt_verify import verify
+res = verify(token, jwks, request={"tool": "stripe", "action": "charge.create", "resource": None, "args": {...}},
+             mandate_reveal=reveal_from_owner, policy_reveal=policy_reveal_from_org)
+res.valid, res.kind, res.claims, res.args_hash_match, res.mandate_match, res.policy_match
+```
+
+What it proves:
+
+| check | meaning |
+|---|---|
+| signature (RS256, kid from the JWKS) | Regent's issuer signed exactly these claims |
+| `kind` receipt / allow / budget | a receipt (`typ receipt+jwt`, `aud regent-receipt`) can never pass as an access token |
+| `expired` | receipts carry a 10-year evidence period; an allow token lives about a minute, so for evidence its expiry is a note, not a failure |
+| `args_hash_match` | the token authorised this exact request (tool, action, resource, args) and nothing else |
+| `mandate_match` | the owner's revealed mandate version (snapshot + salt, `terms-v2`) opens the receipt's `mandate_hash` |
+| `policy_match` | the organisation's revealed policy version (text + profile + salt, `policy-v1`) opens `policy_hash`; starter-pack decisions need only the public text |
+
+Key rotation: pass `--jwks` several times (every JWKS you saved). Exit code 0 when the signature
+verifies and every supplied check matches.
+
+Test vectors are minted by the real issuer (`packages/receipt-verify-vectors`), and the same
+file drives the Node package `@regent-protocol/receipt-verify`.

regent_receipt_verify-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "regent-receipt-verify"
+version = "0.1.0"
+description = "Verify Regent Control receipts and allow tokens offline against a saved JWKS; open mandate and policy reveals"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+dependencies = ["cryptography>=41.0"]
+
+[project.urls]
+Homepage = "https://github.com/regent-protocol/regent-receipt-verify"
+Source = "https://github.com/regent-protocol/regent-receipt-verify"
+Issues = "https://github.com/regent-protocol/regent-receipt-verify/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0"]
+
+[project.scripts]
+regent-verify = "regent_receipt_verify.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/regent_receipt_verify"]

regent_receipt_verify-0.1.0/src/regent_receipt_verify/__init__.py

@@ -0,0 +1,254 @@
+"""regent-receipt-verify — check a Regent Control receipt or allow token without Regent.
+
+Everything needed is in the token and a JWKS you saved while the issuer was reachable
+(GET https://control-api.regentprotocol.org/v1/control/.well-known/jwks.json). Nothing here
+calls the network. Signature: RS256 via `cryptography`. Commitments: the same canonical
+strings as the gate (terms-v2 for mandates, policy-v1 for policies) and the same request
+hash (sha256 over canonical JSON of {tool, action, resource, args}).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+
+__version__ = "0.1.0"
+__all__ = [
+    "VerificationResult", "verify_token", "verify", "canonical_args_hash", "check_request_binding",
+    "mandate_commitment", "check_mandate_reveal", "policy_commitment", "check_policy_reveal",
+]
+
+
+# ── JWS ───────────────────────────────────────────────────────────────────────
+
+def _b64url_decode(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def _b64url_uint(s: str) -> int:
+    return int.from_bytes(_b64url_decode(s), "big")
+
+
+def _keys(jwks: Any) -> list[dict[str, Any]]:
+    """Accept a JWKS dict, a list of JWKS dicts (key rotation), or a list of JWKs."""
+    if isinstance(jwks, dict) and "keys" in jwks:
+        return list(jwks["keys"])
+    if isinstance(jwks, dict):
+        return [jwks]
+    out: list[dict[str, Any]] = []
+    for item in jwks or []:
+        out.extend(_keys(item))
+    return out
+
+
+@dataclass
+class VerificationResult:
+    signature_valid: bool
+    kind: str                      # receipt | allow | budget | unknown
+    header: dict[str, Any] = field(default_factory=dict)
+    claims: dict[str, Any] = field(default_factory=dict)
+    kid: str | None = None
+    expired: bool | None = None
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    # populated by verify() when the optional inputs are given
+    args_hash_match: bool | None = None
+    mandate_match: bool | None = None
+    policy_match: bool | None = None
+
+    @property
+    def valid(self) -> bool:
+        """Authentic and, for a receipt, still inside its evidence period."""
+        return self.signature_valid and not self.errors
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "valid": self.valid, "signature_valid": self.signature_valid, "kind": self.kind, "kid": self.kid,
+            "expired": self.expired, "args_hash_match": self.args_hash_match, "mandate_match": self.mandate_match,
+            "policy_match": self.policy_match, "errors": self.errors, "warnings": self.warnings,
+            "header": self.header, "claims": self.claims,
+        }
+
+
+def _kind(header: dict[str, Any], claims: dict[str, Any]) -> str:
+    typ = str(header.get("typ") or "")
+    if typ == "receipt+jwt" or claims.get("aud") == "regent-receipt":
+        return "receipt"
+    if typ == "aa-auth+jwt" or "budget" in claims:
+        return "budget"
+    if "scope" in claims and "decision_id" in claims:
+        return "allow"
+    return "unknown"
+
+
+def verify_token(token: str, jwks: Any, *, now: float | None = None, issuer: str | None = "regent-control") -> VerificationResult:
+    """Signature + structure. Returns a result even for invalid tokens (never raises on bad input)."""
+    now = time.time() if now is None else now
+    parts = token.strip().split(".")
+    if len(parts) != 3:
+        return VerificationResult(False, "unknown", errors=["not a compact JWS (expected header.payload.signature)"])
+    try:
+        header = json.loads(_b64url_decode(parts[0]))
+        claims = json.loads(_b64url_decode(parts[1]))
+        signature = _b64url_decode(parts[2])
+    except Exception as exc:  # noqa: BLE001
+        return VerificationResult(False, "unknown", errors=[f"cannot decode token: {exc}"])
+    res = VerificationResult(False, _kind(header, claims), header=header, claims=claims, kid=header.get("kid"))
+    if header.get("alg") != "RS256":
+        res.errors.append(f"unsupported alg {header.get('alg')!r} (Regent signs RS256)")
+        return res
+    candidates = [k for k in _keys(jwks) if k.get("kty") == "RSA" and (res.kid is None or k.get("kid") == res.kid)]
+    if not candidates:
+        res.errors.append(f"no RSA key with kid {res.kid!r} in the JWKS you supplied")
+        return res
+    signed = f"{parts[0]}.{parts[1]}".encode("ascii")
+    for k in candidates:
+        try:
+            pub = rsa.RSAPublicNumbers(_b64url_uint(k["e"]), _b64url_uint(k["n"])).public_key()
+            pub.verify(signature, signed, padding.PKCS1v15(), hashes.SHA256())
+            res.signature_valid = True
+            res.kid = k.get("kid")
+            break
+        except (InvalidSignature, ValueError, KeyError):
+            continue
+    if not res.signature_valid:
+        res.errors.append("signature does not verify against the supplied key(s)")
+        return res
+    # structure
+    if issuer and claims.get("iss") != issuer:
+        res.errors.append(f"issuer is {claims.get('iss')!r}, expected {issuer!r}")
+    if res.kind == "receipt" and claims.get("aud") != "regent-receipt":
+        res.errors.append("receipt audience must be 'regent-receipt'")
+    exp = claims.get("exp")
+    if isinstance(exp, (int, float)):
+        res.expired = exp < now
+        if res.expired:
+            if res.kind == "receipt":
+                res.errors.append("receipt is past its evidence period (exp)")
+            else:
+                res.warnings.append("token expired (allow tokens live about a minute; signature and binding still verify)")
+    iat = claims.get("iat")
+    if isinstance(iat, (int, float)) and iat > now + 300:
+        res.errors.append("issued in the future (iat)")
+    if res.kind == "allow" and "scope" in claims and claims.get("scope") != f"{claims.get('aud')}:{claims.get('scope','').split(':', 1)[-1]}":
+        res.warnings.append("scope does not start with the audience tool")
+    return res
+
+
+# ── request binding (args_hash) ───────────────────────────────────────────────
+
+def canonical_args_hash(tool: str, action: str, resource: str | None, args: dict[str, Any] | None) -> str:
+    """Byte-identical to the gate: sha256 over canonical JSON of {tool, action, resource, args}."""
+    canonical = json.dumps({"tool": tool, "action": action, "resource": resource, "args": args or {}},
+                           sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def check_request_binding(claims: dict[str, Any], *, tool: str, action: str, resource: str | None = None,
+                          args: dict[str, Any] | None = None) -> bool:
+    expected = claims.get("args_hash")
+    return bool(expected) and hmac.compare_digest(canonical_args_hash(tool, action, resource, args), str(expected))
+
+
+# ── mandate terms (terms-v2) ──────────────────────────────────────────────────
+
+MANDATE_FIELDS = ("mandate_id", "version", "agent_id", "owner_id", "currency", "settlement_chain", "status",
+                  "per_tx_limit", "daily_limit", "monthly_limit", "per_entity_limit", "entity_key", "relational_cap",
+                  "expires_at", "agent_may_read_limits")
+
+
+def _cv(value: Any) -> str:
+    if value is None:
+        return "none"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    return str(value)
+
+
+def mandate_canonical_string(snapshot: dict[str, Any], salt: str) -> str:
+    return "|".join(["terms-v2", *(f"{n}={_cv(snapshot.get(n))}" for n in MANDATE_FIELDS), f"salt={salt}"])
+
+
+def mandate_commitment(snapshot: dict[str, Any], salt: str) -> str:
+    return hashlib.sha256(mandate_canonical_string(snapshot, salt).encode("utf-8")).hexdigest()
+
+
+def check_mandate_reveal(claims: dict[str, Any], reveal: dict[str, Any]) -> bool:
+    """`reveal` = the owner's version object ({snapshot, salt, ...}) or {snapshot, salt}."""
+    expected = str(claims.get("mandate_hash") or "")
+    snap = reveal.get("snapshot") if isinstance(reveal.get("snapshot"), dict) else reveal
+    salt = str(reveal.get("salt") or "")
+    if not expected or not salt:
+        return False
+    if "version" in snap and claims.get("mandate_version") is not None and int(snap["version"]) != int(claims["mandate_version"]):
+        return False
+    return hmac.compare_digest(mandate_commitment(snap, salt.lower()), expected.lower())
+
+
+# ── policy (policy-v1) ────────────────────────────────────────────────────────
+
+def _text_digest(text: str) -> str:
+    return hashlib.sha256((text or "").encode("utf-8")).hexdigest()
+
+
+def policy_canonical_string(org_id: str, version: int, cedar_text: str, profile: dict[str, Any] | None, salt: str) -> str:
+    prof = None if profile is None else hashlib.sha256(
+        json.dumps(profile, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")).hexdigest()
+    return "|".join(["policy-v1", f"org_id={org_id}", f"version={int(version)}", f"text_sha256={_text_digest(cedar_text)}",
+                     f"profile_sha256={prof if prof is not None else 'none'}", f"salt={salt}"])
+
+
+def policy_commitment(org_id: str, version: int, cedar_text: str, profile: dict[str, Any] | None, salt: str) -> str:
+    return hashlib.sha256(policy_canonical_string(org_id, version, cedar_text, profile, salt).encode("utf-8")).hexdigest()
+
+
+def check_policy_reveal(claims: dict[str, Any], reveal: dict[str, Any] | str) -> bool:
+    """`reveal` = the org's version object ({org_id, version, cedar_text, profile, salt}); for a
+    starter-pack or legacy decision the Cedar text alone (str or {cedar_text})."""
+    expected = str(claims.get("policy_hash") or "")
+    if not expected:
+        return False
+    if isinstance(reveal, str):
+        reveal = {"cedar_text": reveal}
+    text = reveal.get("cedar_text") if isinstance(reveal.get("cedar_text"), str) else reveal.get("cedar")
+    if not isinstance(text, str):
+        return False
+    if claims.get("policy_source") in ("starter", "legacy"):
+        return hmac.compare_digest(_text_digest(text), expected.lower())
+    try:
+        version = reveal["version"] if reveal.get("version") is not None else claims.get("policy_version")
+        got = policy_commitment(str(reveal.get("org_id") or ""), int(version), text,
+                                reveal.get("profile") if isinstance(reveal.get("profile"), dict) else None,
+                                str(reveal.get("salt") or "").lower())
+    except (TypeError, ValueError):
+        return False
+    return hmac.compare_digest(got, expected.lower())
+
+
+# ── one call for everything ───────────────────────────────────────────────────
+
+def verify(token: str, jwks: Any, *, request: dict[str, Any] | None = None, mandate_reveal: dict[str, Any] | None = None,
+           policy_reveal: dict[str, Any] | str | None = None, now: float | None = None,
+           issuer: str | None = "regent-control") -> VerificationResult:
+    res = verify_token(token, jwks, now=now, issuer=issuer)
+    if not res.signature_valid:
+        return res
+    if request is not None:
+        res.args_hash_match = check_request_binding(res.claims, tool=request.get("tool", ""), action=request.get("action", ""),
+                                                    resource=request.get("resource"), args=request.get("args"))
+    if mandate_reveal is not None:
+        res.mandate_match = check_mandate_reveal(res.claims, mandate_reveal)
+    if policy_reveal is not None:
+        res.policy_match = check_policy_reveal(res.claims, policy_reveal)
+    return res

regent_receipt_verify-0.1.0/src/regent_receipt_verify/cli.py

@@ -0,0 +1,69 @@
+"""regent-verify — command line for regent_receipt_verify.
+
+  regent-verify TOKEN --jwks jwks.json [--jwks older.json] [--request req.json]
+                      [--mandate reveal.json] [--policy reveal.json|text.cedar] [--json] [--now EPOCH]
+
+Exit 0 when the signature verifies and every supplied check matches; 1 otherwise."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__, verify
+
+
+def _load(path: str):
+    with open(path, encoding="utf-8") as f:
+        text = f.read()
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text  # a Cedar text file for --policy
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="regent-verify", description="Verify a Regent receipt or allow token offline.")
+    ap.add_argument("token", help="the JWT, or @file to read it from a file")
+    ap.add_argument("--jwks", action="append", required=True, help="saved JWKS file (repeat for older keys)")
+    ap.add_argument("--request", help='JSON {"tool","action","resource","args"} to check args_hash')
+    ap.add_argument("--mandate", help="mandate version reveal JSON from the owner")
+    ap.add_argument("--policy", help="policy version reveal JSON, or the Cedar text for starter-pack decisions")
+    ap.add_argument("--issuer", default="regent-control")
+    ap.add_argument("--now", type=float, help="epoch seconds to evaluate exp against (default: now)")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    ap.add_argument("--version", action="version", version=__version__)
+    a = ap.parse_args(argv)
+
+    token = open(a.token[1:], encoding="utf-8").read().strip() if a.token.startswith("@") else a.token
+    res = verify(token, [_load(p) for p in a.jwks],
+                 request=_load(a.request) if a.request else None,
+                 mandate_reveal=_load(a.mandate) if a.mandate else None,
+                 policy_reveal=_load(a.policy) if a.policy else None,
+                 now=a.now, issuer=a.issuer or None)
+    checks = [res.args_hash_match, res.mandate_match, res.policy_match]
+    ok = res.valid and all(c is not False for c in checks)
+    if a.json:
+        print(json.dumps(res.to_dict(), indent=2, ensure_ascii=False))
+        return 0 if ok else 1
+    c = res.claims
+    print(("VALID" if res.valid else "INVALID") + f" — {res.kind} signed by {c.get('iss', '?')} (kid {res.kid})")
+    for e in res.errors:
+        print(f"  error: {e}")
+    for w in res.warnings:
+        print(f"  note: {w}")
+    if res.signature_valid:
+        for k in ("decision_id", "status", "sub", "amount", "currency", "payee", "mandate_id", "mandate_version",
+                  "mandate_hash", "policy_source", "policy_version", "policy_hash", "risk_model", "tool", "action",
+                  "scope", "args_hash", "settlement_mismatch", "jti", "iat", "exp"):
+            if k in c:
+                print(f"  {k}: {c[k]}")
+        for label, val in (("request binding (args_hash)", res.args_hash_match), ("mandate reveal", res.mandate_match),
+                           ("policy reveal", res.policy_match)):
+            if val is not None:
+                print(f"  {label}: {'MATCH' if val else 'NO MATCH'}")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

regent_receipt_verify-0.1.0/tests/test_vectors.py

@@ -0,0 +1,95 @@
+"""Both verifier packages run the same vectors, minted by the real issuer (make_vectors.py)."""
+import json
+import os
+
+import pytest
+
+from regent_receipt_verify import (
+    canonical_args_hash, check_mandate_reveal, check_policy_reveal, check_request_binding, verify, verify_token,
+)
+from regent_receipt_verify.cli import main
+
+V = json.load(open(os.path.join(os.path.dirname(__file__), "..", "..", "receipt-verify-vectors", "vectors.json")))
+NOW = V["now"]
+
+
+def test_args_hash_matches_the_gate():
+    r = V["request"]
+    assert canonical_args_hash(r["tool"], r["action"], r["resource"], r["args"]) == V["args_hash"]
+
+
+@pytest.mark.parametrize("name", ["receipt", "allow"])
+def test_full_verification(name):
+    case = V["cases"][name]
+    res = verify(case["token"], V["jwks"], request=V["request"], mandate_reveal=V["mandate_reveal"],
+                 policy_reveal=V["policy_reveal"], now=NOW)
+    e = case["expect"]
+    assert res.kind == e["kind"] and res.signature_valid is True and res.valid is True
+    assert res.expired is False and res.args_hash_match is True
+    assert res.mandate_match is True and res.policy_match is True
+    assert res.kid == V["jwks"]["keys"][0]["kid"]
+    # every tampering of a reveal or the request must fail to open the commitment
+    assert verify(case["token"], V["jwks"], request=V["wrong_request"], now=NOW).args_hash_match is False
+    bad_m = {**V["mandate_reveal"], "salt": "00" * 32}
+    assert check_mandate_reveal(res.claims, bad_m) is False
+    bad_snap = {**V["mandate_reveal"], "snapshot": {**V["mandate_reveal"]["snapshot"], "daily_limit": "9999.000000"}}
+    assert check_mandate_reveal(res.claims, bad_snap) is False
+    assert check_policy_reveal(res.claims, {**V["policy_reveal"], "cedar_text": V["policy_reveal"]["cedar_text"] + " "}) is False
+    assert check_policy_reveal(res.claims, {**V["policy_reveal"], "profile": None}) is False
+
+
+def test_allow_token_expiry_is_a_note_not_an_error():
+    case = V["cases"]["allow_expired"]
+    res = verify_token(case["token"], V["jwks"], now=case["now"])
+    assert res.signature_valid and res.expired is True and res.valid is True and res.warnings
+
+
+def test_receipt_past_evidence_period_is_invalid():
+    res = verify_token(V["cases"]["receipt"]["token"], V["jwks"], now=NOW + 86400 * 4000)
+    assert res.signature_valid and res.expired is True and res.valid is False
+
+
+def test_starter_policy_opens_with_text_only():
+    res = verify(V["cases"]["starter_receipt"]["token"], V["jwks"], policy_reveal=V["starter_text"], now=NOW)
+    assert res.policy_match is True
+    assert verify(V["cases"]["starter_receipt"]["token"], V["jwks"], policy_reveal=V["starter_text"] + "\n", now=NOW).policy_match is False
+
+
+def test_budget_token_is_classified_and_verifies():
+    res = verify_token(V["cases"]["budget"]["token"], V["jwks"], now=NOW)
+    assert res.kind == "budget" and res.signature_valid
+
+
+def test_wrong_key_and_tampering_fail():
+    assert verify_token(V["cases"]["wrong_key"]["token"], V["jwks"], now=NOW).signature_valid is False
+    assert verify_token(V["cases"]["tampered"]["token"], V["jwks"], now=NOW).signature_valid is False
+    # the wrong key's own JWKS verifies it — key rotation: pass several JWKS
+    assert verify_token(V["cases"]["wrong_key"]["token"], [V["jwks"], V["other_jwks"]], now=NOW).signature_valid is True
+
+
+def test_garbage_never_raises():
+    for bad in ("", "abc", "a.b", "a.b.c", "x" * 10):
+        res = verify_token(bad, V["jwks"], now=NOW)
+        assert res.signature_valid is False and res.errors
+
+
+def test_request_binding_helper():
+    claims = verify_token(V["cases"]["allow"]["token"], V["jwks"], now=NOW).claims
+    r = V["request"]
+    assert check_request_binding(claims, tool=r["tool"], action=r["action"], resource=r["resource"], args=r["args"])
+    assert not check_request_binding(claims, tool=r["tool"], action="charge.refund", resource=r["resource"], args=r["args"])
+
+
+def test_cli(tmp_path, capsys):
+    jw = tmp_path / "jwks.json"; jw.write_text(json.dumps(V["jwks"]))
+    req = tmp_path / "req.json"; req.write_text(json.dumps(V["request"]))
+    man = tmp_path / "m.json"; man.write_text(json.dumps(V["mandate_reveal"]))
+    pol = tmp_path / "p.json"; pol.write_text(json.dumps(V["policy_reveal"]))
+    rc = main([V["cases"]["receipt"]["token"], "--jwks", str(jw), "--request", str(req), "--mandate", str(man),
+               "--policy", str(pol), "--now", str(NOW)])
+    out = capsys.readouterr().out
+    assert rc == 0 and out.startswith("VALID") and "mandate reveal: MATCH" in out and "policy reveal: MATCH" in out
+    rc = main([V["cases"]["tampered"]["token"], "--jwks", str(jw), "--json", "--now", str(NOW)])
+    assert rc == 1 and json.loads(capsys.readouterr().out)["signature_valid"] is False
+    bad = tmp_path / "bad.json"; bad.write_text(json.dumps(V["wrong_request"]))
+    assert main([V["cases"]["allow"]["token"], "--jwks", str(jw), "--request", str(bad), "--now", str(NOW)]) == 1