odgn-rights 0.1.0 → 0.5.0

package/dist/role-registry.js

@@ -23,6 +23,18 @@ export class RoleRegistry {
     toJSON() {
         return Array.from(this.roles.values()).map(r => r.toJSON());
     }
+    /**
+     * Load all roles and their relationships from a database adapter
+     */
+    static async loadFrom(adapter) {
+        return adapter.loadRegistry();
+    }
+    /**
+     * Save all roles and their relationships to a database adapter
+     */
+    async saveTo(adapter) {
+        await adapter.saveRegistry(this);
+    }
     static fromJSON(data) {
         const registry = new RoleRegistry();
         // First pass: create all roles
@@ -38,6 +50,9 @@ export class RoleRegistry {
                     if (parent) {
                         role.inheritsFrom(parent);
                     }
+                    else {
+                        throw new Error(`Role ${item.name} inherits from missing role ${parentName}`);
+                    }
                 }
             }
         }

package/dist/role.d.ts

@@ -4,7 +4,8 @@ import type { RoleJSON } from './role-registry';
 export declare class Role {
     readonly name: string;
     readonly rights: Rights;
-    private parents;
+    readonly parents: Role[];
+    private children;
     private _cachedAllRights;
     constructor(name: string, rights?: Rights);
     inheritsFrom(role: Role): this;
@@ -18,6 +19,7 @@ export declare class Role {
             type: 'role';
         };
     }>;
+    findRightsByTag(tag: string): Right[];
     invalidateCache(): void;
     toJSON(): RoleJSON;
 }

package/dist/role.js

@@ -3,9 +3,11 @@ import { Rights } from './rights';
 export class Role {
     constructor(name, rights) {
         this.parents = [];
+        this.children = [];
         this._cachedAllRights = null;
         this.name = name;
         this.rights = rights ?? new Rights();
+        this.rights.onChange = () => this.invalidateCache();
     }
     inheritsFrom(role) {
         if (role === this) {
@@ -13,6 +15,7 @@ export class Role {
         }
         if (!this.parents.includes(role)) {
             this.parents.push(role);
+            role.children.push(this);
             this.invalidateCache();
         }
         return this;
@@ -34,8 +37,16 @@ export class Role {
         this._cachedAllRights = list;
         return list;
     }
+    findRightsByTag(tag) {
+        return this.allRights()
+            .map(r => r.right)
+            .filter(r => r.hasTag(tag));
+    }
     invalidateCache() {
         this._cachedAllRights = null;
+        for (const child of this.children) {
+            child.invalidateCache();
+        }
     }
     toJSON() {
         const out = {

package/dist/subject-registry.d.ts

@@ -0,0 +1,77 @@
+import type { DatabaseAdapter } from './adapters/types';
+import { Flags } from './constants';
+import type { ConditionContext } from './right';
+import type { RoleRegistry } from './role-registry';
+import { Subject, type SubjectJSON } from './subject';
+export type SubjectRegistryJSON = {
+    [identifier: string]: SubjectJSON;
+};
+/**
+ * In-memory registry for managing Subject instances.
+ * Provides an API similar to RoleRegistry for consistency.
+ */
+export declare class SubjectRegistry {
+    private subjects;
+    /**
+     * Register a subject with an identifier.
+     * If a subject with this identifier already exists, it will be replaced.
+     */
+    register(identifier: string, subject: Subject): void;
+    /**
+     * Get a subject by its identifier.
+     */
+    get(identifier: string): Subject | undefined;
+    /**
+     * Check if a subject with the given identifier exists.
+     */
+    has(identifier: string): boolean;
+    /**
+     * Delete a subject by its identifier.
+     * @returns true if the subject was deleted, false if not found
+     */
+    delete(identifier: string): boolean;
+    /**
+     * Get all registered identifiers.
+     */
+    identifiers(): string[];
+    /**
+     * Get the number of registered subjects.
+     */
+    get size(): number;
+    /**
+     * Clear all registered subjects.
+     */
+    clear(): void;
+    /**
+     * Iterate over all subjects.
+     */
+    entries(): IterableIterator<[string, Subject]>;
+    /**
+     * Find all subject identifiers that have access to a specific path with given flags.
+     * @param pathPattern The path pattern to check (supports wildcards)
+     * @param flags The flags to check for
+     * @param context Optional condition context for ABAC-style checks
+     * @returns Array of subject identifiers that have access
+     */
+    findSubjectsWithAccess(pathPattern: string, flags: Flags, context?: ConditionContext): string[];
+    /**
+     * Serialize the registry to JSON.
+     */
+    toJSON(): SubjectRegistryJSON;
+    /**
+     * Create a SubjectRegistry from JSON data.
+     * @param data The serialized registry data
+     * @param roleRegistry Optional RoleRegistry for resolving role references
+     */
+    static fromJSON(data: SubjectRegistryJSON, roleRegistry?: RoleRegistry): SubjectRegistry;
+    /**
+     * Save all subjects to a database adapter.
+     */
+    saveTo(adapter: DatabaseAdapter): Promise<void>;
+    /**
+     * Load all subjects from a database adapter.
+     * Note: This requires the adapter to support getAllSubjectIdentifiers().
+     * For adapters that don't support this, use loadFromIdentifiers() instead.
+     */
+    static loadFrom(adapter: DatabaseAdapter, identifiers: string[]): Promise<SubjectRegistry>;
+}

package/dist/subject-registry.js

@@ -0,0 +1,123 @@
+import { Flags } from './constants';
+import { Subject } from './subject';
+/**
+ * In-memory registry for managing Subject instances.
+ * Provides an API similar to RoleRegistry for consistency.
+ */
+export class SubjectRegistry {
+    constructor() {
+        this.subjects = new Map();
+    }
+    /**
+     * Register a subject with an identifier.
+     * If a subject with this identifier already exists, it will be replaced.
+     */
+    register(identifier, subject) {
+        this.subjects.set(identifier, subject);
+    }
+    /**
+     * Get a subject by its identifier.
+     */
+    get(identifier) {
+        return this.subjects.get(identifier);
+    }
+    /**
+     * Check if a subject with the given identifier exists.
+     */
+    has(identifier) {
+        return this.subjects.has(identifier);
+    }
+    /**
+     * Delete a subject by its identifier.
+     * @returns true if the subject was deleted, false if not found
+     */
+    delete(identifier) {
+        return this.subjects.delete(identifier);
+    }
+    /**
+     * Get all registered identifiers.
+     */
+    identifiers() {
+        return Array.from(this.subjects.keys());
+    }
+    /**
+     * Get the number of registered subjects.
+     */
+    get size() {
+        return this.subjects.size;
+    }
+    /**
+     * Clear all registered subjects.
+     */
+    clear() {
+        this.subjects.clear();
+    }
+    /**
+     * Iterate over all subjects.
+     */
+    entries() {
+        return this.subjects.entries();
+    }
+    /**
+     * Find all subject identifiers that have access to a specific path with given flags.
+     * @param pathPattern The path pattern to check (supports wildcards)
+     * @param flags The flags to check for
+     * @param context Optional condition context for ABAC-style checks
+     * @returns Array of subject identifiers that have access
+     */
+    findSubjectsWithAccess(pathPattern, flags, context) {
+        const matching = [];
+        for (const [identifier, subject] of this.subjects) {
+            if (subject.has(pathPattern, flags, context)) {
+                matching.push(identifier);
+            }
+        }
+        return matching;
+    }
+    /**
+     * Serialize the registry to JSON.
+     */
+    toJSON() {
+        const result = {};
+        for (const [identifier, subject] of this.subjects) {
+            result[identifier] = subject.toJSON();
+        }
+        return result;
+    }
+    /**
+     * Create a SubjectRegistry from JSON data.
+     * @param data The serialized registry data
+     * @param roleRegistry Optional RoleRegistry for resolving role references
+     */
+    static fromJSON(data, roleRegistry) {
+        const registry = new SubjectRegistry();
+        for (const [identifier, subjectData] of Object.entries(data)) {
+            const subject = Subject.fromJSON(subjectData, roleRegistry);
+            registry.register(identifier, subject);
+        }
+        return registry;
+    }
+    /**
+     * Save all subjects to a database adapter.
+     */
+    async saveTo(adapter) {
+        for (const [identifier, subject] of this.subjects) {
+            await adapter.saveSubject(identifier, subject);
+        }
+    }
+    /**
+     * Load all subjects from a database adapter.
+     * Note: This requires the adapter to support getAllSubjectIdentifiers().
+     * For adapters that don't support this, use loadFromIdentifiers() instead.
+     */
+    static async loadFrom(adapter, identifiers) {
+        const registry = new SubjectRegistry();
+        for (const id of identifiers) {
+            const subject = await adapter.loadSubject(id);
+            if (subject) {
+                registry.register(id, subject);
+            }
+        }
+        return registry;
+    }
+}

package/dist/subject.d.ts

@@ -1,12 +1,19 @@
 import { Flags } from './constants';
 import { Right, type ConditionContext } from './right';
-import { Rights } from './rights';
+import { Rights, type RightJSON } from './rights';
 import { Role } from './role';
+import type { RoleRegistry } from './role-registry';
+export type SubjectJSON = {
+    rights?: RightJSON[];
+    roles?: string[];
+};
 export declare class Subject {
-    private roles;
+    readonly roles: Role[];
     readonly rights: Rights;
     private _aggregate;
     private _aggregateMeta;
+    toJSON(): SubjectJSON;
+    static fromJSON(data: SubjectJSON, registry?: RoleRegistry): Subject;
     memberOf(role: Role): this;
     invalidateCache(): void;
     has(path: string, flag: Flags, context?: ConditionContext): boolean;
@@ -22,10 +29,22 @@ export declare class Subject {
             };
         }>;
     };
+    allRights(): Array<{
+        right: Right;
+        source?: {
+            name?: string;
+            type: 'direct' | 'role';
+        };
+    }>;
+    private ensureAggregate;
     all(path: string, context?: ConditionContext): boolean;
     read(path: string, context?: ConditionContext): boolean;
     write(path: string, context?: ConditionContext): boolean;
     delete(path: string, context?: ConditionContext): boolean;
     create(path: string, context?: ConditionContext): boolean;
     execute(path: string, context?: ConditionContext): boolean;
+    checkMany(requests: Array<{
+        flags: Flags;
+        path: string;
+    }>, context?: ConditionContext): boolean[];
 }

package/dist/subject.js

@@ -9,6 +9,35 @@ export class Subject {
         this._aggregate = null;
         this._aggregateMeta = null;
     }
+    toJSON() {
+        const out = {};
+        if (this.roles.length > 0) {
+            out.roles = this.roles.map(r => r.name);
+        }
+        const rights = this.rights.toJSON();
+        if (rights.length > 0) {
+            out.rights = rights;
+        }
+        return out;
+    }
+    static fromJSON(data, registry) {
+        const subject = new Subject();
+        if (data.roles && registry) {
+            for (const roleName of data.roles) {
+                const role = registry.get(roleName);
+                if (role) {
+                    subject.memberOf(role);
+                }
+            }
+        }
+        if (data.rights) {
+            const rights = Rights.fromJSON(data.rights);
+            for (const r of rights.allRights()) {
+                subject.rights.add(r);
+            }
+        }
+        return subject;
+    }
     memberOf(role) {
         if (!this.roles.includes(role)) {
             this.roles.push(role);
@@ -24,6 +53,24 @@ export class Subject {
         return this.explain(path, flag, context).allowed;
     }
     explain(path, flag, context) {
+        const { meta, rights } = this.ensureAggregate();
+        const res = rights.explain(path, flag, context);
+        return {
+            allowed: res.allowed,
+            details: res.details.map(d => ({
+                ...d,
+                source: d.right ? meta.get(d.right) : undefined
+            }))
+        };
+    }
+    allRights() {
+        const { meta, rights } = this.ensureAggregate();
+        return rights.allRights().map(right => ({
+            right,
+            source: meta.get(right)
+        }));
+    }
+    ensureAggregate() {
         if (!this._aggregate) {
             this._aggregate = new Rights();
             this._aggregateMeta = new Map();
@@ -42,14 +89,7 @@ export class Subject {
                 this._aggregateMeta.set(r, { type: 'direct' });
             }
         }
-        const res = this._aggregate.explain(path, flag, context);
-        return {
-            allowed: res.allowed,
-            details: res.details.map(d => ({
-                ...d,
-                source: d.right ? this._aggregateMeta.get(d.right) : undefined
-            }))
-        };
+        return { meta: this._aggregateMeta, rights: this._aggregate };
     }
     // Convenience helpers
     all(path, context) {
@@ -70,4 +110,7 @@ export class Subject {
     execute(path, context) {
         return this.has(path, Flags.EXECUTE, context);
     }
+    checkMany(requests, context) {
+        return requests.map(req => this.has(req.path, req.flags, context));
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odgn-rights",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "description": "Tiny TypeScript library for expressing and evaluating hierarchical rights with simple glob patterns.",
   "keywords": [
     "rights",
@@ -16,10 +16,38 @@
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "odgn-rights": "./dist/cli/index.js",
+    "rights": "./dist/cli/index.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "import": "./dist/adapters/index.js"
+    },
+    "./adapters/sqlite": {
+      "types": "./dist/adapters/sqlite-adapter.d.ts",
+      "import": "./dist/adapters/sqlite-adapter.js"
+    },
+    "./adapters/postgres": {
+      "types": "./dist/adapters/postgres-adapter.d.ts",
+      "import": "./dist/adapters/postgres-adapter.js"
+    },
+    "./adapters/redis": {
+      "types": "./dist/adapters/redis-adapter.d.ts",
+      "import": "./dist/adapters/redis-adapter.js"
+    },
+    "./integrations/elysia": {
+      "types": "./dist/integrations/elysia.d.ts",
+      "import": "./dist/integrations/elysia.js"
     }
   },
   "files": [
@@ -32,26 +60,54 @@
     "lint": "eslint --cache .",
     "lint:fix": "eslint --fix .",
     "outdated": "bunx npm-check-updates --interactive --format group",
-    "test": "bun test",
-    "test:coverage": "bun test --coverage",
+    "test": "bun test src",
+    "test:coverage": "bun test --coverage src",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
     "unused": "knip",
     "clean": "rm -rf dist",
     "build": "tsc -p tsconfig.build.json",
+    "playground": "bun ./playground/index.html",
+    "playground:build": "bun run ./playground/build.ts",
     "prepublishOnly": "bun run clean && bun run build && bun run test && bun run lint:fix && bun run format:check"
   },
   "devDependencies": {
     "@ianvs/prettier-plugin-sort-imports": "^4.7.0",
     "@nkzw/eslint-config": "^3.3.0",
+    "@playwright/test": "^1.57.0",
+    "@testcontainers/postgresql": "^11.11.0",
+    "@testcontainers/valkey": "^11.11.0",
     "@types/bun": "latest",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "elysia": "^1.4.21",
     "eslint": "^9",
-    "knip": "^5.76.3",
-    "prettier": "^3"
+    "knip": "^5.80.0",
+    "prettier": "^3",
+    "testcontainers": "^11.11.0"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5",
+    "elysia": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "elysia": {
+      "optional": true
+    }
   },
   "publishConfig": {
     "access": "public"
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "dependencies": {
+    "commander": "^14.0.2",
+    "ioredis": "^5.9.0",
+    "jotai": "^2.16.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3"
+  },
+  "trustedDependencies": [
+    "protobufjs",
+    "unrs-resolver"
+  ]
 }

package/dist/utils.d.ts

@@ -1,2 +0,0 @@
-export declare const normalizePath: (p: string) => string;
-export declare const lettersFromMask: (mask: number) => string;