@cauth/express 0.0.5 → 0.1.2

package/README.md

@@ -1,140 +1,117 @@
 # @cauth/express
 
-Express integration for CAuth authentication system.
+[![NPM Version](https://img.shields.io/npm/v/@cauth/express.svg)](https://www.npmjs.com/package/@cauth/express)
 
-## Features
+**CAuth Express** provides seamless integration between the CAuth core authentication system and Express.js applications. It includes type-safe route handlers, middleware, and request augmentation.
 
-- **Express Integration**: Seamless integration with Express.js applications
-- **Type-Safe Routes**: TypeScript support for route handlers
-- **Authentication Middleware**: Ready-to-use authentication guard
-- **Request Augmentation**: Typed user data in request object
-- **Error Handling**: Express-compatible error handling
+> [!IMPORTANT]
+> For more information and full documentation, visit **[cauth.dev](https://cauth.dev)**.
 
-## Installation
+---
+
+## ✨ Features
+
+- **🚀 Express Optimized**: Plug-and-play middleware and route handlers.
+- **🛡️ Type-Safe Guard**: Protect routes with RBAC that knows your roles.
+- **📦 Request Augmentation**: Automatically injects `req.cauth` with user session data.
+- **🧩 Flexible**: Use pre-built routes or call core `FN` functions manually.
+- **🛡️ Standardized Errors**: Automatically maps core errors to appropriate HTTP status codes.
+
+---
+
+## 🚀 Installation
 
 ```bash
 npm install @cauth/express @cauth/core
 # or
 yarn add @cauth/express @cauth/core
-# or
-pnpm add @cauth/express @cauth/core
 ```
 
-## Quick Start
+---
+
+## 🏁 Quick Start
+
+1. Initialize your CAuth client (see `@cauth/core` for full config).
+2. Attach the generated routes and middleware to your Express app.
 
 ```typescript
 import express from 'express';
-import { CAuth } from '@cauth/core';
-import { ExpressContractor, Guard } from '@cauth/express';
-import { PrismaContractor } from '@cauth/prisma';
+import auth from './auth'; // Your initialized CAuth instance
 
 const app = express();
 app.use(express.json());
 
-// Initialize CAuth with Express contractor
-const CAuthClient = CAuth({
-  dbContractor: new PrismaContractor(prismaClient),
-  routeContractor: new ExpressContractor(),
-  roles: ['USER', 'ADMIN'],
-  jwtConfig: {
-    accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
-    refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
-  }
-});
-
-//  authentication routes
-app.post('/register', CAuthClient.Routes.Register())
-
-app.post('/login', CAuthClient.Routes.Login())
-
-// Using the Guard to extract the id from the user's request
-app.post('/change-password', CAuthClient.Guard(),  (req: Request, res: Response) => CAuth.Guard(), CAuthClient.Routes.ChangePassword(req.cauth?.id!)(req, res))
-
-
-app.post('/refresh', CAuthClient.Routes.Refresh())
-
-app.post('/logout', CAuthClient.Routes.Logout())
-
-app.post('/login-with-code', async (req: Request, res: Response) => {
-    const result = await CAuthClient.FN.LoginWithOTP({ phoneNumber: req.body.phone, code: req.body.code })
+// 1. Mount pre-built authentication routes
+app.post('/auth/register', auth.Routes.Register());
+app.post('/auth/login', auth.Routes.Login());
+app.post('/auth/refresh', auth.Routes.Refresh());
+app.post('/auth/logout', auth.Routes.Logout());
 
-    return res.send(result)
-
-})
-
-// Protected route example
-app.get('/protected', CAuthClient.Guard(), (req, res) => {
-  // User data is available in req.user
-  res.json({ message: 'Protected data', user: req.user });
-});
-
-// Role-based protection
-app.get('/admin', Guard(['ADMIN']), (req, res) => {
-  res.json({ message: 'Admin only', user: req.user });
+// 2. Protect routes with the Guard middleware
+app.get('/me', auth.Guard(), (req, res) => {
+  // Access typed user data from req.cauth
+  res.json({ user: req.cauth });
 });
 
-app.listen(3000, () => {
-  console.log('Server running on port 3000');
+// 3. Role-based protection
+app.get('/admin', auth.Guard(['ADMIN']), (req, res) => {
+  res.json({ message: 'Welcome, Admin!' });
 });
-```
-
-## API Reference
-
 
-### Guard Middleware
-
-The `Guard` middleware protects routes and adds user data to the request object:
-
-```typescript
-// Protect route for authenticated users
-app.get('/profile', CAuthCliebt.Guard(), (req, res) => {
-  const data = req.cauth; // TypeScript knows user exists
-  res.json({ user });
+// 4. Manual usage in custom routes
+app.post('/auth/reset-password', async (req, res) => {
+  const result = await auth.FN.RequestOTPCode({
+    email: req.body.email,
+    otpPurpose: 'RESET_PASSWORD',
+    onCode: (code) => {
+       // Logic to send code via email
+       console.log(`OTP Code: ${code}`);
+    }
+  });
+  
+  res.status(result.success ? 200 : 400).send(result);
 });
 
-// Protect route for specific roles
-app.get('/admin', Guard(['ADMIN']), (req, res) => {
-  res.json({ message: 'Admin access granted' });
-});
+app.listen(3000);
 ```
 
-### Request Object
+---
 
-The middleware augments the Express `Request` object with user data:
-
-```typescript
-interface AuthenticatedRequest extends Request {
-  cauth: {
-    id: string;
-    role: string;
-  };
-}
-```
+## 📖 API Reference
 
-### Error Handling
+### `auth.Guard(roles?: string[])`
+A middleware that verifies the Access Token in the `Authorization` header (`Bearer <token>`).
 
-Common error status codes:
+- If no roles are provided, it only checks for a valid session.
+- If roles are provided, it checks if the user has one of the specified roles.
+- Injects `req.cauth` with `{ id: string, role: string }`.
 
-- 400: Invalid request data
-- 401: Unauthorized (invalid credentials)
-- 403: Forbidden (insufficient permissions)
-- 404: Account not found
-- 409: Duplicate account
-- 422: Invalid OTP code
+### `auth.Routes`
+A collection of pre-configured Express route handlers:
 
-## Development
+- **Register**: `POST` handler for user creation.
+- **Login**: `POST` handler for credentials-based auth.
+- **Logout**: `POST` handler that revokes refresh tokens.
+- **Refresh**: `POST` handler for rotating access tokens.
+- **ChangePassword**: `POST` handler for updating passwords (requires `userId`).
 
-### Prerequisites
+---
 
-- Node.js >= 18
-- TypeScript >= 5.9
-- Express.js >= 4.18
+## 🔒 Error Mapping
 
+CAuth Express automatically maps core errors to HTTP status codes:
 
-## License
+| Core Error | HTTP Status |
+| :--- | :--- |
+| `CredentialMismatchError` | 401 Unauthorized |
+| `InvalidDataError` | 400 Bad Request |
+| `AccountNotFoundError` | 404 Not Found |
+| `InvalidRoleError` | 403 Forbidden |
+| `DuplicateAccountError` | 409 Conflict |
+| `InvalidOTPCode` | 422 Unprocessable Entity |
 
-MIT License - see LICENSE file for details.
+---
 
-## Support
+## 📄 License
 
-For issues and feature requests, please visit the [GitHub repository](https://github.com/jonace-mpelule/cauth).
+MIT © [Jonace Mpelule](https://github.com/jonace-mpelule)

package/dist/index.d.ts

@@ -23,16 +23,26 @@ declare const AuthModelSchema: z$1.ZodObject<{
   passwordHash: z$1.ZodOptional<z$1.ZodString>;
   role: z$1.ZodString;
   lastLogin: z$1.ZodDate;
-  refreshTokens: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+  refreshTokens: z$1.ZodArray<z$1.ZodObject<{
+    token: z$1.ZodString;
+    exp: z$1.ZodCoercedNumber<unknown>;
+  }, z$1.core.$strip>>;
   createdAt: z$1.ZodDate;
   updatedAt: z$1.ZodDate;
-}, z$1.z.core.$strip>;
+}, z$1.core.$strip>;
 type AuthModel = z$1.infer<typeof AuthModelSchema>;
 //#endregion
+//#region ../core/src/errors/errors.d.ts
+type CAuthErrorShape = {
+  type: string;
+  message: string;
+  code: string | number;
+  name: string;
+};
+//#endregion
 //#region ../core/src/types/result.t.d.ts
 type FNError = {
-  type: string;
-  error: Error;
+  error: CAuthErrorShape;
 };
 /**
  * @description Core Result type.
@@ -84,6 +94,7 @@ interface DatabaseContract {
     id: string;
     refreshToken: string;
     select?: any;
+    config: CAuthOptions;
   }): Promise<T>;
   removeAndAddRefreshToken({
     ...args
@@ -133,30 +144,62 @@ declare const CAuthOptionsSchema: z$1.ZodObject<{
     accessTokenSecret: z$1.ZodString;
     accessTokenLifeSpan: z$1.ZodOptional<z$1.ZodCustom<ms.StringValue, ms.StringValue>>;
     refreshTokenLifeSpan: z$1.ZodOptional<z$1.ZodCustom<ms.StringValue, ms.StringValue>>;
-  }, z$1.z.core.$strip>;
+  }, z$1.core.$strip>;
   otpConfig: z$1.ZodObject<{
     expiresIn: z$1.ZodOptional<z$1.ZodNumber>;
     length: z$1.ZodOptional<z$1.ZodNumber>;
-  }, z$1.z.core.$strip>;
-}, z$1.z.core.$strip>;
+  }, z$1.core.$strip>;
+}, z$1.core.$strip>;
 type CAuthOptions = z$1.infer<typeof CAuthOptionsSchema>;
 //#endregion
 //#region ../core/src/types/dto-schemas.t.d.ts
 declare const LoginSchema: z.ZodUnion<readonly [z.ZodObject<{
   email: z.ZodEmail;
   phoneNumber: z.ZodOptional<z.ZodNever>;
-  password: z.ZodString;
+  password: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
   phoneNumber: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
   email: z.ZodOptional<z.ZodNever>;
-  password: z.ZodString;
+  password: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>]>;
 type LoginSchemaType = z.infer<typeof LoginSchema>;
+declare const OTPCodeUnion: z.ZodUnion<readonly [z.ZodObject<{
+  email: z.ZodEmail;
+  phoneNumber: z.ZodOptional<z.ZodNever>;
+  code: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  phoneNumber: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+  email: z.ZodOptional<z.ZodNever>;
+  code: z.ZodString;
+}, z.core.$strip>]>;
+type OTPLogin = z.infer<typeof OTPCodeUnion>;
+declare const RequestOTPCodeSchema: z.ZodUnion<readonly [z.ZodObject<{
+  otpPurpose: z.ZodEnum<{
+    LOGIN: "LOGIN";
+    RESET_PASSWORD: "RESET_PASSWORD";
+    ACTION: "ACTION";
+  }>;
+  usePassword: z.ZodDefault<z.ZodBoolean>;
+  password: z.ZodOptional<z.ZodString>;
+  phoneNumber: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+  email: z.ZodOptional<z.ZodNever>;
+}, z.core.$strip>, z.ZodObject<{
+  otpPurpose: z.ZodEnum<{
+    LOGIN: "LOGIN";
+    RESET_PASSWORD: "RESET_PASSWORD";
+    ACTION: "ACTION";
+  }>;
+  usePassword: z.ZodDefault<z.ZodBoolean>;
+  password: z.ZodOptional<z.ZodString>;
+  phoneNumber: z.ZodOptional<z.ZodNever>;
+  email: z.ZodString;
+}, z.core.$strip>]>;
+type RequestOTP = z.infer<typeof RequestOTPCodeSchema>;
 declare const RegisterSchema: z.ZodObject<{
   phoneNumber: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
   email: z.ZodOptional<z.ZodEmail>;
   role: z.ZodString;
-  password: z.ZodString;
+  password: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type RegisterSchemaType = z.infer<typeof RegisterSchema>;
 declare const RefreshTokenSchema: z.ZodObject<{
@@ -224,17 +267,12 @@ declare class _CAuth<T extends string[], TContractor extends RoutesContract<any>
     }: ChangePasswordSchemaType) => Promise<Result<unknown>>;
     RequestOTPCode: ({
       ...args
-    }: Omit<LoginSchemaType, "password"> & {
-      password?: string;
-      usePassword?: boolean;
-      otpPurpose: OtpPurpose;
+    }: RequestOTP & {
+      onCode: (code: string) => any;
     }) => Promise<Result<{
       id: string;
-      code: string;
     }>>;
-    LoginWithOTP: (args: Omit<LoginSchemaType, "password"> & {
-      code: string;
-    }) => Promise<Result<{
+    LoginWithOTP: (args: OTPLogin) => Promise<Result<{
       account: Account;
       tokens: Tokens;
     }>>;