Merge pull request #217 from Merit-Systems/rfs/sessions

AppSessions for keeping track of multi session per user

Author: zdql

echo-control/prisma/migrations/20250827002614_app_sessions/migration.sql

@@ -0,0 +1,43 @@
+-- AlterTable
+ALTER TABLE "refresh_tokens" ADD COLUMN     "sessionId" UUID;
+
+-- CreateTable
+CREATE TABLE "app_sessions" (
+    "id" UUID NOT NULL,
+    "userId" UUID NOT NULL,
+    "echoAppId" UUID NOT NULL,
+    "deviceName" TEXT,
+    "userAgent" TEXT,
+    "ipAddress" TEXT,
+    "createdAt" TIMESTAMPTZ(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMPTZ(6) NOT NULL,
+    "lastSeenAt" TIMESTAMPTZ(6),
+    "revokedAt" TIMESTAMPTZ(6),
+    "isArchived" BOOLEAN NOT NULL DEFAULT false,
+
+    CONSTRAINT "app_sessions_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "app_sessions_userId_echoAppId_idx" ON "app_sessions"("userId", "echoAppId");
+
+-- CreateIndex
+CREATE INDEX "app_sessions_echoAppId_isArchived_idx" ON "app_sessions"("echoAppId", "isArchived");
+
+-- CreateIndex
+CREATE INDEX "refresh_tokens_userId_echoAppId_isArchived_idx" ON "refresh_tokens"("userId", "echoAppId", "isArchived");
+
+-- CreateIndex
+CREATE INDEX "refresh_tokens_sessionId_isArchived_idx" ON "refresh_tokens"("sessionId", "isArchived");
+
+-- CreateIndex
+CREATE INDEX "refresh_tokens_expiresAt_idx" ON "refresh_tokens"("expiresAt");
+
+-- AddForeignKey
+ALTER TABLE "refresh_tokens" ADD CONSTRAINT "refresh_tokens_sessionId_fkey" FOREIGN KEY ("sessionId") REFERENCES "app_sessions"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "app_sessions" ADD CONSTRAINT "app_sessions_userId_fkey" FOREIGN KEY ("userId") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "app_sessions" ADD CONSTRAINT "app_sessions_echoAppId_fkey" FOREIGN KEY ("echoAppId") REFERENCES "echo_apps"("id") ON DELETE CASCADE ON UPDATE CASCADE;

echo-control/prisma/schema.prisma

@@ -31,6 +31,7 @@ model User {
   transactions   Transaction[]
   spendPoolUsage UserSpendPoolUsage[]
   ReferralCode   ReferralCode[]
+  appSessions    AppSession[]
 
   @@map("users")
 }
@@ -96,6 +97,7 @@ model EchoApp {
   currentReferralRewardId String?          @db.Uuid // Reference to current active referral reward
   currentReferralReward   ReferralReward?  @relation("CurrentReferralReward", fields: [currentReferralRewardId], references: [id])
   ReferralRewards         ReferralReward[] @relation("AppReferralRewards") // All referral rewards for this app
+  appSessions             AppSession[]
 
   @@map("echo_apps")
 }
@@ -157,9 +159,37 @@ model RefreshToken {
   echoApp    EchoApp   @relation(fields: [echoAppId], references: [id], onDelete: Cascade)
   user       User      @relation(fields: [userId], references: [id], onDelete: Cascade)
 
+  sessionId String?     @db.Uuid
+  session   AppSession? @relation(fields: [sessionId], references: [id], onDelete: Cascade)
+
+  @@index([userId, echoAppId, isArchived])
+  @@index([sessionId, isArchived])
+  @@index([expiresAt])
   @@map("refresh_tokens")
 }
 
+model AppSession {
+  id         String    @id @default(uuid()) @db.Uuid
+  userId     String    @db.Uuid
+  echoAppId  String    @db.Uuid
+  deviceName String?
+  userAgent  String?
+  ipAddress  String?
+  createdAt  DateTime  @default(now()) @db.Timestamptz(6)
+  updatedAt  DateTime  @updatedAt @db.Timestamptz(6)
+  lastSeenAt DateTime? @db.Timestamptz(6)
+  revokedAt  DateTime? @db.Timestamptz(6)
+  isArchived Boolean   @default(false)
+
+  user          User           @relation(fields: [userId], references: [id], onDelete: Cascade)
+  echoApp       EchoApp        @relation(fields: [echoAppId], references: [id], onDelete: Cascade)
+  refreshTokens RefreshToken[]
+
+  @@index([userId, echoAppId])
+  @@index([echoAppId, isArchived])
+  @@map("app_sessions")
+}
+
 model Payment {
   id          String     @id @default(uuid()) @db.Uuid
   paymentId   String     @unique
@@ -296,7 +326,7 @@ model TransactionMetadata {
   inputTokens  Int
   outputTokens Int
   totalTokens  Int
-  toolCost     Decimal   @default(0.0) @db.Decimal(65, 14) 
+  toolCost     Decimal       @default(0.0) @db.Decimal(65, 14)
   prompt       String?
   isArchived   Boolean       @default(false)
   archivedAt   DateTime?     @db.Timestamptz(6)

echo-control/src/app/(auth)/api/oauth/token/route.ts

@@ -1,6 +1,6 @@
 import {
-  handleRefreshToken,
   handleInitialTokenIssuance,
+  handleRefreshToken,
 } from '@/lib/jwt-tokens';
 import { NextRequest, NextResponse } from 'next/server';
 
@@ -20,6 +20,19 @@ export async function POST(req: NextRequest) {
 
     const { grant_type, code, redirect_uri, code_verifier } = body;
 
+    // Capture metadata from forwarded headers if present, fallback to standard
+    const deviceName = undefined; // derive later from userAgent if desired
+    const forwardedUserAgent =
+      req.headers.get('x-client-user-agent') ||
+      req.headers.get('user-agent') ||
+      undefined;
+    const forwardedIp =
+      req.headers.get('x-client-ip') ||
+      req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ||
+      req.headers.get('x-real-ip') ||
+      req.headers.get('cf-connecting-ip') ||
+      undefined;
+
     const client_id =
       body.client_id || req.nextUrl.searchParams.get('client_id');
 
@@ -48,7 +61,11 @@ export async function POST(req: NextRequest) {
         );
       }
 
-      const result = await handleRefreshToken(refresh_token);
+      const result = await handleRefreshToken(refresh_token, {
+        userAgent: forwardedUserAgent,
+        ipAddress: forwardedIp,
+        deviceName,
+      });
 
       // Check if result is an error
       if ('error' in result) {
@@ -74,6 +91,9 @@ export async function POST(req: NextRequest) {
       redirect_uri,
       client_id,
       code_verifier,
+      deviceName,
+      userAgent: forwardedUserAgent,
+      ipAddress: forwardedIp,
     });
 
     // Check if result is an error

echo-control/src/lib/apps/soft-delete.ts

@@ -49,6 +49,19 @@ export async function softDeleteEchoApp(appId: string) {
     },
   });
 
+  // Archive related app sessions
+  await db.appSession.updateMany({
+    where: {
+      echoAppId: appId,
+      isArchived: false,
+    },
+    data: {
+      isArchived: true,
+      revokedAt: now,
+      updatedAt: now,
+    },
+  });
+
   // Archive related app memberships
   await db.appMembership.updateMany({
     where: {
@@ -158,6 +171,18 @@ export async function softDeleteUser(userId: string) {
     },
   });
 
+  await db.appSession.updateMany({
+    where: {
+      userId,
+      isArchived: false,
+    },
+    data: {
+      isArchived: true,
+      revokedAt: now,
+      updatedAt: now,
+    },
+  });
+
   // Finally archive the user
   return await db.user.update({
     where: { id: userId },

echo-control/src/lib/jwt-tokens.ts

@@ -27,6 +27,7 @@ export interface ApiTokenPayload {
   app_id: string;
   scope: string;
   key_version: number;
+  sid?: string;
   // Standard JWT claims
   sub: string; // user_id
   aud: string; // app_id
@@ -55,8 +56,9 @@ export async function createEchoAccessJwtToken(params: {
   scope: string;
   expiry: Date;
   keyVersion?: number;
+  sessionId?: string;
 }): Promise<string> {
-  const { userId, appId, scope, expiry, keyVersion = 1 } = params;
+  const { userId, appId, scope, expiry, keyVersion = 1, sessionId } = params;
 
   const tokenId = nanoid(16);
   const now = Math.floor(Date.now() / 1000); // divide by 1000 to convert to seconds
@@ -67,6 +69,7 @@ export async function createEchoAccessJwtToken(params: {
     app_id: appId,
     scope,
     key_version: keyVersion,
+    ...(sessionId ? { sid: sessionId } : {}),
   })
     .setProtectedHeader({ alg: 'HS256' })
     .setSubject(userId)
@@ -192,7 +195,8 @@ export interface RefreshTokenError {
  * Handle refresh token logic
  */
 export async function handleRefreshToken(
-  refreshToken: string
+  refreshToken: string,
+  metadata?: { deviceName?: string; userAgent?: string; ipAddress?: string }
 ): Promise<RefreshTokenResponse | RefreshTokenError> {
   console.log('🔄 Processing refresh token request');
 
@@ -204,6 +208,7 @@ export async function handleRefreshToken(
     include: {
       user: true,
       echoApp: true,
+      session: true,
     },
   });
 
@@ -240,15 +245,27 @@ export async function handleRefreshToken(
     };
   }
 
-  /* 3️⃣ Check if echo app is still active */
+  /* 3️⃣ Check if session and echo app are still active */
+  if (
+    !echoRefreshTokenRecord.session ||
+    echoRefreshTokenRecord.session.revokedAt
+  ) {
+    return {
+      error: 'invalid_grant',
+      error_description: 'Session is revoked or invalid',
+    };
+  }
+
+  const sessionId = echoRefreshTokenRecord.session.id;
+
   if (echoRefreshTokenRecord.echoApp.isArchived) {
     return {
       error: 'invalid_grant',
       error_description: 'Echo app is no longer active',
     };
   }
 
-  /* 4️⃣ Generate new refresh token */
+  /* 4️⃣ Generate new refresh token (rotate within the same session) */
   const newEchoRefreshTokenValue = `refresh_${nanoid(48)}`;
   const newEchoRefreshTokenExpiry = createEchoRefreshTokenExpiry();
 
@@ -266,6 +283,18 @@ export async function handleRefreshToken(
       userId: echoRefreshTokenRecord.userId,
       echoAppId: echoRefreshTokenRecord.echoAppId,
       scope: echoRefreshTokenRecord.scope,
+      sessionId,
+    },
+  });
+
+  // Update session last seen
+  await db.appSession.update({
+    where: { id: sessionId },
+    data: {
+      lastSeenAt: new Date(),
+      ...(metadata?.userAgent ? { userAgent: metadata.userAgent } : {}),
+      ...(metadata?.ipAddress ? { ipAddress: metadata.ipAddress } : {}),
+      ...(metadata?.deviceName ? { deviceName: metadata.deviceName } : {}),
     },
   });
 
@@ -278,6 +307,7 @@ export async function handleRefreshToken(
     scope: echoRefreshTokenRecord.scope,
     keyVersion: 1,
     expiry: newEchoAccessTokenExpiry,
+    sessionId,
   });
 
   /* 6️⃣ Return new tokens with user and app info */
@@ -313,6 +343,9 @@ export interface AuthCodeTokenRequest {
   redirect_uri: string;
   client_id: string;
   code_verifier: string;
+  deviceName?: string;
+  userAgent?: string;
+  ipAddress?: string;
 }
 
 /**
@@ -331,7 +364,15 @@ export type InitialTokenError = RefreshTokenError;
 export async function handleInitialTokenIssuance(
   params: AuthCodeTokenRequest
 ): Promise<InitialTokenResponse | InitialTokenError> {
-  const { code, redirect_uri, client_id, code_verifier } = params;
+  const {
+    code,
+    redirect_uri,
+    client_id,
+    code_verifier,
+    deviceName,
+    userAgent,
+    ipAddress,
+  } = params;
 
   console.log('🎫 Processing authorization code token request');
 
@@ -473,28 +514,28 @@ export async function handleInitialTokenIssuance(
     };
   }
 
-  /* 🔟 Generate refresh token */
-  const echoRefreshTokenValue = `refresh_${nanoid(48)}`;
-  const echoRefreshTokenExpiry = createEchoRefreshTokenExpiry();
-
-  // Deactivate any existing refresh tokens for this app
-  await db.refreshToken.updateMany({
-    where: {
+  /* 🔟 Create an app session and refresh token */
+  const appSession = await db.appSession.create({
+    data: {
       userId: user.id,
       echoAppId: echoApp.id,
-      isArchived: false,
+      deviceName,
+      userAgent,
+      ipAddress,
     },
-    data: { isArchived: true },
   });
 
-  // Create new refresh token
+  const echoRefreshTokenValue = `refresh_${nanoid(48)}`;
+  const echoRefreshTokenExpiry = createEchoRefreshTokenExpiry();
+
   const newEchoRefreshToken = await db.refreshToken.create({
     data: {
       token: echoRefreshTokenValue,
       expiresAt: echoRefreshTokenExpiry,
       userId: user.id,
       echoAppId: echoApp.id,
       scope: authData.scope,
+      sessionId: appSession.id,
     },
   });
 
@@ -507,6 +548,7 @@ export async function handleInitialTokenIssuance(
     scope: authData.scope,
     keyVersion: 1,
     expiry: newEchoAccessTokenExpiry,
+    sessionId: appSession.id,
   });
 
   console.log('🎫 JWT access token generated');

echo-next-sdk/package.json

@@ -37,7 +37,7 @@
   "author": "Merit Systems",
   "license": "MIT",
   "dependencies": {
-    "@merit-systems/echo-typescript-sdk": "1.0.4",
+    "@merit-systems/echo-typescript-sdk": "1.0.5",
     "ai": "^5.0.17",
     "jwt-decode": "^4.0.0"
   },