odgn-rights 0.1.0 → 0.2.0

package/README.md

@@ -105,3 +105,124 @@ const json = rights.toJSON();
 // [ { path: '/', allow: 'r' }, { path: '/*/device/**', allow: 'c' }, ... ]
 const loaded = Rights.fromJSON(json);
 ```
+
+## CLI Tool
+
+The CLI tool helps test and debug permission configurations from the command line.
+
+### Installation
+
+```bash
+# Install globally
+npm install -g @odgn/rights
+
+# Or use with npx
+npx @odgn/rights --help
+
+# Or run directly with bun
+bun run src/cli/index.ts --help
+```
+
+### Commands
+
+#### check
+
+Test if a permission is allowed:
+
+```bash
+# Basic usage
+odgn-rights check -c config.json -p /users/123 -f READ
+
+# With combined flags
+odgn-rights check -c config.json -p /users/123 -f RW
+
+# With comma-separated flags
+odgn-rights check -c config.json -p /users/123 -f READ,WRITE
+
+# Quiet mode for scripting (outputs 'true' or 'false')
+odgn-rights check -c config.json -p /users/123 -f READ --quiet
+
+# With context for conditional rights
+odgn-rights check -c config.json -p /posts/1 -f WRITE --context '{"userId":"abc","ownerId":"abc"}'
+
+# Override time for time-based rights
+odgn-rights check -c config.json -p /scheduled -f READ --time 2025-06-15T12:00:00Z
+```
+
+Exit codes: `0` = allowed, `1` = denied, `2` = error
+
+#### explain
+
+Understand why a permission is allowed or denied:
+
+```bash
+# Basic usage
+odgn-rights explain -c config.json -p /users/123 -f WRITE
+
+# JSON output
+odgn-rights explain -c config.json -p /users/123 -f READ --json
+```
+
+The explain command shows:
+
+- Decision breakdown per flag
+- Matching rules sorted by specificity
+- Suggestions for granting denied permissions
+
+#### validate
+
+Validate a configuration file:
+
+```bash
+# Validate JSON config
+odgn-rights validate config.json
+
+# Validate string format config
+odgn-rights validate config.txt
+
+# Strict mode (warns on broad patterns like /**)
+odgn-rights validate --strict config.json
+
+# JSON output
+odgn-rights validate --json config.json
+```
+
+Exit codes: `0` = valid, `1` = validation errors, `2` = file error
+
+### Configuration Formats
+
+The CLI supports two configuration formats:
+
+**JSON format** (`config.json`):
+
+```json
+[
+  { "path": "/", "allow": "r" },
+  { "path": "/users/*", "allow": "rw" },
+  { "path": "/admin/**", "allow": "*", "tags": ["admin"] },
+  { "path": "/scheduled", "allow": "r", "validFrom": "2025-01-01T00:00:00Z" }
+]
+```
+
+**String format** (`config.txt`):
+
+```
+# Comments start with #
++r:/
++rw:/users/*
++*:/admin/**
+-d+rw:/public
+```
+
+### Flag Reference
+
+| Flag    | Letter | Description        |
+| ------- | ------ | ------------------ |
+| READ    | R      | Read permission    |
+| WRITE   | W      | Write permission   |
+| CREATE  | C      | Create permission  |
+| DELETE  | D      | Delete permission  |
+| EXECUTE | X      | Execute permission |
+| ALL     | \*     | All permissions    |
+
+Flags can be combined: `RW`, `READ,WRITE`, `RWCDX`

package/dist/cli/commands/check.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const checkCommand: Command;

package/dist/cli/commands/check.js

@@ -0,0 +1,38 @@
+/* eslint-disable no-console */
+import { Command } from 'commander';
+import { loadConfig } from '../helpers/config-loader';
+import { parseFlags } from '../helpers/flag-parser';
+import { colors, formatResult } from '../helpers/output';
+export const checkCommand = new Command('check')
+    .description('Test a permission check against a configuration')
+    .requiredOption('-c, --config <file>', 'Path to rights configuration file')
+    .requiredOption('-p, --path <path>', 'Resource path to check')
+    .requiredOption('-f, --flag <flag>', 'Permission flag(s) to check (READ, WRITE, etc.)')
+    .option('--context <json>', 'JSON context for conditional rights')
+    .option('--time <iso-date>', 'Override current time for time-based rights')
+    .option('--quiet', 'Only output result (for scripting)')
+    .action(options => {
+    try {
+        const rights = loadConfig(options.config);
+        const flag = parseFlags(options.flag);
+        let context = undefined;
+        if (options.context) {
+            context = JSON.parse(options.context);
+        }
+        if (options.time) {
+            context = { ...context, _now: new Date(options.time) };
+        }
+        const result = rights.has(options.path, flag, context);
+        if (options.quiet) {
+            process.stdout.write(result ? 'true' : 'false');
+            process.exit(result ? 0 : 1);
+        }
+        console.log(`Checking ${colors.cyan(options.flag)} on ${colors.cyan(options.path)}...`);
+        console.log(`Result: ${formatResult(result)}`);
+        process.exit(result ? 0 : 1);
+    }
+    catch (error) {
+        console.error(colors.red(`Error: ${error.message}`));
+        process.exit(2);
+    }
+});

package/dist/cli/commands/explain.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const explainCommand: Command;

package/dist/cli/commands/explain.js

@@ -0,0 +1,85 @@
+/* eslint-disable no-console */
+import { Command } from 'commander';
+import { lettersFromMask } from '../../utils';
+import { loadConfig } from '../helpers/config-loader';
+import { parseFlags } from '../helpers/flag-parser';
+import { colors, flagName, formatResult } from '../helpers/output';
+export const explainCommand = new Command('explain')
+    .description('Explain why a permission is allowed or denied')
+    .requiredOption('-c, --config <file>', 'Path to rights configuration file')
+    .requiredOption('-p, --path <path>', 'Resource path to check')
+    .requiredOption('-f, --flag <flag>', 'Permission flag(s) to explain')
+    .option('--context <json>', 'JSON context for conditional rights')
+    .option('--time <iso-date>', 'Override current time for time-based rights')
+    .option('--json', 'Output as JSON')
+    .action(options => {
+    try {
+        const rights = loadConfig(options.config);
+        const flag = parseFlags(options.flag);
+        let context = undefined;
+        if (options.context) {
+            context = JSON.parse(options.context);
+        }
+        if (options.time) {
+            context = { ...context, _now: new Date(options.time) };
+        }
+        const explanation = rights.explain(options.path, flag, context);
+        if (options.json) {
+            console.log(JSON.stringify({
+                allowed: explanation.allowed,
+                details: explanation.details.map(d => ({
+                    allowed: d.allowed,
+                    flag: flagName(d.bit),
+                    rule: d.right?.toString()
+                })),
+                flag: options.flag,
+                path: options.path
+            }, null, 2));
+            process.exit(explanation.allowed ? 0 : 1);
+        }
+        console.log(`\nExplaining ${colors.cyan(options.flag)} on ${colors.cyan(options.path)}...\n`);
+        console.log(`Result: ${formatResult(explanation.allowed)}\n`);
+        console.log(colors.bold('Decision breakdown:'));
+        for (const detail of explanation.details) {
+            const status = detail.allowed
+                ? colors.green('ALLOWED')
+                : colors.red('DENIED');
+            console.log(`  ${flagName(detail.bit)}: ${status}`);
+            if (detail.right) {
+                console.log(`    Matched by: ${colors.dim(detail.right.toString())}`);
+            }
+            else {
+                console.log(`    ${colors.dim('No matching rule grants this permission')}`);
+            }
+        }
+        // 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):')}`);
+            allRights
+                .sort((a, b) => b.specificity() - a.specificity())
+                .forEach((r, i) => {
+                console.log(`  ${i + 1}. ${colors.cyan(r.toString())}`);
+                console.log(`     Specificity: ${r.specificity()}`);
+                if (r.tags.length > 0) {
+                    console.log(`     Tags: ${r.tags.join(', ')}`);
+                }
+            });
+        }
+        // Provide suggestions if denied
+        if (!explanation.allowed) {
+            console.log(`\n${colors.yellow('Suggestion:')} To grant ${options.flag} access, add:`);
+            const flagLetters = lettersFromMask(flag);
+            console.log(`  +${flagLetters}:${options.path}    ${colors.dim('(exact path)')}`);
+            const wildcardPath = options.path.replace(/\/[^/]+$/, '/*');
+            if (wildcardPath !== options.path) {
+                console.log(`  +${flagLetters}:${wildcardPath}      ${colors.dim('(wildcard)')}`);
+            }
+        }
+        process.exit(explanation.allowed ? 0 : 1);
+    }
+    catch (error) {
+        console.error(colors.red(`Error: ${error.message}`));
+        process.exit(2);
+    }
+});

package/dist/cli/commands/validate.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const validateCommand: Command;

package/dist/cli/commands/validate.js

@@ -0,0 +1,177 @@
+/* eslint-disable no-console */
+import { readFileSync } from 'node:fs';
+import { Command } from 'commander';
+import { Right } from '@/right';
+import { Rights } from '@/rights';
+import { colors } from '../helpers/output';
+export const validateCommand = new Command('validate')
+    .description('Validate a rights configuration file')
+    .argument('<file>', 'Configuration file to validate')
+    .option('--strict', 'Enable strict validation (warn on unusual patterns)')
+    .option('--json', 'Output as JSON')
+    .action((file, options) => {
+    const errors = [];
+    const warnings = [];
+    try {
+        const content = readFileSync(file, 'utf8');
+        const isJson = file.endsWith('.json');
+        if (isJson) {
+            validateJsonConfig(content, errors, warnings, options.strict);
+        }
+        else {
+            validateStringConfig(content, errors, warnings, options.strict);
+        }
+        if (options.json) {
+            console.log(JSON.stringify({
+                errors,
+                valid: errors.length === 0,
+                warnings
+            }, null, 2));
+            process.exit(errors.length > 0 ? 1 : 0);
+        }
+        console.log(`Validating ${colors.cyan(file)}...\n`);
+        if (errors.length > 0) {
+            console.log(colors.red('Errors found:\n'));
+            for (const err of errors) {
+                const loc = err.index !== undefined
+                    ? `Rule ${err.index + 1}`
+                    : `Line ${err.line}`;
+                console.log(`  ${colors.red(loc)}: ${err.message}`);
+                if (err.detail) {
+                    console.log(`    ${colors.dim(err.detail)}`);
+                }
+            }
+            console.log(`\n${colors.red(`Validation failed with ${errors.length} error(s).`)}`);
+            process.exit(1);
+        }
+        if (warnings.length > 0) {
+            console.log(colors.yellow('Warnings:\n'));
+            for (const warn of warnings) {
+                const loc = warn.index !== undefined
+                    ? `Rule ${warn.index + 1}`
+                    : `Line ${warn.line}`;
+                console.log(`  ${colors.yellow(loc)}: ${warn.message}`);
+                if (warn.detail) {
+                    console.log(`    ${colors.dim(warn.detail)}`);
+                }
+            }
+            console.log('');
+        }
+        // Parse and show summary
+        const rights = isJson
+            ? Rights.fromJSON(JSON.parse(content))
+            : Rights.parse(content);
+        const allRights = rights.allRights();
+        const withTags = allRights.filter(r => r.tags.length > 0).length;
+        const timeBased = allRights.filter(r => r.validFrom || r.validUntil).length;
+        console.log(colors.green('All rules are valid.\n'));
+        console.log(colors.bold('Summary:'));
+        console.log(`  Paths:      ${allRights.length}`);
+        console.log(`  With tags:  ${withTags}`);
+        console.log(`  Time-based: ${timeBased}`);
+        process.exit(0);
+    }
+    catch (error) {
+        if (!options.json) {
+            console.error(colors.red(`Error: ${error.message}`));
+        }
+        else {
+            console.log(JSON.stringify({
+                errors: [{ message: error.message }],
+                valid: false,
+                warnings: []
+            }, null, 2));
+        }
+        process.exit(2);
+    }
+});
+const validateJsonConfig = (content, errors, warnings, strict) => {
+    let data;
+    try {
+        data = JSON.parse(content);
+    }
+    catch (error) {
+        errors.push({ detail: error.message, message: 'Invalid JSON' });
+        return;
+    }
+    if (!Array.isArray(data)) {
+        errors.push({ message: 'Configuration must be an array of rights' });
+        return;
+    }
+    data.forEach((item, index) => {
+        // Check required fields
+        if (!item.path) {
+            errors.push({ index, message: 'Missing required field: path' });
+        }
+        if (!item.allow && !item.deny) {
+            errors.push({
+                index,
+                message: 'Must specify at least "allow" or "deny"'
+            });
+        }
+        // Validate time range
+        if (item.validFrom && item.validUntil) {
+            const from = new Date(item.validFrom);
+            const until = new Date(item.validUntil);
+            if (from > until) {
+                errors.push({
+                    detail: `validFrom (${item.validFrom}) is after validUntil (${item.validUntil})`,
+                    index,
+                    message: 'Invalid time range'
+                });
+            }
+        }
+        // Try to parse the right
+        try {
+            const init = {};
+            if (item.validFrom) {
+                init.validFrom = new Date(item.validFrom);
+            }
+            if (item.validUntil) {
+                init.validUntil = new Date(item.validUntil);
+            }
+            if (item.tags) {
+                init.tags = item.tags;
+            }
+            new Right(item.path, init);
+        }
+        catch (error) {
+            errors.push({ index, message: error.message });
+        }
+        // Strict mode warnings
+        if (strict) {
+            if (item.path === '/**') {
+                warnings.push({
+                    detail: '"/**" matches everything - ensure this is intentional',
+                    index,
+                    message: 'Overly broad pattern'
+                });
+            }
+        }
+    });
+};
+const validateStringConfig = (content, errors, warnings, strict) => {
+    const lines = content.split(/\r?\n/);
+    lines.forEach((line, lineNum) => {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            return;
+        } // Skip empty/comments
+        try {
+            Right.parse(trimmed);
+        }
+        catch (error) {
+            errors.push({
+                detail: error.message,
+                line: lineNum + 1,
+                message: 'Invalid right definition'
+            });
+        }
+        if (strict && trimmed.includes('/**')) {
+            warnings.push({
+                line: lineNum + 1,
+                message: 'Overly broad pattern detected'
+            });
+        }
+    });
+};

package/dist/cli/helpers/config-loader.d.ts

@@ -0,0 +1,3 @@
+import { Rights } from '@/rights';
+export type ConfigFormat = 'json' | 'string' | 'auto';
+export declare const loadConfig: (filePath: string, format?: ConfigFormat) => Rights;

package/dist/cli/helpers/config-loader.js

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs';
+import { Rights } from '@/rights';
+export const loadConfig = (filePath, format = 'auto') => {
+    const content = readFileSync(filePath, 'utf8');
+    if (format === 'auto') {
+        format = filePath.endsWith('.json') ? 'json' : 'string';
+    }
+    if (format === 'json') {
+        const data = JSON.parse(content);
+        return Rights.fromJSON(data);
+    }
+    return Rights.parse(content);
+};

package/dist/cli/helpers/flag-parser.d.ts

@@ -0,0 +1,3 @@
+import { Flags } from '@/constants';
+export declare const parseFlag: (input: string) => Flags;
+export declare const parseFlags: (input: string) => number;

package/dist/cli/helpers/flag-parser.js

@@ -0,0 +1,40 @@
+import { Flags } from '@/constants';
+const FLAG_MAP = {
+    '*': Flags.ALL,
+    ALL: Flags.ALL,
+    C: Flags.CREATE,
+    CREATE: Flags.CREATE,
+    D: Flags.DELETE,
+    DELETE: Flags.DELETE,
+    EXECUTE: Flags.EXECUTE,
+    R: Flags.READ,
+    READ: Flags.READ,
+    W: Flags.WRITE,
+    WRITE: Flags.WRITE,
+    X: Flags.EXECUTE
+};
+export const parseFlag = (input) => {
+    const normalized = input.toUpperCase().trim();
+    const flag = FLAG_MAP[normalized];
+    if (flag === undefined) {
+        throw new Error(`Unknown flag: ${input}. Valid flags: READ, WRITE, CREATE, DELETE, EXECUTE, ALL`);
+    }
+    return flag;
+};
+export const parseFlags = (input) => {
+    if (input.includes(',')) {
+        return input
+            .split(',')
+            .reduce((acc, f) => acc | parseFlag(f.trim()), 0);
+    }
+    try {
+        return parseFlag(input);
+    }
+    catch {
+        let combined = 0;
+        for (const ch of input.toUpperCase()) {
+            combined |= parseFlag(ch);
+        }
+        return combined;
+    }
+};

package/dist/cli/helpers/output.d.ts

@@ -0,0 +1,10 @@
+export declare const colors: {
+    bold: (s: string) => string;
+    cyan: (s: string) => string;
+    dim: (s: string) => string;
+    green: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+};
+export declare const formatResult: (allowed: boolean) => string;
+export declare const flagName: (flag: number) => string;

package/dist/cli/helpers/output.js

@@ -0,0 +1,29 @@
+import { Flags } from '../../constants';
+export const colors = {
+    bold: (s) => `\u001b[1m${s}\u001b[0m`,
+    cyan: (s) => `\u001b[36m${s}\u001b[0m`,
+    dim: (s) => `\u001b[2m${s}\u001b[0m`,
+    green: (s) => `\u001b[32m${s}\u001b[0m`,
+    red: (s) => `\u001b[31m${s}\u001b[0m`,
+    yellow: (s) => `\u001b[33m${s}\u001b[0m`
+};
+export const formatResult = (allowed) => allowed ? colors.green('ALLOWED') : colors.red('DENIED');
+export const flagName = (flag) => {
+    const names = [];
+    if (flag & Flags.READ) {
+        names.push('READ');
+    }
+    if (flag & Flags.WRITE) {
+        names.push('WRITE');
+    }
+    if (flag & Flags.CREATE) {
+        names.push('CREATE');
+    }
+    if (flag & Flags.DELETE) {
+        names.push('DELETE');
+    }
+    if (flag & Flags.EXECUTE) {
+        names.push('EXECUTE');
+    }
+    return names.join(' | ') || 'NONE';
+};

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import pkg from '../../package.json';
+import { checkCommand } from './commands/check';
+import { explainCommand } from './commands/explain';
+import { validateCommand } from './commands/validate';
+const program = new Command();
+program
+    .name('odgn-rights')
+    .description('CLI tool for testing and debugging permission configurations')
+    .version(pkg.version);
+program.addCommand(checkCommand);
+program.addCommand(explainCommand);
+program.addCommand(validateCommand);
+program.parse();

package/dist/cli/types.d.ts

@@ -0,0 +1,10 @@
+export type CLIOptions = {
+    config: string;
+    context?: string;
+    flag: string;
+    json?: boolean;
+    path: string;
+    quiet?: boolean;
+    strict?: boolean;
+    time?: string;
+};

package/dist/cli/types.js

@@ -0,0 +1 @@
+export {};

package/dist/right.d.ts

@@ -6,6 +6,9 @@ export type RightInit = {
     condition?: Condition;
     deny?: Flags[];
     description?: string;
+    tags?: string[];
+    validFrom?: Date;
+    validUntil?: Date;
 };
 export declare class Right {
     readonly path: string;
@@ -13,20 +16,34 @@ export declare class Right {
     private denyMask;
     readonly description?: string;
     readonly condition?: Condition;
+    readonly validFrom?: Date;
+    readonly validUntil?: Date;
+    private readonly _tags;
     private readonly _specificity;
     private readonly _re?;
     constructor(path: string, init?: RightInit);
     allow(flag: Flags): this;
     deny(flag: Flags): this;
     clear(): this;
-    has(flag: Flags): boolean;
+    get tags(): string[];
+    hasTag(tag: string): boolean;
+    hasTags(tags: string[], mode?: 'and' | 'or'): boolean;
+    addTag(tag: string): this;
+    removeTag(tag: string): this;
+    has(flag: Flags, now?: Date): boolean;
+    isValidAt(now?: Date): boolean;
+    isExpired(now?: Date): boolean;
     get allowMaskValue(): number;
     get denyMaskValue(): number;
     toString(): string;
     toJSON(): {
         allow: string;
+        deny?: string;
         description?: string;
         path: string;
+        tags?: string[];
+        validFrom?: string;
+        validUntil?: string;
     };
     matches(targetPath: string): boolean;
     specificity(): number;

package/dist/right.js

@@ -7,6 +7,12 @@ export class Right {
         this.path = normalizePath(path);
         this.description = init?.description;
         this.condition = init?.condition;
+        this.validFrom = init?.validFrom;
+        this.validUntil = init?.validUntil;
+        this._tags = new Set(init?.tags);
+        if (this.validFrom && this.validUntil && this.validFrom > this.validUntil) {
+            throw new Error('validFrom must be before validUntil');
+        }
         this._specificity = this.calculateSpecificity();
         if (this.path.includes('*') || this.path.includes('?')) {
             this._re = Right.globToRegExp(this.path);
@@ -35,7 +41,33 @@ export class Right {
         this.denyMask = 0;
         return this;
     }
-    has(flag) {
+    get tags() {
+        return [...this._tags].sort();
+    }
+    hasTag(tag) {
+        return this._tags.has(tag);
+    }
+    hasTags(tags, mode = 'and') {
+        if (mode === 'and') {
+            return tags.every(t => this._tags.has(t));
+        }
+        return tags.some(t => this._tags.has(t));
+    }
+    addTag(tag) {
+        this._tags.add(tag);
+        return this;
+    }
+    removeTag(tag) {
+        this._tags.delete(tag);
+        return this;
+    }
+    has(flag, now = new Date()) {
+        if (this.validFrom && now < this.validFrom) {
+            return false;
+        }
+        if (this.validUntil && now > this.validUntil) {
+            return false;
+        }
         // For composite masks, require all bits
         let remaining = flag;
         for (const bit of ALL_BITS) {
@@ -52,6 +84,18 @@ export class Right {
         }
         return true;
     }
+    isValidAt(now = new Date()) {
+        if (this.validFrom && now < this.validFrom) {
+            return false;
+        }
+        if (this.validUntil && now > this.validUntil) {
+            return false;
+        }
+        return true;
+    }
+    isExpired(now = new Date()) {
+        return this.validUntil !== undefined && now > this.validUntil;
+    }
     get allowMaskValue() {
         return this.allowMask;
     }
@@ -69,17 +113,39 @@ export class Right {
             parts.push(`+${allowLetters}`);
         }
         const left = parts.join('');
-        return `${left}:${this.path}`;
+        let res = `${left}:${this.path}`;
+        if (this._tags.size > 0) {
+            res += `#${this.tags.join(',')}`;
+        }
+        if (this.validFrom || this.validUntil) {
+            const from = this.validFrom ? this.validFrom.toISOString() : '*';
+            const until = this.validUntil ? this.validUntil.toISOString() : '*';
+            res += `@${from}/${until}`;
+        }
+        return res;
     }
     toJSON() {
         const allow = lettersFromMask(this.allowMask);
+        const deny = lettersFromMask(this.denyMask);
         const out = {
             allow,
             path: this.path
         };
+        if (deny) {
+            out.deny = deny;
+        }
         if (this.description) {
             out.description = this.description;
         }
+        if (this._tags.size > 0) {
+            out.tags = this.tags;
+        }
+        if (this.validFrom) {
+            out.validFrom = this.validFrom.toISOString();
+        }
+        if (this.validUntil) {
+            out.validUntil = this.validUntil.toISOString();
+        }
         return out;
     }
     // Pattern match helper
@@ -140,25 +206,68 @@ export class Right {
     }
     static parse(input) {
         const s = input.trim();
-        const idx = s.indexOf(':');
-        if (idx === -1) {
-            return new Right(s);
+        const colonIdx = s.indexOf(':');
+        const hashIdx = s.lastIndexOf('#');
+        const atIdx = s.lastIndexOf('@');
+        let flagsStr = '';
+        let pathStr = '';
+        let tagsStr = '';
+        let timeStr = '';
+        let pathEndIdx = s.length;
+        if (atIdx !== -1) {
+            timeStr = s.slice(atIdx + 1);
+            pathEndIdx = atIdx;
+        }
+        if (hashIdx !== -1 && (atIdx === -1 || hashIdx < atIdx)) {
+            tagsStr = s.slice(hashIdx + 1, pathEndIdx);
+            pathEndIdx = hashIdx;
+        }
+        if (colonIdx === -1) {
+            pathStr = s.slice(0, pathEndIdx);
+        }
+        else {
+            flagsStr = s.slice(0, colonIdx);
+            pathStr = s.slice(colonIdx + 1, pathEndIdx);
+        }
+        const init = {};
+        if (timeStr) {
+            const parts = timeStr.split('/');
+            const from = parts[0];
+            const until = parts[1];
+            if (from && from !== '*') {
+                const d = new Date(from);
+                if (!Number.isNaN(d.getTime())) {
+                    init.validFrom = d;
+                }
+            }
+            if (until && until !== '*') {
+                const d = new Date(until);
+                if (!Number.isNaN(d.getTime())) {
+                    init.validUntil = d;
+                }
+            }
+        }
+        if (tagsStr) {
+            init.tags = tagsStr.split(',').map(t => t.trim());
+        }
+        const r = new Right(pathStr, init);
+        if (!flagsStr) {
+            return r;
         }
-        const groups = s.slice(0, idx);
-        const path = s.slice(idx + 1);
-        const r = new Right(path);
         // parse groups like '-abc+xyz' or '+xyz-abc'
         let i = 0;
-        while (i < groups.length) {
-            const sign = groups[i];
+        while (i < flagsStr.length) {
+            const sign = flagsStr[i];
             if (sign !== '+' && sign !== '-') {
                 i++;
                 continue;
             }
             i++;
             let letters = '';
-            while (i < groups.length && groups[i] !== '+' && groups[i] !== '-') {
-                letters += groups[i];
+            while (i < flagsStr.length &&
+                flagsStr[i] !== '+' &&
+                flagsStr[i] !== '-') {
+                letters += flagsStr[i];
                 i++;
             }
             const apply = sign === '+' ? (f) => r.allow(f) : (f) => r.deny(f);

package/dist/rights.d.ts

@@ -2,13 +2,25 @@ import { Flags } from './constants';
 import { Right, type ConditionContext } from './right';
 export type RightJSON = {
     allow: string;
+    deny?: string;
     description?: string;
     path: string;
+    tags?: string[];
+    validFrom?: string;
+    validUntil?: string;
 };
 export declare class Rights {
     private list;
     private matchCache;
+    private _onChange?;
+    set onChange(cb: () => void | undefined);
+    private notify;
     add(right: Right): this;
+    findByTag(tag: string): Right[];
+    findByTags(tags: string[], mode?: 'and' | 'or'): Right[];
+    revokeByTag(tag: string): this;
+    allowByTag(tag: string, ...flags: Flags[]): this;
+    prune(now?: Date): this;
     allRights(): Right[];
     allow(path: string, ...flags: Flags[]): this;
     deny(path: string, flag: Flags): this;

package/dist/rights.js

@@ -1,14 +1,60 @@
 import { ALL_BITS, Flags, hasBit } from './constants';
 import { Right } from './right';
-import { lettersFromMask, normalizePath } from './utils';
+import { normalizePath } from './utils';
 export class Rights {
     constructor() {
         this.list = [];
         this.matchCache = new Map();
     }
+    set onChange(cb) {
+        this._onChange = cb;
+    }
+    notify() {
+        this._onChange?.();
+    }
     add(right) {
         this.list.push(right);
         this.matchCache.clear();
+        this.notify();
+        return this;
+    }
+    findByTag(tag) {
+        return this.list.filter(r => r.hasTag(tag));
+    }
+    findByTags(tags, mode = 'and') {
+        return this.list.filter(r => r.hasTags(tags, mode));
+    }
+    revokeByTag(tag) {
+        const toRemove = this.findByTag(tag);
+        if (toRemove.length > 0) {
+            this.list = this.list.filter(r => !toRemove.includes(r));
+            this.matchCache.clear();
+            this.notify();
+        }
+        return this;
+    }
+    allowByTag(tag, ...flags) {
+        const matches = this.findByTag(tag);
+        if (matches.length > 0) {
+            // Support spreading an array
+            const flat = [].concat(...flags);
+            for (const r of matches) {
+                for (const f of flat) {
+                    r.allow(f);
+                }
+            }
+            this.matchCache.clear();
+            this.notify();
+        }
+        return this;
+    }
+    prune(now = new Date()) {
+        const originalCount = this.list.length;
+        this.list = this.list.filter(r => !r.isExpired(now));
+        if (this.list.length !== originalCount) {
+            this.matchCache.clear();
+            this.notify();
+        }
         return this;
     }
     allRights() {
@@ -19,7 +65,7 @@ export class Rights {
         let r = this.list.find(x => x.path === p);
         if (!r) {
             r = new Right(p);
-            this.add(r);
+            this.list.push(r);
         }
         else {
             // Invalidate cache if we update an existing right
@@ -30,6 +76,7 @@ export class Rights {
         for (const f of flat) {
             r.allow(f);
         }
+        this.notify();
         return this;
     }
     deny(path, flag) {
@@ -37,13 +84,14 @@ export class Rights {
         let r = this.list.find(x => x.path === p);
         if (!r) {
             r = new Right(p);
-            this.add(r);
+            this.list.push(r);
         }
         else {
             // Invalidate cache if we update an existing right
             this.matchCache.clear();
         }
         r.deny(flag);
+        this.notify();
         return this;
     }
     matchOrdered(path) {
@@ -92,8 +140,12 @@ export class Rights {
         return this.explainSingle(path, bit, context).allowed;
     }
     explainSingle(path, bit, context) {
+        const now = getNow(context);
         const matches = this.matchOrdered(normalizePath(path));
         for (const r of matches) {
+            if (!r.isValidAt(now)) {
+                continue;
+            }
             if (r.condition && !r.condition(context)) {
                 continue;
             }
@@ -126,9 +178,7 @@ export class Rights {
         return this.has(path, Flags.EXECUTE, context);
     }
     toString() {
-        return this.list
-            .map(r => `+${lettersFromMask(r.allowMaskValue)}:${r.path}`)
-            .join(', ');
+        return this.list.map(r => r.toString()).join(', ');
     }
     toJSON() {
         return this.list.map(r => r.toJSON());
@@ -137,32 +187,31 @@ export class Rights {
         const rights = new Rights();
         for (const item of arr) {
             const p = normalizePath(item.path);
-            const r = new Right(p, { description: item.description });
-            const allowStr = item.allow;
-            if (allowStr === '*') {
-                r.allow(Flags.ALL);
+            const init = {
+                description: item.description,
+                tags: item.tags
+            };
+            if (item.validFrom) {
+                const d = new Date(item.validFrom);
+                if (!Number.isNaN(d.getTime())) {
+                    init.validFrom = d;
+                }
             }
-            else {
-                for (const ch of allowStr) {
-                    switch (ch) {
-                        case 'r':
-                            r.allow(Flags.READ);
-                            break;
-                        case 'w':
-                            r.allow(Flags.WRITE);
-                            break;
-                        case 'c':
-                            r.allow(Flags.CREATE);
-                            break;
-                        case 'd':
-                            r.allow(Flags.DELETE);
-                            break;
-                        case 'x':
-                            r.allow(Flags.EXECUTE);
-                            break;
-                    }
+            if (item.validUntil) {
+                const d = new Date(item.validUntil);
+                if (!Number.isNaN(d.getTime())) {
+                    init.validUntil = d;
                 }
             }
+            const r = new Right(p, init);
+            const allowStr = item.allow;
+            const denyStr = item.deny;
+            if (allowStr) {
+                applyFlags(allowStr, f => r.allow(f));
+            }
+            if (denyStr) {
+                applyFlags(denyStr, f => r.deny(f));
+            }
             rights.add(r);
         }
         return rights;
@@ -187,3 +236,39 @@ export class Rights {
         return this.list.map(r => r.toString()).join(separator);
     }
 }
+const getNow = (context) => {
+    if (context &&
+        typeof context === 'object' &&
+        '_now' in context &&
+        // eslint-disable-next-line @nkzw/no-instanceof
+        context._now instanceof Date) {
+        return context._now;
+    }
+    return new Date();
+};
+const applyFlags = (str, apply) => {
+    if (str === '*') {
+        apply(Flags.ALL);
+    }
+    else {
+        for (const ch of str) {
+            switch (ch) {
+                case 'r':
+                    apply(Flags.READ);
+                    break;
+                case 'w':
+                    apply(Flags.WRITE);
+                    break;
+                case 'c':
+                    apply(Flags.CREATE);
+                    break;
+                case 'd':
+                    apply(Flags.DELETE);
+                    break;
+                case 'x':
+                    apply(Flags.EXECUTE);
+                    break;
+            }
+        }
+    }
+};

package/dist/role-registry.js

@@ -38,6 +38,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.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,6 +29,14 @@ 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;

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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odgn-rights",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Tiny TypeScript library for expressing and evaluating hierarchical rights with simple glob patterns.",
   "keywords": [
     "rights",
@@ -16,10 +16,18 @@
   "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"
     }
   },
   "files": [
@@ -32,17 +40,24 @@
     "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",
     "@types/bun": "latest",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "eslint": "^9",
     "knip": "^5.76.3",
     "prettier": "^3"
@@ -53,5 +68,11 @@
   "publishConfig": {
     "access": "public"
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "dependencies": {
+    "commander": "^14.0.2",
+    "jotai": "^2.16.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3"
+  }
 }