@ftisindia/create-app 0.1.4 → 0.1.6

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

@@ -0,0 +1,210 @@
+import { ForbiddenException, Injectable, NotFoundException } from '@nestjs/common';
+import { FieldTypeRegistry } from '@ftisindia/form-builder';
+import type { FieldDef, FormDefinition, SubmissionRecord } from '@ftisindia/form-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+import { AuditService } from '../../../audit/application/services/audit.service';
+import { AuthenticatedUser } from '../../../auth/types/authenticated-user';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { ExportSubmissionsQueryDto } from '../../dto/export-submissions-query.dto';
+import { PrismaFormDefinitionStore } from '../../infrastructure/stores/prisma-form-definition.store';
+import { PrismaSubmissionStore } from '../../infrastructure/stores/prisma-submission.store';
+
+const BASE_COLUMNS = ['id', 'formVersion', 'status', 'createdBy', 'createdAt'] as const;
+
+export interface ExportResult {
+  format: 'csv' | 'json';
+  columns: string[];
+  rows: Array<Record<string, unknown>>;
+  csv?: string;
+}
+
+/**
+ * Submission export — PII egress, treated accordingly (ecosystem guide §7):
+ * gated by formSubmissions.export (never implied by .read at the route), and
+ * EVERY export writes an audit row recording form key, filters, row count,
+ * and included fields — including empty results. Field selection defaults to
+ * the definitions' `reportable` manifest (design doc §15), computed
+ * version-aware across the versions present in the result set; sensitive and
+ * credential-typed fields are refused even when requested explicitly.
+ */
+@Injectable()
+export class FormsExportService {
+  constructor(
+    private readonly definitions: PrismaFormDefinitionStore,
+    private readonly submissions: PrismaSubmissionStore,
+    private readonly audit: AuditService,
+    private readonly prisma: PrismaService,
+    private readonly requestContext: RequestContextService,
+    private readonly fieldTypes: FieldTypeRegistry,
+  ) {}
+
+  async export(
+    orgId: string,
+    formKey: string,
+    query: ExportSubmissionsQueryDto,
+    user: AuthenticatedUser,
+  ): Promise<ExportResult> {
+    this.requestContext.assertOrgScope(orgId);
+
+    const latest = await this.definitions.findLatest(orgId, formKey);
+    if (!latest) {
+      throw new NotFoundException('Form was not found.');
+    }
+
+    const filters = {
+      status: query.status,
+      createdFrom: query.from ? new Date(query.from) : undefined,
+      createdTo: query.to ? new Date(query.to) : undefined,
+    };
+    const rows = await this.submissions.listForExport(orgId, formKey, filters);
+
+    const versions = [...new Set([latest.version, ...rows.map((row) => row.formVersion)])];
+    const schemas: FormDefinition[] = [latest.schema];
+    for (const version of versions) {
+      if (version === latest.version) {
+        continue;
+      }
+      const record = await this.definitions.findByKeyVersion(orgId, formKey, version);
+      if (record) {
+        schemas.push(record.schema);
+      }
+    }
+
+    const { reportable, sensitive } = this.fieldManifest(schemas);
+    const requested = query.fields
+      ? query.fields.split(',').map((field) => field.trim()).filter(Boolean)
+      : undefined;
+    if (requested) {
+      const refused = requested.filter((field) => sensitive.has(field));
+      if (refused.length > 0) {
+        throw new ForbiddenException(
+          `Sensitive fields can never be exported: ${refused.join(', ')}.`,
+        );
+      }
+    }
+    const dataColumns = (requested ?? [...reportable]).filter((field) => !sensitive.has(field));
+    const columns = [...BASE_COLUMNS, ...dataColumns];
+
+    const flatRows = rows.map((row) => this.flatten(row, dataColumns));
+    const format = query.format ?? 'json';
+    const result: ExportResult = { format, columns, rows: flatRows };
+    if (format === 'csv') {
+      result.csv = this.toCsv(columns, flatRows);
+    }
+
+    await this.audit.write(this.prisma, {
+      orgId,
+      actorUserId: user.id,
+      action: 'formSubmissions.export',
+      targetType: 'FormDefinition',
+      targetId: latest.id,
+      metadata: {
+        formKey,
+        filters: {
+          status: query.status ?? null,
+          from: query.from ?? null,
+          to: query.to ?? null,
+        },
+        rowCount: rows.length,
+        fields: dataColumns,
+        format,
+      },
+    });
+
+    return result;
+  }
+
+  /** Version-aware union of reportable field names; sensitive set across ALL versions. */
+  private fieldManifest(schemas: FormDefinition[]) {
+    const reportable = new Set<string>();
+    const sensitive = new Set<string>();
+    for (const schema of schemas) {
+      this.collectFieldManifest(schema.fields, [], false, reportable, sensitive);
+    }
+    return { reportable, sensitive };
+  }
+
+  private collectFieldManifest(
+    fields: FieldDef[],
+    parentPath: string[],
+    inheritedSensitive: boolean,
+    reportable: Set<string>,
+    sensitive: Set<string>,
+  ): boolean {
+    let subtreeHasSensitive = false;
+    for (const field of fields) {
+      const path = [...parentPath, field.name];
+      const dotted = path.join('.');
+      const ownSensitive = inheritedSensitive || this.isSensitiveField(field);
+      if (field.reportable === true) {
+        reportable.add(dotted);
+      }
+
+      const childHasSensitive =
+        field.fields && field.fields.length > 0
+          ? this.collectFieldManifest(
+              field.fields,
+              path,
+              ownSensitive,
+              reportable,
+              sensitive,
+            )
+          : false;
+
+      if (ownSensitive || childHasSensitive) {
+        sensitive.add(dotted);
+        sensitive.add(field.name);
+        subtreeHasSensitive = true;
+      }
+    }
+    return subtreeHasSensitive;
+  }
+
+  private isSensitiveField(field: FieldDef): boolean {
+    return field.sensitive === true || this.fieldTypes.get(field.type)?.alwaysSensitive === true;
+  }
+
+  private flatten(row: SubmissionRecord, dataColumns: string[]): Record<string, unknown> {
+    const flat: Record<string, unknown> = {
+      id: row.id,
+      formVersion: row.formVersion,
+      status: row.status,
+      createdBy: row.createdBy ?? null,
+      createdAt: row.createdAt.toISOString(),
+    };
+    for (const column of dataColumns) {
+      const value = this.valueAtPath(row.data, column);
+      flat[column] =
+        value !== null && typeof value === 'object' ? JSON.stringify(value) : (value ?? null);
+    }
+    return flat;
+  }
+
+  private valueAtPath(data: Record<string, unknown>, dotted: string): unknown {
+    let current: unknown = data;
+    for (const segment of dotted.split('.')) {
+      if (current === null || typeof current !== 'object' || Array.isArray(current)) {
+        return undefined;
+      }
+      current = (current as Record<string, unknown>)[segment];
+    }
+    return current;
+  }
+
+  private toCsv(columns: string[], rows: Array<Record<string, unknown>>): string {
+    const escape = (value: unknown): string => {
+      if (value === null || value === undefined) {
+        return '';
+      }
+      // flatten() already stringifies objects; this branch is type-level only.
+      const text =
+        typeof value === 'object' ? JSON.stringify(value) : String(value as string | number);
+      return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+    };
+    const lines = [columns.map(escape).join(',')];
+    for (const row of rows) {
+      lines.push(columns.map((column) => escape(row[column])).join(','));
+    }
+    return lines.join('\r\n');
+  }
+}

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

@@ -0,0 +1,164 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  BadRequestException,
+  ConflictException,
+  Injectable,
+  NotFoundException,
+  PayloadTooLargeException,
+  UnsupportedMediaTypeException,
+} from '@nestjs/common';
+import {
+  DefaultMagicByteSniffer,
+  acceptSatisfied,
+  walkFields,
+} from '@ftisindia/form-builder';
+import type { FieldDef, FormDefinitionRecord, 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';
+import { PrismaFileStore } from '../../infrastructure/stores/prisma-file.store';
+import { PrismaFormDefinitionStore } from '../../infrastructure/stores/prisma-form-definition.store';
+import { PrismaSubmissionStore } from '../../infrastructure/stores/prisma-submission.store';
+import { LocalDiskStorageAdapter } from '../../infrastructure/storage/local-disk-storage.adapter';
+import { FormsSettingsReader } from './forms-settings-reader.service';
+
+const sniffer = new DefaultMagicByteSniffer();
+
+/**
+ * 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.
+ */
+@Injectable()
+export class FormsFilesService {
+  constructor(
+    private readonly definitions: PrismaFormDefinitionStore,
+    private readonly submissions: PrismaSubmissionStore,
+    private readonly files: PrismaFileStore,
+    private readonly storage: LocalDiskStorageAdapter,
+    private readonly settings: FormsSettingsReader,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async upload(
+    orgId: string,
+    formKey: string,
+    query: UploadFileQueryDto,
+    file: { originalname: string; size: number; buffer: Buffer } | undefined,
+    user: AuthenticatedUser,
+  ) {
+    this.requestContext.assertOrgScope(orgId);
+    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);
+    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.`);
+    }
+
+    const sniffed = sniffer.sniff(file.buffer);
+    if (!sniffed) {
+      throw new UnsupportedMediaTypeException('The file type could not be determined.');
+    }
+    if (!acceptSatisfied(field.accept, sniffed.mimeType)) {
+      throw new UnsupportedMediaTypeException(
+        `Detected type "${sniffed.mimeType}" is not accepted for this field.`,
+      );
+    }
+
+    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({
+      storageKey,
+      originalName: file.originalname,
+      mimeType: sniffed.mimeType,
+      size: file.size,
+      checksum,
+      ownerId: user.id,
+      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.');
+    }
+    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 async resolveTargetDefinition(
+    orgId: string,
+    formKey: string,
+    query: UploadFileQueryDto,
+  ): Promise<FormDefinitionRecord> {
+    let version = query.version;
+
+    if (query.submissionId) {
+      const submission = await this.submissions.findById(orgId, query.submissionId);
+      if (!submission || submission.formKey !== formKey) {
+        throw new NotFoundException('Draft submission was not found.');
+      }
+      if (submission.status !== 'DRAFT') {
+        throw new ConflictException('Files can only be uploaded for editable draft submissions.');
+      }
+      if (version !== undefined && version !== submission.formVersion) {
+        throw new ConflictException(
+          'Upload version does not match the draft submission version.',
+        );
+      }
+      version = submission.formVersion;
+    }
+
+    const record =
+      version !== undefined
+        ? await this.definitions.findByKeyVersion(orgId, formKey, version)
+        : await this.definitions.findLatest(orgId, formKey, 'PUBLISHED');
+    if (!record || record.status !== 'PUBLISHED') {
+      throw new NotFoundException('Form was not found.');
+    }
+    return record;
+  }
+
+  private findFileField(fields: FieldDef[], name: string): FieldDef | undefined {
+    let found: FieldDef | undefined;
+    walkFields(fields, (field) => {
+      if (!found && field.type === 'file' && field.name === name) {
+        found = field;
+      }
+    });
+    return found;
+  }
+}

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

@@ -0,0 +1,49 @@
+import { Injectable } from '@nestjs/common';
+import { DefinitionService, SubmissionService } from '@ftisindia/form-builder';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { PublicSubmitFormDto } from '../../dto/public-submit-form.dto';
+import { RequestFormsContext } from '../../infrastructure/request-forms-context';
+import { withFormsErrorMapping } from './forms-error.mapper';
+
+/**
+ * The anonymous path (ecosystem guide §5.4). No membership, no permission
+ * keys: access is decided per definition (settings.access === 'public',
+ * checked dynamically — a private form answers 404, indistinguishable from
+ * missing). orgId comes from the route path; the engine enforces captcha and
+ * the per-IP/day cap, and stamps ip/ua on the stored submission.
+ */
+@Injectable()
+export class FormsPublicService {
+  constructor(
+    private readonly definitions: DefinitionService,
+    private readonly submissions: SubmissionService,
+    private readonly formsContext: RequestFormsContext,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async render(orgId: string, formKey: string) {
+    this.requestContext.merge({ orgId });
+    const result = await withFormsErrorMapping(() =>
+      this.definitions.getForRender({ orgId, key: formKey, public: true }, this.formsContext),
+    );
+    return { definition: result.definition, options: result.options };
+  }
+
+  async submit(orgId: string, formKey: string, dto: PublicSubmitFormDto) {
+    this.requestContext.merge({ orgId });
+    const result = await withFormsErrorMapping(() =>
+      this.submissions.submit(
+        {
+          orgId,
+          formKey,
+          version: dto.version,
+          data: dto.data,
+          public: true,
+          captchaToken: dto.captchaToken,
+        },
+        this.formsContext,
+      ),
+    );
+    return { submissionId: result.submissionId ?? null, outputs: result.outputs };
+  }
+}

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

@@ -0,0 +1,53 @@
+import { Inject, Injectable, Optional } from '@nestjs/common';
+import type { CaptchaVerifier, OrgFormsPolicy } from '@ftisindia/form-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+import { settingDefinitions } from '../../../settings/types/setting-definitions';
+import { FORMS_CAPTCHA_VERIFIER } from '../../forms.tokens';
+
+const FORMS_SETTING_KEYS = [
+  'forms.allowedDangerousActions',
+  'forms.maxFileSizeMb',
+  'forms.enableRuleIteration',
+  'forms.virusScanRequired',
+  'forms.maxSubmissionsPerIpPerDay',
+  'forms.webhookAllowedHosts',
+] as const;
+
+/**
+ * Reads the org's forms policy from typed settings, falling back to the
+ * 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.
+ */
+@Injectable()
+export class FormsSettingsReader {
+  constructor(
+    private readonly prisma: PrismaService,
+    @Optional() @Inject(FORMS_CAPTCHA_VERIFIER) private readonly captcha?: CaptchaVerifier,
+  ) {}
+
+  get captchaVerifier(): CaptchaVerifier | undefined {
+    return this.captcha ?? undefined;
+  }
+
+  async policyFor(orgId: string): Promise<OrgFormsPolicy> {
+    const rows = await this.prisma.organisationSetting.findMany({
+      where: { orgId, key: { in: [...FORMS_SETTING_KEYS] } },
+      select: { key: true, value: true },
+    });
+    const values = new Map(rows.map((row) => [row.key, row.value as unknown]));
+    const read = <T>(key: (typeof FORMS_SETTING_KEYS)[number]): T =>
+      (values.has(key) ? values.get(key) : settingDefinitions[key].defaultValue) as T;
+
+    return {
+      allowedDangerousActions: read<string[]>('forms.allowedDangerousActions'),
+      enableRuleIteration: read<boolean>('forms.enableRuleIteration'),
+      maxFileSizeMb: read<number>('forms.maxFileSizeMb'),
+      virusScanRequired: read<boolean>('forms.virusScanRequired'),
+      maxSubmissionsPerIpPerDay: read<number>('forms.maxSubmissionsPerIpPerDay'),
+      webhookAllowedHosts: read<string[]>('forms.webhookAllowedHosts'),
+      captchaConfigured: this.captcha != null,
+    };
+  }
+}

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

@@ -0,0 +1,103 @@
+import { Injectable } from '@nestjs/common';
+import { SubmissionService } from '@ftisindia/form-builder';
+import type { SubmissionRecord, SubmitArgs } from '@ftisindia/form-builder';
+import { resolvePageLimit, toPage } from '../../../../common/dto/pagination-query.dto';
+import { AuthenticatedUser } from '../../../auth/types/authenticated-user';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { ListSubmissionsQueryDto } from '../../dto/list-submissions-query.dto';
+import { SubmitFormDto } from '../../dto/submit-form.dto';
+import { ValidateSubmissionDto } from '../../dto/validate-submission.dto';
+import { RequestFormsContext } from '../../infrastructure/request-forms-context';
+import { withFormsErrorMapping } from './forms-error.mapper';
+
+/**
+ * Thin HTTP-facing wrapper over the engine's SubmissionService: org-scope
+ * assertion first, engine call through the FormsContext seam, engine-typed
+ * errors mapped onto the app's HTTP envelope. The submitter's identity flows
+ * through the request context, never through the payload.
+ */
+@Injectable()
+export class FormsSubmissionsService {
+  constructor(
+    private readonly engine: SubmissionService,
+    private readonly formsContext: RequestFormsContext,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async submit(orgId: string, formKey: string, dto: SubmitFormDto, _user: AuthenticatedUser) {
+    this.requestContext.assertOrgScope(orgId);
+
+    const args: SubmitArgs = {
+      orgId,
+      formKey,
+      version: dto.version,
+      data: dto.data,
+      button: dto.button,
+      submissionId: dto.submissionId,
+    };
+
+    const result = await withFormsErrorMapping(() =>
+      dto.mode === 'draft'
+        ? this.engine.saveDraft(args, this.formsContext)
+        : this.engine.submit(args, this.formsContext),
+    );
+
+    return { submissionId: result.submissionId ?? null, outputs: result.outputs };
+  }
+
+  async validate(orgId: string, formKey: string, dto: ValidateSubmissionDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.validateOnly(
+        { orgId, formKey, version: dto.version, data: dto.data, mode: dto.mode },
+        this.formsContext,
+      ),
+    );
+  }
+
+  async list(orgId: string, formKey: string, query: ListSubmissionsQueryDto) {
+    this.requestContext.assertOrgScope(orgId);
+    const limit = resolvePageLimit(query.limit);
+
+    const records = await withFormsErrorMapping(() =>
+      this.engine.list(
+        {
+          orgId,
+          formKey,
+          filters: { status: query.status, cursor: query.cursor, limit: limit + 1 },
+        },
+        this.formsContext,
+      ),
+    );
+
+    const page = toPage(records, limit);
+    return { items: page.items.map((record) => this.toResponse(record)), nextCursor: page.nextCursor };
+  }
+
+  async get(orgId: string, submissionId: string) {
+    this.requestContext.assertOrgScope(orgId);
+    const record = await withFormsErrorMapping(() =>
+      this.engine.get({ orgId, submissionId }, this.formsContext),
+    );
+    return this.toResponse(record);
+  }
+
+  /**
+   * Explicit field map — never serialize the raw record: ipAddress/userAgent
+   * are abuse-control telemetry, not data for formSubmissions.read holders.
+   */
+  private toResponse(record: SubmissionRecord) {
+    return {
+      id: record.id,
+      orgId: record.orgId,
+      formKey: record.formKey,
+      formVersion: record.formVersion,
+      data: record.data,
+      status: record.status,
+      locked: record.locked,
+      createdBy: record.createdBy ?? null,
+      createdAt: record.createdAt,
+      updatedAt: record.updatedAt,
+    };
+  }
+}

package/template/src/modules/forms/application/services/handlers/authenticate.action.ts

@@ -0,0 +1,37 @@
+import { Injectable } from '@nestjs/common';
+import type { ActionContext, FormAction } from '@ftisindia/form-builder';
+import { FormsValidationError } from '@ftisindia/form-builder';
+import { AuthService } from '../../../../auth/application/services/auth.service';
+import { FormActionHandler } from '../../../infrastructure/registry/form-extension.decorators';
+
+/**
+ * "Login is just a form whose submit action authenticates" (design doc §13):
+ * this action delegates to the template's real AuthService — hashing, token
+ * issuance, throttling all stay where they belong. It is `dangerous`, so
+ * wiring it into a definition requires forms.wireDangerous AND membership in
+ * the org's forms.allowedDangerousActions setting; being dangerous also means
+ * its input/output are never written to the action log (token redaction).
+ * The definition linter additionally rejects pipelines that combine
+ * `authenticate` with `persist` — credentials are never stored.
+ */
+@Injectable()
+@FormActionHandler()
+export class AuthenticateActionHandler implements FormAction {
+  readonly name = 'authenticate';
+  readonly kind = 'transactional' as const;
+  readonly dangerous = true;
+
+  constructor(private readonly auth: AuthService) {}
+
+  async execute(ctx: ActionContext): Promise<unknown> {
+    const { email, password } = ctx.data as { email?: unknown; password?: unknown };
+    if (typeof email !== 'string' || typeof password !== 'string' || !email || !password) {
+      throw new FormsValidationError([
+        { path: 'email', code: 'REQUIRED', message: 'Email and password are required.' },
+      ]);
+    }
+    // Returned opaquely: the pipeline result carries the auth module's token
+    // payload to the caller; the action log records only '[REDACTED]'.
+    return this.auth.login({ email, password });
+  }
+}

package/template/src/modules/forms/application/services/handlers/logging-email.handler.ts

@@ -0,0 +1,22 @@
+import { Injectable, Logger } from '@nestjs/common';
+import type { OutboxJobHandler, OutboxJobRecord } from '@ftisindia/form-builder';
+
+/**
+ * The default email seam: the template ships no mailer, so delivered form
+ * emails are logged instead of sent. Replace this handler (same type:
+ * 'email') with a real adapter — SES, SMTP, Resend — without touching the
+ * engine or the outbox flow; retries/backoff/parking already apply.
+ */
+@Injectable()
+export class LoggingEmailHandler implements OutboxJobHandler {
+  readonly type = 'email';
+  private readonly logger = new Logger('FormsEmailSeam');
+
+  handle(job: OutboxJobRecord): Promise<void> {
+    const { to, template } = job.payload as { to?: unknown; template?: unknown };
+    this.logger.log(
+      `Email seam (no mailer configured) — would send template "${String(template)}" to "${String(to)}" (job ${job.id}).`,
+    );
+    return Promise.resolve();
+  }
+}

package/template/src/modules/forms/application/services/handlers/send-confirmation-email.action.ts

@@ -0,0 +1,40 @@
+import { Injectable } from '@nestjs/common';
+import type { ActionContext, FormAction } from '@ftisindia/form-builder';
+import { FormActionHandler } from '../../../infrastructure/registry/form-extension.decorators';
+
+/**
+ * Post-commit confirmation email. Does NOT send inline: it enqueues an
+ * outbox job through ctx.enqueue (written in the same transaction as the
+ * submission), and the dispatcher delivers after commit with retries — the
+ * design doc §8.3 contract. Expects the form to have an `email` field; when
+ * absent the action is a no-op rather than an error, so authors can wire it
+ * unconditionally.
+ */
+@Injectable()
+@FormActionHandler()
+export class SendConfirmationEmailAction implements FormAction {
+  readonly name = 'sendConfirmationEmail';
+  readonly kind = 'post-commit' as const;
+  readonly dangerous = false;
+
+  async execute(ctx: ActionContext): Promise<unknown> {
+    const to = ctx.data.email;
+    if (typeof to !== 'string' || to.length === 0) {
+      return { queued: false, reason: 'no email field in submission' };
+    }
+    await ctx.enqueue({
+      type: 'email',
+      payload: {
+        to,
+        template: 'form-submission-received',
+        data: {
+          formKey: ctx.definitionRecord.key,
+          formVersion: ctx.definitionRecord.version,
+          submissionId: ctx.submissionId ?? null,
+          title: typeof ctx.data.title === 'string' ? ctx.data.title : undefined,
+        },
+      },
+    });
+    return { queued: true };
+  }
+}