@crewhaus/tool-objectstore 0.7.0

package/dist/lib/encode.js

@@ -0,0 +1,106 @@
+/**
+ * Percent-encoding, SigV4's way — which is not `encodeURIComponent`'s way.
+ *
+ * This is the module that decides whether a signature verifies, and it is the
+ * one place in the package where being nearly right is worse than being
+ * obviously wrong: a mis-encoded byte produces a well-formed URL that 403s
+ * with `SignatureDoesNotMatch` and no indication of which character
+ * disagreed, at whatever hour the URL is eventually used.
+ *
+ * `encodeURIComponent` is the trap. It leaves `!`, `'`, `(`, `)` and `*`
+ * unencoded; AWS's canonical form encodes all five. So a key like
+ * `q&a (2026)/notes!.txt` signs one way and is requested another. It also
+ * lowercases nothing and uppercases nothing — it happens to emit uppercase
+ * hex, which is right — but the unreserved set is the part that differs, and
+ * that difference is silent.
+ *
+ * The rule, from RFC 3986 §2.3 as SigV4 cites it: `A-Z a-z 0-9 - _ . ~` pass
+ * through unchanged; every other byte of the UTF-8 encoding becomes `%XX`
+ * with UPPERCASE hex digits. No exceptions, no locale, no normalization.
+ */
+const UTF8 = new TextEncoder();
+/**
+ * The unreserved set as a byte table. A table rather than a regex because the
+ * question is asked per BYTE of the UTF-8 encoding, not per character — `é`
+ * is two bytes and neither of them is unreserved, and a regex over characters
+ * invites exactly the reasoning error that lets a non-ASCII key through
+ * half-encoded.
+ */
+const UNRESERVED = (() => {
+    const table = new Array(128).fill(false);
+    const mark = (from, to) => {
+        for (let c = from.charCodeAt(0); c <= to.charCodeAt(0); c++)
+            table[c] = true;
+    };
+    mark("A", "Z");
+    mark("a", "z");
+    mark("0", "9");
+    for (const ch of "-_.~")
+        table[ch.charCodeAt(0)] = true;
+    return table;
+})();
+const HEX = "0123456789ABCDEF";
+/**
+ * Percent-encode one component the way SigV4 requires.
+ *
+ * Every byte outside the unreserved set is encoded, `/` included — this is
+ * the function for query names, query values and single path SEGMENTS. Use
+ * {@link encodePath} for a whole object key, which keeps `/` as a separator.
+ */
+export function encodeRfc3986(value) {
+    let out = "";
+    for (const byte of UTF8.encode(value)) {
+        if (byte < 0x80 && UNRESERVED[byte] === true) {
+            out += String.fromCharCode(byte);
+        }
+        else {
+            out += `%${HEX[byte >> 4]}${HEX[byte & 0x0f]}`;
+        }
+    }
+    return out;
+}
+/**
+ * Percent-encode an object key as a canonical URI path: each segment encoded,
+ * the `/` separators left alone.
+ *
+ * S3 encodes the path ONCE. Every other AWS service encodes the canonical URI
+ * twice (the literal `%` of an already-encoded byte is itself encoded), which
+ * is why `doubleEncode` exists here rather than being assumed away: this
+ * module is the shared SigV4 primitive for the monorepo, and the next caller
+ * will not be S3. Getting it backwards for S3 turns `a b.txt` into
+ * `a%2520b.txt` — a signature over a path nobody will ever request.
+ */
+export function encodePath(path, options) {
+    const once = path.split("/").map(encodeRfc3986).join("/");
+    return options?.doubleEncode === true ? once.split("/").map(encodeRfc3986).join("/") : once;
+}
+/**
+ * Build the canonical query string: encode first, then sort by byte order.
+ *
+ * The order matters and the order of the two OPERATIONS matters more. Sorting
+ * raw names and then encoding them gives a different sequence than encoding
+ * and then sorting, because encoding moves characters around the ASCII table
+ * (`~` is 0x7E raw, `%7E`-shaped forms sort near `%`). AWS specifies
+ * encode-then-sort, so that is what happens here.
+ *
+ * After encoding every byte is ASCII, so JavaScript's `<` on the encoded
+ * strings IS a byte comparison; that equivalence is why this can use plain
+ * string comparison rather than comparing `Uint8Array`s.
+ *
+ * Duplicate names are ordered by their encoded value, as the spec says.
+ */
+export function canonicalQuery(params) {
+    const encoded = params.map(([name, value]) => [encodeRfc3986(name), encodeRfc3986(value)]);
+    encoded.sort((a, b) => {
+        if (a[0] !== b[0])
+            return a[0] < b[0] ? -1 : 1;
+        if (a[1] !== b[1])
+            return a[1] < b[1] ? -1 : 1;
+        return 0;
+    });
+    return encoded.map(([name, value]) => `${name}=${value}`).join("&");
+}
+/** UTF-8 byte length — S3's key limit is 1024 BYTES, not 1024 characters. */
+export function utf8Length(value) {
+    return UTF8.encode(value).length;
+}

package/dist/lib/request.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What else gets signed, besides the path: the headers pinned into a PUT and
+ * the query overrides pinned into a GET.
+ *
+ * These two look symmetrical and are not, and the asymmetry is the whole
+ * reason this module exists:
+ *
+ *   - A PUT pins `content-type` (and any `x-amz-meta-*`) as a signed HEADER.
+ *     It therefore lands in `SignedHeaders`, and the eventual upload must
+ *     send that header with that exact value or the store answers 403. The
+ *     tool that mints the URL is the only thing that knows the value, so it
+ *     hands it back and says to send it verbatim.
+ *   - A GET pins its overrides as signed QUERY parameters. They are already
+ *     in the URL, so the caller sends them by doing nothing at all.
+ *
+ * Mixing the two — a `content-type` on a GET — is refused rather than
+ * quietly dropped or quietly signed, because both of those produce a URL that
+ * fails much later for a reason that does not mention content types.
+ */
+import type { QueryParam } from "./encode";
+import { type Header } from "./sigv4";
+export declare const OPERATIONS: readonly ["get", "put"];
+export type Operation = (typeof OPERATIONS)[number];
+/** S3's ceiling on user metadata, counted over the names and values together. */
+export declare const MAX_METADATA_BYTES = 2048;
+/**
+ * Refuse a header value this package cannot sign honestly.
+ *
+ * A CR or LF is a request-splitting attempt or a stray paste; neither belongs
+ * in a signature. The second check is subtler: SigV4 canonicalization trims
+ * the ends of a header value and collapses internal whitespace runs, so a
+ * value with a doubled space is signed in a form the caller did not write.
+ * The server applies the same reduction and it would in fact verify — but the
+ * tool's promise is "send this back byte for byte", and a value that is not
+ * its own canonical form makes that promise false. The spec's quoted-string
+ * exemption lives in the same gap. Refusing is one sentence; explaining the
+ * exemption to whoever hits the 403 is not.
+ */
+export declare function checkHeaderValue(name: string, value: string): void;
+/**
+ * Turn `{ owner: "ops" }` into `[["x-amz-meta-owner", "ops"]]`.
+ *
+ * Names are lowercased here because S3 lowercases them on arrival: signing
+ * `X-Amz-Meta-Owner` and receiving `x-amz-meta-owner` is a mismatch the
+ * caller cannot see and cannot fix.
+ */
+export declare function metadataHeaders(metadata: Record<string, string>): Header[];
+export type Overrides = {
+    responseContentType?: string;
+    responseContentDisposition?: string;
+    responseCacheControl?: string;
+    versionId?: string;
+};
+/**
+ * The GET-side pins, as signed query parameters.
+ *
+ * `response-content-disposition` is the reason this exists: it is how a
+ * presigned link downloads as `invoice-2026-01.pdf` instead of as the key,
+ * and it only works if it is signed in — adding it to a finished URL
+ * invalidates the signature.
+ */
+export declare function responseOverrides(overrides: Overrides): QueryParam[];
+/**
+ * Refuse the cross-operation mistakes before anything is signed.
+ *
+ * Each of these would otherwise produce a URL that looks correct and fails
+ * for a reason the 403 does not name.
+ */
+export declare function checkOperationFields(operation: Operation, fields: {
+    contentType?: string;
+    metadata?: Record<string, string>;
+    overrides: Overrides;
+}): void;

package/dist/lib/request.js

@@ -0,0 +1,118 @@
+import { canonicalHeaderValue } from "./sigv4";
+import { PresignError } from "./store";
+export const OPERATIONS = ["get", "put"];
+/** S3's ceiling on user metadata, counted over the names and values together. */
+export const MAX_METADATA_BYTES = 2048;
+/**
+ * Refuse a header value this package cannot sign honestly.
+ *
+ * A CR or LF is a request-splitting attempt or a stray paste; neither belongs
+ * in a signature. The second check is subtler: SigV4 canonicalization trims
+ * the ends of a header value and collapses internal whitespace runs, so a
+ * value with a doubled space is signed in a form the caller did not write.
+ * The server applies the same reduction and it would in fact verify — but the
+ * tool's promise is "send this back byte for byte", and a value that is not
+ * its own canonical form makes that promise false. The spec's quoted-string
+ * exemption lives in the same gap. Refusing is one sentence; explaining the
+ * exemption to whoever hits the 403 is not.
+ */
+export function checkHeaderValue(name, value) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: refusing C0 controls is the point.
+    if (/[\x00-\x1f\x7f]/.test(value)) {
+        throw new PresignError(`${name} contains a control character (a CR, LF or tab). A header value that is signed here and sent later must be one line of printable text`);
+    }
+    if (canonicalHeaderValue(value) !== value) {
+        throw new PresignError(`${name} "${value}" has leading, trailing or repeated whitespace. SigV4 signs the whitespace-collapsed form, so the value handed back would not be the value signed — pass "${canonicalHeaderValue(value)}" if that is what you meant`);
+    }
+}
+/** A metadata name must be an HTTP token; S3 lowercases it on the way in. */
+const TOKEN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+/**
+ * Turn `{ owner: "ops" }` into `[["x-amz-meta-owner", "ops"]]`.
+ *
+ * Names are lowercased here because S3 lowercases them on arrival: signing
+ * `X-Amz-Meta-Owner` and receiving `x-amz-meta-owner` is a mismatch the
+ * caller cannot see and cannot fix.
+ */
+export function metadataHeaders(metadata) {
+    const headers = [];
+    const seen = new Set();
+    let bytes = 0;
+    for (const [rawName, value] of Object.entries(metadata)) {
+        if (!TOKEN.test(rawName)) {
+            throw new PresignError(`metadata name "${rawName}" is not a valid HTTP header token — use letters, digits and -_.`);
+        }
+        if (rawName.toLowerCase().startsWith("x-amz-meta-")) {
+            throw new PresignError(`metadata name "${rawName}" already carries the x-amz-meta- prefix; pass the bare name ("${rawName.slice("x-amz-meta-".length)}") and the prefix is added here`);
+        }
+        const name = `x-amz-meta-${rawName.toLowerCase()}`;
+        if (seen.has(name)) {
+            throw new PresignError(`metadata names "${rawName}" and another differ only in case; S3 lowercases them, so one would silently overwrite the other`);
+        }
+        seen.add(name);
+        if (!/^[\x20-\x7e]*$/.test(value)) {
+            throw new PresignError(`metadata value for "${rawName}" is not printable US-ASCII. S3 carries user metadata in HTTP headers, which cannot hold it as-is — encode it yourself (base64, or RFC 2047) so that what is signed is what is sent`);
+        }
+        checkHeaderValue(`metadata value for "${rawName}"`, value);
+        bytes += name.length + value.length;
+        headers.push([name, value]);
+    }
+    if (bytes > MAX_METADATA_BYTES) {
+        throw new PresignError(`user metadata is ${bytes} bytes and S3's limit is ${MAX_METADATA_BYTES}; the store would reject the upload after the bytes were sent`);
+    }
+    return headers;
+}
+/**
+ * The GET-side pins, as signed query parameters.
+ *
+ * `response-content-disposition` is the reason this exists: it is how a
+ * presigned link downloads as `invoice-2026-01.pdf` instead of as the key,
+ * and it only works if it is signed in — adding it to a finished URL
+ * invalidates the signature.
+ */
+export function responseOverrides(overrides) {
+    const query = [];
+    const push = (param, value) => {
+        if (value === undefined)
+            return;
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: refusing C0 controls is the point.
+        if (/[\x00-\x1f\x7f]/.test(value)) {
+            throw new PresignError(`${param} contains a control character`);
+        }
+        query.push([param, value]);
+    };
+    push("response-content-type", overrides.responseContentType);
+    push("response-content-disposition", overrides.responseContentDisposition);
+    push("response-cache-control", overrides.responseCacheControl);
+    push("versionId", overrides.versionId);
+    return query;
+}
+/**
+ * Refuse the cross-operation mistakes before anything is signed.
+ *
+ * Each of these would otherwise produce a URL that looks correct and fails
+ * for a reason the 403 does not name.
+ */
+export function checkOperationFields(operation, fields) {
+    const named = (name) => {
+        throw new PresignError(operation === "get"
+            ? `${name} applies to an upload, not a download. A GET cannot pin a request header the browser will not send; use responseContentType or responseContentDisposition, which are signed into the URL itself`
+            : `${name} applies to a download, not an upload: the response-* overrides tell S3 how to answer a GET. For a PUT, pass contentType and metadata, which are signed as request headers`);
+    };
+    if (operation === "get") {
+        if (fields.contentType !== undefined)
+            named("contentType");
+        if (fields.metadata !== undefined)
+            named("metadata");
+        return;
+    }
+    if (fields.overrides.responseContentType !== undefined)
+        named("responseContentType");
+    if (fields.overrides.responseContentDisposition !== undefined)
+        named("responseContentDisposition");
+    if (fields.overrides.responseCacheControl !== undefined)
+        named("responseCacheControl");
+    if (fields.overrides.versionId !== undefined) {
+        throw new PresignError("versionId identifies an existing version to read; a PUT creates a new one, and the store assigns its id");
+    }
+}

package/dist/lib/sigv4.d.ts

@@ -0,0 +1,132 @@
+import { type QueryParam } from "./encode";
+export declare const ALGORITHM = "AWS4-HMAC-SHA256";
+/**
+ * The payload hash a presigned URL carries. The body does not exist yet when
+ * the URL is minted — that is the entire point of presigning — so S3 accepts
+ * this sentinel in place of a digest. Writing the SHA-256 of the empty string
+ * here instead would sign "this PUT has no body", and every real upload would
+ * then 403.
+ */
+export declare const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+/** A header as it will be signed: `[name, value]`, name in any case. */
+export type Header = readonly [string, string];
+/** Lowercase-hex SHA-256 of a string, the form every step of SigV4 wants. */
+export declare function sha256Hex(value: string): string;
+/**
+ * Derive the signing key: HMAC down the scope, starting from `AWS4` + secret.
+ *
+ * `dateStamp` is `YYYYMMDD` in UTC, and it must be the same day as the
+ * timestamp in the string to sign. A key derived from yesterday's date with
+ * today's timestamp verifies against nothing, and the error says only
+ * `SignatureDoesNotMatch`.
+ */
+export declare function signingKey(secretAccessKey: string, dateStamp: string, region: string, service: string): Buffer;
+/** `20130524T000000Z` and `20130524` for an instant, always UTC. */
+export declare function amzTimestamps(epochMs: number): {
+    amzDate: string;
+    dateStamp: string;
+};
+/** `20130524/us-east-1/s3/aws4_request` — the credential scope. */
+export declare function credentialScope(dateStamp: string, region: string, service: string): string;
+/**
+ * Canonicalize one header value: trim the ends, collapse internal runs of
+ * whitespace to a single space.
+ *
+ * The server applies this same reduction to what it receives, so a value with
+ * doubled spaces still verifies — the collapse is not a divergence. The
+ * divergence to fear is a DIFFERENT value: an HTTP client that appends
+ * `; charset=utf-8` to a bare `text/plain` changes the signed bytes, and no
+ * canonicalization saves it. That is why the caller is handed back the exact
+ * value that was signed.
+ *
+ * Known limit, stated rather than hidden: the spec exempts whitespace inside
+ * a quoted string from the collapse. This does not implement that exemption,
+ * so a value like `attachment; filename="a  b"` would be canonicalized by
+ * this code and (arguably) not by the server. Such values are refused
+ * upstream in `headers.ts` rather than signed on a guess.
+ */
+export declare function canonicalHeaderValue(value: string): string;
+/**
+ * The `SignedHeaders` value: lowercase names, sorted, semicolon-joined.
+ *
+ * It appears twice in a presigned URL — inside the canonical request and as
+ * the `X-Amz-SignedHeaders` query parameter — and the two must agree, so both
+ * come from here rather than from two list comprehensions that drift.
+ */
+export declare function signedHeaderList(headers: ReadonlyArray<Header>): string;
+export type CanonicalRequest = {
+    /** The canonical request text, newline-joined, exactly as it is hashed. */
+    text: string;
+    /** `content-type;host;x-amz-meta-owner` — semicolon-joined, sorted. */
+    signedHeaders: string;
+};
+/**
+ * Assemble the canonical request.
+ *
+ * `canonicalUri` arrives already percent-encoded (see `encode.ts`): this
+ * function must not encode it again, because whether the path is encoded once
+ * or twice is a per-service fact the caller owns and S3's answer is "once".
+ */
+export declare function canonicalRequest(input: {
+    method: string;
+    canonicalUri: string;
+    query: ReadonlyArray<QueryParam>;
+    headers: ReadonlyArray<Header>;
+    payloadHash: string;
+}): CanonicalRequest;
+/** The string to sign: algorithm, timestamp, scope, hash of the canonical request. */
+export declare function stringToSign(input: {
+    amzDate: string;
+    scope: string;
+    canonicalRequest: string;
+}): string;
+/** The signature itself: lowercase hex, 64 characters. */
+export declare function sign(input: {
+    secretAccessKey: string;
+    dateStamp: string;
+    region: string;
+    service: string;
+    stringToSign: string;
+}): string;
+export type PresignInput = {
+    method: "GET" | "PUT";
+    /** `https://bucket.s3.amazonaws.com` — scheme and authority, no path. */
+    origin: string;
+    /** The exact Host header value, port included only when non-default. */
+    host: string;
+    /** Already percent-encoded, always starting with `/`. */
+    canonicalUri: string;
+    region: string;
+    service: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+    epochMs: number;
+    expiresInSeconds: number;
+    /** Extra query parameters to sign, un-encoded. */
+    query?: ReadonlyArray<QueryParam>;
+    /** Headers to sign beyond `host`, un-canonicalized. */
+    headers?: ReadonlyArray<Header>;
+};
+export type PresignResult = {
+    url: string;
+    amzDate: string;
+    /** Sorted, semicolon-joined — what the eventual request must send. */
+    signedHeaders: string;
+    canonicalRequest: string;
+    stringToSign: string;
+    signature: string;
+};
+/**
+ * Mint a presigned URL: query-string authentication, SigV4.
+ *
+ * Two facts about query-string auth that the header-based form does not share,
+ * and that are easy to get wrong by analogy:
+ *
+ *   - the session token travels as `X-Amz-Security-Token` in the QUERY and is
+ *     signed there, not as a header;
+ *   - `X-Amz-Signature` itself is the one parameter excluded from the
+ *     canonical query string, because it does not exist yet when the canonical
+ *     request is built. It is appended to the URL afterwards.
+ */
+export declare function presign(input: PresignInput): PresignResult;

package/dist/lib/sigv4.js

@@ -0,0 +1,203 @@
+/**
+ * AWS Signature Version 4, as arithmetic.
+ *
+ * Nothing in this file reaches a network, opens a socket or keeps state. It
+ * takes a request description and a secret, and returns bytes. The secret is
+ * used to derive the signing key and is referenced nowhere else — not in the
+ * result, not in an error message, not in a log line — because a signing
+ * routine that puts its key into a thrown error has published it to every
+ * transcript that ever catches one.
+ *
+ * The chain, per AWS's "Signing AWS API requests":
+ *
+ *   1. canonical request  — method, URI, query, headers, signed-header list,
+ *                           payload hash, joined by newlines
+ *   2. string to sign     — algorithm, timestamp, credential scope, and the
+ *                           SHA-256 of (1)
+ *   3. signing key        — HMAC-SHA256 chained through date, region, service
+ *                           and the literal `aws4_request`
+ *   4. signature          — HMAC-SHA256 of (2) under (3), lowercase hex
+ *
+ * Step 3 is why a leaked signature is not a leaked credential: it is scoped to
+ * one day, one region and one service, and it cannot be run backwards.
+ */
+import { createHash, createHmac } from "node:crypto";
+import { canonicalQuery } from "./encode";
+export const ALGORITHM = "AWS4-HMAC-SHA256";
+/**
+ * The payload hash a presigned URL carries. The body does not exist yet when
+ * the URL is minted — that is the entire point of presigning — so S3 accepts
+ * this sentinel in place of a digest. Writing the SHA-256 of the empty string
+ * here instead would sign "this PUT has no body", and every real upload would
+ * then 403.
+ */
+export const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+/** Lowercase-hex SHA-256 of a string, the form every step of SigV4 wants. */
+export function sha256Hex(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function hmac(key, data) {
+    return createHmac("sha256", key).update(data, "utf8").digest();
+}
+/**
+ * Derive the signing key: HMAC down the scope, starting from `AWS4` + secret.
+ *
+ * `dateStamp` is `YYYYMMDD` in UTC, and it must be the same day as the
+ * timestamp in the string to sign. A key derived from yesterday's date with
+ * today's timestamp verifies against nothing, and the error says only
+ * `SignatureDoesNotMatch`.
+ */
+export function signingKey(secretAccessKey, dateStamp, region, service) {
+    const kDate = hmac(`AWS4${secretAccessKey}`, dateStamp);
+    const kRegion = hmac(kDate, region);
+    const kService = hmac(kRegion, service);
+    return hmac(kService, "aws4_request");
+}
+/** `20130524T000000Z` and `20130524` for an instant, always UTC. */
+export function amzTimestamps(epochMs) {
+    if (!Number.isFinite(epochMs))
+        throw new Error("the signing instant is not a finite number");
+    // toISOString throws RangeError outside ±8.64e15; let it, rather than
+    // emitting "InvalidDate" into a signature.
+    const iso = new Date(epochMs).toISOString();
+    // Sub-second precision is dropped rather than rounded: X-Amz-Date has
+    // second resolution, and rounding up could place the timestamp in the
+    // future for a store that enforces clock skew strictly.
+    const amzDate = `${iso.slice(0, 19).replace(/[-:]/g, "")}Z`;
+    if (!/^\d{8}T\d{6}Z$/.test(amzDate)) {
+        // The finite check above is not enough, and the RangeError above does not
+        // cover this. `toISOString` only throws outside ±8.64e15; for the years
+        // in between that do not fit four digits it switches to the EXPANDED
+        // form, `+010000-01-01T00:00:00.000Z`. Slicing that yields an X-Amz-Date
+        // of `+0100000101T0000Z` and a credential scope of `+0100000/...` — a URL
+        // that is well-formed, correctly signed over nonsense, and refused by
+        // every store on earth with the reason nowhere in sight. Refuse the
+        // instant instead of signing it.
+        throw new Error(`the signing instant (${iso}) is outside the years 0000-9999 that X-Amz-Date can express`);
+    }
+    return { amzDate, dateStamp: amzDate.slice(0, 8) };
+}
+/** `20130524/us-east-1/s3/aws4_request` — the credential scope. */
+export function credentialScope(dateStamp, region, service) {
+    return `${dateStamp}/${region}/${service}/aws4_request`;
+}
+/**
+ * Canonicalize one header value: trim the ends, collapse internal runs of
+ * whitespace to a single space.
+ *
+ * The server applies this same reduction to what it receives, so a value with
+ * doubled spaces still verifies — the collapse is not a divergence. The
+ * divergence to fear is a DIFFERENT value: an HTTP client that appends
+ * `; charset=utf-8` to a bare `text/plain` changes the signed bytes, and no
+ * canonicalization saves it. That is why the caller is handed back the exact
+ * value that was signed.
+ *
+ * Known limit, stated rather than hidden: the spec exempts whitespace inside
+ * a quoted string from the collapse. This does not implement that exemption,
+ * so a value like `attachment; filename="a  b"` would be canonicalized by
+ * this code and (arguably) not by the server. Such values are refused
+ * upstream in `headers.ts` rather than signed on a guess.
+ */
+export function canonicalHeaderValue(value) {
+    return value.trim().replace(/[ \t]+/g, " ");
+}
+/**
+ * The `SignedHeaders` value: lowercase names, sorted, semicolon-joined.
+ *
+ * It appears twice in a presigned URL — inside the canonical request and as
+ * the `X-Amz-SignedHeaders` query parameter — and the two must agree, so both
+ * come from here rather than from two list comprehensions that drift.
+ */
+export function signedHeaderList(headers) {
+    return headers
+        .map(([name]) => name.toLowerCase())
+        .sort()
+        .join(";");
+}
+/**
+ * Assemble the canonical request.
+ *
+ * `canonicalUri` arrives already percent-encoded (see `encode.ts`): this
+ * function must not encode it again, because whether the path is encoded once
+ * or twice is a per-service fact the caller owns and S3's answer is "once".
+ */
+export function canonicalRequest(input) {
+    const lowered = input.headers.map(([name, value]) => [name.toLowerCase(), canonicalHeaderValue(value)]);
+    lowered.sort((a, b) => (a[0] === b[0] ? 0 : a[0] < b[0] ? -1 : 1));
+    const canonicalHeaders = lowered.map(([name, value]) => `${name}:${value}\n`).join("");
+    const signedHeaders = lowered.map(([name]) => name).join(";");
+    const text = [
+        input.method,
+        input.canonicalUri,
+        canonicalQuery(input.query),
+        canonicalHeaders,
+        signedHeaders,
+        input.payloadHash,
+    ].join("\n");
+    return { text, signedHeaders };
+}
+/** The string to sign: algorithm, timestamp, scope, hash of the canonical request. */
+export function stringToSign(input) {
+    return [ALGORITHM, input.amzDate, input.scope, sha256Hex(input.canonicalRequest)].join("\n");
+}
+/** The signature itself: lowercase hex, 64 characters. */
+export function sign(input) {
+    const key = signingKey(input.secretAccessKey, input.dateStamp, input.region, input.service);
+    return hmac(key, input.stringToSign).toString("hex");
+}
+/**
+ * Mint a presigned URL: query-string authentication, SigV4.
+ *
+ * Two facts about query-string auth that the header-based form does not share,
+ * and that are easy to get wrong by analogy:
+ *
+ *   - the session token travels as `X-Amz-Security-Token` in the QUERY and is
+ *     signed there, not as a header;
+ *   - `X-Amz-Signature` itself is the one parameter excluded from the
+ *     canonical query string, because it does not exist yet when the canonical
+ *     request is built. It is appended to the URL afterwards.
+ */
+export function presign(input) {
+    const { amzDate, dateStamp } = amzTimestamps(input.epochMs);
+    const scope = credentialScope(dateStamp, input.region, input.service);
+    const headers = [["host", input.host], ...(input.headers ?? [])];
+    const signed = signedHeaderList(headers);
+    const query = [
+        ...(input.query ?? []),
+        ["X-Amz-Algorithm", ALGORITHM],
+        ["X-Amz-Credential", `${input.accessKeyId}/${scope}`],
+        ["X-Amz-Date", amzDate],
+        ["X-Amz-Expires", String(input.expiresInSeconds)],
+        ["X-Amz-SignedHeaders", signed],
+    ];
+    if (input.sessionToken !== undefined) {
+        query.push(["X-Amz-Security-Token", input.sessionToken]);
+    }
+    const creq = canonicalRequest({
+        method: input.method,
+        canonicalUri: input.canonicalUri,
+        query,
+        headers,
+        payloadHash: UNSIGNED_PAYLOAD,
+    });
+    const toSign = stringToSign({ amzDate, scope, canonicalRequest: creq.text });
+    const signature = sign({
+        secretAccessKey: input.secretAccessKey,
+        dateStamp,
+        region: input.region,
+        service: input.service,
+        stringToSign: toSign,
+    });
+    // The URL carries the canonical (sorted, encoded) query so that two calls
+    // with the same inputs produce byte-identical URLs. The server re-sorts
+    // anyway; determinism is for the caller, who diffs these.
+    const url = `${input.origin}${input.canonicalUri}?${canonicalQuery(query)}&X-Amz-Signature=${signature}`;
+    return {
+        url,
+        amzDate,
+        signedHeaders: creq.signedHeaders,
+        canonicalRequest: creq.text,
+        stringToSign: toSign,
+        signature,
+    };
+}