AgeGuard Documentation

AgeGuard is a zero-knowledge age verification system. It lets your site confirm that a user meets a configurable age threshold — without ever receiving any personal data.

What AgeGuard is

AgeGuard combines government-grade identity verification with zero-knowledge cryptography to produce a reusable, privacy-preserving age credential. Once a user enrolls, subsequent verifications take seconds and require only a biometric gesture (Face ID, Touch ID, or Windows Hello) — no documents, no uploads, no data leaves the device.

The system is built on three open standards:

• SD-JWT — selective-disclosure JSON Web Token for the identity credential
• Noir / UltraHonk — a ZK proving system for the age proof circuit
• WebAuthn / FIDO2 — biometric authentication to bind the credential to the user's device

The 4-step flow

How it works technically

Identity verification → SD-JWT credential

During enrollment, the user completes a liveness + document check via Veriff. The AgeGuard Issuer Worker reads the verified date-of-birth from the Veriff result, constructs a selective-disclosure JWT (SD-JWT) containing the dob claim, and signs it with a Schnorr key pair. The SD-JWT is returned to the browser and persisted in localStorage. The issuer does not retain any personal data after issuing the credential.

ZK proof generation

The age-proof Noir circuit takes as private inputs the credential's dob field and signature, and as public inputs the age_threshold, the current date, and a server-issued challenge nonce. The circuit proves:

1. The SD-JWT signature is valid (credential is authentic)
2. The date-of-birth encoded in the credential yields an age ≥ the threshold as of today
3. The proof is bound to the provided challenge (replay prevention)

Proof generation runs entirely in the browser using the Barretenberg WASM library. Private data — the raw date of birth — never leaves the device.

Proof verification on Cloudflare Workers

The Verifier Worker runs a native UltraHonk verifier (compiled to WASM). It checks the proof against the public inputs, verifies the challenge has not expired (5-minute TTL), and — if all checks pass — issues a short-lived HMAC-signed session JWT to the caller.

Enrollment flow

Users obtain their AgeGuard credential through a one-time enrollment at holder.ageguard.dev.

Steps

1. User visits holder.ageguard.dev and clicks Get your age credential.
2. The Veriff SDK launches a guided liveness check and document scan (passport, national ID, or driving licence).
3. Veriff returns a verified session result to the AgeGuard Issuer Worker.
4. The issuer extracts the date-of-birth, constructs the SD-JWT, signs it, and returns it to the browser.
5. The credential is stored in localStorage and bound to the device via WebAuthn.

After enrollment, the credential is reused for every subsequent verification — no re-verification with Veriff is required. If the user clears their browser storage or switches devices, they must re-enroll.

SDK Integration

The fastest way to integrate AgeGuard is the CDN script tag. An npm package is coming soon.

Script tag (HTML)

<script src="https://cdn.ageguard.dev/sdk/v1/ageguard.js"></script>
<script>
  const ag = AgeGuard.create({
    verifierUrl: 'https://verifier.ageguard.dev',
    ageThreshold: 18  // configurable: 13, 16, 18, 21, etc.
  });

  document.getElementById('verify-btn')
    .addEventListener('click', async () => {
      await ag.init();
      const result = await ag.verify();
      if (result.verified) {
        // User meets the age threshold — unlock content
        console.log('Session token:', result.token);
      }
    });
</script>

AgeGuard.create() options

Handling the result

The ag.verify() promise resolves with a result object:

// Success
{
  verified: true,
  age_threshold: 18,
  token: "eyJ...",           // HMAC-signed session JWT
  token_expires_at: "2026-04-26T12:05:00Z"
}

// Failure
{
  verified: false,
  reason: "proof_invalid"  // or "challenge_expired", "credential_invalid"
}

Pass the token to your backend and validate it with your shared secret. The token payload includes age_threshold and exp (expiry) claims.

Verifier API

The AgeGuard Verifier is a Cloudflare Worker deployed at https://verifier.ageguard.dev. All endpoints accept and return JSON. CORS is enabled for registered origins.

Base URL

https://verifier.ageguard.dev

GET /challenge

{
  "challenge":      "a3f2...8e1c",  // 64-character hex string
  "expires_at":     "2026-04-26T12:05:00Z",
  "ttl_seconds":    300
}

POST /verify

{
  "verified":         true,
  "age_threshold":    18,
  "token":            "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_expires_at": "2026-04-26T12:05:00Z"
}

{
  "verified": false,
  "reason":   "proof_invalid"
}

GET /.well-known/ageguard.json

{
  "name":            "AgeGuard Verifier",
  "version":         1,
  "verifier_id":     "https://verifier.ageguard.dev",
  "proof_systems":   ["ultrahonk"],
  "age_thresholds":  [13, 16, 18, 21],
  "docs":            "https://docs.ageguard.dev"
}

Self-Hosting

The AgeGuard Verifier Worker is open source under the MIT licence and can be self-hosted on your own Cloudflare account.

Prerequisites

• A Cloudflare account with Workers enabled
• Wrangler CLI v3+
• Node.js 18+

Deploying

git clone https://github.com/AgeGuard/ageguard
cd ageguard/packages/verifier
npm install
npx wrangler deploy --env production

Configure the following secrets in your Cloudflare dashboard or via wrangler secret put: