sealkeep 0.5.0

package/dist/src/providers/s3.d.ts

@@ -0,0 +1,174 @@
+import { type Credentials } from "./sigv4.js";
+import type { ProviderKind, ProviderUploadClient, UploadLease } from "../control-plane.js";
+export type S3Endpoint = {
+    region: string;
+    bucket: string;
+    /** Which S3-compatible service this is. Decides the default host and addressing style. */
+    provider?: "s3" | "r2" | "b2";
+    /** Set for R2, MinIO, or any non-AWS S3-compatible endpoint. */
+    host?: string;
+    port?: number;
+    protocol?: "https" | "http";
+    pathStyle?: boolean;
+};
+export declare const DEFAULT_PART_BYTES: number;
+export declare const MIN_PART_BYTES: number;
+/**
+ * The checksum S3 stores for a multipart object, computed the way S3 computes it:
+ * SHA-256 over the concatenated raw part digests, base64, then `-<part count>`.
+ *
+ * Worth deriving rather than skipping. A multipart object's stored checksum is
+ * never the whole-object SHA-256, so comparing the two always fails — and the
+ * cheap way out is to skip the check whenever a `-N` suffix appears, which
+ * silently disables verification for exactly the largest archives. Computing it
+ * keeps the comparison real at every size.
+ */
+export declare function compositeChecksum(partChecksumsB64: readonly string[]): string;
+/** One uploaded part as the resume journal records it. `etag` and `checksum` are
+ *  what CompleteMultipartUpload needs back; `bytes` is what makes a short part
+ *  detectable at resume time, when the part bodies themselves are long gone. */
+export type S3StreamPart = {
+    partNumber: number;
+    etag: string;
+    checksum: string;
+    bytes: number;
+};
+/** Everything a crashed stream needs to continue. Journal exactly this shape. */
+export type S3StreamState = {
+    uploadId: string;
+    parts: S3StreamPart[];
+};
+export type S3StreamOptions = {
+    /** State from an earlier run's onState: skips initiation, reuses the parts
+     *  already uploaded, and continues numbering after them. */
+    resume?: S3StreamState;
+    /** Awaited after every completed part upload with the full current state.
+     *  This call is the durability point a resume journal writes at: once it
+     *  returns, a crash can be resumed from that state. */
+    onState?: (state: S3StreamState) => void | Promise<void>;
+};
+/**
+ * The byte position a resumed stream must start feeding from: one full part per
+ * seeded entry, with exactly one exception.
+ *
+ * A short part anywhere but LAST means the journal describes a
+ * differently-shaped upload (or a different part size), and continuing would
+ * splice new bytes at the wrong offset — refused. A short LAST seed is the
+ * one legitimate shape: the object ended there, and the only thing left to do
+ * is complete. `uploadStream` therefore refuses any further data after a short
+ * last seed — bytes cannot follow a tail.
+ */
+export declare function resumeOffsetBytes(parts: readonly S3StreamPart[], partBytes: number): number;
+/** True when the seeds end in a short (object-ending) part: completion-only resume. */
+export declare function seededTailIsFinal(parts: readonly S3StreamPart[], partBytes: number): boolean;
+export declare function xmlValue(body: string, tag: string): string | null;
+export declare function target(endpoint: S3Endpoint, key: string): {
+    host: string;
+    path: string;
+};
+/**
+ * An S3-compatible upload client for S3, R2, and MinIO.
+ *
+ * Requests are presigned locally with credentials this process was handed; no
+ * long-lived credential is ever written to a Sealkeep config file. Only the
+ * checksum header is signed, because `content-length` is a forbidden header for
+ * `fetch` and could not be sent verbatim — the SHA-256 already pins the bytes.
+ */
+export declare class S3UploadClient implements ProviderUploadClient {
+    readonly kind: ProviderKind;
+    private readonly endpoint;
+    private readonly credentials;
+    private readonly partBytes;
+    constructor(kind: ProviderKind, endpoint: S3Endpoint, credentials: Credentials, partBytes?: number, 
+    /** S3 requires every part except the last to be at least 5 MiB. Local emulators and
+     *  MinIO do not, so this is the deliberate opt-out for those targets only. */
+    allowSmallParts?: boolean);
+    private sign;
+    private put;
+    /**
+     * The chunk-folder layout's whole provider API: put one object, ask about
+     * one object, remove one object. A 4 MB sealed chunk has a known length, so
+     * a plain checksummed PUT does everything multipart machinery did — which
+     * is exactly why the chunk layout needs none of it.
+     */
+    putObject(key: string, body: Buffer): Promise<{
+        checksum: string;
+    }>;
+    headObject(key: string): Promise<{
+        exists: boolean;
+        bytes: number;
+        checksum?: string;
+    }>;
+    getObject(key: string): Promise<Buffer>;
+    deleteObject(key: string): Promise<void>;
+    initiateMultipart(key: string): Promise<string>;
+    completeMultipart(key: string, uploadId: string, parts: {
+        partNumber: number;
+        etag: string;
+        checksum: string;
+    }[]): Promise<string>;
+    /**
+     * What the provider ACTUALLY holds for an in-flight multipart — the resume
+     * path's source of truth. A journal can lag the provider by exactly the
+     * parts that landed between a PUT and the journal write that would have
+     * recorded them; ListParts is how a resume sees those, so nothing the
+     * provider holds can be silently overwritten with re-sealed bytes.
+     */
+    listParts(key: string, uploadId: string): Promise<{
+        partNumber: number;
+        etag: string;
+        bytes: number;
+    }[]>;
+    abortMultipart(key: string, uploadId: string): Promise<void>;
+    /** Uploads ciphertext and returns the checksum the provider confirmed. */
+    upload(lease: UploadLease, ciphertext: Buffer): Promise<{
+        remoteChecksum: string;
+        bytes: number;
+    }>;
+    /**
+     * Streams an object up as it is produced: stored chunks accumulate into
+     * multipart parts of `partBytes`, each part uploads as soon as it fills, and
+     * the remainder goes up as the final part. A source that ends before one
+     * part fills becomes a plain single PUT — S3 refuses multiparts under 5 MB
+     * except as the last part, and a one-part multipart is just ceremony.
+     *
+     * Peak memory is one part buffer. On any failure the multipart is aborted so
+     * no half-object lingers as billable invisible parts.
+     *
+     * Resume: `options.resume` seeds the parts of an earlier run and skips
+     * initiation. The caller guarantees the incoming chunks begin at the byte
+     * position right after the seeded parts — it re-seals from a chunk boundary,
+     * so that guarantee only holds when `partBytes` is a multiple of the seal
+     * chunk size, an alignment invisible from here and therefore the caller's
+     * problem. What IS checkable is that the seeded parts imply a part-aligned
+     * offset, so a journal carrying a short non-final part is refused before any
+     * request goes out. `options.onState` is awaited after every completed part
+     * with the full state — the journal's durability point.
+     */
+    uploadStream(key: string, chunks: AsyncIterable<Buffer>, options?: S3StreamOptions): Promise<{
+        remoteChecksum: string;
+        bytes: number;
+    }>;
+    /**
+     * Fetches one object back.
+     *
+     * Managed downloads from an S3-compatible provider cannot be presigned by the
+     * control plane — Spala has no SigV4 signer — so the machine signs its own
+     * GET with the short-lived credential it was vended, exactly as it does for
+     * the upload.
+     */
+    download(lease: UploadLease): Promise<Buffer>;
+    /**
+     * Confirms the object exists remotely and reports what the provider stored.
+     *
+     * `x-amz-checksum-mode: ENABLED` is required before S3 will return a stored
+     * checksum on HEAD at all. Without it the header is simply absent, and a
+     * caller that skips the comparison when the header is missing ends up
+     * verifying nothing but the byte count.
+     */
+    head(lease: UploadLease): Promise<{
+        exists: boolean;
+        bytes: number;
+        checksum?: string;
+    }>;
+}

package/dist/src/providers/s3.js

@@ -0,0 +1,345 @@
+import { createHash } from "node:crypto";
+import { fail } from "../errors.js";
+import { presign } from "./sigv4.js";
+export const DEFAULT_PART_BYTES = 8 * 1024 * 1024;
+export const MIN_PART_BYTES = 5 * 1024 * 1024;
+const sha256b64 = (body) => createHash("sha256").update(body).digest("base64");
+/**
+ * The checksum S3 stores for a multipart object, computed the way S3 computes it:
+ * SHA-256 over the concatenated raw part digests, base64, then `-<part count>`.
+ *
+ * Worth deriving rather than skipping. A multipart object's stored checksum is
+ * never the whole-object SHA-256, so comparing the two always fails — and the
+ * cheap way out is to skip the check whenever a `-N` suffix appears, which
+ * silently disables verification for exactly the largest archives. Computing it
+ * keeps the comparison real at every size.
+ */
+export function compositeChecksum(partChecksumsB64) {
+    const digests = Buffer.concat(partChecksumsB64.map((part) => Buffer.from(part, "base64")));
+    return `${createHash("sha256").update(digests).digest("base64")}-${partChecksumsB64.length}`;
+}
+/**
+ * The byte position a resumed stream must start feeding from: one full part per
+ * seeded entry, with exactly one exception.
+ *
+ * A short part anywhere but LAST means the journal describes a
+ * differently-shaped upload (or a different part size), and continuing would
+ * splice new bytes at the wrong offset — refused. A short LAST seed is the
+ * one legitimate shape: the object ended there, and the only thing left to do
+ * is complete. `uploadStream` therefore refuses any further data after a short
+ * last seed — bytes cannot follow a tail.
+ */
+export function resumeOffsetBytes(parts, partBytes) {
+    let offset = 0;
+    parts.forEach((part, index) => {
+        if (part.bytes !== partBytes && index !== parts.length - 1) {
+            fail("invalid_argument", `Cannot resume this upload: seeded part ${part.partNumber} holds ${part.bytes} bytes, but every part before the final one must hold exactly ${partBytes} bytes for the resume offset to land on a part boundary.`, { partNumber: part.partNumber, partBytes, bytes: part.bytes });
+        }
+        offset += part.bytes;
+    });
+    return offset;
+}
+/** True when the seeds end in a short (object-ending) part: completion-only resume. */
+export function seededTailIsFinal(parts, partBytes) {
+    return parts.length > 0 && parts[parts.length - 1].bytes !== partBytes;
+}
+/** Minimal extraction for the three fields S3 returns in XML. No general XML parsing is required. */
+/**
+ * Where each S3-compatible provider lives when no host is given explicitly.
+ *
+ * B2 and R2 speak S3, so they reuse this client wholesale; only the endpoint
+ * differs. B2 is path-style (`.../bucket/key`) rather than virtual-hosted,
+ * which is why the caller must not assume a bucket-prefixed host.
+ */
+function defaultHost(endpoint) {
+    if (endpoint.provider === "b2")
+        return `s3.${endpoint.region}.backblazeb2.com`;
+    // R2 endpoints are per Cloudflare account, so there is nothing to derive from
+    // bucket and region. Falling through to the AWS host would send a presigned
+    // request — carrying the customer's R2 access key id in X-Amz-Credential — to
+    // Amazon, for a bucket name they do not own. Refuse instead.
+    if (endpoint.provider === "r2")
+        fail("storage_not_configured", "R2 needs its endpoint host: pass --endpoint https://<account-id>.r2.cloudflarestorage.com", { provider: "r2", bucket: endpoint.bucket });
+    return `${endpoint.bucket}.s3.${endpoint.region}.amazonaws.com`;
+}
+export function xmlValue(body, tag) {
+    const match = new RegExp(`<${tag}[^>]*>([^<]*)</${tag}>`).exec(body);
+    return match ? match[1] : null;
+}
+export function target(endpoint, key) {
+    const host = endpoint.host ?? defaultHost(endpoint);
+    const pathStyle = endpoint.pathStyle ?? (endpoint.provider === "b2" || Boolean(endpoint.host));
+    return { host, path: pathStyle ? `/${endpoint.bucket}/${key}` : `/${key}` };
+}
+async function readError(response) {
+    const body = await response.text().catch(() => "");
+    return `${response.status} ${response.statusText}${body ? `: ${xmlValue(body, "Message") ?? body.slice(0, 200)}` : ""}`;
+}
+/**
+ * An S3-compatible upload client for S3, R2, and MinIO.
+ *
+ * Requests are presigned locally with credentials this process was handed; no
+ * long-lived credential is ever written to a Sealkeep config file. Only the
+ * checksum header is signed, because `content-length` is a forbidden header for
+ * `fetch` and could not be sent verbatim — the SHA-256 already pins the bytes.
+ */
+export class S3UploadClient {
+    kind;
+    endpoint;
+    credentials;
+    partBytes;
+    constructor(kind, endpoint, credentials, partBytes = DEFAULT_PART_BYTES, 
+    /** S3 requires every part except the last to be at least 5 MiB. Local emulators and
+     *  MinIO do not, so this is the deliberate opt-out for those targets only. */
+    allowSmallParts = false) {
+        this.kind = kind;
+        this.endpoint = endpoint;
+        this.credentials = credentials;
+        this.partBytes = partBytes;
+        if (partBytes < MIN_PART_BYTES && !allowSmallParts)
+            fail("invalid_argument", `S3 multipart parts must be at least ${MIN_PART_BYTES} bytes`, { partBytes });
+        if (partBytes <= 0)
+            fail("invalid_argument", "partBytes must be positive");
+    }
+    sign(method, key, query, headers = {}, expiresInSeconds = 900) {
+        const { host, path } = target(this.endpoint, key);
+        return presign({ method, host, port: this.endpoint.port, protocol: this.endpoint.protocol, path, region: this.endpoint.region, credentials: this.credentials, query, headers, expiresInSeconds });
+    }
+    async put(key, body, query = {}) {
+        const checksum = sha256b64(body);
+        const { url } = this.sign("PUT", key, query, { "x-amz-checksum-sha256": checksum });
+        const response = await fetch(url, { method: "PUT", body: new Uint8Array(body), headers: { "x-amz-checksum-sha256": checksum } });
+        if (!response.ok)
+            fail("internal", `Upload failed for ${key}: ${await readError(response)}`, { key, status: response.status });
+        return { etag: (response.headers.get("etag") ?? "").replace(/"/g, ""), checksum };
+    }
+    /**
+     * The chunk-folder layout's whole provider API: put one object, ask about
+     * one object, remove one object. A 4 MB sealed chunk has a known length, so
+     * a plain checksummed PUT does everything multipart machinery did — which
+     * is exactly why the chunk layout needs none of it.
+     */
+    async putObject(key, body) {
+        const { checksum } = await this.put(key, body);
+        return { checksum };
+    }
+    async headObject(key) {
+        const { url } = this.sign("HEAD", key, {}, { "x-amz-checksum-mode": "ENABLED" });
+        const response = await fetch(url, { method: "HEAD", headers: { "x-amz-checksum-mode": "ENABLED" } });
+        if (response.status === 404)
+            return { exists: false, bytes: 0 };
+        if (!response.ok)
+            fail("internal", `Could not read ${key}: ${response.status} ${response.statusText}`, { key, status: response.status });
+        return { exists: true, bytes: Number(response.headers.get("content-length") ?? "0"), checksum: response.headers.get("x-amz-checksum-sha256") ?? undefined };
+    }
+    async getObject(key) {
+        const { url } = this.sign("GET", key, {});
+        const response = await fetch(url);
+        if (!response.ok)
+            fail("internal", `Could not download ${key}: ${await readError(response)}`, { key, status: response.status });
+        return Buffer.from(await response.arrayBuffer());
+    }
+    async deleteObject(key) {
+        const { url } = this.sign("DELETE", key, {});
+        const response = await fetch(url, { method: "DELETE" });
+        if (!response.ok && response.status !== 404)
+            fail("internal", `Could not delete ${key}: ${await readError(response)}`, { key, status: response.status });
+    }
+    async initiateMultipart(key) {
+        const { url } = this.sign("POST", key, { uploads: "" });
+        const response = await fetch(url, { method: "POST" });
+        if (!response.ok)
+            fail("internal", `Could not start a multipart upload for ${key}: ${await readError(response)}`, { key });
+        const uploadId = xmlValue(await response.text(), "UploadId");
+        return uploadId ?? fail("internal", `Multipart initiation for ${key} returned no UploadId`, { key });
+    }
+    async completeMultipart(key, uploadId, parts) {
+        const body = Buffer.from(`<CompleteMultipartUpload>${parts.map((part) => `<Part><PartNumber>${part.partNumber}</PartNumber><ETag>"${part.etag}"</ETag><ChecksumSHA256>${part.checksum}</ChecksumSHA256></Part>`).join("")}</CompleteMultipartUpload>`);
+        const { url } = this.sign("POST", key, { uploadId });
+        const response = await fetch(url, { method: "POST", body: new Uint8Array(body) });
+        if (!response.ok)
+            fail("internal", `Could not complete the multipart upload for ${key}: ${await readError(response)}`, { key });
+        const text = await response.text();
+        if (xmlValue(text, "Code"))
+            fail("internal", `Multipart completion for ${key} reported ${xmlValue(text, "Code")}`, { key });
+        return (xmlValue(text, "ETag") ?? "").replace(/&quot;|"/g, "");
+    }
+    /**
+     * What the provider ACTUALLY holds for an in-flight multipart — the resume
+     * path's source of truth. A journal can lag the provider by exactly the
+     * parts that landed between a PUT and the journal write that would have
+     * recorded them; ListParts is how a resume sees those, so nothing the
+     * provider holds can be silently overwritten with re-sealed bytes.
+     */
+    async listParts(key, uploadId) {
+        const { url } = this.sign("GET", key, { uploadId });
+        const response = await fetch(url);
+        if (!response.ok)
+            fail("internal", `Cannot resume this upload: the provider would not list its parts (${await readError(response)})`, { key, uploadId });
+        const text = await response.text();
+        const parts = [];
+        for (const match of text.matchAll(/<Part>([\s\S]*?)<\/Part>/g)) {
+            const block = match[1];
+            const partNumber = Number(xmlValue(block, "PartNumber"));
+            const etag = (xmlValue(block, "ETag") ?? "").replace(/&quot;|"/g, "");
+            const bytes = Number(xmlValue(block, "Size"));
+            if (!Number.isInteger(partNumber) || !Number.isFinite(bytes))
+                continue;
+            parts.push({ partNumber, etag, bytes });
+        }
+        parts.sort((a, b) => a.partNumber - b.partNumber);
+        return parts;
+    }
+    async abortMultipart(key, uploadId) {
+        const { url } = this.sign("DELETE", key, { uploadId });
+        await fetch(url, { method: "DELETE" }).catch(() => undefined);
+    }
+    /** Uploads ciphertext and returns the checksum the provider confirmed. */
+    async upload(lease, ciphertext) {
+        const key = lease.objectKey;
+        if (ciphertext.length <= this.partBytes) {
+            const { checksum } = await this.put(key, ciphertext);
+            return { remoteChecksum: checksum, bytes: ciphertext.length };
+        }
+        const uploadId = await this.initiateMultipart(key);
+        try {
+            const parts = [];
+            for (let offset = 0, partNumber = 1; offset < ciphertext.length; offset += this.partBytes, partNumber += 1) {
+                const slice = ciphertext.subarray(offset, Math.min(offset + this.partBytes, ciphertext.length));
+                const { etag, checksum } = await this.put(key, slice, { partNumber: String(partNumber), uploadId });
+                parts.push({ partNumber, etag, checksum });
+            }
+            await this.completeMultipart(key, uploadId, parts);
+            // The composite, not sha256b64(ciphertext): a multipart object's stored
+            // checksum is derived from the part digests, so the whole-object hash
+            // would never match what `head` reads back.
+            return { remoteChecksum: compositeChecksum(parts.map((part) => part.checksum)), bytes: ciphertext.length };
+        }
+        catch (error) {
+            await this.abortMultipart(key, uploadId);
+            throw error;
+        }
+    }
+    /**
+     * Streams an object up as it is produced: stored chunks accumulate into
+     * multipart parts of `partBytes`, each part uploads as soon as it fills, and
+     * the remainder goes up as the final part. A source that ends before one
+     * part fills becomes a plain single PUT — S3 refuses multiparts under 5 MB
+     * except as the last part, and a one-part multipart is just ceremony.
+     *
+     * Peak memory is one part buffer. On any failure the multipart is aborted so
+     * no half-object lingers as billable invisible parts.
+     *
+     * Resume: `options.resume` seeds the parts of an earlier run and skips
+     * initiation. The caller guarantees the incoming chunks begin at the byte
+     * position right after the seeded parts — it re-seals from a chunk boundary,
+     * so that guarantee only holds when `partBytes` is a multiple of the seal
+     * chunk size, an alignment invisible from here and therefore the caller's
+     * problem. What IS checkable is that the seeded parts imply a part-aligned
+     * offset, so a journal carrying a short non-final part is refused before any
+     * request goes out. `options.onState` is awaited after every completed part
+     * with the full state — the journal's durability point.
+     */
+    async uploadStream(key, chunks, options = {}) {
+        const resume = options.resume;
+        if (resume) {
+            // Refusals happen before the try block on purpose: the catch below
+            // aborts the multipart, and a rejected resume must leave the seeded
+            // parts alive so the caller can correct its journal and try again.
+            resume.parts.forEach((part, index) => {
+                if (part.partNumber !== index + 1) {
+                    fail("invalid_argument", `Cannot resume this upload: the seeded parts must be numbered 1 through ${resume.parts.length} without gaps, but entry ${index + 1} calls itself part ${part.partNumber}.`, { key, uploadId: resume.uploadId });
+                }
+            });
+        }
+        const seededBytes = resume ? resumeOffsetBytes(resume.parts, this.partBytes) : 0;
+        const completionOnly = resume ? seededTailIsFinal(resume.parts, this.partBytes) : false;
+        let uploadId = resume?.uploadId ?? null;
+        let held = [];
+        let heldBytes = 0;
+        // Whole-object accounting: head() reports the object's full length, so a
+        // resumed run counts the seeded bytes as well as what it sends itself.
+        let total = seededBytes;
+        const parts = resume ? resume.parts.map((part) => ({ ...part })) : [];
+        // Snapshots, not the live array: the journal may hold a state across an
+        // await while more parts land, and a shared reference would let a later
+        // push rewrite history the journal already recorded.
+        const journal = async (id) => {
+            if (options.onState)
+                await options.onState({ uploadId: id, parts: parts.map((part) => ({ ...part })) });
+        };
+        try {
+            for await (const chunk of chunks) {
+                if (completionOnly && chunk.length > 0) {
+                    fail("invalid_argument", "Cannot resume this upload with more data: the seeded parts already end in the object's final short part, so the only thing left is completion.", { key });
+                }
+                held.push(chunk);
+                heldBytes += chunk.length;
+                total += chunk.length;
+                while (heldBytes >= this.partBytes) {
+                    const buffered = Buffer.concat(held);
+                    const part = buffered.subarray(0, this.partBytes);
+                    held = part.length < buffered.length ? [buffered.subarray(this.partBytes)] : [];
+                    heldBytes = buffered.length - part.length;
+                    uploadId = uploadId ?? await this.initiateMultipart(key);
+                    const { etag, checksum } = await this.put(key, part, { partNumber: String(parts.length + 1), uploadId });
+                    parts.push({ partNumber: parts.length + 1, etag, checksum, bytes: part.length });
+                    await journal(uploadId);
+                }
+            }
+            const tail = Buffer.concat(held);
+            if (!uploadId) {
+                // The whole object fit inside one part: a single PUT stores it with a
+                // whole-object checksum, exactly like the buffered small-object path.
+                // (Never reached on resume — a seeded uploadId always exists there.)
+                const { checksum } = await this.put(key, tail);
+                return { remoteChecksum: checksum, bytes: total };
+            }
+            if (tail.length > 0 || parts.length === 0) {
+                const { etag, checksum } = await this.put(key, tail, { partNumber: String(parts.length + 1), uploadId });
+                parts.push({ partNumber: parts.length + 1, etag, checksum, bytes: tail.length });
+                await journal(uploadId);
+            }
+            await this.completeMultipart(key, uploadId, parts);
+            return { remoteChecksum: compositeChecksum(parts.map((part) => part.checksum)), bytes: total };
+        }
+        catch (error) {
+            if (uploadId)
+                await this.abortMultipart(key, uploadId);
+            throw error;
+        }
+    }
+    /**
+     * Fetches one object back.
+     *
+     * Managed downloads from an S3-compatible provider cannot be presigned by the
+     * control plane — Spala has no SigV4 signer — so the machine signs its own
+     * GET with the short-lived credential it was vended, exactly as it does for
+     * the upload.
+     */
+    async download(lease) {
+        const { url } = this.sign("GET", lease.objectKey, {});
+        const response = await fetch(url, { method: "GET" });
+        if (!response.ok)
+            fail("internal", `Could not read ${lease.objectKey}: ${await readError(response)}`, { key: lease.objectKey, status: response.status });
+        return Buffer.from(await response.arrayBuffer());
+    }
+    /**
+     * Confirms the object exists remotely and reports what the provider stored.
+     *
+     * `x-amz-checksum-mode: ENABLED` is required before S3 will return a stored
+     * checksum on HEAD at all. Without it the header is simply absent, and a
+     * caller that skips the comparison when the header is missing ends up
+     * verifying nothing but the byte count.
+     */
+    async head(lease) {
+        const mode = { "x-amz-checksum-mode": "ENABLED" };
+        const { url } = this.sign("HEAD", lease.objectKey, {}, mode);
+        const response = await fetch(url, { method: "HEAD", headers: mode });
+        if (response.status === 404)
+            return { exists: false, bytes: 0 };
+        if (!response.ok)
+            fail("internal", `Could not read ${lease.objectKey}: ${response.status} ${response.statusText}`, { key: lease.objectKey, status: response.status });
+        return { exists: true, bytes: Number(response.headers.get("content-length") ?? "0"), checksum: response.headers.get("x-amz-checksum-sha256") ?? undefined };
+    }
+}

package/dist/src/providers/sigv4.d.ts

@@ -0,0 +1,78 @@
+/**
+ * AWS Signature Version 4 for S3-compatible endpoints (S3, R2, MinIO).
+ *
+ * Implemented from the published specification and checked against AWS's own
+ * documented example in `test/sigv4.test.ts`, including the intermediate canonical
+ * request and string-to-sign, so a regression is caught at the step that broke.
+ */
+export declare const ALGORITHM = "AWS4-HMAC-SHA256";
+export declare const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+export type Credentials = {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+};
+/** RFC 3986 unreserved characters stay literal; everything else is percent-encoded. */
+export declare function uriEncode(value: string, encodeSlash?: boolean): string;
+export declare function canonicalUri(path: string): string;
+export declare function canonicalQuery(query: Iterable<[string, string]>): string;
+export declare function canonicalHeaders(headers: Record<string, string>): {
+    canonical: string;
+    signed: string;
+};
+export declare function canonicalRequest(input: {
+    method: string;
+    path: string;
+    query: Iterable<[string, string]>;
+    headers: Record<string, string>;
+    payloadHash: string;
+}): {
+    request: string;
+    signedHeaders: string;
+};
+export declare function credentialScope(date: string, region: string, service: string): string;
+export declare function stringToSign(amzDate: string, scope: string, request: string): string;
+export declare function signingKey(secretAccessKey: string, date: string, region: string, service: string): Buffer;
+export declare function sign(secretAccessKey: string, date: string, region: string, service: string, toSign: string): string;
+/** `20130524T000000Z` and its `20130524` date portion. */
+export declare function amzDates(when: Date): {
+    amzDate: string;
+    date: string;
+};
+export type PresignInput = {
+    method: string;
+    host: string;
+    path: string;
+    region: string;
+    service?: string;
+    credentials: Credentials;
+    expiresInSeconds?: number;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    when?: Date;
+    payloadHash?: string;
+    protocol?: "https" | "http";
+    port?: number;
+};
+export type PresignResult = {
+    url: string;
+    signature: string;
+    canonicalRequest: string;
+    stringToSign: string;
+    signedHeaders: string;
+    expiresAt: string;
+};
+/**
+ * Produces a presigned URL. Host is always signed; any extra header supplied here
+ * is signed too and must be sent verbatim by the uploader or the request is rejected.
+ */
+export declare function presign(input: PresignInput): PresignResult;
+/** Recomputes a presigned signature so a server can verify it. Used by the test emulator. */
+export declare function verifyPresigned(input: {
+    method: string;
+    url: URL;
+    credentials: Credentials;
+    region: string;
+    service?: string;
+    extraHeaders?: Record<string, string>;
+}): boolean;