odgn-rights 0.1.0 → 0.5.0

package/dist/{utils.js → helpers.js}

@@ -1,4 +1,26 @@
 import { Flags, hasBit } from './constants';
+/**
+ * Parse a path string, detecting and stripping negation prefix.
+ * Handles double negation (!! becomes positive).
+ *
+ * @example
+ * parsePath('!/api/internal') // { path: '/api/internal', negated: true }
+ * parsePath('/api/public')    // { path: '/api/public', negated: false }
+ * parsePath('!!/api/path')    // { path: '/api/path', negated: false }
+ */
+export const parsePath = (p) => {
+    let trimmed = p.trim();
+    let negated = false;
+    // Handle negation prefix(es) - !! cancels out
+    while (trimmed.startsWith('!')) {
+        negated = !negated;
+        trimmed = trimmed.slice(1).trimStart();
+    }
+    return {
+        negated,
+        path: normalizePath(trimmed)
+    };
+};
 export const normalizePath = (p) => {
     if (!p) {
         return '/';

package/dist/index.d.ts

@@ -4,4 +4,6 @@ export * from './rights';
 export * from './role';
 export * from './role-registry';
 export * from './subject';
-export * from './utils';
+export * from './subject-registry';
+export * from './helpers';
+export * from './adapters';

package/dist/index.js

@@ -4,4 +4,6 @@ export * from './rights';
 export * from './role';
 export * from './role-registry';
 export * from './subject';
-export * from './utils';
+export * from './subject-registry';
+export * from './helpers';
+export * from './adapters';

package/dist/integrations/elysia.d.ts

@@ -0,0 +1,235 @@
+/**
+ * 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);
+ * ```
+ */
+import type { Flags } from '../constants';
+import type { ConditionContext } from '../right';
+import type { Rights } from '../rights';
+import type { Subject } from '../subject';
+import type { SubjectRegistry } from '../subject-registry';
+/**
+ * Configuration options for the Elysia rights middleware
+ */
+export type ElysiaRightsOptions<Store = unknown, Derive = unknown> = {
+    /**
+     * Function to determine the required flags based on the request.
+     * Defaults to mapping HTTP methods to flags:
+     * - GET, HEAD, OPTIONS -> READ
+     * - POST -> CREATE
+     * - PUT, PATCH -> WRITE
+     * - DELETE -> DELETE
+     */
+    flagMapper?: (ctx: {
+        method: string;
+        path: string;
+        request: Request;
+    }) => Flags;
+    /**
+     * Function to build the condition context for ABAC-style checks.
+     * The returned context is passed to the permission check.
+     */
+    getContext?: (ctx: {
+        headers: Headers;
+        path: string;
+        request: Request;
+        store: Store;
+        subject: Subject;
+    } & Derive) => ConditionContext | Promise<ConditionContext>;
+    /**
+     * Function to extract the subject or subject identifier from the request context.
+     * If registry is provided, this should return a string identifier.
+     * Otherwise, it should return a Subject instance directly.
+     */
+    getSubject: (ctx: {
+        headers: Headers;
+        path: string;
+        request: Request;
+        store: Store;
+    } & Derive) => string | Subject | undefined | null | Promise<string | Subject | undefined | null>;
+    /**
+     * Custom handler when no subject is found.
+     * Defaults to returning 401 status.
+     */
+    onNoSubject?: (ctx: {
+        path: string;
+        request: Request;
+    }) => Response | Promise<Response>;
+    /**
+     * Custom handler for unauthorized responses.
+     * Defaults to returning 403 status.
+     */
+    onUnauthorized?: (ctx: {
+        path: string;
+        request: Request;
+        requiredFlags: Flags;
+        subject?: Subject;
+    }) => Response | Promise<Response>;
+    /**
+     * Function to map the request path to a rights path.
+     * Useful for stripping prefixes or transforming paths.
+     * Defaults to using the request path as-is.
+     */
+    pathMapper?: (ctx: {
+        method: string;
+        path: string;
+        request: Request;
+    }) => string;
+    /**
+     * The SubjectRegistry to look up subjects from.
+     * If provided, getSubject should return the subject identifier.
+     */
+    registry?: SubjectRegistry;
+};
+/**
+ * Options for standalone rights-based checks (without subjects)
+ */
+export type ElysiaRightsStandaloneOptions<Store = unknown, Derive = unknown> = Omit<ElysiaRightsOptions<Store, Derive>, 'registry' | 'getSubject'> & {
+    /**
+     * A Rights instance to check against directly.
+     * Use this when you don't need subject/role-based access control.
+     */
+    rights: Rights;
+};
+type ElysiaContext = {
+    [key: string]: unknown;
+    path: string;
+    request: Request;
+    set: {
+        status?: number | string;
+    };
+};
+/**
+ * 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 declare const elysiaRights: <Store = unknown, Derive = unknown>(options: ElysiaRightsOptions<Store, Derive>) => any;
+/**
+ * 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 declare const elysiaRightsStandalone: <Store = unknown, Derive = unknown>(options: ElysiaRightsStandaloneOptions<Store, Derive>) => any;
+/**
+ * Type for beforeHandle guard configuration
+ */
+export type RightsGuardConfig = {
+    beforeHandle: (ctx: ElysiaContext) => Promise<Response | object | void>;
+};
+/**
+ * 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 declare const createRightsGuard: <Store = unknown, Derive = unknown>(options: ElysiaRightsOptions<Store, Derive>) => {
+    beforeHandle({ path, request, set, ...rest }: ElysiaContext): Promise<Response | {
+        error: string;
+        message: string;
+    } | undefined>;
+};
+/**
+ * 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 declare const createRightsMacro: <Store = unknown, Derive = unknown>(options: ElysiaRightsOptions<Store, Derive>) => any;
+export {};

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 };
+            }
+        })
+    });
+};