dolibarr 25.0.0-alpha
privacy_guard.class.php
Go to the documentation of this file.
1<?php
2/* Copyright (C) 2026 Laurent Destailleur <eldy@users.sourceforge.net>
3 * Copyright (C) 2026 Nick Fragoulis
4 * Copyright (C) 2026 MDW <mdeweerd@users.noreply.github.com>
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <https://www.gnu.org/licenses/>.
18 */
19
30{
34 public $db;
35
39 private $map = [];
40
44 private $salt = '';
45
49 private $index = 0;
50
59 public function mask($text)
60 {
61 $this->startSession();
62
63 // Emails, before the references: a local part with digits (jean2024@...) would
64 // otherwise be taken as a reference and the domain sent unmasked.
65 $text = preg_replace_callback(
66 '/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/',
71 function (array $m) {
72 return $this->createToken($m[0], 'EMAIL');
73 },
74 $text
75 );
76
77 // References / IDs (e.g. FA24-001, CUS-999)
78 // Must contain letters and numbers and separators. A house number with one
79 // letter (221B, 5a) is left to the address patterns below.
80 $text = preg_replace_callback(
81 '/\b(?!\d{1,5}[A-Za-z]\b)(?=[A-Z0-9]*[0-9])(?=[A-Z0-9]*[A-Z])[A-Z0-9-_]{4,}\b/i',
86 function (array $m) {
87 return $this->createToken($m[0], 'REF');
88 },
89 $text
90 );
91
92 // Credit cards (13-19 digits, various separators)
93 // Use the Luhn algorithm to validate credit cards before masking
94 $text = preg_replace_callback(
95 '/\b(?:\d[ -]*?){13,19}\b/',
96 [$this, 'maskCreditCardCallback'],
97 $text
98 );
99
100 // IBAN (International Bank Account Number)
101 $text = preg_replace_callback(
102 '/\b[A-Z]{2}[0-9]{2}[a-zA-Z0-9]{4,30}\b/',
107 function (array $m) {
108 return $this->createToken($m[0], 'IBAN');
109 },
110 $text
111 );
112
113 // SWIFT / BIC Codes (8 or 11 characters)
114 $text = $this->maskSwift($text);
115
116 // Generic bank account numbers (Context-aware)
117 // This looks for numbers preceded by keywords to reduce false positives.
118 $text = preg_replace_callback(
119 '/(?i)(?:account\s+num(?:ber)?|bank\s+acct|acct\s*#)[:\s#]*\b(\d{8,17})\b/',
124 function (array $m) {
125 return $this->createToken($m[0], 'BANKACCT');
126 },
127 $text
128 );
129
130 // Vat numbers (EU: 2 letters + 2-12 chars)
131 $taxPatterns = [
132 [
133 'name' => 'EU VAT Numbers',
134 'regex' => '/\b(AT|BE|BG|CY|CZ|DE|DK|EE|EL|ES|FI|FR|GB|GR|HR|HU|IE|IT|LT|LU|LV|MT|NL|PL|PT|RO|SE|SI|SK)(?![a-z])[0-9A-Z]{2,12}\b/i',
135 'token' => 'VAT'
136 ],
137 [
138 'name' => 'Canadian GST/HST Numbers',
139 'regex' => '/\b\d{9}\s*RT\s*\d{4}\b/i',
140 'token' => 'TAXID'
141 ],
142 [
143 'name' => 'Australian ABN (Australian Business Number)',
144 'regex' => '/\b\d{2}\s*\d{3}\s*\d{3}\s*\d{3}\b/',
145 'token' => 'TAXID'
146 ],
147 [
148 'name' => 'Norwegian MVA (VAT) Numbers',
149 'regex' => '/\b\d{9}\s*MVA\b/i',
150 'token' => 'TAXID'
151 ],
152 [
153 'name' => 'Swiss VAT Numbers (MWST/TVA/IVA)',
154 'regex' => '/\bCHE-?\d{3}\.?\d{3}\.?\d{3}\s*(MWST|TVA|IVA)\b/i',
155 'token' => 'TAXID'
156 ],
157 ];
158
159 foreach ($taxPatterns as $pattern) {
160 $text = preg_replace_callback(
161 $pattern['regex'],
166 function (array $m) use ($pattern) {
167 return $this->createToken($m[0], $pattern['token']);
168 },
169 $text
170 );
171 }
172
173 // Phone numbers
174 $phonePatterns = [
175 [
176 'name' => 'Greek International Numbers',
177 // +30 / 0030 followed by exactly 10 national digits with the valid
178 // prefixes (2x landline, 69 mobile) — Greek numbers are 10 digits,
179 // so this is checked strictly; other countries fall through to the
180 // length-flexible generic pattern below.
181 'regex' => '/(?<![\w+])(?:\+30|0030)[\s.\-]?(?:2\d|69)(?:[\s.\-()]?\d){8}(?!\d)/',
182 'token' => 'PHONE'
183 ],
184 [
185 'name' => 'Generic International Numbers',
186 // Counts DIGITS (9-14 after the prefix) with optional single separators
187 // between them; the old char-counting class broke on spaced formats.
188 // No \b before '+': space->'+' is not a word boundary, so that \b
189 // could never match and the pattern was dead for '+30 ...' numbers.
190 'regex' => '/(?<![\w+])(?:\+|00)\d{1,3}(?:[\s.\-()]?\d){8,13}(?!\d)/',
191 'token' => 'PHONE'
192 ],
193 [
194 'name' => 'Greek National Numbers',
195 // This pattern is specific to Greece.
196 // Landlines: 10 digits starting with '2' (e.g., 210 123 4567).
197 // Mobiles: 10 digits starting with '69' (e.g., 698 123 4567).
198 // It matches numbers with optional separators like spaces, hyphens, or dots.
199 // Exactly 10 digits (landline 2x..., mobile 69...), separators optional
200 // BETWEEN digits. The old pattern counted characters: '210 2461234'
201 // (11 chars) overflowed {9} and slipped through unmasked, while
202 // '2026-09-07' (9 chars after the 2) was masked as a phone. The
203 // lookarounds forbid digit-adjacency, so it never fires inside longer
204 // digit runs (EAN barcodes, references).
205 'regex' => '/(?<!\d)(?:2\d|69)(?:[\s.\-()]?\d){8}(?!\d)/',
206 'token' => 'PHONE'
207 ],
208 [
209 'name' => 'French National Numbers',
210 // This pattern matches standard 10-digit French numbers.
211 // It handles common formats like "01 23 45 67 89", "01.23.45.67.89", or "0123456789".
212 // It covers all geographic prefixes (01-05) and mobiles (06, 07).
213 'regex' => '/\b0[1-9](?:[\s.-]?\d){8}\b/',
214 'token' => 'PHONE'
215 ],
216 ];
217
218 foreach ($phonePatterns as $pattern) {
219 $text = preg_replace_callback(
220 $pattern['regex'],
225 function (array $m) use ($pattern) {
226 return $this->createToken($m[0], $pattern['token']);
227 },
228 $text
229 );
230 }
231
232 // Address patterns
233 // An address is recognised by its shape around a street word (Street, Rue,
234 // Via, Straße, Οδός...) or a street suffix (Musterweg), never by a list of
235 // words that are not streets: such a list never ends ("Customer 4821",
236 // "Order 1007"...). Without a street word, a name and a number are an
237 // address only when a postcode and a town follow (ΦΟΡΜΙΩΝΟΣ 101, 115 28 Athens).
238 // No i flag on the shapes that start with a word: with it, \p{Lu} also
239 // takes lowercase letters and a match grows leftwards over the sentence.
240 $address_keywords = 'Street|Road|Avenue|Lane|Boulevard|Drive|Court|Way|Plaza|Square|Rue|Allée|Impasse|Chemin|Place|Quai|Via|Viale|Piazza|Corso|Avenida|Paseo|Camino|Strasse|Straße|Platz|Gasse|Weg|Οδός|Οδ\.|Λεωφόρος|Λεωφ\.|Πλατεία';
241 $address_abbreviations = 'St|Rd|Ave|Ln|Blvd|Dr|Ct|Sq|Str';
242 // Written in lowercase after the number, as French, Spanish and Italian
243 // addresses do ("12 rue de Rivoli"); English street words are capitalised.
244 $address_keywords_lower = 'rue|avenue|boulevard|chemin|place|allée|impasse|quai|avenida|paseo|camino|via|viale|piazza|corso';
245 $address_suffixes = 'strasse|straße|weg|platz|gasse|allee|ring|damm|ufer|laan|straat|gracht|vej|gatan|gade';
246 $word = '\p{Lu}[\p{L}\p{N}\.\'\-]*';
247 $particle = '\p{Ll}{1,3}\b'; // de, la, du, del, di, von, der
248 // A house number (12, 12B), never part of a larger number: the 3 of 3,374.00.
249 // A comma may follow it, as in "Musterweg 12, 10115 Berlin".
250 $number = '\d{1,5}[A-Za-z]?(?!\d|[.,]\d)\b';
251 // A postcode then a town, not a currency: "4821, 12500 EUR" is no address.
252 $town = '(?=\s*,?\s*(?:\d{3}\s?\d{2}|\d{4,5})(?!\d)(?!\s*(?:[A-Z]{3}\b|[€$£¥₹%]))\s+\p{Lu})';
253
254 $addressPatterns = [
255 [
256 'name' => 'Number First (e.g., 12 rue de Rivoli, 123 Main St, 221B Baker Street)',
257 'regex' => '/\b\d{1,5}[A-Za-z]?,?\s+(?:' . $word . '\s+){0,3}(?:' . $address_keywords . '|' . $address_abbreviations . '|' . $address_keywords_lower . ')\b\.?(?:\s+(?:' . $word . '|' . $particle . ')){0,4}/u',
258 'token' => 'ADDR'
259 ],
260 [
261 'name' => 'Name First, Keyword After (e.g., Main Street 42, Main St. 42)',
262 'regex' => '/\b' . $word . '(?:\s+' . $word . '){0,2}\s+(?:' . $address_keywords . '|' . $address_abbreviations . ')\.?\s+' . $number . '/u',
263 'token' => 'ADDR'
264 ],
265 [
266 'name' => 'Street Suffix (e.g., Musterweg 12, Hauptstraße 5)',
267 'regex' => '/\b\p{Lu}\p{L}*(?:' . $address_suffixes . ')\.?\s+' . $number . '/u',
268 'token' => 'ADDR'
269 ],
270 [
271 'name' => 'Keyword First (e.g., Rue Victor Hugo 5, Οδός Ερμού 12)',
272 // At least one name between the street word and the number: "Square 3" is no address.
273 'regex' => '/\b(?:' . $address_keywords . ')(?:\s+(?:' . $word . '|' . $particle . ')){1,4}\s+' . $number . '/u',
274 'token' => 'ADDR'
275 ],
276 [
277 'name' => 'No Keyword, Postcode And Town After (e.g., ΦΟΡΜΙΩΝΟΣ 101, 115 28 Athens)',
278 'regex' => '/\b' . $word . '(?:\s+' . $word . '){0,2}\s+' . $number . $town . '/u',
279 'token' => 'ADDR'
280 ],
281 ];
282
283 foreach ($addressPatterns as $pattern) {
284 // We use a callback to replace the found address with a token
285 $text = preg_replace_callback(
286 $pattern['regex'],
291 function (array $m) use ($pattern) {
292 return $this->createToken($m[0], $pattern['token']);
293 },
294 $text
295 );
296 }
297
298 // Zip codes
299 $zipCodePatterns = [
300 [
301 'name' => 'UK Postal Codes',
302 // Matches UK postcodes like SW1A 0AA, M1 1AA, B33 8TH.
303 'regex' => '/\b[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}\b/i',
304 'token' => 'ZIP'
305 ],
306 [
307 'name' => 'Canadian Postal Codes',
308 // Matches Canadian codes like K1A 0B1 or V6A 1H1.
309 'regex' => '/\b[A-CEGHJ-NPR-STV-Z]\d[A-CEGHJ-NPR-STV-Z][ -]?\d[A-CEGHJ-NPR-STV-Z]\d\b/i',
310 'token' => 'ZIP'
311 ],
312 [
313 'name' => 'French Postal Codes',
314 // Matches 5-digit French codes. It's more specific than a generic \d{5}
315 // by checking for valid department numbers (01-95) and Corsica (2A, 2B).
316 'regex' => '/\b(0[1-9]\d{3}|[1-8]\d{4}|9[0-5]\d{2}|2[AB]\d{3})\b/',
317 'token' => 'ZIP',
318 'amounts_look_alike' => true
319 ],
320 [
321 'name' => 'Greek Postal Codes',
322 // Matches 5-digit Greek codes (e.g., 115 28). Note: This is a generic
323 // 5-digit pattern and may have false positives, but is standard for Greece.
324 'regex' => '/\b\d{3}\s?\d{2}\b/',
325 'token' => 'ZIP',
326 'amounts_look_alike' => true
327 ],
328 [
329 'name' => 'US ZIP Codes',
330 // Matches 5-digit US ZIP codes and ZIP+4 format.
331 'regex' => '/\b\d{5}(?:-\d{4})?\b/',
332 'token' => 'ZIP',
333 'amounts_look_alike' => true
334 ],
335 ];
336
337 foreach ($zipCodePatterns as $pattern) {
338 if (!empty($pattern['amounts_look_alike'])) {
339 // A five-digit postcode looks like an amount: masked only outside of one.
340 $text = $this->maskOutsideAmounts($text, $pattern['regex'], $pattern['token']);
341 continue;
342 }
343 $text = preg_replace_callback(
344 $pattern['regex'],
349 function (array $m) use ($pattern) {
350 return $this->createToken($m[0], $pattern['token']);
351 },
352 $text
353 );
354 }
355
356 return $text;
357 }
358
370 private function maskOutsideAmounts($text, $regex, $token)
371 {
372 $m = array();
373 if (!preg_match_all($regex, $text, $m, PREG_OFFSET_CAPTURE)) {
374 return $text;
375 }
376 $labels = 'amount|total|subtotal|sum|price|qty|quantity|balance|due|paid|net|gross|montant|prix|somme|betrag|summe|preis|importe|precio|ποσό|σύνολο|τιμή|αξία';
377 $replace = array();
378 foreach ($m[0] as $found) {
379 $value = (string) $found[0];
380 $start = (int) $found[1];
381 $end = $start + strlen($value);
382 $before = substr($text, max(0, $start - 30), $start - max(0, $start - 30));
383 $after = substr($text, $end, 12);
384 if (preg_match('/\d[.,]$/', $before) || preg_match('/^[.,]\d/', $after)) {
385 continue; // part of a larger number
386 }
387 if (preg_match('/(?:[€$£¥₹]|\b[A-Z]{3})\s*$/u', $before) || preg_match('/^\s*(?:[€$£¥₹%]|[A-Z]{3}\b)/u', $after)) {
388 continue; // next to a currency or a percent sign
389 }
390 if (preg_match('/(?:'.$labels.')\s*[:=]?\s*$/iu', $before)) {
391 continue; // said to be an amount
392 }
393 $replace[] = array($start, strlen($value), $this->createToken($value, $token));
394 }
395 // From the end, so the offsets of the earlier matches stay valid.
396 foreach (array_reverse($replace) as $r) {
397 $text = substr($text, 0, $r[0]).$r[2].substr($text, $r[0] + $r[1]);
398 }
399
400 return $text;
401 }
402
410 public function unmask($jsonString)
411 {
412 if (empty($this->map)) {
413 return $jsonString;
414 }
415
416 // Handle case where AI might return token inside quotes or escaped
417 $search = array_keys($this->map);
418 $replace = array_values($this->map);
419
420 return str_replace($search, $replace, $jsonString);
421 }
422
436 private function maskSwift($text)
437 {
438 $m = array();
439 if (!preg_match_all('/\b[A-Z]{6}([A-Z0-9]{2})([A-Z0-9]{3})?\b/', $text, $m, PREG_SET_ORDER | PREG_OFFSET_CAPTURE)) {
440 return $text;
441 }
442 // Right to left, so the offsets of the earlier codes stay valid.
443 foreach (array_reverse($m) as $hit) {
444 list($code, $pos) = $hit[0];
445 $tail = $hit[1][0].(isset($hit[2]) ? $hit[2][0] : '');
446 $start = max(0, $pos - 30);
447 $before = substr($text, $start, $pos - $start);
448 if (!preg_match('/(bic|swift)/i', $before) && !preg_match('/[0-9]/', $tail)) {
449 continue;
450 }
451 $text = substr($text, 0, $pos).$this->createToken($code, 'SWIFT').substr($text, $pos + strlen($code));
452 }
453
454 return $text;
455 }
456
464 private function maskCreditCardCallback(array $matches)
465 {
466 $potentialCc = $matches[0];
467 if ($this->passesLuhnCheck($potentialCc)) {
468 return $this->createToken($potentialCc, 'CC');
469 }
470
471 // If it doesn't pass the Luhn check, return the original string unmodified.
472 return $potentialCc;
473 }
474
481 private function passesLuhnCheck($number)
482 {
483 // Clean the string to contain only digits.
484 $digits = preg_replace('/\D/', '', $number);
485
486 // Check if the cleaned string is within a valid length range.
487 if (strlen($digits) < 13 || strlen($digits) > 19) {
488 return false;
489 }
490
491 // Perform the Luhn algorithm.
492 $sum = 0;
493 $isEvenDigit = false;
494
495 // Iterate from right to left
496 for ($i = strlen($digits) - 1; $i >= 0; $i--) {
497 $digit = (int) $digits[$i];
498
499 if ($isEvenDigit) {
500 $digit *= 2;
501 // If the result is two digits, sum them (or subtract 9)
502 if ($digit > 9) {
503 $digit -= 9;
504 }
505 }
506
507 $sum += $digit;
508 $isEvenDigit = !$isEvenDigit; // Flip the flag for the next digit
509 }
510
511 // The number is valid if the sum is a multiple of 10.
512 return ($sum % 10) === 0;
513 }
514
522 public function unmaskAiResponse($text)
523 {
524 if (empty($this->map)) {
525 return $text;
526 }
527
528 // Standard unmasking
529 $text = $this->unmask($text);
530
531 // Next, find and replace any tokens that were stripped by the AI.
532 // We iterate through our map and check for the stripped version of each token.
533 foreach ($this->map as $fullToken => $originalValue) {
534 // The stripped token is the full token without the brackets.
535 // e.g., '[[REF_1]]' becomes 'REF_1'
536 $strippedToken = substr($fullToken, 2, -2);
537
538 if (strpos($text, $strippedToken) !== false) {
539 // We found a stripped token in the text, so we replace it.
540 $text = str_replace($strippedToken, $originalValue, $text);
541 }
542 }
543
544 return $text;
545 }
546
552 private function startSession()
553 {
554 // One masking session per guard instance: mask() and maskNames() may
555 // be called several times for one request (query, context line), and
556 // every token they issue must survive in the same map until unmask.
557 if ($this->salt !== '') {
558 return;
559 }
560 $this->map = [];
561 $this->index = 0;
562 $this->salt = dol_substr(dol_hash(uniqid((string) mt_rand(), true), 'md5'), 0, 4);
563 }
564
572 private function createToken($value, $type)
573 {
574 // Reuse the token already issued for this value in this request, so
575 // the same entity reads as the same placeholder throughout the prompt.
576 $existing = array_search($value, $this->map, true);
577 if ($existing !== false) {
578 return (string) $existing;
579 }
580
581 $this->index++;
582 // Format: [[EMAIL_1a2b3c]]. The per-request salt keeps placeholders
583 // unpredictable (a provider cannot correlate "entity 1" across
584 // requests) and prevents collisions with literal [[TYPE_n]] text.
585 $token = "[[{$type}_{$this->index}{$this->salt}]]";
586 $this->map[$token] = $value;
587 return $token;
588 }
589
602 public function maskNames($text, $names)
603 {
604 $this->startSession();
605
606 $clean = array();
607 foreach ($names as $name) {
608 $name = trim((string) $name);
609 // Very short names would shred unrelated words.
610 if (dol_strlen($name) >= 4) {
611 $clean[] = $name;
612 }
613 }
614 if (empty($clean)) {
615 return $text;
616 }
617 $clean = array_unique($clean);
618 usort($clean, function (string $a, string $b) {
619 return dol_strlen($b) - dol_strlen($a);
620 });
621 foreach ($clean as $name) {
622 // Whole words only, case-insensitive in any script ("Acme" must not
623 // eat "Acmetal"), and never inside a placeholder already issued: a
624 // company called "Name" would otherwise break [[NAME_1ab12]].
625 $pattern = '/(?<![\p{L}\p{N}])'.preg_quote($name, '/').'(?![\p{L}\p{N}])/iu';
626 $parts = preg_split('/(\[\[[A-Z]+_[^\]]*\]\])/', $text, -1, PREG_SPLIT_DELIM_CAPTURE);
627 if (!is_array($parts)) {
628 continue;
629 }
630 $found = false;
631 foreach ($parts as $pi => $part) {
632 if ($pi % 2 === 1 || !preg_match($pattern, $part)) {
633 continue;
634 }
635 $found = true;
636 $parts[$pi] = (string) preg_replace($pattern, $this->createToken($name, 'NAME'), $part);
637 }
638 if ($found) {
639 $text = implode('', $parts);
640 }
641 }
642
643 return $text;
644 }
645}
Class to manage privacy data masking and unmasking.
maskNames($text, $names)
Mask the names of the objects carried in this payload.
startSession()
Start the masking session for this guard instance, once.
mask($text)
Mask sensitive GDPR data in the query.
maskCreditCardCallback(array $matches)
Callback function for preg_replace_callback to mask credit cards.
unmaskAiResponse($text)
Unmasks a string from an AI response, handling cases where the AI might have stripped the [[ and ]] d...
passesLuhnCheck($number)
Validates a number string using the Luhn algorithm.
unmask($jsonString)
Restore real data from a masked string.
createToken($value, $type)
Create a unique token and store the original value in the map.
maskOutsideAmounts($text, $regex, $token)
Mask the matches of a pattern, except those that are an amount: part of a larger number (12,...
maskSwift($text)
Mask SWIFT / BIC codes.
dol_strlen($string, $stringencoding='UTF-8', $binarycount=0)
Make a strlen call.
dol_substr($string, $start, $length=null, $stringencoding='', $trunconbytes=0)
Make a substring.
dol_hash($chain, $type='0', $nosalt=0, $mode=0)
Returns a hash (non reversible encryption) of a string.