@podosoft/podokit 1.4.0 → 1.4.2

package/dist/templates/modules/admin-dashboard/files/tests/ui/settings.ui.spec.ts

@@ -1,5 +1,6 @@
 import { expect, test, type Page } from "@playwright/test";
 import { ready } from "../helpers/hydration";
+import { exclusive } from "../helpers/exclusive";
 
 // admin storageState (project default)
 
@@ -30,16 +31,19 @@ test("general settings: shows the favicon uploader", async ({ page }) => {
 });
 
 test("general settings: edit the site name, save, and apply live", async ({ page }) => {
-  await ready(page, "/admin/settings");
-  const name = page.getByLabel("Site name");
-  const original = await name.inputValue();
-  await name.fill("PodoKit Test Site");
-  await saveGeneral(page);
-  // the browser tab title reflects the new name live (no reload)
-  await expect(page).toHaveTitle("PodoKit Test Site");
-  // restore so other specs start clean
-  await name.fill(original);
-  await saveGeneral(page);
+  test.slow();
+  await exclusive("site-general", async () => {
+    await ready(page, "/admin/settings");
+    const name = page.getByLabel("Site name");
+    const original = await name.inputValue();
+    await name.fill("PodoKit Test Site");
+    await saveGeneral(page);
+    // the browser tab title reflects the new name live (no reload)
+    await expect(page).toHaveTitle("PodoKit Test Site");
+    // restore so other specs start clean
+    await name.fill(original);
+    await saveGeneral(page);
+  });
 });
 
 test("settings lists the auth features under the Authentication tab", async ({ page }) => {
@@ -69,18 +73,21 @@ test("settings is reachable from the sidebar", async ({ page }) => {
 });
 
 test("admin can toggle a feature flag and it applies live @smoke", async ({ page }) => {
-  await ready(page, "/admin/settings");
-  await page.getByRole("tab", { name: "Authentication" }).click();
-  const toggle = page.getByRole("switch", { name: "Magic link" });
-  test.skip((await toggle.count()) === 0, "magic link toggle not present");
-  // Serial workers (workers:1) make toggle-then-restore safe for other specs.
-  await expect(toggle).toBeChecked();
-  await toggle.click();
-  await expect(page.getByText("Setting updated")).toBeVisible();
-  await expect(toggle).not.toBeChecked(); // capabilities refreshed live
-  // restore so the shared magic-link/2FA specs keep their expected state
-  await toggle.click();
-  await expect(toggle).toBeChecked();
+  test.slow();
+  await exclusive("magic-link", async () => {
+    await ready(page, "/admin/settings");
+    await page.getByRole("tab", { name: "Authentication" }).click();
+    const toggle = page.getByRole("switch", { name: "Magic link" });
+    test.skip((await toggle.count()) === 0, "magic link toggle not present");
+    // The magic-link lock keeps the API spec that toggles the same flag out.
+    await expect(toggle).toBeChecked();
+    await toggle.click();
+    await expect(page.getByText("Setting updated")).toBeVisible();
+    await expect(toggle).not.toBeChecked(); // capabilities refreshed live
+    // restore so the shared magic-link/2FA specs keep their expected state
+    await toggle.click();
+    await expect(toggle).toBeChecked();
+  });
 });
 
 test("settings: the require-two-factor toggle is available", async ({ page }) => {
@@ -95,68 +102,71 @@ test("settings: the require-two-factor toggle is available", async ({ page }) =>
 });
 
 test("inactive browser sessions are signed out automatically @smoke", async ({ browser, page: adminPage }) => {
-  // Idle sign-out revokes the active server session. Use a dedicated login so
-  // this test cannot invalidate the shared admin storageState used by later specs.
-  const context = await browser.newContext({ baseURL: base });
-  const page = await context.newPage();
-  const email = `idle-admin-${Date.now()}@example.com`;
-  let signOutRequests = 0;
-  let userId = "";
-  try {
-    const created = await adminPage.request.post("/api/auth/admin/create-user", {
-      headers: { origin: base },
-      data: { email, password: "Podokit3e-Str0ng!pw", name: "Idle Admin", role: "admin" },
-    });
-    expect(created.ok()).toBeTruthy();
-    userId = ((await created.json()).user?.id ?? "") as string;
-    expect(userId).toBeTruthy();
-
-    const signIn = await context.request.post("/api/auth/sign-in/email", {
-      headers: { origin: base },
-      data: { email, password: "Podokit3e-Str0ng!pw" },
-    });
-    expect(signIn.ok()).toBeTruthy();
-
-    const configured = await context.request.put("/api/account/auth-config", {
-      data: { server: { sessionIdleTimeoutMinutes: 5 } },
-    });
-    expect(configured.ok()).toBeTruthy();
-    await page.route("**/api/auth/sign-out", async (route) => {
-      signOutRequests += 1;
-      await route.fulfill({ status: 200, contentType: "application/json", body: '{"success":true}' });
-    });
-    await page.clock.install();
-
+  test.slow();
+  await exclusive("session-idle-timeout", async () => {
+    // Idle sign-out revokes the active server session. Use a dedicated login so
+    // this test cannot invalidate the shared admin storageState used by later specs.
+    const context = await browser.newContext({ baseURL: base });
+    const page = await context.newPage();
+    const email = `idle-admin-${Date.now()}@example.com`;
+    let signOutRequests = 0;
+    let userId = "";
     try {
-      await ready(page, "/admin");
-      await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
-    } finally {
-      // Keep the loaded page policy at five minutes while restoring the shared
-      // DB policy before the isolated session is revoked.
-      const restored = await context.request.put("/api/account/auth-config", {
-        data: { server: { sessionIdleTimeoutMinutes: null } },
+      const created = await adminPage.request.post("/api/auth/admin/create-user", {
+        headers: { origin: base },
+        data: { email, password: "Podokit3e-Str0ng!pw", name: "Idle Admin", role: "admin" },
       });
-      expect(restored.ok()).toBeTruthy();
-    }
+      expect(created.ok()).toBeTruthy();
+      userId = ((await created.json()).user?.id ?? "") as string;
+      expect(userId).toBeTruthy();
 
-    const removed = await adminPage.request.post("/api/auth/admin/remove-user", {
-      headers: { origin: base },
-      data: { userId },
-    });
-    expect(removed.ok()).toBeTruthy();
-    userId = "";
-
-    await page.clock.fastForward(5 * 60_000 + 1_000);
-    await expect.poll(() => signOutRequests).toBe(1);
-    await expect(page).toHaveURL(/\/login\?reason=idle$/);
-    await expect(page.getByTestId("session-timeout-message")).toBeVisible();
-  } finally {
-    if (userId) {
-      await adminPage.request.post("/api/auth/admin/remove-user", {
+      const signIn = await context.request.post("/api/auth/sign-in/email", {
+        headers: { origin: base },
+        data: { email, password: "Podokit3e-Str0ng!pw" },
+      });
+      expect(signIn.ok()).toBeTruthy();
+
+      const configured = await context.request.put("/api/account/auth-config", {
+        data: { server: { sessionIdleTimeoutMinutes: 5 } },
+      });
+      expect(configured.ok()).toBeTruthy();
+      await page.route("**/api/auth/sign-out", async (route) => {
+        signOutRequests += 1;
+        await route.fulfill({ status: 200, contentType: "application/json", body: '{"success":true}' });
+      });
+      await page.clock.install();
+
+      try {
+        await ready(page, "/admin");
+        await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
+      } finally {
+        // Keep the loaded page policy at five minutes while restoring the shared
+        // DB policy before the isolated session is revoked.
+        const restored = await context.request.put("/api/account/auth-config", {
+          data: { server: { sessionIdleTimeoutMinutes: null } },
+        });
+        expect(restored.ok()).toBeTruthy();
+      }
+
+      const removed = await adminPage.request.post("/api/auth/admin/remove-user", {
         headers: { origin: base },
         data: { userId },
       });
+      expect(removed.ok()).toBeTruthy();
+      userId = "";
+
+      await page.clock.fastForward(5 * 60_000 + 1_000);
+      await expect.poll(() => signOutRequests).toBe(1);
+      await expect(page).toHaveURL(/\/login\?reason=idle$/);
+      await expect(page.getByTestId("session-timeout-message")).toBeVisible();
+    } finally {
+      if (userId) {
+        await adminPage.request.post("/api/auth/admin/remove-user", {
+          headers: { origin: base },
+          data: { userId },
+        });
+      }
+      await context.close();
     }
-    await context.close();
-  }
+  });
 });

package/dist/templates/modules/admin-dashboard/files/tests/ui/two-factor.ui.spec.ts

@@ -1,6 +1,7 @@
 import { expect, test, type Page } from "@playwright/test";
 import { ADMIN, USER, anonState } from "../helpers/accounts";
 import { totpCode } from "../helpers/totp";
+import { exclusive } from "../helpers/exclusive";
 
 test.use({ storageState: anonState });
 
@@ -85,58 +86,61 @@ test("two-factor: sign in with an authenticator code from the login page", async
 });
 
 test("require-2fa: a new sign-up is forced through the enrolment page", async ({ page, 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 email = `rq-ui-${Date.now()}@example.com`;
-  const pw = "Podokit3e-Str0ng!pw";
-  try {
-    await admin.put("/api/account/settings", { data: { require2fa: true } });
-    // A fresh un-enrolled user; poll (via API) until the guard cache picks up the policy.
-    const probe = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-    await probe.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "RQUI" } });
-    await expect(async () => {
-      expect((await probe.get("/api/account/me")).status()).toBe(403);
-    }).toPass({ timeout: 8000 });
-    await probe.dispose();
-
-    // Signing in toward a protected route lands on the mandatory enrolment page.
-    await openHydratedLogin(page, "/account");
-    await page.getByLabel("Email").fill(email);
-    await page.getByLabel("Password").fill(pw);
-    await page.getByRole("button", { name: "Sign in", exact: true }).click();
-    await expect(page).toHaveURL(/\/setup-2fa/);
-
-    // Complete enrolment entirely through the UI: password → QR + backup codes →
-    // authenticator code → activate. The code is computed from the on-page URI.
-    await page.getByLabel("Confirm your password").fill(pw);
-    await page.getByRole("button", { name: "Continue" }).click();
-    await expect(page.getByTestId("backup-codes")).toBeVisible();
-    await expect(page.getByRole("button", { name: "Download" })).toBeVisible();
-    const uri = (await page.locator("code").first().innerText()).trim();
-    await page.getByRole("checkbox").click();
-    await page.getByLabel("3. Enter the 6-digit code").fill(totpCode(uri));
-    await page.getByRole("button", { name: "Activate and continue" }).click();
-
-    // Enrolled → the gate lets the regular user into their account page.
-    await expectAccountPage(page);
-
-    // An enrolled user who revisits setup is returned to the same non-admin page.
-    await page.goto("/setup-2fa");
-    await expectAccountPage(page);
-  } finally {
-    await admin.put("/api/account/settings", { data: { require2fa: false } });
-    await expect(async () => {
+  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 email = `rq-ui-${Date.now()}@example.com`;
+    const pw = "Podokit3e-Str0ng!pw";
+    try {
+      await admin.put("/api/account/settings", { data: { require2fa: true } });
+      // A fresh un-enrolled user; poll (via API) until the guard cache picks up the policy.
       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.post("/api/auth/sign-up/email", { data: { email, password: pw, name: "RQUI" } });
+      await expect(async () => {
+        expect((await probe.get("/api/account/me")).status()).toBe(403);
+      }).toPass({ timeout: 8000 });
       await probe.dispose();
-      expect(status).toBe(200);
-    }).toPass({ timeout: 8000 });
-    await admin.dispose();
-  }
+
+      // Signing in toward a protected route lands on the mandatory enrolment page.
+      await openHydratedLogin(page, "/account");
+      await page.getByLabel("Email").fill(email);
+      await page.getByLabel("Password").fill(pw);
+      await page.getByRole("button", { name: "Sign in", exact: true }).click();
+      await expect(page).toHaveURL(/\/setup-2fa/);
+
+      // Complete enrolment entirely through the UI: password → QR + backup codes →
+      // authenticator code → activate. The code is computed from the on-page URI.
+      await page.getByLabel("Confirm your password").fill(pw);
+      await page.getByRole("button", { name: "Continue" }).click();
+      await expect(page.getByTestId("backup-codes")).toBeVisible();
+      await expect(page.getByRole("button", { name: "Download" })).toBeVisible();
+      const uri = (await page.locator("code").first().innerText()).trim();
+      await page.getByRole("checkbox").click();
+      await page.getByLabel("3. Enter the 6-digit code").fill(totpCode(uri));
+      await page.getByRole("button", { name: "Activate and continue" }).click();
+
+      // Enrolled → the gate lets the regular user into their account page.
+      await expectAccountPage(page);
+
+      // An enrolled user who revisits setup is returned to the same non-admin page.
+      await page.goto("/setup-2fa");
+      await expectAccountPage(page);
+    } finally {
+      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();
+    }
+  });
 });
 
 test("account: regenerate backup codes shows a fresh set", async ({ page, playwright }) => {

package/dist/templates/modules/audit-log/module.manifest.json

@@ -34,7 +34,7 @@
     }
   ],
   "instructions": [
-    "Run migrations to create the audit_logs table: {{apiRun}} migration:run{{apiWorkspaceArg}}",
+    "Run migrations to create the audit_logs table: {{apiRun}} migrate:all{{apiWorkspaceArg}}",
     "Auth/admin actions are recorded by a Better Auth hook. Record semantic application events with AuditService.recordRequest() or recordAudit(); use recordAuditLater() only for high-volume, non-security events.",
     "List entries newest first (admin session required): curl -i -b cookies.txt 'localhost:5002/audit-logs?limit=50' and pass the X-Next-Cursor header back as ?cursor= for the next page"
   ],

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.ts

@@ -3,7 +3,7 @@ import { APIError } from "better-auth/api";
 import { twoFactor, haveIBeenPwned, magicLink, emailOTP, username, multiSession, phoneNumber, organization, jwt, bearer, openAPI } from "better-auth/plugins";
 import { actionEmail, sendMail } from "../mail/mailer";
 import { sendSms } from "../sms/sms";
-import { assertUserCreationAllowed, createFeatureGate, readSignupOpen } from "./feature-gate";
+import { assertUserCreationAllowed, createFeatureGate, featureGatePlugin, readSignupOpen, type FeatureGateSettings } from "./feature-gate";
 import { featureFlags, isSignupOpen } from "./auth-config-store";
 import { orgAc, orgRoles } from "./org-permissions";
 import { authDatabase } from "./db";
@@ -48,7 +48,13 @@ function buildSocial(config: AuthConfig): NonNullable<BetterAuthOptions["socialP
 // server-enforced toggles) apply without a restart. Everything below the injection
 // markers is contributed by other PodoKit modules (admin-dashboard, audit-log).
 export function buildAuth(config: AuthConfig) {
+  // The feature gate reads the process-wide settings snapshot, so a rebuild does
+  // not start a new cache.
+  const gateSettings: FeatureGateSettings = { flags: featureFlags, signupOpen: isSignupOpen };
   const plugins: BetterAuthPlugin[] = [
+    // First, so a disabled feature answers 404 before another plugin's onRequest
+    // (such as the OIDC provider's discovery metadata) can answer.
+    featureGatePlugin(gateSettings),
     twoFactor(),
     magicLink({
       sendMagicLink: async ({ email, url }: { email: string; url: string; token: string }) => {
@@ -179,11 +185,11 @@ export function buildAuth(config: AuthConfig) {
   };
 
   // Request-time hooks. The feature gate turns the admin Settings toggles into a
-  // real server boundary (disabled features 404). It reads the process-wide
-  // settings snapshot, so a rebuild does not start a new cache. Other PodoKit
-  // modules add their own hooks below the marker.
+  // real server boundary (disabled features 404) for endpoint calls, including
+  // in-process auth.api calls the plugin above never sees. Other PodoKit modules
+  // add their own hooks below the marker.
   const hooks: NonNullable<BetterAuthOptions["hooks"]> = {
-    before: createFeatureGate({ flags: featureFlags, signupOpen: isSignupOpen }),
+    before: createFeatureGate(gateSettings),
   };
   // podokit:begin:auth-hooks
   // podokit:end:auth-hooks

package/dist/templates/modules/auth/files/apps/api/src/auth/feature-gate.spec.ts

@@ -1,7 +1,14 @@
 import { describe, expect, test } from "bun:test";
+import { oauthProvider } from "@better-auth/oauth-provider";
+import { betterAuth } from "better-auth";
+import { memoryAdapter } from "better-auth/adapters/memory";
+import { jwt } from "better-auth/plugins";
 import { FLAG_DEFAULTS, flagsFrom } from "../settings/flag-defaults";
 import {
+  authRequestPath,
   enforceFeatureGate,
+  featureForPath,
+  featureGatePlugin,
   PUBLIC_SIGNUP_DISABLED,
   signupOpenFrom,
   type FeatureFlags,
@@ -56,3 +63,79 @@ describe("feature gate", () => {
     expect(signupOpenFrom(new Map())).toBe(true);
   });
 });
+
+describe("OIDC provider gate", () => {
+  test("covers the provider's endpoints but not the jwt plugin's", () => {
+    for (const path of [
+      "/oauth2/authorize",
+      "/oauth2/token",
+      "/oauth2/userinfo",
+      "/oauth2/register",
+      "/oauth2/consent",
+      "/oauth2/create-client",
+      "/oauth2/end-session",
+      "/admin/oauth2/create-client",
+      "/.well-known/openid-configuration",
+      "/.well-known/oauth-authorization-server",
+      "/.well-known/oauth-authorization-server/api/auth",
+    ]) {
+      expect(featureForPath(path)).toBe("oidcProvider");
+    }
+    for (const path of ["/jwks", "/token", "/get-session", "/sign-in/email"]) {
+      expect(featureForPath(path)).toBeUndefined();
+    }
+  });
+
+  test("resolves request paths against the auth base URL", () => {
+    const base = "http://localhost:5002/api/auth";
+    expect(authRequestPath("http://localhost:5002/api/auth/oauth2/authorize?client_id=x", base))
+      .toBe("/oauth2/authorize");
+    expect(authRequestPath("http://localhost:5002/api/auth/.well-known/openid-configuration", `${base}/`))
+      .toBe("/.well-known/openid-configuration");
+    expect(authRequestPath("http://localhost:5002/.well-known/oauth-authorization-server/api/auth", base))
+      .toBe("/.well-known/oauth-authorization-server/api/auth");
+    expect(authRequestPath("http://localhost:5002/api/authority/oauth2/token", base))
+      .toBe("/api/authority/oauth2/token");
+  });
+
+  test("answers the provider's discovery with 404 while it is disabled and serves it once enabled", async () => {
+    let enabled = false;
+    const auth = betterAuth({
+      database: memoryAdapter({ jwks: [] }),
+      baseURL: "http://localhost:5002",
+      secret: "feature-gate-spec-secret-0123456789abcdef",
+      logger: { disabled: true },
+      plugins: [
+        featureGatePlugin({
+          flags: async () => ({ ...FLAG_DEFAULTS, oidcProvider: enabled }),
+          signupOpen: async () => true,
+        }),
+        jwt(),
+        // Serves the discovery metadata from its own onRequest hook.
+        oauthProvider({ loginPage: "/login", consentPage: "/oauth2/consent" }),
+      ],
+    });
+    const request = (path: string): Promise<Response> =>
+      auth.handler(new Request(`http://localhost:5002${path}`));
+    const discovery = [
+      "/api/auth/.well-known/openid-configuration",
+      "/api/auth/.well-known/oauth-authorization-server",
+      "/.well-known/oauth-authorization-server/api/auth",
+    ];
+
+    for (const path of discovery) {
+      const response = await request(path);
+      expect(response.status).toBe(404);
+      expect(await response.json()).toEqual({ message: "This feature is disabled." });
+    }
+    expect((await request("/api/auth/oauth2/authorize?client_id=probe")).status).toBe(404);
+    expect((await request("/api/auth/jwks")).status).toBe(200);
+
+    enabled = true;
+    for (const path of discovery) {
+      const response = await request(path);
+      expect(response.status).toBe(200);
+      expect((await response.json()).issuer).toBe("http://localhost:5002/api/auth");
+    }
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/feature-gate.ts

@@ -1,10 +1,13 @@
+import type { BetterAuthPlugin } from "better-auth";
 import { APIError, createAuthMiddleware } from "better-auth/api";
 import { FLAG_DEFAULTS, type FeatureFlag } from "../settings/flag-defaults";
 
 export const PUBLIC_SIGNUP_DISABLED = "PUBLIC_SIGNUP_DISABLED" as const;
 
 /** Auth-relative path prefixes owned by each admin-toggleable feature. A path is
- *  gated when it equals a prefix or starts with a prefix ending in "/". */
+ *  gated when it starts with one of its feature's prefixes. The OIDC provider's
+ *  JWKS (`/jwks`) and session JWT (`/token`) belong to the always-on `jwt`
+ *  plugin, so they stay available while the provider is off. */
 const FEATURE_PATHS: Array<{ flag: FeatureFlag; prefixes: string[] }> = [
   { flag: "twoFactor", prefixes: ["/two-factor/"] },
   { flag: "magicLink", prefixes: ["/sign-in/magic-link", "/magic-link/"] },
@@ -15,9 +18,37 @@ const FEATURE_PATHS: Array<{ flag: FeatureFlag; prefixes: string[] }> = [
   { flag: "apiKey", prefixes: ["/api-key/"] },
   { flag: "passkey", prefixes: ["/passkey/", "/sign-in/passkey"] },
   { flag: "organization", prefixes: ["/organization"] },
-  { flag: "oidcProvider", prefixes: ["/oauth2/", "/.well-known/openid-configuration", "/.well-known/oauth-authorization-server", "/.well-known/oauth-protected-resource"] },
+  {
+    flag: "oidcProvider",
+    prefixes: [
+      "/oauth2/",
+      "/admin/oauth2/",
+      "/.well-known/openid-configuration",
+      // Also matches the RFC 8414 form outside the base path,
+      // /.well-known/oauth-authorization-server/api/auth.
+      "/.well-known/oauth-authorization-server",
+      "/.well-known/oauth-protected-resource",
+    ],
+  },
 ];
 
+/** The admin-toggleable feature that owns an auth-relative path, if any. */
+export function featureForPath(path: string): FeatureFlag | undefined {
+  return FEATURE_PATHS.find((f) => f.prefixes.some((p) => path.startsWith(p)))?.flag;
+}
+
+/** A request's path relative to Better Auth's base URL. A path outside the base
+ *  path is returned whole. */
+export function authRequestPath(requestUrl: string, baseURL: string): string {
+  const pathname = new URL(requestUrl).pathname;
+  const basePath = new URL(baseURL).pathname.replace(/\/+$/, "");
+  return basePath && pathname.startsWith(`${basePath}/`) ? pathname.slice(basePath.length) : pathname;
+}
+
+function featureDisabled(): APIError {
+  return new APIError("NOT_FOUND", { message: "This feature is disabled." });
+}
+
 export type FeatureFlags = Record<FeatureFlag, boolean>;
 
 /** Live settings the gate reads per request, normally the shared settings snapshot. */
@@ -75,12 +106,9 @@ export async function enforceFeatureGate(path: string, settings: FeatureGateSett
     assertUserCreationAllowed(await readSignupOpen(settings.signupOpen), path);
     return;
   }
-  const feature = FEATURE_PATHS.find((f) =>
-    f.prefixes.some((p) => path === p || path.startsWith(p)),
-  );
+  const feature = featureForPath(path);
   if (!feature) return;
-  const enabled = (await readFeatureFlags(settings.flags))[feature.flag];
-  if (!enabled) throw new APIError("NOT_FOUND", { message: "This feature is disabled." });
+  if (!(await readFeatureFlags(settings.flags))[feature]) throw featureDisabled();
 }
 
 /** Better Auth middleware over {@link enforceFeatureGate}. The settings come from
@@ -91,3 +119,19 @@ export function createFeatureGate(settings: FeatureGateSettings): ReturnType<typ
     await enforceFeatureGate(ctx.path, settings);
   });
 }
+
+/** Rejects HTTP requests to a disabled feature before any plugin's `onRequest`
+ *  runs. `hooks.before` alone is not enough: the OAuth provider answers its
+ *  discovery metadata from `onRequest`, which Better Auth runs before endpoint
+ *  hooks. Register this plugin ahead of every other plugin. */
+export function featureGatePlugin(settings: FeatureGateSettings): BetterAuthPlugin {
+  return {
+    id: "podokit-feature-gate",
+    onRequest: async (request, ctx) => {
+      const feature = featureForPath(authRequestPath(request.url, ctx.baseURL));
+      if (!feature || (await readFeatureFlags(settings.flags))[feature]) return undefined;
+      const error = featureDisabled();
+      return { response: Response.json(error.body, { status: error.statusCode }) };
+    },
+  };
+}

package/dist/templates/modules/auth/module.manifest.json

@@ -19,7 +19,6 @@
     "@types/pg": "^8.11.10"
   },
   "scripts": {
-    "migrate:all": "bun scripts/run-migrations.mjs",
     "auth:configure": "bun scripts/configure-auth.mjs"
   },
   "env": [

package/dist/templates/modules/file-upload/files/tests/api/chunked-uploads.api.spec.ts

@@ -77,12 +77,18 @@ test("chunked upload: parts, a retried part, resume status, and complete store t
     // Completing again returns the same result.
     expect(await (await ctx.post(`${uploads}/${upload.id}/complete`, { data: {} })).json()).toMatchObject({ key: result.key });
 
-    // S3 returns an absolute presigned URL; local storage a signed API path.
-    const download = await ctx.get(result.url.startsWith("/") ? `${apiBase}${result.url}` : result.url);
-    expect(download.status()).toBe(200);
-    const stored = await download.body();
-    expect(stored.byteLength).toBe(file.byteLength);
-    expect(sha256(stored)).toBe(sha256(file));
+    // Local storage returns a signed API path. S3 returns a URL signed for the API's
+    // S3 endpoint; a containerized dev stack signs an in-network host, so download it
+    // only when the runner was given that endpoint too. The completed size above
+    // comes from the stored object either way.
+    const local = result.url.startsWith("/");
+    if (local || process.env.S3_ENDPOINT) {
+      const download = await ctx.get(local ? `${apiBase}${result.url}` : result.url);
+      expect(download.status()).toBe(200);
+      const stored = await download.body();
+      expect(stored.byteLength).toBe(file.byteLength);
+      expect(sha256(stored)).toBe(sha256(file));
+    }
   } finally {
     await ctx.dispose();
   }

package/dist/templates/modules/file-upload/module.manifest.json

@@ -31,12 +31,12 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### file-upload\n- `POST /files` stores one multipart file under `uploads/<userId>/`; `GET /files/:key/url` presigns it for the owner or an administrator.\n- For large files use the resumable upload in the browser: `uploadFile(file, { onProgress, signal })` and `resumeUpload(id, file)` from `$lib/uploads`. They create a session (`POST /files/uploads`), send parts (`PUT /files/uploads/:id/parts/:n`, `application/octet-stream`, `Content-Length` equal to the part size; with `XMLHttpRequest` in the browser so `onProgress` reports bytes), retry failed parts honoring `Retry-After`, and complete (`POST /files/uploads/:id/complete`). `GET /files/uploads/:id` lists stored parts; `DELETE` cancels.\n- Upload sessions live in the database (`file_upload_sessions`, `file_upload_parts`), so any API replica serves any request; never keep upload state in memory. Run `{{apiRun}} migration:run{{apiWorkspaceArg}}` after adding the module.\n- Parts are larger than the web `BODY_SIZE_LIMIT`, so the gateway sends `/api/files/uploads/` straight to the API: `podo add` listed it in `.podokit/dev.json` `apiPaths` and each deployment profile's `exposure.apiPaths`, and `podo deploy init` adds it to new profiles. Keep it there.\n- POST bodies must be `application/json` and parts `application/octet-stream` (else 415 `UNSUPPORTED_MEDIA_TYPE`), and a browser `Origin` outside `CORS_ORIGIN` gets 403. Branch on `error.code`: `UPLOAD_NOT_FOUND`, `UPLOAD_TOO_LARGE`, `UPLOAD_PART_SIZE_MISMATCH`, `UPLOAD_INCOMPLETE`, `UPLOAD_COMPLETING`, `UPLOAD_EXPIRED`, `UPLOAD_ABORTED`.\n"
+      "text": "### file-upload\n- `POST /files` stores one multipart file under `uploads/<userId>/`; `GET /files/:key/url` presigns it for the owner or an administrator.\n- For large files use the resumable upload in the browser: `uploadFile(file, { onProgress, signal })` and `resumeUpload(id, file)` from `$lib/uploads`. They create a session (`POST /files/uploads`), send parts (`PUT /files/uploads/:id/parts/:n`, `application/octet-stream`, `Content-Length` equal to the part size; with `XMLHttpRequest` in the browser so `onProgress` reports bytes), retry failed parts honoring `Retry-After`, and complete (`POST /files/uploads/:id/complete`). `GET /files/uploads/:id` lists stored parts; `DELETE` cancels.\n- Upload sessions live in the database (`file_upload_sessions`, `file_upload_parts`), so any API replica serves any request; never keep upload state in memory. Run `{{apiRun}} migrate:all{{apiWorkspaceArg}}` after adding the module.\n- Parts are larger than the web `BODY_SIZE_LIMIT`, so the gateway sends `/api/files/uploads/` straight to the API: `podo add` listed it in `.podokit/dev.json` `apiPaths` and each deployment profile's `exposure.apiPaths`, and `podo deploy init` adds it to new profiles. Keep it there.\n- POST bodies must be `application/json` and parts `application/octet-stream` (else 415 `UNSUPPORTED_MEDIA_TYPE`), and a browser `Origin` outside `CORS_ORIGIN` gets 403. Branch on `error.code`: `UPLOAD_NOT_FOUND`, `UPLOAD_TOO_LARGE`, `UPLOAD_PART_SIZE_MISMATCH`, `UPLOAD_INCOMPLETE`, `UPLOAD_COMPLETING`, `UPLOAD_EXPIRED`, `UPLOAD_ABORTED`.\n"
     }
   ],
   "instructions": [
     "Configure the selected object-storage provider before uploading files.",
-    "Run migrations to create the upload session tables: {{apiRun}} migration:run{{apiWorkspaceArg}}",
+    "Run migrations to create the upload session tables: {{apiRun}} migrate:all{{apiWorkspaceArg}}",
     "Uploads are stored as uploads/<userId>/<uuid>-<name>. Add the auth module so every upload has an owner.",
     "Upload a file:  curl -b cookies.txt -F 'file=@./some.png' localhost:5002/files",
     "The response includes { key, url } — an S3 presigned URL or a signed local download URL.",