@atproto/oauth-client 0.1.0 → 0.1.1

package/src/session-getter.ts

@@ -4,12 +4,15 @@ import {
   SimpleStore,
 } from '@atproto-labs/simple-store'
 import { Key } from '@atproto/jwk'
+
+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 { OAuthResponseError } from './oauth-response-error.js'
 import { TokenSet } from './oauth-server-agent.js'
 import { OAuthServerFactory } from './oauth-server-factory.js'
-import { RefreshError } from './refresh-error.js'
 import { Runtime } from './runtime.js'
-import { withSignal } from './util.js'
+import { CustomEventTarget, timeoutSignal } from './util.js'
 
 export type Session = {
   dpopKey: Key
@@ -18,6 +21,20 @@ export type Session = {
 
 export type SessionStore = SimpleStore<string, Session>
 
+export type SessionEventMap = {
+  updated: {
+    sub: string
+  } & Session
+  deleted: {
+    sub: string
+    cause: TokenRefreshError | TokenRevokedError | TokenInvalidError | unknown
+  }
+}
+
+export type SessionEventListener<
+  T extends keyof SessionEventMap = keyof SessionEventMap,
+> = (event: CustomEvent<SessionEventMap[T]>) => void
+
 /**
  * There are several advantages to wrapping the sessionStore in a (single)
  * CachedGetter, the main of which is that the cached getter will ensure that at
@@ -26,33 +43,39 @@ export type SessionStore = SimpleStore<string, Session>
  * localStorage/indexedDB, will sync across multiple tabs (for a given sub).
  */
 export class SessionGetter extends CachedGetter<string, Session> {
+  private readonly eventTarget = new CustomEventTarget<SessionEventMap>()
+
   constructor(
     sessionStore: SessionStore,
     serverFactory: OAuthServerFactory,
     private readonly runtime: Runtime,
   ) {
     super(
-      async (sub, options, storedSession) => {
+      async (sub, options, storedSession): Promise<Session> => {
         // 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. Since this might have been caused by the
-        // value being cleared in another process (e.g. another tab), we will
-        // give a chance to the process running this code to detect that the
-        // session was revoked. This should allow processes not implementing a
-        // subscribe/notify between instances to still be "notified" that the
-        // session was revoked.
+        // a session for the given sub.
         if (storedSession === undefined) {
-          // Because the session is not in the store, the sessionStore.del
-          // function will not be called, even if the "deleteOnError" callback
-          // returns true when the error is an "OAuthRefreshError". Let's
-          // call it here manually.
-          await sessionStore.del(sub)
-          throw new RefreshError(sub, 'The session was revoked')
+          // Because the session is not in the store, this.delStored() method
+          // will not be called by the CachedGetter class (because there is
+          // nothing to delete). This would typically happen if there is no
+          // synchronization mechanism between instances of this class. Let's
+          // 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 })
+          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).
+
         if (sub !== storedSession.tokenSet.sub) {
           // Fool-proofing (e.g. against invalid session storage)
-          throw new RefreshError(sub, 'Stored session sub mismatch')
+          throw new TokenRefreshError(sub, 'Stored session sub mismatch')
         }
 
         // Since refresh tokens can only be used once, we might run into
@@ -70,61 +93,67 @@ export class SessionGetter extends CachedGetter<string, Session> {
         const { tokenSet, dpopKey } = storedSession
         const server = await serverFactory.fromIssuer(tokenSet.iss, dpopKey)
 
-        // We must not use the "signal" to cancel the refresh or its storage in
-        // case of successful refresh. If we obtain a new refresh token, we must
-        // ensure that is gets stored in the session store (by returning the new
-        // session object). Failing to do so would result in the new credentials
-        // being lost.
+        // 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
+        // point. Any thrown error beyond this point will prevent the
+        // SessionGetter from obtaining, and storing, the new token set,
+        // effectively rendering the currently saved session unusable.
         options?.signal?.throwIfAborted()
 
-        const newTokenSet = await server
-          .refresh(tokenSet)
-          .catch(async (cause) => {
-            if (
-              cause instanceof OAuthResponseError &&
-              cause.status === 400 &&
-              cause.error === 'invalid_grant'
-            ) {
-              // In case there is no lock implementation in the runtime, we will
-              // wait for a short time to give the other concurrent instances a
-              // chance to finish their refreshing of the token. If a concurrent
-              // refresh did occur, we will pretend that this one succeeded.
-              if (!runtime.hasLock) {
-                await new Promise((r) => setTimeout(r, 1000))
-
-                const stored = await this.getStored(sub)
-                if (stored === undefined) {
-                  // Using a distinct error message mainly for debugging
-                  // purposes
-                  const msg = 'The session was revoked by another process'
-                  throw new RefreshError(sub, msg, { cause })
-                } else if (
-                  stored.tokenSet.access_token !== tokenSet.access_token ||
-                  stored.tokenSet.refresh_token !== tokenSet.refresh_token
-                ) {
-                  // A concurrent refresh occurred. Pretend this one succeeded.
-                  return stored.tokenSet
-                } else {
-                  // There were no concurrent refresh. The token is (likely)
-                  // simply no longer valid.
-                }
+        try {
+          const newTokenSet = await server.refresh(tokenSet)
+
+          if (sub !== newTokenSet.sub) {
+            // The server returned another sub. Was the tokenSet manipulated?
+            throw new TokenRefreshError(sub, 'Token set sub mismatch')
+          }
+
+          return { dpopKey, tokenSet: newTokenSet }
+        } 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.
+          if (
+            cause instanceof OAuthResponseError &&
+            cause.status === 400 &&
+            cause.error === 'invalid_grant'
+          ) {
+            // In case there is no lock implementation in the runtime, we will
+            // wait for a short time to give the other concurrent instances a
+            // chance to finish their refreshing of the token. If a concurrent
+            // refresh did occur, we will pretend that this one succeeded.
+            if (!runtime.hasImplementationLock) {
+              await new Promise((r) => setTimeout(r, 1000))
+
+              const stored = await this.getStored(sub)
+              if (stored === undefined) {
+                // A concurrent refresh occurred and caused the session to be
+                // deleted (for a reason we can't know at this point).
+
+                // Using a distinct error message mainly for debugging
+                // purposes. Also, throwing a TokenRefreshError to trigger
+                // deletion through the deleteOnError callback.
+                const msg = 'The session was deleted by another process'
+                throw new TokenRefreshError(sub, msg, { cause })
+              } else if (
+                stored.tokenSet.access_token !== tokenSet.access_token ||
+                stored.tokenSet.refresh_token !== tokenSet.refresh_token
+              ) {
+                // A concurrent refresh occurred. Pretend this one succeeded.
+                return { dpopKey, tokenSet: stored.tokenSet }
+              } else {
+                // There were no concurrent refresh. The token is (likely)
+                // simply no longer valid.
               }
-
-              // Throwing an RefreshError to trigger deletion through the
-              // deleteOnError callback.
-              const msg = cause.errorDescription ?? 'The session was revoked'
-              throw new RefreshError(sub, msg, { cause })
             }
 
-            throw cause
-          })
+            // Make sure the session gets deleted from the store
+            const msg = cause.errorDescription ?? 'The session was revoked'
+            throw new TokenRefreshError(sub, msg, { cause })
+          }
 
-        if (sub !== newTokenSet.sub) {
-          // The server returned another sub. Was the tokenSet manipulated?
-          throw new RefreshError(sub, 'Token set sub mismatch')
+          throw cause
         }
-
-        return { ...storedSession, tokenSet: newTokenSet }
       },
       sessionStore,
       {
@@ -143,13 +172,48 @@ export class SessionGetter extends CachedGetter<string, Session> {
           await server.revoke(tokenSet.refresh_token ?? tokenSet.access_token)
           throw err
         },
-        deleteOnError: async (err) => {
-          return err instanceof RefreshError
-        },
+        deleteOnError: async (err) =>
+          // Optimization: More likely to happen first
+          err instanceof TokenRefreshError ||
+          err instanceof TokenRevokedError ||
+          err instanceof TokenInvalidError,
       },
     )
   }
 
+  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)
+  }
+
+  async setStored(sub: string, session: Session) {
+    await super.setStored(sub, session)
+    this.dispatchEvent('updated', { sub, ...session })
+  }
+
+  async delStored(sub: string, cause?: unknown): Promise<void> {
+    await super.delStored(sub, cause)
+    this.dispatchEvent('deleted', { 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
@@ -171,12 +235,12 @@ export class SessionGetter extends CachedGetter<string, Session> {
   }
 
   async get(sub: string, options?: GetCachedOptions): Promise<Session> {
-    return this.runtime.withLock(`@atproto-oauth-client-${sub}`, async () => {
+    return this.runtime.usingLock(`@atproto-oauth-client-${sub}`, async () => {
       // Make sure, even if there is no signal in the options, that the request
       // will be cancelled after at most 30 seconds.
-      return withSignal({ signal: options?.signal, timeout: 30e3 }, (signal) =>
-        super.get(sub, { ...options, signal }),
-      )
+      using signal = timeoutSignal(30e3, options)
+
+      return await super.get(sub, { ...options, signal })
     })
   }
 }

package/src/state-store.ts

@@ -0,0 +1,12 @@
+import { SimpleStore } from '@atproto-labs/simple-store'
+import { Key } from '@atproto/jwk'
+
+export type InternalStateData = {
+  iss: string
+  nonce: string
+  dpopKey: Key
+  verifier?: string
+  appState?: string
+}
+
+export type StateStore = SimpleStore<string, InternalStateData>

package/src/types.ts

@@ -11,12 +11,15 @@ import z from 'zod'
 export type AuthorizeOptions = {
   display?: 'page' | 'popup' | 'touch' | 'wap'
   redirect_uri?: string
-  id_token_hint?: string
-  max_age?: number
   prompt?: 'login' | 'none' | 'consent' | 'select_account'
   scope?: string
   state?: string
+  signal?: AbortSignal
+
+  // Only for OIDC compatible
   ui_locales?: string
+  id_token_hint?: string
+  max_age?: number
 }
 
 export const clientMetadataSchema = oauthClientMetadataSchema.extend({

package/src/util.ts

@@ -1,51 +1,82 @@
+export type Awaitable<T> = T | PromiseLike<T>
+
+// @ts-expect-error
+Symbol.dispose ??= Symbol('@@dispose')
+
 /**
  * @todo (?) move to common package
  */
-export const withSignal = async <T>(
-  options:
-    | undefined
-    | {
-        signal?: AbortSignal
-        timeout: number
-      },
-  fn: (signal: AbortSignal) => T | PromiseLike<T>,
-): Promise<T> => {
+export const timeoutSignal = (
+  timeout: number,
+  options?: { signal?: AbortSignal },
+): AbortSignal & Disposable => {
+  if (!Number.isInteger(timeout) || timeout < 0) {
+    throw new TypeError('Expected a positive integer')
+  }
+
   options?.signal?.throwIfAborted()
 
-  const abortController = new AbortController()
-  const { signal } = abortController
+  const controller = new AbortController()
+  const { signal } = controller
 
   options?.signal?.addEventListener(
     'abort',
-    (reason) => abortController.abort(reason),
+    (reason) => controller.abort(reason),
     { once: true, signal },
   )
 
-  if (options?.timeout != null) {
-    const timeoutId = setTimeout(
-      (err) => abortController.abort(err),
-      options.timeout,
-      new Error('Timeout'),
-    )
+  const timeoutId = setTimeout(
+    (err) => controller.abort(err),
+    timeout,
+    // create Error here to keep original stack trace
+    new Error('Timeout'),
+  )
 
-    timeoutId.unref?.() // NodeJS only
+  timeoutId?.unref?.() // NodeJS only
 
-    signal.addEventListener('abort', () => clearTimeout(timeoutId), {
-      once: true,
-      signal,
-    })
-  }
+  signal.addEventListener('abort', () => clearTimeout(timeoutId), {
+    once: true,
+    signal,
+  })
 
-  try {
-    return await fn(signal)
-  } finally {
-    // - Remove listener on incoming signal
-    // - Cancel timeout
-    // - Cancel pending (async) tasks
-    abortController.abort()
-  }
+  Object.defineProperty(signal, Symbol.dispose, {
+    value: () => controller.abort(),
+  })
+
+  return signal as AbortSignal & Disposable
 }
 
 export function contentMime(headers: Headers): string | undefined {
   return headers.get('content-type')?.split(';')[0]!.trim()
 }
+
+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],
+  ): boolean {
+    return this.eventTarget.dispatchEvent(new CustomEvent(type, { detail }))
+  }
+}

package/src/validate-client-metadata.ts

@@ -16,6 +16,24 @@ export function validateClientMetadata(
   input: OAuthClientMetadataInput,
   keyset?: Keyset,
 ): ClientMetadata {
+  if (input.jwks) {
+    if (!keyset) {
+      throw new TypeError(`Keyset must not be provided when jwks is provided`)
+    }
+    for (const key of input.jwks.keys) {
+      if (!key.kid) {
+        throw new TypeError(`Key must have a "kid" property`)
+      } else if (!keyset.has(key.kid)) {
+        throw new TypeError(`Key with kid "${key.kid}" not found in keyset`)
+      }
+    }
+  }
+
+  // Allow to pass a keyset and omit the jwks/jwks_uri properties
+  if (!input.jwks && !input.jwks_uri && keyset?.size) {
+    input = { ...input, jwks: keyset.toJSON() }
+  }
+
   const metadata = clientMetadataSchema.parse(input)
 
   // ATPROTO uses client metadata discovery