Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript
23.8 KB
Raw Blame
/**
 * Object-storage abstraction. Two backends — `LocalStorage` writes to disk
 * for dev, `R2Storage` (S3-compatible) talks to Cloudflare R2 (or any
 * S3-API bucket) and emits presigned URLs.
 *
 * Why two: local dev shouldn't require a bucket; prod shouldn't require
 * a shared filesystem. Selection is automatic — if all `R2_*` env vars are
 * present we flip to R2, otherwise we fall back to disk. Callers (router,
 * avatar-gen) never care which is active.
 *
 * Surface area kept deliberately small:
 *   - `put(key, body, mime)` — write bytes, return the public URL
 *   - `presignPut(key, mime)` — short-lived URL the browser PUTs to
 *   - `publicUrl(key)` — read URL (long-lived if R2_PUBLIC_BASE is set,
 *                       otherwise a short presigned GET)
 *   - `mode` — 'local' | 'r2', surfaced so the API can advertise it
 *
 * Keys look like `<prefix>/<uuid>.<ext>`. Prefixes are conventional:
 *   - `attachments/`       — user uploads (signed)
 *   - `email-attachments/` — inbound and outbound mail files (signed)
 *   - `avatars/`           — portraits (the only unsigned R2 prefix)
 */
import { writeFile, mkdir, readdir, readFile, stat, unlink } from 'node:fs/promises'
import { basename, join, resolve, dirname } from 'node:path'
import { createHmac } from 'node:crypto'
import {
  S3Client, PutObjectCommand, GetObjectCommand, HeadObjectCommand,
  DeleteObjectCommand, ListObjectsV2Command,
} from '@aws-sdk/client-s3'
import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
import { env } from './env.js'
import {
  ATTACHMENT_MAX_FILE_BYTES,
  ATTACHMENT_MAX_TOTAL_BYTES,
  normalizeAttachments,
  validateAttachmentInput,
  type AttachmentDescriptor,
  type AttachmentKind,
} from '../../shared/attachments.js'
import {
  normalizeStorageKey,
  storageKeyFromPublicUrl as storageKeyFromPublicUrlForBase,
  messageAttachmentStorageKey as messageAttachmentStorageKeyForBase,
} from './storage-keys.js'

export { normalizeStorageKey }

/** Keys under these prefixes get HMAC-signed URLs when a signing secret is
 *  configured. The R2 worker serves only `avatars/` without a signature;
 *  every other key is rejected at the edge until it is signed. Keep this
 *  list, `PUBLIC_PREFIXES` in `workers/r2-gate/src/index.ts`, and
 *  `STORAGE_KEY_PREFIXES` in `storage-keys.ts` in agreement — the prefix
 *  contract test fails when they drift. */
const SIGNED_PREFIXES = ['attachments/', 'email-attachments/']
function needsSignature(key: string): boolean {
  return SIGNED_PREFIXES.some((p) => key.startsWith(p))
}

export function storageKeyFromPublicUrl(raw: string): string | null {
  return storageKeyFromPublicUrlForBase(raw, env.R2_PUBLIC_BASE)
}

export function messageAttachmentStorageKey(input: { key?: unknown; url?: unknown }): string | null {
  return messageAttachmentStorageKeyForBase(input, env.R2_PUBLIC_BASE)
}

export function signedUrlExpiresSoon(raw: string, leewaySeconds = 300): boolean {
  try {
    const exp = Number(new URL(raw).searchParams.get('exp') ?? 0)
    return Number.isFinite(exp) && exp > 0 && exp <= Math.floor(Date.now() / 1000) + leewaySeconds
  } catch {
    return false
  }
}

/** Local fallback directory. Same path the static handler historically
 *  served from, so existing /uploads/<file> URLs keep working after the
 *  abstraction lands. */
export const UPLOAD_DIR = resolve(process.cwd(), 'server/uploads')

/** The chat-upload MIME allowlist also defines the extension and renderer kind
 *  for a new object. Message persistence derives both from stored metadata. */
export const CHAT_ATTACHMENT_MIME_POLICY: Record<string, { kind: 'img' | 'file'; ext: string }> = {
  'image/png': { kind: 'img', ext: 'png' },
  'image/jpeg': { kind: 'img', ext: 'jpg' },
  'image/webp': { kind: 'img', ext: 'webp' },
  'image/gif': { kind: 'img', ext: 'gif' },
  'application/pdf': { kind: 'file', ext: 'pdf' },
  'application/msword': { kind: 'file', ext: 'doc' },
  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': { kind: 'file', ext: 'docx' },
  'application/vnd.ms-excel': { kind: 'file', ext: 'xls' },
  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': { kind: 'file', ext: 'xlsx' },
  'application/vnd.ms-powerpoint': { kind: 'file', ext: 'ppt' },
  'application/vnd.openxmlformats-officedocument.presentationml.presentation': { kind: 'file', ext: 'pptx' },
  'application/zip': { kind: 'file', ext: 'zip' },
  'application/x-tar': { kind: 'file', ext: 'tar' },
  'application/gzip': { kind: 'file', ext: 'gz' },
  'text/plain': { kind: 'file', ext: 'txt' },
  'text/markdown': { kind: 'file', ext: 'md' },
  'text/csv': { kind: 'file', ext: 'csv' },
  'application/json': { kind: 'file', ext: 'json' },
  'application/x-yaml': { kind: 'file', ext: 'yml' },
  'application/x-toml': { kind: 'file', ext: 'toml' },
  'audio/mpeg': { kind: 'file', ext: 'mp3' },
  'audio/wav': { kind: 'file', ext: 'wav' },
  'video/mp4': { kind: 'file', ext: 'mp4' },
  'video/quicktime': { kind: 'file', ext: 'mov' },
}

function attachmentKindForMime(mime: string): AttachmentKind {
  if (mime === 'application/pdf') return 'pdf'
  return CHAT_ATTACHMENT_MIME_POLICY[mime]?.kind ?? 'file'
}

/** Validate a presign request against the same policy the message write uses. */
export function validateChatUpload(input: {
  name: unknown
  mime: unknown
  size: unknown
}):
  | { ok: true; name: string; mime: string; size: number; kind: AttachmentKind }
  | { ok: false; status: 400 | 413 | 415; error: string } {
  const name = String(input.name ?? '').trim().slice(0, 200)
  const mime = String(input.mime ?? '').trim().toLowerCase()
  const size = Number(input.size ?? 0)
  if (!name || !mime) return { ok: false, status: 400, error: 'name + mime required' }
  if (!Number.isSafeInteger(size) || size <= 0 || size > ATTACHMENT_MAX_FILE_BYTES) {
    return { ok: false, status: 413, error: `size out of range (got ${size}, max ${ATTACHMENT_MAX_FILE_BYTES})` }
  }
  const policy = CHAT_ATTACHMENT_MIME_POLICY[mime]
  if (!policy) return { ok: false, status: 415, error: `mime not allowed: ${mime}` }
  return { ok: true, name, mime, size, kind: attachmentKindForMime(mime) }
}

const STORAGE_MIME_BY_EXTENSION = new Map<string, string>()
for (const [mime, policy] of Object.entries(CHAT_ATTACHMENT_MIME_POLICY)) {
  STORAGE_MIME_BY_EXTENSION.set(policy.ext, mime)
}

function normalizedMime(raw: string): string {
  return raw.split(';', 1)[0]?.trim().toLowerCase() ?? ''
}

/** Local uploads use a small sidecar for the exact MIME supplied when the
 *  server wrote the bytes. The sidecar never becomes a message attachment. */
async function putLocalMimeMetadata(key: string, mime: string): Promise<void> {
  const marker = localMimeMarker(key)
  await mkdir(dirname(marker), { recursive: true })
  await writeFile(marker, mime)
}

function localMimeMarker(key: string): string {
  return join(UPLOAD_DIR, dirname(key), `${basename(key)}.cumora-mime`)
}

/** Local files have no object-store Content-Type header. Their server-minted
 *  extension is the storage-side type record used for persistence and reads. */
export function mimeTypeFromStorageKey(key: string): string | undefined {
  const extension = key.toLowerCase().match(/\.([a-z0-9]+)$/)?.[1]
  return extension ? STORAGE_MIME_BY_EXTENSION.get(extension) : undefined
}

/** One enumerated object. lastModifiedMs is the storage backend's notion
 *  of when the object was last written — GC uses it to spare keys that
 *  were uploaded recently (the row write may still be in flight). */
export interface StorageObject {
  key: string
  sizeBytes: number
  lastModifiedMs: number
}

/** Authoritative metadata for one stored object. Callers use this instead of
 *  trusting browser-supplied MIME or size values when persisting a message. */
export interface StoredObjectMetadata {
  key: string
  sizeBytes: number
  mime?: string
}

export interface Storage {
  mode: 'local' | 'r2'
  /** Write bytes synchronously from the server side (avatar gen path).
   *  Returns the resolved public URL. */
  put(key: string, body: Buffer, mime: string): Promise<string>
  /** Return a short-lived PUT URL the browser uploads to directly, plus
   *  the public URL the file will be available at after the upload. */
  presignPut(
    key: string,
    mime: string,
    sizeBytes: number,
    ttlSeconds?: number,
  ): Promise<{ uploadUrl: string; publicUrl: string }>
  /** Return object metadata, or null when the key does not exist. */
  statObject(key: string): Promise<StoredObjectMetadata | null>
  /** Resolve a long-lived public URL for a key. R2 mode emits a presigned
   *  GET when no public base is configured. */
  publicUrl(key: string): Promise<string>
  /** Enumerate every object whose key starts with `prefix`. Used by the
   *  GC sweep to find orphans not referenced by any DB row. Both backends
   *  walk lazily / paginated under the hood; the caller gets the flat
   *  list. */
  listObjectsByPrefix(prefix: string): Promise<StorageObject[]>
  /** Best-effort removal of one object. Never throws — returns false if
   *  the key didn't exist OR the backend complained — so the GC loop
   *  doesn't stall on a single bad row. */
  deleteObject(key: string): Promise<boolean>
}

class LocalStorage implements Storage {
  mode = 'local' as const

  async put(key: string, body: Buffer, _mime: string): Promise<string> {
    const path = join(UPLOAD_DIR, key)
    await mkdir(dirname(path), { recursive: true })
    await writeFile(path, body)
    await putLocalMimeMetadata(key, _mime)
    // Existing static handler mounts UPLOAD_DIR at /uploads/.
    return `/uploads/${key}`
  }

  // Local mode has no real presign — the browser still goes through
  // `POST /uploads` (base64). Callers MUST check `storage.mode` first
  // and pick the base64 path; this method only exists to satisfy the
  // interface and will throw if reached.
  async presignPut(
    _key: string,
    _mime: string,
    _sizeBytes: number,
    _ttl?: number,
  ): Promise<{ uploadUrl: string; publicUrl: string }> {
    throw new Error('presignPut not supported in local mode — POST /uploads (base64) instead')
  }

  async statObject(key: string): Promise<StoredObjectMetadata | null> {
    const path = join(UPLOAD_DIR, key)
    try {
      const s = await stat(path)
      if (!s.isFile()) return null
      const metaMarker = localMimeMarker(key)
      let mime: string | undefined
      try {
        const raw = (await readFile(metaMarker, 'utf8')).trim()
        if (raw) mime = normalizedMime(raw)
      } catch (error) {
        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
      }
      return { key, sizeBytes: s.size, mime }
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
      throw error
    }
  }

  async publicUrl(key: string): Promise<string> {
    return `/uploads/${key}`
  }

  async listObjectsByPrefix(prefix: string): Promise<StorageObject[]> {
    // Local layout: UPLOAD_DIR/<prefix>/<files>. readdir + stat is fine —
    // local dev never accumulates the millions of objects R2 would.
    const dir = join(UPLOAD_DIR, prefix)
    let names: string[]
    try { names = await readdir(dir) }
    catch { return [] }  // no such directory == no objects
    const out: StorageObject[] = []
    for (const name of names) {
      const full = join(dir, name)
      try {
        const s = await stat(full)
        if (!s.isFile()) continue
        out.push({
          key: `${prefix.replace(/\/+$/, '')}/${name}`,
          sizeBytes: s.size,
          lastModifiedMs: s.mtimeMs,
        })
      } catch { /* ignore disappeared / unreadable */ }
    }
    return out
  }

  async deleteObject(key: string): Promise<boolean> {
    const path = join(UPLOAD_DIR, key)
    try { await unlink(path); return true }
    catch (error) {
      // Deletion is idempotent: a prior successful attempt may have removed
      // the file before the durable cleanup job could be marked complete.
      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return true
      return false
    }
  }
}

class R2Storage implements Storage {
  mode = 'r2' as const
  private client: S3Client
  private bucket: string
  private publicBase: string
  private signingSecret: string
  private urlTtl: number

  constructor(opts: {
    endpoint: string; bucket: string;
    accessKeyId: string; secretAccessKey: string;
    publicBase: string;
    signingSecret: string;
    urlTtl: number;
  }) {
    this.bucket = opts.bucket
    this.publicBase = opts.publicBase
    this.signingSecret = opts.signingSecret
    this.urlTtl = opts.urlTtl
    this.client = new S3Client({
      // R2 lives in a single region; the SDK still requires *some* value.
      // "auto" is the documented choice for R2.
      region: 'auto',
      endpoint: opts.endpoint,
      credentials: {
        accessKeyId: opts.accessKeyId,
        secretAccessKey: opts.secretAccessKey,
      },
      // R2 requires path-style addressing in some configs; force it on so
      // the same code works whether the user is on the default subdomain
      // setup or a custom hostname.
      forcePathStyle: true,
    })
  }

  async put(key: string, body: Buffer, mime: string): Promise<string> {
    await this.client.send(new PutObjectCommand({
      Bucket: this.bucket,
      Key: key,
      Body: body,
      ContentType: mime,
    }))
    return this.publicUrl(key)
  }

  async presignPut(
    key: string,
    mime: string,
    sizeBytes: number,
    ttl = 300,
  ): Promise<{ uploadUrl: string; publicUrl: string }> {
    const cmd = new PutObjectCommand({
      Bucket: this.bucket,
      Key: key,
      ContentType: mime,
      // SigV4 binds this header into the presigned URL. The browser's PUT must
      // carry the same Content-Length, preventing a larger object upload.
      ContentLength: sizeBytes,
    })
    const uploadUrl = await getSignedUrl(this.client, cmd, { expiresIn: ttl })
    const publicUrl = await this.publicUrl(key)
    return { uploadUrl, publicUrl }
  }

  async statObject(key: string): Promise<StoredObjectMetadata | null> {
    try {
      const res = await this.client.send(new HeadObjectCommand({
        Bucket: this.bucket,
        Key: key,
      }))
      if (typeof res.ContentLength !== 'number' || !Number.isSafeInteger(res.ContentLength)) {
        throw new Error('storage object has no valid Content-Length')
      }
      return {
        key,
        sizeBytes: res.ContentLength,
        ...(res.ContentType ? { mime: res.ContentType.toLowerCase() } : {}),
      }
    } catch (error) {
      const name = (error as { name?: unknown } | null)?.name
      const status = (error as { $metadata?: { httpStatusCode?: unknown } } | null)?.$metadata?.httpStatusCode
      if (name === 'NotFound' || name === 'NoSuchKey' || status === 404) return null
      throw error
    }
  }

  async listObjectsByPrefix(prefix: string): Promise<StorageObject[]> {
    // R2 / S3 ListObjectsV2 is paginated; loop on ContinuationToken so a
    // large bucket doesn't silently truncate at 1000.
    const out: StorageObject[] = []
    let token: string | undefined
    do {
      const res = await this.client.send(new ListObjectsV2Command({
        Bucket: this.bucket,
        Prefix: prefix,
        ContinuationToken: token,
      }))
      for (const obj of res.Contents ?? []) {
        if (!obj.Key) continue
        out.push({
          key: obj.Key,
          sizeBytes: obj.Size ?? 0,
          lastModifiedMs: obj.LastModified ? obj.LastModified.getTime() : 0,
        })
      }
      token = res.IsTruncated ? res.NextContinuationToken : undefined
    } while (token)
    return out
  }

  async deleteObject(key: string): Promise<boolean> {
    try {
      await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }))
      return true
    } catch (e) {
      console.warn(`[storage] deleteObject(${key}) failed:`, e instanceof Error ? e.message : String(e))
      return false
    }
  }

  async publicUrl(key: string): Promise<string> {
    // Prefer the explicit public base (custom domain). Cache-friendly,
    // no expiry on the URL structure itself. When a signing secret is
    // configured AND the key falls under a signed prefix, append the
    // HMAC query params — the Cloudflare Worker at the edge validates
    // these before proxying R2 reads.
    if (this.publicBase) {
      if (this.signingSecret && needsSignature(key)) {
        const exp = Math.floor(Date.now() / 1000) + this.urlTtl
        const sig = createHmac('sha256', this.signingSecret)
          .update(`${key}:${exp}`).digest('hex')
        return `${this.publicBase}/${key}?exp=${exp}&sig=${sig}`
      }
      return `${this.publicBase}/${key}`
    }
    // No public base — fall back to a long-lived presigned GET (works
    // without a CDN domain; not cacheable; rotates).
    return getSignedUrl(
      this.client,
      new GetObjectCommand({ Bucket: this.bucket, Key: key }),
      { expiresIn: 60 * 60 * 24 * 7 },  // 7 days
    )
  }
}

function buildStorage(): Storage {
  const have = env.R2_ENDPOINT && env.R2_BUCKET && env.R2_ACCESS_KEY_ID && env.R2_SECRET_ACCESS_KEY
  if (have) {
    const signingActive = Boolean(env.R2_URL_SIGNING_SECRET)
    console.log(
      `[storage] R2 active · bucket=${env.R2_BUCKET} ` +
      `publicBase=${env.R2_PUBLIC_BASE || '(presigned GET)'} ` +
      `signing=${signingActive ? 'on' : 'OFF'}`,
    )
    // Loud warning when the public base is set but signing isn't — every
    // URL under `attachments/` will be unsigned, which the Cloudflare
    // Worker gate then 403s. Almost always means the server was started
    // before R2_URL_SIGNING_SECRET landed in .env. Restart fixes it.
    if (env.R2_PUBLIC_BASE && !signingActive) {
      console.warn(
        '[storage] ⚠ R2_PUBLIC_BASE is set but R2_URL_SIGNING_SECRET is empty — ' +
        'attachment URLs will be emitted UNSIGNED and the cdn gate will 403 them. ' +
        'Check .env and restart the server.',
      )
    }
    return new R2Storage({
      endpoint: env.R2_ENDPOINT,
      bucket: env.R2_BUCKET,
      accessKeyId: env.R2_ACCESS_KEY_ID,
      secretAccessKey: env.R2_SECRET_ACCESS_KEY,
      publicBase: env.R2_PUBLIC_BASE,
      signingSecret: env.R2_URL_SIGNING_SECRET,
      urlTtl: env.R2_URL_TTL_SECONDS,
    })
  }
  console.log('[storage] local mode · server/uploads/ (set R2_* env to use R2)')
  return new LocalStorage()
}

export const storage: Storage = buildStorage()

/** Stored attachment shape — mirror of AttachmentPayload in the router.
 *  Defined here so the freshening helper has no circular import. */
export interface StoredAttachment {
  url: string
  name: string
  kind: 'img' | 'pdf' | 'file' | 'fig'
  mime?: string
  size?: number
  key?: string
  [extra: string]: unknown
}

/** Re-sign an attachment's `url` from its stored `key` so each response
 *  carries a fresh signature. Without this, persisted message URLs would
 *  expire and break historical bubbles after the TTL window. Returns the
 *  input unchanged when no key is stored (legacy local-mode attachments)
 *  or storage doesn't need signing. */
export async function freshenAttachmentUrl<T extends StoredAttachment | null | undefined>(
  att: T,
): Promise<T> {
  if (!att) return att
  // Re-sign from the stored key, or derive it from the (possibly already-signed)
  // url — older attachments persisted no `key`, and without this they'd be stuck
  // with a stale signed url that 403s once its TTL lapses.
  const key = att.key ?? (att.url ? storageKeyFromPublicUrl(att.url) : null)
  if (!key) return att
  const url = await storage.publicUrl(key)
  if (url === att.url && att.key === key) return att
  return { ...att, url, key } as T
}

export type ResolveMessageAttachmentsResult =
  | { readonly ok: true; readonly attachments: readonly AttachmentDescriptor[] }
  | {
      readonly ok: false
      readonly status: 400 | 413
      readonly error: string
      readonly index?: number
    }

/** Validate the ordered wire list, resolve each trusted Cumora object, and
 *  replace every client-controlled size/MIME/kind/URL with storage-derived
 *  values. Message persistence must use this result verbatim. */
export async function resolveMessageAttachments(
  raw: unknown,
  backend: Pick<Storage, 'statObject' | 'publicUrl'> = storage,
  opts: {
    mimeForLegacyKey?: (key: string) => string | undefined
    /** Tenant-bound grant check supplied by the API boundary. Keeping the
     * callback here avoids coupling storage backends to Postgres. */
    attachmentGrant?: (key: string) => Promise<boolean>
  } = {},
): Promise<ResolveMessageAttachmentsResult> {
  const parsed = validateAttachmentInput(raw)
  if (!parsed.ok) {
    const indexSuffix = parsed.index === undefined ? '' : ` at index ${parsed.index}`
    switch (parsed.issue) {
      case 'too-many-files':
        return { ok: false, status: 413, error: 'too many attachments (maximum 16)' }
      case 'file-too-large':
        return { ok: false, status: 413, error: `attachment${indexSuffix} exceeds 25 MiB` }
      case 'total-too-large':
        return { ok: false, status: 413, error: `attachments${indexSuffix} exceed 25 MiB total` }
      case 'invalid-shape':
        return { ok: false, status: 400, error: `invalid attachment${indexSuffix}` }
    }
  }

  const attachments: AttachmentDescriptor[] = []
  let totalBytes = 0
  for (let index = 0; index < parsed.attachments.length; index++) {
    const input = parsed.attachments[index]
    const key = messageAttachmentStorageKey(input)
    if (!key) {
      return { ok: false, status: 400, error: 'attachment must reference Cumora storage', index }
    }
    if (opts.attachmentGrant && !(await opts.attachmentGrant(key))) {
      return { ok: false, status: 400, error: 'attachment is not granted to this workspace', index }
    }
    let stored: StoredObjectMetadata | null
    let url: string
    try {
      ;[stored, url] = await Promise.all([backend.statObject(key), backend.publicUrl(key)])
    } catch {
      return { ok: false, status: 400, error: 'attachment storage reference is invalid', index }
    }
    if (!stored) return { ok: false, status: 400, error: 'attachment object does not exist', index }
    if (stored.sizeBytes <= 0 || stored.sizeBytes > ATTACHMENT_MAX_FILE_BYTES) {
      return { ok: false, status: 413, error: `attachment object size is invalid (maximum 25 MiB)`, index }
    }
    if (input.size !== undefined && input.size !== stored.sizeBytes) {
      return { ok: false, status: 400, error: 'attachment size does not match uploaded object', index }
    }
    totalBytes += stored.sizeBytes
    if (totalBytes > ATTACHMENT_MAX_TOTAL_BYTES) {
      return { ok: false, status: 413, error: 'attachments exceed 25 MiB total', index }
    }

    const mime = stored.mime
      ? normalizedMime(stored.mime)
      : (opts.mimeForLegacyKey ?? mimeTypeFromStorageKey)(key)
    if (!mime || !CHAT_ATTACHMENT_MIME_POLICY[mime]) {
      return { ok: false, status: 400, error: 'attachment object has an unsupported content type', index }
    }
    if (input.mime && normalizedMime(input.mime) !== mime) {
      return { ok: false, status: 400, error: 'attachment MIME does not match uploaded object', index }
    }
    attachments.push({
      name: input.name,
      kind: attachmentKindForMime(mime),
      url,
      key,
      mime,
      size: stored.sizeBytes,
    })
  }
  return { ok: true, attachments }
}

/** Add the canonical ordered list plus the first-entry legacy projection to a
 *  message response without changing any surrounding fields. */
export async function freshenMessageAttachments(
  value: unknown,
): Promise<{ attachment?: AttachmentDescriptor; attachments: readonly AttachmentDescriptor[] }> {
  const attachments = await Promise.all(normalizeAttachments(value).map(async (attachment) => {
    const freshened = await freshenAttachmentUrl({
      ...attachment,
      url: attachment.url ?? '',
    })
    return {
      ...attachment,
      ...(freshened.url ? { url: freshened.url } : {}),
      ...(freshened.key ? { key: freshened.key } : {}),
    }
  }))
  return {
    ...(attachments[0] ? { attachment: attachments[0] } : {}),
    attachments,
  }
}