Proposal for adding (optional) SIM type information

[HuubAppelboom]

What type of PR is this?

• enhancement/feature

What this PR does / why we need it:

Customers that use the SIM Swap API in combination with Number Verify immediately after the user has migrated to a new device experience a large number of false positives due to eSIMs. By recognizing eSIMs and in particular the type of transfer with eSIMs, the API Consumer can correct for this.

Which issue(s) this PR fixes:

Fixes #241

Special notes for reviewers:

@bigludo7 @jlurien @fernandopradocabrillo Can you please review and approve this PR for fixing the false positives problem with eSIMs?

Changelog input

 release-note

Additional documentation

This section can be blank.

docs

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: HuubAppelboom / name: Huub Appelboom (0651e3d, 06fc922, 25e0967, de493a1)

[bigludo7]

Hello
I understood from #241 that we have an agreement for this one.

I'm just a bit anxious the calendar regarding freezing Syn26 release.
@HuubAppelboom could you solve the 2 blocking points? & @albertoramosmonagas I guess we're still on track to integrate this one for syn 26 but time running short right?

[albertoramosmonagas]

Hi @HuubAppelboom, @bigludo7, some points from my side:

1. The field should be named simType to comply with the CAMARA naming guidelines.

simType:
  type: string
  maxLength: 4
  enum:
    - eSIM
    - pSIM
  description: The type of SIM that is currently active, either an eSIM or a physical SIM card.

2. The concept of directTransfer should be described more precisely. The current definition is quite generic and does not clearly explain what constitutes a direct transfer or how this process is performed from an implementation perspective.
3. Please replace the term "Telecom Provider" with "Telco Operator" throughout the proposal to maintain consistency with CAMARA terminology.

With these changes, I think we can move foward the PR

[HuubAppelboom]

@bigludo7 @albertoramosmonagas
The CLA authorization should be under way, hopefully today.

[HuubAppelboom]

@albertoramosmonagas
About the directTransfer: I agree with your comment that we should make it more precise, I am a bit puzzled how to do that.
Are we allowed to put links in the YAML towards for example urls where Apple or Android describe their versions of the directTransfer process ? Like a link to https://support.apple.com/en-us/118669 ?
Are we even allowed to mention IOS and Android ?

Regarding the name directTransfer, we could also call this directDeviceTransfer

And in stead of a boolean, use an enum with directDeviceTransfer and carrierActivation
That may be more future proof in case we want to make it more granular in future.

What do you think ?

[albertoramosmonagas]

Hi @HuubAppelboom, thanks for checking.

On links / vendor references: my understanding is that they are not forbidden, but the YAML should be self-contained for all normative behavior and should not depend on mutable third-party pages. So Apple / Android references could be mentioned as illustrative examples or kept in maintained explanatory documentation, but the API contract itself should remain vendor-neutral and not make those links normative.

On the field itself, I would avoid an enum such as directDeviceTransfer / carrierActivation for now, as that starts exposing transfer / activation mechanisms again and may become difficult to standardize across operators. I would prefer to keep it simple for this PR with an optional boolean field. I still think directDeviceTransfer is too narrow if we also want to cover same-device pSIM-to-eSIM migration. Something like assuredTransfer seems more accurate.

Suggested semantics:

• assuredTransfer=true: the SIM swap was performed through a CSP-verified transfer flow requiring possession/control of the previously active SIM or trusted device.
• assuredTransfer=false: the CSP knows the swap was not performed through such an assured transfer flow.
• if the CSP cannot determine this or does not support the attribute, the field should be omitted.

Both simType and assuredTransfer should remain optional and bound to the same SIM swap event the response refers to: the latest swap within the /check maxAge window, or the event behind latestSimChange for /retrieve-date.

So my suggestion would be: optional simType + optional assuredTransfer, vendor-neutral normative wording in the YAML, and any Apple/Android details only as non-normative examples or in maintained documentation.

[HuubAppelboom]

@bigludo7 @albertoramosmonagas @fernandopradocabrillo I have made all the requested changes, can you please review ?

[albertoramosmonagas]

Hi @HuubAppelboom, thanks for the update.

The only blocking points I still see are:

1. simType should not be described as the SIM type that is “currently active”, as this may be ambiguous in multi-SIM scenarios. It should be explicitly bound to the relevant SIM swap event:
   • for /check, the latest swap within the requested maxAge window;
   • for /retrieve-date, the event behind latestSimChange.
2. The expected behaviour for assuredTransfer should be clarified:
   • assuredTransfer=true: the CSP knows the SIM swap was performed through a CSP-verified transfer flow requiring possession/control of the previously active SIM or trusted device.
   • assuredTransfer=false: the CSP knows the SIM swap was not performed through such an assured transfer flow.
   • if the CSP cannot determine this or does not support the attribute, the field should be omitted.

With these two clarifications, the proposal looks good from my side.

[bigludo7]

Hello @HuubAppelboom
Thanks for the contribution.
2 points for your consideration:

• Examples in the yaml need to be updated.
• As the API is stable we have to be precise in the Test definition. I guess we have to provide additional TCs in the sim-swap-retrieveSimSwapDate.feature file to test specifically these 2 new attributes: 1 test for eSIM, 1 for Physical, 1 for Transfert done by the operator, 1 for transfer not done by the operator. These tests are not mandatory and applies only if the carrier provide this information but for me they must be present.

[HuubAppelboom]

@bigludo7 I added a fourth example showing a case of extra provided information. Can you check this one ?

@albertoramosmonagas I added some extra parts in de definition section. I also replaced "currently active" by the SIM after the swap event.

Somehow the CAMARA Validation also fails. Is that normal ?

[HuubAppelboom]

@bigludo7 I have als added 2TCs in the sim-swap-retrieveSimSwapDate.feature file, one for eSIM and assuredTransfer true, and one for pSIM and assuredTransfer false. That probably is sufficient, or do we need to provide all possible combinations?
Can you plscheck these ? I am not that familiar with these test case descriptions
Thanks in advance,

[albertoramosmonagas]

Hi @HuubAppelboom, thanks for the update. A few points:

1. On the CAMARA validation failure: this does not appear to be caused by the functional proposal itself, or by adding simType and assuredTransfer. It looks mainly like a specification consistency / YAML structure issue introduced by the latest changes.

   In particular, the RETRIEVE_DATE example was renamed, but an existing reference still points to the previous name, so the validator cannot resolve that component. The YAML also contains several trailing spaces and what looks like an indentation issue. Since OpenAPI components depend on the YAML hierarchy being exact, that indentation problem may also be causing the validator to interpret some sections incorrectly and report additional unresolved references, such as x-correlator and ErrorInfo.

2. The new retrieve-date test cases should probably not use latestSimChange = null. Since simType and assuredTransfer are bound to the SIM swap event behind latestSimChange, the test should cover a case where latestSimChange is actually returned. If the date is null because the event is outside the monitored / retention period, we should not expose event-level attributes for that non-returned event.

3. Since the new optional attributes are added to both /retrieve-date and /check, I think we should also add at least basic test coverage for /check, not only for sim-swap-retrieveSimSwapDate.feature.

On the number of combinations: from my side, I do not think we need to test all possible combinations. Two positive optional-information cases should be enough if they cover both simType values and both assuredTransfer values, for example eSIM + assuredTransfer=true and pSIM + assuredTransfer=false.

[HuubAppelboom]

@bigludo7 HI Ludo, can you help with this PR ? I am getting errors related to x-correlator in this PR in the RetrieveAgeBand area,

The CAMARA file I could inspect shows /retrieve-age-band using local component references, while /retrieve-date and /check still use the shared common CAMARA reference.

Do you know what the correct refencing should be ? Should I change this in the YAML? Or is this already being addressed in
#278 ?

[bigludo7]

Hi @HuubAppelboom - for me it is fixed in #278
I merge it and let see

[bigludo7]

LGTM - Thanks @HuubAppelboom

[HuubAppelboom]

@fernandopradocabrillo @maxl2287 Can you please review this PR as well?