@rbacbee-lib/core 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# @rbacbee-lib/core
+
+Framework-agnostic authorization engine for RBAC, scoped permissions and policy evaluation.
+
+```ts
+import { createRbacEngine } from '@rbacbee-lib/core';
+
+const engine = createRbacEngine({ accessRepository });
+
+const result = await engine.can({ userId: 'user-1' }, 'posts:update', {
+  tenantId: 'tenant-1'
+});
+```
+
+Security defaults:
+
+- Deny by default.
+- No implicit user storage assumptions.
+- Input validation through value objects.
+- Storage and cache are ports, not framework dependencies.

package/dist/index.cjs

@@ -0,0 +1,629 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Assignment: () => Assignment,
+  CheckPermissionUseCase: () => CheckPermissionUseCase,
+  CheckRoleUseCase: () => CheckRoleUseCase,
+  DefaultRbacEngine: () => DefaultRbacEngine,
+  MemoryCache: () => MemoryCache,
+  Permission: () => Permission,
+  PermissionEvaluator: () => PermissionEvaluator,
+  PermissionKey: () => PermissionKey,
+  PolicyKey: () => PolicyKey,
+  PolicyRegistry: () => PolicyRegistry,
+  RbacAuthorizationError: () => RbacAuthorizationError,
+  RbacConfigurationError: () => RbacConfigurationError,
+  RbacError: () => RbacError,
+  RbacValidationError: () => RbacValidationError,
+  ResourceId: () => ResourceId,
+  Role: () => Role,
+  RoleId: () => RoleId,
+  SystemClock: () => SystemClock,
+  TenantId: () => TenantId,
+  UserId: () => UserId,
+  accessProfileCacheKey: () => accessProfileCacheKey,
+  createRbacEngine: () => createRbacEngine,
+  matchesPermission: () => matchesPermission,
+  normalizeContext: () => normalizeContext
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/domain/errors/rbac-error.ts
+var RbacError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+  }
+};
+var RbacValidationError = class extends RbacError {
+  constructor(message) {
+    super("RBAC_VALIDATION_ERROR", message);
+  }
+};
+var RbacAuthorizationError = class extends RbacError {
+  constructor(message = "Authorization denied") {
+    super("RBAC_AUTHORIZATION_DENIED", message);
+  }
+};
+var RbacConfigurationError = class extends RbacError {
+  constructor(message) {
+    super("RBAC_CONFIGURATION_ERROR", message);
+  }
+};
+
+// src/domain/value-objects/identifiers.ts
+var ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_:@./-]{0,255}$/;
+var PERMISSION_PATTERN = /^[A-Za-z0-9*][A-Za-z0-9:_.*-]{0,127}$/;
+var StringValueObject = class {
+  value;
+  constructor(value, name, pattern, maxLength) {
+    const normalized = value.trim();
+    if (normalized.length === 0) {
+      throw new RbacValidationError(`${name} cannot be empty`);
+    }
+    if (normalized.length > maxLength) {
+      throw new RbacValidationError(`${name} cannot exceed ${maxLength} characters`);
+    }
+    if (!pattern.test(normalized)) {
+      throw new RbacValidationError(`${name} contains invalid characters`);
+    }
+    this.value = normalized;
+    Object.freeze(this);
+  }
+  equals(other) {
+    return this.value === other.value;
+  }
+  toString() {
+    return this.value;
+  }
+};
+var UserId = class _UserId extends StringValueObject {
+  constructor(value) {
+    super(value, "UserId", ID_PATTERN, 256);
+  }
+  static create(value) {
+    return new _UserId(value);
+  }
+};
+var RoleId = class _RoleId extends StringValueObject {
+  constructor(value) {
+    super(value, "RoleId", ID_PATTERN, 256);
+  }
+  static create(value) {
+    return new _RoleId(value);
+  }
+};
+var TenantId = class _TenantId extends StringValueObject {
+  constructor(value) {
+    super(value, "TenantId", ID_PATTERN, 256);
+  }
+  static create(value) {
+    return new _TenantId(value);
+  }
+};
+var ResourceId = class _ResourceId extends StringValueObject {
+  constructor(value) {
+    super(value, "ResourceId", ID_PATTERN, 256);
+  }
+  static create(value) {
+    return new _ResourceId(value);
+  }
+};
+var PermissionKey = class _PermissionKey extends StringValueObject {
+  constructor(value) {
+    super(value, "PermissionKey", PERMISSION_PATTERN, 128);
+  }
+  static create(value) {
+    return new _PermissionKey(value);
+  }
+};
+var PolicyKey = class _PolicyKey extends StringValueObject {
+  constructor(value) {
+    super(value, "PolicyKey", PERMISSION_PATTERN, 128);
+  }
+  static create(value) {
+    return new _PolicyKey(value);
+  }
+};
+
+// src/domain/policies/policy-registry.ts
+var PolicyRegistry = class {
+  handlers = /* @__PURE__ */ new Map();
+  register(policy, handler) {
+    const key = PolicyKey.create(policy).value;
+    this.handlers.set(key, handler);
+  }
+  has(policy) {
+    return this.handlers.has(PolicyKey.create(policy).value);
+  }
+  async evaluate(policy, principal, context) {
+    const key = PolicyKey.create(policy).value;
+    const handler = this.handlers.get(key);
+    if (handler === void 0) {
+      return {
+        decision: "deny",
+        reason: "policy not registered",
+        principal,
+        context,
+        policy: key
+      };
+    }
+    const result = await handler({ principal, context });
+    if (typeof result === "boolean") {
+      return {
+        decision: result ? "allow" : "deny",
+        reason: result ? "policy allowed" : "policy denied",
+        principal,
+        context,
+        policy: key
+      };
+    }
+    return result;
+  }
+};
+
+// src/infrastructure/clock/system-clock.ts
+var SystemClock = class {
+  now() {
+    return /* @__PURE__ */ new Date();
+  }
+};
+
+// src/domain/services/permission-evaluator.ts
+var PermissionEvaluator = class {
+  evaluatePermission(profile, principal, requiredPermission, context) {
+    const now = context.now ?? /* @__PURE__ */ new Date();
+    const matched = profile.permissions.filter((permission) => permissionApplies(permission, requiredPermission, context, now)).map((permission) => permission.key);
+    if (matched.length > 0) {
+      return {
+        decision: "allow",
+        reason: "permission matched",
+        principal,
+        context,
+        permission: requiredPermission,
+        matched
+      };
+    }
+    return {
+      decision: "deny",
+      reason: "permission not found",
+      principal,
+      context,
+      permission: requiredPermission
+    };
+  }
+  evaluateRole(profile, principal, requiredRole, context) {
+    const now = context.now ?? /* @__PURE__ */ new Date();
+    const matched = profile.roles.filter((role) => roleApplies(role, requiredRole, context, now)).map((role) => role.id);
+    if (matched.length > 0) {
+      return {
+        decision: "allow",
+        reason: "role matched",
+        principal,
+        context,
+        role: requiredRole,
+        matched
+      };
+    }
+    return {
+      decision: "deny",
+      reason: "role not found",
+      principal,
+      context,
+      role: requiredRole
+    };
+  }
+};
+function matchesPermission(granted, required) {
+  if (granted === "*" || granted === required) {
+    return true;
+  }
+  const grantedParts = granted.split(":");
+  const requiredParts = required.split(":");
+  for (let index = 0; index < grantedParts.length; index += 1) {
+    const grantedPart = grantedParts[index];
+    const requiredPart = requiredParts[index];
+    if (grantedPart === void 0) {
+      return false;
+    }
+    if (grantedPart === "*") {
+      return index === grantedParts.length - 1 || requiredPart !== void 0;
+    }
+    if (requiredPart === void 0 || grantedPart !== requiredPart) {
+      return false;
+    }
+  }
+  return grantedParts.length === requiredParts.length;
+}
+function permissionApplies(granted, requiredPermission, context, now) {
+  if (granted.expiresAt !== void 0 && granted.expiresAt <= now) {
+    return false;
+  }
+  if (!scopeApplies(granted, context)) {
+    return false;
+  }
+  return matchesPermission(granted.key, requiredPermission);
+}
+function roleApplies(granted, requiredRole, context, now) {
+  if (granted.expiresAt !== void 0 && granted.expiresAt <= now) {
+    return false;
+  }
+  if (!scopeApplies(granted, context)) {
+    return false;
+  }
+  return granted.id === requiredRole || granted.name === requiredRole;
+}
+function scopeApplies(granted, context) {
+  if (granted.tenantId !== void 0 && granted.tenantId !== context.tenantId) {
+    return false;
+  }
+  if (granted.resourceType !== void 0 && granted.resourceType !== context.resourceType) {
+    return false;
+  }
+  if (granted.resourceId !== void 0 && granted.resourceId !== context.resourceId) {
+    return false;
+  }
+  return true;
+}
+
+// src/application/use-cases/check-permission.ts
+var CheckPermissionUseCase = class {
+  accessRepository;
+  evaluator;
+  cache;
+  audit;
+  clock;
+  cacheTtlMs;
+  constructor(dependencies) {
+    this.accessRepository = dependencies.accessRepository;
+    this.evaluator = dependencies.evaluator ?? new PermissionEvaluator();
+    this.cache = dependencies.cache;
+    this.audit = dependencies.audit;
+    this.clock = dependencies.clock ?? new SystemClock();
+    this.cacheTtlMs = dependencies.cacheTtlMs;
+  }
+  async execute(principal, requiredPermission, context = {}) {
+    UserId.create(principal.userId);
+    PermissionKey.create(requiredPermission);
+    const normalizedContext = normalizeContext(principal, context, this.clock.now());
+    const profile = await this.loadProfile(principal, normalizedContext);
+    const result = profile === null ? deny(principal, normalizedContext, requiredPermission, "access profile not found") : this.evaluator.evaluatePermission(
+      profile,
+      principal,
+      requiredPermission,
+      normalizedContext
+    );
+    await this.audit?.record({
+      type: "authorization.checked",
+      occurredAt: this.clock.now(),
+      decision: result.decision,
+      principal,
+      permission: requiredPermission,
+      context: normalizedContext,
+      reason: result.reason
+    });
+    return result;
+  }
+  async loadProfile(principal, context) {
+    const cacheKey = accessProfileCacheKey(principal.userId, context.tenantId);
+    const cachedProfile = await this.cache?.get(cacheKey);
+    if (cachedProfile !== void 0) {
+      return cachedProfile;
+    }
+    const query = { userId: principal.userId };
+    if (context.tenantId !== void 0) {
+      TenantId.create(context.tenantId);
+      Object.assign(query, { tenantId: context.tenantId });
+    }
+    const profile = await this.accessRepository.getAccessProfile(query);
+    if (profile !== null) {
+      await this.cache?.set(cacheKey, profile, this.cacheTtlMs);
+    }
+    return profile;
+  }
+};
+function normalizeContext(principal, context, now) {
+  return {
+    ...context,
+    tenantId: context.tenantId ?? principal.tenantId,
+    now: context.now ?? now
+  };
+}
+function accessProfileCacheKey(userId, tenantId) {
+  return `rbac:access-profile:${userId}:${tenantId ?? "global"}`;
+}
+function deny(principal, context, permission, reason) {
+  return {
+    decision: "deny",
+    reason,
+    principal,
+    context,
+    permission
+  };
+}
+
+// src/application/use-cases/check-role.ts
+var CheckRoleUseCase = class {
+  accessRepository;
+  evaluator;
+  cache;
+  audit;
+  clock;
+  cacheTtlMs;
+  constructor(dependencies) {
+    this.accessRepository = dependencies.accessRepository;
+    this.evaluator = dependencies.evaluator ?? new PermissionEvaluator();
+    this.cache = dependencies.cache;
+    this.audit = dependencies.audit;
+    this.clock = dependencies.clock ?? new SystemClock();
+    this.cacheTtlMs = dependencies.cacheTtlMs;
+  }
+  async execute(principal, requiredRole, context = {}) {
+    UserId.create(principal.userId);
+    RoleId.create(requiredRole);
+    const normalizedContext = normalizeContext(principal, context, this.clock.now());
+    const profile = await this.loadProfile(principal, normalizedContext);
+    const result = profile === null ? deny2(principal, normalizedContext, requiredRole, "access profile not found") : this.evaluator.evaluateRole(profile, principal, requiredRole, normalizedContext);
+    await this.audit?.record({
+      type: "role.checked",
+      occurredAt: this.clock.now(),
+      decision: result.decision,
+      principal,
+      role: requiredRole,
+      context: normalizedContext,
+      reason: result.reason
+    });
+    return result;
+  }
+  async loadProfile(principal, context) {
+    const cacheKey = accessProfileCacheKey(principal.userId, context.tenantId);
+    const cachedProfile = await this.cache?.get(cacheKey);
+    if (cachedProfile !== void 0) {
+      return cachedProfile;
+    }
+    const query = { userId: principal.userId };
+    if (context.tenantId !== void 0) {
+      TenantId.create(context.tenantId);
+      Object.assign(query, { tenantId: context.tenantId });
+    }
+    const profile = await this.accessRepository.getAccessProfile(query);
+    if (profile !== null) {
+      await this.cache?.set(cacheKey, profile, this.cacheTtlMs);
+    }
+    return profile;
+  }
+};
+function deny2(principal, context, role, reason) {
+  return {
+    decision: "deny",
+    reason,
+    principal,
+    context,
+    role
+  };
+}
+
+// src/application/rbac-engine.ts
+var DefaultRbacEngine = class {
+  checkPermission;
+  checkRole;
+  policies;
+  audit;
+  clock;
+  constructor(dependencies) {
+    this.clock = dependencies.clock ?? new SystemClock();
+    this.audit = dependencies.audit;
+    this.policies = dependencies.policies ?? new PolicyRegistry();
+    this.checkPermission = new CheckPermissionUseCase(dependencies);
+    this.checkRole = new CheckRoleUseCase(dependencies);
+  }
+  can(principal, permission, context = {}) {
+    return this.checkPermission.execute(principal, permission, context);
+  }
+  async assertCan(principal, permission, context = {}) {
+    const result = await this.can(principal, permission, context);
+    if (result.decision === "deny") {
+      throw new RbacAuthorizationError(result.reason);
+    }
+  }
+  hasRole(principal, role, context = {}) {
+    return this.checkRole.execute(principal, role, context);
+  }
+  async evaluatePolicy(policy, principal, context = {}) {
+    const key = PolicyKey.create(policy).value;
+    const result = await this.policies.evaluate(key, principal, {
+      ...context,
+      tenantId: context.tenantId ?? principal.tenantId,
+      now: context.now ?? this.clock.now()
+    });
+    await this.audit?.record({
+      type: "policy.checked",
+      occurredAt: this.clock.now(),
+      decision: result.decision,
+      principal,
+      policy: key,
+      context: result.context,
+      reason: result.reason
+    });
+    return result;
+  }
+};
+function createRbacEngine(dependencies) {
+  return new DefaultRbacEngine(dependencies);
+}
+
+// src/domain/entities/assignment.ts
+var Assignment = class _Assignment {
+  userId;
+  roleId;
+  tenantId;
+  resourceType;
+  resourceId;
+  expiresAt;
+  constructor(input) {
+    this.userId = UserId.create(input.userId);
+    this.roleId = RoleId.create(input.roleId);
+    this.tenantId = input.tenantId === void 0 ? void 0 : TenantId.create(input.tenantId);
+    this.resourceType = input.resourceType;
+    this.resourceId = input.resourceId === void 0 ? void 0 : ResourceId.create(input.resourceId);
+    this.expiresAt = input.expiresAt;
+    Object.freeze(this);
+  }
+  static create(input) {
+    return new _Assignment(input);
+  }
+  toPrimitives() {
+    const output = {
+      userId: this.userId.value,
+      roleId: this.roleId.value
+    };
+    return {
+      ...output,
+      ...this.tenantId === void 0 ? {} : { tenantId: this.tenantId.value },
+      ...this.resourceType === void 0 ? {} : { resourceType: this.resourceType },
+      ...this.resourceId === void 0 ? {} : { resourceId: this.resourceId.value },
+      ...this.expiresAt === void 0 ? {} : { expiresAt: this.expiresAt }
+    };
+  }
+};
+
+// src/domain/entities/permission.ts
+var Permission = class _Permission {
+  key;
+  description;
+  constructor(key, description) {
+    this.key = key;
+    this.description = description;
+    Object.freeze(this);
+  }
+  static create(input) {
+    return new _Permission(PermissionKey.create(input.key), input.description);
+  }
+  toPrimitives() {
+    const output = { key: this.key.value };
+    if (this.description !== void 0) {
+      return { ...output, description: this.description };
+    }
+    return output;
+  }
+};
+
+// src/domain/entities/role.ts
+var Role = class _Role {
+  id;
+  name;
+  tenantId;
+  permissions;
+  constructor(id, name, permissions, tenantId) {
+    const normalizedName = name.trim();
+    if (normalizedName.length === 0) {
+      throw new Error("Role name cannot be empty");
+    }
+    this.id = id;
+    this.name = normalizedName;
+    this.permissions = Object.freeze([...permissions]);
+    this.tenantId = tenantId;
+    Object.freeze(this);
+  }
+  static create(input) {
+    return new _Role(
+      RoleId.create(input.id),
+      input.name,
+      (input.permissions ?? []).map((permission) => PermissionKey.create(permission)),
+      input.tenantId === void 0 ? void 0 : TenantId.create(input.tenantId)
+    );
+  }
+  toPrimitives() {
+    const output = {
+      id: this.id.value,
+      name: this.name,
+      permissions: this.permissions.map((permission) => permission.value)
+    };
+    if (this.tenantId !== void 0) {
+      return { ...output, tenantId: this.tenantId.value };
+    }
+    return output;
+  }
+};
+
+// src/infrastructure/cache/memory-cache.ts
+var MemoryCache = class {
+  entries = /* @__PURE__ */ new Map();
+  async get(key) {
+    const entry = this.entries.get(key);
+    if (entry === void 0) {
+      return void 0;
+    }
+    if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) {
+      this.entries.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  async set(key, value, ttlMs) {
+    const entry = ttlMs === void 0 ? { value } : { value, expiresAt: Date.now() + ttlMs };
+    this.entries.set(key, entry);
+  }
+  async delete(key) {
+    this.entries.delete(key);
+  }
+  async deleteByPrefix(prefix) {
+    for (const key of this.entries.keys()) {
+      if (key.startsWith(prefix)) {
+        this.entries.delete(key);
+      }
+    }
+  }
+  clear() {
+    this.entries.clear();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Assignment,
+  CheckPermissionUseCase,
+  CheckRoleUseCase,
+  DefaultRbacEngine,
+  MemoryCache,
+  Permission,
+  PermissionEvaluator,
+  PermissionKey,
+  PolicyKey,
+  PolicyRegistry,
+  RbacAuthorizationError,
+  RbacConfigurationError,
+  RbacError,
+  RbacValidationError,
+  ResourceId,
+  Role,
+  RoleId,
+  SystemClock,
+  TenantId,
+  UserId,
+  accessProfileCacheKey,
+  createRbacEngine,
+  matchesPermission,
+  normalizeContext
+});
+//# sourceMappingURL=index.cjs.map