@atproto/oauth-provider 0.1.0

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

@@ -0,0 +1,130 @@
+import {
+  OAuthAuthenticationRequestParameters,
+  OAuthTokenType,
+} from '@atproto/oauth-types'
+import { ServerResponse } from 'node:http'
+
+import { Client } from '../client/client.js'
+import { html, js } from '../lib/html/index.js'
+import { Code } from '../request/code.js'
+import { sendWebPage } from './send-web-page.js'
+
+// https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11#section-7.5.4
+const REDIRECT_STATUS_CODE = 303
+
+export type AuthorizationResponseParameters = {
+  // Will be added from AuthorizationResultRedirect['issuer']
+  // iss: string // rfc9207
+
+  // Will be added from AuthorizationResultRedirect['parameters']
+  // state?: string
+
+  code?: Code
+  id_token?: string
+  access_token?: string
+  token_type?: OAuthTokenType
+  expires_in?: string
+
+  response?: string // FAPI JARM
+  session_state?: string // OIDC Session Management
+
+  error?: string
+  error_description?: string
+  error_uri?: string
+}
+
+export type AuthorizationResultRedirect = {
+  issuer: string
+  client: Client
+  parameters: OAuthAuthenticationRequestParameters
+  redirect: AuthorizationResponseParameters
+}
+
+export async function sendAuthorizeRedirect(
+  res: ServerResponse,
+  result: AuthorizationResultRedirect,
+): Promise<void> {
+  const { issuer, parameters, redirect, client } = result
+
+  const uri = parameters.redirect_uri || client.metadata.redirect_uris[0]
+  const mode = parameters.response_mode || 'query' // @TODO: default should depend on response_type
+
+  const entries: [string, string][] = Object.entries({
+    iss: issuer, // rfc9207
+    state: parameters.state,
+
+    response: redirect.response, // FAPI JARM
+    session_state: redirect.session_state, // OIDC Session Management
+
+    code: redirect.code,
+    id_token: redirect.id_token,
+    access_token: redirect.access_token,
+    expires_in: redirect.expires_in,
+    token_type: redirect.token_type,
+
+    error: redirect.error,
+    error_description: redirect.error_description,
+    error_uri: redirect.error_uri,
+  }).filter((entry): entry is [string, string] => entry[1] != null)
+
+  res.setHeader('Cache-Control', 'no-store')
+
+  switch (mode) {
+    case 'query':
+      return writeQuery(res, uri, entries)
+    case 'fragment':
+      return writeFragment(res, uri, entries)
+    case 'form_post':
+      return writeFormPost(res, uri, entries)
+  }
+
+  // @ts-expect-error fool proof
+  throw new Error(`Unsupported mode: ${mode}`)
+}
+
+function writeQuery(
+  res: ServerResponse,
+  uri: string,
+  entries: readonly [string, string][],
+) {
+  const url = new URL(uri)
+  for (const [key, value] of entries) url.searchParams.set(key, value)
+  res.writeHead(REDIRECT_STATUS_CODE, { Location: url.href }).end()
+}
+
+function writeFragment(
+  res: ServerResponse,
+  uri: string,
+  entries: readonly [string, string][],
+) {
+  const url = new URL(uri)
+  const searchParams = new URLSearchParams()
+  for (const [key, value] of entries) searchParams.set(key, value)
+  url.hash = searchParams.toString()
+  res.writeHead(REDIRECT_STATUS_CODE, { Location: url.href }).end()
+}
+
+async function writeFormPost(
+  res: ServerResponse,
+  uri: string,
+  entries: readonly [string, string][],
+) {
+  // Prevent the Chrome from caching this page
+  // see: https://latesthackingnews.com/2023/12/12/google-updates-chrome-bfcache-for-faster-page-viewing/
+  res.setHeader('Set-Cookie', `bfCacheBypass=foo; max-age=1; SameSite=Lax`)
+  res.setHeader('Cache-Control', 'no-store')
+  res.setHeader('Permissions-Policy', 'otp-credentials=*, document-domain=()')
+
+  return sendWebPage(res, {
+    htmlAttrs: { lang: 'en' },
+    body: html`
+      <form method="post" action="${uri}">
+        ${entries.map(([key, value]) => [
+          html`<input type="hidden" name="${key}" value="${value}" />`,
+        ])}
+        <input type="submit" value="Continue" />
+      </form>
+    `,
+    scripts: [js`document.forms[0].submit();`],
+  })
+}

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

@@ -0,0 +1,41 @@
+import { ServerResponse } from 'node:http'
+
+import { getAsset } from '../assets/index.js'
+import { cssCode, html } from '../lib/html/index.js'
+import { buildErrorPayload, buildErrorStatus } from './build-error-payload.js'
+import {
+  Customization,
+  buildCustomizationCss,
+  buildCustomizationData,
+} from './customization.js'
+import { declareBackendData, sendWebPage } from './send-web-page.js'
+
+export async function sendErrorPage(
+  res: ServerResponse,
+  err: unknown,
+  customization?: Customization,
+): Promise<void> {
+  const [jsAsset, cssAsset] = await Promise.all([
+    getAsset('main.js'),
+    getAsset('main.css'),
+  ])
+
+  return sendWebPage(res, {
+    status: buildErrorStatus(err),
+    scripts: [
+      declareBackendData(
+        '__customizationData',
+        buildCustomizationData(customization),
+      ),
+      declareBackendData('__errorData', buildErrorPayload(err)),
+      jsAsset, // Last (to be able to read the global variables)
+    ],
+    styles: [
+      cssAsset, // First (to be overridden by customization)
+      cssCode(buildCustomizationCss(customization)),
+    ],
+    htmlAttrs: { lang: 'en' },
+    title: 'Error',
+    body: html`<div id="root"></div>`,
+  })
+}

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

@@ -0,0 +1,66 @@
+import { createHash } from 'node:crypto'
+import { ServerResponse } from 'node:http'
+
+import {
+  AssetRef,
+  buildDocument,
+  BuildDocumentOptions,
+  Html,
+  js,
+} from '../lib/html/index.js'
+import { writeHtml } from '../lib/http/response.js'
+
+export function declareBackendData(name: string, data: unknown) {
+  // The script tag is removed after the data is assigned to the global variable
+  // to prevent other scripts from deducing the value of the variable. The "app"
+  // script will read the global variable and then unset it. See
+  // "readBackendData" in "src/assets/app/backend-data.ts".
+  return js`window[${name}]=${data};document.currentScript.remove();`
+}
+
+export function sendWebPage(
+  res: ServerResponse,
+  { status = 200, ...options }: BuildDocumentOptions & { status?: number },
+): void {
+  // @TODO: make these headers configurable (?)
+  res.setHeader('Cross-Origin-Embedder-Policy', 'credentialless')
+  res.setHeader('Cross-Origin-Resource-Policy', 'same-origin')
+  res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
+  res.setHeader('Referrer-Policy', 'same-origin')
+  res.setHeader('X-Frame-Options', 'DENY')
+  res.setHeader('X-Content-Type-Options', 'nosniff')
+  res.setHeader('X-XSS-Protection', '0')
+  res.setHeader('Strict-Transport-Security', 'max-age=63072000')
+  res.setHeader(
+    'Content-Security-Policy',
+    [
+      `default-src 'none'`,
+      `frame-ancestors 'none'`,
+      `form-action 'none'`,
+      `base-uri ${options.base?.origin || `'none'`}`,
+      `script-src 'self' ${
+        options.scripts?.map(assetToHash).map(hashToCspRule).join(' ') ?? ''
+      }`,
+      `style-src 'self' ${
+        options.styles?.map(assetToHash).map(hashToCspRule).join(' ') ?? ''
+      }`,
+      `img-src 'self' data: https:`,
+      `connect-src 'self'`,
+      `upgrade-insecure-requests`,
+    ].join('; '),
+  )
+
+  const html = buildDocument(options)
+
+  writeHtml(res, html.toString(), status)
+}
+
+function assetToHash(asset: Html | AssetRef): string {
+  return asset instanceof Html
+    ? createHash('sha256').update(asset.toString()).digest('base64')
+    : asset.sha256
+}
+
+function hashToCspRule(hash: string): string {
+  return `'sha256-${hash}'`
+}

package/src/parameters/claims-requested.ts

@@ -0,0 +1,106 @@
+import {
+  OAuthAuthenticationRequestParameters,
+  OidcClaimsParameter,
+  OidcEntityType,
+} from '@atproto/oauth-types'
+import { InvalidRequestError } from '../errors/invalid-request-error.js'
+
+export function claimRequested(
+  parameters: OAuthAuthenticationRequestParameters,
+  entityType: OidcEntityType,
+  claimName: OidcClaimsParameter,
+  value: unknown,
+): boolean {
+  if (claimAvailable(parameters, entityType, claimName, value)) {
+    return true
+  }
+
+  const entityClaims = parameters.claims?.[entityType]
+  if (entityClaims?.[claimName]?.essential === true) {
+    // https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.5.1
+    //
+    // > By requesting Claims as Essential Claims, the RP indicates to the
+    // > End-User that releasing these Claims will ensure a smooth
+    // > authorization for the specific task requested by the End-User. Note
+    // > that even if the Claims are not available because the End-User did
+    // > not authorize their release or they are not present, the
+    // > Authorization Server MUST NOT generate an error when Claims are not
+    // > returned, whether they are Essential or Voluntary, unless otherwise
+    // > specified in the description of the specific claim.
+    switch (claimName) {
+      case 'acr':
+        // https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.5.1.1
+        //
+        // > If this is an Essential Claim and the requirement cannot be met,
+        // > then the Authorization Server MUST treat that outcome as a failed
+        // > authentication attempt.
+        throw new InvalidRequestError(
+          `Unable to provide essential claim: ${claimName}`,
+        )
+    }
+  }
+
+  return false
+}
+
+function claimAvailable(
+  parameters: OAuthAuthenticationRequestParameters,
+  entityType: OidcEntityType,
+  claimName: OidcClaimsParameter,
+  value: unknown,
+): boolean {
+  if (value === undefined) return false
+
+  if (parameters.claims) {
+    const entityClaims = parameters.claims[entityType]
+    if (entityClaims === undefined) return false
+
+    const claimConfig = entityClaims[claimName]
+    if (claimConfig === undefined) return false
+    if (claimConfig === null) return true
+
+    if (
+      claimConfig.value !== undefined &&
+      !compareClaimValue(claimConfig.value, value)
+    ) {
+      return false
+    }
+
+    if (
+      claimConfig?.values !== undefined &&
+      !claimConfig.values.some((v) => compareClaimValue(v, value))
+    ) {
+      return false
+    }
+  }
+
+  return true
+}
+
+type DefinedValue = NonNullable<unknown> | null
+
+function compareClaimValue(
+  expectedValue: DefinedValue,
+  value: DefinedValue,
+): boolean {
+  const expectedType = typeof expectedValue
+  const valueType = typeof value
+
+  if (expectedType !== valueType) return false
+
+  switch (typeof expectedValue) {
+    case 'undefined':
+    case 'string':
+    case 'number':
+    case 'boolean':
+      return expectedValue === value
+    case 'object':
+      if (expectedValue === null) return value === null
+    // @TODO (?): allow object comparison
+    // falls through
+    default:
+      throw new InvalidRequestError(
+        `Unable to compare claim value of type ${expectedType}`,
+      )
+  }
+}

package/src/parameters/oidc-payload.ts

@@ -0,0 +1,28 @@
+import { OAuthAuthenticationRequestParameters } from '@atproto/oauth-types'
+import { Account } from '../account/account.js'
+import { OIDCStandardPayload, OIDC_SCOPE_CLAIMS } from '../oidc/claims.js'
+import { claimRequested } from './claims-requested.js'
+
+export function oidcPayload(
+  params: OAuthAuthenticationRequestParameters,
+  account: Account,
+) {
+  const payload: OIDCStandardPayload = {}
+
+  const scopes = params.scope ? params.scope?.split(' ') : undefined
+  if (scopes) {
+    for (const [scope, claims] of Object.entries(OIDC_SCOPE_CLAIMS)) {
+      const allowed = scopes.includes(scope)
+      for (const claim of claims) {
+        const value = allowed ? account[claim] : undefined
+        // Should not throw as RequestManager should have already checked
+        // that all the essential claims are available.
+        if (claimRequested(params, 'id_token', claim, value)) {
+          payload[claim] = value as any // All good as long as the account props match the claims
+        }
+      }
+    }
+  }
+
+  return payload
+}

package/src/replay/replay-manager.ts

@@ -0,0 +1,38 @@
+import { ClientId } from '../client/client-id.js'
+import {
+  CLIENT_ASSERTION_MAX_AGE,
+  DPOP_NONCE_MAX_AGE,
+  JAR_MAX_AGE,
+} from '../constants.js'
+import { ReplayStore } from './replay-store.js'
+
+const SECURITY_RATIO = 1.1 // 10% extra time for security
+const asTimeFrame = (timeFrame: number) => Math.ceil(timeFrame * SECURITY_RATIO)
+
+export class ReplayManager {
+  constructor(protected readonly replayStore: ReplayStore) {}
+
+  async uniqueAuth(jti: string, clientId: ClientId): Promise<boolean> {
+    return this.replayStore.unique(
+      `Auth@${clientId}`,
+      jti,
+      asTimeFrame(CLIENT_ASSERTION_MAX_AGE),
+    )
+  }
+
+  async uniqueJar(jti: string, clientId: ClientId): Promise<boolean> {
+    return this.replayStore.unique(
+      `JAR@${clientId}`,
+      jti,
+      asTimeFrame(JAR_MAX_AGE),
+    )
+  }
+
+  async uniqueDpop(jti: string, clientId?: ClientId): Promise<boolean> {
+    return this.replayStore.unique(
+      clientId ? `DPoP@${clientId}` : `DPoP`,
+      jti,
+      asTimeFrame(DPOP_NONCE_MAX_AGE),
+    )
+  }
+}

package/src/replay/replay-store-memory.ts

@@ -0,0 +1,36 @@
+import type { ReplayStore } from './replay-store.js'
+
+export class ReplayStoreMemory implements ReplayStore {
+  private lastCleanup = Date.now()
+  private nonces = new Map<string, number>()
+
+  /**
+   * Returns true if the nonce is unique within the given time frame.
+   */
+  async unique(
+    namespace: string,
+    nonce: string,
+    timeFrame: number,
+  ): Promise<boolean> {
+    this.cleanup()
+    const key = `${namespace}:${nonce}`
+
+    const now = Date.now()
+
+    const exp = this.nonces.get(key)
+    this.nonces.set(key, now + timeFrame)
+
+    return exp == null || exp < now
+  }
+
+  private cleanup() {
+    const now = Date.now()
+
+    if (this.lastCleanup < now - 60_000) {
+      for (const [key, expires] of this.nonces) {
+        if (expires < now) this.nonces.delete(key)
+      }
+      this.lastCleanup = now
+    }
+  }
+}

package/src/replay/replay-store-redis.ts

@@ -0,0 +1,31 @@
+import { Redis } from 'ioredis'
+
+import { CreateRedisOptions, createRedis } from '../lib/redis.js'
+import type { ReplayStore } from './replay-store.js'
+
+export type { CreateRedisOptions, Redis }
+
+export type ReplayStoreRedisOptions = {
+  redis: CreateRedisOptions
+}
+
+export class ReplayStoreRedis implements ReplayStore {
+  private readonly redis: Redis
+
+  constructor(options: ReplayStoreRedisOptions) {
+    this.redis = createRedis(options.redis)
+  }
+
+  /**
+   * Returns true if the nonce is unique within the given time frame.
+   */
+  async unique(
+    namespace: string,
+    nonce: string,
+    timeFrame: number,
+  ): Promise<boolean> {
+    const key = `nonces:${namespace}:${nonce}`
+    const prev = await this.redis.set(key, '1', 'PX', timeFrame, 'GET')
+    return prev == null
+  }
+}

package/src/replay/replay-store.ts

@@ -0,0 +1,44 @@
+import { Awaitable } from '../lib/util/type.js'
+
+// Export all types needed to implement the ReplayStore interface
+export type { Awaitable }
+
+export interface ReplayStore {
+  /**
+   * Returns true if the nonce is unique within the given time frame. While not
+   * strictly necessary for security purposes, the namespace should be used to
+   * mitigate denial of service attacks from one client to the other.
+   *
+   * @param timeFrame expressed in milliseconds. Will never exceed 24 hours.
+   */
+  unique(
+    namespace: string,
+    nonce: string,
+    timeFrame: number,
+  ): Awaitable<boolean>
+}
+
+export function isReplayStore(
+  implementation: Record<string, unknown> & Partial<ReplayStore>,
+): implementation is Record<string, unknown> & ReplayStore {
+  return typeof implementation.unique === 'function'
+}
+
+export function ifReplayStore(
+  implementation?: Record<string, unknown> & Partial<ReplayStore>,
+): ReplayStore | undefined {
+  if (implementation && isReplayStore(implementation)) {
+    return implementation
+  }
+
+  return undefined
+}
+
+export function asReplayStore(
+  implementation?: Record<string, unknown> & Partial<ReplayStore>,
+): ReplayStore {
+  const store = ifReplayStore(implementation)
+  if (store) return store
+
+  throw new Error('Invalid ReplayStore implementation')
+}

package/src/request/code.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+
+import { CODE_BYTES_LENGTH, CODE_PREFIX } from '../constants.js'
+import { randomHexId } from '../lib/util/crypto.js'
+
+export const CODE_LENGTH = CODE_PREFIX.length + CODE_BYTES_LENGTH * 2 // hex encoding
+
+export const codeSchema = z
+  .string()
+  .length(CODE_LENGTH) // hex encoding
+  .refine(
+    (v): v is `${typeof CODE_PREFIX}${string}` => v.startsWith(CODE_PREFIX),
+    {
+      message: `Invalid code format`,
+    },
+  )
+
+export const isCode = (data: unknown): data is Code =>
+  codeSchema.safeParse(data).success
+
+export type Code = z.infer<typeof codeSchema>
+export const generateCode = async (): Promise<Code> => {
+  return `${CODE_PREFIX}${await randomHexId(CODE_BYTES_LENGTH)}`
+}

package/src/request/request-data.ts

@@ -0,0 +1,26 @@
+import { OAuthAuthenticationRequestParameters } from '@atproto/oauth-types'
+
+import { ClientAuth } from '../client/client-auth.js'
+import { ClientId } from '../client/client-id.js'
+import { DeviceId } from '../device/device-id.js'
+import { Sub } from '../oidc/sub.js'
+import { Code } from './code.js'
+
+export type RequestData = {
+  clientId: ClientId
+  clientAuth: ClientAuth
+  parameters: Readonly<OAuthAuthenticationRequestParameters>
+  expiresAt: Date
+  deviceId: DeviceId | null
+  sub: Sub | null
+  code: Code | null
+}
+
+export type RequestDataAuthorized = RequestData & {
+  sub: Sub
+  deviceId: DeviceId
+}
+
+export const isRequestDataAuthorized = (
+  data: RequestData,
+): data is RequestDataAuthorized => data.sub !== null && data.deviceId !== null

package/src/request/request-id.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod'
+
+import { REQUEST_ID_BYTES_LENGTH, REQUEST_ID_PREFIX } from '../constants.js'
+import { randomHexId } from '../lib/util/crypto.js'
+
+export const REQUEST_ID_LENGTH =
+  REQUEST_ID_PREFIX.length + REQUEST_ID_BYTES_LENGTH * 2 // hex encoding
+
+export const requestIdSchema = z
+  .string()
+  .length(REQUEST_ID_LENGTH)
+  .refine(
+    (v): v is `${typeof REQUEST_ID_PREFIX}${string}` =>
+      v.startsWith(REQUEST_ID_PREFIX),
+    {
+      message: `Invalid request ID format`,
+    },
+  )
+
+export type RequestId = z.infer<typeof requestIdSchema>
+export const generateRequestId = async (): Promise<RequestId> => {
+  return `${REQUEST_ID_PREFIX}${await randomHexId(REQUEST_ID_BYTES_LENGTH)}`
+}

package/src/request/request-info.ts

@@ -0,0 +1,12 @@
+import { OAuthAuthenticationRequestParameters } from '@atproto/oauth-types'
+import { ClientAuth } from '../client/client-auth.js'
+import { RequestId } from './request-id.js'
+import { RequestUri } from './request-uri.js'
+
+export type RequestInfo = {
+  id: RequestId
+  uri: RequestUri
+  parameters: Readonly<OAuthAuthenticationRequestParameters>
+  expiresAt: Date
+  clientAuth: ClientAuth
+}