@atproto/oauth-client 0.3.22 → 0.4.0

package/src/oauth-client-auth.ts

@@ -0,0 +1,182 @@
+import { Keyset } from '@atproto/jwk'
+import {
+  CLIENT_ASSERTION_TYPE_JWT_BEARER,
+  OAuthAuthorizationServerMetadata,
+  OAuthClientCredentials,
+} from '@atproto/oauth-types'
+import { FALLBACK_ALG } from './constants.js'
+import { AuthMethodUnsatisfiableError } from './errors/auth-method-unsatisfiable-error.js'
+import { Runtime } from './runtime.js'
+import { ClientMetadata } from './types.js'
+import { Awaitable } from './util.js'
+
+export type ClientAuthMethod =
+  | { method: 'none' }
+  | { method: 'private_key_jwt'; kid: string }
+
+export function negotiateClientAuthMethod(
+  serverMetadata: OAuthAuthorizationServerMetadata,
+  clientMetadata: ClientMetadata,
+  keyset?: Keyset,
+): ClientAuthMethod {
+  const method = clientMetadata.token_endpoint_auth_method
+
+  // @NOTE ATproto spec requires that AS support both "none" and
+  // "private_key_jwt", and that clients use one of the other. The following
+  // check ensures that the AS is indeed compliant with this client's
+  // configuration.
+  const methods = supportedMethods(serverMetadata)
+  if (!methods.includes(method)) {
+    throw new Error(
+      `The server does not support "${method}" authentication. Supported methods are: ${methods.join(
+        ', ',
+      )}.`,
+    )
+  }
+
+  if (method === 'private_key_jwt') {
+    // Invalid client configuration. This should not happen as
+    // "validateClientMetadata" already check this.
+    if (!keyset) throw new Error('A keyset is required for private_key_jwt')
+
+    const alg = supportedAlgs(serverMetadata)
+
+    // @NOTE we can't use `keyset.findPrivateKey` here because we can't enforce
+    // that the returned key contains a "kid". The following implementation is
+    // more robust against keysets containing keys without a "kid" property.
+    for (const key of keyset.list({ use: 'sig', alg })) {
+      // Return the first key from the key set that matches the server's
+      // supported algorithms.
+      if (key.isPrivate && key.kid) {
+        return { method: 'private_key_jwt', kid: key.kid }
+      }
+    }
+
+    throw new Error(
+      alg.includes(FALLBACK_ALG)
+        ? `Client authentication method "${method}" requires at least one "${FALLBACK_ALG}" signing key with a "kid" property`
+        : // AS is not compliant with the ATproto OAuth spec.
+          `Authorization server requires "${method}" authentication method, but does not support "${FALLBACK_ALG}" algorithm.`,
+    )
+  }
+
+  if (method === 'none') {
+    return { method: 'none' }
+  }
+
+  throw new Error(
+    `The ATProto OAuth spec requires that client use either "none" or "private_key_jwt" authentication method.` +
+      (method === 'client_secret_basic'
+        ? ' You might want to explicitly set "token_endpoint_auth_method" to one of those values in the client metadata document.'
+        : ` You set "${method}" which is not allowed.`),
+  )
+}
+
+export type ClientCredentialsFactory = () => Awaitable<{
+  headers?: Record<string, string>
+  payload?: OAuthClientCredentials
+}>
+
+/**
+ * @throws {AuthMethodUnsatisfiableError} if the authentication method is no
+ * long usable (either because the AS changed, of because the key is no longer
+ * available in the keyset).
+ */
+export function createClientCredentialsFactory(
+  authMethod: ClientAuthMethod,
+  serverMetadata: OAuthAuthorizationServerMetadata,
+  clientMetadata: ClientMetadata,
+  runtime: Runtime,
+  keyset?: Keyset,
+): ClientCredentialsFactory {
+  // Ensure the AS still supports the auth method.
+  if (!supportedMethods(serverMetadata).includes(authMethod.method)) {
+    throw new AuthMethodUnsatisfiableError(
+      `Client authentication method "${authMethod.method}" no longer supported`,
+    )
+  }
+
+  if (authMethod.method === 'none') {
+    return () => ({
+      payload: {
+        client_id: clientMetadata.client_id,
+      },
+    })
+  }
+
+  if (authMethod.method === 'private_key_jwt') {
+    try {
+      // The client used to be a confidential client but no longer has a keyset.
+      if (!keyset) throw new Error('A keyset is required for private_key_jwt')
+
+      // @NOTE throws if no matching key can be found
+      const [key, alg] = keyset.findPrivateKey({
+        use: 'sig',
+        kid: authMethod.kid,
+        alg: supportedAlgs(serverMetadata),
+      })
+
+      // https://www.rfc-editor.org/rfc/rfc7523.html#section-3
+      return async () => ({
+        payload: {
+          client_id: clientMetadata.client_id,
+          client_assertion_type: CLIENT_ASSERTION_TYPE_JWT_BEARER,
+          client_assertion: await key.createJwt(
+            { alg },
+            {
+              // > The JWT MUST contain an "iss" (issuer) claim that contains a
+              // > unique identifier for the entity that issued the JWT.
+              iss: clientMetadata.client_id,
+              // > For client authentication, the subject MUST be the
+              // > "client_id" of the OAuth client.
+              sub: clientMetadata.client_id,
+              // > The JWT MUST contain an "aud" (audience) claim containing a value
+              // > that identifies the authorization server as an intended audience.
+              // > The token endpoint URL of the authorization server MAY be used as a
+              // > value for an "aud" element to identify the authorization server as an
+              // > intended audience of the JWT.
+              aud: serverMetadata.issuer,
+              // > The JWT MAY contain a "jti" (JWT ID) claim that provides a
+              // > unique identifier for the token.
+              jti: await runtime.generateNonce(),
+              // > The JWT MAY contain an "iat" (issued at) claim that
+              // > identifies the time at which the JWT was issued.
+              iat: Math.floor(Date.now() / 1000),
+              // > The JWT MUST contain an "exp" (expiration time) claim that
+              // > limits the time window during which the JWT can be used.
+              exp: Math.floor(Date.now() / 1000) + 60, // 1 minute
+            },
+          ),
+        },
+      })
+    } catch (cause) {
+      throw new AuthMethodUnsatisfiableError('Failed to load private key', {
+        cause,
+      })
+    }
+  }
+
+  throw new AuthMethodUnsatisfiableError(
+    // @ts-expect-error
+    `Unsupported auth method ${authMethod.method}`,
+  )
+}
+
+function supportedMethods(serverMetadata: OAuthAuthorizationServerMetadata) {
+  return serverMetadata['token_endpoint_auth_methods_supported']
+}
+
+function supportedAlgs(serverMetadata: OAuthAuthorizationServerMetadata) {
+  return (
+    serverMetadata['token_endpoint_auth_signing_alg_values_supported'] ?? [
+      // @NOTE If not specified, assume that the server supports the ES256
+      // algorithm, as prescribed by the spec:
+      //
+      // > Clients and Authorization Servers currently must support the ES256
+      // > cryptographic system [for client authentication].
+      //
+      // https://atproto.com/specs/oauth#confidential-client-authentication
+      FALLBACK_ALG,
+    ]
+  )
+}

package/src/oauth-client.ts

@@ -26,12 +26,14 @@ import {
 import { IdentityResolver } from '@atproto-labs/identity-resolver'
 import { SimpleStoreMemory } from '@atproto-labs/simple-store-memory'
 import { FALLBACK_ALG } from './constants.js'
+import { AuthMethodUnsatisfiableError } from './errors/auth-method-unsatisfiable-error.js'
 import { TokenRevokedError } from './errors/token-revoked-error.js'
 import {
   AuthorizationServerMetadataCache,
   OAuthAuthorizationServerMetadataResolver,
 } from './oauth-authorization-server-metadata-resolver.js'
 import { OAuthCallbackError } from './oauth-callback-error.js'
+import { negotiateClientAuthMethod } from './oauth-client-auth.js'
 import {
   OAuthProtectedResourceMetadataResolver,
   ProtectedResourceMetadataCache,
@@ -290,11 +292,17 @@ export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
       metadata.dpop_signing_alg_values_supported || [FALLBACK_ALG],
     )
 
+    const authMethod = negotiateClientAuthMethod(
+      metadata,
+      this.clientMetadata,
+      this.keyset,
+    )
     const state = await this.runtime.generateNonce()
 
     await this.stateStore.set(state, {
       iss: metadata.issuer,
       dpopKey,
+      authMethod,
       verifier: pkce.verifier,
       appState: options?.state,
     })
@@ -327,7 +335,11 @@ export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
     }
 
     if (metadata.pushed_authorization_request_endpoint) {
-      const server = await this.serverFactory.fromMetadata(metadata, dpopKey)
+      const server = await this.serverFactory.fromMetadata(
+        metadata,
+        authMethod,
+        dpopKey,
+      )
       const parResponse = await server.request(
         'pushed_authorization_request',
         parameters,
@@ -423,6 +435,8 @@ export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
 
       const server = await this.serverFactory.fromIssuer(
         stateData.iss,
+        // Using the literal 'legacy' if the authMethod is not defined (because stateData was created through an old version of this lib)
+        stateData.authMethod ?? 'legacy',
         stateData.dpopKey,
       )
 
@@ -455,6 +469,7 @@ export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
       try {
         await this.sessionGetter.setStored(tokenSet.sub, {
           dpopKey: stateData.dpopKey,
+          authMethod: server.authMethod,
           tokenSet,
         })
 
@@ -486,24 +501,45 @@ export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
     // sub arg is lightly typed for convenience of library user
     assertAtprotoDid(sub)
 
-    const { dpopKey, tokenSet } = await this.sessionGetter.get(sub, {
+    const {
+      dpopKey,
+      authMethod = 'legacy',
+      tokenSet,
+    } = await this.sessionGetter.get(sub, {
       noCache: refresh === true,
       allowStale: refresh === false,
     })
 
-    const server = await this.serverFactory.fromIssuer(tokenSet.iss, dpopKey, {
-      noCache: refresh === true,
-      allowStale: refresh === false,
-    })
+    try {
+      const server = await this.serverFactory.fromIssuer(
+        tokenSet.iss,
+        authMethod,
+        dpopKey,
+        {
+          noCache: refresh === true,
+          allowStale: refresh === false,
+        },
+      )
+
+      return this.createSession(server, sub)
+    } catch (err) {
+      if (err instanceof AuthMethodUnsatisfiableError) {
+        await this.sessionGetter.delStored(sub, err)
+      }
 
-    return this.createSession(server, sub)
+      throw err
+    }
   }
 
   async revoke(sub: string) {
     // sub arg is lightly typed for convenience of library user
     assertAtprotoDid(sub)
 
-    const { dpopKey, tokenSet } = await this.sessionGetter.get(sub, {
+    const {
+      dpopKey,
+      authMethod = 'legacy',
+      tokenSet,
+    } = await this.sessionGetter.get(sub, {
       allowStale: true,
     })
 
@@ -511,7 +547,11 @@ export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
     // the tokens to be deleted even if it was not possible to fetch the issuer
     // data.
     try {
-      const server = await this.serverFactory.fromIssuer(tokenSet.iss, dpopKey)
+      const server = await this.serverFactory.fromIssuer(
+        tokenSet.iss,
+        authMethod,
+        dpopKey,
+      )
       await server.revoke(tokenSet.access_token)
     } finally {
       await this.sessionGetter.delStored(sub, new TokenRevokedError(sub))

package/src/oauth-server-agent.ts

@@ -1,10 +1,8 @@
 import { AtprotoDid } from '@atproto/did'
 import { Key, Keyset } from '@atproto/jwk'
 import {
-  CLIENT_ASSERTION_TYPE_JWT_BEARER,
   OAuthAuthorizationRequestPar,
   OAuthAuthorizationServerMetadata,
-  OAuthClientCredentials,
   OAuthEndpointName,
   OAuthParResponse,
   OAuthTokenRequest,
@@ -17,9 +15,13 @@ import {
   AtprotoTokenResponse,
   atprotoTokenResponseSchema,
 } from './atproto-token-response.js'
-import { FALLBACK_ALG } from './constants.js'
 import { TokenRefreshError } from './errors/token-refresh-error.js'
 import { dpopFetchWrapper } from './fetch-dpop.js'
+import {
+  ClientAuthMethod,
+  ClientCredentialsFactory,
+  createClientCredentialsFactory,
+} from './oauth-client-auth.js'
 import { OAuthResolver } from './oauth-resolver.js'
 import { OAuthResponseError } from './oauth-response-error.js'
 import { Runtime } from './runtime.js'
@@ -43,8 +45,13 @@ export type DpopNonceCache = SimpleStore<string, string>
 
 export class OAuthServerAgent {
   protected dpopFetch: Fetch<unknown>
+  protected clientCredentialsFactory: ClientCredentialsFactory
 
+  /**
+   * @throws see {@link createClientCredentialsFactory}
+   */
   constructor(
+    readonly authMethod: ClientAuthMethod,
     readonly dpopKey: Key,
     readonly serverMetadata: OAuthAuthorizationServerMetadata,
     readonly clientMetadata: ClientMetadata,
@@ -54,6 +61,14 @@ export class OAuthServerAgent {
     readonly keyset?: Keyset,
     fetch?: Fetch,
   ) {
+    this.clientCredentialsFactory = createClientCredentialsFactory(
+      authMethod,
+      serverMetadata,
+      clientMetadata,
+      runtime,
+      keyset,
+    )
+
     this.dpopFetch = dpopFetchWrapper<void>({
       fetch: bindFetch(fetch),
       key: dpopKey,
@@ -204,7 +219,7 @@ export class OAuthServerAgent {
     const url = this.serverMetadata[`${endpoint}_endpoint`]
     if (!url) throw new Error(`No ${endpoint} endpoint available`)
 
-    const auth = await this.buildClientAuth(endpoint)
+    const auth = await this.clientCredentialsFactory()
 
     // https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-3.2.2
     // https://datatracker.ietf.org/doc/html/rfc7009#section-2.1
@@ -232,73 +247,6 @@ export class OAuthServerAgent {
       throw new OAuthResponseError(response, json)
     }
   }
-
-  async buildClientAuth(endpoint: OAuthEndpointName): Promise<{
-    headers?: Record<string, string>
-    payload: OAuthClientCredentials
-  }> {
-    const methodSupported =
-      this.serverMetadata[`token_endpoint_auth_methods_supported`]
-
-    const method = this.clientMetadata[`token_endpoint_auth_method`]
-
-    if (
-      method === 'private_key_jwt' ||
-      (this.keyset &&
-        !method &&
-        (methodSupported?.includes('private_key_jwt') ?? false))
-    ) {
-      if (!this.keyset) throw new Error('No keyset available')
-
-      try {
-        const alg =
-          this.serverMetadata[
-            `token_endpoint_auth_signing_alg_values_supported`
-          ] ?? FALLBACK_ALG
-
-        // If jwks is defined, make sure to only sign using a key that exists in
-        // the jwks. If jwks_uri is defined, we can't be sure that the key we're
-        // looking for is in there so we will just assume it is.
-        const kid = this.clientMetadata.jwks?.keys
-          .map(({ kid }) => kid)
-          .filter((v): v is string => typeof v === 'string')
-
-        return {
-          payload: {
-            client_id: this.clientMetadata.client_id,
-            client_assertion_type: CLIENT_ASSERTION_TYPE_JWT_BEARER,
-            client_assertion: await this.keyset.createJwt(
-              { alg, kid },
-              {
-                iss: this.clientMetadata.client_id,
-                sub: this.clientMetadata.client_id,
-                aud: this.serverMetadata.issuer,
-                jti: await this.runtime.generateNonce(),
-                iat: Math.floor(Date.now() / 1000),
-              },
-            ),
-          },
-        }
-      } catch (err) {
-        if (method === 'private_key_jwt') throw err
-
-        // Else try next method
-      }
-    }
-
-    if (
-      method === 'none' ||
-      (!method && (methodSupported?.includes('none') ?? true))
-    ) {
-      return {
-        payload: {
-          client_id: this.clientMetadata.client_id,
-        },
-      }
-    }
-
-    throw new Error(`Unsupported ${endpoint} authentication method`)
-  }
 }
 
 function wwwFormUrlEncode(payload: Record<string, undefined | unknown>) {

package/src/oauth-server-factory.ts

@@ -2,6 +2,10 @@ import { Key, Keyset } from '@atproto/jwk'
 import { OAuthAuthorizationServerMetadata } from '@atproto/oauth-types'
 import { Fetch } from '@atproto-labs/fetch'
 import { GetCachedOptions } from './oauth-authorization-server-metadata-resolver.js'
+import {
+  ClientAuthMethod,
+  negotiateClientAuthMethod,
+} from './oauth-client-auth.js'
 import { OAuthResolver } from './oauth-resolver.js'
 import { DpopNonceCache, OAuthServerAgent } from './oauth-server-agent.js'
 import { Runtime } from './runtime.js'
@@ -17,19 +21,50 @@ export class OAuthServerFactory {
     readonly dpopNonceCache: DpopNonceCache,
   ) {}
 
-  async fromIssuer(issuer: string, dpopKey: Key, options?: GetCachedOptions) {
+  /**
+   * @param authMethod `undefined` means that we are restoring a session that
+   * was created before we started storing the `authMethod` in the session. In
+   * that case, we will use the first key from the keyset.
+   *
+   * Support for this might be removed in the future.
+   *
+   * @throws see {@link OAuthServerFactory.fromMetadata}
+   */
+  async fromIssuer(
+    issuer: string,
+    authMethod: 'legacy' | ClientAuthMethod,
+    dpopKey: Key,
+    options?: GetCachedOptions,
+  ) {
     const serverMetadata = await this.resolver.getAuthorizationServerMetadata(
       issuer,
       options,
     )
-    return this.fromMetadata(serverMetadata, dpopKey)
+
+    if (authMethod === 'legacy') {
+      // @NOTE Because we were previously not storing the authMethod in the
+      // session data, we provide a backwards compatible implementation by
+      // computing it here.
+      authMethod = negotiateClientAuthMethod(
+        serverMetadata,
+        this.clientMetadata,
+        this.keyset,
+      )
+    }
+
+    return this.fromMetadata(serverMetadata, authMethod, dpopKey)
   }
 
+  /**
+   * @throws see {@link OAuthServerAgent}
+   */
   async fromMetadata(
     serverMetadata: OAuthAuthorizationServerMetadata,
+    authMethod: ClientAuthMethod,
     dpopKey: Key,
   ) {
     return new OAuthServerAgent(
+      authMethod,
       dpopKey,
       serverMetadata,
       this.clientMetadata,

package/src/session-getter.ts

@@ -5,9 +5,11 @@ import {
   GetCachedOptions,
   SimpleStore,
 } from '@atproto-labs/simple-store'
+import { AuthMethodUnsatisfiableError } from './errors/auth-method-unsatisfiable-error.js'
 import { TokenInvalidError } from './errors/token-invalid-error.js'
 import { TokenRefreshError } from './errors/token-refresh-error.js'
 import { TokenRevokedError } from './errors/token-revoked-error.js'
+import { ClientAuthMethod } from './oauth-client-auth.js'
 import { OAuthResponseError } from './oauth-response-error.js'
 import { TokenSet } from './oauth-server-agent.js'
 import { OAuthServerFactory } from './oauth-server-factory.js'
@@ -16,6 +18,10 @@ import { CustomEventTarget, combineSignals, timeoutSignal } from './util.js'
 
 export type Session = {
   dpopKey: Key
+  /**
+   * Previous implementation of this lib did not define an `authMethod`
+   */
+  authMethod?: ClientAuthMethod
   tokenSet: TokenSet
 }
 
@@ -51,7 +57,7 @@ export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
     private readonly runtime: Runtime,
   ) {
     super(
-      async (sub, options, storedSession): Promise<Session> => {
+      async (sub, options, storedSession) => {
         // There needs to be a previous session to be able to refresh. If
         // storedSession is undefined, it means that the store does not contain
         // a session for the given sub.
@@ -73,7 +79,7 @@ export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
         // concurrent access (which, normally, should not happen if a proper
         // runtime lock was provided).
 
-        const { dpopKey, tokenSet } = storedSession
+        const { dpopKey, authMethod = 'legacy', tokenSet } = storedSession
 
         if (sub !== tokenSet.sub) {
           // Fool-proofing (e.g. against invalid session storage)
@@ -94,7 +100,11 @@ export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
         // always possible. If no lock implementation is provided, we will use
         // the store to check if a concurrent refresh occurred.
 
-        const server = await serverFactory.fromIssuer(tokenSet.iss, dpopKey)
+        const server = await serverFactory.fromIssuer(
+          tokenSet.iss,
+          authMethod,
+          dpopKey,
+        )
 
         // Because refresh tokens can only be used once, we must not use the
         // "signal" to abort the refresh, or throw any abort error beyond this
@@ -111,7 +121,11 @@ export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
             throw new TokenRefreshError(sub, 'Token set sub mismatch')
           }
 
-          return { dpopKey, tokenSet: newTokenSet }
+          return {
+            dpopKey,
+            tokenSet: newTokenSet,
+            authMethod: server.authMethod,
+          }
         } catch (cause) {
           // If the refresh token is invalid, let's try to recover from
           // concurrency issues, or make sure the session is deleted by throwing
@@ -173,17 +187,36 @@ export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
                 30e3 * Math.random()
           )
         },
-        onStoreError: async (err, sub, { tokenSet, dpopKey }) => {
-          // If the token data cannot be stored, let's revoke it
-          const server = await serverFactory.fromIssuer(tokenSet.iss, dpopKey)
-          await server.revoke(tokenSet.refresh_token ?? tokenSet.access_token)
+        onStoreError: async (
+          err,
+          sub,
+          { tokenSet, dpopKey, authMethod = 'legacy' as const },
+        ) => {
+          if (!(err instanceof AuthMethodUnsatisfiableError)) {
+            // If the error was an AuthMethodUnsatisfiableError, there is no
+            // point in trying to call `fromIssuer`.
+            try {
+              // If the token data cannot be stored, let's revoke it
+              const server = await serverFactory.fromIssuer(
+                tokenSet.iss,
+                authMethod,
+                dpopKey,
+              )
+              await server.revoke(
+                tokenSet.refresh_token ?? tokenSet.access_token,
+              )
+            } catch {
+              // Let the original error propagate
+            }
+          }
+
           throw err
         },
         deleteOnError: async (err) =>
-          // Optimization: More likely to happen first
           err instanceof TokenRefreshError ||
           err instanceof TokenRevokedError ||
-          err instanceof TokenInvalidError,
+          err instanceof TokenInvalidError ||
+          err instanceof AuthMethodUnsatisfiableError,
       },
     )
   }

package/src/state-store.ts

@@ -1,9 +1,12 @@
 import { Key } from '@atproto/jwk'
 import { SimpleStore } from '@atproto-labs/simple-store'
+import { ClientAuthMethod } from './oauth-client-auth.js'
 
 export type InternalStateData = {
   iss: string
   dpopKey: Key
+  /** @note optional for legacy reasons */
+  authMethod?: ClientAuthMethod
   verifier?: string
   appState?: string
 }