otavia 0.1.0

package/src/commands/dev/tunnel.ts

@@ -0,0 +1,176 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import concurrently from "concurrently";
+import { parse as parseYaml } from "yaml";
+
+type TunnelConfig = {
+  ingress?: Array<{ hostname?: string }>;
+};
+
+export type TunnelHandle = {
+  publicBaseUrl: string;
+  stop: () => void;
+};
+
+const TUNNEL_LOG_LEVELS = ["debug", "info", "warn", "error"] as const;
+type TunnelLogLevel = (typeof TUNNEL_LOG_LEVELS)[number];
+const DEFAULT_TUNNEL_LOG_LEVEL: TunnelLogLevel = "warn";
+const TUNNEL_PROTOCOLS = ["auto", "quic", "http2"] as const;
+type TunnelProtocol = (typeof TUNNEL_PROTOCOLS)[number];
+const DEFAULT_TUNNEL_PROTOCOL: TunnelProtocol = "quic";
+
+export function extractTunnelHostFromConfig(configContent: string): string | null {
+  const parsed = parseYaml(configContent) as TunnelConfig | null;
+  const ingress = parsed?.ingress;
+  if (!Array.isArray(ingress)) return null;
+  for (const rule of ingress) {
+    const host = rule?.hostname?.trim();
+    if (!host) continue;
+    if (host.startsWith("*.")) continue;
+    return host;
+  }
+  return null;
+}
+
+export function normalizeTunnelPublicBaseUrl(hostOrUrl: string): string {
+  const trimmed = hostOrUrl.trim().replace(/\/$/, "");
+  if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
+    return trimmed;
+  }
+  return `https://${trimmed}`;
+}
+
+export function defaultTunnelConfigPath(rootDir: string): string {
+  const fromEnv = process.env.OTAVIA_TUNNEL_CONFIG?.trim();
+  if (fromEnv) return fromEnv;
+  const projectPath = resolve(rootDir, ".otavia", "tunnel", "config.yml");
+  if (existsSync(projectPath)) return projectPath;
+  const globalConfig = resolve(homedir(), ".config", "otavia", "config.yml");
+  if (existsSync(globalConfig)) return globalConfig;
+  const legacyGlobalConfig = resolve(homedir(), ".config", "otavia", "tunnel.yaml");
+  return legacyGlobalConfig;
+}
+
+export function resolveTunnelLogLevel(level?: string): TunnelLogLevel {
+  const normalized = (level ?? process.env.OTAVIA_TUNNEL_LOG_LEVEL ?? DEFAULT_TUNNEL_LOG_LEVEL)
+    .trim()
+    .toLowerCase();
+  if (TUNNEL_LOG_LEVELS.includes(normalized as TunnelLogLevel)) {
+    return normalized as TunnelLogLevel;
+  }
+  throw new Error(
+    `Invalid tunnel log level "${normalized}". Expected one of: ${TUNNEL_LOG_LEVELS.join(", ")}.`
+  );
+}
+
+export function resolveTunnelProtocol(protocol?: string): TunnelProtocol {
+  const normalized = (protocol ?? process.env.OTAVIA_TUNNEL_PROTOCOL ?? DEFAULT_TUNNEL_PROTOCOL)
+    .trim()
+    .toLowerCase();
+  if (TUNNEL_PROTOCOLS.includes(normalized as TunnelProtocol)) {
+    return normalized as TunnelProtocol;
+  }
+  throw new Error(
+    `Invalid tunnel protocol "${normalized}". Expected one of: ${TUNNEL_PROTOCOLS.join(", ")}.`
+  );
+}
+
+export function buildCloudflaredTunnelCommand(
+  tunnelConfigPath: string,
+  tunnelLogLevel: TunnelLogLevel,
+  tunnelProtocol: TunnelProtocol
+): string {
+  return `cloudflared tunnel --loglevel ${tunnelLogLevel} --protocol ${tunnelProtocol} --config ${JSON.stringify(tunnelConfigPath)} run`;
+}
+
+export async function startTunnel(
+  rootDir: string,
+  options?: {
+    tunnelConfigPath?: string;
+    tunnelHost?: string;
+    tunnelLogLevel?: string;
+    tunnelProtocol?: string;
+  }
+): Promise<TunnelHandle> {
+  const tunnelConfigPath = options?.tunnelConfigPath ?? defaultTunnelConfigPath(rootDir);
+  if (!existsSync(tunnelConfigPath)) {
+    console.log("[tunnel] No tunnel config found. Running auto-setup...");
+    // Set OTAVIA_TUNNEL_DEV_ROOT from otavia.yaml dns.zone if not already set
+    const { loadOtaviaYaml } = await import("../../config/load-otavia-yaml.js");
+    if (!process.env.OTAVIA_TUNNEL_DEV_ROOT) {
+      const otavia = loadOtaviaYaml(rootDir);
+      const zone = otavia.domain?.dns?.zone;
+      if (zone) {
+        process.env.OTAVIA_TUNNEL_DEV_ROOT = zone;
+      }
+    }
+    const { setupCommand } = await import("../setup.js");
+    await setupCommand(rootDir, { tunnel: true });
+    if (!existsSync(tunnelConfigPath)) {
+      throw new Error(
+        `Tunnel config not found after auto-setup: ${tunnelConfigPath}. Run setup manually or pass --tunnel-config.`
+      );
+    }
+  }
+  const cloudflaredExit = await Bun.spawn(["cloudflared", "--version"], {
+    stdout: "pipe",
+    stderr: "pipe",
+  }).exited;
+  if (cloudflaredExit !== 0) {
+    throw new Error(
+      "cloudflared not found. Install from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/"
+    );
+  }
+
+  const configText = await Bun.file(tunnelConfigPath).text();
+  const host =
+    options?.tunnelHost?.trim() ||
+    process.env.OTAVIA_TUNNEL_HOST?.trim() ||
+    extractTunnelHostFromConfig(configText);
+  if (!host) {
+    throw new Error(
+      `Cannot find tunnel hostname in ${tunnelConfigPath}. Add ingress.hostname or pass --tunnel-host.`
+    );
+  }
+  const publicBaseUrl = normalizeTunnelPublicBaseUrl(host);
+  const tunnelLogLevel = resolveTunnelLogLevel(options?.tunnelLogLevel);
+  const tunnelProtocol = resolveTunnelProtocol(options?.tunnelProtocol);
+  const tunnelCommand = buildCloudflaredTunnelCommand(tunnelConfigPath, tunnelLogLevel, tunnelProtocol);
+  const { commands, result } = concurrently(
+    [
+      {
+        command: tunnelCommand,
+        name: "tunnel",
+        cwd: rootDir,
+        env: { ...process.env },
+      },
+    ],
+    {
+      prefix: "[{name}]",
+      prefixColors: ["cyan"],
+      raw: false,
+      handleInput: false,
+      killOthersOn: ["failure"],
+    }
+  );
+  let stopped = false;
+  result.catch((events) => {
+    if (stopped) return;
+    const tunnelEvent = Array.isArray(events) ? events.find((event) => event.command.name === "tunnel") : null;
+    const exitCode = tunnelEvent?.exitCode;
+    console.error(`[tunnel] cloudflared exited with code ${exitCode ?? "unknown"}`);
+  });
+  result.then(() => {
+    if (stopped) return;
+    console.error("[tunnel] cloudflared exited.");
+  });
+
+  return {
+    publicBaseUrl,
+    stop: () => {
+      stopped = true;
+      commands[0]?.kill("SIGTERM");
+    },
+  };
+}

package/src/commands/dev/vite-dev.ts

@@ -0,0 +1,382 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { loadOtaviaYaml } from "../../config/load-otavia-yaml.js";
+import { loadCellConfig } from "../../config/load-cell-yaml.js";
+import type { CellConfig } from "../../config/cell-yaml-schema.js";
+import { resolveCellDir } from "../../config/resolve-cell-dir.js";
+import { resolveRootRedirectMount } from "./mount-selection.js";
+
+export interface ViteDevHandle {
+  stop: () => void;
+}
+
+export type RouteMatch = "prefix" | "exact";
+
+export type RouteRule = {
+  path: string;
+  match: RouteMatch;
+};
+
+export type ProxyRule = {
+  mount: string;
+  path: string;
+  match: RouteMatch;
+  target: string;
+};
+
+export type MainDevGeneratedConfig = {
+  firstMount: string;
+  mounts: string[];
+  routeRules: RouteRule[];
+  proxyRules: ProxyRule[];
+  frontendModuleProxyRules: Array<{
+    path: string;
+    sourcePath: string;
+  }>;
+  frontendRouteRules: Array<{
+    mount: string;
+    path: string;
+    match: RouteMatch;
+    entryName: string;
+    entryType: "html" | "module";
+  }>;
+};
+
+const GLOBAL_WELL_KNOWN_RULE: RouteRule = { path: "/.well-known", match: "prefix" };
+const GLOBAL_PROXY_MOUNT = "__global__";
+
+const MAIN_FRONTEND_INDEX_HTML = `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Otavia Main</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+`;
+
+const MAIN_FRONTEND_ENTRY_TS = `import { rootRedirectMount, mountLoaders, mounts } from "./generated/mount-loaders";
+import { bootMainFrontend } from "otavia/dev/main-frontend-runtime/main-entry";
+
+void bootMainFrontend(rootRedirectMount, mounts, mountLoaders);
+`;
+
+const MAIN_FRONTEND_VITE_CONFIG_TS = `import { createMainFrontendViteConfig } from "otavia/dev/main-frontend-runtime/vite-config";
+
+const backendPort = process.env.GATEWAY_BACKEND_PORT;
+const vitePort = Number.parseInt(process.env.VITE_PORT ?? "", 10);
+const generatedConfigPath = new URL("./src/generated/main-dev-config.json", import.meta.url);
+const packageRoot = process.env.OTAVIA_MAIN_ROOT ?? process.cwd();
+
+if (!backendPort) {
+  throw new Error("Missing GATEWAY_BACKEND_PORT");
+}
+if (!Number.isFinite(vitePort)) {
+  throw new Error("Missing VITE_PORT");
+}
+
+export default createMainFrontendViteConfig({
+  generatedConfigPath,
+  packageRoot,
+  backendPort,
+  vitePort,
+});
+`;
+
+function writeMainFrontendShell(frontendRoot: string): void {
+  const srcDir = resolve(frontendRoot, "src");
+  const generatedDir = resolve(srcDir, "generated");
+  mkdirSync(generatedDir, { recursive: true });
+  writeFileSync(resolve(frontendRoot, "index.html"), MAIN_FRONTEND_INDEX_HTML, "utf-8");
+  writeFileSync(resolve(frontendRoot, "vite.config.ts"), MAIN_FRONTEND_VITE_CONFIG_TS, "utf-8");
+  writeFileSync(resolve(srcDir, "main.ts"), MAIN_FRONTEND_ENTRY_TS, "utf-8");
+}
+
+function normalizeRoutePath(path: string): string {
+  if (!path.startsWith("/")) {
+    throw new Error(`Invalid backend route "${path}": route must start with "/"`);
+  }
+  const trimmed = path.replace(/\/+$/, "");
+  return trimmed || "/";
+}
+
+export function deriveRouteRulesFromCellConfig(config: CellConfig): RouteRule[] {
+  const seen = new Set<string>();
+  const rules: RouteRule[] = [];
+  const entries = config.backend?.entries ? Object.values(config.backend.entries) : [];
+  for (const entry of entries) {
+    for (const route of entry.routes ?? []) {
+      const isPrefix = route.endsWith("/*");
+      const rawPath = isPrefix ? route.slice(0, -2) : route;
+      const path = normalizeRoutePath(rawPath);
+      const match: RouteMatch = isPrefix ? "prefix" : "exact";
+      const key = `${path}|${match}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      rules.push({ path, match });
+    }
+  }
+  return rules;
+}
+
+export function buildMainDevGeneratedConfig(
+  cells: Array<{
+    mount: string;
+    routeRules: RouteRule[];
+    moduleProxySpecs: FrontendModuleProxySpec[];
+    frontendRouteRules: Array<{
+      mount: string;
+      path: string;
+      match: RouteMatch;
+      entryName: string;
+      entryType: "html" | "module";
+    }>;
+  }>,
+  backendPort: number,
+  sourcePathBaseDir?: string
+): MainDevGeneratedConfig {
+  const mounts = cells.map((c) => c.mount);
+  const firstMount = mounts[0] ?? "";
+  const routeRulesMap = new Map<string, RouteRule>();
+  const proxyRules: ProxyRule[] = [];
+  const frontendModuleProxyRules: MainDevGeneratedConfig["frontendModuleProxyRules"] = [];
+  const frontendRouteRules: MainDevGeneratedConfig["frontendRouteRules"] = [];
+  const target = `http://localhost:${backendPort}`;
+
+  for (const cell of cells) {
+    frontendModuleProxyRules.push(
+      ...cell.moduleProxySpecs.map((spec) => ({
+        path: spec.routePath,
+        sourcePath: sourcePathBaseDir
+          ? relative(sourcePathBaseDir, spec.sourcePath).replace(/\\/g, "/")
+          : spec.sourcePath,
+      }))
+    );
+    frontendRouteRules.push(...cell.frontendRouteRules);
+    for (const rule of cell.routeRules) {
+      const rrKey = `${rule.path}|${rule.match}`;
+      if (!routeRulesMap.has(rrKey)) routeRulesMap.set(rrKey, rule);
+      const mountedPath = rule.path === "/" ? `/${cell.mount}` : `/${cell.mount}${rule.path}`;
+      proxyRules.push({
+        mount: cell.mount,
+        path: mountedPath,
+        match: rule.match,
+        target,
+      });
+    }
+  }
+
+  const globalRuleKey = `${GLOBAL_WELL_KNOWN_RULE.path}|${GLOBAL_WELL_KNOWN_RULE.match}`;
+  if (!routeRulesMap.has(globalRuleKey)) {
+    routeRulesMap.set(globalRuleKey, GLOBAL_WELL_KNOWN_RULE);
+  }
+  proxyRules.push({
+    mount: GLOBAL_PROXY_MOUNT,
+    path: GLOBAL_WELL_KNOWN_RULE.path,
+    match: GLOBAL_WELL_KNOWN_RULE.match,
+    target,
+  });
+
+  proxyRules.sort((a, b) => {
+    if (a.path === b.path) {
+      if (a.match === b.match) return a.mount.localeCompare(b.mount);
+      return a.match === "exact" ? -1 : 1;
+    }
+    return b.path.length - a.path.length;
+  });
+
+  return {
+    firstMount,
+    mounts,
+    routeRules: Array.from(routeRulesMap.values()),
+    proxyRules,
+    frontendModuleProxyRules,
+    frontendRouteRules,
+  };
+}
+
+function normalizeFrontendRoutePath(path: string): string {
+  if (path === "") return "/";
+  if (!path.startsWith("/")) {
+    throw new Error(`Invalid frontend route "${path}": route must start with "/"`);
+  }
+  const trimmed = path.replace(/\/+$/, "");
+  return trimmed || "/";
+}
+
+function toMountedPath(mount: string, routePath: string): string {
+  const normalizedRoute = normalizeFrontendRoutePath(routePath);
+  return normalizedRoute === "/" ? `/${mount}` : `/${mount}${normalizedRoute}`;
+}
+
+function isHtmlEntry(entry: string): boolean {
+  return entry.toLowerCase().endsWith(".html");
+}
+
+export function deriveFrontendRouteRulesFromCellConfig(
+  mount: string,
+  config: CellConfig
+): MainDevGeneratedConfig["frontendRouteRules"] {
+  const entries = config.frontend?.entries ? Object.entries(config.frontend.entries) : [];
+  const rules: MainDevGeneratedConfig["frontendRouteRules"] = [];
+  for (const [entryName, entry] of entries) {
+    const entryType: "html" | "module" = isHtmlEntry(entry.entry) ? "html" : "module";
+    for (const route of entry.routes ?? []) {
+      const isPrefix = route.endsWith("/*");
+      const rawPath = isPrefix ? route.slice(0, -2) : route;
+      const path = toMountedPath(mount, rawPath);
+      rules.push({
+        mount,
+        path,
+        match: isPrefix ? "prefix" : "exact",
+        entryName,
+        entryType,
+      });
+    }
+  }
+  return rules;
+}
+
+type FrontendModuleProxySpec = {
+  mount: string;
+  routePath: string;
+  sourcePath: string;
+};
+
+export function deriveFrontendModuleProxySpecs(
+  mount: string,
+  cellDir: string,
+  config: CellConfig
+): FrontendModuleProxySpec[] {
+  if (!config.frontend) return [];
+  const specs: FrontendModuleProxySpec[] = [];
+  for (const entry of Object.values(config.frontend.entries)) {
+    if (isHtmlEntry(entry.entry)) continue;
+    const sourcePath = resolve(cellDir, config.frontend.dir, entry.entry).replace(/\\/g, "/");
+    for (const route of entry.routes ?? []) {
+      if (route.endsWith("/*")) {
+        throw new Error(
+          `Invalid module frontend route "${route}" for mount "${mount}": wildcard routes are only supported for HTML entries`
+        );
+      }
+      specs.push({
+        mount,
+        routePath: toMountedPath(mount, route),
+        sourcePath,
+      });
+    }
+  }
+  return specs;
+}
+
+/**
+ * Start main frontend Vite dev server (single root MPA shell):
+ * - root is apps/main/.otavia/dev/main-frontend
+ * - dynamically loads each cell frontend via package exports ("@pkg/frontend")
+ * - proxies API/OAuth requests to backend gateway with mount-aware rewrite
+ * If no cell has frontend, returns a no-op stop.
+ */
+export async function startViteDev(
+  rootDir: string,
+  backendPort: number,
+  vitePort: number,
+  publicBaseUrl?: string
+): Promise<ViteDevHandle> {
+  const root = resolve(rootDir);
+  const otavia = loadOtaviaYaml(root);
+  const cellsWithFrontend: {
+    mount: string;
+    packageName: string;
+    routeRules: RouteRule[];
+    frontendRouteRules: MainDevGeneratedConfig["frontendRouteRules"];
+    moduleProxySpecs: FrontendModuleProxySpec[];
+  }[] = [];
+
+  for (const entry of otavia.cellsList) {
+    const cellDir = resolveCellDir(root, entry.package);
+    const cellYamlPath = resolve(cellDir, "cell.yaml");
+    if (!existsSync(cellYamlPath)) continue;
+    const config = loadCellConfig(cellDir);
+    if (!config.frontend?.dir) continue;
+    const routeRules = deriveRouteRulesFromCellConfig(config);
+    const frontendRouteRules = deriveFrontendRouteRulesFromCellConfig(entry.mount, config);
+    const moduleProxySpecs = deriveFrontendModuleProxySpecs(entry.mount, cellDir, config);
+    cellsWithFrontend.push({
+      mount: entry.mount,
+      packageName: entry.package,
+      routeRules,
+      frontendRouteRules,
+      moduleProxySpecs,
+    });
+  }
+
+  if (cellsWithFrontend.length === 0) {
+    console.log("[vite] No cells with frontend, skipping Vite dev server");
+    return { stop: () => {} };
+  }
+
+  const frontendRoot = resolve(root, ".otavia", "dev", "main-frontend");
+  writeMainFrontendShell(frontendRoot);
+  const srcDir = resolve(frontendRoot, "src");
+  const generatedDir = resolve(srcDir, "generated");
+  mkdirSync(generatedDir, { recursive: true });
+
+  const generatedLoadersPath = resolve(generatedDir, "mount-loaders.ts");
+  const generatedDevConfigPath = resolve(generatedDir, "main-dev-config.json");
+  const firstMount = cellsWithFrontend[0].mount;
+  const rootRedirectMount = resolveRootRedirectMount(
+    cellsWithFrontend.map((c) => c.mount),
+    otavia.defaultCell
+  );
+  const loadersSource = `// Auto-generated by otavia dev. Do not edit.
+export const firstMount = ${JSON.stringify(firstMount)};
+export const rootRedirectMount = ${JSON.stringify(rootRedirectMount)};
+export const mounts = ${JSON.stringify(cellsWithFrontend.map((c) => c.mount))};
+export const mountLoaders = {
+${cellsWithFrontend
+  .map((c) => `  ${JSON.stringify(c.mount)}: () => import(${JSON.stringify(`${c.packageName}/frontend`)}),`)
+  .join("\n")}
+} as Record<string, () => Promise<unknown>>;
+`;
+  writeFileSync(generatedLoadersPath, loadersSource, "utf-8");
+  const generatedDevConfig = buildMainDevGeneratedConfig(cellsWithFrontend, backendPort, root);
+  writeFileSync(generatedDevConfigPath, JSON.stringify(generatedDevConfig, null, 2), "utf-8");
+
+  const env = {
+    ...process.env,
+    OTAVIA_MOUNTS: JSON.stringify(cellsWithFrontend.map((c) => c.mount)),
+    OTAVIA_FIRST_MOUNT: firstMount,
+    VITE_PORT: String(vitePort),
+    GATEWAY_BACKEND_PORT: String(backendPort),
+    OTAVIA_MAIN_ROOT: root,
+  };
+
+  const configPath = resolve(frontendRoot, "vite.config.ts");
+  const child = Bun.spawn(["bun", "x", "vite", "--config", configPath], {
+    cwd: frontendRoot,
+    env,
+    stdio: ["ignore", "inherit", "inherit"],
+  });
+
+  const stop = () => {
+    child.kill();
+  };
+
+  child.exited.then((code) => {
+    if (code !== 0 && code !== null) {
+      console.error(`[vite] Process exited with code ${code}`);
+    }
+  });
+
+  const base = publicBaseUrl?.replace(/\/$/, "") ?? `http://localhost:${vitePort}`;
+  console.log(
+    `[vite] Main frontend dev server starting at ${base} (mounts: ${cellsWithFrontend
+      .map((c) => c.mount)
+      .join(", ")})`
+  );
+  return { stop };
+}

package/src/commands/dev/well-known.ts

@@ -0,0 +1,76 @@
+import type { Context } from "hono";
+import type { CellConfig } from "../../config/cell-yaml-schema.js";
+
+const AUTHORIZATION_SERVER_WELL_KNOWN_PREFIX = "/.well-known/oauth-authorization-server";
+const PROTECTED_RESOURCE_WELL_KNOWN_PREFIX = "/.well-known/oauth-protected-resource";
+
+type OAuthEnabledCell = {
+  mount: string;
+  config: CellConfig;
+};
+
+export function extractMountFromAuthorizationServerWellKnownPath(pathname: string): string | null {
+  if (pathname === AUTHORIZATION_SERVER_WELL_KNOWN_PREFIX) return null;
+  if (!pathname.startsWith(`${AUTHORIZATION_SERVER_WELL_KNOWN_PREFIX}/`)) return null;
+  const suffix = pathname.slice(`${AUTHORIZATION_SERVER_WELL_KNOWN_PREFIX}/`.length).replace(/\/+$/, "");
+  if (!suffix || suffix.includes("/")) return null;
+  return suffix;
+}
+
+export function createOAuthDiscoveryRegistry(cells: OAuthEnabledCell[]): Map<string, { scopes: string[] }> {
+  const registry = new Map<string, { scopes: string[] }>();
+  for (const cell of cells) {
+    const oauth = cell.config.oauth;
+    if (!oauth?.enabled) continue;
+    registry.set(cell.mount, { scopes: oauth.scopes });
+  }
+  return registry;
+}
+
+export function getRequestOrigin(c: Context): string {
+  const forwardedHost = c.req.header("X-Forwarded-Host");
+  const forwardedProto = c.req.header("X-Forwarded-Proto");
+  if (forwardedHost) {
+    const proto = forwardedProto ?? (forwardedHost.includes("localhost") ? "http" : "https");
+    return `${proto}://${forwardedHost}`.replace(/\/$/, "");
+  }
+  return new URL(c.req.url).origin.replace(/\/$/, "");
+}
+
+export function buildOAuthAuthorizationServerMetadata(origin: string, mount: string, scopes: string[]) {
+  const cleanOrigin = origin.replace(/\/$/, "");
+  const issuer = `${cleanOrigin}/${mount}`;
+  return {
+    issuer,
+    authorization_endpoint: `${issuer}/oauth/authorize`,
+    token_endpoint: `${issuer}/oauth/token`,
+    registration_endpoint: `${issuer}/oauth/register`,
+    response_types_supported: ["code"],
+    grant_types_supported: ["authorization_code", "refresh_token"],
+    code_challenge_methods_supported: ["S256"],
+    scopes_supported: scopes,
+  };
+}
+
+export function extractProtectedResourcePathFromWellKnown(pathname: string): string | null {
+  if (pathname === PROTECTED_RESOURCE_WELL_KNOWN_PREFIX) return null;
+  if (!pathname.startsWith(`${PROTECTED_RESOURCE_WELL_KNOWN_PREFIX}/`)) return null;
+  const suffix = pathname.slice(PROTECTED_RESOURCE_WELL_KNOWN_PREFIX.length).replace(/\/+$/, "");
+  if (!suffix || suffix === "/") return null;
+  return suffix.startsWith("/") ? suffix : `/${suffix}`;
+}
+
+export function buildOAuthProtectedResourceMetadata(
+  origin: string,
+  resourcePath: string,
+  mount: string,
+  scopes: string[]
+) {
+  const cleanOrigin = origin.replace(/\/$/, "");
+  return {
+    authorization_servers: [`${cleanOrigin}/${mount}`],
+    resource: `${cleanOrigin}${resourcePath}`,
+    scopes_supported: scopes,
+  };
+}
+