<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\library\mail;
use seekquarry\yioop\library as L;
/**
* Builds and checks the signed tokens used in one-click mail
* unsubscribe links. A token names the member and the group their
* unsubscribe applies to, plus a signature so the link cannot be
* altered to unsubscribe a different person or group. The signature is
* an HMAC keyed by this site's secret AUTH_KEY, so a token only
* verifies on the site that issued it and cannot be forged without
* that key.
*/
class UnsubscribeToken
{
/**
* Mixed into the signed text so an unsubscribe signature can never
* be mistaken for, or reused as, some other value the site signs
* with the same key.
*/
const SIGN_PREFIX = "mail-unsubscribe:";
/**
* Mixed into the signed text of a whole-site unsubscribe token. It
* differs from SIGN_PREFIX so a token that turns off one group can
* never be read as one that turns off all mail, and the reverse.
*/
const DOMAIN_SIGN_PREFIX = "mail-unsubscribe-all:";
/**
* Builds the signed token that names one member and one group for
* an unsubscribe link.
*
* @param int $user_id the member the link unsubscribes
* @param int $group_id the group being unsubscribed from
* @return string the two ids and their signature joined by dots,
* safe to drop straight into a URL
*/
public static function make($user_id, $group_id)
{
$payload = intval($user_id) . "." . intval($group_id);
return $payload . "." . self::signPayload(self::SIGN_PREFIX, $payload);
}
/**
* Reads a token from an unsubscribe link and, when its signature
* checks out, returns who and which group it names. Returns false
* for anything that does not parse or whose signature does not
* match, so a tampered or made-up link is simply rejected.
*
* @param string $token the token taken from the link
* @return array|bool ['user_id' => int, 'group_id' => int] when the
* token is valid, or false when it is not
*/
public static function parse($token)
{
$parts = explode(".", (string) $token);
if (count($parts) !== 3) {
return false;
}
list($user_id, $group_id, $signature) = $parts;
if (!ctype_digit($user_id) || !ctype_digit($group_id)) {
return false;
}
$payload = $user_id . "." . $group_id;
if (!hash_equals(
self::signPayload(self::SIGN_PREFIX, $payload),
$signature)) {
return false;
}
return ["user_id" => intval($user_id),
"group_id" => intval($group_id)];
}
/**
* Builds the signed token that names one email address for a
* whole-site unsubscribe. The bot mailbox checks this signature
* before it will turn off all of a site's mail to an address, so a
* forged request naming someone else's address is rejected: only
* this site, holding the secret key, can produce a token that
* verifies.
*
* @param string $email the address the token unsubscribes
* @return string the encoded address and its signature joined by a
* dot, safe to carry in a mail subject or address
*/
public static function makeEmail($email)
{
$payload = rtrim(strtr(
base64_encode(trim((string) $email)), "+/", "-_"), "=");
return $payload . "." .
self::signPayload(self::DOMAIN_SIGN_PREFIX, $payload);
}
/**
* Reads a whole-site unsubscribe token and, when its signature
* checks out, returns the email address it names. Returns false for
* anything that does not parse or whose signature does not match, so
* a forged or tampered request is simply ignored.
*
* @param string $token the token taken from the unsubscribe mail
* @return string|bool the email address when the token is valid, or
* false when it is not
*/
public static function parseEmail($token)
{
$parts = explode(".", (string) $token);
if (count($parts) !== 2) {
return false;
}
list($payload, $signature) = $parts;
if (!hash_equals(
self::signPayload(self::DOMAIN_SIGN_PREFIX, $payload),
$signature)) {
return false;
}
$email = (string) base64_decode(
strtr($payload, "-_", "+/"));
if ($email === "") {
return false;
}
return $email;
}
/**
* Builds the List-Unsubscribe mail headers for one recipient of a
* group's mail. The recipient's mail program is handed two ways to
* unsubscribe, each carrying a signed token naming this member and
* group: a one-click web address and a mailto address. The second
* header is the one-click marker (RFC 8058) that lets a single click
* in the mail program turn the group's mail off without the member
* having to open a page.
*
* @param int $user_id the member being mailed
* @param int $group_id the group whose mail they may turn off
* @param string $base_url site address the unsubscribe page lives on
* (the site the mail went out from); the web link is this plus
* the api unsubscribe query
* @param string $mailto_address address that accepts unsubscribe mail
* (the bot mailbox when this site runs its own mail, otherwise
* the site's own from address)
* @return array two headers as name => value: List-Unsubscribe (the
* mailto and web links) and List-Unsubscribe-Post (the one-click
* marker)
*/
public static function listUnsubscribeHeaders($user_id, $group_id,
$base_url, $mailto_address)
{
return self::headersForToken(self::make($user_id, $group_id),
$base_url, $mailto_address);
}
/**
* Builds the List-Unsubscribe mail headers for a recipient whose
* link turns off ALL of this site's mail to their address. Used on
* mail (such as a registration confirmation) that is not tied to any
* one group. The recipient's mail program is handed the same two
* ways to unsubscribe as the group headers, but the token names an
* email address rather than a member and group.
*
* @param string $email the address being mailed
* @param string $base_url site address the unsubscribe page lives on
* (the site the mail went out from)
* @param string $mailto_address address that accepts unsubscribe mail
* @return array two headers as name => value: List-Unsubscribe (the
* mailto and web links) and List-Unsubscribe-Post (the one-click
* marker)
*/
public static function listUnsubscribeHeadersForEmail($email,
$base_url, $mailto_address)
{
return self::headersForToken(self::makeEmail($email),
$base_url, $mailto_address);
}
/**
* Builds the web address of the unsubscribe page for an
* already-made token, the link a recipient clicks (or that a mail
* client follows) to reach the confirm / one-click page.
*
* @param string $token the signed unsubscribe token to carry
* @param string $base_url site address the unsubscribe page lives on
* @return string the full unsubscribe web address
*/
public static function unsubscribeUrl($token, $base_url)
{
return $base_url . "?c=api&a=unsubscribe&token=" .
urlencode($token);
}
/**
* Builds the pair of List-Unsubscribe headers around an already-made
* token, shared by the group and whole-site header builders. The
* recipient's mail program is handed two ways to unsubscribe, each
* carrying the token: a one-click web address and a mailto address.
* The second header is the one-click marker (RFC 8058) that lets a
* single click in the mail program unsubscribe without opening a
* page.
*
* @param string $token the signed unsubscribe token to carry
* @param string $base_url site address the unsubscribe page lives on
* @param string $mailto_address address that accepts unsubscribe mail
* @return array two headers as name => value: List-Unsubscribe (the
* mailto and web links) and List-Unsubscribe-Post (the one-click
* marker)
*/
private static function headersForToken($token, $base_url,
$mailto_address)
{
$web = self::unsubscribeUrl($token, $base_url);
$mailto = "mailto:" . $mailto_address . "?subject=" .
urlencode("unsubscribe " . $token);
return [
"List-Unsubscribe" => "<" . $mailto . ">, <" . $web . ">",
"List-Unsubscribe-Post" => "List-Unsubscribe=One-Click",
];
}
/**
* Signs a token's payload with this site's secret key. The prefix
* keeps the two kinds of token apart: a one-group signature and a
* whole-site signature over the same payload come out different, so
* neither can be read as the other.
*
* @param string $prefix the kind-of-token prefix mixed into the
* signed text (SIGN_PREFIX or DOMAIN_SIGN_PREFIX)
* @param string $payload the token body being signed
* @return string the URL-safe signature for that payload
*/
private static function signPayload($prefix, $payload)
{
return L\crawlAuthHash($prefix . $payload);
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software