@marver-design/marver 0.10.2 → 0.11.0

package/dist/sync-DELGomPk.mjs

@@ -0,0 +1,397 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { i as readLog, r as listBoards, t as appendEvents } from "./comments-DZyobpxG.mjs";
+import { t as CLI_TOKEN_CHARS } from "./auth-B5yuwnOq.mjs";
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+//#region src/shared/events.ts
+/** Events the other side lacks, by id - the sync payload in either direction. */
+function diffEvents(mine, theirIds) {
+	const have = new Set(theirIds);
+	return mine.filter((e) => !have.has(e.id));
+}
+/** Replay a board's events into current thread state. Deterministic: replay order is
+*  (ts, id) so two stores holding the same event SET always derive the same state.
+*  TWO passes - creates first, then everything else - so a reply whose author's clock
+*  ran ahead of the creator's still lands instead of being dropped forever. */
+function replay(events) {
+	const ordered = [...events].sort((a, b) => a.ts - b.ts || (a.id < b.id ? -1 : 1));
+	const threads = /* @__PURE__ */ new Map();
+	for (const ev of ordered) {
+		if (ev.type !== "create") continue;
+		if (!ev.commentId || threads.has(ev.commentId)) continue;
+		threads.set(ev.commentId, {
+			id: ev.commentId,
+			board: ev.board,
+			nodeKey: ev.nodeKey,
+			frame: ev.frame,
+			anchor: ev.anchor,
+			author: ev.author,
+			body: ev.body,
+			ts: ev.ts,
+			resolved: false,
+			agent: ev.agent,
+			agentMeta: ev.agentMeta,
+			replies: [],
+			reactions: {}
+		});
+	}
+	for (const ev of ordered) switch (ev.type) {
+		case "reply": {
+			const t = ev.parentId ? threads.get(ev.parentId) : void 0;
+			if (!t || !ev.commentId || t.replies.some((r) => r.id === ev.commentId)) break;
+			t.replies.push({
+				id: ev.commentId,
+				author: ev.author,
+				body: ev.body,
+				ts: ev.ts,
+				agent: ev.agent,
+				agentMeta: ev.agentMeta
+			});
+			break;
+		}
+		case "edit": {
+			if (!ev.commentId || ev.body === void 0) break;
+			const t = threads.get(ev.commentId);
+			if (t) {
+				t.body = ev.body;
+				break;
+			}
+			for (const th of threads.values()) {
+				const r = th.replies.find((r) => r.id === ev.commentId);
+				if (r) {
+					r.body = ev.body;
+					break;
+				}
+			}
+			break;
+		}
+		case "resolve": {
+			const t = ev.commentId ? threads.get(ev.commentId) : void 0;
+			if (t) {
+				t.resolved = true;
+				if (ev.addressedIn) t.addressedIn = ev.addressedIn;
+			}
+			break;
+		}
+		case "reopen": {
+			const t = ev.commentId ? threads.get(ev.commentId) : void 0;
+			if (t) {
+				t.resolved = false;
+				t.addressedIn = void 0;
+			}
+			break;
+		}
+		case "reanchor": {
+			const t = ev.commentId ? threads.get(ev.commentId) : void 0;
+			if (t && ev.anchor != null) t.anchor = ev.anchor;
+			break;
+		}
+		case "react": {
+			const t = ev.commentId ? threads.get(ev.commentId) : void 0;
+			const who = ev.author?.email;
+			if (!t || !who || !ev.emoji) break;
+			const users = t.reactions[ev.emoji] ??= [];
+			const at = users.indexOf(who);
+			if (at === -1) users.push(who);
+			else {
+				users.splice(at, 1);
+				if (!users.length) delete t.reactions[ev.emoji];
+			}
+			break;
+		}
+	}
+	return [...threads.values()];
+}
+//#endregion
+//#region src/server/sync.ts
+/**
+* Dev ↔ published comment sync - one merge rule, run from the dev side.
+*
+* The published serve is the canonical home; the repo's design/comments/ is the
+* mirror the agent reads. Each exchange is: pull remote events → union into local
+* files; push the local events the remote lacks (chunked - the server unions too).
+* Idempotent and retry-safe by construction, so a dropped exchange costs nothing.
+*
+* Credentials: ~/.marver/canvases/<hash-of-project-path>.json {url, token},
+* written by `comments connect`. Deliberately OUTSIDE the repository - a dev
+* server serves the repository, and no amount of path guarding makes a secret
+* inside a published tree safe. The token is always a server SESSION - expiring,
+* and ended by rotating MARVER_CLI_TOKEN - never the operator's secret itself,
+* which is traded for one and then forgotten.
+*/
+var sync_exports = /* @__PURE__ */ __exportAll({
+	connect: () => connect,
+	connectClaim: () => connectClaim,
+	connectToken: () => connectToken,
+	loadCollab: () => loadCollab,
+	saveCollab: () => saveCollab,
+	syncOnce: () => syncOnce
+});
+/**
+* The credential does not live in the repository.
+*
+* It used to, at `design/.local/collab.json`, and `marver dev` puts the
+* repository on the web so frames can import from it. Two rounds of guards -
+* a deny list, then a realpath check - each closed a way to read it and each was
+* followed by another: a symlink, then `public/`, then Vite's derived
+* `index`/`.html` candidates. Enumerating every path a bundler might resolve is
+* not a thing anyone can finish.
+*
+* So the file moved out of reach instead. Under the user's home, keyed by the
+* absolute path of the project it belongs to, one file per canvas per machine.
+* Nothing serves that directory, so there is no path to guard.
+*
+* The old location is still read once, moved, and removed - a credential left
+* behind in a repo is exactly the thing being fixed.
+*/
+const legacyCollabFile = (root) => join(root, "design", ".local", "collab.json");
+const collabDir = () => join(homedir(), ".marver", "canvases");
+const collabFile = (root) => {
+	let canonical = root;
+	try {
+		canonical = realpathSync(root);
+	} catch {}
+	const key = createHash("sha256").update(canonical).digest("hex").slice(0, 32);
+	return join(collabDir(), `${key}.json`);
+};
+/** Move a credential written by an older marver out of the repository. Best
+*  effort in one direction only: if anything here fails the old file is left
+*  alone and `loadCollab` still reads it, so nobody is locked out by a tidy-up. */
+function migrateLegacy(root) {
+	const from = legacyCollabFile(root);
+	if (!existsSync(from)) return;
+	if (readCollab(collabFile(root))) {
+		try {
+			unlinkSync(from);
+		} catch {}
+		return;
+	}
+	const collab = readCollab(from);
+	if (!collab) return;
+	try {
+		saveCollab(root, collab);
+	} catch {}
+}
+/** A credential file, or null if it is missing, unreadable or not one. */
+function readCollab(file) {
+	try {
+		const c = JSON.parse(readFileSync(file, "utf8"));
+		return typeof c?.url === "string" && typeof c?.token === "string" ? c : null;
+	} catch {
+		return null;
+	}
+}
+function loadCollab(root) {
+	migrateLegacy(root);
+	return readCollab(collabFile(root)) ?? readCollab(legacyCollabFile(root));
+}
+function saveCollab(root, collab) {
+	const dir = collabDir();
+	const file = collabFile(root);
+	mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	try {
+		chmodSync(dir, 448);
+	} catch {}
+	/**
+	* Written through a temp file created O_EXCL at 0600, then renamed.
+	*
+	* Writing in place and fixing the mode afterwards leaves a window - and, after
+	* a crash, no window at all but a token sitting under the previous file's
+	* permissions. Creating the temp file with the mode means the credential is
+	* never on disk readable, not even briefly, and rename is atomic so a reader
+	* sees the old file or the new one.
+	*/
+	const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+	const fd = openSync(tmp, "wx", 384);
+	try {
+		writeSync(fd, JSON.stringify(collab, null, 2) + "\n");
+	} finally {
+		closeSync(fd);
+	}
+	try {
+		renameSync(tmp, file);
+	} catch (err) {
+		try {
+			unlinkSync(tmp);
+		} catch {}
+		throw err;
+	}
+	try {
+		unlinkSync(legacyCollabFile(root));
+	} catch {}
+}
+/** One full exchange. Returns per-board counts, or throws on auth/network failure. */
+async function syncOnce(root, collab) {
+	const dir = join(root, "design", "comments");
+	const auth = { authorization: `Bearer ${collab.token}` };
+	const base = collab.url.replace(/\/+$/, "");
+	const bres = await fetch(`${base}/__mv/api/boards`, { headers: auth });
+	if (bres.status === 401) throw new Error("the connect token was rejected - run `comments connect` again");
+	if (!bres.ok) throw new Error(`published canvas answered ${bres.status} - is it up?`);
+	const { rights } = await bres.json();
+	const boards = [.../* @__PURE__ */ new Set([...Object.keys(rights), ...listBoards(dir)])];
+	const out = {};
+	const failures = [];
+	for (const board of boards) {
+		if (!(board in rights)) continue;
+		const res = await fetch(`${base}/__mv/api/comments/${board}`, { headers: auth });
+		if (!res.ok) {
+			failures.push(`${board}: pull ${res.status}`);
+			continue;
+		}
+		const { events: remote } = await res.json();
+		const pulled = appendEvents(dir, board, remote).length;
+		let pushed = 0;
+		if (rights[board] === "comment") {
+			const missing = diffEvents(readLog(dir, board), remote.map((e) => e.id)).filter((e) => !e.agent);
+			for (let i = 0; i < missing.length; i += 100) {
+				const r = await fetch(`${base}/__mv/api/comments/${board}`, {
+					method: "POST",
+					headers: {
+						...auth,
+						"content-type": "application/json"
+					},
+					body: JSON.stringify({ events: missing.slice(i, i + 100) })
+				});
+				if (r.ok) pushed += (await r.json()).accepted ?? 0;
+				else failures.push(`${board}: push ${r.status} ${(await r.json().catch(() => null))?.error ?? ""}`.trim());
+			}
+		}
+		out[board] = {
+			pulled,
+			pushed
+		};
+	}
+	if (failures.length) throw new Error(`sync incomplete - ${failures.join(" · ")}`);
+	return out;
+}
+/** The account endpoints live BEHIND the canvas gate (the outer READ boundary), so
+*  connecting passes the gate first when a canvas password is set. */
+async function gateCookie(base, canvasPassword) {
+	if (!canvasPassword) return "";
+	const cookie = (await fetch(`${base}/__mv/auth`, {
+		method: "POST",
+		redirect: "manual",
+		headers: { "content-type": "application/x-www-form-urlencoded" },
+		body: `password=${encodeURIComponent(canvasPassword)}&next=`
+	})).headers.getSetCookie?.().find((c) => c.startsWith("mv_a=")) ?? "";
+	const tok = /^mv_a=([^;]+)/.exec(cookie)?.[1];
+	if (!tok) throw new Error("the canvas password was not accepted");
+	return `mv_a=${tok}`;
+}
+async function sessionFrom(res, ctx) {
+	if (!res.ok) {
+		const err = (await res.json().catch(() => null))?.error;
+		throw new Error(err ?? `${ctx} failed (${res.status})`);
+	}
+	const cookie = res.headers.getSetCookie?.().find((c) => c.startsWith("mv_s=")) ?? "";
+	const token = /^mv_s=([\w-]+)/.exec(cookie)?.[1];
+	if (!token) throw new Error("the canvas did not issue a session - is collaboration enabled on it (MARVER_DATA_DIR)?");
+	return token;
+}
+/** Sign in against a published canvas and persist the device credential. The account's
+*  identity rides along: locally-born events carry it as their author snapshot (the
+*  server validates the claim against the session - it never rewrites events). */
+async function connect(root, url, email, password, canvasPassword) {
+	const base = url.replace(/\/+$/, "");
+	const gate = await gateCookie(base, canvasPassword);
+	const res = await fetch(`${base}/__mv/api/auth/signin`, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			...gate ? { cookie: gate } : {}
+		},
+		body: JSON.stringify({
+			email,
+			password
+		})
+	});
+	if ((res.headers.get("content-type") ?? "").includes("text/html")) throw new Error(`this canvas signs people in with Marver ID, so there is no password to use here.
+  Set MARVER_CLI_TOKEN=\$(openssl rand -hex 24) on the canvas, then run:
+    npx marver comments connect ${base} --token <that same value>`);
+	const token = await sessionFrom(res, "sign-in");
+	const user = (await res.clone().json().catch(() => null))?.user;
+	saveCollab(root, {
+		url: base,
+		token,
+		email: user?.email ?? email,
+		name: user?.name,
+		avatar: user?.avatar
+	});
+}
+/** Claim an invite from the CLI (the dev-first path - no published UI needed). */
+async function connectClaim(root, url, invite, profile, canvasPassword) {
+	const base = url.replace(/\/+$/, "");
+	const gate = await gateCookie(base, canvasPassword);
+	const res = await fetch(`${base}/__mv/api/auth/claim`, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			...gate ? { cookie: gate } : {}
+		},
+		body: JSON.stringify({
+			token: invite,
+			...profile
+		})
+	});
+	const token = await sessionFrom(res, "claim");
+	const user = (await res.clone().json().catch(() => null))?.user;
+	saveCollab(root, {
+		url: base,
+		token,
+		email: user?.email,
+		name: user?.name ?? profile.name,
+		avatar: user?.avatar
+	});
+}
+/**
+* Connect with the canvas's `MARVER_CLI_TOKEN` - the operator's own credential.
+*
+* The path that works whatever the canvas gates on, and the only one that works
+* when it gates on Marver ID: an identity account has no password for `connect`
+* to present, and the session its sign-in produced lives in an HttpOnly cookie
+* the terminal cannot read. The token is set in the deployment environment
+* rather than handed out by a page, because a page that mints CLI credentials is
+* a page an authored frame can drive - see the note on `operatorUser`.
+*
+* Checked before it is written, so a mistyped token fails here, once, in front
+* of somebody - rather than being persisted and failing on every sync from now
+* on. No canvas password is needed: the token IS gate passage.
+*/
+async function connectToken(root, url, token) {
+	const base = url.replace(/\/+$/, "");
+	if (!token.trim()) throw new Error("that token is empty - is MARVER_CLI_TOKEN set in your shell?");
+	if (token.length < 32) throw new Error(`that token is ${token.length} characters and the canvas will not honour anything under 32.\n  Generate one: MARVER_CLI_TOKEN=\$(openssl rand -hex 24), set it on the canvas, and use the same value here.`);
+	if (!CLI_TOKEN_CHARS.test(token)) throw new Error("that token has characters an Authorization header cannot carry (letters, digits, _ and - only).\n  If it came from `openssl rand -base64`, regenerate it with `openssl rand -hex 24`\n  and set the same value as MARVER_CLI_TOKEN on the canvas.");
+	const res = await fetch(`${base}/__mv/api/cli-session`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json"
+		},
+		body: "{}"
+	});
+	const html = (res.headers.get("content-type") ?? "").includes("text/html");
+	if (res.status === 404) throw new Error(`${base} has no CLI sign-in - it is running a marver older than 0.11.0`);
+	if (res.status === 401 || html) throw new Error(`the canvas would not accept that token.
+  - is it the same value as MARVER_CLI_TOKEN on ${base}?\n  - has the owner signed in yet? the token acts as the owner, so it does nothing until one exists
+  - is MARVER_DATA_DIR set on the canvas? without it there are no accounts at all
+  - is the canvas running marver 0.11.0 or newer? older ones have no CLI sign-in at all`);
+	if (!res.ok) throw new Error(`the canvas answered ${res.status} - is it up?`);
+	const body = await res.json().catch(() => null);
+	if (!body?.token || !body?.user?.email) throw new Error("the canvas accepted the token but issued nothing - is it running a current marver?");
+	saveCollab(root, {
+		url: base,
+		token: body.token,
+		email: body.user.email,
+		name: body.user.name,
+		avatar: body.user.avatar
+	});
+}
+//#endregion
+export { syncOnce as a, loadCollab as i, connectClaim as n, sync_exports as o, connectToken as r, replay as s, connect as t };

package/dist/update-DuWDj5nR.mjs

@@ -0,0 +1,77 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { r as PKG } from "./cli.mjs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/server/update.ts
+/**
+* Update discovery - dev only, and deliberately boring about privacy: one anonymous
+* registry metadata GET per day (the same request `npm view` makes), cached in
+* design/.local/, nothing sent beyond the request itself. Offline, slow, or
+* firewalled registries degrade to silence. MARVER_NO_UPDATE_CHECK=1 disables it.
+* Published bundles never check anything - viewers are not the owner.
+*/
+var update_exports = /* @__PURE__ */ __exportAll({
+	checkUpdate: () => checkUpdate,
+	installedVersion: () => installedVersion
+});
+const TTL = 864e5;
+/** Installed version: walk up from this module to the package's own package.json
+*  (one level from dist/, two from src/server/ - the walk covers both). */
+function installedVersion() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 4; i++) {
+		try {
+			const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+			if (pkg.name === "@marver-design/marver") return pkg.version;
+		} catch {}
+		dir = dirname(dir);
+	}
+	return null;
+}
+/** Strictly-newer numeric compare; anything non-numeric (prerelease tags) compares false. */
+const newer = (a, b) => {
+	const pa = a.split(".").map((n) => parseInt(n, 10));
+	const pb = b.split(".").map((n) => parseInt(n, 10));
+	for (let i = 0; i < 3; i++) {
+		const x = pa[i] ?? 0, y = pb[i] ?? 0;
+		if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
+		if (x !== y) return x > y;
+	}
+	return false;
+};
+/** The latest published version when strictly newer than installed, else null. Never throws. */
+async function checkUpdate(root) {
+	if (process.env.MARVER_NO_UPDATE_CHECK) return null;
+	const current = installedVersion();
+	if (!current) return null;
+	const latest = await latestVersion(root);
+	return latest && newer(latest, current) ? latest : null;
+}
+async function latestVersion(root) {
+	const cacheFile = join(root, "design", ".local", "update-check.json");
+	const wellFormed = (v) => typeof v === "string" && /^\d+\.\d+\.\d+$/.test(v);
+	try {
+		const c = JSON.parse(readFileSync(cacheFile, "utf8"));
+		const age = Date.now() - c.checkedAt;
+		if (typeof c.checkedAt === "number" && age >= 0 && age < TTL) return wellFormed(c.latest) ? c.latest : null;
+	} catch {}
+	let latest = null;
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(PKG)}/latest`, { signal: AbortSignal.timeout(3e3) });
+		if (res.ok) {
+			const v = (await res.json())?.version;
+			if (wellFormed(v)) latest = v;
+		}
+	} catch {}
+	try {
+		mkdirSync(join(root, "design", ".local"), { recursive: true });
+		writeFileSync(cacheFile, JSON.stringify({
+			checkedAt: Date.now(),
+			latest
+		}) + "\n");
+	} catch {}
+	return latest;
+}
+//#endregion
+export { installedVersion as n, update_exports as r, checkUpdate as t };

package/dist/utm-CxC3QN5X.mjs

@@ -0,0 +1,20 @@
+//#region src/shared/utm.ts
+/** Automatic attribution for the powered-by links: every canvas tags its marver.design
+*  link so site analytics can see WHICH canvas sent a visitor - zero user setup.
+*  Conventional UTM semantics (stable groupings first, the variable last):
+*    utm_source   = the surface class ('published-canvas' | 'dev-canvas')
+*    utm_medium   = the link unit ('powered-by')
+*    utm_campaign = THIS canvas's name, slugged ("Marver tour" -> "marver-tour")
+*    utm_content  = the placement ('gate' badge | 'shell' wordmark | 'sign-in' finish page)
+*/
+function poweredByUrl(canvasName, source, content) {
+	const slug = (canvasName ?? "").toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	return `https://marver.design/?${new URLSearchParams({
+		utm_source: source,
+		utm_medium: "powered-by",
+		...slug ? { utm_campaign: slug } : {},
+		utm_content: content
+	}).toString()}`;
+}
+//#endregion
+export { poweredByUrl as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
   "type": "module",
   "private": false,

package/src/shared/utm.ts

@@ -4,12 +4,12 @@
  *    utm_source   = the surface class ('published-canvas' | 'dev-canvas')
  *    utm_medium   = the link unit ('powered-by')
  *    utm_campaign = THIS canvas's name, slugged ("Marver tour" -> "marver-tour")
- *    utm_content  = the placement ('gate' badge | 'shell' wordmark)
+ *    utm_content  = the placement ('gate' badge | 'shell' wordmark | 'sign-in' finish page)
  */
 export function poweredByUrl(
   canvasName: string | undefined,
   source: 'published-canvas' | 'dev-canvas',
-  content: 'gate' | 'shell',
+  content: 'gate' | 'shell' | 'sign-in',
 ): string {
   const slug = (canvasName ?? '').toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
   const q = new URLSearchParams({

package/templates/instructions/configure.md

@@ -72,6 +72,10 @@ If collaboration is deployed, each engineer runs `marver comments connect
 cloud sync on top of git. Git carries the committed comments; `connect` adds
 the real-time stream from published viewers.
 
+On a canvas gated by Marver Sign In there are no per-engineer CLI accounts:
+identity accounts have no password to connect with. The repo connects once with
+the canvas's `MARVER_CLI_TOKEN`, acting as the owner - see instructions/publish.md.
+
 ## Dev identity (who comments render as)
 
 `marver dev` resolves the local author from `design/.local/` - never invent or

package/templates/instructions/publish.md

@@ -18,11 +18,32 @@ vars if the host has no CLI.
    `--boards a,b` overrides ad hoc (grants comment), `--all-boards` ships
    everything loudly.
 
-2. **The canvas password** - `MARVER_PASSWORD` at serve time. This is the READ
-   boundary: one shared password for GUESTS. Members never need it - their own
-   account signs them in at the gate, and invite links skip it entirely (the
-   token is the authorization). Rotating it therefore only affects guests.
-   No env var = an open canvas.
+2. **Who gets in** - pick ONE of two gates at serve time. They are alternatives,
+   not layers; setting both weakens the invite list to "an account OR whoever
+   has the password". No env var at all = an open canvas.
+
+   **Marver Sign In - `MARVER_ID_ISSUER`. Use this by default.** People sign in
+   as themselves (Google, or an emailed code) instead of sharing a secret. One
+   sign-in opens every canvas gated this way, there is no password to leak or
+   rotate, and removing one person removes exactly them. Needs
+   `MARVER_PUBLIC_ORIGIN` set to the canvas's exact public origin, and
+   `MARVER_DATA_DIR`.
+
+   ```
+   MARVER_ID_ISSUER=https://id.marver.design
+   MARVER_PUBLIC_ORIGIN=https://<the deployed url>
+   ```
+
+   **The canvas password - `MARVER_PASSWORD`.** The sovereign option, and the
+   right one when the canvas must depend on nothing outside itself: no outbound
+   request of any kind. One shared password for GUESTS; members never need it,
+   since their own account signs them in and invite links skip it entirely.
+   Choose it deliberately - offline or air-gapped hosting, or an explicit
+   preference for no third party in the sign-in path - not by default.
+
+   **Who may enter is decided by the canvas either way**, from the invite list
+   the owner keeps. Marver Sign In proves who somebody is; it has no say in
+   where they may go, and is never told the answer.
 
 3. **Collaboration on or off** - `MARVER_DATA_DIR` at serve time. Set it to a
    path on a PERSISTENT disk and the serve grows accounts + live comments.
@@ -35,9 +56,12 @@ vars if the host has no CLI.
 | Var | Meaning |
 |---|---|
 | `PORT` | listen port (hosts inject this) |
-| `MARVER_PASSWORD` | canvas password (guests' read credential); unset = open |
+| `MARVER_ID_ISSUER` | `https://id.marver.design` - people sign in as themselves (**preferred**) |
+| `MARVER_PUBLIC_ORIGIN` | REQUIRED with `MARVER_ID_ISSUER`: this canvas's exact public origin |
+| `MARVER_PASSWORD` | the sovereign alternative: one shared password; unset = open |
 | `MARVER_DATA_DIR` | persistent dir for `comments/` + `auth.json`; unset = no collaboration |
-| `MARVER_OWNER_EMAIL` | prints a single-use OWNER claim link in the deploy logs on first boot |
+| `MARVER_OWNER_EMAIL` | who owns an empty canvas. With Marver Sign In they just sign in; with a password, a single-use claim link prints in the deploy logs on first boot |
+| `MARVER_CLI_TOKEN` | generated 32+ char secret (`openssl rand -hex 24`) that lets this repo run `comments invite`/`revoke`/`sync` as the owner. Required with `MARVER_ID_ISSUER` - identity accounts have no password for the CLI to use |
 | `MARVER_TRUSTED_PROXY` | set to `1` behind a reverse proxy (Railway, Fly) so rate limits see real IPs |
 
 ## The host contract (works on any volume-capable host)
@@ -71,10 +95,17 @@ Then, once per service:
 ```bash
 railway init                      # or `railway link` an existing service
 railway volume add --mount-path /data
-railway variables --set MARVER_PASSWORD=<pw> --set MARVER_DATA_DIR=/data \
-  --set MARVER_OWNER_EMAIL=<owner@email> --set MARVER_TRUSTED_PROXY=1
+# The default gate: people sign in as themselves.
+railway variables --set MARVER_ID_ISSUER=https://id.marver.design \
+  --set MARVER_PUBLIC_ORIGIN=https://<the deployed url> --set MARVER_DATA_DIR=/data \
+  --set MARVER_OWNER_EMAIL=<owner@email> --set MARVER_TRUSTED_PROXY=1 \
+  --set MARVER_CLI_TOKEN="$(openssl rand -hex 24)"
+# ...or the sovereign alternative, if this canvas must depend on nothing external:
+#   --set MARVER_PASSWORD=<pw>   (instead of MARVER_ID_ISSUER/MARVER_PUBLIC_ORIGIN)
 railway up                        # uploads the repo; Railway runs build then start
-railway logs                      # ← the owner claim LINK prints here, once (see below)
+railway logs                      # with a PASSWORD gate, the owner claim link prints
+                                  # here once. With Marver Sign In there is no link -
+                                  # the owner simply signs in. See below.
 ```
 
 Republishing is just `railway up` again: the server unions the seeded logs on
@@ -83,7 +114,12 @@ the event log is single-writer by design.
 
 ## What the deployed gate offers (so you know what you're wiring)
 
-On a collaboration canvas the gate has three doors, one credential each:
+**With `MARVER_ID_ISSUER`** there is one door: people sign in at
+id.marver.design with Google or an emailed code, come back, and are let in if
+the owner's list has their address. Nobody types a canvas password because there
+isn't one. An address that is not on the list is refused by name, on screen.
+
+**With `MARVER_PASSWORD`** the gate has three doors, one credential each:
 - **Guest** - the canvas password → read-only across published boards.
 - **Member** - "Sign in instead" → their own email + password → read + comment.
   A member session IS gate passage; they never touch the shared password again.
@@ -92,9 +128,41 @@ On a collaboration canvas the gate has three doors, one credential each:
 
 ## Wiring people up (after first deploy)
 
-`MARVER_OWNER_EMAIL` makes the first boot print an owner bootstrap in the logs:
-a browser link (`<url>/#/i/<token>`) AND the exact repo command. The token is
-single-use. Claim it from the repo so this machine can mint invites:
+**With Marver Sign In**, the owner just signs in - `MARVER_OWNER_EMAIL` claims an
+empty canvas for that address, with no token to pass around.
+
+**To manage people from this machine, the canvas needs `MARVER_CLI_TOKEN`.**
+`comments invite`, `revoke` and `sync` sign the CLI in with a password, and
+identity mode has none. Generate a secret - do not choose one, nothing
+rate-limits this and nothing slows a guess down - set it on the canvas, and hand
+the same value back:
+
+```bash
+# on the canvas (deployment environment):  MARVER_CLI_TOKEN=$(openssl rand -hex 24)
+MARVER_CLI_TOKEN='<that same value>' marver comments connect https://canvas.example.com
+```
+
+Hex, not base64: an `Authorization` header carries letters, digits, `_` and `-`,
+and the canvas refuses to start on a value it could never accept. `--token` works
+too, but a value on the command line is visible to anything that can list
+processes, so prefer the variable.
+
+It acts as whoever owns the canvas, so let the owner sign in once first - until
+somebody owns it there is nobody for the token to be. `connect` trades it for an
+ordinary session and stores THAT, so the secret never lands in your repo.
+Rotating `MARVER_CLI_TOKEN` ends every session it minted.
+
+It is a deployment variable and not something a page hands out, because authored
+frames run same-origin in a canvas: frame code can read `mv_c` and ride the
+viewer's session, so anything a browser can mint, a frame can mint silently. A
+browser-approved device flow was built for this job and removed before release for
+that reason. Do not reintroduce one, and do not invent a workaround that posts to
+internal endpoints.
+
+**With a canvas password**, `MARVER_OWNER_EMAIL` makes the first boot print an
+owner bootstrap in the logs: a browser link (`<url>/#/i/<token>`) AND the exact
+repo command. The token is single-use. Claim it from the repo so this machine can
+mint invites:
 
 ```bash
 # 1. claim the owner account - copy the command the deploy logs printed:
@@ -125,5 +193,6 @@ through sign-in.
 - `<MARVER_DATA_DIR>/auth.json` - accounts (scrypt), sessions, invites, on the volume.
 - `design/comments/<board>.jsonl` - the dev-side mirror, git-tracked: feedback
   has history, and the volume has an off-site replica for free.
-- `design/.local/collab.json` - THIS machine's device credential. Gitignored;
+- `~/.marver/canvases/<project-hash>.json` - THIS machine's device credential, kept
+  OUTSIDE the repo because `marver dev` serves the repo;
   never commit it.