@podosoft/podokit 1.4.1 → 1.4.2

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/todo/README.md

@@ -131,7 +131,7 @@ Run each service in a separate terminal from the project root:
 ```
 
 - API: http://localhost:5002 — health at `/health`, docs at `/api-docs`
-- Web: http://localhost:5001
+- Web: http://localhost:5001 — its own health at `/healthz`, which never calls the API
 
 For multi-project routing, container profiles, and OAuth over a stable HTTPS
 tunnel, see the PodoKit [development guide](https://github.com/podosoft-dev/podokit/blob/main/docs/development.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "An opinionated Bun and Elysia full-stack TypeScript starter toolkit and CLI with SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {