APPT-659 Booking reference update for scaling and security

[jsed-nhs]

Overview

This PR introduces a new secure, deterministic, and human-readable booking reference format for much higher volume generation than the current format. It has been designed to prevent brute-force and sequential-guessing attacks while remaining operationally simple.

The current format for references collides after 1 million bookings against a site group, which is likely to be hit soon and especially in a pandemic traffic event. Despite the RNG part in the middle, this is only 1/100 chance of hitting every time so is not future proof.

Current Reference Format
SiteGroup (2) + RNG (2) + Sequence (6)
Displayed as: XX-XX-XXXXXX

Current format consecutive references: 04-61-000002, 04-30-000003, 04-58-000004

Proposed New Reference Format
PPYY (4) + PERM8 (8) + Luhn (1)
Displayed as: XXXX-XXXXX-XXXX

New format booking references that are all 'consecutive' in generation, but this is not obvious:

7625-96725-0462
7625-19588-2334
7625-42451-4203

• PPYY: Partition key (4-day partition index 00–91 + 2-digit year), ensures predictable, time-based bucketing.
• PERM8: 8-digit value derived from a coprime permutation of the sequence number, making references non-sequential externally.
• Luhn check: 1-digit checksum for typo and junk filtering.

Benefits

• Fast: extremely low per-ID generation cost.
• Secure: unpredictable without key.
• Scale: 200M+/week capacity for 100 years.
• Human-readable & typo-checked.
• Maintainable: rotation path ready, minimal moving parts.

Sequence Multiplier Derivation

• Uses the HMAC secret (unique per env) and partition PPYY to derive a multiplier S deterministically.
• This multiplier is then manipulated to be coprime with 10^8 by picking a last digit from {1, 3, 7, 9}.
• Ensures a full unique bijection of the 100M possible values per partition.
• Different partition keys generate different multipliers per environment, making the sequence multiplier secure as protected by a secret key.
• Caches the derived multiplier per (HmacKeyVersion, PPYY) covering the partition-days plus overlap, so it isn't computed for every single booking ref generation.

Each booking generation after that is just:

PERM8 = (S * i) % 100_000_000 where S is the derived multiplier and i is the DB sequence number increment

Luhn Digit

• A way of verifying if a provided booking reference is valid without any DB checks for ID existence.
• Protects against guesswork attacks as not all booking refs of the format XXXX-XXXXX-XXXX are valid.
• Can log out to Splunk logs to see if our APIs are being hit with attacks trying to find a valid ID.

Example: 4016-90927-6174 is valid, but 4016-90927-6175 is not despite it having the correct formatted string.

Key Management

• Single key & version ("v1") for MVP, loaded from config and injected into the service.
• Uses per-environment keys (Dev/Int/Stag/Prod) so a leak in one env does not affect others.
• Potential future rotation: upversion to "v2" without changing the reference format; old partitions could continue using "v1" format.

Security

• Large unique values (100M per partition) + partitioning gives ~200M unique references per week.
• Partition Key format means pattern will last for 100 years before being reused and colliding.
• Uses seqeunceNumber increment in cosmosDB so DB access is needed.
• Unpredictable multiplier is derived from a HMAC secret key which means it protects against sequential/brute-force attacks.
• Luhn check digit filters junk traffic early and protects against invalid references.
• Per-environment key isolation improves security for Production.
• Deterministic verification: known PPYY at generation allows multiplier derivation without a further DB lookup.

Tests

• Prove uniqueness algebraically (multiplier coprime to 10^8 guarantees a bijection).
• Full permutation tests use smaller modulus to validate logic efficiently.
• Sample-based tests on real modulus for format + Luhn + uniqueness checks.
• Unit test to demonstrate collisions between different HMAC keys (expected, not a flaw).

Checklist:

• My work is behind a feature toggle (if appropriate)
• If my work is behind a feature toggle, I've added a full suite of tests for both the ON and OFF state
• The ticket number is in the Pull Request title, with format "APPT-XXX: My Title Here"
• I have ran npm tsc / lint (in the future these will be ran automatically)
• My code generates no new .NET warnings (in the future these will be treated as errors)
• If I've added a new Function, it is disabled in all but one of the terraform groups (e.g. http_functions)
• If I've added a new Function, it has both unit and integration tests. Any request body validators have unit tests also
• If I've made UI changes, I've added appropriate Playwright and Jest tests
• If I've added/updated an end-point, I've added the appropriate annotations and tested the Swagger documentation reflects the change

[sonarqubecloud]

Quality Gate passed

Issues
11 New issues
0 Accepted issues

Measures
0 Security Hotspots
92.6% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud