@atproto/oauth-provider 0.4.0 → 0.5.0

package/src/oauth-hooks.ts

@@ -6,15 +6,18 @@ import {
   OAuthTokenResponse,
 } from '@atproto/oauth-types'
 import { Account } from './account/account.js'
+import { SignInData } from './account/sign-in-data.js'
+import { SignUpData } from './account/sign-up-data.js'
 import { ClientAuth } from './client/client-auth.js'
 import { ClientId } from './client/client-id.js'
 import { ClientInfo } from './client/client-info.js'
 import { Client } from './client/client.js'
-import { InvalidAuthorizationDetailsError } from './errors/invalid-authorization-details-error.js'
+import { InvalidRequestError } from './errors/invalid-request-error.js'
+import { HcaptchaConfig, HcaptchaVerifyResult } from './lib/hcaptcha.js'
 import { RequestMetadata } from './lib/http/request.js'
 import { Awaitable } from './lib/util/type.js'
 import { AccessDeniedError, OAuthError } from './oauth-errors.js'
-import { DeviceId } from './oauth-store.js'
+import { DeviceAccountInfo, DeviceId } from './oauth-store.js'
 
 // Make sure all types needed to implement the OAuthHooks are exported
 export {
@@ -25,8 +28,11 @@ export {
   type ClientAuth,
   type ClientId,
   type ClientInfo,
+  type DeviceAccountInfo,
   type DeviceId,
-  InvalidAuthorizationDetailsError,
+  type HcaptchaConfig,
+  type HcaptchaVerifyResult,
+  InvalidRequestError,
   type Jwks,
   type OAuthAuthorizationDetails,
   type OAuthAuthorizationRequestParameters,
@@ -34,6 +40,8 @@ export {
   OAuthError,
   type OAuthTokenResponse,
   type RequestMetadata,
+  type SignInData,
+  type SignUpData,
 }
 
 export type OAuthHooks = {
@@ -63,6 +71,64 @@ export type OAuthHooks = {
     account: Account
   }) => Awaitable<undefined | OAuthAuthorizationDetails>
 
+  /**
+   * This hook is called whenever an hcaptcha challenge is verified
+   * during sign-up (if hcaptcha is enabled).
+   *
+   * @throws {InvalidRequestError} to deny the sign-up
+   */
+  onSignupHcaptchaResult?: (data: {
+    data: SignUpData
+    /**
+     * This indicates not only wether the hCaptcha challenge succeeded, but also
+     * if the score was low enough according to the
+     * {@link HcaptchaConfig.scoreThreshold}.
+     *
+     * @see {@link HCaptchaClient.isAllowed}
+     */
+    allowed: boolean
+    result: HcaptchaVerifyResult
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called when a user attempts to sign up, after every validation
+   * has passed (including hcaptcha).
+   */
+  onSignupAttempt?: (data: {
+    data: SignUpData
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+    hcaptchaResult?: HcaptchaVerifyResult
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called when a user successfully signs up.
+   *
+   * @throws {AccessDeniedError} to deny the sign-up
+   */
+  onSignedUp?: (data: {
+    data: SignUpData
+    info: DeviceAccountInfo
+    account: Account
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+  }) => Awaitable<void>
+
+  /**
+   * This hook is called when a user successfully signs in.
+   *
+   * @throws {InvalidRequestError} when the sing-in should be denied
+   */
+  onSignedIn?: (data: {
+    data: SignInData
+    info: DeviceAccountInfo
+    account: Account
+    deviceId: DeviceId
+    deviceMetadata: RequestMetadata
+  }) => Awaitable<void>
+
   /**
    * This hook is called when a client is authorized.
    *