@vercel/board 0.30.0 → 0.31.0

package/dist/{commands-BtH69yqt.d.mts → commands-DK4W3HCJ.d.mts}

@@ -40,8 +40,10 @@ type CliCommand = {
   readonly subcommands?: readonly CliCommand[];
   /** Its arguments come before its subcommand, as in `sources <key> read <target>`. */
   readonly argumentsBeforeSubcommand?: true;
-  /** It does something without a subcommand too, as `identity` lists your links. */
+  /** It does something without a subcommand too, as `sources` lists the sync entries. */
   readonly runsWithoutSubcommand?: true;
+  /** The subcommand its command runs when given none, as `channels` runs `channels list`. */
+  readonly default?: true;
   /** Out of help: it still runs, for what calls it. */
   readonly hidden?: true;
 };
@@ -61,7 +63,7 @@ declare const options: {
     readonly type: 'string';
     readonly value: '@handle';
     readonly optionalValue: true;
-    readonly description: 'mentioning a handle, or you without one';
+    readonly description: 'mentioning a handle or email, or you without one';
   };
   readonly label: {
     readonly type: 'string';
@@ -202,14 +204,6 @@ declare const options: {
     readonly value: 'duration';
     readonly description: 'how long to wait (default: 30m)';
   };
-  readonly code: {
-    readonly type: 'boolean';
-    readonly description: 'post a code from your account instead of signing in';
-  };
-  readonly 'no-wait': {
-    readonly type: 'boolean';
-    readonly description: "start linking, and don't wait for it to finish";
-  };
   readonly 'no-open': {
     readonly type: 'boolean';
     readonly description: "don't open the browser";
@@ -245,6 +239,32 @@ declare const options: {
     readonly value: 'N';
     readonly description: 'repeating this many times';
   };
+  readonly can: {
+    readonly type: 'string';
+    readonly value: 'scope';
+    readonly description: 'what it may do (default: *=read,post,react,label)';
+  };
+  readonly claim: {
+    readonly type: 'string';
+    readonly multiple: true;
+    readonly value: 'k=v';
+    readonly description: 'a claim its tokens carry; the same name again is any of them';
+  };
+  readonly profile: {
+    readonly type: 'string';
+    readonly value: 'name';
+    readonly description: 'the profile every request with it writes as';
+  };
+  readonly session: {
+    readonly type: 'string';
+    readonly value: 'id';
+    readonly description: 'the session every request with it writes from';
+  };
+  readonly expires: {
+    readonly type: 'string';
+    readonly value: 'duration';
+    readonly description: 'how long it lives (default: 30d, at most 90d)';
+  };
   readonly port: {
     readonly type: 'string';
     readonly value: 'N';

package/dist/{commands-B5DHjZKK.mjs → commands-L1JSGz2Z.mjs}

@@ -15,7 +15,7 @@ const options = {
 		type: "string",
 		value: "@handle",
 		optionalValue: true,
-		description: "mentioning a handle, or you without one"
+		description: "mentioning a handle or email, or you without one"
 	},
 	label: {
 		type: "string",
@@ -156,14 +156,6 @@ const options = {
 		value: "duration",
 		description: "how long to wait (default: 30m)"
 	},
-	code: {
-		type: "boolean",
-		description: "post a code from your account instead of signing in"
-	},
-	"no-wait": {
-		type: "boolean",
-		description: "start linking, and don't wait for it to finish"
-	},
 	"no-open": {
 		type: "boolean",
 		description: "don't open the browser"
@@ -199,6 +191,32 @@ const options = {
 		value: "N",
 		description: "repeating this many times"
 	},
+	can: {
+		type: "string",
+		value: "scope",
+		description: "what it may do (default: *=read,post,react,label)"
+	},
+	claim: {
+		type: "string",
+		multiple: true,
+		value: "k=v",
+		description: "a claim its tokens carry; the same name again is any of them"
+	},
+	profile: {
+		type: "string",
+		value: "name",
+		description: "the profile every request with it writes as"
+	},
+	session: {
+		type: "string",
+		value: "id",
+		description: "the session every request with it writes from"
+	},
+	expires: {
+		type: "string",
+		value: "duration",
+		description: "how long it lives (default: 30d, at most 90d)"
+	},
 	port: {
 		type: "string",
 		value: "N",
@@ -284,70 +302,169 @@ const commands = [
 		}]
 	},
 	{
-		group: "the board",
-		name: "channels",
-		description: "channels, grouped by path prefix",
+		group: "you",
+		name: "tokens",
+		description: "tokens that act as you, narrowed, for a widget, a sandbox, or a script",
 		arguments: [],
 		options: [],
+		runsWithoutSubcommand: true,
 		examples: [{
-			name: "list the channels",
-			value: "channels"
-		}]
+			name: "list your tokens",
+			value: "tokens"
+		}],
+		subcommands: [
+			{
+				name: "list",
+				default: true,
+				description: "your live tokens, or with manage, everyone's",
+				arguments: [],
+				options: [],
+				examples: [{
+					name: "list your tokens",
+					value: "tokens list"
+				}]
+			},
+			{
+				name: "create",
+				description: "mint one, and print its secret once",
+				arguments: [{
+					name: "name",
+					required: true,
+					description: "what it is for, e.g. feedback-widget"
+				}],
+				options: [
+					option("can"),
+					option("profile"),
+					option("session"),
+					option("expires")
+				],
+				examples: [{
+					name: "a token that only posts feedback",
+					value: "tokens create feedback-widget --can feedback/=post"
+				}, {
+					name: "a week's token for a sandbox agent",
+					value: "tokens create sandbox-7 --can dev/=read,post,react --profile lemur --expires 7d"
+				}]
+			},
+			{
+				name: "revoke",
+				description: "stop one, and every token minted with it",
+				arguments: [{
+					name: "token",
+					required: true,
+					description: "its ID, as tokens shows it (t12)"
+				}],
+				options: [],
+				examples: [{
+					name: "revoke a token",
+					value: "tokens revoke t12"
+				}]
+			}
+		]
 	},
 	{
 		group: "the board",
-		name: "actors",
-		description: "actors and their handles",
+		name: "grants",
+		description: "who the board lets in beside its code's rules: tokens from an OIDC issuer with these claims",
 		arguments: [],
 		options: [],
+		runsWithoutSubcommand: true,
 		examples: [{
-			name: "list who has written here",
-			value: "actors"
-		}]
+			name: "list the grants",
+			value: "grants"
+		}],
+		subcommands: [
+			{
+				name: "list",
+				default: true,
+				description: "the board's grants",
+				arguments: [],
+				options: [],
+				examples: [{
+					name: "list the grants",
+					value: "grants list"
+				}]
+			},
+			{
+				name: "create",
+				description: "let them in, or change what they may do",
+				arguments: [{
+					name: "issuer",
+					required: true,
+					description: "vercel, github, or an https URL"
+				}],
+				options: [option("claim"), option("can")],
+				examples: [{
+					name: "let a workflow post in ci/",
+					value: "grants create github --claim repository=acme/web --can ci/=read,post"
+				}, {
+					name: "let a project's production post feedback",
+					value: "grants create vercel --claim project_id=prj_123 --claim environment=production --can feedback/=post"
+				}]
+			},
+			{
+				name: "revoke",
+				description: "stop letting them in",
+				arguments: [{
+					name: "grant",
+					required: true,
+					description: "its ID, as grants shows it (g3)"
+				}],
+				options: [],
+				examples: [{
+					name: "revoke a grant",
+					value: "grants revoke g3"
+				}]
+			}
+		]
 	},
 	{
 		group: "the board",
-		name: "identity",
-		description: "your linked Slack and GitHub accounts",
+		name: "channels",
+		description: "channels, grouped by path prefix: a first post makes one, and so does create",
 		arguments: [],
 		options: [],
 		runsWithoutSubcommand: true,
 		examples: [{
-			name: "list your linked accounts",
-			value: "identity"
+			name: "list the channels",
+			value: "channels"
 		}],
 		subcommands: [{
-			name: "link",
-			description: "link your account on a sync entry: sign in, or post a code from it",
-			arguments: [{
-				name: "key",
-				required: true,
-				description: "the sync entry, e.g. slack"
-			}],
-			options: [
-				option("code"),
-				option("no-wait"),
-				option("no-open")
-			],
+			name: "list",
+			default: true,
+			description: "channels, grouped by path prefix",
+			arguments: [],
+			options: [],
 			examples: [{
-				name: "link your Slack account",
-				value: "identity link slack"
+				name: "list the channels",
+				value: "channels list"
 			}]
 		}, {
-			name: "unlink",
-			description: "unlink one, by handle or actor ID",
+			name: "create",
+			description: "a channel, before anything posts to it (one that exists stays as it is)",
 			arguments: [{
-				name: "account",
+				name: "channel",
 				required: true,
-				description: "a handle or actor ID from identity"
+				description: "its path, such as dev/alerts"
 			}],
 			options: [],
 			examples: [{
-				name: "unlink an account",
-				value: "identity unlink @ada"
+				name: "make a channel for alerts",
+				value: "channels create dev/alerts"
 			}]
 		}]
 	},
+	{
+		group: "the board",
+		name: "actors",
+		description: "actors and their handles",
+		arguments: [],
+		options: [],
+		examples: [{
+			name: "list who has written here",
+			value: "actors"
+		}]
+	},
 	{
 		group: "messages",
 		name: "read",
@@ -558,7 +675,7 @@ const commands = [
 	{
 		group: "messages",
 		name: "typing",
-		description: "show typing in the thread's synced platform threads (marks WhatsApp read)",
+		description: "show typing in the thread's synced platform threads",
 		arguments: [id(), {
 			name: "status",
 			required: false,

package/dist/{conformance-C7fwIvmN.mjs → conformance-DK43HiHf.mjs}

@@ -1,5 +1,5 @@
-import { u as BoardError } from "./errors-C_5rB8Iz.mjs";
-import { r as compileAccess } from "./access-CQ39gqEV.mjs";
+import { u as BoardError } from "./errors-CJXhhzvT.mjs";
+import { r as compileAccess } from "./access-CY5xVMIK.mjs";
 //#region src/conformance/index.ts
 var Mismatch = class extends Error {};
 const show = (value) => JSON.stringify(value) ?? String(value);
@@ -18,6 +18,16 @@ async function rejects(attempt, status, code, what) {
 	}
 	throw new Mismatch(`${what}: expected ${status} ${code}, and it succeeded`);
 }
+/** That `attempt` is refused with `status`, whatever code the board gives it. */
+async function refused(attempt, status, what) {
+	try {
+		await attempt;
+	} catch (error) {
+		if (error instanceof BoardError && error.status === status) return;
+		throw new Mismatch(`${what}: expected ${status}, got ${error instanceof BoardError ? `${error.status} ${error.code}` : String(error)}`);
+	}
+	throw new Mismatch(`${what}: expected ${status}, and it succeeded`);
+}
 /** Where a registration is woken, to put back after a check replaces it: its path (and branch) on a board that wakes by path, or its url. */
 function wokenAt(registered) {
 	if (!registered?.path) return { url: registered?.url ?? null };
@@ -32,9 +42,16 @@ function isRef(value, what) {
 }
 /**
 * The groups a board may keep none of, saying so with a 501: a board on `a2()` without a scheduler
-* answers `no_scheduler`, and without a blob store `no_files`.
+* answers `no_scheduler`, and without a blob store `no_files`; one whose `access` is one function keeps
+* no grants, `no_grants`. A board that's meant to keep something and doesn't yet answers otherwise,
+* and fails.
 */
-const OPTIONAL = /* @__PURE__ */ new Set(["schedules", "attachments"]);
+const OPTIONAL = /* @__PURE__ */ new Set([
+	"schedules",
+	"grants",
+	"tokens",
+	"attachments"
+]);
 const needRoot = (ctx) => {
 	check(ctx.root && ctx.reply, "posting failed, so there's nothing to read");
 	return {
@@ -42,6 +59,23 @@ const needRoot = (ctx) => {
 		reply: ctx.reply
 	};
 };
+/** A grant for a project that doesn't exist, from an environment its deployments would have: it lets nobody in. */
+const grantFor = (ctx) => ({
+	issuer: "vercel",
+	claims: {
+		environment: "preview",
+		project_id: `prj_conformance${ctx.labels.conformance}`
+	}
+});
+/** Sets the check's grant, or says why it can't: changing who the board trusts takes `manage` in every channel. */
+async function firstGrant(ctx) {
+	try {
+		return await ctx.board.createGrant(grantFor(ctx));
+	} catch (error) {
+		if (error instanceof BoardError && error.status === 403) return { skip: "this token can't change the board's grants" };
+		throw error;
+	}
+}
 /** The sync key the sync checks register, a platform of their own, so nothing reaches a real one. */
 const SYNC_KEY = "conformance";
 /**
@@ -354,10 +388,25 @@ const CHECKS = [
 		run: async (ctx) => {
 			const found = (await ctx.board.channels()).find((c) => c.path === ctx.channel);
 			check(found, `the channels should include ${ctx.channel}`);
-			check(typeof found.lastIndex === "number", `a channel's lastIndex should be a number, got ${show(found.lastIndex)}`);
+			for (const field of [
+				"lastIndex",
+				"messages",
+				"threads"
+			]) check(found[field] === void 0 || typeof found[field] === "number", `a channel's ${field} should be a number or left out, got ${show(found[field])}`);
 			check((await ctx.board.actors()).some((a) => a.id === ctx.me.actor), `the actors should include ${ctx.me.actor}`);
 		}
 	},
+	{
+		group: "core",
+		name: "creates a channel only once: one a post made is there already",
+		run: async (ctx) => {
+			needRoot(ctx);
+			const { channel, created } = await ctx.board.createChannel(ctx.channel);
+			same(created, false, `creating ${ctx.channel}, which this run posted to`);
+			same(channel.path, ctx.channel, "the channel's path");
+			await rejects(ctx.board.createChannel("Not A Channel"), 400, "invalid_request", "creating a malformed channel");
+		}
+	},
 	{
 		group: "core",
 		name: "answers 404 for an ID that names nothing",
@@ -411,6 +460,174 @@ const CHECKS = [
 			}
 		}
 	},
+	{
+		group: "grants",
+		name: "grants a project, lists it, takes the same grant again as one, and revokes it",
+		run: async (ctx) => {
+			const asked = grantFor(ctx);
+			const first = await firstGrant(ctx);
+			if ("skip" in first) return first.skip;
+			try {
+				isRef(first.grant.id, "a grant's id");
+				same(first.created, true, "a new grant: created");
+				same(first.grant.issuer, "vercel", "the grant's issuer");
+				same(first.grant.claims.project_id, asked.claims.project_id, "the grant's project_id");
+				check(first.grant.can["*"]?.includes("post"), `a grant with no can should let them post everywhere, got ${show(first.grant.can)}`);
+				same(first.grant.by, ctx.me.actor, "the grant's by");
+				const again = await ctx.board.createGrant(asked);
+				same(again.created, false, "the same issuer and claims again: created");
+				same(again.grant.id, first.grant.id, "the same issuer and claims again: its id");
+				same((await ctx.board.grants()).filter((grant) => grant.id === first.grant.id).length, 1, "grants listing it");
+			} catch (error) {
+				await ctx.board.revokeGrant(first.grant.id).catch(() => {});
+				throw error;
+			}
+			same((await ctx.board.revokeGrant(first.grant.id)).revoked, true, "revoking it");
+			same((await ctx.board.revokeGrant(first.grant.id)).revoked, false, "revoking it again");
+			check(!(await ctx.board.grants()).some((grant) => grant.id === first.grant.id), "grants shouldn't list it once it's revoked");
+		}
+	},
+	{
+		group: "grants",
+		name: "changes a grant's can when it's set again",
+		run: async (ctx) => {
+			const first = await firstGrant(ctx);
+			if ("skip" in first) return first.skip;
+			const { grant } = first;
+			try {
+				const narrowed = await ctx.board.createGrant({
+					...grantFor(ctx),
+					can: { [ctx.channel]: ["post"] }
+				});
+				same(narrowed.created, false, "setting its can: created");
+				same(narrowed.grant.id, grant.id, "setting its can: its id");
+				same(show(narrowed.grant.can), show({ [ctx.channel]: ["post"] }), "the grant's can");
+			} finally {
+				await ctx.board.revokeGrant(grant.id).catch(() => {});
+			}
+		}
+	},
+	{
+		group: "grants",
+		name: "grants a GitHub repository's workflows, and another team's project",
+		run: async (ctx) => {
+			const first = await firstGrant(ctx);
+			if ("skip" in first) return first.skip;
+			const made = [first.grant.id];
+			try {
+				const github = await ctx.board.createGrant({
+					issuer: "github",
+					claims: { repository: `acme/conformance-${ctx.labels.conformance}` },
+					can: { [ctx.channel]: ["post"] }
+				});
+				made.push(github.grant.id);
+				same(github.grant.issuer, "github", "the GitHub grant's issuer");
+				const theirs = await ctx.board.createGrant({
+					issuer: "vercel",
+					claims: {
+						environment: "production",
+						owner_id: `team_conformance${ctx.labels.conformance}`,
+						project_id: `prj_conformance${ctx.labels.conformance}x`
+					}
+				});
+				made.push(theirs.grant.id);
+				same(theirs.grant.claims.owner_id, `team_conformance${ctx.labels.conformance}`, "another team's grant's owner_id");
+				const listed = new Set((await ctx.board.grants()).map((grant) => grant.id));
+				check(made.every((id) => listed.has(id)), `grants should list ${made.join(", ")}`);
+			} finally {
+				for (const id of made) await ctx.board.revokeGrant(id).catch(() => {});
+			}
+		}
+	},
+	{
+		group: "grants",
+		name: "keeps two environments of one project as two grants, and revokes one without the other",
+		run: async (ctx) => {
+			const first = await firstGrant(ctx);
+			if ("skip" in first) return first.skip;
+			const made = [first.grant.id];
+			try {
+				const production = await ctx.board.createGrant({
+					...grantFor(ctx),
+					claims: {
+						...grantFor(ctx).claims,
+						environment: "production"
+					}
+				});
+				made.push(production.grant.id);
+				same(production.created, true, "another environment: created");
+				check(production.grant.id !== first.grant.id, "another environment should be another grant");
+				same((await ctx.board.revokeGrant(first.grant.id)).revoked, true, "revoking the preview grant");
+				const listed = (await ctx.board.grants()).map((grant) => grant.id);
+				check(listed.includes(production.grant.id) && !listed.includes(first.grant.id), `grants should list ${production.grant.id} and not ${first.grant.id}, got ${show(listed)}`);
+			} finally {
+				for (const id of made) await ctx.board.revokeGrant(id).catch(() => {});
+			}
+		}
+	},
+	{
+		group: "tokens",
+		name: "mints a token, shows its secret only then, lists it, and revokes it",
+		run: async (ctx) => {
+			const name = `conformance-${ctx.labels.conformance}`;
+			const { token, secret } = await ctx.board.createToken({
+				name,
+				can: { [ctx.channel]: ["read"] },
+				expires: "1h"
+			});
+			try {
+				isRef(token.id, "a token's id");
+				check(typeof secret === "string" && secret.length >= 32, `a token's secret should be a string of at least 32 characters, got ${typeof secret}`);
+				same(token.name, name, "the token's name");
+				same(show(token.can), show({ [ctx.channel]: ["read"] }), "the token's can");
+				const left = Date.parse(token.expiresAt) - Date.now();
+				check(left > 33e5 && left <= 3605e3, `a token minted for 1h should expire in an hour, got ${token.expiresAt}`);
+				const listed = await ctx.board.tokens();
+				check(listed.some((found) => found.id === token.id), `tokens should list ${token.id}`);
+				check(!JSON.stringify(listed).includes(secret), "tokens shouldn't show a token's secret");
+			} catch (error) {
+				await ctx.board.revokeToken(token.id).catch(() => {});
+				throw error;
+			}
+			same((await ctx.board.revokeToken(token.id)).revoked, true, "revoking it");
+			same((await ctx.board.revokeToken(token.id)).revoked, false, "revoking it again");
+			check(!(await ctx.board.tokens()).some((found) => found.id === token.id), "tokens shouldn't list it once it's revoked");
+		}
+	},
+	{
+		group: "tokens",
+		name: "lets a token do what its can says, as whoever minted it, and nothing once it's revoked",
+		run: async (ctx) => {
+			if (!ctx.withToken) return "this run can't call the board with a token's secret";
+			const { root } = needRoot(ctx);
+			const { token, secret } = await ctx.board.createToken({
+				name: `conformance-${ctx.labels.conformance}-reads`,
+				can: { [ctx.channel]: ["read"] },
+				expires: "1h"
+			});
+			const holder = ctx.withToken(secret);
+			try {
+				const me = await holder.me();
+				same(me.principal, ctx.me.principal, "a token's principal, its minter's");
+				const want = { [ctx.channel]: ["read"] };
+				check(show(me.can) === show(want), `what a token that may only read says it may do: expected ${show(want)}, got ${show(me.can)}`);
+				same((await holder.thread(root.id)).message.id, root.id, "a thread read with a token that may read it");
+				await refused(holder.post(ctx.channel, {
+					text: "conformance: a token that may only read",
+					labels: ctx.labels,
+					noSync: true
+				}).then((message) => {
+					ctx.posted.push(message.id);
+					return message;
+				}), 403, "a post with a token that may only read");
+			} catch (error) {
+				await ctx.board.revokeToken(token.id).catch(() => {});
+				throw error;
+			}
+			same((await ctx.board.revokeToken(token.id)).revoked, true, "revoking it");
+			await refused(holder.me(), 401, "a request with a revoked token");
+		}
+	},
 	{
 		group: "attachments",
 		name: "takes a file, posts it, and gives it back",
@@ -703,20 +920,6 @@ const CHECKS = [
 			same(thread.message.noSync, true, "a post's noSync, read back");
 			same(thread.replies.find((m) => m.id === reply.id)?.noSync, true, "a reply's noSync, read back");
 		}
-	},
-	{
-		group: "sync",
-		name: "finds no one for a platform account nobody linked",
-		run: async (ctx) => {
-			let found;
-			try {
-				found = await ctx.board.syncFind({ account: `${SYNC_KEY}:user:${ctx.labels.conformance}` });
-			} catch (error) {
-				if (error instanceof BoardError && error.status === 403) return "this token can't look up a sync here";
-				throw error;
-			}
-			same(found.person, null, "who an account nobody linked is");
-		}
 	}
 ];
 /** Runs the checks against `board`, in order, and reports each. It never throws for what the board answers. */
@@ -754,7 +957,8 @@ async function conformance(board, options = {}) {
 			limit: 1
 		})).cursor,
 		me,
-		posted: []
+		posted: [],
+		...options.withToken ? { withToken: options.withToken } : {}
 	};
 	try {
 		for (const { group, name, run } of CHECKS) try {

package/dist/conformance.d.mts

@@ -1,4 +1,4 @@
-import { d as Board } from "./backend-n3hajfrD.mjs";
+import { f as Board } from "./backend-Bob-5CM7.mjs";
 //#region src/conformance/index.d.ts
 /**
  * Checks that a board speaks the protocol, through a handle on it (`conformance(board())`), as
@@ -7,7 +7,7 @@ import { d as Board } from "./backend-n3hajfrD.mjs";
  * (`conformance` by default), keeps every post on the board, and deletes what it posted.
  */
 /** What a check is about, for the report's headings. */
-export type CheckGroup = 'core' | 'schedules' | 'attachments' | 'watchers' | 'sync';
+export type CheckGroup = 'core' | 'schedules' | 'grants' | 'tokens' | 'attachments' | 'watchers' | 'sync';
 export type CheckResult = {
   group: CheckGroup;
   name: string;
@@ -24,6 +24,12 @@ export type ConformanceReport = {
 export type ConformanceOptions = {
   /** Where it posts. Default `conformance`. */
   channel?: string;
+  /**
+   * The same board, with a board token's secret as the credential (as `BOARD_TOKEN` sends it):
+   * the tokens check calls it so to see that a token does only what its `can` says. Without it,
+   * that check is skipped.
+   */
+  withToken?: (secret: string) => Board;
 };
 /** Runs the checks against `board`, in order, and reports each. It never throws for what the board answers. */
 export declare function conformance(board: Board, options?: ConformanceOptions): Promise<ConformanceReport>;

package/dist/conformance.mjs

@@ -1,2 +1,2 @@
-import { t as conformance } from "./conformance-C7fwIvmN.mjs";
+import { t as conformance } from "./conformance-DK43HiHf.mjs";
 export { conformance };