@vercel/board 0.24.0 → 0.25.1

package/dist/{middleware-DUjyQP_a.mjs → middleware-ChKM1zuu.mjs}

@@ -1,5 +1,5 @@
 import { m as MESSAGE_TEXT_MAX, p as Labels } from "./schemas-Be08nyfW.mjs";
-import { t as HttpError } from "./errors-CQ-fwxM3.mjs";
+import { t as HttpError } from "./errors-CusN4x2l.mjs";
 import { z } from "zod";
 //#region src/server/middleware.ts
 /** A write the middleware didn't let through: the API answers 422 with what it responded. */

package/dist/{node-CirFYqw0.mjs → node-Bkd1x0QI.mjs}

@@ -1,4 +1,4 @@
-import { t as BoardError } from "./client-ClznIBMg.mjs";
+import { t as BoardError } from "./client-D0Px7KzF.mjs";
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
@@ -52,6 +52,13 @@ const LOOPBACK = /* @__PURE__ */ new Set([
 	"localhost",
 	"[::1]"
 ]);
+const PROJECT_ID = /^prj_[A-Za-z0-9]{1,64}$/;
+const URL_SHAPE = /^https?:\/\/[A-Za-z0-9.-]{1,253}(:\d{1,5})?(\/[A-Za-z0-9._~%/-]{0,2000})?$/;
+/**
+* A value a board said, as a message can show it: only when it's what it should be (a project
+* ID, a URL), since the handle's messages are trusted where a board's words aren't.
+*/
+const shown = (value, shape) => typeof value === "string" && shape.test(value) ? value : void 0;
 /** Where `vb serve` leaves the token for the board it runs at `url`: only this user can read it. */
 function localTokenFile(url) {
 	const normalized = url.replace(/\/+$/, "");
@@ -99,7 +106,7 @@ function detectAgent(env = process.env) {
 		profile: named,
 		session: null
 	});
-	if (found.length > 1) throw new BoardError("ambiguous_agent", `several agent environments detected (${found.map((a) => a.profile).join(", ")}): choose one with a profile, or none`, 0);
+	if (found.length > 1) throw new BoardError("ambiguous_agent", `Several coding agents' environments are set (${found.map((a) => a.profile).join(", ")}), so it can't tell which one is writing.`, 0, { hint: "Pick one with a profile, or none to write as yourself." });
 	return found[0] ?? null;
 }
 const expiry = (token) => {
@@ -157,7 +164,7 @@ async function personToken(audience, discovery) {
 		return filled;
 	}
 	if (cached) return cached;
-	if (!discovery.project_id) throw new BoardError("no_project", `the board at ${discovery.url} doesn't know its Vercel project`, 0);
+	if (!discovery.project_id) throw new BoardError("no_project", `The board at ${audience} doesn't know its Vercel project, so there's no Vercel login token to mint for it.`, 0, { hint: "Pass a token it accepts in BOARD_TOKEN." });
 	const authToken = await vercelLogin().catch(() => null);
 	const project = await boardProject(audience, discovery, authToken);
 	let development;
@@ -167,7 +174,7 @@ async function personToken(audience, discovery) {
 			method: "POST",
 			headers: { authorization: `Bearer ${authToken}` }
 		});
-		if (response.status === 403 || response.status === 404) throw new BoardError("no_access", "your Vercel account can't access this board's project: ask for access to it", response.status);
+		if (response.status === 403 || response.status === 404) throw new BoardError("no_access", "Your Vercel account can't access this board's project.", response.status, { hint: "Ask someone on the project's team for access to it." });
 		if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
 		development = (await response.json()).token;
 	} catch (error) {
@@ -210,8 +217,8 @@ async function boardProject(url, discovery, authToken) {
 		});
 		return response.ok ? await response.json() : null;
 	} : vercelCliApi, host);
-	if (!found) throw new BoardError("no_access", `your Vercel login can't see the project ${host} belongs to: run \`vercel login\` or ask for access to it`, 0);
-	if (found.projectId !== discovery.project_id) throw new BoardError("wrong_project", `the board at ${url} says its project is ${discovery.project_id}, but it's a deployment of ${found.projectId}, so vb won't sign in to it`, 0);
+	if (!found) throw new BoardError("no_access", `Your Vercel login can't see the project ${host} belongs to.`, 0, { hint: "Log in as someone on the project's team (vercel login), or ask for access to it." });
+	if (found.projectId !== discovery.project_id) throw new BoardError("wrong_project", `The board at ${url} says its project is ${shown(discovery.project_id, PROJECT_ID) ?? "another one"}, but it's a deployment of ${found.projectId}, so no token is minted for it.`, 0);
 	return {
 		id: found.projectId,
 		team: found.ownerId.startsWith("team_") ? found.ownerId : null
@@ -230,7 +237,7 @@ async function tokenFromVercelCli(project) {
 		const { stdout } = await promisify(execFile)("vercel", args, { timeout: 3e4 });
 		return JSON.parse(stdout).token;
 	} catch {
-		throw new BoardError("not_logged_in", "not signed in to Vercel: run `vercel login`", 0);
+		throw new BoardError("not_logged_in", "You're not logged in to Vercel.", 0, { hint: "Run vercel login." });
 	}
 }
 /** Your Vercel username, display name, and avatar (Vercel serves avatars publicly). */
@@ -252,13 +259,13 @@ async function githubActionsToken(audience) {
 	const url = new URL(process.env.ACTIONS_ID_TOKEN_REQUEST_URL);
 	url.searchParams.set("audience", audience);
 	const response = await fetch(url, { headers: { authorization: `bearer ${process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN}` } });
-	if (!response.ok) throw new BoardError("no_token", `GitHub Actions refused an OIDC token (${response.status}): does the job have \`permissions: id-token: write\`?`, 0);
+	if (!response.ok) throw new BoardError("no_token", `GitHub Actions refused an OIDC token (${response.status}).`, 0, { hint: "Give the job `permissions: id-token: write`." });
 	return (await response.json()).value;
 }
 /** The board the environment points at: `BOARD_URL`. */
 function boardUrl() {
 	const url = process.env.BOARD_URL?.replace(/\/+$/, "");
-	if (!url) throw new BoardError("no_board", "no board URL: set BOARD_URL", 0);
+	if (!url) throw new BoardError("no_board", "There's no board URL: BOARD_URL isn't set.", 0, { hint: "Set BOARD_URL, or pass the URL to http()." });
 	return url;
 }
 /**
@@ -272,9 +279,9 @@ function connect(url, options = {}) {
 	const doFetch = guarded(url, options.fetch ?? ((input, init) => globalThis.fetch(input, init)), options.token);
 	let discovery;
 	const discover = () => discovery ??= doFetch(url).then(async (response) => {
-		if (!response.ok) throw new BoardError("no_board", `no board at ${url} (${response.status})`, response.status);
+		if (!response.ok) throw new BoardError("no_board", `There's no board at ${url}: it answered ${response.status}.`, response.status);
 		const found = await response.json();
-		if (found.audience !== url) throw new BoardError("wrong_audience", `the board at ${url} says its URL is ${found.audience}: use that URL`, 0);
+		if (found.audience !== url) throw new BoardError("wrong_audience", `The board at ${url} says its URL is ${shown(found.audience, URL_SHAPE) ?? "another one"}.`, 0, { hint: shown(found.audience, URL_SHAPE) ? `Use ${found.audience}.` : "Use the URL its discovery names." });
 		return found;
 	});
 	let cached = null;
@@ -381,6 +388,19 @@ var Wall = class extends Error {
 	}
 };
 /**
+* A wall reached after a redirect to another origin, which none of a request's credentials follow,
+* by design: no bypass or token gets through it from here, so none is looked for.
+*/
+var Moved = class extends Error {
+	origin;
+	status;
+	constructor(origin, status) {
+		super("moved");
+		this.origin = origin;
+		this.status = status;
+	}
+};
+/**
 * This deployment's Vercel OIDC token, with `url` as its audience: what a hosted client sends a
 * board, for Deployment Protection's Trusted Sources. Its `cause` says why it couldn't.
 */
@@ -388,7 +408,7 @@ async function hostedToken(url) {
 	try {
 		return await getVercelOidcToken({ audience: url });
 	} catch (cause) {
-		throw Object.assign(new BoardError("no_token", `cannot obtain Vercel OIDC credentials for ${url}: enable OIDC on the calling project or supply token / BOARD_TOKEN; configure Deployment Protection Trusted Sources for its project and environment`, 0), { cause });
+		throw Object.assign(new BoardError("no_token", `This deployment can't get a Vercel OIDC token for ${url}.`, 0, { hint: "Enable OIDC on its project, or pass a token (BOARD_TOKEN), and add its project to the board project's Deployment Protection Trusted Sources." }), { cause });
 	}
 }
 /** A host this deployment answers on, as Vercel's system variables name them (bare hosts). */
@@ -403,7 +423,12 @@ function guarded(url, doFetch, suppliedToken) {
 	let secret;
 	let looked;
 	let envRejected = false;
-	return async (input, init = {}) => {
+	return (input, init) => attempt(input, init).catch((error) => {
+		if (!(error instanceof Moved)) throw error;
+		const there = shown(`${error.origin}${new URL(url).pathname}`, URL_SHAPE);
+		throw new BoardError("redirected", `${url} redirects to ${there ? new URL(there).origin : "another origin"}, and its credentials don't follow it there, so Deployment Protection turns it away.`, error.status, { hint: there ? `Use ${there}.` : "Use the URL it redirects to." });
+	});
+	async function attempt(input, init = {}) {
 		const headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : void 0));
 		init = {
 			...init,
@@ -414,7 +439,7 @@ function guarded(url, doFetch, suppliedToken) {
 			return await through(doFetch, input, init, fromEnv);
 		} catch (error) {
 			if (!(error instanceof Wall)) throw error;
-			if (process.env.VERCEL !== "1") throw new BoardError("protected", `${url} is behind Vercel Deployment Protection and rejected VERCEL_AUTOMATION_BYPASS_SECRET; check it against ${WHERE}`, error.status);
+			if (process.env.VERCEL !== "1") throw new BoardError("protected", `${url} is behind Vercel Deployment Protection, and it rejected VERCEL_AUTOMATION_BYPASS_SECRET.`, error.status, { hint: `Check VERCEL_AUTOMATION_BYPASS_SECRET against ${WHERE}.` });
 			envRejected = true;
 		}
 		if (process.env.VERCEL === "1") {
@@ -423,7 +448,7 @@ function guarded(url, doFetch, suppliedToken) {
 				headers.set("x-vercel-trusted-oidc-idp-token", token);
 			}
 			return through(doFetch, input, init, null).catch((error) => {
-				throw error instanceof Wall ? new BoardError("protected", `${url} rejected Vercel OIDC access: configure Deployment Protection Trusted Sources for the calling project and environment`, error.status) : error;
+				throw error instanceof Wall ? new BoardError("protected", `${url} is behind Vercel Deployment Protection, and it rejected this deployment's Vercel OIDC token.`, error.status, { hint: "Add this project and environment to the board project's Deployment Protection Trusted Sources." }) : error;
 			});
 		}
 		const used = await (secret ??= readBypass(host));
@@ -445,9 +470,9 @@ function guarded(url, doFetch, suppliedToken) {
 				return through(doFetch, input, init, found);
 			});
 		} catch (error) {
-			throw error instanceof Wall ? new BoardError("protected", `${url} is behind Vercel Deployment Protection and its project's automation bypass didn't get through; set VERCEL_AUTOMATION_BYPASS_SECRET (${WHERE})`, error.status) : error;
+			throw error instanceof Wall ? new BoardError("protected", `${url} is behind Vercel Deployment Protection, and its project's automation bypass didn't get through.`, error.status, { hint: `Set VERCEL_AUTOMATION_BYPASS_SECRET (${WHERE}).` }) : error;
 		}
-	};
+	}
 }
 /**
 * One request that recognizes the wall: a redirect to `/sso-api`, an HTML
@@ -464,6 +489,8 @@ async function through(doFetch, input, init, bypass) {
 	const method = (init.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
 	let headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : void 0));
 	if (bypass) headers.set("x-vercel-protection-bypass", bypass);
+	let moved = null;
+	const wall = (status) => moved ? new Moved(moved, status) : new Wall(status);
 	for (let hops = 0;; hops++) {
 		const response = await doFetch(hops === 0 ? input : target, {
 			...init,
@@ -473,10 +500,11 @@ async function through(doFetch, input, init, bypass) {
 		const location = response.status >= 300 && response.status < 400 ? response.headers.get("location") : null;
 		if (location) {
 			const next = new URL(location, target);
-			if (next.pathname.startsWith("/sso-api")) throw new Wall(response.status);
+			if (next.pathname.startsWith("/sso-api")) throw wall(response.status);
 			if (method === "GET" || method === "HEAD") {
-				if (hops >= 20) throw new BoardError("too_many_redirects", `too many redirects from ${target}`, response.status);
+				if (hops >= 20) throw new BoardError("too_many_redirects", `${target} redirected more than 20 times.`, response.status);
 				if (next.origin !== new URL(target).origin) {
+					moved = next.origin;
 					headers = new Headers(headers);
 					headers.delete("authorization");
 					headers.delete("x-vercel-trusted-oidc-idp-token");
@@ -487,8 +515,8 @@ async function through(doFetch, input, init, bypass) {
 			}
 		}
 		const { status } = response;
-		if (/^text\/html\b/i.test(response.headers.get("content-type") ?? "") && !response.headers.has("content-disposition") && (status >= 200 && status < 300 || status === 401 || status === 403)) throw new Wall(status);
-		if (status === 401 && response.headers.has("x-vercel-error")) throw new Wall(status);
+		if (/^text\/html\b/i.test(response.headers.get("content-type") ?? "") && !response.headers.has("content-disposition") && (status >= 200 && status < 300 || status === 401 || status === 403)) throw wall(status);
+		if (status === 401 && response.headers.has("x-vercel-error")) throw wall(status);
 		return response;
 	}
 }
@@ -517,7 +545,7 @@ const automationBypass = (bypasses) => Object.entries(bypasses ?? {}).find(([, v
 * `protectionBypass` has it. When there's none, it's created.
 */
 async function projectBypass(url, host, doFetch) {
-	const blocked = (why) => new BoardError("protected", `${url} is behind Vercel Deployment Protection, and your Vercel login ${why}, or set VERCEL_AUTOMATION_BYPASS_SECRET (${WHERE})`, 0);
+	const blocked = (why, fix) => new BoardError("protected", `${url} is behind Vercel Deployment Protection, and your Vercel login ${why}.`, 0, { hint: `${fix}, or set VERCEL_AUTOMATION_BYPASS_SECRET (${WHERE}).` });
 	let api;
 	try {
 		const token = await vercelLogin();
@@ -536,19 +564,19 @@ async function projectBypass(url, host, doFetch) {
 		api = vercelCliApi;
 	}
 	const project = await findProject(api, host);
-	if (!project) throw blocked("can't see its project: run `vercel login` or ask for access");
+	if (!project) throw blocked("can't see its project", "Log in as someone on its project's team (vercel login), ask for access");
 	const scope = project.ownerId.startsWith("team_") ? `?teamId=${project.ownerId}` : "";
 	const details = await api("GET", `/v9/projects/${project.projectId}${scope}`);
-	if (!details) throw blocked("can't read its project's settings: ask for access");
+	if (!details) throw blocked("can't read its project's settings", "Ask for access to its project");
 	const existing = automationBypass(details.protectionBypass);
 	if (existing) return {
 		secret: existing,
 		created: false
 	};
-	if (!details.ssoProtection && !details.passwordProtection && !details.passport) throw new BoardError("no_board", `no board at ${url}: it answered with a web page, and its Vercel project isn't protected`, 0);
+	if (!details.ssoProtection && !details.passwordProtection && !details.passport) throw new BoardError("no_board", `There's no board at ${url}: it answered with a web page, and its Vercel project isn't protected.`, 0);
 	const created = await api("PATCH", `/v1/projects/${project.projectId}/protection-bypass${scope}`);
 	const secret = automationBypass(created?.protectionBypass);
-	if (!secret) throw blocked("can't read or create its project's automation bypass: ask a project admin");
+	if (!secret) throw blocked("can't read or create its project's automation bypass", "Ask a project admin to create one");
 	process.stderr.write(`created a Protection Bypass for Automation on the Vercel project ${details?.name ?? project.projectId}\n`);
 	return {
 		secret,
@@ -579,7 +607,7 @@ async function findProject(api, host) {
 let vercelCli;
 const vercelCliApi = async (method, path) => {
 	vercelCli ??= promisify(execFile)("vercel", ["whoami", "--non-interactive"], { timeout: 1e4 }).then(() => true, () => false);
-	if (!await vercelCli) throw new BoardError("not_logged_in", "not signed in to Vercel: run `vercel login`", 0);
+	if (!await vercelCli) throw new BoardError("not_logged_in", "You're not logged in to Vercel.", 0, { hint: "Run vercel login." });
 	const args = [
 		"api",
 		path,
@@ -595,7 +623,7 @@ const vercelCliApi = async (method, path) => {
 		run.child.stdin?.end(method === "PATCH" ? "{}" : "");
 		return JSON.parse((await run).stdout);
 	} catch (error) {
-		if (error.code === "ENOENT") throw new BoardError("not_logged_in", "not signed in to Vercel: run `vercel login`", 0);
+		if (error.code === "ENOENT") throw new BoardError("not_logged_in", "You're not logged in to Vercel.", 0, { hint: "Run vercel login." });
 		return null;
 	}
 };