@codecanva/nest-auth 0.1.0 → 0.2.0

package/INSTALLATION.md

@@ -0,0 +1,682 @@
+# `@codecanva/nest-auth` Installation Guide
+
+End-to-end guide for wiring `@codecanva/nest-auth` into a NestJS + Mongoose project. Includes every file we created plus the dependency, env, and bootstrap changes.
+
+> **Shortcut:** `npx @codecanva/nest-auth init` scaffolds everything below
+> (files, env vars, AppModule + `main.ts` wiring, dependencies) automatically.
+> Use `--dry-run` to preview, `--store memory` for a no-DB trial. This document
+> is the manual reference for what that command generates and why.
+
+---
+
+## 1. Install dependencies
+
+`@codecanva/nest-auth` requires `class-validator@^0.14.x`. If you have `0.15.x` installed, downgrade it here.
+
+```bash
+npm install \
+  @codecanva/nest-auth \
+  @nestjs/jwt @nestjs/passport \
+  passport passport-jwt \
+  bcrypt \
+  class-validator@^0.14.1
+
+npm install -D @types/passport-jwt @types/bcrypt
+```
+
+---
+
+## 2. Environment variables
+
+Add these to your `.env` (use strong random values in real environments):
+
+```dotenv
+JWT_ACCESS_SECRET=change-me-access-secret-min-32-chars-long-please
+JWT_REFRESH_SECRET=change-me-refresh-secret-min-32-chars-long-different
+TOKEN_HASH_PEPPER=change-me-pepper
+```
+
+Update `src/config/env.validation.ts` so the app fails fast if they're missing:
+
+```ts
+// src/config/env.validation.ts
+const REQUIRED_KEYS = [
+  'MONGODB_URI',
+  'JWT_ACCESS_SECRET',
+  'JWT_REFRESH_SECRET',
+] as const;
+
+export function validateEnv(
+  config: Record<string, unknown>,
+): Record<string, unknown> {
+  const missing = REQUIRED_KEYS.filter((key) => !config[key]);
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required environment variables: ${missing.join(', ')}. ` +
+        `Check your .env file.`,
+    );
+  }
+
+  const uri = String(config.MONGODB_URI);
+  if (!/^mongodb(\+srv)?:\/\//.test(uri)) {
+    throw new Error(
+      `MONGODB_URI must start with "mongodb://" or "mongodb+srv://" (got: "${uri}")`,
+    );
+  }
+
+  return config;
+}
+```
+
+---
+
+## 3. User module
+
+### 3.1 User schema
+
+```ts
+// src/user/schemas/user.schema.ts
+import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
+import { HydratedDocument } from 'mongoose';
+
+export type UserDocument = HydratedDocument<User>;
+
+@Schema({ timestamps: true })
+export class User {
+  @Prop({ required: true, unique: true, lowercase: true, trim: true, index: true })
+  email: string;
+
+  @Prop({ required: true })
+  passwordHash: string;
+
+  @Prop({ type: [String], default: [] })
+  roles: string[];
+}
+
+export const UserSchema = SchemaFactory.createForClass(User);
+```
+
+### 3.2 DTO
+
+```ts
+// src/user/dto/create-user.dto.ts
+import { IsEmail, IsString, MinLength } from 'class-validator';
+
+export class CreateUserDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @MinLength(8)
+  password: string;
+}
+```
+
+`src/user/dto/update-user.dto.ts` stays as-is (PartialType).
+
+### 3.3 Service
+
+```ts
+// src/user/user.service.ts
+import {
+  ConflictException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import { InjectModel } from '@nestjs/mongoose';
+import { Model } from 'mongoose';
+import * as bcrypt from 'bcrypt';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+import { User, UserDocument } from './schemas/user.schema';
+
+const BCRYPT_ROUNDS = 12;
+
+@Injectable()
+export class UserService {
+  constructor(
+    @InjectModel(User.name) private readonly userModel: Model<UserDocument>,
+  ) {}
+
+  async create(dto: CreateUserDto): Promise<UserDocument> {
+    const existing = await this.userModel.findOne({ email: dto.email }).lean();
+    if (existing) {
+      throw new ConflictException('Email already registered');
+    }
+    const passwordHash = await bcrypt.hash(dto.password, BCRYPT_ROUNDS);
+    return this.userModel.create({ email: dto.email, passwordHash });
+  }
+
+  findAll(): Promise<UserDocument[]> {
+    return this.userModel.find().exec();
+  }
+
+  findByEmail(email: string): Promise<UserDocument | null> {
+    return this.userModel.findOne({ email: email.toLowerCase() }).exec();
+  }
+
+  findById(id: string): Promise<UserDocument | null> {
+    return this.userModel.findById(id).exec();
+  }
+
+  async update(id: string, dto: UpdateUserDto): Promise<UserDocument> {
+    const updated = await this.userModel
+      .findByIdAndUpdate(id, dto, { new: true })
+      .exec();
+    if (!updated) throw new NotFoundException('User not found');
+    return updated;
+  }
+
+  async remove(id: string): Promise<void> {
+    const result = await this.userModel.findByIdAndDelete(id).exec();
+    if (!result) throw new NotFoundException('User not found');
+  }
+}
+```
+
+### 3.4 UserValidator (implements `@codecanva/nest-auth`'s contract)
+
+```ts
+// src/user/user.validator.ts
+import { Injectable } from '@nestjs/common';
+import { AuthUser, UserValidator } from '@codecanva/nest-auth';
+import * as bcrypt from 'bcrypt';
+import { UserService } from './user.service';
+import { UserDocument } from './schemas/user.schema';
+
+@Injectable()
+export class MyUserValidator implements UserValidator {
+  constructor(private readonly users: UserService) {}
+
+  async validateCredentials(
+    email: string,
+    password: string,
+  ): Promise<AuthUser | null> {
+    const user = await this.users.findByEmail(email);
+    if (!user) return null;
+    const ok = await bcrypt.compare(password, user.passwordHash);
+    if (!ok) return null;
+    return this.toAuthUser(user);
+  }
+
+  async findById(userId: string | number): Promise<AuthUser | null> {
+    const user = await this.users.findById(String(userId));
+    return user ? this.toAuthUser(user) : null;
+  }
+
+  private toAuthUser(user: UserDocument): AuthUser {
+    return {
+      id: user._id.toString(),
+      email: user.email,
+      roles: user.roles,
+    };
+  }
+}
+```
+
+### 3.5 Controller (with `@Public() POST /user/register`)
+
+```ts
+// src/user/user.controller.ts
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Param,
+  Patch,
+  Post,
+} from '@nestjs/common';
+import { Public } from '@codecanva/nest-auth';
+import { UserService } from './user.service';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+
+@Controller('user')
+export class UserController {
+  constructor(private readonly userService: UserService) {}
+
+  @Public()
+  @Post('register')
+  async register(@Body() dto: CreateUserDto) {
+    const user = await this.userService.create(dto);
+    return { id: user._id.toString(), email: user.email, roles: user.roles };
+  }
+
+  @Get()
+  findAll() {
+    return this.userService.findAll();
+  }
+
+  @Get(':id')
+  findOne(@Param('id') id: string) {
+    return this.userService.findById(id);
+  }
+
+  @Patch(':id')
+  update(@Param('id') id: string, @Body() dto: UpdateUserDto) {
+    return this.userService.update(id, dto);
+  }
+
+  @Delete(':id')
+  remove(@Param('id') id: string) {
+    return this.userService.remove(id);
+  }
+}
+```
+
+### 3.6 Module (registers schema, exports validator)
+
+```ts
+// src/user/user.module.ts
+import { Module } from '@nestjs/common';
+import { MongooseModule } from '@nestjs/mongoose';
+import { UserService } from './user.service';
+import { UserController } from './user.controller';
+import { MyUserValidator } from './user.validator';
+import { User, UserSchema } from './schemas/user.schema';
+
+@Module({
+  imports: [
+    MongooseModule.forFeature([{ name: User.name, schema: UserSchema }]),
+  ],
+  controllers: [UserController],
+  providers: [UserService, MyUserValidator],
+  exports: [UserService, MyUserValidator],
+})
+export class UserModule {}
+```
+
+---
+
+## 4. Auth module (refresh-token persistence + controller)
+
+### 4.1 Refresh-token schema
+
+The `_id` is the token id chosen by the library (not Mongo's auto-id). `expiresAt` has a TTL index so expired sessions self-clean.
+
+```ts
+// src/schemas/refresh-token.schema.ts
+import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
+import { HydratedDocument } from 'mongoose';
+
+export type RefreshTokenDocument = HydratedDocument<RefreshToken>;
+
+@Schema({ collection: 'refresh_tokens', timestamps: { createdAt: true, updatedAt: false } })
+export class RefreshToken {
+  @Prop({ type: String, required: true })
+  _id: string;
+
+  @Prop({ type: String, required: true, index: true })
+  userId: string;
+
+  @Prop({ type: String, required: true, index: true })
+  tokenHash: string;
+
+  @Prop({ type: Object })
+  metadata?: Record<string, unknown>;
+
+  @Prop({ type: Date, required: true, index: { expires: 0 } })
+  expiresAt: Date;
+
+  @Prop({ type: Date, default: null })
+  revokedAt: Date | null;
+}
+
+export const RefreshTokenSchema = SchemaFactory.createForClass(RefreshToken);
+```
+
+### 4.2 Store (implements `RefreshTokenStore`)
+
+`consume` MUST be atomic — a single `findOneAndUpdate` filters on `revokedAt: null` + `tokenHash`, sets `revokedAt`, and returns the pre-update doc.
+
+```ts
+// src/auth/refresh-token.store.ts
+import { Injectable } from '@nestjs/common';
+import { InjectModel } from '@nestjs/mongoose';
+import { Model } from 'mongoose';
+import {
+  CreateRefreshTokenInput,
+  RefreshTokenStore,
+  StoredRefreshToken,
+} from '@codecanva/nest-auth';
+import {
+  RefreshToken,
+  RefreshTokenDocument,
+} from '../schemas/refresh-token.schema';
+
+@Injectable()
+export class MyRefreshTokenStore implements RefreshTokenStore {
+  constructor(
+    @InjectModel(RefreshToken.name)
+    private readonly model: Model<RefreshTokenDocument>,
+  ) {}
+
+  async create(input: CreateRefreshTokenInput): Promise<StoredRefreshToken> {
+    const doc = await this.model.create({
+      _id: input.id,
+      userId: String(input.userId),
+      tokenHash: input.tokenHash,
+      expiresAt: input.expiresAt,
+      metadata: input.metadata,
+      revokedAt: null,
+    });
+    return this.toStored(doc.toObject());
+  }
+
+  async findById(id: string): Promise<StoredRefreshToken | null> {
+    const doc = await this.model.findById(id).lean();
+    return doc ? this.toStored(doc) : null;
+  }
+
+  async consume(
+    id: string,
+    expectedHash: string,
+  ): Promise<StoredRefreshToken | null> {
+    const doc = await this.model
+      .findOneAndUpdate(
+        { _id: id, tokenHash: expectedHash, revokedAt: null },
+        { $set: { revokedAt: new Date() } },
+        { new: false, lean: true },
+      )
+      .exec();
+    return doc ? this.toStored(doc) : null;
+  }
+
+  async revokeById(id: string): Promise<void> {
+    await this.model
+      .updateOne(
+        { _id: id, revokedAt: null },
+        { $set: { revokedAt: new Date() } },
+      )
+      .exec();
+  }
+
+  async revokeAllForUser(userId: string | number): Promise<void> {
+    await this.model
+      .updateMany(
+        { userId: String(userId), revokedAt: null },
+        { $set: { revokedAt: new Date() } },
+      )
+      .exec();
+  }
+
+  private toStored(doc: any): StoredRefreshToken {
+    return {
+      id: String(doc._id),
+      userId: doc.userId,
+      tokenHash: doc.tokenHash,
+      metadata: doc.metadata,
+      expiresAt: doc.expiresAt,
+      revokedAt: doc.revokedAt ?? null,
+      createdAt: doc.createdAt,
+    };
+  }
+}
+```
+
+### 4.3 Auth persistence module
+
+```ts
+// src/auth/auth-persistence.module.ts
+import { Module } from '@nestjs/common';
+import { MongooseModule } from '@nestjs/mongoose';
+import { MyRefreshTokenStore } from './refresh-token.store';
+import {
+  RefreshToken,
+  RefreshTokenSchema,
+} from '../schemas/refresh-token.schema';
+
+@Module({
+  imports: [
+    MongooseModule.forFeature([
+      { name: RefreshToken.name, schema: RefreshTokenSchema },
+    ]),
+  ],
+  providers: [MyRefreshTokenStore],
+  exports: [MyRefreshTokenStore],
+})
+export class AuthPersistenceModule {}
+```
+
+### 4.4 Auth controller (login / refresh / logout / me)
+
+The handlers return the `AuthService` calls directly — no try/catch needed.
+`AuthModule` registers a global `AuthExceptionFilter` that maps the library's
+domain errors to HTTP responses (`InvalidCredentialsError` → `401 Invalid
+credentials`, `InvalidRefreshTokenError` / `RefreshTokenExpiredError` /
+`RefreshTokenReuseDetectedError` → `401`, etc.). Without it, those errors are
+plain `Error`s and Nest would render them as `500 Internal Server Error`.
+
+```ts
+// src/auth/auth.controller.ts
+import { Body, Controller, Get, HttpCode, Post } from '@nestjs/common';
+import {
+  AuthService,
+  AuthUser,
+  CurrentUser,
+  LoginDto,
+  Public,
+  RefreshTokenDto,
+} from '@codecanva/nest-auth';
+
+@Controller('auth')
+export class AuthController {
+  constructor(private readonly auth: AuthService) {}
+
+  @Public()
+  @Post('login')
+  login(@Body() dto: LoginDto) {
+    return this.auth.login(dto.email, dto.password);
+  }
+
+  @Public()
+  @Post('refresh')
+  refresh(@Body() dto: RefreshTokenDto) {
+    return this.auth.refresh(dto.refreshToken);
+  }
+
+  @Post('logout')
+  @HttpCode(204)
+  logout(@Body() dto: RefreshTokenDto) {
+    return this.auth.logout(dto.refreshToken);
+  }
+
+  @Get('me')
+  me(@CurrentUser() user: AuthUser) {
+    return user;
+  }
+}
+```
+
+---
+
+## 5. Wire everything in `AppModule`
+
+`useExisting` points `AuthModule` at the providers already created by `UserModule` and `AuthPersistenceModule`. Registering `JwtAuthGuard` as `APP_GUARD` makes every route require auth unless marked `@Public()`.
+
+```ts
+// src/app.module.ts
+import { Module } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { MongooseModule } from '@nestjs/mongoose';
+import { AuthModule, JwtAuthGuard } from '@codecanva/nest-auth';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+import { UserModule } from '@/user/user.module';
+import { MyUserValidator } from '@/user/user.validator';
+import { AuthPersistenceModule } from '@/auth/auth-persistence.module';
+import { MyRefreshTokenStore } from '@/auth/refresh-token.store';
+import { AuthController } from '@/auth/auth.controller';
+import { validateEnv } from '@/config/env.validation';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true, validate: validateEnv }),
+    MongooseModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        uri: config.getOrThrow<string>('MONGODB_URI'),
+      }),
+    }),
+    UserModule,
+    AuthPersistenceModule,
+    AuthModule.forRootAsync({
+      imports: [ConfigModule, UserModule, AuthPersistenceModule],
+      useFactory: (cfg: ConfigService) => ({
+        accessSecret: cfg.getOrThrow('JWT_ACCESS_SECRET'),
+        refreshSecret: cfg.getOrThrow('JWT_REFRESH_SECRET'),
+        accessTtl: '15m',
+        refreshTtl: '30d',
+        tokenHashPepper: cfg.get('TOKEN_HASH_PEPPER'),
+        issuer: 'vehcall',
+      }),
+      inject: [ConfigService],
+      store: { useExisting: MyRefreshTokenStore },
+      validator: { useExisting: MyUserValidator },
+    }),
+  ],
+  controllers: [AppController, AuthController],
+  providers: [
+    AppService,
+    { provide: APP_GUARD, useClass: JwtAuthGuard },
+  ],
+})
+export class AppModule {}
+```
+
+Mark public routes on existing controllers (e.g. the root `/` health endpoint):
+
+```ts
+// src/app.controller.ts
+import { Controller, Get } from '@nestjs/common';
+import { Public } from '@codecanva/nest-auth';
+import { AppService } from './app.service';
+
+@Controller()
+export class AppController {
+  constructor(private readonly appService: AppService) {}
+
+  @Public()
+  @Get()
+  getHello(): string {
+    return this.appService.getHello();
+  }
+}
+```
+
+---
+
+## 6. Enable validation globally in `main.ts`
+
+```ts
+// src/main.ts
+import { NestFactory } from '@nestjs/core';
+import { ValidationPipe } from '@nestjs/common';
+import { AppModule } from '@/app.module';
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.useGlobalPipes(
+    new ValidationPipe({ whitelist: true, transform: true, forbidNonWhitelisted: true }),
+  );
+
+  const config = new DocumentBuilder()
+    .setTitle('Vehcall')
+    .setDescription('VehCall API')
+    .setVersion('1.0')
+    .build();
+  const documentFactory = () => SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup('api', app, documentFactory);
+
+  await app.listen(process.env.PORT ?? 3000);
+}
+bootstrap();
+```
+
+---
+
+## 7. File tree (final)
+
+```
+src/
+├── app.controller.ts          # marked @Public() on /
+├── app.module.ts              # wires AuthModule + APP_GUARD
+├── app.service.ts
+├── main.ts                    # global ValidationPipe
+├── auth/
+│   ├── auth-persistence.module.ts
+│   ├── auth.controller.ts     # /auth/login, /refresh, /logout, /me
+│   └── refresh-token.store.ts # MyRefreshTokenStore (atomic consume)
+├── schemas/
+│   └── refresh-token.schema.ts
+├── config/
+│   └── env.validation.ts      # requires JWT secrets
+└── user/
+    ├── dto/
+    │   ├── create-user.dto.ts # email + password validation
+    │   └── update-user.dto.ts
+    ├── schemas/
+    │   └── user.schema.ts
+    ├── user.controller.ts     # @Public() POST /user/register
+    ├── user.module.ts         # provides + exports MyUserValidator
+    ├── user.service.ts        # bcrypt + Mongoose CRUD
+    └── user.validator.ts      # implements UserValidator
+```
+
+---
+
+## 8. Smoke test
+
+```bash
+npm run start:dev
+```
+
+```bash
+# 1. Register
+curl -X POST localhost:3000/user/register \
+  -H 'content-type: application/json' \
+  -d '{"email":"a@b.com","password":"password123"}'
+
+# 2. Login → { accessToken, refreshToken, user }
+curl -X POST localhost:3000/auth/login \
+  -H 'content-type: application/json' \
+  -d '{"email":"a@b.com","password":"password123"}'
+
+# 2b. Wrong password → 401 { "message": "Invalid credentials", ... }
+curl -i -X POST localhost:3000/auth/login \
+  -H 'content-type: application/json' \
+  -d '{"email":"a@b.com","password":"nope"}'
+
+# 3. Authed request
+curl localhost:3000/auth/me -H "authorization: Bearer <ACCESS_TOKEN>"
+
+# 4. Refresh (old refreshToken is now revoked)
+curl -X POST localhost:3000/auth/refresh \
+  -H 'content-type: application/json' \
+  -d '{"refreshToken":"<REFRESH_TOKEN>"}'
+
+# 5. Replay the OLD refreshToken → 401 + every session for this user revoked
+curl -X POST localhost:3000/auth/refresh \
+  -H 'content-type: application/json' \
+  -d '{"refreshToken":"<OLD_REFRESH_TOKEN>"}'
+
+# 6. Logout
+curl -X POST localhost:3000/auth/logout \
+  -H "authorization: Bearer <ACCESS_TOKEN>" \
+  -H 'content-type: application/json' \
+  -d '{"refreshToken":"<REFRESH_TOKEN>"}'
+```
+
+---
+
+## 9. Security checklist
+
+- Rotate the placeholder JWT secrets and `TOKEN_HASH_PEPPER` before deploying.
+- Serve auth endpoints over HTTPS only.
+- Prefer storing the refresh token in an `httpOnly` cookie over returning it in JSON.
+- Keep `consume` atomic — any non-atomic refactor opens a session-split window under concurrent refreshes.
+- On replay detection the library calls `revokeAllForUser` — your store handles this correctly via `updateMany`.
+- Never commit real `.env` values to git; `.env.example` should be the only committed template.