@ftisindia/create-app 0.1.4 → 0.1.6

package/template/src/modules/access-control/dto/access-control-response.dto.ts

@@ -20,6 +20,7 @@ export class PermissionResponseDto {
   subject!: string;
 
   @ApiPropertyOptional({
+    type: String,
     example: 'Read organisation memberships.',
     nullable: true,
   })
@@ -57,6 +58,7 @@ export class RoleResponseDto {
   name!: string;
 
   @ApiPropertyOptional({
+    type: String,
     example: 'Can review support-facing records.',
     nullable: true,
   })
@@ -83,6 +85,7 @@ export class RoleListResponseDto {
   items!: RoleResponseDto[];
 
   @ApiPropertyOptional({
+    type: String,
     example: 'f602c057-04f4-4ef8-8c84-1b7c62fbf8c5',
     format: 'uuid',
     nullable: true,

package/template/src/modules/access-control/dto/current-access-control-response.dto.ts

@@ -0,0 +1,35 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { PermissionKey, permissionKeys } from '../types/permission-key';
+
+export class CurrentAccessControlResponseDto {
+  @ApiProperty({
+    example: '2c67399d-670c-4025-a5fd-1ea9a211891e',
+    format: 'uuid',
+  })
+  orgId!: string;
+
+  @ApiProperty({
+    example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
+    format: 'uuid',
+  })
+  membershipId!: string;
+
+  @ApiProperty({
+    example: 'f602c057-04f4-4ef8-8c84-1b7c62fbf8c5',
+    format: 'uuid',
+  })
+  roleId!: string;
+
+  @ApiProperty({ example: true })
+  isOwner!: boolean;
+
+  @ApiProperty({ example: true })
+  isBillingContact!: boolean;
+
+  @ApiProperty({
+    enum: permissionKeys,
+    isArray: true,
+    example: ['organisations.read', 'settings.read'],
+  })
+  permissionKeys!: PermissionKey[];
+}

package/template/src/modules/access-control/presentation/current-access-control.controller.ts

@@ -0,0 +1,40 @@
+import { Controller, Get, Param, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiOkResponse, ApiOperation, ApiParam, ApiTags } from '@nestjs/swagger';
+import { ApiProtectedErrorResponses } from '../../../common/swagger/api-error-responses';
+import { JwtAuthGuard } from '../../auth/infrastructure/passport/jwt-auth.guard';
+import { CurrentUser } from '../../auth/presentation/current-user.decorator';
+import { AuthenticatedUser } from '../../auth/types/authenticated-user';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { RbacCacheService } from '../application/services/rbac-cache.service';
+import { CurrentAccessControlResponseDto } from '../dto/current-access-control-response.dto';
+
+@ApiTags('Access control')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiProtectedErrorResponses()
+@Controller('organisations/:orgId/access-control')
+@UseGuards(JwtAuthGuard, OrgScopeGuard)
+export class CurrentAccessControlController {
+  constructor(private readonly rbacCache: RbacCacheService) {}
+
+  @Get('me')
+  @ApiOperation({
+    summary: "Return the current user's effective RBAC context for the organisation.",
+  })
+  @ApiOkResponse({
+    description: 'Effective access-control context.',
+    type: CurrentAccessControlResponseDto,
+  })
+  async me(@CurrentUser() user: AuthenticatedUser, @Param('orgId') orgId: string) {
+    const context = await this.rbacCache.getContext(user.id, orgId);
+
+    return {
+      orgId: context.orgId,
+      membershipId: context.membershipId,
+      roleId: context.roleId,
+      isOwner: context.isOwner,
+      isBillingContact: context.isBillingContact,
+      permissionKeys: context.permissionKeys,
+    };
+  }
+}

package/template/src/modules/access-control/types/permission-key.ts

@@ -17,6 +17,33 @@ export const permissionKeys = [
   'settings.update',
   'audit.read',
   'platform.admin',
+  // Form builder (@ftisindia/form-builder). Kept as literals so the as-const
+  // tuple stays narrow; test/forms-permission-sync.spec.ts asserts these match
+  // the engine's FORM_PERMISSION_KEYS export exactly.
+  'forms.read',
+  'forms.create',
+  'forms.update',
+  'forms.publish',
+  'forms.archive',
+  'forms.wireDangerous',
+  'forms.managePublicAccess',
+  'formSubmissions.read',
+  'formSubmissions.create',
+  // Row-level edits delegated from report grids (report design §6.1) — and any
+  // other surface that patches submissions through the form engine.
+  'formSubmissions.update',
+  'formSubmissions.export',
+  'formDataSources.manage',
+  // Report builder (@ftisindia/report-builder). Kept as literals so the
+  // as-const tuple stays narrow; test/reports-permission-sync.spec.ts asserts
+  // these match the engine's REPORT_PERMISSION_KEYS export exactly.
+  'reports.read',
+  'reports.create',
+  'reports.update',
+  'reports.publish',
+  'reports.archive',
+  'reports.export',
+  'reportTags.manage',
 ] as const;
 
 export type PermissionKey = (typeof permissionKeys)[number];

package/template/src/modules/access-control/types/route-permission-registry.ts

@@ -126,4 +126,187 @@ export const routePermissionRegistry: RoutePermissionEntry[] = [
     path: '/organisations/:orgId/sample/echo',
     permissions: ['organisations.update'],
   },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/forms',
+    permissions: ['forms.read'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/forms',
+    permissions: ['forms.create'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/forms/:formKey',
+    permissions: ['forms.read'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/forms/:formKey/render',
+    permissions: ['formSubmissions.create'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/forms/:formKey/versions/:version',
+    permissions: ['forms.read'],
+  },
+  {
+    method: 'PATCH',
+    path: '/organisations/:orgId/forms/:formKey/versions/:version',
+    permissions: ['forms.update'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/forms/:formKey/versions/:version/publish',
+    permissions: ['forms.publish'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/forms/:formKey/versions/:version/archive',
+    permissions: ['forms.archive'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/forms/:formKey/versions/:version/public-access',
+    permissions: ['forms.managePublicAccess'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/forms/:formKey/submissions',
+    permissions: ['formSubmissions.create'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/forms/:formKey/submissions/validate',
+    permissions: ['formSubmissions.create'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/forms/:formKey/submissions',
+    permissions: ['formSubmissions.read'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/forms/:formKey/submissions/:submissionId',
+    permissions: ['formSubmissions.read'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/forms/data-sources',
+    permissions: ['formDataSources.manage'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/forms/:formKey/data-sources/:dataSourceKey/options',
+    permissions: ['formSubmissions.create'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/forms/:formKey/files',
+    permissions: ['formSubmissions.create'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/forms/:formKey/files/:fileId',
+    permissions: ['formSubmissions.read'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/forms/:formKey/submissions/export',
+    permissions: ['formSubmissions.export'],
+  },
+  // Report builder (@ftisindia/report-builder) — report design §10. Row
+  // actions carry an additional per-action permission check inside the engine
+  // (attach-time and execute-time, §6.1); the route gate below is the base.
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/reports',
+    permissions: ['reports.read'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/reports',
+    permissions: ['reports.create'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/reports/exports/:jobId',
+    permissions: ['reports.export'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/reports/exports/:jobId/download',
+    permissions: ['reports.export'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/reports/:key',
+    permissions: ['reports.read'],
+  },
+  {
+    method: 'PATCH',
+    path: '/organisations/:orgId/reports/:key',
+    permissions: ['reports.update'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/reports/:key/publish',
+    permissions: ['reports.publish'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/reports/:key/archive',
+    permissions: ['reports.archive'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/reports/:key/meta',
+    permissions: ['reports.read'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/reports/:key/query',
+    permissions: ['reports.read'],
+  },
+  {
+    method: 'GET',
+    path: '/organisations/:orgId/reports/:key/views',
+    permissions: ['reports.read'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/reports/:key/views',
+    permissions: ['reports.read'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/reports/:key/views/shared',
+    permissions: ['reports.update'],
+  },
+  {
+    method: 'PATCH',
+    path: '/organisations/:orgId/reports/:key/views/:viewId',
+    permissions: ['reports.read'],
+  },
+  {
+    method: 'DELETE',
+    path: '/organisations/:orgId/reports/:key/views/:viewId',
+    permissions: ['reports.read'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/reports/:key/actions/:name/prepare',
+    permissions: ['reports.read'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/reports/:key/actions/:name',
+    permissions: ['reports.read'],
+  },
+  {
+    method: 'POST',
+    path: '/organisations/:orgId/reports/:key/export',
+    permissions: ['reports.export'],
+  },
 ];

package/template/src/modules/audit/dto/audit-response.dto.ts

@@ -7,7 +7,7 @@ class AuditActorResponseDto {
   })
   id!: string;
 
-  @ApiPropertyOptional({ example: 'Starter Owner', nullable: true })
+  @ApiPropertyOptional({ type: String, example: 'Starter Owner', nullable: true })
   displayName?: string | null;
 }
 
@@ -19,6 +19,7 @@ export class AuditLogResponseDto {
   id!: string;
 
   @ApiPropertyOptional({
+    type: String,
     example: '2c67399d-670c-4025-a5fd-1ea9a211891e',
     format: 'uuid',
     nullable: true,
@@ -26,6 +27,7 @@ export class AuditLogResponseDto {
   orgId?: string | null;
 
   @ApiPropertyOptional({
+    type: String,
     example: '4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456',
     format: 'uuid',
     nullable: true,
@@ -39,6 +41,7 @@ export class AuditLogResponseDto {
   targetType!: string;
 
   @ApiPropertyOptional({
+    type: String,
     example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
     nullable: true,
   })
@@ -50,10 +53,10 @@ export class AuditLogResponseDto {
   })
   metadata?: Record<string, unknown> | null;
 
-  @ApiPropertyOptional({ example: '127.0.0.1', nullable: true })
+  @ApiPropertyOptional({ type: String, example: '127.0.0.1', nullable: true })
   ipAddress?: string | null;
 
-  @ApiPropertyOptional({ example: 'Mozilla/5.0', nullable: true })
+  @ApiPropertyOptional({ type: String, example: 'Mozilla/5.0', nullable: true })
   userAgent?: string | null;
 
   @ApiProperty({ example: '2026-06-01T10:30:00.000Z', format: 'date-time' })
@@ -68,6 +71,7 @@ export class AuditLogListResponseDto {
   items!: AuditLogResponseDto[];
 
   @ApiPropertyOptional({
+    type: String,
     example: 'df6537c4-f58b-452e-a67e-18ec528d0f0f',
     nullable: true,
   })

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

@@ -41,6 +41,8 @@ import { GoogleOAuthExceptionFilter } from './presentation/google-oauth-exceptio
     PasswordService,
     TokenService,
   ],
-  exports: [JwtAuthGuard, PasswordService],
+  // AuthService is exported for the forms module's delegating `authenticate`
+  // action (login-as-a-form rides the real auth stack, never reimplements it).
+  exports: [JwtAuthGuard, PasswordService, AuthService],
 })
 export class AuthModule {}

package/template/src/modules/auth/dto/auth-response.dto.ts

@@ -14,7 +14,7 @@ export class AuthTokensResponseDto {
   })
   refreshToken!: string;
 
-  @ApiProperty({ example: 'Bearer' })
+  @ApiProperty({ enum: ['Bearer'], example: 'Bearer' })
   tokenType!: 'Bearer';
 
   @ApiProperty({

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

@@ -0,0 +1,85 @@
+import { Injectable, Logger, OnApplicationBootstrap, OnModuleDestroy } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { isGcEligible } from '@ftisindia/form-builder';
+import { PrismaFileStore } from '../../infrastructure/stores/prisma-file.store';
+import { LocalDiskStorageAdapter } from '../../infrastructure/storage/local-disk-storage.adapter';
+
+const GC_BATCH_SIZE = 100;
+
+/**
+ * Sweeps orphaned TEMPORARY uploads (design doc §10.3): files uploaded but
+ * never linked to a submission within FORMS_FILE_TEMP_TTL_HOURS are deleted
+ * — bytes first, then the row. LINKED files are exempt by construction.
+ * runOnce() makes tests deterministic; the timer mirrors the outbox poller.
+ */
+@Injectable()
+export class FileGcService implements OnApplicationBootstrap, OnModuleDestroy {
+  private readonly logger = new Logger('FormsFileGc');
+  private timer?: NodeJS.Timeout;
+  private sweeping = false;
+
+  constructor(
+    private readonly config: ConfigService,
+    private readonly files: PrismaFileStore,
+    private readonly storage: LocalDiskStorageAdapter,
+  ) {}
+
+  onApplicationBootstrap(): void {
+    if (this.config.get<boolean>('forms.outboxEnabled') === false) {
+      // Test environments disable background work with one switch.
+      return;
+    }
+    const intervalMs = this.config.get<number>('forms.fileGcIntervalMs') ?? 3_600_000;
+    this.timer = setInterval(() => {
+      void this.sweep();
+    }, intervalMs);
+    this.timer.unref?.();
+  }
+
+  onModuleDestroy(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  async runOnce(now = new Date()): Promise<number> {
+    const ttlMs =
+      (this.config.get<number>('forms.fileTempTtlHours') ?? 24) * 60 * 60 * 1000;
+    const cutoff = new Date(now.getTime() - ttlMs);
+    const candidates = await this.files.listGcEligible(cutoff, GC_BATCH_SIZE);
+    let removed = 0;
+    for (const file of candidates) {
+      if (!isGcEligible(file, now, ttlMs)) {
+        continue;
+      }
+      try {
+        await this.storage.delete(file.storageKey);
+        await this.files.delete(file.id);
+        removed += 1;
+      } catch (error) {
+        this.logger.warn(
+          `Failed to garbage-collect file ${file.id}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+    return removed;
+  }
+
+  private async sweep(): Promise<void> {
+    if (this.sweeping) {
+      return;
+    }
+    this.sweeping = true;
+    try {
+      const removed = await this.runOnce();
+      if (removed > 0) {
+        this.logger.log(`Garbage-collected ${removed} orphaned temporary file(s).`);
+      }
+    } catch (error) {
+      this.logger.error('File GC sweep failed.', error instanceof Error ? error.stack : error);
+    } finally {
+      this.sweeping = false;
+    }
+  }
+}

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

@@ -0,0 +1,137 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { DataSourceRegistry, DefinitionService, walkFields } from '@ftisindia/form-builder';
+import type { DataSourceOption, FormDefinition } from '@ftisindia/form-builder';
+import { resolvePageLimit, toPage } from '../../../../common/dto/pagination-query.dto';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { CreateFormDefinitionDto } from '../../dto/create-form-definition.dto';
+import { ListFormDefinitionsQueryDto } from '../../dto/list-form-definitions-query.dto';
+import { SetPublicAccessDto } from '../../dto/set-public-access.dto';
+import { UpdateFormDefinitionDto } from '../../dto/update-form-definition.dto';
+import { RequestFormsContext } from '../../infrastructure/request-forms-context';
+import { withFormsErrorMapping } from './forms-error.mapper';
+
+/**
+ * Thin HTTP-facing wrapper over the engine's DefinitionService: org-scope
+ * assertion first, engine call through the FormsContext seam, engine-typed
+ * errors mapped onto the app's HTTP envelope. No business logic lives here.
+ */
+@Injectable()
+export class FormsDefinitionsService {
+  constructor(
+    private readonly engine: DefinitionService,
+    private readonly dataSources: DataSourceRegistry,
+    private readonly formsContext: RequestFormsContext,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async list(orgId: string, query: ListFormDefinitionsQueryDto) {
+    this.requestContext.assertOrgScope(orgId);
+    const limit = resolvePageLimit(query.limit);
+
+    const records = await withFormsErrorMapping(() =>
+      this.engine.list(
+        { orgId, status: query.status, cursor: query.cursor, limit: limit + 1 },
+        this.formsContext,
+      ),
+    );
+
+    return toPage(records, limit);
+  }
+
+  async create(orgId: string, dto: CreateFormDefinitionDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.createDraft(
+        { orgId, definition: dto.definition as unknown as FormDefinition },
+        this.formsContext,
+      ),
+    );
+  }
+
+  async getLatest(orgId: string, formKey: string) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.getLatest({ orgId, key: formKey }, this.formsContext),
+    );
+  }
+
+  async getVersion(orgId: string, formKey: string, version: number) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.getByKeyVersion({ orgId, key: formKey, version }, this.formsContext),
+    );
+  }
+
+  async update(orgId: string, formKey: string, version: number, dto: UpdateFormDefinitionDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.updateDraft(
+        {
+          orgId,
+          key: formKey,
+          version,
+          definition: dto.definition as unknown as FormDefinition,
+        },
+        this.formsContext,
+      ),
+    );
+  }
+
+  async publish(orgId: string, formKey: string, version: number) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.publish({ orgId, key: formKey, version }, this.formsContext),
+    );
+  }
+
+  async archive(orgId: string, formKey: string, version: number) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.archive({ orgId, key: formKey, version }, this.formsContext),
+    );
+  }
+
+  async setPublicAccess(orgId: string, formKey: string, version: number, dto: SetPublicAccessDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.setPublicAccess(
+        { orgId, key: formKey, version, access: dto.access },
+        this.formsContext,
+      ),
+    );
+  }
+
+  async render(orgId: string, formKey: string) {
+    this.requestContext.assertOrgScope(orgId);
+    const result = await withFormsErrorMapping(() =>
+      this.engine.getForRender({ orgId, key: formKey }, this.formsContext),
+    );
+    return { definition: result.definition, options: result.options };
+  }
+
+  async dataSourceOptions(orgId: string, formKey: string, dataSourceKey: string) {
+    this.requestContext.assertOrgScope(orgId);
+    const render = await withFormsErrorMapping(() =>
+      this.engine.getForRender({ orgId, key: formKey }, this.formsContext),
+    );
+
+    const paths: string[] = [];
+    walkFields(render.definition.fields, (field, path) => {
+      if (field.dataSource?.key === dataSourceKey) {
+        paths.push(path.join('.'));
+      }
+    });
+
+    if (paths.length === 0) {
+      throw new NotFoundException('No field on this form uses the requested data source.');
+    }
+
+    const items: DataSourceOption[] = paths.flatMap((path) => render.options[path] ?? []);
+    return { items };
+  }
+
+  listDataSourceKeys(orgId: string) {
+    this.requestContext.assertOrgScope(orgId);
+    return { items: this.dataSources.keys() };
+  }
+}

package/template/src/modules/forms/application/services/forms-error.mapper.ts

@@ -0,0 +1,64 @@
+import {
+  ConflictException,
+  ForbiddenException,
+  NotFoundException,
+  UnprocessableEntityException,
+} from '@nestjs/common';
+import {
+  FormsAuthzDeniedError,
+  FormsConflictError,
+  FormsDefinitionLintError,
+  FormsNotFoundError,
+  FormsStateError,
+  FormsValidationError,
+} from '@ftisindia/form-builder';
+import { Prisma } from '@prisma/client';
+
+/**
+ * Maps the engine's typed errors (ecosystem guide §2.1) onto the app's HTTP
+ * error envelope. Object bodies survive the global HttpExceptionFilter, which
+ * lifts every non-message key into `error.details` — so 422 responses carry
+ * the engine's `errors` / `issues` arrays verbatim.
+ */
+export function mapFormsError(error: unknown): never {
+  if (error instanceof FormsValidationError) {
+    throw new UnprocessableEntityException({
+      message: 'Validation failed.',
+      errors: error.errors,
+    });
+  }
+
+  if (error instanceof FormsDefinitionLintError) {
+    throw new UnprocessableEntityException({
+      message: 'Form definition is invalid.',
+      issues: error.issues,
+    });
+  }
+
+  if (error instanceof FormsAuthzDeniedError) {
+    throw new ForbiddenException(error.message);
+  }
+
+  if (error instanceof FormsNotFoundError) {
+    throw new NotFoundException(error.message);
+  }
+
+  if (error instanceof FormsConflictError || error instanceof FormsStateError) {
+    throw new ConflictException(error.message);
+  }
+
+  if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2002') {
+    throw new ConflictException('A form definition with this key and version already exists.');
+  }
+
+  throw error;
+}
+
+/** Awaits an engine call and maps any engine-typed failure onto HTTP errors. */
+export async function withFormsErrorMapping<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    mapFormsError(error);
+  }
+}