@atproto/lex-client 0.0.10 → 0.0.11

package/src/response.ts

@@ -7,6 +7,7 @@ import {
   ResultSuccess,
 } from '@atproto/lex-schema'
 import {
+  XrpcAuthenticationError,
   XrpcResponseError,
   XrpcUpstreamError,
   isXrpcErrorPayload,
@@ -26,7 +27,7 @@ export type XrpcResponsePayload<M extends Procedure | Query> =
  *
  * @implements {ResultSuccess<XrpcResponse<M>>} for convenience in result handling contexts.
  */
-export class XrpcResponse<const M extends Procedure | Query>
+export class XrpcResponse<M extends Procedure | Query>
   implements ResultSuccess<XrpcResponse<M>>
 {
   /** @see {@link ResultSuccess.success} */
@@ -63,7 +64,8 @@ export class XrpcResponse<const M extends Procedure | Query>
   /**
    * @throws {XrpcResponseError} in case of (valid) XRPC error responses. Use
    * {@link XrpcResponseError.matchesSchema} to narrow the error type based on
-   * the method's declared error schema.
+   * the method's declared error schema. This can be narrowed further as a
+   * {@link XrpcAuthenticationError} if the error is an authentication error.
    * @throws {XrpcUpstreamError} when the response is not a valid XRPC
    * response, or if the response does not conform to the method's schema.
    */
@@ -79,39 +81,49 @@ export class XrpcResponse<const M extends Procedure | Query>
     // @NOTE redirect is set to 'follow', so we shouldn't get 3xx responses here
     if (response.status < 200 || response.status >= 300) {
       // Always parse json for error responses
-      const payload = await readPayload(response, { parse: true })
+      const payload = await readPayload(response, { parse: true }).catch(
+        (cause) => {
+          throw new XrpcUpstreamError(
+            method,
+            response,
+            null,
+            'Unable to parse response payload',
+            { cause },
+          )
+        },
+      )
 
+      // Properly formatted XRPC error response ?
       if (response.status >= 400 && isXrpcErrorPayload(payload)) {
-        throw new XrpcResponseError(
-          method,
-          response.status,
-          response.headers,
-          payload,
-        )
-      }
-
-      if (response.status >= 500) {
-        throw new XrpcUpstreamError(
-          'UpstreamFailure',
-          `Upstream server encountered an error`,
-          response,
-          payload,
-        )
+        throw response.status === 401
+          ? new XrpcAuthenticationError<M>(method, response, payload)
+          : new XrpcResponseError<M>(method, response, payload)
       }
 
+      // Invalid XRPC response (we probably did not hit an XRPC implementation)
       throw new XrpcUpstreamError(
-        'InvalidResponse',
-        response.status >= 400
-          ? `Upstream server returned an invalid response payload`
-          : `Upstream server returned an invalid status code`,
+        method,
         response,
         payload,
+        response.status >= 500
+          ? 'Upstream server encountered an error'
+          : response.status >= 400
+            ? 'Invalid response payload'
+            : 'Invalid response status code',
       )
     }
 
     // Only parse json if the schema expects it
     const payload = await readPayload(response, {
       parse: shouldParse(method),
+    }).catch((cause) => {
+      throw new XrpcUpstreamError(
+        method,
+        response,
+        null,
+        'Unable to parse response payload',
+        { cause },
+      )
     })
 
     // Response is successful (2xx). Validate payload (data and encoding) against schema.
@@ -119,22 +131,22 @@ export class XrpcResponse<const M extends Procedure | Query>
       // Schema expects no payload
       if (payload) {
         throw new XrpcUpstreamError(
-          'InvalidResponse',
-          `Expected response with no body, got ${payload.encoding}`,
+          method,
           response,
           payload,
+          `Expected response with no body, got ${payload.encoding}`,
         )
       }
     } else {
       // Schema expects a payload
       if (!payload || !method.output.matchesEncoding(payload.encoding)) {
         throw new XrpcUpstreamError(
-          'InvalidResponse',
+          method,
+          response,
+          payload,
           payload
             ? `Expected ${method.output.encoding} response, got ${payload.encoding}`
             : `Expected non-empty response with content-type ${method.output.encoding}`,
-          response,
-          payload,
         )
       }
 
@@ -144,10 +156,10 @@ export class XrpcResponse<const M extends Procedure | Query>
 
         if (!result.success) {
           throw new XrpcUpstreamError(
-            'InvalidResponse',
-            `Response validation failed: ${result.reason.message}`,
+            method,
             response,
             payload,
+            `Response validation failed: ${result.reason.message}`,
             { cause: result.reason },
           )
         }
@@ -204,22 +216,12 @@ async function readPayload(
     // to @ipld/dag-json)
     const text = await response.text()
 
-    try {
-      // @NOTE Using `lexParse(text)` (instead of `jsonToLex(json)`) here as
-      // using a reviver function during JSON.parse should be faster than
-      // parsing to JSON then converting to Lex (?)
+    // @NOTE Using `lexParse(text)` (instead of `jsonToLex(json)`) here as
+    // using a reviver function during JSON.parse should be faster than
+    // parsing to JSON then converting to Lex (?)
 
-      // @TODO verify statement above
-      return { encoding, body: lexParse(text) }
-    } catch (cause) {
-      throw new XrpcUpstreamError(
-        'InvalidResponse',
-        'Invalid JSON response body',
-        response,
-        null,
-        { cause },
-      )
-    }
+    // @TODO verify statement above
+    return { encoding, body: lexParse(text) }
   }
 
   return { encoding, body: new Uint8Array(await response.arrayBuffer()) }

package/src/www-authenticate.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it } from 'vitest'
+import { parseWWWAuthenticateHeader } from './www-authenticate.js'
+
+describe(parseWWWAuthenticateHeader, () => {
+  describe('auth-params', () => {
+    it('parses single unquoted auth param', () => {
+      expect(parseWWWAuthenticateHeader('Bearer realm=example.com')).toEqual({
+        Bearer: { realm: 'example.com' },
+      })
+    })
+
+    it('parses single quoted auth param', () => {
+      expect(parseWWWAuthenticateHeader('Bearer realm="example.com"')).toEqual({
+        Bearer: { realm: 'example.com' },
+      })
+    })
+
+    it('parses quoted values with spaces', () => {
+      expect(parseWWWAuthenticateHeader('Bearer realm="my realm"')).toEqual({
+        Bearer: { realm: 'my realm' },
+      })
+    })
+
+    it('parses quoted values with escaped double quotes', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer realm="example\\"quoted\\""'),
+      ).toEqual({
+        Bearer: { realm: 'example"quoted"' },
+      })
+    })
+
+    it('parses quoted values with escaped backslash', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer realm="path\\\\to\\\\file"'),
+      ).toEqual({
+        Bearer: { realm: 'path\\to\\file' },
+      })
+    })
+
+    it('parses param names with hyphens', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer error-uri="https://example.com"'),
+      ).toEqual({
+        Bearer: { 'error-uri': 'https://example.com' },
+      })
+    })
+
+    it('parses param names with underscores', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer error_description="test"'),
+      ).toEqual({
+        Bearer: { error_description: 'test' },
+      })
+    })
+
+    it('parses param with numeric value', () => {
+      expect(parseWWWAuthenticateHeader('Bearer max-age=3600')).toEqual({
+        Bearer: { 'max-age': '3600' },
+      })
+    })
+
+    it('parses empty quoted value', () => {
+      expect(parseWWWAuthenticateHeader('Bearer realm=""')).toEqual({
+        Bearer: { realm: '' },
+      })
+    })
+
+    it('parses Basic auth challenge', () => {
+      expect(
+        parseWWWAuthenticateHeader('Basic realm="Access to staging site"'),
+      ).toEqual({
+        Basic: { realm: 'Access to staging site' },
+      })
+    })
+
+    it('parses Bearer with realm', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer realm="https://auth.example.com"'),
+      ).toEqual({
+        Bearer: { realm: 'https://auth.example.com' },
+      })
+    })
+
+    it('parses DPoP with algs param', () => {
+      expect(parseWWWAuthenticateHeader('DPoP algs="ES256 RS256"')).toEqual({
+        DPoP: { algs: 'ES256 RS256' },
+      })
+    })
+
+    it('parses Digest auth challenge', () => {
+      const result = parseWWWAuthenticateHeader(
+        'Digest realm="digest-realm", nonce="abc123"',
+      )
+      expect(result).toEqual({
+        Digest: { realm: 'digest-realm', nonce: 'abc123' },
+      })
+    })
+
+    it('handle empty unquoted params', () => {
+      const result = parseWWWAuthenticateHeader('Bearer realm=')
+      expect(result).toEqual({ Bearer: { realm: '' } })
+    })
+
+    it('handle empty params', () => {
+      const result = parseWWWAuthenticateHeader('Bearer realm=""')
+      expect(result).toEqual({ Bearer: { realm: '' } })
+    })
+
+    it('treats scheme-only header as scheme with itself as token68', () => {
+      const result = parseWWWAuthenticateHeader('Basic')
+      expect(result).toEqual({ Basic: {} })
+    })
+
+    it('parses multiple challenges with commas and escaped quotes', () => {
+      const result = parseWWWAuthenticateHeader(
+        `Newauth realm="apps", type=1,\n\t    title="Login to \\"apps\\"", Basic realm="simple"`,
+      )
+      expect(result).toEqual({
+        Newauth: {
+          realm: 'apps',
+          type: '1',
+          title: 'Login to "apps"',
+        },
+        Basic: { realm: 'simple' },
+      })
+    })
+
+    it('parses first challenge before comma', () => {
+      const result = parseWWWAuthenticateHeader(
+        'Basic realm="foo", Bearer realm="bar"',
+      )
+      expect(result).toEqual({
+        Basic: { realm: 'foo' },
+        Bearer: { realm: 'bar' },
+      })
+    })
+  })
+
+  describe('edge cases', () => {
+    it('handles empty string', () => {
+      expect(parseWWWAuthenticateHeader('')).toEqual({})
+    })
+
+    it('handles whitespace-only string', () => {
+      expect(parseWWWAuthenticateHeader('   ')).toEqual({})
+    })
+
+    it('trims whitespace from header', () => {
+      expect(parseWWWAuthenticateHeader('  Bearer realm="test"  ')).toEqual({
+        Bearer: { realm: 'test' },
+      })
+    })
+
+    it('handles commas as quoted param value', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer realm="example, with, commas"'),
+      ).toEqual({ Bearer: { realm: 'example, with, commas' } })
+    })
+
+    it('handles multiple challenges with varying whitespace', () => {
+      expect(
+        parseWWWAuthenticateHeader(
+          '  Bearer realm="test"  ,    Basic    rr=               ',
+        ),
+      ).toEqual({
+        Bearer: { realm: 'test' },
+        Basic: { rr: '' },
+      })
+    })
+  })
+
+  describe('invalid challenges', () => {
+    it('parses single challenge with no comma correctly', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer realm="oauth" error="invalid"'),
+      ).toEqual(undefined)
+    })
+
+    it('ignores invalid challenges', () => {
+      expect(parseWWWAuthenticateHeader('Bearer realm="unclosed')).toEqual(
+        undefined,
+      )
+    })
+
+    it('handles random text without equals sign as token68', () => {
+      expect(parseWWWAuthenticateHeader('Bearer sometoken')).toEqual({
+        Bearer: 'sometoken',
+      })
+    })
+
+    it('ignores trailing whitespace after scheme', () => {
+      expect(parseWWWAuthenticateHeader('Bearer   ')).toEqual({ Bearer: {} })
+    })
+
+    it('handles duplicate params (last wins)', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer realm="first", realm="second"'),
+      ).toEqual({ Bearer: { realm: 'second' } })
+    })
+
+    it('extracts valid param after invalid characters', () => {
+      expect(parseWWWAuthenticateHeader('Bearer realm@foo="bar"')).toEqual({
+        Bearer: { 'realm@foo': 'bar' },
+      })
+    })
+
+    it('ignores param with empty name', () => {
+      expect(parseWWWAuthenticateHeader('Bearer ="value"')).toEqual(undefined)
+    })
+
+    it('handles completely malformed input gracefully', () => {
+      expect(parseWWWAuthenticateHeader('!@#$%')).toEqual({ '!@#$%': {} })
+    })
+
+    it('handles duplicate schemes as invalid', () => {
+      expect(
+        parseWWWAuthenticateHeader('Basic realm="first", Basic realm="second"'),
+      ).toEqual(undefined)
+    })
+
+    it('handles params without scheme as invalid', () => {
+      expect(parseWWWAuthenticateHeader('Bearer, realm="foo"')).toEqual(
+        undefined,
+      )
+    })
+  })
+})

package/src/www-authenticate.ts

@@ -0,0 +1,77 @@
+type WWWAuthenticateParams = { [authParam in string]: string }
+export type WWWAuthenticate = {
+  [authScheme in string]:
+    | string // token68
+    | WWWAuthenticateParams
+}
+
+/**
+ * Returns `undefined` if the header is malformed.
+ */
+export function parseWWWAuthenticateHeader(
+  header?: unknown,
+): undefined | WWWAuthenticate {
+  if (typeof header !== 'string') return undefined
+
+  const wwwAuthenticate: WWWAuthenticate = {}
+
+  // Split over commas, not within quoted strings
+  const trimmedHeader = header.trim()
+  if (!trimmedHeader) return wwwAuthenticate
+
+  const parts = trimmedHeader.split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/)
+
+  let currentParams: WWWAuthenticateParams | null = null
+
+  for (let part of parts) {
+    // Check if the part starts with an auth scheme
+    const schemeMatch = part.trim().match(/^([^"=\s]+)(\s+.*)?$/)
+    if (schemeMatch) {
+      const scheme = schemeMatch[1]
+
+      // Duplicate scheme
+      if (Object.hasOwn(wwwAuthenticate, scheme)) return undefined
+
+      const rest = schemeMatch[2]?.trim()
+      if (!rest) {
+        // Scheme only (no params or token68)
+        currentParams = null
+        wwwAuthenticate[scheme] = Object.create(null)
+        continue
+      }
+
+      if (!rest.includes('=')) {
+        // Scheme with token68
+        currentParams = null
+        wwwAuthenticate[scheme] = rest
+        continue
+      }
+
+      // Scheme with params
+
+      currentParams = Object.create(null) as WWWAuthenticateParams
+      wwwAuthenticate[scheme] = currentParams
+
+      // Fall through to parse params
+      part = rest
+    }
+
+    // Invalid header
+    if (!currentParams) return undefined
+
+    const param = part.match(
+      /^\s*([^"\s=]+)=(?:("[^"\\]*(?:\\.[^"\\]*)*")|([^\s,"]*))\s*$/,
+    )
+
+    // invalid param
+    if (!param) return undefined
+
+    const paramName = param[1]
+    const paramValue =
+      param[3] ?? param[2]!.slice(1, -1).replaceAll(/\\(.)/g, '$1')
+
+    currentParams[paramName] = paramValue
+  }
+
+  return wwwAuthenticate
+}

package/src/xrpc.ts

@@ -13,11 +13,7 @@ import {
   getMain,
 } from '@atproto/lex-schema'
 import { Agent } from './agent.js'
-import {
-  XrpcResponseError,
-  XrpcUnexpectedError,
-  XrpcUpstreamError,
-} from './errors.js'
+import { XrpcFailure, asXrpcFailure } from './errors.js'
 import { XrpcResponse } from './response.js'
 import { BinaryBodyInit, CallOptions } from './types.js'
 import {
@@ -49,32 +45,6 @@ export type XrpcOptions<M extends Procedure | Query = Procedure | Query> =
     XrpcInputOptions<XrpcRequestPayload<M>> &
     XrpcParamsOptions<XrpcRequestParams<M>>
 
-export type XrpcFailure<M extends Procedure | Query> =
-  // The server returned a valid XRPC error response
-  | XrpcResponseError<M>
-  // The response was not a valid XRPC response, or it does not match the schema
-  | XrpcUpstreamError
-  // Something went wrong (network error, etc.)
-  | XrpcUnexpectedError
-
-export type XrpcResult<M extends Procedure | Query> =
-  | XrpcResponse<M>
-  | XrpcFailure<M>
-
-/**
- * Utility method to type cast the error thrown by {@link xrpc} to an
- * {@link XrpcFailure} matching the provided method. Only use this function
- * inside a catch block right after calling {@link xrpc}, and use the same
- * method type parameter as used in the {@link xrpc} call.
- */
-export function asXrpcFailure<M extends Procedure | Query = Procedure | Query>(
-  err: unknown,
-): XrpcFailure<M> {
-  if (err instanceof XrpcResponseError) return err
-  if (err instanceof XrpcUpstreamError) return err
-  return XrpcUnexpectedError.from(err)
-}
-
 /**
  * @throws XrpcFailure<M>
  */
@@ -94,13 +64,15 @@ export async function xrpc<const M extends Query | Procedure>(
   ns: Main<M>,
   options: XrpcOptions<M> = {} as XrpcOptions<M>,
 ): Promise<XrpcResponse<M>> {
-  try {
-    return await lexRpcRequest<M>(agent, ns, options)
-  } catch (err) {
-    throw asXrpcFailure<M>(err)
-  }
+  const response = await xrpcSafe<M>(agent, ns, options)
+  if (response.success) return response
+  else throw response
 }
 
+export type XrpcResult<M extends Procedure | Query> =
+  | XrpcResponse<M>
+  | XrpcFailure<M>
+
 export async function xrpcSafe<const M extends Query | Procedure>(
   agent: Agent,
   ns: NonNullable<unknown> extends XrpcOptions<M>
@@ -117,20 +89,16 @@ export async function xrpcSafe<const M extends Query | Procedure>(
   ns: Main<M>,
   options: XrpcOptions<M> = {} as XrpcOptions<M>,
 ): Promise<XrpcResult<M>> {
-  return lexRpcRequest<M>(agent, ns, options).catch(asXrpcFailure<M>)
-}
-
-async function lexRpcRequest<const M extends Query | Procedure>(
-  agent: Agent,
-  ns: Main<M>,
-  options: XrpcOptions<M> = {} as XrpcOptions<M>,
-): Promise<XrpcResponse<M>> {
-  const method = getMain(ns)
   options.signal?.throwIfAborted()
-  const url = xrpcRequestUrl(method, options)
-  const request = xrpcRequestInit(method, options)
-  const response = await agent.fetchHandler(url, request)
-  return XrpcResponse.fromFetchResponse<M>(method, response, options)
+  const method: M = getMain(ns)
+  try {
+    const url = xrpcRequestUrl(method, options)
+    const request = xrpcRequestInit(method, options)
+    const response = await agent.fetchHandler(url, request)
+    return await XrpcResponse.fromFetchResponse<M>(method, response, options)
+  } catch (cause) {
+    return asXrpcFailure(method, cause)
+  }
 }
 
 function xrpcRequestUrl<M extends Procedure | Query | Subscription>(