[WIP] feat: add optional 'ageTiers' for granular risk assessment

[yyeAduna]

Introduce an optional input parameter ageTiers (list of integers) that enables a "Tiered Response" mode, where the highest tier is the maxAge.

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

Introduces an additive, optional mechanism to query SIM swap "recency tiers" without exposing exact timestamps.

Current consumers of the API (e.g., banks) often need more granular signals to assess account-takeover risk alongside their own data for their ML based risk engine (vs the rule based sequential gate). A simple boolean result (True/False) is form of lossy compression and doesn’t provide enough detail, while returning the underlying event date/time isn’t feasible due to strict privacy requirements (e.g., GDPR) and operator restrictions.

Also due to privacy and security reasons, a bank won't want to leak the value/risk of their customer's operation and disclose their internal risk policies to third party by using different maxAge for each individual transactions. The standard age-tier approach will help to protect bank customers' privacy and bank's corporate security.

Solution:

Adds ageTiers (Request): An optional list of integer buckets (e.g., [1, 4, 24]) with max 10 tiers

Adds tierIndex (Response): An optional integer indicating which bucket the swap falls into.

Which issue(s) this PR fixes:

Fixes #248

Special notes for reviewers:

Backward Compatibility Analysis: This change is strictly additive.

The maxAge parameter remains required and continues to drive the standard swapped boolean logic.

If ageTiers is omitted by the client (legacy behavior), the API behaves exactly as the current v2.0.0 spec, and tierIndex is not returned.

Privacy Impact: This improvement enhances privacy by allowing operators to share risk granularity without revealing the exact time of the swap (PII). Also allow the banks (Clients) take full advantage of the function without revealing the value/risk of customer's bank transactions/operations.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: yyeAduna / name: yyeAduna (9f645b2, f7c00c0)

[bigludo7]

Hi @yyeAduna
Thanks !
May I ask you to trigger an issue to gather team feedback.

To be honest this is a breaking change (not from technical perspective but fonctional/business) and from my company we're not sure about the breaking change vs evolution value.
I understand the business requirement but in this case I will see this as a L3 api (composite API) offered by channel partner and consuming atomic L1 MNO API.

I tag some usual suspects to get their view: @fernandopradocabrillo @HuubAppelboom @jgarciahospital @AxelNennker

[HuubAppelboom]

Hi @yyeAduna Thanks ! May I ask you to trigger an issue to gather team feedback.

To be honest this is a breaking change (not from technical perspective but fonctional/business) and from my company we're not sure about the breaking change vs evolution value. I understand the business requirement but in this case I will see this as a L3 api (composite API) offered by channel partner and consuming atomic L1 MNO API.

I tag some usual suspects to get their view: @fernandopradocabrillo @HuubAppelboom @jgarciahospital @AxelNennker

This could get quite complex, better put this first in a separate issue or discussion topic

[yyeAduna]

reopen issue #248 to facilitate discussion