Tokens Bearer

Format des tokens Bearer, modèle de stockage SHA-256, TTL, chemin de validation, rotation, révocation et format du header Authorization pour VantagePeers.

Tokens Bearer

Les tokens Bearer sont les identifiants principaux pour tous les appels au serveur MCP VantagePeers. Cette page couvre le format des tokens, le modèle de sécurité, le chemin de validation et comment effectuer une rotation ou une révocation.

Format du token

Un token Bearer VP est une chaîne hexadécimale minuscule de 64 caractères générée à partir de 32 octets cryptographiquement aléatoires :

a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890

Génération :

const rawBytes = new Uint8Array(32)
crypto.getRandomValues(rawBytes)
const bearer = Array.from(rawBytes).map(b => b.toString(16).padStart(2, '0')).join('')

Modèle de stockage

À l'émission :

1. 32 octets aléatoires sont générés.
2. sha256(token_brut) est calculé sous forme de chaîne hex 64 caractères.
3. Le hash est écrit dans userBearerTokens.tokenHash (flux Clerk) ou oauth_access_tokens.tokenHash (flux OAuth).
4. Le token brut est retourné dans le corps de la réponse HTTP et supprimé côté serveur.

Durée de vie des tokens

Chemin de validation

Quand le serveur MCP reçoit une requête avec Authorization: Bearer <token> :

1. La valeur brute du token est extraite du header.
2. sha256(token) est calculé.
3. Le hash est recherché dans Convex via l'index by_token_hash sur userBearerTokens (tokens Clerk) ou by_tokenHash sur oauth_access_tokens (tokens OAuth).
4. Si trouvé : vérification du flag revoked et de l'horodatage expiresAt.
5. Si tous les contrôles passent : la requête est autorisée.

Référence source : mcp-server/src/auth.ts:275 — recherche Bearer sha256 via l'index by_token_hash.

Le token BEARER_SECRET_MASTER suit un chemin plus simple : comparaison de chaîne en temps constant contre la valeur de la variable d'environnement (sans accès base de données).

Format du header

Toutes les requêtes au serveur MCP doivent inclure :

Authorization: Bearer <token-hex-64-chars>

Exemple :

GET /health HTTP/1.1
Host: votre-déploiement.railway.app
Authorization: Bearer a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890

Pour la configuration .mcp.json de Claude Code :

{
  "mcpServers": {
    "vantage-peers": {
      "type": "http",
      "url": "https://votre-déploiement.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer votre-secret-bearer"
      }
    }
  }
}

BEARER_SECRET_MASTER

BEARER_SECRET_MASTER est le token master admin. Il :

• Est défini comme variable d'environnement sur le serveur MCP (variables d'env Railway ou équivalent)
• Sert aux opérations admin : provisionnement de clients OAuth, contrôle d'émission de tokens, mutations admin Convex
• Est validé par comparaison en temps constant (sans accès base de données) pour prévenir les attaques temporelles
• Est requis pour toutes les mutations admin de oauth.ts (createClient, listClients, deleteClient, seedDefaultProfiles)

Procédure de rotation de BEARER_SECRET_MASTER

1. Générez un nouveau secret : openssl rand -hex 32
2. Mettez à jour BEARER_SECRET_MASTER dans les variables d'environnement Railway (ou votre hôte MCP).
3. Redémarrez le processus MCP pour prendre en compte la nouvelle valeur.
4. Mettez à jour les comptes de service ou automatisations qui utilisent le token master.
5. L'ancienne valeur est immédiatement invalide une fois la variable d'env mise à jour et le processus redémarré.

Révoquer un token émis par Clerk

Il n'existe pas d'endpoint API pour révoquer des tokens individuels émis par Clerk en V0.0.2. Pour révoquer :

1. Contactez votre admin VP ou utilisez le tableau de bord Convex pour mettre directement userBearerTokens.revoked = true pour le tokenHash correspondant.
2. Le token échouera à la validation à la prochaine requête une fois revoked: true.

Un endpoint de révocation est prévu pour V0.0.3.

Révoquer un token OAuth

Les tokens OAuth sont révoqués via la mutation deleteClient dans oauth.ts, qui définit revokedAt sur l'enregistrement client et tous les tokens d'accès/rafraîchissement associés :

// Appel admin — requiert BEARER_SECRET_MASTER
oauth.deleteClient({ callerToken: masterToken, clientId: 'votre-client-id' })

Cela révoque le client et tous ses tokens atomiquement. Le client doit se ré-enregistrer via DCR pour obtenir de nouveaux identifiants.

Sources d'émission des tokens