presign.ts · Source

presign.tspackages/storage/src/presign.tsraw ← src20,119 B← Back to the app
1/**
2 * @factory/storage — AWS Signature Version 4 for S3 (PURE).
3 *
4 * Implements SigV4 exactly as AWS specifies it
5 * (docs.aws.amazon.com/general/latest/gr/sigv4_signing.html):
6 *
7 *   1. canonical request  = METHOD \n canonicalURI \n canonicalQueryString
8 *                           \n canonicalHeaders \n signedHeaders \n payloadHash
9 *   2. stringToSign       = AWS4-HMAC-SHA256 \n amzDate \n scope
10 *                           \n sha256Hex(canonicalRequest)
11 *   3. signingKey         = HMAC chain: "AWS4"+secret → date → region →
12 *                           service → "aws4_request"
13 *   4. signature          = hex(HMAC_SHA256(signingKey, stringToSign))
14 *
15 * The signer is DETERMINISTIC given `now` (injected, never `new Date()`),
16 * which is what makes it unit-testable without a clock and lets the API and
17 * any future independent implementation produce byte-identical signatures.
18 *
19 * No runtime dependencies: node:crypto (sha256/hmac) only.
20 */
21 
22import { createHash, createHmac } from "node:crypto";
23 
24import type { S3Config } from "./types.js";
25 
26/** SHA-256 of bytes (or a string, UTF-8) as lowercase hex. */
27export function sha256Hex(data: Uint8Array | string): string {
28  const hash = createHash("sha256");
29  hash.update(data);
30  return hash.digest("hex");
31}
32 
33/** HMAC-SHA256 of `data` with `key`, as lowercase hex. */
34export function hmacSha256(key: string | Uint8Array, data: string | Uint8Array): string {
35  return createHmac("sha256", key).update(data).digest("hex");
36}
37 
38/** SHA-256 as raw 32 bytes (for the payload hash header). */
39export function sha256Bytes(data: Uint8Array | string): Uint8Array {
40  return new Uint8Array(createHash("sha256").update(data).digest());
41}
42 
43/** The canonical empty-body hash (AWS constant). */
44export const EMPTY_BODY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
45 
46/** AWS RFC 3986 URI encoding (more strict than encodeURIComponent: `~` and
47 *  a few chars are not escaped). */
48export function uriEncode(input: string, encodeSlash = true): string {
49  let out = "";
50  for (const ch of input) {
51    const hex = ch.codePointAt(0)!;
52    // RFC 3986 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~". These are
53    // NEVER percent-encoded (they appear raw in `X-Amz-*` query keys, the
54    // credential scope, signed-header lists, …).
55    if (
56      (hex >= 0x30 && hex <= 0x39) || // 0-9
57      (hex >= 0x41 && hex <= 0x5a) || // A-Z
58      (hex >= 0x61 && hex <= 0x7a) || // a-z
59      ch === "-" ||
60      ch === "." ||
61      ch === "_" ||
62      ch === "~"
63    ) {
64      out += ch;
65    } else if (ch === "/" && !encodeSlash) {
66      out += "/";
67    } else {
68      for (const byte of new TextEncoder().encode(ch)) {
69        out += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
70      }
71    }
72  }
73  return out;
74}
75 
76/**
77 * Encode a RAW request path (leading `/`) for use as a URL path or a SigV4
78 * canonical URI: each segment RFC 3986-encoded, `/` separators preserved.
79 *
80 * THE single source of truth for "raw path → encoded path". Both the signed
81 * canonical URI and the request URL MUST be derived from the SAME raw path
82 * with this encoding, so the wire path is byte-identical to the path the
83 * signature was computed over. Double-encoding a key containing spaces or
84 * other specials (space → `%2520`) makes S3/MinIO re-canonicalize the wire
85 * path to a different string and reject the request with
86 * `SignatureDoesNotMatch` (the `ARL Budget 208384.xlsx` 403).
87 */
88export function encodePath(path: string): string {
89  return (
90    path
91      .split("/")
92      .map((seg, i) => (i === 0 ? "" : uriEncode(seg, false)))
93      .join("/") || "/"
94  );
95}
96 
97/**
98 * Canonical query string: params sorted by (encoded key, encoded value),
99 * `key=value` joined with `&`. Both sides RFC 3986-encoded (slashes included).
100 */
101export function canonicalQuery(params: Record<string, string>): string {
102  const entries = Object.entries(params)
103    .map(([k, v]) => [uriEncode(k), uriEncode(v)] as const)
104    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
105  return entries.map(([k, v]) => `${k}=${v}`).join("&");
106}
107 
108/** ISO-8601 basic format required by SigV4: `YYYYMMDDTHHMMSSZ`. */
109export function amzDate(now: Date): string {
110  return now
111    .toISOString()
112    .replace(/[-:]/g, "")
113    .replace(/\.\d{3}/, "");
114}
115 
116/** `YYYYMMDD` (for the credential scope). */
117export function amzDateDay(now: Date): string {
118  return amzDate(now).slice(0, 8);
119}
120 
121/** Credential scope: `date/region/service/aws4_request`. */
122export function credentialScope(now: Date, region: string, service = "s3"): string {
123  return `${amzDateDay(now)}/${region}/${service}/aws4_request`;
124}
125 
126export interface SignS3RequestOptions {
127  method: string;
128  /** Object path INCLUDING the leading `/` (e.g. `/bucket/key` or `/key`). */
129  path: string;
130  /** Query params (unencoded; the signer encodes + sorts). */
131  query?: Record<string, string>;
132  /** Headers to sign — lower-cased keys (content-type, x-amz-date, …). */
133  headers: Record<string, string>;
134  /** Hex SHA-256 of the payload (EMPTY_BODY_SHA256 for zero-byte bodies). */
135  payloadHash: string;
136  config: S3Config;
137  /** Signing time — INJECTED so the signer is deterministic. */
138  now: Date;
139  /**
140   * When `true` the signer FORCES `x-amz-date` + `x-amz-content-sha256` into
141   * the signed header set (useful when the caller does not manage
142   * `x-amz-date` itself). Default `false`: the signer signs EXACTLY the
143   * header set provided — `x-amz-date` must be passed in `headers` explicitly
144   * (as {@link S3Client} does), keeping the canonical request a pure
145   * function of its inputs.
146   */
147  alwaysSignContentSha?: boolean;
148}
149 
150export interface SignedS3Request {
151  /** Final headers to send (input headers + x-amz-date + x-amz-content-sha256
152   *  + Authorization). */
153  headers: Record<string, string>;
154  /** The final `Authorization` header value. */
155  authorization: string;
156  /** Exposed for tests/auditing: the four SigV4 layers. */
157  canonicalRequest: string;
158  stringToSign: string;
159  signature: string;
160}
161 
162/**
163 * Sign an S3 REST request with SigV4 (V4 header signing, NOT query-string
164 * presigning — used by {@link S3Client} for server-side operations.
165 * Browser-usable URLs come from {@link presignPut}/{@link presignGet}).
166 */
167export function signS3Request(opts: SignS3RequestOptions): SignedS3Request {
168  const { config, now } = opts;
169  const method = opts.method.toUpperCase();
170  const query = opts.query ?? {};
171 
172  // canonical URI: the RAW path, each segment encoded, `/` preserved (a
173  // single encode — the caller passes the raw path; encoding it AGAIN here
174  // would double-encode keys with spaces/specials and mismatch the wire path).
175  const canonicalUri = encodePath(opts.path);
176 
177  const canonicalQs = canonicalQuery(query);
178  const date = amzDate(now);
179 
180  // canonical headers: sorted by lower-cased name, values trimmed.
181  // `host` is REQUIRED by S3 SigV4 (the request always carries a Host
182  // header) and is injected when the caller did not provide one.
183  // `x-amz-date` and `x-amz-content-sha256` are required on S3 authenticated
184  // (header-signed) requests. They are FORCED into the signed header set only
185  // when `alwaysSignContentSha === true`; otherwise the signer signs exactly
186  // the header set the caller provides (the default — keeps the canonical
187  // request a pure function of its inputs, which is what the exact-shape
188  // and independent-recomputation tests rely on).
189  const alwaysSign = opts.alwaysSignContentSha === true;
190  const lowerHeaders: Record<string, string> = {};
191  for (const [k, v] of Object.entries(opts.headers)) {
192    const key = k.toLowerCase();
193    lowerHeaders[key] = v.replace(/\s+/g, " ").trim();
194  }
195  if (!("host" in lowerHeaders)) {
196    lowerHeaders["host"] = requestHost(config);
197  }
198  if (alwaysSign) {
199    lowerHeaders["x-amz-date"] = date;
200    lowerHeaders["x-amz-content-sha256"] = opts.payloadHash;
201  }
202  const headerNames = Object.keys(lowerHeaders).sort();
203  const canonicalHeaders = headerNames.map((n) => `${n}:${lowerHeaders[n]}\n`).join("");
204  const signedHeaders = headerNames.join(";");
205 
206  const canonicalRequest = [
207    method,
208    canonicalUri,
209    canonicalQs,
210    canonicalHeaders,
211    signedHeaders,
212    opts.payloadHash,
213  ].join("\n");
214 
215  const scope = credentialScope(now, config.region);
216  const stringToSign = ["AWS4-HMAC-SHA256", amzDate(now), scope, sha256Hex(canonicalRequest)].join(
217    "\n",
218  );
219 
220  // Signing key derivation (the HMAC chain).
221  const kDate = createHmac("sha256", `AWS4${config.secretAccessKey}`)
222    .update(amzDateDay(now))
223    .digest();
224  const kRegion = createHmac("sha256", kDate).update(config.region).digest();
225  const kService = createHmac("sha256", kRegion).update("s3").digest();
226  const kSigning = createHmac("sha256", kService).update("aws4_request").digest();
227  const signature = createHmac("sha256", kSigning).update(stringToSign).digest("hex");
228 
229  const headers: Record<string, string> = { ...lowerHeaders };
230  headers["Authorization"] =
231    `AWS4-HMAC-SHA256 Credential=${config.accessKeyId}/${scope}, ` +
232    `SignedHeaders=${signedHeaders}, Signature=${signature}`;
233 
234  return {
235    headers,
236    authorization: headers["Authorization"]!,
237    canonicalRequest,
238    stringToSign,
239    signature,
240  };
241}
242 
243/**
244 * Absolute URL for a request against the configured endpoint. `path` is the
245 * RAW request path (leading `/`); each segment is RFC 3986-encoded once
246 * (exactly the encoding the signers use for the canonical URI — the wire
247 * path must be byte-identical to the signed path, see {@link encodePath}).
248 */
249export function buildUrl(config: S3Config, path: string, query?: Record<string, string>): string {
250  const origin = config.endpoint.replace(/\/+$/, "");
251  const qs = query && Object.keys(query).length > 0 ? `?${canonicalQuery(query)}` : "";
252  return `${origin}${encodePath(path)}${qs}`;
253}
254 
255/**
256 * Sign a request for an S3 object key, resolving path-style vs
257 * virtual-host addressing:
258 *
259 *  - `forcePathStyle` (MinIO): `https://host/<bucket>/<key>` — the canonical
260 *    URI contains the bucket.
261 *  - otherwise (AWS): `https://<bucket>.host/<key>` — the host carries the
262 *    bucket and the canonical URI does NOT (AWS SigV4 requirement).
263 */
264/**
265 * `path` is the RAW request path (no percent-encoding) — the signers
266 * ({@link signS3Request} / {@link presignRequest}) encode it ONCE for the
267 * canonical URI, and {@link buildUrl} / the virtual-host URL below encode it
268 * for the wire. Returning it pre-encoded would make the signers double-encode
269 * keys containing spaces/specials (space → `%2520`) and S3/MinIO would reject
270 * the request with `SignatureDoesNotMatch`.
271 */
272export function objectRequestParts(config: S3Config, key: string): { url: string; path: string } {
273  if (config.forcePathStyle === true) {
274    const path = `/${config.bucket}/${key}`;
275    return { url: buildUrl(config, path), path };
276  }
277  // Virtual-host: bucket becomes a subdomain of the endpoint host.
278  const origin = config.endpoint.replace(/\/+$/, "");
279  const m = /^([a-z][a-z0-9+.-]*:\/\/)([^/?#]+)(.*)$/i.exec(origin);
280  if (m) {
281    const proto = m[1]!;
282    const host = m[2]!;
283    const rest = m[3] ?? "";
284    // `encodePath("/key")` is the same single-encoded form the canonical URI
285    // uses; drop its leading `/` (the template supplies it) so the URL is
286    // `<bucket>.<host><rest>/a%20b/c.png`, not `...//a%20b/c.png`.
287    return { url: `${proto}${config.bucket}.${host}${rest}/${encodePath(`/${key}`).slice(1)}`, path: `/${key}` };
288  }
289  // Malformed endpoint — degrade to path-style (still signed consistently).
290  const path = `/${config.bucket}/${key}`;
291  return { url: buildUrl(config, path), path };
292}
293 
294const PRE_SIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
295 
296/**
297 * The value of the HTTP `Host` header a request to this config's objects
298 * actually carries — the value SigV4 MUST sign (AWS SigV4: the canonical
299 * headers always include `host`; reference: the AWS SDK / boto3 sign
300 * `host` on EVERY S3 request, presigned or header-authenticated).
301 *
302 *  - path-style:  the endpoint authority as-is (e.g. `localhost:9000`) —
303 *    the bucket rides in the path, not the host.
304 *  - virtual-host: `<bucket>.<endpoint authority>` (e.g.
305 *    `factory-files.localhost:9000`) — matching the URL the client hits.
306 */
307export function requestHost(config: S3Config): string {
308  const origin = config.endpoint.replace(/\/+$/, "");
309  const m = /^([a-z][a-z0-9+.-]*:\/\/)([^/?#]+)(.*)$/i.exec(origin);
310  if (!m) return origin;
311  const authority = m[2]!;
312  if (config.forcePathStyle === true) return authority;
313  // Virtual-host (the same rule objectRequestParts applies to the URL).
314  return `${config.bucket}.${authority}`;
315}
316 
317/**
318 * Sign a request in QUERY-STRING presigned-URL form (AWS SigV4 "Presigned
319 * Requests").
320 *
321 * Unlike {@link signS3Request} (header-signed), the credentials ride in the
322 * URL itself — `X-Amz-Algorithm`, `X-Amz-Credential`, `X-Amz-Date`,
323 * `X-Amz-Expires`, `X-Amz-SignedHeaders`, `X-Amz-Signature` — so the URL is
324 * usable by ANY HTTP client (browsers, curl, the upload worker) WITHOUT
325 * secret material on the client. The payload hash is `UNSIGNED-PAYLOAD`
326 * (presigned requests never hash the body).
327 *
328 * The signed headers are `host` (always — the request always carries a
329 * Host header and SigV4 requires it in the canonical set) plus whatever
330 * `opts.headers` contains (e.g. `content-type` for a signed PUT). `x-amz-date`
331 * is NOT a signed header in presigned form — it travels in the query string
332 * (`X-Amz-Date`), as the AWS SDK does. The canonical query string signs
333 * EVERY param including `X-Amz-Expires` — omitting any of them from the
334 * signature makes S3 reject the request.
335 */
336export function presignRequest(opts: {
337  method: string;
338  config: S3Config;
339  /** Object path INCLUDING the leading `/` (e.g. `/bucket/key`). */
340  path: string;
341  /** Headers to sign — lower-cased keys (content-type, x-amz-date, …). */
342  headers: Record<string, string>;
343  /** Lifetime of the signed URL, seconds. */
344  expiresSec: number;
345  /** INJECTED clock — determinism. */
346  now: Date;
347  /** Extra query params to include in the signed URL (e.g.
348   *  `response-content-disposition` for downloads). */
349  extraQuery?: Record<string, string> | undefined;
350}): {
351  url: string;
352  /**
353   * The EXACT client headers to send — the caller-provided headers with
354   * `host` and `x-amz-date` REMOVED (the HTTP client sets `host` from the URL;
355   * `x-amz-date` travels in the query string). Empty for a plain GET,
356   * `{ "content-type": … }` for a signed PUT.
357   */
358  headers: Record<string, string>;
359  method: string;
360  expiresInSec: number;
361} {
362  const { config, now, expiresSec } = opts;
363  const method = opts.method.toUpperCase();
364  const date = amzDate(now);
365 
366  const lowerHeaders: Record<string, string> = {};
367  for (const [k, v] of Object.entries(opts.headers)) {
368    lowerHeaders[k.toLowerCase()] = v.replace(/\s+/g, " ").trim();
369  }
370  // `host` is ALWAYS signed (the request always carries a Host header);
371  // `x-amz-date` is NOT a signed header in presigned form — it is a query
372  // param (X-Amz-Date), exactly as the AWS SDK does it.
373  lowerHeaders["host"] = requestHost(config);
374  const signedHeaderNames = Object.keys(lowerHeaders).sort();
375  const signedHeaders = signedHeaderNames.join(";");
376 
377  const query: Record<string, string> = {
378    "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
379    "X-Amz-Credential": `${config.accessKeyId}/${credentialScope(now, config.region)}`,
380    "X-Amz-Date": date,
381    "X-Amz-Expires": String(expiresSec),
382    "X-Amz-SignedHeaders": signedHeaders,
383    ...(opts.extraQuery ?? {}),
384  };
385 
386  const canonicalUri = encodePath(opts.path);
387  const canonicalQs = canonicalQuery(query);
388  const canonicalHeaders = signedHeaderNames.map((n) => `${n}:${lowerHeaders[n]}\n`).join("");
389  const canonicalRequest = [
390    method,
391    canonicalUri,
392    canonicalQs,
393    canonicalHeaders,
394    signedHeaders,
395    PRE_SIGNED_PAYLOAD,
396  ].join("\n");
397 
398  const stringToSign = [
399    "AWS4-HMAC-SHA256",
400    date,
401    credentialScope(now, config.region),
402    sha256Hex(canonicalRequest),
403  ].join("\n");
404 
405  const kDate = createHmac("sha256", `AWS4${config.secretAccessKey}`)
406    .update(amzDateDay(now))
407    .digest();
408  const kRegion = createHmac("sha256", kDate).update(config.region).digest();
409  const kService = createHmac("sha256", kRegion).update("s3").digest();
410  const kSigning = createHmac("sha256", kService).update("aws4_request").digest();
411  const signature = createHmac("sha256", kSigning).update(stringToSign).digest("hex");
412 
413  query["X-Amz-Signature"] = signature;
414 
415  // The URL carries EXACTLY the canonical query string the signature was
416  // computed over (strict RFC 3986 — `/` → %2F in the credential scope, etc).
417  // This mirrors the AWS SDK's presigned-URL output and is byte-identical to
418  // what S3/MinIO re-canonicalize when verifying.
419  const urlQuery = canonicalQuery(query);
420  const origin = config.endpoint.replace(/\/+$/, "");
421 
422  // Client headers WITHOUT `host` (the HTTP client sets it automatically
423  // from the URL — it is a forbidden/managed header in browsers and Node)
424  // and WITHOUT `x-amz-date` (it is a query param here).
425  const { "x-amz-date": _omitDate, host: _omitHost, ...clientHeaders } = lowerHeaders;
426  void _omitDate;
427  void _omitHost;
428 
429  return {
430    // The URL path is the SAME encoded form the signature was computed over
431    // (the raw path, encoded once) — so the wire path is byte-identical to
432    // the canonical URI and S3/MinIO accept the signature.
433    url: `${origin}${encodePath(opts.path)}?${urlQuery}`,
434    headers: clientHeaders,
435    method,
436    expiresInSec: expiresSec,
437  };
438}
439 
440export interface PresignPutOptions {
441  config: S3Config;
442  key: string;
443  /** Content-Type of the upload — MUST be sent by the uploader (signed). */
444  contentType: string;
445  /** Lifetime of the signed URL, seconds. */
446  expiresSec: number;
447  /** INJECTED clock — determinism. */
448  now: Date;
449}
450 
451/**
452 * Presign a PUT as a browser-usable QUERY-STRING signed URL (the two-phase
453 * upload start, ARCHITECTURE.md §8 / TASK-0101 §3).
454 *
455 * The URL carries the whole credential set; the client sends the body with
456 * EXACTLY the returned headers (content-type is signed, so a wrong
457 * Content-Type fails the signature check). Payload: `UNSIGNED-PAYLOAD`.
458 */
459export function presignPut(opts: PresignPutOptions): {
460  url: string;
461  headers: Record<string, string>;
462  method: "PUT";
463  expiresInSec: number;
464} {
465  const { config, key, contentType, expiresSec, now } = opts;
466  const { path } = objectRequestParts(config, key);
467  const signed = presignRequest({
468    method: "PUT",
469    path,
470    headers: { "content-type": contentType },
471    expiresSec,
472    now,
473    config,
474  });
475  return { ...signed, method: "PUT" };
476}
477 
478/**
479 * Presign a GET as a browser-usable QUERY-STRING signed URL — the
480 * short-lived download URL (private buckets, ARCHITECTURE.md §8 /
481 * TASK-0101 §5). No client headers required; an optional
482 * `response-content-disposition` is passed through as a SIGNED query param
483 * so the download filename is part of the signature (key + disposition
484 * binding).
485 */
486export function presignGet(opts: {
487  config: S3Config;
488  key: string;
489  expiresSec: number;
490  now: Date;
491  /** Optional signed response override (e.g. `attachment; filename="a b.png"`). */
492  responseContentDisposition?: string;
493}): { url: string; headers: Record<string, string>; method: "GET"; expiresInSec: number } {
494  const { config, key, expiresSec, now, responseContentDisposition } = opts;
495  const { path } = objectRequestParts(config, key);
496  const extraQuery: Record<string, string> = {};
497  if (responseContentDisposition) {
498    extraQuery["response-content-disposition"] = responseContentDisposition;
499  }
500  const signed = presignRequest({
501    method: "GET",
502    path,
503    headers: {},
504    expiresSec,
505    now,
506    config,
507    extraQuery: Object.keys(extraQuery).length > 0 ? extraQuery : undefined,
508  });
509  return { ...signed, method: "GET" };
510}
511