Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
60f1dad
Add AbeRecipientSignature for personalized ABE link params
sanjacornelius Nov 14, 2026
e25015a
Add AbeResponder to build nested abe_responder request data
sanjacornelius Nov 14, 2026
322a4ec
Send one signed ABE email per unique recipient with merged groups
sanjacornelius Nov 14, 2026
713fb0e
Append signed recipient params to ABE update_variable links in email …
sanjacornelius Nov 14, 2026
904dbda
Store ABE click metadata under abe_responder in request data
sanjacornelius Nov 14, 2026
a36e05c
Cover overlapping groups and shared-email recipient dedupe for ABE
sanjacornelius Nov 14, 2026
fc1489a
Add stress tests for large and overlapping ABE recipient groups
sanjacornelius Nov 14, 2026
44fa8b9
Gate personalized ABE emails behind trackResponder and stagger queue …
sanjacornelius Nov 14, 2026
c0255c7
Omit abe_responder from request data unless trackResponder is enabled
sanjacornelius Nov 14, 2026
2bf3bd6
Add send-side trackResponder and stagger coverage; enable tracking in…
sanjacornelius Nov 14, 2026
65bc9be
Document Track responder identity for Actions by Email
sanjacornelius Nov 14, 2026
8a91e6f
Preserve signed ABE click params across Require Login via abe_click_t…
sanjacornelius Nov 15, 2026
71ccb41
Omit identity_mismatch unless a signed ABE recipient is present to co…
sanjacornelius Nov 15, 2026
fdb33c3
Test Require Login preserves signed recipient and omits mismatch with…
sanjacornelius Nov 15, 2026
6a4fa3e
Document abe_click_ticket restore and forward + Require Login mismatc…
sanjacornelius Nov 15, 2026
beef46d
Render the ABE email screen once per mailer and reuse it for personal…
sanjacornelius Nov 16, 2026
95e0ab4
Assert personalized ABE batches render the email screen once per reci…
sanjacornelius Nov 16, 2026
2eb5d70
Note that personalized ABE tracking renders the email screen once per…
sanjacornelius Nov 16, 2026
a70b0a0
Rethrow ValidationException from updateVariable so missing ABE query …
sanjacornelius Nov 16, 2026
a04dd64
Assert expired `abe_click` restore returns 422 validation errors, not…
sanjacornelius Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 131 additions & 0 deletions ProcessMaker/Helpers/AbeRecipientSignature.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
<?php

namespace ProcessMaker\Helpers;

use Illuminate\Http\Request;

/**
* Signs and verifies personalized ABE recipient query parameters.
*
* Payload: recipient email, user_id, and assigned group(s) for the task.
*/
class AbeRecipientSignature
{
public const EMAIL = 'abe_email';

public const USER_ID = 'abe_user_id';

public const GROUPS = 'abe_groups';

public const SIG = 'abe_sig';

/**
* Build a signed query string to append to ABE action URLs.
*
* @param array<int, array{id:int|string, name?:string}> $groups
*/
public static function queryString(string $tokenAbe, string $email, int|string|null $userId, array $groups = []): string
{
$normalizedGroups = self::normalizeGroups($groups);
$params = [
self::EMAIL => strtolower(trim($email)),
self::USER_ID => (string) (int) $userId,
self::GROUPS => self::encodeGroups($normalizedGroups),
];
$params[self::SIG] = self::sign($tokenAbe, $params[self::EMAIL], $params[self::USER_ID], $normalizedGroups);

return http_build_query($params);
}

/**
* Verify signed params from the request. Returns null if missing/invalid.
*
* @return array{email:string,user_id:int,groups:array}|null
*/
public static function verify(Request $request, string $tokenAbe): ?array
{
$email = strtolower(trim((string) $request->query(self::EMAIL, '')));
$userId = (string) $request->query(self::USER_ID, '');
$groupsEncoded = (string) $request->query(self::GROUPS, '');
$sig = (string) $request->query(self::SIG, '');

if ($email === '' || $sig === '') {
return null;
}

$groups = self::decodeGroups($groupsEncoded);
$expected = self::sign($tokenAbe, $email, $userId, $groups);

if (!hash_equals($expected, $sig)) {
return null;
}

return [
'email' => $email,
'user_id' => (int) $userId,
'groups' => $groups,
];
}

/**
* @param array<int, array{id:int|string, name?:string}> $groups
*/
private static function sign(string $tokenAbe, string $email, string $userId, array $groups): string
{
$canonical = implode('|', [
$tokenAbe,
strtolower(trim($email)),
(string) (int) $userId,
self::encodeGroups($groups),
]);

return hash_hmac('sha256', $canonical, (string) config('app.key'));
}

/**
* @param array<int, array{id:int|string, name?:string}> $groups
* @return array<int, array{id:int, name:string}>
*/
private static function normalizeGroups(array $groups): array
{
$normalized = [];
foreach ($groups as $group) {
if (!is_array($group) || !isset($group['id'])) {
continue;
}
$normalized[] = [
'id' => (int) $group['id'],
'name' => (string) ($group['name'] ?? ''),
];
}

usort($normalized, static fn ($a, $b) => $a['id'] <=> $b['id']);

return $normalized;
}

/**
* @param array<int, array{id:int, name:string}> $groups
*/
private static function encodeGroups(array $groups): string
{
return base64_encode(json_encode(array_values($groups)));
}

/**
* @return array<int, array{id:int, name:string}>
*/
private static function decodeGroups(string $encoded): array
{
if ($encoded === '') {
return [];
}

$decoded = json_decode(base64_decode($encoded, true) ?: '', true);
if (!is_array($decoded)) {
return [];
}

return self::normalizeGroups($decoded);
}
}
116 changes: 116 additions & 0 deletions ProcessMaker/Helpers/AbeResponder.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
<?php

namespace ProcessMaker\Helpers;

use Carbon\Carbon;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use ProcessMaker\Models\AnonymousUser;
use ProcessMaker\Models\User;

/**
* Builds the abe_responder request-data object from an ABE click.
*/
class AbeResponder
{
/**
* @return array<string, mixed>
*/
public static function fromRequest(Request $request, string $tokenAbe): array
{
$signed = AbeRecipientSignature::verify($request, $tokenAbe);
$actedAt = Carbon::now()->toIso8601String();
$userAgent = (string) $request->userAgent();

$responder = [
'acted_at' => $actedAt,
'ip_address' => $request->ip(),
'user_agent' => $userAgent,
'device' => self::detectDevice($userAgent),
'email_client' => self::detectEmailClient($userAgent),
];

if ($signed) {
$responder['email'] = $signed['email'];
$responder['user_id'] = $signed['user_id'] ?: null;
$responder['groups'] = $signed['groups'];
}

$authUser = self::authenticatedUser();
if ($authUser) {
$responder['authenticated_email'] = $authUser->email;
$responder['authenticated_user_id'] = $authUser->id;

// Only compare when a signed recipient is present. If the signature
// is missing/invalid (e.g. query params dropped after login redirect),
// do not claim identity_mismatch false — there is nothing to match.
$signedEmail = strtolower(trim((string) ($responder['email'] ?? '')));
if ($signedEmail !== '') {
$authEmail = strtolower(trim((string) $authUser->email));
$responder['identity_mismatch'] = $signedEmail !== $authEmail;
}
}

return $responder;
}

private static function authenticatedUser(): ?User
{
if (!Auth::check()) {
return null;
}

$user = Auth::user();
if (!$user instanceof User) {
return null;
}

// Anonymous session used for public ABE clicks is not a real identity
if (($user->username ?? null) === AnonymousUser::ANONYMOUS_USERNAME) {
return null;
}

return $user;
}

private static function detectDevice(string $userAgent): string
{
$ua = strtolower($userAgent);
if ($ua === '') {
return 'unknown';
}
if (preg_match('/mobile|android|iphone|ipad|ipod|blackberry|windows phone/i', $ua)) {
return 'mobile';
}

return 'desktop';
}

private static function detectEmailClient(string $userAgent): string
{
$ua = strtolower($userAgent);
if ($ua === '') {
return 'Unknown';
}
if (str_contains($ua, 'googleimageproxy') || str_contains($ua, 'gmail')) {
return 'Gmail';
}
if (str_contains($ua, 'outlook') || str_contains($ua, 'microsoft office') || str_contains($ua, 'ms-office')) {
return 'Outlook';
}
if (str_contains($ua, 'thunderbird')) {
return 'Thunderbird';
}
if (str_contains($ua, 'yahoo')) {
return 'Yahoo Mail';
}
if (str_contains($ua, 'applewebkit') && (str_contains($ua, 'macintosh') || str_contains($ua, 'iphone') || str_contains($ua, 'ipad'))) {
// Apple Mail / iOS Mail often look like Safari; coarse best-effort
if (!str_contains($ua, 'crios') && !str_contains($ua, 'fxios') && !str_contains($ua, 'edgios')) {
return 'Apple Mail';
}
}

return 'Unknown';
}
}
Loading
Loading