@codecanva/nest-auth 0.1.0 → 0.2.0

package/README.md

@@ -1,164 +1,200 @@
-# @codecanva/nest-auth
-
-Reusable NestJS authentication module. JWT access + refresh-token rotation, multi-device sessions, replay detection, and pluggable persistence (no DB lock-in).
-
-## Features
-
-- Short-lived access JWT + long-lived refresh JWT
-- Refresh-token rotation on every refresh (with replay detection → `revokeAllForUser`)
-- Multi-device sessions (one row per session, hashed at rest)
-- Pluggable `RefreshTokenStore` and `UserValidator` — bring your own DB
-- `@CurrentUser()`, `@Public()` decorators
-- `JwtAuthGuard` (honours `@Public()`) and `RefreshAuthGuard`
-- Configurable issuer, audience, clock tolerance, optional hash pepper
-
-## Install
-
-```bash
-npm install @codecanva/nest-auth \
-  @nestjs/jwt @nestjs/passport passport passport-jwt \
-  class-validator class-transformer
-```
-
-## Usage
-
-### 1. Implement the two interfaces against your data layer
-
-```ts
-// users/user.validator.ts
-import { Injectable } from '@nestjs/common';
-import { AuthUser, UserValidator } from '@codecanva/nest-auth';
-
-@Injectable()
-export class MyUserValidator implements UserValidator {
-  async validateCredentials(email: string, password: string): Promise<AuthUser | null> {
-    // load user, bcrypt.compare, return { id, email, roles } or null
-  }
-  async findById(userId: string | number): Promise<AuthUser | null> {
-    // load by id, return AuthUser or null
-  }
-}
-```
-
-```ts
-// auth/refresh-token.store.ts — example with TypeORM
-import { Injectable } from '@nestjs/common';
-import {
-  CreateRefreshTokenInput,
-  RefreshTokenStore,
-  StoredRefreshToken,
-} from '@codecanva/nest-auth';
-
-@Injectable()
-export class MyRefreshTokenStore implements RefreshTokenStore {
-  // create / findById / consume / revokeById / revokeAllForUser
-  // IMPORTANT: `consume` must be atomic (single UPDATE ... WHERE revoked_at IS NULL
-  // AND token_hash = $hash RETURNING *). Non-atomic impls split sessions under load.
-}
-```
-
-### 2. Register the module
-
-```ts
-import { AuthModule } from '@codecanva/nest-auth';
-
-@Module({
-  imports: [
-    AuthModule.forRootAsync({
-      imports: [ConfigModule],
-      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: 'my-app',
-      }),
-      inject: [ConfigService],
-      store: { useClass: MyRefreshTokenStore },
-      validator: { useClass: MyUserValidator },
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-### 3. Apply the guard globally (optional)
-
-```ts
-import { APP_GUARD } from '@nestjs/core';
-import { JwtAuthGuard } from '@codecanva/nest-auth';
-
-providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }],
-```
-
-### 4. Use in controllers
-
-```ts
-import {
-  AuthService, 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')
-  logout(@Body() dto: RefreshTokenDto) { return this.auth.logout(dto.refreshToken); }
-}
-
-@Controller('me')
-export class MeController {
-  @Get() me(@CurrentUser() user: AuthUser) { return user; }
-}
-```
-
-## API surface
-
-- `AuthModule.forRootAsync(opts)` — only entry point
-- `AuthService` — `login` / `refresh` / `logout` / `logoutAll`
-- Guards — `JwtAuthGuard`, `RefreshAuthGuard`
-- Decorators — `@Public()`, `@CurrentUser()`
-- DTOs — `LoginDto`, `RefreshTokenDto`
-- Errors — `AuthError`, `InvalidCredentialsError`, `InvalidRefreshTokenError`, `RefreshTokenExpiredError`, `RefreshTokenReuseDetectedError`, `UserNotFoundError`
-- Interfaces — `AuthModuleOptions`, `AuthModuleAsyncOptions`, `AuthUser`, `JwtPayload`, `RefreshTokenStore`, `StoredRefreshToken`, `CreateRefreshTokenInput`, `SessionMetadata`, `UserValidator`
-
-## Local development / publishing
-
-```bash
-npm install            # install deps
-npm run start:dev      # run the demo app at :3000 (uses in-memory store + validator)
-npm run build:lib      # compile lib → dist/
-npm publish            # publish (runs build:lib via prepublishOnly)
-```
-
-To consume from a sibling project before publishing:
-
-```bash
-# in this repo
-npm run build:lib && npm pack
-# in the consumer
-npm install /path/to/codecanva-nest-auth-0.1.0.tgz
-```
-
-## Demo endpoints (when running `start:dev`)
-
-```
-POST /auth/login         { "email": "demo@example.com", "password": "password123" }
-POST /auth/refresh       { "refreshToken": "..." }
-POST /auth/logout        { "refreshToken": "..." }   # 204
-GET  /me                 # bearer access token required
-```
-
-## Security notes
-
-- Refresh tokens are JWTs; the **hash** of the JWT (sha256 + optional pepper) is stored, never the raw token.
-- `consume` must be atomic — non-atomic impls split sessions under concurrent refresh.
-- On replay (token hash mismatch or already-revoked row), every active session for that user is revoked.
-- Always serve auth over HTTPS. Store the refresh token in an httpOnly cookie when possible.
+# @codecanva/nest-auth
+
+Reusable NestJS authentication module. JWT access + refresh-token rotation, multi-device sessions, replay detection, and pluggable persistence (no DB lock-in).
+
+## Features
+
+- Short-lived access JWT + long-lived refresh JWT
+- Refresh-token rotation on every refresh (with replay detection → `revokeAllForUser`)
+- Multi-device sessions (one row per session, hashed at rest)
+- Pluggable `RefreshTokenStore` and `UserValidator` — bring your own DB
+- `@CurrentUser()`, `@Public()` decorators
+- `JwtAuthGuard` (honours `@Public()`) and `RefreshAuthGuard`
+- Configurable issuer, audience, clock tolerance, optional hash pepper
+
+## Install
+
+```bash
+npm install @codecanva/nest-auth \
+  @nestjs/jwt @nestjs/passport passport passport-jwt \
+  class-validator class-transformer
+```
+
+## Quick install (CLI)
+
+Scaffold everything into an existing NestJS project — user/auth files, env vars,
+AppModule + `main.ts` wiring, and dependencies — in one command:
+
+```bash
+# Mongoose persistence (default): generates user + refresh-token modules
+npx @codecanva/nest-auth init
+
+# In-memory store, no DB — great for a quick trial
+npx @codecanva/nest-auth init --store memory
+
+# Preview without writing anything
+npx @codecanva/nest-auth init --dry-run
+```
+
+The installer generates an `AuthIntegrationModule` (a single drop-in module that
+bundles the store, validator, controller, and the global `JwtAuthGuard`), adds it
+to your `AppModule`, and enables a global `ValidationPipe`. Existing files are
+never overwritten without `--force`, and every edited file is backed up to
+`<file>.bak`.
+
+| Flag | Effect |
+| --- | --- |
+| `--store <mongoose\|memory>` | Persistence to scaffold (default `mongoose`) |
+| `--dir <path>` | Target project root (default: current directory) |
+| `--no-wire` | Don't touch `app.module.ts` / `main.ts` |
+| `--skip-install` | Don't install npm dependencies |
+| `--force` | Overwrite files that already exist |
+| `--dry-run` | Show planned changes, write nothing |
+
+After running it, set real values for `JWT_ACCESS_SECRET`, `JWT_REFRESH_SECRET`,
+and `TOKEN_HASH_PEPPER` in `.env` (and, for `--store mongoose`, make sure a
+`MongooseModule.forRoot(...)` connection exists at the app root). For a fully
+manual, step-by-step walkthrough see [INSTALLATION.md](./INSTALLATION.md).
+
+## Usage
+
+### 1. Implement the two interfaces against your data layer
+
+```ts
+// users/user.validator.ts
+import { Injectable } from '@nestjs/common';
+import { AuthUser, UserValidator } from '@codecanva/nest-auth';
+
+@Injectable()
+export class MyUserValidator implements UserValidator {
+  async validateCredentials(email: string, password: string): Promise<AuthUser | null> {
+    // load user, bcrypt.compare, return { id, email, roles } or null
+  }
+  async findById(userId: string | number): Promise<AuthUser | null> {
+    // load by id, return AuthUser or null
+  }
+}
+```
+
+```ts
+// auth/refresh-token.store.ts — example with TypeORM
+import { Injectable } from '@nestjs/common';
+import {
+  CreateRefreshTokenInput,
+  RefreshTokenStore,
+  StoredRefreshToken,
+} from '@codecanva/nest-auth';
+
+@Injectable()
+export class MyRefreshTokenStore implements RefreshTokenStore {
+  // create / findById / consume / revokeById / revokeAllForUser
+  // IMPORTANT: `consume` must be atomic (single UPDATE ... WHERE revoked_at IS NULL
+  // AND token_hash = $hash RETURNING *). Non-atomic impls split sessions under load.
+}
+```
+
+### 2. Register the module
+
+```ts
+import { AuthModule } from '@codecanva/nest-auth';
+
+@Module({
+  imports: [
+    AuthModule.forRootAsync({
+      imports: [ConfigModule],
+      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: 'my-app',
+      }),
+      inject: [ConfigService],
+      store: { useClass: MyRefreshTokenStore },
+      validator: { useClass: MyUserValidator },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 3. Apply the guard globally (optional)
+
+```ts
+import { APP_GUARD } from '@nestjs/core';
+import { JwtAuthGuard } from '@codecanva/nest-auth';
+
+providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }],
+```
+
+### 4. Use in controllers
+
+```ts
+import {
+  AuthService, 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')
+  logout(@Body() dto: RefreshTokenDto) { return this.auth.logout(dto.refreshToken); }
+}
+
+@Controller('me')
+export class MeController {
+  @Get() me(@CurrentUser() user: AuthUser) { return user; }
+}
+```
+
+## API surface
+
+- `AuthModule.forRootAsync(opts)` — only entry point
+- `AuthService` — `login` / `refresh` / `logout` / `logoutAll`
+- Guards — `JwtAuthGuard`, `RefreshAuthGuard`
+- Decorators — `@Public()`, `@CurrentUser()`
+- DTOs — `LoginDto`, `RefreshTokenDto`
+- Errors — `AuthError`, `InvalidCredentialsError`, `InvalidRefreshTokenError`, `RefreshTokenExpiredError`, `RefreshTokenReuseDetectedError`, `UserNotFoundError`
+- Interfaces — `AuthModuleOptions`, `AuthModuleAsyncOptions`, `AuthUser`, `JwtPayload`, `RefreshTokenStore`, `StoredRefreshToken`, `CreateRefreshTokenInput`, `SessionMetadata`, `UserValidator`
+
+## Local development / publishing
+
+```bash
+npm install            # install deps
+npm run start:dev      # run the demo app at :3000 (uses in-memory store + validator)
+npm run build:lib      # compile lib → dist/
+npm publish            # publish (runs build:lib via prepublishOnly)
+```
+
+To consume from a sibling project before publishing:
+
+```bash
+# in this repo
+npm run build:lib && npm pack
+# in the consumer
+npm install /path/to/codecanva-nest-auth-0.1.0.tgz
+```
+
+## Demo endpoints (when running `start:dev`)
+
+```
+POST /auth/login         { "email": "demo@example.com", "password": "password123" }
+POST /auth/refresh       { "refreshToken": "..." }
+POST /auth/logout        { "refreshToken": "..." }   # 204
+GET  /me                 # bearer access token required
+```
+
+## Security notes
+
+- Refresh tokens are JWTs; the **hash** of the JWT (sha256 + optional pepper) is stored, never the raw token.
+- `consume` must be atomic — non-atomic impls split sessions under concurrent refresh.
+- On replay (token hash mismatch or already-revoked row), every active session for that user is revoked.
+- Always serve auth over HTTPS. Store the refresh token in an httpOnly cookie when possible.

package/dist/auth.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../src/lib/auth.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAoB,MAAM,gBAAgB,CAAC;AASjE,OAAO,KAAK,EACV,sBAAsB,EAGvB,MAAM,4CAA4C,CAAC;AAKpD,qBACa,UAAU;IACrB,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,sBAAsB,GAAG,aAAa;CAoCpE"}
+{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../src/lib/auth.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAoB,MAAM,gBAAgB,CAAC;AAWjE,OAAO,KAAK,EACV,sBAAsB,EAGvB,MAAM,4CAA4C,CAAC;AAKpD,qBACa,UAAU;IACrB,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,sBAAsB,GAAG,aAAa;CAwCpE"}

package/dist/auth.module.js

@@ -9,10 +9,12 @@ var AuthModule_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthModule = void 0;
 const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
 const jwt_1 = require("@nestjs/jwt");
 const passport_1 = require("@nestjs/passport");
 const auth_constants_1 = require("./auth.constants");
 const auth_service_1 = require("./auth.service");
+const auth_exception_filter_1 = require("./filters/auth-exception.filter");
 const token_service_1 = require("./services/token.service");
 const jwt_strategy_1 = require("./strategies/jwt.strategy");
 const refresh_strategy_1 = require("./strategies/refresh.strategy");
@@ -40,6 +42,10 @@ let AuthModule = AuthModule_1 = class AuthModule {
                 jwt_strategy_1.JwtStrategy,
                 refresh_strategy_1.RefreshStrategy,
                 auth_service_1.AuthService,
+                // Globally maps AuthError domain errors → HTTP responses (e.g.
+                // InvalidCredentialsError → 401), so consumers don't need per-route
+                // try/catch to get correct status codes on auth failure.
+                { provide: core_1.APP_FILTER, useClass: auth_exception_filter_1.AuthExceptionFilter },
             ],
             exports: [
                 auth_service_1.AuthService,

package/dist/auth.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.module.js","sourceRoot":"","sources":["../src/lib/auth.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAiE;AACjE,qCAAwC;AACxC,+CAAkD;AAClD,qDAI0B;AAC1B,iDAA6C;AAM7C,4DAAwD;AACxD,4DAAwD;AACxD,oEAAgE;AAGzD,IAAM,UAAU,kBAAhB,MAAM,UAAU;IACrB,MAAM,CAAC,YAAY,CAAC,OAA+B;QACjD,MAAM,eAAe,GAAa;YAChC,OAAO,EAAE,oCAAmB;YAC5B,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;SAC7B,CAAC;QAEF,MAAM,aAAa,GAAG,aAAa,CAAC,oCAAmB,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACxE,MAAM,iBAAiB,GAAG,aAAa,CAAC,+BAAc,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAE3E,OAAO;YACL,MAAM,EAAE,YAAU;YAClB,OAAO,EAAE;gBACP,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;gBAC1B,yBAAc;gBACd,eAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;aACvB;YACD,SAAS,EAAE;gBACT,eAAe;gBACf,aAAa;gBACb,iBAAiB;gBACjB,4BAAY;gBACZ,0BAAW;gBACX,kCAAe;gBACf,0BAAW;aACZ;YACD,OAAO,EAAE;gBACP,0BAAW;gBACX,oCAAmB;gBACnB,oCAAmB;gBACnB,+BAAc;gBACd,eAAS;gBACT,yBAAc;aACf;SACF,CAAC;IACJ,CAAC;CACF,CAAA;AArCY,gCAAU;qBAAV,UAAU;IADtB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,UAAU,CAqCtB;AAED,SAAS,aAAa,CACpB,KAAa,EACb,GAAsD;IAEtD,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;QACnB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE;SACzB,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;QACpB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC;IAC1D,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC;IACpD,CAAC;IACD,MAAM,IAAI,KAAK,CACb,4BAA4B,KAAK,CAAC,QAAQ,EAAE,gDAAgD,CAC7F,CAAC;AACJ,CAAC"}
+{"version":3,"file":"auth.module.js","sourceRoot":"","sources":["../src/lib/auth.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAiE;AACjE,uCAA0C;AAC1C,qCAAwC;AACxC,+CAAkD;AAClD,qDAI0B;AAC1B,iDAA6C;AAC7C,2EAAsE;AAMtE,4DAAwD;AACxD,4DAAwD;AACxD,oEAAgE;AAGzD,IAAM,UAAU,kBAAhB,MAAM,UAAU;IACrB,MAAM,CAAC,YAAY,CAAC,OAA+B;QACjD,MAAM,eAAe,GAAa;YAChC,OAAO,EAAE,oCAAmB;YAC5B,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;SAC7B,CAAC;QAEF,MAAM,aAAa,GAAG,aAAa,CAAC,oCAAmB,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACxE,MAAM,iBAAiB,GAAG,aAAa,CAAC,+BAAc,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAE3E,OAAO;YACL,MAAM,EAAE,YAAU;YAClB,OAAO,EAAE;gBACP,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;gBAC1B,yBAAc;gBACd,eAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;aACvB;YACD,SAAS,EAAE;gBACT,eAAe;gBACf,aAAa;gBACb,iBAAiB;gBACjB,4BAAY;gBACZ,0BAAW;gBACX,kCAAe;gBACf,0BAAW;gBACX,+DAA+D;gBAC/D,oEAAoE;gBACpE,yDAAyD;gBACzD,EAAE,OAAO,EAAE,iBAAU,EAAE,QAAQ,EAAE,2CAAmB,EAAE;aACvD;YACD,OAAO,EAAE;gBACP,0BAAW;gBACX,oCAAmB;gBACnB,oCAAmB;gBACnB,+BAAc;gBACd,eAAS;gBACT,yBAAc;aACf;SACF,CAAC;IACJ,CAAC;CACF,CAAA;AAzCY,gCAAU;qBAAV,UAAU;IADtB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,UAAU,CAyCtB;AAED,SAAS,aAAa,CACpB,KAAa,EACb,GAAsD;IAEtD,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;QACnB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE;SACzB,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;QACpB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC;IAC1D,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC;IACpD,CAAC;IACD,MAAM,IAAI,KAAK,CACb,4BAA4B,KAAK,CAAC,QAAQ,EAAE,gDAAgD,CAC7F,CAAC;AACJ,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/cli/index.ts"],"names":[],"mappings":""}