@rbacbee-lib/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,300 @@
+type RbacDecision = 'allow' | 'deny';
+type RbacRequirementMode = 'all' | 'any';
+interface RbacPrincipal {
+    readonly userId: string;
+    readonly tenantId?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface RbacAuthorizationContext {
+    readonly tenantId?: string;
+    readonly resourceType?: string;
+    readonly resourceId?: string;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly now?: Date;
+}
+interface AccessPermission {
+    readonly key: string;
+    readonly tenantId?: string;
+    readonly resourceType?: string;
+    readonly resourceId?: string;
+    readonly expiresAt?: Date;
+    readonly sourceRoleId?: string;
+}
+interface AccessRole {
+    readonly id: string;
+    readonly name?: string;
+    readonly tenantId?: string;
+    readonly resourceType?: string;
+    readonly resourceId?: string;
+    readonly expiresAt?: Date;
+}
+interface AccessProfile {
+    readonly userId: string;
+    readonly tenantId?: string;
+    readonly permissions: readonly AccessPermission[];
+    readonly roles: readonly AccessRole[];
+    readonly loadedAt: Date;
+}
+interface AuthorizationResult {
+    readonly decision: RbacDecision;
+    readonly reason: string;
+    readonly principal: RbacPrincipal;
+    readonly context: RbacAuthorizationContext;
+    readonly permission?: string;
+    readonly role?: string;
+    readonly policy?: string;
+    readonly matched?: readonly string[];
+}
+interface PermissionDefinition {
+    readonly key: string;
+    readonly description?: string;
+}
+interface RoleDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly tenantId?: string;
+    readonly permissions?: readonly string[];
+}
+interface RoleAssignment {
+    readonly userId: string;
+    readonly roleId: string;
+    readonly tenantId?: string;
+    readonly resourceType?: string;
+    readonly resourceId?: string;
+    readonly expiresAt?: Date;
+}
+interface RoleAssignmentRevocation {
+    readonly userId: string;
+    readonly roleId: string;
+    readonly tenantId?: string;
+    readonly resourceType?: string;
+    readonly resourceId?: string;
+}
+
+interface RbacPolicyInput {
+    readonly principal: RbacPrincipal;
+    readonly context: RbacAuthorizationContext;
+}
+type RbacPolicyHandler = (input: RbacPolicyInput) => boolean | AuthorizationResult | Promise<boolean | AuthorizationResult>;
+declare class PolicyRegistry {
+    private readonly handlers;
+    register(policy: string, handler: RbacPolicyHandler): void;
+    has(policy: string): boolean;
+    evaluate(policy: string, principal: RbacPrincipal, context: RbacAuthorizationContext): Promise<AuthorizationResult>;
+}
+
+interface AccessProfileQuery {
+    readonly userId: string;
+    readonly tenantId?: string;
+}
+interface AccessRepository {
+    getAccessProfile(query: AccessProfileQuery): Promise<AccessProfile | null>;
+}
+interface PermissionRepository {
+    upsertPermission(permission: PermissionDefinition): Promise<void>;
+    deletePermission(permissionKey: string): Promise<void>;
+}
+interface RoleRepository {
+    createRole(role: RoleDefinition): Promise<void>;
+    deleteRole(roleId: string): Promise<void>;
+    grantPermissionToRole(roleId: string, permissionKey: string): Promise<void>;
+    revokePermissionFromRole(roleId: string, permissionKey: string): Promise<void>;
+}
+interface AssignmentRepository {
+    assignRole(assignment: RoleAssignment): Promise<void>;
+    revokeRole(revocation: RoleAssignmentRevocation): Promise<void>;
+}
+
+type RbacAuditEventType = 'authorization.checked' | 'policy.checked' | 'role.checked' | 'role.assigned' | 'role.revoked';
+interface RbacAuditEvent {
+    readonly type: RbacAuditEventType;
+    readonly occurredAt: Date;
+    readonly decision?: RbacDecision;
+    readonly principal?: RbacPrincipal;
+    readonly permission?: string;
+    readonly role?: string;
+    readonly policy?: string;
+    readonly context?: RbacAuthorizationContext;
+    readonly reason?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface AuditPort {
+    record(event: RbacAuditEvent): Promise<void> | void;
+}
+
+interface CachePort {
+    get<TValue>(key: string): Promise<TValue | undefined>;
+    set<TValue>(key: string, value: TValue, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteByPrefix?(prefix: string): Promise<void>;
+}
+
+interface ClockPort {
+    now(): Date;
+}
+
+interface RbacEngine {
+    can(principal: RbacPrincipal, permission: string, context?: RbacAuthorizationContext): Promise<AuthorizationResult>;
+    assertCan(principal: RbacPrincipal, permission: string, context?: RbacAuthorizationContext): Promise<void>;
+    hasRole(principal: RbacPrincipal, role: string, context?: RbacAuthorizationContext): Promise<AuthorizationResult>;
+    evaluatePolicy(policy: string, principal: RbacPrincipal, context?: RbacAuthorizationContext): Promise<AuthorizationResult>;
+}
+interface RbacEngineDependencies {
+    readonly accessRepository: AccessRepository;
+    readonly cache?: CachePort;
+    readonly audit?: AuditPort;
+    readonly clock?: ClockPort;
+    readonly policies?: PolicyRegistry;
+    readonly cacheTtlMs?: number;
+}
+declare class DefaultRbacEngine implements RbacEngine {
+    private readonly checkPermission;
+    private readonly checkRole;
+    private readonly policies;
+    private readonly audit?;
+    private readonly clock;
+    constructor(dependencies: RbacEngineDependencies);
+    can(principal: RbacPrincipal, permission: string, context?: RbacAuthorizationContext): Promise<AuthorizationResult>;
+    assertCan(principal: RbacPrincipal, permission: string, context?: RbacAuthorizationContext): Promise<void>;
+    hasRole(principal: RbacPrincipal, role: string, context?: RbacAuthorizationContext): Promise<AuthorizationResult>;
+    evaluatePolicy(policy: string, principal: RbacPrincipal, context?: RbacAuthorizationContext): Promise<AuthorizationResult>;
+}
+declare function createRbacEngine(dependencies: RbacEngineDependencies): RbacEngine;
+
+declare class PermissionEvaluator {
+    evaluatePermission(profile: AccessProfile, principal: RbacPrincipal, requiredPermission: string, context: RbacAuthorizationContext): AuthorizationResult;
+    evaluateRole(profile: AccessProfile, principal: RbacPrincipal, requiredRole: string, context: RbacAuthorizationContext): AuthorizationResult;
+}
+declare function matchesPermission(granted: string, required: string): boolean;
+
+interface CheckPermissionDependencies {
+    readonly accessRepository: AccessRepository;
+    readonly evaluator?: PermissionEvaluator;
+    readonly cache?: CachePort;
+    readonly audit?: AuditPort;
+    readonly clock?: ClockPort;
+    readonly cacheTtlMs?: number;
+}
+declare class CheckPermissionUseCase {
+    private readonly accessRepository;
+    private readonly evaluator;
+    private readonly cache?;
+    private readonly audit?;
+    private readonly clock;
+    private readonly cacheTtlMs?;
+    constructor(dependencies: CheckPermissionDependencies);
+    execute(principal: RbacPrincipal, requiredPermission: string, context?: RbacAuthorizationContext): Promise<AuthorizationResult>;
+    private loadProfile;
+}
+declare function normalizeContext(principal: RbacPrincipal, context: RbacAuthorizationContext, now: Date): RbacAuthorizationContext;
+declare function accessProfileCacheKey(userId: string, tenantId?: string): string;
+
+interface CheckRoleDependencies {
+    readonly accessRepository: AccessRepository;
+    readonly evaluator?: PermissionEvaluator;
+    readonly cache?: CachePort;
+    readonly audit?: AuditPort;
+    readonly clock?: ClockPort;
+    readonly cacheTtlMs?: number;
+}
+declare class CheckRoleUseCase {
+    private readonly accessRepository;
+    private readonly evaluator;
+    private readonly cache?;
+    private readonly audit?;
+    private readonly clock;
+    private readonly cacheTtlMs?;
+    constructor(dependencies: CheckRoleDependencies);
+    execute(principal: RbacPrincipal, requiredRole: string, context?: RbacAuthorizationContext): Promise<AuthorizationResult>;
+    private loadProfile;
+}
+
+declare abstract class StringValueObject {
+    readonly value: string;
+    protected constructor(value: string, name: string, pattern: RegExp, maxLength: number);
+    equals(other: StringValueObject): boolean;
+    toString(): string;
+}
+declare class UserId extends StringValueObject {
+    private constructor();
+    static create(value: string): UserId;
+}
+declare class RoleId extends StringValueObject {
+    private constructor();
+    static create(value: string): RoleId;
+}
+declare class TenantId extends StringValueObject {
+    private constructor();
+    static create(value: string): TenantId;
+}
+declare class ResourceId extends StringValueObject {
+    private constructor();
+    static create(value: string): ResourceId;
+}
+declare class PermissionKey extends StringValueObject {
+    private constructor();
+    static create(value: string): PermissionKey;
+}
+declare class PolicyKey extends StringValueObject {
+    private constructor();
+    static create(value: string): PolicyKey;
+}
+
+declare class Assignment {
+    readonly userId: UserId;
+    readonly roleId: RoleId;
+    readonly tenantId?: TenantId;
+    readonly resourceType?: string;
+    readonly resourceId?: ResourceId;
+    readonly expiresAt?: Date;
+    private constructor();
+    static create(input: RoleAssignment): Assignment;
+    toPrimitives(): RoleAssignment;
+}
+
+declare class Permission {
+    readonly key: PermissionKey;
+    readonly description?: string;
+    private constructor();
+    static create(input: PermissionDefinition): Permission;
+    toPrimitives(): PermissionDefinition;
+}
+
+declare class Role {
+    readonly id: RoleId;
+    readonly name: string;
+    readonly tenantId?: TenantId;
+    readonly permissions: readonly PermissionKey[];
+    private constructor();
+    static create(input: RoleDefinition): Role;
+    toPrimitives(): RoleDefinition;
+}
+
+declare class RbacError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+declare class RbacValidationError extends RbacError {
+    constructor(message: string);
+}
+declare class RbacAuthorizationError extends RbacError {
+    constructor(message?: string);
+}
+declare class RbacConfigurationError extends RbacError {
+    constructor(message: string);
+}
+
+declare class MemoryCache implements CachePort {
+    private readonly entries;
+    get<TValue>(key: string): Promise<TValue | undefined>;
+    set<TValue>(key: string, value: TValue, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteByPrefix(prefix: string): Promise<void>;
+    clear(): void;
+}
+
+declare class SystemClock implements ClockPort {
+    now(): Date;
+}
+
+export { type AccessPermission, type AccessProfile, type AccessProfileQuery, type AccessRepository, type AccessRole, Assignment, type AssignmentRepository, type AuditPort, type AuthorizationResult, type CachePort, type CheckPermissionDependencies, CheckPermissionUseCase, type CheckRoleDependencies, CheckRoleUseCase, type ClockPort, DefaultRbacEngine, MemoryCache, Permission, type PermissionDefinition, PermissionEvaluator, PermissionKey, type PermissionRepository, PolicyKey, PolicyRegistry, type RbacAuditEvent, type RbacAuditEventType, type RbacAuthorizationContext, RbacAuthorizationError, RbacConfigurationError, type RbacDecision, type RbacEngine, type RbacEngineDependencies, RbacError, type RbacPolicyHandler, type RbacPolicyInput, type RbacPrincipal, type RbacRequirementMode, RbacValidationError, ResourceId, Role, type RoleAssignment, type RoleAssignmentRevocation, type RoleDefinition, RoleId, type RoleRepository, SystemClock, TenantId, UserId, accessProfileCacheKey, createRbacEngine, matchesPermission, normalizeContext };