@taodigital/app-brain 0.0.0-stage → 1.2.0

package/src/cloud-storage.ts

@@ -0,0 +1,627 @@
+/**
+ * Cloud Storage integration for ZeTa-AI artifacts.
+ *
+ * Folder convention:
+ *   {prefix}/{tenantId}/{projectId}/screenshots/{filename}
+ *   {prefix}/{tenantId}/{projectId}/test-plans/{filename}
+ *   {prefix}/{tenantId}/{projectId}/test-data/{filename}
+ *   {prefix}/{tenantId}/{projectId}/reports/{runId}/{filename}
+ *
+ * Industry reference: Playwright Cloud, BrowserStack, Cypress Cloud all use
+ * tenant→project→type→artifact path hierarchies for multi-tenant isolation.
+ */
+
+import { withTenant } from '@taodigital/database';
+import { decrypt, config as platformConfig, getSystemConfig } from '@taodigital/core';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+type StorageKind = 'S3' | 'R2' | 'GDRIVE' | 'DROPBOX';
+
+interface StorageConfig {
+  kind: StorageKind;
+  creds: Record<string, string>;
+  prefix: string;
+}
+
+function decryptConfig(raw: any): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(raw ?? {})) {
+    if (key.endsWith('_enc') && typeof value === 'string') {
+      try { out[key.replace('_enc', '')] = decrypt(value); } catch { out[key.replace('_enc', '')] = ''; }
+    } else {
+      out[key] = value as string;
+    }
+  }
+  return out;
+}
+
+export interface TenantStorageConfig {
+  provider: 'S3' | 'R2';
+  bucket: string;
+  region?: string;
+  accountId?: string;
+  endpointUrl?: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  publicUrl?: string;
+  prefix?: string;
+}
+
+/** Resolve the platform-managed default bucket from Platform Admin config first,
+ *  then env vars (AWS_S3_BUCKET / PLATFORM_S3_BUCKET). Used as a fallback for
+ *  tenants who haven't set up their own storage connector. accessKeyId/
+ *  secretAccessKey are optional: when unset, buildS3Client() falls back to the
+ *  AWS SDK's default credential provider chain (e.g. an ECS task IAM role). */
+async function getPlatformStorageConfig(): Promise<TenantStorageConfig | null> {
+  const adminCfg = await getSystemConfig('storage').catch(() => ({} as Record<string, string>));
+  const p = platformConfig.platformStorage;
+  const bucket = adminCfg.bucket ?? p.bucket;
+  const accountId = adminCfg.accountId ?? p.accountId;
+  const providerRaw = (adminCfg.provider ?? p.provider ?? (accountId ? 'R2' : bucket ? 'S3' : '')).toUpperCase();
+  const provider = providerRaw === 'R2' ? 'R2' : providerRaw === 'S3' ? 'S3' : null;
+  if (!provider || !bucket) return null;
+  return {
+    provider,
+    bucket,
+    region: adminCfg.region ?? p.region,
+    accountId,
+    endpointUrl: adminCfg.endpointUrl ?? p.endpointUrl,
+    accessKeyId: adminCfg.accessKeyId ?? p.accessKeyId ?? '',
+    secretAccessKey: adminCfg.secretAccessKey ?? p.secretAccessKey ?? '',
+    publicUrl: adminCfg.publicUrl ?? p.publicUrl,
+    prefix: adminCfg.prefix ?? p.prefix,
+  };
+}
+
+/**
+ * Resolves the storage config to use for a tenant's screenshots/artifacts:
+ * the tenant's own connector if they've configured one, otherwise the
+ * platform-managed default bucket (if configured via env vars), otherwise
+ * null — meaning the caller should leave the artifact on local disk.
+ */
+export async function getTenantStorageConfig(tenantId: string): Promise<TenantStorageConfig | null> {
+  const { withTenant: wt } = await import('@taodigital/database');
+  const setting = await wt(tenantId, (tx: any) =>
+    tx.tenantSetting.findUnique({ where: { tenantId_category: { tenantId, category: 'STORAGE' } } })
+  ) as { config: any } | null;
+  const raw = setting?.config as Record<string, any> | undefined;
+  if (raw?.bucket && raw?.accessKeyId && raw?.secretAccessKey_enc) {
+    try {
+      return {
+        provider: (raw.provider as 'S3' | 'R2') ?? 'S3',
+        bucket: raw.bucket,
+        region: raw.region ?? undefined,
+        accountId: raw.accountId ?? undefined,
+        endpointUrl: raw.endpointUrl ?? undefined,
+        accessKeyId: raw.accessKeyId,
+        secretAccessKey: decrypt(raw.secretAccessKey_enc),
+        publicUrl: raw.publicUrl ?? undefined,
+        prefix: raw.prefix ?? undefined,
+      };
+    } catch { /* fall through to platform default below */ }
+  }
+  return getPlatformStorageConfig();
+}
+
+/**
+ * Upload a screenshot to tenant-level S3/R2 storage.
+ * Returns public URL if publicUrl configured, otherwise returns the storage key
+ * (callers should use resolveCloudUrl() to generate presigned URLs on demand).
+ */
+export async function uploadScreenshotToTenantStorage(
+  cfg: TenantStorageConfig,
+  localPath: string,
+  screenshotKey: string,
+): Promise<string> {
+  const isR2 = cfg.provider === 'R2';
+  const creds = {
+    bucket: cfg.bucket,
+    region: cfg.region ?? 'auto',
+    accountId: cfg.accountId ?? '',
+    endpointUrl: cfg.endpointUrl ?? '',
+    accessKeyId: cfg.accessKeyId,
+    secretAccessKey: cfg.secretAccessKey,
+  };
+  await s3Upload(creds, localPath, screenshotKey, 'image/png', isR2);
+  if (cfg.publicUrl) {
+    const base = cfg.publicUrl.replace(/\/$/, '');
+    return `${base}/${screenshotKey}`;
+  }
+  return screenshotKey;
+}
+
+/**
+ * Upload any file to tenant-level S3/R2 storage.
+ * Returns public URL if publicUrl configured, otherwise returns the storage key.
+ */
+export async function uploadFileToTenantStorage(
+  cfg: TenantStorageConfig,
+  localPath: string,
+  storageKey: string,
+  contentType: string,
+): Promise<string> {
+  const isR2 = cfg.provider === 'R2';
+  const creds = {
+    bucket: cfg.bucket,
+    region: cfg.region ?? 'auto',
+    accountId: cfg.accountId ?? '',
+    endpointUrl: cfg.endpointUrl ?? '',
+    accessKeyId: cfg.accessKeyId,
+    secretAccessKey: cfg.secretAccessKey,
+  };
+  await s3Upload(creds, localPath, storageKey, contentType, isR2);
+  if (cfg.publicUrl) {
+    const base = cfg.publicUrl.replace(/\/$/, '');
+    return `${base}/${storageKey}`;
+  }
+  return storageKey;
+}
+
+/**
+ * Resolve a stored cloudUrl to a usable URL for the browser.
+ * - If it starts with https:// → return as-is (public URL, no expiry).
+ * - Otherwise → treat as storage key and generate a presigned GET URL.
+ */
+export async function resolveCloudUrl(
+  cfg: TenantStorageConfig,
+  cloudUrl: string,
+  expiresIn = 3600,
+): Promise<string | null> {
+  if (cloudUrl.startsWith('https://') || cloudUrl.startsWith('http://')) {
+    return cloudUrl;
+  }
+  return generatePresignedGetUrl(cfg, cloudUrl, expiresIn);
+}
+
+export async function getProjectStorageConfig(tenantId: string, projectId: string): Promise<StorageConfig | null> {
+  const connector = await withTenant(tenantId, (tx) =>
+    (tx as any).connector.findFirst({
+      where: { tenantId, projectId, kind: { in: ['S3', 'R2', 'GDRIVE', 'DROPBOX'] } },
+    })
+  ) as { kind: string; config: any } | null;
+  if (connector) {
+    const creds = decryptConfig(connector.config);
+    return { kind: connector.kind as StorageKind, creds, prefix: creds.prefix ?? '' };
+  }
+
+  const tenantCfg = await getTenantStorageConfig(tenantId);
+  if (!tenantCfg) return null;
+  return {
+    kind: tenantCfg.provider,
+    prefix: tenantCfg.prefix ?? '',
+    creds: {
+      bucket: tenantCfg.bucket,
+      region: tenantCfg.region ?? '',
+      accountId: tenantCfg.accountId ?? '',
+      endpointUrl: tenantCfg.endpointUrl ?? '',
+      accessKeyId: tenantCfg.accessKeyId,
+      secretAccessKey: tenantCfg.secretAccessKey,
+      publicUrl: tenantCfg.publicUrl ?? '',
+      prefix: tenantCfg.prefix ?? '',
+    },
+  };
+}
+
+/** Build the cloud storage key for an artifact. */
+export function buildArtifactKey(tenantId: string, projectId: string, type: string, filename: string, prefix = ''): string {
+  return [prefix, tenantId, projectId, type, filename].filter(Boolean).join('/');
+}
+
+/** Upload a single file to the configured cloud storage provider. Returns storage key/path. */
+export async function uploadArtifact(
+  cfg: StorageConfig,
+  localPath: string,
+  storageKey: string,
+  contentType = 'application/octet-stream',
+): Promise<string> {
+  switch (cfg.kind) {
+    case 'S3': return s3Upload(cfg.creds, localPath, storageKey, contentType, false);
+    case 'R2': return s3Upload(cfg.creds, localPath, storageKey, contentType, true);
+    case 'GDRIVE': return gdriveUpload(cfg.creds, localPath, storageKey, contentType);
+    case 'DROPBOX': return dropboxUpload(cfg.creds, localPath, storageKey);
+    default: throw new Error(`Unknown storage provider: ${cfg.kind}`);
+  }
+}
+
+/** Upload a Buffer (for generated content like test plans, scripts). */
+export async function uploadArtifactBuffer(
+  cfg: StorageConfig,
+  buffer: Buffer,
+  storageKey: string,
+  contentType = 'text/plain; charset=utf-8',
+): Promise<string> {
+  switch (cfg.kind) {
+    case 'S3': return s3UploadBuffer(cfg.creds, buffer, storageKey, contentType, false);
+    case 'R2': return s3UploadBuffer(cfg.creds, buffer, storageKey, contentType, true);
+    case 'GDRIVE': return gdriveUploadBuffer(cfg.creds, buffer, storageKey, contentType);
+    case 'DROPBOX': return dropboxUploadBuffer(cfg.creds, buffer, storageKey);
+    default: throw new Error(`Unknown storage provider: ${cfg.kind}`);
+  }
+}
+
+// ── S3 / R2 ─────────────────────────────────────────────────────────────────
+
+function buildS3Client(creds: Record<string, string>, isR2: boolean) {
+  const { S3Client } = require('@aws-sdk/client-s3');
+  const endpoint = isR2 ? `https://${creds.accountId}.r2.cloudflarestorage.com` : creds.endpointUrl;
+  return new S3Client({
+    region: isR2 ? 'auto' : (creds.region || 'us-east-1'),
+    // No explicit key pair (e.g. platform-default bucket on ECS with a task IAM
+    // role) — omit `credentials` entirely so the SDK's default provider chain
+    // (env vars, IMDS, task role) resolves them instead of an empty key pair.
+    ...(creds.accessKeyId && creds.secretAccessKey
+      ? { credentials: { accessKeyId: creds.accessKeyId, secretAccessKey: creds.secretAccessKey } }
+      : {}),
+    ...(endpoint ? { endpoint, forcePathStyle: true } : {}),
+  });
+}
+
+async function s3Upload(creds: Record<string, string>, localPath: string, key: string, ct: string, isR2: boolean): Promise<string> {
+  const { PutObjectCommand } = require('@aws-sdk/client-s3');
+  const { createReadStream } = require('node:fs');
+  const client = buildS3Client(creds, isR2);
+  await client.send(new PutObjectCommand({ Bucket: creds.bucket, Key: key, Body: createReadStream(localPath), ContentType: ct }));
+  return key;
+}
+
+async function s3UploadBuffer(creds: Record<string, string>, buffer: Buffer, key: string, ct: string, isR2: boolean): Promise<string> {
+  const { PutObjectCommand } = require('@aws-sdk/client-s3');
+  const client = buildS3Client(creds, isR2);
+  await client.send(new PutObjectCommand({ Bucket: creds.bucket, Key: key, Body: buffer, ContentType: ct }));
+  return key;
+}
+
+async function s3PresignedGetUrl(creds: Record<string, string>, key: string, isR2: boolean, expiresIn: number): Promise<string> {
+  const { GetObjectCommand } = require('@aws-sdk/client-s3');
+  const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');
+  const client = buildS3Client(creds, isR2);
+  return getSignedUrl(client, new GetObjectCommand({ Bucket: creds.bucket, Key: key }), { expiresIn });
+}
+
+async function s3DownloadBuffer(creds: Record<string, string>, key: string, isR2: boolean): Promise<Buffer> {
+  const { GetObjectCommand } = require('@aws-sdk/client-s3');
+  const client = buildS3Client(creds, isR2);
+  const res = await client.send(new GetObjectCommand({ Bucket: creds.bucket, Key: key }));
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of (res.Body as any)) chunks.push(chunk);
+  return Buffer.concat(chunks);
+}
+
+// ── Google Drive ─────────────────────────────────────────────────────────────
+
+async function getGDriveToken(sa: { client_email: string; private_key: string }): Promise<string> {
+  const { createSign } = require('node:crypto');
+  const now = Math.floor(Date.now() / 1000);
+  const header = Buffer.from(JSON.stringify({ alg: 'RS256', typ: 'JWT' })).toString('base64url');
+  const payload = Buffer.from(JSON.stringify({
+    iss: sa.client_email,
+    scope: 'https://www.googleapis.com/auth/drive',
+    aud: 'https://oauth2.googleapis.com/token',
+    iat: now, exp: now + 3600,
+  })).toString('base64url');
+  const sigInput = `${header}.${payload}`;
+  const sign = createSign('RSA-SHA256');
+  sign.update(sigInput);
+  const jwt = `${sigInput}.${sign.sign(sa.private_key, 'base64url')}`;
+  const res = await fetch('https://oauth2.googleapis.com/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({ grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer', assertion: jwt }),
+  });
+  if (!res.ok) throw new Error(`GDrive token error: ${await res.text()}`);
+  return ((await res.json()) as any).access_token;
+}
+
+async function gdriveUpload(creds: Record<string, string>, localPath: string, key: string, ct: string): Promise<string> {
+  return gdriveUploadBuffer(creds, readFileSync(localPath), key, ct);
+}
+
+async function gdriveUploadBuffer(creds: Record<string, string>, buffer: Buffer, key: string, ct: string): Promise<string> {
+  const sa = JSON.parse(creds.serviceAccountJson);
+  const token = await getGDriveToken(sa);
+  const name = path.basename(key);
+  const boundary = 'ZeTa_b';
+  const body = `--${boundary}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n${JSON.stringify({ name, parents: creds.folderId ? [creds.folderId] : [] })}\r\n--${boundary}\r\nContent-Type: ${ct}\r\n\r\n`;
+  const tail = `\r\n--${boundary}--`;
+  const full = Buffer.concat([Buffer.from(body), buffer, Buffer.from(tail)]);
+  const res = await fetch('https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': `multipart/related; boundary=${boundary}` },
+    body: full,
+  });
+  if (!res.ok) throw new Error(`GDrive upload failed: ${await res.text()}`);
+  return ((await res.json()) as any).id as string;
+}
+
+// ── Dropbox ──────────────────────────────────────────────────────────────────
+
+async function dropboxUpload(creds: Record<string, string>, localPath: string, key: string): Promise<string> {
+  return dropboxUploadBuffer(creds, readFileSync(localPath), key);
+}
+
+async function dropboxUploadBuffer(creds: Record<string, string>, buffer: Buffer, key: string): Promise<string> {
+  const folder = creds.folderPath ?? '/ZeTa-AI';
+  const dropboxPath = `${folder}/${key}`.replace(/\/+/g, '/');
+  const res = await fetch('https://content.dropboxapi.com/2/files/upload', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${creds.accessToken}`,
+      'Dropbox-API-Arg': JSON.stringify({ path: dropboxPath, mode: 'overwrite' }),
+      'Content-Type': 'application/octet-stream',
+    },
+    body: new Uint8Array(buffer),
+  });
+  if (!res.ok) throw new Error(`Dropbox upload failed: ${await res.text()}`);
+  return dropboxPath;
+}
+
+async function gdriveDownloadBuffer(creds: Record<string, string>, fileId: string): Promise<Buffer> {
+  const sa = JSON.parse(creds.serviceAccountJson);
+  const token = await getGDriveToken(sa);
+  const res = await fetch(`https://www.googleapis.com/drive/v3/files/${fileId}?alt=media`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!res.ok) throw new Error(`GDrive download failed: ${await res.text()}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+async function dropboxDownloadBuffer(creds: Record<string, string>, dropboxPath: string): Promise<Buffer> {
+  const res = await fetch('https://content.dropboxapi.com/2/files/download', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${creds.accessToken}`,
+      'Dropbox-API-Arg': JSON.stringify({ path: dropboxPath }),
+    },
+  });
+  if (!res.ok) throw new Error(`Dropbox download failed: ${await res.text()}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Generate a presigned GET URL for S3/R2 (time-limited, auth-gated).
+ * GDrive/Dropbox: returns null (caller must use downloadBufferFromTenantStorage + proxy).
+ */
+export async function generatePresignedGetUrl(
+  cfg: TenantStorageConfig,
+  storageKey: string,
+  expiresIn = 3600,
+): Promise<string | null> {
+  if (cfg.provider === 'S3' || cfg.provider === 'R2') {
+    const isR2 = cfg.provider === 'R2';
+    const creds: Record<string, string> = {
+      bucket: cfg.bucket,
+      region: cfg.region ?? 'auto',
+      accountId: cfg.accountId ?? '',
+      endpointUrl: cfg.endpointUrl ?? '',
+      accessKeyId: cfg.accessKeyId,
+      secretAccessKey: cfg.secretAccessKey,
+    };
+    return s3PresignedGetUrl(creds, storageKey, isR2, expiresIn);
+  }
+  return null;
+}
+
+/**
+ * Download raw bytes from tenant storage (for GDrive/Dropbox proxy, or fallback).
+ */
+export async function downloadBufferFromTenantStorage(
+  cfg: TenantStorageConfig,
+  storageKey: string,
+): Promise<Buffer> {
+  const isR2 = cfg.provider === 'R2';
+  const creds = {
+    bucket: cfg.bucket,
+    region: cfg.region ?? 'auto',
+    accountId: cfg.accountId ?? '',
+    endpointUrl: cfg.endpointUrl ?? '',
+    accessKeyId: cfg.accessKeyId,
+    secretAccessKey: cfg.secretAccessKey,
+  };
+  return s3DownloadBuffer(creds, storageKey, isR2);
+}
+
+/** Upload a buffer to tenant storage. Returns the storage key. */
+export async function uploadBufferToTenantStorage(
+  cfg: TenantStorageConfig,
+  buffer: Buffer,
+  storageKey: string,
+  contentType = 'application/octet-stream',
+): Promise<string> {
+  const isR2 = cfg.provider === 'R2';
+  const creds = {
+    bucket: cfg.bucket,
+    region: cfg.region ?? 'auto',
+    accountId: cfg.accountId ?? '',
+    endpointUrl: cfg.endpointUrl ?? '',
+    accessKeyId: cfg.accessKeyId,
+    secretAccessKey: cfg.secretAccessKey,
+  };
+  return s3UploadBuffer(creds, buffer, storageKey, contentType, isR2);
+}
+
+/** Build the canonical storage key for a knowledge artifact. */
+export function buildKnowledgeKey(tenantId: string, projectId: string, artifactId: string, filename: string, prefix?: string): string {
+  return [prefix, tenantId, projectId, 'knowledge', artifactId, filename].filter(Boolean).join('/');
+}
+
+export interface StorageObject {
+  key: string;
+  size: number;
+  lastModified: string | null;
+}
+
+/** List all S3/R2 objects under a project prefix. Paginates automatically. */
+export async function listProjectStorageObjects(
+  cfg: TenantStorageConfig,
+  tenantId: string,
+  projectId: string,
+): Promise<StorageObject[]> {
+  const { ListObjectsV2Command } = require('@aws-sdk/client-s3');
+  const isR2 = cfg.provider === 'R2';
+  const creds: Record<string, string> = {
+    bucket: cfg.bucket,
+    region: cfg.region ?? 'auto',
+    accountId: cfg.accountId ?? '',
+    endpointUrl: cfg.endpointUrl ?? '',
+    accessKeyId: cfg.accessKeyId,
+    secretAccessKey: cfg.secretAccessKey,
+  };
+  const client = buildS3Client(creds, isR2);
+  const prefix = [cfg.prefix, tenantId, projectId].filter(Boolean).join('/') + '/';
+  const objects: StorageObject[] = [];
+  let continuationToken: string | undefined;
+
+  do {
+    const res = await client.send(new ListObjectsV2Command({
+      Bucket: cfg.bucket,
+      Prefix: prefix,
+      ContinuationToken: continuationToken,
+      MaxKeys: 1000,
+    }));
+    for (const obj of (res.Contents ?? [])) {
+      objects.push({ key: obj.Key!, size: obj.Size ?? 0, lastModified: obj.LastModified ? obj.LastModified.toISOString() : null });
+    }
+    continuationToken = res.IsTruncated ? res.NextContinuationToken : undefined;
+  } while (continuationToken);
+
+  return objects;
+}
+
+/**
+ * Delete all S3/R2 objects under a project prefix (GDPR cleanup on project delete).
+ * Batch-deletes in groups of 1 000 (S3 DeleteObjects limit).
+ * No-ops silently when cfg is null.
+ */
+export async function deleteProjectStorageObjects(
+  tenantId: string,
+  projectId: string,
+): Promise<void> {
+  const cfg = await getTenantStorageConfig(tenantId);
+  if (!cfg) return;
+  const objects = await listProjectStorageObjects(cfg, tenantId, projectId);
+  if (objects.length === 0) return;
+  const { DeleteObjectsCommand } = require('@aws-sdk/client-s3');
+  const isR2 = cfg.provider === 'R2';
+  const creds: Record<string, string> = {
+    bucket: cfg.bucket,
+    region: cfg.region ?? 'auto',
+    accountId: cfg.accountId ?? '',
+    endpointUrl: cfg.endpointUrl ?? '',
+    accessKeyId: cfg.accessKeyId,
+    secretAccessKey: cfg.secretAccessKey,
+  };
+  const client = buildS3Client(creds, isR2);
+  for (let i = 0; i < objects.length; i += 1000) {
+    const batch = objects.slice(i, i + 1000).map((o) => ({ Key: o.key }));
+    await client.send(new DeleteObjectsCommand({ Bucket: cfg.bucket, Delete: { Objects: batch, Quiet: true } }));
+  }
+}
+
+/**
+ * Delete all S3/R2 objects for an entire tenant (GDPR cleanup on tenant delete).
+ * Lists by tenant prefix and batch-deletes everything found.
+ * No-ops silently when cfg is null.
+ */
+export async function deleteTenantStorageObjects(
+  tenantId: string,
+): Promise<void> {
+  const cfg = await getTenantStorageConfig(tenantId);
+  if (!cfg) return;
+  const { ListObjectsV2Command, DeleteObjectsCommand } = require('@aws-sdk/client-s3');
+  const isR2 = cfg.provider === 'R2';
+  const creds: Record<string, string> = {
+    bucket: cfg.bucket,
+    region: cfg.region ?? 'auto',
+    accountId: cfg.accountId ?? '',
+    endpointUrl: cfg.endpointUrl ?? '',
+    accessKeyId: cfg.accessKeyId,
+    secretAccessKey: cfg.secretAccessKey,
+  };
+  const client = buildS3Client(creds, isR2);
+  const prefix = [cfg.prefix, tenantId].filter(Boolean).join('/') + '/';
+  let continuationToken: string | undefined;
+  do {
+    const res = await client.send(new ListObjectsV2Command({
+      Bucket: cfg.bucket,
+      Prefix: prefix,
+      ContinuationToken: continuationToken,
+      MaxKeys: 1000,
+    }));
+    const keys = (res.Contents ?? []).map((o: any) => ({ Key: o.Key! }));
+    if (keys.length > 0) {
+      await client.send(new DeleteObjectsCommand({ Bucket: cfg.bucket, Delete: { Objects: keys, Quiet: true } }));
+    }
+    continuationToken = res.IsTruncated ? res.NextContinuationToken : undefined;
+  } while (continuationToken);
+}
+
+// ── DB→S3 Content Pointer Helpers (doc 18) ────────────────────────────────────
+//
+// These implement the DB→S3 pointer pattern: large content fields (script code,
+// artifact markdown, test case steps/gherkin) are stored in tenant S3 when
+// configured, with only an object key kept in the DB column. When tenant S3
+// is not configured, content stays in the DB and the key field remains NULL.
+//
+// Key convention: {prefix}/{tenantId}/{projectId}/{type}/{entityId}.{ext}
+//   type: "scripts" | "artifacts" | "testcases"
+//   ext:  "ts" | "md" | "json" | "feature"
+
+/** Build a content object key for a specific entity type. */
+export function buildContentKey(
+  tenantId: string,
+  projectId: string,
+  type: 'scripts' | 'artifacts' | 'testcases',
+  entityId: string,
+  ext: string,
+  prefix?: string,
+): string {
+  return [prefix, tenantId, projectId, type, `${entityId}.${ext}`].filter(Boolean).join('/');
+}
+
+/**
+ * Persist string content to tenant S3 if configured.
+ * Returns the storage key on success, or null if no S3 is configured
+ * (caller should keep content in the DB column in that case).
+ */
+export async function persistContent(
+  tenantId: string,
+  projectId: string,
+  type: 'scripts' | 'artifacts' | 'testcases',
+  entityId: string,
+  ext: string,
+  content: string,
+  mimeType = 'text/plain; charset=utf-8',
+): Promise<string | null> {
+  try {
+    const cfg = await getTenantStorageConfig(tenantId);
+    if (!cfg) return null;
+    const key = buildContentKey(tenantId, projectId, type, entityId, ext, cfg.prefix);
+    await uploadBufferToTenantStorage(cfg, Buffer.from(content, 'utf-8'), key, mimeType);
+    return key;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve content: if a storage key is provided, download from S3.
+ * Otherwise (or on error) return the fallback DB content.
+ */
+export async function resolveContent(
+  tenantId: string,
+  storageKey: string | null | undefined,
+  fallback: string,
+): Promise<string> {
+  if (!storageKey) return fallback;
+  try {
+    const cfg = await getTenantStorageConfig(tenantId);
+    if (!cfg) return fallback;
+    const buf = await downloadBufferFromTenantStorage(cfg, storageKey);
+    return buf.toString('utf-8');
+  } catch {
+    return fallback;
+  }
+}