Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 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
4712c1f
Merge branch 'develop' into subtask/FOUR-34335
sanjacornelius Nov 17, 2026
c1968d7
Refactor updateVariable to lower Sonar cognitive complexity and retur…
sanjacornelius Nov 18, 2026
495b56d
Reduce restoreAbeClickQuery return count for SonarQube
sanjacornelius Nov 18, 2026
e05b7f1
Reduce Sonar CC on validateAndSendActionByEmail via extraction and ea…
sanjacornelius Nov 18, 2026
d1e32cf
Remove unnecessary regex group in TaskActionByEmail ABE href pattern
sanjacornelius Nov 18, 2026
65144d5
Extract ABE self-service recipient helpers to satisfy Sonar CC and re…
sanjacornelius Nov 18, 2026
2f0fae8
Split processModelForAbeToken into helpers to lower cognitive complexity
sanjacornelius Nov 18, 2026
6c1013f
Use UnableToResolveAbeProcessModelException in ABE Process resolution
sanjacornelius Nov 18, 2026
8a5c70b
Fix Sonar nested-if in AbeResponder::detectEmailClient Apple Mail branch
sanjacornelius Nov 18, 2026
ad7c088
Reduce AbeResponder authenticatedUser return count to satisfy Sonar
sanjacornelius Nov 18, 2026
0f1bfca
Refactor AbeResponder::detectEmailClient for Sonar return-count limit
sanjacornelius Nov 18, 2026
e1ba7ba
Merge pull request #9169 from ProcessMaker/subtask/FOUR-34335
sanjacornelius Nov 19, 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
16 changes: 16 additions & 0 deletions ProcessMaker/Exception/UnableToResolveAbeProcessModelException.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?php

namespace ProcessMaker\Exception;

use RuntimeException;

/**
* Thrown when the Process model cannot be resolved for ABE recipient lookups.
*/
class UnableToResolveAbeProcessModelException extends RuntimeException
{
public function __construct()
{
parent::__construct('Unable to resolve Process model for ABE recipients');
}
}
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);
}
}
125 changes: 125 additions & 0 deletions ProcessMaker/Helpers/AbeResponder.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
<?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();
// Anonymous session used for public ABE clicks is not a real identity
if (
!$user instanceof User
|| ($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);

return $ua === '' ? 'Unknown' : self::resolveEmailClientName($ua);
}

private static function resolveEmailClientName(string $ua): string
{
if (str_contains($ua, 'googleimageproxy') || str_contains($ua, 'gmail')) {
$client = 'Gmail';
} elseif (str_contains($ua, 'outlook') || str_contains($ua, 'microsoft office') || str_contains($ua, 'ms-office')) {
$client = 'Outlook';
} elseif (str_contains($ua, 'thunderbird')) {
$client = 'Thunderbird';
} elseif (str_contains($ua, 'yahoo')) {
$client = 'Yahoo Mail';
} elseif (self::isAppleMailUserAgent($ua)) {
$client = 'Apple Mail';
} else {
$client = 'Unknown';
}

return $client;
}

/**
* Apple Mail / iOS Mail often look like Safari; coarse best-effort.
*/
private static function isAppleMailUserAgent(string $ua): bool
{
return str_contains($ua, 'applewebkit')
&& (str_contains($ua, 'macintosh') || str_contains($ua, 'iphone') || str_contains($ua, 'ipad'))
&& !str_contains($ua, 'crios')
&& !str_contains($ua, 'fxios')
&& !str_contains($ua, 'edgios');
}
}
Loading
Loading