@liorian/sdk 0.51.2-alpha.ee4411f → 1.3.1-alpha.53f9eeb

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liorian/sdk",
-  "version": "0.51.2-alpha.ee4411f",
+  "version": "1.3.1-alpha.53f9eeb",
   "description": "Core package for the Liora (application shell, domain, infrastructure, UI design system).",
   "type": "module",
   "license": "MIT",

package/schemas/module.schema.json

@@ -59,10 +59,14 @@
         }
       },
       "permissions": [
-        "User:Get",
-        "Editor:Post",
-        "Editor:Put",
-        "Admin:Delete"
+        "Widget"
+      ],
+      "access": [
+        "Admin",
+        "Root"
+      ],
+      "userScope": [
+        "UserActivity:Get"
       ],
       "oauth": {
         "scopes": [
@@ -330,17 +334,31 @@
     "permissions": {
       "type": "array",
       "items": {
-        "$ref": "#/definitions/role-permission-code"
+        "$ref": "#/definitions/module-permission-domain"
       },
       "uniqueItems": true,
-      "title": "Permissions",
-      "description": "Accès accordés au module par rôle et par verbe HTTP, au format `<ROLE>:<VERBE>` (ex. `User:Get`, `Editor:Post`, `Editor:Put`, `Admin:Delete`). Rôles et actions alignés sur les rôles/permissions du backend (PermissionsConfig) et sur les verbes HTTP des contrôleurs Raiton.",
+      "title": "Permissions (domaines exposés)",
+      "description": "Domaines de permissions que le module expose et qu'un rôle peut se voir attribuer, sous la forme de domaines PascalCase **sans** préfixe (ex. `Post`, `PostCategory`). Le serveur les compose avec la clé du module (`manifest.key`, ex. `BLOGGING`) pour former la clé namespacée du RBAC — `BLOGGING:Post`. Une liste vide signifie « le module n'expose aucune permission attribuable » ; elle n'empêche pas d'ouvrir le module. Historiquement ce champ portait des couples `<ROLE>:<VERBE>` (`User:Get`, `Editor:Post`) : cette grammaire est supprimée, le RBAC étant dynamique et non plus déclaré par le manifeste.",
       "examples": [
         [
-          "User:Get",
-          "Editor:Post",
-          "Editor:Put",
-          "Admin:Delete"
+          "Post",
+          "PostCategory"
+        ]
+      ]
+    },
+    "access": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z][A-Za-z0-9]*$"
+      },
+      "uniqueItems": true,
+      "title": "Rôles requis pour ouvrir le module",
+      "description": "Facultatif. Noms de rôles (`PermissionsConfig`) dont le niveau permet d'ouvrir le module (ex. `Admin`, `Root`). Vide ou absent : aucun palier minimal n'est exigé — seule l'attribution des permissions dans l'écran « Contrôle d'accès » fait foi.",
+      "examples": [
+        [
+          "Admin",
+          "Root"
         ]
       ]
     },
@@ -380,6 +398,41 @@
         ]
       ]
     },
+    "legal": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/legal-document-declaration"
+      },
+      "title": "Documents légaux (D16)",
+      "description": "Conditions d'utilisation, politique de confidentialité et — facultativement — contrat de licence, que l'utilisateur doit accepter avant toute utilisation du module. Le serveur normalise ces déclarations, les empreinte et verrouille l'exécution du module tant que les documents obligatoires ne sont pas acceptés à leur version et à leur empreinte courantes. Un module sans `legal` n'a aucune obligation légale : la porte reste ouverte. Dès qu'un seul document est déclaré, `TERMS` et `PRIVACY` sont tous deux obligatoires ; `LICENSE` peut être déclarée avec `required: false`.",
+      "examples": [
+        [
+          {
+            "key": "terms",
+            "kind": "TERMS",
+            "version": "1.0.0",
+            "content": [
+              {
+                "title": "Article 1 — Objet",
+                "paragraphs": [
+                  "Le présent contrat définit les conditions d'utilisation du module."
+                ]
+              }
+            ]
+          },
+          {
+            "key": "privacy",
+            "kind": "PRIVACY",
+            "version": "1.0.0",
+            "content": {
+              "Données collectées": {
+                "Responsable": "Liorian est responsable du traitement."
+              }
+            }
+          }
+        ]
+      ]
+    },
     "oauth": {
       "type": "object",
       "required": [
@@ -526,6 +579,60 @@
       "$ref": "#/definitions/menu",
       "title": "Menu de navigation",
       "description": "Déclaration des éléments de menu du module injectés dans le menu de démarrage (start menu). Les entrées purement programmatiques (`action`) restent dans la déclaration React et ne sont pas représentables en JSON."
+    },
+    "router": {
+      "type": "object",
+      "additionalProperties": false,
+      "title": "Routeur fichier",
+      "description": "Routeur fichier du module (§8.5) : la CLI génère le registre de routes depuis l'arbre de routes (défaut presentation/routes, surcharge router.dir). En mode auto, le manifeste est synchronisé avec les routes (table `routes`, complétion de `menu.items` — les entrées manuelles gagnent). En mode manual (défaut), le routage manuel du module est conservé.",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "auto",
+            "manual"
+          ],
+          "title": "Mode",
+          "description": "auto : registre généré + manifeste synchronisé. manual : le module gère ses routes à la main."
+        },
+        "dir": {
+          "type": "string",
+          "title": "Arbre de routes",
+          "description": "Arbre des routes du module, relatif à la racine (défaut presentation/routes)."
+        }
+      }
+    },
+    "routes": {
+      "type": "array",
+      "title": "Routes dérivées",
+      "description": "Table de routes dérivée de l'arbre de routes en mode router.auto (path, title, icon, menu) — écrite par la CLI, ignorée en routage manuel.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "type": "string",
+            "title": "Chemin",
+            "description": "Chemin relatif au module (racine : chaîne vide)."
+          },
+          "title": {
+            "type": "string",
+            "title": "Titre"
+          },
+          "icon": {
+            "type": "string",
+            "title": "Icône"
+          },
+          "menu": {
+            "type": "boolean",
+            "title": "Menu",
+            "description": "false : la route n'alimente pas le menu."
+          }
+        },
+        "required": [
+          "path"
+        ]
+      }
     }
   },
   "definitions": {
@@ -775,16 +882,158 @@
         ]
       ]
     },
+    "legal-document-declaration": {
+      "type": "object",
+      "required": [
+        "key",
+        "kind",
+        "version",
+        "content"
+      ],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "$comment": "`required: false` n'est admis que pour LICENSE. Le déclarer sur TERMS ou PRIVACY au `pack` permet de publier un module que personne n'a l'obligation de lire avant de l'utiliser — le serveur refuserait la publication, autant le dire à l'outil.",
+          "if": {
+            "properties": {
+              "kind": {
+                "enum": [
+                  "TERMS",
+                  "PRIVACY"
+                ]
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "properties": {
+              "required": {
+                "enum": [
+                  true
+                ]
+              }
+            }
+          }
+        }
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+          "minLength": 2,
+          "maxLength": 64,
+          "title": "Clé du document",
+          "description": "Identifiant stable du document au sein du module (kebab-case). Il entre dans la clé d'acceptation : le renommer ferait redemander l'acceptation.",
+          "examples": [
+            "terms",
+            "privacy",
+            "license"
+          ]
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "TERMS",
+            "PRIVACY",
+            "LICENSE"
+          ],
+          "title": "Catégorie du document",
+          "description": "`TERMS` (conditions d'utilisation) et `PRIVACY` (politique de confidentialité) sont obligatoires dès qu'un module déclare des documents. `LICENSE` (contrat de licence) est facultative et peut être déclarée avec `required: false`."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "title": "Titre affiché",
+          "description": "Titre du document tel que l'utilisateur le lit dans la case à cocher. Par défaut : « Conditions d'utilisation », « Politique de confidentialité » ou « Contrat de licence » selon la catégorie. Fait partie de l'empreinte du contenu."
+        },
+        "version": {
+          "$ref": "#/definitions/semver",
+          "title": "Révision du document",
+          "description": "Version du document, distincte de celle du module. **Obligatoire** et obligatoire au `pack` : c'est elle qui déclenche la ré-acceptation quand l'éditeur republie ses conditions. Publier des CGU v2 sans changer cette valeur est possible, mais l'empreinte du contenu rattrape la publication et redéclenche l'acceptation."
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "title": "Acceptation bloquante",
+          "description": "`false` n'est admis que pour `LICENSE` : les conditions d'utilisation et la politique de confidentialité bloquent toujours l'exécution du module."
+        },
+        "content": {
+          "title": "Contenu du document",
+          "description": "Le contenu est libre dans sa forme d'écriture — trois notations acceptées, normalisées en une forme canonique unique par le serveur (sections titrées, chacune portant des paragraphes) :\n\n- **tableau** de sections : `[{ \"title\": \"Article 1\", \"paragraphs\": [\"…\", \"…\"] }]` ;\n- **objet** de sections : `{ \"Article 1\": { \"Objet\": \"…\" } }` — l'ordre des clés est l'ordre de lecture ;\n- **Markdown** : une chaîne, découpée sur les titres (`##`) en sections et sur les lignes vides en paragraphes.\n\nL'empreinte SHA-256 est calculée sur la forme canonique, jamais sur la forme d'écriture : réécrire un même CGU du tableau en Markdown ne redéclenche donc pas l'acceptation.",
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1,
+              "description": "Texte, ou Markdown avec titres `##`."
+            },
+            {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "required": [
+                  "title"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "title": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "paragraphs": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              }
+            },
+            {
+              "type": "object",
+              "minProperties": 1,
+              "additionalProperties": {
+                "oneOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": {
+                      "type": "string"
+                    }
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      }
+    },
     "role-permission-code": {
       "type": "string",
       "pattern": "^[A-Za-z][A-Za-z0-9]*:(Get|Post|Put|Delete)$",
-      "title": "Permission rôle:verbe",
-      "description": "Accès accordé au format `<DOMAINE>:<VERBE>`. `DOMAINE` est un nom PascalCase (rôle du backend — `Root`, `SuperAdmin`, `Admin`, … — ou domaine de permissions — `User`, `UserActivity`, `Organization`, …) et `VERBE` un verbe HTTP (`Get`, `Post`, `Put`, `Delete`).",
+      "title": "Domaine:verbe (userScope)",
+      "description": "Entrée de `userScope` (D15), au format `<DOMAINE>:<VERBE>`. `DOMAINE` est un nom PascalCase de domaine de permissions (`User`, `UserActivity`, `Organization`, …) et `VERBE` un verbe HTTP (`Get`, `Post`, `Put`, `Delete`). La clé du module n'y figure pas : le périmètre d'un jeton de module reste exprimé en domaines nus.",
       "examples": [
         "User:Get",
-        "Editor:Post",
-        "Editor:Put",
-        "Admin:Delete"
+        "UserActivity:Get"
+      ]
+    },
+    "module-permission-domain": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9]*$",
+      "title": "Domaine exposé par le module",
+      "description": "Nom PascalCase d'un domaine de permissions exposé par le module (ex. `Post`, `PostCategory`). Le serveur le namespace avec `manifest.key` pour écrire la clé de rôle `<moduleKey>:<Domaine>` (ex. `BLOGGING:Post`).",
+      "examples": [
+        "Post",
+        "PostCategory"
       ]
     },
     "module-artifact": {

package/src/application/service/auth-api-service.ts

@@ -9,6 +9,14 @@ import {
     UserAuthSessionCheckingResponseInterface
 } from "../../domain/entities/user-auth.interface";
 import {FetchResponseInterface} from "../../domain/typing/response";
+import {type UserPermissionCapabilities} from "../../domain/entities/user.interface";
+
+/** Réponse de `GET /access-control/me/permissions` (P0.4). */
+export interface MyPermissionsResponseInterface {
+    userId: string;
+    organizationId: string;
+    permissions: UserPermissionCapabilities;
+}
 import {AuthConfig} from "../../domain/config/auth.config";
 import type {
     AuthFactor,
@@ -231,6 +239,24 @@ export class AuthApiService extends SocleApiService {
         return unwrap(this.get<FetchResponseInterface<UserInfo>>('/oauth/userinfo'));
     }
 
+    /**
+     * Matrice de permissions effective de l'appelant pour l'organisation
+     * courante (P0.4).
+     *
+     * `/oauth/userinfo` ne publie que l'identité OIDC : la matrice d'accès n'y
+     * figure pas. Elle est donc lue sur une route dédiée de l'API
+     * access-control, recalculée à chaque appel depuis les rôles vivants —
+     * condition indispensable pour que l'image rechargée remplace réellement
+     * l'instantané figé au login.
+     *
+     * L'organisation est portée par l'en-tête `X-Organization-Id` (voir
+     * `SocleApiService.buildAuthHeaders`) : elle correspond donc toujours à
+     * l'organisation courante de la session.
+     */
+    static async myPermissions(): Promise<MyPermissionsResponseInterface> {
+        return unwrap(this.get<FetchResponseInterface<MyPermissionsResponseInterface>>('/access-control/me/permissions'));
+    }
+
     static async listConsents(): Promise<AuthorizedApplication[]> {
         return unwrap(this.get<FetchResponseInterface<AuthorizedApplication[]>>('/oauth/user/consents'));
     }

package/src/application/service/auth-user.service.ts

@@ -114,6 +114,58 @@ export class AuthUserService {
         await instance.set('apiKey', apiKey).save();
     }
 
+    /**
+     * Rafraîchit la matrice de permissions de la session (P0.4).
+     *
+     * Les permissions de l'utilisateur sont aplaties au moment de la connexion
+     * puis plus jamais relues : l'image reste celle de l'instant du login. Toute
+     * mutation d'accès survenue ensuite — installation d'un module, mise à jour
+     * d'un rôle, changement d'organisation — est donc invisible de l'interface
+     * jusqu'à la déconnexion suivante. Le garde d'accès des modules évalue cette
+     * image : l'utilisateur garde un « Accès refusé » sur un module qu'il vient
+     * d'installer, ou accède à un écran devenu interdit.
+     *
+     * Cette méthode recalcule `user.permissions` depuis l'API et réécrit la
+     * session chiffrée. **Best-effort** : un échec réseau ne doit pas
+     * interrompre une installation réussie ni un changement d'organisation — la
+     * matrice reste simplement à jour au prochain appel. L'erreur est donc
+     * avalée et non propagée : l'appelant n'a pas à traiter un échec
+     * d'affichage comme un échec de l'action métier qu'il vient de réussir.
+     *
+     * L'organisation courante doit être déjà positionnée dans la session :
+     * l'appel lit l'en-tête `X-Organization-Id` (voir `buildAuthHeaders`), donc
+     * un rafraîchissement avant le choix d'organisation viserait le mauvais
+     * périmètre — il est alors ignoré plutôt que d'écrire une matrice vide.
+     *
+     * @returns la matrice réécrite, ou `null` si aucun rafraîchissement n'a eu lieu.
+     */
+    static async refreshPermissions(): Promise<UserInterface['permissions'] | null> {
+        try {
+            await this.ready();
+
+            // Sans session ni organisation courante, il n'y a rien à recalculer.
+            if (!instance.get('token') || !instance.get('currentOrganization')) return null;
+
+            const currentUser = instance.get('user');
+            if (!currentUser) return null;
+
+            // Import différé : `auth-api-service` lit la session via cette classe,
+            // et un import statique refermerait le cycle au chargement du module.
+            const {AuthApiService} = await import("./auth-api-service");
+            const result = await AuthApiService.myPermissions();
+
+            // Une réponse sans matrice exploitable ne doit pas effacer l'image
+            // courante : `{}` est une matrice valide (aucun accès), `undefined`
+            // ne l'est pas.
+            if (!result?.permissions || typeof result.permissions !== "object") return null;
+
+            await this.setUser({...currentUser, permissions: result.permissions});
+            return result.permissions;
+        } catch {
+            return null;
+        }
+    }
+
     /**
      * Installe une session neuve (connexion directe ou échange du code OAuth).
      *

package/src/application/service/module-activation-api.service.ts

@@ -43,6 +43,29 @@ export class ModuleActivationApiService extends SocleApiService {
         );
     }
 
+    /**
+     * Garantir une activation active pour un module (P0.1).
+     *
+     * Action **idempotente** : crée l'activation si elle est absente, réactive
+     * une suspension, et ne fait rien si le module est déjà actif. Elle ne
+     * consomme aucune clé sérielle.
+     *
+     * Sert au socle pour un module first-party (`external: false`), qui ne
+     * passe pas par la chaîne d'installation : sans elle,
+     * `ModuleAccessMiddleware` refuse **toutes** les routes métier du module
+     * avec « le module X n'est pas activé pour cette organisation ».
+     *
+     * Elle n'installe rien : aucun téléchargement, aucune vérification
+     * d'artefact. Un produit éditeur distribué avec `external: true` doit
+     * toujours passer par `ModuleInstallerService.install`.
+     */
+    static async ensureActivation(organizationId: string, moduleIdentifier: string) {
+        return await this.post<FetchResponseInterface<ModuleActivationInterface>>(
+            `/module-activation/organizations/${organizationId}/modules/${moduleIdentifier}/ensure`,
+            {}
+        );
+    }
+
     /** Désactiver un module pour une organisation */
     static async deactivateModule(organizationId: string, moduleIdentifier: string) {
         return await this.delete(

package/src/application/service/storefront-api.service.ts

@@ -19,7 +19,10 @@ import {
  */
 export class StorefrontApiService extends SocleApiService {
 
-    protected static baseUrl: string = (AppConfig.STORE_API_HOST || AppConfig.CORE_API_HOST) as string;
+    /** Hôte de `liorian-api-store`, relu à chaque appel (cf. `SocleApiService.baseUrl`). */
+    protected static get baseUrl(): string {
+        return ((AppConfig.STORE_API_HOST || AppConfig.CORE_API_HOST) ?? "") as string;
+    }
 
     // ─── Catalogue : modules ────────────────────────────────────────
 

package/src/domain/config/__tests__/app.config.test.ts

@@ -0,0 +1,70 @@
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest'
+
+/**
+ * Lecture d'environnement de `app.config` (D1).
+ *
+ * Deux états doivent rester distinguables : le socle, où le bundler inline les
+ * valeurs, et le bundle de module, où `process` n'existe pas. Une lecture
+ * par `typeof process` n'est inoffensive qu'aussi longtemps qu'elle s'appuie
+ * sur le polyfill interne de Next : `CORE_API_HOST` redevenu
+ * `undefined` suffisait à faire partir le déverrouillage sur `/m/undefined/…`.
+ */
+const loadConfig = async (env: Record<string, string | undefined>) => {
+    vi.resetModules()
+    const previous = {...process.env}
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined) delete process.env[key]
+        else process.env[key] = value
+    }
+    try {
+        return (await import("../app.config")).AppConfig
+    } finally {
+        for (const key of Object.keys(process.env)) delete process.env[key]
+        Object.assign(process.env, previous)
+    }
+}
+
+describe('AppConfig — lecture module-safe', () => {
+    beforeEach(() => {
+        vi.resetModules()
+    })
+
+    afterEach(() => {
+        vi.restoreAllMocks()
+    })
+
+    it('lit les hôtes exposés par l\'application', async () => {
+        const config = await loadConfig({
+            NEXT_PUBLIC_CORE_API_HOST: 'https://localhost:5711/api',
+            NEXT_PUBLIC_APP_HOST: 'https://localhost:5010',
+        })
+
+        expect(config.CORE_API_HOST).toBe('https://localhost:5711/api')
+        expect(config.APP_HOST).toBe('https://localhost:5010')
+    })
+
+    it('retombe sur les valeurs par défaut quand l\'environnement est vide', async () => {
+        const config = await loadConfig({
+            NEXT_PUBLIC_CORE_API_HOST: undefined,
+            NEXT_PUBLIC_UI_ACTIVITY_TRACKER_TIMEOUT: undefined,
+        })
+
+        expect(config.CORE_API_HOST).toBeUndefined()
+        expect(config.UI_ACTIVITY_TRACKER_TIMEOUT).toBe(3 * 60 * 1000)
+    })
+
+    it('ne lève pas quand `process` est absent — le cas d\'un bundle de module (D1)', async () => {
+        vi.resetModules()
+        const descriptor = Object.getOwnPropertyDescriptor(globalThis, 'process')
+        // Simule l'absence de `process` : un bundle de module n'injecte que
+        // `process.env.NODE_ENV` via esbuild, `process` lui-même reste indéfini.
+        Object.defineProperty(globalThis, 'process', {value: undefined, configurable: true})
+        try {
+            const {AppConfig} = await import("../app.config")
+            expect(AppConfig.CORE_API_HOST).toBeUndefined()
+            expect(AppConfig.UI_ACTIVITY_TRACKER_TIMEOUT).toBe(3 * 60 * 1000)
+        } finally {
+            if (descriptor) Object.defineProperty(globalThis, 'process', descriptor)
+        }
+    })
+})