@hexclave/shared 1.0.3 → 1.0.6

package/src/helpers/vault/client-side.ts

@@ -0,0 +1,92 @@
+import { decodeBase64, encodeBase64 } from "../../utils/bytes";
+import { decrypt, encrypt, hash, iteratedHash } from "../../utils/crypto";
+
+// NOTE (Hexclave rebrand): do NOT rename these "stack-*" purpose tags. They are mixed into the
+// vault's key derivation and value encryption; renaming any of them would make every
+// previously-stored vault value undecryptable. Internal constants, never user-visible.
+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: string, key: string) {
+  return await iteratedHash({
+    purpose: encryptionSecretPurpose,
+    extra: secret,
+    value: key,
+    iterations: 100_000,
+  });
+}
+
+/**
+ * Use to hash the key so the server cannot infer it.
+ */
+export async function hashKey(secret: string, key: string) {
+  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.
+ */
+export async function encryptValue(secret: string, key: string, value: string) {
+  const valueEncryptionDerivedKey = await getDerivedKey(secret, key);
+
+  const bytes = await encrypt({
+    purpose: encryptionValuePurpose,
+    secret: valueEncryptionDerivedKey,
+    value: new TextEncoder().encode(value)
+  });
+  return encodeBase64(bytes);
+}
+
+/**
+ * Use to decrypt the value. See encryptValue.
+ */
+export async function decryptValue(secret: string, key: string, encryptedValue: string) {
+  const valueEncryptionDerivedKey = await getDerivedKey(secret, key);
+
+  const bytesResult = await decrypt({
+    purpose: encryptionValuePurpose,
+    secret: valueEncryptionDerivedKey,
+    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);
+}
+
+
+import.meta.vitest?.describe("encryptValue & decryptValue", () => {
+  import.meta.vitest?.it("should encrypt and decrypt a value", async ({ expect }) => {
+    const secret = "test-secret";
+    const value = "test-value";
+    const encrypted = await encryptValue(secret, "key", value);
+    const decrypted = await decryptValue(secret, "key", encrypted);
+    expect(decrypted).toEqual(value);
+  });
+
+  import.meta.vitest?.it("should not decrypt a value with a different secret", async ({ expect }) => {
+    const secret = "test-secret";
+    const value = "test-value";
+    const encrypted = await encryptValue(secret, "key", value);
+    await expect(decryptValue("different-secret", "key", encrypted)).rejects.toThrow();
+  });
+
+  import.meta.vitest?.it("should not decrypt a value with a different key", async ({ expect }) => {
+    const secret = "test-secret";
+    const value = "test-value";
+    const encrypted = await encryptValue(secret, "key", value);
+    await expect(decryptValue(secret, "different-key", encrypted)).rejects.toThrow();
+  });
+
+  import.meta.vitest?.it("should not decrypt a value if the cipher was tampered with", async ({ expect }) => {
+    const secret = "test-secret";
+    const value = "test-value";
+    const encrypted = await encryptValue(secret, "key", value);
+    const tampered = encrypted + "7";
+    await expect(decryptValue(secret, "key", tampered)).rejects.toThrow();
+  });
+});

package/src/helpers/vault/server-side.ts

@@ -0,0 +1,153 @@
+import {
+  CreateAliasCommand,
+  CreateKeyCommand,
+  DecryptCommand,
+  DescribeKeyCommand,
+  GenerateDataKeyCommand,
+  KMSClient
+} from "@aws-sdk/client-kms";
+import { decodeBase64, encodeBase64 } from "../../utils/bytes";
+import { decrypt, encrypt } from "../../utils/crypto";
+import { getEnvVariable } from "../../utils/env";
+import { Result } from "../../utils/results";
+
+
+async function getAwsCredentials() {
+  // 1. Vercel OIDC: Vercel injects an OIDC token that can be exchanged for AWS credentials
+  const vercelRoleArn = getEnvVariable("STACK_AWS_VERCEL_OIDC_ROLE_ARN", "");
+  if (vercelRoleArn) {
+    const { awsCredentialsProvider } = await import("@vercel/functions/oidc");
+    return awsCredentialsProvider({ roleArn: vercelRoleArn });
+  }
+
+  // 2. GCP Workload Identity Federation: Cloud Run gets a GCP ID token from the metadata server,
+  //    then exchanges it for temporary AWS credentials via STS AssumeRoleWithWebIdentity.
+  //    Requires:
+  //      - An OIDC identity provider in AWS IAM (issuer: https://accounts.google.com)
+  //      - An IAM role with a trust policy allowing the GCP service account
+  //      - STACK_AWS_GCP_WIF_ROLE_ARN set to that role's ARN
+  //      - STACK_AWS_GCP_WIF_AUDIENCE set to the audience configured in the AWS OIDC provider
+  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 a provider that fetches a fresh GCP ID token on each invocation.
+    // GCP metadata tokens expire after ~1h, so we can't bake a single token into the closure.
+    return async () => {
+      return await fromWebToken({
+        roleArn: gcpWifRoleArn,
+        roleSessionName: "stack-backend-cloudrun",
+        webIdentityToken: await fetchGcpIdToken(audience),
+      })();
+    };
+  }
+
+  // 3. Static credentials: fallback for self-hosted / local development
+  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: string): Promise<string> {
+  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: KMSClient | undefined;
+
+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(): Promise<string> {
+  // NOTE (Hexclave rebrand): do NOT rename this "stack-*" alias. It is the AWS KMS key alias for
+  // the existing key-encryption key; renaming it would point at a non-existent key and break
+  // wrap/unwrap of all stored data keys. Internal infrastructure constant, never user-visible.
+  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 kms = await getKmsClient();
+  const out = await kms.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: string) {
+  const edkBytes = decodeBase64(edk_b64);
+  const kms = await getKmsClient();
+  const out = await kms.send(new DecryptCommand({ CiphertextBlob: edkBytes }));
+  if (!out.Plaintext) throw new Error("KMS Decrypt failed");
+  return {
+    dekBytes: out.Plaintext,
+    edkBytes,
+  };
+}
+
+export async function encryptWithKms(value: string) {
+  const { dekBytes, edkBytes } = await genDEK();
+  try {
+    const ciphertext = await encrypt({
+      // NOTE (Hexclave rebrand): do NOT rename this "stack-*" purpose tag — it must match the one
+      // used in decryptWithKms below, or already-encrypted values become undecryptable.
+      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);
+  }
+}
+
+export async function decryptWithKms(encrypted: Awaited<ReturnType<typeof encryptWithKms>>) {
+  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);
+  }
+}

package/src/hexclave-config-file.ts

@@ -0,0 +1,120 @@
+import * as parser from "@babel/parser";
+import * as t from "@babel/types";
+import { isValidConfig, normalize } from "./config/format";
+
+export const showOnboardingHexclaveConfigValue = "show-onboarding";
+
+const DEFAULT_CONFIG_IMPORT_PACKAGE = "@hexclave/js";
+
+/**
+ * Renders a config object into the source text of a `stack.config.ts` file.
+ *
+ * Browser-safe: kept here (next to `parseHexclaveConfigFileContent`) instead of in
+ * `config-rendering.ts` so dashboard client code can render config files
+ * without pulling in `fs` / `path`.
+ */
+export function renderConfigFileContent(config: unknown, importPackage?: string): string {
+  if (!isValidConfig(config)) {
+    throw new Error("Invalid config: expected a plain object.");
+  }
+
+  const droppedKeys: string[] = [];
+  const normalizedConfig = normalize(config, {
+    onDotIntoNonObject: "ignore",
+    onDotIntoNull: "empty-object",
+    droppedKeys,
+  });
+  if (droppedKeys.length > 0) {
+    throw new Error(`Config has conflicting keys that would be dropped during normalization: ${droppedKeys.map(k => JSON.stringify(k)).join(", ")}`);
+  }
+  const pkg = importPackage ?? DEFAULT_CONFIG_IMPORT_PACKAGE;
+  const importLine = `import type { HexclaveConfig } from "${pkg}";`;
+  return `${importLine}\n\nexport const config: HexclaveConfig = ${JSON.stringify(normalizedConfig, null, 2)};\n`;
+}
+
+type ParsedStackConfig = Record<string, unknown> | typeof showOnboardingHexclaveConfigValue;
+
+function unwrapStaticConfigExpression(expression: t.Expression): t.Expression {
+  if (
+    t.isTSAsExpression(expression)
+    || t.isTSSatisfiesExpression(expression)
+    || t.isTSTypeAssertion(expression)
+    || t.isTSNonNullExpression(expression)
+  ) {
+    return unwrapStaticConfigExpression(expression.expression);
+  }
+  return expression;
+}
+
+function evaluateStaticConfigExpression(expression: t.Expression): unknown {
+  const unwrapped = unwrapStaticConfigExpression(expression);
+  if (t.isStringLiteral(unwrapped)) return unwrapped.value;
+  if (t.isBooleanLiteral(unwrapped)) return unwrapped.value;
+  if (t.isNumericLiteral(unwrapped)) return unwrapped.value;
+  if (t.isNullLiteral(unwrapped)) return null;
+  if (t.isIdentifier(unwrapped) && unwrapped.name === "undefined") return undefined;
+  if (t.isUnaryExpression(unwrapped) && unwrapped.operator === "-" && t.isNumericLiteral(unwrapped.argument)) {
+    return -unwrapped.argument.value;
+  }
+  if (t.isArrayExpression(unwrapped)) {
+    return unwrapped.elements.map((element) => {
+      if (element == null || t.isSpreadElement(element)) {
+        throw new Error("Config arrays cannot contain holes or spreads.");
+      }
+      return evaluateStaticConfigExpression(element);
+    });
+  }
+  if (t.isObjectExpression(unwrapped)) {
+    const result: Record<string, unknown> = {};
+    for (const property of unwrapped.properties) {
+      if (t.isSpreadElement(property)) {
+        throw new Error("Config objects cannot contain spreads.");
+      }
+      if (property.computed) {
+        throw new Error("Config object keys cannot be computed.");
+      }
+      const key = t.isIdentifier(property.key)
+        ? property.key.name
+        : t.isStringLiteral(property.key) || t.isNumericLiteral(property.key)
+          ? String(property.key.value)
+          : null;
+      if (key == null) {
+        throw new Error("Unsupported config object key.");
+      }
+      if (t.isObjectMethod(property)) {
+        throw new Error("Config objects cannot contain methods.");
+      }
+      if (!t.isExpression(property.value)) {
+        throw new Error("Unsupported config object value.");
+      }
+      result[key] = evaluateStaticConfigExpression(property.value);
+    }
+    return result;
+  }
+  throw new Error(`Unsupported config expression: ${unwrapped.type}`);
+}
+
+export function parseHexclaveConfigFileContent(content: string, filePath: string): ParsedStackConfig {
+  if (content.trim() === "") return {};
+  const ast = parser.parse(content, {
+    sourceType: "module",
+    plugins: ["typescript"],
+  });
+
+  for (const statement of ast.program.body) {
+    if (!t.isExportNamedDeclaration(statement) || !t.isVariableDeclaration(statement.declaration)) {
+      continue;
+    }
+    for (const declaration of statement.declaration.declarations) {
+      if (!t.isIdentifier(declaration.id) || declaration.id.name !== "config") {
+        continue;
+      }
+      if (declaration.init == null || !t.isExpression(declaration.init)) {
+        throw new Error(`Config export in ${filePath} must have an initializer.`);
+      }
+      return evaluateStaticConfigExpression(declaration.init) as ParsedStackConfig;
+    }
+  }
+
+  throw new Error(`Invalid config in ${filePath}. The file must export a plain \`config\` object or "show-onboarding".`);
+}

package/src/hooks/use-async-callback.tsx

@@ -0,0 +1,43 @@
+import React from "react";
+import { captureError } from "../utils/errors";
+
+export function useAsyncCallback<A extends any[], R>(
+  callback: (...args: A) => Promise<R>,
+  deps: React.DependencyList
+): [cb: (...args: A) => Promise<R>, loading: boolean, error: unknown | undefined] {
+  const [error, setError] = React.useState<unknown | undefined>(undefined);
+  const [loadingCount, setLoadingCount] = React.useState(0);
+
+  const cb = React.useCallback(
+    async (...args: A) => {
+      setLoadingCount((c) => c + 1);
+      try {
+        return await callback(...args);
+      } catch (e) {
+        setError(e);
+        throw e;
+      } finally {
+        setLoadingCount((c) => c - 1);
+      }
+    },
+    deps,
+  );
+
+  return [cb, loadingCount > 0, error];
+}
+
+export function useAsyncCallbackWithLoggedError<A extends any[], R>(
+  callback: (...args: A) => Promise<R>,
+  deps: React.DependencyList
+): [cb: (...args: A) => Promise<R>, loading: boolean] {
+  const [newCallback, loading] = useAsyncCallback<A, R>(async (...args) => {
+    try {
+      return await callback(...args);
+    } catch (e) {
+      captureError("async-callback", e);
+      throw e;
+    }
+  }, deps);
+
+  return [newCallback, loading];
+}

package/src/hooks/use-async-external-store.tsx

@@ -0,0 +1,24 @@
+import { useEffect, useState } from "react";
+import { AsyncResult } from "../utils/results";
+
+export function useAsyncExternalStore<T>(
+  subscribe: (callback: (t: T) => void) => (() => void),
+): AsyncResult<T, never> & { status: "ok" | "pending" } {
+  // sure, the "sync" in useSyncExternalStore refers to "synchronize a store" and not "sync/async", but it's too good of a name to pass up on
+
+  const [isAvailable, setIsAvailable] = useState(false);
+  const [value, setValue] = useState<T>();
+  useEffect(() => {
+    const unsubscribe = subscribe((value: T) => {
+      setValue(() => value);
+      setIsAvailable(() => true);
+    });
+    return unsubscribe;
+  }, [subscribe]);
+
+  if (isAvailable) {
+    return AsyncResult.ok(value as T);
+  } else {
+    return AsyncResult.pending();
+  }
+}

package/src/hooks/use-hash.tsx

@@ -0,0 +1,14 @@
+import { useSyncExternalStore } from "react";
+import { suspendIfSsr } from "../utils/react";
+
+export const useHash = () => {
+  suspendIfSsr("useHash");
+  return useSyncExternalStore(
+    (onChange) => {
+      const interval = setInterval(() => onChange(), 10);
+      return () => clearInterval(interval);
+    },
+    () => window.location.hash.substring(1)
+  );
+};
+

package/src/hooks/use-hover.tsx

@@ -0,0 +1,88 @@
+import { useLayoutEffect } from "react";
+import { useRefState } from "../utils/react";
+
+export function useHover<T extends HTMLElement | null>(
+  ref: React.RefObject<T>,
+  options: {
+    onMouseEnter?: () => void,
+    onMouseLeave?: () => void,
+  } = {},
+): boolean {
+  // Internal counter: mouseenter++ / mouseleave-- (isHovering = counter > 0)
+  const counter = useRefState(0);
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    let incr = 0;
+    let prevInside = false;
+
+    const contains = (r: DOMRect, x: number, y: number) =>
+      x >= r.left && x <= r.right && y >= r.top && y <= r.bottom;
+
+    const enter = () => {
+      incr++;
+      counter.set(c => c + 1);
+      if (counter.current === 1) {
+        options.onMouseEnter?.();
+      }
+    };
+
+    const leave = () => {
+      incr--;
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          counter.set(c => c - 1);
+          if (counter.current === 0) {
+            options.onMouseLeave?.();
+          }
+        });
+      });
+    };
+
+    const topMatchesTarget = (x: number, y: number) => {
+      const top = document.elementFromPoint(x, y);
+      return !!(top && (top === el || el.contains(top)));
+    };
+
+    const processPoint = (x: number, y: number) => {
+      const rect = el.getBoundingClientRect();
+
+      // True “hoverability”: inside rect AND not occluded by others
+      const inside = contains(rect, x, y) && topMatchesTarget(x, y);
+      if (inside && !prevInside) {
+        enter();
+      } else if (!inside && prevInside) {
+        leave();
+      }
+      prevInside = inside;
+    };
+
+    const onMove = (e: PointerEvent) => {
+      if (e.pointerType !== "mouse") return; // keep it hover-only
+      // Use coalesced points when available
+      const batch = e.getCoalescedEvents();
+      if (batch.length) {
+        for (let eventIndex = 0; eventIndex < batch.length - 1; eventIndex++) {
+          const e1 = batch[eventIndex];
+          const e2 = batch[eventIndex + 1];
+          const steps = 10;
+          for (let i = 0; i <= steps; i++) {
+            processPoint(e1.clientX + (e2.clientX - e1.clientX) * i / steps, e1.clientY + (e2.clientY - e1.clientY) * i / steps);
+          }
+        }
+      } else {
+        processPoint(e.clientX, e.clientY);
+      }
+    };
+
+    window.addEventListener("pointermove", onMove, { passive: true });
+
+    return () => {
+      window.removeEventListener("pointermove", onMove);
+      counter.set(c => c - incr);
+    };
+  }, []);
+
+  return counter.current > 0;
+}