@opengeni/api-router 0.30.1 → 1.0.0

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,10 +82,15 @@ const ListEditableArtifactsQuery = z
 
 const MintEditableArtifactLiveTicketRequest = z
   .object({
+    sourceSessionId: SessionId.optional(),
     replicaId: ReplicaId,
-    protocolVersion: PositiveProtocolVersion,
+    modality: z.enum(["document", "spreadsheet", "presentation"]),
+    liveProtocolVersion: PositiveProtocolVersion,
     kernelVersion: VersionName,
     modelSchemaVersion: PositiveModelSchemaVersion,
+    snapshotVersion: PositiveProtocolVersion,
+    commandProtocolVersion: PositiveProtocolVersion,
+    committedTransactionProtocolVersion: PositiveProtocolVersion,
   })
   .strict();
 
@@ -467,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);
@@ -475,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 {
@@ -482,10 +510,52 @@ export function registerEditableArtifactRoutes(
         scope,
         actor,
         artifactId,
-        protocolVersion: body.protocolVersion,
+        modality: body.modality,
+        liveProtocolVersion: body.liveProtocolVersion,
         kernelVersion: body.kernelVersion,
         modelSchemaVersion: body.modelSchemaVersion,
+        snapshotVersion: body.snapshotVersion,
+        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);
@@ -496,7 +566,7 @@ export function registerEditableArtifactRoutes(
       !parsedTicket.success ||
       parsedTicket.data.artifactId !== artifactId ||
       parsedTicket.data.replicaId !== actor.replicaId ||
-      parsedTicket.data.protocolVersion !== body.protocolVersion ||
+      parsedTicket.data.protocolVersion !== body.liveProtocolVersion ||
       Date.parse(parsedTicket.data.expiresAt) <= Date.now()
     ) {
       throw new Error("Editable artifact application returned an invalid live ticket");
@@ -608,7 +678,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,
       },
     });
   });
@@ -901,7 +971,7 @@ function normalizeArtifactIdList(value: readonly string[]): readonly string[] {
   return ids;
 }
 
-function isInvisibleListCandidate(error: unknown): boolean {
+export function isInvisibleListCandidate(error: unknown): boolean {
   return (
     (error instanceof EditableArtifactDomainError &&
       (error.code === "forbidden" || error.code === "not_found")) ||
@@ -1042,7 +1112,7 @@ async function readBoundedJson(request: Request, maxBytes: number): Promise<unkn
   }
 }
 
-function editableArtifactHttpError(error: unknown): unknown {
+export function editableArtifactHttpError(error: unknown): unknown {
   if (error instanceof EditableArtifactDurableExportError) {
     switch (error.code) {
       case "invalid_request":
@@ -1059,7 +1129,7 @@ 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,
@@ -50,7 +51,12 @@ import {
 } from "@opengeni/db";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
-import { requireAccessGrant } from "@opengeni/core";
+import { trustedRequestSourceRateLimitKey } from "../http/request-source";
+import {
+  requireAccessGrant,
+  requireAccessGrantAuthorization,
+  requirePermission,
+} from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
   approveDeviceEnrollment,
@@ -60,6 +66,7 @@ import {
   mintEnrollToken,
   pollDeviceEnrollment,
   startDeviceEnrollment,
+  renewEnrollmentCredentials,
   toLookupResponse,
 } from "../sandbox/enrollment";
 
@@ -88,15 +95,33 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
   const lookupLimiter = new TokenBucket({ capacity: 30, refillPerSecond: 1 });
   // The headless token exchange (UNAUTHENTICATED — the token is the auth). Bounded
   // against an enroll-token brute force; the `oget_` HMAC is the real boundary.
-  const exchangeLimiter = new TokenBucket({ capacity: 20, refillPerSecond: 0.5 });
+  const exchangeLimiter = new TokenBucket({
+    capacity: 20,
+    refillPerSecond: 0.5,
+  });
 
   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);
+    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();
@@ -123,8 +148,10 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
         machineName: body.machineName ?? null,
         canOfferDisplay: body.canOfferDisplay,
         requestsScreenControl: body.requestsScreenControl,
-        // The approve page is served at the SAME origin as this request.
-        verificationOrigin: new URL(c.req.url).origin,
+        // Prefer the externally configured deployment origin. Behind a TLS-
+        // terminating proxy c.req.url can carry the internal http scheme, which
+        // must never leak into the device-flow command shown to the operator.
+        verificationOrigin: settings.publicBaseUrl ?? new URL(c.req.url).origin,
       },
     );
     return c.json(result, 201);
@@ -156,7 +183,9 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
     rateLimit(c, lookupLimiter);
     const parsed = DeviceEnrollmentLookupRequest.safeParse(await c.req.json().catch(() => null));
     if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid device-lookup request" });
+      throw new HTTPException(400, {
+        message: "invalid device-lookup request",
+      });
     }
     const record = await lookupDeviceEnrollment(
       { db, settings },
@@ -165,7 +194,9 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!record) {
       // Unknown / terminal / expired code → 404 (indistinguishable from an
       // unauthorized one below, by design).
-      throw new HTTPException(404, { message: "no pending enrollment for that code" });
+      throw new HTTPException(404, {
+        message: "no pending enrollment for that code",
+      });
     }
     // Authorize the caller against the RESOLVED workspace. A missing grant throws
     // 403/404 from requireAccessGrant; we normalize that to 404 so a caller cannot
@@ -173,7 +204,9 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
     try {
       await requireAccessGrant(c, deps, record.workspaceId, "enrollments:read");
     } catch {
-      throw new HTTPException(404, { message: "no pending enrollment for that code" });
+      throw new HTTPException(404, {
+        message: "no pending enrollment for that code",
+      });
     }
     return c.json(DeviceEnrollmentLookupResponse.parse(toLookupResponse(record)), 200);
   });
@@ -189,7 +222,9 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
     rateLimit(c, exchangeLimiter);
     const parsed = EnrollTokenExchangeRequest.safeParse(await c.req.json().catch(() => null));
     if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid enroll-token-exchange request" });
+      throw new HTTPException(400, {
+        message: "invalid enroll-token-exchange request",
+      });
     }
     const body = parsed.data;
     const result = await exchangeEnrollToken(
@@ -206,10 +241,14 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!result.ok) {
       if (result.reason === "disabled") {
         // The credential plane is off for this deployment (no signing secret).
-        throw new HTTPException(503, { message: "enrollment credential plane is not configured" });
+        throw new HTTPException(503, {
+          message: "enrollment credential plane is not configured",
+        });
       }
       // An invalid / expired / wrong-typ token — the token is the auth, so 401.
-      throw new HTTPException(401, { message: "invalid or expired enroll token" });
+      throw new HTTPException(401, {
+        message: "invalid or expired enroll token",
+      });
     }
     return c.json(EnrollTokenExchangeResponse.parse({ credentials: result.credentials }), 201);
   });
@@ -218,18 +257,48 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
   // The LOUD CONSENT step. requireAccessGrant BEFORE the Zod parse.
   app.post("/v1/workspaces/:workspaceId/enrollments/device/approve", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "enrollments:manage");
+    const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+    const grant = authorization.grant;
+    requirePermission(grant, "enrollments:manage");
     assertSelfhostedEnabled();
-    const parsed = DeviceEnrollmentApproveRequest.safeParse(await c.req.json().catch(() => null));
+    const rawBody = await c.req.json().catch(() => null);
+    const parsed = DeviceEnrollmentApproveRequest.safeParse(rawBody);
     if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid device-approve request" });
+      throw new HTTPException(400, {
+        message: "invalid device-approve request",
+      });
     }
     const body = parsed.data;
+    const scopeWasExplicit =
+      typeof rawBody === "object" &&
+      rawBody !== null &&
+      Object.prototype.hasOwnProperty.call(rawBody, "scope");
+    // Managed browser humans get the personal default. Legacy/delegated
+    // principals predate organization-user ownership and retain the compatible
+    // workspace default when the caller omitted scope; an explicit scope is
+    // never silently rewritten.
+    const effectiveScope =
+      scopeWasExplicit ||
+      (grant.principalKind === "human_session" &&
+        authorization.contextIntegrity &&
+        grant.metadata?.delegated !== true)
+        ? body.scope
+        : undefined;
+    const allowOrganization =
+      effectiveScope === "organization" &&
+      authorization.accountGrant?.permissions.includes("account:admin") === true;
+    if (effectiveScope === "organization" && !allowOrganization) {
+      throw new HTTPException(403, {
+        message: "missing permission: account:admin",
+      });
+    }
     const approved = await approveDeviceEnrollment(
       { db, settings },
       {
         accountId: grant.accountId,
         workspaceId,
+        ...(effectiveScope ? { scope: effectiveScope } : {}),
+        allowOrganization,
         userCode: body.userCode,
         allowScreenControl: body.allowScreenControl,
         // The LOUD consent record: WHO consented (the authenticated subject + label).
@@ -239,7 +308,9 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
     if (!approved) {
       // An unknown / expired / already-terminal user_code in this workspace.
-      throw new HTTPException(404, { message: "no pending enrollment for that code" });
+      throw new HTTPException(404, {
+        message: "no pending enrollment for that code",
+      });
     }
     return c.json(
       DeviceEnrollmentApproveResponse.parse({
@@ -286,7 +357,9 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
     // allowScreenControl=false). Coalesce a missing/empty body to {} before parse.
     const parsed = MintEnrollTokenRequest.safeParse(await c.req.json().catch(() => ({})));
     if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid mint-enroll-token request" });
+      throw new HTTPException(400, {
+        message: "invalid mint-enroll-token request",
+      });
     }
     const minted = await mintEnrollToken(
       { db, settings },
@@ -298,7 +371,9 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
     if (!minted) {
       // The credential plane is off (no signing secret) — mirror poll's disabled path.
-      throw new HTTPException(503, { message: "enrollment credential plane is not configured" });
+      throw new HTTPException(503, {
+        message: "enrollment credential plane is not configured",
+      });
     }
     return c.json(MintEnrollTokenResponse.parse(minted), 201);
   });
@@ -306,13 +381,15 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
   // ── GET /workspaces/:workspaceId/enrollments (user-authed) ──────────────────
   app.get("/v1/workspaces/:workspaceId/enrollments", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "enrollments:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "enrollments:read");
     assertSelfhostedEnabled();
     const statusFilter = c.req.query("status");
     if (statusFilter !== undefined && statusFilter !== "active" && statusFilter !== "revoked") {
-      throw new HTTPException(400, { message: "status must be active or revoked" });
+      throw new HTTPException(400, {
+        message: "status must be active or revoked",
+      });
     }
-    const rows = await listEnrollments(db, workspaceId, {
+    const rows = await listEnrollments(db, grant, {
       status: statusFilter === "revoked" ? "revoked" : "active",
     });
     return c.json(
@@ -320,6 +397,8 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
         enrollments: rows.map((row) =>
           EnrollmentSummary.parse({
             id: row.id,
+            scope: row.scope,
+            generation: row.generation,
             pubkey: row.pubkey,
             exposure: row.exposure,
             hasDisplay: row.hasDisplay,
@@ -340,19 +419,40 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
   // ── POST /workspaces/:workspaceId/enrollments/:id/revoke (user-authed) ──────
   app.post("/v1/workspaces/:workspaceId/enrollments/:enrollmentId/revoke", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "enrollments:manage");
+    const authorization = await requireAccessGrantAuthorization(c, deps, workspaceId);
+    const grant = authorization.grant;
+    requirePermission(grant, "enrollments:manage");
     assertSelfhostedEnabled();
     const parsed = RemoveEnrollmentRequest.safeParse(await c.req.json().catch(() => ({})));
     if (!parsed.success) {
-      throw new HTTPException(400, { message: "invalid machine removal request" });
+      throw new HTTPException(400, {
+        message: "invalid machine removal request",
+      });
     }
     const idempotencyKey =
       parsed.data.idempotencyKey?.trim() || c.req.header("idempotency-key")?.trim() || randomUUID();
     try {
+      const enrollmentId = c.req.param("enrollmentId");
+      const enrollment = (await listEnrollments(db, grant, { status: "active" })).find(
+        (candidate) => candidate.id === enrollmentId,
+      );
+      if (!enrollment) {
+        throw new HTTPException(404, {
+          message: "machine enrollment not found",
+        });
+      }
+      if (
+        enrollment.scope === "organization" &&
+        authorization.accountGrant?.permissions.includes("account:admin") !== true
+      ) {
+        throw new HTTPException(403, {
+          message: "missing permission: account:admin",
+        });
+      }
       const result = await removeEnrollment(db, {
         accountId: grant.accountId,
-        workspaceId,
-        enrollmentId: c.req.param("enrollmentId"),
+        workspaceId: enrollment.workspaceId,
+        enrollmentId,
         operationKey: idempotencyKey,
         ...(parsed.data.expectedUpdatedAt
           ? { expectedUpdatedAt: parsed.data.expectedUpdatedAt }
@@ -360,7 +460,9 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
         subjectId: grant.subjectId,
       });
       if (!result) {
-        throw new HTTPException(404, { message: "machine enrollment not found" });
+        throw new HTTPException(404, {
+          message: "machine enrollment not found",
+        });
       }
       return c.json(
         RevokeEnrollmentResponse.parse({
@@ -376,7 +478,10 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
       if (error instanceof MachineRemovalRevisionConflictError) {
         throw new HTTPException(409, {
           message: error.message,
-          cause: { code: "stale_revision", currentUpdatedAt: error.currentUpdatedAt },
+          cause: {
+            code: "stale_revision",
+            currentUpdatedAt: error.currentUpdatedAt,
+          },
         });
       }
       throw error;
@@ -384,18 +489,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.
@@ -410,7 +503,10 @@ class TokenBucket {
   }
 
   take(key: string, now = Date.now()): boolean {
-    const bucket = this.buckets.get(key) ?? { tokens: this.capacity, updatedAt: now };
+    const bucket = this.buckets.get(key) ?? {
+      tokens: this.capacity,
+      updatedAt: now,
+    };
     const elapsedSeconds = Math.max(0, (now - bucket.updatedAt) / 1000);
     bucket.tokens = Math.min(this.capacity, bucket.tokens + elapsedSeconds * this.refillPerSecond);
     bucket.updatedAt = now;