@specific.dev/spectest 0.39.0 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -8,27 +8,33 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
       "default": "./dist/index.js"
     },
     "./components": {
       "types": "./dist/components/index.d.ts",
+      "bun": "./src/components/index.ts",
       "default": "./dist/components/index.js"
     },
     "./browser": {
       "types": "./dist/browser.d.ts",
+      "bun": "./src/browser.ts",
       "default": "./dist/browser.js"
     },
     "./daemon": {
       "types": "./dist/daemon.d.ts",
+      "bun": "./src/daemon.ts",
       "default": "./dist/daemon.js"
     },
     "./resolver": {
       "types": "./dist/resolver.d.ts",
+      "bun": "./src/resolver.ts",
       "default": "./dist/resolver.js"
     }
   },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "repository": {

package/src/aws-sigv4.ts

@@ -0,0 +1,218 @@
+// AWS Signature Version 4 signer — dependency-free, over `node:crypto`.
+//
+// Used by `components/replayFake.ts` to RE-SIGN a request on the record-mode
+// egress forward. The app under test signs with throwaway dummy credentials
+// (any AWS SDK refuses to build a request without *some* credential); the
+// broker strips that dummy signature and re-signs the exact outbound request
+// with the real credentials brokered eval-scoped from the platform Secrets
+// store. Because signing happens at forward time over the real outbound
+// canonical request, `x-amz-date` / `x-amz-content-sha256` / `authorization`
+// are always internally consistent — which is exactly what static header
+// injection cannot achieve for SigV4 (the signature is a keyed HMAC over the
+// whole request, not a static token).
+//
+// Scope note: this implements the standard non-S3 canonicalization (path
+// URI-encoded once more on top of the wire path; query canonicalized with
+// %20). That is correct for the single-host JSON services this targets
+// (DynamoDB, SQS, STS, …). S3 (single-encoded path, virtual-hosted style)
+// and streaming/chunked signatures are out of scope.
+
+import { createHash, createHmac } from "node:crypto";
+
+export interface SigV4Credentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  /** Session token for temporary credentials (STS/assume-role). */
+  sessionToken?: string;
+}
+
+export interface SigV4Scope {
+  region: string;
+  service: string;
+}
+
+function hmac(key: Buffer | string, data: string): Buffer {
+  return createHmac("sha256", key).update(data, "utf8").digest();
+}
+
+function sha256Hex(data: Uint8Array | string): string {
+  const buf = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+/** RFC 3986 URI-encode per the SigV4 rules: unreserved chars pass through,
+ *  everything else is `%XX` over the UTF-8 bytes. `/` is encoded only when
+ *  `encodeSlash` (true for query components, false for path segments). */
+function awsUriEncode(input: string, encodeSlash: boolean): string {
+  let out = "";
+  for (const byte of Buffer.from(input, "utf8")) {
+    const isUnreserved =
+      (byte >= 0x41 && byte <= 0x5a) || // A-Z
+      (byte >= 0x61 && byte <= 0x7a) || // a-z
+      (byte >= 0x30 && byte <= 0x39) || // 0-9
+      byte === 0x2d || // -
+      byte === 0x2e || // .
+      byte === 0x5f || // _
+      byte === 0x7e; // ~
+    if (isUnreserved) {
+      out += String.fromCharCode(byte);
+    } else if (byte === 0x2f && !encodeSlash) {
+      out += "/";
+    } else {
+      out += "%" + byte.toString(16).toUpperCase().padStart(2, "0");
+    }
+  }
+  return out;
+}
+
+/** Canonical URI = the absolute path, URI-encoded once more (non-S3 rule).
+ *  For the near-universal `/` path of JSON services this is just `/`. */
+function canonicalUri(path: string): string {
+  if (!path || path === "/") return "/";
+  return path
+    .split("/")
+    .map((seg) => awsUriEncode(seg, false))
+    .join("/");
+}
+
+/** Canonical query string: each key/value AWS-URI-encoded, sorted by encoded
+ *  key then value, joined by `&`. Also the exact string to put on the wire so
+ *  the received query re-canonicalizes to what we signed (URLSearchParams
+ *  would encode spaces as `+`, diverging from the signed `%20`). */
+function canonicalQuery(params: URLSearchParams): string {
+  const pairs: [string, string][] = [];
+  for (const [k, v] of params) pairs.push([awsUriEncode(k, true), awsUriEncode(v, true)]);
+  pairs.sort((a, b) =>
+    a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0,
+  );
+  return pairs.map(([k, v]) => `${k}=${v}`).join("&");
+}
+
+/** `20260722T101112Z` (amzDate) + `20260722` (dateStamp) from a Date. */
+function amzDates(now: Date): { amzDate: string; dateStamp: string } {
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
+  return { amzDate, dateStamp: amzDate.slice(0, 8) };
+}
+
+/** Parse the `<AKID>/<date>/<region>/<service>/aws4_request` credential scope
+ *  out of an `Authorization` header or an `X-Amz-Credential` query value. */
+function scopeFromCredential(cred: string | null | undefined): SigV4Scope | undefined {
+  if (!cred) return undefined;
+  const m = /Credential=([^,\s]+)/.exec(cred);
+  const scope = m ? m[1] : cred;
+  const parts = scope.split("/");
+  if (parts.length >= 5 && parts[4] === "aws4_request" && parts[2] && parts[3]) {
+    return { region: parts[2], service: parts[3] };
+  }
+  return undefined;
+}
+
+/** Fallback: derive scope from a `<service>.<region>.amazonaws.com` host. */
+function scopeFromHost(host: string): SigV4Scope | undefined {
+  if (!host.endsWith(".amazonaws.com")) return undefined;
+  const label = host.slice(0, -".amazonaws.com".length);
+  const parts = label.split(".");
+  if (parts.length === 1 && parts[0]) return { service: parts[0], region: "us-east-1" };
+  if (parts.length === 2 && parts[0] && parts[1]) return { service: parts[0], region: parts[1] };
+  // `bucket.s3.region` (S3 virtual-host) is out of scope, but recover what we can.
+  const s3i = parts.indexOf("s3");
+  if (s3i >= 0 && parts[s3i + 1]) return { service: "s3", region: parts[s3i + 1] };
+  return undefined;
+}
+
+/** Infer the region + service to sign for. The app's own (dummy-credentialed)
+ *  request still carries a real credential SCOPE — that's authoritative; the
+ *  host is a fallback. Returns `undefined` when nothing is derivable. */
+export function inferSigV4Scope(args: {
+  authorization?: string | null;
+  credentialParam?: string | null;
+  host: string;
+}): SigV4Scope | undefined {
+  return (
+    scopeFromCredential(args.authorization) ??
+    scopeFromCredential(args.credentialParam) ??
+    scopeFromHost(args.host)
+  );
+}
+
+export interface SignedRequest {
+  /** Headers to SET on the outbound request (lowercased). Includes
+   *  `authorization`, `x-amz-date`, `x-amz-content-sha256`, and
+   *  `x-amz-security-token` when session credentials are used. */
+  headers: Record<string, string>;
+  /** Canonical query string to place on the wire (matches the signature). */
+  canonicalQuery: string;
+}
+
+/** Sign an outbound request with SigV4 (header authorization). `additionalHeaders`
+ *  (e.g. `x-amz-target`, `content-type`) are folded into the signed set — they
+ *  must already be present on the outbound request with these exact values. */
+export function signAwsV4Request(args: {
+  method: string;
+  /** Wire path (as the app sent it, already once-encoded). */
+  path: string;
+  /** Query params to send (SigV4 `x-amz-*` params already stripped). */
+  query: URLSearchParams;
+  host: string;
+  body: Uint8Array;
+  credentials: SigV4Credentials;
+  scope: SigV4Scope;
+  additionalHeaders?: Record<string, string>;
+  now?: Date;
+}): SignedRequest {
+  const { amzDate, dateStamp } = amzDates(args.now ?? new Date());
+  const payloadHash = sha256Hex(args.body);
+
+  const signedHeaders: Record<string, string> = {};
+  for (const [k, v] of Object.entries(args.additionalHeaders ?? {})) {
+    signedHeaders[k.toLowerCase()] = v.trim();
+  }
+  signedHeaders["host"] = args.host;
+  signedHeaders["x-amz-content-sha256"] = payloadHash;
+  signedHeaders["x-amz-date"] = amzDate;
+  if (args.credentials.sessionToken) {
+    signedHeaders["x-amz-security-token"] = args.credentials.sessionToken;
+  }
+
+  const names = Object.keys(signedHeaders).sort();
+  const canonicalHeaders = names.map((n) => `${n}:${signedHeaders[n]}\n`).join("");
+  const signedHeaderList = names.join(";");
+
+  const cq = canonicalQuery(args.query);
+  const canonicalRequest = [
+    args.method.toUpperCase(),
+    canonicalUri(args.path),
+    cq,
+    canonicalHeaders,
+    signedHeaderList,
+    payloadHash,
+  ].join("\n");
+
+  const credentialScope = `${dateStamp}/${args.scope.region}/${args.scope.service}/aws4_request`;
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    credentialScope,
+    sha256Hex(canonicalRequest),
+  ].join("\n");
+
+  const kDate = hmac("AWS4" + args.credentials.secretAccessKey, dateStamp);
+  const kRegion = hmac(kDate, args.scope.region);
+  const kService = hmac(kRegion, args.scope.service);
+  const kSigning = hmac(kService, "aws4_request");
+  const signature = createHmac("sha256", kSigning).update(stringToSign, "utf8").digest("hex");
+
+  const authorization =
+    `AWS4-HMAC-SHA256 Credential=${args.credentials.accessKeyId}/${credentialScope}, ` +
+    `SignedHeaders=${signedHeaderList}, Signature=${signature}`;
+
+  const headers: Record<string, string> = {
+    authorization,
+    "x-amz-date": amzDate,
+    "x-amz-content-sha256": payloadHash,
+  };
+  if (args.credentials.sessionToken) {
+    headers["x-amz-security-token"] = args.credentials.sessionToken;
+  }
+  return { headers, canonicalQuery: cq };
+}