@atproto/oauth-types 0.4.1 → 0.5.0

package/src/oauth-protected-resource-metadata.ts

@@ -3,7 +3,7 @@ import { oauthIssuerIdentifierSchema } from './oauth-issuer-identifier.js'
 import { webUriSchema } from './uri.js'
 
 /**
- * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-05#name-protected-resource-metadata-r}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-3.2}
  */
 export const oauthProtectedResourceMetadataSchema = z.object({
   /**

package/src/oauth-redirect-uri.ts

@@ -6,19 +6,23 @@ import {
   privateUseUriSchema,
 } from './uri.js'
 
-export const oauthLoopbackRedirectURISchema = loopbackUriSchema.superRefine(
+/**
+ * This is a {@link loopbackUriSchema} with the additional restriction that
+ * the hostname `localhost` is not allowed.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc8252#section-8.3 Loopback Redirect Considerations} RFC8252
+ *
+ * > While redirect URIs using localhost (i.e.,
+ * > "http://localhost:{port}/{path}") function similarly to loopback IP
+ * > redirects described in Section 7.3, the use of localhost is NOT
+ * > RECOMMENDED. Specifying a redirect URI with the loopback IP literal rather
+ * > than localhost avoids inadvertently listening on network interfaces other
+ * > than the loopback interface.  It is also less susceptible to client-side
+ * > firewalls and misconfigured host name resolution on the user's device.
+ */
+export const loopbackRedirectURISchema = loopbackUriSchema.superRefine(
   (value, ctx): value is Exclude<LoopbackUri, `http://localhost${string}`> => {
     if (value.startsWith('http://localhost')) {
-      // https://datatracker.ietf.org/doc/html/rfc8252#section-8.3
-      //
-      // > While redirect URIs using localhost (i.e.,
-      // > "http://localhost:{port}/{path}") function similarly to loopback IP
-      // > redirects described in Section 7.3, the use of localhost is NOT
-      // > RECOMMENDED.  Specifying a redirect URI with the loopback IP literal
-      // > rather than localhost avoids inadvertently listening on network
-      // > interfaces other than the loopback interface.  It is also less
-      // > susceptible to client-side firewalls and misconfigured host name
-      // > resolution on the user's device.
       ctx.addIssue({
         code: ZodIssueCode.custom,
         message:
@@ -30,27 +34,17 @@ export const oauthLoopbackRedirectURISchema = loopbackUriSchema.superRefine(
     return true
   },
 )
-export type OAuthLoopbackRedirectURI = TypeOf<
-  typeof oauthLoopbackRedirectURISchema
->
-
-export const oauthHttpsRedirectURISchema = httpsUriSchema
-export type OAuthHttpsRedirectURI = TypeOf<typeof oauthHttpsRedirectURISchema>
+export type LoopbackRedirectURI = TypeOf<typeof loopbackRedirectURISchema>
 
-export const oauthPrivateUseRedirectURISchema = privateUseUriSchema
-export type OAuthPrivateUseRedirectURI = TypeOf<
-  typeof oauthPrivateUseRedirectURISchema
+export const oauthLoopbackClientRedirectUriSchema = loopbackRedirectURISchema
+export type OAuthLoopbackRedirectURI = TypeOf<
+  typeof oauthLoopbackClientRedirectUriSchema
 >
 
 export const oauthRedirectUriSchema = z.union(
-  [
-    oauthLoopbackRedirectURISchema,
-    oauthHttpsRedirectURISchema,
-    oauthPrivateUseRedirectURISchema,
-  ],
+  [loopbackRedirectURISchema, httpsUriSchema, privateUseUriSchema],
   {
     message: `URL must use the "https:" or "http:" protocol, or a private-use URI scheme (RFC 8252)`,
   },
 )
-
 export type OAuthRedirectUri = TypeOf<typeof oauthRedirectUriSchema>

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

@@ -1,18 +1,10 @@
 import { TypeOf, ZodIssueCode, z } from 'zod'
-import { isHostnameIP, isLoopbackHost } from './util.js'
-
-const canParseUrl =
-  // eslint-disable-next-line n/no-unsupported-features/node-builtins
-  URL.canParse ??
-  // URL.canParse is not available in Node.js < 18.7.0
-  ((urlStr: string): boolean => {
-    try {
-      new URL(urlStr)
-      return true
-    } catch {
-      return false
-    }
-  })
+import {
+  canParseUrl,
+  isHostnameIP,
+  isLocalHostname,
+  isLoopbackHost,
+} from './util.js'
 
 /**
  * Valid, but potentially dangerous URL (`data:`, `file:`, `javascript:`, etc.).
@@ -167,12 +159,56 @@ export const privateUseUriSchema = dangerousUriSchema.superRefine(
       return false
     }
 
-    if (url.hostname) {
-      // https://datatracker.ietf.org/doc/html/rfc8252#section-7.1
+    // https://datatracker.ietf.org/doc/html/rfc8252#section-7.1
+    //
+    // > When choosing a URI scheme to associate with the app, apps MUST use a
+    // > URI scheme based on a domain name under their control, expressed in
+    // > reverse order
+    //
+    // https://datatracker.ietf.org/doc/html/rfc8252#section-8.4
+    //
+    // > In addition to the collision-resistant properties, requiring a URI
+    // > scheme based on a domain name that is under the control of the app can
+    // > help to prove ownership in the event of a dispute where two apps claim
+    // > the same private-use URI scheme (where one app is acting maliciously).
+    //
+    // We can't check for ownership here (as there is no concept of proven
+    // ownership in a generic validation logic), besides excluding local domains
+    // as they can't be controlled/owned by the app.
+    //
+    // https://atproto.com/specs/oauth
+    //
+    // > Any custom scheme must match the `client_id` hostname in reverse-domain
+    // > order.
+    //
+    // This ATPROTO specific requirement cannot be enforced here, (as there is
+    // no concept of `client_id` in this context).
+
+    const uriScheme = url.protocol.slice(0, -1) // remove trailing ":"
+    const urlDomain = uriScheme.split('.').reverse().join('.')
+
+    if (isLocalHostname(urlDomain)) {
       ctx.addIssue({
         code: ZodIssueCode.custom,
-        message:
-          'Private-use URI schemes must not include a hostname (only one "/" is allowed after the protocol, as per RFC 8252)',
+        message: `Private-use URI Scheme redirect URI must not be a local hostname`,
+      })
+    }
+
+    // https://datatracker.ietf.org/doc/html/rfc8252#section-7.1
+    //
+    // > Following the requirements of Section 3.2 of [RFC3986], as there is no
+    // > naming authority for private-use URI scheme redirects, only a single
+    // > slash ("/") appears after the scheme component.
+    if (
+      url.href.startsWith(`${url.protocol}//`) ||
+      url.username ||
+      url.password ||
+      url.hostname ||
+      url.port
+    ) {
+      ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message: `Private-Use URI Scheme must be in the form ${url.protocol}/<path> (as per RFC 8252)`,
       })
       return false
     }

package/src/util.ts

@@ -1,3 +1,16 @@
+export const canParseUrl =
+  // eslint-disable-next-line n/no-unsupported-features/node-builtins
+  URL.canParse?.bind(URL) ??
+  // URL.canParse is not available in Node.js < 18.7.0
+  ((urlStr: string): boolean => {
+    try {
+      new URL(urlStr)
+      return true
+    } catch {
+      return false
+    }
+  })
+
 export function isHostnameIP(hostname: string) {
   // IPv4
   if (hostname.match(/^\d+\.\d+\.\d+\.\d+$/)) return true
@@ -14,9 +27,18 @@ export function isLoopbackHost(host: unknown): host is LoopbackHost {
   return host === 'localhost' || host === '127.0.0.1' || host === '[::1]'
 }
 
-export function isLoopbackUrl(input: URL | string): boolean {
-  const url = typeof input === 'string' ? new URL(input) : input
-  return isLoopbackHost(url.hostname)
+export function isLocalHostname(hostname: string): boolean {
+  const parts = hostname.split('.')
+  if (parts.length < 2) return true
+
+  const tld = parts.at(-1)!.toLowerCase()
+  return (
+    tld === 'test' ||
+    tld === 'local' ||
+    tld === 'localhost' ||
+    tld === 'invalid' ||
+    tld === 'example'
+  )
 }
 
 export function safeUrl(input: URL | string): URL | null {
@@ -86,3 +108,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"}