Update docs for blind indices and secrets v3 endpoints

docs/api-reference/overview/examples/update-secret.mdx

@@ -0,0 +1,229 @@
+---
+title: "Update secret"
+description: "How to update a secret using an Infisical Token scoped to a project and environment"
+---
+
+Prerequisites:
+
+- Set up and add envars to [Infisical Cloud](https://app.infisical.com).
+- Create an [Infisical Token](../../../getting-started/dashboard/token) for your project and environment with write access enabled.
+- Grasp a basic understanding of the system and its underlying cryptography [here](/api-reference/overview/introduction).
+- [Ensure that your project is blind-indexed](../blind-indices).
+
+## Flow
+
+1. [Get your Infisical Token data](/api-reference/endpoints/service-tokens/get) including a (encrypted) project key.
+2. Decrypt the (encrypted) project key with the key from your Infisical Token.
+3. Encrypt your updated secret with the project key
+4. [Send (encrypted) updated secret to Infical](/api-reference/endpoints/secrets/update)
+
+## Example
+
+<Tabs>
+<Tab title="Javascript">
+```js
+const crypto = require('crypto');
+const axios = require('axios');
+
+const BASE_URL = 'https://app.infisical.com';
+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 updateSecrets = async () => {
+    const serviceToken = 'your_service_token';
+    const serviceTokenSecret = serviceToken.substring(serviceToken.lastIndexOf('.') + 1);
+    
+    const secretType = 'shared' // 'shared' or 'personal'
+    const secretKey = 'some_key';
+    const secretValue = 'updated_value';
+    const secretComment = 'updated_comment';
+
+    // 1. Get your Infisical Token data
+    const { data: serviceTokenData } = await axios.get(
+       `${BASE_URL}/api/v2/service-token`,
+        {
+            headers: {
+                Authorization: `Bearer ${serviceToken}`
+            }
+        }
+    );
+
+    // 2. Decrypt the (encrypted) project key with the key from your Infisical Token
+    const projectKey = decrypt({
+        ciphertext: serviceTokenData.encryptedKey,
+        iv: serviceTokenData.iv,
+        tag: serviceTokenData.tag,
+        secret: serviceTokenSecret
+    });
+    
+	// 3. Encrypt your updated secret with the project key
+    const {
+        ciphertext: secretKeyCiphertext,
+        iv: secretKeyIV,
+        tag: secretKeyTag
+    } = encrypt({
+        text: secretKey,
+        secret: projectKey
+    });
+
+    const {
+        ciphertext: secretValueCiphertext,
+        iv: secretValueIV,
+        tag: secretValueTag
+    } = encrypt({
+        text: secretValue,
+        secret: projectKey
+    });
+
+    const {
+        ciphertext: secretCommentCiphertext,
+        iv: secretCommentIV,
+        tag: secretCommentTag
+    } = encrypt({
+        text: secretComment,
+        secret: projectKey
+    });
+	
+	// 4. Send (encrypted) updated secret to Infisical
+    await axios.patch(
+        `${BASE_URL}/api/v3/secrets/${secretKey}`,
+        {
+            workspaceId: serviceTokenData.workspace,
+            environment: serviceTokenData.environment,
+            type: secretType,
+            secretValueCiphertext,
+            secretValueIV,
+            secretValueTag,
+            secretCommentCiphertext,
+            secretCommentIV,
+            secretCommentTag
+        },
+        {
+            headers: {
+                Authorization: `Bearer ${serviceToken}`
+            }
+        }
+    );
+}
+
+updateSecrets();
+```
+</Tab>
+
+<Tab title="Python">
+```Python
+import base64
+import requests
+from Cryptodome.Cipher import AES
+from Cryptodome.Random import get_random_bytes
+
+
+BASE_URL = "https://app.infisical.com"
+BLOCK_SIZE_BYTES = 16
+
+
+def encrypt(text, secret):
+    iv = get_random_bytes(BLOCK_SIZE_BYTES)
+    secret = bytes(secret, "utf-8")
+    cipher = AES.new(secret, AES.MODE_GCM, iv)
+    ciphertext, tag = cipher.encrypt_and_digest(text.encode("utf-8"))
+    return {
+        "ciphertext": base64.standard_b64encode(ciphertext).decode("utf-8"),
+        "tag": base64.standard_b64encode(tag).decode("utf-8"),
+        "iv": base64.standard_b64encode(iv).decode("utf-8"),
+    }
+
+
+def decrypt(ciphertext, iv, tag, secret):
+    secret = bytes(secret, "utf-8")
+    iv = base64.standard_b64decode(iv)
+    tag = base64.standard_b64decode(tag)
+    ciphertext = base64.standard_b64decode(ciphertext)
+
+    cipher = AES.new(secret, AES.MODE_GCM, iv)
+    cipher.update(tag)
+    cleartext = cipher.decrypt(ciphertext).decode("utf-8")
+    return cleartext
+
+
+def update_secret():
+    service_token = "your_service_token"
+    service_token_secret = service_token[service_token.rindex(".") + 1 :]
+
+    secret_type = "shared" # "shared" or "personal"
+    secret_key = "some_key"
+    secret_value = "updated_value"
+    secret_comment = "updated_comment"
+
+    # 1. Get your Infisical Token data
+    service_token_data = requests.get(
+        f"{BASE_URL}/api/v2/service-token",
+        headers={"Authorization": f"Bearer {service_token}"},
+    ).json()
+
+    # 2. Decrypt the (encrypted) project key with the key from your Infisical Token
+    project_key = decrypt(
+        ciphertext=service_token_data["encryptedKey"],
+        iv=service_token_data["iv"],
+        tag=service_token_data["tag"],
+        secret=service_token_secret,
+    )
+
+    # 3. Encrypt your updated secret with the project key
+    encrypted_key_data = encrypt(text=secret_key, secret=project_key)
+    encrypted_value_data = encrypt(text=secret_value, secret=project_key)
+    encrypted_comment_data = encrypt(text=secret_comment, secret=project_key)
+
+    # 4. Send (encrypted) updated secret to Infisical
+    requests.patch(
+        f"{BASE_URL}/api/v3/secrets/{secret_key}",
+        json={
+            "workspaceId": service_token_data["workspace"],
+            "environment": service_token_data["environment"],
+            "type": secret_type,
+            "secretKeyCiphertext": encrypted_key_data["ciphertext"],
+            "secretKeyIV": encrypted_key_data["iv"],
+            "secretKeyTag": encrypted_key_data["tag"],
+            "secretValueCiphertext": encrypted_value_data["ciphertext"],
+            "secretValueIV": encrypted_value_data["iv"],
+            "secretValueTag": encrypted_value_data["tag"],
+            "secretCommentCiphertext": encrypted_comment_data["ciphertext"],
+            "secretCommentIV": encrypted_comment_data["iv"],
+            "secretCommentTag": encrypted_comment_data["tag"]
+        },
+        headers={"Authorization": f"Bearer {service_token}"},
+    )
+
+
+update_secret()
+
+```
+</Tab>
+</Tabs>