@atproto/oauth-types 0.4.1 → 0.4.2

package/src/atproto-loopback-client-metadata.ts

@@ -1,23 +1,43 @@
 import {
-  OAuthClientIdLoopback,
-  parseOAuthLoopbackClientId,
-} from './oauth-client-id-loopback.js'
+  AtprotoLoopbackClientIdParams,
+  OAuthLoopbackClientIdConfig,
+  buildAtprotoLoopbackClientId,
+  parseAtprotoLoopbackClientId,
+} from './atproto-loopback-client-id.js'
+import { AtprotoOAuthScope } from './atproto-oauth-scope.js'
+import { OAuthClientIdLoopback } from './oauth-client-id-loopback.js'
 import { OAuthClientMetadataInput } from './oauth-client-metadata.js'
+import { OAuthLoopbackRedirectURI } from './oauth-redirect-uri.js'
+
+export type AtprotoLoopbackClientMetadata = OAuthClientMetadataInput & {
+  client_id: OAuthClientIdLoopback
+  scope: AtprotoOAuthScope
+  redirect_uris: [OAuthLoopbackRedirectURI, ...OAuthLoopbackRedirectURI[]]
+}
 
 export function atprotoLoopbackClientMetadata(
   clientId: string,
-): OAuthClientMetadataInput & {
-  client_id: OAuthClientIdLoopback
-} {
-  const {
-    scope = 'atproto',
-    redirect_uris = [`http://127.0.0.1/`, `http://[::1]/`],
-  } = parseOAuthLoopbackClientId(clientId)
+): AtprotoLoopbackClientMetadata {
+  const params = parseAtprotoLoopbackClientId(clientId)
+  // Safe to cast because parseAtprotoLoopbackClientId ensures it's a loopback ID
+  return buildMetadataInternal(clientId as OAuthClientIdLoopback, params)
+}
+
+export function buildAtprotoLoopbackClientMetadata(
+  config: OAuthLoopbackClientIdConfig,
+): AtprotoLoopbackClientMetadata {
+  const clientId = buildAtprotoLoopbackClientId(config)
+  return buildMetadataInternal(clientId, parseAtprotoLoopbackClientId(clientId))
+}
 
+function buildMetadataInternal(
+  clientId: OAuthClientIdLoopback,
+  clientParams: AtprotoLoopbackClientIdParams,
+): AtprotoLoopbackClientMetadata {
   return {
-    client_id: clientId as OAuthClientIdLoopback,
-    scope,
-    redirect_uris,
+    client_id: clientId,
+    scope: clientParams.scope,
+    redirect_uris: clientParams.redirect_uris,
     response_types: ['code'],
     grant_types: ['authorization_code', 'refresh_token'],
     token_endpoint_auth_method: 'none',

package/src/atproto-loopback-client-redirect-uris.ts

@@ -0,0 +1,4 @@
+export const DEFAULT_LOOPBACK_CLIENT_REDIRECT_URIS = Object.freeze([
+  `http://127.0.0.1/`,
+  `http://[::1]/`,
+] as const)

package/src/atproto-oauth-scope.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod'
+import { OAuthScope, isOAuthScope } from './oauth-scope.js'
+import { SpaceSeparatedValue, isSpaceSeparatedValue } from './util.js'
+
+export const ATPROTO_SCOPE_VALUE = 'atproto'
+export type AtprotoScopeValue = typeof ATPROTO_SCOPE_VALUE
+
+export type AtprotoOAuthScope = OAuthScope &
+  SpaceSeparatedValue<AtprotoScopeValue>
+
+export function isAtprotoOAuthScope(input: string): input is AtprotoOAuthScope {
+  return (
+    isOAuthScope(input) && isSpaceSeparatedValue(ATPROTO_SCOPE_VALUE, input)
+  )
+}
+
+export function asAtprotoOAuthScope<I extends string>(input: I) {
+  if (isAtprotoOAuthScope(input)) return input
+  throw new TypeError(`Value must contain "${ATPROTO_SCOPE_VALUE}" scope value`)
+}
+
+export function assertAtprotoOAuthScope(
+  input: string,
+): asserts input is AtprotoOAuthScope {
+  void asAtprotoOAuthScope(input)
+}
+
+export const atprotoOAuthScopeSchema = z.string().refine(isAtprotoOAuthScope, {
+  message: 'Invalid ATProto OAuth scope',
+})
+
+// Default scope is for reading identity (did) only
+export const DEFAULT_ATPROTO_OAUTH_SCOPE =
+  ATPROTO_SCOPE_VALUE satisfies AtprotoOAuthScope

package/src/atproto-oauth-token-response.ts

@@ -0,0 +1,16 @@
+import { TypeOf, z } from 'zod'
+import { atprotoDidSchema } from '@atproto/did'
+import { atprotoOAuthScopeSchema } from './atproto-oauth-scope'
+import { oauthTokenResponseSchema } from './oauth-token-response.js'
+
+export const atprotoOAuthTokenResponseSchema = oauthTokenResponseSchema.extend({
+  token_type: z.literal('DPoP'),
+  sub: atprotoDidSchema,
+  scope: atprotoOAuthScopeSchema,
+  // OpenID is not compatible with atproto identities
+  id_token: z.never().optional(),
+})
+
+export type AtprotoOAuthTokenResponse = TypeOf<
+  typeof atprotoOAuthTokenResponseSchema
+>

package/src/index.ts

@@ -2,9 +2,12 @@ export * from './constants.js'
 export * from './uri.js'
 export * from './util.js'
 
+export * from './atproto-loopback-client-id.js'
 export * from './atproto-loopback-client-metadata.js'
+export * from './atproto-loopback-client-redirect-uris.js'
+export * from './atproto-oauth-scope.js'
+export * from './atproto-oauth-token-response.js'
 export * from './oauth-access-token.js'
-export * from './oauth-authorization-response-error.js'
 export * from './oauth-authorization-code-grant-token-request.js'
 export * from './oauth-authorization-details.js'
 export * from './oauth-authorization-request-jar.js'
@@ -12,6 +15,7 @@ export * from './oauth-authorization-request-par.js'
 export * from './oauth-authorization-request-parameters.js'
 export * from './oauth-authorization-request-query.js'
 export * from './oauth-authorization-request-uri.js'
+export * from './oauth-authorization-response-error.js'
 export * from './oauth-authorization-server-metadata.js'
 export * from './oauth-client-credentials-grant-token-request.js'
 export * from './oauth-client-credentials.js'

package/src/oauth-client-id-loopback.ts

@@ -1,106 +1,164 @@
-import { TypeOf, ZodIssueCode } from 'zod'
 import { oauthClientIdSchema } from './oauth-client-id.js'
 import {
   OAuthLoopbackRedirectURI,
-  OAuthRedirectUri,
   oauthLoopbackRedirectURISchema,
 } from './oauth-redirect-uri.js'
 import { OAuthScope, oauthScopeSchema } from './oauth-scope.js'
 
-const PREFIX = 'http://localhost'
+export const LOOPBACK_CLIENT_ID_ORIGIN = 'http://localhost'
+
+// @NOTE This is not actually based on a standard, but rather a convention
+// established by Bluesky in the Atproto specs and implementation. As such, and
+// in order to respect the convention from this package, these should be
+// prefixed with "Atproto" instead of "OAuth". For legacy reasons, we keep the
+// current names, but we should rename them in a future major release, unless
+// loopback client ids have since then been standardized.
+
+export type OAuthClientIdLoopback =
+  `http://localhost${'' | `/`}${'' | `?${string}`}`
+
+export type OAuthLoopbackClientIdParams = {
+  scope?: OAuthScope
+  redirect_uris?: [OAuthLoopbackRedirectURI, ...OAuthLoopbackRedirectURI[]]
+}
 
 export const oauthClientIdLoopbackSchema = oauthClientIdSchema.superRefine(
-  (value, ctx): value is `${typeof PREFIX}${'' | '/'}${'' | `?${string}`}` => {
-    try {
-      assertOAuthLoopbackClientId(value)
-      return true
-    } catch (error) {
-      ctx.addIssue({
-        code: ZodIssueCode.custom,
-        message:
-          error instanceof TypeError
-            ? error.message
-            : 'Invalid loopback client ID',
-      })
-      return false
+  (input, ctx): input is OAuthClientIdLoopback => {
+    const result = safeParseOAuthLoopbackClientId(input)
+    if (!result.success) {
+      ctx.addIssue({ code: 'custom', message: result.message })
     }
+    return result.success
   },
 )
 
-export type OAuthClientIdLoopback = TypeOf<typeof oauthClientIdLoopbackSchema>
+export function assertOAuthLoopbackClientId(
+  input: string,
+): asserts input is OAuthClientIdLoopback {
+  void parseOAuthLoopbackClientId(input)
+}
 
-export function isOAuthClientIdLoopback(
-  clientId: string,
-): clientId is OAuthClientIdLoopback {
-  try {
-    parseOAuthLoopbackClientId(clientId)
-    return true
-  } catch {
-    return false
-  }
+export function isOAuthClientIdLoopback<T extends string>(
+  input: T,
+): input is T & OAuthClientIdLoopback {
+  return safeParseOAuthLoopbackClientId(input).success
 }
 
-export function assertOAuthLoopbackClientId(
-  clientId: string,
-): asserts clientId is OAuthClientIdLoopback {
-  void parseOAuthLoopbackClientId(clientId)
+export function asOAuthClientIdLoopback<T extends string>(input: T) {
+  assertOAuthLoopbackClientId(input)
+  return input
 }
 
-// @TODO should we turn this into a zod schema? (more coherent error with other
-// validation functions)
-export function parseOAuthLoopbackClientId(clientId: string): {
-  scope?: OAuthScope
-  redirect_uris?: [OAuthRedirectUri, ...OAuthRedirectUri[]]
-} {
-  if (!clientId.startsWith(PREFIX)) {
-    throw new TypeError(`Loopback ClientID must start with "${PREFIX}"`)
-  } else if (clientId.includes('#', PREFIX.length)) {
-    throw new TypeError('Loopback ClientID must not contain a hash component')
-  }
+export function parseOAuthLoopbackClientId(
+  input: string,
+): OAuthLoopbackClientIdParams {
+  const result = safeParseOAuthLoopbackClientId(input)
+  if (result.success) return result.value
 
-  const queryStringIdx =
-    clientId.length > PREFIX.length && clientId[PREFIX.length] === '/'
-      ? PREFIX.length + 1
-      : PREFIX.length
+  throw new TypeError(`Invalid loopback client ID: ${result.message}`)
+}
 
-  if (clientId.length === queryStringIdx) {
-    return {} // no query string to parse
+/**
+ * Similar to Zod's {@link SafeParseReturnType} but uses a simple "message"
+ * string instead of an "error" Error object.
+ */
+type LightParseReturnType<T> =
+  | { success: true; value: T }
+  | { success: false; message: string }
+
+export function safeParseOAuthLoopbackClientId(
+  input: string,
+): LightParseReturnType<OAuthLoopbackClientIdParams> {
+  // @NOTE Not using "new URL" to ensure input indeed matches the type
+  // OAuthClientIdLoopback
+
+  if (!input.startsWith(LOOPBACK_CLIENT_ID_ORIGIN)) {
+    return {
+      success: false,
+      message: `Value must start with "${LOOPBACK_CLIENT_ID_ORIGIN}"`,
+    }
   }
 
-  if (clientId[queryStringIdx] !== '?') {
-    throw new TypeError('Loopback ClientID must not contain a path component')
+  if (input.includes('#', LOOPBACK_CLIENT_ID_ORIGIN.length)) {
+    return {
+      success: false,
+      message: 'Value must not contain a hash component',
+    }
   }
 
-  const searchParams = new URLSearchParams(clientId.slice(queryStringIdx + 1))
+  // Since we don't allow a path component (except for a single "/") the query
+  // string starts after the origin (+ 1 if there is a "/")
+  const queryStringIdx =
+    input.length > LOOPBACK_CLIENT_ID_ORIGIN.length &&
+    input.charCodeAt(LOOPBACK_CLIENT_ID_ORIGIN.length) === 0x2f /* '/' */
+      ? LOOPBACK_CLIENT_ID_ORIGIN.length + 1
+      : LOOPBACK_CLIENT_ID_ORIGIN.length
 
-  for (const name of searchParams.keys()) {
-    if (name !== 'redirect_uri' && name !== 'scope') {
-      throw new TypeError(`Invalid query parameter "${name}" in client ID`)
+  // Since we determined the position of the query string based on the origin
+  // length (instead of looking for a "?"), we need to make sure the query
+  // string position (if any) indeed starts with a "?".
+  if (
+    input.length !== queryStringIdx &&
+    input.charCodeAt(queryStringIdx) !== 0x3f /* '?' */
+  ) {
+    return {
+      success: false,
+      message: 'Value must not contain a path component',
     }
   }
 
-  const scope = searchParams.get('scope') ?? undefined
-  if (scope != null) {
-    if (searchParams.getAll('scope').length > 1) {
-      throw new TypeError(
-        'Loopback ClientID must contain at most one scope query parameter',
-      )
-    } else if (!oauthScopeSchema.safeParse(scope).success) {
-      throw new TypeError('Invalid scope query parameter in client ID')
+  const queryString = input.slice(queryStringIdx + 1)
+  return safeParseOAuthLoopbackClientIdQueryString(queryString)
+}
+
+export function safeParseOAuthLoopbackClientIdQueryString(
+  input: string | Iterable<[key: string, value: string]>,
+): LightParseReturnType<OAuthLoopbackClientIdParams> {
+  // Parse query params
+  const params: OAuthLoopbackClientIdParams = {}
+
+  const it = typeof input === 'string' ? new URLSearchParams(input) : input
+  for (const [key, value] of it) {
+    if (key === 'scope') {
+      if ('scope' in params) {
+        return {
+          success: false,
+          message: 'Duplicate "scope" query parameter',
+        }
+      }
+
+      const res = oauthScopeSchema.safeParse(value)
+      if (!res.success) {
+        const reason = res.error.issues.map((i) => i.message).join(', ')
+        return {
+          success: false,
+          message: `Invalid "scope" query parameter: ${reason || 'Validation failed'}`,
+        }
+      }
+
+      params.scope = res.data
+    } else if (key === 'redirect_uri') {
+      const res = oauthLoopbackRedirectURISchema.safeParse(value)
+      if (!res.success) {
+        const reason = res.error.issues.map((i) => i.message).join(', ')
+        return {
+          success: false,
+          message: `Invalid "redirect_uri" query parameter: ${reason || 'Validation failed'}`,
+        }
+      }
+
+      if (params.redirect_uris == null) params.redirect_uris = [res.data]
+      else params.redirect_uris.push(res.data)
+    } else {
+      return {
+        success: false,
+        message: `Unexpected query parameter "${key}"`,
+      }
     }
   }
 
-  const redirect_uris = searchParams.has('redirect_uri')
-    ? (searchParams
-        .getAll('redirect_uri')
-        .map((value) => oauthLoopbackRedirectURISchema.parse(value)) as [
-        OAuthLoopbackRedirectURI,
-        ...OAuthLoopbackRedirectURI[],
-      ])
-    : undefined
-
   return {
-    scope,
-    redirect_uris,
+    success: true,
+    value: params,
   }
 }

package/src/oauth-scope.ts

@@ -1,15 +1,21 @@
 import { z } from 'zod'
 
+// scope       = scope-token *( SP scope-token )
+// scope-token = 1*( %x21 / %x23-5B / %x5D-7E )
+export const OAUTH_SCOPE_REGEXP =
+  /^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/
+
+export const isOAuthScope = (input: string): boolean =>
+  OAUTH_SCOPE_REGEXP.test(input)
+
 /**
- * A space separated list of most non-control ASCII characters except backslash
- * and double quote.
+ * A (single) space separated list of non empty printable ASCII char string
+ * (except backslash and double quote).
  *
  * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11#section-1.4.1}
  */
-export const oauthScopeSchema = z
-  .string()
-  // scope       = scope-token *( SP scope-token )
-  // scope-token = 1*( %x21 / %x23-5B / %x5D-7E )
-  .regex(/^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/)
+export const oauthScopeSchema = z.string().refine(isOAuthScope, {
+  message: 'Invalid OAuth scope',
+})
 
 export type OAuthScope = z.infer<typeof oauthScopeSchema>

package/src/uri.ts

@@ -3,7 +3,7 @@ import { isHostnameIP, isLoopbackHost } from './util.js'
 
 const canParseUrl =
   // eslint-disable-next-line n/no-unsupported-features/node-builtins
-  URL.canParse ??
+  URL.canParse?.bind(URL) ??
   // URL.canParse is not available in Node.js < 18.7.0
   ((urlStr: string): boolean => {
     try {

package/src/util.ts

@@ -86,3 +86,63 @@ export const numberPreprocess = (val: unknown): unknown => {
   }
   return val
 }
+
+/**
+ * Returns true if the two arrays contain the same elements, regardless of order
+ * or duplicates.
+ */
+export function arrayEquivalent<T>(a: readonly T[], b: readonly T[]) {
+  if (a === b) return true
+  return a.every(includedIn, b) && b.every(includedIn, a)
+}
+
+export function includedIn<T>(this: readonly T[], item: T) {
+  return this.includes(item)
+}
+
+export function asArray<T>(
+  value: Iterable<T> | undefined,
+): undefined | readonly T[] {
+  if (value == null) return undefined
+  if (Array.isArray(value)) return value // already a (possibly readonly) array
+  return Array.from(value)
+}
+
+export type SpaceSeparatedValue<Value extends string> =
+  `${'' | `${string} `}${Value}${'' | ` ${string}`}`
+
+export const isSpaceSeparatedValue = <Value extends string>(
+  value: Value,
+  input: string,
+): 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.charCodeAt(idx - 1) === 32) &&
+      // at end or followed by space
+      (idxEnd === inputLength || input.charCodeAt(idxEnd) === 32)
+    ) {
+      return true
+    }
+
+    idx = input.indexOf(value, idxEnd + 1)
+  }
+
+  return false
+}

package/tsconfig.build.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/atproto-loopback-client-metadata.ts","./src/constants.ts","./src/index.ts","./src/oauth-access-token.ts","./src/oauth-authorization-code-grant-token-request.ts","./src/oauth-authorization-details.ts","./src/oauth-authorization-request-jar.ts","./src/oauth-authorization-request-par.ts","./src/oauth-authorization-request-parameters.ts","./src/oauth-authorization-request-query.ts","./src/oauth-authorization-request-uri.ts","./src/oauth-authorization-response-error.ts","./src/oauth-authorization-server-metadata.ts","./src/oauth-client-credentials-grant-token-request.ts","./src/oauth-client-credentials.ts","./src/oauth-client-id-discoverable.ts","./src/oauth-client-id-loopback.ts","./src/oauth-client-id.ts","./src/oauth-client-metadata.ts","./src/oauth-code-challenge-method.ts","./src/oauth-endpoint-auth-method.ts","./src/oauth-endpoint-name.ts","./src/oauth-grant-type.ts","./src/oauth-introspection-response.ts","./src/oauth-issuer-identifier.ts","./src/oauth-par-response.ts","./src/oauth-password-grant-token-request.ts","./src/oauth-protected-resource-metadata.ts","./src/oauth-redirect-uri.ts","./src/oauth-refresh-token-grant-token-request.ts","./src/oauth-refresh-token.ts","./src/oauth-request-uri.ts","./src/oauth-response-mode.ts","./src/oauth-response-type.ts","./src/oauth-scope.ts","./src/oauth-token-identification.ts","./src/oauth-token-request.ts","./src/oauth-token-response.ts","./src/oauth-token-type.ts","./src/oidc-authorization-error-response.ts","./src/oidc-claims-parameter.ts","./src/oidc-claims-properties.ts","./src/oidc-entity-type.ts","./src/oidc-userinfo.ts","./src/uri.ts","./src/util.ts"],"version":"5.8.2"}
+{"root":["./src/atproto-loopback-client-id.ts","./src/atproto-loopback-client-metadata.ts","./src/atproto-loopback-client-redirect-uris.ts","./src/atproto-oauth-scope.ts","./src/atproto-oauth-token-response.ts","./src/constants.ts","./src/index.ts","./src/oauth-access-token.ts","./src/oauth-authorization-code-grant-token-request.ts","./src/oauth-authorization-details.ts","./src/oauth-authorization-request-jar.ts","./src/oauth-authorization-request-par.ts","./src/oauth-authorization-request-parameters.ts","./src/oauth-authorization-request-query.ts","./src/oauth-authorization-request-uri.ts","./src/oauth-authorization-response-error.ts","./src/oauth-authorization-server-metadata.ts","./src/oauth-client-credentials-grant-token-request.ts","./src/oauth-client-credentials.ts","./src/oauth-client-id-discoverable.ts","./src/oauth-client-id-loopback.ts","./src/oauth-client-id.ts","./src/oauth-client-metadata.ts","./src/oauth-code-challenge-method.ts","./src/oauth-endpoint-auth-method.ts","./src/oauth-endpoint-name.ts","./src/oauth-grant-type.ts","./src/oauth-introspection-response.ts","./src/oauth-issuer-identifier.ts","./src/oauth-par-response.ts","./src/oauth-password-grant-token-request.ts","./src/oauth-protected-resource-metadata.ts","./src/oauth-redirect-uri.ts","./src/oauth-refresh-token-grant-token-request.ts","./src/oauth-refresh-token.ts","./src/oauth-request-uri.ts","./src/oauth-response-mode.ts","./src/oauth-response-type.ts","./src/oauth-scope.ts","./src/oauth-token-identification.ts","./src/oauth-token-request.ts","./src/oauth-token-response.ts","./src/oauth-token-type.ts","./src/oidc-authorization-error-response.ts","./src/oidc-claims-parameter.ts","./src/oidc-claims-properties.ts","./src/oidc-entity-type.ts","./src/oidc-userinfo.ts","./src/uri.ts","./src/util.ts"],"version":"5.8.2"}