vibecarbon 0.1.0

package/src/lib/providers/hetzner-s3.js

@@ -0,0 +1,656 @@
+/**
+ * Hetzner Object Storage (S3-compatible) Provider
+ *
+ * Manages S3 bucket operations using AWS SDK v3.
+ * Note: S3 credentials must be created manually in Hetzner Console.
+ *
+ * API Documentation: https://docs.hetzner.com/storage/object-storage/
+ *
+ * Retry posture: every SDK call routes through `_send()`, which retries
+ * transient errors (TimeoutError, ECONNRESET, EAI_AGAIN, 5xx, AWS SDK
+ * "UnknownError" wrappers) with capped backoff. Operation-specific
+ * conditions (NotFound, BucketAlreadyExists, BucketNotEmpty) are handled
+ * by the caller via a `terminal` classifier so they don't waste retries.
+ * Hetzner Ceph has a higher transient-error floor than AWS S3, so this
+ * uniform posture is what keeps e2e off the whack-a-mole treadmill.
+ */
+
+import {
+  AbortMultipartUploadCommand,
+  CreateBucketCommand,
+  DeleteBucketCommand,
+  DeleteObjectsCommand,
+  HeadBucketCommand,
+  ListBucketsCommand,
+  ListMultipartUploadsCommand,
+  ListObjectsV2Command,
+  ListObjectVersionsCommand,
+  PutBucketCorsCommand,
+  S3Client,
+} from '@aws-sdk/client-s3';
+
+// Transient S3 error classifier. Matches AWS SDK error names ("TimeoutError",
+// "UnknownError"), socket-level Node errors ("ECONNRESET", "EAI_AGAIN"), and
+// 5xx HTTP statuses from $metadata.httpStatusCode. The regex covers cases
+// where the status code is embedded in the error name/message (some SDK
+// versions do this); the explicit $metadata check covers the common case
+// where Hetzner returns a clean 502/503/504 with a typed name like
+// "ServiceUnavailable" that wouldn't match the regex.
+const TRANSIENT_S3_ERROR_RE =
+  /TimeoutError|ETIMEDOUT|ECONNRESET|EAI_AGAIN|NetworkingError|Network failure|UnknownError|503|504|502/i;
+const TRANSIENT_HTTP_STATUSES = new Set([502, 503, 504]);
+
+function isTransientS3Error(error) {
+  if (!error) return false;
+  if (TRANSIENT_S3_ERROR_RE.test(error.name ?? '')) return true;
+  if (TRANSIENT_S3_ERROR_RE.test(error.message ?? '')) return true;
+  const status = error.$metadata?.httpStatusCode;
+  if (status && TRANSIENT_HTTP_STATUSES.has(status)) return true;
+  return false;
+}
+
+export class HetznerS3Provider {
+  static ENDPOINTS = {
+    fsn1: 'https://fsn1.your-objectstorage.com',
+    nbg1: 'https://nbg1.your-objectstorage.com',
+    hel1: 'https://hel1.your-objectstorage.com',
+  };
+
+  static REGIONS = {
+    fsn1: 'Falkenstein, Germany',
+    nbg1: 'Nuremberg, Germany',
+    hel1: 'Helsinki, Finland',
+  };
+
+  /**
+   * Create a new Hetzner S3 provider instance
+   * @param {string} accessKeyId - S3 access key
+   * @param {string} secretAccessKey - S3 secret key
+   * @param {string} region - Region (fsn1, nbg1, hel1)
+   */
+  constructor(accessKeyId, secretAccessKey, region) {
+    if (!accessKeyId || !secretAccessKey) {
+      throw new Error('S3 credentials are required');
+    }
+
+    if (!HetznerS3Provider.ENDPOINTS[region]) {
+      throw new Error(
+        `Invalid region: ${region}. Valid regions: ${Object.keys(HetznerS3Provider.ENDPOINTS).join(', ')}`,
+      );
+    }
+
+    this.accessKeyId = accessKeyId;
+    this.secretAccessKey = secretAccessKey;
+    this.region = region;
+    this.endpoint = HetznerS3Provider.ENDPOINTS[region];
+    this._client = null;
+  }
+
+  /**
+   * Get or create the S3 client (lazy initialization)
+   * @returns {S3Client}
+   */
+  getClient() {
+    if (!this._client) {
+      // Explicit timeouts on the underlying http handler. The AWS SDK's
+      // NodeHttpHandler defaults to no socket timeout, so a Hetzner Ceph
+      // endpoint that accepts the TCP connection but stops responding mid-
+      // request will hang the call indefinitely. Observed in iter-initbackend
+      // 2026-05-01: compose destroy hung for 600s (test runner SIGKILL) on
+      // emptyAndDeleteBucket → ListObjectsV2; the per-iteration `client.send`
+      // never returned. With requestTimeout set, a stuck call surfaces as a
+      // TimeoutError after 60s and `_send` retries. maxAttempts here is the
+      // SDK's own internal retry; `_send` adds an outer layer with backoff
+      // tuned for Hetzner Ceph's recovery cadence.
+      this._client = new S3Client({
+        region: this.region,
+        endpoint: this.endpoint,
+        forcePathStyle: true, // Hetzner requires path-style URLs
+        credentials: {
+          accessKeyId: this.accessKeyId,
+          secretAccessKey: this.secretAccessKey,
+        },
+        maxAttempts: 3,
+        requestHandler: {
+          connectionTimeout: 10_000,
+          requestTimeout: 60_000,
+        },
+      });
+    }
+    return this._client;
+  }
+
+  /**
+   * Send a command through the S3 client with uniform transient-error retry.
+   *
+   * All SDK calls in this module route through here. The default 3-attempt
+   * loop with [5s, 10s] backoff absorbs Hetzner Ceph's typical blip
+   * envelope (one or two failed dispatches followed by recovery). Callers
+   * that need different retry economics — credential-validation prompts
+   * want fast failure, createBucket wants 5×exponential to ride out the
+   * post-delete bucket-name reservation window — pass `maxAttempts` and
+   * `backoffSeconds` explicitly.
+   *
+   * `terminal(error) → boolean` lets the caller short-circuit retry for
+   * conditions that are deterministic outcomes rather than transient
+   * faults (e.g., HeadBucket NotFound is "the bucket doesn't exist", not
+   * "Hetzner blipped"). Without this, NotFound would cost 15s+ of retry
+   * before bucketExists could return false.
+   *
+   * @param {object} command - AWS SDK command instance
+   * @param {object} [opts]
+   * @param {number} [opts.maxAttempts=3]
+   * @param {number[]} [opts.backoffSeconds=[5,10]] - delays BETWEEN attempts; length should be maxAttempts-1 (last entry repeats if shorter)
+   * @param {(error: Error) => boolean} [opts.terminal] - if returns true, throw immediately without retry
+   * @returns {Promise<*>} SDK response
+   */
+  async _send(command, { maxAttempts = 3, backoffSeconds = [5, 10], terminal = null } = {}) {
+    const client = this.getClient();
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        return await client.send(command);
+      } catch (error) {
+        lastError = error;
+        if (terminal?.(error)) throw error;
+        if (isTransientS3Error(error) && attempt < maxAttempts - 1) {
+          const delay = backoffSeconds[Math.min(attempt, backoffSeconds.length - 1)];
+          await new Promise((r) => setTimeout(r, delay * 1000));
+          continue;
+        }
+        throw error;
+      }
+    }
+    // Loop above always returns or throws on the final attempt.
+    throw lastError;
+  }
+
+  /**
+   * Validate credentials by listing buckets
+   * @returns {Promise<{valid: boolean, error?: string}>}
+   */
+  async validateCredentials() {
+    // Tight retry budget tuned for the credential-prompt UX: terminal auth
+    // errors fail fast; transient errors get up to 3 quick re-tries before
+    // we surface "credentials invalid" to the user. We bypass _send's own
+    // retry (`maxAttempts: 1`) so the outer loop here is the single source
+    // of retry, keeping the worst-case wait under ~5s.
+    const terminalNames = new Set(['InvalidAccessKeyId', 'SignatureDoesNotMatch', 'AccessDenied']);
+    const maxAttempts = 3;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        await this._send(new ListBucketsCommand({}), { maxAttempts: 1 });
+        return { valid: true };
+      } catch (error) {
+        lastError = error;
+        if (terminalNames.has(error.name)) break;
+        if (attempt < maxAttempts) {
+          await new Promise((r) => setTimeout(r, 1500 * attempt));
+        }
+      }
+    }
+    if (lastError.name === 'InvalidAccessKeyId') {
+      return { valid: false, error: 'Invalid Access Key ID' };
+    }
+    if (lastError.name === 'SignatureDoesNotMatch') {
+      return { valid: false, error: 'Invalid Secret Key' };
+    }
+    if (lastError.name === 'AccessDenied') {
+      return { valid: false, error: 'Access denied. Check credentials permissions.' };
+    }
+    return {
+      valid: false,
+      error:
+        lastError.message ||
+        lastError.Code ||
+        lastError.name ||
+        `S3 error (HTTP ${lastError.$metadata?.httpStatusCode || 'unknown'})`,
+    };
+  }
+
+  /**
+   * List all buckets
+   * @returns {Promise<Array<{name: string, creationDate: Date}>>}
+   */
+  async listBuckets() {
+    const response = await this._send(new ListBucketsCommand({}));
+    return (response.Buckets || []).map((bucket) => ({
+      name: bucket.Name,
+      creationDate: bucket.CreationDate,
+    }));
+  }
+
+  /**
+   * Check if a bucket exists. NotFound and 403 short-circuit `_send`'s
+   * retry via the terminal classifier — they're deterministic outcomes
+   * (bucket missing / cross-account collision), not Hetzner blips. Only
+   * actual transient errors (TimeoutError, 5xx) get retried by `_send`.
+   * @param {string} bucketName - Bucket name
+   * @returns {Promise<boolean>}
+   */
+  async bucketExists(bucketName) {
+    const command = new HeadBucketCommand({ Bucket: bucketName });
+    try {
+      await this._send(command, {
+        terminal: (err) => {
+          const status = err.$metadata?.httpStatusCode;
+          return err.name === 'NotFound' || status === 404 || status === 403;
+        },
+      });
+      return true;
+    } catch (error) {
+      const status = error.$metadata?.httpStatusCode;
+      if (error.name === 'NotFound' || status === 404) return false;
+      if (status === 403) {
+        throw new Error(
+          `Bucket "${bucketName}" exists but is owned by another account. Try a different project name.`,
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Search all S3 regions for a bucket we own.
+   * Each region's HeadBucket failure is intentionally swallowed — finding
+   * the bucket means we got a success on at least one region; finding it
+   * nowhere means it doesn't exist anywhere we own. We deliberately don't
+   * retry transients here because findBucketRegion is itself a fallback
+   * called from createBucket's BucketAlreadyExists branch — a per-region
+   * blip just means "try the next region", not "give up".
+   * @param {string} bucketName
+   * @returns {Promise<string|null>} The region where the bucket was found, or null
+   */
+  async findBucketRegion(bucketName) {
+    for (const [region, endpoint] of Object.entries(HetznerS3Provider.ENDPOINTS)) {
+      try {
+        const client = new S3Client({
+          region,
+          endpoint,
+          forcePathStyle: true,
+          credentials: {
+            accessKeyId: this.accessKeyId,
+            secretAccessKey: this.secretAccessKey,
+          },
+        });
+        await client.send(new HeadBucketCommand({ Bucket: bucketName }));
+        return region;
+      } catch {
+        // Not in this region or not accessible — try next
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Create a new bucket.
+   *
+   * Outer loop handles two operation-specific conditions that aren't
+   * just "Hetzner blipped":
+   *   - BucketAlreadyExists: Hetzner reserves bucket names for ~30-90s
+   *     after deletion; on a destroy→restore cycle we ride that window
+   *     out with exponential backoff before declaring cross-account
+   *     collision.
+   *   - BucketAlreadyOwnedByYou: success-equivalent — return early.
+   * Transient errors fall through to the same loop's backoff, courtesy
+   * of `_send` (with maxAttempts=1 inside) so we don't double-retry.
+   * @param {string} bucketName - Bucket name (must be globally unique)
+   * @returns {Promise<{name: string, created: boolean}>}
+   */
+  async createBucket(bucketName) {
+    if (await this.bucketExists(bucketName)) {
+      return { name: bucketName, created: false, message: 'Bucket already exists' };
+    }
+
+    const command = new CreateBucketCommand({ Bucket: bucketName });
+    const maxAttempts = 5;
+    const backoffSeconds = [10, 20, 30, 40, 50];
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        await this._send(command, { maxAttempts: 1 });
+        return { name: bucketName, created: true };
+      } catch (error) {
+        if (error.name === 'BucketAlreadyOwnedByYou') {
+          return { name: bucketName, created: false, message: 'Bucket already exists' };
+        }
+        if (isTransientS3Error(error) && attempt < maxAttempts - 1) {
+          await new Promise((r) => setTimeout(r, backoffSeconds[attempt] * 1000));
+          continue;
+        }
+        if (error.name === 'BucketAlreadyExists') {
+          // Hetzner S3 bucket names are globally unique but region-scoped for access.
+          // HeadBucket returns 404 when checking a bucket that lives in a different region.
+          // Try all regions to find the bucket before assuming another account owns it.
+          const foundRegion = await this.findBucketRegion(bucketName);
+          if (foundRegion) {
+            this.region = foundRegion;
+            this.endpoint = HetznerS3Provider.ENDPOINTS[foundRegion];
+            this._client = null;
+            return { name: bucketName, created: false, message: 'Bucket already exists' };
+          }
+          if (attempt < maxAttempts - 1) {
+            // Eventual consistency window — probably our own prior delete
+            // hasn't fully propagated. Wait and retry.
+            await new Promise((r) => setTimeout(r, backoffSeconds[attempt] * 1000));
+            continue;
+          }
+          throw new Error(
+            `Bucket name "${bucketName}" is already taken by another account. Try a different name.`,
+          );
+        }
+        throw error;
+      }
+    }
+    // Unreachable; loop above either returns or throws.
+    throw new Error(`createBucket: unexpected exit after ${maxAttempts} attempts`);
+  }
+
+  /**
+   * Delete a bucket (must be empty).
+   * Outer loop handles BucketNotEmpty (eventual-consistency: object
+   * deletes from emptyAndDeleteBucket may not have fully propagated yet).
+   * Transient errors get retried by `_send` itself; we only wrap
+   * BucketNotEmpty in the operation-specific outer loop here.
+   * @param {string} bucketName - Bucket name
+   */
+  async deleteBucket(bucketName) {
+    for (let attempt = 0; attempt < 5; attempt++) {
+      try {
+        await this._send(new DeleteBucketCommand({ Bucket: bucketName }));
+        return;
+      } catch (err) {
+        const isNotEmpty = err.Code === 'BucketNotEmpty' || err.message?.includes('not empty');
+        if (!isNotEmpty || attempt === 4) throw err;
+        await new Promise((r) => setTimeout(r, 3000 * (attempt + 1)));
+      }
+    }
+  }
+
+  /**
+   * Empty all objects from a bucket and then delete it.
+   * Handles current objects, versioned objects/delete markers, and incomplete
+   * multipart uploads.
+   *
+   * Step errors that look like "API not supported by provider" (NotImplemented,
+   * MethodNotAllowed, 405/501) are tolerated and recorded as warnings — not all
+   * S3-compatible providers expose ListObjectVersions / multipart listing.
+   * Real errors (timeouts, 5xx, auth) propagate so callers can surface them
+   * instead of getting an opaque BucketNotEmpty downstream.
+   *
+   * If `deleteBucket` finally fails with BucketNotEmpty, the thrown error is
+   * enriched with a fresh listing summary so the operator can see exactly
+   * what's left blocking deletion.
+   *
+   * @param {string} bucketName
+   * @returns {Promise<{deleted: boolean, objectsRemoved: number, warnings: string[]}>}
+   */
+  async emptyAndDeleteBucket(bucketName) {
+    let objectsRemoved = 0;
+    const warnings = [];
+
+    // 1. Delete current objects via ListObjectsV2.
+    let continuationToken;
+    do {
+      const listResult = await this._send(
+        new ListObjectsV2Command({ Bucket: bucketName, ContinuationToken: continuationToken }),
+      );
+      if (listResult.Contents?.length > 0) {
+        await this._send(
+          new DeleteObjectsCommand({
+            Bucket: bucketName,
+            Delete: { Objects: listResult.Contents.map((obj) => ({ Key: obj.Key })) },
+          }),
+        );
+        objectsRemoved += listResult.Contents.length;
+      }
+      continuationToken = listResult.IsTruncated ? listResult.NextContinuationToken : undefined;
+    } while (continuationToken);
+
+    // 2. Delete all object versions and delete markers (required for versioned
+    // buckets — without this, DeleteBucket fails with BucketNotEmpty even after
+    // removing current objects).
+    try {
+      let keyMarker;
+      let versionIdMarker;
+      do {
+        const versionsResult = await this._send(
+          new ListObjectVersionsCommand({
+            Bucket: bucketName,
+            KeyMarker: keyMarker,
+            VersionIdMarker: versionIdMarker,
+          }),
+        );
+        const toDelete = [
+          ...(versionsResult.Versions || []).map((v) => ({ Key: v.Key, VersionId: v.VersionId })),
+          ...(versionsResult.DeleteMarkers || []).map((d) => ({
+            Key: d.Key,
+            VersionId: d.VersionId,
+          })),
+        ];
+        if (toDelete.length > 0) {
+          await this._send(
+            new DeleteObjectsCommand({ Bucket: bucketName, Delete: { Objects: toDelete } }),
+          );
+          objectsRemoved += toDelete.length;
+        }
+        keyMarker = versionsResult.IsTruncated ? versionsResult.NextKeyMarker : undefined;
+        versionIdMarker = versionsResult.IsTruncated
+          ? versionsResult.NextVersionIdMarker
+          : undefined;
+      } while (keyMarker);
+    } catch (err) {
+      if (HetznerS3Provider._isUnsupportedApiError(err)) {
+        warnings.push(`ListObjectVersions not supported by provider: ${err.name || err.message}`);
+      } else {
+        throw new Error(`Failed to list/delete object versions in ${bucketName}: ${err.message}`, {
+          cause: err,
+        });
+      }
+    }
+
+    // 3. Abort incomplete multipart uploads (can also prevent bucket deletion).
+    try {
+      const uploads = await this._send(new ListMultipartUploadsCommand({ Bucket: bucketName }));
+      for (const upload of uploads.Uploads || []) {
+        await this._send(
+          new AbortMultipartUploadCommand({
+            Bucket: bucketName,
+            Key: upload.Key,
+            UploadId: upload.UploadId,
+          }),
+        );
+      }
+    } catch (err) {
+      if (HetznerS3Provider._isUnsupportedApiError(err)) {
+        warnings.push(`ListMultipartUploads not supported by provider: ${err.name || err.message}`);
+      } else {
+        throw new Error(`Failed to abort multipart uploads in ${bucketName}: ${err.message}`, {
+          cause: err,
+        });
+      }
+    }
+
+    // Now delete the empty bucket. On BucketNotEmpty (eventual consistency
+    // OR a step above silently undercounted), enrich the error with a fresh
+    // listing summary so operators don't have to open the Hetzner console
+    // to figure out what's left.
+    try {
+      await this.deleteBucket(bucketName);
+    } catch (err) {
+      const isNotEmpty = err.Code === 'BucketNotEmpty' || /not empty/i.test(err.message ?? '');
+      if (!isNotEmpty) throw err;
+      const summary = await this._summarizeBucketContents(bucketName);
+      const enriched = new Error(`${bucketName} is not empty after cleanup: ${summary}`);
+      enriched.cause = err;
+      enriched.bucketSummary = summary;
+      throw enriched;
+    }
+    return { deleted: true, objectsRemoved, warnings };
+  }
+
+  /**
+   * Best-effort listing of remaining bucket contents for diagnostics. Used
+   * when DeleteBucket fails with BucketNotEmpty — returns a one-line summary
+   * like `47 objects (e.g. .placeholder, public/avatar.png), 3 versions + 1
+   * delete marker, 2 incomplete multipart uploads`. Each section is
+   * independently try/caught so partial visibility beats none.
+   * @param {string} bucketName
+   * @returns {Promise<string>}
+   */
+  async _summarizeBucketContents(bucketName) {
+    const parts = [];
+
+    try {
+      const r = await this._send(new ListObjectsV2Command({ Bucket: bucketName, MaxKeys: 5 }), {
+        maxAttempts: 1,
+      });
+      const count = r.KeyCount ?? r.Contents?.length ?? 0;
+      if (count > 0) {
+        const examples = (r.Contents ?? [])
+          .slice(0, 3)
+          .map((o) => o.Key)
+          .join(', ');
+        const more = r.IsTruncated ? '+' : '';
+        parts.push(`${count}${more} objects (e.g. ${examples})`);
+      }
+    } catch (err) {
+      parts.push(`object listing failed: ${err.name || err.message}`);
+    }
+
+    try {
+      const r = await this._send(
+        new ListObjectVersionsCommand({ Bucket: bucketName, MaxKeys: 5 }),
+        { maxAttempts: 1 },
+      );
+      const versionCount = (r.Versions ?? []).length;
+      const markerCount = (r.DeleteMarkers ?? []).length;
+      if (versionCount + markerCount > 0) {
+        parts.push(
+          `${versionCount} version${versionCount === 1 ? '' : 's'} + ${markerCount} delete marker${markerCount === 1 ? '' : 's'}`,
+        );
+      }
+    } catch {
+      // versioning API absent — covered by primary listing
+    }
+
+    try {
+      const r = await this._send(new ListMultipartUploadsCommand({ Bucket: bucketName }), {
+        maxAttempts: 1,
+      });
+      const uploadCount = (r.Uploads ?? []).length;
+      if (uploadCount > 0) {
+        parts.push(`${uploadCount} incomplete multipart upload${uploadCount === 1 ? '' : 's'}`);
+      }
+    } catch {
+      // multipart API absent — covered above
+    }
+
+    return parts.length > 0 ? parts.join(', ') : 'unable to list remaining contents';
+  }
+
+  /**
+   * Heuristic: does this S3 error mean "the provider doesn't expose this API"
+   * vs. a transient or auth failure that we should surface? AWS standard
+   * error codes plus a few HTTP status fallbacks for non-AWS providers.
+   */
+  static _isUnsupportedApiError(err) {
+    const name = err?.name ?? '';
+    const code = err?.Code ?? '';
+    const status = err?.$metadata?.httpStatusCode;
+    if (name === 'NotImplemented' || code === 'NotImplemented') return true;
+    if (name === 'MethodNotAllowed' || code === 'MethodNotAllowed') return true;
+    if (status === 405 || status === 501) return true;
+    return false;
+  }
+
+  /**
+   * Configure CORS policy for browser uploads
+   * @param {string} bucketName - Bucket name
+   * @param {string[]} [allowedOrigins=['*']] - Allowed origins
+   * @returns {Promise<void>}
+   */
+  async configureCORS(bucketName, allowedOrigins = ['*']) {
+    const command = new PutBucketCorsCommand({
+      Bucket: bucketName,
+      CORSConfiguration: {
+        CORSRules: [
+          {
+            AllowedHeaders: ['*'],
+            AllowedMethods: ['GET', 'PUT', 'POST', 'DELETE', 'HEAD'],
+            AllowedOrigins: allowedOrigins,
+            ExposeHeaders: ['ETag', 'Content-Length', 'Content-Type'],
+            MaxAgeSeconds: 3600,
+          },
+        ],
+      },
+    });
+    await this._send(command);
+  }
+
+  /**
+   * Get the S3 endpoint URL for this region
+   * @returns {string}
+   */
+  getEndpoint() {
+    return this.endpoint;
+  }
+
+  /**
+   * Get all available regions
+   * @returns {Object<string, string>}
+   */
+  static getRegions() {
+    return HetznerS3Provider.REGIONS;
+  }
+
+  /**
+   * Get endpoint for a specific region
+   * @param {string} region - Region ID
+   * @returns {string|null}
+   */
+  static getEndpointForRegion(region) {
+    return HetznerS3Provider.ENDPOINTS[region] || null;
+  }
+
+  /**
+   * Resolve the nearest S3 region for a given deployment region.
+   * Returns the region itself if S3 is available there, otherwise maps to the closest one.
+   */
+  static resolveS3Region(deployRegion) {
+    if (HetznerS3Provider.ENDPOINTS[deployRegion]) return deployRegion;
+
+    // Map non-S3 regions to nearest S3 region
+    // hel1 is the only non-German EU S3 region, so EU regions map to fsn1 (central Germany)
+    // US regions also map to nearest EU S3 (no US S3 available)
+    const regionMap = {
+      ash: 'fsn1', // Ashburn, VA → Falkenstein (lowest latency EU)
+      hil: 'fsn1', // Hillsboro, OR → Falkenstein
+      sin: 'hel1', // Singapore → Helsinki (if ever added)
+    };
+    return regionMap[deployRegion] || 'fsn1';
+  }
+}
+
+/**
+ * Sanitize a project name into a valid S3 bucket name
+ * S3 bucket naming rules:
+ * - 3-63 characters
+ * - Lowercase letters, numbers, and hyphens only
+ * - Must start and end with letter or number
+ * - No consecutive periods or adjacent period/hyphen
+ *
+ * @param {string} projectName - Project name to sanitize
+ * @param {string} [suffix='storage'] - Suffix to append
+ * @returns {string} - Valid bucket name
+ */
+export function sanitizeBucketName(projectName, suffix = 'storage') {
+  const baseName = suffix ? `${projectName}-${suffix}` : projectName;
+
+  return baseName
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-') // Replace invalid chars with hyphens
+    .replace(/-+/g, '-') // Collapse multiple hyphens
+    .replace(/^-|-$/g, '') // Remove leading/trailing hyphens
+    .slice(0, 63); // Truncate to max length
+}