@ftisindia/create-app 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftisindia/create-app",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "One-command scaffolder for the Phase 1 NestJS foundation starter.",
   "type": "module",
   "bin": {

package/template/_package.json

@@ -10,6 +10,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "forms:push": "ts-node scripts/push-form.ts",
+    "reports:push": "ts-node scripts/push-report.ts",
     "gen:form": "node scripts/gen-form.mjs",
     "gen:module": "node scripts/gen-module.mjs",
     "lint": "eslint .",
@@ -33,8 +34,8 @@
   },
   "dependencies": {
     "@casl/ability": "6.8.1",
-    "@ftisindia/form-builder": "^0.1.0",
-    "@ftisindia/report-builder": "^0.1.0",
+    "@ftisindia/form-builder": "^1.0.0",
+    "@ftisindia/report-builder": "^0.3.0",
     "@nestjs/common": "11.1.24",
     "@nestjs/config": "4.0.4",
     "@nestjs/core": "11.1.24",

package/template/docs/FORMS.md

@@ -49,6 +49,14 @@ rolls back everything.
 Implement the engine interface, decorate the provider, list it in a module —
 the registry bootstrap finds it at startup:
 
+Definitions can reference a `dataSource.key` only after a matching provider is
+registered. This template ships `ConferenceTracksDataSource` in
+`src/modules/forms/application/services/data-sources/` for the bundled
+`abstract-submission` example (`conference-tracks`). It is intentionally static
+so fresh apps can publish and render the example immediately; replace it with an
+org-scoped Prisma/API lookup before using real production master data. An
+unregistered source fails save/publish lint with `UNKNOWN_DATA_SOURCE`.
+
 ```ts
 import { FormDataSource } from './modules/forms/infrastructure/registry/form-extension.decorators';
 import type { DataSourceDef, DataSourceContext, DataSourceOption } from '@ftisindia/form-builder';
@@ -95,9 +103,51 @@ Flip a published definition with `POST .../public-access { "access": "public" }`
 (requires `forms.managePublicAccess`, writes an audit row). Public routes are
 throttled tighter than the app default; the engine enforces the per-IP/day
 cap (`forms.maxSubmissionsPerIpPerDay` setting, per-form override in the
-definition's `settings`) and the captcha seam (`settings.captcha: true` —
+definition's `settings`) and the captcha seam (`settings.captcha: true` -
 publish fails closed unless a `CaptchaVerifier` is bound to the
-`FORMS_CAPTCHA_VERIFIER` token). Public forms cannot contain file fields.
+`FORMS_CAPTCHA_VERIFIER` token). Public file fields are allowed through the
+public upload endpoint: upload first, then submit `{ fileId }` in `data` and the
+returned token in `uploadTokens[fileId]`. Anonymous upload volume is capped by
+`forms.maxPublicUploadsPerIpPerDay`. Like the public submission cap, it depends on a resolvable request IP; configure proxy/IP handling correctly in deployments behind a reverse proxy.
+
+A captcha-enabled public form keeps failing closed until the app binds a real
+verifier. Example Turnstile-style adapter:
+
+```ts
+import { Injectable, Module } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import type { CaptchaVerifier, FormsContext } from '@ftisindia/form-builder';
+import { FORMS_CAPTCHA_VERIFIER } from './modules/forms/forms.tokens';
+
+@Injectable()
+export class TurnstileCaptchaVerifier implements CaptchaVerifier {
+  constructor(private readonly config: ConfigService) {}
+
+  async verify(token: string, _ctx: FormsContext): Promise<boolean> {
+    const body = new URLSearchParams({
+      secret: this.config.getOrThrow<string>('TURNSTILE_SECRET_KEY'),
+      response: token,
+    });
+    const response = await fetch(
+      'https://challenges.cloudflare.com/turnstile/v0/siteverify',
+      { method: 'POST', body },
+    );
+    const result = (await response.json()) as { success?: boolean };
+    return result.success === true;
+  }
+}
+
+@Module({
+  providers: [
+    { provide: FORMS_CAPTCHA_VERIFIER, useClass: TurnstileCaptchaVerifier },
+  ],
+})
+export class AppCaptchaModule {}
+```
+
+After that binding is present, a definition can opt in with
+`settings.captcha: true`; without the binding, publish fails before the form can
+go public.
 
 ## Files
 
@@ -161,7 +211,7 @@ npm run forms:push -- --file src/modules/forms/definitions/customer-feedback.for
     --org demo --user owner@example.com --publish
 ```
 
-`gen:form` writes `src/modules/forms/definitions/<key>.form.json` and
+Example files under `src/modules/forms/examples/` are reference fixtures; copy or scaffold into `src/modules/forms/definitions/` before pushing. `gen:form` writes `src/modules/forms/definitions/<key>.form.json` and
 `test/<key>.form.spec.ts` (meta-schema + publish-stage lint — fails `npm test`
 the moment the definition would be rejected by the API). `forms:push` loads a
 definition file into an org through the real engine path: it impersonates an

package/template/docs/FORMS_CHECKLIST.md

@@ -23,6 +23,7 @@ local PostgreSQL `postgres/root`: `npm run dogfood`, generated app
 
 - [x] All 11 form permission keys exist in `permissionKeys`, are seeded, and `test/forms-permission-sync.spec.ts` passes (engine <-> template set equality).
 - [x] Every protected form route is in `routePermissionRegistry` (the boot-time registry validator passes).
+- [x] The bundled `ConferenceTracksDataSource` backs the abstract-submission example; production data sources remain app-provided `@FormDataSource()` providers.
 
 ## Gating
 
@@ -45,10 +46,11 @@ local PostgreSQL `postgres/root`: `npm run dogfood`, generated app
 
 - [x] Public path: `@Public()` render/submit works without membership; a non-public form 404s on the public routes; org-scoped storage still enforced; permissioned paths unaffected.
 - [x] Tier-1 abuse baseline active: public routes throttled tighter than the app default; per-IP/day caps read from typed settings (with per-form override) and enforced; IP/UA stamped on anonymous submissions; captcha seam invoked when enabled; captcha-enabled-without-adapter fails at publish, not at submit.
+- [x] Captcha remains fail-closed by default: apps must bind a real `CaptchaVerifier` to `FORMS_CAPTCHA_VERIFIER` before publishing public forms with `settings.captcha: true`.
 
 ## Files
 
-- [x] Upload -> submit -> `LINKED` flow proven; a foreign user's `fileId` is rejected (IDOR); GC sweeps orphaned `TEMPORARY` files past TTL; public forms with file fields are rejected at publish.
+- [x] Upload -> submit -> `LINKED` flow proven; a foreign user's `fileId` is rejected (IDOR); public uploads require the per-file token returned by the public upload endpoint; GC sweeps orphaned `TEMPORARY` files past TTL.
 
 ## Webhooks
 

package/template/docs/REPORTS.md

@@ -50,8 +50,17 @@ definition AND again at execute time.
 
 Example definitions live in `src/modules/reports/examples/` — `org-members`
 (custom source, no form builder anywhere) and `abstract-review-board` (the
-form-backed quick path, indexed tier).
+form-backed quick path, indexed tier).
+
+## Definitions as code (`reports:push`)
 
+```bash
+npm run reports:push -- --file src/modules/reports/definitions/member-directory.report.json \
+    --org demo --user owner@example.com --publish
+```
+
+`src/modules/reports/definitions/*.report.json` files are source files; they are not loaded automatically at boot. `reports:push` loads a definition into an org through the real service path, so member RBAC, save/publish linting, versioning, and audit rows match the HTTP API. Re-pushing unchanged content is a no-op; changed content creates the next draft version, and `--publish` publishes it.
+
 ## One contract: the QuerySpec
 
 The frontend never builds queries. Every grid interaction posts a declarative

package/template/prisma/migrations/20260625000000_form_builder_public_uploads/migration.sql

@@ -0,0 +1,7 @@
+-- AlterTable
+ALTER TABLE "UploadedFile" ALTER COLUMN "ownerId" DROP NOT NULL,
+ADD COLUMN "claimTokenHash" TEXT,
+ADD COLUMN "uploadedIp" TEXT;
+
+-- CreateIndex
+CREATE INDEX "UploadedFile_orgId_uploadedIp_createdAt_idx" ON "UploadedFile"("orgId", "uploadedIp", "createdAt");

package/template/prisma/schema.prisma

@@ -298,7 +298,7 @@ model AuditLog {
   @@index([createdAt])
 }
 // ─────────────────────────────────────────────────────────────────────────────
-// @ftisindia/form-builder — canonical Prisma model snippet (ENGINE_SCHEMA_VERSION 1)
+// @ftisindia/form-builder - canonical Prisma model snippet (ENGINE_SCHEMA_VERSION 3)
 //
 // The APP owns schema.prisma and the migration history (ecosystem guide §10.1).
 // Copy these models into your app's prisma/schema.prisma verbatim and run
@@ -441,9 +441,11 @@ model UploadedFile {
   size     Int
   // sha256 hex.
   checksum String
-  // Two-factor ownership: uploader identity AND tenant scope (§10).
-  ownerId String
-  orgId   String
+  // Authenticated uploads have ownerId; anonymous public uploads have a claim token.
+  ownerId        String?
+  claimTokenHash String?
+  uploadedIp     String?
+  orgId          String
 
   status       FileStatus @default(TEMPORARY)
   submissionId String?
@@ -451,7 +453,8 @@ model UploadedFile {
   createdAt DateTime @default(now())
 
   @@index([orgId, status])
-  @@index([ownerId, status])
+  @@index([ownerId, status])
+  @@index([orgId, uploadedIp, createdAt])
   @@index([status, createdAt])
 }
 

package/template/scripts/push-report.ts

@@ -0,0 +1,123 @@
+/**
+ * Push a report-definition JSON file into an organisation through the real
+ * report engine path: member RBAC, save/publish linting, versioning, and audit
+ * rows all stay intact.
+ *
+ *   npm run reports:push -- --file src/modules/reports/definitions/my-report.report.json \
+ *       --org <org-id-or-slug> --user <member-email> [--publish]
+ *
+ * Idempotent: if the file matches the latest stored version's authored content,
+ * nothing new is created. With --publish, a matching DRAFT is published in place.
+ * Runs under ts-node because it bootstraps Nest.
+ */
+import { readFileSync } from 'node:fs';
+import { NestFactory } from '@nestjs/core';
+import type { ReportDefinition } from '@ftisindia/report-builder';
+import { AppModule } from '../src/app.module';
+import { PrismaService } from '../src/database/prisma/prisma.service';
+import { RbacCacheService } from '../src/modules/access-control/application/services/rbac-cache.service';
+import { RequestContextService } from '../src/modules/request-context/application/services/request-context.service';
+import { ReportsDefinitionsService } from '../src/modules/reports/application/services/reports-definitions.service';
+import { CreateReportDefinitionDto } from '../src/modules/reports/dto/create-report-definition.dto';
+
+function argValue(flag: string): string | undefined {
+  const index = process.argv.indexOf(flag);
+  return index !== -1 ? process.argv[index + 1] : undefined;
+}
+
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** Version/status are managed by the engine - compare authored content only. */
+function normalized(schema: ReportDefinition): string {
+  const { version: _version, status: _status, ...rest } = schema;
+  return stableStringify(rest);
+}
+
+async function main() {
+  const file = argValue('--file');
+  const orgRef = argValue('--org');
+  const userEmail = argValue('--user');
+  const publish = process.argv.includes('--publish');
+  if (!file || !orgRef || !userEmail) {
+    throw new Error(
+      'Usage: npm run reports:push -- --file <path> --org <org-id-or-slug> --user <member-email> [--publish]',
+    );
+  }
+
+  const definition = JSON.parse(readFileSync(file, 'utf8')) as ReportDefinition;
+  if (!definition.key) {
+    throw new Error(`${file} does not look like a report definition (missing "key").`);
+  }
+
+  const app = await NestFactory.createApplicationContext(AppModule, {
+    logger: ['error', 'warn'],
+  });
+  try {
+    const prisma = app.get(PrismaService);
+    const user = await prisma.user.findFirst({ where: { email: userEmail } });
+    if (!user) {
+      throw new Error(`No user found with email "${userEmail}".`);
+    }
+    const org = await prisma.organisation.findFirst({
+      where: { OR: [{ id: orgRef }, { slug: orgRef }] },
+    });
+    if (!org) {
+      throw new Error(`No organisation found with id or slug "${orgRef}".`);
+    }
+
+    const rbac = await app.get(RbacCacheService).getContext(user.id, org.id);
+    const requestContext = app.get(RequestContextService);
+    const definitions = app.get(ReportsDefinitionsService);
+
+    await requestContext.run(
+      { source: 'worker', orgId: org.id, userId: user.id, rbac },
+      async () => {
+        const latest = await prisma.reportDefinition.findFirst({
+          where: { orgId: org.id, key: definition.key },
+          orderBy: { version: 'desc' },
+        });
+
+        if (latest && normalized(latest.schema as unknown as ReportDefinition) === normalized(definition)) {
+          if (publish && latest.status === 'DRAFT') {
+            await definitions.publish(org.id, definition.key);
+            console.log(`Unchanged content - published existing draft v${latest.version}.`);
+          } else {
+            console.log(
+              `No changes - "${definition.key}" v${latest.version} (${latest.status}) already matches ${file}.`,
+            );
+          }
+          return;
+        }
+
+        const created = await definitions.create(
+          org.id,
+          definition as unknown as CreateReportDefinitionDto,
+        );
+        console.log(`Created "${created.key}" v${created.version} (DRAFT).`);
+        if (publish) {
+          await definitions.publish(org.id, created.key);
+          console.log(`Published "${created.key}" v${created.version}.`);
+        }
+      },
+    );
+  } finally {
+    await app.close();
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/template/src/common/swagger/api-error-responses.ts

@@ -6,13 +6,15 @@ import {
   ApiGoneResponse,
   ApiInternalServerErrorResponse,
   ApiNotFoundResponse,
+  ApiPayloadTooLargeResponse,
   ApiServiceUnavailableResponse,
   ApiTooManyRequestsResponse,
   ApiUnauthorizedResponse,
+  ApiUnsupportedMediaTypeResponse,
 } from '@nestjs/swagger';
 import { ErrorResponseDto } from '../dto/error-response.dto';
 
-type ApiErrorStatus = 400 | 401 | 403 | 404 | 409 | 410 | 429 | 500 | 503;
+type ApiErrorStatus = 400 | 401 | 403 | 404 | 409 | 410 | 413 | 415 | 429 | 500 | 503;
 
 const errorResponseFactories = {
   400: ApiBadRequestResponse,
@@ -21,6 +23,8 @@ const errorResponseFactories = {
   404: ApiNotFoundResponse,
   409: ApiConflictResponse,
   410: ApiGoneResponse,
+  413: ApiPayloadTooLargeResponse,
+  415: ApiUnsupportedMediaTypeResponse,
   429: ApiTooManyRequestsResponse,
   500: ApiInternalServerErrorResponse,
   503: ApiServiceUnavailableResponse,
@@ -33,6 +37,8 @@ const descriptions: Record<ApiErrorStatus, string> = {
   404: 'The requested resource was not found.',
   409: 'The request conflicts with current resource state.',
   410: 'The resource is no longer available.',
+  413: 'The request payload is too large.',
+  415: 'The uploaded media type is not supported.',
   429: 'Too many requests.',
   500: 'Unexpected server error.',
   503: 'The service is temporarily unavailable.',
@@ -51,4 +57,4 @@ export function ApiErrorResponses(...statuses: ApiErrorStatus[]) {
 
 export function ApiProtectedErrorResponses(...extraStatuses: ApiErrorStatus[]) {
   return ApiErrorResponses(400, 401, 403, ...extraStatuses);
-}
+}

package/template/src/modules/forms/application/services/data-sources/conference-tracks.data-source.ts

@@ -0,0 +1,32 @@
+import { Injectable } from '@nestjs/common';
+import type {
+  DataSourceContext,
+  DataSourceDef,
+  DataSourceOption,
+} from '@ftisindia/form-builder';
+import { FormDataSource } from '../../../infrastructure/registry/form-extension.decorators';
+
+/**
+ * Example data source for src/modules/forms/examples/abstract-submission.form.json.
+ *
+ * Real apps should replace this static list with an org-scoped Prisma/API
+ * lookup using ctx.orgId. Keeping the shipped example self-contained makes
+ * the data-source registry usable immediately after scaffolding.
+ */
+@Injectable()
+@FormDataSource()
+export class ConferenceTracksDataSource implements DataSourceDef {
+  readonly key = 'conference-tracks';
+
+  fetch(
+    _params: Record<string, unknown>,
+    _ctx: DataSourceContext,
+  ): Promise<DataSourceOption[]> {
+    return Promise.resolve([
+      { value: 'clinical-research', label: 'Clinical Research' },
+      { value: 'public-health', label: 'Public Health' },
+      { value: 'biomedical-engineering', label: 'Biomedical Engineering' },
+      { value: 'data-science', label: 'Data Science' },
+    ]);
+  }
+}

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

@@ -1,7 +1,9 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import {
   BadRequestException,
-  ConflictException,
+  ConflictException,
+  HttpException,
+  HttpStatus,
   Injectable,
   NotFoundException,
   PayloadTooLargeException,
@@ -12,7 +14,12 @@ import {
   acceptSatisfied,
   walkFields,
 } from '@ftisindia/form-builder';
-import type { FieldDef, FormDefinitionRecord, UploadedFileRecord } from '@ftisindia/form-builder';
+import type {
+  FieldDef,
+  FormDefinitionRecord,
+  OrgFormsPolicy,
+  UploadedFileRecord,
+} from '@ftisindia/form-builder';
 import { AuthenticatedUser } from '../../../auth/types/authenticated-user';
 import { RequestContextService } from '../../../request-context/application/services/request-context.service';
 import { UploadFileQueryDto } from '../../dto/upload-file-query.dto';
@@ -23,15 +30,20 @@ import { LocalDiskStorageAdapter } from '../../infrastructure/storage/local-disk
 import { FormsSettingsReader } from './forms-settings-reader.service';
 
 const sniffer = new DefaultMagicByteSniffer();
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+type UploadedMultipartFile = {
+  originalname: string;
+  size: number;
+  buffer: Buffer;
+};
 
 /**
- * Upload-before-submit (design doc §10): bytes are stored here, the form
- * submission later carries only the file id. Every trust decision is
- * server-side — MIME type is sniffed from content (never the client header),
- * size is enforced against both the field's and the org's caps, sha256 is
- * computed, and the record is bound to uploader AND org (two-factor
- * ownership). Files start TEMPORARY; submit-time linking promotes to LINKED;
- * the GC sweeps the rest after the TTL.
+ * Upload-before-submit (design doc section 10): bytes are stored here, the form
+ * submission later carries only the file id. Authenticated uploads bind to the
+ * user id; public uploads bind to an anonymous claim token returned once by the
+ * public upload endpoint. Submit-time linking re-checks the same ownership or
+ * token claim before promoting the file to LINKED.
  */
 @Injectable()
 export class FormsFilesService {
@@ -48,24 +60,90 @@ export class FormsFilesService {
     orgId: string,
     formKey: string,
     query: UploadFileQueryDto,
-    file: { originalname: string; size: number; buffer: Buffer } | undefined,
+    file: UploadedMultipartFile | undefined,
     user: AuthenticatedUser,
   ) {
     this.requestContext.assertOrgScope(orgId);
+    this.assertUploadRequest(query, file);
+
+    const definition = await this.resolveTargetDefinition(orgId, formKey, query);
+    const field = this.requireFileField(definition, query.field);
+    const policy = await this.settings.policyFor(orgId);
+    const record = await this.storeUpload(orgId, field, file, policy, {
+      ownerId: user.id,
+    });
+
+    return this.toResponse(record);
+  }
+
+  async uploadPublic(
+    orgId: string,
+    formKey: string,
+    query: UploadFileQueryDto,
+    file: UploadedMultipartFile | undefined,
+  ) {
+    this.requestContext.merge({ orgId });
+    this.assertUploadRequest(query, file);
+    if (query.submissionId) {
+      throw new BadRequestException('Public uploads cannot target draft submissions.');
+    }
+
+    const definition = await this.resolvePublicDefinition(orgId, formKey, query);
+    const field = this.requireFileField(definition, query.field);
+    const policy = await this.settings.policyFor(orgId);
+    await this.enforcePublicUploadCap(orgId, policy);
+
+    const uploadToken = randomBytes(32).toString('base64url');
+    const record = await this.storeUpload(orgId, field, file, policy, {
+      ownerId: null,
+      claimTokenHash: createHash('sha256').update(uploadToken).digest('hex'),
+      uploadedIp: this.requestContext.getIpAddress() ?? null,
+    });
+
+    return { ...this.toResponse(record), uploadToken };
+  }
+
+  async getMeta(orgId: string, fileId: string) {
+    this.requestContext.assertOrgScope(orgId);
+    const record = await this.files.findById(orgId, fileId);
+    if (!record) {
+      throw new NotFoundException('File was not found.');
+    }
+    return this.toResponse(record);
+  }
+
+  /** Storage keys never leave the server. */
+  private toResponse(record: UploadedFileRecord) {
+    return {
+      fileId: record.id,
+      originalName: record.originalName,
+      mimeType: record.mimeType,
+      size: record.size,
+      checksum: record.checksum,
+      status: record.status,
+      createdAt: record.createdAt,
+    };
+  }
+
+  private assertUploadRequest(
+    query: UploadFileQueryDto,
+    file: UploadedMultipartFile | undefined,
+  ): asserts file is UploadedMultipartFile {
     if (!file || !file.buffer || file.size === 0) {
       throw new BadRequestException('A non-empty file is required (multipart field "file").');
     }
     if (!query.field) {
       throw new BadRequestException('The "field" query parameter is required.');
     }
+  }
 
-    const definition = await this.resolveTargetDefinition(orgId, formKey, query);
-    const field = this.findFileField(definition.schema.fields, query.field);
-    if (!field) {
-      throw new NotFoundException(`Form has no file field named "${query.field}".`);
-    }
-
-    const policy = await this.settings.policyFor(orgId);
+  private async storeUpload(
+    orgId: string,
+    field: FieldDef,
+    file: UploadedMultipartFile,
+    policy: OrgFormsPolicy,
+    ownership: { ownerId: string | null; claimTokenHash?: string; uploadedIp?: string | null },
+  ) {
     const capMb = Math.min(field.maxSizeMb ?? Infinity, policy.maxFileSizeMb ?? Infinity);
     if (Number.isFinite(capMb) && file.size > capMb * 1024 * 1024) {
       throw new PayloadTooLargeException(`File exceeds the ${capMb} MB limit for this field.`);
@@ -84,39 +162,38 @@ export class FormsFilesService {
     const checksum = createHash('sha256').update(file.buffer).digest('hex');
     const storageKey = `${orgId}/${randomUUID()}`;
     await this.storage.put(storageKey, file.buffer);
-    const record = await this.files.create({
+    return this.files.create({
       storageKey,
       originalName: file.originalname,
       mimeType: sniffed.mimeType,
       size: file.size,
       checksum,
-      ownerId: user.id,
+      ownerId: ownership.ownerId,
+      claimTokenHash: ownership.claimTokenHash ?? null,
+      uploadedIp: ownership.uploadedIp ?? null,
       orgId,
       status: 'TEMPORARY',
     });
-    return this.toResponse(record);
   }
 
-  async getMeta(orgId: string, fileId: string) {
-    this.requestContext.assertOrgScope(orgId);
-    const record = await this.files.findById(orgId, fileId);
-    if (!record) {
-      throw new NotFoundException('File was not found.');
+  private async enforcePublicUploadCap(orgId: string, policy: OrgFormsPolicy): Promise<void> {
+    const cap = policy.maxPublicUploadsPerIpPerDay;
+    const ipAddress = this.requestContext.getIpAddress();
+    if (!cap || cap <= 0 || !ipAddress) {
+      return;
     }
-    return this.toResponse(record);
-  }
 
-  /** Storage keys never leave the server. */
-  private toResponse(record: UploadedFileRecord) {
-    return {
-      fileId: record.id,
-      originalName: record.originalName,
-      mimeType: record.mimeType,
-      size: record.size,
-      checksum: record.checksum,
-      status: record.status,
-      createdAt: record.createdAt,
-    };
+    const count = await this.files.countPublicUploadsByIpSince(
+      orgId,
+      ipAddress,
+      new Date(Date.now() - DAY_MS),
+    );
+    if (count >= cap) {
+      throw new HttpException(
+        'Public upload limit reached. Please try again later.',
+        HttpStatus.TOO_MANY_REQUESTS,
+      );
+    }
   }
 
   private async resolveTargetDefinition(
@@ -152,6 +229,33 @@ export class FormsFilesService {
     return record;
   }
 
+  private async resolvePublicDefinition(
+    orgId: string,
+    formKey: string,
+    query: UploadFileQueryDto,
+  ): Promise<FormDefinitionRecord> {
+    const record =
+      query.version !== undefined
+        ? await this.definitions.findByKeyVersion(orgId, formKey, query.version)
+        : await this.definitions.findLatest(orgId, formKey, 'PUBLISHED');
+    if (
+      !record ||
+      record.status !== 'PUBLISHED' ||
+      (record.schema.settings?.access ?? 'private') !== 'public'
+    ) {
+      throw new NotFoundException('Form was not found.');
+    }
+    return record;
+  }
+
+  private requireFileField(definition: FormDefinitionRecord, name: string): FieldDef {
+    const field = this.findFileField(definition.schema.fields, name);
+    if (!field) {
+      throw new NotFoundException(`Form has no file field named "${name}".`);
+    }
+    return field;
+  }
+
   private findFileField(fields: FieldDef[], name: string): FieldDef | undefined {
     let found: FieldDef | undefined;
     walkFields(fields, (field) => {

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

@@ -38,7 +38,8 @@ export class FormsPublicService {
           formKey,
           version: dto.version,
           data: dto.data,
-          public: true,
+          public: true,
+          uploadTokens: dto.uploadTokens,
           captchaToken: dto.captchaToken,
         },
         this.formsContext,

package/template/src/modules/forms/application/services/forms-settings-reader.service.ts

@@ -9,7 +9,8 @@ const FORMS_SETTING_KEYS = [
   'forms.maxFileSizeMb',
   'forms.enableRuleIteration',
   'forms.virusScanRequired',
-  'forms.maxSubmissionsPerIpPerDay',
+  'forms.maxSubmissionsPerIpPerDay',
+  'forms.maxPublicUploadsPerIpPerDay',
   'forms.webhookAllowedHosts',
 ] as const;
 
@@ -18,7 +19,7 @@ const FORMS_SETTING_KEYS = [
  * setting definitions' defaults for unset keys (the SettingsService 404s on
  * unset keys, which is wrong for policy reads). The result feeds every
  * engine call that takes an OrgFormsPolicy — dangerous-action gating, rule
- * iteration, file caps, public-submission caps.
+ * iteration, file caps, public submission/upload caps.
  */
 @Injectable()
 export class FormsSettingsReader {
@@ -45,7 +46,8 @@ export class FormsSettingsReader {
       enableRuleIteration: read<boolean>('forms.enableRuleIteration'),
       maxFileSizeMb: read<number>('forms.maxFileSizeMb'),
       virusScanRequired: read<boolean>('forms.virusScanRequired'),
-      maxSubmissionsPerIpPerDay: read<number>('forms.maxSubmissionsPerIpPerDay'),
+      maxSubmissionsPerIpPerDay: read<number>('forms.maxSubmissionsPerIpPerDay'),
+      maxPublicUploadsPerIpPerDay: read<number>('forms.maxPublicUploadsPerIpPerDay'),
       webhookAllowedHosts: read<string[]>('forms.webhookAllowedHosts'),
       captchaConfigured: this.captcha != null,
     };

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,8 @@ 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';
 
 /**
@@ -61,7 +63,8 @@ import { FORMS_CAPTCHA_VERIFIER } from './forms.tokens';
     FormsDefinitionsController,
     FormsFilesController,
     FormsSubmissionsController,
-    PublicFormsController,
+    PublicFormsController,
+    PublicFormsFilesController,
   ],
   providers: [
     // Adapters over the ecosystem seams.
@@ -76,6 +79,8 @@ import { FORMS_CAPTCHA_VERIFIER } from './forms.tokens';
     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.
     {
@@ -196,6 +201,9 @@ import { FORMS_CAPTCHA_VERIFIER } from './forms.tokens';
     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/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);
+  }
+}

package/template/src/modules/settings/types/setting-definitions.ts

@@ -57,6 +57,10 @@ export const settingDefinitions = {
     defaultValue: 50,
     parse: parsePositiveInt('forms.maxSubmissionsPerIpPerDay', 100000),
   },
+  'forms.maxPublicUploadsPerIpPerDay': {
+    defaultValue: 100,
+    parse: parsePositiveInt('forms.maxPublicUploadsPerIpPerDay', 100000),
+  },
   // SSRF gate for definition webhooks: empty list = webhooks disabled until
   // an admin explicitly allows destination hosts (changes are audited).
   'forms.webhookAllowedHosts': {

package/template/test/forms-files.e2e-spec.ts

@@ -1,6 +1,5 @@
 import { INestApplication, ValidationPipe } from '@nestjs/common';
 import { Test } from '@nestjs/testing';
-import { DataSourceRegistry } from '@ftisindia/form-builder';
 import request from 'supertest';
 import { HttpExceptionFilter } from '../src/common/filters/http-exception.filter';
 import { PrismaService } from '../src/database/prisma/prisma.service';
@@ -43,16 +42,6 @@ describe('Forms file uploads (e2e)', () => {
     await app.init();
     prisma = app.get(PrismaService);
 
-    // The abstract-like definition binds a select to this source; register the
-    // stub BEFORE creating the definition so save-time lint passes.
-    app.get(DataSourceRegistry).register({
-      key: 'conference-tracks',
-      fetch: () => Promise.resolve([
-        { value: 'ai', label: 'Artificial Intelligence' },
-        { value: 'ml', label: 'Machine Learning' },
-      ]),
-    });
-
     owner = await createUserAndOrg('files-owner');
     formKey = await publishDefinition(abstractDefinition(uniqueFormKey('abstract')));
   });
@@ -87,7 +76,7 @@ describe('Forms file uploads (e2e)', () => {
     const draft = await request(app.getHttpServer())
       .post(`/organisations/${owner.orgId}/forms/${key}/submissions`)
       .set('Authorization', `Bearer ${owner.accessToken}`)
-      .send({ mode: 'draft', data: { title: 'Versioned upload', track: 'ai' } })
+      .send({ mode: 'draft', data: { title: 'Versioned upload', track: 'clinical-research' } })
       .expect(200);
 
     const createdV2 = await request(app.getHttpServer())
@@ -136,7 +125,7 @@ describe('Forms file uploads (e2e)', () => {
       .set('Authorization', `Bearer ${owner.accessToken}`)
       .send({
         mode: 'submit',
-        data: { title: 'On Linking Files', track: 'ai', manuscript: { fileId } },
+        data: { title: 'On Linking Files', track: 'clinical-research', manuscript: { fileId } },
       })
       .expect(200);
 
@@ -159,7 +148,7 @@ describe('Forms file uploads (e2e)', () => {
       .set('Authorization', `Bearer ${member.accessToken}`)
       .send({
         mode: 'submit',
-        data: { title: 'Stolen Reference', track: 'ml', manuscript: { fileId } },
+        data: { title: 'Stolen Reference', track: 'public-health', manuscript: { fileId } },
       })
       .expect(422);
 
@@ -186,15 +175,48 @@ describe('Forms file uploads (e2e)', () => {
     expect(row).toBeNull();
   });
 
-  it('refuses to flip a definition with file fields to public access', async () => {
-    const response = await request(app.getHttpServer())
-      .post(`/organisations/${owner.orgId}/forms/${formKey}/versions/1/public-access`)
+  it('accepts public uploads only with the returned claim token', async () => {
+    const key = await publishDefinition(abstractDefinition(uniqueFormKey('public-file')));
+    await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${key}/versions/1/public-access`)
       .set('Authorization', `Bearer ${owner.accessToken}`)
       .send({ access: 'public' })
+      .expect(200);
+
+    const upload = await request(app.getHttpServer())
+      .post(`/public/organisations/${owner.orgId}/forms/${key}/files`)
+      .query({ field: 'manuscript' })
+      .attach('file', PDF_BYTES, 'public-manuscript.pdf')
+      .expect(200);
+
+    const fileId = upload.body.fileId as string;
+    const uploadToken = upload.body.uploadToken as string;
+    expect(fileId).toBeTruthy();
+    expect(uploadToken).toBeTruthy();
+    expect(upload.body.status).toBe('TEMPORARY');
+
+    const rejected = await request(app.getHttpServer())
+      .post(`/public/organisations/${owner.orgId}/forms/${key}/submissions`)
+      .send({
+        data: { title: 'Missing token', track: 'clinical-research', manuscript: { fileId } },
+      })
       .expect(422);
+    const errors = rejected.body.error.details.errors as Array<{ code: string; path: string }>;
+    expect(errors.some((error) => error.code === 'FILE_REFERENCE')).toBe(true);
+
+    const submitted = await request(app.getHttpServer())
+      .post(`/public/organisations/${owner.orgId}/forms/${key}/submissions`)
+      .send({
+        data: { title: 'Public file', track: 'clinical-research', manuscript: { fileId } },
+        uploadTokens: { [fileId]: uploadToken },
+      })
+      .expect(200);
 
-    const issues = response.body.error.details.issues as Array<{ code: string }>;
-    expect(issues.map((issue) => issue.code)).toContain('PUBLIC_FILE_FIELD');
+    const submissionId = submitted.body.submissionId as string;
+    const row = await prisma.uploadedFile.findUnique({ where: { id: fileId } });
+    expect(row?.ownerId).toBeNull();
+    expect(row?.status).toBe('LINKED');
+    expect(row?.submissionId).toBe(submissionId);
   });
 
   // ── Helpers ────────────────────────────────────────────────────────────────

package/template/test/forms-submissions.e2e-spec.ts

@@ -1,6 +1,6 @@
 import { INestApplication, ValidationPipe } from '@nestjs/common';
 import { Test } from '@nestjs/testing';
-import { ActionRegistry, DataSourceRegistry } from '@ftisindia/form-builder';
+import { ActionRegistry } from '@ftisindia/form-builder';
 import request from 'supertest';
 import { HttpExceptionFilter } from '../src/common/filters/http-exception.filter';
 import { PrismaService } from '../src/database/prisma/prisma.service';
@@ -51,15 +51,6 @@ describe('Forms submissions engine flow (e2e)', () => {
       execute: (ctx) => Promise.resolve({ ...ctx.data }),
     });
 
-    const dataSources = app.get(DataSourceRegistry);
-    dataSources.register({
-      key: 'conference-tracks',
-      fetch: () => Promise.resolve([
-        { value: 'ai', label: 'Artificial Intelligence' },
-        { value: 'ml', label: 'Machine Learning' },
-      ]),
-    });
-
     owner = await createUserAndOrg('sub-owner');
   });
 
@@ -263,7 +254,7 @@ describe('Forms submissions engine flow (e2e)', () => {
     await request(app.getHttpServer())
       .post(`/organisations/${owner.orgId}/forms/${key}/submissions`)
       .set('Authorization', `Bearer ${owner.accessToken}`)
-      .send({ mode: 'submit', data: { track: 'ai' } })
+      .send({ mode: 'submit', data: { track: 'clinical-research' } })
       .expect(200);
   });
 

package/template/test/route-registry.validator.spec.ts

@@ -12,7 +12,8 @@ import { FormsDataSourcesController } from '../src/modules/forms/presentation/fo
 import { FormsDefinitionsController } from '../src/modules/forms/presentation/forms-definitions.controller';
 import { FormsFilesController } from '../src/modules/forms/presentation/forms-files.controller';
 import { FormsSubmissionsController } from '../src/modules/forms/presentation/forms-submissions.controller';
-import { PublicFormsController } from '../src/modules/forms/presentation/public-forms.controller';
+import { PublicFormsController } from '../src/modules/forms/presentation/public-forms.controller';
+import { PublicFormsFilesController } from '../src/modules/forms/presentation/public-forms-files.controller';
 import { InvitationsController } from '../src/modules/invitations/presentation/invitations.controller';
 import { MembershipsController } from '../src/modules/memberships/presentation/memberships.controller';
 import { OrganisationsController } from '../src/modules/organisations/presentation/organisations.controller';
@@ -34,7 +35,8 @@ const controllers = [
   FormsDefinitionsController,
   FormsFilesController,
   FormsSubmissionsController,
-  PublicFormsController,
+  PublicFormsController,
+  PublicFormsFilesController,
   InvitationsController,
   MembershipsController,
   OrganisationsController,