# Vérifier une clé de votre wakapp

> Protéger les routes de votre wakapp avec les clés wsk_ des organismes clients : introspection auprès de Wakastart, contrôle des droits et de l'organisme.

Quand un organisme client appelle l'API de votre wakapp avec une clé `wsk_`, votre wakapp demande à Wakastart ce que vaut cette clé : c'est l'**introspection**. Ce guide protège une route de votre wakapp par un droit, avec le kit Wakastart ou à la main.

:::important
Les clés API des wakapps sont en cours de déploiement : l'opération `POST /api/app-keys/introspect` ne répond pas encore. Ce guide décrit le fonctionnement prévu.
:::

## Avant de commencer

- Votre wakapp dispose de sa clé `sk_` dans un secret de son serveur (voir [Stocker une clé en sécurité](/v1.0/cles-api/stocker-une-cle-en-securite)). Elle doit appartenir au même environnement que les clés que vos clients présenteront.
- Votre catalogue de droits contient les droits que vos routes exigent, par exemple `formations.read` (voir [Définir les droits de votre application](/v1.0/droits-et-profils/definir-les-droits-de-votre-application)).
- Votre serveur tourne sous Node.js 20 ou plus si vous utilisez le kit.

```mermaid
sequenceDiagram
  participant SI as SI de l'organisme
  participant App as Votre wakapp
  participant WS as Wakastart
  SI->>App: GET /api/formations<br/>Authorization: Bearer wsk_…
  App->>WS: POST /api/app-keys/introspect<br/>x-api-key: sk_…  { secret }
  WS-->>App: { active: true, customer, rights, … }
  App->>App: droit « formations.read » présent ?
  App-->>SI: 200, formations de cet organisme seulement
```

## Appeler l'introspection

Envoyez le secret reçu dans le corps, et authentifiez l'appel avec la clé `sk_` de votre wakapp dans `x-api-key`, **sans en-tête `Authorization`**. Wakastart en déduit votre application et votre environnement.

```bash
curl -s -X POST "https://api.wakastart.app/api/app-keys/introspect" \
  -H "x-api-key: sk_test_exemple" \
  -H "Content-Type: application/json" \
  -d '{ "secret": "wsk_exemple3kTq9" }'
```

```ts
const res = await fetch("https://api.wakastart.app/api/app-keys/introspect", {
  method: "POST",
  headers: { "x-api-key": process.env.WAKASTART_API_KEY!, "Content-Type": "application/json" },
  body: JSON.stringify({ secret: "wsk_exemple3kTq9" }),
  signal: AbortSignal.timeout(5000),
});
const key = await res.json();
```

Réponse attendue pour une clé valide (`200`) :

```json
{
  "active": true,
  "key_id": "K7hq2P",
  "type": "TECHNICAL",
  "owner": null,
  "customer": { "wid": "ALPHA1", "name": "Organisme Alpha" },
  "app": "APPEX1",
  "env": "prod",
  "rights": ["formations.read", "participants.invite"],
  "exp": null
}
```

Pour toute autre clé, la réponse est `{ "active": false }`, toujours en `200` et sans autre champ : clé inconnue, révoquée, expirée, suspendue, d'une autre application, d'un autre environnement, ou dont l'organisme n'a plus l'application. N'essayez pas d'en deviner la raison.

Les champs sont décrits dans la [référence API](/v1.0/reference-api/cles-api#vérifier-une-clé). Retenez surtout :

- `rights` : les droits **effectifs**, déjà croisés avec les droits actuels de l'utilisateur pour une clé liée ;
- `customer` : l'organisme de la clé, auquel vous limitez toutes vos requêtes ;
- `key_id` : l'identifiant public de la clé, à écrire dans vos journaux à la place du secret.

## Appliquer la réponse

1. Refusez l'appel avec un `401` si `active` ne vaut pas `true`.
2. Refusez avec un `403` si un droit exigé par la route manque dans `rights`.
3. Limitez toutes vos lectures et écritures à `customer.wid`. L'organisme vient de la clé, **jamais d'un paramètre de la requête du client**.
4. Appliquez vos propres limites de débit par client et le cloisonnement de ses données : ils restent l'affaire de votre wakapp.

### Ne gardez aucune réponse positive en cache

Chaque appel d'un client entraîne une introspection : c'est ce qui rend la révocation immédiate. Vous pouvez en revanche garder une réponse **négative** une dizaine de secondes, indexée par l'empreinte SHA-256 du secret et jamais par le secret lui-même, pour ne pas relayer un essai de secrets en masse.

### Refusez quand Wakastart ne répond pas

Si l'introspection échoue (délai dépassé, erreur réseau, réponse inattendue), refusez l'appel du client avec un `503`. Ne laissez jamais passer une clé faute de réponse, et ne gardez pas cet échec en cache.

## Protéger une route avec le kit

Le kit `@wakastellar/wakastart-keys` fait l'introspection, applique ces règles de cache et protège vos routes par droit.

:::note
Le kit n'est pas encore publié sur npm. Il est fourni sous forme de module autonome, sans dépendance au reste de votre code, sur demande au [support Wakastart](/v1.0/support) : copiez-le dans votre backend. Les exemples importent le nom du futur paquet ; avec le module copié, remplacez-le par son chemin.
:::

| Entrée | Contenu | Dépendances |
|---|---|---|
| `@wakastellar/wakastart-keys` | Client, contexte, types, erreurs | Aucune |
| `@wakastellar/wakastart-keys/express` | Middleware `requireAppKey` | Aucune |
| `@wakastellar/wakastart-keys/nest` | Décorateur `RequireAppKey`, garde, module | `@nestjs/common`, `@nestjs/core`, `rxjs` |

Configurez-le par des variables d'environnement de votre serveur :

| Variable | Rôle | Défaut |
|---|---|---|
| `WAKASTART_API_URL` | URL de base de l'API publique, **sans** `/api` : `https://api.wakastart.app` | Obligatoire |
| `WAKASTART_API_KEY` | Clé `sk_` de votre wakapp. Jamais dans le code, jamais dans une variable exposée au navigateur | Obligatoire |
| `WAKASTART_APP_WID` | Facultatif : WID de votre application. Le kit refuse alors en plus toute clé dont l'introspection renvoie une autre application | — |
| `WAKASTART_TIMEOUT_MS` | Délai d'attente de chaque appel à Wakastart, en millisecondes | `5000` |

Sans `WAKASTART_API_URL` ou `WAKASTART_API_KEY`, toutes les clés sont refusées avec un `503` ; le reste de votre wakapp n'est pas affecté.

::::tabs{sync="framework"}
:::tab{label="NestJS"}
```ts
import { Controller, Get } from "@nestjs/common";
import { CurrentAppKey, RequireAppKey } from "@wakastellar/wakastart-keys/nest";
import type { AppKeyPrincipal } from "@wakastellar/wakastart-keys";

@Controller("formations")
export class FormationsController {
  constructor(private readonly formations: FormationsService) {}

  @Get()
  @RequireAppKey("formations.read")
  list(@CurrentAppKey() key: AppKeyPrincipal) {
    // Toujours limité à l'organisme de la clé
    return this.formations.findAll(key.customer.wid);
  }
}
```
:::
:::tab{label="Express"}
```ts
import { requireAppKey } from "@wakastellar/wakastart-keys/express";

app.get("/api/formations", requireAppKey("formations.read"), (req, res) => {
  res.json(listFormations(req.appKey.customer.wid));
});
```
:::
::::

`req.appKey` (ou `@CurrentAppKey()`) contient `wid`, `type`, `customer`, `rights`, `owner`, `app`, `env` et `exp`. Le secret n'y figure pas.

Le kit répond à vos clients ainsi :

| Cas | Statut | `message` |
|---|---|---|
| Pas d'en-tête `Authorization: Bearer` | `401`, avec `WWW-Authenticate: Bearer` | `APP_KEY_MISSING` |
| Clé inconnue, révoquée, expirée, d'une autre application ou d'un autre environnement | `401` | `APP_KEY_INVALID` |
| Droit manquant | `403`, avec `details.missing` | `APP_KEY_RIGHTS_MISSING` |
| Wakastart injoignable, délai dépassé, réponse inattendue | `503` | `WAKASTART_UNAVAILABLE` |

## Protéger une route sans le kit

Le contrat s'applique aussi à la main. Exemple de middleware Express :

```ts
import type { NextFunction, Request, Response } from "express";

export function requireAppKey(...required: string[]) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const auth = req.headers.authorization;
    if (!auth?.startsWith("Bearer ")) {
      return res.status(401).json({ statusCode: 401, message: "APP_KEY_MISSING" });
    }

    let key: { active: boolean; rights?: string[]; customer?: { wid: string } };
    try {
      const r = await fetch(`${process.env.WAKASTART_API_URL}/api/app-keys/introspect`, {
        method: "POST",
        // Clé sk_ de la wakapp, et surtout pas d'en-tête Authorization
        headers: { "x-api-key": process.env.WAKASTART_API_KEY!, "Content-Type": "application/json" },
        body: JSON.stringify({ secret: auth.slice(7) }),
        signal: AbortSignal.timeout(5000),
      });
      if (!r.ok) throw new Error(`Wakastart ${r.status}`);
      key = await r.json();
    } catch {
      // On refuse quand on ne peut pas vérifier
      return res.status(503).json({ statusCode: 503, message: "WAKASTART_UNAVAILABLE" });
    }

    if (key.active !== true) {
      return res.status(401).json({ statusCode: 401, message: "APP_KEY_INVALID" });
    }
    const missing = required.filter((code) => !key.rights!.includes(code));
    if (missing.length) {
      return res.status(403).json({ statusCode: 403, message: "APP_KEY_RIGHTS_MISSING", details: { missing } });
    }

    res.locals.appKey = key; // aucune mise en cache de cette réponse
    next();
  };
}
```

## Vérifier le résultat

Appelez votre route avec une clé de test qui porte le droit, puis sans le droit :

```bash
curl -s -o /dev/null -w "%{http_code}\n" "https://mon-app.exemple.fr/api/formations" \
  -H "Authorization: Bearer wsk_exemple3kTq9"
```

Réponse attendue : `200` avec la clé qui porte `formations.read`, `403` avec une clé qui ne le porte pas, `401` après la révocation de la clé dans la console.

## Bonnes pratiques

- Journalisez le `key_id`, jamais le secret ni son empreinte.
- N'envoyez la clé du client à Wakastart que dans le corps de l'introspection.
- Documentez pour vos clients l'en-tête attendu (`Authorization: Bearer <clé>`) et les droits de votre catalogue utiles à chaque route.

## Voir aussi

- [Proposer les clés dans votre wakapp](/v1.0/cles-api/proposer-les-cles-dans-votre-wakapp)
- [Agir sur Wakastart pour un client](/v1.0/cles-api/agir-sur-wakastart-pour-un-client)
- [Référence API : clés de votre wakapp](/v1.0/reference-api/cles-api#clés-api-de-votre-wakapp)
