ProofAge Node.js Client — Age Verification for Node.js

Platform: https://proofage.xyz | npm: https://www.npmjs.com/package/@proofage/node

A Node.js client for the ProofAge API with HMAC request signing and webhook signature verification.

About ProofAge

ProofAge is an online age verification platform enabling websites to confirm users meet minimum age requirements through a hosted, privacy-focused KYC process — without server-side document handling. It supports alcohol/tobacco/cannabis commerce, adult content platforms, gambling sites, and age-restricted subscriptions.

This package provides a first-class Node.js integration: auto-configuration from environment variables, HMAC-signed API calls, a drop-in webhook handler for Next.js App Router, Hono, Cloudflare Workers, and any framework with a standard Request, plus a CLI verification command.

Requirements

• Node.js 18+

Installation

npm install @proofage/node

Quick Start

Set your environment variables:

PROOFAGE_API_KEY=pk_live_...
PROOFAGE_SECRET_KEY=sk_live_...
# Optional:
# PROOFAGE_BASE_URL=https://api.proofage.xyz
# PROOFAGE_WEBHOOK_TOLERANCE=300

Create a client — keys resolve from env automatically:

import { ProofAgeClient } from '@proofage/node';

const client = new ProofAgeClient();

const workspace = await client.workspace().get();

const verification = await client.verifications().create({
  callback_url: 'https://your-app.com/verify/complete',  // optional
  metadata: { order_id: '123' },
});

Or pass config explicitly:

const client = new ProofAgeClient({
  apiKey: 'pk_live_...',
  secretKey: 'sk_live_...',
});

Configuration

All options fall back to environment variables, then to defaults.

Option	Env var	Default	Description
apiKey	PROOFAGE_API_KEY	—	Workspace API key
secretKey	PROOFAGE_SECRET_KEY	—	Secret key for HMAC signing
baseUrl	PROOFAGE_BASE_URL	https://api.proofage.xyz	API base URL
version	PROOFAGE_VERSION	v1	API version path segment
timeout	PROOFAGE_TIMEOUT	30000	Request timeout (ms)
retryAttempts	PROOFAGE_RETRY_ATTEMPTS	3	Retries for transient failures
retryDelay	PROOFAGE_RETRY_DELAY	1000	Base delay between retries (ms)

API Methods

• client.workspace().get() — GET /v1/workspace
• client.workspace().getConsent() — GET /v1/consent
• client.verifications().create(body) — POST /v1/verifications
• client.verifications(id).get() — GET /v1/verifications/{id}
• client.verifications(id).acceptConsent(body) — POST /v1/verifications/{id}/consent
• client.verifications(id).uploadMedia({ type, file, filename }) — POST /v1/verifications/{id}/media (multipart)
• client.verifications(id).submit() — POST /v1/verifications/{id}/submit

Request bodies use snake_case keys to match the ProofAge API. callback_url is optional — if omitted, the verification result is available via polling or webhook.

Webhooks

ProofAge sends POST requests with HMAC headers:

Header	Description
X-Auth-Client	Your workspace API key
X-HMAC-Signature	HMAC-SHA256 hex digest of {timestamp}.{rawJsonBody}
X-Timestamp	Unix timestamp (seconds)

Drop-in handler (recommended)

One-liner for Next.js App Router, Hono, Cloudflare Workers, or any framework with a standard Request:

import { webhookHandler } from '@proofage/node';

// Keys and tolerance resolve from env automatically
export const POST = webhookHandler(async (payload) => {
  console.log(payload.verification_id, payload.status);
  // your business logic: update DB, send email, etc.
});

Returns 200 on success, 401 on invalid signature, 400 on invalid JSON, 500 if your callback throws.

Manual verification

For full control or non-standard frameworks:

import { verifyWebhookSignature } from '@proofage/node';

const rawBody = await request.text();

verifyWebhookSignature({
  rawBody,
  signature: request.headers.get('x-hmac-signature'),
  timestamp: request.headers.get('x-timestamp'),
  authClient: request.headers.get('x-auth-client'),
  // apiKey and secretKey resolve from env if omitted
});

const payload = JSON.parse(rawBody);

Mid-level helper

handleWebhook() verifies + parses in one call, returns a result object:

import { handleWebhook } from '@proofage/node';

const { verified, payload, error } = await handleWebhook(request);
if (!verified) {
  return new Response(null, { status: 401 });
}
// payload is typed as WebhookPayload

CLI

Verify your setup from the terminal:

npx @proofage/node verify-setup

Reads PROOFAGE_API_KEY, PROOFAGE_SECRET_KEY, and PROOFAGE_BASE_URL from .env.local / .env automatically. Auto-skips TLS verification for local dev domains (.test, .local, localhost).

Errors

• ProofAgeError — generic API error (includes statusCode and parsed error object when present)
• AuthenticationError — HTTP 401
• ValidationError — HTTP 422 (getErrors() returns field errors)
• WebhookVerificationError — invalid or missing webhook signature / headers

Additional Resources

• Platform: https://proofage.xyz
• Live Demo: https://demo.proofage.xyz
• Laravel Package: proofage/laravel-client on Packagist

Integrations for other platforms

Platform	Repository	Use-case
Node.js	this repo	Node.js age verification client — HMAC-signed API calls, webhook verification for Express, Hono, Next.js and other Node.js frameworks
WordPress	ProofAge/wordpress-plugin	Age gate plugin for WordPress — WooCommerce age verification, age-restricted pages, adult content gating
Laravel	ProofAge/laravel-client	Laravel age verification client — HMAC-signed API calls, webhook handling, middleware for age-restricted routes
Next.js	ProofAge/demo	Full-stack age verification demo with JS SDK, server routes, and webhook receiver

License

MIT