@liiift-studio/deploy-vercel-from-sanity 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liiift-studio/deploy-vercel-from-sanity",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Sanity Studio plugin — trigger and monitor Vercel deployments with full status, history, and build logs. Supports Studio v3.30 through v6.",
   "license": "MIT",
   "author": "Liiift Studio",
@@ -22,16 +22,21 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
       "default": "./dist/index.mjs"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
-    "src"
+    "proxy"
   ],
   "scripts": {
     "build": "tsup",
@@ -43,7 +48,7 @@
     "@sanity/ui": ">=2 <5",
     "react": ">=18",
     "react-dom": ">=18",
-    "sanity": ">=3.30"
+    "sanity": ">=3.30 <7"
   },
   "devDependencies": {
     "@sanity/icons": "^5",
@@ -51,10 +56,10 @@
     "@types/react": "^19",
     "@types/react-dom": "^19.2.4",
     "react": "^19",
+    "react-dom": "^19",
     "sanity": "^6",
     "tsup": "^8",
-    "typescript": "^5",
-    "react-dom": "^19"
+    "typescript": "^5"
   },
   "repository": {
     "type": "git",
@@ -62,6 +67,6 @@
   },
   "sideEffects": true,
   "engines": {
-    "node": ">=20.19"
+    "node": ">=20.19 <22 || >=22.12"
   }
 }

package/proxy/.env.example

@@ -0,0 +1,40 @@
+# Vercel API token. Scope it to the Team that owns these projects — not Full Account.
+VERCEL_API_TOKEN=
+
+# One hook per deploy target. The suffix after VERCEL_DEPLOY_HOOK_ is the proxyKey
+# you set on the target document in Sanity (case-insensitive).
+VERCEL_DEPLOY_HOOK_PRODUCTION=https://api.vercel.com/v1/integrations/deploy/prj_xxx/yyy
+VERCEL_DEPLOY_HOOK_STAGING=https://api.vercel.com/v1/integrations/deploy/prj_xxx/zzz
+
+# Project details for status lookups: projectId:hookId[:teamId]
+# Both ids are the two path segments of the hook URL above.
+VERCEL_DEPLOY_PROJECT_PRODUCTION=prj_xxx:yyy
+VERCEL_DEPLOY_PROJECT_STAGING=prj_xxx:zzz
+
+# Secret configured on the Sanity webhook. This is what makes the deploy endpoint
+# safe to expose — without it, anyone could POST it and trigger a build.
+SANITY_WEBHOOK_SECRET=
+
+# Sent by the Studio with status, log and cancel requests. Must hold the SAME value
+# as the plugin's `statusKey` option. Generate one with: openssl rand -hex 16
+#
+# It ships inside the Studio bundle, so treat it as public. It permits reading
+# deployment status and build logs for the targets configured above, and
+# cancelling their in-progress deployments — cancel is a write, so this is not a
+# read-only key. Requests are scoped to the configured projects.
+#
+# Required. If unset, status requests fail closed with a 500.
+VERCEL_DEPLOY_STATUS_KEY=
+
+# Origins allowed to call the status endpoints, comma-separated. The Studio is
+# cross-origin and sends a custom header, so the browser preflights every call and
+# blocks it without this.
+VERCEL_DEPLOY_ALLOWED_ORIGINS=https://your-project.sanity.studio,http://localhost:3333
+
+# Optional. Restrict deploys further than Sanity's write ACL already does.
+# Without this, anyone who can create a document can deploy — which excludes
+# viewers, since they cannot write. Set it to require specific roles.
+# VERCEL_DEPLOY_ALLOWED_ROLES=administrator,editor
+# SANITY_PROJECT_ID=
+# SANITY_DATASET=production
+# SANITY_READ_TOKEN=

package/proxy/README.md

@@ -0,0 +1,228 @@
+# Deploy proxy
+
+Optional. Use this if you need **editors and above to trigger deploys, without any
+credential being stealable from the dataset**.
+
+## Why it exists
+
+In the default (`direct`) mode the Studio talks to Vercel itself. That means two
+things live in the dataset:
+
+- the **Vercel API token**, in a `config.vercelDeploy` document
+- a **deploy hook URL** on every target
+
+Sanity has no per-document access control, so both are readable by everyone who
+can read the dataset — and if the dataset is public, by anyone at all. The hook
+URL matters as much as the token: it *is* the deploy credential, so restricting
+the Deploy tool to editors does nothing while a viewer can read the URL and
+`curl` it.
+
+Proxy mode moves both to a server you control. The Studio holds no credential.
+
+## How it works
+
+```
+Deploy   Studio creates a vercelDeploy.request document
+         └─ Sanity's write ACL authorises this. Viewers cannot write, so they cannot deploy.
+         └─ Sanity webhook (signed) ──▶ proxy ──▶ POSTs the hook URL from its own env
+
+Status   Studio ──▶ proxy /deployments|/events|/cancel ──▶ Vercel API with the server-held token
+```
+
+The only value that reaches the browser is a **status key**. It permits reading
+deployment status and build logs for the configured **projects**, and cancelling
+their in-progress deployments — cancel is a write, so this is not a read-only key.
+It ships inside the Studio bundle, so treat it as public.
+
+Read [What this does not solve](#what-this-does-not-solve) before deciding this is
+enough for your threat model.
+
+## Setup
+
+Roughly 15 minutes.
+
+### 1. Add the route
+
+Copy `core.ts` and `nextjs-app-router/route.ts` into your Next.js app:
+
+```
+app/api/vercel-deploy/[...path]/route.ts   ← nextjs-app-router/route.ts
+app/api/vercel-deploy/core.ts              ← core.ts
+```
+
+`route.ts` imports `parseBody` from `next-sanity`, so install it if you have not:
+
+```sh
+npm i next-sanity
+```
+
+Not on Next.js? `core.ts` has no framework dependency. Wrap it in your own handler
+and verify the Sanity webhook signature before calling `handleDeployRequest` —
+that verification is the only thing standing between the endpoint and an
+unauthenticated deploy trigger.
+
+### 2. Set environment variables
+
+See `.env.example`. The two per-target ones:
+
+```sh
+VERCEL_DEPLOY_HOOK_PRODUCTION=https://api.vercel.com/v1/integrations/deploy/prj_xxx/yyy
+VERCEL_DEPLOY_PROJECT_PRODUCTION=prj_xxx:yyy
+```
+
+`prj_xxx` and `yyy` are the last two path segments of the hook URL. The suffix
+after the prefix (`PRODUCTION`) is the **proxy key** you put on the target
+document; it is matched case-insensitively. Environment variable names cannot
+contain hyphens, so keys must be `[A-Za-z0-9_]` — use `my_site`, not `my-site`.
+
+For a team-owned project, append the team id — `projectId:hookId:teamId`. **The
+Team ID field on the target document is ignored in proxy mode**; the proxy reads
+it from here, because the Studio never talks to Vercel.
+
+Scope `VERCEL_API_TOKEN` to the **Team** that owns the projects, not Full Account.
+
+`VERCEL_DEPLOY_STATUS_KEY` and the plugin's `statusKey` must hold the **same
+value**. Generate one with `openssl rand -hex 16`. The proxy fails closed — if the
+server-side variable is unset, status requests return 500 rather than serving
+everyone.
+
+Set `VERCEL_DEPLOY_ALLOWED_ORIGINS` to your Studio's origin(s), comma-separated —
+for example `https://acme.sanity.studio,http://localhost:3333`. The Studio is
+cross-origin and sends a custom header, so without this the browser blocks every
+status call at the preflight.
+
+### 3. Add the Sanity webhook
+
+Sanity → Project → API → Webhooks → Create:
+
+Use a **GROQ-powered webhook**, not a legacy one.
+
+| Field | Value |
+| --- | --- |
+| URL | `https://your-site.com/api/vercel-deploy/deploy` |
+| Dataset | your dataset |
+| Trigger on | Create |
+| Filter | `_type == "vercelDeploy.request"` |
+| Projection | *leave empty* — the proxy needs both `proxyKey` and `_createdBy` |
+| HTTP method | POST |
+| Secret | same value as `SANITY_WEBHOOK_SECRET` |
+
+The secret must match byte for byte; `parseBody` verifies the
+`sanity-webhook-signature` header against it and rejects anything else.
+
+### 4. Point the plugin at it
+
+`SANITY_STUDIO_DEPLOY_STATUS_KEY` goes in the **Studio's** `.env`, not the proxy's.
+Sanity only inlines variables prefixed `SANITY_STUDIO_`, and it inlines them at
+**build time** — so it must be present wherever you run `sanity build` / `sanity
+deploy`, and changing it needs a rebuild. If it is missing the header is omitted
+entirely and the proxy answers 401, which reads like a mismatch rather than an
+absence.
+
+```ts
+vercelDeploy({
+  mode: 'proxy',
+  proxyUrl: 'https://your-site.com/api/vercel-deploy',
+  statusKey: process.env.SANITY_STUDIO_DEPLOY_STATUS_KEY,
+})
+```
+
+### 5. Set a proxy key on each target
+
+In the Deploy tool, each target now asks for a **Proxy Key** instead of a hook
+URL. Use the same suffix as the environment variables — `production`, `staging`.
+
+## Verify it worked
+
+Status path — expect `{"deployments":[…]}`. `{"error":"Unknown target key"}` is
+also JSON, so read the body, not just the status:
+
+```sh
+curl -s -H "x-deploy-status-key: $VERCEL_DEPLOY_STATUS_KEY" \
+  "https://your-site.com/api/vercel-deploy/deployments?key=production"
+```
+
+CORS — curl does not implement CORS, so the call above passes even with
+`VERCEL_DEPLOY_ALLOWED_ORIGINS` unset. Check the preflight explicitly and look for
+`Access-Control-Allow-Origin` in the response headers:
+
+```sh
+curl -si -X OPTIONS \
+  -H "Origin: https://your-project.sanity.studio" \
+  -H "Access-Control-Request-Method: GET" \
+  -H "Access-Control-Request-Headers: x-deploy-status-key" \
+  "https://your-site.com/api/vercel-deploy/deployments" | head -20
+```
+
+Deploy path — click **Deploy** in the Studio, then check, in order:
+
+1. **Sanity → API → Webhooks → your webhook → delivery log.** This is where the
+   proxy's response lands. The Studio never sees it, so a 400/403/404/502 here is
+   invisible in the UI and this log is the only place it appears.
+2. A new `vercelDeploy.request` document exists. If not, the click failed
+   client-side — check the browser console.
+3. A new deployment in Vercel.
+
+## When the webhook fires but nothing deploys
+
+| Symptom in the delivery log | Cause |
+| --- | --- |
+| `400 Request document has no proxyKey` | The target has no Proxy Key set |
+| `404 No hook configured for key "…"` | Key does not match any `VERCEL_DEPLOY_HOOK_*` variable |
+| `403 Requesting user is not permitted` | `VERCEL_DEPLOY_ALLOWED_ROLES` excludes the requester |
+| `502 Deploy hook returned …` | Vercel rejected the hook — check it still exists |
+| `401 Invalid signature` | `SANITY_WEBHOOK_SECRET` does not match the webhook's secret |
+| `500 Missing SANITY_WEBHOOK_SECRET` | The variable is not set on the proxy |
+| `403 Request document has no creator` | `_createdBy` was absent — the webhook has a projection set; leave it empty |
+| An opaque 500 with no body | `VERCEL_DEPLOY_ALLOWED_ROLES` is set without `SANITY_PROJECT_ID` / `SANITY_READ_TOKEN` |
+| An SSO/login page instead of JSON | **Vercel Deployment Protection** is on for the app hosting the proxy. Use Protection Bypass for Automation, or add the route to the **OPTIONS Allowlist**. This breaks the *status* path too — a preflight from the Studio gets the SSO challenge, which surfaces as a blocked CORS request rather than an auth error. |
+
+Status shows nothing while deploys work? That is the CORS or status-key path, not
+the webhook — check the browser console for a blocked preflight, and confirm both
+sides hold the same status key.
+
+## Who can deploy
+
+By default: anyone Sanity lets create a document. That already excludes viewers,
+which is usually what "editors and above" means in practice.
+
+To require specific roles, set `VERCEL_DEPLOY_ALLOWED_ROLES` plus the `SANITY_*`
+variables. The proxy then looks up the roles of the user in `_createdBy` — a field
+Sanity stamps and the client cannot forge — and rejects anything not on the list.
+Note that `contributor` can also write, so include it explicitly or exclude it
+deliberately.
+
+## What this does not solve
+
+**The status key is effectively public, and it can do more than read.** A hosted
+Studio bundle is fetchable without logging in, and the key is compiled into it. So
+in the worst case anyone on the internet can: list your deployments (which yields
+deployment ids), read their build logs, and **cancel an in-progress production
+build**. `VERCEL_DEPLOY_ALLOWED_ORIGINS` does not prevent this — CORS constrains
+browsers, not `curl`.
+
+**Build logs can contain secrets.** A failed build that dumps `process.env`, a
+registry 401 echoing a token, a stack trace with a connection string — all of that
+is returned to a status-key holder. Do not treat log exposure as harmless.
+
+If that is unacceptable, do not rely on the status key alone: put the proxy behind
+network controls, or drop `statusKey` usage and accept losing status while keeping
+the deploy path, which is properly gated by the signed webhook and Sanity's write
+ACL.
+
+**Scoping is per project, not per target.** `assertDeploymentInProject` checks the
+deployment's `projectId`. A key holder can therefore read logs for, and cancel, any
+deployment in a configured project — including git-push deployments the plugin's UI
+never lists — but nothing outside those projects.
+
+**Role gating is proxy-wide.** `VERCEL_DEPLOY_ALLOWED_ROLES` is one list for all
+targets; there is no "contributors may deploy staging but not production."
+
+**Request documents accumulate** unless you prune them. The proxy does not delete
+them, so they double as an audit trail of who deployed what and when. Their type is
+not registered in the schema, so they appear in the Studio as "Unknown document
+type" if you browse to one — that is expected, not a bug.
+
+**`assertDeploymentInProject` assumes** `GET /v13/deployments/{id}` returns a
+top-level `projectId`. If Vercel ever changes that, the proxy returns a loud 502
+rather than silently allowing or denying.

package/proxy/core.ts

@@ -0,0 +1,283 @@
+// Framework-agnostic deploy proxy — holds the Vercel token and hook URLs so the Studio never does
+//
+// Copy this file, and one of the runtime wrappers next to it, into your own
+// project. It has no dependency on the Sanity plugin.
+
+/** Environment the proxy needs. Everything here is a server-side secret except TARGETS' keys. */
+export interface ProxyEnv {
+	/** Vercel API token. Scope it to the Team that owns the projects, not Full Account. */
+	vercelToken: string
+	/**
+	 * Map of proxy key to Vercel deploy hook URL, e.g.
+	 * `{ production: 'https://api.vercel.com/v1/integrations/deploy/prj_.../...' }`.
+	 * These are deploy credentials — they belong here, not in the dataset.
+	 */
+	hooks: Record<string, string>
+	/**
+	 * Map of proxy key to the project the hook belongs to, used for status lookups:
+	 * `{ production: { projectId: 'prj_…', hookId: '…', teamId: 'team_…' } }`.
+	 * projectId and hookId are the last two path segments of the deploy hook URL.
+	 */
+	projects: Record<string, { projectId: string; hookId: string; teamId?: string }>
+	/**
+	 * Key the Studio sends with status, log and cancel requests.
+	 *
+	 * Present in the Studio bundle and therefore public. It permits reading
+	 * deployment status and build logs for the configured targets, and cancelling
+	 * their in-progress deployments — cancel is a write, so this is not a read-only
+	 * key. Requests are scoped to the configured projects. Required.
+	 */
+	statusKey?: string
+	/**
+	 * Sanity roles permitted to deploy, checked against the requesting user.
+	 * Omit to accept anyone Sanity's write ACL already let create the request —
+	 * which excludes viewers, since they cannot write at all.
+	 */
+	allowedRoles?: string[]
+	/** Sanity project id, dataset and a read token — only needed when `allowedRoles` is set. */
+	sanity?: { projectId: string; dataset: string; readToken: string }
+}
+
+/** Minimal shape of the webhook payload the Studio's request document produces. */
+export interface DeployRequestPayload {
+	_id?: string
+	_type?: string
+	proxyKey?: string
+	/** Sanity stamps this; the client cannot forge it. */
+	_createdBy?: string
+}
+
+/** Result of handling a request, ready to be turned into a runtime response. */
+export interface ProxyResult {
+	status: number
+	body: unknown
+}
+
+const VERCEL_API = 'https://api.vercel.com'
+
+/** Only genuine Vercel deploy hooks are ever POSTed to. */
+const VERCEL_HOOK_RE = /^https:\/\/api\.vercel\.com\/v1\/integrations\/deploy\//
+
+/** Call the Vercel API with the server-held token. */
+async function vercel<T>(path: string, env: ProxyEnv, init?: RequestInit): Promise<T> {
+	const res = await fetch(`${VERCEL_API}${path}`, {
+		...init,
+		headers: {
+			Authorization: `Bearer ${env.vercelToken}`,
+			'Content-Type': 'application/json',
+			...init?.headers,
+		},
+	})
+	if (!res.ok) throw new Error(`Vercel API ${res.status}`)
+	return res.json() as Promise<T>
+}
+
+/**
+ * Look up the Sanity roles of the user who created the request document.
+ *
+ * Only used when `allowedRoles` is set. Without it, authorisation is already
+ * handled by Sanity's write ACL — a viewer cannot create the document at all.
+ */
+async function userRoles(userId: string, env: ProxyEnv): Promise<string[]> {
+	if (!env.sanity) throw new Error('allowedRoles is set but sanity config is missing')
+	const { projectId, readToken } = env.sanity
+	const res = await fetch(`https://api.sanity.io/v2021-06-07/projects/${projectId}/acl`, {
+		headers: { Authorization: `Bearer ${readToken}` },
+	})
+	if (!res.ok) throw new Error(`Sanity ACL lookup failed: ${res.status}`)
+	const acl = (await res.json()) as Array<{ userId: string; roles?: Array<{ name: string }> }>
+	const entry = acl.find(a => a.userId === userId)
+	return entry?.roles?.map(r => r.name) ?? []
+}
+
+/**
+ * Handle a verified deploy-request webhook.
+ *
+ * The caller MUST have verified the Sanity webhook signature before calling this
+ * — see the runtime wrappers. An unverified payload is an unauthenticated deploy
+ * trigger.
+ *
+ * @param payload Parsed webhook body for the created request document.
+ * @param env     Proxy environment.
+ */
+export async function handleDeployRequest(payload: DeployRequestPayload, env: ProxyEnv): Promise<ProxyResult> {
+	// Lowercased to match envFromProcess, which lowercases the env-var side. Without
+	// this, a target typed as "Production" would 404 against a PRODUCTION env var.
+	const key = payload.proxyKey?.trim().toLowerCase()
+	if (!key) return { status: 400, body: { error: 'Request document has no proxyKey' } }
+
+	const hook = env.hooks[key]
+	if (!hook) return { status: 404, body: { error: `No hook configured for key "${key}"` } }
+	if (!VERCEL_HOOK_RE.test(hook)) return { status: 500, body: { error: `Hook for "${key}" is not a Vercel deploy hook` } }
+
+	if (env.allowedRoles?.length) {
+		const userId = payload._createdBy
+		if (!userId) return { status: 403, body: { error: 'Request document has no creator' } }
+		const roles = await userRoles(userId, env)
+		if (!roles.some(r => env.allowedRoles!.includes(r))) {
+			return { status: 403, body: { error: 'Requesting user is not permitted to deploy' } }
+		}
+	}
+
+	const res = await fetch(hook, { method: 'POST' })
+	if (!res.ok) return { status: 502, body: { error: `Deploy hook returned ${res.status}` } }
+	return { status: 200, body: { ok: true, key } }
+}
+
+/**
+ * Reject a request whose status key does not match.
+ *
+ * Fails closed: an unset key rejects everything rather than serving everyone. The
+ * previous behaviour left cancellation open to unauthenticated callers, since
+ * cancel is gated by this same check.
+ */
+function checkStatusKey(provided: string | null, env: ProxyEnv): ProxyResult | null {
+	if (!env.statusKey) {
+		return { status: 500, body: { error: 'VERCEL_DEPLOY_STATUS_KEY is not configured' } }
+	}
+	return provided === env.statusKey ? null : { status: 401, body: { error: 'Invalid status key' } }
+}
+
+/**
+ * Confirm a deployment actually belongs to the project behind `key`.
+ *
+ * Without this, `deploymentId` is caller-supplied and the project lookup only
+ * supplies `teamId` — so a team-scoped token would let any holder of the (public)
+ * status key read build logs for, or cancel, any deployment in the whole team.
+ *
+ * @param deploymentId Deployment the caller is asking about.
+ * @param project      Project configured for the requested proxy key.
+ */
+async function assertDeploymentInProject(
+	deploymentId: string,
+	project: { projectId: string; teamId?: string },
+	env: ProxyEnv,
+): Promise<ProxyResult | null> {
+	const query = new URLSearchParams()
+	if (project.teamId) query.set('teamId', project.teamId)
+	const suffix = query.toString() ? `?${query}` : ''
+	let deployment: { projectId?: string }
+	try {
+		deployment = await vercel<{ projectId?: string }>(
+			`/v13/deployments/${encodeURIComponent(deploymentId)}${suffix}`,
+			env,
+		)
+	} catch (err) {
+		// Distinguish an unknown deployment from a broken token or a rate limit —
+		// collapsing all three into 404 makes a revoked token look like a UI bug.
+		const status = Number(String(err instanceof Error ? err.message : '').match(/\b(\d{3})\b/)?.[1])
+		if (status === 401 || status === 403) {
+			return { status: 502, body: { error: 'Vercel rejected the proxy token — check VERCEL_API_TOKEN' } }
+		}
+		if (status === 429) return { status: 429, body: { error: 'Vercel rate limit reached' } }
+		return { status: 404, body: { error: 'Deployment not found' } }
+	}
+	if (!deployment.projectId) {
+		// Loud rather than silently denying forever if the API shape ever changes.
+		return { status: 502, body: { error: 'Vercel returned no projectId; cannot verify deployment ownership' } }
+	}
+	if (deployment.projectId !== project.projectId) {
+		return { status: 403, body: { error: 'Deployment does not belong to this target' } }
+	}
+	return null
+}
+
+/** List recent deployments for a proxy key. */
+export async function handleDeployments(
+	params: { key: string | null; limit?: number; statusKey: string | null },
+	env: ProxyEnv,
+): Promise<ProxyResult> {
+	const denied = checkStatusKey(params.statusKey, env)
+	if (denied) return denied
+	const project = params.key ? env.projects[params.key.trim().toLowerCase()] : undefined
+	if (!project) return { status: 404, body: { error: 'Unknown target key' } }
+
+	const query = new URLSearchParams({
+		projectId: project.projectId,
+		'meta-deployHookId': project.hookId,
+		limit: String(params.limit ?? 10),
+	})
+	if (project.teamId) query.set('teamId', project.teamId)
+	const data = await vercel<{ deployments: unknown[] }>(`/v6/deployments?${query}`, env)
+	return { status: 200, body: { deployments: data.deployments ?? [] } }
+}
+
+/** Fetch build log events for a deployment. */
+export async function handleEvents(
+	params: { key: string | null; deploymentId: string | null; statusKey: string | null },
+	env: ProxyEnv,
+): Promise<ProxyResult> {
+	const denied = checkStatusKey(params.statusKey, env)
+	if (denied) return denied
+	const project = params.key ? env.projects[params.key.trim().toLowerCase()] : undefined
+	if (!project) return { status: 404, body: { error: 'Unknown target key' } }
+	if (!params.deploymentId) return { status: 400, body: { error: 'Missing deploymentId' } }
+	const wrongProject = await assertDeploymentInProject(params.deploymentId, project, env)
+	if (wrongProject) return wrongProject
+
+	// direction=backward returns the *newest* events. Without it Vercel returns the
+	// first 100, so a failed build showed the top of its log and never the error.
+	const query = new URLSearchParams({ limit: '100', direction: 'backward' })
+	if (project.teamId) query.set('teamId', project.teamId)
+	const raw = await vercel<unknown>(
+		`/v2/deployments/${encodeURIComponent(params.deploymentId)}/events?${query}`,
+		env,
+	)
+	// Vercel has returned both a bare array and a wrapped object here; tolerate both.
+	const events = Array.isArray(raw)
+		? raw
+		: Array.isArray((raw as { events?: unknown[] })?.events)
+			? (raw as { events: unknown[] }).events
+			: []
+	return { status: 200, body: { events } }
+}
+
+/** Cancel an in-progress deployment. */
+export async function handleCancel(
+	params: { key?: string; deploymentId?: string; statusKey: string | null },
+	env: ProxyEnv,
+): Promise<ProxyResult> {
+	const denied = checkStatusKey(params.statusKey, env)
+	if (denied) return denied
+	const project = params.key ? env.projects[params.key.trim().toLowerCase()] : undefined
+	if (!project) return { status: 404, body: { error: 'Unknown target key' } }
+	if (!params.deploymentId) return { status: 400, body: { error: 'Missing deploymentId' } }
+	const wrongProject = await assertDeploymentInProject(params.deploymentId, project, env)
+	if (wrongProject) return wrongProject
+
+	const query = new URLSearchParams()
+	if (project.teamId) query.set('teamId', project.teamId)
+	const suffix = query.toString() ? `?${query}` : ''
+	await vercel(`/v12/deployments/${encodeURIComponent(params.deploymentId)}/cancel${suffix}`, env, {
+		method: 'PATCH',
+	})
+	return { status: 200, body: { ok: true } }
+}
+
+/** Build a {@link ProxyEnv} from process.env, using the documented variable names. */
+export function envFromProcess(e: Record<string, string | undefined>): ProxyEnv {
+	const hooks: ProxyEnv['hooks'] = {}
+	const projects: ProxyEnv['projects'] = {}
+	// VERCEL_DEPLOY_HOOK_<KEY> and VERCEL_DEPLOY_PROJECT_<KEY> pairs define the targets.
+	for (const [name, value] of Object.entries(e)) {
+		if (!value) continue
+		const hookMatch = name.match(/^VERCEL_DEPLOY_HOOK_(.+)$/)
+		if (hookMatch) hooks[hookMatch[1].toLowerCase()] = value
+		const projMatch = name.match(/^VERCEL_DEPLOY_PROJECT_(.+)$/)
+		if (projMatch) {
+			const [projectId, hookId, teamId] = value.split(':')
+			projects[projMatch[1].toLowerCase()] = { projectId, hookId, teamId: teamId || undefined }
+		}
+	}
+	const allowedRoles = e.VERCEL_DEPLOY_ALLOWED_ROLES?.split(',').map(r => r.trim()).filter(Boolean)
+	return {
+		vercelToken: e.VERCEL_API_TOKEN ?? '',
+		hooks,
+		projects,
+		statusKey: e.VERCEL_DEPLOY_STATUS_KEY,
+		allowedRoles: allowedRoles?.length ? allowedRoles : undefined,
+		sanity: e.SANITY_PROJECT_ID && e.SANITY_READ_TOKEN
+			? { projectId: e.SANITY_PROJECT_ID, dataset: e.SANITY_DATASET ?? 'production', readToken: e.SANITY_READ_TOKEN }
+			: undefined,
+	}
+}