@quanticjs/core 1.1.1

package/src/entities/BaseEntity.ts

@@ -0,0 +1,16 @@
+import {
+  PrimaryGeneratedColumn,
+  CreateDateColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+
+export abstract class BaseEntity {
+  @PrimaryGeneratedColumn('uuid')
+  id!: string;
+
+  @CreateDateColumn({ type: 'timestamptz' })
+  createdAt!: Date;
+
+  @UpdateDateColumn({ type: 'timestamptz' })
+  updatedAt!: Date;
+}

package/src/entities/TenantBaseEntity.ts

@@ -0,0 +1,7 @@
+import { Column } from 'typeorm';
+import { BaseEntity } from './BaseEntity';
+
+export abstract class TenantBaseEntity extends BaseEntity {
+  @Column({ type: 'uuid' })
+  organizationId!: string;
+}

package/src/events/DomainEvent.ts

@@ -0,0 +1,27 @@
+import { v4 as uuidv4 } from 'uuid';
+
+export interface DomainEventPayload {
+  [key: string]: unknown;
+}
+
+export class DomainEvent {
+  public readonly eventId: string;
+  public readonly occurredAt: Date;
+
+  constructor(
+    public readonly eventType: string,
+    public readonly aggregateId: string,
+    public readonly payload: DomainEventPayload,
+    public readonly organizationId?: string,
+  ) {
+    this.eventId = uuidv4();
+    this.occurredAt = new Date();
+  }
+
+  /** The Redis Stream key this event should be published to */
+  get streamKey(): string {
+    // e.g. 'build.completed' → 'arex:events:builds'
+    const category = this.eventType.split('.')[0];
+    return `arex:events:${category}s`;
+  }
+}

package/src/events/OutboxEvent.entity.ts

@@ -0,0 +1,56 @@
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  Index,
+  PrimaryGeneratedColumn,
+} from 'typeorm';
+
+export enum OutboxEventStatus {
+  Pending = 'Pending',
+  Published = 'Published',
+  Failed = 'Failed',
+}
+
+@Entity('outbox_events')
+@Index('idx_outbox_pending', ['status', 'createdAt'], {
+  where: `"status" = 'Pending'`,
+})
+export class OutboxEvent {
+  @PrimaryGeneratedColumn('uuid')
+  id!: string;
+
+  @Column({ type: 'varchar' })
+  eventType!: string;
+
+  @Column({ type: 'varchar' })
+  aggregateId!: string;
+
+  @Column({ type: 'varchar' })
+  streamKey!: string;
+
+  @Column({ type: 'jsonb' })
+  payload!: Record<string, unknown>;
+
+  @Column({ type: 'uuid', nullable: true })
+  organizationId!: string | null;
+
+  @Column({
+    type: 'enum',
+    enum: OutboxEventStatus,
+    default: OutboxEventStatus.Pending,
+  })
+  status!: OutboxEventStatus;
+
+  @Column({ type: 'int', default: 0 })
+  publishAttempts!: number;
+
+  @Column({ type: 'varchar', nullable: true })
+  lastError!: string | null;
+
+  @CreateDateColumn({ type: 'timestamptz' })
+  createdAt!: Date;
+
+  @Column({ type: 'timestamptz', nullable: true })
+  publishedAt!: Date | null;
+}

package/src/events/OutboxPublisherService.ts

@@ -0,0 +1,94 @@
+import { Injectable, Logger, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { DataSource } from 'typeorm';
+import { OutboxEvent, OutboxEventStatus } from './OutboxEvent.entity';
+import { RedisStreamPublisher } from './RedisStreamPublisher';
+
+const POLL_INTERVAL_MS = 100;
+const BATCH_SIZE = 50;
+const MAX_PUBLISH_ATTEMPTS = 5;
+const DLQ_STREAM = 'arex:events:dlq';
+
+@Injectable()
+export class OutboxPublisherService implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(OutboxPublisherService.name);
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private processing = false;
+
+  constructor(
+    private readonly dataSource: DataSource,
+    private readonly redisPublisher: RedisStreamPublisher,
+  ) {}
+
+  onModuleInit() {
+    this.timer = setInterval(() => this.pollAndPublish(), POLL_INTERVAL_MS);
+    this.logger.log(`Outbox publisher started (${POLL_INTERVAL_MS}ms poll interval)`);
+  }
+
+  onModuleDestroy() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.logger.log('Outbox publisher stopped');
+  }
+
+  private async pollAndPublish(): Promise<void> {
+    if (this.processing) return;
+    this.processing = true;
+
+    try {
+      const repo = this.dataSource.getRepository(OutboxEvent);
+
+      const events = await repo.find({
+        where: { status: OutboxEventStatus.Pending },
+        order: { createdAt: 'ASC' },
+        take: BATCH_SIZE,
+      });
+
+      for (const event of events) {
+        try {
+          await this.redisPublisher.publishToStream(event.streamKey, {
+            eventId: event.id,
+            eventType: event.eventType,
+            aggregateId: event.aggregateId,
+            organizationId: event.organizationId || '',
+            payload: JSON.stringify(event.payload),
+            occurredAt: event.createdAt.toISOString(),
+          });
+
+          event.status = OutboxEventStatus.Published;
+          event.publishedAt = new Date();
+          await repo.save(event);
+        } catch (error) {
+          event.publishAttempts += 1;
+          event.lastError = (error as Error).message;
+
+          if (event.publishAttempts >= MAX_PUBLISH_ATTEMPTS) {
+            event.status = OutboxEventStatus.Failed;
+            this.logger.error(
+              `Event ${event.id} exceeded max attempts, routing to DLQ`,
+            );
+
+            try {
+              await this.redisPublisher.publishToStream(DLQ_STREAM, {
+                eventId: event.id,
+                eventType: event.eventType,
+                aggregateId: event.aggregateId,
+                error: event.lastError || 'unknown',
+                payload: JSON.stringify(event.payload),
+              });
+            } catch {
+              this.logger.error(`Failed to route event ${event.id} to DLQ`);
+            }
+          }
+
+          await repo.save(event);
+        }
+      }
+    } catch (error) {
+      this.logger.error('Outbox poll cycle failed', (error as Error).stack);
+    } finally {
+      this.processing = false;
+    }
+  }
+}

package/src/events/RedisStreamConsumer.ts

@@ -0,0 +1,172 @@
+import { Logger, Inject, Optional, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { REDIS_CLIENT } from '../cqrs/constants';
+import type { Redis } from 'ioredis';
+
+/**
+ * Abstract base class for Redis Stream consumer groups.
+ *
+ * Subclasses declare `streamKey`, `consumerGroup`, `consumerName`
+ * and implement `handleMessage(fields)`.
+ *
+ * Lifecycle:
+ *  - OnModuleInit: creates consumer group (idempotent), starts read loop
+ *  - OnModuleDestroy: stops the read loop gracefully, disconnects dedicated client
+ *
+ * Connection strategy:
+ *  - Shared REDIS_CLIENT: used for non-blocking ops (XGROUP CREATE, XACK)
+ *  - Dedicated cloned connection: used ONLY for blocking XREADGROUP BLOCK calls
+ *  - This prevents blocking consumers from starving non-blocking callers
+ *    (cache, distributed locks, publishers) that share the main REDIS_CLIENT.
+ *
+ * Features:
+ *  - Auto-creates consumer group via XGROUP CREATE ... MKSTREAM
+ *  - Recovers pending (unacked) messages on startup before reading new ones
+ *  - XREADGROUP BLOCK for efficient new-message polling (on dedicated connection)
+ *  - XACK after successful processing (on shared connection)
+ *  - Graceful shutdown (finishes in-flight message, disconnects dedicated client)
+ */
+export abstract class RedisStreamConsumer implements OnModuleInit, OnModuleDestroy {
+  protected readonly logger = new Logger(this.constructor.name);
+
+  abstract readonly streamKey: string;
+  abstract readonly consumerGroup: string;
+  abstract readonly consumerName: string;
+
+  /** Override to filter by eventType. Return true to process. Default: all messages. */
+  protected shouldHandle(_fields: Record<string, string>): boolean {
+    return true;
+  }
+
+  abstract handleMessage(fields: Record<string, string>): Promise<void>;
+
+  private running = false;
+
+  /** Dedicated connection for blocking XREADGROUP — cloned from shared client on init */
+  private blockingClient?: Redis;
+
+  constructor(
+    @Optional() @Inject(REDIS_CLIENT) protected readonly redis?: Redis,
+  ) {}
+
+  async onModuleInit(): Promise<void> {
+    if (!this.redis) {
+      this.logger.warn('Redis client not available — consumer disabled');
+      return;
+    }
+
+    // Clone a dedicated connection for blocking reads.
+    // This prevents XREADGROUP BLOCK from starving cache/lock/publish ops on the shared client.
+    this.blockingClient = this.redis.duplicate();
+    this.blockingClient.on('error', (err) =>
+      this.logger.error(`Blocking client error on ${this.streamKey}: ${err.message}`),
+    );
+
+    // Create consumer group (idempotent) — uses shared client (non-blocking)
+    try {
+      await this.redis.xgroup(
+        'CREATE',
+        this.streamKey,
+        this.consumerGroup,
+        '0',
+        'MKSTREAM',
+      );
+      this.logger.log(`Created consumer group "${this.consumerGroup}" on "${this.streamKey}"`);
+    } catch (err: any) {
+      if (!err.message?.includes('BUSYGROUP')) {
+        throw err;
+      }
+      // Group already exists — fine
+    }
+
+    this.running = true;
+
+    // Process pending messages first, then new ones
+    // Run in background so NestJS startup isn't blocked
+    void this.consumeLoop();
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    this.running = false;
+
+    // Disconnect the dedicated blocking client
+    if (this.blockingClient) {
+      this.blockingClient.disconnect();
+      this.blockingClient = undefined;
+    }
+  }
+
+  private async consumeLoop(): Promise<void> {
+    // Phase 1: recover pending (unacked) messages
+    await this.readMessages('0');
+
+    // Phase 2: read new messages
+    while (this.running) {
+      await this.readMessages('>');
+    }
+  }
+
+  private async readMessages(id: '0' | '>'): Promise<void> {
+    if (!this.redis || !this.blockingClient || !this.running) return;
+
+    try {
+      const blockMs = id === '>' ? 5000 : undefined;
+      const args: (string | number)[] = [
+        'GROUP',
+        this.consumerGroup,
+        this.consumerName,
+        'COUNT',
+        '10',
+      ];
+      if (blockMs !== undefined) {
+        args.push('BLOCK', blockMs);
+      }
+      args.push('STREAMS', this.streamKey, id);
+
+      // Use dedicated blocking client for XREADGROUP — never the shared REDIS_CLIENT
+      const results = await (this.blockingClient as any).xreadgroup(...args) as
+        Array<[string, Array<[string, string[]]>]> | null;
+
+      if (!results || results.length === 0) {
+        if (id === '0') return; // No pending — switch to new messages
+        return;
+      }
+
+      const [, entries] = results[0];
+
+      if (entries.length === 0 && id === '0') {
+        return; // All pending recovered
+      }
+
+      for (const [messageId, fieldArray] of entries) {
+        // Parse flat field array into Record
+        const fields: Record<string, string> = {};
+        for (let i = 0; i < fieldArray.length; i += 2) {
+          fields[fieldArray[i]] = fieldArray[i + 1];
+        }
+
+        if (!this.shouldHandle(fields)) {
+          // Ack and skip — uses shared client (non-blocking)
+          await this.redis.xack(this.streamKey, this.consumerGroup, messageId);
+          continue;
+        }
+
+        try {
+          await this.handleMessage(fields);
+          // XACK on shared client — non-blocking
+          await this.redis.xack(this.streamKey, this.consumerGroup, messageId);
+        } catch (err: any) {
+          this.logger.error(
+            `Failed to process message ${messageId} on ${this.streamKey}: ${err.message}`,
+            err.stack,
+          );
+          // Don't ack — message stays pending for retry on next startup
+        }
+      }
+    } catch (err: any) {
+      if (!this.running) return; // Shutdown in progress
+      this.logger.error(`Consumer read error on ${this.streamKey}: ${err.message}`, err.stack);
+      // Back off before retrying
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+  }
+}

package/src/events/RedisStreamPublisher.ts

@@ -0,0 +1,54 @@
+import { Injectable, Logger, Inject, Optional } from '@nestjs/common';
+import { REDIS_CLIENT } from '../cqrs/constants';
+import type { Redis } from 'ioredis';
+import { DomainEvent } from './DomainEvent';
+
+const MAX_STREAM_LENGTH = 10000;
+
+@Injectable()
+export class RedisStreamPublisher {
+  private readonly logger = new Logger(RedisStreamPublisher.name);
+
+  constructor(
+    @Optional() @Inject(REDIS_CLIENT) private readonly redis?: Redis,
+  ) {}
+
+  async publish(event: DomainEvent): Promise<void> {
+    if (!this.redis) {
+      this.logger.warn('Redis client not available, skipping event publish');
+      return;
+    }
+
+    await this.publishToStream(event.streamKey, {
+      eventId: event.eventId,
+      eventType: event.eventType,
+      aggregateId: event.aggregateId,
+      organizationId: event.organizationId || '',
+      payload: JSON.stringify(event.payload),
+      occurredAt: event.occurredAt.toISOString(),
+    });
+  }
+
+  async publishToStream(
+    streamKey: string,
+    fields: Record<string, string>,
+  ): Promise<string | null> {
+    if (!this.redis) return null;
+
+    try {
+      const messageId = await this.redis.xadd(
+        streamKey,
+        'MAXLEN',
+        '~',
+        String(MAX_STREAM_LENGTH),
+        '*',
+        ...Object.entries(fields).flat(),
+      );
+      this.logger.debug(`Published to ${streamKey}: ${messageId}`);
+      return messageId;
+    } catch (error) {
+      this.logger.error(`Failed to publish to ${streamKey}`, (error as Error).stack);
+      throw error;
+    }
+  }
+}

package/src/filters/GlobalExceptionFilter.ts

@@ -0,0 +1,125 @@
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+  Logger,
+} from '@nestjs/common';
+import { ThrottlerException } from '@nestjs/throttler';
+import { Request, Response } from 'express';
+import { correlationStore } from '../middleware/CorrelationStore';
+
+interface ProblemDetails {
+  type: string;
+  title: string;
+  status: number;
+  detail?: string;
+  instance?: string;
+  correlationId?: string;
+  retryAfter?: number;
+  errors?: Array<{ field?: string; message: string }>;
+  stack?: string;
+}
+
+/**
+ * Global exception filter for framework-level exceptions (guards, pipes, throttler).
+ * Result<T> errors are handled by ResultInterceptor — they never reach this filter.
+ */
+@Catch()
+export class GlobalExceptionFilter implements ExceptionFilter {
+  private readonly logger = new Logger(GlobalExceptionFilter.name);
+  private readonly isProduction = process.env.NODE_ENV === 'production';
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const request = ctx.getRequest<Request>();
+    const response = ctx.getResponse<Response>();
+    const correlationId = correlationStore.getStore()?.correlationId;
+
+    if (response.headersSent) return;
+
+    if (correlationId) {
+      response.setHeader('X-Correlation-ID', correlationId);
+    }
+
+    const problem = this.toProblemDetails(exception, correlationId, request.originalUrl);
+
+    if (problem.retryAfter) {
+      response.setHeader('Retry-After', String(problem.retryAfter));
+    }
+
+    this.logger.error({
+      msg: `${problem.status} ${problem.title}`,
+      correlationId,
+      status: problem.status,
+      detail: problem.detail,
+    });
+
+    response
+      .status(problem.status)
+      .setHeader('Content-Type', 'application/problem+json')
+      .json(problem);
+  }
+
+  private toProblemDetails(
+    exception: unknown,
+    correlationId?: string,
+    instance?: string,
+  ): ProblemDetails {
+    // ThrottlerException → 429
+    if (exception instanceof ThrottlerException) {
+      return {
+        type: 'https://arex.dev/errors/RATE_LIMITED',
+        title: 'Too Many Requests',
+        status: 429,
+        detail: 'Rate limit exceeded. Please retry later.',
+        instance,
+        correlationId,
+        retryAfter: 60,
+      };
+    }
+
+    // NestJS HttpException (guards, pipes, etc.)
+    if (exception instanceof HttpException) {
+      const status = exception.getStatus();
+      const exceptionResponse = exception.getResponse();
+      const detail =
+        typeof exceptionResponse === 'string'
+          ? exceptionResponse
+          : (exceptionResponse as Record<string, unknown>).message;
+
+      if (status === 400 && Array.isArray(detail)) {
+        return {
+          type: 'https://arex.dev/errors/VALIDATION_ERROR',
+          title: 'Validation Error',
+          status: 400,
+          detail: 'One or more validation errors occurred.',
+          instance,
+          correlationId,
+          errors: (detail as string[]).map((msg) => ({ message: msg })),
+        };
+      }
+
+      return {
+        type: `https://arex.dev/errors/HTTP_${status}`,
+        title: exception.name,
+        status,
+        detail: typeof detail === 'string' ? detail : JSON.stringify(detail),
+        instance,
+        correlationId,
+      };
+    }
+
+    // Unhandled errors (middleware crashes, etc.)
+    const error = exception instanceof Error ? exception : new Error(String(exception));
+    return {
+      type: 'https://arex.dev/errors/INTERNAL_ERROR',
+      title: 'Internal Server Error',
+      status: 500,
+      detail: this.isProduction ? 'An unexpected error occurred.' : error.message,
+      instance,
+      correlationId,
+      ...(this.isProduction ? {} : { stack: error.stack }),
+    };
+  }
+}

package/src/guards/JwtAuthGuard.ts

@@ -0,0 +1,29 @@
+import { ExecutionContext, Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { AuthGuard } from '@nestjs/passport';
+
+const IS_PUBLIC_KEY = 'isPublic';
+
+export const Public = () => (target: object, _key?: string | symbol, descriptor?: PropertyDescriptor) => {
+  if (descriptor) {
+    Reflect.defineMetadata(IS_PUBLIC_KEY, true, descriptor.value!);
+  } else {
+    Reflect.defineMetadata(IS_PUBLIC_KEY, true, target);
+  }
+};
+
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {
+  constructor(private readonly reflector: Reflector) {
+    super();
+  }
+
+  canActivate(context: ExecutionContext) {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (isPublic) return true;
+    return super.canActivate(context);
+  }
+}

package/src/guards/JwtStrategy.ts

@@ -0,0 +1,41 @@
+import { Injectable } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import { Strategy, ExtractJwt } from 'passport-jwt';
+import { passportJwtSecret } from 'jwks-rsa';
+
+export interface JwtPayload {
+  sub: string;
+  email: string;
+  realm_access?: { roles: string[] };
+  preferred_username?: string;
+}
+
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor() {
+    const internalUrl = process.env.KEYCLOAK_INTERNAL_URL || process.env.KEYCLOAK_URL || 'http://localhost:8080';
+    const publicUrl = process.env.KEYCLOAK_URL || 'http://localhost:8080';
+    const realm = process.env.KEYCLOAK_REALM || 'arex';
+
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      secretOrKeyProvider: passportJwtSecret({
+        jwksUri: `${internalUrl}/realms/${realm}/protocol/openid-connect/certs`,
+        cache: true,
+        cacheMaxAge: 600_000,
+        rateLimit: true,
+      }),
+      issuer: `${publicUrl}/realms/${realm}`,
+      algorithms: ['RS256'],
+    });
+  }
+
+  validate(payload: JwtPayload) {
+    return {
+      keycloakId: payload.sub,
+      email: payload.email,
+      roles: payload.realm_access?.roles || [],
+      username: payload.preferred_username,
+    };
+  }
+}

package/src/guards/RolesGuard.ts

@@ -0,0 +1,39 @@
+import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+
+const ROLES_KEY = 'roles';
+
+export const Roles = (...roles: string[]): ClassDecorator & MethodDecorator =>
+  (target: object, _key?: string | symbol, descriptor?: PropertyDescriptor) => {
+    if (descriptor) {
+      Reflect.defineMetadata(ROLES_KEY, roles, descriptor.value!);
+    } else {
+      Reflect.defineMetadata(ROLES_KEY, roles, target);
+    }
+  };
+
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this.reflector.getAllAndOverride<string[]>(ROLES_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (!requiredRoles || requiredRoles.length === 0) return true;
+
+    const request = context.switchToHttp().getRequest();
+    const userRoles: string[] = request.user?.roles || [];
+
+    const hasRole = requiredRoles.some((role) => userRoles.includes(role));
+    if (!hasRole) {
+      throw new ForbiddenException({
+        error: { code: 'FORBIDDEN', message: 'Insufficient permissions' },
+      });
+    }
+
+    return true;
+  }
+}