@hexclave/shared 1.0.2 → 1.0.5

package/src/utils/types.tsx

@@ -0,0 +1,208 @@
+import { DeepPartial } from "./objects";
+import { Join } from "./strings";
+
+export type IsAny<T> = 0 extends (1 & T) ? true : false;
+export type IsNever<T> = [T] extends [never] ? true : false;
+export type IsNullish<T> = [T] extends [null | undefined] ? true : false;
+export type IsUnion<T, U = T> =
+  IsNever<T> extends true ? false
+  : IsAny<T> extends true ? false
+    : T extends U // distributive conditional https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types
+        ? /* if the *whole* original type (`U`) still fits inside the current variant, then `T` wasn’t a union */ ([U] extends [T] ? false : true)
+        : never;
+
+export type NullishCoalesce<T, U> = T extends null | undefined ? U : T;
+
+export type LastUnionElement<U> = UnionToIntersection<U extends any ? (x: U) => 0 : never> extends (x: infer L) => 0 ? L & U : never;
+
+type primitive = string | number | boolean | bigint | symbol | null | undefined;
+
+/**
+ * Makes a type prettier by recursively expanding all object types. For example, `Omit<{ a: 1 }, "a">` becomes just `{}`.
+ */
+export type Expand<T> = T extends (...args: infer A) => infer R
+  ? ((...args: A) => R) extends T
+    ? (...args: Expand<A>) => Expand<R>
+    : ((...args: Expand<A>) => Expand<R>) & { [K in keyof T]: Expand<T[K]> }
+  : T extends object
+    ? T extends primitive
+      ? T
+      : T extends infer O
+        ? { [K in keyof O]: Expand<O[K]> }
+        : never
+    : T;
+
+
+/**
+ * Removes all optional undefined/never keys from an object.
+ */
+export type DeepRemoveOptionalUndefined<T> = T extends object ? { [K in keyof T]: DeepRemoveOptionalUndefined<T[K]> } : T;
+
+// why this works: https://stackoverflow.com/a/50375286
+export type UnionToIntersection<U> =
+  (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never
+
+type _UnionToTupleInner<U, R extends any[], Last> = UnionToTuple<Exclude<U, Last>, [...R, Last]>
+export type UnionToTuple<U, R extends any[] = []> = [U] extends [never] ? R : _UnionToTupleInner<U, R, LastUnionElement<U>>;
+
+export type CollapseObjectUnion<T extends object> = {
+  [K in AllUnionKeys<T>]?: T extends Record<K, infer V> ? V : never;
+};
+typeAssertIs<CollapseObjectUnion<{ a: string } | { b: number }>, { a?: string, b?: number }>()();
+typeAssertIs<CollapseObjectUnion<{ a: string } | { a: number }>, { a?: string | number }>()();
+
+export type IntersectAll<T extends any[]> = UnionToIntersection<T[number]>;
+
+export type OptionalKeys<T> = {
+  [K in keyof T]: {} extends Pick<T, K> ? K : never;
+}[keyof T];
+export type RequiredKeys<T> = {
+  [K in keyof T]: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+
+/**
+ * Returns a type whose keys are the intersection of the keys of T and U, deeply.
+ */
+export type KeyIntersect<T, U> =
+  & { [K in keyof T & keyof U]?: T[K] & U[K] }
+  & { [K in RequiredKeys<T> & keyof U]: T[K] & U[K] }
+  & { [K in RequiredKeys<U> & keyof T]: U[K] & T[K] }
+
+/**
+ * Returns ALL keys of all union elements.
+ */
+export type AllUnionKeys<T extends object> = T extends T ? keyof T : never;
+typeAssertIs<AllUnionKeys<{ a: string } | { b: number }>, "a" | "b">()();
+
+export type SubtractType<T, U> = T extends object ? { [K in keyof T]: K extends keyof U ? SubtractType<T[K], U[K]> : T[K] } : (T extends U ? never : T); // note: this only works due to the distributive property of conditional types https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types
+
+export type XOR<T extends readonly any[]> = T extends readonly [infer A, infer B, ...infer Rest]
+  ? Rest extends []
+  ? (A & { [K in keyof B]?: never }) | (B & { [K in keyof A]?: never })
+  : XOR<[(A & { [K in keyof B]?: never }) | (B & { [K in keyof A]?: never }), ...Rest]>
+  : T[0];
+
+
+type _AntiIntersectInner<T, U> = T extends object ? (
+  & Omit<U, keyof T>
+  & { [K in keyof Pick<U, { [K in keyof T & keyof U]: U[K] extends T[K] ? (T[K] extends U[K] ? never : K) : never }[keyof T & keyof U]>]: PseudoAntiIntersect<T[K], U[K]> }
+  & { [K in keyof Pick<U, keyof T & keyof U>]?: PseudoAntiIntersect<T[K], U[K]> }
+) : U;
+/**
+ * Returns a type R such that T & R = U.
+ */
+export type AntiIntersect<T, U> = U extends T ? _AntiIntersectInner<T, U> : "Cannot anti-intersect a type with a type that is not a subtype of it"; // NOTE: This type is mostly untested — not sure how well it works on the edge cases
+export type PseudoAntiIntersect<T, U> = _AntiIntersectInner<T, T & U>;
+
+/**
+ * A variation of TypeScript's conditionals with slightly different semantics. It is the perfect type for cases where:
+ *
+ * - If all possible values are contained in `Extends`, then it will be mapped to `Then`.
+ * - If all possible values are not contained in `Extends`, then it will be mapped to `Otherwise`.
+ * - If some possible values are contained in `Extends` and some are not, then it will be mapped to `Then | Otherwise`.
+ *
+ * This is different from TypeScript's built-in conditional types (`Value extends Extends ? Then : Otherwise`), which
+ * returns `Otherwise` for the third case (causing unsoundness in many real-world cases).
+ */
+export type IfAndOnlyIf<Value, Extends, Then, Otherwise> =
+  | (Value extends Extends ? never : Otherwise)
+  | (Value & Extends extends never ? never : Then);
+
+
+/**
+ * Can be used to prettify a type in the IDE; for example, some complicated intersected types can be flattened into a single type.
+ */
+export type PrettifyType<T> = T extends object ? { [K in keyof T]: T[K] } & {} : T;
+
+type _ToStringAndJoin<T extends any[], Separator extends string> =
+  T extends [infer U, ...infer Rest extends any[]]
+    ? `${TypeToString<U>}${Rest extends [any, ...any[]] ? `${Separator}${_ToStringAndJoin<Rest, Separator>}` : ""}`
+    : "<error-joining-tuple-elements>";
+type _TypeToStringInner<T> =
+  IsAny<T> extends true ? "any"
+  : IsNever<T> extends true ? "never"
+  : IsUnion<T> extends true ? _ToStringAndJoin<UnionToTuple<T>, " | ">
+  : [T] extends [number] ? (number extends T ? "number" : `${T}`)
+  : [T] extends [boolean] ? `${T}`
+  : [T] extends [undefined] ? "undefined"
+  : [T] extends [null] ? "null"
+  : [T] extends [string] ? (string extends T ? "string" : `'${T}'`)
+  : [T] extends [[]] ? "[]"
+  : [T] extends [[any, ...any[]]] ? `[${_ToStringAndJoin<T, ", ">}]`
+  : [T] extends [(infer E)[]] ? `${TypeToString<E>}[]`
+  : [T] extends [Function] ? "function"
+  : [T] extends [symbol] ? `symbol(${T['description']})`
+  : [T] extends [object] ? `{ ${Join<UnionToTuple<{ [K in keyof T]: `${TypeToString<K>}: ${TypeToString<T[K]>}` }[keyof T]>, ", ">} }`
+  : "<unknown-type>"
+export type TypeToString<T> = _TypeToStringInner<T> extends `${infer S}` ? S : never;
+
+/**
+ * Can be used to create assertions on types. For example, if passed any T other than `true`, the following will
+ * show a type error:
+ *
+ * ```ts
+ * typeAssert<T>()();  // the second pair of braces is important!
+ * ```
+ */
+export function typeAssert<T>(): (
+  IsAny<T> extends true ? TypeAssertionError<`Type assertion failed. Expected true, but got any.`>
+    : IsNever<T> extends true ? TypeAssertionError<`Type assertion failed. Expected true, but got never.`>
+    : T extends true ? (() => undefined)
+    : TypeAssertionError<`Type assertion failed. Expected true, but got: ${TypeToString<T>}`>
+) {
+  return (() => undefined) as any;
+}
+type TypeAssertionError<T> =
+  & [T]
+  & /* this promise makes sure that if we accidentally forget the second pair of braces, eslint will complain (if we have no-floating-promises enabled) */ Promise<any>;
+
+
+typeAssertExtends<ReturnType<typeof typeAssert<true>>, () => undefined>()();
+typeAssertExtends<ReturnType<typeof typeAssert<false>>, TypeAssertionError<`Type assertion failed. Expected true, but got: false`>>()();
+typeAssertExtends<ReturnType<typeof typeAssert<never>>, TypeAssertionError<`Type assertion failed. Expected true, but got never.`>>()();
+typeAssertExtends<ReturnType<typeof typeAssert<any>>, TypeAssertionError<`Type assertion failed. Expected true, but got any.`>>()();
+
+/**
+ * Functionally equivalent to `typeAssert<T extends S ? true : false>()()`, but with better error messages.
+ */
+export function typeAssertExtends<T, S>(): (
+  [T] extends [S] ? (() => undefined) : TypeAssertionError<`Type assertion failed. Expected ${TypeToString<T>} to extend ${TypeToString<S>}`>
+) {
+  return (() => undefined) as any;
+}
+
+typeAssertExtends<ReturnType<typeof typeAssertExtends<never, true>>, () => undefined>()();
+typeAssertExtends<ReturnType<typeof typeAssertExtends<any, true>>, () => undefined>()();
+typeAssertExtends<ReturnType<typeof typeAssertExtends<false, false>>, () => undefined>()();
+typeAssertExtends<ReturnType<typeof typeAssertExtends<"abc", string>>, () => undefined>()();
+typeAssertExtends<ReturnType<typeof typeAssertExtends<{a: 1, b: 123}, {a: number}>>, () => undefined>()();
+typeAssertExtends<ReturnType<typeof typeAssertExtends<never, never>>, () => undefined>()();
+typeAssertExtends<ReturnType<typeof typeAssertExtends<true, any>>, () => undefined>()();
+
+typeAssertExtends<ReturnType<typeof typeAssertExtends<{a: number}, {a: 1}>>, ["Type assertion failed. Expected { 'a': number } to extend { 'a': 1 }"]>()();
+typeAssertExtends<ReturnType<typeof typeAssertExtends<any, never>>, ["Type assertion failed. Expected any to extend never"]>()();
+typeAssertExtends<ReturnType<typeof typeAssertExtends<false, true>>, ["Type assertion failed. Expected false to extend true"]>()();
+typeAssertExtends<ReturnType<typeof typeAssertExtends<false, never>>, ["Type assertion failed. Expected false to extend never"]>()();
+
+
+export function typeAssertIs<T, U>(): (
+  IsAny<T> extends true ? (IsAny<U> extends true ? (() => undefined) : TypeAssertionError<`Type assertion failed. Expected ${TypeToString<T>} to be ${TypeToString<U>}`>)
+    : IsAny<U> extends true ? TypeAssertionError<`Type assertion failed. Expected ${TypeToString<T>} to be ${TypeToString<U>}`>
+    : [T] extends [U] ? ([U] extends [T] ? (() => undefined) : TypeAssertionError<`Type assertion failed. Expected ${TypeToString<T>} to be ${TypeToString<U>}`>)
+    : TypeAssertionError<`Type assertion failed. Expected ${TypeToString<T>} to be ${TypeToString<U>}`>
+) {
+  return (() => undefined) as any;
+}
+
+typeAssertExtends<ReturnType<typeof typeAssertIs<"123", "123">>, () => undefined>()();
+typeAssertExtends<ReturnType<typeof typeAssertIs<{a: 1}, {a: 1}>>, () => undefined>()();
+typeAssertExtends<ReturnType<typeof typeAssertIs<DeepPartial<{a: 1}>, {a?: 1}>>, () => undefined>()();
+typeAssertExtends<ReturnType<typeof typeAssertIs<any, any>>, () => undefined>()();
+typeAssertExtends<ReturnType<typeof typeAssertIs<never, never>>, () => undefined>()();
+typeAssertExtends<ReturnType<typeof typeAssertIs<1, any>>, ["Type assertion failed. Expected 1 to be any"]>()();
+typeAssertExtends<ReturnType<typeof typeAssertIs<any, 1>>, ["Type assertion failed. Expected any to be 1"]>()();
+typeAssertExtends<ReturnType<typeof typeAssertIs<false, true>>, ["Type assertion failed. Expected false to be true"]>()();
+typeAssertExtends<ReturnType<typeof typeAssertIs<{a: number}, {a: 1}>>, ["Type assertion failed. Expected { 'a': number } to be { 'a': 1 }"]>()();
+typeAssertExtends<ReturnType<typeof typeAssertIs<any, never>>, ["Type assertion failed. Expected any to be never"]>()();
+typeAssertExtends<ReturnType<typeof typeAssertIs<false, true>>, ["Type assertion failed. Expected false to be true"]>()();
+typeAssertExtends<ReturnType<typeof typeAssertIs<false, never>>, ["Type assertion failed. Expected false to be never"]>()();

package/src/utils/unicode.tsx

@@ -0,0 +1,24 @@
+import { isValidCountryCode, normalizeCountryCode } from "./country-codes";
+import { HexclaveAssertionError } from "./errors";
+
+export function getFlagEmoji(twoLetterCountryCode: string) {
+  if (!isValidCountryCode(twoLetterCountryCode)) throw new HexclaveAssertionError("Country code must be two alphabetical letters");
+  const codePoints = normalizeCountryCode(twoLetterCountryCode)
+    .split('')
+    .map(char => 127397 + char.charCodeAt(0));
+  return String.fromCodePoint(...codePoints);
+}
+import.meta.vitest?.test("getFlagEmoji", ({ expect }) => {
+  // Test with valid country codes
+  expect(getFlagEmoji("US")).toBe("🇺🇸");
+  expect(getFlagEmoji("us")).toBe("🇺🇸");
+  expect(getFlagEmoji("GB")).toBe("🇬🇧");
+  expect(getFlagEmoji("JP")).toBe("🇯🇵");
+
+  // Test with invalid country codes
+  expect(() => getFlagEmoji("")).toThrow("Country code must be two alphabetical letters");
+  expect(() => getFlagEmoji("A")).toThrow("Country code must be two alphabetical letters");
+  expect(() => getFlagEmoji("ABC")).toThrow("Country code must be two alphabetical letters");
+  expect(() => getFlagEmoji("12")).toThrow("Country code must be two alphabetical letters");
+  expect(() => getFlagEmoji("A1")).toThrow("Country code must be two alphabetical letters");
+});

package/src/utils/urls.tsx

@@ -0,0 +1,411 @@
+import { generateSecureRandomString } from "./crypto";
+import { templateIdentity } from "./strings";
+
+export function createUrlIfValid(...args: ConstructorParameters<typeof URL>) {
+  try {
+    return new URL(...args);
+  } catch (e) {
+    return null;
+  }
+}
+import.meta.vitest?.test("createUrlIfValid", ({ expect }) => {
+  // Test with valid URLs
+  expect(createUrlIfValid("https://example.com")).toBeInstanceOf(URL);
+  expect(createUrlIfValid("https://example.com/path?query=value#hash")).toBeInstanceOf(URL);
+  expect(createUrlIfValid("/path", "https://example.com")).toBeInstanceOf(URL);
+
+  // Test with invalid URLs
+  expect(createUrlIfValid("")).toBeNull();
+  expect(createUrlIfValid("not a url")).toBeNull();
+  expect(createUrlIfValid("http://")).toBeNull();
+});
+
+export function isValidUrl(url: string) {
+  return !!createUrlIfValid(url);
+}
+import.meta.vitest?.test("isValidUrl", ({ expect }) => {
+  // Test with valid URLs
+  expect(isValidUrl("https://example.com")).toBe(true);
+  expect(isValidUrl("http://localhost:3000")).toBe(true);
+  expect(isValidUrl("ftp://example.com")).toBe(true);
+
+  // Test with invalid URLs
+  expect(isValidUrl("")).toBe(false);
+  expect(isValidUrl("not a url")).toBe(false);
+  expect(isValidUrl("http://")).toBe(false);
+});
+
+export function isValidHostname(hostname: string) {
+  // Basic validation
+  if (!hostname || hostname.startsWith('.') || hostname.endsWith('.') || hostname.includes('..')) {
+    return false;
+  }
+
+  const url = createUrlIfValid(`https://${hostname}`);
+  if (!url) return false;
+  return url.hostname === hostname;
+}
+import.meta.vitest?.test("isValidHostname", ({ expect }) => {
+  // Test with valid hostnames
+  expect(isValidHostname("example.com")).toBe(true);
+  expect(isValidHostname("localhost")).toBe(true);
+  expect(isValidHostname("sub.domain.example.com")).toBe(true);
+  expect(isValidHostname("127.0.0.1")).toBe(true);
+
+  // Test with invalid hostnames
+  expect(isValidHostname("")).toBe(false);
+  expect(isValidHostname("example.com/path")).toBe(false);
+  expect(isValidHostname("https://example.com")).toBe(false);
+  expect(isValidHostname("example com")).toBe(false);
+});
+
+export function isValidHostnameWithWildcards(hostname: string) {
+  // Empty hostnames are invalid
+  if (!hostname) return false;
+
+  // Check if it contains wildcards
+  const hasWildcard = hostname.includes('*');
+
+  if (!hasWildcard) {
+    // If no wildcards, validate as a normal hostname
+    return isValidHostname(hostname);
+  }
+
+  // Basic validation checks that apply even with wildcards
+  // - Hostname cannot start or end with a dot
+  if (hostname.startsWith('.') || hostname.endsWith('.')) {
+    return false;
+  }
+
+  // - No consecutive dots
+  if (hostname.includes('..')) {
+    return false;
+  }
+
+  // For wildcard validation, check that non-wildcard parts contain valid characters
+  // Replace wildcards with a valid placeholder to check the rest
+  const testHostname = hostname.replace(/\*+/g, 'wildcard');
+
+  // Check if the resulting string would be a valid hostname
+  if (!/^[a-zA-Z0-9.-]+$/.test(testHostname)) {
+    return false;
+  }
+
+  // Additional check: ensure the pattern makes sense
+  // Check each segment between wildcards
+  const segments = hostname.split(/\*+/);
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (segment === '') continue; // Empty segments are OK (consecutive wildcards)
+
+    // First segment can't start with dot
+    if (i === 0 && segment.startsWith('.')) {
+      return false;
+    }
+
+    // Last segment can't end with dot
+    if (i === segments.length - 1 && segment.endsWith('.')) {
+      return false;
+    }
+
+    // No segment should have consecutive dots
+    if (segment.includes('..')) {
+      return false;
+    }
+  }
+
+  return true;
+}
+import.meta.vitest?.test("isValidHostnameWithWildcards", ({ expect }) => {
+  // Test with valid regular hostnames
+  expect(isValidHostnameWithWildcards("example.com")).toBe(true);
+  expect(isValidHostnameWithWildcards("localhost")).toBe(true);
+  expect(isValidHostnameWithWildcards("sub.domain.example.com")).toBe(true);
+
+  // Test with valid wildcard hostnames
+  expect(isValidHostnameWithWildcards("*.example.com")).toBe(true);
+  expect(isValidHostnameWithWildcards("a-*.example.com")).toBe(true);
+  expect(isValidHostnameWithWildcards("*.*.org")).toBe(true);
+  expect(isValidHostnameWithWildcards("**.example.com")).toBe(true);
+  expect(isValidHostnameWithWildcards("sub.**.com")).toBe(true);
+  expect(isValidHostnameWithWildcards("*-api.*.com")).toBe(true);
+
+  // Test with invalid hostnames
+  expect(isValidHostnameWithWildcards("")).toBe(false);
+  expect(isValidHostnameWithWildcards("example.com/path")).toBe(false);
+  expect(isValidHostnameWithWildcards("https://example.com")).toBe(false);
+  expect(isValidHostnameWithWildcards("example com")).toBe(false);
+  expect(isValidHostnameWithWildcards(".example.com")).toBe(false);
+  expect(isValidHostnameWithWildcards("example.com.")).toBe(false);
+  expect(isValidHostnameWithWildcards("example..com")).toBe(false);
+  expect(isValidHostnameWithWildcards("*.example..com")).toBe(false);
+});
+
+export function matchHostnamePattern(pattern: string, hostname: string): boolean {
+  // If no wildcards, it's an exact match
+  if (!pattern.includes('*')) {
+    return pattern === hostname;
+  }
+
+  // Convert the pattern to a regex
+  // First, escape all regex special characters except *
+  let regexPattern = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+
+  // Use a placeholder for ** to handle it separately from single *
+  const doubleWildcardPlaceholder = '\x00DOUBLE_WILDCARD\x00';
+  regexPattern = regexPattern.replace(/\*\*/g, doubleWildcardPlaceholder);
+
+  // Replace single * with a pattern that matches anything except dots
+  regexPattern = regexPattern.replace(/\*/g, '[^.]*');
+
+  // Replace the double wildcard placeholder with a pattern that matches anything including dots
+  regexPattern = regexPattern.replace(new RegExp(doubleWildcardPlaceholder, 'g'), '.*');
+
+  // Anchor the pattern to match the entire hostname
+  regexPattern = '^' + regexPattern + '$';
+
+  try {
+    const regex = new RegExp(regexPattern);
+    return regex.test(hostname);
+  } catch {
+    return false;
+  }
+}
+import.meta.vitest?.test("matchHostnamePattern", ({ expect }) => {
+  // Test exact matches
+  expect(matchHostnamePattern("example.com", "example.com")).toBe(true);
+  expect(matchHostnamePattern("example.com", "other.com")).toBe(false);
+
+  // Test single wildcard matches
+  expect(matchHostnamePattern("*.example.com", "api.example.com")).toBe(true);
+  expect(matchHostnamePattern("*.example.com", "www.example.com")).toBe(true);
+  expect(matchHostnamePattern("*.example.com", "example.com")).toBe(false);
+  expect(matchHostnamePattern("*.example.com", "api.v2.example.com")).toBe(false);
+
+  // Test double wildcard matches
+  expect(matchHostnamePattern("**.example.com", "api.example.com")).toBe(true);
+  expect(matchHostnamePattern("**.example.com", "api.v2.example.com")).toBe(true);
+  expect(matchHostnamePattern("**.example.com", "a.b.c.example.com")).toBe(true);
+  expect(matchHostnamePattern("**.example.com", "example.com")).toBe(false);
+
+  // Test complex patterns
+  expect(matchHostnamePattern("api-*.example.com", "api-v1.example.com")).toBe(true);
+  expect(matchHostnamePattern("api-*.example.com", "api-v2.example.com")).toBe(true);
+  expect(matchHostnamePattern("api-*.example.com", "api.example.com")).toBe(false);
+  expect(matchHostnamePattern("*.*.org", "mail.example.org")).toBe(true);
+  expect(matchHostnamePattern("*.*.org", "example.org")).toBe(false);
+});
+
+export function getHardcodedFallbackUrls(primaryBaseUrl: string): string[] {
+  // `defaultBaseUrl` in `@stackframe/*` SDK builds is `https://api.stack-auth.com`
+  // (see `packages/template/src/lib/hexclave-app/apps/implementations/common.ts`).
+  // The `@hexclave/*` mirror packages will get this rewritten to the hexclave
+  // hostname by `scripts/rewrite-packages-to-hexclave.ts` in a follow-up PR; both
+  // branches below stay listed so either build resolves its own fallback set.
+  if (primaryBaseUrl === "https://api.stack-auth.com") {
+    return ["https://api1.stack-auth.com", "https://api2.stack-auth.com"];
+  }
+  if (primaryBaseUrl === "https://api.dev.stack-auth.com") {
+    return ["https://api1.dev.stack-auth.com", "https://api2.dev.stack-auth.com"];
+  }
+  if (primaryBaseUrl === "https://api.hexclave.com") {
+    return ["https://api1.hexclave.com", "https://api2.hexclave.com"];
+  }
+  if (primaryBaseUrl === "https://api.dev.hexclave.com") {
+    return ["https://api1.dev.hexclave.com", "https://api2.dev.hexclave.com"];
+  }
+  const localhostMatch = primaryBaseUrl.match(/^http:\/\/localhost:(\d+)02$/);
+  if (localhostMatch) {
+    return [`http://localhost:${localhostMatch[1]}10`];
+  }
+  return [];
+}
+
+export function getDefaultApiUrls(primaryBaseUrl: string): string[] {
+  return [primaryBaseUrl, ...getHardcodedFallbackUrls(primaryBaseUrl)];
+}
+
+export function isLocalhost(urlOrString: string | URL) {
+  const url = createUrlIfValid(urlOrString);
+  if (!url) return false;
+  if (url.hostname === "localhost" || url.hostname.endsWith(".localhost")) return true;
+  if (url.hostname.match(/^127\.\d+\.\d+\.\d+$/)) return true;
+  if (url.hostname === "[::1]" || url.hostname === "::1") return true;
+  return false;
+}
+import.meta.vitest?.test("isLocalhost", ({ expect }) => {
+  // Test with localhost URLs
+  expect(isLocalhost("http://localhost")).toBe(true);
+  expect(isLocalhost("https://localhost:8080")).toBe(true);
+  expect(isLocalhost("http://sub.localhost")).toBe(true);
+  expect(isLocalhost("http://127.0.0.1")).toBe(true);
+  expect(isLocalhost("http://127.1.2.3")).toBe(true);
+  expect(isLocalhost("http://[::1]")).toBe(true);
+
+  // Test with non-localhost URLs
+  expect(isLocalhost("https://example.com")).toBe(false);
+  expect(isLocalhost("http://192.168.1.1")).toBe(false);
+  expect(isLocalhost("http://10.0.0.1")).toBe(false);
+
+  // Test with URL objects
+  expect(isLocalhost(new URL("http://localhost"))).toBe(true);
+  expect(isLocalhost(new URL("https://example.com"))).toBe(false);
+
+  // Test with invalid URLs
+  expect(isLocalhost("not a url")).toBe(false);
+  expect(isLocalhost("")).toBe(false);
+});
+
+export function isRelative(url: string) {
+  const randomDomain = `${generateSecureRandomString()}.stack-auth.example.com`;
+  const u = createUrlIfValid(url, `https://${randomDomain}`);
+  if (!u) return false;
+  if (u.host !== randomDomain) return false;
+  if (u.protocol !== "https:") return false;
+  return true;
+}
+import.meta.vitest?.test("isRelative", ({ expect }) => {
+  // We can't easily mock generateSecureRandomString in this context
+  // but we can still test the function's behavior
+
+  // Test with relative URLs
+  expect(isRelative("/")).toBe(true);
+  expect(isRelative("/path")).toBe(true);
+  expect(isRelative("/path?query=value#hash")).toBe(true);
+
+  // Test with absolute URLs
+  expect(isRelative("https://example.com")).toBe(false);
+  expect(isRelative("http://example.com")).toBe(false);
+  expect(isRelative("//example.com")).toBe(false);
+
+  // Note: The implementation treats empty strings and invalid URLs as relative
+  // This is because they can be resolved against a base URL
+  expect(isRelative("")).toBe(true);
+  expect(isRelative("not a url")).toBe(true);
+});
+
+export function getRelativePart(url: URL) {
+  return url.pathname + url.search + url.hash;
+}
+import.meta.vitest?.test("getRelativePart", ({ expect }) => {
+  // Test with various URLs
+  expect(getRelativePart(new URL("https://example.com"))).toBe("/");
+  expect(getRelativePart(new URL("https://example.com/path"))).toBe("/path");
+  expect(getRelativePart(new URL("https://example.com/path?query=value"))).toBe("/path?query=value");
+  expect(getRelativePart(new URL("https://example.com/path#hash"))).toBe("/path#hash");
+  expect(getRelativePart(new URL("https://example.com/path?query=value#hash"))).toBe("/path?query=value#hash");
+
+  // Test with different domains but same paths
+  const url1 = new URL("https://example.com/path?query=value#hash");
+  const url2 = new URL("https://different.com/path?query=value#hash");
+  expect(getRelativePart(url1)).toBe(getRelativePart(url2));
+});
+
+/**
+ * A template literal tag that returns a URL.
+ *
+ * Any values passed are encoded.
+ */
+export function url(strings: TemplateStringsArray | readonly string[], ...values: (string | number | boolean)[]): URL {
+  return new URL(urlString(strings, ...values));
+}
+import.meta.vitest?.test("url", ({ expect }) => {
+  // Test with no interpolation
+  expect(url`https://example.com`).toBeInstanceOf(URL);
+  expect(url`https://example.com`.href).toBe("https://example.com/");
+
+  // Test with string interpolation
+  expect(url`https://example.com/${"path"}`).toBeInstanceOf(URL);
+  expect(url`https://example.com/${"path"}`.pathname).toBe("/path");
+
+  // Test with number interpolation
+  expect(url`https://example.com/${42}`).toBeInstanceOf(URL);
+  expect(url`https://example.com/${42}`.pathname).toBe("/42");
+
+  // Test with boolean interpolation
+  expect(url`https://example.com/${true}`).toBeInstanceOf(URL);
+  expect(url`https://example.com/${true}`.pathname).toBe("/true");
+
+  // Test with special characters in interpolation
+  expect(url`https://example.com/${"path with spaces"}`).toBeInstanceOf(URL);
+  expect(url`https://example.com/${"path with spaces"}`.pathname).toBe("/path%20with%20spaces");
+
+  // Test with multiple interpolations
+  expect(url`https://example.com/${"path"}?query=${"value"}`).toBeInstanceOf(URL);
+  expect(url`https://example.com/${"path"}?query=${"value"}`.pathname).toBe("/path");
+  expect(url`https://example.com/${"path"}?query=${"value"}`.search).toBe("?query=value");
+});
+
+
+/**
+ * A template literal tag that returns a URL string.
+ *
+ * Any values passed are encoded.
+ */
+export function urlString(strings: TemplateStringsArray | readonly string[], ...values: (string | number | boolean)[]): string {
+  return templateIdentity(strings, ...values.map(encodeURIComponent));
+}
+import.meta.vitest?.test("urlString", ({ expect }) => {
+  // Test with no interpolation
+  expect(urlString`https://example.com`).toBe("https://example.com");
+
+  // Test with string interpolation
+  expect(urlString`https://example.com/${"path"}`).toBe("https://example.com/path");
+
+  // Test with number interpolation
+  expect(urlString`https://example.com/${42}`).toBe("https://example.com/42");
+
+  // Test with boolean interpolation
+  expect(urlString`https://example.com/${true}`).toBe("https://example.com/true");
+
+  // Test with special characters in interpolation
+  expect(urlString`https://example.com/${"path with spaces"}`).toBe("https://example.com/path%20with%20spaces");
+  expect(urlString`https://example.com/${"?&="}`).toBe("https://example.com/%3F%26%3D");
+
+  // Test with multiple interpolations
+  expect(urlString`https://example.com/${"path"}?query=${"value"}`).toBe("https://example.com/path?query=value");
+  expect(urlString`https://example.com/${"path"}?query=${"value with spaces"}`).toBe("https://example.com/path?query=value%20with%20spaces");
+});
+
+export function isChildUrl(parentUrl: URL, maybeChildUrl: URL) {
+  return parentUrl.origin === maybeChildUrl.origin
+    && isChildPath(parentUrl.pathname, maybeChildUrl.pathname)
+    && [...parentUrl.searchParams].every(([key, value]) => maybeChildUrl.searchParams.get(key) === value)
+    && (!parentUrl.hash || parentUrl.hash === maybeChildUrl.hash);
+}
+import.meta.vitest?.test("isChildUrl", ({ expect }) => {
+  // true
+  expect(isChildUrl(new URL("https://abc.com/"), new URL("https://abc.com/"))).toBe(true);
+  expect(isChildUrl(new URL("https://abc.com/"), new URL("https://abc.com/path"))).toBe(true);
+  expect(isChildUrl(new URL("https://abc.com/"), new URL("https://abc.com/path?query=value"))).toBe(true);
+  expect(isChildUrl(new URL("https://abc.com/"), new URL("https://abc.com/path?query=value#hash"))).toBe(true);
+
+  // false
+  expect(isChildUrl(new URL("https://abc.com"), new URL("https://example.com"))).toBe(false);
+  expect(isChildUrl(new URL("https://abc.com/"), new URL("https://example.com/path"))).toBe(false);
+  expect(isChildUrl(new URL("https://abc.com/"), new URL("https://example.com/path?query=value"))).toBe(false);
+  expect(isChildUrl(new URL("https://abc.com/"), new URL("https://example.com/path?query=value#hash"))).toBe(false);
+  expect(isChildUrl(new URL("https://example.com"), new URL("https://abc.com/path?query=value#hash"))).toBe(false);
+  expect(isChildUrl(new URL("https://example.com?query=value123"), new URL("https://example.com/path?query=value#hash"))).toBe(false);
+});
+
+export function isChildPath(parentPath: string, maybeChildPath: string) {
+  parentPath = parentPath.endsWith("/") ? parentPath : parentPath + "/";
+  maybeChildPath = maybeChildPath.endsWith("/") ? maybeChildPath : maybeChildPath + "/";
+  return maybeChildPath.startsWith(parentPath);
+}
+import.meta.vitest?.test("isSubPath", ({ expect }) => {
+  expect(isChildPath("/", "/")).toBe(true);
+  expect(isChildPath("/", "/path")).toBe(true);
+  expect(isChildPath("/path", "/")).toBe(false);
+  expect(isChildPath("/path", "/path")).toBe(true);
+  expect(isChildPath("/path/", "/path")).toBe(true);
+  expect(isChildPath("/path", "/path/")).toBe(true);
+  expect(isChildPath("/path/", "/path/")).toBe(true);
+  expect(isChildPath("/path", "/path/abc")).toBe(true);
+  expect(isChildPath("/path/", "/path/abc")).toBe(true);
+  expect(isChildPath("/path", "/path-abc")).toBe(false);
+  expect(isChildPath("/path", "/path-abc/")).toBe(false);
+  expect(isChildPath("/path/", "/path-abc")).toBe(false);
+  expect(isChildPath("/path/", "/path-abc/")).toBe(false);
+});