@kushbitx/sdk 0.1.5 → 0.1.6

package/README.md

@@ -62,6 +62,24 @@ if (await canSign(report, tx)) {
 }
 ```
 
+### Signature Check: sign only the typed data that was checked
+
+Before an agent signs an EIP-712 request (an x402 payment authorisation, a Permit or a Permit2 message), pay 0.003 USDC for `POST /api/signature-check` with `{ chainId: 8453, signer, typedData }`. The report has `verdict`, `typedDataDigest` and `expiresAt`. `canSignTypedData` recomputes the EIP-712 digest locally and is true only for ALLOW on the same typed data, for the same signer, on Base (`chainId: 8453` in the request and in `typedData.domain`), before `expiresAt`.
+
+```js
+import { canSignTypedData } from '@kushbitx/sdk';
+
+const request = { chainId: 8453, signer: wallet, typedData };   // the exact object you are asked to sign
+// ... pay for POST /api/signature-check with your x402 client, get `report` ...
+if (await canSignTypedData(report, request)) {
+  // ALLOW, same digest, same signer, not expired: sign now
+} else {
+  // REVIEW, BLOCK, changed typed data, another signer or network, or expired: do not sign
+}
+```
+
+`typedDataDigest(typedData)` returns the same digest on its own. Neither function uses the network or a key.
+
 Required checks per transaction type: `requiredChecks` in https://kushbitx.com/api/services.
 
 Current prices: https://kushbitx.com/api/services

package/kushbitx.d.ts

@@ -1,11 +1,12 @@
-// Type declarations for @kushbitx/sdk 0.1.3. The SDK never requests, stores or signs with a private key.
+// Type declarations for @kushbitx/sdk 0.1.6. The SDK never requests, stores or signs with a private key.
 
 /** Paid service names accepted by the payment helpers, and the route each one calls. */
 export type PaidService =
   | 'token-risk'
   | 'preflight' | 'transaction-preflight'
   | 'payment' | 'payment-proof' | 'verify-payment'
-  | 'kushbitx-preflight';
+  | 'kushbitx-preflight'
+  | 'signature-check';
 
 export declare const paidServices: Readonly<Record<PaidService, string>>;
 
@@ -127,6 +128,17 @@ export declare function preflightDigest(transaction: { chainId?: number | string
 /** True only for ALLOW on this exact Base transaction before expiresAt. chainId must be stated and be 8453; a missing or other chainId, or any changed field, is false. */
 export declare function canSign(report: PreflightReport | Record<string, unknown>, transaction: { chainId: number | string | bigint; from?: Address | null; to: Address; value?: string; data?: string }, now?: number): Promise<boolean>;
 
+/** EIP-712 typed data: the exact object a wallet is asked to sign. */
+export interface TypedData { domain: { name?: string; version?: string; chainId?: number | string | bigint; verifyingContract?: Address; salt?: string }; types: Record<string, { name: string; type: string }[]>; primaryType: string; message: Record<string, unknown> }
+/** Input of Signature Check (0.003 USDC). */
+export interface SignatureCheckInput { chainId: 8453; signer: Address; typedData: TypedData; expectedPayTo?: Address; expectedAmount?: string; expectedSpender?: Address }
+/** Signature Check report (fields used by canSignTypedData). */
+export interface SignatureCheckReport { service: 'signature-check'; verdict: 'ALLOW' | 'REVIEW' | 'BLOCK'; typedDataDigest: `0x${string}`; chainId: 8453; signer: Address; expiresAt: string; kind: string; reasonCodes: string[]; [k: string]: unknown }
+/** EIP-712 digest of typed data, computed locally (no network). Equals typedDataDigest in a Signature Check report. Throws on malformed typed data. */
+export declare function typedDataDigest(typedData: TypedData): `0x${string}`;
+/** True only for ALLOW on this exact typed data, for this signer, before expiresAt. request.chainId and typedData.domain.chainId must both be 8453; anything else is false. */
+export declare function canSignTypedData(report: SignatureCheckReport | Record<string, unknown>, request: { chainId: number | string | bigint; signer: Address; typedData: TypedData }, now?: number): Promise<boolean>;
+
 export declare class KushBitxClient {
   constructor(options?: ClientOptions);
   baseUrl: string;
@@ -146,6 +158,7 @@ export declare class KushBitxClient {
 
   /** Ask for the x402 challenge (HTTP 402). Nothing is charged. */
   getPaymentChallenge(service: 'kushbitx-preflight', input: PreflightInput): Promise<PaymentChallenge>;
+  getPaymentChallenge(service: 'signature-check', input: SignatureCheckInput): Promise<PaymentChallenge>;
   getPaymentChallenge(service: 'token-risk', input: TokenInput): Promise<PaymentChallenge>;
   getPaymentChallenge(service: 'preflight' | 'transaction-preflight', input: TransactionInput): Promise<PaymentChallenge>;
   getPaymentChallenge(service: 'payment' | 'payment-proof' | 'verify-payment', input: PaymentProofInput): Promise<PaymentChallenge>;
@@ -153,6 +166,7 @@ export declare class KushBitxClient {
   prepareRecovery(service: PaidService, input: object): Promise<RecoveryCredentials>;
   /** Send an externally signed payment (PAYMENT-SIGNATURE). Returns the report, or a pending status (HTTP 202). */
   submitPaidCheck(service: 'kushbitx-preflight', input: PreflightInput, auth: { paymentSignature: string; reportId: string; recoveryKey: string }): Promise<PreflightReport | Record<string, unknown>>;
+  submitPaidCheck(service: 'signature-check', input: SignatureCheckInput, auth: { paymentSignature: string; reportId: string; recoveryKey: string }): Promise<SignatureCheckReport | Record<string, unknown>>;
   submitPaidCheck(service: PaidService, input: object, auth: { paymentSignature: string; reportId: string; recoveryKey: string }): Promise<Record<string, unknown>>;
   restoreReport(args: { id: string; key: string; txHash?: string }): Promise<Record<string, unknown>>;
 }

package/kushbitx.mjs

@@ -6,7 +6,9 @@ const PAID_SERVICES = Object.freeze({
   'payment-proof': '/api/verify-payment',
   'verify-payment': '/api/verify-payment',
   // KushBitx Preflight (0.005 USDC): one verdict before money moves. 'preflight' stays Transaction Preflight.
-  'kushbitx-preflight': '/api/preflight'
+  'kushbitx-preflight': '/api/preflight',
+  // Signature Check (0.003 USDC): ALLOW, REVIEW or BLOCK for an EIP-712 signature request, bound to its digest.
+  'signature-check': '/api/signature-check'
 });
 
 function required(value, name) {
@@ -164,3 +166,102 @@ export async function canSign(report, transaction, now = Date.now()) {
     return false;
   }
 }
+
+// Signature Check: the EIP-712 digest the service returns in typedDataDigest, computed locally with no network and
+// no dependency: keccak256(0x19 0x01 ‖ domainSeparator ‖ hashStruct(primaryType, message)).
+const MASK64 = (1n << 64n) - 1n;
+const KECCAK_RC = [0x1n, 0x8082n, 0x800000000000808an, 0x8000000080008000n, 0x808bn, 0x80000001n, 0x8000000080008081n, 0x8000000000008009n, 0x8an, 0x88n, 0x80008009n, 0x8000000an, 0x8000808bn, 0x800000000000008bn, 0x8000000000008089n, 0x8000000000008003n, 0x8000000000008002n, 0x8000000000000080n, 0x800an, 0x800000008000000an, 0x8000000080008081n, 0x8000000000008080n, 0x80000001n, 0x8000000080008008n];
+const KECCAK_ROT = [0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39, 41, 45, 15, 21, 8, 18, 2, 61, 56, 14];
+const rotl64 = (v, n) => (n === 0 ? v : ((v << BigInt(n)) | (v >> BigInt(64 - n))) & MASK64);
+function keccakF(st) {
+  for (let round = 0; round < 24; round++) {
+    const c = [0, 1, 2, 3, 4].map(x => st[x] ^ st[x + 5] ^ st[x + 10] ^ st[x + 15] ^ st[x + 20]);
+    for (let x = 0; x < 5; x++) { const d = c[(x + 4) % 5] ^ rotl64(c[(x + 1) % 5], 1); for (let y = 0; y < 25; y += 5) st[y + x] ^= d; }
+    const b = new Array(25);
+    for (let x = 0; x < 5; x++) for (let y = 0; y < 5; y++) b[y + 5 * ((2 * x + 3 * y) % 5)] = rotl64(st[x + 5 * y], KECCAK_ROT[x + 5 * y]);
+    for (let x = 0; x < 5; x++) for (let y = 0; y < 5; y++) st[x + 5 * y] = b[x + 5 * y] ^ (~b[(x + 1) % 5 + 5 * y] & MASK64 & b[(x + 2) % 5 + 5 * y]);
+    st[0] ^= KECCAK_RC[round];
+  }
+}
+function keccak256(bytes) {
+  const rate = 136, st = new Array(25).fill(0n);
+  const padded = new Uint8Array(Math.floor(bytes.length / rate) * rate + rate);
+  padded.set(bytes); padded[bytes.length] ^= 0x01; padded[padded.length - 1] ^= 0x80;
+  for (let off = 0; off < padded.length; off += rate) {
+    for (let i = 0; i < rate / 8; i++) { let lane = 0n; for (let j = 7; j >= 0; j--) lane = (lane << 8n) | BigInt(padded[off + i * 8 + j]); st[i] ^= lane; }
+    keccakF(st);
+  }
+  const out = new Uint8Array(32);
+  for (let i = 0; i < 4; i++) for (let j = 0; j < 8; j++) out[i * 8 + j] = Number((st[i] >> BigInt(8 * j)) & 0xffn);
+  return out;
+}
+const hexBytes = hex => { const h = String(hex).replace(/^0x/i, ''); if (h.length % 2 || /[^0-9a-f]/i.test(h)) throw new Error('Invalid hex in typedData'); return Uint8Array.from(h.match(/../g) || [], b => parseInt(b, 16)); };
+const concatBytes = parts => { const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0)); let o = 0; for (const p of parts) { out.set(p, o); o += p.length; } return out; };
+const utf8 = text => new TextEncoder().encode(String(text));
+const word256 = n => hexBytes(BigInt.asUintN(256, BigInt(n)).toString(16).padStart(64, '0'));
+function typeDeps(primary, types, found = new Set()) {
+  const base = primary.replace(/\[.*$/, '');
+  if (found.has(base) || !types[base]) return found;
+  found.add(base);
+  for (const field of types[base]) typeDeps(field.type, types, found);
+  return found;
+}
+function encodeType(primary, types) {
+  return [primary, ...[...typeDeps(primary, types)].filter(t => t !== primary).sort()].map(t => {
+    if (!Array.isArray(types[t])) throw new Error('Unknown type in typedData: ' + t);
+    return t + '(' + types[t].map(f => f.type + ' ' + f.name).join(',') + ')';
+  }).join('');
+}
+function encodeValue(type, value, types) {
+  if (types[type]) return hashStruct(type, value, types);
+  const array = type.match(/^(.*)\[(\d*)\]$/);
+  if (array) {
+    if (!Array.isArray(value)) throw new Error('Expected an array for ' + type);
+    if (array[2] !== '' && value.length !== Number(array[2])) throw new Error('Wrong array length for ' + type);
+    return keccak256(concatBytes(value.map(v => encodeValue(array[1], v, types))));
+  }
+  if (type === 'string') return keccak256(utf8(value));
+  if (type === 'bytes') return keccak256(hexBytes(value));
+  if (type === 'bool') return word256(value === true || value === 'true' ? 1 : 0);
+  if (type === 'address') { if (!/^0x[0-9a-fA-F]{40}$/.test(String(value))) throw new Error('Invalid address in typedData'); return word256(BigInt(value)); }
+  const bytesN = type.match(/^bytes(\d+)$/);
+  if (bytesN) { const b = hexBytes(value); if (b.length !== Number(bytesN[1])) throw new Error('Wrong length for ' + type); const out = new Uint8Array(32); out.set(b); return out; }
+  const int = type.match(/^(u?)int(\d*)$/);
+  if (int) { const n = BigInt(value); if (int[1] === 'u' && (n < 0n || n >= 1n << BigInt(Number(int[2] || 256)))) throw new Error('Value out of range for ' + type); return word256(n); }
+  throw new Error('Unsupported type in typedData: ' + type);
+}
+function hashStruct(primary, data, types) {
+  if (!data || typeof data !== 'object') throw new Error('Missing struct value for ' + primary);
+  return keccak256(concatBytes([keccak256(utf8(encodeType(primary, types))), ...types[primary].map(f => encodeValue(f.type, data[f.name], types))]));
+}
+const DOMAIN_FIELDS = [['name', 'string'], ['version', 'string'], ['chainId', 'uint256'], ['verifyingContract', 'address'], ['salt', 'bytes32']];
+/** EIP-712 digest of typed data ({domain, types, primaryType, message}), as 0x-hex. Same value as typedDataDigest in a Signature Check report. */
+export function typedDataDigest(typedData) {
+  const { domain, types, primaryType, message } = typedData || {};
+  if (!domain || !types || !primaryType || !message) throw new Error('typedData needs domain, types, primaryType and message');
+  const own = Object.fromEntries(Object.entries(types).filter(([k]) => k !== 'EIP712Domain'));
+  if (!own[primaryType]) throw new Error('primaryType is not defined in types');
+  const domainTypes = { EIP712Domain: DOMAIN_FIELDS.filter(([n]) => domain[n] !== undefined && domain[n] !== null).map(([name, type]) => ({ name, type })) };
+  const digest = keccak256(concatBytes([new Uint8Array([0x19, 0x01]), hashStruct('EIP712Domain', domain, domainTypes), hashStruct(primaryType, message, own)]));
+  return '0x' + Array.from(digest, b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * True only for an ALLOW Signature Check report on this exact typed data, for this signer, on Base, before expiresAt.
+ * request: { chainId: 8453 (stated), signer, typedData }. typedData.domain.chainId must also be 8453: a signature
+ * without a chain in its domain could be replayed elsewhere, so it is never accepted. Anything else: do not sign.
+ */
+export async function canSignTypedData(report, request, now = Date.now()) {
+  if (!report || typeof report !== 'object' || report.verdict !== 'ALLOW' || typeof report.typedDataDigest !== 'string') return false;
+  if (!request || typeof request !== 'object' || request.chainId === undefined || request.chainId === null || chainIdOf(request) !== BASE_CHAIN_ID) return false;
+  if (report.chainId !== undefined && Number(report.chainId) !== BASE_CHAIN_ID) return false;
+  const domainChain = request.typedData?.domain?.chainId;
+  if (domainChain === undefined || domainChain === null || chainIdOf({ chainId: domainChain }) !== BASE_CHAIN_ID) return false;
+  if (typeof request.signer !== 'string' || typeof report.signer !== 'string' || request.signer.toLowerCase() !== report.signer.toLowerCase()) return false;
+  if (!report.expiresAt || !(Date.parse(report.expiresAt) > now)) return false;
+  try {
+    return report.typedDataDigest.toLowerCase() === typedDataDigest(request.typedData);
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kushbitx/sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Zero-dependency ESM client for KushBitx AgentProof services on Base",
   "type": "module",
   "exports": {
@@ -26,6 +26,7 @@
     "payment-security",
     "spendguard",
     "preflight",
+    "eip712",
     "typescript"
   ],
   "homepage": "https://github.com/BHamim/kushbitx-sdk#readme",