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
• client.verifications(id).document() — GET /v1/verifications/{id}/document
• client.verifications(id).estimation() — GET /v1/verifications/{id}/estimation
• client.verifications(id).blockFace({ reason }) — POST /v1/verifications/{id}/blocked-face

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.

Every method is fully typed (see src/types.ts / the package's type definitions), and the exact request/response shape of each endpoint is documented in AGENTS.md and the bundled openapi.json.

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