@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/machines.ts

@@ -15,6 +15,9 @@
 //     The downsampled (~1/min) history for ONE machine over a time window.
 
 import {
+  ChangeMachineAudienceRequest,
+  MachineAudiencePreviewRequest,
+  OpenMachinePrivacySettingsRequest,
   MachineMetricsSeriesResponse,
   MachineOperationPolicy,
   MachinesResponse,
@@ -24,18 +27,19 @@ import {
   UpdateMachineAgentResponse,
 } from "@opengeni/contracts";
 import {
-  advanceEnrollmentAgentUpdate,
-  beginEnrollmentAgentUpdate,
+  changeMachineAudience,
   getLiveEnrollmentConnection,
   listEnrollments,
+  previewMachineAudienceChange,
   readMachineMetricsSeries,
   requireSession,
   updateEnrollmentOperationPolicy,
 } from "@opengeni/db";
-import type { Hono } from "hono";
+import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import {
   grantHasAgentAttemptAuthority,
+  mayStartOnlyMe,
   requireAccessGrant,
   requireAccessGrantAuthorization,
   requireSessionAuthorization,
@@ -44,10 +48,23 @@ import {
 } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { buildFleetContextForSession, swapActiveSandbox } from "@opengeni/core";
+import {
+  enableMachineScreenControl,
+  enrollmentAccess,
+  MachineNotActiveError,
+  openMachinePrivacySettings,
+} from "../sandbox/screen-control";
 import { listMachines, metricRowToSample } from "../sandbox/machines";
+import { requestAgentUpdate } from "../sandbox/agent-update";
+import {
+  machineAudienceChangeResponse,
+  machineAudiencePreview,
+  machineAudienceRefusalError,
+  machineAudienceRequestFor,
+} from "../sandbox/machine-audience";
 import { ensureSessionGroupReady as ensureViewerSessionGroupReady } from "../sandbox/viewer";
-import { ControlRequest, ErrorCode } from "@opengeni/agent-proto";
-import { NatsControlRpc, subjectFor } from "@opengeni/runtime/sandbox";
+import { parseRequestJson } from "../http/request-body";
+import { requireFullAccessIfAgent } from "../http/acting-person";
 
 // The supported series windows → milliseconds. An unknown/absent window defaults
 // to 1h (the default). Bounded so a caller cannot request an unbounded
@@ -183,6 +200,164 @@ export function registerMachineRoutes(app: Hono, deps: ApiRouteDeps): void {
     return c.json(MachineOperationPolicy.parse(updated.operationPolicy));
   });
 
+  // ── Who can use a machine: Workspace or Only me, changed in place ──────────
+  // POST .../audience/preview lists what the change would affect with the
+  // caller's choices applied; PUT .../audience applies it in one transaction at
+  // the previewed generation. The enrollment, sandbox ID, credentials and live
+  // connection stay, so chats, schedules and the installed agent keep working.
+  // A person decides this: in the app, through the API, or through an agent
+  // they gave their full access (admin access, a full-access connected agent),
+  // which acts as them. An agent acting as itself, or one with less than the
+  // person's full access, is refused: the change decides who else can use the
+  // machine.
+  async function requireAudienceCaller(c: Context, workspaceId: string) {
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "enrollments:manage",
+    );
+    const grant = authorization.grant;
+    assertSelfhostedEnabled();
+    if (grantHasAgentAttemptAuthority(grant)) {
+      throw new HTTPException(403, {
+        message:
+          "only a person, or an agent they gave admin access acting as them, can change who can use a machine",
+      });
+    }
+    requireFullAccessIfAgent(c, "Changing who can use a machine");
+    return grant;
+  }
+
+  // The new owner's Workspace schedules on the machine become Only me when
+  // they may have Only me schedules; otherwise they pause.
+  async function schedulesMayBeOnlyMe(workspaceId: string, ownerSubjectId: string | null) {
+    return ownerSubjectId === null
+      ? false
+      : await mayStartOnlyMe(db, settings, workspaceId, ownerSubjectId);
+  }
+
+  app.post("/v1/workspaces/:workspaceId/machines/:enrollmentId/audience/preview", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAudienceCaller(c, workspaceId);
+    const enrollmentId = c.req.param("enrollmentId");
+    const body = await parseRequestJson(c, MachineAudiencePreviewRequest);
+    const machine = await requireScopedEnrollment(grant, enrollmentId);
+    const { ownerSubjectId } = machineAudienceRequestFor(grant, workspaceId, machine, body);
+    const preview = await previewMachineAudienceChange(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      enrollmentId,
+      target: body.audience,
+      ownerSubjectId,
+      schedulesMayBeOnlyMe: await schedulesMayBeOnlyMe(workspaceId, ownerSubjectId),
+    });
+    if (typeof preview === "string") throw machineAudienceRefusalError(preview);
+    return c.json(machineAudiencePreview(preview));
+  });
+
+  app.put("/v1/workspaces/:workspaceId/machines/:enrollmentId/audience", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAudienceCaller(c, workspaceId);
+    const enrollmentId = c.req.param("enrollmentId");
+    const body = await parseRequestJson(c, ChangeMachineAudienceRequest);
+    const machine = await requireScopedEnrollment(grant, enrollmentId);
+    const { ownerSubjectId } = machineAudienceRequestFor(grant, workspaceId, machine, body);
+    const changed = await changeMachineAudience(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      enrollmentId,
+      target: body.audience,
+      ownerSubjectId,
+      schedulesMayBeOnlyMe: await schedulesMayBeOnlyMe(workspaceId, ownerSubjectId),
+      expectedGeneration: body.expectedGeneration,
+    });
+    return c.json(machineAudienceChangeResponse(changed));
+  });
+
+  // ── POST /workspaces/:ws/machines/:enrollmentId/screen-control ─────────────
+  // Turn screen control on for one connected machine, in place (see
+  // ../sandbox/screen-control.ts): record the consent, then have the live agent
+  // renew its credentials. Needs enrollments:manage, like connecting the
+  // machine; agents holding it call this too (or the
+  // connected_machine_enable_screen_control tool). No request body.
+  app.post("/v1/workspaces/:workspaceId/machines/:enrollmentId/screen-control", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "enrollments:manage",
+    );
+    const grant = authorization.grant;
+    assertSelfhostedEnabled();
+    const enrollmentId = c.req.param("enrollmentId");
+    const enrollment = await requireScopedEnrollment(grant, enrollmentId);
+    if (
+      enrollment.scope === "organization" &&
+      authorization.accountGrant?.permissions.includes("account:admin") !== true
+    ) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    try {
+      return c.json(
+        await enableMachineScreenControl(
+          { db, settings, bus, observability: deps.observability },
+          {
+            enrollment,
+            access: enrollmentAccess(enrollment, grant),
+            actor: { subjectId: grant.subjectId },
+          },
+        ),
+      );
+    } catch (error) {
+      if (error instanceof MachineNotActiveError) {
+        throw new HTTPException(404, { message: error.message });
+      }
+      throw error;
+    }
+  });
+
+  // ── POST /workspaces/:ws/machines/:enrollmentId/privacy-settings ───────────
+  // Open one macOS Privacy & Security pane on the connected Mac, so the person
+  // only flips the switch for Opengeni. Opening a pane grants nothing.
+  app.post("/v1/workspaces/:workspaceId/machines/:enrollmentId/privacy-settings", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "enrollments:manage",
+    );
+    const grant = authorization.grant;
+    assertSelfhostedEnabled();
+    const enrollmentId = c.req.param("enrollmentId");
+    const parsed = OpenMachinePrivacySettingsRequest.safeParse(
+      await c.req.json().catch(() => null),
+    );
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "invalid privacy settings request" });
+    }
+    const enrollment = await requireScopedEnrollment(grant, enrollmentId);
+    if (
+      enrollment.scope === "organization" &&
+      authorization.accountGrant?.permissions.includes("account:admin") !== true
+    ) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    if (enrollment.os !== "macos") {
+      throw new HTTPException(422, { message: "privacy settings panes exist only on macOS" });
+    }
+    return c.json(
+      await openMachinePrivacySettings(
+        { db, settings, bus, observability: deps.observability },
+        { enrollment, access: enrollmentAccess(enrollment, grant), pane: parsed.data.pane },
+      ),
+    );
+  });
+
   // ── POST /workspaces/:ws/machines/:enrollmentId/update ─────────────────────
   // Reserve one exact-generation operation, ask the authoritative runner to
   // drain and apply the signed promoted release, then let progress events + the
@@ -211,143 +386,22 @@ export function registerMachineRoutes(app: Hono, deps: ApiRouteDeps): void {
       visibleEnrollment.scope === "user" ? grant : originWorkspaceId,
       enrollmentId,
     );
-    if (!live?.connectionInstanceId || !live.agentVersion) {
+    if (!live || live.id !== enrollmentId || live.workspaceId !== originWorkspaceId) {
       throw new HTTPException(409, {
         message: "machine has no authoritative live agent build",
       });
     }
-    const channel = live.agentUpdateChannel ?? "stable";
-    const targetVersion =
-      channel === "beta"
-        ? (settings.agentBetaVersion ?? settings.agentStableVersion)
-        : settings.agentStableVersion;
-    const reusableRequest =
-      live.agentUpdate?.status === "requested" &&
-      live.agentUpdate.targetVersion === targetVersion &&
-      live.agentUpdate.connectionInstanceId === live.connectionInstanceId &&
-      live.agentUpdate.connectionGeneration === live.connectionGeneration
-        ? live.agentUpdate
-        : null;
-    if (
-      !reusableRequest &&
-      live.agentVersion === targetVersion &&
-      live.agentUpdate?.status !== "failed"
-    ) {
-      throw new HTTPException(409, {
-        message: "machine already runs the promoted version",
-      });
-    }
-    const operationId = reusableRequest?.operationId ?? crypto.randomUUID();
-    if (!reusableRequest) {
-      const reserved = await beginEnrollmentAgentUpdate(db, {
-        accountId: grant.accountId,
-        workspaceId: originWorkspaceId,
-        enrollmentId,
-        connectionInstanceId: live.connectionInstanceId,
-        connectionGeneration: live.connectionGeneration,
-        operationId,
-        targetVersion,
-      });
-      if (!reserved) {
-        throw new HTTPException(409, {
-          message: "machine update state changed; refresh and retry",
-        });
-      }
-    }
-
-    const rpc = new NatsControlRpc(async () => bus?.getRequestConnection() ?? null);
-    const request: ControlRequest = {
-      requestId: operationId,
-      // The subject already selects the exact authoritative process instance.
-      // `epoch` is the sandbox lease epoch, not the enrollment connection
-      // generation, so this process-scoped operation intentionally leaves it 0.
-      epoch: 0,
-      resourcePolicy: undefined,
-      op: {
-        $case: "agentUpdateApply",
-        agentUpdateApply: {
-          operationId,
-          targetVersion,
-          channel,
-          expectedCurrentVersion: live.agentVersion,
-          expectedCurrentSha256: live.agentBinarySha256 ?? "",
-          releaseBaseUrl: (settings.publicBaseUrl ?? new URL(c.req.url).origin).replace(/\/+$/, ""),
-        },
-      },
-    };
-    let response = await rpc.request(
-      subjectFor(originWorkspaceId, enrollmentId, live.connectionInstanceId),
-      request,
-      { timeoutMs: 10_000 },
-    );
-    // The operation id is idempotent. One retry heals an ambiguous lost reply;
-    // the agent returns the same acceptance and never starts a second update.
-    if (response.error?.code === ErrorCode.ERROR_CODE_TIMEOUT) {
-      response = await rpc.request(
-        subjectFor(originWorkspaceId, enrollmentId, live.connectionInstanceId),
-        request,
-        { timeoutMs: 10_000 },
-      );
-    }
-    if (response.error) {
-      // A second timeout remains ambiguous: progress/Hello may still prove the
-      // operation. Keep it requested rather than racing a false terminal failure.
-      if (response.error.code !== ErrorCode.ERROR_CODE_TIMEOUT) {
-        await advanceEnrollmentAgentUpdate(db, {
-          accountId: grant.accountId,
-          workspaceId: originWorkspaceId,
-          enrollmentId,
-          connectionInstanceId: live.connectionInstanceId,
-          connectionGeneration: live.connectionGeneration,
-          operationId,
-          status: "failed",
-          errorCode:
-            response.error.detail.failure_code ??
-            (response.error.code === ErrorCode.ERROR_CODE_AGENT_OFFLINE
-              ? "agent_offline"
-              : "update_dispatch_rejected"),
-          retryable: response.error.retryable,
-          rolledBack: false,
-        });
-        throw new HTTPException(response.error.retryable ? 409 : 422, {
-          message: response.error.message,
-        });
-      }
-    } else if (
-      response.result?.$case !== "agentUpdateApply" ||
-      !response.result.agentUpdateApply.accepted
-    ) {
-      await advanceEnrollmentAgentUpdate(db, {
-        accountId: grant.accountId,
-        workspaceId: originWorkspaceId,
-        enrollmentId,
-        connectionInstanceId: live.connectionInstanceId,
-        connectionGeneration: live.connectionGeneration,
-        operationId,
-        status: "failed",
-        errorCode: "invalid_agent_response",
-        retryable: true,
-        rolledBack: false,
-      });
-      throw new HTTPException(502, {
-        message: "agent returned an invalid update response",
-      });
-    } else {
-      await advanceEnrollmentAgentUpdate(db, {
-        accountId: grant.accountId,
-        workspaceId: originWorkspaceId,
-        enrollmentId,
-        connectionInstanceId: live.connectionInstanceId,
-        connectionGeneration: live.connectionGeneration,
-        operationId,
-        status: "accepted",
-      });
+    const result = await requestAgentUpdate({ db, bus, settings }, live, {
+      releaseBaseUrl: settings.publicBaseUrl ?? new URL(c.req.url).origin,
+    });
+    if (result.kind === "refused") {
+      throw new HTTPException(result.status, { message: result.message });
     }
     return c.json(
       UpdateMachineAgentResponse.parse({
-        operationId,
+        operationId: result.operationId,
         accepted: true,
-        targetVersion,
+        targetVersion: result.targetVersion,
       }),
       202,
     );
@@ -388,7 +442,7 @@ export function registerMachineRoutes(app: Hono, deps: ApiRouteDeps): void {
         throw error;
       }
     }
-    const body = SwapActiveSandboxRequest.parse(await c.req.json());
+    const body = await parseRequestJson(c, SwapActiveSandboxRequest);
     const ctx = await buildFleetContextForSession(deps, {
       accountId: grant.accountId,
       workspaceId,

package/src/routes/managed-auth-session-sets.ts

@@ -1,3 +1,8 @@
+import {
+  assertManagedUserAdmission,
+  getManagedSession,
+  withManagedAuthSessionLookup,
+} from "@opengeni/core";
 import { randomUUID } from "node:crypto";
 import {
   BeginManagedAuthLoginTransactionRequest,
@@ -64,7 +69,10 @@ import { sql } from "drizzle-orm";
 import type { Context, Hono } from "hono";
 import { deleteCookie, getCookie, setCookie } from "hono/cookie";
 import { HTTPException } from "hono/http-exception";
+import { SIGNUP_ATTRIBUTION_AUTH_FIELD } from "../auth/signup-funnel-metrics";
 import { ApiHttpError } from "../http/api-error";
+import { trustedRequestSourceRateLimitKey } from "../http/request-source";
+import { ManagedAuthEmailThrottleError } from "../auth/managed-auth-rate-limits";
 import { z } from "zod";
 
 const ManagedAuthSocialStartReceipt = z
@@ -97,6 +105,11 @@ export function registerManagedAuthSessionSetRoutes(app: Hono, deps: ApiRouteDep
   app.get("/v1/auth/get-session", async (context) => {
     if (deps.settings.managedAuthSessionSetMode === "legacy") {
       if (!deps.managedAuth) throw new HTTPException(404);
+      if (deps.settings.allowedUserEmails !== undefined) {
+        const session = await getManagedSession(context, deps.managedAuth, { db: deps.db });
+        context.header("cache-control", "no-store");
+        return context.json(session ? safeBetterAuthSession(session) : null);
+      }
       return await deps.managedAuth.handler(context.req.raw);
     }
     context.header("cache-control", "no-store");
@@ -188,10 +201,13 @@ export function registerManagedAuthSessionSetRoutes(app: Hono, deps: ApiRouteDep
   app.post("/v1/auth/session-set/bootstrap", async (context) => {
     const body = await bodyAs(context, BootstrapManagedAuthSessionSetRequest);
     const { authority, actorEpoch } = await requireMutation(context, deps, body.expectedGeneration);
-    const ambient = await requireAvailable(deps).managedAuth!.api.getSession({
-      headers: context.req.raw.headers,
-      returnHeaders: true,
-    });
+    const ambient = await withManagedAuthSessionLookup(() =>
+      requireAvailable(deps).managedAuth!.api.getSession({
+        headers: context.req.raw.headers,
+        returnHeaders: true,
+      }),
+    );
+    assertManagedUserAdmission(deps.managedAuth!, ambient.response?.user);
     const authSessionId = ambient.response?.session?.id;
     if (typeof authSessionId !== "string") {
       throw managedAuthApiError(401, "managed_authentication_required");
@@ -313,7 +329,7 @@ export function registerManagedAuthSessionSetRoutes(app: Hono, deps: ApiRouteDep
         }),
       );
     } catch (error) {
-      throwHttp(error);
+      throwHttp(error, context);
     }
   });
 
@@ -392,6 +408,9 @@ export function registerManagedAuthSessionSetRoutes(app: Hono, deps: ApiRouteDep
                 expectedGeneration: body.expectedGeneration,
                 expectedActorEpoch: actorEpoch,
               },
+              // Content-free acquisition metrics read this from the OAuth
+              // state if the callback creates a new account.
+              ...(body.attribution ? { [SIGNUP_ATTRIBUTION_AUTH_FIELD]: body.attribution } : {}),
             },
           },
           headers: isolatedManagedAuthHeaders(context.req.raw),
@@ -1009,11 +1028,9 @@ function digest(deps: ApiRouteDeps, value: unknown): string {
 }
 
 function loginTransactionClientScope(context: Context, deps: ApiRouteDeps): string {
-  const forwarded = context.req.header("x-forwarded-for")?.split(",")[0]?.trim();
-  const address = forwarded || context.req.header("x-real-ip")?.trim() || "unknown";
   return digest(deps, {
     purpose: "managed-auth-login-transaction-rate-limit",
-    client: address.slice(0, 128),
+    client: trustedRequestSourceRateLimitKey(context, deps.settings),
   });
 }
 
@@ -1107,7 +1124,7 @@ function appendCookies(context: Context, cookies: readonly string[]): void {
   for (const cookie of cookies) context.header("set-cookie", cookie, { append: true });
 }
 
-function throwHttp(error: unknown): never {
+function throwHttp(error: unknown, context?: Context): never {
   if (error instanceof HTTPException) throw error;
   if (error instanceof ManagedAuthSessionSetGenerationConflictError) {
     throw managedAuthApiError(409, "generation_conflict", { cause: error, retryable: true });
@@ -1127,6 +1144,16 @@ function throwHttp(error: unknown): never {
   if (error instanceof ManagedAuthActorMutationInFlightError) {
     throw managedAuthApiError(409, "actor_mutation_in_flight", { cause: error, retryable: true });
   }
+  if (error instanceof ManagedAuthEmailThrottleError) {
+    // A per-email window lasts 15 minutes to an hour; tell the client when,
+    // unlike the short login-transaction backoff.
+    context?.header("Retry-After", String(error.retryAfterSeconds));
+    throw managedAuthApiError(429, "login_transaction_rate_limited", {
+      cause: error,
+      retryable: true,
+      retryAfterSeconds: error.retryAfterSeconds,
+    });
+  }
   if (error instanceof ManagedAuthLoginTransactionRateLimitError) {
     throw managedAuthApiError(429, "login_transaction_rate_limited", {
       cause: error,
@@ -1153,6 +1180,7 @@ function managedAuthApiError(
     cause?: unknown;
     retryable?: boolean;
     outcomeUnknown?: boolean;
+    retryAfterSeconds?: number;
   } = {},
 ): ApiHttpError {
   ManagedAuthSessionSetErrorCode.parse(code);
@@ -1177,7 +1205,12 @@ function managedAuthApiError(
     message: code,
     retryable: options.retryable ?? false,
     ...(options.outcomeUnknown === undefined ? {} : { outcomeUnknown: options.outcomeUnknown }),
-    details: { managedAuthCode: code },
+    details: {
+      managedAuthCode: code,
+      ...(options.retryAfterSeconds === undefined
+        ? {}
+        : { retryAfterSeconds: options.retryAfterSeconds }),
+    },
   });
   if (options.cause !== undefined) (error as Error & { cause?: unknown }).cause = options.cause;
   return error;

package/src/routes/managed-onboarding.ts

@@ -1,3 +1,4 @@
+import { signupCreditModelIds } from "@opengeni/config";
 import {
   CompleteSelfServiceOrganizationSetupRequest,
   CompleteSelfServiceOrganizationSetupResponse,
@@ -15,6 +16,7 @@ import {
   nestedPostgresSqlState,
   preflightOrganizationUserSetup,
   previewOrganizationUserSetup,
+  recordOrganizationSignupUseCase,
 } from "@opengeni/db";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
@@ -24,7 +26,9 @@ import {
   organizationUserSetupTokenDigest,
   selfServiceOrganizationSetupRequestFingerprint,
 } from "../auth/organization-user-setup";
+import { recordOrganizationSetupOutcome } from "../auth/signup-funnel-metrics";
 import { hashManagedAuthPassword } from "../auth/managed-auth";
+import { trustedRequestSourceRateLimitKey } from "../http/request-source";
 
 export type ManagedOnboardingRouteOptions = {
   accountSetupLimiter?: { take(key: string): boolean };
@@ -59,6 +63,7 @@ export function registerManagedOnboardingRoutes(
       await context.req.json().catch(() => null),
     );
     if (!parsed.success) {
+      recordOrganizationSetupOutcome(deps.observability, "failed");
       throw new HTTPException(422, {
         message: "invalid organization setup request",
       });
@@ -69,18 +74,38 @@ export function registerManagedOnboardingRoutes(
         authUserId: session.user.id,
         organizationName,
       });
-      return context.json(
-        CompleteSelfServiceOrganizationSetupResponse.parse(
-          await completeSelfServiceOrganizationSetup(deps.db, {
-            authUserId: session.user.id,
-            actorSubjectId: `user:${session.user.id}`,
-            organizationName,
-            operationId: parsed.data.operationId,
-            requestFingerprint,
-          }),
-        ),
+      const completed = CompleteSelfServiceOrganizationSetupResponse.parse(
+        await completeSelfServiceOrganizationSetup(deps.db, {
+          authUserId: session.user.id,
+          actorSubjectId: `user:${session.user.id}`,
+          organizationName,
+          operationId: parsed.data.operationId,
+          requestFingerprint,
+          trialCreditModelIds: signupCreditModelIds(deps.settings),
+          trialCreditsEnabled:
+            deps.settings.productAccessMode === "managed" &&
+            deps.settings.verifiedSignupTrialCreditsEnabled,
+        }),
       );
+      // An idempotent replay of the same operation returns the same committed
+      // setup and is counted again; clients retry only on an ambiguous response.
+      recordOrganizationSetupOutcome(deps.observability, "created");
+      if (parsed.data.useCase) {
+        // The organization is already committed, so a failure to keep the
+        // signup answer must not fail its setup. The first answer wins.
+        await recordOrganizationSignupUseCase(deps.db, {
+          organizationId: completed.organizationId,
+          subjectId: `user:${session.user.id}`,
+          useCase: parsed.data.useCase,
+        }).catch((error: unknown) => {
+          console.warn("[api] could not record the signup use case", {
+            sqlState: nestedPostgresSqlState(error) ?? null,
+          });
+        });
+      }
+      return context.json(completed);
     } catch (error) {
+      recordOrganizationSetupOutcome(deps.observability, "failed");
       const sqlState = nestedPostgresSqlState(error);
       if (sqlState === "22023") {
         throw new HTTPException(422, {
@@ -105,7 +130,7 @@ export function registerManagedOnboardingRoutes(
     if (deps.settings.productAccessMode !== "managed" || !deps.managedAuth) {
       throw new HTTPException(404, { message: "account setup is unavailable" });
     }
-    enforceAccountSetupRateLimit(context, accountSetupLimiter);
+    enforceAccountSetupRateLimit(context, deps, accountSetupLimiter);
     const parsed = PreviewOrganizationUserSetupRequest.safeParse(
       await context.req.json().catch(() => null),
     );
@@ -126,7 +151,7 @@ export function registerManagedOnboardingRoutes(
     if (deps.settings.productAccessMode !== "managed" || !deps.managedAuth) {
       throw new HTTPException(404, { message: "account setup is unavailable" });
     }
-    enforceAccountSetupRateLimit(context, accountSetupLimiter);
+    enforceAccountSetupRateLimit(context, deps, accountSetupLimiter);
     const parsed = CompleteOrganizationUserSetupRequest.safeParse(
       await context.req.json().catch(() => null),
     );
@@ -189,11 +214,12 @@ export function registerManagedOnboardingRoutes(
 
 function enforceAccountSetupRateLimit(
   context: Context,
+  deps: ApiRouteDeps,
   limiter: { take(key: string): boolean },
 ): void {
   let allowed = false;
   try {
-    allowed = limiter.take(accountSetupClientKey(context));
+    allowed = limiter.take(trustedRequestSourceRateLimitKey(context, deps.settings));
   } catch {
     // A public credential-setting endpoint must fail closed if its abuse gate
     // cannot make a decision.
@@ -203,12 +229,6 @@ function enforceAccountSetupRateLimit(
   }
 }
 
-function accountSetupClientKey(context: Context): string {
-  const forwarded = context.req.header("x-forwarded-for")?.split(",")[0]?.trim();
-  const address = forwarded || context.req.header("x-real-ip")?.trim() || "unknown";
-  return address.slice(0, 128);
-}
-
 /**
  * Bounded application-tier protection for the public setup bearer endpoint.
  * The global bucket prevents spoofed/high-cardinality client keys from