@liiift-studio/deploy-vercel-from-sanity 1.4.0 → 1.5.0

package/README.md

@@ -291,12 +291,72 @@ HEAD, which is the same commit with the same author, so it is blocked
 identically. The only way out is a new commit by an authorised author.
 
 A Studio running in a browser holds no git credential, so it cannot make that
-commit itself. With `unblock` configured it dispatches a GitHub Actions workflow
-that does.
+commit itself. `unblock` gives it two ways to borrow one.
 
-### The credential split
+### Choose a mode
 
-This is the part worth understanding before enabling it.
+| | `endpoint` — **preferred** | `token` — workflow dispatch |
+|---|---|---|
+| Needs a server | yes, one API route | no |
+| GitHub credential in the bundle | **none** | one, `Actions: write` |
+| Tokens to maintain | **1** | 2 |
+| Workflow file on the default branch | not needed | required, or dispatch 404s |
+
+Use `endpoint` if you have anywhere to put an API route. Its whole advantage is
+that nothing sensitive reaches the browser, so there is only one credential and
+it is a server secret like any other.
+
+---
+
+## `endpoint` mode
+
+```ts
+vercelDeploy({
+  unblock: {
+    endpoint: 'https://example.com/api/deploy-unblock',
+  },
+})
+```
+
+That is the entire Studio-side configuration — note the absence of a token.
+
+The Studio posts `{ ref, requestedBy }` to that URL with the signed-in user's
+**Sanity session token** in an `Authorization: Bearer` header. Your route verifies
+that token against Sanity, then makes the commit with its own server-held GitHub
+token.
+
+Requirements for the route:
+
+- **Verify the session token.** Do not accept a shared secret instead — the bundle
+  is public, so a shared secret only moves the bar from "know the URL" to "open
+  devtools". Verify against
+  `https://<projectId>.api.sanity.io/v2021-06-07/users/me`. Note Sanity answers
+  `200` with a null `id` for an unauthenticated request rather than `401`.
+- **Allow the Studio's origin.** A deployed Studio is on `*.sanity.studio`, not
+  your site's domain, so every call is cross-origin and the preflight fails
+  without an allow-list. Echo one allow-listed origin; do not send `*` to an
+  endpoint that takes an `Authorization` header.
+- **Restrict which branches it will bump.** The recovery flow only ever needs the
+  branches you deploy.
+- **Answer `{ error }` on failure.** The plugin shows that string to the editor
+  verbatim, in preference to its own generic message.
+- **Serve it over https.** The plugin refuses a plaintext endpoint, because the
+  session token travels with the request. `localhost` is exempt for development.
+
+The token forwarded is `client.config().token`. Sanity only exposes it under
+token-based auth, so it can be absent under cookie-based login; the plugin
+detects that and says so, rather than sending an anonymous request and letting
+your route report it as a permissions failure.
+
+A worked Next.js Pages Router implementation is in
+[`docs/deploy-unblock-route.js`](docs/deploy-unblock-route.js).
+
+---
+
+## `token` mode — workflow dispatch
+
+For setups with no server. The Studio dispatches a GitHub Actions workflow, and
+the workflow makes the commit.
 
 ```
 Studio bundle  ──  unblock.token   Actions: write, one repo
@@ -312,8 +372,7 @@ Handing the Studio a `Contents: write` token would be far simpler and is the
 obvious first design. Do not: the Studio bundle is served publicly, so that token
 would let anyone who can load the Studio push arbitrary commits to the production
 repository — and the next build would run them. The dispatch token is scoped so
-that the worst a leak permits is *running the bump workflow*, which produces a
-version bump and a deploy.
+that the worst a leak permits is *running the bump workflow*.
 
 ### What a leaked dispatch token can actually do
 
@@ -331,61 +390,60 @@ The shipped workflow therefore opens with a branch allowlist, and a `concurrency
 group that serialises bumps per branch. Narrow the allowlist to the branches you
 actually deploy. Rotate the token if it leaks.
 
-### 1. Add the workflow
+### Setup
 
-Copy [`docs/version-bump.yml`](docs/version-bump.yml) to
-`.github/workflows/version-bump.yml` in the **site** repository, then set the git
-identity in it to the account whose commits Vercel accepts, and narrow the branch
-allowlist to the branches you deploy.
+1. Copy [`docs/version-bump.yml`](docs/version-bump.yml) to
+   `.github/workflows/version-bump.yml`, set the git identity in it to the account
+   whose commits Vercel accepts, and narrow the branch allowlist.
 
-> **The workflow file must exist on the repository's default branch**, and on
-> every branch you deploy from. GitHub resolves a dispatch against the default
-> branch's copy, then runs the copy on the requested ref. A file present only on
-> `staging` returns a 404 — which the plugin reports in full, since GitHub uses
-> the same 404 for "no such workflow" and "your token cannot see this repo".
+   > **The workflow file must exist on the repository's default branch**, and on
+   > every branch you deploy from. GitHub resolves a dispatch against the default
+   > branch's copy, then runs the copy on the requested ref. A file present only on
+   > `staging` returns a 404 — which the plugin reports in full, since GitHub uses
+   > the same 404 for "no such workflow" and "your token cannot see this repo".
 
-### 2. Add the commit credential
+2. Create a fine-grained token with **`Contents: write`** on that one repository
+   and save it as the repository Actions secret **`DEPLOY_COMMIT_TOKEN`**.
 
-Create a fine-grained token on the account whose commits Vercel accepts, scoped
-to **`Contents: write`** on that one repository, and save it as the repository
-Actions secret **`DEPLOY_COMMIT_TOKEN`**.
+   It must not be the default `GITHUB_TOKEN`: commits made with it are authored by
+   `github-actions[bot]`, which is not a team member either, so Vercel would block
+   the bump for the same reason it blocked the original commit.
 
-It must not be the default `GITHUB_TOKEN`: commits made with it are authored by
-`github-actions[bot]`, which is not a team member either, so Vercel would block
-the bump for the same reason it blocked the original commit.
+3. Create a second fine-grained token scoped to **`Actions: write`** on the same
+   repository — and nothing else — and expose it to the Studio build:
 
-### 3. Add the dispatch token
+   ```sh
+   SANITY_STUDIO_DEPLOY_UNBLOCK_GH_TOKEN=github_pat_…
+   ```
 
-Create a second fine-grained token scoped to **`Actions: write`** on the same
-repository — and nothing else — and expose it to the Studio build:
+4. Configure the plugin:
 
-```sh
-SANITY_STUDIO_DEPLOY_UNBLOCK_GH_TOKEN=github_pat_…
-```
+   ```ts
+   vercelDeploy({
+     unblock: {
+       token: process.env.SANITY_STUDIO_DEPLOY_UNBLOCK_GH_TOKEN,
+       owner: 'your-org',
+       repo: 'your-site-repo',
+       workflow: 'version-bump.yml',   // optional, this is the default
+     },
+   })
+   ```
 
-### 4. Configure the plugin
+---
 
-```ts
-vercelDeploy({
-  unblock: {
-    token: process.env.SANITY_STUDIO_DEPLOY_UNBLOCK_GH_TOKEN,
-    owner: 'your-org',
-    repo: 'your-site-repo',
-    workflow: 'version-bump.yml',   // optional, this is the default
-  },
-})
-```
+## `unblock` reference
 
 | Field | Required | Description |
 |---|---|---|
-| `token` | yes | Fine-grained token, `Actions: write` on `repo` only. Ships in the Studio bundle — treat it as public. Unset hides the button. |
-| `owner` | yes | Repository owner, e.g. `your-org` |
-| `repo` | yes | Repository name |
+| `endpoint` | one of | URL of your site route. Wins when both modes are configured. Must be https. |
+| `token` | one of | Fine-grained token, `Actions: write` on `repo` only. Ships in the Studio bundle — treat it as public. |
+| `owner` | dispatch only | Repository owner, e.g. `your-org` |
+| `repo` | dispatch only | Repository name |
 | `workflow` | no | Workflow filename. Defaults to `version-bump.yml`. |
 | `defaultRef` | no | Branch to bump when the blocked deployment names none. Normally unnecessary — the branch is read from the deployment being recovered. |
 
-An `unblock` block missing `token`, `owner` or `repo` is discarded, so a
-half-finished configuration renders no button rather than one that only errors.
+A config with neither `endpoint` nor all of `token`/`owner`/`repo` is discarded,
+so a half-finished setup renders no button rather than one that only errors.
 
 ### What the editor sees
 
@@ -394,9 +452,8 @@ not a general "deploy harder" control, and it is deliberately not offered when
 the plugin has nothing to target.
 
 Pressing it reports that the bump was **requested**. That is the honest claim:
-GitHub has accepted the dispatch, but the workflow still has to run, commit and
-push before Vercel sees anything, so the new deployment turns up a minute or two
-later. Polling picks it up on its own.
+the commit is made, but Vercel still has to notice the push and build it, so the
+new deployment turns up shortly after. Polling picks it up on its own.
 
 ### The real fix
 

package/dist/index.d.mts

@@ -84,37 +84,57 @@ type VercelDeployMode = 'direct' | 'proxy';
  * commit's git author is not a member of the Vercel team.
  *
  * The Studio cannot fix this itself — the remedy is a commit by an authorised
- * author, and a browser holds no git credential. So the button dispatches a
- * GitHub Actions workflow, and that workflow does the commit with a token held
- * in Actions secrets.
+ * author, and a browser holds no git credential. There are two ways to borrow
+ * one, and they are not equivalent:
  *
- * The split matters. {@link token} ships inside the Studio bundle and must be
- * treated as public; scope it to **Actions: write on the one repo** so the worst
- * a leak permits is running that workflow. The credential that can actually
- * write code stays in GitHub, where the browser never sees it.
+ * - **{@link endpoint} (preferred).** The Studio posts the signed-in user's
+ *   Sanity session token to a route on your own site; the route verifies it and
+ *   commits with its own server-held GitHub token. Nothing secret reaches the
+ *   browser, there is one token to maintain, and there is no workflow file whose
+ *   presence on the default branch you have to remember.
+ *
+ * - **{@link token}.** The Studio dispatches a GitHub Actions workflow directly.
+ *   Needs no server, but puts a GitHub token in the bundle, which is public.
+ *   Scope it to **Actions: write on the one repo** so the worst a leak permits is
+ *   running that workflow, and never give it `Contents: write` — a public token
+ *   that can push code is a public token that can run code on your next build.
+ *
+ * Set `endpoint` if you have anywhere to put a route. It wins when both are set.
  */
 interface UnblockConfig {
+    /**
+     * URL of a site API route that performs the bump server-side. **Preferred.**
+     *
+     * In this mode the Studio carries no GitHub credential at all. It posts the
+     * signed-in user's Sanity session token, the route verifies it against Sanity,
+     * and the route's own server-held GitHub token makes the commit. One token,
+     * never public, and no workflow file to keep on the default branch.
+     *
+     * Takes precedence over {@link token} when both are set.
+     */
+    endpoint?: string;
     /**
      * Fine-grained GitHub token, scoped to `Actions: write` on {@link repo} alone.
+     * Only used when {@link endpoint} is not set.
      *
      * Compiled into the Studio bundle, so anyone who can load the Studio can read
      * it and dispatch the workflow. Never give it `Contents: write` — that would
-     * let a reader push arbitrary commits to the production repo.
-     *
-     * Leave unset to hide the button entirely.
+     * let a reader push arbitrary commits to the production repo. If you have a
+     * server to put a route on, prefer {@link endpoint} and avoid this entirely.
      */
     token?: string;
-    /** Repository owner, e.g. `Liiift-Studio`. */
-    owner: string;
-    /** Repository name, e.g. `the-designers-foundry`. */
-    repo: string;
+    /** Repository owner, e.g. `your-org`. Required for workflow-dispatch mode only. */
+    owner?: string;
+    /** Repository name. Required for workflow-dispatch mode only. */
+    repo?: string;
     /**
      * Workflow filename to dispatch. Defaults to `version-bump.yml`.
+     * Workflow-dispatch mode only.
      *
      * GitHub resolves a dispatch against the workflow file **on the repository's
      * default branch**, then runs the copy on the requested ref — so the file must
      * exist on the default branch as well as on every branch you deploy from, or
-     * the dispatch returns 404.
+     * the dispatch returns 404. `endpoint` mode has no such constraint.
      */
     workflow?: string;
     /**

package/dist/index.d.ts

@@ -84,37 +84,57 @@ type VercelDeployMode = 'direct' | 'proxy';
  * commit's git author is not a member of the Vercel team.
  *
  * The Studio cannot fix this itself — the remedy is a commit by an authorised
- * author, and a browser holds no git credential. So the button dispatches a
- * GitHub Actions workflow, and that workflow does the commit with a token held
- * in Actions secrets.
+ * author, and a browser holds no git credential. There are two ways to borrow
+ * one, and they are not equivalent:
  *
- * The split matters. {@link token} ships inside the Studio bundle and must be
- * treated as public; scope it to **Actions: write on the one repo** so the worst
- * a leak permits is running that workflow. The credential that can actually
- * write code stays in GitHub, where the browser never sees it.
+ * - **{@link endpoint} (preferred).** The Studio posts the signed-in user's
+ *   Sanity session token to a route on your own site; the route verifies it and
+ *   commits with its own server-held GitHub token. Nothing secret reaches the
+ *   browser, there is one token to maintain, and there is no workflow file whose
+ *   presence on the default branch you have to remember.
+ *
+ * - **{@link token}.** The Studio dispatches a GitHub Actions workflow directly.
+ *   Needs no server, but puts a GitHub token in the bundle, which is public.
+ *   Scope it to **Actions: write on the one repo** so the worst a leak permits is
+ *   running that workflow, and never give it `Contents: write` — a public token
+ *   that can push code is a public token that can run code on your next build.
+ *
+ * Set `endpoint` if you have anywhere to put a route. It wins when both are set.
  */
 interface UnblockConfig {
+    /**
+     * URL of a site API route that performs the bump server-side. **Preferred.**
+     *
+     * In this mode the Studio carries no GitHub credential at all. It posts the
+     * signed-in user's Sanity session token, the route verifies it against Sanity,
+     * and the route's own server-held GitHub token makes the commit. One token,
+     * never public, and no workflow file to keep on the default branch.
+     *
+     * Takes precedence over {@link token} when both are set.
+     */
+    endpoint?: string;
     /**
      * Fine-grained GitHub token, scoped to `Actions: write` on {@link repo} alone.
+     * Only used when {@link endpoint} is not set.
      *
      * Compiled into the Studio bundle, so anyone who can load the Studio can read
      * it and dispatch the workflow. Never give it `Contents: write` — that would
-     * let a reader push arbitrary commits to the production repo.
-     *
-     * Leave unset to hide the button entirely.
+     * let a reader push arbitrary commits to the production repo. If you have a
+     * server to put a route on, prefer {@link endpoint} and avoid this entirely.
      */
     token?: string;
-    /** Repository owner, e.g. `Liiift-Studio`. */
-    owner: string;
-    /** Repository name, e.g. `the-designers-foundry`. */
-    repo: string;
+    /** Repository owner, e.g. `your-org`. Required for workflow-dispatch mode only. */
+    owner?: string;
+    /** Repository name. Required for workflow-dispatch mode only. */
+    repo?: string;
     /**
      * Workflow filename to dispatch. Defaults to `version-bump.yml`.
+     * Workflow-dispatch mode only.
      *
      * GitHub resolves a dispatch against the workflow file **on the repository's
      * default branch**, then runs the copy on the requested ref — so the file must
      * exist on the default branch as well as on every branch you deploy from, or
-     * the dispatch returns 404.
+     * the dispatch returns 404. `endpoint` mode has no such constraint.
      */
     workflow?: string;
     /**

package/dist/index.js

@@ -102,6 +102,11 @@ var import_react2 = require("react");
 var import_jsx_runtime2 = require("react/jsx-runtime");
 var DEFAULTS = { mode: "direct" };
 var ConfigContext = (0, import_react2.createContext)(DEFAULTS);
+function isUsableUnblock(unblock) {
+  if (!unblock) return false;
+  if (unblock.endpoint) return true;
+  return Boolean(unblock.token && unblock.owner && unblock.repo);
+}
 function resolveConfig(options) {
   const config = options ?? {};
   return {
@@ -109,9 +114,11 @@ function resolveConfig(options) {
     // Trailing slashes would double up when request paths are appended.
     proxyUrl: config.proxyUrl?.replace(/\/+$/, ""),
     statusKey: config.statusKey,
-    // Dropped unless it can actually be used. A config missing the token, the owner
-    // or the repo would otherwise render a button whose only outcome is an error.
-    unblock: config.unblock?.token && config.unblock.owner && config.unblock.repo ? config.unblock : void 0
+    // Dropped unless it can actually be used, so an incomplete configuration renders
+    // no button rather than one whose only outcome is an error. Either mode will do:
+    // an `endpoint` needs nothing else, while workflow dispatch needs all three of
+    // token, owner and repo to build an authenticated request.
+    unblock: isUsableUnblock(config.unblock) ? config.unblock : void 0
   };
 }
 function ConfigProvider({ value, children }) {
@@ -760,6 +767,78 @@ function dispatchErrorMessage(status, workflow, ref) {
   }
 }
 
+// src/lib/unblock.ts
+function assertSafeEndpoint(endpoint) {
+  let parsed;
+  try {
+    parsed = new URL(endpoint);
+  } catch {
+    throw new Error(`The configured recovery endpoint is not a valid URL: "${endpoint}".`);
+  }
+  const isLocal = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+  if (parsed.protocol !== "https:" && !isLocal) {
+    throw new Error("The recovery endpoint must be https \u2014 the Studio session token is sent with the request.");
+  }
+  return parsed;
+}
+async function postToEndpoint(opts) {
+  const { config, ref, requestedBy, studioToken } = opts;
+  const endpoint = assertSafeEndpoint(config.endpoint);
+  if (!studioToken) {
+    throw new Error(
+      "Your Studio session token is not available, so the site cannot verify who you are. This happens under cookie-based login \u2014 sign out and back in, or ask a developer to deploy manually."
+    );
+  }
+  let res;
+  try {
+    res = await fetch(endpoint.toString(), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${studioToken}`
+      },
+      body: JSON.stringify({ ref, requestedBy })
+    });
+  } catch {
+    throw new Error(
+      `Could not reach ${endpoint.host}. Check the site is up and that the route allows requests from this Studio's origin.`
+    );
+  }
+  if (res.ok) return;
+  let detail = "";
+  try {
+    const body = await res.json();
+    if (typeof body?.error === "string") detail = body.error;
+  } catch {
+  }
+  throw new Error(detail || endpointErrorMessage(res.status, endpoint.host));
+}
+function endpointErrorMessage(status, host) {
+  switch (status) {
+    case 401:
+      return "The site did not accept your Studio session. Try signing out of the Studio and back in.";
+    case 403:
+      return "Your Studio account is not permitted to trigger a deploy recovery.";
+    case 404:
+      return `No recovery route at ${host}. It may not be deployed yet \u2014 check the endpoint URL.`;
+    case 429:
+      return "A bump was requested very recently. Wait a moment before trying again.";
+    default:
+      return status >= 500 ? "The site failed while making the bump commit. Check its function logs." : `The site refused the request (${status}).`;
+  }
+}
+async function requestUnblock(opts) {
+  if (opts.config.endpoint) return postToEndpoint(opts);
+  if (!opts.config.owner || !opts.config.repo) {
+    throw new Error("Deploy recovery is misconfigured \u2014 set either `endpoint`, or `owner` and `repo`.");
+  }
+  return dispatchVersionBump({
+    config: opts.config,
+    ref: opts.ref,
+    requestedBy: opts.requestedBy
+  });
+}
+
 // src/components/DeployItem.tsx
 var import_sanity = require("sanity");
 
@@ -1158,10 +1237,16 @@ function DeployItem({ target, token, onDelete, onEdit }) {
     setBumping(true);
     setBumpResult(null);
     try {
-      await dispatchVersionBump({
+      await requestUnblock({
         config: unblockConfig,
         ref,
-        requestedBy: currentUser?.name || currentUser?.email || void 0
+        requestedBy: currentUser?.name || currentUser?.email || void 0,
+        // Forwarded so a site endpoint can verify the caller is a signed-in project
+        // user. Sanity only exposes this under token-based auth, so it can be
+        // absent; `requestUnblock` reports that as its own case rather than
+        // letting the server see an anonymous request and call it a permissions
+        // failure. Unused by workflow-dispatch mode.
+        studioToken: client.config().token
       });
       setBumpResult({
         ok: true,
@@ -1179,7 +1264,7 @@ function DeployItem({ target, token, onDelete, onEdit }) {
     } finally {
       setBumping(false);
     }
-  }, [pluginConfig.unblock, latest?.meta?.githubCommitRef, currentUser, target.name, toast]);
+  }, [pluginConfig.unblock, latest?.meta?.githubCommitRef, currentUser, target.name, toast, client]);
   const branch = latest?.meta?.githubCommitRef;
   const commitMsg = latest?.meta?.githubCommitMessage?.split("\n")[0];
   const sha = shortSha(latest?.meta?.githubCommitSha);
@@ -1785,7 +1870,7 @@ function DeployTargetForm({ initial, onSaved, onClose }) {
 }
 
 // src/version.ts
-var VERSION = "1.4.0";
+var VERSION = "1.5.0";
 
 // src/components/DeployTool.tsx
 var import_jsx_runtime13 = require("react/jsx-runtime");

package/dist/index.mjs

@@ -67,6 +67,11 @@ import { createContext, useContext } from "react";
 import { jsx as jsx2 } from "react/jsx-runtime";
 var DEFAULTS = { mode: "direct" };
 var ConfigContext = createContext(DEFAULTS);
+function isUsableUnblock(unblock) {
+  if (!unblock) return false;
+  if (unblock.endpoint) return true;
+  return Boolean(unblock.token && unblock.owner && unblock.repo);
+}
 function resolveConfig(options) {
   const config = options ?? {};
   return {
@@ -74,9 +79,11 @@ function resolveConfig(options) {
     // Trailing slashes would double up when request paths are appended.
     proxyUrl: config.proxyUrl?.replace(/\/+$/, ""),
     statusKey: config.statusKey,
-    // Dropped unless it can actually be used. A config missing the token, the owner
-    // or the repo would otherwise render a button whose only outcome is an error.
-    unblock: config.unblock?.token && config.unblock.owner && config.unblock.repo ? config.unblock : void 0
+    // Dropped unless it can actually be used, so an incomplete configuration renders
+    // no button rather than one whose only outcome is an error. Either mode will do:
+    // an `endpoint` needs nothing else, while workflow dispatch needs all three of
+    // token, owner and repo to build an authenticated request.
+    unblock: isUsableUnblock(config.unblock) ? config.unblock : void 0
   };
 }
 function ConfigProvider({ value, children }) {
@@ -725,6 +732,78 @@ function dispatchErrorMessage(status, workflow, ref) {
   }
 }
 
+// src/lib/unblock.ts
+function assertSafeEndpoint(endpoint) {
+  let parsed;
+  try {
+    parsed = new URL(endpoint);
+  } catch {
+    throw new Error(`The configured recovery endpoint is not a valid URL: "${endpoint}".`);
+  }
+  const isLocal = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+  if (parsed.protocol !== "https:" && !isLocal) {
+    throw new Error("The recovery endpoint must be https \u2014 the Studio session token is sent with the request.");
+  }
+  return parsed;
+}
+async function postToEndpoint(opts) {
+  const { config, ref, requestedBy, studioToken } = opts;
+  const endpoint = assertSafeEndpoint(config.endpoint);
+  if (!studioToken) {
+    throw new Error(
+      "Your Studio session token is not available, so the site cannot verify who you are. This happens under cookie-based login \u2014 sign out and back in, or ask a developer to deploy manually."
+    );
+  }
+  let res;
+  try {
+    res = await fetch(endpoint.toString(), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${studioToken}`
+      },
+      body: JSON.stringify({ ref, requestedBy })
+    });
+  } catch {
+    throw new Error(
+      `Could not reach ${endpoint.host}. Check the site is up and that the route allows requests from this Studio's origin.`
+    );
+  }
+  if (res.ok) return;
+  let detail = "";
+  try {
+    const body = await res.json();
+    if (typeof body?.error === "string") detail = body.error;
+  } catch {
+  }
+  throw new Error(detail || endpointErrorMessage(res.status, endpoint.host));
+}
+function endpointErrorMessage(status, host) {
+  switch (status) {
+    case 401:
+      return "The site did not accept your Studio session. Try signing out of the Studio and back in.";
+    case 403:
+      return "Your Studio account is not permitted to trigger a deploy recovery.";
+    case 404:
+      return `No recovery route at ${host}. It may not be deployed yet \u2014 check the endpoint URL.`;
+    case 429:
+      return "A bump was requested very recently. Wait a moment before trying again.";
+    default:
+      return status >= 500 ? "The site failed while making the bump commit. Check its function logs." : `The site refused the request (${status}).`;
+  }
+}
+async function requestUnblock(opts) {
+  if (opts.config.endpoint) return postToEndpoint(opts);
+  if (!opts.config.owner || !opts.config.repo) {
+    throw new Error("Deploy recovery is misconfigured \u2014 set either `endpoint`, or `owner` and `repo`.");
+  }
+  return dispatchVersionBump({
+    config: opts.config,
+    ref: opts.ref,
+    requestedBy: opts.requestedBy
+  });
+}
+
 // src/components/DeployItem.tsx
 import { useClient, useCurrentUser } from "sanity";
 
@@ -1123,10 +1202,16 @@ function DeployItem({ target, token, onDelete, onEdit }) {
     setBumping(true);
     setBumpResult(null);
     try {
-      await dispatchVersionBump({
+      await requestUnblock({
         config: unblockConfig,
         ref,
-        requestedBy: currentUser?.name || currentUser?.email || void 0
+        requestedBy: currentUser?.name || currentUser?.email || void 0,
+        // Forwarded so a site endpoint can verify the caller is a signed-in project
+        // user. Sanity only exposes this under token-based auth, so it can be
+        // absent; `requestUnblock` reports that as its own case rather than
+        // letting the server see an anonymous request and call it a permissions
+        // failure. Unused by workflow-dispatch mode.
+        studioToken: client.config().token
       });
       setBumpResult({
         ok: true,
@@ -1144,7 +1229,7 @@ function DeployItem({ target, token, onDelete, onEdit }) {
     } finally {
       setBumping(false);
     }
-  }, [pluginConfig.unblock, latest?.meta?.githubCommitRef, currentUser, target.name, toast]);
+  }, [pluginConfig.unblock, latest?.meta?.githubCommitRef, currentUser, target.name, toast, client]);
   const branch = latest?.meta?.githubCommitRef;
   const commitMsg = latest?.meta?.githubCommitMessage?.split("\n")[0];
   const sha = shortSha(latest?.meta?.githubCommitSha);
@@ -1750,7 +1835,7 @@ function DeployTargetForm({ initial, onSaved, onClose }) {
 }
 
 // src/version.ts
-var VERSION = "1.4.0";
+var VERSION = "1.5.0";
 
 // src/components/DeployTool.tsx
 import { jsx as jsx13, jsxs as jsxs9 } from "react/jsx-runtime";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liiift-studio/deploy-vercel-from-sanity",
-  "version": "1.4.0",
+  "version": "1.5.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",