@originals/auth 1.5.0

package/src/server/email-auth.ts

@@ -0,0 +1,258 @@
+/**
+ * Turnkey Email Authentication Service
+ * Implements email-based authentication using Turnkey's OTP flow
+ */
+
+import { Turnkey } from '@turnkey/sdk-server';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import type { EmailAuthSession, InitiateAuthResult, VerifyAuthResult } from '../types';
+import { getOrCreateTurnkeySubOrg } from './turnkey-client';
+
+// Session timeout (15 minutes to match Turnkey OTP)
+const SESSION_TIMEOUT = 15 * 60 * 1000;
+
+/**
+ * Session storage interface for pluggable session management
+ */
+export interface SessionStorage {
+  get(sessionId: string): EmailAuthSession | undefined;
+  set(sessionId: string, session: EmailAuthSession): void;
+  delete(sessionId: string): void;
+  cleanup(): void;
+}
+
+/**
+ * Create an in-memory session storage
+ * For production, consider using Redis or a database
+ */
+export function createInMemorySessionStorage(): SessionStorage {
+  const sessions = new Map<string, EmailAuthSession>();
+
+  // Start cleanup interval
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [sessionId, session] of sessions.entries()) {
+      if (now - session.timestamp > SESSION_TIMEOUT) {
+        sessions.delete(sessionId);
+      }
+    }
+  }, 60 * 1000);
+
+  // Keep the interval from preventing process exit
+  if (cleanupInterval.unref) {
+    cleanupInterval.unref();
+  }
+
+  return {
+    get: (sessionId: string) => sessions.get(sessionId),
+    set: (sessionId: string, session: EmailAuthSession) => sessions.set(sessionId, session),
+    delete: (sessionId: string) => sessions.delete(sessionId),
+    cleanup: () => {
+      clearInterval(cleanupInterval);
+      sessions.clear();
+    },
+  };
+}
+
+// Default session storage
+let defaultSessionStorage: SessionStorage | null = null;
+
+function getDefaultSessionStorage(): SessionStorage {
+  if (!defaultSessionStorage) {
+    defaultSessionStorage = createInMemorySessionStorage();
+  }
+  return defaultSessionStorage;
+}
+
+/**
+ * Generate a random session ID
+ */
+function generateSessionId(): string {
+  return `session_${Date.now()}_${Math.random().toString(36).substring(2, 15)}`;
+}
+
+/**
+ * Initiate email authentication using Turnkey OTP
+ * Sends a 6-digit OTP code to the user's email
+ */
+export async function initiateEmailAuth(
+  email: string,
+  turnkeyClient: Turnkey,
+  sessionStorage?: SessionStorage
+): Promise<InitiateAuthResult> {
+  const storage = sessionStorage ?? getDefaultSessionStorage();
+
+  // Validate email format
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(email)) {
+    throw new Error('Invalid email format');
+  }
+
+  console.log(`\n🚀 Initiating email auth for: ${email}`);
+
+  // Step 1: Get or create Turnkey sub-organization
+  const subOrgId = await getOrCreateTurnkeySubOrg(email, turnkeyClient);
+
+  // Step 2: Send OTP via Turnkey
+  console.log(`📨 Sending OTP to ${email} via Turnkey...`);
+
+  // Generate a unique user identifier for rate limiting
+  const data = new TextEncoder().encode(email);
+  const hash = sha256(data);
+  const userIdentifier = bytesToHex(hash);
+
+  const otpResult = await turnkeyClient.apiClient().initOtp({
+    otpType: 'OTP_TYPE_EMAIL',
+    contact: email,
+    userIdentifier: userIdentifier,
+    appName: 'Originals',
+    otpLength: 6,
+    alphanumeric: false,
+  });
+
+  const otpId = otpResult.otpId;
+
+  if (!otpId) {
+    throw new Error('Failed to initiate OTP - no OTP ID returned');
+  }
+
+  console.log(`✅ OTP sent! OTP ID: ${otpId}`);
+
+  // Create auth session
+  const sessionId = generateSessionId();
+  storage.set(sessionId, {
+    email,
+    subOrgId,
+    otpId,
+    timestamp: Date.now(),
+    verified: false,
+  });
+
+  console.log('='.repeat(60));
+  console.log(`📧 Check ${email} for the verification code!`);
+  console.log(`   Session ID: ${sessionId}`);
+  console.log(`   Valid for: 15 minutes`);
+  console.log('='.repeat(60) + '\n');
+
+  return {
+    sessionId,
+    message: 'Verification code sent to your email. Check your inbox!',
+  };
+}
+
+/**
+ * Verify email authentication code using Turnkey OTP
+ */
+export async function verifyEmailAuth(
+  sessionId: string,
+  code: string,
+  turnkeyClient: Turnkey,
+  sessionStorage?: SessionStorage
+): Promise<VerifyAuthResult> {
+  const storage = sessionStorage ?? getDefaultSessionStorage();
+  const session = storage.get(sessionId);
+
+  if (!session) {
+    throw new Error('Invalid or expired session');
+  }
+
+  // Check if session has expired
+  if (Date.now() - session.timestamp > SESSION_TIMEOUT) {
+    storage.delete(sessionId);
+    throw new Error('Session expired. Please request a new code.');
+  }
+
+  if (!session.otpId) {
+    throw new Error('OTP ID not found in session');
+  }
+
+  if (!session.subOrgId) {
+    throw new Error('Sub-organization ID not found');
+  }
+
+  console.log(`\n🔐 Verifying OTP for session ${sessionId}...`);
+
+  try {
+    // Verify the OTP code with Turnkey
+    const verifyResult = await turnkeyClient.apiClient().verifyOtp({
+      otpId: session.otpId,
+      otpCode: code,
+      expirationSeconds: '900', // 15 minutes
+    });
+
+    if (!verifyResult.verificationToken) {
+      throw new Error('OTP verification failed - no verification token returned');
+    }
+
+    console.log(`✅ OTP verified successfully!`);
+
+    // Mark session as verified
+    session.verified = true;
+    storage.set(sessionId, session);
+
+    return {
+      verified: true,
+      email: session.email,
+      subOrgId: session.subOrgId,
+    };
+  } catch (error) {
+    console.error('❌ OTP verification failed:', error);
+    throw new Error(
+      `Invalid verification code: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Check if a session is verified
+ */
+export function isSessionVerified(
+  sessionId: string,
+  sessionStorage?: SessionStorage
+): boolean {
+  const storage = sessionStorage ?? getDefaultSessionStorage();
+  const session = storage.get(sessionId);
+
+  if (!session) return false;
+
+  if (Date.now() - session.timestamp > SESSION_TIMEOUT) {
+    storage.delete(sessionId);
+    return false;
+  }
+
+  return session.verified;
+}
+
+/**
+ * Clean up a session after successful login
+ */
+export function cleanupSession(
+  sessionId: string,
+  sessionStorage?: SessionStorage
+): void {
+  const storage = sessionStorage ?? getDefaultSessionStorage();
+  storage.delete(sessionId);
+}
+
+/**
+ * Get session data
+ */
+export function getSession(
+  sessionId: string,
+  sessionStorage?: SessionStorage
+): EmailAuthSession | undefined {
+  const storage = sessionStorage ?? getDefaultSessionStorage();
+  const session = storage.get(sessionId);
+
+  if (!session) return undefined;
+
+  // Check if expired
+  if (Date.now() - session.timestamp > SESSION_TIMEOUT) {
+    storage.delete(sessionId);
+    return undefined;
+  }
+
+  return session;
+}
+

package/src/server/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Server-side authentication utilities
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createAuthMiddleware,
+ *   initiateEmailAuth,
+ *   verifyEmailAuth,
+ *   signToken,
+ *   verifyToken,
+ *   createTurnkeyClient,
+ *   TurnkeyWebVHSigner
+ * } from '@originals/auth/server';
+ * ```
+ */
+
+export { createTurnkeyClient, getOrCreateTurnkeySubOrg } from './turnkey-client';
+export {
+  initiateEmailAuth,
+  verifyEmailAuth,
+  isSessionVerified,
+  cleanupSession,
+  getSession,
+  type SessionStorage,
+  createInMemorySessionStorage,
+} from './email-auth';
+export {
+  signToken,
+  verifyToken,
+  getAuthCookieConfig,
+  getClearAuthCookieConfig,
+} from './jwt';
+export { createAuthMiddleware } from './middleware';
+export { TurnkeyWebVHSigner, createTurnkeySigner } from './turnkey-signer';
+
+
+

package/src/server/jwt.ts

@@ -0,0 +1,154 @@
+/**
+ * JWT Authentication Module
+ * Implements secure token issuance and validation with HTTP-only cookies
+ */
+
+import jwt from 'jsonwebtoken';
+import type { TokenPayload, AuthCookieConfig } from '../types';
+
+// 7 days in seconds
+const DEFAULT_JWT_EXPIRES_IN = 7 * 24 * 60 * 60;
+
+/**
+ * Get JWT secret from config or environment
+ */
+function getJwtSecret(configSecret?: string): string {
+  const secret = configSecret ?? process.env.JWT_SECRET;
+  if (!secret) {
+    throw new Error('JWT_SECRET environment variable is required');
+  }
+  return secret;
+}
+
+/**
+ * Sign a JWT token for a user
+ * @param subOrgId - Turnkey sub-organization ID (stable identifier)
+ * @param email - User email (metadata)
+ * @param sessionToken - Optional Turnkey session token for user authentication
+ * @param options - Additional options
+ * @returns Signed JWT token string
+ */
+export function signToken(
+  subOrgId: string,
+  email: string,
+  sessionToken?: string,
+  options?: {
+    secret?: string;
+    expiresIn?: number;
+    issuer?: string;
+    audience?: string;
+  }
+): string {
+  if (!subOrgId) {
+    throw new Error('Sub-organization ID is required for token signing');
+  }
+
+  const secret = getJwtSecret(options?.secret);
+
+  const payload: Record<string, unknown> = {
+    sub: subOrgId,
+    email,
+  };
+
+  if (sessionToken) {
+    payload.sessionToken = sessionToken;
+  }
+
+  const signOptions: jwt.SignOptions = {
+    expiresIn: options?.expiresIn ?? DEFAULT_JWT_EXPIRES_IN,
+    issuer: options?.issuer ?? 'originals-auth',
+    audience: options?.audience ?? 'originals-api',
+  };
+
+  return jwt.sign(payload, secret, signOptions);
+}
+
+/**
+ * Verify and decode a JWT token
+ * @param token - JWT token string
+ * @param options - Additional options
+ * @returns Decoded token payload
+ * @throws Error if token is invalid or expired
+ */
+export function verifyToken(
+  token: string,
+  options?: {
+    secret?: string;
+    issuer?: string;
+    audience?: string;
+  }
+): TokenPayload {
+  const secret = getJwtSecret(options?.secret);
+
+  try {
+    const payload = jwt.verify(token, secret, {
+      issuer: options?.issuer ?? 'originals-auth',
+      audience: options?.audience ?? 'originals-api',
+    }) as TokenPayload;
+
+    if (!payload.sub) {
+      throw new Error('Token missing sub-organization ID');
+    }
+
+    return payload;
+  } catch (error) {
+    if (error instanceof jwt.TokenExpiredError) {
+      throw new Error('Token has expired');
+    }
+    if (error instanceof jwt.JsonWebTokenError) {
+      throw new Error('Invalid token');
+    }
+    throw error;
+  }
+}
+
+/**
+ * Generate a secure cookie configuration for authentication tokens
+ * @param token - JWT token to set in cookie
+ * @param options - Cookie options
+ * @returns Cookie configuration object
+ */
+export function getAuthCookieConfig(
+  token: string,
+  options?: {
+    cookieName?: string;
+    maxAge?: number;
+    secure?: boolean;
+  }
+): AuthCookieConfig {
+  const isProduction = process.env.NODE_ENV === 'production';
+
+  return {
+    name: options?.cookieName ?? 'auth_token',
+    value: token,
+    options: {
+      httpOnly: true, // Cannot be accessed by JavaScript (XSS protection)
+      secure: options?.secure ?? isProduction, // HTTPS only in production
+      sameSite: 'strict', // CSRF protection
+      maxAge: options?.maxAge ?? 7 * 24 * 60 * 60 * 1000, // 7 days in milliseconds
+      path: '/', // Available for all routes
+    },
+  };
+}
+
+/**
+ * Get cookie configuration for logout (clears the auth cookie)
+ * @param cookieName - Name of the cookie to clear
+ * @returns Cookie configuration for clearing
+ */
+export function getClearAuthCookieConfig(cookieName?: string): AuthCookieConfig {
+  const isProduction = process.env.NODE_ENV === 'production';
+
+  return {
+    name: cookieName ?? 'auth_token',
+    value: '',
+    options: {
+      httpOnly: true,
+      secure: isProduction,
+      sameSite: 'strict',
+      maxAge: 0, // Expire immediately
+      path: '/',
+    },
+  };
+}
+

package/src/server/middleware.ts

@@ -0,0 +1,136 @@
+/**
+ * Express authentication middleware factory
+ */
+
+import type { Request, Response, NextFunction } from 'express';
+import { verifyToken } from './jwt';
+import type { AuthMiddlewareOptions, AuthUser, AuthenticatedRequest } from '../types';
+
+/**
+ * Create an authentication middleware for Express
+ *
+ * @example
+ * ```typescript
+ * import { createAuthMiddleware } from '@originals/auth/server';
+ *
+ * const authenticateUser = createAuthMiddleware({
+ *   getUserByTurnkeyId: async (turnkeyId) => {
+ *     return db.query.users.findFirst({
+ *       where: eq(users.turnkeySubOrgId, turnkeyId)
+ *     });
+ *   },
+ *   createUser: async (turnkeyId, email, temporaryDid) => {
+ *     return db.insert(users).values({
+ *       turnkeySubOrgId: turnkeyId,
+ *       email,
+ *       did: temporaryDid,
+ *     }).returning().then(rows => rows[0]);
+ *   }
+ * });
+ *
+ * app.get('/api/protected', authenticateUser, (req, res) => {
+ *   res.json({ user: req.user });
+ * });
+ * ```
+ */
+export function createAuthMiddleware(
+  options: AuthMiddlewareOptions
+): (req: Request, res: Response, next: NextFunction) => Promise<void | Response> {
+  const cookieName = options.cookieName ?? 'auth_token';
+
+  return async (req: Request, res: Response, next: NextFunction): Promise<void | Response> => {
+    try {
+      // Get JWT token from HTTP-only cookie
+      const token = req.cookies?.[cookieName];
+
+      if (!token) {
+        return res.status(401).json({ error: 'Not authenticated' });
+      }
+
+      // Verify JWT token
+      const payload = verifyToken(token, { secret: options.jwtSecret });
+      const turnkeySubOrgId = payload.sub;
+      const email = payload.email;
+
+      // Check if user already exists
+      let user: AuthUser | null = await options.getUserByTurnkeyId(turnkeySubOrgId);
+
+      // If user doesn't exist and createUser is provided, create user
+      if (!user && options.createUser) {
+        console.log(`Creating user record for ${email}...`);
+
+        // Use temporary DID as placeholder until user creates real DID
+        const temporaryDid = `temp:turnkey:${turnkeySubOrgId}`;
+
+        user = await options.createUser(turnkeySubOrgId, email, temporaryDid);
+
+        console.log(`✅ User created: ${email}`);
+        console.log(`   Turnkey sub-org ID: ${turnkeySubOrgId}`);
+        console.log(`   Temporary DID: ${temporaryDid}`);
+      }
+
+      if (!user) {
+        return res.status(401).json({ error: 'User not found' });
+      }
+
+      // Add user info to request
+      (req as Request & AuthenticatedRequest).user = {
+        id: user.id,
+        turnkeySubOrgId,
+        email,
+        did: user.did,
+        sessionToken: payload.sessionToken,
+      };
+
+      next();
+    } catch (error) {
+      console.error('Authentication error:', error);
+      return res.status(401).json({ error: 'Invalid or expired token' });
+    }
+  };
+}
+
+/**
+ * Optional authentication middleware - doesn't fail if not authenticated
+ * Attaches user to request if valid token exists, otherwise continues without user
+ */
+export function createOptionalAuthMiddleware(
+  options: AuthMiddlewareOptions
+): (req: Request, res: Response, next: NextFunction) => Promise<void> {
+  const cookieName = options.cookieName ?? 'auth_token';
+
+  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    try {
+      const token = req.cookies?.[cookieName];
+
+      if (!token) {
+        next();
+        return;
+      }
+
+      const payload = verifyToken(token, { secret: options.jwtSecret });
+      const turnkeySubOrgId = payload.sub;
+      const email = payload.email;
+
+      const user = await options.getUserByTurnkeyId(turnkeySubOrgId);
+
+      if (user) {
+        (req as Request & AuthenticatedRequest).user = {
+          id: user.id,
+          turnkeySubOrgId,
+          email,
+          did: user.did,
+          sessionToken: payload.sessionToken,
+        };
+      }
+
+      next();
+    } catch {
+      // Token invalid or expired, continue without user
+      next();
+    }
+  };
+}
+
+
+