@vercel/board 0.0.0 → 0.15.0

package/dist/access-CJU2-vaa.mjs

@@ -0,0 +1,226 @@
+import { c as ChannelPath, v as SCOPE_MAX } from "./schemas-Be08nyfW.mjs";
+import { a as forbidden } from "./errors-DX3hpwWt.mjs";
+//#region src/server/access.ts
+/**
+* What a principal may do in a channel. `read` covers messages, threads,
+* `/events`, and schedules; `post` starts threads and edits your own messages;
+* `manage` is the board's own bookkeeping (inbox, sources).
+*/
+const PERMISSIONS = [
+	"read",
+	"post",
+	"react",
+	"label",
+	"sync",
+	"manage"
+];
+/**
+* One hop of implication, kept as data like Vercel's git broker
+* (`ACTION_IMPLICATIONS`). Each verb that addresses a message by ID implies
+* `read`, so none of them is a blind existence oracle. `post` implies nothing:
+* write-only is `['post']`.
+*/
+const IMPLIES = {
+	read: [],
+	post: [],
+	react: ["read"],
+	label: ["read"],
+	sync: ["read"],
+	manage: [
+		"read",
+		"post",
+		"react",
+		"label",
+		"sync"
+	]
+};
+const ORDER = new Map(PERMISSIONS.map((permission, index) => [permission, index]));
+const SHAPE = "write *, a channel, or a channel and its subtree (feedback/)";
+/** A pattern's parts; any other `*` throws, and says what to type instead. */
+function parsePattern(pattern) {
+	if (pattern === "*") return { kind: "all" };
+	if (pattern.includes("*")) {
+		const before = pattern.slice(0, pattern.indexOf("*")).replace(/\/+$/, "");
+		const hint = before === "" ? "write * for every channel" : ChannelPath.safeParse(before).success ? `write ${before}/ for ${before} and its subtree` : SHAPE;
+		throw new Error(`invalid channel pattern ${pattern}: ${hint}`);
+	}
+	const subtree = pattern.endsWith("/");
+	const path = subtree ? pattern.slice(0, -1) : pattern;
+	if (!ChannelPath.safeParse(path).success) throw new Error(`invalid channel pattern ${pattern || "(empty)"}: ${SHAPE}`);
+	return subtree ? {
+		kind: "subtree",
+		path
+	} : {
+		kind: "exact",
+		path
+	};
+}
+const key = (pattern) => pattern.kind === "all" ? "*" : pattern.kind === "subtree" ? `${pattern.path}/` : pattern.path;
+/** A grant with its implications, closed: `['label']` is `read` and `label`. */
+function expand(grant) {
+	const out = /* @__PURE__ */ new Set();
+	const add = (permission) => {
+		if (!ORDER.has(permission)) throw new Error(`unknown permission ${String(permission)}: use ${PERMISSIONS.join(", ")}`);
+		if (out.has(permission)) return;
+		out.add(permission);
+		for (const implied of IMPLIES[permission]) add(implied);
+	};
+	for (const permission of grant === "all" ? PERMISSIONS : grant) add(permission);
+	return out;
+}
+const NOTHING = /* @__PURE__ */ new Set();
+function compile(entries) {
+	let all = null;
+	const exact = /* @__PURE__ */ new Map();
+	const subtrees = [];
+	for (const [pattern, permissions] of entries) if (pattern.kind === "all") all = permissions;
+	else if (pattern.kind === "exact") exact.set(pattern.path, permissions);
+	else subtrees.push([pattern.path, permissions]);
+	subtrees.sort((a, b) => b[0].length - a[0].length);
+	return {
+		all,
+		exact,
+		subtrees
+	};
+}
+const under = (channel, path) => channel === path || channel.startsWith(`${path}/`);
+/** What the most specific pattern covering `channel` gives; with `subtreeOnly`, ignoring an exact rule for it. */
+function resolve(rules, channel, subtreeOnly = false) {
+	if (!subtreeOnly) {
+		const exact = rules.exact.get(channel);
+		if (exact) return exact;
+	}
+	for (const [path, permissions] of rules.subtrees) if (under(channel, path)) return permissions;
+	return rules.all ?? NOTHING;
+}
+/**
+* What `rules` gives every channel `pattern` governs where nothing more
+* specific does. The patterns matching one channel form a chain, so that's one
+* answer: an exact channel resolves as itself, a subtree as whatever covers the
+* subtree's root, ignoring an exact rule for the root.
+*/
+const at = (rules, pattern) => pattern.kind === "all" ? rules.all ?? NOTHING : resolve(rules, pattern.path, pattern.kind === "subtree");
+const equal = (a, b) => a.size === b.size && [...a].every((permission) => b.has(permission));
+/** The answer of the pattern next less specific than `pattern` in `rules`. */
+function parent(rules, pattern) {
+	if (pattern.kind === "exact") return resolve(rules, pattern.path, true);
+	if (pattern.kind === "subtree") {
+		for (const [path, permissions] of rules.subtrees) if (path !== pattern.path && under(pattern.path, path)) return permissions;
+	}
+	return rules.all ?? NOTHING;
+}
+/** Drops rules that say what their parent says, and an empty `*`, so equal access has one summary. */
+function canonical(entries) {
+	const rules = compile(entries);
+	return compile(entries.filter(([pattern, permissions]) => pattern.kind === "all" ? permissions.size > 0 : !equal(permissions, parent(rules, pattern))));
+}
+function entriesOf(can) {
+	if (can === "all" || Array.isArray(can)) return [[{ kind: "all" }, expand(can)]];
+	return Object.entries(can).map(([pattern, grant]) => [parsePattern(pattern), expand(grant)]);
+}
+const entriesIn = (rules) => [
+	...rules.all ? [[{ kind: "all" }, rules.all]] : [],
+	...rules.subtrees.map(([path, permissions]) => [{
+		kind: "subtree",
+		path
+	}, permissions]),
+	...[...rules.exact].map(([path, permissions]) => [{
+		kind: "exact",
+		path
+	}, permissions])
+];
+const RULES = Symbol("board.access");
+const isAccess = (value) => typeof value === "object" && RULES in value;
+function fromRules(rules) {
+	const entries = entriesIn(rules);
+	const everywhere = (permission) => (rules.all?.has(permission) ?? false) && entries.every(([, permissions]) => permissions.has(permission));
+	const readable = /* @__PURE__ */ new Map();
+	return {
+		[RULES]: rules,
+		can: (permission, channel) => resolve(rules, channel).has(permission),
+		readable(channel) {
+			let found = readable.get(channel);
+			if (found === void 0) readable.set(channel, found = resolve(rules, channel).has("read"));
+			return found;
+		},
+		readsAll: everywhere("read"),
+		everywhere,
+		anywhere: (permission) => entries.some(([, permissions]) => permissions.has(permission)),
+		narrow(scope) {
+			const other = isAccess(scope) ? scope[RULES] : canonical(entriesOf(scope));
+			const patterns = /* @__PURE__ */ new Map([["*", { kind: "all" }]]);
+			for (const [pattern] of [...entries, ...entriesIn(other)]) patterns.set(key(pattern), pattern);
+			return fromRules(canonical([...patterns.values()].map((pattern) => {
+				const theirs = at(other, pattern);
+				return [pattern, new Set([...at(rules, pattern)].filter((permission) => theirs.has(permission)))];
+			})));
+		},
+		summary() {
+			const named = entries.map(([pattern, permissions]) => [key(pattern), permissions]);
+			named.sort(([a], [b]) => a === "*" ? -1 : b === "*" ? 1 : a.localeCompare(b));
+			const out = {};
+			for (const [name, permissions] of named) out[name] = [...permissions].sort((a, b) => ORDER.get(a) - ORDER.get(b));
+			return out;
+		}
+	};
+}
+/** Access from config: `'all'`, a list for every channel, or a map from pattern to grant. Throws on a bad pattern or permission. */
+function compileAccess(can) {
+	return fromRules(canonical(entriesOf(can)));
+}
+const FULL_ACCESS = compileAccess("all");
+/**
+* `x-board-scope`: `dev/=read,post,react,label;ci/=read`. Each entry is a
+* pattern and its permissions (or `all`). It's meant for a proxy that holds the
+* credential, like Pi's sandbox: the board intersects it with the principal's
+* access, so it can only narrow, and a caller holding its own token gains
+* nothing by sending it.
+*/
+function parseScope(header) {
+	if (header.length > 4e3) throw new Error(`x-board-scope is longer than ${SCOPE_MAX} characters`);
+	const out = {};
+	const entries = header.split(";").map((entry) => entry.trim());
+	if (entries.every((entry) => entry === "")) throw new Error("x-board-scope is empty: write pattern=permissions, like dev/=read,post");
+	for (const entry of entries) {
+		if (entry === "") continue;
+		const split = entry.indexOf("=");
+		if (split < 0) throw new Error(`x-board-scope entry ${entry} needs =: write pattern=permissions, like dev/=read,post`);
+		const pattern = entry.slice(0, split).trim();
+		const list = entry.slice(split + 1).trim();
+		if (Object.hasOwn(out, pattern)) throw new Error(`x-board-scope lists ${pattern} twice`);
+		parsePattern(pattern);
+		const permissions = list === "" ? [] : list.split(",").map((permission) => permission.trim());
+		if (permissions.length === 1 && permissions[0] === "all") {
+			out[pattern] = "all";
+			continue;
+		}
+		for (const permission of permissions) if (!ORDER.has(permission)) throw new Error(`x-board-scope: unknown permission ${permission || "(empty)"}: use ${PERMISSIONS.join(", ")}, or all`);
+		out[pattern] = permissions;
+	}
+	return out;
+}
+const PHRASE = {
+	read: (channel) => `read ${channel}`,
+	post: (channel) => `post in ${channel}`,
+	react: (channel) => `react in ${channel}`,
+	label: (channel) => `label in ${channel}`,
+	sync: (channel) => `sync in ${channel}`,
+	manage: (channel) => `manage ${channel}`
+};
+/**
+* A proof that `access` allows `permission` in `channel`, or a 403 naming what's
+* missing: `this token can't label in dev`. Pass the channel the board looked
+* up, never one the request named. What the caller can't read should answer as
+* if it didn't exist: pass that error as `hidden`, and it's thrown instead
+* whenever `channel` isn't readable.
+*/
+function authorize(access, permission, channel, hidden) {
+	if (hidden && !access.readable(channel)) throw hidden();
+	if (!access.can(permission, channel)) throw forbidden(`this token can't ${PHRASE[permission](channel)}`);
+	return Object.freeze({
+		permission,
+		channel
+	});
+}
+//#endregion
+export { parseScope as i, authorize as n, compileAccess as r, FULL_ACCESS as t };

package/dist/access-CV96SYgr.d.mts

@@ -0,0 +1,32 @@
+//#region src/server/access.d.ts
+/**
+ * What a principal may do in a channel. `read` covers messages, threads,
+ * `/events`, and schedules; `post` starts threads and edits your own messages;
+ * `manage` is the board's own bookkeeping (inbox, sources).
+ */
+declare const PERMISSIONS: readonly ['read', 'post', 'react', 'label', 'sync', 'manage'];
+type Permission = (typeof PERMISSIONS)[number];
+/** `*`, a channel (`feedback`), or a channel and its subtree (`feedback/`). */
+type ChannelPattern = string;
+type Grant = 'all' | readonly Permission[];
+/** `'all'`, a list for every channel (`['post']` is `{ '*': ['post'] }`), or a map from pattern to grant. */
+type Can = Grant | Readonly<Record<ChannelPattern, Grant>>;
+/** Each pattern's whole answer, implications included. */
+type AccessSummary = Readonly<Record<ChannelPattern, readonly Permission[]>>;
+type Access = {
+  can(permission: Permission, channel: string): boolean;
+  /** The hot path for feeds: memoized per channel. */
+  readable(channel: string): boolean;
+  /** `read` in every channel, including ones that don't exist yet. */
+  readsAll: boolean;
+  /** `permission` in every channel, including ones that don't exist yet: `everywhere('manage')` is full access. */
+  everywhere(permission: Permission): boolean;
+  /** `permission` in some channel. */
+  anywhere(permission: Permission): boolean;
+  /** Only what both this and `scope` allow, channel by channel. It never widens. */
+  narrow(scope: Can | Access): Access;
+  /** Each pattern and its permissions, `*` first and the rest sorted; an empty `*` is left out. */
+  summary(): AccessSummary;
+};
+//#endregion
+export { Grant as a, ChannelPattern as i, AccessSummary as n, Permission as o, Can as r, Access as t };

package/dist/access.d.mts

@@ -0,0 +1,29 @@
+import { a as Grant, i as ChannelPattern, n as AccessSummary, o as Permission, r as Can, t as Access } from "./access-CV96SYgr.mjs";
+import { _ as oidc, a as CallerRequest, c as HostPrincipal, d as OidcTokensOptions, f as Principal, g as githubActions, h as compileRules, i as AuthenticateContext, l as IssuerConfig, m as RuleFunction, n as AccessRule, o as Claims, p as PrincipalKind, r as Authenticate, t as AccessFunction, u as Known, v as vercelProject } from "./auth-wHFcAte3.mjs";
+import { o as Author } from "./schemas-CWxs3ECJ.mjs";
+import { t as Actor } from "./reducers-B_vUGQRp.mjs";
+//#region src/server/tokens.d.ts
+/**
+ * The OIDC tokens made out to this board: a request's bearer token, from Vercel (people and
+ * deployments), GitHub Actions, an `oidc()` rule's issuer, or `local`'s (`vb serve`'s), verified
+ * for the board's URL. Null for a request with no token, and a 401 for one whose token fails.
+ * Without `request.board`, the board's project is the environment's, and it trusts no issuer past
+ * Vercel's and GitHub's.
+ */
+export declare function oidcTokens(options?: OidcTokensOptions): (request: CallerRequest & {
+  board?: AuthenticateContext;
+}) => Promise<Principal | null>;
+//#endregion
+//#region src/server/actors.d.ts
+type ResolvedActor = {
+  author: Author;
+  actor: Actor;
+};
+/**
+ * The actor a caller writes as: its principal, plus the profile it claims (`vercel:user:u_123+claude`).
+ * A person's handle and name are what they claim; anyone else's are their principal's. `audience`
+ * is the board's URL, which serves the known agents' avatars.
+ */
+export declare function resolveActor(principal: Principal, claims: Claims, audience: string): ResolvedActor;
+//#endregion
+export { type Access, type AccessFunction, type AccessRule, type AccessSummary, type Authenticate, type AuthenticateContext, type CallerRequest, type Can, type ChannelPattern, type Claims, type Grant, type HostPrincipal, type IssuerConfig, type Known, type OidcTokensOptions, type Permission, type Principal, type PrincipalKind, type RuleFunction, compileRules, githubActions, oidc, vercelProject };

package/dist/access.mjs

@@ -0,0 +1,4 @@
+import { i as resolveActor } from "./actors-rdN4dDTU.mjs";
+import { a as compileRules, c as githubActions, h as vercelProject, p as oidc } from "./auth-COzc09sn.mjs";
+import { t as oidcTokens } from "./tokens-DKLn5P9B.mjs";
+export { compileRules, githubActions, oidc, oidcTokens, resolveActor, vercelProject };

package/dist/actors-rdN4dDTU.mjs

@@ -0,0 +1,223 @@
+import { C as toStorable } from "./schemas-Be08nyfW.mjs";
+import { r as badRequest } from "./errors-DX3hpwWt.mjs";
+import { t as own } from "./own-OwgPWdmh.mjs";
+import { i as parseScope } from "./access-CJU2-vaa.mjs";
+//#region src/contract/mentions.ts
+const FENCED_CODE = /```[\s\S]*?```/g;
+const INLINE_CODE = /`[^`\n]*`/g;
+const NAME = "[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?";
+const MENTION = new RegExp(`(?<![\\w@.-])@(${NAME}(?:/${NAME})?)(?!:|[a-z0-9_/-]|\\.(?=[a-z0-9]))`, "gi");
+const EXACT = /(?<![\w@.-])@\[([^\]\s]+)\]/g;
+/** Blanks out code so mentions inside it never count. */
+const proseOnly = (text) => text.replace(FENCED_CODE, (match) => " ".repeat(match.length)).replace(INLINE_CODE, (match) => " ".repeat(match.length));
+/** Mentions in prose order, deduplicated. Handles are lowercased. */
+function extractMentions(text) {
+	const prose = proseOnly(text);
+	const found = [];
+	for (const match of prose.matchAll(EXACT)) {
+		const actor = match[1];
+		if (actor !== void 0) found.push({
+			index: match.index,
+			token: {
+				kind: "actor",
+				actor
+			},
+			key: `actor:${actor}`
+		});
+	}
+	for (const match of prose.replace(EXACT, (m) => " ".repeat(m.length)).matchAll(MENTION)) {
+		const handle = match[1]?.toLowerCase();
+		if (handle !== void 0) found.push({
+			index: match.index,
+			token: {
+				kind: "handle",
+				handle
+			},
+			key: `handle:${handle}`
+		});
+	}
+	const seen = /* @__PURE__ */ new Set();
+	return found.sort((a, b) => a.index - b.index).filter(({ key }) => !seen.has(key) && seen.add(key)).map(({ token }) => token);
+}
+/**
+* Rewrites each mention in prose with `replace`, which also gets the mention as
+* written; one it returns null for stays as written.
+* Code is left alone, as in `extractMentions`.
+*/
+function replaceMentions(text, replace) {
+	const prose = proseOnly(text);
+	const found = [];
+	for (const match of prose.matchAll(EXACT)) found.push({
+		index: match.index,
+		length: match[0].length,
+		token: {
+			kind: "actor",
+			actor: match[1]
+		}
+	});
+	for (const match of prose.replace(EXACT, (m) => " ".repeat(m.length)).matchAll(MENTION)) found.push({
+		index: match.index,
+		length: match[0].length,
+		token: {
+			kind: "handle",
+			handle: match[1].toLowerCase()
+		}
+	});
+	let out = "";
+	let at = 0;
+	for (const { index, length, token } of found.sort((a, b) => a.index - b.index)) {
+		const written = text.slice(index, index + length);
+		out += text.slice(at, index) + (replace(token, written) ?? written);
+		at = index + length;
+	}
+	return out + text.slice(at);
+}
+//#endregion
+//#region src/server/actors.ts
+/** Agents whose avatars the board serves itself. */
+const KNOWN_AGENTS = [
+	"claude",
+	"codex",
+	"grok",
+	"pi"
+];
+const PROFILE = /^[A-Za-z][A-Za-z0-9-]{0,31}$/;
+const HANDLE = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/;
+/** An actor ID starts with where it's from: `vercel:user:u_abc123+claude`, `slack:user:U0456`, `board:client`. */
+const isActorId = (id) => id.length <= 256 && /^[^\s:]+:\S+$/.test(id);
+/**
+* What a request's headers say about its caller, checked for shape: a 400 for one that's
+* malformed. None of it is verified; board() works out the actor from it once it knows who the
+* credential is.
+*/
+function claimsOf(headers) {
+	const profile = headers.get("x-board-profile")?.trim() || null;
+	if (profile !== null && !PROFILE.test(profile)) throw badRequest("profile names start with a letter and use up to 32 letters, numbers, and hyphens");
+	const avatar = headers.get("x-board-avatar")?.trim() || null;
+	if (avatar !== null && !isAvatarUrl(avatar)) throw badRequest("avatars must be https URLs (http only on localhost)");
+	const session = headers.get("x-board-session")?.trim().slice(0, 200) || null;
+	const handle = headers.get("x-board-handle")?.trim().toLowerCase() || null;
+	if (handle !== null && !HANDLE.test(handle)) throw badRequest(`invalid handle: ${handle}`);
+	const encoded = headers.get("x-board-name");
+	let name = null;
+	if (encoded) try {
+		name = decodeURIComponent(encoded).replace(/[\u0000-\u001f\u007f]/g, "").trim().slice(0, 128) || null;
+	} catch {
+		throw badRequest("x-board-name must be URI-encoded");
+	}
+	const scope = headers.get("x-board-scope");
+	if (scope !== null) try {
+		parseScope(scope);
+	} catch (error) {
+		throw badRequest(error.message, "invalid_scope");
+	}
+	return {
+		profile,
+		avatar,
+		session,
+		handle,
+		name,
+		scope
+	};
+}
+/**
+* The actor a caller writes as: its principal, plus the profile it claims (`vercel:user:u_123+claude`).
+* A person's handle and name are what they claim; anyone else's are their principal's. `audience`
+* is the board's URL, which serves the known agents' avatars.
+*/
+function resolveActor(principal, claims, audience) {
+	const baseHandle = principal.kind === "person" && claims.handle ? claims.handle : principal.handle;
+	const personName = principal.kind === "person" ? claims.name : null;
+	const profile = claims.profile?.toLowerCase() ?? null;
+	const id = profile === null ? principal.id : `${principal.id}+${profile}`;
+	const known = profile !== null && KNOWN_AGENTS.includes(profile);
+	const actor = {
+		id,
+		kind: profile === null ? principal.kind : "agent",
+		handle: profile === null ? baseHandle : `${baseHandle}/${profile}`,
+		name: claims.profile ?? personName ?? baseHandle,
+		avatar: claims.avatar ?? (known ? `${audience}/avatars/${profile}` : null)
+	};
+	return {
+		author: {
+			actor: id,
+			principal: principal.id,
+			profile,
+			session: claims.session
+		},
+		actor
+	};
+}
+function isAvatarUrl(value) {
+	try {
+		const url = new URL(value);
+		return url.protocol === "https:" || url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname);
+	} catch {
+		return false;
+	}
+}
+/**
+* An `actor.seen` event, or null when the board already knows these details. `host`: the actor is
+* a host's principal or one of its profiles, which the board records once.
+*/
+function actorSeen(seen, known, host = false) {
+	const existing = own(known.byId, seen.id);
+	const actor = seen.kind === "external" && seen.avatar === null ? {
+		...seen,
+		avatar: existing?.avatar ?? null
+	} : seen;
+	if (existing && existing.kind === actor.kind && existing.handle === actor.handle && existing.name === actor.name && existing.avatar === actor.avatar && (!host || existing.host)) return null;
+	return {
+		type: "actor.seen",
+		payload: {
+			actor: actor.id,
+			kind: actor.kind,
+			handle: toStorable(actor.handle),
+			name: toStorable(actor.name),
+			avatar: actor.avatar,
+			...host ? { host: true } : {}
+		}
+	};
+}
+/**
+* Resolves prose mentions to actor IDs. A `@handle` names the one actor the board
+* has seen with it; `@[actor-id]` names one directly. A handle nobody has stays
+* plain text and comes back in `unknown`, so the writer can be told. A handle
+* several actors share, or an `@[actor-id]` the board doesn't know, fails the
+* write. `lenient` is for platform text: no mention fails it, and one that
+* doesn't resolve stays plain text. Without `candidates`, an ambiguous mention
+* doesn't list who it could be: a caller that can't read every channel can't
+* list actors either.
+*/
+function resolveMentions(text, known, pending, lenient = false, candidates = true) {
+	const resolved = [];
+	const unknown = [];
+	const add = (id) => {
+		if (!resolved.includes(id)) resolved.push(id);
+	};
+	const fail = (error) => {
+		if (!lenient) throw error;
+	};
+	for (const token of extractMentions(text)) {
+		if (token.kind === "actor") {
+			if (isActorId(token.actor) && own(known.byId, token.actor) || pending?.id === token.actor) add(token.actor);
+			else fail(badRequest(`unknown actor @[${token.actor}]`, "unknown_mention"));
+			continue;
+		}
+		const ids = new Set(own(known.byHandle, token.handle) ?? []);
+		if (pending && pending.handle.toLowerCase() === token.handle) ids.add(pending.id);
+		if (ids.size === 1) add([...ids][0]);
+		else if (ids.size === 0) unknown.push(token.handle);
+		else if (!candidates) fail(badRequest(`ambiguous mention @${token.handle}: use @[actor-id]`, "ambiguous_mention"));
+		else {
+			const options = [...ids].map((id) => `@[${id}] (${own(known.byId, id)?.name ?? pending?.name ?? id})`).join(" or ");
+			fail(badRequest(`ambiguous mention @${token.handle}: use ${options}`, "ambiguous_mention"));
+		}
+	}
+	return {
+		mentions: resolved,
+		unknown: lenient ? [] : unknown
+	};
+}
+//#endregion
+export { resolveMentions as a, resolveActor as i, actorSeen as n, extractMentions as o, claimsOf as r, replaceMentions as s, KNOWN_AGENTS as t };