@hexclave/shared 1.0.0

package/dist/esm/helpers/password.d.ts

@@ -0,0 +1,7 @@
+import { KnownErrors } from "..";
+
+//#region src/helpers/password.d.ts
+declare function getPasswordError(password: string): KnownErrors["PasswordRequirementsNotMet"] | undefined;
+//#endregion
+export { getPasswordError };
+//# sourceMappingURL=password.d.ts.map

package/dist/esm/helpers/password.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"password.d.ts","names":[],"sources":["../../../src/helpers/password.ts"],"mappings":";;;iBAKgB,gBAAA,CAAiB,QAAA,WAAmB,WAAA"}

package/dist/esm/helpers/password.js

@@ -0,0 +1,13 @@
+import { KnownErrors } from "../index.js";
+
+//#region src/helpers/password.ts
+const minLength = 8;
+const maxLength = 70;
+function getPasswordError(password) {
+	if (password.length < minLength) return new KnownErrors.PasswordTooShort(minLength);
+	if (password.length > maxLength) return new KnownErrors.PasswordTooLong(maxLength);
+}
+
+//#endregion
+export { getPasswordError };
+//# sourceMappingURL=password.js.map

package/dist/esm/helpers/password.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"password.js","names":[],"sources":["../../../src/helpers/password.ts"],"sourcesContent":["import { KnownErrors } from \"..\";\n\nconst minLength = 8;\nconst maxLength = 70;\n\nexport function getPasswordError(password: string): KnownErrors[\"PasswordRequirementsNotMet\"] | undefined {\n  if (password.length < minLength) {\n    return new KnownErrors.PasswordTooShort(minLength);\n  }\n\n  if (password.length > maxLength) {\n    return new KnownErrors.PasswordTooLong(maxLength);\n  }\n\n  return undefined;\n}\n"],"mappings":";;;AAEA,MAAM,YAAY;AAClB,MAAM,YAAY;AAElB,SAAgB,iBAAiB,UAAyE;AACxG,KAAI,SAAS,SAAS,UACpB,QAAO,IAAI,YAAY,iBAAiB,UAAU;AAGpD,KAAI,SAAS,SAAS,UACpB,QAAO,IAAI,YAAY,gBAAgB,UAAU"}

package/dist/esm/helpers/production-mode.d.ts

@@ -0,0 +1,11 @@
+import { ProjectsCrud } from "../interface/crud/projects";
+
+//#region src/helpers/production-mode.d.ts
+type ProductionModeError = {
+  message: string;
+  relativeFixUrl: `/${string}`;
+};
+declare function getProductionModeErrors(project: ProjectsCrud["Admin"]["Read"]): ProductionModeError[];
+//#endregion
+export { ProductionModeError, getProductionModeErrors };
+//# sourceMappingURL=production-mode.d.ts.map

package/dist/esm/helpers/production-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"production-mode.d.ts","names":[],"sources":["../../../src/helpers/production-mode.ts"],"mappings":";;;KAIY,mBAAA;EACV,OAAA;EACA,cAAA;AAAA;AAAA,iBAGc,uBAAA,CAAwB,OAAA,EAAS,YAAA,oBAAgC,mBAAA"}

package/dist/esm/helpers/production-mode.js

@@ -0,0 +1,46 @@
+import { HexclaveAssertionError, captureError } from "../utils/errors.js";
+import { isLocalhost } from "../utils/urls.js";
+
+//#region src/helpers/production-mode.ts
+function getProductionModeErrors(project) {
+	const errors = [];
+	const domainsFixUrl = `/projects/${project.id}/domains`;
+	if (project.config.allow_localhost) errors.push({
+		message: "Localhost is not allowed in production mode, turn off 'Allow localhost' in project settings",
+		relativeFixUrl: domainsFixUrl
+	});
+	for (const { domain } of project.config.domains) {
+		let url;
+		try {
+			const normalizedDomain = domain.replace(/\*+/g, "wildcard-placeholder");
+			url = new URL(normalizedDomain);
+		} catch (e) {
+			captureError("production-mode-domain-not-valid", new HexclaveAssertionError("Domain was somehow not a valid URL; we should've caught this when setting the domain in the first place", {
+				domain,
+				projectId: project
+			}));
+			errors.push({
+				message: "Trusted domain is not a valid URL: " + domain,
+				relativeFixUrl: domainsFixUrl
+			});
+			continue;
+		}
+		if (isLocalhost(url)) errors.push({
+			message: "Localhost domains are not allowed to be trusted in production mode: " + domain,
+			relativeFixUrl: domainsFixUrl
+		});
+		else if (url.hostname.match(/^\d+(\.\d+)*$/)) errors.push({
+			message: "Direct IPs are not valid for trusted domains in production mode: " + domain,
+			relativeFixUrl: domainsFixUrl
+		});
+		else if (url.protocol !== "https:") errors.push({
+			message: "Trusted domains should be HTTPS: " + domain,
+			relativeFixUrl: domainsFixUrl
+		});
+	}
+	return errors;
+}
+
+//#endregion
+export { getProductionModeErrors };
+//# sourceMappingURL=production-mode.js.map

package/dist/esm/helpers/production-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"production-mode.js","names":[],"sources":["../../../src/helpers/production-mode.ts"],"sourcesContent":["import { ProjectsCrud } from \"../interface/crud/projects\";\nimport { HexclaveAssertionError, captureError } from \"../utils/errors\";\nimport { isLocalhost } from \"../utils/urls\";\n\nexport type ProductionModeError = {\n  message: string,\n  relativeFixUrl: `/${string}`,\n};\n\nexport function getProductionModeErrors(project: ProjectsCrud[\"Admin\"][\"Read\"]): ProductionModeError[] {\n  const errors: ProductionModeError[] = [];\n  const domainsFixUrl = `/projects/${project.id}/domains` as const;\n\n  if (project.config.allow_localhost) {\n    errors.push({\n      message: \"Localhost is not allowed in production mode, turn off 'Allow localhost' in project settings\",\n      relativeFixUrl: domainsFixUrl,\n    });\n  }\n\n  for (const { domain } of project.config.domains) {\n    let url;\n    try {\n      // For wildcard domains, replace wildcards with a valid placeholder to validate the URL structure\n      const normalizedDomain = domain.replace(/\\*+/g, 'wildcard-placeholder');\n      url = new URL(normalizedDomain);\n    } catch (e) {\n      captureError(\"production-mode-domain-not-valid\", new HexclaveAssertionError(\"Domain was somehow not a valid URL; we should've caught this when setting the domain in the first place\", {\n        domain,\n        projectId: project\n      }));\n      errors.push({\n        message: \"Trusted domain is not a valid URL: \" + domain,\n        relativeFixUrl: domainsFixUrl,\n      });\n      continue;\n    }\n\n    if (isLocalhost(url)) {\n      errors.push({\n        message: \"Localhost domains are not allowed to be trusted in production mode: \" + domain,\n        relativeFixUrl: domainsFixUrl,\n      });\n    } else if (url.hostname.match(/^\\d+(\\.\\d+)*$/)) {\n      errors.push({\n        message: \"Direct IPs are not valid for trusted domains in production mode: \" + domain,\n        relativeFixUrl: domainsFixUrl,\n      });\n    } else if (url.protocol !== \"https:\") {\n      errors.push({\n        message: \"Trusted domains should be HTTPS: \" + domain,\n        relativeFixUrl: domainsFixUrl,\n      });\n    }\n  }\n\n  return errors;\n}\n"],"mappings":";;;;AASA,SAAgB,wBAAwB,SAA+D;CACrG,MAAM,SAAgC,EAAE;CACxC,MAAM,gBAAgB,aAAa,QAAQ,GAAG;AAE9C,KAAI,QAAQ,OAAO,gBACjB,QAAO,KAAK;EACV,SAAS;EACT,gBAAgB;EACjB,CAAC;AAGJ,MAAK,MAAM,EAAE,YAAY,QAAQ,OAAO,SAAS;EAC/C,IAAI;AACJ,MAAI;GAEF,MAAM,mBAAmB,OAAO,QAAQ,QAAQ,uBAAuB;AACvE,SAAM,IAAI,IAAI,iBAAiB;WACxB,GAAG;AACV,gBAAa,oCAAoC,IAAI,uBAAuB,2GAA2G;IACrL;IACA,WAAW;IACZ,CAAC,CAAC;AACH,UAAO,KAAK;IACV,SAAS,wCAAwC;IACjD,gBAAgB;IACjB,CAAC;AACF;;AAGF,MAAI,YAAY,IAAI,CAClB,QAAO,KAAK;GACV,SAAS,yEAAyE;GAClF,gBAAgB;GACjB,CAAC;WACO,IAAI,SAAS,MAAM,gBAAgB,CAC5C,QAAO,KAAK;GACV,SAAS,sEAAsE;GAC/E,gBAAgB;GACjB,CAAC;WACO,IAAI,aAAa,SAC1B,QAAO,KAAK;GACV,SAAS,sCAAsC;GAC/C,gBAAgB;GACjB,CAAC;;AAIN,QAAO"}

package/dist/esm/helpers/support-sla.d.ts

@@ -0,0 +1,48 @@
+//#region src/helpers/support-sla.d.ts
+type SupportSlaConfig = {
+  enabled: boolean;
+  firstResponseMinutes: number | null;
+  nextResponseMinutes: number | null;
+};
+declare const DEFAULT_SUPPORT_SLA: SupportSlaConfig;
+/**
+ * Returns the target first-response due timestamp for a new conversation,
+ * or `null` if SLA tracking is off or no target is set.
+ */
+declare function computeFirstResponseDueAt(now: Date, sla: SupportSlaConfig): Date | null;
+/**
+ * Returns the target next-response due timestamp when a conversation has been
+ * re-opened by a user reply, or `null` if SLA tracking is off or no target
+ * is set.
+ */
+declare function computeNextResponseDueAt(now: Date, sla: SupportSlaConfig): Date | null;
+type SlaUrgency = "ok" | "warning" | "urgent" | "overdue";
+/**
+ * How soon (in milliseconds) before a due timestamp we switch into the
+ * "urgent" state. Within this window the due timestamp should be rendered
+ * with a strong alert treatment.
+ */
+declare const SLA_URGENT_THRESHOLD_MS: number;
+/**
+ * How soon (in milliseconds) before a due timestamp we switch into the
+ * "warning" state. Within this window the due timestamp should be rendered
+ * with a subtle alert treatment so agents can notice it without being
+ * distracted.
+ */
+declare const SLA_WARNING_THRESHOLD_MS: number;
+/**
+ * Classifies how close a due timestamp is to `now` so we can subtly alert
+ * agents as it approaches (and after it passes).
+ *
+ * If `windowStartedAt` is provided, thresholds scale with the total SLA
+ * window length - so a 5-minute SLA doesn't read as "urgent" from t=0 - and
+ * are capped by the fixed wall-clock thresholds so a 24-hour SLA doesn't
+ * sit in "warning" for 12 hours. If `windowStartedAt` isn't known, we fall
+ * back to the fixed wall-clock thresholds.
+ */
+declare function computeSlaUrgency(dueAt: Date, now: Date, options?: {
+  windowStartedAt?: Date | null;
+}): SlaUrgency;
+//#endregion
+export { DEFAULT_SUPPORT_SLA, SLA_URGENT_THRESHOLD_MS, SLA_WARNING_THRESHOLD_MS, SlaUrgency, SupportSlaConfig, computeFirstResponseDueAt, computeNextResponseDueAt, computeSlaUrgency };
+//# sourceMappingURL=support-sla.d.ts.map

package/dist/esm/helpers/support-sla.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"support-sla.d.ts","names":[],"sources":["../../../src/helpers/support-sla.ts"],"mappings":";KAAY,gBAAA;EACV,OAAA;EACA,oBAAA;EACA,mBAAA;AAAA;AAAA,cAGW,mBAAA,EAAqB,gBAAA;;;;;iBAelB,yBAAA,CACd,GAAA,EAAK,IAAA,EACL,GAAA,EAAK,gBAAA,GACJ,IAAA;;;;;AAHH;iBAagB,wBAAA,CACd,GAAA,EAAK,IAAA,EACL,GAAA,EAAK,gBAAA,GACJ,IAAA;AAAA,KAKS,UAAA;;;;;;cAOC,uBAAA;;;;;;;cAQA,wBAAA;;;;;;;;;;;iBAYG,iBAAA,CACd,KAAA,EAAO,IAAA,EACP,GAAA,EAAK,IAAA,EACL,OAAA;EAAY,eAAA,GAAkB,IAAA;AAAA,IAC7B,UAAA"}

package/dist/esm/helpers/support-sla.js

@@ -0,0 +1,65 @@
+//#region src/helpers/support-sla.ts
+const DEFAULT_SUPPORT_SLA = {
+	enabled: false,
+	firstResponseMinutes: null,
+	nextResponseMinutes: null
+};
+function addMinutesOrNull(now, minutes) {
+	if (minutes == null || !Number.isFinite(minutes) || minutes <= 0) return null;
+	return new Date(now.getTime() + minutes * 6e4);
+}
+/**
+* Returns the target first-response due timestamp for a new conversation,
+* or `null` if SLA tracking is off or no target is set.
+*/
+function computeFirstResponseDueAt(now, sla) {
+	if (!sla.enabled) return null;
+	return addMinutesOrNull(now, sla.firstResponseMinutes);
+}
+/**
+* Returns the target next-response due timestamp when a conversation has been
+* re-opened by a user reply, or `null` if SLA tracking is off or no target
+* is set.
+*/
+function computeNextResponseDueAt(now, sla) {
+	if (!sla.enabled) return null;
+	return addMinutesOrNull(now, sla.nextResponseMinutes);
+}
+/**
+* How soon (in milliseconds) before a due timestamp we switch into the
+* "urgent" state. Within this window the due timestamp should be rendered
+* with a strong alert treatment.
+*/
+const SLA_URGENT_THRESHOLD_MS = 900 * 1e3;
+/**
+* How soon (in milliseconds) before a due timestamp we switch into the
+* "warning" state. Within this window the due timestamp should be rendered
+* with a subtle alert treatment so agents can notice it without being
+* distracted.
+*/
+const SLA_WARNING_THRESHOLD_MS = 3600 * 1e3;
+/**
+* Classifies how close a due timestamp is to `now` so we can subtly alert
+* agents as it approaches (and after it passes).
+*
+* If `windowStartedAt` is provided, thresholds scale with the total SLA
+* window length - so a 5-minute SLA doesn't read as "urgent" from t=0 - and
+* are capped by the fixed wall-clock thresholds so a 24-hour SLA doesn't
+* sit in "warning" for 12 hours. If `windowStartedAt` isn't known, we fall
+* back to the fixed wall-clock thresholds.
+*/
+function computeSlaUrgency(dueAt, now, options) {
+	const remainingMs = dueAt.getTime() - now.getTime();
+	if (remainingMs <= 0) return "overdue";
+	const windowStartedAt = options?.windowStartedAt ?? null;
+	const totalWindowMs = windowStartedAt != null ? Math.max(1, dueAt.getTime() - windowStartedAt.getTime()) : null;
+	const urgentThresholdMs = totalWindowMs != null ? Math.min(totalWindowMs * .25, SLA_URGENT_THRESHOLD_MS) : SLA_URGENT_THRESHOLD_MS;
+	const warningThresholdMs = totalWindowMs != null ? Math.min(totalWindowMs * .5, SLA_WARNING_THRESHOLD_MS) : SLA_WARNING_THRESHOLD_MS;
+	if (remainingMs <= urgentThresholdMs) return "urgent";
+	if (remainingMs <= warningThresholdMs) return "warning";
+	return "ok";
+}
+
+//#endregion
+export { DEFAULT_SUPPORT_SLA, SLA_URGENT_THRESHOLD_MS, SLA_WARNING_THRESHOLD_MS, computeFirstResponseDueAt, computeNextResponseDueAt, computeSlaUrgency };
+//# sourceMappingURL=support-sla.js.map

package/dist/esm/helpers/support-sla.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"support-sla.js","names":[],"sources":["../../../src/helpers/support-sla.ts"],"sourcesContent":["export type SupportSlaConfig = {\n  enabled: boolean,\n  firstResponseMinutes: number | null,\n  nextResponseMinutes: number | null,\n};\n\nexport const DEFAULT_SUPPORT_SLA: SupportSlaConfig = {\n  enabled: false,\n  firstResponseMinutes: null,\n  nextResponseMinutes: null,\n};\n\nfunction addMinutesOrNull(now: Date, minutes: number | null): Date | null {\n  if (minutes == null || !Number.isFinite(minutes) || minutes <= 0) return null;\n  return new Date(now.getTime() + minutes * 60_000);\n}\n\n/**\n * Returns the target first-response due timestamp for a new conversation,\n * or `null` if SLA tracking is off or no target is set.\n */\nexport function computeFirstResponseDueAt(\n  now: Date,\n  sla: SupportSlaConfig,\n): Date | null {\n  if (!sla.enabled) return null;\n  return addMinutesOrNull(now, sla.firstResponseMinutes);\n}\n\n/**\n * Returns the target next-response due timestamp when a conversation has been\n * re-opened by a user reply, or `null` if SLA tracking is off or no target\n * is set.\n */\nexport function computeNextResponseDueAt(\n  now: Date,\n  sla: SupportSlaConfig,\n): Date | null {\n  if (!sla.enabled) return null;\n  return addMinutesOrNull(now, sla.nextResponseMinutes);\n}\n\nexport type SlaUrgency = \"ok\" | \"warning\" | \"urgent\" | \"overdue\";\n\n/**\n * How soon (in milliseconds) before a due timestamp we switch into the\n * \"urgent\" state. Within this window the due timestamp should be rendered\n * with a strong alert treatment.\n */\nexport const SLA_URGENT_THRESHOLD_MS = 15 * 60 * 1000;\n\n/**\n * How soon (in milliseconds) before a due timestamp we switch into the\n * \"warning\" state. Within this window the due timestamp should be rendered\n * with a subtle alert treatment so agents can notice it without being\n * distracted.\n */\nexport const SLA_WARNING_THRESHOLD_MS = 60 * 60 * 1000;\n\n/**\n * Classifies how close a due timestamp is to `now` so we can subtly alert\n * agents as it approaches (and after it passes).\n *\n * If `windowStartedAt` is provided, thresholds scale with the total SLA\n * window length - so a 5-minute SLA doesn't read as \"urgent\" from t=0 - and\n * are capped by the fixed wall-clock thresholds so a 24-hour SLA doesn't\n * sit in \"warning\" for 12 hours. If `windowStartedAt` isn't known, we fall\n * back to the fixed wall-clock thresholds.\n */\nexport function computeSlaUrgency(\n  dueAt: Date,\n  now: Date,\n  options?: { windowStartedAt?: Date | null },\n): SlaUrgency {\n  const remainingMs = dueAt.getTime() - now.getTime();\n  if (remainingMs <= 0) return \"overdue\";\n\n  const windowStartedAt = options?.windowStartedAt ?? null;\n  const totalWindowMs = windowStartedAt != null\n    ? Math.max(1, dueAt.getTime() - windowStartedAt.getTime())\n    : null;\n\n  const urgentThresholdMs = totalWindowMs != null\n    ? Math.min(totalWindowMs * 0.25, SLA_URGENT_THRESHOLD_MS)\n    : SLA_URGENT_THRESHOLD_MS;\n  const warningThresholdMs = totalWindowMs != null\n    ? Math.min(totalWindowMs * 0.5, SLA_WARNING_THRESHOLD_MS)\n    : SLA_WARNING_THRESHOLD_MS;\n\n  if (remainingMs <= urgentThresholdMs) return \"urgent\";\n  if (remainingMs <= warningThresholdMs) return \"warning\";\n  return \"ok\";\n}\n"],"mappings":";AAMA,MAAa,sBAAwC;CACnD,SAAS;CACT,sBAAsB;CACtB,qBAAqB;CACtB;AAED,SAAS,iBAAiB,KAAW,SAAqC;AACxE,KAAI,WAAW,QAAQ,CAAC,OAAO,SAAS,QAAQ,IAAI,WAAW,EAAG,QAAO;AACzE,QAAO,IAAI,KAAK,IAAI,SAAS,GAAG,UAAU,IAAO;;;;;;AAOnD,SAAgB,0BACd,KACA,KACa;AACb,KAAI,CAAC,IAAI,QAAS,QAAO;AACzB,QAAO,iBAAiB,KAAK,IAAI,qBAAqB;;;;;;;AAQxD,SAAgB,yBACd,KACA,KACa;AACb,KAAI,CAAC,IAAI,QAAS,QAAO;AACzB,QAAO,iBAAiB,KAAK,IAAI,oBAAoB;;;;;;;AAUvD,MAAa,0BAA0B,MAAU;;;;;;;AAQjD,MAAa,2BAA2B,OAAU;;;;;;;;;;;AAYlD,SAAgB,kBACd,OACA,KACA,SACY;CACZ,MAAM,cAAc,MAAM,SAAS,GAAG,IAAI,SAAS;AACnD,KAAI,eAAe,EAAG,QAAO;CAE7B,MAAM,kBAAkB,SAAS,mBAAmB;CACpD,MAAM,gBAAgB,mBAAmB,OACrC,KAAK,IAAI,GAAG,MAAM,SAAS,GAAG,gBAAgB,SAAS,CAAC,GACxD;CAEJ,MAAM,oBAAoB,iBAAiB,OACvC,KAAK,IAAI,gBAAgB,KAAM,wBAAwB,GACvD;CACJ,MAAM,qBAAqB,iBAAiB,OACxC,KAAK,IAAI,gBAAgB,IAAK,yBAAyB,GACvD;AAEJ,KAAI,eAAe,kBAAmB,QAAO;AAC7C,KAAI,eAAe,mBAAoB,QAAO;AAC9C,QAAO"}

package/dist/esm/helpers/support-sla.test.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/esm/helpers/support-sla.test.js

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { SLA_URGENT_THRESHOLD_MS, SLA_WARNING_THRESHOLD_MS, computeFirstResponseDueAt, computeNextResponseDueAt, computeSlaUrgency } from "./support-sla.js";
+
+//#region src/helpers/support-sla.test.ts
+const enabledSla = {
+	enabled: true,
+	firstResponseMinutes: 60,
+	nextResponseMinutes: 120
+};
+describe("computeFirstResponseDueAt", () => {
+	const now = /* @__PURE__ */ new Date("2026-04-22T12:00:00.000Z");
+	it("returns null when SLA is disabled", () => {
+		expect(computeFirstResponseDueAt(now, {
+			...enabledSla,
+			enabled: false
+		})).toBeNull();
+	});
+	it("returns null when no target is set", () => {
+		expect(computeFirstResponseDueAt(now, {
+			...enabledSla,
+			firstResponseMinutes: null
+		})).toBeNull();
+	});
+	it("adds the configured minutes to now", () => {
+		const due = computeFirstResponseDueAt(now, enabledSla);
+		expect(due).not.toBeNull();
+		expect(due.toISOString()).toBe("2026-04-22T13:00:00.000Z");
+	});
+	it("returns null when the configured value is non-positive", () => {
+		expect(computeFirstResponseDueAt(now, {
+			...enabledSla,
+			firstResponseMinutes: 0
+		})).toBeNull();
+	});
+});
+describe("computeNextResponseDueAt", () => {
+	const now = /* @__PURE__ */ new Date("2026-04-22T12:00:00.000Z");
+	it("returns null when SLA is disabled", () => {
+		expect(computeNextResponseDueAt(now, {
+			...enabledSla,
+			enabled: false
+		})).toBeNull();
+	});
+	it("returns null when no target is set", () => {
+		expect(computeNextResponseDueAt(now, {
+			...enabledSla,
+			nextResponseMinutes: null
+		})).toBeNull();
+	});
+	it("adds the configured next-response minutes to now", () => {
+		expect(computeNextResponseDueAt(now, enabledSla).toISOString()).toBe("2026-04-22T14:00:00.000Z");
+	});
+});
+describe("computeSlaUrgency", () => {
+	const now = /* @__PURE__ */ new Date("2026-04-22T12:00:00.000Z");
+	it("returns 'overdue' when the due timestamp is in the past", () => {
+		expect(computeSlaUrgency(/* @__PURE__ */ new Date(now.getTime() - 1), now)).toBe("overdue");
+		expect(computeSlaUrgency(/* @__PURE__ */ new Date(now.getTime() - 6e4), now)).toBe("overdue");
+	});
+	it("returns 'overdue' when the due timestamp is exactly now", () => {
+		expect(computeSlaUrgency(now, now)).toBe("overdue");
+	});
+	it("returns 'urgent' within the urgent threshold", () => {
+		expect(computeSlaUrgency(new Date(now.getTime() + 6e4), now)).toBe("urgent");
+		expect(computeSlaUrgency(new Date(now.getTime() + SLA_URGENT_THRESHOLD_MS), now)).toBe("urgent");
+	});
+	it("returns 'warning' within the warning threshold", () => {
+		expect(computeSlaUrgency(new Date(now.getTime() + SLA_URGENT_THRESHOLD_MS + 6e4), now)).toBe("warning");
+		expect(computeSlaUrgency(new Date(now.getTime() + SLA_WARNING_THRESHOLD_MS), now)).toBe("warning");
+	});
+	it("returns 'ok' when comfortably before the warning threshold", () => {
+		expect(computeSlaUrgency(new Date(now.getTime() + SLA_WARNING_THRESHOLD_MS + 6e4), now)).toBe("ok");
+		expect(computeSlaUrgency(new Date(now.getTime() + 1440 * 60 * 1e3), now)).toBe("ok");
+	});
+	describe("with a windowStartedAt", () => {
+		it("scales thresholds down for short SLA windows so t=0 is not immediately urgent", () => {
+			const windowStartedAt = now;
+			const dueAt = new Date(now.getTime() + 5 * 6e4);
+			expect(computeSlaUrgency(dueAt, now, { windowStartedAt })).toBe("ok");
+			expect(computeSlaUrgency(dueAt, new Date(now.getTime() + 2 * 6e4), { windowStartedAt })).toBe("ok");
+			expect(computeSlaUrgency(dueAt, new Date(now.getTime() + 3 * 6e4), { windowStartedAt })).toBe("warning");
+			expect(computeSlaUrgency(dueAt, new Date(now.getTime() + 4 * 6e4), { windowStartedAt })).toBe("urgent");
+		});
+		it("caps thresholds at the fixed wall-clock windows for long SLAs", () => {
+			const windowStartedAt = now;
+			const dueAt = new Date(now.getTime() + 1440 * 60 * 1e3);
+			expect(computeSlaUrgency(dueAt, /* @__PURE__ */ new Date(dueAt.getTime() - 7200 * 1e3), { windowStartedAt })).toBe("ok");
+			expect(computeSlaUrgency(dueAt, /* @__PURE__ */ new Date(dueAt.getTime() - 45 * 6e4), { windowStartedAt })).toBe("warning");
+			expect(computeSlaUrgency(dueAt, /* @__PURE__ */ new Date(dueAt.getTime() - 10 * 6e4), { windowStartedAt })).toBe("urgent");
+		});
+		it("falls back to fixed thresholds when windowStartedAt is nullish", () => {
+			const dueAt = new Date(now.getTime() + 30 * 6e4);
+			expect(computeSlaUrgency(dueAt, now)).toBe("warning");
+			expect(computeSlaUrgency(dueAt, now, { windowStartedAt: null })).toBe("warning");
+			expect(computeSlaUrgency(dueAt, now, { windowStartedAt: void 0 })).toBe("warning");
+		});
+	});
+});
+
+//#endregion
+export {  };
+//# sourceMappingURL=support-sla.test.js.map

package/dist/esm/helpers/support-sla.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"support-sla.test.js","names":[],"sources":["../../../src/helpers/support-sla.test.ts"],"sourcesContent":["import { describe, expect, it } from \"vitest\";\nimport {\n  computeFirstResponseDueAt,\n  computeNextResponseDueAt,\n  computeSlaUrgency,\n  SLA_URGENT_THRESHOLD_MS,\n  SLA_WARNING_THRESHOLD_MS,\n  type SupportSlaConfig,\n} from \"./support-sla\";\n\nconst enabledSla: SupportSlaConfig = {\n  enabled: true,\n  firstResponseMinutes: 60,\n  nextResponseMinutes: 120,\n};\n\ndescribe(\"computeFirstResponseDueAt\", () => {\n  const now = new Date(\"2026-04-22T12:00:00.000Z\");\n\n  it(\"returns null when SLA is disabled\", () => {\n    expect(computeFirstResponseDueAt(now, { ...enabledSla, enabled: false })).toBeNull();\n  });\n\n  it(\"returns null when no target is set\", () => {\n    expect(computeFirstResponseDueAt(now, { ...enabledSla, firstResponseMinutes: null })).toBeNull();\n  });\n\n  it(\"adds the configured minutes to now\", () => {\n    const due = computeFirstResponseDueAt(now, enabledSla);\n    expect(due).not.toBeNull();\n    expect(due!.toISOString()).toBe(\"2026-04-22T13:00:00.000Z\");\n  });\n\n  it(\"returns null when the configured value is non-positive\", () => {\n    expect(computeFirstResponseDueAt(now, { ...enabledSla, firstResponseMinutes: 0 })).toBeNull();\n  });\n});\n\ndescribe(\"computeNextResponseDueAt\", () => {\n  const now = new Date(\"2026-04-22T12:00:00.000Z\");\n\n  it(\"returns null when SLA is disabled\", () => {\n    expect(computeNextResponseDueAt(now, { ...enabledSla, enabled: false })).toBeNull();\n  });\n\n  it(\"returns null when no target is set\", () => {\n    expect(computeNextResponseDueAt(now, { ...enabledSla, nextResponseMinutes: null })).toBeNull();\n  });\n\n  it(\"adds the configured next-response minutes to now\", () => {\n    const due = computeNextResponseDueAt(now, enabledSla);\n    expect(due!.toISOString()).toBe(\"2026-04-22T14:00:00.000Z\");\n  });\n});\n\ndescribe(\"computeSlaUrgency\", () => {\n  const now = new Date(\"2026-04-22T12:00:00.000Z\");\n\n  it(\"returns 'overdue' when the due timestamp is in the past\", () => {\n    expect(computeSlaUrgency(new Date(now.getTime() - 1), now)).toBe(\"overdue\");\n    expect(computeSlaUrgency(new Date(now.getTime() - 60_000), now)).toBe(\"overdue\");\n  });\n\n  it(\"returns 'overdue' when the due timestamp is exactly now\", () => {\n    expect(computeSlaUrgency(now, now)).toBe(\"overdue\");\n  });\n\n  it(\"returns 'urgent' within the urgent threshold\", () => {\n    expect(computeSlaUrgency(new Date(now.getTime() + 60_000), now)).toBe(\"urgent\");\n    expect(computeSlaUrgency(new Date(now.getTime() + SLA_URGENT_THRESHOLD_MS), now)).toBe(\"urgent\");\n  });\n\n  it(\"returns 'warning' within the warning threshold\", () => {\n    expect(computeSlaUrgency(new Date(now.getTime() + SLA_URGENT_THRESHOLD_MS + 60_000), now)).toBe(\"warning\");\n    expect(computeSlaUrgency(new Date(now.getTime() + SLA_WARNING_THRESHOLD_MS), now)).toBe(\"warning\");\n  });\n\n  it(\"returns 'ok' when comfortably before the warning threshold\", () => {\n    expect(computeSlaUrgency(new Date(now.getTime() + SLA_WARNING_THRESHOLD_MS + 60_000), now)).toBe(\"ok\");\n    expect(computeSlaUrgency(new Date(now.getTime() + 24 * 60 * 60 * 1000), now)).toBe(\"ok\");\n  });\n\n  describe(\"with a windowStartedAt\", () => {\n    it(\"scales thresholds down for short SLA windows so t=0 is not immediately urgent\", () => {\n      // 5-minute SLA window: due 5 min after it started.\n      const windowStartedAt = now;\n      const dueAt = new Date(now.getTime() + 5 * 60_000);\n      // Right at the start, 5 min remaining — should be 'ok' (>50% of window remaining).\n      expect(computeSlaUrgency(dueAt, now, { windowStartedAt })).toBe(\"ok\");\n      // At t+2min (3 min remaining, 60% of window remaining) — still 'ok'.\n      const twoMinLater = new Date(now.getTime() + 2 * 60_000);\n      expect(computeSlaUrgency(dueAt, twoMinLater, { windowStartedAt })).toBe(\"ok\");\n      // At t+3min (2 min remaining, 40% of window) — 'warning'.\n      const threeMinLater = new Date(now.getTime() + 3 * 60_000);\n      expect(computeSlaUrgency(dueAt, threeMinLater, { windowStartedAt })).toBe(\"warning\");\n      // At t+4min (1 min remaining, 20% of window) — 'urgent'.\n      const fourMinLater = new Date(now.getTime() + 4 * 60_000);\n      expect(computeSlaUrgency(dueAt, fourMinLater, { windowStartedAt })).toBe(\"urgent\");\n    });\n\n    it(\"caps thresholds at the fixed wall-clock windows for long SLAs\", () => {\n      // 24-hour SLA window.\n      const windowStartedAt = now;\n      const dueAt = new Date(now.getTime() + 24 * 60 * 60 * 1000);\n      // 2 hours remaining (long past the 50% mark of the 24h window) — should\n      // still be 'ok' because the warning cap is 60 min.\n      const tMinusTwoHours = new Date(dueAt.getTime() - 2 * 60 * 60 * 1000);\n      expect(computeSlaUrgency(dueAt, tMinusTwoHours, { windowStartedAt })).toBe(\"ok\");\n      // 45 minutes remaining — 'warning' (inside the 60-min cap).\n      const tMinus45Min = new Date(dueAt.getTime() - 45 * 60_000);\n      expect(computeSlaUrgency(dueAt, tMinus45Min, { windowStartedAt })).toBe(\"warning\");\n      // 10 minutes remaining — 'urgent' (inside the 15-min cap).\n      const tMinus10Min = new Date(dueAt.getTime() - 10 * 60_000);\n      expect(computeSlaUrgency(dueAt, tMinus10Min, { windowStartedAt })).toBe(\"urgent\");\n    });\n\n    it(\"falls back to fixed thresholds when windowStartedAt is nullish\", () => {\n      const dueAt = new Date(now.getTime() + 30 * 60_000);\n      expect(computeSlaUrgency(dueAt, now)).toBe(\"warning\");\n      expect(computeSlaUrgency(dueAt, now, { windowStartedAt: null })).toBe(\"warning\");\n      expect(computeSlaUrgency(dueAt, now, { windowStartedAt: undefined })).toBe(\"warning\");\n    });\n  });\n});\n"],"mappings":"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"}

package/dist/esm/helpers/vault/client-side.d.ts

@@ -0,0 +1,16 @@
+//#region src/helpers/vault/client-side.d.ts
+/**
+ * Use to hash the key so the server cannot infer it.
+ */
+declare function hashKey(secret: string, key: string): Promise<string>;
+/**
+ * Use to encrypt the value so that the server cannot read the value without knowing the key.
+ */
+declare function encryptValue(secret: string, key: string, value: string): Promise<string>;
+/**
+ * Use to decrypt the value. See encryptValue.
+ */
+declare function decryptValue(secret: string, key: string, encryptedValue: string): Promise<string>;
+//#endregion
+export { decryptValue, encryptValue, hashKey };
+//# sourceMappingURL=client-side.d.ts.map

package/dist/esm/helpers/vault/client-side.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-side.d.ts","names":[],"sources":["../../../../src/helpers/vault/client-side.ts"],"mappings":";;AAoBA;;iBAAsB,OAAA,CAAQ,MAAA,UAAgB,GAAA,WAAW,OAAA;;;;iBAWnC,YAAA,CAAa,MAAA,UAAgB,GAAA,UAAa,KAAA,WAAa,OAAA;;;AAA7E;iBAcsB,YAAA,CAAa,MAAA,UAAgB,GAAA,UAAa,cAAA,WAAsB,OAAA"}

package/dist/esm/helpers/vault/client-side.js

@@ -0,0 +1,69 @@
+import { decodeBase64, encodeBase64 } from "../../utils/bytes.js";
+import { decrypt, encrypt, hash, iteratedHash } from "../../utils/crypto.js";
+
+//#region src/helpers/vault/client-side.ts
+const hashPurpose = "stack-data-vault-client-side-encryption-key-hash";
+const encryptionSecretPurpose = "stack-data-vault-client-side-encryption-value-encryption-key-hash";
+const encryptionValuePurpose = "stack-data-vault-client-side-encryption-value-encryption-value-encryption";
+async function getDerivedKey(secret, key) {
+	return await iteratedHash({
+		purpose: encryptionSecretPurpose,
+		extra: secret,
+		value: key,
+		iterations: 1e5
+	});
+}
+/**
+* Use to hash the key so the server cannot infer it.
+*/
+async function hashKey(secret, key) {
+	return encodeBase64(await hash({
+		purpose: hashPurpose,
+		extra: secret,
+		value: await getDerivedKey(secret, key)
+	}));
+}
+/**
+* Use to encrypt the value so that the server cannot read the value without knowing the key.
+*/
+async function encryptValue(secret, key, value) {
+	return encodeBase64(await encrypt({
+		purpose: encryptionValuePurpose,
+		secret: await getDerivedKey(secret, key),
+		value: new TextEncoder().encode(value)
+	}));
+}
+/**
+* Use to decrypt the value. See encryptValue.
+*/
+async function decryptValue(secret, key, encryptedValue) {
+	const bytesResult = await decrypt({
+		purpose: encryptionValuePurpose,
+		secret: await getDerivedKey(secret, key),
+		cipher: decodeBase64(encryptedValue)
+	});
+	if (bytesResult.status === "error") throw new Error("Data vault client-side decryption failed. Are you sure you're using the correct secret?", { cause: bytesResult.error });
+	return new TextDecoder().decode(bytesResult.data);
+}
+(void 0)?.describe("encryptValue & decryptValue", () => {
+	(void 0)?.it("should encrypt and decrypt a value", async ({ expect }) => {
+		const secret = "test-secret";
+		const value = "test-value";
+		expect(await decryptValue(secret, "key", await encryptValue(secret, "key", value))).toEqual(value);
+	});
+	(void 0)?.it("should not decrypt a value with a different secret", async ({ expect }) => {
+		await expect(decryptValue("different-secret", "key", await encryptValue("test-secret", "key", "test-value"))).rejects.toThrow();
+	});
+	(void 0)?.it("should not decrypt a value with a different key", async ({ expect }) => {
+		const secret = "test-secret";
+		await expect(decryptValue(secret, "different-key", await encryptValue(secret, "key", "test-value"))).rejects.toThrow();
+	});
+	(void 0)?.it("should not decrypt a value if the cipher was tampered with", async ({ expect }) => {
+		const secret = "test-secret";
+		await expect(decryptValue(secret, "key", await encryptValue(secret, "key", "test-value") + "7")).rejects.toThrow();
+	});
+});
+
+//#endregion
+export { decryptValue, encryptValue, hashKey };
+//# sourceMappingURL=client-side.js.map

package/dist/esm/helpers/vault/client-side.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-side.js","names":[],"sources":["../../../../src/helpers/vault/client-side.ts"],"sourcesContent":["import { decodeBase64, encodeBase64 } from \"../../utils/bytes\";\nimport { decrypt, encrypt, hash, iteratedHash } from \"../../utils/crypto\";\n\nconst hashPurpose = \"stack-data-vault-client-side-encryption-key-hash\";\nconst encryptionSecretPurpose = \"stack-data-vault-client-side-encryption-value-encryption-key-hash\";\nconst encryptionValuePurpose = \"stack-data-vault-client-side-encryption-value-encryption-value-encryption\";\n\n\nasync function getDerivedKey(secret: string, key: string) {\n  return await iteratedHash({\n    purpose: encryptionSecretPurpose,\n    extra: secret,\n    value: key,\n    iterations: 100_000,\n  });\n}\n\n/**\n * Use to hash the key so the server cannot infer it.\n */\nexport async function hashKey(secret: string, key: string) {\n  return encodeBase64(await hash({\n    purpose: hashPurpose,\n    extra: secret,\n    value: await getDerivedKey(secret, key),\n  }));\n}\n\n/**\n * Use to encrypt the value so that the server cannot read the value without knowing the key.\n */\nexport async function encryptValue(secret: string, key: string, value: string) {\n  const valueEncryptionDerivedKey = await getDerivedKey(secret, key);\n\n  const bytes = await encrypt({\n    purpose: encryptionValuePurpose,\n    secret: valueEncryptionDerivedKey,\n    value: new TextEncoder().encode(value)\n  });\n  return encodeBase64(bytes);\n}\n\n/**\n * Use to decrypt the value. See encryptValue.\n */\nexport async function decryptValue(secret: string, key: string, encryptedValue: string) {\n  const valueEncryptionDerivedKey = await getDerivedKey(secret, key);\n\n  const bytesResult = await decrypt({\n    purpose: encryptionValuePurpose,\n    secret: valueEncryptionDerivedKey,\n    cipher: decodeBase64(encryptedValue),\n  });\n  if (bytesResult.status === \"error\") throw new Error(\"Data vault client-side decryption failed. Are you sure you're using the correct secret?\", { cause: bytesResult.error });\n  return new TextDecoder().decode(bytesResult.data);\n}\n\n\nimport.meta.vitest?.describe(\"encryptValue & decryptValue\", () => {\n  import.meta.vitest?.it(\"should encrypt and decrypt a value\", async ({ expect }) => {\n    const secret = \"test-secret\";\n    const value = \"test-value\";\n    const encrypted = await encryptValue(secret, \"key\", value);\n    const decrypted = await decryptValue(secret, \"key\", encrypted);\n    expect(decrypted).toEqual(value);\n  });\n\n  import.meta.vitest?.it(\"should not decrypt a value with a different secret\", async ({ expect }) => {\n    const secret = \"test-secret\";\n    const value = \"test-value\";\n    const encrypted = await encryptValue(secret, \"key\", value);\n    await expect(decryptValue(\"different-secret\", \"key\", encrypted)).rejects.toThrow();\n  });\n\n  import.meta.vitest?.it(\"should not decrypt a value with a different key\", async ({ expect }) => {\n    const secret = \"test-secret\";\n    const value = \"test-value\";\n    const encrypted = await encryptValue(secret, \"key\", value);\n    await expect(decryptValue(secret, \"different-key\", encrypted)).rejects.toThrow();\n  });\n\n  import.meta.vitest?.it(\"should not decrypt a value if the cipher was tampered with\", async ({ expect }) => {\n    const secret = \"test-secret\";\n    const value = \"test-value\";\n    const encrypted = await encryptValue(secret, \"key\", value);\n    const tampered = encrypted + \"7\";\n    await expect(decryptValue(secret, \"key\", tampered)).rejects.toThrow();\n  });\n});\n"],"mappings":";;;;AAGA,MAAM,cAAc;AACpB,MAAM,0BAA0B;AAChC,MAAM,yBAAyB;AAG/B,eAAe,cAAc,QAAgB,KAAa;AACxD,QAAO,MAAM,aAAa;EACxB,SAAS;EACT,OAAO;EACP,OAAO;EACP,YAAY;EACb,CAAC;;;;;AAMJ,eAAsB,QAAQ,QAAgB,KAAa;AACzD,QAAO,aAAa,MAAM,KAAK;EAC7B,SAAS;EACT,OAAO;EACP,OAAO,MAAM,cAAc,QAAQ,IAAI;EACxC,CAAC,CAAC;;;;;AAML,eAAsB,aAAa,QAAgB,KAAa,OAAe;AAQ7E,QAAO,aALO,MAAM,QAAQ;EAC1B,SAAS;EACT,QAJgC,MAAM,cAAc,QAAQ,IAAI;EAKhE,OAAO,IAAI,aAAa,CAAC,OAAO,MAAK;EACtC,CAAC,CACwB;;;;;AAM5B,eAAsB,aAAa,QAAgB,KAAa,gBAAwB;CAGtF,MAAM,cAAc,MAAM,QAAQ;EAChC,SAAS;EACT,QAJgC,MAAM,cAAc,QAAQ,IAAI;EAKhE,QAAQ,aAAa,eAAe;EACrC,CAAC;AACF,KAAI,YAAY,WAAW,QAAS,OAAM,IAAI,MAAM,2FAA2F,EAAE,OAAO,YAAY,OAAO,CAAC;AAC5K,QAAO,IAAI,aAAa,CAAC,OAAO,YAAY,KAAK;;CAInD,SAAW,SAAS,qCAAqC;AACvD,WAAW,GAAC,sCAAwC,OAAO,EAAE,aAAS;EACpE,MAAM,SAAS;EACf,MAAM,QAAQ;AAGd,SADkB,MAAM,aAAa,QAAQ,OAD3B,MAAM,aAAa,QAAQ,OAAO,MAAM,CACI,CAC7C,CAAC,QAAQ,MAAM;GAChC;AAEF,WAAW,GAAC,sDAAwD,OAAO,EAAE,aAAS;AAIpF,QAAM,OAAO,aAAa,oBAAoB,OAD5B,MAAM,aAFT,eAE8B,OAD/B,aAC4C,CACK,CAAC,CAAC,QAAQ,SAAS;GAClF;AAEF,WAAW,GAAC,mDAA8C,OAAc,EAAE,aAAS;EACjF,MAAM,SAAS;AAGf,QAAM,OAAO,aAAa,QAAQ,iBADhB,MAAM,aAAa,QAAQ,OAD/B,aAC4C,CACG,CAAC,CAAC,QAAQ,SAAS;GAChF;AAEF,WAAW,GAAC,8DAAyD,OAAc,EAAE,aAAS;EAC5F,MAAM,SAAS;AAIf,QAAM,OAAO,aAAa,QAAQ,OAFhB,MAAM,aAAa,QAAQ,OAD/B,aAC4C,GAC7B,IACqB,CAAC,CAAC,QAAQ,SAAS;GACrE;EACF"}

package/dist/esm/helpers/vault/server-side.d.ts

@@ -0,0 +1,9 @@
+//#region src/helpers/vault/server-side.d.ts
+declare function encryptWithKms(value: string): Promise<{
+  edkBase64: string;
+  ciphertextBase64: string;
+}>;
+declare function decryptWithKms(encrypted: Awaited<ReturnType<typeof encryptWithKms>>): Promise<string>;
+//#endregion
+export { decryptWithKms, encryptWithKms };
+//# sourceMappingURL=server-side.d.ts.map

package/dist/esm/helpers/vault/server-side.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-side.d.ts","names":[],"sources":["../../../../src/helpers/vault/server-side.ts"],"mappings":";iBAyHsB,cAAA,CAAe,KAAA,WAAa,OAAA;;;;iBAc5B,cAAA,CAAe,SAAA,EAAW,OAAA,CAAQ,UAAA,QAAkB,cAAA,KAAgB,OAAA"}

package/dist/esm/helpers/vault/server-side.js

@@ -0,0 +1,123 @@
+import { decodeBase64, encodeBase64 } from "../../utils/bytes.js";
+import { decrypt, encrypt } from "../../utils/crypto.js";
+import { CreateAliasCommand, CreateKeyCommand, DecryptCommand, DescribeKeyCommand, GenerateDataKeyCommand, KMSClient } from "@aws-sdk/client-kms";
+import { getEnvVariable } from "../../utils/env.js";
+import { Result } from "../../utils/results.js";
+
+//#region src/helpers/vault/server-side.ts
+async function getAwsCredentials() {
+	const vercelRoleArn = getEnvVariable("STACK_AWS_VERCEL_OIDC_ROLE_ARN", "");
+	if (vercelRoleArn) {
+		const { awsCredentialsProvider } = await import("@vercel/functions/oidc");
+		return awsCredentialsProvider({ roleArn: vercelRoleArn });
+	}
+	const gcpWifRoleArn = getEnvVariable("STACK_AWS_GCP_WIF_ROLE_ARN", "");
+	if (gcpWifRoleArn) {
+		const { fromWebToken } = await import("@aws-sdk/credential-provider-web-identity");
+		const audience = getEnvVariable("STACK_AWS_GCP_WIF_AUDIENCE", "sts.amazonaws.com");
+		return async () => {
+			return await fromWebToken({
+				roleArn: gcpWifRoleArn,
+				roleSessionName: "stack-backend-cloudrun",
+				webIdentityToken: await fetchGcpIdToken(audience)
+			})();
+		};
+	}
+	return {
+		accessKeyId: getEnvVariable("STACK_AWS_ACCESS_KEY_ID"),
+		secretAccessKey: getEnvVariable("STACK_AWS_SECRET_ACCESS_KEY")
+	};
+}
+/**
+* Fetches a GCP ID token from the metadata server (available on Cloud Run, GCE, GKE).
+* The token is a Google-signed JWT with the specified audience, suitable for
+* AWS STS AssumeRoleWithWebIdentity.
+*/
+async function fetchGcpIdToken(audience) {
+	const metadataUrl = `http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=${encodeURIComponent(audience)}`;
+	const response = await fetch(metadataUrl, { headers: { "Metadata-Flavor": "Google" } });
+	if (!response.ok) throw new Error(`Failed to fetch GCP ID token: ${response.status} ${await response.text()}`);
+	return await response.text();
+}
+let kmsClientCache;
+async function getKmsClient() {
+	if (!kmsClientCache) kmsClientCache = new KMSClient({
+		region: getEnvVariable("STACK_AWS_REGION"),
+		endpoint: getEnvVariable("STACK_AWS_KMS_ENDPOINT"),
+		credentials: await getAwsCredentials()
+	});
+	return kmsClientCache;
+}
+async function getOrCreateKekId() {
+	const id = "alias/stack-data-vault-server-side-kek";
+	const kms = await getKmsClient();
+	try {
+		const describeResult = await kms.send(new DescribeKeyCommand({ KeyId: id }));
+		if (describeResult.KeyMetadata?.KeyId) return describeResult.KeyMetadata.KeyId;
+	} catch (e) {
+		if (e instanceof Error && e.name !== "NotFoundException") throw e;
+	}
+	const { KeyMetadata } = await kms.send(new CreateKeyCommand({
+		KeyUsage: "ENCRYPT_DECRYPT",
+		Description: "DataVault KEK"
+	}));
+	await kms.send(new CreateAliasCommand({
+		AliasName: id,
+		TargetKeyId: KeyMetadata.KeyId
+	}));
+	return id;
+}
+async function genDEK() {
+	const kekId = await getOrCreateKekId();
+	const out = await (await getKmsClient()).send(new GenerateDataKeyCommand({
+		KeyId: kekId,
+		KeySpec: "AES_256"
+	}));
+	if (!out.Plaintext || !out.CiphertextBlob) throw new Error("GenerateDataKey failed");
+	return {
+		dekBytes: out.Plaintext,
+		edkBytes: out.CiphertextBlob
+	};
+}
+async function unwrapDEK(edk_b64) {
+	const edkBytes = decodeBase64(edk_b64);
+	const out = await (await getKmsClient()).send(new DecryptCommand({ CiphertextBlob: edkBytes }));
+	if (!out.Plaintext) throw new Error("KMS Decrypt failed");
+	return {
+		dekBytes: out.Plaintext,
+		edkBytes
+	};
+}
+async function encryptWithKms(value) {
+	const { dekBytes, edkBytes } = await genDEK();
+	try {
+		const ciphertext = await encrypt({
+			purpose: "stack-data-vault-server-side-encryption",
+			secret: dekBytes,
+			value: new TextEncoder().encode(value)
+		});
+		return {
+			edkBase64: encodeBase64(edkBytes),
+			ciphertextBase64: encodeBase64(ciphertext)
+		};
+	} finally {
+		dekBytes.fill(0);
+	}
+}
+async function decryptWithKms(encrypted) {
+	const { dekBytes } = await unwrapDEK(encrypted.edkBase64);
+	try {
+		const value = Result.orThrow(await decrypt({
+			purpose: "stack-data-vault-server-side-encryption",
+			secret: dekBytes,
+			cipher: decodeBase64(encrypted.ciphertextBase64)
+		}));
+		return new TextDecoder().decode(value);
+	} finally {
+		dekBytes.fill(0);
+	}
+}
+
+//#endregion
+export { decryptWithKms, encryptWithKms };
+//# sourceMappingURL=server-side.js.map

package/dist/esm/helpers/vault/server-side.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-side.js","names":[],"sources":["../../../../src/helpers/vault/server-side.ts"],"sourcesContent":["import {\n  CreateAliasCommand,\n  CreateKeyCommand,\n  DecryptCommand,\n  DescribeKeyCommand,\n  GenerateDataKeyCommand,\n  KMSClient\n} from \"@aws-sdk/client-kms\";\nimport { decodeBase64, encodeBase64 } from \"../../utils/bytes\";\nimport { decrypt, encrypt } from \"../../utils/crypto\";\nimport { getEnvVariable } from \"../../utils/env\";\nimport { Result } from \"../../utils/results\";\n\n\nasync function getAwsCredentials() {\n  // 1. Vercel OIDC: Vercel injects an OIDC token that can be exchanged for AWS credentials\n  const vercelRoleArn = getEnvVariable(\"STACK_AWS_VERCEL_OIDC_ROLE_ARN\", \"\");\n  if (vercelRoleArn) {\n    const { awsCredentialsProvider } = await import(\"@vercel/functions/oidc\");\n    return awsCredentialsProvider({ roleArn: vercelRoleArn });\n  }\n\n  // 2. GCP Workload Identity Federation: Cloud Run gets a GCP ID token from the metadata server,\n  //    then exchanges it for temporary AWS credentials via STS AssumeRoleWithWebIdentity.\n  //    Requires:\n  //      - An OIDC identity provider in AWS IAM (issuer: https://accounts.google.com)\n  //      - An IAM role with a trust policy allowing the GCP service account\n  //      - STACK_AWS_GCP_WIF_ROLE_ARN set to that role's ARN\n  //      - STACK_AWS_GCP_WIF_AUDIENCE set to the audience configured in the AWS OIDC provider\n  const gcpWifRoleArn = getEnvVariable(\"STACK_AWS_GCP_WIF_ROLE_ARN\", \"\");\n  if (gcpWifRoleArn) {\n    const { fromWebToken } = await import(\"@aws-sdk/credential-provider-web-identity\");\n    const audience = getEnvVariable(\"STACK_AWS_GCP_WIF_AUDIENCE\", \"sts.amazonaws.com\");\n    // Return a provider that fetches a fresh GCP ID token on each invocation.\n    // GCP metadata tokens expire after ~1h, so we can't bake a single token into the closure.\n    return async () => {\n      return await fromWebToken({\n        roleArn: gcpWifRoleArn,\n        roleSessionName: \"stack-backend-cloudrun\",\n        webIdentityToken: await fetchGcpIdToken(audience),\n      })();\n    };\n  }\n\n  // 3. Static credentials: fallback for self-hosted / local development\n  return {\n    accessKeyId: getEnvVariable(\"STACK_AWS_ACCESS_KEY_ID\"),\n    secretAccessKey: getEnvVariable(\"STACK_AWS_SECRET_ACCESS_KEY\"),\n  };\n}\n\n/**\n * Fetches a GCP ID token from the metadata server (available on Cloud Run, GCE, GKE).\n * The token is a Google-signed JWT with the specified audience, suitable for\n * AWS STS AssumeRoleWithWebIdentity.\n */\nasync function fetchGcpIdToken(audience: string): Promise<string> {\n  const metadataUrl = `http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=${encodeURIComponent(audience)}`;\n  const response = await fetch(metadataUrl, {\n    headers: { \"Metadata-Flavor\": \"Google\" },\n  });\n  if (!response.ok) {\n    throw new Error(`Failed to fetch GCP ID token: ${response.status} ${await response.text()}`);\n  }\n  return await response.text();\n}\n\nlet kmsClientCache: KMSClient | undefined;\n\nasync function getKmsClient() {\n  if (!kmsClientCache) {\n    kmsClientCache = new KMSClient({\n      region: getEnvVariable(\"STACK_AWS_REGION\"),\n      endpoint: getEnvVariable(\"STACK_AWS_KMS_ENDPOINT\"),\n      credentials: await getAwsCredentials(),\n    });\n  }\n  return kmsClientCache;\n}\n\nasync function getOrCreateKekId(): Promise<string> {\n  const id = \"alias/stack-data-vault-server-side-kek\";\n  const kms = await getKmsClient();\n  try {\n    const describeResult = await kms.send(new DescribeKeyCommand({ KeyId: id }));\n    if (describeResult.KeyMetadata?.KeyId) return describeResult.KeyMetadata.KeyId;\n  } catch (e) {\n    if (e instanceof Error && e.name !== \"NotFoundException\") {\n      throw e;\n    }\n  }\n  const { KeyMetadata } = await kms.send(new CreateKeyCommand({\n    KeyUsage: \"ENCRYPT_DECRYPT\",\n    Description: \"DataVault KEK\"\n  }));\n  await kms.send(new CreateAliasCommand({ AliasName: id, TargetKeyId: KeyMetadata!.KeyId! }));\n  return id;\n}\n\nasync function genDEK() {\n  const kekId = await getOrCreateKekId();\n  const kms = await getKmsClient();\n  const out = await kms.send(new GenerateDataKeyCommand({ KeyId: kekId, KeySpec: \"AES_256\" }));\n  if (!out.Plaintext || !out.CiphertextBlob) throw new Error(\"GenerateDataKey failed\");\n  return {\n    dekBytes: out.Plaintext,\n    edkBytes: out.CiphertextBlob,\n  };\n}\n\nasync function unwrapDEK(edk_b64: string) {\n  const edkBytes = decodeBase64(edk_b64);\n  const kms = await getKmsClient();\n  const out = await kms.send(new DecryptCommand({ CiphertextBlob: edkBytes }));\n  if (!out.Plaintext) throw new Error(\"KMS Decrypt failed\");\n  return {\n    dekBytes: out.Plaintext,\n    edkBytes,\n  };\n}\n\nexport async function encryptWithKms(value: string) {\n  const { dekBytes, edkBytes } = await genDEK();\n  try {\n    const ciphertext = await encrypt({\n      purpose: \"stack-data-vault-server-side-encryption\",\n      secret: dekBytes,\n      value: new TextEncoder().encode(value),\n    });\n    return { edkBase64: encodeBase64(edkBytes), ciphertextBase64: encodeBase64(ciphertext) };\n  } finally {\n    dekBytes.fill(0);\n  }\n}\n\nexport async function decryptWithKms(encrypted: Awaited<ReturnType<typeof encryptWithKms>>) {\n  const { dekBytes } = await unwrapDEK(encrypted.edkBase64);\n  try {\n    const value = Result.orThrow(await decrypt({\n      purpose: \"stack-data-vault-server-side-encryption\",\n      secret: dekBytes,\n      cipher: decodeBase64(encrypted.ciphertextBase64),\n    }));\n    return new TextDecoder().decode(value);\n  } finally {\n    dekBytes.fill(0);\n  }\n}\n"],"mappings":"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"}

package/dist/esm/hooks/use-async-callback.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+
+//#region src/hooks/use-async-callback.d.ts
+declare function useAsyncCallback<A extends any[], R>(callback: (...args: A) => Promise<R>, deps: React.DependencyList): [cb: (...args: A) => Promise<R>, loading: boolean, error: unknown | undefined];
+declare function useAsyncCallbackWithLoggedError<A extends any[], R>(callback: (...args: A) => Promise<R>, deps: React.DependencyList): [cb: (...args: A) => Promise<R>, loading: boolean];
+//#endregion
+export { useAsyncCallback, useAsyncCallbackWithLoggedError };
+//# sourceMappingURL=use-async-callback.d.ts.map

package/dist/esm/hooks/use-async-callback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-async-callback.d.ts","names":[],"sources":["../../../src/hooks/use-async-callback.tsx"],"mappings":";;;iBAGgB,gBAAA,oBAAA,CACd,QAAA,MAAc,IAAA,EAAM,CAAA,KAAM,OAAA,CAAQ,CAAA,GAClC,IAAA,EAAM,KAAA,CAAM,cAAA,IACV,EAAA,MAAQ,IAAA,EAAM,CAAA,KAAM,OAAA,CAAQ,CAAA,GAAI,OAAA,WAAkB,KAAA;AAAA,iBAsBtC,+BAAA,oBAAA,CACd,QAAA,MAAc,IAAA,EAAM,CAAA,KAAM,OAAA,CAAQ,CAAA,GAClC,IAAA,EAAM,KAAA,CAAM,cAAA,IACV,EAAA,MAAQ,IAAA,EAAM,CAAA,KAAM,OAAA,CAAQ,CAAA,GAAI,OAAA"}