@rytass/bpm-core-nestjs-module 0.3.0 → 0.5.0

package/src/lib/bpm-auth/bpm-auth.module.ts

@@ -0,0 +1,69 @@
+import { DynamicModule, Module } from '@nestjs/common';
+import {
+  BPM_AUTH_CONTEXT_ACCESSOR,
+  BPM_AUTH_MODULE_OPTIONS,
+} from './bpm-auth-context';
+import {
+  BPMAuthModuleAsyncOptions,
+  BPMAuthModuleOptions,
+} from './bpm-auth.options';
+import { BPMAuthenticatedGuard } from './bpm-auth.guard';
+import { BPMAdminGuard, BPMDesignerGuard } from './bpm-auth.authorization';
+import { ConfigurableBPMAuthContextAccessor } from './configurable-bpm-auth-context.accessor';
+
+@Module({})
+export class BPMAuthModule {
+  static forRoot(options: BPMAuthModuleOptions = {}): DynamicModule {
+    return {
+      exports: [
+        BPM_AUTH_CONTEXT_ACCESSOR,
+        BPMAdminGuard,
+        BPMDesignerGuard,
+        BPMAuthenticatedGuard,
+      ],
+      global: true,
+      module: BPMAuthModule,
+      providers: [
+        {
+          provide: BPM_AUTH_MODULE_OPTIONS,
+          useValue: options,
+        },
+        {
+          provide: BPM_AUTH_CONTEXT_ACCESSOR,
+          useClass: ConfigurableBPMAuthContextAccessor,
+        },
+        BPMAdminGuard,
+        BPMDesignerGuard,
+        BPMAuthenticatedGuard,
+      ],
+    };
+  }
+
+  static forRootAsync(options: BPMAuthModuleAsyncOptions): DynamicModule {
+    return {
+      exports: [
+        BPM_AUTH_CONTEXT_ACCESSOR,
+        BPMAdminGuard,
+        BPMDesignerGuard,
+        BPMAuthenticatedGuard,
+      ],
+      global: true,
+      imports: options.imports,
+      module: BPMAuthModule,
+      providers: [
+        {
+          inject: [...(options.inject ?? [])],
+          provide: BPM_AUTH_MODULE_OPTIONS,
+          useFactory: options.useFactory,
+        },
+        {
+          provide: BPM_AUTH_CONTEXT_ACCESSOR,
+          useClass: ConfigurableBPMAuthContextAccessor,
+        },
+        BPMAdminGuard,
+        BPMDesignerGuard,
+        BPMAuthenticatedGuard,
+      ],
+    };
+  }
+}

package/src/lib/bpm-auth/bpm-auth.options.ts

@@ -0,0 +1,21 @@
+import { ExecutionContext, InjectionToken } from '@nestjs/common';
+import type { ModuleMetadata } from '@nestjs/common/interfaces';
+import { BPMAuthContext } from './bpm-auth-context';
+
+export type BPMAuthContextFactory = (
+  context?: ExecutionContext,
+) => BPMAuthContext | null | Promise<BPMAuthContext | null>;
+
+export interface BPMAuthModuleOptions {
+  readonly contextFactory?: BPMAuthContextFactory;
+}
+
+export interface BPMAuthModuleAsyncOptions extends Pick<
+  ModuleMetadata,
+  'imports'
+> {
+  readonly inject?: readonly InjectionToken[];
+  readonly useFactory: (
+    ...args: readonly unknown[]
+  ) => BPMAuthModuleOptions | Promise<BPMAuthModuleOptions>;
+}

package/src/lib/bpm-auth/configurable-bpm-auth-context.accessor.ts

@@ -0,0 +1,55 @@
+import {
+  ExecutionContext,
+  Inject,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import {
+  BPM_AUTH_MODULE_OPTIONS,
+  BPMAuthContext,
+  BPMAuthContextAccessor,
+} from './bpm-auth-context';
+import { extractBPMAuthContext } from './bpm-auth-context.extractor';
+import { BPMAuthModuleOptions } from './bpm-auth.options';
+
+@Injectable()
+export class ConfigurableBPMAuthContextAccessor implements BPMAuthContextAccessor {
+  constructor(
+    @Inject(BPM_AUTH_MODULE_OPTIONS)
+    private readonly options: BPMAuthModuleOptions,
+  ) {}
+
+  async assertAuthenticated(
+    context?: ExecutionContext,
+  ): Promise<BPMAuthContext> {
+    const authContext = await this.getCurrentContext(context);
+
+    if (!authContext?.memberId.trim()) {
+      throw new UnauthorizedException('BPM authentication is required');
+    }
+
+    return authContext;
+  }
+
+  async getCurrentContext(
+    context?: ExecutionContext,
+  ): Promise<BPMAuthContext | null> {
+    const extractedContext = extractBPMAuthContext(context);
+
+    if (extractedContext) {
+      return extractedContext;
+    }
+
+    if (this.options.contextFactory) {
+      return this.options.contextFactory(context);
+    }
+
+    return null;
+  }
+
+  async getCurrentMemberId(context?: ExecutionContext): Promise<string> {
+    const authContext = await this.assertAuthenticated(context);
+
+    return authContext.memberId;
+  }
+}

package/src/lib/common/filters/all-exceptions.filter.ts

@@ -0,0 +1,138 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common';
+import { Response } from 'express';
+
+interface HttpRequestLike {
+  readonly url?: string;
+}
+
+interface HttpResponseLike {
+  readonly json?: (body: ErrorResponseBody) => unknown;
+  readonly status?: (statusCode: number) => HttpResponseLike;
+}
+
+interface ErrorResponseBody {
+  readonly error: string;
+  readonly message: string;
+  readonly path: string;
+  readonly statusCode: number;
+  readonly timestamp: string;
+}
+
+/**
+ * Global Nest exception filter that normalizes both HTTP and GraphQL error
+ * responses into a consistent JSON body with `statusCode`, `error`,
+ * `message`, `path`, and `timestamp`.
+ *
+ * Wire it from your bootstrap:
+ *
+ * ```ts
+ * import { AllExceptionsFilter } from '@rytass/bpm-core-nestjs-module';
+ *
+ * app.useGlobalFilters(new AllExceptionsFilter());
+ * ```
+ *
+ * Hosts that already have a custom global filter can keep their own; this
+ * filter is provided as a convenience and is not required by BPM.
+ */
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  private readonly logger = new Logger(AllExceptionsFilter.name);
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const context = host.switchToHttp();
+    const response = context.getResponse<Response | undefined>();
+    const request = context.getRequest<HttpRequestLike | undefined>();
+
+    if (!this.isWritableHttpResponse(response)) {
+      throw exception;
+    }
+
+    const statusCode =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+    const message = this.resolveMessage(exception);
+    const body: ErrorResponseBody = {
+      error:
+        statusCode === HttpStatus.INTERNAL_SERVER_ERROR
+          ? 'Internal Server Error'
+          : 'Request Error',
+      message,
+      path: request?.url ?? host.getType<string>(),
+      statusCode,
+      timestamp: new Date().toISOString(),
+    };
+
+    if (statusCode === HttpStatus.INTERNAL_SERVER_ERROR) {
+      this.logger.error(
+        message,
+        exception instanceof Error ? exception.stack : undefined,
+      );
+    }
+
+    response.status(statusCode).json(body);
+  }
+
+  private isWritableHttpResponse(
+    response: Response | undefined,
+  ): response is Response {
+    const candidate = response as HttpResponseLike | undefined;
+
+    return (
+      typeof candidate?.status === 'function' &&
+      typeof candidate.json === 'function'
+    );
+  }
+
+  private resolveMessage(exception: unknown): string {
+    if (exception instanceof HttpException) {
+      const response = exception.getResponse();
+
+      if (typeof response === 'string') {
+        return response;
+      }
+
+      if (this.hasMessageArray(response)) {
+        return response.message.join(', ');
+      }
+
+      if (this.hasMessage(response)) {
+        return response.message;
+      }
+    }
+
+    if (exception instanceof Error) {
+      return exception.message;
+    }
+
+    return 'Unexpected error';
+  }
+
+  private hasMessage(value: unknown): value is { readonly message: string } {
+    return (
+      typeof value === 'object' &&
+      value !== null &&
+      'message' in value &&
+      typeof value.message === 'string'
+    );
+  }
+
+  private hasMessageArray(
+    value: unknown,
+  ): value is { readonly message: readonly string[] } {
+    return (
+      typeof value === 'object' &&
+      value !== null &&
+      'message' in value &&
+      Array.isArray(value.message) &&
+      value.message.every((item) => typeof item === 'string')
+    );
+  }
+}

package/src/lib/common/iso-duration.ts

@@ -0,0 +1,31 @@
+const ISO_DURATION_PATTERN =
+  /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/u;
+
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+const MINUTES_PER_HOUR = 60;
+const HOURS_PER_DAY = 24;
+
+export function parseIsoDurationToMilliseconds(value: string): number | null {
+  const match = ISO_DURATION_PATTERN.exec(value.trim());
+
+  if (!match) {
+    return null;
+  }
+
+  const days = readDurationUnit(match[1]);
+  const hours = readDurationUnit(match[2]);
+  const minutes = readDurationUnit(match[3]);
+  const seconds = readDurationUnit(match[4]);
+  const totalSeconds =
+    seconds +
+    minutes * SECONDS_PER_MINUTE +
+    hours * MINUTES_PER_HOUR * SECONDS_PER_MINUTE +
+    days * HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE;
+
+  return totalSeconds > 0 ? totalSeconds * MS_PER_SECOND : null;
+}
+
+function readDurationUnit(value: string | undefined): number {
+  return value ? Number(value) : 0;
+}

package/src/lib/condition/condition.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { ConditionService } from './condition.service';
+
+@Module({
+  providers: [ConditionService],
+  exports: [ConditionService],
+})
+export class ConditionModule {}

package/src/lib/condition/condition.service.spec.ts

@@ -0,0 +1,50 @@
+import { BadRequestException } from '@nestjs/common';
+import { ConditionService } from './condition.service';
+
+describe('ConditionService', () => {
+  it('rejects expressions longer than the configured guard limit', (): void => {
+    const service = new ConditionService();
+
+    expect(
+      service.lintExpression('form.amount > 1000', 'edge condition', {
+        maxExpressionLength: 10,
+      }),
+    ).toEqual(['edge condition must be 10 characters or fewer']);
+  });
+
+  it('rejects unsupported root identifiers when a registry is provided', (): void => {
+    const service = new ConditionService();
+
+    expect(
+      service.lintExpression('account.amount > 1000', 'edge condition', {
+        allowedRootIdentifiers: ['form', 'initiator'],
+      }),
+    ).toEqual(['edge condition references unsupported identifier account']);
+  });
+
+  it('does not treat string literals as identifiers', (): void => {
+    const service = new ConditionService();
+
+    expect(
+      service.lintExpression('form.status == "account"', 'edge condition', {
+        allowedRootIdentifiers: ['form'],
+      }),
+    ).toEqual([]);
+  });
+
+  it('applies guard lint before evaluating expressions', (): void => {
+    const service = new ConditionService();
+
+    expect(() =>
+      service.evaluateBoolean(
+        'form.amount > 1000',
+        { form: { amount: 100 } },
+        'edge condition',
+      ),
+    ).not.toThrow();
+
+    expect(() =>
+      service.evaluateBoolean('x'.repeat(2001), {}, 'edge condition'),
+    ).toThrow(BadRequestException);
+  });
+});

package/src/lib/condition/condition.service.ts

@@ -0,0 +1,141 @@
+import { BadRequestException, Injectable } from '@nestjs/common';
+import { evaluate, parse, type Failure, type ParseResult } from 'cel-js';
+
+interface ConditionExpression {
+  readonly expression: string | null | undefined;
+  readonly label: string;
+}
+
+interface ConditionLintOptions {
+  readonly allowedRootIdentifiers?: readonly string[];
+  readonly maxExpressionLength?: number;
+}
+
+export type CelEvaluationContext = Readonly<Record<string, unknown>>;
+
+const DEFAULT_MAX_EXPRESSION_LENGTH = 2000;
+const CEL_KEYWORDS = new Set(['false', 'has', 'in', 'null', 'true']);
+
+@Injectable()
+export class ConditionService {
+  lintExpressions(
+    expressions: readonly ConditionExpression[],
+    options: ConditionLintOptions = {},
+  ): readonly string[] {
+    return expressions.flatMap(({ expression, label }) =>
+      this.lintExpression(expression, label, options),
+    );
+  }
+
+  lintExpression(
+    expression: string | null | undefined,
+    label: string,
+    options: ConditionLintOptions = {},
+  ): readonly string[] {
+    if (typeof expression === 'undefined' || expression === null) {
+      return [];
+    }
+
+    const trimmedExpression = expression.trim();
+    const maxExpressionLength =
+      options.maxExpressionLength ?? DEFAULT_MAX_EXPRESSION_LENGTH;
+
+    if (!trimmedExpression) {
+      return [`${label} must not be blank`];
+    }
+
+    if (trimmedExpression.length > maxExpressionLength) {
+      return [`${label} must be ${maxExpressionLength} characters or fewer`];
+    }
+
+    const parseResult = parse(trimmedExpression);
+
+    if (isParseFailure(parseResult)) {
+      return parseResult.errors.map((error) => `${label}: ${error}`);
+    }
+
+    return lintRootIdentifiers(trimmedExpression, label, options);
+  }
+
+  evaluateBoolean(
+    expression: string | null | undefined,
+    context: CelEvaluationContext,
+    label: string,
+  ): boolean {
+    if (typeof expression !== 'string' || !expression.trim()) {
+      return true;
+    }
+
+    const value = this.evaluateValue(expression, context, label);
+
+    if (typeof value === 'boolean') {
+      return value;
+    }
+
+    throw new BadRequestException(`${label} must evaluate to a boolean`);
+  }
+
+  evaluateValue(
+    expression: string,
+    context: CelEvaluationContext,
+    label: string,
+  ): unknown {
+    const trimmedExpression = expression.trim();
+    const lengthErrors = this.lintExpression(trimmedExpression, label);
+
+    if (lengthErrors.length) {
+      throw new BadRequestException(lengthErrors.join('; '));
+    }
+
+    const parseResult = parse(trimmedExpression);
+
+    if (isParseFailure(parseResult)) {
+      throw new BadRequestException(
+        parseResult.errors.map((error) => `${label}: ${error}`).join('; '),
+      );
+    }
+
+    try {
+      return evaluate(parseResult.cst, { ...context });
+    } catch (error: unknown) {
+      throw new BadRequestException(
+        error instanceof Error ? `${label}: ${error.message}` : label,
+      );
+    }
+  }
+}
+
+function isParseFailure(parseResult: ParseResult): parseResult is Failure {
+  return !parseResult.isSuccess;
+}
+
+function lintRootIdentifiers(
+  expression: string,
+  label: string,
+  options: ConditionLintOptions,
+): readonly string[] {
+  const allowedRootIdentifiers = options.allowedRootIdentifiers;
+
+  if (!allowedRootIdentifiers?.length) {
+    return [];
+  }
+
+  const allowed = new Set([...allowedRootIdentifiers, ...CEL_KEYWORDS]);
+  const sanitizedExpression = stripStringLiterals(expression);
+  const identifiers = Array.from(
+    sanitizedExpression.matchAll(
+      /(^|[^A-Za-z0-9_.])([A-Za-z_][A-Za-z0-9_]*)/gu,
+    ),
+  ).map((match) => match[2]);
+  const unknownIdentifiers = [
+    ...new Set(identifiers.filter((identifier) => !allowed.has(identifier))),
+  ];
+
+  return unknownIdentifiers.map(
+    (identifier) => `${label} references unsupported identifier ${identifier}`,
+  );
+}
+
+function stripStringLiterals(expression: string): string {
+  return expression.replace(/"([^"\\]|\\.)*"|'([^'\\]|\\.)*'/gu, '""');
+}

package/src/lib/database/data-source.ts

@@ -0,0 +1,7 @@
+import 'reflect-metadata';
+import { DataSource } from 'typeorm';
+import { buildDataSourceOptionsFromVaultEnv } from './typeorm.config';
+
+export default buildDataSourceOptionsFromVaultEnv(process.env).then(
+  (options) => new DataSource(options),
+);

package/src/lib/database/migration-runner.ts

@@ -0,0 +1,26 @@
+import dataSource from './data-source';
+import { reconcileLegacyMigrationNames } from './reconcile-legacy-migrations';
+
+async function run(): Promise<void> {
+  const action = process.argv[2] ?? 'run';
+  const source = await dataSource;
+
+  await source.initialize();
+
+  try {
+    if (action === 'revert') {
+      await source.undoLastMigration();
+      return;
+    }
+
+    await reconcileLegacyMigrationNames(source);
+    await source.runMigrations();
+  } finally {
+    await source.destroy();
+  }
+}
+
+void run().catch((error: unknown) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/lib/database/reconcile-legacy-migrations.ts

@@ -0,0 +1,87 @@
+import { DataSource } from 'typeorm';
+
+/**
+ * Legacy (date-stamped) -> current (sequential) migration class names.
+ *
+ * Early BPMCore migrations were named with date-based timestamps
+ * (`...2026050202000`); they were later renamed to a zero-padded sequential
+ * scheme (`...0000000002000`). TypeORM keys idempotency on `migrations.name`,
+ * so any database whose `migrations` table still holds the old names would see
+ * the renamed classes as *pending* and try to re-run their `up()` — failing on
+ * already-existing objects (e.g. duplicate constraints).
+ *
+ * Each pair maps the exact same migration (same already-applied SQL); only the
+ * class name's numeric suffix changed. Reconciling the tracking-table rows is a
+ * metadata-only correction — it changes no schema.
+ */
+const LEGACY_MIGRATION_RENAMES: ReadonlyArray<readonly [string, string]> = [
+  [
+    'EnablePostgresExtensions2026043000000',
+    'EnablePostgresExtensions0000000000001',
+  ],
+  [
+    'IdentityOrganizationFoundation2026043001000',
+    'IdentityOrganizationFoundation0000000001000',
+  ],
+  ['FormBuilderFoundation2026050202000', 'FormBuilderFoundation0000000002000'],
+  [
+    'ApprovalTemplateFoundation2026050403000',
+    'ApprovalTemplateFoundation0000000003000',
+  ],
+  [
+    'WorkflowEngineFoundation2026050404000',
+    'WorkflowEngineFoundation0000000004000',
+  ],
+  [
+    'ApprovalTemplateCategories2026051208000',
+    'ApprovalTemplateCategories0000000008000',
+  ],
+  ['TaskCandidates2026051309000', 'TaskCandidates0000000009000'],
+];
+
+/**
+ * Rename any legacy-named migration tracking rows to their current class names
+ * so `runMigrations()` recognises them as already applied. Idempotent and safe
+ * on fresh databases (no `migrations` table yet → no-op) and on
+ * already-reconciled databases (target name present → skip).
+ *
+ * MUST be invoked *before* `DataSource.runMigrations()`, since TypeORM freezes
+ * its pending-migration set at the start of that call.
+ *
+ * @returns the number of tracking rows renamed.
+ */
+export async function reconcileLegacyMigrationNames(
+  dataSource: DataSource,
+): Promise<number> {
+  const tableProbe = (await dataSource.query(
+    `SELECT to_regclass('migrations') AS migrations_table`,
+  )) as readonly { readonly migrations_table: string | null }[];
+
+  if (!tableProbe[0]?.migrations_table) {
+    return 0;
+  }
+
+  return dataSource.transaction(async (manager): Promise<number> => {
+    return LEGACY_MIGRATION_RENAMES.reduce<Promise<number>>(
+      async (countPromise, [legacyName, currentName]): Promise<number> => {
+        const count = await countPromise;
+        const alreadyCurrent = (await manager.query(
+          'SELECT 1 FROM migrations WHERE name = $1 LIMIT 1',
+          [currentName],
+        )) as readonly unknown[];
+
+        if (alreadyCurrent.length > 0) {
+          return count;
+        }
+
+        const result = (await manager.query(
+          'UPDATE migrations SET name = $1 WHERE name = $2',
+          [currentName, legacyName],
+        )) as readonly [unknown, number];
+
+        return count + (Number(result[1]) || 0);
+      },
+      Promise.resolve(0),
+    );
+  });
+}