@atproto/oauth-client 0.2.2 → 0.3.0

package/src/oauth-server-agent.ts

@@ -1,18 +1,23 @@
 import { Fetch, Json, bindFetch, fetchJsonProcessor } from '@atproto-labs/fetch'
 import { SimpleStore } from '@atproto-labs/simple-store'
+import { AtprotoDid } from '@atproto/did'
 import { Key, Keyset } from '@atproto/jwk'
 import {
   CLIENT_ASSERTION_TYPE_JWT_BEARER,
+  OAuthAuthorizationRequestPar,
   OAuthAuthorizationServerMetadata,
   OAuthClientCredentials,
   OAuthEndpointName,
   OAuthParResponse,
-  OAuthTokenResponse,
-  OAuthTokenType,
+  OAuthTokenRequest,
   oauthParResponseSchema,
-  oauthTokenResponseSchema,
 } from '@atproto/oauth-types'
 
+import {
+  AtprotoScope,
+  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'
@@ -24,13 +29,13 @@ import { timeoutSignal } from './util.js'
 
 export type TokenSet = {
   iss: string
-  sub: string
+  sub: AtprotoDid
   aud: string
-  scope: string
+  scope: AtprotoScope
 
   refresh_token?: string
   access_token: string
-  token_type: OAuthTokenType
+  token_type: 'DPoP'
   /** ISO Date */
   expires_at?: string
 }
@@ -61,6 +66,10 @@ export class OAuthServerAgent {
     })
   }
 
+  get issuer() {
+    return this.serverMetadata.issuer
+  }
+
   async revoke(token: string) {
     try {
       await this.request('revocation', { token })
@@ -69,16 +78,38 @@ export class OAuthServerAgent {
     }
   }
 
-  async exchangeCode(code: string, verifier?: string): Promise<TokenSet> {
+  async exchangeCode(code: string, codeVerifier?: string): Promise<TokenSet> {
+    const now = Date.now()
+
     const tokenResponse = await this.request('token', {
       grant_type: 'authorization_code',
       redirect_uri: this.clientMetadata.redirect_uris[0]!,
       code,
-      code_verifier: verifier,
+      code_verifier: codeVerifier,
     })
 
     try {
-      return this.processTokenResponse(tokenResponse)
+      // /!\ IMPORTANT /!\
+      //
+      // The tokenResponse MUST always be valid before the "sub" it contains
+      // can be trusted (see Atproto's OAuth spec for details).
+      const aud = await this.verifyIssuer(tokenResponse.sub)
+
+      return {
+        aud,
+        sub: tokenResponse.sub,
+        iss: this.issuer,
+
+        scope: tokenResponse.scope,
+        refresh_token: tokenResponse.refresh_token,
+        access_token: tokenResponse.access_token,
+        token_type: tokenResponse.token_type,
+
+        expires_at:
+          typeof tokenResponse.expires_in === 'number'
+            ? new Date(now + tokenResponse.expires_in * 1000).toISOString()
+            : undefined,
+      }
     } catch (err) {
       await this.revoke(tokenResponse.access_token)
 
@@ -91,27 +122,37 @@ export class OAuthServerAgent {
       throw new TokenRefreshError(tokenSet.sub, 'No refresh token available')
     }
 
+    // /!\ IMPORTANT /!\
+    //
+    // The "sub" MUST be a DID, whose issuer authority is indeed the server we
+    // are trying to obtain credentials from. Note that we are doing this
+    // *before* we actually try to refresh the token:
+    // 1) To avoid unnecessary refresh
+    // 2) So that the refresh is the last async operation, ensuring as few
+    //    async operations happen before the result gets a chance to be stored.
+    const aud = await this.verifyIssuer(tokenSet.sub)
+
+    const now = Date.now()
+
     const tokenResponse = await this.request('token', {
       grant_type: 'refresh_token',
       refresh_token: tokenSet.refresh_token,
     })
 
-    try {
-      if (tokenSet.sub !== tokenResponse.sub) {
-        throw new TokenRefreshError(
-          tokenSet.sub,
-          `Unexpected "sub" in token response (${tokenResponse.sub})`,
-        )
-      }
-      if (tokenSet.iss !== this.serverMetadata.issuer) {
-        throw new TokenRefreshError(tokenSet.sub, 'Issuer mismatch')
-      }
+    return {
+      aud,
+      sub: tokenSet.sub,
+      iss: this.issuer,
 
-      return this.processTokenResponse(tokenResponse)
-    } catch (err) {
-      await this.revoke(tokenResponse.access_token)
+      scope: tokenResponse.scope,
+      refresh_token: tokenResponse.refresh_token,
+      access_token: tokenResponse.access_token,
+      token_type: tokenResponse.token_type,
 
-      throw err
+      expires_at:
+        typeof tokenResponse.expires_in === 'number'
+          ? new Date(now + tokenResponse.expires_in * 1000).toISOString()
+          : undefined,
     }
   }
 
@@ -122,68 +163,46 @@ export class OAuthServerAgent {
    * "sub" is a DID, whose issuer authority is indeed the server we just
    * obtained credentials from. This check is a critical step to actually be
    * able to use the "sub" (DID) as being the actual user's identifier.
+   *
+   * @returns The user's PDS URL (the resource server for the user)
    */
-  private async processTokenResponse(
-    tokenResponse: OAuthTokenResponse,
-  ): Promise<TokenSet> {
-    const { sub } = tokenResponse
-
-    if (!sub || typeof sub !== 'string') {
-      throw new TypeError(`Unexpected ${typeof sub} "sub" in token response`)
-    }
-
-    // Using an array to check for the presence of the "atproto" scope (we don't
-    // want atproto to be a substring of another scope)
-    const scopes = tokenResponse.scope?.split(' ')
-    if (!scopes?.includes('atproto')) {
-      throw new TypeError('Missing "atproto" scope in token response')
-    }
-
-    // @TODO (?) make timeout configurable
+  protected async verifyIssuer(sub: AtprotoDid) {
     using signal = timeoutSignal(10e3)
 
     const resolved = await this.oauthResolver.resolveFromIdentity(sub, {
+      noCache: true,
+      allowStale: false,
       signal,
     })
 
-    if (this.serverMetadata.issuer !== resolved.metadata.issuer) {
+    if (this.issuer !== resolved.metadata.issuer) {
       // Best case scenario; the user switched PDS. Worst case scenario; a bad
       // actor is trying to impersonate a user. In any case, we must not allow
       // this token to be used.
       throw new TypeError('Issuer mismatch')
     }
 
-    return {
-      aud: resolved.identity.pds.href,
-      iss: resolved.metadata.issuer,
-
-      sub,
-
-      scope: tokenResponse.scope!,
-      refresh_token: tokenResponse.refresh_token,
-      access_token: tokenResponse.access_token,
-      token_type: tokenResponse.token_type ?? 'Bearer',
-      expires_at:
-        typeof tokenResponse.expires_in === 'number'
-          ? new Date(Date.now() + tokenResponse.expires_in * 1000).toISOString()
-          : undefined,
-    }
+    return resolved.identity.pds.href
   }
 
-  async request(
-    endpoint: 'token',
-    payload: Record<string, unknown>,
-  ): Promise<OAuthTokenResponse>
-  async request(
-    endpoint: 'pushed_authorization_request',
-    payload: Record<string, unknown>,
-  ): Promise<OAuthParResponse>
+  async request<Endpoint extends OAuthEndpointName>(
+    endpoint: Endpoint,
+    payload: Endpoint extends 'token'
+      ? OAuthTokenRequest
+      : Endpoint extends 'pushed_authorization_request'
+        ? OAuthAuthorizationRequestPar
+        : Record<string, unknown>,
+  ): Promise<
+    Endpoint extends 'token'
+      ? AtprotoTokenResponse
+      : Endpoint extends 'pushed_authorization_request'
+        ? OAuthParResponse
+        : Json
+  >
   async request(
     endpoint: OAuthEndpointName,
     payload: Record<string, unknown>,
-  ): Promise<Json>
-
-  async request(endpoint: OAuthEndpointName, payload: Record<string, unknown>) {
+  ): Promise<unknown> {
     const url = this.serverMetadata[`${endpoint}_endpoint`]
     if (!url) throw new Error(`No ${endpoint} endpoint available`)
 
@@ -198,7 +217,7 @@ export class OAuthServerAgent {
     if (response.ok) {
       switch (endpoint) {
         case 'token':
-          return oauthTokenResponseSchema.parse(json)
+          return atprotoTokenResponseSchema.parse(json)
         case 'pushed_authorization_request':
           return oauthParResponseSchema.parse(json)
         default:

package/src/oauth-session.ts

@@ -1,7 +1,8 @@
-import { asDid } from '@atproto/did'
-import { Fetch, bindFetch } from '@atproto-labs/fetch'
+import { bindFetch, Fetch } from '@atproto-labs/fetch'
+import { AtprotoDid } from '@atproto/did'
 import { OAuthAuthorizationServerMetadata } from '@atproto/oauth-types'
 
+import { AtprotoScope } from './atproto-token-response.js'
 import { TokenInvalidError } from './errors/token-invalid-error.js'
 import { TokenRevokedError } from './errors/token-revoked-error.js'
 import { dpopFetchWrapper } from './fetch-dpop.js'
@@ -15,10 +16,10 @@ const ReadableStream = globalThis.ReadableStream as
 export type TokenInfo = {
   expiresAt?: Date
   expired?: boolean
-  scope?: string
+  scope: AtprotoScope
   iss: string
   aud: string
-  sub: string
+  sub: AtprotoDid
 }
 
 export class OAuthSession {
@@ -26,7 +27,7 @@ export class OAuthSession {
 
   constructor(
     public readonly server: OAuthServerAgent,
-    public readonly sub: string,
+    public readonly sub: AtprotoDid,
     private readonly sessionGetter: SessionGetter,
     fetch: Fetch = globalThis.fetch,
   ) {
@@ -41,8 +42,8 @@ export class OAuthSession {
     })
   }
 
-  get did() {
-    return asDid(this.sub)
+  get did(): AtprotoDid {
+    return this.sub
   }
 
   get serverMetadata(): Readonly<OAuthAuthorizationServerMetadata> {
@@ -50,14 +51,21 @@ export class OAuthSession {
   }
 
   /**
-   * @param refresh See {@link SessionGetter.getSession}
+   * @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`.
    */
-  public async getTokenSet(refresh?: boolean): Promise<TokenSet> {
-    const { tokenSet } = await this.sessionGetter.getSession(this.sub, refresh)
+  protected async getTokenSet(refresh: boolean | 'auto'): Promise<TokenSet> {
+    const { tokenSet } = await this.sessionGetter.get(this.sub, {
+      noCache: refresh === true,
+      allowStale: refresh === false,
+    })
+
     return tokenSet
   }
 
-  async getTokenInfo(refresh?: boolean): Promise<TokenInfo> {
+  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)
@@ -78,7 +86,7 @@ export class OAuthSession {
 
   async signOut(): Promise<void> {
     try {
-      const { tokenSet } = await this.sessionGetter.getSession(this.sub, false)
+      const tokenSet = await this.getTokenSet(false)
       await this.server.revoke(tokenSet.access_token)
     } finally {
       await this.sessionGetter.delStored(
@@ -90,7 +98,7 @@ export class OAuthSession {
 
   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(undefined)
+    const tokenSet = await this.getTokenSet('auto')
 
     const initialUrl = new URL(pathname, tokenSet.aud)
     const initialAuth = `${tokenSet.token_type} ${tokenSet.access_token}`

package/src/runtime.ts

@@ -39,7 +39,7 @@ export class Runtime {
     return {
       verifier,
       challenge: await this.sha256(verifier),
-      method: 'S256',
+      method: 'S256' as const,
     }
   }
 

package/src/session-getter.ts

@@ -3,6 +3,7 @@ import {
   GetCachedOptions,
   SimpleStore,
 } from '@atproto-labs/simple-store'
+import { AtprotoDid } from '@atproto/did'
 import { Key } from '@atproto/jwk'
 
 import { TokenInvalidError } from './errors/token-invalid-error.js'
@@ -12,7 +13,7 @@ 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, timeoutSignal } from './util.js'
+import { combineSignals, CustomEventTarget, timeoutSignal } from './util.js'
 
 export type Session = {
   dpopKey: Key
@@ -42,7 +43,7 @@ export type SessionEventListener<
  * 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<string, Session> {
+export class SessionGetter extends CachedGetter<AtprotoDid, Session> {
   private readonly eventTarget = new CustomEventTarget<SessionEventMap>()
 
   constructor(
@@ -73,30 +74,33 @@ export class SessionGetter extends CachedGetter<string, Session> {
         // concurrent access (which, normally, should not happen if a proper
         // runtime lock was provided).
 
-        if (sub !== storedSession.tokenSet.sub) {
+        const { dpopKey, 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')
+        }
+
         // Since refresh tokens can only be used once, we might run into
-        // concurrency issues if multiple tabs/instances are trying to refresh
-        // the same token. The chances of this happening when multiple instances
-        // are started simultaneously is reduced by randomizing the expiry time
-        // (see isStale() below). Even so, There still exist chances that
-        // multiple tabs will try to refresh the token at the same time. The
-        // best solution would be to use a mutex/lock to ensure that only one
-        // instance is refreshing the token at a time. A simpler workaround is
-        // to check if the value stored in the session store is the same as the
-        // one in memory. If it isn't, then another instance has already
-        // refreshed the token.
-
-        const { tokenSet, dpopKey } = storedSession
+        // 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, 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
-        // SessionGetter from obtaining, and storing, the new token set,
+        // TokenGetter from obtaining, and storing, the new token set,
         // effectively rendering the currently saved session unusable.
         options?.signal?.throwIfAborted()
 
@@ -140,7 +144,7 @@ export class SessionGetter extends CachedGetter<string, Session> {
                 stored.tokenSet.refresh_token !== tokenSet.refresh_token
               ) {
                 // A concurrent refresh occurred. Pretend this one succeeded.
-                return { dpopKey, tokenSet: stored.tokenSet }
+                return stored
               } else {
                 // There were no concurrent refresh. The token is (likely)
                 // simply no longer valid.
@@ -161,9 +165,13 @@ export class SessionGetter extends CachedGetter<string, Session> {
           return (
             tokenSet.expires_at != null &&
             new Date(tokenSet.expires_at).getTime() <
-              // Add some lee way to ensure the token is not expired when it
-              // reaches the server.
-              Date.now() + 60e3
+              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 }) => {
@@ -205,11 +213,15 @@ export class SessionGetter extends CachedGetter<string, Session> {
   }
 
   async setStored(sub: string, 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 })
   }
 
-  async delStored(sub: string, cause?: unknown): Promise<void> {
+  override async delStored(sub: AtprotoDid, cause?: unknown): Promise<void> {
     await super.delStored(sub, cause)
     this.dispatchEvent('deleted', { sub, cause })
   }
@@ -220,11 +232,29 @@ export class SessionGetter extends CachedGetter<string, Session> {
    * 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: string, refresh?: boolean) {
-    const session = await this.get(sub, {
+  async getSession(sub: AtprotoDid, refresh?: boolean) {
+    return this.get(sub, {
       noCache: refresh === true,
       allowStale: refresh === false,
     })
+  }
+
+  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.
+        using signal = timeoutSignal(30e3, options)
+
+        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)
@@ -233,14 +263,4 @@ export class SessionGetter extends CachedGetter<string, Session> {
 
     return session
   }
-
-  async get(sub: string, options?: GetCachedOptions): Promise<Session> {
-    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.
-      using signal = timeoutSignal(30e3, options)
-
-      return await super.get(sub, { ...options, signal })
-    })
-  }
 }

package/src/types.ts

@@ -1,24 +1,29 @@
 import {
+  OAuthAuthorizationRequestParameters,
   oauthClientIdSchema,
   oauthClientMetadataSchema,
 } from '@atproto/oauth-types'
 import z from 'zod'
 
+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 = {
-  display?: 'page' | 'popup' | 'touch' | 'wap'
-  redirect_uri?: string
-  prompt?: 'login' | 'none' | 'consent' | 'select_account'
-  scope?: string
-  state?: string
-  signal?: AbortSignal
-
-  // Borrowed from OIDC
-  ui_locales?: string
-}
+export type AuthorizeOptions = Simplify<
+  Omit<
+    OAuthAuthorizationRequestParameters,
+    | 'client_id'
+    | 'response_mode'
+    | 'response_type'
+    | 'login_hint'
+    | 'code_challenge'
+    | 'code_challenge_method'
+  > & {
+    signal?: AbortSignal
+  }
+>
 
 export const clientMetadataSchema = oauthClientMetadataSchema.extend({
   client_id: oauthClientIdSchema.url(),

package/src/util.ts

@@ -1,4 +1,5 @@
 export type Awaitable<T> = T | PromiseLike<T>
+export type Simplify<T> = { [K in keyof T]: T[K] } & NonNullable<unknown>
 
 // @ts-expect-error
 Symbol.dispose ??= Symbol('@@dispose')
@@ -116,3 +117,80 @@ export class CustomEventTarget<EventDetailMap extends Record<string, unknown>> {
     )
   }
 }
+
+export type SpaceSeparatedValue<Value extends string> =
+  | `${Value}`
+  | `${Value} ${string}`
+  | `${string} ${Value}`
+  | `${string} ${Value} ${string}`
+
+export const includesSpaceSeparatedValue = <Value extends string>(
+  input: string,
+  value: Value,
+): input is SpaceSeparatedValue<Value> => {
+  if (value.length === 0) throw new TypeError('Value cannot be empty')
+  if (value.includes(' ')) throw new TypeError('Value cannot contain spaces')
+
+  // Optimized version of:
+  // return input.split(' ').includes(value)
+
+  const inputLength = input.length
+  const valueLength = value.length
+
+  if (inputLength < valueLength) return false
+
+  let idx = input.indexOf(value)
+  let idxEnd: number
+
+  while (idx !== -1) {
+    idxEnd = idx + valueLength
+
+    if (
+      // at beginning or preceded by space
+      (idx === 0 || input[idx - 1] === ' ') &&
+      // at end or followed by space
+      (idxEnd === inputLength || input[idxEnd] === ' ')
+    ) {
+      return true
+    }
+
+    idx = input.indexOf(value, idxEnd + 1)
+  }
+
+  return false
+}
+
+export function combineSignals(signals: readonly (AbortSignal | undefined)[]) {
+  const controller = new AbortController()
+
+  const onAbort = function (this: AbortSignal, _event: Event) {
+    const reason = new Error('This operation was aborted', {
+      cause: this.reason,
+    })
+
+    controller.abort(reason)
+  }
+
+  for (const sig of signals) {
+    if (!sig) continue
+
+    if (sig.aborted) {
+      // Remove "abort" listener that was added to sig in previous iterations
+      controller.abort()
+
+      throw new Error('One of the signals is already aborted', {
+        cause: sig.reason,
+      })
+    }
+
+    sig.addEventListener('abort', onAbort, { signal: controller.signal })
+  }
+
+  controller[Symbol.dispose] = () => {
+    const reason = new Error('AbortController was disposed')
+
+    controller.abort(reason)
+  }
+
+  return controller as AbortController & Disposable
+}

package/tsconfig.build.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/atproto-token-response.ts","./src/constants.ts","./src/fetch-dpop.ts","./src/index.ts","./src/lock.ts","./src/oauth-authorization-server-metadata-resolver.ts","./src/oauth-callback-error.ts","./src/oauth-client.ts","./src/oauth-protected-resource-metadata-resolver.ts","./src/oauth-resolver-error.ts","./src/oauth-resolver.ts","./src/oauth-response-error.ts","./src/oauth-server-agent.ts","./src/oauth-server-factory.ts","./src/oauth-session.ts","./src/runtime-implementation.ts","./src/runtime.ts","./src/session-getter.ts","./src/state-store.ts","./src/types.ts","./src/util.ts","./src/validate-client-metadata.ts","./src/errors/token-invalid-error.ts","./src/errors/token-refresh-error.ts","./src/errors/token-revoked-error.ts"],"version":"5.6.3"}