@opengeni/api-router 2.1.0-canary.0 → 2.3.2-canary.0

package/src/auth/managed-email.ts

@@ -0,0 +1,174 @@
+import type { Settings } from "@opengeni/config";
+import type {
+  ManagedEmailDeliveryResult,
+  ManagedEmailMessage,
+  ManagedEmailTransport,
+} from "@opengeni/core";
+import { createHmac } from "node:crypto";
+import { Resend } from "resend";
+
+const CAPTURE_MAX_MESSAGES = 250;
+const CAPTURE_TTL_MS = 15 * 60 * 1000;
+
+export type CapturedManagedEmail = ManagedEmailMessage & {
+  capturedAt: string;
+};
+
+/**
+ * Process-local test/development transport. Captures are count/TTL bounded and
+ * one-time readable; there is deliberately no route, disk, database, or log
+ * projection for message bodies or setup bearers.
+ */
+export class InMemoryManagedEmailTransport implements ManagedEmailTransport {
+  private readonly messages: CapturedManagedEmail[] = [];
+  readonly sender: string;
+  readonly idempotency: ManagedEmailTransport["idempotency"];
+
+  constructor(
+    private readonly options: {
+      maxMessages?: number;
+      ttlMs?: number;
+      now?: () => number;
+      sender?: string;
+      idempotency?: ManagedEmailTransport["idempotency"];
+    } = {},
+  ) {
+    this.sender = options.sender ?? "OpenGeni <auth@mail.opengeni.ai>";
+    this.idempotency = options.idempotency ?? {
+      scope: "opengeni-in-memory-v1",
+      retentionSeconds: 86_400,
+    };
+  }
+
+  async send(message: ManagedEmailMessage): Promise<ManagedEmailDeliveryResult> {
+    this.prune();
+    const maxMessages = this.options.maxMessages ?? CAPTURE_MAX_MESSAGES;
+    if (this.messages.length >= maxMessages) this.messages.splice(0, 1);
+    this.messages.push({
+      ...message,
+      capturedAt: new Date(this.now()).toISOString(),
+    });
+    return { status: "sent", providerMessageId: null };
+  }
+
+  take(predicate: (message: CapturedManagedEmail) => boolean): CapturedManagedEmail | null {
+    this.prune();
+    const index = this.messages.findIndex(predicate);
+    if (index < 0) return null;
+    return this.messages.splice(index, 1)[0] ?? null;
+  }
+
+  size(): number {
+    this.prune();
+    return this.messages.length;
+  }
+
+  private prune(): void {
+    const cutoff = this.now() - (this.options.ttlMs ?? CAPTURE_TTL_MS);
+    while (this.messages[0] && Date.parse(this.messages[0].capturedAt) <= cutoff) {
+      this.messages.shift();
+    }
+  }
+
+  private now(): number {
+    return this.options.now?.() ?? Date.now();
+  }
+}
+
+class UnconfiguredManagedEmailTransport implements ManagedEmailTransport {
+  readonly idempotency = {
+    scope: "opengeni-unconfigured-v1",
+    retentionSeconds: 0,
+  } as const;
+
+  constructor(readonly sender: string) {}
+
+  async send(): Promise<ManagedEmailDeliveryResult> {
+    return { status: "failed", errorClass: "provider_not_configured" };
+  }
+}
+
+class ResendManagedEmailTransport implements ManagedEmailTransport {
+  private readonly client: Resend;
+  readonly idempotency: ManagedEmailTransport["idempotency"];
+
+  constructor(
+    apiKey: string,
+    readonly sender: string,
+    scopeSecret: string,
+  ) {
+    this.client = new Resend(apiKey);
+    this.idempotency = {
+      // The keyed digest binds this delivery to the Resend account without
+      // persisting an API-key derivative that can be tested offline.
+      scope: `resend-v1-24h:${createHmac("sha256", scopeSecret).update(apiKey).digest("hex")}`,
+      retentionSeconds: 86_400,
+    };
+  }
+
+  async send(message: ManagedEmailMessage): Promise<ManagedEmailDeliveryResult> {
+    if (message.from !== this.sender) {
+      return { status: "failed", errorClass: "sender_changed" };
+    }
+    try {
+      const result = await this.client.emails.send(
+        {
+          from: message.from,
+          to: message.to,
+          subject: message.subject,
+          text: message.text,
+          html: message.html,
+        },
+        message.idempotencyKey ? { idempotencyKey: message.idempotencyKey } : undefined,
+      );
+      if (!result.error) {
+        return { status: "sent", providerMessageId: result.data?.id ?? null };
+      }
+      const statusCode = "statusCode" in result.error ? Number(result.error.statusCode) : NaN;
+      return clearProviderRefusal(statusCode)
+        ? { status: "failed", errorClass: boundedErrorClass(result.error.name, "provider_refused") }
+        : {
+            status: "outcome_unknown",
+            errorClass: boundedErrorClass(result.error.name, "provider_ambiguous"),
+          };
+    } catch (error) {
+      return {
+        status: "outcome_unknown",
+        errorClass: boundedErrorClass(
+          error instanceof Error ? error.name : "transport_error",
+          "transport_error",
+        ),
+      };
+    }
+  }
+}
+
+export function createManagedEmailTransport(settings: Settings): ManagedEmailTransport {
+  if (settings.resendApiKey) {
+    if (!settings.betterAuthSecret) {
+      throw new Error("OPENGENI_BETTER_AUTH_SECRET is required for managed email delivery");
+    }
+    return new ResendManagedEmailTransport(
+      settings.resendApiKey,
+      settings.emailFrom,
+      settings.betterAuthSecret,
+    );
+  }
+  if (settings.environment === "local" || settings.environment === "test") {
+    return new InMemoryManagedEmailTransport({ sender: settings.emailFrom });
+  }
+  return new UnconfiguredManagedEmailTransport(settings.emailFrom);
+}
+
+function clearProviderRefusal(statusCode: number): boolean {
+  return statusCode >= 400 && statusCode < 500 && ![408, 409, 425, 429].includes(statusCode);
+}
+
+function boundedErrorClass(value: string, fallback: string): string {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9_-]+/g, "_")
+    .slice(0, 64);
+  return normalized || fallback;
+}

package/src/auth/organization-user-setup.ts

@@ -0,0 +1,217 @@
+import type { Settings } from "@opengeni/config";
+import type { ManagedEmailTransport } from "@opengeni/core";
+
+const encoder = new TextEncoder();
+
+/**
+ * Prove that the stable invited-user setup bearer can be constructed before an
+ * invitation commits. Provider availability is intentionally outside this
+ * precondition: the durable delivery journal records a failed or ambiguous
+ * transport outcome after the invitation exists.
+ */
+export function assertOrganizationUserSetupDeliveryConfigured(
+  settings: Settings,
+  transport: ManagedEmailTransport,
+): void {
+  requiredSetupSecret(settings);
+  requiredPublicBaseUrl(settings);
+  assertManagedEmailTransportMetadata(transport);
+}
+
+/** Reject an invalid embedded-provider contract before any durable boundary. */
+export function assertManagedEmailTransportMetadata(transport: ManagedEmailTransport): void {
+  if (
+    transport.sender.trim() !== transport.sender ||
+    encoder.encode(transport.sender).byteLength < 3 ||
+    encoder.encode(transport.sender).byteLength > 320
+  ) {
+    throw new Error("Managed email sender is invalid");
+  }
+  const { scope, retentionSeconds } = transport.idempotency;
+  if (
+    scope.trim() !== scope ||
+    !/^[a-z0-9][a-z0-9:._-]*$/.test(scope) ||
+    encoder.encode(scope).byteLength > 200 ||
+    !Number.isInteger(retentionSeconds) ||
+    retentionSeconds < 0 ||
+    retentionSeconds > 31_536_000
+  ) {
+    throw new Error("Managed email idempotency contract is invalid");
+  }
+}
+
+export async function deriveOrganizationUserSetupToken(
+  settings: Settings,
+  input: { invitationId: string; deliveryId: string },
+): Promise<{ token: string; digest: string; url: string }> {
+  const secret = requiredSetupSecret(settings);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(
+      `opengeni:organization-user-setup-delivery:v1:${input.deliveryId}:${input.invitationId}`,
+    ),
+  );
+  const token = base64Url(new Uint8Array(signature));
+  const digest = await sha256Hex(token);
+  const url = new URL("/setup-account", requiredPublicBaseUrl(settings));
+  url.hash = new URLSearchParams({ token }).toString();
+  return { token, digest, url: url.toString() };
+}
+
+export type OrganizationUserSetupEmailSnapshot = {
+  senderEmail: string;
+  recipientEmail: string;
+  recipientName: string | null;
+  organizationName: string;
+  organizationRole: "owner" | "admin" | "member";
+  sharedWorkspaceAccess: Array<{
+    workspaceId: string;
+    workspaceName: string;
+    role: "viewer" | "member" | "admin";
+  }>;
+  setupUrl: string;
+};
+
+export function renderOrganizationUserSetupEmail(input: OrganizationUserSetupEmailSnapshot): {
+  from: string;
+  to: string;
+  subject: string;
+  text: string;
+  html: string;
+} {
+  const greeting = input.recipientName ? `Hi ${input.recipientName},` : "Hello,";
+  const role = titleCase(input.organizationRole);
+  const workspaceSummary =
+    input.sharedWorkspaceAccess.length === 0
+      ? "No shared workspaces are assigned yet."
+      : `Shared workspace access:\n${input.sharedWorkspaceAccess
+          .map((workspace) => `- ${workspace.workspaceName}: ${titleCase(workspace.role)}`)
+          .join("\n")}`;
+  const workspaceHtml =
+    input.sharedWorkspaceAccess.length === 0
+      ? "<p>No shared workspaces are assigned yet.</p>"
+      : `<p>Shared workspace access:</p><ul>${input.sharedWorkspaceAccess
+          .map(
+            (workspace) =>
+              `<li>${escapeHtml(workspace.workspaceName)}: ${escapeHtml(titleCase(workspace.role))}</li>`,
+          )
+          .join("")}</ul>`;
+  return {
+    from: input.senderEmail,
+    to: input.recipientEmail,
+    subject: `Join ${input.organizationName} on OpenGeni`,
+    text: `${greeting}\n\nYou have been invited to ${input.organizationName} as ${role}.\n\n${workspaceSummary}\n\nThis invitation grants only the organization role and shared workspace access listed above. It never shares anyone's Personal workspace.\n\nSet up your account: ${input.setupUrl}\n\nIf you already have an OpenGeni account, sign in and accept the invitation instead.`,
+    html: `<p>${escapeHtml(greeting)}</p><p>You have been invited to <strong>${escapeHtml(input.organizationName)}</strong> as ${escapeHtml(role)}.</p>${workspaceHtml}<p>This invitation grants only the organization role and shared workspace access listed above. It never shares anyone's Personal workspace.</p><p><a href="${escapeHtml(input.setupUrl)}">Set up your account</a></p><p>If you already have an OpenGeni account, sign in and accept the invitation instead.</p>`,
+  };
+}
+
+export async function organizationUserSetupPayloadDigest(input: {
+  from: string;
+  to: string;
+  subject: string;
+  text: string;
+  html: string;
+  providerIdempotencyScope: string;
+}): Promise<string> {
+  return await sha256Hex(
+    JSON.stringify({
+      version: 2,
+      providerIdempotencyScope: input.providerIdempotencyScope,
+      from: input.from,
+      to: input.to,
+      subject: input.subject,
+      text: input.text,
+      html: input.html,
+    }),
+  );
+}
+
+export async function organizationUserSetupRequestFingerprint(
+  settings: Settings,
+  input: { tokenDigest: string; name: string; password: string },
+): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(requiredSetupSecret(settings)),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(
+      JSON.stringify({
+        tokenDigest: input.tokenDigest,
+        name: input.name,
+        password: input.password,
+      }),
+    ),
+  );
+  return hex(new Uint8Array(signature));
+}
+
+export async function selfServiceOrganizationSetupRequestFingerprint(input: {
+  authUserId: string;
+  organizationName: string;
+}): Promise<string> {
+  const actorSubjectId = `user:${input.authUserId}`;
+  const organizationNameBytes = encoder.encode(input.organizationName);
+  return await sha256Hex(
+    `opengeni:self-service-organization:v1:${actorSubjectId}:${organizationNameBytes.byteLength}:${input.organizationName}`,
+  );
+}
+
+export async function organizationUserSetupTokenDigest(token: string): Promise<string> {
+  return await sha256Hex(token);
+}
+
+function requiredSetupSecret(settings: Settings): string {
+  if (!settings.betterAuthSecret) {
+    throw new Error("OPENGENI_BETTER_AUTH_SECRET is required for organization user setup");
+  }
+  return settings.betterAuthSecret;
+}
+
+function requiredPublicBaseUrl(settings: Settings): string {
+  if (!settings.publicBaseUrl) {
+    throw new Error("OPENGENI_PUBLIC_BASE_URL is required for organization user setup");
+  }
+  return settings.publicBaseUrl;
+}
+
+async function sha256Hex(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", encoder.encode(value));
+  return hex(new Uint8Array(digest));
+}
+
+function hex(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function base64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+
+function titleCase(value: string): string {
+  return `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#039;");
+}

package/src/http/auth.ts

@@ -5,6 +5,8 @@ import { installExactPaths, isInstallRedirectPath } from "../routes/install";
 
 const githubConnectPathPattern = /^\/v1\/workspaces\/[^/]+\/github\/connect$/;
 const githubInstallationLinkPathPattern = /^\/v1\/workspaces\/[^/]+\/github\/installations$/;
+const prReviewGithubBrowserPathPattern =
+  /^\/v1\/workspaces\/[^/]+\/pr-review\/github\/(?:connect|installations\/select|installations\/[^/]+\/configure)$/;
 
 export function requireAccessKey(settings: Settings): MiddlewareHandler {
   return async (c, next) => {
@@ -43,6 +45,9 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (c.req.method === "POST" && path.startsWith("/v1/webhooks/automations/")) {
     return true;
   }
+  if (c.req.method === "POST" && path === "/v1/webhooks/pr-review/github") {
+    return true;
+  }
   if (
     path === "/v1/github/setup" ||
     path === "/v1/github/install/callback" ||
@@ -51,6 +56,13 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   ) {
     return true;
   }
+  if (
+    path === "/v1/pr-review/github/setup" ||
+    path === "/v1/pr-review/github/install/callback" ||
+    path === "/v1/pr-review/github/oauth/callback"
+  ) {
+    return true;
+  }
   if (
     path === "/v1/integrations/oauth/callback" ||
     path === "/v1/integrations/provider-oauth/callback" ||
@@ -83,6 +95,9 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (githubConnectPathPattern.test(path)) {
     return true;
   }
+  if (prReviewGithubBrowserPathPattern.test(path)) {
+    return true;
+  }
   // Compatibility endpoint for stale chooser submissions. It remains public
   // only so already-rendered forms can authenticate their signed account and
   // workspace state locally before terminating with 410; it does not parse a

package/src/http/sse.ts

@@ -13,6 +13,7 @@ import {
   coalesceSessionEventDeltas,
   formatSessionEventSse,
   formatWorkspaceControlEventSse,
+  requireSessionEventDurableFanoutCapability,
   SESSION_EVENT_SSE_FRAME_MAX_BYTES,
   sessionEventResumeSequence,
   type EventBus,
@@ -269,12 +270,14 @@ export async function sseSessionStream(
   signal: AbortSignal,
   options: SessionSseDeliveryOptions = {},
 ): Promise<Response> {
+  const durableFanout = requireSessionEventDurableFanoutCapability(bus);
   const heartbeatIntervalMs = resolveHeartbeatInterval(options.heartbeatIntervalMs);
   let lastSent = after;
   let bootstrapping = true;
   let newestBuffered: SessionEvent | null = null;
   let unsubscribe: (() => void) | null = null;
   let delivery: LatestWinsDelivery<SessionEvent> | null = null;
+  let stopReconnectObservation = () => {};
   let stopReauthorization = () => {};
   let heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
   let detachAbortListener = () => {};
@@ -282,6 +285,8 @@ export async function sseSessionStream(
   const stopUpstream = () => {
     closeMetrics();
     detachAbortListener();
+    stopReconnectObservation();
+    stopReconnectObservation = () => {};
     stopReauthorization();
     if (heartbeatTimer) {
       clearTimeout(heartbeatTimer);
@@ -316,17 +321,6 @@ export async function sseSessionStream(
     writeTail = write.catch(() => {});
     return write;
   };
-  const scheduleHeartbeat = () => {
-    if (channel.stopped()) return;
-    heartbeatTimer = setTimeout(() => {
-      heartbeatTimer = null;
-      void writeFrame(": heartbeat\n\n")
-        .then(scheduleHeartbeat)
-        .catch((error) => {
-          if (!(error instanceof SseStreamStoppedError)) fail(error);
-        });
-    }, heartbeatIntervalMs);
-  };
   const deliverDurableThrough = async (targetSequence?: number) => {
     while (true) {
       if (targetSequence !== undefined && lastSent >= targetSequence) return;
@@ -364,12 +358,66 @@ export async function sseSessionStream(
       if (targetSequence === undefined && page.length < limit) return;
     }
   };
+  let durableDeliveryTail = Promise.resolve();
+  const reconcileDurableThrough = (targetSequence?: number): Promise<void> => {
+    const deliveryRun = durableDeliveryTail.then(() => deliverDurableThrough(targetSequence));
+    durableDeliveryTail = deliveryRun.catch(() => {});
+    return deliveryRun;
+  };
+  let newestReconnectGeneration = 0;
+  let reconnectReconcilePending = false;
+  let reconnectReconcileRunning = false;
+  const drainReconnectReconciliation = () => {
+    if (
+      bootstrapping ||
+      reconnectReconcileRunning ||
+      !reconnectReconcilePending ||
+      channel.stopped()
+    ) {
+      return;
+    }
+    reconnectReconcileRunning = true;
+    void (async () => {
+      while (reconnectReconcilePending && !channel.stopped()) {
+        // Multiple reconnects during one durable read collapse into one newest
+        // catch-up. Postgres is authoritative, so that later read covers every
+        // disconnect window without one query per heartbeat or buffered event.
+        reconnectReconcilePending = false;
+        await reconcileDurableThrough();
+      }
+    })()
+      .catch((error) => {
+        if (!(error instanceof SseStreamStoppedError)) fail(error);
+      })
+      .finally(() => {
+        reconnectReconcileRunning = false;
+        drainReconnectReconciliation();
+      });
+  };
+  const scheduleReconnectReconciliation = (generation: number) => {
+    if (generation <= newestReconnectGeneration || channel.stopped()) return;
+    newestReconnectGeneration = generation;
+    reconnectReconcilePending = true;
+    drainReconnectReconciliation();
+  };
   const send = async (event: SessionEvent) => {
     const targetSequence = sessionEventResumeSequence(event);
     if (targetSequence <= lastSent) return;
-    await deliverDurableThrough(targetSequence);
+    await reconcileDurableThrough(targetSequence);
+  };
+  const scheduleHeartbeat = () => {
+    if (channel.stopped()) return;
+    heartbeatTimer = setTimeout(() => {
+      heartbeatTimer = null;
+      void writeFrame(": heartbeat\n\n")
+        .then(scheduleHeartbeat)
+        .catch((error) => {
+          if (!(error instanceof SseStreamStoppedError)) fail(error);
+        });
+    }, heartbeatIntervalMs);
   };
   delivery = createLatestWinsDelivery(send, fail);
+  stopReconnectObservation = durableFanout.subscribeRecovery(scheduleReconnectReconciliation);
 
   void (async () => {
     const release = await bus.subscribe(workspaceId, sessionId, (events) => {
@@ -389,10 +437,11 @@ export async function sseSessionStream(
     }
     unsubscribe = release;
 
-    await deliverDurableThrough();
+    await reconcileDurableThrough();
     await writeFrame(": connected\n\n");
     scheduleHeartbeat();
     bootstrapping = false;
+    drainReconnectReconciliation();
     const buffered = newestBuffered;
     newestBuffered = null;
     if (buffered) delivery.publish([buffered]);

package/src/integrations/slack-app-home.ts

@@ -1,4 +1,4 @@
-import type { Session } from "@opengeni/contracts";
+import { AUTOMATIC_SESSION_TITLE_FALLBACK, type Session } from "@opengeni/contracts";
 import type { SlackHomeBlock } from "./slack-bot";
 
 const ATTENTION_LIMIT = 5;
@@ -186,7 +186,7 @@ function appendSessionGroup(
   );
   for (const session of sessions) {
     const url = sessionUrl(session.id);
-    const title = (session.title || session.initialMessage || "Untitled task").slice(0, 180);
+    const title = (session.title?.trim() || AUTOMATIC_SESSION_TITLE_FALLBACK).slice(0, 180);
     blocks.push({
       type: "section",
       block_id: `opengeni_home_session_${session.id}`,

package/src/integrations/slack-bot.ts

@@ -207,6 +207,11 @@ export type SlackMessageBlock =
         style?: "primary" | "danger";
       }>;
     }
+  | {
+      type: "context";
+      block_id?: string;
+      elements: Array<{ type: "mrkdwn" | "plain_text"; text: string; emoji?: boolean }>;
+    }
   | { type: "divider" };
 
 export type SlackHomeBlock =