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

package/src/lib/attachment/attachment.service.ts

@@ -0,0 +1,477 @@
+import { createHash, createHmac, randomUUID } from 'crypto';
+import {
+  BadRequestException,
+  Inject,
+  Injectable,
+  NotFoundException,
+  Optional,
+} from '@nestjs/common';
+import { EntityManager, In, Repository } from 'typeorm';
+import { InjectRepository } from '@nestjs/typeorm';
+import { ApprovalInstanceEntity } from '../workflow-engine/approval-instance.entity';
+import { TaskCandidateEntity } from '../workflow-engine/task-candidate.entity';
+import { TaskDecisionEntity } from '../workflow-engine/task-decision.entity';
+import { TaskEntity } from '../workflow-engine/task.entity';
+import {
+  ATTACHMENT_STORAGE,
+  AttachmentStorage,
+} from './attachment-storage.token';
+import {
+  BPM_ATTACHMENT_OPTIONS,
+  BPMResolvedAttachmentOptions,
+  DEFAULT_BPM_ATTACHMENT_OPTIONS,
+} from './attachment-options';
+import { AttachmentEntity } from './attachment.entity';
+import { UploadAttachmentInput } from './dto/upload-attachment.input';
+
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+type AttachmentDisposition = 'attachment' | 'inline';
+
+interface AttachmentTokenPayload {
+  readonly disposition: AttachmentDisposition;
+  readonly expiresAt: number;
+  readonly id: string;
+}
+
+@Injectable()
+export class AttachmentService {
+  constructor(
+    @InjectRepository(AttachmentEntity)
+    private readonly attachmentRepository: Repository<AttachmentEntity>,
+    @InjectRepository(ApprovalInstanceEntity)
+    private readonly approvalInstanceRepository: Repository<ApprovalInstanceEntity>,
+    @InjectRepository(TaskEntity)
+    private readonly taskRepository: Repository<TaskEntity>,
+    @InjectRepository(TaskCandidateEntity)
+    private readonly taskCandidateRepository: Repository<TaskCandidateEntity>,
+    @InjectRepository(TaskDecisionEntity)
+    private readonly taskDecisionRepository: Repository<TaskDecisionEntity>,
+    @Inject(ATTACHMENT_STORAGE)
+    private readonly storage: AttachmentStorage,
+    @Optional()
+    @Inject(BPM_ATTACHMENT_OPTIONS)
+    private readonly attachmentOptions: BPMResolvedAttachmentOptions = DEFAULT_BPM_ATTACHMENT_OPTIONS,
+  ) {}
+
+  async uploadAttachment(
+    input: UploadAttachmentInput,
+  ): Promise<AttachmentEntity> {
+    const fileBuffer = Buffer.from(input.contentBase64, 'base64');
+    const uploaderMemberId = input.uploaderMemberId?.trim();
+
+    if (!uploaderMemberId) {
+      throw new BadRequestException('Attachment uploader member id is required');
+    }
+
+    if (fileBuffer.length !== input.sizeBytes) {
+      throw new BadRequestException('Attachment size does not match payload');
+    }
+
+    const checksumSha256 = hashBuffer(fileBuffer);
+
+    if (input.checksumSha256 && input.checksumSha256 !== checksumSha256) {
+      throw new BadRequestException('Attachment checksum mismatch');
+    }
+
+    const id = randomUUID();
+    const storageKey = buildStorageKey(id, input.filename);
+    const storedFile = await this.storage.write(fileBuffer, {
+      contentType: input.mimeType,
+      filename: storageKey,
+    });
+
+    return this.attachmentRepository.save(
+      this.attachmentRepository.create({
+        checksumSha256,
+        filename: input.filename,
+        formFieldPath: normalizeOptionalText(input.formFieldPath),
+        id,
+        instanceId: input.instanceId ?? null,
+        mimeType: input.mimeType,
+        sizeBytes: String(input.sizeBytes),
+        storageKey: storedFile.key,
+        storageProvider: this.attachmentOptions.storageProviderId,
+        taskId: input.taskId ?? null,
+        uploaderMemberId,
+      }),
+    );
+  }
+
+  async listAttachments({
+    formFieldPath = null,
+    instanceId,
+    requestedByMemberId = null,
+    taskId = null,
+  }: {
+    readonly formFieldPath?: string | null;
+    readonly instanceId: string;
+    readonly requestedByMemberId?: string | null;
+    readonly taskId?: string | null;
+  }): Promise<readonly AttachmentEntity[]> {
+    const attachments = await this.attachmentRepository.find({
+      order: { createdAt: 'ASC' },
+      where: {
+        instanceId,
+        ...(formFieldPath ? { formFieldPath } : {}),
+        ...(taskId ? { taskId } : {}),
+      },
+    });
+
+    if (!requestedByMemberId) {
+      return attachments;
+    }
+
+    const readableAttachments = await Promise.all(
+      attachments.map(async (attachment): Promise<AttachmentEntity | null> => {
+        try {
+          await this.assertAttachmentReadableByMember(
+            attachment,
+            requestedByMemberId,
+          );
+
+          return attachment;
+        } catch {
+          return null;
+        }
+      }),
+    );
+
+    return readableAttachments.filter(
+      (attachment): attachment is AttachmentEntity => attachment !== null,
+    );
+  }
+
+  async bindFormDataAttachmentsToInstance(
+    manager: EntityManager,
+    {
+      formData,
+      instanceId,
+    }: {
+      readonly formData: Readonly<Record<string, unknown>>;
+      readonly instanceId: string;
+    },
+  ): Promise<void> {
+    const attachmentRefs = readAttachmentRefsFromFormData(formData);
+    const ids = [...new Set(attachmentRefs.map((ref) => ref.id))];
+
+    if (ids.length === 0) {
+      return;
+    }
+
+    const attachmentRepository = manager.getRepository(AttachmentEntity);
+    const attachments = await attachmentRepository.find({
+      where: { id: In(ids) },
+    });
+    const refsById = new Map(attachmentRefs.map((ref) => [ref.id, ref]));
+    const nextAttachments = attachments
+      .filter(
+        (attachment) =>
+          attachment.instanceId === null ||
+          attachment.instanceId === instanceId,
+      )
+      .map((attachment) => ({
+        ...attachment,
+        formFieldPath:
+          attachment.formFieldPath ?? refsById.get(attachment.id)?.path ?? null,
+        instanceId,
+      }));
+
+    if (nextAttachments.length > 0) {
+      await attachmentRepository.save(nextAttachments);
+    }
+  }
+
+  async createSignedUrl({
+    disposition,
+    id,
+    requestedByMemberId,
+  }: {
+    readonly disposition: AttachmentDisposition;
+    readonly id: string;
+    readonly requestedByMemberId: string;
+  }): Promise<string> {
+    const attachment = await this.readAttachmentOrThrow(id);
+
+    await this.assertAttachmentReadableByMember(
+      attachment,
+      requestedByMemberId,
+    );
+
+    if (disposition === 'inline' && attachment.mimeType !== 'application/pdf') {
+      throw new BadRequestException('Only PDF attachments can be previewed');
+    }
+
+    const token = signAttachmentToken(
+      {
+        disposition,
+        expiresAt:
+          Math.floor(Date.now() / 1000) +
+          this.attachmentOptions.signedUrlTtlSeconds,
+        id,
+      },
+      this.attachmentOptions.signedUrlSecret,
+    );
+
+    return `${this.attachmentOptions.publicBaseUrl}${this.attachmentOptions.routePrefix}/${id}/download?token=${encodeURIComponent(
+      token,
+    )}&disposition=${disposition}`;
+  }
+
+  async readSignedAttachment({
+    disposition,
+    id,
+    token,
+  }: {
+    readonly disposition: AttachmentDisposition;
+    readonly id: string;
+    readonly token: string;
+  }): Promise<{
+    readonly attachment: AttachmentEntity;
+    readonly buffer: Buffer;
+  }> {
+    const payload = verifyAttachmentToken(
+      token,
+      this.attachmentOptions.signedUrlSecret,
+    );
+
+    if (
+      payload.id !== id ||
+      payload.disposition !== disposition ||
+      payload.expiresAt < Math.floor(Date.now() / 1000)
+    ) {
+      throw new NotFoundException(`Attachment ${id} was not found`);
+    }
+
+    const attachment = await this.readAttachmentOrThrow(id);
+    const buffer = await this.storage.read(attachment.storageKey, {
+      format: 'buffer',
+    });
+
+    return { attachment, buffer };
+  }
+
+  private async readAttachmentOrThrow(id: string): Promise<AttachmentEntity> {
+    const attachment = await this.attachmentRepository.findOne({
+      where: { id },
+    });
+
+    if (!attachment) {
+      throw new NotFoundException(`Attachment ${id} was not found`);
+    }
+
+    return attachment;
+  }
+
+  private async assertAttachmentReadableByMember(
+    attachment: AttachmentEntity,
+    requestedByMemberId: string,
+  ): Promise<void> {
+    if (attachment.uploaderMemberId === requestedByMemberId) {
+      return;
+    }
+
+    const instance = attachment.instanceId
+      ? await this.approvalInstanceRepository.findOne({
+          where: { id: attachment.instanceId },
+        })
+      : null;
+
+    if (instance?.initiatorMemberId === requestedByMemberId) {
+      return;
+    }
+
+    const task = attachment.taskId
+      ? await this.taskRepository.findOne({ where: { id: attachment.taskId } })
+      : null;
+
+    if (task && isTaskDirectlyReadableByMember(task, requestedByMemberId)) {
+      return;
+    }
+
+    const relatedTaskIds = attachment.taskId
+      ? [attachment.taskId]
+      : attachment.instanceId
+        ? (
+            await this.taskRepository.find({
+              where: { instanceId: attachment.instanceId },
+            })
+          ).map((candidateTask) => candidateTask.id)
+        : [];
+
+    if (
+      relatedTaskIds.length > 0 &&
+      (await this.isMemberRelatedToTaskCandidates(
+        relatedTaskIds,
+        requestedByMemberId,
+      ))
+    ) {
+      return;
+    }
+
+    if (
+      relatedTaskIds.length > 0 &&
+      (await this.isMemberRelatedToTaskDecisions(
+        relatedTaskIds,
+        requestedByMemberId,
+      ))
+    ) {
+      return;
+    }
+
+    if (
+      relatedTaskIds.length > 0 &&
+      (
+        await this.taskRepository.find({
+          where: { id: In(relatedTaskIds) },
+        })
+      ).some((candidateTask) =>
+        isTaskDirectlyReadableByMember(candidateTask, requestedByMemberId),
+      )
+    ) {
+      return;
+    }
+
+    throw new NotFoundException(`Attachment ${attachment.id} was not found`);
+  }
+
+  private async isMemberRelatedToTaskCandidates(
+    taskIds: readonly string[],
+    memberId: string,
+  ): Promise<boolean> {
+    const candidates = await this.taskCandidateRepository.find({
+      where: { taskId: In([...taskIds]) },
+    });
+
+    return candidates.some(
+      (candidate) =>
+        candidate.memberId === memberId || candidate.originalMemberId === memberId,
+    );
+  }
+
+  private async isMemberRelatedToTaskDecisions(
+    taskIds: readonly string[],
+    memberId: string,
+  ): Promise<boolean> {
+    const decisions = await this.taskDecisionRepository.find({
+      where: { taskId: In([...taskIds]) },
+    });
+
+    return decisions.some((decision) => decision.decidedByMemberId === memberId);
+  }
+}
+
+function isTaskDirectlyReadableByMember(
+  task: TaskEntity,
+  memberId: string,
+): boolean {
+  return (
+    task.assigneeMemberId === memberId ||
+    task.originalAssigneeMemberId === memberId
+  );
+}
+
+function hashBuffer(buffer: Buffer): string {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function buildStorageKey(id: string, filename: string): string {
+  return `${id}/${sanitizeFilename(filename)}`;
+}
+
+function sanitizeFilename(filename: string): string {
+  const sanitized = filename.replace(/[^a-zA-Z0-9._-]/g, '_');
+
+  return sanitized || 'attachment.bin';
+}
+
+function normalizeOptionalText(
+  value: string | null | undefined,
+): string | null {
+  const trimmedValue = value?.trim();
+
+  return trimmedValue ? trimmedValue : null;
+}
+
+function readAttachmentRefsFromFormData(
+  formData: Readonly<Record<string, unknown>>,
+): readonly { readonly id: string; readonly path: string }[] {
+  return Object.entries(formData).flatMap(([fieldKey, value]) =>
+    readAttachmentRefsFromValue(value, `form.${fieldKey}`),
+  );
+}
+
+function readAttachmentRefsFromValue(
+  value: unknown,
+  path: string,
+): readonly { readonly id: string; readonly path: string }[] {
+  if (typeof value === 'string') {
+    return UUID_PATTERN.test(value) ? [{ id: value, path }] : [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.flatMap((entry) => readAttachmentRefsFromValue(entry, path));
+  }
+
+  if (isRecord(value)) {
+    return Object.entries(value).flatMap(([key, entry]) =>
+      readAttachmentRefsFromValue(entry, `${path}.${key}`),
+    );
+  }
+
+  return [];
+}
+
+function signAttachmentToken(
+  payload: AttachmentTokenPayload,
+  signedUrlSecret: string,
+): string {
+  const body = Buffer.from(JSON.stringify(payload), 'utf8').toString(
+    'base64url',
+  );
+  const signature = createHmac('sha256', signedUrlSecret)
+    .update(body)
+    .digest('base64url');
+
+  return `${body}.${signature}`;
+}
+
+function verifyAttachmentToken(
+  token: string,
+  signedUrlSecret: string,
+): AttachmentTokenPayload {
+  const [body, signature] = token.split('.');
+  const expectedSignature = createHmac('sha256', signedUrlSecret)
+    .update(body ?? '')
+    .digest('base64url');
+
+  if (!body || !signature || signature !== expectedSignature) {
+    throw new NotFoundException('Attachment token is invalid');
+  }
+
+  const payload = JSON.parse(
+    Buffer.from(body, 'base64url').toString('utf8'),
+  ) as unknown;
+
+  if (!isAttachmentTokenPayload(payload)) {
+    throw new NotFoundException('Attachment token is invalid');
+  }
+
+  return payload;
+}
+
+function isAttachmentTokenPayload(
+  value: unknown,
+): value is AttachmentTokenPayload {
+  return (
+    isRecord(value) &&
+    typeof value.id === 'string' &&
+    typeof value.expiresAt === 'number' &&
+    (value.disposition === 'attachment' || value.disposition === 'inline')
+  );
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === 'object' && value !== null;
+}

package/src/lib/attachment/dto/upload-attachment.input.ts

@@ -0,0 +1,60 @@
+import { Field, ID, InputType, Int } from '@nestjs/graphql';
+import {
+  IsBase64,
+  IsInt,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Max,
+  Min,
+} from 'class-validator';
+
+@InputType()
+export class UploadAttachmentInput {
+  @Field(() => ID, { nullable: true })
+  @IsOptional()
+  @IsUUID()
+  instanceId?: string | null;
+
+  @Field(() => ID, { nullable: true })
+  @IsOptional()
+  @IsUUID()
+  taskId?: string | null;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  formFieldPath?: string | null;
+
+  @Field(() => String, {
+    deprecationReason:
+      'Ignored. The current authenticated BPM member is always used.',
+    nullable: true,
+  })
+  @IsOptional()
+  @IsString()
+  uploaderMemberId?: string | null;
+
+  @Field()
+  @IsString()
+  filename!: string;
+
+  @Field()
+  @IsString()
+  mimeType!: string;
+
+  @Field(() => Int)
+  @IsInt()
+  @Max(10 * 1024 * 1024)
+  @Min(1)
+  sizeBytes!: number;
+
+  @Field()
+  @IsBase64()
+  contentBase64!: string;
+
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  checksumSha256?: string | null;
+}

package/src/lib/bpm/bpm-root.module.spec.ts

@@ -0,0 +1,138 @@
+import { Module, Provider } from '@nestjs/common';
+import { BPMRootModule } from './bpm-root.module';
+import {
+  BPM_MEMBER_RESOLVER,
+  BPMMemberResolver,
+} from '../identity/member-resolver.interface';
+import { ATTACHMENT_STORAGE, AttachmentStorage } from '../attachment';
+import {
+  BPM_WORKFLOW_SERVICE_TASK_DISPATCHER,
+  BPMWorkflowWebhookDispatchInput,
+  BPMWorkflowWebhookDispatchResult,
+  BPMWorkflowServiceTaskDispatcher,
+} from '../workflow-engine';
+
+const HOST_INTEGRATION_BUS = Symbol('HOST_INTEGRATION_BUS');
+
+interface HostIntegrationBus {
+  enqueueWebhook(
+    input: BPMWorkflowWebhookDispatchInput,
+  ): Promise<BPMWorkflowWebhookDispatchResult>;
+}
+
+@Module({
+  providers: [
+    {
+      provide: 'HOST_MEMBER_RESOLVER',
+      useValue: {},
+    },
+    {
+      provide: 'HOST_ATTACHMENT_STORAGE',
+      useValue: {},
+    },
+  ],
+  exports: ['HOST_MEMBER_RESOLVER', 'HOST_ATTACHMENT_STORAGE'],
+})
+class HostProviderModule {}
+
+@Module({
+  providers: [
+    {
+      provide: HOST_INTEGRATION_BUS,
+      useValue: {
+        enqueueWebhook: jest.fn(),
+      } satisfies HostIntegrationBus,
+    },
+  ],
+  exports: [HOST_INTEGRATION_BUS],
+})
+class HostWorkflowIntegrationModule {}
+
+describe('BPMRootModule', () => {
+  it('passes host imports to static child modules that resolve host providers', (): void => {
+    const memberResolverProvider: Provider<BPMMemberResolver> = {
+      provide: BPM_MEMBER_RESOLVER,
+      useExisting: 'HOST_MEMBER_RESOLVER',
+    };
+    const attachmentStorageProvider: Provider<AttachmentStorage> = {
+      provide: ATTACHMENT_STORAGE,
+      useExisting: 'HOST_ATTACHMENT_STORAGE',
+    };
+    const workflowServiceTaskDispatcherProvider: Provider<BPMWorkflowServiceTaskDispatcher> =
+      {
+        provide: BPM_WORKFLOW_SERVICE_TASK_DISPATCHER,
+        useValue: {
+          dispatchWebhook: jest.fn(),
+        },
+      };
+
+    const module = BPMRootModule.forRoot({
+      attachmentStorageProvider,
+      imports: [HostProviderModule],
+      memberResolverProvider,
+      workflowServiceTaskDispatcherProvider,
+    });
+    const importedModules = module.imports ?? [];
+
+    expect(importedModules).toContain(HostProviderModule);
+    expect(
+      importedModules.some(
+        (importedModule) =>
+          typeof importedModule === 'object' &&
+          importedModule !== null &&
+          'imports' in importedModule &&
+          importedModule.imports?.includes(HostProviderModule),
+      ),
+    ).toBe(true);
+    expect(
+      importedModules.some(
+        (importedModule) =>
+          typeof importedModule === 'object' &&
+          importedModule !== null &&
+          'providers' in importedModule &&
+          importedModule.providers?.includes(
+            workflowServiceTaskDispatcherProvider,
+          ),
+      ),
+    ).toBe(true);
+  });
+
+  it('passes a host workflow service task dispatcher factory to workflow engine module', (): void => {
+    const workflowServiceTaskDispatcherProvider: Provider<BPMWorkflowServiceTaskDispatcher> =
+      {
+        inject: [HOST_INTEGRATION_BUS],
+        provide: BPM_WORKFLOW_SERVICE_TASK_DISPATCHER,
+        useFactory: (
+          integrationBus: HostIntegrationBus,
+        ): BPMWorkflowServiceTaskDispatcher => ({
+          dispatchWebhook: (
+            input: BPMWorkflowWebhookDispatchInput,
+          ): Promise<BPMWorkflowWebhookDispatchResult> =>
+            integrationBus.enqueueWebhook(input),
+        }),
+      };
+
+    const module = BPMRootModule.forRoot({
+      imports: [HostWorkflowIntegrationModule],
+      memberResolverProvider: {
+        provide: BPM_MEMBER_RESOLVER,
+        useExisting: 'HOST_MEMBER_RESOLVER',
+      },
+      workflowServiceTaskDispatcherProvider,
+    });
+    const importedModules = module.imports ?? [];
+
+    expect(importedModules).toContain(HostWorkflowIntegrationModule);
+    expect(
+      importedModules.some(
+        (importedModule) =>
+          typeof importedModule === 'object' &&
+          importedModule !== null &&
+          'providers' in importedModule &&
+          importedModule.providers?.includes(
+            workflowServiceTaskDispatcherProvider,
+          ),
+      ),
+    ).toBe(true);
+  });
+});