@felipedsvit/s3node 0.1.2

package/src/auth/chunked.js

@@ -0,0 +1,277 @@
+import { createHash } from 'node:crypto'
+import { Transform } from 'node:stream'
+import { S3Error } from '../errors.js'
+import {
+  EMPTY_SHA256,
+  calculateSignature,
+  chunkStringToSign,
+  signaturesMatch,
+  trailerStringToSign,
+} from './sigv4.js'
+
+const CRLF = Buffer.from('\r\n')
+const MAX_LINE_BYTES = 8192
+const MAX_CHUNK_BYTES = 1024 * 1024 * 1024
+
+/**
+ * Strips `aws-chunked` framing from a request body.
+ *
+ * The aws-cli does not send object bytes raw — it wraps them in
+ * `<hex-size>;chunk-signature=<sig>\r\n<data>\r\n` frames. Writing the request
+ * body straight to disk therefore stores the framing alongside the data and
+ * silently corrupts every object the CLI uploads. See docs/plan.md 4.1.
+ *
+ * Chunk signatures are verified as each frame completes. Data is forwarded
+ * before its frame is verified, which is safe because object metadata is only
+ * committed after the whole body succeeds — a failed verification destroys the
+ * stream and leaves nothing but an orphaned temp file (docs/plan.md 8).
+ */
+export class ChunkedDecoder extends Transform {
+  constructor({
+    signed = false,
+    seedSignature = null,
+    signingKey = null,
+    scope = null,
+    amzDate = null,
+    expectedLength = null,
+  } = {}, options = {}) {
+    super(options)
+    this.signed = signed
+    this.previousSignature = seedSignature
+    this.signingKey = signingKey
+    this.scope = scope
+    this.amzDate = amzDate
+    this.expectedLength = expectedLength
+
+    this.trailers = Object.create(null)
+    this.decodedLength = 0
+
+    this._pending = Buffer.alloc(0)
+    this._state = 'size'
+    this._remaining = 0
+    this._chunkHash = null
+    this._chunkSignature = null
+    this._trailerBytes = ''
+  }
+
+  _transform(chunk, _encoding, callback) {
+    this._pending = this._pending.length ? Buffer.concat([this._pending, chunk]) : chunk
+    try {
+      this._drain()
+      callback()
+    } catch (err) {
+      callback(err)
+    }
+  }
+
+  _flush(callback) {
+    try {
+      this._drain()
+      if (this._state === 'trailer' && this._pending.length) {
+        this._consumeTrailerLine(this._pending.toString('latin1').replace(/\r?\n$/, ''))
+        this._pending = Buffer.alloc(0)
+      }
+      if (this._state !== 'done' && this._state !== 'trailer') {
+        throw new S3Error('IncompleteBody', 'The request body terminated before the final chunk')
+      }
+      this._verifyTrailerSignature()
+      if (this.expectedLength !== null && this.decodedLength !== this.expectedLength) {
+        throw new S3Error(
+          'IncompleteBody',
+          `Decoded body length ${this.decodedLength} does not match x-amz-decoded-content-length ${this.expectedLength}`,
+        )
+      }
+      callback()
+    } catch (err) {
+      callback(err)
+    }
+  }
+
+  _takeLine() {
+    const index = this._pending.indexOf(CRLF)
+    if (index === -1) {
+      if (this._pending.length > MAX_LINE_BYTES) {
+        throw new S3Error('InvalidRequest', 'Malformed aws-chunked framing: line too long')
+      }
+      return null
+    }
+    const line = this._pending.subarray(0, index).toString('latin1')
+    this._pending = this._pending.subarray(index + 2)
+    return line
+  }
+
+  _drain() {
+    for (;;) {
+      if (this._state === 'done') return
+
+      if (this._state === 'size') {
+        const line = this._takeLine()
+        if (line === null) return
+        const [sizeField, ...extensions] = line.split(';')
+        const size = Number.parseInt(sizeField.trim(), 16)
+        if (!Number.isInteger(size) || size < 0 || size > MAX_CHUNK_BYTES) {
+          throw new S3Error('InvalidRequest', `Malformed aws-chunked framing: bad chunk size "${sizeField}"`)
+        }
+        this._chunkSignature = null
+        for (const extension of extensions) {
+          const [name, value] = extension.split('=')
+          if (name?.trim() === 'chunk-signature') this._chunkSignature = value?.trim() ?? null
+        }
+        if (this.signed && !this._chunkSignature) {
+          throw new S3Error('SignatureDoesNotMatch', 'Chunk is missing chunk-signature')
+        }
+        if (size === 0) {
+          this._verifyChunk(EMPTY_SHA256)
+          this._state = 'trailer'
+          continue
+        }
+        this._remaining = size
+        this._chunkHash = this.signed ? createHash('sha256') : null
+        this._state = 'data'
+        continue
+      }
+
+      if (this._state === 'data') {
+        if (this._pending.length === 0) return
+        const take = Math.min(this._remaining, this._pending.length)
+        const data = this._pending.subarray(0, take)
+        this._pending = this._pending.subarray(take)
+        this._remaining -= take
+        this.decodedLength += take
+        if (this._chunkHash) this._chunkHash.update(data)
+        this.push(data)
+        if (this._remaining === 0) this._state = 'chunk-end'
+        continue
+      }
+
+      if (this._state === 'chunk-end') {
+        if (this._pending.length < 2) return
+        if (this._pending[0] !== 0x0d || this._pending[1] !== 0x0a) {
+          throw new S3Error('InvalidRequest', 'Malformed aws-chunked framing: missing CRLF after chunk data')
+        }
+        this._pending = this._pending.subarray(2)
+        this._verifyChunk(this._chunkHash ? this._chunkHash.digest('hex') : null)
+        this._state = 'size'
+        continue
+      }
+
+      if (this._state === 'trailer') {
+        const line = this._takeLine()
+        if (line === null) return
+        if (line === '') {
+          this._state = 'done'
+          return
+        }
+        this._consumeTrailerLine(line)
+        continue
+      }
+
+      return
+    }
+  }
+
+  _consumeTrailerLine(line) {
+    if (!line) return
+    const separator = line.indexOf(':')
+    if (separator === -1) {
+      throw new S3Error('InvalidRequest', 'Malformed aws-chunked trailer')
+    }
+    const name = line.slice(0, separator).trim().toLowerCase()
+    const value = line.slice(separator + 1).trim()
+    if (name === 'x-amz-trailer-signature') {
+      this._trailerSignature = value
+      return
+    }
+    this.trailers[name] = value
+    this._trailerBytes += `${name}:${value}\n`
+  }
+
+  _verifyChunk(chunkSha256) {
+    if (!this.signed) return
+    const stringToSign = chunkStringToSign({
+      amzDate: this.amzDate,
+      scope: this.scope,
+      previousSignature: this.previousSignature,
+      chunkSha256,
+    })
+    const expected = calculateSignature(this.signingKey, stringToSign)
+    if (!signaturesMatch(expected, this._chunkSignature)) {
+      throw new S3Error('SignatureDoesNotMatch', 'The chunk signature does not match')
+    }
+    this.previousSignature = expected
+  }
+
+  _verifyTrailerSignature() {
+    if (!this.signed || !this._trailerSignature) return
+    const stringToSign = trailerStringToSign({
+      amzDate: this.amzDate,
+      scope: this.scope,
+      previousSignature: this.previousSignature,
+      trailerSha256: createHash('sha256').update(this._trailerBytes, 'utf8').digest('hex'),
+    })
+    const expected = calculateSignature(this.signingKey, stringToSign)
+    if (!signaturesMatch(expected, this._trailerSignature)) {
+      throw new S3Error('SignatureDoesNotMatch', 'The trailer signature does not match')
+    }
+  }
+}
+
+/**
+ * Encodes a body as `aws-chunked`. Used by the test client to exercise the
+ * decoder the way the aws-cli does.
+ */
+export function encodeChunked(body, { signed = false, seedSignature, signingKey, scope, amzDate, chunkSize = 65536, trailers = null } = {}) {
+  const source = Buffer.isBuffer(body) ? body : Buffer.from(body)
+  const frames = []
+  let previousSignature = seedSignature
+
+  const frame = (data) => {
+    let extension = ''
+    if (signed) {
+      const stringToSign = chunkStringToSign({
+        amzDate,
+        scope,
+        previousSignature,
+        chunkSha256: createHash('sha256').update(data).digest('hex'),
+      })
+      previousSignature = calculateSignature(signingKey, stringToSign)
+      extension = `;chunk-signature=${previousSignature}`
+    }
+    frames.push(Buffer.from(`${data.length.toString(16)}${extension}\r\n`), data, CRLF)
+  }
+
+  for (let offset = 0; offset < source.length; offset += chunkSize) {
+    frame(source.subarray(offset, Math.min(offset + chunkSize, source.length)))
+  }
+
+  // Final zero-length frame.
+  let finalExtension = ''
+  if (signed) {
+    const stringToSign = chunkStringToSign({
+      amzDate, scope, previousSignature, chunkSha256: EMPTY_SHA256,
+    })
+    previousSignature = calculateSignature(signingKey, stringToSign)
+    finalExtension = `;chunk-signature=${previousSignature}`
+  }
+  frames.push(Buffer.from(`0${finalExtension}\r\n`))
+
+  if (trailers) {
+    let trailerBytes = ''
+    for (const [name, value] of Object.entries(trailers)) {
+      frames.push(Buffer.from(`${name}:${value}\r\n`))
+      trailerBytes += `${name}:${value}\n`
+    }
+    if (signed) {
+      const stringToSign = trailerStringToSign({
+        amzDate,
+        scope,
+        previousSignature,
+        trailerSha256: createHash('sha256').update(trailerBytes, 'utf8').digest('hex'),
+      })
+      frames.push(Buffer.from(`x-amz-trailer-signature:${calculateSignature(signingKey, stringToSign)}\r\n`))
+    }
+  }
+
+  frames.push(CRLF)
+  return Buffer.concat(frames)
+}

package/src/auth/credentials.js

@@ -0,0 +1,41 @@
+import { randomBytes } from 'node:crypto'
+
+/**
+ * In-memory credential store.
+ *
+ * SigV4 recomputes an HMAC from the secret, so the secret cannot be stored as a
+ * one-way hash — the store always holds recoverable material and must be
+ * treated accordingly (docs/plan.md section 7).
+ */
+export class CredentialStore {
+  constructor(credentials = []) {
+    this.credentials = new Map()
+    for (const credential of credentials) this.add(credential)
+  }
+
+  add({ accessKeyId, secretAccessKey }) {
+    if (!accessKeyId || !secretAccessKey) {
+      throw new TypeError('A credential requires both accessKeyId and secretAccessKey')
+    }
+    this.credentials.set(accessKeyId, { accessKeyId, secretAccessKey })
+    return this
+  }
+
+  get(accessKeyId) {
+    return this.credentials.get(accessKeyId)
+  }
+
+  get size() {
+    return this.credentials.size
+  }
+
+  /** Bound lookup suitable for passing into `verifyRequest`. */
+  lookup = (accessKeyId) => this.get(accessKeyId)
+}
+
+export function generateCredential() {
+  return {
+    accessKeyId: randomBytes(10).toString('hex').toUpperCase(),
+    secretAccessKey: randomBytes(30).toString('base64url'),
+  }
+}

package/src/auth/sigv4.js

@@ -0,0 +1,293 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
+import { S3Error } from '../errors.js'
+
+export const ALGORITHM = 'AWS4-HMAC-SHA256'
+export const EMPTY_SHA256 = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+
+export const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD'
+export const STREAMING_SIGNED = 'STREAMING-AWS4-HMAC-SHA256-PAYLOAD'
+export const STREAMING_SIGNED_TRAILER = 'STREAMING-AWS4-HMAC-SHA256-PAYLOAD-TRAILER'
+export const STREAMING_UNSIGNED_TRAILER = 'STREAMING-UNSIGNED-PAYLOAD-TRAILER'
+
+export const STREAMING_PAYLOADS = new Set([
+  STREAMING_SIGNED,
+  STREAMING_SIGNED_TRAILER,
+  STREAMING_UNSIGNED_TRAILER,
+])
+
+const MAX_SKEW_MS = 15 * 60 * 1000
+const MAX_PRESIGN_EXPIRY = 7 * 24 * 60 * 60
+
+/**
+ * RFC 3986 percent-encoding. `encodeURIComponent` leaves !'()* alone, which
+ * SigV4 does not — getting this wrong breaks every key containing a space or
+ * an accent (docs/plan.md section 4.5).
+ */
+export function uriEncode(value, encodeSlash = true) {
+  const bytes = Buffer.from(String(value), 'utf8')
+  let out = ''
+  for (const byte of bytes) {
+    const char = String.fromCharCode(byte)
+    if ((byte >= 0x41 && byte <= 0x5a) || (byte >= 0x61 && byte <= 0x7a) ||
+        (byte >= 0x30 && byte <= 0x39) || char === '-' || char === '.' ||
+        char === '_' || char === '~') {
+      out += char
+    } else if (char === '/' && !encodeSlash) {
+      out += char
+    } else {
+      out += `%${byte.toString(16).toUpperCase().padStart(2, '0')}`
+    }
+  }
+  return out
+}
+
+function hmac(key, data) {
+  return createHmac('sha256', key).update(data, 'utf8').digest()
+}
+
+const signingKeyCache = new Map()
+const SIGNING_KEY_CACHE_LIMIT = 512
+
+/**
+ * kSigning = HMAC(HMAC(HMAC(HMAC("AWS4"+secret, date), region), service), "aws4_request").
+ * Only changes daily, so it is cached per (accessKey, date, region, service).
+ */
+export function deriveSigningKey(secretAccessKey, date, region, service = 's3', accessKeyId = '') {
+  // The secret is part of the cache key (via its digest) so that rotating a
+  // secret under the same access key id cannot serve a stale signing key.
+  const secretFingerprint = createHash('sha256').update(secretAccessKey, 'utf8').digest('base64')
+  const cacheKey = `${accessKeyId}/${date}/${region}/${service}/${secretFingerprint}`
+  const cached = signingKeyCache.get(cacheKey)
+  if (cached) return cached
+  const kDate = hmac(`AWS4${secretAccessKey}`, date)
+  const kRegion = hmac(kDate, region)
+  const kService = hmac(kRegion, service)
+  const kSigning = hmac(kService, 'aws4_request')
+  if (signingKeyCache.size >= SIGNING_KEY_CACHE_LIMIT) signingKeyCache.clear()
+  signingKeyCache.set(cacheKey, kSigning)
+  return kSigning
+}
+
+export function normalizeHeaderValue(value) {
+  const raw = Array.isArray(value) ? value.join(',') : String(value ?? '')
+  return raw.trim().replace(/\s+/g, ' ')
+}
+
+/**
+ * Canonical query string: parameters decoded, then re-encoded per RFC 3986 and
+ * sorted by encoded name, then encoded value.
+ */
+export function canonicalQueryString(pairs) {
+  return pairs
+    .map(([name, value]) => [uriEncode(name), uriEncode(value ?? '')])
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0))
+    .map(([name, value]) => `${name}=${value}`)
+    .join('&')
+}
+
+export function buildCanonicalRequest({ method, canonicalUri, queryPairs, headers, signedHeaders, payloadHash }) {
+  const canonicalHeaders = signedHeaders
+    .map((name) => `${name}:${normalizeHeaderValue(headers[name])}\n`)
+    .join('')
+  return [
+    method,
+    canonicalUri || '/',
+    canonicalQueryString(queryPairs),
+    canonicalHeaders,
+    signedHeaders.join(';'),
+    payloadHash,
+  ].join('\n')
+}
+
+export function buildStringToSign({ amzDate, scope, canonicalRequest }) {
+  return [
+    ALGORITHM,
+    amzDate,
+    scope,
+    createHash('sha256').update(canonicalRequest, 'utf8').digest('hex'),
+  ].join('\n')
+}
+
+export function calculateSignature(signingKey, stringToSign) {
+  return createHmac('sha256', signingKey).update(stringToSign, 'utf8').digest('hex')
+}
+
+/**
+ * Per-chunk signature for `aws-chunked` bodies. Each chunk chains off the
+ * previous signature, seeded with the header signature (docs/plan.md 4.1).
+ */
+export function chunkStringToSign({ amzDate, scope, previousSignature, chunkSha256 }) {
+  return [
+    'AWS4-HMAC-SHA256-PAYLOAD',
+    amzDate,
+    scope,
+    previousSignature,
+    EMPTY_SHA256,
+    chunkSha256,
+  ].join('\n')
+}
+
+export function trailerStringToSign({ amzDate, scope, previousSignature, trailerSha256 }) {
+  return [
+    'AWS4-HMAC-SHA256-TRAILER',
+    amzDate,
+    scope,
+    previousSignature,
+    trailerSha256,
+  ].join('\n')
+}
+
+export function signaturesMatch(expected, provided) {
+  if (typeof provided !== 'string' || expected.length !== provided.length) return false
+  return timingSafeEqual(Buffer.from(expected, 'utf8'), Buffer.from(provided, 'utf8'))
+}
+
+/** Parse `YYYYMMDDTHHMMSSZ`. */
+export function parseAmzDate(amzDate) {
+  const match = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(amzDate ?? '')
+  if (!match) return null
+  const [, y, mo, d, h, mi, s] = match
+  return new Date(Date.UTC(+y, +mo - 1, +d, +h, +mi, +s))
+}
+
+function parseCredentialScope(credential) {
+  const parts = String(credential ?? '').split('/')
+  if (parts.length !== 5 || parts[4] !== 'aws4_request') {
+    throw new S3Error('AuthorizationHeaderMalformed', 'Credential should be scoped with a valid terminator')
+  }
+  const [accessKeyId, date, region, service] = parts
+  return { accessKeyId, date, region, service, scope: parts.slice(1).join('/') }
+}
+
+function parseAuthorizationHeader(header) {
+  if (!header.startsWith(`${ALGORITHM} `)) {
+    throw new S3Error('AuthorizationHeaderMalformed', 'Unsupported signature algorithm')
+  }
+  const fields = {}
+  for (const part of header.slice(ALGORITHM.length + 1).split(',')) {
+    const idx = part.indexOf('=')
+    if (idx === -1) continue
+    fields[part.slice(0, idx).trim()] = part.slice(idx + 1).trim()
+  }
+  if (!fields.Credential || !fields.SignedHeaders || !fields.Signature) {
+    throw new S3Error('AuthorizationHeaderMalformed', 'Authorization header is missing required fields')
+  }
+  return {
+    ...parseCredentialScope(fields.Credential),
+    signedHeaders: fields.SignedHeaders.split(';').map((h) => h.toLowerCase()).filter(Boolean),
+    signature: fields.Signature,
+  }
+}
+
+function assertFreshness(requestDate, now, code = 'RequestTimeTooSkewed') {
+  if (!requestDate) throw new S3Error('AuthorizationHeaderMalformed', 'Invalid x-amz-date')
+  if (Math.abs(now - requestDate.getTime()) > MAX_SKEW_MS) {
+    throw new S3Error(code, 'The difference between the request time and the current time is too large')
+  }
+}
+
+/**
+ * Verify a request. `ctx` carries the raw path (already percent-encoded by the
+ * client — reusing it verbatim is what makes the canonical URI match), the raw
+ * query pairs and the lower-cased headers.
+ *
+ * Returns the auth result including the seed signature and scope, which the
+ * chunked decoder needs to validate the body.
+ */
+export function verifyRequest(ctx, { lookupCredential, now = Date.now(), region = 'us-east-1' }) {
+  const headers = ctx.headers
+  const authorization = headers.authorization
+  const presigned = !authorization && ctx.query.get('X-Amz-Signature') !== undefined
+
+  if (!authorization && !presigned) {
+    throw new S3Error('AccessDenied', 'Anonymous access is not supported')
+  }
+
+  let parsed
+  let amzDate
+  let payloadHash
+  let queryPairs = ctx.queryPairs
+
+  if (presigned) {
+    const credential = ctx.query.get('X-Amz-Credential')
+    const signedHeaders = (ctx.query.get('X-Amz-SignedHeaders') ?? '')
+      .split(';').map((h) => h.toLowerCase()).filter(Boolean)
+    parsed = {
+      ...parseCredentialScope(credential),
+      signedHeaders,
+      signature: ctx.query.get('X-Amz-Signature'),
+    }
+    if (ctx.query.get('X-Amz-Algorithm') !== ALGORITHM) {
+      throw new S3Error('AuthorizationHeaderMalformed', 'Unsupported signature algorithm')
+    }
+    amzDate = ctx.query.get('X-Amz-Date')
+    const requestDate = parseAmzDate(amzDate)
+    if (!requestDate) throw new S3Error('AuthorizationHeaderMalformed', 'Invalid X-Amz-Date')
+    const expires = Number.parseInt(ctx.query.get('X-Amz-Expires') ?? '', 10)
+    if (!Number.isInteger(expires) || expires <= 0 || expires > MAX_PRESIGN_EXPIRY) {
+      throw new S3Error('AuthorizationHeaderMalformed', 'X-Amz-Expires must be between 1 and 604800 seconds')
+    }
+    if (now > requestDate.getTime() + expires * 1000) {
+      throw new S3Error('AccessDenied', 'Request has expired')
+    }
+    if (requestDate.getTime() - now > MAX_SKEW_MS) {
+      throw new S3Error('RequestTimeTooSkewed', 'Request is dated too far in the future')
+    }
+    payloadHash = headers['x-amz-content-sha256'] ?? UNSIGNED_PAYLOAD
+    queryPairs = ctx.queryPairs.filter(([name]) => name !== 'X-Amz-Signature')
+  } else {
+    parsed = parseAuthorizationHeader(authorization)
+    amzDate = headers['x-amz-date'] ?? ''
+    assertFreshness(parseAmzDate(amzDate), now)
+    payloadHash = headers['x-amz-content-sha256']
+    if (!payloadHash) {
+      throw new S3Error('InvalidRequest', 'Missing required header x-amz-content-sha256')
+    }
+  }
+
+  if (!parsed.signedHeaders.includes('host')) {
+    throw new S3Error('AuthorizationHeaderMalformed', 'The host header must be signed')
+  }
+  if (parsed.service !== 's3') {
+    throw new S3Error('AuthorizationHeaderMalformed', `Credential should be scoped to service: s3`)
+  }
+
+  const credential = lookupCredential(parsed.accessKeyId)
+  if (!credential) {
+    throw new S3Error('InvalidAccessKeyId', 'The AWS Access Key Id you provided does not exist in our records')
+  }
+
+  const canonicalRequest = buildCanonicalRequest({
+    method: ctx.method,
+    canonicalUri: ctx.rawPath,
+    queryPairs,
+    headers,
+    signedHeaders: parsed.signedHeaders,
+    payloadHash,
+  })
+  const stringToSign = buildStringToSign({ amzDate, scope: parsed.scope, canonicalRequest })
+  const signingKey = deriveSigningKey(
+    credential.secretAccessKey, parsed.date, parsed.region, parsed.service, parsed.accessKeyId,
+  )
+  const expected = calculateSignature(signingKey, stringToSign)
+
+  if (!signaturesMatch(expected, parsed.signature)) {
+    const error = new S3Error('SignatureDoesNotMatch')
+    error.detail.canonicalRequest = canonicalRequest
+    error.detail.stringToSign = stringToSign
+    throw error
+  }
+
+  return {
+    accessKeyId: parsed.accessKeyId,
+    region: parsed.region,
+    scope: parsed.scope,
+    amzDate,
+    payloadHash,
+    presigned,
+    seedSignature: expected,
+    signingKey,
+    canonicalRequest,
+    stringToSign,
+  }
+}

package/src/errors.js

@@ -0,0 +1,65 @@
+/**
+ * S3 error codes. The `<Code>` value drives SDK retry logic, so these strings
+ * are a wire contract — see docs/plan.md section 4.7.
+ */
+
+const CODES = {
+  AccessDenied: [403, 'Access Denied'],
+  AccessForbidden: [403, 'CORSResponse: This CORS request is not allowed'],
+  AuthorizationHeaderMalformed: [400, 'The authorization header is malformed'],
+  BadDigest: [400, 'The Content-MD5 you specified did not match what we received'],
+  BucketAlreadyExists: [409, 'The requested bucket name is not available'],
+  BucketAlreadyOwnedByYou: [409, 'You already own this bucket'],
+  BucketNotEmpty: [409, 'The bucket you tried to delete is not empty'],
+  EntityTooLarge: [400, 'Your proposed upload exceeds the maximum allowed object size'],
+  EntityTooSmall: [400, 'Your proposed upload is smaller than the minimum allowed object size'],
+  IllegalVersioningConfigurationException: [400, 'The versioning configuration specified is invalid'],
+  IncompleteBody: [400, 'You did not provide the number of bytes specified by the Content-Length HTTP header'],
+  InternalError: [500, 'We encountered an internal error. Please try again.'],
+  InvalidAccessKeyId: [403, 'The AWS Access Key Id you provided does not exist in our records'],
+  InvalidArgument: [400, 'Invalid Argument'],
+  InvalidBucketName: [400, 'The specified bucket is not valid'],
+  InvalidDigest: [400, 'The Content-MD5 you specified is not valid'],
+  InvalidPart: [400, 'One or more of the specified parts could not be found'],
+  InvalidPartNumber: [416, 'The requested partnumber is not satisfiable'],
+  InvalidPartOrder: [400, 'The list of parts was not in ascending order'],
+  InvalidRange: [416, 'The requested range is not satisfiable'],
+  InvalidRequest: [400, 'Invalid Request'],
+  InvalidTag: [400, 'The tag provided was not valid'],
+  MalformedPolicy: [400, 'The policy is not in the valid JSON format'],
+  NoSuchBucketPolicy: [404, 'The bucket policy does not exist'],
+  NoSuchCORSConfiguration: [404, 'The CORS configuration does not exist'],
+  NoSuchLifecycleConfiguration: [404, 'The lifecycle configuration does not exist'],
+  NoSuchTagSet: [404, 'The TagSet does not exist'],
+  NoSuchVersion: [404, 'The specified version does not exist'],
+  KeyTooLongError: [400, 'Your key is too long'],
+  MalformedXML: [400, 'The XML you provided was not well-formed or did not validate against our published schema'],
+  MethodNotAllowed: [405, 'The specified method is not allowed against this resource'],
+  MissingContentLength: [411, 'You must provide the Content-Length HTTP header'],
+  NoSuchBucket: [404, 'The specified bucket does not exist'],
+  NoSuchKey: [404, 'The specified key does not exist'],
+  NoSuchUpload: [404, 'The specified multipart upload does not exist'],
+  NotImplemented: [501, 'A header you provided implies functionality that is not implemented'],
+  PreconditionFailed: [412, 'At least one of the pre-conditions you specified did not hold'],
+  RequestTimeTooSkewed: [403, 'The difference between the request time and the current time is too large'],
+  SignatureDoesNotMatch: [403, 'The request signature we calculated does not match the signature you provided'],
+  SlowDown: [503, 'Please reduce your request rate'],
+  XAmzContentSHA256Mismatch: [400, 'The provided x-amz-content-sha256 header does not match what was computed'],
+}
+
+export class S3Error extends Error {
+  constructor(code, message, detail = {}) {
+    const known = CODES[code] ?? [400, code]
+    super(message ?? known[1])
+    this.name = 'S3Error'
+    this.code = code
+    this.statusCode = detail.statusCode ?? known[0]
+    this.detail = detail
+  }
+}
+
+export function isS3Error(err) {
+  return err instanceof S3Error
+}
+
+export { CODES as ERROR_CODES }