Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

71.2 KB
Raw Blame
import { externalAppSharingAllowed } from "../../feature-flags.ts";
import { DeployAccessError, type DeployAccessErrorCode } from "../../deploy/deploy-service.ts";
import { SocksProxyAgent } from "socks-proxy-agent";
import { request as httpRequest } from "node:http";
import { request as httpsRequest } from "node:https";
import {
  connect as connectHttp2,
  constants as http2Constants,
  type ClientHttp2Session,
  type ClientHttp2Stream,
  type OutgoingHttpHeaders,
} from "node:http2";
import { spawn } from "node:child_process";
import { basename, dirname } from "node:path";
import { deploymentView, type App, type DeployInput, type RedeployInput } from "../app.ts";
import { errMessage, reportFailureAs, swallowAs } from "../../util/errors.ts";
import { escapeHtml } from "../../../plugins/chassis/src/http.ts";
import { canonicalPayload } from "../../../plugins/chassis/src/source-auth-sign.ts";
import { sendJson, verifyOrReject } from "../http.ts";
import { mintPortalIdentity, verifyPortalIdentity, PORTAL_IDENTITY_HEADER } from "../../auth/portal-identity.ts";
import { audit, authorizeAdmin, isObj, orgScope } from "./shared.ts";
import { parseScopeId, scopeId, type Permission } from "../../types.ts";
import type { ApiCtx, BaseCtx, Route } from "./route.ts";
import { CONFIG_DEFAULTS } from "../../config.ts";
import { resolveShareTarget as resolveShareTargetGrammar } from "../artifact-share.ts";
import { verifyDeployGitAccess, viewerIdentityKey } from "../../deploy/access-token.ts";
import { appAnnotationAsset } from "../../deploy/app-annotate.ts";
import { APP_SHELL_PATH_PREFIX, appShellHtml } from "../../deploy/app-shell.ts";
import type { AppViewAuthMode } from "../../deploy/page-views.ts";
import { principalDestination } from "../../reach/reach.ts";
import { FRAME_SESSION_COOKIE, portalSession, portalSessionFrom } from "../../deploy/viewer-session.ts";
import { EMBED_ANCESTORS_HINT, parseEmbedAncestors } from "../../deploy/embed-ancestors.ts";
import { proxyHeaders } from "../../util/http-proxy.ts";

function deploymentProxyAgent(port?: number): { agent?: SocksProxyAgent } {
  if (port === undefined) return {};
  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error("Invalid deployment SOCKS port");
  return { agent: new SocksProxyAgent(`socks5h://127.0.0.1:${port}`, { keepAlive: false }) };
}

const isStringRecord = (v: unknown): v is Record<string, string> =>
  isObj(v) && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");

function isRedeployInput(b: unknown): b is RedeployInput {
  return (
    isObj(b) &&
    typeof b.entrypoint === "string" &&
    Array.isArray(b.files) &&
    (b.homeFiles === undefined || Array.isArray(b.homeFiles)) &&
    (b.env === undefined || isStringRecord(b.env)) &&
    b.stampEnv === undefined &&
    (b.alwaysOn === undefined || typeof b.alwaysOn === "boolean")
  );
}

function isDeployInput(b: unknown): b is DeployInput {
  return isObj(b) && typeof b.ownerScopeId === "string" && typeof b.createdBy === "string" && isRedeployInput(b);
}

async function proxyDeployment(ctx: BaseCtx): Promise<void> {
  const { req, res, app, deps, secret, auth, url, pathname, method } = ctx;
  const rest = pathname.slice("/d/".length);
  const slash = rest.indexOf("/");
  const id = decodeURIComponent(slash === -1 ? rest : rest.slice(0, slash));
  const subPath = slash === -1 ? "/" : rest.slice(slash);
  const principal = (req.headers["x-as-principal"] as string) ?? "";
  if (
    !(await verifyOrReject(
      req,
      res,
      secret,
      auth,
      canonicalPayload(method, pathname + url.search, principal),
      false,
      ctx.allowUnsignedSourceAuth,
    ))
  )
    return;
  if (deps.requireSignedPortalIdentity || deps.production) {
    const psecret = deps.portalIdentitySecret ?? secret;
    const rawTok = req.headers[PORTAL_IDENTITY_HEADER];
    const tok = Array.isArray(rawTok) ? rawTok[0] : rawTok;
    const actor = psecret && tok ? await verifyPortalIdentity(tok, psecret, Date.now()) : null;
    if (!psecret || !actor || actor.p !== principal)
      return sendJson(res, 403, { error: "forbidden", message: "portal identity required" });
    if (deps.identity) {
      await deps.identity.refresh();
      if (deps.identity.classify(actor.p).type !== "internal") {
        return sendJson(res, 403, { error: "forbidden", message: "principal is no longer active" });
      }
    }
  }
  if (
    deps.deployAppsDomain &&
    deps.deployGateSecret &&
    deps.deployAppsSessionSecret &&
    method === "GET" &&
    String(req.headers["sec-fetch-dest"] ?? "") === "document"
  ) {
    const d = await app.getDeployment(id).catch(swallowAs("deployments: load deployment", null));
    const slug = d?.name ?? d?.id;
    if (d && slug && /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(slug)) {
      res.writeHead(302, {
        location: `https://${slug}.${deps.deployAppsDomain}${subPath}${url.search}`,
        "cache-control": "no-store",
      });
      res.end();
      return;
    }
  }
  const reach = await app.reachDeployment(id, principal);
  return proxyReach(ctx, reach, subPath, principal, { sandbox: true });
}

function adminDeploymentProxyParts(pathname: string): { id: string; subPath: string } | null {
  const prefix = "/v1/admin/deployments/";
  if (!pathname.startsWith(prefix)) return null;
  const rest = pathname.slice(prefix.length);
  const marker = "/proxy";
  const markerAt = rest.indexOf(marker);
  if (markerAt < 0) return null;
  const after = rest.slice(markerAt + marker.length);
  if (after && !after.startsWith("/")) return null;
  try {
    return { id: decodeURIComponent(rest.slice(0, markerAt)), subPath: after || "/" };
  } catch {
    return null;
  }
}

async function proxyAdminDeployment(ctx: BaseCtx): Promise<void> {
  const { req, res, app, deps, secret, auth, url, pathname, method } = ctx;
  const parts = adminDeploymentProxyParts(pathname);
  if (!parts) return sendJson(res, 404, { error: "not_found" });
  const actorHeader = (req.headers["x-admin-actor"] as string) ?? "";
  if (
    !(await verifyOrReject(
      req,
      res,
      secret,
      auth,
      canonicalPayload(method, pathname + url.search, actorHeader),
      false,
      ctx.allowUnsignedSourceAuth,
    ))
  )
    return;
  const deployment = (await app.listDeployments()).find((d) => d.id === parts.id);
  const actor = await authorizeAdmin({ req, res, deps, capability: null }, deployment?.ownerScopeId ?? orgScope(deps));
  if (!actor) return;
  if (!deployment) return sendJson(res, 404, { error: "not_found" });
  audit(deps, {
    principalId: actor.id,
    action: "deployment.visit",
    resource: deployment.id,
    scopeLabel: deployment.ownerScopeId,
  });
  const reach = await app.reachDeployment(parts.id, "", { bypassAcl: true });
  return proxyReach(ctx, reach, parts.subPath, undefined, { sandbox: true });
}

const GATEWAY_AUTH_HEADERS = [
  "x-qm-app-host",
  "x-qm-client-ip",
  "x-signature",
  "x-timestamp",
  "x-as-principal",
  "x-admin-actor",
  "x-agent-capability",
  PORTAL_IDENTITY_HEADER,
];

const PROXY_BUFFER_MAX_BYTES = 10_000_000;
const AGENT_FETCH_DEFAULT_MAX_BYTES = 256 * 1024;
const AGENT_FETCH_MAX_BYTES = 1024 * 1024;
const AGENT_FETCH_TIMEOUT_MS = 10_000;
const AGENT_FETCH_MAX_REDIRECTS = 5;

const THROTTLE_SHIELD_MS = 5_000;
const throttledUpstreams = new Map<string, number>();

function armThrottleShield(upstreamKey: string, statusCode: number, upstream: NodeJS.EventEmitter): void {
  if (statusCode !== 429) return;
  let sawBody = false;
  upstream.on("data", () => (sawBody = true));
  upstream.on("end", () => {
    if (sawBody) return;
    if (throttledUpstreams.size > 1000) {
      for (const [k, until] of throttledUpstreams) if (Date.now() >= until) throttledUpstreams.delete(k);
    }
    throttledUpstreams.set(upstreamKey, Date.now() + THROTTLE_SHIELD_MS);
  });
}
const HTTP2_IDLE_TIMEOUT_MS = 60_000;
const HTTP2_DRAIN_TIMEOUT_MS = 5_000;
interface DeploymentHttp2Connection {
  session: ClientHttp2Session;
  activeStreams: number;
  idleTimer?: NodeJS.Timeout;
  retiring?: boolean;
}
const deploymentHttp2Sessions = new Map<string, DeploymentHttp2Connection>();

const TRACE_HEADERS = ["sentry-trace", "baggage", "traceparent", "tracestate"];

function forwardableHeaders(req: BaseCtx["req"]): Record<string, string | string[]> {
  const out = proxyHeaders(req.headers, ["host", ...GATEWAY_AUTH_HEADERS, ...TRACE_HEADERS]);
  const kept = String(out.cookie ?? "")
    .split(";")
    .map((part) => part.trim())
    .filter((part) => part && !/^(?:dpl_access|dpl_owner|portal_session|portal_session_x)\s*=/.test(part));
  if (kept.length) out.cookie = kept.join("; ");
  else delete out.cookie;
  return out;
}

const APP_SANDBOX_CSP = "sandbox allow-scripts allow-forms allow-popups allow-modals allow-downloads";

function frameAncestorsDirective(ancestors: readonly string[]): string {
  return `frame-ancestors 'self' ${ancestors.join(" ")}`;
}

function cspMentionsFrameAncestors(value: string | string[] | undefined): boolean {
  if (!value) return false;
  return (Array.isArray(value) ? value : [value]).some((v) => /frame-ancestors/i.test(v));
}

function gatewaySafeResponseHeaders(
  headers: Record<string, string | string[] | number | undefined>,
  sandbox = false,
  frameAncestors?: readonly string[],
): Record<string, string | string[]> {
  const normalized: Record<string, string | string[] | undefined> = {};
  for (const [rawName, value] of Object.entries(headers)) {
    const name = rawName.toLowerCase();
    if (value === undefined || name.startsWith(":")) continue;
    normalized[name] = typeof value === "number" ? String(value) : value;
  }
  const out = proxyHeaders(normalized);
  const cookies = out["set-cookie"];
  if (cookies) {
    const values = Array.isArray(cookies) ? cookies : [cookies];
    const kept = values.filter(
      (cookie) => !/^\s*(?:dpl_access|dpl_owner|portal_session|portal_session_x)\s*=/i.test(cookie),
    );
    if (kept.length) out["set-cookie"] = kept;
    else delete out["set-cookie"];
  }
  delete out["clear-site-data"];
  if (sandbox) {
    const existing = out["content-security-policy"];
    out["content-security-policy"] = existing
      ? [...(Array.isArray(existing) ? existing : [existing]), APP_SANDBOX_CSP]
      : APP_SANDBOX_CSP;
  }
  if (frameAncestors?.length && !out["x-frame-options"] && !cspMentionsFrameAncestors(out["content-security-policy"])) {
    const directive = frameAncestorsDirective(frameAncestors);
    const existing = out["content-security-policy"];
    out["content-security-policy"] = existing
      ? [...(Array.isArray(existing) ? existing : [existing]), directive]
      : directive;
  }
  return out;
}

function deploymentHttp2Session(origin: string): DeploymentHttp2Connection {
  const existing = deploymentHttp2Sessions.get(origin);
  if (existing && !existing.session.closed && !existing.session.destroyed) {
    if (existing.idleTimer) clearTimeout(existing.idleTimer);
    existing.idleTimer = undefined;
    return existing;
  }
  const session = connectHttp2(origin);
  session.unref();
  const connection: DeploymentHttp2Connection = { session, activeStreams: 0 };
  deploymentHttp2Sessions.set(origin, connection);
  const remove = (): void => {
    if (deploymentHttp2Sessions.get(origin) === connection) deploymentHttp2Sessions.delete(origin);
    if (connection.idleTimer) clearTimeout(connection.idleTimer);
    connection.idleTimer = undefined;
  };
  session.on("error", () => {
    remove();
    session.destroy();
  });
  session.on("close", remove);
  session.on("goaway", () => retireDeploymentHttp2Connection(origin, connection));
  return connection;
}

function retireDeploymentHttp2Connection(origin: string, connection: DeploymentHttp2Connection): void {
  if (deploymentHttp2Sessions.get(origin) === connection) deploymentHttp2Sessions.delete(origin);
  if (connection.retiring || connection.session.destroyed) return;
  connection.retiring = true;
  connection.session.close();
  const timer = setTimeout(() => connection.session.destroy(), HTTP2_DRAIN_TIMEOUT_MS);
  timer.unref();
  connection.session.once("close", () => clearTimeout(timer));
}

function releaseDeploymentHttp2Stream(origin: string, connection: DeploymentHttp2Connection): void {
  connection.activeStreams--;
  if (connection.activeStreams !== 0 || deploymentHttp2Sessions.get(origin) !== connection) return;
  connection.idleTimer = setTimeout(() => connection.session.close(), HTTP2_IDLE_TIMEOUT_MS);
  connection.idleTimer.unref();
}

function checkDeploymentHttp2Session(connection: DeploymentHttp2Connection): void {
  const timer = setTimeout(() => connection.session.destroy(), 1_000);
  timer.unref();
  try {
    connection.session.ping((error) => {
      clearTimeout(timer);
      if (error) connection.session.destroy();
    });
  } catch {
    clearTimeout(timer);
    connection.session.destroy();
  }
}

function proxyReachHttp2(
  ctx: BaseCtx,
  endpoint: Awaited<ReturnType<App["reachDeployment"]>> & { status: "ok" },
  subPath: string,
  headers: Record<string, string | string[]>,
  bufferedBody: Buffer | null,
  sandbox: boolean,
  frameAncestors?: readonly string[],
): void {
  const { req, res, deps, url, method } = ctx;
  const { host, port, tls } = endpoint.endpoint;
  const origin = `${tls ? "https" : "http"}://${host}:${port}`;
  const requestHeaders: OutgoingHttpHeaders = {
    ":method": method,
    ":path": subPath + url.search,
    ":authority": tls ? host : `${host}:${port}`,
  };
  for (const [name, value] of Object.entries(headers)) {
    if (name.toLowerCase() !== "host") requestHeaders[name.toLowerCase()] = value;
  }
  const replaySafe =
    (method === "GET" || method === "HEAD") && bufferedBody === null && headers["content-length"] === undefined;
  let current: ClientHttp2Stream | undefined;
  res.on("close", () => {
    if (current && !current.closed) current.close(http2Constants.NGHTTP2_CANCEL);
  });
  req.on("error", () => current?.close(http2Constants.NGHTTP2_CANCEL));
  req.on("aborted", () => current?.close(http2Constants.NGHTTP2_CANCEL));

  const start = (retried: boolean): void => {
    const connection = deploymentHttp2Session(origin);
    let up: ClientHttp2Stream;
    try {
      up = connection.session.request(requestHeaders);
    } catch (error) {
      const code = (error as NodeJS.ErrnoException).code;
      const sessionFailed =
        connection.session.closed ||
        connection.session.destroyed ||
        code === "ERR_HTTP2_GOAWAY_SESSION" ||
        code === "ERR_HTTP2_OUT_OF_STREAMS" ||
        code === "ERR_HTTP2_INVALID_SESSION";
      if (sessionFailed) retireDeploymentHttp2Connection(origin, connection);
      if (replaySafe && !retried && sessionFailed && !res.headersSent && !res.destroyed && !res.writableEnded)
        return start(true);
      if (res.destroyed || res.writableEnded) return;
      sendJson(res, 502, { error: "bad_gateway", message: "deployment unreachable" });
      return;
    }
    current = up;
    connection.activeStreams++;
    let responseStarted = false;
    let failureHandled = false;
    const fail = (error?: unknown): void => {
      if (failureHandled) return;
      failureHandled = true;
      const code = (error as NodeJS.ErrnoException | undefined)?.code;
      const sessionFailed =
        connection.session.closed ||
        connection.session.destroyed ||
        code === "ECONNRESET" ||
        code === "ERR_HTTP2_SESSION_ERROR" ||
        code === "ERR_HTTP2_INVALID_SESSION";
      if (sessionFailed) retireDeploymentHttp2Connection(origin, connection);
      const moved = deploymentHttp2Sessions.get(origin) !== connection;
      if (
        !responseStarted &&
        replaySafe &&
        !retried &&
        (sessionFailed || moved) &&
        !res.headersSent &&
        !res.destroyed &&
        !res.writableEnded
      ) {
        up.setTimeout(0);
        if (!up.closed) up.close(http2Constants.NGHTTP2_CANCEL);
        return start(true);
      }
      if (res.destroyed || res.writableEnded) return;
      if (wantsWarmingPage(req, method) && !res.headersSent) sendWarmingPage(res);
      else if (!res.headersSent) sendJson(res, 502, { error: "bad_gateway", message: "deployment unreachable" });
      else res.destroy();
    };
    up.once("close", () => {
      releaseDeploymentHttp2Stream(origin, connection);
      if (!responseStarted || !up.readableEnded || up.rstCode !== http2Constants.NGHTTP2_NO_ERROR) fail();
      else if (!failureHandled && !res.destroyed && !res.writableEnded) res.end();
    });
    const htmlNav = wantsWarmingPage(req, method);
    up.setTimeout(
      warmingDialTimeoutMs(`${host}:${port}`, htmlNav, deps.deployDialTimeoutMs ?? CONFIG_DEFAULTS.deployDialTimeoutMs),
      () => {
        if (failureHandled) return;
        failureHandled = true;
        if (htmlNav && !res.headersSent) sendWarmingPage(res);
        else if (!res.headersSent)
          sendJson(res, 504, { error: "gateway_timeout", message: "deployment did not respond" });
        else res.end();
        up.close(http2Constants.NGHTTP2_CANCEL);
        checkDeploymentHttp2Session(connection);
      },
    );
    up.on("response", (responseHeaders) => {
      if (failureHandled || res.headersSent || res.destroyed || res.writableEnded) {
        up.close(http2Constants.NGHTTP2_CANCEL);
        return;
      }
      responseStarted = true;
      up.setTimeout(0);
      markUpstreamUp(`${host}:${port}`);
      armThrottleShield(`${host}:${port}`, Number(responseHeaders[":status"] ?? 0), up);
      const status = Number(responseHeaders[":status"] ?? 502);
      const safeHeaders = gatewaySafeResponseHeaders(responseHeaders, sandbox, frameAncestors);
      if (frameAncestors !== undefined) res.removeHeader("content-security-policy");
      res.writeHead(status, safeHeaders);
      up.pipe(res, { end: false });
    });
    up.on("error", fail);
    if (replaySafe) up.end();
    else if (bufferedBody !== null) up.end(bufferedBody);
    else req.pipe(up);
  };
  start(false);
}

// --- cold-start warming page -------------------------------------------------
// AWS microVMs auto-resume on first connect, which can take many seconds. During
// that window a browser navigation would otherwise hang for the full dial timeout
// and then land on raw gateway JSON. For document requests we instead answer
// quickly with a small self-refreshing "warming up" page.
const WARM_RECENT_MS = 60_000;
const COLD_FIRST_BYTE_TIMEOUT_MS = 4_000;
const upstreamLastOk = new Map<string, number>();

function markUpstreamUp(upstreamKey: string): void {
  if (upstreamLastOk.size > 1000) {
    for (const [k, at] of upstreamLastOk) if (Date.now() - at > WARM_RECENT_MS) upstreamLastOk.delete(k);
  }
  upstreamLastOk.set(upstreamKey, Date.now());
}

function wantsWarmingPage(req: BaseCtx["req"], method: string): boolean {
  if (method !== "GET" && method !== "HEAD") return false;
  const dest = String(req.headers["sec-fetch-dest"] ?? "");
  if (dest && dest !== "document") return false;
  return String(req.headers.accept ?? "").includes("text/html");
}

function warmingDialTimeoutMs(upstreamKey: string, htmlNav: boolean, configuredMs: number): number {
  if (!htmlNav) return configuredMs;
  const lastOk = upstreamLastOk.get(upstreamKey) ?? 0;
  if (Date.now() - lastOk < WARM_RECENT_MS) return configuredMs;
  return Math.min(configuredMs, COLD_FIRST_BYTE_TIMEOUT_MS);
}

const WARMING_PAGE_HTML = `<!doctype html>
<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
<title>Starting up…</title>
<style>
  body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
    font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:#fafaf8;color:#333}
  .card{text-align:center;padding:2rem}
  .spinner{width:28px;height:28px;margin:0 auto 1rem;border:3px solid #eee;border-top-color:#f26522;
    border-radius:50%;animation:spin .9s linear infinite}
  @keyframes spin{to{transform:rotate(360deg)}}
  h1{font-size:1.1rem;font-weight:600;margin:0 0 .35rem}
  p{margin:0;color:#777}
</style></head>
<body><div class="card"><div class="spinner"></div><h1>Starting up&hellip;</h1>
<p id="msg"></p></div>
<script>
  var started = Date.now();
  function retry(){
    if (Date.now() - started > 120000) {
      document.getElementById("msg").textContent = "Still not responding — the app may have crashed.";
      return;
    }
    fetch(location.href, { method: "HEAD", cache: "no-store" }).then(function(r){
      if (r.status !== 503 && r.status !== 502 && r.status !== 504) location.reload();
      else setTimeout(retry, 2000);
    }).catch(function(){ setTimeout(retry, 2000); });
  }
  setTimeout(retry, 1500);
</script></body></html>`;

function sendWarmingPage(res: BaseCtx["res"]): void {
  if (res.headersSent || res.destroyed || res.writableEnded) {
    res.end();
    return;
  }
  res.writeHead(503, {
    "content-type": "text/html; charset=utf-8",
    "cache-control": "no-store",
    "retry-after": "2",
  });
  res.end(WARMING_PAGE_HTML);
}
// -----------------------------------------------------------------------------

async function proxyReach(
  ctx: BaseCtx,
  reach: Awaited<ReturnType<App["reachDeployment"]>>,
  subPath: string,
  viewer?: string,
  opts?: { sandbox?: boolean; frameAncestors?: readonly string[] },
): Promise<void> {
  const { req, res, deps, url, method } = ctx;
  if (res.destroyed) return;
  if (reach.status === "not_found") return sendJson(res, 404, { error: "not_found" });
  if (reach.status === "denied")
    return sendJson(res, 403, { error: "forbidden", message: "not in the deployment's scope" });
  const { host, port } = reach.endpoint;
  const upstreamKey = `${host}:${port}`;
  const shieldedUntil = throttledUpstreams.get(upstreamKey) ?? 0;
  if (Date.now() < shieldedUntil) {
    res.writeHead(429, {
      "content-type": "application/json",
      "retry-after": String(Math.max(1, Math.ceil((shieldedUntil - Date.now()) / 1000))),
      "cache-control": "no-store",
    });
    res.end(JSON.stringify({ error: "throttled", message: "deployment is rate limited upstream" }));
    return;
  }
  const requestFn = reach.endpoint.tls ? httpsRequest : httpRequest;
  const hostHeader = reach.endpoint.tls ? host : `${host}:${port}`;
  let bufferedBody: Buffer | null = null;
  const headers: Record<string, string | string[]> = {
    ...forwardableHeaders(req),
    host: hostHeader,
    ...reach.endpoint.proxyHeaders,
  };

  if (viewer && ctx.secret) {
    headers[PORTAL_IDENTITY_HEADER] = await mintPortalIdentity(
      { p: viewer, exp: Date.now() + 60_000 },
      viewerIdentityKey(ctx.secret, reach.id),
    );
  }
  if (/(?:^|,)\s*chunked\s*$/i.test(String(req.headers["transfer-encoding"] ?? ""))) {
    const chunks: Buffer[] = [];
    let size = 0;
    try {
      for await (const chunk of req) {
        size += (chunk as Buffer).length;
        if (size > PROXY_BUFFER_MAX_BYTES)
          return sendJson(res, 413, { error: "payload_too_large", message: "request body too large" });
        chunks.push(chunk as Buffer);
      }
    } catch {
      res.destroy();
      return;
    }
    bufferedBody = Buffer.concat(chunks);
    headers["content-length"] = String(bufferedBody.length);
  }
  if (res.destroyed) return;
  if (reach.endpoint.httpVersion === "2") {
    proxyReachHttp2(ctx, reach, subPath, headers, bufferedBody, opts?.sandbox ?? false, opts?.frameAncestors);
    return;
  }
  const htmlNav = wantsWarmingPage(req, method);
  const up = requestFn(
    {
      hostname: host,
      port,
      path: subPath + url.search,
      method,
      headers,
      ...deploymentProxyAgent(reach.endpoint.socksProxyPort),
    },
    (upRes) => {
      up.setTimeout(0);
      markUpstreamUp(upstreamKey);
      upRes.on("error", () => res.destroy());
      armThrottleShield(upstreamKey, upRes.statusCode ?? 0, upRes);
      const headers = gatewaySafeResponseHeaders(upRes.headers, opts?.sandbox ?? false, opts?.frameAncestors);
      if (opts?.frameAncestors !== undefined) res.removeHeader("content-security-policy");
      res.writeHead(upRes.statusCode ?? 502, headers);
      upRes.pipe(res);
    },
  );
  const dialMs = warmingDialTimeoutMs(
    upstreamKey,
    htmlNav,
    deps.deployDialTimeoutMs ?? CONFIG_DEFAULTS.deployDialTimeoutMs,
  );
  up.setTimeout(dialMs, () => {
    if (htmlNav && !res.headersSent) sendWarmingPage(res);
    else if (!res.headersSent) sendJson(res, 504, { error: "gateway_timeout", message: "deployment did not respond" });
    else res.end();
    up.destroy();
  });
  up.on("error", () => {
    if (htmlNav && !res.headersSent) sendWarmingPage(res);
    else if (!res.headersSent) sendJson(res, 502, { error: "bad_gateway", message: "deployment unreachable" });
    else res.end();
  });
  req.on("error", () => up.destroy());
  if (bufferedBody !== null) up.end(bufferedBody);
  else req.pipe(up);
  return;
}

interface DeploymentFetchResult {
  status: number;
  headers: Record<string, string | string[] | number | undefined>;
  body: Buffer;
  truncated: boolean;
}

function boundedResponseBody(
  stream: NodeJS.ReadableStream & { destroy(error?: Error): void },
  maxBytes: number,
  timeoutMs = AGENT_FETCH_TIMEOUT_MS,
): Promise<{ body: Buffer; truncated: boolean }> {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];
    let size = 0;
    let settled = false;
    const timeout = setTimeout(() => stream.destroy(new Error("timeout")), Math.max(1, timeoutMs));
    timeout.unref();
    const finish = (truncated: boolean): void => {
      if (settled) return;
      settled = true;
      clearTimeout(timeout);
      resolve({ body: Buffer.concat(chunks, Math.min(size, maxBytes)), truncated });
      if (truncated) stream.destroy();
    };
    stream.on("data", (raw: Buffer | string) => {
      const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
      const remaining = maxBytes - size;
      if (remaining > 0) chunks.push(chunk.subarray(0, remaining));
      size += Math.min(chunk.length, Math.max(remaining, 0));
      if (chunk.length > remaining) finish(true);
    });
    stream.on("end", () => finish(false));
    const fail = (error?: Error): void => {
      if (settled) return;
      settled = true;
      clearTimeout(timeout);
      reject(error ?? new Error("upstream aborted"));
    };
    stream.on("error", fail);
    stream.on("aborted", fail);
  });
}

function deploymentFetchHttp1(
  endpoint: Awaited<ReturnType<App["reachDeployment"]>> & { status: "ok" },
  path: string,
  maxBytes: number,
  deadline: number,
): Promise<DeploymentFetchResult> {
  return new Promise((resolve, reject) => {
    const { host, port, tls, proxyHeaders } = endpoint.endpoint;
    const requestFn = tls ? httpsRequest : httpRequest;
    const request = requestFn(
      {
        hostname: host,
        port,
        path,
        method: "GET",
        headers: { ...proxyHeaders, "accept-encoding": "identity" },
        ...deploymentProxyAgent(endpoint.endpoint.socksProxyPort),
      },
      async (response) => {
        clearTimeout(timeout);
        try {
          const collected = await boundedResponseBody(response, maxBytes, deadline - Date.now());
          resolve({ status: response.statusCode ?? 502, headers: response.headers, ...collected });
        } catch (error) {
          reject(error);
        }
      },
    );
    const timeout = setTimeout(() => request.destroy(new Error("timeout")), Math.max(1, deadline - Date.now()));
    timeout.unref();
    request.on("error", (error) => {
      clearTimeout(timeout);
      reject(error);
    });
    request.end();
  });
}

function deploymentFetchHttp2(
  endpoint: Awaited<ReturnType<App["reachDeployment"]>> & { status: "ok" },
  path: string,
  maxBytes: number,
  deadline: number,
): Promise<DeploymentFetchResult> {
  return new Promise((resolve, reject) => {
    const { host, port, tls, proxyHeaders } = endpoint.endpoint;
    const origin = `${tls ? "https" : "http"}://${host}:${port}`;
    const connection = deploymentHttp2Session(origin);
    const stream = connection.session.request({
      ":method": "GET",
      ":path": path,
      ":authority": tls ? host : `${host}:${port}`,
      "accept-encoding": "identity",
      ...proxyHeaders,
    });
    connection.activeStreams++;
    let headers: Record<string, string | string[] | number | undefined> = {};
    stream.on("response", (responseHeaders) => {
      headers = responseHeaders;
    });
    boundedResponseBody(stream, maxBytes, deadline - Date.now())
      .then((collected) => resolve({ status: Number(headers[":status"] ?? 502), headers, ...collected }))
      .catch(reject);
    stream.once("close", () => releaseDeploymentHttp2Stream(origin, connection));
    stream.end();
  });
}

function normalizedDeploymentFetchPath(raw: string | null): string | null {
  const path = raw ?? "/";
  if (!path.startsWith("/") || path.includes("\\") || path.includes("\0")) return null;
  try {
    let decodedPath = path.split("?", 1)[0]!;
    for (let depth = 0; depth < 8; depth++) {
      const next = decodeURIComponent(decodedPath);
      if (
        next.includes("\\") ||
        next.includes("\0") ||
        next.split("/").some((segment) => segment === "." || segment === "..")
      )
        return null;
      if (next === decodedPath) break;
      if (depth === 7) return null;
      decodedPath = next;
    }
    const normalized = new URL(path, "http://deployment.invalid");
    if (normalized.origin !== "http://deployment.invalid") return null;
    return normalized.pathname + normalized.search;
  } catch {
    return null;
  }
}

function redirectPath(
  endpoint: Awaited<ReturnType<App["reachDeployment"]>> & { status: "ok" },
  location: string | string[] | number | undefined,
  currentPath: string,
): string | null {
  if (typeof location !== "string") return null;
  try {
    const { host, port, tls } = endpoint.endpoint;
    const origin = `${tls ? "https" : "http"}://${host}:${port}`;
    const next = new URL(location, `${origin}${currentPath}`);
    if (next.origin !== origin) return null;
    return normalizedDeploymentFetchPath(next.pathname + next.search);
  } catch {
    return null;
  }
}

async function fetchDeploymentResponse(
  endpoint: Awaited<ReturnType<App["reachDeployment"]>> & { status: "ok" },
  initialPath: string,
  maxBytes: number,
): Promise<DeploymentFetchResult> {
  let path = initialPath;
  const deadline = Date.now() + AGENT_FETCH_TIMEOUT_MS;
  for (let redirects = 0; ; redirects++) {
    const response =
      endpoint.endpoint.httpVersion === "2"
        ? await deploymentFetchHttp2(endpoint, path, maxBytes, deadline)
        : await deploymentFetchHttp1(endpoint, path, maxBytes, deadline);
    if (![301, 302, 303, 307, 308].includes(response.status)) return response;
    if (redirects >= AGENT_FETCH_MAX_REDIRECTS) throw new Error("too many redirects");
    const next = redirectPath(endpoint, response.headers.location, path);
    if (!next) throw new Error("redirect leaves deployment");
    path = next;
  }
}

export async function proxyDeploymentSubdomain(ctx: BaseCtx): Promise<boolean> {
  const { req, res, app, deps, url, pathname } = ctx;
  const appsDomain = deps.deployAppsDomain;
  const gateSecret = deps.deployGateSecret;
  const fromAppHost = req.headers["x-qm-app-host"] === "1";
  if (!appsDomain || !gateSecret) {
    if (!fromAppHost) return false;
    sendJson(res, 503, { error: "unavailable", message: "app gateway is not configured" });
    return true;
  }
  const rawHost = (req.headers.host ?? "").split(":")[0]!.toLowerCase();
  const suffix = `.${appsDomain.toLowerCase()}`;
  if (!rawHost || !rawHost.endsWith(suffix)) {
    if (!fromAppHost) return false;
    sendJson(res, 404, { error: "not_found" });
    return true;
  }
  const slug = rawHost.slice(0, -suffix.length);
  if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(slug)) {
    sendJson(res, 404, { error: "not_found" });
    return true;
  }
  if (!["GET", "HEAD", "OPTIONS"].includes(ctx.method)) {
    const origin = req.headers.origin;
    const site = req.headers["sec-fetch-site"];
    if ((origin !== undefined && origin !== `https://${rawHost}`) || (site !== undefined && site !== "same-origin")) {
      sendJson(res, 403, { error: "forbidden", message: "cross-origin app request refused" });
      return true;
    }
  }
  const safePathname =
    pathname.startsWith("/") && !pathname.startsWith("//") && !/[\\\x00-\x1f]/.test(pathname) ? pathname : "/";
  const staleAccess = url.searchParams.has("access");
  url.searchParams.delete("access");
  const staleOwner = url.searchParams.has("owner");
  url.searchParams.delete("owner");
  const signInAttempted = url.searchParams.get("dpl_signin") === "1";
  url.searchParams.delete("dpl_signin");
  const cleanUrlRedirect = (): void => {
    const qs = url.searchParams.toString();
    res.writeHead(302, { location: safePathname + (qs ? `?${qs}` : ""), "cache-control": "no-store" });
    res.end();
  };
  if ((staleAccess || staleOwner) && ctx.method === "GET") {
    cleanUrlRedirect();
    return true;
  }
  const deployment = await app.getDeployment(slug).catch(swallowAs("deployments: load deployment", null));
  const externalAllowed = deployment
    ? await externalAppSharingAllowed(deps.featureFlags, deployment.ownerScopeId)
    : false;
  const isPublic = deployment?.public === true && externalAllowed;
  const sessionSecret = deps.deployAppsSessionSecret;
  const loginUrl = deps.deployAppsLoginUrl;
  const wantsHtml = ctx.method === "GET" && String(req.headers.accept ?? "").includes("text/html");
  let session = sessionSecret ? portalSession(req.headers.cookie, sessionSecret) : null;
  const dest = req.headers["sec-fetch-dest"];
  const site = req.headers["sec-fetch-site"];
  const framed = dest === "iframe" || site === "same-origin";
  const embedAncestors = framed ? (deployment?.embedAncestors ?? []) : [];
  if (!session && sessionSecret && embedAncestors.length) {
    session = portalSessionFrom(req.headers.cookie, FRAME_SESSION_COOKIE, sessionSecret);
  }
  const sub = session?.sub;
  if (embedAncestors.length) res.setHeader("content-security-policy", frameAncestorsDirective(embedAncestors));
  if (!isPublic && (!sessionSecret || !loginUrl)) {
    sendJson(res, 503, { error: "unavailable", message: "sign-in is not configured for deployment subdomains" });
    return true;
  }
  if (!sub && !isPublic) {
    const qs = url.searchParams.toString();
    const returnTo = `https://${rawHost}${safePathname}?${qs ? `${qs}&` : ""}dpl_signin=1`;
    const signIn = `${loginUrl}${deps.deployAppsLoginPath ?? "/auth/login"}?returnTo=${encodeURIComponent(returnTo)}`;
    if (!wantsHtml) {
      sendJson(res, 401, { error: "unauthorized", message: "sign-in required", loginUrl: signIn });
    } else if (signInAttempted) {
      res.writeHead(401, {
        "content-type": "text/html; charset=utf-8",
        "cache-control": "no-store",
        "x-content-type-options": "nosniff",
      });
      res.end(signInFailedHtml(signIn));
    } else {
      res.writeHead(302, { location: signIn, "cache-control": "no-store" });
      res.end();
    }
    return true;
  }
  const bareApp = url.searchParams.get("__qm_no_shell") === "1";
  url.searchParams.delete("__qm_no_shell");
  const isTopDocument = String(req.headers["sec-fetch-dest"] ?? "") === "document";
  const isShellRequest = pathname.startsWith(APP_SHELL_PATH_PREFIX);
  const canManage = sub && !session?.appOnly ? await app.canManageDeployment(slug, sub) : false;
  let authenticatedPermission: Permission | null = null;
  if (sub && deployment) {
    if (session?.appOnly) {
      await deps.identity?.refresh();
      if (
        externalAllowed &&
        deps.identity?.deactivationSource(sub) !== "manual" &&
        (await app.deploymentGrantees(deployment.id)).some(
          (grant) => grant.scope === scopeId("personal", sub.trim().toLowerCase()) && grant.permission === "read",
        )
      )
        authenticatedPermission = "read";
    } else {
      authenticatedPermission = await app.effectiveDeploymentPermission(deployment, sub);
    }
  }
  const isPageLoad =
    ctx.method === "GET" &&
    wantsHtml &&
    (dest === undefined || dest === "document" || (dest === "iframe" && site !== "same-origin"));
  const recordPageView = (authMode: AppViewAuthMode): void => {
    if (!isPageLoad || !deployment || !deps.appPageViews) return;
    const forwardedIp = fromAppHost ? req.headers["x-qm-client-ip"] : undefined;
    const ip = typeof forwardedIp === "string" && forwardedIp ? forwardedIp : (req.socket.remoteAddress ?? null);
    const userAgent = req.headers["user-agent"];
    void deps.appPageViews
      .record({
        deploymentId: deployment.id,
        version: deployment.appliedVersion ?? deployment.currentVersion ?? null,
        viewer: sub ?? null,
        authMode,
        at: Date.now(),
        path: safePathname,
        ip,
        userAgent: typeof userAgent === "string" ? userAgent : null,
      })
      .catch(reportFailureAs("app page view log", undefined, deployment.id));
  };
  if (ctx.method === "GET" && ((!bareApp && isTopDocument) || isShellRequest) && canManage && loginUrl) {
    const annotationsEnabled =
      !!sub && (await deps.featureFlags?.enabled("app_annotations", scopeId("personal", sub))) === true;
    if (signInAttempted) {
      cleanUrlRedirect();
      return true;
    }
    if (isShellRequest) {
      if (pathname === "/__claw__/version" && deployment)
        sendJson(res, 200, { version: deployment.appliedVersion ?? deployment.currentVersion });
      else if (annotationsEnabled && (pathname === "/__claw__/annotate.js" || pathname === "/__claw__/annotate.css")) {
        const kind = pathname.endsWith(".js") ? "js" : "css";
        res.writeHead(200, {
          "content-type": kind === "js" ? "text/javascript; charset=utf-8" : "text/css; charset=utf-8",
          "cache-control": "no-cache",
          "x-content-type-options": "nosniff",
        });
        res.end(appAnnotationAsset(kind));
      } else sendJson(res, 404, { error: "not_found" });
      return true;
    }
    recordPageView("signed_in");
    res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
    res.end(
      appShellHtml({
        annotationsEnabled,
        slug,
        name: deployment?.displayName ?? slug,
        portalUrl: loginUrl,
        path: safePathname + url.search,
      }),
    );
    return true;
  }
  const viewer = sub ?? "";
  const reach =
    session?.appOnly && !isPublic && !authenticatedPermission
      ? { status: deployment ? ("denied" as const) : ("not_found" as const) }
      : await app.reachDeployment(
          deployment?.id ?? slug,
          viewer,
          canManage || isPublic || session?.appOnly ? { bypassAcl: true } : undefined,
        );
  if (reach.status === "denied") {
    const owner = (await app.getDeployment(slug).catch(swallowAs("deployments: load deployment", null)))?.ownerScopeId;
    const ev = {
      at: Date.now(),
      principalId: viewer,
      action: "deployment.reach_denied",
      resource: slug,
      scopeLabel: owner ?? scopeId("personal", viewer),
      status: "denied",
    };
    const hour = Math.floor(ev.at / 3_600_000);
    if (deps.auditLog?.recordOnce) await deps.auditLog.recordOnce(`reach_denied|${viewer}|${slug}|${hour}`, ev);
    else deps.auditLog?.record(ev);
  }
  if (reach.status === "denied" && ctx.method === "POST" && pathname === REQUEST_ACCESS_PATH) {
    const d = await app.getDeployment(slug).catch(swallowAs("deployments: load deployment", null));
    if (!d) {
      sendJson(res, 404, { error: "not_found" });
      return true;
    }
    // The recipient is the app's owner: the personal home scope if it has one, else whoever created it.
    const [ownerKind, ownerRef] = String(d.ownerScopeId).split(":", 2);
    const ownerId = ownerKind === "personal" && ownerRef ? ownerRef : d.createdBy;
    const label = d.displayName ?? d.name ?? slug;
    // One request per visitor per app per day — the idempotent outbox absorbs button mashing.
    const day = Math.floor(Date.now() / 86_400_000);
    try {
      await app.enqueueDelivery({
        destination: {
          ...principalDestination(ownerId, viewer),
          deploymentAccess: { deploymentId: d.id, requesterId: viewer },
        },
        text:
          `${viewer} is asking for access to your app "${label}" (https://${rawHost}/). ` +
          `They signed in but the app isn't shared with them. To grant it, share the deployment with personal:${viewer}.`,
        idempotencyKey: `deploy-access-request:${slug}:${viewer}:${day}`,
      });
      sendJson(res, 200, { ok: true });
    } catch {
      sendJson(res, 502, { error: "delivery_failed", message: "the request could not be delivered — try again later" });
    }
    return true;
  }
  if (reach.status === "denied" && wantsHtml) {
    res.writeHead(403, {
      "content-type": "text/html; charset=utf-8",
      "cache-control": "no-store",
      "x-content-type-options": "nosniff",
    });
    res.end(notSharedHtml(viewer));
    return true;
  }
  if (reach.status === "ok" && signInAttempted && ctx.method === "GET") {
    cleanUrlRedirect();
    return true;
  }
  if (reach.status === "ok") {
    let authMode: AppViewAuthMode = "public";
    if (session?.appOnly) authMode = "app_only";
    else if (sub && (canManage || authenticatedPermission)) authMode = "signed_in";
    recordPageView(authMode);
  }
  await proxyReach(ctx, reach, pathname, sub && (canManage || authenticatedPermission) ? sub : undefined, {
    frameAncestors: embedAncestors,
  });
  return true;
}

function gateCardHtml(title: string, paragraphsHtml: string): string {
  return `<!doctype html><html lang="en"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1"><title>${escapeHtml(title)}</title>
<style>body{margin:0;min-height:100vh;display:grid;place-items:center;background:#0a0a0a;color:#fafafa;
font:14px/1.6 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif}
.card{max-width:420px;text-align:center;padding:32px 20px}h1{font-size:19px;margin:0 0 10px}
p{color:#a3a3a3;margin:0 0 8px}b{color:#fafafa}a{color:#fafafa}</style></head>
<body><div class="card"><h1>${escapeHtml(title)}</h1>${paragraphsHtml}</div></body></html>`;
}

const REQUEST_ACCESS_PATH = "/__claw__/request-access";

function notSharedHtml(sub: string): string {
  return gateCardHtml(
    "This app hasn't been shared with you",
    `<p>You're signed in as <b>${escapeHtml(sub)}</b>, but this app's owner hasn't shared it with you.</p>
<p>Ask the owner for access, or for the app's share link.</p>
<p><button id="req" style="margin-top:12px;padding:8px 18px;border-radius:8px;border:1px solid #3f3f3f;
background:#fafafa;color:#0a0a0a;font:inherit;font-weight:600;cursor:pointer">Request access</button></p>
<script>document.getElementById("req").addEventListener("click",async function(){
var b=this;b.disabled=true;b.textContent="Sending\u2026";
try{var r=await fetch(${JSON.stringify(REQUEST_ACCESS_PATH)},{method:"POST"});
b.textContent=r.ok?"Request sent \u2713":"Couldn't send \u2014 try again";b.disabled=r.ok;}
catch(e){b.textContent="Couldn't send \u2014 try again";b.disabled=false;}});</script>`,
  );
}

function signInFailedHtml(signIn: string): string {
  return gateCardHtml(
    "Sign-in didn't reach this app",
    `<p>You signed in, but this app never received your session. This usually means the app gateway is misconfigured — tell whoever runs it.</p>
<p><a href="${escapeHtml(signIn)}">Try signing in again</a></p>`,
  );
}

const deploymentId = async (app: App, idOrName: string): Promise<string | undefined> =>
  (await app.listDeployments()).find((d) => d.id === idOrName || d.name === idOrName)?.id;

function deploymentGitParts(pathname: string): { id: string; tail: string } | null {
  const prefix = "/v1/deployments/";
  if (!pathname.startsWith(prefix)) return null;
  const rest = pathname.slice(prefix.length);
  const marker = "/git/";
  const markerAt = rest.indexOf(marker);
  if (markerAt < 0) return null;
  const tail = rest.slice(markerAt + marker.length);
  if (!tail) return null;
  try {
    return { id: decodeURIComponent(rest.slice(0, markerAt)), tail };
  } catch {
    return null;
  }
}

function isDeploymentGitRoute(method: string, pathname: string): boolean {
  const parts = deploymentGitParts(pathname);
  if (!parts) return false;
  return (
    (method === "GET" && parts.tail === "info/refs") ||
    (method === "POST" && (parts.tail === "git-upload-pack" || parts.tail === "git-receive-pack"))
  );
}

function gitServiceOf(tail: string, url: URL): "git-upload-pack" | "git-receive-pack" | null {
  if (tail === "git-upload-pack" || tail === "git-receive-pack") return tail;
  if (tail === "info/refs") {
    const s = url.searchParams.get("service");
    if (s === "git-upload-pack" || s === "git-receive-pack") return s;
  }
  return null;
}

function gitTokenFrom(ctx: BaseCtx): string | null {
  const authz = ctx.req.headers.authorization;
  if (typeof authz === "string") {
    const basic = /^basic\s+(.+)$/i.exec(authz);
    if (basic) {
      try {
        const decoded = Buffer.from(basic[1]!, "base64").toString("utf8");
        const colon = decoded.indexOf(":");
        const user = colon < 0 ? decoded : decoded.slice(0, colon);
        const pass = colon < 0 ? "" : decoded.slice(colon + 1);
        return pass || user || null;
      } catch {
        return null;
      }
    }
    const bearer = /^bearer\s+(.+)$/i.exec(authz);
    if (bearer) return bearer[1]!;
  }
  return ctx.url.searchParams.get("token") ?? ctx.url.searchParams.get("access_token");
}

function rejectGitAuth(res: BaseCtx["res"], message = "deployment git token required"): void {
  res.writeHead(401, { "content-type": "application/json", "www-authenticate": 'Basic realm="deployment git"' });
  res.end(JSON.stringify({ error: "unauthorized", message }));
}

async function readRequestBytes(req: BaseCtx["req"]): Promise<Buffer> {
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(Buffer.from(chunk as Buffer));
  return Buffer.concat(chunks);
}

function gitQueryString(url: URL): string {
  const qs = new URLSearchParams(url.searchParams);
  qs.delete("token");
  qs.delete("access_token");
  return qs.toString();
}

function headerEnd(buf: Buffer): { headEnd: number; bodyStart: number } | null {
  const crlf = buf.indexOf("\r\n\r\n");
  if (crlf >= 0) return { headEnd: crlf, bodyStart: crlf + 4 };
  const lf = buf.indexOf("\n\n");
  if (lf >= 0) return { headEnd: lf, bodyStart: lf + 2 };
  return null;
}

async function runGitHttpBackend(input: {
  repoPath: string;
  tail: string;
  method: string;
  query: string;
  contentType?: string;
  body: Buffer;
}): Promise<{ status: number; headers: Record<string, string>; body: Buffer }> {
  const repoRoot = dirname(input.repoPath);
  const repoName = basename(input.repoPath);
  const env: NodeJS.ProcessEnv = {
    PATH: "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin",
    GIT_PROJECT_ROOT: repoRoot,
    GIT_HTTP_EXPORT_ALL: "1",
    PATH_INFO: `/${repoName}/${input.tail}`,
    REQUEST_METHOD: input.method,
    QUERY_STRING: input.query,
    CONTENT_TYPE: input.contentType ?? "",
    CONTENT_LENGTH: String(input.body.length),
    REMOTE_USER: "deployment-git",
  };
  return new Promise((resolve, reject) => {
    const child = spawn("git", ["-c", "http.receivepack=true", "http-backend"], {
      env,
      stdio: ["pipe", "pipe", "pipe"],
    });
    const stdout: Buffer[] = [];
    const stderr: Buffer[] = [];
    child.stdout.on("data", (d) => stdout.push(Buffer.from(d)));
    child.stderr.on("data", (d) => stderr.push(Buffer.from(d)));
    child.on("error", reject);
    child.stdin.on("error", () => {});
    child.on("close", (code) => {
      const out = Buffer.concat(stdout);
      const split = headerEnd(out);
      if ((code ?? 0) !== 0 || !split) {
        reject(new Error(`git http-backend exited ${code}: ${Buffer.concat(stderr).toString("utf8").trim()}`));
        return;
      }
      const headers: Record<string, string> = {};
      let status = 200;
      for (const line of out.subarray(0, split.headEnd).toString("utf8").split(/\r?\n/)) {
        const i = line.indexOf(":");
        if (i < 0) continue;
        const name = line.slice(0, i).trim();
        const value = line.slice(i + 1).trim();
        if (name.toLowerCase() === "status") {
          status = Number(value.split(/\s+/)[0]) || 200;
        } else {
          headers[name] = value;
        }
      }
      resolve({ status, headers, body: out.subarray(split.bodyStart) });
    });
    child.stdin.end(input.body);
  });
}

async function serveDeploymentGit(ctx: BaseCtx): Promise<void> {
  const parts = deploymentGitParts(ctx.pathname);
  if (!parts) return sendJson(ctx.res, 404, { error: "not_found" });
  const service = gitServiceOf(parts.tail, ctx.url);
  if (!service) return sendJson(ctx.res, 403, { error: "forbidden", message: "unsupported deployment git service" });
  const isPush = service === "git-receive-pack";
  if (isPush && !ctx.secret)
    return sendJson(ctx.res, 503, { error: "unavailable", message: "deployment git push requires core signing" });
  let access: Awaited<ReturnType<typeof verifyDeployGitAccess>> = null;
  if (ctx.secret) {
    const token = gitTokenFrom(ctx);
    access = token ? await verifyDeployGitAccess(ctx.secret, token) : null;
    if (!access) return rejectGitAuth(ctx.res);
    if (access.deploymentId !== parts.id)
      return sendJson(ctx.res, 403, { error: "forbidden", message: "token is for a different deployment" });
    if (isPush && access.permission !== "write")
      return sendJson(ctx.res, 403, { error: "forbidden", message: "deployment git token is read-only" });
    if (
      access.principalId &&
      !(await ctx.app.authorizesDeploymentGitAccess(parts.id, access.principalId, access.permission))
    ) {
      return sendJson(ctx.res, 403, { error: "forbidden", message: "deployment git access has been revoked" });
    }
    if (isPush && !access.principalId) {
      return sendJson(ctx.res, 403, { error: "forbidden", message: "deployment git write access has been revoked" });
    }
  }
  const repoPath = await ctx.app.deploymentGitRepoPath(parts.id);
  if (!repoPath) return sendJson(ctx.res, 404, { error: "not_found" });
  try {
    const body = ctx.method === "POST" ? await readRequestBytes(ctx.req) : Buffer.alloc(0);
    const runBackend = () =>
      runGitHttpBackend({
        repoPath,
        tail: parts.tail,
        method: ctx.method,
        query: gitQueryString(ctx.url),
        contentType: typeof ctx.req.headers["content-type"] === "string" ? ctx.req.headers["content-type"] : undefined,
        body,
      });
    const result = isPush
      ? await ctx.app.runDeploymentGitPush(parts.id, async () => {
          if (
            access?.principalId &&
            !(await ctx.app.authorizesDeploymentGitAccess(parts.id, access.principalId, "write"))
          ) {
            const body = Buffer.from(
              JSON.stringify({ error: "forbidden", message: "deployment git write access has been revoked" }),
            );
            return {
              result: {
                status: 403,
                headers: { "content-type": "application/json", "content-length": String(body.length) },
                body,
              },
              ok: false,
            };
          }
          const r = await runBackend();
          return { result: r, ok: r.status >= 200 && r.status < 300 };
        })
      : await runBackend();
    ctx.res.writeHead(result.status, result.headers);
    ctx.res.end(result.body);
  } catch (e) {
    console.error("[deploy-git] request failed:", errMessage(e));
    return sendJson(ctx.res, 500, { error: "git_failed", message: "deployment git request failed" });
  }
}

function gitUrlBase(ctx: ApiCtx): string {
  if (ctx.deps.apiBaseUrl) {
    return ctx.deps.apiBaseUrl;
  } else if (ctx.deps.publicUrl) {
    return ctx.deps.publicUrl;
  } else {
    const host = (ctx.req.headers["x-forwarded-host"] as string) ?? ctx.req.headers.host ?? "localhost";
    const proto = (ctx.req.headers["x-forwarded-proto"] as string) ?? "http";
    return `${proto}://${host}`;
  }
}

async function deploymentGitUrl(ctx: ApiCtx): Promise<void> {
  const { res, app, params, capability } = ctx;
  if (!capability)
    return sendJson(res, 403, { error: "forbidden", message: "a git URL requires an agent capability token" });
  if (!ctx.secret) return sendJson(res, 503, { error: "unavailable", message: "core signing secret not configured" });
  const result = await app.deploymentGitUrlFor(params.id!, capability.actorId, {
    secret: ctx.secret,
    baseUrl: gitUrlBase(ctx),
  });
  if (!result) return sendJson(res, 403, { error: "forbidden", message: "no access to this deployment" });
  return sendJson(res, 200, result);
}

async function createDeployment(ctx: ApiCtx): Promise<void> {
  const { res, app, body } = ctx;
  if (!isDeployInput(body)) return sendJson(res, 400, { error: "bad_request", message: "expected a DeployInput" });
  const principalId = ctx.capability?.actorId ?? ctx.actor?.p;
  if (principalId && body.createdBy !== principalId) return sendJson(res, 403, { error: "forbidden" });
  try {
    return sendJson(res, 200, { deployment: deploymentView(await app.deploy(body)) });
  } catch (e) {
    return sendJson(res, 400, { error: "deploy_failed", message: errMessage(e) });
  }
}

async function listDeployments(ctx: ApiCtx): Promise<void> {
  const { res, app, url, secret, capability, actor } = ctx;
  const principalId = capability?.actorId ?? actor?.p ?? url.searchParams.get("principalId");
  if (!principalId) return sendJson(res, 200, { deployments: (await app.listDeployments()).map(deploymentView) });
  const visible = await app.listDeploymentsForViewer(principalId);
  const baseUrl = gitUrlBase(ctx);
  const deployments = await Promise.all(
    visible.map(async (d) => {
      if (!secret) return d;
      const git = await app.deploymentGitUrlFor(d.id, principalId, { secret, baseUrl });
      return git ? { ...d, gitUrl: git.url } : d;
    }),
  );
  return sendJson(res, 200, { deployments });
}

function textContentType(contentType: string): boolean {
  return (
    /^text\//i.test(contentType) ||
    /(?:^|\/)(?:json|xml|javascript)(?:;|$)/i.test(contentType) ||
    /\+(?:json|xml)(?:;|$)/i.test(contentType)
  );
}

const LOGS_DEFAULT_TAIL_LINES = 200;
const LOGS_MAX_TAIL_LINES = 2000;

async function deploymentLogs(ctx: ApiCtx): Promise<void> {
  const { res, app, params, capability, actor, url } = ctx;
  const viewer = capability?.actorId ?? actor?.p;
  if (!viewer) return sendJson(res, 401, { error: "capability_required" });
  const rawTail = url.searchParams.get("tailLines");
  const tailLines = rawTail === null ? LOGS_DEFAULT_TAIL_LINES : Number(rawTail);
  if (!Number.isInteger(tailLines) || tailLines < 1 || tailLines > LOGS_MAX_TAIL_LINES) {
    return sendJson(res, 400, {
      error: "bad_request",
      message: `tailLines must be an integer from 1 to ${LOGS_MAX_TAIL_LINES}`,
    });
  }
  const result = await app.deploymentLogsFor(params.id!, viewer, { tailLines });
  if (result.status !== "ok") return sendJson(res, 404, { error: "not_found" });
  if (result.logs === null) return sendJson(res, 200, { logs: null, message: "no logs available for this deployment" });
  return sendJson(res, 200, { logs: result.logs });
}

async function fetchDeployment(ctx: ApiCtx): Promise<void> {
  const { res, app, params, capability, actor, url } = ctx;
  const viewer = capability?.actorId ?? actor?.p;
  if (!viewer) return sendJson(res, 401, { error: "capability_required" });
  const path = normalizedDeploymentFetchPath(url.searchParams.get("path"));
  if (!path) return sendJson(res, 400, { error: "bad_request", message: "path must be a safe absolute path" });
  const rawMaxBytes = url.searchParams.get("maxBytes");
  const maxBytes = rawMaxBytes === null ? AGENT_FETCH_DEFAULT_MAX_BYTES : Number(rawMaxBytes);
  if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > AGENT_FETCH_MAX_BYTES) {
    return sendJson(res, 400, {
      error: "bad_request",
      message: `maxBytes must be an integer from 1 to ${AGENT_FETCH_MAX_BYTES}`,
    });
  }
  const reach = await app.reachDeployment(params.id!, viewer);
  if (reach.status !== "ok") return sendJson(res, 404, { error: "not_found" });
  try {
    const response = await fetchDeploymentResponse(reach, path, maxBytes);
    const rawContentType = response.headers["content-type"];
    const contentType = typeof rawContentType === "string" ? rawContentType : "application/octet-stream";
    if (textContentType(contentType)) {
      return sendJson(res, 200, {
        status: response.status,
        contentType,
        body: response.body.toString("utf8"),
        truncated: response.truncated,
      });
    }
    return sendJson(res, 200, {
      status: response.status,
      contentType,
      body: response.body.toString("base64"),
      encoding: "base64",
      truncated: response.truncated,
    });
  } catch {
    return sendJson(res, 502, { error: "upstream_unreachable" });
  }
}

export async function getDeployment(ctx: ApiCtx): Promise<void> {
  const { res, app, url, secret, capability, params } = ctx;
  const principalId = capability ? capability.actorId : url.searchParams.get("principalId");
  const id = params.id!;
  let deployment;
  if (principalId) {
    deployment = (await app.listDeploymentsForViewer(principalId)).find((d) => d.id === id || d.name === id);
  } else {
    const stored = (await app.listDeployments()).find((d) => d.id === id || d.name === id);
    deployment = stored ? deploymentView(stored) : undefined;
  }
  if (!deployment) return sendJson(res, 404, { error: "not_found" });
  if (!principalId || !secret) return sendJson(res, 200, { deployment });
  const git = await app.deploymentGitUrlFor(deployment.id, principalId, { secret, baseUrl: gitUrlBase(ctx) });
  return sendJson(res, 200, { deployment: git ? { ...deployment, gitUrl: git.url } : deployment });
}

async function rollbackDeployment(ctx: ApiCtx): Promise<void> {
  const { res, app, params, body } = ctx;
  const id = await deploymentId(app, params.id!);
  if (!id) return sendJson(res, 404, { error: "not_found" });
  if (!(await callerMayManageDeployment(ctx, id))) return sendJson(res, 403, { error: "forbidden" });
  const b = body as { version?: unknown };
  if (typeof b.version !== "number")
    return sendJson(res, 400, { error: "bad_request", message: "version (number) required" });
  try {
    await app.rollbackDeployment(id, b.version);
    return sendJson(res, 200, { ok: true });
  } catch (e) {
    return sendJson(res, 400, { error: "rollback_failed", message: errMessage(e) });
  }
}

async function redeployDeployment(ctx: ApiCtx): Promise<void> {
  const { res, app, params, body } = ctx;
  const id = await deploymentId(app, params.id!);
  if (!id) return sendJson(res, 404, { error: "not_found" });
  if (!(await callerMayManageDeployment(ctx, id))) return sendJson(res, 403, { error: "forbidden" });
  if (!isRedeployInput(body)) {
    return sendJson(res, 400, {
      error: "bad_request",
      message:
        "entrypoint (string) and files (array) required; env must be a string map, homeFiles an array, alwaysOn a boolean",
    });
  }
  try {
    return sendJson(res, 200, { deployment: deploymentView(await app.redeploy(id, body)) });
  } catch (e) {
    return sendJson(res, 400, { error: "deploy_failed", message: errMessage(e) });
  }
}

async function callerMayManageDeployment(ctx: ApiCtx, id: string): Promise<boolean> {
  const principalId = ctx.capability?.actorId ?? ctx.actor?.p;
  return !principalId || ctx.app.canManageDeployment(id, principalId, ctx.capability?.scopeId);
}

export async function archiveDeployment(ctx: ApiCtx): Promise<void> {
  const { res, app, params } = ctx;
  const id = await deploymentId(app, params.id!);
  if (!id) return sendJson(res, 404, { error: "not_found" });
  if (!(await callerMayManageDeployment(ctx, id)))
    return sendJson(res, 403, { error: "forbidden", message: "only someone who manages this app can archive it" });
  try {
    await app.archiveDeployment(id);
    return sendJson(res, 200, { ok: true });
  } catch (e) {
    return sendJson(res, 400, { error: "archive_failed", message: errMessage(e) });
  }
}

export async function restoreDeployment(ctx: ApiCtx): Promise<void> {
  const { res, app, params, capability, body } = ctx;
  const id = await deploymentId(app, params.id!);
  if (!id) return sendJson(res, 404, { error: "not_found" });
  if (!(await callerMayManageDeployment(ctx, id)))
    return sendJson(res, 403, { error: "forbidden", message: "only someone who manages this app can restore it" });
  try {
    const principalId =
      capability?.actorId ??
      ctx.actor?.p ??
      (isObj(body) && typeof body.principalId === "string" ? body.principalId : undefined);
    return sendJson(res, 200, {
      deployment: { ...deploymentView(await app.restoreDeployment(id, principalId)), permission: "write" },
    });
  } catch (e) {
    return sendJson(res, 400, { error: "restore_failed", message: errMessage(e) });
  }
}

export async function renameDeployment(ctx: ApiCtx): Promise<void> {
  const { res, app, params, body } = ctx;
  const id = await deploymentId(app, params.id!);
  if (!id) return sendJson(res, 404, { error: "not_found" });
  if (!(await callerMayManageDeployment(ctx, id)))
    return sendJson(res, 403, { error: "forbidden", message: "only someone who manages this app can rename it" });
  const b = body as { name?: unknown };
  if (typeof b.name !== "string")
    return sendJson(res, 400, { error: "bad_request", message: "name (string) required" });
  try {
    return sendJson(res, 200, { deployment: await app.renameDeployment(id, b.name) });
  } catch (e) {
    return sendJson(res, 400, { error: "rename_failed", message: errMessage(e) });
  }
}

export async function setDeploymentDisplayName(ctx: ApiCtx): Promise<void> {
  const { res, app, params, body } = ctx;
  const id = await deploymentId(app, params.id!);
  if (!id) return sendJson(res, 404, { error: "not_found" });
  if (!(await callerMayManageDeployment(ctx, id)))
    return sendJson(res, 403, { error: "forbidden", message: "only someone who manages this app can rename it" });
  const b = body as { displayName?: unknown };
  if (typeof b.displayName !== "string")
    return sendJson(res, 400, { error: "bad_request", message: "displayName (string) required" });
  try {
    return sendJson(res, 200, { deployment: await app.setDeploymentDisplayName(id, b.displayName) });
  } catch (e) {
    return sendJson(res, 400, { error: "display_name_failed", message: errMessage(e) });
  }
}

async function setDeploymentEmbedAncestors(ctx: ApiCtx): Promise<void> {
  const { res, app, params, body } = ctx;
  const id = await deploymentId(app, params.id!);
  if (!id) return sendJson(res, 404, { error: "not_found" });
  if (!(await callerMayManageDeployment(ctx, id)))
    return sendJson(res, 403, { error: "forbidden", message: "only someone who manages this app can change this" });
  const ancestors = parseEmbedAncestors((body as { embedAncestors?: unknown }).embedAncestors);
  if (!ancestors)
    return sendJson(res, 400, { error: "bad_request", message: `embedAncestors (${EMBED_ANCESTORS_HINT}) required` });
  try {
    return sendJson(res, 200, { deployment: deploymentView(await app.setDeploymentEmbedAncestors(id, ancestors)) });
  } catch (e) {
    return sendJson(res, 400, { error: "embed_ancestors_failed", message: errMessage(e) });
  }
}

async function setDeploymentAlwaysOn(ctx: ApiCtx): Promise<void> {
  const { res, app, params, body } = ctx;
  const id = await deploymentId(app, params.id!);
  if (!id) return sendJson(res, 404, { error: "not_found" });
  if (!(await callerMayManageDeployment(ctx, id)))
    return sendJson(res, 403, { error: "forbidden", message: "only someone who manages this app can change this" });
  const b = body as { alwaysOn?: unknown };
  if (typeof b.alwaysOn !== "boolean")
    return sendJson(res, 400, { error: "bad_request", message: "alwaysOn (boolean) required" });
  try {
    return sendJson(res, 200, { deployment: deploymentView(await app.setDeploymentAlwaysOn(id, b.alwaysOn)) });
  } catch (e) {
    return sendJson(res, 400, { error: "always_on_failed", message: errMessage(e) });
  }
}

type ShareTarget =
  | { kind: "ok"; scope: string; label: string }
  | { kind: "none" }
  | { kind: "ambiguous"; candidates: Array<{ principalId: string; displayName: string }> }
  | { kind: "invalid"; message: string };

export function resolveShareTarget(
  app: App,
  input: { scope?: string; recipient?: string; email?: string },
): Promise<ShareTarget> {
  return resolveShareTargetGrammar(app, input, {
    allowEmail: true,
    invalidScope: (scope) => `invalid scope "${scope}" — use "org" or a scope id like personal:<id> or org:<id>`,
    targetRequired: 'a target is required: pass `scope` ("org" or a scope id) or `recipient` (a teammate\'s name)',
  });
}

export async function getDeploymentShares(ctx: ApiCtx): Promise<void> {
  const { res, app, params, capability } = ctx;
  if (!capability) return sendJson(res, 403, { error: "forbidden" });
  const deployment = await app.getDeployment(params.id!);
  if (!deployment) return sendJson(res, 404, { error: "not_found" });
  if (deployment.ownerScopeId !== `personal:${capability.actorId}`)
    return sendJson(res, 403, { error: "forbidden", message: "Only the owner can edit app permissions." });
  const externalSharing = await externalAppSharingAllowed(ctx.deps.featureFlags, deployment.ownerScopeId);
  return sendJson(res, 200, {
    public: deployment.public === true && externalSharing,
    externalSharing,
    grantees: await app.deploymentGrantees(deployment.id),
  });
}

export async function shareDeployment(ctx: ApiCtx): Promise<void> {
  const { res, app, params, body, capability } = ctx;
  if (!capability)
    return sendJson(res, 403, { error: "forbidden", message: "sharing requires an agent capability token" });
  const b = (isObj(body) ? body : {}) as {
    scope?: unknown;
    recipient?: unknown;
    email?: unknown;
    access?: unknown;
    public?: unknown;
  };
  if (b.public !== undefined) {
    if (typeof b.public !== "boolean")
      return sendJson(res, 400, { error: "bad_request", message: "public must be a boolean" });
    if (b.scope !== undefined || b.recipient !== undefined || b.email !== undefined || b.access !== undefined)
      return sendJson(res, 400, {
        error: "bad_request",
        message: "public access and person/scope access must be changed separately",
      });
    try {
      const deployment = await app.setDeploymentPublic(params.id!, b.public, { createdBy: capability.actorId });
      return sendJson(res, 200, {
        ok: true,
        public: deployment.public === true,
        reach: deployment.public === true ? "anyone with the link" : "restricted",
        grantees: await app.deploymentGrantees(deployment.id),
      });
    } catch (e) {
      return sendShareFailure(res, e);
    }
  }
  if (b.email !== undefined && typeof b.email !== "string")
    return sendJson(res, 400, { error: "bad_request", message: "email must be a string" });
  if (b.email !== undefined && (b.scope !== undefined || b.recipient !== undefined))
    return sendJson(res, 400, { error: "bad_request", message: "pass only one of email, scope, or recipient" });
  const access = typeof b.access === "string" ? b.access.toLowerCase() : "view";
  if (access !== "view" && access !== "manage" && access !== "none") {
    return sendJson(res, 400, { error: "bad_request", message: 'access must be "view", "manage", or "none"' });
  }
  let permission: Permission | null = "read";
  if (access === "none") permission = null;
  else if (access === "manage") permission = "write";
  const target = await resolveShareTarget(app, {
    ...(typeof b.scope === "string" ? { scope: b.scope } : {}),
    ...(typeof b.recipient === "string" ? { recipient: b.recipient } : {}),
    ...(typeof b.email === "string" ? { email: b.email } : {}),
  });
  if (target.kind === "invalid") return sendJson(res, 400, { error: "bad_request", message: target.message });
  if (target.kind === "none")
    return sendJson(res, 404, {
      error: "recipient_not_found",
      message: `no teammate matches "${String(b.recipient)}"`,
    });
  if (target.kind === "ambiguous")
    return sendJson(res, 409, {
      error: "ambiguous_recipient",
      message: "more than one teammate matches",
      candidates: target.candidates,
    });
  try {
    const invite =
      typeof b.email === "string" && permission === "read"
        ? await app.inviteToDeployment(params.id!, b.email, capability.actorId)
        : undefined;
    const grantees =
      invite?.grantees ??
      (await app.shareDeployment(params.id!, target.scope, permission, { createdBy: capability.actorId }));
    const orgGrant = grantees.find((g) => parseScopeId(g.scope).kind === "org");
    let reach = "owner-only";
    if (orgGrant) reach = `everyone in ${parseScopeId(orgGrant.scope).ref}`;
    else if (grantees.length) reach = `${grantees.length} grantee${grantees.length === 1 ? "" : "s"}`;
    const deployment = await app.getDeployment(params.id!);
    return sendJson(res, 200, {
      ok: true,
      target: { scope: target.scope, label: target.label },
      access,
      reach,
      ...(invite ? { invitation: invite.invitation } : {}),
      public:
        deployment?.public === true &&
        (await externalAppSharingAllowed(ctx.deps.featureFlags, deployment.ownerScopeId)),
      grantees,
    });
  } catch (e) {
    return sendShareFailure(res, e);
  }
}

const DEPLOY_ACCESS_STATUS: Record<DeployAccessErrorCode, number> = {
  not_found: 404,
  forbidden: 403,
  external_sharing_disabled: 403,
  public_links_unavailable: 409,
};

function sendShareFailure(res: ApiCtx["res"], e: unknown): void {
  if (e instanceof DeployAccessError)
    return sendJson(res, DEPLOY_ACCESS_STATUS[e.code], { error: e.code, message: e.message });
  return sendJson(res, 400, { error: "share_failed", message: errMessage(e) });
}

export const deploymentRawRoutes: ReadonlyArray<Route<BaseCtx>> = [
  { match: isDeploymentGitRoute, auth: "public", handle: serveDeploymentGit },
  {
    match: (m, p) =>
      p.startsWith("/v1/admin/deployments/") &&
      p.includes("/proxy") &&
      ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"].includes(m),
    auth: "source",
    handle: proxyAdminDeployment,
  },
  { match: (_m, p) => p.startsWith("/d/"), auth: "source", handle: proxyDeployment },
];

export const deploymentRoutes: ReadonlyArray<Route<ApiCtx>> = [
  { method: "POST", path: "/v1/deployments", actor: "body.createdBy", auth: "source", handle: createDeployment },
  { method: "GET", path: "/v1/deployments", actor: "query.principalId", auth: "either", handle: listDeployments },
  { method: "GET", path: "/v1/deployments/:id", auth: "either", handle: getDeployment },
  { method: "GET", path: "/v1/deployments/:id/fetch", auth: "either", handle: fetchDeployment },
  { method: "GET", path: "/v1/deployments/:id/logs", auth: "either", handle: deploymentLogs },
  { method: "GET", path: "/v1/deployments/:id/git-url", auth: "either", handle: deploymentGitUrl },
  { method: "GET", path: "/v1/deployments/:id/share", actor: "person", auth: "either", handle: getDeploymentShares },
  { method: "POST", path: "/v1/deployments/:id/share", auth: "either", handle: shareDeployment },
  { method: "POST", path: "/v1/deployments/:id/rollback", auth: "source", handle: rollbackDeployment },
  { method: "POST", path: "/v1/deployments/:id/redeploy", auth: "source", handle: redeployDeployment },
  { method: "POST", path: "/v1/deployments/:id/archive", auth: "either", handle: archiveDeployment },
  { method: "POST", path: "/v1/deployments/:id/restore", auth: "either", handle: restoreDeployment },
  { method: "POST", path: "/v1/deployments/:id/name", auth: "either", handle: renameDeployment },
  { method: "POST", path: "/v1/deployments/:id/display-name", auth: "either", handle: setDeploymentDisplayName },
  { method: "POST", path: "/v1/deployments/:id/always-on", auth: "either", handle: setDeploymentAlwaysOn },
  { method: "POST", path: "/v1/deployments/:id/embed-ancestors", auth: "either", handle: setDeploymentEmbedAncestors },
];