@xenterprises/fastify-xconfig 1.0.2 → 1.1.0

package/README.md

@@ -1,29 +1,182 @@
-# __MY_PLUGIN__
+# xConfig - Fastify Configuration Plugin
 
-[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](http://standardjs.com/)  ![CI workflow](__MY_PLUGIN_URL__
-/workflows/CI%20workflow/badge.svg)
+**xConfig** is a Fastify configuration plugin designed for setting up middleware, services, and route handling.
 
-Supports Fastify versions `4.x`
+This plugin provides a comprehensive setup for configuring various services such as Prisma, SendGrid, Twilio, Cloudinary, CORS, rate limiting, authentication, and more within a Fastify instance. It centralizes configuration, allowing for easy customization and scaling.
 
-## Install
-```
-npm i __MY_PLUGIN__
-```
+## Key Features
+
+- Handles CORS, rate-limiting, multipart handling, and error handling out of the box.
+- Integrates with third-party services such as SendGrid, Twilio, Cloudinary, Stripe, and Bugsnag.
+- Provides authentication setup for both Admin and User, with Stack Auth integration.
+- Includes Prisma database connection and gracefully handles disconnecting on server shutdown.
+- Adds health check routes and resource usage monitoring, with environment validation.
+- Customizes route listing and applies various performance and security options.
 
 ## Usage
-Require `__MY_PLUGIN__` and register.
-```js
-const fastify = require('fastify')()
 
-fastify.register(require('__MY_PLUGIN__'), {
-  // put your options here
-})
+This plugin should be registered in your Fastify instance with custom options provided for each service. It ensures proper initialization of services like SendGrid, Twilio, and Prisma.
+
+### Example
+
+```typescript
+import Fastify from "fastify";
+import xConfig from "./path/to/xConfig";
 
-fastify.listen({ port: 3000 })
+const fastify = Fastify();
+fastify.register(xConfig, {
+  prisma: { active: true },
+  sendGrid: { apiKey: "your-sendgrid-api-key" },
+  twilio: {
+    accountSid: "your-account-sid",
+    authToken: "your-auth-token",
+    phoneNumber: "your-twilio-number",
+  },
+  cloudinary: {
+    cloudName: "your-cloud-name",
+    apiKey: "your-api-key",
+    apiSecret: "your-api-secret",
+  },
+  auth: {
+    excludedPaths: ["/public", "/portal/auth/register"],
+    admin: {
+      active: true,
+      stackProjectId: "your-admin-stack-project-id",
+      publishableKey: "your-admin-stack-publishable-key",
+      secretKey: "your-admin-stack-secret-key",
+    },
+    user: {
+      active: true,
+      stackProjectId: "your-user-stack-project-id",
+      publishableKey: "your-user-stack-publishable-key",
+      secretKey: "your-user-stack-secret-key",
+    },
+  },
+  cors: { origin: ["https://your-frontend.com"], credentials: true },
+});
+
+fastify.listen({ port: 3000 });
 ```
 
-## Acknowledgements
+## Parameters
+
+- **prisma**: Prisma Client configuration (optional).
+- **sendGrid**: SendGrid configuration for email services (optional).
+- **twilio**: Twilio configuration for SMS services (optional).
+- **cloudinary**: Cloudinary configuration for media upload services (optional).
+- **auth**: Authentication configuration for Admin and User with Stack Auth integration (optional).
+- **cors**: CORS configuration (optional).
+- **rateLimit**: Rate-limiting options (optional).
+- **multipart**: Multipart handling options for file uploads (optional).
+- **bugsnag**: Bugsnag error reporting configuration (optional).
+- **underPressure**: Under Pressure plugin options for monitoring and throttling under load (optional).
+
+## Authentication
+
+The plugin provides both Admin and User authentication with Stack Auth integration. It handles token verification, protected routes, and authentication endpoints.
+
+### User Authentication
+
+- `/portal/auth/login` - User login endpoint
+- `/portal/auth/me` - Get current user information
+- `/portal/auth/verify` - Verify a user token
+
+### Admin Authentication
+
+- `/admin/auth/login` - Admin login endpoint
+- `/admin/auth/me` - Get current admin information
+- `/admin/auth/verify` - Verify an admin token
+
+### Stack Auth Integration
+
+The plugin integrates with [Stack Auth](https://stack-auth.com) for secure authentication. You'll need to provide:
+
+- `stackProjectId` - Your Stack Auth project ID
+- `publishableKey` - Your Stack Auth publishable client key
+- `secretKey` - Your Stack Auth secret server key
+
+These can be provided via environment variables or in the plugin options.
+
+## Health Check
 
-## License
+The `/health` route provides a health check with details about uptime, memory usage, CPU load, database and Redis status, and environment variable validation.
 
-Licensed under [MIT](./LICENSE).<br/>
+## Services
+
+- **Prisma**: Initializes Prisma Client and decorates the Fastify instance for database queries.
+- **SendGrid**: Provides an email sending service through SendGrid, integrated with the Fastify instance.
+- **Twilio**: Provides SMS sending and phone number validation services.
+- **Cloudinary**: Handles file uploads to Cloudinary and deletion of media files.
+- **Authentication**: Stack Auth integration for secure user and admin authentication.
+
+## Hooks
+
+- **onRequest**: Validates tokens for protected routes.
+- **onClose**: Gracefully disconnects Prisma and other services on server shutdown.
+
+## Error Handling
+
+Enhanced error handling is enabled by default, showing detailed error messages during development. Bugsnag integration is optional for real-time error reporting.
+
+## Route Listing
+
+The plugin prints all routes after registration, color-coded by HTTP method, unless disabled.
+
+## Dependencies
+
+The following dependencies are used for various services and integrations:
+
+- Prisma Client, SendGrid, Twilio, Cloudinary, Fastify CORS, Fastify Rate Limit, Fastify Multipart, Fastify Under Pressure, and Fastify Bugsnag.
+
+## Environment Variables
+
+### Required for Authentication
+
+- `ADMIN_STACK_PROJECT_ID` - Stack Auth project ID for admin authentication
+- `ADMIN_STACK_PUBLISHABLE_CLIENT_KEY` - Stack Auth publishable key for admin authentication
+- `ADMIN_STACK_SECRET_SERVER_KEY` - Stack Auth secret key for admin authentication
+- `USER_STACK_PROJECT_ID` - Stack Auth project ID for user authentication
+- `USER_STACK_PUBLISHABLE_CLIENT_KEY` - Stack Auth publishable key for user authentication
+- `USER_STACK_SECRET_SERVER_KEY` - Stack Auth secret key for user authentication
+
+### Other Environment Variables
+
+- `DATABASE_URL` - Required for Prisma Client
+- `SENDGRID_API_KEY` - Required for SendGrid integration
+- `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER` - Required for Twilio integration
+- `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, `CLOUDINARY_API_SECRET` - Required for Cloudinary integration
+
+## Example Configuration
+
+```javascript
+fastify.register(xConfig, {
+  prisma: { active: true },
+  sendGrid: { apiKey: "SG.your_api_key" },
+  twilio: {
+    accountSid: "ACxxxxxxxxxxxxxxxx",
+    authToken: "your_auth_token",
+    phoneNumber: "+1234567890",
+  },
+  cloudinary: {
+    cloudName: "your-cloud-name",
+    apiKey: "your-api-key",
+    apiSecret: "your-api-secret",
+  },
+  auth: {
+    excludedPaths: ["/public", "/portal/auth/login", "/portal/auth/register"],
+    admin: {
+      active: true,
+      stackProjectId: "your-admin-stack-project-id",
+      publishableKey: "your-admin-stack-publishable-key",
+      secretKey: "your-admin-stack-secret-key",
+    },
+    user: {
+      active: true,
+      stackProjectId: "your-user-stack-project-id",
+      publishableKey: "your-user-stack-publishable-key",
+      secretKey: "your-user-stack-secret-key",
+    },
+  },
+  cors: { origin: ["https://your-frontend.com"], credentials: true },
+});
+```

package/dist/utils/randomUUID.d.ts

@@ -1 +1 @@
-export declare const generateUUID: () => `${string}-${string}-${string}-${string}-${string}`;
+export declare const generateUUID: any;

package/dist/xConfig.d.ts

@@ -1,4 +1,3 @@
-import type { FastifyInstance, FastifyPluginOptions } from "fastify";
-declare function xConfig(fastify: FastifyInstance, options: FastifyPluginOptions): Promise<void>;
+declare function xConfig(fastify: any, options: any): Promise<void>;
 declare const _default: typeof xConfig;
 export default _default;

package/dist/xConfig.js

@@ -1,12 +1,7 @@
+//src/xConfig.js
 import fp from "fastify-plugin";
-import { captureRoutes, printRoutes } from "./utils/colorize";
 async function xConfig(fastify, options) {
-    // Capture routes using the hook
-    const routes = captureRoutes(fastify);
-    // After all plugins are loaded, print the routes
-    fastify.ready(() => {
-        printRoutes(routes);
-    });
+    fastify.decorate("xEcho", () => "Hello from X Enterprises!");
 }
 export default fp(xConfig, {
     name: "xConfig",

package/dist/xConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"xConfig.js","sourceRoot":"","sources":["../src/xConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAEhC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE9D,KAAK,UAAU,OAAO,CACpB,OAAwB,EACxB,OAA6B;IAE7B,gCAAgC;IAChC,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAEtC,iDAAiD;IACjD,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;QACjB,WAAW,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,eAAe,EAAE,CAAC,OAAO,EAAE;IACzB,IAAI,EAAE,SAAS;CAChB,CAAC,CAAC"}
+{"version":3,"file":"xConfig.js","sourceRoot":"","sources":["../src/xConfig.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAChB,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAEhC,KAAK,UAAU,OAAO,CAAC,OAAO,EAAE,OAAO;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,2BAA2B,CAAC,CAAC;AAC/D,CAAC;AAED,eAAe,EAAE,CAAC,OAAO,EAAE;IACzB,IAAI,EAAE,SAAS;CAChB,CAAC,CAAC"}

package/package.json

@@ -1,67 +1,48 @@
 {
   "name": "@xenterprises/fastify-xconfig",
-  "version": "1.0.2",
-  "description": "Fastify configuration plugin for setting up middleware, services, and route handling.",
-  "main": "dist/xConfig.js",
-  "directories": {
-    "test": "test"
-  },
   "type": "module",
+  "version": "1.1.0",
+  "description": "Fastify configuration plugin for setting up middleware, services, and route handling.",
+  "main": "src/xConfig.js",
   "scripts": {
-    "build": "tsc",
-    "prepare": "npm run build",
-    "test": "node dist/xConfig.js",
-    "lint": "standard && npm run lint:typescript",
-    "lint:typescript": "ts-standard",
-    "test:typescript": "tsd",
-    "unit": "node --test"
+    "start": "fastify start -l info server/app.js",
+    "dev": "fastify start -w -l info -P server/app.js",
+    "test": "node --test test/**/*.test.js"
   },
-  "keywords": [],
   "author": "Tim Mushen",
-  "license": "MIT",
-  "types": "dist/xConfig.d.ts",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "c8": "^9.0.0",
+    "fastify": "^4.28.1",
+    "fastify-plugin": "^4.0.0",
+    "fastify-tsconfig": "^2.0.0",
+    "typescript": "^5.6.3"
+  },
   "dependencies": {
-    "@fastify/autoload": "^6.0.1",
+    "@fastify/autoload": "^6.0.2",
     "@fastify/cookie": "^9.4.0",
     "@fastify/cors": "^9.0.1",
-    "@fastify/jwt": "^8.0.1",
     "@fastify/multipart": "^8.3.0",
     "@fastify/rate-limit": "^9.1.0",
     "@fastify/sensible": "^5.6.0",
     "@fastify/under-pressure": "^9.0.1",
-    "@prisma/client": "^5.20.0",
+    "@prisma/client": "^6.3.1",
     "@sendgrid/client": "^8.1.3",
     "@sendgrid/mail": "^8.1.3",
     "bcrypt": "^5.1.1",
+    "check-disk-space": "^3.4.0",
+    "fastify": "^4.28.1",
     "fastify-bugsnag": "^4.1.4",
     "fastify-cli": "^6.2.1",
     "fastify-cloudinary": "^2.0.0",
     "fastify-list-routes": "^1.0.0",
     "fastify-multipart": "^5.4.0",
+    "fastify-plugin": "^4.0.0",
     "fastify-rate-limit": "^5.9.0",
+    "jose": "^6.0.11",
     "stripe": "^16.12.0",
     "twilio": "^5.3.2",
     "uncrypto": "^0.1.3"
-  },
-  "devDependencies": {
-    "@types/node": "^20.17.0",
-    "fastify": "^4.28.1",
-    "fastify-plugin": "^4.0.0",
-    "fastify-tsconfig": "^2.0.0",
-    "standard": "^17.0.0",
-    "ts-standard": "^12.0.1",
-    "tsd": "^0.31.0",
-    "typescript": "^5.6.3"
-  },
-  "tsd": {
-    "directory": "test"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/xenterprises/module-fastify-xconfig.git"
-  },
-  "bugs": {
-    "url": "https://github.com/xenterprises/module-fastify-xconfig/issues"
-  },
-  "homepage": "https://github.com/xenterprises/module-fastify-xconfig#readme"
-}
+  }
+}

package/server/app.js

@@ -0,0 +1,78 @@
+// server/app.js
+import Fastify from 'fastify';
+import xConfig from '../src/xConfig.js';  // Import your plugin correctly
+
+const fastify = Fastify();
+
+
+export default async function (fastify, opts) {
+  fastify.register(xConfig, {
+    professional: false,
+    fancyErrors: true,
+    prisma: {
+      active: false,
+    },
+    bugsnag: {
+      apiKey: process.env.BUGSNAG_API_KEY
+    },
+    rateLimit: {
+      max: process.env.RATE_LIMIT_MAX || 100,
+      timeWindow: process.env.RATE_LIMIT_TIME_WINDOW || '1 minute'
+    },
+    stripe: {
+      active: false,
+      apiKey: process.env.STRIPE_API_KEY
+    },
+    sendGrid: {
+      active: true,
+      apiKey: process.env.SENDGRID_API_KEY,
+      apiKeyEmailValidation: process.env.SENDGRID_API_EMAIL_VALIDATION_KEY,
+      fromEmail: process.env.SENDGRID_FROM_EMAIL || 'ops@getx.io',
+    },
+    twilio: {
+      active: true,
+      accountSid: process.env.TWILIO_ACCOUNT_SID,
+      authToken: process.env.TWILIO_AUTH_TOKEN,
+      phoneNumber: process.env.TWILIO_PHONE_NUMBER
+    },
+    cloudinary: {
+      active: false,
+      cloudName: process.env.CLOUDINARY_CLOUD_NAME,
+      apiKey: process.env.CLOUDINARY_API_KEY,
+      apiSecret: process.env.CLOUDINARY_API_SECRET,
+      basePath: process.env.CLOUDINARY_BASE_PATH || 'basepath'
+    },
+    cors: {
+      active: true,
+      origin: process.env.CORS_ORIGIN || ['http://localhost:3000', 'https://app.bandmate.io'],
+      credentials: true
+    },
+    auth: {
+      excludedPaths: ['/public', '/portal/auth/register'],
+      admin: {
+        active: true,
+        secret: process.env.ADMIN_STACK_PROJECT_ID,
+      },
+      user: {
+        active: true,
+        portalStackProjectId: process.env.STACK_PROJECT_ID,
+        me: {
+          isOnboarded: true
+        },
+        registerEmail: {
+          subject: 'Welcome to Bandmate!',
+          templateId: ''
+        }
+      },
+    },
+    geocode: {
+      active: true,
+      apiKey: process.env.GEOCODIO_API_KEY
+    }
+  });  // Register the default export, which should be a function
+  fastify.get('/', async (request, reply) => {
+    console.log(fastify.xEcho())
+    return { status: fastify.xEcho() }
+  })
+
+};

package/src/auth/admin.js

@@ -0,0 +1,181 @@
+import * as jose from "jose";
+const isProduction = process.env.NODE_ENV === 'production';
+
+export async function setupAdminAuth(fastify, options) {
+  if (options.admin?.active !== false) {
+    // Get configuration
+    const projectId = options.admin.stackProjectId || process.env.ADMIN_STACK_PROJECT_ID;
+    const publishableKey = options.admin.publishableKey || process.env.ADMIN_STACK_PUBLISHABLE_CLIENT_KEY;
+    const secretKey = options.admin.secretKey || process.env.ADMIN_STACK_SECRET_SERVER_KEY;
+
+    if (!projectId) {
+      throw new Error("Stack Auth admin project ID is required");
+    }
+
+    if (!publishableKey || !secretKey) {
+      throw new Error("Stack Auth admin publishable and secret keys are required");
+    }
+
+    const adminExcludedPaths = options.admin.excludedPaths || [
+      "/admin/auth/login",
+      "/admin/auth/logout",
+    ];
+
+    // Base URL for Stack Auth API
+    const stackAuthBaseUrl = `https://api.stack-auth.com/api/v1`;
+    const jwksUrl = `${stackAuthBaseUrl}/projects/${projectId}/.well-known/jwks.json`;
+
+    // Create JWKS for token verification
+    const jwks = jose.createRemoteJWKSet(new URL(jwksUrl));
+
+    // Helper for Stack Auth API headers
+    fastify.decorate('getAdminStackAuthHeaders', function (accessType = "server") {
+      const headers = {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+        'X-Stack-Access-Type': accessType,
+        'X-Stack-Project-Id': projectId,
+      };
+
+      if (accessType === "client") {
+        headers['X-Stack-Publishable-Client-Key'] = publishableKey;
+      } else if (accessType === "server") {
+        headers['X-Stack-Secret-Server-Key'] = secretKey;
+      }
+
+      return headers;
+    });
+
+    // JWT verification helper
+    fastify.decorate('verifyAdminStackJWT', async function (accessToken) {
+      try {
+        // Add validation to ensure accessToken is a valid string
+        if (!accessToken || typeof accessToken !== 'string') {
+          fastify.log.error('Invalid admin token format: token must be a non-empty string');
+          return null;
+        }
+
+        const { payload } = await jose.jwtVerify(accessToken, jwks);
+
+        // Verify the payload has expected properties
+        if (!payload || !payload.sub) {
+          fastify.log.error('Invalid admin token payload: missing required claims');
+          return null;
+        }
+
+        return payload;
+      } catch (error) {
+        fastify.log.error(error);
+        return null;
+      }
+    });
+
+    // Admin authentication hook
+    fastify.addHook("onRequest", async (request, reply) => {
+      const url = request.url;
+
+      // Skip authentication for excluded paths
+      if (adminExcludedPaths.some((path) => url.startsWith(path))) {
+        return;
+      }
+
+      if (url.startsWith("/admin")) {
+        try {
+          // Get token from header
+          const authHeader = request.headers.authorization;
+          if (!authHeader || !authHeader.startsWith("Bearer ")) {
+            return reply.code(401).send({ error: "Admin access token required" });
+          }
+
+          // Verify token
+          const token = authHeader.slice(7);
+          const payload = await fastify.verifyAdminStackJWT(token);
+
+          if (!payload) {
+            return reply.code(401).send({ error: "Invalid admin token" });
+          }
+
+          // Set admin info on request
+          request.admin = payload;
+          request.adminAuth = { id: payload.sub };
+        } catch (err) {
+          return reply.code(401).send({ error: "Admin authentication failed" });
+        }
+      }
+    });
+
+    // Admin login endpoint
+    fastify.post("/admin/auth/login", async (req, reply) => {
+      try {
+        const { email, password } = req.body;
+
+        if (!email || !password) {
+          return reply.code(400).send({ error: "Email and password required" });
+        }
+
+        // Call Stack Auth API for password sign-in
+        const response = await fetch(
+          `${stackAuthBaseUrl}/auth/password/sign-in`,
+          {
+            method: 'POST',
+            headers: fastify.getAdminStackAuthHeaders("server"),
+            body: JSON.stringify({ email, password })
+          }
+        );
+
+        const data = await response.json().catch(() => ({}));
+
+        if (!response.ok) {
+          return reply.code(response.status || 400).send({
+            error: data.message || "Authentication failed"
+          });
+        }
+
+        // Check if we have the expected response properties
+        if (!data.access_token || !data.refresh_token || !data.user_id) {
+          return reply.code(500).send({ error: "Invalid response from authentication service" });
+        }
+
+        // Verify token
+        const payload = await fastify.verifyAdminStackJWT(data.access_token);
+        if (!payload) {
+          return reply.code(401).send({ error: "Invalid token received" });
+        }
+
+        reply.send({
+          accessToken: data.access_token,
+          refreshToken: data.refresh_token,
+          admin: payload,
+          adminId: data.user_id
+        });
+      } catch (err) {
+        fastify.log.error(err);
+        reply.code(500).send({ error: "Internal server error" });
+      }
+    });
+
+    // Admin info endpoint
+    fastify.get("/admin/auth/me", async (req, reply) => {
+      reply.send(req.admin || { authenticated: false });
+    });
+
+    // Token verification endpoint
+    fastify.post("/admin/auth/verify", async (req, reply) => {
+      const { token } = req.body;
+
+      if (!token) {
+        return reply.code(400).send({ error: "Token required" });
+      }
+
+      const payload = await fastify.verifyAdminStackJWT(token);
+
+      if (!payload) {
+        return reply.code(401).send({ valid: false });
+      }
+
+      reply.send({ valid: true, admin: payload });
+    });
+
+    console.info("   ✅ Auth Admin Enabled");
+  }
+}