@atproto/oauth-provider 0.17.0-next.0 → 0.18.0

package/src/account/account-manager.ts

@@ -8,6 +8,7 @@ import { DeviceId } from '../device/device-id.js'
 import { InvalidCredentialsError } from '../errors/invalid-credentials-error.js'
 import { InvalidRequestError } from '../errors/invalid-request-error.js'
 import { HCaptchaClient, HcaptchaVerifyResult } from '../lib/hcaptcha.js'
+import { callAsync } from '../lib/util/function.js'
 import { constantTime } from '../lib/util/time.js'
 import { OAuthHooks, RequestMetadata } from '../oauth-hooks.js'
 import { Customization } from '../oauth-provider.js'
@@ -20,6 +21,10 @@ import {
   ResetPasswordConfirmInput,
   ResetPasswordRequestInput,
   SignUpData,
+  UpdateEmailConfirmInput,
+  UpdateEmailRequestInput,
+  VerifyEmailConfirmInput,
+  VerifyEmailRequestInput,
 } from './account-store.js'
 import { SignInData } from './sign-in-data.js'
 import { SignUpInput } from './sign-up-input.js'
@@ -27,6 +32,8 @@ import { SignUpInput } from './sign-up-input.js'
 const TIMING_ATTACK_MITIGATION_DELAY = 400
 const BRUTE_FORCE_MITIGATION_DELAY = 300
 
+// @TODO Add rate limit to all the OAuth routes.
+
 export class AccountManager {
   protected readonly inviteCodeRequired: boolean
   protected readonly hcaptchaClient?: HCaptchaClient
@@ -119,42 +126,39 @@ export class AccountManager {
     deviceMetadata: RequestMetadata,
     input: SignUpInput,
   ): Promise<Account> {
-    await this.hooks.onSignUpAttempt?.call(null, {
-      input,
-      deviceId,
-      deviceMetadata,
-    })
-
-    const data = await this.buildSignupData(input, deviceId, deviceMetadata)
-
-    // Mitigation against brute forcing email of users.
-    // @TODO Add rate limit to all the OAuth routes.
-    const account = await constantTime(
-      BRUTE_FORCE_MITIGATION_DELAY,
-      async () => {
-        return this.store.createAccount(data)
-      },
-    ).catch((err) => {
-      throw InvalidRequestError.from(err, 'Account creation failed')
-    })
-
-    try {
-      await this.hooks.onSignedUp?.call(null, {
-        data,
-        account,
+    return constantTime(BRUTE_FORCE_MITIGATION_DELAY, async () => {
+      await this.hooks.onSignUpAttempt?.call(null, {
+        input,
         deviceId,
         deviceMetadata,
       })
 
-      return account
-    } catch (err) {
-      await this.removeDeviceAccount(deviceId, account.sub)
+      const data = await this.buildSignupData(input, deviceId, deviceMetadata)
 
-      throw InvalidRequestError.from(
-        err,
-        'The account was successfully created but something went wrong, try signing-in.',
-      )
-    }
+      const account = await callAsync(() =>
+        this.store.createAccount(data),
+      ).catch((err) => {
+        throw InvalidRequestError.from(err, 'Account creation failed')
+      })
+
+      try {
+        await this.hooks.onSignedUp?.call(null, {
+          data,
+          account,
+          deviceId,
+          deviceMetadata,
+        })
+
+        return account
+      } catch (err) {
+        await this.removeDeviceAccount(deviceId, account.sub)
+
+        throw InvalidRequestError.from(
+          err,
+          'The account was successfully created but something went wrong, try signing-in.',
+        )
+      }
+    })
   }
 
   public async authenticateAccount(
@@ -163,7 +167,7 @@ export class AccountManager {
     data: SignInData,
     clientId?: ClientId,
   ): Promise<Account> {
-    try {
+    return constantTime(TIMING_ATTACK_MITIGATION_DELAY, async () => {
       await this.hooks.onSignInAttempt?.call(null, {
         data,
         deviceId,
@@ -171,15 +175,9 @@ export class AccountManager {
         clientId,
       })
 
-      let account: Account
-      try {
-        account = await constantTime(
-          TIMING_ATTACK_MITIGATION_DELAY,
-          async () => {
-            return this.store.authenticateAccount(data)
-          },
-        )
-      } catch (err) {
+      const account = await callAsync(() =>
+        this.store.authenticateAccount(data),
+      ).catch(async (err) => {
         // Only notify for credential failures (e.g. unknown identifier, wrong
         // password). Server errors and flows that require an additional factor
         // (e.g. SecondAuthenticationFactorRequiredError) are not "failed
@@ -213,8 +211,9 @@ export class AccountManager {
             throw new InvalidRequestError(err.error_description)
           }
         }
+
         throw err
-      }
+      })
 
       await this.hooks.onSignedIn?.call(null, {
         data,
@@ -225,12 +224,12 @@ export class AccountManager {
       })
 
       return account
-    } catch (err) {
+    }).catch((err) => {
       throw InvalidRequestError.from(
         err,
         'Unable to sign-in due to an unexpected server error',
       )
-    }
+    })
   }
 
   public async upsertDeviceAccount(
@@ -294,18 +293,16 @@ export class AccountManager {
     deviceMetadata: RequestMetadata,
     input: ResetPasswordRequestInput,
   ) {
-    await this.hooks.onResetPasswordRequest?.call(null, {
-      input,
-      deviceId,
-      deviceMetadata,
-    })
-
     return constantTime(TIMING_ATTACK_MITIGATION_DELAY, async () => {
+      await this.hooks.onResetPasswordRequest?.call(null, {
+        input,
+        deviceId,
+        deviceMetadata,
+      })
+
       const account = await this.store.resetPasswordRequest(input)
 
-      if (!account) {
-        return // Silently ignore to prevent user enumeration
-      }
+      // @NOTE Do not throw here, to prevent user enumeration
 
       await this.hooks.onResetPasswordRequested?.call(null, {
         input,
@@ -321,13 +318,13 @@ export class AccountManager {
     deviceMetadata: RequestMetadata,
     input: ResetPasswordConfirmInput,
   ) {
-    await this.hooks.onResetPasswordConfirm?.call(null, {
-      input,
-      deviceId,
-      deviceMetadata,
-    })
-
     return constantTime(TIMING_ATTACK_MITIGATION_DELAY, async () => {
+      await this.hooks.onResetPasswordConfirm?.call(null, {
+        input,
+        deviceId,
+        deviceMetadata,
+      })
+
       const account = await this.store.resetPasswordConfirm(input)
 
       if (!account) {
@@ -340,6 +337,8 @@ export class AccountManager {
         deviceMetadata,
         account,
       })
+
+      return account
     })
   }
 
@@ -348,4 +347,110 @@ export class AccountManager {
       return this.store.verifyHandleAvailability(handle)
     })
   }
+
+  public async updateEmailRequest(
+    deviceId: DeviceId,
+    deviceMetadata: RequestMetadata,
+    input: UpdateEmailRequestInput,
+    account: Account,
+  ): Promise<{ tokenRequired: boolean }> {
+    await this.hooks.onChangeEmailRequest?.call(null, {
+      deviceId,
+      deviceMetadata,
+      input,
+      account,
+    })
+
+    const { tokenRequired } = await this.store.updateEmailRequest(input)
+
+    await this.hooks.onChangeEmailRequested?.call(null, {
+      deviceId,
+      deviceMetadata,
+      input,
+      account,
+    })
+
+    return { tokenRequired: tokenRequired === true }
+  }
+
+  public async updateEmailConfirm(
+    deviceId: DeviceId,
+    deviceMetadata: RequestMetadata,
+    input: UpdateEmailConfirmInput,
+    account: Account,
+  ): Promise<Account> {
+    await this.hooks.onUpdateEmailConfirm?.call(null, {
+      deviceId,
+      deviceMetadata,
+      input,
+      account,
+    })
+
+    const updatedAccount = await this.store.updateEmailConfirm(input)
+
+    if (!updatedAccount) {
+      throw new InvalidRequestError('Invalid token')
+    }
+
+    await this.hooks.onUpdateEmailConfirmed?.call(null, {
+      deviceId,
+      deviceMetadata,
+      input,
+      account: updatedAccount,
+    })
+
+    return updatedAccount
+  }
+
+  public async verifyEmailRequest(
+    deviceId: DeviceId,
+    deviceMetadata: RequestMetadata,
+    input: VerifyEmailRequestInput,
+    account: Account,
+  ): Promise<void> {
+    await this.hooks.onVerifyEmailRequest?.call(null, {
+      deviceId,
+      deviceMetadata,
+      input,
+      account,
+    })
+
+    await this.store.verifyEmailRequest(input)
+
+    await this.hooks.onVerifyEmailRequested?.call(null, {
+      deviceId,
+      deviceMetadata,
+      input,
+      account,
+    })
+  }
+
+  public async verifyEmailConfirm(
+    deviceId: DeviceId,
+    deviceMetadata: RequestMetadata,
+    input: VerifyEmailConfirmInput,
+    account: Account,
+  ): Promise<Account> {
+    await this.hooks.onVerifyEmailConfirm?.call(null, {
+      deviceId,
+      deviceMetadata,
+      input,
+      account,
+    })
+
+    const updatedAccount = await this.store.verifyEmailConfirm(input)
+
+    if (!updatedAccount) {
+      throw new InvalidRequestError('Invalid token')
+    }
+
+    await this.hooks.onVerifyEmailConfirmed?.call(null, {
+      deviceId,
+      deviceMetadata,
+      input,
+      account: updatedAccount,
+    })
+
+    return updatedAccount
+  }
 }

package/src/account/account-store.ts

@@ -1,6 +1,11 @@
 import type {
   Account,
+  ConfirmEmailUpdateInput,
+  ConfirmEmailVerificationInput,
   ConfirmResetPasswordInput,
+  InitiateEmailUpdateInput,
+  InitiateEmailUpdateOutput,
+  InitiateEmailVerificationInput,
   InitiatePasswordResetInput,
 } from '@atproto/oauth-provider-api'
 import { OAuthScope } from '@atproto/oauth-types'
@@ -45,6 +50,12 @@ export {
 export type ResetPasswordRequestInput = InitiatePasswordResetInput
 export type ResetPasswordConfirmInput = ConfirmResetPasswordInput
 
+export type UpdateEmailRequestInput = InitiateEmailUpdateInput
+export type UpdateEmailRequestOutput = InitiateEmailUpdateOutput
+export type UpdateEmailConfirmInput = ConfirmEmailUpdateInput
+export type VerifyEmailRequestInput = InitiateEmailVerificationInput
+export type VerifyEmailConfirmInput = ConfirmEmailVerificationInput
+
 export type CreateAccountData = {
   locale: string
   email: string
@@ -187,6 +198,20 @@ export interface AccountStore {
     data: ResetPasswordConfirmInput,
   ): Awaitable<null | Account>
 
+  updateEmailRequest(
+    data: UpdateEmailRequestInput,
+  ): Awaitable<UpdateEmailRequestOutput>
+  /**
+   * Must trigger a verification email to be sent to the new email address, that
+   * will then be confirmed through {@link updateEmailConfirm}. The account's
+   * `email_verified` field is expected to become `false` until the new email is
+   * confirmed.
+   */
+  updateEmailConfirm(data: UpdateEmailConfirmInput): Awaitable<Account | null>
+
+  verifyEmailRequest(data: VerifyEmailRequestInput): Awaitable<void>
+  verifyEmailConfirm(data: VerifyEmailConfirmInput): Awaitable<Account | null>
+
   /**
    * @throws {HandleUnavailableError} - To indicate that the handle is already taken
    */
@@ -204,6 +229,10 @@ export const isAccountStore = buildInterfaceChecker<AccountStore>([
   'listDeviceAccounts',
   'resetPasswordRequest',
   'resetPasswordConfirm',
+  'updateEmailRequest',
+  'updateEmailConfirm',
+  'verifyEmailRequest',
+  'verifyEmailConfirm',
   'verifyHandleAvailability',
 ])
 

package/src/oauth-hooks.ts

@@ -12,6 +12,10 @@ import {
   ResetPasswordConfirmInput,
   ResetPasswordRequestInput,
   SignUpData,
+  UpdateEmailConfirmInput,
+  UpdateEmailRequestInput,
+  VerifyEmailConfirmInput,
+  VerifyEmailRequestInput,
 } from './account/account-store.js'
 import { SignInData } from './account/sign-in-data.js'
 import { SignUpInput } from './account/sign-up-input.js'
@@ -87,6 +91,98 @@ export type OAuthHooks = {
     data: { metadata: OAuthClientMetadata; jwks?: Jwks },
   ) => Awaitable<undefined | Partial<ClientInfo>>
 
+  /**
+   * This hook is called when a user requests an email change, before the email
+   * change request is triggered on the account store. Only triggered with
+   * authenticated sessions, so the `account` is always available.
+   */
+  onChangeEmailRequest?: (data: {
+    input: UpdateEmailRequestInput
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called after a user requests an email change, and the email
+   * change request was successfully triggered on the account store.
+   */
+  onChangeEmailRequested?: (data: {
+    input: UpdateEmailRequestInput
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called when a user confirms an email change, before the email
+   * change is actually confirmed on the account store. Only triggered with
+   * authenticated sessions, so the `account` is always available.
+   */
+  onUpdateEmailConfirm?: (data: {
+    input: UpdateEmailConfirmInput
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called after a user confirms an email change, and the email
+   * change was successfully confirmed on the account store.
+   */
+  onUpdateEmailConfirmed?: (data: {
+    input: UpdateEmailConfirmInput
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called when a user requests an email verification, before the
+   * verification request is triggered on the account store. Only triggered with
+   * authenticated sessions, so the `account` is always available.
+   */
+  onVerifyEmailRequest?: (data: {
+    input: VerifyEmailRequestInput
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called after a user requests an email verification, and the
+   * verification request was successfully triggered on the account store.
+   */
+  onVerifyEmailRequested?: (data: {
+    input: VerifyEmailRequestInput
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called when a user confirms an email verification, before the
+   * verification is actually confirmed on the account store. Only triggered
+   * with authenticated sessions, so the `account` is always available.
+   */
+  onVerifyEmailConfirm?: (data: {
+    input: VerifyEmailConfirmInput
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called after a user confirms an email verification, and the
+   * verification was successfully confirmed on the account store.
+   */
+  onVerifyEmailConfirmed?: (data: {
+    input: VerifyEmailConfirmInput
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    account: Account
+  }) => Awaitable<void>
+
   /**
    * This hook is called when a user attempts to sign up, after every validation
    * has passed (including hcaptcha).
@@ -111,7 +207,8 @@ export type OAuthHooks = {
 
   /**
    * This hook is called when a user requests a password reset, before the
-   * reset password request is triggered on the account store.
+   * reset password request is triggered on the account store. Use this to
+   * potentially cancel the password reset.
    */
   onResetPasswordRequest?: (data: {
     input: ResetPasswordRequestInput
@@ -121,13 +218,14 @@ export type OAuthHooks = {
 
   /**
    * This hook is called when a user requests a password reset, before the
-   * reset password request is triggered on the account store.
+   * reset password request is triggered on the account store. If not account
+   * was found for the provided identifier, the `account` field will be `null`.
    */
   onResetPasswordRequested?: (data: {
     input: ResetPasswordRequestInput
     deviceId: DeviceId
     deviceMetadata: RequestMetadata
-    account: Account
+    account: Account | null
   }) => Awaitable<void>
 
   /**

package/src/router/create-api-middleware.ts

@@ -269,6 +269,110 @@ export function createApiMiddleware<
     }),
   )
 
+  router.use(
+    apiRoute({
+      method: 'POST',
+      endpoint: '/update-email-request',
+      schema: z
+        .object({
+          sub: subSchema,
+          locale: localeSchema.optional(),
+        })
+        .strict(),
+      async handler(req, res) {
+        const { account } = await authenticate.call(this, req, res)
+
+        const { tokenRequired } =
+          await server.accountManager.updateEmailRequest(
+            this.deviceId,
+            this.deviceMetadata,
+            this.input,
+            account,
+          )
+
+        return { json: { tokenRequired } }
+      },
+    }),
+  )
+
+  router.use(
+    apiRoute({
+      method: 'POST',
+      endpoint: '/update-email-confirm',
+      schema: z
+        .object({
+          sub: subSchema,
+          token: emailOtpSchema,
+          email: emailSchema,
+          locale: localeSchema.optional(),
+        })
+        .strict(),
+      async handler(req, res) {
+        const { account } = await authenticate.call(this, req, res)
+
+        await server.accountManager.updateEmailConfirm(
+          this.deviceId,
+          this.deviceMetadata,
+          this.input,
+          account,
+        )
+
+        return { json: { success: true } }
+      },
+    }),
+  )
+
+  router.use(
+    apiRoute({
+      method: 'POST',
+      endpoint: '/verify-email-request',
+      schema: z
+        .object({
+          sub: subSchema,
+          locale: localeSchema.optional(),
+        })
+        .strict(),
+      async handler(req, res) {
+        const { account } = await authenticate.call(this, req, res)
+
+        await server.accountManager.verifyEmailRequest(
+          this.deviceId,
+          this.deviceMetadata,
+          this.input,
+          account,
+        )
+
+        return { json: { success: true } }
+      },
+    }),
+  )
+
+  router.use(
+    apiRoute({
+      method: 'POST',
+      endpoint: '/verify-email-confirm',
+      schema: z
+        .object({
+          sub: subSchema,
+          token: emailOtpSchema,
+          email: emailSchema,
+        })
+        .strict(),
+      async handler(req, res) {
+        const { account } = await authenticate.call(this, req, res)
+
+        await server.accountManager.verifyEmailConfirm(
+          this.deviceId,
+          this.deviceMetadata,
+          this.input,
+          account,
+        )
+
+        return { json: { success: true } }
+      },
+    }),
+  )
+
   router.use(
     apiRoute({
       method: 'GET',