@liorian/sdk 0.38.0-alpha.7aa2e5b → 0.46.0-alpha.63c4079

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liorian/sdk",
-  "version": "0.38.0-alpha.7aa2e5b",
+  "version": "0.46.0-alpha.63c4079",
   "description": "Core package for the Liora (application shell, domain, infrastructure, UI design system).",
   "type": "module",
   "license": "MIT",

package/schemas/module.schema.json

@@ -10,7 +10,7 @@
     {
       "schemaVersion": 1,
       "id": "hello-world",
-      "domain": "mod.liorian.helloworld",
+      "domain": "mod.liorian.hello-world",
       "key": "HELLO_WORLD",
       "name": "Hello World",
       "description": "Module d'exemple pour l'onboarding des développeurs",
@@ -59,6 +59,7 @@
     "platforms",
     "compatibility",
     "permissions",
+    "userScope",
     "oauth",
     "capabilities",
     "isEnabled",
@@ -86,11 +87,11 @@
     },
     "domain": {
       "type": "string",
-      "pattern": "^mod\\.[a-z0-9]+(\\.[a-z0-9-]+)*$",
+      "pattern": "^mod\\.[a-z0-9]+(-[a-z0-9]+)*\\.[a-z0-9]+(-[a-z0-9]+)*$",
       "minLength": 5,
-      "title": "Domaine / identifiant pleinement qualifié",
-      "description": "Identifiant de type reverse-DNS unique du module, préfixé par « mod. ». Utilisé comme `identifier` dans la déclaration (ModuleDeclarationInterface) et comme clé de synchronisation avec le backend.",
-      "examples": ["mod.liorian.accounting", "mod.liorian.pos-management"]
+      "title": "Identifiant canonique du module",
+      "description": "Identifiant canonique unique du module : mod.<organization-slug>.<module-identifier> — exactement trois labels, deux slugs kebab-case. Le slug d'organisation est obligatoirement configuré avant tout accès au socle, à Connect et à la CLI. Utilisé comme `identifier` dans la déclaration (ModuleDeclarationInterface) et comme clé de synchronisation avec le backend.",
+      "examples": ["mod.liorian.hello-world", "mod.acme.crm"]
     },
     "key": {
       "type": "string",
@@ -159,10 +160,15 @@
     "entry": {
       "type": "string",
       "pattern": "^[a-zA-Z0-9_./-]+\\.tsx?$",
-      "default": "index.tsx",
+      "default": "entry.tsx",
       "title": "Point d'entrée",
-      "description": "Chemin relatif du fichier contenant l'export default de la `ModuleDeclarationInterface` du module.",
-      "examples": ["index.tsx"]
+      "description": "Chemin relatif du fichier d'entrée TypeScript du module. Pour un module à artefact isolé (runtime iframe), c'est le fichier exportant `mount(el, ctx)` / `unmount()` (spec module-isolated-runtime.md §8.2) ; pour un module déclaratif du socle, il conserve l'export default de la `ModuleDeclarationInterface`.",
+      "examples": ["entry.tsx", "index.tsx"]
+    },
+    "artifact": {
+      "$ref": "#/definitions/module-artifact",
+      "title": "Artefact exécutable",
+      "description": "Localisation du bundle autonome et du document hôte de l'iframe (D4/D7). Obligatoire au `pack` pour un module `WEB_APP_LOCAL` ; un module purement déclaratif garde le squelette mais n'est pas servi depuis l'artefact."
     },
     "uri": {
       "type": "string",
@@ -220,6 +226,26 @@
       "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.",
       "examples": [["User:Get", "Editor:Post", "Editor:Put", "Admin:Delete"]]
     },
+    "backends": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/backend-declaration"
+      },
+      "uniqueItems": true,
+      "title": "Backends tiers déclarés (tier 1, D9)",
+      "description": "Déclaration de l'éditeur : « ce module a besoin de ces backends ». L'autorisation réelle relève du tier 2 — la liste maîtresse `ModuleEgressBackend` de l'exploitant `api-core` (§6.3). Un module qui n'appelle que `api-core` via `ctx.api` ne déclare rien.",
+      "examples": [[{"key": "erp-prod", "url": "https://erp.acme.com/api", "scopes": ["Accounting:read"], "description": "ERP de production (lecture seule)"}]]
+    },
+    "userScope": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/role-permission-code"
+      },
+      "uniqueItems": true,
+      "title": "Périmètre de données utilisateur (D15)",
+      "description": "Données utilisateur que le module lit via `ctx.api`, même grammaire que `permissions`. Le consentement est tout-ou-rien : l'utilisateur accorde l'ensemble ou refuse le module. Obligatoire au `pack` pour tous les modules, first-party compris ; `[]` est valide et signifie « aucune donnée utilisateur ».",
+      "examples": [["User:Get", "UserActivity:Get"]]
+    },
     "oauth": {
       "type": "object",
       "required": ["scopes"],
@@ -507,11 +533,81 @@
     },
     "role-permission-code": {
       "type": "string",
-      "pattern": "^(Root|SuperAdmin|Admin|Manager|Editor|Moderator|Analyst|Commercial|Operator|Contributor|Caissier|User|Guest|Viewer):(Get|Post|Put|Delete)$",
+      "pattern": "^[A-Za-z][A-Za-z0-9]*:(Get|Post|Put|Delete)$",
       "title": "Permission rôle:verbe",
-      "description": "Accès accordé au format `<ROLE>:<VERBE>`. `ROLE` est un nom de rôle existant du backend (`Root`, `SuperAdmin`, `Admin`, `Manager`, `Editor`, `Moderator`, `Analyst`, `Commercial`, `Operator`, `Contributor`, `Caissier`, `User`, `Guest`, `Viewer`) et `VERBE` un verbe HTTP (`Get`, `Post`, `Put`, `Delete`).",
+      "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`).",
       "examples": ["User:Get", "Editor:Post", "Editor:Put", "Admin:Delete"]
     },
+    "module-artifact": {
+      "type": "object",
+      "required": ["dir", "bundle", "document"],
+      "additionalProperties": false,
+      "properties": {
+        "dir": {
+          "type": "string",
+          "const": "artifact",
+          "title": "Dossier de sortie",
+          "description": "Dossier de build du module (D7 : `artifact/` et non `dist/`)."
+        },
+        "bundle": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_./-]+\\.js$",
+          "default": "module.js",
+          "title": "Bundle autonome",
+          "description": "Bundle ES unique produit par `bun build`, React et dépendances inlinés : l'origine opaque de l'iframe interdit tout partage de runtime (§11)."
+        },
+        "document": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_./-]+\\.html$",
+          "default": "index.html",
+          "title": "Document hôte",
+          "description": "Document HTML chargé dans l'iframe ; référence le bundle par chemin relatif."
+        }
+      },
+      "title": "Artefact exécutable",
+      "description": "Sortie de build installée sous `library/modules/<id>/<version>/artifact/**` et servie par `/library/**` (web) ou `liormod://` (Tauri)."
+    },
+    "backend-declaration": {
+      "type": "object",
+      "required": ["key", "url"],
+      "additionalProperties": false,
+      "properties": {
+        "key": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+          "minLength": 2,
+          "maxLength": 64,
+          "title": "Clé du backend",
+          "description": "Identifiant stable kebab-case, repris tel quel dans la liste maîtresse du tier 2 et dans `ClientApiService`."
+        },
+        "url": {
+          "type": "string",
+          "pattern": "^https://",
+          "maxLength": 2048,
+          "title": "URL de base",
+          "description": "Origine + chemin de base du backend. `https://` obligatoire (`http://` refusé sauf loopback explicitement listé au tier 2). Aucun userinfo (`user:pass@host`), aucun segment `..` ni `%2e%2e` : contraintes complétées par le validateur du `pack`, le pattern JSON ne peut pas les exprimer.",
+          "examples": ["https://erp.acme.com/api"]
+        },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/role-permission-code"
+          },
+          "minItems": 1,
+          "uniqueItems": true,
+          "title": "Permissions déclaratives",
+          "description": "Permissions que le module s'attend à exercer sur ce backend. Déclaratif : affiché dans l'écran d'approbation, non appliqué par la passerelle."
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 200,
+          "title": "Description",
+          "description": "Libellé lisible affiché à l'utilisateur dans l'écran d'approbation (§6.10.5)."
+        }
+      },
+      "title": "Déclaration de backend tiers",
+      "description": "Tier 1 du contrôle réseau (D9) : déclaration de l'éditeur. Persisté dans `ModuleInstallation.manifest` et couvert par `manifestChecksum` de la signature (§6.9)."
+    },
     "oauth-scope": {
       "type": "string",
       "enum": ["openid", "profile", "email", "organizations", "roles", "permissions"],

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

@@ -1,4 +1,4 @@
-import {ApiService} from "../../infrastructure/utilities/api-service";
+import {SocleApiService} from "../../infrastructure/utilities/socle-api-service";
 import {AuthUserService} from "./auth-user.service";
 import {
     type CreateUserAccountInterface,
@@ -72,7 +72,7 @@ function prepareWebAuthnOptions<T extends WebAuthnOptions>(options: T): T {
     return options;
 }
 
-export class AuthApiService extends ApiService {
+export class AuthApiService extends SocleApiService {
     static async fetchAvailableSessions() {
         // Les tokens/infos de l'utilisateur doivent être disponibles en local
         // avant de vérifier la validité de la session.

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

@@ -1,4 +1,4 @@
-import {ApiService} from "../../infrastructure/utilities/api-service";
+import {SocleApiService} from "../../infrastructure/utilities/socle-api-service";
 import {FetchResponseInterface} from "../../domain/typing/response";
 
 /**
@@ -45,7 +45,7 @@ export interface ConfigModuleAggregateGrouped {
 
 export type ConfigModuleAggregateResponse = ConfigModuleAggregateScalar | ConfigModuleAggregateGrouped;
 
-export class ConfigModuleApiService extends ApiService {
+export class ConfigModuleApiService extends SocleApiService {
 
     /** Lister les enregistrements d'une ressource (`?search=`). */
     static async list(moduleIdentifier: string, resource: string, options?: {search?: string}) {

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

@@ -1,4 +1,4 @@
-import {ApiService} from "../../infrastructure/utilities/api-service";
+import {SocleApiService} from "../../infrastructure/utilities/socle-api-service";
 import {FetchResponseInterface} from "../../domain/typing/response";
 import {
     ActivateModulePayloadInterface,
@@ -19,7 +19,7 @@ import {
  * validation, clés sérielles, synchronisation et analytics d'usage.
  * Le catalogue public est porté par {@link StorefrontApiService} (`/catalog`).
  */
-export class ModuleActivationApiService extends ApiService {
+export class ModuleActivationApiService extends SocleApiService {
 
     /** Activer un module pour une organisation */
     static async activateModule(organizationId: string, payload: ActivateModulePayloadInterface) {

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

@@ -1,4 +1,4 @@
-import {ApiService} from "../../infrastructure/utilities/api-service";
+import {SocleApiService} from "../../infrastructure/utilities/socle-api-service";
 import {FetchResponseInterface} from "../../domain/typing/response";
 import type {
     InstallModulePayloadInterface,
@@ -17,7 +17,7 @@ import type {
  * Cible `liorian-api-core` (base `/module-installation`) : résolution,
  * installation, cycle de vie, sync et jetons d'artefacts.
  */
-export class ModuleInstallationApiService extends ApiService {
+export class ModuleInstallationApiService extends SocleApiService {
 
     private static org(organizationId: string) {
         return `/module-installation/organizations/${organizationId}`;
@@ -115,4 +115,21 @@ export class ModuleInstallationApiService extends ApiService {
             {deviceId},
         );
     }
+
+    /**
+     * Relais de l'archive vérifiée (spec `module-isolated-runtime` §5.2).
+     *
+     * `api-core` re-vérifie les octets (checksum, Ed25519, manifeste, audit)
+     * **au moment du relais** et ne répond que s'ils sont intacts ; le socle
+     * devient l'installateur d'octets sans devenir une autorité de confiance.
+     * Invariant : un artefact obtenu hors de ce canal n'est pas installable.
+     */
+    static async fetchVerifiedArchive(organizationId: string, moduleIdentifier: string, version: string): Promise<ArrayBuffer> {
+        const response = await this.get<ArrayBuffer>(
+            `${this.org(organizationId)}/modules/${moduleIdentifier}/versions/${version}/verified-archive`,
+            undefined,
+            {responseType: "arraybuffer"},
+        );
+        return response.data;
+    }
 }

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

@@ -1,4 +1,4 @@
-import {ApiService} from "../../infrastructure/utilities/api-service";
+import {SocleApiService} from "../../infrastructure/utilities/socle-api-service";
 import {PaginationWithSearchOptions} from "../../domain/typing/response";
 
 export interface PushSubscriptionKeys {
@@ -11,7 +11,7 @@ export interface PushSubscriptionPayload {
     keys: PushSubscriptionKeys;
 }
 
-export class NotificationsApiService extends ApiService {
+export class NotificationsApiService extends SocleApiService {
     static async getAll(options?: PaginationWithSearchOptions & { read?: boolean }) {
         return await this.get('/notifications/', options);
     }

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

@@ -1,8 +1,8 @@
-import {ApiService} from "../../infrastructure/utilities/api-service";
+import {SocleApiService} from "../../infrastructure/utilities/socle-api-service";
 import {FetchResponseInterface} from "../../domain/typing/response";
 import {OrganizationApiAccessResponseInterface} from "../../domain/entities/organization.interface";
 
-export class OrganizationsApiService extends ApiService {
+export class OrganizationsApiService extends SocleApiService {
     // Organizations
     static async create(payload: any) {
         return await this.post('/organizations/', payload);

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

@@ -1,6 +1,6 @@
-import {ApiService} from "../../infrastructure/utilities/api-service";
+import {SocleApiService} from "../../infrastructure/utilities/socle-api-service";
 
-export class OtpApiService extends ApiService {
+export class OtpApiService extends SocleApiService {
     static async createOtp(payload: { phone: string; domain?: string }) {
         return await this.post('/otp/create', payload);
     }

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

@@ -1,9 +1,9 @@
-import {ApiService} from "../../infrastructure/utilities/api-service";
+import {SocleApiService} from "../../infrastructure/utilities/socle-api-service";
 import {MediaLabelService} from "../../infrastructure/utilities/media-label.service";
 import type {MediaSection, MediaUploadOptions} from "../../domain/entities/media";
 import type {AxiosProgressEvent, AxiosRequestConfig} from "axios";
 
-export class StorageApiService extends ApiService {
+export class StorageApiService extends SocleApiService {
     static async uploadFile(file: File, options?: MediaUploadOptions, onUploadProgress?: (progressEvent: AxiosProgressEvent) => void, config?: AxiosRequestConfig<any>) {
         const formData = new FormData();
         formData.append("file", file);

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

@@ -1,4 +1,4 @@
-import {ApiService} from "../../infrastructure/utilities/api-service";
+import {SocleApiService} from "../../infrastructure/utilities/socle-api-service";
 import {AppConfig} from "../../domain/config/app.config";
 import {FetchResponseInterface} from "../../domain/typing/response";
 import {
@@ -17,7 +17,7 @@ import {
  * sans auth ; les mutations (fiche produit / catégorie) sont réservées au
  * SuperAdmin (JWT partagé émis par core).
  */
-export class StorefrontApiService extends ApiService {
+export class StorefrontApiService extends SocleApiService {
 
     protected static baseUrl: string = (AppConfig.STORE_API_HOST || AppConfig.CORE_API_HOST) as string;
 
@@ -28,9 +28,9 @@ export class StorefrontApiService extends ApiService {
         return await this.get<FetchResponseInterface<CatalogModuleInterface[]>>('/catalog/modules');
     }
 
-    /** Récupérer un module du catalogue par son ID */
-    static async getCatalogModule(moduleId: string) {
-        return await this.get<FetchResponseInterface<CatalogModuleInterface>>(`/catalog/modules/${moduleId}`);
+    /** Récupérer un module du catalogue par son identifiant technique (`mod.<organization-slug>.<module-identifier>`) */
+    static async getCatalogModule(identifier: string) {
+        return await this.get<FetchResponseInterface<CatalogModuleInterface>>(`/catalog/modules/${identifier}`);
     }
 
     /** Créer une fiche produit (SuperAdmin) */

package/src/application/service/user-preferences-api.service.ts

@@ -1,4 +1,4 @@
-import {ApiService} from "../../infrastructure/utilities/api-service";
+import {SocleApiService} from "../../infrastructure/utilities/socle-api-service";
 
 export interface UserPreferenceInterface {
     id: string;
@@ -7,7 +7,7 @@ export interface UserPreferenceInterface {
     value: string;
 }
 
-export class UserPreferencesApiService extends ApiService {
+export class UserPreferencesApiService extends SocleApiService {
 
     static async getByUserId(userId: string) {
         return await this.get(`/user-preferences/user/${userId}`);

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

@@ -10,6 +10,13 @@ export const AppConfig = {
     APP_NAME: process.env.NEXT_PUBLIC_APP_NAME as unknown as string,
     APP_VERSION: process.env.NEXT_PUBLIC_APP_VERSION as unknown as string,
     APP_VERSION_NUMBER: process.env.NEXT_PUBLIC_APP_VERSION_NUMBER as unknown as number,
+    /**
+     * Version de l'API core exposée au socle. Distincte d'`APP_VERSION` (version
+     * du socle) : la résolution de module compare ces deux axes séparément
+     * (`compat.socle` / `compat.api`), envoyer la version du socle sur l'axe
+     * `api` rend toute version publiée incompatible.
+     */
+    CORE_API_VERSION: process.env.NEXT_PUBLIC_CORE_API_VERSION as unknown as string,
     
     /** Alias conservé pour compatibilité : renvoie la même cadence que `APP_REFRESH_UI`. */
     UI_REFRESH_TIMEOUT: toPositiveMilliseconds(

package/src/domain/entities/index.ts

@@ -5,6 +5,8 @@ export * from "./catalog.interface";
 export * from "./module-activation.interface";
 export * from "./module-configuration.interface";
 export * from "./module.interface";
+export * from "./module-runtime.interface";
+export * from "./module-scope.interface";
 export * from "./notification.interface";
 export * from "./objectable.type";
 export * from "./organization.interface";

package/src/domain/entities/module-installation.interface.ts

@@ -28,36 +28,49 @@ export interface ResolveModulePayloadInterface {
     deviceId?: string;
 }
 
+/**
+ * Version résolue par le core. Le contrat est volontairement aligné sur ce que
+ * le registre renvoie réellement : la résolution s'appuie sur le catalogue
+ * **public** du store (`CatalogModuleVersionPublicVm`), qui ne publie ni la
+ * signature brute ni les empreintes ni les URL d'artefact. Ces champs ne sont
+ * matérialisés qu'au moment de l'installation, sur le manifeste interne
+ * consommé par le core (FR-004 / FR-005). Le client doit donc les traiter
+ * comme absents et ne jamais en supposer la présence.
+ */
 export interface ModuleResolutionItemInterface {
     id: string;
-    moduleIdentifier: string;
+    moduleIdentifier?: string;
     version: string;
     type: string;
-    external: boolean;
+    external?: boolean;
     uri: string;
     entry: string;
-    name: string;
+    name?: string;
     description?: string | null;
     icon?: string | null;
     logoUrl?: string | null;
     bannerUrl?: string | null;
     category?: string | null;
-    checksum: string;
-    manifestChecksum: string;
-    signature: string;
-    signatureKeyId: string;
+    /** Empreinte SHA-256 de l'archive — non publiée par le catalogue public. */
+    checksum?: string;
+    /** Empreinte SHA-256 du manifeste canonicalisé — non publiée par le catalogue public. */
+    manifestChecksum?: string;
+    /** Signature Ed25519 (base64) — jamais publiée au client. */
+    signature?: string;
+    /** Identifiant de la clé de signature — non publié par le catalogue public. */
+    signatureKeyId?: string;
     sizeBytes: number;
     capabilities?: string[];
     permissions?: string[];
     platforms?: Record<string, any> | null;
     compatibility?: Record<string, any> | null;
-    manifestUrl: string;
-    downloadUrl: string;
-    runtimeUrlTemplate: string;
-    installable: boolean;
+    manifestUrl?: string;
+    downloadUrl?: string;
+    runtimeUrlTemplate?: string;
+    installable?: boolean;
     reason?: string | null;
     installedVersion?: string | null;
-    updateAvailable: boolean;
+    updateAvailable?: boolean;
 }
 
 export interface ModuleResolutionResponseInterface {

package/src/domain/entities/module-runtime.interface.ts

@@ -0,0 +1,108 @@
+/**
+ * Contrat d'exécution d'un module isolé (docs/specs/applications/
+ * module-isolated-runtime.md §4.2).
+ *
+ * Ce fichier doit rester transport-agnostique : aucun import `next/*`, aucun
+ * accès au DOM du socle, aucune lecture de jeton. Tout ce que le module
+ * reçoit est injecté par l'hôte via `mount(el, ctx)`.
+ */
+
+import type {ModuleRuntimeType} from "./module-installation.interface";
+import type {ModuleScopeUserInterface} from "./module-scope.interface";
+
+/** Chemin logique du socle, indispensable en iframe où usePathname() est faux. */
+export interface ModuleRouteInterface {
+    soclePath: string;
+    segments: string[];
+    pageId?: string;
+}
+
+/** Capacités RPC offertes par le socle via postMessage — des capacités, jamais des identifiants. */
+export interface ModuleBridgeInterface {
+    navigate(href: string): void;
+    notify(message: string, kind?: "info" | "success" | "warning" | "error"): void;
+    openMediaPicker(): Promise<PickedMediaInterface | null>;
+    setTitle(title: string): void;
+    getTheme(): Promise<"light" | "dark">;
+    reload(): void;
+    on(event: ModuleBridgeEvent, listener: () => void): void;
+    off(event: ModuleBridgeEvent, listener: () => void): void;
+}
+
+export type ModuleBridgeEvent = "reload" | "theme-changed";
+
+export interface PickedMediaInterface {
+    id: string;
+    url: string;
+    name?: string;
+    mimeType?: string;
+}
+
+/**
+ * Point de passage réseau vers api-core (D16). Instance injectée par l'hôte,
+ * adossée à un jeton modulaire (session × module × périmètre accordé) : le
+ * module ne voit jamais le jeton de session et n'agit pas au-delà du
+ * périmètre accordé. La forme exacte est livrée par le refactor d'`ApiService`
+ * (§4.5, phase 1b) ; le contrat reste minimal et sans hôte.
+ */
+export interface ModuleApiClientInterface {
+    get<T>(path: string, query?: Record<string, unknown>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+
+/**
+ * Client egress vers la passerelle api-core (D17, modules tiers uniquement).
+ * Absent pour un module first-party.
+ *
+ * Callable direct : `egress(backendKey, path, init)` — le module ne fournit
+ * jamais d'URL absolue, la passerelle joint le chemin sous le chemin de base
+ * autorisé de la liste maîtresse (§6.5). `ClientApiService` l'encapsule.
+ */
+export type ModuleEgressInterface = (
+    backendKey: string,
+    path: string,
+    init?: ModuleEgressRequestInit,
+) => Promise<unknown>;
+
+export interface ModuleEgressRequestInit {
+    method?: string;
+    body?: unknown;
+    query?: Record<string, unknown>;
+    headers?: Record<string, string>;
+}
+
+export interface ModuleContextUserInterface {
+    id: string;
+    displayName: string;
+}
+
+export interface ModuleContextOrganizationInterface {
+    id: string;
+    name: string;
+}
+
+export interface ModuleContext {
+    /** Transport détecté (`detectModuleRuntime()`). */
+    runtime: ModuleRuntimeType;
+    /** Santé de la connectivité api-core — false → bandeau socle, dégradation du module. */
+    core: boolean;
+    route: ModuleRouteInterface;
+    bridge: ModuleBridgeInterface;
+    /** Instance d'`ApiService` construite et signée par l'hôte — jamais par le module. */
+    api: ModuleApiClientInterface;
+    /** Consentement utilisateur (D15). Injecté par l'hôte, déduit de l'accord. */
+    scope: {
+        user: ModuleScopeUserInterface;
+    };
+    /** Passerelle egress (D17). Absent pour un module first-party. */
+    egress?: ModuleEgressInterface;
+    user: ModuleContextUserInterface;
+    organization: ModuleContextOrganizationInterface;
+}
+
+export interface ModuleHandle {
+    unmount: () => void | Promise<void>;
+}

package/src/domain/entities/module-scope.interface.ts

@@ -0,0 +1,32 @@
+/**
+ * Périmètre de données utilisateur accordé à un module (D15 — consentement
+ * tout-ou-rien). Voir docs/specs/applications/module-isolated-runtime.md §6.10.
+ *
+ * Le grant vit dans api-core ; ce que voit le module n'est qu'une projection
+ * déclarative, interrogable et opposable — jamais un jeton.
+ */
+export interface ModuleScopeUserInterface {
+    /** true si le module est approuvé par l'utilisateur (tout-ou-rien). */
+    readonly granted: boolean;
+
+    /** Périmètres accordés, même grammaire que `permissions` (ex. `User:Get`). */
+    readonly scopes: readonly string[];
+
+    /** Le périmètre demandé est-il couvert par l'accord ? */
+    can(permission: string): boolean;
+
+    /**
+     * Lève une exception typée si le périmètre n'est pas couvert. Seul idiome
+     * autorisé dans un chemin de données : un `if (can())` oublié rend un refus
+     * invisible.
+     */
+    require(permission: string): void;
+}
+
+/** Exception levée par `ctx.scope.user.require()` hors périmètre accordé. */
+export class ModuleScopeDeniedError extends Error {
+    constructor(readonly permission: string) {
+        super(`Périmètre utilisateur non accordé au module : ${permission}`);
+        this.name = "ModuleScopeDeniedError";
+    }
+}

package/src/domain/entities/module.interface.ts

@@ -1,5 +1,4 @@
 import React from "react";
-import {ApiService} from "../../infrastructure/utilities/api-service";
 import {IconKey} from "../../presentation/icons/types";
 import {RoutineInterface} from "../typing/routine.types";
 import {AppRouterInstance} from "next/dist/shared/lib/app-router-context.shared-runtime";
@@ -7,6 +6,7 @@ import {ModuleStoreStateType, ModuleConfigSettingsFieldInterface} from "./module
 import type {ModuleConfigurationInterface} from "./module-configuration.interface";
 import {ModuleCategory} from "../enums/module-category.enum";
 import type {ModuleType} from "../enums/module-type.enum";
+import type {ModuleApiClientInterface} from "./module-runtime.interface";
 
 export type {ModuleType} from "../enums/module-type.enum";
 
@@ -25,7 +25,8 @@ export interface ModuleInstanceInterface {
 }
 
 export interface ModuleDeclarationServicesInterface {
-    fetch?: ApiService
+    /** Client réseau injecté par l'hôte (D16) — jamais l'`ApiService` statique du socle. */
+    fetch?: ModuleApiClientInterface
 }
 
 export interface ModuleDeclarationProvidersInterface {

package/src/domain/enums/module-category.enum.ts

@@ -1,4 +1,4 @@
-import {IconKey} from "../../presentation/icons/types";
+import type {IconKey} from "../../presentation/icons/types";
 
 /**
  * Catégories de modules du Module Store.