@zerodev/data-api-stamp

Shared canonical-payload and verification contract for requests signed by ZeroDev Wallet SDK clients and verified by ZeroDev Data API servers.

The root entry is intentionally small and runtime-neutral. It builds the canonical payload around the encoded request target supplied by each side; it does not create keys, sign requests, or authorize wallets. The Node-only verifier is isolated behind the ./verifier subpath so frontend consumers do not load its Noble or Zod module graph.

Install

pnpm add @zerodev/data-api-stamp

Servers that import @zerodev/data-api-stamp/verifier also need zod, declared as an optional peer dependency so browser consumers of the root entry do not have to install it.

Usage

import { buildDataApiPayload } from '@zerodev/data-api-stamp';

const path = '/v1/me/transaction-history';
const query = new URLSearchParams({}).toString();
const requestTarget = query === '' ? path : `${path}?${query}`;

const payload = buildDataApiPayload({
  method: 'GET',
  requestTarget,
  walletAddress: '0x1111111111111111111111111111111111111111',
  environment: 'mainnet',
  ts: Date.now(),
});

const url = new URL(requestTarget, 'https://data.example');

The client builds and validates requestTarget before constructing the URL that it passes to fetch. It includes the pathname and query string exactly as sent, including percent encoding and query order. An omitted X-Env header is represented as environment: 'mainnet'.

Server verification

import { verifyDataApiStamp } from '@zerodev/data-api-stamp/verifier';

const stampHeader = request.headers['x-stamp'];
const timestampHeader = request.headers['x-timestamp'];

if (
  typeof stampHeader !== 'string' ||
  typeof timestampHeader !== 'string' ||
  !/^(?:0|[1-9][0-9]*)$/.test(timestampHeader)
) {
  return reply.code(401).send({ error: 'unauthorized' });
}

const ts = Number(timestampHeader);
if (!Number.isSafeInteger(ts)) {
  return reply.code(401).send({ error: 'unauthorized' });
}

// Apply the server's timestamp freshness policy before verification.
const requestTarget = request.raw.url;
if (requestTarget === undefined) {
  return reply.code(401).send({ error: 'unauthorized' });
}

const result = verifyDataApiStamp(stampHeader, {
  method: 'GET',
  requestTarget,
  walletAddress: '0x1111111111111111111111111111111111111111',
  environment: 'mainnet',
  ts,
});

./verifier is Node-only. Validate request semantics and timestamp freshness before verification. The server must use the raw request target rather than rebuilding it from decoded path and query values. buildDataApiPayload throws a TypeError when its input is invalid. verifyDataApiStamp reports invalid payloads, malformed envelopes, and invalid signatures in its StampVerificationResult.

Failure reasons are stable diagnostic codes for internal logs and metrics. They must not be exposed as differentiated authentication responses; clients should continue to receive a generic unauthorized response.

Do not use the raw X-Stamp header for replay detection. The same request can have more than one valid header value. Use requestFingerprint from a successful verification result instead.

Development

pnpm --filter @zerodev/data-api-stamp build
pnpm --filter @zerodev/data-api-stamp typecheck
pnpm --filter @zerodev/data-api-stamp test

pnpm pack runs the build automatically and the tarball contains the ESM, CommonJS, and TypeScript declaration outputs.

Workspace consumers use the same compiled ESM, CommonJS, and declaration files that a published consumer will use. Run the package build after installing dependencies, switching to a branch that changes this package, or cleaning dist:

pnpm --filter @zerodev/data-api-stamp build

No watcher is configured yet, so rebuild manually after changing the package's source or interface.