@ftisindia/create-app 0.1.4 → 0.1.6

package/template/src/modules/forms/examples/login.form.json

@@ -0,0 +1,24 @@
+{
+  "key": "login",
+  "version": 1,
+  "title": "Sign in",
+  "settings": { "access": "public" },
+  "fields": [
+    {
+      "type": "email",
+      "name": "email",
+      "label": "Email address",
+      "validators": { "required": true }
+    },
+    {
+      "type": "password",
+      "name": "password",
+      "label": "Password",
+      "validators": { "required": true, "minLength": 8 },
+      "ui": { "widget": "password" }
+    }
+  ],
+  "actions": {
+    "submit": ["authenticate"]
+  }
+}

package/template/src/modules/forms/examples/registration.form.json

@@ -0,0 +1,44 @@
+{
+  "key": "registration",
+  "version": 1,
+  "title": "Event registration",
+  "fields": [
+    {
+      "type": "text",
+      "name": "fullName",
+      "label": "Full name",
+      "validators": { "required": true, "maxLength": 120 },
+      "reportable": true
+    },
+    {
+      "type": "email",
+      "name": "email",
+      "label": "Email address",
+      "validators": { "required": true },
+      "reportable": true,
+      "indexHint": true
+    },
+    {
+      "type": "select",
+      "name": "ticketType",
+      "label": "Ticket type",
+      "validators": { "required": true, "options": ["standard", "student", "vip"] },
+      "reportable": true
+    },
+    {
+      "type": "boolean",
+      "name": "newsletter",
+      "label": "Subscribe to updates?"
+    },
+    {
+      "type": "hidden",
+      "name": "registeredBy",
+      "source": "context",
+      "path": "user.id"
+    }
+  ],
+  "actions": {
+    "submit": ["validateAll", "persist", "sendConfirmationEmail"],
+    "saveDraft": ["persistDraft"]
+  }
+}

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

@@ -0,0 +1,226 @@
+import { Module } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
+import {
+  ActionRegistry,
+  DataSourceRegistry,
+  DataSourceResolver,
+  DefinitionService,
+  FieldTypeRegistry,
+  LifecycleRegistry,
+  OutboxHandlerRegistry,
+  SubmissionService,
+  ValidationEngine,
+  registerCoreFieldTypes,
+} from '@ftisindia/form-builder';
+import { AuthModule } from '../auth/auth.module';
+import { FileGcService } from './application/services/file-gc.service';
+import { FormsDefinitionsService } from './application/services/forms-definitions.service';
+import { FormsExportService } from './application/services/forms-export.service';
+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 { 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';
+import { WebhookOutboxHandler } from './application/services/handlers/webhook.handler';
+import { OutboxDispatcherService } from './application/services/outbox-dispatcher.service';
+import { CaslFormsAuthorization } from './infrastructure/casl-forms-authorization';
+import { PrismaFormsAuditSink } from './infrastructure/audit-sink.adapter';
+import { PrismaTxRunner } from './infrastructure/prisma-tx-runner';
+import { RequestFormsContext } from './infrastructure/request-forms-context';
+import { RegistryBootstrapService } from './infrastructure/registry/registry-bootstrap.service';
+import { FormsSchemaCheckService } from './infrastructure/schema-check/forms-schema-check.service';
+import { LocalDiskStorageAdapter } from './infrastructure/storage/local-disk-storage.adapter';
+import { PrismaActionLogStore } from './infrastructure/stores/prisma-action-log.store';
+import { PrismaFileStore } from './infrastructure/stores/prisma-file.store';
+import { PrismaFormDefinitionStore } from './infrastructure/stores/prisma-form-definition.store';
+import { PrismaOutboxStore } from './infrastructure/stores/prisma-outbox.store';
+import { PrismaSubmissionStore } from './infrastructure/stores/prisma-submission.store';
+import { FormsDataSourcesController } from './presentation/forms-data-sources.controller';
+import { FormsDefinitionsController } from './presentation/forms-definitions.controller';
+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';
+
+/**
+ * The forms glue module — the ONLY place that binds the framework-free
+ * @ftisindia/form-builder engine to this app's services (request context,
+ * CASL RBAC, AuditService, Prisma). Engine services are composed here via
+ * factories over the four adapters and five stores; app extensions register
+ * through the @FormFieldType/@FormActionHandler/@FormDataSource decorators.
+ */
+@Module({
+  imports: [AuthModule, DiscoveryModule],
+  controllers: [
+    // Listed before the definitions controller so the literal 'data-sources'
+    // segment wins over the ':formKey' parameter on the shared base path.
+    FormsDataSourcesController,
+    FormsDefinitionsController,
+    FormsFilesController,
+    FormsSubmissionsController,
+    PublicFormsController,
+  ],
+  providers: [
+    // Adapters over the ecosystem seams.
+    RequestFormsContext,
+    CaslFormsAuthorization,
+    PrismaFormsAuditSink,
+    PrismaTxRunner,
+    // Prisma store implementations of the engine ports.
+    PrismaFormDefinitionStore,
+    PrismaSubmissionStore,
+    PrismaOutboxStore,
+    PrismaFileStore,
+    PrismaActionLogStore,
+    FormsSettingsReader,
+    // Engine registries — singletons; core field types registered up front.
+    {
+      provide: FieldTypeRegistry,
+      useFactory: () => {
+        const registry = new FieldTypeRegistry();
+        registerCoreFieldTypes(registry);
+        return registry;
+      },
+    },
+    { provide: ActionRegistry, useFactory: () => new ActionRegistry() },
+    { provide: DataSourceRegistry, useFactory: () => new DataSourceRegistry() },
+    { provide: LifecycleRegistry, useFactory: () => new LifecycleRegistry() },
+    { provide: OutboxHandlerRegistry, useFactory: () => new OutboxHandlerRegistry() },
+    {
+      provide: ValidationEngine,
+      useFactory: (fieldTypes: FieldTypeRegistry) => new ValidationEngine(fieldTypes),
+      inject: [FieldTypeRegistry],
+    },
+    {
+      provide: DataSourceResolver,
+      useFactory: (dataSources: DataSourceRegistry) => new DataSourceResolver(dataSources),
+      inject: [DataSourceRegistry],
+    },
+    // Engine orchestration services, composed over the adapters and stores.
+    {
+      provide: DefinitionService,
+      useFactory: (
+        store: PrismaFormDefinitionStore,
+        authz: CaslFormsAuthorization,
+        audit: PrismaFormsAuditSink,
+        txRunner: PrismaTxRunner,
+        fieldTypes: FieldTypeRegistry,
+        actions: ActionRegistry,
+        dataSources: DataSourceRegistry,
+        resolver: DataSourceResolver,
+        settings: FormsSettingsReader,
+      ) =>
+        new DefinitionService({
+          store,
+          authz,
+          audit,
+          txRunner,
+          fieldTypes,
+          actions,
+          dataSources,
+          resolver,
+          policyFor: (orgId) => settings.policyFor(orgId),
+        }),
+      inject: [
+        PrismaFormDefinitionStore,
+        CaslFormsAuthorization,
+        PrismaFormsAuditSink,
+        PrismaTxRunner,
+        FieldTypeRegistry,
+        ActionRegistry,
+        DataSourceRegistry,
+        DataSourceResolver,
+        FormsSettingsReader,
+      ],
+    },
+    {
+      provide: SubmissionService,
+      useFactory: (
+        definitions: PrismaFormDefinitionStore,
+        submissions: PrismaSubmissionStore,
+        files: PrismaFileStore,
+        outbox: PrismaOutboxStore,
+        actionLog: PrismaActionLogStore,
+        audit: PrismaFormsAuditSink,
+        txRunner: PrismaTxRunner,
+        authz: CaslFormsAuthorization,
+        fieldTypes: FieldTypeRegistry,
+        actions: ActionRegistry,
+        lifecycles: LifecycleRegistry,
+        validation: ValidationEngine,
+        resolver: DataSourceResolver,
+        settings: FormsSettingsReader,
+      ) =>
+        new SubmissionService({
+          definitions,
+          submissions,
+          files,
+          outbox,
+          actionLog,
+          audit,
+          txRunner,
+          authz,
+          fieldTypes,
+          actions,
+          lifecycles,
+          validation,
+          resolver,
+          captcha: settings.captchaVerifier,
+          policyFor: (orgId) => settings.policyFor(orgId),
+        }),
+      inject: [
+        PrismaFormDefinitionStore,
+        PrismaSubmissionStore,
+        PrismaFileStore,
+        PrismaOutboxStore,
+        PrismaActionLogStore,
+        PrismaFormsAuditSink,
+        PrismaTxRunner,
+        CaslFormsAuthorization,
+        FieldTypeRegistry,
+        ActionRegistry,
+        LifecycleRegistry,
+        ValidationEngine,
+        DataSourceResolver,
+        FormsSettingsReader,
+      ],
+    },
+    // Startup wiring + background work.
+    RegistryBootstrapService,
+    FormsSchemaCheckService,
+    OutboxDispatcherService,
+    LocalDiskStorageAdapter,
+    FileGcService,
+    FormsUploadInterceptor,
+    // Default outbox handlers + shipped form actions.
+    LoggingEmailHandler,
+    WebhookOutboxHandler,
+    AuthenticateActionHandler,
+    SendConfirmationEmailAction,
+    // Thin HTTP-facing services.
+    FormsDefinitionsService,
+    FormsSubmissionsService,
+    FormsFilesService,
+    FormsPublicService,
+    FormsExportService,
+  ],
+  exports: [
+    FieldTypeRegistry,
+    ActionRegistry,
+    DataSourceRegistry,
+    LifecycleRegistry,
+    OutboxHandlerRegistry,
+    OutboxDispatcherService,
+    // Consumed ONLY by the optional ReportsFormsModule bridge (report design
+    // §3.2/§13): the form definition store backs the form→report source
+    // adapter, and SubmissionService + the forms request context let the
+    // delegated editSubmission/updateStatus grid verbs run the form engine's
+    // own validation pipeline. ReportsModule itself imports none of this.
+    PrismaFormDefinitionStore,
+    SubmissionService,
+    RequestFormsContext,
+  ],
+})
+export class FormsModule {}

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

@@ -0,0 +1,6 @@
+/**
+ * Optional-provider tokens for the forms module's seams. Bind an
+ * implementation in your AppModule to activate the seam; absence fails
+ * closed (e.g. captcha-enabled definitions refuse to publish).
+ */
+export const FORMS_CAPTCHA_VERIFIER = 'FORMS_CAPTCHA_VERIFIER';

package/template/src/modules/forms/infrastructure/audit-sink.adapter.ts

@@ -0,0 +1,30 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import type { AuditEntry, EngineTx, FormsAuditSink } from '@ftisindia/form-builder';
+import { PrismaService } from '../../../database/prisma/prisma.service';
+import { AuditService } from '../../audit/application/services/audit.service';
+
+/**
+ * Routes engine audit entries through the template's AuditService. When the
+ * engine supplies a transaction, the audit row is written through it so it
+ * commits atomically with the change it describes (ecosystem guide §7).
+ */
+@Injectable()
+export class PrismaFormsAuditSink implements FormsAuditSink {
+  constructor(
+    private readonly audit: AuditService,
+    private readonly prisma: PrismaService,
+  ) {}
+
+  async write(entry: AuditEntry, tx?: EngineTx): Promise<void> {
+    const client = tx ? (tx as unknown as Prisma.TransactionClient) : this.prisma;
+    await this.audit.write(client, {
+      orgId: entry.orgId ?? null,
+      actorUserId: entry.actorUserId ?? null,
+      action: entry.action,
+      targetType: entry.targetType,
+      targetId: entry.targetId ?? null,
+      metadata: entry.metadata as Prisma.InputJsonValue | undefined,
+    });
+  }
+}

package/template/src/modules/forms/infrastructure/casl-forms-authorization.ts

@@ -0,0 +1,31 @@
+import { Injectable } from '@nestjs/common';
+import type { FormPermissionKey, FormsAuthorization } from '@ftisindia/form-builder';
+import { AbilityFactory } from '../../access-control/application/services/ability.factory';
+import { permissionKeyToRule } from '../../access-control/types/permission-key';
+import { RequestContextService } from '../../request-context/application/services/request-context.service';
+
+/**
+ * The engine's internal authorization seam over CASL — mirrors
+ * PermissionGuard's own logic and fails closed when no RBAC context exists
+ * (anonymous/public requests). Route guards remain the first enforcement
+ * layer; this is the defense-in-depth second layer (ecosystem guide §5.3).
+ */
+@Injectable()
+export class CaslFormsAuthorization implements FormsAuthorization {
+  constructor(
+    private readonly abilities: AbilityFactory,
+    private readonly ctx: RequestContextService,
+  ) {}
+
+  can(required: FormPermissionKey[]): boolean {
+    const rbac = this.ctx.getRbacContext();
+    if (!rbac) {
+      return false;
+    }
+    const ability = this.abilities.createForContext(rbac);
+    return required.every((key) => {
+      const { action, subject } = permissionKeyToRule(key);
+      return ability.can(action, subject);
+    });
+  }
+}

package/template/src/modules/forms/infrastructure/prisma-tx-runner.ts

@@ -0,0 +1,17 @@
+import { Injectable } from '@nestjs/common';
+import type { EngineTx, TxRunner } from '@ftisindia/form-builder';
+import { PrismaService } from '../../../database/prisma/prisma.service';
+
+/**
+ * The engine's transaction seam over PrismaService.$transaction. The opaque
+ * EngineTx brand is a Prisma.TransactionClient underneath; the stores cast it
+ * back. One TxRunner.run call IS the design doc's Phase-2 atomicity boundary.
+ */
+@Injectable()
+export class PrismaTxRunner implements TxRunner {
+  constructor(private readonly prisma: PrismaService) {}
+
+  run<T>(fn: (tx: EngineTx) => Promise<T>): Promise<T> {
+    return this.prisma.$transaction((tx) => fn(tx as unknown as EngineTx));
+  }
+}

package/template/src/modules/forms/infrastructure/registry/form-extension.decorators.ts

@@ -0,0 +1,17 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const FORM_FIELD_TYPE_METADATA = 'ftis:forms:field-type';
+export const FORM_ACTION_METADATA = 'ftis:forms:action';
+export const FORM_DATA_SOURCE_METADATA = 'ftis:forms:data-source';
+export const FORM_LIFECYCLE_METADATA = 'ftis:forms:lifecycle';
+
+/**
+ * The standardized extension story: implement the engine interface
+ * (FieldTypeDef / FormAction / DataSourceDef / FormLifecycle), decorate the
+ * @Injectable class, list it as a provider — RegistryBootstrapService
+ * discovers and registers it at startup. Same three steps for every kind.
+ */
+export const FormFieldType = () => SetMetadata(FORM_FIELD_TYPE_METADATA, true);
+export const FormActionHandler = () => SetMetadata(FORM_ACTION_METADATA, true);
+export const FormDataSource = () => SetMetadata(FORM_DATA_SOURCE_METADATA, true);
+export const FormLifecycleHook = () => SetMetadata(FORM_LIFECYCLE_METADATA, true);

package/template/src/modules/forms/infrastructure/registry/registry-bootstrap.service.ts

@@ -0,0 +1,82 @@
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import {
+  ActionRegistry,
+  DataSourceRegistry,
+  FieldTypeRegistry,
+  LifecycleRegistry,
+  OutboxHandlerRegistry,
+  ValidationEngine,
+  registerBuiltinActions,
+} from '@ftisindia/form-builder';
+import type {
+  DataSourceDef,
+  FieldTypeDef,
+  FormAction,
+  FormLifecycle,
+} from '@ftisindia/form-builder';
+import { PrismaSubmissionStore } from '../stores/prisma-submission.store';
+import { LoggingEmailHandler } from '../../application/services/handlers/logging-email.handler';
+import { WebhookOutboxHandler } from '../../application/services/handlers/webhook.handler';
+import {
+  FORM_ACTION_METADATA,
+  FORM_DATA_SOURCE_METADATA,
+  FORM_FIELD_TYPE_METADATA,
+  FORM_LIFECYCLE_METADATA,
+} from './form-extension.decorators';
+
+/**
+ * Populates the engine registries at startup: builtin actions first
+ * (validateAll/persist/persistDraft/lockEditing), the default outbox
+ * handlers, then every provider decorated with @FormFieldType /
+ * @FormActionHandler / @FormDataSource / @FormLifecycleHook — the app
+ * declares its extensions as ordinary providers; the engine finds them.
+ */
+@Injectable()
+export class RegistryBootstrapService implements OnModuleInit {
+  constructor(
+    private readonly discovery: DiscoveryService,
+    private readonly reflector: Reflector,
+    private readonly fieldTypes: FieldTypeRegistry,
+    private readonly actions: ActionRegistry,
+    private readonly dataSources: DataSourceRegistry,
+    private readonly lifecycles: LifecycleRegistry,
+    private readonly outboxHandlers: OutboxHandlerRegistry,
+    private readonly validation: ValidationEngine,
+    private readonly submissions: PrismaSubmissionStore,
+    private readonly emailHandler: LoggingEmailHandler,
+    private readonly webhookHandler: WebhookOutboxHandler,
+  ) {}
+
+  onModuleInit(): void {
+    registerBuiltinActions(this.actions, {
+      validate: (def, data, mode) => this.validation.validate(def, data, mode),
+      submissions: this.submissions,
+    });
+    this.outboxHandlers.register(this.emailHandler);
+    this.outboxHandlers.register(this.webhookHandler);
+
+    for (const wrapper of this.discovery.getProviders()) {
+      const instance: unknown = wrapper.instance;
+      if (!instance || typeof instance !== 'object') {
+        continue;
+      }
+      const ctor = instance.constructor as object | undefined;
+      if (!ctor || ctor === Object) {
+        continue;
+      }
+      if (this.reflector.get<boolean>(FORM_FIELD_TYPE_METADATA, ctor as never)) {
+        this.fieldTypes.register(instance as FieldTypeDef);
+      }
+      if (this.reflector.get<boolean>(FORM_ACTION_METADATA, ctor as never)) {
+        this.actions.register(instance as FormAction);
+      }
+      if (this.reflector.get<boolean>(FORM_DATA_SOURCE_METADATA, ctor as never)) {
+        this.dataSources.register(instance as DataSourceDef);
+      }
+      if (this.reflector.get<boolean>(FORM_LIFECYCLE_METADATA, ctor as never)) {
+        this.lifecycles.register(instance as FormLifecycle);
+      }
+    }
+  }
+}

package/template/src/modules/forms/infrastructure/request-forms-context.ts

@@ -0,0 +1,60 @@
+import { Injectable } from '@nestjs/common';
+import type { ContextPath, FormsContext } from '@ftisindia/form-builder';
+import { RequestContextService } from '../../request-context/application/services/request-context.service';
+
+/**
+ * Binds the engine's FormsContext seam to the app's AsyncLocalStorage request
+ * context. The closed ContextPath union IS the design doc's anti-tenant-leak
+ * rule for hidden fields, enforced by the type system (ecosystem guide §3).
+ */
+@Injectable()
+export class RequestFormsContext implements FormsContext {
+  constructor(private readonly ctx: RequestContextService) {}
+
+  requestId() {
+    return this.ctx.getRequestId();
+  }
+
+  source(): 'http' | 'worker' {
+    return this.ctx.get()?.source ?? 'worker';
+  }
+
+  userId() {
+    return this.ctx.getUserId();
+  }
+
+  orgId() {
+    return this.ctx.getOrgId();
+  }
+
+  permissionKeys() {
+    return this.ctx.getPermissions();
+  }
+
+  isOwner() {
+    return this.ctx.getRbacContext()?.isOwner ?? false;
+  }
+
+  assertOrgScope(orgId: string) {
+    this.ctx.assertOrgScope(orgId);
+  }
+
+  resolve(path: ContextPath) {
+    switch (path) {
+      case 'user.id':
+        return this.ctx.getUserId();
+      case 'org.id':
+        return this.ctx.getOrgId();
+      case 'request.id':
+        return this.ctx.getRequestId();
+    }
+  }
+
+  ipAddress() {
+    return this.ctx.getIpAddress();
+  }
+
+  userAgent() {
+    return this.ctx.getUserAgent();
+  }
+}

package/template/src/modules/forms/infrastructure/schema-check/forms-schema-check.service.ts

@@ -0,0 +1,76 @@
+import { Injectable, Logger, OnApplicationBootstrap } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Prisma } from '@prisma/client';
+import {
+  ENGINE_SCHEMA_VERSION,
+  EXPECTED_FORMS_SCHEMA,
+  FORMS_PRISMA_SNIPPET_PATH,
+} from '@ftisindia/form-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+
+/**
+ * Boot-time schema compatibility check (ecosystem guide §10.1): the app owns
+ * schema.prisma and migrations; the engine ships the canonical snippet and a
+ * tables/columns manifest. On mismatch the app fails fast at startup with an
+ * actionable message instead of crashing mid-request with a cryptic Prisma
+ * error. Escape hatch: FORMS_SCHEMA_CHECK=off.
+ */
+@Injectable()
+export class FormsSchemaCheckService implements OnApplicationBootstrap {
+  private readonly logger = new Logger('FormsSchemaCheck');
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly config: ConfigService,
+  ) {}
+
+  async onApplicationBootstrap(): Promise<void> {
+    if (this.config.get<string>('forms.schemaCheck') === 'off') {
+      this.logger.warn('Forms schema check is disabled (FORMS_SCHEMA_CHECK=off).');
+      return;
+    }
+    await this.check();
+    this.logger.log(`Forms schema check passed (engine schema version ${ENGINE_SCHEMA_VERSION}).`);
+  }
+
+  async check(): Promise<void> {
+    const tables = EXPECTED_FORMS_SCHEMA.map((expected) => expected.table);
+    const rows = await this.prisma.$queryRaw<Array<{ table_name: string; column_name: string }>>`
+      SELECT table_name, column_name
+      FROM information_schema.columns
+      WHERE table_schema = current_schema()
+        AND table_name IN (${Prisma.join(tables)})
+    `;
+
+    const present = new Map<string, Set<string>>();
+    for (const row of rows) {
+      const columns = present.get(row.table_name) ?? new Set<string>();
+      columns.add(row.column_name);
+      present.set(row.table_name, columns);
+    }
+
+    const problems: string[] = [];
+    for (const expected of EXPECTED_FORMS_SCHEMA) {
+      const columns = present.get(expected.table);
+      if (!columns) {
+        problems.push(`missing table "${expected.table}"`);
+        continue;
+      }
+      const missingColumns = expected.columns.filter((column) => !columns.has(column));
+      if (missingColumns.length > 0) {
+        problems.push(`table "${expected.table}" is missing column(s): ${missingColumns.join(', ')}`);
+      }
+    }
+
+    if (problems.length > 0) {
+      throw new Error(
+        [
+          `The database does not match @ftisindia/form-builder engine schema version ${ENGINE_SCHEMA_VERSION}:`,
+          ...problems.map((problem) => `  - ${problem}`),
+          `Fix: copy the canonical models from "${FORMS_PRISMA_SNIPPET_PATH}" (in node_modules) into prisma/schema.prisma and run "npx prisma migrate dev".`,
+          'To bypass temporarily (NOT recommended), set FORMS_SCHEMA_CHECK=off.',
+        ].join('\n'),
+      );
+    }
+  }
+}

package/template/src/modules/forms/infrastructure/storage/local-disk-storage.adapter.ts

@@ -0,0 +1,43 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, resolve, sep } from 'node:path';
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import type { FileStoragePort } from '@ftisindia/form-builder';
+
+/**
+ * Default byte storage under FORMS_FILE_STORAGE_DIR. Storage keys are always
+ * server-generated (orgId/uuid — never client-controlled names), and the
+ * resolved path is verified to stay inside the base directory as defense in
+ * depth against traversal. Swap this provider for an S3/GCS adapter without
+ * touching the engine.
+ */
+@Injectable()
+export class LocalDiskStorageAdapter implements FileStoragePort {
+  private readonly baseDir: string;
+
+  constructor(config: ConfigService) {
+    this.baseDir = resolve(config.get<string>('forms.storageDir') ?? './var/uploads');
+  }
+
+  async put(storageKey: string, bytes: Uint8Array): Promise<void> {
+    const path = this.fullPath(storageKey);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, bytes);
+  }
+
+  async get(storageKey: string): Promise<Uint8Array> {
+    return readFile(this.fullPath(storageKey));
+  }
+
+  async delete(storageKey: string): Promise<void> {
+    await rm(this.fullPath(storageKey), { force: true });
+  }
+
+  private fullPath(storageKey: string): string {
+    const path = resolve(this.baseDir, storageKey);
+    if (path !== this.baseDir && !path.startsWith(this.baseDir + sep)) {
+      throw new Error('Storage key resolves outside the configured storage directory.');
+    }
+    return path;
+  }
+}

package/template/src/modules/forms/infrastructure/stores/index.ts

@@ -0,0 +1,5 @@
+export * from './prisma-action-log.store';
+export * from './prisma-file.store';
+export * from './prisma-form-definition.store';
+export * from './prisma-outbox.store';
+export * from './prisma-submission.store';