@atproto/oauth-provider 0.1.0

package/src/device/device-manager.ts

@@ -0,0 +1,287 @@
+import { IncomingMessage, ServerResponse } from 'node:http'
+
+import { serialize as serializeCookie } from 'cookie'
+import type Keygrip from 'keygrip'
+import { z } from 'zod'
+
+import { appendHeader, parseHttpCookies } from '../lib/http/index.js'
+
+import { SESSION_FIXATION_MAX_AGE } from '../constants.js'
+import { DeviceData } from './device-data.js'
+import { extractDeviceDetails } from './device-details.js'
+import { DeviceId, deviceIdSchema, generateDeviceId } from './device-id.js'
+import { DeviceStore } from './device-store.js'
+import { generateSessionId, sessionIdSchema } from './session-id.js'
+
+export const DEFAULT_OPTIONS = {
+  /**
+   * Controls whether the IP address is read from the `X-Forwarded-For` header
+   * (if `true`), or from the `req.socket.remoteAddress` property (if `false`).
+   *
+   * @default true // (nowadays, most requests are proxied)
+   */
+  trustProxy: true,
+
+  /**
+   * Amount of time (in ms) after which session IDs will be rotated
+   *
+   * @default 300e3 // (5 minutes)
+   */
+  rotationRate: 5 * 60e3,
+
+  /**
+   * Cookie options
+   */
+  cookie: {
+    keys: undefined as undefined | Keygrip,
+
+    /**
+     * Name of the cookie used to identify the device
+     *
+     * @default 'session-id'
+     */
+    device: 'device-id',
+
+    /**
+     * Name of the cookie used to identify the session
+     *
+     * @default 'session-id'
+     */
+    session: 'session-id',
+
+    /**
+     * Url path for the cookie
+     *
+     * @default '/oauth/authorize'
+     */
+    path: '/oauth/authorize',
+
+    /**
+     * Amount of time (in ms) after which the session cookie will expire.
+     * If set to `null`, the cookie will be a session cookie (deleted when the
+     * browser is closed).
+     *
+     * @default 10 * 365.2 * 24 * 60 * 60e3 // 10 years (in ms)
+     */
+    age: <number | null>(10 * 365.2 * 24 * 60 * 60e3),
+
+    /**
+     * Controls whether the cookie is only sent over HTTPS (if `true`), or also
+     * over HTTP (if `false`). This should **NOT** be set to `false` in
+     * production.
+     */
+    secure: true,
+
+    /**
+     * Controls whether the cookie is sent along with cross-site requests.
+     *
+     * @default 'lax'
+     */
+    sameSite: 'lax' as 'lax' | 'strict',
+  },
+}
+
+export type DeviceDeviceManagerOptions = typeof DEFAULT_OPTIONS
+
+const cookieValueSchema = z.tuple([deviceIdSchema, sessionIdSchema])
+type CookieValue = z.infer<typeof cookieValueSchema>
+
+/**
+ * This class provides an abstraction for keeping track of DEVICE sessions. It
+ * relies on a {@link DeviceStore} to persist session data and a cookie to
+ * identify the session.
+ */
+export class DeviceManager {
+  constructor(
+    private readonly store: DeviceStore,
+    private readonly options: DeviceDeviceManagerOptions = DEFAULT_OPTIONS,
+  ) {}
+
+  public async load(
+    req: IncomingMessage,
+    res: ServerResponse,
+  ): Promise<{ deviceId: DeviceId }> {
+    const cookie = await this.getCookie(req)
+    if (cookie) {
+      return this.refresh(req, res, cookie.value, cookie.mustRotate)
+    } else {
+      return this.create(req, res)
+    }
+  }
+
+  private async create(
+    req: IncomingMessage,
+    res: ServerResponse,
+  ): Promise<{ deviceId: DeviceId }> {
+    const { userAgent, ipAddress } = this.getDeviceDetails(req)
+
+    const [deviceId, sessionId] = await Promise.all([
+      generateDeviceId(),
+      generateSessionId(),
+    ] as const)
+
+    await this.store.createDevice(deviceId, {
+      sessionId,
+      lastSeenAt: new Date(),
+      userAgent,
+      ipAddress,
+    })
+
+    this.setCookie(res, [deviceId, sessionId])
+
+    return { deviceId }
+  }
+
+  private async refresh(
+    req: IncomingMessage,
+    res: ServerResponse,
+    [deviceId, sessionId]: CookieValue,
+    forceRotate = false,
+  ): Promise<{ deviceId: DeviceId }> {
+    const data = await this.store.readDevice(deviceId)
+    if (!data) return this.create(req, res)
+
+    const lastSeenAt = new Date(data.lastSeenAt)
+    const age = Date.now() - lastSeenAt.getTime()
+
+    if (sessionId !== data.sessionId) {
+      if (age <= SESSION_FIXATION_MAX_AGE) {
+        // The cookie was probably rotated by a concurrent request. Let's
+        // update the cookie with the new sessionId.
+        forceRotate = true
+      } else {
+        // Something's wrong. Let's create a new session.
+        await this.store.deleteDevice(deviceId)
+        return this.create(req, res)
+      }
+    }
+
+    const details = this.getDeviceDetails(req)
+
+    if (
+      forceRotate ||
+      details.ipAddress !== data.ipAddress ||
+      details.userAgent !== data.userAgent ||
+      age > this.options.rotationRate
+    ) {
+      await this.rotate(req, res, deviceId, {
+        ipAddress: details.ipAddress,
+        userAgent: details.userAgent || data.userAgent,
+      })
+    }
+
+    return { deviceId }
+  }
+
+  public async rotate(
+    req: IncomingMessage,
+    res: ServerResponse,
+    deviceId: DeviceId,
+    data?: Partial<Omit<DeviceData, 'sessionId' | 'lastSeenAt'>>,
+  ): Promise<void> {
+    const sessionId = await generateSessionId()
+
+    await this.store.updateDevice(deviceId, {
+      ...data,
+      sessionId,
+      lastSeenAt: new Date(),
+    })
+
+    this.setCookie(res, [deviceId, sessionId])
+  }
+
+  private async getCookie(
+    req: IncomingMessage,
+  ): Promise<{ value: CookieValue; mustRotate: boolean } | null> {
+    const cookies = parseHttpCookies(req)
+    if (!cookies) return null
+
+    const device = this.parseCookie(
+      cookies,
+      this.options.cookie.device,
+      deviceIdSchema,
+    )
+    const session = this.parseCookie(
+      cookies,
+      this.options.cookie.session,
+      sessionIdSchema,
+    )
+
+    // Silently ignore invalid cookies
+    if (!device || !session) {
+      // If the device cookie is valid, let's cleanup the DB
+      if (device) await this.store.deleteDevice(device.value)
+
+      return null
+    }
+
+    return {
+      value: [device.value, session.value],
+      mustRotate: device.mustRotate || session.mustRotate,
+    }
+  }
+
+  private parseCookie<T>(
+    cookies: Record<string, string | undefined>,
+    name: string,
+    schema: z.ZodType<T> | z.ZodEffects<z.ZodTypeAny, T, string>,
+  ): null | { value: T; mustRotate: boolean } {
+    const result = schema.safeParse(cookies[name], { path: ['cookie', name] })
+    if (!result.success) return null
+
+    const value = result.data
+
+    if (this.options.cookie.keys) {
+      const hash = cookies[`${name}:hash`]
+      if (!hash) return null
+
+      const idx = this.options.cookie.keys.index(value, hash)
+      if (idx < 0) return null
+
+      return { value, mustRotate: idx !== 0 }
+    }
+
+    return { value, mustRotate: false }
+  }
+
+  private setCookie(res: ServerResponse, cookieValue: null | CookieValue) {
+    this.writeCookie(res, this.options.cookie.device, cookieValue?.[0])
+    this.writeCookie(res, this.options.cookie.session, cookieValue?.[1])
+  }
+
+  private writeCookie(res: ServerResponse, name: string, value?: string) {
+    const cookieOptions = {
+      maxAge: value
+        ? this.options.cookie.age == null
+          ? undefined
+          : this.options.cookie.age / 1000
+        : 0,
+      httpOnly: true,
+      path: this.options.cookie.path,
+      secure: this.options.cookie.secure !== false,
+      sameSite: this.options.cookie.sameSite === 'lax' ? 'lax' : 'strict',
+    } as const
+
+    appendHeader(
+      res,
+      'Set-Cookie',
+      serializeCookie(name, value || '', cookieOptions),
+    )
+
+    if (this.options.cookie.keys) {
+      appendHeader(
+        res,
+        'Set-Cookie',
+        serializeCookie(
+          `${name}:hash`,
+          value ? this.options.cookie.keys.sign(value) : '',
+          cookieOptions,
+        ),
+      )
+    }
+  }
+
+  private getDeviceDetails(req: IncomingMessage) {
+    return extractDeviceDetails(req, this.options.trustProxy)
+  }
+}

package/src/device/device-store.ts

@@ -0,0 +1,35 @@
+import { Awaitable } from '../lib/util/type.js'
+import { DeviceData } from './device-data.js'
+import { DeviceId } from './device-id.js'
+
+// Export all types needed to implement the DeviceStore interface
+export * from './device-id.js'
+export * from './device-data.js'
+export * from './session-id.js'
+
+export interface DeviceStore {
+  createDevice(deviceId: DeviceId, data: DeviceData): Awaitable<void>
+  readDevice(deviceId: DeviceId): Awaitable<DeviceData | null>
+  updateDevice(deviceId: DeviceId, data: Partial<DeviceData>): Awaitable<void>
+  deleteDevice(deviceId: DeviceId): Awaitable<void>
+}
+
+export function isDeviceStore(
+  implementation: Record<string, unknown> & Partial<DeviceStore>,
+): implementation is Record<string, unknown> & DeviceStore {
+  return (
+    typeof implementation.createDevice === 'function' &&
+    typeof implementation.readDevice === 'function' &&
+    typeof implementation.updateDevice === 'function' &&
+    typeof implementation.deleteDevice === 'function'
+  )
+}
+
+export function asDeviceStore(
+  implementation?: Record<string, unknown> & Partial<DeviceStore>,
+): DeviceStore {
+  if (!implementation || !isDeviceStore(implementation)) {
+    throw new Error('Invalid DeviceStore implementation')
+  }
+  return implementation
+}

package/src/device/session-id.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod'
+
+import { SESSION_ID_BYTES_LENGTH, SESSION_ID_PREFIX } from '../constants.js'
+import { randomHexId } from '../lib/util/crypto.js'
+
+export const SESSION_ID_LENGTH =
+  SESSION_ID_PREFIX.length + SESSION_ID_BYTES_LENGTH * 2 // hex encoding
+
+export const sessionIdSchema = z
+  .string()
+  .length(SESSION_ID_LENGTH)
+  .refine(
+    (v): v is `${typeof SESSION_ID_PREFIX}${string}` =>
+      v.startsWith(SESSION_ID_PREFIX),
+    {
+      message: `Invalid session ID format`,
+    },
+  )
+export type SessionId = z.infer<typeof sessionIdSchema>
+export const generateSessionId = async (): Promise<SessionId> => {
+  return `${SESSION_ID_PREFIX}${await randomHexId(SESSION_ID_BYTES_LENGTH)}`
+}

package/src/dpop/dpop-manager.ts

@@ -0,0 +1,147 @@
+import { createHash } from 'node:crypto'
+
+import { EmbeddedJWK, calculateJwkThumbprint, jwtVerify } from 'jose'
+import { JOSEError } from 'jose/errors'
+
+import { DPOP_NONCE_MAX_AGE } from '../constants.js'
+import { InvalidDpopProofError } from '../errors/invalid-dpop-proof-error.js'
+import { UseDpopNonceError } from '../errors/use-dpop-nonce-error.js'
+import { DpopNonce, DpopNonceInput } from './dpop-nonce.js'
+
+export { DpopNonce, type DpopNonceInput }
+export type DpopManagerOptions = {
+  /**
+   * Set this to `false` to disable the use of nonces in DPoP proofs. Set this
+   * to a secret Uint8Array or hex encoded string to use a predictable seed for
+   * all nonces (typically useful when multiple instances are running). Leave
+   * undefined to generate a random seed at startup.
+   */
+  dpopSecret?: false | DpopNonceInput
+  dpopStep?: number
+}
+
+export class DpopManager {
+  protected readonly dpopNonce?: DpopNonce
+
+  constructor({ dpopSecret, dpopStep }: DpopManagerOptions = {}) {
+    this.dpopNonce =
+      dpopSecret === false ? undefined : DpopNonce.from(dpopSecret, dpopStep)
+  }
+
+  nextNonce(): string | undefined {
+    return this.dpopNonce?.next()
+  }
+
+  /**
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc9449#section-4.3}
+   */
+  async checkProof(
+    proof: unknown,
+    htm: string, // HTTP Method
+    htu: string | URL, // HTTP URL
+    accessToken?: string, // Access Token
+  ) {
+    if (Array.isArray(proof) && proof.length === 1) {
+      proof = proof[0]
+    }
+
+    if (!proof || typeof proof !== 'string') {
+      throw new InvalidDpopProofError('DPoP proof required')
+    }
+
+    const { protectedHeader, payload } = await jwtVerify<{
+      iat: number
+      exp: number
+      jti: string
+    }>(proof, EmbeddedJWK, {
+      typ: 'dpop+jwt',
+      maxTokenAge: 10,
+      clockTolerance: DPOP_NONCE_MAX_AGE / 1e3,
+      requiredClaims: ['iat', 'exp', 'jti'],
+    }).catch((err) => {
+      const message =
+        err instanceof JOSEError
+          ? `Invalid DPoP proof (${err.message})`
+          : 'Invalid DPoP proof'
+      throw new InvalidDpopProofError(message, err)
+    })
+
+    if (!payload.jti || typeof payload.jti !== 'string') {
+      throw new InvalidDpopProofError('Invalid or missing jti property')
+    }
+
+    if (payload.exp - payload.iat > DPOP_NONCE_MAX_AGE / 3 / 1e3) {
+      throw new InvalidDpopProofError('DPoP proof validity too long')
+    }
+
+    // Note rfc9110#section-9.1 states that the method name is case-sensitive
+    if (!htm || htm !== payload['htm']) {
+      throw new InvalidDpopProofError('DPoP htm mismatch')
+    }
+
+    if (
+      payload['nonce'] !== undefined &&
+      typeof payload['nonce'] !== 'string'
+    ) {
+      throw new InvalidDpopProofError('DPoP nonce must be a string')
+    }
+
+    if (!payload['nonce'] && this.dpopNonce) {
+      throw new UseDpopNonceError()
+    }
+
+    if (payload['nonce'] && !this.dpopNonce?.check(payload['nonce'])) {
+      throw new UseDpopNonceError()
+    }
+
+    const htuNorm = normalizeHtu(htu)
+    if (!htuNorm || htuNorm !== normalizeHtu(payload['htu'])) {
+      throw new InvalidDpopProofError('DPoP htu mismatch')
+    }
+
+    if (accessToken) {
+      const athBuffer = createHash('sha256').update(accessToken).digest()
+      if (payload['ath'] !== athBuffer.toString('base64url')) {
+        throw new InvalidDpopProofError('DPoP ath mismatch')
+      }
+    } else if (payload['ath']) {
+      throw new InvalidDpopProofError('DPoP ath not allowed')
+    }
+
+    try {
+      return {
+        protectedHeader,
+        payload,
+        jkt: await calculateJwkThumbprint(protectedHeader['jwk']!, 'sha256'), // EmbeddedJWK
+      }
+    } catch (err) {
+      const message =
+        err instanceof JOSEError ? err.message : 'Failed to calculate jkt'
+      throw new InvalidDpopProofError(message, err)
+    }
+  }
+}
+
+/**
+ * @note
+ * > The htu claim matches the HTTP URI value for the HTTP request in which the
+ * > JWT was received, ignoring any query and fragment parts.
+ *
+ * > To reduce the likelihood of false negatives, servers SHOULD employ
+ * > syntax-based normalization (Section 6.2.2 of [RFC3986]) and scheme-based
+ * > normalization (Section 6.2.3 of [RFC3986]) before comparing the htu claim.
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc9449#section-4.3 | RFC9449 section 4.3. Checking DPoP Proofs}
+ */
+function normalizeHtu(htu: unknown): string | null {
+  // Optimization
+  if (!htu) return null
+
+  try {
+    const url = new URL(String(htu))
+    url.hash = ''
+    url.search = ''
+    return url.href
+  } catch {
+    return null
+  }
+}

package/src/dpop/dpop-nonce.ts

@@ -0,0 +1,104 @@
+import { createHmac, randomBytes } from 'node:crypto'
+
+import { DPOP_NONCE_MAX_AGE } from '../constants.js'
+
+function numTo64bits(num: number) {
+  const arr = new Uint8Array(8)
+  arr[7] = (num = num | 0) & 0xff
+  arr[6] = (num >>= 8) & 0xff
+  arr[5] = (num >>= 8) & 0xff
+  arr[4] = (num >>= 8) & 0xff
+  arr[3] = (num >>= 8) & 0xff
+  arr[2] = (num >>= 8) & 0xff
+  arr[1] = (num >>= 8) & 0xff
+  arr[0] = (num >>= 8) & 0xff
+  return arr
+}
+
+export type DpopNonceInput = string | Uint8Array | DpopNonce
+
+export class DpopNonce {
+  #secret: Uint8Array
+  #counter: number
+
+  #prev: string
+  #now: string
+  #next: string
+
+  constructor(
+    protected readonly secret: Uint8Array,
+    protected readonly step: number,
+  ) {
+    if (secret.length !== 32) throw new TypeError('Expected 32 bytes')
+    if (this.step < 0 || this.step > DPOP_NONCE_MAX_AGE / 3) {
+      throw new TypeError('Invalid step')
+    }
+
+    this.#secret = Uint8Array.from(secret)
+    this.#counter = (Date.now() / step) | 0
+
+    this.#prev = this.compute(this.#counter - 1)
+    this.#now = this.compute(this.#counter)
+    this.#next = this.compute(this.#counter + 1)
+  }
+
+  protected rotate() {
+    const counter = (Date.now() / this.step) | 0
+    switch (counter - this.#counter) {
+      case 0:
+        // counter === this.#counter => nothing to do
+        return
+      case 1:
+        // Optimization: avoid recomputing #prev & #now
+        this.#prev = this.#now
+        this.#now = this.#next
+        this.#next = this.compute(counter + 1)
+        break
+      case 2:
+        // Optimization: avoid recomputing #prev
+        this.#prev = this.#next
+        this.#now = this.compute(counter)
+        this.#next = this.compute(counter + 1)
+        break
+      default:
+        // All nonces are outdated, so we recompute all of them
+        this.#prev = this.compute(counter - 1)
+        this.#now = this.compute(counter)
+        this.#next = this.compute(counter + 1)
+        break
+    }
+    this.#counter = counter
+  }
+
+  protected compute(counter: number) {
+    return createHmac('sha256', this.#secret)
+      .update(numTo64bits(counter))
+      .digest()
+      .toString('base64url')
+  }
+
+  public next() {
+    this.rotate()
+    return this.#next
+  }
+
+  public check(nonce: string) {
+    return this.#next === nonce || this.#now === nonce || this.#prev === nonce
+  }
+
+  static from(
+    input: DpopNonceInput = randomBytes(32),
+    step = DPOP_NONCE_MAX_AGE / 3,
+  ): DpopNonce {
+    if (input instanceof DpopNonce) {
+      return input
+    }
+    if (input instanceof Uint8Array) {
+      return new DpopNonce(input, step)
+    }
+    if (typeof input === 'string') {
+      return new DpopNonce(Buffer.from(input, 'hex'), step)
+    }
+    return new DpopNonce(input, step)
+  }
+}

package/src/errors/access-denied-error.ts

@@ -0,0 +1,26 @@
+import { OAuthAuthenticationRequestParameters } from '@atproto/oauth-types'
+import { buildErrorPayload } from '../output/build-error-payload.js'
+import { OAuthError } from './oauth-error.js'
+
+export class AccessDeniedError extends OAuthError {
+  constructor(
+    public readonly parameters: OAuthAuthenticationRequestParameters,
+    error_description: string,
+    error = 'access_denied',
+    cause?: unknown,
+  ) {
+    super(error, error_description, 400, cause)
+  }
+
+  static from(
+    parameters: OAuthAuthenticationRequestParameters,
+    cause?: unknown,
+  ) {
+    if (cause && cause instanceof AccessDeniedError) {
+      return cause
+    }
+
+    const { error, error_description } = buildErrorPayload(cause)
+    return new AccessDeniedError(parameters, error_description, error, cause)
+  }
+}

package/src/errors/account-selection-required-error.ts

@@ -0,0 +1,12 @@
+import { OAuthAuthenticationRequestParameters } from '@atproto/oauth-types'
+import { AccessDeniedError } from './access-denied-error.js'
+
+export class AccountSelectionRequiredError extends AccessDeniedError {
+  constructor(
+    parameters: OAuthAuthenticationRequestParameters,
+    error_description = 'Account selection required',
+    cause?: unknown,
+  ) {
+    super(parameters, error_description, 'account_selection_required', cause)
+  }
+}

package/src/errors/consent-required-error.ts

@@ -0,0 +1,12 @@
+import { OAuthAuthenticationRequestParameters } from '@atproto/oauth-types'
+import { AccessDeniedError } from './access-denied-error.js'
+
+export class ConsentRequiredError extends AccessDeniedError {
+  constructor(
+    parameters: OAuthAuthenticationRequestParameters,
+    error_description = 'User consent required',
+    cause?: unknown,
+  ) {
+    super(parameters, error_description, 'consent_required', cause)
+  }
+}

package/src/errors/invalid-authorization-details-error.ts

@@ -0,0 +1,22 @@
+import { OAuthError } from './oauth-error.js'
+
+/**
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc9396#section-14.6 | RFC 9396 - OAuth Dynamic Client Registration Metadata Registration Error}
+ *
+ * The AS MUST refuse to process any unknown authorization details type or
+ * authorization details not conforming to the respective type definition. The
+ * AS MUST abort processing and respond with an error
+ * invalid_authorization_details to the client if any of the following are true
+ * of the objects in the authorization_details structure:
+ *  - contains an unknown authorization details type value,
+ *  - is an object of known type but containing unknown fields,
+ *  - contains fields of the wrong type for the authorization details type,
+ *  - contains fields with invalid values for the authorization details type, or
+ *  - is missing required fields for the authorization details type.
+ */
+export class InvalidAuthorizationDetailsError extends OAuthError {
+  constructor(error_description: string, cause?: unknown) {
+    super('invalid_authorization_details', error_description, 400, cause)
+  }
+}

package/src/errors/invalid-client-error.ts

@@ -0,0 +1,20 @@
+import { OAuthError } from './oauth-error.js'
+
+/**
+ * @see
+ * {@link https://datatracker.ietf.org/doc/html/rfc6749#section-5.2 | RFC6749 - Issuing an Access Token }
+ *
+ * Client authentication failed (e.g., unknown client, no client authentication
+ * included, or unsupported authentication method). The authorization server MAY
+ * return an HTTP 401 (Unauthorized) status code to indicate which HTTP
+ * authentication schemes are supported.  If the client attempted to
+ * authenticate via the "Authorization" request header field, the authorization
+ * server MUST respond with an HTTP 401 (Unauthorized) status code and include
+ * the "WWW-Authenticate" response header field matching the authentication
+ * scheme used by the client.
+ */
+export class InvalidClientError extends OAuthError {
+  constructor(error_description: string, cause?: unknown) {
+    super('invalid_client', error_description, 400, cause)
+  }
+}