Complete v1 API reference docs, pre-launch

docs/api-reference/overview/examples/retrieve-secrets.mdx

@@ -2,9 +2,141 @@
 title: "Retrieve secrets"
 ---
 
+In this example, we demonstrate how to retrieve secrets from a project and environment.
+
+Prerequisites:
+
+- Set up and add envars to [Infisical Cloud](https://app.infisical.com)
+- Grasp a basic understanding of the system and its underlying cryptography [here](/api-reference/overview/introduction).
+
+## Flow
+
 1. Get your (encrypted) private key.
 2. Decrypt your (encrypted) private key with your password.
-3. Get the project key for the project.
-4. Decrypt the project key with your private key.
+3. Get the (encrypted) project key for the project.
+4. Decrypt the (encrypted) project key with your private key.
 5. Get secrets for a project and environment.
-6. Decrypt the secrets in your project.
+6. Decrypt the (encrypted) secrets
+
+## Example
+
+```js
+const crypto = require('crypto');
+const axios = require('axios');
+
+const ALGORITHM = 'aes-256-gcm';
+const BLOCK_SIZE_BYTES = 16;
+
+const encrypt = (
+	text,
+	secret
+) => {
+	const iv = crypto.randomBytes(BLOCK_SIZE_BYTES);
+	const cipher = crypto.createCipheriv(ALGORITHM, secret, iv);
+
+	let ciphertext = cipher.update(text, 'utf8', 'base64');
+	ciphertext += cipher.final('base64');
+	return {
+		ciphertext,
+		iv: iv.toString('base64'),
+		tag: cipher.getAuthTag().toString('base64')
+	};
+}
+
+const decrypt = (ciphertext, iv, tag, secret) => {
+	const decipher = crypto.createDecipheriv(
+		ALGORITHM,
+		secret,
+		Buffer.from(iv, 'base64')
+	);
+	decipher.setAuthTag(Buffer.from(tag, 'base64'));
+
+	let cleartext = decipher.update(ciphertext, 'base64', 'utf8');
+	cleartext += decipher.final('utf8');
+
+	return cleartext;
+}
+
+const retrieveSecrets = async () => {
+	const API_KEY = 'your_api_key';
+	const PSWD = 'your_pswd';
+	const WORKSPACE_ID = 'your_workspace_id';
+
+	// 1. get (encrypted) private key
+	const user = await axios.get(
+		'https://api.infisical.com/api/v2/users/me', {
+			headers: {
+				'X-API-KEY': API_KEY
+			}
+		}
+	);
+
+	// 2. decrypt your (encrypted) private key with your password
+	const privateKey = decrypt({
+		ciphertext: user.encryptedPrivateKey,
+		iv: user.iv,
+		tag: user.tag,
+		secret: PSWD.slice(0, 32).padStart(32, '0');
+	});
+
+	// 3. get the (encrypted) project key for the project
+	const encryptedProjectKey = await axios.get(
+		`https://api.infisical.com/api/v2/workspace/${WORKSPACE_ID}`, {
+			headers: {
+				'X-API-KEY': API_KEY
+			}
+		}
+	);
+
+	// 4. decrypt the project key with your private key
+	const projectKey = nacl.box.open(
+		util.decodeBase64(encryptedProjectKey),
+		util.decodeBase64(projectKey.nonce),
+		util.decodeBase64(projectKey.sender.publicKey),
+		util.decodeBase64(privateKey)
+	);
+
+	// 5. get (encrypted) secrets for a project and environment.
+    const encryptedSecrets = await axios.get(
+		'https://api.infisical.com/api/v2/secrets', {
+			headers: {
+				'X-API-KEY': API_KEY
+			}
+		}
+	);
+
+    // 6. decrypt the (encrypted) secrets
+    const secrets = encryptedSecrets.map((encryptedSecret) => {
+        const secretKey = decrypt({
+            ciphertext: encryptedSecret.secretKeyCiphertext,
+            iv: encryptedSecret.secretKeyIV,
+            tag: encryptedSecret.secretKeyTag
+            secret: projectKey
+        });
+        const secretValue = decrypt({
+            ciphertext: encryptedSecret.secretValueCiphertext,
+            iv: encryptedSecret.secretValueIV,
+            tag: encryptedSecret.secretValueTag
+            secret: projectKey
+        });
+
+        return ({
+            secretKey,
+            secretValue
+        });
+    });
+}
+
+retrieveSecrets();
+```
+
+<Info>
+  This example uses [TweetNaCl.js](https://tweetnacl.js.org/#/), a port of
+  TweetNacl/Nacl, to perform asymmeric decryption of the project key but there
+  are ports of NaCl available in every major language.
+</Info>
+<Tip>
+  It can be useful to perform steps 1-4 ahead of time and store away your
+  private key (and even project key) for later use. The Infisical CLI works by
+  securely storing your private key via your OS keyring.
+</Tip>