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

package/src/lib/organization/position.entity.ts

@@ -0,0 +1,39 @@
+import { Field, ID, Int, ObjectType } from '@nestjs/graphql';
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  PrimaryGeneratedColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+
+@Entity('positions')
+@ObjectType('Position')
+export class PositionEntity {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(() => ID)
+  id!: string;
+
+  @Column('text', { unique: true })
+  @Field()
+  code!: string;
+
+  @Column('text')
+  @Field()
+  name!: string;
+
+  @Column('int')
+  @Field(() => Int)
+  level!: number;
+
+  @Column('jsonb', { default: {} })
+  metadata!: Readonly<Record<string, unknown>>;
+
+  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
+  @Field()
+  createdAt!: Date;
+
+  @UpdateDateColumn({ name: 'updated_at', type: 'timestamptz' })
+  @Field()
+  updatedAt!: Date;
+}

package/src/lib/organization/resolved-manager.object.ts

@@ -0,0 +1,10 @@
+import { Field, ObjectType } from '@nestjs/graphql';
+
+@ObjectType('ResolvedManager')
+export class ResolvedManagerObject {
+  @Field()
+  memberId!: string;
+
+  @Field(() => String, { nullable: true })
+  managerMemberId!: string | null;
+}

package/src/lib/signature/signature-options.spec.ts

@@ -0,0 +1,60 @@
+import { resolveBPMSignatureOptions } from './signature-options';
+
+describe('resolveBPMSignatureOptions', () => {
+  const originalNodeEnv = process.env.NODE_ENV;
+  let warnSpy: jest.SpiedFunction<typeof console.warn>;
+
+  beforeEach(() => {
+    warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    process.env.NODE_ENV = originalNodeEnv;
+  });
+
+  it('does not warn outside production', (): void => {
+    process.env.NODE_ENV = 'test';
+
+    resolveBPMSignatureOptions();
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('warns when default providers are used under production', (): void => {
+    process.env.NODE_ENV = 'production';
+
+    resolveBPMSignatureOptions();
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const message = String(warnSpy.mock.calls[0]?.[0]);
+    expect(message).toContain('signatureKeyProvider');
+    expect(message).toContain('signatureTimestampProvider');
+  });
+
+  it('omits the field from the warning when a custom key provider is supplied', (): void => {
+    process.env.NODE_ENV = 'production';
+
+    resolveBPMSignatureOptions({
+      signatureKeyProvider: { readKey: (): string => 'kms-key' },
+    });
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const message = String(warnSpy.mock.calls[0]?.[0]);
+    expect(message).not.toContain('signatureKeyProvider,');
+    expect(message).toContain('signatureTimestampProvider');
+  });
+
+  it('does not warn when both providers are supplied', (): void => {
+    process.env.NODE_ENV = 'production';
+
+    resolveBPMSignatureOptions({
+      signatureKeyProvider: { readKey: (): string => 'kms-key' },
+      signatureTimestampProvider: {
+        createTimestampToken: (): Buffer => Buffer.from('rfc3161'),
+      },
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});

package/src/lib/signature/signature-options.ts

@@ -0,0 +1,120 @@
+import { InjectionToken } from '@nestjs/common';
+
+export interface BPMSignatureKeyProvider {
+  readKey(keyVersion: number): Promise<string | null> | string | null;
+}
+
+export interface BPMSignatureTimestampInput {
+  readonly signedAt: Date;
+  readonly signedPayloadHash: string;
+}
+
+export interface BPMSignatureTimestampProvider {
+  createTimestampToken(
+    input: BPMSignatureTimestampInput,
+  ): Promise<Buffer> | Buffer;
+}
+
+export interface BPMRootSignatureOptions {
+  /**
+   * Current signature key version used for newly created signatures.
+   */
+  readonly signatureCurrentKeyVersion?: number;
+
+  /**
+   * Host-provided key provider used to sign and verify signature records.
+   */
+  readonly signatureKeyProvider?: BPMSignatureKeyProvider;
+
+  /**
+   * Host-provided timestamp provider used to stamp signed payloads.
+   */
+  readonly signatureTimestampProvider?: BPMSignatureTimestampProvider;
+}
+
+export interface BPMResolvedSignatureOptions {
+  readonly currentKeyVersion: number;
+  readonly keyProvider: BPMSignatureKeyProvider;
+  readonly timestampProvider: BPMSignatureTimestampProvider;
+}
+
+const DEFAULT_KEY_VERSION = 1;
+const DEFAULT_SIGNATURE_KEYS: Readonly<Record<number, string>> = {
+  [DEFAULT_KEY_VERSION]: 'bpm-core-local-signature-key-v1',
+};
+
+const defaultKeyProvider: BPMSignatureKeyProvider = {
+  readKey: (keyVersion: number): string | null =>
+    DEFAULT_SIGNATURE_KEYS[keyVersion] ?? null,
+};
+
+const defaultTimestampProvider: BPMSignatureTimestampProvider = {
+  createTimestampToken: ({
+    signedAt,
+    signedPayloadHash,
+  }: BPMSignatureTimestampInput): Buffer =>
+    Buffer.from(
+      JSON.stringify({
+        provider: 'mock-rfc3161',
+        signedAt: signedAt.toISOString(),
+        signedPayloadHash,
+      }),
+      'utf8',
+    ),
+};
+
+export const BPM_SIGNATURE_OPTIONS: InjectionToken<BPMResolvedSignatureOptions> =
+  Symbol('BPM_SIGNATURE_OPTIONS');
+
+export const DEFAULT_BPM_SIGNATURE_OPTIONS: BPMResolvedSignatureOptions = {
+  currentKeyVersion: DEFAULT_KEY_VERSION,
+  keyProvider: defaultKeyProvider,
+  timestampProvider: defaultTimestampProvider,
+};
+
+export function resolveBPMSignatureOptions(
+  options: BPMRootSignatureOptions = {},
+): BPMResolvedSignatureOptions {
+  const usingDefaultKeyProvider = !options.signatureKeyProvider;
+  const usingDefaultTimestampProvider = !options.signatureTimestampProvider;
+
+  if (
+    (usingDefaultKeyProvider || usingDefaultTimestampProvider) &&
+    process.env.NODE_ENV === 'production'
+  ) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[@rytass/bpm-core-nestjs-module] decision signatures are using built-in local development providers (${
+        [
+          usingDefaultKeyProvider ? 'signatureKeyProvider' : null,
+          usingDefaultTimestampProvider ? 'signatureTimestampProvider' : null,
+        ]
+          .filter(Boolean)
+          .join(', ')
+      }). Replace them with KMS / Vault / RFC3161 providers before serving production traffic — signature chains would otherwise be unverifiable on rotation.`,
+    );
+  }
+
+  return {
+    currentKeyVersion: normalizePositiveInteger(
+      options.signatureCurrentKeyVersion,
+      DEFAULT_BPM_SIGNATURE_OPTIONS.currentKeyVersion,
+    ),
+    keyProvider:
+      options.signatureKeyProvider ?? DEFAULT_BPM_SIGNATURE_OPTIONS.keyProvider,
+    timestampProvider:
+      options.signatureTimestampProvider ??
+      DEFAULT_BPM_SIGNATURE_OPTIONS.timestampProvider,
+  };
+}
+
+function normalizePositiveInteger(
+  value: number | undefined,
+  fallback: number,
+): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+    return fallback;
+  }
+
+  return value;
+}

package/src/lib/signature/signature-verification.object.ts

@@ -0,0 +1,16 @@
+import { Field, ObjectType } from '@nestjs/graphql';
+
+@ObjectType('SignatureVerification')
+export class SignatureVerificationObject {
+  @Field()
+  instanceId!: string;
+
+  @Field()
+  valid!: boolean;
+
+  @Field()
+  checkedCount!: number;
+
+  @Field(() => [String])
+  errors!: readonly string[];
+}

package/src/lib/signature/signature.entity.ts

@@ -0,0 +1,62 @@
+import { Field, ID, Int, ObjectType } from '@nestjs/graphql';
+import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';
+
+@Entity('signatures')
+@ObjectType('Signature')
+export class SignatureEntity {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(() => ID)
+  id!: string;
+
+  @Column('uuid', { name: 'instance_id' })
+  @Field(() => ID)
+  instanceId!: string;
+
+  @Column('uuid', { name: 'task_id', nullable: true })
+  @Field(() => ID, { nullable: true })
+  taskId!: string | null;
+
+  @Column('text', { name: 'signer_member_id' })
+  @Field()
+  signerMemberId!: string;
+
+  @Column('text')
+  @Field()
+  algorithm!: string;
+
+  @Column('jsonb', { name: 'signed_payload' })
+  signedPayload!: Readonly<Record<string, unknown>>;
+
+  @Column('text', { name: 'signed_payload_hash' })
+  @Field()
+  signedPayloadHash!: string;
+
+  @Column('text')
+  @Field()
+  signature!: string;
+
+  @Column('integer', { name: 'key_version' })
+  @Field(() => Int)
+  keyVersion!: number;
+
+  @Column('text', { name: 'previous_signature_hash', nullable: true })
+  @Field(() => String, { nullable: true })
+  previousSignatureHash!: string | null;
+
+  @Column('bytea', { name: 'timestamp_token', nullable: true })
+  timestampToken!: Buffer | null;
+
+  @Column('timestamptz', { name: 'signed_at' })
+  @Field()
+  signedAt!: Date;
+
+  @Field()
+  get signedPayloadJson(): string {
+    return JSON.stringify(this.signedPayload ?? {});
+  }
+
+  @Field(() => String, { nullable: true })
+  get timestampTokenBase64(): string | null {
+    return this.timestampToken ? this.timestampToken.toString('base64') : null;
+  }
+}

package/src/lib/signature/signature.module.ts

@@ -0,0 +1,80 @@
+import {
+  DynamicModule,
+  Global,
+  InjectionToken,
+  Module,
+  Provider,
+} from '@nestjs/common';
+import { ModuleMetadata } from '@nestjs/common/interfaces';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import {
+  BPMRootSignatureOptions,
+  BPM_SIGNATURE_OPTIONS,
+  resolveBPMSignatureOptions,
+} from './signature-options';
+import { SignatureEntity } from './signature.entity';
+import { SignatureQueries } from './signature.queries';
+import { SignatureService } from './signature.service';
+
+export interface SignatureModuleAsyncOptions extends Pick<
+  ModuleMetadata,
+  'imports'
+> {
+  readonly inject?: readonly InjectionToken[];
+  readonly useFactory: (
+    ...args: readonly unknown[]
+  ) => BPMRootSignatureOptions | Promise<BPMRootSignatureOptions>;
+}
+
+@Global()
+@Module({
+  imports: [TypeOrmModule.forFeature([SignatureEntity])],
+  providers: [SignatureQueries, SignatureService],
+  exports: [SignatureService],
+})
+export class SignatureModule {
+  static forRoot(options: BPMRootSignatureOptions = {}): DynamicModule {
+    return {
+      exports: [BPM_SIGNATURE_OPTIONS, SignatureService],
+      imports: [TypeOrmModule.forFeature([SignatureEntity])],
+      module: SignatureModule,
+      providers: [
+        SignatureQueries,
+        SignatureService,
+        createSignatureOptionsProvider(options),
+      ],
+    };
+  }
+
+  static forRootAsync(options: SignatureModuleAsyncOptions): DynamicModule {
+    return {
+      exports: [BPM_SIGNATURE_OPTIONS, SignatureService],
+      imports: [
+        ...(options.imports ?? []),
+        TypeOrmModule.forFeature([SignatureEntity]),
+      ],
+      module: SignatureModule,
+      providers: [
+        SignatureQueries,
+        SignatureService,
+        {
+          inject: [...(options.inject ?? [])],
+          provide: BPM_SIGNATURE_OPTIONS,
+          useFactory: async (
+            ...args: readonly unknown[]
+          ): Promise<ReturnType<typeof resolveBPMSignatureOptions>> =>
+            resolveBPMSignatureOptions(await options.useFactory(...args)),
+        },
+      ],
+    };
+  }
+}
+
+function createSignatureOptionsProvider(
+  options: BPMRootSignatureOptions = {},
+): Provider {
+  return {
+    provide: BPM_SIGNATURE_OPTIONS,
+    useValue: resolveBPMSignatureOptions(options),
+  };
+}

package/src/lib/signature/signature.queries.ts

@@ -0,0 +1,37 @@
+import { Args, Query, Resolver } from '@nestjs/graphql';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { BPMAuthenticated } from '../bpm-auth';
+import { SignatureEntity } from './signature.entity';
+import { SignatureService } from './signature.service';
+import { SignatureVerificationObject } from './signature-verification.object';
+
+@Resolver()
+@BPMAuthenticated()
+export class SignatureQueries {
+  constructor(
+    @InjectRepository(SignatureEntity)
+    private readonly signatureRepository: Repository<SignatureEntity>,
+    private readonly signatureService: SignatureService,
+  ) {}
+
+  @Query(() => [SignatureEntity])
+  async signatures(
+    @Args('instanceId', { type: () => String }) instanceId: string,
+  ): Promise<readonly SignatureEntity[]> {
+    return this.signatureService.listSignatures(
+      this.signatureRepository,
+      instanceId,
+    );
+  }
+
+  @Query(() => SignatureVerificationObject)
+  async verifySignatureChain(
+    @Args('instanceId', { type: () => String }) instanceId: string,
+  ): Promise<SignatureVerificationObject> {
+    return this.signatureService.verifyInstanceSignatureChain(
+      this.signatureRepository,
+      instanceId,
+    );
+  }
+}

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

@@ -0,0 +1,134 @@
+import { EntityManager, Repository } from 'typeorm';
+import { ApprovalInstanceEntity } from '../workflow-engine/approval-instance.entity';
+import { TaskEntity } from '../workflow-engine/task.entity';
+import { TaskDecisionActionEnum } from '../workflow-engine/workflow-engine.enums';
+import { SignatureEntity } from './signature.entity';
+import { resolveBPMSignatureOptions } from './signature-options';
+import { SignatureService } from './signature.service';
+
+describe('SignatureService', () => {
+  it('creates verifiable chained HMAC signatures for task decisions', async (): Promise<void> => {
+    const signatures: SignatureEntity[] = [];
+    const repository = createSignatureRepository(signatures);
+    const manager = createManager(repository);
+    const service = new SignatureService();
+    const instance = Object.assign(new ApprovalInstanceEntity(), {
+      formData: { amount: 1200 },
+      id: 'instance-1',
+    });
+    const task = Object.assign(new TaskEntity(), {
+      id: 'task-1',
+      nodeId: 'approval',
+    });
+
+    const firstSignature = await service.signTaskDecision(manager, {
+      action: TaskDecisionActionEnum.APPROVED,
+      comment: null,
+      decidedAt: new Date('2026-05-10T10:00:00.000Z'),
+      instance,
+      returnToNodeId: null,
+      signerMemberId: 'member-001',
+      task,
+      transferToMemberId: null,
+    });
+    const secondSignature = await service.signTaskDecision(manager, {
+      action: TaskDecisionActionEnum.REJECTED,
+      comment: '資料不足',
+      decidedAt: new Date('2026-05-10T10:05:00.000Z'),
+      instance,
+      returnToNodeId: null,
+      signerMemberId: 'member-001',
+      task,
+      transferToMemberId: null,
+    });
+
+    expect(firstSignature.previousSignatureHash).toBeNull();
+    expect(secondSignature.previousSignatureHash).toBe(
+      firstSignature.signedPayloadHash,
+    );
+    await expect(
+      service.verifyInstanceSignatureChain(repository, instance.id),
+    ).resolves.toMatchObject({
+      checkedCount: 2,
+      errors: [],
+      valid: true,
+    });
+  });
+
+  it('uses configured signature key version, key provider, and timestamp provider', async (): Promise<void> => {
+    const signatures: SignatureEntity[] = [];
+    const repository = createSignatureRepository(signatures);
+    const manager = createManager(repository);
+    const service = new SignatureService(
+      resolveBPMSignatureOptions({
+        signatureCurrentKeyVersion: 7,
+        signatureKeyProvider: {
+          readKey: (keyVersion: number): string | null =>
+            keyVersion === 7 ? 'custom-signature-key' : null,
+        },
+        signatureTimestampProvider: {
+          createTimestampToken: (): Buffer => Buffer.from('timestamp-token'),
+        },
+      }),
+    );
+    const instance = Object.assign(new ApprovalInstanceEntity(), {
+      formData: { amount: 1200 },
+      id: 'instance-1',
+    });
+    const task = Object.assign(new TaskEntity(), {
+      id: 'task-1',
+      nodeId: 'approval',
+    });
+
+    const signature = await service.signTaskDecision(manager, {
+      action: TaskDecisionActionEnum.APPROVED,
+      comment: null,
+      decidedAt: new Date('2026-05-10T10:00:00.000Z'),
+      instance,
+      returnToNodeId: null,
+      signerMemberId: 'member-001',
+      task,
+      transferToMemberId: null,
+    });
+
+    expect(signature.keyVersion).toBe(7);
+    expect(signature.timestampToken?.toString('utf8')).toBe('timestamp-token');
+    await expect(
+      service.verifyInstanceSignatureChain(repository, instance.id),
+    ).resolves.toMatchObject({ errors: [], valid: true });
+  });
+});
+
+function createSignatureRepository(
+  signatures: SignatureEntity[],
+): Repository<SignatureEntity> {
+  const repository = {
+    create: (entity: Partial<SignatureEntity>): SignatureEntity =>
+      Object.assign(new SignatureEntity(), entity),
+    find: (): Promise<readonly SignatureEntity[]> =>
+      Promise.resolve(
+        [...signatures].sort(
+          (left, right) => left.signedAt.getTime() - right.signedAt.getTime(),
+        ),
+      ),
+    findOne: (): Promise<SignatureEntity | null> =>
+      Promise.resolve(signatures[signatures.length - 1] ?? null),
+    save: (entity: SignatureEntity): Promise<SignatureEntity> => {
+      const savedEntity = Object.assign(new SignatureEntity(), entity, {
+        id: entity.id ?? `signature-${signatures.length + 1}`,
+      });
+
+      signatures.push(savedEntity);
+
+      return Promise.resolve(savedEntity);
+    },
+  };
+
+  return repository as unknown as Repository<SignatureEntity>;
+}
+
+function createManager(repository: Repository<SignatureEntity>): EntityManager {
+  return {
+    getRepository: (): Repository<SignatureEntity> => repository,
+  } as unknown as EntityManager;
+}