Extract authentication business logic and remove deprecated code

[nicknisi]

Summary

Extract authentication business logic into reusable classes and remove deprecated factory pattern. Provides clean API for building framework-specific WorkOS authentication packages.

Key Changes

New API:

• createAuthService({ sessionStorageFactory }) - Create auth instance
• AuthService - Main API (withAuth, signOut, getSignInUrl, etc.)
• Discriminated union for AuthResult - TypeScript-safe auth checks

Removed:

• createAuthKitFactory() - Deprecated
• SessionManager - Deprecated
• ~500 lines of unused code

Internal architecture:

• AuthKitCore - JWT verification, session encryption, refresh logic
• AuthOperations - WorkOS API operations
• Clean separation of concerns

Breaking Changes

1. Factory function renamed:

// Before
import { createAuthKitFactory } from '@workos/authkit-session';
const authKit = createAuthKitFactory({ sessionStorageFactory });

// After
import { createAuthService } from '@workos/authkit-session';
const authService = createAuthService({ sessionStorageFactory });

2. withAuth returns discriminated union:

// Before
const result = await authKit.withAuth(request);
if (result.user) {
  console.log(result.sessionId!); // Needed ! assertion
}

// After
const { auth, refreshedSessionData } = await authService.withAuth(request);
if (!auth.user) {
  return redirect('/login');
}
// TypeScript knows sessionId exists (no ! needed)
console.log(auth.sessionId);    // ✅ string
console.log(auth.accessToken);  // ✅ string

3. AuthResult type:

type AuthResult<T> = 
  | { user: null }
  | { user: User; sessionId: string; accessToken: string; claims: T; ... }

Testing

• ✅ All 142 tests passing
• ✅ TanStack Start builds successfully
• ✅ 80%+ coverage maintained

Documentation

• Updated README with correct API examples
• Removed migration guide (no existing users)
• Clear architecture explanation

[Copilot]

Pull Request Overview

This PR successfully extracts WorkOS authentication business logic into a framework-agnostic library, replacing the deprecated factory pattern with a clean service-based architecture. The refactor introduces improved type safety through discriminated unions and establishes clear separation of concerns between public API (AuthService) and internal implementation (AuthKitCore, AuthOperations).

Key changes:

• Introduced AuthService as the main public API with createAuthService() factory
• Removed deprecated SessionManager and createAuthKitFactory() (~500 lines)
• Enhanced type safety with discriminated union AuthResult type (eliminates optional chaining)
• Updated dependencies (jose 6.1.2, vitest 4.0.10, typescript 5.9.3)

Reviewed Changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/service/factory.ts	New factory function with lazy initialization for AuthService creation
src/service/AuthService.ts	New main public API coordinating core logic, operations, and storage
src/operations/AuthOperations.ts	New operations layer handling WorkOS API calls (signOut, refresh, URLs)
src/core/AuthKitCore.ts	New core business logic layer (JWT, encryption, refresh orchestration)
src/core/session/types.ts	Enhanced with discriminated union AuthResult type for better type safety
src/core/session/CookieSessionStorage.ts	Added secure flag inference and SameSite capitalization for Safari
src/index.ts	Reorganized exports with clear public API vs internal layers distinction
package.json	Updated dependencies and version to 0.2.0-beta.0
README.md	Complete rewrite explaining architecture, storage adapter pattern, and usage
pnpm-lock.yaml	Dependency updates reflecting package.json changes
src/core/session/SessionManager.ts	Removed deprecated SessionManager class
src/core/createAuthKitFactory.ts	Removed deprecated factory pattern

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull Request Overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 5 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 5 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The parameter name has a typo: confg should be config.

[nicknisi]

@greptileai

[nicknisi]

@greptileai

[greptile-apps]

Greptile Overview

Greptile Summary

This PR successfully extracts authentication business logic into a cleaner, more maintainable architecture with three distinct layers: AuthKitCore (pure business logic), AuthOperations (WorkOS API calls), and AuthService (framework orchestration). The refactoring removes ~500 lines of deprecated code (SessionManager, createAuthKitFactory) and introduces a discriminated union AuthResult type for improved TypeScript safety.

Key improvements:

• Clean separation of concerns with clear responsibility boundaries
• Lazy initialization pattern allows config to be set after instantiation
• Type-safe authentication checks via discriminated unions eliminate need for null assertions
• All 142 tests passing with 80%+ coverage maintained
• Comprehensive documentation updates with accurate examples

Breaking changes:

• Factory function renamed: createAuthKitFactory → createAuthService
• withAuth() now returns discriminated union instead of nullable fields
• No existing users affected (prerelease software)

Security posture:

• No sensitive data logging detected
• Secure cookie defaults maintained (HttpOnly, Secure, SameSite=lax)
• Session encryption and JWT verification properly implemented
• Error handling swallows exceptions and returns safe defaults

Confidence Score: 5/5

• This PR is safe to merge with minimal risk - well-architected refactoring with comprehensive test coverage
• Score reflects excellent code organization, thorough testing (142 tests passing), clean separation of concerns, proper security practices, and clear documentation. The refactoring simplifies the codebase while maintaining all functionality. No security issues or logical errors detected.
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
src/core/AuthKitCore.ts	5/5	New pure business logic layer for JWT verification, session encryption, and token refresh - well-structured with clear separation of concerns
src/operations/AuthOperations.ts	5/5	New high-level operations layer orchestrating WorkOS API calls for sign out, org switching, and authorization URLs
src/service/AuthService.ts	5/5	Main framework-agnostic authentication service with lazy initialization - coordinates core logic, operations, and storage
src/service/factory.ts	5/5	Factory function for creating AuthService with lazy initialization support and sensible defaults
src/index.ts	5/5	Updated exports reflecting new API - removed deprecated factory, added new createAuthService and core layers
src/core/session/types.ts	5/5	Updated type definitions with new discriminated union AuthResult for type-safe authentication checks

Sequence Diagram

sequenceDiagram
    participant App as Framework App
    participant AS as AuthService
    participant Storage as SessionStorage
    participant Core as AuthKitCore
    participant Ops as AuthOperations
    participant WorkOS as WorkOS API

    Note over App,WorkOS: Authentication Flow (withAuth)
    App->>AS: withAuth(request)
    AS->>Storage: getSession(request)
    Storage-->>AS: encryptedSession
    AS->>Core: decryptSession(encryptedSession)
    Core-->>AS: session (tokens + user)
    AS->>Core: validateAndRefresh(session)
    Core->>Core: verifyToken(accessToken)
    Core->>Core: isTokenExpiring(accessToken)
    alt Token valid and not expiring
        Core-->>AS: valid session, no refresh
    else Token invalid or expiring
        Core->>WorkOS: authenticateWithRefreshToken()
        WorkOS-->>Core: new tokens and user
        Core->>Core: encryptSession(newSession)
        Core-->>AS: refreshed session data
    end
    AS-->>App: AuthResult with optional refresh

    Note over App,WorkOS: OAuth Callback Flow
    App->>AS: handleCallback(request, response, options)
    AS->>WorkOS: authenticateWithCode(authCode)
    WorkOS-->>AS: tokens and user data
    AS->>Core: encryptSession(session)
    Core-->>AS: encryptedSession
    AS->>Storage: saveSession(response, encryptedSession)
    Storage-->>AS: updated response with cookie
    AS-->>App: response with return path

    Note over App,WorkOS: Sign Out Flow
    App->>AS: signOut(sessionId, options)
    AS->>Ops: signOut(sessionId, options)
    Ops->>WorkOS: getLogoutUrl(sessionId)
    WorkOS-->>Ops: logoutUrl
    Ops->>Ops: buildClearCookieHeader()
    Ops-->>AS: logout URL and clear cookie
    AS-->>App: logout data for redirect

Loading

[greptile-apps]

_{18 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}