AltchaService
in package
Issues and verifies ALTCHA proof-of-work challenges.
Tags
Table of Contents
Constants
- ALGORITHM = 'SHA-256'
- Hash algorithm advertised to and required from the client.
- ALGORITHM_ID = 'sha256'
- The same algorithm as a PHP hash()/hash_hmac() identifier.
- MAX_NUMBER = 50000
- Upper bound for the secret number the client must brute-force. Larger = more work per attempt. ~50k keeps a real user's solve well under a second while still costing a bot meaningfully at scale.
- TTL_SECONDS = 600
- How long an issued challenge stays valid, in seconds.
Properties
Methods
- __construct() : mixed
- createChallenge() : array{algorithm: string, challenge: string, maxnumber: int, salt: string, signature: string}
- Create a fresh challenge for the client to solve.
- fromEnvironment() : self
- Build a service from environment configuration.
- isEnabled() : bool
- Whether challenges are being enforced.
- verify() : bool
- Verify a base64-encoded solution payload sent back by the client.
- isExpired() : bool
- Whether the salt's embedded `expires` timestamp is in the past. A salt without an expiry is treated as valid (never expires).
- loadOrCreatePersistedKey() : string
- Load the persisted auto-generated HMAC key, creating it on first use.
Constants
ALGORITHM
Hash algorithm advertised to and required from the client.
private
mixed
ALGORITHM
= 'SHA-256'
ALGORITHM_ID
The same algorithm as a PHP hash()/hash_hmac() identifier.
private
mixed
ALGORITHM_ID
= 'sha256'
MAX_NUMBER
Upper bound for the secret number the client must brute-force. Larger = more work per attempt. ~50k keeps a real user's solve well under a second while still costing a bot meaningfully at scale.
private
mixed
MAX_NUMBER
= 50000
TTL_SECONDS
How long an issued challenge stays valid, in seconds.
private
mixed
TTL_SECONDS
= 600
Properties
$enabled
private
bool
$enabled
$hmacKey
private
string
$hmacKey
Methods
__construct()
public
__construct(string $hmacKey[, bool $enabled = true ]) : mixed
Parameters
- $hmacKey : string
-
Secret key used to sign/verify challenges.
- $enabled : bool = true
-
When false, verification is skipped (returns true) and the challenge endpoint advertises "disabled".
createChallenge()
Create a fresh challenge for the client to solve.
public
createChallenge() : array{algorithm: string, challenge: string, maxnumber: int, salt: string, signature: string}
Return values
array{algorithm: string, challenge: string, maxnumber: int, salt: string, signature: string}fromEnvironment()
Build a service from environment configuration.
public
static fromEnvironment() : self
- ALTCHA_ENABLED (default true) toggles the feature.
- ALTCHA_HMAC_KEY supplies the signing secret. When unset, a random key is generated once and persisted to the system temp dir so challenges remain verifiable across requests/workers. Production installs should set ALTCHA_HMAC_KEY explicitly for a stable, backed-up secret.
Return values
selfisEnabled()
Whether challenges are being enforced.
public
isEnabled() : bool
Return values
boolverify()
Verify a base64-encoded solution payload sent back by the client.
public
verify(string $payloadBase64) : bool
Parameters
- $payloadBase64 : string
-
Base64 of the JSON {algorithm, challenge, number, salt, signature} returned by the ALTCHA widget/solver.
Return values
bool —True if the solution is valid (or the feature is disabled).
isExpired()
Whether the salt's embedded `expires` timestamp is in the past. A salt without an expiry is treated as valid (never expires).
private
isExpired(string $salt) : bool
Parameters
- $salt : string
Return values
boolloadOrCreatePersistedKey()
Load the persisted auto-generated HMAC key, creating it on first use.
private
static loadOrCreatePersistedKey() : string
Used only when ALTCHA_HMAC_KEY is not configured. The key must be shared across requests/workers, so it lives in a file rather than memory.