@atproto/oauth-types 0.2.0 → 0.2.1

package/dist/uri.d.ts

@@ -0,0 +1,20 @@
+import { TypeOf, z } from 'zod';
+/**
+ * Valid, but potentially dangerous URL (`data:`, `file:`, `javascript:`, etc.).
+ *
+ * Any value that matches this schema is safe to parse using `new URL()`.
+ */
+export declare const dangerousUriSchema: z.ZodEffects<z.ZodString, `${string}:${string}`, string>;
+/**
+ * Valid, but potentially dangerous URL (`data:`, `file:`, `javascript:`, etc.).
+ */
+export type DangerousUrl = TypeOf<typeof dangerousUriSchema>;
+export declare const loopbackUriSchema: z.ZodEffects<z.ZodEffects<z.ZodString, `${string}:${string}`, string>, `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}`, string>;
+export type LoopbackUri = TypeOf<typeof loopbackUriSchema>;
+export declare const httpsUriSchema: z.ZodEffects<z.ZodEffects<z.ZodString, `${string}:${string}`, string>, `https://${string}`, string>;
+export type HttpsUri = TypeOf<typeof httpsUriSchema>;
+export declare const webUriSchema: z.ZodEffects<z.ZodString, `http://[::1]${string}` | "http://localhost" | `http://localhost#${string}` | `http://localhost?${string}` | `http://localhost/${string}` | `http://localhost:${string}` | "http://127.0.0.1" | `http://127.0.0.1#${string}` | `http://127.0.0.1?${string}` | `http://127.0.0.1/${string}` | `http://127.0.0.1:${string}` | `https://${string}`, string>;
+export type WebUri = TypeOf<typeof webUriSchema>;
+export declare const privateUseUriSchema: z.ZodEffects<z.ZodEffects<z.ZodString, `${string}:${string}`, string>, `${string}.${string}:/${string}`, string>;
+export type PrivateUseUri = TypeOf<typeof privateUseUriSchema>;
+//# sourceMappingURL=uri.d.ts.map

package/dist/uri.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri.d.ts","sourceRoot":"","sources":["../src/uri.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,CAAC,EAAgB,MAAM,KAAK,CAAA;AAG7C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,0DAQ5B,CAAA;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAE5D,eAAO,MAAM,iBAAiB,2YA6B7B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE1D,eAAO,MAAM,cAAc,qGA6C1B,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAA;AAEpD,eAAO,MAAM,YAAY,oXAqBrB,CAAA;AAEJ,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,YAAY,CAAC,CAAA;AAEhD,eAAO,MAAM,mBAAmB,kHAsC/B,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

package/dist/uri.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.privateUseUriSchema = exports.webUriSchema = exports.httpsUriSchema = exports.loopbackUriSchema = exports.dangerousUriSchema = void 0;
+const zod_1 = require("zod");
+const util_js_1 = require("./util.js");
+/**
+ * Valid, but potentially dangerous URL (`data:`, `file:`, `javascript:`, etc.).
+ *
+ * Any value that matches this schema is safe to parse using `new URL()`.
+ */
+exports.dangerousUriSchema = zod_1.z
+    .string()
+    .refine((data) => data.includes(':') && URL.canParse(data), {
+    message: 'Invalid URL',
+});
+exports.loopbackUriSchema = exports.dangerousUriSchema.superRefine((value, ctx) => {
+    // Loopback url must use the "http:" protocol
+    if (!value.startsWith('http://')) {
+        ctx.addIssue({
+            code: zod_1.ZodIssueCode.custom,
+            message: 'URL must use the "http:" protocol',
+        });
+        return false;
+    }
+    const url = new URL(value);
+    if (!(0, util_js_1.isLoopbackHost)(url.hostname)) {
+        ctx.addIssue({
+            code: zod_1.ZodIssueCode.custom,
+            message: 'URL must use "localhost", "127.0.0.1" or "[::1]" as hostname',
+        });
+        return false;
+    }
+    return true;
+});
+exports.httpsUriSchema = exports.dangerousUriSchema.superRefine((value, ctx) => {
+    if (!value.startsWith('https://')) {
+        ctx.addIssue({
+            code: zod_1.ZodIssueCode.custom,
+            message: 'URL must use the "https:" protocol',
+        });
+        return false;
+    }
+    const url = new URL(value);
+    // Disallow loopback URLs with the `https:` protocol
+    if ((0, util_js_1.isLoopbackHost)(url.hostname)) {
+        ctx.addIssue({
+            code: zod_1.ZodIssueCode.custom,
+            message: 'https: URL must not use a loopback host',
+        });
+        return false;
+    }
+    if ((0, util_js_1.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: zod_1.ZodIssueCode.custom,
+                message: 'Domain name must contain at least two segments',
+            });
+            return false;
+        }
+        if (url.hostname.endsWith('.local')) {
+            ctx.addIssue({
+                code: zod_1.ZodIssueCode.custom,
+                message: 'Domain name must not end with ".local"',
+            });
+            return false;
+        }
+    }
+    return true;
+});
+exports.webUriSchema = zod_1.z
+    .string()
+    .superRefine((value, ctx) => {
+    // discriminated union of `loopbackUriSchema` and `httpsUriSchema`
+    if (value.startsWith('http://')) {
+        const result = exports.loopbackUriSchema.safeParse(value);
+        if (!result.success)
+            result.error.issues.forEach(ctx.addIssue, ctx);
+        return result.success;
+    }
+    if (value.startsWith('https://')) {
+        const result = exports.httpsUriSchema.safeParse(value);
+        if (!result.success)
+            result.error.issues.forEach(ctx.addIssue, ctx);
+        return result.success;
+    }
+    ctx.addIssue({
+        code: zod_1.ZodIssueCode.custom,
+        message: 'URL must use the "http:" or "https:" protocol',
+    });
+    return false;
+});
+exports.privateUseUriSchema = exports.dangerousUriSchema.superRefine((value, ctx) => {
+    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: zod_1.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: zod_1.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: zod_1.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;
+});
+//# sourceMappingURL=uri.js.map

package/dist/uri.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri.js","sourceRoot":"","sources":["../src/uri.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/oauth-types",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "MIT",
   "description": "OAuth typing & validation library",
   "keywords": [

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

@@ -1,16 +1,21 @@
-import { parseOAuthLoopbackClientId } from './oauth-client-id-loopback.js'
+import {
+  OAuthClientIdLoopback,
+  parseOAuthLoopbackClientId,
+} from './oauth-client-id-loopback.js'
 import { OAuthClientMetadataInput } from './oauth-client-metadata.js'
 
 export function atprotoLoopbackClientMetadata(
   clientId: string,
-): OAuthClientMetadataInput {
+): OAuthClientMetadataInput & {
+  client_id: OAuthClientIdLoopback
+} {
   const {
     scope = 'atproto',
     redirect_uris = [`http://127.0.0.1/`, `http://[::1]/`],
   } = parseOAuthLoopbackClientId(clientId)
 
   return {
-    client_id: clientId,
+    client_id: clientId as OAuthClientIdLoopback,
     scope,
     redirect_uris,
     client_name: 'Loopback client',

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './constants.js'
+export * from './uri.js'
 export * from './util.js'
 
 export * from './atproto-loopback-client-metadata.js'
@@ -25,6 +26,7 @@ export * from './oauth-issuer-identifier.js'
 export * from './oauth-par-response.js'
 export * from './oauth-password-grant-token-request.js'
 export * from './oauth-protected-resource-metadata.js'
+export * from './oauth-redirect-uri.js'
 export * from './oauth-refresh-token-grant-token-request.js'
 export * from './oauth-refresh-token.js'
 export * from './oauth-request-uri.js'

package/src/oauth-authorization-code-grant-token-request.ts

@@ -1,9 +1,10 @@
 import { z } from 'zod'
+import { oauthRedirectUriSchema } from './oauth-redirect-uri.js'
 
 export const oauthAuthorizationCodeGrantTokenRequestSchema = z.object({
   grant_type: z.literal('authorization_code'),
   code: z.string().min(1),
-  redirect_uri: z.string().url(),
+  redirect_uri: oauthRedirectUriSchema,
   /** @see {@link https://datatracker.ietf.org/doc/html/rfc7636#section-4.1} */
   code_verifier: z
     .string()

package/src/oauth-authorization-details.ts

@@ -1,14 +1,34 @@
 import { z } from 'zod'
+import { dangerousUriSchema } from './uri.js'
 
 /**
  * @see {@link https://datatracker.ietf.org/doc/html/rfc9396#section-2 | RFC 9396, Section 2}
  */
 export const oauthAuthorizationDetailSchema = z.object({
   type: z.string(),
-  locations: z.array(z.string().url()).optional(),
+  /**
+   * An array of strings representing the location of the resource or RS. These
+   * strings are typically URIs identifying the location of the RS.
+   */
+  locations: z.array(dangerousUriSchema).optional(),
+  /**
+   * An array of strings representing the kinds of actions to be taken at the
+   * resource.
+   */
   actions: z.array(z.string()).optional(),
+  /**
+   * An array of strings representing the kinds of data being requested from the
+   * resource.
+   */
   datatypes: z.array(z.string()).optional(),
+  /**
+   * A string identifier indicating a specific resource available at the API.
+   */
   identifier: z.string().optional(),
+  /**
+   * An array of strings representing the types or levels of privilege being
+   * requested at the resource.
+   */
   privileges: z.array(z.string()).optional(),
 })
 

package/src/oauth-authorization-request-parameters.ts

@@ -4,6 +4,7 @@ import { z } from 'zod'
 import { oauthAuthorizationDetailsSchema } from './oauth-authorization-details.js'
 import { oauthClientIdSchema } from './oauth-client-id.js'
 import { oauthCodeChallengeMethodSchema } from './oauth-code-challenge-method.js'
+import { oauthRedirectUriSchema } from './oauth-redirect-uri.js'
 import { oauthResponseTypeSchema } from './oauth-response-type.js'
 import { oauthScopeSchema } from './oauth-scope.js'
 import { oidcClaimsParameterSchema } from './oidc-claims-parameter.js'
@@ -16,7 +17,7 @@ import { oidcEntityTypeSchema } from './oidc-entity-type.js'
 export const oauthAuthorizationRequestParametersSchema = z.object({
   client_id: oauthClientIdSchema,
   state: z.string().optional(),
-  redirect_uri: z.string().url().optional(),
+  redirect_uri: oauthRedirectUriSchema.optional(),
   scope: oauthScopeSchema.optional(),
   response_type: oauthResponseTypeSchema,
 

package/src/oauth-authorization-server-metadata.ts

@@ -2,9 +2,13 @@ import { z } from 'zod'
 
 import { oauthCodeChallengeMethodSchema } from './oauth-code-challenge-method.js'
 import { oauthIssuerIdentifierSchema } from './oauth-issuer-identifier.js'
+import { webUriSchema } from './uri.js'
 
 /**
  * @see {@link https://datatracker.ietf.org/doc/html/rfc8414}
+ * @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 oauthAuthorizationServerMetadataSchema = z.object({
   issuer: oauthIssuerIdentifierSchema,
@@ -37,31 +41,31 @@ export const oauthAuthorizationServerMetadataSchema = z.object({
     .array(z.string())
     .optional(),
 
-  jwks_uri: z.string().url().optional(),
+  jwks_uri: webUriSchema.optional(),
 
-  authorization_endpoint: z.string().url(), // .optional(),
+  authorization_endpoint: webUriSchema, // .optional(),
 
-  token_endpoint: z.string().url(), // .optional(),
+  token_endpoint: webUriSchema, // .optional(),
   token_endpoint_auth_methods_supported: z.array(z.string()).optional(),
   token_endpoint_auth_signing_alg_values_supported: z
     .array(z.string())
     .optional(),
 
-  revocation_endpoint: z.string().url().optional(),
-  introspection_endpoint: z.string().url().optional(),
-  pushed_authorization_request_endpoint: z.string().url().optional(),
+  revocation_endpoint: webUriSchema.optional(),
+  introspection_endpoint: webUriSchema.optional(),
+  pushed_authorization_request_endpoint: webUriSchema.optional(),
 
   require_pushed_authorization_requests: z.boolean().optional(),
 
-  userinfo_endpoint: z.string().url().optional(),
-  end_session_endpoint: z.string().url().optional(),
-  registration_endpoint: z.string().url().optional(),
+  userinfo_endpoint: webUriSchema.optional(),
+  end_session_endpoint: webUriSchema.optional(),
+  registration_endpoint: webUriSchema.optional(),
 
   // https://datatracker.ietf.org/doc/html/rfc9449#section-5.1
   dpop_signing_alg_values_supported: z.array(z.string()).optional(),
 
   // https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-05#section-4
-  protected_resources: z.array(z.string().url()).optional(),
+  protected_resources: z.array(webUriSchema).optional(),
 
   // https://drafts.aaronpk.com/draft-parecki-oauth-client-id-metadata-document/draft-parecki-oauth-client-id-metadata-document.html
   client_id_metadata_document_supported: z.boolean().optional(),

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

@@ -1,69 +1,87 @@
-import { OAuthClientId } from './oauth-client-id.js'
+import { TypeOf, z } from 'zod'
+import { oauthClientIdSchema } from './oauth-client-id.js'
+import { httpsUriSchema } from './uri.js'
 import { extractUrlPath, isHostnameIP } from './util.js'
 
 /**
  * @see {@link https://drafts.aaronpk.com/draft-parecki-oauth-client-id-metadata-document/draft-parecki-oauth-client-id-metadata-document.html}
  */
-export type OAuthClientIdDiscoverable = OAuthClientId & `https://${string}`
+export const oauthClientIdDiscoverableSchema = z
+  .intersection(oauthClientIdSchema, httpsUriSchema)
+  .superRefine((value, ctx): value is `https://${string}/${string}` => {
+    const url = new URL(value)
+
+    if (url.username || url.password) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'ClientID must not contain credentials',
+      })
+      return false
+    }
+
+    if (url.hash) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'ClientID must not contain a fragment',
+      })
+      return false
+    }
+
+    if (url.pathname === '/') {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          'ClientID must contain a path component (e.g. "/client-metadata.json")',
+      })
+      return false
+    }
+
+    if (url.pathname.endsWith('/')) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'ClientID path must not end with a trailing slash',
+      })
+      return false
+    }
+
+    if (isHostnameIP(url.hostname)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'ClientID hostname must not be an IP address',
+      })
+      return false
+    }
+
+    // URL constructor normalizes the URL, so we extract the path manually to
+    // avoid normalization, then compare it to the normalized path to ensure
+    // that the URL does not contain path traversal or other unexpected characters
+    if (extractUrlPath(value) !== url.pathname) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `ClientID must be in canonical form ("${url.href}", got "${value}")`,
+      })
+      return false
+    }
+
+    return true
+  })
+
+export type OAuthClientIdDiscoverable = TypeOf<
+  typeof oauthClientIdDiscoverableSchema
+>
 
 export function isOAuthClientIdDiscoverable(
   clientId: string,
 ): clientId is OAuthClientIdDiscoverable {
-  try {
-    parseOAuthDiscoverableClientId(clientId)
-    return true
-  } catch {
-    return false
-  }
+  return oauthClientIdDiscoverableSchema.safeParse(clientId).success
 }
 
 export function assertOAuthDiscoverableClientId(
   value: string,
 ): asserts value is OAuthClientIdDiscoverable {
-  void parseOAuthDiscoverableClientId(value)
+  void oauthClientIdDiscoverableSchema.parse(value)
 }
 
 export function parseOAuthDiscoverableClientId(clientId: string): URL {
-  const url = new URL(clientId)
-
-  if (url.protocol !== 'https:') {
-    throw new TypeError('ClientID must use the "https:" protocol')
-  }
-
-  if (url.username || url.password) {
-    throw new TypeError('ClientID must not contain credentials')
-  }
-
-  if (url.hash) {
-    throw new TypeError('ClientID must not contain a fragment')
-  }
-
-  if (url.hostname === 'localhost') {
-    throw new TypeError('ClientID hostname must not be "localhost"')
-  }
-
-  if (url.pathname === '/') {
-    throw new TypeError(
-      'ClientID must contain a path component (e.g. "/client-metadata.json")',
-    )
-  }
-
-  if (url.pathname.endsWith('/')) {
-    throw new TypeError('ClientID path must not end with a trailing slash')
-  }
-
-  if (isHostnameIP(url.hostname)) {
-    throw new TypeError('ClientID hostname must not be an IP address')
-  }
-
-  // URL constructor normalizes the URL, so we extract the path manually to
-  // avoid normalization, then compare it to the normalized path to ensure
-  // that the URL does not contain path traversal or other unexpected characters
-  if (extractUrlPath(clientId) !== url.pathname) {
-    throw new TypeError(
-      `ClientID must be in canonical form ("${url.href}", got "${clientId}")`,
-    )
-  }
-
-  return url
+  return new URL(oauthClientIdDiscoverableSchema.parse(clientId))
 }

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