@atproto/oauth-provider 0.4.0 → 0.5.1

package/src/account/account-manager.ts

@@ -1,31 +1,164 @@
-import { isOAuthClientIdLoopback } from '@atproto/oauth-types'
+import {
+  OAuthIssuerIdentifier,
+  isOAuthClientIdLoopback,
+} from '@atproto/oauth-types'
 import { Client } from '../client/client.js'
 import { DeviceId } from '../device/device-id.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 { InvalidRequestError } from '../oauth-errors.js'
+import { OAuthHooks, RequestMetadata } from '../oauth-hooks.js'
+import { Customization } from '../oauth-provider.js'
 import { Sub } from '../oidc/sub.js'
 import { ClientAuth } from '../token/token-store.js'
 import {
   Account,
   AccountInfo,
   AccountStore,
-  SignInCredentials,
+  ResetPasswordConfirmData,
+  ResetPasswordRequestData,
 } from './account-store.js'
+import { SignInData } from './sign-in-data.js'
+import { SignUpData } from './sign-up-data.js'
 
 const TIMING_ATTACK_MITIGATION_DELAY = 400
+const BRUTE_FORCE_MITIGATION_DELAY = 300
 
 export class AccountManager {
-  constructor(protected readonly store: AccountStore) {}
+  protected readonly inviteCodeRequired: boolean
+  protected readonly hcaptchaClient?: HCaptchaClient
+
+  constructor(
+    issuer: OAuthIssuerIdentifier,
+    protected readonly store: AccountStore,
+    protected readonly hooks: OAuthHooks,
+    customization: Customization,
+  ) {
+    this.inviteCodeRequired = customization.inviteCodeRequired !== false
+    this.hcaptchaClient = customization.hcaptcha
+      ? new HCaptchaClient(new URL(issuer).hostname, customization.hcaptcha)
+      : undefined
+  }
+
+  protected async verifySignupData(
+    data: SignUpData,
+    deviceId: DeviceId,
+    deviceMetadata: RequestMetadata,
+  ): Promise<void> {
+    let hcaptchaResult: undefined | HcaptchaVerifyResult
+
+    if (this.inviteCodeRequired && !data.inviteCode) {
+      throw new InvalidRequestError('Invite code is required')
+    }
+
+    if (this.hcaptchaClient) {
+      if (!data.hcaptchaToken) {
+        throw new InvalidRequestError('hCaptcha token is required')
+      }
+
+      const { allowed, result } = await this.hcaptchaClient.verify(
+        'signup',
+        data.hcaptchaToken,
+        deviceMetadata.ipAddress,
+        data.handle,
+        deviceMetadata.userAgent,
+      )
+
+      await callAsync(this.hooks.onSignupHcaptchaResult, {
+        data,
+        allowed,
+        result,
+        deviceId,
+        deviceMetadata,
+      })
+
+      if (!allowed) {
+        throw new InvalidRequestError('hCaptcha verification failed')
+      }
+
+      hcaptchaResult = result
+    }
+
+    await callAsync(this.hooks.onSignupAttempt, {
+      data,
+      deviceId,
+      deviceMetadata,
+      hcaptchaResult,
+    })
+  }
+
+  public async signUp(
+    data: SignUpData,
+    deviceId: DeviceId,
+    deviceMetadata: RequestMetadata,
+  ): Promise<AccountInfo> {
+    await this.verifySignupData(data, deviceId, deviceMetadata)
+
+    // Mitigation against brute forcing email of users.
+    // @TODO Add rate limit to all the OAuth routes.
+    return constantTime(BRUTE_FORCE_MITIGATION_DELAY, async () => {
+      let account: Account
+      try {
+        account = await this.store.createAccount(data)
+      } catch (err) {
+        throw InvalidRequestError.from(err, 'Account creation failed')
+      }
+
+      try {
+        const info = await this.store.addDeviceAccount(
+          deviceId,
+          account.sub,
+          false,
+        )
+
+        await callAsync(this.hooks.onSignedUp, {
+          data,
+          info,
+          account,
+          deviceId,
+          deviceMetadata,
+        })
+
+        return { account, info }
+      } catch (err) {
+        throw InvalidRequestError.from(
+          err,
+          'Something went wrong, try singing-in',
+        )
+      }
+    })
+  }
 
   public async signIn(
-    credentials: SignInCredentials,
+    data: SignInData,
     deviceId: DeviceId,
+    deviceMetadata: RequestMetadata,
   ): Promise<AccountInfo> {
     return constantTime(TIMING_ATTACK_MITIGATION_DELAY, async () => {
-      const result = await this.store.authenticateAccount(credentials, deviceId)
-      if (result) return result
+      try {
+        const account = await this.store.authenticateAccount(data)
+        const info = await this.store.addDeviceAccount(
+          deviceId,
+          account.sub,
+          data.remember,
+        )
 
-      throw new InvalidRequestError('Invalid credentials')
+        await callAsync(this.hooks.onSignedIn, {
+          data,
+          info,
+          account,
+          deviceId,
+          deviceMetadata,
+        })
+
+        return { account, info }
+      } catch (err) {
+        throw InvalidRequestError.from(
+          err,
+          'Unable to sign-in due to an unexpected server error',
+        )
+      }
     })
   }
 
@@ -52,4 +185,22 @@ export class AccountManager {
     const results = await this.store.listDeviceAccounts(deviceId)
     return results.filter((result) => result.info.remembered)
   }
+
+  public async resetPasswordRequest(data: ResetPasswordRequestData) {
+    return constantTime(TIMING_ATTACK_MITIGATION_DELAY, async () => {
+      await this.store.resetPasswordRequest(data)
+    })
+  }
+
+  public async resetPasswordConfirm(data: ResetPasswordConfirmData) {
+    return constantTime(TIMING_ATTACK_MITIGATION_DELAY, async () => {
+      await this.store.resetPasswordConfirm(data)
+    })
+  }
+
+  public async verifyHandleAvailability(handle: string): Promise<void> {
+    return constantTime(TIMING_ATTACK_MITIGATION_DELAY, async () => {
+      return this.store.verifyHandleAvailability(handle)
+    })
+  }
 }

package/src/account/account-store.ts

@@ -1,25 +1,86 @@
+import { isEmailValid } from '@hapi/address'
+import { isDisposableEmail } from 'disposable-email-domains-js'
 import { z } from 'zod'
 import { ClientId } from '../client/client-id.js'
 import { DeviceId } from '../device/device-id.js'
-import { Awaitable } from '../lib/util/type.js'
+import { localeSchema } from '../lib/locale.js'
+import { Awaitable, buildInterfaceChecker } from '../lib/util/type.js'
+import {
+  HandleUnavailableError,
+  InvalidRequestError,
+  SecondAuthenticationFactorRequiredError,
+} from '../oauth-errors.js'
 import { Sub } from '../oidc/sub.js'
 import { Account } from './account.js'
 
-export const signInCredentialsSchema = z.object({
-  username: z.string(),
-  password: z.string(),
+// @NOTE Change the length here to force stronger passwords (through a reset)
+export const oldPasswordSchema = z.string().min(1)
+export const newPasswordSchema = z.string().min(8)
+export const tokenSchema = z.string().regex(/^[A-Z2-7]{5}-[A-Z2-7]{5}$/)
+export const handleSchema = z
+  .string()
+  .min(3)
+  .max(30)
+  .regex(/^[a-z0-9][a-z0-9-]+[a-z0-9](?:\.[a-z0-9][a-z0-9-]+[a-z0-9])+$/)
+export const emailSchema = z
+  .string()
+  .email()
+  // @NOTE using @hapi/address here, in addition to the email() check to ensure
+  // compatibility with the current email validation in the PDS's account
+  // manager
+  .refine(isEmailValid, {
+    message: 'Invalid email address',
+  })
+  .refine((email) => !isDisposableEmail(email), {
+    message: 'Disposable email addresses are not allowed',
+  })
 
-  /**
-   * If false, the account must not be returned from
-   * {@link AccountStore.listDeviceAccounts}. Note that this only makes sense when
-   * used with a device ID.
-   */
-  remember: z.boolean().optional().default(false),
+export const authenticateAccountDataSchema = z
+  .object({
+    locale: localeSchema,
+    username: z.string(),
+    password: oldPasswordSchema,
+    emailOtp: z.string().optional(),
+  })
+  .strict()
+
+export type AuthenticateAccountData = z.TypeOf<
+  typeof authenticateAccountDataSchema
+>
+
+export const createAccountDataSchema = z
+  .object({
+    locale: localeSchema,
+    handle: handleSchema,
+    email: emailSchema,
+    password: z.intersection(oldPasswordSchema, newPasswordSchema),
+    inviteCode: tokenSchema.optional(),
+  })
+  .strict()
+
+export type CreateAccountData = z.TypeOf<typeof createAccountDataSchema>
+
+export const resetPasswordRequestDataSchema = z
+  .object({
+    locale: localeSchema,
+    email: emailSchema,
+  })
+  .strict()
+
+export type ResetPasswordRequestData = z.TypeOf<
+  typeof resetPasswordRequestDataSchema
+>
 
-  emailOtp: z.string().optional(),
-})
+export const resetPasswordConfirmDataSchema = z
+  .object({
+    token: tokenSchema,
+    password: z.intersection(oldPasswordSchema, newPasswordSchema),
+  })
+  .strict()
 
-export type SignInCredentials = z.TypeOf<typeof signInCredentialsSchema>
+export type ResetPasswordConfirmData = z.TypeOf<
+  typeof resetPasswordConfirmDataSchema
+>
 
 export type DeviceAccountInfo = {
   remembered: boolean
@@ -28,7 +89,14 @@ export type DeviceAccountInfo = {
 }
 
 // Export all types needed to implement the AccountStore interface
-export type { Account, DeviceId, Sub }
+export {
+  type Account,
+  type DeviceId,
+  HandleUnavailableError,
+  InvalidRequestError,
+  SecondAuthenticationFactorRequiredError,
+  type Sub,
+}
 
 export type AccountInfo = {
   account: Account
@@ -36,10 +104,17 @@ export type AccountInfo = {
 }
 
 export interface AccountStore {
-  authenticateAccount(
-    credentials: SignInCredentials,
-    deviceId: DeviceId,
-  ): Awaitable<AccountInfo | null>
+  /**
+   * @throws {HandleUnavailableError} - To indicate that the handle is already taken
+   * @throws {InvalidRequestError} - To indicate that some data is invalid
+   */
+  createAccount(data: CreateAccountData): Awaitable<Account>
+
+  /**
+   * @throws {InvalidRequestError} - When the credentials are not valid
+   * @throws {SecondAuthenticationFactorRequiredError} - To indicate that an {@link SecondAuthenticationFactorRequiredError.type} is required in the credentials
+   */
+  authenticateAccount(data: AuthenticateAccountData): Awaitable<Account>
 
   addAuthorizedClient(
     deviceId: DeviceId,
@@ -47,6 +122,19 @@ export interface AccountStore {
     clientId: ClientId,
   ): Awaitable<void>
 
+  /**
+   * @param remember If false, the account must not be returned from
+   * {@link AccountStore.listDeviceAccounts}.
+   */
+  addDeviceAccount(
+    deviceId: DeviceId,
+    sub: Sub,
+    remember: boolean,
+  ): Awaitable<DeviceAccountInfo>
+
+  /**
+   * @returns The account info, whether the account, even if remember was false.
+   */
   getDeviceAccount(deviceId: DeviceId, sub: Sub): Awaitable<AccountInfo | null>
   removeDeviceAccount(deviceId: DeviceId, sub: Sub): Awaitable<void>
 
@@ -55,23 +143,30 @@ export interface AccountStore {
    * be returned. The others will be ignored.
    */
   listDeviceAccounts(deviceId: DeviceId): Awaitable<AccountInfo[]>
-}
 
-export function isAccountStore(
-  implementation: Record<string, unknown> & Partial<AccountStore>,
-): implementation is Record<string, unknown> & AccountStore {
-  return (
-    typeof implementation.authenticateAccount === 'function' &&
-    typeof implementation.getDeviceAccount === 'function' &&
-    typeof implementation.addAuthorizedClient === 'function' &&
-    typeof implementation.listDeviceAccounts === 'function' &&
-    typeof implementation.removeDeviceAccount === 'function'
-  )
+  resetPasswordRequest(data: ResetPasswordRequestData): Awaitable<void>
+  resetPasswordConfirm(data: ResetPasswordConfirmData): Awaitable<void>
+
+  /**
+   * @throws {HandleUnavailableError} - To indicate that the handle is already taken
+   */
+  verifyHandleAvailability(handle: string): Awaitable<void>
 }
 
-export function asAccountStore(
-  implementation?: Record<string, unknown> & Partial<AccountStore>,
-): AccountStore {
+export const isAccountStore = buildInterfaceChecker<AccountStore>([
+  'createAccount',
+  'authenticateAccount',
+  'addAuthorizedClient',
+  'addDeviceAccount',
+  'getDeviceAccount',
+  'removeDeviceAccount',
+  'listDeviceAccounts',
+  'resetPasswordRequest',
+  'resetPasswordConfirm',
+  'verifyHandleAvailability',
+])
+
+export function asAccountStore<V>(implementation: V): V & AccountStore {
   if (!implementation || !isAccountStore(implementation)) {
     throw new Error('Invalid AccountStore implementation')
   }

package/src/account/sign-in-data.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+import { authenticateAccountDataSchema } from './account-store.js'
+
+export const signInDataSchema = authenticateAccountDataSchema
+  .extend({
+    /**
+     * If false, the account must not be returned from
+     * {@link AccountStore.listDeviceAccounts}. Note that this only makes sense when
+     * used with a device ID.
+     */
+    remember: z.boolean().optional().default(false),
+  })
+  .strict()
+
+export type SignInData = z.TypeOf<typeof signInDataSchema>

package/src/account/sign-up-data.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod'
+import { hcaptchaTokenSchema } from '../lib/hcaptcha.js'
+import { createAccountDataSchema } from './account-store.js'
+
+export const signUpDataSchema = createAccountDataSchema
+  .extend({
+    hcaptchaToken: hcaptchaTokenSchema.optional(),
+  })
+  .strict()
+
+export type SignUpData = z.TypeOf<typeof signUpDataSchema>

package/src/assets/app/app.tsx

@@ -1,28 +1,43 @@
+import { ErrorBoundary } from 'react-error-boundary'
 import type {
   AuthorizeData,
+  AvailableLocales,
   CustomizationData,
   ErrorData,
-} from './backend-data'
-import { AuthorizeView } from './views/authorize-view'
-import { ErrorView } from './views/error-view'
+} from './backend-types.ts'
+import { LocaleProvider } from './locales/locale-provider.tsx'
+import { AuthorizeView } from './views/authorize/authorize-view.tsx'
+import { ErrorView } from './views/error/error-view.tsx'
 
 export type AppProps = {
+  availableLocales?: AvailableLocales
   authorizeData?: AuthorizeData
   customizationData?: CustomizationData
   errorData?: ErrorData
 }
 
-export function App({ authorizeData, customizationData, errorData }: AppProps) {
-  if (authorizeData && !errorData) {
-    return (
-      <AuthorizeView
-        customizationData={customizationData}
-        authorizeData={authorizeData}
-      />
-    )
-  } else {
-    return (
-      <ErrorView customizationData={customizationData} errorData={errorData} />
-    )
-  }
+export function App({
+  availableLocales,
+  authorizeData,
+  customizationData,
+  errorData,
+}: AppProps) {
+  return (
+    <LocaleProvider availableLocales={availableLocales}>
+      <ErrorBoundary
+        fallbackRender={({ error }) => (
+          <ErrorView error={error} customizationData={customizationData} />
+        )}
+      >
+        {errorData || !authorizeData ? (
+          <ErrorView error={errorData} customizationData={customizationData} />
+        ) : (
+          <AuthorizeView
+            customizationData={customizationData}
+            authorizeData={authorizeData}
+          />
+        )}
+      </ErrorBoundary>
+    </LocaleProvider>
+  )
 }

package/src/assets/app/backend-data.ts

@@ -1,72 +1,27 @@
-import { OAuthClientMetadata } from '@atproto/oauth-types'
-
-// TODO: Find a way to share these types with the backend code
-
-export type Account = {
-  sub: string
-  aud: string
-
-  email?: string
-  name?: string
-  preferred_username?: string
-  picture?: string
-}
-
-export type Session = {
-  account: Account
-  info?: never // Prevent relying on this in the frontend
-
-  selected: boolean
-  loginRequired: boolean
-  consentRequired: boolean
-}
-
-export type LinkDefinition = {
-  title: string
-  href: string
-  rel?: string
-}
-
-export type CustomizationData = {
-  name?: string
-  logo?: string
-  links?: LinkDefinition[]
-}
-
-export type ErrorData = {
-  error: string
-  error_description: string
-}
-
-export type ScopeDetail = {
-  scope: string
-  description?: string
-}
-
-export type AuthorizeData = {
-  clientId: string
-  clientMetadata: OAuthClientMetadata
-  clientTrusted: boolean
-  requestUri: string
-  csrfCookie: string
-  loginHint?: string
-  scopeDetails?: ScopeDetail[]
-  newSessionsRequireConsent: boolean
-  sessions: Session[]
-}
-
-// see "declareBackendData()" in the backend
-const readBackendData = <T>(key: string): T | undefined => {
+import {
+  AuthorizeData,
+  AvailableLocales,
+  CustomizationData,
+  ErrorData,
+} from './backend-types.ts'
+
+function readBackendData<T>(key: string): T | undefined {
   const value = window[key] as T | undefined
   delete window[key] // Prevent accidental usage / potential leaks to dependencies
   return value
 }
 
 // These values are injected by the backend when it builds the
-// page HTML.
+// page HTML. See "declareBackendData()" in the backend.
 
+/** @deprecated Do not import directly. Only import this from main.tsx */
+export const availableLocales =
+  readBackendData<AvailableLocales>('__availableLocales')
+/** @deprecated Do not import directly. Only import this from main.tsx */
 export const customizationData = readBackendData<CustomizationData>(
   '__customizationData',
 )
+/** @deprecated Do not import directly. Only import this from main.tsx */
 export const errorData = readBackendData<ErrorData>('__errorData')
+/** @deprecated Do not import directly. Only import this from main.tsx */
 export const authorizeData = readBackendData<AuthorizeData>('__authorizeData')

package/src/assets/app/backend-types.ts

@@ -0,0 +1,66 @@
+import type { OAuthClientMetadata } from '@atproto/oauth-types'
+
+// @TODO: Find a way to share these types with the backend code
+
+export type Account = {
+  sub: string
+  aud: string | [string, ...string[]]
+
+  email?: string
+  email_verified?: boolean
+  name?: string
+  preferred_username?: string
+  picture?: string
+}
+
+export type Session = {
+  account: Account
+  info?: never // Prevent relying on this in the frontend
+
+  selected: boolean
+  loginRequired: boolean
+  consentRequired: boolean
+}
+
+export type LocalizedString = string | ({ en: string } & Record<string, string>)
+
+export type AvailableLocales = readonly string[]
+
+export type LinkDefinition = {
+  title: LocalizedString
+  href: string
+  rel?: string
+}
+
+export type CustomizationData = {
+  // Functional customization
+  hcaptchaSiteKey?: string
+  inviteCodeRequired?: boolean
+  availableUserDomains?: string[]
+
+  // Aesthetic customization
+  name?: string
+  logo?: string
+  links?: LinkDefinition[]
+}
+
+export type ErrorData = {
+  error: string
+  error_description: string
+}
+
+export type ScopeDetail = {
+  scope: string
+  description?: string
+}
+
+export type AuthorizeData = {
+  clientId: string
+  clientMetadata: OAuthClientMetadata
+  clientTrusted: boolean
+  requestUri: string
+  loginHint?: string
+  scopeDetails?: ScopeDetail[]
+  newSessionsRequireConsent: boolean
+  sessions: Session[]
+}

package/src/assets/app/components/forms/button-toggle-visibility.tsx

@@ -0,0 +1,43 @@
+import { useLingui } from '@lingui/react/macro'
+import { Override } from '../../lib/util.ts'
+import { EyeIcon, EyeSlashIcon } from '../utils/icons.tsx'
+import { Button, ButtonProps } from './button.tsx'
+
+export type ButtonToggleVisibilityProps = Override<
+  Omit<ButtonProps, 'aria-label' | 'square'>,
+  {
+    visible: boolean
+    toggleVisible: () => void
+  }
+>
+
+/**
+ * Generic button to toggle visibility of an item (e.g. password).
+ */
+export function ButtonToggleVisibility({
+  visible,
+  toggleVisible,
+
+  // button
+  onClick,
+  ...props
+}: ButtonToggleVisibilityProps) {
+  const { t } = useLingui()
+  return (
+    <Button
+      {...props}
+      square
+      onClick={(event) => {
+        onClick?.(event)
+        if (!event.defaultPrevented) toggleVisible()
+      }}
+      aria-label={visible ? t`Hide` : t`Make visible`}
+    >
+      {visible ? (
+        <EyeIcon className="w-5" aria-hidden />
+      ) : (
+        <EyeSlashIcon className="w-5" aria-hidden />
+      )}
+    </Button>
+  )
+}