@opengeni/api-router 0.2.0

package/src/routes/enrollments.ts

@@ -0,0 +1,357 @@
+// apps/api/src/routes/enrollments.ts — the bring-your-own-compute enrollment
+// device-flow routes (M5; dossier §10.2 + §18). Mirrors the other sandbox route
+// modules (registerSessionRoutes / registerApiKeyRoutes): a thin route over a
+// focused service (../sandbox/enrollment.ts), requireAccessGrant BEFORE any Zod
+// parse on the USER-authenticated routes, explicit HTTPException(400) on a parse
+// failure (never a raw ZodError → 500), and the whole router gated behind
+// sandboxSelfhostedEnabled (default OFF → every route 404s, invisible).
+//
+// AUTH SEAM (the device-flow split):
+//   * device/start + device/poll are AGENT-side — user-UNAUTHENTICATED (the agent
+//     has no logged-in browser session; it presents only the deployment access key
+//     the app.use("*", requireAccessKey) edge already enforces). They are
+//     IP-rate-limited here. They DO NOT call requireAccessGrant.
+//   * device/approve + GET /enrollments + revoke are USER-authenticated +
+//     workspace-gated via requireAccessGrant (enrollments:manage / enrollments:read;
+//     workspace:admin is the super-wildcard).
+//
+// The cross-workspace safety of an unauthenticated start: start binds the request
+// to a workspaceId the agent supplies, and ONLY a user holding a grant in THAT
+// workspace can approve it (the approve's user_code lookup is workspace-scoped) — a
+// start can never grant access to a workspace no authorized user later approves in.
+
+import {
+  DeviceEnrollmentApproveRequest,
+  DeviceEnrollmentApproveResponse,
+  DeviceEnrollmentDenyRequest,
+  DeviceEnrollmentDenyResponse,
+  DeviceEnrollmentLookupRequest,
+  DeviceEnrollmentLookupResponse,
+  DeviceEnrollmentPollRequest,
+  DeviceEnrollmentStartRequest,
+  EnrollmentSummary,
+  EnrollTokenExchangeRequest,
+  EnrollTokenExchangeResponse,
+  ListEnrollmentsResponse,
+  MintEnrollTokenRequest,
+  MintEnrollTokenResponse,
+  RevokeEnrollmentResponse,
+  type EnrollmentArch,
+  type EnrollmentOs,
+} from "@opengeni/contracts";
+import {
+  getWorkspace,
+  listEnrollments,
+  revokeEnrollment,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { requireAccessGrant } from "@opengeni/core";
+import type { ApiRouteDeps } from "@opengeni/core";
+import {
+  approveDeviceEnrollment,
+  denyDeviceEnrollment,
+  exchangeEnrollToken,
+  lookupDeviceEnrollment,
+  mintEnrollToken,
+  pollDeviceEnrollment,
+  startDeviceEnrollment,
+  toLookupResponse,
+} from "../sandbox/enrollment";
+
+export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const { settings, db } = deps;
+
+  // The whole feature is behind sandboxSelfhostedEnabled. A 404 (not 403) keeps the
+  // surface invisible while disabled — it does not exist for this deployment yet.
+  function assertSelfhostedEnabled(): void {
+    if (!settings.sandboxSelfhostedEnabled) {
+      throw new HTTPException(404, { message: "selfhosted enrollment is not enabled for this deployment" });
+    }
+  }
+
+  // A tiny in-process IP token-bucket for the UNAUTHENTICATED agent routes (start/
+  // poll). The relay tier owns the heavy stream rate-limiting (dossier §10.5); 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.
+  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
+  // user_code brute force — the lookup resolves a workspace from a short code).
+  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 });
+
+  function rateLimit(c: Context, limiter: TokenBucket): void {
+    const ip = clientIp(c);
+    if (!limiter.take(ip)) {
+      throw new HTTPException(429, { message: "too many requests; slow down" });
+    }
+  }
+
+  // ── POST /enrollments/device/start (agent-side, user-unauthenticated) ───────
+  app.post("/v1/enrollments/device/start", async (c) => {
+    assertSelfhostedEnabled();
+    rateLimit(c, startLimiter);
+    const parsed = DeviceEnrollmentStartRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "invalid device-start request" });
+    }
+    const body = parsed.data;
+    // Resolve the (account) for the supplied workspace. An unknown workspace is a
+    // 404 (the same shape requireAccessGrant uses for an unknown workspace).
+    const workspace = await getWorkspace(db, body.workspaceId);
+    if (!workspace) {
+      throw new HTTPException(404, { message: "workspace not found" });
+    }
+    const result = await startDeviceEnrollment({ db, settings }, {
+      accountId: workspace.accountId,
+      workspaceId: workspace.id,
+      publicKey: body.publicKey,
+      os: body.os as EnrollmentOs,
+      arch: body.arch as EnrollmentArch,
+      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,
+    });
+    return c.json(result, 201);
+  });
+
+  // ── POST /enrollments/device/poll (agent-side, user-unauthenticated) ────────
+  app.post("/v1/enrollments/device/poll", async (c) => {
+    assertSelfhostedEnabled();
+    rateLimit(c, pollLimiter);
+    const parsed = DeviceEnrollmentPollRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "invalid device-poll request" });
+    }
+    const result = await pollDeviceEnrollment({ db, settings }, { deviceCode: parsed.data.deviceCode });
+    return c.json(result, 200);
+  });
+
+  // ── POST /enrollments/device/lookup (user-authed, NO workspace in path) ─────
+  // The click-Grant approve page reads machine details for a user_code WITHOUT
+  // consuming it. The user_code is globally unique among pending rows; we resolve
+  // its workspace, then assert the caller holds enrollments:read in THAT workspace.
+  // A failed grant OR no live pending row both → 404 (never reveal cross-workspace
+  // existence). Rate-limited against a user_code brute force.
+  app.post("/v1/enrollments/device/lookup", async (c) => {
+    assertSelfhostedEnabled();
+    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" });
+    }
+    const record = await lookupDeviceEnrollment({ db, settings }, { userCode: parsed.data.userCode });
+    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" });
+    }
+    // Authorize the caller against the RESOLVED workspace. A missing grant throws
+    // 403/404 from requireAccessGrant; we normalize that to 404 so a caller cannot
+    // distinguish "code exists in a workspace I can't see" from "no such code".
+    try {
+      await requireAccessGrant(c, deps, record.workspaceId, "enrollments:read");
+    } catch {
+      throw new HTTPException(404, { message: "no pending enrollment for that code" });
+    }
+    return c.json(DeviceEnrollmentLookupResponse.parse(toLookupResponse(record)), 200);
+  });
+
+  // ── POST /enrollments/token/exchange (UNAUTHENTICATED — the token is the auth) ─
+  // The headless / fleet enroll path. The agent presents the same identity fields
+  // it sends to device/start plus the `oget_` enroll token. The token IS the grant
+  // (no human approve). On a valid token we perform the SAME finalize as approve and
+  // return the IDENTICAL EnrollmentCredentials shape the poll authorized branch
+  // returns. Rate-limited against an enroll-token brute force.
+  app.post("/v1/enrollments/token/exchange", async (c) => {
+    assertSelfhostedEnabled();
+    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" });
+    }
+    const body = parsed.data;
+    const result = await exchangeEnrollToken({ db, settings }, {
+      token: body.token,
+      publicKey: body.publicKey,
+      os: body.os as EnrollmentOs,
+      arch: body.arch as EnrollmentArch,
+      machineName: body.machineName ?? null,
+      canOfferDisplay: body.canOfferDisplay,
+    });
+    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" });
+      }
+      // An invalid / expired / wrong-typ token — the token is the auth, so 401.
+      throw new HTTPException(401, { message: "invalid or expired enroll token" });
+    }
+    return c.json(EnrollTokenExchangeResponse.parse({ credentials: result.credentials }), 201);
+  });
+
+  // ── POST /workspaces/:workspaceId/enrollments/device/approve (user-authed) ──
+  // 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");
+    assertSelfhostedEnabled();
+    const parsed = DeviceEnrollmentApproveRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "invalid device-approve request" });
+    }
+    const body = parsed.data;
+    const approved = await approveDeviceEnrollment({ db, settings }, {
+      accountId: grant.accountId,
+      workspaceId,
+      userCode: body.userCode,
+      allowScreenControl: body.allowScreenControl,
+      // The LOUD consent record: WHO consented (the authenticated subject + label).
+      approvedBySubjectId: grant.subjectId,
+      approvedBySubjectLabel: grant.subjectLabel ?? null,
+    });
+    if (!approved) {
+      // An unknown / expired / already-terminal user_code in this workspace.
+      throw new HTTPException(404, { message: "no pending enrollment for that code" });
+    }
+    return c.json(DeviceEnrollmentApproveResponse.parse({
+      approved: true,
+      enrollmentId: approved.enrollmentId,
+      sandboxId: approved.sandboxId,
+      allowScreenControl: approved.allowScreenControl,
+    }), 201);
+  });
+
+  // ── POST /workspaces/:workspaceId/enrollments/device/deny (user-authed) ─────
+  // The explicit "no" at the approve page. Mirrors approve (enrollments:manage,
+  // requireAccessGrant BEFORE the parse). Idempotent: a non-pending code → denied:false.
+  app.post("/v1/workspaces/:workspaceId/enrollments/device/deny", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "enrollments:manage");
+    assertSelfhostedEnabled();
+    const parsed = DeviceEnrollmentDenyRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "invalid device-deny request" });
+    }
+    const result = await denyDeviceEnrollment({ db, settings }, {
+      accountId: grant.accountId,
+      workspaceId,
+      userCode: parsed.data.userCode,
+    });
+    return c.json(DeviceEnrollmentDenyResponse.parse({ denied: result.denied }), 200);
+  });
+
+  // ── POST /workspaces/:workspaceId/enrollments/token (user-authed) ───────────
+  // 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.
+  app.post("/v1/workspaces/:workspaceId/enrollments/token", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "enrollments:manage");
+    assertSelfhostedEnabled();
+    // All fields are optional/defaulted, so an empty POST body is valid (default
+    // 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" });
+    }
+    const minted = await mintEnrollToken({ db, settings }, {
+      accountId: grant.accountId,
+      workspaceId,
+      allowScreenControl: parsed.data.allowScreenControl,
+    });
+    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" });
+    }
+    return c.json(MintEnrollTokenResponse.parse(minted), 201);
+  });
+
+  // ── 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");
+    assertSelfhostedEnabled();
+    const statusFilter = c.req.query("status");
+    const rows = await listEnrollments(db, workspaceId, statusFilter === "active" ? { status: "active" } : {});
+    return c.json(ListEnrollmentsResponse.parse({
+      enrollments: rows.map((row) => EnrollmentSummary.parse({
+        id: row.id,
+        pubkey: row.pubkey,
+        exposure: row.exposure,
+        hasDisplay: row.hasDisplay,
+        allowScreenControl: row.allowScreenControl,
+        status: row.status,
+        os: row.os,
+        arch: row.arch,
+        lastSeenAt: row.lastSeenAt,
+        createdAt: row.createdAt,
+        revokedAt: row.revokedAt,
+      })),
+    }));
+  });
+
+  // ── 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");
+    assertSelfhostedEnabled();
+    const result = await revokeEnrollment(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      enrollmentId: c.req.param("enrollmentId"),
+    });
+    return c.json(RevokeEnrollmentResponse.parse(result));
+  });
+}
+
+// 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.
+class TokenBucket {
+  private readonly capacity: number;
+  private readonly refillPerSecond: number;
+  private readonly buckets = new Map<string, { tokens: number; updatedAt: number }>();
+
+  constructor(options: { capacity: number; refillPerSecond: number }) {
+    this.capacity = options.capacity;
+    this.refillPerSecond = options.refillPerSecond;
+  }
+
+  take(key: string, now = Date.now()): boolean {
+    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;
+    // Prune the map opportunistically so it never grows unbounded: a fully-refilled
+    // bucket carries no state worth keeping.
+    if (bucket.tokens >= this.capacity && this.buckets.size > 10_000) {
+      this.buckets.delete(key);
+    }
+    if (bucket.tokens < 1) {
+      this.buckets.set(key, bucket);
+      return false;
+    }
+    bucket.tokens -= 1;
+    this.buckets.set(key, bucket);
+    return true;
+  }
+}

package/src/routes/environments.ts

@@ -0,0 +1,175 @@
+import {
+  CreateWorkspaceEnvironmentRequest,
+  SetWorkspaceEnvironmentVariableRequest,
+  UpdateWorkspaceEnvironmentRequest,
+  WorkspaceEnvironmentVariableName,
+} from "@opengeni/contracts";
+import {
+  countActiveSessionsUsingEnvironment,
+  countScheduledTasksUsingEnvironment,
+  countWorkspaceEnvironments,
+  createWorkspaceEnvironment,
+  deleteWorkspaceEnvironment,
+  deleteWorkspaceEnvironmentVariable,
+  encryptEnvironmentValue,
+  getWorkspaceEnvironmentByName,
+  listWorkspaceEnvironments,
+  setWorkspaceEnvironmentVariable,
+  updateWorkspaceEnvironment,
+} from "@opengeni/db";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { requireAccessGrant } from "@opengeni/core";
+import type { ApiRouteDeps } from "@opengeni/core";
+import {
+  assertAllowedEnvironmentVariableName,
+  MAX_ENVIRONMENTS_PER_WORKSPACE,
+  MAX_VARIABLES_PER_ENVIRONMENT,
+  recordEnvironmentAuditEvent,
+  requireEnvironmentEncryption,
+  requireEnvironmentForApi,
+} from "@opengeni/core";
+
+export function registerEnvironmentRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const { settings, db } = deps;
+
+  app.get("/v1/workspaces/:workspaceId/environments", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "environments:use");
+    return c.json(await listWorkspaceEnvironments(db, workspaceId));
+  });
+
+  app.post("/v1/workspaces/:workspaceId/environments", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "environments:manage");
+    const key = requireEnvironmentEncryption(settings);
+    const payload = CreateWorkspaceEnvironmentRequest.parse(await c.req.json());
+    const name = trimmedEnvironmentName(payload.name);
+    if (payload.variables.length > MAX_VARIABLES_PER_ENVIRONMENT) {
+      throw new HTTPException(422, { message: `an environment supports at most ${MAX_VARIABLES_PER_ENVIRONMENT} variables` });
+    }
+    const variableNames = new Set<string>();
+    for (const variable of payload.variables) {
+      assertAllowedEnvironmentVariableName(variable.name);
+      if (variableNames.has(variable.name)) {
+        throw new HTTPException(422, { message: `duplicate environment variable name: ${variable.name}` });
+      }
+      variableNames.add(variable.name);
+    }
+    if (await countWorkspaceEnvironments(db, workspaceId) >= MAX_ENVIRONMENTS_PER_WORKSPACE) {
+      throw new HTTPException(422, { message: `a workspace supports at most ${MAX_ENVIRONMENTS_PER_WORKSPACE} environments` });
+    }
+    if (await getWorkspaceEnvironmentByName(db, workspaceId, name)) {
+      throw new HTTPException(409, { message: `environment name is already in use: ${name}` });
+    }
+    // Values are encrypted up front and the environment plus all initial
+    // variables are written in one transaction: a failure leaves nothing.
+    const created = await createWorkspaceEnvironment(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      name,
+      description: payload.description ?? null,
+      variables: payload.variables.map((variable) => ({
+        name: variable.name,
+        valueEncrypted: encryptEnvironmentValue(key, variable.value),
+      })),
+    });
+    await recordEnvironmentAuditEvent(db, { grant, action: "environment.created", environmentId: created.id });
+    return c.json(created, 201);
+  });
+
+  app.get("/v1/workspaces/:workspaceId/environments/:environmentId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "environments:use");
+    return c.json(await requireEnvironmentForApi(db, workspaceId, c.req.param("environmentId")));
+  });
+
+  app.patch("/v1/workspaces/:workspaceId/environments/:environmentId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "environments:manage");
+    const environment = await requireEnvironmentForApi(db, workspaceId, c.req.param("environmentId"));
+    const payload = UpdateWorkspaceEnvironmentRequest.parse(await c.req.json());
+    const name = payload.name !== undefined ? trimmedEnvironmentName(payload.name) : undefined;
+    if (name !== undefined && name !== environment.name) {
+      const existing = await getWorkspaceEnvironmentByName(db, workspaceId, name);
+      if (existing && existing.id !== environment.id) {
+        throw new HTTPException(409, { message: `environment name is already in use: ${name}` });
+      }
+    }
+    const updated = await updateWorkspaceEnvironment(db, workspaceId, environment.id, {
+      ...(name !== undefined ? { name } : {}),
+      ...(payload.description !== undefined ? { description: payload.description } : {}),
+    });
+    await recordEnvironmentAuditEvent(db, { grant, action: "environment.updated", environmentId: environment.id });
+    return c.json(updated);
+  });
+
+  app.delete("/v1/workspaces/:workspaceId/environments/:environmentId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "environments:manage");
+    const environment = await requireEnvironmentForApi(db, workspaceId, c.req.param("environmentId"));
+    const attachedTasks = await countScheduledTasksUsingEnvironment(db, workspaceId, environment.id);
+    if (attachedTasks > 0) {
+      throw new HTTPException(409, { message: `environment is attached to ${attachedTasks} scheduled task(s); detach first` });
+    }
+    const activeSessions = await countActiveSessionsUsingEnvironment(db, workspaceId, environment.id);
+    if (activeSessions > 0) {
+      throw new HTTPException(409, { message: `environment is attached to ${activeSessions} active session(s); wait for them to finish or cancel them first` });
+    }
+    await deleteWorkspaceEnvironment(db, workspaceId, environment.id);
+    await recordEnvironmentAuditEvent(db, { grant, action: "environment.deleted", environmentId: environment.id });
+    return c.json({ ok: true });
+  });
+
+  app.put("/v1/workspaces/:workspaceId/environments/:environmentId/variables/:name", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "environments:manage");
+    const key = requireEnvironmentEncryption(settings);
+    const name = parseVariableName(c.req.param("name"));
+    const environment = await requireEnvironmentForApi(db, workspaceId, c.req.param("environmentId"));
+    const payload = SetWorkspaceEnvironmentVariableRequest.parse(await c.req.json());
+    const exists = environment.variables.some((variable) => variable.name === name);
+    if (!exists && environment.variables.length >= MAX_VARIABLES_PER_ENVIRONMENT) {
+      throw new HTTPException(422, { message: `an environment supports at most ${MAX_VARIABLES_PER_ENVIRONMENT} variables` });
+    }
+    const metadata = await setWorkspaceEnvironmentVariable(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      environmentId: environment.id,
+      name,
+      valueEncrypted: encryptEnvironmentValue(key, payload.value),
+    });
+    await recordEnvironmentAuditEvent(db, { grant, action: "environment.variable.set", environmentId: environment.id, variableName: name });
+    return c.json(metadata);
+  });
+
+  app.delete("/v1/workspaces/:workspaceId/environments/:environmentId/variables/:name", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "environments:manage");
+    const name = parseVariableName(c.req.param("name"));
+    const environment = await requireEnvironmentForApi(db, workspaceId, c.req.param("environmentId"));
+    const deleted = await deleteWorkspaceEnvironmentVariable(db, workspaceId, environment.id, name);
+    if (!deleted) {
+      throw new HTTPException(404, { message: "environment variable not found" });
+    }
+    await recordEnvironmentAuditEvent(db, { grant, action: "environment.variable.deleted", environmentId: environment.id, variableName: name });
+    return c.json({ ok: true });
+  });
+}
+
+function parseVariableName(raw: string): string {
+  const parsed = WorkspaceEnvironmentVariableName.safeParse(raw);
+  if (!parsed.success) {
+    throw new HTTPException(422, { message: "environment variable names must match ^[A-Z][A-Z0-9_]*$" });
+  }
+  assertAllowedEnvironmentVariableName(parsed.data);
+  return parsed.data;
+}
+
+function trimmedEnvironmentName(name: string): string {
+  const trimmed = name.trim();
+  if (!trimmed) {
+    throw new HTTPException(422, { message: "environment name is required" });
+  }
+  return trimmed;
+}

package/src/routes/files.ts

@@ -0,0 +1,148 @@
+import {
+  CompleteFileUploadResponse,
+  CreateFileUploadRequest,
+  CreateFileUploadResponse,
+  FileAsset,
+  FileDownloadUrlResponse,
+} from "@opengeni/contracts";
+import {
+  completeFileUpload,
+  createFileUpload,
+  getFileUpload,
+  markFileUploadFailed,
+  requireFile,
+} from "@opengeni/db";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { requireAccessGrant } from "@opengeni/core";
+import { recordWorkspaceUsage, requireLimit } from "@opengeni/core";
+import type { ApiRouteDeps } from "@opengeni/core";
+
+export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const { db, objectStorage } = deps;
+
+  app.post("/v1/workspaces/:workspaceId/files/uploads", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:upload");
+    if (!objectStorage) {
+      throw new HTTPException(503, { message: "object storage is not configured" });
+    }
+    const payload = CreateFileUploadRequest.parse(await c.req.json());
+    await requireLimit(deps, { accountId: grant.accountId, workspaceId, action: "file:upload", quantity: payload.sizeBytes });
+    if (payload.sizeBytes > objectStorage.maxSinglePutSizeBytes) {
+      throw new HTTPException(413, { message: `file exceeds single PUT limit of ${objectStorage.maxSinglePutSizeBytes} bytes` });
+    }
+    const fileId = crypto.randomUUID();
+    const safeFilename = sanitizeFilename(payload.filename);
+    const objectKey = `workspaces/${workspaceId}/files/${fileId}/original/${safeFilename}`;
+    const signed = await objectStorage.createPutUrl({
+      key: objectKey,
+      contentType: payload.contentType,
+      ...(payload.sha256 ? { sha256: payload.sha256 } : {}),
+    });
+    const upload = await createFileUpload(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      fileId,
+      filename: payload.filename,
+      safeFilename,
+      contentType: payload.contentType,
+      sizeBytes: payload.sizeBytes,
+      sha256: payload.sha256 ?? null,
+      bucket: objectStorage.bucket,
+      objectKey,
+      expiresAt: signed.expiresAt,
+    });
+    return c.json(CreateFileUploadResponse.parse({
+      fileId: upload.file.id,
+      uploadId: upload.uploadId,
+      putUrl: signed.url,
+      requiredHeaders: signed.requiredHeaders,
+      expiresAt: upload.expiresAt,
+      maxSizeBytes: objectStorage.maxSinglePutSizeBytes,
+    }), 201);
+  });
+
+  app.post("/v1/workspaces/:workspaceId/files/uploads/:uploadId/complete", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:upload");
+    if (!objectStorage) {
+      throw new HTTPException(503, { message: "object storage is not configured" });
+    }
+    const upload = await getFileUpload(db, workspaceId, c.req.param("uploadId"));
+    if (!upload) {
+      throw new HTTPException(404, { message: "file upload not found" });
+    }
+    if (upload.status !== "pending") {
+      throw new HTTPException(409, { message: `file upload is ${upload.status}` });
+    }
+    if (upload.expiresAt.getTime() < Date.now()) {
+      await markFileUploadFailed(db, workspaceId, upload.id, upload.file.id);
+      throw new HTTPException(409, { message: "file upload has expired" });
+    }
+    const head = await objectStorage.headFile(upload.file).catch((error) => {
+      throw new HTTPException(409, { message: `uploaded object is not available: ${error instanceof Error ? error.message : String(error)}` });
+    });
+    if (Number(head.ContentLength ?? -1) !== upload.file.sizeBytes) {
+      await markFileUploadFailed(db, workspaceId, upload.id, upload.file.id);
+      throw new HTTPException(422, { message: "uploaded object size does not match file metadata" });
+    }
+    if (upload.file.contentType && head.ContentType && head.ContentType !== upload.file.contentType) {
+      await markFileUploadFailed(db, workspaceId, upload.id, upload.file.id);
+      throw new HTTPException(422, { message: "uploaded object content type does not match file metadata" });
+    }
+    if (upload.file.sha256 && head.Metadata?.sha256 !== upload.file.sha256) {
+      await markFileUploadFailed(db, workspaceId, upload.id, upload.file.id);
+      throw new HTTPException(422, { message: "uploaded object checksum metadata does not match file metadata" });
+    }
+    const file = await completeFileUpload(db, workspaceId, upload.id);
+    await recordWorkspaceUsage(deps, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      eventType: "file.uploaded",
+      quantity: file.sizeBytes,
+      unit: "byte",
+      sourceResourceType: "file",
+      sourceResourceId: file.id,
+      idempotencyKey: `file.uploaded:${workspaceId}:${file.id}`,
+    });
+    return c.json(CompleteFileUploadResponse.parse({ file }));
+  });
+
+  app.get("/v1/workspaces/:workspaceId/files/:fileId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const file = await requireFile(db, workspaceId, c.req.param("fileId")).catch(() => null);
+    if (!file) {
+      throw new HTTPException(404, { message: "file not found" });
+    }
+    return c.json(FileAsset.parse(file));
+  });
+
+  app.post("/v1/workspaces/:workspaceId/files/:fileId/download-url", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    if (!objectStorage) {
+      throw new HTTPException(503, { message: "object storage is not configured" });
+    }
+    const file = await requireFile(db, workspaceId, c.req.param("fileId")).catch(() => null);
+    if (!file) {
+      throw new HTTPException(404, { message: "file not found" });
+    }
+    if (file.status !== "ready") {
+      throw new HTTPException(409, { message: `file is ${file.status}` });
+    }
+    const signed = await objectStorage.createGetUrl({ key: file.objectKey });
+    return c.json(FileDownloadUrlResponse.parse({
+      url: signed.url,
+      expiresAt: signed.expiresAt.toISOString(),
+    }));
+  });
+}
+
+function sanitizeFilename(filename: string): string {
+  const trimmed = filename.trim().replace(/[/\\]/g, "_");
+  const safe = trimmed.replace(/[^A-Za-z0-9._ -]+/g, "_").replace(/\s+/g, " ").trim();
+  return safe || "file";
+}