odgn-rights 0.2.0 → 0.5.0

package/dist/integrations/elysia.js

@@ -0,0 +1,375 @@
+/**
+ * ElysiaJS integration for odgn-rights
+ *
+ * @module odgn-rights/integrations/elysia
+ *
+ * This module provides middleware and utilities for integrating
+ * odgn-rights with ElysiaJS applications.
+ *
+ * @example
+ * ```typescript
+ * import { Elysia } from 'elysia';
+ * import { elysiaRights } from 'odgn-rights/integrations/elysia';
+ *
+ * const app = new Elysia()
+ *   .use(elysiaRights({
+ *     registry: subjectRegistry,
+ *     getSubject: ({ headers }) => headers.get('x-user-id')
+ *   }))
+ *   .get('/users', () => 'list users')
+ *   .listen(3000);
+ * ```
+ */
+/**
+ * HTTP method to Flags mapping
+ */
+const DEFAULT_METHOD_FLAG_MAP = {
+    DELETE: 4, // DELETE
+    GET: 1, // READ
+    HEAD: 1,
+    OPTIONS: 1,
+    PATCH: 2,
+    POST: 8, // CREATE
+    PUT: 2 // WRITE
+};
+/**
+ * Create an Elysia plugin for rights-based authorization.
+ *
+ * @example Using with SubjectRegistry
+ * ```typescript
+ * import { Elysia } from 'elysia';
+ * import { elysiaRights } from 'odgn-rights/integrations/elysia';
+ *
+ * const app = new Elysia()
+ *   .use(elysiaRights({
+ *     registry: subjectRegistry,
+ *     getSubject: ({ headers }) => headers.get('x-user-id')
+ *   }))
+ *   .get('/users', () => 'list users')
+ *   .listen(3000);
+ * ```
+ *
+ * @example Using with direct Subject
+ * ```typescript
+ * const app = new Elysia()
+ *   .derive(({ headers }) => ({
+ *     user: getUserFromToken(headers.get('authorization'))
+ *   }))
+ *   .use(elysiaRights({
+ *     getSubject: ({ user }) => user?.subject
+ *   }))
+ *   .get('/users', () => 'list users')
+ *   .listen(3000);
+ * ```
+ */
+export const elysiaRights = (options) => {
+    // Dynamic import to avoid requiring elysia as a hard dependency
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { Elysia } = require('elysia');
+    const { flagMapper, getContext, getSubject, onNoSubject, onUnauthorized, pathMapper, registry } = options;
+    return new Elysia({ name: 'odgn-rights' }).onBeforeHandle({ as: 'scoped' }, async ({ path, request, set, ...rest }) => {
+        const method = request.method;
+        // Get the subject
+        const subjectOrId = await getSubject({
+            headers: request.headers,
+            path,
+            request,
+            ...rest
+        });
+        let subject;
+        if (subjectOrId === null || subjectOrId === undefined) {
+            if (onNoSubject) {
+                return onNoSubject({ path, request });
+            }
+            set.status = 401;
+            return { error: 'Unauthorized', message: 'No subject found' };
+        }
+        if (typeof subjectOrId === 'string') {
+            if (!registry) {
+                throw new Error('elysiaRights: registry is required when getSubject returns a string identifier');
+            }
+            subject = registry.get(subjectOrId);
+            if (!subject) {
+                if (onNoSubject) {
+                    return onNoSubject({ path, request });
+                }
+                set.status = 401;
+                return { error: 'Unauthorized', message: 'Subject not found' };
+            }
+        }
+        else {
+            subject = subjectOrId;
+        }
+        // Map the path
+        const rightsPath = pathMapper
+            ? pathMapper({ method, path, request })
+            : path;
+        // Get the required flags
+        const requiredFlags = flagMapper
+            ? flagMapper({ method, path, request })
+            : (DEFAULT_METHOD_FLAG_MAP[method] ?? 1); // Default to READ
+        // Get condition context if provided
+        const context = getContext
+            ? await getContext({
+                headers: request.headers,
+                path,
+                request,
+                subject,
+                ...rest
+            })
+            : undefined;
+        // Check permission
+        const allowed = subject.has(rightsPath, requiredFlags, context);
+        if (!allowed) {
+            if (onUnauthorized) {
+                return onUnauthorized({
+                    path: rightsPath,
+                    request,
+                    requiredFlags,
+                    subject
+                });
+            }
+            set.status = 403;
+            return { error: 'Forbidden', message: 'Access denied' };
+        }
+        // Permission granted, continue to handler
+    });
+};
+/**
+ * Create an Elysia plugin for rights-based authorization using a Rights instance directly.
+ * Use this when you don't need subject/role-based access control.
+ *
+ * @example
+ * ```typescript
+ * import { Elysia } from 'elysia';
+ * import { elysiaRightsStandalone } from 'odgn-rights/integrations/elysia';
+ * import { Rights, Flags } from 'odgn-rights';
+ *
+ * const rights = new Rights();
+ * rights.allow('/api/**', Flags.READ);
+ * rights.allow('/api/admin/**', Flags.ALL);
+ *
+ * const app = new Elysia()
+ *   .use(elysiaRightsStandalone({ rights }))
+ *   .get('/api/users', () => 'list users')
+ *   .listen(3000);
+ * ```
+ */
+export const elysiaRightsStandalone = (options) => {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { Elysia } = require('elysia');
+    const { flagMapper, getContext, onUnauthorized, pathMapper, rights } = options;
+    return new Elysia({ name: 'odgn-rights-standalone' }).onBeforeHandle({ as: 'scoped' }, async ({ path, request, set, ...rest }) => {
+        const method = request.method;
+        // Map the path
+        const rightsPath = pathMapper
+            ? pathMapper({ method, path, request })
+            : path;
+        // Get the required flags
+        const requiredFlags = flagMapper
+            ? flagMapper({ method, path, request })
+            : (DEFAULT_METHOD_FLAG_MAP[method] ?? 1);
+        // Get condition context if provided
+        const context = getContext
+            ? await getContext({
+                headers: request.headers,
+                path,
+                request,
+                subject: undefined,
+                ...rest
+            })
+            : undefined;
+        // Check permission
+        const allowed = rights.has(rightsPath, requiredFlags, context);
+        if (!allowed) {
+            if (onUnauthorized) {
+                return onUnauthorized({
+                    path: rightsPath,
+                    request,
+                    requiredFlags,
+                    subject: undefined
+                });
+            }
+            set.status = 403;
+            return { error: 'Forbidden', message: 'Access denied' };
+        }
+    });
+};
+/**
+ * Create a guard configuration for use with Elysia's .guard() method.
+ * This allows more fine-grained control over which routes are protected.
+ *
+ * @example
+ * ```typescript
+ * import { Elysia } from 'elysia';
+ * import { createRightsGuard } from 'odgn-rights/integrations/elysia';
+ *
+ * const guard = createRightsGuard({
+ *   registry: subjectRegistry,
+ *   getSubject: ({ headers }) => headers.get('x-user-id')
+ * });
+ *
+ * const app = new Elysia()
+ *   .get('/public', () => 'anyone can see this')
+ *   .guard(guard, (app) =>
+ *     app
+ *       .get('/protected', () => 'only authorized users')
+ *       .post('/protected', () => 'create something')
+ *   )
+ *   .listen(3000);
+ * ```
+ */
+export const createRightsGuard = (options) => {
+    const { flagMapper, getContext, getSubject, onNoSubject, onUnauthorized, pathMapper, registry } = options;
+    return {
+        async beforeHandle({ path, request, set, ...rest }) {
+            const method = request.method;
+            const subjectOrId = await getSubject({
+                headers: request.headers,
+                path,
+                request,
+                ...rest
+            });
+            let subject;
+            if (subjectOrId === null || subjectOrId === undefined) {
+                if (onNoSubject) {
+                    return onNoSubject({ path, request });
+                }
+                set.status = 401;
+                return { error: 'Unauthorized', message: 'No subject found' };
+            }
+            if (typeof subjectOrId === 'string') {
+                if (!registry) {
+                    throw new Error('createRightsGuard: registry is required when getSubject returns a string identifier');
+                }
+                subject = registry.get(subjectOrId);
+                if (!subject) {
+                    if (onNoSubject) {
+                        return onNoSubject({ path, request });
+                    }
+                    set.status = 401;
+                    return { error: 'Unauthorized', message: 'Subject not found' };
+                }
+            }
+            else {
+                subject = subjectOrId;
+            }
+            const rightsPath = pathMapper
+                ? pathMapper({ method, path, request })
+                : path;
+            const requiredFlags = flagMapper
+                ? flagMapper({ method, path, request })
+                : (DEFAULT_METHOD_FLAG_MAP[method] ?? 1);
+            const context = getContext
+                ? await getContext({
+                    headers: request.headers,
+                    path,
+                    request,
+                    subject,
+                    ...rest
+                })
+                : undefined;
+            const allowed = subject.has(rightsPath, requiredFlags, context);
+            if (!allowed) {
+                if (onUnauthorized) {
+                    return onUnauthorized({
+                        path: rightsPath,
+                        request,
+                        requiredFlags,
+                        subject
+                    });
+                }
+                set.status = 403;
+                return { error: 'Forbidden', message: 'Access denied' };
+            }
+        }
+    };
+};
+/**
+ * Create a macro for declarative per-route authorization.
+ * This allows you to specify rights requirements directly on route definitions.
+ *
+ * @example
+ * ```typescript
+ * import { Elysia } from 'elysia';
+ * import { createRightsMacro } from 'odgn-rights/integrations/elysia';
+ * import { Flags } from 'odgn-rights';
+ *
+ * const rightsMacro = createRightsMacro({
+ *   registry: subjectRegistry,
+ *   getSubject: ({ headers }) => headers.get('x-user-id')
+ * });
+ *
+ * const app = new Elysia()
+ *   .use(rightsMacro)
+ *   .get('/public', () => 'anyone')
+ *   .get('/users', () => 'list users', {
+ *     rights: { path: '/users', flags: Flags.READ }
+ *   })
+ *   .delete('/users/:id', () => 'delete user', {
+ *     rights: { path: '/users/*', flags: Flags.DELETE }
+ *   })
+ *   .listen(3000);
+ * ```
+ */
+export const createRightsMacro = (options) => {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { Elysia } = require('elysia');
+    const { getContext, getSubject, onNoSubject, onUnauthorized, registry } = options;
+    return new Elysia({ name: 'odgn-rights-macro' }).macro({
+        rights: (rightsConfig) => ({
+            async resolve({ path, request, set, status, ...rest }) {
+                const subjectOrId = await getSubject({
+                    headers: request.headers,
+                    path,
+                    request,
+                    ...rest
+                });
+                let subject;
+                if (subjectOrId === null || subjectOrId === undefined) {
+                    if (onNoSubject) {
+                        return onNoSubject({ path, request });
+                    }
+                    return status(401);
+                }
+                if (typeof subjectOrId === 'string') {
+                    if (!registry) {
+                        throw new Error('createRightsMacro: registry is required when getSubject returns a string identifier');
+                    }
+                    subject = registry.get(subjectOrId);
+                    if (!subject) {
+                        if (onNoSubject) {
+                            return onNoSubject({ path, request });
+                        }
+                        return status(401);
+                    }
+                }
+                else {
+                    subject = subjectOrId;
+                }
+                const context = getContext
+                    ? await getContext({
+                        headers: request.headers,
+                        path,
+                        request,
+                        subject,
+                        ...rest
+                    })
+                    : undefined;
+                const allowed = subject.has(rightsConfig.path, rightsConfig.flags, context);
+                if (!allowed) {
+                    if (onUnauthorized) {
+                        return onUnauthorized({
+                            path: rightsConfig.path,
+                            request,
+                            requiredFlags: rightsConfig.flags,
+                            subject
+                        });
+                    }
+                    return status(403);
+                }
+                return { subject };
+            }
+        })
+    });
+};

package/dist/right.d.ts

@@ -6,6 +6,7 @@ export type RightInit = {
     condition?: Condition;
     deny?: Flags[];
     description?: string;
+    priority?: number;
     tags?: string[];
     validFrom?: Date;
     validUntil?: Date;
@@ -20,7 +21,9 @@ export declare class Right {
     readonly validUntil?: Date;
     private readonly _tags;
     private readonly _specificity;
+    private readonly _priority;
     private readonly _re?;
+    private _dbId?;
     constructor(path: string, init?: RightInit);
     allow(flag: Flags): this;
     deny(flag: Flags): this;
@@ -35,18 +38,22 @@ export declare class Right {
     isExpired(now?: Date): boolean;
     get allowMaskValue(): number;
     get denyMaskValue(): number;
+    get dbId(): number | undefined;
+    _setDbId(id: number): void;
     toString(): string;
     toJSON(): {
         allow: string;
         deny?: string;
         description?: string;
         path: string;
+        priority?: number;
         tags?: string[];
         validFrom?: string;
         validUntil?: string;
     };
     matches(targetPath: string): boolean;
     specificity(): number;
+    get priority(): number;
     private calculateSpecificity;
     private static globToRegExp;
     static parse(input: string): Right;

package/dist/right.js

@@ -1,15 +1,17 @@
 import { ALL_BITS, Flags, hasBit } from './constants';
-import { lettersFromMask, normalizePath } from './utils';
+import { lettersFromMask, normalizePath, parsePath } from './helpers';
 export class Right {
     constructor(path, init) {
         this.allowMask = 0;
         this.denyMask = 0;
-        this.path = normalizePath(path);
+        const parsed = parsePath(path);
+        this.path = parsed.path;
         this.description = init?.description;
         this.condition = init?.condition;
         this.validFrom = init?.validFrom;
         this.validUntil = init?.validUntil;
         this._tags = new Set(init?.tags);
+        this._priority = init?.priority ?? 0;
         if (this.validFrom && this.validUntil && this.validFrom > this.validUntil) {
             throw new Error('validFrom must be before validUntil');
         }
@@ -17,11 +19,23 @@ export class Right {
         if (this.path.includes('*') || this.path.includes('?')) {
             this._re = Right.globToRegExp(this.path);
         }
-        if (init?.allow) {
-            init.allow.forEach(f => this.allow(f));
+        // When path is negated (!path), swap allow and deny semantics
+        // allow becomes deny, deny becomes allow
+        if (parsed.negated) {
+            if (init?.allow) {
+                init.allow.forEach(f => this.deny(f));
+            }
+            if (init?.deny) {
+                init.deny.forEach(f => this.allow(f));
+            }
         }
-        if (init?.deny) {
-            init.deny.forEach(f => this.deny(f));
+        else {
+            if (init?.allow) {
+                init.allow.forEach(f => this.allow(f));
+            }
+            if (init?.deny) {
+                init.deny.forEach(f => this.deny(f));
+            }
         }
     }
     allow(flag) {
@@ -102,6 +116,12 @@ export class Right {
     get denyMaskValue() {
         return this.denyMask;
     }
+    get dbId() {
+        return this._dbId;
+    }
+    _setDbId(id) {
+        this._dbId = id;
+    }
     toString() {
         const denyLetters = lettersFromMask(this.denyMask);
         const allowLetters = lettersFromMask(this.allowMask);
@@ -114,6 +134,9 @@ export class Right {
         }
         const left = parts.join('');
         let res = `${left}:${this.path}`;
+        if (this._priority !== 0) {
+            res += `^${this._priority}`;
+        }
         if (this._tags.size > 0) {
             res += `#${this.tags.join(',')}`;
         }
@@ -137,6 +160,9 @@ export class Right {
         if (this.description) {
             out.description = this.description;
         }
+        if (this._priority !== 0) {
+            out.priority = this._priority;
+        }
         if (this._tags.size > 0) {
             out.tags = this.tags;
         }
@@ -164,6 +190,9 @@ export class Right {
     specificity() {
         return this._specificity;
     }
+    get priority() {
+        return this._priority;
+    }
     calculateSpecificity() {
         const parts = this.path.split('/').filter(p => p.length > 0);
         let literalCount = 0;
@@ -213,6 +242,7 @@ export class Right {
         let pathStr = '';
         let tagsStr = '';
         let timeStr = '';
+        let priorityStr = '';
         let pathEndIdx = s.length;
         if (atIdx !== -1) {
             timeStr = s.slice(atIdx + 1);
@@ -222,6 +252,13 @@ export class Right {
             tagsStr = s.slice(hashIdx + 1, pathEndIdx);
             pathEndIdx = hashIdx;
         }
+        // Find ^ for priority (between path and #/@)
+        const pathStartIdx = colonIdx === -1 ? 0 : colonIdx + 1;
+        const caretIdx = s.indexOf('^', pathStartIdx);
+        if (caretIdx !== -1 && caretIdx < pathEndIdx) {
+            priorityStr = s.slice(caretIdx + 1, pathEndIdx);
+            pathEndIdx = caretIdx;
+        }
         if (colonIdx === -1) {
             pathStr = s.slice(0, pathEndIdx);
         }
@@ -250,11 +287,20 @@ export class Right {
         if (tagsStr) {
             init.tags = tagsStr.split(',').map(t => t.trim());
         }
-        const r = new Right(pathStr, init);
+        if (priorityStr) {
+            const p = Number.parseInt(priorityStr, 10);
+            if (!Number.isNaN(p)) {
+                init.priority = p;
+            }
+        }
+        // Check if path is negated (starts with !)
+        const parsed = parsePath(pathStr);
+        const r = new Right(parsed.path, init);
         if (!flagsStr) {
             return r;
         }
         // parse groups like '-abc+xyz' or '+xyz-abc'
+        // When path is negated, swap the meaning of + and -
         let i = 0;
         while (i < flagsStr.length) {
             const sign = flagsStr[i];
@@ -270,7 +316,16 @@ export class Right {
                 letters += flagsStr[i];
                 i++;
             }
-            const apply = sign === '+' ? (f) => r.allow(f) : (f) => r.deny(f);
+            // When negated: + becomes deny, - becomes allow
+            let apply;
+            if (parsed.negated) {
+                apply =
+                    sign === '+' ? (f) => r.deny(f) : (f) => r.allow(f);
+            }
+            else {
+                apply =
+                    sign === '+' ? (f) => r.allow(f) : (f) => r.deny(f);
+            }
             if (letters === '*') {
                 apply(Flags.ALL);
                 continue;

package/dist/rights.d.ts

@@ -5,6 +5,7 @@ export type RightJSON = {
     deny?: string;
     description?: string;
     path: string;
+    priority?: number;
     tags?: string[];
     validFrom?: string;
     validUntil?: string;
@@ -24,6 +25,20 @@ export declare class Rights {
     allRights(): Right[];
     allow(path: string, ...flags: Flags[]): this;
     deny(path: string, flag: Flags): this;
+    /**
+     * Exclude (deny) specific flags for a path pattern.
+     * This is equivalent to calling deny() for each flag but accepts multiple flags.
+     * Provides clearer semantics for exclusion patterns.
+     *
+     * @example
+     * rights.allow('/api/**', Flags.READ);
+     * rights.exclude('/api/internal/**', Flags.READ); // Deny read on internal paths
+     *
+     * @example
+     * rights.allow('/files/**', Flags.ALL);
+     * rights.exclude('/files/system/**', Flags.DELETE, Flags.WRITE); // Protect system files
+     */
+    exclude(path: string, ...flags: Flags[]): this;
     private matchOrdered;
     has(path: string, flag: Flags, context?: ConditionContext): boolean;
     explain(path: string, flag: Flags, context?: ConditionContext): {
@@ -42,6 +57,10 @@ export declare class Rights {
     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[];
     toString(): string;
     toJSON(): RightJSON[];
     static fromJSON(arr: RightJSON[]): Rights;

package/dist/rights.js

@@ -1,6 +1,6 @@
 import { ALL_BITS, Flags, hasBit } from './constants';
+import { normalizePath } from './helpers';
 import { Right } from './right';
-import { normalizePath } from './utils';
 export class Rights {
     constructor() {
         this.list = [];
@@ -94,6 +94,40 @@ export class Rights {
         this.notify();
         return this;
     }
+    /**
+     * Exclude (deny) specific flags for a path pattern.
+     * This is equivalent to calling deny() for each flag but accepts multiple flags.
+     * Provides clearer semantics for exclusion patterns.
+     *
+     * @example
+     * rights.allow('/api/**', Flags.READ);
+     * rights.exclude('/api/internal/**', Flags.READ); // Deny read on internal paths
+     *
+     * @example
+     * rights.allow('/files/**', Flags.ALL);
+     * rights.exclude('/files/system/**', Flags.DELETE, Flags.WRITE); // Protect system files
+     */
+    exclude(path, ...flags) {
+        // Strip leading ! if present (user might write exclude('!/path'))
+        const cleanPath = path.startsWith('!') ? path.slice(1) : path;
+        const p = normalizePath(cleanPath);
+        let r = this.list.find(x => x.path === p);
+        if (!r) {
+            r = new Right(p);
+            this.list.push(r);
+        }
+        else {
+            // Invalidate cache if we update an existing right
+            this.matchCache.clear();
+        }
+        // Support spreading an array: exclude(path, [Flags.READ, Flags.WRITE] as any)
+        const flat = [].concat(...flags);
+        for (const f of flat) {
+            r.deny(f);
+        }
+        this.notify();
+        return this;
+    }
     matchOrdered(path) {
         const cached = this.matchCache.get(path);
         if (cached) {
@@ -101,7 +135,15 @@ export class Rights {
         }
         const result = this.list
             .filter(r => r.matches(path))
-            .sort((a, b) => b.specificity() - a.specificity());
+            .sort((a, b) => {
+            // Priority first (higher wins)
+            const pDiff = b.priority - a.priority;
+            if (pDiff !== 0) {
+                return pDiff;
+            }
+            // Then specificity
+            return b.specificity() - a.specificity();
+        });
         this.matchCache.set(path, result);
         return result;
     }
@@ -177,6 +219,9 @@ export class Rights {
     execute(path, context) {
         return this.has(path, Flags.EXECUTE, context);
     }
+    checkMany(requests, context) {
+        return requests.map(req => this.has(req.path, req.flags, context));
+    }
     toString() {
         return this.list.map(r => r.toString()).join(', ');
     }
@@ -189,6 +234,7 @@ export class Rights {
             const p = normalizePath(item.path);
             const init = {
                 description: item.description,
+                priority: item.priority,
                 tags: item.tags
             };
             if (item.validFrom) {