@teleporthq/teleport-plugin-next-workflows 0.43.75 → 0.44.1

package/__tests__/invoice-payment-email.test.ts

@@ -0,0 +1,191 @@
+import {
+  BUYER,
+  ORDER_ID,
+  Row,
+  Store,
+  historyLines,
+  invoiceOf,
+  ledgerRows,
+  openStore,
+  payWhilePdfServiceIsDown,
+  runsAsTheStore,
+  seedPaidOrder,
+} from './_helpers/invoice-store'
+
+/**
+ * The invoice email a payment sends is on its order's history.
+ *
+ * With Invoice Email Delivery on, the payment's `/api/invoices/generate`
+ * emails the buyer the invoice it just issued. The admin panel's Regenerate
+ * writes an "email sent" line on the order's history when it emails one; the
+ * payment wrote none, so the order never showed that its buyer got the
+ * invoice.
+ *
+ * Everything here is the code the store runs, as emitted (see
+ * `_helpers/invoice-store.ts`); only its database, the PDF service and the
+ * email provider are faked.
+ */
+describe("the payment's invoice email is on its order's history", () => {
+  runsAsTheStore()
+
+  it('the email the payment sends writes one "email sent" line, by the store', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+
+    const paid = await store.pay(ORDER_ID)
+
+    expect(paid.status).toBe(200)
+    const invoice = invoiceOf(store, ORDER_ID)
+    expect(store.emails.map((email) => email.To)).toEqual([BUYER])
+    expect(ledgerRows(store)).toEqual([
+      expect.objectContaining({ status: 'sent', source_ref: 'api/invoices/generate' }),
+    ])
+    // The line the regeneration writes, keyed on the same invoice: an
+    // invoice's email is on its order's history once, whoever sent it.
+    expect(historyLines(store)).toEqual([
+      expect.objectContaining({
+        event_type: 'order-email-sent',
+        dedupe_key: 'order-email-sent:' + String(invoice.id) + ':invoice-email',
+        order_id: ORDER_ID,
+        payload: JSON.stringify({ purpose: 'invoice-email', to: BUYER }),
+        actor: '',
+        actor_type: 'system',
+        status: 'recorded',
+      }),
+    ])
+  })
+
+  it('a payment reported again sends nothing and writes no second line', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    expect((await store.pay(ORDER_ID)).status).toBe(200)
+
+    const again = await store.pay(ORDER_ID)
+
+    expect(again.body).toMatchObject({ success: true, alreadyIssued: true })
+    expect(store.emails).toHaveLength(1)
+    expect(historyLines(store)).toHaveLength(1)
+  })
+
+  it('an invoice an admin issues by hand is on the history under their name', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+
+    expect((await store.issueAsAdmin(ORDER_ID)).status).toBe(200)
+
+    expect(store.emails).toHaveLength(1)
+    expect(historyLines(store)).toEqual([
+      expect.objectContaining({ actor: 'Store admin', actor_type: 'merchant' }),
+    ])
+  })
+
+  it('a refused email writes no line, and the log says it failed', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    store.provider.refuses = true
+
+    const paid = await store.pay(ORDER_ID)
+
+    expect(paid.status).toBe(200)
+    expect(store.emails).toHaveLength(1)
+    expect(ledgerRows(store)).toEqual([expect.objectContaining({ status: 'failed' })])
+    expect(historyLines(store)).toEqual([])
+    expect(store.errors).toContainEqual(expect.stringContaining('Email delivery FAILED'))
+  })
+
+  it('a history that cannot be written costs nothing else: the email goes and the payment is answered', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    store.db.failNext(/^INSERT INTO teleport_events /, 'relation "teleport_events" does not exist')
+
+    const paid = await store.pay(ORDER_ID)
+
+    expect(paid.status).toBe(200)
+    expect(paid.body).toMatchObject({ success: true, invoiceNumber: 'INV-0001' })
+    expect(store.emails).toHaveLength(1)
+    expect(historyLines(store)).toEqual([])
+    expect(store.errors).toContainEqual(
+      expect.stringContaining('INV-0001 was emailed, but the order history could not record it')
+    )
+  })
+
+  it('Invoice Email Delivery off: no email and no line', async () => {
+    const store = openStore({ emailDelivery: false })
+    seedPaidOrder(store.db, ORDER_ID)
+
+    expect((await store.pay(ORDER_ID)).status).toBe(200)
+
+    expect(store.emails).toEqual([])
+    expect(historyLines(store)).toEqual([])
+  })
+})
+
+/**
+ * A retried payment and the merchant's Regenerate finishing the same invoice.
+ *
+ * The PDF service was down at payment, so the invoice is reserved without a
+ * PDF. A quarter of an hour later the provider retries the payment, which
+ * claims the stale reservation and renders it — and the merchant clicks
+ * Regenerate meanwhile. Each route emails the buyer when it gives the invoice
+ * its first PDF, so the database must give that to exactly one of them.
+ */
+describe('a retried payment and a regeneration finishing the same invoice', () => {
+  runsAsTheStore()
+
+  const PAYMENT_PDF = /^UPDATE teleport_invoices SET "?pdf_data"? = \$1/
+  const REGENERATION_PDF = /^UPDATE teleport_invoices SET "invoice_number" = \$1/
+
+  /** The order paid while the PDF service was down, its reservation older than any request lives. */
+  async function staleInvoice(store: Store): Promise<Row> {
+    seedPaidOrder(store.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+    invoice.updated_at = new Date(Date.now() - 20 * 60 * 1000).toISOString()
+    return invoice
+  }
+
+  it("the regeneration's PDF lands first: it emails the buyer, and the payment answers with its invoice", async () => {
+    const store = openStore()
+    const invoice = await staleInvoice(store)
+    const paymentsPdf = store.db.pauseNext(PAYMENT_PDF)
+
+    const payment = store.pay(ORDER_ID)
+    await paymentsPdf.reached
+    const regenerated = await store.regenerate(String(invoice.id))
+    paymentsPdf.release()
+    const paid = await payment
+
+    expect(store.emails.map((email) => email.To)).toEqual([BUYER])
+    expect(ledgerRows(store).map((row) => row.source_ref)).toEqual(['api/invoices/[id]/regenerate'])
+    expect(historyLines(store)).toEqual([expect.objectContaining({ actor_type: 'merchant' })])
+    expect(regenerated.status).toBe(200)
+    expect(paid.status).toBe(200)
+    expect(paid.body).toMatchObject({
+      success: true,
+      alreadyIssued: true,
+      invoiceId: invoice.id,
+      invoiceNumber: 'INV-0001',
+      pdfUrl: '/api/invoices/' + String(invoice.id) + '/pdf',
+    })
+    expect(store.db.row('teleport_orders', ORDER_ID)).toMatchObject({ invoice_id: invoice.id })
+  })
+
+  it("the payment's PDF lands first: it emails the buyer, and the regeneration does not", async () => {
+    const store = openStore()
+    const invoice = await staleInvoice(store)
+    const regenerationsPdf = store.db.pauseNext(REGENERATION_PDF)
+
+    const regeneration = store.regenerate(String(invoice.id))
+    await regenerationsPdf.reached
+    const paid = await store.pay(ORDER_ID)
+    regenerationsPdf.release()
+    const regenerated = await regeneration
+
+    expect(store.emails.map((email) => email.To)).toEqual([BUYER])
+    expect(ledgerRows(store).map((row) => row.source_ref)).toEqual(['api/invoices/generate'])
+    expect(historyLines(store)).toEqual([expect.objectContaining({ actor_type: 'system' })])
+    expect(paid.status).toBe(200)
+    expect(paid.body).toMatchObject({ success: true, invoiceId: invoice.id })
+    expect(paid.body).not.toHaveProperty('alreadyIssued')
+    expect(regenerated.status).toBe(200)
+  })
+})

package/__tests__/invoice-regenerate-email.test.ts

@@ -0,0 +1,288 @@
+import {
+  BUYER,
+  ORDER_ID,
+  SECOND_BUYER,
+  SECOND_ORDER_ID,
+  PostmarkMessage,
+  historyLines,
+  invoiceOf,
+  ledgerRows,
+  openStore,
+  payWhilePdfServiceIsDown,
+  runsAsTheStore,
+  seedPaidOrder,
+} from './_helpers/invoice-store'
+
+/**
+ * Regenerate emails the buyer the invoice their payment could not.
+ *
+ * When the PDF service is down at payment, the order is still paid and its
+ * invoice row stays reserved without a PDF, so the payment's invoice email
+ * never goes out. The merchant then gets the PDF with the admin panel's
+ * Regenerate — and that regeneration, the FIRST to give the invoice a PDF,
+ * emails the buyer, once, when the store emails invoices.
+ *
+ * Everything here is the code the store runs, as emitted: the payment's
+ * `/api/invoices/generate`, the admin panel's `/api/invoices/[id]/regenerate`,
+ * the data access, the assembly, the PDF client, the invoice sender, the
+ * sent-email ledger and the locale module. Only what lies outside the store is
+ * faked: its Postgres database, the PDF service and the email provider.
+ */
+
+describe('Regenerate emails the buyer the invoice their payment could not', () => {
+  runsAsTheStore()
+
+  it('no PDF before: the regeneration that gives the invoice its PDF emails the buyer once', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+    expect(store.emails).toHaveLength(0)
+
+    const regenerated = await store.regenerate(String(invoice.id))
+
+    expect(regenerated.status).toBe(200)
+    expect(Number(invoice.pdf_size_bytes)).toBeGreaterThan(0)
+    expect(store.emails).toHaveLength(1)
+    const [email] = store.emails
+    expect(email.To).toBe(BUYER)
+    expect(email.From).toBe('Lumen Pottery <shop@lumen.test>')
+    expect(email.Attachments).toEqual([
+      {
+        Name: 'INV-0001.pdf',
+        Content: Buffer.from('%PDF-1.4 INV-0001').toString('base64'),
+        ContentType: 'application/pdf',
+      },
+    ])
+
+    // The sent-email ledger: the row the payment's email writes, naming the
+    // route that sent it.
+    expect(ledgerRows(store)).toEqual([
+      expect.objectContaining({
+        email_type: 'invoice-email',
+        audience: 'customer',
+        recipient_email: BUYER,
+        from_email: 'shop@lumen.test',
+        from_name: 'Lumen Pottery',
+        status: 'sent',
+        provider: 'postmark',
+        source: 'invoice',
+        source_ref: 'api/invoices/[id]/regenerate',
+        order_id: ORDER_ID,
+        reference_type: 'invoice',
+        reference_id: invoice.id,
+      }),
+    ])
+    // The order's history: one "email sent" line, by the store admin.
+    expect(historyLines(store)).toEqual([
+      expect.objectContaining({
+        event_type: 'order-email-sent',
+        dedupe_key: 'order-email-sent:' + String(invoice.id) + ':invoice-email',
+        order_id: ORDER_ID,
+        payload: JSON.stringify({ purpose: 'invoice-email', to: BUYER }),
+        actor: 'Store admin',
+        actor_type: 'merchant',
+        status: 'recorded',
+      }),
+    ])
+  })
+
+  it.each([
+    [
+      'served from the database',
+      false,
+      (invoiceId: string) => '/api/invoices/' + invoiceId + '/pdf',
+    ],
+    ['in runtime storage', true, () => 'https://cdn.test/INV-0001.pdf'],
+  ])(
+    'sends exactly the email the payment would have sent — sender, template, attachment, language, and the link of a PDF %s',
+    async (_, storageConfigured, expectedLink) => {
+      // A payment the PDF service served: the invoice email it sends.
+      const paidOk = openStore()
+      paidOk.storage.configured = storageConfigured
+      seedPaidOrder(paidOk.db, ORDER_ID)
+      expect((await paidOk.pay(ORDER_ID)).status).toBe(200)
+      expect(paidOk.emails).toHaveLength(1)
+      const atPayment = paidOk.emails[0]
+      const paidInvoiceId = String(invoiceOf(paidOk, ORDER_ID).id)
+
+      // The same order, paid while the PDF service was down, then regenerated.
+      const paidDown = openStore()
+      paidDown.storage.configured = storageConfigured
+      seedPaidOrder(paidDown.db, ORDER_ID)
+      const invoice = await payWhilePdfServiceIsDown(paidDown, ORDER_ID)
+      expect((await paidDown.regenerate(String(invoice.id))).status).toBe(200)
+      expect(paidDown.emails).toHaveLength(1)
+      const atRegeneration = paidDown.emails[0]
+
+      // Nothing differs but the invoice's own id, inside a database link.
+      const sameLink = (message: PostmarkMessage, id: string): PostmarkMessage => ({
+        ...message,
+        HtmlBody: message.HtmlBody.split(id).join('<invoice id>'),
+      })
+      expect(sameLink(atRegeneration, String(invoice.id))).toEqual(
+        sameLink(atPayment, paidInvoiceId)
+      )
+      // The buyer's language (the order is Spanish), not the merchant's German admin.
+      expect(atRegeneration.Subject).toBe('Factura INV-0001')
+      expect(atRegeneration.HtmlBody).toBe(
+        '<p>Hola Ana Pop, factura INV-0001 por €100.00: ' +
+          expectedLink(String(invoice.id)) +
+          '</p>'
+      )
+    }
+  )
+
+  it("an order with no language of its own gets the store's main language, never the merchant's", async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID, { locale: null })
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+
+    await store.regenerate(String(invoice.id))
+
+    expect(store.emails.map((email) => email.Subject)).toEqual(['Invoice INV-0001'])
+  })
+
+  it('had a PDF: only the invoice that never had one is emailed', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    seedPaidOrder(store.db, SECOND_ORDER_ID, {}, SECOND_BUYER)
+    // The first order's invoice was issued and emailed at payment.
+    expect((await store.pay(ORDER_ID)).status).toBe(200)
+    const issued = invoiceOf(store, ORDER_ID)
+    expect(store.emails.map((email) => email.To)).toEqual([BUYER])
+    // The second order's was not: the PDF service was down.
+    const unfinished = await payWhilePdfServiceIsDown(store, SECOND_ORDER_ID)
+
+    expect((await store.regenerate(String(issued.id))).status).toBe(200)
+    expect((await store.regenerate(String(unfinished.id))).status).toBe(200)
+
+    // The payment's email, then the unfinished invoice's — nothing for the
+    // invoice that already had its PDF.
+    expect(store.emails.map((email) => email.To)).toEqual([BUYER, SECOND_BUYER])
+    // Each email is on its own order's history once: the payment's, by the
+    // store, and the regeneration's, by the admin.
+    expect(historyLines(store).map((line) => [line.order_id, line.actor_type])).toEqual([
+      [ORDER_ID, 'system'],
+      [SECOND_ORDER_ID, 'merchant'],
+    ])
+  })
+
+  it('a second regeneration never emails again', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+
+    expect((await store.regenerate(String(invoice.id))).status).toBe(200)
+    expect(store.emails).toHaveLength(1)
+    expect((await store.regenerate(String(invoice.id))).status).toBe(200)
+    expect((await store.regenerate(String(invoice.id))).status).toBe(200)
+
+    expect(store.emails).toHaveLength(1)
+    expect(ledgerRows(store)).toHaveLength(1)
+    expect(historyLines(store)).toHaveLength(1)
+  })
+
+  it('two overlapping regenerations (a double click) email once', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+
+    // Both requests read the invoice without a PDF and render before either
+    // writes: the PDF service answers neither until it has both.
+    let releaseRenders: () => void = () => undefined
+    store.pdfService.hold = new Promise((resolve) => {
+      releaseRenders = resolve
+    })
+    const first = store.regenerate(String(invoice.id))
+    const second = store.regenerate(String(invoice.id))
+    while (store.pdfService.renders < 2) {
+      await new Promise((resolve) => setImmediate(resolve))
+    }
+    releaseRenders()
+    const answers = await Promise.all([first, second])
+
+    expect(answers.map((answer) => answer.status)).toEqual([200, 200])
+    expect(store.emails).toHaveLength(1)
+    expect(ledgerRows(store)).toHaveLength(1)
+    expect(historyLines(store)).toHaveLength(1)
+  })
+
+  it('Invoice Email Delivery off: the same regeneration emails nobody', async () => {
+    const delivering = openStore()
+    seedPaidOrder(delivering.db, ORDER_ID)
+    const deliveredInvoice = await payWhilePdfServiceIsDown(delivering, ORDER_ID)
+    await delivering.regenerate(String(deliveredInvoice.id))
+    expect(delivering.emails).toHaveLength(1)
+
+    const silent = openStore({ emailDelivery: false })
+    seedPaidOrder(silent.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(silent, ORDER_ID)
+    const regenerated = await silent.regenerate(String(invoice.id))
+
+    expect(regenerated.status).toBe(200)
+    expect(Number(invoice.pdf_size_bytes)).toBeGreaterThan(0)
+    expect(silent.emails).toHaveLength(0)
+    expect(ledgerRows(silent)).toHaveLength(0)
+    expect(historyLines(silent)).toHaveLength(0)
+    // The route does not even load the sender.
+    expect(silent.routeCode).not.toContain('email-sender')
+  })
+
+  it('a refused email still regenerates the invoice, is logged, and is never sent again', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+    store.provider.refuses = true
+
+    const regenerated = await store.regenerate(String(invoice.id))
+
+    // The merchant has the PDF, and the order links to it.
+    expect(regenerated.status).toBe(200)
+    expect(regenerated.body).toMatchObject({ success: true, invoiceNumber: 'INV-0001' })
+    expect(Number(invoice.pdf_size_bytes)).toBeGreaterThan(0)
+    expect(store.db.row('teleport_orders', ORDER_ID)).toMatchObject({
+      invoice_id: invoice.id,
+      invoice_number: 'INV-0001',
+      invoice_pdf_url: '/api/invoices/' + String(invoice.id) + '/pdf',
+    })
+    // The provider was asked once and refused: the ledger says so, the
+    // order's history does not claim an email went out, the log names it.
+    expect(store.emails).toHaveLength(1)
+    expect(ledgerRows(store)).toEqual([
+      expect.objectContaining({
+        status: 'failed',
+        error_message: '422 The From address is not a confirmed sender signature',
+      }),
+    ])
+    expect(historyLines(store)).toHaveLength(0)
+    expect(store.errors).toContainEqual(
+      expect.stringContaining('invoice INV-0001 could not be emailed to its customer')
+    )
+
+    store.provider.refuses = false
+    expect((await store.regenerate(String(invoice.id))).status).toBe(200)
+    expect(store.emails).toHaveLength(1)
+  })
+
+  it('an order that cannot be updated still gets its invoice emailed, once', async () => {
+    const store = openStore()
+    seedPaidOrder(store.db, ORDER_ID)
+    const invoice = await payWhilePdfServiceIsDown(store, ORDER_ID)
+    store.db.failNext(/^UPDATE teleport_orders SET invoice_id = \$1/, 'Connection terminated')
+
+    const failed = await store.regenerate(String(invoice.id))
+
+    // The invoice has its PDF, so its buyer is emailed it, with the link the
+    // database serves it from.
+    expect(failed.status).toBe(500)
+    expect(store.emails).toHaveLength(1)
+    expect(store.emails[0].HtmlBody).toContain('/api/invoices/' + String(invoice.id) + '/pdf')
+    expect(ledgerRows(store)).toHaveLength(1)
+
+    // Regenerating again links the order, and emails nobody.
+    expect((await store.regenerate(String(invoice.id))).status).toBe(200)
+    expect(store.db.row('teleport_orders', ORDER_ID)).toMatchObject({ invoice_id: invoice.id })
+    expect(store.emails).toHaveLength(1)
+    expect(historyLines(store)).toHaveLength(1)
+  })
+})

package/__tests__/invoice-regenerate-route.test.ts

@@ -16,8 +16,10 @@ import {
  *
  * Every test runs the EMITTED route against the REAL emitted assembly, with
  * the database, the PDF service and the session stubbed: a regenerated invoice
- * must be priced by exactly the code that issued it, keep its identity, take
- * the merchant's corrections over the order, and never email anybody.
+ * must be priced by exactly the code that issued it, keep its identity and
+ * take the merchant's corrections over the order. These run a store that does
+ * not email invoices; the one email a regeneration can send is proved in
+ * `invoice-regenerate-email.test.ts`.
  */
 
 const SETTINGS = {
@@ -27,7 +29,7 @@ const SETTINGS = {
   companyDetails: {},
   template: { document: null as unknown },
   tables: { invoicesTable: 'teleport_invoices', invoiceItemsTable: 'teleport_invoice_items' },
-  emailDelivery: { enabled: true, provider: 'postmark' },
+  emailDelivery: { enabled: false },
 } as unknown as UIDLInvoiceSettings
 
 type Row = Record<string, unknown>
@@ -190,7 +192,7 @@ async function run(options: RunOptions = {}): Promise<Harness> {
 
   const token = options.token === undefined ? { role: 'admin', id: 'u1' } : options.token
   const handler = evaluateEmittedModule<(req: unknown, res: unknown) => Promise<void>>(
-    generateInvoiceRegenerateRouteCode(),
+    generateInvoiceRegenerateRouteCode(SETTINGS),
     createInvoiceRouteRequire(SETTINGS, {
       dataAccess,
       pdfGenerator,
@@ -333,9 +335,9 @@ describe('/api/invoices/[id]/regenerate', () => {
     })
   })
 
-  it('never emails the customer', async () => {
+  it('never emails the customer of a store that does not email invoices', async () => {
     // The route does not even load the sender: a require of it would throw here.
-    const code = generateInvoiceRegenerateRouteCode()
+    const code = generateInvoiceRegenerateRouteCode(SETTINGS)
     expect(code).not.toContain('email-sender')
     expect(code).not.toContain('sendInvoiceEmail')
   })
@@ -402,7 +404,7 @@ describe('/api/invoices/generate — remembers where its PDF is stored', () => {
         invoiceData.invoiceNumber = 'INV-0009'
         return { invoice: invoiceData, created: true }
       },
-      storeInvoicePdf: async () => ({}),
+      storeInvoicePdf: async () => ({ firstPdf: true }),
       updateInvoice: async (id: string, fields: Row) => {
         updates.push({ id, fields })
         return fields

package/__tests__/invoice-reservation.test.ts

@@ -61,7 +61,7 @@ async function run(
     },
     storeInvoicePdf: async (id: string, pdf: Buffer) => {
       stored.push({ id, bytes: pdf.length })
-      return {}
+      return { firstPdf: true }
     },
     updateInvoice: async () => ({}),
   }

package/__tests__/invoice-tender.test.ts

@@ -86,7 +86,7 @@ async function runHandler(order: Row, items: Row[], body: Row): Promise<HandlerR
       invoice = invoiceData
       return { invoice: invoiceData, created: true }
     },
-    storeInvoicePdf: async () => ({}),
+    storeInvoicePdf: async () => ({ firstPdf: true }),
     updateInvoice: async () => ({}),
   }
   const pdfGeneratorStub = {

package/__tests__/middleware-admin-panel-roles.test.ts

@@ -0,0 +1,127 @@
+import { UIDLAuthentication } from '@teleporthq/teleport-types'
+import { generateMiddlewareFile } from '../src/auth-generator'
+import {
+  compileGeneratedMiddleware,
+  extractProtectedRoutes,
+} from './_helpers/run-generated-middleware'
+
+/**
+ * An admin panel whose folder admits admins only, some of whose pages (the
+ * dashboard first among them) also admit staff, whose built-in entities stay
+ * admin only, and whose project redirects the home page into the dashboard
+ * (`homeRedirect`). Two things must follow from the ADMIN FOLDER's protection,
+ * never from whichever page happens to come first:
+ *  - the `/admin` catch-all, which guards `/admin` itself and every admin page
+ *    the middleware has no entry for (one an owner added without protection);
+ *  - where a role denial lands: never `/` when `/` leads straight back into a
+ *    page the visitor may not open — that is a redirect loop.
+ */
+
+const page = (route: string, allowedRoles: string[]) => ({
+  requiresAuth: true,
+  allowedRoles,
+  pageName: route,
+  route,
+})
+
+const panelAuth = (homeRedirect?: string): UIDLAuthentication => ({
+  enabled: true,
+  dataSourceId: 'ds-1',
+  dataSourceType: 'teleport',
+  passwordAuthEnabled: true,
+  providers: [],
+  roles: ['admin', 'staff', 'user'],
+  tables: {},
+  // The dashboard is the first admin route, as the GUI emits it.
+  pageProtection: {
+    'p-dashboard': page('/admin/dashboard', ['admin', 'staff']),
+    'p-tasks': page('/admin/tasks', ['admin', 'staff']),
+    'p-users': page('/admin/users', ['admin']),
+  },
+  folderProtection: {
+    'f-admin': {
+      requiresAuth: true,
+      allowedRoles: ['admin'],
+      folderName: 'admin-panel',
+      parentId: 'pages',
+      children: { 'p-dashboard': 'page', 'f-tasks': 'folder', 'f-users': 'folder' },
+    },
+    'f-tasks': {
+      requiresAuth: true,
+      allowedRoles: ['admin', 'staff'],
+      folderName: 'tasks',
+      parentId: 'f-admin',
+      children: { 'p-tasks': 'page' },
+    },
+    'f-users': {
+      requiresAuth: true,
+      allowedRoles: ['admin'],
+      folderName: 'users',
+      parentId: 'f-admin',
+      children: { 'p-users': 'page' },
+    },
+  },
+  authPages: {
+    signIn: { pageId: 'p-sign-in', pageName: 'sign-in', route: '/auth/sign-in' },
+  },
+  callbackBaseUrl: '/api/auth/callback',
+  envKeys: {},
+  customUserProperties: [],
+  ...(homeRedirect ? { homeRedirect } : {}),
+})
+
+const ORIGIN = 'https://panel.test'
+
+describe('the /admin catch-all', () => {
+  it("admits the admin folder's roles, not the first admin page's", () => {
+    const routes = extractProtectedRoutes(generateMiddlewareFile(panelAuth('/admin/dashboard')))
+    expect(routes['/admin']).toEqual({ requiresAuth: true, allowedRoles: ['admin'] })
+  })
+
+  it('keeps staff out of an admin page the middleware has no entry for', async () => {
+    const run = compileGeneratedMiddleware(panelAuth('/admin/dashboard'))
+    const staff = { id: 's1', role: 'staff' }
+    expect(await run('/admin/reports', { sessionUser: staff, origin: ORIGIN })).toMatchObject({
+      kind: 'redirect',
+    })
+    expect(await run('/admin/tasks', { sessionUser: staff, origin: ORIGIN })).toEqual({
+      kind: 'next',
+    })
+    expect(
+      await run('/admin/reports', { sessionUser: { id: 'a1', role: 'admin' }, origin: ORIGIN })
+    ).toEqual({ kind: 'next' })
+  })
+})
+
+describe('a role denial when the home page redirects into the admin panel', () => {
+  const run = compileGeneratedMiddleware(panelAuth('/admin/dashboard'))
+  const signInLocation = (callbackUrl: string) =>
+    `${ORIGIN}/auth/sign-in?callbackUrl=${encodeURIComponent(callbackUrl)}&error=forbidden`
+
+  it('sends a signed-in account the panel does not admit to sign-in, explained — never to "/"', async () => {
+    const user = { id: 'u1', role: 'user' }
+    // "/" would redirect to the dashboard, which denies the role again: a loop.
+    expect(await run('/admin/dashboard', { sessionUser: user, origin: ORIGIN })).toEqual({
+      kind: 'redirect',
+      location: signInLocation('/admin/dashboard'),
+    })
+    expect(await run('/admin/users', { sessionUser: user, origin: ORIGIN })).toEqual({
+      kind: 'redirect',
+      location: signInLocation('/admin/users'),
+    })
+  })
+
+  it('still sends staff denied an admin-only page home, where the dashboard admits them', async () => {
+    expect(
+      await run('/admin/users', { sessionUser: { id: 's1', role: 'staff' }, origin: ORIGIN })
+    ).toEqual({ kind: 'redirect', location: `${ORIGIN}/` })
+  })
+
+  it('leaves a project whose home is not redirected as it was', () => {
+    const code = generateMiddlewareFile(panelAuth())
+    expect(code).toContain('function roleDeniedRedirect(request, pathname) {')
+    expect(code).toContain('return roleDeniedRedirect(request, pathname);')
+    expect(code).not.toContain('homeRedirect')
+    expect(code).not.toContain("'forbidden'")
+  })
+})