@atproto/oauth-provider 0.3.1 → 0.5.0

package/src/lib/util/type.ts

@@ -1,4 +1,133 @@
 // eslint-disable-next-line @typescript-eslint/ban-types
 export type Simplify<T> = { [K in keyof T]: T[K] } & {}
-export type Override<T, V> = Simplify<V & Omit<T, keyof V>>
+export type Override<T, V> = Simplify<{
+  [K in keyof (V & T)]: K extends keyof V
+    ? V[K]
+    : K extends keyof T
+      ? T[K]
+      : never
+}>
 export type Awaitable<T> = T | Promise<T>
+
+/**
+ * Similar to {@link Required} but also ensures that all values are defined.
+ */
+export type RequiredDefined<T> = { [K in keyof T]-?: Exclude<T[K], undefined> }
+
+// <hardcore-mode> (don't touch this)
+
+/**
+ * @example
+ * ```ts
+ * type F = UnionToFnUnion<'a' | 'b'> // (() => 'a') | (() => 'b')
+ * ```
+ */
+type UnionToFnUnion<T> = T extends any ? () => T : never
+
+/**
+ * @example
+ * ```ts
+ * type A = UnionToIntersection<(() => 'a') | (() => 'b')> // (() => 'a') & (() => 'b')
+ *
+ * UnionToIntersection<{ foo: string | number } | { foo: number; bar: 4 }> // { foo: number; bar: 4 }
+ * ```
+ */
+type UnionToIntersection<T> = (T extends any ? (x: T) => void : never) extends (
+  x: infer U,
+) => void
+  ? U
+  : never
+
+/**
+ * @example
+ * ```ts
+ * type B = ExtractUnionItem<'a' | 'b'> // 'b'
+ * ```
+ */
+type ExtractUnionItem<T> =
+  // There exists a quirk in the way TypeScript works when inferring return
+  // types of an (disjoined) intersection of functions:
+  //
+  // type AnB = (() => 'a') & (() => 'b')
+  // type B = AnB extends () => infer R ? R : never // 'b'
+  //
+  // By turning the input union T (e.g. 'a' | 'b') into a union of function
+  // (() => 'a') | (() => 'b') and then into an intersection of those functions
+  // (() => 'a') & (() => 'b'), we can exploit the special TypeScript behavior
+  // to infer only the last return type from the functions, which is effectively
+  // equal to the last item of the input union T.
+  UnionToIntersection<UnionToFnUnion<T>> extends () => infer R ? R : never
+
+/**
+ * Utility that turn a union of types (`'a' | 'b'`) into a tuple with matching
+ * types (`['a', 'b']`).
+ *
+ * @note this only work with unions of "const" types. Using this with globals
+ * types (`string`, etc.) will yield unexpected results.
+ *
+ * @example
+ * ```ts
+ * type T = UnionToTuple<'a' | 'b'> // ['a', 'b']
+ * type T = UnionToTuple<'a' | 'b' | 'c'> // ['a', 'b', 'c']
+ * ```
+ */
+type UnionToTuple<T> = UnionToTupleInternal<T>
+
+type UnionToTupleInternal<
+  T,
+  // Accumulator for terminal recursivity (initialized to empty tuple)
+  Acc extends readonly any[] = [],
+  // Get the next item from the union (if any)
+  Next = ExtractUnionItem<T>,
+> =
+  // If there were no more items to extract from the union T, then we are done
+  [Next] extends [never]
+    ? // Return result of previous recursive calls
+      Acc
+    : // Recursively call UnionToTupleInternal by Exclude'ing the Next item from
+      // the union (T) and adding it to the accumulator.
+      UnionToTupleInternal<Exclude<T, Next>, readonly [Next, ...Acc]>
+
+/**
+ * This utility allows to create an assertion function that checks if a
+ * particular interface is fully implemented by some value.
+ *
+ * The use of the (rather complex) {@link UnionToTuple} allows to ensure that,
+ * at runtime, all the required interface keys are indeed checked, and that
+ * future additions to the interface do not result in a false sense of type
+ * safety.
+ *
+ * @note This function should not be made public, as it relies on a quirk of
+ * TypeScript to work properly.
+ *
+ * @example Valid use
+ *
+ * ```ts
+ * const isFoo = buildInterfaceChecker<{ foo: string }>(['foo'])
+ * const isFooBar = buildInterfaceChecker<{ foo: string; bar: boolean }>([
+ *   'foo',
+ *   'bar',
+ * ])
+ *
+ * declare const val: { foo?: string }
+ *
+ * if (isFoo(val)) {
+ *   val // { foo: string }
+ * }
+ * ```
+ *
+ * @example Use cases where the runtime keys do not match the interface keys
+ *
+ * ```ts
+ * buildInterfaceChecker<{ foo: string }>([])
+ * buildInterfaceChecker<{ foo: string }>(['fee'])
+ * buildInterfaceChecker<{ foo: string; bar: string }>(['foo'])
+ * buildInterfaceChecker<{ foo: string; bar: string }>(['foo', 'baz'])
+ * ```
+ */
+export const buildInterfaceChecker =
+  <I extends object>(keys: readonly string[] & UnionToTuple<keyof I>) =>
+  <V extends Partial<I>>(value: V): value is V & RequiredDefined<I> =>
+    keys.every((name) => value[name] !== undefined)
+
+// </hardcore-mode>

package/src/metadata/build-metadata.ts

@@ -1,6 +1,7 @@
 import { Keyset } from '@atproto/jwk'
 import {
   OAuthAuthorizationServerMetadata,
+  OAuthIssuerIdentifier,
   oauthAuthorizationServerMetadataSchema,
 } from '@atproto/oauth-types'
 import { Client } from '../client/client.js'
@@ -17,7 +18,7 @@ export type CustomMetadata = {
  * @see {@link https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata}
  */
 export function buildMetadata(
-  issuer: string,
+  issuer: OAuthIssuerIdentifier,
   keyset: Keyset,
   customMetadata?: CustomMetadata,
 ): OAuthAuthorizationServerMetadata {

package/src/oauth-errors.ts

@@ -4,6 +4,7 @@ export { OAuthError } from './errors/oauth-error.js'
 export { AccessDeniedError } from './errors/access-denied-error.js'
 export { AccountSelectionRequiredError } from './errors/account-selection-required-error.js'
 export { ConsentRequiredError } from './errors/consent-required-error.js'
+export { HandleUnavailableError } from './errors/handle-unavailable-error.js'
 export { InvalidAuthorizationDetailsError } from './errors/invalid-authorization-details-error.js'
 export { InvalidClientError } from './errors/invalid-client-error.js'
 export { InvalidClientIdError } from './errors/invalid-client-id-error.js'

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.
    *