@podosoft/podokit 1.4.2 → 1.6.0

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

@@ -4,7 +4,7 @@ import { twoFactor, haveIBeenPwned, magicLink, emailOTP, username, multiSession,
 import { actionEmail, sendMail } from "../mail/mailer";
 import { sendSms } from "../sms/sms";
 import { assertUserCreationAllowed, createFeatureGate, featureGatePlugin, readSignupOpen, type FeatureGateSettings } from "./feature-gate";
-import { featureFlags, isSignupOpen } from "./auth-config-store";
+import { AUTH_CONFIG_DEFAULTS, featureFlags, isSignupOpen } from "./auth-config-store";
 import { orgAc, orgRoles } from "./org-permissions";
 import { authDatabase } from "./db";
 import { type AuthConfig, envAuthConfig, sessionIdleOptions, SUPPORTED_PROVIDER_IDS } from "@podosoft/podokit-auth";
@@ -15,6 +15,8 @@ import { SIGNUP_APPROVAL_REQUIRED } from "@podosoft/podokit-contracts";
 import { runUserDeletedHandlers } from "./user-delete-handlers";
 import { authBaseUrl, authSecret } from "./auth-environment";
 import { isMaintenanceCommand } from "./maintenance";
+import { CLIENT_ADDRESS_HEADER } from "../core/client-address";
+import { revokeEveryOtherSession } from "./revoke-other-sessions";
 // podokit:begin:auth-imports
 // podokit:end:auth-imports
 
@@ -55,7 +57,10 @@ export function buildAuth(config: AuthConfig) {
     // 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(),
+    // "Sign out other sessions" revokes every other session, not only the first 100.
+    revokeEveryOtherSession(),
+    // The issuer is the account name authenticator apps show.
+    twoFactor({ issuer: config.appName }),
     magicLink({
       sendMagicLink: async ({ email, url }: { email: string; url: string; token: string }) => {
         await sendMail({
@@ -91,8 +96,8 @@ export function buildAuth(config: AuthConfig) {
     apiKey(),
     // Passwordless sign-in with WebAuthn passkeys. The ceremony runs at the web
     // origin, so expected origins are the CORS origins and rpID is their host.
-    // Change rpName to your product name (shown in the browser passkey prompt).
-    passkey({ rpName: "PodoKit", rpID: new URL(webOrigins[0]).hostname, origin: webOrigins }),
+    // rpName is the name the browser shows in the passkey prompt.
+    passkey({ rpName: config.appName, rpID: new URL(webOrigins[0]).hostname, origin: webOrigins }),
     // Multi-tenant organizations: teams with members, roles, and email invitations.
     organization({
       // Custom member roles (adds "manager") and a parent-organization link so orgs
@@ -197,6 +202,7 @@ export function buildAuth(config: AuthConfig) {
   const session = sessionIdleOptions(config.sessionIdleTimeoutMinutes);
 
   return betterAuth({
+    appName: config.appName,
     database: authDatabase,
     emailAndPassword: {
       enabled: true,
@@ -235,9 +241,10 @@ export function buildAuth(config: AuthConfig) {
     baseURL: authBaseUrl(),
     advanced: {
       ipAddress: {
-        // The API sits behind the SvelteKit server proxy, which forwards the
-        // resolved client IP as x-forwarded-for; trust it so sessions record an IP.
-        ipAddressHeaders: ["x-forwarded-for"],
+        // The address the API resolved behind its trusted proxies, which it sets
+        // on every request, so sessions and Better Auth's own rate limits use the
+        // same client address as the rest of the API.
+        ipAddressHeaders: [CLIENT_ADDRESS_HEADER],
       },
       ...(isMaintenanceCommand() ? { database: { validateSchema: false } } : {}),
     },
@@ -292,4 +299,4 @@ export function buildAuth(config: AuthConfig) {
 // Bootstrap instance from environment config. Used by the better-auth CLI
 // (`--config auth.ts`) and as the guaranteed last-good fallback. The runtime
 // mount (auth-provider.ts) rebuilds from DB config on top of this.
-export const auth = buildAuth(envAuthConfig());
+export const auth = buildAuth(envAuthConfig(AUTH_CONFIG_DEFAULTS));

package/dist/templates/modules/auth/files/apps/api/src/auth/revoke-other-sessions.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { betterAuth, type BetterAuthPlugin } from "better-auth";
+import { memoryAdapter } from "better-auth/adapters/memory";
+import { revokeEveryOtherSession } from "./revoke-other-sessions";
+
+type Row = Record<string, unknown>;
+
+// A user signed in once more than Better Auth's default findMany limit of 100
+// sessions per list allows, plus the 50 extra the endpoint used to leave behind.
+const EXTRA_SESSIONS = 150;
+
+async function signedInWithManySessions(plugins: BetterAuthPlugin[]): Promise<{
+  revokeOthers: () => Promise<unknown>;
+  sessions: () => Row[];
+  currentToken: string;
+}> {
+  const db: Record<string, Row[]> = { user: [], session: [], account: [], verification: [] };
+  const auth = betterAuth({
+    database: memoryAdapter(db),
+    secret: "revoke-other-sessions-test-secret-0123456789",
+    baseURL: "http://localhost:5002",
+    emailAndPassword: { enabled: true },
+    plugins,
+  });
+  const response = await auth.api.signUpEmail({
+    body: { email: "many@example.com", password: "Podokit3e-Str0ng!pw", name: "Many" },
+    asResponse: true,
+  });
+  const cookie = response.headers.getSetCookie().map((value) => value.split(";")[0]).join("; ");
+  const context = await auth.$context;
+  const userId = String(db.user[0]?.id);
+  for (let index = 0; index < EXTRA_SESSIONS; index += 1) {
+    await context.internalAdapter.createSession(userId);
+  }
+  const currentToken = String((await auth.api.getSession({ headers: new Headers({ cookie }) }))?.session.token);
+  return {
+    revokeOthers: () => auth.api.revokeOtherSessions({ headers: new Headers({ cookie }) }),
+    sessions: () => db.session ?? [],
+    currentToken,
+  };
+}
+
+describe("revokeEveryOtherSession", () => {
+  test("Better Auth alone revokes only the first 100 other sessions", async () => {
+    const user = await signedInWithManySessions([]);
+    expect(user.sessions()).toHaveLength(EXTRA_SESSIONS + 1);
+    await user.revokeOthers();
+    expect(user.sessions().length).toBeGreaterThan(1);
+  });
+
+  test("revokes every other session and keeps the current one", async () => {
+    const user = await signedInWithManySessions([revokeEveryOtherSession()]);
+    await user.revokeOthers();
+    expect(user.sessions().map((session) => session.token)).toEqual([user.currentToken]);
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/revoke-other-sessions.ts

@@ -0,0 +1,45 @@
+import type { BetterAuthPlugin } from "better-auth";
+import { createAuthMiddleware } from "better-auth/api";
+
+/** Sessions read and revoked per pass. */
+const BATCH_SIZE = 500;
+
+/**
+ * Makes `/revoke-other-sessions` revoke every other session of the user.
+ * Better Auth's endpoint lists the sessions through the adapter's default
+ * findMany limit of 100 and revokes only those, so a user with more sessions
+ * kept the rest after "sign out other sessions". This hook runs after the
+ * endpoint and revokes the remainder in batches through the internal adapter,
+ * which also clears their secondary-storage entries when one is configured.
+ */
+export function revokeEveryOtherSession(): BetterAuthPlugin {
+  return {
+    id: "podokit-revoke-every-other-session",
+    hooks: {
+      after: [
+        {
+          matcher: (context) => context.path === "/revoke-other-sessions",
+          handler: createAuthMiddleware(async (ctx) => {
+            const current = ctx.context.session;
+            if (!current) return;
+            let first: string | undefined;
+            for (;;) {
+              const others = await ctx.context.adapter.findMany<{ token: string }>({
+                model: "session",
+                where: [
+                  { field: "userId", value: current.user.id },
+                  { field: "token", value: current.session.token, operator: "ne" },
+                ],
+                limit: BATCH_SIZE,
+              });
+              // Stop when nothing is left, or when a pass removed nothing.
+              if (others.length === 0 || others[0]?.token === first) return;
+              first = others[0]?.token;
+              await ctx.context.internalAdapter.deleteSessions(others.map((session) => session.token));
+            }
+          }),
+        },
+      ],
+    },
+  };
+}

package/dist/templates/modules/auth/files/apps/api/src/auth/schema-recheck.spec.ts

@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { betterAuth, type BetterAuthOptions } from "better-auth";
+import { getMigrations } from "better-auth/db/migration";
+import { createSchemaRecheck, isSchemaMismatch, type SchemaCheckedAuth } from "./schema-recheck";
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function options(database: Database): BetterAuthOptions {
+  return {
+    database,
+    secret: "schema-recheck-test-secret-with-32-characters",
+    baseURL: "http://localhost:5002",
+    emailAndPassword: { enabled: true },
+    logger: { disabled: true },
+  };
+}
+
+async function signUp(auth: ReturnType<typeof betterAuth>): Promise<unknown> {
+  try {
+    await auth.api.signUpEmail({
+      body: { email: `${crypto.randomUUID()}@example.com`, password: "password123", name: "A" },
+    });
+    return "signed up";
+  } catch (error) {
+    return error;
+  }
+}
+
+function fakeAuth(check: () => Promise<void> | undefined): SchemaCheckedAuth {
+  return { $context: Promise.resolve({ checkSchema: check }) };
+}
+
+describe("schema recheck", () => {
+  it("lets an API that started before the migrations sign users up once another process ran them", async () => {
+    const root = mkdtempSync(join(tmpdir(), "schema-recheck-"));
+    roots.push(root);
+    const file = join(root, "auth.sqlite");
+    const api = new Database(file, { create: true });
+    try {
+      let auth = betterAuth(options(api));
+      expect(isSchemaMismatch(await signUp(auth))).toBe(true);
+
+      // migrate:all runs in a process of its own, with a connection of its own.
+      const migrator = new Database(file);
+      await (await getMigrations(options(migrator))).runMigrations();
+      migrator.close();
+      // Better Auth keeps the mismatch it found.
+      expect(isSchemaMismatch(await signUp(auth))).toBe(true);
+
+      await createSchemaRecheck()(auth, () => { auth = betterAuth(options(api)); });
+      expect(await signUp(auth)).toBe("signed up");
+    } finally {
+      api.close();
+    }
+  });
+
+  it("rebuilds at most once per interval while the mismatch lasts", async () => {
+    let clock = 0;
+    let rebuilds = 0;
+    const recheck = createSchemaRecheck({ intervalMs: 2_000, now: () => clock });
+    const mismatched = fakeAuth(() => Promise.reject(Object.assign(new Error("mismatch"), { code: "SCHEMA_MISMATCH" })));
+    await recheck(mismatched, () => { rebuilds += 1; });
+    clock = 1_999;
+    await recheck(mismatched, () => { rebuilds += 1; });
+    expect(rebuilds).toBe(1);
+    clock = 2_000;
+    await recheck(mismatched, () => { rebuilds += 1; });
+    expect(rebuilds).toBe(2);
+  });
+
+  it("leaves a clean schema and an unreachable database alone", async () => {
+    let rebuilds = 0;
+    const recheck = createSchemaRecheck();
+    await recheck(fakeAuth(() => undefined), () => { rebuilds += 1; });
+    await recheck(fakeAuth(() => Promise.reject(new Error("connect ECONNREFUSED"))), () => { rebuilds += 1; });
+    expect(rebuilds).toBe(0);
+  });
+});

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

@@ -0,0 +1,44 @@
+/** The shortest time between two rebuilds while Better Auth reports a schema mismatch. */
+export const SCHEMA_RECHECK_INTERVAL_MS = 2_000;
+
+export interface SchemaCheckedAuth {
+  $context: Promise<{ checkSchema?: (() => Promise<void> | undefined) | undefined }>;
+}
+
+export interface SchemaRecheckOptions {
+  intervalMs?: number;
+  now?: () => number;
+}
+
+export function isSchemaMismatch(error: unknown): boolean {
+  return typeof error === "object" && error !== null && (error as { code?: unknown }).code === "SCHEMA_MISMATCH";
+}
+
+/**
+ * Better Auth keeps a schema mismatch it found until a migration run by the
+ * same process clears it. An API that started before `migrate:all` ran in
+ * another process, such as a separate container, therefore failed every
+ * sign-in until it restarted. The returned function calls `rebuild` when
+ * `auth` holds a mismatch, at most once per interval; the new instance checks
+ * the database again, so the first request after the migration succeeds.
+ */
+export function createSchemaRecheck(
+  options: SchemaRecheckOptions = {},
+): (auth: SchemaCheckedAuth, rebuild: () => void) => Promise<void> {
+  const intervalMs = options.intervalMs ?? SCHEMA_RECHECK_INTERVAL_MS;
+  const now = options.now ?? Date.now;
+  let rebuiltAt = Number.NEGATIVE_INFINITY;
+  return async (auth, rebuild) => {
+    // Nothing is pending once the schema is known to be clean.
+    const pending = (await auth.$context).checkSchema?.();
+    if (!pending) return;
+    try {
+      await pending;
+    } catch (error) {
+      // A failure to reach the database is not kept, so only a mismatch needs a rebuild.
+      if (!isSchemaMismatch(error) || now() - rebuiltAt < intervalMs) return;
+      rebuiltAt = now();
+      rebuild();
+    }
+  };
+}

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

@@ -11,6 +11,7 @@ import {
   SUPPORTED_SOCIAL_PROVIDERS,
 } from "@podosoft/podokit-auth";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { AUTH_CONFIG_DEFAULTS } from "../auth/auth-config-store";
 import { refreshAuthNow } from "../auth/auth-provider";
 import {
   readAuthConfigRow,
@@ -123,7 +124,7 @@ export class AuthConfigService {
   async describe(): Promise<AuthConfigView> {
     const rows = await this.rows();
     const byKey = new Map(rows.map((row) => [row.key, row]));
-    const environment = envAuthConfig();
+    const environment = envAuthConfig(AUTH_CONFIG_DEFAULTS);
     const social: Record<string, SocialProviderView> = {};
 
     for (const row of rows) {

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

@@ -10,6 +10,7 @@ import {
   migrateSqliteLegacyAccountIssuers,
   postgresAccountIssuerMigrationDatabase,
 } from "./auth/account-issuer-migration";
+import { assertMigrationsLoaded } from "./database/migration-files";
 import { runSqliteMigrations } from "./database/sqlite-migrator";
 
 async function runMigrations(): Promise<void> {
@@ -24,9 +25,10 @@ async function runMigrations(): Promise<void> {
   if (sqliteDatabase) {
     await runSqliteMigrations(sqliteDatabase);
   } else {
-    const { appDataSource: dataSource } = await import("./database/data-source.js");
+    const { appDataSource: dataSource, appMigrations } = await import("./database/data-source.js");
     await dataSource.initialize();
     try {
+      assertMigrationsLoaded(dataSource.migrations, appMigrations);
       await dataSource.runMigrations();
     } finally {
       await dataSource.destroy();

package/dist/templates/modules/auth/files/apps/api/src/settings/app-flags.ts

@@ -0,0 +1,9 @@
+// This owned file is never overwritten by `podo update`. Declare the
+// application's on/off settings and their defaults here. They are stored with
+// PodoKit's feature flags in app_setting: administrators change them through
+// PUT /account/settings, the API reads them with SettingsService.getBool(), and
+// GET /account/capabilities returns them as `appFlags`, so do not put anything
+// secret in a name. A missing row keeps the default. For example:
+//
+//   export const APP_FLAG_DEFAULTS = { reportsEnabled: true } satisfies Record<string, boolean>;
+export const APP_FLAG_DEFAULTS = {} satisfies Record<string, boolean>;

package/dist/templates/modules/auth/files/apps/api/src/settings/flag-defaults.spec.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { copyFileSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { FLAG_DEFAULTS, mergeFlagDefaults } from "./flag-defaults";
+
+describe("feature flag defaults", () => {
+  test("adds the application's flags after PodoKit's", () => {
+    const merged = mergeFlagDefaults(FLAG_DEFAULTS, { reportsEnabled: true, betaSearch: false });
+    expect(merged).toMatchObject({ twoFactor: true, phoneNumber: false, reportsEnabled: true, betaSearch: false });
+  });
+
+  test("rejects an application flag that reuses a PodoKit name", () => {
+    expect(() => mergeFlagDefaults(FLAG_DEFAULTS, { passkey: false })).toThrow(
+      "app-flags.ts redefines PodoKit feature flags: passkey",
+    );
+  });
+
+  test("reads stored application flags and keeps their defaults otherwise", async () => {
+    // A copy next to an app-flags.ts of the test's own, in the API directory.
+    const root = mkdtempSync(join(__dirname, ".app-flags-"));
+    try {
+      copyFileSync(join(__dirname, "flag-defaults.ts"), join(root, "flag-defaults.ts"));
+      writeFileSync(
+        join(root, "app-flags.ts"),
+        "export const APP_FLAG_DEFAULTS = { reportsEnabled: true, betaSearch: false };\n",
+      );
+      writeFileSync(join(root, "check.ts"), [
+        'import { APP_FLAGS, FEATURE_FLAGS, flagsFrom } from "./flag-defaults";',
+        'const flags = flagsFrom(new Map([["betaSearch", "true"], ["magicLink", "false"]]));',
+        "console.log(JSON.stringify([APP_FLAGS, FEATURE_FLAGS.includes(\"reportsEnabled\"), flags.reportsEnabled, flags.betaSearch, flags.magicLink]));",
+        "",
+      ].join("\n"));
+      const child = Bun.spawn([process.execPath, join(root, "check.ts")], { stdout: "pipe", stderr: "pipe" });
+      const [stdout, code] = await Promise.all([new Response(child.stdout).text(), child.exited]);
+      expect({ code, stdout: stdout.trim() }).toEqual({
+        code: 0,
+        stdout: '[["reportsEnabled","betaSearch"],true,true,true,false]',
+      });
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/settings/flag-defaults.ts

@@ -1,14 +1,22 @@
-/** Admin-managed auth feature flags and their shipped defaults.
+import { APP_FLAG_DEFAULTS } from "./app-flags";
+
+/** Admin-managed auth feature flags and their shipped defaults, followed by the
+ *  application's flags from the owned app-flags.ts.
  *
  *  Kept free of framework/ORM imports so both SettingsService and the Better
  *  Auth feature gate (loaded by auth.ts, including when
  *  the better-auth CLI evaluates auth.ts for migrations) can import it safely.
  *
- *  Must match the rows seeded by the InitAppSettings migration. phoneNumber is
- *  off by default because real delivery needs an SMS provider. */
-export type FeatureFlag = "twoFactor" | "magicLink" | "emailOtp" | "username" | "multiSession" | "phoneNumber" | "apiKey" | "passkey" | "organization" | "oidcProvider" | "require2fa";
+ *  The PodoKit defaults must match the rows seeded by the InitAppSettings
+ *  migration. phoneNumber is off by default because real delivery needs an SMS
+ *  provider. */
+export type PodokitFeatureFlag = "twoFactor" | "magicLink" | "emailOtp" | "username" | "multiSession" | "phoneNumber" | "apiKey" | "passkey" | "organization" | "oidcProvider" | "require2fa";
+
+export type AppFlag = keyof typeof APP_FLAG_DEFAULTS;
 
-export const FLAG_DEFAULTS: Record<FeatureFlag, boolean> = {
+export type FeatureFlag = PodokitFeatureFlag | AppFlag;
+
+const PODOKIT_FLAG_DEFAULTS: Record<PodokitFeatureFlag, boolean> = {
   twoFactor: true,
   magicLink: true,
   emailOtp: true,
@@ -26,8 +34,25 @@ export const FLAG_DEFAULTS: Record<FeatureFlag, boolean> = {
   require2fa: false,
 };
 
+/** PodoKit's defaults with the application's; an application flag may not reuse a PodoKit name. */
+export function mergeFlagDefaults<App extends Record<string, boolean>>(
+  podokit: Record<PodokitFeatureFlag, boolean>,
+  app: App,
+): Record<PodokitFeatureFlag | keyof App, boolean> {
+  const redefined = Object.keys(app).filter((flag) => flag in podokit);
+  if (redefined.length > 0) {
+    throw new Error(`app-flags.ts redefines PodoKit feature flags: ${redefined.join(", ")}`);
+  }
+  return { ...podokit, ...app };
+}
+
+export const FLAG_DEFAULTS: Record<FeatureFlag, boolean> = mergeFlagDefaults(PODOKIT_FLAG_DEFAULTS, APP_FLAG_DEFAULTS);
+
 export const FEATURE_FLAGS = Object.keys(FLAG_DEFAULTS) as FeatureFlag[];
 
+/** The application's flags, which the capabilities endpoint returns as `appFlags`. */
+export const APP_FLAGS = Object.keys(APP_FLAG_DEFAULTS) as AppFlag[];
+
 /** Stored values override the shipped defaults; a missing row keeps the default. */
 export function flagsFrom(settings: ReadonlyMap<string, string>): Record<FeatureFlag, boolean> {
   const flags = { ...FLAG_DEFAULTS };

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

@@ -6,9 +6,12 @@
   "managedOverrides": [
     ".claude/skills/podokit-configure-auth/**"
   ],
+  "ownedGlobs": [
+    "apps/api/src/settings/app-flags.ts"
+  ],
   "dependencies": {
-    "@podosoft/podokit-auth": "^0.5.0",
-    "@podosoft/podokit-contracts": "^0.5.0",
+    "@podosoft/podokit-auth": "^0.6.0",
+    "@podosoft/podokit-contracts": "^0.6.0",
     "better-auth": "^1.7.7",
     "pg": "^8.12.0",
     "@better-auth/api-key": "^1.7.7",
@@ -28,6 +31,9 @@
     "# makes previously saved DB secrets undecryptable.",
     "BETTER_AUTH_SECRET=change-me-in-production-min-32-characters",
     "BETTER_AUTH_URL=http://localhost:5002",
+    "# The name authenticator apps and passkey prompts show. Unset, it is the site",
+    "# name from the admin Settings, then the project name.",
+    "# AUTH_APP_NAME=",
     "# Everything below is optional. OAuth providers, SMTP, and server-enforced",
     "# toggles are configured on the admin Settings page and applied without restart.",
     "# Email/SMTP is provided by the mailer module (see its .env block).",

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/bullmq-job.queue.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import type { ConnectionOptions } from "bullmq";
+import { Queue, type ConnectionOptions } from "bullmq";
 import { BullMqJobQueue, externalJobId, parseExternalJobId } from "./bullmq-job.queue";
 import { producerConnection, reconnectDelay, redisConnection } from "./queue";
 
@@ -128,3 +128,59 @@ describe("BullMqJobQueue while Redis is unavailable", () => {
     }
   });
 });
+
+describe("BullMqJobQueue schedules", () => {
+  it("rejects an invalid schedule before keeping it", async () => {
+    const queue = new BullMqJobQueue(producerAt(closedPort()));
+    try {
+      await expect(queue.schedule("bad", "report", {}, { cron: "61 * * * *" })).rejects.toThrow();
+      await expect(queue.schedule("bad", "report", {}, { cron: "0 3 * * *", timezone: "Mars/Olympus" })).rejects.toThrow();
+      await expect(queue.schedule("bad", "report", {}, { everyMs: 10 })).rejects.toThrow("at least 1000");
+    } finally {
+      await queue.close();
+    }
+  });
+
+  it("keeps a schedule while Redis is unreachable instead of failing", async () => {
+    const queue = new BullMqJobQueue(producerAt(closedPort()));
+    try {
+      await expect(queue.schedule("nightly", "report", {}, { cron: "0 3 * * *" })).resolves.toBeUndefined();
+      await expect(queue.unschedule("nightly")).resolves.toBeUndefined();
+    } finally {
+      await queue.close();
+    }
+  });
+});
+
+// Runs against the Redis the app's environment names (REDIS_URL or REDIS_HOST, as
+// in .env); skipped when neither is set.
+describe.skipIf(!process.env.REDIS_URL && !process.env.REDIS_HOST)("BullMqJobQueue schedules in Redis", () => {
+  const REDIS = process.env;
+  it("applies schedules on connect, again after Redis lost them, and removes them", async () => {
+    const name = `schedule-test-${crypto.randomUUID()}`;
+    const queue = new BullMqJobQueue(producerConnection(REDIS));
+    const inspect = new Queue(name, { connection: redisConnection(REDIS) });
+    try {
+      await queue.schedule("hourly", name, { scope: "all" }, { everyMs: 3_600_000 });
+      await queue.schedule("nightly", name, {}, { cron: "0 3 * * *", timezone: "Asia/Seoul" });
+      expect(await inspect.getJobScheduler("hourly")).toBeUndefined();
+
+      await queue.connect();
+      expect(await inspect.getJobScheduler("hourly")).toMatchObject({ every: 3_600_000, name });
+      expect(await inspect.getJobScheduler("nightly")).toMatchObject({ pattern: "0 3 * * *", tz: "Asia/Seoul" });
+
+      // A Redis that lost its data gets the schedules back on the next connect.
+      await inspect.removeJobScheduler("hourly");
+      await queue.connect();
+      expect(await inspect.getJobScheduler("hourly")).toMatchObject({ every: 3_600_000 });
+
+      await queue.unschedule("nightly");
+      expect(await inspect.getJobScheduler("nightly")).toBeUndefined();
+      expect(await inspect.getJobSchedulersCount()).toBe(1);
+    } finally {
+      await queue.close();
+      await inspect.obliterate({ force: true });
+      await inspect.close();
+    }
+  });
+});