@atproto/oauth-provider 0.6.6 → 0.7.0

package/src/account/account-store.ts

@@ -1,11 +1,13 @@
-import { isEmailValid } from '@hapi/address'
-import { isDisposableEmail } from 'disposable-email-domains-js'
-import { z } from 'zod'
-import { ensureValidHandle, normalizeHandle } from '@atproto/syntax'
+import {
+  Account,
+  ConfirmResetPasswordInput,
+  InitiatePasswordResetInput,
+} from '@atproto/oauth-provider-api'
+import { OAuthScope } from '@atproto/oauth-types'
 import { ClientId } from '../client/client-id.js'
 import { DeviceId } from '../device/device-id.js'
+import { DeviceData } from '../device/device-store.js'
 import { HcaptchaVerifyResult } from '../lib/hcaptcha.js'
-import { localeSchema } from '../lib/locale.js'
 import { Awaitable, buildInterfaceChecker } from '../lib/util/type.js'
 import {
   HandleUnavailableError,
@@ -13,112 +15,83 @@ import {
   SecondAuthenticationFactorRequiredError,
 } from '../oauth-errors.js'
 import { Sub } from '../oidc/sub.js'
-import { Account } from './account.js'
+import { InviteCode } from '../types/invite-code.js'
 import { SignUpInput } from './sign-up-input.js'
 
-// @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}$/, 'Invalid token format')
-export const handleSchema = z
-  .string()
-  // @NOTE: We only check against validity towards ATProto's syntax. Additional
-  // rules may be imposed by the store implementation.
-  .superRefine((value, ctx) => {
-    try {
-      ensureValidHandle(value)
-    } catch (err) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: err instanceof Error ? err.message : 'Invalid handle',
-      })
-    }
-  })
-  .transform(normalizeHandle)
-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',
-  })
-  .transform((value) => value.toLowerCase())
-export const inviteCodeSchema = z.string().min(1)
-export type InviteCode = z.infer<typeof inviteCodeSchema>
-
-export const authenticateAccountDataSchema = z
-  .object({
-    locale: localeSchema,
-    username: z.string(),
-    password: oldPasswordSchema,
-    emailOtp: tokenSchema.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: inviteCodeSchema.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
->
-
-export const resetPasswordConfirmDataSchema = z
-  .object({
-    token: tokenSchema,
-    password: z.intersection(oldPasswordSchema, newPasswordSchema),
-  })
-  .strict()
-
-export type ResetPasswordConfirmData = z.TypeOf<
-  typeof resetPasswordConfirmDataSchema
->
-
-export type DeviceAccountInfo = {
-  remembered: boolean
-  authenticatedAt: Date
-  authorizedClients: readonly ClientId[]
+// Export all types needed to implement the AccountStore interface
+
+export * from '../client/client-id.js'
+export * from '../device/device-data.js'
+export * from '../device/device-id.js'
+export * from '../oidc/sub.js'
+export * from '../request/request-id.js'
+
+export type {
+  Account,
+  HcaptchaVerifyResult,
+  InviteCode,
+  OAuthScope,
+  SignUpInput,
 }
 
-// Export all types needed to implement the AccountStore interface
 export {
-  type Account,
-  type DeviceId,
   HandleUnavailableError,
   InvalidRequestError,
   SecondAuthenticationFactorRequiredError,
-  type Sub,
 }
 
-export type AccountInfo = {
+export type ResetPasswordRequestData = InitiatePasswordResetInput
+export type ResetPasswordConfirmData = ConfirmResetPasswordInput
+export type CreateAccountData = {
+  locale: string
+  email: string
+  password: string
+  handle: string
+  inviteCode?: string | undefined
+}
+
+export type AuthenticateAccountData = {
+  locale: string
+  password: string
+  username: string
+  emailOtp?: string | undefined
+}
+
+export type AuthorizedClientData = { authorizedScopes: readonly string[] }
+export type AuthorizedClients = Map<ClientId, AuthorizedClientData>
+
+export type DeviceAccount = {
+  deviceId: DeviceId
+
+  /**
+   * The data associated with the device, created through the
+   * {@link DeviceStore}. This data is used to identify devices on which a user
+   * has logged in.
+   */
+  deviceData: DeviceData
+
+  /**
+   * The account associated with the device account.
+   */
   account: Account
-  info: DeviceAccountInfo
+
+  /**
+   * The list of clients that are authorized by the account, as created through
+   * the {@link AccountStore.setAuthorizedClient} method.
+   */
+  authorizedClients: AuthorizedClients
+
+  /**
+   * The date at which the device account was created. This value is currently
+   * not used.
+   */
+  createdAt: Date
+
+  /**
+   * The date at which the device account was last updated. This value is used
+   * to determine the date at which the user last authenticated on a device
+   */
+  updatedAt: Date
 }
 
 export type SignUpData = SignUpInput & {
@@ -139,33 +112,63 @@ export interface AccountStore {
    */
   authenticateAccount(data: AuthenticateAccountData): Awaitable<Account>
 
-  addAuthorizedClient(
-    deviceId: DeviceId,
+  /**
+   * Add a client & scopes to the list of authorized clients for the given account.
+   */
+  setAuthorizedClient(
     sub: Sub,
     clientId: ClientId,
+    data: AuthorizedClientData,
   ): Awaitable<void>
 
   /**
-   * @param remember If false, the account must not be returned from
-   * {@link AccountStore.listDeviceAccounts}.
+   * @throws {InvalidRequestError} - When the credentials are not valid
+   */
+  getAccount(sub: Sub): Awaitable<{
+    account: Account
+    authorizedClients: AuthorizedClients
+  }>
+
+  /**
+   * @param data.requestId - If provided, the inserted account must be bound to
+   * that particular requestId.
+   *
+   * @note Whenever a particular device account is created, all **unbound**
+   * device accounts for the same `deviceId` & `sub` should be deleted.
+   *
+   * @note When a particular request is deleted (through
+   * {@link RequestStore.deleteRequest}), all accounts bound to that request
+   * should be deleted as well.
+   */
+  upsertDeviceAccount(deviceId: DeviceId, sub: Sub): Awaitable<void>
+
+  /**
+   * @param requestId - If provided, the result must either have the same
+   * requestId, or not be bound to a particular requestId. If `null`, the
+   * result must not be bound to a particular requestId.
+   * @throws {InvalidRequestError} - Instead of returning `null` in order to
+   * provide a custom error message
    */
-  addDeviceAccount(
+  getDeviceAccount(
     deviceId: DeviceId,
     sub: Sub,
-    remember: boolean,
-  ): Awaitable<DeviceAccountInfo>
+  ): Awaitable<DeviceAccount | null>
 
   /**
-   * @returns The account info, whether the account, even if remember was false.
+   * Removes *all* the unbound device-accounts associated with the given device
+   * & account.
+   *
+   * @note Noop if the device-account is not found.
    */
-  getDeviceAccount(deviceId: DeviceId, sub: Sub): Awaitable<AccountInfo | null>
   removeDeviceAccount(deviceId: DeviceId, sub: Sub): Awaitable<void>
 
   /**
-   * @note Only the accounts that where logged in with `remember: true` need to
-   * be returned. The others will be ignored.
+   * @returns **all** the device accounts that match the {@link requestId}
+   * criteria and given {@link filter}.
    */
-  listDeviceAccounts(deviceId: DeviceId): Awaitable<AccountInfo[]>
+  listDeviceAccounts(
+    filter: { sub: Sub } | { deviceId: DeviceId },
+  ): Awaitable<DeviceAccount[]>
 
   resetPasswordRequest(data: ResetPasswordRequestData): Awaitable<void>
   resetPasswordConfirm(data: ResetPasswordConfirmData): Awaitable<void>
@@ -179,8 +182,9 @@ export interface AccountStore {
 export const isAccountStore = buildInterfaceChecker<AccountStore>([
   'createAccount',
   'authenticateAccount',
-  'addAuthorizedClient',
-  'addDeviceAccount',
+  'setAuthorizedClient',
+  'getAccount',
+  'upsertDeviceAccount',
   'getDeviceAccount',
   'removeDeviceAccount',
   'listDeviceAccounts',

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

@@ -1,15 +1,15 @@
 import { z } from 'zod'
-import { authenticateAccountDataSchema } from './account-store.js'
+import { localeSchema } from '../lib/util/locale.js'
+import { emailOtpSchema } from '../types/email-otp.js'
+import { newPasswordSchema, oldPasswordSchema } from '../types/password.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),
+export const signInDataSchema = z
+  .object({
+    locale: localeSchema,
+    username: z.string(),
+    password: z.union([oldPasswordSchema, newPasswordSchema]),
+    emailOtp: emailOtpSchema.optional(),
   })
   .strict()
 
-export type SignInData = z.TypeOf<typeof signInDataSchema>
+export type SignInData = z.output<typeof signInDataSchema>

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

@@ -1,11 +1,20 @@
 import { z } from 'zod'
 import { hcaptchaTokenSchema } from '../lib/hcaptcha.js'
-import { createAccountDataSchema } from './account-store.js'
+import { localeSchema } from '../lib/util/locale.js'
+import { emailSchema } from '../types/email.js'
+import { handleSchema } from '../types/handle.js'
+import { inviteCodeSchema } from '../types/invite-code.js'
+import { newPasswordSchema } from '../types/password.js'
 
-export const signUpInputSchema = createAccountDataSchema
-  .extend({
+export const signUpInputSchema = z
+  .object({
+    locale: localeSchema,
+    handle: handleSchema,
+    email: emailSchema,
+    password: newPasswordSchema,
+    inviteCode: inviteCodeSchema.optional(),
     hcaptchaToken: hcaptchaTokenSchema.optional(),
   })
   .strict()
 
-export type SignUpInput = z.TypeOf<typeof signUpInputSchema>
+export type SignUpInput = z.output<typeof signUpInputSchema>

package/src/client/client-manager.ts

@@ -93,7 +93,7 @@ export class ClientManager {
    *
    * @see {@link https://openid.net/specs/openid-connect-registration-1_0.html#rfc.section.2 OIDC Client Registration}
    */
-  public async getClient(clientId: string) {
+  public async getClient(clientId: ClientId) {
     const metadata = await this.getClientMetadata(clientId).catch((err) => {
       throw InvalidClientMetadataError.from(
         err,
@@ -126,6 +126,38 @@ export class ClientManager {
     return new Client(clientId, metadata, jwks, { isFirstParty, isTrusted })
   }
 
+  public async loadClients(
+    clientIds: Iterable<ClientId>,
+    {
+      onError = (err) => {
+        throw err
+      },
+    }: {
+      onError?: (
+        err: unknown,
+        clientId: ClientId,
+      ) => Awaitable<Client | null | undefined>
+    } = {},
+  ): Promise<Map<ClientId, Client>> {
+    // Make sure we don't load the same client multiple times
+    const uniqueClientIds =
+      clientIds instanceof Set ? clientIds : new Set(clientIds)
+
+    // Load all (unique) clients in parallel
+    const clients = await Promise.all(
+      Array.from(uniqueClientIds, async (clientId) =>
+        this.getClient(clientId).catch((err) => onError(err, clientId)),
+      ),
+    )
+
+    // Return a map for easy lookups
+    return new Map(
+      clients
+        .filter((c) => c != null && c instanceof Client)
+        .map((c) => [c.id, c]),
+    )
+  }
+
   protected async getClientMetadata(
     clientId: ClientId,
   ): Promise<OAuthClientMetadata> {
@@ -257,7 +289,7 @@ export class ClientManager {
             `Grant type "${grantType}" is not allowed`,
           )
 
-        // @TODO: Add support (e.g. for first party client)
+        // @TODO Add support (e.g. for first party client)
         // case 'client_credentials':
         // case 'password':
         case 'authorization_code':

package/src/client/client-store.ts

@@ -5,7 +5,7 @@ import { ClientId } from './client-id.js'
 // Export all types needed to implement the ClientStore interface
 export * from './client-data.js'
 export * from './client-id.js'
-export type { Awaitable }
+export type { Awaitable, OAuthClientMetadata }
 
 export interface ClientStore {
   findClient(clientId: ClientId): Awaitable<OAuthClientMetadata>

package/src/constants.ts

@@ -29,6 +29,9 @@ const MONTH = YEAR / 12
 /** 7 days */
 export const AUTHENTICATION_MAX_AGE = 7 * DAY
 
+/** 15 minutes */
+export const EPHEMERAL_SESSION_MAX_AGE = 15 * MINUTE
+
 /** 60 minutes */
 export const TOKEN_MAX_AGE = 60 * MINUTE
 
@@ -53,7 +56,9 @@ export const PAR_EXPIRES_IN = 5 * MINUTE
 /**
  * 59 seconds (should be less than a minute)
  *
- * @see {@link https://datatracker.ietf.org/doc/html/rfc9101#section-10.2}
+ * > "A general guidance for the validity time would be less than a minute."
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc9101#section-10.2 | JWT-Secured Authorization Request (JAR) - Section 10.2 (d)}
  */
 export const JAR_MAX_AGE = 59 * SECOND
 

package/src/customization/branding.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod'
+import { colorsSchema } from './colors.js'
+import { linksSchema } from './links.js'
+
+export const brandingSchema = z.object({
+  name: z.string().optional(),
+  logo: z.string().url().optional(),
+  colors: colorsSchema.optional(),
+  links: z.array(linksSchema).optional(),
+})
+export type BrandingInput = z.input<typeof brandingSchema>
+export type Branding = z.infer<typeof brandingSchema>

package/src/customization/build-customization-css.ts

@@ -0,0 +1,30 @@
+import { extractHue, pickContrastColor } from '../lib/util/color.js'
+import { Branding } from './branding.js'
+import { COLOR_NAMES } from './colors.js'
+import { Customization } from './customization.js'
+
+export function buildCustomizationCss({
+  branding,
+}: Customization): undefined | string {
+  const vars = Array.from(buildCustomizationVars(branding))
+  if (vars.length) return `:root { ${vars.join(' ')} }`
+}
+
+function* buildCustomizationVars(branding?: Branding): Generator<string> {
+  if (branding?.colors) {
+    // @NOTE these could come from branding (in the future)
+    const contrastLight = { r: 255, g: 255, b: 255 }
+    const contrastDark = { r: 0, g: 0, b: 0 }
+
+    for (const name of COLOR_NAMES) {
+      const value = branding.colors[name]
+      if (!value) continue // Skip missing colors
+
+      const contrast = pickContrastColor(value, contrastLight, contrastDark)
+
+      yield `--branding-color-${name}: ${value.r} ${value.g} ${value.b};`
+      yield `--branding-color-${name}-contrast: ${contrast.r} ${contrast.g} ${contrast.b};`
+      yield `--branding-color-${name}-hue: ${extractHue(value)};`
+    }
+  }
+}

package/src/customization/build-customization-data.ts

@@ -0,0 +1,22 @@
+import { CustomizationData } from '@atproto/oauth-provider-api'
+import { Customization } from './customization.js'
+
+export function buildCustomizationData({
+  branding,
+  availableUserDomains,
+  inviteCodeRequired,
+  hcaptcha,
+}: Customization): CustomizationData {
+  // @NOTE the front end does not need colors here as they will be injected as
+  // CSS variables.
+  // @NOTE We only copy the values explicitly needed to avoid leaking sensitive
+  // data (in case the caller passed more than what we expect).
+  return {
+    availableUserDomains,
+    inviteCodeRequired,
+    hcaptchaSiteKey: hcaptcha?.siteKey,
+    name: branding?.name,
+    logo: branding?.logo,
+    links: branding?.links,
+  }
+}

package/src/customization/colors.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+import { RgbColor, parseColor } from '../lib/util/color.js'
+
+export const COLOR_NAMES = ['primary', 'error', 'warning', 'success'] as const
+
+export const rgbColorSchema = z.string().transform((value, ctx): RgbColor => {
+  try {
+    const parsed = parseColor(value)
+    if ('a' in parsed && parsed.a !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Alpha values are not supported',
+      })
+    }
+    return parsed
+  } catch (e) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: e instanceof Error ? e.message : 'Invalid color value',
+    })
+    return z.NEVER
+  }
+})
+
+export const colorsSchema = z.record(
+  z.enum(COLOR_NAMES),
+  rgbColorSchema.optional(),
+)
+
+export type Colors = z.infer<typeof colorsSchema>

package/src/customization/customization.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+import { hcaptchaConfigSchema } from '../lib/hcaptcha.js'
+import { brandingSchema } from './branding.js'
+
+export const customizationSchema = z.object({
+  /**
+   * Available user domains that can be used to sign up. A non-empty array
+   * is required to enable the sign-up feature.
+   */
+  availableUserDomains: z.array(z.string()).optional(),
+  /**
+   * UI customizations
+   */
+  branding: brandingSchema.optional(),
+  /**
+   * Is an invite code required to sign up?
+   */
+  inviteCodeRequired: z.boolean().optional(),
+  /**
+   * Enables hCaptcha during sign-up.
+   */
+  hcaptcha: hcaptchaConfigSchema.optional(),
+})
+export type CustomizationInput = z.input<typeof customizationSchema>
+export type Customization = z.infer<typeof customizationSchema>

package/src/customization/links.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod'
+import { isLinkRel } from '../lib/html/build-document.js'
+import { localizedStringSchema } from '../lib/util/locale.js'
+
+export const linksSchema = z.object({
+  title: localizedStringSchema,
+  href: z.string().url(),
+  rel: z.string().refine(isLinkRel, 'Invalid link rel').optional(),
+})
+export type Links = z.infer<typeof linksSchema>

package/src/device/device-id.ts

@@ -17,6 +17,11 @@ export const deviceIdSchema = z
   )
 
 export type DeviceId = z.infer<typeof deviceIdSchema>
+
+export function isDeviceId(value: unknown): value is DeviceId {
+  return deviceIdSchema.safeParse(value).success
+}
+
 export const generateDeviceId = async (): Promise<DeviceId> => {
   return `${DEVICE_ID_PREFIX}${await randomHexId(DEVICE_ID_BYTES_LENGTH)}`
 }