@opengeni/api-router 0.2.0

package/src/auth/managed-auth.ts

@@ -0,0 +1,237 @@
+import type { Settings } from "@opengeni/config";
+import { type ManagedAuth } from "@opengeni/core";
+import type { Database } from "@opengeni/db";
+import { ensureManagedAccessForUser } from "@opengeni/db";
+import { betterAuth } from "better-auth";
+import { createEmailVerificationToken } from "better-auth/api";
+import { Pool } from "pg";
+import { Resend } from "resend";
+
+// `ManagedAuth` (the Better Auth `Auth<any>` alias) is owned by @opengeni/core
+// (`managed-auth-type.ts`) — `dependencies.ts`/`access` reference it as a
+// type-only slot. We re-export it from this construction site so existing
+// importers (`app.ts`) keep the same import path.
+export type { ManagedAuth };
+
+export function createManagedAuth(settings: Settings, db: Database): ManagedAuth | null {
+  if (settings.productAccessMode !== "managed") {
+    return null;
+  }
+  const pool = new Pool({ connectionString: settings.databaseUrl });
+  return betterAuth({
+    appName: "OpenGeni",
+    baseURL: betterAuthBaseUrl(settings),
+    basePath: "/v1/auth",
+    secret: settings.betterAuthSecret,
+    database: pool,
+    trustedOrigins: betterAuthTrustedOrigins(settings),
+    advanced: {
+      useSecureCookies: settings.publicBaseUrl?.startsWith("https://") ?? false,
+      ...(settings.betterAuthCookieDomain ? {
+        crossSubDomainCookies: {
+          enabled: true,
+          domain: settings.betterAuthCookieDomain,
+        },
+      } : {}),
+      database: {
+        generateId: () => crypto.randomUUID(),
+      },
+    },
+    rateLimit: {
+      enabled: true,
+      storage: "database",
+      modelName: "auth_rate_limits",
+      fields: {
+        lastRequest: "last_request",
+      },
+    },
+    user: {
+      modelName: "auth_users",
+      fields: {
+        emailVerified: "email_verified",
+        createdAt: "created_at",
+        updatedAt: "updated_at",
+      },
+    },
+    session: {
+      modelName: "auth_sessions",
+      fields: {
+        userId: "user_id",
+        expiresAt: "expires_at",
+        ipAddress: "ip_address",
+        userAgent: "user_agent",
+        createdAt: "created_at",
+        updatedAt: "updated_at",
+      },
+    },
+    account: {
+      modelName: "auth_identities",
+      fields: {
+        userId: "user_id",
+        accountId: "account_id",
+        providerId: "provider_id",
+        accessToken: "access_token",
+        refreshToken: "refresh_token",
+        idToken: "id_token",
+        accessTokenExpiresAt: "access_token_expires_at",
+        refreshTokenExpiresAt: "refresh_token_expires_at",
+        createdAt: "created_at",
+        updatedAt: "updated_at",
+      },
+      accountLinking: {
+        enabled: false,
+      },
+    },
+    verification: {
+      modelName: "auth_verifications",
+      fields: {
+        expiresAt: "expires_at",
+        createdAt: "created_at",
+        updatedAt: "updated_at",
+      },
+      storeIdentifier: "hashed",
+    },
+    emailAndPassword: {
+      enabled: true,
+      requireEmailVerification: true,
+      revokeSessionsOnPasswordReset: true,
+      onExistingUserSignUp: async ({ user }) => {
+        if (!user.emailVerified) {
+          const url = await verificationUrl(settings, user.email);
+          await sendEmail(settings, {
+            to: user.email,
+            subject: "Verify your OpenGeni email",
+            text: `Verify your OpenGeni email: ${url}`,
+            html: `<p>Verify your OpenGeni email:</p><p><a href="${escapeHtml(url)}">Verify email</a></p>`,
+          });
+        }
+      },
+      sendResetPassword: async ({ user, url }) => {
+        await sendEmail(settings, {
+          to: user.email,
+          subject: "Reset your OpenGeni password",
+          text: `Reset your OpenGeni password: ${url}`,
+          html: `<p>Reset your OpenGeni password:</p><p><a href="${escapeHtml(url)}">Reset password</a></p>`,
+        });
+      },
+    },
+    emailVerification: {
+      sendOnSignUp: true,
+      sendVerificationEmail: async ({ user, url }) => {
+        await sendEmail(settings, {
+          to: user.email,
+          subject: "Verify your OpenGeni email",
+          text: `Verify your OpenGeni email: ${url}`,
+          html: `<p>Verify your OpenGeni email:</p><p><a href="${escapeHtml(url)}">Verify email</a></p>`,
+        });
+      },
+      afterEmailVerification: async (user) => {
+        await ensureManagedAccessForUser(db, {
+          userId: user.id,
+          email: user.email,
+          name: user.name,
+        });
+      },
+    },
+    databaseHooks: {
+      user: {
+        create: {
+          after: async (user) => {
+            await ensureManagedAccessForUser(db, {
+              userId: user.id,
+              email: user.email,
+              name: user.name,
+            });
+          },
+        },
+      },
+    },
+  }) as ManagedAuth;
+}
+
+export async function managedSessionAccessContext(auth: ManagedAuth, db: Database, headers: Headers) {
+  const session = await auth.api.getSession({ headers });
+  if (!session?.user) {
+    return null;
+  }
+  return await ensureManagedAccessForUser(db, {
+    userId: session.user.id,
+    email: session.user.email,
+    name: session.user.name,
+  });
+}
+
+function betterAuthBaseUrl(settings: Settings) {
+  const allowedHosts = splitCsv(settings.betterAuthAllowedHosts);
+  if (allowedHosts.length === 0) {
+    return settings.publicBaseUrl;
+  }
+  return {
+    allowedHosts,
+    fallback: settings.publicBaseUrl,
+    protocol: "auto" as const,
+  };
+}
+
+function betterAuthTrustedOrigins(settings: Settings): string[] {
+  const origins = new Set<string>();
+  if (settings.publicBaseUrl) {
+    origins.add(new URL(settings.publicBaseUrl).origin);
+  }
+  for (const origin of splitCsv(settings.betterAuthTrustedOrigins)) {
+    origins.add(origin);
+  }
+  return [...origins];
+}
+
+async function sendEmail(settings: Settings, input: {
+  to: string;
+  subject: string;
+  text: string;
+  html: string;
+}): Promise<void> {
+  if (!settings.resendApiKey) {
+    if (settings.environment === "local" || settings.environment === "test") {
+      console.warn(`[opengeni] Skipping email to ${input.to}: OPENGENI_RESEND_API_KEY is not configured`);
+      return;
+    }
+    throw new Error("OPENGENI_RESEND_API_KEY is required to send managed auth email");
+  }
+  const resend = new Resend(settings.resendApiKey);
+  const result = await resend.emails.send({
+    from: settings.emailFrom,
+    to: input.to,
+    subject: input.subject,
+    text: input.text,
+    html: input.html,
+  });
+  if (result.error) {
+    throw new Error(result.error.message);
+  }
+}
+
+async function verificationUrl(settings: Settings, email: string): Promise<string> {
+  if (!settings.betterAuthSecret) {
+    throw new Error("OPENGENI_BETTER_AUTH_SECRET is required to send managed auth verification email");
+  }
+  if (!settings.publicBaseUrl) {
+    throw new Error("OPENGENI_PUBLIC_BASE_URL is required to send managed auth verification email");
+  }
+  const token = await createEmailVerificationToken(settings.betterAuthSecret, email);
+  const url = new URL("/v1/auth/verify-email", settings.publicBaseUrl);
+  url.searchParams.set("token", token);
+  url.searchParams.set("callbackURL", "/");
+  return url.toString();
+}
+
+function splitCsv(raw: string): string[] {
+  return raw.split(",").map((value) => value.trim()).filter(Boolean);
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}

package/src/http/auth.ts

@@ -0,0 +1,92 @@
+import type { Settings } from "@opengeni/config";
+import type { Context, MiddlewareHandler } from "hono";
+import { installExactPaths, isInstallRedirectPath } from "../routes/install";
+
+const githubConnectPathPattern = /^\/v1\/workspaces\/[^/]+\/github\/connect$/;
+
+export function requireAccessKey(settings: Settings): MiddlewareHandler {
+  return async (c, next) => {
+    // §7.2 P1: requireAccessKey is the coarse NETWORK perimeter, not the
+    // per-tenant identity gate (that is resolveAccessContext). When
+    // `authRequired:false` it is a NO-OP — the embedded (Path 2) case where the
+    // host's own auth is the sole human gate and OpenGeni is mounted behind it.
+    // Standalone/separate deployments set `authRequired:true` to keep this ON as
+    // the shared-deployment-key perimeter.
+    if (!settings.authRequired || isAuthExempt(c, settings)) {
+      await next();
+      return;
+    }
+    if (isAuthorized(c, settings.accessKey)) {
+      await next();
+      return;
+    }
+    return c.json({ error: "unauthorized" }, 401);
+  };
+}
+
+function isAuthExempt(c: Context, settings: Settings): boolean {
+  if (c.req.method === "OPTIONS") {
+    return true;
+  }
+  const path = new URL(c.req.url).pathname;
+  if (path === "/v1/config/client") {
+    return true;
+  }
+  if (path === "/v1/auth" || path.startsWith("/v1/auth/")) {
+    return true;
+  }
+  if (path === "/v1/webhooks/stripe") {
+    return true;
+  }
+  if (
+    path === "/v1/github/setup" ||
+    path === "/v1/github/install/callback" ||
+    path === "/v1/github/oauth/callback" ||
+    path === "/v1/github/app-manifest/callback"
+  ) {
+    return true;
+  }
+  // Browser entry for MCP-issued GitHub install links: opened in a browser
+  // that holds no API credentials, like the callbacks above. The route itself
+  // verifies the signed workspace-bound state before doing anything.
+  if (githubConnectPathPattern.test(path)) {
+    return true;
+  }
+  // The get.<domain> install-serving routes (install.sh/.ps1/uninstall.sh/
+  // minisign pub + the release-binary redirects). Reached by a fresh machine
+  // with no credentials; the bodies carry no secrets (dossier §23.1).
+  if (installExactPaths.has(path) || isInstallRedirectPath(path)) {
+    return true;
+  }
+  if (settings.authAllowHealth && path === "/healthz") {
+    return true;
+  }
+  if (settings.authAllowMetrics && path === "/metrics") {
+    return true;
+  }
+  return false;
+}
+
+function isAuthorized(c: Context, expected: string | undefined): boolean {
+  if (!expected) {
+    return false;
+  }
+  const explicit = c.req.header("x-opengeni-access-key");
+  return constantTimeEqual(explicit, expected);
+}
+
+function constantTimeEqual(actual: string | undefined, expected: string): boolean {
+  if (typeof actual !== "string") {
+    return false;
+  }
+  const actualBytes = new TextEncoder().encode(actual);
+  const expectedBytes = new TextEncoder().encode(expected);
+  if (actualBytes.length !== expectedBytes.length) {
+    return false;
+  }
+  let diff = 0;
+  for (let index = 0; index < actualBytes.length; index += 1) {
+    diff |= actualBytes[index]! ^ expectedBytes[index]!;
+  }
+  return diff === 0;
+}

package/src/http/common.ts

@@ -0,0 +1,16 @@
+import { getSession, type Database } from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+
+export function boundedLimit(raw: string | undefined): number {
+  const limit = Number(raw ?? 100);
+  if (!Number.isFinite(limit)) {
+    return 100;
+  }
+  return Math.min(500, Math.max(1, Math.floor(limit)));
+}
+
+export async function assertSessionExists(db: Database, workspaceId: string, sessionId: string): Promise<void> {
+  if (!await getSession(db, workspaceId, sessionId)) {
+    throw new HTTPException(404, { message: "session not found" });
+  }
+}

package/src/http/sse.ts

@@ -0,0 +1,89 @@
+import type { SessionEvent } from "@opengeni/contracts";
+import { listSessionEvents, type Database } from "@opengeni/db";
+import { formatSse, type EventBus } from "@opengeni/events";
+
+export async function sseSessionStream(db: Database, bus: EventBus, workspaceId: string, sessionId: string, after: number, signal: AbortSignal): Promise<Response> {
+  const encoder = new TextEncoder();
+  let controller: ReadableStreamDefaultController<Uint8Array>;
+  let lastSent = after;
+  let replaying = true;
+  const buffered: SessionEvent[] = [];
+  let unsubscribe: (() => void) | null = null;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start: async (rawController) => {
+      controller = rawController;
+      const send = async (event: SessionEvent) => {
+        if (event.sequence <= lastSent) {
+          return;
+        }
+        if (event.sequence > lastSent + 1) {
+          const missing = await listSessionEvents(db, workspaceId, sessionId, lastSent, event.sequence - lastSent - 1);
+          for (const missed of missing) {
+            if (missed.sequence > lastSent) {
+              controller.enqueue(encoder.encode(formatSse(missed)));
+              lastSent = missed.sequence;
+            }
+          }
+        }
+        controller.enqueue(encoder.encode(formatSse(event)));
+        lastSent = event.sequence;
+      };
+
+      unsubscribe = await bus.subscribe(workspaceId, sessionId, async (events) => {
+        if (replaying) {
+          buffered.push(...events);
+          return;
+        }
+        for (const event of events.sort((a, b) => a.sequence - b.sequence)) {
+          await send(event);
+        }
+      });
+
+      await replaySessionEvents((cursor, limit) => listSessionEvents(db, workspaceId, sessionId, cursor, limit), send, after);
+      replaying = false;
+      for (const event of buffered.sort((a, b) => a.sequence - b.sequence)) {
+        await send(event);
+      }
+      buffered.length = 0;
+      controller.enqueue(encoder.encode(": connected\n\n"));
+    },
+    cancel: () => {
+      unsubscribe?.();
+    },
+  });
+
+  signal.addEventListener("abort", () => {
+    unsubscribe?.();
+  }, { once: true });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+    },
+  });
+}
+
+export async function replaySessionEvents(
+  loadPage: (after: number, limit: number) => Promise<SessionEvent[]>,
+  send: (event: SessionEvent) => Promise<void>,
+  after: number,
+  pageSize = 1000,
+): Promise<void> {
+  let cursor = after;
+  while (true) {
+    const page = await loadPage(cursor, pageSize);
+    if (page.length === 0) {
+      return;
+    }
+    for (const event of page.sort((a, b) => a.sequence - b.sequence)) {
+      await send(event);
+      cursor = Math.max(cursor, event.sequence);
+    }
+    if (page.length < pageSize) {
+      return;
+    }
+  }
+}