@podosoft/podokit 1.4.1 → 1.4.2

package/dist/templates/modules/admin-dashboard/files/tests/api/auth-config.api.spec.ts

@@ -4,6 +4,7 @@ import {
   isUserCreationAllowed,
 } from "../../apps/api/src/auth/feature-gate";
 import { ADMIN } from "../helpers/accounts";
+import { exclusive } from "../helpers/exclusive";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
@@ -17,62 +18,68 @@ async function adminCtx(playwright: import("@playwright/test").PlaywrightWorkerA
 }
 
 test("admin can enable Google OAuth from the DB and it applies without a restart", async ({ playwright }) => {
-  const admin = await adminCtx(playwright);
-  await admin.put("/api/account/auth-config", { data: { social: { google: { enabled: false } } } }); // clean start
-  const anon = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  const social = () => anon.post("/api/auth/sign-in/social", { data: { provider: "google", callbackURL: `${base}/admin` } });
-
-  // Before: provider not configured.
-  await expect.poll(async () => (await social()).status(), { timeout: 8000 }).toBe(404);
-
-  // Paste credentials via the admin API.
-  const put = await admin.put("/api/account/auth-config", {
-    data: { social: { google: { enabled: true, clientId: "dummy-google-client-id", clientSecret: "dummy-google-client-secret" } } },
+  test.slow();
+  await exclusive("social-providers", async () => {
+    const admin = await adminCtx(playwright);
+    await admin.put("/api/account/auth-config", { data: { social: { google: { enabled: false } } } }); // clean start
+    const anon = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+    const social = () => anon.post("/api/auth/sign-in/social", { data: { provider: "google", callbackURL: `${base}/admin` } });
+
+    // Before: provider not configured.
+    await expect.poll(async () => (await social()).status(), { timeout: 8000 }).toBe(404);
+
+    // Paste credentials via the admin API.
+    const put = await admin.put("/api/account/auth-config", {
+      data: { social: { google: { enabled: true, clientId: "dummy-google-client-id", clientSecret: "dummy-google-client-secret" } } },
+    });
+    expect(put.ok()).toBeTruthy();
+    const view = await put.json();
+    expect(view.social.google.enabled).toBe(true);
+    expect(view.social.google.hasSecret).toBe(true);
+    expect(view.social.google.clientId).toBe("dummy-google-client-id");
+    expect("clientSecret" in view.social.google).toBe(false); // secret is never returned
+
+    // Applied live (no restart): social sign-in now redirects to Google.
+    await expect
+      .poll(async () => {
+        const r = await social();
+        return r.ok() ? (((await r.json())?.url as string) ?? "") : "";
+      }, { timeout: 8000 })
+      .toContain("accounts.google.com");
+    const caps = await (await anon.get("/api/account/capabilities")).json();
+    expect(caps.providers).toContain("google");
+
+    await admin.put("/api/account/auth-config", { data: { social: { google: { enabled: false } } } }); // restore
+    await anon.dispose();
+    await admin.dispose();
   });
-  expect(put.ok()).toBeTruthy();
-  const view = await put.json();
-  expect(view.social.google.enabled).toBe(true);
-  expect(view.social.google.hasSecret).toBe(true);
-  expect(view.social.google.clientId).toBe("dummy-google-client-id");
-  expect("clientSecret" in view.social.google).toBe(false); // secret is never returned
-
-  // Applied live (no restart): social sign-in now redirects to Google.
-  await expect
-    .poll(async () => {
-      const r = await social();
-      return r.ok() ? (((await r.json())?.url as string) ?? "") : "";
-    }, { timeout: 8000 })
-    .toContain("accounts.google.com");
-  const caps = await (await anon.get("/api/account/capabilities")).json();
-  expect(caps.providers).toContain("google");
-
-  await admin.put("/api/account/auth-config", { data: { social: { google: { enabled: false } } } }); // restore
-  await anon.dispose();
-  await admin.dispose();
 });
 
 test("admin can add and remove a social provider dynamically", async ({ playwright }) => {
-  const admin = await adminCtx(playwright);
-  // The catalog offers providers beyond the two legacy env-backed ones.
-  const catalog = (await (await admin.get("/api/account/auth-config")).json()).catalog as Array<{ id: string }>;
-  expect(catalog.map((c) => c.id)).toEqual(expect.arrayContaining(["google", "github", "apple"]));
+  test.slow();
+  await exclusive("social-providers", async () => {
+    const admin = await adminCtx(playwright);
+    // The catalog offers providers beyond the two legacy env-backed ones.
+    const catalog = (await (await admin.get("/api/account/auth-config")).json()).catalog as Array<{ id: string }>;
+    expect(catalog.map((c) => c.id)).toEqual(expect.arrayContaining(["google", "github", "apple"]));
+
+    const anon = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+    const github = () => anon.post("/api/auth/sign-in/social", { data: { provider: "github", callbackURL: `${base}/admin` } });
+
+    // Add GitHub (a provider with no env fallback) → applies live, no restart.
+    await admin.put("/api/account/auth-config", { data: { social: { github: { enabled: true, clientId: "dummy-github-client-id", clientSecret: "dummy-github-client-secret" } } } });
+    await expect
+      .poll(async () => { const r = await github(); return r.ok() ? (((await r.json())?.url as string) ?? "") : ""; }, { timeout: 8000 })
+      .toContain("github.com");
+
+    // Remove it → the row is deleted and the provider stops working (again live).
+    await admin.put("/api/account/auth-config", { data: { social: { github: { delete: true } } } });
+    expect("github" in (await (await admin.get("/api/account/auth-config")).json()).social).toBe(false);
+    await expect.poll(async () => (await github()).status(), { timeout: 8000 }).toBe(404);
 
-  const anon = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  const github = () => anon.post("/api/auth/sign-in/social", { data: { provider: "github", callbackURL: `${base}/admin` } });
-
-  // Add GitHub (a provider with no env fallback) → applies live, no restart.
-  await admin.put("/api/account/auth-config", { data: { social: { github: { enabled: true, clientId: "dummy-github-client-id", clientSecret: "dummy-github-client-secret" } } } });
-  await expect
-    .poll(async () => { const r = await github(); return r.ok() ? (((await r.json())?.url as string) ?? "") : ""; }, { timeout: 8000 })
-    .toContain("github.com");
-
-  // Remove it → the row is deleted and the provider stops working (again live).
-  await admin.put("/api/account/auth-config", { data: { social: { github: { delete: true } } } });
-  expect("github" in (await (await admin.get("/api/account/auth-config")).json()).social).toBe(false);
-  await expect.poll(async () => (await github()).status(), { timeout: 8000 }).toBe(404);
-
-  await anon.dispose();
-  await admin.dispose();
+    await anon.dispose();
+    await admin.dispose();
+  });
 });
 
 test("auth-config is admin-only and never leaks secrets @smoke", async ({ playwright }) => {
@@ -85,43 +92,46 @@ test("auth-config is admin-only and never leaks secrets @smoke", async ({ playwr
 });
 
 test("automatic logout validates and applies a sliding session lifetime", async ({ playwright }) => {
-  const admin = await adminCtx(playwright);
-  const freshAdmin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-
-  try {
-    expect(
-      (await admin.put("/api/account/auth-config", {
-        data: { server: { sessionIdleTimeoutMinutes: 4 } },
-      })).status(),
-    ).toBe(400);
-
-    const enabled = await admin.put("/api/account/auth-config", {
-      data: { server: { sessionIdleTimeoutMinutes: 30 } },
-    });
-    expect(enabled.ok()).toBeTruthy();
-    expect((await enabled.json()).server.sessionIdleTimeoutMinutes).toBe(30);
-
-    const caps = await (await admin.get("/api/account/capabilities")).json();
-    expect(caps.sessionIdleTimeoutMinutes).toBe(30);
-
-    const signIn = await freshAdmin.post("/api/auth/sign-in/email", {
-      data: { email: ADMIN.email, password: ADMIN.password },
-    });
-    expect(signIn.ok()).toBeTruthy();
-    expect(signIn.headers()["set-cookie"]).toMatch(/Max-Age=1800(?:;|,)/i);
-
-    const sessions = (await (await admin.get("/api/auth/list-sessions")).json()) as Array<{
-      expiresAt: string;
-    }>;
-    const latestExpiry = Math.max(...sessions.map((session) => new Date(session.expiresAt).getTime()));
-    expect(latestExpiry).toBeLessThanOrEqual(Date.now() + 30 * 60_000 + 10_000);
-  } finally {
-    await admin.put("/api/account/auth-config", {
-      data: { server: { sessionIdleTimeoutMinutes: null } },
-    });
-    await freshAdmin.dispose();
-    await admin.dispose();
-  }
+  test.slow();
+  await exclusive("session-idle-timeout", async () => {
+    const admin = await adminCtx(playwright);
+    const freshAdmin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+
+    try {
+      expect(
+        (await admin.put("/api/account/auth-config", {
+          data: { server: { sessionIdleTimeoutMinutes: 4 } },
+        })).status(),
+      ).toBe(400);
+
+      const enabled = await admin.put("/api/account/auth-config", {
+        data: { server: { sessionIdleTimeoutMinutes: 30 } },
+      });
+      expect(enabled.ok()).toBeTruthy();
+      expect((await enabled.json()).server.sessionIdleTimeoutMinutes).toBe(30);
+
+      const caps = await (await admin.get("/api/account/capabilities")).json();
+      expect(caps.sessionIdleTimeoutMinutes).toBe(30);
+
+      const signIn = await freshAdmin.post("/api/auth/sign-in/email", {
+        data: { email: ADMIN.email, password: ADMIN.password },
+      });
+      expect(signIn.ok()).toBeTruthy();
+      expect(signIn.headers()["set-cookie"]).toMatch(/Max-Age=1800(?:;|,)/i);
+
+      const sessions = (await (await admin.get("/api/auth/list-sessions")).json()) as Array<{
+        expiresAt: string;
+      }>;
+      const latestExpiry = Math.max(...sessions.map((session) => new Date(session.expiresAt).getTime()));
+      expect(latestExpiry).toBeLessThanOrEqual(Date.now() + 30 * 60_000 + 10_000);
+    } finally {
+      await admin.put("/api/account/auth-config", {
+        data: { server: { sessionIdleTimeoutMinutes: null } },
+      });
+      await freshAdmin.dispose();
+      await admin.dispose();
+    }
+  });
 });
 
 test("new registrations require approval when the policy is enabled", async ({ playwright }) => {
@@ -204,75 +214,78 @@ test("new registrations require approval when the policy is enabled", async ({ p
 });
 
 test("closed public sign-up blocks new OAuth users but preserves existing sign-in", async ({ playwright }) => {
-  const admin = await adminCtx(playwright);
-  const anon = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  const password = "Podokit3e-Str0ng!pw";
-  const adminCreatedEmail = `closed-admin-${Date.now()}@example.com`;
-  const initialSite = (await (await anon.get("/api/site/settings")).json()) as {
-    allowSignup?: string | null;
-  };
-  const initialAllowSignup = initialSite.allowSignup === "false" ? "false" : "true";
-  let adminCreatedId = "";
-
-  try {
-    expect(
-      (await admin.put("/api/account/auth-config", {
-        data: {
-          social: {
-            google: {
-              enabled: true,
-              clientId: "dummy-google-client-id",
-              clientSecret: "dummy-google-client-secret",
+  test.slow();
+  await exclusive(["site-general", "social-providers"], async () => {
+    const admin = await adminCtx(playwright);
+    const anon = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+    const password = "Podokit3e-Str0ng!pw";
+    const adminCreatedEmail = `closed-admin-${Date.now()}@example.com`;
+    const initialSite = (await (await anon.get("/api/site/settings")).json()) as {
+      allowSignup?: string | null;
+    };
+    const initialAllowSignup = initialSite.allowSignup === "false" ? "false" : "true";
+    let adminCreatedId = "";
+
+    try {
+      expect(
+        (await admin.put("/api/account/auth-config", {
+          data: {
+            social: {
+              google: {
+                enabled: true,
+                clientId: "dummy-google-client-id",
+                clientSecret: "dummy-google-client-secret",
+              },
             },
           },
-        },
-      })).ok(),
-    ).toBeTruthy();
-    expect((await admin.put("/api/site/settings", { data: { allowSignup: "false" } })).ok()).toBeTruthy();
+        })).ok(),
+      ).toBeTruthy();
+      expect((await admin.put("/api/site/settings", { data: { allowSignup: "false" } })).ok()).toBeTruthy();
 
-    // The site policy uses a short cache shared by sign-up requests and user
-    // creation hooks, so wait for the setting to become live.
-    await new Promise((resolve) => setTimeout(resolve, 3_200));
-
-    const signup = await anon.post("/api/auth/sign-up/email", {
-      data: {
-        email: `closed-${Date.now()}@example.com`,
-        password,
-        name: "Closed Registration",
-      },
-    });
-    expect(signup.status()).toBe(403);
-    expect((await signup.json()).code).toBe(PUBLIC_SIGNUP_DISABLED);
+      // The site policy uses a short cache shared by sign-up requests and user
+      // creation hooks, so wait for the setting to become live.
+      await new Promise((resolve) => setTimeout(resolve, 3_200));
 
-    // OAuth initiation must stay available for existing social users. Only a
-    // callback that attempts to create a new user is rejected by the DB hook.
-    const social = await anon.post("/api/auth/sign-in/social", {
-      data: { provider: "google", callbackURL: `${base}/` },
-    });
-    expect(social.ok()).toBeTruthy();
-    expect(((await social.json()).url as string)).toContain("accounts.google.com");
-    expect(isUserCreationAllowed(false, "/callback/google")).toBe(false);
-    expect(isUserCreationAllowed(false, undefined)).toBe(false);
-
-    // Deliberate administrator provisioning remains available while the public
-    // site is closed.
-    expect(isUserCreationAllowed(false, "/admin/create-user")).toBe(true);
-    const adminCreated = await admin.post("/api/auth/admin/create-user", {
-      data: { email: adminCreatedEmail, password, name: "Admin Created", role: "user" },
-    });
-    expect(adminCreated.ok()).toBeTruthy();
-    adminCreatedId = ((await adminCreated.json()).user as { id: string }).id;
-  } finally {
-    if (adminCreatedId) {
-      await admin.post("/api/auth/admin/remove-user", { data: { userId: adminCreatedId } });
+      const signup = await anon.post("/api/auth/sign-up/email", {
+        data: {
+          email: `closed-${Date.now()}@example.com`,
+          password,
+          name: "Closed Registration",
+        },
+      });
+      expect(signup.status()).toBe(403);
+      expect((await signup.json()).code).toBe(PUBLIC_SIGNUP_DISABLED);
+
+      // OAuth initiation must stay available for existing social users. Only a
+      // callback that attempts to create a new user is rejected by the DB hook.
+      const social = await anon.post("/api/auth/sign-in/social", {
+        data: { provider: "google", callbackURL: `${base}/` },
+      });
+      expect(social.ok()).toBeTruthy();
+      expect(((await social.json()).url as string)).toContain("accounts.google.com");
+      expect(isUserCreationAllowed(false, "/callback/google")).toBe(false);
+      expect(isUserCreationAllowed(false, undefined)).toBe(false);
+
+      // Deliberate administrator provisioning remains available while the public
+      // site is closed.
+      expect(isUserCreationAllowed(false, "/admin/create-user")).toBe(true);
+      const adminCreated = await admin.post("/api/auth/admin/create-user", {
+        data: { email: adminCreatedEmail, password, name: "Admin Created", role: "user" },
+      });
+      expect(adminCreated.ok()).toBeTruthy();
+      adminCreatedId = ((await adminCreated.json()).user as { id: string }).id;
+    } finally {
+      if (adminCreatedId) {
+        await admin.post("/api/auth/admin/remove-user", { data: { userId: adminCreatedId } });
+      }
+      await admin.put("/api/site/settings", { data: { allowSignup: initialAllowSignup } });
+      await admin.put("/api/account/auth-config", {
+        data: { social: { google: { enabled: false } } },
+      });
+      await new Promise((resolve) => setTimeout(resolve, 3_200));
+      await anon.get("/api/auth/get-session");
+      await anon.dispose();
+      await admin.dispose();
     }
-    await admin.put("/api/site/settings", { data: { allowSignup: initialAllowSignup } });
-    await admin.put("/api/account/auth-config", {
-      data: { social: { google: { enabled: false } } },
-    });
-    await new Promise((resolve) => setTimeout(resolve, 3_200));
-    await anon.get("/api/auth/get-session");
-    await anon.dispose();
-    await admin.dispose();
-  }
+  });
 });

package/dist/templates/modules/admin-dashboard/files/tests/api/auth.api.spec.ts

@@ -1,6 +1,7 @@
 import { expect, test } from "@playwright/test";
 import { createPublicKey, verify, type JsonWebKey } from "node:crypto";
 import { ADMIN, USER } from "../helpers/accounts";
+import { exclusive } from "../helpers/exclusive";
 import { clearSms, smsSinkReachable, waitForSmsOtp } from "../helpers/sms";
 import { totpCode } from "../helpers/totp";
 
@@ -144,46 +145,49 @@ test("two-factor: regenerating backup codes invalidates the old set", async ({ p
 });
 
 test("require-2fa: gates an un-enrolled user until they enrol", async ({ playwright }) => {
-  const admin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  const caps = await (await admin.get("/api/account/capabilities")).json();
-  test.skip(!caps?.twoFactor, "two-factor not enabled");
-  await admin.post("/api/auth/sign-in/email", { data: { email: ADMIN.email, password: ADMIN.password } });
-
-  const user = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  const email = `rq-${Date.now()}@example.com`;
-  const pw = "Podokit3e-Str0ng!pw";
-  await user.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "RQ" } });
-
-  try {
-    // Turn the policy on (admin; the toggle endpoint is allow-listed by the guard).
-    await admin.put("/api/account/settings", { data: { require2fa: true } });
-    // Capabilities carry the same policy as the dedicated endpoint.
-    await expect(async () => {
-      expect((await (await admin.get("/api/account/capabilities")).json()).require2fa).toBe(true);
-      expect(await (await admin.get("/api/account/require-2fa")).json()).toEqual({ require2fa: true });
-    }).toPass({ timeout: 8000 });
-    // The guard caches for a few seconds — poll until the un-enrolled user is gated.
-    await expect(async () => {
-      expect((await user.get("/api/account/me")).status()).toBe(403);
-    }).toPass({ timeout: 8000 });
-
-    // Enrolling restores access.
-    const enable = await (await user.post("/api/auth/two-factor/enable", { data: { password: pw } })).json();
-    await user.post("/api/auth/two-factor/verify-totp", { data: { code: totpCode(enable.totpURI) } });
-    expect((await user.get("/api/account/me")).status()).toBe(200);
-  } finally {
-    // Always turn it back off so the shared (un-enrolled) sessions aren't gated.
-    await admin.put("/api/account/settings", { data: { require2fa: false } });
-    await expect(async () => {
-      const probe = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-      await probe.post("/api/auth/sign-in/email", { data: { email: USER.email, password: USER.password } });
-      const status = (await probe.get("/api/account/me")).status();
-      await probe.dispose();
-      expect(status).toBe(200);
-    }).toPass({ timeout: 8000 });
-    await admin.dispose();
-    await user.dispose();
-  }
+  test.slow();
+  await exclusive("require2fa", async () => {
+    const admin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+    const caps = await (await admin.get("/api/account/capabilities")).json();
+    test.skip(!caps?.twoFactor, "two-factor not enabled");
+    await admin.post("/api/auth/sign-in/email", { data: { email: ADMIN.email, password: ADMIN.password } });
+
+    const user = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+    const email = `rq-${Date.now()}@example.com`;
+    const pw = "Podokit3e-Str0ng!pw";
+    await user.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "RQ" } });
+
+    try {
+      // Turn the policy on (admin; the toggle endpoint is allow-listed by the guard).
+      await admin.put("/api/account/settings", { data: { require2fa: true } });
+      // Capabilities carry the same policy as the dedicated endpoint.
+      await expect(async () => {
+        expect((await (await admin.get("/api/account/capabilities")).json()).require2fa).toBe(true);
+        expect(await (await admin.get("/api/account/require-2fa")).json()).toEqual({ require2fa: true });
+      }).toPass({ timeout: 8000 });
+      // The guard caches for a few seconds — poll until the un-enrolled user is gated.
+      await expect(async () => {
+        expect((await user.get("/api/account/me")).status()).toBe(403);
+      }).toPass({ timeout: 8000 });
+
+      // Enrolling restores access.
+      const enable = await (await user.post("/api/auth/two-factor/enable", { data: { password: pw } })).json();
+      await user.post("/api/auth/two-factor/verify-totp", { data: { code: totpCode(enable.totpURI) } });
+      expect((await user.get("/api/account/me")).status()).toBe(200);
+    } finally {
+      // Always turn it back off so the shared (un-enrolled) sessions aren't gated.
+      await admin.put("/api/account/settings", { data: { require2fa: false } });
+      await expect(async () => {
+        const probe = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+        await probe.post("/api/auth/sign-in/email", { data: { email: USER.email, password: USER.password } });
+        const status = (await probe.get("/api/account/me")).status();
+        await probe.dispose();
+        expect(status).toBe(200);
+      }).toPass({ timeout: 8000 });
+      await admin.dispose();
+      await user.dispose();
+    }
+  });
 });
 
 test("multi-session holds several accounts and switches between them", async ({ playwright }) => {
@@ -380,9 +384,39 @@ test("an organization can have a parent and manager members", async ({ playwrigh
   await ctx.dispose();
 });
 
-// OIDC discovery + the enabled/disabled behaviour is covered by the front-channel
-// test in tests/ui/oidc.ui.spec.ts (which owns toggling the oidcProvider flag), and
-// the server-side gate is covered generically by the feature-toggle test above.
+test("the OIDC provider's discovery and endpoints follow its setting", async ({ playwright }) => {
+  // The provider's metadata is answered before endpoint hooks run, so it needs its
+  // own check that "off" hides it. The lock keeps tests/ui/oidc.ui.spec.ts, which
+  // also toggles the provider, from running at the same time.
+  test.slow();
+  const admin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  await admin.post("/api/auth/sign-in/email", { data: { email: ADMIN.email, password: ADMIN.password } });
+  const status = (path: string): Promise<number> => admin.get(path).then((r) => r.status());
+  const discovery = [
+    "/api/auth/.well-known/openid-configuration",
+    "/api/auth/.well-known/oauth-authorization-server",
+  ];
+  const allStatuses = (): Promise<number[]> =>
+    Promise.all([...discovery, "/api/auth/oauth2/authorize?client_id=probe"].map(status));
+
+  await exclusive("oidc-provider", async () => {
+    try {
+      expect((await admin.put("/api/account/settings", { data: { oidcProvider: false } })).ok()).toBeTruthy();
+      await expect.poll(allStatuses, { timeout: 8000 }).toEqual([404, 404, 404]);
+      // The jwt plugin's keys and session tokens are not part of the provider.
+      expect(await status("/api/auth/jwks")).toBe(200);
+
+      expect((await admin.put("/api/account/settings", { data: { oidcProvider: true } })).ok()).toBeTruthy();
+      await expect.poll(() => Promise.all(discovery.map(status)), { timeout: 8000 }).toEqual([200, 200]);
+      const metadata = await (await admin.get(discovery[0]!)).json();
+      expect(metadata.authorization_endpoint).toContain("/api/auth/oauth2/authorize");
+    } finally {
+      expect((await admin.put("/api/account/settings", { data: { oidcProvider: false } })).ok()).toBeTruthy();
+    }
+    await expect.poll(allStatuses, { timeout: 8000 }).toEqual([404, 404, 404]);
+  });
+  await admin.dispose();
+});
 
 test("only admins can change settings @smoke", async ({ playwright }) => {
   const userCtx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
@@ -393,24 +427,27 @@ test("only admins can change settings @smoke", async ({ playwright }) => {
 });
 
 test("disabling a feature blocks its endpoint server-side and re-enabling restores it @smoke", async ({ playwright }) => {
-  // Uses a fresh admin context (not the shared storageState) so it never rotates
-  // the seeded session. Toggles a flag and confirms the feature gate enforces it.
-  const admin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  await admin.post("/api/auth/sign-in/email", { data: { email: ADMIN.email, password: ADMIN.password } });
-  const caps = await (await admin.get("/api/account/capabilities")).json();
-  test.skip(!caps?.magicLink, "magic link not enabled");
+  test.slow();
+  await exclusive("magic-link", async () => {
+    // Uses a fresh admin context (not the shared storageState) so it never rotates
+    // the seeded session. Toggles a flag and confirms the feature gate enforces it.
+    const admin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+    await admin.post("/api/auth/sign-in/email", { data: { email: ADMIN.email, password: ADMIN.password } });
+    const caps = await (await admin.get("/api/account/capabilities")).json();
+    test.skip(!caps?.magicLink, "magic link not enabled");
 
-  // A disabled feature's endpoint 404s; the gate reads the flag through a short cache.
-  const status = (): Promise<number> =>
-    admin.post("/api/auth/sign-in/magic-link", { data: { email: "probe@example.com" } }).then((r) => r.status());
+    // A disabled feature's endpoint 404s; the gate reads the flag through a short cache.
+    const status = (): Promise<number> =>
+      admin.post("/api/auth/sign-in/magic-link", { data: { email: "probe@example.com" } }).then((r) => r.status());
 
-  expect((await admin.put("/api/account/settings", { data: { magicLink: false } })).ok()).toBeTruthy();
-  await expect.poll(status, { timeout: 8000 }).toBe(404);
+    expect((await admin.put("/api/account/settings", { data: { magicLink: false } })).ok()).toBeTruthy();
+    await expect.poll(status, { timeout: 8000 }).toBe(404);
 
-  expect((await admin.put("/api/account/settings", { data: { magicLink: true } })).ok()).toBeTruthy();
-  await expect.poll(status, { timeout: 8000 }).not.toBe(404);
+    expect((await admin.put("/api/account/settings", { data: { magicLink: true } })).ok()).toBeTruthy();
+    await expect.poll(status, { timeout: 8000 }).not.toBe(404);
 
-  await admin.dispose();
+    await admin.dispose();
+  });
 });
 
 test("sign-in with a wrong password is rejected", async ({ request }) => {

package/dist/templates/modules/admin-dashboard/files/tests/api/exclusive.api.spec.ts

@@ -0,0 +1,75 @@
+import { expect, test } from "@playwright/test";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, utimesSync, writeFileSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { exclusive, lockPath } from "../helpers/exclusive";
+
+// Checks the lock that specs changing shared settings hold. Names are unique per
+// run so these never wait on, or release, a lock a real spec holds.
+const unique = (label: string): string => `self-test-${label}-${process.pid}-${Date.now()}`;
+
+test("exclusive releases its locks when the body fails", async () => {
+  const first = unique("first");
+  const second = unique("second");
+  await expect(
+    exclusive([second, first], async () => {
+      expect(existsSync(lockPath(first))).toBe(true);
+      expect(existsSync(lockPath(second))).toBe(true);
+      throw new Error("body failed");
+    }),
+  ).rejects.toThrow("body failed");
+  expect(existsSync(lockPath(first))).toBe(false);
+  expect(existsSync(lockPath(second))).toBe(false);
+
+  // The next holder gets the lock without waiting.
+  const started = Date.now();
+  await exclusive(first, async () => undefined);
+  expect(Date.now() - started).toBeLessThan(1_000);
+});
+
+test("exclusive runs holders of one lock one at a time", async () => {
+  const name = unique("serial");
+  const events: string[] = [];
+  const hold = (id: string): Promise<void> =>
+    exclusive(name, async () => {
+      events.push(`${id} start`);
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      events.push(`${id} end`);
+    });
+  await Promise.all([hold("a"), hold("b")]);
+  expect(events.map((event) => event.split(" ")[1])).toEqual(["start", "end", "start", "end"]);
+  expect(existsSync(lockPath(name))).toBe(false);
+});
+
+test("exclusive takes over a lock left by a run that was killed", async () => {
+  const name = unique("stale");
+  mkdirSync(lockPath(name));
+  const longAgo = new Date(Date.now() - 10 * 60_000);
+  utimesSync(lockPath(name), longAgo, longAgo);
+  await expect(exclusive(name, async () => "acquired")).resolves.toBe("acquired");
+  expect(existsSync(lockPath(name))).toBe(false);
+});
+
+test("exclusive takes over a lock whose holder exited, such as after Ctrl-C", async () => {
+  const name = unique("exited");
+  const exited = spawnSync(process.execPath, ["-e", ""]).pid;
+  mkdirSync(lockPath(name));
+  writeFileSync(join(lockPath(name), "owner"), String(exited));
+  const started = Date.now();
+  await expect(exclusive(name, async () => "acquired")).resolves.toBe("acquired");
+  expect(Date.now() - started).toBeLessThan(1_000);
+  expect(existsSync(lockPath(name))).toBe(false);
+});
+
+test("exclusive waits for a lock whose holder is still running", async () => {
+  const name = unique("alive");
+  mkdirSync(lockPath(name));
+  writeFileSync(join(lockPath(name), "owner"), String(process.pid));
+  const waiting = exclusive(name, async () => "acquired");
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  expect(existsSync(lockPath(name))).toBe(true);
+  // The holder finishes; the waiter then gets the lock.
+  await rm(lockPath(name), { recursive: true, force: true });
+  await expect(waiting).resolves.toBe("acquired");
+});