feat: define token-type-dependent phoneNumber handling for registration POST /sessions (#158)

[deepakjaiswal1]

What type of PR is this?

Add one of the following kinds:

• feature

What this PR does / why we need it:

WebRTC registrations target softphones, which are decoupled from any SIM. As a result, a single deviceId can be associated with more than one phone number — for example, an enterprise activating one number from its pool on a user's device. This raises the question of how a specific number is selected at registration.

In the CAMARA model, an access token identifies at most one subscriber, and the way the subscriber's phoneNumber is determined depends on the type of token:

• A three-legged token carries the subscriber's identity, so the operator resolves the phoneNumber server-side.
• A two-legged token carries no subscriber identity, so the API consumer must state the phoneNumber explicitly.

Previously the spec only covered the three-legged case, leaving no way to register a specific number under a two-legged token.

Which issue(s) this PR fixes:

Fixes #158

Special notes for reviewers:

Strict handling of the identifier by token type:

• Three-legged token → phoneNumber MUST NOT be in the request body (resolved from the token); if present → 422 UNNECESSARY_IDENTIFIER.
• Two-legged token → phoneNumber MUST be in the request body; if omitted → 422 MISSING_IDENTIFIER.

Rejecting (rather than validating) a body phoneNumber under a three-legged token also prevents the endpoint from being used as an MSISDN lookup/verification oracle.

Changes in this PR: new optional phoneNumber in RegSessionRequest (references existing PhoneNumber schema, stays out of required); POST /sessions description updated; new 422 response CreateSessionUnprocessable422 (MISSING_IDENTIFIER, UNNECESSARY_IDENTIFIER) referenced from POST /sessions; uniqueness-constraint wording generalised for both token types.

Non-breaking: phoneNumber did not previously exist in the request body, so the new 422 rules cannot reject previously-valid requests. Existing (deviceId, phoneNumber) uniqueness and 409 ALREADY_EXISTS behaviour unchanged. Validated with OpenAPI 3.0.3 schema validation and Spectral (no new findings). Approach settled in the WG discussion on #158.

Changelog input

 release-note
feat(webrtc-registration): add optional phoneNumber to POST /sessions with strict token-type handling

Additional documentation

Reference: CAMARA Identity and Consent Management (Security & Interoperability Profile) — access-token types and server-side subscriber identity resolution.

[stroncoso]

Hi @deepakjaiswal1 ,

Please use the standarized template for PRs:

• What type of PR is this?
• What this PR does / why we need it:
• Which issue(s) this PR fixes:
• Special notes for reviewers:
  • Here you can add all the context required for understand the PR itself.
• Changelog input (key for release notes)
• Additional documentation (optional)

Now that we have an automated release process, we need to keep the PR descriptions on track with the official template.

Sorry for the extra work here 🙇

Thanks

[deepakjaiswal1]

@stroncoso I updated the PR description per CAMARA standard template.

Warm regards,
Deepak

[stroncoso]

Thanks @deepakjaiswal1 , but you close the PR on the way... Did you intended that?
The description was good and the examples also provide clarity.

If you reopen it, I can review and approve.

Thanks!

[deepakjaiswal1]

@stroncoso I have re-opened the PR.

[stroncoso]

LGTM. Thanks for your contribution!