cyberchef/docs/GCloudGCSSetup.md

# GCP Configuration Guide: GCS + Speech-to-Text

This guide ensures your Google Cloud project is correctly configured to support:
- **CyberChef `GCloud List Bucket`** — listing objects in a GCS bucket from the browser
- **CyberChef `GCloud Read File`** — downloading small files from GCS into the browser
- **CyberChef `GCloud Speech-to-Text`** — transcribing audio files stored in GCS, both returning results to the browser and writing outputs back to GCS

**Your bucket:** `cyber-chef-cloud-examples`

---

## 1. APIs to Enable

In the [Google Cloud Console](https://console.cloud.google.com/apis/library) (or via `gcloud`), ensure the following APIs are enabled for your project:

| API | Purpose | Enable via Console link |
| :--- | :--- | :--- |
| **Cloud Storage JSON API** | Listing & reading bucket objects | [Enable](https://console.cloud.google.com/apis/library/storage-component.googleapis.com) |
| **Cloud Speech-to-Text API** | Audio transcription | [Enable](https://console.cloud.google.com/apis/library/speech.googleapis.com) |

Via `gcloud`:
```bash
gcloud services enable storage-component.googleapis.com
gcloud services enable speech.googleapis.com
```

---

## 2. IAM Roles for Your User Identity

CyberChef sends API requests using **your OAuth token** (generated by `gcloud auth print-access-token`). Your user identity needs the following roles:

### On the GCS Bucket (`cyber-chef-cloud-examples`)

| Role | Why Needed |
| :--- | :--- |
| `roles/storage.objectViewer` | To list objects and read file metadata (List Bucket operation) |
| `roles/storage.objectCreator` | To write transcription output files back to the `output/` prefix |

Grant via console: **Cloud Storage → cyber-chef-cloud-examples → Permissions → Grant Access**

Or via `gcloud`:
```bash
# Replace YOUR_EMAIL with your Google account email
gcloud storage buckets add-iam-policy-binding gs://cyber-chef-cloud-examples \
    --member="user:YOUR_EMAIL@gmail.com" \
    --role="roles/storage.objectViewer"

gcloud storage buckets add-iam-policy-binding gs://cyber-chef-cloud-examples \
    --member="user:YOUR_EMAIL@gmail.com" \
    --role="roles/storage.objectCreator"
```

### On the Speech-to-Text API

Your user identity needs permission to call the Speech-to-Text API at the **project level**:

| Role | Why Needed |
| :--- | :--- |
| `roles/speech.editor` (or `roles/speech.client`) | To call `longrunningrecognize` and poll operation status |

```bash
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="user:YOUR_EMAIL@gmail.com" \
    --role="roles/speech.client"
```

---

## 3. Allow the Speech-to-Text Service Account to Read Your Bucket

> [!IMPORTANT]
> This is the most commonly missed step. When you call `longrunningrecognize` with a `gcsUri`, the **Speech-to-Text API reads the file using its own internal service account**, not yours. You must explicitly grant this service account access to your bucket.

### Find your Speech-to-Text service account

The service account follows the pattern:
```
service-{PROJECT_NUMBER}@gcp-sa-speech.iam.gserviceaccount.com
```

Get your project number:
```bash
gcloud projects describe YOUR_PROJECT_ID --format="value(projectNumber)"
# Example output: 123456789012
```

So your service account would be:
```
service-123456789012@gcp-sa-speech.iam.gserviceaccount.com
```

### Grant it access to the bucket

```bash
gcloud storage buckets add-iam-policy-binding gs://cyber-chef-cloud-examples \
    --member="serviceAccount:service-123456789012@gcp-sa-speech.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"
```

---

## 4. Configure CORS on the Bucket

CyberChef runs in the browser and makes direct `fetch()` requests to the GCS JSON API. For the **list** and **metadata** endpoints these are generally permitted, but to be safe and to avoid issues with `OPTIONS` preflight requests, configure CORS on the bucket.

Create a file `cors.json`:
```json
[
  {
    "origin": [
      "http://localhost:8080",
      "https://YOUR_CYBERCHEF_DOMAIN.com"
    ],
    "method": ["GET", "POST", "PUT", "HEAD"],
    "responseHeader": ["Content-Type", "Authorization", "x-goog-user-project"],
    "maxAgeSeconds": 3600
  }
]
```

Apply it:
```bash
gcloud storage buckets update gs://cyber-chef-cloud-examples \
    --cors-file=cors.json
```

Verify:
```bash
gcloud storage buckets describe gs://cyber-chef-cloud-examples --format="json(cors)"
```

---

## 5. Quota Project / ADC Setup

If you are using an **OAuth Token** (recommended), some APIs require a billing quota project. Ensure your `gcloud` environment is configured:

```bash
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
```

In CyberChef operations, always populate the **Quota Project** field with your Project ID (e.g., `cyberchefcloud`).

---

## 6. Verification Checklist

Run these commands to verify your configuration before using CyberChef:

### ✅ Can you list your bucket?
```bash
gcloud storage ls gs://cyber-chef-cloud-examples/audio/
# Expected: 4 audio file URIs
```

### ✅ Can you read a file?
```bash
gsutil cat gs://cyber-chef-cloud-examples/audio/hello_kitty.mp3 | file -
# Expected: MPEG audio data (or similar) — confirms read access
```

### ✅ Can the Speech API access the file? (Test with REST)
```bash
TOKEN=$(gcloud auth print-access-token)
PROJECT_ID=YOUR_PROJECT_ID

curl -s -X POST \
  "https://speech.googleapis.com/v1/speech:longrunningrecognize" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-goog-user-project: $PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "config": { "languageCode": "en-US", "enableAutomaticPunctuation": true },
    "audio": { "uri": "gs://cyber-chef-cloud-examples/audio/hello_kitty.mp3" }
  }'
# Expected: { "name": "projects/.../operations/12345" }
```

If this returns an operation name, your setup is correct.

### ✅ Can you poll the operation?
```bash
# Use the operation name from the previous step
OP_NAME="projects/YOUR_PROJECT_NUMBER/operations/12345"

curl -s \
  "https://speech.googleapis.com/v1/operations/${OP_NAME}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-goog-user-project: $PROJECT_ID"
# Wait a few seconds and re-run. When done: { "done": true, "response": { "results": [...] } }
```

### ✅ Can you write to the output/ prefix?
```bash
echo "Test transcript" | gsutil cp - gs://cyber-chef-cloud-examples/output/test.txt
# Expected: Copying... Operation completed

# Clean up
gsutil rm gs://cyber-chef-cloud-examples/output/test.txt
```

---

## 7. Expected Bucket Structure

```
cyber-chef-cloud-examples/
├── audio/
│   ├── hello_kitty.mp3
│   ├── track_02.mp3
│   ├── track_03.mp3
│   └── track_04.mp3
├── images/
│   └── (future image files)
├── video/
│   └── (future video files)
└── output/
    └── audio/
        └── hello_kitty.mp3/
            └── speech-to-text/
                └── text.txt         ← written by CyberChef
```

---

## 8. Summary of Roles Required

| Identity | Bucket Role | Project Role |
| :--- | :--- | :--- |
| Your user OAuth token | `storage.objectViewer` + `storage.objectCreator` | `speech.client` |
| Speech-to-Text service account | `storage.objectViewer` | *(handled internally by GCP)* |