On-chain RS256 JWT verification

Verify a JSON Web Token inside a smart contract. No oracle, no trusted relayer, no off-chain signer you have to believe.

If an identity provider signs something RS256 — Google, Auth0, Okta, Apple, Keycloak, your own IdP — a contract using this library can check that signature itself and act on the claims.

It was extracted from Flint, where it verifies Google Confidential Space attestation tokens so that an escrow only accepts release signatures from a key proven to live inside measured TEE code. That's one use. The primitive is general.

Install

npm install solidity-jwt

import {JWT} from "solidity-jwt/src/JWT.sol";

Why this works on the EVM

A JWT is base64url(header).base64url(payload).base64url(signature), and RS256 means the signature is RSASSA-PKCS1-v1_5 over SHA-256 of the first two segments joined by a dot. Every piece of that is available on-chain:

| Step | How | |---|---| | SHA-256 | sha256() precompile | | RSA public-key op | modexp precompile, EIP-198, address 0x05 | | base64url | Base64URL.sol | | PKCS#1 v1.5 unpadding | RSAPKCS1.sol |

The modexp precompile is the load-bearing part, and it isn't available everywhere — confirm your chain supports EIP-198 before relying on this. It is present on Ethereum mainnet and on Flare/Coston2, where this is deployed.

Files

| File | Purpose | |---|---| | JWT.sol | The library: verify, split, header, claim, expired | | ../lib/RSAPKCS1.sol | RSASSA-PKCS1-v1_5 / SHA-256 verification via modexp | | ../lib/Base64URL.sol | base64url decoder (RFC 4648 §5) | | JWTVerifierHarness.sol | External wrapper — tests, and the shortest worked example |

Usage

import {JWT} from "./jwt/JWT.sol";

contract GatedByGoogle {
    // Published at the issuer's jwks_uri, base64url-decoded to bytes.
    bytes public modulus;
    bytes public constant EXPONENT = hex"010001";

    function admit(bytes calldata token) external view returns (string memory subject) {
        (bool ok, bytes memory payload) = JWT.verify(
            token,
            JWT.PublicKey({modulus: modulus, exponent: EXPONENT})
        );
        require(ok, "bad signature");

        // The signature is valid — now enforce your own policy.
        require(!JWT.expired(payload, block.timestamp), "expired");
        require(
            keccak256(bytes(JWT.claim(payload, "iss"))) == keccak256("https://accounts.google.com"),
            "wrong issuer"
        );
        require(
            keccak256(bytes(JWT.claim(payload, "aud"))) == keccak256(bytes(EXPECTED_AUDIENCE)),
            "wrong audience"
        );

        return JWT.claim(payload, "sub");
    }
}

Keys rotate, so read kid from the header and look up the matching key before verifying:

string memory kid = JWT.claim(JWT.header(token), "kid");
JWT.PublicKey memory key = keys[kid];

ConfidentialSpaceAttestation.sol is a complete real-world consumer — key registration by kid, signature check, measurement pinning, hardware allow-list, and binding an address out of eat_nonce.

Gas

Measured on Hardhat (scripts/bench/jwt-gas.ts), RSA-2048:

| Token | Size | Gas | |---|---|---| | Minimal ({"s":"a"}) | 376 B | ~345,000 | | Real Confidential Space token | 2,617 B | ~1,920,000 |

Cost is dominated by base64url decoding, not by RSA. The decoder is linear in token size, so a large token costs far more than the signature check itself. If you control the token, keep it small. If you don't, budget for it — the full attestation flow in Flint, including storage writes, costs ~2.68M gas.

Security notes

Read these before using claim.

1. Verify before you read. claim does no signature checking. Only call it on a payload returned by verify with ok == true.

2. claim is a scanner, not a JSON parser. It returns the first "name": "value" match anywhere in the document, at any nesting depth. This is deliberate — real Confidential Space tokens bury image_digest inside submods.container, and a top-level-only parser silently misses it. But it means a claim name that also appears in a nested object could be read from the wrong place. Only use it on payloads whose structure the authenticated issuer controls. It does not handle JSON string escapes.

3. Signature ≠ policy. This library proves who signed. Expiry, issuer, audience, nonce and replay are yours to enforce. expired is a helper, not an automatic check.

4. alg is not read from the token, by design. Choosing the algorithm from attacker-supplied input is the classic JWT vulnerability (alg: none, or RS256→HS256 confusion). Here RS256 is the only thing implemented, and the caller supplies the key. Do check alg yourself if you accept tokens from a source that might send something else.

5. X.509 chains are not walked. You trust that a registered modulus really belongs to the issuer. Verify it against their published JWKS out-of-band, and control who can register keys.

6. Not audited. Written for a hackathon, tested against a real Google token, but no third party has reviewed it.

Tests

npx hardhat test test/jwt.test.ts

17 tests: signature acceptance, payload tampering, wrong key, truncated signature, 4096-bit keys, malformed tokens, nested and numeric claims, expiry, header parsing — plus the real Google-signed Confidential Space token that authorized Flint's enclave on Coston2, pinned with the key that signed it so it stays a valid regression vector after Google rotates.

License

MIT.