exp-node-server 1.1.7 → 2.1.0

package/templates/mongoose/src/app/passport-js/oauth-state.ts

@@ -0,0 +1,150 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  hkdfSync,
+  randomBytes,
+  timingSafeEqual,
+} from 'node:crypto';
+import type { CookieOptions, Request, Response } from 'express';
+import { configs } from '../configs/index.js';
+
+/**
+ * Stateless OAuth handshake storage. Instead of a server-side session, the data a
+ * provider round trip needs (CSRF state, PKCE verifier, OAuth 1.0a request token)
+ * lives in a short-lived, encrypted, httpOnly cookie scoped to the social routes.
+ * Works across instances and restarts, and nothing accumulates in memory.
+ */
+
+const STATE_TTL_MS = 10 * 60 * 1000;
+
+// separate key for this purpose, derived from the access token secret
+const key = Buffer.from(hkdfSync('sha256', configs.jwt.access_token, '', 'oauth-state-cookie', 32));
+
+const cookieOptions: CookieOptions = {
+  httpOnly: true,
+  secure: configs.is_production,
+  // the provider sends the user back with a top-level GET, which `lax` allows
+  sameSite: 'lax',
+  path: '/api/auth/social',
+};
+
+const cookieName = (provider: string) => `oauth_${provider}`;
+
+const seal = (data: object): string => {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const body = JSON.stringify({ ...data, exp: Date.now() + STATE_TTL_MS });
+  const encrypted = Buffer.concat([cipher.update(body, 'utf8'), cipher.final()]);
+  return Buffer.concat([iv, cipher.getAuthTag(), encrypted]).toString('base64url');
+};
+
+const unseal = <T>(value: unknown): T | undefined => {
+  if (typeof value !== 'string') return undefined;
+  try {
+    const raw = Buffer.from(value, 'base64url');
+    const decipher = createDecipheriv('aes-256-gcm', key, raw.subarray(0, 12));
+    decipher.setAuthTag(raw.subarray(12, 28));
+    const body = Buffer.concat([decipher.update(raw.subarray(28)), decipher.final()]);
+    const data = JSON.parse(body.toString('utf8'));
+    return data.exp > Date.now() ? data : undefined;
+  } catch {
+    return undefined; // tampered, wrong key or malformed
+  }
+};
+
+const res = (req: Request): Response => req.res!;
+
+/** Reads and clears the handshake cookie, so it can only be used once. */
+const take = <T>(req: Request, provider: string): T | undefined => {
+  res(req).clearCookie(cookieName(provider), cookieOptions);
+  return unseal<T>(req.cookies?.[cookieName(provider)]);
+};
+
+const put = (req: Request, provider: string, data: object) => {
+  res(req).cookie(cookieName(provider), seal(data), { ...cookieOptions, maxAge: STATE_TTL_MS });
+};
+
+const safeEqual = (a: string, b: string) => {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && timingSafeEqual(x, y);
+};
+
+/**
+ * `?returnTo=` lets the front-end resume where the user was. Only same-site paths
+ * are kept (no `//host` or `\` tricks), so it can't become an open redirect.
+ */
+const readReturnTo = (req: Request): string | undefined => {
+  const value = req.query.returnTo;
+  if (typeof value !== 'string' || value.length > 512) return undefined;
+  return /^\/(?![/\\])[^\\]*$/.test(value) ? value : undefined;
+};
+
+/** The `returnTo` saved when the login started, available in the callback. */
+export const getReturnTo = (res: Response): string | undefined => res.locals.oauthReturnTo;
+
+type OAuth2State = { handle: string; verifier?: string; returnTo?: string };
+
+/** passport-oauth2 state store: `state` parameter (CSRF) + PKCE verifier. */
+export class CookieStateStore {
+  constructor(private readonly provider: string) {}
+
+  store(
+    req: Request,
+    verifier: string | undefined,
+    _state: unknown,
+    _meta: unknown,
+    callback: (err: Error | null, handle?: string) => void,
+  ) {
+    const handle = randomBytes(24).toString('base64url');
+    put(req, this.provider, {
+      handle,
+      verifier,
+      returnTo: readReturnTo(req),
+    } satisfies OAuth2State);
+    callback(null, handle);
+  }
+
+  verify(
+    req: Request,
+    providedState: unknown,
+    callback: (err: Error | null, ok: string | boolean, info?: { message: string }) => void,
+  ) {
+    const saved = take<OAuth2State>(req, this.provider);
+    if (!saved || typeof providedState !== 'string' || !safeEqual(saved.handle, providedState)) {
+      return callback(null, false, { message: 'invalid_state' });
+    }
+    res(req).locals.oauthReturnTo = saved.returnTo;
+    // a string tells passport-oauth2 to send it as the PKCE `code_verifier`
+    callback(null, saved.verifier ?? true);
+  }
+}
+
+type OAuth1State = { token: string; tokenSecret: string; returnTo?: string };
+
+/** passport-oauth1 request token store (Twitter / X). */
+export class CookieRequestTokenStore {
+  constructor(private readonly provider: string) {}
+
+  get(req: Request, token: string, callback: (err: Error | null, tokenSecret?: string) => void) {
+    const saved = take<OAuth1State>(req, this.provider);
+    if (!saved || typeof token !== 'string' || !safeEqual(saved.token, token)) {
+      return callback(new Error('invalid_state'));
+    }
+    res(req).locals.oauthReturnTo = saved.returnTo;
+    callback(null, saved.tokenSecret);
+  }
+
+  set(req: Request, token: string, tokenSecret: string, callback: (err?: Error) => void) {
+    put(req, this.provider, {
+      token,
+      tokenSecret,
+      returnTo: readReturnTo(req),
+    } satisfies OAuth1State);
+    callback();
+  }
+
+  destroy(_req: Request, _token: string, callback: (err?: Error) => void) {
+    callback(); // already cleared by get()
+  }
+}

package/templates/mongoose/src/app/passport-js/providers.ts

@@ -0,0 +1,258 @@
+import type { PROVIDER } from '../modules/account/account.interface.js';
+import type { Profile, Strategy } from 'passport';
+import { Strategy as FacebookStrategy } from 'passport-facebook';
+import { Strategy as GithubStrategy } from 'passport-github';
+import { Strategy as GoogleStrategy } from 'passport-google-oauth20';
+import OAuth1Strategy, { InternalOAuthError as OAuth1Error } from 'passport-oauth1';
+import OAuth2Strategy, { InternalOAuthError } from 'passport-oauth2';
+import { configs } from '../configs/index.js';
+import { CookieRequestTokenStore, CookieStateStore } from './oauth-state.js';
+import { findOrCreateSocialAccount } from './social-account.js';
+
+type Done = (err: unknown, user?: Express.User | false) => void;
+
+export type SocialProviderName =
+  'google' | 'facebook' | 'github' | 'twitter' | 'linkedin' | 'discord';
+
+export interface SocialProvider {
+  /** Passport strategy name, also used in the route: `/api/auth/social/<name>`. */
+  name: SocialProviderName;
+  /** Human readable name, e.g. for login buttons. */
+  label: string;
+  provider: PROVIDER;
+  enabled: boolean;
+  createStrategy: () => Strategy;
+}
+
+/** Shared verify callback: map the provider profile to one of our accounts. */
+const verify =
+  (provider: PROVIDER) =>
+  (_token: string, _tokenSecret: string, profile: Profile, done: Done): void => {
+    findOrCreateSocialAccount(profile, provider).then(
+      (user) => done(null, user),
+      (err) => done(err),
+    );
+  };
+
+/**
+ * Minimal OAuth 2.0 strategy for providers without a maintained passport package:
+ * fetches `profileURL` with the access token and maps the JSON to a passport profile.
+ */
+class JsonProfileStrategy extends OAuth2Strategy {
+  constructor(
+    name: string,
+    options: OAuth2Strategy.StrategyOptions,
+    private readonly profileURL: string,
+    private readonly toProfile: (json: Record<string, unknown>) => Profile,
+  ) {
+    super(options, verify(name.toUpperCase() as PROVIDER));
+    this.name = name;
+    this._oauth2.useAuthorizationHeaderforGET(true);
+  }
+
+  override userProfile(accessToken: string, done: (err?: unknown, profile?: Profile) => void) {
+    this._oauth2.get(this.profileURL, accessToken, (err, body) => {
+      if (err) return done(new InternalOAuthError('Failed to fetch user profile', err));
+      try {
+        done(null, this.toProfile(JSON.parse(String(body))));
+      } catch (e) {
+        done(e);
+      }
+    });
+  }
+}
+
+/**
+ * X (Twitter) login over OAuth 1.0a, which is what returns the user's email. Built on
+ * passport-oauth1 directly: the old passport-twitter package is unmaintained and
+ * pulls in a vulnerable XML parser.
+ */
+class TwitterStrategy extends OAuth1Strategy {
+  constructor(options: { consumerKey: string; consumerSecret: string; callbackURL: string }) {
+    super(
+      {
+        ...options,
+        requestTokenURL: 'https://api.twitter.com/oauth/request_token',
+        accessTokenURL: 'https://api.twitter.com/oauth/access_token',
+        userAuthorizationURL: 'https://api.twitter.com/oauth/authenticate',
+        // the request token lives in an encrypted cookie instead of a session
+        requestTokenStore: new CookieRequestTokenStore('twitter'),
+      },
+      verify('TWITTER'),
+    );
+    this.name = 'twitter';
+  }
+
+  override userProfile(
+    token: string,
+    tokenSecret: string,
+    _params: unknown,
+    done: (err?: unknown, profile?: Profile) => void,
+  ) {
+    const url =
+      'https://api.twitter.com/1.1/account/verify_credentials.json?include_email=true&skip_status=true';
+    this._oauth.get(url, token, tokenSecret, (err, body) => {
+      if (err) return done(new OAuth1Error('Failed to fetch user profile', err));
+      try {
+        const json = JSON.parse(String(body));
+        done(null, {
+          provider: 'twitter',
+          id: String(json.id_str),
+          displayName: str(json.name) ?? str(json.screen_name) ?? '',
+          // X only returns the email when it is verified
+          emails: json.email ? [{ value: String(json.email) }] : [],
+          photos: str(json.profile_image_url_https)
+            ? [{ value: json.profile_image_url_https }]
+            : [],
+        });
+      } catch (e) {
+        done(e);
+      }
+    });
+  }
+}
+
+/**
+ * `state` (login CSRF protection) and optional PKCE, kept in an encrypted cookie.
+ * Typed as `object` because the strategy typings don't all declare these options.
+ */
+const oauthState = (name: SocialProviderName, pkce = false): object => ({
+  store: new CookieStateStore(name),
+  state: true,
+  ...(pkce && { pkce: true }),
+});
+
+const str = (value: unknown) => (typeof value === 'string' && value ? value : undefined);
+
+const { google, facebook, github, twitter, linkedin, discord } = configs.social;
+
+// every OAuth 2.0 provider gets `state`; PKCE is enabled where the provider supports it
+export const socialProviders: SocialProvider[] = [
+  {
+    name: 'google',
+    label: 'Google',
+    provider: 'GOOGLE',
+    enabled: google.enabled,
+    createStrategy: () =>
+      new GoogleStrategy(
+        {
+          clientID: google.client_id,
+          clientSecret: google.client_secret,
+          callbackURL: google.callback_url,
+          scope: ['openid', 'email', 'profile'],
+          ...oauthState('google', true),
+        },
+        verify('GOOGLE'),
+      ),
+  },
+  {
+    name: 'facebook',
+    label: 'Facebook',
+    provider: 'FACEBOOK',
+    enabled: facebook.enabled,
+    createStrategy: () =>
+      new FacebookStrategy(
+        {
+          clientID: facebook.client_id,
+          clientSecret: facebook.client_secret,
+          callbackURL: facebook.callback_url,
+          scope: ['email', 'public_profile'],
+          profileFields: ['id', 'displayName', 'emails', 'photos'],
+          ...oauthState('facebook'),
+        },
+        verify('FACEBOOK'),
+      ),
+  },
+  {
+    name: 'github',
+    label: 'GitHub',
+    provider: 'GITHUB',
+    enabled: github.enabled,
+    createStrategy: () =>
+      new GithubStrategy(
+        {
+          clientID: github.client_id,
+          clientSecret: github.client_secret,
+          callbackURL: github.callback_url,
+          scope: ['user:email'],
+          ...oauthState('github'),
+        },
+        verify('GITHUB'),
+      ),
+  },
+  {
+    name: 'twitter',
+    label: 'X (Twitter)',
+    provider: 'TWITTER',
+    enabled: twitter.enabled,
+    createStrategy: () =>
+      new TwitterStrategy({
+        consumerKey: twitter.client_id,
+        consumerSecret: twitter.client_secret,
+        callbackURL: twitter.callback_url,
+      }),
+  },
+  {
+    // "Sign In with LinkedIn using OpenID Connect"
+    name: 'linkedin',
+    label: 'LinkedIn',
+    provider: 'LINKEDIN',
+    enabled: linkedin.enabled,
+    createStrategy: () =>
+      new JsonProfileStrategy(
+        'linkedin',
+        {
+          authorizationURL: 'https://www.linkedin.com/oauth/v2/authorization',
+          tokenURL: 'https://www.linkedin.com/oauth/v2/accessToken',
+          clientID: linkedin.client_id,
+          clientSecret: linkedin.client_secret,
+          callbackURL: linkedin.callback_url,
+          scope: ['openid', 'profile', 'email'],
+          ...oauthState('linkedin'),
+        },
+        'https://api.linkedin.com/v2/userinfo',
+        (json) => ({
+          provider: 'linkedin',
+          id: String(json.sub),
+          displayName: str(json.name) ?? '',
+          emails: json.email
+            ? [{ value: String(json.email), verified: json.email_verified === true } as never]
+            : [],
+          photos: str(json.picture) ? [{ value: String(json.picture) }] : [],
+        }),
+      ),
+  },
+  {
+    name: 'discord',
+    label: 'Discord',
+    provider: 'DISCORD',
+    enabled: discord.enabled,
+    createStrategy: () =>
+      new JsonProfileStrategy(
+        'discord',
+        {
+          authorizationURL: 'https://discord.com/oauth2/authorize',
+          tokenURL: 'https://discord.com/api/oauth2/token',
+          clientID: discord.client_id,
+          clientSecret: discord.client_secret,
+          callbackURL: discord.callback_url,
+          scope: ['identify', 'email'],
+          ...oauthState('discord'),
+        },
+        'https://discord.com/api/users/@me',
+        (json) => ({
+          provider: 'discord',
+          id: String(json.id),
+          displayName: str(json.global_name) ?? str(json.username) ?? '',
+          emails: json.email
+            ? [{ value: String(json.email), verified: json.verified === true } as never]
+            : [],
+          photos: str(json.avatar)
+            ? [{ value: `https://cdn.discordapp.com/avatars/${json.id}/${json.avatar}.png` }]
+            : [],
+        }),
+      ),
+  },
+];
+
+export const enabledSocialProviders = socialProviders.filter((p) => p.enabled);

package/templates/mongoose/src/app/passport-js/social-account.ts

@@ -0,0 +1,141 @@
+import { createHash, randomBytes } from 'node:crypto';
+import type { Types } from 'mongoose';
+import type { Profile } from 'passport';
+import type { PROVIDER } from '../modules/account/account.interface.js';
+import {
+  account_model,
+  createAccountWithProfile,
+  social_account_model,
+  social_login_code_model,
+} from '../modules/account/account.schema.js';
+import type { TokenUser } from '../utils/JWT.js';
+
+/** How long the front-end has to exchange the code from the social login redirect. */
+export const SOCIAL_LOGIN_CODE_TTL_MS = 60 * 1000;
+
+/** A failed social login. `code` is sent to the front-end as `?error=<code>`. */
+export class SocialLoginError extends Error {
+  constructor(
+    public code: 'email_unverified' | 'account_disabled' | 'invalid_profile',
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+type ProfileEmail = { value: string; verified?: boolean | string; primary?: boolean };
+
+const isVerified = (e: ProfileEmail) => e.verified === true || e.verified === 'true';
+
+// Facebook and X only ever return confirmed addresses; the others say whether the
+// address is verified, and unverified ones are ignored
+const ONLY_RETURNS_VERIFIED_EMAILS: PROVIDER[] = ['FACEBOOK', 'TWITTER'];
+
+/** Picks an email we can trust, preferring the primary one. */
+const pickEmail = (profile: Profile, provider: PROVIDER): string | undefined => {
+  const emails = (profile.emails ?? []) as ProfileEmail[];
+  const trusted = ONLY_RETURNS_VERIFIED_EMAILS.includes(provider)
+    ? emails
+    : emails.filter(isVerified);
+  return (trusted.find((e) => e.primary) ?? trusted[0])?.value?.toLowerCase();
+};
+
+const USER_FIELDS = 'email role isDeleted tokenVersion';
+
+type AccountForToken = {
+  _id: Types.ObjectId;
+  email: string;
+  role: TokenUser['role'];
+  isDeleted: boolean;
+  tokenVersion: number;
+};
+
+const toUser = (account: AccountForToken): TokenUser => {
+  if (account.isDeleted) {
+    throw new SocialLoginError('account_disabled', 'Account is deleted');
+  }
+  return {
+    accountId: String(account._id),
+    email: account.email,
+    role: account.role,
+    tokenVersion: account.tokenVersion,
+  };
+};
+
+/**
+ * Finds or creates the account for a social login and returns the user for `req.user`.
+ *
+ * 1. A provider identity that was used before logs straight into its account.
+ * 2. Otherwise the provider's verified email links the identity to the account with
+ *    that email, or creates a new account.
+ */
+export const findOrCreateSocialAccount = async (
+  profile: Profile,
+  provider: PROVIDER,
+): Promise<TokenUser> => {
+  const providerUserId = profile.id ? String(profile.id) : '';
+  if (!providerUserId) {
+    throw new SocialLoginError('invalid_profile', 'The provider did not return a user id');
+  }
+
+  const linked = await social_account_model.findOne({ provider, providerUserId }).lean();
+  if (linked) {
+    const account = await account_model.findById(linked.accountId).select(USER_FIELDS).lean();
+    if (account) return toUser(account);
+    // the account was removed; drop the stale link and continue as a new login
+    await social_account_model.deleteOne({ _id: linked._id });
+  }
+
+  const email = pickEmail(profile, provider);
+  if (!email) {
+    throw new SocialLoginError(
+      'email_unverified',
+      `Your ${provider.toLowerCase()} account doesn't have a verified email address.`,
+    );
+  }
+
+  const existing = await account_model
+    .findOne({ email })
+    .select(`${USER_FIELDS} isAccountVerified`)
+    .lean();
+
+  let account: AccountForToken;
+  if (!existing) {
+    account = await createAccountWithProfile(
+      { email, password: null, provider, isAccountVerified: true },
+      {
+        fullName: profile.displayName || email.split('@')[0]!,
+        profilePhoto: profile.photos?.[0]?.value ?? null,
+      },
+    );
+  } else {
+    toUser(existing); // rejects deleted accounts before linking anything
+    account = existing;
+
+    if (!existing.isAccountVerified) {
+      // The provider just proved ownership of this email, but nobody ever proved the
+      // password on this unverified account belongs to the owner (it may have been
+      // registered by someone else). Verify the account and drop that password.
+      await account_model.updateOne(
+        { _id: existing._id },
+        { $set: { isAccountVerified: true, password: null, lastOtp: null, otpAttempts: 0 } },
+      );
+    }
+  }
+
+  await social_account_model.create({ accountId: account._id, provider, providerUserId });
+  return toUser(account);
+};
+
+export const hashLoginCode = (code: string) => createHash('sha256').update(code).digest('hex');
+
+/** Creates the single-use code the front-end exchanges for an access token. */
+export const createSocialLoginCode = async (accountId: string): Promise<string> => {
+  const code = randomBytes(32).toString('base64url');
+  await social_login_code_model.create({
+    _id: hashLoginCode(code),
+    accountId,
+    expiresAt: new Date(Date.now() + SOCIAL_LOGIN_CODE_TTL_MS),
+  });
+  return code;
+};

package/templates/mongoose/src/app/queues/agenda.ts

@@ -0,0 +1,36 @@
+import { MongoBackend } from '@agendajs/mongo-backend';
+import { Agenda } from 'agenda';
+import mongoose from 'mongoose';
+import { logger } from '../lib/logger.js';
+
+export type AgendaOptions = {
+  /** How often a worker looks for due jobs (ms or a human interval). */
+  processEvery?: string | number;
+};
+
+/**
+ * Agenda stores jobs in the app's MongoDB (`agendaJobs` collection), so no Redis
+ * is needed. Created on start, once mongoose is connected, to reuse its connection.
+ */
+let agenda: Agenda | undefined;
+
+/** A new Agenda instance (a worker) on the app's MongoDB connection. */
+export const newAgenda = ({ processEvery = '5 seconds' }: AgendaOptions = {}) => {
+  const instance = new Agenda({
+    backend: new MongoBackend({ mongo: mongoose.connection.db! }),
+    processEvery,
+  });
+  instance.on('error', (err) => logger.error(err, 'Agenda error'));
+  return instance;
+};
+
+/** Creates the app's Agenda instance, used by `enqueueEmail()` & co. */
+export const createAgenda = (options?: AgendaOptions) => {
+  agenda = newAgenda(options);
+  return agenda;
+};
+
+export const getAgenda = (): Agenda => {
+  if (!agenda) throw new Error('Queues are not started, call startQueues() first');
+  return agenda;
+};

package/templates/mongoose/src/app/queues/email.queue.ts

@@ -0,0 +1,81 @@
+import { type Agenda, exponential, type Job } from 'agenda';
+import mongoose from 'mongoose';
+import { configs } from '../configs/index.js';
+import { logger } from '../lib/logger.js';
+import { otpEmailTemplate } from '../templates/otpEmailTemplate.js';
+import { resetPasswordEmailTemplate } from '../templates/resetPasswordEmailTemplate.js';
+import sendMail from '../utils/mail_sender.js';
+import { getAgenda } from './agenda.js';
+
+export const EMAIL_QUEUE = 'email';
+// Agenda's default collection (see agenda.ts)
+export const JOBS_COLLECTION = 'agendaJobs';
+
+/** Every email the app sends goes through this one queue. */
+export type EmailJob =
+  | { type: 'verify-account'; email: string; otp: string; verificationLink: string }
+  | { type: 'reset-password'; email: string; resetLink: string };
+
+const render = (job: EmailJob) => {
+  switch (job.type) {
+    case 'verify-account':
+      return {
+        subject: 'Verify Your Email',
+        htmlBody: otpEmailTemplate(job),
+        textBody: `Your verification code is ${job.otp}. Or verify using this link: ${job.verificationLink}`,
+      };
+    case 'reset-password':
+      return {
+        subject: 'Reset Your Password',
+        htmlBody: resetPasswordEmailTemplate(job.resetLink, configs.jwt.reset_expires),
+        textBody: `Reset your password using this link: ${job.resetLink}`,
+      };
+  }
+};
+
+export type EmailJobOptions = {
+  /** Delay before the first retry; it doubles on every further retry. */
+  retryDelayMs?: number;
+  maxRetries?: number;
+};
+
+/** Registers the email job on a worker. */
+export const defineEmailJob = (
+  agenda: Agenda,
+  { retryDelayMs = 10_000, maxRetries = 3 }: EmailJobOptions = {},
+) =>
+  agenda.define(
+    EMAIL_QUEUE,
+    async ({ attrs }: Job<EmailJob>) => {
+      const data = attrs.data;
+      try {
+        await sendMail({ to: data.email, ...render(data) });
+        logger.info(`Email (${data.type}) sent to ${data.email}`);
+      } catch (err) {
+        logger.error({ err, jobId: attrs._id }, `Failed to send ${data.type} email, will retry`);
+        throw err; // let Agenda retry the job
+      }
+    },
+    {
+      backoff: exponential({ delay: retryDelayMs, factor: 2, maxRetries }),
+      // Not `removeOnComplete`: Agenda emits "complete" before it forgets the job,
+      // and the extra await of the removal makes drain() miss it and hang until its
+      // timeout on every shutdown. A TTL index cleans up instead (below).
+    },
+  );
+
+/**
+ * Jobs carry OTPs and reset links, so finished email jobs (sent or given up on)
+ * are deleted by MongoDB an hour later. Only the email job: other jobs are kept.
+ */
+export const ensureEmailJobCleanup = () =>
+  mongoose.connection.db!.collection(JOBS_COLLECTION).createIndex(
+    { lastFinishedAt: 1 },
+    {
+      name: 'email_jobs_ttl',
+      expireAfterSeconds: 60 * 60,
+      partialFilterExpression: { name: EMAIL_QUEUE },
+    },
+  );
+
+export const enqueueEmail = (job: EmailJob) => getAgenda().now(EMAIL_QUEUE, job);

package/templates/mongoose/src/app/queues/index.ts

@@ -0,0 +1,17 @@
+import { logger } from '../lib/logger.js';
+import { type AgendaOptions, createAgenda, getAgenda } from './agenda.js';
+import { defineEmailJob, type EmailJobOptions, ensureEmailJobCleanup } from './email.queue.js';
+
+/** The defaults are meant for production; tests pass shorter delays. */
+export type QueueOptions = AgendaOptions & EmailJobOptions;
+
+export const startQueues = async (options: QueueOptions = {}) => {
+  const agenda = createAgenda(options);
+  defineEmailJob(agenda, options);
+  await ensureEmailJobCleanup();
+  await agenda.start();
+  logger.info('Queues are running...');
+};
+
+// waits for running jobs to finish (up to 30s) instead of abandoning them
+export const stopQueues = () => getAgenda().drain(30_000);