docs: add visibility control documentation and workflows

# Visibility Control

WORK IN PROGRESS

 No newline at end of file

## Overview

The Visibility Control API is a Helper service within OpenCAPIF that allows API Providers and administrators to define fine-grained rules that determine whether specific APIs can be discovered and consumed by API Invokers.

Based on this, the discovery process returns only the APIs that the Invoker is authorized to access. This approach restricts visibility from the very beginning, ensuring the Invoker cannot even see unauthorized AEFs during discovery.

*Note: The first version of this API was merged with the staging branch (Release 4). The complete changes and evolution have been developed for **Release 5**.*

## Testing & Documentation References

* **Robot Tests Location:**  

  `/capif/tests/features/Helper/Visibility Control Api/visibility_control.robot`

* **Test Plan Documentation:**  

  Available at `doc/testing/testplan/visibility_control` in the `develop` branch on GitLab.

---

## Core Operations

### 1. Rules Management (API Provider)

**User Story:**  

As an API Provider, I want to define access control rules for my APIs, so that I can decide which API Invokers are allowed or denied to access.

**Acceptance Criteria:**

* The Provider can create, update, list, and delete access rules[cite: 1].

* Each rule includes filters (`providerSelector`, `invokerExceptions`), an `enabled` field, and a validity period (`startsAt`, `endsAt`)[cite: 1].

* The field `default_access` defines the default behavior (`ALLOW` or `DENY`)[cite: 1].

* The Helper validates Provider identity, the rule structure, time, and consistency overall.

* Only enabled and time-valid rules are enforced by the CCF.

#### Example: Rule Creation Request Payload

```json

{

  "providerSelector": {

    "createdByUser": "userA",

    "apiProviderId": [ "capif-prov-01", "capif-prov-02" ],

    "apiName": [ "apiName-001" ],

    "apiId": [ "apiId-001" ],

    "aefId": [ "aef-001" ]

  },

  "invokerExceptions": {

    "apiInvokerId": [ "invk-123", "invk-999" ]

  },

  "default_access": "ALLOW",

  "enabled": true

}

```

#### Rules Creation Sequence Diagram

```mermaid

sequenceDiagram

    participant Provider as API Provider

    participant Helper as Helper

    participant DB as RulesDB

    Provider->> Helper: 1. POST /rules (rule body)

    Helper-->>Helper: 2. Verify Provider Identity

    Helper-->>Helper: 3. Data validation

    Helper-->>Helper: 4. Time validity (e.g. startsAt < endsAt)

    alt Rule invalid

        Helper-->>Provider: 400 Bad Request (validation errors)

    else Rule valid

        Helper->>DB: 5. Store rule in RulesDB

        DB-->>Helper: ruleId + timestamps

        Helper-->>Provider: 201 Created (ruleId + metadata)

    end

```

---

### 2. Access Decision (API Invoker)

**User Story:**  

As an API Invoker, I want to discover APIs published by Providers, but I will discover only those that I am authorized to see according to the Provider/Admin’s rules.

**Acceptance Criteria & Decision Workflow:**  

When sending a Service API Discovery Request, the CCF executes the following process:

1. **Identity & Discovery Initiation:**

   * Verifies the identity of the Invoker.

   * Lists all published APIs.

   * *(Note: This first part is the current Discovery Process).*

2. **Decision Evaluation (`POST /decision/invokers/{apiInvokerId}/discoverable-apis`):**[cite: 1]

   * Fetches the list of rules (`GET /rules`) and filters out inactive ones (retains rules where `enabled=true` and `startsAt <= now < endsAt`)[cite: 1].

   * Filters the active rules that belong to the specific `apiInvokerId`[cite: 1].

   * Matches those rules against all published APIs.

   * Selects the `winnerRule` for each API based on the granularity of each rule.

3. **Enforcement:**

   * Checks whether the Invoker is explicitly allowed or denied.

   * **If allowed:** The API is included in the discovery response.

   * **If denied:** The API is not listed (or a `403 Forbidden` status is returned if invoked directly).

4. **Response:** Returns the final list of discoverable APIs[cite: 1].

#### Access Decision Sequence Diagram

```mermaid

sequenceDiagram

    actor Client as API Invoker

    participant Discovery as Discovery Service

    participant Visibility as Visibility Control

    participant DB as MongoDB

    Client->>Discovery: GET /discovered-apis

    Note over Discovery: Collect all published APIs

    Discovery->>Visibility: POST /decision/invokers/{id}/discoverable-apis

    Note over Discovery,Visibility: Send API list for filtering

    Visibility->>Visibility: Extract serviceAPIDescriptions

    Visibility->>DB: Get active visibility rules

    DB-->>Visibility: Rules list

    Visibility->>Visibility: Check active rules (enabled, expiration)

    Note over Visibility: For each API

    Visibility->>Visibility: Check rules matching

    Visibility->>Visibility: Check rules specificity

    Visibility->>Visibility: Apply ALLOW/DENY filter

    Visibility-->>Discovery: 200 OK + Filtered APIs

    Discovery->>Discovery: Update json_docs

    alt APIs found

        Discovery-->>Client: 200 OK + DiscoveredAPIs

    else No visible APIs

        Discovery-->>Client: 404 Not Found

    end

```

---

## API Endpoints & Response Summary

Below is a summary of the available endpoints, HTTP methods, descriptions, and possible response codes based on the OpenAPI specification:

| Endpoint | Method | Description | Output / Status Codes |

| :--- | :---: | :--- | :--- |

| `/rules` | `GET` | Retrieves a list of all defined visibility rules. | **200 OK**: JSON object containing an array of rules (`items`) and optional `nextPageToken`. |

| `/rules` | `POST` | Creates a new visibility rule (server generates `ruleId`). | **201 Created**: Returns created `Rule` object.<br>**400 Bad Request**: Invalid input/structure. |

| `/rules/{ruleId}` | `GET` | Retrieves details of a specific rule by ID. | **200 OK**: `Rule` object details.<br>**404 Not Found**: Rule does not exist. |

| `/rules/{ruleId}` | `PATCH` | Partially updates fields in an existing rule. | **200 OK**: Updated `Rule` object.<br>**400 Bad Request**: Invalid payload.<br>**404 Not Found**: Rule not found. |

| `/rules/{ruleId}` | `DELETE` | Removes a specific rule by ID. | **204 No Content**: Successfully deleted.<br>**404 Not Found**: Rule not found. |

| `/decision/invokers/{apiInvokerId}/discoverable-apis` | `GET` / `POST` | Evaluates and returns filtered discoverable APIs for the given invoker. | **200 OK**: `DiscoveredAPIs` list matching active rules.<br>**400 Bad Request**: Invalid parameters.<br>**404 Not Found**: Invoker not found. |

---