Lighthouse HMAC Demo

This demo application connects to Google Cloud Storage using S3-compatible HMAC authentication and lists objects in a specified bucket. It's designed to help clients verify that their HMAC keys are working correctly.

Usage

Some prerequisites:

• Either use UV, or Python +3.11 with venv
• HMAC keys for Google Cloud Storage access saved locally (remember to remove them when you're done)

First use

Option 1: Using UV (Recommended)

1. Clone this repository

2. Install UV if you haven't already

3. Run the demo directly - UV will automatically handle dependencies:

   uv run main.py path/to/credentials.json

Option 2: Traditional Virtual Environment

1. Clone this repository

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

   pip install -e .

4. Run the tool from the activated environment

   python main.py path/to/credentials.json

5. When finished, deactivate the virtual environment:

   deactivate

Command Line Options

• credentials_file: Path to JSON file containing HMAC credentials (required)
• --max-objects: Maximum number of objects to list or download (default: 10)
• --download: Download the listed objects to local directory
• --download-path: Custom download directory path (default: {bucket-name}_{ISO8601-timestamp})

Usage Examples

With UV:

# Basic listing
uv run main.py credentials.json

# Download with limited objects
uv run main.py credentials.json --max-objects 5 --download

# Download to custom directory
uv run main.py credentials.json --download --download-path ./my-downloads

With traditional setup:

# Activate your environment if it isn't done yet
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Basic listing
python main.py credentials.json

# Download with limited objects
python main.py credentials.json --max-objects 5 --download

# Download to custom directory
python main.py credentials.json --download --download-path ./my-downloads

Credentials File Format

The secret credentials JSON file should contain the following fields:

{
  "AWS_S3_ACCESS_KEY": "your-hmac-access-key",
  "AWS_S3_SECRET_KEY": "your-hmac-secret-key",
  "AWS_S3_ENDPOINT": "https://storage.googleapis.com",
  "AWS_S3_BUCKET": "your-bucket-name",
  "AWS_S3_REGION": "EU"
}

Sample Output

Basic Listing

🚀 Lighthouse HMAC Demo
==============================
Loading credentials from: credentials.json
✓ Credentials loaded successfully
  Endpoint: https://storage.googleapis.com
  Bucket: your-example-bucket
  Region: EU
Testing connection...
ⓘ Global bucket listing not permitted (this is normal)
  → HMAC keys are often scoped to specific buckets for security
  → Will test bucket-specific access instead...

Listing objects in bucket 'your-example-bucket'...
--------------------------------------------------
Found 5 objects (showing up to 10):

 1. data/file1.csv
    Size: 2.45 MB
    Last Modified: 2024-01-15 10:30:00+00:00

 2. data/file2.json
    Size: 0.12 MB
    Last Modified: 2024-01-15 11:45:00+00:00

✅ Demo completed successfully!

Your HMAC keys are working correctly with Google Cloud Storage.

With Downloads

🚀 Lighthouse HMAC Demo
==============================
Loading credentials from: credentials.json
✓ Credentials loaded successfully
  Endpoint: https://storage.googleapis.com
  Bucket: your-example-bucket
  Region: EU
Testing connection...
ⓘ Global bucket listing not permitted (this is normal)
  → HMAC keys are often scoped to specific buckets for security
  → Will test bucket-specific access instead...

Listing objects in bucket 'your-example-bucket'...
--------------------------------------------------
Found 3 objects (showing up to 10):

 1. sample/
    Size: 0.00 MB
    Last Modified: 2025-10-29 11:38:25+00:00

 2. sample/data.csv.gz
    Size: 2.45 MB
    Last Modified: 2025-10-29 11:41:01+00:00

 3. sample/report.json
    Size: 0.12 MB
    Last Modified: 2025-10-29 11:41:02+00:00

📥 Downloading 3 objects to 'your-example-bucket_20251031T154708'...
--------------------------------------------------
 1. Skipping directory sample/
 2. Downloading sample/data.csv.gz... ✓ (2.45 MB)
 3. Downloading sample/report.json... ✓ (0.12 MB)

Download summary:
  ✓ Successfully downloaded: 2
  ➤ Skipped directories: 1

✅ All objects downloaded successfully to 'your-example-bucket_20251031T154708'

✅ Demo completed successfully!

Your HMAC keys are working correctly with Google Cloud Storage.

Security Notes

• Never commit actual credentials to version control
• Consider using environment variables for production deployments
• Store credentials files securely
• Use appropriate file permissions for credentials files

Troubleshooting

Common Issues

1. "Access Denied" Error

   • Verify your HMAC keys are correct
   • Check that the keys have read permissions for the bucket
   • Ensure the bucket name is correct

2. "No Such Bucket" Error

   • Verify the bucket name in your credentials
   • Ensure the bucket exists in the specified region

3. Connection Timeout

   • Check your internet connection
   • Verify the endpoint URL is correct
   • Check for firewall restrictions

License

This project is provided as a demonstration tool for Lighthouse clients.