Twenty Oauth Mastery

# Twenty CRM OAuth Mastery Skill

**Author**: Generated from extensive OAuth debugging sessions in OpenCode  
**Last Updated**: 2026-02-08  
**Version**: 1.0

---

## Skill Metadata

```yaml
name: twenty-oauth-mastery
description: Expert-level OAuth authentication knowledge for Twenty CRM including implementation, troubleshooting, and best practices
expertise_level: Expert/Mastery
category: Authentication
applicable_to:
  - Twenty CRM authentication
  - Google/Microsoft OAuth
  - Token refresh management
  - Domain restrictions
  - Email/Calendar sync integration
prerequisites:
  - Knowledge of TypeScript/JavaScript
  - Understanding of OAuth 2.0 protocol
  - Familiarity with NestJS framework
keywords:
  - oauth
  - authentication
  - twenty-crm
  - google-oauth
  - microsoft-oauth
  - token-refresh
  - sync-integration
  - domain-restriction
```

---

## Quick Start

### When to Use This Skill

You should use this skill when working on:

✅ **Implementing** new OAuth providers  
✅ **Fixing** OAuth login issues  
✅ **Setting up** automatic Gmail/Calendar sync after OAuth  
✅ **Debugging** token refresh failures  
✅ **Configuring** domain restrictions  
✅ **Troubleshooting** redirect loops  

### Quick Reference for Common Issues

| Issue | File to Check | Quick Fix |
|-------|---------------|-----------|
| Redirect loop | `auth.service.ts` | Rebuild: `npx nx build twenty-server` |
| .co domain blocked | `google-auth.controller.ts` | Add to allowlist: `['company.com', 'company.co']` |
| Sync not starting | `google.auth.strategy.ts` | Return tokens in validate() |
| Cookie not readable | Controller cookie settings | Set `httpOnly: false` |
| Infinite loop | `SignInUpGlobalScopeFormEffect.tsx` | Track processed token signatures |

---

## Core Knowledge

### 1. Twenty CRM OAuth Architecture

**Key Files**: `twenty/packages/twenty-server/src/engine/core-modules/auth/`

**Structure**:
```
auth/
├── strategies/         # Passport strategies (Google, Microsoft)
├── co...

# Twenty CRM OAuth Mastery Skill - Created

## What Was Created

A comprehensive expertise skill for Twenty CRM OAuth integration, troubleshooting, and best practices based on extensive session analysis.

## Skill Location

**Primary File**: `/home/agent/fratres/custom-skills/twenty-oauth-mastery.skill.md`

**Draft Documentation**: `/home/agent/fratres/.sisyphus/drafts/twenty-oauth-mastery-skill.md`

## Skill Overview

**Name**: `twenty-oauth-mastery`

**Expertise Level**: Expert/Mastery

**Applicable To**:
- Twenty CRM authentication
- Google/Microsoft OAuth
- Token refresh management
- Domain restrictions
- Email/Calendar sync integration

---

## Key Components

### 1. Architecture Knowledge

**File Structure**: `twenty/packages/twenty-server/src/engine/core-modules/auth/`

```
auth/
├── strategies/         # Passport strategies (Google, Microsoft)
├── controllers/        # OAuth endpoints and callbacks
├── services/          # Auth logic, sync setup, token management
├── guards/            # Auth guards and validation
└── utils/             # Scope configuration, utilities
```

### 2. 5 Major Issues with Solutions

| Issue | Quick Fix |
|-------|-----------|
| **Redirect Loop** | Rebuild: `npx nx build twenty-server` |
| **.co Domain Blocked** | Add to allowlist in 3 places |
| **Sync Not Starting** | Return tokens in validate() method |
| **Cookie Not Readable** | Set `httpOnly: false` |
| **Infinite Loop** | Track processed token signatures |

### 3. Critical Code Patterns

**Passport Strategy** (MUST FOLLOW):
```typescript
passReqToCallback: true, // Required
return { ..., accessToken, refreshToken }; // Must preserve tokens
```

**Token Refresh**:
```typescript
// Preserve original refresh token (Google may not return new one)
return { accessToken: token, refreshToken: refreshToken };
```

### 4. Testing Strategies

- Unit testing for token refresh
- Playwright for cookie injection testing
- Database verification for sync issues

### 5. Deployment Checklist...