TypeScript Types

interface AuthConfig {
  // JWT signing secret (min 32 characters)
  secret: string;

  // Authentication provider (OAuth, email, or 2FA)
  provider: Provider;

  // Optional database adapter for session persistence
  adapter?: Adapter;

  // Optional MCP (Model Context Protocol) configuration
  mcp?: {
    enabled: boolean;
    scopes?: string[];
  };

  // Optional Warpy Cloud Shield configuration
  warpy?: {
    apiKey?: string;
    baseUrl?: string;
  };

  // Optional CAPTCHA configuration
  captcha?: CaptchaEnforcement;

  // Lifecycle callbacks
  callbacks?: {
    // Resolve/upsert user (called after OAuth or email verification)
    user?: (
      user: { id?: string; email: string; name?: string; picture?: string },
      context?: { provider?: string }
    ) =>
      | Promise<{ id: string; email: string; name?: string; picture?: string }>
      | { id: string; email: string; name?: string; picture?: string };

    // Mutate JWT claims before signing
    jwt?: (token: JWTPayload) => JWTPayload | Promise<JWTPayload>;

    // Mutate session before returning to client
    session?: (session: Session) => Session | Promise<Session>;
  };
}

interface Session {
  // User information
  user: {
    id: string;
    email: string;
    name?: string;
    picture?: string;
  };

  // Session expiration date
  expires: Date;

  // JWT token (present for MCP agent sessions)
  token?: string;

  // Session type
  type?: "standard" | "mcp-agent";

  // Scopes (for MCP agent sessions)
  scopes?: string[];

  // Agent ID (for MCP agent sessions)
  agentId?: string;
}

interface AuthenticateResult {
  // Successful authentication session
  session?: Session;

  // Error message if authentication failed
  error?: string;

  // Redirect URL (for OAuth flows)
  redirectUrl?: string;

  // Set-Cookie headers to send to client
  cookies?: string[];

  // For 2FA: identifier to verify code
  identifier?: string;

  // For 2FA: code expiration time in milliseconds
  expiresIn?: number;
}

type Provider =
  | OAuthProviderConfig
  | EmailProviderConfig
  | TwoFactorProviderConfig;

interface OAuthProviderConfig {
  type: "oauth";
  clientId: string;
  clientSecret: string;
  authorizeUrl: string;
  tokenUrl: string;
  userInfoUrl: string;
  redirectUri: string;
  scope?: string[];

  // PKCE method: "S256" (SHA-256), "plain", or false (disabled)
  pkce?: "S256" | "plain" | false;

  // Function to map provider user info to standard UserProfile
  getUser: (accessToken: string) => Promise<UserProfile>;
}

interface EmailProviderConfig {
  type: "email";
  server: string; // Email service type
  from: string;   // From email address

  // Send magic link to user's email
  sendMagicLink: (email: string, url: string) => Promise<void>;

  // Verify magic link token
  verify: (token: string) => Promise<{ email: string; userId?: string } | null>;
}

interface TwoFactorProviderConfig {
  type: "twofa";
  from: string; // From email address

  // Send 6-digit verification code
  sendCode: (
    email: string
  ) => Promise<{ identifier: string; expiresIn: number }>;

  // Verify code
  verifyCode: (
    identifier: string,
    code: string
  ) => Promise<{ email: string; userId?: string } | null>;
}

interface UserProfile {
  id: string;      // Provider's user ID
  email: string;   // User's email
  name?: string;   // User's display name
  picture?: string; // User's profile picture URL
}

interface Adapter {
  // Session methods
  createSession(session: Omit<Session, "sessionToken">): Promise<Session>;
  getSession(sessionToken: string): Promise<Session | null>;
  updateSession(
    sessionToken: string,
    session: Partial<Session>
  ): Promise<Session | null>;
  deleteSession(sessionToken: string): Promise<void>;

  // User methods
  createUser(user: Omit<User, "id">): Promise<User>;
  getUser(id: string): Promise<User | null>;
  getUserByEmail(email: string): Promise<User | null>;
  updateUser(id: string, user: Partial<User>): Promise<User | null>;

  // Account methods (OAuth provider accounts)
  createAccount(account: Omit<Account, "id">): Promise<Account>;
  getAccount(
    provider: string,
    providerAccountId: string
  ): Promise<Account | null>;
  deleteAccount(provider: string, providerAccountId: string): Promise<void>;
}

interface Session {
  sessionToken: string;
  userId: string;
  expires: Date;
}

interface User {
  id: string;
  email: string;
  name?: string;
  picture?: string;
}

interface Account {
  id: string;
  userId: string;
  provider: string; // e.g., "google", "github"
  providerAccountId: string;
  accessToken?: string;
  refreshToken?: string;
  expiresAt?: Date;
}

interface MCPLoginPayload {
  userId: string;       // User ID to login as
  scopes: string[];     // Scopes for the agent (e.g., ["read", "debug"])
  agentId: string;      // Agent identifier
  expiresIn: string;    // Expiration time (e.g., "15m", "1h")
}

interface MCPShieldConfig {
  secret: string;
  adapter?: Adapter;

  // Warpy Cloud Shield configuration
  warpy?: {
    apiKey?: string;
    baseUrl?: string; // Default: "https://platform.warpy.co"
  };

  // Metrics configuration
  metrics?: {
    enabled: boolean;
    flushIntervalMs?: number; // Default: 10000 (10 seconds)
  };
}

interface CaptchaEnforcement {
  // CAPTCHA provider configuration
  provider: CaptchaProvider;

  // Which authentication methods require CAPTCHA
  enforce: {
    email?: boolean;  // Email magic links
    twofa?: boolean;  // Two-factor codes
    oauth?: boolean;  // OAuth flows (handled by provider)
  };
}

interface CaptchaProvider {
  type: 'recaptcha-v2' | 'recaptcha-v3' | 'hcaptcha' | 'turnstile';

  // Verify CAPTCHA token
  verify(token: string, remoteIp?: string): Promise<CaptchaVerificationResult>;
}

interface CaptchaVerificationResult {
  success: boolean;
  score?: number;      // reCAPTCHA v3 score (0.0 to 1.0)
  errors?: string[];   // Error messages if verification failed
}

// reCAPTCHA v2 (checkbox)
interface RecaptchaV2Config {
  type: 'recaptcha-v2';
  secretKey: string;
}

// reCAPTCHA v3 (invisible, score-based)
interface RecaptchaV3Config {
  type: 'recaptcha-v3';
  secretKey: string;
  minimumScore?: number; // Default: 0.5 (0.0 to 1.0)
}

// hCaptcha
interface HCaptchaConfig {
  type: 'hcaptcha';
  secretKey: string;
}

// Cloudflare Turnstile
interface TurnstileConfig {
  type: 'turnstile';
  secretKey: string;
}

interface AuthProviderProps {
  children: ReactNode;
  secret: string;
  onSignIn?: (session: Session) => void;
  onSignOut?: () => void;
}

interface AuthContextValue {
  session: Session | null;
  loading: boolean;
  signIn: (email: string, captchaToken?: string) => Promise<void>;
  signOut: () => Promise<void>;
  refreshSession: () => Promise<void>;
}

interface ExpressAuthOptions {
  basePath?: string;
  successRedirect?: string;
  errorRedirect?: string;
  mcp?: {
    enabled?: boolean;
    path?: string;
    shield?: MCPShieldConfig;
  };
}

type RequireAuth = (
  req: ExpressRequest,
  res: ExpressResponse,
  next: ExpressNextFunction
) => Promise<void>;

interface FastifyAuthOptions {
  basePath?: string;
  successRedirect?: string;
  errorRedirect?: string;
  mcp?: {
    enabled?: boolean;
    path?: string;
    shield?: MCPShieldConfig;
  };
}

type RequireAuth = (
  req: FastifyRequest,
  reply: FastifyReply
) => Promise<void>;

interface HonoAuthOptions {
  basePath?: string;
  successRedirect?: string;
  errorRedirect?: string;
  mcp?: {
    enabled?: boolean;
    path?: string;
    shield?: MCPShieldConfig;
  };
}

type RequireAuth = HonoMiddleware;

type HonoMiddleware = (
  c: HonoContext,
  next: () => Promise<void>
) => Promise<Response | void>;

interface NodeAuthOptions {
  basePath?: string;
  successRedirect?: string;
  errorRedirect?: string;
  mcp?: {
    enabled?: boolean;
    path?: string;
    shield?: MCPShieldConfig;
  };
}

type AuthHandler = (
  req: IncomingMessage,
  res: ServerResponse
) => Promise<boolean>;

interface NextAuthHandlerOptions {
  basePath?: string;        // Default: "/auth"
  successRedirect?: string; // Default: "/dashboard"
  errorRedirect?: string;   // Default: "/login"
}

interface AuthMiddlewareOptions extends NextAuthHandlerOptions {
  basePath?: string;
  successRedirect?: string;
  errorRedirect?: string;
  publicRoutes?: string[];
  protectedRoutes?: string[];
}

interface JWTPayload {
  userId: string;
  email?: string;
  name?: string;
  picture?: string;
  type?: "standard" | "mcp-agent";
  scopes?: string[];
  agentId?: string;
  exp?: number; // Expiration timestamp
  iat?: number; // Issued at timestamp
  [key: string]: unknown; // Custom claims
}

type EmailServiceConfig =
  | NodemailerConfig
  | ResendConfig;

interface NodemailerConfig {
  type: 'nodemailer';
  server: string; // SMTP server (e.g., "smtp.gmail.com:587")
  auth: {
    user: string;
    pass: string;
  };
}

interface ResendConfig {
  type: 'resend';
  apiKey: string;
}

interface EmailService {
  send(params: {
    to: string;
    subject: string;
    html: string;
    from: string;
  }): Promise<void>;
}

interface CustomEmailTemplate {
  component: (props: { magicLink: string }) => React.ReactElement;
  subject: string;
}

interface CustomTwoFactorTemplate {
  component: (props: { code: string }) => React.ReactElement;
  subject: string;
}