Verify a DueReason grant without Node: a Python recipe
Verify a DueReason grant in Python or any language without Node: fetch the JWKS, check the EdDSA signature, expiry and payload hash, step by step.
Updated · 7 min read
In short
- A grant is a signed JWS your executor can check entirely offline against the organization's published keys; nothing about the check requires the TypeScript SDK or even Node.
- The five checks are the same in any language: parse the three-part token, verify the Ed25519 signature against the published JWKS, check that it has not expired and names your organization, then recompute the payload hash and compare it to the ph claim.
- A tested, commented Python port of @duereason/sdk's verifyGrant lives in the SDK's examples directory as a copy-and-adapt recipe, not a published package.
- Whatever language you check in, the rule stays the same: execute only when every check passes, and report the outcome afterward so the grant cannot be replayed.
The strongest part of a DueReason approval is the part that happens after someone clicks approve: the system that actually pays the invoice, deploys the code or changes the access right checks, on its own, that the approval covers exactly what it is about to do. That check is a signed token (a grant) verified against a public key, and it does not require Node or the TypeScript SDK to perform. If your executor is a bash deploy script, a Python pipeline, or anything else that cannot easily pull in a JavaScript dependency, you can verify a grant in about fifty lines of code against the same published keys.
What a grant is
A grant is a compact JWS (three base64url segments separated by dots): a header naming the signing algorithm (EdDSA) and the key id (kid) that signed it, a claims body, and the Ed25519 signature itself. The claims carry org (your organization's slug), act (the action key, such as payment), exp (when the grant expires), and ph, the lowercase hex sha256 of the exact payload that was approved. Verifying a grant means checking all of that before you act, never after.
Step 1: fetch the organization's JWKS
Every organization publishes its current and recently retired signing keys at https://duereason.com/.well-known/duereason/{organization}/jwks.json, a standard JWK Set: a JSON object with a keys array, each entry { kty: "OKP", crv: "Ed25519", x, kid, alg: "EdDSA", use: "sig" }. This endpoint needs no API key; cache the response for a few minutes in a long-running executor, and refetch it when you see a kid you do not recognize, so a key rotation never strands a grant in flight.
Step 2: parse the token and check its header
Split the grant on .; a valid one has exactly three non-empty, base64url-only segments. Base64url-decode and JSON-parse the first segment as the header, and refuse anything whose alg is not exactly EdDSA, whose typ is not exactly duereason-grant+jwt, or that has no non-empty kid. This step alone rejects tokens signed with the wrong algorithm or carrying an unexpected crit extension before you ever touch a cryptography library.
Step 3: verify the Ed25519 signature
Find the JWK in the fetched JWKS whose kid matches the header's; if none matches, refuse the grant outright; a key your organization never published verifies nothing. Decode that JWK's x field (the raw 32-byte Ed25519 public key, base64url-encoded) and use it to verify the signature (the third segment, also base64url, and exactly 64 bytes for Ed25519) over the ASCII bytes of {header segment}.{claims segment}, joined by a literal dot. Python's cryptography package does this in two lines with Ed25519PublicKey.from_public_bytes and .verify(); most languages have an equivalent Ed25519 primitive, since it needs no padding scheme or curve parameters beyond the raw public key.
Step 4: check expiry, organization and action
Only once the signature verifies should you trust the claims body enough to read it. Decode and parse it, confirm every required claim (iss, org, sub, jti, act, ph, apv, iat, exp) is present with the right type, then refuse a grant whose exp is in the past, whose org is not yours, or, when your executor checks a specific action, whose act does not match. These are simple comparisons; the point is to run them in this order, after the signature check, so a forged or edited token never reaches them with claims you have any reason to trust.
Step 5: recompute the payload hash
The binding that stops a changed amount or a changed deploy target is the last check: recompute the sha256 of the canonical JSON of the exact payload you are about to execute (object keys sorted, no extra whitespace, numbers and strings formatted as JSON normally would) and compare it, as a lowercase hex string, to the claims' ph. A grant that verifies perfectly but whose ph does not match the payload in front of you was approved for something else; refuse it the same as a bad signature.
The reference script
A tested, line-commented Python port of @duereason/sdk's verifyGrant, implementing exactly these five steps with the same failure reasons (malformed, unknown_key, bad_signature, expired, wrong_organization, wrong_action, payload_mismatch), ships in the SDK's source tree as duereason/sdk/examples/python/verify_grant.py, together with a test file exercising a known-good grant, a tampered payload, an expired grant and a forged signature. It depends only on Python's standard library plus the widely used cryptography package for the Ed25519 check; it is example code to copy into your own executor and adapt, not a maintained package published to PyPI, so pin and review it like you would any code you vendor.
Whatever language you use
The five checks above translate directly to Go, Rust, Ruby or plain openssl on the command line: fetch the JWKS, parse the header, verify the Ed25519 signature over header.claims, check exp/org/act, and compare ph to the payload's canonical sha256. None of it needs a DueReason-specific library; it needs a JWS-shaped token, a public key, and a hash function every language already has.
Questions
- Do I need an API key to fetch the JWKS?
- No. The JWKS endpoint is public (it has to be, for any executor to verify a grant offline) and does not accept or require authentication.
- Can I skip the signature check and just compare the payload hash?
- No. Without the signature check, anyone who can guess or observe your payload shape could construct a token with a matching ph and no valid approval behind it. The signature is what proves DueReason, not an attacker, issued the claims.
- What if my language has no Ed25519 library?
- Ed25519 is widely supported: OpenSSL 1.1.1 and later, Python's cryptography, Go's crypto/ed25519, Rust's ed25519-dalek, and Ruby's rbnacl all implement it. If yours genuinely does not, call POST /api/v1/grants/verify instead and let DueReason's server perform the check.
- Does verifying a grant consume it?
- No. Verification is read-only and can be repeated. Report the execution afterward (POST /approvals/{id}/executions); DueReason accepts the first report for a grant and answers already_executed to any later one, which is what actually prevents a grant from being used twice.
- Is the Python script kept in sync with the TypeScript SDK?
- It mirrors the checks in @duereason/sdk's verifyGrant and ships with tests against the same kind of fixtures. Treat it as a reference to adapt, not a package with its own release cycle; re-check it against the SDK if you rely on it for a long time.
Read the full grant and API reference
Every claim in a grant, the JWKS endpoint, the Node.js verification example and the error reasons an executor can see live in the API reference.
Read the API docsSources
- RFC 8037: CFRG Elliptic Curve Diffie-Hellman and Signatures in JOSE (Ed25519)
- RFC 7517: JSON Web Key (JWK)
- RFC 7515: JSON Web Signature (JWS)
- Python cryptography library: Ed25519 signing and verification
This guide explains the regulation as we read it; it is not legal advice. Check the official text and your national law, which may add obligations.