@hgdc/auth 0.11.0 → 0.12.0

package/README.md

@@ -157,10 +157,10 @@ Une absence de session n'est jamais gardée. Déconnexion : recharger la page, o
 ## Garder une fonction Convex
 
 ```ts
-import { requireOrgMember } from "@hgdc/auth/convex"
+import { convexIssuers, requireOrgMember } from "@hgdc/auth/convex"
 
 const { userId, role } = await requireOrgMember(ctx, organizationId, {
-  issuer: process.env.CONVEX_SITE_URL!, // émetteur des JWT du plugin convex
+  issuer: convexIssuers(process.env), // émetteurs des JWT du plugin convex
   minRole: "admin",
   load: async (ctx, { organizationId, userId }) => /* appartenance lue dans la base du produit */ null,
 })
@@ -187,6 +187,31 @@ if (authErrorReason(error) === "insufficient_role") showUpgradeHint()
 
 Les organisations arrivent par la portée `organizations` : claim `organizations: [{ id, slug, name, role }]` de l'id_token et de userinfo.
 
+### Changer le domaine du déploiement Convex
+
+Les jetons du plugin `convex` portent l'émetteur `CONVEX_SITE_URL`. Quand l'adresse du déploiement change (domaine personnalisé posé par `update_canonical_url`, migration vers un Convex auto-hébergé), les jetons déjà émis gardent l'ancienne pendant leur durée de vie (15 minutes) : Convex les refuse sur une connexion neuve (`NoAuthProvider`) et la garde répond `wrong_issuer` sur un WebSocket ouvert. La variable `CONVEX_PREVIOUS_SITE_URL` ouvre une fenêtre où les deux émetteurs sont acceptés :
+
+```ts
+// convex/auth.config.ts
+import { convexAuthProviders } from "@hgdc/auth/convex"
+
+export default {
+  providers: convexAuthProviders(getAuthConfigProvider({ jwks: process.env.JWKS }), process.env),
+} satisfies AuthConfig
+
+// convex/auth.ts, dans les plugins : le plugin refuse deux fournisseurs « convex »
+convex({ authConfig: currentAuthConfig(authConfig), jwks: process.env.JWKS })
+
+// gardes
+await requireIdentity(ctx, { issuer: convexIssuers(process.env) })
+```
+
+1. Poser `CONVEX_PREVIOUS_SITE_URL` à l'adresse actuelle (`npx convex env set`), puis `convex deploy`.
+2. Changer l'adresse. Les nouveaux jetons portent le nouvel émetteur, les anciens restent acceptés.
+3. Attendre 30 minutes (deux fois la durée d'un jeton), retirer la variable, redéployer.
+
+Hors bascule, la variable est absente et rien ne change : `convexAuthProviders` rend le seul fournisseur, `convexIssuers` la seule `CONVEX_SITE_URL`. La liste ne sert qu'à donner deux adresses au même émetteur (même clé, mêmes utilisateurs), jamais à accepter un autre fournisseur.
+
 ## Synchroniser les organisations
 
 Les organisations vivent dans Account ; le produit en garde une copie (espace par organisation, appartenances) que lit le chargeur de `requireOrgMember`. Le modèle recommandé, celui de Host :

package/dist/convex.d.ts

@@ -50,15 +50,69 @@ export declare function isAuthError(error: unknown): error is ConvexError<AuthEr
 export declare function authErrorReason(error: unknown): AuthErrorReason | null;
 /**
  * Émetteur des jetons dont le `subject` désigne un utilisateur du produit. Avec le plugin
- * `convex` de better-auth : `process.env.CONVEX_SITE_URL`. Un `subject` n'est unique que chez
- * son émetteur : sans ce contrôle, un autre fournisseur accepté par Convex pourrait présenter
- * le `subject` d'un membre et prendre ses droits. Un seul émetteur : l'appartenance est
- * cherchée par `subject`, qui ne distingue pas deux fournisseurs.
+ * `convex` de better-auth : `process.env.CONVEX_SITE_URL`, ou `convexIssuers(process.env)`.
+ * Un `subject` n'est unique que chez son émetteur : sans ce contrôle, un autre fournisseur
+ * accepté par Convex pourrait présenter le `subject` d'un membre et prendre ses droits.
+ *
+ * Une liste ne sert qu'à donner plusieurs adresses au même émetteur, le temps d'un changement
+ * de domaine du déploiement : l'appartenance est cherchée par `subject`, qui ne distingue pas
+ * deux fournisseurs. Jamais deux bases d'utilisateurs différentes.
  */
 export type IssuerOption = {
+    issuer: string | readonly string[];
+};
+/** Variables d'environnement lues par `convexIssuers` et `convexAuthProviders`. */
+export type ConvexIssuerEnv = Readonly<Record<string, string | undefined>>;
+/**
+ * Émetteurs des jetons du plugin `convex` de better-auth sur ce déploiement, à passer tels quels
+ * à `requireIdentity` et `requireOrgMember` : `CONVEX_SITE_URL`, plus `CONVEX_PREVIOUS_SITE_URL`
+ * quand elle est posée.
+ *
+ * `CONVEX_PREVIOUS_SITE_URL` ne vit que pendant la bascule d'un domaine : l'ancienne adresse
+ * `actions` du déploiement, pour que les jetons émis avant la bascule restent valables jusqu'à
+ * leur expiration (15 minutes). Elle se retire ensuite.
+ *
+ * ```ts
+ * await requireIdentity(ctx, { issuer: convexIssuers(process.env) })
+ * ```
+ */
+export declare function convexIssuers(env: ConvexIssuerEnv): string[];
+/**
+ * Fournisseurs de `convex/auth.config.ts` : `provider` (celui de `getAuthConfigProvider`), plus
+ * sa copie pour `CONVEX_PREVIOUS_SITE_URL` quand elle est posée, avec la même clé. Sans elle,
+ * Convex refuse dès la bascule (`NoAuthProvider`) un jeton émis avant, sur une connexion neuve.
+ *
+ * La copie est gardée même si les deux adresses sont égales : elles le sont entre la pose de la
+ * variable et le changement de domaine, et seule `CONVEX_SITE_URL` suit alors le domaine.
+ * Le plugin `convex` de better-auth refuse deux fournisseurs `applicationID: "convex"` : il
+ * reçoit `currentAuthConfig(authConfig)`.
+ *
+ * ```ts
+ * export default {
+ *   providers: convexAuthProviders(getAuthConfigProvider({ jwks: process.env.JWKS }), process.env),
+ * } satisfies AuthConfig
+ * ```
+ */
+export declare function convexAuthProviders<P extends {
     issuer: string;
+}>(provider: P, env: ConvexIssuerEnv): P[];
+/**
+ * Configuration à donner au plugin `convex` de better-auth : le seul fournisseur courant, le
+ * premier de `convexAuthProviders`.
+ *
+ * ```ts
+ * convex({ authConfig: currentAuthConfig(authConfig), jwks: process.env.JWKS })
+ * ```
+ */
+export declare function currentAuthConfig<P>(config: {
+    providers: readonly P[];
+}): {
+    providers: P[];
 };
-/** Identité de la personne connectée, émise par `issuer`, ou erreur `UNAUTHENTICATED`. */
+/**
+ * Identité de la personne connectée, émise par `issuer` (ou l'un d'eux), ou erreur
+ * `UNAUTHENTICATED`.
+ */
 export declare function requireIdentity(ctx: {
     auth: Auth;
 }, options: IssuerOption): Promise<UserIdentity>;

package/dist/convex.js

@@ -45,14 +45,84 @@ export function authErrorReason(error) {
 function normalizeIssuer(value) {
     return value.replace(/\/+$/, "");
 }
-/** Identité de la personne connectée, émise par `issuer`, ou erreur `UNAUTHENTICATED`. */
+/**
+ * Émetteurs des jetons du plugin `convex` de better-auth sur ce déploiement, à passer tels quels
+ * à `requireIdentity` et `requireOrgMember` : `CONVEX_SITE_URL`, plus `CONVEX_PREVIOUS_SITE_URL`
+ * quand elle est posée.
+ *
+ * `CONVEX_PREVIOUS_SITE_URL` ne vit que pendant la bascule d'un domaine : l'ancienne adresse
+ * `actions` du déploiement, pour que les jetons émis avant la bascule restent valables jusqu'à
+ * leur expiration (15 minutes). Elle se retire ensuite.
+ *
+ * ```ts
+ * await requireIdentity(ctx, { issuer: convexIssuers(process.env) })
+ * ```
+ */
+export function convexIssuers(env) {
+    const issuers = [];
+    for (const value of [env.CONVEX_SITE_URL, env.CONVEX_PREVIOUS_SITE_URL]) {
+        const issuer = value ? normalizeIssuer(value.trim()) : "";
+        if (issuer && !issuers.includes(issuer))
+            issuers.push(issuer);
+    }
+    return issuers;
+}
+/** Lit une variable facultative dans `auth.config.ts`, où Convex lève sur une variable absente. */
+function optionalEnv(env, name) {
+    try {
+        return env[name]?.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Fournisseurs de `convex/auth.config.ts` : `provider` (celui de `getAuthConfigProvider`), plus
+ * sa copie pour `CONVEX_PREVIOUS_SITE_URL` quand elle est posée, avec la même clé. Sans elle,
+ * Convex refuse dès la bascule (`NoAuthProvider`) un jeton émis avant, sur une connexion neuve.
+ *
+ * La copie est gardée même si les deux adresses sont égales : elles le sont entre la pose de la
+ * variable et le changement de domaine, et seule `CONVEX_SITE_URL` suit alors le domaine.
+ * Le plugin `convex` de better-auth refuse deux fournisseurs `applicationID: "convex"` : il
+ * reçoit `currentAuthConfig(authConfig)`.
+ *
+ * ```ts
+ * export default {
+ *   providers: convexAuthProviders(getAuthConfigProvider({ jwks: process.env.JWKS }), process.env),
+ * } satisfies AuthConfig
+ * ```
+ */
+export function convexAuthProviders(provider, env) {
+    // Convex refuse un push dont auth.config.ts lit une variable absente, et n'y énumère pas
+    // `process.env` (`in`, `Object.keys` ne voient rien) : seule une lecture directe, rattrapée, convient.
+    const previous = optionalEnv(env, "CONVEX_PREVIOUS_SITE_URL");
+    return previous ? [provider, { ...provider, issuer: normalizeIssuer(previous) }] : [provider];
+}
+/**
+ * Configuration à donner au plugin `convex` de better-auth : le seul fournisseur courant, le
+ * premier de `convexAuthProviders`.
+ *
+ * ```ts
+ * convex({ authConfig: currentAuthConfig(authConfig), jwks: process.env.JWKS })
+ * ```
+ */
+export function currentAuthConfig(config) {
+    return { providers: config.providers.slice(0, 1) };
+}
+/**
+ * Identité de la personne connectée, émise par `issuer` (ou l'un d'eux), ou erreur
+ * `UNAUTHENTICATED`.
+ */
 export async function requireIdentity(ctx, options) {
     const identity = await ctx.auth.getUserIdentity();
     if (!identity)
         throw authError("no_session");
-    if (!options.issuer)
+    const expected = (typeof options.issuer === "string" ? [options.issuer] : options.issuer)
+        .map(normalizeIssuer)
+        .filter((issuer) => issuer !== "");
+    if (expected.length === 0)
         throw new Error("requireIdentity : émetteur attendu manquant (CONVEX_SITE_URL ?).");
-    if (normalizeIssuer(identity.issuer) !== normalizeIssuer(options.issuer))
+    if (!expected.includes(normalizeIssuer(identity.issuer)))
         throw authError("wrong_issuer");
     return identity;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hgdc/auth",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Connexion HGDC : bouton « Se connecter avec HGDC », config better-auth et gardes Convex.",
   "license": "UNLICENSED",
   "homepage": "https://github.com/hugogebel-boop/hgdc-kit/tree/main/packages/auth#readme",