@atproto/oauth-client 0.7.5 → 0.7.7

package/src/oauth-session.ts

@@ -1,170 +0,0 @@
-import { AtprotoDid } from '@atproto/did'
-import {
-  AtprotoOAuthScope,
-  OAuthAuthorizationServerMetadata,
-} from '@atproto/oauth-types'
-import { Fetch, bindFetch } from '@atproto-labs/fetch'
-import { TokenInvalidError } from './errors/token-invalid-error.js'
-import { TokenRevokedError } from './errors/token-revoked-error.js'
-import { dpopFetchWrapper } from './fetch-dpop.js'
-import { OAuthServerAgent, TokenSet } from './oauth-server-agent.js'
-import { SessionGetter } from './session-getter.js'
-
-const ReadableStream = globalThis.ReadableStream as
-  | typeof globalThis.ReadableStream
-  | undefined
-
-export type { AtprotoDid, AtprotoOAuthScope }
-export type TokenInfo = {
-  expiresAt?: Date
-  expired?: boolean
-  scope: AtprotoOAuthScope
-  iss: string
-  aud: string
-  sub: AtprotoDid
-}
-
-export class OAuthSession {
-  protected dpopFetch: Fetch<unknown>
-
-  constructor(
-    public readonly server: OAuthServerAgent,
-    public readonly sub: AtprotoDid,
-    private readonly sessionGetter: SessionGetter,
-    fetch: Fetch = globalThis.fetch,
-  ) {
-    this.dpopFetch = dpopFetchWrapper<void>({
-      fetch: bindFetch(fetch),
-      key: server.dpopKey,
-      supportedAlgs: server.serverMetadata.dpop_signing_alg_values_supported,
-      sha256: async (v) => server.runtime.sha256(v),
-      nonces: server.dpopNonces,
-      isAuthServer: false,
-    })
-  }
-
-  get did(): AtprotoDid {
-    return this.sub
-  }
-
-  get serverMetadata(): Readonly<OAuthAuthorizationServerMetadata> {
-    return this.server.serverMetadata
-  }
-
-  /**
-   * @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`.
-   */
-  protected async getTokenSet(refresh: boolean | 'auto'): Promise<TokenSet> {
-    const { tokenSet } = await this.sessionGetter.getSession(this.sub, refresh)
-
-    return tokenSet
-  }
-
-  async getTokenInfo(refresh: boolean | 'auto' = 'auto'): Promise<TokenInfo> {
-    const tokenSet = await this.getTokenSet(refresh)
-    const expiresAt =
-      tokenSet.expires_at == null ? undefined : new Date(tokenSet.expires_at)
-
-    return {
-      expiresAt,
-      get expired() {
-        return expiresAt == null
-          ? undefined
-          : expiresAt.getTime() < Date.now() - 5e3
-      },
-      scope: tokenSet.scope,
-      iss: tokenSet.iss,
-      aud: tokenSet.aud,
-      sub: tokenSet.sub,
-    }
-  }
-
-  async signOut(): Promise<void> {
-    try {
-      const tokenSet = await this.getTokenSet(false)
-      await this.server.revoke(tokenSet.access_token)
-    } finally {
-      await this.sessionGetter.delStored(
-        this.sub,
-        new TokenRevokedError(this.sub),
-      )
-    }
-  }
-
-  async fetchHandler(pathname: string, init?: RequestInit): Promise<Response> {
-    // This will try and refresh the token if it is known to be expired
-    const tokenSet = await this.getTokenSet('auto')
-
-    const initialUrl = new URL(pathname, tokenSet.aud satisfies string)
-    const initialAuth = `${tokenSet.token_type} ${tokenSet.access_token}`
-
-    const headers = new Headers(init?.headers)
-    headers.set('Authorization', initialAuth)
-
-    const initialResponse = await this.dpopFetch(initialUrl, {
-      ...init,
-      headers,
-    })
-
-    // If the token is not expired, we don't need to refresh it
-    if (!isInvalidTokenResponse(initialResponse)) {
-      return initialResponse
-    }
-
-    let tokenSetFresh: TokenSet
-    try {
-      // Force a refresh
-      tokenSetFresh = await this.getTokenSet(true)
-    } catch (err) {
-      return initialResponse
-    }
-
-    // The stream was already consumed. We cannot retry the request. A solution
-    // would be to tee() the input stream but that would bufferize the entire
-    // stream in memory which can lead to memory starvation. Instead, we will
-    // return the original response and let the calling code handle retries.
-    if (ReadableStream && init?.body instanceof ReadableStream) {
-      return initialResponse
-    }
-
-    const finalAuth = `${tokenSetFresh.token_type} ${tokenSetFresh.access_token}`
-    const finalUrl = new URL(pathname, tokenSetFresh.aud)
-
-    headers.set('Authorization', finalAuth)
-
-    const finalResponse = await this.dpopFetch(finalUrl, { ...init, headers })
-
-    // The token was successfully refreshed, but is still not accepted by the
-    // resource server. This might be due to the resource server not accepting
-    // credentials from the authorization server (e.g. because some migration
-    // occurred). Any ways, there is no point in keeping the session.
-    if (isInvalidTokenResponse(finalResponse)) {
-      // @TODO Is there a "softer" way to handle this, e.g. by marking the
-      // session as "expired" in the session store, allowing the user to trigger
-      // a new login (using login_hint)?
-      await this.sessionGetter.delStored(
-        this.sub,
-        new TokenInvalidError(this.sub),
-      )
-    }
-
-    return finalResponse
-  }
-}
-
-/**
- * @see {@link https://datatracker.ietf.org/doc/html/rfc6750#section-3}
- * @see {@link https://datatracker.ietf.org/doc/html/rfc9449#name-resource-server-provided-no}
- */
-function isInvalidTokenResponse(response: Response) {
-  if (response.status !== 401) return false
-  const wwwAuth = response.headers.get('WWW-Authenticate')
-  return (
-    wwwAuth != null &&
-    (wwwAuth.startsWith('Bearer ') || wwwAuth.startsWith('DPoP ')) &&
-    wwwAuth.includes('error="invalid_token"')
-  )
-}

package/src/runtime-implementation.ts

@@ -1,25 +0,0 @@
-import { Key } from '@atproto/jwk'
-import { Awaitable } from './util.js'
-
-export type { Key }
-export type RuntimeKeyFactory = (algs: string[]) => Key | PromiseLike<Key>
-
-export type RuntimeRandomValues = (length: number) => Awaitable<Uint8Array>
-
-export type DigestAlgorithm = { name: 'sha256' | 'sha384' | 'sha512' }
-export type RuntimeDigest = (
-  data: Uint8Array<ArrayBuffer>,
-  alg: DigestAlgorithm,
-) => Awaitable<Uint8Array>
-
-export type RuntimeLock = <T>(
-  name: string,
-  fn: () => Awaitable<T>,
-) => Awaitable<T>
-
-export interface RuntimeImplementation {
-  createKey: RuntimeKeyFactory
-  getRandomValues: RuntimeRandomValues
-  digest: RuntimeDigest
-  requestLock?: RuntimeLock
-}

package/src/runtime.ts

@@ -1,114 +0,0 @@
-import { base64url } from 'multiformats/bases/base64'
-import { Key } from '@atproto/jwk'
-import { requestLocalLock } from './lock.js'
-import { RuntimeImplementation, RuntimeLock } from './runtime-implementation.js'
-
-export class Runtime {
-  readonly hasImplementationLock: boolean
-  readonly usingLock: RuntimeLock
-
-  constructor(protected implementation: RuntimeImplementation) {
-    const { requestLock } = implementation
-
-    this.hasImplementationLock = requestLock != null
-    this.usingLock =
-      requestLock?.bind(implementation) ||
-      // Falling back to a local lock
-      requestLocalLock
-  }
-
-  public async generateKey(algs: string[]): Promise<Key> {
-    const algsSorted = Array.from(algs).sort(compareAlgos)
-    return this.implementation.createKey(algsSorted)
-  }
-
-  public async sha256(text: string): Promise<string> {
-    const bytes = new TextEncoder().encode(text)
-    const digest = await this.implementation.digest(bytes, { name: 'sha256' })
-    return base64url.baseEncode(digest)
-  }
-
-  public async generateNonce(length = 16): Promise<string> {
-    const bytes = await this.implementation.getRandomValues(length)
-    return base64url.baseEncode(bytes)
-  }
-
-  public async generatePKCE(byteLength?: number) {
-    const verifier = await this.generateVerifier(byteLength)
-    return {
-      verifier,
-      challenge: await this.sha256(verifier),
-      method: 'S256' as const,
-    }
-  }
-
-  public async calculateJwkThumbprint(jwk) {
-    const components = extractJktComponents(jwk)
-    const data = JSON.stringify(components)
-    return this.sha256(data)
-  }
-
-  /**
-   * @see {@link https://datatracker.ietf.org/doc/html/rfc7636#section-4.1}
-   * @note It is RECOMMENDED that the output of a suitable random number generator
-   * be used to create a 32-octet sequence. The octet sequence is then
-   * base64url-encoded to produce a 43-octet URL safe string to use as the code
-   * verifier.
-   */
-  protected async generateVerifier(byteLength = 32) {
-    if (byteLength < 32 || byteLength > 96) {
-      throw new TypeError('Invalid code_verifier length')
-    }
-    const bytes = await this.implementation.getRandomValues(byteLength)
-    return base64url.baseEncode(bytes)
-  }
-}
-
-function extractJktComponents(jwk) {
-  const get = (field) => {
-    const value = jwk[field]
-    if (typeof value !== 'string' || !value) {
-      throw new TypeError(`"${field}" Parameter missing or invalid`)
-    }
-    return value
-  }
-
-  switch (jwk.kty) {
-    case 'EC':
-      return { crv: get('crv'), kty: get('kty'), x: get('x'), y: get('y') }
-    case 'OKP':
-      return { crv: get('crv'), kty: get('kty'), x: get('x') }
-    case 'RSA':
-      return { e: get('e'), kty: get('kty'), n: get('n') }
-    case 'oct':
-      return { k: get('k'), kty: get('kty') }
-    default:
-      throw new TypeError('"kty" (Key Type) Parameter missing or unsupported')
-  }
-}
-
-/**
- * 256K > ES (256 > 384 > 512) > PS (256 > 384 > 512) > RS (256 > 384 > 512) > other (in original order)
- */
-function compareAlgos(a: string, b: string): number {
-  if (a === 'ES256K') return -1
-  if (b === 'ES256K') return 1
-
-  for (const prefix of ['ES', 'PS', 'RS']) {
-    if (a.startsWith(prefix)) {
-      if (b.startsWith(prefix)) {
-        const aLen = parseInt(a.slice(2, 5))
-        const bLen = parseInt(b.slice(2, 5))
-
-        // Prefer shorter key lengths
-        return aLen - bLen
-      }
-      return -1
-    } else if (b.startsWith(prefix)) {
-      return 1
-    }
-  }
-
-  // Don't know how to compare, keep original order
-  return 0
-}

package/src/session-getter.ts

@@ -1,281 +0,0 @@
-import { AtprotoDid } from '@atproto/did'
-import { Key } from '@atproto/jwk'
-import {
-  CachedGetter,
-  GetCachedOptions,
-  GetOptions,
-  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'
-import { Runtime } from './runtime.js'
-import { combineSignals, timeoutSignal } from './util.js'
-
-export type Session = {
-  dpopKey: Key
-  authMethod: ClientAuthMethod
-  tokenSet: TokenSet
-}
-
-export type SessionStore = SimpleStore<string, Session>
-
-export type SessionHooks = {
-  onUpdate?: (sub: AtprotoDid, session: Session) => void
-  onDelete?: (
-    sub: AtprotoDid,
-    cause: TokenRefreshError | TokenRevokedError | TokenInvalidError | unknown,
-  ) => 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)
- * CachedGetter, the main of which is that the cached getter will ensure that at
- * most one fresh call is ever being made. Another advantage, is that it
- * contains the logic for reading from the cache which, if the cache is based on
- * localStorage/indexedDB, will sync across multiple tabs (for a given sub).
- */
-export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
-  constructor(
-    sessionStore: SessionStore,
-    serverFactory: OAuthServerFactory,
-    private readonly runtime: Runtime,
-    private readonly hooks: SessionHooks = {},
-  ) {
-    super(
-      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.
-        if (storedSession === undefined) {
-          // 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)
-          await hooks.onDelete?.call(null, sub, cause)
-          throw cause
-        }
-
-        // @NOTE Throwing a TokenRefreshError (or any other error class defined
-        // in the deleteOnError options) will result in this.delStored() being
-        // called.
-
-        const { dpopKey, authMethod, tokenSet } = storedSession
-
-        if (sub !== tokenSet.sub) {
-          // Fool-proofing (e.g. against invalid session storage)
-          throw new TokenRefreshError(sub, 'Stored session sub mismatch')
-        }
-
-        if (!tokenSet.refresh_token) {
-          throw new TokenRefreshError(sub, 'No refresh token available')
-        }
-
-        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
-        // 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.
-        signal?.throwIfAborted()
-
-        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,
-            authMethod: server.authMethod,
-          }
-        } catch (cause) {
-          // 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 &&
-            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 stored
-              } else {
-                // There were no concurrent refresh. The token is (likely)
-                // simply no longer valid.
-              }
-            }
-
-            // Make sure the session gets deleted from the store
-            const msg = cause.errorDescription ?? 'The session was revoked'
-            throw new TokenRefreshError(sub, msg, { cause })
-          }
-
-          throw cause
-        }
-      },
-      sessionStore,
-      {
-        isStale: (sub, { tokenSet }) => {
-          return (
-            tokenSet.expires_at != null &&
-            new Date(tokenSet.expires_at).getTime() <
-              Date.now() +
-                // Add some lee way to ensure the token is not expired when it
-                // reaches the server.
-                10e3 +
-                // Add some randomness to reduce the chances of multiple
-                // instances trying to refresh the token at the same.
-                30e3 * Math.random()
-          )
-        },
-        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: isExpectedSessionError,
-      },
-    )
-  }
-
-  override async getStored(
-    sub: AtprotoDid,
-    options?: GetOptions,
-  ): Promise<Session | undefined> {
-    return super.getStored(sub, options)
-  }
-
-  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)
-    await this.hooks.onUpdate?.call(null, sub, session)
-  }
-
-  override async delStored(sub: AtprotoDid, cause?: unknown): Promise<void> {
-    await super.delStored(sub, cause)
-    await this.hooks.onDelete?.call(null, sub, cause)
-  }
-
-  /**
-   * @deprecated Use {@link getSession} instead
-   * @internal (not really deprecated)
-   */
-  override async get(
-    sub: AtprotoDid,
-    options?: GetCachedOptions,
-  ): Promise<Session> {
-    const session = await 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.
-        const signal = timeoutSignal(30e3)
-
-        using abortController = combineSignals([options?.signal, signal])
-
-        return await super.get(sub, {
-          ...options,
-          signal: abortController.signal,
-        })
-      },
-    )
-
-    if (sub !== session.tokenSet.sub) {
-      // Fool-proofing (e.g. against invalid session storage)
-      throw new Error('Token set does not match the expected sub')
-    }
-
-    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

@@ -1,24 +0,0 @@
-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
-  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/types.ts

@@ -1,39 +0,0 @@
-import { TypeOf, z } from 'zod'
-import {
-  OAuthAuthorizationRequestParameters,
-  oauthClientIdDiscoverableSchema,
-  oauthClientIdLoopbackSchema,
-  oauthClientMetadataSchema,
-} from '@atproto/oauth-types'
-import { Simplify } from './util.js'
-
-// Note: These types are not prefixed with `OAuth` because they are not specific
-// to OAuth. They are specific to this packages. OAuth specific types are in
-// `@atproto/oauth-types`.
-
-export type AuthorizeOptions = Simplify<
-  Omit<
-    OAuthAuthorizationRequestParameters,
-    | 'client_id'
-    | 'response_mode'
-    | 'response_type'
-    | 'login_hint'
-    | 'code_challenge'
-    | 'code_challenge_method'
-  > & {
-    signal?: AbortSignal
-  }
->
-
-export type CallbackOptions = Simplify<
-  Partial<Pick<OAuthAuthorizationRequestParameters, 'redirect_uri'>>
->
-
-export const clientMetadataSchema = oauthClientMetadataSchema.extend({
-  client_id: z.union([
-    oauthClientIdDiscoverableSchema,
-    oauthClientIdLoopbackSchema,
-  ]),
-})
-
-export type ClientMetadata = TypeOf<typeof clientMetadataSchema>