The token format and the checks are in the offline verification reference, which includes a PHP version. This page builds on it for WordPress. The design question is where the verification runs. If it runs on every page view, a host without the native sodium extension pays for pure-PHP elliptic-curve math each time. The answer is to verify when the license is refreshed, store what the result means as one timestamp, and compare that on page views. The call that fetches the token and the cron job are in license key validation in a WordPress plugin. The check logic was run in Swift, Rust, Python, C++ and Node against the same test tokens.
The verifier
/** Returns the decoded bytes, or false when the input is not valid base64url. */
function clavem_b64url_decode( string $value ) {
$b64 = strtr( $value, '-_', '+/' );
return base64_decode( $b64 . str_repeat( '=', ( 4 - strlen( $b64 ) % 4 ) % 4 ), true ); // true: strict
}
/**
* Returns array( reason, claims ). reason is 'ok', 'malformed', 'bad-signature', 'wrong-product',
* 'not-valid', 'expired', 'clock-set-back' or 'stale'. claims is null unless the signature was good.
*/
function clavem_check_token( string $token, string $public_key, int $product_id, int $highest_iat = 0, ?int $now = null ): array {
$now = $now ?? time(); // not current_time( 'timestamp' ): that one is shifted by the site's timezone
$parts = explode( '.', $token );
if ( 3 !== count( $parts ) || 'sgt1' !== $parts[0] ) {
return array( 'malformed', null );
}
$key = clavem_b64url_decode( trim( $public_key ) );
$sig = clavem_b64url_decode( $parts[2] );
$raw = clavem_b64url_decode( $parts[1] );
if ( false === $key || false === $sig || false === $raw
|| SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES !== strlen( $key ) || SODIUM_CRYPTO_SIGN_BYTES !== strlen( $sig ) ) {
return array( 'malformed', null ); // sodium throws on wrong lengths, so check them first
}
try {
$good = sodium_crypto_sign_verify_detached( $sig, $parts[0] . '.' . $parts[1], $key ); // the text as received
} catch ( SodiumException $e ) {
return array( 'malformed', null );
}
if ( ! $good ) {
return array( 'bad-signature', null );
}
$c = json_decode( $raw, true );
if ( ! is_array( $c ) || 1 !== ( $c['v'] ?? null ) ) {
return array( 'malformed', null );
}
if ( ( $c['pid'] ?? null ) !== $product_id ) {
return array( 'wrong-product', $c );
}
if ( true !== ( $c['valid'] ?? false ) ) {
return array( 'not-valid', $c );
}
if ( isset( $c['exp'] ) && $c['exp'] <= $now ) {
return array( 'expired', $c );
}
if ( $now < $highest_iat ) {
return array( 'clock-set-back', $c );
}
if ( ( $c['refresh_by'] ?? 0 ) <= $now ) {
return array( 'stale', $c );
}
return array( 'ok', $c );
}
Only 'ok' should turn the paid features on, and 'stale' means validate online. Comparisons use !== and true !== on purpose. PHP’s loose == treats the string "false" and the number 0 in ways you do not want in a license check.
Verify rarely, compare often
The refresh job from the validation page calls the verifier, and on 'ok' stores two numbers: the token’s iat, for the clock guard, and the time until which the token is good. The first is the highest iat seen. The second is the earlier of exp, when present, and refresh_by:
function inkwell_apply_token( array $saved ): string {
$highest = (int) get_option( 'inkwell_highest_iat', 0 );
list( $reason, $c ) = clavem_check_token( $saved['token'], INKWELL_PUBLIC_KEY, INKWELL_PRODUCT_ID, $highest );
if ( 'ok' !== $reason ) {
update_option( 'inkwell_valid_until', 0, false );
return 'stale' === $reason ? 'needs-network' : 'invalid';
}
update_option( 'inkwell_highest_iat', max( $highest, (int) $c['iat'] ), false );
update_option( 'inkwell_valid_until', min( $c['exp'] ?? PHP_INT_MAX, $c['refresh_by'] ), false );
return 'licensed';
}
/** Cheap enough for every request: one option read and a comparison. No crypto. */
function inkwell_is_licensed(): bool {
return time() < (int) get_option( 'inkwell_valid_until', 0 );
}
A token that expires between two cron runs then stops working on time, not up to a day late. The online path sets the same value from the fresh token the API returns. On a host with the native sodium extension, verification takes a negligible time. On a host that falls back to sodium_compat, the pure-PHP version is slower, so measure it on a cheap shared host. Because it runs from cron and a settings save only, either case is fine.
Test results
The same logic, on test tokens signed with a throwaway key in the documented sgt1 format, in other languages. The PHP code should return the same:
| Token | Reason |
|---|---|
| Fresh | ok |
exp in 30 days |
ok |
exp a minute ago |
expired |
refresh_by 6 days ago |
stale |
Issued for an expired license (valid: false) |
not-valid |
Another product’s pid |
wrong-product |
v is 2 |
malformed |
Payload edited to a far-off exp, old signature |
bad-signature |
| Signed by another key | bad-signature |
| The live demo token, with a different public key | bad-signature |
Two or four parts, sgt2 prefix, plain text |
malformed |
| Fresh token, 15 days later | stale |
| Fresh token, clock behind a token already seen | clock-set-back |
The live demo token is real and decodes, but Clavem signed it with its own key, so a verifier with any other public key has to refuse it. Write a PHPUnit data provider with these rows, passing $now, and the 15-days-later case needs no waiting.
Traps in WordPress and PHP
time()and notcurrent_time( 'timestamp' ). The second is offset by the site’s timezone. It is not a Unix timestamp.- 32-bit PHP. Its integers overflow in 2038, and
json_decodereturns a float for a number that does not fit. Timestamps are fine today, but test on your oldest supported build before you rely on the(int)casts. base64_decodeneeds the strict flag. Withouttrueit skips characters it does not know.- Network-activated multisite. Use
get_site_optionandupdate_site_optionfor these values, so one network shares one result. - The check is plugin source. A customer can edit it. Keep anything that must stay protected on your own server.
Where the token lives
The token is signed, not secret, so it needs integrity more than hiding. An option with autoload off is fine, and a changed byte fails the signature. The payload holds the buyer’s email in readable form, so keep it out of debug logs and out of any admin screen.
Doing this with Clavem
Each product has its own key pair. The public half is on the product page and in GET /v1/admin/products, and every activate and validate response carries a token signed with the private half. See the API reference for the endpoints.
Questions
Does WordPress include Ed25519 verification?
Through the sodium functions. PHP ships the sodium extension, and WordPress loads sodium_compat when it is missing, so sodium_crypto_sign_verify_detached is available. The compat version is plain PHP and slower, which is one reason to verify rarely.
Why not use current_time for the clock?
current_time with the timestamp type returns a value shifted by the site's timezone offset, so it is not a Unix timestamp. Tokens use real Unix seconds, so compare with time(), which is always UTC.
Can a customer edit the check out of my plugin?
Yes. A plugin is PHP source on their server, and anyone can edit it. The signature stops forged tokens and refresh_by stops old ones, but nothing stops a patched plugin. Plan for honest customers, and keep the server-side parts of your product on your own server.