revocation endpoints

Author: talktosam2003

docs/swagger.yaml

@@ -572,6 +572,95 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+  /api/auth/sessions:
+    get:
+      summary: List active sessions
+      description: |
+        Returns all active session records for the authenticated user (one per device/login).
+        Sessions are ordered newest-first.
+      tags:
+        - Auth
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Session list retrieved successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  message:
+                    type: string
+                    example: Sessions retrieved
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Session'
+        '401':
+          description: Missing or invalid authorization token
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/auth/sessions/{jti}:
+    delete:
+      summary: Revoke a session
+      description: |
+        Blocklists the token identified by `jti` in Redis and removes the session record.
+        The token will be rejected immediately by `requireAuth` on subsequent requests.
+
+        - Returns **403** if the session belongs to a different user (cross-user revocation).
+        - Returns **404** if no session with that `jti` exists.
+      tags:
+        - Auth
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: path
+          name: jti
+          required: true
+          schema:
+            type: string
+          description: The JWT ID (`jti` claim) of the session to revoke
+      responses:
+        '200':
+          description: Session revoked successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  message:
+                    type: string
+                    example: Session revoked successfully
+                  data:
+                    nullable: true
+                    example: null
+        '401':
+          description: Missing or invalid authorization token
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '403':
+          description: Forbidden — cannot revoke another user's session
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Session not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
   /api/auth/signup:
     post:
       summary: Register a new user
@@ -4214,6 +4303,33 @@ paths:
 
 components:
   schemas:
+    Session:
+      type: object
+      description: A per-device session record created on login or signup.
+      properties:
+        _id:
+          type: string
+          description: Session MongoDB ObjectId
+        userId:
+          type: string
+          description: Owner user ObjectId
+        jti:
+          type: string
+          description: JWT ID (UUID v4) — use this as the path param for DELETE /api/auth/sessions/:jti
+        ip:
+          type: string
+          description: Client IP address at time of login (optional)
+        userAgent:
+          type: string
+          description: HTTP User-Agent string at time of login (optional)
+        createdAt:
+          type: string
+          format: date-time
+          description: When the session was created (ISO 8601)
+        lastUsedAt:
+          type: string
+          format: date-time
+          description: When the session was last active (ISO 8601)
     TelemetryUpdateEvent:
       type: object
       description: Real-time telemetry reading from an IoT sensor.

src/modules/auth/auth.controller.ts

@@ -21,7 +21,11 @@ import { sendResponse } from '../../shared/http/sendResponse.js';
  * @throws {AppError} 409 EMAIL_TAKEN — when the email is already registered.
  */
 export const signupController: RequestHandler = async (req, res) => {
-  const result = await signup(req.body);
+  const ctx = {
+    ip: req.ip,
+    userAgent: req.headers['user-agent'],
+  };
+  const result = await signup(req.body, ctx);
   sendResponse(res, 201, true, 'Account created successfully', result);
 };
 
@@ -34,7 +38,11 @@ export const signupController: RequestHandler = async (req, res) => {
  * @throws {AppError} 401 INVALID_CREDENTIALS — when email or password is incorrect.
  */
 export const loginController: RequestHandler = async (req, res) => {
-  const result = await login(req.body);
+  const ctx = {
+    ip: req.ip,
+    userAgent: req.headers['user-agent'],
+  };
+  const result = await login(req.body, ctx);
   sendResponse(res, 200, true, 'Login successful', result);
 };
 

src/modules/auth/auth.routes.ts

@@ -31,6 +31,8 @@ import {
   CreateApiKeyBodySchema,
   OrganizationIdParamSchema,
 } from './apiKey.validation.js';
+import { listSessionsController, revokeSessionController } from './session.controller.js';
+import { SessionJtiParamSchema } from './session.validation.js';
 
 export const authRouter = Router();
 
@@ -91,3 +93,12 @@ authRouter.delete(
   validateRequest({ params: ApiKeyIdParamSchema }),
   asyncHandler(revokeApiKeyController)
 );
+
+// Session management routes (protected by JWT auth)
+authRouter.get('/sessions', asyncHandler(requireAuth), asyncHandler(listSessionsController));
+authRouter.delete(
+  '/sessions/:jti',
+  asyncHandler(requireAuth),
+  validateRequest({ params: SessionJtiParamSchema }),
+  asyncHandler(revokeSessionController)
+);

src/modules/auth/auth.service.ts

@@ -7,7 +7,8 @@ import { config } from '../../config/index.js';
 import { OrganizationType } from '../../shared/constants/index.js';
 import { UserModel, OrganizationModel, UserRole } from '../users/users.model.js';
 import { blockToken, isTokenBlocked } from '../../infra/redis/tokenBlocklist.js';
-import type { SignupInput, LoginInput, RegisterCompanyInput } from './auth.validation.js';
+import { createSession } from './session.service.js';
+import type { SignupInput, LoginInput } from './auth.validation.js';
 import { logger } from '../../shared/logger/logger.js';
 import { sendEmail, resetPasswordEmailHtml } from '../../services/email.service.js';
 
@@ -23,22 +24,23 @@ export interface TokenPayload {
 // SECURITY: [Token Lifecycle Compromise] — This prevents long-term token abuse by enforcing a 7-day Time-To-Live (TTL) limit on authentication tokens, bounding the window of opportunity for stolen credentials.
 const TOKEN_TTL_SECONDS = 7 * 24 * 60 * 60; // 7 days
 
-function generateToken(payload: Omit<TokenPayload, 'jti'>): string {
+function generateToken(payload: Omit<TokenPayload, 'jti'>): { token: string; jti: string } {
   // SECURITY: [Token Replay Attack] — This prevents reuse of old or intercepted JWTs by attaching a cryptographically random, unique JWT ID (jti) to each token, allowing the middleware to track and revoke individual sessions via Redis.
   const jti = randomUUID();
-  return jwt.sign({ ...payload, jti }, env.JWT_SECRET, { expiresIn: TOKEN_TTL_SECONDS });
+  const token = jwt.sign({ ...payload, jti }, env.JWT_SECRET, { expiresIn: TOKEN_TTL_SECONDS });
+  return { token, jti };
 }
 
 /**
  * Determines the safe default role for public signup.
- * 
+ *
  * SECURITY: Always returns VIEWER role to prevent privilege escalation.
  * No exceptions or role overrides permitted for unauthenticated signup.
  * Admin/privileged roles are assigned exclusively through:
  * - POST /api/users (ADMIN only)
  * - POST /api/users/team (ADMIN only)
  * - Invitation acceptance flow (role determined by inviter)
- * 
+ *
  * @param {string} _email - Email (unused - role is same for all users)
  * @returns {UserRole} Always returns VIEWER
  */
@@ -54,20 +56,26 @@ function derivePersona(role: string, organizationType?: OrganizationType): 'comp
   return 'company';
 }
 
+export interface RequestContext {
+  ip?: string;
+  userAgent?: string;
+}
+
 /**
  * Registers a new user and returns an auth token.
- * 
+ *
  * SECURITY CONTROLS:
  * - Public signup ALWAYS assigns VIEWER role (determined via determineUserRole)
  * - No role parameter accepted in request body (enforced by SignupBodySchema)
  * - Admin/privileged roles only assignable via authenticated admin endpoints
  * - Prevents privilege escalation (CWE-284) by unauthenticated users
- * 
+ *
  * @param {SignupInput} input - User signup input payload.
+ * @param {RequestContext} [ctx] - Optional request context for session tracking.
  * @returns {Promise<{user: {id: string; email: string; name: string; role: string}; token: string}>} The created user and JWT token.
  * @throws {AppError} When the email is already in use.
  */
-export async function signup(input: SignupInput) {
+export async function signup(input: SignupInput, ctx?: RequestContext) {
   const existing = await UserModel.findOne({ email: input.email });
   if (existing) {
     throw new AppError(409, 'Email already in use', 'EMAIL_TAKEN');
@@ -90,14 +98,16 @@ export async function signup(input: SignupInput) {
     organizationType = organization?.type;
   }
 
-  const token = generateToken({
+  const { token, jti } = generateToken({
     userId: user._id.toString(),
     role: user.role as string,
     persona: derivePersona(user.role as string, organizationType),
     organizationId: user.organizationId?.toString(),
     organizationType,
   });
 
+  await createSession({ userId: user._id.toString(), jti, ip: ctx?.ip, userAgent: ctx?.userAgent });
+
   return {
     user: {
       id: user._id,
@@ -112,10 +122,11 @@ export async function signup(input: SignupInput) {
 /**
  * Authenticates a user and returns a JWT.
  * @param {LoginInput} input - User login credentials.
+ * @param {RequestContext} [ctx] - Optional request context for session tracking.
  * @returns {Promise<{user: {id: string; email: string; name: string; role: string}; token: string}>} Authenticated user data and token.
  * @throws {AppError} When credentials are invalid.
  */
-export async function login(input: LoginInput) {
+export async function login(input: LoginInput, ctx?: RequestContext) {
   const user = await UserModel.findOne({ email: input.email });
   if (!user) {
     throw new AppError(401, 'Invalid credentials', 'INVALID_CREDENTIALS');
@@ -132,14 +143,16 @@ export async function login(input: LoginInput) {
     organizationType = organization?.type;
   }
 
-  const token = generateToken({
+  const { token, jti } = generateToken({
     userId: user._id.toString(),
     role: user.role as string,
     persona: derivePersona(user.role as string, organizationType),
     organizationId: user.organizationId?.toString(),
     organizationType,
   });
 
+  await createSession({ userId: user._id.toString(), jti, ip: ctx?.ip, userAgent: ctx?.userAgent });
+
   return {
     user: {
       id: user._id,
@@ -217,7 +230,7 @@ export async function refreshToken(token: string): Promise<{ token: string; expi
     organizationType,
   });
 
-  return { token: newToken, expiresIn: TOKEN_TTL_SECONDS };
+  return { token: newToken.token, expiresIn: TOKEN_TTL_SECONDS };
 }
 
 /**
@@ -313,7 +326,7 @@ export async function resetPassword(token: string, newPassword: string): Promise
 /**
  * Self-service company registration: creates both an Organization (type: ENTERPRISE)
  * and the first admin user in a single atomic operation.
- * 
+ *
  * @param {RegisterCompanyInput} input - Company and admin user details.
  * @returns {Promise<{user: {id: string; email: string; name: string; role: string}; token: string}>} The created admin user and JWT token.
  * @throws {AppError} 409 if email or organization name already exists.
@@ -384,7 +397,7 @@ export async function registerCompany(input: {
     const createdUser = user[0];
 
     // Generate JWT token with organization context
-    const token = generateToken({
+    const { token } = generateToken({
       userId: createdUser._id.toString(),
       role: UserRole.ADMIN,
       persona: derivePersona(UserRole.ADMIN, OrganizationType.ENTERPRISE),

src/modules/auth/session.controller.ts

@@ -0,0 +1,47 @@
+import type { RequestHandler } from 'express';
+import { listSessions, revokeSession } from './session.service.js';
+import { sendResponse } from '../../shared/http/sendResponse.js';
+import { AppError, ErrorCodes } from '../../shared/http/errors.js';
+
+/**
+ * GET /api/auth/sessions
+ *
+ * Returns all active sessions for the authenticated user.
+ *
+ * @returns HTTP 200 with envelope `{ success, message, data: Session[] }`.
+ * @throws {AppError} 401 ERR_AUTH_INVALID — when JWT auth fails.
+ */
+export const listSessionsController: RequestHandler = async (req, res) => {
+  const userId = req.user?.userId;
+
+  if (!userId) {
+    throw new AppError(401, 'Unauthorized', ErrorCodes.UNAUTHORIZED);
+  }
+
+  const sessions = await listSessions(userId);
+  sendResponse(res, 200, true, 'Sessions retrieved', sessions);
+};
+
+/**
+ * DELETE /api/auth/sessions/:jti
+ *
+ * Revokes a session by JTI — blocklists the token and removes the session record.
+ * Cross-user revocation returns 403.
+ *
+ * @param req.params.jti - The JWT ID of the session to revoke.
+ * @returns HTTP 200 with envelope `{ success, message, data: null }`.
+ * @throws {AppError} 401 ERR_AUTH_INVALID — when JWT auth fails.
+ * @throws {AppError} 403 ERR_PERMISSION_DENIED — when revoking another user's session.
+ * @throws {AppError} 404 ERR_NOT_FOUND — when no session with that JTI exists.
+ */
+export const revokeSessionController: RequestHandler = async (req, res) => {
+  const userId = req.user?.userId;
+
+  if (!userId) {
+    throw new AppError(401, 'Unauthorized', ErrorCodes.UNAUTHORIZED);
+  }
+
+  const { jti } = req.params;
+  await revokeSession(userId, jti);
+  sendResponse(res, 200, true, 'Session revoked successfully', null);
+};

src/modules/auth/session.model.ts

@@ -0,0 +1,29 @@
+import mongoose from 'mongoose';
+import { isoDatePlugin } from '../../shared/plugins/isoDatePlugin.js';
+
+export interface ISession {
+  _id: string;
+  userId: mongoose.Types.ObjectId | string;
+  jti: string;
+  ip?: string;
+  userAgent?: string;
+  createdAt: Date;
+  lastUsedAt: Date;
+}
+
+const SessionSchema = new mongoose.Schema(
+  {
+    userId: { type: mongoose.Schema.Types.ObjectId, ref: 'User', required: true, index: true },
+    jti: { type: String, required: true, unique: true, index: true },
+    ip: { type: String, required: false },
+    userAgent: { type: String, required: false },
+    lastUsedAt: { type: Date, default: () => new Date() },
+  },
+  { timestamps: true }
+);
+
+SessionSchema.plugin(isoDatePlugin);
+
+SessionSchema.index({ userId: 1, createdAt: -1 });
+
+export const SessionModel = mongoose.model<ISession>('Session', SessionSchema);