@liiift-studio/deploy-vercel-from-sanity 1.2.1 → 1.3.1

package/README.md

@@ -8,31 +8,51 @@
 
 ![The Deploy tool inside Sanity Studio — Production and Preview targets each showing a live status badge, branch, commit SHA, deploy author, and a one-click Deploy button](https://raw.githubusercontent.com/Liiift-Studio/Deploy-Vercel-from-Sanity/main/docs/screenshot.png?v=1)
 
+> **Using Sanity but not setting it up?** Your developer installs this once. Day
+> to day you'll only use the **Deploy** tab — see [Using it day to day](#using-it-day-to-day).
+
+```bash
+npm install @liiift-studio/deploy-vercel-from-sanity
+```
+
 ---
 
-## Features
+## Why this one
 
-- **One-click deploy** — trigger Production or Preview builds from inside Sanity Studio
-- **Live status** with automatic polling — Queued → Building → Ready / Error
-- **Build timer** showing elapsed time while a deploy is in progress
-- **Cancel** in-progress deployments
-- **Deploy-complete notifications** — Studio toast when a build finishes, errors, or is canceled
-- **Copy deployment URL** with one click
-- **GitHub commit links** — commit SHA links directly to the GitHub commit when repo metadata is available
-- **Inline error log viewer** — see build errors without leaving the studio
-- **Deployment history** per target
-- **"Open in Vercel"** link to your project dashboard
-- **Multiple targets** — configure Production, Preview, and any number of custom environments
-- **Shared API token** — set it once; readable by anyone who can read the dataset (see [Security](#security))
-- **Responsive grid layout** — cards reflow to fill the available width, one column on narrow viewports
+There is an established alternative, [`sanity-plugin-vercel-deploy`](https://www.npmjs.com/package/sanity-plugin-vercel-deploy). Reasons you might pick this instead:
+
+- **One build spans Studio v3.30 → v6.** `@sanity/icons` v5 and `@sanity/ui` v4 both moved components out of their barrels; this plugin resolves them from the installed package at runtime rather than shipping a version-locked build. See [Studio compatibility](#studio-compatibility).
+- **[Proxy mode](#two-modes)** keeps the Vercel token — and the deploy hook URLs — off the dataset entirely, so viewers cannot read a credential or trigger a build. (The browser still holds a status key that can cancel a running build; see [Security](#security).)
+- **Inline build logs and cancel**, not just a trigger button.
+- **Zero runtime dependencies.**
+
+If none of that matters to you, the alternative is more widely used and simpler.
 
 ---
 
-## Installation
+## Using it day to day
 
-```bash
-npm install @liiift-studio/deploy-vercel-from-sanity
-```
+For whoever presses the button:
+
+- Open **Deploy** in the Studio sidebar. Each card is one environment — **Production** is your live public site; **Preview** is a copy only your team sees.
+- Press **Deploy** to rebuild that environment with the content you have already published. It does **not** publish drafts — anything still in draft stays unpublished.
+- The badge tells you where it is: **Queued** → **Building** → **Ready**. A typical build is a couple of minutes; the card shows a running timer.
+- **Ready** means the site is live. **Error** means the build failed — press **Details** → **Show error details** and send those lines to your developer.
+- Pressing Deploy twice is harmless; Vercel just builds again.
+
+<details>
+<summary>Everything it does</summary>
+
+- **One-click deploy** — Production, Preview, or any number of custom environments
+- **Live status** — Queued → Building → Ready / Error, polled every 5s, with a build timer and a toast when it finishes
+- **Inline build logs** — see why a build failed without leaving the Studio
+- **Cancel** in-progress deployments
+- **Deployment history** per target — the last 20 builds
+- Copy deployment URL, and an **Open in Vercel** link
+- GitHub commit links when repo metadata is available
+- Responsive grid — cards reflow to fill the width, one column on narrow viewports
+
+</details>
 
 ---
 
@@ -53,42 +73,70 @@ export default defineConfig({
 })
 ```
 
-### 2. Connect your Vercel API token
+### 2a. Connect your Vercel API token *(direct mode)*
 
 Open the **Deploy** tab in Sanity Studio and enter a Vercel API token when prompted.
 
-To create a token: **vercel.com → Settings → Tokens → Create → Full Account scope**.
+To create a token: **vercel.com → Settings → Tokens → Create**, and set **Scope** to the team that owns your projects.
+
+> Scope the token as narrowly as Vercel lets you. The plugin only reads deployments, reads build logs, and cancels — all of which work with a team-scoped token as long as each target has its **Team ID** set. A Full Account token also works, but it can read and write everything in your Vercel account, which is far more than this needs.
 
 The token is stored in a `config.vercelDeploy` document in your dataset and shared across all authenticated studio users.
 
+### 2b. Or set up the proxy *(proxy mode)*
+
+Skip the token entirely. Deploy the route, set its environment variables, add the
+Sanity webhook, then pass `mode`, `proxyUrl` and `statusKey` to the plugin —
+full walkthrough in [`proxy/README.md`](./proxy/README.md).
+
 ### 3. Add a deploy target
 
-Create one or more `vercel_deploy` documents — each represents an environment (Production, Preview, etc.).
+Each target is an environment — Production, Preview, or anything else.
+
+**In the Studio (recommended):** open the **Deploy** tab and click **Add target**
+in the top-right. The form validates the hook URL, and in proxy mode it asks for a
+Proxy Key instead. This is the path the screenshot above is showing.
+
+**To get your deploy hook URL:** Vercel Dashboard → Project → Settings → Git → Deploy Hooks → Create Hook.
+
+<details>
+<summary>Or create targets from the CLI</summary>
 
-**Via Sanity CLI:**
+`sanity documents create` reads a **file** — it has no stdin mode, so piping a
+heredoc into it silently does nothing.
 
 ```bash
-sanity documents create << 'EOF'
+cat > target.json << 'EOF'
 {
   "_type": "vercel_deploy",
   "_id": "vercel-deploy-production",
   "name": "Production",
-  "url": "https://api.vercel.com/v1/integrations/deploy/YOUR_PROJECT_ID/YOUR_HOOK_ID"
+  "url": "https://api.vercel.com/v1/integrations/deploy/YOUR_PROJECT_ID/YOUR_HOOK_ID",
+  "teamId": "team_xxxxxxxx"
 }
 EOF
+
+sanity documents create target.json
 ```
 
-**To get your deploy hook URL:** Vercel Dashboard → Project → Settings → Git → Deploy Hooks → Create Hook.
+Targets are also editable from the Structure sidebar, since the plugin registers
+the `vercel_deploy` type. **Publish them** — the Deploy tool ignores drafts, so an
+unpublished target shows as "No deploy targets configured".
+
+</details>
 
 **Available fields on each `vercel_deploy` document:**
 
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `name` | `string` | ✓ | Display label (e.g. "Production", "Preview") |
-| `url` | `url` | ✓ | Vercel deploy hook URL |
-| `teamId` | `string` | | Vercel team ID — required for team-owned projects |
+| `url` | `url` | ✓ *(direct mode)* | Vercel deploy hook URL, https only. Leave empty in proxy mode. |
+| `proxyKey` | `string` | ✓ *(proxy mode)* | Matches a key on your deploy proxy, which holds the real hook URL. Contains no secret. |
+| `teamId` | `string` | | Vercel team ID — required for team-owned projects. Ignored in proxy mode, where the proxy supplies it. |
 | `disableDeleteAction` | `boolean` | | Hides the delete button for this target in the studio UI |
 
+A target needs **either** `url` **or** `proxyKey`; the schema enforces that.
+
 ---
 
 ## Plugin options
@@ -97,7 +145,40 @@ EOF
 |---|---|---|---|
 | `name` | `string` | `'vercel-deploy'` | Tool slug in the Studio sidebar |
 | `title` | `string` | `'Deploy'` | Tool label in the Studio sidebar |
-| `icon` | `ComponentType` | `RocketIcon` | Accepted and stored on the tool descriptor. Note that no Studio version from v3 to v6 currently renders `tool.icon`, so this has no visible effect today. |
+| `icon` | `ComponentType` | `RocketIcon` | Stored on the tool descriptor. No Studio version renders `tool.icon` yet, so it has no visible effect. |
+| `mode` | `'direct' \| 'proxy'` | `'direct'` | Transport used to reach Vercel — see [Two modes](#two-modes) |
+| `proxyUrl` | `string` | — | Base URL of the deploy proxy, no trailing slash. Required when `mode` is `'proxy'`. |
+| `statusKey` | `string` | — | Key sent with status requests. Must match the proxy's `VERCEL_DEPLOY_STATUS_KEY`. Ships in the Studio bundle — treat it as public. |
+
+---
+
+## Two modes
+
+| | `direct` (default) | `proxy` |
+| --- | --- | --- |
+| Setup | Paste a token | Deploy one route, 4 env vars, one webhook (~15 min) |
+| Vercel token | In the dataset | On your server |
+| Deploy hook URLs | In the dataset | On your server |
+| Who can deploy | Anyone who can **read** the dataset | Anyone who can **write** — viewers cannot |
+| In the browser | The Vercel API token | A status key — reads status and logs, and can cancel a running build, within the configured projects |
+
+Direct mode is the default and needs no infrastructure. Use it when everyone with
+Studio access is already trusted with Vercel access.
+
+Reach for proxy mode when that is not true — untrusted editors, a public dataset,
+or a token you cannot afford to have read. Note that the hook URL matters as much
+as the token: it is itself a deploy credential, so in direct mode the section
+below is a UI convenience, not a security control.
+
+```ts
+vercelDeploy({
+  mode: 'proxy',
+  proxyUrl: 'https://your-site.com/api/vercel-deploy',
+  statusKey: process.env.SANITY_STUDIO_DEPLOY_STATUS_KEY,
+})
+```
+
+Setup guide: [`proxy/README.md`](./proxy/README.md).
 
 ---
 
@@ -105,6 +186,8 @@ EOF
 
 By default the Deploy tab is visible to all authenticated users. To hide it from viewers:
 
+> This hides the tab. In `direct` mode it does not prevent deploying — the hook URL is in the dataset, and anyone who can read it can trigger a build without the Studio. Use `proxy` mode if you need that actually enforced.
+
 > Filter on the tool name you actually configured. The snippet below uses the default `vercel-deploy`; if you passed a custom `name`, match that instead or the filter silently does nothing.
 
 ```ts
@@ -121,6 +204,8 @@ tools: (prev, { currentUser }) => {
 
 ## How it works
 
+### Direct mode
+
 ```mermaid
 flowchart LR
     subgraph studio["Sanity Studio"]
@@ -135,14 +220,49 @@ flowchart LR
         api["REST API<br/>/v6/deployments · /v2/.../events"]
     end
 
-    tool -- "reads targets + token" --> targets
-    tool -- "reads token" --> cfg
-    tool -- "1 - click Deploy" --> hook
-    hook -- "queues a build" --> api
-    api -- "poll every 5s while active" --> tool
+    tool -- "1 - reads targets" --> targets
+    tool -- "2 - reads token" --> cfg
+    tool -- "3 - click Deploy" --> hook
+    hook -- "4 - queues a build" --> api
+    api -- "5 - poll every 5s while active" --> tool
     tool -. "toast on Ready / Error / Canceled" .-> tool
 ```
 
+### Proxy mode
+
+```mermaid
+flowchart LR
+    subgraph studio["Sanity Studio (browser)"]
+        tool["Deploy tool<br/>holds no credential"]
+    end
+    subgraph dataset["Sanity dataset"]
+        targets["vercel_deploy docs<br/>name + proxyKey only"]
+        req["vercelDeploy.request<br/>created on click"]
+    end
+    subgraph server["Your server"]
+        proxy["Deploy proxy<br/>VERCEL_API_TOKEN<br/>hook URLs"]
+    end
+    subgraph vercel["Vercel"]
+        hook["Deploy hook"]
+        api["REST API"]
+    end
+
+    tool -- "reads targets" --> targets
+    tool -- "1 - Deploy click<br/>write ACL gates this" --> req
+    req -- "2 - signed webhook" --> proxy
+    proxy -- "3 - POST hook URL" --> hook
+    hook --> api
+    tool -- "4 - status, via status key" --> proxy
+    proxy -- "5 - reads with server-held token" --> api
+```
+
+No Vercel credential reaches the browser, and a viewer cannot create the request
+document, so a viewer cannot deploy. The browser does hold the status key, which
+can cancel a running build for the configured targets — see
+[Security](#security). Setup: [`proxy/README.md`](./proxy/README.md).
+
+### Direct mode, step by step
+
 1. Deploy targets are stored as `vercel_deploy` documents in your Sanity dataset.
 2. The plugin fetches the last 10 deployments for each target from the Vercel API, filtered to those triggered by that hook.
 3. While a deployment is active (Queued / Initializing / Building), it polls every 5 seconds.
@@ -158,11 +278,11 @@ flowchart LR
 
 ### "Vercel API 401 — token is invalid or expired"
 
-Your Vercel API token has been revoked or expired. Go to **Vercel → Settings → Tokens**, create a new token with **Full Account** scope, and reconnect it in the Deploy tab (top-right → *Token connected* button).
+Your Vercel API token has been revoked or expired. Go to **Vercel → Settings → Tokens**, create a new token scoped to the team that owns your projects, and reconnect it in the Deploy tab (top-right → *Token connected* button).
 
 ### "Vercel API 403 — token lacks the required permissions"
 
-The token exists but was created with insufficient scope. Vercel tokens need **Full Account** scope to read deployments. Delete the token and create a new one with the correct scope.
+The token exists but cannot see the project. Check the target's **Team ID** is set — a team-scoped token needs it to resolve team-owned projects. If the project is personal rather than team-owned, the token must be scoped to that personal account.
 
 ### "Vercel API 404 — resource not found. Check the deploy hook URL and team ID."
 
@@ -174,7 +294,9 @@ The plugin is making too many API calls at once (common when many targets are al
 
 ### Deploy triggers but status never updates
 
-This usually means the token is missing. The plugin can trigger deploys via hook URL without a token, but it needs an API token to read back deployment status. Connect a token using the button in the top-right of the Deploy tab.
+**Direct mode** — usually a missing token. The plugin can trigger deploys via the hook URL without one, but reading status back needs an API token. Connect one using the button in the top-right of the Deploy tab.
+
+**Proxy mode** — the token button is deliberately hidden, so this is not it. Check, in order: the browser console for a blocked CORS preflight (set `VERCEL_DEPLOY_ALLOWED_ORIGINS` on the proxy to your Studio's origin); that the plugin's `statusKey` and the proxy's `VERCEL_DEPLOY_STATUS_KEY` hold the same value; and that the target's **Proxy Key** matches a `VERCEL_DEPLOY_PROJECT_*` variable. Deploy failures land in **Sanity → API → Webhooks → delivery log**, never in the Studio — see [`proxy/README.md`](./proxy/README.md#when-the-webhook-fires-but-nothing-deploys).
 
 ### Commit SHA does not link to GitHub
 
@@ -188,7 +310,13 @@ If "No stderr or stdout was captured" appears, the build may have failed before
 
 ## Security
 
-**API token storage** — The Vercel API token is stored in cleartext in a `config.vercelDeploy` document of type `vercelDeploy.config`. Sanity has no per-document access control at this tier, so **the token is readable by anyone who can read the dataset** — and if the dataset is public, which is the usual setup for a statically generated front-end, that includes unauthenticated requests to the public GROQ API. A `viewer`-role member who cannot write a single document can also read it. Note that a **Full Account** scoped token can read and write your entire Vercel account, so anyone with studio access can read a credential that grants broad Vercel access — treat the token accordingly. The document type is deliberately **not** registered in the schema — registering it would list a "Vercel Deploy Configuration" entry in the Structure sidebar for every editor. Revoke the stored token from the plugin instead: **Deploy → Token connected → Remove token**. Audit who has access to your Sanity project at sanity.io → Project → Members, and do not store a Full Account token in a public dataset. If your studio includes untrusted editors, consider a server-side proxy that holds the token and exposes only a scoped deploy endpoint.
+**API token storage** — The Vercel API token is stored in cleartext in a `config.vercelDeploy` document of type `vercelDeploy.config`. Sanity has no per-document access control at this tier, so **the token is readable by anyone who can read the dataset** — and if the dataset is public, which is the usual setup for a statically generated front-end, that includes unauthenticated requests to the public GROQ API. A `viewer`-role member who cannot write a single document can also read it. A Vercel API token can read **every environment variable in every project it can see** — which for most teams means the database URL, payment keys, and every other production secret — as well as deploy arbitrary code to your production domain. Scope it to a single team, and understand that leaking it leaks those secrets. The document type is deliberately **not** registered in the schema — registering it would list a "Vercel Deploy Configuration" entry in the Structure sidebar for every editor. Revoke the stored token from the plugin instead: **Deploy → Token connected → Remove token**. Audit who has access to your Sanity project at sanity.io → Project → Members, and never store a Vercel token in a public dataset. If your studio includes untrusted editors, use [proxy mode](#two-modes) — the plugin ships the proxy.
+
+**Two credentials, not one** — in direct mode the dataset holds *both* the API token and a deploy hook URL on every target. The hook URL is itself a deploy credential: anyone who can read it can POST it and trigger a build, with no Studio and no role. That is why [Restrict access to editors](#restrict-access-to-editors-and-above) hides the tab but does not enforce anything, and why [proxy mode](#two-modes) moves both server-side.
+
+**Proxy mode status key** — the key that reaches the browser permits reading deployment status and build logs for the configured targets, and cancelling their in-progress deployments. Cancel is a write, so it is not a read-only key. Requests are scoped to the configured **projects** — the proxy verifies a deployment belongs to the target's project before reading or cancelling it. That is broader than the targets you configured: it includes any deployment in those projects, such as git-push builds the plugin never lists.
+
+Assume the key is obtainable: a hosted Studio bundle is fetchable without logging in. In the worst case that means anyone can list deployments, read their build logs — which can contain secrets a failed build printed — and cancel a running production build. CORS does not prevent this; it constrains browsers, not `curl`. If that is unacceptable, see [What this does not solve](./proxy/README.md#what-this-does-not-solve). Treat the key as public, because it ships in the Studio bundle.
 
 **Deploy hook URL validation** — `triggerDeploy` validates that the hook URL matches `api.vercel.com/v1/integrations/deploy/` before making the request, preventing SSRF from a tampered document.
 
@@ -232,6 +360,25 @@ toasts render in a live region anchored to the bottom-right of the tool.
 
 ---
 
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+---
+
+## Tests
+
+```bash
+npm test
+```
+
+Unit tests cover the proxy's authorization boundary (fail-closed status key,
+per-project deployment scoping, role gating, SSRF guard on hook URLs) and the URL
+validators that guard every anchor the plugin renders. `prepublishOnly` runs
+typecheck and tests before building, so a release cannot ship past them.
+
+---
+
 ## Contributing
 
 Issues and pull requests welcome at [github.com/Liiift-Studio/Deploy-Vercel-from-Sanity](https://github.com/Liiift-Studio/Deploy-Vercel-from-Sanity).

package/dist/index.d.mts

@@ -7,8 +7,19 @@ interface DeployTarget {
     _id: string;
     _type: 'vercel_deploy';
     name: string;
-    /** Full Vercel deploy hook URL */
-    url: string;
+    /**
+     * Full Vercel deploy hook URL. Used in `direct` mode.
+     *
+     * In `proxy` mode leave this empty and set {@link proxyKey} instead — a hook URL
+     * is itself a deploy credential, so storing one in the dataset lets anyone who
+     * can read the dataset trigger a build regardless of their Studio role.
+     */
+    url?: string;
+    /**
+     * Identifier the proxy maps to a hook URL held in its own environment. Used in
+     * `proxy` mode. Contains no secret.
+     */
+    proxyKey?: string;
     /** Vercel team ID — optional, only needed for team projects */
     teamId?: string;
     /** Prevent editors from deleting this target */
@@ -42,14 +53,47 @@ interface VercelDeployment {
         githubCommitOrg?: string;
     };
 }
+/**
+ * How the plugin reaches Vercel.
+ *
+ * - `direct` (default) — the Studio calls Vercel itself, using an API token stored
+ *   in the dataset and deploy hook URLs stored on each target. Simplest to set up.
+ *   Everything in the dataset is readable by everyone who can read the dataset,
+ *   so anyone with read access can both read the token and trigger a deploy.
+ * - `proxy` — the Studio holds no Vercel credentials. Deploys are requested by
+ *   creating a document, which Sanity's own write ACL already restricts to roles
+ *   that can write, and a server-side proxy performs the actual deploy. See
+ *   `proxy/README.md`.
+ */
+type VercelDeployMode = 'direct' | 'proxy';
 /** Plugin configuration options */
 interface VercelDeployPluginConfig {
     /** Tool name slug shown in Studio sidebar (default: 'vercel-deploy') */
     name?: string;
     /** Tool label shown in Studio sidebar (default: 'Deploy') */
     title?: string;
-    /** Custom icon component */
+    /**
+     * Accepted and stored on the tool descriptor. No Studio version from v3 to v6
+     * renders `tool.icon`, so this currently has no visible effect.
+     */
     icon?: React.ComponentType;
+    /** Transport used to reach Vercel. Defaults to `direct`. */
+    mode?: VercelDeployMode;
+    /**
+     * Base URL of the deploy proxy, without a trailing slash — for example
+     * `https://example.com/api/vercel-deploy`. Required when `mode` is `proxy`.
+     */
+    proxyUrl?: string;
+    /**
+     * Key sent with status requests to the proxy.
+     *
+     * This ends up in the Studio bundle, which is served publicly for a hosted
+     * Studio, so treat it as public. 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. The Vercel
+     * API token never leaves the proxy.
+     */
+    statusKey?: string;
 }
 
 declare const vercelDeploySchema: {
@@ -69,6 +113,12 @@ declare const vercelDeploySchema: {
         type: "url";
         description: string;
         validation: (Rule: sanity.UrlRule) => sanity.UrlRule;
+    } & sanity.WidenValidation) | ({
+        name: "proxyKey";
+        title: string;
+        type: "string";
+        description: string;
+        validation: (Rule: sanity.StringRule) => sanity.StringRule;
     } & sanity.WidenValidation) | {
         name: "teamId";
         title: string;
@@ -109,4 +159,4 @@ declare const vercelDeploySchema: {
  */
 declare const vercelDeploy: sanity.Plugin<void | VercelDeployPluginConfig>;
 
-export { type DeployTarget, type VercelDeployPluginConfig, type VercelDeployState, type VercelDeployment, vercelDeploy, vercelDeploySchema };
+export { type DeployTarget, type VercelDeployMode, type VercelDeployPluginConfig, type VercelDeployState, type VercelDeployment, vercelDeploy, vercelDeploySchema };

package/dist/index.d.ts

@@ -7,8 +7,19 @@ interface DeployTarget {
     _id: string;
     _type: 'vercel_deploy';
     name: string;
-    /** Full Vercel deploy hook URL */
-    url: string;
+    /**
+     * Full Vercel deploy hook URL. Used in `direct` mode.
+     *
+     * In `proxy` mode leave this empty and set {@link proxyKey} instead — a hook URL
+     * is itself a deploy credential, so storing one in the dataset lets anyone who
+     * can read the dataset trigger a build regardless of their Studio role.
+     */
+    url?: string;
+    /**
+     * Identifier the proxy maps to a hook URL held in its own environment. Used in
+     * `proxy` mode. Contains no secret.
+     */
+    proxyKey?: string;
     /** Vercel team ID — optional, only needed for team projects */
     teamId?: string;
     /** Prevent editors from deleting this target */
@@ -42,14 +53,47 @@ interface VercelDeployment {
         githubCommitOrg?: string;
     };
 }
+/**
+ * How the plugin reaches Vercel.
+ *
+ * - `direct` (default) — the Studio calls Vercel itself, using an API token stored
+ *   in the dataset and deploy hook URLs stored on each target. Simplest to set up.
+ *   Everything in the dataset is readable by everyone who can read the dataset,
+ *   so anyone with read access can both read the token and trigger a deploy.
+ * - `proxy` — the Studio holds no Vercel credentials. Deploys are requested by
+ *   creating a document, which Sanity's own write ACL already restricts to roles
+ *   that can write, and a server-side proxy performs the actual deploy. See
+ *   `proxy/README.md`.
+ */
+type VercelDeployMode = 'direct' | 'proxy';
 /** Plugin configuration options */
 interface VercelDeployPluginConfig {
     /** Tool name slug shown in Studio sidebar (default: 'vercel-deploy') */
     name?: string;
     /** Tool label shown in Studio sidebar (default: 'Deploy') */
     title?: string;
-    /** Custom icon component */
+    /**
+     * Accepted and stored on the tool descriptor. No Studio version from v3 to v6
+     * renders `tool.icon`, so this currently has no visible effect.
+     */
     icon?: React.ComponentType;
+    /** Transport used to reach Vercel. Defaults to `direct`. */
+    mode?: VercelDeployMode;
+    /**
+     * Base URL of the deploy proxy, without a trailing slash — for example
+     * `https://example.com/api/vercel-deploy`. Required when `mode` is `proxy`.
+     */
+    proxyUrl?: string;
+    /**
+     * Key sent with status requests to the proxy.
+     *
+     * This ends up in the Studio bundle, which is served publicly for a hosted
+     * Studio, so treat it as public. 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. The Vercel
+     * API token never leaves the proxy.
+     */
+    statusKey?: string;
 }
 
 declare const vercelDeploySchema: {
@@ -69,6 +113,12 @@ declare const vercelDeploySchema: {
         type: "url";
         description: string;
         validation: (Rule: sanity.UrlRule) => sanity.UrlRule;
+    } & sanity.WidenValidation) | ({
+        name: "proxyKey";
+        title: string;
+        type: "string";
+        description: string;
+        validation: (Rule: sanity.StringRule) => sanity.StringRule;
     } & sanity.WidenValidation) | {
         name: "teamId";
         title: string;
@@ -109,4 +159,4 @@ declare const vercelDeploySchema: {
  */
 declare const vercelDeploy: sanity.Plugin<void | VercelDeployPluginConfig>;
 
-export { type DeployTarget, type VercelDeployPluginConfig, type VercelDeployState, type VercelDeployment, vercelDeploy, vercelDeploySchema };
+export { type DeployTarget, type VercelDeployMode, type VercelDeployPluginConfig, type VercelDeployState, type VercelDeployment, vercelDeploy, vercelDeploySchema };