# Banking setup — Powens (AISP) en dev local

> Version : 0.1 · 2026-05-12

L'intégration banking utilise [Powens](https://www.powens.com/) (ex-Budget Insight) comme **agrégateur AISP** (Account Information Service Provider). On lit les transactions des comptes pros de l'user pour détecter les virements entrants et matcher avec les factures émises. **Lecture seule** — Rubis ne déplace jamais d'argent.

## Architecture du flux

```
[Front /parametres]
   │  POST /api/v1/banking/powens/init
   ▼
[API] crée/récupère le user Powens de l'org
       génère un code temporaire
       renvoie webviewUrl
   │
   ▼
[Powens webview] user choisit sa banque + se logue
   │
   ▼  redirige sur POWENS_REDIRECT_URI
[API] /api/v1/banking/powens/callback
       valide le state HMAC
       fetch la connection, accounts, transactions
       302 vers WEB_URL/parametres/banque?banking=connected
   │
   ▼
[Front] poll /banking/connections, affiche la banque connectée
```

Webhook Powens (`POST /api/v1/webhooks/powens`) garde les transactions fraîches sans cron lourd.

## Pourquoi un tunnel HTTPS en dev

Powens **refuse** les redirect_uri en `http://` ou sur `localhost`. Il faut une URL HTTPS publique whitelistée dans la console Powens. En dev local, on monte un tunnel **Cloudflare Quick Tunnel** (gratuit, sans compte, sans config DNS).

## 1. Compte Powens sandbox

1. Crée un compte sur https://console.powens.com/
2. Demande un domaine **sandbox** (gratuit, banques fakes, pas de SCA réelle).
3. Récupère :
   - `client_id` (entier)
   - `client_secret` (string)
   - Le **slug** du domaine (ex : `rubis-sandbox`). L'API tape sur `https://<slug>.biapi.pro/2.0/`.
4. Génère un **webhook secret** dans la console (sera utilisé pour la vérif HMAC).

Renseigne dans `apps/api/.env` :

```bash
BANKING_ENABLED=true
BANKING_PROVIDER=powens
POWENS_DOMAIN=rubis-sandbox
POWENS_API_BASE_URL=https://rubis-sandbox.biapi.pro/2.0/
POWENS_CLIENT_ID=...
POWENS_CLIENT_SECRET=...
POWENS_WEBHOOK_SECRET=...
```

## 2. Tunnel HTTPS — Cloudflare Quick Tunnel

### Installer `cloudflared`

```bash
brew install cloudflared            # macOS
# ou : https://github.com/cloudflare/cloudflared/releases
```

### Lancer le tunnel sur l'API Adonis (port 3333)

```bash
cloudflared tunnel --url http://localhost:3333
```

Sortie attendue :

```
+--------------------------------------------------------------------------------------------+
|  Your quick Tunnel has been created! Visit it at (it may take a few moments to be reachable):  |
|  https://random-name-here.trycloudflare.com                                                |
+--------------------------------------------------------------------------------------------+
```

Copie cette URL.

### Renseigner `POWENS_REDIRECT_URI`

Dans `apps/api/.env` :

```bash
POWENS_REDIRECT_URI=https://random-name-here.trycloudflare.com/api/v1/banking/powens/callback
```

Redémarre `pnpm dev:api` pour prendre la nouvelle valeur.

### Whitelister l'URL côté Powens

Console Powens → ton appli → **Allowed redirect URIs** → ajoute :

```
https://random-name-here.trycloudflare.com/api/v1/banking/powens/callback
```

Et l'URL prod (à ajouter dès qu'on déploie) :

```
https://app.rubis.pro/api/v1/banking/powens/callback
```

### Whitelister l'URL webhook

Même console → **Webhooks** → ajoute :

```
https://random-name-here.trycloudflare.com/api/v1/webhooks/powens
```

> ⚠️ L'URL Cloudflare Quick Tunnel **change à chaque restart** du `cloudflared`. Faut re-whitelister et update le `.env` à chaque session. Pour du long terme, prendre un ngrok payant (~10$/mois, URL stable) ou monter un Cloudflare Tunnel nommé avec un domaine perso.

## 3. Tester de bout en bout (sandbox)

1. SPA → `/parametres` → section **Banque** → clic **Connecter une banque**.
2. Webview Powens s'ouvre → choisir **Connecteur de test** (banque sandbox).
3. Credentials sandbox standards : login `1234567`, password `123456` (à confirmer sur la doc Powens du moment).
4. Validation → Powens redirige vers ton tunnel → API enregistre la connexion → 302 vers `/parametres/banque?banking=connected`.
5. Vérifier que `bank_connections` a une ligne `state='active'` et que `bank_accounts` contient les comptes du connecteur de test.

## 4. Prod

- Domaine Powens prod (KYC à valider).
- `POWENS_REDIRECT_URI=https://app.rubis.pro/api/v1/banking/powens/callback`.
- `POWENS_API_BASE_URL=https://<slug-prod>.biapi.pro/2.0/`.
- Webhook URL whitelistée : `https://app.rubis.pro/api/v1/webhooks/powens`.

## 5. Gating plan

Le module banking est **réservé aux plans Pro et Business**. Le middleware `requirePaidPlan` sur les routes `/banking/*` renvoie `403` pour les comptes Free. La section banking dans la SPA affiche un upsell pour les Free.

## 6. Sécurité — résumé

- `powens_token` chiffré au repos via `app/services/encryption` (clé `APP_KEY`).
- State HMAC signé sur la webview, vérifié au callback (anti-CSRF).
- Webhook HMAC (`POWENS_WEBHOOK_SECRET`) vérifié avant tout traitement.
- Scope par org : un `connection_id` est toujours filtré par `auth.user.organizationId` (anti-IDOR).
- IBAN masqué dans les logs (`FR76 **** **** **** 1234`).
- Rate limit sur `/banking/powens/init` (anti-abuse).