sigflint 1.0.1 → 1.0.2

package/src/bun.js

@@ -10,15 +10,26 @@ import { createEventSigner } from './events.js';
 const bun = /** @type {any} */ (globalThis).Bun;
 
 // the HMAC state for the signing key in use is built once and cloned for each signature
+/** @type {Uint8Array | undefined} */
 let baseKey;
+/** @type {any} */
 let base;
 
+/**
+ * @param {string | Uint8Array} key
+ * @param {string} data
+ */
 const hmac = (key, data) => crypto.createHmac('sha256', key).update(data).digest();
 const getSigningKey = /* @__PURE__ */ createKeys(hmac);
+/** @param {string | Uint8Array} data */
 const hexHash = (data) => bun.SHA256.hash(data, 'hex');
 const primitives = {
   hexHash,
   hmac,
+  /**
+   * @param {Uint8Array} key
+   * @param {string} data
+   */
   hmacHex: (key, data) => {
     if (key !== baseKey) {
       baseKey = key;

package/src/chunks.js

@@ -4,39 +4,69 @@ import { emptyBodyHash as emptyHash } from './base.js';
 
 export const utf8 = /* @__PURE__ */ new TextEncoder();
 
-/** The seed signature, timestamp and scope of a signed request, from the headers getAuthHeaders returned. */
+/**
+ * The seed signature, timestamp and scope of a signed request, from the headers getAuthHeaders returned.
+ * @param {import('./base.js').AuthHeaders} authHeaders
+ */
 export function seedOf(authHeaders) {
   const auth = authHeaders.authorization;
-  if (typeof auth !== 'string' || !auth.startsWith('AWS4-HMAC-SHA256 '))
-    throw new TypeError('authHeaders must be the headers getAuthHeaders returned (a SigV4a signature cannot start a chunk or event stream)');
+  if (typeof auth !== 'string' || !auth.startsWith('AWS4-HMAC-SHA256 ')) {
+    throw new TypeError(
+      'authHeaders must be the headers getAuthHeaders returned (a SigV4a signature cannot start a chunk or event stream)',
+    );
+  }
   const scope = auth.slice(auth.indexOf('Credential=') + 11, auth.indexOf(',')).split('/'); // access key, date, region, service, aws4_request
   return {
     signature: auth.slice(auth.lastIndexOf('Signature=') + 10),
-    datetime: authHeaders['x-amz-date'],
-    date: scope[1],
-    region: scope[2],
-    service: scope[3],
+    datetime: /** @type {string} */ (authHeaders['x-amz-date']),
+    date: /** @type {string} */ (scope[1]),
+    region: /** @type {string} */ (scope[2]),
+    service: /** @type {string} */ (scope[3]),
     scope: scope.slice(1).join('/'),
   };
 }
 
-export const chunkStringToSign = (datetime, scope, previous, payloadHash) => `AWS4-HMAC-SHA256-PAYLOAD\n${datetime}\n${scope}\n${previous}\n${emptyHash}\n${payloadHash}`;
-export const trailerStringToSign = (datetime, scope, previous, trailerHash) => `AWS4-HMAC-SHA256-TRAILER\n${datetime}\n${scope}\n${previous}\n${trailerHash}`;
+/**
+ * @param {string} datetime
+ * @param {string} scope
+ * @param {string} previous
+ * @param {string} payloadHash
+ */
+export const chunkStringToSign = (datetime, scope, previous, payloadHash) =>
+  `AWS4-HMAC-SHA256-PAYLOAD\n${datetime}\n${scope}\n${previous}\n${emptyHash}\n${payloadHash}`;
+/**
+ * @param {string} datetime
+ * @param {string} scope
+ * @param {string} previous
+ * @param {string} trailerHash
+ */
+export const trailerStringToSign = (datetime, scope, previous, trailerHash) =>
+  `AWS4-HMAC-SHA256-TRAILER\n${datetime}\n${scope}\n${previous}\n${trailerHash}`;
 
-/** Trailing headers in canonical form: lowercase names in name order, each line ending in a newline. A line break in a name or value would start another trailer line, so it throws. */
+/** Trailing headers in canonical form: lowercase names in name order, each line ending in a newline. A line break in a name or value would start another trailer line, so it throws.
+ * @param {Record<string, string>} trailers
+ */
 export function canonicalTrailers(trailers) {
   return Object.keys(trailers)
-    .map((name) => {
-      const value = String(trailers[name]);
-      if (/[\r\n]/.test(name) || /[\r\n]/.test(value)) throw new TypeError('a trailer name or value cannot hold a line break');
-      return [name.toLowerCase(), value.trim()];
-    })
+    .map(
+      /** @returns {[string, string]} */ (name) => {
+        const value = String(trailers[name]);
+        if (/[\r\n]/.test(name) || /[\r\n]/.test(value)) {
+          throw new TypeError('a trailer name or value cannot hold a line break');
+        }
+        return [name.toLowerCase(), value.trim()];
+      },
+    )
     .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
     .map(([name, value]) => `${name}:${value}\n`)
     .join('');
 }
 
-/** The bytes of one chunk on the wire: size in hex, signature, the data. */
+/**
+ * The bytes of one chunk on the wire: size in hex, signature, the data.
+ * @param {string} signature
+ * @param {Uint8Array} data
+ */
 export function frameChunk(signature, data) {
   const head = utf8.encode(`${data.length.toString(16)};chunk-signature=${signature}\r\n`);
   const out = new Uint8Array(head.length + data.length + 2);
@@ -47,7 +77,12 @@ export function frameChunk(signature, data) {
   return out;
 }
 
-/** The last chunk (no data), with the signed trailing headers when there are any. */
+/**
+ * The last chunk (no data), with the signed trailing headers when there are any.
+ * @param {string} signature
+ * @param {string} [trailers] - canonical trailing headers
+ * @param {string} [trailerSignature]
+ */
 export function frameEnd(signature, trailers, trailerSignature) {
   return utf8.encode(
     trailers === undefined
@@ -71,14 +106,24 @@ export function createChunkSigner({ hexHash, hmacHex, getSigningKey }) {
     const seed = seedOf(authHeaders);
     const key = getSigningKey(credentials.secretAccessKey, seed.date, seed.region, seed.service);
     let previous = seed.signature;
-    const sign = (data) => (previous = hmacHex(key, chunkStringToSign(seed.datetime, seed.scope, previous, hexHash(data))));
+    /** @param {Uint8Array} data */
+    const sign = (data) =>
+      (previous = hmacHex(
+        key,
+        chunkStringToSign(seed.datetime, seed.scope, previous, hexHash(data)),
+      ));
     return {
       chunk: (data) => (data.length === 0 ? data : frameChunk(sign(data), data)), // a zero-length chunk would end the upload; it is not sent
       end(trailers) {
         const text = trailers === undefined ? undefined : canonicalTrailers(trailers); // before sign(), so a refused trailer leaves the chain where it was
         const signature = sign(new Uint8Array(0));
-        if (text === undefined) return frameEnd(signature);
-        const trailerSignature = hmacHex(key, trailerStringToSign(seed.datetime, seed.scope, signature, hexHash(text)));
+        if (text === undefined) {
+          return frameEnd(signature);
+        }
+        const trailerSignature = hmacHex(
+          key,
+          trailerStringToSign(seed.datetime, seed.scope, signature, hexHash(text)),
+        );
         return frameEnd(signature, text, trailerSignature);
       },
     };

package/src/ecdsa-node.js

@@ -1,14 +1,29 @@
 // SigV4a's ECDSA P-256 for the entries that have node:crypto (Node, Deno, Bun). The key is rebuilt from the derived scalar; ECDH supplies the public point that a JWK needs.
 import crypto from 'node:crypto';
 
+/** @param {Uint8Array} bytes */
 const b64url = (bytes) => Buffer.from(bytes).toString('base64url');
 
 export const ecdsa = {
+  /** @param {Uint8Array} d */
   key(d) {
     const ecdh = crypto.createECDH('prime256v1');
     ecdh.setPrivateKey(d);
     const point = ecdh.getPublicKey();
-    return crypto.createPrivateKey({ key: { kty: 'EC', crv: 'P-256', d: b64url(d), x: b64url(point.subarray(1, 33)), y: b64url(point.subarray(33)) }, format: 'jwk' });
+    return crypto.createPrivateKey({
+      key: {
+        kty: 'EC',
+        crv: 'P-256',
+        d: b64url(d),
+        x: b64url(point.subarray(1, 33)),
+        y: b64url(point.subarray(33)),
+      },
+      format: 'jwk',
+    });
   },
+  /**
+   * @param {crypto.KeyObject} key
+   * @param {string} text
+   */
   sign: (key, text) => crypto.sign('sha256', text, { key, dsaEncoding: 'der' }).toString('hex'),
 };

package/src/events.js

@@ -2,22 +2,37 @@
 import { amzDatetime } from './base.js';
 import { seedOf, utf8 } from './chunks.js';
 
+/** @type {Int32Array | undefined} */
 let crcTable;
+/**
+ * @param {Uint8Array} bytes
+ * @param {number} start
+ * @param {number} end
+ */
 function crc32(bytes, start, end) {
   if (crcTable === undefined) {
     crcTable = new Int32Array(256);
     for (let n = 0; n < 256; n++) {
       let c = n;
-      for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+      for (let k = 0; k < 8; k++) {
+        c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+      }
       crcTable[n] = c;
     }
   }
   let crc = -1;
-  for (let i = start; i < end; i++) crc = crcTable[(crc ^ bytes[i]) & 255] ^ (crc >>> 8);
+  for (let i = start; i < end; i++) {
+    crc =
+      /** @type {number} */ (crcTable[(crc ^ /** @type {number} */ (bytes[i])) & 255]) ^
+      (crc >>> 8);
+  }
   return ~crc >>> 0;
 }
 
-/** The :date header of an event: name, type 8 (timestamp), milliseconds since the epoch as 8 bytes. */
+/**
+ * The :date header of an event: name, type 8 (timestamp), milliseconds since the epoch as 8 bytes.
+ * @param {number} ms
+ */
 export function dateHeader(ms) {
   const out = new Uint8Array(15);
   out[0] = 5;
@@ -27,7 +42,12 @@ export function dateHeader(ms) {
   return out;
 }
 
-/** The signed event: prelude, the :date and :chunk-signature headers, the inner message as payload, checksums. */
+/**
+ * The signed event: prelude, the :date and :chunk-signature headers, the inner message as payload, checksums.
+ * @param {Uint8Array} dateBytes
+ * @param {string} signatureHex
+ * @param {Uint8Array} inner
+ */
 export function frameEvent(dateBytes, signatureHex, inner) {
   const headersLength = dateBytes.length + 52;
   const out = new Uint8Array(16 + headersLength + inner.length);
@@ -43,18 +63,36 @@ export function frameEvent(dateBytes, signatureHex, inner) {
   out[at++] = 6;
   view.setUint16(at, 32);
   at += 2;
-  for (let i = 0; i < 32; i++) out[at + i] = parseInt(signatureHex.slice(2 * i, 2 * i + 2), 16);
+  for (let i = 0; i < 32; i++) {
+    out[at + i] = parseInt(signatureHex.slice(2 * i, 2 * i + 2), 16);
+  }
   at += 32;
   out.set(inner, at);
   view.setUint32(out.length - 4, crc32(out, 0, out.length - 4));
   return out;
 }
 
+/**
+ * @param {string} datetime
+ * @param {string} scope
+ * @param {string} previous
+ * @param {string} headersHash
+ * @param {string} payloadHash
+ */
 export const eventStringToSign = (datetime, scope, previous, headersHash, payloadHash) =>
   `AWS4-HMAC-SHA256-PAYLOAD\n${datetime}\n${scope}\n${previous}\n${headersHash}\n${payloadHash}`;
+/**
+ * @param {number} ms
+ * @param {string} region
+ * @param {string} service
+ */
 export const eventScope = (ms, region, service) => {
   const datetime = amzDatetime(ms);
-  return { datetime, scope: `${datetime.slice(0, 8)}/${region}/${service}/aws4_request`, date: datetime.slice(0, 8) };
+  return {
+    datetime,
+    scope: `${datetime.slice(0, 8)}/${region}/${service}/aws4_request`,
+    date: datetime.slice(0, 8),
+  };
 };
 
 /**

package/src/node.js

@@ -12,33 +12,51 @@ const maxData = 1024;
 const inner = /* @__PURE__ */ new Uint8Array(64 + maxData); // the ipad block, then the data
 const outer = /* @__PURE__ */ new Uint8Array(64 + 32); // the opad block, then the inner digest
 const data = /* @__PURE__ */ inner.subarray(64);
+/** @type {Uint8Array[]} */
 const innerViews = [];
+/** @type {Uint8Array | undefined} */
 let blockKey;
+/** @param {number} c */
 const nibble = (c) => (c > 96 ? c - 87 : c - 48);
 
 // HMAC-SHA-256 as two one-shot hashes over preallocated buffers: it avoids creating a Hmac object per signature.
 // Only a key of at most 64 bytes is handled; the signing key is always 32 bytes.
+/**
+ * @param {Uint8Array} key
+ * @param {string} text
+ */
 function hmacHexOneShot(key, text) {
   if (key !== blockKey) {
     blockKey = key;
     inner.fill(0x36, 0, 64);
     outer.fill(0x5c, 0, 64);
     for (let i = 0; i < key.length; i++) {
-      inner[i] ^= key[i];
-      outer[i] ^= key[i];
+      inner[i] = /** @type {number} */ (inner[i]) ^ /** @type {number} */ (key[i]);
+      outer[i] = /** @type {number} */ (outer[i]) ^ /** @type {number} */ (key[i]);
     }
   }
   const end = 64 + utf8.encodeInto(text, data).written;
   const hex = crypto.hash('sha256', (innerViews[end] ??= inner.subarray(0, end)), 'hex');
-  for (let i = 0; i < 32; i++) outer[64 + i] = (nibble(hex.charCodeAt(2 * i)) << 4) | nibble(hex.charCodeAt(2 * i + 1));
+  for (let i = 0; i < 32; i++) {
+    outer[64 + i] = (nibble(hex.charCodeAt(2 * i)) << 4) | nibble(hex.charCodeAt(2 * i + 1));
+  }
   return crypto.hash('sha256', outer, 'hex');
 }
 
+/**
+ * @param {Uint8Array} key
+ * @param {string} text
+ */
 const hmacHexStreaming = (key, text) => crypto.createHmac('sha256', key).update(text).digest('hex');
 
+/**
+ * @param {string | Uint8Array} key
+ * @param {string} text
+ */
 const hmac = (key, text) => crypto.createHmac('sha256', key).update(text).digest();
 
 // The one-shot form is used only when it agrees with the streaming one on a sample, and only for short data. The sample is checked on first use.
+/** @type {boolean | undefined} */
 let oneShotWorks;
 function probe() {
   const key = hmac('probe', 'key');
@@ -47,9 +65,17 @@ function probe() {
   blockKey = undefined;
   return works;
 }
-const hmacHex = (key, text) => ((oneShotWorks ??= probe()) && text.length * 3 <= maxData && key.length <= 64 ? hmacHexOneShot(key, text) : hmacHexStreaming(key, text));
+/**
+ * @param {Uint8Array} key
+ * @param {string} text
+ */
+const hmacHex = (key, text) =>
+  (oneShotWorks ??= probe()) && text.length * 3 <= maxData && key.length <= 64
+    ? hmacHexOneShot(key, text)
+    : hmacHexStreaming(key, text);
 
 const getSigningKey = /* @__PURE__ */ createKeys(hmac);
+/** @param {string | Uint8Array} text */
 const hexHash = (text) => crypto.hash('sha256', text, 'hex');
 const primitives = { hexHash, hmac, hmacHex, getSigningKey };
 

package/src/presign.js

@@ -1,19 +1,48 @@
 // Presigned URLs: the signature goes in the query string instead of the authorization header.
-import { symmetric, canonicalPath, canonicalQuery, insert, headerValue, signHeaderName, amzDatetime, payloadHashOf, stringToSign } from './base.js';
+import {
+  symmetric,
+  canonicalPath,
+  canonicalQuery,
+  insert,
+  headerValue,
+  signHeaderName,
+  amzDatetime,
+  payloadHashOf,
+  stringToSign,
+} from './base.js';
 
-export const encodeQueryPart = (text) => encodeURIComponent(text).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
+/** @param {string} text */
+export const encodeQueryPart = (text) =>
+  encodeURIComponent(text).replace(
+    /[!'()*]/g,
+    (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase(),
+  );
 
 /**
  * Everything up to the hashing for a presigned URL. `request.expires` is the lifetime in seconds (default 3600). Only the host and request.signHeaders are
  * signed; S3 URLs are always UNSIGNED-PAYLOAD, other services sign the body hash. `extra` is appended to the authentication parameters.
+ * @param {import('./base.js').SignRequest} request
+ * @param {import('./base.js').Credentials} credentials
+ * @param {string} payloadHash
+ * @param {import('./base.js').Scheme} [scheme]
+ * @param {string} [extra]
  */
 export function preparePresign(request, credentials, payloadHash, scheme = symmetric, extra = '') {
   const { url, signHeaders } = request;
   const method = request.method.toUpperCase();
-  if (url.protocol !== 'https:' && url.protocol !== 'http:') throw new TypeError('presign needs an http or https URL');
-  if (url.search.length > 1 && (url.search.includes('X-Amz-Signature=') || url.search.includes('X-Amz-Algorithm='))) throw new TypeError('the URL is already presigned');
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new TypeError('presign needs an http or https URL');
+  }
+  if (
+    url.search.length > 1 &&
+    (url.search.includes('X-Amz-Signature=') || url.search.includes('X-Amz-Algorithm='))
+  ) {
+    throw new TypeError('the URL is already presigned');
+  }
   const expires = request.expires ?? 3600;
-  if (!Number.isInteger(expires) || expires < 1 || expires > 604800) throw new RangeError('expires must be a whole number of seconds from 1 to 604800 (7 days)');
+  if (!Number.isInteger(expires) || expires < 1 || expires > 604800) {
+    throw new RangeError('expires must be a whole number of seconds from 1 to 604800 (7 days)');
+  }
   const region = request.region ?? '';
   const service = request.service ?? 's3';
   const datetime = amzDatetime(request.now ?? Date.now());
@@ -21,21 +50,50 @@ export function preparePresign(request, credentials, payloadHash, scheme = symme
   const credentialScope = scheme.scope(date, region, service);
   const names = ['host'];
   const values = [url.host];
-  if (signHeaders !== undefined) for (const name of Object.keys(signHeaders)) insert(names, values, signHeaderName(name, signHeaders[name]), headerValue(signHeaders[name]));
+  if (signHeaders !== undefined) {
+    for (const name of Object.keys(signHeaders)) {
+      insert(
+        names,
+        values,
+        signHeaderName(name, /** @type {string} */ (signHeaders[name])),
+        headerValue(signHeaders[name]),
+      );
+    }
+  }
   let canonicalHeaders = '';
-  for (let i = 0; i < names.length; i++) canonicalHeaders += `${names[i]}:${values[i]}\n`;
+  for (let i = 0; i < names.length; i++) {
+    canonicalHeaders += `${names[i]}:${values[i]}\n`;
+  }
   const signedHeaders = names.join(';');
   let auth = `X-Amz-Algorithm=${scheme.algorithm}&X-Amz-Credential=${encodeQueryPart(`${credentials.accessKeyId}/${credentialScope}`)}&X-Amz-Date=${datetime}&X-Amz-Expires=${expires}&X-Amz-SignedHeaders=${encodeQueryPart(signedHeaders)}`;
-  if (credentials.sessionToken) auth += `&X-Amz-Security-Token=${encodeQueryPart(credentials.sessionToken)}`;
+  if (credentials.sessionToken) {
+    auth += `&X-Amz-Security-Token=${encodeQueryPart(credentials.sessionToken)}`;
+  }
   auth += extra;
   const query = url.search.length > 1 ? url.search + '&' + auth : '?' + auth;
   const hash = service === 's3' || request.unsignedPayload ? 'UNSIGNED-PAYLOAD' : payloadHash;
   const canonicalRequest = `${method}\n${canonicalPath(service, url.pathname)}\n${canonicalQuery(query)}\n${canonicalHeaders}\n${signedHeaders}\n${hash}`;
-  return { canonicalRequest, datetime, date, region, service, credentialScope, signedHeaders, algorithm: scheme.algorithm, base: url.origin + url.pathname, query };
+  return {
+    canonicalRequest,
+    datetime,
+    date,
+    region,
+    service,
+    credentialScope,
+    signedHeaders,
+    algorithm: scheme.algorithm,
+    base: url.origin + url.pathname,
+    query,
+  };
 }
 
-/** The URL to hand out: the original URL with the authentication query parameters and the signature appended. */
-export const presignedUrl = (prepared, signature) => `${prepared.base}${prepared.query}&X-Amz-Signature=${signature}`;
+/**
+ * The URL to hand out: the original URL with the authentication query parameters and the signature appended.
+ * @param {{ base: string, query: string }} prepared
+ * @param {string} signature
+ */
+export const presignedUrl = (prepared, signature) =>
+  `${prepared.base}${prepared.query}&X-Amz-Signature=${signature}`;
 
 /**
  * @param {import('./base.js').Primitives} primitives
@@ -46,7 +104,15 @@ export function createPresigner({ hexHash, hmacHex, getSigningKey }) {
     const prepared = preparePresign(request, credentials, payloadHashOf(request, hexHash));
     return presignedUrl(
       prepared,
-      hmacHex(getSigningKey(credentials.secretAccessKey, prepared.date, prepared.region, prepared.service), stringToSign(prepared, hexHash(prepared.canonicalRequest))),
+      hmacHex(
+        getSigningKey(
+          credentials.secretAccessKey,
+          prepared.date,
+          prepared.region,
+          prepared.service,
+        ),
+        stringToSign(prepared, hexHash(prepared.canonicalRequest)),
+      ),
     );
   };
 }

package/src/v4a.js

@@ -3,60 +3,112 @@
 import { prepare, payloadHashOf, stringToSign, authorize } from './base.js';
 import { preparePresign, presignedUrl, encodeQueryPart } from './presign.js';
 
-export const asymmetric = { algorithm: 'AWS4-ECDSA-P256-SHA256', scope: (date, _region, service) => `${date}/${service}/aws4_request` };
+/** @type {import('./base.js').Scheme} */
+export const asymmetric = {
+  algorithm: 'AWS4-ECDSA-P256-SHA256',
+  scope: (date, _region, service) => `${date}/${service}/aws4_request`,
+};
 
+/** @param {import('./base.js').SignRequest} request */
 function regionSetOf(request) {
   const regionSet = request.regionSet;
-  if (typeof regionSet !== 'string' || regionSet === '') throw new TypeError("SigV4a needs request.regionSet, for example 'us-east-1,us-west-2' or '*'");
+  if (typeof regionSet !== 'string' || regionSet === '') {
+    throw new TypeError("SigV4a needs request.regionSet, for example 'us-east-1,us-west-2' or '*'");
+  }
   return regionSet;
 }
 
-/** The request with the region set added as a signed header; `regionSet` is 'us-east-1,us-west-2' or '*'. */
-export const withRegionSet = (request) => ({ ...request, signHeaders: { ...request.signHeaders, 'x-amz-region-set': regionSetOf(request) } });
+/**
+ * The request with the region set added as a signed header; `regionSet` is 'us-east-1,us-west-2' or '*'.
+ * @param {import('./base.js').SignRequest} request
+ */
+export const withRegionSet = (request) => ({
+  ...request,
+  signHeaders: { ...request.signHeaders, 'x-amz-region-set': regionSetOf(request) },
+});
 
-export const regionSetQuery = (request) => `&X-Amz-Region-Set=${encodeQueryPart(regionSetOf(request))}`;
+/** @param {import('./base.js').SignRequest} request */
+export const regionSetQuery = (request) =>
+  `&X-Amz-Region-Set=${encodeQueryPart(regionSetOf(request))}`;
 
 // 4-byte counter 1, label, 0x00, the access key id, the external counter, 256 as 4 bytes
-export const kdfInput = (accessKeyId, counter) => `\0\0\0\x01AWS4-ECDSA-P256-SHA256\0${accessKeyId}${String.fromCharCode(counter)}\0\0\x01\0`;
+/**
+ * @param {string} accessKeyId
+ * @param {number} counter
+ */
+export const kdfInput = (accessKeyId, counter) =>
+  `\0\0\0\x01AWS4-ECDSA-P256-SHA256\0${accessKeyId}${String.fromCharCode(counter)}\0\0\x01\0`;
 
-/** The private scalar (HMAC output + 1) when the HMAC output is at most the curve order minus 2, else undefined. */
+/**
+ * The private scalar (HMAC output + 1) when the HMAC output is at most the curve order minus 2, else undefined.
+ * @param {Uint8Array} k
+ */
 export function scalarFrom(k) {
   const nMinusTwo = 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc63254fn;
   let c = 0n;
-  for (let i = 0; i < 32; i++) c = (c << 8n) | BigInt(k[i]);
-  if (c > nMinusTwo) return undefined;
+  for (let i = 0; i < 32; i++) {
+    c = (c << 8n) | BigInt(/** @type {number} */ (k[i]));
+  }
+  if (c > nMinusTwo) {
+    return undefined;
+  }
   c += 1n;
   const d = new Uint8Array(32);
-  for (let i = 31; i >= 0; i--, c >>= 8n) d[i] = Number(c & 0xffn);
+  for (let i = 31; i >= 0; i--, c >>= 8n) {
+    d[i] = Number(c & 0xffn);
+  }
   return d;
 }
 
-/** The SigV4a private key: the P-256 scalar derived from the secret key by the counter-mode HMAC construction in the AWS documentation (32 bytes, big-endian). */
+/** The SigV4a private key: the P-256 scalar derived from the secret key by the counter-mode HMAC construction in the AWS documentation (32 bytes, big-endian).
+ * @param {AsymmetricPrimitives['hmac']} hmac
+ * @param {string} accessKeyId
+ * @param {string} secretAccessKey
+ */
 export function deriveP256(hmac, accessKeyId, secretAccessKey) {
   for (let counter = 1; counter < 128; counter++) {
     const d = scalarFrom(hmac('AWS4A' + secretAccessKey, kdfInput(accessKeyId, counter)));
-    if (d !== undefined) return d;
+    if (d !== undefined) {
+      return d;
+    }
   }
   throw new Error('no SigV4a key for these credentials');
 }
 
+/** @type {WeakMap<AsymmetricPrimitives['ecdsa'], (credentials: import('./base.js').Credentials, text: string) => string>} */
 const signers = /* @__PURE__ */ new WeakMap(); // ecdsa -> its signer, so the header and presign functions of one entry share one key cache
 
-/** A signer from the string to sign to a hex DER ECDSA signature, with a cache of the keys built from credentials. Asking again for the same `ecdsa` returns the same signer. */
+/** A signer from the string to sign to a hex DER ECDSA signature, with a cache of the keys built from credentials. Asking again for the same `ecdsa` returns the same signer.
+ * @param {AsymmetricPrimitives['hmac']} hmac
+ * @param {AsymmetricPrimitives['ecdsa']} ecdsa
+ */
 export function createAsymmetric(hmac, ecdsa) {
   let sign = signers.get(ecdsa);
-  if (sign === undefined) signers.set(ecdsa, (sign = signerFor(hmac, ecdsa)));
+  if (sign === undefined) {
+    signers.set(ecdsa, (sign = signerFor(hmac, ecdsa)));
+  }
   return sign;
 }
 
+/**
+ * @param {AsymmetricPrimitives['hmac']} hmac
+ * @param {AsymmetricPrimitives['ecdsa']} ecdsa
+ */
 function signerFor(hmac, ecdsa) {
+  /** @type {Map<string, unknown>} */
   const keys = new Map();
+  /**
+   * @param {import('./base.js').Credentials} credentials
+   * @param {string} text
+   */
   return function sign(credentials, text) {
     const id = `${credentials.accessKeyId}/${credentials.secretAccessKey}`;
     let key = keys.get(id);
     if (key === undefined) {
       key = ecdsa.key(deriveP256(hmac, credentials.accessKeyId, credentials.secretAccessKey));
-      if (keys.size >= 1000) keys.delete(keys.keys().next().value);
+      if (keys.size >= 1000) {
+        keys.delete(/** @type {string} */ (keys.keys().next().value));
+      }
       keys.set(id, key);
     }
     return ecdsa.sign(key, text);
@@ -78,8 +130,17 @@ function signerFor(hmac, ecdsa) {
 export function createSignerV4a({ hexHash, hmac, ecdsa }) {
   const sign = createAsymmetric(hmac, ecdsa);
   return function getAuthHeadersV4a(request, credentials) {
-    const prepared = prepare(withRegionSet(request), credentials, payloadHashOf(request, hexHash), asymmetric);
-    return authorize(prepared, credentials.accessKeyId, sign(credentials, stringToSign(prepared, hexHash(prepared.canonicalRequest))));
+    const prepared = prepare(
+      withRegionSet(request),
+      credentials,
+      payloadHashOf(request, hexHash),
+      asymmetric,
+    );
+    return authorize(
+      prepared,
+      credentials.accessKeyId,
+      sign(credentials, stringToSign(prepared, hexHash(prepared.canonicalRequest))),
+    );
   };
 }
 
@@ -90,7 +151,16 @@ export function createSignerV4a({ hexHash, hmac, ecdsa }) {
 export function createPresignerV4a({ hexHash, hmac, ecdsa }) {
   const sign = createAsymmetric(hmac, ecdsa);
   return function presignV4a(request, credentials) {
-    const prepared = preparePresign(request, credentials, payloadHashOf(request, hexHash), asymmetric, regionSetQuery(request));
-    return presignedUrl(prepared, sign(credentials, stringToSign(prepared, hexHash(prepared.canonicalRequest))));
+    const prepared = preparePresign(
+      request,
+      credentials,
+      payloadHashOf(request, hexHash),
+      asymmetric,
+      regionSetQuery(request),
+    );
+    return presignedUrl(
+      prepared,
+      sign(credentials, stringToSign(prepared, hexHash(prepared.canonicalRequest))),
+    );
   };
 }