@3sln/trove 0.0.2

package/packages/core/src/storage/memory.js

@@ -0,0 +1,113 @@
+// In-memory storage backend. The reference implementation and the one tests run
+// against — it exercises the full contract (multipart, ranges) without touching
+// disk or the network. Not for production (everything lives in a Map), but it
+// keeps the higher layers honest.
+
+import { StorageBackend, toBytes, bytesStream, concat, resolveRange } from './interface.js';
+import { TroveError } from '../errors.js';
+
+function etagOf(bytes) {
+  // Cheap non-cryptographic content tag; good enough to detect changes.
+  let h = 2166136261;
+  for (let i = 0; i < bytes.length; i++) {
+    h ^= bytes[i];
+    h = Math.imul(h, 16777619);
+  }
+  return `"${(h >>> 0).toString(16)}-${bytes.length}"`;
+}
+
+export class MemoryStorage extends StorageBackend {
+  constructor() {
+    super();
+    this.objects = new Map(); // key -> { bytes, contentType, etag }
+    this.uploads = new Map(); // uploadId -> { key, contentType, parts: Map<number, bytes> }
+  }
+
+  get capabilities() {
+    return { presignDownload: false, presignUpload: false, multipart: true, range: true, list: true, usage: false };
+  }
+
+  async list({ prefix = '', cursor = null, limit = 1000 } = {}) {
+    // Sorted so the cursor (the last key returned) is a stable resume point.
+    const keys = [...this.objects.keys()].filter((k) => k.startsWith(prefix)).sort();
+    const start = cursor ? keys.findIndex((k) => k > cursor) : 0;
+    const from = start === -1 ? keys.length : start;
+    const page = keys.slice(from, from + limit);
+    return {
+      objects: page.map((key) => {
+        const o = this.objects.get(key);
+        return { key, size: o.bytes.length, etag: o.etag, modifiedAt: o.modifiedAt ?? null };
+      }),
+      nextCursor: from + limit < keys.length ? page[page.length - 1] : null,
+    };
+  }
+
+  async put(key, body, opts = {}) {
+    const bytes = await toBytes(body);
+    if (opts.signal?.aborted) throw TroveError.aborted();
+    const rec = { bytes, contentType: opts.contentType, etag: etagOf(bytes), modifiedAt: Date.now() };
+    this.objects.set(key, rec);
+    opts.onProgress?.(bytes.length);
+    return { size: bytes.length, contentType: rec.contentType, etag: rec.etag };
+  }
+
+  async head(key) {
+    const rec = this.objects.get(key);
+    if (!rec) throw TroveError.notFound('Object');
+    return { size: rec.bytes.length, contentType: rec.contentType, etag: rec.etag };
+  }
+
+  async get(key, opts = {}) {
+    const rec = this.objects.get(key);
+    if (!rec) throw TroveError.notFound('Object');
+    const total = rec.bytes.length;
+    const range = resolveRange(opts.range, total);
+    return {
+      stream: bytesStream(rec.bytes, range && { start: range.start, end: range.end }),
+      size: range ? range.end - range.start + 1 : total,
+      contentType: rec.contentType,
+      etag: rec.etag,
+      range,
+    };
+  }
+
+  async delete(key) {
+    this.objects.delete(key);
+  }
+
+  // --- multipart (direct part upload) ---------------------------------------
+
+  async createMultipart(key, opts = {}) {
+    const uploadId = `mem-${Math.random().toString(36).slice(2)}`;
+    this.uploads.set(uploadId, { key, contentType: opts.contentType, parts: new Map() });
+    return uploadId;
+  }
+
+  async putPart(key, uploadId, partNumber, body) {
+    const up = this.uploads.get(uploadId);
+    if (!up) throw TroveError.notFound('Upload');
+    const bytes = await toBytes(body);
+    up.parts.set(partNumber, bytes);
+    return { partNumber, etag: etagOf(bytes) };
+  }
+
+  async completeMultipart(key, uploadId, parts) {
+    const up = this.uploads.get(uploadId);
+    if (!up) throw TroveError.notFound('Upload');
+    const ordered = [...parts].sort((a, b) => a.partNumber - b.partNumber);
+    const chunks = ordered.map((p) => {
+      const b = up.parts.get(p.partNumber);
+      if (!b) throw TroveError.invalid(`Missing part ${p.partNumber}`);
+      return b;
+    });
+    const bytes = concat(chunks);
+    const rec = { bytes, contentType: up.contentType, etag: etagOf(bytes), modifiedAt: Date.now() };
+    this.objects.set(key, rec);
+    this.uploads.delete(uploadId);
+    return { size: bytes.length, etag: rec.etag };
+  }
+
+  async abortMultipart(key, uploadId) {
+    this.uploads.delete(uploadId);
+  }
+}

package/packages/core/src/storage/prefixed.js

@@ -0,0 +1,75 @@
+// PrefixedStorage — wraps any StorageBackend and namespaces every key under a
+// prefix. This is what lets many collections share one bucket ("bucket + prefix"):
+// each collection gets its own PrefixedStorage over the same underlying S3/FS
+// backend, isolated by key prefix, with zero changes to the backend itself.
+
+import { StorageBackend } from './interface.js';
+
+export class PrefixedStorage extends StorageBackend {
+  /** @param {StorageBackend} inner @param {string} prefix e.g. "team-a/" */
+  constructor(inner, prefix) {
+    super();
+    this.inner = inner;
+    this.prefix = prefix ? prefix.replace(/^\/+|\/+$/g, '') + '/' : '';
+  }
+  #k(key) {
+    return this.prefix + key;
+  }
+  #strip(key) {
+    return this.prefix && key.startsWith(this.prefix) ? key.slice(this.prefix.length) : key;
+  }
+  get capabilities() {
+    return this.inner.capabilities;
+  }
+  /**
+   * Free space is a property of the VOLUME, not the prefix, so it passes straight
+   * through. Forwarding `capabilities.usage: true` without forwarding this left the
+   * client told the backend could answer and then handed `null` every time — so the
+   * status bar's meter never appeared and the "running out of storage" issue, whose
+   * whole point is to warn before writes start failing, could never be raised for a
+   * prefixed collection.
+   */
+  usage(opts) {
+    return this.inner.usage(opts);
+  }
+  async list(opts = {}) {
+    // The prefix is this wrapper's whole job, so listing has to add it on the way in
+    // and strip it on the way out — a caller must never see the wrapper's own prefix
+    // and try to store it as a key.
+    const res = await this.inner.list({ ...opts, prefix: this.#k(opts.prefix || '') });
+    return { ...res, objects: res.objects.map((o) => ({ ...o, key: this.#strip(o.key) })) };
+  }
+  put(key, body, opts) {
+    return this.inner.put(this.#k(key), body, opts);
+  }
+  get(key, opts) {
+    return this.inner.get(this.#k(key), opts);
+  }
+  head(key) {
+    return this.inner.head(this.#k(key));
+  }
+  delete(key, opts) {
+    return this.inner.delete(this.#k(key), opts);
+  }
+  presignGet(key, opts) {
+    return this.inner.presignGet(this.#k(key), opts);
+  }
+  presignPut(key, opts) {
+    return this.inner.presignPut(this.#k(key), opts);
+  }
+  createMultipart(key, opts) {
+    return this.inner.createMultipart(this.#k(key), opts);
+  }
+  presignPart(key, uploadId, partNumber, opts) {
+    return this.inner.presignPart(this.#k(key), uploadId, partNumber, opts);
+  }
+  putPart(key, uploadId, partNumber, body, opts) {
+    return this.inner.putPart(this.#k(key), uploadId, partNumber, body, opts);
+  }
+  completeMultipart(key, uploadId, parts, opts) {
+    return this.inner.completeMultipart(this.#k(key), uploadId, parts, opts);
+  }
+  abortMultipart(key, uploadId, opts) {
+    return this.inner.abortMultipart(this.#k(key), uploadId, opts);
+  }
+}

package/packages/core/src/storage/s3.js

@@ -0,0 +1,316 @@
+// S3-compatible storage backend (AWS S3, Cloudflare R2, MinIO, Backblaze B2…).
+// Uses fetch + our Web-Crypto SigV4 signer, so it works on any modern runtime
+// including Cloudflare Workers. The headline capability is presigning: clients
+// upload and download large objects straight to/from S3, never proxied through
+// the Trove server.
+//
+// Path-style vs virtual-host addressing is configurable (`forcePathStyle`);
+// MinIO/R2-with-custom-domain want path style, real AWS wants virtual host.
+
+import { StorageBackend, toBytes } from './interface.js';
+import { presignUrl, signRequest, sha256Hex, uriEncode } from './s3sigv4.js';
+import { TroveError, wrapError } from '../errors.js';
+import { withRetry } from '../retry.js';
+
+export class S3Storage extends StorageBackend {
+  /**
+   * @param {object} cfg
+   * @param {string} cfg.bucket
+   * @param {string} cfg.region
+   * @param {string} cfg.accessKeyId
+   * @param {string} cfg.secretAccessKey
+   * @param {string} [cfg.sessionToken]
+   * @param {string} [cfg.endpoint]  e.g. https://<acct>.r2.cloudflarestorage.com (defaults to AWS)
+   * @param {boolean} [cfg.forcePathStyle]
+   * @param {number} [cfg.presignExpiry] default seconds for signed URLs
+   */
+  constructor(cfg) {
+    super();
+    for (const k of ['bucket', 'region', 'accessKeyId', 'secretAccessKey']) {
+      if (!cfg?.[k]) throw TroveError.invalid(`S3Storage requires "${k}"`);
+    }
+    this.cfg = cfg;
+    this.creds = {
+      accessKeyId: cfg.accessKeyId,
+      secretAccessKey: cfg.secretAccessKey,
+      sessionToken: cfg.sessionToken,
+      region: cfg.region,
+      service: 's3',
+    };
+    this.presignExpiry = cfg.presignExpiry ?? 900;
+    const host = cfg.endpoint
+      ? cfg.endpoint.replace(/\/$/, '')
+      : `https://s3.${cfg.region}.amazonaws.com`;
+    this.forcePathStyle = cfg.forcePathStyle ?? !!cfg.endpoint;
+    this.base = this.forcePathStyle ? `${host}/${cfg.bucket}` : insertBucket(host, cfg.bucket);
+  }
+
+  get capabilities() {
+    return { presignDownload: true, presignUpload: true, multipart: true, range: true, list: true, usage: false };
+  }
+
+  /**
+   * The object's URL, encoded the way SigV4 will canonicalize it.
+   *
+   * `uriEncode`, not `encodeURIComponent`/`URLSearchParams`: the signature is computed
+   * over this exact string, so anything that encodes differently here than the signer
+   * does there produces a URL we send one way and sign another — a 403 from S3 for any
+   * key or parameter containing a space, a `+`, a `!`, or a non-ASCII character.
+   */
+  #url(key, query) {
+    const u = new URL(`${this.base}/${uriEncode(key, false)}`);
+    if (query) {
+      u.search = Object.entries(query)
+        .map(([k, v]) => `${uriEncode(k)}=${uriEncode(v)}`)
+        .join('&');
+    }
+    return u.toString();
+  }
+
+  async #send(method, key, { query, headers, body, signal } = {}) {
+    return withRetry(
+      async () => {
+        const url = this.#url(key, query);
+        const payloadHash = body ? await sha256Hex(body) : await sha256Hex('');
+        const signed = await signRequest(this.creds, { method, url, headers, body, payloadHash });
+        let res;
+        try {
+          res = await fetch(url, { method, headers: signed, body, signal });
+        } catch (err) {
+          throw wrapError(err);
+        }
+        if (!res.ok && res.status >= 500) {
+          throw TroveError.transient(`S3 ${method} ${res.status}`, { details: { status: res.status } });
+        }
+        if (res.status === 429 || res.status === 503) {
+          throw TroveError.transient('S3 throttled', { details: { status: res.status } });
+        }
+        return res;
+      },
+      { signal },
+    );
+  }
+
+  async put(key, body, opts = {}) {
+    const bytes = await toBytes(body);
+    const res = await this.#send('PUT', key, {
+      body: bytes,
+      headers: opts.contentType ? { 'content-type': opts.contentType } : {},
+      signal: opts.signal,
+    });
+    if (!res.ok) throw await s3Error(res, 'put');
+    opts.onProgress?.(bytes.length);
+    return { size: bytes.length, contentType: opts.contentType, etag: res.headers.get('etag') || undefined };
+  }
+
+  async head(key) {
+    const res = await this.#send('HEAD', key);
+    if (res.status === 404) throw TroveError.notFound('Object');
+    if (!res.ok) throw await s3Error(res, 'head');
+    return {
+      size: Number(res.headers.get('content-length') || 0),
+      contentType: res.headers.get('content-type') || undefined,
+      etag: res.headers.get('etag') || undefined,
+    };
+  }
+
+  async get(key, opts = {}) {
+    const headers = {};
+    if (opts.range) {
+      // S3 understands the suffix form natively, so pass it through rather than
+      // resolving it here — we'd need a HEAD to learn the total first. Except `-0`,
+      // which S3 answers with the entire object under a 200 where every other backend
+      // calls it unsatisfiable.
+      if (opts.range.suffix != null) {
+        if (!(opts.range.suffix > 0)) throw TroveError.badRange('Range not satisfiable');
+        headers.range = `bytes=-${opts.range.suffix}`;
+      } else headers.range = `bytes=${opts.range.start ?? 0}-${opts.range.end != null ? opts.range.end : ''}`;
+    }
+    const res = await this.#send('GET', key, { headers, signal: opts.signal });
+    if (res.status === 404) throw TroveError.notFound('Object');
+    // 416 is a real answer, not an internal error: a media player seeking past the end
+    // of a file got "Internal error" on S3 and a 400 everywhere else.
+    if (res.status === 416) throw TroveError.badRange('Range not satisfiable');
+    if (!res.ok && res.status !== 206) throw await s3Error(res, 'get');
+    let range;
+    const cr = res.headers.get('content-range'); // bytes start-end/total
+    if (cr) {
+      const m = /bytes (\d+)-(\d+)\/(\d+)/.exec(cr);
+      if (m) range = { start: +m[1], end: +m[2], total: +m[3] };
+    }
+    return {
+      stream: res.body,
+      size: Number(res.headers.get('content-length') || 0),
+      contentType: res.headers.get('content-type') || undefined,
+      etag: res.headers.get('etag') || undefined,
+      range,
+    };
+  }
+
+  async delete(key, opts = {}) {
+    const res = await this.#send('DELETE', key, { signal: opts.signal });
+    if (!res.ok && res.status !== 404) throw await s3Error(res, 'delete');
+  }
+
+  /**
+   * ListObjectsV2 — how a scan sees objects that reached the bucket without us.
+   *
+   * The bucket is shared infrastructure: another tool, another person, or a lifecycle
+   * rule can add and remove objects, and this is the only way to find out. Paged on S3's
+   * own continuation token rather than a key offset, because that is what the service
+   * guarantees is stable across a page boundary.
+   */
+  async list({ prefix = '', cursor = null, limit = 1000, signal } = {}) {
+    const query = { 'list-type': '2', 'max-keys': String(Math.min(limit, 1000)) };
+    if (prefix) query.prefix = prefix;
+    if (cursor) query['continuation-token'] = cursor;
+    // Bucket-level operation: the key is empty, the bucket is in the base URL.
+    const res = await this.#send('GET', '', { query, signal });
+    if (!res.ok) throw await s3Error(res, 'list');
+    const xml = await res.text();
+    const objects = [];
+    for (const entry of tagAll(xml, 'Contents')) {
+      const key = tag(entry, 'Key');
+      if (key == null) continue;
+      const modified = Date.parse(tag(entry, 'LastModified') || '');
+      objects.push({
+        key: decodeXml(key),
+        size: Number(tag(entry, 'Size') || 0),
+        // decodeXml here too. S3 wraps an ETag in quotes and then XML-escapes them, so
+        // the raw text is `&quot;d16f…&quot;` while `head()` reports `"d16f…"`. The
+        // scanner's normalizeEtag strips a real quote but not the entity, so the first
+        // scan of any S3 collection called every object changed, re-read and re-embedded
+        // the whole drive, and persisted the escaped form — after which every later
+        // upload flipped it back and triggered the same spurious refresh again.
+        etag: decodeXml(tag(entry, 'ETag') || '') || undefined,
+        modifiedAt: Number.isNaN(modified) ? null : modified,
+      });
+    }
+    // Truncated is authoritative: an empty page can still have more behind it.
+    const truncated = tag(xml, 'IsTruncated') === 'true';
+    return { objects, nextCursor: truncated ? tag(xml, 'NextContinuationToken') : null };
+  }
+
+  // --- presigning ------------------------------------------------------------
+
+  async presignGet(key, opts = {}) {
+    const query = {};
+    if (opts.downloadName) {
+      query['response-content-disposition'] = `attachment; filename="${sanitizeFilename(opts.downloadName)}"`;
+    }
+    if (opts.responseContentType) query['response-content-type'] = opts.responseContentType;
+    return presignUrl(this.creds, {
+      method: 'GET',
+      url: this.#url(key),
+      expiresIn: opts.expiresIn ?? this.presignExpiry,
+      query,
+    });
+  }
+
+  async presignPut(key, opts = {}) {
+    return presignUrl(this.creds, {
+      method: 'PUT',
+      url: this.#url(key),
+      expiresIn: opts.expiresIn ?? this.presignExpiry,
+    });
+  }
+
+  // --- multipart -------------------------------------------------------------
+
+  async createMultipart(key, opts = {}) {
+    const res = await this.#send('POST', key, {
+      query: { uploads: '' },
+      headers: opts.contentType ? { 'content-type': opts.contentType } : {},
+    });
+    if (!res.ok) throw await s3Error(res, 'createMultipart');
+    const xml = await res.text();
+    const id = tag(xml, 'UploadId');
+    if (!id) throw TroveError.internal('S3 did not return an UploadId');
+    return id;
+  }
+
+  async presignPart(key, uploadId, partNumber, opts = {}) {
+    return presignUrl(this.creds, {
+      method: 'PUT',
+      url: this.#url(key),
+      expiresIn: opts.expiresIn ?? this.presignExpiry,
+      query: { partNumber: String(partNumber), uploadId },
+    });
+  }
+
+  async putPart(key, uploadId, partNumber, body, opts = {}) {
+    const res = await this.#send('PUT', key, {
+      query: { partNumber: String(partNumber), uploadId },
+      body: await toBytes(body),
+      signal: opts.signal,
+    });
+    if (!res.ok) throw await s3Error(res, 'putPart');
+    const etag = res.headers.get('etag');
+    return { partNumber, etag };
+  }
+
+  async completeMultipart(key, uploadId, parts) {
+    const ordered = [...parts].sort((a, b) => a.partNumber - b.partNumber);
+    const body =
+      `<CompleteMultipartUpload>` +
+      ordered
+        .map((p) => `<Part><PartNumber>${p.partNumber}</PartNumber><ETag>${p.etag}</ETag></Part>`)
+        .join('') +
+      `</CompleteMultipartUpload>`;
+    const res = await this.#send('POST', key, { query: { uploadId }, body, headers: { 'content-type': 'application/xml' } });
+    if (!res.ok) throw await s3Error(res, 'completeMultipart');
+    const xml = await res.text();
+    // S3 can return a 200 with an error body — check for that.
+    if (xml.includes('<Error>')) throw TroveError.transient('S3 completeMultipart failed', { details: { xml } });
+    return { etag: tag(xml, 'ETag') || undefined };
+  }
+
+  async abortMultipart(key, uploadId) {
+    const res = await this.#send('DELETE', key, { query: { uploadId } });
+    if (!res.ok && res.status !== 404) throw await s3Error(res, 'abortMultipart');
+  }
+}
+
+function insertBucket(host, bucket) {
+  const u = new URL(host);
+  u.host = `${bucket}.${u.host}`;
+  return u.toString().replace(/\/$/, '');
+}
+
+function tag(xml, name) {
+  const m = new RegExp(`<${name}>([\\s\\S]*?)</${name}>`).exec(xml);
+  return m ? m[1] : null;
+}
+
+/** Every occurrence of a repeated element (ListObjectsV2 returns one <Contents> per object). */
+function tagAll(xml, name) {
+  const out = [];
+  const re = new RegExp(`<${name}>([\\s\\S]*?)</${name}>`, 'g');
+  let m;
+  while ((m = re.exec(xml))) out.push(m[1]);
+  return out;
+}
+
+/** S3 XML-escapes keys; a key with & or < in it comes back encoded. */
+function decodeXml(s) {
+  return String(s)
+    .replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+function sanitizeFilename(name) {
+  return String(name).replace(/[\r\n"\\]/g, '_');
+}
+
+async function s3Error(res, op) {
+  let body = '';
+  try {
+    body = await res.text();
+  } catch { /* ignore */ }
+  const code = tag(body, 'Code');
+  const msg = tag(body, 'Message') || res.statusText;
+  if (res.status === 403) return new TroveError('forbidden', `S3 ${op}: ${msg}`, { details: { code } });
+  if (res.status === 404) return TroveError.notFound('Object');
+  return TroveError.internal(`S3 ${op} failed (${res.status}): ${msg}`, { details: { code } });
+}

package/packages/core/src/storage/s3sigv4.js

@@ -0,0 +1,185 @@
+// A compact AWS Signature V4 implementation built on Web Crypto (crypto.subtle),
+// so it runs unchanged on Node ≥20, Bun, Deno, and Cloudflare Workers — no
+// aws-sdk, no Node crypto. Supports both signed requests (Authorization header)
+// and presigned URLs (query-string signing), which is what lets clients GET/PUT
+// large objects straight from S3 without proxying through our server.
+//
+// Scope: exactly what an S3-compatible object store needs (S3, MinIO, R2, B2…).
+
+const enc = new TextEncoder();
+
+async function sha256Hex(data) {
+  const buf = await crypto.subtle.digest('SHA-256', typeof data === 'string' ? enc.encode(data) : data);
+  return hex(buf);
+}
+
+async function hmac(key, data) {
+  const k = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  return new Uint8Array(await crypto.subtle.sign('HMAC', k, enc.encode(data)));
+}
+
+function hex(buf) {
+  const b = new Uint8Array(buf);
+  let s = '';
+  for (let i = 0; i < b.length; i++) s += b[i].toString(16).padStart(2, '0');
+  return s;
+}
+
+/**
+ * RFC 3986 encoding — the `UriEncode()` SigV4 specifies. Deliberately stricter than
+ * `encodeURIComponent`, which leaves `!'()*` literal; S3 percent-encodes those when it
+ * recomputes the canonical request, so a URL built with encodeURIComponent gets signed
+ * one way and verified another.
+ *
+ * @param {string} str
+ * @param {boolean} [encodeSlash] false for a path (slashes are separators, not data)
+ */
+export function uriEncode(str, encodeSlash = true) {
+  let out = '';
+  for (const ch of String(str)) {
+    if (/[A-Za-z0-9\-._~]/.test(ch)) out += ch;
+    else if (ch === '/' && !encodeSlash) out += ch;
+    else {
+      for (const byte of enc.encode(ch)) out += '%' + byte.toString(16).toUpperCase().padStart(2, '0');
+    }
+  }
+  return out;
+}
+
+function amzDate(d = new Date()) {
+  const iso = d.toISOString().replace(/[:-]|\.\d{3}/g, '');
+  return { amz: iso, date: iso.slice(0, 8) };
+}
+
+async function signingKey(secret, date, region, service) {
+  const kDate = await hmac(enc.encode('AWS4' + secret), date);
+  const kRegion = await hmac(kDate, region);
+  const kService = await hmac(kRegion, service);
+  return hmac(kService, 'aws4_request');
+}
+
+/**
+ * @typedef {object} S3Creds
+ * @property {string} accessKeyId
+ * @property {string} secretAccessKey
+ * @property {string} region
+ * @property {string} [sessionToken]
+ * @property {string} service   usually 's3'
+ */
+
+/**
+ * Build a presigned URL.
+ * @param {S3Creds} creds
+ * @param {object} o
+ * @param {string} o.method  GET|PUT|POST|DELETE
+ * @param {string} o.url     full endpoint URL for the object (incl. host + path)
+ * @param {number} [o.expiresIn] seconds (default 900, max 604800)
+ * @param {Record<string,string>} [o.query] extra query params (e.g. partNumber, uploadId, response-content-disposition)
+ * @param {Record<string,string>} [o.signedHeaders] headers to bind (host is always bound)
+ */
+export async function presignUrl(creds, o) {
+  const url = new URL(o.url);
+  const { amz, date } = amzDate();
+  const expiresIn = Math.min(o.expiresIn ?? 900, 604800);
+  const scope = `${date}/${creds.region}/${creds.service}/aws4_request`;
+
+  const headers = { host: url.host, ...(o.signedHeaders || {}) };
+  const signedHeaderNames = Object.keys(headers)
+    .map((h) => h.toLowerCase())
+    .sort();
+  const canonicalHeaders = signedHeaderNames.map((h) => `${h}:${String(headers[h]).trim()}\n`).join('');
+  const signedHeaders = signedHeaderNames.join(';');
+
+  const q = new URLSearchParams(url.search);
+  for (const [k, v] of Object.entries(o.query || {})) q.set(k, v);
+  q.set('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+  q.set('X-Amz-Credential', `${creds.accessKeyId}/${scope}`);
+  q.set('X-Amz-Date', amz);
+  q.set('X-Amz-Expires', String(expiresIn));
+  if (creds.sessionToken) q.set('X-Amz-Security-Token', creds.sessionToken);
+  q.set('X-Amz-SignedHeaders', signedHeaders);
+
+  // Canonical query string: sorted, RFC3986-encoded.
+  const canonicalQuery = [...q.entries()]
+    .map(([k, v]) => [uriEncode(k), uriEncode(v)])
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : 1))
+    .map(([k, v]) => `${k}=${v}`)
+    .join('&');
+
+  const canonicalRequest = [
+    o.method,
+    // The path VERBATIM. `url.pathname` is already percent-encoded, and S3 (alone among
+    // AWS services) single-encodes the canonical URI — re-encoding here would turn the
+    // %20 we send into the %2520 we sign, and every key with a space in it would come
+    // back 403 SignatureDoesNotMatch. Callers must therefore hand us a URL whose path
+    // was built with `uriEncode`, not `encodeURIComponent`.
+    url.pathname,
+    canonicalQuery,
+    canonicalHeaders,
+    signedHeaders,
+    'UNSIGNED-PAYLOAD',
+  ].join('\n');
+
+  const stringToSign = [
+    'AWS4-HMAC-SHA256',
+    amz,
+    scope,
+    await sha256Hex(canonicalRequest),
+  ].join('\n');
+
+  const key = await signingKey(creds.secretAccessKey, date, creds.region, creds.service);
+  const signature = hex(await hmac(key, stringToSign));
+
+  url.search = canonicalQuery + `&X-Amz-Signature=${signature}`;
+  return url.toString();
+}
+
+/**
+ * Sign a request with an Authorization header (for server-side S3 calls).
+ * @returns {Promise<Record<string,string>>} headers to send.
+ */
+export async function signRequest(creds, o) {
+  const url = new URL(o.url);
+  const { amz, date } = amzDate();
+  const scope = `${date}/${creds.region}/${creds.service}/aws4_request`;
+  const payloadHash = o.payloadHash || (await sha256Hex(o.body ?? ''));
+
+  const headers = {
+    host: url.host,
+    'x-amz-content-sha256': payloadHash,
+    'x-amz-date': amz,
+    ...(creds.sessionToken ? { 'x-amz-security-token': creds.sessionToken } : {}),
+    ...(o.headers || {}),
+  };
+  const names = Object.keys(headers)
+    .map((h) => h.toLowerCase())
+    .sort();
+  const canonicalHeaders = names.map((h) => `${h}:${String(headers[h]).trim()}\n`).join('');
+  const signedHeaders = names.join(';');
+
+  const canonicalQuery = [...url.searchParams.entries()]
+    .map(([k, v]) => [uriEncode(k), uriEncode(v)])
+    .sort((a, b) => (a[0] < b[0] ? -1 : 1))
+    .map(([k, v]) => `${k}=${v}`)
+    .join('&');
+
+  const canonicalRequest = [
+    o.method,
+    url.pathname, // verbatim — see the note in presignUrl
+    canonicalQuery,
+    canonicalHeaders,
+    signedHeaders,
+    payloadHash,
+  ].join('\n');
+
+  const stringToSign = ['AWS4-HMAC-SHA256', amz, scope, await sha256Hex(canonicalRequest)].join('\n');
+  const key = await signingKey(creds.secretAccessKey, date, creds.region, creds.service);
+  const signature = hex(await hmac(key, stringToSign));
+
+  return {
+    ...headers,
+    Authorization: `AWS4-HMAC-SHA256 Credential=${creds.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+  };
+}
+
+export { sha256Hex };