refactor(ext/net): extract TLS key and certificate from interfaces (#23296)

Removes the certificate options from all the interfaces and replaces
them with a new `TlsCertifiedKeyOptions`. This allows us to centralize
the documentation for TLS key management for both client and server, and
will allow us to add key object support in the future.

Also adds an option `keyFormat` field to the cert/key that must be
omitted or set to `pem`. This will allow us to load other format keys in
the future `der`, `pfx`, etc.

In a future PR, we will add a way to load a certified key object, and we
will add another option to `TlsCertifiedKeyOptions` like so:

```ts
export interface TlsCertifiedKeyOptions =
    | TlsCertifiedKeyPem
    | TlsCertifiedKeyFromFile
    | TlsCertifiedKeyConnectTls
    | { key: Deno.CertifiedKey }
```

1 files changed, 107 insertions, 32 deletions

diff --git a/ext/net/lib.deno_net.d.ts b/ext/net/lib.deno_net.d.ts
index 597b3d348..4b88b154a 100644
--- a/ext/net/lib.deno_net.d.ts
+++ b/ext/net/lib.deno_net.d.ts
@@ -197,12 +197,50 @@ declare namespace Deno {
     options: UnixListenOptions & { transport: "unix" },
   ): UnixListener;
 
-  /** @category Network */
-  export interface ListenTlsOptions extends TcpListenOptions {
-    /** Server private key in PEM format */
-    key?: string;
-    /** Cert chain in PEM format */
-    cert?: string;
+  /** Provides TLS certified keys, ie: a key that has been certified by a trusted certificate authority.
+   * A certified key generally consists of a private key and certificate part.
+   *
+   * @category Network
+   */
+  export type TlsCertifiedKeyOptions =
+    | TlsCertifiedKeyPem
+    | TlsCertifiedKeyFromFile
+    | TlsCertifiedKeyConnectTls;
+
+  /**
+   * Provides certified key material from strings. The key material is provided in
+   * `PEM`-format (Privacy Enhanced Mail, https://www.rfc-editor.org/rfc/rfc1422) which can be identified by having
+   * `-----BEGIN-----` and `-----END-----` markers at the beginning and end of the strings. This type of key is not compatible
+   * with `DER`-format keys which are binary.
+   *
+   * Deno supports RSA, EC, and PKCS8-format keys.
+   *
+   * ```ts
+   * const key = {
+   *  key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
+   *  cert: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n" }
+   * };
+   * ```
+   *
+   * @category Network
+   */
+  export interface TlsCertifiedKeyPem {
+    /** The format of this key material, which must be PEM. */
+    keyFormat?: "pem";
+    /** Private key in `PEM` format. RSA, EC, and PKCS8-format keys are supported. */
+    key: string;
+    /** Certificate chain in `PEM` format. */
+    cert: string;
+  }
+
+  /**
+   * @deprecated This will be removed in Deno 2.0. See the
+   * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
+   * for migration instructions.
+   *
+   * @category Network
+   */
+  export interface TlsCertifiedKeyFromFile {
     /** Path to a file containing a PEM formatted CA certificate. Requires
      * `--allow-read`.
      *
@@ -211,16 +249,45 @@ declare namespace Deno {
      * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
      * for migration instructions.
      */
-    certFile?: string;
-    /** Server private key file. Requires `--allow-read`.
+    certFile: string;
+    /** Path to a file containing a private key file. Requires `--allow-read`.
      *
      * @tags allow-read
      * @deprecated This will be removed in Deno 2.0. See the
      * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
      * for migration instructions.
      */
-    keyFile?: string;
+    keyFile: string;
+  }
 
+  /**
+   * @deprecated This will be removed in Deno 2.0. See the
+   * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
+   * for migration instructions.
+   *
+   * @category Network
+   */
+  export interface TlsCertifiedKeyConnectTls {
+    /**
+     * Certificate chain in `PEM` format.
+     *
+     * @deprecated This will be removed in Deno 2.0. See the
+     * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
+     * for migration instructions.
+     */
+    certChain: string;
+    /**
+     * Private key in `PEM` format. RSA, EC, and PKCS8-format keys are supported.
+     *
+     * @deprecated This will be removed in Deno 2.0. See the
+     * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
+     * for migration instructions.
+     */
+    privateKey: string;
+  }
+
+  /** @category Network */
+  export interface ListenTlsOptions extends TcpListenOptions {
     transport?: "tcp";
 
     /** Application-Layer Protocol Negotiation (ALPN) protocols to announce to
@@ -246,7 +313,9 @@ declare namespace Deno {
    * @tags allow-net
    * @category Network
    */
-  export function listenTls(options: ListenTlsOptions): TlsListener;
+  export function listenTls(
+    options: ListenTlsOptions & TlsCertifiedKeyOptions,
+  ): TlsListener;
 
   /** @category Network */
   export interface ConnectOptions {
@@ -343,9 +412,11 @@ declare namespace Deno {
      *
      * @default {"127.0.0.1"} */
     hostname?: string;
-    /**
-     * Server certificate file.
+    /** Path to a file containing a PEM formatted list of root certificates that will
+     * be used in addition to the default root certificates to verify the peer's certificate. Requires
+     * `--allow-read`.
      *
+     * @tags allow-read
      * @deprecated This will be removed in Deno 2.0. See the
      * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
      * for migration instructions.
@@ -361,26 +432,6 @@ declare namespace Deno {
      * TLS handshake.
      */
     alpnProtocols?: string[];
-    /**
-     * PEM formatted client certificate chain.
-     *
-     * @deprecated This will be removed in Deno 2.0. See the
-     * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
-     * for migration instructions.
-     */
-    certChain?: string;
-    /**
-     * PEM formatted (RSA or PKCS8) private key of client certificate.
-     *
-     * @deprecated This will be removed in Deno 2.0. See the
-     * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide}
-     * for migration instructions.
-     */
-    privateKey?: string;
-    /** Server private key in PEM format. */
-    key?: string;
-    /** Cert chain in PEM format. */
-    cert?: string;
   }
 
   /** Establishes a secure connection over TLS (transport layer security) using
@@ -403,6 +454,30 @@ declare namespace Deno {
    */
   export function connectTls(options: ConnectTlsOptions): Promise<TlsConn>;
 
+  /** Establishes a secure connection over TLS (transport layer security) using
+   * an optional cert file, client certificate, hostname (default is "127.0.0.1") and
+   * port.  The cert file is optional and if not included Mozilla's root certificates will
+   * be used (see also https://github.com/ctz/webpki-roots for specifics)
+   *
+   * ```ts
+   * const caCert = await Deno.readTextFile("./certs/my_custom_root_CA.pem");
+   * const key = "----BEGIN PRIVATE KEY----...";
+   * const cert = "----BEGIN CERTIFICATE----...";
+   * const conn1 = await Deno.connectTls({ port: 80, key, cert });
+   * const conn2 = await Deno.connectTls({ caCerts: [caCert], hostname: "192.0.2.1", port: 80, key, cert });
+   * const conn3 = await Deno.connectTls({ hostname: "[2001:db8::1]", port: 80, key, cert });
+   * const conn4 = await Deno.connectTls({ caCerts: [caCert], hostname: "golang.org", port: 80, key, cert });
+   * ```
+   *
+   * Requires `allow-net` permission.
+   *
+   * @tags allow-net
+   * @category Network
+   */
+  export function connectTls(
+    options: ConnectTlsOptions & TlsCertifiedKeyOptions,
+  ): Promise<TlsConn>;
+
   /** @category Network */
   export interface StartTlsOptions {
     /** A literal IP address or host name that can be resolved to an IP address.