@mostajs/rbac-tenant 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog — @mostajs/rbac-tenant
+## [0.1.0] — 2026-06-25
+### Ajouté (MVP)
+- RBAC étagé délégué : résolution à 2 étages `can(subject, perm, {tenantId})`, rôles tenant (`defineTenantRole`),
+  assignation/révocation scopées, délégation bornée (`grantDelegation`/`assertCanDelegate`) et boundary anti-escalade
+  (`assertGrantable`, catalogue `company.*`). Repos mémoire + matcher de repli. 8 tests (@mostajs/mjs-unit). Compose
+  @mostajs/rbac + multitenancy + repository + audit. Membre de mosta-rbac-stack.

package/README.md

@@ -0,0 +1,28 @@
+# @mostajs/rbac-tenant
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+
+**RBAC étagé délégué (multi-tenant)** : deux étages d'autorisation.
+- **Plateforme** — rôles globaux gérés par l'hôte (via `@mostajs/rbac`).
+- **Tenant** — chaque locataire (entreprise) a ses **rôles locaux**, qu'un **admin délégué** (ex. le responsable) définit et assigne **dans son périmètre**, **sans** pouvoir toucher la plateforme ni les autres tenants (**permission boundary** anti-escalade).
+
+Compose (DEVRULES §10) `@mostajs/rbac` (matching) + `@mostajs/multitenancy` (scope) + `@mostajs/repository` (persistance) + `@mostajs/audit` — ne réimplémente rien. Membre de `mosta-rbac-stack`.
+
+```js
+import { createScopedRbac } from '@mostajs/rbac-tenant';
+import { hasPermission } from '@mostajs/rbac/helpers/permissions';
+
+const rbacT = createScopedRbac({
+  match: hasPermission,
+  platformPermissionsOf: (id) => platformRbac.permissionsOf(id),   // droits plateforme (Hadhinat)
+  catalog: ['company.projects.write', 'company.ged.write', 'company.members.invite'],
+});
+
+rbacT.grantDelegation('ent-42', 'resp-id');                         // le responsable administre SON entreprise
+rbacT.defineTenantRole('resp-id', 'ent-42', 'chef-projet', ['company.projects.write']);
+rbacT.assignRole('resp-id', 'collab-id', 'chef-projet', { tenantId: 'ent-42' });
+rbacT.can('collab-id', 'company.projects.write', { tenantId: 'ent-42' });  // true
+rbacT.defineTenantRole('resp-id', 'ent-42', 'x', ['incubator.company.create']); // throw (anti-escalade)
+```
+
+API complète : `llms.txt`. Tests : `npm test` (8). Étude/conception : `incubator/app/docs/10-ETUDE-RBAC-TENANT-24062026.md`. AGPL-3.0-or-later.

package/llms.txt

@@ -0,0 +1,28 @@
+# @mostajs/rbac-tenant
+RBAC ÉTAGÉ délégué (multi-tenant). Membre de mosta-rbac-stack (à côté de @mostajs/rbac).
+## RÔLE
+Deux étages d'autorisation : (1) PLATEFORME = rôles globaux gérés par l'hôte (via @mostajs/rbac) ; (2) TENANT = rôles
+locaux qu'un admin DÉLÉGUÉ définit/assigne dans SON périmètre, avec permission boundary anti-escalade (il ne peut
+accorder QUE des permissions délégables `company.*`, jamais une permission plateforme ni un autre tenant).
+Résolution : can(subject, perm, {tenantId}) = match(permsPlateforme ∪ permsTenant, perm).
+## COMPOSE (injection, ne réimplémente rien)
+- match : @mostajs/rbac hasPermission (matching exact/wildcard/glob). Repli interne defaultMatch.
+- platformPermissionsOf : droits plateforme du sujet (fournis par l'hôte / RBAC global).
+- repos : @mostajs/repository scopé tenant (repli mémoire createMemoryRepos).
+- audit : @mostajs/audit (trace fire-and-forget).
+## EXPORTS
+createScopedRbac({ match, platformPermissionsOf, repos, catalog, audit }) → {
+  can(subjectId, perm, {tenantId}), permissionsOf(subjectId, {tenantId}),
+  isGrantable(perm), assertGrantable(perm), canDelegate(actor, tenantId), assertCanDelegate(actor, tenantId),
+  grantDelegation(tenantId, subjectId), revokeDelegation(...),
+  defineTenantRole(actor, tenantId, name, perms[]), deleteTenantRole(...), listTenantRoles(tenantId),
+  assignRole(actor, subjectId, roleName, {tenantId}), revokeRole(...), listMembers(tenantId), rolesOfMember(subjectId, tenantId),
+}
+defaultMatch(perms[], required) ; createMemoryRepos() (sous-chemin ./memory-repos)
+## TYPES
+ScopedAssignment {subjectId, roleName, scope:'tenant:<id>'} · TenantRole {tenantId, name, permissions[]} · DelegationGrant {tenantId, subjectId}
+## PIÈGES
+- can() SANS tenantId ne voit que les droits PLATEFORME (les droits tenant exigent {tenantId}).
+- un rôle tenant ne référence QUE des permissions délégables (catalogue, def. `company.*`) — assertGrantable lève sinon.
+- defineTenantRole/assignRole exigent que l'actor soit admin délégué du tenant (grantDelegation d'abord) — sinon « non déléguée ».
+- assignRole n'assigne que des rôles TENANT existants (jamais un rôle plateforme).

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mostajs/rbac-tenant",
+  "version": "0.1.0",
+  "description": "RBAC étagé délégué (multi-tenant) : rôles plateforme (global) + rôles tenant gérés par un admin DÉLÉGUÉ dans son périmètre, avec permission boundary anti-escalade. Compose @mostajs/rbac (matching) + multitenancy + repository + audit. Membre de mosta-rbac-stack.",
+  "license": "AGPL-3.0-or-later",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "type": "module",
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "llms.txt",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./memory-repos": "./src/memory-repos.js"
+  },
+  "keywords": [
+    "mostajs",
+    "rbac",
+    "multi-tenant",
+    "authorization",
+    "delegation",
+    "permission-boundary",
+    "scoped"
+  ],
+  "devDependencies": {
+    "@mostajs/mjs-unit": "^0.3.0"
+  },
+  "scripts": {
+    "test": "bash test-scripts/run-tests.sh"
+  }
+}

package/src/index.js

@@ -0,0 +1,121 @@
+// @mostajs/rbac-tenant — RBAC ÉTAGÉ délégué (multi-tenant). Author: Dr Hamid MADANI <drmdh@msn.com>
+// Deux étages : (1) PLATEFORME (rôles globaux gérés par l'hôte) ; (2) TENANT (rôles locaux qu'un admin DÉLÉGUÉ gère
+// dans SON périmètre, sans pouvoir toucher la plateforme ni les autres tenants — permission boundary anti-escalade).
+// COMPOSE (injection, DEVRULES §10) : le matching de permission (@mostajs/rbac hasPermission) + le contexte/persistance de l'hôte.
+import { createMemoryRepos } from './memory-repos.js';
+
+// Matcher par défaut (exact · wildcard '*' · glob 'a.b.*') — MIRROIR de @mostajs/rbac hasPermission.
+// En production, INJECTER `match: hasPermission` de @mostajs/rbac (ne pas dépendre de ce repli).
+export function defaultMatch(perms, required) {
+  if (!Array.isArray(perms)) return false;
+  for (const p of perms) {
+    if (p === '*' || p === required) return true;
+    if (p.endsWith('.*') && (required === p.slice(0, -2) || required.startsWith(p.slice(0, -1)))) return true;
+  }
+  return false;
+}
+
+const tenantScope = (tenantId) => `tenant:${tenantId}`;
+
+/**
+ * @param match                  (perms[], required) → bool — matching de permission (def. @mostajs/rbac).
+ * @param platformPermissionsOf  (subjectId) → string[] — droits PLATEFORME du sujet (fournis par l'hôte / @mostajs/rbac global).
+ * @param repos                  { assignments, tenantRoles, delegations } — persistance (def. mémoire).
+ * @param catalog                string[] des permissions tenant DÉLÉGABLES ; vide → tout `company.*` (la boundary).
+ * @param audit                  { log({...}) } optionnel — traçabilité fire-and-forget.
+ */
+export function createScopedRbac({
+  match = defaultMatch,
+  platformPermissionsOf = () => [],
+  repos = createMemoryRepos(),
+  catalog = [],
+  audit = null,
+} = {}) {
+  const trace = (action, data) => { try { audit?.log?.({ action, at: data?.at, ...data }); } catch { /* fire-and-forget */ } };
+  const idOf = (actor) => (typeof actor === 'string' ? actor : actor?.id);
+
+  // ── Boundary : une permission est-elle DÉLÉGABLE par un tenant (anti-escalade plateforme) ? ──
+  const isGrantable = (permission) => (catalog.length ? catalog.includes(permission) : /^company\./.test(permission));
+  function assertGrantable(permission) {
+    if (!isGrantable(permission)) throw new Error(`rbac-tenant: permission « ${permission} » non délégable (hors catalogue tenant)`);
+  }
+  // ── Boundary : l'acteur est-il admin DÉLÉGUÉ de CE tenant ? ──
+  const canDelegate = (actor, tenantId) => repos.delegations.isAdmin(tenantId, idOf(actor));
+  function assertCanDelegate(actor, tenantId) {
+    if (!tenantId) throw new Error('rbac-tenant: tenantId requis');
+    if (!canDelegate(actor, tenantId)) throw new Error('rbac-tenant: administration non déléguée pour ce tenant');
+  }
+
+  // ── Résolution des permissions effectives (plateforme ∪ tenant) ──
+  function tenantPermissionsOf(subjectId, tenantId) {
+    if (!tenantId) return [];
+    const scope = tenantScope(tenantId);
+    const roleNames = repos.assignments.rolesOf(subjectId, scope);            // rôles tenant assignés
+    const out = [];
+    for (const name of roleNames) {
+      const r = repos.tenantRoles.get(tenantId, name);
+      if (r) out.push(...r.permissions);
+    }
+    return out;
+  }
+  function permissionsOf(subjectId, { tenantId } = {}) {
+    return [...(platformPermissionsOf(subjectId) || []), ...tenantPermissionsOf(subjectId, tenantId)];
+  }
+  function can(subjectId, permission, { tenantId } = {}) {
+    return match(permissionsOf(subjectId, { tenantId }), permission);
+  }
+
+  // ── Administration DÉLÉGUÉE (bornée) ──
+  /** Déclare un sujet comme admin délégué d'un tenant (typiquement le responsable de l'entreprise). */
+  function grantDelegation(tenantId, subjectId) {
+    if (!tenantId || !subjectId) throw new Error('rbac-tenant: tenantId et subjectId requis');
+    repos.delegations.add(tenantId, subjectId);
+    trace('delegation.grant', { tenantId, subjectId });
+    return { tenantId, subjectId };
+  }
+  function revokeDelegation(tenantId, subjectId) { repos.delegations.remove(tenantId, subjectId); trace('delegation.revoke', { tenantId, subjectId }); }
+
+  /** Définit/MAJ un rôle LOCAL au tenant — toutes ses permissions doivent être délégables (anti-escalade). */
+  function defineTenantRole(actor, tenantId, name, permissions = []) {
+    assertCanDelegate(actor, tenantId);
+    if (!name) throw new Error('rbac-tenant: nom de rôle requis');
+    permissions.forEach(assertGrantable);
+    const role = repos.tenantRoles.upsert(tenantId, name, permissions);
+    trace('tenant-role.define', { actor: idOf(actor), tenantId, name, permissions });
+    return role;
+  }
+  function deleteTenantRole(actor, tenantId, name) {
+    assertCanDelegate(actor, tenantId);
+    repos.tenantRoles.remove(tenantId, name);
+    repos.assignments.removeRoleEverywhere(tenantScope(tenantId), name);
+    trace('tenant-role.delete', { actor: idOf(actor), tenantId, name });
+  }
+
+  /** Assigne un rôle TENANT à un sujet, dans le périmètre du tenant (jamais un rôle plateforme). */
+  function assignRole(actor, subjectId, roleName, { tenantId } = {}) {
+    assertCanDelegate(actor, tenantId);
+    if (!repos.tenantRoles.get(tenantId, roleName)) throw new Error(`rbac-tenant: rôle « ${roleName} » inconnu pour ce tenant`);
+    repos.assignments.add(subjectId, roleName, tenantScope(tenantId));
+    trace('role.assign', { actor: idOf(actor), subjectId, roleName, tenantId });
+    return { subjectId, roleName, scope: tenantScope(tenantId) };
+  }
+  function revokeRole(actor, subjectId, roleName, { tenantId } = {}) {
+    assertCanDelegate(actor, tenantId);
+    repos.assignments.remove(subjectId, roleName, tenantScope(tenantId));
+    trace('role.revoke', { actor: idOf(actor), subjectId, roleName, tenantId });
+  }
+
+  const listTenantRoles = (tenantId) => repos.tenantRoles.list(tenantId);
+  const listMembers = (tenantId) => repos.assignments.subjectsIn(tenantScope(tenantId));
+  const rolesOfMember = (subjectId, tenantId) => repos.assignments.rolesOf(subjectId, tenantScope(tenantId));
+
+  return {
+    can, permissionsOf, isGrantable, assertGrantable, assertCanDelegate, canDelegate,
+    grantDelegation, revokeDelegation,
+    defineTenantRole, deleteTenantRole, listTenantRoles,
+    assignRole, revokeRole, listMembers, rolesOfMember,
+  };
+}
+
+export { createMemoryRepos } from './memory-repos.js';
+export default createScopedRbac;

package/src/memory-repos.js

@@ -0,0 +1,35 @@
+// @mostajs/rbac-tenant — repos en mémoire (repli par défaut ; en prod, injecter @mostajs/repository scopé tenant). Author: Dr Hamid MADANI <drmdh@msn.com>
+export function createMemoryRepos() {
+  const assignments = [];          // { subjectId, roleName, scope }
+  const tenantRoles = new Map();   // `${tenantId}|${name}` → { tenantId, name, permissions }
+  const delegations = new Map();   // tenantId → Set(subjectId)
+  const trKey = (t, n) => `${t}|${n}`;
+  const same = (a, s, r, sc) => a.subjectId === s && a.roleName === r && a.scope === sc;
+
+  return {
+    assignments: {
+      add(subjectId, roleName, scope) {
+        if (!assignments.some((a) => same(a, subjectId, roleName, scope))) assignments.push({ subjectId, roleName, scope });
+      },
+      remove(subjectId, roleName, scope) {
+        for (let i = assignments.length - 1; i >= 0; i--) if (same(assignments[i], subjectId, roleName, scope)) assignments.splice(i, 1);
+      },
+      rolesOf(subjectId, scope) { return assignments.filter((a) => a.subjectId === subjectId && a.scope === scope).map((a) => a.roleName); },
+      subjectsIn(scope) { return [...new Set(assignments.filter((a) => a.scope === scope).map((a) => a.subjectId))]; },
+      removeRoleEverywhere(scope, roleName) {
+        for (let i = assignments.length - 1; i >= 0; i--) { const a = assignments[i]; if (a.scope === scope && a.roleName === roleName) assignments.splice(i, 1); }
+      },
+    },
+    tenantRoles: {
+      upsert(tenantId, name, permissions) { const r = { tenantId, name, permissions: [...permissions] }; tenantRoles.set(trKey(tenantId, name), r); return r; },
+      get(tenantId, name) { return tenantRoles.get(trKey(tenantId, name)) || null; },
+      remove(tenantId, name) { tenantRoles.delete(trKey(tenantId, name)); },
+      list(tenantId) { return [...tenantRoles.values()].filter((r) => r.tenantId === tenantId); },
+    },
+    delegations: {
+      add(tenantId, subjectId) { if (!delegations.has(tenantId)) delegations.set(tenantId, new Set()); delegations.get(tenantId).add(subjectId); },
+      remove(tenantId, subjectId) { delegations.get(tenantId)?.delete(subjectId); },
+      isAdmin(tenantId, subjectId) { return !!delegations.get(tenantId)?.has(subjectId); },
+    },
+  };
+}