Authentication

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    ThrottlerModule.forRoot([{ ttl: minutes(1), limit: 100 }]),
    AuthenticationModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        session: {
          absoluteTtl: '14d', // signed out after 14 days, however active
          idleTtl: '3d', // or after 3 days without a request
          metadata: (request) => ({ userAgent: request.headers['user-agent'] }),
        },
        accessToken: {
          key: config.getOrThrow<string>('JWT_SECRET'), // openssl rand -hex 32
          issuer: 'https://api.bookshelf.test',
          audience: 'bookshelf-mobile',
          ttl: '15m',
        },
        mfa: {
          issuer: 'bookshelf.test',
          encryption: { keys: [config.getOrThrow<string>('TOTP_ENCRYPTION_KEY')] },
        },
        emailVerification: { url: `${config.getOrThrow<string>('APP_URL')}/verify-email` },
        passwordReset: { url: `${config.getOrThrow<string>('APP_URL')}/reset-password` },
        magicLink: { url: `${config.getOrThrow<string>('APP_URL')}/sign-in/magic` },
        oidc: {
          callbackUrl: `${config.getOrThrow<string>('APP_URL')}/auth/oidc/:provider/callback`,
          providers: {
            google: google({
              clientId: config.getOrThrow<string>('GOOGLE_CLIENT_ID'),
              clientSecret: config.getOrThrow<string>('GOOGLE_CLIENT_SECRET'),
            }),
          },
        },
      }),
    }),
  ],

curl -i http://localhost:3000/me

{ "message": "Unauthorized", "statusCode": 401 }

import { Injectable } from '@nestjs/common';
import { AuthenticationRegistry, SessionCookieProvider, type SessionRecord } from '@nestjs/authentication';
import type { User } from './user.js';
import { UsersRepository } from './users.repository.js';

@Injectable()
export class SessionAuth extends SessionCookieProvider<User> {
  constructor(
    private readonly usersRepository: UsersRepository,
    registry: AuthenticationRegistry,
  ) {
    super();
    registry.registerProvider(this); // order 0: asked first
  }

  // Called for every request with a live session cookie.
  // Returning null (the user was deleted) ends the session.
  validate(session: SessionRecord) {
    return this.usersRepository.findById(session.userId);
  }
}

import { Injectable } from '@nestjs/common';
import { AuthenticationRegistry, JwtBearerProvider, type JwtClaims } from '@nestjs/authentication';
import type { User } from './user.js';
import { UsersRepository } from './users.repository.js';

@Injectable()
export class JwtAuth extends JwtBearerProvider<User> {
  constructor(
    private readonly usersRepository: UsersRepository,
    registry: AuthenticationRegistry,
  ) {
    // The key, issuer and audience come from the `accessToken` module options.
    super({ realm: 'bookshelf' });
    registry.registerProvider(this, { order: 1 });
  }

  validate({ sub }: JwtClaims) {
    return sub ? this.usersRepository.findById(sub) : null;
  }
}

import { ConflictException, Injectable } from '@nestjs/common';
import { PasswordHasher } from '@nestjs/authentication';
import type { User } from './user.js';
import { UsersRepository } from './users.repository.js';

@Injectable()
export class CredentialsService {
  constructor(
    private readonly usersRepository: UsersRepository,
    private readonly passwordHasher: PasswordHasher,
  ) {}

  async register(email: string, password: string): Promise<User> {
    if (await this.usersRepository.findByEmail(email)) {
      throw new ConflictException('Email already registered');
    }
    // Unverified: anyone can type any address into a sign-up form.
    return this.usersRepository.create(email, await this.passwordHasher.hash(password));
  }

  /** The user, or `null` when the email or the password is wrong. */
  async verify(email: string, password: string): Promise<User | null> {
    const found = await this.usersRepository.findCredentials(email);
    // With no account, verify() checks a dummy hash: same timing, same answer.
    const valid = await this.passwordHasher.verify(password, found?.passwordHash ?? undefined);
    if (!valid || !found?.passwordHash) {
      return null;
    }
    if (this.passwordHasher.needsRehash(found.passwordHash)) {
      await this.usersRepository.updatePasswordHash(found.user.id, await this.passwordHasher.hash(password));
    }
    return found.user;
  }
}

import { IsEmail, IsOptional, IsString, MaxLength, MinLength } from 'class-validator';

export class SignUpDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(12)
  @MaxLength(128)
  password: string;
}

export class SignInDto {
  @IsEmail()
  email: string;

  @IsString()
  password: string;
}

export class EmailDto {
  @IsEmail()
  email: string;
}

/** The mobile app's sign-in: a password, and a code once the user has an authenticator. */
export class TokenRequestDto extends SignInDto {
  @IsOptional()
  @IsString()
  code?: string;

  @IsOptional()
  @IsString()
  recoveryCode?: string;
}

export class ResetPasswordDto {
  @IsString()
  token: string;

  @IsString()
  @MinLength(12)
  @MaxLength(128)
  password: string;
}

import { Body, Controller, HttpCode, Post, UnauthorizedException } from '@nestjs/common';
import { EmailVerificationService, Public, SignInService } from '@nestjs/authentication';
import { Throttle, minutes } from '@nestjs/throttler';
import { SignInDto, SignUpDto } from './auth.dto.js';
import { CredentialsService } from './credentials.service.js';

@Public()
@Controller('auth')
export class AuthController {
  constructor(
    private readonly credentialsService: CredentialsService,
    private readonly signInService: SignInService,
    private readonly emailVerificationService: EmailVerificationService,
  ) {}

  @Post('sign-up')
  async signUp(@Body() body: SignUpDto) {
    const user = await this.credentialsService.register(body.email, body.password);
    await this.signInService.signIn(user.id, { method: 'password' });
    await this.emailVerificationService.send(user); // the link proves the address
    return user;
  }

  @Throttle({ default: { limit: 5, ttl: minutes(15) } })
  @Post('sign-in')
  @HttpCode(200)
  async signIn(@Body() body: SignInDto) {
    const user = await this.credentialsService.verify(body.email, body.password);
    if (!user) {
      throw new UnauthorizedException('Invalid email or password');
    }
    const { session } = await this.signInService.signIn(user.id, { method: 'password' });
    return { mfaRequired: session.mfa === 'pending' };
  }
}

Set-Cookie: __Host-sid=<token>; Max-Age=1209600; Path=/; HttpOnly; Secure; SameSite=Lax

curl -i -c jar.txt -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"<at least 12 characters>"}' http://localhost:3000/auth/sign-up
curl -b jar.txt http://localhost:3000/me

{ "id": "63ab04ac-19e5-4ac5-876f-dde9cc75b584", "email": "ada@example.com", "emailVerified": false, "roles": ["reader"] }

{ "message": ["email must be an email", "password must be longer than or equal to 12 characters"], "error": "Bad Request", "statusCode": 400 }

import { Injectable } from '@nestjs/common';

/** Stand-in for a mail library: keeps the last link sent to each address. */
@Injectable()
export class LinkOutbox {
  readonly sent: { kind: string; email: string; url: string }[] = [];

  push(kind: string, email: string, url: string) {
    this.sent.push({ kind, email, url });
  }

  last(kind: string, email: string) {
    return [...this.sent].reverse().find((m) => m.kind === kind && m.email === email);
  }
}

import { ForbiddenException, Injectable } from '@nestjs/common';
import {
  AuthenticationRegistry,
  EmailVerificationHandler,
  MagicLinkHandler,
  PasswordResetHandler,
  type EmailVerificationLink,
  type MagicLink,
  type PasswordResetLink,
} from '@nestjs/authentication';
import { LinkOutbox } from './link-outbox.js';
import { UsersRepository } from './users.repository.js';

@Injectable()
export class EmailVerificationMailer extends EmailVerificationHandler {
  constructor(
    private readonly usersRepository: UsersRepository,
    private readonly outbox: LinkOutbox,
    registry: AuthenticationRegistry,
  ) {
    super();
    registry.registerHandler('emailVerification', this);
  }

  // With @nestjs/mail this is `await this.mailer.send(VerifyEmailMail, { to: link.email, data: link })`.
  send(link: EmailVerificationLink) {
    this.outbox.push('verify', link.email, link.url);
  }

  // Runs when the link is used; verifies nothing if the address changed since.
  markVerified(userId: string, email: string) {
    return this.usersRepository.markEmailVerified(userId, email);
  }
}

@Injectable()
export class PasswordResetMailer extends PasswordResetHandler {
  constructor(
    private readonly usersRepository: UsersRepository,
    private readonly outbox: LinkOutbox,
    registry: AuthenticationRegistry,
  ) {
    super();
    registry.registerHandler('passwordReset', this);
  }

  // The link goes to the stored address, and works only while address and hash stay the same.
  async findUser(email: string) {
    const found = await this.usersRepository.findCredentials(email);
    return found && { id: found.user.id, email: found.user.email, passwordHash: found.passwordHash };
  }

  send(link: PasswordResetLink) {
    this.outbox.push('reset', link.email, link.url);
  }

  updatePassword(userId: string, passwordHash: string) {
    return this.usersRepository.updatePasswordHash(userId, passwordHash);
  }
}

@Injectable()
export class MagicLinkMailer extends MagicLinkHandler {
  constructor(
    private readonly usersRepository: UsersRepository,
    private readonly outbox: LinkOutbox,
    registry: AuthenticationRegistry,
  ) {
    super();
    registry.registerHandler('magicLink', this);
  }

  send(link: MagicLink) {
    this.outbox.push('magic', link.email, link.url);
  }

  // Runs when the link is used, which proves the address.
  async resolveUser(email: string) {
    const user = await this.usersRepository.findByEmail(email);
    if (!user) {
      return this.usersRepository.create(email, null, true); // passwordless sign-up; return null to refuse
    }
    if (!user.emailVerified) {
      // Whoever chose that password may not own the address.
      throw new ForbiddenException('Sign in with your password, or reset it');
    }
    return user;
  }
}

import { BadRequestException, Body, ConflictException, Controller, HttpCode, Post, UnauthorizedException } from '@nestjs/common';
import {
  CurrentUser,
  EmailVerificationService,
  MagicLinkService,
  PasswordResetService,
  Public,
} from '@nestjs/authentication';
import { Throttle, minutes } from '@nestjs/throttler';
import { EmailDto, ResetPasswordDto } from './auth.dto.js';
import type { User } from './user.js';

@Controller('auth/email')
export class EmailVerificationController {
  constructor(private readonly emailVerificationService: EmailVerificationService) {}

  // The page the link opens POSTs the token: scanners follow links with GET and would spend it.
  @Public()
  @Post('verify')
  @HttpCode(200)
  async verify(@Body('token') token: string) {
    const verified = await this.emailVerificationService.verify(token);
    if (!verified) {
      throw new BadRequestException('Invalid or expired link');
    }
    return { email: verified.email, emailVerified: true };
  }

  @Post('verification')
  @HttpCode(202)
  async resend(@CurrentUser() user: User) {
    if (user.emailVerified) {
      throw new ConflictException('Email address already verified');
    }
    await this.emailVerificationService.send(user);
  }
}

@Public()
@Controller('auth/password')
export class PasswordResetController {
  constructor(private readonly passwordResetService: PasswordResetService) {}

  // Same answer, as fast, whether or not the address has an account: do not await request().
  @Throttle({ default: { limit: 3, ttl: minutes(15) } })
  @Post('forgot')
  @HttpCode(202)
  forgot(@Body() body: EmailDto) {
    this.passwordResetService.request(body.email);
  }

  @Post('reset')
  @HttpCode(200)
  async reset(@Body() body: ResetPasswordDto) {
    const result = await this.passwordResetService.reset(body.token, body.password, { signIn: true });
    if (!result) {
      throw new BadRequestException('Invalid or expired link');
    }
    return { mfaRequired: result.signedIn?.session.mfa === 'pending' };
  }
}

@Public()
@Controller('auth/magic-link')
export class MagicLinkController {
  constructor(private readonly magicLinkService: MagicLinkService) {}

  @Throttle({ default: { limit: 3, ttl: minutes(15) } })
  @Post()
  @HttpCode(202)
  async request(@Body() body: EmailDto, @Body('redirectTo') redirectTo?: string) {
    await this.magicLinkService.create(body.email, { redirectTo });
  }

  @Post('consume')
  @HttpCode(200)
  async consume(@Body('token') token: string) {
    // A link opened in another browser throws MagicLinkError: a 401 `not_this_browser`.
    const result = await this.magicLinkService.consume(token);
    if (!result) {
      throw new UnauthorizedException('Invalid or expired link');
    }
    return { redirectTo: result.redirectTo ?? '/', mfaRequired: result.session.mfa === 'pending' };
  }
}

{ "message": "Open the link in the browser you requested it from, or request a new one here", "error": "not_this_browser", "statusCode": 401 }

import { Controller, Get } from '@nestjs/common';
import { Authenticate, CurrentUser, Public } from '@nestjs/authentication';
import type { User } from './user.js';

@Controller()
export class MeController {
  @Get('me')
  me(@CurrentUser() user: User) {
    return user;
  }

  // `@CurrentUser('key')` injects one property.
  @Get('me/email')
  email(@CurrentUser('email') email: string) {
    return { email };
  }

  // Only verified addresses: anyone else signed in gets 403 `email_unverified`.
  @Authenticate({ verifiedEmail: true })
  @Get('me/orders')
  orders() {
    return [];
  }

  // Anonymous callers are let through with a null user; bad credentials still get 401.
  @Authenticate({ optional: true })
  @Get('hello')
  hello(@CurrentUser() user: User | null) {
    return { hello: user?.email ?? 'guest' };
  }

  @Public()
  @Get('health')
  health() {
    return { status: 'ok' };
  }
}

{ "message": "Email address not verified", "error": "email_unverified", "statusCode": 403 }

import { Body, Controller, HttpCode, Post, UnauthorizedException } from '@nestjs/common';
import { Public, TokenService } from '@nestjs/authentication';
import { Throttle, minutes } from '@nestjs/throttler';
import { TokenRequestDto } from './auth.dto.js';
import { CredentialsService } from './credentials.service.js';

@Public()
@Controller('auth/token')
export class TokensController {
  constructor(
    private readonly credentialsService: CredentialsService,
    private readonly tokenService: TokenService,
  ) {}

  @Throttle({ default: { limit: 5, ttl: minutes(15) } })
  @Post()
  @HttpCode(200)
  async issue(@Body() body: TokenRequestDto) {
    const user = await this.credentialsService.verify(body.email, body.password);
    if (!user) {
      throw new UnauthorizedException('Invalid email or password');
    }
    return this.tokenService.issue(user.id, {
      method: 'password',
      claims: { amr: ['pwd'] }, // copied into every refreshed access token
      secondFactor: { code: body.code, recoveryCode: body.recoveryCode }, // checked only with an authenticator
    });
  }

  // Each refresh token works once; an unknown, expired or reused one gets a 401.
  @Post('refresh')
  @HttpCode(200)
  refresh(@Body('refreshToken') refreshToken: string) {
    return this.tokenService.refresh(refreshToken);
  }

  // Ends the token's family. Unknown tokens get the same answer, as in RFC 7009.
  @Post('revoke')
  @HttpCode(204)
  async revoke(@Body('refreshToken') refreshToken: string) {
    await this.tokenService.revoke(refreshToken);
  }
}

import { Controller, Delete, Get, HttpCode, NotFoundException, Param, Post, UnauthorizedException } from '@nestjs/common';
import { CurrentSession, CurrentUser, Public, SessionService, SignInService, type SessionRecord } from '@nestjs/authentication';

@Controller('auth')
export class SessionsController {
  constructor(
    private readonly sessionService: SessionService,
    private readonly signInService: SignInService,
  ) {}

  @Get('sessions')
  async list(@CurrentUser('id') userId: string, @CurrentSession() current: SessionRecord) {
    const sessions = await this.sessionService.list(userId);
    return sessions.map(({ id, createdAt, lastActiveAt, metadata }) => ({
      id,
      createdAt,
      lastActiveAt,
      userAgent: metadata?.userAgent ?? null,
      current: id === current.id,
    }));
  }

  // revoke() only ends a session of this user: another user's id is a 404.
  @Delete('sessions/:id')
  @HttpCode(204)
  async revoke(@CurrentUser('id') userId: string, @Param('id') id: string) {
    if (!(await this.sessionService.revoke(id, { userId }))) {
      throw new NotFoundException();
    }
  }

  // Public so that a session still waiting for its second factor can sign out too.
  @Public()
  @Post('sign-out')
  @HttpCode(204)
  async signOut() {
    if (!(await this.signInService.signOut())) {
      throw new UnauthorizedException(); // no session cookie, e.g. a bearer token
    }
  }

  @Post('sign-out-everywhere')
  @HttpCode(204)
  async signOutEverywhere(@CurrentUser('id') userId: string) {
    await this.signInService.signOutEverywhere(userId);
  }
}

[
  { "id": "<session id, 43 characters>", "createdAt": "2026-10-02T16:23:36.322Z", "lastActiveAt": "2026-10-02T16:23:36.322Z", "userAgent": null, "current": true },
  { "id": "<another session id>", "createdAt": "2026-10-02T16:23:36.330Z", "lastActiveAt": "2026-10-02T16:23:36.330Z", "userAgent": "phone", "current": false }
]

import { Body, Controller, HttpCode, Post, UnauthorizedException } from '@nestjs/common';
import { Authenticate, CurrentUser, MfaService, Public, SignInService } from '@nestjs/authentication';
import type { User } from './user.js';

@Controller('auth/mfa')
export class MfaController {
  constructor(
    private readonly mfaService: MfaService,
    private readonly signInService: SignInService,
  ) {}

  // Returns the otpauth:// URI for a QR code, and the secret for people who type it in.
  @Post('enroll')
  enroll(@CurrentUser() user: User) {
    return this.mfaService.enroll(user.id, user.email);
  }

  // The first code proves the authenticator works; recovery codes are shown once.
  @Post('confirm')
  @HttpCode(200)
  async confirm(@CurrentUser('id') userId: string, @Body('code') code: string) {
    if (!(await this.signInService.confirmMfa(userId, code))) {
      throw new UnauthorizedException('Invalid code');
    }
    return { recoveryCodes: await this.mfaService.generateRecoveryCodes(userId) };
  }

  // Second step of signing in. A pending session counts as signed in nowhere, so the route is public.
  @Public()
  @Post('verify')
  @HttpCode(200)
  async verify(@Body('code') code?: string, @Body('recoveryCode') recoveryCode?: string) {
    const issued = await this.signInService.completeMfa({ code, recoveryCode });
    if (!issued) {
      throw new UnauthorizedException('Invalid code');
    }
    return { mfa: issued.session.mfa };
  }

  // Step-up authentication: a verified second factor is required to get here.
  @Authenticate({ mfa: true })
  @Post('sensitive')
  @HttpCode(200)
  sensitive() {
    return { ok: true };
  }
}

{ "message": "Second factor required", "error": "mfa_required", "statusCode": 401 }

import { Controller, ForbiddenException, Get, Injectable, Param, Query, Redirect, ConflictException } from '@nestjs/common';
import {
  AuthenticationRegistry,
  OidcAccountResolver,
  OidcService,
  Public,
  type OAuthTokens,
  type OidcProfile,
  type OidcResolveContext,
} from '@nestjs/authentication';
import { UsersRepository } from './users.repository.js';

@Injectable()
export class AccountLinker extends OidcAccountResolver {
  /** `provider:subject` -> user id. */
  private readonly identities = new Map<string, string>();

  constructor(
    private readonly usersRepository: UsersRepository,
    registry: AuthenticationRegistry,
  ) {
    super();
    registry.registerHandler('oidc', this);
  }

  async resolveUser(profile: OidcProfile, _tokens: OAuthTokens, { linkTo }: OidcResolveContext) {
    const key = `${profile.provider}:${profile.subject}`;
    const linkedId = this.identities.get(key);

    if (linkTo) {
      // "Connect Google" from the account page.
      if (linkedId && linkedId !== linkTo.id) throw new ConflictException('Linked to another user');
      this.identities.set(key, linkTo.id);
      return this.usersRepository.findById(linkTo.id);
    }
    if (linkedId) return this.usersRepository.findById(linkedId);

    // First visit: trust only an address the provider verified.
    if (!profile.email || !profile.emailVerified) return null; // 403

    const existing = await this.usersRepository.findByEmail(profile.email);
    if (!existing) {
      const user = await this.usersRepository.create(profile.email, null, true);
      this.identities.set(key, user.id);
      return user;
    }
    // Link by email only if the local account's owner proved the address too (pre-hijacking).
    if (!existing.emailVerified) {
      throw new ForbiddenException('Sign in with your password, then connect the provider from your account');
    }
    this.identities.set(key, existing.id);
    return existing;
  }
}

@Public()
@Controller('auth/oidc')
export class OidcController {
  constructor(private readonly oidcService: OidcService) {}

  @Get(':provider/login')
  @Redirect()
  login(@Param('provider') provider: string, @Query('redirectTo') redirectTo?: string, @Query('link') link?: string) {
    return this.oidcService.start(provider, { redirectTo, link: link === 'true' });
  }

  @Get(':provider/callback')
  @Redirect()
  callback(@Param('provider') provider: string, @Query() query: Record<string, string>) {
    return this.oidcService.finish(provider, query);
  }
}

import { Injectable } from '@nestjs/common';
import { ApiKeyProvider, AuthenticationRegistry } from '@nestjs/authentication';
import type { User } from './user.js';
import { UsersRepository } from './users.repository.js';

export interface StoredApiKey {
  id: string;
  userId: string;
  hash: string;
  createdAt: Date;
  expiresAt: Date;
}

@Injectable()
export class ApiKeyAuth extends ApiKeyProvider<User> {
  /** In-memory stand-in for an `api_keys` table: it keeps the SHA-256 of each key, never the key. */
  readonly keys = new Map<string, StoredApiKey>();

  constructor(
    private readonly usersRepository: UsersRepository,
    registry: AuthenticationRegistry,
  ) {
    // Keys look like shelf_<id>_<secret>. The prefix tells secret scanners what they found.
    super({ prefix: 'shelf', realm: 'bookshelf' });
    registry.registerProvider(this, { order: 2 });
  }

  // Called with the id part of a key; the provider then checks the hash and the expiry.
  async findKey(id: string) {
    const key = this.keys.get(id);
    const user = key && (await this.usersRepository.findById(key.userId));
    return user ? { hash: key.hash, user, expiresAt: key.expiresAt } : null;
  }
}

import { Controller, Delete, Get, HttpCode, NotFoundException, Param, Post } from '@nestjs/common';
import { Authenticate, CurrentUser } from '@nestjs/authentication';
import { ApiKeyAuth } from './api-key-auth.provider.js';
import { SessionAuth } from './session-auth.provider.js';

const ONE_YEAR = 365 * 24 * 60 * 60 * 1000;

// Managed from the web app with a session: a key can neither create nor revoke keys.
@Authenticate({ providers: [SessionAuth] })
@Controller('auth/api-keys')
export class ApiKeysController {
  constructor(private readonly apiKeyAuth: ApiKeyAuth) {}

  // The only response that contains the key: the table keeps its hash.
  @Post()
  create(@CurrentUser('id') userId: string) {
    const { key, id, hash } = this.apiKeyAuth.generate();
    const createdAt = new Date();
    const expiresAt = new Date(createdAt.getTime() + ONE_YEAR);
    this.apiKeyAuth.keys.set(id, { id, userId, hash, createdAt, expiresAt });
    return { id, key, createdAt, expiresAt };
  }

  @Get()
  list(@CurrentUser('id') userId: string) {
    return [...this.apiKeyAuth.keys.values()]
      .filter((k) => k.userId === userId)
      .map(({ id, createdAt, expiresAt }) => ({ id, createdAt, expiresAt }));
  }

  @Delete(':id')
  @HttpCode(204)
  revoke(@CurrentUser('id') userId: string, @Param('id') id: string) {
    const key = this.apiKeyAuth.keys.get(id);
    if (!key || key.userId !== userId) {
      throw new NotFoundException();
    }
    this.apiKeyAuth.keys.delete(id);
  }
}

import { ExecutionContext, Injectable } from '@nestjs/common';
import { GqlContextType, GqlExecutionContext } from '@nestjs/graphql';
import { ThrottlerGuard } from '@nestjs/throttler';

/** Per IP everywhere; per (email, IP) where the request body names an account. */
@Injectable()
export class AuthThrottlerGuard extends ThrottlerGuard {
  protected async getTracker(req: Record<string, any>): Promise<string> {
    const ip = await super.getTracker(req);
    const email = typeof req.body?.email === 'string' ? req.body.email.trim().normalize('NFC').toLowerCase() : '';
    return email ? `${email}|${ip}` : ip;
  }

  // GraphQL operations carry the HTTP request on the GraphQL context.
  getRequestResponse(context: ExecutionContext) {
    if (context.getType<GqlContextType>() === 'graphql') {
      const { req, res } = GqlExecutionContext.create(context).getContext();
      return { req, res };
    }
    return super.getRequestResponse(context);
  }
}

@Throttle({ default: { limit: 5, ttl: minutes(15) } })
@Post('sign-in')

import { Module } from '@nestjs/common';
import { ApolloDriver, type ApolloDriverConfig } from '@nestjs/apollo';
import { Field, GraphQLModule, ObjectType, Query, Resolver } from '@nestjs/graphql';
import { SubscribeMessage, WebSocketGateway, type OnGatewayConnection } from '@nestjs/websockets';
import { Authenticate, AuthenticationContext, CurrentUser, Public, WsAuthenticator } from '@nestjs/authentication';
import type { Socket } from 'socket.io';
import { AuthenticationDemoModule } from './authentication-demo.module.js';
import type { User } from './user.js';

@ObjectType()
export class Profile {
  @Field() id: string;
  @Field() email: string;
}

@Resolver(() => Profile)
export class ProfileResolver {
  constructor(private readonly context: AuthenticationContext) {}

  // The global guard protects resolvers too; @CurrentUser() reads the user from the GraphQL context.
  @Query(() => Profile)
  whoAmI(@CurrentUser() user: User) {
    return user;
  }

  @Public()
  @Query(() => String)
  ping() {
    return 'pong';
  }

  @Authenticate({ optional: true })
  @Query(() => String)
  viaContext() {
    return this.context.user ? 'signed-in' : 'guest';
  }
}

@WebSocketGateway()
export class ChatGateway implements OnGatewayConnection {
  constructor(private readonly wsAuthenticator: WsAuthenticator) {}

  // Nest runs no guards on handleConnection(): authenticate the handshake explicitly.
  async handleConnection(client: Socket) {
    await this.wsAuthenticator.authenticateConnection(client);
  }

  // The global guard authenticates every message too.
  @SubscribeMessage('whoami')
  whoami(@CurrentUser('email') email: string) {
    return { email };
  }
}

@Module({
  imports: [
    AuthenticationDemoModule,
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
      autoSchemaFile: true,
      subscriptions: { 'graphql-ws': true },
      // Over graphql-ws there is no request per operation: the upgrade request stands in for it.
      context: ({ req, res, extra }: { req?: any; res?: any; extra?: any }) => ({ req: req ?? extra?.request, res }),
      fieldResolverEnhancers: ['guards', 'interceptors'],
    }),
  ],
  providers: [ProfileResolver, ChatGateway],
})
export class RealtimeModule {}

import { randomBytes } from 'node:crypto';
import type { INestApplication } from '@nestjs/common';
import { Test } from '@nestjs/testing';
import { PasswordHasher } from '@nestjs/authentication';
import request from 'supertest';
import { AuthenticationDemoModule } from '../src/authentication/authentication-demo.module.js';
import { LinkOutbox } from '../src/authentication/link-outbox.js';

describe('Authentication (e2e)', () => {
  let app: INestApplication;
  let outbox: LinkOutbox;
  // Generated per run: no credential-like literal in the repository.
  const ada = { email: 'ada@example.com', password: randomBytes(12).toString('hex') };

  beforeAll(async () => {
    // In an application these come from the environment through ConfigService.
    process.env.JWT_SECRET = randomBytes(32).toString('hex');
    process.env.TOTP_ENCRYPTION_KEY = randomBytes(32).toString('hex');
    process.env.APP_URL = 'http://localhost:3000';
    process.env.GOOGLE_CLIENT_ID = 'test-client.apps.example';
    process.env.GOOGLE_CLIENT_SECRET = randomBytes(16).toString('hex');

    const moduleRef = await Test.createTestingModule({ imports: [AuthenticationDemoModule] })
      .overrideProvider(PasswordHasher)
      .useValue(new PasswordHasher({ logN: 10 })) // scrypt is slow on purpose: use a cheap instance in tests
      .compile();
    app = moduleRef.createNestApplication();
    await app.init();
    outbox = app.get(LinkOutbox);
  });

  afterAll(() => app.close());

  it('signs up, verifies the address, then reads the profile with the session cookie', async () => {
    const res = await request(app.getHttpServer()).post('/auth/sign-up').send(ada).expect(201);
    const cookie = (res.headers['set-cookie'] as unknown as string[])[0].split(';')[0];

    // The link the user would have received by email.
    const token = new URL(outbox.last('verify', ada.email)!.url).searchParams.get('token');
    await request(app.getHttpServer()).post('/auth/email/verify').send({ token }).expect(200);

    await request(app.getHttpServer())
      .get('/me')
      .set('Cookie', cookie)
      .expect(200, { id: res.body.id, email: ada.email, emailVerified: true, roles: ['reader'] });
  });

  it('issues bearer tokens to the mobile app', async () => {
    const res = await request(app.getHttpServer()).post('/auth/token').send(ada).expect(200);

    await request(app.getHttpServer())
      .get('/me/orders')
      .set('Authorization', `Bearer ${res.body.accessToken}`)
      .expect(200, []);
  });

  it('rejects anonymous requests and wrong passwords', async () => {
    await request(app.getHttpServer()).get('/me').expect(401);
    await request(app.getHttpServer())
      .post('/auth/sign-in')
      .send({ ...ada, password: randomBytes(12).toString('hex') }) // any other password
      .expect(401);
  });
});