RFC: Unify OAuth 2.0 API

[pilcrowonpaper]

We recently introduced experimental createOAuth2AuthorizationUrl() (+ PKCE version) and validateOAuth2AuthorizationCode(), and I think it's a pretty well defined API that makes everything easier. However, types like OAuthProvider is loosely defined and aren't strictly enforced. This RFC aims to create 2 unified API for OAuth 2.0 and OAuth 2.0 with PKCE. This shouldn't affect those using the helpers and mostly is intended to clean up internal code. This makes documenting API much easier as well.

This is going to be a minor breaking change.

Provider Auth

ProviderUserAuth is a regular class and that will be extended (e.g. GithubUserAuth). The major difference is that ProviderUserAuth.existingUser is replaced with ProviderUserAuth.getExistingUser().

type ProviderUserAuth<_Auth extends Auth> = {
  getExistingUser: () => Promise<LuciaUser<_Auth> | null>
  createKey: (userId: string) => Promise<Key>
  createUser: (options: {
      userId?: string;
      attributes: LuciaDatabaseUserAttributes<_Auth>;
  }) => Promise<LuciaUser<_Auth>>
}

OAuth 2.0

OAuth2Provider is an abstract class. See #993 for an implementation example.

type OAuth2Provider<_ProviderUserAuth extends ProviderUserAuth<Auth>> = {
  getAuthorizationUrl: () => Promise<readonly [url: URL, state: string | null]>
  validateCallback: (code: string) => Promise< _ProviderUserAuth>
}

OAuth 2.0 with PKCE

OAuth2ProviderWithPKCE is an abstract class. See #993 for an implementation example.

type OAuth2ProviderWithPKCE<_ProviderUserAuth extends ProviderUserAuth<Auth>> = {
  getAuthorizationUrl: () => Promise<readonly [url: URL, codeVerifier: string, state: string | null]>
  validateCallback: (code: string, codeVerifier: string) => Promise< _ProviderUserAuth>
}

Breaking changes

• Replace ProviderUserAuth.existingUser with ProviderUserAuth.getExistingUser()
• LichessAuth.getAuthorizationUrl() will return url, code verifier, state instead of url, state, code verifier