Update multi-point-vpn to Commonalities 0.8.0 (Spring26) and consume common definitions by reference

[hdamker]

Problem description

The API currently targets Commonalities r3.4 (0.6.1), as declared in release-plan.yaml (commonalities_release) and info.x-camara-commonalities: 0.6.1. CAMARA Validation runs against the r3.4 linting ruleset, which does not include several checks present in the current r4.x (Spring26) ruleset, and the API redefines locally several schemas that Commonalities provides as common definitions. As a result, the r1.1 snapshot validates with 0 errors / 0 warnings while some Design Guide requirements are not met and common definitions are duplicated.

Possible evolution

Update the API to target Commonalities 0.8.0 (Spring26 / r4.x line): set commonalities_release in release-plan.yaml and info.x-camara-commonalities accordingly, adapt the definition to the r4.x design guidelines, and consume the common definitions by reference.

1. Consume common definitions via $ref

Commonalities 0.8.0 supports referencing the shared CAMARA_common.yaml (placed in code/common/) via $ref: "../common/CAMARA_common.yaml#/components/schemas/<SchemaName>". Common definitions should be referenced rather than redefined. In the current spec (line numbers refer to the r1.1 snapshot):

• ErrorInfo (line 313) duplicates the common ErrorInfo.
• Generic400 / Generic401 / Generic403 / Generic500 (lines 546, 579, 605, 630) duplicate common error responses. Commonalities provides the full set (400, 401, 403, 404, 405, 406, 409, 410, 412, 415, 422, 429, 500–504) for reference.
• x-correlator header and parameter (lines 220, 226) and the ^[a-zA-Z0-9-]{0,55}$ pattern duplicate the common x-correlator / XCorrelator definitions.
• The openId security scheme is available in the common file (the API currently defines no security scheme — see the separate security issue).
• IpAddress / Ipv4Address / Ipv6Address (lines 346, 357, 371) overlap with common IP-address types (e.g. SingleIpv4Address, DeviceIpv4Address, DeviceIpv6Address); the team should confirm the appropriate common type or an API-specific need.
• Duration (line 301) has no direct common equivalent (common provides DateTime and TimePeriod); confirm whether the duration concept maps to a common type or remains API-specific.

2. Expanded linting ruleset

Targeting r4.x brings the definition under the expanded ruleset, which adds the OWASP API Security Top 10 2023 rules (see Linting-rules.md). Effects on the current definition include:

• owasp:api2:2023-write-restricted (severity error) flags the four non-GET operations that have no security declaration: createNetwork, updateNetwork, deleteNetwork, assessConnectionFeasibility.
• owasp:api2:2023-read-restricted (severity warning) flags the GET operation getVpnConnection.
• Additional r4.x rules cover error codes, info.contact, tags, array maxItems, schema typing, and others.

Several items raised in the separate security/correctness issue would be detected automatically once the API targets the r4.x ruleset and references the common definitions.

Alternative solution

Remain on r3.4 for the alpha and schedule the move to r4.x and the adoption of common definitions before the release-candidate, where Commonalities compliance becomes a mandatory release asset.

Additional context

Updating the dependency, adopting common definitions by reference, and aligning the definition to the current guidelines are related parts of one migration. The immediate security and definition-correction items are tracked in their own issues.