Phase D

packages/auth/src/index.ts

@@ -15,11 +15,21 @@ export interface AuthenticatedUser {
   roles: UserRole[];
 }
 
+export interface SessionImpersonationContext {
+  isImpersonation: boolean;
+  source?: string;
+  externalServiceId?: string | null;
+  externalClientId?: string | null;
+  externalUserId?: string | null;
+  impersonatorLabel?: string;
+}
+
 export interface SessionContext {
   user: AuthenticatedUser;
   sessionId: string;
   issuedAt: Date;
   expiresAt: Date;
+  impersonation?: SessionImpersonationContext;
 }
 
 export interface AuthTokenPayload {

packages/contracts/src/index.ts

@@ -228,6 +228,10 @@ export {
   whmcsServiceResponseSchema,
   whmcsChangePackageRequestSchema,
   whmcsSuspendRequestSchema,
+  whmcsCreateSsoRequestSchema,
+  whmcsCreateSsoResponseSchema,
+  ssoConsumeRequestSchema,
+  ssoConsumeResponseSchema,
   type WhmcsHealthResponse,
   type WhmcsPlanCatalogResponse,
   type WhmcsProvisionServiceRequest,
@@ -235,4 +239,8 @@ export {
   type WhmcsUpsertClientRequest,
   type WhmcsUpsertClientResponse,
   type WhmcsChangePackageRequest,
+  type WhmcsCreateSsoRequest,
+  type WhmcsCreateSsoResponse,
+  type SsoConsumeRequest,
+  type SsoConsumeResponse,
 } from './whmcs';

packages/contracts/src/whmcs.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 
+import { authUserSchema } from './auth';
 import { serverResponseSchema } from './servers';
 
 export const whmcsHealthResponseSchema = z.object({
@@ -61,6 +62,40 @@ export const whmcsSuspendRequestSchema = z.object({
   reason: z.string().max(256).optional(),
 });
 
+export const whmcsSsoRoleSchema = z.enum(['owner', 'admin']);
+
+export const whmcsSsoKindSchema = z.enum(['service', 'admin']);
+
+export const whmcsCreateSsoRequestSchema = z.object({
+  externalClientId: z.string().min(1).max(64),
+  externalUserId: z.string().min(1).max(64),
+  role: whmcsSsoRoleSchema.default('owner'),
+  kind: whmcsSsoKindSchema.default('service'),
+  targetPath: z.string().max(256).optional(),
+});
+
+export const whmcsCreateSsoResponseSchema = z.object({
+  ticketId: z.string().uuid(),
+  redirectUrl: z.string().url(),
+  expiresAt: z.string().datetime(),
+  targetPath: z.string(),
+});
+
+export const ssoConsumeRequestSchema = z.object({
+  ticket: z.string().min(32).max(256),
+});
+
+export const ssoImpersonationSchema = z.object({
+  isImpersonation: z.boolean(),
+  label: z.string().optional(),
+});
+
+export const ssoConsumeResponseSchema = z.object({
+  redirectPath: z.string(),
+  user: authUserSchema,
+  impersonation: ssoImpersonationSchema.optional(),
+});
+
 export type WhmcsHealthResponse = z.infer<typeof whmcsHealthResponseSchema>;
 export type WhmcsPlanCatalogResponse = z.infer<typeof whmcsPlanCatalogResponseSchema>;
 export type WhmcsUpsertClientRequest = z.infer<typeof whmcsUpsertClientRequestSchema>;
@@ -69,3 +104,7 @@ export type WhmcsProvisionServiceRequest = z.infer<typeof whmcsProvisionServiceR
 export type WhmcsServiceResponse = z.infer<typeof whmcsServiceResponseSchema>;
 export type WhmcsChangePackageRequest = z.infer<typeof whmcsChangePackageRequestSchema>;
 export type WhmcsSuspendRequest = z.infer<typeof whmcsSuspendRequestSchema>;
+export type WhmcsCreateSsoRequest = z.infer<typeof whmcsCreateSsoRequestSchema>;
+export type WhmcsCreateSsoResponse = z.infer<typeof whmcsCreateSsoResponseSchema>;
+export type SsoConsumeRequest = z.infer<typeof ssoConsumeRequestSchema>;
+export type SsoConsumeResponse = z.infer<typeof ssoConsumeResponseSchema>;

packages/database/prisma/migrations/20260626240000_phase_d_sso/migration.sql

@@ -0,0 +1,43 @@
+-- WHMCS Phase D: SSO tickets and impersonation sessions
+
+CREATE TYPE "SsoTicketKind" AS ENUM ('SERVICE', 'ADMIN');
+
+ALTER TABLE "user_sessions"
+  ADD COLUMN IF NOT EXISTS "isImpersonation" BOOLEAN NOT NULL DEFAULT false,
+  ADD COLUMN IF NOT EXISTS "impersonationMetadata" JSONB;
+
+CREATE TABLE IF NOT EXISTS "sso_tickets" (
+  "id" TEXT NOT NULL,
+  "installationId" TEXT NOT NULL,
+  "tokenHash" TEXT NOT NULL,
+  "kind" "SsoTicketKind" NOT NULL,
+  "userId" TEXT NOT NULL,
+  "serverId" TEXT,
+  "externalServiceId" TEXT,
+  "externalClientId" TEXT,
+  "externalUserId" TEXT,
+  "targetPath" TEXT NOT NULL,
+  "issuer" TEXT NOT NULL,
+  "audience" TEXT NOT NULL,
+  "nonce" TEXT NOT NULL,
+  "expiresAt" TIMESTAMPTZ(3) NOT NULL,
+  "usedAt" TIMESTAMPTZ(3),
+  "createdAt" TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  CONSTRAINT "sso_tickets_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "sso_tickets_tokenHash_key" ON "sso_tickets"("tokenHash");
+CREATE UNIQUE INDEX IF NOT EXISTS "sso_tickets_nonce_key" ON "sso_tickets"("nonce");
+CREATE INDEX IF NOT EXISTS "sso_tickets_expiresAt_idx" ON "sso_tickets"("expiresAt");
+CREATE INDEX IF NOT EXISTS "sso_tickets_installationId_createdAt_idx"
+  ON "sso_tickets"("installationId", "createdAt");
+
+ALTER TABLE "sso_tickets"
+  ADD CONSTRAINT "sso_tickets_installationId_fkey"
+  FOREIGN KEY ("installationId") REFERENCES "whmcs_installations"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "sso_tickets"
+  ADD CONSTRAINT "sso_tickets_userId_fkey"
+  FOREIGN KEY ("userId") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "sso_tickets"
+  ADD CONSTRAINT "sso_tickets_serverId_fkey"
+  FOREIGN KEY ("serverId") REFERENCES "game_servers"("id") ON DELETE SET NULL ON UPDATE CASCADE;

packages/database/prisma/schema.prisma

@@ -147,6 +147,11 @@ enum IntegrationOperationStatus {
   FAILED
 }
 
+enum SsoTicketKind {
+  SERVICE
+  ADMIN
+}
+
 model User {
   id                  String     @id @default(uuid())
   email               String     @unique
@@ -169,6 +174,7 @@ model User {
   totpCredential          TotpCredential?
   creditWallet            CreditWallet?
   whmcsClientLink         WhmcsClientLink?
+  ssoTickets              SsoTicket[]
 
   @@map("users")
 }
@@ -194,6 +200,8 @@ model UserSession {
   revokedAt DateTime? @db.Timestamptz(3)
   ipAddress String?
   userAgent String?
+  isImpersonation      Boolean @default(false)
+  impersonationMetadata Json?
   createdAt DateTime  @default(now()) @db.Timestamptz(3)
   updatedAt DateTime  @updatedAt @db.Timestamptz(3)
 
@@ -332,6 +340,7 @@ model GameServer {
   usageRecords     UsageRecord[]
   dnsRecords       ServerDnsRecord[]
   whmcsServiceLink WhmcsServiceLink?
+  ssoTickets       SsoTicket[]
 
   @@index([userId])
   @@index([nodeId])
@@ -714,6 +723,7 @@ model WhmcsInstallation {
   clientLinks  WhmcsClientLink[]
   serviceLinks WhmcsServiceLink[]
   operations   IntegrationOperation[]
+  ssoTickets   SsoTicket[]
 
   @@map("whmcs_installations")
 }
@@ -770,3 +780,30 @@ model IntegrationOperation {
   @@index([installationId, createdAt])
   @@map("integration_operations")
 }
+
+model SsoTicket {
+  id                String        @id @default(uuid())
+  installationId    String
+  tokenHash         String        @unique
+  kind              SsoTicketKind
+  userId            String
+  serverId          String?
+  externalServiceId String?
+  externalClientId  String?
+  externalUserId    String?
+  targetPath        String
+  issuer            String
+  audience          String
+  nonce             String        @unique
+  expiresAt         DateTime      @db.Timestamptz(3)
+  usedAt            DateTime?     @db.Timestamptz(3)
+  createdAt         DateTime      @default(now()) @db.Timestamptz(3)
+
+  installation WhmcsInstallation @relation(fields: [installationId], references: [id], onDelete: Cascade)
+  user         User              @relation(fields: [userId], references: [id], onDelete: Cascade)
+  server       GameServer?       @relation(fields: [serverId], references: [id], onDelete: SetNull)
+
+  @@index([expiresAt])
+  @@index([installationId, createdAt])
+  @@map("sso_tickets")
+}

packages/database/src/index.ts

@@ -28,6 +28,7 @@ export type {
   WhmcsClientLink,
   WhmcsServiceLink,
   IntegrationOperation,
+  SsoTicket,
   Plan,
   FeatureFlag,
   SystemSetting,
@@ -35,7 +36,7 @@ export type {
   JobRecord,
 } from '@prisma/client';
 
-import { PrismaClient } from '@prisma/client';
+import { PrismaClient, Prisma } from '@prisma/client';
 
 const globalForPrisma = globalThis as unknown as {
   prisma: PrismaClient | undefined;