my-crud-lib 1.0.4 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to `my-crud-lib` are documented here.
+
+This project follows semantic versioning. Breaking changes are called out explicitly and should be reviewed before upgrading.
+
+## 2.1.0 - Unreleased
+
+### Added
+
+- Added a repeatable changelog and release-note workflow.
+- Added a v2 migration guide for applications upgrading from the pre-v2 API shape.
+- Added `prisma.config.ts` so Prisma CLI configuration no longer relies on the deprecated `package.json#prisma` field.
+- Added self-hosted GitHub Actions runner documentation and configured CI to target the `local-ci` runner label.
+- Added optional persistent refresh token rotation/revocation ports and Prisma adapter.
+- Added optional password reset request/confirm service methods, routes, hooks, token repository port, and Prisma adapter.
+- Added optional email verification request/confirm service methods, routes, hooks, token repository port, and Prisma adapter.
+- Added provider-agnostic OAuth account linking service methods, port, and Prisma adapter.
+
+### Changed
+
+- Bumped the package version to `2.1.0`.
+- Expanded the starter Prisma schema with optional auth extension storage models.
+
+## 2.0.0 - 2026-05-14
+
+### Breaking Changes
+
+- Auth routes are now dependency-injected. `createAuthRouter()` requires a `userRepo` dependency instead of constructing Prisma access internally.
+- `createLibrary()` now receives application dependencies separately from route configuration.
+- Self-registration creates `USER` accounts by default. Applications must create `ADMIN` users intentionally through their own seed or admin workflow.
+- Public imports were consolidated around documented package entry points: `my-crud-lib`, `my-crud-lib/auth`, `my-crud-lib/user`, `my-crud-lib/schemas`, `my-crud-lib/middleware`, `my-crud-lib/adapter-prisma`, and `my-crud-lib/adapters/prisma`.
+
+### Added
+
+- Added public Express router factories for auth and user/profile CRUD.
+- Added `UserRepo` as the core persistence port.
+- Added Prisma adapter exports.
+- Added smoke tests for public package exports, auth safety defaults, and adapter-driven auth service behavior.
+
+### Changed
+
+- Prisma is optional for consumers that provide a custom repository adapter.
+- Auth behavior now strips `passwordHash` from service responses.
+- JWT configuration validates `JWT_SECRET` before signing or verifying tokens.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Riccardo Sensi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,214 +1,309 @@
 # my-crud-lib
 
-A modular, TypeScript-first **Auth + User/Profile CRUD** library for Node.js, designed to be **framework-light**, **DB-agnostic** (via adapters), and **highly extensible** (schemas + hooks). Ship a secure `/auth/register`, `/auth/login`, and `/me` in minutes—then customize without forking the core.
+[![CI](https://github.com/riccardosensi99/CRUD-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/riccardosensi99/CRUD-lib/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/my-crud-lib.svg)](https://www.npmjs.com/package/my-crud-lib)
 
-> Works great with Express and Prisma out of the box, but you can plug in your own repo adapter.
+TypeScript-first auth and user/profile CRUD helpers for Node.js and Express.
 
----
+The package currently provides:
 
-## Features
+- Express routers for auth and user CRUD.
+- JWT access and refresh token helpers.
+- Optional persistent refresh token rotation and revocation.
+- Optional password reset and email verification hooks.
+- Provider-agnostic OAuth account linking extension points.
+- Zod schemas for request validation.
+- A `UserRepo` port plus a Prisma adapter.
+- Convenience setup helpers for small Express APIs.
 
-- ✅ Ready-made routes: `POST /auth/register`, `POST /auth/login`, `GET /me`
-- 🔐 JWT-based auth with pluggable lifecycle hooks (before/after create, before issuing JWT, etc.)
-- 🧩 Extensible validation via **Zod**: merge your own fields into the base schemas
-- 🗄️ Repository interfaces (DB-agnostic) + optional Prisma adapter
-- 🧰 Cleanly separated core logic & web router
-- 🧪 TypeScript types exported for DX
-
----
+For advanced auth flows, see [docs/auth-extensions.md](docs/auth-extensions.md). For v1 to v2 upgrades, see [docs/migration-v2.md](docs/migration-v2.md). Release history and breaking changes are tracked in [CHANGELOG.md](CHANGELOG.md).
 
 ## Installation
 
 ```bash
-npm i my-crud-lib zod jsonwebtoken bcryptjs
-# If using Prisma adapter in your app:
-npm i @prisma/client
+npm i my-crud-lib express cors body-parser
 ```
 
-> Node.js `>= 18.17` is required.
+If you use the bundled Prisma adapter:
+
+```bash
+npm i @prisma/client prisma
+npx prisma generate
+```
 
----
+Node.js `>=18.17` is required.
 
-## Quickstart (Express)
+## Environment
+
+```bash
+DATABASE_URL="postgresql://user:password@localhost:5432/app"
+JWT_SECRET="replace-with-a-long-random-secret"
+JWT_ACCESS_EXPIRES_IN="15m"
+JWT_REFRESH_EXPIRES_IN="7d"
+BCRYPT_SALT="10"
+```
+
+`JWT_ACCESS_EXPIRES_IN` and `JWT_REFRESH_EXPIRES_IN` have defaults. `JWT_SECRET` and `DATABASE_URL` must be set before using the default auth and Prisma paths.
+
+## Quickstart With Express And Prisma
 
 ```ts
-import express from "express";
-import { json } from "body-parser";
-import { createLibrary } from "my-crud-lib";
-// Optional: Prisma adapter (provided in your app)
 import { PrismaClient } from "@prisma/client";
-import { makePrismaUserRepo } from "my-crud-lib/adapter-prisma"; // if you expose this path
+import { createLibrary, createServer } from "my-crud-lib";
+import { makePrismaUserRepo } from "my-crud-lib/adapter-prisma";
 
 const prisma = new PrismaClient();
-
-const app = express();
-app.use(json());
+const app = createServer();
 
 const lib = createLibrary(
   {
+    routesPrefix: "/api",
     auth: {
-      jwtSecret: process.env.JWT_SECRET!, // e.g. "supersecret"
-      jwtExpiresIn: "7d",
       passwordHashRounds: 10,
     },
-    routesPrefix: "/api", // optional
   },
   { userRepo: makePrismaUserRepo(prisma) }
 );
 
 app.use(lib.router);
 
-app.listen(3000, () => console.log("API running on http://localhost:3000"));
+app.listen(3000, () => {
+  console.log("API running on http://localhost:3000");
+});
 ```
 
-### Available Routes
+With the `/api` prefix, the mounted routes include:
 
-- `POST /auth/register` → create user (email + password + optional name)
-- `POST /auth/login` → returns `{ accessToken }`
-- `GET /me` → authenticated endpoint, returns the current user
+- `POST /api/auth/register`
+- `POST /api/auth/login`
+- `POST /api/auth/refresh`
+- `POST /api/auth/logout`
+- `POST /api/auth/password-reset/request`
+- `POST /api/auth/password-reset/confirm`
+- `POST /api/auth/email-verification/request`
+- `POST /api/auth/email-verification/confirm`
+- `GET /api/auth/me`
+- `GET /api/users`
+- `GET /api/users/me`
+- `PUT /api/users/me`
+- `POST /api/users`
+- `GET /api/users/:id`
+- `PUT /api/users/:id`
+- `DELETE /api/users/:id`
 
-> Protect `/me` with the `isAuth` middleware already wired inside the library router.
+Admin user routes require a bearer token with role `ADMIN`.
 
----
+## Examples
 
-## Configuration
+- `examples/express-prisma` is a runnable Express + Prisma app.
+- `examples/custom-repo` shows the `UserRepo` shape with an in-memory adapter.
 
-```ts
-type AuthConfig = {
-  jwtSecret: string;
-  jwtExpiresIn: string; // e.g. "7d"
-  passwordHashRounds: number; // e.g. 10
-};
-
-type LibraryConfig = {
-  auth: AuthConfig;
-  routesPrefix?: string; // e.g. "/api"
-};
+Run the Prisma example:
+
+```bash
+cd examples/express-prisma
+npm install
+cp .env.example .env
+npx prisma generate
+npx prisma migrate dev --name init
+npm run dev
 ```
 
-Create the library:
+## Response Examples
 
-```ts
-const lib = createLibrary(config, { userRepo });
+Register:
+
+```http
+POST /api/auth/register
+Content-Type: application/json
+
+{
+  "email": "reader@example.com",
+  "password": "password123",
+  "name": "Reader"
+}
 ```
 
----
+Response:
 
-## Extending Schemas (Zod)
+```json
+{
+  "user": {
+    "id": 1,
+    "email": "reader@example.com",
+    "name": "Reader",
+    "role": "USER"
+  },
+  "accessToken": "eyJ...",
+  "refreshToken": "eyJ..."
+}
+```
 
-The library exports base Zod schemas and a factory to merge your custom fields.
+Login:
 
-```ts
-// consumer app
-import { z } from "zod";
-import { makeCreateUserSchema } from "my-crud-lib/schemas";
+```http
+POST /api/auth/login
+Content-Type: application/json
 
-const ExtraUserFields = z.object({
-  companyVat: z.string().min(5),
-  marketingOptIn: z.boolean().default(false),
-});
+{
+  "email": "reader@example.com",
+  "password": "password123"
+}
+```
 
-export const CreateUserSchema = makeCreateUserSchema(ExtraUserFields);
+Protected request:
 
-// Later in your route (if you override the built-in):
-const data = CreateUserSchema.parse(req.body);
+```http
+GET /api/auth/me
+Authorization: Bearer <accessToken>
 ```
 
-**Tip:** The default Prisma schema (if you use it) exposes `profile.extra: Json?` so you can store arbitrary fields without altering the core tables.
+## Public Imports
 
----
+```ts
+import {
+  createLibrary,
+  createServer,
+  mountDefaultRoutes,
+  createAuthRouter,
+  createUserRouter,
+  isAuth,
+  hasRole,
+} from "my-crud-lib";
+
+import { createAuthRouter, makeAuthService, registerSchema, loginSchema } from "my-crud-lib/auth";
+import { createUserRouter, type UserRepo } from "my-crud-lib/user";
+import { registerSchema, listUsersQuerySchema } from "my-crud-lib/schemas";
+import { isAuth, hasRole } from "my-crud-lib/middleware";
+import { makePrismaUserRepo } from "my-crud-lib/adapter-prisma";
+import { makePrismaUserRepo as makePrismaUserRepoCanonical } from "my-crud-lib/adapters/prisma";
+```
 
-## Hooks (Lifecycle)
+## Repository Adapter
 
-Use hooks to change data or enrich tokens without forking.
+User CRUD is driven by the `UserRepo` interface:
 
 ```ts
-import { plugins } from "my-crud-lib";
-
-plugins.use({
-  beforeCreateUser: async (data, ctx) => {
-    if (data.companyVat) data.companyVat = data.companyVat.toUpperCase();
-    return data;
-  },
-  afterCreateUser: async (user, ctx) => {
-    // e.g., send welcome email or audit log
-  },
-  beforeIssueJwt: (payload, ctx) => {
-    return { ...payload, tenantId: "acme-123" };
-  },
-});
+export interface UserRepo {
+  count(where: { role?: string; search?: string }): Promise<number>;
+  findMany(params: {
+    page: number;
+    pageSize: number;
+    role?: string;
+    search?: string;
+    sortField: "createdAt" | "updatedAt" | "email" | "name";
+    sortDir: "asc" | "desc";
+  }): Promise<UserListItem[]>;
+  findById(id: number | string): Promise<UserListItem | null>;
+  findByEmail(email: string): Promise<(UserListItem & { passwordHash?: string }) | null>;
+  create(input: {
+    email: string;
+    passwordHash: string;
+    name?: string | null;
+    role?: string;
+    bio?: string | null;
+    avatarUrl?: string | null;
+  }): Promise<UserListItem>;
+  update(id: number | string, input: AdminUpdateUserInput): Promise<UserListItem>;
+  delete(id: number | string): Promise<void>;
+  updateMe(
+    userId: number | string,
+    input: { name?: string | null; bio?: string | null; avatarUrl?: string | null }
+  ): Promise<UserListItem>;
+}
 ```
 
-**Available hooks**
-- `beforeCreateUser(data, ctx)`
-- `afterCreateUser(user, ctx)`
-- `beforeUpdateUser(data, ctx)`
-- `beforeIssueJwt(payload, ctx)`
+The Prisma adapter is available from both import paths:
 
-`ctx` includes the request and useful dependencies (e.g., repos).
+```ts
+import {
+  makePrismaEmailVerificationTokenRepo,
+  makePrismaOAuthAccountRepo,
+  makePrismaPasswordResetTokenRepo,
+  makePrismaRefreshTokenRepo,
+  makePrismaUserRepo,
+} from "my-crud-lib/adapter-prisma";
+// or
+import { makePrismaUserRepo } from "my-crud-lib/adapters/prisma";
+```
 
----
+Auth also receives the same repository dependency:
 
-## Repository Adapters (DB-agnostic)
+```ts
+import { createAuthRouter } from "my-crud-lib/auth";
 
-Core interface:
+app.use("/auth", createAuthRouter({ userRepo }));
+```
+
+Optional auth extensions use additional ports:
 
 ```ts
-export interface UserRepo {
-  create(data: any): Promise<any>;
-  update(id: string, data: any): Promise<any>;
-  findById(id: string): Promise<any | null>;
-  findByEmail(email: string): Promise<any | null>;
-}
+app.use(
+  "/auth",
+  createAuthRouter({
+    userRepo,
+    refreshTokenRepo,
+    passwordResetTokenRepo,
+    emailVerificationTokenRepo,
+    oauthAccountRepo,
+    async sendPasswordReset({ user, token }) {
+      await emailProvider.sendPasswordReset(user.email, token);
+    },
+    async sendEmailVerification({ user, token }) {
+      await emailProvider.sendVerification(user.email, token);
+    },
+  })
+);
 ```
 
-Example Prisma adapter (in your app or provided by the lib):
+These dependencies are optional. Without them, the existing stateless refresh-token flow remains available and password reset, email verification, and OAuth methods report that they are not configured.
 
-```ts
-export function makePrismaUserRepo(prisma: any): UserRepo {
-  return {
-    create: (data) => prisma.user.create({ data }),
-    update: (id, data) => prisma.user.update({ where: { id }, data }),
-    findById: (id) => prisma.user.findUnique({ where: { id } }),
-    findByEmail: (email) => prisma.user.findUnique({ where: { email } }),
-  };
-}
+## Build Checks
+
+```bash
+npm run build
+npm test
+npm run smoke:exports
+npm run smoke:auth-hardening
+npm run smoke:auth-service
 ```
 
----
+`smoke:exports` builds the package and imports the documented public paths from `dist`.
+`smoke:auth-hardening` checks auth safety defaults and JWT secret validation.
+`smoke:auth-service` verifies register/login/refresh/me with an in-memory repo.
 
-## Types
+## Current Limitations
 
-The package exports the main public types:
+- Lifecycle hooks and schema factories are not part of the current public API.
+- The Prisma schema is included as a starter schema; consumer apps should own their migrations.
 
-- `LibraryConfig`, `AuthConfig`
-- `UserRepo`
-- schema types (e.g., `CreateUserBase`)
+## Troubleshooting
 
----
+`Cannot find module '@prisma/client'`
 
-## Security Notes
+Install Prisma dependencies in your app and run `npx prisma generate`.
 
-- Keep `JWT_SECRET` secure; rotate if compromised.
-- Consider adding rate limiting in your app (e.g., `express-rate-limit`).
-- Store password hashes using `bcryptjs` with adequate rounds (default shown: `10`).
-- Use HTTPS in production.
+`JWT_SECRET is required before signing or verifying tokens`
 
----
+Set `JWT_SECRET` before mounting or calling auth routes. Use a long random value.
 
-## Optional
+`Invalid or expired token`
 
-if you want to use the prisma adeapter use:
+Send the access token in the `Authorization` header as `Bearer <accessToken>`. Use `/auth/refresh` with a refresh token to get a new pair.
 
-npm i @prisma/client prisma
-npx prisma generate
+ESM import errors
 
-## Contributing
+Use Node.js `>=18.17` and import from the documented package paths, for example `my-crud-lib`, `my-crud-lib/auth`, or `my-crud-lib/adapter-prisma`.
 
-PRs and issues are welcome! Please follow conventional commits or include a clear description. For releases, we recommend Changesets or semantic-release.
+## Security Notes
 
----
+- Use a long random `JWT_SECRET` and rotate it if compromised.
+- Keep access tokens short-lived.
+- Add rate limiting around auth endpoints in production.
+- Use HTTPS in production.
+- Self-registration creates `USER` accounts by default.
+- Create `ADMIN` accounts intentionally through your own seed/admin workflow.
 
 ## License
 
-MIT © Riccardo
+MIT

package/RELEASE.md

@@ -0,0 +1,36 @@
+# Release Checklist
+
+Use this checklist before publishing `my-crud-lib` to npm.
+
+## Preflight
+
+- Confirm `package.json` version is the intended release version.
+- Add an entry to `CHANGELOG.md` under the target version.
+- Move `CHANGELOG.md` entries from `Unreleased` to the release date before publishing.
+- Confirm `README.md` examples match tested public imports.
+- Confirm migration notes are linked when the release contains breaking changes.
+- Confirm `LICENSE`, `README.md`, `examples`, `dist`, and `prisma/schema.prisma` are included in the package.
+- Review open issues for release blockers.
+
+## Verify
+
+```bash
+npm ci
+npm run ci
+npm pack --dry-run
+```
+
+Inspect the dry-run file list before publishing.
+
+## Publish
+
+```bash
+npm publish --access public
+```
+
+## After Publish
+
+- Create a GitHub release or tag for the published version.
+- Use `CHANGELOG.md` as the release body, and include migration links for breaking releases.
+- Confirm the npm page shows repository, license, README, examples, and keywords.
+- Smoke test installation in a fresh temporary project.

package/dist/adapter-prisma.d.ts

@@ -0,0 +1 @@
+export { makePrismaEmailVerificationTokenRepo, makePrismaOAuthAccountRepo, makePrismaPasswordResetTokenRepo, makePrismaRefreshTokenRepo, makePrismaUserRepo, } from './adapters/prisma.js';

package/dist/adapter-prisma.js

@@ -0,0 +1 @@
+export { makePrismaEmailVerificationTokenRepo, makePrismaOAuthAccountRepo, makePrismaPasswordResetTokenRepo, makePrismaRefreshTokenRepo, makePrismaUserRepo, } from './adapters/prisma.js';

package/dist/adapters/prisma.d.ts

@@ -1,3 +1,8 @@
 import type { PrismaClient } from '@prisma/client';
 import type { UserRepo } from '../core/ports/user.repo.js';
+import type { EmailVerificationTokenRepo, OAuthAccountRepo, PasswordResetTokenRepo, RefreshTokenRepo } from '../modules/auth/auth.types.js';
 export declare function makePrismaUserRepo(prisma: PrismaClient): UserRepo;
+export declare function makePrismaRefreshTokenRepo(prisma: PrismaClient): RefreshTokenRepo;
+export declare function makePrismaPasswordResetTokenRepo(prisma: PrismaClient): PasswordResetTokenRepo;
+export declare function makePrismaEmailVerificationTokenRepo(prisma: PrismaClient): EmailVerificationTokenRepo;
+export declare function makePrismaOAuthAccountRepo(prisma: PrismaClient): OAuthAccountRepo;