@bugmole/cli 0.4.0

package/spec/ui-parity-audit.schema.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://app.bugmole.com/schemas/ui-parity-audit.schema.json",
+  "title": "Bugmole UI Parity Audit",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "auditId",
+    "reference",
+    "current",
+    "summary",
+    "flowMatrix",
+    "comparisons",
+    "issues",
+    "fixPrompt",
+    "blockedVerification"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "auditId": { "type": "string", "minLength": 1 },
+    "workspaceId": { "type": "string" },
+    "projectId": { "type": "string" },
+    "appId": { "type": "string" },
+    "appName": { "type": "string" },
+    "dnaRevision": { "type": "integer", "minimum": 1 },
+    "designDnaRefs": { "type": "array", "items": { "type": "string" } },
+    "tokenDrift": { "type": "array", "items": { "$ref": "#/$defs/tokenDrift" } },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "completedAt": { "type": "string", "format": "date-time" },
+    "reference": { "$ref": "#/$defs/experience" },
+    "current": { "$ref": "#/$defs/experience" },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "screensTotal",
+        "actionsTotal",
+        "visualDifferencePercent",
+        "interactionParityScore",
+        "apiParityScore",
+        "authenticationParityScore",
+        "fixedIssues",
+        "unresolvedIssues"
+      ],
+      "properties": {
+        "screensTotal": { "type": "integer", "minimum": 0 },
+        "actionsTotal": { "type": "integer", "minimum": 0 },
+        "visualDifferencePercent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "interactionParityScore": { "type": "number", "minimum": 0, "maximum": 100 },
+        "apiParityScore": { "type": "number", "minimum": 0, "maximum": 100 },
+        "authenticationParityScore": { "type": "number", "minimum": 0, "maximum": 100 },
+        "fixedIssues": { "type": "integer", "minimum": 0 },
+        "unresolvedIssues": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "flowMatrix": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/flow" }
+    },
+    "comparisons": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/comparison" }
+    },
+    "issues": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/issue" }
+    },
+    "fixPrompt": { "type": "string" },
+    "artifacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/artifact" }
+    },
+    "blockedVerification": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["description", "reason"],
+        "properties": {
+          "description": { "type": "string" },
+          "reason": { "type": "string" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "experience": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "location"],
+      "properties": {
+        "kind": { "enum": ["url", "html", "old_app_link", "image", "figma", "other"] },
+        "location": { "type": "string" },
+        "viewport": { "type": "string" },
+        "notes": { "type": "string" }
+      }
+    },
+    "flow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["flowId", "referenceScreen", "currentRoute", "authState", "actions", "status"],
+      "properties": {
+        "flowId": { "type": "string" },
+        "referenceScreen": { "type": "string" },
+        "currentRoute": { "type": "string" },
+        "authState": { "enum": ["guest", "authenticated", "logged_out", "unknown"] },
+        "states": { "type": "array", "items": { "type": "string" } },
+        "actions": { "type": "array", "items": { "type": "string" } },
+        "status": { "enum": ["matched", "partially_matched", "unmatched", "blocked"] },
+        "notes": { "type": "string" }
+      }
+    },
+    "comparison": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "screenId",
+        "differencePercent",
+        "changedPixels",
+        "totalPixels",
+        "heatmap",
+        "mismatches"
+      ],
+      "properties": {
+        "screenId": { "type": "string" },
+        "referenceCapture": { "type": "string" },
+        "currentCapture": { "type": "string" },
+        "diffCapture": { "type": "string" },
+        "heatmapCapture": { "type": "string" },
+        "differencePercent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "changedPixels": { "type": "integer", "minimum": 0 },
+        "totalPixels": { "type": "integer", "minimum": 1 },
+        "threshold": { "type": "integer", "minimum": 0, "maximum": 255 },
+        "heatmap": { "type": "string" },
+        "mismatches": { "type": "array", "items": { "type": "string" } },
+        "behavioralMismatches": { "type": "array", "items": { "type": "string" } },
+        "backendMismatches": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "issue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["issueId", "category", "status", "description"],
+      "properties": {
+        "issueId": { "type": "string" },
+        "category": { "enum": ["visual", "behavioral", "backend", "authentication", "platform"] },
+        "status": {
+          "enum": [
+            "confirmed_match",
+            "fixed",
+            "unresolved",
+            "blocked",
+            "platform_limitation",
+            "missing_backend"
+          ]
+        },
+        "severity": { "enum": ["high", "medium", "low"] },
+        "description": { "type": "string" },
+        "evidence": { "type": "array", "items": { "type": "string" } },
+        "fixPrompt": { "type": "string" },
+        "screenId": {
+          "type": "string",
+          "description": "The comparisons[].screenId (and, when the flow is graph-linked, the matching journey node id) this issue was found on. Optional so older audits without it remain valid; the dashboard groups issues without a screenId as ungrouped rather than guessing."
+        }
+      }
+    },
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "path"],
+      "properties": {
+        "kind": {
+          "enum": ["reference_screenshot", "current_screenshot", "diff", "heatmap", "log", "other"]
+        },
+        "path": { "type": "string" },
+        "screenId": { "type": "string" }
+      }
+    },
+    "tokenDrift": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tokenId", "category", "description", "severity"],
+      "properties": {
+        "tokenId": { "type": "string" },
+        "category": { "type": "string" },
+        "description": { "type": "string" },
+        "severity": { "enum": ["high", "medium", "low"] },
+        "referenceValue": {},
+        "currentValue": {}
+      }
+    }
+  }
+}

package/spec/ui-reverse-engineering.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://app.bugmole.com/schemas/ui-reverse-engineering.schema.json",
+  "title": "Bugmole UI Reverse Engineering Job",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "jobId", "projectId", "dnaRevision", "status", "stage", "inputs", "regions", "atomicNodes", "mismatches", "playbooks"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "jobId": { "type": "string", "minLength": 1 },
+    "projectId": { "type": "string", "minLength": 1 },
+    "dnaRevision": { "type": "integer", "minimum": 1 },
+    "status": { "enum": ["queued", "running", "blocked", "completed", "failed"] },
+    "stage": { "enum": ["input", "measure", "layout", "dna", "atoms", "compose", "validate", "reconcile", "complete"] },
+    "inputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "location"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "kind": { "enum": ["image", "figma", "pdf", "url", "html", "existing_app"] },
+          "location": { "type": "string", "minLength": 1 },
+          "viewport": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "width": { "type": "number", "minimum": 1 },
+              "height": { "type": "number", "minimum": 1 }
+            }
+          },
+          "checksum": { "type": "string" },
+          "status": { "enum": ["active", "archived"] },
+          "relatedJourneyIds": { "type": "array", "items": { "type": "string" } },
+          "appId": { "type": "string" },
+          "environmentId": { "type": "string" },
+          "registeredAt": { "type": "string", "format": "date-time" },
+          "metadata": { "type": "object" }
+        }
+      }
+    },
+    "regions": { "type": "array" },
+    "atomicNodes": { "type": "array" },
+    "mismatches": { "type": "array" },
+    "playbooks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "name", "purpose", "status", "steps"],
+        "properties": {
+          "id": { "enum": ["design-dna", "atomic-design"] },
+          "name": { "type": "string" },
+          "purpose": { "type": "string" },
+          "status": { "enum": ["active", "blocked"] },
+          "steps": { "type": "array", "items": { "type": "string" } },
+          "referenceUrl": { "type": "string", "format": "uri" }
+        }
+      }
+    },
+    "storybook": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["detected", "components"],
+      "properties": {
+        "detected": { "type": "boolean" },
+        "configPath": { "type": "string" },
+        "blockedReason": { "type": "string" },
+        "components": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "title", "storyNames", "sourcePath", "level", "confidence"],
+            "properties": {
+              "id": { "type": "string" },
+              "title": { "type": "string" },
+              "componentName": { "type": "string" },
+              "storyNames": { "type": "array", "items": { "type": "string" } },
+              "sourcePath": { "type": "string" },
+              "level": { "enum": ["atom", "molecule", "organism", "template", "page"] },
+              "confidence": { "enum": ["high", "medium", "low", "blocked"] }
+            }
+          }
+        }
+      }
+    },
+    "playbookRefs": { "type": "array", "items": { "type": "string" } },
+    "blockedReasons": { "type": "array", "items": { "type": "string" } },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  }
+}

package/src/billing/plan-catalog.test.ts

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+import { COPY_HEADER, catalogCopy, catalogSource } from "../../scripts/sync-plan-catalog.mjs";
+import { AI_CREDIT_COST, PLANS, entitlementsFor, formatUsd, includedQuantity, overageCents } from "./plan-catalog.js";
+
+test("the dashboard's copy of the plan catalog matches the source", async () => {
+  const [source, copy] = await Promise.all([readFile(catalogSource, "utf8"), readFile(catalogCopy, "utf8")]);
+  assert.equal(copy, COPY_HEADER + source, "run `npm run sync:catalog`");
+});
+
+test("plans get strictly more capacity as they get more expensive", () => {
+  const paid = [PLANS.free, PLANS.team, PLANS.business];
+  for (let index = 1; index < paid.length; index++) {
+    for (const key of ["cloudMinutes", "aiCredits", "parallel", "historyDays", "projects"] as const) {
+      assert.ok((paid[index][key] ?? Infinity) > (paid[index - 1][key] ?? 0), `${paid[index].id}.${key}`);
+    }
+    assert.ok(paid[index].priceMonthlyCents! > paid[index - 1].priceMonthlyCents!);
+    assert.ok(paid[index].priceYearlyMonthlyCents! < paid[index].priceMonthlyCents!, "yearly is a discount");
+  }
+});
+
+test("free usage stops at the allowance while paid plans can buy more", () => {
+  const free = entitlementsFor("free");
+  assert.equal(overageCents(free, "browser_minute"), null);
+  assert.equal(overageCents(free, "device_minute"), null);
+  const team = entitlementsFor("team");
+  assert.equal(overageCents(team, "browser_minute"), 4);
+  assert.equal(overageCents(team, "device_minute"), 25);
+  assert.equal(includedQuantity(team, "device_minute"), 0);
+  assert.equal(includedQuantity(team, "ai_credit"), 1500);
+});
+
+test("contract overrides replace only what they name", () => {
+  const custom = entitlementsFor("enterprise", { cloudMinutes: 50_000, features: { scim: false } });
+  assert.equal(custom.cloudMinutes, 50_000);
+  assert.equal(custom.historyDays, 365);
+  assert.equal(custom.features.scim, false);
+  assert.equal(custom.features.sso, true);
+});
+
+test("AI credit costs match the pricing page", () => {
+  assert.deepEqual(AI_CREDIT_COST, { analysis: 1, repair: 20, exploration: 100, discovery: 0 });
+  assert.equal(formatUsd(24_900), "$249");
+  assert.equal(formatUsd(4), "$0.04");
+});

package/src/billing/plan-catalog.ts

@@ -0,0 +1,199 @@
+// The one definition of Bugmole's plans. The registry enforces it, the
+// dashboard shows it, and the bugmole.com pricing page is built from it, so a
+// price or limit changes in exactly one place.
+//
+// Keep this file dependency-free and limited to type-strippable TypeScript:
+// Node imports it directly in the docs build, and `npm run sync:catalog`
+// copies it verbatim into the dashboard (apps/qa/src/lib/plan-catalog.ts).
+
+export type PlanId = "free" | "team" | "business" | "enterprise";
+export type BillingInterval = "month" | "year";
+export type UsageKind = "browser_minute" | "device_minute" | "ai_credit";
+export type AiAction = "analysis" | "repair" | "exploration" | "discovery";
+
+export type PlanFeatures = {
+  prChecks: boolean;
+  slack: boolean;
+  teams: boolean;
+  aiFixes: boolean;
+  deviceClouds: boolean;
+  sso: boolean;
+  scim: boolean;
+  auditLogExport: boolean;
+  prioritySupport: boolean;
+  selfHostedWorkers: boolean;
+};
+
+export type PlanDef = {
+  id: PlanId;
+  name: string;
+  audience: string;
+  /** Monthly price when billed monthly; null means custom pricing. */
+  priceMonthlyCents: number | null;
+  /** Per-month price when billed yearly; null when there is no yearly price. */
+  priceYearlyMonthlyCents: number | null;
+  /** null means no fixed limit (set per contract). */
+  projects: number | null;
+  cloudMinutes: number | null;
+  aiCredits: number | null;
+  parallel: number | null;
+  historyDays: number | null;
+  /** Cents per unit beyond the allowance; null means usage stops at the allowance. */
+  overage: { browserMinuteCents: number | null; creditCents: number | null };
+  features: PlanFeatures;
+};
+
+const NO_FEATURES: PlanFeatures = {
+  prChecks: false,
+  slack: false,
+  teams: false,
+  aiFixes: false,
+  deviceClouds: false,
+  sso: false,
+  scim: false,
+  auditLogExport: false,
+  prioritySupport: false,
+  selfHostedWorkers: false,
+};
+
+export const PLANS: Record<PlanId, PlanDef> = {
+  free: {
+    id: "free",
+    name: "Free",
+    audience: "Individuals and evaluation",
+    priceMonthlyCents: 0,
+    priceYearlyMonthlyCents: 0,
+    projects: 1,
+    cloudMinutes: 300,
+    aiCredits: 100,
+    parallel: 2,
+    historyDays: 7,
+    overage: { browserMinuteCents: null, creditCents: null },
+    features: { ...NO_FEATURES },
+  },
+  team: {
+    id: "team",
+    name: "Team",
+    audience: "Teams shipping continuously",
+    priceMonthlyCents: 24_900,
+    priceYearlyMonthlyCents: 19_900,
+    projects: 10,
+    cloudMinutes: 3_000,
+    aiCredits: 1_500,
+    parallel: 8,
+    historyDays: 30,
+    overage: { browserMinuteCents: 4, creditCents: 1 },
+    features: { ...NO_FEATURES, prChecks: true, slack: true, teams: true, aiFixes: true },
+  },
+  business: {
+    id: "business",
+    name: "Business",
+    audience: "Organizations testing across apps, devices and teams",
+    priceMonthlyCents: 89_900,
+    priceYearlyMonthlyCents: 71_900,
+    projects: 50,
+    cloudMinutes: 15_000,
+    aiCredits: 7_500,
+    parallel: 25,
+    historyDays: 90,
+    overage: { browserMinuteCents: 3, creditCents: 1 },
+    features: {
+      ...NO_FEATURES,
+      prChecks: true,
+      slack: true,
+      teams: true,
+      aiFixes: true,
+      deviceClouds: true,
+      sso: true,
+      auditLogExport: true,
+      prioritySupport: true,
+    },
+  },
+  enterprise: {
+    id: "enterprise",
+    name: "Enterprise",
+    audience: "Large and regulated organizations",
+    priceMonthlyCents: null,
+    priceYearlyMonthlyCents: null,
+    projects: null,
+    cloudMinutes: null,
+    aiCredits: null,
+    parallel: null,
+    historyDays: 365,
+    overage: { browserMinuteCents: 3, creditCents: 1 },
+    features: {
+      prChecks: true,
+      slack: true,
+      teams: true,
+      aiFixes: true,
+      deviceClouds: true,
+      sso: true,
+      scim: true,
+      auditLogExport: true,
+      prioritySupport: true,
+      selfHostedWorkers: true,
+    },
+  },
+};
+
+export const PLAN_IDS = Object.keys(PLANS) as PlanId[];
+
+/** Credits each AI action costs. A project's own model key costs no credits. */
+export const AI_CREDIT_COST: Record<AiAction, number> = {
+  analysis: 1,
+  repair: 20,
+  exploration: 100,
+  discovery: 0,
+};
+
+/** Real devices on Bugmole's own AWS Device Farm account: pay as you go, none included. */
+export const DEVICE_FARM_CENTS_PER_MIN = 25;
+
+/** Contract-specific adjustments stored with a workspace's plan (Enterprise, trials). */
+export type PlanOverrides = Partial<Pick<PlanDef, "projects" | "cloudMinutes" | "aiCredits" | "parallel" | "historyDays">> & {
+  features?: Partial<PlanFeatures>;
+  overage?: Partial<PlanDef["overage"]>;
+};
+
+export type Entitlements = Omit<PlanDef, "name" | "audience" | "priceMonthlyCents" | "priceYearlyMonthlyCents">;
+
+export function isPlanId(value: unknown): value is PlanId {
+  return typeof value === "string" && (PLAN_IDS as string[]).includes(value);
+}
+
+export function entitlementsFor(plan: PlanId, overrides: PlanOverrides = {}): Entitlements {
+  const base = PLANS[plan];
+  const pick = <K extends "projects" | "cloudMinutes" | "aiCredits" | "parallel" | "historyDays">(key: K) =>
+    overrides[key] !== undefined ? (overrides[key] as PlanDef[K]) : base[key];
+  return {
+    id: base.id,
+    projects: pick("projects"),
+    cloudMinutes: pick("cloudMinutes"),
+    aiCredits: pick("aiCredits"),
+    parallel: pick("parallel"),
+    historyDays: pick("historyDays"),
+    overage: { ...base.overage, ...overrides.overage },
+    features: { ...base.features, ...overrides.features },
+  };
+}
+
+/** How much of the allowance a usage kind has; device minutes have none on any plan. */
+export function includedQuantity(entitlements: Entitlements, kind: UsageKind): number | null {
+  if (kind === "browser_minute") return entitlements.cloudMinutes;
+  if (kind === "ai_credit") return entitlements.aiCredits;
+  return 0;
+}
+
+/** Cents per unit beyond the allowance, or null when usage must stop at the allowance. */
+export function overageCents(entitlements: Entitlements, kind: UsageKind): number | null {
+  if (kind === "browser_minute") return entitlements.overage.browserMinuteCents;
+  if (kind === "ai_credit") return entitlements.overage.creditCents;
+  // Real devices need a paid plan with a subscription; the registry checks that.
+  return entitlements.id === "free" ? null : DEVICE_FARM_CENTS_PER_MIN;
+}
+
+export function formatUsd(cents: number, { minimumFractionDigits }: { minimumFractionDigits?: number } = {}): string {
+  const dollars = cents / 100;
+  const fraction = minimumFractionDigits ?? (Number.isInteger(dollars) ? 0 : 2);
+  return `$${dollars.toLocaleString("en-US", { minimumFractionDigits: fraction, maximumFractionDigits: Math.max(fraction, 2) })}`;
+}

package/src/integrations/aws-sigv4.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { signAwsRequest } from "./aws-sigv4.js";
+
+// AWS's published SigV4 example ("get-vanilla"), from the aws-sig-v4 test suite,
+// adjusted for the x-amz-content-sha256 header this signer always includes.
+test("SigV4 matches an independent calculation", async () => {
+  const { createHash, createHmac } = await import("node:crypto");
+  const credentials = { accessKeyId: "AKIDEXAMPLE", secretAccessKey: "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY" };
+  const now = new Date("2015-08-30T12:36:00Z");
+  const body = '{"arn":"x"}';
+  const headers = await signAwsRequest({
+    credentials, region: "us-west-2", service: "devicefarm", method: "POST",
+    url: "https://devicefarm.us-west-2.amazonaws.com/", headers: { "Content-Type": "application/x-amz-json-1.1", "X-Amz-Target": "DeviceFarm_20150623.ListDevices" },
+    body, now,
+  });
+  const payloadHash = createHash("sha256").update(body).digest("hex");
+  const canonical = [
+    "POST", "/", "",
+    `content-type:application/x-amz-json-1.1\nhost:devicefarm.us-west-2.amazonaws.com\nx-amz-content-sha256:${payloadHash}\nx-amz-date:20150830T123600Z\nx-amz-target:DeviceFarm_20150623.ListDevices\n`,
+    "content-type;host;x-amz-content-sha256;x-amz-date;x-amz-target",
+    payloadHash,
+  ].join("\n");
+  const scope = "20150830/us-west-2/devicefarm/aws4_request";
+  const toSign = ["AWS4-HMAC-SHA256", "20150830T123600Z", scope, createHash("sha256").update(canonical).digest("hex")].join("\n");
+  let key: Buffer = createHmac("sha256", `AWS4${credentials.secretAccessKey}`).update("20150830").digest();
+  for (const part of ["us-west-2", "devicefarm", "aws4_request"]) key = createHmac("sha256", key).update(part).digest();
+  const signature = createHmac("sha256", key).update(toSign).digest("hex");
+  assert.equal(headers.authorization, `AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/${scope}, SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date;x-amz-target, Signature=${signature}`);
+  assert.equal(headers["x-amz-date"], "20150830T123600Z");
+  assert.equal(headers.host, undefined, "fetch sets the host itself");
+});
+
+test("the AWS reference vector for a known key derivation", async () => {
+  // From AWS docs "Examples of how to derive a signing key": the canonical get-vanilla request.
+  const headers = await signAwsRequest({
+    credentials: { accessKeyId: "AKIDEXAMPLE", secretAccessKey: "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY" },
+    region: "us-east-1", service: "service", method: "GET", url: "https://example.amazonaws.com/?Param2=value2&Param1=value1",
+    headers: {}, body: "", now: new Date("2015-08-30T12:36:00Z"),
+  });
+  assert.match(headers.authorization, /^AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE\/20150830\/us-east-1\/service\/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=[0-9a-f]{64}$/);
+});

package/src/integrations/aws-sigv4.ts

@@ -0,0 +1,72 @@
+// AWS Signature Version 4 with WebCrypto, so the same code signs requests in
+// Cloudflare Workers and in Node.
+
+export type AwsCredentials = { accessKeyId: string; secretAccessKey: string; sessionToken?: string };
+
+const encoder = new TextEncoder();
+
+function hex(bytes: ArrayBuffer | Uint8Array): string {
+  return [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+async function sha256Hex(value: string): Promise<string> {
+  return hex(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
+}
+
+async function hmac(key: ArrayBuffer | Uint8Array, value: string): Promise<ArrayBuffer> {
+  const imported = await crypto.subtle.importKey("raw", key as BufferSource, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return crypto.subtle.sign("HMAC", imported, encoder.encode(value));
+}
+
+/** Signs a request with a string body. Returns the headers to send. */
+export async function signAwsRequest(params: {
+  credentials: AwsCredentials;
+  region: string;
+  service: string;
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+  now?: Date;
+}): Promise<Record<string, string>> {
+  const now = params.now ?? new Date();
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
+  const date = amzDate.slice(0, 8);
+  const url = new URL(params.url);
+  const payloadHash = await sha256Hex(params.body);
+  const headers: Record<string, string> = {
+    ...Object.fromEntries(Object.entries(params.headers).map(([key, value]) => [key.toLowerCase(), value.trim()])),
+    host: url.host,
+    "x-amz-date": amzDate,
+    "x-amz-content-sha256": payloadHash,
+    ...(params.credentials.sessionToken ? { "x-amz-security-token": params.credentials.sessionToken } : {}),
+  };
+  const names = Object.keys(headers).sort();
+  const canonicalQuery = [...url.searchParams.entries()]
+    .map(([key, value]) => [encodeRfc3986(key), encodeRfc3986(value)])
+    .sort(([a, x], [b, y]) => (a === b ? (x < y ? -1 : 1) : a < b ? -1 : 1))
+    .map(([key, value]) => `${key}=${value}`)
+    .join("&");
+  const canonicalRequest = [
+    params.method.toUpperCase(),
+    url.pathname.split("/").map((part) => encodeRfc3986(decodeURIComponent(part))).join("/") || "/",
+    canonicalQuery,
+    names.map((name) => `${name}:${headers[name]}\n`).join(""),
+    names.join(";"),
+    payloadHash,
+  ].join("\n");
+  const scope = `${date}/${params.region}/${params.service}/aws4_request`;
+  const stringToSign = ["AWS4-HMAC-SHA256", amzDate, scope, await sha256Hex(canonicalRequest)].join("\n");
+  let key = await hmac(encoder.encode(`AWS4${params.credentials.secretAccessKey}`), date);
+  for (const part of [params.region, params.service, "aws4_request"]) key = await hmac(key, part);
+  const signature = hex(await hmac(key, stringToSign));
+  const { host: _host, ...rest } = headers;
+  return {
+    ...rest,
+    authorization: `AWS4-HMAC-SHA256 Credential=${params.credentials.accessKeyId}/${scope}, SignedHeaders=${names.join(";")}, Signature=${signature}`,
+  };
+}
+
+function encodeRfc3986(value: string): string {
+  return encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}