@atproto/oauth-types 0.1.5 → 0.2.1

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

@@ -1,11 +1,33 @@
-import { OAuthClientId } from './oauth-client-id.js'
+import { TypeOf, ZodIssueCode } from 'zod'
+import { oauthClientIdSchema } from './oauth-client-id.js'
+import {
+  OAuthLoopbackRedirectURI,
+  oauthLoopbackRedirectURISchema,
+  OAuthRedirectUri,
+} from './oauth-redirect-uri.js'
 import { OAuthScope, oauthScopeSchema } from './oauth-scope.js'
-import { isLoopbackHost, safeUrl } from './util.js'
 
-const OAUTH_CLIENT_ID_LOOPBACK_URL = 'http://localhost'
+const PREFIX = 'http://localhost'
 
-export type OAuthClientIdLoopback = OAuthClientId &
-  `${typeof OAUTH_CLIENT_ID_LOOPBACK_URL}${'' | '/'}${'' | `?${string}`}`
+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
+    }
+  },
+)
+
+export type OAuthClientIdLoopback = TypeOf<typeof oauthClientIdLoopbackSchema>
 
 export function isOAuthClientIdLoopback(
   clientId: string,
@@ -28,21 +50,18 @@ export function assertOAuthLoopbackClientId(
 // validation functions)
 export function parseOAuthLoopbackClientId(clientId: string): {
   scope?: OAuthScope
-  redirect_uris?: [string, ...string[]]
+  redirect_uris?: [OAuthRedirectUri, ...OAuthRedirectUri[]]
 } {
-  if (!clientId.startsWith(OAUTH_CLIENT_ID_LOOPBACK_URL)) {
-    throw new TypeError(
-      `Loopback ClientID must start with "${OAUTH_CLIENT_ID_LOOPBACK_URL}"`,
-    )
-  } else if (clientId.includes('#', OAUTH_CLIENT_ID_LOOPBACK_URL.length)) {
+  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')
   }
 
   const queryStringIdx =
-    clientId.length > OAUTH_CLIENT_ID_LOOPBACK_URL.length &&
-    clientId[OAUTH_CLIENT_ID_LOOPBACK_URL.length] === '/'
-      ? OAUTH_CLIENT_ID_LOOPBACK_URL.length + 1
-      : OAUTH_CLIENT_ID_LOOPBACK_URL.length
+    clientId.length > PREFIX.length && clientId[PREFIX.length] === '/'
+      ? PREFIX.length + 1
+      : PREFIX.length
 
   if (clientId.length === queryStringIdx) {
     return {} // no query string to parse
@@ -72,33 +91,14 @@ export function parseOAuthLoopbackClientId(clientId: string): {
   }
 
   const redirect_uris = searchParams.has('redirect_uri')
-    ? (searchParams.getAll('redirect_uri') as [string, ...string[]])
+    ? (searchParams
+        .getAll('redirect_uri')
+        .map((value) => oauthLoopbackRedirectURISchema.parse(value)) as [
+        OAuthLoopbackRedirectURI,
+        ...OAuthLoopbackRedirectURI[],
+      ])
     : undefined
 
-  if (redirect_uris) {
-    for (const uri of redirect_uris) {
-      const url = safeUrl(uri)
-      if (!url) {
-        throw new TypeError(`Invalid redirect_uri in client ID: ${uri}`)
-      }
-      if (url.protocol !== 'http:') {
-        throw new TypeError(
-          `Loopback ClientID must use "http:" redirect_uri's (got ${uri})`,
-        )
-      }
-      if (url.hostname === 'localhost') {
-        throw new TypeError(
-          `Loopback ClientID must not use "localhost" as redirect_uri hostname (got ${uri})`,
-        )
-      }
-      if (!isLoopbackHost(url.hostname)) {
-        throw new TypeError(
-          `Loopback ClientID must use loopback addresses as redirect_uri's (got ${uri})`,
-        )
-      }
-    }
-  }
-
   return {
     scope,
     redirect_uris,

package/src/oauth-client-metadata.ts

@@ -4,13 +4,23 @@ import { z } from 'zod'
 import { oauthClientIdSchema } from './oauth-client-id.js'
 import { oauthEndpointAuthMethod } from './oauth-endpoint-auth-method.js'
 import { oauthGrantTypeSchema } from './oauth-grant-type.js'
+import { oauthRedirectUriSchema } from './oauth-redirect-uri.js'
 import { oauthResponseTypeSchema } from './oauth-response-type.js'
 import { oauthScopeSchema } from './oauth-scope.js'
+import { webUriSchema } from './uri.js'
 
-// https://openid.net/specs/openid-connect-registration-1_0.html
-// https://datatracker.ietf.org/doc/html/rfc7591
+/**
+ * @see {@link https://openid.net/specs/openid-connect-registration-1_0.html}
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7591}
+ * @note we do not enforce https: scheme in URIs to support development
+ * environments. Make sure to validate the URIs before using it in a production
+ * environment.
+ */
 export const oauthClientMetadataSchema = z.object({
-  redirect_uris: z.array(z.string().url()).nonempty(),
+  /**
+   * @note redirect_uris require additional validation
+   */
+  redirect_uris: z.array(oauthRedirectUriSchema).nonempty(),
   response_types: z
     .array(oauthResponseTypeSchema)
     .nonempty()
@@ -30,7 +40,7 @@ export const oauthClientMetadataSchema = z.object({
   token_endpoint_auth_signing_alg: z.string().optional(),
   userinfo_signed_response_alg: z.string().optional(),
   userinfo_encrypted_response_alg: z.string().optional(),
-  jwks_uri: z.string().url().optional(),
+  jwks_uri: webUriSchema.optional(),
   jwks: jwksPubSchema.optional(),
   application_type: z.enum(['web', 'native']).default('web').optional(), // default, per spec, is "web"
   subject_type: z.enum(['public', 'pairwise']).default('public').optional(),
@@ -41,10 +51,10 @@ export const oauthClientMetadataSchema = z.object({
   authorization_encrypted_response_alg: z.string().optional(),
   client_id: oauthClientIdSchema.optional(),
   client_name: z.string().optional(),
-  client_uri: z.string().url().optional(),
-  policy_uri: z.string().url().optional(),
-  tos_uri: z.string().url().optional(),
-  logo_uri: z.string().url().optional(),
+  client_uri: webUriSchema.optional(),
+  policy_uri: webUriSchema.optional(),
+  tos_uri: webUriSchema.optional(),
+  logo_uri: webUriSchema.optional(), // TODO: allow data: uri ?
 
   /**
    * Default Maximum Authentication Age. Specifies that the End-User MUST be

package/src/oauth-issuer-identifier.ts

@@ -1,10 +1,8 @@
 import { z } from 'zod'
-import { ALLOW_UNSECURE_ORIGINS } from './constants.js'
-import { safeUrl } from './util.js'
+import { webUriSchema } from './uri.js'
 
-export const oauthIssuerIdentifierSchema = z
-  .string()
-  .superRefine((value, ctx) => {
+export const oauthIssuerIdentifierSchema = webUriSchema.superRefine(
+  (value, ctx) => {
     // Validate the issuer (MIX-UP attacks)
 
     if (value.endsWith('/')) {
@@ -12,32 +10,17 @@ export const oauthIssuerIdentifierSchema = z
         code: z.ZodIssueCode.custom,
         message: 'Issuer URL must not end with a slash',
       })
+      return false
     }
 
-    const url = safeUrl(value)
-    if (!url) {
-      return ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: 'Invalid url',
-      })
-    }
-
-    if (url.protocol !== 'https:') {
-      if (ALLOW_UNSECURE_ORIGINS && url.protocol === 'http:') {
-        // We'll allow HTTP in development mode
-      } else {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: 'Issuer must be an HTTPS URL',
-        })
-      }
-    }
+    const url = new URL(value)
 
     if (url.username || url.password) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
         message: 'Issuer URL must not contain a username or password',
       })
+      return false
     }
 
     if (url.hash || url.search) {
@@ -45,6 +28,7 @@ export const oauthIssuerIdentifierSchema = z
         code: z.ZodIssueCode.custom,
         message: 'Issuer URL must not contain a query or fragment',
       })
+      return false
     }
 
     const canonicalValue = url.pathname === '/' ? url.origin : url.href
@@ -53,5 +37,11 @@ export const oauthIssuerIdentifierSchema = z
         code: z.ZodIssueCode.custom,
         message: 'Issuer URL must be in the canonical form',
       })
+      return false
     }
-  })
+
+    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/oauth-refresh-token-grant-token-request.ts

@@ -1,11 +1,9 @@
 import { z } from 'zod'
-import { oauthClientIdSchema } from './oauth-client-id.js'
 import { oauthRefreshTokenSchema } from './oauth-refresh-token.js'
 
 export const oauthRefreshTokenGrantTokenRequestSchema = z.object({
   grant_type: z.literal('refresh_token'),
   refresh_token: oauthRefreshTokenSchema,
-  client_id: oauthClientIdSchema,
 })
 
 export type OAuthRefreshTokenGrantTokenRequest = z.infer<

package/src/oauth-token-response.ts

@@ -9,13 +9,15 @@ import { oauthTokenTypeSchema } from './oauth-token-type.js'
  */
 export const oauthTokenResponseSchema = z
   .object({
+    // https://www.rfc-editor.org/rfc/rfc6749.html#section-5.1
     access_token: z.string(),
     token_type: oauthTokenTypeSchema,
-    issuer: z.string().url().optional(),
     scope: z.string().optional(),
-    id_token: signedJwtSchema.optional(),
     refresh_token: z.string().optional(),
     expires_in: z.number().optional(),
+    // https://openid.net/specs/openid-connect-core-1_0.html#TokenResponse
+    id_token: signedJwtSchema.optional(),
+    // https://datatracker.ietf.org/doc/html/rfc9396#name-enriched-authorization-deta
     authorization_details: oauthAuthorizationDetailsSchema.optional(),
   })
   // https://www.rfc-editor.org/rfc/rfc6749.html#section-5.1

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

@@ -0,0 +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-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"}