@ftisindia/create-app 0.1.4 → 0.1.6

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

@@ -0,0 +1,345 @@
+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';
+import { FileGcService } from '../src/modules/forms/application/services/file-gc.service';
+
+const PDF_BYTES = Buffer.from('%PDF-1.4\n1 0 obj\n<<>>\nendobj\ntrailer\n<<>>\n%%EOF');
+const PNG_BYTES = Buffer.from([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
+]);
+
+describe('Forms file uploads (e2e)', () => {
+  let app: INestApplication;
+  let prisma: PrismaService;
+  let owner: { accessToken: string; userId: string; orgId: string };
+  let formKey: string;
+
+  beforeAll(async () => {
+    process.env.DATABASE_URL = process.env.TEST_DATABASE_URL ?? process.env.DATABASE_URL;
+    process.env.JWT_SECRET ||= 'test-jwt-secret-at-least-16-chars';
+    process.env.AUTH_GOOGLE_ENABLED ||= 'false';
+    process.env.AUTH_EMAIL_PASSWORD_ENABLED ||= 'true';
+    process.env.NODE_ENV = 'test';
+    process.env.FORMS_OUTBOX_ENABLED = 'false';
+    process.env.FORMS_FILE_STORAGE_DIR = './var/test-uploads';
+
+    const { AppModule } = await import('../src/app.module');
+    const moduleRef = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleRef.createNestApplication();
+    app.useGlobalFilters(new HttpExceptionFilter());
+    app.useGlobalPipes(
+      new ValidationPipe({
+        forbidNonWhitelisted: true,
+        transform: true,
+        whitelist: true,
+      }),
+    );
+    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')));
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('rejects mismatched content (415) and accepts a sniffed PDF', async () => {
+    await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${formKey}/files`)
+      .query({ field: 'manuscript' })
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .attach('file', PNG_BYTES, 'sneaky.pdf')
+      .expect(415);
+
+    const upload = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${formKey}/files`)
+      .query({ field: 'manuscript' })
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .attach('file', PDF_BYTES, 'manuscript.pdf');
+
+    expect([200, 201]).toContain(upload.status);
+    expect(upload.body.fileId).toBeTruthy();
+    expect(upload.body.mimeType).toBe('application/pdf');
+    expect(upload.body.status).toBe('TEMPORARY');
+    expect(upload.body.checksum).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('validates uploads against the requested version or draft submission stamp', async () => {
+    const key = await publishDefinition(abstractDefinition(uniqueFormKey('versioned-file')));
+    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' } })
+      .expect(200);
+
+    const createdV2 = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms`)
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .send({ definition: abstractDefinition(key, ['image/png']) })
+      .expect(201);
+    await request(app.getHttpServer())
+      .post(
+        `/organisations/${owner.orgId}/forms/${key}/versions/${createdV2.body.version as number}/publish`,
+      )
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .expect(200);
+
+    await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${key}/files`)
+      .query({ field: 'manuscript' })
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .attach('file', PDF_BYTES, 'manuscript.pdf')
+      .expect(415);
+
+    const pngUpload = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${key}/files`)
+      .query({ field: 'manuscript', version: createdV2.body.version as number })
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .attach('file', PNG_BYTES, 'manuscript.png');
+    expect([200, 201]).toContain(pngUpload.status);
+
+    await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${key}/files`)
+      .query({
+        field: 'manuscript',
+        submissionId: draft.body.submissionId as string,
+        version: createdV2.body.version as number,
+      })
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .attach('file', PNG_BYTES, 'manuscript.png')
+      .expect(409);
+  });
+
+  it('links the referenced file to the submission (TEMPORARY -> LINKED)', async () => {
+    const fileId = await uploadPdf(owner.accessToken);
+
+    const submitted = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${formKey}/submissions`)
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .send({
+        mode: 'submit',
+        data: { title: 'On Linking Files', track: 'ai', manuscript: { fileId } },
+      })
+      .expect(200);
+
+    const submissionId = submitted.body.submissionId as string;
+    expect(submissionId).toBeTruthy();
+
+    const row = await prisma.uploadedFile.findUnique({ where: { id: fileId } });
+    expect(row?.status).toBe('LINKED');
+    expect(row?.submissionId).toBe(submissionId);
+  });
+
+  it('rejects another member referencing a file they did not upload (IDOR)', async () => {
+    const fileId = await uploadPdf(owner.accessToken);
+    const member = await createMemberInOrg(owner.orgId, 'files-member', [
+      'formSubmissions.create',
+    ]);
+
+    const response = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${formKey}/submissions`)
+      .set('Authorization', `Bearer ${member.accessToken}`)
+      .send({
+        mode: 'submit',
+        data: { title: 'Stolen Reference', track: 'ml', manuscript: { fileId } },
+      })
+      .expect(422);
+
+    const errors = response.body.error.details.errors as Array<{ code: string; path: string }>;
+    expect(errors.some((error) => error.code === 'FILE_REFERENCE')).toBe(true);
+
+    // The file is untouched.
+    const row = await prisma.uploadedFile.findUnique({ where: { id: fileId } });
+    expect(row?.status).toBe('TEMPORARY');
+  });
+
+  it('garbage-collects orphaned TEMPORARY uploads past the TTL', async () => {
+    const fileId = await uploadPdf(owner.accessToken);
+
+    await prisma.uploadedFile.update({
+      where: { id: fileId },
+      data: { createdAt: new Date(Date.now() - 48 * 60 * 60 * 1000) },
+    });
+
+    const removed = await app.get(FileGcService).runOnce();
+    expect(removed).toBeGreaterThanOrEqual(1);
+
+    const row = await prisma.uploadedFile.findUnique({ where: { id: fileId } });
+    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`)
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .send({ access: 'public' })
+      .expect(422);
+
+    const issues = response.body.error.details.issues as Array<{ code: string }>;
+    expect(issues.map((issue) => issue.code)).toContain('PUBLIC_FILE_FIELD');
+  });
+
+  // ── Helpers ────────────────────────────────────────────────────────────────
+
+  function uniqueSuffix() {
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+
+  function uniqueFormKey(label: string) {
+    return `${label}-${uniqueSuffix()}`.toLowerCase();
+  }
+
+  function abstractDefinition(
+    key: string,
+    accept: string[] = ['application/pdf'],
+  ): Record<string, unknown> {
+    return {
+      key,
+      version: 1,
+      title: 'Scientific abstract submission',
+      fields: [
+        {
+          type: 'text',
+          name: 'title',
+          label: 'Abstract title',
+          validators: { required: true, maxLength: 200 },
+          reportable: true,
+        },
+        {
+          type: 'select',
+          name: 'track',
+          label: 'Conference track',
+          dataSource: { key: 'conference-tracks' },
+          validators: { required: true },
+          reportable: true,
+        },
+        {
+          type: 'file',
+          name: 'manuscript',
+          label: 'Full manuscript (PDF)',
+          accept,
+          maxSizeMb: 5,
+        },
+      ],
+      actions: {
+        submit: ['validateAll', 'persist'],
+        saveDraft: ['persistDraft'],
+      },
+    };
+  }
+
+  async function uploadPdf(accessToken: string): Promise<string> {
+    const upload = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${formKey}/files`)
+      .query({ field: 'manuscript' })
+      .set('Authorization', `Bearer ${accessToken}`)
+      .attach('file', PDF_BYTES, 'manuscript.pdf');
+
+    expect([200, 201]).toContain(upload.status);
+    return upload.body.fileId as string;
+  }
+
+  async function publishDefinition(definition: Record<string, unknown>): Promise<string> {
+    const created = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms`)
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .send({ definition })
+      .expect(201);
+
+    await request(app.getHttpServer())
+      .post(
+        `/organisations/${owner.orgId}/forms/${created.body.key as string}/versions/${created.body.version as number}/publish`,
+      )
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .expect(200);
+
+    return created.body.key as string;
+  }
+
+  async function createUser(label: string) {
+    const suffix = uniqueSuffix();
+    const signup = await request(app.getHttpServer())
+      .post('/auth/signup')
+      .send({
+        email: `${label}-${suffix}@example.com`,
+        password: 'test-password-123',
+        displayName: label,
+      })
+      .expect(201);
+
+    return {
+      accessToken: signup.body.accessToken as string,
+      userId: signup.body.user.id as string,
+    };
+  }
+
+  async function createUserAndOrg(label: string) {
+    const user = await createUser(label);
+    const suffix = uniqueSuffix();
+    const org = await request(app.getHttpServer())
+      .post('/organisations')
+      .set('Authorization', `Bearer ${user.accessToken}`)
+      .send({
+        name: `${label} ${suffix}`,
+        slug: `${label}-${suffix}`,
+      })
+      .expect(201);
+
+    return {
+      ...user,
+      orgId: org.body.organisation.id as string,
+    };
+  }
+
+  async function createMemberInOrg(orgId: string, label: string, permissionKeys: string[]) {
+    const user = await createUser(label);
+    const permissions = await prisma.permission.findMany({
+      where: { key: { in: permissionKeys } },
+      select: { id: true },
+    });
+    expect(permissions).toHaveLength(permissionKeys.length);
+
+    const role = await prisma.role.create({
+      data: {
+        orgId,
+        name: `${label}-${uniqueSuffix()}`,
+        permissions: {
+          create: permissions.map((permission) => ({ permissionId: permission.id })),
+        },
+      },
+      select: { id: true },
+    });
+    const membership = await prisma.membership.create({
+      data: {
+        userId: user.userId,
+        orgId,
+        roleId: role.id,
+      },
+      select: { id: true, roleId: true },
+    });
+
+    return {
+      ...user,
+      membershipId: membership.id,
+      roleId: membership.roleId,
+    };
+  }
+});

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

@@ -0,0 +1,309 @@
+import { INestApplication, ValidationPipe } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import { ActionRegistry, OutboxHandlerRegistry } 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';
+import { AuditService } from '../src/modules/audit/application/services/audit.service';
+import { OutboxDispatcherService } from '../src/modules/forms/application/services/outbox-dispatcher.service';
+
+describe('Forms transactional outbox (e2e)', () => {
+  let app: INestApplication;
+  let prisma: PrismaService;
+  let dispatcher: OutboxDispatcherService;
+  let owner: { accessToken: string; userId: string; orgId: string };
+
+  beforeAll(async () => {
+    process.env.DATABASE_URL = process.env.TEST_DATABASE_URL ?? process.env.DATABASE_URL;
+    process.env.JWT_SECRET ||= 'test-jwt-secret-at-least-16-chars';
+    process.env.AUTH_GOOGLE_ENABLED ||= 'false';
+    process.env.AUTH_EMAIL_PASSWORD_ENABLED ||= 'true';
+    process.env.NODE_ENV = 'test';
+    process.env.FORMS_OUTBOX_ENABLED = 'false';
+    process.env.FORMS_FILE_STORAGE_DIR = './var/test-uploads';
+
+    const { AppModule } = await import('../src/app.module');
+    const moduleRef = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleRef.createNestApplication();
+    app.useGlobalFilters(new HttpExceptionFilter());
+    app.useGlobalPipes(
+      new ValidationPipe({
+        forbidNonWhitelisted: true,
+        transform: true,
+        whitelist: true,
+      }),
+    );
+    await app.init();
+    prisma = app.get(PrismaService);
+    dispatcher = app.get(OutboxDispatcherService);
+
+    // Test-only extensions: a handler type that always throws, and a
+    // post-commit action that enqueues a job for it with a tight retry budget.
+    app.get(OutboxHandlerRegistry).register({
+      type: 'boom',
+      handle: () => {
+        return Promise.reject(new Error('boom handler failure'));
+      },
+    });
+    app.get(ActionRegistry).register({
+      name: 'enqueueBoom',
+      kind: 'post-commit',
+      execute: async (ctx) => {
+        await ctx.enqueue({ type: 'boom', payload: {}, maxAttempts: 2 });
+        return { queued: true };
+      },
+    });
+
+    // Park stray PENDING jobs left by earlier suites/runs so runOnce() cycles
+    // in this suite deterministically claim the jobs created here (the claim
+    // batch is ordered oldest-first and capped).
+    await prisma.formOutboxJob.updateMany({
+      where: { status: { in: ['PENDING', 'PROCESSING'] } },
+      data: { status: 'FAILED', lastError: 'parked by forms-outbox e2e setup' },
+    });
+
+    owner = await createUserAndOrg('outbox-owner');
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('enqueues atomically with the submission and delivers via runOnce()', async () => {
+    const key = await publishDefinition(registrationDefinition(uniqueFormKey('outbox-email')));
+
+    const response = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${key}/submissions`)
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .send({
+        mode: 'submit',
+        data: { fullName: 'Outbox Tester', email: 'outbox@example.com', ticketType: 'standard' },
+      })
+      .expect(200);
+
+    const submissionId = response.body.submissionId as string;
+    expect(submissionId).toBeTruthy();
+
+    const job = await prisma.formOutboxJob.findFirst({
+      where: { idempotencyKey: { contains: submissionId } },
+    });
+    expect(job).not.toBeNull();
+    expect(job?.status).toBe('PENDING');
+    expect(job?.type).toBe('email');
+
+    await dispatcher.runOnce();
+
+    const delivered = await prisma.formOutboxJob.findUnique({ where: { id: job!.id } });
+    expect(delivered?.status).toBe('DONE');
+
+    const auditRow = await prisma.auditLog.findFirst({
+      where: { action: 'forms.outbox.delivered', targetId: job!.id },
+    });
+    expect(auditRow).not.toBeNull();
+    expect(auditRow?.orgId).toBe(owner.orgId);
+  });
+
+  it('retries a failing handler with backoff, then parks the job at maxAttempts', async () => {
+    const key = uniqueFormKey('outbox-boom');
+    await publishDefinition({
+      ...registrationDefinition(key),
+      actions: {
+        submit: ['validateAll', 'persist', 'enqueueBoom'],
+        saveDraft: ['persistDraft'],
+      },
+    });
+
+    const response = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms/${key}/submissions`)
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .send({
+        mode: 'submit',
+        data: { fullName: 'Boom Tester', email: 'boom@example.com', ticketType: 'vip' },
+      })
+      .expect(200);
+
+    const submissionId = response.body.submissionId as string;
+    const job = await prisma.formOutboxJob.findFirst({
+      where: { type: 'boom', idempotencyKey: { contains: submissionId } },
+    });
+    expect(job).not.toBeNull();
+    expect(job?.maxAttempts).toBe(2);
+
+    // First attempt fails -> retried: back to PENDING with a future runAfter.
+    await dispatcher.runOnce();
+    const retried = await prisma.formOutboxJob.findUnique({ where: { id: job!.id } });
+    expect(retried?.status).toBe('PENDING');
+    expect(retried?.attempts).toBe(1);
+    expect(retried?.runAfter).not.toBeNull();
+    expect(retried!.runAfter!.getTime()).toBeGreaterThan(Date.now());
+
+    // Make the retry due, then fail again -> parked as FAILED at maxAttempts.
+    await prisma.formOutboxJob.update({
+      where: { id: job!.id },
+      data: { runAfter: new Date(Date.now() - 1000) },
+    });
+    await dispatcher.runOnce();
+
+    const parked = await prisma.formOutboxJob.findUnique({ where: { id: job!.id } });
+    expect(parked?.status).toBe('FAILED');
+    expect(parked?.attempts).toBe(2);
+  });
+
+  it('fails immediately when no handler is registered for the job type', async () => {
+    const orphan = await prisma.formOutboxJob.create({
+      data: {
+        type: `no-handler-${uniqueSuffix()}`,
+        payload: {},
+        status: 'PENDING',
+        attempts: 0,
+        maxAttempts: 5,
+      },
+    });
+
+    await dispatcher.runOnce();
+
+    const failed = await prisma.formOutboxJob.findUnique({ where: { id: orphan.id } });
+    expect(failed?.status).toBe('FAILED');
+    expect(failed?.attempts).toBe(1);
+    expect(failed?.lastError).toMatch(/No handler registered/);
+  });
+
+  it('does not retry a delivered job when the success audit write fails', async () => {
+    const job = await prisma.formOutboxJob.create({
+      data: {
+        type: 'email',
+        payload: { to: 'audit-failure@example.com', template: 'test' },
+        status: 'PENDING',
+        attempts: 0,
+        maxAttempts: 3,
+        orgId: owner.orgId,
+        actorUserId: owner.userId,
+      },
+    });
+    const audit = app.get(AuditService);
+    const spy = jest.spyOn(audit, 'write').mockRejectedValueOnce(new Error('audit down'));
+
+    await dispatcher.runOnce();
+
+    const delivered = await prisma.formOutboxJob.findUnique({ where: { id: job.id } });
+    expect(delivered?.status).toBe('DONE');
+    expect(delivered?.attempts).toBe(0);
+    expect(delivered?.lastError).toBeNull();
+    spy.mockRestore();
+  });
+
+  it('reclaims stale PROCESSING jobs', async () => {
+    const staleTime = new Date(Date.now() - 10 * 60 * 1000);
+    const job = await prisma.formOutboxJob.create({
+      data: {
+        type: 'email',
+        payload: { to: 'stale@example.com', template: 'test' },
+        status: 'PROCESSING',
+        attempts: 0,
+        maxAttempts: 3,
+        orgId: owner.orgId,
+        actorUserId: owner.userId,
+        createdAt: staleTime,
+        updatedAt: staleTime,
+      },
+    });
+
+    await dispatcher.runOnce();
+
+    const delivered = await prisma.formOutboxJob.findUnique({ where: { id: job.id } });
+    expect(delivered?.status).toBe('DONE');
+  });
+
+  // ── Helpers ────────────────────────────────────────────────────────────────
+
+  function uniqueSuffix() {
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+
+  function uniqueFormKey(label: string) {
+    return `${label}-${uniqueSuffix()}`.toLowerCase();
+  }
+
+  function registrationDefinition(key: string): Record<string, unknown> {
+    return {
+      key,
+      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,
+        },
+        {
+          type: 'select',
+          name: 'ticketType',
+          label: 'Ticket type',
+          validators: { required: true, options: ['standard', 'student', 'vip'] },
+          reportable: true,
+        },
+      ],
+      actions: {
+        submit: ['validateAll', 'persist', 'sendConfirmationEmail'],
+        saveDraft: ['persistDraft'],
+      },
+    };
+  }
+
+  async function publishDefinition(definition: Record<string, unknown>): Promise<string> {
+    const created = await request(app.getHttpServer())
+      .post(`/organisations/${owner.orgId}/forms`)
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .send({ definition })
+      .expect(201);
+
+    await request(app.getHttpServer())
+      .post(
+        `/organisations/${owner.orgId}/forms/${created.body.key as string}/versions/${created.body.version as number}/publish`,
+      )
+      .set('Authorization', `Bearer ${owner.accessToken}`)
+      .expect(200);
+
+    return created.body.key as string;
+  }
+
+  async function createUserAndOrg(label: string) {
+    const suffix = uniqueSuffix();
+    const signup = await request(app.getHttpServer())
+      .post('/auth/signup')
+      .send({
+        email: `${label}-${suffix}@example.com`,
+        password: 'test-password-123',
+        displayName: label,
+      })
+      .expect(201);
+
+    const accessToken = signup.body.accessToken as string;
+    const org = await request(app.getHttpServer())
+      .post('/organisations')
+      .set('Authorization', `Bearer ${accessToken}`)
+      .send({
+        name: `${label} ${suffix}`,
+        slug: `${label}-${suffix}`,
+      })
+      .expect(201);
+
+    return {
+      accessToken,
+      userId: signup.body.user.id as string,
+      orgId: org.body.organisation.id as string,
+    };
+  }
+});

package/template/test/forms-permission-sync.spec.ts

@@ -0,0 +1,27 @@
+import { FORM_PERMISSION_KEYS } from '@ftisindia/form-builder';
+import { permissionKeys } from '../src/modules/access-control/types/permission-key';
+
+/**
+ * The template carries the form permission keys as literals (so the as-const
+ * tuple stays narrow and gen:module's insertion markers keep working); this
+ * test is the mechanical guarantee they can never drift from the engine's
+ * FORM_PERMISSION_KEYS export — in either direction.
+ */
+describe('forms permission sync', () => {
+  const templateFormKeys = permissionKeys.filter(
+    (key) =>
+      key.startsWith('forms.') ||
+      key.startsWith('formSubmissions.') ||
+      key.startsWith('formDataSources.'),
+  );
+
+  it('contains every engine form permission key', () => {
+    for (const key of FORM_PERMISSION_KEYS) {
+      expect(permissionKeys).toContain(key);
+    }
+  });
+
+  it('has no form keys the engine does not declare', () => {
+    expect([...templateFormKeys].sort()).toEqual([...FORM_PERMISSION_KEYS].sort());
+  });
+});