@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/desktop-distribution.ts

@@ -0,0 +1,217 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import type { ApiRouteDeps } from "@opengeni/core";
+
+// Public download routes for the desktop app. Like the agent install routes,
+// they are unauthenticated so a person can install the app before signing in:
+//
+//   GET /desktop/install.sh          the macOS and Linux installer
+//   GET /desktop/latest              302 to the current release's page
+//   GET /desktop/latest/<asset>      302 to the current release's file
+//
+// <asset> is a version-less release file name such as Opengeni-mac.dmg. The
+// route redirects to Opengeni-<version>-mac.dmg on the desktop-v<version>
+// release. GitHub's repository-wide "latest release" can't be used: agent and
+// package releases share the repository, so "latest" is rarely the desktop app.
+
+const INSTALL_DIR =
+  [
+    new URL("./assets/desktop-install/", import.meta.url),
+    new URL("../../../desktop/install/", import.meta.url),
+  ].find((candidate) => existsSync(candidate)) ??
+  new URL("../../../desktop/install/", import.meta.url);
+
+export const DESKTOP_INSTALLER_PATH = "/desktop/install.sh";
+export const DESKTOP_RELEASE_PAGE_PATH = "/desktop/latest";
+export const DESKTOP_DOWNLOAD_PREFIX = "/desktop/latest/";
+
+// Every file a desktop release publishes for people to download, without its
+// version. A strict list, so the redirect can't point anywhere else.
+const RELEASE_FILE =
+  /^Opengeni-(mac\.dmg|mac\.zip|windows\.exe|windows-(?:x64|arm64)\.exe|linux-(?:x86_64|arm64)\.AppImage|linux-(?:amd64|arm64)\.deb|linux-(?:x86_64|aarch64)\.rpm)$/u;
+
+const STABLE_VERSION = /^(\d+)\.(\d+)\.(\d+)$/u;
+const TAG_PREFIX = "desktop-v";
+
+/** The versioned release file for a version-less name, or null if it isn't one. */
+export function desktopReleaseFile(asset: string, version: string): string | null {
+  if (asset === "SHA256SUMS") return asset;
+  const match = RELEASE_FILE.exec(asset);
+  return match ? `Opengeni-${version}-${match[1]}` : null;
+}
+
+/** The highest stable version among desktop-v<version> tags. */
+export function newestDesktopVersion(tags: readonly string[]): string | null {
+  let best: number[] | null = null;
+  for (const tag of tags) {
+    if (!tag.startsWith(TAG_PREFIX)) continue;
+    const match = STABLE_VERSION.exec(tag.slice(TAG_PREFIX.length));
+    if (!match) continue;
+    const version = match.slice(1).map(Number);
+    if (!best || compareVersions(version, best) > 0) best = version;
+  }
+  return best ? best.join(".") : null;
+}
+
+function compareVersions(left: number[], right: number[]): number {
+  for (let index = 0; index < 3; index++) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+
+/** owner/name for a https://github.com/<owner>/<name>/releases base, else null. */
+export function githubRepositoryOf(releasesBase: string): string | null {
+  const match = /^https:\/\/github\.com\/([\w.-]+\/[\w.-]+)\/releases\/?$/u.exec(releasesBase);
+  return match?.[1] ?? null;
+}
+
+export interface DesktopVersionResolverOptions {
+  /** An operator pin. When set, it is the only version ever served. */
+  pinnedVersion?: string | undefined;
+  releasesBase: string;
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+  /** How long a looked-up version is reused. */
+  freshForMs?: number;
+  /** How long to wait before looking again after a failed lookup. */
+  retryAfterMs?: number;
+}
+
+/**
+ * The version /desktop/latest serves: the pin, or the newest desktop-v tag on
+ * the release repository. A lookup is shared by concurrent requests and reused
+ * for ten minutes, well within GitHub's unauthenticated rate limit. When GitHub
+ * is unreachable the last known version keeps serving.
+ */
+export function createDesktopVersionResolver(
+  options: DesktopVersionResolverOptions,
+): () => Promise<string> {
+  const { pinnedVersion } = options;
+  if (pinnedVersion) return async () => pinnedVersion;
+  const repository = githubRepositoryOf(options.releasesBase);
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const now = options.now ?? Date.now;
+  const freshForMs = options.freshForMs ?? 10 * 60_000;
+  const retryAfterMs = options.retryAfterMs ?? 30_000;
+  let known: string | null = null;
+  let nextLookupAt = 0;
+  let inFlight: Promise<void> | null = null;
+
+  async function lookUp(): Promise<void> {
+    try {
+      const response = await fetchImpl(
+        `https://api.github.com/repos/${repository}/git/matching-refs/tags/${TAG_PREFIX}`,
+        {
+          headers: { accept: "application/vnd.github+json", "user-agent": "opengeni-api" },
+          signal: AbortSignal.timeout(5_000),
+        },
+      );
+      if (!response.ok) throw new Error(`GitHub answered ${response.status}`);
+      const refs = (await response.json()) as Array<{ ref?: unknown }>;
+      const version = newestDesktopVersion(
+        refs.flatMap((entry) =>
+          typeof entry.ref === "string" && entry.ref.startsWith("refs/tags/")
+            ? [entry.ref.slice("refs/tags/".length)]
+            : [],
+        ),
+      );
+      if (version) known = version;
+      nextLookupAt = now() + (version ? freshForMs : retryAfterMs);
+    } catch {
+      nextLookupAt = now() + retryAfterMs;
+    }
+  }
+
+  return async () => {
+    if (!repository) {
+      throw new HTTPException(503, {
+        message: "Desktop downloads need OPENGENI_DESKTOP_STABLE_VERSION for this release host.",
+      });
+    }
+    if (now() >= nextLookupAt) {
+      inFlight ??= lookUp().finally(() => {
+        inFlight = null;
+      });
+      // The first lookup has nothing to fall back to; later ones refresh in
+      // the background and keep serving the version already known.
+      if (!known) await inFlight;
+    }
+    if (!known) {
+      throw new HTTPException(503, { message: "No desktop release is available yet." });
+    }
+    return known;
+  };
+}
+
+let installerBody: string | undefined;
+
+// The installer resolves releases through this server when it knows the
+// server's address, so a deployment's version pin applies. A copy run from the
+// repository looks the release up on GitHub itself.
+const BASE_URL_MARKER = 'OPENGENI_DESKTOP_DEFAULT_BASE_URL=""';
+
+export function desktopInstallerFor(body: string, publicBaseUrl: string | undefined): string {
+  if (!publicBaseUrl || !/^https?:\/\//u.test(publicBaseUrl)) return body;
+  const base = publicBaseUrl.replace(/\/+$/u, "");
+  return body.replace(BASE_URL_MARKER, `OPENGENI_DESKTOP_DEFAULT_BASE_URL="${base}"`);
+}
+
+export function registerDesktopDistributionRoutes(
+  app: Hono,
+  deps: ApiRouteDeps,
+  resolveVersion = createDesktopVersionResolver({
+    pinnedVersion: deps.settings.desktopStableVersion,
+    releasesBase: deps.settings.agentReleasesBaseUrl.replace(/\/+$/u, ""),
+  }),
+): void {
+  const releasesBase = deps.settings.agentReleasesBaseUrl.replace(/\/+$/u, "");
+
+  app.get(DESKTOP_INSTALLER_PATH, async (c) => {
+    installerBody ??= await readFile(new URL("install.sh", INSTALL_DIR), "utf8");
+    return c.text(desktopInstallerFor(installerBody, deps.settings.publicBaseUrl), 200, {
+      "content-type": "text/x-shellscript; charset=utf-8",
+      "cache-control": "public, max-age=300",
+    });
+  });
+
+  // The release page, listing every platform's download.
+  app.get(DESKTOP_RELEASE_PAGE_PATH, async () => {
+    const version = await resolveVersion();
+    return new Response(null, {
+      status: 302,
+      headers: {
+        location: `${releasesBase}/tag/${TAG_PREFIX}${version}`,
+        "cache-control": "public, max-age=300",
+      },
+    });
+  });
+
+  app.get(`${DESKTOP_DOWNLOAD_PREFIX}:asset`, async (c) => {
+    const asset = c.req.param("asset");
+    // Validate before resolving, so a bad name never costs a lookup.
+    if (!desktopReleaseFile(asset, "0.0.0")) {
+      throw new HTTPException(404, { message: "Unknown desktop download." });
+    }
+    const version = await resolveVersion();
+    const file = desktopReleaseFile(asset, version)!;
+    return new Response(null, {
+      status: 302,
+      headers: {
+        location: `${releasesBase}/download/${TAG_PREFIX}${version}/${file}`,
+        "cache-control": "public, max-age=300",
+      },
+    });
+  });
+}
+
+export function isDesktopDistributionPath(path: string): boolean {
+  return (
+    path === DESKTOP_INSTALLER_PATH ||
+    path === DESKTOP_RELEASE_PAGE_PATH ||
+    path.startsWith(DESKTOP_DOWNLOAD_PREFIX)
+  );
+}

package/src/routes/documents.ts

@@ -61,6 +61,8 @@ import {
   prepareMcpOAuthWorkspaceToolGateway,
 } from "../workspace-tool-gateway";
 import { sanitizeFilename } from "./files";
+import { userContentSignedGetUrlOptions } from "../http/user-content";
+import { parseRequestBody, parseRequestJson } from "../http/request-body";
 
 export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
   const { db, objectStorage, documentIndexer, getDocumentServices } = deps;
@@ -93,7 +95,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.post("/v1/workspaces/:workspaceId/document-bases", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
-    const payload = CreateDocumentBaseRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, CreateDocumentBaseRequest);
     return c.json(
       DocumentBase.parse(
         await createDocumentBase(db, { ...payload, accountId: grant.accountId, workspaceId }),
@@ -137,7 +139,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       throw new HTTPException(403, { message: "missing permission: account:admin" });
     }
     const accountAdminAuthorization = requireAccountAdminAuthorizationStamp(authorization);
-    const payload = RunDocumentDefaultCollectionBackfillRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, RunDocumentDefaultCollectionBackfillRequest);
     try {
       return c.json(
         DocumentDefaultCollectionBackfill.parse(
@@ -268,7 +270,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       action: "document:index",
       quantity: 0,
     });
-    const payload = AddDocumentRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, AddDocumentRequest);
     const organizationAuthorityGranted =
       access.accountGrant?.permissions.includes("account:admin") === true;
     if (payload.authorityKind === "organization" && !organizationAuthorityGranted) {
@@ -338,7 +340,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
         workspaceId,
         "documents:manage",
       );
-      const payload = ReclassifyDocumentAuthorityRequest.parse(await c.req.json());
+      const payload = await parseRequestJson(c, ReclassifyDocumentAuthorityRequest);
       const accountAdminAuthorized = hasAccountAdminAuthority(authorization);
       const accountAdminAuthorization = accountAdminAuthorized
         ? requireAccountAdminAuthorizationStamp(authorization)
@@ -435,7 +437,10 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       if (file.status !== "ready") {
         throw new HTTPException(409, { message: `file is ${file.status}` });
       }
-      const signed = await objectStorage.createGetUrl({ key: file.objectKey });
+      const signed = await objectStorage.createGetUrl({
+        key: file.objectKey,
+        ...userContentSignedGetUrlOptions(file.contentType, file.filename),
+      });
       await recordAuditEvent(db, {
         accountId: grant.accountId,
         workspaceId,
@@ -591,7 +596,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       action: "document:index",
       quantity: 0,
     });
-    const payload = CreateKnowledgeDropRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, CreateKnowledgeDropRequest);
     const personalFileOwner =
       payload.authorityKind === "personal"
         ? (await fileOwnerContextForAccess(deps, access, "documents:manage"))
@@ -712,7 +717,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
     const { grant } = authorization;
     const organizationAuthorityGranted = hasAccountAdminAuthority(authorization);
-    const payload = MoveDocumentRequest.parse(await c.req.json().catch(() => ({})));
+    const payload = parseRequestBody(MoveDocumentRequest, await c.req.json().catch(() => ({})));
     try {
       const document = await getDocument(db, workspaceId, c.req.param("documentId"), {
         viewerSubjectId: grant.subjectId,
@@ -818,6 +823,7 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
             await requireAccessGrantAuthorization(c, deps, workspaceId, "documents:search"),
             "documents:search",
           ),
+          settings: deps.settings,
         },
       );
       await server.connect(transport);

package/src/routes/editable-artifacts.ts

@@ -11,6 +11,9 @@ import {
   editableArtifactScope,
   hasPermission,
   requireAccessGrant,
+  requireAccessGrantAuthorization,
+  externalActorContinuationForAuthorization,
+  requirePermission,
   requireSessionAuthorization,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
@@ -25,11 +28,13 @@ import {
   type EditableArtifactPinnedVersion,
   type EditableArtifactModality,
 } from "@opengeni/core";
-import { listEditableArtifactIdsForSession } from "@opengeni/db";
+import { hasEditableArtifactSessionLink, listEditableArtifactIdsForSession } from "@opengeni/db";
 import type { Context, Hono } from "hono";
 import { z } from "zod";
 
 import { ApiHttpError } from "../http/api-error";
+import { USER_CONTENT_SECURITY_HEADERS } from "../http/user-content";
+import { withAccessGrantSessionRlsContext } from "../access-grant-rls";
 
 export const EDITABLE_ARTIFACT_HTTP_REQUEST_MAX_BYTES = 4 * 1024;
 export const EDITABLE_ARTIFACT_EXPORT_REQUEST_MAX_BYTES = 260 * 1024;
@@ -77,6 +82,7 @@ const ListEditableArtifactsQuery = z
 
 const MintEditableArtifactLiveTicketRequest = z
   .object({
+    sourceSessionId: SessionId.optional(),
     replicaId: ReplicaId,
     modality: z.enum(["document", "spreadsheet", "presentation"]),
     liveProtocolVersion: PositiveProtocolVersion,
@@ -471,7 +477,13 @@ export function registerEditableArtifactRoutes(
 
     // Workspace authentication precedes path/body parsing. Exact artifact
     // permission is intentionally enforced inside the injected application.
-    const grant = await requireAccessGrant(context, deps, workspaceId, "artifacts:read");
+    const authorization = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "artifacts:read",
+    );
+    const grant = authorization.grant;
     const artifactId = editableArtifactId(parseArtifactId(context.req.param("artifactId")));
     const body = await parseBoundedTicketRequest(context);
     const actor = editableArtifactActorForGrant(grant, body.replicaId);
@@ -479,6 +491,18 @@ export function registerEditableArtifactRoutes(
       accountId: grant.accountId,
       workspaceId,
     });
+    if (body.sourceSessionId) {
+      requirePermission(grant, "sessions:read");
+      await withAccessGrantSessionRlsContext(deps, grant, async () => {
+        await authorizeSourceSession(deps, grant, body.sourceSessionId!);
+        if (
+          !(await hasEditableArtifactSessionLink(deps.db, scope, body.sourceSessionId!, artifactId))
+        ) {
+          throw applicationHttpError("not_found");
+        }
+      });
+    }
+    const externalContinuation = externalActorContinuationForAuthorization(authorization);
 
     let rawTicket: MintEditableArtifactLiveTicketOutput;
     try {
@@ -494,6 +518,44 @@ export function registerEditableArtifactRoutes(
         commandProtocolVersion: body.commandProtocolVersion,
         committedTransactionProtocolVersion: body.committedTransactionProtocolVersion,
         allowEdit: hasPermission(grant.permissions, "artifacts:publish"),
+        ...(body.sourceSessionId
+          ? {
+              sourceSessionAuthority: {
+                sessionId: body.sourceSessionId,
+                grant: {
+                  accountId: grant.accountId,
+                  workspaceId: grant.workspaceId,
+                  subjectId: grant.subjectId,
+                  ...(grant.principalKind ? { principalKind: grant.principalKind } : {}),
+                  ...(grant.metadata
+                    ? {
+                        metadata: Object.fromEntries(
+                          Object.entries(grant.metadata).filter(([key]) =>
+                            [
+                              "externalActor",
+                              "delegated",
+                              "sessionId",
+                              "turnId",
+                              "attemptId",
+                              "executionGeneration",
+                            ].includes(key),
+                          ),
+                        ),
+                      }
+                    : {}),
+                  // Bind only editor capabilities, not a broad delegated wildcard.
+                  permissions: [
+                    "sessions:read",
+                    "artifacts:read",
+                    ...(hasPermission(grant.permissions, "artifacts:publish")
+                      ? ["artifacts:publish" as const]
+                      : []),
+                  ],
+                },
+                ...(externalContinuation ? { externalContinuation } : {}),
+              },
+            }
+          : {}),
       });
     } catch (error) {
       throw editableArtifactHttpError(error);
@@ -547,6 +609,14 @@ export function registerEditableArtifactRoutes(
     const body = await parseBoundedMaterializationRequest(context);
     const scope = editableArtifactScope({ accountId: grant.accountId, workspaceId });
     const actor = editableArtifactActorForGrant(grant, body.replicaId);
+    // Without a materializer workload the job would stay queued forever.
+    if (!deps.settings.artifactMaterializerDeployed) {
+      throw new ApiHttpError(503, {
+        code: "upstream_unavailable",
+        message: "File export is not available on this deployment.",
+        retryable: false,
+      });
+    }
     try {
       const result = await requireEditableArtifactExports(deps).enqueueMaterialization({
         scope,
@@ -616,7 +686,7 @@ export function registerEditableArtifactRoutes(
         "content-length": String(download.byteSize),
         "content-type": download.mimeType,
         etag: `"${download.contentHash}"`,
-        "x-content-type-options": "nosniff",
+        ...USER_CONTENT_SECURITY_HEADERS,
       },
     });
   });
@@ -1067,7 +1137,7 @@ export function editableArtifactHttpError(error: unknown): unknown {
       case "unsupported_format":
         return new ApiHttpError(422, {
           code: "validation_failed",
-          message: "Editable artifact format is not available for this artifact.",
+          message: error.message,
         });
       case "not_ready":
         return new ApiHttpError(409, {

package/src/routes/enrollments.ts

@@ -37,6 +37,7 @@ import {
   MintEnrollTokenRequest,
   MintEnrollTokenResponse,
   RemoveEnrollmentRequest,
+  RenewEnrollmentRequest,
   RevokeEnrollmentResponse,
   type EnrollmentArch,
   type EnrollmentOs,
@@ -46,10 +47,13 @@ import {
   listEnrollments,
   MachineRemovalIdempotencyError,
   MachineRemovalRevisionConflictError,
+  PersonalMachineConnectedElsewhereError,
   removeEnrollment,
 } from "@opengeni/db";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
+import { trustedRequestSourceRateLimitKey } from "../http/request-source";
+import { isPersonalConnectionOwnerPrincipal } from "../connection-ownership";
 import {
   requireAccessGrant,
   requireAccessGrantAuthorization,
@@ -64,9 +68,39 @@ import {
   mintEnrollToken,
   pollDeviceEnrollment,
   startDeviceEnrollment,
+  renewEnrollmentCredentials,
   toLookupResponse,
 } from "../sandbox/enrollment";
 
+const ENROLLMENT_OUTCOMES = new Set([
+  "ok",
+  "authorized",
+  "expired",
+  "denied",
+  "disabled",
+  "invalid",
+  "used",
+  "unauthorized",
+]);
+
+// A personal machine reconnects only from the workspace it was first connected
+// from. The install script and the approval page show this message verbatim.
+const PERSONAL_MACHINE_ELSEWHERE_MESSAGE =
+  "this machine was first connected as a personal machine from another workspace; connect it again from that workspace";
+
+/** Machine enrollment decisions that never surface as an HTTP error status. */
+function recordEnrollment(deps: ApiRouteDeps, flow: string, outcome: string): void {
+  try {
+    deps.observability?.incrementCounter({
+      name: "opengeni_machine_enrollment_total",
+      help: "Connected Machine enrollment decisions by flow (device_start, device_poll, token_exchange, renew) and closed outcome.",
+      labels: { flow, outcome: ENROLLMENT_OUTCOMES.has(outcome) ? outcome : "other" },
+    });
+  } catch {
+    // Telemetry never changes the enrollment decision.
+  }
+}
+
 export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
   const { settings, db } = deps;
 
@@ -84,7 +118,8 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
   // poll). The relay tier owns the heavy stream rate-limiting; this
   // is the application-tier abuse cap on the device-flow endpoints. Per-IP buckets
   // are pruned lazily. Not a distributed limiter (one replica per bucket) — that is
-  // acceptable for a bounded, access-key-gated, short-TTL flow.
+  // acceptable for a bounded, short-TTL flow. These routes are public even behind
+  // the deployment key, because a machine never holds that key.
   const startLimiter = new TokenBucket({ capacity: 10, refillPerSecond: 0.5 });
   const pollLimiter = new TokenBucket({ capacity: 60, refillPerSecond: 2 });
   // The click-Grant approve-page lookup (authenticated, but capped against a
@@ -98,12 +133,28 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
   });
 
   function rateLimit(c: Context, limiter: TokenBucket): void {
-    const ip = clientIp(c);
+    const ip = trustedRequestSourceRateLimitKey(c, settings);
     if (!limiter.take(ip)) {
       throw new HTTPException(429, { message: "too many requests; slow down" });
     }
   }
 
+  // Machine authentication: signed install-key proof + current enrollment grant.
+  app.post("/v1/enrollments/renew", async (c) => {
+    assertSelfhostedEnabled();
+    rateLimit(c, exchangeLimiter);
+    const parsed = RenewEnrollmentRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid renewal request" });
+    const credentials = await renewEnrollmentCredentials({ db, settings }, parsed.data);
+    recordEnrollment(deps, "renew", credentials ? "ok" : "unauthorized");
+    if (!credentials)
+      throw new HTTPException(401, {
+        message: "machine renewal not authorized",
+      });
+    c.header("Cache-Control", "no-store");
+    return c.json(EnrollTokenExchangeResponse.parse({ credentials }), 200);
+  });
+
   // ── POST /enrollments/device/start (agent-side, user-unauthenticated) ───────
   app.post("/v1/enrollments/device/start", async (c) => {
     assertSelfhostedEnabled();
@@ -136,6 +187,7 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
         verificationOrigin: settings.publicBaseUrl ?? new URL(c.req.url).origin,
       },
     );
+    recordEnrollment(deps, "device_start", "ok");
     return c.json(result, 201);
   });
 
@@ -151,6 +203,8 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
       { db, settings },
       { deviceCode: parsed.data.deviceCode },
     );
+    // `pending` is the normal polling loop; count only decisions.
+    if (result.state !== "pending") recordEnrollment(deps, "device_poll", result.state);
     return c.json(result, 200);
   });
 
@@ -220,6 +274,7 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
         canOfferDisplay: body.canOfferDisplay,
       },
     );
+    recordEnrollment(deps, "token_exchange", result.ok ? "ok" : result.reason);
     if (!result.ok) {
       if (result.reason === "disabled") {
         // The credential plane is off for this deployment (no signing secret).
@@ -227,6 +282,30 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
           message: "enrollment credential plane is not configured",
         });
       }
+      if (result.reason === "used") {
+        // Single-use: another machine already redeemed this token. Same 401 as
+        // an invalid token, with a message the install script prints verbatim.
+        throw new HTTPException(401, {
+          message:
+            "this connect command was already used to connect another machine; create a new one for this machine",
+        });
+      }
+      if (result.reason === "owner_unavailable") {
+        // A personal command whose creator can no longer own a machine here.
+        throw new HTTPException(403, {
+          message:
+            "the person who created this connect command can no longer connect machines to this workspace; create a new command",
+        });
+      }
+      if (result.reason === "connected_elsewhere") {
+        // Nothing changed and the command was not used up.
+        throw new HTTPException(409, { message: PERSONAL_MACHINE_ELSEWHERE_MESSAGE });
+      }
+      if (result.reason === "busy") {
+        throw new HTTPException(503, {
+          message: "workspace membership is changing; run the connect command again",
+        });
+      }
       // An invalid / expired / wrong-typ token — the token is the auth, so 401.
       throw new HTTPException(401, {
         message: "invalid or expired enroll token",
@@ -287,7 +366,13 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
         approvedBySubjectId: grant.subjectId,
         approvedBySubjectLabel: grant.subjectLabel ?? null,
       },
-    );
+    ).catch((error: unknown) => {
+      if (error instanceof PersonalMachineConnectedElsewhereError) {
+        // Nothing changed; the request stays pending.
+        throw new HTTPException(409, { message: PERSONAL_MACHINE_ELSEWHERE_MESSAGE });
+      }
+      throw error;
+    });
     if (!approved) {
       // An unknown / expired / already-terminal user_code in this workspace.
       throw new HTTPException(404, {
@@ -331,9 +416,22 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
   // Mint a short-TTL headless enroll token. Mirrors approve (enrollments:manage,
   // requireAccessGrant BEFORE the parse). The accountId comes from the grant. No
   // signing secret → 503/disabled (mirror poll). The token is SECRET — never logged.
+  // `scope: "user"` signs the authenticated person as the machine's owner. Only a
+  // verified person may ask for it: someone signed in, or a credential acting as
+  // them (a personal API key, or an organization key or organization MCP client
+  // acting as that person). A key, service or agent acting as itself gets 422.
+  // The owner is always the caller, never a request field.
   app.post("/v1/workspaces/:workspaceId/enrollments/token", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "enrollments:manage");
+    // The permission is part of the authorization, so a request that lacks it
+    // is refused before any first-use workspace membership is provisioned.
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "enrollments:manage",
+    );
+    const grant = authorization.grant;
     assertSelfhostedEnabled();
     // All fields are optional/defaulted, so an empty POST body is valid (default
     // allowScreenControl=false). Coalesce a missing/empty body to {} before parse.
@@ -343,12 +441,20 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
         message: "invalid mint-enroll-token request",
       });
     }
+    const personal = parsed.data.scope === "user";
+    if (personal && !isPersonalConnectionOwnerPrincipal(authorization)) {
+      throw new HTTPException(422, {
+        message:
+          "only a person, or a credential acting as that person, can connect a machine for themselves; keys, services and agents acting as themselves can connect workspace machines",
+      });
+    }
     const minted = await mintEnrollToken(
       { db, settings },
       {
         accountId: grant.accountId,
         workspaceId,
         allowScreenControl: parsed.data.allowScreenControl,
+        ...(personal ? { ownerSubjectId: grant.subjectId } : {}),
       },
     );
     if (!minted) {
@@ -471,18 +577,6 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
   });
 }
 
-// The remote client IP for the per-IP rate-limit bucket. Honors the proxy's
-// X-Forwarded-For (the first hop) when present, falling back to a constant key when
-// neither is available (the bucket then caps the whole edge — still a useful cap).
-function clientIp(c: Context): string {
-  const xff = c.req.header("x-forwarded-for");
-  if (xff) {
-    const first = xff.split(",")[0]?.trim();
-    if (first) return first;
-  }
-  return c.req.header("x-real-ip")?.trim() || "unknown";
-}
-
 // A minimal per-key token bucket. capacity = burst; refillPerSecond = sustained
 // rate. Buckets are created lazily and reset their tokens by elapsed time on each
 // take, so an idle key fully refills without a background timer.