x402sgl 0.1.0

package/README.md

@@ -0,0 +1,166 @@
+<p align="center">
+  <h1 align="center">Singularity SDK</h1>
+  <p align="center">
+    Server-side receipt verification middleware for the x402 payment protocol — Node.js &amp; Python
+  </p>
+  <p align="center">
+    <a href="https://studio.x402layer.cc/docs/developer/sdk-receipts">Documentation</a>
+    &nbsp;·&nbsp;
+    <a href="https://api.x402layer.cc/.well-known/jwks.json">JWKS Endpoint</a>
+    &nbsp;·&nbsp;
+    <a href="https://studio.x402layer.cc">x402 Studio</a>
+  </p>
+</p>
+
+---
+
+## Overview
+
+When a buyer completes an x402 payment, the worker issues a **signed receipt JWT** containing the transaction details. This SDK provides middleware to cryptographically verify those receipts on your server using RS256 and JWKS — ensuring that only genuine, tamper-proof receipts grant access to your resources.
+
+Both the Node and Python implementations handle JWKS key fetching, caching, signature verification, claim validation, and optional source-slug binding.
+
+---
+
+## Installation
+
+### Node.js
+
+```bash
+npm install github:ivaavimusic/Singularity-SDK
+```
+
+```js
+const { verifyX402ReceiptToken, createX402ReceiptMiddleware } = require('@x402layer/sdk');
+```
+
+### Python
+
+```bash
+pip install git+https://github.com/ivaavimusic/Singularity-SDK.git#subdirectory=python
+```
+
+```python
+from x402layer_middleware import X402ReceiptVerifier, require_x402_receipt
+```
+
+**Python dependencies** (installed automatically): `PyJWT`, `cryptography`. FastAPI is optional — install with `pip install x402layer-sdk[fastapi]`.
+
+---
+
+## Node.js
+
+### API
+
+```js
+const {
+  verifyX402ReceiptToken,
+  createX402ReceiptMiddleware,
+} = require('./x402layer-middleware');
+```
+
+**`verifyX402ReceiptToken(token, options?)`**
+
+Verifies the receipt JWT and returns the decoded claims. Throws on invalid signature, expired token, or claim mismatch.
+
+```js
+const claims = await verifyX402ReceiptToken(token, {
+  requiredSourceSlug: 'my-endpoint', // optional — prevents token replay
+});
+```
+
+**`createX402ReceiptMiddleware(options?)`**
+
+Express middleware that reads the token from `X-X402-Receipt-Token` or `Authorization: Bearer`, verifies it, and attaches the claims to `req.x402Receipt`.
+
+```js
+app.get(
+  '/v1/resource',
+  createX402ReceiptMiddleware({ requiredSourceSlug: 'my-endpoint' }),
+  (req, res) => {
+    res.json({ data: '...', payer: req.x402Receipt.payer_wallet });
+  }
+);
+```
+
+Returns `401` if the token is missing or invalid, `403` if the source slug does not match.
+
+---
+
+## Python
+
+### API
+
+```python
+from x402layer_middleware import X402ReceiptVerifier, require_x402_receipt
+```
+
+**`X402ReceiptVerifier`**
+
+```python
+verifier = X402ReceiptVerifier(
+    jwks_url="https://api.x402layer.cc/.well-known/jwks.json",  # default
+    issuer="https://api.x402layer.cc",                           # default
+    audience="x402layer:receipt",                                # default
+)
+```
+
+**`require_x402_receipt(verifier, required_source_slug?)`**
+
+FastAPI dependency that reads the token from `X-X402-Receipt-Token` or `Authorization: Bearer`, verifies it, and returns the decoded claims.
+
+```python
+@app.get("/v1/resource")
+async def resource(receipt=require_x402_receipt(verifier, required_source_slug="my-endpoint")):
+    return {"payer": receipt["payer_wallet"], "amount": receipt["amount"]}
+```
+
+Raises `HTTP 401` if the token is missing or invalid, `HTTP 403` if the source slug does not match.
+
+---
+
+## Receipt Claims
+
+| Claim | Type | Description |
+|-------|------|-------------|
+| `event` | `string` | Always `"payment.succeeded"` |
+| `source` | `string` | `"endpoint"` or `"product"` |
+| `source_id` | `string` | UUID of the paid resource |
+| `source_slug` | `string` | Slug of the resource |
+| `amount` | `string` | Payment amount (e.g. `"1.00"`) |
+| `currency` | `string` | Asset symbol (e.g. `"USDC"`) |
+| `tx_hash` | `string` | On-chain transaction hash |
+| `payer_wallet` | `string` | Buyer wallet address |
+| `network` | `string` | `"base"` or `"solana"` |
+| `status` | `string` | Settlement status |
+| `iat` | `number` | Issued-at (Unix timestamp) |
+| `exp` | `number` | Expiry (Unix timestamp) |
+| `jti` | `string` | Unique receipt ID — use for idempotency |
+
+---
+
+## Token Contract
+
+| Property | Value |
+|----------|-------|
+| Format | JWT (JWS) |
+| Algorithm | `RS256` |
+| JWKS URL | `https://api.x402layer.cc/.well-known/jwks.json` |
+| Issuer | `https://api.x402layer.cc` |
+| Audience | `x402layer:receipt` |
+
+The token is delivered in the `X-X402-Receipt-Token` response header after a successful payment.
+
+---
+
+## Security
+
+- **Always set `requiredSourceSlug`** in production to prevent receipt replay across resources.
+- The SDK caches JWKS keys in memory (default 5-minute TTL) to avoid excessive network calls.
+- To rotate signing keys: publish a new JWKS entry with a new `kid`, then update the worker private key. Tokens signed with old keys remain verifiable until they expire.
+
+---
+
+## License
+
+MIT

package/node/x402layer-middleware.js

@@ -0,0 +1,112 @@
+/*
+  x402layer receipt middleware (Node/Express)
+  - Verifies RS256 payment receipt JWTs issued by x402layer worker
+  - Uses JWKS from https://api.x402layer.cc/.well-known/jwks.json
+*/
+
+const crypto = require('crypto')
+
+const jwksCache = new Map()
+
+function base64UrlDecode(value) {
+  const normalized = value.replace(/-/g, '+').replace(/_/g, '/')
+  const pad = normalized.length % 4 === 0 ? '' : '='.repeat(4 - (normalized.length % 4))
+  return Buffer.from(normalized + pad, 'base64')
+}
+
+function parseJwt(token) {
+  const parts = token.split('.')
+  if (parts.length !== 3) throw new Error('Invalid JWT format')
+  const [headerB64, payloadB64, signatureB64] = parts
+  const header = JSON.parse(base64UrlDecode(headerB64).toString('utf8'))
+  const payload = JSON.parse(base64UrlDecode(payloadB64).toString('utf8'))
+  const signature = base64UrlDecode(signatureB64)
+  return { header, payload, signature, signingInput: `${headerB64}.${payloadB64}` }
+}
+
+async function fetchJwks(jwksUrl, cacheTtlMs = 5 * 60 * 1000) {
+  const cached = jwksCache.get(jwksUrl)
+  if (cached && Date.now() - cached.fetchedAt < cacheTtlMs) {
+    return cached.keys
+  }
+
+  const res = await fetch(jwksUrl)
+  if (!res.ok) throw new Error(`Failed to fetch JWKS: ${res.status}`)
+  const json = await res.json()
+  if (!json.keys || !Array.isArray(json.keys)) throw new Error('Invalid JWKS payload')
+
+  jwksCache.set(jwksUrl, { keys: json.keys, fetchedAt: Date.now() })
+  return json.keys
+}
+
+function verifyJwtSignature(parsedJwt, jwk) {
+  if (!jwk) throw new Error('Signing key not found')
+  if (jwk.kty !== 'RSA') throw new Error(`Unsupported key type: ${jwk.kty}`)
+  const publicKey = crypto.createPublicKey({ key: jwk, format: 'jwk' })
+  return crypto.verify(
+    'RSA-SHA256',
+    Buffer.from(parsedJwt.signingInput),
+    publicKey,
+    parsedJwt.signature
+  )
+}
+
+function validateClaims(payload, options = {}) {
+  const now = Math.floor(Date.now() / 1000)
+  const issuer = options.issuer || 'https://api.x402layer.cc'
+  const audience = options.audience || 'x402layer:receipt'
+
+  if (payload.iss !== issuer) throw new Error('Invalid issuer')
+  if (payload.aud !== audience) throw new Error('Invalid audience')
+  if (!payload.exp || payload.exp < now) throw new Error('Receipt token expired')
+  if (payload.iat && payload.iat > now + 60) throw new Error('Invalid iat')
+  if (payload.event !== 'payment.succeeded') throw new Error('Invalid receipt event')
+}
+
+async function verifyX402ReceiptToken(token, options = {}) {
+  const jwksUrl = options.jwksUrl || 'https://api.x402layer.cc/.well-known/jwks.json'
+  const parsed = parseJwt(token)
+
+  if (parsed.header.alg !== 'RS256') {
+    throw new Error(`Unsupported algorithm: ${parsed.header.alg}`)
+  }
+
+  const keys = await fetchJwks(jwksUrl, options.cacheTtlMs)
+  const jwk = keys.find((key) => key.kid === parsed.header.kid) || keys[0]
+  const validSignature = verifyJwtSignature(parsed, jwk)
+  if (!validSignature) throw new Error('Invalid receipt signature')
+
+  validateClaims(parsed.payload, options)
+  return parsed.payload
+}
+
+function createX402ReceiptMiddleware(options = {}) {
+  return async function x402ReceiptMiddleware(req, res, next) {
+    try {
+      const headerToken = req.headers['x-x402-receipt-token']
+      const authHeader = req.headers.authorization || ''
+      const bearerToken = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : null
+      const token = headerToken || bearerToken
+
+      if (!token) {
+        return res.status(401).json({ error: 'Missing receipt token' })
+      }
+
+      const claims = await verifyX402ReceiptToken(token, options)
+
+      if (options.requiredSourceSlug && claims.source_slug !== options.requiredSourceSlug) {
+        return res.status(403).json({ error: 'Token source mismatch' })
+      }
+
+      req.x402Receipt = claims
+      return next()
+    } catch (err) {
+      return res.status(401).json({ error: err.message || 'Invalid receipt token' })
+    }
+  }
+}
+
+module.exports = {
+  verifyX402ReceiptToken,
+  createX402ReceiptMiddleware
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "x402sgl",
+    "version": "0.1.0",
+    "description": "Server-side receipt verification middleware for the x402 payment protocol",
+    "main": "node/x402layer-middleware.js",
+    "exports": {
+        ".": "./node/x402layer-middleware.js"
+    },
+    "files": [
+        "node/x402layer-middleware.js",
+        "README.md"
+    ],
+    "keywords": [
+        "x402",
+        "payment",
+        "receipt",
+        "jwt",
+        "jwks",
+        "middleware",
+        "express",
+        "crypto",
+        "usdc",
+        "base",
+        "solana"
+    ],
+    "author": "x402 Studio",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/ivaavimusic/Singularity-SDK.git"
+    },
+    "homepage": "https://studio.x402layer.cc/docs/developer/sdk-receipts",
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}