@felipedsvit/s3node 0.1.2

package/src/features/cors.js

@@ -0,0 +1,115 @@
+import { S3Error } from '../errors.js'
+import { childText, childrenNamed, document, parseXml, text } from '../xml.js'
+
+const MAX_RULES = 100
+
+function ruleValues(rule, name) {
+  return childrenNamed(rule, name).map((child) => child.text)
+}
+
+export function parseCorsXml(body) {
+  const root = parseXml(body)
+  if (root.name !== 'CORSConfiguration') {
+    throw new S3Error('MalformedXML', 'Expected a CORSConfiguration element')
+  }
+  const rules = childrenNamed(root, 'CORSRule').map((rule) => {
+    const allowedOrigins = ruleValues(rule, 'AllowedOrigin')
+    const allowedMethods = ruleValues(rule, 'AllowedMethod').map((method) => method.toUpperCase())
+    if (allowedOrigins.length === 0 || allowedMethods.length === 0) {
+      throw new S3Error('MalformedXML', 'Each CORSRule requires AllowedOrigin and AllowedMethod')
+    }
+    const maxAge = childText(rule, 'MaxAgeSeconds')
+    return {
+      id: childText(rule, 'ID'),
+      allowedOrigins,
+      allowedMethods,
+      allowedHeaders: ruleValues(rule, 'AllowedHeader').map((header) => header.toLowerCase()),
+      exposeHeaders: ruleValues(rule, 'ExposeHeader'),
+      maxAgeSeconds: maxAge === undefined ? undefined : Number.parseInt(maxAge, 10),
+    }
+  })
+  if (rules.length === 0) throw new S3Error('MalformedXML', 'At least one CORSRule is required')
+  if (rules.length > MAX_RULES) {
+    throw new S3Error('MalformedXML', `A maximum of ${MAX_RULES} CORS rules is allowed`)
+  }
+  return { rules }
+}
+
+export function corsXml(config) {
+  const rules = (config?.rules ?? []).map((rule) => (
+    '<CORSRule>' +
+    (rule.id ? text('ID', rule.id) : '') +
+    rule.allowedOrigins.map((origin) => text('AllowedOrigin', origin)).join('') +
+    rule.allowedMethods.map((method) => text('AllowedMethod', method)).join('') +
+    rule.allowedHeaders.map((header) => text('AllowedHeader', header)).join('') +
+    rule.exposeHeaders.map((header) => text('ExposeHeader', header)).join('') +
+    (rule.maxAgeSeconds === undefined ? '' : text('MaxAgeSeconds', rule.maxAgeSeconds)) +
+    '</CORSRule>'
+  )).join('')
+  return document('CORSConfiguration', rules)
+}
+
+/** A single `*` may appear anywhere in an allowed origin. */
+function originMatches(pattern, origin) {
+  if (pattern === '*') return true
+  const star = pattern.indexOf('*')
+  if (star === -1) return pattern === origin
+  const prefix = pattern.slice(0, star)
+  const suffix = pattern.slice(star + 1)
+  return origin.length >= prefix.length + suffix.length &&
+    origin.startsWith(prefix) && origin.endsWith(suffix)
+}
+
+function headersAllowed(rule, requested) {
+  if (requested.length === 0) return true
+  if (rule.allowedHeaders.includes('*')) return true
+  return requested.every((header) => rule.allowedHeaders.includes(header))
+}
+
+export function matchRule(config, { origin, method, requestHeaders = [] }) {
+  if (!config?.rules || !origin) return null
+  for (const rule of config.rules) {
+    if (!rule.allowedOrigins.some((pattern) => originMatches(pattern, origin))) continue
+    if (!rule.allowedMethods.includes(method)) continue
+    if (!headersAllowed(rule, requestHeaders)) continue
+    return rule
+  }
+  return null
+}
+
+export function parseRequestHeaders(header) {
+  return String(header ?? '')
+    .split(',')
+    .map((entry) => entry.trim().toLowerCase())
+    .filter(Boolean)
+}
+
+/**
+ * Headers for an actual (non-preflight) cross-origin response. Vary is always
+ * set so caches do not serve one origin's response to another.
+ */
+export function responseHeaders(rule, origin) {
+  if (!rule) return { Vary: 'Origin' }
+  const headers = {
+    'Access-Control-Allow-Origin': rule.allowedOrigins.includes('*') ? '*' : origin,
+    'Access-Control-Allow-Methods': rule.allowedMethods.join(', '),
+    Vary: 'Origin',
+  }
+  if (rule.exposeHeaders.length) {
+    headers['Access-Control-Expose-Headers'] = rule.exposeHeaders.join(', ')
+  }
+  if (rule.maxAgeSeconds !== undefined) {
+    headers['Access-Control-Max-Age'] = String(rule.maxAgeSeconds)
+  }
+  return headers
+}
+
+export function preflightHeaders(rule, origin, requestHeaders) {
+  const headers = responseHeaders(rule, origin)
+  if (requestHeaders.length) {
+    headers['Access-Control-Allow-Headers'] = rule.allowedHeaders.includes('*')
+      ? requestHeaders.join(', ')
+      : rule.allowedHeaders.filter((header) => requestHeaders.includes(header)).join(', ')
+  }
+  return headers
+}

package/src/features/encryption.js

@@ -0,0 +1,201 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+import { readFile, writeFile } from 'node:fs/promises'
+import { Transform } from 'node:stream'
+import { S3Error } from '../errors.js'
+
+const KEY_BYTES = 32
+const BLOCK_BYTES = 16
+const DATA_CIPHER = 'aes-256-ctr'
+const WRAP_CIPHER = 'aes-256-gcm'
+
+/**
+ * Object data is encrypted with AES-256-CTR rather than GCM because CTR is
+ * seekable: a range read can jump straight to the block containing the first
+ * requested byte. GCM would force decrypting from byte zero on every ranged
+ * GET. Integrity still comes from the stored MD5/checksums, and the SSE-S3 data
+ * key itself is wrapped with GCM.
+ */
+
+/** 128-bit big-endian counter addition, used to seek and to space parts apart. */
+export function advanceIv(iv, blocks) {
+  const value = (BigInt(`0x${iv.toString('hex')}`) + BigInt(blocks)) & ((1n << 128n) - 1n)
+  return Buffer.from(value.toString(16).padStart(32, '0'), 'hex')
+}
+
+/**
+ * Each multipart part gets its own counter window, spaced 2^64 blocks apart.
+ * A part caps out at 5 GiB (2^28 blocks), so windows can never overlap and no
+ * per-part IV has to be stored.
+ */
+export function partIv(baseIv, partNumber) {
+  return partNumber ? advanceIv(baseIv, BigInt(partNumber) << 64n) : Buffer.from(baseIv)
+}
+
+/** Discards the first `count` bytes of a stream. */
+class SkipBytes extends Transform {
+  constructor(count) {
+    super()
+    this.remaining = count
+  }
+
+  _transform(chunk, _encoding, callback) {
+    if (this.remaining >= chunk.length) {
+      this.remaining -= chunk.length
+      callback()
+      return
+    }
+    const output = this.remaining ? chunk.subarray(this.remaining) : chunk
+    this.remaining = 0
+    callback(null, output)
+  }
+}
+
+export class EncryptionManager {
+  constructor(masterKey) {
+    this.masterKey = masterKey
+  }
+
+  /**
+   * Loads the SSE-S3 master key, generating and persisting one on first use.
+   * Losing this file makes every SSE-S3 object unreadable.
+   */
+  static async load(path, provided = null) {
+    if (provided) {
+      const key = Buffer.isBuffer(provided) ? provided : Buffer.from(provided, 'base64')
+      if (key.length !== KEY_BYTES) {
+        throw new TypeError(`encryptionMasterKey must be ${KEY_BYTES} bytes`)
+      }
+      return new EncryptionManager(key)
+    }
+    try {
+      const stored = Buffer.from(await readFile(path, 'utf8'), 'base64')
+      if (stored.length === KEY_BYTES) return new EncryptionManager(stored)
+    } catch {
+      // Fall through and generate one.
+    }
+    const key = randomBytes(KEY_BYTES)
+    await writeFile(path, key.toString('base64'), { mode: 0o600 })
+    return new EncryptionManager(key)
+  }
+
+  /**
+   * Reads the SSE headers off a request. Returns null when the request asks for
+   * no encryption.
+   */
+  parseRequest(headers, { prefix = 'x-amz-server-side-encryption' } = {}) {
+    const customerAlgorithm = headers[`${prefix}-customer-algorithm`]
+    if (customerAlgorithm) {
+      if (String(customerAlgorithm) !== 'AES256') {
+        throw new S3Error('InvalidArgument', 'Unsupported customer encryption algorithm')
+      }
+      const rawKey = headers[`${prefix}-customer-key`]
+      const declaredMd5 = headers[`${prefix}-customer-key-md5`]
+      if (!rawKey || !declaredMd5) {
+        throw new S3Error('InvalidRequest', 'SSE-C requires both the customer key and its MD5')
+      }
+      const key = Buffer.from(String(rawKey), 'base64')
+      if (key.length !== KEY_BYTES) {
+        throw new S3Error('InvalidArgument', 'The customer key must be 256 bits')
+      }
+      const keyMd5 = createHash('md5').update(key).digest('base64')
+      if (keyMd5 !== String(declaredMd5)) {
+        throw new S3Error('InvalidDigest', 'The customer key MD5 does not match the key')
+      }
+      return { mode: 'SSE-C', algorithm: 'AES256', key, keyMd5 }
+    }
+
+    const managed = headers[prefix]
+    if (managed) {
+      if (String(managed) !== 'AES256') {
+        throw new S3Error('InvalidArgument', 'Unsupported server-side encryption algorithm')
+      }
+      return { mode: 'SSE-S3', algorithm: 'AES256' }
+    }
+    return null
+  }
+
+  /** Builds the stored encryption context and the data key used to write. */
+  create(request) {
+    const iv = randomBytes(BLOCK_BYTES)
+    if (request.mode === 'SSE-C') {
+      return {
+        key: request.key,
+        context: { mode: 'SSE-C', algorithm: 'AES256', iv: iv.toString('base64'), keyMd5: request.keyMd5 },
+      }
+    }
+    const dataKey = randomBytes(KEY_BYTES)
+    const wrapIv = randomBytes(12)
+    const wrapper = createCipheriv(WRAP_CIPHER, this.masterKey, wrapIv)
+    const wrapped = Buffer.concat([wrapper.update(dataKey), wrapper.final()])
+    return {
+      key: dataKey,
+      context: {
+        mode: 'SSE-S3',
+        algorithm: 'AES256',
+        iv: iv.toString('base64'),
+        wrappedKey: wrapped.toString('base64'),
+        wrapIv: wrapIv.toString('base64'),
+        wrapTag: wrapper.getAuthTag().toString('base64'),
+      },
+    }
+  }
+
+  /**
+   * Recovers the data key for a stored object. SSE-C objects require the client
+   * to present the same key again; the server never stored it.
+   */
+  resolveKey(context, request) {
+    if (!context) return null
+    if (context.mode === 'SSE-C') {
+      if (!request || request.mode !== 'SSE-C') {
+        throw new S3Error('InvalidRequest',
+          'The object was stored with SSE-C; the same customer key must be supplied to read it')
+      }
+      const stored = Buffer.from(context.keyMd5, 'base64')
+      const offered = Buffer.from(request.keyMd5, 'base64')
+      if (stored.length !== offered.length || !timingSafeEqual(stored, offered)) {
+        throw new S3Error('AccessDenied', 'The customer key does not match the one used to store the object')
+      }
+      return request.key
+    }
+    const unwrapper = createDecipheriv(WRAP_CIPHER, this.masterKey, Buffer.from(context.wrapIv, 'base64'))
+    unwrapper.setAuthTag(Buffer.from(context.wrapTag, 'base64'))
+    return Buffer.concat([
+      unwrapper.update(Buffer.from(context.wrappedKey, 'base64')),
+      unwrapper.final(),
+    ])
+  }
+
+  createEncryptStream(key, context, partNumber = 0) {
+    const iv = partIv(Buffer.from(context.iv, 'base64'), partNumber)
+    return createCipheriv(DATA_CIPHER, key, iv)
+  }
+
+  /**
+   * Decrypts starting at `offset` bytes into the (part's) plaintext. The caller
+   * must have started reading at `blockAlignedOffset(offset)`.
+   */
+  createDecryptStreams(key, context, offset = 0, partNumber = 0) {
+    const base = partIv(Buffer.from(context.iv, 'base64'), partNumber)
+    const block = Math.floor(offset / BLOCK_BYTES)
+    const decipher = createDecipheriv(DATA_CIPHER, key, advanceIv(base, block))
+    const skip = offset - block * BLOCK_BYTES
+    return skip ? [decipher, new SkipBytes(skip)] : [decipher]
+  }
+}
+
+/** Ciphertext must be read from a block boundary for CTR seeking to line up. */
+export function blockAlignedOffset(offset) {
+  return Math.floor(offset / BLOCK_BYTES) * BLOCK_BYTES
+}
+
+export function encryptionResponseHeaders(context) {
+  if (!context) return {}
+  if (context.mode === 'SSE-C') {
+    return {
+      'x-amz-server-side-encryption-customer-algorithm': context.algorithm,
+      'x-amz-server-side-encryption-customer-key-MD5': context.keyMd5,
+    }
+  }
+  return { 'x-amz-server-side-encryption': context.algorithm }
+}

package/src/features/formdata.js

@@ -0,0 +1,169 @@
+import { PassThrough } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import { S3Error } from '../errors.js'
+
+const MAX_HEADER_BYTES = 8192
+const DEFAULT_MAX_FIELD_BYTES = 64 * 1024
+const DEFAULT_MAX_FIELDS = 100
+
+export function parseBoundary(contentType) {
+  const match = /;\s*boundary=(?:"([^"]+)"|([^;\s]+))/i.exec(String(contentType ?? ''))
+  const boundary = match?.[1] ?? match?.[2]
+  if (!boundary) throw new S3Error('MalformedPOSTRequest', 'The Content-Type is missing a boundary')
+  return boundary
+}
+
+/** Pull-based buffer over an async iterable of Buffers. */
+class Scanner {
+  constructor(iterator) {
+    this.iterator = iterator
+    this.buffer = Buffer.alloc(0)
+    this.exhausted = false
+  }
+
+  async fill() {
+    if (this.exhausted) return false
+    const { value, done } = await this.iterator.next()
+    if (done) {
+      this.exhausted = true
+      return false
+    }
+    this.buffer = this.buffer.length ? Buffer.concat([this.buffer, value]) : value
+    return true
+  }
+
+  async readUntil(pattern, maxBytes) {
+    for (;;) {
+      const index = this.buffer.indexOf(pattern)
+      if (index !== -1) {
+        const chunk = this.buffer.subarray(0, index)
+        this.buffer = this.buffer.subarray(index + pattern.length)
+        return chunk
+      }
+      if (this.buffer.length > maxBytes) {
+        throw new S3Error('MalformedPOSTRequest', 'A form part exceeded the maximum accepted size')
+      }
+      if (!(await this.fill())) return null
+    }
+  }
+
+  async ensure(count) {
+    while (this.buffer.length < count) {
+      if (!(await this.fill())) return false
+    }
+    return true
+  }
+}
+
+function parsePartHeaders(raw) {
+  const headers = {}
+  for (const line of raw.toString('latin1').split('\r\n')) {
+    const separator = line.indexOf(':')
+    if (separator === -1) continue
+    headers[line.slice(0, separator).trim().toLowerCase()] = line.slice(separator + 1).trim()
+  }
+  const disposition = headers['content-disposition'] ?? ''
+  const name = /;\s*name="([^"]*)"/i.exec(disposition)?.[1]
+  const filenameMatch = /;\s*filename="([^"]*)"/i.exec(disposition)
+  return {
+    name,
+    filename: filenameMatch?.[1],
+    hasFilename: filenameMatch !== null,
+    contentType: headers['content-type'],
+  }
+}
+
+async function pumpFile(scanner, delimiter, out) {
+  const retain = delimiter.length - 1
+  for (;;) {
+    const index = scanner.buffer.indexOf(delimiter)
+    if (index !== -1) {
+      const tail = scanner.buffer.subarray(0, index)
+      scanner.buffer = scanner.buffer.subarray(index + delimiter.length)
+      if (tail.length && !out.write(tail)) await once(out, 'drain')
+      out.end()
+      return
+    }
+    // Hold back enough bytes that a delimiter split across chunks is still found.
+    if (scanner.buffer.length > retain) {
+      const emit = scanner.buffer.subarray(0, scanner.buffer.length - retain)
+      scanner.buffer = scanner.buffer.subarray(scanner.buffer.length - retain)
+      if (!out.write(emit)) await once(out, 'drain')
+    }
+    if (!(await scanner.fill())) {
+      out.destroy(new S3Error('MalformedPOSTRequest', 'The form data ended before the final boundary'))
+      return
+    }
+  }
+}
+
+function once(emitter, event) {
+  return new Promise((resolve, reject) => {
+    emitter.once(event, resolve)
+    emitter.once('error', reject)
+  })
+}
+
+function sourceIterator(sources) {
+  if (sources.length === 1) return sources[0][Symbol.asyncIterator]()
+  const merged = new PassThrough()
+  pipeline(...sources, merged).catch((err) => merged.destroy(err))
+  return merged[Symbol.asyncIterator]()
+}
+
+/**
+ * Streaming multipart/form-data reader for browser POST uploads.
+ *
+ * Resolves as soon as the file part is reached, so the (possibly very large)
+ * file body is never buffered: it is handed back as a stream that keeps being
+ * fed while the caller writes it to storage. S3 requires the file field to come
+ * last, which is what makes this possible.
+ */
+export async function parseFormData(sources, {
+  boundary,
+  maxFieldBytes = DEFAULT_MAX_FIELD_BYTES,
+  maxFields = DEFAULT_MAX_FIELDS,
+} = {}) {
+  const scanner = new Scanner(sourceIterator(Array.isArray(sources) ? sources : [sources]))
+  const dashBoundary = Buffer.from(`--${boundary}`)
+  const delimiter = Buffer.from(`\r\n--${boundary}`)
+  const fields = new Map()
+
+  // Skip the preamble up to the first boundary.
+  if ((await scanner.readUntil(dashBoundary, maxFieldBytes)) === null) {
+    throw new S3Error('MalformedPOSTRequest', 'No form boundary was found')
+  }
+
+  for (;;) {
+    if (!(await scanner.ensure(2))) {
+      throw new S3Error('MalformedPOSTRequest', 'Truncated form data')
+    }
+    if (scanner.buffer[0] === 0x2d && scanner.buffer[1] === 0x2d) {
+      return { fields, file: null } // closing "--"
+    }
+    scanner.buffer = scanner.buffer.subarray(2) // the CRLF after the boundary
+
+    const rawHeaders = await scanner.readUntil(Buffer.from('\r\n\r\n'), MAX_HEADER_BYTES)
+    if (rawHeaders === null) throw new S3Error('MalformedPOSTRequest', 'Truncated form part headers')
+    const part = parsePartHeaders(rawHeaders)
+    if (!part.name) throw new S3Error('MalformedPOSTRequest', 'A form part is missing its name')
+
+    if (part.hasFilename || part.name.toLowerCase() === 'file') {
+      const stream = new PassThrough()
+      // Deliberately not awaited: the caller consumes the stream while this
+      // keeps feeding it.
+      pumpFile(scanner, delimiter, stream).catch((err) => stream.destroy(err))
+      return {
+        fields,
+        file: { name: part.name, filename: part.filename ?? '', contentType: part.contentType, stream },
+      }
+    }
+
+    const value = await scanner.readUntil(delimiter, maxFieldBytes)
+    if (value === null) throw new S3Error('MalformedPOSTRequest', 'Truncated form field')
+    if (fields.size >= maxFields) {
+      throw new S3Error('MalformedPOSTRequest', `A form may carry at most ${maxFields} fields`)
+    }
+    fields.set(part.name.toLowerCase(), value.toString('utf8'))
+  }
+}

package/src/features/lifecycle.js

@@ -0,0 +1,175 @@
+import { S3Error } from '../errors.js'
+import { childNamed, childText, childrenNamed, document, parseXml, text } from '../xml.js'
+import { toKeyBuffer } from '../util/bytes.js'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const MAX_RULES = 1000
+
+function optionalInt(node, name) {
+  const value = childText(node, name)
+  if (value === undefined) return undefined
+  const parsed = Number.parseInt(value, 10)
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new S3Error('MalformedXML', `Invalid ${name}`)
+  }
+  return parsed
+}
+
+function parseFilter(rule) {
+  // Rules may carry a bare <Prefix> (legacy) or a <Filter>.
+  const legacyPrefix = childText(rule, 'Prefix')
+  const filter = childNamed(rule, 'Filter')
+  if (!filter) return { prefix: legacyPrefix ?? '' }
+  const and = childNamed(filter, 'And')
+  const scope = and ?? filter
+  const tags = {}
+  for (const tag of childrenNamed(scope, 'Tag')) {
+    const key = childText(tag, 'Key')
+    if (key) tags[key] = childText(tag, 'Value') ?? ''
+  }
+  return { prefix: childText(scope, 'Prefix') ?? '', tags }
+}
+
+export function parseLifecycleXml(body) {
+  const root = parseXml(body)
+  if (root.name !== 'LifecycleConfiguration' && root.name !== 'BucketLifecycleConfiguration') {
+    throw new S3Error('MalformedXML', 'Expected a LifecycleConfiguration element')
+  }
+  const rules = childrenNamed(root, 'Rule').map((rule, index) => {
+    const status = childText(rule, 'Status')
+    if (status !== 'Enabled' && status !== 'Disabled') {
+      throw new S3Error('MalformedXML', 'Each Rule requires a Status of Enabled or Disabled')
+    }
+    const expiration = childNamed(rule, 'Expiration')
+    const noncurrent = childNamed(rule, 'NoncurrentVersionExpiration')
+    const abort = childNamed(rule, 'AbortIncompleteMultipartUpload')
+    if (!expiration && !noncurrent && !abort) {
+      throw new S3Error('MalformedXML', 'Each Rule requires at least one action')
+    }
+    const expirationDate = expiration ? childText(expiration, 'Date') : undefined
+    if (expirationDate !== undefined && Number.isNaN(Date.parse(expirationDate))) {
+      throw new S3Error('MalformedXML', 'Invalid Expiration Date')
+    }
+    return {
+      id: childText(rule, 'ID') ?? `rule-${index}`,
+      status,
+      filter: parseFilter(rule),
+      expirationDays: expiration ? optionalInt(expiration, 'Days') : undefined,
+      expirationDate,
+      expiredObjectDeleteMarker: expiration
+        ? childText(expiration, 'ExpiredObjectDeleteMarker') === 'true'
+        : false,
+      noncurrentDays: noncurrent ? optionalInt(noncurrent, 'NoncurrentDays') : undefined,
+      abortAfterDays: abort ? optionalInt(abort, 'DaysAfterInitiation') : undefined,
+    }
+  })
+  if (rules.length === 0) throw new S3Error('MalformedXML', 'At least one Rule is required')
+  if (rules.length > MAX_RULES) {
+    throw new S3Error('MalformedXML', `A maximum of ${MAX_RULES} lifecycle rules is allowed`)
+  }
+  return { rules }
+}
+
+export function lifecycleXml(config) {
+  const rules = (config?.rules ?? []).map((rule) => {
+    const filter = `<Filter>${rule.filter.prefix ? text('Prefix', rule.filter.prefix) : ''}${
+      Object.entries(rule.filter.tags ?? {})
+        .map(([key, value]) => `<Tag>${text('Key', key)}${text('Value', value)}</Tag>`).join('')
+    }</Filter>`
+    const expiration = rule.expirationDays !== undefined || rule.expirationDate || rule.expiredObjectDeleteMarker
+      ? `<Expiration>${
+          rule.expirationDays !== undefined ? text('Days', rule.expirationDays) : ''
+        }${rule.expirationDate ? text('Date', rule.expirationDate) : ''
+        }${rule.expiredObjectDeleteMarker ? text('ExpiredObjectDeleteMarker', 'true') : ''}</Expiration>`
+      : ''
+    const noncurrent = rule.noncurrentDays !== undefined
+      ? `<NoncurrentVersionExpiration>${text('NoncurrentDays', rule.noncurrentDays)}</NoncurrentVersionExpiration>`
+      : ''
+    const abort = rule.abortAfterDays !== undefined
+      ? `<AbortIncompleteMultipartUpload>${
+          text('DaysAfterInitiation', rule.abortAfterDays)}</AbortIncompleteMultipartUpload>`
+      : ''
+    return `<Rule>${text('ID', rule.id)}${filter}${text('Status', rule.status)}${expiration}${noncurrent}${abort}</Rule>`
+  }).join('')
+  return document('LifecycleConfiguration', rules)
+}
+
+function ruleMatches(rule, record) {
+  const prefix = toKeyBuffer(rule.filter.prefix ?? '')
+  if (prefix.length && !record.key.subarray(0, prefix.length).equals(prefix)) return false
+  for (const [key, value] of Object.entries(rule.filter.tags ?? {})) {
+    if ((record.tags ?? {})[key] !== value) return false
+  }
+  return true
+}
+
+function isExpired(rule, timestamp, now) {
+  if (rule.expirationDate !== undefined) return now >= Date.parse(rule.expirationDate)
+  if (rule.expirationDays !== undefined) return now - timestamp >= rule.expirationDays * DAY_MS
+  return false
+}
+
+/**
+ * Applies expiration rules across every bucket that has a lifecycle
+ * configuration. Returns a summary so callers can log or assert on it.
+ *
+ * Deliberately explicit rather than implicit: `ObjectStore` does not run this
+ * on its own, the server schedules it.
+ */
+export async function runLifecycle(store, { now = Date.now() } = {}) {
+  const summary = { expiredObjects: 0, expiredVersions: 0, abortedUploads: 0 }
+
+  for (const { bucket, value: config } of store.metadata.bucketsWithConfig('lifecycle')) {
+    if (!store.metadata.getBucket(bucket)) continue
+    const rules = (config.rules ?? []).filter((rule) => rule.status === 'Enabled')
+    if (rules.length === 0) continue
+
+    for (const rule of rules) {
+      if (rule.abortAfterDays !== undefined) {
+        const cutoff = now - rule.abortAfterDays * DAY_MS
+        for (const upload of store.metadata.uploadsStartedBefore(bucket, cutoff)) {
+          if (!ruleMatches(rule, { key: upload.key, tags: upload.tags })) continue
+          await store.abortMultipartUpload({
+            bucket, key: upload.key.toString('utf8'), uploadId: upload.uploadId,
+          })
+          summary.abortedUploads++
+        }
+      }
+    }
+
+    // Walk every version once and let each rule vote on it.
+    for (const record of store.metadata.objectsModifiedBefore(bucket, now + 1)) {
+      for (const rule of rules) {
+        if (!ruleMatches(rule, record)) continue
+
+        if (!record.isLatest && rule.noncurrentDays !== undefined) {
+          if (now - record.lastModified.getTime() >= rule.noncurrentDays * DAY_MS) {
+            await store.deleteObject(bucket, record.key.toString('utf8'), record.versionId)
+            summary.expiredVersions++
+            break
+          }
+        }
+
+        if (record.isLatest && !record.isDeleteMarker &&
+            isExpired(rule, record.lastModified.getTime(), now)) {
+          await store.deleteObject(bucket, record.key.toString('utf8'))
+          summary.expiredObjects++
+          break
+        }
+
+        if (record.isLatest && record.isDeleteMarker && rule.expiredObjectDeleteMarker) {
+          const remaining = store.metadata.allVersionsOfKey(bucket, record.key)
+          if (remaining.length === 1) {
+            await store.deleteObject(bucket, record.key.toString('utf8'), record.versionId)
+            summary.expiredVersions++
+            break
+          }
+        }
+      }
+    }
+  }
+
+  return summary
+}
+
+export { DAY_MS }