roblox-ts-core 0.0.1-security.1 → 4.6.8

package/tutorials/Authentication.md

@@ -0,0 +1,75 @@
+### What is Authentication on Roblox?
+Authentication is pretty simple, it's how Roblox knows who you are and what account you're using. To identify your account, Roblox uses [**authentication sessions**](https://medium.com/@sherryhsu/session-vs-token-based-authentication-11a6c5ac45e4) which are stored on their servers and linked to your account. Your authentication session will expire when you log out of an account or press sign out of all other sessions. You can keep your session active by obtaining your cookie in an incognito window using the instructions below and closing the window when you're done, rather than signing out manually. Since Roblox uses FunCaptcha and have no official bot system, developers are forced to use these sessions, which are stored in [**cookies.**](https://support.mozilla.org/en-US/kb/cookies-information-websites-store-on-your-computer) This will allow Roblox to easily identify your bot's account and execute actions on it's behalf.
+
+### What's a cookie?
+A cookie (not the ones you eat) is a small quantity of data containing data sent by a website. Cookies are stored by the user's web browser while browsing. Cookies are standard practice across the web and as such, a large part of Roblox's security are based around cookies. Sharing is not caring. Never share your cookie.
+
+### How do I obtain my cookie?
+There are many different ways to obtain your cookie depending on your browser. First of all, open an [Incognito window](https://support.google.com/chrome/answer/95464?co=GENIE.Platform%3DDesktop&hl=en) on your browser and sign into your bot account.
+
+> [Are you hosting your bot remotely? Due to recent security improvements, cookies are now locked by IP region. Learn connect to your VPS and generate the cookie remotely here.](https://noblox.js.org/tutorial-VPS%20Authentication.html)
+
+#### **Chrome**
+    1. Click the arrow icon on the right-hand side of the toolbar. 
+    2. Go to More Tools. 
+    3. Click the Developer Tools button. 
+    4. Click the Application tab and Cookies button on the menu to the left. 
+    5. Click the dropdown until you find www.roblox.com. 
+    6. Your cookie is the value assigned to the key named .ROBLOSECURITY. Copy it.
+#### **Firefox**
+    1. Click the hamburger icon on the right-hand side of the toolbar. 
+    2. Go to Web Developer. 
+    3. Click Storage Inspector and the Cookies button on the menu to the left. 
+    4. Click the dropdown until you find www.roblox.com. 
+    5. Your cookie is the value assigned to the key named .ROBLOSECURITY. Copy it.
+#### **Safari**
+    1. Go to Preferences, Advanced and select Show Develop menu in menu bar. 
+    2. Click the Develop tab. 
+    3. Click Show Web Inspector. 
+    4. Click the Storage tab and then click Cookies. 
+    5. Click the dropdown until you find www.roblox.com. 
+    6. Your cookie is the value assigned to the key named .ROBLOSECURITY. Copy it.
+#### **Edge**
+    1. Click the elipsis (...) on the right-hand side of the toolbar. 
+    2. Go to More tools. 
+    3. Click the Developer Tools button. 
+    4. Click the More Tools button (icon next to Console). 
+    5. Click Storage. 
+    6. Click the dropdown until you find www.roblox.com. 
+    7. Your cookie is the value assigned to the key named .ROBLOSECURITY. Copy it.
+
+### How do I use my cookie?
+Once you have obtained and copied your cookie, close the incognito window without signing out. To use your cookie with noblox, you will have to use the **setCookie method**. This will use your cookie in all requests sent to Roblox to perform actions on your bot's behalf. You should store your cookie somewhere secure, such as a [**.env file**](https://medium.com/the-node-js-collection/making-your-node-js-work-everywhere-with-environment-variables-2da8cdf6e786).
+
+### Example:
+```javascript
+const noblox = require("noblox.js");
+
+noblox.setCookie(process.env.COOKIE).then(function() { //Use COOKIE from our .env file.
+    console.log("Logged in!")
+}).catch(function(err) {
+    console.log("Unable to log in!", err)
+})
+```
+
+### ⚠️ Usage warning
+
+An authentication error which is often seen is `Cannot get CSRF: You are not logged in.`.
+This is an error caused by trying to use an authenticated method, while not having set a cookie.
+This is usually for one of two reasons:
+#### Reason 1: Not used method
+You haven't set the cookie. This should be pretty self-explanatory, and can also appear as "Authorization has been denied for this request".
+To solve this case, use the [setCookie](./global.html#setCookie) method.
+
+
+#### Reason 2: Promises
+More often than not, this error is caused by misuse of promises.
+The setCookie method, like most of our methods, returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+
+Ensure you use either `async await` or the `.then` and `.catch` methods. If using Async await, you must put any
+authenticated code either WITHIN the same async function, or in another function which is called after your setCookie 
+completes. The cookie will **not** be set until setCookie is complete.
+
+If using `then` and `catch`, likewise it should be within the `then` block or a function called by it.
+
+You can read more about Promises [here](./tutorial-Promises.html).

package/tutorials/Event Emitters.md

@@ -0,0 +1,26 @@
+### What is an EventEmitter?
+An Event Emitter is a way in JavaScript to recieve data in real time until the emitter is closed. It's an easy way to handle events that occur in your application and execute functions. In noblox, they are used for handling events such as when someone shouts or Roblox notifications. 
+
+### How can I use an EventEmitter?
+You can use an EventEmitter created by noblox by calling a function that returns an EventEmitter, and calling **.on(event, callback)**. 3 events used by noblox are "data", "connect", and "close". Data is when noblox detects a change on Roblox and informs you of the change, which it will provide as a parameter in the callback function. Connect is when noblox connects to Roblox successfully and starts the emitter. Finally, close is when noblox disconnects from Roblox and stops the emitter.
+
+### Example:
+```javascript
+const noblox = require("noblox.js");
+const Emitter = noblox.onShout(1);
+
+Emitter.on("connect", function() {
+    console.log("noblox is listening for a shout change!");
+})
+
+Emitter.on("data", function(newStatus) {
+    console.log("The group status has been updated! New status:", newStatus);
+})
+
+Emitter.on("close", function() {
+    console.log("noblox has closed the emitter!");
+})
+```
+
+### Resources:
+[**DigitalOcean**](https://www.digitalocean.com/community/tutorials/using-event-emitters-in-node-js)

package/tutorials/Promises.md

@@ -0,0 +1,86 @@
+### What are Promises?
+Promises allow you to easily make your code asynchronous. They will allow your code to yield/stop and wait for a function to return a value. If a value is unknown, they will allow us to wait for the value to become known or for an error to be thrown. For example, if we want to get a user's rank, we want to wait for Roblox to reply with their rank before continuing the execution of our code.
+
+### How do you use Promises?
+
+You can use promises in 2 different ways. The first one is using **await/async**, in which you can set a variable to the result of the Promise, but **only** in an **async** function. This is done using await before calling the function, which will return a Promise. 
+
+Another way you can use promises is by using **.then**(function). The function wrapped in .then() will execute when the Promise resolves, and the variables will be passed through the function.
+
+However, sometimes Promises throw errors. You will need to handle any errors from promises or else you will get an **[Unhandled Promise Rejection Error.](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises#Promise_rejection_events)** These errors are fatal and should always be handled accordingly. To do this, you can use **.catch**, which will allow you to handle the error correctly. When using **async/await**, you can use .catch by attaching it after the function is called. With **.then()**, you can attach it after **.then**. Both cases are shown in the examples below.
+
+### Examples:
+
+#### async/await
+```javascript
+const noblox = require("noblox.js");
+
+//await can only be used in async functions!
+async function DemoteUser (groupId, username) { 
+  //await will yield the code until a value is returned.
+  const userId = await noblox.getIdFromUsername(username).catch(function(error) {
+    console.log("There was an error getting the id!", error)  
+  }); //Handle the rejection accordingly.
+	
+  if (!userId) return console.log("No id was returned.");
+  noblox.demote(groupId, userId); //Use the value returned to demote the user.
+}
+
+DemoteUser(1, "popeeyy");
+```
+
+#### .then(function)
+```javascript
+const noblox = require("noblox.js");
+
+//When the promise is resolved, the function runs with the provided variable.
+noblox.getIdFromUsername("popeeyy").then(function(userId) {
+  noblox.demote(1, userId)
+}).catch(function(error) { //Handle the rejection accordingly.
+  console.log("There was an error getting the id!", error)
+})
+```
+
+### Additional Info:
+
+When you use an **async** function, a Promise is returned, not a function. They should be treated as if they are Promises when returning values by using await or .then with proper error handling as well.
+
+There are different ways to create a Promise, but we'll discuss two of the easiest ways. The first way is to create an **async function**, as explained above. The other way is to use **new Promise(function)**, with the function having 2 parameters. The 2 parameters are resolve and reject respectively, which will resolve the Promise or throw an error.
+
+You should always read the docs, isn't that what you're here for? There are plenty of examples showing when you use Promises and what values are returned by the function. Promises are your friend in this library and many others, so take the time to learn them first and practice using them. If you have any questions, you can always ask the community in the [Roblox API Discord](https://discord.gg/EDXNdAT) via our designated channel "nodejs_nobloxjs".
+
+### Example:
+
+```javascript
+const isCool = false;
+
+function amICool() {
+  //Create a new Promise
+  return new Promise(function(resolve, reject) {
+    if (isCool) {
+      //Resolve that isCool is true.
+      resolve(true)
+    } else {
+      //Reject the Promise because only cool people can call this.
+      reject("You aren't cool, don't call this function!")
+    }
+  })
+}
+
+amICool().then(function(cool) {
+  console.log("Am I cool?", cool)
+}).catch(function(err) {
+  console.log("There was an error while checking if I'm cool", err)
+})
+```
+
+### Resources:
+
+If you are still having trouble with Promises or want to learn more, here are a few helpful resources:
+
+
+[**MDN**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
+<br />
+[**DigitalOcean**](https://www.digitalocean.com/community/tutorials/javascript-promises-for-dummies)
+<br />
+[**JavaScript.info**](https://javascript.info/promise-basics)

package/tutorials/VPS Authentication.md

@@ -0,0 +1,72 @@
+# Retrieving a .ROBLOSECURITY cookie on a headless VPS:
+
+> You must have a **static IP** on a dedicated VPS that you can SSH into; <ins>free hosts like Repl.it and Glitch **are not compatible.**</ins>
+
+[Adapted from a DigitalOcean tutorial.](https://www.digitalocean.com/community/tutorials/how-to-route-web-traffic-securely-without-a-vpn-using-a-socks-tunnel)
+
+---
+
+As of March 8th, 2022, Roblox began rolling out a mandatory security feature that locks an account's `.ROBLOSECURITY` cookie to an IP region. 
+
+Learn more here: [https://devforum.roblox.com/t/ip-changes-invalidate-cookie/1700515](https://devforum.roblox.com/t/ip-changes-invalidate-cookie/1700515)
+
+To bypass this, you must create the token from your VPS; the easiest way of which is through an SSH tunnel. When using this solution, the VPS must be the **only IP** accessing the account. Relogging without the proxy, or using a free coding workspace like Repl.it, Glitch, or Heroku, that assign dynamic IPs **will not work.**
+
+---
+
+**Step 0)** Make sure you are signed out of the target account, and have SSH access to your VPS.
+
+**Step 1)** Connect to your VPS over SSH:
+
+```console
+ssh your_user@your_server_ip
+```
+
+**Step 2)** Whitelist a port in your firewall (any value between 1024 and 65535), we will use `1234`:
+
+```console
+sudo ufw allow 1234
+```
+
+> [If you have never set up a firewall, I strongly recommend reading this article to harden your server](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-ubuntu-20-04); make sure to allow your SSH port too!
+
+**Step 3)** Reconnect and start an SSH tunnel on the whitelisted port:
+
+```console
+ssh -D 1234 your_user@your_server_ip
+```
+
+You will be prompted for a password, and then there will be no sign for success for failure, **this is expected**.
+
+**Step 4)** From a <ins>new terminal instance</ins>, connect your web browser to the proxy in incognito, and log in:
+
+> These commands should be run outside of WSL, either use Git Bash or cmd.
+
+**Google Chrome:**
+```
+start chrome --incognito --proxy-server="socks5://localhost:1234" https://www.roblox.com/login
+```
+
+**Microsoft Edge:**
+```
+start msedge --inprivate --proxy-server="socks5://localhost:1234" https://www.roblox.com/login
+```
+
+[**Mozilla Firefox**](https://www.digitalocean.com/community/tutorials/how-to-route-web-traffic-securely-without-a-vpn-using-a-socks-tunnel#step-2-mdash-configuring-firefox-to-use-the-tunnel) (Less recommended; must be manually configured.)
+
+**Step 5)** [Retrieve your cookie as normal](https://noblox.js.org/tutorial-Authentication.html); this is nothing new.
+
+**Step 6)** Copy the cookie to your VPS, write to a `.env` file, etc, your pick.
+
+**Step 7)** Close the incognito proxied window; **do not** press log out.
+
+**Step 8)** [Clean-Up]: Remove the whitelisted port from your firewall rules:
+```console
+sudo ufw delete allow 1234
+```
+
+**Step 9)** You may now close the SSH tunnel by closing your terminal; you are done- as far as Roblox can tell, you logged in from your VPS's IP.
+
+---
+
+> From now on, you **MUST** be connected through the SSH Tunnel to access the Roblox account. Failing to do so will violate the IP check and invalidate your cookie.