feat: stabilize Deno.startTls (#12581)

This commit stabilizes `Deno.startTls` and removes `certFile` from the
`StartTlsOptions`.

2 files changed, 32 insertions, 13 deletions

diff --git a/ext/net/lib.deno_net.d.ts b/ext/net/lib.deno_net.d.ts
index 1b67fcf22..81c248871 100644
--- a/ext/net/lib.deno_net.d.ts
+++ b/ext/net/lib.deno_net.d.ts
@@ -166,6 +166,36 @@ declare namespace Deno {
    */
   export function connectTls(options: ConnectTlsOptions): Promise<TlsConn>;
 
+  export interface StartTlsOptions {
+    /** A literal IP address or host name that can be resolved to an IP address.
+     * If not specified, defaults to `127.0.0.1`. */
+    hostname?: string;
+    /** A list of root certificates that will be used in addition to the
+     * default root certificates to verify the peer's certificate.
+     *
+     * Must be in PEM format. */
+    caCerts?: string[];
+  }
+
+  /** Start TLS handshake from an existing connection using an optional list of
+   * CA certificates, and hostname (default is "127.0.0.1"). Specifying CA certs
+   * is optional. By default the configured root certificates are used. Using
+   * this function requires that the other end of the connection is prepared for
+   * a TLS handshake.
+   *
+   * ```ts
+   * const conn = await Deno.connect({ port: 80, hostname: "127.0.0.1" });
+   * const caCert = await Deno.readTextFile("./certs/my_custom_root_CA.pem");
+   * const tlsConn = await Deno.startTls(conn, { caCerts: [caCert], hostname: "localhost" });
+   * ```
+   *
+   * Requires `allow-net` permission.
+   */
+  export function startTls(
+    conn: Conn,
+    options?: StartTlsOptions,
+  ): Promise<TlsConn>;
+
   /** Shutdown socket send operations.
    *
    * Matches behavior of POSIX shutdown(3).
diff --git a/ext/net/ops_tls.rs b/ext/net/ops_tls.rs
index 129a702bc..93c2ca1e9 100644
--- a/ext/net/ops_tls.rs
+++ b/ext/net/ops_tls.rs
@@ -776,7 +776,6 @@ pub struct ConnectTlsArgs {
 #[serde(rename_all = "camelCase")]
 struct StartTlsArgs {
   rid: ResourceId,
-  cert_file: Option<String>,
   ca_certs: Vec<String>,
   hostname: String,
 }
@@ -794,29 +793,19 @@ where
     "" => "localhost",
     n => n,
   };
-  let cert_file = args.cert_file.as_deref();
+
   {
-    super::check_unstable2(&state, "Deno.startTls");
     let mut s = state.borrow_mut();
     let permissions = s.borrow_mut::<NP>();
     permissions.check_net(&(hostname, Some(0)))?;
-    if let Some(path) = cert_file {
-      permissions.check_read(Path::new(path))?;
-    }
   }
 
-  let mut ca_certs = args
+  let ca_certs = args
     .ca_certs
     .into_iter()
     .map(|s| s.into_bytes())
     .collect::<Vec<_>>();
 
-  if let Some(path) = cert_file {
-    let mut buf = Vec::new();
-    File::open(path)?.read_to_end(&mut buf)?;
-    ca_certs.push(buf);
-  };
-
   let hostname_dns = DNSNameRef::try_from_ascii_str(hostname)
     .map_err(|_| invalid_hostname(hostname))?;