Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

26.9 KB
Raw Blame
import { createHmac, randomBytes } from 'node:crypto'
import { Readable, Transform, Writable } from 'node:stream'
import { pipeline } from 'node:stream/promises'
import { createGunzip } from 'node:zlib'
import { z } from 'zod'
import type { VoiceFacts } from './voiceMessages.js'

/** Metadata as a message stores it. The bytes stay in the bucket. `url` is the file's public address on the CDN: it names the
 *  object, and apps from before signed links open it, until the bucket is no longer public (docs/swarms.md, "Chat file
 *  links"). Each read adds `link`, a short-lived signed link of that read, and `expiresAt` (epoch ms), when it stops opening
 *  (fileLinks.ts). A read that could not sign one says so with `unlinked: true` instead, so an app asks again rather than
 *  open the public address; only a file with neither comes from a server from before links. None of the three is stored. */
export interface Attachment { id: string; name: string; mime: string; size: number; url: string; link?: string; expiresAt?: number; unlinked?: true
  /** A voice message's length, waveform and whether it has words (voiceMessages.ts); its words are the message's text. */
  voice?: VoiceFacts
  /** A picture's size as it is shown, and the small WebP the server made of it at upload (thumbnails.ts): a chat draws that and
   *  the viewer opens the original. `thumb.url` is its public address beside the original's; a read adds `link` and
   *  `expiresAt` (or `unlinked`) exactly as for the file, from the same read (fileLinks.ts). Absent on a file without them. */
  width?: number; height?: number
  thumb?: { url: string; width: number; height: number; size: number; link?: string; expiresAt?: number; unlinked?: true } }

/** One chat file, whichever way it comes. Every client checks the same number before it sends (attachments.limits.test.ts). */
export const MAX_ATTACHMENT_BYTES = 256 * 1024 * 1024
/** The most a file sent in a multipart form to this server may be. Production sits behind Cloudflare, whose plans below
 *  Business refuse a request body over 100 MB, and an ingress whose body limit the repo does not set; 10 MB is what that
 *  path has carried since #1490. A bigger file goes straight to the bucket on an upload link (uploadLink below). */
export const MAX_FORM_ATTACHMENT_BYTES = 10 * 1024 * 1024
export const MAX_ATTACHMENTS = 10
/** How long an upload link may be started: storage checks it when a request begins, so a long transfer that started in time finishes. */
export const UPLOAD_LINK_MS = 10 * 60_000
/** The `purpose` of an upload whose link was handed out and whose bytes the server has not yet checked. Servers before this
 *  one refuse a row with any purpose as a message's file, so a rollout never sends a file that has not arrived. */
export const PENDING_UPLOAD_PURPOSE = 'pending-upload'
/** An unfinished upload the sweep has claimed (lib/pendingUploadSweep.ts): its stored file is being removed, so it can no
 *  longer be finished or sent. */
export const REMOVING_UPLOAD_PURPOSE = 'removing-upload'
export const TOO_LARGE_MESSAGE = 'Files can be up to 256 MB.'
/** Uploads a sender may start in a Swarm in an hour, and their bytes: bucket space for files that may never be sent. */
export const HOURLY_UPLOADS = 200
export const HOURLY_UPLOAD_BYTES = 4 * 1024 * 1024 * 1024
/** A link's upload never finished is removed, with what it stored, this long after the link was made: an hour after it expired. */
export const PENDING_UPLOAD_LIFE_MS = UPLOAD_LINK_MS + 3_600_000
/** The form route's own refusal, seen only by a client from before upload links. */
export const FORM_TOO_LARGE_MESSAGE = 'Update Harness to send files over 10 MB. Files can be up to 256 MB.'
/** An avatar is a small picture: Desktop resizes it before upload, and the backend still holds it to this. */
export const MAX_AVATAR_BYTES = 1024 * 1024
export const AVATAR_TYPES: ReadonlySet<string> = new Set(['image/png', 'image/jpeg', 'image/webp'])
/** The `purpose` of an avatar upload (schema.prisma SuperTabAttachment): never sendable as a chat file. */
export const AVATAR_PURPOSE = 'avatar'
/** How long an upload may wait to be sent. */
export const UNSENT_LIFE_MS = 24 * 3_600_000
/** `usedBy` of an upload the expiry sweep took (lib/attachmentSweep.ts): its file is being removed and nothing may use it.
 *  Message and receipt ids are 24 hex characters (model.ts stableId), so the colon keeps it from ever matching one. */
export const EXPIRED_UPLOAD = 'expired:unsent'

// Control, format (bidi overrides, zero-width) and line/paragraph separators: a name that hides its real shape.
export const attachmentName = z.string().trim().min(1).max(255).refine(value => !/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(value), 'Use a printable file name.')
export const attachmentMime = z.string().trim().toLowerCase().max(200).regex(/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/)

export class AttachmentTooLarge extends Error {
  constructor(cap = MAX_ATTACHMENT_BYTES) {
    super(cap === MAX_ATTACHMENT_BYTES ? TOO_LARGE_MESSAGE : cap === MAX_FORM_ATTACHMENT_BYTES ? FORM_TOO_LARGE_MESSAGE : `A file can be at most ${cap / 1024 / 1024} MB.`)
  }
}

/** A link that writes one object once, straight to storage, and the headers its request must carry unchanged. */
export interface UploadLink { url: string; headers: Record<string, string> }

/** A bucket the client can write to directly. Each link names one object, which must not exist yet, of exactly `size` bytes,
 *  served as a download; storage itself refuses any other size, a second write, a changed header, or a start after `expiresAt`. */
export interface DirectUploads {
  uploadLink(objectKey: string, file: { name: string }, size: number, expiresAt: number): Promise<UploadLink>
  /** The stored object's size, or null while nothing is there. */
  stored(objectKey: string): Promise<{ size: number } | null>
  /** Its first `bytes` bytes. */
  head(objectKey: string, bytes: number): Promise<Buffer>
  /** The whole object, for a picture to be thumbnailed once its upload is complete; `size` is what `stored` answered. */
  read(objectKey: string): Promise<Buffer>
  /** Removes it; an object already gone counts as removed. */
  delete(objectKey: string): Promise<void>
}
export const directUploads = (store: AttachmentStore): DirectUploads | null =>
  'uploadLink' in store && typeof (store as Partial<DirectUploads>).uploadLink === 'function' ? store as AttachmentStore & DirectUploads : null

/** The headers an upload link signs. The bytes are not seen before they are served, so they are always a download, whatever
 *  type is declared; the message keeps the declared type (an image's checked from its first bytes) for clients to show. */
export function linkHeaders(name: string, size: number, cacheControl: string): Record<string, string> {
  return { 'content-type': 'application/octet-stream', 'content-disposition': served(name, 'application/octet-stream').contentDisposition,
    'cache-control': cacheControl, 'x-goog-content-length-range': `${size},${size}`, 'x-goog-if-generation-match': '0' }
}
/** A storage error's code or HTTP status, for a log line: its text can quote the object's key, which is the file's link. */
export const errorCode = (error: unknown): string | number | null =>
  error && typeof error === 'object' && 'code' in error && (typeof error.code === 'string' || typeof error.code === 'number') ? error.code : null
/** A chat file is read only through a signed link that lasts minutes (fileLinks.ts): no shared cache keeps a copy, and a
 *  browser keeps one no longer than its link lasts. Files stored before this say `public, max-age=31536000, immutable`; the
 *  release step that makes the bucket private rewrites theirs (docs/swarms.md, "Chat file links"). */
export const CHAT_CACHE_CONTROL = 'private, max-age=600'

/** The bucket the chat files are in. Tests and the local rig use the in-memory store below. */
export interface AttachmentStore {
  /** Streams `body` into the object and answers its size. Past `cap` bytes it throws AttachmentTooLarge and leaves no object. */
  put(objectKey: string, file: { name: string; mime: string }, body: Readable, cap: number): Promise<number>
  /** A link that opens [objectKey] until [expiresAt] (epoch ms) and never after, whether or not the bucket is public. Storage
   *  checks it when a request starts, so a long download that started in time finishes. */
  signedUrl(objectKey: string, expiresAt: number): Promise<string>
  /** Removes the object. One that is already gone counts as removed. */
  delete(objectKey: string): Promise<void>
}
/** Where avatars are kept, and the link a member read carries for one (avatarLinks.ts). */
export interface AvatarStore extends AttachmentStore {}
/** `avatars`: where avatars are kept and how they are linked (AvatarStore); without it, avatar uploads are refused and presets
 *  still work. `avatarPrefix`: the folder avatar keys start with, and the only one a link is signed for (avatarLinks.ts);
 *  `prefix` when unset. */
export interface Attachments { store: AttachmentStore; prefix: string; publicBase: string; avatars?: AvatarStore | null; avatarPrefix?: string }
/** Avatars' folder in the attachments bucket, when they have no bucket of their own. */
export const SHARED_AVATAR_PREFIX = 'avatars'
export const trimPrefix = (prefix: string) => prefix.replace(/^\/+|\/+$/g, '')

/** The key carries 128 random bits, so no one finds a file by guessing; the name segment is for people. */
export function objectKeyFor(prefix: string, tabId: string, name: string): string {
  const safe = name.replaceAll(/[^A-Za-z0-9._-]+/g, '_').replace(/^[._]+/, '').slice(-120) || 'file'
  return [trimPrefix(prefix), tabId, randomBytes(16).toString('hex'), safe].filter(Boolean).join('/')
}
export const publicUrl = (base: string, objectKey: string) => `${base.replace(/\/+$/, '')}/${objectKey}`

/** How the bucket serves a file. The CDN shares a parent domain with the apps, so only raster images keep their type
 * and open in the browser. Anything else, HTML and SVG included, is stored as bytes to download, never run as a page.
 * The message keeps the declared type for clients to show. */
const INLINE = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp'])
export function served(name: string, mime: string): { contentType: string; contentDisposition: string } {
  const inline = INLINE.has(mime)
  return { contentType: inline ? mime : 'application/octet-stream',
    contentDisposition: `${inline ? 'inline' : 'attachment'}; filename*=UTF-8''${encodeURIComponent(name)}` }
}

/** A form file's bytes as they were before the client packed them. A client may gzip a form file and say so with
 * `contentEncoding: gzip` before it (task #2737): a gateway's content filter in front of the backend refused a handoff full
 * of shell lines as text, and cannot read packed bytes. The store then sees, sizes and caps the original bytes, so a small
 * packed file that unpacks past the cap is refused like any other. The request stream's own failure reaches the result. */
export function formFileBody(file: Readable, encoding: 'gzip' | null): Readable {
  if (encoding === null) return file
  const unpacked = createGunzip()
  // Not stream.pipeline: stopping the unpacking must not destroy the request's file stream, which the route drains.
  file.once('error', error => unpacked.destroy(error))
  // Bad gzip can fail before the store starts reading (it checks access first): kept on `errored` for the reader, never
  // thrown as an unheard 'error' event that would end the process.
  unpacked.on('error', () => {})
  return file.pipe(unpacked)
}

/** Stops unpacking `body` once the store is done with it, so a packed file past the cap is never inflated to its end. */
export function stopUnpacking(file: Readable, body: Readable): void {
  if (body === file) return
  file.unpipe(body as unknown as NodeJS.WritableStream)
  body.destroy()
}

/** Whether `body` failed because its packed bytes were not gzip: the client's fault, never the bucket's. */
export const unpackFailed = (body: Readable): boolean => {
  const code = body.errored && typeof body.errored === 'object' && 'code' in body.errored ? body.errored.code : null
  return typeof code === 'string' && code.startsWith('Z_')
}

/** The raster type the first bytes really are, or null. */
export function imageTypeOf(head: Buffer): string | null {
  const ascii = (at: number, text: string) => head.subarray(at, at + text.length).toString('latin1') === text
  if (head.length >= 8 && head.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return 'image/png'
  if (head.length >= 3 && head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff) return 'image/jpeg'
  if (ascii(0, 'GIF87a') || ascii(0, 'GIF89a')) return 'image/gif'
  if (head.length >= 12 && ascii(0, 'RIFF') && ascii(8, 'WEBP')) return 'image/webp'
  return null
}

/** The raster type `body`'s first bytes are, or null, and `body` handed back with those bytes in front, so the store
 * still reads the whole file as a stream. */
export async function peekType(body: Readable): Promise<{ type: string | null; body: Readable }> {
  // One iterator for the whole read: leaving a `for await` early would destroy the request stream.
  const source = body[Symbol.asyncIterator]()
  const parts: Buffer[] = []
  let length = 0, done = false
  while (length < 16) {
    const next = await source.next()
    if (next.done) { done = true; break }
    parts.push(Buffer.from(next.value)); length += next.value.length
  }
  const head = Buffer.concat(parts)
  const rest = async function* () {
    if (head.length) yield head
    while (!done) {
      const next = await source.next()
      if (next.done) return
      yield Buffer.from(next.value)
    }
  }
  return { type: imageTypeOf(head), body: Readable.from(rest()) }
}

/** A file that claims to be an image is served as one only when its first bytes agree, and then as what they say: a
 * renamed page or script never opens inline, and a .png that is really a JPEG still shows. */
export async function checkedType(mime: string, body: Readable): Promise<{ mime: string; body: Readable }> {
  if (!INLINE.has(mime)) return { mime, body }
  const peeked = await peekType(body)
  return { mime: peeked.type ?? 'application/octet-stream', body: peeked.body }
}

/** The type a checked upload keeps: a declared raster image only when its first bytes agree, as checkedType decides for a form. */
export const typeFromHead = (mime: string, head: Buffer) => INLINE.has(mime) ? imageTypeOf(head) ?? 'application/octet-stream' : mime

/** Counts what passes and fails the stream past `cap`, so a writer never commits more. */
async function capped(body: Readable, cap: number, sink: Writable): Promise<number> {
  let size = 0
  await pipeline(body, new Transform({ transform(chunk: Buffer, _encoding, done) {
    size += chunk.byteLength
    done(size > cap ? new AttachmentTooLarge(cap) : null, chunk)
  } }), sink)
  return size
}

/** A service account key the bucket is written with. */
export interface ServiceAccount { projectId?: string; credentials: { client_email: string; private_key: string } }

/** SUPER_TAB_ATTACHMENTS_CREDENTIALS: the base64 of a service account JSON key, or empty for application default
 * credentials. A bad value stops the backend at startup. No message repeats any of the value: JSON.parse's own
 * message quotes the text it failed on, so it is never passed on. */
export function serviceAccountFrom(raw: string): ServiceAccount | null {
  const value = raw.replaceAll(/\s+/g, '')
  if (!value) return null
  const invalid = (why: string): never => { throw new Error(`SUPER_TAB_ATTACHMENTS_CREDENTIALS ${why}. Set the base64 of the service account JSON key, or leave it empty to use application default credentials.`) }
  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value) || value.length % 4 === 1) invalid('is not base64')
  let key: Record<string, unknown> = {}
  try { key = JSON.parse(Buffer.from(value, 'base64').toString('utf8')) } catch { invalid('does not decode to JSON') }
  if (!key || typeof key !== 'object' || typeof key.client_email !== 'string' || !key.client_email
    || typeof key.private_key !== 'string' || !key.private_key.includes('PRIVATE KEY')) invalid('is not a service account key with client_email and private_key')
  return { ...(typeof key.project_id === 'string' ? { projectId: key.project_id } : {}),
    credentials: { client_email: key.client_email as string, private_key: key.private_key as string } }
}

export class GcsAttachmentStore implements AttachmentStore, DirectUploads {
  private bucket: Promise<import('@google-cloud/storage').Bucket> | null = null
  constructor(private readonly name: string, private readonly account: ServiceAccount | null = null,
    private readonly cacheControl = CHAT_CACHE_CONTROL) {}
  // Loaded on first use, so a backend without a bucket never loads the client.
  protected files() {
    this.bucket ??= import('@google-cloud/storage').then(({ Storage }) => new Storage(this.account ?? undefined).bucket(this.name))
    return this.bucket
  }
  async put(objectKey: string, file: { name: string; mime: string }, body: Readable, cap: number) {
    const { contentType, contentDisposition } = served(file.name, file.mime)
    // One request, not a resumable session: a failed or refused stream aborts it and no object is written.
    const sink = (await this.files()).file(objectKey).createWriteStream({ resumable: false, contentType,
      metadata: { contentDisposition, cacheControl: this.cacheControl } })
    return capped(body, cap, sink)
  }
  /** A V4 signed PUT: the signature covers every header below, so storage refuses a request that drops or changes one. */
  async uploadLink(objectKey: string, file: { name: string }, size: number, expiresAt: number): Promise<UploadLink> {
    const { 'content-type': contentType, ...extensionHeaders } = linkHeaders(file.name, size, this.cacheControl)
    const [url] = await (await this.files()).file(objectKey).getSignedUrl({ version: 'v4', action: 'write', expires: expiresAt, contentType, extensionHeaders })
    return { url, headers: { 'content-type': contentType!, ...extensionHeaders } }
  }
  async stored(objectKey: string) {
    try {
      const [metadata] = await (await this.files()).file(objectKey).getMetadata()
      return { size: Number(metadata.size) }
    } catch (error) {
      if (error && typeof error === 'object' && 'code' in error && error.code === 404) return null
      throw error
    }
  }
  async head(objectKey: string, bytes: number) {
    const [content] = await (await this.files()).file(objectKey).download({ start: 0, end: bytes - 1 })
    return content
  }
  async read(objectKey: string) {
    const [content] = await (await this.files()).file(objectKey).download()
    return content
  }
  async delete(objectKey: string) {
    await (await this.files()).file(objectKey).delete({ ignoreNotFound: true })
  }
  /** A V4 signed GET, on Cloud Storage's own host. Signed with the service account key when one is set, else through the
   *  cloud's signing API, a network call: fileLinks.ts and avatarLinks.ts reuse each link through its window. */
  async signedUrl(objectKey: string, expiresAt: number) {
    const [url] = await (await this.files()).file(objectKey).getSignedUrl({ version: 'v4', action: 'read', expires: expiresAt })
    return url
  }
}

/** Avatars in a bucket of their own, which grants nobody read access: each read hands out signed links (avatarLinks.ts). */
export class GcsAvatarStore extends GcsAttachmentStore implements AvatarStore {
  constructor(name: string, account: ServiceAccount | null = null) { super(name, account, 'private, max-age=3600') }
}

/** Avatars in the attachments bucket's avatar folder (prod, Ken 2026-10-28 option B1), linked as chat files are: by signed
 *  links, so a removed member's copied link stops opening and nothing breaks once the bucket is no longer public. */
export class SharedAvatarStore implements AvatarStore {
  constructor(readonly store: AttachmentStore) {}
  put(objectKey: string, file: { name: string; mime: string }, body: Readable, cap: number) { return this.store.put(objectKey, file, body, cap) }
  signedUrl(objectKey: string, expiresAt: number) { return this.store.signedUrl(objectKey, expiresAt) }
  delete(objectKey: string) { return this.store.delete(objectKey) }
}

export class MemoryAttachmentStore implements AttachmentStore, DirectUploads {
  readonly objects = new Map<string, { bytes: Buffer; contentType: string; contentDisposition: string; cacheControl?: string }>()
  private readonly linkSecret = randomBytes(32)
  private readonly readSecret = randomBytes(32)
  /** [readBase]: where its signed read links point, as Cloud Storage's own host for a real bucket. */
  constructor(private readonly now: () => number = Date.now, private readonly readBase = 'https://storage.memory.test') {}
  private readSignature(objectKey: string, expiresAt: number) {
    return createHmac('sha256', this.readSecret).update(`${objectKey}\n${expiresAt}`).digest('hex')
  }
  async signedUrl(objectKey: string, expiresAt: number) {
    return `${this.readBase}/${objectKey}?expires=${expiresAt}&signature=${this.readSignature(objectKey, expiresAt)}`
  }
  /** What the bucket answers a GET of [url] at [at]: the bytes, or null once the link is over, was not signed here, or names
   *  nothing. A link checks its own key only, as a real signed link does. */
  open(url: string, at = this.now()): Buffer | null {
    const link = new URL(url), objectKey = decodeURIComponent(link.pathname.slice(1)), expiresAt = Number(link.searchParams.get('expires'))
    if (`${link.origin}` !== new URL(this.readBase).origin || !(expiresAt > at) || link.searchParams.get('signature') !== this.readSignature(objectKey, expiresAt)) return null
    return this.objects.get(objectKey)?.bytes ?? null
  }
  async put(objectKey: string, file: { name: string; mime: string }, body: Readable, cap: number) {
    const chunks: Buffer[] = []
    const size = await capped(body, cap, new Writable({ write(chunk: Buffer, _encoding, done) { chunks.push(chunk); done() } }))
    this.objects.set(objectKey, { bytes: Buffer.concat(chunks), ...served(file.name, file.mime) })
    return size
  }
  private linkSignature(objectKey: string, expiresAt: number, headers: Record<string, string>) {
    return createHmac('sha256', this.linkSecret).update(JSON.stringify([objectKey, expiresAt, Object.entries(headers).sort()])).digest('hex')
  }
  async uploadLink(objectKey: string, file: { name: string }, size: number, expiresAt: number): Promise<UploadLink> {
    const headers = linkHeaders(file.name, size, CHAT_CACHE_CONTROL)
    const url = `https://storage.memory.test/${encodeURIComponent(objectKey)}?expires=${expiresAt}&signature=${this.linkSignature(objectKey, expiresAt, headers)}`
    return { url, headers }
  }
  /** What the bucket answers a PUT to `url`, with storage's rules: the status, and the object written only on 200. */
  async receive(url: string, headers: Record<string, string>, body: Readable | Buffer): Promise<number> {
    const link = new URL(url), objectKey = decodeURIComponent(link.pathname.slice(1)), expiresAt = Number(link.searchParams.get('expires'))
    const lower = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]))
    const signed = Object.fromEntries(['content-type', 'content-disposition', 'cache-control', 'x-goog-content-length-range', 'x-goog-if-generation-match']
      .flatMap(k => lower[k] === undefined ? [] : [[k, lower[k]!]]))
    const drain = async () => { if (!Buffer.isBuffer(body)) body.resume() }
    if (!(expiresAt > this.now()) || link.searchParams.get('signature') !== this.linkSignature(objectKey, expiresAt, signed) || lower.authorization) { await drain(); return 403 }
    if (signed['x-goog-if-generation-match'] === '0' && this.objects.has(objectKey)) { await drain(); return 412 }
    const [min, max] = (signed['x-goog-content-length-range'] ?? '').split(',').map(Number)
    const chunks: Buffer[] = []
    let size = 0
    try {
      size = await capped(Buffer.isBuffer(body) ? Readable.from([body]) : body, max ?? Infinity, new Writable({ write(chunk: Buffer, _encoding, done) { chunks.push(chunk); done() } }))
    } catch (error) { if (error instanceof AttachmentTooLarge) return 400; throw error }
    if (min !== undefined && size < min) return 400
    this.objects.set(objectKey, { bytes: Buffer.concat(chunks), contentType: signed['content-type']!, contentDisposition: signed['content-disposition']!,
      cacheControl: signed['cache-control'] })
    return 200
  }
  async stored(objectKey: string) { const object = this.objects.get(objectKey); return object ? { size: object.bytes.byteLength } : null }
  async head(objectKey: string, bytes: number) { return (this.objects.get(objectKey)?.bytes ?? Buffer.alloc(0)).subarray(0, bytes) }
  async read(objectKey: string) { return this.objects.get(objectKey)?.bytes ?? Buffer.alloc(0) }
  async delete(objectKey: string) { this.objects.delete(objectKey) }
}

/** Avatars for tests and the local rig: links carry their expiry and an HMAC of it, and `open` honours both as the bucket would. */
export class MemoryAvatarStore extends MemoryAttachmentStore implements AvatarStore {
  constructor(base: string) { super(Date.now, base) }
}

export function attachmentsFromEnv(env: { NODE_ENV: string; SUPER_TAB_ATTACHMENTS_BUCKET: string; SUPER_TAB_ATTACHMENTS_CREDENTIALS: string;
  SUPER_TAB_ATTACHMENTS_PREFIX: string; SUPER_TAB_ATTACHMENTS_PUBLIC_BASE: string; SUPER_TAB_AVATARS_BUCKET: string }): Attachments | null {
  // Stored messages name their files by an address on this base (fileLinks.ts reads the object's key from it): in production
  // only HTTPS, as every link once handed out was. A local or test run may use a plain loopback address.
  if (env.NODE_ENV === 'production' && new URL(env.SUPER_TAB_ATTACHMENTS_PUBLIC_BASE).protocol !== 'https:') {
    throw new Error('SUPER_TAB_ATTACHMENTS_PUBLIC_BASE must be an https:// address in production.')
  }
  // Read even without a bucket, so a broken key fails the deploy that set it rather than the one that adds the bucket.
  const account = serviceAccountFrom(env.SUPER_TAB_ATTACHMENTS_CREDENTIALS)
  if (!env.SUPER_TAB_ATTACHMENTS_BUCKET) return null
  const base = { store: new GcsAttachmentStore(env.SUPER_TAB_ATTACHMENTS_BUCKET, account), prefix: env.SUPER_TAB_ATTACHMENTS_PREFIX,
    publicBase: env.SUPER_TAB_ATTACHMENTS_PUBLIC_BASE }
  // A bucket of their own wins: nobody reads it without a signed link.
  if (env.SUPER_TAB_AVATARS_BUCKET) return { ...base, avatars: new GcsAvatarStore(env.SUPER_TAB_AVATARS_BUCKET, account), avatarPrefix: trimPrefix(base.prefix) }
  // Prod has only the attachments bucket (Ken, 2026-10-28, option B1): avatars live there in their own folder and are linked
  // as chat files are, by signed links (docs/swarms.md). Chat files never go in the avatar folder, and avatar links are made
  // for that folder alone.
  const chat = trimPrefix(base.prefix)
  if (chat === SHARED_AVATAR_PREFIX || chat.startsWith(`${SHARED_AVATAR_PREFIX}/`)) {
    throw new Error(`SUPER_TAB_ATTACHMENTS_PREFIX must not be ${SHARED_AVATAR_PREFIX}/ or inside it while avatars share the attachments bucket. Pick another prefix, or set SUPER_TAB_AVATARS_BUCKET.`)
  }
  return { ...base, avatars: new SharedAvatarStore(base.store), avatarPrefix: SHARED_AVATAR_PREFIX }
}