nestjs-auth-bootstrap

nestjs-auth-bootstrap

Scaffold a production-ready NestJS authentication & authorization system in any project — Passport JWT, OAuth2-style permissions, role policy, refresh tokens, throttling, and self-extending docs — in one guided run.

A Claude Code skill that drops a battle-tested auth architecture into a target NestJS project. It analyzes the project first, asks only what it can't infer, installs the right dependencies for your stack, and scaffolds the canonical files. It also writes a CLAUDE.md section and a docs/auth/EXTENDING.md runbook so future Claude sessions know how to extend the system without losing context.

---

What it scaffolds

• AuthModule — Passport + @nestjs/jwt, single login endpoint for all roles
• 3 endpoints — POST /auth/login, POST /auth/refresh, GET /auth/me
• One global guard — CompositeAuthGuard registered via APP_GUARD (no per-handler guard stacking)
• 4 decorators — @Public, @RequirePermission, @CurrentUser, @Roles
• OAuth2-style Permission enum — <RESOURCE>_READ / WRITE / MANAGE per resource
• Roles + policy matrix — SUPER_ADMIN / ADMIN / USER (extendable), ROLE_PERMISSIONS, ASSIGNABLE_ROLES, hasPermission, canAssignRole
• Refresh tokens with type: 'refresh' claim
• ThrottlerGuard — global rate limiting + tighter limits on /auth/*
• ValidationPipe — global { whitelist, transform, forbidNonWhitelisted }
• Persistence layer — variant per ORM: Mongoose schema / TypeORM entity / Prisma model / stub repository
• Self-documenting — appends a section to your CLAUDE.md and creates docs/auth/EXTENDING.md with recipes for adding resources, roles, second auth strategies, account lockout, audit logging, refresh rotation, and multi-tenancy

---

Installation

Via Claude Code plugin manager (recommended)

This repo ships as a plugin: marketplace manifest at .claude-plugin/marketplace.json, plugin manifest at .claude-plugin/plugin.json, slash commands at .claude/commands/, and the skill at .claude/skills/nestjs-auth-bootstrap/.

Inside any Claude Code session:

/plugin marketplace add accentiostudios/nestjs-auth-bootstrap
/plugin menu

Then enable nestjs-auth-bootstrap from the menu. The skill auto-loads on matching prompts; the slash commands become available immediately.

Manage afterwards:

/plugin list                                          # what's installed
/plugin update accentiostudios/nestjs-auth-bootstrap  # pull latest
/plugin disable nestjs-auth-bootstrap                 # turn off without removing
/plugin remove accentiostudios/nestjs-auth-bootstrap  # uninstall

Slash commands exposed by the plugin

Command	Purpose
/bootstrap-auth	Full 5-phase scaffold: analyze → ask → confirm → execute → verify.
/analyze-auth	Phase 1 only — reports project state without writing files.
/extend-auth	Add a resource, role, or recipe to an existing install via EXTENDING.md.

The skill also auto-triggers on natural prompts (see Usage) — slash commands are just deterministic shortcuts.

As a project-local skill (manual, no plugin)

Drop the whole nestjs-auth-bootstrap/ folder into your project's .claude/skills/ directory:

your-project/
├── .claude/
│   └── skills/
│       └── nestjs-auth-bootstrap/
│           ├── SKILL.md
│           ├── references/
│           └── templates/
└── ...

Claude auto-discovers skills under .claude/skills/ — no settings file edit needed. Commit it; everyone on the team gets it.

As a user-global skill

Copy the folder to ~/.claude/skills/nestjs-auth-bootstrap/. It becomes available across all your projects.

---

Usage

In a Claude Code session inside a NestJS project, say:

"Scaffold NestJS auth with roles and permissions"

…or any of:

• "Add JWT auth to this NestJS project"
• "Set up login + refresh + permission guards"
• "Necesito sistema de auth con roles en este NestJS"
• "Bootstrap auth in my Nest app"

Claude will pick up the skill and run a 5-phase workflow:

Phase	What happens
1. Analyze	Reads package.json, app.module.ts, main.ts, tsconfig.json. Detects NestJS version, package manager, ORM, existing auth artifacts, folder layout. Reports findings.
2. Ask	Asks only what it can't infer: existing-auth strategy (abort/merge/overwrite), ORM if none detected, extra resources beyond USER/ORGANIZATION, extra roles, multi-tenant or not.
3. Confirm	Shows the exact list of files to create/modify and dependencies to install. Waits for OK.
4. Execute	Installs deps with the detected package manager, renders templates, merges app.module.ts, appends CLAUDE.md, creates docs/auth/EXTENDING.md.
5. Verify	Runs tsc --noEmit, lists registered routes, suggests cURL smoke tests.