@huma-protocol/sdk

Verify Ed25519-signed HUMA score reports offline. Zero-dep (except @noble/ed25519).

The HUMA scanner — and the future HTTP API — both emit signed score reports. This SDK lets any downstream consumer verify those reports without trusting the source.

Install

npm install @huma-protocol/sdk
# or
pnpm add @huma-protocol/sdk

Verify a report

import { verifyReport } from '@huma-protocol/sdk';
import type { SignedReport } from '@huma-protocol/sdk';

const signed: SignedReport = JSON.parse(reportJson);
const HUMA_PUBLIC_KEY_B64 = process.env.HUMA_PUBLIC_KEY_B64!;

const ok = await verifyReport(signed, HUMA_PUBLIC_KEY_B64);
if (!ok) throw new Error('signature invalid — report was tampered with');

Optionally bind to a specific key id (defends against rogue signer):

await verifyReport(signed, key, { expectedPublicKeyId: 'huma_pk_prod_2026q2' });

Why

Every score response HUMA emits is signed. Verification is what lets a token foundation, a quest platform, or a DAO take HUMA's number and prove to its own users that the number wasn't edited downstream.

See docs/MOAT.md Layer 0 in the parent repo.

Public surface

verifyReport(signed, publicKeyB64, opts?) // boolean
canonicalize(value) // string — for cross-language verifier implementations
class VerifyError extends Error
interface SignedReport, ScanReport, ScoredWallet, FeatureScores, ...

Not included

This package only verifies. To sign reports, run the HUMA scanner CLI (huma scan) — signing keys live with the operator.

For the API client (/v1/score/{handle} calls) that ships in a later phase, @huma-protocol/sdk will gain a client export. Today it's verify-only because verify is what the wedge needs first.

License

Apache-2.0. Deliberately permissive, and deliberately different from the scanner (@huma-protocol/scanner, BUSL-1.1): this package contains no scoring logic — only signature verification — and it is meant to be embedded wherever a HUMA report needs checking, including in code that competes with us. A verifier nobody is allowed to depend on verifies nothing.