Migrate Auth to Result-based error handling; add shared Result/error infra

apps/admin-frontend/src/app/composition/container.test.ts

@@ -7,9 +7,8 @@ import {
   GetCurrentSession,
   Logout,
   toTenantContext,
-  Tenant,
-  User,
 } from '@/features/auth'
+import { Tenant, User } from '@/test/fixtures/authEntityFixtures'
 import { ListTags } from '@/features/catalog'
 
 function stubOidcEnv(): void {

apps/admin-frontend/src/app/layouts/AdminLayout.test.tsx

@@ -4,10 +4,12 @@ import userEvent from '@testing-library/user-event'
 import { MemoryRouter, Routes, Route } from 'react-router'
 import { AdminLayout } from '@/app/layouts/AdminLayout'
 import { AppContainerContext } from '@/app/providers/AppContainerContext'
-import { AuthProvider, ProtectedRoute, Tenant, User, type TenantContext } from '@/features/auth'
+import { AuthProvider, ProtectedRoute, type TenantContext } from '@/features/auth'
+import { Tenant, User } from '@/test/fixtures/authEntityFixtures'
 import { ThemeProvider } from '@/shared/presentation/providers/ThemeProvider'
 import type { AppContainer } from '@/app/composition/container'
 import { createFakeAppContainer } from '@/test/fixtures/createFakeAppContainer'
+import { success } from '@/shared/application/Result'
 import { vi } from 'vitest'
 
 function buildTenantContext(): TenantContext {
@@ -24,7 +26,7 @@ function buildTenantContextWithoutName(): TenantContext {
 
 function buildContainer(
   tenantContext: TenantContext | null,
-  logoutFn = vi.fn(() => Promise.resolve()),
+  logoutFn = vi.fn(() => Promise.resolve(success(undefined))),
 ): AppContainer {
   return createFakeAppContainer({
     auth: {
@@ -95,7 +97,7 @@ describe('AdminLayout', () => {
   })
 
   it('calls the logout use case when the sign out button is clicked', async () => {
-    const logoutSpy = vi.fn(() => Promise.resolve())
+    const logoutSpy = vi.fn(() => Promise.resolve(success(undefined)))
     renderLayout(buildContainer(buildTenantContext(), logoutSpy))
 
     await userEvent.click(await screen.findByRole('button', { name: /sair/i }))

apps/admin-frontend/src/features/auth/application/errors/AuthFlowError.ts

@@ -8,6 +8,7 @@ export type AuthFlowErrorCode =
   | 'AUTH_ATTEMPT_EXPIRED'
   | 'AUTH_RESPONSE_INVALID'
   | 'AUTH_ACCOUNT_WITHOUT_TENANT'
+  | 'AUTH_LOGOUT_FAILED'
 
 interface AuthFlowErrorInput {
   code: AppErrorCode

apps/admin-frontend/src/features/auth/application/repositories/AuthRepository.ts

@@ -1,4 +1,6 @@
 import { Session } from '@/features/auth/domain/entities/Session'
+import type { AuthFlowError } from '@/features/auth/application/errors/AuthFlowError'
+import type { Result } from '@/shared/application/Result'
 
 export interface AuthCallbackResult {
   session: Session
@@ -8,15 +10,16 @@ export interface AuthCallbackResult {
 export type LoginTheme = 'light' | 'dark'
 
 export interface AuthRepository {
-  initiateLogin(returnTo: string, theme: LoginTheme): Promise<void>
+  initiateLogin(returnTo: string, theme: LoginTheme): Promise<Result<void, AuthFlowError>>
 
   // callbackUrl is the full redirect-back URL (query/fragment included),
   // kept as a plain string so this port has no routing-library dependency.
-  handleCallback(callbackUrl: string): Promise<AuthCallbackResult>
+  handleCallback(callbackUrl: string): Promise<Result<AuthCallbackResult, AuthFlowError>>
 
-  // Attempts a silent renewal first if the token is expired/near-expiry;
-  // null if there's no session or renewal failed (stale state is cleared).
+  // Never fails in a way a caller needs to distinguish - null already means
+  // "no usable session" whether that's because none exists, renewal
+  // failed, or the cached data was malformed. See docs/adr/014.
   getCurrentSession(): Promise<Session | null>
 
-  logout(): Promise<void>
+  logout(): Promise<Result<void, AuthFlowError>>
 }

apps/admin-frontend/src/features/auth/application/test-helpers/createFakeAuthRepository.ts

@@ -1,11 +1,20 @@
 import type { AuthRepository } from '@/features/auth/application/repositories/AuthRepository'
+import { AuthFlowError } from '@/features/auth/application/errors/AuthFlowError'
+import { failure, success } from '@/shared/application/Result'
+
+const NOT_IMPLEMENTED = new AuthFlowError({
+  code: 'unexpected',
+  flowCode: 'AUTH_LOGIN_FAILED',
+  message: 'not implemented in this fake',
+  retryable: false,
+})
 
 export function createFakeAuthRepository(overrides: Partial<AuthRepository> = {}): AuthRepository {
   return {
-    initiateLogin: () => Promise.resolve(),
-    handleCallback: () => Promise.reject(new Error('not implemented in this fake')),
+    initiateLogin: () => Promise.resolve(success(undefined)),
+    handleCallback: () => Promise.resolve(failure(NOT_IMPLEMENTED)),
     getCurrentSession: () => Promise.resolve(null),
-    logout: () => Promise.resolve(),
+    logout: () => Promise.resolve(success(undefined)),
     ...overrides,
   }
 }

apps/admin-frontend/src/features/auth/application/use-cases/GetCurrentSession.test.ts

@@ -1,9 +1,7 @@
 import { describe, it, expect } from 'vitest'
 import { GetCurrentSession } from '@/features/auth/application/use-cases/GetCurrentSession'
 import { createFakeAuthRepository } from '@/features/auth/application/test-helpers/createFakeAuthRepository'
-import { Session } from '@/features/auth/domain/entities/Session'
-import { User } from '@/features/auth/domain/entities/User'
-import { Tenant } from '@/features/auth/domain/value-objects/Tenant'
+import { Session, Tenant, User } from '@/test/fixtures/authEntityFixtures'
 
 describe('GetCurrentSession', () => {
   it('returns the tenant context when a valid session exists', async () => {

apps/admin-frontend/src/features/auth/application/use-cases/HandleAuthCallback.test.ts

@@ -1,15 +1,25 @@
 import { describe, it, expect } from 'vitest'
 import { HandleAuthCallback } from '@/features/auth/application/use-cases/HandleAuthCallback'
 import { createFakeAuthRepository } from '@/features/auth/application/test-helpers/createFakeAuthRepository'
-import { Session } from '@/features/auth/domain/entities/Session'
-import { User } from '@/features/auth/domain/entities/User'
-import { Tenant } from '@/features/auth/domain/value-objects/Tenant'
+import { Session, Tenant, User } from '@/test/fixtures/authEntityFixtures'
 import type { AuthCallbackResult } from '@/features/auth/application/repositories/AuthRepository'
+import { AuthFlowError } from '@/features/auth/application/errors/AuthFlowError'
+import { success, failure } from '@/shared/application/Result'
 
-function callbackResult(session: Session, returnTo: string | null = null): AuthCallbackResult {
+function callbackResult(
+  session: AuthCallbackResult['session'],
+  returnTo: string | null = null,
+): AuthCallbackResult {
   return { session, returnTo }
 }
 
+const TOKEN_EXCHANGE_FAILED = new AuthFlowError({
+  code: 'unauthenticated',
+  flowCode: 'AUTH_ATTEMPT_EXPIRED',
+  message: 'invalid_grant: code expired',
+  retryable: true,
+})
+
 describe('HandleAuthCallback', () => {
   it('returns the tenant context when the callback is handled successfully', async () => {
     const tenant = Tenant.create('tenant-123')
@@ -21,17 +31,19 @@ describe('HandleAuthCallback', () => {
     })
 
     const authRepository = createFakeAuthRepository({
-      handleCallback: () => Promise.resolve(callbackResult(session)),
+      handleCallback: () => Promise.resolve(success(callbackResult(session))),
     })
 
     const handleAuthCallback = new HandleAuthCallback(authRepository)
     const result = await handleAuthCallback.execute(
       'https://admin.example.com/callback?code=abc123&state=xyz',
     )
 
-    expect(result.tenantContext.tenant.equals(tenant)).toBe(true)
-    expect(result.tenantContext.user).toBe(user)
-    expect(result.returnTo).toBe('/dashboard')
+    expect(result.success).toBe(true)
+    if (!result.success) return
+    expect(result.value.tenantContext.tenant.equals(tenant)).toBe(true)
+    expect(result.value.tenantContext.user).toBe(user)
+    expect(result.value.returnTo).toBe('/dashboard')
   })
 
   it('passes the callback URL through to the repository unchanged', async () => {
@@ -47,7 +59,7 @@ describe('HandleAuthCallback', () => {
     const authRepository = createFakeAuthRepository({
       handleCallback: url => {
         receivedUrl = url
-        return Promise.resolve(callbackResult(session))
+        return Promise.resolve(success(callbackResult(session)))
       },
     })
 
@@ -60,14 +72,18 @@ describe('HandleAuthCallback', () => {
 
   it('propagates the error when token exchange fails', async () => {
     const authRepository = createFakeAuthRepository({
-      handleCallback: () => Promise.reject(new Error('invalid_grant: code expired')),
+      handleCallback: () => Promise.resolve(failure(TOKEN_EXCHANGE_FAILED)),
     })
 
     const handleAuthCallback = new HandleAuthCallback(authRepository)
 
-    await expect(
-      handleAuthCallback.execute('https://admin.example.com/callback?error=access_denied'),
-    ).rejects.toThrow('invalid_grant: code expired')
+    const result = await handleAuthCallback.execute(
+      'https://admin.example.com/callback?error=access_denied',
+    )
+
+    expect(result.success).toBe(false)
+    if (result.success) return
+    expect(result.error.message).toBe('invalid_grant: code expired')
   })
 
   it('exchanges the code only once for two concurrent calls with the same callback URL', async () => {
@@ -82,7 +98,7 @@ describe('HandleAuthCallback', () => {
     const authRepository = createFakeAuthRepository({
       handleCallback: () => {
         callCount += 1
-        return Promise.resolve(callbackResult(session))
+        return Promise.resolve(success(callbackResult(session)))
       },
     })
 
@@ -112,7 +128,7 @@ describe('HandleAuthCallback', () => {
     const authRepository = createFakeAuthRepository({
       handleCallback: () => {
         callCount += 1
-        return Promise.resolve(callbackResult(session))
+        return Promise.resolve(success(callbackResult(session)))
       },
     })
 
@@ -125,26 +141,26 @@ describe('HandleAuthCallback', () => {
     expect(callCount).toBe(1)
   })
 
-  it('propagates the same rejection to every caller sharing a failed callback URL', async () => {
+  it('propagates the same failure to every caller sharing a failed callback URL', async () => {
     let callCount = 0
     const authRepository = createFakeAuthRepository({
       handleCallback: () => {
         callCount += 1
-        return Promise.reject(new Error('invalid_grant: code expired'))
+        return Promise.resolve(failure(TOKEN_EXCHANGE_FAILED))
       },
     })
 
     const handleAuthCallback = new HandleAuthCallback(authRepository)
     const callbackUrl = 'https://admin.example.com/callback?code=abc123&state=xyz'
 
-    const [firstResult, secondResult] = await Promise.allSettled([
+    const [firstResult, secondResult] = await Promise.all([
       handleAuthCallback.execute(callbackUrl),
       handleAuthCallback.execute(callbackUrl),
     ])
 
     expect(callCount).toBe(1)
-    expect(firstResult.status).toBe('rejected')
-    expect(secondResult.status).toBe('rejected')
+    expect(firstResult.success).toBe(false)
+    expect(secondResult.success).toBe(false)
   })
 
   it('exchanges the code again for a different callback URL (a fresh login)', async () => {
@@ -159,7 +175,7 @@ describe('HandleAuthCallback', () => {
     const authRepository = createFakeAuthRepository({
       handleCallback: () => {
         callCount += 1
-        return Promise.resolve(callbackResult(session))
+        return Promise.resolve(success(callbackResult(session)))
       },
     })
 
@@ -181,14 +197,16 @@ describe('HandleAuthCallback', () => {
     })
     const authRepository = createFakeAuthRepository({
       handleCallback: () =>
-        Promise.resolve(callbackResult(session, '/services?search=massagem#editor')),
+        Promise.resolve(success(callbackResult(session, '/services?search=massagem#editor'))),
     })
 
     const result = await new HandleAuthCallback(authRepository).execute(
       'https://admin.example.com/callback?code=abc',
     )
 
-    expect(result.returnTo).toBe('/services?search=massagem#editor')
+    expect(result.success).toBe(true)
+    if (!result.success) return
+    expect(result.value.returnTo).toBe('/services?search=massagem#editor')
   })
 
   it('falls back to the dashboard when callback state contains an external URL', async () => {
@@ -201,13 +219,15 @@ describe('HandleAuthCallback', () => {
     })
     const authRepository = createFakeAuthRepository({
       handleCallback: () =>
-        Promise.resolve(callbackResult(session, 'https://evil.example/steal-session')),
+        Promise.resolve(success(callbackResult(session, 'https://evil.example/steal-session'))),
     })
 
     const result = await new HandleAuthCallback(authRepository).execute(
       'https://admin.example.com/callback?code=abc',
     )
 
-    expect(result.returnTo).toBe('/dashboard')
+    expect(result.success).toBe(true)
+    if (!result.success) return
+    expect(result.value.returnTo).toBe('/dashboard')
   })
 })

apps/admin-frontend/src/features/auth/application/use-cases/HandleAuthCallback.ts

@@ -1,9 +1,11 @@
 import type { AuthRepository } from '@/features/auth/application/repositories/AuthRepository'
+import type { AuthFlowError } from '@/features/auth/application/errors/AuthFlowError'
 import {
   toTenantContext,
   type TenantContext,
 } from '@/features/auth/application/context/TenantContext'
 import { resolvePostLoginPath } from '@/features/auth/application/navigation/postLoginPath'
+import { success, type Result } from '@/shared/application/Result'
 
 export interface CompletedAuthCallback {
   tenantContext: TenantContext
@@ -12,7 +14,7 @@ export interface CompletedAuthCallback {
 
 interface CachedCallback {
   url: string
-  promise: Promise<CompletedAuthCallback>
+  promise: Promise<Result<CompletedAuthCallback, AuthFlowError>>
 }
 
 // Single-flight per callback URL: an OAuth code is single-use, and
@@ -26,20 +28,25 @@ export class HandleAuthCallback {
     this.authRepository = authRepository
   }
 
-  async execute(callbackUrl: string): Promise<CompletedAuthCallback> {
+  async execute(callbackUrl: string): Promise<Result<CompletedAuthCallback, AuthFlowError>> {
     if (this.cached?.url !== callbackUrl) {
       this.cached = { url: callbackUrl, promise: this.performCallback(callbackUrl) }
     }
 
     return this.cached.promise
   }
 
-  private async performCallback(callbackUrl: string): Promise<CompletedAuthCallback> {
-    const { session, returnTo } = await this.authRepository.handleCallback(callbackUrl)
-
-    return {
-      tenantContext: toTenantContext(session.user),
-      returnTo: resolvePostLoginPath(returnTo),
+  private async performCallback(
+    callbackUrl: string,
+  ): Promise<Result<CompletedAuthCallback, AuthFlowError>> {
+    const result = await this.authRepository.handleCallback(callbackUrl)
+    if (!result.success) {
+      return result
     }
+
+    return success({
+      tenantContext: toTenantContext(result.value.session.user),
+      returnTo: resolvePostLoginPath(result.value.returnTo),
+    })
   }
 }

apps/admin-frontend/src/features/auth/application/use-cases/InitiateLogin.test.ts

@@ -1,10 +1,11 @@
 import { describe, it, expect, vi } from 'vitest'
 import { InitiateLogin } from '@/features/auth/application/use-cases/InitiateLogin'
 import { createFakeAuthRepository } from '@/features/auth/application/test-helpers/createFakeAuthRepository'
+import { success } from '@/shared/application/Result'
 
 describe('InitiateLogin', () => {
   it('delegates with the page that should be restored after login', async () => {
-    const initiateLoginSpy = vi.fn(() => Promise.resolve())
+    const initiateLoginSpy = vi.fn(() => Promise.resolve(success(undefined)))
     const authRepository = createFakeAuthRepository({ initiateLogin: initiateLoginSpy })
 
     const initiateLogin = new InitiateLogin(authRepository)

apps/admin-frontend/src/features/auth/application/use-cases/InitiateLogin.ts

@@ -2,6 +2,8 @@ import type {
   AuthRepository,
   LoginTheme,
 } from '@/features/auth/application/repositories/AuthRepository'
+import type { AuthFlowError } from '@/features/auth/application/errors/AuthFlowError'
+import type { Result } from '@/shared/application/Result'
 import { resolvePostLoginPath } from '@/features/auth/application/navigation/postLoginPath'
 
 export class InitiateLogin {
@@ -11,7 +13,10 @@ export class InitiateLogin {
     this.authRepository = authRepository
   }
 
-  async execute(returnTo: string | undefined, theme: LoginTheme): Promise<void> {
-    await this.authRepository.initiateLogin(resolvePostLoginPath(returnTo), theme)
+  async execute(
+    returnTo: string | undefined,
+    theme: LoginTheme,
+  ): Promise<Result<void, AuthFlowError>> {
+    return this.authRepository.initiateLogin(resolvePostLoginPath(returnTo), theme)
   }
 }

apps/admin-frontend/src/features/auth/application/use-cases/Logout.test.ts

@@ -1,10 +1,11 @@
 import { describe, it, expect, vi } from 'vitest'
 import { Logout } from '@/features/auth/application/use-cases/Logout'
 import { createFakeAuthRepository } from '@/features/auth/application/test-helpers/createFakeAuthRepository'
+import { success } from '@/shared/application/Result'
 
 describe('Logout', () => {
   it('delegates to the auth repository to clear the session and end the provider session', async () => {
-    const logoutSpy = vi.fn(() => Promise.resolve())
+    const logoutSpy = vi.fn(() => Promise.resolve(success(undefined)))
     const authRepository = createFakeAuthRepository({ logout: logoutSpy })
 
     const logout = new Logout(authRepository)