@siremzam/sentinel 0.3.0

package/dist/engine.d.ts

@@ -0,0 +1,70 @@
+import type { SchemaDefinition, InferAction, InferResource, PolicyRule, Decision, Subject, ResourceContext, DecisionListener, EngineOptions, ExplainResult } from "./types.js";
+import { RuleBuilder } from "./policy-builder.js";
+import type { RoleHierarchy } from "./role-hierarchy.js";
+export interface AccessEngineOptions<S extends SchemaDefinition> extends EngineOptions<S> {
+    roleHierarchy?: RoleHierarchy<S>;
+    /**
+     * Enable LRU cache for evaluation results.
+     * Only caches evaluations of rules WITHOUT conditions (context-independent).
+     * Rules with conditions are never cached since their result depends on resourceContext.
+     */
+    cacheSize?: number;
+}
+export declare class AccessEngine<S extends SchemaDefinition> {
+    private compiled;
+    private listeners;
+    private asyncConditions;
+    private _defaultDeny;
+    private _strictTenancy;
+    private hierarchy?;
+    private cache?;
+    private conditionErrorHandler?;
+    constructor(options: AccessEngineOptions<S>);
+    addRule(rule: PolicyRule<S>): this;
+    addRules(...rules: PolicyRule<S>[]): this;
+    removeRule(ruleId: string): boolean;
+    getRules(): ReadonlyArray<PolicyRule<S>>;
+    clearRules(): void;
+    clearCache(): void;
+    get cacheStats(): {
+        size: number;
+        maxSize: number;
+    } | null;
+    allow(): RuleBuilder<S>;
+    deny(): RuleBuilder<S>;
+    onDecision(listener: DecisionListener<S>): () => void;
+    private emit;
+    evaluate(subject: Subject<S>, action: InferAction<S>, resource: InferResource<S>, resourceContext?: ResourceContext, tenantId?: string): Decision<S>;
+    evaluateAsync(subject: Subject<S>, action: InferAction<S>, resource: InferResource<S>, resourceContext?: ResourceContext, tenantId?: string): Promise<Decision<S>>;
+    permitted(subject: Subject<S>, resource: InferResource<S>, actions: InferAction<S>[], resourceContext?: ResourceContext, tenantId?: string): Set<InferAction<S>>;
+    permittedAsync(subject: Subject<S>, resource: InferResource<S>, actions: InferAction<S>[], resourceContext?: ResourceContext, tenantId?: string): Promise<Set<InferAction<S>>>;
+    explain(subject: Subject<S>, action: InferAction<S>, resource: InferResource<S>, resourceContext?: ResourceContext, tenantId?: string): ExplainResult<S>;
+    explainAsync(subject: Subject<S>, action: InferAction<S>, resource: InferResource<S>, resourceContext?: ResourceContext, tenantId?: string): Promise<ExplainResult<S>>;
+    can(subject: Subject<S>): PerformStep<S>;
+    private validateInput;
+    private enforceTenancy;
+    private buildContext;
+    private evaluateConditionsSync;
+    private emitConditionError;
+    private matchRules;
+    private sortCandidates;
+    private matchesAction;
+    private resolveRoles;
+    private buildDecision;
+}
+declare class PerformStep<S extends SchemaDefinition> {
+    private engine;
+    private subject;
+    constructor(engine: AccessEngine<S>, subject: Subject<S>);
+    perform(action: InferAction<S>): OnStep<S>;
+}
+declare class OnStep<S extends SchemaDefinition> {
+    private engine;
+    private subject;
+    private action;
+    constructor(engine: AccessEngine<S>, subject: Subject<S>, action: InferAction<S>);
+    on(resource: InferResource<S>, resourceContext?: ResourceContext, tenantId?: string): Decision<S>;
+    onAsync(resource: InferResource<S>, resourceContext?: ResourceContext, tenantId?: string): Promise<Decision<S>>;
+}
+export {};
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}

package/dist/engine.js

@@ -0,0 +1,562 @@
+import { allow as _allow, deny as _deny } from "./policy-builder.js";
+function escapeRegexMeta(s) {
+    return s.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+}
+function compileActionPatterns(actions) {
+    if (actions === "*")
+        return null;
+    const patterns = [];
+    for (const action of actions) {
+        if (action.includes("*")) {
+            const escaped = escapeRegexMeta(action).replace(/\*/g, "[^:]*");
+            patterns.push(new RegExp("^" + escaped + "$"));
+        }
+    }
+    return patterns.length > 0 ? patterns : null;
+}
+export class AccessEngine {
+    compiled = [];
+    listeners = [];
+    asyncConditions;
+    _defaultDeny;
+    _strictTenancy;
+    hierarchy;
+    cache;
+    conditionErrorHandler;
+    constructor(options) {
+        this.asyncConditions = options.asyncConditions ?? false;
+        this._defaultDeny = (options.defaultEffect ?? "deny") === "deny";
+        this._strictTenancy = options.strictTenancy ?? false;
+        this.hierarchy = options.roleHierarchy;
+        this.conditionErrorHandler = options.onConditionError;
+        if (options.cacheSize && options.cacheSize > 0) {
+            this.cache = new LRUCache(options.cacheSize);
+        }
+        if (options.onDecision) {
+            this.listeners.push(options.onDecision);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Rule management
+    // -----------------------------------------------------------------------
+    addRule(rule) {
+        const frozen = Object.freeze({ ...rule });
+        this.compiled.push({
+            rule: frozen,
+            actionPatterns: compileActionPatterns(frozen.actions),
+        });
+        this.cache?.clear();
+        return this;
+    }
+    addRules(...rules) {
+        for (const rule of rules) {
+            const frozen = Object.freeze({ ...rule });
+            this.compiled.push({
+                rule: frozen,
+                actionPatterns: compileActionPatterns(frozen.actions),
+            });
+        }
+        this.cache?.clear();
+        return this;
+    }
+    removeRule(ruleId) {
+        const idx = this.compiled.findIndex((c) => c.rule.id === ruleId);
+        if (idx === -1)
+            return false;
+        this.compiled.splice(idx, 1);
+        this.cache?.clear();
+        return true;
+    }
+    getRules() {
+        return this.compiled.map((c) => c.rule);
+    }
+    clearRules() {
+        this.compiled = [];
+        this.cache?.clear();
+    }
+    // -----------------------------------------------------------------------
+    // Cache control
+    // -----------------------------------------------------------------------
+    clearCache() {
+        this.cache?.clear();
+    }
+    get cacheStats() {
+        if (!this.cache)
+            return null;
+        return { size: this.cache.size, maxSize: this.cache.maxSize };
+    }
+    // -----------------------------------------------------------------------
+    // Fluent rule builders bound to this engine's schema
+    // -----------------------------------------------------------------------
+    allow() {
+        return _allow();
+    }
+    deny() {
+        return _deny();
+    }
+    // -----------------------------------------------------------------------
+    // Observability
+    // -----------------------------------------------------------------------
+    onDecision(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx !== -1)
+                this.listeners.splice(idx, 1);
+        };
+    }
+    emit(decision) {
+        for (const listener of this.listeners) {
+            try {
+                const result = listener(decision);
+                if (result instanceof Promise) {
+                    result.catch(() => { });
+                }
+            }
+            catch {
+                // listeners must not break evaluation
+            }
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Evaluation
+    // -----------------------------------------------------------------------
+    evaluate(subject, action, resource, resourceContext = {}, tenantId) {
+        if (this.asyncConditions) {
+            throw new Error("Engine has asyncConditions enabled. Use evaluateAsync() instead.");
+        }
+        this.validateInput(subject, action, resource);
+        this.enforceTenancy(subject, tenantId);
+        const cacheKey = this.cache
+            ? buildCacheKey(subject.id, action, resource, tenantId)
+            : undefined;
+        if (cacheKey) {
+            const cached = this.cache.get(cacheKey);
+            if (cached) {
+                this.emit(cached);
+                return cached;
+            }
+        }
+        const start = performance.now();
+        const ctx = this.buildContext(subject, action, resource, resourceContext, tenantId);
+        const candidates = this.matchRules(subject, action, resource, tenantId);
+        let matched = null;
+        let matchedHasConditions = false;
+        for (const compiled of candidates) {
+            const { rule } = compiled;
+            if (!rule.conditions || rule.conditions.length === 0) {
+                matched = compiled;
+                matchedHasConditions = false;
+                break;
+            }
+            const allMet = this.evaluateConditionsSync(rule, ctx);
+            if (allMet) {
+                matched = compiled;
+                matchedHasConditions = true;
+                break;
+            }
+        }
+        const decision = this.buildDecision(matched?.rule ?? null, ctx, start);
+        if (cacheKey && !matchedHasConditions) {
+            this.cache.set(cacheKey, decision);
+        }
+        this.emit(decision);
+        return decision;
+    }
+    async evaluateAsync(subject, action, resource, resourceContext = {}, tenantId) {
+        this.validateInput(subject, action, resource);
+        this.enforceTenancy(subject, tenantId);
+        const start = performance.now();
+        const ctx = this.buildContext(subject, action, resource, resourceContext, tenantId);
+        const candidates = this.matchRules(subject, action, resource, tenantId);
+        let matched = null;
+        for (const compiled of candidates) {
+            const { rule } = compiled;
+            if (!rule.conditions || rule.conditions.length === 0) {
+                matched = rule;
+                break;
+            }
+            const results = await Promise.all(rule.conditions.map((c, i) => Promise.resolve()
+                .then(() => c(ctx))
+                .catch((err) => {
+                this.emitConditionError(rule.id, i, err);
+                return false;
+            })));
+            if (results.every(Boolean)) {
+                matched = rule;
+                break;
+            }
+        }
+        const decision = this.buildDecision(matched, ctx, start);
+        this.emit(decision);
+        return decision;
+    }
+    // -----------------------------------------------------------------------
+    // permitted() — list allowed actions on a resource for UI rendering
+    // -----------------------------------------------------------------------
+    permitted(subject, resource, actions, resourceContext = {}, tenantId) {
+        const allowed = new Set();
+        for (const action of actions) {
+            const decision = this.asyncConditions
+                ? (() => { throw new Error("Use permittedAsync() with asyncConditions enabled."); })()
+                : this.evaluate(subject, action, resource, resourceContext, tenantId);
+            if (decision.allowed) {
+                allowed.add(action);
+            }
+        }
+        return allowed;
+    }
+    async permittedAsync(subject, resource, actions, resourceContext = {}, tenantId) {
+        const allowed = new Set();
+        const results = await Promise.all(actions.map((action) => this.evaluateAsync(subject, action, resource, resourceContext, tenantId)));
+        for (let i = 0; i < actions.length; i++) {
+            if (results[i].allowed) {
+                allowed.add(actions[i]);
+            }
+        }
+        return allowed;
+    }
+    // -----------------------------------------------------------------------
+    // explain() — full evaluation trace for debugging
+    // -----------------------------------------------------------------------
+    explain(subject, action, resource, resourceContext = {}, tenantId) {
+        if (this.asyncConditions) {
+            throw new Error("Engine has asyncConditions enabled. Use explainAsync() instead.");
+        }
+        this.enforceTenancy(subject, tenantId);
+        const start = performance.now();
+        const ctx = this.buildContext(subject, action, resource, resourceContext, tenantId);
+        const subjectRoles = this.resolveRoles(subject, tenantId);
+        const evaluatedRules = [];
+        let firstMatch = null;
+        const sorted = this.sortCandidates([...this.compiled]);
+        for (const compiled of sorted) {
+            const { rule } = compiled;
+            const roleMatched = rule.roles === "*" || rule.roles.some((r) => subjectRoles.has(r));
+            const actionMatched = rule.actions === "*" || this.matchesAction(compiled, action);
+            const resourceMatched = rule.resources === "*" || rule.resources.includes(resource);
+            const conditionResults = [];
+            let allConditionsPassed = true;
+            if (roleMatched && actionMatched && resourceMatched && rule.conditions) {
+                for (let i = 0; i < rule.conditions.length; i++) {
+                    try {
+                        const result = rule.conditions[i](ctx);
+                        if (result !== true) {
+                            conditionResults.push({ index: i, passed: false });
+                            allConditionsPassed = false;
+                        }
+                        else {
+                            conditionResults.push({ index: i, passed: true });
+                        }
+                    }
+                    catch (err) {
+                        conditionResults.push({
+                            index: i,
+                            passed: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                        allConditionsPassed = false;
+                    }
+                }
+            }
+            const matched = roleMatched && actionMatched && resourceMatched &&
+                (!rule.conditions || rule.conditions.length === 0 || allConditionsPassed);
+            evaluatedRules.push({
+                rule,
+                roleMatched,
+                actionMatched,
+                resourceMatched,
+                conditionResults,
+                matched,
+            });
+            if (matched && !firstMatch) {
+                firstMatch = rule;
+            }
+        }
+        const allowed = firstMatch != null ? firstMatch.effect === "allow" : !this._defaultDeny;
+        const effect = firstMatch?.effect ?? "default-deny";
+        const reason = firstMatch
+            ? `Matched rule "${firstMatch.id}"${firstMatch.description ? `: ${firstMatch.description}` : ""}`
+            : "No matching rule — default deny";
+        return {
+            allowed,
+            effect,
+            reason,
+            evaluatedRules,
+            durationMs: performance.now() - start,
+        };
+    }
+    async explainAsync(subject, action, resource, resourceContext = {}, tenantId) {
+        this.enforceTenancy(subject, tenantId);
+        const start = performance.now();
+        const ctx = this.buildContext(subject, action, resource, resourceContext, tenantId);
+        const subjectRoles = this.resolveRoles(subject, tenantId);
+        const evaluatedRules = [];
+        let firstMatch = null;
+        const sorted = this.sortCandidates([...this.compiled]);
+        for (const compiled of sorted) {
+            const { rule } = compiled;
+            const roleMatched = rule.roles === "*" || rule.roles.some((r) => subjectRoles.has(r));
+            const actionMatched = rule.actions === "*" || this.matchesAction(compiled, action);
+            const resourceMatched = rule.resources === "*" || rule.resources.includes(resource);
+            const conditionResults = [];
+            let allConditionsPassed = true;
+            if (roleMatched && actionMatched && resourceMatched && rule.conditions) {
+                for (let i = 0; i < rule.conditions.length; i++) {
+                    try {
+                        const result = await rule.conditions[i](ctx);
+                        if (result !== true) {
+                            conditionResults.push({ index: i, passed: false });
+                            allConditionsPassed = false;
+                        }
+                        else {
+                            conditionResults.push({ index: i, passed: true });
+                        }
+                    }
+                    catch (err) {
+                        conditionResults.push({
+                            index: i,
+                            passed: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                        allConditionsPassed = false;
+                    }
+                }
+            }
+            const matched = roleMatched && actionMatched && resourceMatched &&
+                (!rule.conditions || rule.conditions.length === 0 || allConditionsPassed);
+            evaluatedRules.push({
+                rule,
+                roleMatched,
+                actionMatched,
+                resourceMatched,
+                conditionResults,
+                matched,
+            });
+            if (matched && !firstMatch) {
+                firstMatch = rule;
+            }
+        }
+        const allowed = firstMatch != null ? firstMatch.effect === "allow" : !this._defaultDeny;
+        const effect = firstMatch?.effect ?? "default-deny";
+        const reason = firstMatch
+            ? `Matched rule "${firstMatch.id}"${firstMatch.description ? `: ${firstMatch.description}` : ""}`
+            : "No matching rule — default deny";
+        return {
+            allowed,
+            effect,
+            reason,
+            evaluatedRules,
+            durationMs: performance.now() - start,
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Fluent check API: can(subject).perform(action).on(resource)
+    // -----------------------------------------------------------------------
+    can(subject) {
+        return new PerformStep(this, subject);
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    validateInput(subject, action, resource) {
+        if (!subject || typeof subject.id !== "string") {
+            throw new Error("subject must be an object with a string id");
+        }
+        if (!Array.isArray(subject.roles)) {
+            throw new Error("subject.roles must be an array");
+        }
+        if (!action || typeof action !== "string") {
+            throw new Error("action must be a non-empty string");
+        }
+        if (!resource || typeof resource !== "string") {
+            throw new Error("resource must be a non-empty string");
+        }
+    }
+    enforceTenancy(subject, tenantId) {
+        if (!this._strictTenancy || tenantId != null)
+            return;
+        const hasTenantScoped = subject.roles.some((r) => r.tenantId != null);
+        if (hasTenantScoped) {
+            throw new Error("strictTenancy is enabled and subject has tenant-scoped roles, " +
+                "but no tenantId was provided to evaluate(). This could cause " +
+                "cross-tenant privilege escalation. Pass an explicit tenantId.");
+        }
+    }
+    buildContext(subject, action, resource, resourceContext, tenantId) {
+        return { subject, action, resource, resourceContext, tenantId };
+    }
+    evaluateConditionsSync(rule, ctx) {
+        if (!rule.conditions)
+            return true;
+        for (let i = 0; i < rule.conditions.length; i++) {
+            try {
+                if (rule.conditions[i](ctx) !== true)
+                    return false;
+            }
+            catch (err) {
+                this.emitConditionError(rule.id, i, err);
+                return false;
+            }
+        }
+        return true;
+    }
+    emitConditionError(ruleId, conditionIndex, error) {
+        if (this.conditionErrorHandler) {
+            try {
+                this.conditionErrorHandler({ ruleId, conditionIndex, error });
+            }
+            catch {
+                // error handler must not break evaluation
+            }
+        }
+    }
+    matchRules(subject, action, resource, tenantId) {
+        const subjectRoles = this.resolveRoles(subject, tenantId);
+        const matched = this.compiled.filter((compiled) => {
+            const { rule } = compiled;
+            if (rule.roles !== "*" && !rule.roles.some((r) => subjectRoles.has(r)))
+                return false;
+            if (rule.actions !== "*" && !this.matchesAction(compiled, action))
+                return false;
+            if (rule.resources !== "*" && !rule.resources.includes(resource))
+                return false;
+            return true;
+        });
+        return this.sortCandidates(matched);
+    }
+    sortCandidates(candidates) {
+        return candidates.sort((a, b) => {
+            const pa = a.rule.priority ?? 0;
+            const pb = b.rule.priority ?? 0;
+            if (pb !== pa)
+                return pb - pa;
+            if (a.rule.effect === "deny" && b.rule.effect === "allow")
+                return -1;
+            if (a.rule.effect === "allow" && b.rule.effect === "deny")
+                return 1;
+            return 0;
+        });
+    }
+    matchesAction(compiled, action) {
+        const { rule, actionPatterns } = compiled;
+        if (rule.actions === "*")
+            return true;
+        const actionStr = action;
+        if (rule.actions.includes(actionStr))
+            return true;
+        if (actionPatterns) {
+            for (const pattern of actionPatterns) {
+                if (pattern.test(actionStr))
+                    return true;
+            }
+        }
+        return false;
+    }
+    resolveRoles(subject, tenantId) {
+        const directRoles = new Set();
+        for (const assignment of subject.roles) {
+            if (tenantId == null || assignment.tenantId == null || assignment.tenantId === tenantId) {
+                directRoles.add(assignment.role);
+            }
+        }
+        if (!this.hierarchy)
+            return directRoles;
+        const expanded = new Set();
+        for (const role of directRoles) {
+            for (const r of this.hierarchy.resolve(role)) {
+                expanded.add(r);
+            }
+        }
+        return expanded;
+    }
+    buildDecision(matched, ctx, start) {
+        const allowed = matched != null ? matched.effect === "allow" : !this._defaultDeny;
+        const effect = matched?.effect ?? "default-deny";
+        const reason = matched
+            ? `Matched rule "${matched.id}"${matched.description ? `: ${matched.description}` : ""}`
+            : "No matching rule — default deny";
+        return {
+            allowed,
+            effect,
+            matchedRule: matched,
+            subject: ctx.subject,
+            action: ctx.action,
+            resource: ctx.resource,
+            resourceContext: ctx.resourceContext,
+            tenantId: ctx.tenantId,
+            timestamp: Date.now(),
+            durationMs: performance.now() - start,
+            reason,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Fluent check chain: can(user).perform(action).on(resource)
+// ---------------------------------------------------------------------------
+class PerformStep {
+    engine;
+    subject;
+    constructor(engine, subject) {
+        this.engine = engine;
+        this.subject = subject;
+    }
+    perform(action) {
+        return new OnStep(this.engine, this.subject, action);
+    }
+}
+class OnStep {
+    engine;
+    subject;
+    action;
+    constructor(engine, subject, action) {
+        this.engine = engine;
+        this.subject = subject;
+        this.action = action;
+    }
+    on(resource, resourceContext = {}, tenantId) {
+        return this.engine.evaluate(this.subject, this.action, resource, resourceContext, tenantId);
+    }
+    async onAsync(resource, resourceContext = {}, tenantId) {
+        return this.engine.evaluateAsync(this.subject, this.action, resource, resourceContext, tenantId);
+    }
+}
+// ---------------------------------------------------------------------------
+// Simple LRU cache
+// ---------------------------------------------------------------------------
+function buildCacheKey(subjectId, action, resource, tenantId) {
+    return `${subjectId.length}:${subjectId}\0${action}\0${resource}\0${tenantId ?? ""}`;
+}
+class LRUCache {
+    map = new Map();
+    maxSize;
+    constructor(maxSize) {
+        this.maxSize = maxSize;
+    }
+    get size() {
+        return this.map.size;
+    }
+    get(key) {
+        const value = this.map.get(key);
+        if (value !== undefined) {
+            this.map.delete(key);
+            this.map.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        if (this.map.has(key)) {
+            this.map.delete(key);
+        }
+        else if (this.map.size >= this.maxSize) {
+            const oldest = this.map.keys().next().value;
+            if (oldest !== undefined)
+                this.map.delete(oldest);
+        }
+        this.map.set(key, value);
+    }
+    clear() {
+        this.map.clear();
+    }
+}
+//# sourceMappingURL=engine.js.map