@atproto/oauth-types 0.2.0 → 0.2.2

package/src/oauth-issuer-identifier.ts

@@ -1,9 +1,8 @@
 import { z } from 'zod'
-import { safeUrl } from './util.js'
+import { webUriSchema } from './uri.js'
 
-export const oauthIssuerIdentifierSchema = z
-  .string()
-  .superRefine((value, ctx): value is `${'http' | 'https'}://${string}` => {
+export const oauthIssuerIdentifierSchema = webUriSchema.superRefine(
+  (value, ctx) => {
     // Validate the issuer (MIX-UP attacks)
 
     if (value.endsWith('/')) {
@@ -14,22 +13,7 @@ export const oauthIssuerIdentifierSchema = z
       return false
     }
 
-    const url = safeUrl(value)
-    if (!url) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: 'Invalid url',
-      })
-      return false
-    }
-
-    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: `Invalid issuer URL protocol "${url.protocol}"`,
-      })
-      return false
-    }
+    const url = new URL(value)
 
     if (url.username || url.password) {
       ctx.addIssue({
@@ -57,6 +41,7 @@ export const oauthIssuerIdentifierSchema = z
     }
 
     return true
-  })
+  },
+)
 
 export type OAuthIssuerIdentifier = z.infer<typeof oauthIssuerIdentifierSchema>

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

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 
 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}
@@ -10,8 +11,17 @@ export const oauthProtectedResourceMetadataSchema = z.object({
    * REQUIRED. The protected resource's resource identifier, which is a URL that
    * uses the https scheme and has no query or fragment components. Using these
    * well-known resources is described in Section 3.
+   *
+   * @note This schema allows non https URLs for testing & development purposes.
+   * Make sure to validate the URL before using it in a production environment.
    */
-  resource: z.string().url(),
+  resource: webUriSchema
+    .refine((url) => !url.includes('?'), {
+      message: 'Resource URL must not contain query parameters',
+    })
+    .refine((url) => !url.includes('#'), {
+      message: 'Resource URL must not contain a fragment',
+    }),
 
   /**
    * OPTIONAL. JSON array containing a list of OAuth authorization server issuer
@@ -31,7 +41,7 @@ export const oauthProtectedResourceMetadataSchema = z.object({
    * available, a use (public key use) parameter value is REQUIRED for all keys
    * in the referenced JWK Set to indicate each key's intended usage.
    */
-  jwks_uri: z.string().url().optional(),
+  jwks_uri: webUriSchema.optional(),
 
   /**
    * RECOMMENDED. JSON array containing a list of the OAuth 2.0 [RFC6749] scope
@@ -64,20 +74,20 @@ export const oauthProtectedResourceMetadataSchema = z.object({
    * OPTIONAL. URL of a page containing human-readable information that
    * developers might want or need to know when using the protected resource
    */
-  resource_documentation: z.string().url().optional(),
+  resource_documentation: webUriSchema.optional(),
 
   /**
    * OPTIONAL. URL that the protected resource provides to read about the
    * protected resource's requirements on how the client can use the data
    * provided by the protected resource
    */
-  resource_policy_uri: z.string().url().optional(),
+  resource_policy_uri: webUriSchema.optional(),
 
   /**
    * OPTIONAL. URL that the protected resource provides to read about the
    * protected resource's terms of service
    */
-  resource_tos_uri: z.string().url().optional(),
+  resource_tos_uri: webUriSchema.optional(),
 })
 
 export type OAuthProtectedResourceMetadata = z.infer<

package/src/oauth-redirect-uri.ts

@@ -0,0 +1,56 @@
+import { TypeOf, z, ZodIssueCode } from 'zod'
+import {
+  httpsUriSchema,
+  LoopbackUri,
+  loopbackUriSchema,
+  privateUseUriSchema,
+} from './uri.js'
+
+export const oauthLoopbackRedirectURISchema = 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:
+          'Use of "localhost" hostname is not allowed (RFC 8252), use a loopback IP such as "127.0.0.1" instead',
+      })
+      return false
+    }
+
+    return true
+  },
+)
+export type OAuthLoopbackRedirectURI = TypeOf<
+  typeof oauthLoopbackRedirectURISchema
+>
+
+export const oauthHttpsRedirectURISchema = httpsUriSchema
+export type OAuthHttpsRedirectURI = TypeOf<typeof oauthHttpsRedirectURISchema>
+
+export const oauthPrivateUseRedirectURISchema = privateUseUriSchema
+export type OAuthPrivateUseRedirectURI = TypeOf<
+  typeof oauthPrivateUseRedirectURISchema
+>
+
+export const oauthRedirectUriSchema = z.union(
+  [
+    oauthLoopbackRedirectURISchema,
+    oauthHttpsRedirectURISchema,
+    oauthPrivateUseRedirectURISchema,
+  ],
+  {
+    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/uri.ts

@@ -0,0 +1,171 @@
+import { TypeOf, z, ZodIssueCode } from 'zod'
+import { isHostnameIP, isLoopbackHost } from './util.js'
+
+/**
+ * Valid, but potentially dangerous URL (`data:`, `file:`, `javascript:`, etc.).
+ *
+ * Any value that matches this schema is safe to parse using `new URL()`.
+ */
+export const dangerousUriSchema = z
+  .string()
+  .refine(
+    (data): data is `${string}:${string}` =>
+      data.includes(':') && URL.canParse(data),
+    {
+      message: 'Invalid URL',
+    },
+  )
+
+/**
+ * Valid, but potentially dangerous URL (`data:`, `file:`, `javascript:`, etc.).
+ */
+export type DangerousUrl = TypeOf<typeof dangerousUriSchema>
+
+export const loopbackUriSchema = dangerousUriSchema.superRefine(
+  (
+    value,
+    ctx,
+  ): value is
+    | `http://[::1]${string}`
+    | `http://localhost${'' | `${':' | '/' | '?' | '#'}${string}`}`
+    | `http://127.0.0.1${'' | `${':' | '/' | '?' | '#'}${string}`}` => {
+    // Loopback url must use the "http:" protocol
+    if (!value.startsWith('http://')) {
+      ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message: 'URL must use the "http:" protocol',
+      })
+      return false
+    }
+
+    const url = new URL(value)
+
+    if (!isLoopbackHost(url.hostname)) {
+      ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message: 'URL must use "localhost", "127.0.0.1" or "[::1]" as hostname',
+      })
+      return false
+    }
+
+    return true
+  },
+)
+
+export type LoopbackUri = TypeOf<typeof loopbackUriSchema>
+
+export const httpsUriSchema = dangerousUriSchema.superRefine(
+  (value, ctx): value is `https://${string}` => {
+    if (!value.startsWith('https://')) {
+      ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message: 'URL must use the "https:" protocol',
+      })
+      return false
+    }
+
+    const url = new URL(value)
+
+    // Disallow loopback URLs with the `https:` protocol
+    if (isLoopbackHost(url.hostname)) {
+      ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message: 'https: URL must not use a loopback host',
+      })
+      return false
+    }
+
+    if (isHostnameIP(url.hostname)) {
+      // Hostname is an IP address
+    } else {
+      // Hostname is a domain name
+      if (!url.hostname.includes('.')) {
+        // we don't depend on PSL here, so we only check for a dot
+        ctx.addIssue({
+          code: ZodIssueCode.custom,
+          message: 'Domain name must contain at least two segments',
+        })
+        return false
+      }
+
+      if (url.hostname.endsWith('.local')) {
+        ctx.addIssue({
+          code: ZodIssueCode.custom,
+          message: 'Domain name must not end with ".local"',
+        })
+        return false
+      }
+    }
+
+    return true
+  },
+)
+
+export type HttpsUri = TypeOf<typeof httpsUriSchema>
+
+export const webUriSchema = z
+  .string()
+  .superRefine((value, ctx): value is LoopbackUri | HttpsUri => {
+    // discriminated union of `loopbackUriSchema` and `httpsUriSchema`
+    if (value.startsWith('http://')) {
+      const result = loopbackUriSchema.safeParse(value)
+      if (!result.success) result.error.issues.forEach(ctx.addIssue, ctx)
+      return result.success
+    }
+
+    if (value.startsWith('https://')) {
+      const result = httpsUriSchema.safeParse(value)
+      if (!result.success) result.error.issues.forEach(ctx.addIssue, ctx)
+      return result.success
+    }
+
+    ctx.addIssue({
+      code: ZodIssueCode.custom,
+      message: 'URL must use the "http:" or "https:" protocol',
+    })
+    return false
+  })
+
+export type WebUri = TypeOf<typeof webUriSchema>
+
+export const privateUseUriSchema = dangerousUriSchema.superRefine(
+  (value, ctx): value is `${string}.${string}:/${string}` => {
+    const dotIdx = value.indexOf('.')
+    const colonIdx = value.indexOf(':')
+
+    // Optimization: avoid parsing the URL if the protocol does not contain a "."
+    if (dotIdx === -1 || colonIdx === -1 || dotIdx > colonIdx) {
+      ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message:
+          'Private-use URI scheme requires a "." as part of the protocol',
+      })
+      return false
+    }
+
+    const url = new URL(value)
+
+    // Should be covered by the check before, but let's be extra sure
+    if (!url.protocol.includes('.')) {
+      ctx.addIssue({
+        code: ZodIssueCode.custom,
+        message: 'Invalid private-use URI scheme',
+      })
+      return false
+    }
+
+    if (url.hostname) {
+      // https://datatracker.ietf.org/doc/html/rfc8252#section-7.1
+      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)',
+      })
+      return false
+    }
+
+    return true
+  },
+)
+
+export type PrivateUseUri = TypeOf<typeof privateUseUriSchema>

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-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-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-claims-parameter.ts","./src/oidc-claims-properties.ts","./src/oidc-entity-type.ts","./src/util.ts"],"version":"5.6.3"}
+{"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-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-claims-parameter.ts","./src/oidc-claims-properties.ts","./src/oidc-entity-type.ts","./src/uri.ts","./src/util.ts"],"version":"5.6.3"}