@j3r3mcdev/lib-access 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 j3r3mcdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,286 @@
+# @j3r3mcdev/access-service
+
+### Moteur d’autorisation professionnel — RBAC + ABAC + Access Guard
+
+Access Service est un **moteur d’autorisation complet** pour Node.js / TypeScript.  
+Il combine trois piliers essentiels de la sécurité applicative :
+
+- **RBAC avancé** (héritage, wildcard, cache)
+- **ABAC dynamique + déclaratif (JSON)**
+- **AccessGuard** (AND / OR / NOT sur rôles, permissions, policies)
+
+Son rôle : **décider qui peut faire quoi**, dans n’importe quelle API ou microservice.
+
+Il ne remplace pas ton code métier.  
+Il **observe**, **analyse**, **compare**, **évalue**, et **autorise ou refuse**.
+
+Voici tout ce qu’il couvre, expliqué simplement.
+
+---
+
+## 🔍 1. RBAC avancé (Role-Based Access Control)
+
+Le RBAC gère les **rôles** et leurs **permissions**.
+
+### ✔ Héritage de rôles
+
+Un rôle peut hériter d’un autre :
+
+- `ADMIN` → hérite de `USER`
+- `SUPERADMIN` → hérite de `ADMIN`
+
+### ✔ Wildcards
+
+Tu peux définir des permissions génériques :
+
+- `user.*`
+- `billing.*`
+- `product.read.*`
+
+### ✔ Cache interne
+
+Les permissions sont **calculées une seule fois**, puis mises en cache.  
+Résultat : **performances maximales** même avec beaucoup de rôles.
+
+### Exemple
+
+```ts
+const rbac = new RbacEngine();
+
+rbac.registerRole({
+  name: "USER",
+  permissions: [{ name: "user.read" }],
+});
+
+rbac.registerRole({
+  name: "ADMIN",
+  permissions: [{ name: "user.*" }],
+  inherits: ["USER"],
+});
+```
+
+---
+
+## 🧠 2. ABAC (Attribute-Based Access Control)
+
+Le ABAC permet de prendre des décisions basées sur le **contexte** :
+
+- userId
+- orgId
+- resourceOrgId
+- session
+- IP
+- device
+- etc.
+
+### ✔ Policies dynamiques
+
+```ts
+abac.registerPolicy({
+  name: "sameOrg",
+  effect: "allow",
+  rules: [
+    {
+      name: "sameOrgRule",
+      evaluate: (ctx) => ctx.orgId === ctx.resourceOrgId,
+    },
+  ],
+});
+```
+
+### ✔ Policies déclaratives (JSON)
+
+```ts
+loadJsonPolicies(abac, [
+  {
+    name: "isOwner",
+    effect: "allow",
+    rules: [{ name: "ownerRule", path: "userId", value: 1 }],
+  },
+]);
+```
+
+👉 **ABAC = logique métier + contexte + conditions dynamiques.**
+
+---
+
+## 🔐 3. AccessGuard — le cerveau de la décision
+
+AccessGuard combine **RBAC + ABAC** pour produire une décision finale.
+
+Il supporte :
+
+- **AND** (toutes les conditions doivent être vraies)
+- **OR** (au moins une condition doit être vraie)
+- **NOT** (aucune condition ne doit être vraie)
+- **requireAny** (multi-checks)
+
+### Exemple simple
+
+```ts
+guard.require({ roles: ["ADMIN"] }, ctx); // true
+```
+
+### Exemple avancé
+
+```ts
+guard.require(
+  {
+    rolesAny: ["MANAGER", "ADMIN"],
+    permissionsAny: ["user.delete", "user.read"],
+    policies: ["sameOrg"],
+  },
+  ctx,
+);
+```
+
+👉 **AccessGuard = la couche d’autorisation la plus flexible possible.**
+
+---
+
+## 📜 4. Audit Log — comprendre les refus
+
+Chaque refus est enregistré :
+
+- check demandé
+- contexte
+- raison
+- timestamp
+
+Exemple :
+
+```json
+{
+  "check": { "roles": ["ADMIN"] },
+  "context": { "roles": ["USER"] },
+  "reason": "RBAC AND failed: missing roles ADMIN",
+  "timestamp": 1719412000000
+}
+```
+
+👉 Idéal pour le debug, les logs de sécurité, les audits internes.
+
+---
+
+## ⚡ 5. Performances & Benchmarks
+
+Le moteur est optimisé :
+
+- cache RBAC
+- évaluation ABAC rapide
+- require / requireAny ultra légers
+
+Exemple benchmark :
+
+```ts
+console.time("RBAC");
+for (let i = 0; i < 100000; i++) {
+  guard.require({ roles: ["ADMIN"] }, ctx);
+}
+console.timeEnd("RBAC");
+```
+
+👉 **Pensé pour les API à haut débit.**
+
+---
+
+## 🧩 6. Intégration dans les frameworks
+
+### Express
+
+```ts
+app.get("/admin", (req, res) => {
+  const ctx = req.accessContext;
+
+  if (!guard.require({ roles: ["ADMIN"] }, ctx)) {
+    return res.status(403).json({ error: "Forbidden" });
+  }
+
+  res.json({ ok: true });
+});
+```
+
+### Fastify
+
+```ts
+fastify.get("/admin", async (req, reply) => {
+  const ctx = req.accessContext;
+
+  if (!guard.require({ roles: ["ADMIN"] }, ctx)) {
+    return reply.code(403).send({ error: "Forbidden" });
+  }
+
+  return { ok: true };
+});
+```
+
+### NestJS
+
+```ts
+@Injectable()
+export class AdminGuard implements CanActivate {
+  constructor(private guard: AccessGuard) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const req = context.switchToHttp().getRequest();
+    return this.guard.require({ roles: ["ADMIN"] }, req.accessContext);
+  }
+}
+```
+
+👉 **Compatible avec tous les frameworks Node.**
+
+---
+
+## 🧪 7. Tests
+
+La lib inclut des tests complets :
+
+- RBAC AND / OR / NOT
+- Permissions AND / OR / NOT
+- ABAC AND / OR / NOT
+- requireAny
+- utils (wildcards, deep match)
+- context merging
+
+Exécution :
+
+```bash
+npm run test
+```
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install @j3r3mcdev/access-service
+```
+
+---
+
+## 📦 Architecture interne
+
+```
+src/
+ ├─ rbac/
+ ├─ abac/
+ ├─ guard/
+ ├─ utils/
+ └─ context/
+```
+
+Architecture simple, claire, modulaire.
+
+---
+
+## 📄 Licence
+
+MIT
+
+---
+
+## 👤 Auteur
+
+**Jérémy Corbella — j3r3mcdev**  
+Développeur backend & architecte sécurité.

package/dist/abac/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./rule.ts";
+export * from "./policy-engine.ts";
+export * from "./policy.ts";

package/dist/abac/json-loader.d.ts

@@ -0,0 +1,2 @@
+import type { AbacEngine } from "./policy-engine.ts";
+export declare function loadJsonPolicies(engine: AbacEngine, json: any): void;

package/dist/abac/policy-engine.d.ts

@@ -0,0 +1,7 @@
+import type { AbacPolicy } from "./policy.ts";
+export declare class AbacEngine {
+    private policies;
+    registerPolicy(policy: AbacPolicy): void;
+    private evaluateRule;
+    evaluate(policyName: string, context: Record<string, any>): boolean;
+}

package/dist/abac/policy.d.ts

@@ -0,0 +1,7 @@
+import type { AbacRuleDefinition } from "./rule.ts";
+export interface AbacPolicy {
+    name: string;
+    description?: string;
+    rules: AbacRuleDefinition[];
+    effect: "allow" | "deny";
+}

package/dist/abac/rule.d.ts

@@ -0,0 +1,5 @@
+export interface AbacRuleDefinition {
+    name: string;
+    description?: string;
+    evaluate: (context: Record<string, any>) => boolean;
+}

package/dist/context/access-context.d.ts

@@ -0,0 +1,12 @@
+export interface AccessContextInput {
+    user?: Record<string, any>;
+    resource?: Record<string, any>;
+    environment?: Record<string, any>;
+}
+export declare class AccessContext {
+    user: Record<string, any>;
+    resource: Record<string, any>;
+    environment: Record<string, any>;
+    constructor(input?: AccessContextInput);
+    toObject(): Record<string, any>;
+}

package/dist/context/index.d.ts

@@ -0,0 +1 @@
+export * from "./access-context.ts";

package/dist/guard/access-guard.d.ts

@@ -0,0 +1,32 @@
+import type { RbacEngine } from "../rbac/rbac-engine.ts";
+import type { AbacEngine } from "../abac/policy-engine.ts";
+export interface GuardCheck {
+    roles?: string[];
+    rolesAny?: string[];
+    rolesNot?: string[];
+    permissions?: string[];
+    permissionsAny?: string[];
+    permissionsNot?: string[];
+    policies?: string[];
+    policiesAny?: string[];
+    policiesNot?: string[];
+}
+export type AuditEvent = {
+    check: GuardCheck;
+    context: any;
+    reason: string;
+    timestamp: number;
+};
+export declare class AccessGuard {
+    private rbac;
+    private abac;
+    private auditLog;
+    constructor(rbac: RbacEngine, abac: AbacEngine);
+    /** Audit logger */
+    private audit;
+    getAuditLog(): AuditEvent[];
+    /** Hook pour debug */
+    onDecision?: (result: boolean, check: GuardCheck, ctx: any) => void;
+    require(check: GuardCheck, ctx: any): boolean;
+    requireAny(checks: GuardCheck[], ctx: any): boolean;
+}

package/dist/guard/index.d.ts

@@ -0,0 +1 @@
+export * from "./access-guard.ts";

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/rbac/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./permission.ts";
+export * from "./role.ts";
+export * from "./rbac-engine.ts";

package/dist/rbac/permission.d.ts

@@ -0,0 +1,4 @@
+export interface Permission {
+    name: string;
+    description?: string;
+}

package/dist/rbac/rbac-engine.d.ts

@@ -0,0 +1,11 @@
+import { Role } from "../rbac/role.ts";
+export declare class RbacEngine {
+    private roles;
+    private permissionCache;
+    registerRole(role: Role): void;
+    private getEffectivePermissions;
+    /** 🔥 MÉTHODE MANQUANTE — nécessaire pour AccessGuard + tests */
+    userHasPermission(userRoles: string[], permission: string): boolean;
+    /** 🔥 MÉTHODE MANQUANTE — nécessaire pour RBAC AND/OR/NOT */
+    userHasRole(userRoles: string[], roleName: string): boolean;
+}

package/dist/rbac/role.d.ts

@@ -0,0 +1,6 @@
+import type { Permission } from "./permission.js";
+export interface Role {
+    name: string;
+    permissions: Permission[];
+    inherits?: string[];
+}

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export * from "./matchers.ts";

package/dist/utils/matchers.d.ts

@@ -0,0 +1,2 @@
+export declare function matchWildcard(value: string, pattern: string): boolean;
+export declare function matchDeep(obj: Record<string, any>, path: string): any;

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@j3r3mcdev/lib-access",
+  "version": "1.0.1",
+  "description": "Advanced access control library (RBAC + ABAC + Context + Guards) for TypeScript applications.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/j3r3mcdev/lib-access.git"
+  },
+  "homepage": "https://github.com/j3r3mcdev/lib-access#readme",
+  "bugs": {
+    "url": "https://github.com/j3r3mcdev/lib-access/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "npm run clean && tsc",
+    "test": "jest --runInBand",
+    "test:watch": "jest --watch",
+    "lint": "eslint . --ext .ts",
+    "sanity": "node sanity-check.cjs",
+    "sanity:lite": "node sanity-check.cjs --no-git",
+    "prepare": "husky",
+    "prepush": "npm run sanity:lite",
+    "release:patch": "npm version patch && npm run build && npm run sanity:lite && git push --follow-tags && npm publish --access public --registry=https://registry.npmjs.org/ && npm publish --registry=https://npm.pkg.github.com"
+  },
+  "keywords": [
+    "access-control",
+    "rbac",
+    "abac",
+    "permissions",
+    "roles",
+    "security",
+    "typescript",
+    "middleware"
+  ],
+  "author": "Jérémy",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.43",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.1",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.10",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}