Cloud Auth

  subgraph "Your Server"
      Provider[MastraCloudAuthProvider]
      RBAC[MastraRBACCloud]
  end

  subgraph "Mastra Cloud"
      AuthAPI[/auth/* endpoints]
  end

  Browser -->|1. GET /login| Provider
  Provider -->|2. Redirect w/ PKCE| AuthAPI
  AuthAPI -->|3. User authenticates| AuthAPI
  AuthAPI -->|4. Redirect /callback| Provider
  Provider -->|5. Exchange code| AuthAPI
  Provider -->|6. Verify token| AuthAPI
  Provider -->|7. Set session cookie| Browser

  Browser -->|8. API request + cookie| Provider
  Provider -->|9. Verify session| AuthAPI
  Provider -->|10. Check permission| RBAC

  subgraph Internal["Internal Modules"]
      OAuth[oauth/]
      PKCE[pkce/]
      Session[session/]
  end

  MCAP --> MCA
  MCA --> OAuth
  MCA --> PKCE
  MCA --> Session

  OAuth --> PKCE

  B->>S: GET /auth/login
  S->>S: Generate verifier + challenge
  S->>S: Generate CSRF token
  S->>S: Encode state (CSRF + returnTo)
  S->>B: Set PKCE cookie (5m) + Redirect
  B->>C: /auth/oss?challenge=X&state=Y
  C->>C: User login (WorkOS)
  C->>B: Redirect /callback?code=Z&state=Y
  B->>S: GET /callback?code=Z&state=Y
  S->>S: Validate PKCE cookie
  S->>S: Verify CSRF in state
  S->>C: POST /auth/callback (code + verifier)
  C-->>S: { accessToken }
  S->>C: POST /auth/verify (Bearer token)
  C-->>S: { user, role }
  S->>B: Set session cookie (24h) + Redirect

  B->>S: API Request + Session Cookie
  S->>S: Parse cookie → token
  S->>C: POST /auth/verify (token)
  C-->>S: { user, role }
  S->>R: hasPermission(user, "agents:read")
  R-->>S: true/false
  alt Has Permission
      S-->>B: 200 + Response
  else No Permission
      S-->>B: 403 Forbidden
  end

  class MastraCloudAuthProvider {
      -client: MastraCloudAuth
      +authenticateToken(req)
      +getLoginUrl(returnTo)
      +handleCallback(req)
      +logout(req)
  }

  class MastraCloudAuth {
      -cloudUrl: string
      -clientId: string
      -redirectUrl: string
      +getLoginUrl(returnTo)
      +handleCallback(req)
      +verifyToken(token)
      +destroySession(token)
  }

  class MastraRBACCloud {
      -roleMapping: Map
      +getRoles(user)
      +getPermissions(user)
      +hasPermission(user, perm)
  }

  MastraAuthProvider <|-- MastraCloudAuthProvider
  MastraCloudAuthProvider --> MastraCloudAuth