Auth gcp improvement

.gitignore

@@ -18,6 +18,7 @@ dist/
 
 # Azure credentials file
 *_creds.json
+*-key.json
 
 # Environment variables file
 .env

Dockerfile

@@ -76,16 +76,16 @@ RUN echo $TZ > /etc/timezone && \
 # Install yq (architecture-aware)
 RUN ARCH=$(uname -m) && \
     if [ "$ARCH" = "x86_64" ]; then ARCH="amd64"; elif [ "$ARCH" = "aarch64" ]; then ARCH="arm64"; fi && \
-    curl -sL https://github.com/mikefarah/yq/releases/download/v4.47.2/yq_linux_${ARCH}.tar.gz | tar xz && \
+    curl -sL https://github.com/mikefarah/yq/releases/download/v4.48.1/yq_linux_${ARCH}.tar.gz | tar xz && \
     mv yq_linux_${ARCH} /usr/bin/yq && \
     rm -rf /tmp/*
 
 # Install Google Cloud SDK (architecture-aware)
 RUN ARCH=$(uname -m) && \
     if [ "$ARCH" = "x86_64" ]; then \
-    curl -sSL "https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-sdk-541.0.0-linux-x86_64.tar.gz" -o google-cloud-sdk.tar.gz; \
+    curl -sSL "https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-sdk-545.0.0-linux-x86_64.tar.gz" -o google-cloud-sdk.tar.gz; \
     elif [ "$ARCH" = "aarch64" ]; then \
-    curl -sSL "https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-sdk-541.0.0-linux-arm.tar.gz" -o google-cloud-sdk.tar.gz; \
+    curl -sSL "https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-sdk-545.0.0-linux-arm.tar.gz" -o google-cloud-sdk.tar.gz; \
     fi && \
     tar -xzf google-cloud-sdk.tar.gz && \
     ./google-cloud-sdk/install.sh -q && \

README.md

@@ -97,6 +97,27 @@ docker exec my-secrets worker env get API_KEY
 
 See [Authorization Guide](docs/authorization.md) for supported providers and credential formats (JSON, Base64, File Path).
 
+### 💡 Simplified Deployment
+
+For easier deployment with automatic credential detection, use the [`@udx/worker-deployment`](https://www.npmjs.com/package/@udx/worker-deployment) CLI:
+
+```bash
+# Install
+npm install -g @udx/worker-deployment
+
+# Generate config
+worker-config
+
+# Run with automatic GCP authentication
+worker-run
+```
+
+Features:
+- ✅ Auto-detects GCP credentials (service account keys, impersonation, workload identity)
+- ✅ Zero-config for default file names
+- ✅ Secure read-only mounts
+- ✅ Interactive debugging mode
+
 ### Development Setup
 
 ```bash

deploy-gcp.yml

@@ -0,0 +1,14 @@
+# npm install -g @udx/worker-deployment
+# worker-run --config=deploy-gcp.yml
+
+---
+kind: workerDeployConfig
+version: udx.io/worker-v1/deploy
+config:
+  # Docker image
+  image: "usabilitydynamics/udx-worker:latest"
+
+  env:
+    ACTORS_CLEANUP: "false"
+
+  command: "gcloud auth list"

docs/auth/README.md

@@ -0,0 +1,34 @@
+# Provider Authentication Guides
+
+This directory contains detailed authentication documentation for each supported cloud provider.
+
+## Available Guides
+
+- **[GCP Authentication](gcp.md)** - Complete guide for Google Cloud Platform
+  - Service Account Keys
+  - Workload Identity Tokens
+  - Service Account Impersonation
+  - worker-deployment CLI integration
+
+- **[Azure Authentication](azure.md)** - Coming soon
+- **[AWS Authentication](aws.md)** - Coming soon
+- **[Bitwarden Authentication](bitwarden.md)** - Coming soon
+
+## Quick Links
+
+- [Main Authorization Guide](../authorization.md) - Overview and general credential formats
+- [Worker Configuration](../config.md) - Worker configuration reference
+- [CLI Documentation](../CLI.md) - Worker CLI commands
+
+## Contributing
+
+When adding a new provider authentication guide, please follow this structure:
+
+1. **Authentication Methods** - List all supported authentication methods
+2. **JSON Format Examples** - Show credential structure
+3. **Usage Examples** - Provide practical examples (env vars, file paths, base64)
+4. **Features** - Highlight key features and capabilities
+5. **Best Practices** - Security and operational recommendations
+6. **CLI Integration** - If applicable, show worker-deployment CLI usage
+
+See [gcp.md](gcp.md) as a reference template.

docs/auth/aws.md

@@ -0,0 +1,14 @@
+# AWS Authentication
+
+> **Coming Soon**: Detailed AWS authentication documentation
+
+## Quick Reference
+
+**Environment Variable:** `AWS_CREDS`
+
+**Supported Formats:**
+- JSON
+- Base64-encoded JSON
+- File path
+
+For now, see the [general authorization guide](../authorization.md) for credential format examples.

docs/auth/azure.md

@@ -0,0 +1,24 @@
+# Azure Authentication
+
+> **Coming Soon**: Detailed Azure authentication documentation
+
+## Quick Reference
+
+**Environment Variable:** `AZURE_CREDS`
+
+**Supported Formats:**
+- JSON
+- Base64-encoded JSON
+- File path
+
+**Example:**
+```json
+{
+  "client_id": "CLIENT_ID",
+  "client_secret": "CLIENT_SECRET",
+  "tenant_id": "TENANT_ID",
+  "subscription_id": "SUBSCRIPTION_ID"
+}
+```
+
+For now, see the [general authorization guide](../authorization.md) for credential format examples.

docs/auth/bitwarden.md

@@ -0,0 +1,14 @@
+# Bitwarden Authentication
+
+> **Coming Soon**: Detailed Bitwarden authentication documentation
+
+## Quick Reference
+
+**Environment Variable:** `BITWARDEN_CREDS`
+
+**Supported Formats:**
+- JSON
+- Base64-encoded JSON
+- File path
+
+For now, see the [general authorization guide](../authorization.md) for credential format examples.

docs/auth/gcp.md

@@ -0,0 +1,189 @@
+# GCP Authentication
+
+Google Cloud Platform supports multiple authentication methods, each suited for different use cases.
+
+## Authentication Methods
+
+### 1. Service Account Key (Most Common)
+
+Service account keys work for both local development and CI/CD environments.
+
+**JSON Format:**
+```json
+{
+  "type": "service_account",
+  "project_id": "my-project-id",
+  "private_key_id": "key-id",
+  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
+  "client_email": "my-sa@my-project.iam.gserviceaccount.com",
+  "client_id": "123456789",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token",
+  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/..."
+}
+```
+
+**Usage:**
+```bash
+# Via environment variable
+export GCP_CREDS='{"type":"service_account",...}'
+
+# Via file path
+export GCP_CREDS="/path/to/service-account-key.json"
+
+# Via base64 encoding (recommended for CI/CD)
+export GCP_CREDS=$(cat service-account-key.json | base64)
+```
+
+**Features:**
+- ✅ Automatic `private_key` normalization (handles escaped newlines)
+- ✅ Sets both `GOOGLE_APPLICATION_CREDENTIALS` and `GCP_CREDS`
+- ✅ Authenticates with `gcloud` CLI
+- ✅ Sets project automatically from `project_id` field
+
+---
+
+### 2. Workload Identity Token (GitHub Actions / CI/CD)
+
+Keyless authentication using OIDC tokens - no service account keys needed!
+
+**JSON Format:**
+```json
+{
+  "type": "external_account",
+  "audience": "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID",
+  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
+  "token_url": "https://sts.googleapis.com/v1/token",
+  "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA_EMAIL:generateAccessToken",
+  "credential_source": {
+    "file": "/path/to/token",
+    "format": {
+      "type": "text"
+    }
+  }
+}
+```
+
+**GitHub Actions Example:**
+```yaml
+- uses: google-github-actions/auth@v3
+  id: auth
+  with:
+    workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
+    service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}
+
+- name: Run Worker
+  env:
+    GCP_CREDS: ${{ steps.auth.outputs.credentials_file_path }}
+  run: |
+    docker run -e GCP_CREDS usabilitydynamics/udx-worker:latest
+```
+
+**Features:**
+- ✅ No long-lived credentials
+- ✅ Automatic token refresh
+- ✅ Works with Google Cloud client libraries
+- ✅ Recommended for CI/CD pipelines
+
+---
+
+### 3. Service Account Impersonation (Local Development)
+
+Use your personal gcloud credentials to impersonate a service account - no key files needed!
+
+**Setup:**
+```bash
+# 1. Authenticate with gcloud
+gcloud auth login
+
+# 2. Set up Application Default Credentials (required for Terraform/SDKs)
+gcloud auth application-default login
+
+# 3. Grant yourself impersonation permission
+gcloud iam service-accounts add-iam-policy-binding \
+  my-sa@my-project.iam.gserviceaccount.com \
+  --member="user:$(gcloud config get-value account)" \
+  --role="roles/iam.serviceAccountTokenCreator" \
+  --project=MY_PROJECT
+```
+
+**Usage with worker-deployment CLI:**
+```yaml
+# deploy.yml
+config:
+  service_account:
+    email: "my-sa@my-project.iam.gserviceaccount.com"
+  image: "usabilitydynamics/udx-worker:latest"
+  command: "worker run my-task"
+```
+
+```bash
+# Run with automatic impersonation
+worker-run --config=deploy.yml
+```
+
+**Manual Docker Usage:**
+```bash
+# Generate impersonation credentials
+gcloud auth application-default print-access-token > /tmp/token.txt
+
+# Run container with impersonation
+docker run \
+  -e GOOGLE_APPLICATION_CREDENTIALS=/home/udx/adc.json \
+  -e CLOUDSDK_AUTH_ACCESS_TOKEN=$(cat /tmp/token.txt) \
+  -v ~/.config/gcloud/application_default_credentials.json:/home/udx/adc.json:ro \
+  usabilitydynamics/udx-worker:latest
+```
+
+**Features:**
+- ✅ No service account key files
+- ✅ Uses your personal credentials
+- ✅ Temporary access tokens
+- ✅ Easy permission management
+- ✅ Works with Terraform, gcloud, and SDKs
+
+> **Note**: Impersonation bypasses the `gcp_authenticate()` function by setting `GOOGLE_APPLICATION_CREDENTIALS` and `CLOUDSDK_AUTH_ACCESS_TOKEN` directly.
+
+---
+
+## Authentication Priority
+
+When multiple credential sources are available, the worker uses this priority:
+
+1. **`GOOGLE_APPLICATION_CREDENTIALS`** - If already set, skip authentication (used for impersonation)
+2. **`GCP_CREDS`** - Process through `gcp_authenticate()` function:
+   - Detect credential type (service account key vs. workload identity token)
+   - Normalize service account keys (fix escaped newlines in `private_key`)
+   - Set `GOOGLE_APPLICATION_CREDENTIALS`
+   - Authenticate with `gcloud auth login --cred-file`
+
+---
+
+## Using worker-deployment CLI
+
+The [`@udx/worker-deployment`](https://www.npmjs.com/package/@udx/worker-deployment) CLI simplifies GCP authentication:
+
+**Installation:**
+```bash
+npm install -g @udx/worker-deployment
+```
+
+**Quick Start:**
+```bash
+# Generate config template
+worker-config
+
+# Edit deploy.yml with your settings
+
+# Run with automatic credential detection
+worker-run
+```
+
+**Features:**
+- ✅ Automatic credential detection (service account keys, impersonation, workload identity)
+- ✅ Zero-config for default file names (`gcp-key.json`, `gcp-credentials.json`)
+- ✅ Secure read-only mounts
+- ✅ Support for custom credential paths
+
+See the [worker-deployment README](https://github.com/udx/worker-deployment) for detailed examples.

docs/authorization.md

@@ -13,6 +13,8 @@ The UDX Worker supports multiple cloud providers and services through environmen
 | GCP       | `GCP_CREDS`          | Google Cloud Platform credentials        |
 | Bitwarden | `BITWARDEN_CREDS`    | Bitwarden secrets management credentials |
 
+> **💡 Tip**: For simplified deployment with automatic credential detection, use the [`@udx/worker-deployment`](https://www.npmjs.com/package/@udx/worker-deployment) CLI tool.
+
 ## Credential Formats
 
 Credentials can be provided in three formats:
@@ -74,6 +76,15 @@ AZURE_CREDS="/path/to/azure_credentials.json"
 
 > **Note**: Always use absolute paths in production environments to avoid path resolution issues.
 
+## Provider-Specific Authentication
+
+For detailed authentication guides for each provider, see:
+
+- **[GCP Authentication](auth/gcp.md)** - Service account keys, workload identity, impersonation
+- **[Azure Authentication](auth/azure.md)** - Coming soon
+- **[AWS Authentication](auth/aws.md)** - Coming soon
+- **[Bitwarden Authentication](auth/bitwarden.md)** - Coming soon
+
 ## Credential Management
 
 | Flag             | Default | Description                                                               |