@opengeni/api-router 2.2.0-canary.0 → 2.3.2-canary.1

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   createOpenGeniSlackBotInteractionClient,
   startSlackInteractionPump,
   startTemporalScheduleCleanupPump
-} from "./chunk-3TP54PPX.js";
+} from "./chunk-IBV7Z6F4.js";
 
 // src/index.ts
 import {

package/dist/integrations/slack-app-home.d.ts

@@ -1,4 +1,4 @@
-import type { Session } from "@opengeni/contracts";
+import { type Session } from "@opengeni/contracts";
 import type { SlackHomeBlock } from "./slack-bot.js";
 export type SlackAppHomeOpenedEvent = {
     eventId: string;

package/dist/mcp/server.d.ts

@@ -95,7 +95,7 @@ export declare function capSessionDiscoveryPage(page: Awaited<ReturnType<typeof
             truncated: boolean;
         };
         latestMessage?: {
-            type: "agent.message.completed" | "agent.message.delta" | "agent.model.request" | "agent.model.usage" | "agent.reasoning.delta" | "agent.toolCall.created" | "agent.toolCall.output" | "agent.updated" | "artifact.created" | "codex.account.switched" | "codex.capacity.resumed" | "codex.capacity.superseded" | "codex.capacity.waiting" | "codex.credential.selected" | "codex.fleet.decision" | "credential.auth_needed" | "fs.changed" | "git.changed" | "goal.cleared" | "goal.completed" | "goal.continuation" | "goal.held" | "goal.paused" | "goal.progress" | "goal.resumed" | "goal.rewrite.proposed" | "goal.rewrite.rejected" | "goal.set" | "goal.updated" | "machine.link.lost" | "machine.link.restored" | "machine.op.failed" | "machine.op.recovered" | "machine.runner.restarted" | "memory.corrected" | "memory.saved" | "recording.available" | "recording.failed" | "recording.started" | "rig.setup.completed" | "rig.setup.failed" | "rig.setup.skipped" | "rig.setup.started" | "sandbox.box.created" | "sandbox.box.lost" | "sandbox.box.snapshot" | "sandbox.box.terminated" | "sandbox.command.output.delta" | "sandbox.env.drift" | "sandbox.operation.completed" | "sandbox.operation.failed" | "sandbox.operation.started" | "session.command.backgrounded" | "session.command.finished" | "session.context.cleared" | "session.context.compacted" | "session.context.compaction.requested" | "session.context.compaction.skipped" | "session.context.compaction.started" | "session.control.paused" | "session.control.resumed" | "session.control.steer_requested" | "session.created" | "session.event.envelope_omitted" | "session.humanInput.requested" | "session.mcp.approval_policy.updated" | "session.personal_resources.attached" | "session.queue.changed" | "session.queue.history" | "session.queue.prompt.cancelled" | "session.realtime.ended" | "session.realtime.started" | "session.requiresAction" | "session.route.reconciled" | "session.status.changed" | "session.title_set" | "session.tool_policy.updated" | "session.visibility.changed" | "stream.closed" | "stream.opened" | "stream.revoked" | "stream.url.rotated" | "system.update.cancelled" | "system.update.delivered" | "system.update.pending" | "system.update.settled" | "system.update.superseded" | "terminal.pty.exited" | "terminal.pty.output.delta" | "terminal.pty.started" | "tool.auth_needed" | "turn.cancelled" | "turn.capacity_waiting" | "turn.completed" | "turn.event.rejected_late" | "turn.failed" | "turn.queued" | "turn.recovery.requested" | "turn.started" | "turn.startup.phase.completed" | "turn.startup.phase.failed" | "turn.startup.phase.started" | "turn.superseded" | "user.approvalDecision" | "user.humanInputResponse" | "user.message" | "user.pause" | "workspace.inference.paused" | "workspace.inference.resumed" | "workspace.revision.captured" | "workspace.revision.degraded";
+            type: "agent.message.completed" | "agent.message.delta" | "agent.model.request" | "agent.model.usage" | "agent.reasoning.delta" | "agent.toolCall.created" | "agent.toolCall.output" | "agent.updated" | "artifact.created" | "codex.account.switched" | "codex.capacity.resumed" | "codex.capacity.superseded" | "codex.capacity.waiting" | "codex.credential.selected" | "codex.fleet.decision" | "credential.auth_needed" | "fs.changed" | "git.changed" | "goal.cleared" | "goal.completed" | "goal.continuation" | "goal.held" | "goal.paused" | "goal.progress" | "goal.resumed" | "goal.rewrite.proposed" | "goal.rewrite.rejected" | "goal.set" | "goal.updated" | "machine.link.lost" | "machine.link.restored" | "machine.op.failed" | "machine.op.recovered" | "machine.runner.restarted" | "memory.corrected" | "memory.saved" | "recording.available" | "recording.failed" | "recording.started" | "rig.setup.completed" | "rig.setup.failed" | "rig.setup.skipped" | "rig.setup.started" | "sandbox.box.created" | "sandbox.box.lost" | "sandbox.box.snapshot" | "sandbox.box.terminated" | "sandbox.command.output.delta" | "sandbox.env.drift" | "sandbox.operation.completed" | "sandbox.operation.failed" | "sandbox.operation.started" | "session.command.backgrounded" | "session.command.finished" | "session.context.cleared" | "session.context.compacted" | "session.context.compaction.requested" | "session.context.compaction.skipped" | "session.context.compaction.started" | "session.control.paused" | "session.control.resumed" | "session.control.steer_requested" | "session.created" | "session.event.envelope_omitted" | "session.humanInput.requested" | "session.mcp.approval_policy.updated" | "session.personal_resources.attached" | "session.queue.changed" | "session.queue.history" | "session.queue.prompt.cancelled" | "session.realtime.ended" | "session.realtime.started" | "session.requiresAction" | "session.route.reconciled" | "session.runtime.configured" | "session.status.changed" | "session.title_set" | "session.tool_policy.updated" | "session.variable_sets.updated" | "session.visibility.changed" | "stream.closed" | "stream.opened" | "stream.revoked" | "stream.url.rotated" | "system.update.cancelled" | "system.update.delivered" | "system.update.pending" | "system.update.settled" | "system.update.superseded" | "terminal.pty.exited" | "terminal.pty.output.delta" | "terminal.pty.started" | "tool.auth_needed" | "turn.cancelled" | "turn.capacity_waiting" | "turn.completed" | "turn.event.rejected_late" | "turn.failed" | "turn.queued" | "turn.recovery.requested" | "turn.started" | "turn.startup.phase.completed" | "turn.startup.phase.failed" | "turn.startup.phase.started" | "turn.superseded" | "user.approvalDecision" | "user.humanInputResponse" | "user.message" | "user.pause" | "workspace.inference.paused" | "workspace.inference.resumed" | "workspace.revision.captured" | "workspace.revision.degraded";
             preview: string | null;
             previewTruncated: boolean;
         } | null;

package/dist/mcp/session-view.d.ts

@@ -88,6 +88,7 @@ export declare function boundSessionDetailMcp(session: Session, effectiveControl
     sandboxGroupId: string;
     activeSandboxId: string | null;
     activeEpoch: number;
+    variableSetIds: string[];
     variableSetId: string | null;
     environmentId: string | null;
     rigId: string | null;

package/dist/routes/automations.d.ts

@@ -1,4 +1,17 @@
+import { AutomationNormalizedEvent } from "@opengeni/contracts";
+import { type AutomationSourceSecret } from "@opengeni/db";
 import { type ApiRouteDeps } from "@opengeni/core";
 import type { Hono } from "hono";
 export declare function registerAutomationRoutes(app: Hono, deps: ApiRouteDeps): void;
+export declare function acceptAutomationEvent(deps: ApiRouteDeps, source: AutomationSourceSecret, input: {
+    deliveryKey: string;
+    requestDigest: string;
+    normalizedEvent: AutomationNormalizedEvent;
+}): Promise<{
+    accepted: boolean;
+    duplicate: boolean;
+    ignoredReason: string | null;
+    eventId: string | null;
+    runIds: string[];
+}>;
 export declare function readAutomationWebhookBody(request: Request, maxBytes: number): Promise<Uint8Array>;

package/dist/routes/insights.d.ts

@@ -1,3 +1,4 @@
-import { type ApiRouteDeps } from "@opengeni/core";
+import { type ApiRouteDeps, type WorkspaceInsightsFilterField } from "@opengeni/core";
 import type { Hono } from "hono";
+export declare function normalizeWorkspaceInsightsQueryFilter(value: string | null | undefined, field: WorkspaceInsightsFilterField): string | null;
 export declare function registerInsightsRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/routes/managed-onboarding.d.ts

@@ -0,0 +1,29 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+export type ManagedOnboardingRouteOptions = {
+    accountSetupLimiter?: {
+        take(key: string): boolean;
+    };
+    hashPassword?: (password: string) => Promise<string>;
+};
+export declare function registerManagedOnboardingRoutes(app: Hono, deps: ApiRouteDeps, options?: ManagedOnboardingRouteOptions): void;
+/**
+ * Bounded application-tier protection for the public setup bearer endpoint.
+ * The global bucket prevents spoofed/high-cardinality client keys from
+ * multiplying password-hash work, while the per-client bucket limits bursts.
+ * A full key map rejects new clients until an idle bucket can be pruned.
+ */
+export declare class PublicSetupRateLimiter {
+    private readonly options;
+    private readonly buckets;
+    private global;
+    constructor(options?: {
+        globalCapacity?: number;
+        globalRefillPerSecond?: number;
+        clientCapacity?: number;
+        clientRefillPerSecond?: number;
+        maxClientKeys?: number;
+        now?: () => number;
+    });
+    take(key: string): boolean;
+}

package/dist/routes/pr-review-github.d.ts

@@ -0,0 +1,3 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+export declare function registerPrReviewGitHubRoutes(app: Hono, deps: ApiRouteDeps): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "2.2.0-canary.0",
+  "version": "2.3.2-canary.1",
   "description": "OpenGeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -43,23 +43,23 @@
     "@hono/zod-validator": "^0.7.6",
     "@llamaindex/liteparse": "^1.5.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/agent-proto": "^0.5.1-canary.1",
-    "@opengeni/artifact-tool": "^0.3.5-canary.0",
-    "@opengeni/capabilities": "^0.3.1-canary.0",
-    "@opengeni/codemode": "^0.4.13-canary.0",
-    "@opengeni/codex": "^0.2.19-canary.0",
-    "@opengeni/config": "^0.19.1-canary.0",
-    "@opengeni/contracts": "^2.3.0-canary.0",
-    "@opengeni/core": "^2.2.0-canary.0",
-    "@opengeni/db": "^3.2.0-canary.0",
-    "@opengeni/documents": "^0.7.0-canary.0",
-    "@opengeni/events": "^0.3.124-canary.0",
-    "@opengeni/github": "^0.5.3-canary.0",
-    "@opengeni/network": "^0.2.3-canary.0",
-    "@opengeni/observability": "^0.8.4-canary.0",
-    "@opengeni/runtime": "^1.3.1-canary.0",
-    "@opengeni/storage": "^0.2.106-canary.0",
-    "@opengeni/xai-subscription": "^0.1.2-canary.0",
+    "@opengeni/agent-proto": "^0.5.1-canary.3",
+    "@opengeni/artifact-tool": "^0.3.7-canary.1",
+    "@opengeni/capabilities": "^0.3.1-canary.2",
+    "@opengeni/codemode": "^0.4.15-canary.1",
+    "@opengeni/codex": "^0.2.19-canary.2",
+    "@opengeni/config": "^0.20.1-canary.1",
+    "@opengeni/contracts": "^2.5.0-canary.1",
+    "@opengeni/core": "^2.4.0-canary.1",
+    "@opengeni/db": "^3.4.0-canary.1",
+    "@opengeni/documents": "^0.8.2-canary.1",
+    "@opengeni/events": "^0.4.0-canary.1",
+    "@opengeni/github": "^0.5.5-canary.1",
+    "@opengeni/network": "^0.2.3-canary.2",
+    "@opengeni/observability": "^0.8.6-canary.1",
+    "@opengeni/runtime": "^1.4.0-canary.1",
+    "@opengeni/storage": "^0.2.108-canary.1",
+    "@opengeni/xai-subscription": "^0.1.2-canary.2",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",

package/src/app.ts

@@ -40,6 +40,7 @@ import {
   rlsContextForWorkspace,
   withSessionRlsActorContext,
 } from "@opengeni/db";
+import { requireSessionEventDurableFanoutCapability } from "@opengeni/events";
 import { createObservability } from "@opengeni/observability";
 import { createObjectStorage } from "@opengeni/storage";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
@@ -63,6 +64,8 @@ import {
   SessionAuthorizationUnavailableError,
 } from "@opengeni/core";
 import { createManagedAuth } from "./auth/managed-auth";
+import { createManagedEmailTransport } from "./auth/managed-email";
+import { assertManagedEmailTransportMetadata } from "./auth/organization-user-setup";
 import { createApiSandboxClient, makeResumeBoxById } from "./sandbox/access";
 import { requireLimit } from "@opengeni/core";
 import { buildOpenGeniMcpServer } from "./mcp/server";
@@ -132,6 +135,7 @@ import { registerEditableArtifactRoutes } from "./routes/editable-artifacts";
 import { registerVideoGenerationRoutes } from "./routes/video-generation";
 import { registerCanonicalHumanIdentityRoutes } from "./routes/canonical-human-identities";
 import { registerOrganizationMembershipRoutes } from "./routes/organization-memberships";
+import { registerManagedOnboardingRoutes } from "./routes/managed-onboarding";
 import { registerUserResourceAuthorityRoutes } from "./routes/user-resource-authorities";
 import { registerConnectionAuthorityRoutes } from "./routes/connection-authorities";
 import { projectClientModel } from "./model-catalog";
@@ -193,7 +197,11 @@ export function createAppComposition(deps: AppDependencies): {
   // Pause) run inside API-originated db commands; install the boot-validated
   // rollout flag once for this process.
   configureChildLifecycleNotices({ enabled: deps.settings.childLifecycleNoticesEnabled });
-  const managedAuth = deps.managedAuth ?? createManagedAuth(deps.settings, deps.db);
+  const managedEmailTransport =
+    deps.managedEmailTransport ?? createManagedEmailTransport(deps.settings);
+  assertManagedEmailTransportMetadata(managedEmailTransport);
+  const managedAuth =
+    deps.managedAuth ?? createManagedAuth(deps.settings, deps.db, managedEmailTransport);
   const objectStorage =
     deps.objectStorage === undefined ? createObjectStorage(deps.settings) : deps.objectStorage;
   let documentServices: DocumentServices | null = deps.documentServices ?? null;
@@ -296,6 +304,7 @@ export function createAppComposition(deps: AppDependencies): {
     githubStateSecret:
       deps.githubStateSecret ?? deps.settings.githubAppManifestStateSecret ?? crypto.randomUUID(),
     managedAuth,
+    managedEmailTransport,
     objectStorage,
     documentIndexer,
     getDocumentServices,
@@ -486,6 +495,9 @@ export function createAppComposition(deps: AppDependencies): {
     await next();
   });
 
+  // These product-owned auth routes must be registered before Better Auth's
+  // wildcard handler or the provider returns its own 404 first.
+  registerManagedOnboardingRoutes(app, routeDeps);
   if (managedAuth) {
     app.on(["GET", "POST"], "/v1/auth/*", (c) => managedAuth.handler(c.req.raw));
   }
@@ -1114,19 +1126,23 @@ type ReadinessChecks = Record<ReadinessCheckName, ReadinessCheck>;
 type ReadinessCheckResult = { ok: boolean; error?: string };
 
 function readinessChecks(deps: AppDependencies): ReadinessChecks {
+  const configuredNatsCheck = deps.readinessChecks?.nats;
   return {
     db:
       deps.readinessChecks?.db ??
       (async () => {
         await deps.db.execute(dbSql`select 1`);
       }),
-    nats:
-      deps.readinessChecks?.nats ??
-      (() => {
+    nats: async () => {
+      requireSessionEventDurableFanoutCapability(deps.bus);
+      if (configuredNatsCheck) {
+        await configuredNatsCheck();
+      } else {
         if (deps.bus.isConnected && !deps.bus.isConnected()) {
           throw new Error("NATS is not connected");
         }
-      }),
+      }
+    },
     temporal:
       deps.readinessChecks?.temporal ??
       deps.workflowClient.check ??
@@ -1637,6 +1653,22 @@ const routeLabelPatterns: Array<{
     pattern: /^\/v1\/workspaces\/[^/]+\/github\/app-manifest$/,
     label: "/v1/workspaces/:workspaceId/github/app-manifest",
   },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/pr-review\/github$/,
+    label: "/v1/workspaces/:workspaceId/pr-review/github",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/pr-review\/github\/connect$/,
+    label: "/v1/workspaces/:workspaceId/pr-review/github/connect",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/pr-review\/github\/installations\/select$/,
+    label: "/v1/workspaces/:workspaceId/pr-review/github/installations/select",
+  },
+  {
+    pattern: /^\/v1\/workspaces\/[^/]+\/pr-review\/github\/installations\/[^/]+\/configure$/,
+    label: "/v1/workspaces/:workspaceId/pr-review/github/installations/:installationId/configure",
+  },
   {
     pattern: /^\/v1\/workspaces\/[^/]+\/capabilities$/,
     label: "/v1/workspaces/:workspaceId/capabilities",
@@ -1929,6 +1961,19 @@ const routeLabelPatterns: Array<{
     pattern: /^\/v1\/github\/oauth\/callback$/,
     label: "/v1/github/oauth/callback",
   },
+  { pattern: /^\/v1\/pr-review\/github\/setup$/, label: "/v1/pr-review/github/setup" },
+  {
+    pattern: /^\/v1\/pr-review\/github\/install\/callback$/,
+    label: "/v1/pr-review/github/install/callback",
+  },
+  {
+    pattern: /^\/v1\/pr-review\/github\/oauth\/callback$/,
+    label: "/v1/pr-review/github/oauth/callback",
+  },
+  {
+    pattern: /^\/v1\/webhooks\/pr-review\/github$/,
+    label: "/v1/webhooks/pr-review/github",
+  },
   {
     pattern: /^\/v1\/workspaces\/[^/]+$/,
     label: "/v1/workspaces/:workspaceId",
@@ -1957,6 +2002,12 @@ export function isApiContractProtectedMutation(method: string, pathname: string)
   if (!pathname.startsWith("/v1/")) {
     return false;
   }
+  if (
+    pathname === "/v1/auth/organization-onboarding" ||
+    pathname === "/v1/auth/organization-setup"
+  ) {
+    return true;
+  }
   if (
     pathname.startsWith("/v1/auth/") ||
     pathname.startsWith("/v1/webhooks/") ||

package/src/auth/managed-auth.ts

@@ -1,5 +1,9 @@
 import type { Settings } from "@opengeni/config";
-import { type ManagedAuth } from "@opengeni/core";
+import {
+  type ManagedAuth,
+  type ManagedEmailMessage,
+  type ManagedEmailTransport,
+} from "@opengeni/core";
 import type { Database } from "@opengeni/db";
 import { ensureManagedAccessForUser } from "@opengeni/db";
 import {
@@ -9,8 +13,8 @@ import {
 } from "@opengeni/db/canonical-human-identities";
 import { betterAuth } from "better-auth";
 import { createEmailVerificationToken } from "better-auth/api";
+import { hashPassword } from "better-auth/crypto";
 import { Pool } from "pg";
-import { Resend } from "resend";
 
 import { decideCanonicalHumanSessionAdmission } from "./canonical-human-session-admission";
 
@@ -34,7 +38,16 @@ export function managedAuthUserCreateOverride(
   return { data: { ...user, emailVerified: true } };
 }
 
-export function createManagedAuth(settings: Settings, db: Database): ManagedAuth | null {
+/** Keep Better Auth password policy and storage format behind this boundary. */
+export async function hashManagedAuthPassword(password: string): Promise<string> {
+  return await hashPassword(password);
+}
+
+export function createManagedAuth(
+  settings: Settings,
+  db: Database,
+  managedEmailTransport: ManagedEmailTransport,
+): ManagedAuth | null {
   if (settings.productAccessMode !== "managed") {
     return null;
   }
@@ -147,7 +160,8 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
       onExistingUserSignUp: async ({ user }) => {
         if (requireEmailVerification && !user.emailVerified) {
           const url = await verificationUrl(settings, user.email);
-          await sendEmail(settings, {
+          await sendManagedAuthEmail(managedEmailTransport, {
+            kind: "email_verification",
             to: user.email,
             subject: "Verify your OpenGeni email",
             text: `Verify your OpenGeni email: ${url}`,
@@ -156,7 +170,8 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
         }
       },
       sendResetPassword: async ({ user, url }) => {
-        await sendEmail(settings, {
+        await sendManagedAuthEmail(managedEmailTransport, {
+          kind: "password_reset",
           to: user.email,
           subject: "Reset your OpenGeni password",
           text: `Reset your OpenGeni password: ${url}`,
@@ -167,7 +182,8 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
     emailVerification: {
       sendOnSignUp: requireEmailVerification,
       sendVerificationEmail: async ({ user, url }) => {
-        await sendEmail(settings, {
+        await sendManagedAuthEmail(managedEmailTransport, {
+          kind: "email_verification",
           to: user.email,
           subject: "Verify your OpenGeni email",
           text: `Verify your OpenGeni email: ${url}`,
@@ -180,6 +196,7 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
           email: user.email,
           name: user.name,
           emailVerified: true,
+          provisionFallbackOrganization: false,
         });
       },
     },
@@ -266,6 +283,7 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
               email: user.email,
               name: user.name,
               emailVerified: true,
+              provisionFallbackOrganization: false,
             });
           },
         },
@@ -297,35 +315,12 @@ function betterAuthTrustedOrigins(settings: Settings): string[] {
   return [...origins];
 }
 
-async function sendEmail(
-  settings: Settings,
-  input: {
-    to: string;
-    subject: string;
-    text: string;
-    html: string;
-  },
+export async function sendManagedAuthEmail(
+  transport: ManagedEmailTransport,
+  input: Omit<ManagedEmailMessage, "from">,
 ): 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);
-  }
+  const result = await transport.send({ ...input, from: transport.sender });
+  if (result.status !== "sent") throw new Error(`managed email ${result.status}`);
 }
 
 async function verificationUrl(settings: Settings, email: string): Promise<string> {

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;
+}