odgn-rights 0.2.0 → 0.5.1

package/dist/adapters/types.d.ts

@@ -0,0 +1,174 @@
+import { Flags } from '../constants';
+import type { Right } from '../right';
+import type { Rights } from '../rights';
+import type { Role } from '../role';
+import type { RoleRegistry } from '../role-registry';
+import type { Subject } from '../subject';
+export type RightsRow = {
+    allow_mask: number;
+    created_at: string;
+    deny_mask: number;
+    description: string | null;
+    id: number;
+    path: string;
+    priority: number;
+    tags: string | null;
+    updated_at: string;
+    valid_from: string | null;
+    valid_until: string | null;
+};
+export type RoleRow = {
+    created_at: string;
+    id: number;
+    name: string;
+    updated_at: string;
+};
+export type RoleRightRow = {
+    right_id: number;
+    role_id: number;
+};
+export type RoleInheritanceRow = {
+    child_role_id: number;
+    parent_role_id: number;
+};
+export type SubjectRow = {
+    created_at: string;
+    id: number;
+    identifier: string;
+    updated_at: string;
+};
+export type SubjectRoleRow = {
+    role_id: number;
+    subject_id: number;
+};
+export type SubjectRightRow = {
+    right_id: number;
+    subject_id: number;
+};
+/**
+ * Base configuration shared by all adapters
+ */
+export type BaseAdapterOptions = {
+    /**
+     * Prefix for all table names. Defaults to 'tbl_'.
+     * Set to empty string '' for no prefix.
+     */
+    tablePrefix?: string;
+};
+/**
+ * Table names with the configured prefix applied
+ */
+export type TableNames = {
+    rights: string;
+    roleInheritance: string;
+    roleRights: string;
+    roles: string;
+    subjectRights: string;
+    subjectRoles: string;
+    subjects: string;
+};
+/**
+ * Common interface for all database adapters.
+ * Supports both synchronous (SQLite) and asynchronous (PostgreSQL) patterns
+ * by using Promise-based methods throughout.
+ */
+export type DatabaseAdapter = {
+    /**
+     * Clear all data from the database (useful for testing)
+     */
+    clear(): Promise<void>;
+    /**
+     * Connect to the database
+     */
+    connect(): Promise<void>;
+    /**
+     * Delete a right by its database ID
+     * @returns true if the right was deleted, false if not found
+     */
+    deleteRight(id: number): Promise<boolean>;
+    /**
+     * Delete a role by name
+     * @returns true if the role was deleted, false if not found
+     */
+    deleteRole(name: string): Promise<boolean>;
+    /**
+     * Delete a subject by its external identifier
+     * @returns true if the subject was deleted, false if not found
+     */
+    deleteSubject(identifier: string): Promise<boolean>;
+    /**
+     * Disconnect from the database
+     */
+    disconnect(): Promise<void>;
+    /**
+     * 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
+     * @returns Array of subject identifiers that have access
+     */
+    findSubjectsWithAccess(pathPattern: string, flags: Flags): Promise<string[]>;
+    /**
+     * Load all roles into a new RoleRegistry
+     */
+    loadRegistry(): Promise<RoleRegistry>;
+    /**
+     * Load a right by its database ID
+     */
+    loadRight(id: number): Promise<Right | null>;
+    /**
+     * Load all rights from the database
+     */
+    loadRights(): Promise<Rights>;
+    /**
+     * Load rights matching a path pattern
+     */
+    loadRightsByPath(pathPattern: string): Promise<Rights>;
+    /**
+     * Load a role by name
+     */
+    loadRole(name: string): Promise<Role | null>;
+    /**
+     * Load all roles from the database
+     */
+    loadRoles(): Promise<Role[]>;
+    /**
+     * Load a subject by its external identifier
+     */
+    loadSubject(identifier: string): Promise<Subject | null>;
+    /**
+     * Run database migrations to create or update schema
+     */
+    migrate(): Promise<void>;
+    /**
+     * Save an entire role registry to the database
+     */
+    saveRegistry(registry: RoleRegistry): Promise<void>;
+    /**
+     * Save a single right to the database
+     * @returns The database ID of the saved right
+     */
+    saveRight(right: Right): Promise<number>;
+    /**
+     * Save multiple rights to the database
+     * @returns Array of database IDs for the saved rights
+     */
+    saveRights(rights: Rights): Promise<number[]>;
+    /**
+     * Save a role and its rights to the database
+     * @returns The database ID of the saved role
+     */
+    saveRole(role: Role): Promise<number>;
+    /**
+     * Save a subject with its roles and direct rights
+     * @param identifier External identifier for the subject (e.g., user ID)
+     * @param subject The subject to save
+     * @returns The database ID of the saved subject
+     */
+    saveSubject(identifier: string, subject: Subject): Promise<number>;
+    /**
+     * Execute operations within a transaction.
+     * The transaction will be committed if the function succeeds,
+     * or rolled back if it throws an error.
+     */
+    transaction<T>(fn: (adapter: DatabaseAdapter) => Promise<T>): Promise<T>;
+};

package/dist/adapters/types.js

@@ -0,0 +1 @@
+import { Flags } from '../constants';

package/dist/cli/commands/explain.js

@@ -1,6 +1,6 @@
 /* eslint-disable no-console */
 import { Command } from 'commander';
-import { lettersFromMask } from '../../utils';
+import { lettersFromMask } from '@/helpers';
 import { loadConfig } from '../helpers/config-loader';
 import { parseFlags } from '../helpers/flag-parser';
 import { colors, flagName, formatResult } from '../helpers/output';
@@ -30,7 +30,9 @@ export const explainCommand = new Command('explain')
                 details: explanation.details.map(d => ({
                     allowed: d.allowed,
                     flag: flagName(d.bit),
-                    rule: d.right?.toString()
+                    priority: d.right?.priority,
+                    rule: d.right?.toString(),
+                    specificity: d.right?.specificity()
                 })),
                 flag: options.flag,
                 path: options.path
@@ -55,12 +57,18 @@ export const explainCommand = new Command('explain')
         // Show all matching rules
         const allRights = rights.allRights().filter(r => r.matches(options.path));
         if (allRights.length > 0) {
-            console.log(`\n${colors.bold('Matching rules (by specificity):')}`);
+            console.log(`\n${colors.bold('Matching rules (by priority, then specificity):')}`);
             allRights
-                .sort((a, b) => b.specificity() - a.specificity())
+                .sort((a, b) => {
+                const pDiff = b.priority - a.priority;
+                if (pDiff !== 0) {
+                    return pDiff;
+                }
+                return b.specificity() - a.specificity();
+            })
                 .forEach((r, i) => {
                 console.log(`  ${i + 1}. ${colors.cyan(r.toString())}`);
-                console.log(`     Specificity: ${r.specificity()}`);
+                console.log(`     Priority: ${r.priority}, Specificity: ${r.specificity()}`);
                 if (r.tags.length > 0) {
                     console.log(`     Tags: ${r.tags.join(', ')}`);
                 }

package/dist/helpers.d.ts

@@ -0,0 +1,16 @@
+export type ParsedPath = {
+    negated: boolean;
+    path: string;
+};
+/**
+ * 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 declare const parsePath: (p: string) => ParsedPath;
+export declare const normalizePath: (p: string) => string;
+export declare const lettersFromMask: (mask: number) => string;

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 {};