@felipedsvit/s3node 0.1.2

package/src/http.js

@@ -0,0 +1,243 @@
+import { randomBytes } from 'node:crypto'
+import { Writable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import { S3Error } from './errors.js'
+import { errorDocument } from './xml.js'
+
+export const MAX_XML_BODY_BYTES = 1024 * 1024
+
+export function requestId() {
+  return randomBytes(8).toString('hex').toUpperCase()
+}
+
+export function hostId() {
+  return randomBytes(24).toString('base64')
+}
+
+/** RFC 1123, as required for Last-Modified and Date headers. */
+export function httpDate(date) {
+  return date.toUTCString()
+}
+
+/** ISO 8601 with milliseconds, as required inside S3 XML payloads. */
+export function isoDate(date) {
+  return date.toISOString()
+}
+
+function safeDecode(value) {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+export function parseQueryPairs(rawQuery) {
+  if (!rawQuery) return []
+  return rawQuery.split('&').filter(Boolean).map((pair) => {
+    const eq = pair.indexOf('=')
+    return eq === -1
+      ? [safeDecode(pair), '']
+      : [safeDecode(pair.slice(0, eq)), safeDecode(pair.slice(eq + 1))]
+  })
+}
+
+/**
+ * Resolve bucket and key.
+ *
+ * Virtual-host style is only attempted when a base domain is configured. SigV4
+ * signs the Host header, so a proxy that rewrites Host invalidates every
+ * signature — see docs/plan.md section 4.6.
+ */
+function resolveTarget(rawPath, headers, virtualHostDomain) {
+  const decodedPath = safeDecode(rawPath)
+  if (virtualHostDomain) {
+    const host = String(headers.host ?? '').split(':')[0].toLowerCase()
+    const suffix = `.${virtualHostDomain.toLowerCase()}`
+    if (host.endsWith(suffix) && host.length > suffix.length) {
+      return {
+        bucket: host.slice(0, -suffix.length),
+        key: decodedPath.length > 1 ? decodedPath.slice(1) : '',
+        style: 'virtual-host',
+      }
+    }
+  }
+  const trimmed = decodedPath.startsWith('/') ? decodedPath.slice(1) : decodedPath
+  if (trimmed === '') return { bucket: '', key: '', style: 'path' }
+  const slash = trimmed.indexOf('/')
+  return slash === -1
+    ? { bucket: trimmed, key: '', style: 'path' }
+    : { bucket: trimmed.slice(0, slash), key: trimmed.slice(slash + 1), style: 'path' }
+}
+
+export function createContext(req, { virtualHostDomain = null } = {}) {
+  const rawUrl = req.url ?? '/'
+  const queryStart = rawUrl.indexOf('?')
+  const rawPath = queryStart === -1 ? rawUrl : rawUrl.slice(0, queryStart)
+  const rawQuery = queryStart === -1 ? '' : rawUrl.slice(queryStart + 1)
+  const queryPairs = parseQueryPairs(rawQuery)
+
+  const query = new Map()
+  for (const [name, value] of queryPairs) if (!query.has(name)) query.set(name, value)
+
+  const { bucket, key, style } = resolveTarget(rawPath, req.headers, virtualHostDomain)
+
+  return {
+    req,
+    method: req.method,
+    rawPath,
+    rawQuery,
+    queryPairs,
+    query,
+    headers: req.headers,
+    bucket,
+    key,
+    style,
+    requestId: requestId(),
+    hostId: hostId(),
+    bodyStreams: [req],
+    trailers: null,
+  }
+}
+
+/** User metadata carried on `x-amz-meta-*` headers. */
+export function userMetadata(headers) {
+  const metadata = {}
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.startsWith('x-amz-meta-')) metadata[name.slice('x-amz-meta-'.length)] = String(value)
+  }
+  return metadata
+}
+
+export async function collectBody(sources, maxBytes = MAX_XML_BODY_BYTES) {
+  const chunks = []
+  let total = 0
+  const sink = new Writable({
+    write(chunk, _encoding, callback) {
+      total += chunk.length
+      if (total > maxBytes) {
+        callback(new S3Error('MalformedXML', 'Request body exceeds the maximum accepted size'))
+        return
+      }
+      chunks.push(chunk)
+      callback()
+    },
+  })
+  await pipeline(...sources, sink)
+  return Buffer.concat(chunks)
+}
+
+export function baseHeaders(ctx) {
+  return {
+    'x-amz-request-id': ctx.requestId,
+    'x-amz-id-2': ctx.hostId,
+    Date: httpDate(new Date()),
+    Server: 'S3Node',
+  }
+}
+
+export function sendXml(ctx, res, status, body, extraHeaders = {}) {
+  const payload = Buffer.from(body, 'utf8')
+  res.writeHead(status, {
+    ...baseHeaders(ctx),
+    'Content-Type': 'application/xml',
+    'Content-Length': payload.length,
+    ...extraHeaders,
+  })
+  res.end(ctx.method === 'HEAD' ? undefined : payload)
+}
+
+export function sendEmpty(ctx, res, status, extraHeaders = {}) {
+  res.writeHead(status, { ...baseHeaders(ctx), 'Content-Length': 0, ...extraHeaders })
+  res.end()
+}
+
+export function sendError(ctx, res, error) {
+  const s3 = error instanceof S3Error ? error : new S3Error('InternalError', error?.message)
+  if (res.headersSent) {
+    res.destroy()
+    return s3
+  }
+  const body = errorDocument({
+    code: s3.code,
+    message: s3.message,
+    resource: ctx?.rawPath ?? '/',
+    requestId: ctx?.requestId ?? requestId(),
+    hostId: ctx?.hostId ?? hostId(),
+  })
+  const payload = Buffer.from(body, 'utf8')
+  const headers = {
+    'x-amz-request-id': ctx?.requestId ?? requestId(),
+    'x-amz-id-2': ctx?.hostId ?? hostId(),
+    Date: httpDate(new Date()),
+    Server: 'S3Node',
+    'Content-Type': 'application/xml',
+    'Content-Length': payload.length,
+  }
+  if (s3.detail?.contentRange) headers['Content-Range'] = s3.detail.contentRange
+  Object.assign(headers, s3.detail?.headers ?? {})
+  res.writeHead(s3.statusCode, headers)
+  // A 304 or a HEAD response must not carry a body.
+  res.end(ctx?.method === 'HEAD' || s3.statusCode === 304 ? undefined : payload)
+  return s3
+}
+
+/** Parse a single-range `Range: bytes=` header. Returns null when absent. */
+export function parseRange(header, size) {
+  if (!header) return null
+  const match = /^bytes=(\d*)-(\d*)$/.exec(String(header).trim())
+  if (!match) return null
+  const [, rawStart, rawEnd] = match
+  if (rawStart === '' && rawEnd === '') return null
+
+  let start
+  let end
+  if (rawStart === '') {
+    const suffix = Number.parseInt(rawEnd, 10)
+    if (suffix <= 0) throw new S3Error('InvalidRange', undefined, { contentRange: `bytes */${size}` })
+    start = Math.max(size - suffix, 0)
+    end = size - 1
+  } else {
+    start = Number.parseInt(rawStart, 10)
+    end = rawEnd === '' ? size - 1 : Number.parseInt(rawEnd, 10)
+    if (end >= size) end = size - 1
+  }
+  if (start >= size || start > end) {
+    throw new S3Error('InvalidRange', undefined, { contentRange: `bytes */${size}` })
+  }
+  return { start, end }
+}
+
+function etagMatches(candidate, etag) {
+  const normalize = (value) => value.trim().replace(/^W\//, '').replaceAll('"', '')
+  return candidate.split(',').some((entry) => {
+    const trimmed = entry.trim()
+    return trimmed === '*' || normalize(trimmed) === normalize(etag)
+  })
+}
+
+/**
+ * RFC 7232 precondition evaluation. Order matters: If-Match wins over
+ * If-Unmodified-Since, If-None-Match over If-Modified-Since.
+ */
+export function evaluatePreconditions(headers, { etag, lastModified }) {
+  const modifiedSeconds = Math.floor(lastModified.getTime() / 1000)
+
+  if (headers['if-match'] !== undefined) {
+    if (!etagMatches(headers['if-match'], etag)) throw new S3Error('PreconditionFailed')
+  } else if (headers['if-unmodified-since'] !== undefined) {
+    const since = Date.parse(headers['if-unmodified-since'])
+    if (Number.isFinite(since) && modifiedSeconds > Math.floor(since / 1000)) {
+      throw new S3Error('PreconditionFailed')
+    }
+  }
+
+  if (headers['if-none-match'] !== undefined) {
+    if (etagMatches(headers['if-none-match'], etag)) return 'not-modified'
+  } else if (headers['if-modified-since'] !== undefined) {
+    const since = Date.parse(headers['if-modified-since'])
+    if (Number.isFinite(since) && modifiedSeconds <= Math.floor(since / 1000)) return 'not-modified'
+  }
+
+  return 'ok'
+}

package/src/index.js

@@ -0,0 +1,30 @@
+export { S3NodeServer } from './server.js'
+export { CredentialStore, generateCredential } from './auth/credentials.js'
+export { ObjectStore } from './storage/store.js'
+export { BlobStore } from './storage/blobs.js'
+export { MetadataStore, NULL_VERSION, SCHEMA_VERSION } from './storage/metadata.js'
+export { S3Error, ERROR_CODES } from './errors.js'
+export { ChunkedDecoder, encodeChunked } from './auth/chunked.js'
+export { EncryptionManager } from './features/encryption.js'
+export { evaluatePolicy, parsePolicy } from './features/policy.js'
+export { runLifecycle } from './features/lifecycle.js'
+export { NotificationDispatcher, buildEvent } from './features/notifications.js'
+export * as sigv4 from './auth/sigv4.js'
+
+import { S3NodeServer } from './server.js'
+
+/**
+ * Create and start a server in one call.
+ *
+ * Running in-process is the point of shipping this on Node: tests can boot a
+ * real S3 endpoint without a container or a Go/Rust binary (docs/plan.md 5.5).
+ *
+ *   const s3 = await createServer({ dataDir: './data', credentials: [...] })
+ *   // s3.endpoint -> http://127.0.0.1:54321
+ */
+export async function createServer(options = {}) {
+  const server = await S3NodeServer.create(options)
+  const address = await server.listen(options.port ?? 0, options.host ?? '127.0.0.1')
+  server.endpoint = address.endpoint
+  return server
+}

package/src/router.js

@@ -0,0 +1,128 @@
+import { S3Error } from './errors.js'
+import * as handlers from './handlers/index.js'
+import { bucketArn, objectArn } from './features/policy.js'
+
+/**
+ * Sub-resources that are recognised but not implemented. Returning
+ * NotImplemented is deliberate: silently succeeding would let a client believe
+ * an ACL or a replication rule had been applied.
+ */
+const NOT_IMPLEMENTED_SUBRESOURCES = [
+  'acl', 'website', 'replication', 'encryption', 'object-lock', 'accelerate',
+  'logging', 'requestPayment', 'analytics', 'inventory', 'metrics', 'publicAccessBlock',
+  'intelligent-tiering', 'ownershipControls', 'legal-hold', 'retention', 'restore', 'select',
+]
+
+function rejectUnimplemented(ctx) {
+  for (const subresource of NOT_IMPLEMENTED_SUBRESOURCES) {
+    if (ctx.query.has(subresource)) {
+      throw new S3Error('NotImplemented', `The ${subresource} subresource is not implemented`)
+    }
+  }
+}
+
+const route = (handler, action) => ({ handler, action })
+
+function bucketRoute(ctx) {
+  const { method, query } = ctx
+
+  if (method === 'PUT') {
+    if (query.has('versioning')) return route(handlers.putBucketVersioning, 's3:PutBucketVersioning')
+    if (query.has('policy')) return route(handlers.putBucketPolicy, 's3:PutBucketPolicy')
+    if (query.has('cors')) return route(handlers.putBucketCors, 's3:PutBucketCORS')
+    if (query.has('lifecycle')) return route(handlers.putBucketLifecycle, 's3:PutLifecycleConfiguration')
+    if (query.has('tagging')) return route(handlers.putBucketTagging, 's3:PutBucketTagging')
+    if (query.has('notification')) return route(handlers.putBucketNotification, 's3:PutBucketNotification')
+    return route(handlers.createBucket, 's3:CreateBucket')
+  }
+
+  if (method === 'DELETE') {
+    if (query.has('policy')) return route(handlers.deleteBucketPolicy, 's3:DeleteBucketPolicy')
+    if (query.has('cors')) return route(handlers.deleteBucketCors, 's3:PutBucketCORS')
+    if (query.has('lifecycle')) return route(handlers.deleteBucketLifecycle, 's3:PutLifecycleConfiguration')
+    if (query.has('tagging')) return route(handlers.deleteBucketTagging, 's3:PutBucketTagging')
+    return route(handlers.deleteBucket, 's3:DeleteBucket')
+  }
+
+  if (method === 'HEAD') return route(handlers.headBucket, 's3:ListBucket')
+
+  if (method === 'POST') {
+    if (query.has('delete')) return route(handlers.deleteObjects, 's3:DeleteObject')
+    return route(handlers.postObject, 's3:PutObject')
+  }
+
+  if (method === 'GET') {
+    if (query.has('location')) return route(handlers.getBucketLocation, 's3:GetBucketLocation')
+    if (query.has('versioning')) return route(handlers.getBucketVersioning, 's3:GetBucketVersioning')
+    if (query.has('policy')) return route(handlers.getBucketPolicy, 's3:GetBucketPolicy')
+    if (query.has('cors')) return route(handlers.getBucketCors, 's3:GetBucketCORS')
+    if (query.has('lifecycle')) return route(handlers.getBucketLifecycle, 's3:GetLifecycleConfiguration')
+    if (query.has('tagging')) return route(handlers.getBucketTagging, 's3:GetBucketTagging')
+    if (query.has('notification')) return route(handlers.getBucketNotification, 's3:GetBucketNotification')
+    if (query.has('versions')) return route(handlers.listObjectVersions, 's3:ListBucketVersions')
+    if (query.has('uploads')) return route(handlers.listMultipartUploads, 's3:ListBucketMultipartUploads')
+    return query.get('list-type') === '2'
+      ? route(handlers.listObjectsV2, 's3:ListBucket')
+      : route(handlers.listObjectsV1, 's3:ListBucket')
+  }
+
+  throw new S3Error('MethodNotAllowed')
+}
+
+function objectRoute(ctx) {
+  const { method, query, headers } = ctx
+  const uploadId = query.get('uploadId')
+
+  if (method === 'PUT') {
+    if (query.has('tagging')) return route(handlers.putObjectTagging, 's3:PutObjectTagging')
+    if (uploadId && query.has('partNumber')) return route(handlers.uploadPart, 's3:PutObject')
+    if (headers['x-amz-copy-source']) return route(handlers.copyObject, 's3:PutObject')
+    return route(handlers.putObject, 's3:PutObject')
+  }
+
+  if (method === 'POST') {
+    if (query.has('uploads')) return route(handlers.createMultipartUpload, 's3:PutObject')
+    if (uploadId) return route(handlers.completeMultipartUpload, 's3:PutObject')
+    throw new S3Error('MethodNotAllowed')
+  }
+
+  if (method === 'GET') {
+    if (query.has('tagging')) return route(handlers.getObjectTagging, 's3:GetObjectTagging')
+    if (uploadId) return route(handlers.listParts, 's3:ListMultipartUploadParts')
+    return route(handlers.getObject, 's3:GetObject')
+  }
+
+  if (method === 'HEAD') return route(handlers.headObject, 's3:GetObject')
+
+  if (method === 'DELETE') {
+    if (query.has('tagging')) return route(handlers.deleteObjectTagging, 's3:DeleteObjectTagging')
+    if (uploadId) return route(handlers.abortMultipartUpload, 's3:AbortMultipartUpload')
+    return route(handlers.deleteObject, 's3:DeleteObject')
+  }
+
+  throw new S3Error('MethodNotAllowed')
+}
+
+/**
+ * S3 routing is unusual: sub-resources arrive as query-string flags rather than
+ * path segments, so dispatch is a decision tree rather than a path table
+ * (docs/plan.md section 8).
+ *
+ * Returns the handler alongside the IAM action it performs and the ARN it acts
+ * on, which is what bucket-policy evaluation needs.
+ */
+export function resolveRoute(ctx) {
+  if (!ctx.bucket) {
+    if (ctx.method === 'GET') {
+      return { ...route(handlers.listBuckets, 's3:ListAllMyBuckets'), resource: 'arn:aws:s3:::*' }
+    }
+    throw new S3Error('MethodNotAllowed')
+  }
+
+  rejectUnimplemented(ctx)
+  const resolved = ctx.key ? objectRoute(ctx) : bucketRoute(ctx)
+  return {
+    ...resolved,
+    resource: ctx.key ? objectArn(ctx.bucket, ctx.key) : bucketArn(ctx.bucket),
+  }
+}

package/src/server.js

@@ -0,0 +1,282 @@
+import { createServer as createHttpServer } from 'node:http'
+import { ChunkedDecoder } from './auth/chunked.js'
+import { CredentialStore } from './auth/credentials.js'
+import {
+  STREAMING_PAYLOADS,
+  STREAMING_SIGNED,
+  STREAMING_SIGNED_TRAILER,
+  verifyRequest,
+} from './auth/sigv4.js'
+import { S3Error } from './errors.js'
+import {
+  matchRule,
+  parseRequestHeaders,
+  preflightHeaders,
+  responseHeaders as corsResponseHeaders,
+} from './features/cors.js'
+import { runLifecycle } from './features/lifecycle.js'
+import { NotificationDispatcher } from './features/notifications.js'
+import { evaluatePolicy, objectArn } from './features/policy.js'
+import { createContext, sendEmpty, sendError } from './http.js'
+import { resolveRoute } from './router.js'
+import { ObjectStore } from './storage/store.js'
+
+const DEFAULT_REGION = 'us-east-1'
+
+export class S3NodeServer {
+  constructor({
+    store, credentials, region = DEFAULT_REGION, virtualHostDomain = null, logger = null,
+    lifecycleIntervalMs = 0,
+  }) {
+    this.store = store
+    this.credentials = credentials
+    this.region = region
+    this.virtualHostDomain = virtualHostDomain
+    this.logger = logger
+    this.notifications = new NotificationDispatcher(store, { region, logger })
+    this.lifecycleTimer = null
+    this.http = createHttpServer()
+
+    this.http.on('request', (req, res) => {
+      if (req.headers.expect) return // handled by the checkContinue listener
+      this._handle(req, res, false)
+    })
+    this.http.on('checkContinue', (req, res) => {
+      this._handle(req, res, true)
+    })
+    this.http.on('clientError', (err, socket) => {
+      if (socket.writable) socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n')
+    })
+
+    if (lifecycleIntervalMs > 0) {
+      this.lifecycleTimer = setInterval(() => {
+        this.runLifecycle().catch((err) =>
+          this.logger?.error?.({ message: 'lifecycle sweep failed', error: err.message }))
+      }, lifecycleIntervalMs)
+      this.lifecycleTimer.unref?.()
+    }
+  }
+
+  static async create({
+    dataDir,
+    credentials = [],
+    region = DEFAULT_REGION,
+    virtualHostDomain = null,
+    minPartSize,
+    encryptionMasterKey = null,
+    lifecycleIntervalMs = 0,
+    logger = null,
+  } = {}) {
+    if (!dataDir) throw new TypeError('dataDir is required')
+    const store = await ObjectStore.open({ dataDir, region, minPartSize, encryptionMasterKey })
+    return new S3NodeServer({
+      store,
+      credentials: credentials instanceof CredentialStore ? credentials : new CredentialStore(credentials),
+      region,
+      virtualHostDomain,
+      logger,
+      lifecycleIntervalMs,
+    })
+  }
+
+  /** Applies expiration rules once. Also exposed so callers can trigger it. */
+  runLifecycle(options) {
+    return runLifecycle(this.store, options)
+  }
+
+  /**
+   * `Expect: 100-continue` is answered only after the request is both
+   * authenticated and authorised, so a rejected client is turned away before it
+   * uploads the body rather than after (docs/plan.md section 4.8).
+   */
+  async _handle(req, res, expectContinue) {
+    let ctx = null
+    try {
+      ctx = createContext(req, { virtualHostDomain: this.virtualHostDomain })
+
+      if (req.method === 'OPTIONS') {
+        this._handlePreflight(ctx, res)
+        return
+      }
+
+      const route = resolveRoute(ctx)
+      // A browser form upload carries its credential and signature in the form
+      // body, so it authenticates itself once the body has been parsed.
+      const selfAuthenticating = route.handler.name === 'postObject'
+
+      ctx.auth = selfAuthenticating
+        ? { anonymous: false, deferred: true, payloadHash: null }
+        : this._authenticate(ctx)
+
+      if (!selfAuthenticating) this.authorize(ctx, route.action, route.resource)
+
+      if (expectContinue) res.writeContinue()
+
+      this._attachBody(ctx)
+      this._applyCors(ctx, res)
+      await route.handler(ctx, res, { store: this.store, server: this })
+    } catch (err) {
+      const rendered = sendError(ctx, res, err)
+      this.logger?.error?.({
+        requestId: ctx?.requestId,
+        method: req.method,
+        url: req.url,
+        code: rendered.code,
+        message: rendered.message,
+        canonicalRequest: rendered.detail?.canonicalRequest,
+        stringToSign: rendered.detail?.stringToSign,
+      })
+    }
+  }
+
+  _authenticate(ctx) {
+    const signed = ctx.headers.authorization || ctx.query.get('X-Amz-Signature') !== undefined
+    if (!signed) {
+      // Anonymous is allowed to reach policy evaluation; the default there is
+      // deny, so an unauthenticated request only proceeds if a bucket policy
+      // explicitly permits it.
+      return {
+        anonymous: true,
+        payloadHash: ctx.headers['x-amz-content-sha256'] ?? 'UNSIGNED-PAYLOAD',
+      }
+    }
+    return {
+      anonymous: false,
+      ...verifyRequest(ctx, { lookupCredential: this.credentials.lookup, region: this.region }),
+    }
+  }
+
+  _bucketConfig(bucket, name) {
+    if (!bucket) return null
+    try {
+      return this.store.metadata.getConfig(bucket, name)
+    } catch {
+      return null
+    }
+  }
+
+  _conditionContext(ctx) {
+    const socket = ctx.req.socket
+    return {
+      principal: ctx.auth.anonymous ? '*' : `arn:aws:iam::s3node:user/${ctx.auth.accessKeyId}`,
+      'aws:sourceip': socket?.remoteAddress ?? '',
+      'aws:securetransport': String(Boolean(socket?.encrypted)),
+      'aws:useragent': ctx.headers['user-agent'],
+      'aws:referer': ctx.headers.referer,
+      'aws:principaltype': ctx.auth.anonymous ? 'Anonymous' : 'User',
+      's3:prefix': ctx.query.get('prefix'),
+      's3:delimiter': ctx.query.get('delimiter'),
+      's3:max-keys': ctx.query.get('max-keys'),
+      's3:x-amz-acl': ctx.headers['x-amz-acl'],
+      's3:x-amz-server-side-encryption': ctx.headers['x-amz-server-side-encryption'],
+      's3:x-amz-content-sha256': ctx.headers['x-amz-content-sha256'],
+    }
+  }
+
+  /**
+   * Bucket policy evaluation. Explicit Deny always wins; when the policy is
+   * silent the holder of a valid credential is allowed and anonymous is not.
+   */
+  authorize(ctx, action, resource, overrides = {}) {
+    const policy = this._bucketConfig(ctx.bucket, 'policy')
+    const context = { ...this._conditionContext(ctx), ...overrides }
+    const decision = evaluatePolicy(policy, { action, resource, context })
+
+    if (decision === 'Deny') throw new S3Error('AccessDenied')
+    if (decision === 'Allow') return
+    if (ctx.auth.anonymous) throw new S3Error('AccessDenied')
+  }
+
+  /** Used by the POST upload handler once the form has revealed its principal. */
+  authorizePostUpload(ctx, key, accessKeyId) {
+    const previous = ctx.auth
+    ctx.auth = { anonymous: false, accessKeyId }
+    try {
+      this.authorize(ctx, 's3:PutObject', objectArn(ctx.bucket, key))
+    } finally {
+      ctx.auth = previous
+    }
+  }
+
+  /* -------------------------------- CORS -------------------------------- */
+
+  _handlePreflight(ctx, res) {
+    const origin = ctx.headers.origin
+    const method = ctx.headers['access-control-request-method']
+    if (!origin || !method) {
+      throw new S3Error('InvalidRequest', 'This is not a valid CORS preflight request')
+    }
+    const requestHeaders = parseRequestHeaders(ctx.headers['access-control-request-headers'])
+    const rule = matchRule(this._bucketConfig(ctx.bucket, 'cors'), {
+      origin, method: String(method).toUpperCase(), requestHeaders,
+    })
+    // Preflight is intentionally unauthenticated: browsers never attach
+    // credentials to it.
+    if (!rule) throw new S3Error('AccessForbidden')
+    sendEmpty(ctx, res, 200, preflightHeaders(rule, origin, requestHeaders))
+  }
+
+  _applyCors(ctx, res) {
+    const origin = ctx.headers.origin
+    if (!origin || !ctx.bucket) return
+    const rule = matchRule(this._bucketConfig(ctx.bucket, 'cors'), { origin, method: ctx.method })
+    // Headers set here survive writeHead(): Node merges them, with writeHead's
+    // own object taking precedence.
+    for (const [name, value] of Object.entries(corsResponseHeaders(rule, origin))) {
+      res.setHeader(name, value)
+    }
+  }
+
+  /**
+   * Wraps the request in the `aws-chunked` decoder when the payload is
+   * streamed. Without this the framing bytes are written into the object and
+   * every aws-cli upload is silently corrupted (docs/plan.md section 4.1).
+   */
+  _attachBody(ctx) {
+    const payloadHash = ctx.auth.payloadHash
+    if (!payloadHash || !STREAMING_PAYLOADS.has(payloadHash)) return
+
+    const declaredLength = ctx.headers['x-amz-decoded-content-length']
+    const expectedLength = declaredLength === undefined ? null : Number.parseInt(declaredLength, 10)
+    if (declaredLength !== undefined && !Number.isInteger(expectedLength)) {
+      throw new S3Error('InvalidArgument', 'Invalid x-amz-decoded-content-length')
+    }
+
+    const decoder = new ChunkedDecoder({
+      signed: !ctx.auth.anonymous &&
+        (payloadHash === STREAMING_SIGNED || payloadHash === STREAMING_SIGNED_TRAILER),
+      seedSignature: ctx.auth.seedSignature,
+      signingKey: ctx.auth.signingKey,
+      scope: ctx.auth.scope,
+      amzDate: ctx.auth.amzDate,
+      expectedLength,
+    })
+
+    ctx.trailers = decoder.trailers
+    ctx.bodyStreams = [ctx.req, decoder]
+  }
+
+  listen(port = 0, host = '127.0.0.1') {
+    return new Promise((resolve, reject) => {
+      this.http.once('error', reject)
+      this.http.listen(port, host, () => {
+        this.http.removeListener('error', reject)
+        resolve(this.address())
+      })
+    })
+  }
+
+  address() {
+    const address = this.http.address()
+    if (!address) return null
+    const host = address.family === 'IPv6' ? `[${address.address}]` : address.address
+    return { ...address, endpoint: `http://${host}:${address.port}` }
+  }
+
+  async close() {
+    if (this.lifecycleTimer) clearInterval(this.lifecycleTimer)
+    await new Promise((resolve) => this.http.close(resolve))
+    await this.notifications.drain()
+    this.store.close()
+  }
+}