Supabase : le backend

Jusqu'ici, on a surtout regardé ce qui se passe dans le téléphone : des composants, de l'état, de la navigation. Mais une app de musculation qui oublierait tes entraînements dès que tu changes de téléphone ne servirait à rien. Il faut un endroit, ailleurs, qui se souvient. Cet endroit, c'est le backend, et dans Halterofit il s'appelle Supabase.

1. Qu'est-ce qu'un « backend », et pourquoi en faut-il un ?

Quand tu lances Halterofit, le code qui s'exécute sur ton téléphone — l'interface, les écrans, la logique d'un entraînement — c'est ce qu'on appelle le front-end (« le devant », ce que l'utilisateur voit et touche). Le back-end (« l'arrière »), c'est tout ce qui tourne ailleurs, sur des ordinateurs que tu ne vois jamais : des serveurs, dans un centre de données, quelque part dans le cloud. L'app de ton téléphone leur parle par Internet.

Pourquoi déporter du travail loin du téléphone ? Parce qu'un téléphone, tout seul, a trois grandes faiblesses, et chacune justifie l'existence d'un serveur :

• Il peut être perdu, cassé ou remplacé. Si tes 200 séances ne vivent que dans la mémoire du téléphone, le jour où tu le laisses tomber dans une flaque, tu perds tout. Un serveur garde une copie au chaud, dans le cloud.
• Il est seul. Tu installes l'app sur une tablette, ou tu changes pour un nouveau téléphone : comment retrouver tes données ? Elles doivent être stockées à un endroit central que n'importe lequel de tes appareils peut interroger après t'être identifié.
• Il n'a aucune notion de « qui es-tu ». Pour que tes données soient les tiennes — et pas mélangées à celles des autres utilisateurs — il faut un endroit qui sache vérifier ton identité (ton compte, ton mot de passe) et qui distribue les bonnes données à la bonne personne.

Une analogie : ton téléphone est comme un guichet de banque local, pratique et rapide ; mais l'argent réel n'est pas dans le guichet, il est dans le coffre central de la banque. Le guichet demande au coffre, le coffre vérifie ton identité et autorise (ou non) l'opération. Sans le coffre, un guichet n'est qu'une jolie boîte vide.

2. Qu'est-ce que Supabase ?

Construire un backend complet à la main — un serveur, une base de données, un système de comptes sécurisé, du stockage de fichiers — c'est énorme. Supabase est un produit qui te livre tout cet attirail déjà monté et géré, prêt à l'emploi. On le présente souvent comme « l'alternative open-source à Firebase » (le service équivalent de Google). « Open-source » signifie que son code est public : tu peux l'auto-héberger si tu veux, tu n'es pas prisonnier.

Le cœur de Supabase, c'est PostgreSQL — une base de données relationnelle très réputée, vieille de plusieurs décennies, solide et standard. « Relationnelle » veut dire que les données vivent dans des tables (comme des feuilles de calcul) qui se référencent les unes les autres. Autour de ce noyau Postgres, Supabase ajoute plusieurs briques :

• Auth — la gestion des comptes : inscription, connexion, mots de passe, sessions, vérification d'email. C'est lui qui sait « qui tu es ».
• Postgres — la base de données elle-même : tes tables, tes lignes, les relations entre elles.
• Storage — un espace pour stocker des fichiers volumineux (photos, vidéos) qui n'ont pas leur place dans des tables.
• Realtime — un canal « temps réel » qui pousse les changements vers les clients abonnés, via des websockets (une connexion permanente ouverte).
• Edge Functions — de petites fonctions de code que toi tu écris et qui s'exécutent sur les serveurs de Supabase, pour la logique sur-mesure.

Le point génial : tout ça est accessible depuis ton app via une seule bibliothèque JavaScript, @supabase/supabase-js. Tu écris du code JavaScript familier (supabase.auth.signIn(...), supabase.from('workouts').select()) et la bibliothèque traduit ça en requêtes réseau vers les serveurs. Tu n'as pas à apprendre un protocole réseau de bas niveau ; tu appelles des méthodes, comme pour n'importe quel objet.

3. Ce que Halterofit utilise vraiment (et ce qu'il évite)

Supabase offre beaucoup de briques, mais une app n'est pas obligée de toutes les prendre. Lire le projet, c'est aussi savoir quelles briques sont branchées. Voici la carte de Halterofit :

• Auth — oui, en plein : comptes, sessions, jetons (JWT). C'est le sujet du flux d'authentification, plus loin.
• Postgres — oui : sept tables synchronisées (utilisateurs, entraînements, exercices d'une séance, séries, plans, etc.) qui reflètent les données locales du téléphone.
• RLS (Row Level Security) — oui, et c'est central : des règles de sécurité dans la base qui garantissent que chacun ne voit que ses propres lignes.
• Edge Functions — oui, mais une seule : delete-account, pour supprimer définitivement un compte.
• RPC de synchro — oui : deux fonctions Postgres, pull_changes et push_changes, qui implémentent le protocole de synchronisation (on les détaille dans le module sur le traçage et la synchro).
• Realtime — non. Volontairement. Voir l'encadré ci-dessous.
• Storage — non : l'app ne stocke pas de fichiers/photos côté serveur pour l'instant.

4. Le client Supabase : le point d'entrée unique

Tout dialogue de l'app avec Supabase passe par un seul objet, le client. On le crée une fois, au démarrage, et tout le reste du code l'importe. Voici le vrai fichier qui le construit, dans Halterofit :

import { createClient, type SupabaseClient } from '@supabase/supabase-js';
import { mmkvStorage } from '@/services/storage/mmkvStorage';

// Les deux ingrédients viennent des variables d'environnement (section 5).
const supabaseUrl = process.env.EXPO_PUBLIC_SUPABASE_URL || '';
const supabaseAnonKey = process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY || '';

// Si l'URL OU la clé manque, on n'essaie même pas : le client vaut null.
// C'est le "repli hors-ligne" — l'app démarre quand même, sans auth/sync.
export const supabase: SupabaseClient | null =
  supabaseUrl && supabaseAnonKey
    ? createClient(supabaseUrl, supabaseAnonKey, {
        auth: {
          // Où ranger la session ? Dans MMKV (le stockage local rapide du tél.),
          // pour rester connecté entre deux ouvertures de l'app.
          storage: {
            getItem: (key) => mmkvStorage.get(key) ?? null,
            setItem: (key, value) => mmkvStorage.set(key, value),
            removeItem: (key) => mmkvStorage.delete(key),
          },
          autoRefreshToken: true,   // renouvelle tout seul le jeton qui expire
          persistSession: true,     // se souvient de la session au redémarrage
          detectSessionInUrl: false, // pas de session via l'URL (app mobile, pas web)
        },
      })
    : null;

if (!supabase) {
  console.warn('Supabase not configured — auth/sync unavailable.');
}

createClient(url, clé, options) fabrique l'objet par lequel tout passe. Remarque que la variable exportée a le type SupabaseClient | null : elle peut légitimement être null.

Trois choses méritent qu'on s'y arrête, parce qu'elles racontent des décisions d'ingénierie réelles.

• La session est rangée dans MMKV. Une « session » est la preuve que tu es connecté (concrètement, un jeton). En la persistant dans MMKV — le petit stockage local rapide du téléphone, vu dans le module sur la structure du projet — l'app se souvient de toi : tu n'as pas à te reconnecter à chaque ouverture. Au démarrage, Supabase relit cette session depuis MMKV.
• autoRefreshToken: true. Le jeton d'accès expire vite (souvent une heure), pour la sécurité. Plutôt que de te déconnecter brutalement, le client va, en coulisses, échanger un « jeton de rafraîchissement » contre un jeton neuf. Tu ne vois rien ; tu restes connecté. C'est autoRefreshToken qui orchestre ça automatiquement.
• Le repli null. Si les identifiants de connexion à Supabase manquent (par exemple sur une build de prévisualisation sans secrets configurés), le client vaut null au lieu de planter. L'app peut alors fonctionner en mode purement local. C'est pour ça que, dans tout le code d'auth, chaque opération commence par vérifier que le client existe.

function requireSupabase() {
  if (!supabase) {
    // Pas de client → on lève une erreur claire plutôt que de planter
    // mystérieusement plus loin sur "supabase is null".
    throw new AuthError('Authentication is not available', '...', 'AUTH_UNAVAILABLE');
  }
  return supabase; // ici, TypeScript sait que ce n'est plus null
}

5. Les clés et les variables d'environnement

Pour parler à ton projet Supabase (et pas à celui du voisin), le client a besoin de deux informations : l'URL de ton projet et une clé d'accès. Dans le code, on les lit ainsi :

const supabaseUrl = process.env.EXPO_PUBLIC_SUPABASE_URL || '';
const supabaseAnonKey = process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY || '';

process.env.XXX lit une variable d'environnement : une valeur définie en dehors du code (dans un fichier de config, dans les réglages de build), pas écrite en dur dans les sources. Pourquoi ? Pour ne pas figer des valeurs sensibles ou changeantes dans le code source, et pour pouvoir pointer vers un projet différent en développement et en production sans toucher une ligne. Le préfixe EXPO_PUBLIC_ est une convention d'Expo : il dit « cette variable a le droit d'être embarquée dans l'app livrée ».

Et c'est exactement là qu'il faut être très attentif, parce qu'il existe deux sortes de clés et qu'on ne les traite pas pareil :

6. RLS (Row Level Security) — la sécurité au niveau de la ligne

Voici, sans doute, le concept le plus important de tout ce module. Imagine la table workouts : elle contient tous les entraînements de tous les utilisateurs, ligne après ligne, chacune marquée d'un user_id. Quand ton app demande « donne-moi les entraînements », qu'est-ce qui empêche qu'on te renvoie aussi ceux des autres ?

La réponse est RLS : des règles écrites directement dans la base de données qui filtrent, ligne par ligne, ce que chaque utilisateur a le droit de lire ou d'écrire. « Row Level » = « au niveau de la ligne » : la permission ne se décide pas table par table, mais ligne par ligne, selon qui demande. Voici une vraie politique de Halterofit :

-- D'abord, on ACTIVE la sécurité au niveau ligne sur la table.
-- (sans ça, RLS ne s'applique pas du tout)
ALTER TABLE public.workouts ENABLE ROW LEVEL SECURITY;

-- Puis on écrit la RÈGLE. "FOR ALL" = pour lire, insérer, modifier, supprimer.
CREATE POLICY "Users see own workouts" ON public.workouts FOR ALL
  -- La condition magique : ne laisse passer QUE les lignes
  -- dont le user_id est égal à l'identité de celui qui demande.
  USING ((select auth.uid()) = user_id);

auth.uid() renvoie l'identifiant de l'utilisateur connecté, déduit de son jeton. Le motif auth.uid() = user_id est le cœur de toute la sécurité : « cette ligne t'appartient-elle ? ».

Lis bien le mécanisme. Quand ton app fait une requête, Postgres ajoute automatiquement la condition WHERE (select auth.uid()) = user_id à chaque accès à la table. Tu ne peux donc physiquement pas récupérer une ligne qui n'est pas la tienne : la base les filtre avant même que les données ne sortent. Et ce, quoi que fasse l'app. Même un client malveillant qui forgerait des requêtes ne contournerait rien, parce que le filtre vit dans la base, pas dans l'app.

Pour les tables « filles » (les exercices d'une séance, les séries d'un exercice), la propriété est héritée : une série t'appartient si elle appartient à un exercice qui appartient à un entraînement dont le user_id est le tien. La politique vérifie alors la chaîne avec un EXISTS, mais l'idée reste identique : remonter jusqu'au propriétaire et comparer à auth.uid().

7. Le flux d'authentification, bout à bout

On a maintenant toutes les pièces pour comprendre comment un utilisateur entre dans l'app. Le service d'auth de Halterofit centralise ces opérations dans un seul fichier (services/auth/index.ts) : signUp, signIn, signOut, resetPassword, la vérification d'email par code OTP, etc. Suivons le parcours d'une inscription, étape par étape :

1. Inscription. L'utilisateur saisit email + mot de passe. L'app appelle supabase.auth.signUp(...). Le serveur Auth crée le compte et renvoie un objet utilisateur.
2. Session et JWT. En échange, Supabase délivre une session, qui contient un JWT (JSON Web Token) — un petit jeton signé qui prouve « je suis cet utilisateur ». Ce jeton est joint automatiquement à chaque requête suivante ; c'est lui que la base lit pour calculer auth.uid() dans les politiques RLS. La session est rangée dans MMKV (section 4) pour survivre aux redémarrages.
3. Le store d'auth. L'app range l'utilisateur courant dans son store global (useAuthStore.getState().setUser(user)). C'est l'état partagé qu'on a vu dans le module sur l'état global : poser user fait basculer isAuthenticated, et toute l'app réagit.
4. La garde de navigation. Ce basculement déclenche la garde du module sur la navigation : tant qu'il n'y a pas d'utilisateur, l'app montre les écrans de connexion ; dès qu'il y en a un, elle redirige vers les écrans de l'application. La connexion et la déconnexion ne font, au fond, que basculer un seul booléen, et la navigation suit.

Un fil important relie le serveur et le local : à l'inscription, l'app crée aussi un enregistrement utilisateur dans la base locale du téléphone, et — détail crucial — avec le même identifiant que auth.uid(). C'est ce qui permet à la synchro (pull_changes/push_changes) de faire correspondre la bonne personne des deux côtés. Si les identifiants ne collaient pas, la synchro ne saurait pas à qui appartiennent les données.

8. Les Edge Functions : du code à toi, sur leurs serveurs

La plupart du temps, l'app parle à Postgres et c'est tout. Mais parfois, il faut faire quelque chose qu'on ne peut pas, et ne doit pas, faire depuis le téléphone. C'est là qu'entrent les Edge Functions : de petites fonctions serverless que tu écris (en Halterofit, en Deno, un environnement JavaScript/TypeScript moderne) et qui s'exécutent sur les serveurs de Supabase, près des utilisateurs (« edge » = en bordure de réseau). « Serverless » ne veut pas dire « sans serveur » : ça veut dire que tu n'as pas à gérer le serveur ; tu déposes ta fonction, elle se réveille à chaque appel.

Halterofit n'en a qu'une, mais elle est exemplaire : delete-account, qui supprime définitivement un compte (une exigence des stores d'applications et du RGPD — le « droit à l'effacement »). Pourquoi cette opération doit vivre côté serveur ?

Deno.serve(async (req) => {
  // ... (vérifs de méthode, CORS, en-tête Authorization présent) ...

  const authHeader = req.headers.get('Authorization');

  // Les clés sont INJECTÉES par la plateforme dans l'env de la fonction.
  // La service_role NE vit QUE côté serveur, jamais dans l'app.
  const supabaseUrl = Deno.env.get('SUPABASE_URL');
  const anonKey = Deno.env.get('SUPABASE_ANON_KEY');
  const serviceRoleKey = Deno.env.get('SUPABASE_SERVICE_ROLE_KEY');

  // 1. On identifie l'appelant À PARTIR DE SON JWT — jamais d'un id reçu
  //    dans le corps de la requête. Un appelant ne peut viser QUE son compte.
  const userClient = createClient(supabaseUrl, anonKey, {
    global: { headers: { Authorization: authHeader } },
  });
  const { data: { user } } = await userClient.auth.getUser();

  // 2. On supprime POUR DE BON avec la clé service_role (droits admin).
  //    Le ON DELETE CASCADE efface ensuite toutes ses lignes public.*.
  const adminClient = createClient(supabaseUrl, serviceRoleKey);
  await adminClient.auth.admin.deleteUser(user.id);

  return json({ success: true }, 200);
});

Deux clients, deux rôles : un anon scellé au jeton de l'utilisateur pour savoir qui appelle, puis un service_role pour agir avec les pleins pouvoirs.

Décortiquons le « pourquoi côté serveur », car c'est l'illustration parfaite de tout ce module :

• Supprimer un utilisateur de auth.users est une opération d'administrateur. Elle exige la clé service role, celle qui contourne RLS. Or cette clé ne peut jamais être dans l'app (section 5). La fonction tourne donc là où la clé peut vivre sans risque : sur le serveur.
• L'identité vient du JWT, jamais du corps de la requête. La fonction ne fait pas confiance à un id que l'app lui enverrait (sinon, on pourrait demander à supprimer le compte de quelqu'un d'autre). Elle déduit l'identité du jeton vérifié de l'appelant. Résultat : tu ne peux supprimer que ton compte. Encore le principe « le serveur tranche ».
• Le ON DELETE CASCADE fait le ménage. Une fois la ligne auth.users supprimée, les clés étrangères en cascade effacent automatiquement toutes les lignes public.* de cet utilisateur. Pas de nettoyage table par table à écrire : le schéma s'en charge.

Côté app, l'appel est trivial : supabase.functions.invoke('delete-account', ...). Le client attache automatiquement le jeton de l'utilisateur ; si la fonction répond une erreur, l'app la transforme en message lisible. Toute la complexité — et toute la sécurité — est cachée derrière, sur le serveur.

CREATE POLICY "Users see own workouts" ON public.workouts FOR ALL
  USING ((select auth.uid()) = user_id);