@atproto/oauth-client 0.5.13 → 0.6.0

package/src/oauth-client.ts

@@ -42,36 +42,38 @@ import { OAuthSession } from './oauth-session.js'
 import { RuntimeImplementation } from './runtime-implementation.js'
 import { Runtime } from './runtime.js'
 import {
-  SessionEventMap,
   SessionGetter,
+  SessionHooks,
   SessionStore,
+  isExpectedSessionError,
 } from './session-getter.js'
 import { InternalStateData, StateStore } from './state-store.js'
 import { AuthorizeOptions, CallbackOptions, ClientMetadata } from './types.js'
-import { CustomEventTarget } from './util.js'
 import { validateClientMetadata } from './validate-client-metadata.js'
 
 // Export all types needed to construct OAuthClientOptions
-export {
-  type AuthorizationServerMetadataCache,
-  type DidCache,
-  type DpopNonceCache,
-  type Fetch,
-  type HandleCache,
-  type HandleResolver,
-  type InternalStateData,
-  Key,
-  Keyset,
-  type OAuthClientMetadata,
-  type OAuthClientMetadataInput,
-  type OAuthResponseMode,
-  type ProtectedResourceMetadataCache,
-  type RuntimeImplementation,
-  type SessionStore,
-  type StateStore,
+export type {
+  AuthorizationServerMetadataCache,
+  CreateIdentityResolverOptions,
+  DidCache,
+  DpopNonceCache,
+  Fetch,
+  HandleCache,
+  HandleResolver,
+  InternalStateData,
+  OAuthClientMetadata,
+  OAuthClientMetadataInput,
+  OAuthResponseMode,
+  ProtectedResourceMetadataCache,
+  RuntimeImplementation,
+  SessionHooks,
+  SessionStore,
+  StateStore,
 }
 
-export type OAuthClientOptions = CreateIdentityResolverOptions & {
+export { Key, Keyset }
+
+export type OAuthClientOptions = {
   // Config
   responseMode: OAuthResponseMode
   clientMetadata: Readonly<OAuthClientMetadataInput>
@@ -102,9 +104,8 @@ export type OAuthClientOptions = CreateIdentityResolverOptions & {
   // Services
   runtimeImplementation: RuntimeImplementation
   fetch?: Fetch
-}
-
-export type OAuthClientEventMap = SessionEventMap
+} & CreateIdentityResolverOptions &
+  SessionHooks
 
 export type OAuthClientFetchMetadataOptions = {
   clientId: OAuthClientIdDiscoverable
@@ -112,7 +113,7 @@ export type OAuthClientFetchMetadataOptions = {
   signal?: AbortSignal
 }
 
-export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
+export class OAuthClient {
   static async fetchMetadata({
     clientId,
     fetch = globalThis.fetch,
@@ -181,8 +182,6 @@ export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
       keyset,
     } = options
 
-    super()
-
     this.keyset = keyset
       ? keyset instanceof Keyset
         ? keyset
@@ -215,21 +214,13 @@ export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
       dpopNonceCache,
     )
 
+    this.stateStore = stateStore
     this.sessionGetter = new SessionGetter(
       sessionStore,
       this.serverFactory,
       this.runtime,
+      options,
     )
-    this.stateStore = stateStore
-
-    // Proxy sessionGetter events
-    for (const type of ['deleted', 'updated'] as const) {
-      this.sessionGetter.addEventListener(type, (event) => {
-        if (!this.dispatchCustomEvent(type, event.detail)) {
-          event.preventDefault()
-        }
-      })
-    }
   }
 
   // Exposed as public API for convenience
@@ -411,8 +402,7 @@ 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.authMethod,
         stateData.dpopKey,
       )
 
@@ -446,6 +436,15 @@ export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
         stateData.verifier,
         options?.redirect_uri ?? server.clientMetadata.redirect_uris[0],
       )
+
+      // We revoke any existing session first to avoid leaving orphaned sessions
+      // on the AS.
+      try {
+        await this.revoke(tokenSet.sub)
+      } catch {
+        // No existing session, or failed to get it. This is fine.
+      }
+
       try {
         await this.sessionGetter.setStored(tokenSet.sub, {
           dpopKey: stateData.dpopKey,
@@ -472,7 +471,7 @@ export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
    * Load a stored session. This will refresh the token only if needed (about to
    * expire) by default.
    *
-   * @param refresh See {@link SessionGetter.getSession}
+   * @see {@link SessionGetter.restore}
    */
   async restore(
     sub: string,
@@ -481,11 +480,8 @@ export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
     // sub arg is lightly typed for convenience of library user
     assertAtprotoDid(sub)
 
-    const {
-      dpopKey,
-      authMethod = 'legacy',
-      tokenSet,
-    } = await this.sessionGetter.getSession(sub, refresh)
+    const { dpopKey, authMethod, tokenSet } =
+      await this.sessionGetter.getSession(sub, refresh)
 
     try {
       const server = await this.serverFactory.fromIssuer(
@@ -512,14 +508,15 @@ export class OAuthClient extends CustomEventTarget<OAuthClientEventMap> {
     // sub arg is lightly typed for convenience of library user
     assertAtprotoDid(sub)
 
-    const {
-      dpopKey,
-      authMethod = 'legacy',
-      tokenSet,
-    } = await this.sessionGetter.get(sub, {
-      allowStale: true,
+    const res = await this.sessionGetter.getSession(sub, false).catch((err) => {
+      if (isExpectedSessionError(err)) return null
+      throw err
     })
 
+    if (!res) return
+
+    const { dpopKey, authMethod, tokenSet } = res
+
     // NOT using `;(await this.restore(sub, false)).signOut()` because we want
     // the tokens to be deleted even if it was not possible to fetch the issuer
     // data.

package/src/oauth-server-factory.ts

@@ -2,10 +2,7 @@ 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 { ClientAuthMethod } from './oauth-client-auth.js'
 import { OAuthResolver } from './oauth-resolver.js'
 import { DpopNonceCache, OAuthServerAgent } from './oauth-server-agent.js'
 import { Runtime } from './runtime.js'
@@ -32,7 +29,7 @@ export class OAuthServerFactory {
    */
   async fromIssuer(
     issuer: string,
-    authMethod: 'legacy' | ClientAuthMethod,
+    authMethod: ClientAuthMethod,
     dpopKey: Key,
     options?: GetCachedOptions,
   ) {
@@ -41,17 +38,6 @@ export class OAuthServerFactory {
       options,
     )
 
-    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)
   }
 

package/src/oauth-session.ts

@@ -58,10 +58,7 @@ export class OAuthSession {
    * if, and only if, they are (about to be) expired. Defaults to `undefined`.
    */
   protected async getTokenSet(refresh: boolean | 'auto'): Promise<TokenSet> {
-    const { tokenSet } = await this.sessionGetter.get(this.sub, {
-      noCache: refresh === true,
-      allowStale: refresh === false,
-    })
+    const { tokenSet } = await this.sessionGetter.getSession(this.sub, refresh)
 
     return tokenSet
   }

package/src/session-getter.ts

@@ -3,6 +3,7 @@ import { Key } from '@atproto/jwk'
 import {
   CachedGetter,
   GetCachedOptions,
+  GetOptions,
   SimpleStore,
 } from '@atproto-labs/simple-store'
 import { AuthMethodUnsatisfiableError } from './errors/auth-method-unsatisfiable-error.js'
@@ -14,32 +15,35 @@ import { OAuthResponseError } from './oauth-response-error.js'
 import { TokenSet } from './oauth-server-agent.js'
 import { OAuthServerFactory } from './oauth-server-factory.js'
 import { Runtime } from './runtime.js'
-import { CustomEventTarget, combineSignals } from './util.js'
+import { combineSignals } from './util.js'
 
 export type Session = {
   dpopKey: Key
-  /**
-   * Previous implementation of this lib did not define an `authMethod`
-   */
-  authMethod?: ClientAuthMethod
+  authMethod: ClientAuthMethod
   tokenSet: TokenSet
 }
 
 export type SessionStore = SimpleStore<string, Session>
 
-export type SessionEventMap = {
-  updated: {
-    sub: string
-  } & Session
-  deleted: {
-    sub: string
-    cause: TokenRefreshError | TokenRevokedError | TokenInvalidError | unknown
-  }
+export type SessionHooks = {
+  onUpdate?: (sub: AtprotoDid, session: Session) => void
+  onDelete?: (
+    sub: AtprotoDid,
+    cause: TokenRefreshError | TokenRevokedError | TokenInvalidError | unknown,
+  ) => void
 }
 
-export type SessionEventListener<
-  T extends keyof SessionEventMap = keyof SessionEventMap,
-> = (event: CustomEvent<SessionEventMap[T]>) => void
+export function isExpectedSessionError(err: unknown) {
+  return (
+    err instanceof TokenRefreshError ||
+    err instanceof TokenRevokedError ||
+    err instanceof TokenInvalidError ||
+    err instanceof AuthMethodUnsatisfiableError ||
+    // The stored session is invalid (e.g. missing properties) and cannot
+    // be used properly
+    err instanceof TypeError
+  )
+}
 
 /**
  * There are several advantages to wrapping the sessionStore in a (single)
@@ -49,15 +53,14 @@ export type SessionEventListener<
  * localStorage/indexedDB, will sync across multiple tabs (for a given sub).
  */
 export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
-  private readonly eventTarget = new CustomEventTarget<SessionEventMap>()
-
   constructor(
     sessionStore: SessionStore,
     serverFactory: OAuthServerFactory,
     private readonly runtime: Runtime,
+    private readonly hooks: SessionHooks = {},
   ) {
     super(
-      async (sub, options, storedSession) => {
+      async (sub, { signal }, 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.
@@ -69,17 +72,15 @@ export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
           // make sure an event is dispatched here if this occurs.
           const msg = 'The session was deleted by another process'
           const cause = new TokenRefreshError(sub, msg)
-          this.dispatchEvent('deleted', { sub, cause })
+          await hooks.onDelete?.call(null, sub, cause)
           throw cause
         }
 
-        // From this point forward, throwing a TokenRefreshError will result in
-        // this.delStored() being called, resulting in an event being
-        // dispatched, even if the session was removed from the store through a
-        // concurrent access (which, normally, should not happen if a proper
-        // runtime lock was provided).
+        // @NOTE Throwing a TokenRefreshError (or any other error class defined
+        // in the deleteOnError options) will result in this.delStored() being
+        // called.
 
-        const { dpopKey, authMethod = 'legacy', tokenSet } = storedSession
+        const { dpopKey, authMethod, tokenSet } = storedSession
 
         if (sub !== tokenSet.sub) {
           // Fool-proofing (e.g. against invalid session storage)
@@ -90,16 +91,6 @@ export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
           throw new TokenRefreshError(sub, 'No refresh token available')
         }
 
-        // Since refresh tokens can only be used once, we might run into
-        // concurrency issues if multiple instances (e.g. browser tabs) are
-        // trying to refresh the same token simultaneously. The chances of this
-        // happening when multiple instances are started simultaneously is
-        // reduced by randomizing the expiry time (see isStale() below). The
-        // best solution is to use a mutex/lock to ensure that only one instance
-        // is refreshing the token at a time (runtime.usingLock) but that is not
-        // 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,
           authMethod,
@@ -111,7 +102,7 @@ export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
         // point. Any thrown error beyond this point will prevent the
         // TokenGetter from obtaining, and storing, the new token set,
         // effectively rendering the currently saved session unusable.
-        options?.signal?.throwIfAborted()
+        signal?.throwIfAborted()
 
         try {
           const newTokenSet = await server.refresh(tokenSet)
@@ -127,9 +118,16 @@ export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
             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
-          // a TokenRefreshError.
+          // Since refresh tokens can only be used once, we might run into
+          // concurrency issues if multiple instances (e.g. browser tabs) are
+          // trying to refresh the same token simultaneously. The chances of
+          // this happening when multiple instances are started simultaneously
+          // is reduced by randomizing the expiry time (see isStale() below).
+          // The best solution is to use a mutex/lock to ensure that only one
+          // instance is refreshing the token at a time (runtime.usingLock) but
+          // that is not always possible. Let's try to recover from concurrency
+          // issues, or force the session to be deleted by throwing a
+          // TokenRefreshError.
           if (
             cause instanceof OAuthResponseError &&
             cause.status === 400 &&
@@ -187,91 +185,63 @@ export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
                 30e3 * Math.random()
           )
         },
-        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
-            }
+        onStoreError: async (err, sub, { tokenSet, dpopKey, authMethod }) => {
+          // If the token data cannot be stored, let's revoke it
+          try {
+            const server = await serverFactory.fromIssuer(
+              tokenSet.iss,
+              authMethod,
+              dpopKey,
+            )
+            await server.revoke(tokenSet.refresh_token ?? tokenSet.access_token)
+          } catch {
+            // At least we tried...
+          }
+
+          // Attempt to delete the session from the store. Note that this might
+          // fail if the store is not available, which is fine.
+          try {
+            await this.delStored(sub, err)
+          } catch {
+            // Ignore (better to propagate the original storage error)
           }
 
           throw err
         },
-        deleteOnError: async (err) =>
-          err instanceof TokenRefreshError ||
-          err instanceof TokenRevokedError ||
-          err instanceof TokenInvalidError ||
-          err instanceof AuthMethodUnsatisfiableError,
+        deleteOnError: isExpectedSessionError,
       },
     )
   }
 
-  addEventListener<T extends keyof SessionEventMap>(
-    type: T,
-    callback: SessionEventListener<T>,
-    options?: AddEventListenerOptions | boolean,
-  ) {
-    this.eventTarget.addEventListener(type, callback, options)
-  }
-
-  removeEventListener<T extends keyof SessionEventMap>(
-    type: T,
-    callback: SessionEventListener<T>,
-    options?: EventListenerOptions | boolean,
-  ) {
-    this.eventTarget.removeEventListener(type, callback, options)
-  }
-
-  dispatchEvent<T extends keyof SessionEventMap>(
-    type: T,
-    detail: SessionEventMap[T],
-  ): boolean {
-    return this.eventTarget.dispatchCustomEvent(type, detail)
+  override async getStored(
+    sub: AtprotoDid,
+    options?: GetOptions,
+  ): Promise<Session | undefined> {
+    return super.getStored(sub, options)
   }
 
-  async setStored(sub: string, session: Session) {
+  override async setStored(sub: AtprotoDid, session: Session) {
     // Prevent tampering with the stored value
     if (sub !== session.tokenSet.sub) {
       throw new TypeError('Token set does not match the expected sub')
     }
     await super.setStored(sub, session)
-    this.dispatchEvent('updated', { sub, ...session })
+    await this.hooks.onUpdate?.call(null, sub, session)
   }
 
   override async delStored(sub: AtprotoDid, cause?: unknown): Promise<void> {
     await super.delStored(sub, cause)
-    this.dispatchEvent('deleted', { sub, cause })
+    await this.hooks.onDelete?.call(null, sub, cause)
   }
 
   /**
-   * @param refresh When `true`, the credentials will be refreshed even if they
-   * are not expired. When `false`, the credentials will not be refreshed even
-   * if they are expired. When `undefined`, the credentials will be refreshed
-   * if, and only if, they are (about to be) expired. Defaults to `undefined`.
+   * @deprecated Use {@link getSession} instead
+   * @internal (not really deprecated)
    */
-  async getSession(sub: AtprotoDid, refresh: boolean | 'auto' = 'auto') {
-    return this.get(sub, {
-      noCache: refresh === true,
-      allowStale: refresh === false,
-    })
-  }
-
-  async get(sub: AtprotoDid, options?: GetCachedOptions): Promise<Session> {
+  override async get(
+    sub: AtprotoDid,
+    options?: GetCachedOptions,
+  ): Promise<Session> {
     const session = await this.runtime.usingLock(
       `@atproto-oauth-client-${sub}`,
       async () => {
@@ -295,4 +265,17 @@ export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
 
     return session
   }
+
+  /**
+   * @param refresh When `true`, the credentials will be refreshed even if they
+   * are not expired. When `false`, the credentials will not be refreshed even
+   * if they are expired. When `undefined`, the credentials will be refreshed
+   * if, and only if, they are (about to be) expired. Defaults to `undefined`.
+   */
+  async getSession(sub: AtprotoDid, refresh: boolean | 'auto' = 'auto') {
+    return this.get(sub, {
+      noCache: refresh === true,
+      allowStale: refresh === false,
+    })
+  }
 }

package/src/state-store.ts

@@ -5,10 +5,20 @@ import { ClientAuthMethod } from './oauth-client-auth.js'
 export type InternalStateData = {
   iss: string
   dpopKey: Key
-  /** @note optional for legacy reasons */
-  authMethod?: ClientAuthMethod
-  verifier?: string
+  authMethod: ClientAuthMethod
+  verifier: string
   appState?: string
 }
 
+/**
+ * A store pending oauth authorization flows. The key is the "state" parameter
+ * used in the authorization request, and the value is an object containing the
+ * necessary information to complete the flow once the user is redirected back
+ * to the client.
+ *
+ * @note The data stored in this store is typically short-lived. It should be
+ * automatically cleared after a certain period of time (e.g. 1 hour) to prevent
+ * the store from growing indefinitely. It is up to the implementation to
+ * implement this cleanup mechanism.
+ */
 export type StateStore = SimpleStore<string, InternalStateData>

package/src/util.ts

@@ -7,73 +7,6 @@ export function contentMime(headers: Headers): string | undefined {
   return headers.get('content-type')?.split(';')[0]!.trim()
 }
 
-/**
- * Ponyfill for `CustomEvent` constructor.
- */
-export const CustomEvent: typeof globalThis.CustomEvent =
-  globalThis.CustomEvent ??
-  (() => {
-    class CustomEvent<T> extends Event {
-      #detail: T | null
-      constructor(type: string, options?: CustomEventInit<T>) {
-        if (!arguments.length) throw new TypeError('type argument is required')
-        super(type, options)
-        this.#detail = options?.detail ?? null
-      }
-      get detail() {
-        return this.#detail
-      }
-    }
-
-    Object.defineProperties(CustomEvent.prototype, {
-      [Symbol.toStringTag]: {
-        writable: false,
-        enumerable: false,
-        configurable: true,
-        value: 'CustomEvent',
-      },
-      detail: {
-        enumerable: true,
-      },
-    })
-
-    return CustomEvent
-  })()
-
-export class CustomEventTarget<EventDetailMap extends Record<string, unknown>> {
-  readonly eventTarget = new EventTarget()
-
-  addEventListener<T extends Extract<keyof EventDetailMap, string>>(
-    type: T,
-    callback: (event: CustomEvent<EventDetailMap[T]>) => void,
-    options?: AddEventListenerOptions | boolean,
-  ): void {
-    this.eventTarget.addEventListener(type, callback as EventListener, options)
-  }
-
-  removeEventListener<T extends Extract<keyof EventDetailMap, string>>(
-    type: T,
-    callback: (event: CustomEvent<EventDetailMap[T]>) => void,
-    options?: EventListenerOptions | boolean,
-  ): void {
-    this.eventTarget.removeEventListener(
-      type,
-      callback as EventListener,
-      options,
-    )
-  }
-
-  dispatchCustomEvent<T extends Extract<keyof EventDetailMap, string>>(
-    type: T,
-    detail: EventDetailMap[T],
-    init?: EventInit,
-  ): boolean {
-    return this.eventTarget.dispatchEvent(
-      new CustomEvent(type, { ...init, detail }),
-    )
-  }
-}
-
 export function combineSignals(
   signals: readonly (AbortSignal | undefined)[],
 ): AbortController & Disposable {