`, keeping `data-callback` and the other
callbacks.
- Server: read `pg-trust-check-response` instead of `h-captcha-response`, and
replace `https://api.hcaptcha.com/siteverify` (or `hcaptcha.com/siteverify`)
with `https://api.polyguard.ai/v2/siteverify`. Drop `secret` and `sitekey`,
and compare `hostname`.
- JavaScript: replace `hcaptcha.render / reset / getResponse / execute` with
`Polyguard.TrustCheck.render / reset / getResponse / execute`.
## Testing
- On `localhost` the real widget works, up to 100 checks a day per IP.
- In unit and end-to-end tests, stub `trust-check.js` (or the siteverify call)
rather than calling Polyguard. The repository's Playwright test serves a
fake widget for any `trust-check.js` request:
https://github.com/polyguard-ai/trust-check-widget/blob/main/tests/smoke.spec.ts
## After integrating
Tell the site owner:
- Visitors need a phone.
- The account for the hostname is free and limited to 1,000 checks per
week. To manage it, raise the limit or require a secret, claim the hostname
by publishing `/.well-known/polyguard.json`: https://postcaptcha.com/#claim
## Example source
### Plain HTML: `examples/html/index.html`
```html
Sign up
```
### React hook: `examples/react/usePolyguardTrustCheck.ts`
```ts
'use client';
import { useCallback, useEffect, useRef, useState } from 'react';
const SCRIPT_URL = 'https://cdn.polyguard.ai/sdk/latest/trust-check.js';
type RenderOptions = {
callback?: (response: string) => void;
'expired-callback'?: () => void;
'error-callback'?: (code: string) => void;
action?: string;
cdata?: string;
path?: string;
theme?: 'auto' | 'light' | 'dark';
size?: 'normal' | 'compact' | 'flexible';
locale?: string;
scored?: boolean;
};
type TrustCheckApi = {
render: (container: HTMLElement | string, options?: RenderOptions) => string;
reset: (id?: string) => void;
remove: (id?: string) => void;
getResponse: (id?: string) => string;
};
function globalTrustCheck(): TrustCheckApi | undefined {
return (window as unknown as { Polyguard?: { TrustCheck?: TrustCheckApi } }).Polyguard
?.TrustCheck;
}
let loading: Promise
| null = null;
/** Loads trust-check.js once per page in explicit-render mode. */
function loadTrustCheck(src: string): Promise {
const existing = globalTrustCheck();
if (existing) return Promise.resolve(existing);
if (loading) return loading;
loading = new Promise((resolve, reject) => {
const onload = '__pgTrustCheckHookOnload';
const w = window as unknown as Record;
w[onload] = () => {
delete w[onload];
const api = globalTrustCheck();
if (api) resolve(api);
else reject(new Error('trust-check.js loaded without Polyguard.TrustCheck'));
};
const script = document.createElement('script');
script.src = `${src}${src.includes('?') ? '&' : '?'}render=explicit&onload=${onload}`;
script.async = true;
script.onerror = () => {
loading = null;
reject(new Error(`Failed to load ${src}`));
};
document.head.appendChild(script);
});
return loading;
}
export type UsePolyguardTrustCheckOptions = Omit<
RenderOptions,
'callback' | 'expired-callback' | 'error-callback'
> & { scriptUrl?: string };
/**
* Renders the postcaptcha widget into `ref` and tracks its response.
* `response` is '' until the visitor completes the check, and again after it
* expires (300 seconds) or `reset()` is called.
*/
export function usePolyguardTrustCheck(options: UsePolyguardTrustCheckOptions = {}) {
const { scriptUrl = SCRIPT_URL, action, cdata, path, theme, size, locale, scored } = options;
const ref = useRef(null);
const widgetId = useRef(null);
const [response, setResponse] = useState('');
const [error, setError] = useState(null);
useEffect(() => {
let cancelled = false;
loadTrustCheck(scriptUrl)
.then((api) => {
if (cancelled || !ref.current) return;
widgetId.current = api.render(ref.current, {
action,
cdata,
path,
theme,
size,
locale,
scored,
callback: (value) => {
setResponse(value);
setError(null);
},
'expired-callback': () => setResponse(''),
'error-callback': (code) => {
setResponse('');
setError(code);
},
});
})
.catch(() => {
if (!cancelled) setError('script_load_failed');
});
return () => {
cancelled = true;
if (widgetId.current) globalTrustCheck()?.remove(widgetId.current);
widgetId.current = null;
};
}, [scriptUrl, action, cdata, path, theme, size, locale, scored]);
const reset = useCallback(() => {
if (widgetId.current) globalTrustCheck()?.reset(widgetId.current);
setResponse('');
setError(null);
}, []);
return { ref, response, error, reset };
}
```
### React form: `examples/react/TrustCheckForm.tsx`
```tsx
'use client';
import { useState, type FormEvent } from 'react';
import { usePolyguardTrustCheck } from './usePolyguardTrustCheck';
export function SignupForm() {
const { ref, response, error, reset } = usePolyguardTrustCheck({ action: 'signup' });
const [status, setStatus] = useState<'idle' | 'sending' | 'done' | 'failed'>('idle');
async function onSubmit(event: FormEvent) {
event.preventDefault();
setStatus('sending');
// The widget's hidden pg-trust-check-response input is inside the form.
const res = await fetch('/api/signup', {
method: 'POST',
body: new FormData(event.currentTarget),
});
setStatus(res.ok ? 'done' : 'failed');
// Polyguard accepts a response once; a second submission needs a new check.
reset();
}
return (
);
}
```
### Next.js App Router route handler: `examples/nextjs/route.ts`
```ts
// app/api/signup/route.ts
import { NextRequest, NextResponse } from 'next/server';
const SITEVERIFY_URL = 'https://api.polyguard.ai/v2/siteverify';
// The hostname your form is served from, exactly as visitors load it.
const EXPECTED_HOSTNAME = process.env.SITE_HOSTNAME ?? 'www.example.com';
type Siteverify = {
success: boolean;
hostname?: string;
action?: string;
score?: string;
'error-codes'?: string[];
};
export async function POST(request: NextRequest) {
const form = await request.formData();
const token = form.get('pg-trust-check-response');
if (typeof token !== 'string' || !token) {
return NextResponse.json({ error: 'missing-input-response' }, { status: 400 });
}
const body = new URLSearchParams({ response: token });
const ip = request.headers.get('x-forwarded-for')?.split(',')[0].trim();
if (ip) body.set('remoteip', ip);
// Optional until your hostname is claimed: the App API key from the console.
if (process.env.POLYGUARD_SITEVERIFY_SECRET) {
body.set('secret', process.env.POLYGUARD_SITEVERIFY_SECRET);
}
const res = await fetch(SITEVERIFY_URL, {
method: 'POST',
body,
cache: 'no-store',
signal: AbortSignal.timeout(5000),
});
const result = (await res.json()) as Siteverify;
// Without a secret, the hostname comparison is what ties the result to your site.
if (!result.success || result.hostname !== EXPECTED_HOSTNAME || result.action !== 'signup') {
return NextResponse.json(
{ error: 'trust_check_failed', codes: result['error-codes'] ?? [] },
{ status: 403 },
);
}
// The check passed: create the account with form.get('email').
return NextResponse.json({ ok: true });
}
```
### Express middleware: `examples/express/middleware.js`
```js
// Express middleware that requires a completed postcaptcha check.
// Node 18+ (global fetch). Mount express.urlencoded() before it.
const SITEVERIFY_URL = 'https://api.polyguard.ai/v2/siteverify';
function requireTrustCheck({ expectedHostname, action, secret } = {}) {
if (!expectedHostname) throw new Error('requireTrustCheck: expectedHostname is required');
return async function trustCheck(req, res, next) {
const token = req.body && req.body['pg-trust-check-response'];
if (typeof token !== 'string' || !token) {
return res.status(400).json({ error: 'missing-input-response' });
}
const body = new URLSearchParams({ response: token });
// Behind a proxy, set app.set('trust proxy', ...) so req.ip is the visitor's address.
if (req.ip) body.set('remoteip', req.ip);
if (secret) body.set('secret', secret);
let result;
try {
const response = await fetch(SITEVERIFY_URL, {
method: 'POST',
body,
signal: AbortSignal.timeout(5000),
});
result = await response.json();
} catch (err) {
return next(err);
}
const ok =
result.success === true &&
result.hostname === expectedHostname &&
(action === undefined || result.action === action);
if (!ok) {
return res
.status(403)
.json({ error: 'trust_check_failed', codes: result['error-codes'] || [] });
}
req.trustCheck = result;
return next();
};
}
module.exports = { requireTrustCheck };
// Usage:
//
// const express = require('express');
// const { requireTrustCheck } = require('./middleware');
//
// const app = express();
// app.use(express.urlencoded({ extended: false }));
// app.post(
// '/signup',
// requireTrustCheck({
// expectedHostname: 'www.example.com',
// action: 'signup',
// secret: process.env.POLYGUARD_SITEVERIFY_SECRET,
// }),
// (req, res) => res.send('Account created'),
// );
```
### Flask decorator: `examples/python-flask/verify.py`
```python
"""Flask decorator that requires a completed postcaptcha check.
Standard library only for the HTTP call. Behind a proxy, wrap the app with
werkzeug.middleware.proxy_fix.ProxyFix so request.remote_addr is the visitor's.
"""
import json
import os
import urllib.parse
import urllib.request
from functools import wraps
from flask import Flask, abort, jsonify, request
SITEVERIFY_URL = "https://api.polyguard.ai/v2/siteverify"
# The hostname your form is served from, exactly as visitors load it.
EXPECTED_HOSTNAME = os.environ.get("SITE_HOSTNAME", "www.example.com")
def siteverify(token, remoteip=None, secret=None):
fields = {"response": token}
if remoteip:
fields["remoteip"] = remoteip
if secret:
fields["secret"] = secret
data = urllib.parse.urlencode(fields).encode()
req = urllib.request.Request(SITEVERIFY_URL, data=data, method="POST")
with urllib.request.urlopen(req, timeout=5) as resp:
return json.load(resp)
def require_trust_check(action=None):
def decorator(view):
@wraps(view)
def wrapper(*args, **kwargs):
token = request.form.get("pg-trust-check-response", "")
if not token:
abort(400, "missing-input-response")
result = siteverify(
token,
remoteip=request.remote_addr,
secret=os.environ.get("POLYGUARD_SITEVERIFY_SECRET"),
)
ok = (
result.get("success") is True
and result.get("hostname") == EXPECTED_HOSTNAME
and (action is None or result.get("action") == action)
)
if not ok:
return jsonify(error="trust_check_failed", codes=result.get("error-codes", [])), 403
return view(*args, **kwargs)
return wrapper
return decorator
app = Flask(__name__)
@app.post("/signup")
@require_trust_check(action="signup")
def signup():
return "Account created"
if __name__ == "__main__":
app.run(debug=True)
```
### PHP: `examples/php/verify.php`
```php
$token];
if ($remoteIp) {
$fields['remoteip'] = $remoteIp;
}
if ($secret) {
$fields['secret'] = $secret;
}
$ch = curl_init(POLYGUARD_SITEVERIFY_URL);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($fields),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
]);
$body = curl_exec($ch);
curl_close($ch);
$result = is_string($body) ? json_decode($body, true) : null;
return is_array($result) ? $result : ['success' => false, 'error-codes' => ['internal-error']];
}
// The hostname your form is served from, exactly as visitors load it.
$expectedHostname = getenv('SITE_HOSTNAME') ?: 'www.example.com';
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
$token = $_POST['pg-trust-check-response'] ?? '';
if ($token === '') {
http_response_code(400);
exit('missing-input-response');
}
$result = polyguard_siteverify(
$token,
$_SERVER['REMOTE_ADDR'] ?? null,
getenv('POLYGUARD_SITEVERIFY_SECRET') ?: null
);
if (($result['success'] ?? false) !== true || ($result['hostname'] ?? '') !== $expectedHostname) {
http_response_code(403);
exit('postcaptcha check failed: ' . implode(', ', $result['error-codes'] ?? []));
}
// The check passed: handle $_POST['email'] here.
echo 'Account created';
}
```
### WordPress notes: `examples/wordpress/README.md`
#### WordPress (notes)
There is no WordPress plugin yet. These notes show where the widget and the
server-side check go if you add them to a theme or a small site plugin.
##### Load the script
```php
add_action('wp_enqueue_scripts', function () {
wp_enqueue_script(
'polyguard-trust-check',
'https://cdn.polyguard.ai/sdk/latest/trust-check.js',
[],
null,
['strategy' => 'defer', 'in_footer' => true]
);
});
```
WordPress does not run `wp_enqueue_scripts` on the login page; use
`login_enqueue_scripts` there.
##### Place the widget
```php
add_action('comment_form_after_fields', function () {
echo '';
});
add_action('login_form', function () {
echo '';
});
```
The widget adds a hidden `pg-trust-check-response` input to the enclosing form
when the visitor completes the check.
##### Verify on the server
Use `wp_remote_post` so WordPress's HTTP settings apply:
```php
function polyguard_trust_check_passed(string $action): bool {
$token = sanitize_text_field(wp_unslash($_POST['pg-trust-check-response'] ?? ''));
if ($token === '') {
return false;
}
$response = wp_remote_post('https://api.polyguard.ai/v2/siteverify', [
'timeout' => 5,
'body' => [
'response' => $token,
'remoteip' => $_SERVER['REMOTE_ADDR'] ?? '',
],
]);
if (is_wp_error($response)) {
return false;
}
$result = json_decode(wp_remote_retrieve_body($response), true);
return is_array($result)
&& ($result['success'] ?? false) === true
&& ($result['hostname'] ?? '') === wp_parse_url(home_url(), PHP_URL_HOST)
&& ($result['action'] ?? '') === $action;
}
```
Hook it where WordPress accepts the form:
- Comments: `preprocess_comment`, calling `wp_die()` when the check fails.
- Login: the `authenticate` filter at priority 30, returning a `WP_Error`.
- Registration: `registration_errors`, adding an error.
Skip the check for requests that do not come from the form (XML-RPC, REST,
WP-CLI) or they will all fail.
##### Things to know
- Visitors need a phone. They do not need to install an app.
- `home_url()` must match the hostname visitors load. `www.example.com` and
`example.com` are different hostnames.
- Polyguard accepts each response once. Responses expire after 300 seconds.
## Optional
- [Polyguard SDK docs](https://support.polyguard.ai/sdk/): the full SDK, for identity, location and other proofs on a claimed account.
- [Examples README](https://github.com/polyguard-ai/trust-check-widget/blob/main/examples/README.md): what each example contains.
- [Claim instructions](https://postcaptcha.com/#claim): moving the free hostname account into a Polyguard account.