@atproto/oauth-provider 0.6.5 → 0.7.0

package/src/router/create-authorization-page-middleware.ts

@@ -0,0 +1,173 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import {
+  oauthAuthorizationRequestQuerySchema,
+  oauthClientCredentialsSchema,
+} from '@atproto/oauth-types'
+import { AccessDeniedError } from '../errors/access-denied-error.js'
+import { InvalidRequestError } from '../errors/invalid-request-error.js'
+import {
+  Middleware,
+  Router,
+  RouterCtx,
+  validateFetchDest,
+  validateFetchMode,
+  validateFetchSite,
+  validateOrigin,
+  validateReferrer,
+} from '../lib/http/index.js'
+import type { Awaitable } from '../lib/util/type.js'
+import { extractZodErrorMessage } from '../lib/util/zod-error.js'
+import type { OAuthProvider } from '../oauth-provider.js'
+import { requestUriSchema } from '../request/request-uri.js'
+import { AuthorizationResultRedirect } from '../result/authorization-result-redirect.js'
+import { sendAuthorizePageFactory } from './assets/send-authorization-page.js'
+import { sendErrorPageFactory } from './assets/send-error-page.js'
+import { parseRedirectUrl } from './create-api-middleware.js'
+import type { MiddlewareOptions } from './middleware-options.js'
+import {
+  buildRedirectMode,
+  buildRedirectParams,
+  buildRedirectUri,
+  sendRedirect,
+} from './send-redirect.js'
+
+export function createAuthorizationPageMiddleware<
+  Ctx extends object | void = void,
+  Req extends IncomingMessage = IncomingMessage,
+  Res extends ServerResponse = ServerResponse,
+>(
+  server: OAuthProvider,
+  { onError }: MiddlewareOptions<Req, Res>,
+): Middleware<Ctx, Req, Res> {
+  const sendAuthorizePage = sendAuthorizePageFactory(server.customization)
+  const sendErrorPage = sendErrorPageFactory(server.customization)
+
+  const issuerUrl = new URL(server.issuer)
+  const issuerOrigin = issuerUrl.origin
+
+  const router = new Router<Ctx, Req, Res>(issuerUrl)
+
+  router.get(
+    '/oauth/authorize',
+    withErrorHandler(async function (req, res) {
+      res.setHeader('Cache-Control', 'no-store')
+      res.setHeader('Pragma', 'no-cache')
+
+      validateFetchSite(req, ['cross-site', 'none'])
+      validateFetchMode(req, ['navigate'])
+      validateFetchDest(req, ['document'])
+      validateOrigin(req, issuerOrigin)
+
+      const query = Object.fromEntries(this.url.searchParams)
+
+      const clientCredentials = await oauthClientCredentialsSchema
+        .parseAsync(query, { path: ['query'] })
+        .catch(throwInvalidRequest)
+
+      if ('client_secret' in clientCredentials) {
+        throw new InvalidRequestError('Client secret must not be provided')
+      }
+
+      const authorizationRequest = await oauthAuthorizationRequestQuerySchema
+        .parseAsync(query, { path: ['query'] })
+        .catch(throwInvalidRequest)
+
+      const deviceInfo = await server.deviceManager.load(req, res)
+
+      try {
+        const result = await server.authorize(
+          clientCredentials,
+          authorizationRequest,
+          deviceInfo.deviceId,
+          deviceInfo.deviceMetadata,
+        )
+
+        if ('redirect' in result) {
+          return sendAuthorizeRedirect(res, result)
+        } else {
+          return sendAuthorizePage(req, res, result)
+        }
+      } catch (err) {
+        // If we have the "redirect_uri" parameter, we can redirect the user
+        // to the client with an error.
+        if (err instanceof AccessDeniedError && err.parameters.redirect_uri) {
+          // Prefer logging the cause
+          onError?.(req, res, err.cause ?? err, 'Authorization failed')
+
+          return sendAuthorizeRedirect(res, {
+            issuer: server.issuer,
+            parameters: err.parameters,
+            redirect: err.toJSON(),
+          })
+        }
+
+        throw err
+      }
+    }),
+  )
+
+  // This is a private endpoint that will be called by the user after the
+  // authorization request was either approved or denied. The logic performed
+  // here **could** be performed directly in the frontend. We decided to
+  // implement it here to avoid duplicating the logic.
+  router.get(
+    '/oauth/authorize/redirect',
+    withErrorHandler(async function (req, res) {
+      // Ensure we come from the authorization page
+      validateFetchSite(req, ['same-origin'])
+      validateFetchMode(req, ['navigate'])
+      validateFetchDest(req, ['document'])
+      validateOrigin(req, issuerOrigin)
+
+      const referrer = validateReferrer(req, {
+        origin: issuerOrigin,
+        pathname: '/oauth/authorize',
+      })
+
+      // Ensure we are coming from the authorization page
+      requestUriSchema.parse(referrer.searchParams.get('request_uri'))
+
+      return sendRedirect(res, parseRedirectUrl(this.url))
+    }),
+  )
+
+  return router.buildMiddleware()
+
+  function withErrorHandler<T extends RouterCtx>(
+    handler: (this: T, req: Req, res: Res) => Awaitable<void>,
+  ): Middleware<T, Req, Res> {
+    return async function (req, res) {
+      try {
+        await handler.call(this, req, res)
+      } catch (err) {
+        onError?.(
+          req,
+          res,
+          err,
+          `Failed to handle navigation request to "${req.url}"`,
+        )
+
+        if (!res.headersSent) {
+          sendErrorPage(req, res, err)
+        }
+      }
+    }
+  }
+}
+
+function throwInvalidRequest(err: unknown): never {
+  throw new InvalidRequestError(
+    extractZodErrorMessage(err) ?? 'Input validation error',
+    err,
+  )
+}
+
+function sendAuthorizeRedirect(
+  res: ServerResponse,
+  { issuer, parameters, redirect }: AuthorizationResultRedirect,
+) {
+  const redirectUri = buildRedirectUri(parameters)
+  const mode = buildRedirectMode(parameters)
+  const params = buildRedirectParams(issuer, parameters, redirect)
+  return sendRedirect(res, { mode, redirectUri, params })
+}

package/src/router/create-oauth-middleware.ts

@@ -0,0 +1,247 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import {
+  oauthAuthorizationRequestParSchema,
+  oauthClientCredentialsSchema,
+  oauthTokenIdentificationSchema,
+  oauthTokenRequestSchema,
+} from '@atproto/oauth-types'
+import { buildErrorPayload, buildErrorStatus } from '../errors/error-parser.js'
+import { InvalidClientError } from '../errors/invalid-client-error.js'
+import { InvalidGrantError } from '../errors/invalid-grant-error.js'
+import { InvalidRequestError } from '../errors/invalid-request-error.js'
+import { WWWAuthenticateError } from '../errors/www-authenticate-error.js'
+import {
+  Middleware,
+  Router,
+  cacheControlMiddleware,
+  combineMiddlewares,
+  jsonHandler,
+  parseHttpRequest,
+  staticJsonMiddleware,
+} from '../lib/http/index.js'
+import { extractZodErrorMessage } from '../lib/util/zod-error.js'
+import type { OAuthProvider } from '../oauth-provider.js'
+import type { MiddlewareOptions } from './middleware-options.js'
+
+// CORS preflight
+const corsHeaders: Middleware = function (req, res, next) {
+  res.setHeader('Access-Control-Max-Age', '86400') // 1 day
+
+  // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin
+  //
+  // > For requests without credentials, the literal value "*" can be
+  // > specified as a wildcard; the value tells browsers to allow
+  // > requesting code from any origin to access the resource.
+  // > Attempting to use the wildcard with credentials results in an
+  // > error.
+  //
+  // A "*" is safer to use than reflecting the request origin.
+  res.setHeader('Access-Control-Allow-Origin', '*')
+
+  // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods
+  // > The value "*" only counts as a special wildcard value for
+  // > requests without credentials (requests without HTTP cookies or
+  // > HTTP authentication information). In requests with credentials,
+  // > it is treated as the literal method name "*" without special
+  // > semantics.
+  res.setHeader('Access-Control-Allow-Methods', '*')
+
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type,DPoP')
+
+  next()
+}
+
+const corsPreflight: Middleware = combineMiddlewares([
+  corsHeaders,
+  (req, res) => {
+    res.writeHead(200).end()
+  },
+])
+
+export function createOAuthMiddleware<
+  Ctx extends object | void = void,
+  Req extends IncomingMessage = IncomingMessage,
+  Res extends ServerResponse = ServerResponse,
+>(
+  server: OAuthProvider,
+  { onError }: MiddlewareOptions<Req, Res>,
+): Middleware<Ctx, Req, Res> {
+  const router = new Router<Ctx, Req, Res>(new URL(server.issuer))
+
+  //- Public OAuth endpoints
+
+  router.options('/.well-known/oauth-authorization-server', corsPreflight)
+  router.get(
+    '/.well-known/oauth-authorization-server',
+    corsHeaders,
+    cacheControlMiddleware(300),
+    staticJsonMiddleware(server.metadata),
+  )
+
+  router.options('/oauth/jwks', corsPreflight)
+  router.get(
+    '/oauth/jwks',
+    corsHeaders,
+    cacheControlMiddleware(300),
+    staticJsonMiddleware(server.jwks),
+  )
+
+  router.options('/oauth/par', corsPreflight)
+  router.post(
+    '/oauth/par',
+    corsHeaders,
+    oauthHandler(async function (req) {
+      const payload = await parseHttpRequest(req, ['json', 'urlencoded'])
+
+      const credentials = await oauthClientCredentialsSchema
+        .parseAsync(payload, { path: ['body'] })
+        .catch(throwInvalidRequest)
+
+      const authorizationRequest = await oauthAuthorizationRequestParSchema
+        .parseAsync(payload, { path: ['body'] })
+        .catch(throwInvalidRequest)
+
+      const dpopJkt = await server.checkDpopProof(
+        req.headers['dpop'],
+        req.method!,
+        this.url,
+      )
+
+      return server.pushedAuthorizationRequest(
+        credentials,
+        authorizationRequest,
+        dpopJkt,
+      )
+    }, 201),
+  )
+  // https://datatracker.ietf.org/doc/html/rfc9126#section-2.3
+  // > If the request did not use the POST method, the authorization server
+  // > responds with an HTTP 405 (Method Not Allowed) status code.
+  router.all('/oauth/par', (req, res) => {
+    res.writeHead(405).end()
+  })
+
+  router.options('/oauth/token', corsPreflight)
+  router.post(
+    '/oauth/token',
+    corsHeaders,
+    oauthHandler(async function (req) {
+      const payload = await parseHttpRequest(req, ['json', 'urlencoded'])
+
+      const clientMetadata = await server.deviceManager.getRequestMetadata(req)
+
+      const clientCredentials = await oauthClientCredentialsSchema
+        .parseAsync(payload, { path: ['body'] })
+        .catch(throwInvalidClient)
+
+      const tokenRequest = await oauthTokenRequestSchema
+        .parseAsync(payload, { path: ['body'] })
+        .catch(throwInvalidGrant)
+
+      const dpopJkt = await server.checkDpopProof(
+        req.headers['dpop'],
+        req.method!,
+        this.url,
+      )
+
+      return server.token(
+        clientCredentials,
+        clientMetadata,
+        tokenRequest,
+        dpopJkt,
+      )
+    }),
+  )
+
+  router.options('/oauth/revoke', corsPreflight)
+  router.post(
+    '/oauth/revoke',
+    corsHeaders,
+    oauthHandler(async function (req, res) {
+      const payload = await parseHttpRequest(req, ['json', 'urlencoded'])
+
+      const credentials = await oauthClientCredentialsSchema
+        .parseAsync(payload, { path: ['body'] })
+        .catch(throwInvalidRequest)
+
+      const tokenIdentification = await oauthTokenIdentificationSchema
+        .parseAsync(payload, { path: ['body'] })
+        .catch(throwInvalidRequest)
+
+      try {
+        await server.revoke(credentials, tokenIdentification)
+      } catch (err) {
+        // > Note: invalid tokens do not cause an error response since the
+        // > client cannot handle such an error in a reasonable way.  Moreover,
+        // > the purpose of the revocation request, invalidating the particular
+        // > token, is already achieved.
+        //
+        // https://datatracker.ietf.org/doc/html/rfc7009#section-2.2
+
+        onError?.(req, res, err, 'Failed to revoke token')
+      }
+
+      return {}
+    }),
+  )
+
+  return router.buildMiddleware()
+
+  function oauthHandler<T>(
+    buildOAuthResponse: (this: T, req: Req, res: Res) => unknown,
+    status?: number,
+  ): Middleware<T, Req, Res> {
+    return jsonHandler<T, Req, Res>(async function (req, res) {
+      try {
+        // https://www.rfc-editor.org/rfc/rfc6749.html#section-5.1
+        res.setHeader('Cache-Control', 'no-store')
+        res.setHeader('Pragma', 'no-cache')
+
+        // https://datatracker.ietf.org/doc/html/rfc9449#section-8.2
+        const dpopNonce = server.nextDpopNonce()
+        if (dpopNonce) {
+          const name = 'DPoP-Nonce'
+          res.setHeader(name, dpopNonce)
+          res.appendHeader('Access-Control-Expose-Headers', name)
+        }
+
+        const payload = await buildOAuthResponse.call(this, req, res)
+        return { payload, status }
+      } catch (err) {
+        onError?.(req, res, err, 'OAuth request error')
+
+        if (!res.headersSent && err instanceof WWWAuthenticateError) {
+          const name = 'WWW-Authenticate'
+          res.setHeader(name, err.wwwAuthenticateHeader)
+          res.appendHeader('Access-Control-Expose-Headers', name)
+        }
+
+        const status = buildErrorStatus(err)
+        const payload = buildErrorPayload(err)
+
+        return { payload, status }
+      }
+    })
+  }
+}
+
+function throwInvalidGrant(err: unknown): never {
+  throw new InvalidGrantError(
+    extractZodErrorMessage(err) ?? 'Invalid grant',
+    err,
+  )
+}
+
+function throwInvalidClient(err: unknown): never {
+  throw new InvalidClientError(
+    extractZodErrorMessage(err) ?? 'Client authentication failed',
+    err,
+  )
+}
+
+function throwInvalidRequest(err: unknown): never {
+  throw new InvalidRequestError(
+    extractZodErrorMessage(err) ?? 'Input validation error',
+    err,
+  )
+}

package/src/router/error-handler.ts

@@ -0,0 +1,6 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+export type ErrorHandler<
+  Req extends IncomingMessage = IncomingMessage,
+  Res extends ServerResponse = ServerResponse,
+> = (req: Req, res: Res, err: unknown, message: string) => void

package/src/router/middleware-options.ts

@@ -0,0 +1,9 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { ErrorHandler } from './error-handler.js'
+
+export type MiddlewareOptions<
+  Req extends IncomingMessage = IncomingMessage,
+  Res extends ServerResponse = ServerResponse,
+> = {
+  onError?: ErrorHandler<Req, Res>
+}

package/src/router/send-redirect.ts

@@ -0,0 +1,142 @@
+import type { ServerResponse } from 'node:http'
+import {
+  OAuthAuthorizationRequestParameters,
+  OAuthResponseMode,
+} from '@atproto/oauth-types'
+import { AccessDeniedError } from '../errors/access-denied-error.js'
+import { html, js } from '../lib/html/index.js'
+import { sendWebPage } from '../lib/send-web-page.js'
+import { AuthorizationRedirectParameters } from '../result/authorization-redirect-parameters.js'
+
+// https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11#section-7.5.4
+const REDIRECT_STATUS_CODE = 303
+
+export const SUCCESS_REDIRECT_KEYS = [
+  'code',
+  'id_token',
+  'access_token',
+  'expires_in',
+  'token_type',
+] as const
+
+export const ERROR_REDIRECT_KEYS = [
+  'error',
+  'error_description',
+  'error_uri',
+] as const
+
+export type OAuthRedirectQueryParameter =
+  | 'iss'
+  | 'state'
+  | (typeof SUCCESS_REDIRECT_KEYS)[number]
+  | (typeof ERROR_REDIRECT_KEYS)[number]
+
+export function buildRedirectUri(
+  parameters: OAuthAuthorizationRequestParameters,
+): string {
+  const uri = parameters.redirect_uri
+  if (uri) return uri
+
+  throw new AccessDeniedError(parameters, 'No redirect_uri', 'invalid_request')
+}
+
+export function buildRedirectMode(
+  parameters: OAuthAuthorizationRequestParameters,
+): OAuthResponseMode {
+  const mode = parameters.response_mode || 'query' // @TODO default should depend on response_type
+  return mode
+}
+
+export function buildRedirectParams(
+  issuer: string,
+  parameters: OAuthAuthorizationRequestParameters,
+  redirect: AuthorizationRedirectParameters,
+): [OAuthRedirectQueryParameter, string][] {
+  const params: [OAuthRedirectQueryParameter, string][] = [
+    ['iss', issuer], // rfc9207
+  ]
+
+  if (parameters.state != null) {
+    params.push(['state', parameters.state])
+  }
+
+  const keys = 'code' in redirect ? SUCCESS_REDIRECT_KEYS : ERROR_REDIRECT_KEYS
+  for (const key of keys) {
+    const value = redirect[key]
+    if (value != null) params.push([key, value])
+  }
+
+  return params
+}
+
+export type OAuthRedirectOptions = {
+  mode: OAuthResponseMode
+  redirectUri: string
+  params: Iterable<[string, string]>
+}
+
+export function sendRedirect(
+  res: ServerResponse,
+  { mode, redirectUri: uri, params }: OAuthRedirectOptions,
+): void {
+  res.setHeader('Cache-Control', 'no-store')
+
+  switch (mode) {
+    case 'query':
+      return writeQuery(res, uri, params)
+    case 'fragment':
+      return writeFragment(res, uri, params)
+    case 'form_post':
+      return writeFormPost(res, uri, params)
+  }
+
+  // @ts-expect-error fool proof
+  throw new Error(`Unsupported mode: ${mode}`)
+}
+
+function writeQuery(
+  res: ServerResponse,
+  uri: string,
+  params: Iterable<[string, string]>,
+): void {
+  const url = new URL(uri)
+  for (const [key, value] of params) url.searchParams.set(key, value)
+  res.writeHead(REDIRECT_STATUS_CODE, { Location: url.href }).end()
+}
+
+function writeFragment(
+  res: ServerResponse,
+  uri: string,
+  params: Iterable<[string, string]>,
+): void {
+  const url = new URL(uri)
+  const searchParams = new URLSearchParams()
+  for (const [key, value] of params) searchParams.set(key, value)
+  url.hash = searchParams.toString()
+  res.writeHead(REDIRECT_STATUS_CODE, { Location: url.href }).end()
+}
+
+function writeFormPost(
+  res: ServerResponse,
+  uri: string,
+  params: Iterable<[string, string]>,
+): void {
+  // 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}">
+        ${Array.from(params, ([key, value]) => [
+          html`<input type="hidden" name="${key}" value="${value}" />`,
+        ])}
+        <input type="submit" value="Continue" />
+      </form>
+    `,
+    scripts: [js`document.forms[0].submit();`],
+  })
+}

package/src/signer/api-token-payload.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod'
+import { jwtPayloadSchema } from '@atproto/jwk'
+import { deviceIdSchema } from '../oauth-store.js'
+import { subSchema } from '../oidc/sub.js'
+import { requestUriSchema } from '../request/request-uri.js'
+
+export const apiTokenPayloadSchema = jwtPayloadSchema
+  .extend({
+    sub: subSchema,
+
+    deviceId: deviceIdSchema,
+    // If the token is bound to a particular authorization request, it can only
+    // be used in the context of that request.
+    requestUri: requestUriSchema.optional(),
+  })
+  .passthrough()
+
+export type ApiTokenPayload = z.infer<typeof apiTokenPayloadSchema>

package/src/signer/signed-token-payload.ts

@@ -1,35 +1,25 @@
 import { z } from 'zod'
 import { jwtPayloadSchema } from '@atproto/jwk'
 import { clientIdSchema } from '../client/client-id.js'
-import { Simplify } from '../lib/util/type.js'
 import { subSchema } from '../oidc/sub.js'
 import { tokenIdSchema } from '../token/token-id.js'
 
-export const signedTokenPayloadSchema = z.intersection(
-  jwtPayloadSchema
-    .pick({
-      exp: true,
-      iat: true,
-      iss: true,
-      aud: true,
-    })
-    .required(),
-  jwtPayloadSchema
-    .omit({
-      exp: true,
-      iat: true,
-      iss: true,
-      aud: true,
-    })
-    .partial()
-    .extend({
-      jti: tokenIdSchema,
-      sub: subSchema,
-      client_id: clientIdSchema,
-    })
-    .passthrough(),
-)
+export const signedTokenPayloadSchema = jwtPayloadSchema
+  .partial()
+  .extend({
+    // Following are required
+    jti: tokenIdSchema,
+    sub: subSchema,
+    exp: z.number().int(),
+    iat: z.number().int(),
+    iss: z.string().min(1),
 
-export type SignedTokenPayload = Simplify<
-  z.infer<typeof signedTokenPayloadSchema>
->
+    // @NOTE "aud", "scope", "client_id" are not required, as are stored in the
+    // DB in 'light' access token mode.
+
+    // Restrict type of following
+    client_id: clientIdSchema.optional(),
+  })
+  .passthrough()
+
+export type SignedTokenPayload = z.infer<typeof signedTokenPayloadSchema>