@jant/core 0.6.16 → 0.7.0

package/src/middleware/auth.ts

@@ -5,7 +5,7 @@
  * or Bearer API tokens.
  */
 
-import type { MiddlewareHandler } from "hono";
+import type { Context, MiddlewareHandler } from "hono";
 import type { Bindings } from "../types.js";
 import type { AppVariables } from "../types/app-context.js";
 import { getDevApiToken, getInternalAdminToken } from "../lib/env.js";
@@ -110,6 +110,42 @@ function getPostSigninRedirect(requestUrl: string): string | null {
   return isSafeInternalRedirect(candidate) ? candidate : null;
 }
 
+/**
+ * Whether the request's session belongs to a member of the current site.
+ *
+ * This is the single definition of "signed in *here*", and every entrance must
+ * ask it rather than `c.var.isAuthenticated`. That flag only answers "carries a
+ * session", which is a weaker claim: better-auth's cookie cache keeps answering
+ * from the browser's own copy for minutes after the rows behind it are gone, so
+ * a session routinely outlives the site it was issued for — a factory reset and
+ * a fresh setup being the obvious way. When a guard requires membership and an
+ * entrance settles for a session, the two disagree and bounce the visitor
+ * between them until the browser gives up.
+ *
+ * @param c - The request context, after `attachSession` has run
+ * @returns `true` when the session's user is a member of `c.var.currentSite`
+ *
+ * @example
+ * ```ts
+ * // /signin only sends someone away if they are signed in to *this* site.
+ * if (await isCurrentSiteMember(c)) return c.redirect("/");
+ * ```
+ */
+export async function isCurrentSiteMember(c: Context<Env>): Promise<boolean> {
+  const session = c.var.session;
+  if (!session?.user) return false;
+
+  // `siteMembers.get` resolves to `null` for "not a member", so a throw is
+  // always infrastructure and is left to propagate. Rewriting a failing
+  // database read into "not a member" would read to the user as being randomly
+  // signed out.
+  const membership = await c.var.services.siteMembers.get(
+    c.var.currentSite.id,
+    session.user.id,
+  );
+  return !!membership;
+}
+
 /**
  * Middleware that requires authentication.
  * Redirects to signin page if not authenticated.
@@ -136,25 +172,16 @@ export function requireAuth(redirectTo = "/signin"): MiddlewareHandler<Env> {
       return `${publicHref}${separator}redirect=${encodeURIComponent(postSignin)}`;
     };
 
-    // Session was already fetched by `attachSession` middleware.
-    const session = c.var.session;
-    if (!session?.user) {
+    // Session was already fetched by `attachSession` middleware. The membership
+    // read inside `isCurrentSiteMember` and `next()` both stay outside a catch:
+    // a failing database read or a route handler blowing up used to be
+    // rewritten into a redirect to sign-in, which reads to the user as being
+    // randomly signed out and loses whatever they were doing.
+    if (!(await isCurrentSiteMember(c))) {
       return c.redirect(buildRedirectTarget());
     }
 
-    try {
-      const membership = await c.var.services.siteMembers.get(
-        c.var.currentSite.id,
-        session.user.id,
-      );
-      if (!membership) {
-        return c.redirect(buildRedirectTarget());
-      }
-
-      await next();
-    } catch {
-      return c.redirect(buildRedirectTarget());
-    }
+    await next();
   };
 }
 
@@ -166,20 +193,12 @@ export function requireAuth(redirectTo = "/signin"): MiddlewareHandler<Env> {
 export function requireAuthApi(): MiddlewareHandler<Env> {
   return async (c, next) => {
     // 1. Try session auth (session is pre-fetched by `attachSession` middleware).
-    const session = c.var.session;
-    if (session?.user) {
-      try {
-        const membership = await c.var.services.siteMembers.get(
-          c.var.currentSite.id,
-          session.user.id,
-        );
-        if (membership) {
-          await next();
-          return;
-        }
-      } catch {
-        // Membership check failed — fall through to Bearer token
-      }
+    // Only the membership lookup falls through to Bearer on failure. `next()`
+    // must stay outside that catch, or a route handler throwing turns into a
+    // 401 and the client treats a server error as an expired login.
+    if (await isCurrentSiteMember(c).catch(() => false)) {
+      await next();
+      return;
     }
 
     // 2. Try Bearer token auth

package/src/middleware/cache-control.ts

@@ -20,6 +20,26 @@
  * sitemaps, favicons, manifests, static assets) set their own `Cache-Control`
  * explicitly; this middleware leaves those untouched and only fills in the
  * default for the un-annotated dynamic responses.
+ *
+ * The default differs by audience, because `no-store` costs more than it
+ * looks: it also disables the browser's back/forward cache, so going back
+ * re-requests the page, re-renders it and re-runs its scripts instead of
+ * restoring it instantly. For an anonymous visitor there is nothing to
+ * protect — the page is the public one anybody gets — so they get `no-cache`,
+ * which keeps shared caches out exactly as before (that is `private`'s job)
+ * while letting the browser hold its own copy and revalidate.
+ *
+ * A signed-in author keeps `no-store`. The back/forward cache restores a whole
+ * page snapshot without asking the server, so a page rendered while signed in
+ * would still be there after signing out — on a shared machine that shows the
+ * previous session's view. Trading the author's back-button latency for that
+ * is not worth it; readers are the traffic that matters here anyway.
+ *
+ * Credential surfaces are the exception to "anonymous has nothing to protect".
+ * A sign-in form, a setup form, a reset page whose URL carries a one-time
+ * token, an SSO handoff: all of them are served to someone with no session
+ * yet, so the anonymous default would let the browser write them to disk.
+ * `noStore()` marks those paths, and `app.tsx` mounts it on every one of them.
  */
 
 import type { MiddlewareHandler } from "hono";
@@ -29,32 +49,77 @@ import type { AppVariables } from "../types/app-context.js";
 type Env = { Bindings: Bindings; Variables: AppVariables };
 
 /**
- * Default cache directive for dynamic, potentially auth-variant responses.
- * `private` forbids shared/CDN caches from storing the response; `no-store`
- * prevents any cache (including the browser) from keeping a copy.
+ * Nothing keeps a copy. `private` forbids shared/CDN caches from storing the
+ * response; `no-store` prevents any cache — the browser's own, and its
+ * back/forward cache — from keeping one either.
+ *
+ * The default for a signed-in author, and the rule for every credential
+ * surface whatever the audience.
  */
-const DEFAULT_CACHE_CONTROL = "private, no-store";
+const NO_STORE_CACHE_CONTROL = "private, no-store";
 
 /**
- * Middleware that defaults a missing `Cache-Control` header to
- * `private, no-store`.
+ * Default for anonymous responses. `private` still keeps shared/CDN caches
+ * out; `no-cache` lets the browser keep a copy it must revalidate before
+ * reuse, which is what makes the page eligible for the back/forward cache.
+ */
+const ANONYMOUS_CACHE_CONTROL = "private, no-cache";
+
+/**
+ * Middleware that defaults a missing `Cache-Control` header: `private,
+ * no-cache` for anonymous responses, `private, no-store` once signed in.
  *
  * Runs after the route handler: if the handler (or an inner middleware)
  * already set `Cache-Control`, that explicit value wins. Only responses that
- * declare nothing receive the safe default.
+ * declare nothing receive the default. Requires `attachSession()` to have run
+ * first; without it every response is treated as anonymous, so mount it after.
  *
  * @returns Hono middleware enforcing the default cache policy.
  *
  * @example
  * ```ts
+ * app.use("*", attachSession());
  * app.use("*", defaultCacheControl());
  * ```
  */
 export function defaultCacheControl(): MiddlewareHandler<Env> {
   return async (c, next) => {
     await next();
-    if (!c.res.headers.has("Cache-Control")) {
-      c.res.headers.set("Cache-Control", DEFAULT_CACHE_CONTROL);
-    }
+    if (c.res.headers.has("Cache-Control")) return;
+    c.res.headers.set(
+      "Cache-Control",
+      c.var.isAuthenticated ? NO_STORE_CACHE_CONTROL : ANONYMOUS_CACHE_CONTROL,
+    );
+  };
+}
+
+/**
+ * Middleware for a path that must never be written to any cache.
+ *
+ * For the credential surfaces: sign-in, sign-out, setup, password reset, the
+ * SSO handoff, the dev login, and better-auth's own endpoints. Every one of
+ * them is reached without a session, so `defaultCacheControl` would hand them
+ * the anonymous `no-cache` — which lets the browser keep the page, and the URL
+ * it came from, on disk. A reset link's one-time token then outlives the visit
+ * on a shared machine.
+ *
+ * Unconditional, unlike the default: this is a rule about the path, not a
+ * fallback for a path that said nothing. Mount it after
+ * `defaultCacheControl()` so the header is already set by the time that one
+ * looks, and before the handler it protects — a terminal handler registered
+ * first ends the chain and this never runs.
+ *
+ * @returns Hono middleware forcing `private, no-store`.
+ *
+ * @example
+ * ```ts
+ * app.use("/reset", noStore());
+ * app.route("/", resetRoutes);
+ * ```
+ */
+export function noStore(): MiddlewareHandler<Env> {
+  return async (c, next) => {
+    await next();
+    c.res.headers.set("Cache-Control", NO_STORE_CACHE_CONTROL);
   };
 }

package/src/middleware/config.ts

@@ -18,7 +18,6 @@ import {
 import { buildThemeStyle, resolveBuiltinTheme } from "../lib/theme.js";
 import {
   BUILTIN_FONT_THEMES,
-  getCjkFontCssVariables,
   getFontThemeCssVariables,
 } from "../ui/font-themes.js";
 
@@ -47,14 +46,15 @@ export function withConfig(): MiddlewareHandler<Env> {
     // Resolve active color theme
     const activeTheme = resolveBuiltinTheme(appConfig.themeId);
 
-    // Build font theme CSS variables
+    // Build font theme CSS variables. The CJK fallback stacks are deliberately
+    // NOT resolved here: they depend on the language of the page being
+    // rendered — a post's own language, or the language a filtered list view is
+    // showing — which this middleware runs too early to know. `BaseLayout`
+    // emits them alongside the matching CJK stylesheet instead.
     const fontTheme = BUILTIN_FONT_THEMES.find(
       (f) => f.id === appConfig.fontThemeId,
     );
-    const fontOverrides = {
-      ...getCjkFontCssVariables(appConfig.siteLanguage, appConfig.cjkSerifFont),
-      ...(fontTheme ? getFontThemeCssVariables(fontTheme) : {}),
-    };
+    const fontOverrides = fontTheme ? getFontThemeCssVariables(fontTheme) : {};
 
     const themeStyle = buildThemeStyle(
       activeTheme,

package/src/middleware/error-handler.ts

@@ -13,8 +13,10 @@ import {
   ConfigurationError,
   DomainError,
   NotFoundError,
+  SiteUnavailableError,
   ValidationError,
 } from "../lib/errors.js";
+import { renderSiteUnavailablePage } from "../lib/site-unavailable-page.js";
 import { dsToast } from "../lib/sse.js";
 import { getRuntimeConfigurationErrorPage } from "../lib/startup-config.js";
 
@@ -68,6 +70,16 @@ export const errorHandler: ErrorHandler<Env> = (err, c) => {
     return c.json({ error: "Something went wrong on our end" }, 500);
   }
 
+  // A suspended site: the host is real, so answer with a page that says so
+  // instead of the generic 404 shell. 503 keeps the site's search index alive
+  // while it can still be restored; `Retry-After` is deliberately omitted
+  // because we can't promise when (or whether) it comes back.
+  if (err instanceof SiteUnavailableError) {
+    return c.html(renderSiteUnavailablePage(c.env), 503, {
+      "Cache-Control": "no-store",
+    });
+  }
+
   // Non-API routes: map NotFoundError to Hono's built-in 404
   if (err instanceof NotFoundError) {
     return c.notFound();

package/src/middleware/onboarding.ts

@@ -1,15 +1,28 @@
 /**
  * Onboarding Middleware
  *
- * Redirects key page routes to /setup if onboarding hasn't been completed.
+ * Redirects key page routes to /setup while first-run setup is unfinished.
  * Uses an allowlist approach: only explicitly listed page routes are redirected,
  * so static assets, API endpoints, feeds, and other resources always pass through.
  * Caches the result in memory so the DB is only queried once per isolate lifetime.
+ *
+ * How much is gated depends on how far setup has got:
+ *
+ * - `pending` — nobody owns the site and it holds nothing. Readers have no
+ *   business being anywhere but setup, so the public root is gated too.
+ * - `provisioned` — the site has an owner and owes setup its last answers. A
+ *   control plane leaves a hosted site here at creation, and a self-hosted one
+ *   sits here between its two setup screens. Either way the site is real, so
+ *   readers are served normally; only the author's own entrances are gated,
+ *   and only once they are signed in, because the remaining questions are
+ *   theirs to answer. `/signin` staying open is what lets a self-hosted author
+ *   who lost the session mid-setup get back to the screen they left.
  */
 
 import type { MiddlewareHandler } from "hono";
 import type { Bindings } from "../types.js";
 import type { AppVariables } from "../types/app-context.js";
+import { ONBOARDING_STATUS } from "../lib/constants.js";
 import { getRuntimeSitePathPrefix } from "../lib/site-resolution.js";
 import { toPublicPath } from "../lib/url.js";
 
@@ -31,16 +44,23 @@ export function requireOnboarding(): MiddlewareHandler<Env> {
       return next();
     }
 
-    if (!shouldRedirect(path)) {
+    if (!isGatedPath(path)) {
       return next();
     }
 
-    const isComplete = await c.var.services.settings.isOnboardingComplete();
-    if (isComplete) {
+    const status = await c.var.services.settings.getOnboardingStatus();
+    if (status === ONBOARDING_STATUS.COMPLETED) {
       completedOnboardingSites.add(c.var.currentSite.id);
       return next();
     }
 
+    if (
+      status === ONBOARDING_STATUS.PROVISIONED &&
+      !(c.var.isAuthenticated && isAuthorPath(path))
+    ) {
+      return next();
+    }
+
     const sitePathPrefix = getRuntimeSitePathPrefix({
       env: c.env,
       appConfig: c.var.appConfig,
@@ -52,15 +72,17 @@ export function requireOnboarding(): MiddlewareHandler<Env> {
 }
 
 /**
- * Only these page routes are redirected to /setup during onboarding.
+ * Only these page routes are ever redirected to /setup.
  * Everything else (assets, API, feeds, media, etc.) passes through.
  */
-function shouldRedirect(path: string): boolean {
+function isGatedPath(path: string): boolean {
+  return path === "/signin" || path === "/reset" || isAuthorPath(path);
+}
+
+/** The routes an author uses to reach their own site. */
+function isAuthorPath(path: string): boolean {
   return (
-    path === "/" ||
-    path === "/signin" ||
-    path === "/reset" ||
-    path.startsWith("/settings")
+    path === "/" || path.startsWith("/settings") || path.startsWith("/compose")
   );
 }
 

package/src/middleware/secure-headers.ts

@@ -14,7 +14,7 @@ import type { MiddlewareHandler } from "hono";
 import type { Bindings } from "../types.js";
 import type { AppVariables } from "../types/app-context.js";
 import { getConfiguredStorageDriver, getEnvString } from "../lib/env.js";
-import { IS_VITE_DEV } from "../lib/version.js";
+import { IS_VITE_DEV } from "../lib/build-env.js";
 import {
   buildCspDirectives,
   type ContentSecurityPolicyDirectives,

package/src/middleware/session.ts

@@ -6,31 +6,119 @@
  *
  * This replaces ad-hoc `auth.api.getSession()` calls scattered across
  * view helpers (e.g. `lib/navigation.ts`) so each request only parses
- * the session cookie once. better-auth's own cookieCache (5 min) still
- * keeps this cheap, but centralizing the call also unlocks `Promise.all`
- * patterns in routes that previously serialized on a hidden session fetch.
+ * the session cookie once.
+ *
+ * `getSession` is not purely a read: better-auth re-issues the session cookie
+ * with a fresh `Max-Age` once per `updateAge`, and rebuilds the short-lived
+ * `session_data` cookie cache whenever it misses. Those live in the endpoint's
+ * response headers, which better-call only hands back under `returnHeaders`
+ * — without it the cookies are silently dropped, the browser copy expires a
+ * fixed 30 days after sign-in however active the user is, and the cookie cache
+ * never survives its first 5 minutes. So we take the headers and write them
+ * back onto the outgoing response.
  *
  * Never throws — any lookup error is treated as "not authenticated".
  */
 
-import type { MiddlewareHandler } from "hono";
+import type { Context, MiddlewareHandler } from "hono";
 import type { Bindings } from "../types.js";
 import type { AppVariables } from "../types/app-context.js";
 
 type Env = { Bindings: Bindings; Variables: AppVariables };
 
+/**
+ * Extracts the cookie name from a `Set-Cookie` header value.
+ *
+ * @param setCookie - A single `Set-Cookie` value, e.g. `a=b; Path=/; Max-Age=1`
+ * @returns The cookie name, or the whole trimmed string when there is no `=`
+ *
+ * @example
+ * ```ts
+ * readCookieName("__Secure-better-auth.session_token=abc; Path=/"); // "__Secure-better-auth.session_token"
+ * ```
+ */
+function readCookieName(setCookie: string): string {
+  const separator = setCookie.indexOf("=");
+  return (separator === -1 ? setCookie : setCookie.slice(0, separator)).trim();
+}
+
+/**
+ * Whether a `Cache-Control` value lets a shared cache store the response.
+ *
+ * A missing header counts as not shared-cacheable: `defaultCacheControl` fills
+ * those in with `private, no-store` later in the chain, and this middleware
+ * must stay correct no matter which of the two unwinds first.
+ *
+ * @param cacheControl - The response's `Cache-Control`, if any
+ * @returns `true` when a CDN or proxy is allowed to keep a copy
+ *
+ * @example
+ * ```ts
+ * isSharedCacheable("private, no-store");           // false
+ * isSharedCacheable("public, max-age=31536000");    // true
+ * isSharedCacheable(null);                          // false
+ * ```
+ */
+function isSharedCacheable(cacheControl: string | null): boolean {
+  if (!cacheControl) return false;
+  const directives = cacheControl.toLowerCase();
+  return !directives.includes("no-store") && !directives.includes("private");
+}
+
+/**
+ * Copies better-auth's refreshed cookies onto the response the route produced.
+ *
+ * Two things are deliberately skipped:
+ *
+ * - **Shared-cacheable responses.** `/media/*` answers with
+ *   `public, max-age=31536000, immutable`; a session cookie riding along on
+ *   that response is a session handed to whoever the CDN serves next.
+ *   `Cache-Control: public` is this codebase's explicit marker for
+ *   "auth-invariant, safe to store" (see `middleware/cache-control.ts`), so it
+ *   is exactly the signal to stay out of.
+ * - **Cookie names the route already set.** `/signout` clears the session
+ *   cookie after this middleware read (and possibly refreshed) it. Appending
+ *   ours last would land after the route's deletion and resurrect the session.
+ */
+function applyAuthCookies(
+  c: Context<Env>,
+  authHeaders: Headers | null | undefined,
+): void {
+  const refreshed = authHeaders?.getSetCookie() ?? [];
+  if (refreshed.length === 0) return;
+  if (isSharedCacheable(c.res.headers.get("Cache-Control"))) return;
+
+  const alreadySet = new Set(c.res.headers.getSetCookie().map(readCookieName));
+  for (const cookie of refreshed) {
+    if (alreadySet.has(readCookieName(cookie))) continue;
+    c.res.headers.append("Set-Cookie", cookie);
+  }
+}
+
 export function attachSession(): MiddlewareHandler<Env> {
   return async (c, next) => {
-    try {
-      const session = await c.var.auth.api.getSession({
+    const read = () =>
+      c.var.auth.api.getSession({
         headers: c.req.raw.headers,
+        returnHeaders: true,
       });
-      c.set("session", session ?? null);
-      c.set("isAuthenticated", !!session?.user);
+
+    let authHeaders: Headers | null = null;
+    try {
+      // One retry: a blipping database read would otherwise present to the
+      // user as a logout, and `requireAuth` would send them back to sign-in
+      // with a session that was valid the whole time.
+      const { headers, response } = await read().catch(() => read());
+      authHeaders = headers;
+      c.set("session", response ?? null);
+      c.set("isAuthenticated", !!response?.user);
     } catch {
       c.set("session", null);
       c.set("isAuthenticated", false);
     }
+
     await next();
+
+    applyAuthCookies(c, authHeaders);
   };
 }

package/src/node/__tests__/cli-migrate.test.ts

@@ -1,27 +1,25 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 
+const MIGRATE_ENV_KEYS = [
+  "DATABASE_URL",
+  "DATA_DIR",
+  "JANT_DEBUG_MIGRATE",
+  "JANT_ENV_FILE",
+] as const;
+
 describe("jant migrate", () => {
-  const originalDatabaseUrl = process.env.DATABASE_URL;
-  const originalDataDir = process.env.DATA_DIR;
-  const originalDebugFlag = process.env.JANT_DEBUG_MIGRATE;
+  const originalEnv = Object.fromEntries(
+    MIGRATE_ENV_KEYS.map((key) => [key, process.env[key]]),
+  ) as Record<(typeof MIGRATE_ENV_KEYS)[number], string | undefined>;
 
   afterEach(() => {
-    if (originalDatabaseUrl === undefined) {
-      delete process.env.DATABASE_URL;
-    } else {
-      process.env.DATABASE_URL = originalDatabaseUrl;
-    }
-
-    if (originalDataDir === undefined) {
-      delete process.env.DATA_DIR;
-    } else {
-      process.env.DATA_DIR = originalDataDir;
-    }
-
-    if (originalDebugFlag === undefined) {
-      delete process.env.JANT_DEBUG_MIGRATE;
-    } else {
-      process.env.JANT_DEBUG_MIGRATE = originalDebugFlag;
+    for (const key of MIGRATE_ENV_KEYS) {
+      const value = originalEnv[key];
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
     }
 
     vi.restoreAllMocks();
@@ -33,6 +31,10 @@ describe("jant migrate", () => {
       "postgres://shell_user:super-secret@db.example.com:5432/shell_db";
     delete process.env.DATA_DIR;
     process.env.JANT_DEBUG_MIGRATE = "1";
+    // This test is about the auto-located `.env.node` itself, so it opts back
+    // into the search the suite disables in `vitest.config.ts`. `node:fs` is
+    // mocked below, so the file it finds is the mock's content, not a real one.
+    delete process.env.JANT_ENV_FILE;
 
     const migrate = vi.fn(async () => {});
     const poolQuery = vi