@shohaghinfo/aerojs 0.1.0

package/dist/audit/audit-trail.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @file audit-trail.ts
+ * @description Immutable Audit Trail System for AeroJS.
+ *
+ * Hospital Architecture Section 38:
+ * "হাসপাতালের কোনো মেডিকেল ও ফিন্যান্সিয়াল ডাটা ডাটাবেস থেকে কখনো DELETE করা যাবে না।
+ * ভুল এন্ট্রি হলে তা STATUS = VOID বা CANCELLED হবে এবং রিভার্সাল এন্ট্রি পড়বে।"
+ *
+ * Stores: User ID, Table/Module, Record ID, Action, Old Value, New Value,
+ *         IP Address, Timestamp, Cancellation Reason.
+ */
+export type AuditAction = 'CREATE' | 'UPDATE' | 'VOID' | 'APPROVE' | 'REJECT' | 'PRINT' | 'LOGIN' | 'LOGOUT' | 'LOCK' | 'RESTORE' | 'EXPORT';
+export interface AuditLogEntry {
+    userId: string | number;
+    userRole?: string;
+    module: string;
+    tableName?: string;
+    recordId: string | number;
+    action: AuditAction;
+    oldValue?: Record<string, unknown> | null;
+    newValue?: Record<string, unknown> | null;
+    reason?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    branchId?: string | number;
+    metadata?: Record<string, unknown>;
+}
+export interface AuditLogRecord extends AuditLogEntry {
+    id: number;
+    createdAt: Date;
+}
+export interface AuditDriver {
+    log(entry: AuditLogEntry): Promise<void>;
+    getHistory(tableName: string, recordId: string | number): Promise<AuditLogRecord[]>;
+    getUserActivity(userId: string | number, from?: Date, to?: Date): Promise<AuditLogRecord[]>;
+}
+/**
+ * Database-backed audit driver.
+ * Requires `audit_logs` table (see migration below).
+ */
+export declare class DatabaseAuditDriver implements AuditDriver {
+    private table;
+    constructor(table?: string);
+    log(entry: AuditLogEntry): Promise<void>;
+    getHistory(tableName: string, recordId: string | number): Promise<AuditLogRecord[]>;
+    getUserActivity(userId: string | number, from?: Date, to?: Date): Promise<AuditLogRecord[]>;
+}
+/**
+ * In-memory audit driver (testing only).
+ */
+export declare class MemoryAuditDriver implements AuditDriver {
+    logs: (AuditLogEntry & {
+        id: number;
+        createdAt: Date;
+    })[];
+    private counter;
+    log(entry: AuditLogEntry): Promise<void>;
+    getHistory(tableName: string, recordId: string | number): Promise<AuditLogRecord[]>;
+    getUserActivity(userId: string | number): Promise<AuditLogRecord[]>;
+}
+export declare class AuditTrailManager {
+    private driver;
+    configure(driver: AuditDriver): this;
+    /**
+     * Log an audit event.
+     *
+     * @example
+     * await AuditTrail.log({
+     *   userId: ctx.auth.user()!.id,
+     *   module: 'billing',
+     *   tableName: 'invoices',
+     *   recordId: invoice.id,
+     *   action: 'VOID',
+     *   oldValue: { status: 'paid', amount: 5000 },
+     *   newValue: { status: 'void', amount: 5000 },
+     *   reason: 'Duplicate bill entry',
+     *   ipAddress: ctx.req.ip,
+     * });
+     */
+    log(entry: AuditLogEntry): Promise<void>;
+    /**
+     * Get full history of changes for a specific record.
+     * Hospital use: "Who changed this invoice? Show all modifications."
+     */
+    getHistory(tableName: string, recordId: string | number): Promise<AuditLogRecord[]>;
+    /**
+     * Get all activity by a specific user in a time range.
+     * Hospital use: "What did cashier #42 do during the night shift?"
+     */
+    getUserActivity(userId: string | number, from?: Date, to?: Date): Promise<AuditLogRecord[]>;
+}
+export declare const AuditTrail: AuditTrailManager;
+/**
+ * Migration SQL for audit_logs table.
+ *
+ * @example
+ * // In database/migrations/YYYY_create_audit_logs_table.ts:
+ * await Schema.create('audit_logs', (table) => {
+ *   table.increments('id');
+ *   table.string('user_id', 50).notNull();
+ *   table.string('user_role', 50).nullable();
+ *   table.string('module', 100).notNull();
+ *   table.string('table_name', 100).nullable();
+ *   table.string('record_id', 100).notNull();
+ *   table.string('action', 30).notNull();   // CREATE, UPDATE, VOID, APPROVE...
+ *   table.text('old_value').nullable();      // JSON serialized
+ *   table.text('new_value').nullable();      // JSON serialized
+ *   table.text('reason').nullable();
+ *   table.string('ip_address', 45).nullable();
+ *   table.string('user_agent', 500).nullable();
+ *   table.string('branch_id', 50).nullable();
+ *   table.text('metadata').nullable();       // JSON serialized
+ *   table.timestamp('created_at').notNull(); // IMMUTABLE — no updated_at
+ * });
+ *
+ * // Add indexes for fast lookups:
+ * // CREATE INDEX idx_audit_table_record ON audit_logs (table_name, record_id);
+ * // CREATE INDEX idx_audit_user ON audit_logs (user_id, created_at);
+ * // CREATE INDEX idx_audit_module ON audit_logs (module, created_at);
+ */
+export declare const AUDIT_LOGS_MIGRATION_HINT = "See JSDoc comment above for audit_logs table DDL";
+//# sourceMappingURL=audit-trail.d.ts.map

package/dist/audit/audit-trail.d.ts.map

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

package/dist/audit/audit-trail.js

@@ -0,0 +1,154 @@
+/**
+ * @file audit-trail.ts
+ * @description Immutable Audit Trail System for AeroJS.
+ *
+ * Hospital Architecture Section 38:
+ * "হাসপাতালের কোনো মেডিকেল ও ফিন্যান্সিয়াল ডাটা ডাটাবেস থেকে কখনো DELETE করা যাবে না।
+ * ভুল এন্ট্রি হলে তা STATUS = VOID বা CANCELLED হবে এবং রিভার্সাল এন্ট্রি পড়বে।"
+ *
+ * Stores: User ID, Table/Module, Record ID, Action, Old Value, New Value,
+ *         IP Address, Timestamp, Cancellation Reason.
+ */
+import { DB } from '../database/connection.js';
+/**
+ * Database-backed audit driver.
+ * Requires `audit_logs` table (see migration below).
+ */
+export class DatabaseAuditDriver {
+    table;
+    constructor(table = 'audit_logs') {
+        this.table = table;
+    }
+    async log(entry) {
+        await DB.table(this.table).insert({
+            user_id: entry.userId,
+            user_role: entry.userRole ?? null,
+            module: entry.module,
+            table_name: entry.tableName ?? null,
+            record_id: String(entry.recordId),
+            action: entry.action,
+            old_value: entry.oldValue ? JSON.stringify(entry.oldValue) : null,
+            new_value: entry.newValue ? JSON.stringify(entry.newValue) : null,
+            reason: entry.reason ?? null,
+            ip_address: entry.ipAddress ?? null,
+            user_agent: entry.userAgent ?? null,
+            branch_id: entry.branchId ?? null,
+            metadata: entry.metadata ? JSON.stringify(entry.metadata) : null,
+            created_at: new Date(),
+        });
+    }
+    async getHistory(tableName, recordId) {
+        return await DB.table(this.table)
+            .where('table_name', tableName)
+            .where('record_id', String(recordId))
+            .orderBy('created_at', 'DESC')
+            .get();
+    }
+    async getUserActivity(userId, from, to) {
+        let qb = DB.table(this.table).where('user_id', userId);
+        if (from)
+            qb = qb.where('created_at', '>=', from);
+        if (to)
+            qb = qb.where('created_at', '<=', to);
+        return await qb.orderBy('created_at', 'DESC').get();
+    }
+}
+/**
+ * In-memory audit driver (testing only).
+ */
+export class MemoryAuditDriver {
+    logs = [];
+    counter = 0;
+    async log(entry) {
+        this.logs.push({ ...entry, id: ++this.counter, createdAt: new Date() });
+    }
+    async getHistory(tableName, recordId) {
+        return this.logs
+            .filter((l) => l.tableName === tableName && String(l.recordId) === String(recordId))
+            .reverse();
+    }
+    async getUserActivity(userId) {
+        return this.logs
+            .filter((l) => String(l.userId) === String(userId))
+            .reverse();
+    }
+}
+// ─── AuditTrail Facade ────────────────────────────────────────────────────────
+export class AuditTrailManager {
+    driver = new MemoryAuditDriver();
+    configure(driver) {
+        this.driver = driver;
+        return this;
+    }
+    /**
+     * Log an audit event.
+     *
+     * @example
+     * await AuditTrail.log({
+     *   userId: ctx.auth.user()!.id,
+     *   module: 'billing',
+     *   tableName: 'invoices',
+     *   recordId: invoice.id,
+     *   action: 'VOID',
+     *   oldValue: { status: 'paid', amount: 5000 },
+     *   newValue: { status: 'void', amount: 5000 },
+     *   reason: 'Duplicate bill entry',
+     *   ipAddress: ctx.req.ip,
+     * });
+     */
+    async log(entry) {
+        try {
+            await this.driver.log(entry);
+        }
+        catch (err) {
+            // Audit failures should NEVER crash the application
+            console.error('[AeroJS AuditTrail] Failed to write audit log:', err);
+        }
+    }
+    /**
+     * Get full history of changes for a specific record.
+     * Hospital use: "Who changed this invoice? Show all modifications."
+     */
+    async getHistory(tableName, recordId) {
+        return await this.driver.getHistory(tableName, recordId);
+    }
+    /**
+     * Get all activity by a specific user in a time range.
+     * Hospital use: "What did cashier #42 do during the night shift?"
+     */
+    async getUserActivity(userId, from, to) {
+        return await this.driver.getUserActivity(userId, from, to);
+    }
+}
+export const AuditTrail = new AuditTrailManager();
+// ─── Auditable Model Mixin ────────────────────────────────────────────────────
+/**
+ * Migration SQL for audit_logs table.
+ *
+ * @example
+ * // In database/migrations/YYYY_create_audit_logs_table.ts:
+ * await Schema.create('audit_logs', (table) => {
+ *   table.increments('id');
+ *   table.string('user_id', 50).notNull();
+ *   table.string('user_role', 50).nullable();
+ *   table.string('module', 100).notNull();
+ *   table.string('table_name', 100).nullable();
+ *   table.string('record_id', 100).notNull();
+ *   table.string('action', 30).notNull();   // CREATE, UPDATE, VOID, APPROVE...
+ *   table.text('old_value').nullable();      // JSON serialized
+ *   table.text('new_value').nullable();      // JSON serialized
+ *   table.text('reason').nullable();
+ *   table.string('ip_address', 45).nullable();
+ *   table.string('user_agent', 500).nullable();
+ *   table.string('branch_id', 50).nullable();
+ *   table.text('metadata').nullable();       // JSON serialized
+ *   table.timestamp('created_at').notNull(); // IMMUTABLE — no updated_at
+ * });
+ *
+ * // Add indexes for fast lookups:
+ * // CREATE INDEX idx_audit_table_record ON audit_logs (table_name, record_id);
+ * // CREATE INDEX idx_audit_user ON audit_logs (user_id, created_at);
+ * // CREATE INDEX idx_audit_module ON audit_logs (module, created_at);
+ */
+export const AUDIT_LOGS_MIGRATION_HINT = 'See JSDoc comment above for audit_logs table DDL';
+//# sourceMappingURL=audit-trail.js.map

package/dist/audit/audit-trail.js.map

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

package/dist/auth/auth-manager.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @file auth-manager.ts
+ * @description Central Auth Manager for AeroJS.
+ * Manages multiple named guards (session, jwt, api) and exposes ctx.auth.use('guard').
+ * Hospital use: ctx.auth.use('session') for cashiers, ctx.auth.use('jwt') for doctors.
+ */
+import type { AeroContext } from '../core/context.js';
+import type { AuthUser } from './guards/guard.js';
+import { type SessionGuardConfig } from './guards/session-guard.js';
+import { type JwtGuardConfig } from './guards/jwt-guard.js';
+import { type ApiTokenGuardConfig } from './guards/api-token-guard.js';
+import type { SessionManager } from '../session/session-manager.js';
+import type { Middleware } from '../core/types.js';
+export type GuardDriverName = 'session' | 'jwt' | 'api';
+export type GuardDriverConfig = {
+    driver: 'session';
+    config: SessionGuardConfig;
+} | {
+    driver: 'jwt';
+    config: JwtGuardConfig;
+} | {
+    driver: 'api';
+    config: ApiTokenGuardConfig;
+};
+export interface AuthConfig {
+    /**
+     * Default guard to use when calling ctx.auth.use() with no arguments.
+     */
+    default?: string;
+    /**
+     * Named guard definitions.
+     */
+    guards: Record<string, GuardDriverConfig>;
+}
+/**
+ * Per-request Auth Manager — attached to ctx.auth by authPlugin.
+ */
+export declare class Auth {
+    private guards;
+    private defaultGuardName;
+    private config;
+    private ctx;
+    private sessionManager?;
+    constructor(ctx: AeroContext, config: AuthConfig, sessionManager?: SessionManager);
+    /**
+     * Returns the named guard instance (or default if name is omitted).
+     * Guards are lazily instantiated per request.
+     *
+     * @example
+     * // Cashier session auth
+     * await ctx.auth.use('session').authenticate();
+     *
+     * // Doctor JWT auth
+     * const user = await ctx.auth.use('jwt').authenticate();
+     */
+    use(name?: string): any;
+    /**
+     * Returns the authenticated user from the default guard, or null.
+     */
+    user(): AuthUser | null;
+    /**
+     * Checks if the current user is authenticated on the default guard.
+     */
+    check(): boolean;
+}
+/**
+ * Global Auth Manager — stores config for the application lifetime.
+ */
+export declare class AuthManager {
+    private config;
+    configure(config: AuthConfig): this;
+    /**
+     * Creates a per-request Auth instance bound to the given context.
+     */
+    forContext(ctx: AeroContext, sessionManager?: SessionManager): Auth;
+}
+export declare const authManager: AuthManager;
+/**
+ * Middleware factory that attaches ctx.auth to every request.
+ * Must be registered early in the middleware chain.
+ *
+ * @example
+ * app.use(authPlugin(authManager, sessionManager));
+ */
+export declare function authPlugin(manager: AuthManager, sessionManager?: SessionManager): Middleware;
+/**
+ * Route-level middleware factory — protects a route for a specific guard.
+ * Throws UnauthorizedError if not authenticated.
+ *
+ * @example
+ * router.get('/cashier/dashboard', handler).middleware(auth('session'));
+ * router.get('/api/doctor/patients', handler).middleware(auth('jwt'));
+ */
+export declare function auth(guardName?: string): Middleware;
+//# sourceMappingURL=auth-manager.d.ts.map

package/dist/auth/auth-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-manager.d.ts","sourceRoot":"","sources":["../../src/auth/auth-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAiB,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAClF,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAAiB,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;AAExD,MAAM,MAAM,iBAAiB,GACzB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GACjD;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GACzC;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC3C;AAED;;GAEG;AACH,qBAAa,IAAI;IACf,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,GAAG,CAAc;IACzB,OAAO,CAAC,cAAc,CAAC,CAAiB;gBAE5B,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,CAAC,EAAE,cAAc;IAOjF;;;;;;;;;;OAUG;IACI,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,GAAG;IAuC9B;;OAEG;IACI,IAAI,IAAI,QAAQ,GAAG,IAAI;IAI9B;;OAEG;IACI,KAAK,IAAI,OAAO;CAGxB;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAA8B;IAErC,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAK1C;;OAEG;IACI,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI;CAG3E;AAED,eAAO,MAAM,WAAW,aAAoB,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,cAAc,CAAC,EAAE,cAAc,GAAG,UAAU,CAK5F;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,CAQnD"}

package/dist/auth/auth-manager.js

@@ -0,0 +1,130 @@
+/**
+ * @file auth-manager.ts
+ * @description Central Auth Manager for AeroJS.
+ * Manages multiple named guards (session, jwt, api) and exposes ctx.auth.use('guard').
+ * Hospital use: ctx.auth.use('session') for cashiers, ctx.auth.use('jwt') for doctors.
+ */
+import { SessionGuard } from './guards/session-guard.js';
+import { JwtGuard } from './guards/jwt-guard.js';
+import { ApiTokenGuard } from './guards/api-token-guard.js';
+import { UnauthorizedError, ForbiddenError } from '../core/errors.js';
+/**
+ * Per-request Auth Manager — attached to ctx.auth by authPlugin.
+ */
+export class Auth {
+    guards = new Map();
+    defaultGuardName;
+    config;
+    ctx;
+    sessionManager;
+    constructor(ctx, config, sessionManager) {
+        this.ctx = ctx;
+        this.config = config;
+        this.defaultGuardName = config.default ?? Object.keys(config.guards)[0] ?? 'session';
+        this.sessionManager = sessionManager;
+    }
+    /**
+     * Returns the named guard instance (or default if name is omitted).
+     * Guards are lazily instantiated per request.
+     *
+     * @example
+     * // Cashier session auth
+     * await ctx.auth.use('session').authenticate();
+     *
+     * // Doctor JWT auth
+     * const user = await ctx.auth.use('jwt').authenticate();
+     */
+    use(name) {
+        const guardName = name ?? this.defaultGuardName;
+        if (this.guards.has(guardName)) {
+            return this.guards.get(guardName);
+        }
+        const guardDef = this.config.guards[guardName];
+        if (!guardDef) {
+            throw new Error(`[AeroJS Auth] Guard "${guardName}" is not configured.`);
+        }
+        let guard;
+        switch (guardDef.driver) {
+            case 'session': {
+                if (!this.sessionManager) {
+                    throw new Error('[AeroJS Auth] Session guard requires a SessionManager. Did you call app.useSession()?');
+                }
+                guard = new SessionGuard(this.ctx, this.sessionManager, guardDef.config);
+                break;
+            }
+            case 'jwt': {
+                guard = new JwtGuard(this.ctx, guardDef.config);
+                break;
+            }
+            case 'api': {
+                guard = new ApiTokenGuard(this.ctx, guardDef.config);
+                break;
+            }
+            default: {
+                throw new Error(`[AeroJS Auth] Unknown guard driver: ${guardDef.driver}`);
+            }
+        }
+        this.guards.set(guardName, guard);
+        return guard;
+    }
+    /**
+     * Returns the authenticated user from the default guard, or null.
+     */
+    user() {
+        return this.use().user();
+    }
+    /**
+     * Checks if the current user is authenticated on the default guard.
+     */
+    check() {
+        return this.use().check();
+    }
+}
+/**
+ * Global Auth Manager — stores config for the application lifetime.
+ */
+export class AuthManager {
+    config = { guards: {} };
+    configure(config) {
+        this.config = config;
+        return this;
+    }
+    /**
+     * Creates a per-request Auth instance bound to the given context.
+     */
+    forContext(ctx, sessionManager) {
+        return new Auth(ctx, this.config, sessionManager);
+    }
+}
+export const authManager = new AuthManager();
+/**
+ * Middleware factory that attaches ctx.auth to every request.
+ * Must be registered early in the middleware chain.
+ *
+ * @example
+ * app.use(authPlugin(authManager, sessionManager));
+ */
+export function authPlugin(manager, sessionManager) {
+    return async (ctx, next) => {
+        ctx.auth = manager.forContext(ctx, sessionManager);
+        await next();
+    };
+}
+/**
+ * Route-level middleware factory — protects a route for a specific guard.
+ * Throws UnauthorizedError if not authenticated.
+ *
+ * @example
+ * router.get('/cashier/dashboard', handler).middleware(auth('session'));
+ * router.get('/api/doctor/patients', handler).middleware(auth('jwt'));
+ */
+export function auth(guardName) {
+    return async (ctx, next) => {
+        const authCtx = ctx.auth;
+        if (!authCtx)
+            throw new Error('[AeroJS Auth] authPlugin middleware is not mounted. Add app.use(authPlugin(...))');
+        await authCtx.use(guardName).authenticate();
+        await next();
+    };
+}
+//# sourceMappingURL=auth-manager.js.map

package/dist/auth/auth-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-manager.js","sourceRoot":"","sources":["../../src/auth/auth-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,YAAY,EAA2B,MAAM,2BAA2B,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAuB,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAAE,aAAa,EAA4B,MAAM,6BAA6B,CAAC;AAGtF,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAqBtE;;GAEG;AACH,MAAM,OAAO,IAAI;IACP,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC1C,gBAAgB,CAAS;IACzB,MAAM,CAAa;IACnB,GAAG,CAAc;IACjB,cAAc,CAAkB;IAExC,YAAY,GAAgB,EAAE,MAAkB,EAAE,cAA+B;QAC/E,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,gBAAgB,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC;QACrF,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;IAED;;;;;;;;;;OAUG;IACI,GAAG,CAAC,IAAa;QACtB,MAAM,SAAS,GAAG,IAAI,IAAI,IAAI,CAAC,gBAAgB,CAAC;QAEhD,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC;QACrC,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,wBAAwB,SAAS,sBAAsB,CAAC,CAAC;QAC3E,CAAC;QAED,IAAI,KAAoB,CAAC;QAEzB,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;YACxB,KAAK,SAAS,CAAC,CAAC,CAAC;gBACf,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;oBACzB,MAAM,IAAI,KAAK,CAAC,uFAAuF,CAAC,CAAC;gBAC3G,CAAC;gBACD,KAAK,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;gBACzE,MAAM;YACR,CAAC;YACD,KAAK,KAAK,CAAC,CAAC,CAAC;gBACX,KAAK,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;gBAChD,MAAM;YACR,CAAC;YACD,KAAK,KAAK,CAAC,CAAC,CAAC;gBACX,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;gBACrD,MAAM;YACR,CAAC;YACD,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,IAAI,KAAK,CAAC,uCAAwC,QAAgB,CAAC,MAAM,EAAE,CAAC,CAAC;YACrF,CAAC;QACH,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACI,IAAI;QACT,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACI,KAAK;QACV,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,WAAW;IACd,MAAM,GAAe,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAErC,SAAS,CAAC,MAAkB;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,UAAU,CAAC,GAAgB,EAAE,cAA+B;QACjE,OAAO,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,OAAoB,EAAE,cAA+B;IAC9E,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACxB,GAAW,CAAC,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC5D,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,IAAI,CAAC,SAAkB;IACrC,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACzB,MAAM,OAAO,GAAI,GAAW,CAAC,IAAY,CAAC;QAC1C,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAC;QAElH,MAAM,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,YAAY,EAAE,CAAC;QAC5C,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}

package/dist/auth/bouncer.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @file bouncer.ts
+ * @description RBAC Authorization Engine (Bouncer Pattern) for AeroJS.
+ *
+ * Supports:
+ * - Role-based checks: ctx.bouncer.is('admin')
+ * - Ability checks: ctx.bouncer.can('billing:approve-discount')
+ * - Policy-based authorization: ctx.bouncer.authorize(DiscountPolicy, 'approve', discount)
+ * - Data-scoped checks: enforcing branch-level data isolation
+ *
+ * Hospital use:
+ *   - Section 22: Discount approval matrix (cashier 0%, supervisor 5%, MS 15%, CEO any)
+ *   - Section 37: Maker-Checker dual control for refunds, POs, supplier payments
+ *   - Section 25: Branch-scoped data access (operator sees only own branch)
+ */
+import type { AuthUser } from '../auth/guards/guard.js';
+import type { Middleware } from '../core/types.js';
+export interface PolicyContract {
+    [action: string]: (user: AuthUser, ...args: any[]) => Promise<boolean> | boolean;
+}
+export type PolicyConstructor = new () => PolicyContract;
+export interface PermissionStore {
+    /**
+     * Returns all roles for a given user ID.
+     * Example: ['cashier', 'ipd_operator']
+     */
+    getRoles(userId: string | number): Promise<string[]>;
+    /**
+     * Returns all permission strings for a given user ID.
+     * Example: ['billing:view', 'billing:create', 'discount:approve:5']
+     */
+    getPermissions(userId: string | number): Promise<string[]>;
+}
+export declare class Bouncer {
+    private user;
+    private _roles;
+    private _permissions;
+    private store?;
+    private policies;
+    constructor(user: AuthUser | null, store?: PermissionStore);
+    /**
+     * Lazily loads roles from the permission store.
+     */
+    private loadRoles;
+    /**
+     * Lazily loads permissions from the permission store.
+     */
+    private loadPermissions;
+    /**
+     * Check if the authenticated user has a specific role.
+     *
+     * @example
+     * if (await ctx.bouncer.is('supervisor')) { ... }
+     */
+    is(role: string): Promise<boolean>;
+    /**
+     * Check if the user has any of the given roles.
+     *
+     * @example
+     * if (await ctx.bouncer.isAny(['ms', 'director', 'ceo'])) { ... }
+     */
+    isAny(roles: string[]): Promise<boolean>;
+    /**
+     * Check if the user has a specific permission.
+     *
+     * @example
+     * if (await ctx.bouncer.can('billing:refund')) { ... }
+     */
+    can(permission: string): Promise<boolean>;
+    /**
+     * Check if the user CANNOT perform an action.
+     */
+    cannot(permission: string): Promise<boolean>;
+    /**
+     * Hospital-specific: Check discount approval authority.
+     *
+     * Rules (Section 22):
+     *   cashier     → 0%
+     *   supervisor  → up to 5%
+     *   ms          → up to 15%
+     *   director/ceo → unlimited
+     *
+     * @example
+     * if (!await ctx.bouncer.canApproveDiscount(12.5)) {
+     *   ctx.throw(403, 'Discount exceeds your authority');
+     * }
+     */
+    canApproveDiscount(percent: number): Promise<boolean>;
+    /**
+     * Hospital-specific: Check if user belongs to a specific branch.
+     * Enforces Section 25 — branch data scoping.
+     *
+     * @example
+     * await ctx.bouncer.assertBranch(patient.branchId);
+     */
+    assertBranch(resourceBranchId: string | number): Promise<void>;
+    /**
+     * Policy-based authorization.
+     * Instantiates the policy class and calls the named action method.
+     *
+     * @example
+     * await ctx.bouncer.authorize(DiscountPolicy, 'approve', discount);
+     * await ctx.bouncer.authorize(RefundPolicy, 'check', invoice);
+     */
+    authorize(PolicyClass: PolicyConstructor, action: string, ...args: any[]): Promise<void>;
+    /**
+     * Throws ForbiddenError if the user does NOT have the given role.
+     */
+    assertIs(role: string): Promise<void>;
+    /**
+     * Throws ForbiddenError if the user does NOT have the given permission.
+     */
+    assertCan(permission: string): Promise<void>;
+}
+export declare class BouncerManager {
+    private store?;
+    configure(store: PermissionStore): this;
+    forUser(user: AuthUser | null): Bouncer;
+}
+export declare const bouncerManager: BouncerManager;
+/**
+ * Middleware that attaches ctx.bouncer to every request.
+ * Should be placed AFTER authPlugin so ctx.auth is available.
+ *
+ * @example
+ * app.use(bouncerPlugin(bouncerManager));
+ */
+export declare function bouncerPlugin(manager: BouncerManager): Middleware;
+/**
+ * Route-level middleware to require a specific role.
+ *
+ * @example
+ * router.delete('/invoices/:id', handler).middleware(requireRole('supervisor'));
+ */
+export declare function requireRole(...roles: string[]): Middleware;
+/**
+ * Route-level middleware to require a specific permission.
+ *
+ * @example
+ * router.post('/billing/refund', handler).middleware(requirePermission('billing:refund'));
+ */
+export declare function requirePermission(permission: string): Middleware;
+//# sourceMappingURL=bouncer.d.ts.map