@atproto/oauth-provider 0.1.0

package/src/client/client-store.ts

@@ -0,0 +1,38 @@
+import { OAuthClientMetadata } from '@atproto/oauth-types'
+
+import { Awaitable } from '../lib/util/type.js'
+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 interface ClientStore {
+  findClient(clientId: ClientId): Awaitable<OAuthClientMetadata>
+}
+
+export function isClientStore(
+  implementation: Record<string, unknown> & Partial<ClientStore>,
+): implementation is Record<string, unknown> & ClientStore {
+  return typeof implementation.findClient === 'function'
+}
+
+export function ifClientStore(
+  implementation?: Record<string, unknown> & Partial<ClientStore>,
+): ClientStore | undefined {
+  if (implementation && isClientStore(implementation)) {
+    return implementation
+  }
+
+  return undefined
+}
+
+export function asClientStore(
+  implementation?: Record<string, unknown> & Partial<ClientStore>,
+): ClientStore {
+  const store = ifClientStore(implementation)
+  if (store) return store
+
+  throw new Error('Invalid ClientStore implementation')
+}

package/src/client/client-utils.ts

@@ -0,0 +1,43 @@
+import {
+  OAuthClientIdDiscoverable,
+  OAuthClientIdLoopback,
+  parseOAuthLoopbackClientId,
+  parseOAuthDiscoverableClientId,
+} from '@atproto/oauth-types'
+
+import { InvalidClientIdError } from '../errors/invalid-client-id-error.js'
+import { InvalidRedirectUriError } from '../errors/invalid-redirect-uri-error.js'
+import { isInternetHost } from '../lib/util/hostname.js'
+
+export function parseRedirectUri(redirectUri: string): URL {
+  try {
+    return new URL(redirectUri)
+  } catch (err) {
+    throw InvalidRedirectUriError.from(err)
+  }
+}
+
+export function parseDiscoverableClientId(
+  clientId: OAuthClientIdDiscoverable,
+): URL {
+  try {
+    const url = parseOAuthDiscoverableClientId(clientId)
+
+    // Extra validation, prevent usage of invalid internet domain names.
+    if (!isInternetHost(url.hostname)) {
+      throw new InvalidClientIdError('ClientID is not a valid internet address')
+    }
+
+    return url
+  } catch (err) {
+    throw InvalidClientIdError.from(err)
+  }
+}
+
+export function parseLoopbackClientId(clientId: OAuthClientIdLoopback): URL {
+  try {
+    return parseOAuthLoopbackClientId(clientId)
+  } catch (err) {
+    throw InvalidClientIdError.from(err)
+  }
+}

package/src/client/client.ts

@@ -0,0 +1,231 @@
+import { Jwks } from '@atproto/jwk'
+import {
+  CLIENT_ASSERTION_TYPE_JWT_BEARER,
+  OAuthClientIdentification,
+  OAuthClientMetadata,
+  OAuthEndpointName,
+} from '@atproto/oauth-types'
+import {
+  UnsecuredJWT,
+  createLocalJWKSet,
+  createRemoteJWKSet,
+  jwtVerify,
+  type JWTPayload,
+  type JWTVerifyGetKey,
+  type JWTVerifyOptions,
+  type JWTVerifyResult,
+  type KeyLike,
+  type ResolvedKey,
+  type UnsecuredResult,
+} from 'jose'
+import { JOSEError } from 'jose/errors'
+
+import { CLIENT_ASSERTION_MAX_AGE, JAR_MAX_AGE } from '../constants.js'
+import { InvalidClientError } from '../errors/invalid-client-error.js'
+import { InvalidClientMetadataError } from '../errors/invalid-client-metadata-error.js'
+import { InvalidRequestError } from '../errors/invalid-request-error.js'
+import { ClientAuth, authJwkThumbprint } from './client-auth.js'
+import { ClientId } from './client-id.js'
+import { ClientInfo } from './client-info.js'
+
+export class Client {
+  /**
+   * @see {@link https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-endpoint-auth-method}
+   */
+  static readonly AUTH_METHODS_SUPPORTED = ['none', 'private_key_jwt'] as const
+
+  private readonly keyGetter: JWTVerifyGetKey
+
+  constructor(
+    public readonly id: ClientId,
+    public readonly metadata: OAuthClientMetadata,
+    public readonly jwks: undefined | Jwks = metadata.jwks,
+    public readonly info: ClientInfo,
+  ) {
+    // If the remote JWKS content is provided, we don't need to fetch it again.
+    this.keyGetter =
+      jwks || !metadata.jwks_uri
+        ? createLocalJWKSet(jwks || { keys: [] })
+        : createRemoteJWKSet(new URL(metadata.jwks_uri), {})
+  }
+
+  public async decodeRequestObject(jar: string) {
+    try {
+      switch (this.metadata.request_object_signing_alg) {
+        case 'none':
+          return await this.jwtVerifyUnsecured(jar, {
+            maxTokenAge: JAR_MAX_AGE / 1000,
+          })
+        case undefined:
+          // https://openid.net/specs/openid-connect-registration-1_0.html#rfc.section.2
+          // > The default, if omitted, is that any algorithm supported by the OP
+          // > and the RP MAY be used.
+          return await this.jwtVerify(jar, {
+            maxTokenAge: JAR_MAX_AGE / 1000,
+          })
+        default:
+          return await this.jwtVerify(jar, {
+            maxTokenAge: JAR_MAX_AGE / 1000,
+            algorithms: [this.metadata.request_object_signing_alg],
+          })
+      }
+    } catch (err) {
+      const message =
+        err instanceof JOSEError
+          ? `Invalid "request" object: ${err.message}`
+          : `Invalid "request" object`
+
+      throw new InvalidRequestError(message, err)
+    }
+  }
+
+  protected async jwtVerifyUnsecured<PayloadType = JWTPayload>(
+    token: string,
+    options?: Omit<JWTVerifyOptions, 'issuer'>,
+  ): Promise<UnsecuredResult<PayloadType>> {
+    return UnsecuredJWT.decode(token, {
+      ...options,
+      issuer: this.id,
+    })
+  }
+
+  protected async jwtVerify<PayloadType = JWTPayload>(
+    token: string,
+    options?: Omit<JWTVerifyOptions, 'issuer'>,
+  ): Promise<JWTVerifyResult<PayloadType> & ResolvedKey<KeyLike>> {
+    return jwtVerify<PayloadType>(token, this.keyGetter, {
+      ...options,
+      issuer: this.id,
+    })
+  }
+
+  protected getAuthMethod(endpoint: OAuthEndpointName) {
+    return (
+      this.metadata[`${endpoint}_endpoint_auth_method`] ||
+      this.metadata[`token_endpoint_auth_method`]
+    )
+  }
+
+  /**
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1}
+   * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-oauth-jwt-bearer-11#section-3}
+   * @see {@link https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-endpoint-auth-method}
+   */
+  public async verifyCredentials(
+    input: OAuthClientIdentification,
+    endpoint: OAuthEndpointName,
+    checks: {
+      audience: string
+    },
+  ): Promise<{
+    clientAuth: ClientAuth
+    // for replay protection
+    nonce?: string
+  }> {
+    const method = this.getAuthMethod(endpoint)
+
+    if (method === 'none') {
+      const clientAuth: ClientAuth = { method: 'none' }
+      return { clientAuth }
+    }
+
+    if (method === 'private_key_jwt') {
+      if (!('client_assertion_type' in input) || !input.client_assertion_type) {
+        throw new InvalidRequestError(
+          `client_assertion_type required for "${method}"`,
+        )
+      } else if (!input.client_assertion) {
+        throw new InvalidRequestError(
+          `client_assertion required for "${method}"`,
+        )
+      }
+
+      if (input.client_assertion_type === CLIENT_ASSERTION_TYPE_JWT_BEARER) {
+        const result = await this.jwtVerify<{
+          jti: string
+        }>(input.client_assertion, {
+          audience: checks.audience,
+          subject: this.id,
+          maxTokenAge: CLIENT_ASSERTION_MAX_AGE / 1000,
+        }).catch((err) => {
+          if (err instanceof JOSEError) {
+            const msg = `Validation of "client_assertion" failed: ${err.message}`
+            throw new InvalidClientError(msg, err)
+          }
+
+          throw err
+        })
+
+        if (!result.protectedHeader.kid) {
+          throw new InvalidClientError(`"kid" required in client_assertion`)
+        }
+
+        if (!result.payload.jti) {
+          throw new InvalidClientError(`"jti" required in client_assertion`)
+        }
+
+        const clientAuth: ClientAuth = {
+          method: CLIENT_ASSERTION_TYPE_JWT_BEARER,
+          jkt: await authJwkThumbprint(result.key),
+          alg: result.protectedHeader.alg,
+          kid: result.protectedHeader.kid,
+        }
+
+        return { clientAuth, nonce: result.payload.jti }
+      }
+
+      throw new InvalidClientError(
+        `Unsupported client_assertion_type "${input.client_assertion_type}"`,
+      )
+    }
+
+    // @ts-expect-error Ensure to keep Client.AUTH_METHODS_SUPPORTED in sync
+    // with the implementation of this function.
+    if (Client.AUTH_METHODS_SUPPORTED.includes(method)) {
+      throw new Error(
+        `verifyCredentials() should implement all of ${[
+          Client.AUTH_METHODS_SUPPORTED,
+        ]}`,
+      )
+    }
+
+    throw new InvalidClientMetadataError(
+      `Unsupported ${endpoint}_endpoint_auth_method "${method}"`,
+    )
+  }
+
+  /**
+   * Ensures that a {@link ClientAuth} generated in the past is still valid wrt
+   * the current client metadata & jwks. This is used to invalidate tokens when
+   * the client stops advertising the key that it used to authenticate itself
+   * during the initial token request.
+   */
+  public async validateClientAuth(clientAuth: ClientAuth): Promise<boolean> {
+    if (clientAuth.method === 'none') {
+      return this.getAuthMethod('token') === 'none'
+    }
+
+    if (clientAuth.method === CLIENT_ASSERTION_TYPE_JWT_BEARER) {
+      if (this.getAuthMethod('token') !== 'private_key_jwt') {
+        return false
+      }
+      try {
+        const key = await this.keyGetter(
+          {
+            kid: clientAuth.kid,
+            alg: clientAuth.alg,
+          },
+          { payload: '', signature: '' },
+        )
+        const jtk = await authJwkThumbprint(key)
+
+        return jtk === clientAuth.jkt
+      } catch (e) {
+        return false
+      }
+    }
+
+    // @ts-expect-error
+    throw new Error(`Invalid method "${clientAuth.method}"`)
+  }
+}

package/src/constants.ts

@@ -0,0 +1,69 @@
+// The purpose of the prefix is to provide type safety
+
+export const DEVICE_ID_PREFIX = 'dev-'
+export const DEVICE_ID_BYTES_LENGTH = 16 // 128 bits
+
+export const SESSION_ID_PREFIX = 'ses-'
+export const SESSION_ID_BYTES_LENGTH = 16 // 128 bits - only valid if device id is valid
+
+export const REFRESH_TOKEN_PREFIX = 'ref-'
+export const REFRESH_TOKEN_BYTES_LENGTH = 32 // 256 bits
+
+export const TOKEN_ID_PREFIX = 'tok-'
+export const TOKEN_ID_BYTES_LENGTH = 16 // 128 bits - used as `jti` in JWTs (cannot be forged)
+
+export const REQUEST_ID_PREFIX = 'req-'
+export const REQUEST_ID_BYTES_LENGTH = 16 // 128 bits
+
+export const CODE_PREFIX = 'cod-'
+export const CODE_BYTES_LENGTH = 32
+
+export const ALLOW_LOOPBACK_CLIENT_REFRESH_TOKEN = true
+
+const SECOND = 1e3
+const MINUTE = 60 * SECOND
+const HOUR = 60 * MINUTE
+const DAY = 24 * HOUR
+const WEEK = 7 * DAY
+const YEAR = 365.25 * DAY
+const MONTH = YEAR / 12
+
+/** 7 days */
+export const AUTHENTICATION_MAX_AGE = 7 * DAY
+
+/** 60 minutes */
+export const TOKEN_MAX_AGE = 60 * MINUTE
+
+/** 5 minutes */
+export const AUTHORIZATION_INACTIVITY_TIMEOUT = 5 * MINUTE
+
+/** 1 months */
+export const AUTHENTICATED_REFRESH_INACTIVITY_TIMEOUT = 1 * MONTH
+
+/** 2 days */
+export const UNAUTHENTICATED_REFRESH_INACTIVITY_TIMEOUT = 2 * DAY
+
+/** 1 week */
+export const UNAUTHENTICATED_REFRESH_LIFETIME = 1 * WEEK
+
+/** 1 year */
+export const AUTHENTICATED_REFRESH_LIFETIME = 1 * YEAR
+
+/** 5 minutes */
+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}
+ */
+export const JAR_MAX_AGE = 59 * SECOND
+
+/** 1 minute */
+export const CLIENT_ASSERTION_MAX_AGE = 1 * MINUTE
+
+/** 3 minutes */
+export const DPOP_NONCE_MAX_AGE = 3 * MINUTE
+
+/** 5 seconds */
+export const SESSION_FIXATION_MAX_AGE = 5 * SECOND

package/src/device/device-data.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod'
+
+import { deviceDetailsSchema } from './device-details.js'
+import { sessionIdSchema } from './session-id.js'
+
+export const deviceDataSchema = deviceDetailsSchema.extend({
+  sessionId: sessionIdSchema,
+  lastSeenAt: z.date(),
+})
+
+export type DeviceData = z.infer<typeof deviceDataSchema>

package/src/device/device-details.ts

@@ -0,0 +1,43 @@
+import { IncomingMessage } from 'node:http'
+
+import { z } from 'zod'
+
+export const deviceDetailsSchema = z.object({
+  userAgent: z.string().nullable(),
+  ipAddress: z.string(),
+})
+export type DeviceDetails = z.infer<typeof deviceDetailsSchema>
+
+export function extractDeviceDetails(
+  req: IncomingMessage,
+  trustProxy: boolean,
+): DeviceDetails {
+  const userAgent = req.headers['user-agent'] || null
+  const ipAddress = extractIpAddress(req, trustProxy) || null
+
+  if (!ipAddress) {
+    throw new Error('Could not determine IP address')
+  }
+
+  return { userAgent, ipAddress }
+}
+
+export function extractIpAddress(
+  req: IncomingMessage,
+  trustProxy: boolean,
+): string | undefined {
+  // Express app compatibility
+  if ('ip' in req && typeof req.ip === 'string') {
+    return req.ip
+  }
+
+  if (trustProxy) {
+    const forwardedFor = req.headers['x-forwarded-for']
+    if (typeof forwardedFor === 'string') {
+      const firstForward = forwardedFor.split(',')[0]!.trim()
+      if (firstForward) return firstForward
+    }
+  }
+
+  return req.socket.remoteAddress
+}

package/src/device/device-id.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod'
+
+import { DEVICE_ID_BYTES_LENGTH, DEVICE_ID_PREFIX } from '../constants.js'
+import { randomHexId } from '../lib/util/crypto.js'
+
+export const DEVICE_ID_LENGTH =
+  DEVICE_ID_PREFIX.length + DEVICE_ID_BYTES_LENGTH * 2 // hex encoding
+
+export const deviceIdSchema = z
+  .string()
+  .length(DEVICE_ID_LENGTH)
+  .refine(
+    (v): v is `${typeof DEVICE_ID_PREFIX}${string}` =>
+      v.startsWith(DEVICE_ID_PREFIX),
+    {
+      message: `Invalid device ID format`,
+    },
+  )
+
+export type DeviceId = z.infer<typeof deviceIdSchema>
+export const generateDeviceId = async (): Promise<DeviceId> => {
+  return `${DEVICE_ID_PREFIX}${await randomHexId(DEVICE_ID_BYTES_LENGTH)}`
+}