odgn-rights 0.2.0 → 0.5.0

package/README.md

@@ -98,6 +98,100 @@ rights.write('/posts/1', { userId: 'abc', ownerId: 'xyz' }); // false
 - `**` matches across segments (`/*/device/**`)
 - `?` matches a single character (no slash)
 
+## Rule Priority
+
+By default, rules are matched by **specificity** — the most specific matching rule wins. However, you can override this with explicit **priority** values.
+
+### How Priority Works
+
+1. **Higher priority wins** regardless of specificity
+2. **Equal priorities** fall back to specificity comparison
+3. **Default priority is 0** when not specified
+4. **Negative priorities** can deprioritize rules below the default
+
+```ts
+const rights = new Rights();
+
+// Specific path, default priority (0)
+rights.add(
+  new Right('/posts/123', {
+    allow: [Flags.READ],
+    deny: [Flags.WRITE]
+  })
+);
+
+// Wildcard path, but high priority (100) — this rule wins!
+rights.add(
+  new Right('/posts/*', {
+    allow: [Flags.READ, Flags.WRITE],
+    priority: 100
+  })
+);
+
+rights.write('/posts/123'); // true — high-priority wildcard rule wins
+```
+
+### Priority in Serialization
+
+Priority is included in both text and JSON serialization formats.
+
+**Text format** uses `^` after the path:
+
+```ts
+const right = new Right('/posts/*', {
+  allow: [Flags.WRITE],
+  priority: 100
+});
+right.toString(); // "+w:/posts/*^100"
+
+// With tags and time ranges
+// Format: [flags]:[path]^[priority]#[tags]@[validFrom]/[validUntil]
+Right.parse('+rw:/admin/*^50#secure');
+```
+
+**JSON format** includes an optional `priority` field:
+
+```json
+[
+  { "path": "/posts/*", "allow": "rw", "priority": 100 },
+  { "path": "/posts/123", "allow": "r", "deny": "w" }
+]
+```
+
+Priority is omitted from serialization when it equals 0 (the default).
+
+### Use Cases
+
+- **Emergency overrides**: Grant temporary high-priority access that bypasses normal rules
+- **Default deny rules**: Use negative priority for fallback deny rules
+- **Policy layers**: Implement organizational policies at different priority levels
+
+```ts
+// Low-priority default: deny all writes
+rights.add(
+  new Right('/**', {
+    deny: [Flags.WRITE],
+    priority: -100
+  })
+);
+
+// Normal priority: department-level permissions
+rights.add(
+  new Right('/dept/engineering/**', {
+    allow: [Flags.READ, Flags.WRITE]
+  })
+);
+
+// High priority: emergency maintenance access
+rights.add(
+  new Right('/system/**', {
+    allow: [Flags.ALL],
+    priority: 1000,
+    tags: ['emergency']
+  })
+);
+```
+
 ## JSON Round‑Trip
 
 ```ts
@@ -106,6 +200,74 @@ const json = rights.toJSON();
 const loaded = Rights.fromJSON(json);
 ```
 
+## Batch Permission Checks
+
+Efficiently check multiple permissions at once with `checkMany()`.
+
+### Basic Usage
+
+```ts
+const rights = new Rights();
+rights.allow('/users/*', Flags.READ);
+rights.allow('/posts/*', Flags.WRITE);
+rights.deny('/admin', Flags.ALL);
+
+const results = rights.checkMany([
+  { path: '/users/1', flags: Flags.READ },
+  { path: '/posts/1', flags: Flags.WRITE },
+  { path: '/admin', flags: Flags.ALL }
+]);
+// Returns: [true, true, false]
+```
+
+### With Context
+
+The same context is shared across all checks:
+
+```ts
+rights.add(
+  new Right('/posts/*', {
+    allow: [Flags.WRITE],
+    condition: ctx => ctx.userId === ctx.ownerId
+  })
+);
+
+const results = rights.checkMany(
+  [
+    { path: '/posts/1', flags: Flags.WRITE },
+    { path: '/posts/2', flags: Flags.WRITE },
+    { path: '/posts/3', flags: Flags.WRITE }
+  ],
+  { userId: 'user1', ownerId: 'user1' }
+);
+// Returns: [true, true, true]
+```
+
+### With Subjects
+
+Works with subjects that have multiple roles:
+
+```ts
+const viewer = new Role('viewer', new Rights().allow('/docs', Flags.READ));
+const writer = new Role('writer', new Rights().allow('/docs', Flags.WRITE));
+
+const subject = new Subject().memberOf(viewer).memberOf(writer);
+
+const results = subject.checkMany([
+  { path: '/docs', flags: Flags.READ },
+  { path: '/docs', flags: Flags.WRITE },
+  { path: '/docs', flags: Flags.DELETE }
+]);
+// Returns: [true, true, false]
+```
+
+### Use Cases
+
+- **Bulk authorization**: Check multiple resource permissions in a single call
+- **Feature flags**: Enable/disable multiple features based on permissions
+- **API responses**: Include permission information for multiple resources
+- **UI rendering**: Determine visibility of multiple UI elements efficiently
+
 ## CLI Tool
 
 The CLI tool helps test and debug permission configurations from the command line.
@@ -226,3 +388,209 @@ The CLI supports two configuration formats:
 | ALL     | \*     | All permissions    |
 
 Flags can be combined: `RW`, `READ,WRITE`, `RWCDX`
+
+## Database Adapters
+
+Database adapters enable persistent storage of rights configurations in SQLite or PostgreSQL databases. This is useful for applications that need to load permissions from a database, share configurations across services, or audit permission changes.
+
+### Installation
+
+The adapters use Bun's built-in database drivers (`bun:sqlite` and `bun` SQL), so no additional dependencies are required.
+
+```ts
+import { PostgresAdapter, SQLiteAdapter } from 'odgn-rights/adapters';
+```
+
+### Table Prefix
+
+All adapters support a configurable table prefix. The default prefix is `tbl_`.
+
+```ts
+// Default prefix creates tables: tbl_rights, tbl_roles, etc.
+const adapter = new SQLiteAdapter({ filename: './permissions.db' });
+
+// Custom prefix creates tables: auth_rights, auth_roles, etc.
+const adapter = new SQLiteAdapter({
+  filename: './permissions.db',
+  tablePrefix: 'auth_'
+});
+
+// No prefix creates tables: rights, roles, etc.
+const adapter = new SQLiteAdapter({
+  filename: './permissions.db',
+  tablePrefix: ''
+});
+```
+
+### SQLite Adapter
+
+SQLite is ideal for single-process applications, embedded systems, or local development.
+
+```ts
+import { Flags, Right, Rights } from 'odgn-rights';
+import { SQLiteAdapter } from 'odgn-rights/adapters';
+
+// Create adapter and connect
+const adapter = new SQLiteAdapter({
+  filename: './permissions.db', // Use ':memory:' for in-memory
+  enableWAL: true // Enable WAL mode for better concurrency
+});
+
+await adapter.connect();
+await adapter.migrate();
+
+// Save rights
+const rights = new Rights();
+rights.allow('/users/*', Flags.READ);
+rights.allow('/admin/**', Flags.ALL);
+await adapter.saveRights(rights);
+
+// Load rights
+const loaded = await adapter.loadRights();
+loaded.has('/users/123', Flags.READ); // true
+
+// Save and load roles
+const { Role, RoleRegistry } = await import('odgn-rights');
+const registry = new RoleRegistry();
+const admin = registry.define('admin');
+admin.rights.allow('/**', Flags.ALL);
+await registry.saveTo(adapter);
+
+// Load registry from database
+const loadedRegistry = await RoleRegistry.loadFrom(adapter);
+
+await adapter.disconnect();
+```
+
+### PostgreSQL Adapter
+
+PostgreSQL is ideal for multi-process applications, microservices, or when you need shared access to permissions.
+
+```ts
+import { Flags, RoleRegistry, Subject } from 'odgn-rights';
+import { PostgresAdapter } from 'odgn-rights/adapters';
+
+const adapter = new PostgresAdapter({
+  url: 'postgres://user:pass@localhost:5432/mydb',
+  // Or use individual options:
+  // hostname: 'localhost',
+  // port: 5432,
+  // database: 'mydb',
+  // username: 'user',
+  // password: 'pass',
+  tablePrefix: 'perms_' // Optional custom prefix
+});
+
+await adapter.connect();
+await adapter.migrate();
+
+// Load registry and make changes
+const registry = await adapter.loadRegistry();
+const editor = registry.define('editor');
+editor.rights.allow('/content/**', Flags.READ, Flags.WRITE);
+
+// Save back
+await adapter.saveRegistry(registry);
+
+// Save subjects with roles
+const user = new Subject();
+user.memberOf(editor);
+await adapter.saveSubject('user-123', user);
+
+await adapter.disconnect();
+```
+
+### Factory Functions
+
+Convenience functions for common patterns:
+
+```ts
+import {
+  createPostgresRegistry,
+  createPostgresRights,
+  createSQLiteRegistry,
+  createSQLiteRights
+} from 'odgn-rights/adapters';
+
+// Create SQLite adapter with rights
+const { adapter, rights } = await createSQLiteRights({
+  filename: './permissions.db'
+});
+rights.allow('/public/**', Flags.READ);
+await adapter.saveRights(rights);
+await adapter.disconnect();
+
+// Create SQLite adapter with registry
+const { adapter: regAdapter, registry } = await createSQLiteRegistry({
+  filename: ':memory:'
+});
+const viewer = registry.define('viewer');
+viewer.rights.allow('/read/*', Flags.READ);
+await registry.saveTo(regAdapter);
+await regAdapter.disconnect();
+```
+
+### Transactions
+
+Both adapters support transactions for atomic operations:
+
+```ts
+await adapter.transaction(async () => {
+  await adapter.saveRight(new Right('/a', { allow: [Flags.READ] }));
+  await adapter.saveRight(new Right('/b', { allow: [Flags.WRITE] }));
+  // If an error is thrown, all changes are rolled back
+});
+```
+
+### Adapter Interface
+
+All adapters implement the `DatabaseAdapter` interface:
+
+| Method                             | Description                       |
+| ---------------------------------- | --------------------------------- |
+| `connect()`                        | Connect to the database           |
+| `disconnect()`                     | Disconnect from the database      |
+| `migrate()`                        | Create or update schema           |
+| `saveRight(right)`                 | Save a single right               |
+| `saveRights(rights)`               | Save multiple rights              |
+| `loadRight(id)`                    | Load a right by ID                |
+| `loadRights()`                     | Load all rights                   |
+| `loadRightsByPath(pattern)`        | Load rights matching a pattern    |
+| `deleteRight(id)`                  | Delete a right                    |
+| `saveRole(role)`                   | Save a role with its rights       |
+| `loadRole(name)`                   | Load a role by name               |
+| `loadRoles()`                      | Load all roles                    |
+| `deleteRole(name)`                 | Delete a role                     |
+| `saveRegistry(registry)`           | Save entire RoleRegistry          |
+| `loadRegistry()`                   | Load RoleRegistry with all roles  |
+| `saveSubject(identifier, subject)` | Save a subject                    |
+| `loadSubject(identifier)`          | Load a subject                    |
+| `deleteSubject(identifier)`        | Delete a subject                  |
+| `clear()`                          | Clear all data (for testing)      |
+| `transaction(fn)`                  | Execute operations in transaction |
+
+### Database Schema
+
+The adapters create the following tables (with the configured prefix):
+
+| Table                      | Purpose                              |
+| -------------------------- | ------------------------------------ |
+| `{prefix}rights`           | Individual rights with paths & flags |
+| `{prefix}roles`            | Role definitions                     |
+| `{prefix}role_rights`      | Role-to-rights mapping               |
+| `{prefix}role_inheritance` | Role inheritance relationships       |
+| `{prefix}subjects`         | Subject records                      |
+| `{prefix}subject_roles`    | Subject-to-roles mapping             |
+| `{prefix}subject_rights`   | Direct subject rights                |
+
+### Persistence Metadata
+
+Rights saved to the database receive a `dbId` property:
+
+```ts
+const right = new Right('/test', { allow: [Flags.READ] });
+console.log(right.dbId); // undefined
+
+await adapter.saveRight(right);
+console.log(right.dbId); // 1 (database ID)
+```

package/dist/adapters/base-adapter.d.ts

@@ -0,0 +1,83 @@
+import { Flags } from '../constants';
+import { Right } from '../right';
+import { Rights } from '../rights';
+import { Role } from '../role';
+import { RoleRegistry } from '../role-registry';
+import { Subject } from '../subject';
+import type { BaseAdapterOptions, DatabaseAdapter, RightsRow, TableNames } from './types';
+/**
+ * Abstract base class for database adapters.
+ * Provides common utility methods for serialization/deserialization
+ * and table name management.
+ */
+export declare abstract class BaseAdapter implements DatabaseAdapter {
+    protected readonly tablePrefix: string;
+    protected readonly _tables: TableNames;
+    constructor(options?: BaseAdapterOptions);
+    /**
+     * Get the table names with the configured prefix
+     */
+    protected get tables(): TableNames;
+    /**
+     * Serialize tags array to JSON string
+     */
+    protected serializeTags: (tags: string[]) => string | null;
+    /**
+     * Deserialize JSON string to tags array
+     */
+    protected deserializeTags: (json: string | null) => string[];
+    /**
+     * Convert a Right instance to a database row (partial, without id and timestamps)
+     */
+    protected rightToRow: (right: Right) => Omit<RightsRow, "id" | "created_at" | "updated_at">;
+    /**
+     * Convert a database row to a Right instance
+     */
+    protected rowToRight: (row: RightsRow) => Right;
+    /**
+     * Convert a bitmask to an array of Flag values
+     */
+    protected maskToFlags: (mask: number) => Flags[];
+    /**
+     * Convert an array of Flag values to a bitmask
+     */
+    protected flagsToMask: (flags: Flags[]) => number;
+    /**
+     * Parse an ISO 8601 timestamp string to a Date, or undefined if null/invalid
+     */
+    protected parseTimestamp: (value: string | null) => Date | undefined;
+    abstract connect(): Promise<void>;
+    abstract disconnect(): Promise<void>;
+    abstract migrate(): Promise<void>;
+    abstract saveRight(right: Right): Promise<number>;
+    abstract saveRights(rights: Rights): Promise<number[]>;
+    abstract loadRight(id: number): Promise<Right | null>;
+    abstract loadRights(): Promise<Rights>;
+    abstract loadRightsByPath(pathPattern: string): Promise<Rights>;
+    abstract deleteRight(id: number): Promise<boolean>;
+    abstract saveRole(role: Role): Promise<number>;
+    abstract loadRole(name: string): Promise<Role | null>;
+    abstract loadRoles(): Promise<Role[]>;
+    abstract deleteRole(name: string): Promise<boolean>;
+    abstract saveRegistry(registry: RoleRegistry): Promise<void>;
+    abstract loadRegistry(): Promise<RoleRegistry>;
+    abstract saveSubject(identifier: string, subject: Subject): Promise<number>;
+    abstract loadSubject(identifier: string): Promise<Subject | null>;
+    abstract deleteSubject(identifier: string): Promise<boolean>;
+    /**
+     * Get all subject identifiers from the database.
+     * Used by findSubjectsWithAccess and can be overridden for optimization.
+     */
+    protected abstract getAllSubjectIdentifiers(): Promise<string[]>;
+    /**
+     * Find all subject identifiers that have access to a specific path with given flags.
+     * Default implementation uses getAllSubjectIdentifiers + loadSubject.
+     * Subclasses can override with optimized batch loading implementations.
+     * @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[]>;
+    abstract clear(): Promise<void>;
+    abstract transaction<T>(fn: (adapter: DatabaseAdapter) => Promise<T>): Promise<T>;
+}

package/dist/adapters/base-adapter.js

@@ -0,0 +1,142 @@
+import { Flags, hasBit } from '../constants';
+import { Right } from '../right';
+import { Rights } from '../rights';
+import { Role } from '../role';
+import { RoleRegistry } from '../role-registry';
+import { Subject } from '../subject';
+import { DEFAULT_TABLE_PREFIX, createTableNames } from './schema';
+/**
+ * Abstract base class for database adapters.
+ * Provides common utility methods for serialization/deserialization
+ * and table name management.
+ */
+export class BaseAdapter {
+    constructor(options = {}) {
+        // ===========================================================================
+        // Serialization Utilities
+        // ===========================================================================
+        /**
+         * Serialize tags array to JSON string
+         */
+        this.serializeTags = (tags) => {
+            if (tags.length === 0) {
+                return null;
+            }
+            return JSON.stringify(tags.sort());
+        };
+        /**
+         * Deserialize JSON string to tags array
+         */
+        this.deserializeTags = (json) => {
+            if (!json) {
+                return [];
+            }
+            try {
+                return JSON.parse(json);
+            }
+            catch {
+                return [];
+            }
+        };
+        /**
+         * Convert a Right instance to a database row (partial, without id and timestamps)
+         */
+        this.rightToRow = (right) => ({
+            allow_mask: right.allowMaskValue,
+            deny_mask: right.denyMaskValue,
+            description: right.description ?? null,
+            path: right.path,
+            priority: right.priority,
+            tags: this.serializeTags(right.tags),
+            valid_from: right.validFrom?.toISOString() ?? null,
+            valid_until: right.validUntil?.toISOString() ?? null
+        });
+        /**
+         * Convert a database row to a Right instance
+         */
+        this.rowToRight = (row) => {
+            const init = {
+                allow: this.maskToFlags(row.allow_mask),
+                deny: this.maskToFlags(row.deny_mask),
+                description: row.description ?? undefined,
+                priority: row.priority,
+                tags: this.deserializeTags(row.tags),
+                validFrom: row.valid_from ? new Date(row.valid_from) : undefined,
+                validUntil: row.valid_until ? new Date(row.valid_until) : undefined
+            };
+            return new Right(row.path, init);
+        };
+        /**
+         * Convert a bitmask to an array of Flag values
+         */
+        this.maskToFlags = (mask) => {
+            const flags = [];
+            if (hasBit(mask, Flags.READ)) {
+                flags.push(Flags.READ);
+            }
+            if (hasBit(mask, Flags.WRITE)) {
+                flags.push(Flags.WRITE);
+            }
+            if (hasBit(mask, Flags.CREATE)) {
+                flags.push(Flags.CREATE);
+            }
+            if (hasBit(mask, Flags.DELETE)) {
+                flags.push(Flags.DELETE);
+            }
+            if (hasBit(mask, Flags.EXECUTE)) {
+                flags.push(Flags.EXECUTE);
+            }
+            return flags;
+        };
+        /**
+         * Convert an array of Flag values to a bitmask
+         */
+        this.flagsToMask = (flags) => {
+            let mask = 0;
+            for (const f of flags) {
+                mask |= f;
+            }
+            return mask;
+        };
+        /**
+         * Parse an ISO 8601 timestamp string to a Date, or undefined if null/invalid
+         */
+        this.parseTimestamp = (value) => {
+            if (!value) {
+                return undefined;
+            }
+            const d = new Date(value);
+            if (Number.isNaN(d.getTime())) {
+                return undefined;
+            }
+            return d;
+        };
+        this.tablePrefix = options.tablePrefix ?? DEFAULT_TABLE_PREFIX;
+        this._tables = createTableNames(this.tablePrefix);
+    }
+    /**
+     * Get the table names with the configured prefix
+     */
+    get tables() {
+        return this._tables;
+    }
+    /**
+     * Find all subject identifiers that have access to a specific path with given flags.
+     * Default implementation uses getAllSubjectIdentifiers + loadSubject.
+     * Subclasses can override with optimized batch loading implementations.
+     * @param pathPattern The path pattern to check (supports wildcards)
+     * @param flags The flags to check for
+     * @returns Array of subject identifiers that have access
+     */
+    async findSubjectsWithAccess(pathPattern, flags) {
+        const allIdentifiers = await this.getAllSubjectIdentifiers();
+        const matchingSubjects = [];
+        for (const identifier of allIdentifiers) {
+            const subject = await this.loadSubject(identifier);
+            if (subject?.has(pathPattern, flags)) {
+                matchingSubjects.push(identifier);
+            }
+        }
+        return matchingSubjects;
+    }
+}

package/dist/adapters/factories.d.ts

@@ -0,0 +1,31 @@
+import { Rights, RoleRegistry } from '../index';
+import { PostgresAdapter, type PostgresAdapterOptions } from './postgres-adapter';
+import { RedisAdapter, type RedisAdapterOptions } from './redis-adapter';
+import { SQLiteAdapter, type SQLiteAdapterOptions } from './sqlite-adapter';
+export type CreateSQLiteRightsOptions = SQLiteAdapterOptions;
+export type CreatePostgresRegistryOptions = PostgresAdapterOptions;
+export declare const createSQLiteRights: (options?: CreateSQLiteRightsOptions) => Promise<{
+    adapter: SQLiteAdapter;
+    rights: Rights;
+}>;
+export declare const createPostgresRegistry: (options: CreatePostgresRegistryOptions) => Promise<{
+    adapter: PostgresAdapter;
+    registry: RoleRegistry;
+}>;
+export declare const createSQLiteRegistry: (options?: CreateSQLiteRightsOptions) => Promise<{
+    adapter: SQLiteAdapter;
+    registry: RoleRegistry;
+}>;
+export declare const createPostgresRights: (options: CreatePostgresRegistryOptions) => Promise<{
+    adapter: PostgresAdapter;
+    rights: Rights;
+}>;
+export type CreateRedisRightsOptions = RedisAdapterOptions;
+export declare const createRedisRights: (options: CreateRedisRightsOptions) => Promise<{
+    adapter: RedisAdapter;
+    rights: Rights;
+}>;
+export declare const createRedisRegistry: (options: CreateRedisRightsOptions) => Promise<{
+    adapter: RedisAdapter;
+    registry: RoleRegistry;
+}>;

package/dist/adapters/factories.js

@@ -0,0 +1,48 @@
+import { Rights, RoleRegistry } from '../index';
+import { PostgresAdapter } from './postgres-adapter';
+import { RedisAdapter } from './redis-adapter';
+import { SQLiteAdapter } from './sqlite-adapter';
+export const createSQLiteRights = async (options = {}) => {
+    const adapter = new SQLiteAdapter(options);
+    await adapter.connect();
+    await adapter.migrate();
+    adapter.prepareStatementsAfterMigration();
+    const rights = await adapter.loadRights();
+    return { adapter, rights };
+};
+export const createPostgresRegistry = async (options) => {
+    const adapter = new PostgresAdapter(options);
+    await adapter.connect();
+    await adapter.migrate();
+    const registry = await adapter.loadRegistry();
+    return { adapter, registry };
+};
+export const createSQLiteRegistry = async (options = {}) => {
+    const adapter = new SQLiteAdapter(options);
+    await adapter.connect();
+    await adapter.migrate();
+    adapter.prepareStatementsAfterMigration();
+    const registry = await adapter.loadRegistry();
+    return { adapter, registry };
+};
+export const createPostgresRights = async (options) => {
+    const adapter = new PostgresAdapter(options);
+    await adapter.connect();
+    await adapter.migrate();
+    const rights = await adapter.loadRights();
+    return { adapter, rights };
+};
+export const createRedisRights = async (options) => {
+    const adapter = new RedisAdapter(options);
+    await adapter.connect();
+    await adapter.migrate();
+    const rights = await adapter.loadRights();
+    return { adapter, rights };
+};
+export const createRedisRegistry = async (options) => {
+    const adapter = new RedisAdapter(options);
+    await adapter.connect();
+    await adapter.migrate();
+    const registry = await adapter.loadRegistry();
+    return { adapter, registry };
+};