# Hashing

> How to turn an e-mail address, phone number, shipping address and e-mail domain into the hashes TrustOrder accepts. Normalisation rules and test values.

TrustOrder never receives raw personal data. The client normalises each identifier and sends its SHA-256 hash:

```text
hash = lowercase hex( sha256( "trustorder:v1:" + kind + ":" + normalised value ) )
```

`kind` is `email`, `phone`, `address` or `domain`. The input is UTF-8. On the wire a hash is exactly 64 lowercase hex characters (`^[0-9a-f]{64}$`); anything else is rejected with `400`. If a value cannot be normalised, send no hash for it.

The same buyer must give the same hash in every shop, so follow the rules exactly. The WooCommerce plugin implements them; the values below let you test your own implementation.

## E-mail

1. Unicode NFC, trim white space at both ends, lower case (simple case mapping).
2. White space inside the address makes it invalid.
3. Exactly one `@`.
4. The domain goes through IDNA (UTS #46, non-transitional) to its ASCII (punycode) form.
5. Drop everything from the first `+` in the local part.
6. `googlemail.com` becomes `gmail.com`; for `gmail.com` remove every `.` from the local part.
7. An empty local part is invalid; the whole address is at most 254 bytes.

| Input | Normalised |
|---|---|
| `Foo.Bar+shop@GoogleMail.com` | `foobar@gmail.com` |
| `x.y+z@freemail.hu` | `x.y@freemail.hu` |
| `user@bücher.de` | `user@xn--bcher-kva.de` |

## Phone

1. Trim white space; allowed characters are digits, `+`, spaces and `- / ( ) .`. Anything else makes it invalid.
2. A leading `00` becomes `+`.
3. Parse it with libphonenumber, using the billing country as the default region (the shipping country if there is no billing country). `06…` with region `HU` becomes `+36…`.
4. Invalid if libphonenumber says so, if the national number is one repeated digit, or if it is `123456789`, `1234567` or `0123456789`.
5. Output in E.164: `+36301234567`.

`06 30 123 4567`, `0630/123-4567` and `+36 30 123 4567` (region `HU`) all give `+36301234567`.

## Address

Format: `country|postcode|street and house number`, from the shipping address.

- **Country:** ISO 3166 two-letter code, lower case.
- **Postcode:** remove all white space, lower case, drop trailing dots and a leading `<country>-` prefix (for `hu` also `h-`); only `a-z`, `0-9` and `-` may remain.
- **Street:** from address line 1; if it has no house number, line 1 and line 2 together.
  1. Remove accents (NFD, drop combining marks), lower case.
  2. Every character other than `a-z0-9` becomes a space; collapse spaces.
  3. A Budapest district prefix (`XIII. ker.`) is dropped.
  4. Street types are unified: `u`, `utca` → `utca`; `krt`, `korut` → `korut`; `ter`, `tr` → `ter`; `rkp`, `rakpart` → `rakpart`; `stny`, `setany` → `setany`; `ltp`, `lakotelep` → `lakotelep`; `ut` stays `ut`.
  5. Keep the words up to the first number that follows a word: that number is the house number. A single letter right after it is joined to it (`12/A` → `12a`), except `i`, `v` and `x` (Roman numerals of floors). Floor, door and the second half of `10-12` are dropped.
  6. Outside Hungary an address may start with the number (`10 Downing Street`); then every word is kept.

| Line 1 | Normalised |
|---|---|
| `Petőfi Sándor u. 12/A 3. em. 5.` (HU, 1051) | `hu\|1051\|petofi sandor utca 12a` |
| `Fő út 3` (HU, 1051) | `hu\|1051\|fo ut 3` |
| `Andrássy krt. 10-12.` (HU, 1062) | `hu\|1062\|andrassy korut 10` |

## E-mail domain

For disposable e-mail services TrustOrder checks the domain of the address. Send the hash of the punycode domain and of each parent suffix with at least two labels, the most specific first, at most five (`email_domain_hashes`). `x.mailinator.com` then cannot slip past a list entry for `mailinator.com`. If the domain has more than five such suffixes, keep the five least specific.

Check the MX record yourself, in the shop, and send only the result in `email_domain_mx` (`true`, `false` or `null` if unknown).

## Test values

| Kind | Normalised value | Hash |
|---|---|---|
| `email` | `foobar@gmail.com` | `8cd79ce2224abde026ddc67563fe5edb8b5eb41846c63cd550a76ea76cc2eddd` |
| `phone` | `+36301234567` | `038e5821814169825ae568bfefdb18ca31d4d2e0a0f5941b6da27df45d50ddf4` |
| `address` | `hu\|1051\|petofi sandor utca 12a` | `956b4ad633a194c484c3fdd6d6145ec1ac929b211438b3452e79b4853f65df96` |
| `domain` | `gmail.com` | `4672a2431309380c7954c449b3ff20d2cd31968853d6e98137dd3b0be3652dae` |
| `domain` | `mailinator.com` | `d612e31dc021a25d209e94df9ba873a15ed02e08a48782ca56defc5b1710c8e6` |

Quick check in a shell:

```bash
printf '%s' 'trustorder:v1:email:foobar@gmail.com' | shasum -a 256
```
