@hexclave/shared 1.0.2 → 1.0.5

package/src/utils/cel-fields.ts

@@ -0,0 +1,92 @@
+import { signUpAuthMethodValues } from "./auth-methods";
+import { standardProviders } from "./oauth";
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+export type ConditionField =
+  | 'email'
+  | 'countryCode'
+  | 'emailDomain'
+  | 'authMethod'
+  | 'oauthProvider'
+  | 'riskScores.bot'
+  | 'riskScores.free_trial_abuse';
+
+export type ConditionOperator =
+  | 'equals'
+  | 'not_equals'
+  | 'greater_than'
+  | 'greater_or_equal'
+  | 'less_than'
+  | 'less_or_equal'
+  | 'matches'
+  | 'ends_with'
+  | 'starts_with'
+  | 'contains'
+  | 'in_list';
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+export function isNumericField(field: ConditionField): boolean {
+  return field === 'riskScores.bot' || field === 'riskScores.free_trial_abuse';
+}
+
+/**
+ * Validates a numeric field value is a finite integer within [0, 100].
+ * Returns null if valid, or an error message string if invalid.
+ */
+export function validateNumericFieldValue(field: string, value: string | number): string | null {
+  const num = typeof value === 'number' ? value : Number(value);
+  if (!Number.isFinite(num)) {
+    return `Expected a finite number for field "${field}", got "${String(value)}"`;
+  }
+  if (!Number.isInteger(num)) {
+    return `Expected an integer for field "${field}", got "${String(value)}"`;
+  }
+  if (num < 0 || num > 100) {
+    return `Value for field "${field}" must be between 0 and 100, got ${num}`;
+  }
+  return null;
+}
+
+export function escapeCelString(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+export function unescapeCelString(value: string): string {
+  return value.replace(/\\\\/g, '\\').replace(/\\"/g, '"');
+}
+
+// ── Field metadata ─────────────────────────────────────────────────────
+
+const numericOperators: ConditionOperator[] = ['equals', 'not_equals', 'greater_than', 'greater_or_equal', 'less_than', 'less_or_equal'];
+const enumOperators: ConditionOperator[] = ['equals', 'not_equals', 'in_list'];
+const stringOperators: ConditionOperator[] = ['equals', 'not_equals', 'contains', 'starts_with', 'ends_with', 'matches', 'in_list'];
+
+export type FieldMetadataEntry = {
+  label: string,
+  operators: ConditionOperator[],
+  predefinedValues?: string[],
+};
+
+export const fieldMetadata: Record<ConditionField, FieldMetadataEntry> = {
+  email: { label: 'Email', operators: stringOperators },
+  countryCode: { label: 'Country Code', operators: enumOperators },
+  emailDomain: { label: 'Email Domain', operators: stringOperators },
+  authMethod: { label: 'Auth Method', operators: enumOperators, predefinedValues: [...signUpAuthMethodValues] },
+  oauthProvider: { label: 'OAuth Provider', operators: enumOperators, predefinedValues: [...standardProviders] },
+  'riskScores.bot': { label: 'Risk Score: Bot', operators: numericOperators },
+  'riskScores.free_trial_abuse': { label: 'Risk Score: Free Trial Abuse', operators: numericOperators },
+};
+
+export const conditionFields = Object.keys(fieldMetadata) as ConditionField[];
+
+export const conditionOperators: ConditionOperator[] = [
+  'equals', 'not_equals', 'greater_than', 'greater_or_equal',
+  'less_than', 'less_or_equal', 'matches', 'ends_with',
+  'starts_with', 'contains', 'in_list',
+];
+
+export function getOperatorsForField(field: ConditionField): ConditionOperator[] {
+  return fieldMetadata[field].operators;
+}

package/src/utils/cloud-hosts.tsx

@@ -0,0 +1,92 @@
+/**
+ * Single source of truth for the stack-auth ↔ hexclave host pairs that the
+ * cloud deployment treats as equivalent siblings. Each
+ * `[stackAuthHost, hexclaveHost]` pair is consumed in a few places:
+ *
+ * 1. `CLOUD_API_HOST_BY_REQUEST_HOST` in the backend's `request-api-url.ts` —
+ *    the allowlist of request hosts we resolve into a JWT `iss` claim.
+ * 2. `issuerHostAliases` in `tokens.tsx` — the bidirectional validator alias
+ *    map, so a token issued under either host validates against the other.
+ * 3. `getCloudApiUrlSiblings` below — resolves the branded base URLs used for
+ *    OAuth `redirect_uri` callbacks (both at runtime and in the dashboard).
+ *
+ * Deriving all of these from this one list prevents drift.
+ */
+export const CLOUD_HOST_PAIRS: ReadonlyArray<readonly [string, string]> = [
+  ["api.stack-auth.com", "api.hexclave.com"],
+  ["api.dev.stack-auth.com", "api.dev.hexclave.com"],
+  ["api.staging.stack-auth.com", "api.staging.hexclave.com"],
+];
+
+function hostFromApiUrlOrHost(input: string): string | undefined {
+  try {
+    return new URL(input).host.split(":")[0].toLowerCase();
+  } catch {
+    const firstHost = input.split(",")[0]?.trim();
+    if (!firstHost) return undefined;
+    return firstHost.split(":")[0].toLowerCase();
+  }
+}
+
+/**
+ * Given an API URL (or bare host), if its host belongs to a known
+ * stack-auth ↔ hexclave cloud pair, return both branded base URLs. Returns
+ * null for unknown hosts (localhost, vercel previews, self-host custom
+ * domains).
+ */
+export function getCloudApiUrlSiblings(apiUrlOrHost: string | undefined | null): { stackAuth: string, hexclave: string } | null {
+  if (!apiUrlOrHost) return null;
+  const host = hostFromApiUrlOrHost(apiUrlOrHost);
+  if (!host) return null;
+  for (const [stackAuthHost, hexclaveHost] of CLOUD_HOST_PAIRS) {
+    if (host === stackAuthHost || host === hexclaveHost) {
+      return { stackAuth: `https://${stackAuthHost}`, hexclave: `https://${hexclaveHost}` };
+    }
+  }
+  return null;
+}
+
+/**
+ * The stack-auth-branded base URL for the given deployment API URL. Used as the
+ * OAuth `redirect_uri` base for shared providers and for custom providers that
+ * predate `customCallbackUrl` (so existing flows keep hitting
+ * `api.stack-auth.com`). Unknown hosts fall back to the input unchanged.
+ */
+export function getStackAuthApiBaseUrl(apiUrl: string): string {
+  return getCloudApiUrlSiblings(apiUrl)?.stackAuth ?? apiUrl;
+}
+
+/**
+ * The hexclave-branded base URL for the given deployment API URL. Used when a
+ * new custom OAuth provider is set up, so its `customCallbackUrl` points at the
+ * hexclave brand. Unknown hosts fall back to the input unchanged.
+ */
+export function getHexclaveApiBaseUrl(apiUrl: string): string {
+  return getCloudApiUrlSiblings(apiUrl)?.hexclave ?? apiUrl;
+}
+
+import.meta.vitest?.test("getCloudApiUrlSiblings maps both sides of each cloud pair", ({ expect }) => {
+  for (const [stackAuthHost, hexclaveHost] of CLOUD_HOST_PAIRS) {
+    const expected = { stackAuth: `https://${stackAuthHost}`, hexclave: `https://${hexclaveHost}` };
+    for (const host of [stackAuthHost, hexclaveHost]) {
+      expect(getCloudApiUrlSiblings(host)).toEqual(expected);
+      expect(getCloudApiUrlSiblings(`https://${host}`)).toEqual(expected);
+      expect(getCloudApiUrlSiblings(`https://${host.toUpperCase()}:443`)).toEqual(expected);
+    }
+  }
+});
+
+import.meta.vitest?.test("getCloudApiUrlSiblings returns null for unknown hosts", ({ expect }) => {
+  expect(getCloudApiUrlSiblings("http://localhost:8102")).toBeNull();
+  expect(getCloudApiUrlSiblings("https://my-app.vercel.app")).toBeNull();
+  expect(getCloudApiUrlSiblings(undefined)).toBeNull();
+  expect(getCloudApiUrlSiblings("")).toBeNull();
+});
+
+import.meta.vitest?.test("getStackAuthApiBaseUrl / getHexclaveApiBaseUrl resolve brands and fall back", ({ expect }) => {
+  expect(getStackAuthApiBaseUrl("https://api.hexclave.com")).toBe("https://api.stack-auth.com");
+  expect(getHexclaveApiBaseUrl("https://api.stack-auth.com")).toBe("https://api.hexclave.com");
+  expect(getStackAuthApiBaseUrl("https://api.dev.stack-auth.com")).toBe("https://api.dev.stack-auth.com");
+  expect(getHexclaveApiBaseUrl("http://localhost:8102")).toBe("http://localhost:8102");
+  expect(getStackAuthApiBaseUrl("http://localhost:8102")).toBe("http://localhost:8102");
+});

package/src/utils/compile-time.tsx

@@ -0,0 +1,11 @@
+/**
+ * Returns the first argument passed to it, but compilers won't be able to optimize it out. This is useful in some
+ * cases where compiler warnings go awry; for example, when importing things that may not exist (but are guaranteed
+ * to exist at runtime).
+ */
+export function scrambleDuringCompileTime<T>(t: T): T {
+  if (Math.random() < 0.00001 && Math.random() > 0.99999 && Math.random() < 0.00001 && Math.random() > 0.99999) {
+    return "this will never happen" as any;
+  }
+  return t;
+}

package/src/utils/country-codes.ts

@@ -0,0 +1,39 @@
+export function normalizeCountryCode(countryCode: string): string {
+  return countryCode.trim().toUpperCase();
+}
+
+export function isValidCountryCode(countryCode: string): boolean {
+  const normalized = normalizeCountryCode(countryCode);
+  return /^[A-Z]{2}$/.test(normalized);
+}
+
+/**
+ * Validates and normalizes a country code value (single string or array).
+ * Returns null if valid, or an error message string if invalid.
+ */
+export function validateCountryCode(value: string | string[]): string | null {
+  const values = Array.isArray(value) ? value : [value];
+  if (values.length === 0) {
+    return "At least one country code is required";
+  }
+  return values.every(v => isValidCountryCode(v))
+    ? null
+    : "Country code must be a 2-letter code";
+}
+
+import.meta.vitest?.test("country codes", ({ expect }) => {
+  expect(normalizeCountryCode(" us ")).toBe("US");
+  expect(isValidCountryCode("us")).toBe(true);
+  expect(isValidCountryCode("US")).toBe(true);
+  expect(isValidCountryCode("ZZ")).toBe(true);
+  expect(isValidCountryCode("usa")).toBe(false);
+  expect(isValidCountryCode("a")).toBe(false);
+  expect(isValidCountryCode("")).toBe(false);
+  expect(isValidCountryCode("12")).toBe(false);
+
+  expect(validateCountryCode("US")).toBeNull();
+  expect(validateCountryCode("zz")).toBeNull();
+  expect(validateCountryCode(["US", "CA"])).toBeNull();
+  expect(validateCountryCode([])).toBe("At least one country code is required");
+  expect(validateCountryCode(["US", "123"])).toBe("Country code must be a 2-letter code");
+});

package/src/utils/crypto.tsx

@@ -0,0 +1,174 @@
+import { encodeBase32, encodeBase64 } from "./bytes";
+import { HexclaveAssertionError } from "./errors";
+import { globalVar } from "./globals";
+import { Result } from "./results";
+import { toArrayBufferBacked } from "./typed-arrays";
+
+export function generateRandomValues(array: Uint8Array): typeof array {
+  if (!globalVar.crypto) {
+    throw new HexclaveAssertionError("Crypto API is not available in this environment. Are you using an old browser?");
+  }
+  if (!globalVar.crypto.getRandomValues) {
+    throw new HexclaveAssertionError("crypto.getRandomValues is not available in this environment. Are you using an old browser?");
+  }
+  return globalVar.crypto.getRandomValues(array);
+}
+
+/**
+ * Generates a secure alphanumeric string using the system's cryptographically secure
+ * random number generator.
+ */
+export function generateSecureRandomString(minBitsOfEntropy: number = 224) {
+  const base32CharactersCount = Math.ceil(minBitsOfEntropy / 5);
+  const bytesCount = Math.ceil(base32CharactersCount * 5 / 8);
+  const randomBytes = generateRandomValues(new Uint8Array(bytesCount));
+  const str = encodeBase32(randomBytes);
+  return str.slice(str.length - base32CharactersCount).toLowerCase();
+}
+
+async function getDerivedSymmetricKey(purpose: string, secret: string | Uint8Array, salt: Uint8Array) {
+  const secretBytes = typeof secret === "string" ? new TextEncoder().encode(secret) : toArrayBufferBacked(secret);
+  const originalSecretKey = await crypto.subtle.importKey("raw", secretBytes, "HKDF", false, ["deriveKey"]);
+  return await crypto.subtle.deriveKey(
+    {
+      name: "HKDF",
+      salt: toArrayBufferBacked(salt),
+      hash: "SHA-256",
+      // NOTE (Hexclave rebrand): do NOT rename this "stack-*" literal. It is a domain-separation
+      // tag baked into HKDF key derivation; changing it would derive different keys and make all
+      // previously-encrypted data undecryptable. It is an internal constant, never user-visible.
+      info: new TextEncoder().encode(JSON.stringify([
+        "stack-crypto-helper-derived-symmetric-key",
+        purpose,
+        typeof secret === "string" ? "string-key" : "binary-key",
+        encodeBase64(salt),
+      ])),
+    },
+    originalSecretKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+
+export async function encrypt({ purpose, secret, value }: { purpose: string, secret: string | Uint8Array, value: Uint8Array }) {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  const derivedSecretKey = await getDerivedSymmetricKey(purpose, secret, salt);
+
+  const cipher = await crypto.subtle.encrypt({
+    name: "AES-GCM",
+    iv,
+  }, derivedSecretKey, toArrayBufferBacked(value));
+
+  const version = [0x01, 0x00];
+  return new Uint8Array([...version, ...salt, ...iv, ...new Uint8Array(cipher)]);
+}
+
+export async function decrypt({ purpose, secret, cipher }: { purpose: string, secret: string | Uint8Array, cipher: Uint8Array }) {
+  const version = cipher.slice(0, 2);
+  if (version[0] !== 0x01 || version[1] !== 0x00) throw new HexclaveAssertionError("Invalid ciphertext version in decrypt(...); expected 0x0100", { purpose });
+  const salt = cipher.slice(2, 18);
+  const iv = cipher.slice(18, 30);
+  const cipherBytes = cipher.slice(30);
+  const derivedSecretKey = await getDerivedSymmetricKey(purpose, secret, salt);
+
+  try {
+    const plaintext = await crypto.subtle.decrypt({
+      name: "AES-GCM",
+      iv,
+    }, derivedSecretKey, cipherBytes);
+    return Result.ok(new Uint8Array(plaintext));
+  } catch (e) {
+    if (e instanceof DOMException && e.name === "OperationError") {
+      return Result.error(new Error("Invalid ciphertext or secret when decrypting encrypted value", { cause: e }));
+    }
+    throw e;
+  }
+}
+
+import.meta.vitest?.test("encrypt & decrypt", async ({ expect }) => {
+  const encryptAndDecrypt = async (encryptPurpose: string, decryptPurpose: string, encryptSecret: string | Uint8Array, decryptSecret: string | Uint8Array, value: Uint8Array) => {
+    const encrypted = await encrypt({ purpose: encryptPurpose, secret: encryptSecret, value });
+    const decrypted = await decrypt({ purpose: decryptPurpose, secret: decryptSecret, cipher: encrypted });
+    return decrypted;
+  };
+
+  const exampleBytes = new TextEncoder().encode("hello");
+
+  const exampleKey1 = crypto.getRandomValues(new Uint8Array(32));
+  const exampleKey2 = crypto.getRandomValues(new Uint8Array(32));
+
+  expect(await encryptAndDecrypt("p", "p", "secret", "secret", exampleBytes)).toEqual(Result.ok(exampleBytes));
+  expect(await encryptAndDecrypt("p", "p", exampleKey1, exampleKey1, exampleBytes)).toEqual(Result.ok(exampleBytes));
+  expect(await encryptAndDecrypt("p", "p", exampleKey1, "secret", exampleBytes)).toEqual(Result.error(expect.objectContaining({ message: "Invalid ciphertext or secret when decrypting encrypted value" })));
+  expect(await encryptAndDecrypt("p", "p", exampleKey1, exampleKey2, exampleBytes)).toEqual(Result.error(expect.objectContaining({ message: "Invalid ciphertext or secret when decrypting encrypted value" })));
+  expect(await encryptAndDecrypt("p", "not-p", exampleKey1, exampleKey1, exampleBytes)).toEqual(Result.error(expect.objectContaining({ message: "Invalid ciphertext or secret when decrypting encrypted value" })));
+});
+
+export type HashOptions = {
+  purpose: string,
+  salt?: string | Uint8Array,
+  extra?: string | Uint8Array,
+  value: string | Uint8Array,
+};
+
+export async function hash(options: HashOptions) {
+  return await iteratedHash({ ...options, iterations: 1 });
+}
+
+export async function iteratedHash(options: HashOptions & { iterations: number }) {
+  const stringOrUint8ArrayToUint8Array = (value: string | Uint8Array) => typeof value === "string" ? new TextEncoder().encode(value) : toArrayBufferBacked(value);
+  const stringOrUint8ArrayToBase64 = (value: string | Uint8Array) => encodeBase64(stringOrUint8ArrayToUint8Array(value));
+  const input = await crypto.subtle.importKey(
+    "raw",
+    stringOrUint8ArrayToUint8Array(options.value),
+    "PBKDF2",
+    false,
+    ["deriveBits"]
+  );
+  return new Uint8Array(await crypto.subtle.deriveBits({
+    name: "PBKDF2",
+    // NOTE (Hexclave rebrand): do NOT rename this "stack-*" literal. It is a domain-separation tag
+    // mixed into the PBKDF2 salt; changing it would change every hash output and break verification
+    // of all previously-hashed values. It is an internal constant, never user-visible.
+    salt: new TextEncoder().encode(JSON.stringify([
+      "stack-crypto-helper-iterated-hash",
+      options.purpose,
+      stringOrUint8ArrayToBase64(options.salt ?? ""),
+      stringOrUint8ArrayToBase64(options.extra ?? ""),
+    ])),
+    iterations: options.iterations,
+    hash: "SHA-256",
+  }, input, 256));
+}
+
+import.meta.vitest?.test("iteratedHash", async ({ expect }) => {
+  const valueBytes = new TextEncoder().encode("hello");
+  const incrementBytes = new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10]);
+
+  const hash = await iteratedHash({ purpose: "purpose", value: valueBytes, iterations: 100_000 });
+  const hash2 = await iteratedHash({ purpose: "purpose", value: valueBytes, iterations: 100_000 });
+  const hashWithDifferentPurpose = await iteratedHash({ purpose: "different-purpose", value: valueBytes, iterations: 100_000 });
+  const hashWithEmptySalt = await iteratedHash({ purpose: "purpose", value: valueBytes, salt: new Uint8Array(0), iterations: 100_000 });
+  const hashWithDifferentSalt = await iteratedHash({ purpose: "purpose", value: valueBytes, salt: incrementBytes, iterations: 100_000 });
+  const hashWithEmptyExtra = await iteratedHash({ purpose: "purpose", value: valueBytes, extra: new Uint8Array(0), iterations: 100_000 });
+  const hashWithDifferentExtra = await iteratedHash({ purpose: "purpose", value: valueBytes, extra: incrementBytes, iterations: 100_000 });
+  const hashWithDifferentValue = await iteratedHash({ purpose: "purpose", value: new TextEncoder().encode("hello2"), iterations: 100_000 });
+  const hashWithDifferentSaltAndExtra = await iteratedHash({ purpose: "purpose", value: valueBytes, salt: incrementBytes, extra: incrementBytes, iterations: 100_000 });
+  const hashWithDifferentIterations = await iteratedHash({ purpose: "purpose", value: valueBytes, iterations: 100_001 });
+
+
+  expect(hash).toEqual(hash2);
+  expect(hash).not.toEqual(hashWithDifferentPurpose);
+  expect(hash).toEqual(hashWithEmptySalt);
+  expect(hash).not.toEqual(hashWithDifferentSalt);
+  expect(hash).toEqual(hashWithEmptyExtra);
+  expect(hash).not.toEqual(hashWithDifferentExtra);
+  expect(hash).not.toEqual(hashWithDifferentValue);
+  expect(hash).not.toEqual(hashWithDifferentIterations);
+
+  expect(hashWithDifferentSalt).not.toEqual(hashWithDifferentExtra);
+  expect(hashWithDifferentSalt).not.toEqual(hashWithDifferentSaltAndExtra);
+  expect(hashWithDifferentExtra).not.toEqual(hashWithDifferentSaltAndExtra);
+});

package/src/utils/currencies.tsx

@@ -0,0 +1,53 @@
+import { moneyAmountSchema } from "../schema-fields";
+import { SUPPORTED_CURRENCIES, type Currency, type MoneyAmount } from "./currency-constants";
+import { HexclaveAssertionError } from "./errors";
+
+export type SupportedCurrency = (typeof SUPPORTED_CURRENCIES)[number];
+
+export function moneyAmountToStripeUnits(amount: MoneyAmount, currency: Currency): number {
+  const validated = moneyAmountSchema(currency).defined().validateSync(amount);
+  if (currency.stripeDecimals !== currency.decimals) {
+    throw new HexclaveAssertionError("unimplemented: TODO support different decimal configurations");
+  }
+  // `moneyAmountSchema` accepts strings with 0..currency.decimals fractional
+  // digits, so we must right-pad the fractional part before stripping the dot.
+  // A naïve `replace('.', '')` underweights inputs like "5" → 5 (should be 500
+  // for USD) and "0.5" → 5 (should be 50).
+  const [whole, fractional = ""] = validated.split(".");
+  const paddedFractional = fractional.padEnd(currency.decimals, "0");
+  return Number.parseInt(whole + paddedFractional, 10);
+}
+
+import.meta.vitest?.describe("moneyAmountToStripeUnits", (test) => {
+  const USD = SUPPORTED_CURRENCIES.find((c) => c.code === "USD")!;
+
+  test("converts fully-padded USD amounts", ({ expect }) => {
+    expect(moneyAmountToStripeUnits("5.00" as MoneyAmount, USD)).toBe(500);
+    expect(moneyAmountToStripeUnits("0.01" as MoneyAmount, USD)).toBe(1);
+    expect(moneyAmountToStripeUnits("12.34" as MoneyAmount, USD)).toBe(1234);
+  });
+
+  test("converts whole-number USD amounts (no decimals)", ({ expect }) => {
+    expect(moneyAmountToStripeUnits("5" as MoneyAmount, USD)).toBe(500);
+    expect(moneyAmountToStripeUnits("10" as MoneyAmount, USD)).toBe(1000);
+    expect(moneyAmountToStripeUnits("0" as MoneyAmount, USD)).toBe(0);
+  });
+
+  test("converts USD amounts with one decimal digit", ({ expect }) => {
+    expect(moneyAmountToStripeUnits("5.5" as MoneyAmount, USD)).toBe(550);
+    expect(moneyAmountToStripeUnits("0.5" as MoneyAmount, USD)).toBe(50);
+  });
+
+  test("matches stripeUnitsToMoneyAmount round-trip", ({ expect }) => {
+    for (const cents of [0, 1, 5, 50, 99, 100, 1234, 100000]) {
+      const padded = `${Math.floor(cents / 100)}.${(cents % 100).toString().padStart(2, "0")}` as MoneyAmount;
+      expect(moneyAmountToStripeUnits(padded, USD)).toBe(cents);
+    }
+  });
+
+  test("rejects invalid money strings via schema", ({ expect }) => {
+    expect(() => moneyAmountToStripeUnits("abc" as MoneyAmount, USD)).toThrow();
+    expect(() => moneyAmountToStripeUnits("5.555" as MoneyAmount, USD)).toThrow();
+    expect(() => moneyAmountToStripeUnits("05" as MoneyAmount, USD)).toThrow();
+  });
+});

package/src/utils/currency-constants.tsx

@@ -0,0 +1,51 @@
+/**
+ * A decimal string representing a monetary amount, e.g. `"9.99"`, `"0.01"`, or `"1000"`.
+ *
+ * This is NOT an integer in cents/minor units — it is always a human-readable decimal string.
+ * For example, nine dollars and ninety-nine cents is `"9.99"`, not `999`.
+ */
+export type MoneyAmount = `${number}` | `${number}.${number}`;
+
+export type Currency = {
+  code: Uppercase<string>,
+  decimals: number,
+  stripeDecimals: number,
+};
+
+export const SUPPORTED_CURRENCIES = [
+  {
+    code: 'USD',
+    decimals: 2,
+    stripeDecimals: 2,
+  },
+  {
+    code: 'EUR',
+    decimals: 2,
+    stripeDecimals: 2,
+  },
+  {
+    code: 'GBP',
+    decimals: 2,
+    stripeDecimals: 2,
+  },
+  {
+    code: 'JPY',
+    decimals: 0,
+    stripeDecimals: 0,
+  },
+  {
+    code: 'INR',
+    decimals: 2,
+    stripeDecimals: 2,
+  },
+  {
+    code: 'AUD',
+    decimals: 2,
+    stripeDecimals: 2,
+  },
+  {
+    code: 'CAD',
+    decimals: 2,
+    stripeDecimals: 2,
+  },
+] as const satisfies Currency[];