@every-app/sdk 0.0.1

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@every-app/sdk",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./src/client/index.ts",
+  "exports": {
+    "./client": "./src/client/index.ts",
+    "./server": "./src/server/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "types:check": "tsc --noEmit",
+    "format:check": "prettier --check .",
+    "format:write": "prettier . --write"
+  },
+  "peerDependencies": {
+    "@tanstack/react-router": "^1.0.0",
+    "@tanstack/react-start": "^1.0.0",
+    "jose": "^6.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20251014.0",
+    "@tanstack/react-router": "^1.136.3",
+    "@tanstack/react-start": "^1.136.3",
+    "@types/node": "^22.18.13",
+    "@types/react": "^19.0.8",
+    "jose": "^6.0.12",
+    "jsonc-parser": "^3.3.1",
+    "prettier": "^3.6.2",
+    "react": "^19.0.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.1.2"
+  }
+}

package/src/client/EmbeddedAppProvider.tsx

@@ -0,0 +1,77 @@
+import React, { createContext, useContext, useMemo } from "react";
+import { SessionManager, SessionManagerConfig } from "./session-manager";
+import { useEveryAppSession } from "./_internal/useEveryAppSession";
+import { useEveryAppRouter } from "./_internal/useEveryAppRouter";
+
+interface EmbeddedProviderConfig extends SessionManagerConfig {
+  children: React.ReactNode;
+}
+
+interface EmbeddedAppContextValue {
+  sessionManager: SessionManager;
+  isAuthenticated: boolean;
+  sessionTokenState: ReturnType<SessionManager["getTokenState"]>;
+}
+
+const EmbeddedAppContext = createContext<EmbeddedAppContextValue | null>(null);
+
+export function EmbeddedAppProvider({
+  children,
+  ...config
+}: EmbeddedProviderConfig) {
+  const { sessionManager, sessionTokenState } = useEveryAppSession({
+    sessionManagerConfig: config,
+  });
+  useEveryAppRouter({ sessionManager });
+
+  if (!sessionManager) return null;
+
+  const value: EmbeddedAppContextValue = {
+    sessionManager,
+    isAuthenticated: sessionTokenState.status === "VALID",
+    sessionTokenState,
+  };
+
+  return (
+    <EmbeddedAppContext.Provider value={value}>
+      {children}
+    </EmbeddedAppContext.Provider>
+  );
+}
+
+/**
+ * Hook to get the current authenticated user.
+ * Returns the user's ID and email extracted from the JWT token,
+ * or null if not authenticated.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const user = useCurrentUser();
+ *
+ *   if (!user) {
+ *     return <div>Not authenticated</div>;
+ *   }
+ *
+ *   return <div>Welcome, {user.email}</div>;
+ * }
+ * ```
+ */
+export function useCurrentUser(): { userId: string; email: string } | null {
+  const context = useContext(EmbeddedAppContext);
+
+  if (!context) {
+    throw new Error("useCurrentUser must be used within an EmbeddedAppProvider");
+  }
+
+  const { sessionManager, sessionTokenState } = context;
+
+  return useMemo(() => {
+    // Only return user if we have a valid token
+    if (sessionTokenState.status !== "VALID") {
+      return null;
+    }
+
+    return sessionManager.getUser();
+  }, [sessionManager, sessionTokenState]);
+}

package/src/client/_internal/useEveryAppRouter.tsx

@@ -0,0 +1,75 @@
+import { useEffect } from "react";
+import { SessionManager } from "../session-manager";
+import { useRouter } from "@tanstack/react-router";
+
+interface UseEveryAppRouterParams {
+  sessionManager: SessionManager | null;
+}
+export function useEveryAppRouter({ sessionManager }: UseEveryAppRouterParams) {
+  const router = useRouter();
+  // Route synchronization effect
+  useEffect(() => {
+    if (!sessionManager) return;
+    // Listen for route sync messages from parent
+    const handleMessage = (event: MessageEvent) => {
+      if (event.origin !== sessionManager.getParentOrigin()) return;
+
+      if (
+        event.data.type === "ROUTE_CHANGE" &&
+        event.data.direction === "parent-to-child"
+      ) {
+        const targetRoute = event.data.route;
+        const currentRoute = window.location.pathname;
+
+        // Only navigate if the route is different from current location
+        if (targetRoute && targetRoute !== currentRoute) {
+          router.navigate({ to: targetRoute });
+        }
+      }
+    };
+
+    window.addEventListener("message", handleMessage);
+
+    // Simplified route change detection with 2 reliable methods
+    let lastReportedPath = window.location.pathname;
+
+    const handleRouteChange = () => {
+      const currentPath = window.location.pathname;
+
+      // Only report if the path actually changed
+      if (currentPath === lastReportedPath) {
+        return;
+      }
+
+      lastReportedPath = currentPath;
+
+      if (window.parent !== window) {
+        window.parent.postMessage(
+          {
+            type: "ROUTE_CHANGE",
+            route: currentPath,
+            appId: sessionManager.getAppId(),
+            direction: "child-to-parent",
+          },
+          sessionManager.getParentOrigin(),
+        );
+      }
+    };
+    // Listen to popstate for browser back/forward
+    window.addEventListener("popstate", handleRouteChange);
+
+    // Polling to detect route changes (catches router navigation)
+    const pollInterval = setInterval(() => {
+      const currentPath = window.location.pathname;
+      if (currentPath !== lastReportedPath) {
+        handleRouteChange();
+      }
+    }, 100);
+
+    return () => {
+      window.removeEventListener("message", handleMessage);
+      window.removeEventListener("popstate", handleRouteChange);
+      clearInterval(pollInterval);
+    };
+  }, [sessionManager]);
+}

package/src/client/_internal/useEveryAppSession.tsx

@@ -0,0 +1,53 @@
+import { useEffect, useRef, useState } from "react";
+import { SessionManager, SessionManagerConfig } from "../session-manager";
+
+interface UseEveryAppSessionParams {
+  sessionManagerConfig: SessionManagerConfig;
+}
+
+export function useEveryAppSession({
+  sessionManagerConfig,
+}: UseEveryAppSessionParams) {
+  const sessionManagerRef = useRef<SessionManager>(null);
+  const [sessionTokenState, setSessionTokenState] = useState<
+    ReturnType<SessionManager["getTokenState"]>
+  >({
+    status: "NO_TOKEN",
+    token: null,
+  });
+
+  if (!sessionManagerRef.current && typeof document !== "undefined") {
+    sessionManagerRef.current = new SessionManager(sessionManagerConfig);
+  }
+
+  const sessionManager = sessionManagerRef.current;
+
+  useEffect(() => {
+    if (!sessionManager) return;
+    const interval = setInterval(() => {
+      setSessionTokenState(sessionManager.getTokenState());
+    }, 1000);
+
+    const unsubscribe = sessionManager.onDebugEvent(() => {
+      setSessionTokenState(sessionManager.getTokenState());
+    });
+
+    sessionManager.getToken().catch((err) => {
+      console.error("[EmbeddedProvider] Initial token request failed:", err);
+    });
+
+    return () => {
+      clearInterval(interval);
+      unsubscribe();
+    };
+  }, [sessionManager]);
+
+  useEffect(() => {
+    if (!sessionManager) return;
+
+    // Make sessionManager globally accessible for middleware
+    (window as any).__embeddedSessionManager = sessionManager;
+  }, [sessionManager]);
+
+  return { sessionManager, sessionTokenState };
+}

package/src/client/authenticatedFetch.ts

@@ -0,0 +1,45 @@
+interface SessionManager {
+  getToken(): Promise<string>;
+}
+
+interface WindowWithSessionManager extends Window {
+  __embeddedSessionManager?: SessionManager;
+}
+
+/**
+ * Gets the current session token from the embedded session manager
+ */
+export async function getSessionToken(): Promise<string> {
+  const windowWithSession = window as WindowWithSessionManager;
+  const sessionManager = windowWithSession.__embeddedSessionManager;
+
+  if (!sessionManager) {
+    throw new Error("Session manager not available");
+  }
+
+  const token = await sessionManager.getToken();
+
+  if (!token) {
+    throw new Error("No token available");
+  }
+
+  return token;
+}
+
+/**
+ * Performs a fetch request with the authorization header automatically added
+ */
+export async function authenticatedFetch(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<Response> {
+  const token = await getSessionToken();
+
+  const headers = new Headers(init?.headers);
+  headers.set("Authorization", `Bearer ${token}`);
+
+  return fetch(input, {
+    ...init,
+    headers,
+  });
+}

package/src/client/index.ts

@@ -0,0 +1,9 @@
+export { SessionManager } from "./session-manager";
+export type { SessionManagerConfig } from "./session-manager";
+export { useSessionTokenClientMiddleware } from "./useSessionTokenClientMiddleware";
+
+export { EmbeddedAppProvider, useCurrentUser } from "./EmbeddedAppProvider";
+
+export { lazyInitForWorkers } from "./lazyInitForWorkers";
+
+export { authenticatedFetch, getSessionToken } from "./authenticatedFetch";

package/src/client/lazyInitForWorkers.ts

@@ -0,0 +1,67 @@
+/**
+ * Wraps a factory function in a Proxy to defer initialization until first access.
+ * This prevents async operations (Like creating Tanstack DB Collections) from running in Cloudflare Workers' global scope.
+ *
+ * @param factory - A function that creates and returns the resource.
+ *                  Must be a callback to defer execution; passing the value directly
+ *                  would evaluate it at module load time, triggering the Cloudflare error.
+ * @returns A Proxy that lazily initializes the resource on first property access
+ *
+ * @example
+ * ```ts
+ * export const myCollection = lazyInitForWorkers(() =>
+ *   createCollection(queryCollectionOptions({
+ *     queryKey: ["myData"],
+ *     queryFn: async () => fetchData(),
+ *     // ... other options
+ *   }))
+ * );
+ * ```
+ */
+export function lazyInitForWorkers<T extends object>(factory: () => T): T {
+  // Closure: This variable is captured by getInstance() and the Proxy traps below.
+  // It remains in memory as long as the returned Proxy is referenced, enabling singleton behavior.
+  let instance: T | null = null;
+
+  function getInstance() {
+    if (!instance) {
+      instance = factory();
+    }
+    return instance;
+  }
+
+  return new Proxy({} as T, {
+    get(_, prop) {
+      const inst = getInstance();
+      const value = inst[prop as keyof T];
+      // Bind methods to the instance to preserve `this` context
+      return typeof value === "function" ? value.bind(inst) : value;
+    },
+    set(_, prop, value) {
+      const inst = getInstance();
+      (inst as any)[prop] = value;
+      return true;
+    },
+    deleteProperty(_, prop) {
+      const inst = getInstance();
+      delete (inst as any)[prop];
+      return true;
+    },
+    has(_, prop) {
+      const inst = getInstance();
+      return prop in inst;
+    },
+    ownKeys(_) {
+      const inst = getInstance();
+      return Reflect.ownKeys(inst);
+    },
+    getOwnPropertyDescriptor(_, prop) {
+      const inst = getInstance();
+      return Reflect.getOwnPropertyDescriptor(inst, prop);
+    },
+    getPrototypeOf(_) {
+      const inst = getInstance();
+      return Reflect.getPrototypeOf(inst);
+    },
+  });
+}

package/src/client/session-manager.ts

@@ -0,0 +1,289 @@
+interface SessionToken {
+  token: string;
+  expiresAt: number;
+}
+
+export interface SessionManagerConfig {
+  appId: string;
+  debug?: boolean;
+}
+
+export class SessionManager {
+  private token: SessionToken | null = null;
+  private refreshPromise: Promise<string> | null = null;
+  private parentOrigin: string;
+  private appId: string;
+  private messageTimeout: number;
+  private debug: boolean;
+  private onError?: (error: Error) => void;
+  private pendingRequests = new Map<
+    string,
+    {
+      resolve: (token: string) => void;
+      reject: (error: Error) => void;
+      timeout: NodeJS.Timeout;
+    }
+  >();
+
+  constructor(config: SessionManagerConfig) {
+    this.parentOrigin = import.meta.env.VITE_GATEWAY_URL;
+    this.appId = config.appId || this.detectAppId();
+    this.messageTimeout = 5000;
+    this.debug = config.debug ?? false;
+
+    if (!this.parentOrigin) {
+      throw new Error(
+        "[SessionManager] Set the Parent Origin by specifying the VITE_GATEWAY_URL env var.",
+      );
+    }
+
+    try {
+      new URL(this.parentOrigin);
+    } catch {
+      throw new Error(
+        `[SessionManager] Invalid parent origin URL: ${this.parentOrigin}`,
+      );
+    }
+
+    this.setupMessageListener();
+  }
+
+  private detectAppId(): string {
+    if (typeof window === "undefined") return "";
+
+    const url = new URL(window.location.href);
+    return (
+      url.searchParams.get("appId") ||
+      url.hostname.split(".")[0] ||
+      "embedded-app"
+    );
+  }
+
+  private log(message: string, data?: unknown) {
+    if (this.debug) {
+      console.log(`[SessionManager - Logger] ${message}`, data);
+    }
+  }
+
+  private setupMessageListener() {
+    if (typeof window === "undefined") return;
+
+    window.addEventListener("message", (event) => {
+      if (event.origin !== this.parentOrigin) {
+        this.log("Message rejected due to origin mismatch", {
+          expected: this.parentOrigin,
+          received: event.origin,
+        });
+        return;
+      }
+
+      this.log("Accepted message from parent", event.data);
+    });
+  }
+
+  private isTokenExpired(): boolean {
+    if (!this.token) return true;
+    return Date.now() >= this.token.expiresAt;
+  }
+
+  private isTokenExpiringSoon(bufferMs: number = 10000): boolean {
+    if (!this.token) return true;
+    return Date.now() >= this.token.expiresAt - bufferMs;
+  }
+
+  async requestNewToken(): Promise<string> {
+    if (this.refreshPromise) {
+      return this.refreshPromise;
+    }
+
+    this.refreshPromise = new Promise((resolve, reject) => {
+      const requestId = Date.now().toString();
+
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        this.log(`Token request #${requestId} timed out`);
+        const error = new Error(
+          "Token refresh timeout - parent did not respond",
+        );
+        this.onError?.(error);
+        reject(error);
+      }, this.messageTimeout);
+
+      this.pendingRequests.set(requestId, { resolve, reject, timeout });
+
+      const messageHandler = (event: MessageEvent) => {
+        if (event.origin !== this.parentOrigin) {
+          this.log("Ignoring message from unexpected origin", {
+            expected: this.parentOrigin,
+            received: event.origin,
+          });
+          return;
+        }
+
+        this.log(`Received message for request #${requestId}`, event.data);
+
+        if (
+          event.data.type === "SESSION_TOKEN_RESPONSE" &&
+          event.data.requestId === requestId
+        ) {
+          clearTimeout(timeout);
+          window.removeEventListener("message", messageHandler);
+
+          if (event.data.error) {
+            this.log(`Token request #${requestId} failed`, {
+              error: event.data.error,
+            });
+            const error = new Error(event.data.error);
+            this.onError?.(error);
+            reject(error);
+            return;
+          }
+
+          if (!event.data.token) {
+            this.log(
+              `Token request #${requestId} failed - no token in response`,
+            );
+            const error = new Error("No token in response");
+            this.onError?.(error);
+            reject(error);
+            return;
+          }
+
+          this.token = {
+            token: event.data.token,
+            expiresAt: event.data.expiresAt
+              ? new Date(event.data.expiresAt).getTime()
+              : Date.now() + 60000,
+          };
+
+          this.log(`Token #${requestId} received successfully`, {
+            expiresAt: new Date(this.token.expiresAt).toISOString(),
+          });
+          resolve(this.token.token);
+        }
+      };
+
+      window.addEventListener("message", messageHandler);
+
+      this.log(
+        `Requesting new session token #${requestId} for app "${this.appId}"`,
+      );
+
+      // Fire-and-forget postMessage to the parent
+      try {
+        window.parent.postMessage(
+          {
+            type: "SESSION_TOKEN_REQUEST",
+            requestId: requestId,
+            appId: this.appId,
+          },
+          this.parentOrigin,
+        );
+        this.log(`Message sent for token request #${requestId}`, {
+          targetOrigin: this.parentOrigin,
+        });
+      } catch (e) {
+        this.log(`postMessage failed for token request #${requestId}`, e);
+        // We don't reject the promise here because the timeout will handle it
+      }
+    });
+
+    try {
+      return await this.refreshPromise;
+    } finally {
+      this.refreshPromise = null;
+    }
+  }
+
+  async getToken(): Promise<string> {
+    // If token is expired or expiring soon (within 10 seconds), get a new one
+    if (this.isTokenExpiringSoon() || !this.token) {
+      this.log("Token expired or expiring soon, requesting new token", {
+        hasToken: !!this.token,
+        expiresAt: this.token
+          ? new Date(this.token.expiresAt).toISOString()
+          : "N/A",
+        timeUntilExpiry: this.token ? this.token.expiresAt - Date.now() : "N/A",
+      });
+      return this.requestNewToken();
+    }
+
+    return this.token.token;
+  }
+
+  getParentOrigin(): string {
+    return this.parentOrigin;
+  }
+
+  getAppId(): string {
+    return this.appId;
+  }
+
+  getTokenState(): {
+    status: "NO_TOKEN" | "VALID" | "EXPIRED" | "REFRESHING";
+    token: string | null;
+  } {
+    if (this.refreshPromise) {
+      return { status: "REFRESHING", token: null };
+    }
+
+    if (!this.token) {
+      return { status: "NO_TOKEN", token: null };
+    }
+
+    if (this.isTokenExpired()) {
+      return { status: "EXPIRED", token: this.token.token };
+    }
+
+    return { status: "VALID", token: this.token.token };
+  }
+
+  onDebugEvent(callback: () => void): () => void {
+    // For now, we'll create a simple event system
+    // In a more complete implementation, you might want to emit events at various points
+    const intervalId = setInterval(() => {
+      // This will trigger the callback periodically to update the UI
+      callback();
+    }, 5000);
+
+    // Return an unsubscribe function
+    return () => clearInterval(intervalId);
+  }
+
+  /**
+   * Extracts user information from the current JWT token.
+   * Returns null if no valid token is available.
+   */
+  getUser(): { userId: string; email: string } | null {
+    if (!this.token) {
+      return null;
+    }
+
+    try {
+      // JWT structure: header.payload.signature
+      const parts = this.token.token.split(".");
+      if (parts.length !== 3) {
+        this.log("Invalid JWT format - expected 3 parts", {
+          parts: parts.length,
+        });
+        return null;
+      }
+
+      // Decode the payload (second part)
+      const payload = JSON.parse(atob(parts[1]));
+
+      if (!payload.sub) {
+        this.log("JWT payload missing 'sub' claim");
+        return null;
+      }
+
+      return {
+        userId: payload.sub,
+        email: payload.email ?? "",
+      };
+    } catch (error) {
+      this.log("Failed to decode JWT", error);
+      return null;
+    }
+  }
+}

package/src/client/useSessionTokenClientMiddleware.ts

@@ -0,0 +1,31 @@
+import { createMiddleware } from "@tanstack/react-start";
+import type { SessionManager } from "./session-manager";
+
+export const useSessionTokenClientMiddleware = createMiddleware({
+  type: "function",
+}).client(async ({ next }) => {
+  // Get the global sessionManager - this MUST be available for embedded apps
+  const sessionManager = (window as any)
+    .__embeddedSessionManager as SessionManager;
+
+  if (!sessionManager) {
+    throw new Error(
+      "[AuthMiddleware] SessionManager not available - embedded provider not initialized",
+    );
+  }
+
+  // INVARIANT: This is just an extra check and should never be the case if the sessionManager exists.
+  if (typeof sessionManager.getToken !== "function") {
+    throw new Error(
+      "[AuthMiddleware] SessionManager.getToken is not a function",
+    );
+  }
+
+  const token = await sessionManager.getToken();
+
+  return next({
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+  });
+});

package/src/env.d.ts

@@ -0,0 +1,11 @@
+// Type definitions for environment variables expected by the SDK
+// Apps using this SDK should have these defined in their wrangler configuration
+
+declare namespace Cloudflare {
+  interface Env {
+    GATEWAY_URL: string;
+    EVERY_APP_GATEWAY?: Fetcher;
+  }
+}
+
+interface Env extends Cloudflare.Env {}

package/src/server/auth-config.ts

@@ -0,0 +1,10 @@
+import type { AuthConfig } from "./types";
+import { env } from "cloudflare:workers";
+
+export function getAuthConfig(): AuthConfig {
+  return {
+    jwksUrl: `${env.GATEWAY_URL}/api/embedded/jwks`,
+    issuer: env.GATEWAY_URL,
+    audience: import.meta.env.VITE_APP_ID,
+  };
+}

package/src/server/authenticateRequest.ts

@@ -0,0 +1,104 @@
+import { getRequest } from "@tanstack/react-start/server";
+import {
+  createLocalJWKSet,
+  jwtVerify,
+  JWTVerifyOptions,
+  JSONWebKeySet,
+} from "jose";
+
+import type { AuthConfig } from "./types";
+import { env } from "cloudflare:workers";
+
+interface SessionTokenPayload {
+  sub: string;
+  iss: string;
+  aud: string;
+  exp: number;
+  iat: number;
+  appId?: string;
+  permissions?: string[];
+  email?: string;
+}
+
+export async function authenticateRequest(
+  authConfig: AuthConfig,
+  providedRequest?: Request,
+): Promise<SessionTokenPayload | null> {
+  const request = providedRequest || getRequest();
+  const authHeader = request.headers.get("authorization");
+
+  if (!authHeader) {
+    console.log("No auth header found");
+    return null;
+  }
+
+  const token = extractBearerToken(authHeader);
+
+  if (!token) {
+    return null;
+  }
+
+  try {
+    const session = await verifySessionToken(token, authConfig);
+    return session;
+    // TODO Is there a way to handle this more gracefully?
+  } catch (error) {
+    console.error(
+      JSON.stringify({
+        message: "Error verifying session token",
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        errorType: error instanceof Error ? error.constructor.name : "Unknown",
+        authConfig,
+      }),
+    );
+    return null;
+  }
+}
+
+async function verifySessionToken(
+  token: string,
+  config: AuthConfig,
+): Promise<SessionTokenPayload> {
+  const { issuer, audience } = config;
+
+  if (!issuer) {
+    throw new Error("Issuer must be provided for token verification");
+  }
+
+  if (!audience) {
+    throw new Error("Audience must be provided for token verification");
+  }
+
+  // TODO Maybe we don't even need this if we just store the jwks as an env when we deploy
+  // But, the limitation of these services not being able to talk to each other will be frustrating.
+  // I wonder if there is a better abstraction to wrap this dynamic fetching and link all the services together.
+  const jwksResponse =
+    import.meta.env.PROD && env.EVERY_APP_GATEWAY
+      ? await env.EVERY_APP_GATEWAY.fetch("http://localhost/api/embedded/jwks")
+      : await fetch(`${env.GATEWAY_URL}/api/embedded/jwks`);
+
+  if (!jwksResponse.ok) {
+    throw new Error(
+      `Failed to fetch JWKS: ${jwksResponse.status} ${jwksResponse.statusText}`,
+    );
+  }
+
+  const jwks = (await jwksResponse.json()) as JSONWebKeySet;
+  const localJWKS = createLocalJWKSet(jwks);
+
+  const options: JWTVerifyOptions = {
+    issuer,
+    audience,
+  };
+
+  const { payload } = await jwtVerify(token, localJWKS, options);
+  return payload as SessionTokenPayload;
+}
+
+function extractBearerToken(authHeader: string | null): string | null {
+  if (!authHeader || !authHeader.startsWith("Bearer ")) {
+    return null;
+  }
+  return authHeader.substring(7);
+}

package/src/server/getLocalD1Url.ts

@@ -0,0 +1,66 @@
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { parse } from "jsonc-parser";
+
+export function getLocalD1Url() {
+  const basePath = path.resolve(".wrangler");
+
+  // Check if .wrangler directory exists
+  if (!fs.existsSync(basePath)) {
+    console.error(
+      "================================================================================",
+    );
+    console.error("WARNING: .wrangler directory not found");
+    console.error("This is expected in CI/non-development environments.");
+    console.error(
+      "The local D1 database is only available after running 'wrangler dev' which you can trigger by running 'npm run dev'.",
+    );
+    console.error(
+      "================================================================================",
+    );
+    return null;
+  }
+
+  const dbFile = fs
+    .readdirSync(basePath, { encoding: "utf-8", recursive: true })
+    .find((f) => f.endsWith(".sqlite"));
+
+  if (!dbFile) {
+    // Read wrangler.jsonc to get the database name
+    const wranglerConfigPath = path.resolve("wrangler.jsonc");
+    const wranglerConfig = parse(fs.readFileSync(wranglerConfigPath, "utf-8"));
+
+    const databaseName = wranglerConfig.d1_databases?.[0]?.database_name;
+
+    if (!databaseName) {
+      throw new Error(
+        "Could not find database_name in wrangler.jsonc d1_databases configuration",
+      );
+    }
+
+    // Execute the command to initialize the local database
+    console.log(`Initializing local D1 database: ${databaseName}...`);
+    execSync(
+      `npx wrangler d1 execute ${databaseName} --local --command "SELECT 1;"`,
+      { stdio: "pipe" },
+    );
+
+    // Try to find the db file again after initialization
+    const dbFileAfterInit = fs
+      .readdirSync(basePath, { encoding: "utf-8", recursive: true })
+      .find((f) => f.endsWith(".sqlite"));
+
+    if (!dbFileAfterInit) {
+      throw new Error(
+        `Failed to initialize local D1 database. The sqlite file was not created.`,
+      );
+    }
+
+    const url = path.resolve(basePath, dbFileAfterInit);
+    return url;
+  }
+
+  const url = path.resolve(basePath, dbFile);
+  return url;
+}

package/src/server/index.ts

@@ -0,0 +1,4 @@
+export { authenticateRequest } from "./authenticateRequest";
+export type { AuthConfig } from "./types";
+export { getAuthConfig } from "./auth-config";
+export { getLocalD1Url } from "./getLocalD1Url";

package/src/server/types.ts

@@ -0,0 +1,8 @@
+export interface AuthConfig {
+  jwksUrl: string;
+  issuer: string;
+  audience: string;
+  autoDiscoverJwks?: boolean;
+  debug?: boolean;
+  onError?: (error: Error, req: unknown) => void;
+}