Commit 5884e669 authored by Dimitrios Gogos's avatar Dimitrios Gogos
Browse files

fix: renumber EWBI OAuth2 ADR from 0038 to 0042 

develop independently claimed ADR-0038 for device-targeted control-path
resolution (and 0039-0041) while this branch was in flight. Rebasing
surfaced the collision; the EWBI auth ADR moves to the next free slot
(0042) and all cross-references are updated to match.
parent f8128de7

decisions/0016-fm-python-fastapi-stack.md

+2 −2
Changes for decisions/0016-fm-python-fastapi-stack.md: 2 added lines, 2 removed lines.
Original line number Diff line number Diff line
@@ -28,7 +28,7 @@ exception; (b) FM follows the platform stack — a single Python/FastAPI service 
Option (b). FM is one Python/FastAPI service like every other OOP component, following the same

hexagonal `python-template` layout and importing oop-commons. Nginx (already in front of every

service) terminates HTTPS and routes the canonical EWBI path to FM. OAuth2 Client-Credentials is

the current EWBI authorization mechanism (ADR-0038); `httpx` handles outbound token acquisition

the current EWBI authorization mechanism (ADR-0042); `httpx` handles outbound token acquisition

and Bearer-authenticated partner calls. There is no Envoy sidecar and no Go control plane.



## Consequences
@@ -36,5 +36,5 @@ and Bearer-authenticated partner calls. There is no Envoy sidecar and no Go cont 
Single-language stack: shared Pydantic models, shared auth/logging/health middleware, shared

developer knowledge; one deployable, one scaling model (stateless horizontal pods). Cost: FM does

not get Envoy's policy/filter machinery, so Bearer-token validation and header stripping are FM

application code and require security tests. If mTLS sender-binding is added later (ADR-0038),

application code and require security tests. If mTLS sender-binding is added later (ADR-0042),

revisit whether its revocation and rotation policy still fits Nginx + FastAPI.

fm/implementation-and-delivery.md

+6 −6
Changes for fm/implementation-and-delivery.md: 6 added lines, 6 removed lines.
Original line number Diff line number Diff line
@@ -281,7 +281,7 @@ class RoutingResolver: 


| Module | FM Usage |

|---|---|

| `auth/` | `require_role("operator")` on internal admin routes. EWBI routes use OAuth2 Client-Credentials + JWT against the `federation` Keycloak realm (ADR-0038), not mTLS. |

| `auth/` | `require_role("operator")` on internal admin routes. EWBI routes use OAuth2 Client-Credentials + JWT against the `federation` Keycloak realm (ADR-0042), not mTLS. |

| `db/` | SQLAlchemy async session management for `fm_db`. PostgreSQL connection pooling. |

| `events/` | DataBus publish/subscribe helpers. `CommandEnvelopeV1` and per-subject payload schemas for `command.srm.*` publishing. `SrmOperationCompletedV1` / `SrmOperationStatusV1` for consumption. |

| `health/` | `/healthz` and `/readyz` endpoint registration. Readiness checks PostgreSQL, DataBus. |
@@ -289,7 +289,7 @@ class RoutingResolver: 
| `models/` | Shared domain models. |

| `testing/` | Test fixtures — fake tokens, mock DataBus, shared helpers. |



### P.3 EWBI Authorization Implementation (ADR-0038)

### P.3 EWBI Authorization Implementation (ADR-0042)



FM authorizes E/WBI requests with OAuth2 Client-Credentials + signed JWT. Our Keycloak `federation` realm issues tokens for inbound partner calls; each partner's Authorization Server issues tokens for calls from our FM to that partner. FastAPI dependencies validate inbound Bearer tokens; `httpx` fetches and caches outbound tokens.
@@ -315,7 +315,7 @@ class HttpxEwbiClient: 
        )

```



### P.3.1 Future: mTLS Defense-in-Depth (deferred, ADR-0038)

### P.3.1 Future: mTLS Defense-in-Depth (deferred, ADR-0042)



Not built yet, and not required for a request to be authorized today. Once Nginx performs real mTLS termination (ADR-0016's original assumption), this layers back in as sender-constrained tokens (RFC 8705), binding a partner's JWT to their TLS client certificate:
@@ -329,10 +329,10 @@ The current schema deliberately contains no thumbprint or client-certificate ide 


| Boundary | Mechanism | Owner |

|---|---|---|

| Partner OP → Nginx → FM (EWBI) | OAuth 2.0 Client-Credentials + signed JWT (Keycloak realm `federation`, `fed-mgmt` scope) — ADR-0038. mTLS deferred defense-in-depth, not required today. | FM |

| Partner OP → Nginx → FM (EWBI) | OAuth 2.0 Client-Credentials + signed JWT (Keycloak realm `federation`, `fed-mgmt` scope) — ADR-0042. mTLS deferred defense-in-depth, not required today. | FM |

| Operator → FM (internal admin) | OAuth 2.0 Bearer JWT (Keycloak realm `oop`, `operator` role) | FM via oop-commons |

| FM → SRM (internal HTTP) | Cluster network trust initially; service JWT when available | Platform deployment |

| FM → Partner OP (outbound EWBI) | OAuth 2.0 Client-Credentials — FM as client, per-partner credentials (ADR-0038). mTLS with our client certificate deferred. | FM |

| FM → Partner OP (outbound EWBI) | OAuth 2.0 Client-Credentials — FM as client, per-partner credentials (ADR-0042). mTLS with our client certificate deferred. | FM |



### Q.2 Data Protection
@@ -362,7 +362,7 @@ The current schema deliberately contains no thumbprint or client-certificate ide 


| Threat | Mitigation |

|---|---|

| Unauthorized partner impersonation | OAuth2 Client-Credentials + signed JWT validation (`fed-mgmt` scope, Keycloak `federation` realm); RFC 8705 sender-binding may layer in later (ADR-0038) |

| Unauthorized partner impersonation | OAuth2 Client-Credentials + signed JWT validation (`fed-mgmt` scope, Keycloak `federation` realm); RFC 8705 sender-binding may layer in later (ADR-0042) |

| DDoS from partner or internet | Nginx IP whitelisting + per-partner rate limiting |

| Topology leakage | Mandatory topology-hiding middleware (applying the `TopologyHider` rules) + automated security tests |

| Internal header injection via EWBI | FM strips all `X-Internal-*` headers from inbound requests before processing |

fm/overview-and-architecture.md

+6 −6
Changes for fm/overview-and-architecture.md: 6 added lines, 6 removed lines.
Original line number Diff line number Diff line
@@ -71,7 +71,7 @@ FM maps to **OPG.02 v10.0 §3.3.4 (Federation Functions)** — specifically: 
| §3.3.4.2 Edge API Federation Management | Resource catalogue sync, edge node sharing |

| §3.3.4.3 Network Communication Service API Federation Management | URSP (UE Route Selection Policy) rule exchange (future) |

| §3.3.4.4 EWBI API Gateway | Inbound EWBI termination, partner provisioning |

| §3.3.4.5 EWBI Authentication and Authorization | OAuth2 Client-Credentials today; mTLS sender-binding is deferred (ADR-0038) |

| §3.3.4.5 EWBI Authentication and Authorization | OAuth2 Client-Credentials today; mTLS sender-binding is deferred (ADR-0042) |



FM also implements parts of the **Common Functions** related to federation routing (§3.3.2.4 API Call Routing — routing based on UE (User Equipment) IP/MSISDN/User Identity Token in federation environments).
@@ -84,8 +84,8 @@ There are two success definitions: 


| Area | Current architecture position |

|---|---|

| **EWBI termination** | Terminate inbound EWBI HTTPS requests routed via Nginx under the OPG.04 server prefix `/operatorplatform/federation/v1/*`. Client mTLS is a future defense-in-depth layer (ADR-0038), not required today. |

| **Partner authentication** | OAuth2 Client-Credentials + signed JWT. Our Keycloak `federation` realm issues inbound tokens; each target partner's Authorization Server issues outbound tokens. FM validates `fed-mgmt` and maps inbound `azp` to the partner profile (ADR-0038). |

| **EWBI termination** | Terminate inbound EWBI HTTPS requests routed via Nginx under the OPG.04 server prefix `/operatorplatform/federation/v1/*`. Client mTLS is a future defense-in-depth layer (ADR-0042), not required today. |

| **Partner authentication** | OAuth2 Client-Credentials + signed JWT. Our Keycloak `federation` realm issues inbound tokens; each target partner's Authorization Server issues outbound tokens. FM validates `fed-mgmt` and maps inbound `azp` to the partner profile (ADR-0042). |

| **Federation agreement enforcement** | Check that the requesting partner has a valid agreement before routing any request. |

| **Outbound federation routing** | Resolve target partner from user identifiers (MSISDN — Mobile Station International Subscriber Directory Number — prefix, IP CIDR — Classless Inter-Domain Routing block) via routing table. Forward requests over EWBI to partner OPs. |

| **Inbound request dispatch** | Map OPG.04 `InstallApp`/`RemoveApp` and supported Service API operations to `command.srm.*` with `source=federation` and `federation_partner_ref` (ADR-0001). OPG.04 v1.4.0 defines no application-scale operation. |
@@ -323,7 +323,7 @@ An operator onboards, updates, or decommissions a federation partner. 
- **Service/resource catalogue authority** — owned by SRM. FM reads via internal HTTP.

- **Capacity accounting and reservation** — owned by SRM. FM calls `POST /internal/capacity-check` for pre-flight validation.

- **User consent management** — consent enforcement is OEG's responsibility. Consent forwarding over EWBI is future scope per OPG.02 v10.0 §4.2.2.1.

- **mTLS sender-binding** — deferred defense-in-depth; no certificate identity fields or thumbprint lookup exist in the current path (ADR-0038).

- **mTLS sender-binding** — deferred defense-in-depth; no certificate identity fields or thumbprint lookup exist in the current path (ADR-0042).



### Boundaries
@@ -353,11 +353,11 @@ Per the component boundary matrix: 
| ID | Assumption | Risk if Wrong | Mitigation |

|---|---|---|---|

| F1 | Commercial federation agreements exist before a partner OP is technically onboarded. | FM processes requests from unauthorized partners. High risk. | FM validates agreement status on every inbound request. Onboarding is gated by agreement creation. |

| F2 | *(Deferred, ADR-0038)* A mutually trusted Certificate Authority (CA) exists, or public keys are pre-exchanged between federated OPs, for the future mTLS defense-in-depth layer. Not required for EWBI authorization today — see F6. | mTLS fails; no defense-in-depth once added. Low risk while deferred. | Document certificate exchange process for when mTLS is layered in. Support both CA-signed and pre-exchanged certificate models. |

| F2 | *(Deferred, ADR-0042)* A mutually trusted Certificate Authority (CA) exists, or public keys are pre-exchanged between federated OPs, for the future mTLS defense-in-depth layer. Not required for EWBI authorization today — see F6. | mTLS fails; no defense-in-depth once added. Low risk while deferred. | Document certificate exchange process for when mTLS is layered in. Support both CA-signed and pre-exchanged certificate models. |

| F3 | SRM exposes stable internal HTTP endpoints (`/internal/capacity-check`, `/internal/zones`, `/internal/network-queries/location`, `/internal/network-queries/device-status`) that FM can call. | FM cannot validate capacity, sync catalogues, or fulfill synchronous federated queries. Medium risk. | Shared internal API contract via oop-commons. |

| F4 | DataBus is available with `OOP_TASKS` and `OOP_EVENTS` streams configured. | Federation dispatch blocked. High risk. | Streams created at startup. FM persists transaction state in PostgreSQL as fallback for tracking. |

| F5 | EWBI APIs follow OPG.04 v6.0 standards, including the Sec. 9 OAuth2 Client-Credentials contract. Partner OPs implement compatible EWBI endpoints and run their own OAuth2 Authorization Server per Sec. 9.2. | Interoperability failures with partners. High risk. | Contract tests against OPG.04 OpenAPI specs. Mock partner OP for testing. |

| F6 | The platform's centralized Keycloak is available, with a `federation` realm for inbound EWBI partner OAuth2 Client-Credentials (ADR-0038) in addition to the `oop` realm for internal operator authentication. | New token issuance stops. FM fails closed when a token cannot be validated; cached JWKS may permit existing unexpired tokens temporarily. Outbound token acquisition from partner Authorization Servers is independent. | Keycloak is core platform infrastructure; monitor realm/JWKS availability and use short token lifetimes. |

| F6 | The platform's centralized Keycloak is available, with a `federation` realm for inbound EWBI partner OAuth2 Client-Credentials (ADR-0042) in addition to the `oop` realm for internal operator authentication. | New token issuance stops. FM fails closed when a token cannot be validated; cached JWKS may permit existing unexpired tokens temporarily. Outbound token acquisition from partner Authorization Servers is independent. | Keycloak is core platform infrastructure; monitor realm/JWKS availability and use short token lifetimes. |



---

fm/requirements-and-design.md

+2 −2
Changes for fm/requirements-and-design.md: 2 added lines, 2 removed lines.
Original line number Diff line number Diff line
@@ -18,7 +18,7 @@ status: "ETSI SDG OOP" 


| ID | Requirement | Spec Reference |

|---|---|---|

| REQ-FED-01 | The system shall authorize all EWBI requests via OAuth2 Client-Credentials with signed JWTs (JWS). For inbound calls, partners obtain tokens from our Keycloak `federation` realm and FM validates `fed-mgmt`/`fed-mgmt-notif`; for outbound calls, FM obtains a token from the target partner's Authorization Server using that partner relationship's client registration. mTLS is deferred defense-in-depth — see ADR-0038. | OPG.04 v6.0 §9; OPG.02 v10.0 §3.3.4.5/§4.2.3 (mTLS, deferred) |

| REQ-FED-01 | The system shall authorize all EWBI requests via OAuth2 Client-Credentials with signed JWTs (JWS). For inbound calls, partners obtain tokens from our Keycloak `federation` realm and FM validates `fed-mgmt`/`fed-mgmt-notif`; for outbound calls, FM obtains a token from the target partner's Authorization Server using that partner relationship's client registration. mTLS is deferred defense-in-depth — see ADR-0042. | OPG.04 v6.0 §9; OPG.02 v10.0 §3.3.4.5/§4.2.3 (mTLS, deferred) |

| REQ-FED-02 | The system shall strip all internal IP addresses, Kubernetes cluster names, namespace names, pod UIDs, node names, and internal trace IDs from every response and event payload before it crosses the operator boundary via EWBI. | OPG.02 v10.0 §4.2.3 |

| REQ-FED-03 | The system shall route inbound and outbound federation requests to the correct partner OP based on end-user identifiers (MSISDN prefix, IP CIDR block) or explicit zone/resource identifiers, using PostgreSQL as the authoritative routing table source. | OPG.02 v10.0 §3.3.2.4; OPG.10 v2.0 |

| REQ-FED-04 | The system shall synchronize directed zone/catalogue state through OPG.04 `CreateFederation` offered zones, partner-status callbacks, `ZoneSubscribe`/`ZoneUnsubscribe`, and `GetZoneData`/`GetZoneDetails`, storing opaque partner identifiers and explicit local-zone mappings in `shared_resource_catalogues`. | OPG.02 v10.0 §3.3.4.2; OPG.04 v6.0 OpenAPI v1.4.0 |
@@ -293,7 +293,7 @@ Nginx routes that prefix unchanged to FM. FM shall not replace the standard path 
`/ewbi/v1/management/*` or `/ewbi/v1/service/*` aliases. The contract's root security requirement

lists `oAuth2ClientCredentials`/`fed-mgmt` or `notifClientCredentials`/`fed-mgmt-notif`; FM uses

`fed-mgmt` for initiating API calls, while callback definitions explicitly use `fed-mgmt-notif`.

See ADR-0038.

See ADR-0042.



#### Priority Federation-Management Operations

platform/architecture.md

+2 −2
Changes for platform/architecture.md: 2 added lines, 2 removed lines.
Original line number Diff line number Diff line
@@ -705,7 +705,7 @@ These decisions are **binding** — they have been made and should not be reopen 
**What it is not:** FM does not expose APIs to developers. It does not fulfill requests itself — it publishes commands to the DataBus, and SRM handles fulfillment. FM does not import TF-SDK.



**Key design patterns:**

- **EWBI gateway:** Single Python/FastAPI service (ADR-0016). Inbound authorization uses OAuth2 Client-Credentials + signed JWT from the platform's dedicated Keycloak `federation` realm; outbound authorization uses a token issued by each target partner's Authorization Server (ADR-0038). Nginx terminates HTTPS and routes `/operatorplatform/federation/v1/*` to FM, whitelists partner IPs, and strips internal headers; client-certificate mTLS is deferred defense-in-depth.

- **EWBI gateway:** Single Python/FastAPI service (ADR-0016). Inbound authorization uses OAuth2 Client-Credentials + signed JWT from the platform's dedicated Keycloak `federation` realm; outbound authorization uses a token issued by each target partner's Authorization Server (ADR-0042). Nginx terminates HTTPS and routes `/operatorplatform/federation/v1/*` to FM, whitelists partner IPs, and strips internal headers; client-certificate mTLS is deferred defense-in-depth.

- **Topology hiding:** Mandatory removal of all internal IPs, cluster names, namespace names, and trace IDs before any response crosses the operator boundary.

- **Same fulfillment pipeline:** FM publishes the same `command.srm.*` commands as OEG, with `source=federation` and `federation_partner_ref` set. SRM treats them identically.

- **Charging integration:** FM can emit federation usage records toward the operator-controlled charging system (OPG.02 §4.3.3); financial settlement itself is outside FM.
@@ -778,7 +778,7 @@ These decisions are **binding** — they have been made and should not be reopen 
| Boundary | Mechanism | Owner |

|----------|-----------|-------|

| App Provider → Nginx → OEG | OAuth 2.0 Bearer JWT (Keycloak realm `oop`) | OEG via oop-commons |

| Partner OP → Nginx → FM | OAuth 2.0 Client-Credentials + signed JWT (Keycloak realm `federation`, `fed-mgmt` scope) — ADR-0038. mTLS deferred defense-in-depth. | FM |

| Partner OP → Nginx → FM | OAuth 2.0 Client-Credentials + signed JWT (Keycloak realm `federation`, `fed-mgmt` scope) — ADR-0042. mTLS deferred defense-in-depth. | FM |

| OEG → SRM | Internal service call (cluster network trust Phase 1; service JWT Phase 2) | Platform deployment |

| SRM → TF-SDK | In-process library call (no auth boundary) | N/A |

| TF-SDK → NEF | 3GPP OAuth2 or mTLS | TF-SDK adapter config |