@crewhaus/tool-objectstore 0.7.0

package/README.md

@@ -0,0 +1,190 @@
+# @crewhaus/tool-objectstore
+
+A door key for one object, instead of the keys to the building.
+
+| Tool | Answers |
+|---|---|
+| `ObjectPresign` | what URL lets someone download or upload this one object, for this long |
+
+`ObjectPresign` mints a time-limited SigV4 URL for an S3-compatible store —
+AWS S3, Cloudflare R2, MinIO, anything that verifies SigV4. Whoever holds the
+URL can do one thing to one object until it expires. They get no credential,
+and the bytes never pass through the harness.
+
+## It computes; it does not connect
+
+The whole package is HMAC-SHA256 from `node:crypto` over strings. No SDK, no
+socket, no file read, no state between calls except an injectable clock. It
+works offline, and the same inputs always produce the same URL.
+
+That claim is not left to the reader. The test suite greps this package's own
+source for `node:http`, `node:net`, `node:fs`, a `fetch` call and the rest, so
+an edit that adds one fails a test rather than a review.
+
+It holds no credential either. The access key and secret arrive as arguments
+from whatever the caller uses for secrets, the secret is consumed by the
+signing-key derivation, and it appears in no result, no error and no stack
+trace — asserted on both the success and the failure path. The access key ID
+*is* in the URL: SigV4 puts it in `X-Amz-Credential` by construction, which is
+how the store knows which key to check against. That one is public by design.
+
+## Three things that fail hours later
+
+Every trap in this package has the same shape: the URL comes back looking
+perfect and the failure arrives later, from somewhere else, as a 403 that
+explains nothing.
+
+### 1. `encodeURIComponent` is the wrong encoder
+
+SigV4 percent-encodes everything outside `A-Z a-z 0-9 - _ . ~`.
+`encodeURIComponent` leaves five of those alone:
+
+| Key contains | `encodeURIComponent` | SigV4 |
+|---|---|---|
+| `!` `'` `(` `)` `*` | unchanged | `%21` `%27` `%28` `%29` `%2A` |
+| a space | `%20` | `%20` |
+| `+` | `%2B` | `%2B` |
+| `é` | `%C3%A9` | `%C3%A9` |
+
+So `q&a (2026)/notes!.txt` signs one way and is requested another. The encoder
+here is hand-written for that reason, and it is tested against keys with
+spaces, pluses, the five stragglers, three-byte characters and a surrogate
+pair.
+
+Two more rules live in the same place. The object key is encoded **once** and
+its `/` separators are left alone (every non-S3 AWS service double-encodes its
+canonical URI — the option exists, it is just not what S3 wants). And the
+query string is encoded and **then** sorted, in that order: encoding moves
+characters around the ASCII table, so `a-b` and `a?b` come out in the opposite
+order from the one a sort-then-encode would produce.
+
+### 2. A pinned `content-type` is a promise the caller has to keep
+
+Passing `contentType` to a PUT puts `content-type` into `SignedHeaders`. The
+eventual upload must send that header with that exact value; an HTTP client
+that appends `; charset=utf-8` is sending different signed bytes, and the
+store answers 403 without mentioning headers.
+
+So the result carries the exact headers alongside the URL, plus a sentence
+saying to send them verbatim, plus a `curl` line that already does:
+
+```json
+{
+  "url": "https://…?X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Signature=…",
+  "headers": { "content-type": "application/pdf" },
+  "sendHeadersVerbatim": "send every header above exactly as written — …",
+  "signedHeaders": ["content-type", "host"]
+}
+```
+
+`x-amz-meta-*` works the same way, so `metadata` comes back in `headers` too.
+A GET is the opposite case: `responseContentType` and
+`responseContentDisposition` are signed into the **query**, so they are
+already in the URL and the caller sends them by doing nothing. Mixing the two
+— a `contentType` on a GET — is refused with the alternative named, rather
+than dropped or signed on a guess.
+
+### 3. The addressing style is an argument, never an inference
+
+Virtual-hosted style puts the bucket in the hostname; path style puts it in
+the path. They change *both* the Host header and the canonical URI, so a
+wrong guess is not a typo the server can correct — it is a different request.
+
+| `addressingStyle` | Host | Path |
+|---|---|---|
+| `virtual-hosted` | `docs.s3.us-east-1.amazonaws.com` | `/report.pdf` |
+| `path` | `s3.us-east-1.amazonaws.com` | `/docs/report.pdf` |
+
+AWS S3 and most R2 setups are virtual-hosted; MinIO and some R2 and gateway
+configurations are path-style, and the endpoint URL looks identical either
+way. There is no default.
+
+## What it refuses, and why
+
+Each of these would otherwise mint a URL that cannot work, for a reason the
+store's answer will not name:
+
+| Refused | Because |
+|---|---|
+| a key with a `.` or `..` segment | clients resolve it before sending, so the path signed is not the path that arrives |
+| a key with `//` or a leading `/` | URL normalization collapses it on the way out |
+| a key over 1024 **bytes** | S3's limit counts bytes, so a non-ASCII key reaches it sooner than it looks |
+| a control character in a key or header | a bare CR splits the request in a careless client |
+| `http://` to anything but loopback | the URL *is* the credential for that object; http puts it and the object on the wire in clear. Loopback means the parsed address — `localhost`, `*.localhost`, `[::1]`, or an IPv4 literal in `127.0.0.0/8`. A hostname that merely *starts* with `127.` is a domain somebody else registers |
+| an endpoint with a path, query or credentials | a prefix would be signed twice or not at all |
+| virtual-hosted style against an IP endpoint | an address cannot carry a bucket as a subdomain (this is the local-MinIO mistake) |
+| an endpoint that already names the bucket | it would be signed twice |
+| a bucket that cannot be a DNS label, virtual-hosted | the request would not reach the store; path style takes it, with a warning |
+| a bucket that is not a usable path segment, path-style | `.` would sign `/./key`, the same dot segment a key is refused for |
+| a signing instant outside the years 0000–9999 | `X-Amz-Date` has four digits for the year; `toISOString` switches to `+010000-…` rather than throwing, and the slice of that is a signature over nonsense |
+| a region like `US-East-1` | the credential scope is matched literally |
+| a secret with leading or trailing whitespace | a newline picked up while reading or pasting, which signs cleanly and verifies nowhere |
+| `expiresInSeconds` over 7 days | SigV4 query authentication stops there; clamping silently would be a lie |
+| a `content-type` with doubled or edge whitespace | SigV4 signs the collapsed form, so the value handed back would not be the value signed |
+
+Warnings, rather than refusals, cover the cases that work but should be seen:
+a dotted bucket in virtual-hosted style (the wildcard certificate covers one
+label), temporary credentials (the URL also dies with the session token), and
+an expiry long enough that the URL is effectively a copy of the object.
+
+## Vectors, not vibes
+
+The signing tests are pinned to AWS's own published values and are written as
+literals, so a change to the encoder or the canonicalization moves a byte and
+the test says so:
+
+- the signing-key derivation example (`iam` / `us-east-1` / `20120215`);
+- `aws-sig-v4-test-suite` `get-vanilla` and `get-header-value-trim`, canonical
+  request, string-to-sign and signature;
+- the documented presigned GET Object example for `examplebucket/test.txt`,
+  reproduced end to end through the tool.
+
+Vectors only cover the requests somebody published. So the integration suite
+adds a verifier — the store's half of the exchange, built from the finished
+URL string and nothing the tool returned alongside it — and runs ten awkward
+keys through mint-then-verify, plus the cases that must *fail*: a tampered
+path, the wrong secret, a GET URL replayed as a PUT, a pinned header dropped
+or "improved", and a query parameter appended after signing. Every refusal
+asserts *which* reason it got, so a verifier that fell over somewhere else
+cannot pass for a signature that was correctly rejected.
+
+The verifier writes out RFC 3986 percent-encoding a second time, from the
+rule, rather than importing this package's encoder — and each minted path is
+compared against that independent encoding of the key. Taking `canonicalUri`
+off the minted URL instead, as an earlier version did, makes the verifier
+agree with the tool by construction: with the encoder broken to
+`encodeURIComponent`'s unreserved set, all ten keys still verified, including
+the two carrying `!` `'` `(` `)` `*`.
+
+## Using it
+
+```jsonc
+{
+  "operation": "put",
+  "endpoint": "https://s3.us-east-1.amazonaws.com",
+  "addressingStyle": "virtual-hosted",
+  "region": "us-east-1",
+  "bucket": "acme-invoices",
+  "key": "2026/q1/invoice 0041.pdf",
+  "contentType": "application/pdf",
+  "metadata": { "run-id": "r-4412" },
+  "expiresInSeconds": 900,
+  "accessKeyId": "…",
+  "secretAccessKey": "…"
+}
+```
+
+`signedAt` pins the signing instant, so a URL can be reproduced exactly when
+somebody asks why theirs stopped working. `includeCanonical` returns the
+canonical request and string-to-sign, which is what you diff against the
+`CanonicalRequest` S3 echoes back in a 403 body.
+
+## For the next AWS-signing tool
+
+`lib/sigv4.ts` and `lib/encode.ts` are the general primitive, not an S3
+detail: `encodeRfc3986`, `encodePath` (with the double-encoding option the
+other services need), `canonicalQuery`, `signingKey`, `canonicalRequest`,
+`stringToSign` and `sign` are all exported. Anything in this monorepo that
+needs to sign an AWS request should import them rather than write a second
+copy — there is no second copy today, and the golden vectors are what keeps
+the first one honest.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { PresignError } from "./lib/store";
+export { _setClock, type Clock } from "./lib/clock";
+export { PresignError };
+export { canonicalQuery, encodePath, encodeRfc3986, type QueryParam, } from "./lib/encode";
+export { ALGORITHM, UNSIGNED_PAYLOAD, type Header, amzTimestamps, canonicalRequest, credentialScope, presign, sign, signedHeaderList, signingKey, stringToSign, } from "./lib/sigv4";
+export declare const objectPresign: RegisteredTool;
+/** Every tool this package registers, in the order a catalog should list them. */
+export declare const OBJECTSTORE_TOOLS: ReadonlyArray<RegisteredTool>;

package/dist/index.js

@@ -0,0 +1,256 @@
+/**
+ * @crewhaus/tool-objectstore — handing out a door key instead of the building.
+ *
+ * `ObjectPresign` mints a time-limited URL that downloads or uploads one
+ * object in an S3-compatible store. Nothing else in the harness has to touch
+ * the bytes: the URL goes to whoever needs the file, they talk to the store
+ * directly, and the URL stops working when it expires.
+ *
+ * This is arithmetic, not I/O. The whole package is HMAC-SHA256 from
+ * `node:crypto` over strings; it opens no socket, reads no file, spawns
+ * nothing and keeps no state between calls beyond the injectable clock. That
+ * is why it declares no `ioCapability` — the test suite asserts it, over the
+ * package's own source, so the claim cannot rot.
+ *
+ * It holds no credential either. The access key and secret arrive as
+ * arguments from whatever the caller uses for secrets, the secret is consumed
+ * by the signing-key derivation, and it is referenced in no result, no error
+ * and no log line. (The access key ID does appear in the URL: SigV4 puts it
+ * in `X-Amz-Credential` by construction, which is how the store knows which
+ * key to verify against. That is public by design; the secret is not.)
+ *
+ * Three things are easy to get wrong here and all three fail late:
+ *
+ *   1. **Encoding.** `encodeURIComponent` is not SigV4's encoder. See
+ *      `lib/encode.ts`.
+ *   2. **Signed headers.** Pinning a content type puts `content-type` into
+ *      `SignedHeaders`, so the upload must send that value byte for byte.
+ *      The result carries the exact headers for that reason.
+ *   3. **Addressing style.** Virtual-hosted and path style change both the
+ *      Host header and the path, so the style is an argument, never a guess.
+ */
+import { buildTool } from "@crewhaus/tool-builder";
+import { z } from "zod";
+import { nowMs, parseInstant } from "./lib/clock";
+import { OPERATIONS, checkHeaderValue, checkOperationFields, metadataHeaders, responseOverrides, } from "./lib/request";
+import { UNSIGNED_PAYLOAD, presign } from "./lib/sigv4";
+import { ADDRESSING_STYLES, PresignError, parseEndpoint, resolveTarget } from "./lib/store";
+export { _setClock } from "./lib/clock";
+export { PresignError };
+export { canonicalQuery, encodePath, encodeRfc3986, } from "./lib/encode";
+export { ALGORITHM, UNSIGNED_PAYLOAD, amzTimestamps, canonicalRequest, credentialScope, presign, sign, signedHeaderList, signingKey, stringToSign, } from "./lib/sigv4";
+const json = (value) => JSON.stringify(value);
+/** SigV4 query authentication expires at seven days. Past that, S3 refuses. */
+const MAX_EXPIRY_SECONDS = 7 * 24 * 60 * 60;
+const DEFAULT_EXPIRY_SECONDS = 900;
+/** Past this, a link is less "a link" and more "a copy of the object". */
+const LONG_LIVED_SECONDS = 24 * 60 * 60;
+/** S3 is the only service whose canonical URI is single-encoded; see lib/encode.ts. */
+const SERVICE = "s3";
+/** Shell-quote for the copy-pasteable example. Single quotes, POSIX style. */
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function checkCredential(name, value) {
+    if (value.trim() !== value) {
+        // The classic: a secret read from a file or pasted from a console arrives
+        // with a trailing newline. It signs perfectly and verifies nowhere, and
+        // the store's answer is SignatureDoesNotMatch with no mention of
+        // whitespace. Nothing downstream can detect this; here it is one check.
+        throw new PresignError(`${name} has leading or trailing whitespace — almost always a newline picked up when the secret was read or pasted. It would produce a signature that fails with "SignatureDoesNotMatch" and no other clue`);
+    }
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: refusing C0 controls is the point.
+    if (/[\x00-\x1f\x7f\s]/.test(value)) {
+        throw new PresignError(`${name} contains whitespace or a control character`);
+    }
+}
+const inputSchema = z
+    .object({
+    operation: z
+        .enum(OPERATIONS)
+        .describe("get to hand out a download link, put to hand out an upload target"),
+    endpoint: z
+        .string()
+        .min(1)
+        .max(512)
+        .describe("the store's origin and nothing else, e.g. https://s3.us-east-1.amazonaws.com, https://<account>.r2.cloudflarestorage.com or http://127.0.0.1:9000 for a local MinIO"),
+    addressingStyle: z
+        .enum(ADDRESSING_STYLES)
+        .describe("virtual-hosted puts the bucket in the hostname (AWS S3 and most R2 setups); path puts it in the path (MinIO, and R2 or gateways configured that way). This is not inferred: the two produce different Host headers and different paths, so a wrong guess signs a request that can never verify"),
+    region: z
+        .string()
+        .min(1)
+        .max(64)
+        .describe("the region in the credential scope, e.g. us-east-1, or auto for R2"),
+    bucket: z.string().min(1).max(255),
+    key: z.string().min(1).max(2048).describe("the object key, without a leading slash"),
+    accessKeyId: z.string().min(1).max(256),
+    secretAccessKey: z
+        .string()
+        .min(1)
+        .max(256)
+        .describe("used to derive the signing key and nothing else; it is not returned, logged or stored"),
+    sessionToken: z
+        .string()
+        .min(1)
+        .max(8192)
+        .optional()
+        .describe("for temporary credentials (STS); signed into the URL as X-Amz-Security-Token"),
+    expiresInSeconds: z
+        .number()
+        .int()
+        .positive()
+        .max(31_536_000)
+        .optional()
+        .describe(`how long the URL works; default ${DEFAULT_EXPIRY_SECONDS}, ceiling 7 days`),
+    contentType: z
+        .string()
+        .min(1)
+        .max(256)
+        .optional()
+        .describe("PUT only: pin the upload's Content-Type. This puts content-type into SignedHeaders, so the upload MUST send exactly this value — it comes back in headers for that reason"),
+    metadata: z
+        .record(z.string())
+        .optional()
+        .describe("PUT only: user metadata, named without the x-amz-meta- prefix. Each entry becomes a signed header the upload must send verbatim"),
+    responseContentType: z
+        .string()
+        .min(1)
+        .max(256)
+        .optional()
+        .describe("GET only: the Content-Type the store should answer with"),
+    responseContentDisposition: z
+        .string()
+        .min(1)
+        .max(512)
+        .optional()
+        .describe('GET only: e.g. attachment; filename="invoice.pdf" to control the downloaded filename'),
+    responseCacheControl: z.string().min(1).max(256).optional().describe("GET only"),
+    versionId: z.string().min(1).max(1024).optional().describe("GET only: read one version"),
+    signedAt: z
+        .union([z.string(), z.number()])
+        .optional()
+        .describe("the instant to sign at, as epoch ms or ISO-8601 with an offset; defaults to now. Pass it to reproduce a URL exactly"),
+    includeCanonical: z
+        .boolean()
+        .optional()
+        .describe("include the canonical request and string-to-sign, to diff against the CanonicalRequest S3 echoes in a 403 body"),
+})
+    .strict();
+export const objectPresign = buildTool({
+    name: "ObjectPresign",
+    description: "Mint a time-limited URL that downloads or uploads one object in an S3-compatible store (AWS S3, Cloudflare R2, MinIO, anything that speaks SigV4). Use it to move a file without the bytes passing through this harness and without handing anyone a long-lived key: the URL grants one operation on one object until it expires, and nothing else. It is pure computation — HMAC-SHA256 over strings, no SDK, no network, no credential kept — so it works offline and the same inputs always produce the same URL. For an upload that pins a content type or metadata, the exact headers come back alongside the URL and MUST be sent byte-identically, or the store answers 403 long after this call succeeded. The addressing style (virtual-hosted or path) is required rather than inferred, because the two sign different requests. The secret key is used to derive the signing key and appears in no output.",
+    inputSchema,
+    readOnly: true,
+    concurrencySafe: true,
+    // No scope or ioCapability: this reaches nothing. The package's own test
+    // suite greps its source to keep that true.
+    execute: async (input) => {
+        const operation = input.operation;
+        const overrides = {
+            responseContentType: input.responseContentType,
+            responseContentDisposition: input.responseContentDisposition,
+            responseCacheControl: input.responseCacheControl,
+            versionId: input.versionId,
+        };
+        checkOperationFields(operation, {
+            contentType: input.contentType,
+            metadata: input.metadata,
+            overrides,
+        });
+        checkCredential("accessKeyId", input.accessKeyId);
+        checkCredential("secretAccessKey", input.secretAccessKey);
+        if (input.sessionToken !== undefined)
+            checkCredential("sessionToken", input.sessionToken);
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(input.region)) {
+            throw new PresignError(`region "${input.region}" is not a region name — the credential scope is case-sensitive and matched literally, so "US-East-1" signs cleanly and then fails. Regions are lowercase letters, digits and hyphens (us-east-1, eu-central-1, or auto for R2)`);
+        }
+        const expiresInSeconds = input.expiresInSeconds ?? DEFAULT_EXPIRY_SECONDS;
+        if (expiresInSeconds > MAX_EXPIRY_SECONDS) {
+            throw new PresignError(`expiresInSeconds ${expiresInSeconds} is over the 7-day (${MAX_EXPIRY_SECONDS}s) ceiling that SigV4 query authentication allows; S3 rejects a longer one outright. For standing access, hand out a short URL each time rather than one long one`);
+        }
+        const endpoint = parseEndpoint(input.endpoint);
+        const target = resolveTarget({
+            endpoint,
+            style: input.addressingStyle,
+            bucket: input.bucket,
+            key: input.key,
+        });
+        const headers = [];
+        if (input.contentType !== undefined) {
+            checkHeaderValue("contentType", input.contentType);
+            headers.push(["content-type", input.contentType]);
+        }
+        if (input.metadata !== undefined)
+            headers.push(...metadataHeaders(input.metadata));
+        // Floored to the second BEFORE anything reads it. X-Amz-Date has second
+        // resolution, so the store's clock for this URL starts at the truncated
+        // instant; reporting signedAt/expiresAt from the millisecond one would
+        // hand back a window up to a second longer than the URL actually has.
+        const epochMs = Math.floor((input.signedAt === undefined ? nowMs() : parseInstant(input.signedAt, "signedAt")) / 1000) * 1000;
+        const signed = presign({
+            method: operation === "get" ? "GET" : "PUT",
+            origin: target.origin,
+            host: target.host,
+            canonicalUri: target.canonicalUri,
+            region: input.region,
+            service: SERVICE,
+            accessKeyId: input.accessKeyId,
+            secretAccessKey: input.secretAccessKey,
+            sessionToken: input.sessionToken,
+            epochMs,
+            expiresInSeconds,
+            query: responseOverrides(overrides),
+            headers,
+        });
+        const warnings = [...target.warnings];
+        if (input.sessionToken !== undefined) {
+            warnings.push("signed with temporary credentials: the URL also stops working when the session token expires, which is often sooner than expiresAt.");
+        }
+        if (expiresInSeconds > LONG_LIVED_SECONDS) {
+            warnings.push("this URL is a bearer credential for the object for its whole lifetime — anyone who sees it in a log, a referrer header or a chat message can use it until it expires.");
+        }
+        const sendHeaders = Object.fromEntries(headers);
+        const quoted = Object.entries(sendHeaders).map(([name, value]) => `-H ${shellQuote(`${name}: ${value}`)}`);
+        // `-o <name>`: curl would otherwise write the object to stdout, and the
+        // name it would guess from a URL this long is not the object's.
+        const filename = input.key.split("/").pop();
+        const curl = operation === "get"
+            ? `curl -fSL -o ${shellQuote(filename === undefined || filename === "" ? "downloaded" : filename)} ${shellQuote(signed.url)}`
+            : ["curl -fS -X PUT --upload-file ./FILE", ...quoted, shellQuote(signed.url)].join(" ");
+        return json({
+            url: signed.url,
+            method: operation === "get" ? "GET" : "PUT",
+            headers: sendHeaders,
+            sendHeadersVerbatim: headers.length === 0
+                ? "no extra headers: everything signed is already in the URL, so the request needs nothing added. Adding a header that is not listed in signedHeaders is harmless; changing the URL is not."
+                : "send every header above exactly as written — they are inside the signature, and a client that adds a charset, changes the case of a value or drops one gets a 403 that does not mention headers.",
+            signedHeaders: signed.signedHeaders.split(";"),
+            host: target.host,
+            addressingStyle: input.addressingStyle,
+            bucket: input.bucket,
+            key: input.key,
+            region: input.region,
+            service: SERVICE,
+            payloadHash: UNSIGNED_PAYLOAD,
+            signedAt: new Date(epochMs).toISOString(),
+            expiresAt: new Date(epochMs + expiresInSeconds * 1000).toISOString(),
+            expiresInSeconds,
+            curl,
+            credentials: input.sessionToken === undefined
+                ? "the access key id is inside the URL because SigV4 puts it there; the secret key was used to derive the signing key and appears nowhere in this result"
+                : // The session token is in the URL too, and saying only that the
+                    // secret is absent reads as a full account of what is in here.
+                    // A session token is a live credential with a blast radius far
+                    // past this one object — worth naming before someone pastes the
+                    // URL into a ticket.
+                    "the access key id is inside the URL because SigV4 puts it there, and so is the session token (X-Amz-Security-Token) — SigV4 has nowhere else to carry it, and it is a live credential in its own right, so treat this URL accordingly. The secret key was used to derive the signing key and appears nowhere in this result",
+            ...(warnings.length > 0 ? { warnings } : {}),
+            ...(input.includeCanonical === true
+                ? { canonicalRequest: signed.canonicalRequest, stringToSign: signed.stringToSign }
+                : {}),
+        });
+    },
+});
+/** Every tool this package registers, in the order a catalog should list them. */
+export const OBJECTSTORE_TOOLS = Object.freeze([objectPresign]);

package/dist/lib/clock.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Time, injected.
+ *
+ * A signature is a function of the instant it was made, so `Date.now()` in
+ * the middle of this package would make every assertion about a URL a
+ * statement about the second the test ran. The seam moves that decision to
+ * the edge: tests either pass `signedAt` explicitly or drive `_setClock`, and
+ * no test here asserts a wall-clock duration.
+ *
+ * The tool's own `signedAt` field exists for the same reason a caller needs:
+ * re-minting yesterday's URL to reproduce a support report is impossible if
+ * the timestamp is whatever the process thinks now is.
+ */
+export type Clock = {
+    now(): number;
+};
+/** Test seam — `_setClock(undefined)` restores the real clock. */
+export declare function _setClock(next: Clock | undefined): void;
+export declare function nowMs(): number;
+/**
+ * Read an instant from input: epoch milliseconds, or ISO-8601 WITH an offset.
+ *
+ * An offset-less string is refused rather than read as local time. Per
+ * ECMAScript, `2026-01-01T00:00:00` means local time, so the same input would
+ * sign at two different instants on a laptop and on a CI box in UTC — and the
+ * only symptom would be a URL that is already expired, or not yet valid, on
+ * one of them.
+ */
+export declare function parseInstant(value: string | number, field: string): number;

package/dist/lib/clock.js

@@ -0,0 +1,35 @@
+const realClock = { now: () => Date.now() };
+let clock = realClock;
+/** Test seam — `_setClock(undefined)` restores the real clock. */
+export function _setClock(next) {
+    clock = next ?? realClock;
+}
+export function nowMs() {
+    return clock.now();
+}
+/**
+ * Read an instant from input: epoch milliseconds, or ISO-8601 WITH an offset.
+ *
+ * An offset-less string is refused rather than read as local time. Per
+ * ECMAScript, `2026-01-01T00:00:00` means local time, so the same input would
+ * sign at two different instants on a laptop and on a CI box in UTC — and the
+ * only symptom would be a URL that is already expired, or not yet valid, on
+ * one of them.
+ */
+export function parseInstant(value, field) {
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error(`${field} is not a finite epoch-millisecond value`);
+        }
+        return value;
+    }
+    const text = value.trim();
+    if (!/(?:Z|[+-]\d{2}:?\d{2})$/i.test(text)) {
+        throw new Error(`${field} ("${text}") has no UTC offset — write it as e.g. 2026-01-01T00:00:00Z, because an offset-less string means local time and would sign at a different instant on another machine`);
+    }
+    const parsed = Date.parse(text);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`${field} ("${text}") is not a valid ISO-8601 instant`);
+    }
+    return parsed;
+}

package/dist/lib/encode.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function encodeRfc3986(value: string): string;
+/**
+ * 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 declare function encodePath(path: string, options?: {
+    doubleEncode?: boolean;
+}): string;
+/** One query parameter, before encoding: `[name, value]`. */
+export type QueryParam = readonly [string, string];
+/**
+ * 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 declare function canonicalQuery(params: ReadonlyArray<QueryParam>): string;
+/** UTF-8 byte length — S3's key limit is 1024 BYTES, not 1024 characters. */
+export declare function utf8Length(value: string): number;