@ftisindia/create-app 0.1.6 → 0.3.0

package/template/src/modules/forms/application/services/handlers/webhook.handler.ts

@@ -1,41 +1,89 @@
 import { createHmac } from 'node:crypto';
 import { Injectable } from '@nestjs/common';
+import type { Prisma } from '@prisma/client';
 import type { OutboxJobHandler, OutboxJobRecord } from '@ftisindia/form-builder';
+import { PrismaService } from '../../../../../database/prisma/prisma.service';
+import { deliverWebhookRequest } from './webhook-delivery.transport';
 
 /**
- * Generic webhook delivery. Payload contract: { url: string, body?: object,
- * secret?: string }. When a secret is set, the request carries
- * `x-forms-signature: sha256=<hmac-sha256(rawBody)>` so receivers can verify
- * authenticity. Non-2xx responses and timeouts throw, which the dispatcher
- * turns into a retry with backoff (then parks as FAILED after max attempts).
+ * Generic webhook delivery. Payload contract: { url: string, rawBody: string,
+ * signature?: string }. The engine computes the optional signature before
+ * enqueueing so the shared secret is not copied into the outbox payload.
+ * Non-2xx responses and timeouts throw, which the dispatcher turns into a
+ * retry with backoff (then parks as FAILED after max attempts).
  */
 @Injectable()
 export class WebhookOutboxHandler implements OutboxJobHandler {
   readonly type = 'webhook';
 
+  constructor(private readonly prisma: PrismaService) {}
+
   async handle(job: OutboxJobRecord): Promise<void> {
-    const { url, body, secret } = job.payload as {
+    const { url, rawBody, body, signature, secret } = job.payload as {
       url?: unknown;
+      rawBody?: unknown;
       body?: unknown;
+      signature?: unknown;
+      /** Backward-compatible support for jobs enqueued before secrets moved out of payloads. */
       secret?: unknown;
     };
     if (typeof url !== 'string' || url.length === 0) {
       throw new Error('Webhook job payload requires a "url" string.');
     }
-    const rawBody = JSON.stringify(body ?? {});
-    const headers: Record<string, string> = { 'content-type': 'application/json' };
-    if (typeof secret === 'string' && secret.length > 0) {
-      headers['x-forms-signature'] =
-        'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
+    const requestBody = typeof rawBody === 'string' ? rawBody : JSON.stringify(body ?? {});
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+    };
+    if (job.idempotencyKey) {
+      headers['x-forms-idempotency-key'] = job.idempotencyKey;
+    }
+    let resolvedSignature: string | undefined;
+    if (typeof signature === 'string' && signature.length > 0) {
+      resolvedSignature = signature;
+    } else if (typeof secret === 'string' && secret.length > 0) {
+      resolvedSignature =
+        'sha256=' + createHmac('sha256', secret).update(requestBody).digest('hex');
+      await this.sanitizeLegacyPayload(job, url, requestBody, resolvedSignature);
     }
-    const response = await fetch(url, {
-      method: 'POST',
+    if (resolvedSignature) {
+      headers['x-forms-signature'] = resolvedSignature;
+    }
+    const response = await deliverWebhookRequest(url, {
       headers,
-      body: rawBody,
-      signal: AbortSignal.timeout(10_000),
+      body: requestBody,
+      timeoutMs: 10_000,
     });
-    if (!response.ok) {
+    if (response.status >= 300 && response.status < 400) {
+      throw new Error(`Webhook redirects are not allowed (status ${response.status}).`);
+    }
+    if (response.status < 200 || response.status >= 300) {
       throw new Error(`Webhook endpoint responded with status ${response.status}.`);
     }
   }
+
+  private async sanitizeLegacyPayload(
+    job: OutboxJobRecord,
+    url: string,
+    rawBody: string,
+    signature: string,
+  ): Promise<void> {
+    const claimedBy = typeof job.claimedBy === 'string' ? job.claimedBy : '';
+    if (!claimedBy) {
+      throw new Error('Webhook job is missing a claim token.');
+    }
+
+    const result = await this.prisma.formOutboxJob.updateMany({
+      where: { id: job.id, status: 'PROCESSING', claimedBy },
+      data: {
+        payload: {
+          url,
+          rawBody,
+          signature,
+        } satisfies Prisma.InputJsonValue,
+      },
+    });
+    if (result.count !== 1) {
+      throw new Error('Webhook job lease was lost before legacy payload cleanup.');
+    }
+  }
 }

package/template/src/modules/forms/application/services/outbox-dispatcher.service.ts

@@ -7,6 +7,8 @@ import { AuditService } from '../../../audit/application/services/audit.service'
 import { RequestContextService } from '../../../request-context/application/services/request-context.service';
 import { PrismaOutboxStore } from '../../infrastructure/stores/prisma-outbox.store';
 
+const DEFAULT_PROCESSING_HEARTBEAT_MS = 60_000;
+
 /**
  * In-process outbox poller (ecosystem guide §3/§8.3). Every claimed job runs
  * inside requestContext.run({ source: 'worker', jobId, orgId, userId,
@@ -15,9 +17,9 @@ import { PrismaOutboxStore } from '../../infrastructure/stores/prisma-outbox.sto
  * originating request. Successful delivery writes an audit row.
  *
  * Deterministic in tests: FORMS_OUTBOX_ENABLED=false disables the timer and
- * runOnce() drives a single cycle by hand. Single-instance by design — a
- * multi-node deployment should swap the store's claim for SKIP LOCKED or a
- * real queue (BullMQ) without touching the engine.
+ * runOnce() drives a single cycle by hand. The default Prisma store claims
+ * jobs with row-level locks; apps that outgrow the starter poller can swap
+ * this boundary for a queue-backed implementation without touching handlers.
  */
 @Injectable()
 export class OutboxDispatcherService implements OnApplicationBootstrap, OnModuleDestroy {
@@ -53,6 +55,8 @@ export class OutboxDispatcherService implements OnApplicationBootstrap, OnModule
   }
 
   async runOnce(): Promise<DispatchCycleResult> {
+    const heartbeatMs =
+      this.config.get<number>('forms.outboxHeartbeatMs') ?? DEFAULT_PROCESSING_HEARTBEAT_MS;
     return runDispatchCycle(this.store, this.handlers, {
       wrapJob: (job, run) =>
         this.requestContext.run(
@@ -64,25 +68,43 @@ export class OutboxDispatcherService implements OnApplicationBootstrap, OnModule
             requestId: job.originRequestId ?? undefined,
           },
           async () => {
-            const outcome = await run();
-            if (outcome === 'done') {
-              try {
-                await this.audit.write(this.prisma, {
-                  orgId: job.orgId ?? null,
-                  actorUserId: job.actorUserId ?? null,
-                  action: 'forms.outbox.delivered',
-                  targetType: 'FormOutboxJob',
-                  targetId: job.id,
-                  metadata: { type: job.type, attempts: job.attempts + 1 },
-                });
-              } catch (error) {
+            const claimedBy = typeof job.claimedBy === 'string' ? job.claimedBy : '';
+            const heartbeat = setInterval(() => {
+              if (!claimedBy) {
+                return;
+              }
+              void this.store.touchProcessing(job.id, claimedBy).catch((error: unknown) => {
                 this.logger.warn(
-                  `Outbox delivery audit failed for job ${job.id}.`,
+                  `Outbox heartbeat failed for job ${job.id}.`,
                   error instanceof Error ? error.stack : String(error),
                 );
+              });
+            }, heartbeatMs);
+            heartbeat.unref?.();
+
+            try {
+              const outcome = await run();
+              if (outcome === 'done') {
+                try {
+                  await this.audit.write(this.prisma, {
+                    orgId: job.orgId ?? null,
+                    actorUserId: job.actorUserId ?? null,
+                    action: 'forms.outbox.delivered',
+                    targetType: 'FormOutboxJob',
+                    targetId: job.id,
+                    metadata: { type: job.type, attempts: job.attempts + 1 },
+                  });
+                } catch (error) {
+                  this.logger.warn(
+                    `Outbox delivery audit failed for job ${job.id}.`,
+                    error instanceof Error ? error.stack : String(error),
+                  );
+                }
               }
+              return outcome;
+            } finally {
+              clearInterval(heartbeat);
             }
-            return outcome;
           },
         ),
     });
@@ -97,7 +119,7 @@ export class OutboxDispatcherService implements OnApplicationBootstrap, OnModule
       const result = await this.runOnce();
       if (result.claimed > 0) {
         this.logger.log(
-          `Outbox cycle: claimed ${result.claimed}, done ${result.done}, retried ${result.retried}, failed ${result.failed}.`,
+          `Outbox cycle: claimed ${result.claimed}, done ${result.done}, retried ${result.retried}, failed ${result.failed}, stale ${result.stale}.`,
         );
       }
     } catch (error) {

package/template/src/modules/forms/dto/public-file-upload-response.dto.ts

@@ -0,0 +1,10 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { FileUploadResponseDto } from './file-upload-response.dto';
+
+export class PublicFileUploadResponseDto extends FileUploadResponseDto {
+  @ApiProperty({
+    example: 'qg7N4gJvG7lQzZ5aH8gHovC6hRr0QZq1LurNkrXJq6w',
+    description: 'One-time claim token required when submitting this public file reference.',
+  })
+  uploadToken!: string;
+}

package/template/src/modules/forms/dto/public-submit-form.dto.ts

@@ -16,6 +16,15 @@ export class PublicSubmitFormDto {
   @Min(1)
   version?: number;
 
+  @ApiPropertyOptional({
+    type: 'object',
+    additionalProperties: { type: 'string' },
+    description: 'Public upload claim tokens keyed by fileId.',
+  })
+  @IsOptional()
+  @IsObject()
+  uploadTokens?: Record<string, string>;
+
   @ApiPropertyOptional({ description: 'Captcha token, required when the form enables captcha.' })
   @IsOptional()
   @IsString()

package/template/src/modules/forms/forms.module.ts

@@ -20,6 +20,7 @@ import { FormsFilesService } from './application/services/forms-files.service';
 import { FormsPublicService } from './application/services/forms-public.service';
 import { FormsSettingsReader } from './application/services/forms-settings-reader.service';
 import { FormsSubmissionsService } from './application/services/forms-submissions.service';
+import { ConferenceTracksDataSource } from './application/services/data-sources/conference-tracks.data-source';
 import { AuthenticateActionHandler } from './application/services/handlers/authenticate.action';
 import { LoggingEmailHandler } from './application/services/handlers/logging-email.handler';
 import { SendConfirmationEmailAction } from './application/services/handlers/send-confirmation-email.action';
@@ -42,7 +43,9 @@ import { FormsDefinitionsController } from './presentation/forms-definitions.con
 import { FormsFilesController } from './presentation/forms-files.controller';
 import { FormsSubmissionsController } from './presentation/forms-submissions.controller';
 import { FormsUploadInterceptor } from './presentation/forms-upload.interceptor';
-import { PublicFormsController } from './presentation/public-forms.controller';
+import { PublicFormsController } from './presentation/public-forms.controller';
+import { PublicFormsFilesController } from './presentation/public-forms-files.controller';
+import { FORMS_CAPTCHA_VERIFIER } from './forms.tokens';
 
 /**
  * The forms glue module — the ONLY place that binds the framework-free
@@ -60,7 +63,8 @@ import { PublicFormsController } from './presentation/public-forms.controller';
     FormsDefinitionsController,
     FormsFilesController,
     FormsSubmissionsController,
-    PublicFormsController,
+    PublicFormsController,
+    PublicFormsFilesController,
   ],
   providers: [
     // Adapters over the ecosystem seams.
@@ -75,6 +79,9 @@ import { PublicFormsController } from './presentation/public-forms.controller';
     PrismaFileStore,
     PrismaActionLogStore,
     FormsSettingsReader,
+    // Secure default: public forms with settings.captcha=true fail publish
+    // until the app replaces this provider with a real CaptchaVerifier.
+    { provide: FORMS_CAPTCHA_VERIFIER, useValue: undefined },
     // Engine registries — singletons; core field types registered up front.
     {
       provide: FieldTypeRegistry,
@@ -194,6 +201,9 @@ import { PublicFormsController } from './presentation/public-forms.controller';
     LocalDiskStorageAdapter,
     FileGcService,
     FormsUploadInterceptor,
+    // Example data source backing examples/abstract-submission.form.json.
+    // Delete or replace it with an org-scoped lookup in production apps.
+    ConferenceTracksDataSource,
     // Default outbox handlers + shipped form actions.
     LoggingEmailHandler,
     WebhookOutboxHandler,

package/template/src/modules/forms/infrastructure/stores/prisma-file.store.ts

@@ -1,3 +1,4 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
 import { Injectable } from '@nestjs/common';
 import { Prisma, UploadedFile as UploadedFileRow } from '@prisma/client';
 import type {
@@ -26,6 +27,8 @@ export class PrismaFileStore implements FileStore {
         size: record.size,
         checksum: record.checksum,
         ownerId: record.ownerId,
+        claimTokenHash: record.claimTokenHash ?? null,
+        uploadedIp: record.uploadedIp ?? null,
         orgId: record.orgId,
         status: record.status,
       },
@@ -34,12 +37,19 @@ export class PrismaFileStore implements FileStore {
     return this.toRecord(row);
   }
 
-  async findById(orgId: string, id: string, tx?: EngineTx): Promise<UploadedFileRecord | null> {
+  async findById(
+    orgId: string,
+    id: string,
+    tx?: EngineTx,
+    presentedClaimToken?: string,
+  ): Promise<UploadedFileRecord | null> {
     const row = await this.client(tx).uploadedFile.findFirst({
       where: { id, orgId },
     });
 
-    return row ? this.toRecord(row) : null;
+    return row
+      ? this.toRecord(row, this.claimTokenMatches(row.claimTokenHash, presentedClaimToken))
+      : null;
   }
 
   async updateStatus(
@@ -71,6 +81,21 @@ export class PrismaFileStore implements FileStore {
     return this.toRecord(row);
   }
 
+  async countPublicUploadsByIpSince(
+    orgId: string,
+    ipAddress: string,
+    since: Date,
+  ): Promise<number> {
+    return this.client().uploadedFile.count({
+      where: {
+        orgId,
+        ownerId: null,
+        uploadedIp: ipAddress,
+        createdAt: { gte: since },
+      },
+    });
+  }
+
   async listGcEligible(cutoff: Date, limit: number): Promise<UploadedFileRecord[]> {
     const rows = await this.client().uploadedFile.findMany({
       where: {
@@ -90,7 +115,21 @@ export class PrismaFileStore implements FileStore {
     });
   }
 
-  private toRecord(row: UploadedFileRow): UploadedFileRecord {
+  private claimTokenMatches(
+    expectedHash: string | null,
+    presentedClaimToken: string | undefined,
+  ): boolean {
+    if (!expectedHash || !presentedClaimToken) {
+      return false;
+    }
+
+    const presentedHash = createHash('sha256').update(presentedClaimToken).digest('hex');
+    const expected = Buffer.from(expectedHash, 'hex');
+    const presented = Buffer.from(presentedHash, 'hex');
+    return expected.length === presented.length && timingSafeEqual(expected, presented);
+  }
+
+  private toRecord(row: UploadedFileRow, claimTokenValid?: boolean): UploadedFileRecord {
     return {
       id: row.id,
       storageKey: row.storageKey,
@@ -99,6 +138,7 @@ export class PrismaFileStore implements FileStore {
       size: row.size,
       checksum: row.checksum,
       ownerId: row.ownerId,
+      claimTokenValid,
       orgId: row.orgId,
       status: row.status as FileStatus,
       submissionId: row.submissionId,

package/template/src/modules/forms/infrastructure/stores/prisma-outbox.store.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { Injectable } from '@nestjs/common';
 import { FormOutboxJob as FormOutboxJobRow, Prisma } from '@prisma/client';
 import type {
@@ -20,96 +21,117 @@ export class PrismaOutboxStore implements OutboxStore {
   }
 
   async enqueue(job: OutboxJobInput, tx: EngineTx): Promise<void> {
-    await this.client(tx).formOutboxJob.create({
-      data: {
-        type: job.type,
-        payload: job.payload as unknown as Prisma.InputJsonValue,
-        status: 'PENDING',
-        attempts: 0,
-        maxAttempts: job.maxAttempts ?? 8,
-        idempotencyKey: job.idempotencyKey ?? null,
-        runAfter: job.runAfter ?? null,
-        orgId: job.orgId ?? null,
-        actorUserId: job.actorUserId ?? null,
-        originRequestId: job.originRequestId ?? null,
-      },
-    });
-  }
-
-  /**
-   * Claims due PENDING jobs and stale PROCESSING jobs by selecting candidates
-   * and flipping them to PROCESSING with a guarded updateMany. This is safe
-   * for the template's single in-process dispatcher; multi-instance
-   * deployments should move the claim to `SELECT ... FOR UPDATE SKIP LOCKED`.
-   */
-  async claimDue(now: Date, batchSize: number): Promise<OutboxJobRecord[]> {
-    const staleProcessingBefore = new Date(now.getTime() - PROCESSING_LEASE_MS);
-    const claimableWhere: Prisma.FormOutboxJobWhereInput = {
-      OR: [
+    await this.client(tx).formOutboxJob.createMany({
+      data: [
         {
+          type: job.type,
+          payload: job.payload as unknown as Prisma.InputJsonValue,
           status: 'PENDING',
-          OR: [{ runAfter: null }, { runAfter: { lte: now } }],
-        },
-        {
-          status: 'PROCESSING',
-          updatedAt: { lte: staleProcessingBefore },
+          attempts: 0,
+          maxAttempts: job.maxAttempts ?? 8,
+          idempotencyKey: job.idempotencyKey ?? null,
+          runAfter: job.runAfter ?? null,
+          orgId: job.orgId ?? null,
+          actorUserId: job.actorUserId ?? null,
+          originRequestId: job.originRequestId ?? null,
         },
       ],
-    };
-
-    const due = await this.client().formOutboxJob.findMany({
-      where: claimableWhere,
-      orderBy: { createdAt: 'asc' },
-      take: batchSize,
-      select: { id: true },
+      skipDuplicates: true,
     });
+  }
 
-    if (due.length === 0) {
+  /**
+   * Claims due PENDING jobs and stale PROCESSING jobs with row-level locks so
+   * multiple app instances can poll without double-delivering the same job.
+   */
+  async claimDue(now: Date, batchSize: number): Promise<OutboxJobRecord[]> {
+    if (batchSize <= 0) {
       return [];
     }
 
-    const ids = due.map((row) => row.id);
-
-    await this.client().formOutboxJob.updateMany({
-      where: { id: { in: ids }, ...claimableWhere },
-      data: { status: 'PROCESSING' },
-    });
-
-    const claimed = await this.client().formOutboxJob.findMany({
-      where: { id: { in: ids }, status: 'PROCESSING' },
-    });
+    const staleProcessingBefore = new Date(now.getTime() - PROCESSING_LEASE_MS);
+    const claimedBy = randomUUID();
+    const claimed = await this.prisma.$transaction(
+      (tx) =>
+        tx.$queryRaw<FormOutboxJobRow[]>`
+        WITH due AS (
+          SELECT "id"
+          FROM "FormOutboxJob"
+          WHERE (
+            "status" = 'PENDING'
+            AND ("runAfter" IS NULL OR "runAfter" <= (${now}::timestamptz AT TIME ZONE 'UTC'))
+          )
+          OR (
+            "status" = 'PROCESSING'
+            AND "updatedAt" <= (${staleProcessingBefore}::timestamptz AT TIME ZONE 'UTC')
+          )
+          ORDER BY "createdAt" ASC
+          LIMIT ${batchSize}
+          FOR UPDATE SKIP LOCKED
+        )
+        UPDATE "FormOutboxJob" AS job
+        SET "status" = 'PROCESSING',
+            "claimedBy" = ${claimedBy},
+            "updatedAt" = (CURRENT_TIMESTAMP AT TIME ZONE 'UTC')
+        FROM due
+        WHERE job."id" = due."id"
+        RETURNING job.*
+      `,
+    );
 
     return claimed.map((row) => this.toRecord(row));
   }
 
-  async markDone(id: string): Promise<void> {
-    await this.client().formOutboxJob.update({
-      where: { id },
-      data: { status: 'DONE' },
+  async markDone(id: string, claimedBy: string): Promise<boolean> {
+    const result = await this.client().formOutboxJob.updateMany({
+      where: { id, status: 'PROCESSING', claimedBy },
+      data: { status: 'DONE', claimedBy: null },
     });
+    return result.count === 1;
   }
 
-  async markRetry(id: string, attempts: number, runAfter: Date, lastError: string): Promise<void> {
-    await this.client().formOutboxJob.update({
-      where: { id },
+  async markRetry(
+    id: string,
+    claimedBy: string,
+    attempts: number,
+    runAfter: Date,
+    lastError: string,
+  ): Promise<boolean> {
+    const result = await this.client().formOutboxJob.updateMany({
+      where: { id, status: 'PROCESSING', claimedBy },
       data: {
         status: 'PENDING',
+        claimedBy: null,
         attempts,
         runAfter,
         lastError,
       },
     });
+    return result.count === 1;
   }
 
-  async markFailed(id: string, attempts: number, lastError: string): Promise<void> {
-    await this.client().formOutboxJob.update({
-      where: { id },
+  async markFailed(id: string, claimedBy: string, attempts: number, lastError: string): Promise<boolean> {
+    const result = await this.client().formOutboxJob.updateMany({
+      where: { id, status: 'PROCESSING', claimedBy },
       data: {
         status: 'FAILED',
+        claimedBy: null,
         attempts,
         lastError,
       },
     });
+    return result.count === 1;
+  }
+
+  async touchProcessing(id: string, claimedBy: string): Promise<boolean> {
+    const touched = await this.prisma.$executeRaw`
+      UPDATE "FormOutboxJob"
+      SET "updatedAt" = (CURRENT_TIMESTAMP AT TIME ZONE 'UTC')
+      WHERE "id" = ${id}
+        AND "status" = 'PROCESSING'
+        AND "claimedBy" = ${claimedBy}
+    `;
+    return touched === 1;
   }
 
   private toRecord(row: FormOutboxJobRow): OutboxJobRecord {
@@ -118,6 +140,7 @@ export class PrismaOutboxStore implements OutboxStore {
       type: row.type,
       payload: row.payload as unknown as Record<string, unknown>,
       status: row.status as OutboxStatus,
+      claimedBy: row.claimedBy,
       attempts: row.attempts,
       maxAttempts: row.maxAttempts,
       idempotencyKey: row.idempotencyKey,

package/template/src/modules/forms/presentation/public-forms-files.controller.ts

@@ -0,0 +1,66 @@
+import {
+  Controller,
+  HttpCode,
+  Param,
+  Post,
+  Query,
+  UploadedFile,
+  UseGuards,
+  UseInterceptors,
+} from '@nestjs/common';
+import {
+  ApiBody,
+  ApiConsumes,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+} from '@nestjs/swagger';
+import { Throttle } from '@nestjs/throttler';
+import { ApiProtectedErrorResponses } from '../../../common/swagger/api-error-responses';
+import { Public } from '../../access-control/presentation/public.decorator';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { FormsFilesService } from '../application/services/forms-files.service';
+import { PublicFileUploadResponseDto } from '../dto/public-file-upload-response.dto';
+import { UploadFileQueryDto } from '../dto/upload-file-query.dto';
+import { FormsUploadInterceptor } from './forms-upload.interceptor';
+
+@ApiTags('Forms (public)')
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiParam({ name: 'formKey', description: 'Form definition key.' })
+@ApiProtectedErrorResponses(400, 404, 413, 415, 429)
+@Controller('public/organisations/:orgId/forms/:formKey/files')
+@UseGuards(OrgScopeGuard)
+export class PublicFormsFilesController {
+  constructor(private readonly filesService: FormsFilesService) {}
+
+  @Post()
+  @Public()
+  @HttpCode(200)
+  @Throttle({ default: { limit: 5, ttl: 60_000 } })
+  @UseInterceptors(FormsUploadInterceptor)
+  @ApiConsumes('multipart/form-data')
+  @ApiBody({
+    schema: {
+      type: 'object',
+      properties: { file: { type: 'string', format: 'binary' } },
+      required: ['file'],
+    },
+  })
+  @ApiOperation({
+    summary:
+      'Upload a file for a public form field. Submit must include the returned fileId and uploadToken.',
+  })
+  @ApiOkResponse({
+    description: 'Uploaded public file reference.',
+    type: PublicFileUploadResponseDto,
+  })
+  upload(
+    @Param('orgId') orgId: string,
+    @Param('formKey') formKey: string,
+    @Query() query: UploadFileQueryDto,
+    @UploadedFile() file: { originalname: string; size: number; buffer: Buffer } | undefined,
+  ) {
+    return this.filesService.uploadPublic(orgId, formKey, query, file);
+  }
+}