@sandbox0/dashboard-core 0.1.1

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@sandbox0/dashboard-core",
+  "version": "0.1.1",
+  "description": "Shared Sandbox0 dashboard auth and control-plane core",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "src/auth.ts",
+    "src/config.ts",
+    "src/index.ts",
+    "src/sdk.ts",
+    "src/session.ts",
+    "src/types.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test src/**/*.test.ts"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sandbox0-ai/sandbox0",
+    "directory": "sandbox0-ui/components/dashboard-core"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "next": "^15.1.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.0.2",
+    "@types/react-dom": "^19.0.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "sandbox0": "^0.1.5"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,344 @@
+import { NextResponse } from "next/server";
+
+import { resolveDashboardControlPlaneURL } from "./config";
+import { createDashboardControlPlaneSDK, resolveSDKErrorMessage } from "./sdk";
+import type { DashboardAuthProvider, DashboardRuntimeConfig } from "./types";
+
+interface LoginResponse {
+  access_token: string;
+  refresh_token: string;
+  expires_at: number;
+}
+
+export const dashboardAccessTokenCookieName = "sandbox0_access_token";
+export const dashboardRefreshTokenCookieName = "sandbox0_refresh_token";
+
+function joinURL(baseURL: string, path: string): string {
+  const base = new URL(baseURL);
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return new URL(
+    normalizedPath,
+    `${base.toString().replace(/\/$/, "")}/`,
+  ).toString();
+}
+
+function toLoginResponse(data: {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+}): LoginResponse {
+  return {
+    access_token: data.accessToken,
+    refresh_token: data.refreshToken,
+    expires_at: data.expiresAt,
+  };
+}
+
+export function dashboardCookieNames() {
+  return {
+    accessToken: dashboardAccessTokenCookieName,
+    refreshToken: dashboardRefreshTokenCookieName,
+  };
+}
+
+export async function resolveDashboardAuthProviders(
+  config: DashboardRuntimeConfig,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ providers: DashboardAuthProvider[]; errors: string[] }> {
+  const baseURL = resolveDashboardControlPlaneURL(config);
+  if (!baseURL) {
+    return {
+      providers: [],
+      errors: ["dashboard auth is missing a control-plane base URL"],
+    };
+  }
+
+  try {
+    const sdk = await createDashboardControlPlaneSDK(baseURL, {
+      fetch: fetchImpl,
+    });
+    const response = await sdk.auth.authProvidersGet();
+    const providers = (response.data?.providers ?? []).flatMap((provider) => {
+      if (provider.type !== "oidc" && provider.type !== "builtin") {
+        return [];
+      }
+
+      return [
+        {
+          id: provider.id,
+          name: provider.name,
+          type: provider.type,
+        } satisfies DashboardAuthProvider,
+      ];
+    });
+
+    return { providers, errors: [] };
+  } catch (error) {
+    return {
+      providers: [],
+      errors: [
+        await resolveSDKErrorMessage(
+          error,
+          "failed to resolve auth providers",
+        ),
+      ],
+    };
+  }
+}
+
+export async function exchangeBuiltinLogin(
+  config: DashboardRuntimeConfig,
+  email: string,
+  password: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ tokens?: LoginResponse; error?: string }> {
+  const baseURL = resolveDashboardControlPlaneURL(config);
+  if (!baseURL) {
+    return { error: "dashboard auth is missing a control-plane base URL" };
+  }
+
+  try {
+    const sdk = await createDashboardControlPlaneSDK(baseURL, {
+      fetch: fetchImpl,
+    });
+    const response = await sdk.auth.authLoginPost({
+      loginRequest: { email, password },
+    });
+    if (!response.data) {
+      return { error: "/auth/login returned an empty response" };
+    }
+
+    return { tokens: toLoginResponse(response.data) };
+  } catch (error) {
+    return {
+      error: await resolveSDKErrorMessage(error, "failed to complete login"),
+    };
+  }
+}
+
+export async function exchangeRefreshToken(
+  config: DashboardRuntimeConfig,
+  refreshToken: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ tokens?: LoginResponse; error?: string }> {
+  const baseURL = resolveDashboardControlPlaneURL(config);
+  if (!baseURL) {
+    return { error: "dashboard auth is missing a control-plane base URL" };
+  }
+
+  try {
+    const sdk = await createDashboardControlPlaneSDK(baseURL, {
+      fetch: fetchImpl,
+    });
+    const response = await sdk.auth.authRefreshPost({
+      refreshRequest: { refreshToken },
+    });
+    if (!response.data) {
+      return { error: "/auth/refresh returned an empty response" };
+    }
+
+    return { tokens: toLoginResponse(response.data) };
+  } catch (error) {
+    return {
+      error: await resolveSDKErrorMessage(error, "failed to refresh session"),
+    };
+  }
+}
+
+export async function updateDefaultTeam(
+  config: DashboardRuntimeConfig,
+  accessToken: string,
+  teamID: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ ok: boolean; error?: string }> {
+  const baseURL = resolveDashboardControlPlaneURL(config);
+  if (!baseURL) {
+    return {
+      ok: false,
+      error: "dashboard auth is missing a control-plane base URL",
+    };
+  }
+
+  try {
+    const sdk = await createDashboardControlPlaneSDK(baseURL, {
+      token: accessToken,
+      fetch: fetchImpl,
+    });
+    await sdk.users.tenantActivePut({
+      updateUserRequest: { defaultTeamId: teamID },
+    });
+    return { ok: true };
+  } catch (error) {
+    return {
+      ok: false,
+      error: await resolveSDKErrorMessage(
+        error,
+        "failed to update default team",
+      ),
+    };
+  }
+}
+
+export async function exchangeOIDCCallback(
+  config: DashboardRuntimeConfig,
+  providerID: string,
+  rawQuery: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ tokens?: LoginResponse; error?: string }> {
+  const baseURL = resolveDashboardControlPlaneURL(config);
+  if (!baseURL) {
+    return { error: "dashboard auth is missing a control-plane base URL" };
+  }
+
+  try {
+    const path = `/auth/oidc/${encodeURIComponent(providerID)}/callback${rawQuery}`;
+    const response = await fetchImpl(joinURL(baseURL, path), {
+      method: "GET",
+      cache: "no-store",
+    });
+    const payload = (await response.json().catch(() => null)) as
+      | {
+          data?: LoginResponse;
+          error?: {
+            message?: string;
+          };
+        }
+      | null;
+    if (!response.ok || !payload?.data) {
+      return {
+        error:
+          payload?.error?.message ??
+          `/auth/oidc/${providerID}/callback returned ${response.status}`,
+      };
+    }
+
+    return { tokens: payload.data };
+  } catch (error) {
+    return {
+      error:
+        error instanceof Error
+          ? error.message
+          : "failed to complete oidc login",
+    };
+  }
+}
+
+export async function resolveOIDCLoginLocation(
+  config: DashboardRuntimeConfig,
+  providerID: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ location?: string; error?: string }> {
+  const baseURL = resolveDashboardControlPlaneURL(config);
+  if (!baseURL) {
+    return { error: "dashboard auth is missing a control-plane base URL" };
+  }
+
+  try {
+    const response = await fetchImpl(
+      joinURL(
+        baseURL,
+        `/auth/oidc/${encodeURIComponent(providerID)}/login?return_url=${encodeURIComponent(config.dashboardBasePath)}`,
+      ),
+      {
+        method: "GET",
+        redirect: "manual",
+        cache: "no-store",
+      },
+    );
+
+    if (response.status < 300 || response.status >= 400) {
+      const payload = (await response.json().catch(() => null)) as
+        | {
+            error?: {
+              message?: string;
+            };
+          }
+        | null;
+      return {
+        error:
+          payload?.error?.message ??
+          `/auth/oidc/${providerID}/login returned ${response.status}`,
+      };
+    }
+
+    const location = response.headers.get("location");
+    if (!location) {
+      return { error: "oidc login did not return a redirect location" };
+    }
+
+    return { location };
+  } catch (error) {
+    return {
+      error:
+        error instanceof Error
+          ? error.message
+          : "failed to initiate oidc login",
+    };
+  }
+}
+
+export async function forwardLogout(
+  config: DashboardRuntimeConfig,
+  accessToken: string | undefined,
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  const baseURL = resolveDashboardControlPlaneURL(config);
+  if (!baseURL || !accessToken) {
+    return;
+  }
+
+  try {
+    const sdk = await createDashboardControlPlaneSDK(baseURL, {
+      token: accessToken,
+      fetch: fetchImpl,
+    });
+    await sdk.auth.authLogoutPost();
+  } catch {
+    // Ignore upstream logout failures and clear browser cookies locally.
+  }
+}
+
+export function setDashboardAuthCookies(
+  response: NextResponse,
+  config: DashboardRuntimeConfig,
+  tokens: LoginResponse,
+): void {
+  const secure = config.siteURL.startsWith("https://");
+  const maxAge = Math.max(0, tokens.expires_at - Math.floor(Date.now() / 1000));
+
+  response.cookies.set(dashboardAccessTokenCookieName, tokens.access_token, {
+    httpOnly: true,
+    sameSite: "lax",
+    secure,
+    path: config.dashboardBasePath,
+    maxAge,
+  });
+  response.cookies.set(dashboardRefreshTokenCookieName, tokens.refresh_token, {
+    httpOnly: true,
+    sameSite: "lax",
+    secure,
+    path: config.dashboardBasePath,
+  });
+}
+
+export function clearDashboardAuthCookies(
+  response: NextResponse,
+  config: DashboardRuntimeConfig,
+): void {
+  const secure = config.siteURL.startsWith("https://");
+
+  response.cookies.set(dashboardAccessTokenCookieName, "", {
+    httpOnly: true,
+    sameSite: "lax",
+    secure,
+    path: config.dashboardBasePath,
+    maxAge: 0,
+  });
+  response.cookies.set(dashboardRefreshTokenCookieName, "", {
+    httpOnly: true,
+    sameSite: "lax",
+    secure,
+    path: config.dashboardBasePath,
+    maxAge: 0,
+  });
+}

package/src/config.ts

@@ -0,0 +1,60 @@
+import type {
+  DashboardControlPlaneMode,
+  DashboardRuntimeConfig,
+} from "./types";
+
+const defaultDashboardBasePath = "/dashboard";
+
+function normalizeMode(value: string | undefined): DashboardControlPlaneMode {
+  if (value === "global-directory") {
+    return value;
+  }
+  return "single-cluster";
+}
+
+function defaultSiteURL(nodeEnv: string | undefined): string {
+  if (nodeEnv === "development") {
+    return "http://localhost:4300";
+  }
+  return "https://sandbox0.ai";
+}
+
+export function resolveDashboardRuntimeConfig(
+  env: NodeJS.ProcessEnv = process.env,
+): DashboardRuntimeConfig {
+  const mode = normalizeMode(env.SANDBOX0_DASHBOARD_MODE);
+  const siteURL =
+    env.SANDBOX0_DASHBOARD_SITE_URL ?? defaultSiteURL(env.NODE_ENV);
+
+  if (mode === "global-directory") {
+    return {
+      mode,
+      dashboardBasePath: defaultDashboardBasePath,
+      siteURL,
+      globalDirectoryURL:
+        env.SANDBOX0_DASHBOARD_GLOBAL_DIRECTORY_URL ??
+        env.SANDBOX0_BASE_URL ??
+        "https://api.sandbox0.ai",
+    };
+  }
+
+  return {
+    mode,
+    dashboardBasePath: defaultDashboardBasePath,
+    siteURL,
+    singleClusterURL:
+      env.SANDBOX0_DASHBOARD_SINGLE_CLUSTER_URL ??
+      env.SANDBOX0_BASE_URL ??
+      "http://localhost:30080",
+  };
+}
+
+export function resolveDashboardControlPlaneURL(
+  config: DashboardRuntimeConfig,
+): string | undefined {
+  if (config.mode === "global-directory") {
+    return config.globalDirectoryURL;
+  }
+
+  return config.singleClusterURL;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./auth";
+export * from "./config";
+export * from "./sdk";
+export * from "./session";
+export * from "./types";

package/src/sdk.ts

@@ -0,0 +1,65 @@
+type FetchLike = typeof fetch;
+type Sandbox0Module = typeof import("sandbox0");
+
+export interface DashboardControlPlaneSDK {
+  auth: InstanceType<Sandbox0Module["apis"]["AuthApi"]>;
+  users: InstanceType<Sandbox0Module["apis"]["UsersApi"]>;
+  teams: InstanceType<Sandbox0Module["apis"]["TeamsApi"]>;
+  tenant: InstanceType<Sandbox0Module["apis"]["TenantApi"]>;
+  regions: InstanceType<Sandbox0Module["apis"]["RegionsApi"]>;
+  sandboxes: InstanceType<Sandbox0Module["apis"]["SandboxesApi"]>;
+  templates: InstanceType<Sandbox0Module["apis"]["TemplatesApi"]>;
+}
+
+async function loadSandbox0(): Promise<Sandbox0Module> {
+  return import("sandbox0");
+}
+
+export async function createDashboardControlPlaneSDK(
+  baseURL: string,
+  options?: {
+    token?: string;
+    fetch?: FetchLike;
+  },
+): Promise<DashboardControlPlaneSDK> {
+  const { apis, runtime } = await loadSandbox0();
+  const configuration = new runtime.Configuration({
+    basePath: baseURL,
+    accessToken: options?.token ? async () => options.token ?? "" : undefined,
+    fetchApi: options?.fetch,
+  });
+
+  return {
+    auth: new apis.AuthApi(configuration),
+    users: new apis.UsersApi(configuration),
+    teams: new apis.TeamsApi(configuration),
+    tenant: new apis.TenantApi(configuration),
+    regions: new apis.RegionsApi(configuration),
+    sandboxes: new apis.SandboxesApi(configuration),
+    templates: new apis.TemplatesApi(configuration),
+  };
+}
+
+export async function resolveSDKErrorMessage(
+  error: unknown,
+  fallback: string,
+): Promise<string> {
+  const { runtime } = await loadSandbox0();
+
+  if (error instanceof runtime.ResponseError) {
+    const payload = (await error.response
+      .clone()
+      .json()
+      .catch(() => null)) as
+      | {
+          error?: {
+            message?: string;
+          };
+        }
+      | null;
+
+    return payload?.error?.message ?? fallback;
+  }
+
+  return error instanceof Error ? error.message : fallback;
+}

package/src/session.ts

@@ -0,0 +1,298 @@
+import type {
+  DashboardActiveTeam,
+  DashboardRuntimeConfig,
+  DashboardSandboxSummary,
+  DashboardSession,
+  DashboardTeam,
+  DashboardTemplateSummary,
+  DashboardUser,
+} from "./types";
+import { dashboardAccessTokenCookieName } from "./auth";
+import { createDashboardControlPlaneSDK, resolveSDKErrorMessage } from "./sdk";
+
+export interface SessionAuthInput {
+  bearerToken?: string;
+}
+
+type FetchLike = typeof fetch;
+
+function toUser(user: {
+  id: string;
+  email: string;
+  name: string;
+  avatarUrl?: string | null;
+  defaultTeamId?: string | null;
+  emailVerified: boolean;
+  isAdmin: boolean;
+}): DashboardUser {
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    avatarUrl: user.avatarUrl ?? null,
+    defaultTeamID: user.defaultTeamId ?? null,
+    emailVerified: user.emailVerified,
+    isAdmin: user.isAdmin,
+  };
+}
+
+function toTeams(
+  teams: Array<{
+    id: string;
+    name: string;
+    slug: string;
+    ownerId?: string | null;
+    homeRegionId?: string | null;
+  }> = [],
+): DashboardTeam[] {
+  return teams.map((team) => ({
+    id: team.id,
+    name: team.name,
+    slug: team.slug,
+    ownerID: team.ownerId ?? null,
+    homeRegionID: team.homeRegionId ?? null,
+  }));
+}
+
+function toSandboxes(
+  sandboxes: Array<{
+    id: string;
+    templateId: string;
+    status: string;
+    paused: boolean;
+    clusterId?: string | null;
+    createdAt: Date;
+    expiresAt: Date;
+  }> = [],
+): DashboardSandboxSummary[] {
+  return sandboxes.map((sandbox) => ({
+    id: sandbox.id,
+    templateID: sandbox.templateId,
+    status: sandbox.status,
+    paused: sandbox.paused,
+    clusterID: sandbox.clusterId ?? null,
+    createdAt: sandbox.createdAt.toISOString(),
+    expiresAt: sandbox.expiresAt.toISOString(),
+  }));
+}
+
+function toTemplates(
+  templates: Array<{
+    templateId: string;
+    scope: string;
+    createdAt: Date;
+  }> = [],
+): DashboardTemplateSummary[] {
+  return templates.map((template) => ({
+    templateID: template.templateId,
+    scope: template.scope,
+    createdAt: template.createdAt.toISOString(),
+  }));
+}
+
+function deriveSingleClusterActiveTeam(
+  user: DashboardUser,
+  teams: DashboardTeam[],
+  regionalURL: string,
+): DashboardActiveTeam | undefined {
+  const defaultTeam =
+    teams.find((team) => team.id === user.defaultTeamID) ?? teams[0];
+  if (!defaultTeam) {
+    return undefined;
+  }
+
+  return {
+    userID: user.id,
+    teamID: defaultTeam.id,
+    homeRegionID: defaultTeam.homeRegionID ?? "local",
+    defaultTeam: defaultTeam.id === user.defaultTeamID,
+    edgeGatewayURL: regionalURL,
+  };
+}
+
+export function readBearerToken(
+  authorizationHeader: string | null,
+  cookies: Pick<{ get(name: string): { value: string } | undefined }, "get">,
+): string | undefined {
+  if (authorizationHeader?.startsWith("Bearer ")) {
+    return authorizationHeader.slice("Bearer ".length).trim();
+  }
+
+  const cookieNames = [
+    "__Host-sandbox0_access_token",
+    dashboardAccessTokenCookieName,
+    "sandbox0_token",
+  ];
+  for (const cookieName of cookieNames) {
+    const token = cookies.get(cookieName)?.value?.trim();
+    if (token) {
+      return token;
+    }
+  }
+
+  return undefined;
+}
+
+export async function resolveDashboardSession(
+  config: DashboardRuntimeConfig,
+  auth: SessionAuthInput,
+  fetchImpl: FetchLike = fetch,
+): Promise<DashboardSession> {
+  const baseSession: DashboardSession = {
+    authenticated: false,
+    mode: config.mode,
+    dashboardBasePath: config.dashboardBasePath,
+    siteURL: config.siteURL,
+    configuredGlobalURL: config.globalDirectoryURL,
+    configuredRegionalURL:
+      config.mode === "single-cluster" ? config.singleClusterURL : undefined,
+    teams: [],
+    sandboxes: [],
+    templates: [],
+    errors: [],
+  };
+
+  const token = auth.bearerToken?.trim();
+  if (!token) {
+    return baseSession;
+  }
+
+  if (config.mode === "single-cluster") {
+    const baseURL = config.singleClusterURL;
+    if (!baseURL) {
+      return {
+        ...baseSession,
+        errors: ["single-cluster mode is missing a control-plane base URL"],
+      };
+    }
+
+    try {
+      const sdk = await createDashboardControlPlaneSDK(baseURL, {
+        token,
+        fetch: fetchImpl,
+      });
+      const [userResponse, teamResponse, sandboxResponse, templateResponse] =
+        await Promise.all([
+          sdk.users.usersMeGet(),
+          sdk.teams.teamsGet(),
+          sdk.sandboxes.apiV1SandboxesGet({ limit: 5 }),
+          sdk.templates.apiV1TemplatesGet(),
+        ]);
+
+      const userData = userResponse.data;
+      if (!userData) {
+        throw new Error("/users/me returned an empty response");
+      }
+
+      const user = toUser(userData);
+      const teams = toTeams(teamResponse.data?.teams);
+      const activeTeam = deriveSingleClusterActiveTeam(user, teams, baseURL);
+      const sandboxes = toSandboxes(sandboxResponse.data?.sandboxes);
+      const templates = toTemplates(templateResponse.data?.templates);
+
+      return {
+        ...baseSession,
+        authenticated: true,
+        configuredRegionalURL: baseURL,
+        user,
+        teams,
+        activeTeam,
+        sandboxes,
+        templates,
+      };
+    } catch (error) {
+      return {
+        ...baseSession,
+        errors: [await resolveSDKErrorMessage(error, "failed to resolve session")],
+      };
+    }
+  }
+
+  const globalURL = config.globalDirectoryURL;
+  if (!globalURL) {
+    return {
+      ...baseSession,
+      errors: ["global-directory mode is missing a global base URL"],
+    };
+  }
+
+  try {
+    const globalSDK = await createDashboardControlPlaneSDK(globalURL, {
+      token,
+      fetch: fetchImpl,
+    });
+    const [userResponse, teamResponse, activeTeamResponse] = await Promise.all([
+      globalSDK.users.usersMeGet(),
+      globalSDK.teams.teamsGet(),
+      globalSDK.tenant.tenantActiveGet(),
+    ]);
+
+    const userData = userResponse.data;
+    const activeTeamData = activeTeamResponse.data;
+    if (!userData) {
+      throw new Error("/users/me returned an empty response");
+    }
+    if (!activeTeamData) {
+      throw new Error("/tenant/active returned an empty response");
+    }
+
+    const user = toUser(userData);
+    const teams = toTeams(teamResponse.data?.teams);
+    const activeTeam: DashboardActiveTeam = {
+      userID: activeTeamData.userId,
+      teamID: activeTeamData.teamId,
+      teamRole: activeTeamData.teamRole,
+      homeRegionID: activeTeamData.homeRegionId,
+      defaultTeam: Boolean(activeTeamData.defaultTeam),
+      edgeGatewayURL: activeTeamData.edgeGatewayUrl ?? null,
+    };
+
+    let regionalURL = activeTeam.edgeGatewayURL ?? undefined;
+    let regionToken = token;
+    if (regionalURL) {
+      const regionTokenResponse = await globalSDK.tenant.authRegionTokenPost({
+        issueRegionTokenRequest: { teamId: activeTeam.teamID },
+      });
+      const regionTokenData = regionTokenResponse.data;
+      if (!regionTokenData) {
+        throw new Error("/auth/region-token returned an empty response");
+      }
+
+      regionalURL = regionTokenData.edgeGatewayUrl ?? regionalURL;
+      regionToken = regionTokenData.token;
+    }
+
+    const sandboxes = regionalURL
+      ? await (
+          await createDashboardControlPlaneSDK(regionalURL, {
+            token: regionToken,
+            fetch: fetchImpl,
+          })
+        ).sandboxes.apiV1SandboxesGet({ limit: 5 })
+      : undefined;
+    const templates = regionalURL
+      ? await (
+          await createDashboardControlPlaneSDK(regionalURL, {
+            token: regionToken,
+            fetch: fetchImpl,
+          })
+        ).templates.apiV1TemplatesGet()
+      : undefined;
+
+    return {
+      ...baseSession,
+      authenticated: true,
+      configuredRegionalURL: regionalURL,
+      user,
+      teams,
+      activeTeam,
+      sandboxes: toSandboxes(sandboxes?.data?.sandboxes),
+      templates: toTemplates(templates?.data?.templates),
+    };
+  } catch (error) {
+    return {
+      ...baseSession,
+      errors: [await resolveSDKErrorMessage(error, "failed to resolve session")],
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+export type DashboardControlPlaneMode = "single-cluster" | "global-directory";
+
+export interface DashboardRuntimeConfig {
+  mode: DashboardControlPlaneMode;
+  dashboardBasePath: string;
+  siteURL: string;
+  singleClusterURL?: string;
+  globalDirectoryURL?: string;
+}
+
+export type DashboardAuthProviderType = "oidc" | "builtin";
+
+export interface DashboardAuthProvider {
+  id: string;
+  name: string;
+  type: DashboardAuthProviderType;
+}
+
+export interface DashboardUser {
+  id: string;
+  email: string;
+  name: string;
+  avatarUrl?: string | null;
+  defaultTeamID?: string | null;
+  emailVerified: boolean;
+  isAdmin: boolean;
+}
+
+export interface DashboardTeam {
+  id: string;
+  name: string;
+  slug: string;
+  ownerID?: string | null;
+  homeRegionID?: string | null;
+}
+
+export interface DashboardActiveTeam {
+  userID: string;
+  teamID: string;
+  teamRole?: string;
+  homeRegionID: string;
+  defaultTeam: boolean;
+  edgeGatewayURL?: string | null;
+}
+
+export interface DashboardSandboxSummary {
+  id: string;
+  templateID: string;
+  status: string;
+  paused: boolean;
+  clusterID?: string | null;
+  createdAt: string;
+  expiresAt: string;
+}
+
+export interface DashboardTemplateSummary {
+  templateID: string;
+  scope: string;
+  createdAt: string;
+}
+
+export interface DashboardSession {
+  authenticated: boolean;
+  mode: DashboardControlPlaneMode;
+  dashboardBasePath: string;
+  siteURL: string;
+  configuredGlobalURL?: string;
+  configuredRegionalURL?: string;
+  user?: DashboardUser;
+  teams: DashboardTeam[];
+  activeTeam?: DashboardActiveTeam;
+  sandboxes: DashboardSandboxSummary[];
+  templates: DashboardTemplateSummary[];
+  errors: string[];
+}