age-verification

mGrađani age verification client for web shops. Uses OAuth 2.1 + OIDC with PKCE.

Browser-only package. Uses localStorage for OIDC transaction state.

Install

npm install @mpudt/age-verification

Usage

1. Create the client

import { AgeVerificationClient } from 'age-verification';

const client = new AgeVerificationClient({
  issuer: 'https://mgradjani-test.gov.hr/idp',
  clientId: 'your-client-id',
  redirectUri: 'https://your-shop.com/callback',
});

2. Redirect user to authorization

On your verify button click, generate the URL and redirect:

const url = await client.createAuthorizationUrl();
window.location.href = url;

The user will be redirected to mGrađani, scan a QR code with their mobile app, and then redirected back to your redirectUri with a code in the query string.

3. Handle callback and inspect tokens

On your callback page, read code, exchange it for tokens, then validate id_token and inspect claims:

const params = new URLSearchParams(window.location.search);
const code = params.get('code');
const tokens = await client.exchangeCode(code);
const result = await client.verifyTokens(tokens);

if (result.verified) {
  // user is of legal drinking age
} else {
  // user is not verified
}

console.log(result.claims);

exchangeCode reads and validates returned state from callback URL, then exchanges code for tokens.

verifyTokens validates id_token signature and claims (iss, aud, exp, nonce) against issuer JWKS and returns:

{
  verified: true,
  claims: {
    sub: '...',
    aud: '...',
    'age.alcohol': true,
    iss: '...',
    exp: 1783428386,
    iat: 1783428086,
    nonce: '...',
    jti: '...'
  }
}

completeAgeVerification(code) is convenience wrapper around both steps and returns same { verified, claims } object.

Security behavior

• OIDC transaction data is stored per state, so multiple tabs or repeated starts do not overwrite each other.
• localStorage is required for OIDC transaction state.
• issuer must be valid https URL; redirectUri must be https in production.
• For local development, http://localhost, http://127.0.0.1, and http://[::1] are accepted.
• redirectUri is sent exactly as configured (no automatic slash/protocol rewriting), so keep it identical to IdP registered callback.
• Discovery document is validated against configured issuer.
• Callback processing verifies that current page matches configured redirectUri.
• Callback error and error_description are surfaced explicitly.
• JWKS cache is refreshed once automatically if matching key is not found.
• Token validation checks sub, iss, aud, exp, optional nbf, iat, and nonce.

Config

| Option | Required | Default | Description | |---------------|----------|---------------|------------------------------------| | issuer | yes | — | mGrađani IdP base URL | | clientId | yes | — | Your web shop client ID | | redirectUri | yes | — | Callback URL after authorization | | scope | no | age.alcohol | OIDC scope to request | | clockSkewSeconds | no | 60 | Allowed clock skew for token times | | transactionTtlSeconds | no | 900 | Max lifetime for stored OIDC transaction |