Repository navigation
FOUR-34335: Add Responder Tracking and Personalized Email Links for Actions by Email #9169
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
31 commits
Select commit
Hold shift + click to select a range
60f1dad
Add AbeRecipientSignature for personalized ABE link params
sanjacornelius e25015a
Add AbeResponder to build nested abe_responder request data
sanjacornelius 322a4ec
Send one signed ABE email per unique recipient with merged groups
sanjacornelius 713fb0e
Append signed recipient params to ABE update_variable links in email …
sanjacornelius 904dbda
Store ABE click metadata under abe_responder in request data
sanjacornelius a36e05c
Cover overlapping groups and shared-email recipient dedupe for ABE
sanjacornelius fc1489a
Add stress tests for large and overlapping ABE recipient groups
sanjacornelius 44fa8b9
Gate personalized ABE emails behind trackResponder and stagger queue …
sanjacornelius c0255c7
Omit abe_responder from request data unless trackResponder is enabled
sanjacornelius 2bf3bd6
Add send-side trackResponder and stagger coverage; enable tracking in…
sanjacornelius 65bc9be
Document Track responder identity for Actions by Email
sanjacornelius 8a91e6f
Preserve signed ABE click params across Require Login via abe_click_t…
sanjacornelius 71ccb41
Omit identity_mismatch unless a signed ABE recipient is present to co…
sanjacornelius fdb33c3
Test Require Login preserves signed recipient and omits mismatch with…
sanjacornelius 6a4fa3e
Document abe_click_ticket restore and forward + Require Login mismatc…
sanjacornelius beef46d
Render the ABE email screen once per mailer and reuse it for personal…
sanjacornelius 95e0ab4
Assert personalized ABE batches render the email screen once per reci…
sanjacornelius 2eb5d70
Note that personalized ABE tracking renders the email screen once per…
sanjacornelius a70b0a0
Rethrow ValidationException from updateVariable so missing ABE query …
sanjacornelius a04dd64
Assert expired `abe_click` restore returns 422 validation errors, not…
sanjacornelius 4712c1f
Merge branch 'develop' into subtask/FOUR-34335
sanjacornelius c1968d7
Refactor updateVariable to lower Sonar cognitive complexity and retur…
sanjacornelius 495b56d
Reduce restoreAbeClickQuery return count for SonarQube
sanjacornelius e05b7f1
Reduce Sonar CC on validateAndSendActionByEmail via extraction and ea…
sanjacornelius d1e32cf
Remove unnecessary regex group in TaskActionByEmail ABE href pattern
sanjacornelius 65144d5
Extract ABE self-service recipient helpers to satisfy Sonar CC and re…
sanjacornelius 2f0fae8
Split processModelForAbeToken into helpers to lower cognitive complexity
sanjacornelius 6c1013f
Use UnableToResolveAbeProcessModelException in ABE Process resolution
sanjacornelius 8a5c70b
Fix Sonar nested-if in AbeResponder::detectEmailClient Apple Mail branch
sanjacornelius ad7c088
Reduce AbeResponder authenticatedUser return count to satisfy Sonar
sanjacornelius 0f1bfca
Refactor AbeResponder::detectEmailClient for Sonar return-count limit
sanjacornelius File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
16 changes: 16 additions & 0 deletions
16
ProcessMaker/Exception/UnableToResolveAbeProcessModelException.php
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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'); | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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); | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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'); | ||
| } | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Base64 query params break signatures
Medium Severity
abe_groupsis standard Base64 placed in a query string and bound into the HMAC. Base64+is a space in query parsing, and many email clients decode%2Bback to+before the click. Strictbase64_decodethen fails, verification returns null, andemail,user_id, andgroupsare all dropped even though the action still completes.Additional Locations (1)
ProcessMaker/Helpers/AbeRecipientSignature.php#L36-L37Reviewed by Cursor Bugbot for commit 0f1bfca. Configure here.