# Infomaniak OAuth 2.0 Setup Guide

## Overview

This guide explains how to register an Infomaniak OAuth application so that PowerOn
users can connect their Infomaniak account as a data source. The connection
exposes two services in the Unified Data Bar:

- **kDrive** -- browse and download files from any drive accessible to the user.
- **Mail** -- browse mailboxes, folders, and download messages as `.eml`.

Infomaniak is a **data-only** authority in PowerOn. It is **not** a login
provider; users still authenticate against PowerOn via Local / Google / Microsoft.

## Prerequisites

- An Infomaniak account with admin rights to create API credentials.
- Access to the Infomaniak Manager (https://manager.infomaniak.com).
- The PowerOn gateway publicly reachable (or `http://localhost:8000` for development).

## Step 1: Create an Infomaniak API Application

1. Login to https://manager.infomaniak.com.
2. Navigate to your account icon (top right) > **API**.
3. Click **Create a new application**.
4. Fill in:
   - **Name:** PowerOn (or your project name)
   - **Description:** Data connector for kDrive + Mail
   - **Redirect URI:** must exactly match the gateway endpoint:
     - Development: `http://localhost:8000/api/infomaniak/auth/connect/callback`
     - Production:  `https://<gateway-host>/api/infomaniak/auth/connect/callback`
5. Select scopes:
   - `user_info` -- required to read `/1/profile` for `externalId` / `email`.
   - `kdrive`   -- required for the kDrive ServiceAdapter.
   - `mail`     -- required for the Mail ServiceAdapter.
6. Save and copy the generated **Client ID** and **Client Secret**.

## Step 2: Configure PowerOn Gateway

Add the following keys to your gateway environment file (e.g. `gateway/env_dev.env`):

```env
# Infomaniak OAuth -- Data App (kDrive + Mail)
Service_INFOMANIAK_DATA_CLIENT_ID = your-client-id
Service_INFOMANIAK_DATA_CLIENT_SECRET = your-client-secret
Service_INFOMANIAK_OAUTH_REDIRECT_URI = http://localhost:8000/api/infomaniak/auth/connect/callback
```

For production, replace the redirect URI with your HTTPS gateway host. The URI
must be identical (byte-for-byte) to the one registered in step 1.

Restart the gateway after editing the env file so `APP_CONFIG` is reloaded.

## Step 3: Verify the Flow

1. Login to PowerOn and open **Basisdaten > Verbindungen**.
2. Click **Infomaniak** in the header actions.
3. A popup opens against `https://login.infomaniak.com/authorize`.
4. Sign in with your Infomaniak account, grant the requested scopes.
5. The popup closes automatically and the new connection appears with status
   `connected`.
6. Open the **Unified Data Bar > Sources** tab; you should see the Infomaniak
   authority node with `kdrive` and `mail` services.

## Token Lifecycle

- Access tokens are short-lived (refresh handled automatically by
  `tokenRefreshService._refresh_infomaniak_token`).
- Refresh tokens are stored alongside the connection (`Token.tokenRefresh`).
- If a refresh returns `invalid_grant`, the user must reconnect (popup again
  via the Infomaniak button on `ConnectionsPage`).

## Troubleshooting

### `invalid_redirect_uri`
The URI registered on Infomaniak Manager does not match `Service_INFOMANIAK_OAUTH_REDIRECT_URI`.
They must be byte-identical (including protocol, host, port, and path).

### `invalid_client`
Client ID or secret in the env file does not match what Infomaniak issued.
Re-copy the values from Manager > API.

### Profile lookup returns 401
The `user_info` scope was not granted. Re-create the application with the
correct scope set, or reconnect the user.

### Empty kDrive listing
The user has no kDrives associated. Verify on https://kdrive.infomaniak.com
that at least one drive is accessible.

## Security Notes

- Never commit the client secret. Use the encrypted env mechanism described in
  `wiki/d-guides/encrypt-env-secrets.md`.
- Rotate the client secret if it leaks; update `Service_INFOMANIAK_DATA_CLIENT_SECRET`
  and restart the gateway. Existing tokens remain valid only until they expire.
- The connector is scoped to `DATA_CONNECTION` only. Even with valid Infomaniak
  credentials, no PowerOn login session is created.

## Reference

- Code: `gateway/modules/connectors/providerInfomaniak/connectorInfomaniak.py`
- OAuth route: `gateway/modules/routes/routeSecurityInfomaniak.py`
- Token refresh: `gateway/modules/auth/tokenManager.py::refreshInfomaniakToken`
- Frontend hook: `frontend_nyla/src/hooks/useConnections.ts::createInfomaniakConnectionAndAuth`