@tekcify/auth-backend 1.0.0

package/README.md

@@ -0,0 +1,495 @@
+# @tekcify/auth-backend
+
+Backend authentication helpers for Tekcify Auth. Provides middleware, guards, and utilities for validating JWT tokens and protecting API routes in NestJS and Express applications.
+
+## Installation
+
+```bash
+npm install @tekcify/auth-backend
+# or
+pnpm add @tekcify/auth-backend
+# or
+yarn add @tekcify/auth-backend
+```
+
+## Features
+
+- ✅ **NestJS Support** - Guards and decorators for NestJS applications
+- ✅ **Express Support** - Middleware for Express applications
+- ✅ **Token Verification** - JWT token validation with HMAC/RS256
+- ✅ **User Info Fetching** - Helper to get user information from auth server
+- ✅ **TypeScript Support** - Full type definitions included
+
+## Quick Start
+
+### Prerequisites
+
+You need the JWT access secret from your Tekcify Auth server. This should match the `JWT_ACCESS_SECRET` environment variable used by the auth server.
+
+```env
+JWT_ACCESS_SECRET=your-jwt-access-secret-here
+AUTH_SERVER_URL=http://localhost:7001
+```
+
+## NestJS Integration
+
+### Step 1: Install Dependencies
+
+```bash
+pnpm add @tekcify/auth-backend @nestjs/common @nestjs/core
+```
+
+### Step 2: Create and Configure the Guard
+
+Create a guard provider in your module:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { JwtAuthGuard } from '@tekcify/auth-backend/nestjs';
+
+@Module({
+  providers: [
+    {
+      provide: APP_GUARD,
+      useFactory: () => {
+        return new JwtAuthGuard({
+          secret: process.env.JWT_ACCESS_SECRET!,
+          issuer: 'tekcify-auth',
+          audience: 'tekcify-api',
+          getUserInfo: async (userId: string) => {
+            // Optional: Fetch user info from your database
+            // This is called only if getUserInfo is provided
+            const user = await userRepository.findById(userId);
+            return user ? { email: user.email } : null;
+          },
+        });
+      },
+    },
+  ],
+})
+export class AppModule {}
+```
+
+### Step 3: Use the Guard in Controllers
+
+```typescript
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { JwtAuthGuard, CurrentUser } from '@tekcify/auth-backend/nestjs';
+import type { UserPayload } from '@tekcify/auth-backend/nestjs';
+
+@Controller('api')
+@UseGuards(JwtAuthGuard) // Protect entire controller
+export class ApiController {
+  @Get('profile')
+  getProfile(@CurrentUser() user: UserPayload) {
+    return {
+      userId: user.userId,
+      email: user.email,
+      scopes: user.scopes,
+    };
+  }
+
+  @Get('public')
+  // This route is still protected by the controller-level guard
+  getPublic() {
+    return { message: 'Public endpoint' };
+  }
+}
+```
+
+### Step 4: Per-Route Guard Usage
+
+You can also use the guard on individual routes:
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { JwtAuthGuard, CurrentUser } from '@tekcify/auth-backend/nestjs';
+
+@Controller('api')
+export class ApiController {
+  @Get('public')
+  getPublic() {
+    return { message: 'Public endpoint' };
+  }
+
+  @Get('protected')
+  @UseGuards(new JwtAuthGuard({
+    secret: process.env.JWT_ACCESS_SECRET!,
+    issuer: 'tekcify-auth',
+    audience: 'tekcify-api',
+  }))
+  getProtected(@CurrentUser() user: UserPayload) {
+    return {
+      message: 'Protected endpoint',
+      user: user.userId,
+    };
+  }
+}
+```
+
+### Step 5: Access User Information
+
+The `@CurrentUser()` decorator provides access to the authenticated user:
+
+```typescript
+@Get('me')
+@UseGuards(JwtAuthGuard)
+getCurrentUser(@CurrentUser() user: UserPayload) {
+  return {
+    userId: user.userId,
+    email: user.email,
+    scopes: user.scopes || [],
+  };
+}
+```
+
+## Express Integration
+
+### Step 1: Install Dependencies
+
+```bash
+pnpm add @tekcify/auth-backend express
+```
+
+### Step 2: Create Auth Middleware
+
+```typescript
+import express from 'express';
+import { createAuthMiddleware } from '@tekcify/auth-backend/express';
+
+const app = express();
+
+const authMiddleware = createAuthMiddleware({
+  secret: process.env.JWT_ACCESS_SECRET!,
+  issuer: 'tekcify-auth',
+  audience: 'tekcify-api',
+  getUserInfo: async (userId: string) => {
+    // Optional: Fetch user info from your database
+    const user = await userRepository.findById(userId);
+    return user ? { email: user.email } : null;
+  },
+});
+
+app.use(express.json());
+
+// Apply middleware to all /api routes
+app.use('/api', authMiddleware);
+
+app.get('/api/profile', (req, res) => {
+  // req.user is now available
+  res.json({
+    userId: req.user!.userId,
+    email: req.user!.email,
+    scopes: req.user!.scopes,
+  });
+});
+```
+
+### Step 3: Route-Level Middleware
+
+You can also apply middleware to specific routes:
+
+```typescript
+app.get('/api/public', (req, res) => {
+  res.json({ message: 'Public endpoint' });
+});
+
+app.get('/api/protected', authMiddleware, (req, res) => {
+  res.json({
+    message: 'Protected endpoint',
+    user: req.user!.userId,
+  });
+});
+```
+
+### Step 4: TypeScript Support
+
+The middleware extends Express's `Request` type:
+
+```typescript
+import type { Request, Response } from 'express';
+
+app.get('/api/user', authMiddleware, (req: Request, res: Response) => {
+  // TypeScript knows req.user exists
+  const userId = req.user!.userId;
+  const email = req.user!.email;
+  
+  res.json({ userId, email });
+});
+```
+
+## Token Verification
+
+For cases where you need to verify tokens directly (e.g., in background jobs, WebSocket connections):
+
+```typescript
+import { verifyAccessToken } from '@tekcify/auth-backend';
+
+const token = req.headers.authorization?.replace('Bearer ', '');
+
+if (!token) {
+  throw new Error('No token provided');
+}
+
+const result = verifyAccessToken(token, {
+  secret: process.env.JWT_ACCESS_SECRET!,
+  issuer: 'tekcify-auth',
+  audience: 'tekcify-api',
+});
+
+if (!result.valid) {
+  throw new Error('Invalid token');
+}
+
+console.log('User ID:', result.payload.sub);
+console.log('Scopes:', result.payload.scopes);
+```
+
+## Token Introspection
+
+For cases where you can't verify tokens directly (e.g., different signing keys, remote verification):
+
+```typescript
+import { introspectToken } from '@tekcify/auth-core-client';
+
+const token = req.headers.authorization?.replace('Bearer ', '');
+
+const result = await introspectToken(process.env.AUTH_SERVER_URL!, {
+  token: token!,
+  clientId: process.env.CLIENT_ID,
+  clientSecret: process.env.CLIENT_SECRET,
+});
+
+if (result.active) {
+  console.log('Token is valid');
+  console.log('User ID:', result.sub);
+  console.log('Scopes:', result.scope);
+} else {
+  throw new Error('Token is invalid or expired');
+}
+```
+
+## Getting User Information
+
+Fetch user information from the auth server:
+
+```typescript
+import { fetchUserInfo } from '@tekcify/auth-backend';
+
+const userInfo = await fetchUserInfo(
+  process.env.AUTH_SERVER_URL!,
+  accessToken
+);
+
+console.log('Email:', userInfo.email);
+console.log('Name:', userInfo.name);
+console.log('Verified:', userInfo.email_verified);
+```
+
+## Complete NestJS Example
+
+```typescript
+import { Module, Controller, Get, UseGuards } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { JwtAuthGuard, CurrentUser } from '@tekcify/auth-backend/nestjs';
+import type { UserPayload } from '@tekcify/auth-backend/nestjs';
+
+@Module({
+  providers: [
+    {
+      provide: APP_GUARD,
+      useFactory: () => {
+        return new JwtAuthGuard({
+          secret: process.env.JWT_ACCESS_SECRET!,
+          issuer: 'tekcify-auth',
+          audience: 'tekcify-api',
+        });
+      },
+    },
+  ],
+})
+export class AppModule {}
+
+@Controller('api')
+@UseGuards(JwtAuthGuard)
+export class ApiController {
+  @Get('profile')
+  getProfile(@CurrentUser() user: UserPayload) {
+    return {
+      userId: user.userId,
+      email: user.email,
+      scopes: user.scopes || [],
+    };
+  }
+
+  @Get('posts')
+  async getPosts(@CurrentUser() user: UserPayload) {
+    // Only return posts for the authenticated user
+    return await postRepository.findByUserId(user.userId);
+  }
+}
+```
+
+## Complete Express Example
+
+```typescript
+import express from 'express';
+import { createAuthMiddleware } from '@tekcify/auth-backend/express';
+
+const app = express();
+app.use(express.json());
+
+const authMiddleware = createAuthMiddleware({
+  secret: process.env.JWT_ACCESS_SECRET!,
+  issuer: 'tekcify-auth',
+  audience: 'tekcify-api',
+});
+
+// Public routes
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok' });
+});
+
+// Protected routes
+app.use('/api', authMiddleware);
+
+app.get('/api/profile', (req, res) => {
+  res.json({
+    userId: req.user!.userId,
+    email: req.user!.email,
+    scopes: req.user!.scopes,
+  });
+});
+
+app.get('/api/data', async (req, res) => {
+  const data = await fetchDataForUser(req.user!.userId);
+  res.json(data);
+});
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+## API Reference
+
+### NestJS
+
+#### `JwtAuthGuard`
+
+Guard class for protecting routes.
+
+```typescript
+new JwtAuthGuard({
+  secret: string;                    // JWT secret
+  issuer?: string;                  // Token issuer (default: 'tekcify-auth')
+  audience?: string;                // Token audience (default: 'tekcify-api')
+  getUserInfo?: (userId: string) => Promise<{ email: string } | null>;
+})
+```
+
+#### `@CurrentUser()`
+
+Parameter decorator to inject the current user.
+
+```typescript
+@CurrentUser() user: UserPayload
+```
+
+### Express
+
+#### `createAuthMiddleware(options)`
+
+Creates Express middleware for authentication.
+
+```typescript
+createAuthMiddleware({
+  secret: string;
+  issuer?: string;
+  audience?: string;
+  getUserInfo?: (userId: string) => Promise<{ email: string } | null>;
+})
+```
+
+### Utilities
+
+#### `verifyAccessToken(token, options)`
+
+Verifies a JWT access token.
+
+```typescript
+verifyAccessToken(token: string, {
+  secret: string;
+  issuer?: string;
+  audience?: string;
+}): VerifiedToken
+```
+
+#### `fetchUserInfo(authServerUrl, accessToken)`
+
+Fetches user information from the auth server.
+
+```typescript
+fetchUserInfo(
+  authServerUrl: string,
+  accessToken: string
+): Promise<UserInfo>
+```
+
+### Types
+
+```typescript
+interface UserPayload {
+  userId: string;
+  email: string;
+  scopes?: string[];
+}
+
+interface VerifiedToken {
+  payload: TokenPayload;
+  valid: boolean;
+}
+```
+
+## Error Handling
+
+All middleware and guards throw `UnauthorizedException` (NestJS) or return 401 status (Express) when:
+
+- Token is missing
+- Token is invalid
+- Token is expired
+- User not found (if `getUserInfo` is provided)
+
+## Security Best Practices
+
+1. **Never expose JWT secrets** - Keep secrets in environment variables
+2. **Use HTTPS in production** - Always use secure connections
+3. **Validate token issuer and audience** - Prevents token reuse across services
+4. **Implement rate limiting** - Protect against brute force attacks
+5. **Log authentication failures** - Monitor for suspicious activity
+6. **Use short-lived tokens** - Refresh tokens regularly
+
+## Troubleshooting
+
+### "Invalid token" errors
+
+- Verify `JWT_ACCESS_SECRET` matches the auth server
+- Check token hasn't expired
+- Ensure issuer and audience match
+
+### "User not found" errors
+
+- Verify `getUserInfo` function returns correct format
+- Check database connection
+- Ensure user exists in your system
+
+### Token verification fails
+
+- Verify token format (should start with "Bearer ")
+- Check token hasn't been tampered with
+- Ensure token type is "access" (not "refresh")
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@tekcify/auth-backend",
+  "version": "1.0.0",
+  "description": "Backend authentication helpers for Tekcify Auth. Provides middleware, guards, and utilities for validating JWT tokens and protecting API routes in NestJS and Express applications.",
+  "author": "Tekcify",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tekcify/auth.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tekcify/auth/issues"
+  },
+  "homepage": "https://github.com/tekcify/auth#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./nestjs": {
+      "types": "./dist/nestjs/index.d.ts",
+      "import": "./dist/nestjs/index.js",
+      "require": "./dist/nestjs/index.js"
+    },
+    "./express": {
+      "types": "./dist/express/index.d.ts",
+      "import": "./dist/express/index.js",
+      "require": "./dist/express/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "lint": "eslint \"src/**/*.ts\" --max-warnings=0",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "nestjs",
+    "express",
+    "oauth",
+    "jwt",
+    "auth"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@tekcify/auth-core-client": "^1.0.0",
+    "jsonwebtoken": "^9.0.2"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/core": "^11.0.1",
+    "@types/express": "^5.0.0",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.15"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0"
+  }
+}
+

package/src/__tests__/verify.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import jwt from 'jsonwebtoken';
+import { verifyAccessToken } from '../verify';
+
+describe('verifyAccessToken', () => {
+  const secret = 'test-secret';
+  const issuer = 'tekcify-auth';
+  const audience = 'tekcify-api';
+
+  it('should verify a valid access token', () => {
+    const payload = {
+      sub: 'user-123',
+      type: 'access',
+      scopes: ['read:profile'],
+    };
+
+    const token = jwt.sign(payload, secret, {
+      issuer,
+      audience,
+      expiresIn: '1h',
+    });
+
+    const result = verifyAccessToken(token, { secret, issuer, audience });
+
+    expect(result.valid).toBe(true);
+    expect(result.payload.sub).toBe('user-123');
+    expect(result.payload.type).toBe('access');
+  });
+
+  it('should reject a refresh token', () => {
+    const payload = {
+      sub: 'user-123',
+      type: 'refresh',
+    };
+
+    const token = jwt.sign(payload, secret, {
+      issuer,
+      audience,
+      expiresIn: '7d',
+    });
+
+    const result = verifyAccessToken(token, { secret, issuer, audience });
+
+    expect(result.valid).toBe(false);
+  });
+
+  it('should reject an expired token', () => {
+    const payload = {
+      sub: 'user-123',
+      type: 'access',
+    };
+
+    const token = jwt.sign(payload, secret, {
+      issuer,
+      audience,
+      expiresIn: '-1h',
+    });
+
+    const result = verifyAccessToken(token, { secret, issuer, audience });
+
+    expect(result.valid).toBe(false);
+  });
+
+  it('should reject a token with wrong secret', () => {
+    const payload = {
+      sub: 'user-123',
+      type: 'access',
+    };
+
+    const token = jwt.sign(payload, 'wrong-secret', {
+      issuer,
+      audience,
+      expiresIn: '1h',
+    });
+
+    const result = verifyAccessToken(token, { secret, issuer, audience });
+
+    expect(result.valid).toBe(false);
+  });
+});

package/src/express/index.ts

@@ -0,0 +1,2 @@
+export { createAuthMiddleware } from './middleware';
+export type { ExpressAuthOptions } from './middleware';

package/src/express/middleware.ts

@@ -0,0 +1,61 @@
+import type { Request, Response, NextFunction } from 'express';
+import { verifyAccessToken } from '../verify';
+import type { VerifyTokenOptions, UserPayload } from '../types';
+
+export interface ExpressAuthOptions extends VerifyTokenOptions {
+  getUserInfo?: (userId: string) => Promise<{ email: string } | null>;
+}
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Request {
+      user?: UserPayload;
+    }
+  }
+}
+
+export function createAuthMiddleware(options: ExpressAuthOptions) {
+  return async (
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ): Promise<void> => {
+    const authHeader = req.headers.authorization as string | undefined;
+
+    if (!authHeader?.startsWith('Bearer ')) {
+      res
+        .status(401)
+        .json({ message: 'Missing or invalid authorization header' });
+      return;
+    }
+
+    const token = authHeader.substring(7);
+    const verified = verifyAccessToken(token, options);
+
+    if (!verified.valid) {
+      res.status(401).json({ message: 'Invalid or expired token' });
+      return;
+    }
+
+    let email = '';
+    if (options.getUserInfo) {
+      const userInfo = await options.getUserInfo(verified.payload.sub);
+      if (!userInfo) {
+        res.status(401).json({ message: 'User not found' });
+        return;
+      }
+      email = userInfo.email;
+    }
+
+    req.user = {
+      userId: verified.payload.sub,
+      email,
+      scopes: Array.isArray(verified.payload.scopes)
+        ? verified.payload.scopes
+        : [],
+    };
+
+    next();
+  };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './verify';
+export * from './userinfo';
+export * from './nestjs';
+export * from './express';