@atproto/oauth-provider 0.1.0

package/src/oauth-store.ts

@@ -0,0 +1,11 @@
+/**
+ * Every store file exports all the types needed to implement that store. This
+ * files re-exports all the types from the x-store files.
+ */
+
+export * from './account/account-store.js'
+export * from './client/client-store.js'
+export * from './device/device-store.js'
+export * from './replay/replay-store.js'
+export * from './request/request-store.js'
+export * from './token/token-store.js'

package/src/oauth-verifier.ts

@@ -0,0 +1,219 @@
+import { Key, Keyset, isSignedJwt } from '@atproto/jwk'
+import {
+  AccessToken,
+  OAuthTokenType,
+  oauthIssuerIdentifierSchema,
+} from '@atproto/oauth-types'
+import { Redis, type RedisOptions } from 'ioredis'
+
+import { AccessTokenType } from './access-token/access-token-type.js'
+import { DpopManager, DpopManagerOptions } from './dpop/dpop-manager.js'
+import { DpopNonce } from './dpop/dpop-nonce.js'
+import { InvalidDpopProofError } from './errors/invalid-dpop-proof-error.js'
+import { InvalidTokenError } from './errors/invalid-token-error.js'
+import { UseDpopNonceError } from './errors/use-dpop-nonce-error.js'
+import { WWWAuthenticateError } from './errors/www-authenticate-error.js'
+import { parseAuthorizationHeader } from './lib/util/authorization-header.js'
+import { Override } from './lib/util/type.js'
+import { ReplayManager } from './replay/replay-manager.js'
+import { ReplayStoreMemory } from './replay/replay-store-memory.js'
+import { ReplayStoreRedis } from './replay/replay-store-redis.js'
+import { ReplayStore } from './replay/replay-store.js'
+import { Signer } from './signer/signer.js'
+import {
+  VerifyTokenClaimsOptions,
+  VerifyTokenClaimsResult,
+  verifyTokenClaims,
+} from './token/verify-token-claims.js'
+
+export type OAuthVerifierOptions = Override<
+  DpopManagerOptions,
+  {
+    /**
+     * The "issuer" identifier of the OAuth provider, this is the base URL of the
+     * OAuth provider.
+     */
+    issuer: URL | string
+
+    /**
+     * The keyset used to sign tokens. Note that OIDC requires that at least one
+     * RS256 key is present in the keyset. ATPROTO requires ES256.
+     */
+    keyset: Keyset | Iterable<Key | undefined | null | false>
+
+    /**
+     * If set to {@link AccessTokenType.jwt}, the provider will use JWTs for
+     * access tokens. If set to {@link AccessTokenType.id}, the provider will
+     * use tokenId as access tokens. If set to {@link AccessTokenType.auto},
+     * JWTs will only be used if the audience is different from the issuer.
+     * Defaults to {@link AccessTokenType.jwt}.
+     *
+     * Here is a comparison of the two types:
+     *
+     * - pro id: less CPU intensive (no crypto operations)
+     * - pro id: less bandwidth (shorter tokens than jwt)
+     * - pro id: token data is in sync with database (e.g. revocation)
+     * - pro jwt: stateless: no I/O needed (no db lookups through token store)
+     * - pro jwt: stateless: allows Resource Server to be on a different
+     *   host/server
+     */
+    accessTokenType?: AccessTokenType
+
+    /**
+     * A redis instance to use for replay protection. If not provided, replay
+     * protection will use memory storage.
+     */
+    redis?: Redis | RedisOptions | string
+
+    replayStore?: ReplayStore
+  }
+>
+
+export {
+  AccessTokenType,
+  DpopNonce,
+  Keyset,
+  type ReplayStore,
+  type VerifyTokenClaimsOptions,
+}
+
+export class OAuthVerifier {
+  public readonly issuer: string
+  public readonly keyset: Keyset
+
+  protected readonly accessTokenType: AccessTokenType
+  protected readonly dpopManager: DpopManager
+  protected readonly replayManager: ReplayManager
+  protected readonly signer: Signer
+
+  constructor({
+    redis,
+    issuer,
+    keyset,
+    replayStore = redis != null
+      ? new ReplayStoreRedis({ redis })
+      : new ReplayStoreMemory(),
+    accessTokenType = AccessTokenType.jwt,
+
+    ...dpopMgrOptions
+  }: OAuthVerifierOptions) {
+    const issuerParsed = oauthIssuerIdentifierSchema.parse(issuer)
+    const issuerUrl = new URL(issuerParsed)
+
+    // TODO (?) support issuer with path
+    if (issuerUrl.pathname !== '/') {
+      throw new TypeError(
+        `"issuer" must be an URL with no path, search or hash (${issuerUrl})`,
+      )
+    }
+
+    this.issuer = issuerParsed
+    this.keyset = keyset instanceof Keyset ? keyset : new Keyset(keyset)
+
+    this.accessTokenType = accessTokenType
+    this.dpopManager = new DpopManager(dpopMgrOptions)
+    this.replayManager = new ReplayManager(replayStore)
+    this.signer = new Signer(this.issuer, this.keyset)
+  }
+
+  public nextDpopNonce() {
+    return this.dpopManager.nextNonce()
+  }
+
+  public async checkDpopProof(
+    proof: unknown,
+    htm: string,
+    htu: string | URL,
+    accessToken?: string,
+  ): Promise<string | null> {
+    if (proof === undefined) return null
+
+    const { payload, jkt } = await this.dpopManager.checkProof(
+      proof,
+      htm,
+      htu,
+      accessToken,
+    )
+
+    const unique = await this.replayManager.uniqueDpop(payload.jti)
+    if (!unique) throw new InvalidDpopProofError('DPoP proof jti is not unique')
+
+    return jkt
+  }
+
+  protected assertTokenTypeAllowed(
+    tokenType: OAuthTokenType,
+    accessTokenType: AccessTokenType,
+  ) {
+    if (
+      this.accessTokenType !== AccessTokenType.auto &&
+      this.accessTokenType !== accessTokenType
+    ) {
+      throw new InvalidTokenError(tokenType, `Invalid token type`)
+    }
+  }
+
+  protected async authenticateToken(
+    tokenType: OAuthTokenType,
+    token: AccessToken,
+    dpopJkt: string | null,
+    verifyOptions?: VerifyTokenClaimsOptions,
+  ): Promise<VerifyTokenClaimsResult> {
+    if (!isSignedJwt(token)) {
+      throw new InvalidTokenError(tokenType, `Malformed token`)
+    }
+
+    this.assertTokenTypeAllowed(tokenType, AccessTokenType.jwt)
+
+    const { payload } = await this.signer
+      .verifyAccessToken(token)
+      .catch((err) => {
+        throw InvalidTokenError.from(err, tokenType)
+      })
+
+    return verifyTokenClaims(
+      token,
+      payload.jti,
+      tokenType,
+      dpopJkt,
+      payload,
+      verifyOptions,
+    )
+  }
+
+  public async authenticateRequest(
+    method: string,
+    url: URL,
+    headers: {
+      authorization?: string
+      dpop?: unknown
+    },
+    verifyOptions?: VerifyTokenClaimsOptions,
+  ): Promise<VerifyTokenClaimsResult> {
+    const [tokenType, token] = parseAuthorizationHeader(headers.authorization)
+    try {
+      const dpopJkt = await this.checkDpopProof(
+        headers.dpop,
+        method,
+        url,
+        token,
+      )
+
+      if (tokenType === 'DPoP' && !dpopJkt) {
+        throw new InvalidDpopProofError(`DPoP proof required`)
+      }
+
+      return await this.authenticateToken(
+        tokenType,
+        token,
+        dpopJkt,
+        verifyOptions,
+      )
+    } catch (err) {
+      if (err instanceof UseDpopNonceError) throw err.toWwwAuthenticateError()
+      if (err instanceof WWWAuthenticateError) throw err
+
+      throw InvalidTokenError.from(err, tokenType)
+    }
+  }
+}

package/src/oidc/claims.ts

@@ -0,0 +1,35 @@
+import { JwtPayload } from '@atproto/jwk'
+
+/**
+ * @see {@link https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims | OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values}
+ */
+export const OIDC_SCOPE_CLAIMS = Object.freeze({
+  email: Object.freeze(['email', 'email_verified'] as const),
+  phone: Object.freeze(['phone_number', 'phone_number_verified'] as const),
+  address: Object.freeze(['address'] as const),
+  profile: Object.freeze([
+    'name',
+    'family_name',
+    'given_name',
+    'middle_name',
+    'nickname',
+    'preferred_username',
+    'gender',
+    'picture',
+    'profile',
+    'website',
+    'birthdate',
+    'zoneinfo',
+    'locale',
+    'updated_at',
+  ] as const),
+})
+
+export const OIDC_STANDARD_CLAIMS = Object.freeze(
+  Object.values(OIDC_SCOPE_CLAIMS).flat(),
+)
+
+export type OIDCStandardClaim = (typeof OIDC_STANDARD_CLAIMS)[number]
+export type OIDCStandardPayload = Partial<{
+  [K in OIDCStandardClaim]?: JwtPayload[K]
+}>

package/src/oidc/sub.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod'
+
+export const subSchema = z.string().min(1)
+export type Sub = z.infer<typeof subSchema>

package/src/oidc/userinfo.ts

@@ -0,0 +1,11 @@
+import { OIDCStandardPayload } from './claims.js'
+
+export type Userinfo = OIDCStandardPayload & {
+  // "The sub (subject) Claim MUST always be returned in the UserInfo Response."
+  sub: string
+
+  // client_id is not mandatory per spec, but we require it here for convenience
+  client_id: string
+
+  username?: string
+}

package/src/output/build-error-payload.ts

@@ -0,0 +1,143 @@
+import { JwtVerifyError } from '@atproto/jwk'
+import { JOSEError } from 'jose/errors'
+import { ZodError } from 'zod'
+
+import { OAuthError } from '../errors/oauth-error.js'
+
+const INVALID_REQUEST = 'invalid_request'
+const SERVER_ERROR = 'server_error'
+
+export function buildErrorStatus(error: unknown): number {
+  if (error instanceof OAuthError) {
+    return error.statusCode
+  }
+
+  if (error instanceof JwtVerifyError) {
+    return 400
+  }
+
+  if (error instanceof ZodError) {
+    return 400
+  }
+
+  if (error instanceof JOSEError) {
+    return 400
+  }
+
+  if (error instanceof TypeError) {
+    return 400
+  }
+
+  if (isBoom(error)) {
+    return error.output.statusCode
+  }
+
+  if (isXrpcError(error)) {
+    return error.type
+  }
+
+  const status = (error as any)?.status
+  if (
+    typeof status === 'number' &&
+    status === (status | 0) &&
+    status >= 400 &&
+    status < 600
+  ) {
+    return status
+  }
+
+  return 500
+}
+
+export function buildErrorPayload(error: unknown): {
+  error: string
+  error_description: string
+} {
+  if (error instanceof OAuthError) {
+    return error.toJSON()
+  }
+
+  if (error instanceof ZodError) {
+    return {
+      error: INVALID_REQUEST,
+      error_description: error.issues[0]?.message || 'Invalid request',
+    }
+  }
+
+  if (error instanceof JOSEError) {
+    return {
+      error: INVALID_REQUEST,
+      error_description: error.message,
+    }
+  }
+
+  if (error instanceof TypeError) {
+    return {
+      error: INVALID_REQUEST,
+      error_description: error.message,
+    }
+  }
+
+  if (isBoom(error)) {
+    return {
+      error: error.output.statusCode <= 500 ? INVALID_REQUEST : SERVER_ERROR,
+      error_description:
+        error.output.statusCode <= 500
+          ? isPayloadLike(error.output?.payload)
+            ? error.output.payload.message
+            : error.message
+          : 'Server error',
+    }
+  }
+
+  if (isXrpcError(error)) {
+    return {
+      error: error.type <= 500 ? INVALID_REQUEST : SERVER_ERROR,
+      error_description: error.payload.message,
+    }
+  }
+
+  const status = buildErrorStatus(error)
+  return {
+    error: status < 500 ? INVALID_REQUEST : SERVER_ERROR,
+    error_description:
+      error instanceof Error && (error as any)?.expose === true
+        ? error.message
+        : 'Server error',
+  }
+}
+
+function isBoom(v: unknown): v is Error & {
+  isBoom: true
+  output: { statusCode: number; payload: unknown }
+} {
+  return (
+    v instanceof Error &&
+    (v as any).isBoom === true &&
+    isHttpErrorCode(v['output']?.['statusCode'])
+  )
+}
+
+function isXrpcError(v: unknown): v is Error & {
+  type: number
+  payload: { error: string; message: string }
+} {
+  return (
+    v instanceof Error &&
+    isHttpErrorCode(v['type']) &&
+    isPayloadLike(v['payload'])
+  )
+}
+
+function isHttpErrorCode(v: unknown): v is number {
+  return typeof v === 'number' && v >= 400 && v < 600 && v === (v | 0)
+}
+
+function isPayloadLike(v: unknown): v is { error: string; message: string } {
+  return (
+    v != null &&
+    typeof v === 'object' &&
+    typeof v['error'] === 'string' &&
+    typeof v['message'] === 'string'
+  )
+}

package/src/output/customization.ts

@@ -0,0 +1,96 @@
+// Matches colors defined in tailwind.config.js
+const colorNames = ['primary', 'error'] as const
+type ColorName = (typeof colorNames)[number]
+const isColorName = (name: string): name is ColorName =>
+  (colorNames as readonly string[]).includes(name)
+
+export type FieldDefinition = {
+  label?: string
+  placeholder?: string
+  pattern?: string
+  title?: string
+}
+
+export type ExtraFieldDefinition = FieldDefinition & {
+  type: 'text' | 'password' | 'date' | 'captcha'
+  required?: boolean
+  [_: string]: unknown
+}
+
+export type Customization = {
+  name?: string
+  logo?: string
+  colors?: { [_ in ColorName]?: string }
+  links?: Array<{
+    href: string
+    title: string
+    rel?: string
+  }>
+}
+
+export function buildCustomizationData({
+  name,
+  logo,
+  links,
+}: Customization = {}) {
+  return {
+    name,
+    logo,
+    links,
+  }
+}
+
+export function buildCustomizationCss(customization?: Customization) {
+  if (!customization?.colors) return ''
+
+  const vars = Object.entries(customization.colors)
+    .filter((e) => isColorName(e[0]) && e[1] != null)
+    .map(([name, value]) => [name, parseColor(value)] as const)
+    .filter((e): e is [ColorName, ParsedColor] => e[1] != null)
+    // alpha not supported by tailwind (it does not work that way)
+    .map(([name, { r, g, b }]) => `--color-${name}: ${r} ${g} ${b};`)
+
+  return `:root { ${vars.join(' ')} }`
+}
+
+type ParsedColor = { r: number; g: number; b: number; a?: number }
+function parseColor(color: string): undefined | ParsedColor {
+  if (color.startsWith('#')) {
+    if (color.length === 4 || color.length === 5) {
+      const [r, g, b, a] = color
+        .slice(1)
+        .split('')
+        .map((c) => parseInt(c + c, 16))
+      return { r, g, b, a }
+    }
+
+    if (color.length === 7 || color.length === 9) {
+      const r = parseInt(color.slice(1, 3), 16)
+      const g = parseInt(color.slice(3, 5), 16)
+      const b = parseInt(color.slice(5, 7), 16)
+      const a = color.length > 8 ? parseInt(color.slice(7, 9), 16) : undefined
+      return { r, g, b, a }
+    }
+
+    return undefined
+  }
+
+  const rgbMatch = color.match(/rgb\((\d+),\s*(\d+),\s*(\d+)\)/)
+  if (rgbMatch) {
+    const [, r, g, b] = rgbMatch
+    return { r: parseInt(r, 10), g: parseInt(g, 10), b: parseInt(b, 10) }
+  }
+
+  const rgbaMatch = color.match(/rgba\((\d+),\s*(\d+),\s*(\d+),\s*(\d+)\)/)
+  if (rgbaMatch) {
+    const [, r, g, b, a] = rgbaMatch
+    return {
+      r: parseInt(r, 10),
+      g: parseInt(g, 10),
+      b: parseInt(b, 10),
+      a: parseInt(a, 10),
+    }
+  }
+
+  return undefined
+}

package/src/output/send-authorize-page.ts

@@ -0,0 +1,111 @@
+import {
+  OAuthAuthenticationRequestParameters,
+  OAuthClientMetadata,
+} from '@atproto/oauth-types'
+import { ServerResponse } from 'node:http'
+
+import { DeviceAccountInfo } from '../account/account-store.js'
+import { Account } from '../account/account.js'
+import { getAsset } from '../assets/index.js'
+import { Client } from '../client/client.js'
+import { cssCode, html } from '../lib/html/index.js'
+import { RequestUri } from '../request/request-uri.js'
+import {
+  Customization,
+  buildCustomizationCss,
+  buildCustomizationData,
+} from './customization.js'
+import { declareBackendData, sendWebPage } from './send-web-page.js'
+
+export type AuthorizationResultAuthorize = {
+  issuer: string
+  client: Client
+  parameters: OAuthAuthenticationRequestParameters
+  authorize: {
+    uri: RequestUri
+    sessions: readonly {
+      account: Account
+      info: DeviceAccountInfo
+
+      selected: boolean
+      loginRequired: boolean
+      consentRequired: boolean
+    }[]
+  }
+}
+
+// TODO: find a way to share this type with the frontend code
+// (app/backend-data.ts)
+
+type Session = {
+  account: Account
+  info?: never // Prevent accidental leaks to frontend
+
+  selected: boolean
+  loginRequired: boolean
+  consentRequired: boolean
+}
+
+export type AuthorizeData = {
+  clientId: string
+  clientMetadata: OAuthClientMetadata
+  clientTrusted: boolean
+  requestUri: string
+  csrfCookie: string
+  loginHint?: string
+  newSessionsRequireConsent: boolean
+  sessions: Session[]
+}
+
+function buildAuthorizeData(data: AuthorizationResultAuthorize): AuthorizeData {
+  return {
+    clientId: data.client.id,
+    clientMetadata: data.client.metadata,
+    clientTrusted: data.client.info.isTrusted,
+    requestUri: data.authorize.uri,
+    csrfCookie: `csrf-${data.authorize.uri}`,
+    loginHint: data.parameters.login_hint,
+    newSessionsRequireConsent: data.parameters.prompt === 'consent',
+    sessions: data.authorize.sessions.map(
+      (session): Session => ({
+        account: session.account,
+        selected: session.selected,
+        loginRequired: session.loginRequired,
+        consentRequired: session.consentRequired,
+      }),
+    ),
+  }
+}
+
+export async function sendAuthorizePage(
+  res: ServerResponse,
+  data: AuthorizationResultAuthorize,
+  customization?: Customization,
+): Promise<void> {
+  res.setHeader('Cache-Control', 'no-store')
+  res.setHeader('Permissions-Policy', 'otp-credentials=*, document-domain=()')
+
+  const [jsAsset, cssAsset] = await Promise.all([
+    getAsset('main.js'),
+    getAsset('main.css'),
+  ])
+
+  return sendWebPage(res, {
+    scripts: [
+      declareBackendData(
+        '__customizationData',
+        buildCustomizationData(customization),
+      ),
+      declareBackendData('__authorizeData', buildAuthorizeData(data)),
+      jsAsset, // Last (to be able to read the global variables)
+    ],
+    styles: [
+      cssAsset, // First (to be overridden by customization)
+      cssCode(buildCustomizationCss(customization)),
+    ],
+    links: customization?.links,
+    htmlAttrs: { lang: 'en' },
+    title: 'Authorize',
+    body: html`<div id="root"></div>`,
+  })
+}